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): stop `only` dropping the totals, and bucket test files out of the headline findings (#1361)

Raghav Chamadiyafc44a3b5aaae
diff --git a/docs/agent/MCP_TOOLS.md b/docs/agent/MCP_TOOLS.md
index ba6e55245..a8d2615c3 100644
--- a/docs/agent/MCP_TOOLS.md
+++ b/docs/agent/MCP_TOOLS.md
@@ -507,9 +507,9 @@ code-health merge-gate judges it on.
|-----------|------|----------|-------------|
| `targets` | list[string] | No | File paths, or `module:foo` to expand a module's file set. Empty means dashboard mode. |
| `include` | list[string] | No | Opt-in blocks (default response stays lean): `"biomarkers"` (findings in dashboard mode), `"refactoring"` (structured, graph-aware refactoring plans; see below), `"trend"` (snapshot diff + declining / predicted-decline alerts), `"coverage"`, `"accuracy"` (the "does the score find the bugs?" stat, dashboard mode), `"signals"` (per-file process / people / topology signals, targeted mode), `"churn_complexity"` (churn x complexity quadrant points, dashboard mode), and a dimension name (`"performance"` / `"defect"` / `"maintainability"`) to filter findings to that pillar. |
-| `only` | list[string] | No | Keep just these top-level keys. `include` adds blocks, `only` subtracts them. `mode` and `_meta` always survive. |
+| `only` | list[string] | No | Keep just these top-level keys. `include` adds blocks, `only` subtracts them. `mode`, `_meta` and each kept list's `*_total` sibling always survive. The `include` block names work as aliases: `biomarkers`→`findings`, `accuracy`→`defect_accuracy`, `refactoring`→`refactoring_plans`. `signals` has no top-level key (it merges into `metrics[].signals`), so it is reported in `unknown_only_keys` — in targeted mode, where `signals` applies, name `metrics` instead. |
| `repo` | string | No | *(workspace only)* Target repo alias |
-| `limit` | int | No | Max rows in **every** ranked list (default 20, capped at 50) |
+| `limit` | int | No | Max rows in **every** ranked list (default 20, capped at 50). `0` means no rows; the `*_total` siblings still report the true counts. |
**Returns:** Dashboard mode (no `targets`) returns a `directive`, repo-level KPIs
(hotspot health, average health, worst performer, maintainability / performance
@@ -530,8 +530,21 @@ named in `unresolved` with a reason (`not_indexed` → run `repowise update`,
`known_modules`), so an empty `findings` list means healthy and nothing else. A
target set that resolves to nothing still answers in targeted mode rather than
falling back to the repo dashboard. Every capped list carries a `*_total`
-sibling, and `_meta.health_analyzed_at` dates the health pass, which is separate
-from indexing and can lag it.
+sibling — including under `only`, which retains it automatically — and
+`_meta.health_analyzed_at` dates the health pass, which is separate from
+indexing and can lag it.
+
+**Test material is bucketed, not hidden.** Every metric row carries `is_test`
+(distinct from `has_test_file`: "is this file a test" vs "is this file tested").
+In dashboard mode the ranked finding lists are split — `top_findings` /
+`findings` carry production findings, `test_findings` carries the test half, and
+`top_findings_total + test_findings_total` is the whole open set. Defect risk in
+a test asks a different question from defect risk in the code it covers, and at
+the default limit a quarter of the headline list was describing the test suite.
+Targeted mode is never split: you named the files, so you get their findings.
+KPIs, `worst_files` and `high_leverage_files` deliberately still include test
+files — excluding them would move the repo's headline score, which is a scoring
+change, not a display one.
**Leverage, not just lowness.** `average_health` is NLOC-weighted (the number the
badge and dashboard surface), so a few large low-scoring files hold it down. To
@@ -577,7 +590,13 @@ The opt-in enrichments:
`include=["biomarkers", "performance"]`.
- **`refactoring`** also emits `suggestion_legend`: `biomarker_type` → the prose
suggestion for that type, once per response rather than per finding. Join on
- `biomarker_type`.
+ `biomarker_type`. It is keyed off the ranked finding head and does not vary
+ with `only`, so it can carry an entry for a block a projection dropped —
+ extra rows in a lookup table, never a missing one. Note it explains the
+ **findings**, not the
+ plans it ships beside — the two sets differ (no plan kind is sourced from
+ `coverage_gradient`), and `directive.plan_addresses_reason` is what reports
+ that gap.
**When to use:** Before opening a PR, to self-check the files you changed
(`targets=[...], include=["signals"]`) and confirm you are not regressing the
@@ -594,7 +613,9 @@ get_health(include=["accuracy", "churn_complexity"])
get_health(include=["biomarkers", "performance"]) # only performance findings
get_health(targets=["src/api/server.py"], include=["signals"])
get_health(targets=["module:src.api"], include=["trend", "refactoring"])
-get_health(include=["accuracy"], only=["defect_accuracy"]) # the block, without the dashboard again
+get_health(include=["accuracy"], only=["accuracy"]) # the block, without the dashboard again
+get_health(only=["top_findings"]) # + top_findings_total, automatically
+get_health(only=["kpis"], limit=0) # headline numbers, no rows at all
```
---
diff --git a/packages/core/src/repowise/core/persistence/crud/graph.py b/packages/core/src/repowise/core/persistence/crud/graph.py
index d1e31be88..c82298c26 100644
--- a/packages/core/src/repowise/core/persistence/crud/graph.py
+++ b/packages/core/src/repowise/core/persistence/crud/graph.py
@@ -533,6 +533,42 @@ async def get_graph_nodes_by_ids(
return out
+async def get_test_file_paths(
+ session: AsyncSession,
+ repository_id: str,
+) -> set[str]:
+ """Relative paths of every file the ingester classified as test material.
+
+ Reads the flag ingestion already decided per file (#1103 made ``is_test``
+ the single canonical answer to "is this a test"). For a file node
+ ``node_id`` *is* the repo-relative path, so the result joins straight onto
+ ``HealthFileMetric.file_path`` / ``HealthFinding.file_path`` with no
+ denormalized column and no migration.
+
+ ``node_type == "file"`` is required, not incidental: symbol nodes carry
+ ``is_test`` too and their ``node_id`` is a ``"<path>::<name>"`` composite,
+ which would never match a file path but would inflate the read.
+
+ Narrow in columns, not in rows — no index covers ``node_type`` or
+ ``is_test``, so this scans the repo's nodes (~55 ms on a 35k-node index).
+ A caller serializing no file row and no finding should skip it.
+
+ Degrades to "nothing is test material" when the graph is missing or lags
+ the health pass. That is the safe direction: a caller sees the unsplit
+ world it saw before, never a production file mislabelled as a test.
+ Censused on this repo's index — 1,030 test file nodes, none of them absent
+ from ``health_file_metrics``.
+ """
+ result = await session.execute(
+ select(GraphNode.node_id).where(
+ GraphNode.repository_id == repository_id,
+ GraphNode.node_type == "file",
+ GraphNode.is_test.is_(True),
+ )
+ )
+ return {row[0] for row in result.all()}
+
+
async def get_community_members(
session: AsyncSession,
repository_id: str,
diff --git a/packages/server/src/repowise/server/mcp_server/tool_health.py b/packages/server/src/repowise/server/mcp_server/tool_health.py
index 87f695ecc..2bc46e2a8 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_health.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_health.py
@@ -25,6 +25,7 @@ from repowise.core.persistence.crud import (
get_git_metadata_bulk,
get_node_degree_counts_bulk,
get_refactoring_suggestions,
+ get_test_file_paths,
list_health_snapshots,
load_coverage_for_repo,
sort_metrics_worst_first,
@@ -100,6 +101,24 @@ def _serialize_refactoring(r: Any) -> dict[str, Any]:
}
+# ``include`` and ``only`` were different vocabularies: the block a caller
+# switches on with ``include=["biomarkers"]`` lands under the key ``findings``,
+# so the obvious ``only=["biomarkers"]`` projected it away again. Alias the three
+# that have a 1:1 key rather than make the caller learn two names for one block.
+# ``signals`` is deliberately absent — it has no top-level key to alias to, it
+# merges into ``metrics[].signals``, so it stays reported in ``unknown_only_keys``.
+_ONLY_ALIASES = {
+ "biomarkers": "findings",
+ "accuracy": "defect_accuracy",
+ "refactoring": "refactoring_plans",
+}
+
+# Files the directive reduces over: ``fix_first`` plus the two in ``then``. Named
+# because three separate places have to agree on it — the plan lookup, the lead
+# set the directive reads, and the directive itself — and they are far apart.
+_DIRECTIVE_CANDIDATES = 3
+
+
def _in_dimensions(row: Any, dimensions: set[str]) -> bool:
"""True when *row* belongs to one of *dimensions* (empty set -> everything).
@@ -138,13 +157,24 @@ def _leads_by_file(findings: list[Any]) -> dict[str, dict[str, Any]]:
return leads
-def _serialize_metric(m: HealthFileMetric, lead: dict[str, Any] | None = None) -> dict[str, Any]:
+def _serialize_metric(
+ m: HealthFileMetric,
+ lead: dict[str, Any] | None = None,
+ *,
+ is_test: bool = False,
+) -> dict[str, Any]:
return {
"file_path": m.file_path,
"score": round(m.score, 2),
"max_ccn": m.max_ccn,
"max_nesting": m.max_nesting,
"nloc": m.nloc,
+ # Two different questions, deliberately both present: ``has_test_file``
+ # is "does something test this file", ``is_test`` is "is this file
+ # itself test material". Defect risk in a test reads differently from
+ # defect risk in the code it covers, and nothing in the payload used to
+ # say which one you were looking at.
+ "is_test": is_test,
"has_test_file": m.has_test_file,
"line_coverage_pct": m.line_coverage_pct,
"branch_coverage_pct": m.branch_coverage_pct,
@@ -170,21 +200,32 @@ def _serialize_metric(m: HealthFileMetric, lead: dict[str, Any] | None = None) -
}
-def _serialize_coverage_row(row: Any) -> dict[str, Any]:
- try:
- covered = json.loads(row.covered_lines_json) if row.covered_lines_json else []
- except Exception:
- covered = []
- return {
+def _serialize_coverage_row(row: Any, *, covered_lines: bool = True) -> dict[str, Any]:
+ """One coverage row. ``covered_lines=False`` omits the per-line array.
+
+ The narrow form is not the wide form minus a key: a row read with
+ ``include_covered_lines=False`` carries no ``covered_lines_json`` at all, so
+ touching it would raise rather than merely waste the parse.
+ """
+ out: dict[str, Any] = {
"file_path": row.file_path,
"source_format": row.source_format,
"line_coverage_pct": row.line_coverage_pct,
"branch_coverage_pct": row.branch_coverage_pct,
- "covered_lines": covered,
- "total_coverable_lines": row.total_coverable_lines,
- "ingested_at": row.ingested_at.isoformat() if row.ingested_at else None,
- "ingested_commit_sha": row.ingested_commit_sha,
}
+ # Inserted here rather than appended, so the wide form stays byte-identical
+ # to what callers already receive.
+ if covered_lines:
+ try:
+ out["covered_lines"] = (
+ json.loads(row.covered_lines_json) if row.covered_lines_json else []
+ )
+ except Exception:
+ out["covered_lines"] = []
+ out["total_coverable_lines"] = row.total_coverable_lines
+ out["ingested_at"] = row.ingested_at.isoformat() if row.ingested_at else None
+ out["ingested_commit_sha"] = row.ingested_commit_sha
+ return out
def _module_rollups(metrics: list[HealthFileMetric]) -> list[dict[str, Any]]:
@@ -477,31 +518,37 @@ async def get_health(
``weighted_deficit``, not ``score``: the score floors at 1.0 and cannot
separate the worst band.
- Three co-equal dimensions per file: ``score`` (defect risk, the headline),
- ``maintainability_score``, and ``performance_score`` (static I/O-in-loop /
- N+1 risk, never blended into the defect headline). Each finding carries its
- ``dimension``.
+ Three dimensions per file: ``score`` (defect risk, the headline),
+ ``maintainability_score``, ``performance_score`` (static I/O-in-loop / N+1
+ risk, never blended in). Each finding carries its ``dimension``. Dashboard
+ mode buckets test material: ``top_findings`` is production,
+ ``test_findings`` the rest, each row says ``is_test``.
Args:
- targets: file paths or ``module:<name>``. Empty → dashboard mode. Any
+ targets: file paths or ``module:<name>``. Empty → dashboard mode. A
target matching nothing is named in ``unresolved`` with a reason
(``not_indexed`` → run ``repowise update`` | ``no_such_path`` |
- ``excluded`` | ``no_such_module``), so an empty ``findings`` means
- healthy and nothing else.
- include: opt-in blocks: ``biomarkers`` | ``refactoring`` | ``trend`` |
- ``coverage`` | ``accuracy`` | ``signals`` | ``churn_complexity`` |
- ``performance``/``defect``/``maintainability`` (filter findings to
- one dimension).
- only: keep just these top-level keys. ``include`` adds blocks, ``only``
- subtracts them — pass ``["directive"]`` for the cheapest useful call.
+ ``excluded`` | ``no_such_module``), so empty ``findings`` means
+ healthy.
+ include: ``biomarkers`` | ``refactoring`` | ``trend`` | ``coverage`` |
+ ``accuracy`` | ``signals`` | ``churn_complexity`` |
+ ``performance``/``defect``/``maintainability`` (dimension).
+ only: keep just these top-level keys — ``["directive"]`` is the cheapest
+ useful call. Each kept list's ``*_total`` is retained too, and the
+ ``include`` names work as aliases. Unmatched keys land in
+ ``unknown_only_keys``.
repo: usually omitted.
- limit: max rows in every ranked list (capped at 50); each carries a
- ``*_total`` sibling so truncation is never silent.
+ limit: max rows per ranked list (max 50, ``0`` for none); each carries
+ a ``*_total`` sibling so truncation is never silent.
"""
started = perf_counter()
- limit = min(max(limit, 1), 50)
+ # ``0`` means none, matching the ``module_limit`` convention on the REST
+ # coverage route. It used to clamp up to 1, so the documented way to ask for
+ # "the totals, none of the rows" silently returned a row.
+ limit = min(max(limit, 0), 50)
include_set = set(include or [])
- only_set = set(only or [])
+ only_list = [_ONLY_ALIASES.get(k, k) for k in (only or [])]
+ only_set = set(only_list)
def wants(block: str) -> bool:
"""True when ``block`` survives the ``only`` projection.
@@ -523,6 +570,26 @@ async def get_health(
# The serialized-rows read is the expensive optional one; skip it when no
# block that carries findings survives the projection.
wants_findings = wants("findings") or wants("top_findings")
+ wants_test_findings = wants("test_findings")
+ # Everything downstream of the test/production split, in one place.
+ #
+ # Keep this list exhaustive. The read it gates is not free (the column list
+ # is narrow but the predicate is not indexed, so it scans this repo's graph
+ # nodes — ~55 ms warm on a 35k-node index), and ``only=["directive"]`` /
+ # ``["kpis"]`` / ``["modules"]`` serialize no metric row and no finding.
+ # But a *missing* entry here is worse than the read: it makes the split
+ # collapse for that projection, which is the same "a projection changed
+ # what a surviving key holds" defect this change exists to close. Adding
+ # ``suggestion_legend`` was not optional — the legend derives from the split
+ # heads, and leaving it out silently reverted that fix.
+ needs_test_paths = (
+ wants_findings
+ or wants_test_findings
+ or wants("worst_files")
+ or wants("high_leverage_files")
+ or wants("metrics")
+ or ("refactoring" in include_set and wants("suggestion_legend"))
+ )
# Split ``module:foo`` targets out of the path list. A target that
# matches one or more modules is expanded into the set of files
@@ -544,6 +611,11 @@ async def get_health(
HealthFileMetric.repository_id == repository.id
)
exclude_spec = _get_exclude_spec(ctx.path)
+ # Test material, from the flag ingestion already decided per file.
+ # Gated on ``needs_test_paths`` — see the note at its definition.
+ test_paths: set[str] = set()
+ if needs_test_paths:
+ test_paths = await get_test_file_paths(session, repository.id)
indexed_rows = list((await session.execute(all_metrics_q)).scalars().all())
all_metrics = filter_rows_by_attr(indexed_rows, "file_path", exclude_spec)
# Paths the index knows about but the exclude config drops. Kept so an
@@ -585,6 +657,13 @@ async def get_health(
# ORM object to emit ``limit`` of them measured 262ms on this repo, and
# that cost is linear in finding count, so it grows with the repo the
# dashboard is describing.
+ #
+ # ``test_finding_rows`` is the dashboard-only test bucket (see the split
+ # below). Targeted mode never fills it: the caller named the files, so
+ # partitioning what they explicitly asked about would be answering a
+ # different question than the one they asked.
+ test_finding_rows: list[Any] = []
+ test_findings_total = 0
if scoped:
finding_rows = filter_rows_by_attr(
list(
@@ -605,6 +684,7 @@ async def get_health(
lead_rows: list[Any] = finding_rows
emitted = [f for f in finding_rows if _in_dimensions(f, dimension_filter)]
finding_rows = emitted[:limit]
+ legend_rows: list[Any] = finding_rows
else:
# Narrow read over every open finding: the four attributes
# ``_leads_by_file`` reads, plus ``dimension`` for the perf headline
@@ -632,32 +712,66 @@ async def get_health(
# because the caller asked to *see* one dimension.
lead_rows = filter_rows_by_attr(lite_rows, "file_path", exclude_spec)
emitted = [r for r in lead_rows if _in_dimensions(r, dimension_filter)]
+ # Test material goes in its own bucket rather than competing for
+ # the repo's headline finding list. Measured on this repo, **2 of
+ # the top 5** open findings by impact sit on test files, and 4-5 of
+ # the top 20 — the top-20 figure is tie-dependent (ranks 14+ are all
+ # at impact 2.16), which is itself the point: a fifth of the
+ # most-read list was the test suite, decided partly by tie-break.
+ # Splitting keeps both readable. A thrashing test suite is a real
+ # signal some teams want; it is just not the same question as
+ # "where is the defect risk in this codebase".
+ #
+ # Split *before* the cap, so each list is the top ``limit`` of its
+ # own population — capping first and partitioning after would give
+ # the smaller bucket whatever happened to land in the head.
+ prod_emitted = [r for r in emitted if r.file_path not in test_paths]
+ test_emitted = [r for r in emitted if r.file_path in test_paths]
+ # Both heads, in one list, decided here rather than downstream: the
+ # legend has to be a pure function of the ranked set so no
+ # projection can change what a surviving key contains.
+ legend_rows: list[Any] = prod_emitted[:limit] + test_emitted[:limit]
# Fetch the head by id rather than re-running the ranked query with
# an over-fetch margin. The margin had to cover every exclusion in
# the table, so a repo excluding a large subtree turned the "capped"
# read back into a near-full one; by id it is exactly ``limit`` rows
# whatever the exclude config or dimension filter say.
- head_ids = [r.id for r in emitted[:limit]]
+ head_ids = [r.id for r in prod_emitted[:limit]]
+ test_head_ids = [r.id for r in test_emitted[:limit]] if wants_test_findings else []
finding_rows = []
- if head_ids and wants_findings:
+ if not wants_findings:
+ head_ids = []
+ # One read for both heads — the split is a partition of the same
+ # ranked set, so paying two round-trips for it would be the N+1 this
+ # tool flags in itself.
+ wanted_ids = head_ids + test_head_ids
+ if wanted_ids:
by_id = {
f.id: f
for f in (
await session.execute(
- select(HealthFinding).where(HealthFinding.id.in_(head_ids))
+ select(HealthFinding).where(HealthFinding.id.in_(wanted_ids))
)
)
.scalars()
.all()
}
- # Re-imposed from ``head_ids``; ``IN`` does not preserve order.
+ # Re-imposed from the id lists; ``IN`` does not preserve order.
finding_rows = [by_id[i] for i in head_ids if i in by_id]
+ test_finding_rows = [by_id[i] for i in test_head_ids if i in by_id]
+ test_findings_total = len(test_emitted)
# Counts the rows this response is about: the post-exclusion open set,
# narrowed to the requested dimensions when one was asked for. Reporting
# the unfiltered total beside a filtered list is what made an empty
# ``findings`` read as "nothing here" rather than "nothing shown".
- findings_total = len(emitted)
+ #
+ # In dashboard mode this counts the *production* half, because that is
+ # the list it sits beside; ``test_findings_total`` counts the other half
+ # and the two still sum to the whole open set. Same rule #1337 settled
+ # for the dimension filter: a total describes the list it is a sibling
+ # of, never a wider set the caller cannot see.
+ findings_total = len(emitted if scoped else prod_emitted)
# Worst-first order, placed here because ranking needs the summed
# deduction per file and ``lead_rows`` is the first point that carries
@@ -740,8 +854,17 @@ async def get_health(
coverage_rows = filter_rows_by_attr(
# ``effective_targets``, not ``targets`` — a raw ``module:foo``
# target is not a file path and matched nothing here.
+ #
+ # Only targeted mode serializes ``covered_lines``. The dashboard
+ # used to read every ``covered_lines_json`` blob, ``json.loads``
+ # each one, and then strip the field back out with a dict
+ # comprehension — 466,874 B of parse per call for a key it never
+ # emitted. Decline the column at the read instead.
await load_coverage_for_repo(
- session, repository.id, file_paths=list(effective_targets) if scoped else None
+ session,
+ repository.id,
+ file_paths=list(effective_targets) if scoped else None,
+ include_covered_lines=scoped,
),
"file_path",
exclude_spec,
@@ -812,6 +935,14 @@ async def get_health(
)
printed = {m.file_path for m in metric_rows[:limit]}
printed |= {m.file_path for m in by_leverage[:limit]}
+ # The directive's three candidates, unconditionally — it reads
+ # ``by_leverage[:3]`` and is not a ranked list, so its leads must not
+ # depend on ``limit``. Before ``limit=0`` existed this was covered by
+ # the clamp to 1 only by accident; at 0 the lead set came back empty
+ # and the directive degraded to a fallback ``reason`` ("scores 1.0")
+ # *and* asserted ``plan_addresses_reason: false`` on every file —
+ # a wrong claim rather than a missing one.
+ printed |= {m.file_path for m in by_leverage[:_DIRECTIVE_CANDIDATES]}
lead_source = [r for r in lead_rows if r.file_path in printed]
leads = _leads_by_file(lead_source)
@@ -833,7 +964,7 @@ async def get_health(
plan_biomarkers_by_path: dict[str, set[str]] = {}
plan_count_by_path: dict[str, int] = {}
if not scoped and wants("directive") and by_leverage:
- directive_paths = [m.file_path for m in by_leverage[:3]]
+ directive_paths = [m.file_path for m in by_leverage[:_DIRECTIVE_CANDIDATES]]
for path, source in (
await session.execute(
select(
@@ -855,6 +986,14 @@ async def get_health(
if source:
plan_biomarkers_by_path.setdefault(path, set()).add(source)
+ # KPIs deliberately keep test files in. Excluding them is not a display
+ # choice, it is a scoring change: measured across this workspace, dropping
+ # test material moves NLOC-weighted ``average_health`` 7.52 -> 6.87 here,
+ # 7.07 -> 6.27 on the backend repo and 7.59 -> 7.46 on the frontend. Test
+ # files score *better* than production code, so excluding them would make
+ # every repo's headline drop overnight with no defect having been found.
+ # The calibrated numbers stay where they are; the split above is about which
+ # findings compete for a ranked list, not about what the score means.
kpis = _compute_kpis(
metric_rows if scoped else all_metrics,
performance_findings=perf_findings_count,
@@ -864,7 +1003,7 @@ async def get_health(
if scoped:
metric_payload: list[dict[str, Any]] = []
for m in metric_rows:
- row = _serialize_metric(m, leads.get(m.file_path))
+ row = _serialize_metric(m, leads.get(m.file_path), is_test=m.file_path in test_paths)
if m.file_path in signals_by_path:
row["signals"] = signals_by_path[m.file_path]
metric_payload.append(row)
@@ -937,13 +1076,28 @@ async def get_health(
# long tail" reframe that turns a repo-wide number into a short list.
"gap_analysis": gap,
"worst_files": [
- _serialize_metric(m, leads.get(m.file_path)) for m in metric_rows[:limit]
+ _serialize_metric(m, leads.get(m.file_path), is_test=m.file_path in test_paths)
+ for m in metric_rows[:limit]
],
+ # Both ranked file lists deliberately keep test files in place, and
+ # both now say which rows are tests. Measured on this repo, 0 of the
+ # top 25 by the worst-first comparator are test material, so there
+ # is no crowding here to fix — and dropping them would quietly
+ # change which files the repo's "worst" are. The crowding is in the
+ # *finding* lists, which is where the split below happens.
+ "worst_files_total": len(metric_rows),
"high_leverage_files": [
- _serialize_metric(m, leads.get(m.file_path)) for m in by_leverage[:limit]
+ _serialize_metric(m, leads.get(m.file_path), is_test=m.file_path in test_paths)
+ for m in by_leverage[:limit]
],
+ "high_leverage_files_total": len(by_leverage),
"top_findings": [_serialize_finding(f) for f in finding_rows[:limit]],
"top_findings_total": findings_total,
+ # The test half of the same ranked set, in its own bucket so a
+ # thrashing test suite stays visible without competing with
+ # production defect risk for the most-read list.
+ "test_findings": [_serialize_finding(f) for f in test_finding_rows[:limit]],
+ "test_findings_total": test_findings_total,
# Worst-first, so the cap keeps the modules worth looking at. On a
# monorepo the tail is dozens of single-file buckets.
"modules": all_modules[:limit],
@@ -970,6 +1124,11 @@ async def get_health(
# worth reading.
result["findings"] = [_serialize_finding(f) for f in finding_rows[:limit]]
result["findings_total"] = findings_total
+ # Same production/test split as ``top_findings``: this block only ever
+ # fires in dashboard mode (targeted mode set ``findings`` above), so it
+ # is describing the repo, not a file the caller named.
+ result["test_findings"] = [_serialize_finding(f) for f in test_finding_rows[:limit]]
+ result["test_findings_total"] = test_findings_total
if "refactoring" in include_set:
# Structured refactoring plans (the concrete split groups / evidence /
@@ -1044,12 +1203,13 @@ async def get_health(
if "coverage" in include_set:
# Drop the bulky covered-lines arrays from dashboard mode; full
# detail is available in targeted mode.
- if targets:
+ if scoped:
coverage_payload = [_serialize_coverage_row(r) for r in coverage_rows]
else:
+ # Built narrow, not built wide and subtracted from. These rows came
+ # back without the column at all (see the read above).
coverage_payload = [
- {k: v for k, v in _serialize_coverage_row(r).items() if k != "covered_lines"}
- for r in coverage_rows[:limit]
+ _serialize_coverage_row(r, covered_lines=False) for r in coverage_rows[:limit]
]
# ``ingested_at`` is a datetime on the summary too — coerce.
if coverage_summary.get("ingested_at") is not None:
@@ -1070,12 +1230,24 @@ async def get_health(
# One entry per biomarker type actually present in the findings this
# response carries. Built last so the dimension filter above has already
# narrowed the rows the caller will join against.
- if "refactoring" in include_set:
- present_types = {
- row.get("biomarker_type")
- for field in ("findings", "top_findings")
- for row in result.get(field) or ()
- }
+ if "refactoring" in include_set and wants("suggestion_legend"):
+ # Built from the ranked rows themselves, not from the serialized blocks
+ # in ``result``. It used to read ``result["findings"]`` /
+ # ``["top_findings"]``, which the ``only`` projection's ``wants()``
+ # gating can skip building — so
+ # ``only=["refactoring_plans","suggestion_legend"]`` returned an empty
+ # legend and adding ``top_findings`` back to ``only`` refilled it. A
+ # projection is supposed to subtract keys, never change what a surviving
+ # key contains.
+ #
+ # Scope note, and it is a real limitation rather than an oversight: the
+ # legend explains the *findings*, while it ships beside
+ # ``refactoring_plans``. Those are different sets — no plan kind is
+ # sourced from ``coverage_gradient``, the lead biomarker on this repo's
+ # ten worst files — so a legend entry can describe a biomarker the plans
+ # do not address. ``directive.plan_addresses_reason`` is what reports
+ # that mismatch; the legend is not the place to paper over it.
+ present_types = {getattr(r, "biomarker_type", None) for r in legend_rows}
result["suggestion_legend"] = {
bt: suggestion_for(bt) for bt in sorted(t for t in present_types if t)
}
@@ -1086,12 +1258,21 @@ async def get_health(
# ``_meta`` always survive — a response the caller cannot orient in is not
# a saving.
if only:
- keep = set(only) | {"mode"}
+ # Every capped list's ``*_total`` sibling survives with it. The tool
+ # documents "each carries a ``*_total`` sibling so truncation is never
+ # silent", and the projection was quietly breaking exactly that promise:
+ # ``only=["modules"]`` at ``limit=50`` returned 50 of 116 modules with
+ # no ``modules_total`` to say so. Retaining it is not the caller's job —
+ # a caller who knew to ask for the total would not need the guarantee.
+ keep = set(only_list) | {"mode"} | {f"{k}_total" for k in only_list}
# A key that does not exist in this response is named rather than
# quietly yielding an empty one — same rule as ``unresolved`` above.
# A misspelled projection is otherwise indistinguishable from a block
- # the repo genuinely has no data for.
- unknown = sorted(k for k in only if k not in result)
+ # the repo genuinely has no data for. Reported against what the caller
+ # actually passed, so an alias resolving to a present key is not "unknown".
+ unknown = sorted(
+ raw for raw, resolved in zip(only, only_list, strict=True) if resolved not in result
+ )
result = {k: v for k, v in result.items() if k in keep}
if unknown:
result["unknown_only_keys"] = unknown
diff --git a/tests/unit/server/mcp/test_health.py b/tests/unit/server/mcp/test_health.py
index 898ff6374..32dad5af9 100644
--- a/tests/unit/server/mcp/test_health.py
+++ b/tests/unit/server/mcp/test_health.py
@@ -647,3 +647,419 @@ async def test_one_response_agrees_with_itself_about_the_worst_file(
# Same reduction, same tie, one level down: the module rollup's worst
# performer is picked with ``min()`` over the same rows.
assert [m["worst_performer_path"] for m in result["modules"]] == ["src/z.py"]
+
+
+# ---------------------------------------------------------------------------
+# Projection integrity: ``only`` x ``include`` x mode.
+#
+# Three separate dogfooding passes have now found bugs in the *interaction* of
+# these parameters and nowhere else, so these enumerate combinations rather
+# than inspect one response.
+# ---------------------------------------------------------------------------
+
+
+ ("key", "include"),
+ [
+ ("worst_files", None),
+ ("high_leverage_files", None),
+ ("top_findings", None),
+ ("test_findings", None),
+ ("modules", None),
+ ("findings", ["biomarkers"]),
+ ("refactoring_plans", ["refactoring"]),
+ ],
+)
+async def test_only_retains_the_total_for_every_capped_list(setup_mcp, health_data, key, include):
+ """``only=[list]`` keeps that list's ``*_total`` sibling.
+
+ Regression: the projection kept exactly the named keys, so the tool's own
+ "each carries a ``*_total`` sibling so truncation is never silent" promise
+ broke precisely when a caller economized. ``only=["modules"]`` at
+ ``limit=50`` returned 50 of 116 modules with nothing saying so.
+
+ Asking the caller to name the total themselves is not a fix: a caller who
+ knew to ask for it would not need the guarantee.
+ """
+ from repowise.server.mcp_server import get_health
+
+ result = await get_health(include=include, only=[key], limit=1)
+ assert key in result, result.get("unknown_only_keys")
+ assert f"{key}_total" in result, f"{key} lost its total under a projection"
+ # And it is the real count, not the length of the capped list.
+ full = await get_health(include=include, limit=1)
+ assert result[f"{key}_total"] == full[f"{key}_total"]
+
+
+async def test_worst_files_and_high_leverage_files_report_totals(setup_mcp, health_data):
+ """Both ranked file lists carry a total, like every other capped list.
+
+ ``worst_files_total`` did not exist in any projection — asking for it came
+ back in ``unknown_only_keys``, which reads as "you misspelled it" for a key
+ that was simply never emitted.
+ """
+ from repowise.server.mcp_server import get_health
+
+ result = await get_health(limit=1)
+ assert len(result["worst_files"]) == 1
+ assert result["worst_files_total"] == 2
+ assert len(result["high_leverage_files"]) == 1
+ # Leverage only ranks the below-Healthy files, so this is not file_count.
+ assert result["high_leverage_files_total"] == 1
+
+
+ ("alias", "resolved", "include"),
+ [
+ ("biomarkers", "findings", ["biomarkers"]),
+ ("accuracy", "defect_accuracy", ["accuracy"]),
+ ("refactoring", "refactoring_plans", ["refactoring"]),
+ ],
+)
+async def test_include_names_work_as_only_aliases(setup_mcp, health_data, alias, resolved, include):
+ """``include`` and ``only`` were two vocabularies for the same blocks.
+
+ A caller switches a block on with ``include=["biomarkers"]`` and it lands
+ under the key ``findings``, so the obvious ``only=["biomarkers"]`` projected
+ away the very block just asked for — reported only via
+ ``unknown_only_keys``, which is what kept it survivable rather than silent.
+ """
+ from repowise.server.mcp_server import get_health
+
+ result = await get_health(include=include, only=[alias])
+ assert resolved in result
+ # An alias that resolves is not "unknown".
+ assert "unknown_only_keys" not in result
+ assert set(result) - {"mode", "_meta"} <= {resolved, f"{resolved}_total"}
+
+
+async def test_only_signals_is_reported_rather_than_answered_empty(setup_mcp, health_data):
+ """``signals`` has no top-level key, and saying so is the whole fix.
+
+ It merges into ``metrics[].signals``, so ``only=["signals"]`` can only ever
+ return an empty response. Deliberately *not* aliased — there is no key to
+ alias it to — so it must keep landing in ``unknown_only_keys``.
+ """
+ from repowise.server.mcp_server import get_health
+
+ result = await get_health(include=["signals"], only=["signals"])
+ assert result["unknown_only_keys"] == ["signals"]
+
+
+async def test_suggestion_legend_survives_a_projection(setup_mcp, health_data_with_tests):
+ """A projection subtracts keys; it must not change what a kept key holds.
+
+ Regression: the legend was built from ``result["findings"]`` /
+ ``["top_findings"]``, which the projection's work-gating can skip building.
+ So ``only=["refactoring_plans", "suggestion_legend"]`` returned
+ ``suggestion_legend: {}``, and adding ``top_findings`` back to ``only``
+ refilled it — a performance optimization that had silently become a
+ content change.
+
+ Deliberately on the fixture that *has* test material. The legend derives
+ from the production and test heads, so on a fixture with no test files
+ every projection agrees for the wrong reason and this test cannot fail —
+ which is exactly what happened when the ``is_test`` read was later gated
+ for performance and silently dropped ``suggestion_legend`` from the gate.
+ """
+ from repowise.server.mcp_server import get_health
+
+ full = await get_health(include=["refactoring"])
+ assert full["suggestion_legend"], "fixture should produce legend entries"
+
+ without_findings = await get_health(
+ include=["refactoring"], only=["refactoring_plans", "suggestion_legend"]
+ )
+ with_findings = await get_health(
+ include=["refactoring"], only=["refactoring_plans", "suggestion_legend", "top_findings"]
+ )
+ assert without_findings["suggestion_legend"] == full["suggestion_legend"]
+ assert with_findings["suggestion_legend"] == full["suggestion_legend"]
+
+ # And it explains every biomarker the response actually shows.
+ shown = {f["biomarker_type"] for f in full["top_findings"] + full["test_findings"]}
+ assert shown <= set(full["suggestion_legend"])
+
+
+async def test_limit_zero_means_no_rows_not_one_row(setup_mcp, health_data):
+ """``0`` means none, matching the ``module_limit`` convention.
+
+ It used to clamp up to 1, so the documented way to ask for "the totals,
+ none of the rows" quietly returned a row, and a caller trimming a payload
+ could not tell the clamp had happened.
+ """
+ from repowise.server.mcp_server import get_health
+
+ result = await get_health(limit=0)
+ for key in ("worst_files", "high_leverage_files", "top_findings", "test_findings", "modules"):
+ assert result[key] == [], key
+ # Totals are unaffected: the cap is a display decision, not a filter.
+ assert result["worst_files_total"] == 2
+ assert result["top_findings_total"] == (await get_health())["top_findings_total"]
+
+
+async def test_the_directive_is_identical_at_every_limit(setup_mcp, health_data):
+ """``limit`` caps ranked lists. The directive is not one, so it must not move.
+
+ Regression, and it was introduced by making ``limit=0`` reachable: the
+ per-file lead reduction was scoped to ``metric_rows[:limit] |
+ by_leverage[:limit]``, so at ``limit=0`` the directive's own candidates had
+ no lead. ``fix_first`` survived (it reads ``by_leverage[0]``, not the
+ leads), which is exactly why asserting ``fix_first`` alone was not enough —
+ ``reason`` fell back to "scores N", ``plan_note`` vanished, and
+ ``plan_addresses_reason`` became an unconditional ``False``: a wrong claim
+ rather than a missing one.
+ """
+ from repowise.server.mcp_server import get_health
+
+ baseline = (await get_health())["directive"]
+ assert baseline["reason"]
+ for limit in (0, 1, 2, 50):
+ directive = (await get_health(limit=limit))["directive"]
+ assert directive == baseline, f"directive moved at limit={limit}"
+ # And through the projection that makes it the cheapest call.
+ assert (await get_health(only=["directive"], limit=0))["directive"] == baseline
+
+
+# ---------------------------------------------------------------------------
+# Test material in the defect dashboard
+# ---------------------------------------------------------------------------
+
+
+async def health_data_with_tests(session, health_data: str) -> str:
+ """Add a test file that would dominate the headline finding list.
+
+ ``tests/test_service.py`` is already seeded in ``graph_nodes`` with
+ ``is_test=True``; this gives it health rows. Its findings carry the two
+ highest impacts in the fixture, so an unsplit list leads with the test
+ suite — which is the shape measured on the real index, where 2 of the top
+ 5 open findings repo-wide sat on test files.
+
+ Rows are added through the ORM rather than ``save_health_metrics`` /
+ ``save_health_findings``: both are delete-then-insert over the whole repo,
+ so calling them here would wipe the base fixture instead of extending it.
+ """
+ import json
+ import uuid
+
+ from repowise.core.persistence.models import HealthFileMetric, HealthFinding
+
+ rid = health_data
+ session.add(
+ HealthFileMetric(
+ id=str(uuid.uuid4()),
+ repository_id=rid,
+ file_path="tests/test_service.py",
+ score=3.0,
+ max_ccn=12,
+ max_nesting=4,
+ nloc=120,
+ has_test_file=False,
+ module="tests",
+ )
+ )
+ for biomarker, fn, impact, reason in (
+ ("change_entropy", None, 3.02, "tests/test_service.py changes with unrelated files"),
+ ("complex_method", "test_everything", 2.5, "test_everything has complexity 12"),
+ ):
+ session.add(
+ HealthFinding(
+ id=str(uuid.uuid4()),
+ repository_id=rid,
+ file_path="tests/test_service.py",
+ biomarker_type=biomarker,
+ severity="critical" if fn is None else "high",
+ function_name=fn,
+ line_start=None if fn is None else 1,
+ line_end=None if fn is None else 90,
+ details_json=json.dumps({}),
+ health_impact=impact,
+ reason=reason,
+ dimension="defect",
+ status="open",
+ )
+ )
+ await session.flush()
+ return rid
+
+
+async def test_test_findings_get_their_own_bucket(setup_mcp, health_data_with_tests):
+ """Test material stops competing for the repo's headline finding list.
+
+ Measured on this repo before the split: 5 of the top 20 open findings by
+ impact sat on test files, 2 of the top 5. Defect risk in a test asks a
+ different question from defect risk in the code it covers, and a
+ high-churn test file usually means active development rather than
+ fragility — so it is bucketed, not dropped.
+ """
+ from repowise.server.mcp_server import get_health
+
+ result = await get_health()
+
+ # Unsplit, the two highest-impact findings in the fixture are both tests.
+ assert [f["file_path"] for f in result["test_findings"]] == [
+ "tests/test_service.py",
+ "tests/test_service.py",
+ ]
+ assert all(f["file_path"] != "tests/test_service.py" for f in result["top_findings"])
+ assert result["top_findings"][0]["file_path"] == "src/auth/service.py"
+
+ # Nothing is lost: the two buckets partition the whole open set.
+ assert result["test_findings_total"] == 2
+ assert result["top_findings_total"] == 4
+ assert result["top_findings_total"] + result["test_findings_total"] == 6
+
+
+async def test_each_bucket_is_capped_against_its_own_population(
+ setup_mcp, health_data_with_tests
+):
+ """The split happens before the cap, not after.
+
+ Capping first and partitioning after would hand the smaller bucket
+ whatever happened to land in the shared head — so with two test findings
+ above every production one, ``top_findings`` would come back empty at
+ ``limit=2`` while ``top_findings_total`` claimed four.
+ """
+ from repowise.server.mcp_server import get_health
+
+ result = await get_health(limit=2)
+ assert len(result["top_findings"]) == 2
+ assert len(result["test_findings"]) == 2
+ assert result["top_findings_total"] == 4
+
+
+async def test_metric_rows_say_whether_a_file_is_test_material(
+ setup_mcp, health_data_with_tests
+):
+ """``is_test`` is a fact on the row, distinct from ``has_test_file``.
+
+ The two answer opposite questions — "is this file a test" vs "is this file
+ tested" — and nothing in the payload used to say which one you were
+ looking at.
+ """
+ from repowise.server.mcp_server import get_health
+
+ result = await get_health()
+ by_path = {m["file_path"]: m for m in result["worst_files"]}
+ assert by_path["tests/test_service.py"]["is_test"] is True
+ assert by_path["src/auth/service.py"]["is_test"] is False
+ # Both ranked file lists carry it.
+ assert all("is_test" in m for m in result["high_leverage_files"])
+
+
+async def test_targeted_mode_is_never_split(setup_mcp, health_data_with_tests):
+ """Naming a test file must return its findings, not bucket them away.
+
+ The split answers "where is the defect risk in this codebase". A caller
+ who named the file already answered that question themselves.
+ """
+ from repowise.server.mcp_server import get_health
+
+ result = await get_health(targets=["tests/test_service.py"])
+ assert result["mode"] == "targets"
+ assert "test_findings" not in result
+ assert len(result["findings"]) == 2
+ assert result["findings_total"] == 2
+ assert result["metrics"][0]["is_test"] is True
+
+
+async def test_kpis_still_include_test_files(setup_mcp, health_data_with_tests):
+ """Excluding test material from the KPIs is a scoring change, not a display one.
+
+ Measured across this workspace, dropping tests moves NLOC-weighted
+ ``average_health`` 7.52 -> 6.87 on this repo, 7.07 -> 6.27 on the backend
+ and 7.59 -> 7.46 on the frontend: test files score *better* than
+ production code, so excluding them would drop every repo's headline
+ overnight with no defect having been found.
+ """
+ from repowise.server.mcp_server import get_health
+
+ result = await get_health()
+ assert result["kpis"]["file_count"] == 3
+ assert any(m["file_path"] == "tests/test_service.py" for m in result["worst_files"])
+
+
+async def test_the_split_survives_a_dimension_filter(setup_mcp, health_data_with_tests):
+ """A cap, a filter and a partition over one list — the shape that keeps breaking.
+
+ Both totals must describe the *filtered* set, and still sum to it.
+ """
+ from repowise.server.mcp_server import get_health
+
+ unfiltered = await get_health()
+ filtered = await get_health(include=["biomarkers", "defect"])
+ assert all(f["dimension"] == "defect" for f in filtered["findings"])
+ assert all(f["dimension"] == "defect" for f in filtered["test_findings"])
+ assert (
+ filtered["findings_total"] + filtered["test_findings_total"]
+ < unfiltered["top_findings_total"] + unfiltered["test_findings_total"]
+ )
+
+
+# ---------------------------------------------------------------------------
+# Coverage: the read, not just the response
+# ---------------------------------------------------------------------------
+
+
+async def test_dashboard_coverage_declines_the_covered_lines_column(setup_mcp, health_data):
+ """The dashboard asks the data layer not to read the blob it never emits.
+
+ This asserts the *read*, deliberately. The response was already correct —
+ the dashboard built each row wide, ``json.loads``-ing every
+ ``covered_lines_json``, and then stripped ``covered_lines`` back out with a
+ dict comprehension. So a test that only checked the payload would pass on
+ the unfixed code; the waste is invisible from the outside.
+ """
+ from repowise.server.mcp_server import get_health, tool_health
+
+ seen: list[bool] = []
+ real = tool_health.load_coverage_for_repo
+
+ async def spy(*args, **kwargs):
+ seen.append(kwargs.get("include_covered_lines", True))
+ return await real(*args, **kwargs)
+
+ tool_health.load_coverage_for_repo = spy
+ try:
+ await get_health(include=["coverage"])
+ assert seen == [False], "dashboard mode still read the covered-line arrays"
+ seen.clear()
+ await get_health(include=["coverage"], targets=["src/auth/service.py"])
+ assert seen == [True], "targeted mode serializes covered_lines and must read it"
+ finally:
+ tool_health.load_coverage_for_repo = real
+
+
+async def test_coverage_payload_shape_is_unchanged(setup_mcp, health_data):
+ """Guards the restructure, not a past bug — it passes on the reverted code.
+
+ Kept because the narrow rows are a different object: they carry no
+ ``covered_lines_json`` at all, so the old build-wide-then-subtract would
+ now raise rather than merely waste the parse.
+ """
+ from repowise.server.mcp_server import get_health
+
+ dashboard = await get_health(include=["coverage"])
+ for row in dashboard["coverage"]["files"]:
+ assert "covered_lines" not in row
+ assert {"file_path", "line_coverage_pct", "total_coverable_lines"} <= set(row)
+
+ targeted = await get_health(include=["coverage"], targets=["src/auth/service.py"])
+ for row in targeted["coverage"]["files"]:
+ assert "covered_lines" in row