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
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.mdindex 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 blocksdiff --git a/packages/core/src/repowise/core/analysis/change_health/file_scores.py b/packages/core/src/repowise/core/analysis/change_health/file_scores.pyindex 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 Anyfrom ..health import HealthFileMetricDatafrom ..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.pyindex 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.pyindex 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 annotationsfrom dataclasses import dataclassfrom typing import Any+from repowise.core.analysis.finding_registry import split_heldfrom repowise.core.analysis.health.aggregation import module_rollups as _module_rollupsfrom repowise.core.analysis.health.trends import file_trendfrom 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.pyindex 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, healthassert 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"]