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
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.pyindex 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, suggestionsdiff --git a/packages/core/src/repowise/core/analysis/health/refactoring/models.py b/packages/core/src/repowise/core/analysis/health/refactoring/models.pyindex 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 splitsymbols 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@dataclassdiff --git a/packages/core/src/repowise/core/analysis/health/refactoring/split_file.py b/packages/core/src/repowise/core/analysis/health/refactoring/split_file.pyindex 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. Ashared-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 fpathforeign_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 outdef _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 nxexcept Exception:- return None+ return None, countsweights: Counter[tuple[str, str]] = Counter()@@ -467,7 +570,21 @@ class SplitFileDetector(RefactoringDetector):# 1. direct intra-file callfor 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@staticmethoddef _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.pyindex 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 BlameIndexdef _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 Trueassert _shim_required("typescript") is Trueassert _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()) == []