Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

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.py
new file mode 100644
index 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.py
index 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 annotations
from dataclasses import dataclass, field
from ..health import HealthFindingData
+from ..health.aggregation import finding_raw_deduction
from .identity import finding_key, line_distance, normalize_path, severity_rank
from .models import ChangeKind, FindingKey
@@ -120,6 +121,6 @@ def _classify(base: HealthFindingData | None, head: HealthFindingData) -> Change
return "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.py
index 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.py
index 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 None
else _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 None
else _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.py
index 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 disabled
diff --git a/packages/core/src/repowise/core/persistence/crud/repository.py b/packages/core/src/repowise/core/persistence/crud/repository.py
index 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.py
index 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 file
diff --git a/packages/core/src/repowise/core/pipeline/incremental.py b/packages/core/src/repowise/core/pipeline/incremental.py
index 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 = No
repo = 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_p80
return _percentile_p80(counts)
diff --git a/packages/core/src/repowise/core/pipeline/persist.py b/packages/core/src/repowise/core/pipeline/persist.py
index 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.py
index 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_BYTES
from repowise.core.analysis.change_health.identity import change_finding_id, finding_key
from repowise.core.analysis.change_health.matcher import FindingMatcher
@@ -9,6 +11,7 @@ from repowise.core.analysis.change_health.models import FindingKey
from repowise.core.analysis.change_health.service import ChangeHealthDeltaService, DeltaRequest
from repowise.core.analysis.change_health.sources import GitRevisionSource
from repowise.core.analysis.health import HealthFindingData, Severity
+from repowise.core.analysis.health.scoring import score_file
from .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.py
index 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