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-semantics): correct temporal_hotspot contract to unbounded (#1971)

Akshat malik30a8613bf2a5
diff --git a/docs/layers/CHANGE_RISK.md b/docs/layers/CHANGE_RISK.md
index 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.py
index 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.ts
index 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.py
new file mode 100644
index 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)"
+ )