Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
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.pyindex 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.pynew file mode 100644index 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.pyindex 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 annotationsfrom 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.pynew file mode 100644index 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_HINTSdiff --git a/packages/core/src/repowise/core/ingestion/graph/_metrics.py b/packages/core/src/repowise/core/ingestion/graph/_metrics.pyindex 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 Anyimport networkx as nximport 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 = subreturn 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'snode insertion order varies between runs (git-indexer threads finishin 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.pyindex 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_sourcegraph.add_edge(source, target, **edge_attrs)edge_count += 1diff --git a/packages/core/src/repowise/core/ingestion/graph/builder.py b/packages/core/src/repowise/core/ingestion/graph/builder.pyindex 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, PurePosixPathfrom typing import Anyimport networkx as nximport structlog+from ..cohesion import SAME_PACKAGE_HINT, UNIT_FANOUT_LANGUAGESfrom ..models import ParsedFilefrom ..resolvers import ResolverContext, resolve_importfrom ..resolvers.go import read_go_module_path, read_go_modules@@ -101,6 +102,7 @@ class GraphBuilder(MetricsMixin, ResolveMixin, EdgesMixin, SerializeMixin, Rehydself._subgraph_lock = threading.Lock()self._file_subgraph_cache: nx.DiGraph | None = Noneself._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, Rehydself.__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, Rehydself._execution_flow_cache = Noneself._file_subgraph_cache = Noneself._symbol_subgraph_cache = None+ self._cycle_subgraph_cache = Noneself._import_name_maps = Nonedef _invalidate_subgraph_caches(self) -> None:@@ -154,6 +161,7 @@ class GraphBuilder(MetricsMixin, ResolveMixin, EdgesMixin, SerializeMixin, Rehyd"""self._file_subgraph_cache = Noneself._symbol_subgraph_cache = None+ self._cycle_subgraph_cache = Nonedef 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, Rehydmerged = list(set(existing + imp.imported_names))self._graph[path][target]["imported_names"] = mergedelse:- 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_importslang_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.pyindex 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: ResolverContextif 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.pyindex 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. anexternal ``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.pyindex 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 annotationsfrom collections.abc import Callablefrom pathlib import Path-from typing import TYPE_CHECKING+from typing import TYPE_CHECKING, Anyimport structlog@@ -253,6 +253,7 @@ def _resolve_go_type_refs(if not parsed.type_refs:return 0+ from .cohesion import SAME_PACKAGE_HINTfrom .parser_helpers import _GO_BUILTIN_TYPESfrom .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 += 1continue# 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 itis observable in ``graph_edges`` (the SQLite layer drops ad-hocNetworkX 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.pyindex 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 edgesdiff --git a/packages/core/src/repowise/core/persistence/models.py b/packages/core/src/repowise/core/persistence/models.pyindex 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.pyindex 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.pyindex 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 withdiff --git a/packages/core/src/repowise/core/pipeline/persist.py b/packages/core/src/repowise/core/pipeline/persist.pyindex 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(returnfrom 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.pynew file mode 100644index 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.pynew file mode 100644index 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"}