Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

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.py
deleted file mode 100644
index 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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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 totals
diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/health/metrics.py b/packages/core/src/repowise/core/persistence/crud/analysis/health/metrics.py
new file mode 100644
index 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.py
new file mode 100644
index 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 counts
diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/health/summary.py b/packages/core/src/repowise/core/persistence/crud/analysis/health/summary.py
new file mode 100644
index 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.py
index 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",