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): report production or all code, and name a cause you can fix (#2154)
Raghav Chamadiyaa92ea0b59652
diff --git a/packages/cli/src/repowise/cli/commands/health_cmd/command.py b/packages/cli/src/repowise/cli/commands/health_cmd/command.pyindex d2cdd93d0..57b9d7a4b 100644--- a/packages/cli/src/repowise/cli/commands/health_cmd/command.py+++ b/packages/cli/src/repowise/cli/commands/health_cmd/command.py@@ -23,6 +23,8 @@ from repowise.cli.helpers import (run_async,silence_logs_for_machine_output,)+from repowise.core.analysis.health.scope import DEFAULT_SCOPE, SCOPES, parse_scope+from repowise.core.analysis.health.scoring import compute_kpisfrom .codegen import _generate_refactoring_codefrom .persist import _load_persisted_coverage_map, _load_recommendations, _persist_health@@ -32,6 +34,7 @@ from .summary import (_render_defect_accuracy_line,_render_distribution_line,_render_performance_section,+ _render_split_line,)from .trends import _render_trend@@ -87,6 +90,15 @@ from .trends import _render_trenddefault=None,help="Restrict the report to files whose path starts with this prefix.",)+ "--scope",+ default=DEFAULT_SCOPE,+ type=click.Choice(list(SCOPES)),+ help=(+ "Which files to report on. Tests score higher than production code, "+ "so 'production' lowers every figure without a defect being found."+ ),+)@click.option("--trend","trend_view",@@ -117,6 +129,7 @@ def health_command(refactoring_targets: bool,generate_code: str | None,module_filter: str | None,+ scope: str,trend_view: bool,badge_view: bool,verbose: bool,@@ -266,13 +279,24 @@ def health_command(metrics = [m for m in metrics if m.file_path == file_filter]if module_filter:metrics = [m for m in metrics if m.file_path.startswith(module_filter)]+ if parse_scope(scope) == "production":+ metrics = [m for m in metrics if not m.is_test]+ # Every figure, not just the table: the flag says production, so the+ # headline, the hotspot number, the worst performer and the+ # distribution all have to describe that population too.+ report.kpis = compute_kpis(+ metrics, {p for p, m in git_meta_map.items() if m.get("is_hotspot")}+ )metrics_sorted = sorted(metrics, key=lambda m: m.score)+ scoped_paths = {m.file_path for m in metrics}findings = report.findingsif file_filter:findings = [f for f in findings if f.file_path == file_filter]if module_filter:findings = [f for f in findings if f.file_path.startswith(module_filter)]+ if parse_scope(scope) == "production":+ findings = [f for f in findings if f.file_path in scoped_paths]if generate_code is not None:suggestions = getattr(report, "refactoring_suggestions", None) or []@@ -366,12 +390,13 @@ def health_command(band_color = {"healthy": "green", "warning": "yellow", "alert": "red"}[band]band_str = f" [[{band_color}]{BAND_LABEL[band]}[/{band_color}]]"console.print(- f"\nHotspot: [bold]{kpis.get('hotspot_health', '?')}[/bold]/10 · "- f"Average: [bold]{avg if avg is not None else '?'}[/bold]/10{band_str} · "+ f"\nCode health: [bold]{avg if avg is not None else '?'}[/bold]/10{band_str} · "+ f"Hotspot: [bold]{kpis.get('hotspot_health', '?')}[/bold]/10 · "f"Worst: [bold]{kpis.get('worst_performer_score', '?')}[/bold]/10 "f"({kpis.get('worst_performer_path', 'n/a')})")- _render_distribution_line(health_distribution(report.metrics))+ _render_split_line(kpis)+ _render_distribution_line(health_distribution(metrics))_render_defect_accuracy_line(report)diff --git a/packages/cli/src/repowise/cli/commands/health_cmd/summary.py b/packages/cli/src/repowise/cli/commands/health_cmd/summary.pyindex 516197ed3..a333303b4 100644--- a/packages/cli/src/repowise/cli/commands/health_cmd/summary.py+++ b/packages/cli/src/repowise/cli/commands/health_cmd/summary.py@@ -54,6 +54,18 @@ def _render_performance_section(report: Any, lang_by_path: dict[str, str]) -> No)+def _render_split_line(kpis: dict) -> None:+ """The headline's two halves, so a reader can see which one holds it down."""+ structure = kpis.get("structure_average")+ history = kpis.get("history_average")+ if structure is None or history is None:+ return+ console.print(+ f"[dim]Of that deduction, [/dim]{structure:.2f}[dim] is code shape and [/dim]"+ f"{history:.2f}[dim] is history — history answers to time, not to editing.[/dim]"+ )++def _render_distribution_line(dist: dict) -> None:"""One compact line: the NLOC-weighted file split across the 3 bands."""bands = dist.get("bands") or {}diff --git a/packages/core/src/repowise/core/analysis/health/trends.py b/packages/core/src/repowise/core/analysis/health/trends.pyindex 912453599..eba98a990 100644--- a/packages/core/src/repowise/core/analysis/health/trends.py+++ b/packages/core/src/repowise/core/analysis/health/trends.py@@ -50,6 +50,16 @@ class TrendAlert:baseline: float | Nonedelta: floatmessage: str+ # Which half of the headline moved, in score points. ``structure`` is code+ # shape, which a rewrite can fix; ``history`` is git-derived and answers to+ # time, not to editing. They are changes in each half's mean DEDUCTION, so+ # they sum to ``delta`` only while no file sits at the score floor — the+ # clamp is what the two measures disagree about. All ``None`` for+ # ``hotspot_health``, whose halves are not snapshotted, and on snapshots+ # taken before the split existed.+ driver: str | None = None+ structure_delta: float | None = None+ history_delta: float | None = None@dataclass@@ -63,6 +73,11 @@ class TrendSummary:hotspot_delta: float | Noneaverage_delta: float | Nonealerts: list[TrendAlert] = field(default_factory=list)+ # The newest snapshot's headline split, in deduction points, so a surface+ # can show the two halves without replaying findings. ``None`` before the+ # split was recorded.+ current_structure_deduction: float | None = None+ current_history_deduction: float | None = Nonedef _delta(current: float, previous: float | None) -> float | None:@@ -71,6 +86,92 @@ def _delta(current: float, previous: float | None) -> float | None:return round(current - previous, 3)+def _attribution(current: Any, baseline: Any) -> tuple[str | None, float | None, float | None]:+ """Split a headline move into its structure and history halves.++ Snapshots store the two as deduction points, so each contribution to the+ score is the negated change. Returns ``(driver, structure, history)``, all+ ``None`` when either snapshot predates the split.+ """+ values = [+ (getattr(snap, attr, None))+ for snap in (current, baseline)+ for attr in ("structure_average", "history_average")+ ]+ if any(v is None for v in values):+ return None, None, None+ cur_structure, cur_history, base_structure, base_history = (float(v) for v in values)+ structure = round(base_structure - cur_structure, 3)+ history = round(base_history - cur_history, 3)+ driver = "structure" if abs(structure) >= abs(history) else "history"+ return driver, structure, history+++_DRIVER_PHRASE = {+ "structure": "Code shape moved most",+ "history": "History moved most, and no edit to these files settles it",+}+++def _driver_sentence(driver: str | None, structure: float | None, history: float | None) -> str:+ """Name the driver and both halves, without claiming they sum to ``delta``.++ They are deduction means and ``delta`` is a mean of clamped scores, so the+ two agree only on a repo with no floored file. Stating each half and+ stopping there is the claim the numbers actually support.+ """+ if driver is None or structure is None or history is None:+ return ""+ return f" {_DRIVER_PHRASE[driver]} (code shape {structure:+.2f}, history {history:+.2f})."+++@dataclass+class _ScopedSnapshot:+ """One snapshot with its production figure standing in for the headline.++ Only ``average_health`` was recorded for both populations. Everything else+ on a snapshot describes the whole repository, and a repo-wide figure served+ under a production label is worse than an absent one, so the rest is+ dropped rather than carried across.+ """++ taken_at: Any+ average_health: float+ per_file_scores_json: str+ hotspot_health: float = 0.0+ worst_performer_path: str | None = None+ worst_performer_score: float | None = None+ structure_average: float | None = None+ history_average: float | None = None+++def project_scope(history: list[Any], scope: str) -> list[Any]:+ """Re-read a snapshot series through one scope.++ The default scope is what the rows already hold. Narrowing swaps in the+ stored production average and drops snapshots taken before it was+ recorded — a gap in the line is honest where a repo-wide number wearing a+ production label would not be.+ """+ from .scope import parse_scope++ if parse_scope(scope) != "production":+ return history+ out: list[Any] = []+ for snap in history:+ value = getattr(snap, "production_average", None)+ if value is None:+ continue+ out.append(+ _ScopedSnapshot(+ taken_at=snap.taken_at,+ average_health=float(value),+ per_file_scores_json=snap.per_file_scores_json,+ )+ )+ return out++def diff_snapshots(history: list[Any]) -> TrendSummary:"""Compare the newest snapshot against the window behind it.@@ -103,6 +204,8 @@ def diff_snapshots(history: list[Any]) -> TrendSummary:float(current.average_health),float(prior.average_health) if prior else None,),+ current_structure_deduction=getattr(current, "structure_average", None),+ current_history_deduction=getattr(current, "history_average", None),)summary.alerts.extend(_declining_alerts(history))@@ -140,6 +243,11 @@ def _declining_alerts(history: list[Any]) -> list[TrendAlert]:base_val = float(getattr(baseline, metric))delta = round(cur_val - base_val, 3)if delta <= -DECLINE_THRESHOLD:+ driver, structure, history = (+ _attribution(current, baseline)+ if metric == "average_health"+ else (None, None, None)+ )out.append(TrendAlert(kind="declining",@@ -152,7 +260,11 @@ def _declining_alerts(history: list[Any]) -> list[TrendAlert]:f"{abs(delta):.2f} points vs. snapshot "f"{DECLINE_LOOKBACK} ago "f"({base_val:.2f} → {cur_val:.2f})."+ f"{_driver_sentence(driver, structure, history)}"),+ driver=driver,+ structure_delta=structure,+ history_delta=history,))return out@@ -169,6 +281,11 @@ def _predicted_decline_alerts(history: list[Any]) -> list[TrendAlert]:vals = [float(getattr(s, metric)) for s in tail]if all(vals[i + 1] < vals[i] for i in range(len(vals) - 1)):delta = round(vals[-1] - vals[0], 3)+ driver, structure, history = (+ _attribution(tail[-1], tail[0])+ if metric == "average_health"+ else (None, None, None)+ )out.append(TrendAlert(kind="predicted_decline",@@ -180,12 +297,33 @@ def _predicted_decline_alerts(history: list[Any]) -> list[TrendAlert]:f"{metric.replace('_', ' ').title()} declined for "f"{PREDICTED_DECLINE_CONSECUTIVE} consecutive snapshots "f"({vals[0]:.2f} → {vals[-1]:.2f})."+ f"{_driver_sentence(driver, structure, history)}"),+ driver=driver,+ structure_delta=structure,+ history_delta=history,))return out+def drop_unscoped_fields(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:+ """Blank the per-row figures a narrowed snapshot never recorded.++ A projected snapshot carries the production average and nothing else, so+ the placeholders the rest of the row picked up must not read as measurements.+ """+ return [+ {+ **row,+ "hotspot_health": None,+ "worst_performer_path": None,+ "worst_performer_score": None,+ }+ for row in rows+ ]++def recent_kpis(history: list[Any], limit: int = 10) -> list[dict[str, Any]]:"""Serialize the most-recent *limit* snapshots for CLI / API consumers.diff --git a/packages/server/src/repowise/server/mcp_server/tool_health.py b/packages/server/src/repowise/server/mcp_server/tool_health.pyindex 39653f7af..8c5e99b30 100644--- a/packages/server/src/repowise/server/mcp_server/tool_health.py+++ b/packages/server/src/repowise/server/mcp_server/tool_health.py@@ -13,13 +13,12 @@ from sqlalchemy import func, selectfrom repowise.core.analysis.health.aggregation import module_rollups as _module_rollupsfrom repowise.core.analysis.health.churn_complexity import churn_complexity_points-from repowise.core.analysis.health.complexity.languages import LANGUAGE_MAPSfrom repowise.core.analysis.health.coverage import decay_since, measurement_reffrom repowise.core.analysis.health.defect_accuracy import compute_defect_accuracyfrom repowise.core.analysis.health.finding_identity import finding_public_idfrom repowise.core.analysis.health.grading import HEALTHY_MIN, band_forfrom repowise.core.analysis.health.grading import distribution as health_distribution-from repowise.core.analysis.health.models import primary_finding+from repowise.core.analysis.health.models import primary_finding, split_by_originfrom repowise.core.analysis.health.perf.coverage import PerfCoverage, coverage_for_metricsfrom repowise.core.analysis.health.perf.opportunity_rank import observation_rankfrom repowise.core.analysis.health.ranking import deduction_by_path, sort_metrics_worst_first@@ -28,11 +27,18 @@ from repowise.core.analysis.health.refactoring.recommendations import (build_recommendations,hydrate_recommendations,)-from repowise.core.analysis.health.scoring import hotspot_health+from repowise.core.analysis.health.scope import DEFAULT_SCOPE, parse_scope+from repowise.core.analysis.health.scoring import hotspot_health, nloc_weighted_attrfrom repowise.core.analysis.health.semantics import health_semantics_contractfrom repowise.core.analysis.health.signals import file_signalsfrom repowise.core.analysis.health.suggestions import suggestion_for-from repowise.core.analysis.health.trends import diff_snapshots, file_trend, recent_kpis+from repowise.core.analysis.health.trends import (+ diff_snapshots,+ drop_unscoped_fields,+ file_trend,+ project_scope,+ recent_kpis,+)from repowise.core.ingestion.models import FILE_DEPENDENCY_EDGE_TYPESfrom repowise.core.persistence.crud import (get_all_git_metadata,@@ -707,9 +713,19 @@ def _leads_by_file(findings: list[Any]) -> dict[str, dict[str, Any]]:primary = primary_finding(fs)if primary is None:continue+ # The same rule applied to code shape alone. A file can be led by a+ # history marker, and a caller told to fix that has been handed+ # something no edit resolves; ``watch_*`` carries it as context instead.+ code_shape, history = split_by_origin(fs)+ actionable = primary_finding(code_shape)+ watch = primary_finding(history)leads[path] = {"primary_biomarker": primary.biomarker_type,"primary_reason": primary.reason,+ "actionable_biomarker": actionable.biomarker_type if actionable else None,+ "actionable_reason": actionable.reason if actionable else None,+ "watch_biomarker": watch.biomarker_type if watch else None,+ "watch_reason": watch.reason if watch else None,"total_deduction": round(sum(float(x.health_impact or 0.0) for x in fs), 3),}return leads@@ -902,7 +918,15 @@ def _directive("""if not by_leverage:return None- top = by_leverage[0]+ # The highest-leverage file that has something an edit can remove. A file+ # whose whole deficit is history would otherwise be named ``fix_first``+ # with nothing to fix underneath it, which is the failure this block exists+ # to prevent. Falls back to the top file when no candidate has one, and+ # says so rather than inventing a task.+ top = next(+ (m for m in by_leverage if (leads.get(m.file_path) or {}).get("actionable_biomarker")),+ by_leverage[0],+ )recovers = round(max(HEALTHY_MIN - top.score, 0.0) * max(top.nloc, 1))lead = leads.get(top.file_path) or {}# Does anything behind ``plan_via`` actually address the cause named in@@ -910,12 +934,15 @@ def _directive(# 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")+ # The cause named here has to be one an edit can remove, or the whole block+ # recommends something impossible. History is reported alongside, in its own+ # field, and never as ``reason``.+ lead_biomarker = lead.get("actionable_biomarker")available = (plan_biomarkers_by_path or {}).get(top.file_path, set())addresses = bool(lead_biomarker) and lead_biomarker in availableout = {"fix_first": top.file_path,- "reason": lead.get("primary_reason") or f"scores {round(top.score, 2)}",+ "reason": lead.get("actionable_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. The denominator@@ -930,7 +957,7 @@ def _directive("equivalent_value": True,},"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]],+ "then": [m.file_path for m in by_leverage if m.file_path != top.file_path][:2],# Projected, not bare. ``include`` adds a block without subtracting the# dashboard, and five ranked lists at the default ``limit`` compose: the# bare ``include=['refactoring']`` measured 70,776 chars on this repo@@ -942,6 +969,22 @@ def _directive("plan_via": "get_health(include=['refactoring'], only=['refactoring_plans'])","plan_addresses_reason": addresses,}+ # Context, not a task. These move with the repository's history and no edit+ # to this file settles them.+ if lead.get("watch_biomarker"):+ out["watch"] = {+ "biomarker": lead["watch_biomarker"],+ "reason": lead.get("watch_reason"),+ "note": "History-derived. Read it as context; there is nothing here to fix.",+ }+ if not lead_biomarker:+ # Nothing in the repository has a code-shape lead, so the honest answer+ # is that the deficit is history and no edit here settles it.+ out["next_action"] = (+ "No file's leading cause is code shape; the deficit on this one is "+ "history. Read watch for what is moving and leave it alone."+ )+ return out# 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.@@ -1216,22 +1259,6 @@ def _write_health_analysis_meta(meta["health_analysis"] = analysis-def _dimension_average(metrics: list[HealthFileMetric], attr: str) -> float | None:- """NLOC-weighted headline over a per-dimension score attribute.-- Skips rows without the attribute (those predating that pillar) so the KPI- reads "not measured" rather than a misleading 10.0; ``None`` when no row- carries it.- """- scored = [m for m in metrics if getattr(m, attr, None) is not None]- if not scored:- return None- total_nloc = sum(max(m.nloc, 1) for m in scored)- if not total_nloc:- return round(sum(getattr(m, attr) for m in scored) / len(scored), 2)- return 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.@@ -1330,17 +1357,10 @@ def _perf_kpis(performance_findings: int, coverage: PerfCoverage | None) -> dict}-def _code_only(- metrics: list[HealthFileMetric], lang_by_path: dict[str, str]-) -> list[HealthFileMetric]:- """The metric rows the complexity walker actually walks.-- ``LANGUAGE_MAPS`` is already the repo's definition of "real code" — the perf- pillar uses exactly this filter so docs/config rows never dilute its- coverage math (``perf/coverage.py::coverage_for_metrics``). The defect- headline never applied it.- """- return [m for m in metrics if lang_by_path.get(m.file_path, "") in LANGUAGE_MAPS]+def _avg(metrics: list[HealthFileMetric], attr: str) -> float | None:+ """NLOC-weighted mean of one metric column, rounded for the wire."""+ value = nloc_weighted_attr(metrics, attr)+ return round(value, 2) if value is not None else Nonedef _compute_kpis(@@ -1349,7 +1369,6 @@ def _compute_kpis(hotspot_paths: set[str] | None = None,performance_findings: int = 0,coverage: PerfCoverage | None = None,- lang_by_path: dict[str, str] | None = None,) -> dict[str, Any]:if not metrics:return {@@ -1362,32 +1381,13 @@ def _compute_kpis("worst_performer_score": None,"maintainability_average": None,"performance_average": None,+ "structure_average": None,+ "history_average": None,**_perf_kpis(0, None),}total_nloc = sum(max(m.nloc, 1) for m in metrics)avg = sum(m.score * max(m.nloc, 1) for m in metrics) / total_nlocworst = min(metrics, key=lambda r: r.score)- # What the headline would read over code alone. No biomarker walks a- # markdown or JSON file, so those rows carry a mechanical 10.0 that means- # "nothing looked at this", exactly the fabricated-10.0 problem the perf- # pillar already surfaces rather than hides (``perf/coverage.py``). Measured- # on this repo: 233 of 3,314 rows are non-code, 221 of them score exactly- # 10.0, they are 7.5% of NLOC, and they lift ``average_health`` 7.31 -> 7.47.- # Surfaced rather than subtracted: ``average_health`` is what the badge, the- # snapshots, the trend alerts and the web UI all read, and redefining it- # here alone would make this tool disagree with every one of them.- code_kpis: dict[str, Any] = {}- if lang_by_path is not None:- code = _code_only(metrics, lang_by_path)- code_nloc = sum(max(m.nloc, 1) for m in code)- code_kpis = {- "non_code_files": len(metrics) - len(code),- "average_health_code_only": (- round(sum(m.score * max(m.nloc, 1) for m in code) / code_nloc, 2)- if code_nloc- else None- ),- }return {"file_count": len(metrics),"average_health": round(avg, 2),@@ -1396,7 +1396,6 @@ def _compute_kpis(# reporting it as a score, the same fabricated-10.0 problem the comment# above objects to for non-code rows."hotspot_health": hotspot_health(metrics, hotspot_paths or set()),- **code_kpis,# 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@@ -1408,8 +1407,12 @@ def _compute_kpis("worst_performer_score": round(worst.score, 2),# Maintainability + performance pillar headlines alongside the# defect-backed average. Each is ``None`` until its pillar is measured.- "maintainability_average": _dimension_average(metrics, "maintainability_score"),- "performance_average": _dimension_average(metrics, "performance_score"),+ "maintainability_average": _avg(metrics, "maintainability_score"),+ "performance_average": _avg(metrics, "performance_score"),+ # The headline's two halves, in deduction points, so a caller can see+ # whether code shape or history is holding the number down.+ "structure_average": _avg(metrics, "structure_deduction"),+ "history_average": _avg(metrics, "history_deduction"),# Performance leads with count + density + coverage, not the diluted /10.**_perf_kpis(performance_findings, coverage),}@@ -1494,6 +1497,7 @@ async def get_health(performance_boundary: str | None = None,performance_confidence: str | None = None,performance_sort: str | None = None,+ scope: str = DEFAULT_SCOPE,) -> dict:"""Code-health scores and findings from stored analysis.@@ -1503,7 +1507,7 @@ async def get_health(Args:targets: file paths or ``module:<name>``. Empty means dashboard;- unmatched ones land in ``unresolved``, surviving ``only``.+ unmatched ones land in ``unresolved``.include: ``biomarkers`` | ``refactoring`` | ``trend`` | ``coverage`` |``accuracy`` | ``signals`` | ``churn_complexity``, or a dimension.``performance`` and ``refactoring`` add their queues.@@ -1514,15 +1518,15 @@ async def get_health(repo: usually omitted.limit: max rows per ranked list, ``0`` for none.cursor: zero-based offset into a ranked list.- finding_id: stable ``id`` from a health finding.- plan_id: stable ``id`` from a refactoring plan.- opportunity_id: ``perf...`` or ``refop...`` id from a directive or- queue: the unit, its steps or plan, and evidence paged by- ``only=["*_evidence"]``. Excludes the two ids above.+ finding_id / plan_id: stable ``id`` from a finding or a plan.+ opportunity_id: ``perf...`` or ``refop...`` id: the unit, its steps or+ plan, and evidence paged by ``only=["*_evidence"]``.refactoring_view: ``diversified`` (default) | ``canonical`` |- ``file_spread``; refactoring_type / _confidence / _effort filter.+ ``file_spread``; _type / _confidence / _effort filter.performance_view / _context / _boundary / _confidence / _sort: queueprojection and filters; the facets list them.+ scope: ``all`` (default) | ``production``. Narrowing drops test files+ from every figure; tests score higher, so it lowers them."""started = perf_counter()@@ -1764,8 +1768,25 @@ async def get_health(# 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.+ # Computed before ``scope`` narrows the list, or a test file would be+ # reported as dropped by a config that says nothing about it.excluded_paths = {m.file_path for m in indexed_rows} - {m.file_path for m in all_metrics}+ # Narrowing to production is the same shape of question as the exclude+ # config: both drop whole files from every block at once. Folding it+ # into one filter is what keeps a scoped dashboard from ranking a+ # finding on a file its own file list no longer contains.+ reported_scope = parse_scope(scope)+ scope_paths: set[str] | None = None+ if reported_scope == "production":+ all_metrics = [m for m in all_metrics if not m.is_test]+ scope_paths = {m.file_path for m in all_metrics}++ def in_scope_rows(rows: list, attr: str = "file_path") -> list:+ rows = filter_rows_by_attr(rows, attr, exclude_spec)+ if scope_paths is None:+ return rows+ return [r for r in rows if getattr(r, attr, None) in scope_paths]matched_modules: set[str] = set()if module_targets:module_set = set(module_targets)@@ -1824,7 +1845,7 @@ async def get_health(test_finding_rows: list[Any] = []test_findings_total = 0if scoped:- finding_rows = filter_rows_by_attr(+ finding_rows = in_scope_rows(list((await session.execute(@@ -1838,7 +1859,6 @@ async def get_health(.all()),"file_path",- exclude_spec,)lead_rows: list[Any] = finding_rowsemitted = _rank_emitted(@@ -1891,7 +1911,7 @@ async def get_health(# ``lead_rows`` stays the unfiltered open set: it feeds the per-file# leads and the performance KPI, neither of which should change# because the caller asked to *see* one dimension.- lead_rows = filter_rows_by_attr(lite_rows, "file_path", exclude_spec)+ lead_rows = in_scope_rows(lite_rows)emitted = _rank_emitted([r for r in lead_rows if _in_dimensions(r, ranked_dimensions)])@@ -1993,8 +2013,6 @@ async def get_health(# Dashboard perf headline: coverage (how much of the analyzed code the# perf pass ran on) + open performance-finding count. Both feed ``kpis``# alone, so a projection that drops kpis skips the language-map read.- # The same map answers "how much of this headline is non-code" — one- # read, two KPIs.if not scoped and wants("kpis"):lang_by_path = await get_file_language_map(session, repository.id)perf_coverage = coverage_for_metrics(all_metrics, lang_by_path)@@ -2009,7 +2027,7 @@ async def get_health(# ~10k rows the narrow pass above exists to avoid.accuracy_rows: list[Any] = []if "accuracy" in include_set and not scoped:- accuracy_rows = filter_rows_by_attr(+ accuracy_rows = in_scope_rows(list((await session.execute(@@ -2022,7 +2040,6 @@ async def get_health(.all()),"file_path",- exclude_spec,)# Structured refactoring plans (Extract Class, ...) — loaded only when@@ -2041,14 +2058,13 @@ async def get_health(or ({"performance", "refactoring"} <= include_set and wants("recommendation_lede")))if plans_requested and not nothing_resolved:- refactoring_rows = filter_rows_by_attr(+ refactoring_rows = in_scope_rows(await get_refactoring_suggestions(session,repository.id,file_paths=list(effective_targets) if scoped else None,),"file_path",- exclude_spec,)refactoring_recommendations = await hydrate_recommendations(session,@@ -2098,7 +2114,7 @@ async def get_health(coverage_rows: list[Any] = []coverage_summary: dict[str, Any] = {}if "coverage" in include_set and not nothing_resolved:- coverage_rows = filter_rows_by_attr(+ coverage_rows = in_scope_rows(# ``effective_targets``, not ``targets`` — a raw ``module:foo``# target is not a file path and matched nothing here.#@@ -2114,11 +2130,15 @@ async def get_health(include_covered_lines=scoped,),"file_path",- exclude_spec,)- # coverage_summary is a repo-wide stored aggregate, not recomputed- # here; the per-file rows above are exclude-filtered.- coverage_summary = await get_coverage_summary(session, repository.id)+ # A repo-wide stored aggregate, not recomputed here, so it cannot+ # describe a narrowed population. Omitted rather than served beside+ # per-file rows that no longer match it; the rows themselves stay.+ coverage_summary = (+ {}+ if reported_scope == "production"+ else await get_coverage_summary(session, repository.id)+ )# Per-file process/people/topology signals for targeted files — the# same join the file-detail drawer and REST breakdown use, so an agent@@ -2157,7 +2177,11 @@ async def get_health(# file" context for agents).snapshots: list[Any] = []if "trend" in include_set or (scoped and wants("trends")):- snapshots = await list_health_snapshots(session, repository.id, limit=20)+ # Read through the same scope as the KPIs, or the two halves of one+ # response would disagree about which files they describe.+ snapshots = project_scope(+ await list_health_snapshots(session, repository.id, limit=20), reported_scope+ )# Dominant-cause lead per file. Targeted mode wants one per target, so# the reduction runs over the whole (small) scoped set. Dashboard mode@@ -2234,20 +2258,17 @@ async def get_health(if source:plan_biomarkers_by_path.setdefault(path, set()).add(source)- # KPIs deliberately keep test files in. Excluding them is not a display- # choice, it is a scoring change: measured across this workspace, dropping+ # KPIs keep test files in by default, and ``scope`` is what changes that.+ # The default is not arbitrary: measured across this workspace, dropping# test material moves NLOC-weighted ``average_health`` 7.52 -> 6.87 here,- # 7.07 -> 6.27 on the backend repo and 7.59 -> 7.46 on the frontend. Test- # files score *better* than production code, so excluding them would make- # every repo's headline drop overnight with no defect having been found.- # The calibrated numbers stay where they are; the split above is about which- # findings compete for a ranked list, not about what the score means.+ # 7.07 -> 6.27 on the backend repo and 7.59 -> 7.46 on the frontend. Tests+ # score better than production code, so a narrowed number is a lower number+ # with no defect having been found — a caller should ask for it knowingly.kpis = _compute_kpis(metric_rows if scoped else all_metrics,hotspot_paths=hotspot_paths,performance_findings=perf_findings_count,coverage=perf_coverage,- lang_by_path=lang_by_path,)if scoped:@@ -2379,6 +2400,7 @@ async def get_health(else {}),"mode": "dashboard",+ "scope": reported_scope,"kpis": kpis,"distribution": health_distribution(all_metrics),# Where the gap to Healthy concentrates — the "few files, not the@@ -2551,7 +2573,10 @@ async def get_health(if "trend" in include_set:summary = diff_snapshots(snapshots)+ narrowed = reported_scope == "production"recent = recent_kpis(snapshots, limit=10)+ if narrowed:+ recent = drop_unscoped_fields(recent)alerts = [{"kind": a.kind,@@ -2560,16 +2585,23 @@ async def get_health("baseline": a.baseline,"delta": a.delta,"message": a.message,+ "driver": a.driver,+ "structure_delta": a.structure_delta,+ "history_delta": a.history_delta,}for a in summary.alerts]+ # The hotspot pair describes the whole repository whatever the scope,+ # since only the average was snapshotted for both populations.result["trend"] = {- "current_hotspot_health": summary.current_hotspot_health,+ "current_hotspot_health": None if narrowed else summary.current_hotspot_health,"current_average_health": summary.current_average_health,- "previous_hotspot_health": summary.previous_hotspot_health,+ "previous_hotspot_health": None if narrowed else summary.previous_hotspot_health,"previous_average_health": summary.previous_average_health,- "hotspot_delta": summary.hotspot_delta,+ "hotspot_delta": None if narrowed else summary.hotspot_delta,"average_delta": summary.average_delta,+ "current_structure_deduction": summary.current_structure_deduction,+ "current_history_deduction": summary.current_history_deduction,"alerts": bounded(alerts, "trend.alerts"),"alerts_total": len(alerts),"alerts_emitted": min(len(alerts), limit),diff --git a/packages/server/src/repowise/server/routers/code_health/files_routes.py b/packages/server/src/repowise/server/routers/code_health/files_routes.pyindex 34b47a98d..c85929490 100644--- a/packages/server/src/repowise/server/routers/code_health/files_routes.py+++ b/packages/server/src/repowise/server/routers/code_health/files_routes.py@@ -16,6 +16,7 @@ from repowise.server.deps import get_db_sessionfrom ._router import routerfrom .breakdown import _score_breakdown_from_findingsfrom .loaders import _attach_symbol_ids, _load_file_signals+from .scope import ScopeQuery, narrowfrom .serializers import (_file_signals_to_dict,_file_trend_to_dict,@@ -58,11 +59,13 @@ async def list_health_files("narrows the finding read that produces them."),),+ scope: str = ScopeQuery,session: AsyncSession = Depends(get_db_session),) -> dict:if sort not in _SORT_FIELDS:sort = "score"metrics = await crud.get_health_metrics(session, repo_id)+ (metrics,) = narrow(scope, metrics)hotspot_paths: set[str] = set()if only_hotspots:diff --git a/packages/server/src/repowise/server/routers/code_health/map_routes.py b/packages/server/src/repowise/server/routers/code_health/map_routes.pyindex c44567518..e6b50acc7 100644--- a/packages/server/src/repowise/server/routers/code_health/map_routes.py+++ b/packages/server/src/repowise/server/routers/code_health/map_routes.py@@ -21,6 +21,7 @@ from repowise.server.services.health_map import ()from ._router import router+from .scope import ScopeQuery@router.get("/api/repos/{repo_id}/health/map")@@ -35,10 +36,11 @@ async def get_health_map("them so the cap can never push the subject off its own map."),),+ scope: str = ScopeQuery,session: AsyncSession = Depends(get_db_session),) -> dict[str, Any]:"""One bounded field plus the exact scope of what the cap left out."""feed = await HealthMapService(session, repo_id).feed(- cap=cap, active=parse_active(active)+ cap=cap, active=parse_active(active), scope=scope)return feed.payload()diff --git a/packages/server/src/repowise/server/routers/code_health/overview_routes.py b/packages/server/src/repowise/server/routers/code_health/overview_routes.pyindex 43d889866..9c67734a9 100644--- a/packages/server/src/repowise/server/routers/code_health/overview_routes.py+++ b/packages/server/src/repowise/server/routers/code_health/overview_routes.py@@ -23,6 +23,7 @@ from repowise.server.mcp_server._meta import resolve_indexed_commitfrom ._router import routerfrom .loaders import _attach_symbol_ids+from .scope import ScopeQuery, narrowfrom .serializers import _finding_to_dict, _leads_by_file, _metric_to_dict@@ -49,6 +50,7 @@ def _resolve_last_indexed_at(async def health_overview(repo_id: str,limit: int = Query(20, ge=1, le=200),+ scope: str = ScopeQuery,session: AsyncSession = Depends(get_db_session),) -> dict:"""KPIs + lowest-scoring files + per-module rollup + meta."""@@ -62,22 +64,17 @@ async def health_overview(# two — so the route was paying for each of them twice per request.metrics = await crud.get_health_metrics(session, repo_id)findings = await crud.get_health_findings(session, repo_id)+ metrics, findings = narrow(scope, metrics, findings)summary = await crud.get_health_summary(session, repo_id, metrics=metrics, findings=findings)- # Hotspot health is recomputed from the metrics already loaded above rather- # than read off the latest snapshot. The snapshot was described here as- # authoritative, and it is not: ``repowise update`` re-scores health and- # calls ``save_health_metrics`` without ``save_health_snapshot``- # (``update_cmd/persistence.py``), so after any update this route served a- # figure from the previous full index while every other number on the page- # came from the fresh rows. Measured stale on 3 of 42 local indexes, this- # repo among them (4.62 against 5.08 live) — a lower bound, since a corpus- # of frozen clones mostly has nothing to have gone stale against.- #- # It costs no query: ``metrics`` is already in hand, and the hotspot path- # set is one scalar column. The snapshot is still read, for ``taken_at``.+ # Recomputed from the metrics already loaded rather than read off the latest+ # snapshot: a snapshot is a point in time, and this page's other numbers all+ # come from the live rows, so reading it here would make one figure older+ # than its neighbours. It costs no query — ``metrics`` is in hand and the+ # hotspot path set is one scalar column. The snapshot is still read, for+ # ``taken_at``, and for ``scope`` it would be the wrong population anyway.snapshot = await crud.get_health_snapshot_headline(session, repo_id)hotspot_paths = await crud.get_hotspot_file_paths(session, repo_id)hotspot_health_value = hotspot_health(metrics, hotspot_paths)diff --git a/packages/server/src/repowise/server/routers/code_health/refactoring_routes.py b/packages/server/src/repowise/server/routers/code_health/refactoring_routes.pyindex 0c7c59fd9..77144efb3 100644--- a/packages/server/src/repowise/server/routers/code_health/refactoring_routes.py+++ b/packages/server/src/repowise/server/routers/code_health/refactoring_routes.py@@ -18,6 +18,7 @@ from repowise.server.deps import get_db_sessionfrom repowise.server.schemas import HealthWorkQueueResponsefrom ._router import router+from .scope import ScopeQuery, narrow_SEVERITY_ORDER = {"low": 0, "medium": 1, "high": 2, "critical": 3}@@ -65,6 +66,7 @@ async def health_work_queue(sort: str = Query("impact_per_effort", pattern="^(impact_per_effort|total_impact|score|finding_count)$"),+ scope: str = ScopeQuery,session: AsyncSession = Depends(get_db_session),) -> dict:"""Health work items ranked by impact / effort.@@ -82,8 +84,9 @@ async def health_work_queue(raise HTTPException(status_code=404, detail="Repository not found")metrics = await crud.get_health_metrics(session, repo_id)- metric_by_path = {m.file_path: m for m in metrics}findings = await crud.get_health_findings(session, repo_id)+ metrics, findings = narrow(scope, metrics, findings)+ metric_by_path = {m.file_path: m for m in metrics}by_file: dict[str, list[Any]] = {}for f in findings:diff --git a/packages/server/src/repowise/server/routers/code_health/scope.py b/packages/server/src/repowise/server/routers/code_health/scope.pynew file mode 100644index 000000000..40306ea9f--- /dev/null+++ b/packages/server/src/repowise/server/routers/code_health/scope.py@@ -0,0 +1,34 @@+"""Narrowing a code-health response to one half of the repository."""++from __future__ import annotations++from typing import Any++from fastapi import Query++from repowise.core.analysis.health.scope import DEFAULT_SCOPE, SCOPES, parse_scope++ScopeQuery = Query(+ DEFAULT_SCOPE,+ description=(+ "Which files to report on: 'all' (production and tests) or 'production'. "+ "Tests score higher than production code, so narrowing lowers every figure "+ "without a defect having been found."+ ),+ pattern=f"^({'|'.join(SCOPES)})$",+)+++def narrow(+ scope: str, metrics: list[Any], *keyed_by_path: list[Any]+) -> tuple[list[Any], ...]:+ """Filter *metrics* to *scope*, then everything else to the files it kept.++ Metric rows carry ``is_test``, so they answer the question directly.+ Findings and their kin only carry a path, so they follow the metrics.+ """+ if parse_scope(scope) != "production":+ return (metrics, *keyed_by_path)+ kept = [m for m in metrics if not m.is_test]+ paths = {m.file_path for m in kept}+ return (kept, *([r for r in rows if r.file_path in paths] for rows in keyed_by_path))diff --git a/packages/server/src/repowise/server/routers/code_health/serializers.py b/packages/server/src/repowise/server/routers/code_health/serializers.pyindex 96a0b7645..7245e6e99 100644--- a/packages/server/src/repowise/server/routers/code_health/serializers.py+++ b/packages/server/src/repowise/server/routers/code_health/serializers.py@@ -6,6 +6,7 @@ import jsonfrom typing import Anyfrom repowise.core.analysis.health.models import primary_finding+from repowise.core.analysis.health.scoring import unclamped_scorefrom repowise.core.analysis.health.signals import FileSignalsfrom repowise.core.analysis.health.trends import FileTrend@@ -122,6 +123,14 @@ def _metric_to_dict(out["performance_findings"] = perf_findingsout["performance_analyzed"] = perf_analyzedif not summary:+ # The headline's two halves, and the score the file would carry without+ # the floor. A file pinned at 1.0 reads 1.0 for months while real work+ # lands on it; the unclamped number is the only place that shows.+ structure = _round_opt(getattr(m, "structure_deduction", None))+ history = _round_opt(getattr(m, "history_deduction", None))+ out["structure_deduction"] = structure+ out["history_deduction"] = history+ out["unclamped_score"] = unclamped_score(structure, history)# Dominant-cause lead + pre-clamp magnitude (null when findings weren't# loaded for this row, or the file is clean). Additive; readers degrade.out["primary_biomarker"] = lead.get("primary_biomarker") if lead else Nonediff --git a/packages/server/src/repowise/server/routers/code_health/trends_routes.py b/packages/server/src/repowise/server/routers/code_health/trends_routes.pyindex 17dc9747a..cde60bf13 100644--- a/packages/server/src/repowise/server/routers/code_health/trends_routes.py+++ b/packages/server/src/repowise/server/routers/code_health/trends_routes.py@@ -7,12 +7,20 @@ import jsonfrom fastapi import Depends, HTTPException, Queryfrom sqlalchemy.ext.asyncio import AsyncSession-from repowise.core.analysis.health.trends import diff_snapshots, file_trend, recent_kpis+from repowise.core.analysis.health.scope import parse_scope+from repowise.core.analysis.health.trends import (+ diff_snapshots,+ drop_unscoped_fields,+ file_trend,+ project_scope,+ recent_kpis,+)from repowise.core.persistence import crudfrom repowise.server.deps import get_db_sessionfrom repowise.server.schemas import FileHealthTrendResponse, HealthTrendResponsefrom ._router import router+from .scope import ScopeQueryfrom .serializers import _file_trend_to_dict# How many per-file movements the trend response carries. Paired with@@ -44,13 +52,18 @@ async def file_health_trend(async def health_trend(repo_id: str,limit: int = Query(20, ge=1, le=50),+ scope: str = ScopeQuery,session: AsyncSession = Depends(get_db_session),) -> dict:repo = await crud.get_repository(session, repo_id)if repo is None:raise HTTPException(status_code=404, detail="Repository not found")- snapshots = await crud.list_health_snapshots(session, repo_id)+ narrowed = parse_scope(scope) == "production"+ snapshots = project_scope(await crud.list_health_snapshots(session, repo_id), scope)summary = diff_snapshots(snapshots)+ # Snapshots record per-file scores for the whole repository, so a narrowed+ # response has to drop the test files from the movement list too.+ test_paths = await crud.get_test_file_paths(session, repo_id) if narrowed else set()# Per-file delta from the last two snapshots.file_deltas: list[dict] = []@@ -64,7 +77,7 @@ async def health_trend(for p in all_paths:before = prev.get(p)after = cur.get(p)- if before is None or after is None:+ if before is None or after is None or p in test_paths:continued = round(float(after) - float(before), 2)if d == 0:@@ -80,14 +93,20 @@ async def health_trend(file_deltas.sort(key=lambda r: (-abs(r["delta"]), r["file_path"]))return {- "history": recent_kpis(snapshots, limit=limit),+ "history": (+ drop_unscoped_fields(recent_kpis(snapshots, limit=limit))+ if narrowed+ else recent_kpis(snapshots, limit=limit)+ ),"summary": {- "current_hotspot_health": summary.current_hotspot_health,+ "current_hotspot_health": None if narrowed else summary.current_hotspot_health,"current_average_health": summary.current_average_health,- "previous_hotspot_health": summary.previous_hotspot_health,+ "previous_hotspot_health": None if narrowed else summary.previous_hotspot_health,"previous_average_health": summary.previous_average_health,- "hotspot_delta": summary.hotspot_delta,+ "hotspot_delta": None if narrowed else summary.hotspot_delta,"average_delta": summary.average_delta,+ "current_structure_deduction": summary.current_structure_deduction,+ "current_history_deduction": summary.current_history_deduction,},"alerts": [{@@ -97,6 +116,9 @@ async def health_trend("baseline": a.baseline,"delta": a.delta,"message": a.message,+ "driver": a.driver,+ "structure_delta": a.structure_delta,+ "history_delta": a.history_delta,}for a in summary.alerts],@@ -105,4 +127,5 @@ async def health_trend(# of presenting a truncated list as the whole story."file_deltas_total": len(file_deltas),"snapshot_count": len(snapshots),+ "scope": scope,}diff --git a/packages/server/src/repowise/server/schemas/code_health.py b/packages/server/src/repowise/server/schemas/code_health.pyindex c2982c1d0..f93ebbfd1 100644--- a/packages/server/src/repowise/server/schemas/code_health.py+++ b/packages/server/src/repowise/server/schemas/code_health.py@@ -87,19 +87,26 @@ class HealthTrendKpiRow(BaseModel):"""One snapshot in the repo-level history, newest first."""taken_at: str | None = None- hotspot_health: float+ #: ``None`` under a narrowed scope, which recorded only the average.+ hotspot_health: float | None = Noneaverage_health: floatworst_performer_path: str | None = Noneworst_performer_score: float | None = Noneclass HealthTrendSummary(BaseModel):- current_hotspot_health: float+ #: ``None`` under a narrowed scope: only the average was recorded for both+ #: populations, and a repo-wide hotspot figure under a production label+ #: would describe files the rest of the response has dropped.+ current_hotspot_health: float | None = Nonecurrent_average_health: floatprevious_hotspot_health: float | None = Noneprevious_average_health: float | None = Nonehotspot_delta: float | None = Noneaverage_delta: float | None = None+ #: The newest reading's two halves, in deduction points.+ current_structure_deduction: float | None = None+ current_history_deduction: float | None = Noneclass HealthTrendAlert(BaseModel):@@ -109,6 +116,10 @@ class HealthTrendAlert(BaseModel):baseline: float | None = Nonedelta: floatmessage: str+ #: Which half of the headline moved, and each half's share of ``delta``.+ driver: str | None = None+ structure_delta: float | None = None+ history_delta: float | None = Noneclass HealthFileDelta(BaseModel):@@ -129,6 +140,8 @@ class HealthTrendResponse(BaseModel):#: The count behind the slice, so the UI can say "N of M".file_deltas_total: int = 0snapshot_count: int = 0+ #: Which half of the repository these figures describe.+ scope: str = "all"class HealthBadgeResponse(BaseModel):diff --git a/packages/server/src/repowise/server/services/health_map.py b/packages/server/src/repowise/server/services/health_map.pyindex a8735bb9d..8d7a27ad9 100644--- a/packages/server/src/repowise/server/services/health_map.py+++ b/packages/server/src/repowise/server/services/health_map.py@@ -21,6 +21,7 @@ from typing import Anyfrom sqlalchemy.ext.asyncio import AsyncSessionfrom repowise.core.analysis.health.perf.coverage import supported_perf_languages+from repowise.core.analysis.health.scope import DEFAULT_SCOPE, parse_scopefrom repowise.core.persistence import crud__all__ = [@@ -57,9 +58,12 @@ class HealthMapFeed:recovery: dict[str, Any]modules: list[dict[str, Any]] = field(default_factory=list)performance: dict[str, Any] | None = None+ #: Which half of the repository the field describes.+ scope: str = DEFAULT_SCOPEdef payload(self) -> dict[str, Any]:return {+ "scope": self.scope,"files": self.files,"cap": self.cap,"shown": self.shown,@@ -99,7 +103,11 @@ class HealthMapService:self._repository_id = repository_idasync def feed(- self, *, cap: int = DEFAULT_MAP_CAP, active: tuple[str, ...] = ()+ self,+ *,+ cap: int = DEFAULT_MAP_CAP,+ active: tuple[str, ...] = (),+ scope: str = DEFAULT_SCOPE,) -> HealthMapFeed:session, repo_id = self._session, self._repository_idmetrics = await crud.get_health_metrics(session, repo_id)@@ -108,6 +116,12 @@ class HealthMapService:summary = await crud.get_performance_summary(session, repo_id)perf_languages = supported_perf_languages()+ scope_narrowed = parse_scope(scope) == "production"+ if scope_narrowed:+ metrics = [m for m in metrics if not m.is_test]+ kept = {m.file_path for m in metrics}+ rollups = [r for r in rollups if r.file_path in kept]+by_path = {m.file_path: m for m in metrics}# A zero-NLOC file cannot be sized, and the map drops it on arrival.# Counting it as eligible would promise a node that never appears.@@ -185,7 +199,15 @@ class HealthMapService:"raise_cap": f"cap accepts up to {MAX_MAP_CAP}.",},modules=self._modules(drawn, burden),- performance=self._performance_block(rollups, summary, len(performance_eligible)),+ # The stored performance summary is a repo-wide aggregate and there+ # is no narrowed copy of it, so a narrowed field omits the block+ # rather than serving repo-wide totals beside production-only rows.+ performance=(+ None+ if scope_narrowed+ else self._performance_block(rollups, summary, len(performance_eligible))+ ),+ scope=DEFAULT_SCOPE if not scope_narrowed else "production",)def _row(diff --git a/packages/types/src/generated/http.ts b/packages/types/src/generated/http.tsindex a75ed634e..6cc6c147d 100644--- a/packages/types/src/generated/http.ts+++ b/packages/types/src/generated/http.ts@@ -1543,12 +1543,15 @@ export interface HealthTrendAlert {baseline?: number | null;delta: number;message: string;+ driver?: string | null;+ structure_delta?: number | null;+ history_delta?: number | null;}/** One snapshot in the repo-level history, newest first. */export interface HealthTrendKpiRow {taken_at?: string | null;- hotspot_health: number;+ hotspot_health?: number | null;average_health: number;worst_performer_path?: string | null;worst_performer_score?: number | null;@@ -1561,15 +1564,18 @@ export interface HealthTrendResponse {file_deltas?: HealthFileDelta[];file_deltas_total?: number;snapshot_count?: number;+ scope?: string;}export interface HealthTrendSummary {- current_hotspot_health: number;+ current_hotspot_health?: number | null;current_average_health: number;previous_hotspot_health?: number | null;previous_average_health?: number | null;hotspot_delta?: number | null;average_delta?: number | null;+ current_structure_deduction?: number | null;+ current_history_deduction?: number | null;}/** One file in the triage queue, ranked by impact over effort. */diff --git a/packages/types/src/health.ts b/packages/types/src/health.tsindex 732f05906..e920405a4 100644--- a/packages/types/src/health.ts+++ b/packages/types/src/health.ts@@ -48,9 +48,18 @@ export const HEALTH_DIMENSIONS: readonly HealthDimension[] = ["performance",] as const;+/**+ * Which half of a repository a health figure describes. Tests score higher+ * than production code, so narrowing lowers every figure without a defect+ * having been found — `all` is the default for that reason.+ */+export type HealthScope = "all" | "production";++export const HEALTH_SCOPES: readonly HealthScope[] = ["all", "production"] as const;+/** Display labels for the dimensions surfaced today. */export const HEALTH_DIMENSION_LABEL: Record<HealthDimension, string> = {- defect: "Defect risk",+ defect: "Code health",maintainability: "Maintainability",performance: "Performance",};@@ -179,6 +188,20 @@ export interface HealthFileMetric {defect_score?: number | null;maintainability_score?: number | null;performance_score?: number | null;+ /**+ * The defect deduction split into the half a rewrite can move (code shape)+ * and the half only time can (git history). They sum to the total deduction,+ * so `unclamped_score` is `10 - structure - history` — the only number that+ * moves for a file held at the score floor. Absent on older payloads.+ */+ structure_deduction?: number | null;+ history_deduction?: number | null;+ unclamped_score?: number | null;+ /**+ * Test material, decided at ingestion. Drives the production/all scope+ * without re-deriving the answer from the path on every surface.+ */+ is_test?: boolean;/*** Open performance-risk findings on this file. The performance lens on the* code-health map colors by this count (+ `performance_analyzed`), not by the@@ -779,18 +802,23 @@ export interface FileHealthTrend {export interface HealthTrendResponse {history: Array<{taken_at: string | null;- hotspot_health: number;+ /** `null` under a narrowed scope, which recorded only the average. */+ hotspot_health: number | null;average_health: number;worst_performer_path: string | null;worst_performer_score: number | null;}>;summary: {- current_hotspot_health: number;+ /** `null` under a narrowed scope: only the average covers both populations. */+ current_hotspot_health: number | null;current_average_health: number;previous_hotspot_health: number | null;previous_average_health: number | null;hotspot_delta: number | null;average_delta: number | null;+ /** The newest reading's two halves, in deduction points. */+ current_structure_deduction?: number | null;+ current_history_deduction?: number | null;};alerts: Array<{kind: string;@@ -799,6 +827,15 @@ export interface HealthTrendResponse {baseline: number | null;delta: number;message: string;+ /**+ * Which half of the headline moved, and how far each half moved in score+ * points. These are changes in mean deduction, so they sum to `delta` only+ * while no file sits at the score floor. `null` on the hotspot metric,+ * whose halves are not snapshotted, and on histories predating the split.+ */+ driver?: "structure" | "history" | null;+ structure_delta?: number | null;+ history_delta?: number | null;}>;/** Largest movements first, in either direction, capped server-side. */file_deltas: Array<{@@ -813,6 +850,8 @@ export interface HealthTrendResponse {*/file_deltas_total?: number;snapshot_count: number;+ /** Which half of the repository these figures describe. */+ scope?: HealthScope;}/* ------------------------------------------------------------------ *diff --git a/packages/ui/src/chat/artifacts.tsx b/packages/ui/src/chat/artifacts.tsxindex 245d44b72..c6796f063 100644--- a/packages/ui/src/chat/artifacts.tsx+++ b/packages/ui/src/chat/artifacts.tsx@@ -1017,7 +1017,8 @@ export function HealthRenderer({ data }: { data: Record<string, unknown> }) {["hotspot health", kpis.hotspot_health ?? data.hotspot_health],["maintainability", kpis.maintainability_average ?? data.maintainability_average],["performance", kpis.performance_average ?? data.performance_average],- ["code-only health", kpis.average_health_code_only ?? data.average_health_code_only],+ ["structure deduction", kpis.structure_average ?? data.structure_average],+ ["history deduction", kpis.history_average ?? data.history_average],["worst performer", kpis.worst_performer_score ?? data.worst_performer_score],].filter((entry): entry is [string, unknown] => entry[1] !== undefined && entry[1] !== null);const rows = findings.length > 0 ? findings : files;diff --git a/packages/ui/src/health/trend-chart.tsx b/packages/ui/src/health/trend-chart.tsxindex 620530a53..4efc051ba 100644--- a/packages/ui/src/health/trend-chart.tsx+++ b/packages/ui/src/health/trend-chart.tsx@@ -4,7 +4,8 @@ import { formatDate } from "../lib/format";export interface TrendSeriesPoint {taken_at: string | null;- hotspot_health: number;+ /** `null` under a narrowed scope, which records only the average. */+ hotspot_health: number | null;average_health: number;worst_performer_score: number | null;}@@ -78,7 +79,9 @@ export function TrendChart({ history, height = 220 }: TrendChartProps) {{history.map((p, i) => (<g key={i}><circle cx={xScale(i)} cy={yScale(p.average_health)} r={2.5} fill="var(--color-success)" />- <circle cx={xScale(i)} cy={yScale(p.hotspot_health)} r={2.5} fill="var(--color-warning)" />+ {p.hotspot_health != null ? (+ <circle cx={xScale(i)} cy={yScale(p.hotspot_health)} r={2.5} fill="var(--color-warning)" />+ ) : null}{p.worst_performer_score != null ? (<circle cx={xScale(i)} cy={yScale(p.worst_performer_score)} r={2} fill="var(--color-error)" />) : null}diff --git a/packages/ui/src/health/trend-view.tsx b/packages/ui/src/health/trend-view.tsxindex 2b108a1b1..054d18557 100644--- a/packages/ui/src/health/trend-view.tsx+++ b/packages/ui/src/health/trend-view.tsx@@ -64,6 +64,11 @@ export function TrendView({return `${formatDelta(delta)} vs. ${previous?.toFixed(1) ?? "—"}`;};+ // Absent under a narrowed scope: only the average was recorded for both+ // populations, so a repo-wide hotspot figure would describe files this view+ // has dropped. Say so rather than printing one.+ const hotspot = summary.current_hotspot_health;+const stats: RibbonStat[] = [{label: "Average health",@@ -76,10 +81,13 @@ export function TrendView({},{label: "Hotspot health",- value: summary.current_hotspot_health.toFixed(1),- valueColor: scoreTextColor(summary.current_hotspot_health),- sub: deltaSub(summary.hotspot_delta, summary.previous_hotspot_health),- ...(Math.abs(summary.hotspot_delta ?? 0) >= 0.05+ value: hotspot == null ? "—" : hotspot.toFixed(1),+ ...(hotspot == null ? {} : { valueColor: scoreTextColor(hotspot) }),+ sub:+ hotspot == null+ ? "not measured for this scope"+ : deltaSub(summary.hotspot_delta, summary.previous_hotspot_health),+ ...(hotspot != null && Math.abs(summary.hotspot_delta ?? 0) >= 0.05? { subColor: deltaColor(summary.hotspot_delta) }: {}),},diff --git a/packages/vscode/src/core/webviewApi.ts b/packages/vscode/src/core/webviewApi.tsindex 34edd5c60..597692685 100644--- a/packages/vscode/src/core/webviewApi.ts+++ b/packages/vscode/src/core/webviewApi.ts@@ -229,10 +229,14 @@ export function createHostApi(ctx: RepowiseContext, epoch: () => number): HostApopenFindings: summary.open_findings,band: summary.band ?? null,hotspotDelta: trendVal?.summary?.hotspot_delta ?? null,+ // A snapshot only carries a hotspot figure for the whole+ // repository, so a reading without one is dropped rather than+ // plotted at zero.history: (trendVal?.history ?? []).slice().reverse()- .map((p) => p.hotspot_health),+ .map((p) => p.hotspot_health)+ .filter((v): v is number => v !== null),}: null,counts: {diff --git a/tests/unit/server/mcp/test_health.py b/tests/unit/server/mcp/test_health.pyindex 85174d161..be8e28389 100644--- a/tests/unit/server/mcp/test_health.py+++ b/tests/unit/server/mcp/test_health.py@@ -1868,50 +1868,104 @@ async def test_a_gradient_only_file_still_leads_with_the_gradient(setup_mcp, ses@pytest.mark.asyncio-async def test_kpis_report_how_much_of_the_headline_is_non_code(setup_mcp, session, populated_db):- """Markdown and JSON rows score a mechanical 10.0 and lift the average.-- No biomarker walks a non-code file, so its 10.0 means "nothing looked at- this" — the same fabricated-10.0 problem the perf pillar already surfaces- rather than hides. Measured on the live index: 233 of 3,314 rows are- non-code, 221 of them score exactly 10.0, and they lift ``average_health``- from 7.31 to 7.47, so a repo can raise its score by adding documentation.- Surfaced rather than subtracted — ``average_health`` is what the badge, the- snapshots and the web UI read, and redefining it here alone would make this- tool disagree with all of them.+async def test_the_headline_averages_code_and_nothing_else(setup_mcp, session, populated_db):+ """Prose and configuration carry no score, so they cannot lift the average.++ They used to: no marker walks a Markdown file, so its mechanical 10.0 meant+ "nothing looked at this" and a repo could raise its score by writing+ documentation. Measured on this repo, 293 of 4,064 rows were non-code and+ they lifted the headline 6.92 -> 6.96. The analyzer now writes no row for+ them at all, so there is no split to report and no ``non_code_files`` count+ to explain away."""from repowise.core.persistence.crud import save_health_metricsfrom repowise.server.mcp_server import get_health+ await save_health_metrics(+ session,+ populated_db,+ [{"file_path": "src/auth/service.py", "score": 4.0, "nloc": 100, "max_ccn": 9}],+ )+ kpis = (await get_health())["kpis"]+ assert kpis["file_count"] == 1+ assert kpis["average_health"] == 4.0+ assert "non_code_files" not in kpis+ assert "average_health_code_only" not in kpis+++async def test_scope_narrows_every_figure_to_production(setup_mcp, session, populated_db):+ """``scope`` is one filter over the whole response, not a per-block option."""+ from repowise.core.persistence.crud import save_health_metrics+ from repowise.server.mcp_server import get_health+await save_health_metrics(session,populated_db,[- {"file_path": "src/auth/service.py", "score": 4.0, "nloc": 100, "max_ccn": 9},- # No graph node → no language → not in LANGUAGE_MAPS → non-code.- {"file_path": "docs/CHANGELOG.md", "score": 10.0, "nloc": 100, "max_ccn": 0},+ {"file_path": "src/auth/service.py", "score": 4.0, "nloc": 100, "is_test": False},+ {"file_path": "tests/test_auth.py", "score": 10.0, "nloc": 100, "is_test": True},],)- kpis = (await get_health())["kpis"]- assert kpis["file_count"] == 2- assert kpis["non_code_files"] == 1- assert kpis["average_health"] == 7.0- assert kpis["average_health_code_only"] == 4.0+ everything = await get_health()+ assert everything["scope"] == "all"+ assert everything["kpis"]["average_health"] == 7.0+ assert everything["kpis"]["file_count"] == 2++ production = await get_health(scope="production")+ assert production["scope"] == "production"+ assert production["kpis"]["average_health"] == 4.0+ assert production["kpis"]["file_count"] == 1+ assert all(+ row["file_path"] != "tests/test_auth.py" for row in production.get("worst_files", [])+ )@pytest.mark.asyncio-async def test_non_code_split_is_gated_on_the_language_read(setup_mcp, health_data):- """The split rides the language map ``kpis`` already reads — it adds no query.+async def test_a_narrowed_target_is_not_reported_as_config_excluded(+ setup_mcp, session, populated_db+):+ """``excluded`` means the repo's exclude config dropped the file.- So it appears only where that read happens: dashboard mode with ``kpis``- surviving the projection. ``only=["directive"]`` stays the cheapest useful- call, and targeted mode (which serves no ``kpis`` block at all) is unchanged.+ Narrowing to production drops files for an unrelated reason, and telling a+ caller their config did it sends them to edit something irrelevant."""+ from repowise.core.persistence.crud import save_health_metricsfrom repowise.server.mcp_server import get_health- assert "kpis" not in await get_health(targets=["src/auth/service.py"])- assert "kpis" not in await get_health(only=["directive"])- assert "non_code_files" in (await get_health())["kpis"]+ await save_health_metrics(+ session,+ populated_db,+ [+ {"file_path": "src/auth/service.py", "score": 4.0, "nloc": 100, "is_test": False},+ {"file_path": "tests/test_auth.py", "score": 10.0, "nloc": 100, "is_test": True},+ ],+ )+ result = await get_health(targets=["tests/test_auth.py"], scope="production")+ reasons = {row["reason"] for row in result.get("unresolved", [])}+ assert "excluded" not in reasons+++async def test_the_directive_names_a_cause_an_edit_can_remove(setup_mcp, health_data):+ """``fix_first`` is an instruction, so its ``reason`` has to be actionable.++ History markers carry the largest caps, so the highest-leverage file is+ often led by one. Naming it there tells the caller to fix something no edit+ resolves; it belongs in ``watch``.+ """+ from repowise.core.analysis.health.models import split_by_origin+ from repowise.server.mcp_server import get_health++ directive = (await get_health())["directive"]+ reason_marker = directive.get("reason")+ assert directive["fix_first"]+ watch = directive.get("watch")+ if watch is not None:+ marker = type("F", (), {"biomarker_type": watch["biomarker"]})+ code_shape, _ = split_by_origin([marker])+ assert not code_shape, "watch must carry a history marker, never a code-shape one"+ assert watch["biomarker"] not in (reason_marker or "")@pytest.mark.asyncio