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(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.mdindex 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.pyindex 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_filefrom ...test_paths import is_test_related_path-from ..health import HealthAnalyzer, HealthFindingData+from ..health import HealthAnalyzer, HealthFileMetricData, HealthFindingDatafrom ..health.complexity.languages import has_health_dialectfrom ..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.pynew file mode 100644index 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 Nonediff --git a/packages/core/src/repowise/core/analysis/change_health/models.py b/packages/core/src/repowise/core/analysis/change_health/models.pyindex 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 annotationsfrom dataclasses import dataclass, fieldfrom typing import Any, Literal+from .file_scores import FileScoreDelta+DeltaStatus = Literal["available","partial",@@ -198,6 +200,8 @@ class ChangeHealthDelta:timing_ms: float = 0.0cache_hit: bool = Falselimits: list[str] = field(default_factory=list)+ #: Per-file scores on both sides, largest structure move first.+ files: list[FileScoreDelta] = field(default_factory=list)@propertydef 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.pyindex 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_VERSIONfrom ..health.scoring import ADVISORY_DIMENSION, is_advisoryfrom .analyzer import RevisionAnalysis, RevisionHealthAnalyzer, language_for, language_offrom .attribution import FindingAttributor, changed_symbols_for+from .file_scores import file_score_deltasfrom .identity import change_finding_id, finding_key, severity_rankfrom .matcher import FindingMatcher, MatchedFinding, MatchResultfrom .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) * 1000return deltadiff --git a/packages/server/src/repowise/server/mcp_server/_budget/contracts.py b/packages/server/src/repowise/server/mcp_server/_budget/contracts.pyindex 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.pyindex 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 annotationsfrom 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, ChangeHealthDeltafrom 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) -> dictblock.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) -> dictreturn 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.jsonindex 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": nulldiff --git a/tests/unit/change_health/test_file_scores.py b/tests/unit/change_health/test_file_scores.pynew file mode 100644index 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.pyindex 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",