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(health): say what held-back findings deduct in get_health, and describe the change-risk score basis (#4776)

Raghav Chamadiya3e48bc0a64bb
diff --git a/docs/reference/MCP_RESPONSE_FIELDS.md b/docs/reference/MCP_RESPONSE_FIELDS.md
index 8f7d01be6..8433127e7 100644
--- a/docs/reference/MCP_RESPONSE_FIELDS.md
+++ b/docs/reference/MCP_RESPONSE_FIELDS.md
@@ -445,7 +445,7 @@ Both revisions are analysed from their own content; a head finding is reported o
| `introduced`, `worsened`, `resolved` | Totals |
| `top_findings`, `findings_total` | Three most actionable, and the count |
| `files`, `files_total` | Up to 10 files, largest structure move first |
-| `score_basis`, `score_change` | `structure_only`; nloc-weighted score change |
+| `score_basis`, `score_change` | `structure_only` (code shape of the changed bytes, no coverage); nloc-weighted score change |
Skips:
@@ -458,7 +458,7 @@ Findings name `dimension`, `biomarker`, `severity`, `path`, `symbol`, head-side
- Identity ignores line numbers, so moved code introduces nothing. Ids are bound to the two revisions; pass one as `finding_id` to expand it.
- A match to a stored finding carries `health_reference` for `get_health(finding_id=...)`. Performance findings carry `opportunity_id`, ordered by opportunity rank.
-Files rows: `base_score`, `head_score`, `nloc_base`, `nloc_head` (null on a missing side); `base_structure`/`head_structure` with diagnostics. Each score is 10 minus the structure deduction, as `get_health(counts="code_shape")`, from passes reading no history or coverage. A deleted file has a base-only row, with `moved_to` when split.
+Files rows: `base_score`, `head_score`, `nloc_base`, `nloc_head` (null on a missing side); `base_structure`/`head_structure` with diagnostics. Each score is 10 minus the structure deduction of the changed files' bytes, from passes reading no history or coverage. It can differ from `get_health(counts="code_shape")`, whose structure half also counts coverage markers and clones with unchanged files. A deleted file has a base-only row, with `moved_to` when split.
`score_change` (base-nloc weighted, so a growing improved file keeps its gain): `base`, `head`, `delta` (two decimals), `structure_delta` (moves even at the 1.0 floor), `files_compared`.
@@ -632,6 +632,7 @@ One ranked queue across refactoring, performance and code-shape work, the same o
- Nothing is gated. Health is ungated on Java, C#, C and preview on C++; refactoring, performance and dead code are preview on Java, C#, C, C++ (dead code also Kotlin, Swift).
- **Vendored and generated files:** findings held back in every language (changed upstream or by a generator), counted in `_meta.gated.health` under `vendored` and `generated`; `_meta.gated.reasons` explains once when nothing is listed. Scores, KPIs and worst-file order still count them.
- **History markers** (ownership, churn, change entropy, co-change, other git kinds): on tests, held back under `test_history` (code-shape findings still list); elsewhere, held from finding lists under `history`, though they order hotspots and Fix first and `get_risk` lists them.
+- **`findings_hidden`** (targeted mode): one line beside `findings` when a file or row hold kept findings off it, with their count by hold and the points they still deduct. Absent when nothing is held.
### Opt-in blocks
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
index 79d31d9a6..abebb10ba 100644
--- a/packages/core/src/repowise/core/analysis/change_health/file_scores.py
+++ b/packages/core/src/repowise/core/analysis/change_health/file_scores.py
@@ -1,8 +1,9 @@
"""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.
+so each score is ``10 - structure`` over those bytes: comparable side to side.
+It is not the index's ``counts="code_shape"`` score, whose structure half also
+holds coverage markers and clones with files outside the change.
"""
from __future__ import annotations
@@ -14,6 +15,7 @@ from typing import Any
from ..health import HealthFileMetricData
from ..health.counts import code_shape_score
+#: Name kept for compatibility: code shape of the changed bytes, no coverage.
SCORE_BASIS = "structure_only"
diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/findings.py b/packages/server/src/repowise/server/mcp_server/tool_health/findings.py
index 3af47c8ee..5897b261a 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_health/findings.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_health/findings.py
@@ -65,6 +65,9 @@ class FindingSets:
#: Set when the call prints no finding: ``emitted`` is then unranked and
#: this is the set :meth:`head` measures shapes over, on demand.
unranked_over: list[Any] | None = None
+ #: Targeted mode: rows a file or row hold kept off the list, which the
+ #: score still counts (history markers on a production file, for one).
+ held_rows: list[Any] = field(default_factory=list)
def head(self) -> Any | None:
"""The first ranked finding, ranking now if the call skipped it."""
@@ -151,10 +154,10 @@ async def load_targeted_findings(
),
"file_path",
))
- emitted, labels = _tiered(
- [f for f in _listed(finding_rows, pop, req) if _in_dimensions(f, req.ranked_dimensions)],
- finding_rows,
- )
+ dimensioned = [f for f in finding_rows if _in_dimensions(f, req.ranked_dimensions)]
+ listed = _listed(dimensioned, pop, req)
+ listed_ids = {f.id for f in listed}
+ emitted, labels = _tiered(listed, finding_rows)
return FindingSets(
finding_rows=emitted,
lead_rows=finding_rows,
@@ -162,6 +165,7 @@ async def load_targeted_findings(
emitted=emitted,
findings_total=len(emitted),
lower_priority=labels,
+ held_rows=[f for f in dimensioned if f.id not in listed_ids],
)
diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/targeted.py b/packages/server/src/repowise/server/mcp_server/tool_health/targeted.py
index 543d7f630..752b6eddf 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_health/targeted.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_health/targeted.py
@@ -5,6 +5,7 @@ from __future__ import annotations
from dataclasses import dataclass
from typing import Any
+from repowise.core.analysis.finding_registry import split_held
from repowise.core.analysis.health.aggregation import module_rollups as _module_rollups
from repowise.core.analysis.health.trends import file_trend
from repowise.server.mcp_server.tool_health.loading import HealthData, history_of
@@ -52,6 +53,7 @@ def build_targeted(
"findings",
),
"findings_total": findings_total,
+ **_findings_hidden(data),
# Which reading the scores are on; last, so identity keys lead.
"scope": pop.reported_scope,
"counts": pop.reported_counts,
@@ -81,6 +83,24 @@ def build_targeted(
)
+def _findings_hidden(data: HealthData) -> dict[str, str]:
+ """One line beside ``findings`` naming what the holds kept off it and the
+ points those rows still deduct, so the list is never read as the whole
+ deduction. Absent when nothing was held."""
+ held = data.findings.held_rows
+ if not held:
+ return {}
+ _, by_hold = split_held("health", held, data.pop.files, kind="biomarker_type")
+ kinds = ", ".join(f"{key} {n}" for key, n in sorted(by_hold.items()))
+ points = sum(float(f.health_impact or 0.0) for f in held)
+ return {
+ "findings_hidden": (
+ f"{len(held)} held-back findings ({kinds}) carry {points:.2f} points of total_deduction "
+ 'not listed here; include=["unverified"] lists them.'
+ )
+ }
+
+
def _metric_payload(data: HealthData) -> list[dict[str, Any]]:
rows = []
for m in data.metric_rows:
diff --git a/tests/unit/server/mcp/test_history_hold.py b/tests/unit/server/mcp/test_history_hold.py
index 67f2e8766..115e14cf5 100644
--- a/tests/unit/server/mcp/test_history_hold.py
+++ b/tests/unit/server/mcp/test_history_hold.py
@@ -192,3 +192,51 @@ async def test_get_health_history_count_costs_one_int(setup_mcp, session, health
assert not targeted.get("findings")
assert targeted["_meta"]["gated"]["health"] == {"history": 1}
assert targeted["_meta"]["gated"]["reasons"] == {"history": FILE_HOLDS["history"]}
+
+
+async def test_targeted_findings_say_what_the_holds_deduct(setup_mcp, session, health_data):
+ from repowise.server.mcp_server import get_health
+
+ await _seed(session, health_data)
+ result = await get_health(targets=[_APP], only=["findings"])
+ assert [f["biomarker_type"] for f in result["findings"]] == ["complex_method"]
+ # The two history markers deduct 1.5 + 1.0 points the list does not show.
+ assert result["findings_hidden"] == (
+ '2 held-back findings (history 2) carry 2.50 points of total_deduction not listed here; '
+ 'include=["unverified"] lists them.'
+ )
+
+ opted = await get_health(targets=[_APP], include=["unverified"])
+ assert "findings_hidden" not in opted
+ assert len(opted["findings"]) == 3
+
+
+async def test_targeted_findings_unchanged_when_nothing_is_held(setup_mcp, session, health_data):
+ from repowise.core.persistence.crud import upsert_health_findings
+ from repowise.server.mcp_server import get_health
+
+ await _seed(session, health_data)
+ await upsert_health_findings(
+ session,
+ health_data,
+ [
+ {
+ "file_path": _APP,
+ "biomarker_type": "complex_method",
+ "severity": "high",
+ "function_name": "run",
+ "line_start": 1,
+ "line_end": 90,
+ "details": {},
+ "health_impact": 2.0,
+ "reason": "complex_method only",
+ }
+ ],
+ file_paths=[_APP],
+ )
+ await session.commit()
+ result = await get_health(targets=[_APP])
+ assert "findings_hidden" not in result
+ assert "gated" not in result["_meta"]