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
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.mdindex 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 compatibilitywindow; `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 isnamed in `unresolved` with a reason (`not_indexed` → run `repowise update`,`no_such_path`, `excluded`, `not_measured` → indexed, but carrying no storeddiff --git a/docs/architecture/code-health.md b/docs/architecture/code-health.mdindex 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.mdindex 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 andattributable — 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 thegit layer classifies as hotspots), **Average Health** (NLOC-weighted over allfiles), and **Worst Performer**.@@ -181,6 +190,42 @@ every recommendation.The bands are defined once in core (`analysis/health/grading.py`) and mirroredin `@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 calibratedThis 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 forunchanged 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.mdindex 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 directoryrepowise health --refactoring-targets # ranked by impact / effortrepowise health --generate-code packages/server/app.py::handler # LLM patch for one targetrepowise health --trend # snapshot history + alerts+repowise health --counts code_shape # ignore the git-derived halfrepowise coverage add coverage.lcov # ingest coverage, then:repowise healthrepowise health --format json | jq .kpis # machine-readablediff --git a/packages/core/src/repowise/core/generation/editor_files/data.py b/packages/core/src/repowise/core/generation/editor_files/data.pyindex 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: floatworst_score: floatworst_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-filediff --git a/packages/core/src/repowise/core/generation/editor_files/fetcher.py b/packages/core/src/repowise/core/generation/editor_files/fetcher.pyindex 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 Pathfrom sqlalchemy import func, selectfrom sqlalchemy.ext.asyncio import AsyncSession+from repowise.core.analysis.health.grading import BAND_LABEL, band_forfrom repowise.core.analysis.health.perf.coverage import coverage_for_metricsfrom repowise.core.analysis.health.scoring import hotspot_health, nloc_weighted_scorefrom 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.j2index 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.j2index 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.pyindex 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