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): 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.py
new file mode 100644
index 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.py
index 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 Severity
from .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.py
index 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* that
commit — 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 is
silent.
"""
from __future__ import annotations
from ..models import Severity
+from ..semantics import format_top_percentile
from .base import BiomarkerResult, FileContext
_WINDOW_DAYS = 180
+_MIN_PERCENTILE = 0.80
def _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.py
index 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 it
through 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.py
index 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.py
index 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.py
index 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+) and
PostgreSQL.
+ ``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 a
positive 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 crank
FROM git_metadata
WHERE 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_metadata
SET 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.py
index 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; see
diff --git a/tests/unit/health/test_coverage_biomarkers.py b/tests/unit/health/test_coverage_biomarkers.py
index 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.py
index 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) == 1
assert 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