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(mcp): stop get_health dropping targets and repeating itself (#1142)

Raghav Chamadiya3d4042a25959
diff --git a/docs/agent/MCP_TOOLS.md b/docs/agent/MCP_TOOLS.md
index e26c15dae..42d03a173 100644
--- a/docs/agent/MCP_TOOLS.md
+++ b/docs/agent/MCP_TOOLS.md
@@ -481,16 +481,32 @@ 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. |
| `repo` | string | No | *(workspace only)* Target repo alias |
-| `limit` | int | No | Max rows in the lowest-scoring file list (default 20, capped at 50) |
+| `limit` | int | No | Max rows in **every** ranked list (default 20, capped at 50) |
-**Returns:** Dashboard mode (no `targets`) returns repo-level KPIs (hotspot
-health, average health, worst performer, maintainability / performance pillar
-averages), the lowest-scoring files, and a per-module NLOC-weighted rollup.
-Targeted mode returns per-file marker findings with severity, per-dimension
-scores, and the score breakdown. Each finding carries a `dimension`
+**Returns:** Dashboard mode (no `targets`) returns a `directive`, repo-level KPIs
+(hotspot health, average health, worst performer, maintainability / performance
+pillar averages), the lowest-scoring files, and a per-module NLOC-weighted
+rollup. Targeted mode returns per-file marker findings with severity,
+per-dimension scores, and the score breakdown. Each finding carries a `dimension`
(`defect` / `maintainability` / `performance`).
+**Lead with `directive`.** Dashboard mode opens with the single file to fix
+first, its dominant finding, `recovers_points` / `share_of_repo_gap_pct` (what
+fixing it buys the headline), and `then`, the next two by leverage. Every other
+block ranks and describes; this one recommends. Same role as `get_risk`'s
+`directive`. Rank by `weighted_deficit`, not `score` — the score floors at 1.0.
+
+**Nothing is dropped silently.** Any `targets` entry that matched nothing is
+named in `unresolved` with a reason (`not_indexed` → run `repowise update`,
+`no_such_path`, `excluded`, `no_such_module`; a missed module name also returns
+`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.
+
**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
make that actionable rather than a mystery:
@@ -531,9 +547,11 @@ The opt-in enrichments:
plans on the files that move the headline surface first; `refactoring_plans_total`
reports the full count behind the cap. Each plan echoes its
`file_weighted_deficit`. Full shapes in [`docs/layers/REFACTORING.md`](../layers/REFACTORING.md).
-- **dimension filter** narrows the returned findings to one pillar. Pair with
- `"biomarkers"` for the full (uncapped) finding set, e.g.
+- **dimension filter** narrows the returned findings to one pillar, e.g.
`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`.
**When to use:** Before opening a PR, to self-check the files you changed
(`targets=[...], include=["signals"]`) and confirm you are not regressing the
@@ -544,11 +562,13 @@ hotspots.
**Example calls:**
```
-get_health() # kpis, gap_analysis, worst + high_leverage files
+get_health(only=["directive"]) # cheapest useful call: what to fix first
+get_health() # directive, kpis, gap_analysis, worst + high_leverage files
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
```
---
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 68f69c5e5..4f7e5db6e 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_health.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_health.py
@@ -4,6 +4,7 @@ from __future__ import annotations
import json
from dataclasses import asdict
+from pathlib import Path
from typing import Any
from sqlalchemy import select
@@ -202,6 +203,77 @@ def _module_rollups(metrics: list[HealthFileMetric]) -> list[dict[str, Any]]:
return out
+def _unresolved_targets(
+ *,
+ file_targets: list[str],
+ module_targets: list[str],
+ matched_modules: set[str],
+ resolved_paths: set[str],
+ excluded_paths: set[str],
+ repo_root: Any,
+) -> list[dict[str, str]]:
+ """Name every requested target that produced no rows, with a reason.
+
+ A dropped target is otherwise indistinguishable from a clean file: an
+ empty ``findings`` list reads as "this file is healthy", which is the most
+ damaging default this tool can have. The reason is the actionable part —
+ ``not_indexed`` means run ``repowise update``, ``no_such_path`` means the
+ target was a typo, ``excluded`` means the repo config drops it on purpose.
+ """
+ out: list[dict[str, str]] = []
+ for t in file_targets:
+ if t in resolved_paths:
+ continue
+ if t in excluded_paths:
+ reason = "excluded"
+ else:
+ try:
+ on_disk = (Path(repo_root) / t).exists()
+ except (OSError, ValueError):
+ on_disk = False
+ reason = "not_indexed" if on_disk else "no_such_path"
+ out.append({"target": t, "reason": reason})
+ out.extend(
+ {"target": f"module:{name}", "reason": "no_such_module"}
+ for name in module_targets
+ if name not in matched_modules
+ )
+ return out
+
+
+def _directive(
+ by_leverage: list[HealthFileMetric],
+ leads: dict[str, dict[str, Any]],
+ gap_points: int,
+) -> dict[str, Any] | None:
+ """The one file to fix first, and what fixing it buys.
+
+ Every other block here ranks and describes; none of them recommends. That
+ gap is why a correct finding can sit at position 12 of an undifferentiated
+ list and change nobody's behaviour. Same role as ``get_risk``'s
+ ``directive``: lead with the call, keep the evidence underneath.
+
+ Ranked by ``weighted_deficit`` (not ``score``, which floors at 1.0), so
+ this names the file that actually moves the repo average.
+ """
+ if not by_leverage:
+ return None
+ top = by_leverage[0]
+ recovers = round(max(HEALTHY_MIN - top.score, 0.0) * max(top.nloc, 1))
+ lead = leads.get(top.file_path) or {}
+ return {
+ "fix_first": top.file_path,
+ "reason": lead.get("primary_reason") or f"scores {round(top.score, 2)}",
+ # Points the repo headline recovers if this one file reaches Healthy,
+ # and what share of the total gap that is — the "few files, not the
+ # long tail" argument made concrete for a single file.
+ "recovers_points": recovers,
+ "share_of_repo_gap_pct": (round(100.0 * recovers / gap_points, 1) if gap_points else None),
+ "then": [m.file_path for m in by_leverage[1:3]],
+ "plan_via": "get_health(include=['refactoring'])",
+ }
+
+
def _dimension_average(metrics: list[HealthFileMetric], attr: str) -> float | None:
"""NLOC-weighted headline over a per-dimension score attribute.
@@ -338,32 +410,35 @@ async def get_health(
include: list[str] | None = None,
repo: str | None = None,
limit: int = 20,
+ only: list[str] | None = None,
) -> dict:
"""Code-health scores and findings — self-check a file before/after editing.
- No ``targets`` → repo dashboard (KPIs, worst files, ``high_leverage_files``
- ranked by ``weighted_deficit`` = the files that actually move the repo
- average). With ``targets`` → per-file scores + findings for those paths.
+ No ``targets`` → repo dashboard, led by a ``directive`` naming the one file
+ to fix first. With ``targets`` → per-file scores + findings. Rank by
+ ``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`` (readability/change-cost smells), and
- ``performance_score`` (static I/O-in-loop / N+1 RISK, high-precision /
- low-recall, never blended into the defect headline). Each finding carries
- its ``dimension``; a performance finding's ``details`` name the
- ``boundary_kind`` (db/network/filesystem/subprocess/lock) and, for
- cross-function N+1, the caller→sink ``path``.
+ ``maintainability_score``, and ``performance_score`` (static I/O-in-loop /
+ N+1 risk, never blended into the defect headline). Each finding carries its
+ ``dimension``.
Args:
- targets: file paths or ``module:<name>``. Empty → dashboard mode.
- include: opt-in blocks (default stays lean): ``biomarkers`` (findings
- in dashboard mode) | ``refactoring`` (deterministic suggestion per
- finding) | ``trend`` | ``coverage`` | ``accuracy`` (does the score
- rank the buggy files first) | ``signals`` (per-file churn/owners/
- degree, targeted mode) | ``churn_complexity`` (danger-zone
- quadrant) | ``performance``/``defect``/``maintainability``
- (filter findings to one dimension).
+ targets: file paths or ``module:<name>``. Empty → dashboard mode. Any
+ 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.
repo: usually omitted.
- limit: max rows in ranked lists (capped at 50).
+ limit: max rows in every ranked list (capped at 50); each carries a
+ ``*_total`` sibling so truncation is never silent.
"""
limit = min(max(limit, 1), 50)
include_set = set(include or [])
@@ -373,7 +448,9 @@ async def get_health(
# belonging to those modules.
raw_targets = list(targets or [])
module_targets = [t.split(":", 1)[1] for t in raw_targets if t.startswith("module:")]
- file_targets = [t for t in raw_targets if not t.startswith("module:")]
+ # Stored paths are POSIX-separated. Normalize so a Windows caller passing
+ # ``packages\core\x.py`` matches instead of coming back ``no_such_path``.
+ file_targets = [t.replace("\\", "/") for t in raw_targets if not t.startswith("module:")]
ctx = await _resolve_repo_context(repo)
# Performance headline inputs (dashboard mode): filled inside the session.
@@ -386,22 +463,32 @@ async def get_health(
HealthFileMetric.repository_id == repository.id
)
exclude_spec = _get_exclude_spec(ctx.path)
- all_metrics = filter_rows_by_attr(
- list((await session.execute(all_metrics_q)).scalars().all()),
- "file_path",
- exclude_spec,
- )
-
+ 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
+ # unresolved target can report "excluded" (a config decision) rather
+ # than "no_such_path" (a typo) — the two need different responses.
+ excluded_paths = {m.file_path for m in indexed_rows} - {m.file_path for m in all_metrics}
+
+ matched_modules: set[str] = set()
if module_targets:
module_set = set(module_targets)
for m in all_metrics:
if m.module in module_set:
+ matched_modules.add(m.module)
file_targets.append(m.file_path)
file_targets = sorted(set(file_targets))
- effective_targets = file_targets if (raw_targets) else []
+ # A non-empty ``targets`` means the caller asked for a scope, and that
+ # holds even when nothing resolves. Keying the mode off the *resolved*
+ # paths let ``targets=["module:typo"]`` fall through to dashboard mode
+ # and answer a module-scoped question with repo-wide numbers — an
+ # answer that reads as scoped and is not.
+ scoped = bool(raw_targets)
+ effective_targets = file_targets if scoped else []
+ nothing_resolved = scoped and not effective_targets
- if effective_targets:
+ if scoped:
metric_rows = [
m
for m in sorted(all_metrics, key=lambda r: r.score)
@@ -414,7 +501,7 @@ async def get_health(
HealthFinding.repository_id == repository.id,
HealthFinding.status == "open",
)
- if effective_targets:
+ if scoped:
finding_q = finding_q.where(HealthFinding.file_path.in_(effective_targets))
finding_q = finding_q.order_by(HealthFinding.health_impact.desc())
finding_rows = filter_rows_by_attr(
@@ -426,7 +513,7 @@ async def get_health(
# Dashboard perf headline: coverage (how much of the analyzed code the
# perf pass ran on) + open performance-finding count. finding_rows in
# dashboard mode is the complete open set, so the count is exact.
- if not effective_targets:
+ if not scoped:
lang_by_path = await get_file_language_map(session, repository.id)
perf_coverage = coverage_for_metrics(all_metrics, lang_by_path)
perf_findings_count = sum(
@@ -436,12 +523,12 @@ async def get_health(
# Structured refactoring plans (Extract Class, ...) — loaded only when
# asked for, scoped to the same targets, exclude-filtered like findings.
refactoring_rows: list[Any] = []
- if "refactoring" in include_set:
+ if "refactoring" in include_set and not nothing_resolved:
refactoring_rows = filter_rows_by_attr(
await get_refactoring_suggestions(
session,
repository.id,
- file_paths=list(effective_targets) if effective_targets else None,
+ file_paths=list(effective_targets) if scoped else None,
),
"file_path",
exclude_spec,
@@ -449,10 +536,12 @@ async def get_health(
coverage_rows: list[Any] = []
coverage_summary: dict[str, Any] = {}
- if "coverage" in include_set:
+ if "coverage" in include_set and not nothing_resolved:
coverage_rows = filter_rows_by_attr(
+ # ``effective_targets``, not ``targets`` — a raw ``module:foo``
+ # target is not a file path and matched nothing here.
await load_coverage_for_repo(
- session, repository.id, file_paths=list(targets) if targets else None
+ session, repository.id, file_paths=list(effective_targets) if scoped else None
),
"file_path",
exclude_spec,
@@ -480,7 +569,7 @@ async def get_health(
# Churn x complexity quadrant for the whole repo (dashboard mode). One
# git-metadata query joined against the already-loaded metrics.
churn_points: list[dict[str, Any]] = []
- if "churn_complexity" in include_set and not effective_targets:
+ if "churn_complexity" in include_set and not scoped:
git_meta_by_path = await get_all_git_metadata(session, repository.id)
churn_points = [
asdict(p) for p in churn_complexity_points(all_metrics, git_meta_by_path)[:limit]
@@ -490,11 +579,11 @@ async def get_health(
# per-file trajectory we attach in targeted mode ("should I touch this
# file" context for agents).
snapshots: list[Any] = []
- if "trend" in include_set or effective_targets:
+ if "trend" in include_set or scoped:
snapshots = await list_health_snapshots(session, repository.id, limit=20)
kpis = _compute_kpis(
- metric_rows if effective_targets else all_metrics,
+ metric_rows if scoped else all_metrics,
performance_findings=perf_findings_count,
coverage=perf_coverage,
)
@@ -502,7 +591,7 @@ async def get_health(
# findings are scoped to the targets; dashboard findings cover every file).
leads = _leads_by_file(finding_rows)
- if effective_targets:
+ if scoped:
metric_payload: list[dict[str, Any]] = []
for m in metric_rows:
row = _serialize_metric(m, leads.get(m.file_path))
@@ -513,8 +602,25 @@ async def get_health(
"mode": "targets",
"targets": raw_targets,
"metrics": metric_payload,
- "findings": [_serialize_finding(f) for f in finding_rows],
+ # Capped like every other ranked list, with the total alongside so
+ # the truncation is visible rather than inferred from the length.
+ "findings": [_serialize_finding(f) for f in finding_rows[:limit]],
+ "findings_total": len(finding_rows),
}
+ unresolved = _unresolved_targets(
+ file_targets=file_targets,
+ module_targets=module_targets,
+ matched_modules=matched_modules,
+ resolved_paths={m.file_path for m in metric_rows},
+ excluded_paths=excluded_paths,
+ repo_root=ctx.path,
+ )
+ if unresolved:
+ result["unresolved"] = unresolved
+ if any(u["reason"] == "no_such_module" for u in unresolved):
+ # ``module:`` has no discovery call of its own, so a bad name
+ # would otherwise cost a full dashboard round-trip to correct.
+ result["known_modules"] = sorted({m.module for m in all_metrics if m.module})
# Per-file score trajectory for each target — silent (omitted) when a
# file has < 2 snapshots of history rather than a misleading flat line.
trends = []
@@ -534,8 +640,8 @@ async def get_health(
if trends:
result["trends"] = trends
if module_targets:
- scoped = [m for m in all_metrics if m.module in set(module_targets)]
- result["modules"] = _module_rollups(scoped)
+ in_modules = [m for m in all_metrics if m.module in set(module_targets)]
+ result["modules"] = _module_rollups(in_modules)
else:
# Dashboard mode — top-N worst files + headline findings + the
# per-module rollup so the overview page doesn't need a second
@@ -550,13 +656,18 @@ async def get_health(
key=lambda m: max(HEALTHY_MIN - m.score, 0.0) * max(m.nloc, 1),
reverse=True,
)
+ all_modules = _module_rollups(all_metrics)
+ gap = _gap_analysis(all_metrics)
result = {
"mode": "dashboard",
+ # Lead with the call, not the data. Every block below ranks and
+ # describes; this one recommends.
+ "directive": _directive(by_leverage, leads, gap.get("weighted_gap_points") or 0),
"kpis": kpis,
"distribution": health_distribution(all_metrics),
# Where the gap to Healthy concentrates — the "few files, not the
# long tail" reframe that turns a repo-wide number into a short list.
- "gap_analysis": _gap_analysis(all_metrics),
+ "gap_analysis": gap,
"worst_files": [
_serialize_metric(m, leads.get(m.file_path)) for m in metric_rows[:limit]
],
@@ -564,7 +675,11 @@ async def get_health(
_serialize_metric(m, leads.get(m.file_path)) for m in by_leverage[:limit]
],
"top_findings": [_serialize_finding(f) for f in finding_rows[:limit]],
- "modules": _module_rollups(all_metrics),
+ "top_findings_total": len(finding_rows),
+ # 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],
+ "modules_total": len(all_modules),
}
if "churn_complexity" in include_set:
result["churn_complexity"] = churn_points
@@ -609,24 +724,16 @@ async def get_health(
for r in ranked[:limit]
]
result["refactoring_plans_total"] = len(refactoring_rows)
- # Attach the deterministic prose suggestion to every finding as the
- # fallback for biomarkers without a structured detector yet. Surfaces
- # on the dashboard cards too so both consumers stay in sync.
- for field in ("findings", "top_findings"):
- rows = result.get(field)
- if rows:
- result[field] = [
- {**row, "suggestion": suggestion_for(row.get("biomarker_type", ""))}
- for row in rows
- ]
- if "findings" not in result and "top_findings" not in result:
- result["findings"] = [
- {
- **_serialize_finding(f),
- "suggestion": suggestion_for(f.biomarker_type),
- }
- for f in finding_rows
- ]
+ # The deterministic prose suggestion is the fallback for biomarkers
+ # that have no structured detector yet. It is emitted once per
+ # biomarker type as ``suggestion_legend`` (built below, after the
+ # dimension filter) rather than copied onto every finding: the text is
+ # keyed purely by type, so the per-row form repeated one ~40-word
+ # string up to 10x in a single response.
+ #
+ # (The old no-findings-anywhere fallback here was unreachable: targeted
+ # mode always sets ``findings`` and dashboard mode always sets
+ # ``top_findings``.)
if "trend" in include_set:
summary = diff_snapshots(snapshots)
@@ -686,7 +793,42 @@ async def get_health(
r for r in rows if (r.get("dimension") or "defect") in dimension_filter
]
+ # 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 ()
+ }
+ result["suggestion_legend"] = {
+ bt: suggestion_for(bt) for bt in sorted(t for t in present_types if t)
+ }
+
+ # Projection. ``include`` could only ever add blocks, so asking for one
+ # extra block re-shipped the whole dashboard with it; ``only`` is the
+ # subtract half. Applied last so it can drop anything above, and ``mode`` /
+ # ``_meta`` always survive — a response the caller cannot orient in is not
+ # a saving.
+ if only:
+ keep = set(only) | {"mode"}
+ # 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)
+ result = {k: v for k, v in result.items() if k in keep}
+ if unknown:
+ result["unknown_only_keys"] = unknown
+
# Targeted mode scopes the stale signal to the asked-about files; the
# dashboard (no targets) keeps the repo-level warning.
result["_meta"] = _build_meta(repository=repository, targets=targets if targets else None)
+ # When the health pass last ran, which is a separate pass from indexing and
+ # can lag it. ``_build_meta``'s fields all describe the *index*, so a stale
+ # health row was previously invisible.
+ analyzed = [m.updated_at for m in all_metrics if getattr(m, "updated_at", None)]
+ if analyzed:
+ result["_meta"]["health_analyzed_at"] = max(analyzed).isoformat()
return result
diff --git a/plugins/claude-code/skills/code-health/SKILL.md b/plugins/claude-code/skills/code-health/SKILL.md
index ccf711103..03d753182 100644
--- a/plugins/claude-code/skills/code-health/SKILL.md
+++ b/plugins/claude-code/skills/code-health/SKILL.md
@@ -19,9 +19,9 @@ not just *bigger*.
## Pick the mode by what you pass
-- **Dashboard** — `get_health()` (no targets): repo-level KPIs plus the
- lowest-scoring files. Start here for "how healthy is this codebase?" or "what
- should we clean up?".
+- **Dashboard** — `get_health()` (no targets): a `directive` naming what to fix
+ first, then repo-level KPIs and the lowest-scoring files. Start here for "how
+ healthy is this codebase?" or "what should we clean up?".
- **Targeted** — `get_health(targets=["src/x.py", "src/y.py"])`: per-file score
and the specific marker findings driving it. Use before/after a refactor,
or to explain *why* a file is flagged.
@@ -34,16 +34,21 @@ not just *bigger*.
- `"coverage"` — surface coverage data when it's been ingested.
- `"trend"` — recent health snapshots + declining / predicted-decline signal.
+`include` adds blocks; `only=[...]` subtracts them.
+
## How to use the results
-1. For "what should I refactor?" → dashboard mode, then
+1. For "what should I refactor?" → dashboard mode, lead with `directive`, then
`get_health(targets=[worst files], include=["refactoring"])` and present the
- ranked suggestions, not just the scores.
-2. For a specific file → report the score, the top 2–3 marker findings, and
+ ranked plans, not just the scores.
+2. Rank by `weighted_deficit`, not `score` — the score floors at 1.0.
+3. For a specific file → report the score, the top 2–3 marker findings, and
what each one means in plain language. Avoid dumping the raw payload.
-3. Before editing a flagged file → cross-check `get_risk(targets=[...])`; a file
+4. Check `unresolved` before calling a file clean: a target listed there matched
+ nothing, and `not_indexed` means run `repowise update`.
+5. Before editing a flagged file → cross-check `get_risk(targets=[...])`; a file
that is both low-health *and* a churn hotspot deserves the most care.
-4. Untested-hotspot / coverage questions → tell the user coverage markers
+6. Untested-hotspot / coverage questions → tell the user coverage markers
light up once they ingest a report: `repowise coverage add cov.lcov`
(LCOV / Cobertura / Clover; a coverage.py `.coverage` also builds the
per-test map), then re-run `repowise health`.
diff --git a/plugins/codex/skills/code-health/SKILL.md b/plugins/codex/skills/code-health/SKILL.md
index 6d6b38175..6450bac95 100644
--- a/plugins/codex/skills/code-health/SKILL.md
+++ b/plugins/codex/skills/code-health/SKILL.md
@@ -14,7 +14,8 @@ not just *bigger*.
## Pick the mode by what you pass
-- **Dashboard** — `get_health()` (no targets): repo-level KPIs plus the
+- **Dashboard** — `get_health()` (no targets): a `directive` naming what to fix
+ first, then repo-level KPIs plus the
lowest-scoring files. Start here for "how healthy is this codebase?" or "what
should we clean up?".
- **Targeted** — `get_health(targets=["src/x.py", "src/y.py"])`: per-file score
@@ -29,16 +30,21 @@ not just *bigger*.
- `"coverage"` — surface coverage data when it's been ingested.
- `"trend"` — recent health snapshots + declining / predicted-decline signal.
+`include` adds blocks; `only=[...]` subtracts them.
+
## How to use the results
-1. For "what should I refactor?" → dashboard mode, then
+1. For "what should I refactor?" → dashboard mode, lead with `directive`, then
`get_health(targets=[worst files], include=["refactoring"])` and present the
ranked suggestions, not just the scores.
-2. For a specific file → report the score, the top 2–3 marker findings, and
+2. Rank by `weighted_deficit`, not `score` — the score floors at 1.0.
+3. For a specific file → report the score, the top 2–3 marker findings, and
what each one means in plain language. Avoid dumping the raw payload.
-3. Before editing a flagged file → cross-check `get_risk(targets=[...])`; a file
+4. Check `unresolved` before calling a file clean: a target listed there matched
+ nothing, and `not_indexed` means run `repowise update`.
+5. Before editing a flagged file → cross-check `get_risk(targets=[...])`; a file
that is both low-health *and* a churn hotspot deserves the most care.
-4. Untested-hotspot / coverage questions → tell the user coverage markers
+6. Untested-hotspot / coverage questions → tell the user coverage markers
light up once they ingest a report: `repowise coverage add cov.lcov`
(LCOV / Cobertura / Clover; a coverage.py `.coverage` also builds the
per-test map), then re-run `repowise health`.
diff --git a/tests/unit/server/mcp/test_health.py b/tests/unit/server/mcp/test_health.py
index 0f84883a5..cbe93102f 100644
--- a/tests/unit/server/mcp/test_health.py
+++ b/tests/unit/server/mcp/test_health.py
@@ -121,6 +121,147 @@ async def test_get_health_targeted(setup_mcp, health_data):
assert all(f["file_path"] == "src/auth/service.py" for f in result["findings"])
+async def test_get_health_names_unresolved_targets(setup_mcp, health_data):
+ """A target that matched nothing is named with a reason, never dropped."""
+ from repowise.server.mcp_server import get_health
+
+ result = await get_health(targets=["src/auth/service.py", "does/not/exist.py", "module:nope"])
+ assert [m["file_path"] for m in result["metrics"]] == ["src/auth/service.py"]
+ by_target = {u["target"]: u["reason"] for u in result["unresolved"]}
+ assert by_target == {
+ "does/not/exist.py": "no_such_path",
+ "module:nope": "no_such_module",
+ }
+ # A bad module name is correctable without a second dashboard round-trip.
+ assert set(result["known_modules"]) == {"auth", "db"}
+
+
+async def test_get_health_unmatched_module_stays_scoped(setup_mcp, health_data):
+ """A module target that resolves to nothing must not become a repo dashboard.
+
+ Falling through to dashboard mode answered a module-scoped question with
+ repo-wide numbers, which reads as scoped and is not.
+ """
+ from repowise.server.mcp_server import get_health
+
+ result = await get_health(targets=["module:nope"])
+ assert result["mode"] == "targets"
+ assert result["metrics"] == []
+ assert result["findings"] == []
+ assert result["unresolved"] == [{"target": "module:nope", "reason": "no_such_module"}]
+ # None of the repo-wide blocks leak into a scoped answer.
+ assert not {"kpis", "worst_files", "gap_analysis", "distribution"} & set(result)
+
+
+async def test_get_health_module_target_resolves_to_its_files(setup_mcp, health_data):
+ from repowise.server.mcp_server import get_health
+
+ result = await get_health(targets=["module:auth"])
+ assert [m["file_path"] for m in result["metrics"]] == ["src/auth/service.py"]
+ assert "unresolved" not in result
+
+
+async def test_get_health_findings_capped_with_honest_total(setup_mcp, health_data):
+ """limit governs findings too, and the total says what was cut."""
+ from repowise.server.mcp_server import get_health
+
+ result = await get_health(targets=["src/auth/service.py"], limit=2)
+ assert len(result["findings"]) == 2
+ assert result["findings_total"] == 4
+
+ dash = await get_health(limit=2)
+ assert len(dash["top_findings"]) == 2
+ assert dash["top_findings_total"] == 4
+
+
+async def test_get_health_modules_capped_with_honest_total(setup_mcp, health_data):
+ from repowise.server.mcp_server import get_health
+
+ result = await get_health(limit=1)
+ assert len(result["modules"]) == 1
+ assert result["modules_total"] == 2
+
+
+async def test_get_health_suggestion_text_emitted_once_as_legend(setup_mcp, health_data):
+ """Suggestion prose is keyed by biomarker type, so it ships once, not per row."""
+ from repowise.server.mcp_server import get_health
+
+ result = await get_health(include=["refactoring"])
+ rows = result["top_findings"]
+ assert rows, "fixture should produce findings"
+ assert not any("suggestion" in r for r in rows)
+ legend = result["suggestion_legend"]
+ # Exactly the types present — every row can be joined, nothing spare.
+ assert set(legend) == {r["biomarker_type"] for r in rows}
+ assert all(isinstance(v, str) and v for v in legend.values())
+
+
+async def test_get_health_dashboard_leads_with_a_directive(setup_mcp, health_data):
+ """The dashboard recommends, not just ranks — the D2 gap."""
+ from repowise.server.mcp_server import get_health
+
+ d = (await get_health())["directive"]
+ # Ranked by weighted_deficit, so the big low-scoring file leads.
+ assert d["fix_first"] == "src/auth/service.py"
+ assert d["reason"] == "authenticate has cyclomatic complexity 15"
+ assert d["recovers_points"] == 700 # (8.0 - 4.5) * 200
+ # 700 of the repo's 675 net gap points: the healthy file's surplus is
+ # credited in the denominator, so one file can exceed 100%.
+ assert d["share_of_repo_gap_pct"] == pytest.approx(103.7)
+ assert d["then"] == [] # only one below-target file in the fixture
+
+
+async def test_get_health_only_projects_the_response(setup_mcp, health_data):
+ """``only`` subtracts blocks; ``include`` could only ever add them."""
+ from repowise.server.mcp_server import get_health
+
+ full = await get_health()
+ assert len(full) > 4
+
+ slim = await get_health(only=["directive"])
+ # mode and _meta always survive — a response you cannot orient in is not
+ # a saving.
+ assert set(slim) == {"directive", "mode", "_meta"}
+ assert slim["directive"] == full["directive"]
+
+
+async def test_get_health_only_names_unknown_keys(setup_mcp, health_data):
+ """A misspelled projection is named, not silently answered with nothing."""
+ from repowise.server.mcp_server import get_health
+
+ result = await get_health(only=["directive", "kpiz"])
+ assert result["unknown_only_keys"] == ["kpiz"]
+ assert "directive" in result
+
+
+async def test_get_health_meta_stamps_when_health_last_ran(setup_mcp, health_data):
+ """Health is a separate pass from indexing and can lag it."""
+ from repowise.server.mcp_server import get_health
+
+ meta = (await get_health())["_meta"]
+ assert isinstance(meta["health_analyzed_at"], str)
+
+
+async def test_get_health_accepts_windows_separators(setup_mcp, health_data):
+ """A backslash path is the same file, not a no_such_path."""
+ from repowise.server.mcp_server import get_health
+
+ result = await get_health(targets=["src\\auth\\service.py"])
+ assert [m["file_path"] for m in result["metrics"]] == ["src/auth/service.py"]
+ assert "unresolved" not in result
+
+
@pytest.mark.asyncio
async def test_get_health_metric_carries_dominant_cause_and_magnitude(setup_mcp, health_data):
"""Metric rows lead with the worst finding + the pre-floor deduction sum."""