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(risk): publish a churn rank beside the raw churn sum on direct risks (#2443)

Raghav Chamadiya3e7f41403fd3
diff --git a/docs/layers/CHANGE_RISK.md b/docs/layers/CHANGE_RISK.md
index eee540010..fa76a09d9 100644
--- a/docs/layers/CHANGE_RISK.md
+++ b/docs/layers/CHANGE_RISK.md
@@ -377,7 +377,9 @@ and all three bands are occupied. The corpus lives in
| `get_risk` `health_score` | Indexed code-health model | health points, 0-10; higher is healthier | Benchmarked file-health signal, not interchangeable with change-risk points |
| `structural_impact_score` | PR structural formula above | normalized points, 0-10 | Deterministic and uncalibrated; not authoritative. `overall_risk_score` is an exact deprecated alias |
| `direct_risks[].structural_score` | `pagerank * (1 + temporal_hotspot)` | raw pagerank-weighted-hotspot value, unbounded | Uncalibrated within-change structural weight. `risk_score` is an exact deprecated alias |
-| `direct_risks[].temporal_hotspot` | Exponentially-decayed sum of per-commit churn (halflife 180 d); each commit contributes up to 3.0 | raw decayed churn, unbounded (observed max ~23); use `churn_percentile` for a normalised 0–1 rank | Intermediate input to `structural_score`; not a ratio|
+| `direct_risks[].temporal_hotspot` | Exponentially-decayed sum of per-commit churn (halflife 180 d); each commit contributes up to 3.0 | raw decayed churn, unbounded (observed max 42.6 on this repository); use `churn_percentile` for a normalised 0–1 rank | Intermediate input to `structural_score`; not a ratio|
+| `direct_risks[].churn_percentile` | Rank of `temporal_hotspot` among the repository's files | percentile rank, 0–1 | Comparable across repositories as a rank, not as activity; reported beside `structural_score`, never folded into it |
+| `direct_risks[].is_hotspot` | The index's hotspot verdict: top-quartile churn AND its absolute activity floors | boolean | Read this rather than re-deriving a hotspot from `churn_percentile`, which omits the floors |
| `cochange_warnings[].score` | Number of historical commits in which the pair co-changed | raw commit count, 0+ | Historical evidence only; cannot become structural or runtime-breakage evidence |
| workspace `impacted[].score` | Strongest path product of edge confidence, edge-kind weight, and `0.6` per hop | relative path weight, 0-1 | Deterministic, uncalibrated ranking heuristic; not a probability or change-review authority |
| dashboard hotspot triage index | `40% * churn percentile + 35% * bus-factor tier + 25% * bounded temporal activity` | heuristic points, 0-100 | Client-side, uncalibrated orientation only; labelled adjacent to the chart |
diff --git a/packages/core/src/repowise/core/analysis/pr_blast.py b/packages/core/src/repowise/core/analysis/pr_blast.py
index cf48ddcdd..ca3036b85 100644
--- a/packages/core/src/repowise/core/analysis/pr_blast.py
+++ b/packages/core/src/repowise/core/analysis/pr_blast.py
@@ -201,6 +201,8 @@ class PRBlastRadiusAnalyzer:
meta = meta_by_path.get(path)
node = node_by_path.get(path)
temporal = float(getattr(meta, "temporal_hotspot_score", 0.0) or 0.0)
+ churn_pct = float(getattr(meta, "churn_percentile", 0.0) or 0.0)
+ hotspot = bool(getattr(meta, "is_hotspot", False))
centrality = float(getattr(node, "pagerank", 0.0) or 0.0)
structural_score = self._score_file(temporal, centrality)
results.append(
@@ -210,6 +212,11 @@ class PRBlastRadiusAnalyzer:
# Compatibility alias for pre-semantics clients.
"risk_score": round(structural_score, 4),
"temporal_hotspot": round(temporal, 4),
+ "churn_percentile": round(churn_pct, 4),
+ # Published so a consumer stops re-deriving it from the
+ # churn conjunct alone, which on a dormant repository is
+ # just its top quartile.
+ "is_hotspot": hotspot,
"centrality": round(centrality, 6),
}
)
@@ -219,7 +226,20 @@ class PRBlastRadiusAnalyzer:
@staticmethod
def _score_file(temporal_hotspot_score: float, centrality: float) -> float:
- """Compute file-level risk: centrality * (1 + temporal_hotspot_score)."""
+ """Compute file-level risk: centrality * (1 + temporal_hotspot_score).
+
+ Both inputs are repo-coupled -- the multiplier grows with commit
+ velocity, and pagerank sums to 1 so mean centrality is ``1/file_count``
+ -- so the score compares files within one change set and nothing across
+ repositories.
+
+ Substituting ``churn_percentile`` here was measured on 397 merged PRs
+ and rejected: it moved every moderate-band PR into localized, because a
+ bounded [1, 2] multiplier collapses an exponential tuned against an
+ unbounded one, and re-tuning that exponent would fit the constant to
+ this repository's file count. The rank is published beside the raw
+ value instead.
+ """
return centrality * (1.0 + temporal_hotspot_score)
async def _transitive_affected(
diff --git a/packages/core/src/repowise/core/analysis/risk_semantics.py b/packages/core/src/repowise/core/analysis/risk_semantics.py
index 129c50428..f82c0f7db 100644
--- a/packages/core/src/repowise/core/analysis/risk_semantics.py
+++ b/packages/core/src/repowise/core/analysis/risk_semantics.py
@@ -283,7 +283,22 @@ def structural_impact_contract(score: float, *, full_scale: bool = False) -> dic
"note": (
"Unbounded exponentially-decayed sum of per-commit churn "
"(halflife 180 d); each commit contributes up to 3.0. "
- "Use churn_percentile for a normalised 0-1 rank."
+ "Grows with commit velocity, so it ranks files within one "
+ "repository and does not compare across repositories. "
+ "Use direct_risks.churn_percentile for a normalised 0-1 rank."
+ ),
+ },
+ "direct_risks.churn_percentile": {
+ "kind": "repo_relative_rank",
+ "unit": "percentile",
+ "range": {"minimum": 0.0, "maximum": 1.0},
+ "note": (
+ "The rank of direct_risks.temporal_hotspot among this "
+ "repository's files. Comparable across repositories as a "
+ "rank and not as activity: 0.9 in a dormant repository and "
+ "0.9 in a fast one describe very different absolute churn. "
+ "Reported beside the score, not folded into it -- "
+ "structural_score keeps the raw multiplier."
),
},
"direct_risks.centrality": {
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 56a2ac902..d70522c77 100644
--- a/packages/core/src/repowise/core/ingestion/git_indexer/enrich.py
+++ b/packages/core/src/repowise/core/ingestion/git_indexer/enrich.py
@@ -125,6 +125,17 @@ def meets_hotspot_floors(meta: dict) -> bool:
90-day window AND real line movement (or a sustained commit volume
that is hotspot-grade on its own). See ``_constants`` for the floor
rationale; the SQL mirror lives in ``crud/git.py``.
+
+ Audited as the velocity artifact #2437/#2438 fixed elsewhere and kept; do
+ not strip them without repeating the measurement. Across 41 indexed
+ repositories hotspot share tracks velocity (0-21%, Spearman 0.94 on
+ per-file 90-day commit density) where the percentile alone is flat at 25%,
+ but it moves because hotness moves. The floor that arbitrates is the
+ temporal one, over files at 3-7 commits in the window: it withheld the flag
+ from 152 of the 3,833 files that reached that band, at most 2.6% of any one
+ repository. Dropping the floors would instead call a quarter of a dormant
+ repository hot, since churn_percentile ranks a decayed score that stays
+ positive long after the commits stop.
"""
try:
commit_90d = int(meta.get("commit_count_90d") or 0)
diff --git a/packages/server/src/repowise/server/schemas/blast_radius.py b/packages/server/src/repowise/server/schemas/blast_radius.py
index e888769d2..881622b16 100644
--- a/packages/server/src/repowise/server/schemas/blast_radius.py
+++ b/packages/server/src/repowise/server/schemas/blast_radius.py
@@ -23,6 +23,10 @@ class DirectRiskEntry(BaseModel):
#: Deprecated exact alias of ``structural_score`` for older clients.
risk_score: float
temporal_hotspot: float
+ #: Repo-relative rank of ``temporal_hotspot``; comparable as a rank.
+ churn_percentile: float
+ #: The index's hotspot verdict: top-quartile churn AND its activity floors.
+ is_hotspot: bool
centrality: float
diff --git a/packages/types/src/blast-radius.ts b/packages/types/src/blast-radius.ts
index 1507690c0..4ab0c0a77 100644
--- a/packages/types/src/blast-radius.ts
+++ b/packages/types/src/blast-radius.ts
@@ -19,6 +19,10 @@ export interface DirectRiskEntry {
risk_score: number;
/** Raw decayed churn sum, unbounded; use churn_percentile for 0–1 normalised rank. */
temporal_hotspot: number;
+ /** Repo-relative rank of temporal_hotspot, 0–1. Comparable as a rank, not as activity. */
+ churn_percentile: number;
+ /** The index's hotspot verdict: top-quartile churn AND its absolute activity floors. */
+ is_hotspot: boolean;
/** Raw graph centrality (pagerank); typically well below 1. */
centrality: number;
}
diff --git a/packages/types/src/generated/http.ts b/packages/types/src/generated/http.ts
index 548f0e2e8..bf292065b 100644
--- a/packages/types/src/generated/http.ts
+++ b/packages/types/src/generated/http.ts
@@ -982,6 +982,8 @@ export interface DirectRiskEntry {
structural_score: number;
risk_score: number;
temporal_hotspot: number;
+ churn_percentile: number;
+ is_hotspot: boolean;
centrality: number;
}
diff --git a/packages/ui/__tests__/blast-radius/blast-radius.test.tsx b/packages/ui/__tests__/blast-radius/blast-radius.test.tsx
index a6f877b2e..98cc4ef21 100644
--- a/packages/ui/__tests__/blast-radius/blast-radius.test.tsx
+++ b/packages/ui/__tests__/blast-radius/blast-radius.test.tsx
@@ -17,7 +17,9 @@ const fixture: BlastRadiusResponse = {
path: "src/auth/login.py",
structural_score: 0.82,
risk_score: 0.82,
- temporal_hotspot: 0.74,
+ temporal_hotspot: 8.4,
+ churn_percentile: 0.93,
+ is_hotspot: true,
centrality: 0.045,
},
],
@@ -160,10 +162,12 @@ describe("TableSection", () => {
});
describe("DirectRisksTable", () => {
- it("shows the raw structural weight instead of inventing a 0–10 scale", () => {
+ it("prints the raw churn sum and bars its repo-relative rank", () => {
render(<DirectRisksTable rows={fixture.direct_risks} />);
expect(screen.getByText("0.8200")).toBeTruthy();
- expect(screen.getByText("7.4")).toBeTruthy();
+ // The raw sum, not raw * 10: it is unbounded and reached 42 on this repo.
+ expect(screen.getByText("8.4")).toBeTruthy();
+ expect(screen.queryByText("84.0")).toBeNull();
});
});
diff --git a/packages/ui/src/blast-radius/direct-risks-table.tsx b/packages/ui/src/blast-radius/direct-risks-table.tsx
index 8b76ca294..8266b6f72 100644
--- a/packages/ui/src/blast-radius/direct-risks-table.tsx
+++ b/packages/ui/src/blast-radius/direct-risks-table.tsx
@@ -29,7 +29,7 @@ function MiniBar({
style={{ width: `${pct}%`, background: color }}
/>
</div>
- <span className="w-10 shrink-0 text-right tabular-nums text-[var(--color-text-secondary)]">
+ <span className="w-12 shrink-0 text-right tabular-nums text-[var(--color-text-secondary)]">
{display}
</span>
</div>
@@ -77,17 +77,22 @@ const COLUMNS: ResponsiveColumn<DisplayDirectRisk>[] = [
},
{
key: "temporal_hotspot",
- header: "Temporal hotspot",
+ header: "Temporal hotspot (bar: rank)",
headerClassName: "w-[24%]",
priority: 2,
+ // The bar reads churn_percentile: temporal_hotspot is an unbounded churn
+ // sum whose median is already above 1.0, so a [0,1] bar pinned most rows
+ // full. The raw sum stays as the printed figure, without the *10 that
+ // made it look like a 0-10 score when it can exceed 40. The ?? 0 is for a
+ // server predating the field, where undefined would render width: NaN%.
render: (r) => (
<MiniBar
- value01={r.temporal_hotspot}
+ value01={r.churn_percentile ?? 0}
color="var(--color-accent-secondary)"
- display={(r.temporal_hotspot * 10).toFixed(1)}
+ display={r.temporal_hotspot.toFixed(1)}
/>
),
- mobileRender: (r) => (r.temporal_hotspot * 10).toFixed(1),
+ mobileRender: (r) => r.temporal_hotspot.toFixed(1),
},
{
key: "centrality",
diff --git a/packages/vscode/webview/src/views/risk/App.test.tsx b/packages/vscode/webview/src/views/risk/App.test.tsx
index d9585813a..18f49e977 100644
--- a/packages/vscode/webview/src/views/risk/App.test.tsx
+++ b/packages/vscode/webview/src/views/risk/App.test.tsx
@@ -93,6 +93,8 @@ const IMPACT: ChangeImpactReport = {
structural_score: 0.3,
risk_score: 0.3,
temporal_hotspot: 0.1,
+ churn_percentile: 0.35,
+ is_hotspot: false,
centrality: 0.8,
},
{
@@ -100,6 +102,8 @@ const IMPACT: ChangeImpactReport = {
structural_score: 0.82,
risk_score: 0.82,
temporal_hotspot: 0.9,
+ churn_percentile: 0.95,
+ is_hotspot: true,
centrality: 0.1,
},
],
diff --git a/packages/vscode/webview/src/views/risk/selectors.test.ts b/packages/vscode/webview/src/views/risk/selectors.test.ts
index 209b7f5fa..231f4552e 100644
--- a/packages/vscode/webview/src/views/risk/selectors.test.ts
+++ b/packages/vscode/webview/src/views/risk/selectors.test.ts
@@ -47,8 +47,8 @@ describe("selectDirectRisks", () => {
it("ranks riskiest first with shares relative to the set maximum", () => {
const out = selectDirectRisks(
report([
- { path: "a.ts", structural_score: 0.005, risk_score: 0.005, temporal_hotspot: 0, centrality: 0.005 },
- { path: "b.ts", structural_score: 0.02, risk_score: 0.02, temporal_hotspot: 0, centrality: 0.02 },
+ { path: "a.ts", structural_score: 0.005, risk_score: 0.005, temporal_hotspot: 0, churn_percentile: 0, is_hotspot: false, centrality: 0.005 },
+ { path: "b.ts", structural_score: 0.02, risk_score: 0.02, temporal_hotspot: 0, churn_percentile: 0, is_hotspot: false, centrality: 0.02 },
]),
);
expect(out.map((r) => r.path)).toEqual(["b.ts", "a.ts"]);
@@ -56,11 +56,13 @@ describe("selectDirectRisks", () => {
expect(out[1]?.share).toBeCloseTo(0.25);
});
- it("flags hotspots only above the floor", () => {
+ // The marker reads the index's verdict, not a raw churn number that grows
+ // with how fast the repository commits.
+ it("takes the hotspot marker from the index", () => {
const out = selectDirectRisks(
report([
- { path: "hot.ts", structural_score: 0.01, risk_score: 0.01, temporal_hotspot: 0.9, centrality: 0.005 },
- { path: "quiet.ts", structural_score: 0.01, risk_score: 0.01, temporal_hotspot: 0.2, centrality: 0.005 },
+ { path: "hot.ts", structural_score: 0.01, risk_score: 0.01, temporal_hotspot: 0.9, churn_percentile: 0.92, is_hotspot: true, centrality: 0.005 },
+ { path: "quiet.ts", structural_score: 0.01, risk_score: 0.01, temporal_hotspot: 0.2, churn_percentile: 0.4, is_hotspot: false, centrality: 0.005 },
]),
);
expect(out.find((r) => r.path === "hot.ts")?.hotspot).toBe(true);
@@ -69,7 +71,7 @@ describe("selectDirectRisks", () => {
it("serves zero shares when every risk score is zero", () => {
const out = selectDirectRisks(
- report([{ path: "a.ts", structural_score: 0, risk_score: 0, temporal_hotspot: 0, centrality: 0 }]),
+ report([{ path: "a.ts", structural_score: 0, risk_score: 0, temporal_hotspot: 0, churn_percentile: 0, is_hotspot: false, centrality: 0 }]),
);
expect(out[0]?.share).toBe(0);
});
diff --git a/packages/vscode/webview/src/views/risk/selectors.ts b/packages/vscode/webview/src/views/risk/selectors.ts
index 86ddbb44b..7b17ce8ee 100644
--- a/packages/vscode/webview/src/views/risk/selectors.ts
+++ b/packages/vscode/webview/src/views/risk/selectors.ts
@@ -6,11 +6,21 @@
import type { ChangeImpactReport } from "../../../../src/shared/webviewMessages";
/**
- * Temporal-hotspot fraction above which a file earns the quiet hotspot marker.
+ * Churn percentile above which a file earns the marker when the server is too
+ * old to send `is_hotspot`.
+ *
+ * The marker read `temporal_hotspot >= 0.6`, calling that field a fraction. It
+ * is an unbounded churn sum whose median is above 1.0 and whose maximum
+ * exceeds 40, so the marker fired on most of a fast repo's tree and on none of
+ * a slow one's. The index's own `is_hotspot` is the answer, and this quartile
+ * is only its churn conjunct: it lacks the absolute activity floors, so on a
+ * dormant repository it degenerates to "any file touched recently". Fall back
+ * to it, do not prefer it.
+ *
* The per-file structural weight is centrality-weighted and unbounded, so rows
- * carry a share relative to the riskiest file instead of an absolute scale.
+ * still carry a share relative to the riskiest file.
*/
-export const HOTSPOT_FLOOR = 0.6;
+export const HOTSPOT_FLOOR = 0.75;
/** One changed file ranked by its raw blast-radius structural weight. */
export interface RankedDirectRisk {
@@ -30,7 +40,7 @@ export function selectDirectRisks(report: ChangeImpactReport): RankedDirectRisk[
.map((d) => ({
path: d.path,
share: max > 0 ? d.structural_score / max : 0,
- hotspot: d.temporal_hotspot >= HOTSPOT_FLOOR,
+ hotspot: d.is_hotspot ?? (d.churn_percentile ?? 0) >= HOTSPOT_FLOOR,
}))
.sort((a, b) => b.share - a.share);
}
diff --git a/tests/unit/analysis/test_pr_blast_risk.py b/tests/unit/analysis/test_pr_blast_risk.py
index a87785474..135b458c5 100644
--- a/tests/unit/analysis/test_pr_blast_risk.py
+++ b/tests/unit/analysis/test_pr_blast_risk.py
@@ -22,7 +22,7 @@ _CORPUS = Path(__file__).parents[2] / "fixtures" / "risk_scale_corpus.json"
def _direct(*scores: float) -> list[dict]:
- # Mirrors _score_files: the alias ships beside the typed field.
+ # Only the two keys _compute_overall_risk reads; _score_files emits five.
return [{"structural_score": s, "risk_score": s} for s in scores]
@@ -177,3 +177,103 @@ def test_structural_contract_is_typed_and_legacy_alias_cannot_contradict() -> No
assert contract["overall_risk_score_compatibility"]["replacement"] == (
"structural_impact_score"
)
+
+
+def test_raw_churn_and_its_repo_relative_rank_are_both_published() -> None:
+ """The velocity-coupled multiplier must ship its normalised form beside it.
+
+ Folding the percentile into ``structural_score`` was measured and rejected
+ (it collapses the 0-10 output), so the rank is published as its own field
+ and the contract has to say which one travels across repositories.
+ """
+ fields = structural_impact_contract(6.25, full_scale=True)["structural_impact_scale"][
+ "component_fields"
+ ]
+
+ raw = fields["direct_risks.temporal_hotspot"]
+ assert raw["kind"] == "raw_decayed_churn"
+ assert raw["range"]["maximum"] is None
+ assert "churn_percentile" in raw["note"]
+
+ rank = fields["direct_risks.churn_percentile"]
+ assert rank["kind"] == "repo_relative_rank"
+ assert rank["range"] == {"minimum": 0.0, "maximum": 1.0}
+
+ # The score itself keeps the raw multiplier; the rank sits beside it.
+ assert fields["direct_risks.structural_score"]["formula"] == (
+ "pagerank * (1 + temporal_hotspot)"
+ )
+
+
+def test_score_file_keeps_the_unbounded_multiplier() -> None:
+ # (1 + churn_percentile) would cap this term at 2x; (1 + temporal) does not.
+ assert PRBlastRadiusAnalyzer._score_file(0.0, 0.01) == 0.01
+ assert PRBlastRadiusAnalyzer._score_file(9.0, 0.01) == 0.1
+
+
+class _Meta:
+ def __init__(self, **kw):
+ self.__dict__.update(kw)
+
+
+class _Result:
+ def __init__(self, rows):
+ self._rows = rows
+
+ def scalars(self):
+ return self
+
+ def all(self):
+ return self._rows
+
+
+class _FakeSession:
+ """Answers _score_files' two SELECTs in the order it issues them."""
+
+ def __init__(self, metas, nodes):
+ self._answers = [list(metas.values()), list(nodes.values())]
+
+ async def execute(self, _stmt):
+ return _Result(self._answers.pop(0))
+
+
+class _Node:
+ def __init__(self, node_id, pagerank):
+ self.node_id = node_id
+ self.pagerank = pagerank
+
+
+async def test_score_files_emits_the_rank_and_the_index_verdict() -> None:
+ """A row carries the raw churn sum, its repo-relative rank, and is_hotspot.
+
+ A consumer that had only the raw sum was re-deriving a hotspot from it with
+ an absolute cutoff, which is the velocity artifact this change removes.
+ """
+ analyzer = PRBlastRadiusAnalyzer.__new__(PRBlastRadiusAnalyzer)
+ analyzer._repo_id = "r"
+ metas = {
+ "hot.py": _Meta(
+ file_path="hot.py",
+ temporal_hotspot_score=8.4,
+ churn_percentile=0.93,
+ is_hotspot=True,
+ ),
+ }
+ nodes = {"hot.py": _Node("hot.py", 0.01), "unknown.py": _Node("unknown.py", 0.02)}
+ analyzer._session = _FakeSession(metas, nodes)
+
+ rows = {r["path"]: r for r in await analyzer._score_files(["hot.py", "unknown.py"])}
+
+ hot = rows["hot.py"]
+ assert hot["temporal_hotspot"] == 8.4
+ assert hot["churn_percentile"] == 0.93
+ assert hot["is_hotspot"] is True
+ assert hot["structural_score"] == hot["risk_score"] == round(0.01 * 9.4, 4)
+
+ # No git_metadata row: every history field degrades to a measured zero
+ # rather than to None, so the marker stays off instead of rendering NaN.
+ missing = rows["unknown.py"]
+ assert missing["temporal_hotspot"] == 0.0
+ assert missing["churn_percentile"] == 0.0
+ assert missing["is_hotspot"] is False
+ assert missing["centrality"] == 0.02