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 the directive promising a fix it does not have (#1358)
Raghav Chamadiya3eaed8dabc55
diff --git a/packages/server/src/repowise/server/mcp_server/tool_health.py b/packages/server/src/repowise/server/mcp_server/tool_health.pyindex 25b810a61..87f695ecc 100644--- a/packages/server/src/repowise/server/mcp_server/tool_health.py+++ b/packages/server/src/repowise/server/mcp_server/tool_health.py@@ -30,7 +30,11 @@ from repowise.core.persistence.crud import (sort_metrics_worst_first,)from repowise.core.persistence.database import get_session-from repowise.core.persistence.models import HealthFileMetric, HealthFinding+from repowise.core.persistence.models import (+ HealthFileMetric,+ HealthFinding,+ RefactoringSuggestion,+)from repowise.core.registry import mcp_tool_registry as mcpfrom repowise.server.mcp_server._helpers import (_get_exclude_spec,@@ -258,6 +262,8 @@ def _directive(by_leverage: list[HealthFileMetric],leads: dict[str, dict[str, Any]],gap_points: int,+ plan_biomarkers_by_path: dict[str, set[str]] | None = None,+ plan_count_by_path: dict[str, int] | None = None,) -> dict[str, Any] | None:"""The one file to fix first, and what fixing it buys.@@ -274,7 +280,15 @@ def _directive(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 {+ # Does anything behind ``plan_via`` actually address the cause named in+ # ``reason``? Plans carry the biomarker that produced them, and several+ # biomarkers have no detector at all — ``coverage_gradient`` above all, which+ # no plan kind can answer because none of them writes tests. Saying so beats+ # routing the caller to plans for a different problem with full confidence.+ lead_biomarker = lead.get("primary_biomarker")+ available = (plan_biomarkers_by_path or {}).get(top.file_path, set())+ addresses = bool(lead_biomarker) and lead_biomarker in available+ out = {"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,@@ -284,7 +298,38 @@ def _directive("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'])",+ "plan_addresses_reason": addresses,}+ # Only speak when there is a named cause to speak about. With no lead the+ # ``reason`` above already falls back to the bare score, and a note reading+ # "No stored plan addresses None" would be worse than silence.+ if not addresses and lead_biomarker:+ # Name the gap rather than leaving the caller to diff two biomarker+ # vocabularies. The three branches call for different next moves:+ # plans for other causes, plans with no recorded cause, or no plans.+ n_plans = (plan_count_by_path or {}).get(top.file_path, 0)+ if available:+ # Deliberately "target X, Y" rather than "the plans target only X, Y":+ # plans with an empty ``source_biomarker`` are counted in ``n_plans``+ # but cannot be named, so an exhaustive phrasing would be a claim+ # this read cannot support.+ out["plan_note"] = (+ f"No stored plan addresses {lead_biomarker!r}; the plans on this file "+ f"target {', '.join(sorted(available))}. Treat plan_via as related "+ f"cleanup, not the fix for reason."+ )+ elif n_plans:+ out["plan_note"] = (+ f"No stored plan addresses {lead_biomarker!r}; this file's {n_plans} "+ f"plan(s) record no source biomarker. Treat plan_via as related "+ f"cleanup, not the fix for reason."+ )+ else:+ out["plan_note"] = (+ f"No stored plan addresses {lead_biomarker!r}, and this file has no "+ f"plans at all. plan_via will return plans for other files."+ )+ return outdef _dimension_average(metrics: list[HealthFileMetric], attr: str) -> float | None:@@ -743,34 +788,78 @@ async def get_health(if "trend" in include_set or scoped:snapshots = await list_health_snapshots(session, repository.id, limit=20)+ # Dominant-cause lead per file. Targeted mode wants one per target, so+ # the reduction runs over the whole (small) scoped set. Dashboard mode+ # only ever prints a lead for the files it emits, so it reduces just+ # those rows instead of all ~10k — identical output, and+ # ``_leads_by_file`` measured ~148ms per call handed the full set.+ #+ # Computed inside the session because the directive's plan lookup below+ # needs ``by_leverage`` and has to run before the session closes.+ if scoped:+ by_leverage: list[HealthFileMetric] = []+ lead_source: list[Any] = lead_rows+ else:+ # 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. Computed+ # before the leads so the set of printed files is known.+ 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,+ )+ printed = {m.file_path for m in metric_rows[:limit]}+ printed |= {m.file_path for m in by_leverage[:limit]}+ lead_source = [r for r in lead_rows if r.file_path in printed]+ leads = _leads_by_file(lead_source)++ # Which biomarkers the stored plans for the directive's candidates+ # actually address. The directive names a file and a ``reason``, then+ # points at ``include=['refactoring']`` for the fix — but no detector+ # emits a plan for ``coverage_gradient``, which is the dominant cause on+ # most of this repo's worst files, so that promise was unkeepable and+ # silent about it. Read for the three named files only (``fix_first``+ # plus the two in ``then``), and only when the directive survives the+ # projection, so ``only=["directive"]`` stays the cheapest useful call.+ # Two columns, not whole rows: this reads one field, and the ORM row+ # carries ``plan_json`` + ``evidence_json`` + ``blast_radius_json``.+ # ``status == "open"`` mirrors ``get_refactoring_suggestions`` so the+ # directive cannot claim a plan the ``refactoring`` block would not+ # return. Candidate paths come from ``by_leverage`` ⊆ ``all_metrics``,+ # already exclude-filtered, so the ``IN`` needs no second pass through+ # the exclude spec.+ 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]]+ for path, source in (+ await session.execute(+ select(+ RefactoringSuggestion.file_path,+ RefactoringSuggestion.source_biomarker,+ ).where(+ RefactoringSuggestion.repository_id == repository.id,+ RefactoringSuggestion.status == "open",+ RefactoringSuggestion.file_path.in_(directive_paths),+ )+ )+ ).all():+ # Presence is counted separately from attribution. Every+ # ``split_file`` and ``break_cycle`` plan stores an empty+ # ``source_biomarker``, so keying "has plans" off the biomarker+ # set would report no plans on a file while the highest-leverage+ # plan kind sits on it.+ plan_count_by_path[path] = plan_count_by_path.get(path, 0) + 1+ if source:+ plan_biomarkers_by_path.setdefault(path, set()).add(source)+kpis = _compute_kpis(metric_rows if scoped else all_metrics,performance_findings=perf_findings_count,coverage=perf_coverage,)- # Dominant-cause lead per file. Targeted mode wants one per target, so the- # reduction runs over the whole (small) scoped set. Dashboard mode only ever- # prints a lead for the files it emits, so it reduces just those rows- # instead of all ~10k — identical output, and ``_leads_by_file`` measured- # ~148ms per call when handed the full set.- if scoped:- by_leverage: list[HealthFileMetric] = []- lead_source: list[Any] = lead_rows- else:- # 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. Computed before the leads so the- # set of printed files is known.- 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,- )- printed = {m.file_path for m in metric_rows[:limit]}- printed |= {m.file_path for m in by_leverage[:limit]}- lead_source = [r for r in lead_rows if r.file_path in printed]- leads = _leads_by_file(lead_source)if scoped:metric_payload: list[dict[str, Any]] = []@@ -835,7 +924,13 @@ async def get_health("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),+ "directive": _directive(+ by_leverage,+ leads,+ gap.get("weighted_gap_points") or 0,+ plan_biomarkers_by_path,+ plan_count_by_path,+ ),"kpis": kpis,"distribution": health_distribution(all_metrics),# Where the gap to Healthy concentrates — the "few files, not the@@ -892,6 +987,13 @@ async def get_health(m.file_path: round(max(HEALTHY_MIN - m.score, 0.0) * max(m.nloc, 1))for m in all_metrics}+ # A "plans matching the file's lead biomarker sort first" tiebreak was+ # tried here and removed: measured on this repo, 0 of the top 20 files+ # by deficit have any plan addressing their lead, so it could not move a+ # row inside the cap, while ``deficit`` rounds to an int and ties across+ # files — which would have let the boost reorder *between* files. The+ # honest fix for the mismatch is ``directive.plan_addresses_reason``,+ # which reports it rather than reshuffling around it.ranked = sorted(refactoring_rows,key=lambda r: (deficit_by_path.get(r.file_path, 0), r.impact_delta or 0.0),diff --git a/tests/unit/server/mcp/test_health.py b/tests/unit/server/mcp/test_health.pyindex 330e2c03a..898ff6374 100644--- a/tests/unit/server/mcp/test_health.py+++ b/tests/unit/server/mcp/test_health.py@@ -108,6 +108,160 @@ async def test_get_health_refactoring_capped_and_leverage_ranked(setup_mcp, healassert "refactoring_plans_total" in result+async def _seed_plans(session, rid, plans):+ """Store refactoring suggestions for the directive / ranking tests."""+ from repowise.core.persistence import crud++ await crud.save_refactoring_suggestions(+ session,+ rid,+ [+ {+ "refactoring_type": p.get("refactoring_type", "extract_method"),+ "file_path": p["file_path"],+ "target_symbol": p.get("target_symbol", "authenticate"),+ "line_start": 10,+ "line_end": 80,+ "plan": {"groups": []},+ "evidence": {},+ "impact_delta": p["impact_delta"],+ "effort_bucket": "S",+ "blast_radius": {"dependents_count": 0},+ "confidence": "high",+ "source_biomarker": p["source_biomarker"],+ }+ for p in plans+ ],+ )+ await session.commit()+++async def test_directive_admits_when_the_file_has_no_plans_at_all(setup_mcp, health_data):+ """``plan_via`` promised a fix for ``reason``; with no plans it cannot deliver one."""+ from repowise.server.mcp_server import get_health++ result = await get_health(only=["directive"])+ directive = result["directive"]+ # The seeded worst file leads with complex_method and carries no plans.+ assert directive["fix_first"] == "src/auth/service.py"+ assert directive["plan_addresses_reason"] is False+ assert "no plans at all" in directive["plan_note"]+++async def test_directive_admits_when_plans_target_a_different_biomarker(+ setup_mcp, health_data, session+):+ """The failure this ships for: plans exist, for a cause other than the one named."""+ from repowise.server.mcp_server import get_health++ await _seed_plans(+ session,+ health_data,+ [{"file_path": "src/auth/service.py", "source_biomarker": "dry_violation", "impact_delta": 1.0}],+ )++ directive = (await get_health(only=["directive"]))["directive"]+ assert directive["plan_addresses_reason"] is False+ # Names the gap on both sides: the unaddressed cause and what is on offer.+ assert "complex_method" in directive["plan_note"]+ assert "dry_violation" in directive["plan_note"]+++async def test_directive_confirms_when_a_plan_addresses_the_reason(+ setup_mcp, health_data, session+):+ """The true branch has to be reachable, or the flag is decoration."""+ from repowise.server.mcp_server import get_health++ await _seed_plans(+ session,+ health_data,+ [+ {+ "file_path": "src/auth/service.py",+ "source_biomarker": "complex_method",+ "impact_delta": 1.0,+ }+ ],+ )++ directive = (await get_health(only=["directive"]))["directive"]+ assert directive["plan_addresses_reason"] is True+ assert "plan_note" not in directive+++async def test_directive_does_not_claim_a_file_is_planless_over_an_unattributed_plan(+ setup_mcp, health_data, session+):+ """``split_file`` and ``break_cycle`` store an empty ``source_biomarker``.++ Keying "has plans" off the biomarker set would tell the caller this file has+ no plans while the highest-leverage plan kind sits on it — a false statement+ in the one field that exists to stop the tool over-promising.+ """+ from repowise.server.mcp_server import get_health++ await _seed_plans(+ session,+ health_data,+ [+ {+ "file_path": "src/auth/service.py",+ "refactoring_type": "split_file",+ "source_biomarker": "",+ "impact_delta": 2.0,+ }+ ],+ )++ directive = (await get_health(only=["directive"]))["directive"]+ assert directive["plan_addresses_reason"] is False+ assert "no plans at all" not in directive["plan_note"]+ assert "record no source biomarker" in directive["plan_note"]+++async def test_directive_stays_silent_when_the_file_has_no_named_cause(+ setup_mcp, health_data, session+):+ """No lead biomarker means nothing to report a plan gap *about*.++ ``reason`` already degrades to the bare score here, so a note would read+ "No stored plan addresses None".+ """+ from repowise.core.persistence.crud import save_health_metrics+ from repowise.server.mcp_server import get_health++ # Big and low-scoring, so it outranks the seeded worst file on leverage —+ # but with no findings at all, so it has no lead.+ await save_health_metrics(+ session,+ health_data,+ [+ {+ "file_path": "src/legacy/blob.py",+ "score": 2.0,+ "max_ccn": 1,+ "max_nesting": 1,+ "nloc": 5000,+ "has_test_file": False,+ "module": "legacy",+ }+ ],+ )+ await session.commit()++ directive = (await get_health(only=["directive"]))["directive"]+ assert directive["fix_first"] == "src/legacy/blob.py"+ assert directive["plan_addresses_reason"] is False+ assert "plan_note" not in directive+ assert "None" not in directive["reason"]++@pytest.mark.asyncioasync def test_get_health_targeted(setup_mcp, health_data):from repowise.server.mcp_server import get_health