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
feat(health): surface NLOC-weighting and per-file leverage in get_health (#719)
Raghav Chamadiya79fa4076db1f
diff --git a/docs/MCP_TOOLS.md b/docs/MCP_TOOLS.mdindex 6561dda64..9595d8eb3 100644--- a/docs/MCP_TOOLS.md+++ b/docs/MCP_TOOLS.md@@ -447,6 +447,23 @@ Targeted mode returns per-file marker findings with severity, per-dimensionscores, and the score breakdown. Each finding carries a `dimension`(`defect` / `maintainability` / `performance`).+**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:++- `kpis.average_health_unweighted` is the plain file mean and+ `kpis.average_health_weighting` is `"nloc"`. When the weighted and unweighted+ numbers diverge, the gap is telling you to chase *big* files, not the long tail.+- `gap_analysis` (dashboard mode) reports the net weighted points the average must+ recover to reach the Healthy floor (8.0), how many files sit below it, and how+ few of them carry the whole gap (`files_to_reach_target`) or half of it+ (`files_for_half_gap`). This reframes a repo-wide number as a short worklist.+- Every metric row carries `weighted_deficit = (8 - score) × nloc`: how much the+ repo headline recovers if that file reaches 8.0. `high_leverage_files`+ (dashboard mode) is the top-N ranked by it — distinct from `worst_files`, which+ sorts by raw score and ranks a 30-line file at 1.0 equal to a 1,200-line file at+ 1.0 that moves the average ~40x more.+The opt-in enrichments:- **`accuracy`** returns a `defect_accuracy` block: of the K least-healthy files, how@@ -464,8 +481,11 @@ The opt-in enrichments:strings): `extract_class` (the cohesion `groups` to split into), `extract_helper`(clone `occurrences` + `suggested_site`), `move_method` (`{method, from_class,to_class}`), and `break_cycle` (the import `cut_edges`). Each plan carries its- `evidence`, `impact_delta`, `effort_bucket`, and `blast_radius`, ranked- `impact × centrality × blast radius`. Full shapes in+ `evidence`, `impact_delta`, `effort_bucket`, and `blast_radius`. The list is+ capped to `limit` and ranked file-leverage-first (by the file's+ `weighted_deficit`, then per-plan impact), so 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/REFACTORING.md`](REFACTORING.md).- **dimension filter** narrows the returned findings to one pillar. Pair with`"biomarkers"` for the full (uncapped) finding set, e.g.@@ -480,7 +500,7 @@ hotspots.**Example calls:**```-get_health()+get_health() # kpis, gap_analysis, worst + high_leverage filesget_health(include=["accuracy", "churn_complexity"])get_health(include=["biomarkers", "performance"]) # only performance findingsget_health(targets=["src/api/server.py"], include=["signals"])diff --git a/packages/server/src/repowise/server/mcp_server/tool_health.py b/packages/server/src/repowise/server/mcp_server/tool_health.pyindex d1a2077e1..17293ed8b 100644--- a/packages/server/src/repowise/server/mcp_server/tool_health.py+++ b/packages/server/src/repowise/server/mcp_server/tool_health.py@@ -10,7 +10,7 @@ from sqlalchemy import selectfrom repowise.core.analysis.health.churn_complexity import churn_complexity_pointsfrom repowise.core.analysis.health.defect_accuracy import compute_defect_accuracy-from repowise.core.analysis.health.grading import band_for+from repowise.core.analysis.health.grading import HEALTHY_MIN, band_forfrom repowise.core.analysis.health.grading import distribution as health_distributionfrom repowise.core.analysis.health.perf.coverage import PerfCoverage, coverage_for_metricsfrom repowise.core.analysis.health.signals import file_signals@@ -131,6 +131,12 @@ def _serialize_metric(m: HealthFileMetric, lead: dict[str, Any] | None = None) -"line_coverage_pct": m.line_coverage_pct,"branch_coverage_pct": m.branch_coverage_pct,"module": m.module,+ # Leverage: NLOC-weighted points this file drags below the Healthy band+ # (``(8.0 - score) * nloc``, 0 once healthy). This is how much the repo+ # headline recovers if the file reaches 8.0, so ranking by it — not by+ # raw score — points at the files that actually move the average. A tiny+ # 1.0 file and a 1200-line 1.0 file score the same but differ 40x here.+ "weighted_deficit": round(max(HEALTHY_MIN - m.score, 0.0) * max(m.nloc, 1)),# Per-dimension scores from the three-signal split. ``score`` is the# overall surfaced number (== ``defect_score`` for now);# ``performance_score`` is computed but not yet surfaced as its own pillar.@@ -212,6 +218,53 @@ def _dimension_average(metrics: list[HealthFileMetric], attr: str) -> float | Noreturn round(sum(getattr(m, attr) * max(m.nloc, 1) for m in scored) / total_nloc, 2)+def _gap_analysis(metrics: list[HealthFileMetric]) -> dict[str, Any]:+ """How few files must reach 8.0 for the *weighted average* to reach 8.0.++ Answers what the bare KPI cannot: the NLOC-weighted average is held down by a+ *few large low-scoring files*, not the long tail. The gap here is the **net**+ points the average needs (``8.0 * total_nloc - Σ score*nloc``) — healthy files+ already sit above 8.0 and cushion it, so this is smaller than the gross+ all-files-healthy deficit and is the number that matches the goal "move the+ average". ``files_to_reach_target`` is the punchline: lift the worst-deficit N+ files to 8.0 and the headline crosses 8.0. Pure over the metrics in hand.+ """+ total_nloc = sum(max(m.nloc, 1) for m in metrics)+ weighted_sum = sum(m.score * max(m.nloc, 1) for m in metrics)+ net_gap = HEALTHY_MIN * total_nloc - weighted_sum+ below = sorted(+ (max(HEALTHY_MIN - m.score, 0.0) * max(m.nloc, 1) for m in metrics if m.score < HEALTHY_MIN),+ reverse=True,+ )+ if net_gap <= 0 or not below:+ return {+ "target_score": HEALTHY_MIN,+ "weighted_gap_points": 0,+ "files_below_target": len(below),+ "files_to_reach_target": 0,+ "files_for_half_gap": 0,+ }++ def _files_for(points: float) -> int:+ acc = 0.0+ for i, d in enumerate(below, 1):+ acc += d+ if acc >= points:+ return i+ return len(below)++ return {+ "target_score": HEALTHY_MIN,+ # Net weighted points the average must recover to reach 8.0.+ "weighted_gap_points": round(net_gap),+ "files_below_target": len(below),+ # The reframe: lift this many worst-deficit files to 8.0 and the weighted+ # average reaches 8.0; half that gap needs even fewer.+ "files_to_reach_target": _files_for(net_gap),+ "files_for_half_gap": _files_for(0.5 * net_gap),+ }++def _perf_kpis(performance_findings: int, coverage: PerfCoverage | None) -> dict[str, Any]:"""The honest performance headline: finding count + density + coverage.@@ -257,6 +310,12 @@ def _compute_kpis(return {"file_count": len(metrics),"average_health": round(avg, 2),+ # NLOC-weighted (``average_health``) vs plain file mean. When these+ # diverge, a few large low-scoring files are holding the headline down —+ # the weighted number is what the dashboard/badge surface, and the gap+ # between the two is the signal to chase big files, not the long tail.+ "average_health_weighting": "nloc",+ "average_health_unweighted": round(sum(m.score for m in metrics) / len(metrics), 2),"band": band_for(round(avg, 2)),"worst_performer_path": worst.file_path,"worst_performer_score": round(worst.score, 2),@@ -282,6 +341,17 @@ async def get_health(lowest-scoring files. Targeted mode returns per-file findings andmetrics for each path in ``targets``.+ Leverage, not just lowness: ``average_health`` is NLOC-weighted (the number+ the badge/dashboard surface), so a few large low files hold it down;+ ``kpis.average_health_unweighted`` is the plain file mean, and a gap between+ the two says "chase big files". ``gap_analysis`` reports the weighted points+ to reach an all-Healthy floor and how few files carry 50% / 90% of it;+ ``high_leverage_files`` ranks files by ``weighted_deficit`` (``(8 - score) *+ nloc``, on every metric row) — the ones that actually move the average, as+ opposed to ``worst_files`` which sorts by raw score. ``refactoring_plans``+ is capped to ``limit`` and ranked file-leverage-first (``refactoring_plans_total``+ reports the full count).+Markers in v1: ``brain_method``, ``nested_complexity``,``complex_method``. Phase 2 adds coverage markers; Phase 3 addsduplication + organizational markers.@@ -505,13 +575,29 @@ async def get_health(# Dashboard mode — top-N worst files + headline findings + the# per-module rollup so the overview page doesn't need a second# round-trip.+ # Leverage view: files ranked by NLOC-weighted deficit (how much each+ # drags the headline), not by raw score. Distinct from worst_files —+ # a big warning-band file outranks a tiny alert-band one here because+ # fixing it moves the average far more. Same serializer, so every row+ # carries weighted_deficit for the caller to sort on further.+ by_leverage = sorted(+ (m for m in all_metrics if m.score < HEALTHY_MIN),+ key=lambda m: max(HEALTHY_MIN - m.score, 0.0) * max(m.nloc, 1),+ reverse=True,+ )result = {"mode": "dashboard","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),"worst_files": [_serialize_metric(m, leads.get(m.file_path)) for m in metric_rows[:limit]],+ "high_leverage_files": [+ _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),}@@ -533,7 +619,31 @@ async def get_health(# Structured refactoring plans (the concrete split groups / evidence /# blast radius) for detectors that have one — the upgrade over the old# prose-string suggestions.- result["refactoring_plans"] = [_serialize_refactoring(r) for r in refactoring_rows]+ #+ # Rank by the *file's* weighted deficit first, per-plan impact_delta+ # second, and cap to ``limit``. Two reasons: an un-capped dump is a+ # thousands-of-plans firehose that blows the token budget, and a pure+ # impact_delta sort buries the highest-leverage plans — a Split File on a+ # 1200-line hotspot recovers the most repo-average yet can carry a modest+ # per-file delta, so file leverage has to lead. ``refactoring_plans_total``+ # keeps the truncation honest.+ deficit_by_path = {+ m.file_path: round(max(HEALTHY_MIN - m.score, 0.0) * max(m.nloc, 1))+ for m in all_metrics+ }+ ranked = sorted(+ refactoring_rows,+ key=lambda r: (deficit_by_path.get(r.file_path, 0), r.impact_delta or 0.0),+ reverse=True,+ )+ result["refactoring_plans"] = [+ {+ **_serialize_refactoring(r),+ "file_weighted_deficit": deficit_by_path.get(r.file_path, 0),+ }+ 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.diff --git a/tests/unit/server/mcp/test_health.py b/tests/unit/server/mcp/test_health.pyindex ed270cc54..0f84883a5 100644--- a/tests/unit/server/mcp/test_health.py+++ b/tests/unit/server/mcp/test_health.py@@ -62,6 +62,52 @@ async def test_get_health_dashboard_surfaces_performance(setup_mcp, health_data)]+async def test_get_health_dashboard_surfaces_leverage(setup_mcp, health_data):+ """Leverage view: which files move the NLOC-weighted headline, not just which score low."""+ from repowise.server.mcp_server import get_health++ result = await get_health()+ kpis = result["kpis"]+ # Weighted (4.5*200 + 8.5*50)/250 = 5.3 vs plain mean (4.5 + 8.5)/2 = 6.5:+ # the divergence is the "a big low file holds the headline down" signal.+ assert kpis["average_health"] == 5.3+ assert kpis["average_health_unweighted"] == 6.5+ assert kpis["average_health_weighting"] == "nloc"++ # Per-file leverage: (8 - score) * nloc, 0 once healthy.+ worst = next(m for m in result["worst_files"] if m["file_path"] == "src/auth/service.py")+ assert worst["weighted_deficit"] == 700 # (8.0 - 4.5) * 200+ healthy = next(m for m in result["worst_files"] if m["file_path"] == "src/db/models.py")+ assert healthy["weighted_deficit"] == 0 # score 8.5 >= Healthy floor++ # high_leverage_files excludes healthy files and leads with the biggest drag.+ hi = result["high_leverage_files"]+ assert [m["file_path"] for m in hi] == ["src/auth/service.py"]++ # gap_analysis: net points to move the *average* to 8.0 credits the healthy+ # file's surplus, so it's 8*250 - (4.5*200 + 8.5*50) = 2000 - 1325 = 675,+ # all sitting in one below-target file.+ gap = result["gap_analysis"]+ assert gap["target_score"] == 8.0+ assert gap["weighted_gap_points"] == 675+ assert gap["files_below_target"] == 1+ assert gap["files_to_reach_target"] == 1+ assert gap["files_for_half_gap"] == 1+++async def test_get_health_refactoring_capped_and_leverage_ranked(setup_mcp, health_data):+ """refactoring_plans is bounded by limit and reports the honest total."""+ from repowise.server.mcp_server import get_health++ result = await get_health(include=["refactoring"], limit=5)+ assert "refactoring_plans" in result+ assert len(result["refactoring_plans"]) <= 5+ # Honest truncation signal is always present when refactoring is requested.+ assert "refactoring_plans_total" in result++@pytest.mark.asyncioasync def test_get_health_targeted(setup_mcp, health_data):from repowise.server.mcp_server import get_health