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
refactor(server): decompose get_health into a thin dispatcher (#2546)
Raghav Chamadiya3f14dbd42ff7
diff --git a/docs/architecture/code-health.md b/docs/architecture/code-health.mdindex 615addab7..1027e0e90 100644--- a/docs/architecture/code-health.md+++ b/docs/architecture/code-health.md@@ -158,7 +158,7 @@ cli/src/repowise/cli/commands/```server/src/repowise/server/├── mcp_server/-│ ├── tool_health.py # @mcp.tool get_health(targets, include, repo, limit)+│ ├── tool_health/ # @mcp.tool get_health(targets, include, repo, limit)│ ├── tool_risk.py # enriched: health_score, top_biomarkers, coverage_pct│ ├── tool_context.py # include=["health"]: score, top 2 biomarkers, suggestion│ └── tool_overview.py # code_health block with KPIs@@ -725,7 +725,7 @@ silently re-scored for changed files only.### `get_health(targets?, include?, repo?, limit?)`-Defined in `tool_health.py`. Modes:+Defined in `tool_health/tool.py`, which dispatches to one module per mode and block. Modes:- **Dashboard mode** (`targets=None`): returns repo-level KPIs (with therepo `band`) + the NLOC-weighted `distribution` across the bands +@@ -974,7 +974,7 @@ phases may revisit; the constraints kept v1 shippable.| Change the suggestion text for a marker | `suggestions._TEMPLATES` || Adjust the trend-alert threshold | `trends.DECLINE_THRESHOLD` / `DECLINE_LOOKBACK` || Change snapshot retention | `crud.HEALTH_SNAPSHOT_RETENTION` |-| Add a new MCP `include` flag | `tool_health.py`: append handling near the existing `"coverage"` / `"refactoring"` branches |+| Add a new MCP `include` flag | `tool_health/`: name it in `request.py`, read it in `loading.py`, render it in `blocks.py` beside the existing `"coverage"` / `"refactoring"` blocks || Add a new REST route | `routers/code_health.py`: auth is wired at the router level || Add a new dashboard view | new file under `packages/web/src/app/repos/[id]/health/`, primitives under `packages/ui/src/health/` || Add a CLI flag | `packages/cli/src/repowise/cli/commands/health_cmd.py` |diff --git a/packages/core/src/repowise/core/analysis/health/README.md b/packages/core/src/repowise/core/analysis/health/README.mdindex 5405baddf..e200cbac1 100644--- a/packages/core/src/repowise/core/analysis/health/README.md+++ b/packages/core/src/repowise/core/analysis/health/README.md@@ -141,7 +141,7 @@ the analyzer engine.`HealthFileMetric.module` is populated from graph community labels by theorchestrator (falls back to the top-level directory). The MCP tool-(`tool_health.py`) and the API endpoint (`routers/code_health/`) both call+(`tool_health/`) and the API endpoint (`routers/code_health/`) both call`aggregation.module_rollups` for NLOC-weighted module aggregates and accept`module:foo` targets.@@ -192,7 +192,7 @@ parallel path automatically when `len(parsed_files) >= 500`.- CLI: `packages/cli/src/repowise/cli/commands/health_cmd.py`,`status_cmd.py`, `update_cmd.py`.-- MCP tools: `packages/server/src/repowise/server/mcp_server/tool_health.py`+- MCP tools: `packages/server/src/repowise/server/mcp_server/tool_health/`+ enrichments in `tool_risk.py`, `tool_context.py`, `tool_overview.py`.- API: `packages/server/src/repowise/server/routers/code_health.py`.- UI primitives: `packages/ui/src/health/`. Web routes:diff --git a/packages/server/src/repowise/server/mcp_server/tool_health.py b/packages/server/src/repowise/server/mcp_server/tool_health.pydeleted file mode 100644index 910610102..000000000--- a/packages/server/src/repowise/server/mcp_server/tool_health.py+++ /dev/null@@ -1,3156 +0,0 @@-"""MCP tool: get_health — code-health markers and per-file scores."""--from __future__ import annotations--import hashlib-import json-from dataclasses import asdict, dataclass, field-from pathlib import Path-from time import perf_counter-from typing import Any--from sqlalchemy import func, select-from sqlalchemy.exc import SQLAlchemyError--from repowise.core.analysis.doc_drift.constants import (- DETECTION_BASIS,- UNAVAILABLE_NO_TABLE,-)-from repowise.core.analysis.health.aggregation import module_rollups as _module_rollups-from repowise.core.analysis.health.churn_complexity import churn_complexity_points-from repowise.core.analysis.health.counts import (- DEFAULT_COUNTS,- parse_counts,-)-from repowise.core.analysis.health.counts import (- project as project_counts,-)-from repowise.core.analysis.health.coverage import decay_since, measurement_ref-from repowise.core.analysis.health.defect_accuracy import compute_defect_accuracy-from repowise.core.analysis.health.finding_identity import finding_public_id-from repowise.core.analysis.health.grading import TARGET_SCORE, band_for-from repowise.core.analysis.health.grading import distribution as health_distribution-from repowise.core.analysis.health.models import primary_finding, split_by_origin-from repowise.core.analysis.health.perf.coverage import PerfCoverage, coverage_for_metrics-from repowise.core.analysis.health.perf.opportunity_rank import (- NON_LEADING_MARKERS,- observation_rank,-)-from repowise.core.analysis.health.ranking import deduction_by_path, sort_metrics_worst_first-from repowise.core.analysis.health.refactoring.recommendations import (- Recommendation,- build_recommendations,- hydrate_recommendations,-)-from repowise.core.analysis.health.scope import DEFAULT_SCOPE, parse_scope-from repowise.core.analysis.health.scoring import (- ALL_DIMENSIONS,- hotspot_health,- nloc_weighted_attr,-)-from repowise.core.analysis.health.semantics import health_semantics_contract-from repowise.core.analysis.health.signals import file_signals-from repowise.core.analysis.health.suggestions import suggestion_for-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_TYPES-from repowise.core.persistence.crud import (- get_all_git_metadata,- get_coverage_summary,- get_doc_drift_findings,- get_file_language_map,- get_git_metadata_bulk,- get_health_finding_by_public_id,- get_hotspot_file_paths,- get_node_degree_counts_bulk,- get_refactoring_suggestions,- get_test_file_paths,- list_health_snapshots,- load_coverage_for_repo,- serialize_doc_drift_row,- summarize_confidence_rows,-)-from repowise.core.persistence.database import get_session-from repowise.core.persistence.models import (- HealthFileMetric,- HealthFinding,- RefactoringSuggestion,-)-from repowise.core.registry import ToolRecipe-from repowise.core.registry import mcp_tool_registry as mcp-from repowise.server.mcp_server._budget import (- OmissionCollector,- register_post_enforce,- register_post_shed,-)-from repowise.server.mcp_server._helpers import (- _get_exclude_spec,- _get_repo,- _resolve_repo_context,- filter_rows_by_attr,-)-from repowise.server.mcp_server._meta import build_meta as _build_meta-from repowise.server.mcp_server._references import (- path_identity,- refactoring_plan_id,- stable_entity_id,-)-from repowise.server.services.performance_health import (- PerformanceHealthService,- PerformancePage,- evidence_block,- parse_query,-)-from repowise.server.services.refactoring_health import CANONICAL_VIEWS as _REFACTORING_VIEWS-from repowise.server.services.refactoring_health import DEFAULT_VIEW as _REFACTORING_VIEW_DEFAULT-from repowise.server.services.refactoring_health import (- RefactoringHealthService,- plan_view,-)-from repowise.server.services.refactoring_health import (- parse_query as parse_refactoring_query,-)--# The opportunity id space is shared with the performance pillar's, and told-# apart by prefix alone, so ``opportunity_id`` stays one selector.-_REFACTORING_OPPORTUNITY_PREFIX = "refop"--_REFACTORING_COLLECTION_CAP = 6-"""Opportunities per response, independent of ``limit``. ``cursor`` pages it."""--_REFACTORING_STEP_CAP = 3-"""Steps per row in the queue. The detail call pages the rest."""--_REFACTORING_STEP_PAGE_CAP = 20-"""Ceiling on one page of a detail call's ordered steps."""--_REFACTORING_EVIDENCE_CAP = 3-"""Evidence rows beside a detail response. ``only=['refactoring_evidence']`` pages more."""--_REFACTORING_EVIDENCE_PAGE_CAP = 20-"""Ceiling on one evidence page."""--_PERFORMANCE_COLLECTION_CAP = 6-"""Opportunities per response, independent of ``limit``. ``cursor`` pages it."""--_PERFORMANCE_EVIDENCE_CAP = 3-"""Evidence rows per opportunity in the collection. The detail call pages more."""--_PERFORMANCE_EVIDENCE_PAGE_CAP = 20-"""Ceiling on one evidence page. ``limit`` still means what it says below it,-including ``limit=0`` for the totals and no rows."""---def _selector_conflict(**selectors: str | None) -> dict[str, Any] | None:- """Refuse two detail selectors instead of answering about one of them.-- Preferring whichever was checked first gave a caller a confident answer to- a question they had not only asked, with no sign the other was dropped.- """- named = sorted(name for name, value in selectors.items() if value)- if len(named) < 2:- return None- return {- "mode": "conflict",- "resolved": False,- "reason": "mutually_exclusive_selectors",- "selectors": named,- "detail": "Pass exactly one of finding_id, plan_id, opportunity_id.",- }---def _note_inapplicable_controls(- result: dict[str, Any], scope: str, counts: str-) -> dict[str, Any]:- """Name ``scope`` / ``counts`` when a detail lookup cannot honour them.-- These select a population; a lookup by id answers about one stored row and- is always the calibrated reading. Silently accepting the control returned- that row to a caller who believes they asked for a different one.- """- inapplicable = {- name: value- for name, value, default in (- ("scope", scope, DEFAULT_SCOPE),- ("counts", counts, DEFAULT_COUNTS),- )- if value is not None and value != default- }- if inapplicable:- result["ignored_arguments"] = {**result.get("ignored_arguments", {}), **inapplicable}- return result---@dataclass(frozen=True, slots=True)-class _PerformanceBlocks:- """Everything the performance pillar contributes to one response."""-- page: PerformancePage | None = None- summary: dict[str, Any] | None = None- directive: dict[str, Any] | None = None- ignored: dict[str, str] = field(default_factory=dict)---async def _performance_blocks(- service: PerformanceHealthService,- *,- wants: Any,- included: bool,- file_paths: tuple[str, ...] | None,- scoped: bool,- limit: int,- cursor: int,- view: str | None,- context: str | None,- boundary: str | None,- confidence: str | None,- actionability: str | None,- sort: str | None,-) -> _PerformanceBlocks:- """Read the materialized queue, its rollup, and the dashboard lead.-- Each block is gated on surviving the projection, so a caller that asked for- one of the three does not pay for the other two.- """- page = None- query = None- ignored: dict[str, str] = {}- if included:- # The lede quotes only the first row and no evidence, so a projection- # down to it reads one row rather than a page of six.- emits_queue = wants("performance_opportunities")- query, ignored = parse_query(- context=context,- boundary=boundary,- confidence=confidence,- actionability=actionability,- view=view,- sort=sort,- file_paths=file_paths,- limit=min(max(limit, 0), _PERFORMANCE_COLLECTION_CAP) if emits_queue else 1,- offset=cursor if emits_queue else 0,- )- page = await service.page(- query,- evidence_per_item=_PERFORMANCE_EVIDENCE_CAP if emits_queue else 0,- # Facets are rendered by the summary block alone, so a queue or a- # lede does not pay for the aggregate.- with_facets=wants("performance_summary"),- )- return _PerformanceBlocks(- page=page,- summary=(- # Scoped to the same context as the queue beside it, so two blocks- # in one answer cannot state totals that contradict each other.- await service.summary(query.contexts if query else None)- if included and wants("performance_summary")- else None- ),- # The bare dashboard lead: one primary-key read of the current summary- # row, so it does not grow with the repository and never touches the- # queue.- directive=(- await service.directive() if not scoped and wants("performance_directive") else None- ),- ignored=ignored,- )---async def _resolve_finding(- session: Any, repository_id: str, finding_id: str, repository: str-) -> Any:- """Find one health finding by any id form a caller can be holding.-- The public id is a column, so the common case is a seek. The scan is the- compatibility path: a raw storage id, or an id minted before the column- existed, still has to resolve.- """- match = await get_health_finding_by_public_id(session, repository_id, finding_id)- if match is not None:- return match- rows = (- (- await session.execute(- select(HealthFinding).where(- HealthFinding.repository_id == repository_id,- HealthFinding.status == "open",- )- )- )- .scalars()- .all()- )- return next(- (- row- for row in rows- if finding_id- in {- row.id,- _health_finding_id(row, repository),- _legacy_health_finding_id(row, repository),- }- ),- None,- )---@dataclass(frozen=True, slots=True)-class _RefactoringBlocks:- """Everything the refactoring pillar contributes to one response."""-- page: Any = None- summary: dict[str, Any] | None = None- directive: dict[str, Any] | None = None- ignored: dict[str, str] = field(default_factory=dict)---async def _refactoring_blocks(- service: RefactoringHealthService,- *,- wants: Any,- included: bool,- file_paths: tuple[str, ...] | None,- scoped: bool,- limit: int,- cursor: int,- view: str,- lead_type: str | None = None,- confidence: str | None = None,- effort: str | None = None,-) -> _RefactoringBlocks:- """Read the materialized queue, its rollup, and the dashboard lead.-- Each block is gated on surviving the projection, so a caller that asked for- one of the three does not pay for the other two.- """- page = None- ignored: dict[str, str] = {}- # A scope that resolved to no file is not the dashboard. The queue below- # honours it through an ``IN ()``, but the rollup and its facets are read- # by repository id and have no scope to honour, so they have to be withheld- # rather than filtered — the same reason ``directive`` is dashboard-only.- resolved_scope = not (scoped and not file_paths)- rollup_wanted = included and wants("refactoring_summary") and resolved_scope- if included:- emits_queue = wants("refactoring_opportunities")- query, ignored = parse_refactoring_query(- view=view,- lead_type=lead_type,- confidence=confidence,- effort=effort,- file_paths=list(file_paths) if file_paths is not None else None,- limit=min(max(limit, 0), _REFACTORING_COLLECTION_CAP) if emits_queue else 1,- offset=cursor if emits_queue else 0,- )- page = await service.page(- query,- steps_per_item=_REFACTORING_STEP_CAP if emits_queue else 0,- with_facets=rollup_wanted,- )- return _RefactoringBlocks(- page=page,- summary=await service.summary() if rollup_wanted else None,- # The dashboard lead only. A targeted call is already about a file the- # caller named, so pointing it at the repository's worst file elsewhere- # would be answering a question nobody asked.- directive=(- await service.directive()- if not scoped and wants("refactoring_directive")- else None- ),- ignored=ignored,- )---async def _performance_detail_response(- session: Any,- repository: Any,- reference_repository: str,- opportunity_id: str,- *,- evidence_only: bool,- limit: int,- cursor: int,-) -> dict[str, Any]:- """One causal opportunity, or one page of the evidence behind it.-- ``limit`` means what it means everywhere else, ``0`` included: reading it- as "unset" would return a page the caller declined.- """- service = PerformanceHealthService(session, repository.id, reference_repository)- evidence_limit = min(max(limit, 0), _PERFORMANCE_EVIDENCE_PAGE_CAP)- if evidence_only:- rows, total = await service.evidence(- opportunity_id, limit=evidence_limit, offset=cursor- )- return {- "mode": "performance_evidence",- "opportunity_id": opportunity_id,- "resolved": total > 0,- **evidence_block(rows, total, cursor),- "_meta": _build_meta(repository=repository),- }- detail = await service.detail(opportunity_id, evidence_limit=evidence_limit)- file_path = detail.get("file_path")- result = {- "mode": "performance_opportunity",- **detail,- "_meta": _build_meta(- repository=repository, targets=[file_path] if file_path else None- ),- }- await _attach_repository_analysis_meta(session, repository, result["_meta"])- return result---async def _refactoring_detail_response(- session: Any,- repository: Any,- reference_repository: str,- opportunity_id: str,- *,- evidence_only: bool,- limit: int,- cursor: int,-) -> dict[str, Any]:- """One composed opportunity, or one page of the evidence behind it."""- service = RefactoringHealthService(session, repository.id, reference_repository)- if evidence_only:- detail = await service.detail(- opportunity_id,- step_limit=0,- evidence_limit=min(max(limit, 0), _REFACTORING_EVIDENCE_PAGE_CAP),- evidence_offset=cursor,- with_plans=False,- )- block = {k: v for k, v in detail.items() if k.startswith("evidence")}- result = {- "mode": "refactoring_evidence",- "opportunity_id": opportunity_id,- "resolved": bool(detail.get("resolved")),- **block,- "_meta": _build_meta(repository=repository),- }- if block.get("evidence_next_cursor") is not None:- result["recovery"] = {- "evidence": {- "remaining": block["evidence_total"] - block["evidence_next_cursor"],- "call": (- f"get_health(opportunity_id={opportunity_id!r}, "- f"only=['refactoring_evidence'], limit={limit}, "- f"cursor={block['evidence_next_cursor']})"- ),- }- }- return result- detail = await service.detail(- opportunity_id,- step_limit=min(max(limit, 0), _REFACTORING_STEP_PAGE_CAP),- step_offset=cursor,- evidence_limit=_REFACTORING_EVIDENCE_CAP,- )- file_path = detail.get("file_path")- if not detail.get("resolved"):- detail.setdefault(- "model_state", _refactoring_model_state(opportunity_id)- )- result = {- "mode": "refactoring_opportunity",- **detail,- "_meta": _build_meta(- repository=repository, targets=[file_path] if file_path else None- ),- }- await _attach_repository_analysis_meta(session, repository, result["_meta"])- return result---def _refactoring_model_state(opportunity_id: str) -> dict[str, Any]:- """Tell a stale-model id apart from a wrong one, from the string alone."""- from repowise.core.analysis.health.refactoring.identity import (- REFACTORING_MODEL_VERSION,- model_state,- )-- state = model_state(- opportunity_id.replace(_REFACTORING_OPPORTUNITY_PREFIX, "refac", 1)- )- state["public_id"] = opportunity_id- state["refactoring_model_version"] = REFACTORING_MODEL_VERSION- return state---def _perf_rank(biomarker_type: str | None, details: Any) -> int:- """Order-of-magnitude ordering key for one ``performance`` finding.-- Every performance finding carries ``health_impact: 0`` by construction, so- without a key the list came back in file order and "which of these matters"- was unanswerable from the payload.-- The weights live with the opportunity ranking rather than here. Two tables- used to answer "which marker costs more" and they had already drifted apart- on markers both named, so a finding and the opportunity built from it could- disagree about the same evidence. Nothing here is blended into ``score`` or- ``performance_score``; a caller who disagrees can re-rank from- ``biomarker_type`` and ``details`` on the same row.- """- if not isinstance(details, dict):- details = {}- return observation_rank(- biomarker_type, details.get("boundary_kind"), bool(details.get("cross_function"))- )---def _rank_emitted(rows: list[Any]) -> list[Any]:- """Break the ``health_impact`` ties that the performance dimension is made of.-- Rows arrive impact-ordered from SQL, which decides nothing among the- performance findings: they all carry ``0``, so the head was whatever the tie- broke to — file order. This re-sorts **within** each impact tier, so the- defect ordering every other block is built on is untouched (identical- impacts were already interchangeable) and the perf tier stops being- alphabetical.-- ``file_path`` is the final key so the order is total and reproducible; two- findings that rank the same used to swap places between calls on nothing.- Rows with no ``details_json`` attribute — the narrow dashboard read, unless- the caller filtered to ``performance`` — rank on the marker alone, which is- exactly the tier where the rank cannot move a row anyway.- """- if not rows:- return rows-- def key(r: Any) -> tuple[float, int, str]:- impact = float(getattr(r, "health_impact", 0.0) or 0.0)- dimension = getattr(r, "dimension", None) or "defect"- if dimension != "performance":- return (-impact, 0, getattr(r, "file_path", "") or "")- raw = getattr(r, "details_json", None)- try:- details = json.loads(raw) if raw else {}- except Exception:- details = {}- return (- -impact,- -_perf_rank(getattr(r, "biomarker_type", None), details),- getattr(r, "file_path", "") or "",- )-- return sorted(rows, key=key)---def _health_finding_id(f: Any, repository: str) -> str:- """The finding's public id: the stored one, else the same kernel recomputed.-- Storage row ids are republished on every analysis, so they cannot be quoted- back. This is the id evidence carries and the ``finding_id`` selector- resolves, and it is a column, so resolving it is a seek.- """- stored = getattr(f, "public_id", None)- return stored if isinstance(stored, str) and stored else finding_public_id(f)---def _legacy_health_finding_id(f: Any, repository: str) -> str:- """The pre-column id form, still accepted so a quoted one keeps resolving.-- Its kernel held generated prose and derived detail keys, so it moved- whenever a detector reworded itself or a later model changed its mind.- """- try:- details = json.loads(f.details_json) if f.details_json else {}- except (TypeError, json.JSONDecodeError):- details = str(f.details_json or "")- return stable_entity_id(- "finding",- repository,- {- "family": "health",- "path": path_identity(f.file_path),- "kind": f.biomarker_type,- "symbol": f.function_name or "",- "line_start": f.line_start,- "line_end": f.line_end,- "reason": f.reason or "",- "details": details,- },- )---def _serialize_finding(f: HealthFinding, repository: str = "default") -> dict[str, Any]:- try:- details = json.loads(f.details_json) if f.details_json else {}- except Exception:- details = {}- dimension = getattr(f, "dimension", None) or "defect"- rank = (- {"perf_rank": _perf_rank(f.biomarker_type, details)} if dimension == "performance" else {}- )- return {- "id": _health_finding_id(f, repository),- "repository": repository,- "biomarker_type": f.biomarker_type,- "severity": f.severity,- "file_path": f.file_path,- # A file-level finding has no symbol and no line span. Absent rather- # than null, on the same rule as ``rank`` below: three null keys on- # every such row is a bill, not a disclosure.- **({"function_name": f.function_name} if f.function_name else {}),- **({"line_start": f.line_start} if f.line_start is not None else {}),- **({"line_end": f.line_end} if f.line_end is not None else {}),- "health_impact": round(f.health_impact, 3),- "reason": f.reason,- "details": details,- "status": f.status,- # Health pillar this finding homes under (defect / maintainability /- # performance) for per-dimension filtering.- "dimension": dimension,- # Performance rows only — see ``_perf_rank``. Absent everywhere else- # rather than zero: a defect finding ranks on ``weighted_deficit`` and a- # 0 here would read as "measured, and it is nothing".- **rank,- }---def _refactoring_plan_id(r: Any, repository: str) -> str:- """Unwrap a hydrated recommendation, then defer to the identity owner."""- return refactoring_plan_id(r.suggestion if isinstance(r, Recommendation) else r, repository)---def _serialize_refactoring(- r: Any, repository: str | None = None-) -> dict[str, Any]:- """Compatibility adapter; request paths hydrate through the async service."""- if isinstance(r, Recommendation):- payload = r.as_dict()- else:- payload = build_recommendations([r])[0].as_dict()- if repository is not None:- payload["id"] = _refactoring_plan_id(r, repository)- payload["repository"] = repository- return payload---# ``include`` and ``only`` were different vocabularies: the block a caller-# switches on with ``include=["biomarkers"]`` lands under the key ``findings``,-# so the obvious ``only=["biomarkers"]`` projected it away again. Alias the three-# that have a 1:1 key rather than make the caller learn two names for one block.-# ``signals`` is deliberately absent — it has no top-level key to alias to, it-# merges into ``metrics[].signals``, so it stays reported in ``unknown_only_keys``.-_ONLY_ALIASES = {- "biomarkers": "findings",- "accuracy": "defect_accuracy",- "refactoring": "refactoring_plans",-}--# Files the directive reduces over: ``fix_first`` plus the two in ``then``. Named-# because three separate places have to agree on it — the plan lookup, the lead-# set the directive reads, and the directive itself — and they are far apart.-_DIRECTIVE_CANDIDATES = 3---def _stamp_collection(- result: dict[str, Any],- key: str,- *,- total: int | None = None,- reason: str = "limit",-) -> None:- """Attach complete-population accounting to one emitted collection."""- rows = result.get(key)- if not isinstance(rows, list):- return- eligible = len(rows) if total is None else total- emitted = len(rows)- result[f"{key}_total"] = eligible- result[f"{key}_emitted"] = emitted- if emitted < eligible:- result[f"{key}_reduced_reason"] = reason---def _validation_profile(validation: dict[str, Any]) -> tuple[str, dict[str, Any]]:- """Deduplicate a plan's repeated tests, targets, and command material."""- encoded = json.dumps(validation, sort_keys=True, separators=(",", ":"), default=str)- profile_id = "validation_" + hashlib.sha256(encoded.encode()).hexdigest()[:16]- tests = list(validation.get("tests") or [])- targets = list(validation.get("targets") or [])- profile = {- key: value- for key, value in validation.items()- if key not in {"tests", "targets", "commands", "truncated"}- }- profile.update(- {- "id": profile_id,- "tests": tests,- "tests_total": int(validation.get("total") or len(tests)),- "tests_emitted": len(tests),- "targets": targets,- "commands": list(validation.get("commands") or []),- "commands_total": len(validation.get("commands") or []),- "commands_emitted": len(validation.get("commands") or []),- }- )- if profile["tests_emitted"] < profile["tests_total"]:- profile["tests_reduced_reason"] = "analysis_source_cap"- return profile_id, profile---def _stamp_nested_collections(value: Any) -> None:- """Give every nested list an emitted count and an honest eligible total."""- if isinstance(value, list):- for item in value:- _stamp_nested_collections(item)- return- if not isinstance(value, dict):- return- for key, child in list(value.items()):- if isinstance(child, list):- total_key = f"{key}_total"- emitted_key = f"{key}_emitted"- total = int(value.get(total_key, len(child)) or 0)- value.setdefault(total_key, total)- value.setdefault(emitted_key, len(child))- if len(child) < total:- value.setdefault(f"{key}_reduced_reason", "limit")- _stamp_nested_collections(child)---_RANKED_DIMENSIONS_DEFAULT = {"defect", "maintainability"}-"""Dimensions the impact-ranked findings list carries when none is asked for."""--def _in_dimensions(row: Any, dimensions: set[str]) -> bool:- """True when *row* belongs to one of *dimensions* (empty set -> everything).-- ``dimension`` is nullable and a NULL means ``defect``: the column was added- without a backfill, so pre-existing rows stay NULL until the next index- recomputes them. Reading it as anything else drops real defect findings.- """- if not dimensions:- return True- return (row.dimension or "defect") in dimensions---def _round_opt(v: Any) -> float | None:- """Round a nullable per-dimension score, preserving ``None`` (not measured)."""- return round(v, 2) if v is not None else None---def _leads_by_file(findings: list[Any]) -> dict[str, dict[str, Any]]:- """Reduce each file's findings to its dominant cause + pre-clamp magnitude.-- ``primary_biomarker`` / ``primary_reason`` give a low file "the one reason"- to lead with; ``total_deduction`` (summed ``health_impact``) distinguishes- two files that both floor at 1.0. Additive — the score itself is untouched.-- The headline prefers the strongest **discrete** finding. A continuous- biomarker fires on every file carrying its input signal, so on a repo with- coverage data ``coverage_gradient`` wins the max-impact tiebreak nearly- everywhere: measured on this repo before the preference, it led 22 of the- top 50 ``worst_files`` and 14 of the top 50 ``high_leverage_files`` with- "N% of lines uncovered", which is true and tells a reader nothing about why- this file rather than any other. The gradient still counts in- ``total_deduction`` and still leads when it is a file's only finding — it- just stops crowding out a nameable cause. That selection rule now lives in- ``analysis.health.models.primary_finding``, so this and the composition- layer cannot drift about which finding a file leads with.- """- by_file: dict[str, list[Any]] = {}- for f in findings:- by_file.setdefault(f.file_path, []).append(f)- leads: dict[str, dict[str, Any]] = {}- for path, fs in by_file.items():- 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---def _serialize_metric(- m: HealthFileMetric,- lead: dict[str, Any] | None = None,- *,- is_test: bool = False,-) -> dict[str, Any]:- return {- "file_path": m.file_path,- "score": round(m.score, 2),- "max_ccn": m.max_ccn,- "max_nesting": m.max_nesting,- "nloc": m.nloc,- # Two different questions, deliberately both present: ``has_test_file``- # is "does something test this file", ``is_test`` is "is this file- # itself test material". Defect risk in a test reads differently from- # defect risk in the code it covers, and nothing in the payload used to- # say which one you were looking at.- "is_test": is_test,- "has_test_file": m.has_test_file,- "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 target score- # (``(8.0 - score) * nloc``, 0 once the file is at target). 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.- # The unit is score-points x NLOC, which is meaningless on its own — the- # docstring and ``gap_analysis.weighted_gap_points`` give it a- # denominator, and every ``high_leverage_files`` row carries the same- # quantity as ``share_of_repo_gap_pct``.- "weighted_deficit": round(max(TARGET_SCORE - m.score, 0.0) * max(m.nloc, 1)),- # Per-dimension scores from the three-signal split. ``defect_score`` is- # deliberately absent: ``engine.py`` sets it and ``score`` from the same- # ``scores["defect"]`` value, so it was pure duplication on every row of- # every response — measured on this repo, 3,314 of 3,314 rows had- # ``score == defect_score`` and none was NULL. Two names for one number- # cost an agent a source read to decide which to rank on, and the one to- # rank on is neither (it is ``weighted_deficit``). ``score`` survives- # because every doc, skill and UI already names it.- # ``performance_score`` is computed but not yet surfaced as its own pillar.- "maintainability_score": _round_opt(getattr(m, "maintainability_score", None)),- "performance_score": _round_opt(getattr(m, "performance_score", None)),- # Dominant-cause lead + pre-clamp magnitude (null when no findings for- # this row). Lets a caller lead with the one reason and rank two floored- # files by depth without re-reading every finding.- "primary_biomarker": lead.get("primary_biomarker") if lead else None,- "primary_reason": lead.get("primary_reason") if lead else None,- "total_deduction": lead.get("total_deduction") if lead else None,- }---def _attach_coverage_decay(payload: list[dict[str, Any]], rows: list[Any], repo_path: str) -> None:- """Add a ``decay`` block to each coverage row, in place.-- The stored percentage is a measurement taken at one commit and never- recomputed, so on a file under active development it can describe code that- no longer exists. ``decay`` says how much of that measurement still holds:- ``confirmed`` covered lines are unchanged since the report, ``invalidated``- ones have moved and are now unknown rather than uncovered.-- Targeted mode only. Dashboard mode declines ``covered_lines_json`` at the- read (see the load above), and re-reading every blob to compute drift for a- list nobody drilled into would undo that saving.-- Silent when the measurement cannot be placed in history, when git cannot- read the range, or when the report predates every commit. A missing block- means "not checked", which is why it is absent rather than zero: a zero- would read as a freshness claim.- """- if not rows:- return- first = rows[0]- ref = measurement_ref(- repo_path,- getattr(first, "ingested_commit_sha", None),- getattr(first, "ingested_at", None),- )- if ref is None:- return- covered_by_file = {- entry["file_path"]: set(entry.get("covered_lines") or [])- for entry in payload- if entry.get("covered_lines")- }- decays = decay_since(repo_path, ref, covered_by_file)- if not decays:- return- for entry in payload:- d = decays.get(entry["file_path"])- if d is None:- continue- entry["decay"] = {- "measured_lines": d.measured,- "confirmed_lines": d.confirmed,- "invalidated_lines": d.invalidated,- "drift_pct": d.drift_pct,- "stale": d.is_stale,- "measured_at_commit": ref[:12],- }---def _serialize_coverage_row(row: Any, *, covered_lines: bool = True) -> dict[str, Any]:- """One coverage row. ``covered_lines=False`` omits the per-line array.-- The narrow form is not the wide form minus a key: a row read with- ``include_covered_lines=False`` carries no ``covered_lines_json`` at all, so- touching it would raise rather than merely waste the parse.- """- out: dict[str, Any] = {- "file_path": row.file_path,- "source_format": row.source_format,- "line_coverage_pct": row.line_coverage_pct,- "branch_coverage_pct": row.branch_coverage_pct,- }- # Inserted here rather than appended, so the wide form stays byte-identical- # to what callers already receive.- if covered_lines:- try:- out["covered_lines"] = (- json.loads(row.covered_lines_json) if row.covered_lines_json else []- )- except Exception:- out["covered_lines"] = []- out["total_coverable_lines"] = row.total_coverable_lines- out["ingested_at"] = row.ingested_at.isoformat() if row.ingested_at else None- out["ingested_commit_sha"] = row.ingested_commit_sha- return out---def _unresolved_targets(- *,- file_targets: list[str],- module_targets: list[str],- matched_modules: set[str],- resolved_paths: set[str],- excluded_paths: set[str],- unscored_paths: set[str],- repo_root: Any,-) -> list[dict[str, str]]:- """Name every requested target that produced no rows, with a reason.-- A dropped target is otherwise indistinguishable from a clean file: an- empty ``findings`` list reads as "this file is healthy", which is the most- damaging default this tool can have. The reason is the actionable part —- ``not_indexed`` means run ``repowise update``, ``no_such_path`` means the- target was a typo, ``excluded`` means the repo config drops it on purpose,- and ``not_measured`` means the row is indexed but carries no stored split- for the reading ``counts`` asked for. That last one is why the projection- is passed in rather than inferred: an indexed file it could not answer for- would otherwise read as ``not_indexed`` and send the caller to run an- update that changes nothing.- """- out: list[dict[str, str]] = []- for t in file_targets:- if t in resolved_paths:- continue- if t in excluded_paths:- reason = "excluded"- elif t in unscored_paths:- reason = "not_measured"- else:- try:- on_disk = (Path(repo_root) / t).exists()- except (OSError, ValueError):- on_disk = False- reason = "not_indexed" if on_disk else "no_such_path"- out.append({"target": t, "reason": reason})- out.extend(- {"target": f"module:{name}", "reason": "no_such_module"}- for name in module_targets- if name not in matched_modules- )- return out---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.-- Every other block here ranks and describes; none of them recommends. That- gap is why a correct finding can sit at position 12 of an undifferentiated- list and change nobody's behaviour. Same role as ``get_risk``'s- ``directive``: lead with the call, keep the evidence underneath.-- Ranked by ``weighted_deficit`` (not ``score``, which floors at 1.0), so- this names the file that actually moves the repo average.- """- if not by_leverage:- return None- # 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(TARGET_SCORE - 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- # ``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.- # 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 available- out = {- "fix_first": top.file_path,- "reason": lead.get("actionable_reason") or f"scores {round(top.score, 2)}",- # Points the repo headline recovers if this one file reaches the target,- # 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- # is the *gross* deficit of all below-target files (not the net gap,- # which above-target files cushion): per-file shares are then bounded by- # 100% and sum to 100% by construction (issue #1437).- "recovers_weighted_deficit_points": recovers,- "recovers_points": recovers,- "recovers_points_compatibility": {- "deprecated": True,- "replacement": "recovers_weighted_deficit_points",- "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 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- # (refactoring_plans 34%, the other four lists 59%) and simply fails the- # MCP token cap, so the one call the directive tells an agent to make was- # the one call it could not complete. ``only`` already exists to fix this- # (it gates the work as well as the payload); the directive just has to- # ask for it. Same block, ~24k chars, no dashboard restated.- "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.- 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 plan addresses {lead_biomarker!r}; this file has no plans. "- "Use the finding itself."- )- out["next_action"] = f"investigate {lead_biomarker}"- elif addresses:- out["next_action"] = "inspect matching plan via plan_via"- return out---def _finding_next_action(finding: Any, repo: str | None) -> dict[str, Any]:- """Return one concrete source call for a finding without a stored plan."""- path = str(getattr(finding, "file_path", ""))- line_start = getattr(finding, "line_start", None)- line_end = getattr(finding, "line_end", None)- if path and line_start and line_end:- arguments: dict[str, Any] = {"symbol_id": f"{path}:{line_start}-{line_end}"}- if repo:- arguments["repo"] = repo- return {"tool": "get_symbol", "arguments": arguments}- arguments = {"targets": [path], "include": ["skeleton"]}- if repo:- arguments["repo"] = repo- return {"tool": "get_context", "arguments": arguments}---def _refactoring_plans_status(- *,- available_plans_total: int,- plans_emitted: int,- scoped: bool,- has_eligible_metrics: bool,- finding: Any | None,- repo: str | None,-) -> dict[str, Any]:- """Explain an explicitly requested plan projection deterministically."""- if plans_emitted:- return {"state": "available", "reason": None}- if available_plans_total:- return {- "state": "available_not_emitted",- "reason": "request_window_empty",- "message": "Plans exist but the requested limit/cursor window emitted none.",- }- if scoped and not has_eligible_metrics:- return {- "state": "unavailable",- "reason": "no_eligible_targets",- "message": "No requested target resolved to an eligible stored health row.",- }- if not has_eligible_metrics:- return {- "state": "unavailable",- "reason": "analysis_unavailable",- "message": "No stored health analysis is available for this population.",- "next_action": {- "command": "repowise update",- "reason": "run health analysis before interpreting scores or plans",- },- }- if finding is None:- return {- "state": "empty",- "reason": "no_applicable_findings",- "message": "The eligible population has no applicable open findings.",- }- return {- "state": "indeterminate",- "reason": "plan_analysis_indeterminate",- "message": "Findings exist, but stored plan evidence is absent.",- "possible_causes": [- "no_supported_structured_transformation",- "refactoring_detector_disabled_or_failed",- ],- "next_action": _finding_next_action(finding, repo),- }---def _prune_orphaned_validation_profiles(- result: dict[str, Any], collector: OmissionCollector-) -> None:- """Drop profiles whose plan the response budget removed.-- A validation profile only means anything next to the plan referencing it,- so leaving one behind after its plan is shed hands the agent an id that- resolves to nothing.- """- plans = result.get("refactoring_plans")- profiles = result.get("validation_profiles")- if not isinstance(plans, list) or not isinstance(profiles, list):- return- referenced = {- plan.get("validation_profile_id")- for plan in plans- if isinstance(plan, dict) and plan.get("validation_profile_id")- }- kept = [- profile- for profile in profiles- if isinstance(profile, dict) and profile.get("id") in referenced- ]- dropped = [profile for profile in profiles if profile not in kept]- if not dropped:- return- collector.add("validation_profiles no longer referenced after response budgeting", dropped)- result["validation_profiles"] = kept- result["validation_profiles_emitted"] = len(kept)- result["validation_profiles_reduced_reason"] = "response_budget"- result["truncated"] = True---def _reconcile_plan_status(result: dict[str, Any]) -> None:- """Keep plan availability honest after the final budget mutates collections."""- status = result.get("refactoring_plans_status")- plans = result.get("refactoring_plans")- if not isinstance(status, dict) or status.get("state") != "available":- return- if plans is not None and (not isinstance(plans, list) or plans):- return- if not result.get("refactoring_plans_total", 0):- return- status.update(- state="available_not_emitted",- reason="response_budget",- message="Plans exist but were removed by the final response budget.",- )---register_post_shed("get_health", _prune_orphaned_validation_profiles)-register_post_enforce("get_health", _reconcile_plan_status)---def _attach_health_analysis_meta(- meta: dict[str, Any], metrics: list[HealthFileMetric]-) -> None:- """Keep stored analysis distinct from index/live Git verification."""- analyzed = [m for m in metrics if getattr(m, "updated_at", None)]- latest = max(analyzed, key=lambda m: m.updated_at) if analyzed else None- _write_health_analysis_meta(- meta,- has_metrics=bool(metrics),- latest_at=latest.updated_at if latest is not None else None,- latest_commit=getattr(latest, "analyzed_commit", None) if latest else None,- distinct_commits=len({c for m in analyzed if (c := getattr(m, "analyzed_commit", None))}),- )---async def _attach_repository_analysis_meta(- session: Any, repository: Any, meta: dict[str, Any]-) -> None:- """The same block, computed over the repository rather than one file.-- "Has this repository's health analysis recorded its commit" is a fact about- the analysis, but every detail mode used to answer it from the rows it- happened to be reporting on. A ``plan_id`` call scoped to a file whose row- carries a commit said ``available`` at the same instant the dashboard said- ``provenance_unknown (analysis_commit_not_recorded)`` from the repo-wide row,- and the reverse when the scoped file was the one missing it. Three bounded- aggregates, so agreeing costs no scan.- """- latest = (- await session.execute(- select(HealthFileMetric.updated_at, HealthFileMetric.analyzed_commit)- .where(- HealthFileMetric.repository_id == repository.id,- HealthFileMetric.updated_at.is_not(None),- )- .order_by(HealthFileMetric.updated_at.desc())- .limit(1)- )- ).first()- total, distinct = (- await session.execute(- select(- func.count(),- func.count(func.distinct(HealthFileMetric.analyzed_commit)),- ).where(HealthFileMetric.repository_id == repository.id)- )- ).one()- _write_health_analysis_meta(- meta,- has_metrics=total > 0,- latest_at=latest[0] if latest else None,- latest_commit=latest[1] if latest else None,- distinct_commits=distinct,- )---def _write_health_analysis_meta(- meta: dict[str, Any],- *,- has_metrics: bool,- latest_at: Any,- latest_commit: str | None,- distinct_commits: int,-) -> None:- """The one place the analysis-freshness block is shaped."""- meta["health_semantics"] = health_semantics_contract()- metrics = has_metrics- analyzed = latest_at is not None- commits_count = distinct_commits- # Metrics without a recorded commit are usable but unattributable: a- # provenance gap, not degradation. ``degraded`` is reserved tool-wide for a- # capability that failed or was unavailable.- status = (- "available" if latest_commit else "provenance_unknown" if metrics else "unavailable"- )- analysis: dict[str, Any] = {- "status": status,- "source": "stored_health_analysis",- "recomputed_this_call": False,- "live_verification": {- "basis": (- "index_commit_and_live_git_head"- if meta.get("indexed_commit") and meta.get("live_head")- else "unavailable"- ),- "source_bytes_verified": False,- },- "refresh": {- "command": "repowise update",- "precondition": "commit health-relevant working-tree changes first",- "required_before_comparison": True,- },- }- if not metrics:- analysis["reason"] = "no_stored_health_metrics"- if analyzed:- analyzed_at = latest_at.isoformat()- analysis["analyzed_at"] = analyzed_at- meta["health_analyzed_at"] = analyzed_at- if latest_commit:- analyzed_commit = latest_commit[:12]- analysis["analyzed_commit"] = analyzed_commit- meta["health_analyzed_commit"] = analyzed_commit- if commits_count > 1:- analysis["analyzed_commits_distinct"] = commits_count- meta["health_analyzed_commits_distinct"] = commits_count- if not latest_commit:- analysis["reason"] = "analysis_commit_not_recorded"- analysis["analyzed_commit"] = None- else:- analysis["recorded_at"] = None- analysis["recorded_commit"] = None- if metrics:- analysis["reason"] = "analysis_timestamp_not_recorded"- meta["health_analysis"] = analysis---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. Two gaps are computed and- kept deliberately distinct:-- - ``weighted_gap_points`` — the **net** points the average needs- (``8.0 * total_nloc - Σ score*nloc``). Files already above the target- cushion it, so this is smaller than the gross every-file-at-target- 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. This can be 0 or negative on a- repo that is mostly at target (the average is already above 8.0).- - ``weighted_gross_gap_points`` — the **gross** deficit,- ``Σ max(8.0 - score, 0) * nloc`` over files below 8.0. This is the- denominator ``share_of_repo_gap_pct`` uses: it is positive whenever any- file is below target (unlike the net gap), so a share is meaningful even- when the average is already at target, and per-file shares sum to exactly- 100% by construction. The net gap is not used there precisely because- above-target files cushion it — one large low file could then read as closing- more than the whole remaining gap (issue #1437).-- 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 = TARGET_SCORE * total_nloc - weighted_sum- below = sorted(- (- max(TARGET_SCORE - m.score, 0.0) * max(m.nloc, 1)- for m in metrics- if m.score < TARGET_SCORE- ),- reverse=True,- )- gross_gap = sum(below)- if not below:- return {- "target_score": TARGET_SCORE,- "weighted_gap_points": 0,- "weighted_gross_gap_points": 0,- "files_below_target": 0,- "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)-- # ``files_to_reach_target`` needs the net gap to mean "the headline crosses- # 8.0". When the net gap is <= 0 (average already at target) there is nothing- # to reach, so those fields are 0 — but the gross gap is still reported- # because per-file shares are meaningful whenever any file is below target.- reachable = max(net_gap, 0)- return {- "target_score": TARGET_SCORE,- # Net weighted points the average must recover to reach 8.0.- "weighted_gap_points": round(max(net_gap, 0)),- # Gross deficit of all below-target files: the share_of_repo_gap_pct- # denominator (see docstring for why it is not the net gap).- "weighted_gross_gap_points": round(gross_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(reachable),- "files_for_half_gap": _files_for(0.5 * reachable),- }---def _perf_kpis(performance_findings: int, coverage: PerfCoverage | None) -> dict[str, Any]:- """The honest performance headline: finding count + density + coverage.-- Leads with *how many* findings and over *how much* of the code the perf pass- ran, so an agent never reads a bare ``performance_average`` of ~10 as "fast"- when the real story is "we could only analyze 3% of this repo".- """- density: float | None = None- if coverage is not None and coverage.covered_nloc > 0:- density = round(10000.0 * performance_findings / coverage.covered_nloc, 2)- return {- "performance_findings": performance_findings,- "performance_findings_density_per_10k_loc": density,- "performance_coverage_pct": (- coverage.pct_loc if (coverage and coverage.analyzed_files) else None- ),- "performance_covered_files": coverage.covered_files if coverage else 0,- "performance_analyzed_files": coverage.analyzed_files if coverage else 0,- "performance_skipped_files": coverage.skipped_files if coverage else 0,- "performance_unsupported_languages": (coverage.unsupported_languages if coverage else []),- }---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 None---def _compute_kpis(- metrics: list[HealthFileMetric],- *,- hotspot_paths: set[str] | None = None,- performance_findings: int = 0,- coverage: PerfCoverage | None = None,-) -> dict[str, Any]:- if not metrics:- return {- "file_count": 0,- "average_health": None,- "band": None,- "analysis_status": "unavailable",- "hotspot_health": None,- "worst_performer_path": None,- "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_nloc- worst = min(metrics, key=lambda r: r.score)- return {- "file_count": len(metrics),- "average_health": round(avg, 2),- # ``None`` when the repo has no hotspot files, which is a real answer:- # the alternative is averaging an empty set to a perfect 10.0 and- # 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()),- # 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),- # Maintainability + performance pillar headlines alongside the- # defect-backed average. Each is ``None`` until its pillar is measured.- "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),- }--- surface_order=90,- artifact_type="health",- presentation="health",- evidence_basis="measured",- recipes=(- ToolRecipe(- "health_directive",- 'get_health(only=["directive"])',- ("get_health",),- ),- ToolRecipe(- "health_file_self_check",- 'get_health(targets=["path"], include=["refactoring"])',- ("get_health",),- ),- ToolRecipe(- "health_module_triage",- 'get_health(targets=["module:path"], only=["modules","metrics"])',- ("get_health",),- ),- ToolRecipe(- "health_trend",- 'get_health(include=["trend"], only=["trend"])',- ("get_health",),- ),- ToolRecipe(- "health_accuracy",- 'get_health(include=["accuracy"], only=["accuracy"])',- ("get_health",),- ),- ToolRecipe(- "health_coverage",- 'get_health(include=["coverage"], only=["coverage"])',- ("get_health",),- ),- ToolRecipe(- "health_performance_refactoring",- 'get_health(include=["performance","refactoring"], '- 'only=["performance_opportunities","refactoring_plans"])',- ("get_health",),- ),- ToolRecipe(- "health_performance_summary",- 'get_health(include=["performance"], only=["performance_summary"])',- ("get_health",),- ),- ToolRecipe(- "health_performance_opportunity",- 'get_health(opportunity_id="perf...")',- ("get_health",),- ),- ToolRecipe(- "health_performance_evidence",- 'get_health(opportunity_id="perf...", '- 'only=["performance_evidence"], cursor=0)',- ("get_health",),- ),- ),-)-async def get_health(- targets: list[str] | None = None,- include: list[str] | None = None,- repo: str | None = None,- limit: int = 20,- only: list[str] | None = None,- refactoring_view: str = _REFACTORING_VIEW_DEFAULT,- refactoring_type: str | None = None,- refactoring_confidence: str | None = None,- refactoring_effort: str | None = None,- cursor: int = 0,- finding_id: str | None = None,- plan_id: str | None = None,- opportunity_id: str | None = None,- performance_view: str | None = None,- performance_context: str | None = None,- performance_boundary: str | None = None,- performance_confidence: str | None = None,- performance_actionability: str | None = None,- performance_sort: str | None = None,- scope: str = DEFAULT_SCOPE,- counts: str = DEFAULT_COUNTS,-) -> dict:- """Code-health scores and findings from stored analysis.-- No ``targets`` returns a dashboard; targets rank files and findings.- Never recomputes health: commit, then run ``repowise update``.- Every block and accepted value: docs/agent/MCP_TOOLS.md.-- Args:- targets: file paths or ``module:<name>``; unmatched ones land in- ``unresolved``.- include: ``biomarkers``|``refactoring``|``trend``|``coverage``|- ``accuracy``|``signals``|``churn_complexity``|``doc_drift``,- or a dimension incl. ``advisory``; ``performance`` and- ``refactoring`` add queues.- only: keys to keep; identity, totals, recovery survive.- ``biomarkers``/``accuracy``/``refactoring`` alias their block key;- ``performance``/``defect``/``maintainability``/``advisory``- do not: they filter rows into ``unknown_only_keys``.- repo: usually omitted.- limit: max rows per ranked list, ``0`` for none.- cursor: zero-based offset into a ranked list.- finding_id/plan_id: stable ``id`` from a finding or plan.- opportunity_id: ``perf...``/``refop...``: the unit, its steps or- plan, evidence paged by ``only=["*_evidence"]``.- refactoring_view: ``diversified`` (default)|``canonical``|- ``file_spread``; _type/_confidence/_effort filter.- performance_view/_context/_boundary/_confidence/_actionability/_sort:- queue filters; a rejected value lists the accepted.- scope / counts: default ``all``/``everything``. ``production`` drops- test files; ``code_shape`` drops the git-derived half of the- score and its findings.-- """- started = perf_counter()- conflict = _selector_conflict(- finding_id=finding_id, plan_id=plan_id, opportunity_id=opportunity_id- )- if conflict is not None:- return _note_inapplicable_controls(conflict, scope, counts)- # ``0`` means none, matching the ``module_limit`` convention on the REST- # coverage route. It used to clamp up to 1, so the documented way to ask for- # "the totals, none of the rows" silently returned a row.- limit = max(limit, 0)- cursor = max(cursor, 0)- if refactoring_view not in _REFACTORING_VIEWS:- refactoring_view = _REFACTORING_VIEW_DEFAULT- include_set = set(include or [])- known_includes = {- "biomarkers",- "refactoring",- "trend",- "coverage",- "accuracy",- "signals",- "churn_complexity",- "doc_drift",- "performance",- "defect",- "maintainability",- "advisory",- }- unknown_include_keys = sorted(include_set - known_includes)- only_list = [_ONLY_ALIASES.get(k, k) for k in (only or [])]- only_set = set(only_list)-- def wants(block: str) -> bool:- """True when ``block`` survives the ``only`` projection.-- ``only`` used to be applied to the finished response, so the cheapest- documented call — ``only=["directive"]`` — still paid for every block it- then discarded. Consulted before the expensive optional work so the- projection gates the work as well as the payload.- """- return not only_set or block in only_set-- # Resolved before the reads, not after them. Applied to the finished- # response, a dimension filter narrowed a list that had already been capped- # by impact — and performance findings carry low impact by construction, so- # ``include=["biomarkers", "performance"]`` filtered a defect-heavy head down- # to nothing while the total still reported the whole repo. The filter now- # decides which rows are eligible for the cap in the first place.- dimension_filter = include_set & set(ALL_DIMENSIONS)- # The ranked findings list is ordered by health impact, and every- # performance finding carries zero impact by construction, so leaving it- # in an unfiltered list appends rows that can never rank and cannot be- # compared against the ones above them. Asking for the dimension still- # returns it, and the performance blocks rank the same evidence by cause.- ranked_dimensions = dimension_filter or _RANKED_DIMENSIONS_DEFAULT- # The serialized-rows read is the expensive optional one; skip it when no- # block that carries findings survives the projection.- wants_findings = wants("findings") or wants("top_findings")- wants_test_findings = wants("test_findings")- wants_performance_opportunities = (- wants("performance_opportunities")- or wants("recommendation_lede")- or wants("performance_summary")- )- wants_refactoring_opportunities = (- wants("refactoring_opportunities")- or wants("recommendation_lede")- or wants("refactoring_summary")- )- # Everything downstream of the test/production split, in one place.- #- # Keep this list exhaustive. The read it gates is not free (the column list- # is narrow but the predicate is not indexed, so it scans this repo's graph- # nodes — ~55 ms warm on a 35k-node index), and ``only=["directive"]`` /- # ``["kpis"]`` / ``["modules"]`` serialize no metric row and no finding.- # But a *missing* entry here is worse than the read: it makes the split- # collapse for that projection, which is the same "a projection changed- # what a surviving key holds" defect this change exists to close. Adding- # ``suggestion_legend`` was not optional — the legend derives from the split- # heads, and leaving it out silently reverted that fix.- needs_test_paths = (- wants_findings- or wants_test_findings- or wants("worst_files")- or wants("high_leverage_files")- or wants("metrics")- or ("refactoring" in include_set and wants("suggestion_legend"))- )-- # Split ``module:foo`` targets out of the path list. A target that- # matches one or more modules is expanded into the set of files- # belonging to those modules.- raw_targets = list(targets or [])- module_targets = [t.split(":", 1)[1] for t in raw_targets if t.startswith("module:")]- # Stored paths are POSIX-separated. Normalize so a Windows caller passing- # ``packages\core\x.py`` matches instead of coming back ``no_such_path``.- file_targets = [t.replace("\\", "/") for t in raw_targets if not t.startswith("module:")]-- ctx = await _resolve_repo_context(repo)- omission_collector = OmissionCollector("get_health", repo_root=ctx.path)- semantic_omissions: dict[str, list[Any]] = {}- page_recoveries: dict[str, tuple[int, int, int]] = {}- paged_collections = {- "metrics",- "findings",- "trends",- "worst_files",- "high_leverage_files",- "top_findings",- "test_findings",- "modules",- "churn_complexity",- "coverage.files",- "doc_drift.findings",- "refactoring_plans",- "refactoring_opportunities",- "refactoring_evidence",- "performance_opportunities",- "performance_evidence",- }-- def bounded(rows: list[Any], label: str, *, cap: int | None = None) -> list[Any]:- """Bound one collection and retain its exact tail in shared omission storage."""- row_cap = limit if cap is None else cap- start = cursor if label in paged_collections else 0- kept = rows[start : start + row_cap]- if len(kept) < len(rows):- tail_start = start + len(kept)- if label in paged_collections:- if tail_start < len(rows):- next_limit = (- min(row_cap or 6, 6)- if label- in {- "refactoring_plans",- "refactoring_opportunities",- "performance_opportunities",- }- else min(len(rows) - tail_start, 50)- )- page_recoveries[label] = (- tail_start,- next_limit,- len(rows) - tail_start,- )- elif rows and start >= len(rows):- page_recoveries[label] = (0, min(len(rows), max(row_cap, 1), 50), len(rows))- else:- semantic_omissions[label] = rows[row_cap:]- return kept- # Performance headline inputs (dashboard mode): filled inside the session.- perf_coverage: PerfCoverage | None = None- perf_findings_count = 0- # ``None`` means "not read", which is what keeps the code/non-code KPI split- # off targeted responses rather than reporting it over one file.- lang_by_path: dict[str, str] | None = None- async with get_session(ctx.session_factory) as session:- repository = await _get_repo(session)- reference_repository = ctx.alias or repository.name-- if finding_id:- match = await _resolve_finding(- session, repository.id, finding_id, reference_repository- )- result = {- "mode": "finding",- "finding_id": finding_id,- "finding": (- _serialize_finding(match, reference_repository) if match else None- ),- "resolved": match is not None,- "_meta": _build_meta(- repository=repository,- targets=[match.file_path] if match else None,- ),- }- await _attach_repository_analysis_meta(session, repository, result["_meta"])- return _note_inapplicable_controls(result, scope, counts)-- if opportunity_id and opportunity_id.startswith(_REFACTORING_OPPORTUNITY_PREFIX):- return _note_inapplicable_controls(- await _refactoring_detail_response(- session,- repository,- reference_repository,- opportunity_id,- evidence_only=only_set == {"refactoring_evidence"},- limit=limit,- cursor=cursor,- ),- scope,- counts,- )-- if opportunity_id:- return _note_inapplicable_controls(- await _performance_detail_response(- session,- repository,- reference_repository,- opportunity_id,- evidence_only=only_set == {"performance_evidence"},- limit=limit,- cursor=cursor,- ),- scope,- counts,- )-- if plan_id:- # An indexed seek and one hydration, not a full load and a linear- # scan: resolving one id used to cost every open plan in the repo.- service = RefactoringHealthService(- session, repository.id, reference_repository- )- resolved = await service.plan_detail(plan_id)- plan = resolved.get("plan") if resolved.get("resolved") else None- if plan is not None:- plan.setdefault("id", plan_id)- plan["repository"] = reference_repository- result = {- "mode": "refactoring_plan",- "plan_id": plan_id,- "plan": plan,- "resolved": bool(resolved.get("resolved")),- "_meta": _build_meta(- repository=repository,- targets=[plan["file_path"]] if plan else None,- ),- }- if resolved.get("opportunity_id"):- result["opportunity_id"] = resolved["opportunity_id"]- result["next_action"] = resolved["next_action"]- elif plan is not None:- result["opportunity_note"] = (- "This plan is addressable but is not a step of any composed "- "opportunity; a demoted clone is supporting evidence, not work."- )- await _attach_repository_analysis_meta(session, repository, result["_meta"])- return _note_inapplicable_controls(result, scope, counts)-- all_metrics_q = select(HealthFileMetric).where(- HealthFileMetric.repository_id == repository.id- )- exclude_spec = _get_exclude_spec(ctx.path)- indexed_rows = list((await session.execute(all_metrics_q)).scalars().all())- all_metrics = filter_rows_by_attr(indexed_rows, "file_path", exclude_spec)- # 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}-- # Composes with the scope: a re-read off the stored structure/history- # split, not a rescore. Findings narrow by origin, not by path, so a row- # it cannot read lands in ``unscored_files`` with its findings intact.- reported_counts = parse_counts(counts)- code_shape = reported_counts == "code_shape"- unscored_files = 0- unscored_paths: set[str] = set()- if code_shape:- before = {m.file_path for m in all_metrics}- all_metrics, unscored_files = project_counts(counts, all_metrics)- unscored_paths = before - {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]-- def in_counts_findings(rows: list) -> list:- """A history finding cannot explain a score its half was taken out- of, so it is not part of the code-shape reading."""- return split_by_origin(rows)[0] if code_shape else rows- matched_modules: set[str] = set()- if module_targets:- module_set = set(module_targets)- for m in all_metrics:- if m.module in module_set:- matched_modules.add(m.module)- file_targets.append(m.file_path)- file_targets = sorted(set(file_targets))-- # A non-empty ``targets`` means the caller asked for a scope, and that- # holds even when nothing resolves. Keying the mode off the *resolved*- # paths let ``targets=["module:typo"]`` fall through to dashboard mode- # and answer a module-scoped question with repo-wide numbers — an- # answer that reads as scoped and is not.- scoped = bool(raw_targets)- effective_targets = file_targets if scoped else []- nothing_resolved = scoped and not effective_targets-- # Test material, from the flag ingestion already decided per file.- # Gated on ``needs_test_paths`` — see the note at its definition — and- # placed after the ``module:`` expansion so targeted mode can scope it.- #- # Targeted mode only ever asks ``path in test_paths`` for paths the- # caller named, so it reads exactly those; dashboard mode partitions a- # ranked finding list whose paths are not known until the read below- # runs, so it keeps the repo-wide answer. Measured on this repo, that- # is 32.9ms -> 0.6ms on a single-file target — a quarter of the whole- # call, paid to answer "is this one file a test".- test_paths: set[str] = set()- if needs_test_paths:- test_paths = await get_test_file_paths(- session, repository.id, effective_targets if scoped else None- )-- open_findings = (- HealthFinding.repository_id == repository.id,- HealthFinding.status == "open",- )- # Two row sets, deliberately split.- #- # ``finding_rows`` are the ones this response will serialize.- # ``lead_rows`` is the wider set the per-file dominant-cause reduction- # and the exact totals are computed from — it only ever needs four- # columns.- #- # Targeted mode asks about a handful of files, so one full read serves- # both. Dashboard mode does not: hydrating every open finding as a full- # ORM object to emit ``limit`` of them measured 262ms on this repo, and- # that cost is linear in finding count, so it grows with the repo the- # dashboard is describing.- #- # ``test_finding_rows`` is the dashboard-only test bucket (see the split- # below). Targeted mode never fills it: the caller named the files, so- # partitioning what they explicitly asked about would be answering a- # different question than the one they asked.- test_finding_rows: list[Any] = []- test_findings_total = 0- if scoped:- finding_rows = in_counts_findings(in_scope_rows(- list(- (- await session.execute(- select(HealthFinding)- .where(*open_findings)- .where(HealthFinding.file_path.in_(effective_targets))- .order_by(HealthFinding.health_impact.desc())- )- )- .scalars()- .all()- ),- "file_path",- ))- lead_rows: list[Any] = finding_rows- emitted = _rank_emitted(- [f for f in finding_rows if _in_dimensions(f, ranked_dimensions)]- )- finding_rows = emitted- legend_rows: list[Any] = finding_rows- else:- # Narrow read over every open finding: the four attributes- # ``_leads_by_file`` reads, plus ``dimension`` for the perf headline- # and ``id`` to fetch the head. SQLAlchemy ``Row`` exposes these as- # attributes, so the reduction and the exclude filter both run- # against it unchanged.- #- # ``details_json`` joins them only when the caller asked for the- # performance dimension, because that is the only case where a perf- # finding can reach the head at all: every one carries- # ``health_impact: 0``, so in a mixed list all ~10k defect findings- # sort above them and the rank could not move a row. Measured on- # this repo the column costs 6.6ms on the read (parsing the 697 perf- # rows out of 10,740 costs a further 1.2ms), which is worth paying- # for the one call it changes and not worth paying for the default.- lite_cols = [- HealthFinding.id,- HealthFinding.file_path,- HealthFinding.health_impact,- HealthFinding.biomarker_type,- HealthFinding.reason,- HealthFinding.dimension,- ]- if "performance" in dimension_filter:- lite_cols.append(HealthFinding.details_json)- if wants_performance_opportunities:- lite_cols.extend(- [- HealthFinding.function_name,- HealthFinding.line_start,- HealthFinding.line_end,- ]- )- lite_rows = list(- (- await session.execute(- select(*lite_cols)- .where(*open_findings)- .order_by(HealthFinding.health_impact.desc())- )- ).all()- )- # ``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 = in_counts_findings(in_scope_rows(lite_rows))- emitted = _rank_emitted(- [r for r in lead_rows if _in_dimensions(r, ranked_dimensions)]- )- # Test material goes in its own bucket rather than competing for- # the repo's headline finding list. Measured on this repo, **2 of- # the top 5** open findings by impact sit on test files, and 4-5 of- # the top 20 — the top-20 figure is tie-dependent (ranks 14+ are all- # at impact 2.16), which is itself the point: a fifth of the- # most-read list was the test suite, decided partly by tie-break.- # Splitting keeps both readable. A thrashing test suite is a real- # signal some teams want; it is just not the same question as- # "where is the defect risk in this codebase".- #- # Split *before* the cap, so each list is the top ``limit`` of its- # own population — capping first and partitioning after would give- # the smaller bucket whatever happened to land in the head.- prod_emitted = [r for r in emitted if r.file_path not in test_paths]- test_emitted = [r for r in emitted if r.file_path in test_paths]- # Both heads, in one list, decided here rather than downstream: the- # legend has to be a pure function of the ranked set so no- # projection can change what a surviving key contains.- legend_rows: list[Any] = prod_emitted[:limit] + test_emitted[:limit]- # Fetch the head by id rather than re-running the ranked query with- # an over-fetch margin. The margin had to cover every exclusion in- # the table, so a repo excluding a large subtree turned the "capped"- # read back into a near-full one; by id it is exactly ``limit`` rows- # whatever the exclude config or dimension filter say.- head_ids = [r.id for r in prod_emitted[:limit]]- test_head_ids = [r.id for r in test_emitted[:limit]] if wants_test_findings else []- finding_rows = []- if not wants_findings:- head_ids = []- # One read for both heads — the split is a partition of the same- # ranked set, so paying two round-trips for it would be the N+1 this- # tool flags in itself.- wanted_ids = head_ids + test_head_ids- if wanted_ids:- by_id = {- f.id: f- for f in (- await session.execute(- select(HealthFinding).where(HealthFinding.id.in_(wanted_ids))- )- )- .scalars()- .all()- }- # Re-imposed from the id lists; ``IN`` does not preserve order.- finding_rows = [by_id[i] for i in head_ids if i in by_id]- test_finding_rows = [by_id[i] for i in test_head_ids if i in by_id]- test_findings_total = len(test_emitted)-- action_finding_rows = emitted- # Counts the rows this response is about: the post-exclusion open set,- # narrowed to the requested dimensions when one was asked for. Reporting- # the unfiltered total beside a filtered list is what made an empty- # ``findings`` read as "nothing here" rather than "nothing shown".- #- # In dashboard mode this counts the *production* half, because that is- # the list it sits beside; ``test_findings_total`` counts the other half- # and the two still sum to the whole open set. Same rule #1337 settled- # for the dimension filter: a total describes the list it is a sibling- # of, never a wider set the caller cannot see.- findings_total = len(emitted if scoped else prod_emitted)-- # Worst-first order, placed here because ranking needs the summed- # deduction per file and ``lead_rows`` is the first point that carries- # every open finding this response is entitled to see. Same comparator- # the crud layer applies to ``get_health_metrics``, so the REST- # dashboard and this tool cannot disagree about which file is worst —- # but fed from rows already in memory, so it costs no extra query.- #- # Deliberately ``lead_rows`` (the unfiltered open set) rather than- # ``emitted``: asking to *see* one dimension must not restate which- # files the repo's worst are.- deductions = deduction_by_path(lead_rows)- # Rebound rather than kept beside a sorted copy, and above every reader.- # ``kpis``, the leverage view and the churn quadrant all reduce with- # ``min()`` or a stable sort, which resolve ties by *input* order — so- # leaving them on the raw list would have one response name one file as- # the worst performer while the ``worst_files`` list printed below it- # led with another. The module rollup takes the map itself.- all_metrics = sort_metrics_worst_first(all_metrics, deductions)- metric_rows = (- [m for m in all_metrics if m.file_path in set(effective_targets)]- if scoped- else all_metrics- )-- # Hotspot health was the one repo KPI this tool never returned, while- # ``get_overview`` invented its own definition for it — so the canonical- # persisted number was surfaced by neither. One scalar column, gated the- # same way as the language map below: ``targets`` mode builds no ``kpis``- # block at all, so scoping the call must not pay for this read.- hotspot_paths: set[str] = set()- if not scoped and wants("kpis"):- hotspot_paths = await get_hotspot_file_paths(session, repository.id)-- # 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.- 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)- perf_findings_count = sum(- 1 for f in lead_rows if (f.dimension or "defect") == "performance"- )-- # ``accuracy`` scores the ranking against the whole repo rather than the- # capped head, but it reads exactly one biomarker: ``compute_defect_accuracy``- # ignores every finding whose type is not ``prior_defect``. Selecting- # those directly keeps the honest denominator without re-reading the- # ~10k rows the narrow pass above exists to avoid.- # Not routed through ``in_counts_findings``: ``prior_defect`` is the- # ground truth this block scores the number against, not a deduction- # the reading includes. Dropping it under ``code_shape`` would leave- # the accuracy block with no labels to be accurate about.- accuracy_rows: list[Any] = []- if "accuracy" in include_set and not scoped:- accuracy_rows = in_scope_rows(- list(- (- await session.execute(- select(HealthFinding)- .where(*open_findings)- .where(HealthFinding.biomarker_type == "prior_defect")- )- )- .scalars()- .all()- ),- "file_path",- )-- # Structured refactoring plans (Extract Class, ...) — loaded only when- # asked for, scoped to the same targets, exclude-filtered like findings.- refactoring_rows: list[Any] = []- refactoring_recommendations: list[Recommendation] = []- # Only when a caller names the plan list. ``include=["refactoring"]``- # leads with composed opportunities now, and emitting both would ship- # two representations of the same work in one response - 52k chars on- # this repo, past the expanded budget, most of it duplicated. The- # documented ``only=["refactoring_plans"]`` call is unchanged.- plans_requested = "refactoring" in include_set and (- "refactoring_plans" in only_set- # The cross-pillar lede quotes one plan beside one performance- # opportunity, and only when both pillars were asked for.- or ({"performance", "refactoring"} <= include_set and wants("recommendation_lede"))- )- if plans_requested and not nothing_resolved:- refactoring_rows = in_scope_rows(- await get_refactoring_suggestions(- session,- repository.id,- file_paths=list(effective_targets) if scoped else None,- ),- "file_path",- )- refactoring_recommendations = await hydrate_recommendations(- session,- repository.id,- refactoring_rows,- metric_rows=all_metrics,- view=plan_view(refactoring_view),- )-- # The materialized causal read model. Filtering, ordering, paging, plan- # linkage, and facets are the shared service's; this tool caps the- # collection, pages it, and serializes what comes back.- performance_service = PerformanceHealthService(- session, repository.id, reference_repository- )- refactoring_service = RefactoringHealthService(- session, repository.id, reference_repository- )- refactoring = await _refactoring_blocks(- refactoring_service,- wants=wants,- included="refactoring" in include_set and wants_refactoring_opportunities,- file_paths=tuple(effective_targets) if scoped else None,- scoped=scoped,- limit=limit,- cursor=cursor,- view=refactoring_view,- lead_type=refactoring_type,- confidence=refactoring_confidence,- effort=refactoring_effort,- )- performance = await _performance_blocks(- performance_service,- wants=wants,- included="performance" in include_set and wants_performance_opportunities,- file_paths=tuple(effective_targets) if scoped else None,- scoped=scoped,- limit=limit,- cursor=cursor,- view=performance_view,- context=performance_context,- boundary=performance_boundary,- confidence=performance_confidence,- actionability=performance_actionability,- sort=performance_sort,- )-- coverage_rows: list[Any] = []- coverage_summary: dict[str, Any] = {}- if "coverage" in include_set and not nothing_resolved:- coverage_rows = in_scope_rows(- # ``effective_targets``, not ``targets`` — a raw ``module:foo``- # target is not a file path and matched nothing here.- #- # Only targeted mode serializes ``covered_lines``. The dashboard- # used to read every ``covered_lines_json`` blob, ``json.loads``- # each one, and then strip the field back out with a dict- # comprehension — 466,874 B of parse per call for a key it never- # emitted. Decline the column at the read instead.- await load_coverage_for_repo(- session,- repository.id,- file_paths=list(effective_targets) if scoped else None,- include_covered_lines=scoped,- ),- "file_path",- )- # 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- # can read why a file is risky (prior defects, churn, owners, degree)- # before touching it. Targeted mode only; the target set is small.- signals_by_path: dict[str, dict[str, Any]] = {}- if "signals" in include_set and effective_targets:- # Batched, not per-file. This loop used to issue three round-trips- # per target (git metadata, graph node, degree counts) — the exact- # cross-function N+1 the tool's own ``io_in_loop`` biomarker flags- # here. ``module:`` targets expand to every file in the module, so- # the target set is not always small.- git_meta_by_path = await get_git_metadata_bulk(- session, repository.id, list(effective_targets)- )- degrees_by_path = await get_node_degree_counts_bulk(- session,- repository.id,- list(effective_targets),- edge_types=sorted(FILE_DEPENDENCY_EDGE_TYPES),- )- for path in effective_targets:- signals_by_path[path] = asdict(- file_signals(git_meta_by_path.get(path), degrees_by_path.get(path))- )-- # Documentation this repository's own tree no longer satisfies. A- # finding is filed against the DOCUMENT, so ``targets`` narrows by the- # document path: naming ``docs/a.md`` asks about drift in that file.- # Targets are matched exactly, as everywhere else in this tool, so a- # bare directory resolves to nothing and lands in ``unresolved``.- drift_rows: list[Any] = []- drift_unavailable: str | None = None- if "doc_drift" in include_set:- try:- # The savepoint is not decoration. This read raises on an index- # written before the drift table existed, and on Postgres a- # failed statement poisons the transaction, so without it one- # missing table would take every later read in this call down- # with it. ``replace_doc_drift_guarded`` guards the- # write side against the same hazard.- async with session.begin_nested():- rows = await get_doc_drift_findings(session, repository.id)- # Only the exclude config, NOT ``in_scope_rows``. That helper- # also applies the ``production`` scope, whose path set is the- # files carrying a health metric --- and no markdown file- # carries one. Routing drift through it made- # ``scope="production"`` report every document as clean, which- # is the one answer this detector must never give by accident.- drift_rows = filter_rows_by_attr(rows, "file_path", exclude_spec)- except (SQLAlchemyError, OSError, LookupError):- # Say the block could not be read rather than serve an empty- # list, which would read as a clean bill of health that was- # never taken.- drift_unavailable = UNAVAILABLE_NO_TABLE- if scoped:- drift_rows = [r for r in drift_rows if r.file_path in effective_targets]-- # Churn x complexity quadrant for the whole repo (dashboard mode). One- # git-metadata query joined against the already-loaded metrics.- churn_points: list[dict[str, Any]] = []- if "churn_complexity" in include_set and not scoped:- git_meta_by_path = await get_all_git_metadata(session, repository.id)- churn_points = [asdict(p) for p in churn_complexity_points(all_metrics, git_meta_by_path)]-- # Load the snapshot window for the repo-level trend block and/or the- # per-file trajectory we attach in targeted mode ("should I touch this- # file" context for agents).- snapshots: list[Any] = []- if "trend" in include_set or (scoped and wants("trends")):- # 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- # 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 mid-band file outranks a tiny at-risk- # 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 < TARGET_SCORE),- key=lambda m: max(TARGET_SCORE - 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]}- # The directive's three candidates, unconditionally — it reads- # ``by_leverage[:3]`` and is not a ranked list, so its leads must not- # depend on ``limit``. Before ``limit=0`` existed this was covered by- # the clamp to 1 only by accident; at 0 the lead set came back empty- # and the directive degraded to a fallback ``reason`` ("scores 1.0")- # *and* asserted ``plan_addresses_reason: false`` on every file —- # a wrong claim rather than a missing one.- printed |= {m.file_path for m in by_leverage[:_DIRECTIVE_CANDIDATES]}- 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[:_DIRECTIVE_CANDIDATES]]- 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 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. 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,- )-- if scoped:- metric_payload: list[dict[str, Any]] = []- for m in metric_rows:- row = _serialize_metric(m, leads.get(m.file_path), is_test=m.file_path in test_paths)- if m.file_path in signals_by_path:- row["signals"] = signals_by_path[m.file_path]- metric_payload.append(row)- module_rollup = _module_rollups(- [m for m in all_metrics if m.module in set(module_targets)], deductions- )- result: dict[str, Any] = {- "mode": "targets",- "targets": raw_targets,- # Deliberately NOT capped by ``limit``: the caller named these files- # and getting back fewer than they asked about would answer a- # different question. The response-size guard is what bounds it, and- # ``metrics_total`` is the ``*_total`` sibling that makes a trim- # visible — a ``module:`` target expands to every file in the module,- # so this is the one growable list whose length the caller cannot- # infer from what they passed.- **({"modules": module_rollup} if module_targets else {}),- "metrics": bounded(metric_payload, "metrics"),- "metrics_total": len(metric_payload),- # Capped like every other ranked list, with the total alongside so- # the truncation is visible rather than inferred from the length.- "findings": bounded(- [_serialize_finding(f, reference_repository) for f in finding_rows],- "findings",- ),- "findings_total": findings_total,- # Which reading these scores are on, last so the identity keys keep- # the head of the payload. Without it a projected score is- # indistinguishable from the calibrated one.- "scope": reported_scope,- "counts": reported_counts,- }- unresolved = _unresolved_targets(- file_targets=file_targets,- module_targets=module_targets,- matched_modules=matched_modules,- resolved_paths={m.file_path for m in metric_rows},- excluded_paths=excluded_paths,- unscored_paths=unscored_paths,- repo_root=ctx.path,- )- if unresolved:- result["unresolved"] = unresolved- if any(u["reason"] == "no_such_module" for u in unresolved):- # ``module:`` has no discovery call of its own, so a bad name- # would otherwise cost a full dashboard round-trip to correct.- result["known_modules"] = sorted({m.module for m in all_metrics if m.module})- # Per-file score trajectory for each target — silent (omitted) when a- # file has < 2 snapshots of history rather than a misleading flat line.- trends = []- for m in metric_rows:- t = file_trend(snapshots, m.file_path)- if not t.points:- continue- series = [round(p.score, 2) for p in t.points]- entry: dict[str, Any] = {- "file_path": t.file_path,- "series": series,- "current": t.current,- "delta": t.delta,- "declining": t.declining,- }- # The score floors at 1.0, so a file deep enough to sit on it keeps- # a flat series however much of the work gets done. Where a- # snapshot recorded the real depth, carry the series that can still- # move — and only there, so the files the floor never touches pay- # nothing for it.- unclamped = [round(p.unclamped_score, 2) for p in t.points]- if unclamped != series:- entry["unclamped_series"] = unclamped- entry["unclamped_delta"] = t.unclamped_delta- trends.append(entry)- if trends:- result["trends"] = bounded(trends, "trends")- if module_targets and not only and not include_set:- result["secondary_rankings"] = {- "findings": {- "total": findings_total,- "call": (- f"get_health(targets={raw_targets!r}, only=['findings'], "- f"repo={repo!r}, limit=50, refactoring_view='{refactoring_view}')"- ),- },- "trends": {- "total": len(trends),- "call": (- f"get_health(targets={raw_targets!r}, only=['trends'], "- f"repo={repo!r}, limit=50, refactoring_view='{refactoring_view}')"- ),- },- }- for block in ("findings", "trends"):- result.pop(block, None)- result.pop(f"{block}_total", None)- else:- # Dashboard mode — top-N worst files + headline findings + the- # per-module rollup so the overview page doesn't need a second- # round-trip. ``by_leverage`` is built above, before the leads.- # Same serializer as worst_files, so every row carries- # weighted_deficit for the caller to sort on further.- all_modules = _module_rollups(all_metrics, deductions)- gap = _gap_analysis(all_metrics)- result = {- # Lead with the call, not the data. Every block below ranks and- # describes; this one recommends.- "directive": _directive(- by_leverage,- leads,- gap.get("weighted_gross_gap_points") or 0,- plan_biomarkers_by_path,- plan_count_by_path,- ),- # A second, additive lead for the performance pillar. The block- # above is unchanged: performance findings carry no defect impact,- # so they never competed for it and the dashboard said nothing an- # agent could act on about them.- # Two more additive leads, on the same terms: the block above ranks- # files by health deficit and cannot say which composed work to do,- # and it explicitly reports that no plan addresses the cause it- # names on most files. These say what there is to do about it.- **(- {"refactoring_directive": refactoring.directive}- if refactoring.directive is not None- else {}- ),- **(- {"performance_directive": performance.directive}- if performance.directive is not None- else {}- ),- "mode": "dashboard",- "scope": reported_scope,- "counts": reported_counts,- "unscored_files": unscored_files,- "kpis": kpis,- "distribution": health_distribution(all_metrics),- # Where the gap to the target concentrates — the "few files, not the- # long tail" reframe that turns a repo-wide number into a short list.- "gap_analysis": gap,- "worst_files": bounded([- _serialize_metric(m, leads.get(m.file_path), is_test=m.file_path in test_paths)- for m in metric_rows- ], "worst_files"),- # Both ranked file lists deliberately keep test files in place, and- # both now say which rows are tests. Measured on this repo, 0 of the- # top 25 by the worst-first comparator are test material, so there- # is no crowding here to fix — and dropping them would quietly- # change which files the repo's "worst" are. The crowding is in the- # *finding* lists, which is where the split below happens.- "worst_files_total": len(metric_rows),- # The one list whose entire purpose is leverage ranking, so it is the- # one place ``weighted_deficit`` gets a denominator. The bare number- # is score-points x NLOC and answers "which is bigger" but never "is- # this worth doing"; the same quantity as a share of the repo's total- # gap does, and it is the unit ``directive`` already speaks. The- # denominator is the gross deficit of all below-target files, so a- # share is bounded by 100% and the rows sum to 100% by construction- # — the net gap would let above-target files cushion the total and push a- # single large file over 100% (issue #1437).- "high_leverage_files": bounded([- {- **_serialize_metric(- m, leads.get(m.file_path), is_test=m.file_path in test_paths- ),- "share_of_repo_gap_pct": (- round(- 100.0- * max(TARGET_SCORE - m.score, 0.0)- * max(m.nloc, 1)- / gap["weighted_gross_gap_points"],- 1,- )- if gap.get("weighted_gross_gap_points")- else None- ),- }- for m in by_leverage- ], "high_leverage_files"),- "high_leverage_files_total": len(by_leverage),- "top_findings": bounded(- [_serialize_finding(f, reference_repository) for f in finding_rows],- "top_findings",- ),- "top_findings_total": findings_total,- # The test half of the same ranked set, in its own bucket so a- # thrashing test suite stays visible without competing with- # production defect risk for the most-read list.- "test_findings": bounded(- [_serialize_finding(f, reference_repository) for f in test_finding_rows],- "test_findings",- ),- "test_findings_total": test_findings_total,- # Worst-first, so the cap keeps the modules worth looking at. On a- # monorepo the tail is dozens of single-file buckets.- "modules": bounded(all_modules, "modules"),- "modules_total": len(all_modules),- }- if not only:- result["secondary_rankings"] = {- "worst_files": {- "total": len(metric_rows),- "call": f"get_health(repo={repo!r}, only=['worst_files'], limit=50)",- },- "top_findings": {- "total": findings_total,- "call": f"get_health(repo={repo!r}, only=['top_findings'], limit=50)",- },- "test_findings": {- "total": test_findings_total,- "call": f"get_health(repo={repo!r}, only=['test_findings'], limit=50)",- },- "modules": {- "total": len(all_modules),- "call": f"get_health(repo={repo!r}, only=['modules'], limit=50)",- },- }- for block in ("worst_files", "top_findings", "test_findings", "modules"):- result.pop(block, None)- result.pop(f"{block}_total", None)- if "churn_complexity" in include_set:- result["churn_complexity"] = bounded(churn_points, "churn_complexity")- if "accuracy" in include_set:- # Self-validation: does the score rank the buggy files first?- # Scored over the full open set (``accuracy_rows``), not the capped- # head — ranking quality measured on the top 20 would be circular.- # ``None`` when there isn't enough signal for an honest number.- result["defect_accuracy"] = compute_defect_accuracy(- all_metrics,- [_serialize_finding(f, reference_repository) for f in accuracy_rows],- # The same map ``all_metrics`` was ranked with, so the stat- # measures exactly the ``worst_files`` this response printed.- deductions=deductions,- )-- if "biomarkers" in include_set and "findings" not in result:- # Capped like every other ranked list. Uncapped, this was the one block- # in the tool that could return the repo's entire open finding set: on a- # 3.2k-file repo ``include=["biomarkers"]`` with no targets served 10.3k- # rows / 4.7MB, which overflows an agent's context and returns nothing- # usable. Findings arrive impact-ordered, so the cap keeps the ones- # worth reading.- result["findings"] = bounded(- [_serialize_finding(f, reference_repository) for f in finding_rows],- "findings",- )- result["findings_total"] = findings_total- # Same production/test split as ``top_findings``: this block only ever- # fires in dashboard mode (targeted mode set ``findings`` above), so it- # is describing the repo, not a file the caller named.- result["test_findings"] = bounded(- [_serialize_finding(f, reference_repository) for f in test_finding_rows],- "test_findings",- )- result["test_findings_total"] = test_findings_total-- if plans_requested:- # Canonical is the shared REST/MCP/CLI order. File diversity remains- # available only through the explicitly named ``file_spread`` view.- validation_profiles: dict[str, dict[str, Any]] = {}- plan_payload = []- selected_recommendations = bounded(- refactoring_recommendations,- "refactoring_plans",- cap=min(limit, 6),- )- for recommendation in selected_recommendations:- payload = _serialize_refactoring(recommendation, reference_repository)- validation = payload.pop("validation", None)- if validation:- profile_id, profile = _validation_profile(validation)- validation_profiles.setdefault(profile_id, profile)- payload["validation_profile_id"] = profile_id- plan_payload.append(payload)- result["refactoring_plans"] = plan_payload- if validation_profiles:- result["validation_profiles"] = list(validation_profiles.values())- _stamp_collection(- result,- "validation_profiles",- total=len(validation_profiles),- reason="profile_cap",- )- result["refactoring_plans_total"] = len(refactoring_rows)- if wants("refactoring_plans"):- finding_for_action = next(iter(action_finding_rows), None)- result["refactoring_plans_status"] = _refactoring_plans_status(- available_plans_total=len(refactoring_recommendations),- plans_emitted=len(plan_payload),- scoped=scoped,- has_eligible_metrics=bool(metric_rows if scoped else all_metrics),- finding=finding_for_action,- repo=repo,- )- # The deterministic prose suggestion is the fallback for biomarkers- # that have no structured detector yet. It is emitted once per- # biomarker type as ``suggestion_legend`` (built below, after the- # dimension filter) rather than copied onto every finding: the text is- # keyed purely by type, so the per-row form repeated one ~40-word- # string up to 10x in a single response.- #- # (The old no-findings-anywhere fallback here was unreachable: targeted- # mode always sets ``findings`` and dashboard mode always sets- # ``top_findings``.)-- 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,- "metric": a.metric,- "current": a.current,- "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": None if narrowed else summary.current_hotspot_health,- "current_average_health": summary.current_average_health,- "previous_hotspot_health": None if narrowed else summary.previous_hotspot_health,- "previous_average_health": summary.previous_average_health,- "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),- "recent": bounded(recent, "trend.recent"),- "recent_total": len(recent),- "recent_emitted": min(len(recent), limit),- }- if len(alerts) > limit:- result["trend"]["alerts_reduced_reason"] = "limit"- if len(recent) > limit:- result["trend"]["recent_reduced_reason"] = "limit"-- if refactoring.page is not None and wants("refactoring_opportunities"):- result["refactoring_opportunities"] = refactoring.page.items- result["refactoring_opportunities_total"] = refactoring.page.total- result["refactoring_opportunities_emitted"] = len(refactoring.page.items)- if len(refactoring.page.items) < refactoring.page.total:- result["refactoring_opportunities_reduced_reason"] = (- "collection_cap" if limit > _REFACTORING_COLLECTION_CAP else "limit"- )- if refactoring.page.next_offset is not None:- page_recoveries["refactoring_opportunities"] = (- refactoring.page.next_offset,- _REFACTORING_COLLECTION_CAP,- refactoring.page.total - refactoring.page.next_offset,- )- if refactoring.ignored:- result["ignored_arguments"] = {- **result.get("ignored_arguments", {}),- **refactoring.ignored,- }-- if refactoring.summary is not None:- result["refactoring_summary"] = {- **refactoring.summary,- "facets": refactoring.page.facets if refactoring.page else {},- "view": refactoring_view,- "next_call": (- "get_health(include=['refactoring'], "- "only=['refactoring_opportunities'], limit=6)"- ),- }-- if performance.page is not None and wants("performance_opportunities"):- result["performance_opportunities"] = performance.page.items- result["performance_opportunities_total"] = performance.page.total- result["performance_opportunities_emitted"] = len(performance.page.items)- if performance.page.next_offset is not None:- page_recoveries["performance_opportunities"] = (- performance.page.next_offset,- _PERFORMANCE_COLLECTION_CAP,- performance.page.total - performance.page.next_offset,- )- if performance.ignored:- result["ignored_arguments"] = {- **result.get("ignored_arguments", {}),- **performance.ignored,- }-- if performance.summary is not None:- result["performance_summary"] = {- **performance.summary,- "facets": performance.page.facets if performance.page else {},- "next_call": (- "get_health(include=['performance'], "- "only=['performance_opportunities'], limit=6)"- ),- }-- if {"performance", "refactoring"} <= include_set and wants("recommendation_lede"):- performance_lead = next(- (- item- for item in (performance.page.items if performance.page else [])- if item.get("biomarker_type") not in NON_LEADING_MARKERS- ),- None,- )- recommendation_lead = (- refactoring_recommendations[0] if refactoring_recommendations else None- )- lead_payload = (- _serialize_refactoring(recommendation_lead, reference_repository)- if recommendation_lead- else None- )- result["recommendation_lede"] = {- "performance_opportunities_total": (- performance.page.total if performance.page else 0- ),- "refactoring_plans_total": len(refactoring_recommendations),- "performance_lead": (- {- key: performance_lead[key]- for key in (- "opportunity_id",- "intervention_symbol",- "boundary_kind",- "execution_context",- "affected_call_sites_total",- "rank_score",- )- }- if performance_lead- else None- ),- "recommendation_lead": (- {- key: lead_payload[key]- for key in (- "id",- "refactoring_type",- "file_path",- "target_symbol",- "benefit",- "leverage",- "cost",- "risk",- "rank_score",- )- }- if lead_payload- else None- ),- # The exact plan for the exact lead, from the one place that decides- # plan linkage. This used to match on a key the plan writer never- # wrote, so it was unconditionally null.- "performance_plan_id": (- performance_lead["plan_reference"] if performance_lead else None- ),- "performance_plan_reason": (- performance_lead["plan_reason"] if performance_lead else None- ),- "next_call": (- f"get_health(targets={raw_targets!r}, repo={repo!r}, "- "include=['performance','refactoring'], limit=3, "- "only=['performance_opportunities','refactoring_plans'], "- f"refactoring_view='{refactoring_view}')"- ),- }-- if "coverage" in include_set:- # Drop the bulky covered-lines arrays from dashboard mode; full- # detail is available in targeted mode.- if scoped:- selected_coverage = bounded(coverage_rows, "coverage.files")- coverage_payload = [_serialize_coverage_row(r) for r in selected_coverage]- _attach_coverage_decay(coverage_payload, selected_coverage, str(ctx.path))- else:- # Built narrow, not built wide and subtracted from. These rows came- # back without the column at all (see the read above).- full_coverage_payload = [- _serialize_coverage_row(r, covered_lines=False) for r in coverage_rows- ]- coverage_payload = bounded(full_coverage_payload, "coverage.files")- # ``ingested_at`` is a datetime on the summary too — coerce.- if coverage_summary.get("ingested_at") is not None:- coverage_summary = {- **coverage_summary,- "ingested_at": coverage_summary["ingested_at"].isoformat(),- }- result["coverage"] = {- "summary": coverage_summary,- "files": coverage_payload,- "files_total": len(coverage_rows),- "files_emitted": len(coverage_payload),- }- if len(coverage_payload) < len(coverage_rows):- result["coverage"]["files_reduced_reason"] = "limit"-- if "doc_drift" in include_set:- if drift_unavailable is not None:- result["doc_drift"] = {"unavailable": drift_unavailable}- else:- drift_payload = bounded(- # ``evidence=False``: its first line restates ``file_path``,- # ``line_number`` and ``raw``, and the rest is the resolver's- # own trace, which is a poor trade against this budget. The- # CLI, which has no budget, keeps it.- [serialize_doc_drift_row(r, evidence=False) for r in drift_rows],- "doc_drift.findings",- )- result["doc_drift"] = {- "findings": drift_payload,- "findings_total": len(drift_rows),- "findings_emitted": len(drift_payload),- "documents": len({r.file_path for r in drift_rows}),- "confidence": summarize_confidence_rows(drift_rows),- # The same sentence the CLI prints, under the house ``*_basis``- # name for "what this count does and does not cover". A surface- # that shows findings without it claims coverage and precision- # this detector does not have: most references are uncheckable.- "findings_basis": DETECTION_BASIS,- }- if len(drift_payload) < len(drift_rows):- result["doc_drift"]["findings_reduced_reason"] = "limit"-- # (The dimension filter — ``include=["performance"]`` and friends, so an- # agent can ask "show me only the performance risk in this change" — is- # applied where the rows are selected, not here. Filtering the finished- # response meant filtering a list already capped by impact.)-- # One entry per biomarker type actually present in the findings this- # response carries. Built last so the dimension filter above has already- # narrowed the rows the caller will join against.- if "refactoring" in include_set and wants("suggestion_legend"):- # Built from the ranked rows themselves, not from the serialized blocks- # in ``result``. It used to read ``result["findings"]`` /- # ``["top_findings"]``, which the ``only`` projection's ``wants()``- # gating can skip building — so- # ``only=["refactoring_plans","suggestion_legend"]`` returned an empty- # legend and adding ``top_findings`` back to ``only`` refilled it. A- # projection is supposed to subtract keys, never change what a surviving- # key contains.- #- # Scope note, and it is a real limitation rather than an oversight: the- # legend explains the *findings*, while it ships beside- # ``refactoring_plans``. Those are different sets — no plan kind is- # sourced from ``coverage_gradient``, the lead biomarker on this repo's- # ten worst files — so a legend entry can describe a biomarker the plans- # do not address. ``directive.plan_addresses_reason`` is what reports- # that mismatch; the legend is not the place to paper over it.- present_types = {getattr(r, "biomarker_type", None) for r in legend_rows}- result["suggestion_legend"] = {- bt: suggestion_for(bt) for bt in sorted(t for t in present_types if t)- }-- collection_totals = {- "targets": len(raw_targets),- "metrics": len(metric_payload) if scoped else None,- "findings": findings_total,- "trends": len(trends) if scoped else None,- "modules": len(module_rollup) if scoped else len(all_modules),- "worst_files": len(metric_rows),- "high_leverage_files": len(by_leverage),- "top_findings": findings_total,- "test_findings": test_findings_total,- "churn_complexity": len(churn_points),- "refactoring_plans": len(refactoring_recommendations),- "performance_opportunities": (- performance.page.total if performance.page is not None else 0- ),- }- for key, total in collection_totals.items():- if total is None:- continue- cap_reason = (- "collection_cap"- if key in {"refactoring_plans", "performance_opportunities"}- and limit > 6- and len(result.get(key, [])) == 6- else "limit"- )- _stamp_collection(result, key, total=total, reason=cap_reason)- if unknown_include_keys:- result["unknown_include_keys"] = unknown_include_keys- _stamp_nested_collections(result)-- # A misspelled control falls back to the default, answering a different- # question under the name the caller asked for. The routes and the CLI- # reject outright; MCP cannot, so it names the value it dropped.- rejected = {- name: raw- for name, raw, resolved in (- ("scope", scope, reported_scope),- ("counts", counts, reported_counts),- )- if raw is not None and raw != resolved- }- if rejected:- result["ignored_arguments"] = {**result.get("ignored_arguments", {}), **rejected}-- # Snapshots and the two ranked queues have no stored split to re-read, so- # they stay calibrated. Named, or a projected headline reads as if- # everything beside it were projected too.- if reported_counts == "code_shape":- unprojected = [- key- for key in ("trend", "trends", "refactoring_opportunities", "performance_opportunities")- if key in result- ]- if unprojected:- result["counts_not_applied_to"] = unprojected-- # Projection. ``include`` could only ever add blocks, so asking for one- # extra block re-shipped the whole dashboard with it; ``only`` is the- # subtract half. Applied last so it can drop anything above, and ``mode`` /- # ``_meta`` always survive — a response the caller cannot orient in is not- # a saving.- if only:- # Every capped list's ``*_total`` sibling survives with it. The tool- # documents "each carries a ``*_total`` sibling so truncation is never- # silent", and the projection was quietly breaking exactly that promise:- # ``only=["modules"]`` at ``limit=50`` returned 50 of 116 modules with- # no ``modules_total`` to say so. Retaining it is not the caller's job —- # a caller who knew to ask for the total would not need the guarantee.- # ``unresolved`` / ``known_modules`` survive any projection, for the same- # reason ``mode`` does. They are the block that stops an empty result- # reading as "this file is healthy" (A1), and projecting them away put a- # typo'd target straight back to silent: ``targets=["does/not/exist.py"],- # only=["metrics"]`` returned ``metrics: []`` and nothing else. A caller- # who has to ask for the error report in order to see it does not have an- # error report.- keep = (- set(only_list)- | {- "mode",- "targets",- "targets_total",- "targets_emitted",- "unresolved",- "unresolved_total",- "unresolved_emitted",- "known_modules",- "known_modules_total",- "known_modules_emitted",- "unknown_include_keys",- "unknown_include_keys_total",- "unknown_include_keys_emitted",- # A rejected filter value is a caller-error report, so it- # survives a projection for the same reason ``unresolved`` does.- "ignored_arguments",- "recovery",- }- | {- suffix- for k in only_list- for suffix in (- f"{k}_total",- f"{k}_emitted",- f"{k}_reduced_reason",- )- }- )- # Which reading the kept numbers are on, but only once it is not the- # default: unconditionally would add three empty keys to every other- # projection.- if reported_scope != DEFAULT_SCOPE:- keep |= {"scope"}- if reported_counts != DEFAULT_COUNTS:- keep |= {"counts", "unscored_files", "counts_not_applied_to"}- if "refactoring_plans" in only_set:- keep |= {- "refactoring_plans_status",- "validation_profiles",- "validation_profiles_total",- "validation_profiles_emitted",- "validation_profiles_reduced_reason",- }- # A key that does not exist in this response is named rather than- # quietly yielding an empty one — same rule as ``unresolved`` above.- # A misspelled projection is otherwise indistinguishable from a block- # the repo genuinely has no data for. Reported against what the caller- # actually passed, so an alias resolving to a present key is not "unknown".- unknown = sorted(- raw for raw, resolved in zip(only, only_list, strict=True) if resolved not in result- )- result = {k: v for k, v in result.items() if k in keep}- if unknown:- result["unknown_only_keys"] = unknown- _stamp_collection(result, "unknown_only_keys", total=len(unknown))-- visible_recoveries = {- label: values- for label, values in page_recoveries.items()- if label.split(".", 1)[0] in result- }- if visible_recoveries:- recovery: dict[str, dict[str, Any]] = {}- for label, (next_cursor, next_limit, remaining) in visible_recoveries.items():- root = label.split(".", 1)[0]- recovery[label] = {- "remaining": remaining,- "call": (- f"get_health(targets={raw_targets!r}, include={list(include or [])!r}, "- f"repo={repo!r}, limit={next_limit}, only={[root]!r}, "- f"refactoring_view='{refactoring_view}', cursor={next_cursor})"- ),- }- result["recovery"] = recovery-- # Targeted mode scopes the stale signal to the asked-about files; the- # dashboard (no targets) keeps the repo-level warning.- result["_meta"] = _build_meta(repository=repository, targets=targets if targets else None)- analyzed_source = metric_rows if scoped else all_metrics- if scoped:- # Scoped calls used to answer repository freshness from the caller's own- # files, so one repo read two different statuses in the same second- # depending on which mode answered.- await _attach_repository_analysis_meta(session, repository, result["_meta"])- else:- _attach_health_analysis_meta(result["_meta"], analyzed_source)- # Server-side wall clock, as ``get_context`` already reports. Without it a- # regression in here is invisible until someone profiles it by hand.- for label, dropped in semantic_omissions.items():- root = label.split(".", 1)[0]- if root in result:- omission_collector.add(- f"{label} beyond emitted cap ({len(dropped)} dropped)",- [- _serialize_refactoring(row, reference_repository)- if isinstance(row, Recommendation)- else row.as_dict()- if hasattr(row, "as_dict")- else row- for row in dropped- ],- )- omission_collector.attach(result)- result["_meta"]["timing_ms"] = round((perf_counter() - started) * 1000, 2)- return resultdiff --git a/packages/server/src/repowise/server/mcp_server/tool_health/__init__.py b/packages/server/src/repowise/server/mcp_server/tool_health/__init__.pynew file mode 100644index 000000000..c681bd449--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/tool_health/__init__.py@@ -0,0 +1,37 @@+"""MCP tool: get_health — code-health markers and per-file scores.++``tool.py`` holds the registered tool; the sibling modules hold the pieces it+composes. The private names below are re-exported because other tools and the+tests import them from ``tool_health`` directly.+"""++from __future__ import annotations++from repowise.core.analysis.health.aggregation import module_rollups as _module_rollups+from repowise.server.mcp_server.tool_health.coverage import (+ _attach_coverage_decay,+ _serialize_coverage_row,+)+from repowise.server.mcp_server.tool_health.plans import _validation_profile+from repowise.server.mcp_server.tool_health.serialize import (+ _health_finding_id,+ _perf_rank,+ _rank_emitted,+ _refactoring_plan_id,+ _serialize_refactoring,+)+from repowise.server.mcp_server.tool_health.tool import _ONLY_ALIASES, get_health++__all__ = [+ "_ONLY_ALIASES",+ "_attach_coverage_decay",+ "_health_finding_id",+ "_module_rollups",+ "_perf_rank",+ "_rank_emitted",+ "_refactoring_plan_id",+ "_serialize_coverage_row",+ "_serialize_refactoring",+ "_validation_profile",+ "get_health",+]diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/analysis_meta.py b/packages/server/src/repowise/server/mcp_server/tool_health/analysis_meta.pynew file mode 100644index 000000000..20c715ae9--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/tool_health/analysis_meta.py@@ -0,0 +1,123 @@+"""The stored-analysis freshness block get_health attaches to ``_meta``."""++from __future__ import annotations++from typing import Any++from sqlalchemy import func, select++from repowise.core.analysis.health.semantics import health_semantics_contract+from repowise.core.persistence.models import HealthFileMetric+++def _attach_health_analysis_meta(+ meta: dict[str, Any], metrics: list[HealthFileMetric]+) -> None:+ """Keep stored analysis distinct from index/live Git verification."""+ analyzed = [m for m in metrics if getattr(m, "updated_at", None)]+ latest = max(analyzed, key=lambda m: m.updated_at) if analyzed else None+ _write_health_analysis_meta(+ meta,+ has_metrics=bool(metrics),+ latest_at=latest.updated_at if latest is not None else None,+ latest_commit=getattr(latest, "analyzed_commit", None) if latest else None,+ distinct_commits=len({c for m in analyzed if (c := getattr(m, "analyzed_commit", None))}),+ )+++async def _attach_repository_analysis_meta(+ session: Any, repository: Any, meta: dict[str, Any]+) -> None:+ """The same block, computed over the repository rather than one file.++ Whether the analysis recorded its commit is a fact about the repository, so+ every mode must answer it from the repo-wide rows, not the rows it reports+ on, or a scoped call and the dashboard disagree. Bounded aggregates, no scan.+ """+ latest = (+ await session.execute(+ select(HealthFileMetric.updated_at, HealthFileMetric.analyzed_commit)+ .where(+ HealthFileMetric.repository_id == repository.id,+ HealthFileMetric.updated_at.is_not(None),+ )+ .order_by(HealthFileMetric.updated_at.desc())+ .limit(1)+ )+ ).first()+ total, distinct = (+ await session.execute(+ select(+ func.count(),+ func.count(func.distinct(HealthFileMetric.analyzed_commit)),+ ).where(HealthFileMetric.repository_id == repository.id)+ )+ ).one()+ _write_health_analysis_meta(+ meta,+ has_metrics=total > 0,+ latest_at=latest[0] if latest else None,+ latest_commit=latest[1] if latest else None,+ distinct_commits=distinct,+ )+++def _write_health_analysis_meta(+ meta: dict[str, Any],+ *,+ has_metrics: bool,+ latest_at: Any,+ latest_commit: str | None,+ distinct_commits: int,+) -> None:+ """The one place the analysis-freshness block is shaped."""+ meta["health_semantics"] = health_semantics_contract()+ metrics = has_metrics+ analyzed = latest_at is not None+ commits_count = distinct_commits+ # Metrics without a recorded commit are usable but unattributable: a+ # provenance gap, not degradation. ``degraded`` is reserved tool-wide for a+ # capability that failed or was unavailable.+ status = (+ "available" if latest_commit else "provenance_unknown" if metrics else "unavailable"+ )+ analysis: dict[str, Any] = {+ "status": status,+ "source": "stored_health_analysis",+ "recomputed_this_call": False,+ "live_verification": {+ "basis": (+ "index_commit_and_live_git_head"+ if meta.get("indexed_commit") and meta.get("live_head")+ else "unavailable"+ ),+ "source_bytes_verified": False,+ },+ "refresh": {+ "command": "repowise update",+ "precondition": "commit health-relevant working-tree changes first",+ "required_before_comparison": True,+ },+ }+ if not metrics:+ analysis["reason"] = "no_stored_health_metrics"+ if analyzed:+ analyzed_at = latest_at.isoformat()+ analysis["analyzed_at"] = analyzed_at+ meta["health_analyzed_at"] = analyzed_at+ if latest_commit:+ analyzed_commit = latest_commit[:12]+ analysis["analyzed_commit"] = analyzed_commit+ meta["health_analyzed_commit"] = analyzed_commit+ if commits_count > 1:+ analysis["analyzed_commits_distinct"] = commits_count+ meta["health_analyzed_commits_distinct"] = commits_count+ if not latest_commit:+ analysis["reason"] = "analysis_commit_not_recorded"+ analysis["analyzed_commit"] = None+ else:+ analysis["recorded_at"] = None+ analysis["recorded_commit"] = None+ if metrics:+ analysis["reason"] = "analysis_timestamp_not_recorded"+ meta["health_analysis"] = analysisdiff --git a/packages/server/src/repowise/server/mcp_server/tool_health/blocks.py b/packages/server/src/repowise/server/mcp_server/tool_health/blocks.pynew file mode 100644index 000000000..14ec02c0e--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/tool_health/blocks.py@@ -0,0 +1,170 @@+"""The ``include``-gated blocks get_health adds after the mode's own payload.++Applied in a fixed order: the response is a dict, so the order blocks are+added in is the order a caller reads them in.+"""++from __future__ import annotations++from typing import Any++from repowise.core.analysis.doc_drift.constants import DETECTION_BASIS+from repowise.core.analysis.health.suggestions import suggestion_for+from repowise.core.analysis.health.trends import (+ diff_snapshots,+ drop_unscoped_fields,+ recent_kpis,+)+from repowise.core.persistence.crud import serialize_doc_drift_row, summarize_confidence_rows+from repowise.server.mcp_server.tool_health.coverage import _coverage_block+from repowise.server.mcp_server.tool_health.loading import HealthData+from repowise.server.mcp_server.tool_health.paging import Pager+from repowise.server.mcp_server.tool_health.pillars import (+ _recommendation_lede,+ _render_performance,+ _render_refactoring,+)+from repowise.server.mcp_server.tool_health.plans import _render_plans+from repowise.server.mcp_server.tool_health.request import HealthRequest+from repowise.server.mcp_server.tool_health.serialize import _serialize_finding+++def add_optional_blocks(+ result: dict[str, Any], data: HealthData, req: HealthRequest, pager: Pager, repo_path: str+) -> None:+ include = req.include_set+ if "biomarkers" in include and "findings" not in result:+ _add_biomarkers(result, data, pager)+ if req.plans_requested:+ _render_plans(result, data, req, pager)+ if "trend" in include:+ result["trend"] = _trend_block(data, req, pager)+ _render_refactoring(result, data.refactoring, req, pager)+ _render_performance(result, data.performance, req, pager)+ if req.wants_lede:+ result["recommendation_lede"] = _recommendation_lede(+ data.performance, data.refactoring_recommendations, data.reference_repository, req+ )+ if "coverage" in include:+ result["coverage"] = _coverage_block(+ data.coverage_rows,+ data.coverage_summary,+ scoped=data.pop.scoped,+ pager=pager,+ repo_path=repo_path,+ )+ if "doc_drift" in include:+ result["doc_drift"] = _doc_drift_block(data, pager)+ # The dimension filter (``include=["performance"]`` etc.) is applied where+ # rows are selected: filtering here would filter a list already capped.+ if "refactoring" in include and req.wants("suggestion_legend"):+ result["suggestion_legend"] = _suggestion_legend(data)+++def _add_biomarkers(result: dict[str, Any], data: HealthData, pager: Pager) -> None:+ """Capped like every other ranked list.++ Uncapped, this block could return the repo's entire open finding set, far+ past an agent's context. Findings arrive impact-ordered, so the cap keeps+ the ones worth reading.+ """+ findings, repository = data.findings, data.reference_repository+ result["findings"] = pager.bound(+ [_serialize_finding(f, repository) for f in findings.finding_rows],+ "findings",+ )+ result["findings_total"] = findings.findings_total+ # Dashboard mode only (targeted mode already set ``findings``), so this+ # uses the same production/test split as ``top_findings``.+ result["test_findings"] = pager.bound(+ [_serialize_finding(f, repository) for f in findings.test_finding_rows],+ "test_findings",+ )+ result["test_findings_total"] = findings.test_findings_total+++_ALERT_FIELDS = (+ "kind",+ "metric",+ "current",+ "baseline",+ "delta",+ "message",+ "driver",+ "structure_delta",+ "history_delta",+)+++def _trend_block(data: HealthData, req: HealthRequest, pager: Pager) -> dict[str, Any]:+ summary = diff_snapshots(data.snapshots)+ narrowed = data.pop.reported_scope == "production"+ recent = recent_kpis(data.snapshots, limit=10)+ if narrowed:+ recent = drop_unscoped_fields(recent)+ alerts = [{name: getattr(a, name) for name in _ALERT_FIELDS} for a in summary.alerts]+ limit = req.limit+ # The hotspot pair describes the whole repository whatever the scope,+ # since only the average was snapshotted for both populations.+ block: dict[str, Any] = {+ "current_hotspot_health": None if narrowed else summary.current_hotspot_health,+ "current_average_health": summary.current_average_health,+ "previous_hotspot_health": None if narrowed else summary.previous_hotspot_health,+ "previous_average_health": summary.previous_average_health,+ "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": pager.bound(alerts, "trend.alerts"),+ "alerts_total": len(alerts),+ "alerts_emitted": min(len(alerts), limit),+ "recent": pager.bound(recent, "trend.recent"),+ "recent_total": len(recent),+ "recent_emitted": min(len(recent), limit),+ }+ if len(alerts) > limit:+ block["alerts_reduced_reason"] = "limit"+ if len(recent) > limit:+ block["recent_reduced_reason"] = "limit"+ return block+++def _doc_drift_block(data: HealthData, pager: Pager) -> dict[str, Any]:+ if data.drift_unavailable is not None:+ return {"unavailable": data.drift_unavailable}+ drift_rows = data.drift_rows+ drift_payload = pager.bound(+ # Evidence restates the row plus a resolver trace: not worth this+ # budget. The CLI, which has no budget, keeps it.+ [serialize_doc_drift_row(r, evidence=False) for r in drift_rows],+ "doc_drift.findings",+ )+ block: dict[str, Any] = {+ "findings": drift_payload,+ "findings_total": len(drift_rows),+ "findings_emitted": len(drift_payload),+ "documents": len({r.file_path for r in drift_rows}),+ "confidence": summarize_confidence_rows(drift_rows),+ # Without it, the findings would claim coverage this detector lacks:+ # most references are uncheckable.+ "findings_basis": DETECTION_BASIS,+ }+ if len(drift_payload) < len(drift_rows):+ block["findings_reduced_reason"] = "limit"+ return block+++def _suggestion_legend(data: HealthData) -> dict[str, str]:+ """One entry per biomarker type actually present in the findings this+ response carries.++ Built from the ranked rows, not the serialized blocks in ``result``: the+ ``only`` projection can skip building those, and a projection must never+ change what a surviving key contains.++ The legend explains the findings, not ``refactoring_plans``, so an entry can+ describe a biomarker no plan addresses. ``directive.plan_addresses_reason``+ reports that mismatch.+ """+ present_types = {getattr(r, "biomarker_type", None) for r in data.findings.legend_rows}+ return {bt: suggestion_for(bt) for bt in sorted(t for t in present_types if t)}diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/coverage.py b/packages/server/src/repowise/server/mcp_server/tool_health/coverage.pynew file mode 100644index 000000000..742071571--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/tool_health/coverage.py@@ -0,0 +1,118 @@+"""The coverage block for get_health: row serialization and measurement decay."""++from __future__ import annotations++import json+from typing import Any++from repowise.core.analysis.health.coverage import decay_since, measurement_ref+from repowise.server.mcp_server.tool_health.paging import Pager+++def _coverage_block(+ rows: list[Any],+ summary: dict[str, Any],+ *,+ scoped: bool,+ pager: Pager,+ repo_path: str,+) -> dict[str, Any]:+ """Per-file coverage rows plus the stored repo-wide summary.++ Drop the bulky covered-lines arrays from dashboard mode; full+ detail is available in targeted mode.+ """+ if scoped:+ selected_coverage = pager.bound(rows, "coverage.files")+ coverage_payload = [_serialize_coverage_row(r) for r in selected_coverage]+ _attach_coverage_decay(coverage_payload, selected_coverage, repo_path)+ else:+ # Built narrow: these rows were read without the column (see ``loading``).+ full_coverage_payload = [_serialize_coverage_row(r, covered_lines=False) for r in rows]+ coverage_payload = pager.bound(full_coverage_payload, "coverage.files")+ # ``ingested_at`` is a datetime on the summary too — coerce.+ if summary.get("ingested_at") is not None:+ summary = {**summary, "ingested_at": summary["ingested_at"].isoformat()}+ block: dict[str, Any] = {+ "summary": summary,+ "files": coverage_payload,+ "files_total": len(rows),+ "files_emitted": len(coverage_payload),+ }+ if len(coverage_payload) < len(rows):+ block["files_reduced_reason"] = "limit"+ return block+++def _attach_coverage_decay(payload: list[dict[str, Any]], rows: list[Any], repo_path: str) -> None:+ """Add a ``decay`` block to each coverage row, in place.++ The stored percentage is a measurement taken at one commit and never+ recomputed, so on a file under active development it can describe code that+ no longer exists. ``decay`` says how much of that measurement still holds:+ ``confirmed`` covered lines are unchanged since the report, ``invalidated``+ ones have moved and are now unknown rather than uncovered.++ Targeted mode only: dashboard mode skips ``covered_lines_json`` at the read,+ and computing drift there would undo that saving.++ Absent, not zero, when the measurement cannot be placed in history: a zero+ would read as a freshness claim.+ """+ if not rows:+ return+ first = rows[0]+ ref = measurement_ref(+ repo_path,+ getattr(first, "ingested_commit_sha", None),+ getattr(first, "ingested_at", None),+ )+ if ref is None:+ return+ covered_by_file = {+ entry["file_path"]: set(entry.get("covered_lines") or [])+ for entry in payload+ if entry.get("covered_lines")+ }+ decays = decay_since(repo_path, ref, covered_by_file)+ if not decays:+ return+ for entry in payload:+ d = decays.get(entry["file_path"])+ if d is None:+ continue+ entry["decay"] = {+ "measured_lines": d.measured,+ "confirmed_lines": d.confirmed,+ "invalidated_lines": d.invalidated,+ "drift_pct": d.drift_pct,+ "stale": d.is_stale,+ "measured_at_commit": ref[:12],+ }+++def _serialize_coverage_row(row: Any, *, covered_lines: bool = True) -> dict[str, Any]:+ """One coverage row. ``covered_lines=False`` omits the per-line array.++ The narrow form is not the wide form minus a key: a row read with+ ``include_covered_lines=False`` carries no ``covered_lines_json`` at all, so+ touching it would raise rather than merely waste the parse.+ """+ out: dict[str, Any] = {+ "file_path": row.file_path,+ "source_format": row.source_format,+ "line_coverage_pct": row.line_coverage_pct,+ "branch_coverage_pct": row.branch_coverage_pct,+ }+ # Inserted here, not appended, so the wide form's key order is unchanged.+ if covered_lines:+ try:+ out["covered_lines"] = (+ json.loads(row.covered_lines_json) if row.covered_lines_json else []+ )+ except Exception:+ out["covered_lines"] = []+ out["total_coverable_lines"] = row.total_coverable_lines+ out["ingested_at"] = row.ingested_at.isoformat() if row.ingested_at else None+ out["ingested_commit_sha"] = row.ingested_commit_sha+ return outdiff --git a/packages/server/src/repowise/server/mcp_server/tool_health/dashboard.py b/packages/server/src/repowise/server/mcp_server/tool_health/dashboard.pynew file mode 100644index 000000000..c0b7af852--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/tool_health/dashboard.py@@ -0,0 +1,163 @@+"""get_health dashboard mode: the repository-wide view when no target is named."""++from __future__ import annotations++from typing import Any++from repowise.core.analysis.health.aggregation import module_rollups as _module_rollups+from repowise.core.analysis.health.defect_accuracy import compute_defect_accuracy+from repowise.core.analysis.health.grading import TARGET_SCORE+from repowise.core.analysis.health.grading import distribution as health_distribution+from repowise.server.mcp_server.tool_health.loading import HealthData+from repowise.server.mcp_server.tool_health.paging import Pager+from repowise.server.mcp_server.tool_health.request import HealthRequest+from repowise.server.mcp_server.tool_health.serialize import _serialize_finding, _serialize_metric+from repowise.server.mcp_server.tool_health.summary import (+ _compute_kpis,+ _directive,+ _gap_analysis,+)+from repowise.server.mcp_server.tool_health.targeted import ModeTotals+++def build_dashboard(+ data: HealthData, req: HealthRequest, pager: Pager+) -> tuple[dict[str, Any], ModeTotals]:+ """Top-N worst files + headline findings + the per-module rollup.++ The rollup rides along so the overview page needs no second round-trip.+ ``by_leverage`` is built in ``loading``, before the leads.+ """+ pop = data.pop+ all_metrics = pop.all_metrics+ findings = data.findings+ all_modules = _module_rollups(all_metrics, data.deductions)+ gap = _gap_analysis(all_metrics)+ # KPIs keep test files unless ``scope`` narrows them. Tests score better+ # than production code, so narrowing lowers the number with no new defect+ # found: a caller should ask for it knowingly.+ kpis = _compute_kpis(+ all_metrics,+ hotspot_paths=data.hotspot_paths,+ performance_findings=data.perf_findings_count,+ coverage=data.perf_coverage,+ )+ result: dict[str, Any] = {+ # Lead with the recommendation; every block below ranks and describes.+ "directive": _directive(+ data.by_leverage,+ data.leads,+ gap.get("weighted_gross_gap_points") or 0,+ data.plan_biomarkers_by_path,+ data.plan_count_by_path,+ ),+ # Additive leads for the refactoring and performance pillars, which+ # the deficit-ranked directive above cannot express.+ **(+ {"refactoring_directive": data.refactoring.directive}+ if data.refactoring.directive is not None+ else {}+ ),+ **(+ {"performance_directive": data.performance.directive}+ if data.performance.directive is not None+ else {}+ ),+ "mode": "dashboard",+ "scope": pop.reported_scope,+ "counts": pop.reported_counts,+ "unscored_files": pop.unscored_files,+ "kpis": kpis,+ "distribution": health_distribution(all_metrics),+ # Where the gap to the target concentrates: a short list of files.+ "gap_analysis": gap,+ "worst_files": pager.bound([_metric_row(data, m) for m in data.metric_rows], "worst_files"),+ # Ranked file lists keep test files in place and mark them; dropping+ # them would change which files are "worst". Only finding lists split.+ "worst_files_total": len(data.metric_rows),+ "high_leverage_files": pager.bound(_high_leverage_rows(data, gap), "high_leverage_files"),+ "high_leverage_files_total": len(data.by_leverage),+ "top_findings": pager.bound(+ [_serialize_finding(f, data.reference_repository) for f in findings.finding_rows],+ "top_findings",+ ),+ "top_findings_total": findings.findings_total,+ # The test half of the same ranked set, kept out of the production list.+ "test_findings": pager.bound(+ [_serialize_finding(f, data.reference_repository) for f in findings.test_finding_rows],+ "test_findings",+ ),+ "test_findings_total": findings.test_findings_total,+ # Worst-first, so the cap keeps the modules worth looking at.+ "modules": pager.bound(all_modules, "modules"),+ "modules_total": len(all_modules),+ }+ if not req.only:+ _defer_to_secondary_rankings(result, req, data, len(all_modules))+ if "churn_complexity" in req.include_set:+ result["churn_complexity"] = pager.bound(data.churn_points, "churn_complexity")+ if "accuracy" in req.include_set:+ # Does the score rank the buggy files first? Scored over the full open+ # set, not the capped head, which would be circular.+ result["defect_accuracy"] = compute_defect_accuracy(+ all_metrics,+ [_serialize_finding(f, data.reference_repository) for f in data.accuracy_rows],+ # Same map ``all_metrics`` was ranked with, so it scores these ``worst_files``.+ deductions=data.deductions,+ )+ return result, ModeTotals(metrics=None, trends=None, modules=len(all_modules))+++def _metric_row(data: HealthData, m: Any) -> dict[str, Any]:+ return _serialize_metric(m, data.leads.get(m.file_path), is_test=m.file_path in data.test_paths)+++def _high_leverage_rows(data: HealthData, gap: dict[str, Any]) -> list[dict[str, Any]]:+ """The leverage ranking, each row with its share of the repository's gap.++ The one place ``weighted_deficit`` gets a denominator, in the unit+ ``directive`` speaks. The denominator is the gross deficit of below-target+ files, so shares stay within 100%; the net gap would let above-target files+ shrink it and push one large file past 100% (issue #1437).+ """+ gross = gap.get("weighted_gross_gap_points")+ return [+ {+ **_metric_row(data, m),+ "share_of_repo_gap_pct": (+ round(+ 100.0+ * max(TARGET_SCORE - m.score, 0.0)+ * max(m.nloc, 1)+ / gap["weighted_gross_gap_points"],+ 1,+ )+ if gross+ else None+ ),+ }+ for m in data.by_leverage+ ]+++def _defer_to_secondary_rankings(+ result: dict[str, Any], req: HealthRequest, data: HealthData, modules_total: int+) -> None:+ """An unprojected dashboard leads with the summary; the ranked lists become calls."""+ repo = req.repo+ totals = {+ "worst_files": len(data.metric_rows),+ "top_findings": data.findings.findings_total,+ "test_findings": data.findings.test_findings_total,+ "modules": modules_total,+ }+ result["secondary_rankings"] = {+ block: {+ "total": total,+ "call": f"get_health(repo={repo!r}, only=['{block}'], limit=50)",+ }+ for block, total in totals.items()+ }+ for block in totals:+ result.pop(block, None)+ result.pop(f"{block}_total", None)diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/details.py b/packages/server/src/repowise/server/mcp_server/tool_health/details.pynew file mode 100644index 000000000..e8961c708--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/tool_health/details.py@@ -0,0 +1,327 @@+"""get_health detail modes: one finding, plan or opportunity looked up by id."""++from __future__ import annotations++from typing import Any++from sqlalchemy import select++from repowise.core.analysis.health.counts import DEFAULT_COUNTS+from repowise.core.analysis.health.scope import DEFAULT_SCOPE+from repowise.core.persistence.crud import get_health_finding_by_public_id+from repowise.core.persistence.models import HealthFinding+from repowise.server.mcp_server._meta import build_meta as _build_meta+from repowise.server.mcp_server.tool_health.analysis_meta import _attach_repository_analysis_meta+from repowise.server.mcp_server.tool_health.pillars import (+ _PERFORMANCE_EVIDENCE_PAGE_CAP,+ _REFACTORING_EVIDENCE_CAP,+ _REFACTORING_EVIDENCE_PAGE_CAP,+ _REFACTORING_OPPORTUNITY_PREFIX,+ _REFACTORING_STEP_PAGE_CAP,+)+from repowise.server.mcp_server.tool_health.serialize import (+ _health_finding_id,+ _legacy_health_finding_id,+ _serialize_finding,+)+from repowise.server.services.performance_health import (+ PerformanceHealthService,+ evidence_block,+)+from repowise.server.services.refactoring_health import RefactoringHealthService+++async def _detail_response(+ session: Any,+ repository: Any,+ reference_repository: str,+ *,+ finding_id: str | None,+ plan_id: str | None,+ opportunity_id: str | None,+ only_set: set[str],+ limit: int,+ cursor: int,+) -> dict[str, Any] | None:+ """Answer a lookup by id, or ``None`` when no selector was passed.++ At most one selector is set by the time this runs: ``_selector_conflict``+ refuses two before any read.+ """+ if finding_id:+ return await _finding_detail_response(+ session, repository, reference_repository, finding_id+ )+ if opportunity_id and opportunity_id.startswith(_REFACTORING_OPPORTUNITY_PREFIX):+ return await _refactoring_detail_response(+ session,+ repository,+ reference_repository,+ opportunity_id,+ evidence_only=only_set == {"refactoring_evidence"},+ limit=limit,+ cursor=cursor,+ )+ if opportunity_id:+ return await _performance_detail_response(+ session,+ repository,+ reference_repository,+ opportunity_id,+ evidence_only=only_set == {"performance_evidence"},+ limit=limit,+ cursor=cursor,+ )+ if plan_id:+ return await _plan_detail_response(session, repository, reference_repository, plan_id)+ return None+++async def _finding_detail_response(+ session: Any, repository: Any, reference_repository: str, finding_id: str+) -> dict[str, Any]:+ match = await _resolve_finding(session, repository.id, finding_id, reference_repository)+ result = {+ "mode": "finding",+ "finding_id": finding_id,+ "finding": (+ _serialize_finding(match, reference_repository) if match else None+ ),+ "resolved": match is not None,+ "_meta": _build_meta(+ repository=repository,+ targets=[match.file_path] if match else None,+ ),+ }+ await _attach_repository_analysis_meta(session, repository, result["_meta"])+ return result+++async def _plan_detail_response(+ session: Any, repository: Any, reference_repository: str, plan_id: str+) -> dict[str, Any]:+ """One stored plan, and the composed opportunity it is a step of, if any.++ An indexed seek and one hydration, not a scan of every open plan.+ """+ service = RefactoringHealthService(session, repository.id, reference_repository)+ resolved = await service.plan_detail(plan_id)+ plan = resolved.get("plan") if resolved.get("resolved") else None+ if plan is not None:+ plan.setdefault("id", plan_id)+ plan["repository"] = reference_repository+ result = {+ "mode": "refactoring_plan",+ "plan_id": plan_id,+ "plan": plan,+ "resolved": bool(resolved.get("resolved")),+ "_meta": _build_meta(+ repository=repository,+ targets=[plan["file_path"]] if plan else None,+ ),+ }+ if resolved.get("opportunity_id"):+ result["opportunity_id"] = resolved["opportunity_id"]+ result["next_action"] = resolved["next_action"]+ elif plan is not None:+ result["opportunity_note"] = (+ "This plan is addressable but is not a step of any composed "+ "opportunity; a demoted clone is supporting evidence, not work."+ )+ await _attach_repository_analysis_meta(session, repository, result["_meta"])+ return result+++def _selector_conflict(**selectors: str | None) -> dict[str, Any] | None:+ """Refuse two detail selectors instead of answering about one of them.++ Answering the first one checked would silently drop the other.+ """+ named = sorted(name for name, value in selectors.items() if value)+ if len(named) < 2:+ return None+ return {+ "mode": "conflict",+ "resolved": False,+ "reason": "mutually_exclusive_selectors",+ "selectors": named,+ "detail": "Pass exactly one of finding_id, plan_id, opportunity_id.",+ }+++def _note_inapplicable_controls(+ result: dict[str, Any], scope: str, counts: str+) -> dict[str, Any]:+ """Name ``scope`` / ``counts`` when a detail lookup cannot honour them.++ These select a population; a lookup by id returns one stored row, always+ the calibrated reading, so a silent accept would mislead the caller.+ """+ inapplicable = {+ name: value+ for name, value, default in (+ ("scope", scope, DEFAULT_SCOPE),+ ("counts", counts, DEFAULT_COUNTS),+ )+ if value is not None and value != default+ }+ if inapplicable:+ result["ignored_arguments"] = {**result.get("ignored_arguments", {}), **inapplicable}+ return result+++async def _resolve_finding(+ session: Any, repository_id: str, finding_id: str, repository: str+) -> Any:+ """Find one health finding by any id form a caller can be holding.++ The public id is a column, so the common case is a seek. The scan is the+ compatibility path: a raw storage id, or an id minted before the column+ existed, still has to resolve.+ """+ match = await get_health_finding_by_public_id(session, repository_id, finding_id)+ if match is not None:+ return match+ rows = (+ (+ await session.execute(+ select(HealthFinding).where(+ HealthFinding.repository_id == repository_id,+ HealthFinding.status == "open",+ )+ )+ )+ .scalars()+ .all()+ )+ return next(+ (+ row+ for row in rows+ if finding_id+ in {+ row.id,+ _health_finding_id(row, repository),+ _legacy_health_finding_id(row, repository),+ }+ ),+ None,+ )+++async def _performance_detail_response(+ session: Any,+ repository: Any,+ reference_repository: str,+ opportunity_id: str,+ *,+ evidence_only: bool,+ limit: int,+ cursor: int,+) -> dict[str, Any]:+ """One causal opportunity, or one page of the evidence behind it.++ ``limit`` means what it means everywhere else, ``0`` included: reading it+ as "unset" would return a page the caller declined.+ """+ service = PerformanceHealthService(session, repository.id, reference_repository)+ evidence_limit = min(max(limit, 0), _PERFORMANCE_EVIDENCE_PAGE_CAP)+ if evidence_only:+ rows, total = await service.evidence(+ opportunity_id, limit=evidence_limit, offset=cursor+ )+ return {+ "mode": "performance_evidence",+ "opportunity_id": opportunity_id,+ "resolved": total > 0,+ **evidence_block(rows, total, cursor),+ "_meta": _build_meta(repository=repository),+ }+ detail = await service.detail(opportunity_id, evidence_limit=evidence_limit)+ file_path = detail.get("file_path")+ result = {+ "mode": "performance_opportunity",+ **detail,+ "_meta": _build_meta(+ repository=repository, targets=[file_path] if file_path else None+ ),+ }+ await _attach_repository_analysis_meta(session, repository, result["_meta"])+ return result+++async def _refactoring_detail_response(+ session: Any,+ repository: Any,+ reference_repository: str,+ opportunity_id: str,+ *,+ evidence_only: bool,+ limit: int,+ cursor: int,+) -> dict[str, Any]:+ """One composed opportunity, or one page of the evidence behind it."""+ service = RefactoringHealthService(session, repository.id, reference_repository)+ if evidence_only:+ detail = await service.detail(+ opportunity_id,+ step_limit=0,+ evidence_limit=min(max(limit, 0), _REFACTORING_EVIDENCE_PAGE_CAP),+ evidence_offset=cursor,+ with_plans=False,+ )+ block = {k: v for k, v in detail.items() if k.startswith("evidence")}+ result = {+ "mode": "refactoring_evidence",+ "opportunity_id": opportunity_id,+ "resolved": bool(detail.get("resolved")),+ **block,+ "_meta": _build_meta(repository=repository),+ }+ if block.get("evidence_next_cursor") is not None:+ result["recovery"] = {+ "evidence": {+ "remaining": block["evidence_total"] - block["evidence_next_cursor"],+ "call": (+ f"get_health(opportunity_id={opportunity_id!r}, "+ f"only=['refactoring_evidence'], limit={limit}, "+ f"cursor={block['evidence_next_cursor']})"+ ),+ }+ }+ return result+ detail = await service.detail(+ opportunity_id,+ step_limit=min(max(limit, 0), _REFACTORING_STEP_PAGE_CAP),+ step_offset=cursor,+ evidence_limit=_REFACTORING_EVIDENCE_CAP,+ )+ file_path = detail.get("file_path")+ if not detail.get("resolved"):+ detail.setdefault(+ "model_state", _refactoring_model_state(opportunity_id)+ )+ result = {+ "mode": "refactoring_opportunity",+ **detail,+ "_meta": _build_meta(+ repository=repository, targets=[file_path] if file_path else None+ ),+ }+ await _attach_repository_analysis_meta(session, repository, result["_meta"])+ return result+++def _refactoring_model_state(opportunity_id: str) -> dict[str, Any]:+ """Tell a stale-model id apart from a wrong one, from the string alone."""+ from repowise.core.analysis.health.refactoring.identity import (+ REFACTORING_MODEL_VERSION,+ model_state,+ )++ state = model_state(+ opportunity_id.replace(_REFACTORING_OPPORTUNITY_PREFIX, "refac", 1)+ )+ state["public_id"] = opportunity_id+ state["refactoring_model_version"] = REFACTORING_MODEL_VERSION+ return statediff --git a/packages/server/src/repowise/server/mcp_server/tool_health/findings.py b/packages/server/src/repowise/server/mcp_server/tool_health/findings.pynew file mode 100644index 000000000..8cdfab4f6--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/tool_health/findings.py@@ -0,0 +1,217 @@+"""Which open findings one get_health call ranks, emits, and totals."""++from __future__ import annotations++from dataclasses import dataclass, field+from typing import Any++from sqlalchemy import select++from repowise.core.persistence.models import HealthFinding+from repowise.server.mcp_server.tool_health.population import Population+from repowise.server.mcp_server.tool_health.request import HealthRequest+from repowise.server.mcp_server.tool_health.serialize import _rank_emitted+++def _in_dimensions(row: Any, dimensions: set[str]) -> bool:+ """True when *row* belongs to one of *dimensions* (empty set -> everything).++ A NULL ``dimension`` means ``defect``: the column was added without a+ backfill, so older rows stay NULL until the next index.+ """+ if not dimensions:+ return True+ return (row.dimension or "defect") in dimensions+++@dataclass+class FindingSets:+ """Two row sets, deliberately split.++ ``finding_rows`` are the ones this response will serialize. ``lead_rows``+ is the wider set the per-file leads and exact totals come from, and needs+ only a few columns.++ Targeted mode names a handful of files, so one full read serves both.+ Dashboard mode reads narrow, since hydrating every open finding grows with+ the repo.++ ``test_finding_rows`` is the dashboard-only test bucket. Targeted mode never+ fills it: the caller named the files, so partitioning them would answer a+ different question.+ """++ finding_rows: list[Any]+ lead_rows: list[Any]+ legend_rows: list[Any]+ # The ranked, dimension-filtered set, before any cap. The first row is the+ # one ``refactoring_plans_status`` points at when no plan exists.+ emitted: list[Any]+ # A total describes the list it sits beside (#1337): the post-exclusion,+ # dimension-filtered open set, and in dashboard mode its production half.+ # With ``test_findings_total`` it sums to the whole open set.+ findings_total: int+ test_finding_rows: list[Any] = field(default_factory=list)+ test_findings_total: int = 0+++def _open_findings(repository: Any) -> tuple[Any, Any]:+ return (+ HealthFinding.repository_id == repository.id,+ HealthFinding.status == "open",+ )+++async def load_targeted_findings(+ session: Any, repository: Any, pop: Population, req: HealthRequest+) -> FindingSets:+ """Every open finding on the named files: one full read serves both sets."""+ finding_rows = pop.in_counts_findings(pop.in_scope_rows(+ list(+ (+ await session.execute(+ select(HealthFinding)+ .where(*_open_findings(repository))+ .where(HealthFinding.file_path.in_(pop.effective_targets))+ .order_by(HealthFinding.health_impact.desc())+ )+ )+ .scalars()+ .all()+ ),+ "file_path",+ ))+ emitted = _rank_emitted(+ [f for f in finding_rows if _in_dimensions(f, req.ranked_dimensions)]+ )+ return FindingSets(+ finding_rows=emitted,+ lead_rows=finding_rows,+ legend_rows=emitted,+ emitted=emitted,+ findings_total=len(emitted),+ )+++async def load_dashboard_findings(+ session: Any,+ repository: Any,+ pop: Population,+ req: HealthRequest,+ test_paths: set[str],+) -> FindingSets:+ """A narrow ranked read of every open finding, then the two heads by id."""+ lead_rows = pop.in_counts_findings(+ pop.in_scope_rows(await _read_lite_findings(session, repository, req))+ )+ # ``lead_rows`` stays unfiltered: the leads and performance KPI must not+ # change because the caller asked to see one dimension.+ emitted = _rank_emitted(+ [r for r in lead_rows if _in_dimensions(r, req.ranked_dimensions)]+ )+ # Test findings get their own bucket instead of crowding the headline+ # list. Split before the cap, so each list is the top ``limit`` of its+ # own population.+ prod_emitted = [r for r in emitted if r.file_path not in test_paths]+ test_emitted = [r for r in emitted if r.file_path in test_paths]+ limit = req.limit+ # Fetch the head by id: exactly ``limit`` rows whatever the exclusions,+ # where an over-fetch margin on the ranked query could approach a full read.+ head_ids = [r.id for r in prod_emitted[:limit]] if req.wants_findings else []+ test_head_ids = [r.id for r in test_emitted[:limit]] if req.wants_test_findings else []+ by_id = await _read_findings_by_id(session, head_ids + test_head_ids)+ return FindingSets(+ # Re-imposed from the id lists; ``IN`` does not preserve order.+ finding_rows=[by_id[i] for i in head_ids if i in by_id],+ lead_rows=lead_rows,+ # Decided here so the legend is a pure function of the ranked set,+ # which no projection can change.+ legend_rows=prod_emitted[:limit] + test_emitted[:limit],+ emitted=emitted,+ findings_total=len(prod_emitted),+ test_finding_rows=[by_id[i] for i in test_head_ids if i in by_id],+ test_findings_total=len(test_emitted),+ )+++async def _read_lite_findings(session: Any, repository: Any, req: HealthRequest) -> list[Any]:+ """Narrow read over every open finding.++ The columns ``_leads_by_file`` reads, plus ``dimension`` and ``id``. A+ SQLAlchemy ``Row`` exposes them as attributes, so the reduction and the+ exclude filter run against it unchanged.++ ``details_json`` joins only when the performance dimension is asked for:+ perf findings carry ``health_impact: 0``, so only then can one reach the+ head, and the column is not worth its read cost otherwise.+ """+ lite_cols = [+ HealthFinding.id,+ HealthFinding.file_path,+ HealthFinding.health_impact,+ HealthFinding.biomarker_type,+ HealthFinding.reason,+ HealthFinding.dimension,+ ]+ if "performance" in req.dimension_filter:+ lite_cols.append(HealthFinding.details_json)+ if req.wants_performance_opportunities:+ lite_cols.extend(+ [+ HealthFinding.function_name,+ HealthFinding.line_start,+ HealthFinding.line_end,+ ]+ )+ return list(+ (+ await session.execute(+ select(*lite_cols)+ .where(*_open_findings(repository))+ .order_by(HealthFinding.health_impact.desc())+ )+ ).all()+ )+++async def _read_findings_by_id(session: Any, ids: list[str]) -> dict[str, Any]:+ """One read for both heads, which partition the same ranked set."""+ if not ids:+ return {}+ return {+ f.id: f+ for f in (+ await session.execute(select(HealthFinding).where(HealthFinding.id.in_(ids)))+ )+ .scalars()+ .all()+ }+++async def read_accuracy_rows(+ session: Any, repository: Any, pop: Population, req: HealthRequest+) -> list[Any]:+ """The ``prior_defect`` labels the accuracy block scores the ranking against.++ ``compute_defect_accuracy`` reads only ``prior_defect``, so selecting those+ directly keeps the whole-repo denominator without a full read.++ Not routed through ``in_counts_findings``: these are the ground truth, not a+ deduction, and dropping them under ``code_shape`` would leave no labels.+ """+ if "accuracy" not in req.include_set or pop.scoped:+ return []+ return pop.in_scope_rows(+ list(+ (+ await session.execute(+ select(HealthFinding)+ .where(*_open_findings(repository))+ .where(HealthFinding.biomarker_type == "prior_defect")+ )+ )+ .scalars()+ .all()+ ),+ "file_path",+ )diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/loading.py b/packages/server/src/repowise/server/mcp_server/tool_health/loading.pynew file mode 100644index 000000000..2a7248635--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/tool_health/loading.py@@ -0,0 +1,437 @@+"""Every read one get_health call needs, gated on the blocks that will use it.++``load_health_data`` runs inside the caller's session and returns plain rows;+nothing after it touches the database except the analysis-freshness block.+Each reader returns its empty value when its block was not asked for, so the+projection gates the work as well as the payload.+"""++from __future__ import annotations++from dataclasses import asdict, dataclass, field+from typing import Any++from sqlalchemy import select+from sqlalchemy.exc import SQLAlchemyError++from repowise.core.analysis.doc_drift.constants import UNAVAILABLE_NO_TABLE+from repowise.core.analysis.health.churn_complexity import churn_complexity_points+from repowise.core.analysis.health.grading import TARGET_SCORE+from repowise.core.analysis.health.perf.coverage import PerfCoverage, coverage_for_metrics+from repowise.core.analysis.health.ranking import deduction_by_path, sort_metrics_worst_first+from repowise.core.analysis.health.refactoring.recommendations import (+ Recommendation,+ hydrate_recommendations,+)+from repowise.core.analysis.health.signals import file_signals+from repowise.core.analysis.health.trends import project_scope+from repowise.core.ingestion.models import FILE_DEPENDENCY_EDGE_TYPES+from repowise.core.persistence.crud import (+ get_all_git_metadata,+ get_coverage_summary,+ get_doc_drift_findings,+ get_file_language_map,+ get_git_metadata_bulk,+ get_hotspot_file_paths,+ get_node_degree_counts_bulk,+ get_refactoring_suggestions,+ get_test_file_paths,+ list_health_snapshots,+ load_coverage_for_repo,+)+from repowise.core.persistence.models import HealthFileMetric, RefactoringSuggestion+from repowise.server.mcp_server._helpers import filter_rows_by_attr+from repowise.server.mcp_server.tool_health.findings import (+ FindingSets,+ load_dashboard_findings,+ load_targeted_findings,+ read_accuracy_rows,+)+from repowise.server.mcp_server.tool_health.pillars import (+ _performance_blocks,+ _PerformanceBlocks,+ _refactoring_blocks,+ _RefactoringBlocks,+)+from repowise.server.mcp_server.tool_health.population import Population, load_population+from repowise.server.mcp_server.tool_health.request import HealthRequest+from repowise.server.mcp_server.tool_health.summary import _DIRECTIVE_CANDIDATES, _leads_by_file+from repowise.server.services.performance_health import PerformanceHealthService+from repowise.server.services.refactoring_health import RefactoringHealthService, plan_view+++@dataclass+class HealthData:+ """The rows one response is built from, read inside a single session."""++ repository: Any+ reference_repository: str+ pop: Population+ test_paths: set[str]+ findings: FindingSets+ deductions: dict[str, float]+ metric_rows: list[HealthFileMetric]+ refactoring: _RefactoringBlocks+ performance: _PerformanceBlocks+ by_leverage: list[HealthFileMetric]+ leads: dict[str, dict[str, Any]]+ hotspot_paths: set[str] = field(default_factory=set)+ perf_coverage: PerfCoverage | None = None+ perf_findings_count: int = 0+ accuracy_rows: list[Any] = field(default_factory=list)+ refactoring_rows: list[Any] = field(default_factory=list)+ refactoring_recommendations: list[Recommendation] = field(default_factory=list)+ coverage_rows: list[Any] = field(default_factory=list)+ coverage_summary: dict[str, Any] = field(default_factory=dict)+ signals_by_path: dict[str, dict[str, Any]] = field(default_factory=dict)+ drift_rows: list[Any] = field(default_factory=list)+ drift_unavailable: str | None = None+ churn_points: list[dict[str, Any]] = field(default_factory=list)+ snapshots: list[Any] = field(default_factory=list)+ plan_biomarkers_by_path: dict[str, set[str]] = field(default_factory=dict)+ plan_count_by_path: dict[str, int] = field(default_factory=dict)+++async def load_health_data(+ session: Any, repository: Any, reference_repository: str, repo_path: Any, req: HealthRequest+) -> HealthData:+ """Run every read the requested blocks need, in one session."""+ pop = await load_population(session, repository, repo_path, req)+ test_paths = await _read_test_paths(session, repository, pop, req)+ if pop.scoped:+ findings = await load_targeted_findings(session, repository, pop, req)+ else:+ findings = await load_dashboard_findings(session, repository, pop, req, test_paths)++ # Same worst-first comparator as the crud layer, so REST and this tool+ # agree on the worst file. From ``lead_rows``, the unfiltered open set:+ # viewing one dimension must not change which files are worst.+ deductions = deduction_by_path(findings.lead_rows)+ # Rebound before every reader: ``min()`` and stable sorts break ties by+ # input order, so every block must see the same order as ``worst_files``.+ pop.all_metrics = sort_metrics_worst_first(pop.all_metrics, deductions)+ targets = set(pop.effective_targets)+ metric_rows = (+ [m for m in pop.all_metrics if m.file_path in targets] if pop.scoped else pop.all_metrics+ )+ data = HealthData(+ repository=repository,+ reference_repository=reference_repository,+ pop=pop,+ test_paths=test_paths,+ findings=findings,+ deductions=deductions,+ metric_rows=metric_rows,+ refactoring=_RefactoringBlocks(),+ performance=_PerformanceBlocks(),+ by_leverage=[],+ leads={},+ )+ data.hotspot_paths = await _read_hotspot_paths(session, repository, pop, req)+ data.perf_coverage, data.perf_findings_count = await _read_perf_headline(+ session, repository, pop, req, findings.lead_rows+ )+ data.accuracy_rows = await read_accuracy_rows(session, repository, pop, req)+ data.refactoring_rows, data.refactoring_recommendations = await _read_refactoring_plans(+ session, repository, pop, req+ )+ data.refactoring, data.performance = await _read_pillars(+ session, repository, reference_repository, pop, req+ )+ data.coverage_rows, data.coverage_summary = await _read_coverage(+ session, repository, pop, req+ )+ data.signals_by_path = await _read_signals(session, repository, pop, req)+ data.drift_rows, data.drift_unavailable = await _read_doc_drift(+ session, repository, pop, req+ )+ data.churn_points = await _read_churn_points(session, repository, pop, req)+ data.snapshots = await _read_snapshots(session, repository, pop, req)+ data.by_leverage, data.leads = _rank_leverage_and_leads(pop, metric_rows, findings, req)+ data.plan_biomarkers_by_path, data.plan_count_by_path = await _read_directive_plans(+ session, repository, pop, req, data.by_leverage+ )+ return data+++async def _read_test_paths(+ session: Any, repository: Any, pop: Population, req: HealthRequest+) -> set[str]:+ """Test material, from the flag ingestion already decided per file.++ Gated on ``needs_test_paths`` and run after the ``module:`` expansion.+ Targeted mode reads only the named paths; dashboard mode partitions a+ finding list whose paths are not yet known, so it reads repo-wide.+ """+ if not req.needs_test_paths:+ return set()+ return await get_test_file_paths(+ session, repository.id, pop.effective_targets if pop.scoped else None+ )+++async def _read_hotspot_paths(+ session: Any, repository: Any, pop: Population, req: HealthRequest+) -> set[str]:+ """Hotspot paths for the canonical hotspot-health KPI.++ Skipped in targeted mode, which builds no ``kpis`` block."""+ if pop.scoped or not req.wants("kpis"):+ return set()+ return await get_hotspot_file_paths(session, repository.id)+++async def _read_perf_headline(+ session: Any, repository: Any, pop: Population, req: HealthRequest, lead_rows: list[Any]+) -> tuple[PerfCoverage | None, int]:+ """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."""+ if pop.scoped or not req.wants("kpis"):+ return None, 0+ lang_by_path = await get_file_language_map(session, repository.id)+ return (+ coverage_for_metrics(pop.all_metrics, lang_by_path),+ sum(1 for f in lead_rows if (f.dimension or "defect") == "performance"),+ )+++async def _read_refactoring_plans(+ session: Any, repository: Any, pop: Population, req: HealthRequest+) -> tuple[list[Any], list[Recommendation]]:+ """Plans scoped to the same targets, exclude-filtered like findings."""+ if not req.plans_requested or pop.nothing_resolved:+ return [], []+ rows = pop.in_scope_rows(+ await get_refactoring_suggestions(+ session,+ repository.id,+ file_paths=list(pop.effective_targets) if pop.scoped else None,+ ),+ "file_path",+ )+ recommendations = await hydrate_recommendations(+ session,+ repository.id,+ rows,+ metric_rows=pop.all_metrics,+ view=plan_view(req.refactoring_view),+ )+ return rows, recommendations+++async def _read_pillars(+ session: Any, repository: Any, reference_repository: str, pop: Population, req: HealthRequest+) -> tuple[_RefactoringBlocks, _PerformanceBlocks]:+ """The materialized causal read model. Filtering, ordering, paging, plan+ linkage, and facets are the shared service's; this tool caps the+ collection, pages it, and serializes what comes back."""+ performance_service = PerformanceHealthService(+ session, repository.id, reference_repository+ )+ refactoring_service = RefactoringHealthService(+ session, repository.id, reference_repository+ )+ refactoring = await _refactoring_blocks(+ refactoring_service,+ wants=req.wants,+ included="refactoring" in req.include_set and req.wants_refactoring_opportunities,+ file_paths=pop.target_paths,+ scoped=pop.scoped,+ limit=req.limit,+ cursor=req.cursor,+ view=req.refactoring_view,+ lead_type=req.refactoring_type,+ confidence=req.refactoring_confidence,+ effort=req.refactoring_effort,+ )+ performance = await _performance_blocks(+ performance_service,+ wants=req.wants,+ included="performance" in req.include_set and req.wants_performance_opportunities,+ file_paths=pop.target_paths,+ scoped=pop.scoped,+ limit=req.limit,+ cursor=req.cursor,+ view=req.performance_view,+ context=req.performance_context,+ boundary=req.performance_boundary,+ confidence=req.performance_confidence,+ actionability=req.performance_actionability,+ sort=req.performance_sort,+ )+ return refactoring, performance+++async def _read_coverage(+ session: Any, repository: Any, pop: Population, req: HealthRequest+) -> tuple[list[Any], dict[str, Any]]:+ if "coverage" not in req.include_set or pop.nothing_resolved:+ return [], {}+ rows = pop.in_scope_rows(+ # ``effective_targets``: a raw ``module:foo`` is not a file path.+ # Only targeted mode serializes ``covered_lines``, so the dashboard+ # declines that column at the read.+ await load_coverage_for_repo(+ session,+ repository.id,+ file_paths=list(pop.effective_targets) if pop.scoped else None,+ include_covered_lines=pop.scoped,+ ),+ "file_path",+ )+ # A stored repo-wide aggregate cannot describe a narrowed population, so+ # it is omitted there; the rows stay.+ summary = (+ {}+ if pop.reported_scope == "production"+ else await get_coverage_summary(session, repository.id)+ )+ return rows, summary+++async def _read_signals(+ session: Any, repository: Any, pop: Population, req: HealthRequest+) -> dict[str, dict[str, Any]]:+ """Per-file process/people/topology signals for targeted files.++ The same join the file-detail drawer and REST breakdown use."""+ if "signals" not in req.include_set or not pop.effective_targets:+ return {}+ # Batched: ``module:`` targets expand to every file in the module.+ git_meta_by_path = await get_git_metadata_bulk(+ session, repository.id, list(pop.effective_targets)+ )+ degrees_by_path = await get_node_degree_counts_bulk(+ session,+ repository.id,+ list(pop.effective_targets),+ edge_types=sorted(FILE_DEPENDENCY_EDGE_TYPES),+ )+ return {+ path: asdict(file_signals(git_meta_by_path.get(path), degrees_by_path.get(path)))+ for path in pop.effective_targets+ }+++async def _read_doc_drift(+ session: Any, repository: Any, pop: Population, req: HealthRequest+) -> tuple[list[Any], str | None]:+ """Documentation this repository's own tree no longer satisfies.++ Findings are filed against the document, so ``targets`` narrows by+ document path, matched exactly."""+ if "doc_drift" not in req.include_set:+ return [], None+ drift_rows: list[Any] = []+ drift_unavailable: str | None = None+ try:+ # The savepoint matters: on an index older than the drift table this+ # raises, and on Postgres a failed statement poisons the transaction.+ async with session.begin_nested():+ rows = await get_doc_drift_findings(session, repository.id)+ # Exclude config only, not ``in_scope_rows``: the production scope+ # keeps files with a health metric, and no document has one.+ drift_rows = filter_rows_by_attr(rows, "file_path", pop.exclude_spec)+ except (SQLAlchemyError, OSError, LookupError):+ # Unavailable, not empty: an empty list would read as clean.+ drift_unavailable = UNAVAILABLE_NO_TABLE+ if pop.scoped:+ drift_rows = [r for r in drift_rows if r.file_path in pop.effective_targets]+ return drift_rows, drift_unavailable+++async def _read_churn_points(+ session: Any, repository: Any, pop: Population, req: HealthRequest+) -> list[dict[str, Any]]:+ """Churn x complexity quadrant for the whole repo (dashboard mode). One+ git-metadata query joined against the already-loaded metrics."""+ if "churn_complexity" not in req.include_set or pop.scoped:+ return []+ git_meta_by_path = await get_all_git_metadata(session, repository.id)+ return [asdict(p) for p in churn_complexity_points(pop.all_metrics, git_meta_by_path)]+++async def _read_snapshots(+ session: Any, repository: Any, pop: Population, req: HealthRequest+) -> list[Any]:+ """The snapshot window for the repo-level trend block and/or the+ per-file trajectory attached in targeted mode."""+ if "trend" not in req.include_set and not (pop.scoped and req.wants("trends")):+ return []+ # Same scope as the KPIs, so both describe the same files.+ return project_scope(+ await list_health_snapshots(session, repository.id, limit=20), pop.reported_scope+ )+++def _rank_leverage_and_leads(+ pop: Population,+ metric_rows: list[HealthFileMetric],+ findings: FindingSets,+ req: HealthRequest,+) -> tuple[list[HealthFileMetric], dict[str, dict[str, Any]]]:+ """Dominant-cause lead per file, and the leverage ranking it is printed beside.++ Targeted mode reduces the whole (small) scoped set. Dashboard mode reduces+ only the rows of files it prints: identical output at a fraction of the cost.++ Computed inside the session because the directive's plan lookup needs+ ``by_leverage``.+ """+ if pop.scoped:+ return [], _leads_by_file(findings.lead_rows)+ # Ranked by NLOC-weighted deficit, not raw score: a big mid-band file+ # moves the average more than a tiny at-risk one.+ by_leverage = sorted(+ (m for m in pop.all_metrics if m.score < TARGET_SCORE),+ key=lambda m: max(TARGET_SCORE - m.score, 0.0) * max(m.nloc, 1),+ reverse=True,+ )+ printed = {m.file_path for m in metric_rows[: req.limit]}+ printed |= {m.file_path for m in by_leverage[: req.limit]}+ # The directive's candidates, unconditionally: its leads must not depend+ # on ``limit``, or ``limit=0`` would make it assert wrong claims.+ printed |= {m.file_path for m in by_leverage[:_DIRECTIVE_CANDIDATES]}+ return by_leverage, _leads_by_file([r for r in findings.lead_rows if r.file_path in printed])+++async def _read_directive_plans(+ session: Any,+ repository: Any,+ pop: Population,+ req: HealthRequest,+ by_leverage: list[HealthFileMetric],+) -> tuple[dict[str, set[str]], dict[str, int]]:+ """Which biomarkers the stored plans for the directive's candidates actually address.++ The directive points at ``include=['refactoring']`` for the fix, but some+ biomarkers have no plan kind, so it must know whether a plan addresses the+ cause it names. Read for the directive's candidates only, two columns, and+ only when the directive survives the projection. ``status == "open"``+ mirrors ``get_refactoring_suggestions``; candidates are already+ exclude-filtered.+ """+ plan_biomarkers_by_path: dict[str, set[str]] = {}+ plan_count_by_path: dict[str, int] = {}+ if pop.scoped or not req.wants("directive") or not by_leverage:+ return plan_biomarkers_by_path, plan_count_by_path+ directive_paths = [m.file_path for m in by_leverage[:_DIRECTIVE_CANDIDATES]]+ 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():+ # Counted apart from attribution: ``split_file`` and ``break_cycle``+ # plans store an empty ``source_biomarker``.+ plan_count_by_path[path] = plan_count_by_path.get(path, 0) + 1+ if source:+ plan_biomarkers_by_path.setdefault(path, set()).add(source)+ return plan_biomarkers_by_path, plan_count_by_pathdiff --git a/packages/server/src/repowise/server/mcp_server/tool_health/paging.py b/packages/server/src/repowise/server/mcp_server/tool_health/paging.pynew file mode 100644index 000000000..cae7a6e54--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/tool_health/paging.py@@ -0,0 +1,175 @@+"""Collection accounting for get_health: every emitted list states its total.++``Pager`` bounds each list and remembers how to fetch what it cut: a paged+collection gets a ``recovery`` call, anything else keeps its exact tail in the+shared omission store.+"""++from __future__ import annotations++from typing import Any++from repowise.core.analysis.health.refactoring.recommendations import Recommendation+from repowise.server.mcp_server._budget import OmissionCollector+from repowise.server.mcp_server.tool_health.request import HealthRequest+from repowise.server.mcp_server.tool_health.serialize import _serialize_refactoring++_PAGED_COLLECTIONS = frozenset(+ {+ "metrics",+ "findings",+ "trends",+ "worst_files",+ "high_leverage_files",+ "top_findings",+ "test_findings",+ "modules",+ "churn_complexity",+ "coverage.files",+ "doc_drift.findings",+ "refactoring_plans",+ "refactoring_opportunities",+ "refactoring_evidence",+ "performance_opportunities",+ "performance_evidence",+ }+)++# The queues page six at a time whatever ``limit`` says; see the pillar caps.+_QUEUE_COLLECTIONS = frozenset(+ {"refactoring_plans", "refactoring_opportunities", "performance_opportunities"}+)+_QUEUE_PAGE = 6+++class Pager:+ """Bounds every emitted collection of one response and records the remainder."""++ def __init__(self, limit: int, cursor: int) -> None:+ self.limit = limit+ self.cursor = cursor+ # ``label -> (next_cursor, next_limit, remaining)`` for paged collections.+ self.recoveries: dict[str, tuple[int, int, int]] = {}+ # ``label -> dropped rows`` for everything else.+ self.omissions: dict[str, list[Any]] = {}++ def bound(self, rows: list[Any], label: str, *, cap: int | None = None) -> list[Any]:+ """Bound one collection and retain its exact tail in shared omission storage."""+ row_cap = self.limit if cap is None else cap+ paged = label in _PAGED_COLLECTIONS+ start = self.cursor if paged else 0+ kept = rows[start : start + row_cap]+ if len(kept) < len(rows):+ if paged:+ self._note_recovery(rows, label, start, start + len(kept), row_cap)+ else:+ self.omissions[label] = rows[row_cap:]+ return kept++ def _note_recovery(+ self, rows: list[Any], label: str, start: int, tail_start: int, row_cap: int+ ) -> None:+ if tail_start < len(rows):+ next_limit = (+ min(row_cap or _QUEUE_PAGE, _QUEUE_PAGE)+ if label in _QUEUE_COLLECTIONS+ else min(len(rows) - tail_start, 50)+ )+ self.recoveries[label] = (tail_start, next_limit, len(rows) - tail_start)+ elif rows and start >= len(rows):+ # A cursor past the end restarts at the first page rather than+ # leaving the caller with nothing to call.+ self.recoveries[label] = (0, min(len(rows), max(row_cap, 1), 50), len(rows))++ def recovery_block(+ self, result: dict[str, Any], req: HealthRequest+ ) -> dict[str, dict[str, Any]] | None:+ """One follow-up call per paged collection that survived the projection."""+ recovery: dict[str, dict[str, Any]] = {}+ for label, (next_cursor, next_limit, remaining) in self.recoveries.items():+ root = label.split(".", 1)[0]+ if root not in result:+ continue+ recovery[label] = {+ "remaining": remaining,+ "call": (+ f"get_health(targets={req.raw_targets!r}, include={list(req.include or [])!r}, "+ f"repo={req.repo!r}, limit={next_limit}, only={[root]!r}, "+ f"refactoring_view='{req.refactoring_view}', cursor={next_cursor})"+ ),+ }+ return recovery or None++ def report_omissions(+ self, result: dict[str, Any], collector: OmissionCollector, reference_repository: str+ ) -> None:+ """Hand every dropped tail whose block survived to the omission store."""+ for label, dropped in self.omissions.items():+ root = label.split(".", 1)[0]+ if root in result:+ collector.add(+ f"{label} beyond emitted cap ({len(dropped)} dropped)",+ [_omitted_row(row, reference_repository) for row in dropped],+ )+++def _omitted_row(row: Any, reference_repository: str) -> Any:+ if isinstance(row, Recommendation):+ return _serialize_refactoring(row, reference_repository)+ return row.as_dict() if hasattr(row, "as_dict") else row+++def _stamp_collection_totals(+ result: dict[str, Any], totals: dict[str, int | None], limit: int+) -> None:+ """Stamp each top-level collection with the population it was cut from."""+ for key, total in totals.items():+ if total is None:+ continue+ cap_reason = (+ "collection_cap"+ if key in {"refactoring_plans", "performance_opportunities"}+ and limit > _QUEUE_PAGE+ and len(result.get(key, [])) == _QUEUE_PAGE+ else "limit"+ )+ _stamp_collection(result, key, total=total, reason=cap_reason)+++def _stamp_collection(+ result: dict[str, Any],+ key: str,+ *,+ total: int | None = None,+ reason: str = "limit",+) -> None:+ """Attach complete-population accounting to one emitted collection."""+ rows = result.get(key)+ if not isinstance(rows, list):+ return+ eligible = len(rows) if total is None else total+ emitted = len(rows)+ result[f"{key}_total"] = eligible+ result[f"{key}_emitted"] = emitted+ if emitted < eligible:+ result[f"{key}_reduced_reason"] = reason+++def _stamp_nested_collections(value: Any) -> None:+ """Give every nested list an emitted count and an honest eligible total."""+ if isinstance(value, list):+ for item in value:+ _stamp_nested_collections(item)+ return+ if not isinstance(value, dict):+ return+ for key, child in list(value.items()):+ if isinstance(child, list):+ total_key = f"{key}_total"+ emitted_key = f"{key}_emitted"+ total = int(value.get(total_key, len(child)) or 0)+ value.setdefault(total_key, total)+ value.setdefault(emitted_key, len(child))+ if len(child) < total:+ value.setdefault(f"{key}_reduced_reason", "limit")+ _stamp_nested_collections(child)diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/pillars.py b/packages/server/src/repowise/server/mcp_server/tool_health/pillars.pynew file mode 100644index 000000000..e8a0a56fd--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/tool_health/pillars.py@@ -0,0 +1,321 @@+"""Performance and refactoring pillar blocks for get_health: the queue, rollup and lead."""++from __future__ import annotations++from dataclasses import dataclass, field+from typing import Any++from repowise.core.analysis.health.perf.opportunity_rank import NON_LEADING_MARKERS+from repowise.core.analysis.health.refactoring.recommendations import Recommendation+from repowise.server.mcp_server.tool_health.paging import Pager+from repowise.server.mcp_server.tool_health.request import HealthRequest+from repowise.server.mcp_server.tool_health.serialize import _serialize_refactoring+from repowise.server.services.performance_health import (+ PerformanceHealthService,+ PerformancePage,+ parse_query,+)+from repowise.server.services.refactoring_health import RefactoringHealthService+from repowise.server.services.refactoring_health import parse_query as parse_refactoring_query++# The opportunity id space is shared with the performance pillar's, and told+# apart by prefix alone, so ``opportunity_id`` stays one selector.+_REFACTORING_OPPORTUNITY_PREFIX = "refop"++_REFACTORING_COLLECTION_CAP = 6+"""Opportunities per response, independent of ``limit``. ``cursor`` pages it."""++_REFACTORING_STEP_CAP = 3+"""Steps per row in the queue. The detail call pages the rest."""++_REFACTORING_STEP_PAGE_CAP = 20+"""Ceiling on one page of a detail call's ordered steps."""++_REFACTORING_EVIDENCE_CAP = 3+"""Evidence rows beside a detail response. ``only=['refactoring_evidence']`` pages more."""++_REFACTORING_EVIDENCE_PAGE_CAP = 20+"""Ceiling on one evidence page."""++_PERFORMANCE_COLLECTION_CAP = 6+"""Opportunities per response, independent of ``limit``. ``cursor`` pages it."""++_PERFORMANCE_EVIDENCE_CAP = 3+"""Evidence rows per opportunity in the collection. The detail call pages more."""++_PERFORMANCE_EVIDENCE_PAGE_CAP = 20+"""Ceiling on one evidence page. ``limit`` still means what it says below it,+including ``limit=0`` for the totals and no rows."""+++@dataclass(frozen=True, slots=True)+class _PerformanceBlocks:+ """Everything the performance pillar contributes to one response."""++ page: PerformancePage | None = None+ summary: dict[str, Any] | None = None+ directive: dict[str, Any] | None = None+ ignored: dict[str, str] = field(default_factory=dict)+++async def _performance_blocks(+ service: PerformanceHealthService,+ *,+ wants: Any,+ included: bool,+ file_paths: tuple[str, ...] | None,+ scoped: bool,+ limit: int,+ cursor: int,+ view: str | None,+ context: str | None,+ boundary: str | None,+ confidence: str | None,+ actionability: str | None,+ sort: str | None,+) -> _PerformanceBlocks:+ """Read the materialized queue, its rollup, and the dashboard lead.++ Each block is gated on surviving the projection, so a caller that asked for+ one of the three does not pay for the other two.+ """+ page = None+ query = None+ ignored: dict[str, str] = {}+ if included:+ # The lede quotes only the first row, so projected down to it, read one.+ emits_queue = wants("performance_opportunities")+ query, ignored = parse_query(+ context=context,+ boundary=boundary,+ confidence=confidence,+ actionability=actionability,+ view=view,+ sort=sort,+ file_paths=file_paths,+ limit=min(max(limit, 0), _PERFORMANCE_COLLECTION_CAP) if emits_queue else 1,+ offset=cursor if emits_queue else 0,+ )+ page = await service.page(+ query,+ evidence_per_item=_PERFORMANCE_EVIDENCE_CAP if emits_queue else 0,+ # Facets are rendered only by the summary block.+ with_facets=wants("performance_summary"),+ )+ return _PerformanceBlocks(+ page=page,+ summary=(+ # Same context as the queue, so the two totals cannot contradict.+ await service.summary(query.contexts if query else None)+ if included and wants("performance_summary")+ else None+ ),+ # Dashboard lead: one primary-key read, independent of repo size.+ directive=(+ await service.directive() if not scoped and wants("performance_directive") else None+ ),+ ignored=ignored,+ )+++@dataclass(frozen=True, slots=True)+class _RefactoringBlocks:+ """Everything the refactoring pillar contributes to one response."""++ page: Any = None+ summary: dict[str, Any] | None = None+ directive: dict[str, Any] | None = None+ ignored: dict[str, str] = field(default_factory=dict)+++async def _refactoring_blocks(+ service: RefactoringHealthService,+ *,+ wants: Any,+ included: bool,+ file_paths: tuple[str, ...] | None,+ scoped: bool,+ limit: int,+ cursor: int,+ view: str,+ lead_type: str | None = None,+ confidence: str | None = None,+ effort: str | None = None,+) -> _RefactoringBlocks:+ """Read the materialized queue, its rollup, and the dashboard lead.++ Each block is gated on surviving the projection, so a caller that asked for+ one of the three does not pay for the other two.+ """+ page = None+ ignored: dict[str, str] = {}+ # A scope that resolved to no file is not the dashboard: the rollup is read+ # by repository id and cannot honour a scope, so it is withheld.+ resolved_scope = not (scoped and not file_paths)+ rollup_wanted = included and wants("refactoring_summary") and resolved_scope+ if included:+ emits_queue = wants("refactoring_opportunities")+ query, ignored = parse_refactoring_query(+ view=view,+ lead_type=lead_type,+ confidence=confidence,+ effort=effort,+ file_paths=list(file_paths) if file_paths is not None else None,+ limit=min(max(limit, 0), _REFACTORING_COLLECTION_CAP) if emits_queue else 1,+ offset=cursor if emits_queue else 0,+ )+ page = await service.page(+ query,+ steps_per_item=_REFACTORING_STEP_CAP if emits_queue else 0,+ with_facets=rollup_wanted,+ )+ return _RefactoringBlocks(+ page=page,+ summary=await service.summary() if rollup_wanted else None,+ # Dashboard only: a targeted call is about the files the caller named.+ directive=(+ await service.directive()+ if not scoped and wants("refactoring_directive")+ else None+ ),+ ignored=ignored,+ )+++def _merge_ignored(result: dict[str, Any], ignored: dict[str, str]) -> None:+ if ignored:+ result["ignored_arguments"] = {**result.get("ignored_arguments", {}), **ignored}+++def _render_refactoring(+ result: dict[str, Any], refactoring: _RefactoringBlocks, req: HealthRequest, pager: Pager+) -> None:+ """The refactoring queue and its rollup, as read by ``_refactoring_blocks``."""+ page = refactoring.page+ if page is not None and req.wants("refactoring_opportunities"):+ result["refactoring_opportunities"] = page.items+ result["refactoring_opportunities_total"] = page.total+ result["refactoring_opportunities_emitted"] = len(page.items)+ if len(page.items) < page.total:+ result["refactoring_opportunities_reduced_reason"] = (+ "collection_cap" if req.limit > _REFACTORING_COLLECTION_CAP else "limit"+ )+ if page.next_offset is not None:+ pager.recoveries["refactoring_opportunities"] = (+ page.next_offset,+ _REFACTORING_COLLECTION_CAP,+ page.total - page.next_offset,+ )+ _merge_ignored(result, refactoring.ignored)++ if refactoring.summary is not None:+ result["refactoring_summary"] = {+ **refactoring.summary,+ "facets": page.facets if page else {},+ "view": req.refactoring_view,+ "next_call": (+ "get_health(include=['refactoring'], "+ "only=['refactoring_opportunities'], limit=6)"+ ),+ }+++def _render_performance(+ result: dict[str, Any], performance: _PerformanceBlocks, req: HealthRequest, pager: Pager+) -> None:+ """The performance queue and its rollup, as read by ``_performance_blocks``."""+ page = performance.page+ if page is not None and req.wants("performance_opportunities"):+ result["performance_opportunities"] = page.items+ result["performance_opportunities_total"] = page.total+ result["performance_opportunities_emitted"] = len(page.items)+ if page.next_offset is not None:+ pager.recoveries["performance_opportunities"] = (+ page.next_offset,+ _PERFORMANCE_COLLECTION_CAP,+ page.total - page.next_offset,+ )+ _merge_ignored(result, performance.ignored)++ if performance.summary is not None:+ result["performance_summary"] = {+ **performance.summary,+ "facets": page.facets if page else {},+ "next_call": (+ "get_health(include=['performance'], "+ "only=['performance_opportunities'], limit=6)"+ ),+ }+++_PERFORMANCE_LEAD_KEYS = (+ "opportunity_id",+ "intervention_symbol",+ "boundary_kind",+ "execution_context",+ "affected_call_sites_total",+ "rank_score",+)++_RECOMMENDATION_LEAD_KEYS = (+ "id",+ "refactoring_type",+ "file_path",+ "target_symbol",+ "benefit",+ "leverage",+ "cost",+ "risk",+ "rank_score",+)+++def _recommendation_lede(+ performance: _PerformanceBlocks,+ recommendations: list[Recommendation],+ reference_repository: str,+ req: HealthRequest,+) -> dict[str, Any]:+ """One performance opportunity beside one plan, when both pillars were asked for."""+ performance_lead = next(+ (+ item+ for item in (performance.page.items if performance.page else [])+ if item.get("biomarker_type") not in NON_LEADING_MARKERS+ ),+ None,+ )+ lead_payload = (+ _serialize_refactoring(recommendations[0], reference_repository)+ if recommendations+ else None+ )+ return {+ "performance_opportunities_total": (+ performance.page.total if performance.page else 0+ ),+ "refactoring_plans_total": len(recommendations),+ "performance_lead": (+ {key: performance_lead[key] for key in _PERFORMANCE_LEAD_KEYS}+ if performance_lead+ else None+ ),+ "recommendation_lead": (+ {key: lead_payload[key] for key in _RECOMMENDATION_LEAD_KEYS}+ if lead_payload+ else None+ ),+ # The lead's plan, from the one place that decides plan linkage.+ "performance_plan_id": (+ performance_lead["plan_reference"] if performance_lead else None+ ),+ "performance_plan_reason": (+ performance_lead["plan_reason"] if performance_lead else None+ ),+ "next_call": (+ f"get_health(targets={req.raw_targets!r}, repo={req.repo!r}, "+ "include=['performance','refactoring'], limit=3, "+ "only=['performance_opportunities','refactoring_plans'], "+ f"refactoring_view='{req.refactoring_view}')"+ ),+ }diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/plans.py b/packages/server/src/repowise/server/mcp_server/tool_health/plans.pynew file mode 100644index 000000000..c9f604670--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/tool_health/plans.py@@ -0,0 +1,212 @@+"""Refactoring-plan projection for get_health: validation profiles and plan status."""++from __future__ import annotations++import hashlib+import json+from typing import TYPE_CHECKING, Any++from repowise.server.mcp_server._budget import (+ OmissionCollector,+ register_post_enforce,+ register_post_shed,+)+from repowise.server.mcp_server.tool_health.paging import Pager, _stamp_collection+from repowise.server.mcp_server.tool_health.request import HealthRequest+from repowise.server.mcp_server.tool_health.serialize import _serialize_refactoring++if TYPE_CHECKING:+ from repowise.server.mcp_server.tool_health.loading import HealthData+++def _render_plans(+ result: dict[str, Any], data: HealthData, req: HealthRequest, pager: Pager+) -> None:+ """The plan list, its shared validation profiles, and why it may be empty.++ Canonical is the shared REST/MCP/CLI order. File diversity remains+ available only through the explicitly named ``file_spread`` view.+ """+ recommendations = data.refactoring_recommendations+ validation_profiles: dict[str, dict[str, Any]] = {}+ plan_payload = []+ for recommendation in pager.bound(+ recommendations, "refactoring_plans", cap=min(req.limit, 6)+ ):+ payload = _serialize_refactoring(recommendation, data.reference_repository)+ validation = payload.pop("validation", None)+ if validation:+ profile_id, profile = _validation_profile(validation)+ validation_profiles.setdefault(profile_id, profile)+ payload["validation_profile_id"] = profile_id+ plan_payload.append(payload)+ result["refactoring_plans"] = plan_payload+ if validation_profiles:+ result["validation_profiles"] = list(validation_profiles.values())+ _stamp_collection(+ result,+ "validation_profiles",+ total=len(validation_profiles),+ reason="profile_cap",+ )+ result["refactoring_plans_total"] = len(data.refactoring_rows)+ if req.wants("refactoring_plans"):+ scoped = data.pop.scoped+ result["refactoring_plans_status"] = _refactoring_plans_status(+ available_plans_total=len(recommendations),+ plans_emitted=len(plan_payload),+ scoped=scoped,+ has_eligible_metrics=bool(data.metric_rows if scoped else data.pop.all_metrics),+ finding=next(iter(data.findings.emitted), None),+ repo=req.repo,+ )+ # Prose suggestions for biomarkers without a structured plan ship once per+ # type as ``suggestion_legend``, not per finding: the text is keyed by type.+++def _validation_profile(validation: dict[str, Any]) -> tuple[str, dict[str, Any]]:+ """Deduplicate a plan's repeated tests, targets, and command material."""+ encoded = json.dumps(validation, sort_keys=True, separators=(",", ":"), default=str)+ profile_id = "validation_" + hashlib.sha256(encoded.encode()).hexdigest()[:16]+ tests = list(validation.get("tests") or [])+ targets = list(validation.get("targets") or [])+ profile = {+ key: value+ for key, value in validation.items()+ if key not in {"tests", "targets", "commands", "truncated"}+ }+ profile.update(+ {+ "id": profile_id,+ "tests": tests,+ "tests_total": int(validation.get("total") or len(tests)),+ "tests_emitted": len(tests),+ "targets": targets,+ "commands": list(validation.get("commands") or []),+ "commands_total": len(validation.get("commands") or []),+ "commands_emitted": len(validation.get("commands") or []),+ }+ )+ if profile["tests_emitted"] < profile["tests_total"]:+ profile["tests_reduced_reason"] = "analysis_source_cap"+ return profile_id, profile+++def _finding_next_action(finding: Any, repo: str | None) -> dict[str, Any]:+ """Return one concrete source call for a finding without a stored plan."""+ path = str(getattr(finding, "file_path", ""))+ line_start = getattr(finding, "line_start", None)+ line_end = getattr(finding, "line_end", None)+ if path and line_start and line_end:+ arguments: dict[str, Any] = {"symbol_id": f"{path}:{line_start}-{line_end}"}+ if repo:+ arguments["repo"] = repo+ return {"tool": "get_symbol", "arguments": arguments}+ arguments = {"targets": [path], "include": ["skeleton"]}+ if repo:+ arguments["repo"] = repo+ return {"tool": "get_context", "arguments": arguments}+++def _refactoring_plans_status(+ *,+ available_plans_total: int,+ plans_emitted: int,+ scoped: bool,+ has_eligible_metrics: bool,+ finding: Any | None,+ repo: str | None,+) -> dict[str, Any]:+ """Explain an explicitly requested plan projection deterministically."""+ if plans_emitted:+ return {"state": "available", "reason": None}+ if available_plans_total:+ return {+ "state": "available_not_emitted",+ "reason": "request_window_empty",+ "message": "Plans exist but the requested limit/cursor window emitted none.",+ }+ if scoped and not has_eligible_metrics:+ return {+ "state": "unavailable",+ "reason": "no_eligible_targets",+ "message": "No requested target resolved to an eligible stored health row.",+ }+ if not has_eligible_metrics:+ return {+ "state": "unavailable",+ "reason": "analysis_unavailable",+ "message": "No stored health analysis is available for this population.",+ "next_action": {+ "command": "repowise update",+ "reason": "run health analysis before interpreting scores or plans",+ },+ }+ if finding is None:+ return {+ "state": "empty",+ "reason": "no_applicable_findings",+ "message": "The eligible population has no applicable open findings.",+ }+ return {+ "state": "indeterminate",+ "reason": "plan_analysis_indeterminate",+ "message": "Findings exist, but stored plan evidence is absent.",+ "possible_causes": [+ "no_supported_structured_transformation",+ "refactoring_detector_disabled_or_failed",+ ],+ "next_action": _finding_next_action(finding, repo),+ }+++def _prune_orphaned_validation_profiles(+ result: dict[str, Any], collector: OmissionCollector+) -> None:+ """Drop profiles whose plan the response budget removed.++ A profile left behind by its shed plan is an id that resolves to nothing.+ """+ plans = result.get("refactoring_plans")+ profiles = result.get("validation_profiles")+ if not isinstance(plans, list) or not isinstance(profiles, list):+ return+ referenced = {+ plan.get("validation_profile_id")+ for plan in plans+ if isinstance(plan, dict) and plan.get("validation_profile_id")+ }+ kept = [+ profile+ for profile in profiles+ if isinstance(profile, dict) and profile.get("id") in referenced+ ]+ dropped = [profile for profile in profiles if profile not in kept]+ if not dropped:+ return+ collector.add("validation_profiles no longer referenced after response budgeting", dropped)+ result["validation_profiles"] = kept+ result["validation_profiles_emitted"] = len(kept)+ result["validation_profiles_reduced_reason"] = "response_budget"+ result["truncated"] = True+++def _reconcile_plan_status(result: dict[str, Any]) -> None:+ """Keep plan availability honest after the final budget mutates collections."""+ status = result.get("refactoring_plans_status")+ plans = result.get("refactoring_plans")+ if not isinstance(status, dict) or status.get("state") != "available":+ return+ if plans is not None and (not isinstance(plans, list) or plans):+ return+ if not result.get("refactoring_plans_total", 0):+ return+ status.update(+ state="available_not_emitted",+ reason="response_budget",+ message="Plans exist but were removed by the final response budget.",+ )+++register_post_shed("get_health", _prune_orphaned_validation_profiles)+register_post_enforce("get_health", _reconcile_plan_status)diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/population.py b/packages/server/src/repowise/server/mcp_server/tool_health/population.pynew file mode 100644index 000000000..ed048f26d--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/tool_health/population.py@@ -0,0 +1,114 @@+"""The file population one get_health call describes, and the targets within it."""++from __future__ import annotations++from dataclasses import dataclass+from typing import Any++from sqlalchemy import select++from repowise.core.analysis.health.counts import parse_counts+from repowise.core.analysis.health.counts import project as project_counts+from repowise.core.analysis.health.models import split_by_origin+from repowise.core.analysis.health.scope import parse_scope+from repowise.core.persistence.models import HealthFileMetric+from repowise.server.mcp_server._helpers import _get_exclude_spec, filter_rows_by_attr+from repowise.server.mcp_server.tool_health.request import HealthRequest+from repowise.server.mcp_server.tool_health.targets import _expand_module_targets+++@dataclass+class Population:+ """Metric rows after exclude config, ``scope`` and ``counts``, plus targets."""++ all_metrics: list[HealthFileMetric]+ exclude_spec: Any+ excluded_paths: set[str]+ reported_scope: str+ scope_paths: set[str] | None+ reported_counts: str+ unscored_files: int+ unscored_paths: set[str]+ file_targets: list[str]+ matched_modules: set[str]+ scoped: bool+ effective_targets: list[str]++ @property+ def code_shape(self) -> bool:+ return self.reported_counts == "code_shape"++ @property+ def nothing_resolved(self) -> bool:+ return self.scoped and not self.effective_targets++ @property+ def target_paths(self) -> tuple[str, ...] | None:+ """The targets as a read filter; ``None`` means the whole repository."""+ return tuple(self.effective_targets) if self.scoped else None++ def in_scope_rows(self, rows: list, attr: str = "file_path") -> list:+ rows = filter_rows_by_attr(rows, attr, self.exclude_spec)+ if self.scope_paths is None:+ return rows+ return [r for r in rows if getattr(r, attr, None) in self.scope_paths]++ def in_counts_findings(self, rows: list) -> list:+ """A history finding cannot explain a score its half was taken out+ of, so it is not part of the code-shape reading."""+ return split_by_origin(rows)[0] if self.code_shape else rows+++async def load_population(+ session: Any, repository: Any, repo_path: Any, req: HealthRequest+) -> Population:+ """Read the metric rows and narrow them the way every block will see them."""+ all_metrics_q = select(HealthFileMetric).where(+ HealthFileMetric.repository_id == repository.id+ )+ exclude_spec = _get_exclude_spec(repo_path)+ indexed_rows = list((await session.execute(all_metrics_q)).scalars().all())+ all_metrics = filter_rows_by_attr(indexed_rows, "file_path", exclude_spec)+ # Lets an unresolved target report "excluded" rather than "no_such_path".+ # Computed before ``scope`` narrows, or test files would count as excluded.+ excluded_paths = {m.file_path for m in indexed_rows} - {m.file_path for m in all_metrics}++ # The production scope drops whole files from every block at once, like+ # the exclude config, so every block agrees on the file set.+ reported_scope = parse_scope(req.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}++ # Composes with the scope: a re-read off the stored structure/history+ # split, not a rescore. Findings narrow by origin, not by path, so a row+ # it cannot read lands in ``unscored_files`` with its findings intact.+ reported_counts = parse_counts(req.counts)+ unscored_files = 0+ unscored_paths: set[str] = set()+ if reported_counts == "code_shape":+ before = {m.file_path for m in all_metrics}+ all_metrics, unscored_files = project_counts(req.counts, all_metrics)+ unscored_paths = before - {m.file_path for m in all_metrics}++ file_targets, matched_modules = _expand_module_targets(+ all_metrics, req.module_targets, req.file_targets+ )+ # Keyed off the raw targets, not the resolved ones: a target that resolves+ # to nothing must not fall through to repo-wide numbers.+ scoped = bool(req.raw_targets)+ return Population(+ all_metrics=all_metrics,+ exclude_spec=exclude_spec,+ excluded_paths=excluded_paths,+ reported_scope=reported_scope,+ scope_paths=scope_paths,+ reported_counts=reported_counts,+ unscored_files=unscored_files,+ unscored_paths=unscored_paths,+ file_targets=file_targets,+ matched_modules=matched_modules,+ scoped=scoped,+ effective_targets=file_targets if scoped else [],+ )diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/projection.py b/packages/server/src/repowise/server/mcp_server/tool_health/projection.pynew file mode 100644index 000000000..b2cb257e4--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/tool_health/projection.py@@ -0,0 +1,119 @@+"""The last shaping passes over a get_health response, after every block is built."""++from __future__ import annotations++from typing import Any++from repowise.core.analysis.health.counts import DEFAULT_COUNTS+from repowise.core.analysis.health.scope import DEFAULT_SCOPE+from repowise.server.mcp_server.tool_health.paging import _stamp_collection+from repowise.server.mcp_server.tool_health.request import HealthRequest++# Orientation and caller-error reports survive any projection: without+# ``unresolved``, a typo'd target would read as an empty, healthy result.+_ALWAYS_KEPT = frozenset(+ {+ "mode",+ "targets",+ "targets_total",+ "targets_emitted",+ "unresolved",+ "unresolved_total",+ "unresolved_emitted",+ "known_modules",+ "known_modules_total",+ "known_modules_emitted",+ "unknown_include_keys",+ "unknown_include_keys_total",+ "unknown_include_keys_emitted",+ # A rejected filter value is a caller-error report too.+ "ignored_arguments",+ "recovery",+ }+)++_PLAN_COMPANIONS = frozenset(+ {+ "refactoring_plans_status",+ "validation_profiles",+ "validation_profiles_total",+ "validation_profiles_emitted",+ "validation_profiles_reduced_reason",+ }+)+++def _name_rejected_controls(+ result: dict[str, Any], req: HealthRequest, reported_scope: str, reported_counts: str+) -> None:+ """A misspelled control falls back to the default, answering a different+ question under the name the caller asked for. The routes and the CLI+ reject outright; MCP cannot, so it names the value it dropped."""+ rejected = {+ name: raw+ for name, raw, resolved in (+ ("scope", req.scope, reported_scope),+ ("counts", req.counts, reported_counts),+ )+ if raw is not None and raw != resolved+ }+ if rejected:+ result["ignored_arguments"] = {**result.get("ignored_arguments", {}), **rejected}+++def _name_uncounted_blocks(result: dict[str, Any], reported_counts: str) -> None:+ """Snapshots and the two ranked queues have no stored split to re-read, so+ they stay calibrated. Named, or a projected headline reads as if+ everything beside it were projected too."""+ if reported_counts != "code_shape":+ return+ unprojected = [+ key+ for key in ("trend", "trends", "refactoring_opportunities", "performance_opportunities")+ if key in result+ ]+ if unprojected:+ result["counts_not_applied_to"] = unprojected+++def _project(+ result: dict[str, Any], req: HealthRequest, reported_scope: str, reported_counts: str+) -> dict[str, Any]:+ """Keep only what ``only`` names, plus what a caller needs to orient in it.++ ``include`` only adds blocks; ``only`` is the subtract half. Applied last+ so it can drop anything above, while ``mode`` and ``_meta`` always survive.+ """+ if not req.only:+ return result+ # Each kept list keeps its ``*_total`` siblings, so truncation stays visible.+ keep = (+ set(req.only_list)+ | _ALWAYS_KEPT+ | {+ suffix+ for k in req.only_list+ for suffix in (+ f"{k}_total",+ f"{k}_emitted",+ f"{k}_reduced_reason",+ )+ }+ )+ # Which reading the numbers are on, only when it is not the default.+ if reported_scope != DEFAULT_SCOPE:+ keep |= {"scope"}+ if reported_counts != DEFAULT_COUNTS:+ keep |= {"counts", "unscored_files", "counts_not_applied_to"}+ if "refactoring_plans" in req.only_set:+ keep |= _PLAN_COMPANIONS+ # Name absent keys, so a misspelling is not mistaken for missing data.+ # Reported by what the caller passed, so a resolved alias is not "unknown".+ unknown = sorted(+ raw for raw, resolved in zip(req.only, req.only_list, strict=True) if resolved not in result+ )+ result = {k: v for k, v in result.items() if k in keep}+ if unknown:+ result["unknown_only_keys"] = unknown+ _stamp_collection(result, "unknown_only_keys", total=len(unknown))+ return resultdiff --git a/packages/server/src/repowise/server/mcp_server/tool_health/request.py b/packages/server/src/repowise/server/mcp_server/tool_health/request.pynew file mode 100644index 000000000..dd3983a1c--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/tool_health/request.py@@ -0,0 +1,169 @@+"""What one get_health call asked for, normalized once before any read."""++from __future__ import annotations++from dataclasses import dataclass, field++from repowise.core.analysis.health.scoring import ALL_DIMENSIONS+from repowise.server.services.refactoring_health import CANONICAL_VIEWS as _REFACTORING_VIEWS+from repowise.server.services.refactoring_health import DEFAULT_VIEW as _REFACTORING_VIEW_DEFAULT++# ``include`` names that land under a different response key, so ``only`` can+# use the same name. ``signals`` has no top-level key (it merges into+# ``metrics[].signals``), so it is deliberately absent.+_ONLY_ALIASES = {+ "biomarkers": "findings",+ "accuracy": "defect_accuracy",+ "refactoring": "refactoring_plans",+}++_RANKED_DIMENSIONS_DEFAULT = {"defect", "maintainability"}+"""Dimensions the impact-ranked findings list carries when none is asked for."""++_KNOWN_INCLUDES = frozenset(+ {+ "biomarkers",+ "refactoring",+ "trend",+ "coverage",+ "accuracy",+ "signals",+ "churn_complexity",+ "doc_drift",+ "performance",+ "defect",+ "maintainability",+ "advisory",+ }+)+++@dataclass+class HealthRequest:+ """The call's arguments, clamped and resolved, plus what they imply.++ Built from the raw tool arguments; ``__post_init__`` derives the rest, so+ every block downstream reads one normalized value instead of re-deriving it.+ """++ targets: list[str] | None+ include: list[str] | None+ only: list[str] | None+ repo: str | None+ limit: int+ cursor: int+ refactoring_view: str+ refactoring_type: str | None+ refactoring_confidence: str | None+ refactoring_effort: str | None+ performance_view: str | None+ performance_context: str | None+ performance_boundary: str | None+ performance_confidence: str | None+ performance_actionability: str | None+ performance_sort: str | None+ scope: str+ counts: str+ include_set: set[str] = field(init=False)+ unknown_include_keys: list[str] = field(init=False)+ only_list: list[str] = field(init=False)+ only_set: set[str] = field(init=False)+ dimension_filter: set[str] = field(init=False)+ ranked_dimensions: set[str] = field(init=False)+ raw_targets: list[str] = field(init=False)+ module_targets: list[str] = field(init=False)+ file_targets: list[str] = field(init=False)++ def __post_init__(self) -> None:+ # ``0`` means totals and no rows, as on the REST coverage route.+ self.limit = max(self.limit, 0)+ self.cursor = max(self.cursor, 0)+ if self.refactoring_view not in _REFACTORING_VIEWS:+ self.refactoring_view = _REFACTORING_VIEW_DEFAULT+ self.include_set = set(self.include or [])+ self.unknown_include_keys = sorted(self.include_set - _KNOWN_INCLUDES)+ self.only_list = [_ONLY_ALIASES.get(k, k) for k in (self.only or [])]+ self.only_set = set(self.only_list)+ # Resolved before the reads, so the filter decides which rows are+ # eligible for the impact cap rather than filtering an already-capped list.+ self.dimension_filter = self.include_set & set(ALL_DIMENSIONS)+ # Performance findings carry zero impact, so an impact-ranked list+ # leaves them out unless asked for; the performance blocks rank them.+ self.ranked_dimensions = self.dimension_filter or _RANKED_DIMENSIONS_DEFAULT+ # ``module:foo`` targets expand later into the module's files.+ self.raw_targets = list(self.targets or [])+ self.module_targets = [+ t.split(":", 1)[1] for t in self.raw_targets if t.startswith("module:")+ ]+ # Stored paths are POSIX-separated; accept Windows separators.+ self.file_targets = [+ t.replace("\\", "/") for t in self.raw_targets if not t.startswith("module:")+ ]++ def wants(self, block: str) -> bool:+ """True when ``block`` survives the ``only`` projection.++ Consulted before expensive optional work, so the projection gates the+ work as well as the payload.+ """+ return not self.only_set or block in self.only_set++ @property+ def wants_findings(self) -> bool:+ return self.wants("findings") or self.wants("top_findings")++ @property+ def wants_test_findings(self) -> bool:+ return self.wants("test_findings")++ @property+ def wants_performance_opportunities(self) -> bool:+ return (+ self.wants("performance_opportunities")+ or self.wants("recommendation_lede")+ or self.wants("performance_summary")+ )++ @property+ def wants_refactoring_opportunities(self) -> bool:+ return (+ self.wants("refactoring_opportunities")+ or self.wants("recommendation_lede")+ or self.wants("refactoring_summary")+ )++ @property+ def needs_test_paths(self) -> bool:+ """Everything downstream of the test/production split, in one place.++ Keep this list exhaustive. The read it gates scans graph nodes, but a+ missing entry is worse: the split collapses for that projection, so a+ projection changes what a surviving key holds.+ """+ return (+ self.wants_findings+ or self.wants_test_findings+ or self.wants("worst_files")+ or self.wants("high_leverage_files")+ or self.wants("metrics")+ or ("refactoring" in self.include_set and self.wants("suggestion_legend"))+ )++ @property+ def plans_requested(self) -> bool:+ """Structured refactoring plans (Extract Class, ...), loaded only when asked for.++ ``include=["refactoring"]`` leads with composed opportunities, and+ emitting plans too would ship the same work twice.+ """+ return "refactoring" in self.include_set and (+ "refactoring_plans" in self.only_set+ # The cross-pillar lede quotes one plan.+ or self.wants_lede+ )++ @property+ def wants_lede(self) -> bool:+ return {"performance", "refactoring"} <= self.include_set and self.wants(+ "recommendation_lede"+ )diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/serialize.py b/packages/server/src/repowise/server/mcp_server/tool_health/serialize.pynew file mode 100644index 000000000..8e543cff0--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/tool_health/serialize.py@@ -0,0 +1,183 @@+"""Row serializers for get_health, with the public ids and perf rank they carry."""++from __future__ import annotations++import json+from typing import Any++from repowise.core.analysis.health.finding_identity import finding_public_id+from repowise.core.analysis.health.grading import TARGET_SCORE+from repowise.core.analysis.health.perf.opportunity_rank import observation_rank+from repowise.core.analysis.health.refactoring.recommendations import (+ Recommendation,+ build_recommendations,+)+from repowise.core.persistence.models import (+ HealthFileMetric,+ HealthFinding,+)+from repowise.server.mcp_server._references import (+ path_identity,+ refactoring_plan_id,+ stable_entity_id,+)+++def _perf_rank(biomarker_type: str | None, details: Any) -> int:+ """Order-of-magnitude ordering key for one ``performance`` finding.++ Performance findings all carry ``health_impact: 0``, so they need their own+ key. The weights live with the opportunity ranking, so a finding and its+ opportunity cannot disagree. Never blended into ``score``.+ """+ if not isinstance(details, dict):+ details = {}+ return observation_rank(+ biomarker_type, details.get("boundary_kind"), bool(details.get("cross_function"))+ )+++def _rank_emitted(rows: list[Any]) -> list[Any]:+ """Break the ``health_impact`` ties that the performance dimension is made of.++ Re-sorts only within each impact tier, so the defect ordering is untouched.+ ``file_path`` is the final key, so the order is total and reproducible.+ Rows read without ``details_json`` rank on the marker alone.+ """+ if not rows:+ return rows++ def key(r: Any) -> tuple[float, int, str]:+ impact = float(getattr(r, "health_impact", 0.0) or 0.0)+ dimension = getattr(r, "dimension", None) or "defect"+ if dimension != "performance":+ return (-impact, 0, getattr(r, "file_path", "") or "")+ raw = getattr(r, "details_json", None)+ try:+ details = json.loads(raw) if raw else {}+ except Exception:+ details = {}+ return (+ -impact,+ -_perf_rank(getattr(r, "biomarker_type", None), details),+ getattr(r, "file_path", "") or "",+ )++ return sorted(rows, key=key)+++def _health_finding_id(f: Any, repository: str) -> str:+ """The finding's public id: the stored one, else the same kernel recomputed.++ Storage row ids change on every analysis, so this is the id evidence+ carries and ``finding_id`` resolves.+ """+ stored = getattr(f, "public_id", None)+ return stored if isinstance(stored, str) and stored else finding_public_id(f)+++def _legacy_health_finding_id(f: Any, repository: str) -> str:+ """The pre-column id form, still accepted so a quoted one keeps resolving."""+ try:+ details = json.loads(f.details_json) if f.details_json else {}+ except (TypeError, json.JSONDecodeError):+ details = str(f.details_json or "")+ return stable_entity_id(+ "finding",+ repository,+ {+ "family": "health",+ "path": path_identity(f.file_path),+ "kind": f.biomarker_type,+ "symbol": f.function_name or "",+ "line_start": f.line_start,+ "line_end": f.line_end,+ "reason": f.reason or "",+ "details": details,+ },+ )+++def _serialize_finding(f: HealthFinding, repository: str = "default") -> dict[str, Any]:+ try:+ details = json.loads(f.details_json) if f.details_json else {}+ except Exception:+ details = {}+ dimension = getattr(f, "dimension", None) or "defect"+ rank = (+ {"perf_rank": _perf_rank(f.biomarker_type, details)} if dimension == "performance" else {}+ )+ return {+ "id": _health_finding_id(f, repository),+ "repository": repository,+ "biomarker_type": f.biomarker_type,+ "severity": f.severity,+ "file_path": f.file_path,+ # A file-level finding has no symbol or span: absent rather than null.+ **({"function_name": f.function_name} if f.function_name else {}),+ **({"line_start": f.line_start} if f.line_start is not None else {}),+ **({"line_end": f.line_end} if f.line_end is not None else {}),+ "health_impact": round(f.health_impact, 3),+ "reason": f.reason,+ "details": details,+ "status": f.status,+ "dimension": dimension,+ # Performance rows only: a zero elsewhere would read as measured.+ **rank,+ }+++def _refactoring_plan_id(r: Any, repository: str) -> str:+ """Unwrap a hydrated recommendation, then defer to the identity owner."""+ return refactoring_plan_id(r.suggestion if isinstance(r, Recommendation) else r, repository)+++def _serialize_refactoring(+ r: Any, repository: str | None = None+) -> dict[str, Any]:+ """Compatibility adapter; request paths hydrate through the async service."""+ if isinstance(r, Recommendation):+ payload = r.as_dict()+ else:+ payload = build_recommendations([r])[0].as_dict()+ if repository is not None:+ payload["id"] = _refactoring_plan_id(r, repository)+ payload["repository"] = repository+ return payload+++def _round_opt(v: Any) -> float | None:+ """Round a nullable per-dimension score, preserving ``None`` (not measured)."""+ return round(v, 2) if v is not None else None+++def _serialize_metric(+ m: HealthFileMetric,+ lead: dict[str, Any] | None = None,+ *,+ is_test: bool = False,+) -> dict[str, Any]:+ return {+ "file_path": m.file_path,+ "score": round(m.score, 2),+ "max_ccn": m.max_ccn,+ "max_nesting": m.max_nesting,+ "nloc": m.nloc,+ # ``is_test``: this file is test material. ``has_test_file``: something+ # tests this file. Different questions, both kept.+ "is_test": is_test,+ "has_test_file": m.has_test_file,+ "line_coverage_pct": m.line_coverage_pct,+ "branch_coverage_pct": m.branch_coverage_pct,+ "module": m.module,+ # Leverage: ``(8.0 - score) * nloc``, what the headline recovers if this+ # file reaches target. See ``_gap_analysis`` for its denominator.+ "weighted_deficit": round(max(TARGET_SCORE - m.score, 0.0) * max(m.nloc, 1)),+ # ``defect_score`` is deliberately absent: it always equals ``score``.+ "maintainability_score": _round_opt(getattr(m, "maintainability_score", None)),+ "performance_score": _round_opt(getattr(m, "performance_score", None)),+ # Dominant cause and pre-clamp magnitude; null when the file has no findings.+ "primary_biomarker": lead.get("primary_biomarker") if lead else None,+ "primary_reason": lead.get("primary_reason") if lead else None,+ "total_deduction": lead.get("total_deduction") if lead else None,+ }diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/summary.py b/packages/server/src/repowise/server/mcp_server/tool_health/summary.pynew file mode 100644index 000000000..9bcaf9611--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/tool_health/summary.py@@ -0,0 +1,280 @@+"""Repository summaries for get_health: KPIs, gap analysis, per-file leads, the directive."""++from __future__ import annotations++from typing import Any++from repowise.core.analysis.health.grading import TARGET_SCORE, band_for+from repowise.core.analysis.health.models import primary_finding, split_by_origin+from repowise.core.analysis.health.perf.coverage import PerfCoverage+from repowise.core.analysis.health.scoring import (+ hotspot_health,+ nloc_weighted_attr,+)+from repowise.core.persistence.models import HealthFileMetric++# ``fix_first`` plus the two in ``then``. The plan lookup, the lead set and the+# directive must agree on it.+_DIRECTIVE_CANDIDATES = 3+++def _leads_by_file(findings: list[Any]) -> dict[str, dict[str, Any]]:+ """Reduce each file's findings to its dominant cause + pre-clamp magnitude.++ ``primary_*`` is the one reason to lead with; ``total_deduction`` (summed+ ``health_impact``) tells apart two files that both floor at 1.0. The+ selection rule lives in ``analysis.health.models.primary_finding``.+ """+ by_file: dict[str, list[Any]] = {}+ for f in findings:+ by_file.setdefault(f.file_path, []).append(f)+ leads: dict[str, dict[str, Any]] = {}+ for path, fs in by_file.items():+ primary = primary_finding(fs)+ if primary is None:+ continue+ # No edit resolves a history marker, so ``actionable_*`` uses code shape+ # alone and ``watch_*`` carries history as context.+ 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+++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.++ Every other block ranks and describes; this one recommends, like+ ``get_risk``'s ``directive``. Ranked by ``weighted_deficit`` (``score``+ floors at 1.0), so it names the file that moves the repo average.+ """+ if not by_leverage:+ return None+ # The highest-leverage file with something an edit can remove, else the+ # top file, flagged below rather than given an invented 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(TARGET_SCORE - top.score, 0.0) * max(top.nloc, 1))+ lead = leads.get(top.file_path) or {}+ # Does a plan behind ``plan_via`` address the cause in ``reason``? Some+ # biomarkers (e.g. ``coverage_gradient``) have no plan kind at all.+ 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 available+ out = {+ "fix_first": top.file_path,+ "reason": lead.get("actionable_reason") or f"scores {round(top.score, 2)}",+ # What this file recovers at target, and its share of the gross gap+ # (see ``_gap_analysis`` for the denominator).+ "recovers_weighted_deficit_points": recovers,+ "recovers_points": recovers,+ "recovers_points_compatibility": {+ "deprecated": True,+ "replacement": "recovers_weighted_deficit_points",+ "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 if m.file_path != top.file_path][:2],+ # Projected with ``only``: the bare ``include`` call restates the whole+ # dashboard and can exceed the MCP token cap.+ "plan_via": "get_health(include=['refactoring'], only=['refactoring_plans'])",+ "plan_addresses_reason": addresses,+ }+ # Context, not a task: no edit to this file settles history.+ 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:+ # No file has a code-shape lead: the deficit is history.+ 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+ if addresses:+ out["next_action"] = "inspect matching plan via plan_via"+ return out+ out["plan_note"] = _plan_note(+ lead_biomarker, available, (plan_count_by_path or {}).get(top.file_path, 0)+ )+ out["next_action"] = f"investigate {lead_biomarker}"+ return out+++def _plan_note(lead_biomarker: str, available: set[str], n_plans: int) -> str:+ """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.+ """+ if available:+ # Not "only X, Y": plans with an empty ``source_biomarker`` cannot be named.+ return (+ 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."+ )+ if n_plans:+ return (+ 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."+ )+ return (+ f"No plan addresses {lead_biomarker!r}; this file has no plans. "+ "Use the finding itself."+ )+++def _gap_analysis(metrics: list[HealthFileMetric]) -> dict[str, Any]:+ """How few files must reach 8.0 for the *weighted average* to reach 8.0.++ The NLOC-weighted average is held down by a few large low-scoring files, not+ the long tail. Two gaps, kept distinct:++ - ``weighted_gap_points``: the net points the average needs+ (``8.0 * total_nloc - sum(score * nloc)``). Above-target files cushion it.+ ``files_to_reach_target`` lifts the worst-deficit files until it closes.+ - ``weighted_gross_gap_points``: ``sum(max(8.0 - score, 0) * nloc)`` over+ below-target files, the ``share_of_repo_gap_pct`` denominator. Positive+ whenever any file is below target, and per-file shares sum to 100%; the+ net gap would let one large file exceed 100% (issue #1437).++ 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 = TARGET_SCORE * total_nloc - weighted_sum+ below = sorted(+ (+ max(TARGET_SCORE - m.score, 0.0) * max(m.nloc, 1)+ for m in metrics+ if m.score < TARGET_SCORE+ ),+ reverse=True,+ )+ gross_gap = sum(below)+ if not below:+ return {+ "target_score": TARGET_SCORE,+ "weighted_gap_points": 0,+ "weighted_gross_gap_points": 0,+ "files_below_target": 0,+ "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)++ # At or above target there is nothing to reach, but the gross gap still+ # stands while any file is below target.+ reachable = max(net_gap, 0)+ return {+ "target_score": TARGET_SCORE,+ "weighted_gap_points": round(max(net_gap, 0)),+ "weighted_gross_gap_points": round(gross_gap),+ "files_below_target": len(below),+ "files_to_reach_target": _files_for(reachable),+ "files_for_half_gap": _files_for(0.5 * reachable),+ }+++def _perf_kpis(performance_findings: int, coverage: PerfCoverage | None) -> dict[str, Any]:+ """The honest performance headline: finding count + density + coverage.++ Says how much of the code the perf pass ran on, so a bare+ ``performance_average`` near 10 is not read as "fast" on thin coverage.+ """+ density: float | None = None+ if coverage is not None and coverage.covered_nloc > 0:+ density = round(10000.0 * performance_findings / coverage.covered_nloc, 2)+ return {+ "performance_findings": performance_findings,+ "performance_findings_density_per_10k_loc": density,+ "performance_coverage_pct": (+ coverage.pct_loc if (coverage and coverage.analyzed_files) else None+ ),+ "performance_covered_files": coverage.covered_files if coverage else 0,+ "performance_analyzed_files": coverage.analyzed_files if coverage else 0,+ "performance_skipped_files": coverage.skipped_files if coverage else 0,+ "performance_unsupported_languages": (coverage.unsupported_languages if coverage else []),+ }+++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 None+++def _compute_kpis(+ metrics: list[HealthFileMetric],+ *,+ hotspot_paths: set[str] | None = None,+ performance_findings: int = 0,+ coverage: PerfCoverage | None = None,+) -> dict[str, Any]:+ if not metrics:+ return {+ "file_count": 0,+ "average_health": None,+ "band": None,+ "analysis_status": "unavailable",+ "hotspot_health": None,+ "worst_performer_path": None,+ "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_nloc+ worst = min(metrics, key=lambda r: r.score)+ return {+ "file_count": len(metrics),+ "average_health": round(avg, 2),+ # ``None`` with no hotspot files, not an empty set averaged to 10.0.+ "hotspot_health": hotspot_health(metrics, hotspot_paths or set()),+ # Weighted vs plain mean: a gap means a few large files hold it down.+ "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),+ # ``None`` until the pillar is measured.+ "maintainability_average": _avg(metrics, "maintainability_score"),+ "performance_average": _avg(metrics, "performance_score"),+ # The headline's code-shape and history halves, in deduction points.+ "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),+ }diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/targeted.py b/packages/server/src/repowise/server/mcp_server/tool_health/targeted.pynew file mode 100644index 000000000..9d85a745d--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/tool_health/targeted.py@@ -0,0 +1,139 @@+"""get_health targeted mode: the files and modules the caller named."""++from __future__ import annotations++from dataclasses import dataclass+from typing import Any++from repowise.core.analysis.health.aggregation import module_rollups as _module_rollups+from repowise.core.analysis.health.trends import file_trend+from repowise.server.mcp_server.tool_health.loading import HealthData+from repowise.server.mcp_server.tool_health.paging import Pager+from repowise.server.mcp_server.tool_health.request import HealthRequest+from repowise.server.mcp_server.tool_health.serialize import _serialize_finding, _serialize_metric+from repowise.server.mcp_server.tool_health.targets import _unresolved_targets+++@dataclass(frozen=True)+class ModeTotals:+ """Totals only the mode builder knows; ``None`` means the mode has no such list."""++ metrics: int | None+ trends: int | None+ modules: int+++def build_targeted(+ data: HealthData, req: HealthRequest, pager: Pager, repo_root: Any+) -> tuple[dict[str, Any], ModeTotals]:+ """Metrics, findings and trends for exactly the named targets."""+ pop = data.pop+ findings_total = data.findings.findings_total+ metric_payload = _metric_payload(data)+ module_set = set(req.module_targets)+ module_rollup = _module_rollups(+ [m for m in pop.all_metrics if m.module in module_set], data.deductions+ )+ result: dict[str, Any] = {+ "mode": "targets",+ "targets": req.raw_targets,+ # ``metrics_total`` makes a trim visible: a ``module:`` target expands+ # to a file count the caller cannot infer from what they passed.+ **({"modules": module_rollup} if req.module_targets else {}),+ "metrics": pager.bound(metric_payload, "metrics"),+ "metrics_total": len(metric_payload),+ "findings": pager.bound(+ [_serialize_finding(f, data.reference_repository) for f in data.findings.finding_rows],+ "findings",+ ),+ "findings_total": findings_total,+ # Which reading the scores are on; last, so identity keys lead.+ "scope": pop.reported_scope,+ "counts": pop.reported_counts,+ }+ unresolved = _unresolved_targets(+ file_targets=pop.file_targets,+ module_targets=req.module_targets,+ matched_modules=pop.matched_modules,+ resolved_paths={m.file_path for m in data.metric_rows},+ excluded_paths=pop.excluded_paths,+ unscored_paths=pop.unscored_paths,+ repo_root=repo_root,+ )+ if unresolved:+ result["unresolved"] = unresolved+ if any(u["reason"] == "no_such_module" for u in unresolved):+ # ``module:`` has no discovery call, so list the valid names.+ result["known_modules"] = sorted({m.module for m in pop.all_metrics if m.module})+ trends = _file_trends(data)+ if trends:+ result["trends"] = pager.bound(trends, "trends")+ if req.module_targets and not req.only and not req.include_set:+ _defer_to_secondary_rankings(result, req, findings_total, len(trends))+ return result, ModeTotals(+ metrics=len(metric_payload), trends=len(trends), modules=len(module_rollup)+ )+++def _metric_payload(data: HealthData) -> list[dict[str, Any]]:+ rows = []+ for m in data.metric_rows:+ row = _serialize_metric(+ m, data.leads.get(m.file_path), is_test=m.file_path in data.test_paths+ )+ if m.file_path in data.signals_by_path:+ row["signals"] = data.signals_by_path[m.file_path]+ rows.append(row)+ return rows+++def _file_trends(data: HealthData) -> list[dict[str, Any]]:+ """Per-file score trajectory for each target, omitted when a file has+ fewer than 2 snapshots rather than drawn as a flat line."""+ trends = []+ for m in data.metric_rows:+ t = file_trend(data.snapshots, m.file_path)+ if not t.points:+ continue+ series = [round(p.score, 2) for p in t.points]+ entry: dict[str, Any] = {+ "file_path": t.file_path,+ "series": series,+ "current": t.current,+ "delta": t.delta,+ "declining": t.declining,+ }+ # The score floors at 1.0, flattening progress on the worst files.+ # Carry the unclamped series only where it differs.+ unclamped = [round(p.unclamped_score, 2) for p in t.points]+ if unclamped != series:+ entry["unclamped_series"] = unclamped+ entry["unclamped_delta"] = t.unclamped_delta+ trends.append(entry)+ return trends+++def _defer_to_secondary_rankings(+ result: dict[str, Any], req: HealthRequest, findings_total: int, trends_total: int+) -> None:+ """A bare ``module:`` call leads with the rollup; the ranked lists become calls."""+ targets, repo, view = req.raw_targets, req.repo, req.refactoring_view+ result["secondary_rankings"] = {+ "findings": {+ "total": findings_total,+ "call": (+ f"get_health(targets={targets!r}, only=['findings'], "+ f"repo={repo!r}, limit=50, refactoring_view='{view}')"+ ),+ },+ "trends": {+ "total": trends_total,+ "call": (+ f"get_health(targets={targets!r}, only=['trends'], "+ f"repo={repo!r}, limit=50, refactoring_view='{view}')"+ ),+ },+ }+ for block in ("findings", "trends"):+ result.pop(block, None)+ result.pop(f"{block}_total", None)diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/targets.py b/packages/server/src/repowise/server/mcp_server/tool_health/targets.pynew file mode 100644index 000000000..c7653e083--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/tool_health/targets.py@@ -0,0 +1,72 @@+"""Target resolution for get_health: expanding ``module:`` targets, naming misses."""++from __future__ import annotations++from pathlib import Path+from typing import Any+++def _expand_module_targets(+ metrics: list[Any], module_targets: list[str], file_targets: list[str]+) -> tuple[list[str], set[str]]:+ """Add every file of each named module to the targets; report which matched.++ The path list is returned untouched (not re-sorted) when no module was+ named, so a plain file-target call keeps the caller's order.+ """+ matched_modules: set[str] = set()+ if not module_targets:+ return file_targets, matched_modules+ expanded = list(file_targets)+ module_set = set(module_targets)+ for m in metrics:+ if m.module in module_set:+ matched_modules.add(m.module)+ expanded.append(m.file_path)+ return sorted(set(expanded)), matched_modules+++def _unresolved_targets(+ *,+ file_targets: list[str],+ module_targets: list[str],+ matched_modules: set[str],+ resolved_paths: set[str],+ excluded_paths: set[str],+ unscored_paths: set[str],+ repo_root: Any,+) -> list[dict[str, str]]:+ """Name every requested target that produced no rows, with a reason.++ Otherwise an empty ``findings`` list reads as "this file is healthy". The+ reason is actionable: ``not_indexed`` (run ``repowise update``),+ ``no_such_path`` (a typo), ``excluded`` (repo config), ``not_measured``+ (indexed, but no stored split for the ``counts`` reading; passed in so it+ is not misreported as ``not_indexed``).+ """+ out = [+ {"target": t, "reason": _miss_reason(t, excluded_paths, unscored_paths, repo_root)}+ for t in file_targets+ if t not in resolved_paths+ ]+ out.extend(+ {"target": f"module:{name}", "reason": "no_such_module"}+ for name in module_targets+ if name not in matched_modules+ )+ return out+++def _miss_reason(+ target: str, excluded_paths: set[str], unscored_paths: set[str], repo_root: Any+) -> str:+ """Why one file target produced no row."""+ if target in excluded_paths:+ return "excluded"+ if target in unscored_paths:+ return "not_measured"+ try:+ on_disk = (Path(repo_root) / target).exists()+ except (OSError, ValueError):+ on_disk = False+ return "not_indexed" if on_disk else "no_such_path"diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/tool.py b/packages/server/src/repowise/server/mcp_server/tool_health/tool.pynew file mode 100644index 000000000..958ad0c69--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/tool_health/tool.py@@ -0,0 +1,275 @@+"""MCP tool: get_health — code-health markers and per-file scores.++A thin dispatcher: a lookup by id answers from ``details``; everything else+reads once (``loading``), builds the mode's payload (``targeted`` /+``dashboard``), adds the ``include``-gated blocks (``blocks``), and applies the+accounting and projection passes (``paging`` / ``projection``).+"""++from __future__ import annotations++from time import perf_counter+from typing import Any++from repowise.core.analysis.health.counts import DEFAULT_COUNTS+from repowise.core.analysis.health.scope import DEFAULT_SCOPE+from repowise.core.persistence.database import get_session+from repowise.core.registry import ToolRecipe+from repowise.core.registry import mcp_tool_registry as mcp+from repowise.server.mcp_server._budget import OmissionCollector+from repowise.server.mcp_server._helpers import _get_repo, _resolve_repo_context+from repowise.server.mcp_server._meta import build_meta as _build_meta+from repowise.server.mcp_server.tool_health.analysis_meta import (+ _attach_health_analysis_meta,+ _attach_repository_analysis_meta,+)+from repowise.server.mcp_server.tool_health.blocks import add_optional_blocks+from repowise.server.mcp_server.tool_health.dashboard import build_dashboard+from repowise.server.mcp_server.tool_health.details import (+ _detail_response,+ _note_inapplicable_controls,+ _selector_conflict,+)+from repowise.server.mcp_server.tool_health.loading import HealthData, load_health_data+from repowise.server.mcp_server.tool_health.paging import (+ Pager,+ _stamp_collection_totals,+ _stamp_nested_collections,+)+from repowise.server.mcp_server.tool_health.projection import (+ _name_rejected_controls,+ _name_uncounted_blocks,+ _project,+)+from repowise.server.mcp_server.tool_health.request import _ONLY_ALIASES, HealthRequest+from repowise.server.mcp_server.tool_health.targeted import ModeTotals, build_targeted+from repowise.server.services.refactoring_health import DEFAULT_VIEW as _REFACTORING_VIEW_DEFAULT++__all__ = ["_ONLY_ALIASES", "get_health"]+++ surface_order=90,+ artifact_type="health",+ presentation="health",+ evidence_basis="measured",+ recipes=(+ ToolRecipe(+ "health_directive",+ 'get_health(only=["directive"])',+ ("get_health",),+ ),+ ToolRecipe(+ "health_file_self_check",+ 'get_health(targets=["path"], include=["refactoring"])',+ ("get_health",),+ ),+ ToolRecipe(+ "health_module_triage",+ 'get_health(targets=["module:path"], only=["modules","metrics"])',+ ("get_health",),+ ),+ ToolRecipe(+ "health_trend",+ 'get_health(include=["trend"], only=["trend"])',+ ("get_health",),+ ),+ ToolRecipe(+ "health_accuracy",+ 'get_health(include=["accuracy"], only=["accuracy"])',+ ("get_health",),+ ),+ ToolRecipe(+ "health_coverage",+ 'get_health(include=["coverage"], only=["coverage"])',+ ("get_health",),+ ),+ ToolRecipe(+ "health_performance_refactoring",+ 'get_health(include=["performance","refactoring"], '+ 'only=["performance_opportunities","refactoring_plans"])',+ ("get_health",),+ ),+ ToolRecipe(+ "health_performance_summary",+ 'get_health(include=["performance"], only=["performance_summary"])',+ ("get_health",),+ ),+ ToolRecipe(+ "health_performance_opportunity",+ 'get_health(opportunity_id="perf...")',+ ("get_health",),+ ),+ ToolRecipe(+ "health_performance_evidence",+ 'get_health(opportunity_id="perf...", '+ 'only=["performance_evidence"], cursor=0)',+ ("get_health",),+ ),+ ),+)+async def get_health(+ targets: list[str] | None = None,+ include: list[str] | None = None,+ repo: str | None = None,+ limit: int = 20,+ only: list[str] | None = None,+ refactoring_view: str = _REFACTORING_VIEW_DEFAULT,+ refactoring_type: str | None = None,+ refactoring_confidence: str | None = None,+ refactoring_effort: str | None = None,+ cursor: int = 0,+ finding_id: str | None = None,+ plan_id: str | None = None,+ opportunity_id: str | None = None,+ performance_view: str | None = None,+ performance_context: str | None = None,+ performance_boundary: str | None = None,+ performance_confidence: str | None = None,+ performance_actionability: str | None = None,+ performance_sort: str | None = None,+ scope: str = DEFAULT_SCOPE,+ counts: str = DEFAULT_COUNTS,+) -> dict:+ """Code-health scores and findings from stored analysis.++ No ``targets`` returns a dashboard; targets rank files and findings.+ Never recomputes health: commit, then run ``repowise update``.+ Every block and accepted value: docs/agent/MCP_TOOLS.md.++ Args:+ targets: file paths or ``module:<name>``; unmatched ones land in+ ``unresolved``.+ include: ``biomarkers``|``refactoring``|``trend``|``coverage``|+ ``accuracy``|``signals``|``churn_complexity``|``doc_drift``,+ or a dimension incl. ``advisory``; ``performance`` and+ ``refactoring`` add queues.+ only: keys to keep; identity, totals, recovery survive.+ ``biomarkers``/``accuracy``/``refactoring`` alias their block key;+ ``performance``/``defect``/``maintainability``/``advisory``+ do not: they filter rows into ``unknown_only_keys``.+ repo: usually omitted.+ limit: max rows per ranked list, ``0`` for none.+ cursor: zero-based offset into a ranked list.+ finding_id/plan_id: stable ``id`` from a finding or plan.+ opportunity_id: ``perf...``/``refop...``: the unit, its steps or+ plan, evidence paged by ``only=["*_evidence"]``.+ refactoring_view: ``diversified`` (default)|``canonical``|+ ``file_spread``; _type/_confidence/_effort filter.+ performance_view/_context/_boundary/_confidence/_actionability/_sort:+ queue filters; a rejected value lists the accepted.+ scope / counts: default ``all``/``everything``. ``production`` drops+ test files; ``code_shape`` drops the git-derived half of the+ score and its findings.++ """+ started = perf_counter()+ conflict = _selector_conflict(+ finding_id=finding_id, plan_id=plan_id, opportunity_id=opportunity_id+ )+ if conflict is not None:+ return _note_inapplicable_controls(conflict, scope, counts)+ req = HealthRequest(+ targets=targets,+ include=include,+ only=only,+ repo=repo,+ limit=limit,+ cursor=cursor,+ refactoring_view=refactoring_view,+ refactoring_type=refactoring_type,+ refactoring_confidence=refactoring_confidence,+ refactoring_effort=refactoring_effort,+ performance_view=performance_view,+ performance_context=performance_context,+ performance_boundary=performance_boundary,+ performance_confidence=performance_confidence,+ performance_actionability=performance_actionability,+ performance_sort=performance_sort,+ scope=scope,+ counts=counts,+ )+ ctx = await _resolve_repo_context(repo)+ omission_collector = OmissionCollector("get_health", repo_root=ctx.path)+ pager = Pager(req.limit, req.cursor)+ async with get_session(ctx.session_factory) as session:+ repository = await _get_repo(session)+ reference_repository = ctx.alias or repository.name+ detail = await _detail_response(+ session,+ repository,+ reference_repository,+ finding_id=finding_id,+ plan_id=plan_id,+ opportunity_id=opportunity_id,+ only_set=req.only_set,+ limit=req.limit,+ cursor=req.cursor,+ )+ if detail is not None:+ return _note_inapplicable_controls(detail, scope, counts)+ data = await load_health_data(+ session, repository, reference_repository, ctx.path, req+ )++ if data.pop.scoped:+ result, mode_totals = build_targeted(data, req, pager, ctx.path)+ else:+ result, mode_totals = build_dashboard(data, req, pager)+ add_optional_blocks(result, data, req, pager, str(ctx.path))+ result = _finish(result, data, req, pager, mode_totals)++ # Targeted mode scopes the stale signal to the asked-about files.+ result["_meta"] = _build_meta(repository=repository, targets=targets if targets else None)+ if data.pop.scoped:+ # Analysis freshness is repo-wide, so both modes report the same status.+ await _attach_repository_analysis_meta(session, repository, result["_meta"])+ else:+ _attach_health_analysis_meta(result["_meta"], data.pop.all_metrics)+ pager.report_omissions(result, omission_collector, reference_repository)+ omission_collector.attach(result)+ # Server-side wall clock, as ``get_context`` reports.+ result["_meta"]["timing_ms"] = round((perf_counter() - started) * 1000, 2)+ return result+++def _finish(+ result: dict[str, Any],+ data: HealthData,+ req: HealthRequest,+ pager: Pager,+ mode_totals: ModeTotals,+) -> dict[str, Any]:+ """Accounting, caller-error reports, the ``only`` projection, then recovery."""+ findings = data.findings+ _stamp_collection_totals(+ result,+ {+ "targets": len(req.raw_targets),+ "metrics": mode_totals.metrics,+ "findings": findings.findings_total,+ "trends": mode_totals.trends,+ "modules": mode_totals.modules,+ "worst_files": len(data.metric_rows),+ "high_leverage_files": len(data.by_leverage),+ "top_findings": findings.findings_total,+ "test_findings": findings.test_findings_total,+ "churn_complexity": len(data.churn_points),+ "refactoring_plans": len(data.refactoring_recommendations),+ "performance_opportunities": (+ data.performance.page.total if data.performance.page is not None else 0+ ),+ },+ req.limit,+ )+ if req.unknown_include_keys:+ result["unknown_include_keys"] = req.unknown_include_keys+ _stamp_nested_collections(result)+ reported_scope, reported_counts = data.pop.reported_scope, data.pop.reported_counts+ _name_rejected_controls(result, req, reported_scope, reported_counts)+ _name_uncounted_blocks(result, reported_counts)+ result = _project(result, req, reported_scope, reported_counts)+ recovery = pager.recovery_block(result, req)+ if recovery:+ result["recovery"] = recovery+ return resultdiff --git a/tests/unit/server/mcp/test_health.py b/tests/unit/server/mcp/test_health.pyindex 299b0bd82..802f0b00d 100644--- a/tests/unit/server/mcp/test_health.py+++ b/tests/unit/server/mcp/test_health.py@@ -1518,7 +1518,7 @@ async def test_targeted_mode_asks_only_about_the_files_it_was_given(test. Dashboard mode partitions a ranked finding list whose paths are notknown until that list is built, so it must stay repo-wide."""- import repowise.server.mcp_server.tool_health as th+ import repowise.server.mcp_server.tool_health.loading as thfrom repowise.server.mcp_server import get_healthasked: list[object] = []@@ -1594,7 +1594,8 @@ async def test_dashboard_coverage_declines_the_covered_lines_column(setup_mcp, hdict comprehension. So a test that only checked the payload would pass onthe unfixed code; the waste is invisible from the outside."""- from repowise.server.mcp_server import get_health, tool_health+ from repowise.server.mcp_server import get_health+ from repowise.server.mcp_server.tool_health import loading as tool_healthseen: list[bool] = []real = tool_health.load_coverage_for_repodiff --git a/tests/unit/server/mcp/test_health_doc_drift.py b/tests/unit/server/mcp/test_health_doc_drift.pyindex a89954add..dca5ee203 100644--- a/tests/unit/server/mcp/test_health_doc_drift.py+++ b/tests/unit/server/mcp/test_health_doc_drift.py@@ -128,7 +128,7 @@ async def test_an_index_without_the_drift_table_says_so(setup_mcp, health_data, drift_rows, monkeypatch):""""Could not read" must never render as "nothing to report"."""- import repowise.server.mcp_server.tool_health as th+ import repowise.server.mcp_server.tool_health.loading as thfrom repowise.server.mcp_server import get_healthasync def _raise(*_a, **_k):diff --git a/tests/unit/test_no_hotspot_health_copies.py b/tests/unit/test_no_hotspot_health_copies.pyindex ca5d28934..e59d3cf1b 100644--- a/tests/unit/test_no_hotspot_health_copies.py+++ b/tests/unit/test_no_hotspot_health_copies.py@@ -55,6 +55,7 @@ _PLUMBING: dict[str, str] = {"repowise/core/analysis/health/trends.py": "diffs snapshots; owns no current value","repowise/server/routers/code_health/trends_routes.py": "serves the snapshot series","repowise/cli/commands/health_cmd/trends.py": "prints the snapshot series",+ "repowise/server/mcp_server/tool_health/blocks.py": "renders get_health's snapshot diff",# --- pure renderers: read a value someone else computed ------------------"repowise/cli/commands/health_cmd/command.py": "prints the KPI dict it was handed","repowise/core/generation/editor_files/data.py": "the CodeHealthBlock field",