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): 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.mdindex 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. Atarget set that resolves to nothing still answers in targeted mode rather thanfalling 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 thebadge 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 prosesuggestion 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 findingsget_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.pyindex 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.pyindex 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 outdef _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 cannotseparate 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. Atarget 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 = 0if scoped:finding_rows = filter_rows_by_attr(list(@@ -605,6 +684,7 @@ async def get_health(lead_rows: list[Any] = finding_rowsemitted = [f for f in finding_rows if _in_dimensions(f, dimension_filter)]finding_rows = emitted[:limit]+ legend_rows: list[Any] = finding_rowselse:# 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: ffor 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_totalif "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"] = unknowndiff --git a/tests/unit/server/mcp/test_health.py b/tests/unit/server/mcp/test_health.pyindex 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