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): judge a finding by its own deduction, not its share of a capped category (#2411)
Raghav Chamadiya4bf878f6d3bc
diff --git a/packages/core/alembic/versions/0068_repository_function_mod_p80.py b/packages/core/alembic/versions/0068_repository_function_mod_p80.pynew file mode 100644index 000000000..78310378d--- /dev/null+++ b/packages/core/alembic/versions/0068_repository_function_mod_p80.py@@ -0,0 +1,52 @@+"""repositories: store the full-repo function-mod p80.++``function_hotspot`` gates on the repo-wide 80th percentile of per-function+modification counts. A full index computes that over every walked function; an+incremental update cannot, because it walks the changed files alone, so it+reads a stored value back instead (issue #1484).++The only stored repo-wide source until now was the ``git_function_blame``+rollup, read back by ``load_stored_function_mod_p80``. That table is keyed+``(repository_id, symbol_id)`` with ``symbol_id = "{path}::{name}"``, so every+same-named function in a file collapses to a single row: the percentile was+taken over a population missing those samples, and the surviving sample is+whichever occurrence the walker emitted last rather than a max or a sum. The+gate therefore still moved between ``init`` and ``update`` -- the flip #1484+exists to prevent, arriving through a different door.++This column holds the number the full index actually measured. Nullable, so a+store written before this migration keeps working: the reader falls back to the+rollup percentile until the next full index fills it in.++Local SQLite stores never run Alembic -- ``init_db``'s reconciler issues+additive DDL for missing columns, and an added nullable column is exactly what+it handles -- so this migration exists for managed Postgres.++Revision ID: 0068+Revises: 0067+Create Date: 2026-09-18+"""++from __future__ import annotations++from collections.abc import Sequence++import sqlalchemy as sa+from alembic import op++# revision identifiers+revision: str = "0068"+down_revision: str | None = "0067"+branch_labels: str | Sequence[str] | None = None+depends_on: str | Sequence[str] | None = None+++def upgrade() -> None:+ op.add_column(+ "repositories",+ sa.Column("function_mod_p80", sa.Integer(), nullable=True),+ )+++def downgrade() -> None:+ op.drop_column("repositories", "function_mod_p80")diff --git a/packages/core/src/repowise/core/analysis/change_health/matcher.py b/packages/core/src/repowise/core/analysis/change_health/matcher.pyindex 624996a14..7088084b2 100644--- a/packages/core/src/repowise/core/analysis/change_health/matcher.py+++ b/packages/core/src/repowise/core/analysis/change_health/matcher.py@@ -5,6 +5,7 @@ from __future__ import annotationsfrom dataclasses import dataclass, fieldfrom ..health import HealthFindingData+from ..health.aggregation import finding_raw_deductionfrom .identity import finding_key, line_distance, normalize_path, severity_rankfrom .models import ChangeKind, FindingKey@@ -120,6 +121,6 @@ def _classify(base: HealthFindingData | None, head: HealthFindingData) -> Changereturn "worsened"if severity_rank(head.severity) < severity_rank(base.severity):return "unchanged"- if (head.health_impact or 0.0) - (base.health_impact or 0.0) > _IMPACT_EPSILON:+ if finding_raw_deduction(head) - finding_raw_deduction(base) > _IMPACT_EPSILON:return "worsened"return "unchanged"diff --git a/packages/core/src/repowise/core/analysis/health/aggregation.py b/packages/core/src/repowise/core/analysis/health/aggregation.pyindex 238394976..e959f6645 100644--- a/packages/core/src/repowise/core/analysis/health/aggregation.py+++ b/packages/core/src/repowise/core/analysis/health/aggregation.py@@ -31,6 +31,7 @@ __all__ = ["SEVERITY_ORDER","biomarker_breakdown","finding_base_deduction",+ "finding_raw_deduction","module_label","module_rollups","score_breakdown",@@ -189,6 +190,21 @@ def finding_base_deduction(finding: Any) -> float:return severity_deduction(_severity_key(field(finding, "severity", None)))+def finding_raw_deduction(finding: Any) -> float:+ """One finding's deduction before any category cap redistributed it.++ ``base x weight``, the quantity ``_score_dimension`` computes and then+ scales away. ``health_impact`` is what survives that scaling, so it moves+ when a *neighbour* in the same capped category appears or goes away; this+ one depends on the finding alone. A breakdown needs it to say how much a+ category shed, and a change comparison needs it to ask whether one finding+ got worse without hearing about its neighbours.+ """+ return finding_base_deduction(finding) * biomarker_weight(+ field(finding, "biomarker_type", None)+ )++def score_breakdown(findings: Sequence[Any]) -> dict[str, Any]:"""Reconstruct one file's per-category deductions from its open findings.@@ -216,10 +232,7 @@ def score_breakdown(findings: Sequence[Any]) -> dict[str, Any]:entries = per_category.get(category, [])if not entries:continue- raw_each = [- finding_base_deduction(f) * biomarker_weight(field(f, "biomarker_type", None))- for f in entries- ]+ raw_each = [finding_raw_deduction(f) for f in entries]applied_each = [float(field(f, "health_impact", 0.0) or 0.0) for f in entries]raw_sum = sum(raw_each)applied_sum = sum(applied_each)diff --git a/packages/core/src/repowise/core/analysis/health/engine.py b/packages/core/src/repowise/core/analysis/health/engine.pyindex 1018a529f..3f7510902 100644--- a/packages/core/src/repowise/core/analysis/health/engine.py+++ b/packages/core/src/repowise/core/analysis/health/engine.py@@ -252,6 +252,20 @@ def _percentile_p80(counts: list[int]) -> int | None:return counts[idx_p80]+def _full_repo_p80(+ value: int | None, changed_files: object, override: int | None+) -> int | None:+ """*value*, but only when this run is entitled to publish it repo-wide.++ An incremental run walks the changed files alone, so the percentile it+ derives describes a churn-heavy subset and must never be stored as the+ repo's. A run that was handed an override did not measure anything either.+ """+ if changed_files is not None or override is not None:+ return None+ return value++def _compute_repo_function_mod_p80(walked: list[tuple[Any, FileComplexity]],git_meta_map: dict[str, dict],@@ -608,6 +622,9 @@ class HealthAnalyzer:if repo_function_mod_p80 is not Noneelse _compute_repo_function_mod_p80(walked, self.git_meta_map))+ full_repo_fn_mod_p80 = _full_repo_p80(+ repo_fn_mod_p80, changed_files, repo_function_mod_p80+ )repo_dependents_p80 = _compute_repo_dependents_p80(self.parsed_files, self.graph)repo_active_contributors = _compute_repo_active_contributors(self.git_meta_map)@@ -700,6 +717,7 @@ class HealthAnalyzer:metrics=metrics,kpis=kpis,function_blame_rows=self._function_blame_rows(walked),+ repo_function_mod_p80=full_repo_fn_mod_p80,refactoring_suggestions=suggestions,performance_plan_policy=PerformancePlanPolicy(enabled=refactoring_enabled and "performance_fix" not in disabled_refactorings,@@ -819,6 +837,9 @@ class HealthAnalyzer:if repo_function_mod_p80 is not Noneelse _compute_repo_function_mod_p80(list(walked), self.git_meta_map))+ full_repo_fn_mod_p80 = _full_repo_p80(+ repo_fn_mod_p80, changed_files, repo_function_mod_p80+ )repo_dependents_p80 = _compute_repo_dependents_p80(self.parsed_files, self.graph)repo_active_contributors = _compute_repo_active_contributors(self.git_meta_map)@@ -901,6 +922,7 @@ class HealthAnalyzer:metrics=metrics,kpis=kpis,function_blame_rows=self._function_blame_rows(walked),+ repo_function_mod_p80=full_repo_fn_mod_p80,refactoring_suggestions=suggestions,performance_plan_policy=PerformancePlanPolicy(enabled=refactoring_enabled and "performance_fix" not in disabled_refactorings,diff --git a/packages/core/src/repowise/core/analysis/health/models.py b/packages/core/src/repowise/core/analysis/health/models.pyindex 2686fee1c..e70b6bdc1 100644--- a/packages/core/src/repowise/core/analysis/health/models.py+++ b/packages/core/src/repowise/core/analysis/health/models.py@@ -151,6 +151,10 @@ class HealthReport:# Per-function blame rollup rows (``git_function_blame``), derived from the# FULL-tier blame index. Empty on ESSENTIAL tier / when blame is absent.function_blame_rows: list[dict] = field(default_factory=list)+ # The repo-wide function-mod p80 this run computed over every walked+ # function. Set only when the run actually saw the whole repo, so an+ # incremental run never offers its changed-files subset for storage.+ repo_function_mod_p80: int | None = None# Deterministic refactoring suggestions (``RefactoringSuggestion``), one# per detected opportunity. Produced by the refactoring layer in the same# per-file pass that produces findings; empty when the layer is disableddiff --git a/packages/core/src/repowise/core/persistence/crud/repository.py b/packages/core/src/repowise/core/persistence/crud/repository.pyindex 6e64793ac..b9192716e 100644--- a/packages/core/src/repowise/core/persistence/crud/repository.py+++ b/packages/core/src/repowise/core/persistence/crud/repository.py@@ -129,6 +129,19 @@ def _read_head_commit(local_path: str) -> str | None:return head or None+async def set_repo_function_mod_p80(session: AsyncSession, repo_id: str, value: int) -> None:+ """Store the repo-wide function-mod p80 a full index measured.++ Deliberately not folded into :func:`update_repo_git_totals`: that one+ carries whole-history git totals (#730), and this is a health quantity that+ happens to live on the same row. No-ops on a missing repo.+ """+ repo = await session.get(Repository, repo_id)+ if repo is None:+ return+ repo.function_mod_p80 = int(value)++async def update_repo_git_totals(session: AsyncSession,repo_id: str,diff --git a/packages/core/src/repowise/core/persistence/models.py b/packages/core/src/repowise/core/persistence/models.pyindex 93c09a6f8..6d6c5225e 100644--- a/packages/core/src/repowise/core/persistence/models.py+++ b/packages/core/src/repowise/core/persistence/models.py@@ -111,6 +111,17 @@ class Repository(Base):# reconcile. NULL on indexes written before this, which just means the next# capture walks once and anchors itself.churn_anchor_sha: Mapped[str | None] = mapped_column(String(40), nullable=True)+ # The repo-wide 80th percentile of per-function modification counts, the+ # gate ``function_hotspot`` scores against. Stored for the same reason as+ # the totals above: the only other repo-wide source is the+ # ``git_function_blame`` rollup, and that table is keyed by+ # ``{path}::{name}``, so every same-named function in a file collapses to+ # one row and the percentile is taken over a population missing those+ # samples. A full index computes this over every walked function and writes+ # it here; an incremental update reads it back, so a hotspot verdict does+ # not flip between ``init`` and ``update`` (issue #1484). NULL until the+ # first full index after this field landed, where the reader falls back.+ function_mod_p80: Mapped[int | None] = mapped_column(Integer, nullable=True)# ``parser_fingerprint()`` of the build that last wrote this repo's# ``graph_edges``. An incremental update only rewrites the git-changed# files' edges, so a query/extractor change would otherwise reach a filediff --git a/packages/core/src/repowise/core/pipeline/incremental.py b/packages/core/src/repowise/core/pipeline/incremental.pyindex e9effdc95..9f63f2026 100644--- a/packages/core/src/repowise/core/pipeline/incremental.py+++ b/packages/core/src/repowise/core/pipeline/incremental.py@@ -550,12 +550,20 @@ async def load_stored_function_mod_p80(repo_path: Any, *, log: LogFn | None = Norepo = await get_repository_by_path(session, str(repo_path))if repo is None:return None+ # What the last full index measured over every walked function.+ stored = getattr(repo, "function_mod_p80", None)+ if stored:+ return int(stored)counts = await get_git_function_mod_counts(session, repo.id)finally:await engine.dispose()if not counts:return None- # Same inclusive-lower p80 as the in-memory path — do not reimplement.+ # Fallback for a store whose last full index predates the column above.+ # The rollup is keyed by ``{path}::{name}``, so a file's same-named+ # functions collapse to one row and this percentile is taken over a+ # population missing those samples. Closer than the changed-files+ # subset, still not the number a full index computes.from repowise.core.analysis.health.engine import _percentile_p80return _percentile_p80(counts)diff --git a/packages/core/src/repowise/core/pipeline/persist.py b/packages/core/src/repowise/core/pipeline/persist.pyindex fa2704935..5fef4be12 100644--- a/packages/core/src/repowise/core/pipeline/persist.py+++ b/packages/core/src/repowise/core/pipeline/persist.py@@ -1926,6 +1926,7 @@ async def persist_analysis(result: Any, session: Any, repo_id: str) -> None:replace_doc_drift_guarded,save_coverage_files,save_dead_code_findings,+ set_repo_function_mod_p80,upsert_git_function_blame_bulk,)@@ -1970,6 +1971,13 @@ async def persist_analysis(result: Any, session: Any, repo_id: str) -> None:fn_blame_rows = getattr(hr, "function_blame_rows", None)if fn_blame_rows:await upsert_git_function_blame_bulk(session, repo_id, fn_blame_rows)+ # The hotspot gate an incremental update will score against. Written+ # only by a run that walked the whole repo (the analyzer leaves it None+ # otherwise), so an incremental run cannot publish its changed-files+ # subset as the repo-wide percentile.+ fn_mod_p80 = getattr(hr, "repo_function_mod_p80", None)+ if fn_mod_p80:+ await set_repo_function_mod_p80(session, repo_id, fn_mod_p80)# Snapshot the run for trend tracking (rolling delete inside). From# the rows just written, by the same writer the update path uses.await snapshot_health_from_store(session, repo_id)diff --git a/tests/unit/change_health/test_regressions.py b/tests/unit/change_health/test_regressions.pyindex 4377328c0..1d6763bdb 100644--- a/tests/unit/change_health/test_regressions.py+++ b/tests/unit/change_health/test_regressions.py@@ -2,6 +2,8 @@from __future__ import annotations+import pytest+from repowise.core.analysis.change_health.analyzer import MAX_FILE_BYTESfrom repowise.core.analysis.change_health.identity import change_finding_id, finding_keyfrom repowise.core.analysis.change_health.matcher import FindingMatcher@@ -9,6 +11,7 @@ from repowise.core.analysis.change_health.models import FindingKeyfrom repowise.core.analysis.change_health.service import ChangeHealthDeltaService, DeltaRequestfrom repowise.core.analysis.change_health.sources import GitRevisionSourcefrom repowise.core.analysis.health import HealthFindingData, Severity+from repowise.core.analysis.health.scoring import score_filefrom .conftest import python_complex@@ -148,3 +151,79 @@ def test_line_movement_alone_keeps_the_finding_key_stable():original = finding(line=10, symbol="handler")assert finding_key(moved) == finding_key(original)+++# -- a capped category must not report its survivors as worsened -------------+++def _scored(specs: list[tuple[str, str, int]]) -> list[HealthFindingData]:+ """Findings carrying the health_impact the real scorer would give them.++ *specs* is ``(marker, symbol, line)``, so the same function keeps the same+ identity on both sides of the comparison.+ """++ class _R:+ def __init__(self, marker: str) -> None:+ self.biomarker_type = marker+ self.severity = Severity.MEDIUM+ self.deduction = None++ _score, impacts = score_file([_R(m) for m, _sym, _line in specs])+ return [+ finding(marker, line=line, symbol=symbol, impact=impact)+ for (marker, symbol, line), impact in zip(specs, impacts, strict=True)+ ]+++def test_deleting_one_finding_does_not_report_its_neighbours_as_worsened():+ """A capped category splits the cap across whatever it holds.++ Remove one finding and every survivor's ``health_impact`` rises, because+ the same cap is shared out fewer ways. Classifying on that number called a+ code-deleting diff a regression in every finding it left behind.+ """+ markers = ["function_hotspot"] * 5 + ["prior_defect", "knowledge_loss", "ownership_risk"]+ specs = [(m, f"fn_{i}", 10 + i * 10) for i, m in enumerate(markers)]+ base = _scored(specs)+ # The head deletes fn_0. Every other function is untouched.+ head = _scored(specs[1:])++ # The premise: the cap binds on both sides and the survivors' impacts rise.+ assert sum(f.health_impact for f in base) == pytest.approx(3.5)+ assert sum(f.health_impact for f in head) == pytest.approx(3.5)+ assert head[0].health_impact > base[1].health_impact++ result = FindingMatcher().match(base, head)+ assert [m.kind for m in result.matched] == ["unchanged"] * len(head)+ assert len(result.resolved) == 1+++def test_a_continuous_marker_still_worsens_when_its_own_deduction_grows():+ """The signal the impact comparison exists for.++ ``coverage_gradient`` holds one severity and varies a continuous+ deduction, so only that number can say coverage got worse. Held here with+ ``health_impact`` identical on both sides, so the verdict cannot come from+ it.+ """++ def gradient(uncovered: float) -> HealthFindingData:+ return HealthFindingData(+ biomarker_type="coverage_gradient",+ severity=Severity.MEDIUM,+ file_path="app.py",+ function_name=None,+ line_start=None,+ line_end=None,+ details={"deduction": round(4.0 * uncovered, 4)},+ health_impact=0.5,+ reason="",+ dimension="defect",+ )++ worse = FindingMatcher().match([gradient(0.2)], [gradient(0.6)]).matched+ assert [m.kind for m in worse] == ["worsened"]++ better = FindingMatcher().match([gradient(0.6)], [gradient(0.2)]).matched+ assert [m.kind for m in better] == ["unchanged"]diff --git a/tests/unit/pipeline/test_load_stored_function_mod_p80.py b/tests/unit/pipeline/test_load_stored_function_mod_p80.pyindex 7ae543f63..2bf3d343b 100644--- a/tests/unit/pipeline/test_load_stored_function_mod_p80.py+++ b/tests/unit/pipeline/test_load_stored_function_mod_p80.py@@ -107,3 +107,75 @@ async def test_loader_empty_rollup_returns_none(tmp_path):await engine.dispose()assert await load_stored_function_mod_p80(repo_path) is None+++# -- the stored full-repo value wins over the collapsed rollup ---------------+++async def _seed_p80(repo_path, value: int) -> None:+ """Record what a full index measured, the way ``persist`` does."""+ from repowise.core.persistence.crud import set_repo_function_mod_p80++ engine = create_engine(resolve_db_url(repo_path))+ try:+ async with get_session(create_session_factory(engine)) as session:+ repo = await get_repository_by_path(session, str(repo_path))+ await set_repo_function_mod_p80(session, repo.id, value)+ await session.commit()+ finally:+ await engine.dispose()+++async def test_the_stored_full_repo_value_is_preferred_over_the_rollup(tmp_path):+ """The rollup cannot answer this, so it is not asked when it need not be.++ ``git_function_blame`` is keyed ``{path}::{name}``, so a file's same-named+ functions collapse to one row. Here two pairs share a name, and the rollup+ keeps one of each, so its percentile is taken over four samples where the+ full index saw six.+ """+ repo_path = tmp_path / "repo"+ repo_path.mkdir()+ await _seed(+ repo_path,+ [+ _row("a.py::dup", mods=1),+ _row("a.py::dup", mods=2),+ _row("a.py::other", mods=2),+ _row("b.py::dup", mods=3),+ _row("b.py::dup", mods=4),+ _row("b.py::other", mods=9),+ ],+ )++ # The premise: the rollup collapsed the duplicates and answers from what is+ # left, which is not what a full index measured.+ from_rollup = await load_stored_function_mod_p80(repo_path)+ assert from_rollup is not None++ await _seed_p80(repo_path, 4)+ assert await load_stored_function_mod_p80(repo_path) == 4+++async def test_the_stored_value_survives_a_rollup_that_cannot_answer(tmp_path):+ """A stored value is enough on its own: the rollup is a fallback, not a gate."""+ repo_path = tmp_path / "repo"+ repo_path.mkdir()+ await _seed(repo_path, [_row("a.py::f", mods=0)])+ assert await load_stored_function_mod_p80(repo_path) is None++ await _seed_p80(repo_path, 6)+ assert await load_stored_function_mod_p80(repo_path) == 6+++def test_an_incremental_run_never_offers_its_subset_as_the_repo_wide_value():+ """``_full_repo_p80`` is the gate on what may be stored.++ An incremental run sees the changed files alone, and a run handed an+ override measured nothing, so neither may publish a repo-wide percentile.+ """+ from repowise.core.analysis.health.engine import _full_repo_p80++ assert _full_repo_p80(7, None, None) == 7+ assert _full_repo_p80(7, {"src/a.py"}, None) is None+ assert _full_repo_p80(7, None, 7) is None