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.

docs(health): say what the score counts, and stop the agent line reading inverted (#2201)

Raghav Chamadiyaa44d19a1a76f
diff --git a/docs/agent/MCP_TOOLS.md b/docs/agent/MCP_TOOLS.md
index 38ad21766..d80e06fce 100644
--- a/docs/agent/MCP_TOOLS.md
+++ b/docs/agent/MCP_TOOLS.md
@@ -920,6 +920,13 @@ block ranks and describes; this one recommends. Same role as `get_risk`'s
`recovers_points` remains an exact deprecated alias during the compatibility
window; `recovers_points_compatibility` names its replacement.
+**`watch` is context, not a task.** When the leading cause is history-derived —
+churn, ownership, co-change, prior fixes — the directive carries it under
+`watch` rather than in the fix path, because no edit to the file settles it.
+If *no* file has a code-shape lead, `next_action` says so instead of naming a
+file to change, so an agent is never sent to refactor a file whose deficit is
+its history.
+
**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`, `not_measured` → indexed, but carrying no stored
diff --git a/docs/architecture/code-health.md b/docs/architecture/code-health.md
index 16c204635..b748c5eb3 100644
--- a/docs/architecture/code-health.md
+++ b/docs/architecture/code-health.md
@@ -670,6 +670,9 @@ by the dashboard's file table.
| Column | Notes |
|---|---|
| `score` | 1.0–10.0 final |
+| `defect_score`, `maintainability_score`, `performance_score` | per-pillar; nullable |
+| `structure_deduction`, `history_deduction` | the two halves of the total deduction; nullable on rows written before the split. `counts=code_shape` rescores from `structure_deduction` alone, and a null pair is reported as unscored rather than counted as a ten |
+| `is_test` | stored, not re-derived per surface, so `scope` is one row filter everywhere; nullable on rows predating the column |
| `max_ccn`, `max_nesting`, `nloc` | aggregate function metrics |
| `duplication_pct` | percent of NLOC covered by clones; nullable |
| `has_test_file` | paired or heuristic |
@@ -759,8 +762,9 @@ Every response carries the standard `_meta` envelope via `build_meta()`.
## 13. REST surface
-`packages/server/src/repowise/server/routers/code_health.py`. All under
-`/api/repos/{repo_id}/health/`:
+`packages/server/src/repowise/server/routers/code_health/` — a package, one
+module per surface, sharing `scope.py`, `counts.py`, `file_filters.py` and
+`statuses.py`. All routes under `/api/repos/{repo_id}/health/`:
| Route | Returns |
|---|---|
@@ -771,13 +775,25 @@ Every response carries the standard `_meta` envelope via `build_meta()`.
| `GET /files/breakdown` | one file's metric + score breakdown + findings + suggestions + per-file `trend` + `signals` |
| `GET /files/trend` | one file's score-over-time series + current delta + `declining` flag (`?file_path=`) |
| `GET /trend` | repo KPI history + alerts + last-two-snapshot per-file deltas |
-| `GET /findings` | findings list (filterable by biomarker_type, severity, file_path) |
+| `GET /findings` | findings list, filterable by `biomarker_type`, `file_path`, `dimension`, `status` and severity (`severity` exact, or the `min_severity` floor). Performance is excluded unless asked for by name |
| `GET /coverage` | coverage summary + per-file rows |
| `POST /coverage` | ingest a coverage report (used by some CI integrations) |
-| `GET /refactoring-targets` | ranked by `total_impact / effort_bucket` |
+| `GET /refactoring-targets` | the work queue: files carrying findings, ranked by `total_impact / effort_bucket`. Takes the findings filters plus `search`, `module` and the `only_hotspots` / `only_untested` / `only_failing` row filters, pages by `limit` + `offset`, and returns `total` with `finding_total` beside it. Impact counts open findings only, so dismissing work moves a file down |
| `GET /churn-complexity` | churn × complexity scatter points (one per churned file: `commit_count_90d`, `max_ccn`, `nloc`, `score`, `churn_percentile`) |
| `GET /modules` | NLOC-weighted module rollup table |
+`scope` and `counts` are accepted by every route whose figures they could
+change, parsed by the shared `ScopeQuery` / `CountsQuery`, and echoed back. An
+unrecognized value falls back to the default rather than answering a different
+question under the name that was asked for.
+
+`counts=code_shape` is a projection over the two stored deduction columns, not
+a rescore: it re-derives each score from `structure_deduction`, drops
+history-derived findings from the row sets so a list cannot sum past the figure
+above it, and recomputes `total` and every ranking afterwards. Rows with no
+stored split are removed and counted in `unscored_files`. Nothing is written
+back.
+
Auth is the standard `verify_api_key` dependency from
`server/deps.py`.
diff --git a/docs/layers/CODE_HEALTH.md b/docs/layers/CODE_HEALTH.md
index 460f2945f..741fb8aa3 100644
--- a/docs/layers/CODE_HEALTH.md
+++ b/docs/layers/CODE_HEALTH.md
@@ -147,6 +147,15 @@ rather than truncated, so each finding's reported impact stays linear and
attributable — you can always explain exactly why a file scored what it scored.
The final score is clamped to `[1.0, 10.0]`.
+**Organizational is the largest cap, and it is the git-derived one.** Churn,
+ownership, co-change, congestion and prior fixes describe what a file has been
+*through*, not what its code is like — and they rise as a file is worked on. So
+a week of genuine refactoring can lower a file's structural deduction while its
+history deduction climbs, and the headline barely moves. Each file therefore
+stores its deduction as two numbers, `structure_deduction` and
+`history_deduction`, which sum to the total. Nothing is hidden: the split is on
+every metric row, and the Counts control below reads it back.
+
Three repo-level KPIs: **Hotspot Health** (NLOC-weighted average over files the
git layer classifies as hotspots), **Average Health** (NLOC-weighted over all
files), and **Worst Performer**.
@@ -181,6 +190,42 @@ every recommendation.
The bands are defined once in core (`analysis/health/grading.py`) and mirrored
in `@repowise-dev/types`, with a parity test on each side.
+### What the score counts
+
+Two controls decide which files a figure describes and which half of the
+deduction it counts. Both reach the CLI, MCP and every page, and both are
+echoed on the response, so a number always states what it is.
+
+| Control | Values | What it does |
+|---|---|---|
+| **Scope** | `all` (default) · `production` | Which files are in the population. Non-code files are never scored. |
+| **Counts** | `everything` (default) · `code_shape` | Whether the git-derived half of the deduction counts. |
+
+```bash
+repowise health --scope production # exclude tests
+repowise health --counts code_shape # the code-shape reading
+```
+
+```python
+get_health(scope="production", counts="code_shape")
+```
+
+**`code_shape` answers "is my code getting better".** It subtracts
+`history_deduction` and rescores from what is left, so a week of refactoring
+shows up as the improvement it was rather than being masked by the churn that
+the work itself created. It is arithmetic over the two stored columns, not a
+second scoring pass: history findings are dropped rather than re-weighted, and
+a file with no stored split is reported in `unscored_files` rather than counted
+as a ten.
+
+**`production` lowers the headline**, which surprises people: test files
+generally score higher than the code they cover, so removing them removes the
+easy end of the distribution. Nothing was found; the population changed.
+
+`everything` remains the calibrated number every accuracy claim on this page is
+about, and the health badge always reports it — so a projected reading can
+never be mistaken for the published one.
+
## How the weights were calibrated
This is the part that separates "we wrote some heuristics" from "we measured
@@ -524,36 +569,6 @@ never silently change what those numbers mean.
`repowise update` re-scores only changed files. Findings and metrics for
unchanged files stay put; no nightly full re-index.
-## Comparison
-
-The honest dividing line: each tool below has a rules engine and a definitional
-rating. Repowise predicts which files harbor the next bug and validates that
-forward in time against a labeled corpus.
-
-| Capability | Repowise | CodeScene | SonarQube | Qlty¹ | Codacy |
-|---|---|---|---|---|---|
-| Per-file health score | ✅ 1-10 | ✅ 1-10 | ⚠️ A-E from rule counts | ✅ A-F | ✅ A-F |
-| Score uses git / behavioral signals | ✅ | ✅ its core | ❌ static rules only | ⚠️ churn vs complexity | ❌ |
-| Cross-file / call-graph analysis | ✅ interprocedural | ⚠️ git temporal coupling | ⚠️ taint, security only | ❌ file-local | ❌ file-local |
-| Defect-validated against a bug corpus | ✅ AUC 0.737, held-out 0.76-0.78 | ⚠️ "Code Red" study, no per-file AUC | ❌ | ❌ | ❌ |
-| Static performance risk across the call graph | ✅ | ❌ | ❌ | ❌ | ❌ |
-| Test-coverage ingestion | ✅ | ✅ | ⚠️ imports reports | ✅ | ✅ |
-| Cross-file refactoring plans | ✅ + opt-in codegen | ⚠️ 5 in-function smells | ❌ | ❌ | ❌ |
-| Trend tracking + declining alerts | ✅ | ✅ | ✅ quality gates | ✅ | ✅ |
-| MCP / agent integration | ✅ | ✅ | ✅ | ❌ | ✅ |
-| Security scanning | ⚠️ separate layer | ⚠️ secondary | ✅ strong | ❌ | ✅ full suite |
-| License | ✅ AGPL-3.0 | ⚠️ proprietary, on-prem Docker | ⚠️ Community free, paid by LOC | ⚠️ free OSS, paid teams | ⚠️ free OSS, paid per dev |
-
-¹ Code Climate Quality was spun out as Qlty Software in November 2024.
-
-**What each does that we do not.** **SonarQube** has the broadest security
-scanning, the widest language coverage, and the most adopted merge-gate model.
-**CodeScene** is the most mature behavioral-analysis product — knowledge maps,
-off-boarding simulation, 28+ languages — and holds the only published business-
-impact study in this group, which we could not replicate on open data.
-**Qlty** defined the churn-vs-complexity quadrant. **Codacy** has the widest
-security suite of the four and polished PR automation.
-
## See also
- [`docs/architecture/code-health.md`](../architecture/code-health.md): internals,
diff --git a/docs/reference/CLI_REFERENCE.md b/docs/reference/CLI_REFERENCE.md
index 09a618d5a..1a007becf 100644
--- a/docs/reference/CLI_REFERENCE.md
+++ b/docs/reference/CLI_REFERENCE.md
@@ -926,6 +926,8 @@ Compute per-file code-health scores from 49 deterministic detectors (McCabe comp
|------|-------------|
| `--file <path>` | Deep-dive a single file (relative path) |
| `--module <prefix>` | Restrict the report to files whose path starts with this prefix |
+| `--scope` | `all` (default) or `production`. Which files every figure describes. Tests score higher than production code, so narrowing lowers the number without a defect being found. |
+| `--counts` | `everything` (default) or `code_shape`. `code_shape` drops the git-derived half of the deduction, which rises as a file is worked on — the reading that answers whether the code itself is improving. |
| `--refactoring-targets` | Print structured, graph-aware refactoring plans (Extract Class / Helper / Move Method / Break Cycle), ranked `impact × centrality × blast radius`. See [REFACTORING.md](../layers/REFACTORING.md) |
| `--generate-code <selector>` | Generate an actual refactoring patch for one target. The only `health` flag that calls an LLM; needs a configured provider. |
| `--trend` | Print the last 10 health snapshots + any active alerts (declining / predicted decline) |
@@ -942,6 +944,7 @@ repowise health --module packages/server # restrict to a directory
repowise health --refactoring-targets # ranked by impact / effort
repowise health --generate-code packages/server/app.py::handler # LLM patch for one target
repowise health --trend # snapshot history + alerts
+repowise health --counts code_shape # ignore the git-derived half
repowise coverage add coverage.lcov # ingest coverage, then:
repowise health
repowise health --format json | jq .kpis # machine-readable
diff --git a/packages/core/src/repowise/core/generation/editor_files/data.py b/packages/core/src/repowise/core/generation/editor_files/data.py
index 02176b4bb..c8555c208 100644
--- a/packages/core/src/repowise/core/generation/editor_files/data.py
+++ b/packages/core/src/repowise/core/generation/editor_files/data.py
@@ -66,6 +66,10 @@ class CodeHealthBlock:
average_health: float
worst_score: float
worst_path: str
+ # The band word for ``average_health``, so the line reads the same
+ # direction as every other surface: a bare "6.9/10" beside a risk-shaped
+ # label is the one reading that inverts.
+ band: str = ""
# ``None`` until two snapshots exist; the section then omits the label.
hotspot_trend: str | None = None
# Maintainability pillar headline (NLOC-weighted average over the per-file
diff --git a/packages/core/src/repowise/core/generation/editor_files/fetcher.py b/packages/core/src/repowise/core/generation/editor_files/fetcher.py
index 32fca0a80..1275f2e93 100644
--- a/packages/core/src/repowise/core/generation/editor_files/fetcher.py
+++ b/packages/core/src/repowise/core/generation/editor_files/fetcher.py
@@ -15,6 +15,7 @@ from pathlib import Path
from sqlalchemy import func, select
from sqlalchemy.ext.asyncio import AsyncSession
+from repowise.core.analysis.health.grading import BAND_LABEL, band_for
from repowise.core.analysis.health.perf.coverage import coverage_for_metrics
from repowise.core.analysis.health.scoring import hotspot_health, nloc_weighted_score
from repowise.core.analysis.health.trends import DECLINE_LOOKBACK, hotspot_trend
@@ -450,6 +451,7 @@ class EditorFileDataFetcher:
return CodeHealthBlock(
hotspot_health=round(hotspot_for_claude_md, 2),
average_health=round(avg, 2),
+ band=BAND_LABEL[band_for(round(avg, 2))],
worst_score=round(worst.score, 2),
worst_path=worst.file_path,
hotspot_trend=hotspot_trend(history),
diff --git a/packages/core/src/repowise/core/generation/templates/agents_md.j2 b/packages/core/src/repowise/core/generation/templates/agents_md.j2
index 65133d9bb..cb15e38e5 100644
--- a/packages/core/src/repowise/core/generation/templates/agents_md.j2
+++ b/packages/core/src/repowise/core/generation/templates/agents_md.j2
@@ -43,7 +43,7 @@ Indexed by [Repowise](https://repowise.dev). Last indexed: {{ data.indexed_at }}
{% if data.code_health %}
### Code health
-Three co-equal signals: defect risk {{ data.code_health.average_health }}/10 avg, hotspot health {{ data.code_health.hotspot_health }}/10{% if data.code_health.hotspot_trend %} ({{ data.code_health.hotspot_trend }}){% endif %}, worst `{{ data.code_health.worst_path }}` at {{ data.code_health.worst_score }}/10{% if data.code_health.maintainability_average is not none %} · maintainability {{ data.code_health.maintainability_average }}/10{% endif %}{% if data.code_health.performance_average is not none %} · performance risk {{ data.code_health.performance_findings }} open static I/O-in-loop / N+1 finding{{ 's' if data.code_health.performance_findings != 1 else '' }}{% endif %}. Detail: `get_health()`.
+Three co-equal signals: code health {{ data.code_health.average_health }}/10 avg{% if data.code_health.band %} ({{ data.code_health.band }}){% endif %}, hotspot health {{ data.code_health.hotspot_health }}/10{% if data.code_health.hotspot_trend %} ({{ data.code_health.hotspot_trend }}){% endif %}, worst `{{ data.code_health.worst_path }}` at {{ data.code_health.worst_score }}/10{% if data.code_health.maintainability_average is not none %} · maintainability {{ data.code_health.maintainability_average }}/10{% endif %}{% if data.code_health.performance_average is not none %} · performance risk {{ data.code_health.performance_findings }} open static I/O-in-loop / N+1 finding{{ 's' if data.code_health.performance_findings != 1 else '' }}{% endif %}. Detail: `get_health()`.
{% if data.code_health.critical_biomarkers %}
Critical files:
diff --git a/packages/core/src/repowise/core/generation/templates/claude_md.j2 b/packages/core/src/repowise/core/generation/templates/claude_md.j2
index 9677a62b7..59fddbedb 100644
--- a/packages/core/src/repowise/core/generation/templates/claude_md.j2
+++ b/packages/core/src/repowise/core/generation/templates/claude_md.j2
@@ -43,7 +43,7 @@ Indexed by [Repowise](https://repowise.dev). Last indexed: {{ data.indexed_at }}
{% if data.code_health %}
### Code health
-Three co-equal signals: defect risk {{ data.code_health.average_health }}/10 avg, hotspot health {{ data.code_health.hotspot_health }}/10{% if data.code_health.hotspot_trend %} ({{ data.code_health.hotspot_trend }}){% endif %}, worst `{{ data.code_health.worst_path }}` at {{ data.code_health.worst_score }}/10{% if data.code_health.maintainability_average is not none %} · maintainability {{ data.code_health.maintainability_average }}/10{% endif %}{% if data.code_health.performance_average is not none %} · performance risk {{ data.code_health.performance_findings }} open static I/O-in-loop / N+1 finding{{ 's' if data.code_health.performance_findings != 1 else '' }}{% endif %}. Detail: `get_health()`.
+Three co-equal signals: code health {{ data.code_health.average_health }}/10 avg{% if data.code_health.band %} ({{ data.code_health.band }}){% endif %}, hotspot health {{ data.code_health.hotspot_health }}/10{% if data.code_health.hotspot_trend %} ({{ data.code_health.hotspot_trend }}){% endif %}, worst `{{ data.code_health.worst_path }}` at {{ data.code_health.worst_score }}/10{% if data.code_health.maintainability_average is not none %} · maintainability {{ data.code_health.maintainability_average }}/10{% endif %}{% if data.code_health.performance_average is not none %} · performance risk {{ data.code_health.performance_findings }} open static I/O-in-loop / N+1 finding{{ 's' if data.code_health.performance_findings != 1 else '' }}{% endif %}. Detail: `get_health()`.
{% if data.code_health.critical_biomarkers %}
Critical files:
diff --git a/tests/unit/generation/test_editor_file_base.py b/tests/unit/generation/test_editor_file_base.py
index fde519ce6..6a63844a2 100644
--- a/tests/unit/generation/test_editor_file_base.py
+++ b/tests/unit/generation/test_editor_file_base.py
@@ -71,10 +71,12 @@ def _health_block(
performance_average: float | None = None,
performance_findings: int = 0,
performance_coverage_pct: float | None = None,
+ band: str = "Good",
) -> CodeHealthBlock:
return CodeHealthBlock(
hotspot_health=5.0,
average_health=7.5,
+ band=band,
worst_score=2.0,
worst_path="src/bad.py",
maintainability_average=maintainability_average,
@@ -84,6 +86,30 @@ def _health_block(
)
+def test_the_headline_reads_the_same_direction_as_every_other_surface(gen):
+ """A score out of ten beside a risk-shaped label reads inverted.
+
+ The CLI prints "Code health: 7.5/10 [Good]". The generated file is the one
+ an agent reads without a page around it, so it carries the same label and
+ the same band word rather than a bare number.
+ """
+ import dataclasses
+
+ data = dataclasses.replace(_minimal_data(), code_health=_health_block(6.4))
+ result = gen.render(data)
+ assert "code health 7.5/10 avg (Good)" in result
+ assert "defect risk 7.5" not in result
+
+
+def test_the_headline_drops_the_band_when_it_is_unknown(gen):
+ import dataclasses
+
+ data = dataclasses.replace(_minimal_data(), code_health=_health_block(6.4, band=""))
+ result = gen.render(data)
+ assert "code health 7.5/10 avg," in result
+ assert "avg ()" not in result
+
+
def test_render_surfaces_maintainability_when_present(gen):
import dataclasses