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): add Split File detector for module decomposition (#607)
Raghav Chamadiyaf3cb3b271836
diff --git a/packages/cli/src/repowise/cli/commands/health_cmd.py b/packages/cli/src/repowise/cli/commands/health_cmd.pyindex 7f6af1751..7dbe987a2 100644--- a/packages/cli/src/repowise/cli/commands/health_cmd.py+++ b/packages/cli/src/repowise/cli/commands/health_cmd.py@@ -673,6 +673,7 @@ def _render_refactoring_targets(_render_extract_helper_plans_md(ranked_plans)_render_move_method_plans_md(ranked_plans)_render_break_cycle_plans_md(ranked_plans)+ _render_split_file_plans_md(ranked_plans)returntable = Table(title=f"Refactoring targets ({len(targets)})")@@ -696,6 +697,7 @@ def _render_refactoring_targets(_render_extract_helper_plans_console(ranked_plans)_render_move_method_plans_console(ranked_plans)_render_break_cycle_plans_console(ranked_plans)+ _render_split_file_plans_console(ranked_plans)def _render_extract_class_plans_console(plans: list[dict]) -> None:@@ -852,6 +854,58 @@ def _render_break_cycle_plans_md(plans: list[dict]) -> None:click.echo(f" - invert {e['from']} -> {e['to']}")+def _render_split_file_plans_console(plans: list[dict]) -> None:+ """Print the concrete Split File (module decomposition) plans below the table."""+ sf_plans = [p for p in plans if p["refactoring_type"] == "split_file"]+ if not sf_plans:+ return+ console.print(f"\n[bold]Split File plans ({len(sf_plans)})[/bold]")+ for p in sf_plans:+ pl = p["plan"]+ ev = p["evidence"]+ groups = pl.get("groups", [])+ br = p["blast_radius"]+ shim = " [dim]+shim[/dim]" if pl.get("shim_required") else ""+ console.print(+ f"\n[cyan]{p['file_path']}[/cyan] — "+ f"{ev.get('symbol_count')} symbols, {ev.get('file_nloc')} NLOC, "+ f"modularity {ev.get('modularity')} → split into {len(groups)} files{shim} "+ f"[dim](effort {p['effort_bucket']}, {p['confidence']} confidence, "+ f"{br.get('import_rewrites', 0)} import rewrites in "+ f"{br.get('dependent_count', 0)} files)[/dim]"+ )+ for i, g in enumerate(groups, 1):+ console.print(+ f" [bold]{i}.[/bold] [green]{g.get('suggested_file')}[/green]: "+ f"{', '.join(g.get('symbols', []))}"+ )+ residual = pl.get("residual")+ if residual and residual.get("symbols"):+ console.print(f" [dim]core (shared):[/dim] {', '.join(residual['symbols'])}")+++def _render_split_file_plans_md(plans: list[dict]) -> None:+ sf_plans = [p for p in plans if p["refactoring_type"] == "split_file"]+ if not sf_plans:+ return+ click.echo("\n## Split File plans\n")+ for p in sf_plans:+ pl = p["plan"]+ ev = p["evidence"]+ groups = pl.get("groups", [])+ click.echo(+ f"- **{p['file_path']}** — {ev.get('symbol_count')} symbols, "+ f"modularity {ev.get('modularity')}, split into {len(groups)} files:"+ )+ for i, g in enumerate(groups, 1):+ click.echo(+ f" {i}. `{g.get('suggested_file')}`: {', '.join(g.get('symbols', []))}"+ )+ residual = pl.get("residual")+ if residual and residual.get("symbols"):+ click.echo(f" - core (shared): {', '.join(residual['symbols'])}")++def _render_trend(repo_path: object, *, fmt: str) -> None:"""Print the last 10 health snapshots straight from SQLite history.diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/__init__.py b/packages/core/src/repowise/core/analysis/health/refactoring/__init__.pyindex 4b40d254e..c20022243 100644--- a/packages/core/src/repowise/core/analysis/health/refactoring/__init__.py+++ b/packages/core/src/repowise/core/analysis/health/refactoring/__init__.py@@ -18,6 +18,7 @@ from . import (extract_class, # noqa: F401 (import-for-side-effect)extract_helper, # noqa: F401 (import-for-side-effect)move_method, # noqa: F401 (import-for-side-effect)+ split_file, # noqa: F401 (import-for-side-effect))from .graph_signals import build_file_scc_indexfrom .models import (diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/models.py b/packages/core/src/repowise/core/analysis/health/refactoring/models.pyindex b536796e1..b01874d11 100644--- a/packages/core/src/repowise/core/analysis/health/refactoring/models.py+++ b/packages/core/src/repowise/core/analysis/health/refactoring/models.py@@ -50,6 +50,21 @@ For Break Cycle:"cut_count": int}`` — the SCC size, total intra-cycle edges, and cut size.- ``blast_radius`` = ``{"files": [...], "file_count": int}`` — every file inthe cycle (breaking it is a multi-file change).++For Split File:++- ``plan`` = ``{"groups": [{"name": str | None, "symbols": [str, ...],+ "suggested_file": str}], "residual": {"symbols": [...]} | None,+ "shim_required": bool}`` — the cohesive groups the file should split into+ (each with a suggested filename), the shared-utility ``core`` left behind,+ and whether a back-compat re-export shim is needed (false for same-package+ 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.+- ``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."""from __future__ import annotationsdiff --git a/packages/core/src/repowise/core/analysis/health/refactoring/split_file.py b/packages/core/src/repowise/core/analysis/health/refactoring/split_file.pynew file mode 100644index 000000000..b8e7c0560--- /dev/null+++ b/packages/core/src/repowise/core/analysis/health/refactoring/split_file.py@@ -0,0 +1,636 @@+"""Split File detector — the file-level analog of Extract Class.++Extract Class partitions a *class* by its methods' cohesion (LCOM4+components). Split File partitions a *file* by its top-level symbols'+cohesion: a 2,000-line module of 40 loosely-related top-level functions is+the single most common thing developers stare at and call "needs splitting",+yet no class-internal or edge-level refactoring fires on it.++The detector is language-agnostic — it reads only the already-built graph+(``defines`` / ``calls`` edges on ``ctx.graph``), exactly like Move Method+and Break Cycle. No per-language module, no re-parse, no indexing change.++Algorithm (all signals from ``ctx.graph`` for v1):++- **Nodes:** the file's top-level symbols. A class collapses to one node+ (its methods roll up into it); each top-level function is a node; nested+ 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) ->+ ``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".+- **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+ into a residual ``core`` group before clustering so it does not glue+ everything together.+- **The decomposability gate (the precision story):** emit a suggestion only+ when the partition has **high modularity** — the inter-group cut is small+ relative to intra-group cohesion. A big-but-cohesive file (one giant state+ machine, a generated registry) yields a low-modularity partition and+ produces *nothing*. Better ten great splits than two hundred maybes.++Output is "split into these N files; here are the import edits in the M+dependent files" — the blast-radius column nobody else has. Splitting Go+files in the same package is near-zero blast (no import edits); Python/TS+need a back-compat re-export shim, surfaced as ``shim_required``.+"""++from __future__ import annotations++from collections import Counter, defaultdict+from typing import Any++from .models import RefactoringContext, RefactoringSuggestion+from .registry import RefactoringDetector, effort_bucket, register++# Edge weights over the intra-file symbol graph (see module docstring).+_DIRECT_CALL_WEIGHT = 3.0+_SHARED_HELPER_WEIGHT = 2.0+_SHARED_MODULE_WEIGHT = 1.0++# Floors — gate on decomposability, not size, but a tiny or short file is+# never worth a split suggestion regardless of how it partitions.+_MIN_FILE_NLOC = 300+_MIN_SYMBOLS = 8++# A split needs at least this many substantive resulting groups (a lone helper+# split out is not worth a suggestion). A group is substantive at >= this many+# symbols; smaller communities fold into the residual ``core``.+_MIN_GROUPS = 2+_MIN_GROUP_SYMBOLS = 2++# The decomposability gate: the weighted partition must separate this cleanly+# (Newman modularity over the weighted graph). Tuned toward suppression — a+# cohesive big file scores well below this and yields nothing. Tunable on+# dogfood evidence.+_MIN_MODULARITY = 0.30++# Route single-dominant-class files to Extract Class instead: if one class is+# more than this fraction of the file, splitting the file *is* splitting that+# class, which Extract Class already covers. The two compose, never overlap.+_DOMINANT_CLASS_FRACTION = 0.70++# A local symbol called by at least this fraction of the file's symbols (and+# by at least 3 of them) is a shared-utility spine: it connects every group,+# so it is pulled into the residual ``core`` rather than gluing the partition.+_SPINE_CALLER_FRACTION = 0.6+_SPINE_MIN_CALLERS = 3++# Confidence: a very clean separation is high; a marginal-but-passing one is+# medium (still worth surfacing, ranks lower).+_HIGH_CONFIDENCE_MODULARITY = 0.45+++def _is_test_path(path: str) -> bool:+ """Conservative test-file check (mirrors the other detectors)."""+ p = path.lower().replace("\\", "/")+ segments = p.split("/")+ if any(seg in ("test", "tests", "__tests__") for seg in segments[:-1]):+ return True+ base = segments[-1]+ return (+ base in ("tests.py", "test.py", "conftest.py")+ or base.startswith("test_")+ or base.endswith(+ (+ "_test.py",+ "_test.go",+ ".test.ts",+ ".test.tsx",+ ".test.js",+ ".test.mts",+ ".test.cts",+ ".spec.ts",+ ".spec.js",+ ".spec.mts",+ ".spec.cts",+ )+ )+ )+++def _is_generated_path(path: str) -> bool:+ """Generated / vendored / append-only code: a migration or a barrel+ re-export file must stay self-contained, so it is never a split target."""+ p = path.lower().replace("\\", "/")+ base = p.rsplit("/", 1)[-1]+ return (+ "/migrations/" in p+ or "/alembic/versions/" in p+ or "/node_modules/" in p+ or "/vendor/" in p+ or "/__generated__/" in p+ or ".generated." in base+ or base.endswith(".min.js")+ # Barrel / package-init re-export files: nothing of substance to split.+ or base in ("__init__.py", "index.ts", "index.js", "mod.rs")+ )+++def _is_skippable_path(path: str) -> bool:+ return _is_test_path(path) or _is_generated_path(path)+++def _node_span(data: dict) -> int:+ start = data.get("start_line")+ end = data.get("end_line")+ if isinstance(start, int) and isinstance(end, int) and end >= start:+ return end - start + 1+ return 0+++def _basename(path: str) -> str:+ return path.replace("\\", "/").rsplit("/", 1)[-1]+++def _split_stem_ext(path: str) -> tuple[str, str]:+ base = _basename(path)+ if "." in base:+ stem, ext = base.rsplit(".", 1)+ return stem, "." + ext+ return base, ""+++def _directory(path: str) -> str:+ norm = path.replace("\\", "/")+ return norm.rsplit("/", 1)[0] if "/" in norm else ""+++# Generic verbs / connectives that name no responsibility — skipped when+# voting for a group's name so ``get_repo`` / ``build_story`` don't all read as+# "get" / "build".+_NAME_STOPWORDS = frozenset(+ {+ "get",+ "set",+ "build",+ "make",+ "run",+ "load",+ "save",+ "read",+ "write",+ "create",+ "update",+ "fetch",+ "handle",+ "compute",+ "render",+ "the",+ "and",+ "for",+ "with",+ "into",+ "from",+ "all",+ "new",+ "raw",+ }+)+++def _dominant_token(names: list[str]) -> str:+ """A group's name by *plurality vote* over its symbols' name tokens.++ The most frequent meaningful ``snake_case`` token across the group wins+ (``filter_dicts``, ``filter_path``, ``is_excluded`` -> ``filter``). A+ plurality is far more robust than a shared prefix, which one outlier kills.+ Stopword verbs and short tokens are ignored; each symbol votes for a token+ at most once. Returns ``""`` when no token is shared by >= 2 symbols.+ """+ if len(names) < 2:+ return ""+ counts: Counter[str] = Counter()+ for name in names:+ seen: set[str] = set()+ for tok in name.lower().lstrip("_").split("_"):+ if len(tok) >= 4 and tok not in _NAME_STOPWORDS and not tok.isdigit():+ seen.add(tok)+ counts.update(seen)+ if not counts:+ return ""+ token, votes = min(counts.items(), key=lambda kv: (-kv[1], kv[0]))+ return token if votes >= 2 else ""+++def _partition_weighted(wg: Any) -> dict[str, int]:+ """Community assignment over the weighted intra-file graph *wg*.++ Reuses the repo's shared Leiden/Louvain partitioner (seeded, deterministic)+ and degrades to connected components on any failure or when *wg* has no+ edges. Every node of *wg* is always assigned.+ """+ nodes = sorted(wg.nodes())+ if wg.number_of_edges() == 0:+ return {n: i for i, n in enumerate(nodes)}++ assignment: dict[str, int] = {}+ try:+ from repowise.core.analysis.communities import _partition++ raw, _algo = _partition(wg)+ assignment = {n: int(c) for n, c in raw.items()}+ except Exception:+ assignment = {}++ if not assignment:+ # Connected-components fallback — fully deterministic.+ try:+ import networkx as nx++ for cid, comp in enumerate(nx.connected_components(wg)):+ for n in comp:+ assignment[n] = cid+ except Exception:+ return {n: i for i, n in enumerate(nodes)}++ # Any node the partitioner dropped (Leiden can omit isolates) gets its own+ # community so it lands in the residual rather than vanishing.+ next_cid = max(assignment.values(), default=-1) + 1+ for n in nodes:+ if n not in assignment:+ assignment[n] = next_cid+ next_cid += 1+ return assignment+++@register+class SplitFileDetector(RefactoringDetector):+ name = "split_file"++ def detect(self, ctx: RefactoringContext) -> list[RefactoringSuggestion]:+ graph = ctx.graph+ if graph is None or _is_skippable_path(ctx.file_path):+ return []+ if ctx.nloc < _MIN_FILE_NLOC:+ return []++ defined = self._defined_symbols(graph, ctx.file_path)+ owner_of = {sid: self._resolve_owner(ctx.file_path, sid, defined) for sid in defined}+ node_ids = sorted(+ {+ owner+ for owner in owner_of.values()+ if defined.get(owner, {}).get("kind") in ("class", "function")+ and not defined.get(owner, {}).get("parent_name")+ }+ )+ if len(node_ids) < _MIN_SYMBOLS:+ return []++ # Single-dominant-class router: that is an Extract Class candidate.+ node_set = set(node_ids)+ for nid in node_ids:+ data = defined[nid]+ if (+ data.get("kind") == "class"+ and _node_span(data) > _DOMINANT_CLASS_FRACTION * ctx.nloc+ ):+ return []++ local_pairs, callers_of, foreign_of = self._intra_file_signals(+ graph, ctx, defined, owner_of, node_set+ )++ # Collapse the shared-utility spine into the residual ``core`` so it+ # does not connect every group (the under-split risk).+ n = len(node_ids)+ spine = {+ callee+ for callee, callers in callers_of.items()+ if len(callers) >= max(_SPINE_MIN_CALLERS, _SPINE_CALLER_FRACTION * n)+ }+ cluster_nodes = [nid for nid in node_ids if nid not in spine]+ if len(cluster_nodes) < _MIN_SYMBOLS // 2:+ return []++ wg = self._build_weighted_graph(cluster_nodes, spine, local_pairs, callers_of, foreign_of)+ if wg is None:+ return []++ assignment = _partition_weighted(wg)+ groups_map: dict[int, list[str]] = defaultdict(list)+ for node, cid in assignment.items():+ groups_map[cid].append(node)++ modularity = self._modularity(wg, groups_map)+ substantive = sorted(+ (+ sorted(members)+ for members in groups_map.values()+ if len(members) >= _MIN_GROUP_SYMBOLS+ ),+ key=lambda members: (-len(members), members[0]),+ )+ if len(substantive) < _MIN_GROUPS or modularity < _MIN_MODULARITY:+ return []++ # Residual = the spine + every symbol not in a substantive group.+ placed = {m for g in substantive for m in g}+ residual_ids = sorted(+ spine | {nid for nid in node_ids if nid not in placed and nid not in spine}+ )++ intra_edges, cut_edges = self._edge_cut(wg, assignment)+ groups, residual = self._shape_groups(ctx, defined, foreign_of, substantive, residual_ids)+ blast = self._blast_radius(graph, ctx, defined, shim_required=_shim_required(ctx.language))++ confidence = "high" if modularity >= _HIGH_CONFIDENCE_MODULARITY else "medium"+ return [+ RefactoringSuggestion(+ refactoring_type=self.name,+ file_path=ctx.file_path,+ target_symbol=f"{_basename(ctx.file_path)} -> {len(groups)} files",+ line_start=None,+ line_end=None,+ plan={+ "groups": groups,+ "residual": residual,+ "shim_required": _shim_required(ctx.language),+ },+ evidence={+ "file_nloc": ctx.nloc,+ "symbol_count": len(node_ids),+ "group_count": len(groups),+ "modularity": round(modularity, 3),+ "intra_edges": intra_edges,+ "cut_edges": cut_edges,+ },+ impact_delta=0.0,+ effort_bucket=effort_bucket(ctx.nloc),+ blast_radius=blast,+ confidence=confidence,+ source_biomarker="",+ )+ ]++ # ----- graph reading ---------------------------------------------------++ def _defined_symbols(self, graph: Any, file_path: str) -> dict[str, dict]:+ """Symbol nodes defined in *file_path* via ``defines`` edges (with a+ prefix-scan fallback), excluding the synthetic ``__module__`` node."""+ out: dict[str, dict] = {}+ if file_path in graph:+ for _u, v, data in graph.out_edges(file_path, data=True):+ if data.get("edge_type") != "defines":+ continue+ node = graph.nodes[v]+ if node.get("node_type") == "symbol" and node.get("kind") != "module":+ out[v] = node+ if not out:+ prefix = f"{file_path}::"+ for node_id, data in graph.nodes(data=True):+ if (+ data.get("node_type") == "symbol"+ and data.get("kind") != "module"+ and node_id.startswith(prefix)+ ):+ out[node_id] = data+ return out++ def _resolve_owner(self, file_path: str, sid: str, defined: dict[str, dict]) -> str:+ """Walk ``parent_name`` up to the outermost top-level symbol (a method+ rolls up to its class, a nested function to its owner)."""+ cur = sid+ seen: set[str] = set()+ while cur not in seen:+ seen.add(cur)+ data = defined.get(cur, {})+ parent = data.get("parent_name")+ if not parent:+ return cur+ pid = f"{file_path}::{parent}"+ if pid not in defined or pid == cur:+ return cur+ cur = pid+ return cur++ def _intra_file_signals(+ self,+ graph: Any,+ ctx: RefactoringContext,+ 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."""+ local_pairs: set[tuple[str, str]] = set()+ callers_of: dict[str, set[str]] = defaultdict(set)+ foreign_of: dict[str, set[str]] = defaultdict(set)++ for sid, owner in owner_of.items():+ if owner not in node_set:+ continue+ for _u, callee, edata in graph.out_edges(sid, data=True):+ if edata.get("edge_type") != "calls" or callee == sid:+ continue+ if callee in owner_of:+ cowner = owner_of[callee]+ if cowner not in node_set or cowner == owner:+ continue+ local_pairs.add((owner, cowner))+ callers_of[cowner].add(owner)+ else:+ cdata = graph.nodes.get(callee, {})+ fpath = cdata.get("file_path")+ 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++ def _build_weighted_graph(+ self,+ cluster_nodes: list[str],+ spine: set[str],+ local_pairs: set[tuple[str, str]],+ callers_of: dict[str, set[str]],+ foreign_of: dict[str, set[str]],+ ) -> Any:+ try:+ import networkx as nx+ except Exception:+ return None++ weights: Counter[tuple[str, str]] = Counter()++ def _add(a: str, b: str, w: float) -> None:+ if a == b or a in spine or b in spine:+ return+ weights[tuple(sorted((a, b)))] += w++ # 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)+ for callee, callers in callers_of.items():+ if callee in spine:+ continue+ members = sorted(c for c in callers if c not in spine)+ 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)+ 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))++ 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++ @staticmethod+ def _modularity(wg: Any, groups_map: dict[int, list[str]]) -> float:+ if wg.number_of_edges() == 0:+ return 0.0+ try:+ import networkx as nx++ communities = [set(members) for members in groups_map.values()]+ return float(nx.community.modularity(wg, communities, weight="weight"))+ except Exception:+ return 0.0++ @staticmethod+ def _edge_cut(wg: Any, assignment: dict[str, int]) -> tuple[int, int]:+ intra = cut = 0+ for a, b in wg.edges():+ if assignment.get(a) == assignment.get(b):+ intra += 1+ else:+ cut += 1+ return intra, cut++ # ----- output shaping --------------------------------------------------++ def _shape_groups(+ self,+ ctx: RefactoringContext,+ defined: dict[str, dict],+ foreign_of: dict[str, set[str]],+ substantive: list[list[str]],+ residual_ids: list[str],+ ) -> tuple[list[dict], dict | None]:+ stem, ext = _split_stem_ext(ctx.file_path)+ directory = _directory(ctx.file_path)+ used: set[str] = {_basename(ctx.file_path)}+ groups: list[dict] = []+ self_segments = {seg.lower() for seg in ctx.file_path.replace("\\", "/").split("/")}+ self_segments.add(stem.lower())+ for idx, members in enumerate(substantive, 1):+ label = self._group_label(defined, foreign_of, members, self_segments)+ file_stem = label or f"{stem}_part{idx}"+ filename = self._unique_filename(file_stem, ext, used)+ suggested = f"{directory}/{filename}" if directory else filename+ groups.append(+ {+ "name": label or None,+ "symbols": sorted(self._sym_name(defined, m) for m in members),+ "suggested_file": suggested,+ }+ )+ residual = (+ {"symbols": sorted(self._sym_name(defined, m) for m in residual_ids)}+ if residual_ids+ else None+ )+ return groups, residual++ def _group_label(+ self,+ defined: dict[str, dict],+ foreign_of: dict[str, set[str]],+ members: list[str],+ self_segments: set[str],+ ) -> str:+ """Deterministic file name for a group: the dominant shared name token+ first (a plurality vote — the most semantically meaningful signal),+ else a clean dominant foreign-module label, else ``""`` (the caller+ falls back to ``<file>_partN``).++ Dogfood showed the foreign-module label is frequently the repo's own+ package community (carrying a size suffix like ``repowise (290)``),+ which sanitizes to noise like ``repowise__290``. So the name vote+ leads, and a module label is used only when it is a clean identifier+ that is not already part of the file's own path."""+ token = _dominant_token([self._sym_name(defined, m) for m in members])+ if token and token not in self_segments:+ return token++ labels: Counter[str] = Counter()+ for m in members:+ for lab in foreign_of.get(m, set()):+ labels[lab] += 1+ if labels:+ best = min(labels, key=lambda lab: (-labels[lab], lab))+ seg = best.replace("\\", "/").rstrip("/").rsplit("/", 1)[-1]+ seg = _split_stem_ext(seg)[0]+ cleaned = "".join(ch if (ch.isalnum() or ch == "_") else "_" for ch in seg).strip("_")+ # Reject uninformative labels: too short, carrying a community-dedup+ # digit suffix, or naming the file's own namespace (tells you+ # nothing new about the group).+ if (+ len(cleaned) >= 3+ and not any(ch.isdigit() for ch in cleaned)+ and cleaned.lower() not in self_segments+ ):+ return cleaned.lower()+ return token++ @staticmethod+ def _unique_filename(stem: str, ext: str, used: set[str]) -> str:+ candidate = f"{stem}{ext}"+ suffix = 2+ while candidate in used:+ candidate = f"{stem}_{suffix}{ext}"+ suffix += 1+ used.add(candidate)+ return candidate++ @staticmethod+ def _sym_name(defined: dict[str, dict], sid: str) -> str:+ return defined.get(sid, {}).get("name") or sid.rsplit("::", 1)[-1]++ def _blast_radius(+ self, graph: Any, ctx: RefactoringContext, defined: dict[str, dict], *, shim_required: bool+ ) -> dict[str, Any]:+ """External files that reference this file's symbols (call in-edges) or+ import the file. Import rewrites are zero for the same-package Go case+ (no shim, no edits); for shim languages it is the count of dependents+ whose imports the plan's shim preserves but lists for review."""+ dependent_files: set[str] = set()+ for sid in defined:+ for u, _v, edata in graph.in_edges(sid, data=True):+ if edata.get("edge_type") != "calls":+ continue+ f = graph.nodes.get(u, {}).get("file_path")+ if f and f != ctx.file_path:+ dependent_files.add(f)+ if ctx.file_path in graph:+ for u, _v, edata in graph.in_edges(ctx.file_path, data=True):+ if edata.get("edge_type") == "imports" and u != ctx.file_path:+ dependent_files.add(u)+ files = sorted(f for f in dependent_files if f)+ return {+ "dependent_files": files,+ "dependent_count": len(files),+ "import_rewrites": len(files) if shim_required else 0,+ }+++def _shim_required(language: str | None) -> bool:+ """Go files in the same package share a namespace — splitting into sibling+ files needs no import edits. Python/TS/etc. need a back-compat re-export+ shim in the original path to preserve the public API."""+ lang = (language or "").lower()+ return lang not in ("go", "golang")diff --git a/tests/unit/health/test_refactoring_split_file.py b/tests/unit/health/test_refactoring_split_file.pynew file mode 100644index 000000000..1eed4c6f7--- /dev/null+++ b/tests/unit/health/test_refactoring_split_file.py@@ -0,0 +1,241 @@+"""Tests for the Split File refactoring detector (module decomposition).++The detector reads the file's top-level symbols (``defines`` edges) and their+intra-file cohesion (``calls`` edges) off the in-memory graph, builds a+weighted symbol graph, partitions it by modularity, and suggests splitting the+file into the resulting cohesive groups. Fixtures build a tiny NetworkX graph+directly so the symbol set and the call edges — and therefore the expected+partition — are explicit.+"""++from __future__ import annotations++import networkx as nx++from repowise.core.analysis.health.refactoring import (+ RefactoringContext,+ detect_refactorings,+)+from repowise.core.analysis.health.refactoring.split_file import (+ SplitFileDetector,+ _dominant_token,+ _shim_required,+)+++def _add_func(g: nx.DiGraph, file_path: str, name: str, *, start: int = 1, end: int = 30) -> str:+ if file_path not in g:+ g.add_node(file_path, node_type="file")+ sid = f"{file_path}::{name}"+ g.add_node(+ sid,+ node_type="symbol",+ kind="function",+ name=name,+ file_path=file_path,+ start_line=start,+ end_line=end,+ parent_name=None,+ )+ g.add_edge(file_path, sid, edge_type="defines")+ return sid+++def _add_class(g: nx.DiGraph, file_path: str, name: str, *, start: int = 1, end: int = 30) -> str:+ if file_path not in g:+ g.add_node(file_path, node_type="file")+ sid = f"{file_path}::{name}"+ g.add_node(+ sid,+ node_type="symbol",+ kind="class",+ name=name,+ file_path=file_path,+ start_line=start,+ end_line=end,+ parent_name=None,+ )+ g.add_edge(file_path, sid, edge_type="defines")+ return sid+++def _call(g: nx.DiGraph, src: str, dst: str) -> None:+ g.add_edge(src, dst, edge_type="calls")+++def _ctx(+ g: nx.DiGraph, file_path: str, *, nloc: int = 600, language: str = "python"+) -> RefactoringContext:+ return RefactoringContext(file_path=file_path, language=language, nloc=nloc, graph=g)+++def _detect(g: nx.DiGraph, file_path: str, **kw) -> list:+ return [+ s+ for s in detect_refactorings(_ctx(g, file_path, **kw))+ if s.refactoring_type == "split_file"+ ]+++def _two_cluster_graph(file_path: str = "big.py", n_each: int = 5) -> nx.DiGraph:+ """Two internally-cohesive clusters with no edges between them — a textbook+ 2-way split. Each cluster is a clique of direct calls."""+ g = nx.DiGraph()+ cluster_a = [_add_func(g, file_path, f"alpha_{i}") for i in range(n_each)]+ cluster_b = [_add_func(g, file_path, f"beta_{i}") for i in range(n_each)]+ for cluster in (cluster_a, cluster_b):+ for i in range(len(cluster)):+ for j in range(len(cluster)):+ if i != j:+ _call(g, cluster[i], cluster[j])+ return g+++def test_two_cohesive_clusters_split_into_two_files():+ out = _detect(_two_cluster_graph(), "big.py")+ assert len(out) == 1+ s = out[0]+ assert s.refactoring_type == "split_file"+ assert s.evidence["symbol_count"] == 10+ assert s.evidence["group_count"] == 2+ assert s.evidence["modularity"] >= 0.30+ assert len(s.plan["groups"]) == 2+ # The two clusters partition cleanly: each group is all-alpha or all-beta.+ group_syms = [set(g["symbols"]) for g in s.plan["groups"]]+ for syms in group_syms:+ prefixes = {name.split("_")[0] for name in syms}+ assert len(prefixes) == 1 # no cross-contamination+ assert s.plan["shim_required"] is True+ assert s.impact_delta == 0.0+++def test_cohesive_big_file_is_suppressed_by_modularity_gate():+ # One big clique: every symbol calls every other — high cohesion, no clean+ # cut, low modularity → no suggestion (better no split than a bad one).+ g = nx.DiGraph()+ syms = [_add_func(g, "mono.py", f"fn_{i}") for i in range(10)]+ for i in range(len(syms)):+ for j in range(len(syms)):+ if i != j:+ _call(g, syms[i], syms[j])+ assert _detect(g, "mono.py") == []+++def test_single_dominant_class_routes_to_extract_class():+ # One class spanning ~90% of the file → Extract Class territory, not Split.+ g = nx.DiGraph()+ _add_class(g, "svc.py", "BigService", start=1, end=540)+ for i in range(8):+ _add_func(g, "svc.py", f"helper_{i}", start=541 + i, end=541 + i)+ assert _detect(g, "svc.py", nloc=600) == []+++def test_below_nloc_floor_is_skipped():+ assert _detect(_two_cluster_graph(), "big.py", nloc=100) == []+++def test_below_symbol_floor_is_skipped():+ g = nx.DiGraph()+ a = [_add_func(g, "small.py", f"a_{i}") for i in range(3)]+ for i in range(len(a)):+ for j in range(len(a)):+ if i != j:+ _call(g, a[i], a[j])+ assert _detect(g, "small.py") == []+++def test_test_file_is_excluded():+ g = _two_cluster_graph("tests/test_big.py")+ assert _detect(g, "tests/test_big.py") == []+++def test_generated_and_barrel_files_are_excluded():+ assert _detect(_two_cluster_graph("pkg/__init__.py"), "pkg/__init__.py") == []+ assert _detect(_two_cluster_graph("app/migrations/0001_x.py"), "app/migrations/0001_x.py") == []+++def test_no_graph_yields_nothing():+ ctx = RefactoringContext(file_path="big.py", language="python", nloc=600, graph=None)+ assert SplitFileDetector().detect(ctx) == []+++def test_deterministic_and_stable_order():+ g = _two_cluster_graph()+ first = _detect(g, "big.py")+ second = _detect(g, "big.py")+ assert [s.target_symbol for s in first] == [s.target_symbol for s in second]+ assert first[0].plan["groups"] == second[0].plan["groups"]+++def test_blast_radius_lists_external_referrers():+ g = _two_cluster_graph()+ # An external file calls into one of the file's symbols.+ g.add_node("caller.py", node_type="file")+ g.add_node(+ "caller.py::client",+ node_type="symbol",+ kind="function",+ name="client",+ file_path="caller.py",+ start_line=1,+ end_line=5,+ parent_name=None,+ )+ _call(g, "caller.py::client", "big.py::alpha_0")+ g.add_edge("caller.py", "big.py", edge_type="imports")+ out = _detect(g, "big.py")+ assert len(out) == 1+ br = out[0].blast_radius+ assert "caller.py" in br["dependent_files"]+ assert br["dependent_count"] >= 1+ assert br["import_rewrites"] == br["dependent_count"] # python → shim language+++def test_go_split_needs_no_import_rewrites():+ out = _detect(_two_cluster_graph("pkg/big.go"), "pkg/big.go", language="go")+ assert len(out) == 1+ assert out[0].plan["shim_required"] is False+ assert out[0].blast_radius["import_rewrites"] == 0+++def test_shared_helper_groups_callers_together():+ # Two pairs of functions, each pair bound only by a shared local helper+ # (no direct A<->B call), plus a separate cohesive cluster. The shared+ # helper should pull each pair together.+ g = nx.DiGraph()+ h1 = _add_func(g, "f.py", "shared_one")+ a1 = _add_func(g, "f.py", "uses_one_a")+ a2 = _add_func(g, "f.py", "uses_one_b")+ _call(g, a1, h1)+ _call(g, a2, h1)+ h2 = _add_func(g, "f.py", "shared_two")+ b1 = _add_func(g, "f.py", "uses_two_a")+ b2 = _add_func(g, "f.py", "uses_two_b")+ _call(g, b1, h2)+ _call(g, b2, h2)+ # pad to clear the symbol floor with a third cohesive cluster+ c = [_add_func(g, "f.py", f"gamma_{i}") for i in range(2)]+ _call(g, c[0], c[1])+ _call(g, c[1], c[0])+ out = _detect(g, "f.py")+ assert len(out) == 1+ # uses_one_a and uses_one_b end up in the same group.+ groups = [set(grp["symbols"]) for grp in out[0].plan["groups"]]+ assert any({"uses_one_a", "uses_one_b"} <= grp for grp in groups)+++def test_dominant_token_helper():+ # Plurality vote: one outlier doesn't kill the shared token.+ assert _dominant_token(["filter_dicts", "filter_path", "filter_rows", "is_excluded"]) == "filter"+ # Stopword verbs and short tokens don't win.+ assert _dominant_token(["get_repo", "get_spec"]) == ""+ # No token shared by >= 2 symbols.+ assert _dominant_token(["alpha", "beta"]) == ""+++def test_shim_required_helper():+ assert _shim_required("go") is False+ assert _shim_required("golang") is False+ assert _shim_required("python") is True+ assert _shim_required("typescript") is True+ assert _shim_required(None) is True