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.

feat(health): add prior-defect process signal (#312)

Raghav Chamadiya455ec5f2311d
diff --git a/docs/CODE_HEALTH.md b/docs/CODE_HEALTH.md
index 279ec848b..1cf4a2813 100644
--- a/docs/CODE_HEALTH.md
+++ b/docs/CODE_HEALTH.md
@@ -1,11 +1,11 @@
# Code Health
-Repowise computes a 1–10 health score for every file in your repo from twenty-three
+Repowise computes a 1–10 health score for every file in your repo from twenty-four
deterministic biomarkers — McCabe complexity, deep nesting, brain methods,
class cohesion (LCOM4), god classes, clone detection, untested hotspots,
function-level churn, code-age volatility,
ownership dispersion, relative churn, change entropy, co-change scatter,
-test-quality smells, and more. **No LLM calls, no cloud requirement.** Pure
+recent defect history, test-quality smells, and more. **No LLM calls, no cloud requirement.** Pure
Python over tree-sitter + git data, designed to finish in under 30 seconds on a
3 000-file repo.
@@ -297,7 +297,7 @@ Health: 7.4 (avg) · 6.2 (hotspots) · 2.1 (worst: payments/processor.ts)
| Feature | Repowise | CodeScene | DeepSource | Sourcery |
|----------------------------------|:--:|:--:|:--:|:--:|
-| Code health score (1–10) | ✅ 23 biomarkers | ✅ 25–30 | ❌ | ❌ |
+| Code health score (1–10) | ✅ 24 biomarkers | ✅ 25–30 | ❌ | ❌ |
| Brain Method detection | ✅ | ✅ | ❌ | ❌ |
| Low cohesion (LCOM4) / god class | ✅ | ✅ | ❌ | ❌ |
| Test coverage intelligence | ✅ LCOV/Cobertura/Clover/JSON | ❌ | ❌ | ❌ |
diff --git a/docs/architecture/code-health.md b/docs/architecture/code-health.md
index 205c274d4..c2e1d4230 100644
--- a/docs/architecture/code-health.md
+++ b/docs/architecture/code-health.md
@@ -317,7 +317,7 @@ higher than dormant ones.
---
-## 5. The 23 biomarkers and their categories
+## 5. The 24 biomarkers and their categories
Each biomarker is a stateless class implementing the `Biomarker` Protocol
from `biomarkers/base.py`:
@@ -331,7 +331,7 @@ class Biomarker(Protocol):
| Category | Cap | Biomarkers |
|------------------------|------|------------|
-| Organizational | −3.5 | developer_congestion, knowledge_loss, hidden_coupling, function_hotspot, code_age_volatility, ownership_risk, churn_risk, change_entropy, co_change_scatter |
+| Organizational | −3.5 | developer_congestion, knowledge_loss, hidden_coupling, function_hotspot, code_age_volatility, ownership_risk, churn_risk, change_entropy, co_change_scatter, prior_defect |
| Structural complexity | −2.5 | brain_method, low_cohesion, god_class, nested_complexity, bumpy_road, complex_conditional |
| Test coverage | −2.0 | untested_hotspot, coverage_gap |
| Size & complexity | −1.5 | complex_method, large_method, primitive_obsession |
@@ -355,6 +355,23 @@ co-change coupling, D'Ambros) are likewise git-only and read the
`co_change_partners_json`. `knowledge_loss` is activity-gated so
abandoned-but-stable files (the survivor effect) no longer fire.
+`prior_defect` (recent bug-fix history, Ostrand-Weyuker / Kim's "bug cache")
+is the other git-only process signal: the count of bug-fix commits touching a
+file in the trailing ~6-month window, read from `prior_defect_count`. The
+git indexer classifies a commit as a fix with the **same keyword rule the
+defect benchmark labels fixes with** (`_constants.is_fix_commit`), counts only
+non-merge commits inside the window, and anchors the window to the index's
+`as_of` reference (`REPOWISE_GIT_WINDOW_ANCHOR`) — so scoring a historical T0
+checkout measures the fixes *before* T0, never leaking the post-T0 fixes that
+form the benchmark's labels. It carries a **neutral (1.0) weight by design**:
+on the calibration corpus prior-defect history is largely redundant with the
+existing process signals (correlation ≈ +0.59 with `change_entropy`, +0.38 with
+churn; calibrated coefficient ≈ +0.02, effort-aware Popt gain within bootstrap
+noise), so it is not boosted as a predictor. It ships for its **explanatory**
+value — "this file was bug-fixed N times recently" is immediately actionable,
+and it uniquely flags a few files the other signals miss — not for a measured
+accuracy lift.
+
`low_cohesion` (LCOM4) and `god_class` are the two **class-level**
structural smells. They read `ctx.class_metrics`, the per-class aggregates
the walker now emits alongside per-function metrics (see §5.2).
diff --git a/packages/core/alembic/versions/0026_git_prior_defect_count.py b/packages/core/alembic/versions/0026_git_prior_defect_count.py
new file mode 100644
index 000000000..f3fb97a80
--- /dev/null
+++ b/packages/core/alembic/versions/0026_git_prior_defect_count.py
@@ -0,0 +1,35 @@
+"""Add prior_defect_count column to git_metadata.
+
+Stores the count of bug-fix commits touching a file in the trailing ~6-month
+defect window (anchored to the index's as_of reference so historical/T0 scoring
+stays leakage-free). Computed during per-file git history indexing and consumed
+by the ``prior_defect`` health biomarker.
+
+Revision ID: 0026
+Revises: 0025
+Create Date: 2026-05-29
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers
+revision: str = "0026"
+down_revision: str | None = "0025"
+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_count", sa.Integer, nullable=False, server_default="0"),
+ )
+
+
+def downgrade() -> None:
+ op.drop_column("git_metadata", "prior_defect_count")
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/README.md b/packages/core/src/repowise/core/analysis/health/biomarkers/README.md
index ce44a80f7..53d4049f3 100644
--- a/packages/core/src/repowise/core/analysis/health/biomarkers/README.md
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/README.md
@@ -9,7 +9,7 @@ class Biomarker(Protocol):
def detect(self, ctx: FileContext) -> list[BiomarkerResult]: ...
```
-## Registered detectors (23)
+## Registered detectors (24)
Structural complexity (cap −2.5):
- `brain_method` — symbols simultaneously long, complex, and central. The
@@ -56,6 +56,14 @@ Organizational (cap −3.5):
- `co_change_scatter` — breadth of co-change coupling: a file coupled to
many others (shotgun surgery). Complements `hidden_coupling`, which
flags specific undeclared pairs.
+- `prior_defect` — recent bug-fix history: the count of bug-fix commits
+ touching the file in the trailing ~6-month window (same keyword rule the
+ defect benchmark labels fixes with, anchored to the index's `as_of`
+ reference so historical/T0 scoring stays leakage-free). Reads the
+ `prior_defect_count` git field. **Neutral weight (1.0) by design** — on the
+ calibration corpus it is largely redundant with `change_entropy`/`churn_risk`
+ (no measured lift), so it ships as an interpretable, actionable finding
+ ("bug-fixed N times recently") rather than a boosted predictor.
Test quality (cap −0.5, test files only):
- `large_assertion_block` — a test function with a run of ≥ 15 consecutive
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
new file mode 100644
index 000000000..909209b6a
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/prior_defect.py
@@ -0,0 +1,83 @@
+"""Prior Defect — a file with recent bug-fix history.
+
+Defects cluster: the single strongest cheap predictor of "will this file be
+bug-fixed soon" is "was it bug-fixed recently" (Ostrand & Weyuker; Kim et al.
+"bug cache"). On the defect benchmark the prior-defects baseline is the most
+cost-effective signal (highest Popt) — it flags only files that already proved
+fragile, so inspecting them per line of code catches defects efficiently.
+
+The git indexer counts, per file, the bug-fix commits touching it in the
+trailing ~6-month window (``git_meta["prior_defect_count"]``), classified by the
+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):
+
+- 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
+silent.
+"""
+
+from __future__ import annotations
+
+from ..models import Severity
+from .base import BiomarkerResult, FileContext
+
+_WINDOW_DAYS = 180
+
+
+def _as_int(value: object, default: int = 0) -> int:
+ try:
+ return int(value or 0) # type: ignore[arg-type]
+ except (TypeError, ValueError):
+ return default
+
+
+class PriorDefectDetector:
+ name = "prior_defect"
+ category = "organizational"
+
+ def detect(self, ctx: FileContext) -> list[BiomarkerResult]:
+ meta = ctx.git_meta or {}
+ count = _as_int(meta.get("prior_defect_count"))
+ if count < 1:
+ return []
+
+ is_hotspot = bool(meta.get("is_hotspot"))
+ if count >= 5:
+ severity = Severity.CRITICAL
+ elif count >= 3:
+ severity = Severity.CRITICAL if is_hotspot else Severity.HIGH
+ elif count >= 2:
+ severity = Severity.MEDIUM
+ else:
+ severity = Severity.LOW
+
+ fixes = "fix" if count == 1 else "fixes"
+ return [
+ BiomarkerResult(
+ biomarker_type=self.name,
+ severity=severity,
+ function_name=None,
+ line_start=None,
+ line_end=None,
+ details={
+ "prior_defect_count": count,
+ "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"
+ ),
+ )
+ ]
+
+
+BIOMARKER = PriorDefectDetector()
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/registry.py b/packages/core/src/repowise/core/analysis/health/biomarkers/registry.py
index 614bdcc70..967095e10 100644
--- a/packages/core/src/repowise/core/analysis/health/biomarkers/registry.py
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/registry.py
@@ -34,6 +34,7 @@ from .low_cohesion import LowCohesionDetector
from .nested_complexity import NestedComplexityDetector
from .ownership_risk import OwnershipRiskDetector
from .primitive_obsession import PrimitiveObsessionDetector
+from .prior_defect import PriorDefectDetector
from .untested_hotspot import UntestedHotspotDetector
_DETECTOR_FACTORIES: list[type[Biomarker]] = [
@@ -58,6 +59,7 @@ _DETECTOR_FACTORIES: list[type[Biomarker]] = [
ChurnRiskDetector, # type: ignore[list-item]
ChangeEntropyDetector, # type: ignore[list-item]
CoChangeScatterDetector, # type: ignore[list-item]
+ PriorDefectDetector, # type: ignore[list-item]
LargeAssertionBlockDetector, # type: ignore[list-item]
DuplicatedAssertionBlockDetector, # type: ignore[list-item]
]
diff --git a/packages/core/src/repowise/core/analysis/health/scoring.py b/packages/core/src/repowise/core/analysis/health/scoring.py
index 08210d81d..a41a0d12a 100644
--- a/packages/core/src/repowise/core/analysis/health/scoring.py
+++ b/packages/core/src/repowise/core/analysis/health/scoring.py
@@ -82,6 +82,16 @@ _BIOMARKER_WEIGHT_MULTIPLIER: dict[str, float] = {
"complex_method": 1.21,
"function_hotspot": 1.16,
"god_class": 1.13,
+ # Prior-defect history (recent bug-fix count). NEUTRAL weight by design, not
+ # a boost: on the 13-repo corpus its calibrated coefficient is ~+0.02 (no lift
+ # beyond size + the existing process signals — it correlates +0.59 with
+ # change_entropy, +0.38 with churn) and the effort-aware Popt gain is +0.01
+ # with bootstrap CIs straddling zero. So it ships as an interpretable,
+ # leakage-free finding ("bug-fixed N times recently" — directly actionable,
+ # and it uniquely flags a handful of files the other signals miss), NOT as a
+ # calibrated predictor. See local-stash/{calibrate_health_weights,
+ # measure_prior_defect,diagnose_prior_defect}.py + the progress doc Phase 8.5.
+ "prior_defect": 1.0,
# --- kept at prior: benchmark could not fairly measure these ---
"untested_hotspot": 1.3, # benchmark ingests no coverage (has_test_file fallback only)
"churn_risk": 1.2, # fired in too few repos to calibrate
@@ -127,6 +137,7 @@ _BIOMARKER_CATEGORY: dict[str, str] = {
"churn_risk": "organizational",
"change_entropy": "organizational",
"co_change_scatter": "organizational",
+ "prior_defect": "organizational",
"large_assertion_block": "test_quality",
"duplicated_assertion_block": "test_quality",
# Governance biomarkers — written by the additive governance pass
diff --git a/packages/core/src/repowise/core/analysis/health/suggestions.py b/packages/core/src/repowise/core/analysis/health/suggestions.py
index df957f248..fc5f496a0 100644
--- a/packages/core/src/repowise/core/analysis/health/suggestions.py
+++ b/packages/core/src/repowise/core/analysis/health/suggestions.py
@@ -136,6 +136,13 @@ _TEMPLATES: dict[str, str] = {
"shared concerns behind a stable boundary, or split it so callers "
"depend on smaller, more cohesive units."
),
+ "prior_defect": (
+ "This file has been bug-fixed repeatedly in recent months — defects "
+ "cluster, so it is among the likeliest places the next bug will land. "
+ "Treat it as fragile: add regression tests around the areas that keep "
+ "breaking, harden input handling, and review changes here with extra "
+ "care before they ship."
+ ),
"large_assertion_block": (
"Split this test. A long run of assertions in one case tests "
"several behaviours at once — when it fails it names a line, not a "
diff --git a/packages/core/src/repowise/core/ingestion/git_indexer/README.md b/packages/core/src/repowise/core/ingestion/git_indexer/README.md
index a2db8eb97..a27fb0302 100644
--- a/packages/core/src/repowise/core/ingestion/git_indexer/README.md
+++ b/packages/core/src/repowise/core/ingestion/git_indexer/README.md
@@ -1,13 +1,40 @@
# `git_indexer`
Mines git history into per-file metadata (ownership, churn, hotspots,
-co-change partners) for the ingestion pipeline.
+co-change, change entropy, prior-defect history) for the ingestion pipeline.
## Purpose
Turn a repository's commit history into the signals the wiki and health
-layers consume: commit counts and recency windows, contributor/bus-factor,
-significant commits, a temporal hotspot score, and co-change relationships.
+layers consume:
+
+- commit counts and recency windows (90d / 30d), file age, `is_stable`;
+- contributor count, bus factor, primary/recent ownership (blame-based on the
+ FULL tier, commit-author fallback otherwise);
+- significant commits + commit-category ratios (feature / fix / refactor / …);
+- a temporal hotspot score (exponentially decayed churn) and repo-wide
+ percentiles (`churn_percentile`, `is_hotspot`);
+- co-change partners and Hassan **change entropy** (History Complexity Metric);
+- per-function blame (modification counts, line age) for function-level health;
+- **prior-defect history** — bug-fix commits touching each file in the trailing
+ window, the most cost-effective defect predictor.
+
+## Window anchoring (`REPOWISE_GIT_WINDOW_ANCHOR`)
+
+Every recency window (90d/30d, age, temporal decay, co-change/entropy decay, the
+prior-defect window) is measured relative to a single reference "now":
+
+- **default (env unset)** → wall-clock `now()`, so "churned lately" means
+ relative to today — the live-product meaning.
+- **`REPOWISE_GIT_WINDOW_ANCHOR=head`** → the repo's most-recent commit
+ timestamp. This makes indexing **deterministic** (re-indexing the same commit
+ yields identical windows) and **correct for historical checkouts**: scoring a
+ worktree detached at an old commit then measures the window *before that
+ commit*, not an empty window in its future. Used by the defect benchmark to
+ score repos at a past T0 without leaking future history into the signals.
+
+`REPOWISE_SKIP_EDITOR_SETUP=1` is the companion guard that lets `init` index a
+transient worktree without touching the developer's global editor config.
## Public API
@@ -19,33 +46,57 @@ Imported via `repowise.core.ingestion.git_indexer`:
- `backfill_full_tier(indexer, repo_id, *, job_store=None)` — promote an
ESSENTIAL index to FULL as a resumable phase.
- Module-level building blocks (unit-tested directly): `index_file`,
- `compute_co_changes`, `compute_percentiles`, `get_blame_ownership`,
- `is_significant_commit`, `detect_original_path`.
+ `compute_co_changes`, `compute_co_changes_and_entropy`, `compute_percentiles`,
+ `compute_prior_defects`, `get_blame_ownership`, `is_significant_commit`,
+ `detect_original_path`, `is_fix_commit`.
## Tiers
-| Tier | Per-file history | `git blame` ownership | Co-change walk |
-|------|------------------|-----------------------|----------------|
+| Tier | Per-file history | `git blame` ownership + per-fn blame | Co-change + entropy |
+|------|------------------|--------------------------------------|---------------------|
| `FULL` (default) | yes | yes | yes |
-| `ESSENTIAL` | yes | no (commit-author fallback) | no |
+| `ESSENTIAL` | yes | no (commit-author fallback) | no (deferred) |
`ESSENTIAL` is for the fast orchestrator path (`--mode fast`) on very large
repos: it skips the two O(repo) signals so a first index lands quickly, then
-`backfill_full_tier` fills in blame + co-change later.
+`backfill_full_tier` fills in blame + co-change/entropy later. The prior-defect
+pass runs on both tiers (it is bounded to the window, not O(repo)).
+
+## Performance: one repo-wide commit index
+
+The naive design spawns one `git log -- <file>` per tracked file — O(files)
+subprocesses. Instead, when rename-tracking is off (the default), `indexer.py`
+builds a single repo-wide commit index once (`git_commit_index.load_commit_index`,
+`git log -<commit_limit> --numstat`) and each per-file worker reads its slice
+from that dict. This caps depth at `_DEFAULT_COMMIT_LIMIT` (the newest N commits)
+to keep `init` inside its time/memory budget.
+
+**Caveat the prior-defect pass works around:** that cap bounds the index by
+*commit count*, so on a hyperactive repo a hot file's slice under-represents a
+wide window. `compute_prior_defects` therefore does NOT read the index — it runs
+its own date-bounded `git log prior_sha..HEAD --name-only` pass, which reaches
+the full window at a fraction of the cost of lifting the global cap (it scales
+with window activity, not total repo age). Windowed-but-decayed signals
+(90d counts, entropy) tolerate the cap because old commits contribute ~nothing.
## Internal layout
| Module | Contents |
|--------|----------|
| `tiers.py` | `GitIndexTier` enum + `includes_blame` / `includes_co_change` |
-| `_constants.py` | commit-depth defaults, decay half-lives, skip heuristics, GitPython noise patch |
-| `records.py` | `_CommitRec`, `GitIndexSummary`, rename/skip path helpers |
+| `_constants.py` | commit-depth defaults, decay half-lives, the bug-fix keyword classifier (`is_fix_commit`, mirrors the benchmark) + `PRIOR_DEFECT_WINDOW_DAYS`, skip heuristics, GitPython noise patch |
+| `records.py` | `_CommitRec`, `GitIndexSummary`, the `git log` record format + rename/skip path helpers |
| `file_history.py` | `index_file` — per-file parse + base metrics (blame gated by tier) |
| `enrich.py` | blame ownership, commit significance, rename detection, percentiles |
-| `co_change.py` | `compute_co_changes` — repo-wide decay-weighted pair walk |
-| `indexer.py` | `GitIndexer` class wiring the above; back-compat instance shims |
+| `function_blame.py` | per-line blame index → per-function modification counts + line age (FULL tier; feeds `function_hotspot` / `code_age_volatility`) |
+| `co_change.py` | `compute_co_changes` / `compute_co_changes_and_entropy` — repo-wide decay-weighted pair walk + Hassan HCM |
+| `prior_defects.py` | `compute_prior_defects` — windowed bug-fix count per file (leakage-aware, benchmark-mirroring) |
+| `indexer.py` | `GitIndexer` class wiring the above; merges co-change/entropy/prior-defects into per-file metadata; back-compat instance shims |
| `backfill.py` | `backfill_full_tier` resumable ESSENTIAL→FULL promotion |
+(`git_commit_index.py` lives one level up in `ingestion/` — the repo-wide
+commit-bucketing pass `indexer.py` consumes; see Performance above.)
+
## Extension points
A downstream indexer can call the module functions directly with its own
@@ -54,6 +105,7 @@ executor, or subclass nothing and just pass a different `GitIndexTier`.
## Tests
-`tests/unit/test_git_indexer.py` (per-function behaviour),
-`tests/unit/ingestion/test_git_indexer_tiers.py` (tier gating + backfill),
-`tests/integration/test_git_intelligence_integration.py` (end-to-end).
+`tests/unit/test_git_indexer.py` (per-function behaviour, incl. the fix-commit
+classifier + prior-defect counting), `tests/unit/ingestion/test_git_indexer_tiers.py`
+(tier gating + backfill), `tests/integration/test_git_intelligence_integration.py`
+(end-to-end).
diff --git a/packages/core/src/repowise/core/ingestion/git_indexer/__init__.py b/packages/core/src/repowise/core/ingestion/git_indexer/__init__.py
index 25d7598e4..4c41056f6 100644
--- a/packages/core/src/repowise/core/ingestion/git_indexer/__init__.py
+++ b/packages/core/src/repowise/core/ingestion/git_indexer/__init__.py
@@ -19,9 +19,9 @@ This package was split out of a single 1k-line module; the public import path
from __future__ import annotations
-from ._constants import HOTSPOT_HALFLIFE_DAYS
+from ._constants import HOTSPOT_HALFLIFE_DAYS, is_fix_commit
from .backfill import BACKFILL_PHASE, backfill_full_tier
-from .co_change import compute_co_changes
+from .co_change import compute_co_changes, compute_co_changes_and_entropy
from .enrich import (
compute_percentiles,
detect_original_path,
@@ -30,6 +30,7 @@ from .enrich import (
)
from .file_history import index_file
from .indexer import GitIndexer
+from .prior_defects import compute_prior_defects
from .records import (
_FIELD_SEP,
_LOG_FORMAT,
@@ -58,9 +59,12 @@ __all__ = [
"_should_skip_index",
"backfill_full_tier",
"compute_co_changes",
+ "compute_co_changes_and_entropy",
"compute_percentiles",
+ "compute_prior_defects",
"detect_original_path",
"get_blame_ownership",
"index_file",
+ "is_fix_commit",
"is_significant_commit",
]
diff --git a/packages/core/src/repowise/core/ingestion/git_indexer/_constants.py b/packages/core/src/repowise/core/ingestion/git_indexer/_constants.py
index f5b049745..9b243ec61 100644
--- a/packages/core/src/repowise/core/ingestion/git_indexer/_constants.py
+++ b/packages/core/src/repowise/core/ingestion/git_indexer/_constants.py
@@ -150,6 +150,53 @@ _COMMIT_CATEGORIES: dict[str, re.Pattern[str]] = {
),
}
+# Bug-fix commit classifier — mirrors the defect benchmark's
+# ``lib/defect_counter.find_fix_commits`` (keyword strategy) so the product's
+# ``prior_defect`` signal counts exactly the commits the benchmark labels as
+# fixes (product == benchmark). A commit subject is a fix iff it matches an
+# INCLUDE pattern and NO EXCLUDE pattern; merge commits are excluded upstream
+# (the per-file walk skips ``is_merge``), mirroring the bench's ``--no-merges``.
+#
+# Deliberately NOT reusing ``_COMMIT_CATEGORIES["fix"]`` — that is a broader
+# classifier tuned for commit-category *ratios* (it catches "refactor to fix
+# crash", "error handling"), whereas the defect label wants high-precision
+# fix-only matches and must stay byte-identical to the benchmark's regex set.
+_FIX_COMMIT_INCLUDE: tuple[re.Pattern[str], ...] = (
+ re.compile(r"\bfix\b", re.IGNORECASE),
+ re.compile(r"\bbug\b", re.IGNORECASE),
+ re.compile(r"\bpatch\b", re.IGNORECASE),
+ re.compile(r"\bresolves?\b", re.IGNORECASE),
+ re.compile(r"closes?\s+#\d+", re.IGNORECASE),
+ re.compile(r"fixes?\s+#\d+", re.IGNORECASE),
+)
+_FIX_COMMIT_EXCLUDE: tuple[re.Pattern[str], ...] = (
+ re.compile(r"^Merge ", re.IGNORECASE),
+ re.compile(r"\btypo\b", re.IGNORECASE),
+ re.compile(r"\bbump\b", re.IGNORECASE),
+ re.compile(r"\bdeps?\b", re.IGNORECASE),
+ re.compile(r"\bchore\b", re.IGNORECASE),
+ re.compile(r"\blint\b", re.IGNORECASE),
+ re.compile(r"\bformat\b", re.IGNORECASE),
+ re.compile(r"\bstyle\b", re.IGNORECASE),
+ re.compile(r"\bdocs?\b", re.IGNORECASE),
+)
+
+# Trailing window over which ``prior_defect`` counts bug-fix commits. 180 days
+# (≈6 months) intentionally matches the benchmark's ``defect_window_months: 6``
+# prior-defects baseline — a wider window than the 90d activity signals because
+# defect history is a slower-moving cluster than recent churn.
+PRIOR_DEFECT_WINDOW_DAYS: int = 180
+
+
+def is_fix_commit(subject: str) -> bool:
+ """Whether a commit *subject* is a bug-fix, per the benchmark's keyword rule."""
+ if not subject:
+ return False
+ if any(p.search(subject) for p in _FIX_COMMIT_EXCLUDE):
+ return False
+ return any(p.search(subject) for p in _FIX_COMMIT_INCLUDE)
+
+
# Co-change temporal decay: half-life ~125 days (lambda for exp(-t/tau)).
_CO_CHANGE_DECAY_TAU: float = 180.0
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 dbc76b9fe..5a37f949a 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
@@ -104,6 +104,12 @@ def new_meta(file_path: str) -> dict[str, Any]:
# Phase 3 fields
"original_path": None,
"merge_commit_count_90d": 0,
+ # Prior-defect history: count of bug-fix commits touching this file in
+ # the trailing PRIOR_DEFECT_WINDOW_DAYS window (anchored to as_of_ts when
+ # set, so T0 benchmark scoring stays leakage-free). Consumed by the
+ # ``prior_defect`` health biomarker; mirrors the benchmark's
+ # prior-defects baseline definition (product == benchmark).
+ "prior_defect_count": 0,
# Temporal hotspot score (exponentially decayed churn)
"temporal_hotspot_score": 0.0,
# Change entropy (Hassan HCM) — populated repo-wide by the co-change
diff --git a/packages/core/src/repowise/core/ingestion/git_indexer/indexer.py b/packages/core/src/repowise/core/ingestion/git_indexer/indexer.py
index d0da45f38..69ce4359c 100644
--- a/packages/core/src/repowise/core/ingestion/git_indexer/indexer.py
+++ b/packages/core/src/repowise/core/ingestion/git_indexer/indexer.py
@@ -28,6 +28,7 @@ from ._constants import (
from .co_change import compute_co_changes, compute_co_changes_and_entropy
from .enrich import compute_percentiles
from .file_history import index_file
+from .prior_defects import compute_prior_defects
from .records import GitIndexSummary, _CommitRec, _should_skip_index
from .tiers import GitIndexTier
@@ -208,13 +209,25 @@ class GitIndexer:
else:
results.append(r)
- # Merge co-change partners + change entropy into per-file metadata.
+ # Prior-defect counts: one dedicated windowed git-log pass (NOT the
+ # depth-capped commit index, which under-counts the busiest files —
+ # exactly the ones this signal flags). Bounded to the trailing window,
+ # so it's cheap regardless of total repo age and leakage-free at T0.
+ prior_defects: dict[str, int] = {}
+ try:
+ prior_defects = compute_prior_defects(repo, set(indexable_files), as_of_ts=as_of_ts)
+ except Exception as exc:
+ logger.debug("prior_defect_pass_failed", error=str(exc))
+
+ # Merge co-change partners + change entropy + prior defects into metadata.
for meta in results:
fp = meta["file_path"]
if fp in co_changes:
meta["co_change_partners_json"] = json.dumps(co_changes[fp])
if fp in change_entropy:
meta["change_entropy"] = change_entropy[fp]
+ if fp in prior_defects:
+ meta["prior_defect_count"] = prior_defects[fp]
compute_percentiles(results)
@@ -296,6 +309,19 @@ class GitIndexer:
else:
results.append(r)
+ # Recompute prior-defect counts for the changed files (same dedicated
+ # windowed pass as the full index — the per-file commit list can't carry
+ # this signal accurately on busy repos).
+ try:
+ prior_defects = compute_prior_defects(
+ repo, {m["file_path"] for m in results}, as_of_ts=as_of_ts
+ )
+ for meta in results:
+ if meta["file_path"] in prior_defects:
+ meta["prior_defect_count"] = prior_defects[meta["file_path"]]
+ except Exception as exc:
+ logger.debug("prior_defect_pass_failed", error=str(exc))
+
repo.close()
return results
diff --git a/packages/core/src/repowise/core/ingestion/git_indexer/prior_defects.py b/packages/core/src/repowise/core/ingestion/git_indexer/prior_defects.py
new file mode 100644
index 000000000..585b75f56
--- /dev/null
+++ b/packages/core/src/repowise/core/ingestion/git_indexer/prior_defects.py
@@ -0,0 +1,115 @@
+"""Repo-wide prior-defect counting — bug-fix commits per file in a trailing window.
+
+A file's recent bug-fix history is the single most cost-effective defect
+predictor (defects cluster; Ostrand-Weyuker, Kim's "bug cache"). The
+``prior_defect`` health biomarker consumes ``git_meta["prior_defect_count"]``.
+
+This runs as its own ``git log`` pass rather than reading the shared commit
+index, deliberately: that index is depth-capped (``_DEFAULT_COMMIT_LIMIT`` newest
+commits repo-wide) and buckets by file, so on a busy repo a hot file's slice of
+those commits silently under-counts — exactly the files this signal cares about.
+
+It mirrors the defect benchmark's prior-defects baseline
+(``lib/baselines._prior_defect_count`` → ``defect_counter.find_fix_commits`` +
+``_attribute``) so the product counts exactly the commits the benchmark labels as
+fixes (product == benchmark):
+
+* resolve the window-start commit = the last commit on/before ``as_of - window``;
+* walk the **topological range** ``prior_sha..head`` (every non-merge commit
+ merged into HEAD since then — so feature-branch fixes count, matching the
+ benchmark's ``prior_sha..t0_sha`` range, not a date-pruned ``--since`` walk);
+* classify each commit subject with the shared ``is_fix_commit`` keyword rule;
+* attribute a fix to every indexable file it touched.
+
+Reachable-from-HEAD means a T0 worktree never sees post-T0 fixes → leakage-free.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+import structlog
+
+from ._constants import PRIOR_DEFECT_WINDOW_DAYS, is_fix_commit
+from .records import _RECORD_SEP, _extract_rename_paths
+
+logger = structlog.get_logger(__name__)
+
+__all__ = ["compute_prior_defects"]
+
+# sha <US> subject, one record per commit (NUL-separated); --name-only then
+# emits the touched paths on the lines that follow.
+_PRIOR_LOG_FORMAT = "%x00%H%x1f%s"
+_FIELD_SEP = "\x1f"
+
+
+def compute_prior_defects(
+ repo: Any,
+ indexable_files: set[str],
+ *,
+ as_of_ts: float | None,
+ window_days: int = PRIOR_DEFECT_WINDOW_DAYS,
+) -> dict[str, int]:
+ """Return ``{file_path: bug-fix-commit count}`` over the trailing window.
+
+ *as_of_ts* anchors the window's end (the repo's HEAD-commit timestamp under
+ ``REPOWISE_GIT_WINDOW_ANCHOR``, else wall-clock now). Only commits reachable
+ from HEAD are walked, so a historical T0 checkout never sees post-T0 fixes.
+ Files outside *indexable_files* are ignored.
+ """
+ now = datetime.fromtimestamp(as_of_ts, tz=UTC) if as_of_ts is not None else datetime.now(UTC)
+ window_start = (now - timedelta(days=window_days)).strftime("%Y-%m-%d")
+
+ try:
+ head_sha = repo.head.commit.hexsha # type: ignore[attr-defined]
+ except Exception as exc:
+ logger.debug("prior_defect_head_failed", error=str(exc))
+ return {}
+
+ # Window-start boundary: the last commit on/before (as_of - window),
+ # reachable from HEAD. Mirrors the benchmark's ``resolve_t0_sha``.
+ prior_sha = ""
+ try:
+ prior_sha = repo.git.log( # type: ignore[attr-defined]
+ head_sha, f"--before={window_start}T23:59:59", "-1", "--format=%H"
+ ).strip()
+ except Exception as exc:
+ logger.debug("prior_defect_window_resolve_failed", error=str(exc))
+
+ # Range: prior_sha..head (window) when the boundary resolves; otherwise the
+ # repo is younger than the window → count all fixes reachable from HEAD.
+ rev_range = f"{prior_sha}..{head_sha}" if prior_sha else head_sha
+ try:
+ raw = repo.git.log( # type: ignore[attr-defined]
+ rev_range,
+ "--no-merges",
+ "--name-only",
+ f"--format={_PRIOR_LOG_FORMAT}",
+ )
+ except Exception as exc:
+ logger.debug("prior_defect_log_failed", error=str(exc))
+ return {}
+
+ if not raw:
+ return {}
+
+ counts: dict[str, int] = {}
+ for record in raw.split(_RECORD_SEP):
+ record = record.strip("\n")
+ if not record:
+ continue
+ head, _, rest = record.partition("\n")
+ _sha, _, subject = head.partition(_FIELD_SEP)
+ if not is_fix_commit(subject):
+ continue
+ for line in rest.split("\n"):
+ path = line.strip()
+ if not path:
+ continue
+ if "=>" in path: # rename marker {old => new}
+ _old, new = _extract_rename_paths(path, set())
+ path = new or path
+ if path in indexable_files:
+ counts[path] = counts.get(path, 0) + 1
+ return counts
diff --git a/packages/core/src/repowise/core/persistence/models.py b/packages/core/src/repowise/core/persistence/models.py
index 03d98b6e3..2a39d3ed5 100644
--- a/packages/core/src/repowise/core/persistence/models.py
+++ b/packages/core/src/repowise/core/persistence/models.py
@@ -388,6 +388,11 @@ class GitMetadata(Base):
original_path: Mapped[str | None] = mapped_column(Text, nullable=True)
merge_commit_count_90d: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+ # Prior-defect history: bug-fix commits touching this file in the trailing
+ # ~6-month defect window (anchored to the index's as_of reference). Consumed
+ # by the ``prior_defect`` health biomarker — a leakage-aware process signal.
+ prior_defect_count: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+
# Temporal hotspot score: exponentially time-decayed churn signal
temporal_hotspot_score: Mapped[float | None] = mapped_column(Float, nullable=True, default=0.0)
diff --git a/tests/unit/health/test_organizational_biomarkers.py b/tests/unit/health/test_organizational_biomarkers.py
index 35339ae30..57c4f1d58 100644
--- a/tests/unit/health/test_organizational_biomarkers.py
+++ b/tests/unit/health/test_organizational_biomarkers.py
@@ -22,6 +22,9 @@ from repowise.core.analysis.health.biomarkers.knowledge_loss import (
from repowise.core.analysis.health.biomarkers.ownership_risk import (
OwnershipRiskDetector,
)
+from repowise.core.analysis.health.biomarkers.prior_defect import (
+ PriorDefectDetector,
+)
def _authors(*pairs: tuple[str, int]) -> str:
@@ -357,3 +360,33 @@ def test_co_change_scatter_skips_low_activity():
def test_co_change_scatter_silent_on_essential_tier():
# Empty partner list (ESSENTIAL git tier) → no signal.
assert CoChangeScatterDetector().detect(_ctx({"commit_count_90d": 8})) == []
+
+
+# ---- prior_defect --------------------------------------------------------
+
+
+def test_prior_defect_fires_low_on_single_fix():
+ out = PriorDefectDetector().detect(_ctx({"prior_defect_count": 1}))
+ assert len(out) == 1
+ assert out[0].severity == "low"
+ assert out[0].details["prior_defect_count"] == 1
+ assert out[0].details["window_days"] == 180
+
+
+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"
+
+
+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))
+ 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({"commit_count_90d": 9})) == []
diff --git a/tests/unit/health/test_scoring_snapshot.py b/tests/unit/health/test_scoring_snapshot.py
index 0509c16f0..4bd4cb568 100644
--- a/tests/unit/health/test_scoring_snapshot.py
+++ b/tests/unit/health/test_scoring_snapshot.py
@@ -54,6 +54,9 @@ _EXPECTED_BIOMARKER_WEIGHT_MULTIPLIER = {
"complex_method": 1.21,
"function_hotspot": 1.16,
"god_class": 1.13,
+ # prior-defect history — neutral weight: interpretable finding, calibrated
+ # coef ~0 (redundant with change_entropy/churn), Popt gain within noise.
+ "prior_defect": 1.0,
# kept at prior (benchmark could not fairly measure)
"untested_hotspot": 1.3,
"churn_risk": 1.2,
@@ -95,6 +98,7 @@ _EXPECTED_BIOMARKER_CATEGORY = {
"churn_risk": "organizational",
"change_entropy": "organizational",
"co_change_scatter": "organizational",
+ "prior_defect": "organizational",
"large_assertion_block": "test_quality",
"duplicated_assertion_block": "test_quality",
# Phase 4B governance biomarkers.
diff --git a/tests/unit/test_git_indexer.py b/tests/unit/test_git_indexer.py
index b9657ab28..49184c90b 100644
--- a/tests/unit/test_git_indexer.py
+++ b/tests/unit/test_git_indexer.py
@@ -316,6 +316,111 @@ class TestGitWindowAnchor:
assert meta["commit_count_90d"] == 15
+class TestFixCommitClassifier:
+ """``is_fix_commit`` must agree byte-for-byte with the benchmark's
+ ``lib/defect_counter.find_fix_commits`` keyword rule (product == benchmark)."""
+
+ def test_include_patterns_match(self) -> None:
+ from repowise.core.ingestion.git_indexer._constants import is_fix_commit
+
+ assert is_fix_commit("fix: null deref in parser")
+ assert is_fix_commit("Resolve crash on empty input")
+ assert is_fix_commit("patch the off-by-one")
+ assert is_fix_commit("closes #123")
+ assert is_fix_commit("fixes #99 regression")
+ assert is_fix_commit("squash a nasty bug")
+
+ def test_exclude_overrides_include(self) -> None:
+ from repowise.core.ingestion.git_indexer._constants import is_fix_commit
+
+ # "fix" present, but excluded keyword wins (matches the bench's order).
+ assert not is_fix_commit("fix lint")
+ assert not is_fix_commit("fix formatting in docs")
+ assert not is_fix_commit("Merge fix branch")
+ assert not is_fix_commit("bump deps to fix CVE")
+ assert not is_fix_commit("fix a typo")
+
+ def test_non_fixes_silent(self) -> None:
+ from repowise.core.ingestion.git_indexer._constants import is_fix_commit
+
+ assert not is_fix_commit("feat: add new endpoint")
+ assert not is_fix_commit("refactor the walker")
+ assert not is_fix_commit("")
+
+
+class TestPriorDefectCount:
+ """``compute_prior_defects`` walks a dedicated windowed ``prior_sha..HEAD``
+ git-log pass (NOT the depth-capped commit index), classifies fixes with the
+ shared keyword rule, and attributes each fix to every indexable file it
+ touched — mirroring the defect benchmark's prior-defects baseline."""
+
+ def _mock_repo(self, records: list[tuple[str, list[str]]]) -> MagicMock:
+ """records: list of (subject, [touched paths]). Builds the --name-only
+ log output and routes prior_sha resolution vs the windowed walk."""
+ mock_repo = MagicMock()
+ mock_repo.head.commit.hexsha = "HEADSHA"
+ chunks = []
+ for i, (subject, paths) in enumerate(records):
+ body = "\n".join(paths)
+ chunks.append(f"\x00sha{i:04d}\x1f{subject}\n{body}")
+ log_out = "\n".join(chunks)
+
+ def _log(*args, **kwargs):
+ # prior_sha resolution carries --before / -1; the walk carries
+ # --name-only. Route on that.
+ if any(str(a).startswith("--before") for a in args):
+ return "PRIORSHA"
+ return log_out
+
+ mock_repo.git.log.side_effect = _log
+ return mock_repo
+
+ def test_counts_and_attributes_fixes(self) -> None:
+ from repowise.core.ingestion.git_indexer.prior_defects import (
+ compute_prior_defects,
+ )
+
+ repo = self._mock_repo(
+ [
+ ("fix: crash on empty config", ["src/app.py", "src/util.py"]),
+ ("resolve race in scheduler", ["src/app.py"]),
+ ("feat: add flag", ["src/app.py"]), # not a fix
+ ("fix lint", ["src/app.py"]), # excluded keyword
+ ]
+ )
+ counts = compute_prior_defects(
+ repo, {"src/app.py", "src/util.py"}, as_of_ts=1_700_000_000.0
+ )
+ assert counts == {"src/app.py": 2, "src/util.py": 1}
+
+ def test_ignores_non_indexable_paths(self) -> None:
+ from repowise.core.ingestion.git_indexer.prior_defects import (
+ compute_prior_defects,
+ )
+
+ repo = self._mock_repo(
+ [
+ ("fix: bug", ["src/app.py", "docs/readme.md"]),
+ ]
+ )
+ counts = compute_prior_defects(repo, {"src/app.py"}, as_of_ts=1_700_000_000.0)
+ assert counts == {"src/app.py": 1}
+
+ def test_zero_when_no_fixes(self) -> None:
+ from repowise.core.ingestion.git_indexer.prior_defects import (
+ compute_prior_defects,
+ )
+
+ repo = self._mock_repo(
+ [
+ ("feat: add thing", ["src/app.py"]),
+ ("docs: update readme", ["src/app.py"]),
+ ]
+ )
+ counts = compute_prior_defects(repo, {"src/app.py"}, as_of_ts=1_700_000_000.0)
+ assert counts == {}
+
+
# ---------------------------------------------------------------------------
# 4b. test_numstat_parsing
# ---------------------------------------------------------------------------