Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

fix(graph): stop reporting a Go package as a circular dependency (#1354)

Raghav Chamadiyabede2cb32919
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py b/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py
index 3042061d3..42a027333 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py
@@ -475,9 +475,18 @@ async def _persist_full_update_async(
# who re-index, and everyone else keeps being served a page the
# product no longer has.
try:
- from repowise.core.pipeline.persist import sweep_retired_pages
+ from repowise.core.pipeline.persist import (
+ sweep_absent_cycle_pages,
+ sweep_retired_pages,
+ )
swept_page_ids = await sweep_retired_pages(session, repo_id)
+ # Cycle pages are never regenerated on this path (the ladder
+ # stops at file pages), so a cycle that no longer exists can
+ # only be retired by asking the rebuilt graph directly.
+ swept_page_ids += await sweep_absent_cycle_pages(
+ session, repo_id, graph_builder
+ )
# Drop the embeddings before the SQL session commits, the same
# ordering ``init`` uses: the vector store is a separate engine,
diff --git a/packages/core/alembic/versions/0046_graph_edge_hint_source.py b/packages/core/alembic/versions/0046_graph_edge_hint_source.py
new file mode 100644
index 000000000..25e1704bf
--- /dev/null
+++ b/packages/core/alembic/versions/0046_graph_edge_hint_source.py
@@ -0,0 +1,51 @@
+"""Persist ``graph_edges.hint_source`` so cohesion survives rehydration.
+
+Several resolver passes synthesise file-level edges to record that two files
+belong to one compilation unit — Go package siblings, JVM same-package classes,
+C# ``partial`` fragments and global usings, Swift same-module files, and the
+C/C++ header/implementation pair. Each pass stamps ``hint_source`` on the edge.
+
+Cycle detection reads that stamp to drop those edges: files in one compilation
+unit cannot depend on each other, so counting them turns every cohesive package
+into a fabricated import cycle (issue #1294).
+
+The stamp only lived in the in-memory NetworkX graph. Anything running against a
+graph rehydrated from ``graph_edges`` — the health engine's break-cycle detector,
+incremental updates — saw cohesion edges as ordinary imports and re-reported the
+false cycles. Persisting the column closes that gap.
+
+Nullable with no default: NULL means "a real import/using directive", which is
+the correct reading for every pre-existing row.
+
+``init_db``'s additive schema reconciler picks the column up from the model for
+local SQLite stores that never run Alembic; this migration covers the managed
+Postgres ones. The two converge on the same shape.
+
+Revision ID: 0046
+Revises: 0045
+Create Date: 2026-08-08
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers
+revision: str = "0046"
+down_revision: str | None = "0045"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+ op.add_column(
+ "graph_edges",
+ sa.Column("hint_source", sa.String(length=64), nullable=True),
+ )
+
+
+def downgrade() -> None:
+ op.drop_column("graph_edges", "hint_source")
diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/graph_signals.py b/packages/core/src/repowise/core/analysis/health/refactoring/graph_signals.py
index 21fbb77a5..cf2a32f37 100644
--- a/packages/core/src/repowise/core/analysis/health/refactoring/graph_signals.py
+++ b/packages/core/src/repowise/core/analysis/health/refactoring/graph_signals.py
@@ -15,6 +15,8 @@ from __future__ import annotations
from typing import Any
+from ....ingestion.cohesion import is_cohesion_edge
+
# File->file edge types that constitute a structural dependency cycle.
# ``imports`` is the actionable, invertible edge; the others are carried so a
# cycle that closes through a framework/type edge is still reported. Today the
@@ -23,9 +25,21 @@ from typing import Any
# drops only git ``co_changes``) and the persisted ``graph_node_membership``
# rows; the two could drift only if a new file-level edge type is added to one
# definition but not the other.
+#
+# Edge *type* is not sufficient on its own: the resolver passes synthesise
+# ``imports`` and ``type_use`` edges to express that two files are one
+# compilation unit (Go package siblings, C# partial fragments, a C++
+# header/impl pair). Those are not dependencies and must not close a cycle, so
+# both definitions additionally reject ``is_cohesion_edge``. See
+# repowise.core.ingestion.cohesion.
_CYCLE_EDGE_TYPES = ("imports", "framework", "dynamic", "type_use", "extends", "implements")
+def _is_cycle_edge(data: Any) -> bool:
+ """True if *data* is a file-level edge that can legitimately close a cycle."""
+ return data.get("edge_type") in _CYCLE_EDGE_TYPES and not is_cohesion_edge(data)
+
+
def build_file_scc_index(graph: Any) -> dict[str, tuple[str, ...]]:
"""Map each file in a non-trivial dependency cycle to its sorted members.
@@ -48,7 +62,7 @@ def build_file_scc_index(graph: Any) -> dict[str, tuple[str, ...]]:
for u, v, data in graph.edges(data=True):
if u == v:
continue
- if data.get("edge_type") in _CYCLE_EDGE_TYPES and u in fg and v in fg:
+ if _is_cycle_edge(data) and u in fg and v in fg:
fg.add_edge(u, v)
out: dict[str, tuple[str, ...]] = {}
@@ -80,7 +94,7 @@ def cycle_edges(graph: Any, members: tuple[str, ...]) -> list[tuple[str, str]]:
for _u, v, data in graph.out_edges(u, data=True):
if u == v or v not in member_set:
continue
- if data.get("edge_type") in _CYCLE_EDGE_TYPES:
+ if _is_cycle_edge(data):
edges.append((u, v))
return sorted(set(edges))
diff --git a/packages/core/src/repowise/core/ingestion/cohesion.py b/packages/core/src/repowise/core/ingestion/cohesion.py
new file mode 100644
index 000000000..bbaa75850
--- /dev/null
+++ b/packages/core/src/repowise/core/ingestion/cohesion.py
@@ -0,0 +1,76 @@
+"""Cohesion edges — file links that assert co-membership, not dependency.
+
+Several languages let a file reference a sibling's declarations with no import
+statement at all: Go package siblings, JVM same-package classes, C#
+same-namespace types and ``partial`` fragments, Swift same-module files, and the
+C/C++ header/implementation pair. Resolver passes synthesise file-level edges for
+those relationships so reachability, dead-code, and orphan detection see cohesive
+code as connected rather than as a field of isolated nodes.
+
+Those edges are right for reachability and wrong for cycle detection. A Go
+package is one compilation unit: its files cannot depend on each other, because
+there is no edge to cut and no build order to break. Feed the synthesised edges
+to a strongly-connected-component pass and every cohesive package becomes a
+fabricated import cycle — and the C++ header pair, emitted in both directions by
+construction, fabricates a two-file cycle for every ``foo.h`` / ``foo.c`` in the
+repo.
+
+So the split is: keep cohesion edges in the graph, where reachability needs them,
+and drop them at the cycle boundary only. Every synthesising pass already stamps
+``hint_source``; this module turns that stamp into the single predicate both
+cycle definitions share. A new language pass joins by adding its hint to
+:data:`COHESION_HINTS` — there is no per-language cycle logic to write.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+#: Hint stamped on an edge between two files of one package / build target.
+SAME_PACKAGE_HINT = "same_package"
+
+#: Languages whose import statement names a *compilation unit* that is exactly a
+#: directory, so a fan-out landing in the importer's own directory landed on its
+#: siblings — and a unit cannot depend on itself.
+#:
+#: Membership is narrow on purpose, because the test the builder applies is a
+#: directory comparison and that is only sound where package identity *is* the
+#: directory:
+#: * ``go`` — the package is the directory, by language rule; the resolver's
+#: own package index is keyed by directory.
+#: * ``java`` — javac requires a source file's package to match its directory.
+#:
+#: Deliberately excluded, each of which would make the directory test lie:
+#: * ``c`` / ``cpp`` — the fan-out unit is a CMake/Bazel target, not a
+#: directory. In a flat ``src/`` layout ``foo.c -> bar.h`` is a genuine,
+#: cuttable dependency between unrelated translation units. The real C/C++
+#: cohesion case (a header and its implementation) is already stamped
+#: ``header_source_pair`` by its own pass.
+#: * ``kotlin`` / ``scala`` — ``package`` need not match the directory, so two
+#: same-directory files can sit in different packages and an import between
+#: them is a real dependency.
+#: * ``python`` — its ``_all`` fan-out crosses real module boundaries
+#: (``from pkg import submodule``), so a sibling import is a genuine
+#: dependency and a genuine cycle if it closes one.
+UNIT_FANOUT_LANGUAGES: frozenset[str] = frozenset({"go", "java"})
+
+#: ``hint_source`` values marking an edge as intra-compilation-unit cohesion.
+#:
+#: Deliberately excluded: ``spec_mirror`` (an rspec file genuinely depends on its
+#: subject) and ``compile_order`` (F# compilation order is a real dependency, and
+#: acyclic by construction). Both are directional dependencies, not co-membership.
+COHESION_HINTS: frozenset[str] = frozenset(
+ {
+ SAME_PACKAGE_HINT, # JVM siblings; Go/JVM/C++ unit fan-out onto siblings
+ "same_namespace", # C# same-namespace types
+ "global_using", # C# project-wide global usings
+ "same_module", # Swift SPM target siblings
+ "partial_class", # C# fragments of one partial type
+ "header_source_pair", # C/C++ foo.h <-> foo.c
+ }
+)
+
+
+def is_cohesion_edge(data: Any) -> bool:
+ """True if *data* — a graph edge's attribute dict — is a cohesion edge."""
+ return data.get("hint_source") in COHESION_HINTS
diff --git a/packages/core/src/repowise/core/ingestion/graph/_metrics.py b/packages/core/src/repowise/core/ingestion/graph/_metrics.py
index d64be7441..beb8e0b4d 100644
--- a/packages/core/src/repowise/core/ingestion/graph/_metrics.py
+++ b/packages/core/src/repowise/core/ingestion/graph/_metrics.py
@@ -19,6 +19,8 @@ from typing import Any
import networkx as nx
import structlog
+from ..cohesion import is_cohesion_edge
+
log = structlog.get_logger(__name__)
_LARGE_REPO_THRESHOLD = 30_000 # nodes — above this, algorithms are expensive
@@ -106,6 +108,39 @@ class MetricsMixin:
self._file_subgraph_cache = sub
return sub
+ def cycle_subgraph(self) -> nx.DiGraph:
+ """Return :meth:`file_subgraph` minus cohesion edges, for cycle detection.
+
+ A cohesion edge records that two files are one compilation unit — Go
+ package siblings, JVM same-package classes, C# partial fragments, a C++
+ header/implementation pair — not that one depends on the other. See
+ :mod:`repowise.core.ingestion.cohesion`. Left in, they turn every
+ cohesive package into a fabricated import cycle.
+
+ Kept separate from :meth:`file_subgraph` deliberately: PageRank,
+ betweenness and the degree kernels must keep seeing cohesion edges,
+ because dead-code and orphan detection are the whole reason the resolver
+ passes synthesise them.
+
+ Built lazily — only cycle callers pay for it — and cached like the other
+ subgraphs. A ``restricted_view`` rather than a filtered copy: on a 30k-node
+ repo a second full copy of the file graph is real memory for a graph we
+ only ever read. Callers must treat the result as read-only.
+ """
+ cached = self._cycle_subgraph_cache
+ if cached is not None:
+ return cached
+ # Resolve the base graph BEFORE taking the lock: file_subgraph() takes
+ # the same lock, and threading.Lock is not reentrant.
+ base = self.file_subgraph()
+ with self._subgraph_lock:
+ if self._cycle_subgraph_cache is not None:
+ return self._cycle_subgraph_cache
+ cohesion = [(u, v) for u, v, d in base.edges(data=True) if is_cohesion_edge(d)]
+ sub = nx.restricted_view(base, [], cohesion)
+ self._cycle_subgraph_cache = sub
+ return sub
+
def symbol_subgraph(self) -> nx.DiGraph:
"""Return a subgraph of symbol nodes connected by call + heritage edges.
@@ -141,6 +176,9 @@ class MetricsMixin:
def strongly_connected_components(self) -> list[frozenset[str]]:
"""Return SCCs as a list of frozensets, in a run-stable order.
+ Computed over :meth:`cycle_subgraph`, so files that are merely siblings
+ in one compilation unit do not read as a cycle.
+
NetworkX yields components in graph-iteration order, and the graph's
node insertion order varies between runs (git-indexer threads finish
in whatever order they finish). Callers that index into this list, such
@@ -150,7 +188,7 @@ class MetricsMixin:
something that depends only on the component contents.
"""
return sorted(
- (frozenset(scc) for scc in nx.strongly_connected_components(self.file_subgraph())),
+ (frozenset(scc) for scc in nx.strongly_connected_components(self.cycle_subgraph())),
key=lambda scc: (-len(scc), min(scc)),
)
diff --git a/packages/core/src/repowise/core/ingestion/graph/_rehydrate.py b/packages/core/src/repowise/core/ingestion/graph/_rehydrate.py
index 645e30150..86b3890c6 100644
--- a/packages/core/src/repowise/core/ingestion/graph/_rehydrate.py
+++ b/packages/core/src/repowise/core/ingestion/graph/_rehydrate.py
@@ -104,6 +104,12 @@ class RehydrateMixin:
imported_names = edge.get("imported_names")
if imported_names:
edge_attrs["imported_names"] = list(imported_names)
+ # Cohesion provenance — cycle detection drops these edges, so a
+ # rehydrated graph must carry the mark or it re-reports every
+ # cohesive package as an import cycle.
+ hint_source = edge.get("hint_source")
+ if hint_source:
+ edge_attrs["hint_source"] = hint_source
graph.add_edge(source, target, **edge_attrs)
edge_count += 1
diff --git a/packages/core/src/repowise/core/ingestion/graph/builder.py b/packages/core/src/repowise/core/ingestion/graph/builder.py
index 9fca64f2f..817a0b678 100644
--- a/packages/core/src/repowise/core/ingestion/graph/builder.py
+++ b/packages/core/src/repowise/core/ingestion/graph/builder.py
@@ -8,12 +8,13 @@ file under the project's 400-line ceiling.
from __future__ import annotations
-from pathlib import Path
+from pathlib import Path, PurePosixPath
from typing import Any
import networkx as nx
import structlog
+from ..cohesion import SAME_PACKAGE_HINT, UNIT_FANOUT_LANGUAGES
from ..models import ParsedFile
from ..resolvers import ResolverContext, resolve_import
from ..resolvers.go import read_go_module_path, read_go_modules
@@ -101,6 +102,7 @@ class GraphBuilder(MetricsMixin, ResolveMixin, EdgesMixin, SerializeMixin, Rehyd
self._subgraph_lock = threading.Lock()
self._file_subgraph_cache: nx.DiGraph | None = None
self._symbol_subgraph_cache: nx.DiGraph | None = None
+ self._cycle_subgraph_cache: nx.DiGraph | None = None
# Shared import-name maps (built once per build(), injected into the
# call + heritage resolvers; reset whenever files change).
self._import_name_maps: Any | None = None
@@ -122,6 +124,10 @@ class GraphBuilder(MetricsMixin, ResolveMixin, EdgesMixin, SerializeMixin, Rehyd
self.__dict__.update(state)
self._subgraph_lock = threading.Lock()
+ # A bundle pickled by an older build predates this cache attribute, and
+ # this is an explicit cross-version process boundary — default it rather
+ # than let the first cycle_subgraph() call raise AttributeError.
+ self.__dict__.setdefault("_cycle_subgraph_cache", None)
def set_tsconfig_resolver(self, resolver: Any) -> None:
"""Attach a :class:`TsconfigResolver` for TS/JS path-alias resolution."""
@@ -142,6 +148,7 @@ class GraphBuilder(MetricsMixin, ResolveMixin, EdgesMixin, SerializeMixin, Rehyd
self._execution_flow_cache = None
self._file_subgraph_cache = None
self._symbol_subgraph_cache = None
+ self._cycle_subgraph_cache = None
self._import_name_maps = None
def _invalidate_subgraph_caches(self) -> None:
@@ -154,6 +161,7 @@ class GraphBuilder(MetricsMixin, ResolveMixin, EdgesMixin, SerializeMixin, Rehyd
"""
self._file_subgraph_cache = None
self._symbol_subgraph_cache = None
+ self._cycle_subgraph_cache = None
def release_graph(self) -> None:
"""Drop the in-memory NetworkX object after metrics are materialized.
@@ -326,6 +334,11 @@ class GraphBuilder(MetricsMixin, ResolveMixin, EdgesMixin, SerializeMixin, Rehyd
_lang = parsed.file_info.language
_t0 = _t.monotonic()
file_imports: set[str] = set()
+ # A unit fan-out that resolves to the importer's own package lands on
+ # its siblings; those edges are cohesion, not dependency. See
+ # repowise.core.ingestion.cohesion.
+ _unit_fanout = _lang in UNIT_FANOUT_LANGUAGES
+ _own_dir = PurePosixPath(path).parent.as_posix() if _unit_fanout else ""
for imp in parsed.imports:
# Go and JVM imports name a package *directory*; fan the edge
# out to every file in the resolved package so sibling files
@@ -375,12 +388,24 @@ class GraphBuilder(MetricsMixin, ResolveMixin, EdgesMixin, SerializeMixin, Rehyd
merged = list(set(existing + imp.imported_names))
self._graph[path][target]["imported_names"] = merged
else:
- self._graph.add_edge(
- path,
- target,
- edge_type="imports",
- imported_names=list(imp.imported_names),
- )
+ edge_attrs: dict[str, Any] = {
+ "edge_type": "imports",
+ "imported_names": list(imp.imported_names),
+ }
+ # ``external:`` targets are excluded before the
+ # directory test, not after: an external node id has no
+ # directory, and a single-segment one such as
+ # ``external:strings`` yields parent ``"."`` — which is
+ # exactly _own_dir for any root-level file, so every
+ # dot-free stdlib import from the repo root would
+ # otherwise be stamped a same-package sibling.
+ if (
+ _unit_fanout
+ and not target.startswith("external:")
+ and PurePosixPath(target).parent.as_posix() == _own_dir
+ ):
+ edge_attrs["hint_source"] = SAME_PACKAGE_HINT
+ self._graph.add_edge(path, target, **edge_attrs)
import_targets[path] = file_imports
lang_import_time[_lang] = lang_import_time.get(_lang, 0.0) + (_t.monotonic() - _t0)
if progress:
diff --git a/packages/core/src/repowise/core/ingestion/resolvers/go.py b/packages/core/src/repowise/core/ingestion/resolvers/go.py
index 4a55e5fcf..2fec4cec4 100644
--- a/packages/core/src/repowise/core/ingestion/resolvers/go.py
+++ b/packages/core/src/repowise/core/ingestion/resolvers/go.py
@@ -32,6 +32,65 @@ def read_go_module_path(repo_path: Path | None) -> str | None:
return _read_module_directive(go_mod)
+def _read_local_replacements(go_mod: Path, repo_path: Path) -> list[tuple[str, str]]:
+ """Return ``(dir_posix, import_path)`` for each filesystem ``replace`` in *go_mod*.
+
+ ``replace github.com/x/y => ./y`` makes an import path local that no
+ ``module`` directive mentions, which is the normal way a Go monorepo wires a
+ library into its consumers. Without this the import matches no module and
+ resolves to an external node, so the local package loses every inbound edge
+ and reads as dead.
+
+ Only filesystem replacements count. Go's rule: the replacement is a path
+ when it starts with ``./``, ``../`` or is absolute; anything else is a
+ module-to-module replacement that stays external. A version on either side
+ is ignored, and a target outside the repo is skipped.
+ """
+ out: list[tuple[str, str]] = []
+ try:
+ text = go_mod.read_text(encoding="utf-8", errors="ignore")
+ except Exception:
+ return out
+
+ in_block = False
+ for raw in text.splitlines():
+ line = raw.split("//", 1)[0].strip()
+ if not line:
+ continue
+ if in_block:
+ if line.startswith(")"):
+ in_block = False
+ continue
+ elif line.startswith("replace ("):
+ in_block = True
+ continue
+ elif line.startswith("replace "):
+ line = line[len("replace ") :].strip()
+ else:
+ continue
+
+ if "=>" not in line:
+ continue
+ lhs, _, rhs = line.partition("=>")
+ # "path v1.2.3" on either side — the version is not part of the identity.
+ left = lhs.split()
+ right = rhs.split()
+ if not left or not right:
+ continue
+ if len(right) > 1:
+ continue # module => module@version, not a local directory
+ target = right[0]
+ if not (target.startswith("./") or target.startswith("../") or Path(target).is_absolute()):
+ continue
+ try:
+ resolved = (go_mod.parent / target).resolve()
+ rel = resolved.relative_to(repo_path.resolve()).as_posix()
+ except (OSError, ValueError):
+ continue # replacement points outside the repo
+ out.append(("" if rel == "." else rel, left[0]))
+ return out
+
+
def read_go_modules(
repo_path: Path | None, *, prune_nested_git: bool = True
) -> tuple[tuple[str, str], ...]:
@@ -39,7 +98,8 @@ def read_go_modules(
``((module_dir_posix, module_path), ...)`` sorted longest-module-path-first.
This supports Go monorepos with multiple modules (e.g.
- ``services/foo/go.mod`` + ``libs/bar/go.mod``).
+ ``services/foo/go.mod`` + ``libs/bar/go.mod``), and local ``replace``
+ directives, which bind an unrelated import path to a directory in the repo.
"""
if repo_path is None or not repo_path.is_dir():
return ()
@@ -56,6 +116,7 @@ def read_go_modules(
if module_dir == ".":
module_dir = ""
found.append((module_dir, module_path))
+ found.extend(_read_local_replacements(go_mod, repo_path))
# Longest module path first so prefix-matching prefers the most specific.
found.sort(key=lambda t: len(t[1]), reverse=True)
return tuple(found)
@@ -97,7 +158,24 @@ def resolve_go_import(module_path: str, importer_path: str, ctx: ResolverContext
if result:
return result
- # No module match — fall back to stem matching on the last segment.
+ # Nothing local matched. Go import paths are fully qualified, so the stem
+ # fallback below is a guess on the last segment alone — and a wrong guess
+ # invents an edge pointing the wrong way down the dependency graph. Because
+ # the mis-matched local package usually imports the importer back for real,
+ # that fabricates an import cycle Go itself would reject (issue #1294):
+ # hugo's ``import "strings"`` stem-matched ``tpl/strings/strings.go``, and
+ # ``golang.org/x/text/transform`` matched ``tpl/transform/transform.go``.
+ #
+ # Once a go.mod has told us the local module paths — including the
+ # directories bound by local ``replace`` directives — an import that matched
+ # none of them is not local, so guessing can only do harm.
+ if ctx.go_modules or ctx.go_module_path:
+ return ctx.add_external_node(module_path)
+
+ # No module metadata at all: a pre-modules / GOPATH-era checkout, or a
+ # hand-built test context. Here we genuinely cannot tell ``net/http`` from a
+ # GOPATH import root like ``myproject/lib``, so the legacy stem match stays
+ # rather than externalising real local code.
stem = module_path.rsplit("/", 1)[-1].lower()
result = ctx.stem_lookup(stem)
if result:
diff --git a/packages/core/src/repowise/core/ingestion/resolvers/go_workspace.py b/packages/core/src/repowise/core/ingestion/resolvers/go_workspace.py
index 5fe7ced6e..4260ba623 100644
--- a/packages/core/src/repowise/core/ingestion/resolvers/go_workspace.py
+++ b/packages/core/src/repowise/core/ingestion/resolvers/go_workspace.py
@@ -59,7 +59,17 @@ class GoPackageIndex:
"""Maps a fully-qualified import path → its package directory."""
def files_for_import(self, import_path: str) -> tuple[str, ...]:
- """Return every ``.go`` file in the package the import resolves to.
+ """Return the *importable* ``.go`` files of the package the import names.
+
+ ``_test.go`` files are excluded: they are compiled only into their own
+ package's test binary and are never part of the surface an importer
+ sees, so fanning an import out onto them asserts a dependency that
+ cannot exist. Left in, they let unrelated packages' test files reach
+ each other and close large false import cycles (issue #1294).
+
+ ``GoPackage.files`` keeps the full list — sibling cohesion, dead-code
+ rescue, and type-reference resolution all need test files to be part of
+ their own package. Only the *import* surface is narrowed here.
Empty tuple when the import path is not a local package (e.g. an
external ``github.com/...`` dependency) — callers fall back to the
@@ -69,7 +79,9 @@ class GoPackageIndex:
if pkg_dir is None:
return ()
pkg = self.packages.get(pkg_dir)
- return pkg.files if pkg else ()
+ if not pkg:
+ return ()
+ return tuple(f for f in pkg.files if not f.endswith("_test.go"))
def package_for_file(self, file_path: str) -> GoPackage | None:
"""Return the package owning *file_path*, or None."""
diff --git a/packages/core/src/repowise/core/ingestion/type_ref_resolution.py b/packages/core/src/repowise/core/ingestion/type_ref_resolution.py
index d620eea3c..4a43ae242 100644
--- a/packages/core/src/repowise/core/ingestion/type_ref_resolution.py
+++ b/packages/core/src/repowise/core/ingestion/type_ref_resolution.py
@@ -44,7 +44,7 @@ from __future__ import annotations
from collections.abc import Callable
from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
import structlog
@@ -253,6 +253,7 @@ def _resolve_go_type_refs(
if not parsed.type_refs:
return 0
+ from .cohesion import SAME_PACKAGE_HINT
from .parser_helpers import _GO_BUILTIN_TYPES
from .resolvers.go_workspace import get_or_build_go_index
@@ -264,6 +265,10 @@ def _resolve_go_type_refs(
# means a single import already maps to all of a package's files).
candidates: set[str] = set()
own_pkg = index.package_for_file(from_path)
+ # Siblings are one compilation unit, not dependencies: a Go package's files
+ # reference each other freely and cannot form an import cycle. Tracked so
+ # the resulting edges can be marked and kept out of cycle detection.
+ sibling_files: frozenset[str] = frozenset(own_pkg.files) if own_pkg else frozenset()
if own_pkg:
candidates.update(own_pkg.files)
for imp in parsed.imports:
@@ -288,8 +293,14 @@ def _resolve_go_type_refs(
if target is not None and target != from_path:
if (name, target) not in seen_targets:
seen_targets.add((name, target))
- _add_or_merge_type_use_edge(graph, src=from_path, dst=target,
- type_name=name, origin=ref.origin)
+ _add_or_merge_type_use_edge(
+ graph,
+ src=from_path,
+ dst=target,
+ type_name=name,
+ origin=ref.origin,
+ hint_source=SAME_PACKAGE_HINT if target in sibling_files else None,
+ )
emitted += 1
continue
# Type not found cross-file — check if it is defined in the same file.
@@ -733,9 +744,15 @@ def _add_or_merge_type_use_edge(
dst: str,
type_name: str,
origin: str,
+ hint_source: str | None = None,
) -> None:
"""Add a ``type_use`` edge between two files, merging on conflict.
+ *hint_source* marks the edge's provenance when the two files belong to one
+ compilation unit (see :mod:`repowise.core.ingestion.cohesion`); it is
+ stamped on creation only, since an existing edge already carries whatever
+ stronger evidence produced it.
+
The edge is persisted as its own ``edge_type='type_use'`` row so it
is observable in ``graph_edges`` (the SQLite layer drops ad-hoc
NetworkX attributes like ``via`` and ``origin``, so encoding the
@@ -764,12 +781,13 @@ def _add_or_merge_type_use_edge(
if type_name not in names:
names.append(type_name)
return
- graph.add_edge(
- src,
- dst,
- edge_type="type_use",
- origin=origin,
- confidence=_TYPE_USE_CONFIDENCE,
- type_uses=[type_name],
- imported_names=[type_name],
- )
+ attrs: dict[str, Any] = {
+ "edge_type": "type_use",
+ "origin": origin,
+ "confidence": _TYPE_USE_CONFIDENCE,
+ "type_uses": [type_name],
+ "imported_names": [type_name],
+ }
+ if hint_source is not None:
+ attrs["hint_source"] = hint_source
+ graph.add_edge(src, dst, **attrs)
diff --git a/packages/core/src/repowise/core/persistence/crud/graph.py b/packages/core/src/repowise/core/persistence/crud/graph.py
index 727ab5af8..d1e31be88 100644
--- a/packages/core/src/repowise/core/persistence/crud/graph.py
+++ b/packages/core/src/repowise/core/persistence/crud/graph.py
@@ -37,6 +37,10 @@ def _update_graph_edge(existing: GraphEdge, edge_data: dict) -> None:
imported = edge_data.get("imported_names_json")
if imported is not None:
existing.imported_names_json = imported
+ # Assigned unconditionally, including None: an edge that stops being
+ # cohesion (a real import statement appears between two package siblings)
+ # must lose the stamp, or cycle detection keeps skipping it forever.
+ existing.hint_source = edge_data.get("hint_source")
confidence = edge_data.get("confidence")
if confidence is not None:
# Keep the max on collision, mirroring the in-memory resolver
@@ -54,6 +58,9 @@ def _update_graph_metric(existing: GraphMetric, m: dict) -> None:
_MEMBERSHIP_FIELDS = ("node_type", "scc_id", "scc_size", "symbol_community_id")
+# Chunk size for IN (...) deletes — stays under SQLite's host-parameter limit.
+_MEMBERSHIP_PRUNE_CHUNK = 500
+
def _update_graph_node_membership(existing: GraphNodeMembership, m: dict) -> None:
for key in _MEMBERSHIP_FIELDS:
@@ -122,6 +129,7 @@ async def batch_upsert_graph_edges(
imported_names_json=e.get("imported_names_json", "[]"),
edge_type=e.get("edge_type", "imports"),
confidence=e.get("confidence", 1.0),
+ hint_source=e.get("hint_source"),
),
)
@@ -214,6 +222,7 @@ async def reconcile_edges_for_files(
imported_names_json=e.get("imported_names_json", "[]"),
edge_type=e.get("edge_type", "imports"),
confidence=e.get("confidence", 1.0),
+ hint_source=e.get("hint_source"),
)
)
await session.flush()
@@ -265,7 +274,36 @@ async def batch_upsert_graph_node_membership(
``scc_id`` / ``scc_size`` (file nodes in a size>=2 cycle) /
``symbol_community_id`` (symbol nodes). Additive to ``graph_nodes``;
SELECT-then-write for dialect portability (SQLite + Postgres).
+
+ The snapshot is a full recomputation, so absence is meaningful: a node the
+ caller did not send is a node that is no longer in any cycle or community.
+ Rows for absent nodes are therefore deleted rather than left behind. Without
+ that, a pure upsert let a file that dropped out of a cycle keep its old
+ ``scc_id`` / ``scc_size`` forever, and the Stats "largest cycle" record and
+ ``get_scc_members`` both read exactly those rows — so a fixed cycle stayed
+ on screen indefinitely.
"""
+ current = set(membership)
+ existing_ids = (
+ (
+ await session.execute(
+ select(GraphNodeMembership.node_id).where(
+ GraphNodeMembership.repository_id == repository_id
+ )
+ )
+ )
+ .scalars()
+ .all()
+ )
+ stale = [nid for nid in existing_ids if nid not in current]
+ for i in range(0, len(stale), _MEMBERSHIP_PRUNE_CHUNK):
+ await session.execute(
+ delete(GraphNodeMembership).where(
+ GraphNodeMembership.repository_id == repository_id,
+ GraphNodeMembership.node_id.in_(stale[i : i + _MEMBERSHIP_PRUNE_CHUNK]),
+ )
+ )
+
await _batch_upsert_keyed(
session,
GraphNodeMembership,
@@ -397,6 +435,7 @@ async def get_all_graph_edges(
"edge_type": row.edge_type,
"confidence": row.confidence,
"imported_names": imported_names,
+ "hint_source": row.hint_source,
}
)
return edges
diff --git a/packages/core/src/repowise/core/persistence/models.py b/packages/core/src/repowise/core/persistence/models.py
index 0ce6d40f4..dcbc7b4d7 100644
--- a/packages/core/src/repowise/core/persistence/models.py
+++ b/packages/core/src/repowise/core/persistence/models.py
@@ -282,6 +282,12 @@ class GraphEdge(Base):
imported_names_json: Mapped[str] = mapped_column(Text, nullable=False, default="[]")
edge_type: Mapped[str] = mapped_column(String(64), nullable=False, default="imports")
confidence: Mapped[float] = mapped_column(Float, nullable=False, default=1.0)
+ # Provenance of a synthesised edge (e.g. "same_package", "header_source_pair").
+ # NULL for edges that come from a real import/using directive. Cycle detection
+ # reads it to drop intra-compilation-unit edges; see
+ # repowise.core.ingestion.cohesion. Persisted because the health engine and
+ # incremental updates run against a graph rehydrated from these rows.
+ hint_source: Mapped[str | None] = mapped_column(String(64), nullable=True)
created_at: Mapped[datetime] = mapped_column(
DateTime(timezone=True), nullable=False, default=_now_utc
)
diff --git a/packages/core/src/repowise/core/pipeline/incremental.py b/packages/core/src/repowise/core/pipeline/incremental.py
index a9e6158dd..85f0aaf63 100644
--- a/packages/core/src/repowise/core/pipeline/incremental.py
+++ b/packages/core/src/repowise/core/pipeline/incremental.py
@@ -981,9 +981,19 @@ async def persist_incremental_index(
# whose updates all come from the post-commit hook this is the only
# place a retirement can land.
try:
- from repowise.core.pipeline.persist import sweep_retired_pages
+ from repowise.core.pipeline.persist import (
+ sweep_absent_cycle_pages,
+ sweep_retired_pages,
+ )
swept_page_ids = await sweep_retired_pages(session, repo_id)
+ # Same reasoning as the retirement sweep above: this path never
+ # regenerates a cycle page, so asking the rebuilt graph whether
+ # the cycle still exists is the only way a fixed cycle's page
+ # can ever be retired for a user who only runs `update`.
+ swept_page_ids += await sweep_absent_cycle_pages(
+ session, repo_id, graph_builder
+ )
except Exception as exc:
_skip("Retired page sweep", exc)
diff --git a/packages/core/src/repowise/core/pipeline/orchestrator.py b/packages/core/src/repowise/core/pipeline/orchestrator.py
index 67c4f90f9..104a30c30 100644
--- a/packages/core/src/repowise/core/pipeline/orchestrator.py
+++ b/packages/core/src/repowise/core/pipeline/orchestrator.py
@@ -820,14 +820,17 @@ async def run_pipeline(
# zero" here has exactly one cause. Their ids keep resolving through
# the redirect table, so retiring the rows breaks no inbound link.
authoritative_page_types.add("layer_page")
- # A deterministic run takes every candidate rather than a budgeted
- # slice, so an SCC page missing from its output means the cycle is
- # gone, not that it lost a budget fight. That makes the run
- # authoritative for the type and lets the sweep clear cycle pages for
- # cycles that no longer exist. A budgeted run cannot claim the same:
- # zero SCC pages there may just mean the allocation was zero.
- if getattr(resolved_generation_config, "deterministic", False):
- authoritative_page_types.add("scc_page")
+ # An SCC page missing from a full run's output means the cycle is gone,
+ # so the run is authoritative for the type and the sweep may clear the
+ # pages of cycles that no longer exist. This used to be claimed only for
+ # a deterministic run, on the premise that a budgeted run's zero might
+ # mean "the allocation was zero" rather than "there are no cycles" —
+ # but selection applies no budget to scc_groups (selection/selector.py
+ # _build_scc_candidates, unlike the file-page path), so zero produced
+ # really does mean zero cycles on every full run. Holding the narrower
+ # rule left a keyed index of a repo whose cycles all disappeared unable
+ # to ever retire them.
+ authoritative_page_types.add("scc_page")
# ---- Knowledge Graph enrichment: join + finalize ----------------------
# The structural half (layer naming + tour) ran concurrently with
diff --git a/packages/core/src/repowise/core/pipeline/persist.py b/packages/core/src/repowise/core/pipeline/persist.py
index 25045e675..9b0d10988 100644
--- a/packages/core/src/repowise/core/pipeline/persist.py
+++ b/packages/core/src/repowise/core/pipeline/persist.py
@@ -488,11 +488,51 @@ def _changed_file_edges(
"imported_names_json": json.dumps(data.get("imported_names", [])),
"edge_type": data.get("edge_type", "imports"),
"confidence": data.get("confidence", 1.0),
+ "hint_source": data.get("hint_source"),
}
)
return sorted(reconcile), edges
+async def _edges_predate_cohesion(session: Any, repo_id: str, graph_builder: Any) -> bool:
+ """True when ``graph_edges`` was written before edge cohesion was recorded.
+
+ An incremental update rewrites only the changed files' edges, so a store
+ indexed by an older build keeps that build's edges — and its resolution
+ mistakes — on every file that has not happened to change since. The health
+ engine and the server both read a graph rehydrated from those rows, so they
+ would go on reporting cycles the current engine no longer finds.
+
+ The signal is the store's own content rather than a version marker: a
+ routine update deliberately clamps ``store_format_version`` below the first
+ reindex gate, so a version comparison would refire on every run. Here, a
+ repo whose graph now has cohesion edges but whose table has no
+ ``hint_source`` anywhere is exactly a pre-cohesion store. Rewriting it
+ stamps those rows, so this answers False from then on and the full
+ reconcile happens once.
+ """
+ from sqlalchemy import select
+
+ from repowise.core.ingestion.cohesion import is_cohesion_edge
+ from repowise.core.persistence.models import GraphEdge
+
+ try:
+ graph = graph_builder.graph()
+ except Exception:
+ return False
+ if not any(is_cohesion_edge(d) for _u, _v, d in graph.edges(data=True)):
+ return False # nothing to record, so nothing can be missing
+
+ row = (
+ await session.execute(
+ select(GraphEdge.id)
+ .where(GraphEdge.repository_id == repo_id, GraphEdge.hint_source.is_not(None))
+ .limit(1)
+ )
+ ).first()
+ return row is None
+
+
async def persist_incremental_edges(
session: Any,
repo_id: str,
@@ -514,6 +554,14 @@ async def persist_incremental_edges(
return
from repowise.core.persistence.crud import reconcile_edges_for_files
+ if await _edges_predate_cohesion(session, repo_id, graph_builder):
+ # Widen the reconcile to the whole parsed set, once. Same code path,
+ # so the delete-then-insert still drops edges a file no longer has —
+ # which is what clears the pre-fix resolution mistakes, an upsert
+ # alone would leave them behind.
+ changed_paths = [pf.file_info.path for pf in parsed_files]
+ logger.info("graph_edges_cohesion_backfill", repo_id=repo_id, files=len(changed_paths))
+
reconcile_paths, edges = _changed_file_edges(graph_builder, parsed_files, changed_paths)
if not reconcile_paths:
return
@@ -805,6 +853,70 @@ async def _sweep_stale_generated_pages(
return swept
+async def sweep_absent_cycle_pages(session: Any, repo_id: str, graph_builder: Any) -> list[str]:
+ """Delete ``scc_page`` rows whose cycle no longer exists in the graph.
+
+ The other sweeps ask "did this run *produce* this page?", which a scoped run
+ cannot answer: ``repowise update`` runs with ``file_pages_only`` and never
+ reaches level 3, so it emits no ``scc_page`` at all and every prior row
+ looks stale to that question. ``_sweep_stale_generated_pages`` therefore
+ gates on the run declaring itself authoritative, and only a keyless
+ (``deterministic``) run does.
+
+ Between them those two rules leave a cycle page immortal on the paths that
+ matter: an update never regenerates it, and a keyed full re-index of a repo
+ whose cycles all disappeared never claims authority to retire it. A user
+ upgrading into a build that fixes a cycle-detection bug keeps being served
+ the cycles it fixed.
+
+ This asks a different question — "does the graph still contain this cycle?"
+ — which the rebuilt graph answers directly and identically on every path,
+ with no dependence on what generation chose to emit or what budget it had.
+ A cycle's page id is a hash of its sorted members
+ (:func:`~repowise.core.generation.models.scc_page_slug`), so the current
+ cycle set names exactly the ids that may survive.
+
+ Returns the deleted page ids so the caller can drop them from FTS and the
+ vector store after the session closes.
+ """
+ from sqlalchemy import delete, select
+
+ from repowise.core.generation.models import compute_page_id, scc_page_slug
+ from repowise.core.persistence.models import Page, PageVersion
+
+ if graph_builder is None:
+ return []
+ try:
+ sccs = graph_builder.strongly_connected_components()
+ except Exception: # a released graph has no cycles to speak for
+ return []
+
+ valid = {
+ compute_page_id("scc_page", scc_page_slug(sorted(scc))) for scc in sccs if len(scc) > 1
+ }
+ existing = (
+ (
+ await session.execute(
+ select(Page.id).where(
+ Page.repository_id == repo_id, Page.page_type == "scc_page"
+ )
+ )
+ )
+ .scalars()
+ .all()
+ )
+ stale = [pid for pid in existing if pid not in valid]
+ for i in range(0, len(stale), _PRUNE_CHUNK):
+ batch = stale[i : i + _PRUNE_CHUNK]
+ await session.execute(delete(PageVersion).where(PageVersion.page_id.in_(batch)))
+ await session.execute(
+ delete(Page).where(Page.repository_id == repo_id, Page.id.in_(batch))
+ )
+ if stale:
+ logger.info("absent_cycle_pages_swept", repo_id=repo_id, count=len(stale))
+ return stale
+
+
async def sweep_superseded_generated_pages(
session: Any,
repo_id: str,
@@ -949,6 +1061,7 @@ async def persist_ingestion(result: Any, session: Any, repo_id: str) -> int:
"imported_names_json": json.dumps(data.get("imported_names", [])),
"edge_type": data.get("edge_type", "imports"),
"confidence": data.get("confidence", 1.0),
+ "hint_source": data.get("hint_source"),
}
)
if edges:
diff --git a/tests/unit/ingestion/test_cohesion_cycles.py b/tests/unit/ingestion/test_cohesion_cycles.py
new file mode 100644
index 000000000..3d5b9fa9c
--- /dev/null
+++ b/tests/unit/ingestion/test_cohesion_cycles.py
@@ -0,0 +1,463 @@
+"""Cohesion edges must not be read as dependency cycles (issue #1294).
+
+Go reports one *package* — a directory of ``.go`` files — as its unit of
+compilation. Those files reference each other with no import statement, so
+several resolver passes synthesise file-level edges between them to keep
+reachability and dead-code analysis honest. Feeding those synthesised edges to
+cycle detection turned every cohesive Go package into a "Circular Dependency"
+page listing every file in it.
+
+These tests pin the three mechanisms that produced the false cycles and the two
+places that consume cycles, and they guard the reachability behaviour the
+synthesised edges exist for in the first place.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import networkx as nx
+
+from repowise.core.analysis.health.refactoring.graph_signals import (
+ build_file_scc_index,
+ cycle_edges,
+)
+from repowise.core.ingestion import ASTParser, FileTraverser, GraphBuilder
+from repowise.core.ingestion.cohesion import (
+ COHESION_HINTS,
+ SAME_PACKAGE_HINT,
+ UNIT_FANOUT_LANGUAGES,
+ is_cohesion_edge,
+)
+
+
+def _builder(repo: Path) -> GraphBuilder:
+ traverser = FileTraverser(repo)
+ parser = ASTParser()
+ builder = GraphBuilder(repo_path=repo)
+ for fi in traverser.traverse():
+ builder.add_file(parser.parse_file(fi, Path(fi.abs_path).read_bytes()))
+ builder.build()
+ return builder
+
+
+def _cycles(graph: nx.DiGraph) -> list[set[str]]:
+ return [set(c) for c in nx.strongly_connected_components(graph) if len(c) > 1]
+
+
+def _pair_builder(**edge_attrs) -> GraphBuilder:
+ """A bare builder holding one mutual a.go <-> b.go pair."""
+ import threading
+
+ b = GraphBuilder.__new__(GraphBuilder)
+ b._graph = nx.DiGraph()
+ b._built = True
+ b._subgraph_lock = threading.Lock()
+ b._file_subgraph_cache = None
+ b._symbol_subgraph_cache = None
+ b._cycle_subgraph_cache = None
+ b._graph.add_node("a.go", node_type="file")
+ b._graph.add_node("b.go", node_type="file")
+ b._graph.add_edge("a.go", "b.go", edge_type="imports", **edge_attrs)
+ b._graph.add_edge("b.go", "a.go", edge_type="imports", **edge_attrs)
+ return b
+
+
+def _go_pkg(root: Path, module: str = "example.com/app") -> None:
+ (root / "go.mod").write_text(f"module {module}\n\ngo 1.22\n")
+
+
+class TestCohesionPredicate:
+ def test_every_synthesising_pass_stops_a_cycle(self) -> None:
+ # Behavioural: each hint a resolver pass actually stamps must keep a
+ # mutual pair out of cycle detection.
+ for hint in COHESION_HINTS:
+ b = _pair_builder(hint_source=hint)
+ assert _cycles(b.cycle_subgraph()) == [], hint
+
+ def test_real_import_is_not_cohesion(self) -> None:
+ assert not is_cohesion_edge({"edge_type": "imports"})
+ assert not is_cohesion_edge({"edge_type": "imports", "hint_source": None})
+
+ def test_directional_hints_still_close_a_cycle(self) -> None:
+ # An rspec file genuinely depends on its subject; F# compile order is a
+ # real dependency. Neither is co-membership, so neither is exempt.
+ for hint in ("spec_mirror", "compile_order"):
+ b = _pair_builder(hint_source=hint)
+ assert _cycles(b.cycle_subgraph()) == [{"a.go", "b.go"}], hint
+
+
+class TestPythonSiblingsAreRealDependencies:
+ def test_python_circular_sibling_import_is_still_a_cycle(self, tmp_path: Path) -> None:
+ # Python modules are independent even in one directory: the fan-out
+ # exemption must not reach them.
+ assert "python" not in UNIT_FANOUT_LANGUAGES
+ pkg = tmp_path / "pkg"
+ pkg.mkdir()
+ (pkg / "__init__.py").write_text("")
+ (pkg / "a.py").write_text("from pkg.b import B\n\nclass A: pass\n")
+ (pkg / "b.py").write_text("from pkg.a import A\n\nclass B: pass\n")
+ b = _builder(tmp_path)
+ assert any(
+ {"pkg/a.py", "pkg/b.py"} <= c for c in _cycles(b.cycle_subgraph())
+ ), "a real Python circular import must still be reported"
+
+
+class TestCppSameDirectoryIncludesStayDependencies:
+ def test_header_impl_pair_is_not_a_cycle(self, tmp_path: Path) -> None:
+ (tmp_path / "util.h").write_text("int helper(void);\n")
+ (tmp_path / "util.c").write_text('#include "util.h"\nint helper(void){return 1;}\n')
+ b = _builder(tmp_path)
+ # The pairing pass makes this mutual by construction; it is one unit.
+ assert b.file_subgraph().has_edge("util.h", "util.c")
+ assert _cycles(b.cycle_subgraph()) == []
+
+ def test_unrelated_same_dir_include_is_still_a_dependency(self, tmp_path: Path) -> None:
+ # C's fan-out unit is a build target, not a directory: foo.c -> bar.h in
+ # a flat src/ layout is a genuine, cuttable edge and must not be exempt.
+ (tmp_path / "bar.h").write_text("int bar(void);\n")
+ (tmp_path / "foo.c").write_text('#include "bar.h"\nint foo(void){return bar();}\n')
+ graph = _builder(tmp_path).cycle_subgraph()
+ assert graph.has_edge("foo.c", "bar.h")
+
+
+class TestCycleSubgraph:
+ def _graph_with(self, **edge_attrs) -> GraphBuilder:
+ b = GraphBuilder.__new__(GraphBuilder)
+ import threading
+
+ b._graph = nx.DiGraph()
+ b._built = True
+ b._subgraph_lock = threading.Lock()
+ b._file_subgraph_cache = None
+ b._symbol_subgraph_cache = None
+ b._cycle_subgraph_cache = None
+ b._graph.add_node("a.go", node_type="file")
+ b._graph.add_node("b.go", node_type="file")
+ b._graph.add_edge("a.go", "b.go", edge_type="imports", **edge_attrs)
+ b._graph.add_edge("b.go", "a.go", edge_type="imports", **edge_attrs)
+ return b
+
+ def test_cohesion_pair_is_not_a_cycle(self) -> None:
+ b = self._graph_with(hint_source=SAME_PACKAGE_HINT)
+ assert _cycles(b.cycle_subgraph()) == []
+ assert [c for c in b.strongly_connected_components() if len(c) > 1] == []
+
+ def test_real_pair_is_still_a_cycle(self) -> None:
+ b = self._graph_with()
+ assert _cycles(b.cycle_subgraph()) == [{"a.go", "b.go"}]
+
+ def test_file_subgraph_keeps_cohesion_edges(self) -> None:
+ # Reachability, PageRank and the degree kernels must be unaffected —
+ # dead-code and orphan detection are why these edges are synthesised.
+ b = self._graph_with(hint_source=SAME_PACKAGE_HINT)
+ fs = b.file_subgraph()
+ assert fs.number_of_edges() == 2
+ assert fs.in_degree("a.go") == 1
+ assert b.cycle_subgraph().number_of_edges() == 0
+
+
+class TestHealthCycleDefinitionAgrees:
+ """break_cycle must not propose cutting an edge the wiki calls no cycle."""
+
+ def _pair(self, **attrs) -> nx.DiGraph:
+ g = nx.DiGraph()
+ g.add_node("a.go", node_type="file")
+ g.add_node("b.go", node_type="file")
+ g.add_edge("a.go", "b.go", edge_type="imports", **attrs)
+ g.add_edge("b.go", "a.go", edge_type="imports", **attrs)
+ return g
+
+ def test_cohesion_pair_yields_no_scc(self) -> None:
+ assert build_file_scc_index(self._pair(hint_source=SAME_PACKAGE_HINT)) == {}
+
+ def test_real_pair_yields_an_scc(self) -> None:
+ idx = build_file_scc_index(self._pair())
+ assert idx["a.go"] == ("a.go", "b.go")
+
+ def test_cohesion_edges_are_not_cut_candidates(self) -> None:
+ g = self._pair(hint_source=SAME_PACKAGE_HINT)
+ assert cycle_edges(g, ("a.go", "b.go")) == []
+
+
+class TestGoSamePackageIsNotACycle:
+ def test_sibling_files_do_not_form_a_cycle(self, tmp_path: Path) -> None:
+ _go_pkg(tmp_path)
+ pkg = tmp_path / "acl"
+ pkg.mkdir()
+ # Mutually referencing siblings — legal Go, one compilation unit.
+ (pkg / "acl.go").write_text(
+ "package acl\n\ntype ACL struct{ Owner *User }\n"
+ "func New(u *User) *ACL { return &ACL{Owner: u} }\n"
+ )
+ (pkg / "user.go").write_text(
+ "package acl\n\ntype User struct{ Rules *ACL }\n"
+ "func Owner(a *ACL) *User { return a.Owner }\n"
+ )
+ b = _builder(tmp_path)
+ assert _cycles(b.cycle_subgraph()) == []
+ # ...but they are still connected, so neither reads as an orphan.
+ fs = b.file_subgraph()
+ assert fs.in_degree("acl/user.go") > 0 or fs.in_degree("acl/acl.go") > 0
+
+ def test_importing_own_package_marks_siblings_as_cohesion(self, tmp_path: Path) -> None:
+ # An external test package (``package acl_test``) sits in the same
+ # directory and imports the package under test; the fan-out lands on
+ # every sibling, including the other test files.
+ _go_pkg(tmp_path)
+ pkg = tmp_path / "acl"
+ pkg.mkdir()
+ (pkg / "acl.go").write_text("package acl\n\ntype ACL struct{}\n")
+ (pkg / "a_test.go").write_text(
+ 'package acl_test\n\nimport "example.com/app/acl"\n\n'
+ "func A() { _ = acl.ACL{} }\n"
+ )
+ (pkg / "b_test.go").write_text(
+ 'package acl_test\n\nimport "example.com/app/acl"\n\n'
+ "func B() { _ = acl.ACL{} }\n"
+ )
+ b = _builder(tmp_path)
+ assert _cycles(b.cycle_subgraph()) == []
+ sibling_edges = [
+ (u, v, d)
+ for u, v, d in b.file_subgraph().edges(data=True)
+ if not v.startswith("external:") and Path(u).parent == Path(v).parent
+ ]
+ # Guard the loop actually ran — otherwise the assertion below is vacuous.
+ assert sibling_edges, "expected the fan-out to produce sibling edges"
+ for u, v, d in sibling_edges:
+ assert is_cohesion_edge(d), f"{u} -> {v} should be cohesion"
+
+ def test_real_cross_package_cycle_still_reported(self, tmp_path: Path) -> None:
+ _go_pkg(tmp_path)
+ for name, other in (("alpha", "beta"), ("beta", "alpha")):
+ d = tmp_path / name
+ d.mkdir()
+ (d / f"{name}.go").write_text(
+ f"package {name}\n\nimport \"example.com/app/{other}\"\n\n"
+ f"func Use() {{ _ = {other}.Name }}\n\nvar Name = \"{name}\"\n"
+ )
+ b = _builder(tmp_path)
+ assert _cycles(b.cycle_subgraph()) == [{"alpha/alpha.go", "beta/beta.go"}]
+
+
+class TestGoImportResolutionHonesty:
+ def test_stdlib_import_does_not_match_a_local_package(self, tmp_path: Path) -> None:
+ # hugo's shape: a local ``tpl/strings`` package plus ``import "strings"``.
+ # The stdlib import must resolve external, not onto the local package —
+ # otherwise it pairs with the local package's real reverse import and
+ # fabricates a cycle Go itself would reject.
+ _go_pkg(tmp_path)
+ tpl = tmp_path / "tpl" / "strings"
+ tpl.mkdir(parents=True)
+ helpers = tmp_path / "helpers"
+ helpers.mkdir()
+ (helpers / "general.go").write_text(
+ 'package helpers\n\nimport "strings"\n\n'
+ 'func Up(s string) string { return strings.ToUpper(s) }\n'
+ )
+ (tpl / "strings.go").write_text(
+ 'package strings\n\nimport "example.com/app/helpers"\n\n'
+ "func Up(s string) string { return helpers.Up(s) }\n"
+ )
+ b = _builder(tmp_path)
+ graph = b.graph()
+ assert not graph.has_edge("helpers/general.go", "tpl/strings/strings.go")
+ assert graph.has_edge("tpl/strings/strings.go", "helpers/general.go")
+ assert _cycles(b.cycle_subgraph()) == []
+
+ def test_third_party_import_does_not_match_a_local_package(self, tmp_path: Path) -> None:
+ _go_pkg(tmp_path)
+ tpl = tmp_path / "tpl" / "transform"
+ tpl.mkdir(parents=True)
+ (tpl / "transform.go").write_text("package transform\n\ntype T struct{}\n")
+ h = tmp_path / "helpers"
+ h.mkdir()
+ (h / "general.go").write_text(
+ 'package helpers\n\nimport "golang.org/x/text/transform"\n\n'
+ "func F() { _ = transform.Nop }\n"
+ )
+ graph = _builder(tmp_path).graph()
+ assert not graph.has_edge("helpers/general.go", "tpl/transform/transform.go")
+
+ def test_local_package_still_resolves(self, tmp_path: Path) -> None:
+ _go_pkg(tmp_path)
+ store = tmp_path / "store"
+ store.mkdir()
+ (store / "store.go").write_text("package store\n\ntype S struct{}\n")
+ (tmp_path / "main.go").write_text(
+ 'package main\n\nimport "example.com/app/store"\n\n'
+ "func main() { _ = store.S{} }\n"
+ )
+ graph = _builder(tmp_path).graph()
+ assert graph.has_edge("main.go", "store/store.go")
+
+
+class TestExternalTargetsAreNeverCohesion:
+ def test_root_file_stdlib_import_is_not_stamped(self, tmp_path: Path) -> None:
+ # ``external:strings`` has parent "." — the same value as a root-level
+ # file's own directory — so a naive directory test stamps every dot-free
+ # stdlib import from the repo root as a same-package sibling.
+ _go_pkg(tmp_path)
+ (tmp_path / "main.go").write_text(
+ 'package main\n\nimport (\n\t"strings"\n\t"net/http"\n)\n\n'
+ "func main() { _ = strings.ToUpper; _ = http.Get }\n"
+ )
+ graph = _builder(tmp_path).graph()
+ externals = [
+ (u, v, d) for u, v, d in graph.edges(data=True) if v.startswith("external:")
+ ]
+ assert externals, "expected stdlib imports to resolve external"
+ for u, v, d in externals:
+ assert not is_cohesion_edge(d), f"{u} -> {v} wrongly marked cohesion"
+
+
+class TestCohesionSurvivesPersistence:
+ def test_rehydrated_graph_still_suppresses_the_cycle(self) -> None:
+ # hint_source lives only in the NetworkX graph unless it round-trips
+ # through graph_edges; the health engine reads a rehydrated graph, so a
+ # lost stamp brings every false cycle straight back.
+ edges = [
+ {
+ "source_node_id": "acl/acl.go",
+ "target_node_id": "acl/user.go",
+ "edge_type": "imports",
+ "confidence": 1.0,
+ "imported_names": [],
+ "hint_source": SAME_PACKAGE_HINT,
+ },
+ {
+ "source_node_id": "acl/user.go",
+ "target_node_id": "acl/acl.go",
+ "edge_type": "imports",
+ "confidence": 1.0,
+ "imported_names": [],
+ "hint_source": SAME_PACKAGE_HINT,
+ },
+ ]
+ nodes = [
+ {"node_id": "acl/acl.go", "node_type": "file"},
+ {"node_id": "acl/user.go", "node_type": "file"},
+ ]
+ b = GraphBuilder.from_persisted(nodes=nodes, edges=edges, metrics={})
+ assert _cycles(b.cycle_subgraph()) == []
+ assert build_file_scc_index(b.graph()) == {}
+
+ def test_rehydrated_real_cycle_is_still_reported(self) -> None:
+ edges = [
+ {"source_node_id": "a.py", "target_node_id": "b.py", "edge_type": "imports"},
+ {"source_node_id": "b.py", "target_node_id": "a.py", "edge_type": "imports"},
+ ]
+ nodes = [
+ {"node_id": "a.py", "node_type": "file"},
+ {"node_id": "b.py", "node_type": "file"},
+ ]
+ b = GraphBuilder.from_persisted(nodes=nodes, edges=edges, metrics={})
+ assert _cycles(b.cycle_subgraph()) == [{"a.py", "b.py"}]
+
+
+class TestGoLocalReplaceDirectives:
+ def test_replace_binds_an_unrelated_import_path_to_a_local_dir(self, tmp_path: Path) -> None:
+ # A Go monorepo wires a library in with `replace`; the import path no
+ # `module` directive mentions is still local and must keep its edge.
+ (tmp_path / "go.mod").write_text(
+ "module example.com/app\n\ngo 1.22\n\n"
+ "replace github.com/acme/lib => ./lib\n"
+ )
+ lib = tmp_path / "lib"
+ lib.mkdir()
+ (lib / "lib.go").write_text("package lib\n\ntype T struct{}\n")
+ (tmp_path / "main.go").write_text(
+ 'package main\n\nimport "github.com/acme/lib"\n\nfunc main() { _ = lib.T{} }\n'
+ )
+ graph = _builder(tmp_path).graph()
+ assert graph.has_edge("main.go", "lib/lib.go")
+
+ def test_module_to_module_replace_stays_external(self, tmp_path: Path) -> None:
+ (tmp_path / "go.mod").write_text(
+ "module example.com/app\n\ngo 1.22\n\n"
+ "replace github.com/acme/lib => github.com/fork/lib v1.2.3\n"
+ )
+ lib = tmp_path / "lib"
+ lib.mkdir()
+ (lib / "lib.go").write_text("package lib\n\ntype T struct{}\n")
+ (tmp_path / "main.go").write_text(
+ 'package main\n\nimport "github.com/acme/lib"\n\nfunc main() {}\n'
+ )
+ graph = _builder(tmp_path).graph()
+ assert not graph.has_edge("main.go", "lib/lib.go")
+
+
+class TestGoStemFallbackPreservedWithoutModuleMetadata:
+ def test_no_go_mod_keeps_the_legacy_stem_match(self, tmp_path: Path) -> None:
+ # A pre-modules / GOPATH checkout cannot distinguish ``net/http`` from a
+ # GOPATH import root, so the legacy guess stays rather than
+ # externalising real local code.
+ lib = tmp_path / "util"
+ lib.mkdir()
+ (lib / "util.go").write_text("package util\n\ntype T struct{}\n")
+ (tmp_path / "main.go").write_text(
+ 'package main\n\nimport "myproject/util"\n\nfunc main() { _ = util.T{} }\n'
+ )
+ graph = _builder(tmp_path).graph()
+ assert graph.has_edge("main.go", "util/util.go")
+
+
+class TestCycleSubgraphCacheInvalidation:
+ def test_adding_a_file_clears_the_cached_cycle_subgraph(self, tmp_path: Path) -> None:
+ b = _pair_builder(hint_source=SAME_PACKAGE_HINT)
+ assert b.cycle_subgraph().number_of_edges() == 0
+ assert b._cycle_subgraph_cache is not None
+ b._invalidate_subgraph_caches()
+ assert b._cycle_subgraph_cache is None
+ b._invalidate_metric_caches()
+ assert b._cycle_subgraph_cache is None
+
+ def test_unpickling_an_older_builder_does_not_crash(self) -> None:
+ b = _pair_builder(hint_source=SAME_PACKAGE_HINT)
+ state = b.__getstate__()
+ state.pop("_cycle_subgraph_cache", None) # an older build's bundle
+ revived = GraphBuilder.__new__(GraphBuilder)
+ revived.__setstate__(state)
+ assert _cycles(revived.cycle_subgraph()) == []
+
+
+class TestGoImportSurfaceExcludesTestFiles:
+ def test_importing_a_package_does_not_reach_its_test_files(self, tmp_path: Path) -> None:
+ _go_pkg(tmp_path)
+ store = tmp_path / "store"
+ store.mkdir()
+ (store / "store.go").write_text("package store\n\ntype S struct{}\n")
+ (store / "store_test.go").write_text("package store\n\nfunc TestS(t *T) {}\ntype T struct{}\n")
+ (tmp_path / "main.go").write_text(
+ 'package main\n\nimport "example.com/app/store"\n\n'
+ "func main() { _ = store.S{} }\n"
+ )
+ graph = _builder(tmp_path).graph()
+ assert graph.has_edge("main.go", "store/store.go")
+ # A test file is never part of the importable package surface.
+ assert not graph.has_edge("main.go", "store/store_test.go")
+
+ def test_package_still_owns_its_test_files(self, tmp_path: Path) -> None:
+ from repowise.core.ingestion.resolvers.context import ResolverContext
+ from repowise.core.ingestion.resolvers.go_workspace import build_go_package_index
+
+ _go_pkg(tmp_path)
+ store = tmp_path / "store"
+ store.mkdir()
+ (store / "store.go").write_text("package store\n\ntype S struct{}\n")
+ (store / "store_test.go").write_text("package store\n")
+ ctx = ResolverContext(
+ path_set={"go.mod", "store/store.go", "store/store_test.go"},
+ stem_map={},
+ graph=nx.DiGraph(),
+ repo_path=tmp_path,
+ go_modules=(("", "example.com/app"),),
+ )
+ index = build_go_package_index(ctx)
+ pkg = index.package_for_file("store/store_test.go")
+ assert pkg is not None
+ # Sibling cohesion / dead-code rescue still see the test file.
+ assert "store/store_test.go" in pkg.files
+ # The import surface does not.
+ assert index.files_for_import("example.com/app/store") == ("store/store.go",)
diff --git a/tests/unit/persistence/test_cycle_page_convergence.py b/tests/unit/persistence/test_cycle_page_convergence.py
new file mode 100644
index 000000000..acceae6bf
--- /dev/null
+++ b/tests/unit/persistence/test_cycle_page_convergence.py
@@ -0,0 +1,141 @@
+"""`repowise update` must retire the cycles a fixed engine no longer finds.
+
+The engine fix for #1294 only changes what the in-memory graph says. Three
+persisted artifacts had no path back to agreement with it on an incremental
+update, so a user who upgraded and ran `update` would keep being served the
+false cycles: the `scc_page` rows, the `graph_node_membership` rows behind the
+Stats "largest cycle" record, and the `graph_edges` rows the health engine
+rehydrates. These cover all three.
+"""
+
+from __future__ import annotations
+
+import networkx as nx
+import pytest
+
+from repowise.core.generation.models import compute_page_id, scc_page_slug
+from repowise.core.persistence import (
+ batch_upsert_graph_node_membership,
+ get_scc_members,
+)
+from repowise.core.persistence.models import GraphNodeMembership, Page
+from repowise.core.pipeline.persist import sweep_absent_cycle_pages
+from tests.unit.persistence.helpers import insert_repo, make_page_kwargs
+
+
+async def repo_id(async_session) -> str:
+ repo = await insert_repo(async_session)
+ return repo.id
+
+
+class _FakeBuilder:
+ """Minimal stand-in exposing only what the sweep reads."""
+
+ def __init__(self, sccs: list[set[str]], graph: nx.DiGraph | None = None) -> None:
+ self._sccs = sccs
+ self._graph = graph if graph is not None else nx.DiGraph()
+
+ def strongly_connected_components(self):
+ return [frozenset(s) for s in self._sccs]
+
+ def graph(self):
+ return self._graph
+
+
+async def _add_scc_page(async_session, repo_id: str, members: list[str]) -> str:
+ from repowise.core.persistence.crud import upsert_page
+
+ slug = scc_page_slug(sorted(members))
+ await upsert_page(
+ async_session,
+ **make_page_kwargs(
+ repo_id,
+ page_id=compute_page_id("scc_page", slug),
+ page_type="scc_page",
+ target_path=slug,
+ title="Circular Dependency",
+ ),
+ )
+ await async_session.flush()
+ return compute_page_id("scc_page", slug)
+
+
+class TestCyclePageSweep:
+ async def test_page_for_a_vanished_cycle_is_deleted(self, async_session, repo_id) -> None:
+ ghost = await _add_scc_page(async_session, repo_id, ["acl/acl.go", "acl/user.go"])
+ # The rebuilt graph finds no cycle at all.
+ swept = await sweep_absent_cycle_pages(async_session, repo_id, _FakeBuilder([]))
+ assert swept == [ghost]
+ remaining = (await async_session.execute(Page.__table__.select())).fetchall()
+ assert not [r for r in remaining if r.page_type == "scc_page"]
+
+ async def test_page_for_a_surviving_cycle_is_kept(self, async_session, repo_id) -> None:
+ members = ["a.py", "b.py"]
+ live = await _add_scc_page(async_session, repo_id, members)
+ swept = await sweep_absent_cycle_pages(async_session, repo_id, _FakeBuilder([set(members)]))
+ assert swept == []
+ rows = (await async_session.execute(Page.__table__.select())).fetchall()
+ assert [r.id for r in rows if r.page_type == "scc_page"] == [live]
+
+ async def test_shrunken_cycle_retires_the_old_id(self, async_session, repo_id) -> None:
+ # Membership is the page's identity, so a cycle that loses a member is
+ # a different page: the old row must not linger as a duplicate.
+ old = await _add_scc_page(async_session, repo_id, ["a.py", "b.py", "c.py"])
+ swept = await sweep_absent_cycle_pages(
+ async_session, repo_id, _FakeBuilder([{"a.py", "b.py"}])
+ )
+ assert swept == [old]
+
+ async def test_missing_builder_is_a_no_op(self, async_session, repo_id) -> None:
+ page = await _add_scc_page(async_session, repo_id, ["a.py", "b.py"])
+ assert await sweep_absent_cycle_pages(async_session, repo_id, None) == []
+ rows = (await async_session.execute(Page.__table__.select())).fetchall()
+ assert [r.id for r in rows] == [page]
+
+
+class TestMembershipPrune:
+ async def test_node_that_left_a_cycle_loses_its_row(self, async_session, repo_id) -> None:
+ await batch_upsert_graph_node_membership(
+ async_session,
+ repo_id,
+ {
+ "a.go": {"node_type": "file", "scc_id": 0, "scc_size": 2},
+ "b.go": {"node_type": "file", "scc_id": 0, "scc_size": 2},
+ },
+ )
+ assert set((await get_scc_members(async_session, repo_id)).get(0, [])) == {"a.go", "b.go"}
+
+ # Re-run after the fix: the cycle is gone, so the snapshot is empty.
+ await batch_upsert_graph_node_membership(async_session, repo_id, {})
+ rows = (
+ await async_session.execute(
+ GraphNodeMembership.__table__.select().where(
+ GraphNodeMembership.repository_id == repo_id
+ )
+ )
+ ).fetchall()
+ assert rows == []
+ assert (await get_scc_members(async_session, repo_id)) == {}
+
+ async def test_surviving_nodes_are_kept_and_updated(self, async_session, repo_id) -> None:
+ await batch_upsert_graph_node_membership(
+ async_session,
+ repo_id,
+ {
+ "a.go": {"node_type": "file", "scc_id": 0, "scc_size": 3},
+ "b.go": {"node_type": "file", "scc_id": 0, "scc_size": 3},
+ "c.go": {"node_type": "file", "scc_id": 0, "scc_size": 3},
+ },
+ )
+ await batch_upsert_graph_node_membership(
+ async_session,
+ repo_id,
+ {
+ "a.go": {"node_type": "file", "scc_id": 0, "scc_size": 2},
+ "b.go": {"node_type": "file", "scc_id": 0, "scc_size": 2},
+ },
+ )
+ assert set((await get_scc_members(async_session, repo_id)).get(0, [])) == {"a.go", "b.go"}