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(health): keep sweep commits and inheritance out of hidden coupling (#3686)
Swati Ahuja2fc2ceb60a09
diff --git a/packages/core/src/repowise/core/analysis/graph_view.py b/packages/core/src/repowise/core/analysis/graph_view.pyindex 0a422b0f0..26d1ad056 100644--- a/packages/core/src/repowise/core/analysis/graph_view.py+++ b/packages/core/src/repowise/core/analysis/graph_view.py@@ -18,12 +18,38 @@ from ..ingestion.languages import REGISTRYfrom ..ingestion.models import FILE_DEPENDENCY_EDGE_TYPESfrom .dead_code.file_reachability import BARREL_FILENAMES-__all__ = ["BARREL_DEPENDENCY", "HasEdge", "ImportEdgeView", "can_carry_dependency"]+__all__ = [+ "BARREL_DEPENDENCY",+ "INHERITANCE_DEPENDENCY",+ "HasEdge",+ "ImportEdgeView",+ "can_carry_dependency",+ "heritage_ancestors",+]#: ``dependency_kind`` for a pair joined through a re-export barrel rather than#: by a direct edge: ``a -> index.ts -> b``.BARREL_DEPENDENCY = "barrel"+#: ``dependency_kind`` for a pair where a type in one file inherits, directly+#: or transitively, from a type in the other. Java and C# classes in one+#: package extend each other with no import, so no file edge records it.+INHERITANCE_DEPENDENCY = "inherits"++_HERITAGE_EDGE_TYPES = ("extends", "implements")+++def heritage_ancestors(graph: Any, class_id: str) -> set[str]:+ """Every type symbol *class_id* inherits from, transitively."""+ seen: set[str] = set()+ stack = [class_id]+ while stack:+ for _u, base, data in graph.out_edges(stack.pop(), data=True):+ if data.get("edge_type") in _HERITAGE_EDGE_TYPES and base not in seen:+ seen.add(base)+ stack.append(base)+ return seen+def _language_of(path: str) -> str:"""The registry's language tag for *path*, or ``"unknown"``."""@@ -70,11 +96,12 @@ class ImportEdgeView:a caller pass ``None`` instead of branching."""- __slots__ = ("_barrels", "_graph")+ __slots__ = ("_barrels", "_graph", "_heritage")def __init__(self, graph: Any) -> None:self._graph = graphself._barrels: dict[str, tuple[str, ...]] = {}+ self._heritage: dict[str, frozenset[str]] = {}def has_edge(self, src: str, dst: str, key: str = "imports") -> bool:g = self._graph@@ -104,8 +131,38 @@ class ImportEdgeView::data:`BARREL_DEPENDENCY`. Only a chain through the barrel counts: twofiles a barrel merely re-exports side by side, or two consumers of onebarrel, share a neighbour and nothing more.++ A subclass and any of its ancestors answer+ :data:`INHERITANCE_DEPENDENCY`; two subclasses of one base do not."""- return self._typed(a, b) or self._typed(b, a) or self._via_barrel(a, b)+ return (+ self._typed(a, b)+ or self._typed(b, a)+ or self._via_barrel(a, b)+ or self._via_heritage(a, b)+ )++ def _via_heritage(self, a: str, b: str) -> str | None:+ if b in self._heritage_files(a) or a in self._heritage_files(b):+ return INHERITANCE_DEPENDENCY+ return None++ def _heritage_files(self, path: str) -> frozenset[str]:+ """Files declaring a type some type in *path* inherits from, cached."""+ cached = self._heritage.get(path)+ if cached is None:+ cached = self._heritage[path] = frozenset(self._inherited_owners(path))+ return cached++ def _inherited_owners(self, path: str) -> set[str]:+ g = self._graph+ if g is None or path not in g:+ return set()+ types = [s for _u, s, d in g.out_edges(path, data=True) if d.get("edge_type") == "defines"]+ bases = set().union(*(heritage_ancestors(g, t) for t in types))+ # An external base has no node attributes, or no node: skip just it.+ owners = {(g.nodes.get(b) or {}).get("file_path") for b in bases}+ return {o for o in owners if o and o != path}def _via_barrel(self, a: str, b: str) -> str | None:for src, dst in ((a, b), (b, a)):diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/hidden_coupling.py b/packages/core/src/repowise/core/analysis/health/biomarkers/hidden_coupling.pyindex 8bfd963c2..f683db5a5 100644--- a/packages/core/src/repowise/core/analysis/health/biomarkers/hidden_coupling.py+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/hidden_coupling.py@@ -16,13 +16,19 @@ Fires when:- the pair is not a test ↔ production pairing (those are expected toco-change)+Shared commits are the pair's focused count: commits wider than the sweep cap+change entropy uses (a license header pass, a package rename) touch every file+at once and are no evidence that two of them belong together. Each file's own+commit total still counts them, since they are still its commits.+Counts come from the co-change walk itself. ``commit_count_total`` looks likethe denominator but is not one: it is collected over a shorter window andonly for files with a code extension, so dividing by it mixes twopopulations and understates every ratio it does not simply zero.-An index written before the walk recorded those counts carries neither them-nor the structural label, and yields no findings until it is rebuilt. Silence+An index written before the walk recorded those counts (or the focused count)+carries neither them nor the structural label, and yields no findings until+the full history rewalk ``GIT_HISTORY_VERSION`` triggers on the next update. Silenceis the honest answer there: without the label the detector cannot tell a pairthe graph explains from one it does not.@@ -105,6 +111,9 @@ class HiddenCouplingDetector:# Only a pair the graph could have explained and did not.if partner.structural != STRUCTURAL_UNEXPLAINED:continue+ support = partner.focused_support+ if support is None:+ continuetotal_self = partner.self_commitspartner_total = partner.partner_commitsif total_self < _MIN_COMMITS or partner_total < _MIN_COMMITS:@@ -112,9 +121,9 @@ class HiddenCouplingDetector:denom = min(total_self, partner_total)# More shared commits than the smaller file has commits is a# record the walk could not have written; there is no ratio to show.- if denom <= 0 or partner.support > denom:+ if denom <= 0 or support > denom:continue- correlation = partner.support / denom+ correlation = support / denomif correlation < _MIN_CORRELATION:continue# Test ↔ production pairs are expected to co-change, so they carry@@ -123,9 +132,7 @@ class HiddenCouplingDetector:ctx.file_path, partner_path, code_language=ctx.language):continue- candidates.append(- (correlation, partner_path, partner.support, total_self, partner_total)- )+ candidates.append((correlation, partner_path, support, total_self, partner_total))if not candidates:return []diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/move_method.py b/packages/core/src/repowise/core/analysis/health/refactoring/move_method.pyindex 39bbe96a8..542d9f5a7 100644--- a/packages/core/src/repowise/core/analysis/health/refactoring/move_method.py+++ b/packages/core/src/repowise/core/analysis/health/refactoring/move_method.py@@ -63,6 +63,7 @@ from typing import Anyfrom repowise.core.analysis.dead_code.contract_methods import is_contract_methodfrom repowise.core.analysis.execution_graph import is_reliable_call_edge+from repowise.core.analysis.graph_view import heritage_ancestorsfrom ....test_paths import is_test_related_pathfrom ..effort import effort_bucket@@ -139,18 +140,6 @@ def _file_is_test(graph: Any, path: str) -> bool:return is_test_related_path(path)-def _ancestors(graph: Any, class_id: str) -> set[str]:- """Every class *class_id* inherits from, transitively."""- seen: set[str] = set()- stack = [class_id]- while stack:- for _u, base, data in graph.out_edges(stack.pop(), data=True):- if data.get("edge_type") in ("extends", "implements") and base not in seen:- seen.add(base)- stack.append(base)- return seen--def _partial_fragments(graph: Any, file_path: str, class_name: str) -> set[str]:"""The class ids of *class_name*'s ``partial`` fragments in other files.@@ -197,7 +186,7 @@ def _overrides(graph: Any, data: dict, own_class_id: str, language: str) -> boolreturn Truedeclared = {(_node(graph, member) or {}).get("name")- for base in _ancestors(graph, own_class_id)+ for base in heritage_ancestors(graph, own_class_id)for member in _class_members(graph, base, {})}return name in declared@@ -251,7 +240,7 @@ def _never_a_target(graph: Any, class_id: str) -> bool:if _is_static_holder(graph, class_id):return Truenames = [_class_name(graph, class_id)]- names += [b.rsplit("::", 1)[-1] for b in _ancestors(graph, class_id)]+ names += [b.rsplit("::", 1)[-1] for b in heritage_ancestors(graph, class_id)]return any(n.endswith(_NON_TARGET_SUFFIXES) for n in names)@@ -421,7 +410,7 @@ class MoveMethodDetector(RefactoringDetector):# Nearest foreign class by Jaccard distance (tie-break on class id).# A constructor call lands the class id in its own member set.- own_and_inherited = _ancestors(graph, own_class_id) | own_ids+ own_and_inherited = heritage_ancestors(graph, own_class_id) | own_idsforeign = [(c, m)for c, m in accessed_by_class.items()diff --git a/packages/core/src/repowise/core/co_change.py b/packages/core/src/repowise/core/co_change.pyindex 2dd098c83..323b7efe2 100644--- a/packages/core/src/repowise/core/co_change.py+++ b/packages/core/src/repowise/core/co_change.py@@ -84,7 +84,9 @@ class CoChangePartner:commits; ``support`` is that plain count. ``self_commits`` and``partner_commits`` are each file's commit total over the same walk, so``support / self_commits`` is an honest directional confidence. They are- zero on an index written before they were recorded.+ zero on an index written before they were recorded. ``focused_support`` is+ ``support`` counted over commits narrow enough to be evidence (the sweep cap+ change entropy uses), ``None`` before it was recorded.``dependency_kind`` is the ``edge_type`` behind a ``corroborated``verdict, or ``"barrel"`` when the pair is joined through a re-export@@ -101,6 +103,7 @@ class CoChangePartner:support: int = 0self_commits: int = 0partner_commits: int = 0+ focused_support: int | None = Nonestructural: str | None = Nonedependency_kind: str | None = Nonerecord: dict = field(default_factory=dict, compare=False, repr=False)@@ -158,6 +161,11 @@ def parse_partners(raw: object) -> list[CoChangePartner]:support=_as_count(record.get("frequency")),self_commits=_as_count(record.get("self_commits")),partner_commits=_as_count(record.get("partner_commits")),+ focused_support=(+ _as_count(record["focused_frequency"])+ if "focused_frequency" in record+ else None+ ),structural=structural if isinstance(structural, str) else None,dependency_kind=kind if isinstance(kind, str) else None,record=record,diff --git a/packages/core/src/repowise/core/ingestion/git_indexer/_constants.py b/packages/core/src/repowise/core/ingestion/git_indexer/_constants.pyindex 6a6b3115b..3590d30d1 100644--- a/packages/core/src/repowise/core/ingestion/git_indexer/_constants.py+++ b/packages/core/src/repowise/core/ingestion/git_indexer/_constants.py@@ -128,7 +128,8 @@ _MAX_FILES_PER_COMMIT_FOR_COCHANGE: int = 200# excludes very wide commits from the History Complexity Metric because a# sweeping edit spreads its "change probability" so thinly that it adds noise# rather than signal. 30 follows the commonly cited Hassan filter; commits-# above it are dropped from the entropy accumulation entirely.+# above it are dropped from the entropy accumulation entirely, and from the+# focused co-change count hidden coupling reads as evidence._MAX_FILES_PER_COMMIT_FOR_ENTROPY: int = 30# Commit message classification regexes. "fix" is not here: a@@ -318,7 +319,9 @@ HOTSPOT_HALFLIFE_DAYS: float = 180.0#: v1: change numbers and author identity read through ``repowise.core.forges``#: (GitLab ``!N`` merge requests, Azure and Bitbucket PRs, GitLab noreply and#: forge bot accounts).-GIT_HISTORY_VERSION: int = 1+#: v2: co-change records carry focused_frequency, the shared commits no wider+#: than the change-entropy sweep cap.+GIT_HISTORY_VERSION: int = 2GIT_HISTORY_VERSION_KEY = "git_history_version"diff --git a/packages/core/src/repowise/core/ingestion/git_indexer/co_change.py b/packages/core/src/repowise/core/ingestion/git_indexer/co_change.pyindex a9a53f543..15c79bcaf 100644--- a/packages/core/src/repowise/core/ingestion/git_indexer/co_change.py+++ b/packages/core/src/repowise/core/ingestion/git_indexer/co_change.py@@ -65,6 +65,7 @@ class CoChangeWalk:def _partner_records(kept: dict[str, list[tuple[float, str]]],pair_support: dict[tuple[str, str], int],+ pair_focused: dict[tuple[str, str], int],pair_last_date: dict[tuple[str, str], int],file_commits: dict[str, int],) -> dict[str, list[dict]]:@@ -73,6 +74,8 @@ def _partner_records(``self_commits`` / ``partner_commits`` are each file's commit total overthis same walk, so a reader can state a directional confidence withoutborrowing a denominator computed over a different window.+ ``focused_frequency`` is ``frequency`` without the sweep commits change+ entropy also drops, for a reader that treats a pair as evidence."""out: dict[str, list[dict]] = {}for owner, heap in kept.items():@@ -85,6 +88,7 @@ def _partner_records("file_path": other,"co_change_count": round(score, 4),"frequency": pair_support[pair],+ "focused_frequency": pair_focused.get(pair, 0),"self_commits": file_commits[owner],"partner_commits": file_commits[other],"last_co_change": (@@ -154,6 +158,7 @@ def compute_co_changes_and_entropy(partner_count: defaultdict[str, int] = defaultdict(int)partner_mass: defaultdict[str, float] = defaultdict(float)pair_support: defaultdict[tuple[str, str], int] = defaultdict(int)+ pair_focused: defaultdict[tuple[str, str], int] = defaultdict(int)pair_last_date: dict[tuple[str, str], int] = {} # pair → latest Unix tsfile_commits: defaultdict[str, int] = defaultdict(int)entropy_scores: defaultdict[str, float] = defaultdict(float)@@ -225,12 +230,15 @@ def compute_co_changes_and_entropy(# Split the commit's weight across the files it touched, so a pair from# a two-file commit outweighs one from a fifty-file commit.pair_weight = pair_decay / (n - 1)+ focused = n <= _MAX_FILES_PER_COMMIT_FOR_ENTROPYsorted_files = sorted(current)for i in range(len(sorted_files)):for j in range(i + 1, len(sorted_files)):pair = (sorted_files[i], sorted_files[j])pair_scores[pair] += pair_weightpair_support[pair] += 1+ if focused:+ pair_focused[pair] += 1if pair not in pair_last_date or current_ts > pair_last_date[pair]:pair_last_date[pair] = current_ts@@ -284,7 +292,7 @@ def compute_co_changes_and_entropy(_offer(a, b, score)_offer(b, a, score)- result = _partner_records(kept, pair_support, pair_last_date, file_commits)+ result = _partner_records(kept, pair_support, pair_focused, pair_last_date, file_commits)entropy = {fp: round(score, 6) for fp, score in entropy_scores.items() if score > 0.0}diff --git a/tests/unit/cli/test_update_git_history_stamp.py b/tests/unit/cli/test_update_git_history_stamp.pyindex 828299abe..2fe00037c 100644--- a/tests/unit/cli/test_update_git_history_stamp.py+++ b/tests/unit/cli/test_update_git_history_stamp.py@@ -112,6 +112,8 @@ def test_current_stamp_forces_no_walk(tmp_path, walks) -> None:def test_missing_stamp_is_stale() -> None:assert git_history_stale({})assert git_history_stale({GIT_HISTORY_VERSION_KEY: GIT_HISTORY_VERSION - 1})+ # v1 co-change records have no focused_frequency, so v1 must rewalk.+ assert git_history_stale({GIT_HISTORY_VERSION_KEY: 1})assert not git_history_stale({GIT_HISTORY_VERSION_KEY: GIT_HISTORY_VERSION})diff --git a/tests/unit/health/test_ff_track_iljk_structural.py b/tests/unit/health/test_ff_track_iljk_structural.pyindex e9ccd82d7..43cb80348 100644--- a/tests/unit/health/test_ff_track_iljk_structural.py+++ b/tests/unit/health/test_ff_track_iljk_structural.py@@ -217,6 +217,7 @@ def test_detector_caps_small_sample_pair_at_medium():"file_path": "src/billing.py","co_change_count": 4,"frequency": 4,+ "focused_frequency": 4,"self_commits": 5,"partner_commits": 5,"structural": "unexplained",diff --git a/tests/unit/health/test_hidden_coupling.py b/tests/unit/health/test_hidden_coupling.pyindex f9c1259a8..b5f1b828c 100644--- a/tests/unit/health/test_hidden_coupling.py+++ b/tests/unit/health/test_hidden_coupling.py@@ -31,6 +31,7 @@ def _partners("file_path": p,"co_change_count": float(support),"frequency": support,+ "focused_frequency": support,"self_commits": self_commits,"partner_commits": repo_commits.get(p, 0),"structural": structural,@@ -340,3 +341,43 @@ def test_more_shared_commits_than_the_smaller_file_has_is_not_reported():repo_commits={"src/billing.py": 30},)assert HiddenCouplingDetector().detect(ctx) == []+++def _record(**overrides) -> FileContext:+ record = {+ "file_path": "src/billing.py",+ "co_change_count": 1.0,+ "frequency": 18,+ "focused_frequency": 18,+ "self_commits": 20,+ "partner_commits": 22,+ "structural": STRUCTURAL_UNEXPLAINED,+ **overrides,+ }+ record = {k: v for k, v in record.items() if v is not None}+ return FileContext(+ file_path="src/payments.py",+ language="python",+ nloc=120,+ has_test_file=False,+ module=None,+ git_meta={"co_change_partners_json": json.dumps([record])},+ dependents_count=0,+ )+++def test_a_pair_seen_only_in_sweep_commits_is_not_hidden_coupling():+ """18 shared commits, every one a wide sweep: no evidence the two belong together."""+ assert HiddenCouplingDetector().detect(_record(focused_frequency=0)) == []+++def test_the_ratio_counts_only_focused_shared_commits():+ (out,) = HiddenCouplingDetector().detect(_record(focused_frequency=12))+ assert out.details["co_change_count"] == 12+ assert out.details["correlation"] == 0.6+ assert "in 12 of this file's 20 commits" in out.reason+++def test_a_record_without_the_focused_count_yields_nothing():+ """Written before the walk counted it: sweeps cannot be told apart, so silence."""+ assert HiddenCouplingDetector().detect(_record(focused_frequency=None)) == []diff --git a/tests/unit/ingestion/test_co_change_edges.py b/tests/unit/ingestion/test_co_change_edges.pyindex 978858dba..19881396a 100644--- a/tests/unit/ingestion/test_co_change_edges.py+++ b/tests/unit/ingestion/test_co_change_edges.py@@ -193,6 +193,49 @@ class TestStructuralLabel:assert builder.label_co_change_structure(partners) == 1+class TestInheritanceLabel:+ """A subclass and its ancestors depend on each other with no file edge."""++ @staticmethod+ def _java(builder: GraphBuilder, path: str, cls: str, base: str | None = None) -> None:+ g = builder._graph+ g.add_node(path, language="java")+ g.add_node(f"{path}::{cls}", node_type="symbol", file_path=path)+ g.add_edge(path, f"{path}::{cls}", edge_type="defines")+ if base:+ g.add_edge(f"{path}::{cls}", base, edge_type="extends")++ def test_a_transitive_ancestor_explains_the_pair(self, builder: GraphBuilder) -> None:+ self._java(builder, "BaseEntity.java", "BaseEntity")+ self._java(builder, "NamedEntity.java", "NamedEntity", "BaseEntity.java::BaseEntity")+ self._java(builder, "PetType.java", "PetType", "NamedEntity.java::NamedEntity")+ self._java(builder, "Owner.java", "Owner", "BaseEntity.java::BaseEntity")+ partners = {+ "BaseEntity.java": [{"file_path": "PetType.java", "frequency": 9}],+ "PetType.java": [+ {"file_path": "BaseEntity.java", "frequency": 9},+ {"file_path": "Owner.java", "frequency": 9},+ ],+ }+ # Two subclasses of one base share an ancestor and nothing more.+ assert builder.label_co_change_structure(partners) == 1+ for record in (partners["BaseEntity.java"][0], partners["PetType.java"][0]):+ assert record["structural"] == "corroborated"+ assert record["dependency_kind"] == "inherits"+ assert partners["PetType.java"][1]["structural"] == "unexplained"+++ def test_an_external_base_does_not_hide_an_in_repo_one(self, builder: GraphBuilder) -> None:+ """A base the graph has no file for is skipped, not the whole answer."""+ self._java(builder, "BaseEntity.java", "BaseEntity")+ self._java(builder, "Pet.java", "Pet", "BaseEntity.java::BaseEntity")+ # ``java.io.Serializable`` exists only as an edge target, with no attributes.+ builder._graph.add_edge("Pet.java::Pet", "java.io.Serializable", edge_type="implements")+ partners = {"Pet.java": [{"file_path": "BaseEntity.java", "frequency": 9}]}+ assert builder.label_co_change_structure(partners) == 0+ assert partners["Pet.java"][0]["dependency_kind"] == "inherits"++class TestLabelPersistence:"""``label_co_change_structure`` writes through the JSON column.diff --git a/tests/unit/test_git_indexer.py b/tests/unit/test_git_indexer.pyindex cff4384ce..3a3b8cc4e 100644--- a/tests/unit/test_git_indexer.py+++ b/tests/unit/test_git_indexer.py@@ -1285,3 +1285,45 @@ class TestCoChangeCommitWidth:assert partner["frequency"] == 2assert partner["self_commits"] == 11 # 2 shared + 9 aloneassert partner["partner_commits"] == 2++ def test_the_focused_count_leaves_out_sweep_commits(self) -> None:+ """A sweep is still a commit of every file it touches, and still a+ shared commit, but not one the focused count holds as evidence."""+ import time++ from repowise.core.ingestion.git_indexer._constants import (+ _MAX_FILES_PER_COMMIT_FOR_ENTROPY,+ )++ now = int(time.time())+ sweep = ("a.py", "b.py", *(f"s{i}.py" for i in range(_MAX_FILES_PER_COMMIT_FOR_ENTROPY)))+ mock_repo = MagicMock()+ mock_repo.git.log.return_value = self._log(now, ("a.py", "b.py"), sweep, sweep)++ result = compute_co_changes_and_entropy(mock_repo, set(sweep), commit_limit=500)++ partner = next(p for p in result.partners["a.py"] if p["file_path"] == "b.py")+ assert partner["frequency"] == 3+ assert partner["focused_frequency"] == 1+ assert partner["self_commits"] == 3++ def test_the_sweep_cap_is_inclusive(self) -> None:+ """A commit of exactly the cap is focused; one file more is a sweep."""+ import time++ from repowise.core.ingestion.git_indexer._constants import (+ _MAX_FILES_PER_COMMIT_FOR_ENTROPY as CAP,+ )++ now = int(time.time())+ at_cap = ("a.py", "b.py", *(f"s{i}.py" for i in range(CAP - 2)))+ over_cap = (*at_cap, "extra.py")+ assert (len(at_cap), len(over_cap)) == (CAP, CAP + 1)+ mock_repo = MagicMock()+ mock_repo.git.log.return_value = self._log(now, at_cap, over_cap)++ result = compute_co_changes_and_entropy(mock_repo, set(over_cap), commit_limit=500)++ partner = next(p for p in result.partners["a.py"] if p["file_path"] == "b.py")+ assert partner["frequency"] == 2+ assert partner["focused_frequency"] == 1