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(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.mdindex 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.pyindex 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:@staticmethoddef _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.pyindex 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.pyindex 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 volumethat is hotspot-grade on its own). See ``_constants`` for the floorrationale; 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.pyindex 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: floattemporal_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: boolcentrality: floatdiff --git a/packages/types/src/blast-radius.ts b/packages/types/src/blast-radius.tsindex 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.tsindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsindex 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.tsindex 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.pyindex 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() -> Noassert 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