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-semantics): correct temporal_hotspot contract to unbounded (#1971)
Akshat malik30a8613bf2a5
diff --git a/docs/layers/CHANGE_RISK.md b/docs/layers/CHANGE_RISK.mdindex c64475974..81faa646b 100644--- a/docs/layers/CHANGE_RISK.md+++ b/docs/layers/CHANGE_RISK.md@@ -377,6 +377,7 @@ 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|| `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/risk_semantics.py b/packages/core/src/repowise/core/analysis/risk_semantics.pyindex d1549c8d7..129c50428 100644--- a/packages/core/src/repowise/core/analysis/risk_semantics.py+++ b/packages/core/src/repowise/core/analysis/risk_semantics.py@@ -277,9 +277,14 @@ def structural_impact_contract(score: float, *, full_scale: bool = False) -> dic"equivalent_value": True,},"direct_risks.temporal_hotspot": {- "kind": "normalized_component_score",- "unit": "ratio",- "range": {"minimum": 0.0, "maximum": 1.0},+ "kind": "raw_decayed_churn",+ "unit": "decayed_line_hundreds",+ "range": {"minimum": 0.0, "maximum": None},+ "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."+ ),},"direct_risks.centrality": {"kind": "graph_centrality",diff --git a/packages/types/src/blast-radius.ts b/packages/types/src/blast-radius.tsindex d2aadc29c..7acb237f0 100644--- a/packages/types/src/blast-radius.ts+++ b/packages/types/src/blast-radius.ts@@ -17,7 +17,7 @@ export interface DirectRiskEntry {structural_score: number;/** @deprecated Exact alias of structural_score for older clients. */risk_score: number;- /** 0-1 normalised. */+ /** Raw decayed churn sum, unbounded; use churn_percentile for 0–1 normalised rank. */temporal_hotspot: number;/** Raw graph centrality (pagerank); typically well below 1. */centrality: number;diff --git a/tests/unit/analysis/test_temporal_hotspot_contract.py b/tests/unit/analysis/test_temporal_hotspot_contract.pynew file mode 100644index 000000000..0b4db6957--- /dev/null+++ b/tests/unit/analysis/test_temporal_hotspot_contract.py@@ -0,0 +1,125 @@+"""Contract tests for direct_risks.temporal_hotspot — issue #1970.++``temporal_hotspot_score`` is an unbounded exponentially-decayed churn sum+(each commit contributes up to 3.0; 40% of files exceed 1.0 on this repo).+The scale contract must accurately describe that, not claim a 0-1 ratio.++These tests are pure-unit: ``structural_impact_contract`` is a dict-builder+with no I/O, so no fixtures, DB, or async are needed.+"""++from __future__ import annotations++from repowise.core.analysis.risk_semantics import structural_impact_contract+++def _component_fields() -> dict:+ """Return the component_fields sub-dict from the full-scale contract.++ component_fields is a reference-tier key that compact_scale() intentionally+ strips; always read it from full_scale=True.+ """+ contract = structural_impact_contract(5.0, full_scale=True)+ scale = contract["structural_impact_scale"]+ return scale["component_fields"]+++class TestTemporalHotspotContractKind:+ """direct_risks.temporal_hotspot must declare itself as raw decayed churn."""++ def test_kind_is_raw_decayed_churn(self) -> None:+ fields = _component_fields()+ assert fields["direct_risks.temporal_hotspot"]["kind"] == "raw_decayed_churn", (+ "temporal_hotspot is an unbounded decayed sum — it must not claim "+ "'normalized_component_score'"+ )++ def test_unit_is_decayed_line_hundreds(self) -> None:+ fields = _component_fields()+ assert fields["direct_risks.temporal_hotspot"]["unit"] == "decayed_line_hundreds"++ def test_maximum_is_none(self) -> None:+ """Range maximum must be None — the value is unbounded (max observed: 23.2)."""+ fields = _component_fields()+ rng = fields["direct_risks.temporal_hotspot"]["range"]+ assert rng["maximum"] is None, (+ f"temporal_hotspot maximum must be None (unbounded), got {rng['maximum']!r}"+ )++ def test_minimum_is_zero(self) -> None:+ fields = _component_fields()+ assert fields["direct_risks.temporal_hotspot"]["range"]["minimum"] == 0.0++ def test_note_is_present_and_mentions_churn_percentile(self) -> None:+ """A consumer note must exist and point to churn_percentile for normalisation."""+ fields = _component_fields()+ note = fields["direct_risks.temporal_hotspot"].get("note", "")+ assert note, "A consumer-facing note is required on this field"+ assert "churn_percentile" in note, (+ "Note must reference churn_percentile so consumers know the normalised alternative"+ )+++class TestStructuralScoreContractUnchanged:+ """Regression guard: direct_risks.structural_score must stay unbounded.++ This field was already declared correctly; the fix must not touch it.+ """++ def test_structural_score_maximum_is_none(self) -> None:+ fields = _component_fields()+ rng = fields["direct_risks.structural_score"]["range"]+ assert rng["maximum"] is None+++class TestContractConsistencyAcrossScoreTiers:+ """component_fields is a reference-tier key — compact_scale strips it.++ Assertions:+ 1. The full scale carries the corrected contract.+ 2. compact_scale correctly omits component_fields (that is the design,+ not a regression — so we assert it explicitly).+ """++ def test_kind_in_full_scale(self) -> None:+ fields = _component_fields()+ assert fields["direct_risks.temporal_hotspot"]["kind"] == "raw_decayed_churn"++ def test_maximum_in_full_scale(self) -> None:+ fields = _component_fields()+ assert fields["direct_risks.temporal_hotspot"]["range"]["maximum"] is None++ def test_compact_scale_omits_component_fields(self) -> None:+ """compact_scale() strips reference-tier keys — component_fields must not appear."""+ contract = structural_impact_contract(5.0, full_scale=False)+ scale = contract["structural_impact_scale"]+ assert "component_fields" not in scale, (+ "compact_scale must strip component_fields (it is a reference-tier key)"+ )+++class TestPreviousContractWasWrong:+ """Explicitly assert that the old (broken) values are gone.++ These assertions will catch any future regression that re-introduces+ the false ratio claim.+ """++ def test_kind_is_not_normalized_component_score(self) -> None:+ fields = _component_fields()+ assert fields["direct_risks.temporal_hotspot"]["kind"] != "normalized_component_score", (+ "Regression: temporal_hotspot must not be declared as 'normalized_component_score' "+ "(issue #1970)"+ )++ def test_unit_is_not_ratio(self) -> None:+ fields = _component_fields()+ assert fields["direct_risks.temporal_hotspot"]["unit"] != "ratio"++ def test_maximum_is_not_1_0(self) -> None:+ fields = _component_fields()+ rng = fields["direct_risks.temporal_hotspot"]["range"]+ assert rng["maximum"] != 1.0, (+ "Regression: temporal_hotspot maximum must not be 1.0 — the value is unbounded "+ "(issue #1970)"+ )