feat(test): coverage map health check (loud anti-rot)

Author: sbryngelson

.github/scripts/check_coverage_map_health.py

@@ -0,0 +1,26 @@
+"""Fail loudly if the committed coverage map is stale or under-covers. Used by coverage-health.yml."""
+import datetime
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "toolchain"))
+from mfc.test.coverage import COVERAGE_MAP_PATH, load_map, map_health  # noqa: E402
+from mfc.test.cases import list_cases  # noqa: E402  (returns the current test list)
+
+MAX_AGE_DAYS = 10
+MIN_FRACTION = 0.80
+
+entries, meta = load_map(COVERAGE_MAP_PATH)
+if entries is None:
+    sys.exit("Coverage map missing or corrupt.")
+current_keys = {b.to_case().coverage_key() for b in list_cases()}
+ok, msg = map_health(
+    meta=meta,
+    current_keys=current_keys,
+    mapped_keys=set(entries),
+    now=datetime.datetime.now(datetime.timezone.utc).isoformat(),
+    max_age_days=MAX_AGE_DAYS,
+    min_fraction=MIN_FRACTION,
+)
+print(msg)
+sys.exit(0 if ok else 1)

toolchain/mfc/test/coverage.py

@@ -162,3 +162,17 @@ def format_summary(*, ran, total, reason, meta, now) -> str:
     else:
         age = "map age unknown"
     return f"Coverage selection: ran {ran}/{total} tests · {age} · {reason}"
+
+
+def map_health(*, meta, current_keys, mapped_keys, now, max_age_days, min_fraction):
+    """Return (ok, message). Loud anti-rot check used by the health workflow."""
+    if not meta or not meta.get("built_at"):
+        return False, "Coverage map has no build metadata."
+    age = (datetime.datetime.fromisoformat(now) - datetime.datetime.fromisoformat(meta["built_at"])).days
+    if age > max_age_days:
+        return False, f"Coverage map is STALE: {age}d old (max {max_age_days}d). Refresh workflow may be broken."
+    if current_keys:
+        frac = len(current_keys & mapped_keys) / len(current_keys)
+        if frac < min_fraction:
+            return False, f"Coverage map under-covers: {frac:.0%} of current tests mapped (min {min_fraction:.0%})."
+    return True, f"Coverage map healthy: {age}d old."

toolchain/mfc/test/test_coverage_unit.py

@@ -3,7 +3,7 @@
 from pathlib import Path
 from unittest.mock import patch
 
-from mfc.test.coverage import format_summary, get_changed_files, is_always_run_all, load_map, param_hash, save_map, select_tests
+from mfc.test.coverage import format_summary, get_changed_files, is_always_run_all, load_map, map_health, param_hash, save_map, select_tests
 
 
 def test_param_hash_is_order_independent():
@@ -190,3 +190,39 @@ def test_summary_handles_missing_meta():
         now="2026-05-29T00:00:00+00:00",
     )
     assert "610/610" in s and "map age unknown" in s
+
+
+def test_health_ok():
+    ok, msg = map_health(
+        meta={"built_at": "2026-05-28T00:00:00+00:00", "n_tests": 600},
+        current_keys=set(str(i) for i in range(600)),
+        mapped_keys=set(str(i) for i in range(580)),
+        now="2026-05-29T00:00:00+00:00",
+        max_age_days=10,
+        min_fraction=0.8,
+    )
+    assert ok, msg
+
+
+def test_health_stale_fails():
+    ok, msg = map_health(
+        meta={"built_at": "2026-05-01T00:00:00+00:00", "n_tests": 600},
+        current_keys=set(["a"]),
+        mapped_keys=set(["a"]),
+        now="2026-05-29T00:00:00+00:00",
+        max_age_days=10,
+        min_fraction=0.8,
+    )
+    assert not ok and "stale" in msg.lower()
+
+
+def test_health_undercoverage_fails():
+    ok, msg = map_health(
+        meta={"built_at": "2026-05-28T00:00:00+00:00", "n_tests": 10},
+        current_keys=set(str(i) for i in range(100)),
+        mapped_keys=set(str(i) for i in range(50)),
+        now="2026-05-29T00:00:00+00:00",
+        max_age_days=10,
+        min_fraction=0.8,
+    )
+    assert not ok and "coverage" in msg.lower()