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
feat(health): say how much of a coverage measurement still holds (#1742)
Raghav Chamadiya370793f9b4e3
diff --git a/packages/core/src/repowise/core/analysis/health/coverage/__init__.py b/packages/core/src/repowise/core/analysis/health/coverage/__init__.pyindex 775de31e1..91a8521b3 100644--- a/packages/core/src/repowise/core/analysis/health/coverage/__init__.py+++ b/packages/core/src/repowise/core/analysis/health/coverage/__init__.py@@ -9,6 +9,14 @@ from .contexts import (parse_coverage_sqlite,parse_lcov_contexts,)+from .decay import (+ STALE_DRIFT_PCT,+ STALE_MIN_MEASURED,+ CoverageDecay,+ decay_for_file,+ decay_since,+ measurement_ref,+)from .detector import detect_format, is_test_file, paired_test_file, parsefrom .discovery import (CoverageConfig,@@ -30,17 +38,23 @@ from .model import (from .repowise_json import parse_repowise_json__all__ = [+ "STALE_DRIFT_PCT",+ "STALE_MIN_MEASURED","ContextCoverageReport","CoverageConfig",+ "CoverageDecay","CoverageReport","FileCoverage","ResolvedCoverage","ResolvedTestCoverage","TestCoverage","build_coverage_map",+ "decay_for_file",+ "decay_since","detect_format","discover_artifacts","is_test_file",+ "measurement_ref","normalize_report_path","paired_test_file","parse",diff --git a/packages/core/src/repowise/core/analysis/health/coverage/decay.py b/packages/core/src/repowise/core/analysis/health/coverage/decay.pynew file mode 100644index 000000000..f396d1651--- /dev/null+++ b/packages/core/src/repowise/core/analysis/health/coverage/decay.py@@ -0,0 +1,175 @@+"""How much of a coverage measurement still describes the current file.++A coverage report is a measurement taken at one commit. Nothing re-runs the+tests, so the stored percentage keeps being served unchanged while the code+underneath it moves. The report date is already rendered next to the figure+(``ingested_at`` / ``ingested_commit_sha``), which tells a reader the+measurement is old but not what that costs *for this file*: a month-old report+is perfect for a file nobody touched and meaningless for the one under active+development, and the date reads identically in both cases.++This module answers the per-file half. Given the covered line set the report+recorded and the lines that have changed since it was taken, it splits the+measurement into the part that still describes the file and the part that does+not:++* ``confirmed`` - lines the report saw covered, that have not changed since.+ The measurement still holds here.+* ``invalidated`` - lines the report saw covered, that have changed since. The+ test that covered them ran against different code, so the fact is void. Not+ "now uncovered": unknown.++Deliberately no re-derived percentage. Whether an invalidated line is covered+today is exactly what nobody knows without running the tests, and a blended+"estimated coverage" would be a number no reader could check. ``drift_pct`` is+the share of the measurement that went unknown, which is a fact about the+*measurement*, not a claim about the code.++Ceiling, deliberate: the diff runs ``<ref>..HEAD``, so uncommitted work in the+tree is not counted as drift. Health analysis reads the working tree, so a file+with heavy uncommitted edits will under-report its drift until those land. The+upgrade is a second diff against the working tree, unioned in; it is left out+here because every consumer of this module renders a committed-history figure+beside it and mixing the two silently would be worse than the gap.+"""++from __future__ import annotations++import subprocess+from dataclasses import dataclass+from datetime import UTC, datetime++from ...change_risk.features import _git+from ...changed_lines import changed_lines+++@dataclass(frozen=True)+class CoverageDecay:+ """The measured/still-valid split for one file's coverage.++ ``measured`` is the size of the covered line set the report recorded, so+ ``confirmed + invalidated == measured`` always holds. ``drift_pct`` is+ ``invalidated / measured``, or 0.0 when the report recorded no covered+ lines at all (nothing to invalidate, so nothing drifted).+ """++ measured: int+ confirmed: int+ invalidated: int+ drift_pct: float++ @property+ def is_stale(self) -> bool:+ """Whether enough of the measurement went unknown to stop quoting it.++ The threshold is a display convention, not a scoring input. Nothing in+ this module deducts health points; consumers use it to decide whether+ to caveat the figure they render.+ """+ return self.measured >= STALE_MIN_MEASURED and self.drift_pct >= STALE_DRIFT_PCT+++#: Share of a measurement that must have gone unknown before a consumer should+#: caveat the figure. A fifth is enough that "91% covered" has stopped being a+#: fair summary of the file in front of the reader.+STALE_DRIFT_PCT = 20.0++#: Covered lines a file must have before the ratio means anything. Measured on+#: this repo's own index: without a floor the drift ranking is led by package+#: ``__init__.py`` files carrying a single covered line, where one version bump+#: is 100% drift and says nothing about the file. Ten lines puts the trigger at+#: two changed lines, which is the smallest move worth caveating a figure over.+STALE_MIN_MEASURED = 10+++def measurement_ref(+ repo_path: str,+ ingested_commit_sha: str | None,+ ingested_at: datetime | None,+) -> str | None:+ """The commit a measurement was taken at, for diffing forward from.++ Prefers the recorded sha. Falls back to the commit that was HEAD at+ ``ingested_at`` when the sha is absent, which it is for any row written+ before the repository row carried a head commit, and for any row written by+ a path that could not resolve one. The fallback is approximate by up to one+ commit and that is the correct trade: an approximate drift figure is worth+ more than no figure, and the error is bounded by how much lands in a single+ commit.++ ``None`` means the measurement cannot be placed in history at all, and the+ caller should render the stored figure without a drift claim rather than+ guess.+ """+ if ingested_commit_sha and _ref_exists(repo_path, ingested_commit_sha):+ return ingested_commit_sha+ if ingested_at is None:+ return None+ # ``ingested_at`` is written UTC-aware, but a SQLite-backed store hands it+ # back naive, and git reads a naive timestamp as *local* time. Left alone+ # that shifts the cut by the reader's offset and can pick the wrong side of+ # a commit. Stamping UTC back on is correct for every row this column has+ # ever held.+ stamped = ingested_at if ingested_at.tzinfo is not None else ingested_at.replace(tzinfo=UTC)+ try:+ sha = _git(+ ["rev-list", "-1", f"--before={stamped.isoformat()}", "HEAD"],+ repo_path,+ ).strip()+ except (subprocess.SubprocessError, OSError):+ return None+ return sha or None+++def _ref_exists(repo_path: str, ref: str) -> bool:+ try:+ return bool(+ _git(["rev-parse", "--verify", "--quiet", f"{ref}^{{commit}}"], repo_path, check=False)+ .strip()+ )+ except (subprocess.SubprocessError, OSError):+ return False+++def decay_since(+ repo_path: str,+ ref: str,+ covered_by_file: dict[str, set[int]],+) -> dict[str, CoverageDecay]:+ """Per-file decay for every file in *covered_by_file*, from one diff.++ One ``git diff`` for the whole range rather than one per file: the callers+ hold every coverage row in the repo, and a per-file diff would be a+ subprocess per row. Files with no changed lines in the range still get a+ record, with everything confirmed, so a consumer can render "nothing has+ moved" as distinct from "we did not check".++ Returns an empty mapping when the range cannot be diffed (an unknown ref, a+ repository git cannot read), because a decay figure that silently defaults+ to zero drift would read as a freshness claim this never made.+ """+ if not covered_by_file:+ return {}+ try:+ changed, _label = changed_lines(repo_path, f"{ref}..HEAD")+ except (ValueError, subprocess.SubprocessError, OSError):+ return {}++ out: dict[str, CoverageDecay] = {}+ for path, covered in covered_by_file.items():+ out[path] = decay_for_file(covered, changed.get(path) or set())+ return out+++def decay_for_file(covered: set[int], changed: set[int]) -> CoverageDecay:+ """The split for one file. Pure, and the unit the tests pin."""+ measured = len(covered)+ if measured == 0:+ return CoverageDecay(measured=0, confirmed=0, invalidated=0, drift_pct=0.0)+ invalidated = len(covered & changed)+ return CoverageDecay(+ measured=measured,+ confirmed=measured - invalidated,+ invalidated=invalidated,+ drift_pct=round(100.0 * invalidated / measured, 2),+ )diff --git a/packages/server/src/repowise/server/mcp_server/tool_health.py b/packages/server/src/repowise/server/mcp_server/tool_health.pyindex c026f494d..7e5e41b15 100644--- a/packages/server/src/repowise/server/mcp_server/tool_health.py+++ b/packages/server/src/repowise/server/mcp_server/tool_health.py@@ -13,6 +13,7 @@ from sqlalchemy import selectfrom repowise.core.analysis.health.biomarkers import continuous_biomarkersfrom repowise.core.analysis.health.churn_complexity import churn_complexity_pointsfrom repowise.core.analysis.health.complexity.languages import LANGUAGE_MAPS+from repowise.core.analysis.health.coverage import decay_since, measurement_reffrom repowise.core.analysis.health.defect_accuracy import compute_defect_accuracyfrom repowise.core.analysis.health.grading import HEALTHY_MIN, band_forfrom repowise.core.analysis.health.grading import distribution as health_distribution@@ -471,6 +472,58 @@ def _serialize_metric(}+def _attach_coverage_decay(+ payload: list[dict[str, Any]], rows: list[Any], repo_path: str+) -> None:+ """Add a ``decay`` block to each coverage row, in place.++ The stored percentage is a measurement taken at one commit and never+ recomputed, so on a file under active development it can describe code that+ no longer exists. ``decay`` says how much of that measurement still holds:+ ``confirmed`` covered lines are unchanged since the report, ``invalidated``+ ones have moved and are now unknown rather than uncovered.++ Targeted mode only. Dashboard mode declines ``covered_lines_json`` at the+ read (see the load above), and re-reading every blob to compute drift for a+ list nobody drilled into would undo that saving.++ Silent when the measurement cannot be placed in history, when git cannot+ read the range, or when the report predates every commit. A missing block+ means "not checked", which is why it is absent rather than zero: a zero+ would read as a freshness claim.+ """+ if not rows:+ return+ first = rows[0]+ ref = measurement_ref(+ repo_path,+ getattr(first, "ingested_commit_sha", None),+ getattr(first, "ingested_at", None),+ )+ if ref is None:+ return+ covered_by_file = {+ entry["file_path"]: set(entry.get("covered_lines") or [])+ for entry in payload+ if entry.get("covered_lines")+ }+ decays = decay_since(repo_path, ref, covered_by_file)+ if not decays:+ return+ for entry in payload:+ d = decays.get(entry["file_path"])+ if d is None:+ continue+ entry["decay"] = {+ "measured_lines": d.measured,+ "confirmed_lines": d.confirmed,+ "invalidated_lines": d.invalidated,+ "drift_pct": d.drift_pct,+ "stale": d.is_stale,+ "measured_at_commit": ref[:12],+ }++def _serialize_coverage_row(row: Any, *, covered_lines: bool = True) -> dict[str, Any]:"""One coverage row. ``covered_lines=False`` omits the per-line array.@@ -1659,6 +1712,7 @@ async def get_health(# detail is available in targeted mode.if scoped:coverage_payload = [_serialize_coverage_row(r) for r in coverage_rows]+ _attach_coverage_decay(coverage_payload, coverage_rows, str(ctx.path))else:# Built narrow, not built wide and subtracted from. These rows came# back without the column at all (see the read above).diff --git a/tests/unit/health/test_coverage_decay.py b/tests/unit/health/test_coverage_decay.pynew file mode 100644index 000000000..95d69a1ab--- /dev/null+++ b/tests/unit/health/test_coverage_decay.py@@ -0,0 +1,197 @@+"""Coverage decay: how much of a measurement still describes the file."""++from __future__ import annotations++import os+import subprocess+from datetime import UTC, datetime, timedelta++import pytest++from repowise.core.analysis.health.coverage import (+ STALE_DRIFT_PCT,+ STALE_MIN_MEASURED,+ decay_for_file,+ decay_since,+ measurement_ref,+)++# --- the pure split --------------------------------------------------------+++def test_nothing_changed_confirms_everything() -> None:+ d = decay_for_file({1, 2, 3}, set())+ assert (d.measured, d.confirmed, d.invalidated) == (3, 3, 0)+ assert d.drift_pct == 0.0+++def test_every_covered_line_changed_invalidates_everything() -> None:+ d = decay_for_file({1, 2, 3}, {1, 2, 3})+ assert (d.measured, d.confirmed, d.invalidated) == (3, 0, 3)+ assert d.drift_pct == 100.0+++def test_only_covered_lines_count_as_drift() -> None:+ """A change to a line the report never saw covered is not drift.++ It may well be new uncovered code, but this module reports on the+ *measurement*, and a line outside the covered set was never part of it.+ """+ d = decay_for_file({1, 2}, {2, 50, 51, 52})+ assert (d.confirmed, d.invalidated) == (1, 1)+ assert d.drift_pct == 50.0+++def test_no_covered_lines_does_not_divide_by_zero() -> None:+ d = decay_for_file(set(), {1, 2, 3})+ assert (d.measured, d.confirmed, d.invalidated) == (0, 0, 0)+ assert d.drift_pct == 0.0+ assert d.is_stale is False+++def test_confirmed_and_invalidated_always_sum_to_measured() -> None:+ d = decay_for_file({1, 4, 9, 16, 25}, {4, 16, 99})+ assert d.confirmed + d.invalidated == d.measured+++# --- the staleness convention ----------------------------------------------+++def test_small_file_is_never_stale_on_ratio_alone() -> None:+ """A one-line __init__ at 100% drift is noise, not a stale measurement.++ Without the floor this shape led the drift ranking on this repo's own+ index: a version bump is the only covered line, so one edit reads as total+ decay while saying nothing about the file.+ """+ d = decay_for_file({1}, {1})+ assert d.drift_pct == 100.0+ assert d.is_stale is False+++def test_stale_once_the_file_is_big_enough_and_drift_clears_the_bar() -> None:+ covered = set(range(1, STALE_MIN_MEASURED + 1))+ changed = set(list(covered)[:3]) # 30% of 10+ d = decay_for_file(covered, changed)+ assert d.measured >= STALE_MIN_MEASURED+ assert d.drift_pct > STALE_DRIFT_PCT+ assert d.is_stale is True+++def test_big_file_under_the_bar_is_not_stale() -> None:+ covered = set(range(1, 101))+ d = decay_for_file(covered, {1, 2}) # 2%+ assert d.is_stale is False+++# --- end-to-end against a real git repo ------------------------------------+++def _git(cwd, *args: str, when: str | None = None) -> str:+ """Run git in *cwd*. *when* pins both dates, since ``rev-list --before``+ filters on the COMMITTER date and ``git commit --date`` only sets the+ author one."""+ env = None+ if when is not None:+ env = {**os.environ, "GIT_COMMITTER_DATE": when, "GIT_AUTHOR_DATE": when}+ return subprocess.run(+ ["git", *args], cwd=cwd, check=True, capture_output=True, text=True, env=env+ ).stdout+++def git_repo(tmp_path):+ _git(tmp_path, "init", "-q")+ _git(tmp_path, "config", "user.email", "[email protected]")+ _git(tmp_path, "config", "user.name", "t")+ (tmp_path / "mod.py").write_text("a = 1\nb = 2\nc = 3\nd = 4\n", encoding="utf-8")+ (tmp_path / "quiet.py").write_text("x = 1\ny = 2\n", encoding="utf-8")+ _git(tmp_path, "add", "-A")+ _git(tmp_path, "commit", "-qm", "init")+ return tmp_path+++def test_decay_since_splits_an_edited_file_and_leaves_an_untouched_one(git_repo) -> None:+ base = _git(git_repo, "rev-parse", "HEAD").strip()+ (git_repo / "mod.py").write_text("a = 1\nb = 22\nc = 3\nd = 4\n", encoding="utf-8")+ _git(git_repo, "add", "-A")+ _git(git_repo, "commit", "-qm", "edit line 2")++ out = decay_since(str(git_repo), base, {"mod.py": {1, 2, 3}, "quiet.py": {1, 2}})++ # Line 2 was covered and has changed; 1 and 3 still stand.+ assert (out["mod.py"].confirmed, out["mod.py"].invalidated) == (2, 1)+ # A file nothing touched keeps its whole measurement, and is reported+ # rather than omitted, so "nothing moved" is distinguishable from+ # "not checked".+ assert (out["quiet.py"].confirmed, out["quiet.py"].invalidated) == (2, 0)+++def test_decay_since_returns_empty_on_an_unknown_ref(git_repo) -> None:+ """An unresolvable ref must not read as zero drift.++ Zero drift is a freshness claim. When the range cannot be diffed the+ honest answer is no answer, so the caller renders the stored figure+ without a decay line rather than one asserting nothing has moved.+ """+ assert decay_since(str(git_repo), "deadbeef" * 5, {"mod.py": {1}}) == {}+++def test_decay_since_short_circuits_on_no_input(git_repo) -> None:+ assert decay_since(str(git_repo), "HEAD", {}) == {}+++# --- placing the measurement in history ------------------------------------+++def test_measurement_ref_prefers_a_recorded_sha(git_repo) -> None:+ head = _git(git_repo, "rev-parse", "HEAD").strip()+ assert measurement_ref(str(git_repo), head, None) == head+++def test_measurement_ref_falls_back_to_the_timestamp(git_repo) -> None:+ """The sha is absent on rows written before the repo carried a head commit.++ The second commit is dated an hour ahead so "now" sits strictly between the+ two, which is the shape the fallback exists for: pick the commit that was+ HEAD when the report was taken, not the one that is HEAD today.+ """+ first = _git(git_repo, "rev-parse", "HEAD").strip()+ later = (datetime.now(UTC) + timedelta(hours=1)).isoformat()+ (git_repo / "mod.py").write_text("a = 9\n", encoding="utf-8")+ _git(git_repo, "add", "-A")+ _git(git_repo, "commit", "-qm", "later", when=later)++ assert measurement_ref(str(git_repo), None, datetime.now(UTC)) == first+++def test_measurement_ref_is_none_when_the_report_predates_all_history(git_repo) -> None:+ """No commit existed when the measurement was taken, so it cannot be placed.++ ``None`` here is load-bearing: ``decay_since`` refuses to run without a+ ref, so the caller renders the stored figure with no drift claim instead of+ one asserting nothing has moved.+ """+ ancient = datetime(2000, 1, 1, tzinfo=UTC)+ assert measurement_ref(str(git_repo), None, ancient) is None+++def test_measurement_ref_ignores_an_unknown_sha_and_falls_back(git_repo) -> None:+ resolved = measurement_ref(str(git_repo), "deadbeef" * 5, datetime.now(UTC))+ assert resolved == _git(git_repo, "rev-parse", "HEAD").strip()+++def test_measurement_ref_is_none_when_the_measurement_cannot_be_placed(git_repo) -> None:+ assert measurement_ref(str(git_repo), None, None) is None+++def test_naive_timestamp_is_read_as_utc_not_local(git_repo) -> None:+ """A SQLite store hands back a naive datetime; git would read it as local.++ Both spellings of the same instant must resolve to the same commit, which+ they do not if the naive one is left for git to localise.+ """+ now = datetime.now(UTC)+ aware = measurement_ref(str(git_repo), None, now)+ naive = measurement_ref(str(git_repo), None, now.replace(tzinfo=None))+ assert aware == naivediff --git a/tests/unit/server/mcp/test_health_coverage_decay.py b/tests/unit/server/mcp/test_health_coverage_decay.pynew file mode 100644index 000000000..4bafa5dbb--- /dev/null+++ b/tests/unit/server/mcp/test_health_coverage_decay.py@@ -0,0 +1,117 @@+"""get_health attaches per-file coverage decay in targeted mode."""++from __future__ import annotations++import json+import subprocess+import types+from datetime import UTC, datetime++import pytest++from repowise.server.mcp_server.tool_health import (+ _attach_coverage_decay,+ _serialize_coverage_row,+)+++def _git(cwd, *args: str) -> str:+ return subprocess.run(+ ["git", *args], cwd=cwd, check=True, capture_output=True, text=True+ ).stdout+++def repo(tmp_path):+ _git(tmp_path, "init", "-q")+ _git(tmp_path, "config", "user.email", "[email protected]")+ _git(tmp_path, "config", "user.name", "t")+ (tmp_path / "mod.py").write_text("a = 1\nb = 2\nc = 3\nd = 4\n", encoding="utf-8")+ _git(tmp_path, "add", "-A")+ _git(tmp_path, "commit", "-qm", "init")+ return tmp_path+++def _row(path: str, covered: list[int], *, sha: str | None, pct: float = 100.0):+ return types.SimpleNamespace(+ file_path=path,+ source_format="lcov",+ line_coverage_pct=pct,+ branch_coverage_pct=None,+ covered_lines_json=json.dumps(covered),+ total_coverable_lines=len(covered),+ ingested_at=datetime.now(UTC),+ ingested_commit_sha=sha,+ )+++def test_decay_marks_the_lines_that_moved_since_the_report(repo) -> None:+ base = _git(repo, "rev-parse", "HEAD").strip()+ (repo / "mod.py").write_text("a = 1\nb = 22\nc = 3\nd = 4\n", encoding="utf-8")+ _git(repo, "add", "-A")+ _git(repo, "commit", "-qm", "edit")++ rows = [_row("mod.py", [1, 2, 3], sha=base)]+ payload = [_serialize_coverage_row(r) for r in rows]+ _attach_coverage_decay(payload, rows, str(repo))++ decay = payload[0]["decay"]+ assert decay["measured_lines"] == 3+ assert decay["invalidated_lines"] == 1+ assert decay["confirmed_lines"] == 2+ assert decay["measured_at_commit"] == base[:12]+++def test_the_stored_percentage_is_never_rewritten(repo) -> None:+ """Decay annotates the measurement; it must not restate it.++ The report said what it said. Re-deriving a percentage from a partial+ invalidation would invent a figure nobody can check, which is the whole+ reason this is a separate block.+ """+ base = _git(repo, "rev-parse", "HEAD").strip()+ (repo / "mod.py").write_text("a = 1\nb = 22\nc = 33\nd = 4\n", encoding="utf-8")+ _git(repo, "add", "-A")+ _git(repo, "commit", "-qm", "edit")++ rows = [_row("mod.py", [1, 2, 3], sha=base, pct=75.0)]+ payload = [_serialize_coverage_row(r) for r in rows]+ _attach_coverage_decay(payload, rows, str(repo))++ assert payload[0]["line_coverage_pct"] == 75.0+ assert payload[0]["decay"]["invalidated_lines"] == 2+++def test_no_decay_block_when_the_measurement_cannot_be_placed(repo) -> None:+ """Absent, not zero. A zero drift block would read as a freshness claim."""+ rows = [_row("mod.py", [1, 2, 3], sha=None)]+ rows[0].ingested_at = None+ payload = [_serialize_coverage_row(r) for r in rows]+ _attach_coverage_decay(payload, rows, str(repo))++ assert "decay" not in payload[0]+++def test_a_row_with_no_covered_lines_gets_no_decay_block(repo) -> None:+ head = _git(repo, "rev-parse", "HEAD").strip()+ rows = [_row("mod.py", [], sha=head)]+ payload = [_serialize_coverage_row(r) for r in rows]+ _attach_coverage_decay(payload, rows, str(repo))++ assert "decay" not in payload[0]+++def test_untouched_file_reports_a_confirmed_measurement(repo) -> None:+ head = _git(repo, "rev-parse", "HEAD").strip()+ rows = [_row("mod.py", [1, 2, 3], sha=head)]+ payload = [_serialize_coverage_row(r) for r in rows]+ _attach_coverage_decay(payload, rows, str(repo))++ assert payload[0]["decay"]["invalidated_lines"] == 0+ assert payload[0]["decay"]["stale"] is False+++def test_empty_row_list_is_a_no_op(repo) -> None:+ payload: list[dict] = []+ _attach_coverage_decay(payload, [], str(repo))+ assert payload == []