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(mcp): get_health metric rows carry structure_deduction and history_deduction (#4108)
Raghav Chamadiyaf00c84fecdc9
diff --git a/docs/reference/MCP_RESPONSE_FIELDS.md b/docs/reference/MCP_RESPONSE_FIELDS.mdindex 3805e5a0e..b5d54ff79 100644--- a/docs/reference/MCP_RESPONSE_FIELDS.md+++ b/docs/reference/MCP_RESPONSE_FIELDS.md@@ -101,7 +101,7 @@ The key is absent when every argument was understood. One entry per argument.| `search_codebase` | `kind`, `mode` (an unknown `mode` runs as `auto`), `pattern` when `query` is also given (entry carries `"superseded_by": "query"`) | Top-level list || `get_risk`, `get_change_risk`, `get_overview` | `include` | Top-level list || `get_answer` | `include` | `_meta.ignored_arguments`, a map: `{"include": [...]}` |-| `get_health` | `refactoring_*` and `performance_*` filters, `scope`, `counts` | Top-level flat map of argument to dropped value, e.g. `{"counts": "code-shape"}` |+| `get_health` | `refactoring_*` and `performance_*` filters, `scope`, `counts` | Top-level flat map of argument to dropped value, e.g. `{"counts": "code-shape"}`. A value that belongs to the other control (`scope="code_shape"`) also gets `ignored_arguments_hint` naming the right one (not on a detail lookup, where neither control applies) |`get_health` reports a misspelled `only` key under `unknown_only_keys`. A detail lookup (`finding_id`, `plan_id`, `opportunity_id`) also lists `scope` and `counts` there, since a population control has nothing to act on for one stored row.@@ -377,7 +377,7 @@ Items are ordered by value first, then tier. History markers (churn, ownership,| `worst_files`, `test_worst_files` | Lowest raw scores, production and test || `high_leverage_files` | Ranked by `weighted_deficit`, with `share_of_repo_gap_pct` || `top_findings` / `findings`, `test_findings` | Production and test findings; their totals sum to the whole open set |-| metric row | `score` (defect dimension and headline), `maintainability_score`, `performance_score`, `weighted_deficit` = (8 - score) x NLOC, `is_test`, `has_test_file`, `primary_biomarker`, `total_deduction`, and `withheld_deduction` when part of it comes from a withheld finding type |+| metric row | `score` (defect dimension and headline), `maintainability_score`, `performance_score`, `weighted_deficit` = (8 - score) x NLOC, `is_test`, `has_test_file`, `primary_biomarker`, `total_deduction`, `structure_deduction` and `history_deduction` (the score is 10 minus both, before the 1.0 floor; history reads 0.0 under `counts="code_shape"`), and `withheld_deduction` when part of it comes from a withheld finding type |`weighted_deficit` and the gap fields share one unit, score points x NLOC; they compare only with each other. Non-code files score a mechanical 10.0 because no marker reads them; `average_health_code_only` shows the headline without them. `primary_biomarker` prefers a discrete finding over the continuous `coverage_gradient`. Each finding carries a `dimension`; `advisory` findings (`assertion_free_test`, `mock_saturated_test`) never deduct and appear only with `include=["advisory"]`.diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/projection.py b/packages/server/src/repowise/server/mcp_server/tool_health/projection.pyindex abf1c9206..9e227b518 100644--- a/packages/server/src/repowise/server/mcp_server/tool_health/projection.py+++ b/packages/server/src/repowise/server/mcp_server/tool_health/projection.py@@ -4,8 +4,8 @@ from __future__ import annotationsfrom typing import Any-from repowise.core.analysis.health.counts import DEFAULT_COUNTS-from repowise.core.analysis.health.scope import DEFAULT_SCOPE+from repowise.core.analysis.health.counts import COUNTS, DEFAULT_COUNTS+from repowise.core.analysis.health.scope import DEFAULT_SCOPE, SCOPESfrom repowise.server.mcp_server.tool_health.paging import _stamp_collectionfrom repowise.server.mcp_server.tool_health.request import HealthRequest@@ -28,6 +28,7 @@ _ALWAYS_KEPT = frozenset("unknown_include_keys_emitted",# A rejected filter value is a caller-error report too."ignored_arguments",+ "ignored_arguments_hint","recovery",})@@ -39,6 +40,9 @@ _UNKNOWN_ONLY_HINT = ("performance is an `include` value. See docs/agent/MCP_TOOLS.md.")+#: Which control accepts each value, to name the right one for a swapped value.+_CONTROL_OF_VALUE = {**dict.fromkeys(COUNTS, "counts"), **dict.fromkeys(SCOPES, "scope")}+_PLAN_COMPANIONS = frozenset({"refactoring_plans_status", "refactoring_plans_opportunities_total"})@@ -60,6 +64,13 @@ def _name_rejected_controls(}if rejected:result["ignored_arguments"] = {**result.get("ignored_arguments", {}), **rejected}+ swapped = [+ f'{name}="{raw}" is a {other} value: did you mean {other}="{raw}"?'+ for name, raw in rejected.items()+ if (other := _CONTROL_OF_VALUE.get(raw)) and other != name+ ]+ if swapped:+ result["ignored_arguments_hint"] = " ".join(swapped)def _name_uncounted_blocks(result: dict[str, Any], reported_counts: str) -> None:diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/serialize.py b/packages/server/src/repowise/server/mcp_server/tool_health/serialize.pyindex dae04211f..ea332ab8e 100644--- a/packages/server/src/repowise/server/mcp_server/tool_health/serialize.py+++ b/packages/server/src/repowise/server/mcp_server/tool_health/serialize.py@@ -185,6 +185,9 @@ def _serialize_metric(# ``defect_score`` is deliberately absent: it always equals ``score``."maintainability_score": _round_opt(getattr(m, "maintainability_score", None)),"performance_score": _round_opt(getattr(m, "performance_score", None)),+ # The score's two halves (``10 - structure - history``, before the floor).+ "structure_deduction": _round_opt(getattr(m, "structure_deduction", None)),+ "history_deduction": _round_opt(getattr(m, "history_deduction", None)),# Dominant cause and pre-clamp magnitude; null when the file has no findings."primary_biomarker": lead.get("primary_biomarker") if lead else None,"primary_reason": lead.get("primary_reason") if lead else None,diff --git a/tests/unit/server/mcp/test_health.py b/tests/unit/server/mcp/test_health.pyindex b9e9d31f3..48e6972d7 100644--- a/tests/unit/server/mcp/test_health.py+++ b/tests/unit/server/mcp/test_health.py@@ -2288,6 +2288,53 @@ async def test_a_misspelled_control_is_named_rather_than_silently_defaulted(assert result["ignored_arguments"] == {"counts": "code-shape", "scope": "prod"}+async def test_a_value_passed_to_the_other_control_names_the_right_one(+ setup_mcp, session, populated_db+):+ from repowise.server.mcp_server import get_health++ result = await get_health(+ targets=["src/auth/service.py"], scope="code_shape", only=["metrics"]+ )+ assert result["ignored_arguments"] == {"scope": "code_shape"}+ assert 'counts="code_shape"' in result["ignored_arguments_hint"]+ reverse = await get_health(counts="production")+ assert 'scope="production"' in reverse["ignored_arguments_hint"]+ plain = await get_health(counts="code-shape")+ assert "ignored_arguments_hint" not in plain+++async def test_metric_rows_carry_the_structure_and_history_split(+ setup_mcp, session, populated_db+):+ """The two halves the score is ``10 - structure - history`` of, per file."""+ from repowise.core.persistence.crud import save_health_metrics+ from repowise.server.mcp_server import get_health++ await save_health_metrics(+ session,+ populated_db,+ [+ {+ "file_path": "src/auth/service.py",+ "score": 3.0,+ "nloc": 100,+ "is_test": False,+ "structure_deduction": 1.0,+ "history_deduction": 6.0,+ }+ ],+ )+ row = (await get_health(targets=["src/auth/service.py"]))["metrics"][0]+ assert (row["structure_deduction"], row["history_deduction"]) == (1.0, 6.0)+ worst = (await get_health(only=["worst_files"]))["worst_files"][0]+ assert (worst["structure_deduction"], worst["history_deduction"]) == (1.0, 6.0)+ shaped = (await get_health(targets=["src/auth/service.py"], counts="code_shape"))["metrics"]+ assert (shaped[0]["structure_deduction"], shaped[0]["history_deduction"]) == (1.0, 0.0)++@pytest.mark.asyncioasync def test_a_valid_control_is_not_reported_as_ignored(setup_mcp, session, populated_db):from repowise.server.mcp_server import get_health