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.

feat(change-risk): health_delta reports each changed file's score before and after (#4123)

Raghav Chamadiyad375a11bcd1c
diff --git a/docs/reference/MCP_RESPONSE_FIELDS.md b/docs/reference/MCP_RESPONSE_FIELDS.md
index 46b67a9ca..13bbd59d7 100644
--- a/docs/reference/MCP_RESPONSE_FIELDS.md
+++ b/docs/reference/MCP_RESPONSE_FIELDS.md
@@ -284,6 +284,8 @@ Every float is rounded to 4 significant digits. Direct rows' `structural_score`
**health_delta.** Both revisions are analysed from their own content, and a finding at head is reported only when the diff explains it. `scope` counts changed, eligible, analysed, skipped and failed files; `status` is `available`, `partial` or `unavailable`, and `partial` is never a clean bill. Documentation and configuration files (Markdown, JSON, YAML, TOML and the other doc or config extensions) are skipped with reason `not_code` and never make a run `partial`; a change made only of them reads `clear_in_analyzed_scope` with a headline saying health analysis does not cover them. Tree-sitter query files (`.scm` under a `queries` directory) and text templates (`.j2`, `.jinja`, `.jinja2`, `.tmpl`, `.tpl`, `.hbs`, `.mustache`, `.ejs`, `.njk`) are skipped with reason `not_analyzable_data`, which also never makes a run `partial`; a change made only of them reads `clear_in_analyzed_scope` with its own headline, since they can still change behaviour. HTML, schema and other files with no health dialect still make a run `partial`. `introduced`, `worsened` and `resolved` are totals; `top_findings` holds the three most actionable, with `findings_total`. Each finding names `dimension`, `biomarker`, `severity`, `path`, `symbol`, head-side `lines`, a `reason`, and an `attribution` (`basis` of `added_lines`, `changed_symbol`, `changed_call_edge`, `new_file`, `file_change`, `context_change` or `unknown`, with a `confidence`). Identity ignores line numbers, so moved code introduces nothing. `inspect` gives the `finding_id` call that expands one; ids are bound to the two revisions. A finding that matches a stored one carries `health_reference` for `get_health(finding_id=...)`. Performance findings carry `opportunity_id` and are ordered by opportunity rank.
+`files` lists up to 10 analysed files, largest structure move first, each with `base_score`, `head_score`, `base_structure`, `head_structure` (structure deduction), `nloc_base` and `nloc_head`; a side the file is missing on reads null. `files_total` counts them all. `score_basis` is `structure_only`: each score is 10 minus the structure deduction, the reading `get_health(counts="code_shape")` gives, from two passes that read no git history or coverage. A deleted file has a base-only row, with `moved_to` naming where its code went when it was split. `score_change` averages files scored on both sides, weighted by base nloc so a file that grows while improving keeps its gain: `base`, `head`, `delta` (two decimals), `structure_delta` (the deduction change, which still moves when a file sits on the 1.0 floor) and `files_compared`.
+
**impacted_tests.** The selection `repowise impacted-tests` makes, over every path the change touched whatever the score's filters, less the repowise output the score also leaves out (the index, and a managed file whose only change is repowise's block or entry), which the CLI still reads when tracked. `status` is `selected` or `run_all` (or `no_index`, `unknown`, `config_invalid`, `timeout`, `busy`, `no_source_line_changes` when nothing was selected, each with `run_all` true; `timeout` means the selection took over 30 seconds and `busy` that one for this repository is still running, and `repowise impacted-tests` gives the answer); `run_all` true means no subset can be vouched for, with up to three `reasons` (`reasons_total` counts them all). `tests_to_run` (capped at ten, `total` and `truncated`) is in `repowise impacted-tests`' [run order](CLI_REFERENCE.md#repowise-impacted-tests-revspec), the `always_run_total` tests that run with every subset last; `why` gives each listed file's reason. With `run_all` the list is what to run first. `tests_to_run_kind` is `test_id` when a coverage node id is listed, else `test_file`. `basis` is `measured` when coverage decided a changed file, `inferred` when only the graph or a rule did, `none` when nothing named a test; `basis_by_file` names the evidence per changed file (`coverage`, `changed-test`, `call-graph`, `import-graph`, `conftest`, `full-run`, `no-tests-needed`, ...). With a coverage map, `map_present` is true and `line_coverage` buckets the scored files' changed lines, matched on the side of the diff the map was measured at (by file when it was measured at neither): `untested_changes`, `stale_test_candidates` (covered lines whose test file is absent from the diff), `covered`, `no_coverage_data`. Build the measured map with `coverage run --contexts=test` and `repowise coverage add`.
**patch_coverage.** Present when the index stores coverage; the same computation and JSON shape `repowise coverage check --format json` gates on. `patch_coverage_pct` is null when no changed line is executable; files the report never names read `not_in_report`. `scope.freshness` is `stale` when coverage was measured at another commit than the change's head; then a file git shows changed since that commit reads `stale_file`, with no figures, and only untouched files keep theirs. `path_gates` judges the path-scoped gates in `coverage.gates`. Each file row carries `risk` (`fix_pressure`, `dependents`, `hotspot`, `bug_magnet`, `risky`, `reasons`, `basis`) and up to eight `hints` per uncovered range: `range`, `symbol`, up to three `tests` to extend, and a `basis` of `per_test` (measured), `call_graph` or `import_graph` (inferred). Without a `revspec`, it covers everything a push would bring, diffed from the merge-base with the default base branch.
diff --git a/packages/core/src/repowise/core/analysis/change_health/analyzer.py b/packages/core/src/repowise/core/analysis/change_health/analyzer.py
index c1fa77797..eb2357db5 100644
--- a/packages/core/src/repowise/core/analysis/change_health/analyzer.py
+++ b/packages/core/src/repowise/core/analysis/change_health/analyzer.py
@@ -21,7 +21,7 @@ from ...ingestion.models import (
)
from ...ingestion.parser import parse_file
from ...test_paths import is_test_related_path
-from ..health import HealthAnalyzer, HealthFindingData
+from ..health import HealthAnalyzer, HealthFileMetricData, HealthFindingData
from ..health.complexity.languages import has_health_dialect
from ..health.source_reader import MappingSourceReader
@@ -70,6 +70,8 @@ class RevisionAnalysis:
#: Dependents count per file, as this side's centrality gates read it.
dependents: dict[str, int] = field(default_factory=dict)
symbols: dict[str, list[Symbol]] = field(default_factory=dict)
+ #: Per-file scores and deductions, by path.
+ metrics: dict[str, HealthFileMetricData] = field(default_factory=dict)
def findings_for(self, paths: set[str]) -> list[HealthFindingData]:
return [f for f in self.findings if f.file_path in paths]
@@ -117,6 +119,7 @@ class RevisionHealthAnalyzer:
result.analyzed = set(usable)
result.dependents = analyzer.file_dependents()
result.symbols = {pf.file_info.path: pf.symbols for pf in parsed}
+ result.metrics = {m.file_path: m for m in report.metrics}
return result
# -- internals ----------------------------------------------------------
diff --git a/packages/core/src/repowise/core/analysis/change_health/file_scores.py b/packages/core/src/repowise/core/analysis/change_health/file_scores.py
new file mode 100644
index 000000000..5d46cb200
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/change_health/file_scores.py
@@ -0,0 +1,142 @@
+"""Per-file base and head scores for a change, read off both in-memory passes.
+
+The passes see only the changed files' bytes, with no git history or coverage,
+so each score is the code-shape reading, ``10 - structure`` (``structure_only``,
+as ``counts="code_shape"`` reads the index): comparable side to side.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, replace
+from typing import Any
+
+from ..health import HealthFileMetricData
+from ..health.counts import code_shape_score
+
+SCORE_BASIS = "structure_only"
+
+
+@dataclass(frozen=True, slots=True)
+class FileScoreDelta:
+ """One changed file's score and structure deduction on each side."""
+
+ path: str
+ base_score: float | None
+ head_score: float | None
+ base_structure: float | None
+ head_structure: float | None
+ nloc_base: int | None
+ nloc_head: int | None
+ #: A deleted file's code moved to these files.
+ moved_to: tuple[str, ...] = ()
+
+ @property
+ def structure_change(self) -> float:
+ """Signed structure deduction change, a missing side read as no deduction."""
+ return (self.head_structure or 0.0) - (self.base_structure or 0.0)
+
+ def as_dict(self) -> dict[str, Any]:
+ return {
+ "path": self.path,
+ "base_score": _round(self.base_score),
+ "head_score": _round(self.head_score),
+ "base_structure": _round(self.base_structure),
+ "head_structure": _round(self.head_structure),
+ "nloc_base": self.nloc_base,
+ "nloc_head": self.nloc_head,
+ **({"moved_to": list(self.moved_to)} if self.moved_to else {}),
+ }
+
+
+@dataclass(frozen=True, slots=True)
+class ScoreChange:
+ """The changed files' average on each side, weighted by base nloc."""
+
+ base: float
+ head: float
+ structure_delta: float
+ files_compared: int
+
+ def as_dict(self) -> dict[str, Any]:
+ return {
+ "base": round(self.base, 2),
+ "head": round(self.head, 2),
+ "delta": round(round(self.head, 2) - round(self.base, 2), 2),
+ "structure_delta": round(self.structure_delta, 2),
+ "weighting": "base_nloc",
+ "files_compared": self.files_compared,
+ }
+
+
+def file_score_deltas(
+ base: Mapping[str, HealthFileMetricData],
+ head: Mapping[str, HealthFileMetricData],
+ paths: Iterable[str],
+ rename: Mapping[str, str],
+ *,
+ departed: Mapping[str, list[str]] | None = None,
+) -> list[FileScoreDelta]:
+ """A row per head path, largest structure move first. *rename* is ``{base: head}``.
+
+ *departed* maps each deleted file to where its code moved; it gets a base-only row.
+ """
+ base_of = {new: old for old, new in rename.items()}
+ rows = [_row(path, base.get(base_of.get(path, path)), head.get(path)) for path in paths]
+ rows += [
+ replace(_row(path, base.get(path), None), moved_to=tuple(moved))
+ for path, moved in (departed or {}).items()
+ ]
+ return sorted(rows, key=lambda r: (-abs(r.structure_change), r.path))
+
+
+def score_change(rows: Iterable[FileScoreDelta]) -> ScoreChange | None:
+ """Both sides' average over files scored on both, or ``None`` when there are none.
+
+ Weighted by base nloc on both sides, so a file that grows while it improves
+ does not cancel its own gain.
+ """
+ paired = [
+ r
+ for r in rows
+ if r.base_score is not None and r.head_score is not None and (r.nloc_base or 0) > 0
+ ]
+ if not paired:
+ return None
+ weight = sum(r.nloc_base or 0 for r in paired)
+
+ def mean(values: Iterable[float]) -> float:
+ return sum(v * (r.nloc_base or 0) for v, r in zip(values, paired, strict=True)) / weight
+
+ return ScoreChange(
+ base=mean(r.base_score or 0.0 for r in paired),
+ head=mean(r.head_score or 0.0 for r in paired),
+ structure_delta=mean(
+ (r.head_structure or 0.0) - (r.base_structure or 0.0) for r in paired
+ ),
+ files_compared=len(paired),
+ )
+
+
+def _row(
+ path: str, base: HealthFileMetricData | None, head: HealthFileMetricData | None
+) -> FileScoreDelta:
+ return FileScoreDelta(
+ path=path,
+ base_score=_shape_score(base),
+ head_score=_shape_score(head),
+ base_structure=base.structure_deduction if base else None,
+ head_structure=head.structure_deduction if head else None,
+ nloc_base=base.nloc if base else None,
+ nloc_head=head.nloc if head else None,
+ )
+
+
+def _shape_score(metric: HealthFileMetricData | None) -> float | None:
+ if metric is None or metric.score is None:
+ return None
+ return code_shape_score(metric.structure_deduction)
+
+
+def _round(value: float | None) -> float | None:
+ return round(value, 2) if value is not None else None
diff --git a/packages/core/src/repowise/core/analysis/change_health/models.py b/packages/core/src/repowise/core/analysis/change_health/models.py
index 2b365cdca..702bcb53f 100644
--- a/packages/core/src/repowise/core/analysis/change_health/models.py
+++ b/packages/core/src/repowise/core/analysis/change_health/models.py
@@ -5,6 +5,8 @@ from __future__ import annotations
from dataclasses import dataclass, field
from typing import Any, Literal
+from .file_scores import FileScoreDelta
+
DeltaStatus = Literal[
"available",
"partial",
@@ -198,6 +200,8 @@ class ChangeHealthDelta:
timing_ms: float = 0.0
cache_hit: bool = False
limits: list[str] = field(default_factory=list)
+ #: Per-file scores on both sides, largest structure move first.
+ files: list[FileScoreDelta] = field(default_factory=list)
@property
def introduced_total(self) -> int:
diff --git a/packages/core/src/repowise/core/analysis/change_health/service.py b/packages/core/src/repowise/core/analysis/change_health/service.py
index d0f6cb086..4d60b3756 100644
--- a/packages/core/src/repowise/core/analysis/change_health/service.py
+++ b/packages/core/src/repowise/core/analysis/change_health/service.py
@@ -23,6 +23,7 @@ from ..health.perf.causal import PERFORMANCE_MODEL_VERSION
from ..health.scoring import ADVISORY_DIMENSION, is_advisory
from .analyzer import RevisionAnalysis, RevisionHealthAnalyzer, language_for, language_of
from .attribution import FindingAttributor, changed_symbols_for
+from .file_scores import file_score_deltas
from .identity import change_finding_id, finding_key, severity_rank
from .matcher import FindingMatcher, MatchedFinding, MatchResult
from .models import (
@@ -281,6 +282,13 @@ class ChangeHealthDeltaService:
skipped=skipped,
moved_to={old: new for old, new in moves.destinations().items() if old in gone},
limits=_limits(sides.head_run.findings_for(subject)),
+ files=file_score_deltas(
+ sides.base_run.metrics,
+ sides.head_run.metrics,
+ subject,
+ sides.rename,
+ departed={old: moves.destinations().get(old, []) for old in gone},
+ ),
)
delta.timing_ms = (time.perf_counter() - started) * 1000
return delta
diff --git a/packages/server/src/repowise/server/mcp_server/_budget/contracts.py b/packages/server/src/repowise/server/mcp_server/_budget/contracts.py
index 6787ecb32..86ac6b44f 100644
--- a/packages/server/src/repowise/server/mcp_server/_budget/contracts.py
+++ b/packages/server/src/repowise/server/mcp_server/_budget/contracts.py
@@ -152,6 +152,7 @@ _CONTRACTS: dict[str, ResponseBudgetContract] = {
"patch_coverage",
"impacted_tests",
"health_delta.skipped",
+ "health_delta.files[]",
"health_delta.top_findings[]",
"evidence",
),
diff --git a/packages/server/src/repowise/server/mcp_server/_change_health.py b/packages/server/src/repowise/server/mcp_server/_change_health.py
index 31e68dbe5..8e891b6d7 100644
--- a/packages/server/src/repowise/server/mcp_server/_change_health.py
+++ b/packages/server/src/repowise/server/mcp_server/_change_health.py
@@ -9,6 +9,11 @@ from __future__ import annotations
from typing import Any
+from repowise.core.analysis.change_health.file_scores import (
+ SCORE_BASIS,
+ FileScoreDelta,
+ score_change,
+)
from repowise.core.analysis.change_health.models import ChangeFinding, ChangeHealthDelta
from repowise.core.analysis.review_directive import (
CoveringTestEvidence,
@@ -27,6 +32,8 @@ REASON_LIMIT = 3
#: Deleted sources listed with where their code went.
MOVED_TO_LIMIT = 10
+#: Per-file score rows carried in ``health_delta.files``.
+FILE_ROWS_LIMIT = 10
#: Findings whose next-action is carried in the default response.
_ACTIONABLE_FINDINGS = 2
@@ -185,6 +192,8 @@ def health_delta_block(delta: ChangeHealthDelta, *, revspec: str | None) -> dict
block.update(_nonzero(improved=delta.improved_total, moved=delta.moved_total))
if delta.moved_to:
block["moved_to"] = dict(list(delta.moved_to.items())[:MOVED_TO_LIMIT])
+ if delta.files:
+ block.update(_file_scores(delta.files))
if delta.skipped:
block["skipped"] = _skipped(delta.skipped)
if delta.limits:
@@ -192,6 +201,19 @@ def health_delta_block(delta: ChangeHealthDelta, *, revspec: str | None) -> dict
return block
+def _file_scores(rows: list[FileScoreDelta]) -> dict[str, Any]:
+ """The changed files' scores before and after, and their base-nloc average."""
+ out: dict[str, Any] = {
+ "score_basis": SCORE_BASIS,
+ "files": [r.as_dict() for r in rows[:FILE_ROWS_LIMIT]],
+ "files_total": len(rows),
+ }
+ change = score_change(rows)
+ if change is not None:
+ out["score_change"] = change.as_dict()
+ return out
+
+
def finding_row(finding: ChangeFinding, revspec: str | None) -> dict[str, Any]:
"""One surfaced finding, with the exact call that expands it."""
row: dict[str, Any] = {
diff --git a/tests/fixtures/mcp/tool_response_shapes.json b/tests/fixtures/mcp/tool_response_shapes.json
index 987aa0310..b84120c6d 100644
--- a/tests/fixtures/mcp/tool_response_shapes.json
+++ b/tests/fixtures/mcp/tool_response_shapes.json
@@ -207,6 +207,18 @@
"by_dimension": {},
"by_severity": {},
"explanation": null,
+ "files": [
+ {
+ "base_score": null,
+ "base_structure": null,
+ "head_score": null,
+ "head_structure": null,
+ "nloc_base": null,
+ "nloc_head": null,
+ "path": null
+ }
+ ],
+ "files_total": null,
"findings_emitted": null,
"findings_total": null,
"introduced": null,
@@ -218,6 +230,15 @@
"failed": null,
"skipped": null
},
+ "score_basis": null,
+ "score_change": {
+ "base": null,
+ "delta": null,
+ "files_compared": null,
+ "head": null,
+ "structure_delta": null,
+ "weighting": null
+ },
"skipped": {
"by_reason": {
"not_health_analyzable": null
diff --git a/tests/unit/change_health/test_file_scores.py b/tests/unit/change_health/test_file_scores.py
new file mode 100644
index 000000000..28573d570
--- /dev/null
+++ b/tests/unit/change_health/test_file_scores.py
@@ -0,0 +1,69 @@
+"""Per-file before/after scores on a change, structure only."""
+
+from __future__ import annotations
+
+from repowise.core.analysis.change_health.service import ChangeHealthDeltaService, DeltaRequest
+from repowise.server.mcp_server._change_health import health_delta_block
+
+from .conftest import python_complex
+
+
+def _delta(repo):
+ service = ChangeHealthDeltaService(repo_path=str(repo.path))
+ return service.compare(DeltaRequest(str(repo.path), "HEAD"))
+
+
+def test_a_simplified_file_reports_its_score_on_both_sides(make_repo):
+ repo = make_repo()
+ repo.commit("seed", {"app.py": python_complex("tangle", 26), "ok.py": "x = 1\n"})
+ repo.commit("simplify", {"app.py": python_complex("tangle", 1), "ok.py": "x = 2\n"})
+
+ block = health_delta_block(_delta(repo), revspec="HEAD")
+
+ assert block["files_total"] == 2
+ assert block["score_basis"] == "structure_only"
+ row = next(r for r in block["files"] if r["path"] == "app.py")
+ assert row["head_score"] > row["base_score"]
+ assert row["head_structure"] < row["base_structure"]
+ assert row["nloc_base"] > row["nloc_head"] > 0
+ # Largest move first.
+ assert block["files"][0]["path"] == "app.py"
+ change = block["score_change"]
+ assert change["weighting"] == "base_nloc"
+ assert change["head"] > change["base"]
+ assert change["structure_delta"] < 0
+ assert change["delta"] == round(change["head"] - change["base"], 2)
+
+
+def test_a_new_file_has_no_base_score_and_stays_out_of_the_average(make_repo):
+ repo = make_repo()
+ repo.commit("seed", {"ok.py": "x = 1\n"})
+ repo.commit("add", {"ok.py": "x = 1\n", "app.py": python_complex("tangle", 14)})
+
+ block = health_delta_block(_delta(repo), revspec="HEAD")
+
+ row = next(r for r in block["files"] if r["path"] == "app.py")
+ assert row["base_score"] is None and row["head_score"] is not None
+ assert "score_change" not in block or block["score_change"]["files_compared"] == 0
+
+
+def test_rows_are_capped_with_the_total_kept(make_repo):
+ repo = make_repo()
+ seed = {f"m{i}.py": python_complex(f"f{i}", 8) for i in range(12)}
+ repo.commit("seed", seed)
+ repo.commit("touch", {p: python_complex(p[:-3], 2) for p in seed})
+
+ block = health_delta_block(_delta(repo), revspec="HEAD")
+
+ assert block["files_total"] == 12
+ assert len(block["files"]) == 10
+
+
+def test_a_split_source_has_a_base_only_row_naming_where_its_code_went(make_repo):
+ from .test_split_source import split
+
+ block = health_delta_block(_delta(split(make_repo)), revspec="HEAD")
+
+ source = next(r for r in block["files"] if r["path"] == "tool.py")
+ assert source["head_score"] is None and source["base_score"] is not None
+ assert source["moved_to"] == ["tool/a.py", "tool/b.py", "tool/c.py"]
diff --git a/tests/unit/server/mcp/test_cross_tool_reference_contracts.py b/tests/unit/server/mcp/test_cross_tool_reference_contracts.py
index 35708cd2a..15fe1ff5e 100644
--- a/tests/unit/server/mcp/test_cross_tool_reference_contracts.py
+++ b/tests/unit/server/mcp/test_cross_tool_reference_contracts.py
@@ -158,7 +158,7 @@ _REFERENCE_KINDS = (
)
_EXPECTED_KINDS = {
"get_answer": {"file"},
- "get_change_risk": set(),
+ "get_change_risk": {"file"},
"get_context": {
"file",
"symbol",