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): rank the remaining history gates against the repository (#2438)
Raghav Chamadiya9b7e6ef15f13
diff --git a/packages/core/alembic/versions/0072_git_prior_defect_pct.py b/packages/core/alembic/versions/0072_git_prior_defect_pct.pynew file mode 100644index 000000000..c3e96b7b6--- /dev/null+++ b/packages/core/alembic/versions/0072_git_prior_defect_pct.py@@ -0,0 +1,45 @@+"""git_metadata: rank prior_defect_count repo-relative.++Six months is a fixed window, so a repository landing many commits a day+accumulates more fix commits per file inside it than a quiet one, and an entry+gate of one fix then fires on a large share of the tree. This column ranks the+count over the repository, ties sharing a rank, so the gate is a share rather+than a fixed number of fixes.++Defaults to 0, which leaves ``prior_defect`` silent until the next index or+update repopulates it. Unlike the co-change breadth columns it is derivable+from data already stored, so ``recompute_git_percentiles`` fills it in without+a re-walk.++Local SQLite stores never run Alembic -- ``init_db``'s reconciler issues+additive DDL for missing columns -- so this migration exists for managed+Postgres.++Revision ID: 0072+Revises: 0071+Create Date: 2026-09-19+"""++from __future__ import annotations++from collections.abc import Sequence++import sqlalchemy as sa+from alembic import op++# revision identifiers+revision: str = "0072"+down_revision: str | None = "0071"+branch_labels: str | Sequence[str] | None = None+depends_on: str | Sequence[str] | None = None+++def upgrade() -> None:+ op.add_column(+ "git_metadata",+ sa.Column("prior_defect_pct", sa.Float, nullable=False, server_default="0.0"),+ )+++def downgrade() -> None:+ op.drop_column("git_metadata", "prior_defect_pct")diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/developer_congestion.py b/packages/core/src/repowise/core/analysis/health/biomarkers/developer_congestion.pyindex edf4e33f3..9c61e1f90 100644--- a/packages/core/src/repowise/core/analysis/health/biomarkers/developer_congestion.py+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/developer_congestion.py@@ -7,7 +7,9 @@ correlated with regression rates in published industry studies.Fires when ALL of:- ``contributor_count`` ≥ 5-- ``commit_count_90d`` ≥ 6 (the file is genuinely active)+- ``churn_percentile`` ≥ 0.75 (the file is genuinely active *for this+ repository* — a fixed commit count is a different bar on a repository+ landing dozens a day than on one landing a handful a week)- the primary owner's share is below 50% (no clear DRI)Reads ``ctx.git_meta`` only; no AST work needed.@@ -19,7 +21,7 @@ from ..models import Severityfrom .base import BiomarkerResult, FileContext_CONTRIB_THRESHOLD = 5-_RECENT_COMMITS_THRESHOLD = 6+_CHURN_PERCENTILE_FLOOR = 0.75_OWNER_SHARE_THRESHOLD = 0.5@@ -49,7 +51,10 @@ class DeveloperCongestionDetector:if contributors < _CONTRIB_THRESHOLD:return []- if commits_90d < _RECENT_COMMITS_THRESHOLD:+ # "Actively changing" has to mean actively changing for this repository:+ # a fixed count of commits in 90 days is a different bar on a repository+ # landing a handful a week than on one landing dozens a day.+ if _as_float(meta.get("churn_percentile")) < _CHURN_PERCENTILE_FLOOR:return []# primary_owner_commit_pct may be stored as a 0-1 fraction or# 0-100 percentage depending on the source - normalize.diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/prior_defect.py b/packages/core/src/repowise/core/analysis/health/biomarkers/prior_defect.pyindex 909209b6a..c836e5e90 100644--- a/packages/core/src/repowise/core/analysis/health/biomarkers/prior_defect.py+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/prior_defect.py@@ -12,24 +12,33 @@ same keyword rule the benchmark labels fixes with, and anchored to the index's``as_of`` reference so a historical/T0 checkout measures the window *before* thatcommit — no leakage from future fixes. This biomarker is the consumer.-Fires whenever the file carries ≥1 prior fix; severity scales with the count-(and escalates on hotspots, where recent defect history compounds high churn):+Fires when the file's fix count is in the top fifth *for this repository*+(``prior_defect_pct`` ≥ 0.80). The count itself is not repo-relative: six+months is a fixed window, so a repository landing many commits a day+accumulates more fixes per file inside it than a quiet one, and an entry gate+of one fix then fires on a large share of the tree. Ranking the count decides+the entry; the ladder below, which the benchmark calibrated, decides severity:- 1 fix -> LOW- 2 fixes -> MEDIUM- 3-4 fixes -> HIGH (CRITICAL if also a churn hotspot)- 5+ fixes -> CRITICAL-When git indexing was skipped the field is absent/zero and the detector is+The rank is taken over every file, ties sharing a rank, because a file with no+fixes in the window was measured and found clean rather than not measured.++When git indexing was skipped the fields are absent/zero and the detector issilent."""from __future__ import annotationsfrom ..models import Severity+from ..semantics import format_top_percentilefrom .base import BiomarkerResult, FileContext_WINDOW_DAYS = 180+_MIN_PERCENTILE = 0.80def _as_int(value: object, default: int = 0) -> int:@@ -39,6 +48,13 @@ def _as_int(value: object, default: int = 0) -> int:return default+def _as_float(value: object, default: float = 0.0) -> float:+ try:+ return float(value) # type: ignore[arg-type]+ except (TypeError, ValueError):+ return default++class PriorDefectDetector:name = "prior_defect"category = "organizational"@@ -48,6 +64,9 @@ class PriorDefectDetector:count = _as_int(meta.get("prior_defect_count"))if count < 1:return []+ percentile = _as_float(meta.get("prior_defect_pct"))+ if percentile < _MIN_PERCENTILE:+ return []is_hotspot = bool(meta.get("is_hotspot"))if count >= 5:@@ -69,12 +88,15 @@ class PriorDefectDetector:line_end=None,details={"prior_defect_count": count,+ # 0-100, as every other emitted percentile.+ "prior_defect_pct": round(percentile * 100.0, 1),"window_days": _WINDOW_DAYS,},reason=(- f"{count} bug-{fixes} touched this file in the last "- f"~6 months; recent defect history is the strongest "- f"cost-effective predictor of further defects"+ f"{count} bug-{fixes} touched this file in the last ~6 months "+ f"({format_top_percentile(percentile, 'files in this repository')}); "+ f"recent defect history is the strongest cost-effective "+ f"predictor of further defects"),)]diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/untested_hotspot.py b/packages/core/src/repowise/core/analysis/health/biomarkers/untested_hotspot.pyindex 600266cdd..988772f49 100644--- a/packages/core/src/repowise/core/analysis/health/biomarkers/untested_hotspot.py+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/untested_hotspot.py@@ -2,7 +2,8 @@Fires when a file is **all three** of:-- a *hotspot* (``git_meta['is_hotspot']`` true OR commit_count_90d ≥ 8)+- a *hotspot* (``git_meta['is_hotspot']``, which is top-quartile churn with+ absolute activity floors under it)- under-tested (``line_coverage_pct`` < 40 when coverage is available,OR, when it isn't, neither a paired test file nor a test reaching itthrough the call graph)@@ -29,24 +30,17 @@ from .base import BiomarkerResult, FileContext_COVERAGE_LOW = 40.0_COVERAGE_VERY_LOW = 15.0_DEPENDENTS_THRESHOLD = 4-_COMMITS_90D_THRESHOLD = 8--def _is_hotspot(ctx: FileContext) -> bool:- meta = ctx.git_meta or {}- if bool(meta.get("is_hotspot")):- return True- try:- if int(meta.get("commit_count_90d", 0) or 0) >= _COMMITS_90D_THRESHOLD:- return True- except (TypeError, ValueError):- pass- try:- if float(meta.get("temporal_hotspot_score", 0.0) or 0.0) >= 0.8:- return True- except (TypeError, ValueError):- pass- return False+ """The repository's own hotspot verdict, and only that.++ This used to widen it with two absolute alternatives -- eight commits in 90+ days, or a decayed churn score over 0.8 -- either of which a busy repository+ clears for a large share of its files while a quiet one never clears at all.+ ``is_hotspot`` is already top-quartile churn with activity floors under it,+ so the alternatives only ever made the gate less repo-relative, never more+ informative.+ """+ return bool((ctx.git_meta or {}).get("is_hotspot"))class UntestedHotspotDetector:diff --git a/packages/core/src/repowise/core/ingestion/git_indexer/enrich.py b/packages/core/src/repowise/core/ingestion/git_indexer/enrich.pyindex d5409162e..56a2ac902 100644--- a/packages/core/src/repowise/core/ingestion/git_indexer/enrich.py+++ b/packages/core/src/repowise/core/ingestion/git_indexer/enrich.py@@ -211,6 +211,39 @@ def _rank_within_eligible(metadata_list[idx][target_key] = rank / n+def _rank_over_population(+ metadata_list: list[dict],+ *,+ source_key: str,+ target_key: str,+) -> None:+ """Rank *source_key* over every file, with tied values sharing a rank.++ For a signal whose zero is a measurement rather than an absent one: a file+ with no bug-fixes in the window was measured and found clean, unlike a file+ with no co-change history, so excluding the zeros would rank a count+ against the wrong denominator.++ Ties share a rank because the source is a small integer. Spreading a tie+ group across consecutive ranks would put two files with the same count on+ opposite sides of a gate, decided by sort order alone. Mirrors SQL+ ``PERCENT_RANK``: the share of the population scoring strictly lower.+ """+ values = [float(m.get(source_key) or 0.0) for m in metadata_list]+ n = len(values)+ if n < 2:+ for meta in metadata_list:+ meta[target_key] = 0.0+ return+ below: dict[float, float] = {}+ running = 0+ for value in sorted(set(values)):+ below[value] = running / (n - 1)+ running += sum(1 for v in values if v == value)+ for meta, value in zip(metadata_list, values, strict=True):+ meta[target_key] = min(below[value], 1.0)++def compute_percentiles(metadata_list: list[dict]) -> None:"""Compute churn_percentile, is_hotspot, and the history percentiles.@@ -256,3 +289,9 @@ def compute_percentiles(metadata_list: list[dict]) -> None:_rank_within_eligible(metadata_list, source_key="co_change_mass", target_key="co_change_scatter_pct")++ # Bug-fix history, ranked over every file: a file with no fixes in the+ # window is a measured zero, not a missing signal.+ _rank_over_population(+ metadata_list, source_key="prior_defect_count", target_key="prior_defect_pct"+ )diff --git a/packages/core/src/repowise/core/ingestion/git_indexer/file_history.py b/packages/core/src/repowise/core/ingestion/git_indexer/file_history.pyindex 77fc71a5c..412a34d04 100644--- a/packages/core/src/repowise/core/ingestion/git_indexer/file_history.py+++ b/packages/core/src/repowise/core/ingestion/git_indexer/file_history.py@@ -131,6 +131,8 @@ def new_meta(file_path: str) -> dict[str, Any]:# variant is the same walk before fix-shape filtering (fix_shape.py)."prior_defect_count": 0,"prior_defect_raw_count": 0,+ # Repo-relative rank of prior_defect_count; see enrich.compute_percentiles.+ "prior_defect_pct": 0.0,# Agent provenance rollup: how much of this file's indexed history is# agent-attributed (local channels only — see agent_provenance module).# agent_authored_pct stays None when the file has no commits at all.diff --git a/packages/core/src/repowise/core/persistence/crud/git.py b/packages/core/src/repowise/core/persistence/crud/git.pyindex 7c49f3478..dcb2a7f96 100644--- a/packages/core/src/repowise/core/persistence/crud/git.py+++ b/packages/core/src/repowise/core/persistence/crud/git.py@@ -256,6 +256,9 @@ async def recompute_git_percentiles(churn); commit_count_90d is the tiebreak. Works on both SQLite (3.25+) andPostgreSQL.+ ``prior_defect_pct`` ranks over the whole table, ties sharing a rank, since+ a file with no fixes in the window is a measured zero.+``change_entropy_pct`` and ``co_change_scatter_pct`` mirror``enrich._rank_within_eligible``: ``ROW_NUMBER`` over the files carrying apositive signal, over how many of them there are. Ranking them over the@@ -307,6 +310,12 @@ scatter_ranked AS (WHERE repository_id = :repo_id AND COALESCE(co_change_mass, 0.0) > 0.0) AS crankFROM git_metadataWHERE repository_id = :repo_id AND COALESCE(co_change_mass, 0.0) > 0.0+),+defect_ranked AS (+ SELECT id,+ PERCENT_RANK() OVER (ORDER BY COALESCE(prior_defect_count, 0)) AS drank+ FROM git_metadata+ WHERE repository_id = :repo_id)UPDATE git_metadataSET churn_percentile = (SELECT prank FROM ranked WHERE ranked.id = git_metadata.id),@@ -318,7 +327,9 @@ SET churn_percentile = (SELECT prank FROM ranked WHERE ranked.id = git_metadata.change_entropy_pct = COALESCE((SELECT erank FROM entropy_ranked WHERE entropy_ranked.id = git_metadata.id), 0.0),co_change_scatter_pct = COALESCE(- (SELECT crank FROM scatter_ranked WHERE scatter_ranked.id = git_metadata.id), 0.0)+ (SELECT crank FROM scatter_ranked WHERE scatter_ranked.id = git_metadata.id), 0.0),+ prior_defect_pct = COALESCE(+ (SELECT drank FROM defect_ranked WHERE defect_ranked.id = git_metadata.id), 0.0)WHERE repository_id = :repo_id;"""await session.execute(diff --git a/packages/core/src/repowise/core/persistence/models.py b/packages/core/src/repowise/core/persistence/models.pyindex c06b536c2..5679db646 100644--- a/packages/core/src/repowise/core/persistence/models.py+++ b/packages/core/src/repowise/core/persistence/models.py@@ -651,6 +651,11 @@ class GitMetadata(Base):co_change_mass: Mapped[float] = mapped_column(Float, nullable=False, default=0.0)co_change_scatter_pct: Mapped[float] = mapped_column(Float, nullable=False, default=0.0)+ # Repo-relative rank of prior_defect_count, so the entry gate is a share of+ # this repository rather than a fixed number of fixes in six months, which+ # a busy repository clears for most of its files.+ prior_defect_pct: Mapped[float] = mapped_column(Float, nullable=False, default=0.0)+# Agent-provenance rollup: how much of this file's indexed history is# agent-attributed (deterministic local-channel classification — identity# fields, message footers, co-author trailers; seediff --git a/tests/unit/health/test_coverage_biomarkers.py b/tests/unit/health/test_coverage_biomarkers.pyindex fe12721b7..c9c5db26e 100644--- a/tests/unit/health/test_coverage_biomarkers.py+++ b/tests/unit/health/test_coverage_biomarkers.py@@ -74,7 +74,7 @@ def test_untested_hotspot_silent_when_well_covered() -> None:def test_untested_hotspot_falls_back_when_no_coverage_data() -> None:ctx = _ctx(- git_meta={"commit_count_90d": 12},+ git_meta={"commit_count_90d": 12, "is_hotspot": True},dependents=6,has_test_file=False,)@@ -83,9 +83,20 @@ def test_untested_hotspot_falls_back_when_no_coverage_data() -> None:assert "no coverage data" in results[0].reason+def test_untested_hotspot_needs_the_repo_hotspot_verdict() -> None:+ """A raw commit count is a different bar on a busy repository than on a+ quiet one, so the gate is is_hotspot, which is already repo-relative."""+ ctx = _ctx(+ git_meta={"commit_count_90d": 12, "temporal_hotspot_score": 4.0},+ dependents=6,+ has_test_file=False,+ )+ assert UntestedHotspotDetector().detect(ctx) == []++def test_untested_hotspot_skips_when_paired_test_present() -> None:ctx = _ctx(- git_meta={"commit_count_90d": 12},+ git_meta={"commit_count_90d": 12, "is_hotspot": True},dependents=6,has_test_file=True,)diff --git a/tests/unit/health/test_organizational_biomarkers.py b/tests/unit/health/test_organizational_biomarkers.pyindex 9ff13e4bd..32905ba4f 100644--- a/tests/unit/health/test_organizational_biomarkers.py+++ b/tests/unit/health/test_organizational_biomarkers.py@@ -53,6 +53,7 @@ def test_developer_congestion_fires_on_crowded_hotspot():meta = {"contributor_count": 12,"commit_count_90d": 25,+ "churn_percentile": 0.9,"primary_owner_commit_pct": 0.25,"primary_owner_name": "Alice",}@@ -66,6 +67,7 @@ def test_developer_congestion_normalizes_percent_form():meta = {"contributor_count": 6,"commit_count_90d": 8,+ "churn_percentile": 0.8,"primary_owner_commit_pct": 30.0, # percent form}out = DeveloperCongestionDetector().detect(_ctx(meta))@@ -77,15 +79,19 @@ def test_developer_congestion_skips_with_clear_owner():meta = {"contributor_count": 8,"commit_count_90d": 15,+ "churn_percentile": 0.9,"primary_owner_commit_pct": 0.65,}assert DeveloperCongestionDetector().detect(_ctx(meta)) == []-def test_developer_congestion_skips_low_activity():+def test_developer_congestion_skips_quiet_files_for_this_repo():+ """The activity gate is the repository's own churn ranking. A busy file by+ absolute count is not busy if most of the repository is busier."""meta = {"contributor_count": 8,- "commit_count_90d": 2,+ "commit_count_90d": 15,+ "churn_percentile": 0.4,"primary_owner_commit_pct": 0.2,}assert DeveloperCongestionDetector().detect(_ctx(meta)) == []@@ -493,8 +499,15 @@ def test_co_change_scatter_exempts_a_barrel_named_file_even_with_logic():# ---- prior_defect --------------------------------------------------------+def _pd(count: int, **over) -> dict:+ """Fix history for a file in the top fifth of this repository."""+ meta = {"prior_defect_count": count, "prior_defect_pct": 0.9}+ meta.update(over)+ return meta++def test_prior_defect_fires_low_on_single_fix():- out = PriorDefectDetector().detect(_ctx({"prior_defect_count": 1}))+ out = PriorDefectDetector().detect(_ctx(_pd(1)))assert len(out) == 1assert out[0].severity == "low"assert out[0].details["prior_defect_count"] == 1@@ -502,19 +515,33 @@ def test_prior_defect_fires_low_on_single_fix():def test_prior_defect_scales_severity_with_count():- assert PriorDefectDetector().detect(_ctx({"prior_defect_count": 2}))[0].severity == "medium"- assert PriorDefectDetector().detect(_ctx({"prior_defect_count": 3}))[0].severity == "high"- assert PriorDefectDetector().detect(_ctx({"prior_defect_count": 6}))[0].severity == "critical"+ assert PriorDefectDetector().detect(_ctx(_pd(2)))[0].severity == "medium"+ assert PriorDefectDetector().detect(_ctx(_pd(3)))[0].severity == "high"+ assert PriorDefectDetector().detect(_ctx(_pd(6)))[0].severity == "critical"def test_prior_defect_escalates_to_critical_on_hotspot():# A mid-band count (3) on a churn hotspot compounds to CRITICAL.- meta = {"prior_defect_count": 3, "is_hotspot": True}- out = PriorDefectDetector().detect(_ctx(meta))+ out = PriorDefectDetector().detect(_ctx(_pd(3, is_hotspot=True)))assert out[0].severity == "critical"def test_prior_defect_silent_without_prior_fixes():# No defect history (or ESSENTIAL tier where the field is absent) → silent.- assert PriorDefectDetector().detect(_ctx({"prior_defect_count": 0})) == []+ assert PriorDefectDetector().detect(_ctx(_pd(0))) == []assert PriorDefectDetector().detect(_ctx({"commit_count_90d": 9})) == []+++def test_prior_defect_silent_below_the_repo_percentile():+ """Six months is a fixed window, so on a repository landing many commits a+ day most files carry a fix or two. The entry is a share of the repository,+ which is what stops the signal firing on half the tree."""+ assert PriorDefectDetector().detect(_ctx(_pd(2, prior_defect_pct=0.5))) == []+++def test_prior_defect_keeps_the_calibrated_ladder_above_the_gate():+ """Only the entry moved. Above it the count still decides the band, so a+ file reports the severity the benchmark calibrated for its fix count."""+ out = PriorDefectDetector().detect(_ctx(_pd(6, prior_defect_pct=0.81)))+ assert out[0].severity == "critical"+ assert out[0].details["prior_defect_pct"] == 81.0