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.

feat(refactor): richer cohesion signals for Split File (#614)

Raghav Chamadiya56d34273a997
diff --git a/packages/core/src/repowise/core/analysis/health/engine.py b/packages/core/src/repowise/core/analysis/health/engine.py
index f1ae72eeb..483fb1f7d 100644
--- a/packages/core/src/repowise/core/analysis/health/engine.py
+++ b/packages/core/src/repowise/core/analysis/health/engine.py
@@ -855,6 +855,7 @@ class HealthAnalyzer:
graph=self.graph,
file_scc=(file_scc_index or {}).get(file_path),
function_analyses=self._extract_method_analyses(pf, findings),
+ blame_index=blame_index,
)
suggestions = detect_refactorings(rctx, disabled=disabled_refactorings or ())
return metric, findings, suggestions
diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/models.py b/packages/core/src/repowise/core/analysis/health/refactoring/models.py
index 87d9bf531..94db84ed7 100644
--- a/packages/core/src/repowise/core/analysis/health/refactoring/models.py
+++ b/packages/core/src/repowise/core/analysis/health/refactoring/models.py
@@ -61,7 +61,10 @@ For Split File:
Go, true for Python/TS).
- ``evidence`` = ``{"file_nloc": int, "symbol_count": int, "group_count": int,
"modularity": float, "intra_edges": int, "cut_edges": int}`` — the size and
- decomposability signals that justify (and gate) the split.
+ decomposability signals that justify (and gate) the split. Two optional keys
+ are added only when the richer cohesion signals fired:
+ ``"cochange_edges": int`` (symbol pairs joined by a git co-change edge) and
+ ``"import_edges": int`` (pairs joined by a shared imported-name surface).
- ``blast_radius`` = ``{"dependent_files": [str, ...], "dependent_count": int,
"import_rewrites": int}`` — the external files referencing the split
symbols and how many import edits the split implies.
@@ -130,6 +133,14 @@ class RefactoringContext:
# a re-parse of its own. Empty for files with no such finding -- the
# detector then yields nothing.
function_analyses: list[Any] = field(default_factory=list)
+ # This file's per-line blame index (``git_indexer.function_blame.BlameIndex``,
+ # typed ``Any`` to avoid importing the ingestion layer into the model). A
+ # shared read-only reference the engine already materialised for the
+ # function-level biomarkers; Split File projects each top-level symbol's line
+ # range through it for a co-change "keep-together" edge. ``None`` (or an empty
+ # index) is the documented "no signal" outcome — the detector degrades to its
+ # call/import signals only.
+ blame_index: Any = None
@dataclass
diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/split_file.py b/packages/core/src/repowise/core/analysis/health/refactoring/split_file.py
index b8e7c0560..980636ac4 100644
--- a/packages/core/src/repowise/core/analysis/health/refactoring/split_file.py
+++ b/packages/core/src/repowise/core/analysis/health/refactoring/split_file.py
@@ -17,11 +17,18 @@ Algorithm (all signals from ``ctx.graph`` for v1):
functions roll up into their owner.
- **Edges (weighted, strongest -> weakest):**
1. direct intra-file call (A calls B) -> ``w = 3`` — they belong together;
- 2. shared local helper (A and B both call a third local symbol) ->
+ 2. co-change affinity (A and B's line ranges are touched by overlapping
+ commits) -> ``w = 2 x Jaccard(commits_a, commits_b)`` — "these always
+ change together, keep them together". Read from the file's blame index
+ at zero index cost; absent when no ``blame_index`` is threaded in.
+ 3. shared local helper (A and B both call a third local symbol) ->
``w = 2`` per shared helper — cohesion without a direct A<->B edge;
- 3. cross-module affinity proxy (A and B both call into the same *foreign*
- module) -> ``w = 1`` per shared module — the graph-derived stand-in for
- "same responsibility".
+ 4. shared external-import surface (A and B lean on the same *imported
+ names*) -> ``w = 1`` per shared imported name — true "same dependency
+ surface", recovered from the file's ``imports`` edges at zero index cost.
+ Falls back to the older cross-module affinity proxy (A and B both call
+ into the same *foreign module* -> ``w = 1`` per shared module) when a
+ symbol's imported-name surface is empty (lightweight-tier languages).
- **Partition:** community detection (Leiden via the shared
``communities`` module, Louvain fallback) on this weighted subgraph. A
shared-utility *spine* (a local helper most symbols call) is collapsed
@@ -49,7 +56,24 @@ from .registry import RefactoringDetector, effort_bucket, register
# Edge weights over the intra-file symbol graph (see module docstring).
_DIRECT_CALL_WEIGHT = 3.0
+# Co-change weight is scaled by the commit-set Jaccard (0..1), so it peaks at
+# this value for two symbols that always change together and decays toward the
+# floor below. Tunable on dogfood evidence.
+_COCHANGE_WEIGHT = 2.0
+# Only symbols whose commit sets overlap by at least this Jaccard get a
+# co-change edge. Same-file symbols share commit history freely, so an unfloored
+# (or low-floored) edge densifies the graph into a uniform glue that depresses
+# the partition modularity without sharpening any group. "These always change
+# together" means sharing the majority of their history, so the floor sits at
+# half. Dogfood on .repowise: an unfloored edge dropped mean modularity 0.42 ->
+# 0.40 and cut high-confidence splits from 14 to 6; at 0.5 the mean returns to
+# 0.42 (within noise of the call-only baseline) while co-change still reshapes
+# the strongly-coupled files.
+_COCHANGE_MIN_JACCARD = 0.5
_SHARED_HELPER_WEIGHT = 2.0
+# Per shared imported name (the true dependency-surface signal) and, as the
+# fallback when a symbol has no imported-name surface, per shared foreign module.
+_SHARED_IMPORT_WEIGHT = 1.0
_SHARED_MODULE_WEIGHT = 1.0
# Floors — gate on decomposability, not size, but a tiny or short file is
@@ -292,7 +316,7 @@ class SplitFileDetector(RefactoringDetector):
):
return []
- local_pairs, callers_of, foreign_of = self._intra_file_signals(
+ local_pairs, callers_of, foreign_of, imports_of = self._intra_file_signals(
graph, ctx, defined, owner_of, node_set
)
@@ -308,7 +332,15 @@ class SplitFileDetector(RefactoringDetector):
if len(cluster_nodes) < _MIN_SYMBOLS // 2:
return []
- wg = self._build_weighted_graph(cluster_nodes, spine, local_pairs, callers_of, foreign_of)
+ wg, signal_counts = self._build_weighted_graph(
+ cluster_nodes,
+ spine,
+ local_pairs,
+ callers_of,
+ foreign_of,
+ imports_of,
+ commits_of=self._commit_sets(ctx, defined, cluster_nodes),
+ )
if wg is None:
return []
@@ -359,6 +391,17 @@ class SplitFileDetector(RefactoringDetector):
"modularity": round(modularity, 3),
"intra_edges": intra_edges,
"cut_edges": cut_edges,
+ # Optional: present only when the richer signals fired, so
+ # the surface layers can show "kept together by co-change /
+ # shared imports" without breaking older plan records.
+ **{
+ k: v
+ for k, v in (
+ ("cochange_edges", signal_counts["cochange_edges"]),
+ ("import_edges", signal_counts["import_edges"]),
+ )
+ if v
+ },
},
impact_delta=0.0,
effort_bucket=effort_bucket(ctx.nloc),
@@ -416,13 +459,21 @@ class SplitFileDetector(RefactoringDetector):
defined: dict[str, dict],
owner_of: dict[str, str],
node_set: set[str],
- ) -> tuple[set[tuple[str, str]], dict[str, set[str]], dict[str, set[str]]]:
- """Walk ``calls`` edges once and derive the three cohesion signals:
- direct local-call pairs, who-calls-each-local-helper, and each node's
- set of foreign module labels."""
+ ) -> tuple[
+ set[tuple[str, str]],
+ dict[str, set[str]],
+ dict[str, set[str]],
+ dict[str, set[str]],
+ ]:
+ """Walk ``calls`` edges once and derive the cohesion signals: direct
+ local-call pairs, who-calls-each-local-helper, each node's set of
+ foreign module labels (the affinity-proxy fallback), and each node's
+ external-import surface (the imported names it leans on, read off the
+ file's ``imports`` edges)."""
local_pairs: set[tuple[str, str]] = set()
callers_of: dict[str, set[str]] = defaultdict(set)
foreign_of: dict[str, set[str]] = defaultdict(set)
+ imports_of: dict[str, set[str]] = defaultdict(set)
for sid, owner in owner_of.items():
if owner not in node_set:
@@ -442,7 +493,55 @@ class SplitFileDetector(RefactoringDetector):
if fpath and fpath != ctx.file_path:
label = ctx.module_map.get(fpath) or fpath
foreign_of[owner].add(label)
- return local_pairs, callers_of, foreign_of
+ # The imported names this file pulls from the callee's
+ # file approximate the dependency surface this symbol
+ # actually leans on (file-edge granularity; the precise
+ # per-call binding-name variant is a deferred index
+ # change). Empty on lightweight-tier languages -> the
+ # foreign-module proxy carries the signal instead.
+ names = self._imported_names(graph, ctx.file_path, fpath)
+ if names:
+ imports_of[owner] |= names
+ return local_pairs, callers_of, foreign_of, imports_of
+
+ @staticmethod
+ def _imported_names(graph: Any, src_file: str, dst_file: str) -> set[str]:
+ """Imported names on the ``imports`` edge ``src_file -> dst_file`` (the
+ ``imported_names`` payload ``builder.py`` aggregates). Empty when the
+ edge is missing or carries no names (e.g. lightweight-tier languages)."""
+ edata = graph.get_edge_data(src_file, dst_file)
+ if not edata or edata.get("edge_type") != "imports":
+ return set()
+ return {n for n in edata.get("imported_names", ()) if n}
+
+ def _commit_sets(
+ self,
+ ctx: RefactoringContext,
+ defined: dict[str, dict],
+ cluster_nodes: list[str],
+ ) -> dict[str, set[str]]:
+ """Project each node's ``(start_line, end_line)`` through the file's
+ blame index to its set of touching commits — the raw material for the
+ co-change edge. Empty (the documented "no signal" outcome) when no
+ ``blame_index`` was threaded in or the index has no coverage."""
+ idx = ctx.blame_index
+ if idx is None or not getattr(idx, "lines", None):
+ return {}
+ try:
+ from repowise.core.ingestion.git_indexer.function_blame import (
+ distinct_commits_in_range,
+ )
+ except Exception:
+ return {}
+ out: dict[str, set[str]] = {}
+ for nid in cluster_nodes:
+ data = defined.get(nid, {})
+ start, end = data.get("start_line"), data.get("end_line")
+ if isinstance(start, int) and isinstance(end, int) and end >= start:
+ commits = distinct_commits_in_range(idx, start, end)
+ if commits:
+ out[nid] = commits
+ return out
def _build_weighted_graph(
self,
@@ -451,11 +550,15 @@ class SplitFileDetector(RefactoringDetector):
local_pairs: set[tuple[str, str]],
callers_of: dict[str, set[str]],
foreign_of: dict[str, set[str]],
- ) -> Any:
+ imports_of: dict[str, set[str]],
+ *,
+ commits_of: dict[str, set[str]],
+ ) -> tuple[Any, dict[str, int]]:
+ counts = {"cochange_edges": 0, "import_edges": 0}
try:
import networkx as nx
except Exception:
- return None
+ return None, counts
weights: Counter[tuple[str, str]] = Counter()
@@ -467,7 +570,21 @@ class SplitFileDetector(RefactoringDetector):
# 1. direct intra-file call
for a, b in local_pairs:
_add(a, b, _DIRECT_CALL_WEIGHT)
- # 2. shared local helper (callers of a common, non-spine local symbol)
+ # 2. co-change affinity (overlapping commit sets keep symbols together)
+ cc_nodes = sorted(n for n in commits_of if n not in spine)
+ for i in range(len(cc_nodes)):
+ for j in range(i + 1, len(cc_nodes)):
+ a, b = cc_nodes[i], cc_nodes[j]
+ ca, cb = commits_of[a], commits_of[b]
+ inter = len(ca & cb)
+ if not inter:
+ continue
+ jaccard = inter / len(ca | cb)
+ if jaccard < _COCHANGE_MIN_JACCARD:
+ continue
+ _add(a, b, _COCHANGE_WEIGHT * jaccard)
+ counts["cochange_edges"] += 1
+ # 3. shared local helper (callers of a common, non-spine local symbol)
for callee, callers in callers_of.items():
if callee in spine:
continue
@@ -475,19 +592,27 @@ class SplitFileDetector(RefactoringDetector):
for i in range(len(members)):
for j in range(i + 1, len(members)):
_add(members[i], members[j], _SHARED_HELPER_WEIGHT)
- # 3. cross-module affinity proxy (shared foreign modules)
+ # 4. shared external-import surface, with the foreign-module proxy as
+ # the fallback when a symbol carries no imported-name surface.
for i in range(len(cluster_nodes)):
for j in range(i + 1, len(cluster_nodes)):
a, b = cluster_nodes[i], cluster_nodes[j]
- shared = foreign_of.get(a, set()) & foreign_of.get(b, set())
- if shared:
- _add(a, b, _SHARED_MODULE_WEIGHT * len(shared))
+ a_names, b_names = imports_of.get(a), imports_of.get(b)
+ if a_names and b_names:
+ shared_names = a_names & b_names
+ if shared_names:
+ _add(a, b, _SHARED_IMPORT_WEIGHT * len(shared_names))
+ counts["import_edges"] += 1
+ continue
+ shared_mod = foreign_of.get(a, set()) & foreign_of.get(b, set())
+ if shared_mod:
+ _add(a, b, _SHARED_MODULE_WEIGHT * len(shared_mod))
wg = nx.Graph()
wg.add_nodes_from(sorted(cluster_nodes))
for (a, b), w in weights.items():
wg.add_edge(a, b, weight=w)
- return wg
+ return wg, counts
@staticmethod
def _modularity(wg: Any, groups_map: dict[int, list[str]]) -> float:
diff --git a/tests/unit/health/test_refactoring_split_file.py b/tests/unit/health/test_refactoring_split_file.py
index 1eed4c6f7..fd2f00c2c 100644
--- a/tests/unit/health/test_refactoring_split_file.py
+++ b/tests/unit/health/test_refactoring_split_file.py
@@ -21,6 +21,7 @@ from repowise.core.analysis.health.refactoring.split_file import (
_dominant_token,
_shim_required,
)
+from repowise.core.ingestion.git_indexer.function_blame import BlameIndex
def _add_func(g: nx.DiGraph, file_path: str, name: str, *, start: int = 1, end: int = 30) -> str:
@@ -64,9 +65,57 @@ def _call(g: nx.DiGraph, src: str, dst: str) -> None:
def _ctx(
- g: nx.DiGraph, file_path: str, *, nloc: int = 600, language: str = "python"
+ g: nx.DiGraph,
+ file_path: str,
+ *,
+ nloc: int = 600,
+ language: str = "python",
+ blame_index: BlameIndex | None = None,
+ module_map: dict[str, str] | None = None,
) -> RefactoringContext:
- return RefactoringContext(file_path=file_path, language=language, nloc=nloc, graph=g)
+ return RefactoringContext(
+ file_path=file_path,
+ language=language,
+ nloc=nloc,
+ graph=g,
+ blame_index=blame_index,
+ module_map=module_map or {},
+ )
+
+
+def _add_foreign_call(g: nx.DiGraph, src: str, foreign_file: str, callee_name: str) -> None:
+ """Make *src* (a local symbol id) call a symbol living in *foreign_file*."""
+ if foreign_file not in g:
+ g.add_node(foreign_file, node_type="file")
+ cid = f"{foreign_file}::{callee_name}"
+ if cid not in g:
+ g.add_node(cid, node_type="symbol", kind="function", name=callee_name, file_path=foreign_file)
+ g.add_edge(src, cid, edge_type="calls")
+
+
+def _imports(g: nx.DiGraph, src_file: str, dst_file: str, names: list[str]) -> None:
+ g.add_edge(src_file, dst_file, edge_type="imports", imported_names=list(names))
+
+
+def _blame_index(ranges: list[tuple[int, int, str]]) -> BlameIndex:
+ """Blame index where every line in ``[start, end]`` is attributed to ``sha``."""
+ lines: dict[int, tuple[str, int]] = {}
+ for start, end, sha in ranges:
+ for ln in range(start, end + 1):
+ lines[ln] = (sha, 0)
+ return BlameIndex(lines=lines, authors={})
+
+
+def _blame_from_sets(node_shas: dict[int, list[str]]) -> BlameIndex:
+ """Blame index for the ``_disconnected_blocks`` layout: ``fn_i`` spans lines
+ ``10*i+1..10*i+10``; spread its list of shas across those lines so
+ ``distinct_commits_in_range`` recovers exactly that set."""
+ lines: dict[int, tuple[str, int]] = {}
+ for i, shas in node_shas.items():
+ base = 10 * i + 1
+ for offset in range(10):
+ lines[base + offset] = (shas[offset % len(shas)], 0)
+ return BlameIndex(lines=lines, authors={})
def _detect(g: nx.DiGraph, file_path: str, **kw) -> list:
@@ -239,3 +288,109 @@ def test_shim_required_helper():
assert _shim_required("python") is True
assert _shim_required("typescript") is True
assert _shim_required(None) is True
+
+
+def _disconnected_blocks(file_path: str = "big.py") -> nx.DiGraph:
+ """Eight top-level functions with NO call edges and distinct 10-line ranges.
+ On its own this yields no split (every node is its own community); the
+ co-change / import-name signals are what create the partition."""
+ g = nx.DiGraph()
+ for i in range(8):
+ _add_func(g, file_path, f"fn_{i}", start=10 * i + 1, end=10 * i + 10)
+ return g
+
+
+def test_cochange_edge_groups_commit_coupled_symbols():
+ # No call edges; the only cohesion is git co-change. Lines of fn_0..3 are
+ # all touched by commit "ca", fn_4..7 by "cb" -> two co-change cliques.
+ g = _disconnected_blocks()
+ blame = _blame_index(
+ [(10 * i + 1, 10 * i + 10, "ca" if i < 4 else "cb") for i in range(8)]
+ )
+ out = _detect(g, "big.py", blame_index=blame)
+ assert len(out) == 1
+ s = out[0]
+ assert s.evidence["group_count"] == 2
+ assert s.evidence["cochange_edges"] > 0
+ assert "import_edges" not in s.evidence # no foreign calls in this fixture
+ groups = [set(grp["symbols"]) for grp in s.plan["groups"]]
+ block_a = {f"fn_{i}" for i in range(4)}
+ block_b = {f"fn_{i}" for i in range(4, 8)}
+ assert any(grp == block_a for grp in groups)
+ assert any(grp == block_b for grp in groups)
+
+
+def test_cochange_absent_without_blame_index():
+ # Same graph, no blame index -> no co-change edges -> nothing to partition.
+ assert _detect(_disconnected_blocks(), "big.py") == []
+
+
+def test_cochange_floor_suppresses_weak_coupling():
+ # Each symbol shares only a minority (Jaccard well below 0.5) of its commit
+ # set with the others -> incidental coupling, below the floor -> no edges ->
+ # nothing to partition. Guards against same-file co-change densifying the
+ # graph into a uniform glue.
+ g = _disconnected_blocks()
+ blame = _blame_from_sets(
+ {i: ["shared", f"own_{i}_a", f"own_{i}_b", f"own_{i}_c"] for i in range(8)}
+ )
+ # Every symbol's set is {shared, own_i_a, own_i_b, own_i_c}; any two overlap
+ # on just {shared} -> Jaccard = 1/7 < 0.5.
+ assert _detect(g, "big.py", blame_index=blame) == []
+
+
+def test_import_name_signal_separates_distinct_dependencies():
+ # fn_0..3 lean on ext/a.py, fn_4..7 on ext/b.py. Both foreign files map to
+ # the SAME module label, so the old foreign-module proxy would glue all
+ # eight together; the imported-name surface (distinct names per file)
+ # correctly keeps the two dependency clusters apart.
+ g = _disconnected_blocks()
+ for i in range(4):
+ _add_foreign_call(g, f"big.py::fn_{i}", "ext/a.py", "alpha_dep")
+ for i in range(4, 8):
+ _add_foreign_call(g, f"big.py::fn_{i}", "ext/b.py", "beta_dep")
+ _imports(g, "big.py", "ext/a.py", ["alpha_dep"])
+ _imports(g, "big.py", "ext/b.py", ["beta_dep"])
+ module_map = {"ext/a.py": "extpkg", "ext/b.py": "extpkg"}
+ out = _detect(g, "big.py", module_map=module_map)
+ assert len(out) == 1
+ s = out[0]
+ assert s.evidence["group_count"] == 2
+ assert s.evidence["import_edges"] > 0
+ groups = [set(grp["symbols"]) for grp in s.plan["groups"]]
+ assert any(grp == {f"fn_{i}" for i in range(4)} for grp in groups)
+ assert any(grp == {f"fn_{i}" for i in range(4, 8)} for grp in groups)
+
+
+def test_foreign_module_proxy_is_used_when_imported_names_empty():
+ # Lightweight-tier shape: foreign calls but the import edges carry no names.
+ # The detector degrades to the foreign-module affinity proxy (today's
+ # behavior) -> the two distinct-module clusters still separate.
+ g = _disconnected_blocks()
+ for i in range(4):
+ _add_foreign_call(g, f"big.py::fn_{i}", "ext/a.py", "alpha_dep")
+ for i in range(4, 8):
+ _add_foreign_call(g, f"big.py::fn_{i}", "ext/b.py", "beta_dep")
+ module_map = {"ext/a.py": "moda", "ext/b.py": "modb"}
+ out = _detect(g, "big.py", module_map=module_map)
+ assert len(out) == 1
+ s = out[0]
+ assert s.evidence["group_count"] == 2
+ assert "import_edges" not in s.evidence # proxy fired, not the name signal
+
+
+def test_signals_are_deterministic():
+ g = _disconnected_blocks()
+ blame = _blame_index(
+ [(10 * i + 1, 10 * i + 10, "ca" if i < 4 else "cb") for i in range(8)]
+ )
+ first = _detect(g, "big.py", blame_index=blame)
+ second = _detect(g, "big.py", blame_index=blame)
+ assert first[0].plan["groups"] == second[0].plan["groups"]
+ assert first[0].evidence == second[0].evidence
+
+
+def test_empty_blame_index_is_silent():
+ # An empty index (the documented "no signal" outcome) must not raise and
+ # must not invent co-change edges.
+ assert _detect(_disconnected_blocks(), "big.py", blame_index=BlameIndex()) == []