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(persistence): split health crud into findings, metrics, snapshots and summary modules (#3977)
Raghav Chamadiya13bc247bcfba
diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/health.py b/packages/core/src/repowise/core/persistence/crud/analysis/health.pydeleted file mode 100644index ef0307f17..000000000--- a/packages/core/src/repowise/core/persistence/crud/analysis/health.py+++ /dev/null@@ -1,1332 +0,0 @@-"""CRUD operations for code-health findings, metrics, and snapshots-(repowise persistence layer)."""--from __future__ import annotations--import json-from collections.abc import Iterable, Sequence-from datetime import datetime-from pathlib import Path-from typing import TYPE_CHECKING, Any, NamedTuple--from sqlalchemy import func, or_, select-from sqlalchemy.ext.asyncio import AsyncSession-from sqlalchemy.orm import defer--if TYPE_CHECKING:- from ....analysis.health.perf.coverage import PerfCoverage--from ....analysis.finding_registry import excluded_types-from ....analysis.health.complexity.languages import has_health_dialect-from ....analysis.health.finding_identity import (- finding_public_id,- legacy_finding_public_id,-)-from ....analysis.health.governance import GOVERNANCE_BIOMARKERS-from ....analysis.health.grading import analysed_share--# The comparator is pure and lives with the health read models; only the SQL-# that feeds it belongs here. Re-imported rather than moved out of reach: the-# crud surface is where the MCP tool and the tests already read it from.-from ....analysis.health.ranking import (- deduction_by_path,- sort_metrics_worst_first,- worst_kpis,-)-from ....analysis.health.rows import detail_map, split_unscored-from ....analysis.health.scope import scores_language-from ....analysis.health.scoring import ADVISORY_DIMENSION, SCORE_FIELDS, nloc_weighted_attr-from ....analysis.health.worth import LowPriority, finding_priorities-from ....test_paths import is_test_related_path-from ...models import (- DocDriftFinding,- GraphNode,- HealthFileMetric,- HealthFinding,- HealthSnapshot,- Repository,- _new_uuid,- _now_utc,-)-from .._shared import _BATCH_SIZE-from ..graph import get_test_file_paths-from .plain_rows import plain_rows-from .shown import gated_counts, shown---def _health_finding_row_kwargs(finding: Any, repository_id: str) -> dict:- """Normalize an analyzer dataclass or a plain dict into ORM row kwargs.-- All three writers land here, so a column added to the row is written by- every path or by none. ``public_id`` is stamped here because this is the- one place every persisted finding passes through.- """- if hasattr(finding, "biomarker_type"):- severity = finding.severity- data = {- "file_path": finding.file_path,- "biomarker_type": finding.biomarker_type,- "severity": str(severity.value) if hasattr(severity, "value") else str(severity),- "function_name": finding.function_name,- "line_start": finding.line_start,- "line_end": finding.line_end,- "details_json": json.dumps(finding.details or {}),- "health_impact": float(finding.health_impact),- "reason": finding.reason or "",- "dimension": getattr(finding, "dimension", None) or "defect",- }- else:- data = dict(finding)- if "details" in data:- data["details_json"] = json.dumps(data.pop("details") or {})- data.setdefault("public_id", finding_public_id(finding))- if data.get("dimension") == "performance":- # Present before the finalizer runs because the analyzer stamps it into- # ``details``; the finalizer restates it from authoritative stored rows.- data.setdefault("opportunity_id", detail_map(finding).get("opportunity_id"))- return {- "id": _new_uuid(),- "repository_id": repository_id,- **{- k: v- for k, v in data.items()- if k not in ("id", "repository_id") and hasattr(HealthFinding, k)- },- }---_NOT_REFRESHED = frozenset({"id", "repository_id", "status", "created_at"})---async def _insert_keeping_triage(- session: AsyncSession,- repository_id: str,- findings: list[Any],- scope: list[Any],-) -> None:- """Insert *findings*, keeping the triage a person recorded on any of them.-- Callers delete the open rows in *scope* first. A finding whose public id- matches a triaged row in *scope* is folded into that row: its detection- fields are refreshed and ``acknowledged`` / ``false_positive`` stand, while- ``resolved`` reopens because the finding said to be fixed is still there.- Extra triaged rows sharing that id are deleted. Every other finding, a- second one on an already claimed id included, is inserted open.- """- triaged: dict[str, list[HealthFinding]] = {}- rows = await session.execute(- select(HealthFinding)- .where(*scope, HealthFinding.status != "open", HealthFinding.public_id.is_not(None))- .order_by(HealthFinding.updated_at.desc())- )- for row in rows.scalars().all():- triaged.setdefault(row.public_id, []).append(row)-- now = _now_utc()- claimed: set[str] = set()- for i in range(0, len(findings), _BATCH_SIZE):- for f in findings[i : i + _BATCH_SIZE]:- values = _health_finding_row_kwargs(f, repository_id)- matches = triaged and (- triaged.get(values["public_id"]) or triaged.get(legacy_finding_public_id(f))- )- kept, *extra = matches or [None]- if kept is None or kept.id in claimed:- # A second finding on a claimed id is inserted open: two- # findings colliding on one id must not lose either.- session.add(HealthFinding(**values))- continue- claimed.add(kept.id)- for row in extra:- await session.delete(row)- for name, value in values.items():- if name not in _NOT_REFRESHED:- setattr(kept, name, value)- if kept.status == "resolved":- kept.status = "open"- kept.updated_at = now- await session.flush()---async def save_health_findings(- session: AsyncSession,- repository_id: str,- findings: list[Any],-) -> None:- """Replace open health findings for *repository_id* with *findings*.-- Delete-then-insert over the open rows; triaged rows carry over by public id- (``_insert_keeping_triage``). Accepts either ``HealthFindingData``- dataclasses or plain dicts.- """- scope = [HealthFinding.repository_id == repository_id]- existing = await session.execute(- select(HealthFinding).where(*scope, HealthFinding.status == "open")- )- for row in existing.scalars().all():- await session.delete(row)- await session.flush()-- await _insert_keeping_triage(session, repository_id, findings, scope)---async def replace_governance_findings(- session: AsyncSession,- repository_id: str,- findings: list[Any],-) -> None:- """Idempotent additive write of governance-layer health findings.-- Deletes the open ``health_findings`` rows whose ``biomarker_type``- is one of ``ungoverned_hotspot``, ``stale_governance``, or- ``contradictory_decision`` for *repository_id*, then inserts the new- *findings* in batches, keeping triage by public id like the other writers.-- This function deliberately does **not** recompute ``HealthFileMetric.score``- — that pass has already completed in the upstream health-analysis phase.- Governance findings surface through the findings layer (``get_risk``- ``top_biomarkers``, ``get_context`` health block) rather than the numeric- score. A second score-recomputation pass would require re-loading the full- per-file results table; the conservative choice is to leave scores as-is- and let findings carry the governance signal.-- Composable with ``save_health_findings``: the delete is scoped to only- the three governance biomarker types, so structural findings written by- ``save_health_findings`` are untouched.-- Accepts ``HealthFindingData`` dataclasses or plain dicts (same protocol- as ``save_health_findings``).- """- # Delete existing open governance findings for this repo only.- scope = [- HealthFinding.repository_id == repository_id,- HealthFinding.biomarker_type.in_(list(GOVERNANCE_BIOMARKERS)),- ]- existing = await session.execute(- select(HealthFinding).where(*scope, HealthFinding.status == "open")- )- for row in existing.scalars().all():- await session.delete(row)- await session.flush()-- await _insert_keeping_triage(session, repository_id, findings, scope)---def _opt(cast: Any, value: Any) -> Any:- """*value* through *cast*, keeping ``None`` (a file health never walked)."""- return None if value is None else cast(value)---def _health_metric_row_data(metric: Any) -> dict:- """One metric dataclass as column values. Both writers go through here."""- return {- "file_path": metric.file_path,- "score": _opt(float, metric.score),- "max_ccn": _opt(int, metric.max_ccn),- "max_nesting": _opt(int, metric.max_nesting),- "nloc": int(metric.nloc),- "duplication_pct": metric.duplication_pct,- "has_test_file": bool(metric.has_test_file),- "line_coverage_pct": metric.line_coverage_pct,- "branch_coverage_pct": metric.branch_coverage_pct,- "module": metric.module,- "defect_score": getattr(metric, "defect_score", None),- "maintainability_score": getattr(metric, "maintainability_score", None),- "performance_score": getattr(metric, "performance_score", None),- "structure_deduction": getattr(metric, "structure_deduction", None),- "history_deduction": getattr(metric, "history_deduction", None),- "is_test": bool(getattr(metric, "is_test", False)),- "code_origin": getattr(metric, "code_origin", None),- }---async def save_health_metrics(- session: AsyncSession,- repository_id: str,- metrics: list[Any],- *,- analyzed_commit: str | None = None,-) -> None:- """Replace per-file health metrics for *repository_id*.-- Delete-then-insert (matches the findings writer). The unique- constraint on (repository_id, file_path) means we cannot leave- stale rows around without an upsert dance — delete-and-insert keeps- it simple and aligns with how dead-code findings are written.-- ``analyzed_commit`` stamps every written row with the commit these scores- were computed against — the same pattern as ``save_coverage_files``'- ``ingested_commit_sha``. Health runs as its own pass and can lag the index,- so ``Repository.head_commit`` cannot answer "how old is this score". Omitted- → NULL, which reads as "not recorded" rather than "current".- """- existing = await session.execute(- select(HealthFileMetric).where(HealthFileMetric.repository_id == repository_id)- )- for row in existing.scalars().all():- await session.delete(row)- await session.flush()-- for i in range(0, len(metrics), _BATCH_SIZE):- batch = metrics[i : i + _BATCH_SIZE]- for m in batch:- data = _health_metric_row_data(m) if hasattr(m, "file_path") else dict(m)- # After the dict-passthrough branch so an explicit per-row value in a- # raw dict still wins; the sha is a property of the pass, not the row.- if analyzed_commit is not None:- data.setdefault("analyzed_commit", analyzed_commit)-- session.add(- HealthFileMetric(- id=_new_uuid(),- repository_id=repository_id,- **{- k: v- for k, v in data.items()- if k not in ("id", "repository_id") and hasattr(HealthFileMetric, k)- },- )- )- await session.flush()---async def get_scored_file_paths(session: AsyncSession, repository_id: str) -> set[str]:- """The files health currently scores, read off the stored metric rows."""- q = select(HealthFileMetric.file_path).where(- HealthFileMetric.repository_id == repository_id- )- return {path for (path,) in (await session.execute(q)).all()}---async def backfill_is_test(session: AsyncSession, repository_id: str) -> int:- """Stamp ``is_test`` on rows written before the column existed.-- The answer comes from the path, not from a score, so an existing store gets- it on the next update instead of waiting for a re-index. Without this a- ``scope=production`` request on an un-rescored store would quietly answer- with the whole repository. Returns the number of rows filled.- """- rows = (- await session.execute(- select(HealthFileMetric).where(- HealthFileMetric.repository_id == repository_id,- HealthFileMetric.is_test.is_(None),- )- )- ).scalars().all()- if not rows:- return 0- languages = await get_file_language_map(session, repository_id)- for row in rows:- row.is_test = is_test_related_path(row.file_path, languages.get(row.file_path))- await session.flush()- return len(rows)---async def prune_unscored_health_rows(session: AsyncSession, repository_id: str) -> int:- """Drop metrics and findings for files health no longer scores.-- A full index rewrites the whole population and needs nothing here, but an- update only touches the files that changed, so prose and configuration rows- written by an older version would otherwise sit in the average forever.- Files with no graph node are left alone: no language is not the same answer- as a language health does not score. Returns the number of rows removed,- which is zero on every update after the first.- """- languages = await get_file_language_map(session, repository_id)- stale = [path for path, language in languages.items() if not scores_language(language)]- if not stale:- return 0- removed = 0- for i in range(0, len(stale), _BATCH_SIZE):- batch = stale[i : i + _BATCH_SIZE]- for model in (HealthFileMetric, HealthFinding):- rows = await session.execute(- select(model).where(- model.repository_id == repository_id,- model.file_path.in_(batch),- )- )- for row in rows.scalars().all():- await session.delete(row)- removed += 1- await session.flush()- return removed---async def clear_unanalysed_scores(session: AsyncSession, repository_id: str) -> int:- """Drop the numbers stored for files in a language health has no dialect for.-- A store written before such files were left unscored holds a 10.0 and a- max_ccn of 1 for each, which every average would keep counting until a full- rescore. The answer comes from the language alone, so an update fixes it in- place, git history or not. Files with no graph node are left alone, as in- ``prune_unscored_health_rows``. Returns the number of rows cleared.- """- languages = await get_file_language_map(session, repository_id)- paths = [p for p, lang in languages.items() if lang and not has_health_dialect(lang)]- cleared = 0- for i in range(0, len(paths), _BATCH_SIZE):- rows = await session.execute(- select(HealthFileMetric).where(- HealthFileMetric.repository_id == repository_id,- HealthFileMetric.file_path.in_(paths[i : i + _BATCH_SIZE]),- HealthFileMetric.score.is_not(None),- )- )- for row in rows.scalars().all():- for name in (*SCORE_FIELDS, "max_ccn", "max_nesting"):- setattr(row, name, None)- cleared += 1- await session.flush()- return cleared---async def backfill_module_attribution(- session: AsyncSession,- repository_id: str,- package_roots: set[str],-) -> int:- """Recompute every metric row's ``module`` from the repo layout.-- Returns the number of rows changed, so a caller can stay silent when there- was nothing to correct.-- ``module`` is a pure function of ``(file_path, package_roots)`` — no parse,- no symbols, no git, no model — so correcting it never needs the rows- rewritten by a re-score, let alone a re-index. That is the whole point:- a directory label must not cost users an indexing run.-- Idempotent by construction, and it converges with the indexer rather than- fighting it: both call the same :func:`module_for` over the same- disk-scanned roots, so a full index writing a *different* value would mean- the two disagree about the repo layout, and running this again would flip- it back rather than settle.- """- from ....ingestion.package_roots import module_for-- result = await session.execute(- select(HealthFileMetric).where(HealthFileMetric.repository_id == repository_id)- )- changed = 0- for row in result.scalars().all():- expected = module_for(row.file_path, package_roots)- if row.module != expected:- row.module = expected- changed += 1- if changed:- await session.flush()- return changed---def open_finding_count(findings: Iterable[Any]) -> int:- """The open findings total every health headline prints.-- Advisory findings carry a zero health impact, so counting them would grow- the headline without anything having got worse.- """- return sum(1 for f in findings if getattr(f, "dimension", None) != ADVISORY_DIMENSION)---async def health_exclude_spec(- session: AsyncSession, repository_id: str, repo_path: Path | str | None = None-) -> Any:- """The exclude patterns every health surface narrows its files by.-- The repository's settings and ``exclude_patterns`` only. Not the gitignore- stack: ingestion keeps a file git tracks even when an ignore rule matches- it, so a stored row under such a rule is a real file of the repository.- ``repo_path`` is where to read the config when the caller serves a- checkout other than the stored ``local_path``.- """- repo = await session.get(Repository, repository_id)- if repo is None:- return None-- patterns: list[str] = []- seen: set[str] = set()-- def _add(values: Any) -> None:- if not isinstance(values, list):- return- for value in values:- if isinstance(value, str) and value not in seen:- seen.add(value)- patterns.append(value)-- try:- settings = json.loads(getattr(repo, "settings_json", "") or "{}")- if isinstance(settings, dict):- _add(settings.get("exclude_patterns"))- except (TypeError, ValueError):- pass-- try:- from repowise.core.repo_config import load_repo_config-- cfg = load_repo_config(Path(repo_path or repo.local_path))- if isinstance(cfg, dict):- _add(cfg.get("exclude_patterns"))- except Exception:- pass-- if not patterns:- return None-- import pathspec-- return pathspec.PathSpec.from_lines("gitwildmatch", patterns)---def _filter_excluded_paths(rows: list[Any], spec: Any) -> list[Any]:- if spec is None:- return rows- return [row for row in rows if not spec.match_file(getattr(row, "file_path", ""))]---async def get_health_findings(- session: AsyncSession,- repository_id: str,- *,- biomarker_type: str | None = None,- min_severity: str | None = None,- severity: str | None = None,- file_path: str | None = None,- file_paths: Sequence[str] | None = None,- dimension: str | None = None,- exclude_dimensions: tuple[str, ...] | None = None,- status: str = "open",- include_withheld: bool = False,- include_unverified: bool = False,- file_holds: bool = True,- hold_history: bool = True,- limit: int | None = None,-) -> list[HealthFinding]:- """Findings for one repository: production ahead of test files, worth doing- first ahead of lower-priority ones (``worth.finding_priorities``), each part- ordered by health impact.-- Finding types the registry withholds (``finding_registry``) are left out,- so every surface built on this read shows only what has earned a place; a- provisional type named in ``biomarker_type`` is an explicit request and is- returned. Files of a language the registry gates for health findings are- left out too, unless ``include_unverified`` (which also opts into every- provisional type). ``include_withheld`` is for analysis that must see every- row. ``file_holds=False`` keeps the findings held back by their file- (vendored, generated, history on a test) for a reader that sums scores or- KPIs, which count them. ``hold_history=False`` keeps history markers on- production files for a view that treats history itself.-- ``exclude_dimensions`` is how a general queue keeps a dimension out of a- ranking it does not share units with. It is ignored when ``dimension``- names one explicitly, so asking for a dimension always returns it.-- ``severity`` is an exact comma-separated selection and wins over the- ``min_severity`` threshold when both are given.-- ``status`` defaults to open work. It also accepts a comma-separated list of- ``open`` / ``acknowledged`` / ``resolved`` / ``false_positive``, or ``all``- to drop the filter, so a triage surface can show what it has already- reviewed without a second read.-- ``file_paths`` scopes to a set of files in one read; an empty sequence- matches nothing. ``limit`` caps the rows returned, in that order.- """- q = select(HealthFinding).where(HealthFinding.repository_id == repository_id)- statuses = [s.strip() for s in status.split(",") if s.strip()]- if "all" not in statuses:- q = q.where(HealthFinding.status.in_(statuses or ["open"]))- if dimension is None and exclude_dimensions:- q = q.where(- or_(- HealthFinding.dimension.is_(None),- HealthFinding.dimension.not_in(list(exclude_dimensions)),- )- )- # Accept a comma-separated list so a caller can pull several biomarker- # types in one request (e.g. the function-level + coupling panels).- # A single value with no comma still matches exactly (``IN`` of one).- types = [t.strip() for t in (biomarker_type or "").split(",") if t.strip()]- if types:- q = q.where(HealthFinding.biomarker_type.in_(types))- if not include_withheld:- q = q.where(- shown(- "health",- HealthFinding.biomarker_type,- HealthFinding.file_path,- requested=types,- include_unverified=include_unverified,- file_holds=file_holds,- hold_history=hold_history,- )- )- if file_path is not None:- q = q.where(HealthFinding.file_path == file_path)- if file_paths is not None:- q = q.where(HealthFinding.file_path.in_(list(file_paths)))- if dimension is not None:- # Older rows predate the split and carry a NULL dimension that homes- # under "defect"; fold those in so a defect filter never drops them.- if dimension == "defect":- q = q.where(or_(HealthFinding.dimension == "defect", HealthFinding.dimension.is_(None)))- else:- q = q.where(HealthFinding.dimension == dimension)- exact = [v.strip().lower() for v in (severity or "").split(",") if v.strip()]- if exact:- # An exact selection answers the same question the queue's chips do, so- # the two levels of the list agree on which findings a row holds.- q = q.where(HealthFinding.severity.in_(exact))- elif min_severity is not None:- # Severity order: low < medium < high < critical- order = {"low": 0, "medium": 1, "high": 2, "critical": 3}- threshold = order.get(min_severity, 0)- allowed = [k for k, v in order.items() if v >= threshold]- q = q.where(HealthFinding.severity.in_(allowed))- q = q.order_by(HealthFinding.health_impact.desc())- result = await session.execute(q)- kept = _filter_excluded_paths(- list(result.scalars().all()),- await health_exclude_spec(session, repository_id),- )- # A filter that drops some of a function's findings would misread its- # shape, so the tier then reads every open finding on the kept files.- narrowed = bool(types or exact or min_severity or dimension) or statuses != ["open"]- reasons = (- await health_finding_priorities(session, repository_id, kept)- if narrowed- else dict(zip((f.id for f in kept), finding_priorities(kept), strict=True))- )- # Test files go below production, then lower-priority below worth doing.- # Stable: each tier keeps the impact order. The cap applies after the tier.- tests = await get_test_file_paths(- session,- repository_id,- None if file_path is None and file_paths is None else {f.file_path for f in kept},- )- ordered = sorted(kept, key=lambda f: (f.file_path in tests, reasons[f.id] is not None))- return ordered if limit is None else ordered[:limit]---async def gated_health_counts(- session: AsyncSession,- repository_id: str,- *,- file_path: str | None = None,- include_unverified: bool = False,- hold_history: bool = True,-) -> dict[str, dict]:- """``{language or file hold: {count, reason}}`` over the open findings- :func:`get_health_findings` leaves out by default, so a list says why it- is shorter than the stored scores suggest."""- where = [- HealthFinding.repository_id == repository_id,- HealthFinding.status == "open",- HealthFinding.biomarker_type.not_in(excluded_types()),- ]- if file_path is not None:- where.append(HealthFinding.file_path == file_path)- return await gated_counts(- session,- "health",- HealthFinding,- *where,- kind_col=HealthFinding.biomarker_type,- include_unverified=include_unverified,- hold_history=hold_history,- )---async def health_finding_priorities(- session: AsyncSession, repository_id: str, findings: Sequence[HealthFinding]-) -> dict[str, LowPriority | None]:- """Each finding's ``worth`` reason by id, measured over every open,- shown finding on its file: a list filtered by marker, severity or status- still tiers a function by its whole shape."""- paths = sorted({f.file_path for f in findings})- peers: list[HealthFinding] = []- for i in range(0, len(paths), _BATCH_SIZE):- q = select(HealthFinding).where(- HealthFinding.repository_id == repository_id,- HealthFinding.status == "open",- HealthFinding.file_path.in_(paths[i : i + _BATCH_SIZE]),- HealthFinding.biomarker_type.not_in(excluded_types()),- )- peers.extend((await session.execute(q)).scalars().all())- known = {f.id for f in peers}- # A finding outside the open set (resolved, acknowledged) is measured with it.- peers.extend(f for f in findings if f.id not in known)- reasons = dict(zip((f.id for f in peers), finding_priorities(peers), strict=True))- return {f.id: reasons[f.id] for f in findings}---async def get_deduction_by_path(- session: AsyncSession,- repository_id: str,- *,- file_paths: list[str] | None = None,- status: str = "open",-) -> dict[str, float]:- """``{file_path: summed health_impact}`` over the repo's findings.-- The pre-clamp deduction magnitude, aggregated in SQL rather than by- hydrating every finding. Each stored ``health_impact`` is already the- applied (capped) value, so the sum equals the breakdown endpoint's- ``total_deduction``.-- Files with no findings are simply absent — a caller reading this as a- ranking key should treat a miss as 0.0 (a clean file has no magnitude).- """- totals: dict[str, float] = {}- base = select(- HealthFinding.file_path,- func.sum(HealthFinding.health_impact),- ).where(- HealthFinding.repository_id == repository_id,- HealthFinding.status == status,- )- # Batched like the other ``IN`` lookups here: SQLITE_MAX_VARIABLE_NUMBER is- # 999 before SQLite 3.32 and a module-scoped caller expands without bound.- chunks: list[list[str] | None] = (- [file_paths[i : i + _BATCH_SIZE] for i in range(0, len(file_paths), _BATCH_SIZE)]- if file_paths is not None- else [None]- )- for chunk in chunks:- q = base if chunk is None else base.where(HealthFinding.file_path.in_(chunk))- for path, total in (await session.execute(q.group_by(HealthFinding.file_path))).all():- totals[path] = float(total or 0.0)- return totals---async def get_health_metrics(- session: AsyncSession,- repository_id: str,- *,- file_paths: list[str] | None = None,-) -> list[HealthFileMetric]:- """Per-file health metrics, ordered worst-first.-- See :func:`sort_metrics_worst_first` for why the order is not a plain- ``ORDER BY score``.- """- q = select(HealthFileMetric).where(HealthFileMetric.repository_id == repository_id)- if file_paths is not None:- q = q.where(HealthFileMetric.file_path.in_(file_paths))- result = await session.execute(q)- rows = _filter_excluded_paths(- list(result.scalars().all()),- await health_exclude_spec(session, repository_id),- )- if len(rows) < 2:- # Nothing to order. Skips the aggregate for the single-file lookups- # (symbol drawer, file detail, one-plan refactoring view), which are- # per-request reads that would otherwise pay for a ranking they cannot- # use.- return rows- # Scoped to the caller's paths, not to ``rows``: a repo-wide read wants the- # single grouped scan, and the extra keys an exclude config leaves in the- # map are never looked up.- return sort_metrics_worst_first(- rows,- await get_deduction_by_path(session, repository_id, file_paths=file_paths),- )---async def get_headline_health(- session: AsyncSession, repository_id: str-) -> tuple[float | None, float | None]:- """``(average health, analysed share)``: the badge's figure and its band gate.-- The average is ``None`` if unmeasured; the share is ``analysed_share``.-- Numerically identical to ``get_health_summary()["average_health"]`` — same- weighting, same ``max(nloc, 1)`` floor, same 2dp rounding — for callers that- want *only* that number. The summary computes it as a by-product of building- twenty-odd KPIs, which costs a full ORM hydration of the metrics table, the- grouped deduction aggregate behind the worst-first ranking, the whole- findings table for the per-dimension counts, and the graph's language map- for perf coverage. The public badge endpoints want one float.-- Three columns and the same exclusion filter every other health read applies.- That filter is a compiled ``pathspec``, not something SQL can express, which- is why this is a narrow select reduced in Python rather than an ``AVG()``:- a SQL average would quietly include files the dashboard excludes, and the- badge would then disagree with the page it links to.- """- rows = _filter_excluded_paths(- list(- (- await session.execute(- select(- HealthFileMetric.file_path,- HealthFileMetric.score,- HealthFileMetric.nloc,- ).where(HealthFileMetric.repository_id == repository_id)- )- ).all()- ),- await health_exclude_spec(session, repository_id),- )- # Files with no score (no health dialect for their language) are skipped,- # so a repository of nothing else reads unmeasured, never 10.0.- scored, unanalysed = split_unscored(rows)- return _rounded(nloc_weighted_attr(scored, "score")), analysed_share(len(scored), unanalysed)---async def get_file_language_map(session: AsyncSession, repository_id: str) -> dict[str, str]:- """``{file_path: language_tag}`` for every file node in the graph."""- q = select(GraphNode.node_id, GraphNode.language).where(- GraphNode.repository_id == repository_id,- GraphNode.node_type == "file",- )- return {node_id: language for node_id, language in (await session.execute(q)).all()}---async def get_perf_coverage(session: AsyncSession, repository_id: str) -> PerfCoverage:- """How much of the analyzed code the performance pass was able to run on."""- # Imported lazily to keep the persistence layer free of an analysis-layer- # import at module load (and to avoid a circular import).- from ....analysis.health.perf.coverage import coverage_for_metrics-- metrics = await get_health_metrics(session, repository_id)- lang_by_path = await get_file_language_map(session, repository_id)- return coverage_for_metrics(metrics, lang_by_path)---def _rounded(value: float | None) -> float | None:- """Two-decimal wire value, passing ``None`` through as "not measured"."""- return round(value, 2) if value is not None else None---async def _open_finding_totals_rows(session: AsyncSession, repository_id: str) -> list[Any]:- """The open findings :func:`get_health_findings` returns, narrowed to the- columns the summary totals read.-- The summary sums and counts these; it never reads their tier, so it skips- the details column and the tiering pass over every open row. Impact order- is deliberate: per-file deductions are summed in the order the MCP- dashboard sums them, so both name the same worst file; ``id`` makes the- order total.- """- rows = await session.execute(- select(HealthFinding.file_path, HealthFinding.health_impact, HealthFinding.dimension)- .where(- HealthFinding.repository_id == repository_id,- HealthFinding.status == "open",- # The totals sum what the scores counted, file-held rows included.- shown(- "health", HealthFinding.biomarker_type, HealthFinding.file_path, file_holds=False- ),- )- .order_by(HealthFinding.health_impact.desc(), HealthFinding.id)- )- return _filter_excluded_paths(- plain_rows(rows), await health_exclude_spec(session, repository_id)- )---async def get_health_summary(- session: AsyncSession,- repository_id: str,- *,- metrics: list | None = None,- findings: list | None = None,-) -> dict:- """Aggregate KPIs over the per-file metrics table.-- *metrics* and *findings* let a caller that has already loaded those rows- hand them over instead of paying for a second full read. Callers doing more- than one thing with them — the overview payload builds these KPIs, the- severity breakdown and the defect-accuracy stat off the same two tables —- would otherwise pull each table twice per request.-- Both are expected to be exactly what this function would have read itself:- ``get_health_metrics(repository_id)`` and- ``get_health_findings(repository_id)``, i.e. every open row for the repo,- post-exclusion. Handing over a *filtered* subset would silently skew- ``open_findings`` and the per-dimension counts, which are repo headlines.- """- if metrics is None:- metrics = await get_health_metrics(session, repository_id)- # A file in a language health has no dialect for is stored unscored. It is- # counted apart and left out of every figure below.- metrics, unanalysed = split_unscored(metrics)- if not metrics:- return {- "file_count": 0,- "unanalysed_file_count": unanalysed,- "analysed_share": analysed_share(0, unanalysed),- "average_health": None,- "worst_performer_path": None,- "worst_performer_score": None,- "worst_test_path": None,- "worst_test_score": None,- "open_findings": 0,- "maintainability_average": None,- "performance_average": None,- "structure_average": None,- "history_average": None,- "maintainability_findings": 0,- "performance_findings": 0,- "performance_findings_density": None,- "performance_coverage_pct": None,- "performance_covered_files": 0,- "performance_analyzed_files": 0,- "performance_skipped_files": 0,- "performance_unsupported_languages": [],- "worst_performance_path": None,- "worst_performance_score": None,- }- avg = nloc_weighted_attr(metrics, "score")-- # The two co-surfaced pillars: the same NLOC weighting over their own- # columns, ``None`` when no row carries one so a surface reads "not- # measured" rather than a misleading 10.0.- maintainability_average = nloc_weighted_attr(metrics, "maintainability_score")- performance_average = nloc_weighted_attr(metrics, "performance_score")- perf_scored = [m for m in metrics if getattr(m, "performance_score", None) is not None]-- # Worst-performance file: the lowest per-file performance score, surfaced only- # when there is genuine risk (score < 10) so a clean repo shows no actionable- # target rather than a misleading "worst" at a perfect 10.0.- worst_performance_path: str | None = None- worst_performance_score: float | None = None- if perf_scored:- perf_worst = min(perf_scored, key=lambda r: r.performance_score)- if perf_worst.performance_score < 10.0:- worst_performance_path = perf_worst.file_path- worst_performance_score = round(perf_worst.performance_score, 2)-- if findings is None:- findings = await _open_finding_totals_rows(session, repository_id)-- # Ranked with the same key as ``get_health_metrics``, off the findings this- # function already holds, and in Fix first's scope: the file ``get_health``- # lists first, so a script or schema scoring lowest is not named. The worst- # test is named apart, so a weak test is not lost behind it.- worst = worst_kpis(metrics, deduction_by_path(findings))-- by_dim: dict[str, int] = {}- for finding in findings:- dim = finding.dimension or "defect"- by_dim[dim] = by_dim.get(dim, 0) + 1-- # Perf coverage: honest denominator for the score. On a repo that is mostly a- # perf-unsupported language the aggregate perf average is meaningless, so we- # surface how much of the analyzed code a detector actually ran on, plus a- # findings-per-10K-LOC density over the *covered* lines (not the whole repo).- from ....analysis.health.perf.coverage import coverage_for_metrics-- lang_by_path = await get_file_language_map(session, repository_id)- coverage = coverage_for_metrics(metrics, lang_by_path)- performance_findings = by_dim.get("performance", 0)- performance_findings_density: float | None = None- if coverage.covered_nloc > 0:- performance_findings_density = round(- 10000.0 * performance_findings / coverage.covered_nloc, 2- )- return {- "file_count": len(metrics),- "unanalysed_file_count": unanalysed,- "analysed_share": analysed_share(len(metrics), unanalysed),- "average_health": _rounded(avg),- **worst,- "open_findings": open_finding_count(findings),- "maintainability_average": _rounded(maintainability_average),- "performance_average": _rounded(performance_average),- # The headline's two halves, in deduction points. Both come off columns- # already on the rows in hand, so this costs no query — and without them- # the page can show a score falling without saying which half moved.- "structure_average": _rounded(nloc_weighted_attr(metrics, "structure_deduction")),- "history_average": _rounded(nloc_weighted_attr(metrics, "history_deduction")),- "maintainability_findings": by_dim.get("maintainability", 0),- "performance_findings": performance_findings,- "performance_findings_density": performance_findings_density,- "performance_coverage_pct": (coverage.pct_loc if coverage.analyzed_files else None),- "performance_covered_files": coverage.covered_files,- "performance_analyzed_files": coverage.analyzed_files,- "performance_skipped_files": coverage.skipped_files,- "performance_unsupported_languages": coverage.unsupported_languages,- "worst_performance_path": worst_performance_path,- "worst_performance_score": worst_performance_score,- }---async def update_health_finding_status(- session: AsyncSession,- finding_id: str,- status: str,-) -> HealthFinding | None:- f = await session.get(HealthFinding, finding_id)- if f is None:- return None- f.status = status- await session.flush()- return f---# Rolling history kept per repo. Older snapshots are deleted on insert.-# 50 entries gives Phase 4's `--trend` flag (last 10) plus the 5-back-# Declining-Health baseline plenty of headroom.-HEALTH_SNAPSHOT_RETENTION: int = 50--#: How many snapshots a *single file's* trend line reads. Every snapshot row-#: carries two whole-repo ``{path: float}`` maps, so a route that wants one-#: path's score series pays the entire retention window in TEXT to extract a-#: handful of floats. Twenty points is more than the decline heuristics need-#: (``DECLINE_LOOKBACK`` is 5) and more than the sparkline can usefully draw.-#:-#: One knock-on: ``FileTrend.snapshot_count`` is documented as the size of the-#: whole repo window, and on the two routes that pass this it becomes the size-#: of *this* window instead. Nothing reads that field off a per-file trend-#: today — the dashboard and the trend view read it off the repo-level routes,-#: which are unlimited and unchanged. Projecting one path's series in SQL would-#: keep the count true and drop the bytes further, but no query in this module-#: extracts from a JSON column and doing that portably across SQLite and-#: PostgreSQL is its own change.-FILE_TREND_SNAPSHOT_WINDOW: int = 20---async def _doc_drift_count(session: AsyncSession, repository_id: str) -> int | None:- """Stored drift findings; ``None`` when the drift pass has never run here."""- from .doc_drift import doc_drift_pass_ran-- count = await session.scalar(- select(func.count(DocDriftFinding.id)).where(- DocDriftFinding.repository_id == repository_id- )- )- if not count and not await doc_drift_pass_ran(session, repository_id):- return None- return int(count or 0)---async def save_health_snapshot(- session: AsyncSession,- repository_id: str,- *,- hotspot_health: float | None,- average_health: float,- worst_performer_path: str | None,- worst_performer_score: float | None,- per_file_scores: dict[str, float] | None = None,- per_file_deductions: dict[str, float] | None = None,- structure_average: float | None = None,- history_average: float | None = None,- production_average: float | None = None,- maintainability_average: float | None = None,- taken_at: datetime | None = None,-) -> HealthSnapshot:- """Append a snapshot; prune oldest rows past ``HEALTH_SNAPSHOT_RETENTION``.-- Returns the inserted row. Per-file scores are stored compactly as- ``{path: score}`` JSON (no per-finding detail — that lives in- ``HealthFinding`` rows; snapshots are a thin history layer).-- ``per_file_deductions`` is the same shape for the files whose score is held- at the floor, where the stored score has stopped carrying information.- Build both with ``trends.snapshot_file_maps`` rather than by hand: a repo- whose writers disagree gets a history that changes depth depending on which- command last wrote it.-- ``structure_average`` / ``history_average`` are ``average_health``'s two- halves in deduction points, so a later trend can name which one moved.-- The stored doc drift count is read here rather than passed in, so every- writer records it without a new argument; write drift before calling this.- """- snap = HealthSnapshot(- id=_new_uuid(),- repository_id=repository_id,- taken_at=taken_at or _now_utc(),- hotspot_health=float(hotspot_health) if hotspot_health is not None else None,- average_health=float(average_health),- worst_performer_path=worst_performer_path,- worst_performer_score=(- float(worst_performer_score) if worst_performer_score is not None else None- ),- per_file_scores_json=json.dumps(per_file_scores or {}, separators=(",", ":")),- per_file_deductions_json=json.dumps(per_file_deductions or {}, separators=(",", ":")),- structure_average=structure_average,- history_average=history_average,- production_average=production_average,- maintainability_average=maintainability_average,- doc_drift_count=await _doc_drift_count(session, repository_id),- )- session.add(snap)- await session.flush()-- # Prune older-than-retention rows. We keep the *N* newest by- # ``taken_at``; ties are broken by id (UUIDs are random but stable).- rows = await session.execute(- select(HealthSnapshot)- .where(HealthSnapshot.repository_id == repository_id)- .order_by(HealthSnapshot.taken_at.desc(), HealthSnapshot.id.desc())- )- history = list(rows.scalars().all())- if len(history) > HEALTH_SNAPSHOT_RETENTION:- for row in history[HEALTH_SNAPSHOT_RETENTION:]:- await session.delete(row)- await session.flush()- return snap---async def list_health_snapshots(- session: AsyncSession,- repository_id: str,- *,- limit: int | None = None,- file_maps: bool = True,-) -> list[HealthSnapshot]:- """Return snapshots **oldest-first** (the shape ``trends.diff_snapshots``- expects). Pass ``limit`` to cap the most recent N (still returned- oldest-first for stable iteration).-- ``file_maps=False`` defers both per-file maps, for a caller that reads the- scalars of every row and the maps of a few: it loads those with- ``session.refresh(row, ["per_file_scores_json"])``.-- ``limit`` is pushed into SQL rather than applied to the fetched list. Every- row carries ``per_file_scores_json`` and ``per_file_deductions_json``, both- whole-repo ``{path: float}`` maps, and the table keeps- ``HEALTH_SNAPSHOT_RETENTION`` (50) of them — so trimming in Python read the- entire history off disk to throw most of it away. Taking the newest N- descending and reversing gives the same list for a fraction of the bytes.- """- base = select(HealthSnapshot).where(HealthSnapshot.repository_id == repository_id)- if not file_maps:- base = base.options(- defer(HealthSnapshot.per_file_scores_json),- defer(HealthSnapshot.per_file_deductions_json),- )- if limit is not None:- newest_first = await session.execute(- base.order_by(HealthSnapshot.taken_at.desc(), HealthSnapshot.id.desc()).limit(limit)- )- return list(reversed(newest_first.scalars().all()))- q = base.order_by(HealthSnapshot.taken_at.asc(), HealthSnapshot.id.asc())- result = await session.execute(q)- return list(result.scalars().all())---class HealthSnapshotScalars(NamedTuple):- """One snapshot's numeric columns, with no per-file map behind them."""-- taken_at: datetime | None- average_health: float- hotspot_health: float | None---class HealthSnapshotHeadline(NamedTuple):- """The snapshot figures a dashboard header actually reads.-- ``recent`` is empty unless the caller asked for it, and is ordered- **oldest-first** to match ``list_health_snapshots`` — a trend line reads- left to right, and the newest row is ``recent[-1]``.- """-- hotspot_health: float | None- taken_at: datetime | None- snapshot_count: int- recent: tuple[HealthSnapshotScalars, ...] = ()---async def get_health_snapshot_headline(- session: AsyncSession,- repository_id: str,- *,- recent: int = 0,-) -> HealthSnapshotHeadline:- """Latest snapshot's ``hotspot_health`` / ``taken_at``, plus how many exist.-- ``list_health_snapshots`` hydrates whole entities, and every row carries a- ``per_file_scores_json`` blob sized by the repo's file count — on this- codebase that is ~186 KB each, 2.8 MB across the retained history and ~9 MB- at ``HEALTH_SNAPSHOT_RETENTION``. A caller that only needs scalars was- reading all of it to use a handful of floats.-- Pass ``recent=N`` for the newest N rows' scalars as well — a sparkline and a- delta-vs-previous both want a bounded window of numbers, not the history.- ``snapshot_count`` is always the **true** total, independent of ``recent``,- so a capped window can never be mistaken for the whole history.-- No JSON column is touched. Callers that genuinely need the per-file maps- (the trend routes, the file drawer's sparkline) should keep using- ``list_health_snapshots``; a caller that needs only their *sizes* wants- ``get_health_snapshot_file_counts``.- """- rows = (- await session.execute(- select(- HealthSnapshot.hotspot_health,- HealthSnapshot.taken_at,- HealthSnapshot.average_health,- )- .where(HealthSnapshot.repository_id == repository_id)- .order_by(HealthSnapshot.taken_at.asc(), HealthSnapshot.id.asc())- )- ).all()- if not rows:- return HealthSnapshotHeadline(None, None, 0)- hotspot_health, taken_at, _ = rows[-1]- window = rows[-recent:] if recent > 0 else []- return HealthSnapshotHeadline(- hotspot_health,- taken_at,- len(rows),- tuple(- HealthSnapshotScalars(r_taken_at, float(r_avg), r_hotspot)- for r_hotspot, r_taken_at, r_avg in window- ),- )---async def get_health_snapshot_file_counts(- session: AsyncSession,- repository_id: str,- *,- limit: int = 2,-) -> list[int]:- """How many files the newest *limit* snapshots scored, oldest-first.-- The only thing the overview's ``file_count`` delta wants out of- ``per_file_scores_json`` is its key count, and it compares two rows. Loading- the whole retained history to measure two of its maps read 2.8 MB to use- 375 KB of it.-- Ordering matches ``list_health_snapshots`` exactly, so "the newest two"- cannot mean different rows here than there.-- Anything that is not a ``{path: score}`` object counts 0 — unparseable, but- also a bare JSON array or string, which ``len()`` would happily measure into- a file count meaning nothing. The caller reads 0 as "unknown" and omits the- delta rather than publishing a number it cannot justify. This is deliberately- stricter than the ``len(json.loads(...))`` it replaced;- ``save_health_snapshot`` only ever writes an object, so it can only bite on- rows that did not come from it.- """- if limit <= 0:- return []- rows = (- await session.execute(- select(HealthSnapshot.per_file_scores_json)- .where(HealthSnapshot.repository_id == repository_id)- .order_by(HealthSnapshot.taken_at.desc(), HealthSnapshot.id.desc())- .limit(limit)- )- ).all()- counts: list[int] = []- for (blob,) in reversed(rows):- try:- parsed = json.loads(blob or "{}")- except (TypeError, ValueError):- counts.append(0)- continue- counts.append(len(parsed) if isinstance(parsed, dict) else 0)- return counts---async def upsert_health_findings(- session: AsyncSession,- repository_id: str,- findings: list[Any],- *,- file_paths: list[str],- dimension: str | None = None,-) -> None:- """Replace open findings **only for the given file paths**.-- Used by the incremental ``repowise update`` path so unchanged files- keep their findings instead of being wiped on every partial re-index.- """- if not file_paths:- return- predicates = [- HealthFinding.repository_id == repository_id,- HealthFinding.file_path.in_(file_paths),- ]- if dimension is not None:- predicates.append(HealthFinding.dimension == dimension)- existing = await session.execute(- select(HealthFinding).where(*predicates, HealthFinding.status == "open")- )- for row in existing.scalars().all():- await session.delete(row)- await session.flush()-- allowed = set(file_paths)- scoped = [- finding- for finding in findings- if (finding.file_path if hasattr(finding, "file_path") else finding.get("file_path"))- in allowed- and (- dimension is None- or (- getattr(finding, "dimension", None)- if hasattr(finding, "dimension")- else finding.get("dimension")- )- == dimension- )- ]- await _insert_keeping_triage(session, repository_id, scoped, predicates)---async def upsert_health_metrics(- session: AsyncSession,- repository_id: str,- metrics: list[Any],- *,- analyzed_commit: str | None = None,-) -> None:- """Upsert per-file metrics; unchanged files in the table stay put.-- Sibling of ``save_health_metrics`` (which delete-then-inserts the- whole repo). Used by the incremental analysis path so a partial- re-index never wipes metric rows for files that weren't touched.-- ``analyzed_commit`` stamps only the rows this call rewrites, which is the- point of recording it per row: after a partial pass the table honestly- reports two commits, and ``get_health``'s ``_meta`` says so rather than- claiming one scoring commit for the whole repo.- """- if not metrics:- return- paths = [m.file_path if hasattr(m, "file_path") else m["file_path"] for m in metrics]- existing = await session.execute(- select(HealthFileMetric).where(- HealthFileMetric.repository_id == repository_id,- HealthFileMetric.file_path.in_(paths),- )- )- by_path = {row.file_path: row for row in existing.scalars().all()}-- for m in metrics:- data = _health_metric_row_data(m) if hasattr(m, "file_path") else dict(m)- # Only when the caller knows the sha. An unconditional set would push a- # None over a sha already on the row, so a caller that simply does not- # track the commit would erase the stamp a caller that does had written.- if analyzed_commit is not None:- data.setdefault("analyzed_commit", analyzed_commit)-- row = by_path.get(data["file_path"])- if row is not None:- for k, v in data.items():- if k in ("id", "repository_id") or not hasattr(HealthFileMetric, k):- continue- setattr(row, k, v)- else:- session.add(- HealthFileMetric(- id=_new_uuid(),- repository_id=repository_id,- **{- k: v- for k, v in data.items()- if k not in ("id", "repository_id") and hasattr(HealthFileMetric, k)- },- )- )- await session.flush()diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/health/__init__.py b/packages/core/src/repowise/core/persistence/crud/analysis/health/__init__.pynew file mode 100644index 000000000..6296a498b--- /dev/null+++ b/packages/core/src/repowise/core/persistence/crud/analysis/health/__init__.py@@ -0,0 +1,95 @@+"""CRUD operations for code-health findings, metrics, and snapshots+(repowise persistence layer).++Split by responsibility into ``findings``, ``metrics``, ``snapshots``,+``summary`` and ``exclude``. Every name the former single module defined is+re-exported here, private helpers included (``noqa: F401``, kept out of+``__all__``), so ``from ...crud.analysis.health import X`` is unaffected.+"""++from __future__ import annotations++from .exclude import (+ _filter_excluded_paths, # noqa: F401+ health_exclude_spec,+)+from .findings import (+ _NOT_REFRESHED, # noqa: F401+ _health_finding_row_kwargs, # noqa: F401+ _insert_keeping_triage, # noqa: F401+ gated_health_counts,+ get_deduction_by_path,+ get_health_findings,+ health_finding_priorities,+ open_finding_count,+ replace_governance_findings,+ save_health_findings,+ update_health_finding_status,+ upsert_health_findings,+)+from .metrics import (+ _health_metric_row_data, # noqa: F401+ _opt, # noqa: F401+ backfill_is_test,+ backfill_module_attribution,+ clear_unanalysed_scores,+ get_file_language_map,+ get_health_metrics,+ get_perf_coverage,+ get_scored_file_paths,+ prune_unscored_health_rows,+ save_health_metrics,+ sort_metrics_worst_first,+ upsert_health_metrics,+)+from .snapshots import (+ FILE_TREND_SNAPSHOT_WINDOW,+ HEALTH_SNAPSHOT_RETENTION,+ HealthSnapshotHeadline,+ HealthSnapshotScalars,+ _doc_drift_count, # noqa: F401+ get_health_snapshot_file_counts,+ get_health_snapshot_headline,+ list_health_snapshots,+ save_health_snapshot,+)+from .summary import (+ _open_finding_totals_rows, # noqa: F401+ _rounded, # noqa: F401+ get_headline_health,+ get_health_summary,+)++__all__ = [+ "FILE_TREND_SNAPSHOT_WINDOW",+ "HEALTH_SNAPSHOT_RETENTION",+ "HealthSnapshotHeadline",+ "HealthSnapshotScalars",+ "backfill_is_test",+ "backfill_module_attribution",+ "clear_unanalysed_scores",+ "gated_health_counts",+ "get_deduction_by_path",+ "get_file_language_map",+ "get_headline_health",+ "get_health_findings",+ "get_health_metrics",+ "get_health_snapshot_file_counts",+ "get_health_snapshot_headline",+ "get_health_summary",+ "get_perf_coverage",+ "get_scored_file_paths",+ "health_exclude_spec",+ "health_finding_priorities",+ "list_health_snapshots",+ "open_finding_count",+ "prune_unscored_health_rows",+ "replace_governance_findings",+ "save_health_findings",+ "save_health_metrics",+ "save_health_snapshot",+ "sort_metrics_worst_first",+ "update_health_finding_status",+ "upsert_health_findings",+ "upsert_health_metrics",+]diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/health/exclude.py b/packages/core/src/repowise/core/persistence/crud/analysis/health/exclude.pynew file mode 100644index 000000000..31a7d29bc--- /dev/null+++ b/packages/core/src/repowise/core/persistence/crud/analysis/health/exclude.py@@ -0,0 +1,67 @@+"""The exclude patterns every health read narrows its files by."""++from __future__ import annotations++import json+from pathlib import Path+from typing import Any++from sqlalchemy.ext.asyncio import AsyncSession++from ....models import Repository+++async def health_exclude_spec(+ session: AsyncSession, repository_id: str, repo_path: Path | str | None = None+) -> Any:+ """The exclude patterns every health surface narrows its files by.++ The repository's settings and ``exclude_patterns`` only. Not the gitignore+ stack: ingestion keeps a file git tracks even when an ignore rule matches+ it, so a stored row under such a rule is a real file of the repository.+ ``repo_path`` is where to read the config when the caller serves a+ checkout other than the stored ``local_path``.+ """+ repo = await session.get(Repository, repository_id)+ if repo is None:+ return None++ patterns: list[str] = []+ seen: set[str] = set()++ def _add(values: Any) -> None:+ if not isinstance(values, list):+ return+ for value in values:+ if isinstance(value, str) and value not in seen:+ seen.add(value)+ patterns.append(value)++ try:+ settings = json.loads(getattr(repo, "settings_json", "") or "{}")+ if isinstance(settings, dict):+ _add(settings.get("exclude_patterns"))+ except (TypeError, ValueError):+ pass++ try:+ from repowise.core.repo_config import load_repo_config++ cfg = load_repo_config(Path(repo_path or repo.local_path))+ if isinstance(cfg, dict):+ _add(cfg.get("exclude_patterns"))+ except Exception:+ pass++ if not patterns:+ return None++ import pathspec++ return pathspec.PathSpec.from_lines("gitwildmatch", patterns)+++def _filter_excluded_paths(rows: list[Any], spec: Any) -> list[Any]:+ if spec is None:+ return rows+ return [row for row in rows if not spec.match_file(getattr(row, "file_path", ""))]diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/health/findings.py b/packages/core/src/repowise/core/persistence/crud/analysis/health/findings.pynew file mode 100644index 000000000..ac10e5c58--- /dev/null+++ b/packages/core/src/repowise/core/persistence/crud/analysis/health/findings.py@@ -0,0 +1,495 @@+"""Health findings: the writers that keep a person's triage, and the reads+every findings surface narrows and tiers through."""++from __future__ import annotations++import json+from collections.abc import Iterable, Sequence+from datetime import datetime+from typing import Any++from sqlalchemy import func, or_, select+from sqlalchemy.ext.asyncio import AsyncSession++from .....analysis.finding_registry import excluded_types+from .....analysis.health.finding_identity import (+ finding_public_id,+ legacy_finding_public_id,+)+from .....analysis.health.governance import GOVERNANCE_BIOMARKERS+from .....analysis.health.rows import detail_map+from .....analysis.health.scoring import ADVISORY_DIMENSION+from .....analysis.health.worth import LowPriority, finding_priorities+from ....models import HealthFinding, _new_uuid, _now_utc+from ..._shared import _BATCH_SIZE+from ...graph import get_test_file_paths+from ..shown import gated_counts, shown+from .exclude import _filter_excluded_paths, health_exclude_spec+++def _health_finding_row_kwargs(finding: Any, repository_id: str) -> dict:+ """Normalize an analyzer dataclass or a plain dict into ORM row kwargs.++ All three writers land here, so a column added to the row is written by+ every path or by none. ``public_id`` is stamped here because this is the+ one place every persisted finding passes through.+ """+ if hasattr(finding, "biomarker_type"):+ severity = finding.severity+ data = {+ "file_path": finding.file_path,+ "biomarker_type": finding.biomarker_type,+ "severity": str(severity.value) if hasattr(severity, "value") else str(severity),+ "function_name": finding.function_name,+ "line_start": finding.line_start,+ "line_end": finding.line_end,+ "details_json": json.dumps(finding.details or {}),+ "health_impact": float(finding.health_impact),+ "reason": finding.reason or "",+ "dimension": getattr(finding, "dimension", None) or "defect",+ }+ else:+ data = dict(finding)+ if "details" in data:+ data["details_json"] = json.dumps(data.pop("details") or {})+ data.setdefault("public_id", finding_public_id(finding))+ if data.get("dimension") == "performance":+ # Present before the finalizer runs because the analyzer stamps it into+ # ``details``; the finalizer restates it from authoritative stored rows.+ data.setdefault("opportunity_id", detail_map(finding).get("opportunity_id"))+ return {+ "id": _new_uuid(),+ "repository_id": repository_id,+ **{+ k: v+ for k, v in data.items()+ if k not in ("id", "repository_id") and hasattr(HealthFinding, k)+ },+ }+++_NOT_REFRESHED = frozenset({"id", "repository_id", "status", "created_at"})+++async def _triaged_by_public_id(+ session: AsyncSession, scope: list[Any]+) -> dict[str, list[HealthFinding]]:+ """The triaged rows in *scope* by public id, most recently updated first."""+ triaged: dict[str, list[HealthFinding]] = {}+ rows = await session.execute(+ select(HealthFinding)+ .where(*scope, HealthFinding.status != "open", HealthFinding.public_id.is_not(None))+ .order_by(HealthFinding.updated_at.desc())+ )+ for row in rows.scalars().all():+ triaged.setdefault(row.public_id, []).append(row)+ return triaged+++def _triaged_rows_for(+ triaged: dict[str, list[HealthFinding]], values: dict, finding: Any+) -> list[HealthFinding]:+ """The triaged rows *finding* folds into: by its public id, else its legacy one."""+ if not triaged:+ return []+ return (+ triaged.get(values["public_id"]) or triaged.get(legacy_finding_public_id(finding)) or []+ )+++async def _fold_into_triaged(+ session: AsyncSession,+ kept: HealthFinding,+ extra: list[HealthFinding],+ values: dict,+ now: datetime,+) -> None:+ """Refresh *kept* from *values*, keeping its triage; drop the *extra* rows."""+ for row in extra:+ await session.delete(row)+ for name, value in values.items():+ if name not in _NOT_REFRESHED:+ setattr(kept, name, value)+ if kept.status == "resolved":+ kept.status = "open"+ kept.updated_at = now+++async def _insert_keeping_triage(+ session: AsyncSession,+ repository_id: str,+ findings: list[Any],+ scope: list[Any],+) -> None:+ """Insert *findings*, keeping the triage a person recorded on any of them.++ Callers delete the open rows in *scope* first. A finding whose public id+ matches a triaged row in *scope* is folded into that row: its detection+ fields are refreshed and ``acknowledged`` / ``false_positive`` stand, while+ ``resolved`` reopens because the finding said to be fixed is still there.+ Extra triaged rows sharing that id are deleted. Every other finding, a+ second one on an already claimed id included, is inserted open.+ """+ triaged = await _triaged_by_public_id(session, scope)+ now = _now_utc()+ claimed: set[str] = set()+ for i in range(0, len(findings), _BATCH_SIZE):+ for f in findings[i : i + _BATCH_SIZE]:+ values = _health_finding_row_kwargs(f, repository_id)+ kept, *extra = _triaged_rows_for(triaged, values, f) or [None]+ if kept is None or kept.id in claimed:+ # A second finding on a claimed id is inserted open: two+ # findings colliding on one id must not lose either.+ session.add(HealthFinding(**values))+ continue+ claimed.add(kept.id)+ await _fold_into_triaged(session, kept, extra, values, now)+ await session.flush()+++async def save_health_findings(+ session: AsyncSession,+ repository_id: str,+ findings: list[Any],+) -> None:+ """Replace open health findings for *repository_id* with *findings*.++ Delete-then-insert over the open rows; triaged rows carry over by public id+ (``_insert_keeping_triage``). Accepts either ``HealthFindingData``+ dataclasses or plain dicts.+ """+ scope = [HealthFinding.repository_id == repository_id]+ existing = await session.execute(+ select(HealthFinding).where(*scope, HealthFinding.status == "open")+ )+ for row in existing.scalars().all():+ await session.delete(row)+ await session.flush()++ await _insert_keeping_triage(session, repository_id, findings, scope)+++async def replace_governance_findings(+ session: AsyncSession,+ repository_id: str,+ findings: list[Any],+) -> None:+ """Idempotent additive write of governance-layer health findings.++ Deletes the open ``health_findings`` rows whose ``biomarker_type``+ is one of ``ungoverned_hotspot``, ``stale_governance``, or+ ``contradictory_decision`` for *repository_id*, then inserts the new+ *findings* in batches, keeping triage by public id like the other writers.++ This function deliberately does **not** recompute ``HealthFileMetric.score``+ — that pass has already completed in the upstream health-analysis phase.+ Governance findings surface through the findings layer (``get_risk``+ ``top_biomarkers``, ``get_context`` health block) rather than the numeric+ score. A second score-recomputation pass would require re-loading the full+ per-file results table; the conservative choice is to leave scores as-is+ and let findings carry the governance signal.++ Composable with ``save_health_findings``: the delete is scoped to only+ the three governance biomarker types, so structural findings written by+ ``save_health_findings`` are untouched.++ Accepts ``HealthFindingData`` dataclasses or plain dicts (same protocol+ as ``save_health_findings``).+ """+ # Delete existing open governance findings for this repo only.+ scope = [+ HealthFinding.repository_id == repository_id,+ HealthFinding.biomarker_type.in_(list(GOVERNANCE_BIOMARKERS)),+ ]+ existing = await session.execute(+ select(HealthFinding).where(*scope, HealthFinding.status == "open")+ )+ for row in existing.scalars().all():+ await session.delete(row)+ await session.flush()++ await _insert_keeping_triage(session, repository_id, findings, scope)+++async def upsert_health_findings(+ session: AsyncSession,+ repository_id: str,+ findings: list[Any],+ *,+ file_paths: list[str],+ dimension: str | None = None,+) -> None:+ """Replace open findings **only for the given file paths**.++ Used by the incremental ``repowise update`` path so unchanged files+ keep their findings instead of being wiped on every partial re-index.+ """+ if not file_paths:+ return+ predicates = [+ HealthFinding.repository_id == repository_id,+ HealthFinding.file_path.in_(file_paths),+ ]+ if dimension is not None:+ predicates.append(HealthFinding.dimension == dimension)+ existing = await session.execute(+ select(HealthFinding).where(*predicates, HealthFinding.status == "open")+ )+ for row in existing.scalars().all():+ await session.delete(row)+ await session.flush()++ allowed = set(file_paths)+ scoped = [+ finding+ for finding in findings+ if (finding.file_path if hasattr(finding, "file_path") else finding.get("file_path"))+ in allowed+ and (+ dimension is None+ or (+ getattr(finding, "dimension", None)+ if hasattr(finding, "dimension")+ else finding.get("dimension")+ )+ == dimension+ )+ ]+ await _insert_keeping_triage(session, repository_id, scoped, predicates)+++async def update_health_finding_status(+ session: AsyncSession,+ finding_id: str,+ status: str,+) -> HealthFinding | None:+ f = await session.get(HealthFinding, finding_id)+ if f is None:+ return None+ f.status = status+ await session.flush()+ return f+++def open_finding_count(findings: Iterable[Any]) -> int:+ """The open findings total every health headline prints.++ Advisory findings carry a zero health impact, so counting them would grow+ the headline without anything having got worse.+ """+ return sum(1 for f in findings if getattr(f, "dimension", None) != ADVISORY_DIMENSION)+++async def get_health_findings(+ session: AsyncSession,+ repository_id: str,+ *,+ biomarker_type: str | None = None,+ min_severity: str | None = None,+ severity: str | None = None,+ file_path: str | None = None,+ file_paths: Sequence[str] | None = None,+ dimension: str | None = None,+ exclude_dimensions: tuple[str, ...] | None = None,+ status: str = "open",+ include_withheld: bool = False,+ include_unverified: bool = False,+ file_holds: bool = True,+ hold_history: bool = True,+ limit: int | None = None,+) -> list[HealthFinding]:+ """Findings for one repository: production ahead of test files, worth doing+ first ahead of lower-priority ones (``worth.finding_priorities``), each part+ ordered by health impact.++ Finding types the registry withholds (``finding_registry``) are left out,+ so every surface built on this read shows only what has earned a place; a+ provisional type named in ``biomarker_type`` is an explicit request and is+ returned. Files of a language the registry gates for health findings are+ left out too, unless ``include_unverified`` (which also opts into every+ provisional type). ``include_withheld`` is for analysis that must see every+ row. ``file_holds=False`` keeps the findings held back by their file+ (vendored, generated, history on a test) for a reader that sums scores or+ KPIs, which count them. ``hold_history=False`` keeps history markers on+ production files for a view that treats history itself.++ ``exclude_dimensions`` is how a general queue keeps a dimension out of a+ ranking it does not share units with. It is ignored when ``dimension``+ names one explicitly, so asking for a dimension always returns it.++ ``severity`` is an exact comma-separated selection and wins over the+ ``min_severity`` threshold when both are given.++ ``status`` defaults to open work. It also accepts a comma-separated list of+ ``open`` / ``acknowledged`` / ``resolved`` / ``false_positive``, or ``all``+ to drop the filter, so a triage surface can show what it has already+ reviewed without a second read.++ ``file_paths`` scopes to a set of files in one read; an empty sequence+ matches nothing. ``limit`` caps the rows returned, in that order.+ """+ q = select(HealthFinding).where(HealthFinding.repository_id == repository_id)+ statuses = [s.strip() for s in status.split(",") if s.strip()]+ if "all" not in statuses:+ q = q.where(HealthFinding.status.in_(statuses or ["open"]))+ if dimension is None and exclude_dimensions:+ q = q.where(+ or_(+ HealthFinding.dimension.is_(None),+ HealthFinding.dimension.not_in(list(exclude_dimensions)),+ )+ )+ # Accept a comma-separated list so a caller can pull several biomarker+ # types in one request (e.g. the function-level + coupling panels).+ # A single value with no comma still matches exactly (``IN`` of one).+ types = [t.strip() for t in (biomarker_type or "").split(",") if t.strip()]+ if types:+ q = q.where(HealthFinding.biomarker_type.in_(types))+ if not include_withheld:+ q = q.where(+ shown(+ "health",+ HealthFinding.biomarker_type,+ HealthFinding.file_path,+ requested=types,+ include_unverified=include_unverified,+ file_holds=file_holds,+ hold_history=hold_history,+ )+ )+ if file_path is not None:+ q = q.where(HealthFinding.file_path == file_path)+ if file_paths is not None:+ q = q.where(HealthFinding.file_path.in_(list(file_paths)))+ if dimension is not None:+ # Older rows predate the split and carry a NULL dimension that homes+ # under "defect"; fold those in so a defect filter never drops them.+ if dimension == "defect":+ q = q.where(or_(HealthFinding.dimension == "defect", HealthFinding.dimension.is_(None)))+ else:+ q = q.where(HealthFinding.dimension == dimension)+ exact = [v.strip().lower() for v in (severity or "").split(",") if v.strip()]+ if exact:+ # An exact selection answers the same question the queue's chips do, so+ # the two levels of the list agree on which findings a row holds.+ q = q.where(HealthFinding.severity.in_(exact))+ elif min_severity is not None:+ # Severity order: low < medium < high < critical+ order = {"low": 0, "medium": 1, "high": 2, "critical": 3}+ threshold = order.get(min_severity, 0)+ allowed = [k for k, v in order.items() if v >= threshold]+ q = q.where(HealthFinding.severity.in_(allowed))+ q = q.order_by(HealthFinding.health_impact.desc())+ result = await session.execute(q)+ kept = _filter_excluded_paths(+ list(result.scalars().all()),+ await health_exclude_spec(session, repository_id),+ )+ # A filter that drops some of a function's findings would misread its+ # shape, so the tier then reads every open finding on the kept files.+ narrowed = bool(types or exact or min_severity or dimension) or statuses != ["open"]+ reasons = (+ await health_finding_priorities(session, repository_id, kept)+ if narrowed+ else dict(zip((f.id for f in kept), finding_priorities(kept), strict=True))+ )+ # Test files go below production, then lower-priority below worth doing.+ # Stable: each tier keeps the impact order. The cap applies after the tier.+ tests = await get_test_file_paths(+ session,+ repository_id,+ None if file_path is None and file_paths is None else {f.file_path for f in kept},+ )+ ordered = sorted(kept, key=lambda f: (f.file_path in tests, reasons[f.id] is not None))+ return ordered if limit is None else ordered[:limit]+++async def gated_health_counts(+ session: AsyncSession,+ repository_id: str,+ *,+ file_path: str | None = None,+ include_unverified: bool = False,+ hold_history: bool = True,+) -> dict[str, dict]:+ """``{language or file hold: {count, reason}}`` over the open findings+ :func:`get_health_findings` leaves out by default, so a list says why it+ is shorter than the stored scores suggest."""+ where = [+ HealthFinding.repository_id == repository_id,+ HealthFinding.status == "open",+ HealthFinding.biomarker_type.not_in(excluded_types()),+ ]+ if file_path is not None:+ where.append(HealthFinding.file_path == file_path)+ return await gated_counts(+ session,+ "health",+ HealthFinding,+ *where,+ kind_col=HealthFinding.biomarker_type,+ include_unverified=include_unverified,+ hold_history=hold_history,+ )+++async def health_finding_priorities(+ session: AsyncSession, repository_id: str, findings: Sequence[HealthFinding]+) -> dict[str, LowPriority | None]:+ """Each finding's ``worth`` reason by id, measured over every open,+ shown finding on its file: a list filtered by marker, severity or status+ still tiers a function by its whole shape."""+ paths = sorted({f.file_path for f in findings})+ peers: list[HealthFinding] = []+ for i in range(0, len(paths), _BATCH_SIZE):+ q = select(HealthFinding).where(+ HealthFinding.repository_id == repository_id,+ HealthFinding.status == "open",+ HealthFinding.file_path.in_(paths[i : i + _BATCH_SIZE]),+ HealthFinding.biomarker_type.not_in(excluded_types()),+ )+ peers.extend((await session.execute(q)).scalars().all())+ known = {f.id for f in peers}+ # A finding outside the open set (resolved, acknowledged) is measured with it.+ peers.extend(f for f in findings if f.id not in known)+ reasons = dict(zip((f.id for f in peers), finding_priorities(peers), strict=True))+ return {f.id: reasons[f.id] for f in findings}+++async def get_deduction_by_path(+ session: AsyncSession,+ repository_id: str,+ *,+ file_paths: list[str] | None = None,+ status: str = "open",+) -> dict[str, float]:+ """``{file_path: summed health_impact}`` over the repo's findings.++ The pre-clamp deduction magnitude, aggregated in SQL rather than by+ hydrating every finding. Each stored ``health_impact`` is already the+ applied (capped) value, so the sum equals the breakdown endpoint's+ ``total_deduction``.++ Files with no findings are simply absent — a caller reading this as a+ ranking key should treat a miss as 0.0 (a clean file has no magnitude).+ """+ totals: dict[str, float] = {}+ base = select(+ HealthFinding.file_path,+ func.sum(HealthFinding.health_impact),+ ).where(+ HealthFinding.repository_id == repository_id,+ HealthFinding.status == status,+ )+ # Batched like the other ``IN`` lookups here: SQLITE_MAX_VARIABLE_NUMBER is+ # 999 before SQLite 3.32 and a module-scoped caller expands without bound.+ chunks: list[list[str] | None] = (+ [file_paths[i : i + _BATCH_SIZE] for i in range(0, len(file_paths), _BATCH_SIZE)]+ if file_paths is not None+ else [None]+ )+ for chunk in chunks:+ q = base if chunk is None else base.where(HealthFinding.file_path.in_(chunk))+ for path, total in (await session.execute(q.group_by(HealthFinding.file_path))).all():+ totals[path] = float(total or 0.0)+ return totalsdiff --git a/packages/core/src/repowise/core/persistence/crud/analysis/health/metrics.py b/packages/core/src/repowise/core/persistence/crud/analysis/health/metrics.pynew file mode 100644index 000000000..4646c8566--- /dev/null+++ b/packages/core/src/repowise/core/persistence/crud/analysis/health/metrics.py@@ -0,0 +1,345 @@+"""Per-file health metrics: the writers, the in-place repairs an update runs+over stored rows, and the worst-first read."""++from __future__ import annotations++from typing import TYPE_CHECKING, Any++from sqlalchemy import select+from sqlalchemy.ext.asyncio import AsyncSession++if TYPE_CHECKING:+ from .....analysis.health.perf.coverage import PerfCoverage++from .....analysis.health.complexity.languages import has_health_dialect++# The comparator is pure and lives with the health read models; only the SQL+# that feeds it belongs here. Re-imported rather than moved out of reach: the+# crud surface is where the MCP tool and the tests already read it from.+from .....analysis.health.ranking import sort_metrics_worst_first+from .....analysis.health.scope import scores_language+from .....analysis.health.scoring import SCORE_FIELDS+from .....test_paths import is_test_related_path+from ....models import GraphNode, HealthFileMetric, HealthFinding, _new_uuid+from ..._shared import _BATCH_SIZE+from .exclude import _filter_excluded_paths, health_exclude_spec+from .findings import get_deduction_by_path+++def _opt(cast: Any, value: Any) -> Any:+ """*value* through *cast*, keeping ``None`` (a file health never walked)."""+ return None if value is None else cast(value)+++def _health_metric_row_data(metric: Any) -> dict:+ """One metric dataclass as column values. Both writers go through here."""+ return {+ "file_path": metric.file_path,+ "score": _opt(float, metric.score),+ "max_ccn": _opt(int, metric.max_ccn),+ "max_nesting": _opt(int, metric.max_nesting),+ "nloc": int(metric.nloc),+ "duplication_pct": metric.duplication_pct,+ "has_test_file": bool(metric.has_test_file),+ "line_coverage_pct": metric.line_coverage_pct,+ "branch_coverage_pct": metric.branch_coverage_pct,+ "module": metric.module,+ "defect_score": getattr(metric, "defect_score", None),+ "maintainability_score": getattr(metric, "maintainability_score", None),+ "performance_score": getattr(metric, "performance_score", None),+ "structure_deduction": getattr(metric, "structure_deduction", None),+ "history_deduction": getattr(metric, "history_deduction", None),+ "is_test": bool(getattr(metric, "is_test", False)),+ "code_origin": getattr(metric, "code_origin", None),+ }+++async def save_health_metrics(+ session: AsyncSession,+ repository_id: str,+ metrics: list[Any],+ *,+ analyzed_commit: str | None = None,+) -> None:+ """Replace per-file health metrics for *repository_id*.++ Delete-then-insert (matches the findings writer). The unique+ constraint on (repository_id, file_path) means we cannot leave+ stale rows around without an upsert dance — delete-and-insert keeps+ it simple and aligns with how dead-code findings are written.++ ``analyzed_commit`` stamps every written row with the commit these scores+ were computed against — the same pattern as ``save_coverage_files``'+ ``ingested_commit_sha``. Health runs as its own pass and can lag the index,+ so ``Repository.head_commit`` cannot answer "how old is this score". Omitted+ → NULL, which reads as "not recorded" rather than "current".+ """+ existing = await session.execute(+ select(HealthFileMetric).where(HealthFileMetric.repository_id == repository_id)+ )+ for row in existing.scalars().all():+ await session.delete(row)+ await session.flush()++ for i in range(0, len(metrics), _BATCH_SIZE):+ batch = metrics[i : i + _BATCH_SIZE]+ for m in batch:+ data = _health_metric_row_data(m) if hasattr(m, "file_path") else dict(m)+ # After the dict-passthrough branch so an explicit per-row value in a+ # raw dict still wins; the sha is a property of the pass, not the row.+ if analyzed_commit is not None:+ data.setdefault("analyzed_commit", analyzed_commit)++ session.add(+ HealthFileMetric(+ id=_new_uuid(),+ repository_id=repository_id,+ **{+ k: v+ for k, v in data.items()+ if k not in ("id", "repository_id") and hasattr(HealthFileMetric, k)+ },+ )+ )+ await session.flush()+++async def upsert_health_metrics(+ session: AsyncSession,+ repository_id: str,+ metrics: list[Any],+ *,+ analyzed_commit: str | None = None,+) -> None:+ """Upsert per-file metrics; unchanged files in the table stay put.++ Sibling of ``save_health_metrics`` (which delete-then-inserts the+ whole repo). Used by the incremental analysis path so a partial+ re-index never wipes metric rows for files that weren't touched.++ ``analyzed_commit`` stamps only the rows this call rewrites, which is the+ point of recording it per row: after a partial pass the table honestly+ reports two commits, and ``get_health``'s ``_meta`` says so rather than+ claiming one scoring commit for the whole repo.+ """+ if not metrics:+ return+ paths = [m.file_path if hasattr(m, "file_path") else m["file_path"] for m in metrics]+ existing = await session.execute(+ select(HealthFileMetric).where(+ HealthFileMetric.repository_id == repository_id,+ HealthFileMetric.file_path.in_(paths),+ )+ )+ by_path = {row.file_path: row for row in existing.scalars().all()}++ for m in metrics:+ data = _health_metric_row_data(m) if hasattr(m, "file_path") else dict(m)+ # Only when the caller knows the sha. An unconditional set would push a+ # None over a sha already on the row, so a caller that simply does not+ # track the commit would erase the stamp a caller that does had written.+ if analyzed_commit is not None:+ data.setdefault("analyzed_commit", analyzed_commit)++ row = by_path.get(data["file_path"])+ if row is not None:+ for k, v in data.items():+ if k in ("id", "repository_id") or not hasattr(HealthFileMetric, k):+ continue+ setattr(row, k, v)+ else:+ session.add(+ HealthFileMetric(+ id=_new_uuid(),+ repository_id=repository_id,+ **{+ k: v+ for k, v in data.items()+ if k not in ("id", "repository_id") and hasattr(HealthFileMetric, k)+ },+ )+ )+ await session.flush()+++async def get_scored_file_paths(session: AsyncSession, repository_id: str) -> set[str]:+ """The files health currently scores, read off the stored metric rows."""+ q = select(HealthFileMetric.file_path).where(+ HealthFileMetric.repository_id == repository_id+ )+ return {path for (path,) in (await session.execute(q)).all()}+++async def backfill_is_test(session: AsyncSession, repository_id: str) -> int:+ """Stamp ``is_test`` on rows written before the column existed.++ The answer comes from the path, not from a score, so an existing store gets+ it on the next update instead of waiting for a re-index. Without this a+ ``scope=production`` request on an un-rescored store would quietly answer+ with the whole repository. Returns the number of rows filled.+ """+ rows = (+ await session.execute(+ select(HealthFileMetric).where(+ HealthFileMetric.repository_id == repository_id,+ HealthFileMetric.is_test.is_(None),+ )+ )+ ).scalars().all()+ if not rows:+ return 0+ languages = await get_file_language_map(session, repository_id)+ for row in rows:+ row.is_test = is_test_related_path(row.file_path, languages.get(row.file_path))+ await session.flush()+ return len(rows)+++async def prune_unscored_health_rows(session: AsyncSession, repository_id: str) -> int:+ """Drop metrics and findings for files health no longer scores.++ A full index rewrites the whole population and needs nothing here, but an+ update only touches the files that changed, so prose and configuration rows+ written by an older version would otherwise sit in the average forever.+ Files with no graph node are left alone: no language is not the same answer+ as a language health does not score. Returns the number of rows removed,+ which is zero on every update after the first.+ """+ languages = await get_file_language_map(session, repository_id)+ stale = [path for path, language in languages.items() if not scores_language(language)]+ if not stale:+ return 0+ removed = 0+ for i in range(0, len(stale), _BATCH_SIZE):+ batch = stale[i : i + _BATCH_SIZE]+ for model in (HealthFileMetric, HealthFinding):+ rows = await session.execute(+ select(model).where(+ model.repository_id == repository_id,+ model.file_path.in_(batch),+ )+ )+ for row in rows.scalars().all():+ await session.delete(row)+ removed += 1+ await session.flush()+ return removed+++async def clear_unanalysed_scores(session: AsyncSession, repository_id: str) -> int:+ """Drop the numbers stored for files in a language health has no dialect for.++ A store written before such files were left unscored holds a 10.0 and a+ max_ccn of 1 for each, which every average would keep counting until a full+ rescore. The answer comes from the language alone, so an update fixes it in+ place, git history or not. Files with no graph node are left alone, as in+ ``prune_unscored_health_rows``. Returns the number of rows cleared.+ """+ languages = await get_file_language_map(session, repository_id)+ paths = [p for p, lang in languages.items() if lang and not has_health_dialect(lang)]+ cleared = 0+ for i in range(0, len(paths), _BATCH_SIZE):+ rows = await session.execute(+ select(HealthFileMetric).where(+ HealthFileMetric.repository_id == repository_id,+ HealthFileMetric.file_path.in_(paths[i : i + _BATCH_SIZE]),+ HealthFileMetric.score.is_not(None),+ )+ )+ for row in rows.scalars().all():+ for name in (*SCORE_FIELDS, "max_ccn", "max_nesting"):+ setattr(row, name, None)+ cleared += 1+ await session.flush()+ return cleared+++async def backfill_module_attribution(+ session: AsyncSession,+ repository_id: str,+ package_roots: set[str],+) -> int:+ """Recompute every metric row's ``module`` from the repo layout.++ Returns the number of rows changed, so a caller can stay silent when there+ was nothing to correct.++ ``module`` is a pure function of ``(file_path, package_roots)`` — no parse,+ no symbols, no git, no model — so correcting it never needs the rows+ rewritten by a re-score, let alone a re-index. That is the whole point:+ a directory label must not cost users an indexing run.++ Idempotent by construction, and it converges with the indexer rather than+ fighting it: both call the same :func:`module_for` over the same+ disk-scanned roots, so a full index writing a *different* value would mean+ the two disagree about the repo layout, and running this again would flip+ it back rather than settle.+ """+ from .....ingestion.package_roots import module_for++ result = await session.execute(+ select(HealthFileMetric).where(HealthFileMetric.repository_id == repository_id)+ )+ changed = 0+ for row in result.scalars().all():+ expected = module_for(row.file_path, package_roots)+ if row.module != expected:+ row.module = expected+ changed += 1+ if changed:+ await session.flush()+ return changed+++async def get_health_metrics(+ session: AsyncSession,+ repository_id: str,+ *,+ file_paths: list[str] | None = None,+) -> list[HealthFileMetric]:+ """Per-file health metrics, ordered worst-first.++ See :func:`sort_metrics_worst_first` for why the order is not a plain+ ``ORDER BY score``.+ """+ q = select(HealthFileMetric).where(HealthFileMetric.repository_id == repository_id)+ if file_paths is not None:+ q = q.where(HealthFileMetric.file_path.in_(file_paths))+ result = await session.execute(q)+ rows = _filter_excluded_paths(+ list(result.scalars().all()),+ await health_exclude_spec(session, repository_id),+ )+ if len(rows) < 2:+ # Nothing to order. Skips the aggregate for the single-file lookups+ # (symbol drawer, file detail, one-plan refactoring view), which are+ # per-request reads that would otherwise pay for a ranking they cannot+ # use.+ return rows+ # Scoped to the caller's paths, not to ``rows``: a repo-wide read wants the+ # single grouped scan, and the extra keys an exclude config leaves in the+ # map are never looked up.+ return sort_metrics_worst_first(+ rows,+ await get_deduction_by_path(session, repository_id, file_paths=file_paths),+ )+++async def get_file_language_map(session: AsyncSession, repository_id: str) -> dict[str, str]:+ """``{file_path: language_tag}`` for every file node in the graph."""+ q = select(GraphNode.node_id, GraphNode.language).where(+ GraphNode.repository_id == repository_id,+ GraphNode.node_type == "file",+ )+ return {node_id: language for node_id, language in (await session.execute(q)).all()}+++async def get_perf_coverage(session: AsyncSession, repository_id: str) -> PerfCoverage:+ """How much of the analyzed code the performance pass was able to run on."""+ # Imported lazily to keep the persistence layer free of an analysis-layer+ # import at module load (and to avoid a circular import).+ from .....analysis.health.perf.coverage import coverage_for_metrics++ metrics = await get_health_metrics(session, repository_id)+ lang_by_path = await get_file_language_map(session, repository_id)+ return coverage_for_metrics(metrics, lang_by_path)diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/health/snapshots.py b/packages/core/src/repowise/core/persistence/crud/analysis/health/snapshots.pynew file mode 100644index 000000000..4c033fa7f--- /dev/null+++ b/packages/core/src/repowise/core/persistence/crud/analysis/health/snapshots.py@@ -0,0 +1,273 @@+"""Health snapshots: the rolling per-repo history and its narrow reads."""++from __future__ import annotations++import json+from datetime import datetime+from typing import NamedTuple++from sqlalchemy import func, select+from sqlalchemy.ext.asyncio import AsyncSession+from sqlalchemy.orm import defer++from ....models import DocDriftFinding, HealthSnapshot, _new_uuid, _now_utc++# Rolling history kept per repo. Older snapshots are deleted on insert.+# 50 entries gives Phase 4's `--trend` flag (last 10) plus the 5-back+# Declining-Health baseline plenty of headroom.+HEALTH_SNAPSHOT_RETENTION: int = 50++#: How many snapshots a *single file's* trend line reads. Every snapshot row+#: carries two whole-repo ``{path: float}`` maps, so a route that wants one+#: path's score series pays the entire retention window in TEXT to extract a+#: handful of floats. Twenty points is more than the decline heuristics need+#: (``DECLINE_LOOKBACK`` is 5) and more than the sparkline can usefully draw.+#:+#: One knock-on: ``FileTrend.snapshot_count`` is documented as the size of the+#: whole repo window, and on the two routes that pass this it becomes the size+#: of *this* window instead. Nothing reads that field off a per-file trend+#: today — the dashboard and the trend view read it off the repo-level routes,+#: which are unlimited and unchanged. Projecting one path's series in SQL would+#: keep the count true and drop the bytes further, but no query in this module+#: extracts from a JSON column and doing that portably across SQLite and+#: PostgreSQL is its own change.+FILE_TREND_SNAPSHOT_WINDOW: int = 20+++async def _doc_drift_count(session: AsyncSession, repository_id: str) -> int | None:+ """Stored drift findings; ``None`` when the drift pass has never run here."""+ from ..doc_drift import doc_drift_pass_ran++ count = await session.scalar(+ select(func.count(DocDriftFinding.id)).where(+ DocDriftFinding.repository_id == repository_id+ )+ )+ if not count and not await doc_drift_pass_ran(session, repository_id):+ return None+ return int(count or 0)+++async def save_health_snapshot(+ session: AsyncSession,+ repository_id: str,+ *,+ hotspot_health: float | None,+ average_health: float,+ worst_performer_path: str | None,+ worst_performer_score: float | None,+ per_file_scores: dict[str, float] | None = None,+ per_file_deductions: dict[str, float] | None = None,+ structure_average: float | None = None,+ history_average: float | None = None,+ production_average: float | None = None,+ maintainability_average: float | None = None,+ taken_at: datetime | None = None,+) -> HealthSnapshot:+ """Append a snapshot; prune oldest rows past ``HEALTH_SNAPSHOT_RETENTION``.++ Returns the inserted row. Per-file scores are stored compactly as+ ``{path: score}`` JSON (no per-finding detail — that lives in+ ``HealthFinding`` rows; snapshots are a thin history layer).++ ``per_file_deductions`` is the same shape for the files whose score is held+ at the floor, where the stored score has stopped carrying information.+ Build both with ``trends.snapshot_file_maps`` rather than by hand: a repo+ whose writers disagree gets a history that changes depth depending on which+ command last wrote it.++ ``structure_average`` / ``history_average`` are ``average_health``'s two+ halves in deduction points, so a later trend can name which one moved.++ The stored doc drift count is read here rather than passed in, so every+ writer records it without a new argument; write drift before calling this.+ """+ snap = HealthSnapshot(+ id=_new_uuid(),+ repository_id=repository_id,+ taken_at=taken_at or _now_utc(),+ hotspot_health=float(hotspot_health) if hotspot_health is not None else None,+ average_health=float(average_health),+ worst_performer_path=worst_performer_path,+ worst_performer_score=(+ float(worst_performer_score) if worst_performer_score is not None else None+ ),+ per_file_scores_json=json.dumps(per_file_scores or {}, separators=(",", ":")),+ per_file_deductions_json=json.dumps(per_file_deductions or {}, separators=(",", ":")),+ structure_average=structure_average,+ history_average=history_average,+ production_average=production_average,+ maintainability_average=maintainability_average,+ doc_drift_count=await _doc_drift_count(session, repository_id),+ )+ session.add(snap)+ await session.flush()++ # Prune older-than-retention rows. We keep the *N* newest by+ # ``taken_at``; ties are broken by id (UUIDs are random but stable).+ rows = await session.execute(+ select(HealthSnapshot)+ .where(HealthSnapshot.repository_id == repository_id)+ .order_by(HealthSnapshot.taken_at.desc(), HealthSnapshot.id.desc())+ )+ history = list(rows.scalars().all())+ if len(history) > HEALTH_SNAPSHOT_RETENTION:+ for row in history[HEALTH_SNAPSHOT_RETENTION:]:+ await session.delete(row)+ await session.flush()+ return snap+++async def list_health_snapshots(+ session: AsyncSession,+ repository_id: str,+ *,+ limit: int | None = None,+ file_maps: bool = True,+) -> list[HealthSnapshot]:+ """Return snapshots **oldest-first** (the shape ``trends.diff_snapshots``+ expects). Pass ``limit`` to cap the most recent N (still returned+ oldest-first for stable iteration).++ ``file_maps=False`` defers both per-file maps, for a caller that reads the+ scalars of every row and the maps of a few: it loads those with+ ``session.refresh(row, ["per_file_scores_json"])``.++ ``limit`` is pushed into SQL rather than applied to the fetched list. Every+ row carries ``per_file_scores_json`` and ``per_file_deductions_json``, both+ whole-repo ``{path: float}`` maps, and the table keeps+ ``HEALTH_SNAPSHOT_RETENTION`` (50) of them — so trimming in Python read the+ entire history off disk to throw most of it away. Taking the newest N+ descending and reversing gives the same list for a fraction of the bytes.+ """+ base = select(HealthSnapshot).where(HealthSnapshot.repository_id == repository_id)+ if not file_maps:+ base = base.options(+ defer(HealthSnapshot.per_file_scores_json),+ defer(HealthSnapshot.per_file_deductions_json),+ )+ if limit is not None:+ newest_first = await session.execute(+ base.order_by(HealthSnapshot.taken_at.desc(), HealthSnapshot.id.desc()).limit(limit)+ )+ return list(reversed(newest_first.scalars().all()))+ q = base.order_by(HealthSnapshot.taken_at.asc(), HealthSnapshot.id.asc())+ result = await session.execute(q)+ return list(result.scalars().all())+++class HealthSnapshotScalars(NamedTuple):+ """One snapshot's numeric columns, with no per-file map behind them."""++ taken_at: datetime | None+ average_health: float+ hotspot_health: float | None+++class HealthSnapshotHeadline(NamedTuple):+ """The snapshot figures a dashboard header actually reads.++ ``recent`` is empty unless the caller asked for it, and is ordered+ **oldest-first** to match ``list_health_snapshots`` — a trend line reads+ left to right, and the newest row is ``recent[-1]``.+ """++ hotspot_health: float | None+ taken_at: datetime | None+ snapshot_count: int+ recent: tuple[HealthSnapshotScalars, ...] = ()+++async def get_health_snapshot_headline(+ session: AsyncSession,+ repository_id: str,+ *,+ recent: int = 0,+) -> HealthSnapshotHeadline:+ """Latest snapshot's ``hotspot_health`` / ``taken_at``, plus how many exist.++ ``list_health_snapshots`` hydrates whole entities, and every row carries a+ ``per_file_scores_json`` blob sized by the repo's file count — on this+ codebase that is ~186 KB each, 2.8 MB across the retained history and ~9 MB+ at ``HEALTH_SNAPSHOT_RETENTION``. A caller that only needs scalars was+ reading all of it to use a handful of floats.++ Pass ``recent=N`` for the newest N rows' scalars as well — a sparkline and a+ delta-vs-previous both want a bounded window of numbers, not the history.+ ``snapshot_count`` is always the **true** total, independent of ``recent``,+ so a capped window can never be mistaken for the whole history.++ No JSON column is touched. Callers that genuinely need the per-file maps+ (the trend routes, the file drawer's sparkline) should keep using+ ``list_health_snapshots``; a caller that needs only their *sizes* wants+ ``get_health_snapshot_file_counts``.+ """+ rows = (+ await session.execute(+ select(+ HealthSnapshot.hotspot_health,+ HealthSnapshot.taken_at,+ HealthSnapshot.average_health,+ )+ .where(HealthSnapshot.repository_id == repository_id)+ .order_by(HealthSnapshot.taken_at.asc(), HealthSnapshot.id.asc())+ )+ ).all()+ if not rows:+ return HealthSnapshotHeadline(None, None, 0)+ hotspot_health, taken_at, _ = rows[-1]+ window = rows[-recent:] if recent > 0 else []+ return HealthSnapshotHeadline(+ hotspot_health,+ taken_at,+ len(rows),+ tuple(+ HealthSnapshotScalars(r_taken_at, float(r_avg), r_hotspot)+ for r_hotspot, r_taken_at, r_avg in window+ ),+ )+++async def get_health_snapshot_file_counts(+ session: AsyncSession,+ repository_id: str,+ *,+ limit: int = 2,+) -> list[int]:+ """How many files the newest *limit* snapshots scored, oldest-first.++ The only thing the overview's ``file_count`` delta wants out of+ ``per_file_scores_json`` is its key count, and it compares two rows. Loading+ the whole retained history to measure two of its maps read 2.8 MB to use+ 375 KB of it.++ Ordering matches ``list_health_snapshots`` exactly, so "the newest two"+ cannot mean different rows here than there.++ Anything that is not a ``{path: score}`` object counts 0 — unparseable, but+ also a bare JSON array or string, which ``len()`` would happily measure into+ a file count meaning nothing. The caller reads 0 as "unknown" and omits the+ delta rather than publishing a number it cannot justify. This is deliberately+ stricter than the ``len(json.loads(...))`` it replaced;+ ``save_health_snapshot`` only ever writes an object, so it can only bite on+ rows that did not come from it.+ """+ if limit <= 0:+ return []+ rows = (+ await session.execute(+ select(HealthSnapshot.per_file_scores_json)+ .where(HealthSnapshot.repository_id == repository_id)+ .order_by(HealthSnapshot.taken_at.desc(), HealthSnapshot.id.desc())+ .limit(limit)+ )+ ).all()+ counts: list[int] = []+ for (blob,) in reversed(rows):+ try:+ parsed = json.loads(blob or "{}")+ except (TypeError, ValueError):+ counts.append(0)+ continue+ counts.append(len(parsed) if isinstance(parsed, dict) else 0)+ return countsdiff --git a/packages/core/src/repowise/core/persistence/crud/analysis/health/summary.py b/packages/core/src/repowise/core/persistence/crud/analysis/health/summary.pynew file mode 100644index 000000000..7ceba1e73--- /dev/null+++ b/packages/core/src/repowise/core/persistence/crud/analysis/health/summary.py@@ -0,0 +1,219 @@+"""Repository-level health KPIs: the badge figure and the dashboard summary."""++from __future__ import annotations++from typing import Any++from sqlalchemy import select+from sqlalchemy.ext.asyncio import AsyncSession++from .....analysis.health.grading import analysed_share+from .....analysis.health.ranking import deduction_by_path, worst_kpis+from .....analysis.health.rows import split_unscored+from .....analysis.health.scoring import nloc_weighted_attr+from ....models import HealthFileMetric, HealthFinding+from ..plain_rows import plain_rows+from ..shown import shown+from .exclude import _filter_excluded_paths, health_exclude_spec+from .findings import open_finding_count+from .metrics import get_file_language_map, get_health_metrics+++def _rounded(value: float | None) -> float | None:+ """Two-decimal wire value, passing ``None`` through as "not measured"."""+ return round(value, 2) if value is not None else None+++async def get_headline_health(+ session: AsyncSession, repository_id: str+) -> tuple[float | None, float | None]:+ """``(average health, analysed share)``: the badge's figure and its band gate.++ The average is ``None`` if unmeasured; the share is ``analysed_share``.++ Numerically identical to ``get_health_summary()["average_health"]`` — same+ weighting, same ``max(nloc, 1)`` floor, same 2dp rounding — for callers that+ want *only* that number. The summary computes it as a by-product of building+ twenty-odd KPIs, which costs a full ORM hydration of the metrics table, the+ grouped deduction aggregate behind the worst-first ranking, the whole+ findings table for the per-dimension counts, and the graph's language map+ for perf coverage. The public badge endpoints want one float.++ Three columns and the same exclusion filter every other health read applies.+ That filter is a compiled ``pathspec``, not something SQL can express, which+ is why this is a narrow select reduced in Python rather than an ``AVG()``:+ a SQL average would quietly include files the dashboard excludes, and the+ badge would then disagree with the page it links to.+ """+ rows = _filter_excluded_paths(+ list(+ (+ await session.execute(+ select(+ HealthFileMetric.file_path,+ HealthFileMetric.score,+ HealthFileMetric.nloc,+ ).where(HealthFileMetric.repository_id == repository_id)+ )+ ).all()+ ),+ await health_exclude_spec(session, repository_id),+ )+ # Files with no score (no health dialect for their language) are skipped,+ # so a repository of nothing else reads unmeasured, never 10.0.+ scored, unanalysed = split_unscored(rows)+ return _rounded(nloc_weighted_attr(scored, "score")), analysed_share(len(scored), unanalysed)+++async def _open_finding_totals_rows(session: AsyncSession, repository_id: str) -> list[Any]:+ """The open findings :func:`get_health_findings` returns, narrowed to the+ columns the summary totals read.++ The summary sums and counts these; it never reads their tier, so it skips+ the details column and the tiering pass over every open row. Impact order+ is deliberate: per-file deductions are summed in the order the MCP+ dashboard sums them, so both name the same worst file; ``id`` makes the+ order total.+ """+ rows = await session.execute(+ select(HealthFinding.file_path, HealthFinding.health_impact, HealthFinding.dimension)+ .where(+ HealthFinding.repository_id == repository_id,+ HealthFinding.status == "open",+ # The totals sum what the scores counted, file-held rows included.+ shown(+ "health", HealthFinding.biomarker_type, HealthFinding.file_path, file_holds=False+ ),+ )+ .order_by(HealthFinding.health_impact.desc(), HealthFinding.id)+ )+ return _filter_excluded_paths(+ plain_rows(rows), await health_exclude_spec(session, repository_id)+ )+++async def get_health_summary(+ session: AsyncSession,+ repository_id: str,+ *,+ metrics: list | None = None,+ findings: list | None = None,+) -> dict:+ """Aggregate KPIs over the per-file metrics table.++ *metrics* and *findings* let a caller that has already loaded those rows+ hand them over instead of paying for a second full read. Callers doing more+ than one thing with them — the overview payload builds these KPIs, the+ severity breakdown and the defect-accuracy stat off the same two tables —+ would otherwise pull each table twice per request.++ Both are expected to be exactly what this function would have read itself:+ ``get_health_metrics(repository_id)`` and+ ``get_health_findings(repository_id)``, i.e. every open row for the repo,+ post-exclusion. Handing over a *filtered* subset would silently skew+ ``open_findings`` and the per-dimension counts, which are repo headlines.+ """+ if metrics is None:+ metrics = await get_health_metrics(session, repository_id)+ # A file in a language health has no dialect for is stored unscored. It is+ # counted apart and left out of every figure below.+ metrics, unanalysed = split_unscored(metrics)+ if not metrics:+ return {+ "file_count": 0,+ "unanalysed_file_count": unanalysed,+ "analysed_share": analysed_share(0, unanalysed),+ "average_health": None,+ "worst_performer_path": None,+ "worst_performer_score": None,+ "worst_test_path": None,+ "worst_test_score": None,+ "open_findings": 0,+ "maintainability_average": None,+ "performance_average": None,+ "structure_average": None,+ "history_average": None,+ "maintainability_findings": 0,+ "performance_findings": 0,+ "performance_findings_density": None,+ "performance_coverage_pct": None,+ "performance_covered_files": 0,+ "performance_analyzed_files": 0,+ "performance_skipped_files": 0,+ "performance_unsupported_languages": [],+ "worst_performance_path": None,+ "worst_performance_score": None,+ }+ avg = nloc_weighted_attr(metrics, "score")++ # The two co-surfaced pillars: the same NLOC weighting over their own+ # columns, ``None`` when no row carries one so a surface reads "not+ # measured" rather than a misleading 10.0.+ maintainability_average = nloc_weighted_attr(metrics, "maintainability_score")+ performance_average = nloc_weighted_attr(metrics, "performance_score")+ perf_scored = [m for m in metrics if getattr(m, "performance_score", None) is not None]++ # Worst-performance file: the lowest per-file performance score, surfaced only+ # when there is genuine risk (score < 10) so a clean repo shows no actionable+ # target rather than a misleading "worst" at a perfect 10.0.+ worst_performance_path: str | None = None+ worst_performance_score: float | None = None+ if perf_scored:+ perf_worst = min(perf_scored, key=lambda r: r.performance_score)+ if perf_worst.performance_score < 10.0:+ worst_performance_path = perf_worst.file_path+ worst_performance_score = round(perf_worst.performance_score, 2)++ if findings is None:+ findings = await _open_finding_totals_rows(session, repository_id)++ # Ranked with the same key as ``get_health_metrics``, off the findings this+ # function already holds, and in Fix first's scope: the file ``get_health``+ # lists first, so a script or schema scoring lowest is not named. The worst+ # test is named apart, so a weak test is not lost behind it.+ worst = worst_kpis(metrics, deduction_by_path(findings))++ by_dim: dict[str, int] = {}+ for finding in findings:+ dim = finding.dimension or "defect"+ by_dim[dim] = by_dim.get(dim, 0) + 1++ # Perf coverage: honest denominator for the score. On a repo that is mostly a+ # perf-unsupported language the aggregate perf average is meaningless, so we+ # surface how much of the analyzed code a detector actually ran on, plus a+ # findings-per-10K-LOC density over the *covered* lines (not the whole repo).+ from .....analysis.health.perf.coverage import coverage_for_metrics++ lang_by_path = await get_file_language_map(session, repository_id)+ coverage = coverage_for_metrics(metrics, lang_by_path)+ performance_findings = by_dim.get("performance", 0)+ performance_findings_density: float | None = None+ if coverage.covered_nloc > 0:+ performance_findings_density = round(+ 10000.0 * performance_findings / coverage.covered_nloc, 2+ )+ return {+ "file_count": len(metrics),+ "unanalysed_file_count": unanalysed,+ "analysed_share": analysed_share(len(metrics), unanalysed),+ "average_health": _rounded(avg),+ **worst,+ "open_findings": open_finding_count(findings),+ "maintainability_average": _rounded(maintainability_average),+ "performance_average": _rounded(performance_average),+ # The headline's two halves, in deduction points. Both come off columns+ # already on the rows in hand, so this costs no query — and without them+ # the page can show a score falling without saying which half moved.+ "structure_average": _rounded(nloc_weighted_attr(metrics, "structure_deduction")),+ "history_average": _rounded(nloc_weighted_attr(metrics, "history_deduction")),+ "maintainability_findings": by_dim.get("maintainability", 0),+ "performance_findings": performance_findings,+ "performance_findings_density": performance_findings_density,+ "performance_coverage_pct": (coverage.pct_loc if coverage.analyzed_files else None),+ "performance_covered_files": coverage.covered_files,+ "performance_analyzed_files": coverage.analyzed_files,+ "performance_skipped_files": coverage.skipped_files,+ "performance_unsupported_languages": coverage.unsupported_languages,+ "worst_performance_path": worst_performance_path,+ "worst_performance_score": worst_performance_score,+ }diff --git a/tests/unit/test_no_hotspot_health_copies.py b/tests/unit/test_no_hotspot_health_copies.pyindex a28a83131..aa93d3d4a 100644--- a/tests/unit/test_no_hotspot_health_copies.py+++ b/tests/unit/test_no_hotspot_health_copies.py@@ -40,7 +40,7 @@ _PACKAGES = pathlib.Path(__file__).resolve().parents[2] / "packages"_PLUMBING: dict[str, str] = {# --- storage and schema: the value arrives already computed --------------"repowise/core/persistence/models.py": "the column",- "repowise/core/persistence/crud/analysis/health.py": "writes/reads the column",+ "repowise/core/persistence/crud/analysis/health/snapshots.py": "writes/reads the column","repowise/core/persistence/crud/git.py": "supplies the hotspot path set, not the score","repowise/core/persistence/stores/_sql_analysis.py": "passthrough to the crud writer","repowise/core/workspace/store.py": "copies the latest snapshot column into the workspace store",