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(server): split code_health router into a package (#724)

Raghav Chamadiyafc66771f6816
diff --git a/packages/server/src/repowise/server/routers/code_health.py b/packages/server/src/repowise/server/routers/code_health.py
deleted file mode 100644
index dad0b8a33..000000000
--- a/packages/server/src/repowise/server/routers/code_health.py
+++ /dev/null
@@ -1,1087 +0,0 @@
-"""/api/repos/{repo_id}/health/* — code-health endpoints.
-
-Distinct from ``routers/health.py`` (liveness / Prometheus). All routes
-here require API-key auth and operate on the ``health_findings`` /
-``health_file_metrics`` tables.
-"""
-
-from __future__ import annotations
-
-import json
-import re
-from datetime import datetime
-from typing import Any
-
-from fastapi import APIRouter, Depends, HTTPException, Query, Response
-from pydantic import BaseModel, Field
-from sqlalchemy import select
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from repowise.core.analysis.health.churn_complexity import churn_complexity_points
-from repowise.core.analysis.health.defect_accuracy import compute_defect_accuracy
-from repowise.core.analysis.health.grading import band_for
-from repowise.core.analysis.health.grading import distribution as health_distribution
-from repowise.core.analysis.health.models import Severity
-from repowise.core.analysis.health.perf.coverage import supported_perf_languages
-from repowise.core.analysis.health.scoring import (
- CATEGORY_CAPS,
- biomarker_category,
- biomarker_weight,
- severity_deduction,
-)
-from repowise.core.analysis.health.signals import FileSignals, file_signals
-from repowise.core.analysis.health.suggestions import suggestion_for as _suggestion_for
-from repowise.core.analysis.health.trends import (
- FileTrend,
- diff_snapshots,
- file_trend,
- recent_kpis,
-)
-from repowise.core.persistence import crud
-from repowise.core.persistence.models import WikiSymbol
-from repowise.server.deps import get_db_session, verify_api_key
-from repowise.server.mcp_server._meta import resolve_indexed_commit
-
-router = APIRouter(
- tags=["code-health"],
- dependencies=[Depends(verify_api_key)],
-)
-
-
-_SEVERITY_ORDER = {"low": 0, "medium": 1, "high": 2, "critical": 3}
-
-
-def _finding_to_dict(f: Any) -> dict:
- try:
- details = json.loads(f.details_json) if f.details_json else {}
- except Exception:
- details = {}
- return {
- "id": f.id,
- "file_path": f.file_path,
- "biomarker_type": f.biomarker_type,
- "severity": f.severity,
- "function_name": f.function_name,
- "line_start": f.line_start,
- "line_end": f.line_end,
- "health_impact": round(f.health_impact, 3),
- "reason": f.reason,
- "details": details,
- "status": f.status,
- # Pillar the finding homes under (defect / maintainability / performance)
- # so the UI can filter findings per dimension. Defaults to defect for
- # rows that predate the split.
- "dimension": getattr(f, "dimension", None) or "defect",
- }
-
-
-def _round_opt(v: Any) -> float | None:
- """Round a nullable per-dimension score, preserving ``None`` (not measured)."""
- return round(v, 2) if v is not None else None
-
-
-def _primary_and_magnitude(findings: list[Any]) -> dict:
- """Dominant cause + pre-clamp deduction magnitude for one file's findings.
-
- Two presentation signals the score alone can't carry:
-
- - ``primary_biomarker`` / ``primary_reason`` — the single worst finding, so a
- low file can lead with "the one reason" instead of a wall of markers.
- - ``total_deduction`` — the summed (pre-floor) ``health_impact``. Equal to
- the breakdown endpoint's ``total_deduction`` (each finding's stored impact
- is already the applied, capped value), so it distinguishes two files that
- both floor at 1.0 (a -25 file from a -9 one) without touching ``score``.
-
- All-null on an empty list: a clean file has no lead and no magnitude.
- """
- if not findings:
- return {"primary_biomarker": None, "primary_reason": None, "total_deduction": None}
- primary = max(findings, key=lambda x: x.health_impact)
- total = sum(float(x.health_impact or 0.0) for x in findings)
- return {
- "primary_biomarker": primary.biomarker_type,
- "primary_reason": primary.reason,
- "total_deduction": round(total, 3),
- }
-
-
-def _leads_by_file(findings: list[Any]) -> dict[str, dict]:
- """Group findings by file and reduce each group to its dominant-cause lead."""
- by_file: dict[str, list[Any]] = {}
- for f in findings:
- by_file.setdefault(f.file_path, []).append(f)
- return {path: _primary_and_magnitude(fs) for path, fs in by_file.items()}
-
-
-def _metric_to_dict(
- m: Any,
- lead: dict | None = None,
- *,
- perf_findings: int = 0,
- perf_analyzed: bool | None = None,
-) -> dict:
- return {
- "file_path": m.file_path,
- "score": round(m.score, 2),
- "max_ccn": m.max_ccn,
- "max_nesting": m.max_nesting,
- "nloc": m.nloc,
- "has_test_file": m.has_test_file,
- "line_coverage_pct": m.line_coverage_pct,
- "module": m.module,
- "duplication_pct": getattr(m, "duplication_pct", None),
- # Per-dimension scores from the three-signal split. ``score`` above stays
- # the overall surfaced number (== defect_score for now).
- # ``performance_score`` is computed but not yet surfaced as its own pillar.
- "defect_score": _round_opt(getattr(m, "defect_score", None)),
- "maintainability_score": _round_opt(getattr(m, "maintainability_score", None)),
- "performance_score": _round_opt(getattr(m, "performance_score", None)),
- # Performance lens inputs for the code-health map: the open perf-finding
- # count colors the heat, and ``perf_analyzed`` (did a detector run on this
- # language?) separates green ("analyzed, none found") from grey ("never
- # looked"). Presentation only — the score above is untouched.
- "performance_findings": perf_findings,
- "performance_analyzed": perf_analyzed,
- # Dominant-cause lead + pre-clamp magnitude (null when findings weren't
- # loaded for this row, or the file is clean). Additive; readers degrade.
- "primary_biomarker": lead.get("primary_biomarker") if lead else None,
- "primary_reason": lead.get("primary_reason") if lead else None,
- "total_deduction": lead.get("total_deduction") if lead else None,
- }
-
-
-def _file_trend_to_dict(t: FileTrend) -> dict:
- """Wire shape for ``FileHealthTrend`` (types/health.ts). ``points`` is
- empty on thin history so the UI shows a "no history yet" state."""
- return {
- "file_path": t.file_path,
- "points": [
- {
- "taken_at": p.taken_at.isoformat() if p.taken_at else None,
- "score": round(p.score, 2),
- }
- for p in t.points
- ],
- "current": t.current,
- "previous": t.previous,
- "delta": t.delta,
- "declining": t.declining,
- "snapshot_count": t.snapshot_count,
- }
-
-
-def _file_signals_to_dict(s: FileSignals) -> dict:
- """Wire shape for ``FileSignals`` (types/health.ts). Each value is null
- when its source row is absent so the UI shows "no signal", never a
- misleading zero. ``change_entropy_pct`` is 0-100 (the column is 0-1)."""
- return {
- "prior_defect_count": s.prior_defect_count,
- "change_entropy_pct": s.change_entropy_pct,
- "lines_added_90d": s.lines_added_90d,
- "lines_deleted_90d": s.lines_deleted_90d,
- "commit_count_90d": s.commit_count_90d,
- "age_days": s.age_days,
- "primary_owner_name": s.primary_owner_name,
- "primary_owner_commit_pct": s.primary_owner_commit_pct,
- "recent_owner_name": s.recent_owner_name,
- "recent_owner_commit_pct": s.recent_owner_commit_pct,
- "in_degree": s.in_degree,
- "out_degree": s.out_degree,
- }
-
-
-async def _load_file_signals(session: AsyncSession, repo_id: str, file_path: str) -> FileSignals:
- """Join git metadata + graph degree for one file (read-only, no recompute).
-
- Degree is read only when the file is a graph node so topology stays "no
- signal" for files absent from the graph, rather than reporting a spurious
- zero. Shared by the drawer breakdown and the file-detail aggregate.
- """
- git_meta = await crud.get_git_metadata(session, repo_id, file_path)
- node = await crud.get_graph_node(session, repo_id, file_path)
- degrees = (
- await crud.get_node_degree_counts(session, repo_id, file_path)
- if node is not None
- else None
- )
- return file_signals(git_meta, degrees)
-
-
-async def _attach_symbol_ids(
- session: AsyncSession, repo_id: str, finding_dicts: list[dict]
-) -> list[dict]:
- """Attach the matching ``WikiSymbol.symbol_id`` to function-level findings.
-
- Matched by exact (file_path, function_name), falling back to the symbol
- whose line span contains the finding's ``line_start`` (covers methods
- recorded as ``Class.method`` vs the bare symbol name). One query for the
- whole batch; findings with no match keep ``symbol_id = None`` so the UI
- can degrade to the file page.
- """
- paths = {d["file_path"] for d in finding_dicts if d.get("function_name")}
- if not paths:
- return finding_dicts
- rows = (
- await session.execute(
- select(
- WikiSymbol.symbol_id,
- WikiSymbol.file_path,
- WikiSymbol.name,
- WikiSymbol.start_line,
- WikiSymbol.end_line,
- ).where(
- WikiSymbol.repository_id == repo_id,
- WikiSymbol.file_path.in_(paths),
- )
- )
- ).all()
- by_name: dict[tuple[str, str], str] = {}
- by_file: dict[str, list[tuple[int, int, str]]] = {}
- for symbol_id, file_path, name, start_line, end_line in rows:
- by_name.setdefault((file_path, name), symbol_id)
- if name and "." in name:
- by_name.setdefault((file_path, name.rsplit(".", 1)[-1]), symbol_id)
- if start_line is not None and end_line is not None:
- by_file.setdefault(file_path, []).append((start_line, end_line, symbol_id))
- for d in finding_dicts:
- fn = d.get("function_name")
- if not fn:
- d["symbol_id"] = None
- continue
- sid = by_name.get((d["file_path"], fn))
- if sid is None and d.get("line_start") is not None:
- line = d["line_start"]
- spans = by_file.get(d["file_path"], [])
- # Narrowest enclosing span wins (a method, not its class).
- best: tuple[int, str] | None = None
- for start, end, symbol_id in spans:
- if start <= line <= end and (best is None or end - start < best[0]):
- best = (end - start, symbol_id)
- sid = best[1] if best else None
- d["symbol_id"] = sid
- return finding_dicts
-
-
-# Strip the trailing " (N)" suffix that community detection appends to
-# disambiguate same-named modules. The leak is harmless in the DB but
-# noisy in the dashboard.
-_MODULE_SUFFIX = re.compile(r"\s*\(\d+\)\s*$")
-
-
-def _clean_module(name: str) -> str:
- return _MODULE_SUFFIX.sub("", name).strip()
-
-
-def _module_rollups(metrics: list[Any]) -> list[dict]:
- """NLOC-weighted module rollups derived from ``HealthFileMetric.module``."""
- buckets: dict[str, list[Any]] = {}
- for m in metrics:
- if m.module:
- buckets.setdefault(_clean_module(m.module), []).append(m)
- rows: list[dict] = []
- for name, group in buckets.items():
- total_nloc = sum(max(r.nloc, 1) for r in group)
- avg = sum(r.score * max(r.nloc, 1) for r in group) / total_nloc if total_nloc else 10.0
- worst = min(group, key=lambda r: r.score)
- rows.append(
- {
- "module": name,
- "file_count": len(group),
- "nloc": sum(r.nloc for r in group),
- "average_health": round(avg, 2),
- "worst_performer_path": worst.file_path,
- "worst_performer_score": round(worst.score, 2),
- }
- )
- rows.sort(key=lambda r: r["average_health"])
- return rows
-
-
-def _severity_breakdown(findings: list[Any]) -> dict[str, int]:
- out = {"critical": 0, "high": 0, "medium": 0, "low": 0}
- for f in findings:
- s = (f.severity or "").lower()
- if s in out:
- out[s] += 1
- return out
-
-
-def _biomarker_breakdown(findings: list[Any]) -> list[dict]:
- """Per-biomarker counts split by severity, sorted by total."""
- by_type: dict[str, dict[str, int]] = {}
- for f in findings:
- b = f.biomarker_type
- sev = (f.severity or "").lower()
- bucket = by_type.setdefault(
- b, {"critical": 0, "high": 0, "medium": 0, "low": 0, "total": 0}
- )
- if sev in bucket:
- bucket[sev] += 1
- bucket["total"] += 1
- rows = [{"biomarker_type": b, **counts} for b, counts in by_type.items()]
- rows.sort(key=lambda r: r["total"], reverse=True)
- return rows
-
-
-def _resolve_last_indexed_at(
- snapshot_taken_at: datetime | None, repo_updated_at: datetime | None
-) -> str | None:
- """Newest "index brought current" time as an ISO string, or ``None``.
-
- ``last_indexed_at`` should track the last time the index was synced to the
- checkout, not just the last health snapshot. A no-change ``repowise update``
- advances ``repositories.updated_at`` but takes no new snapshot, so a
- snapshot-only value would report the index as hours stale right after a
- refresh. Prefer whichever timestamp is newer (mirrors the overview router's
- sync fallback). Both inputs come from the same DB, so their tz-awareness
- matches and the comparison is safe.
- """
- newest = snapshot_taken_at
- if repo_updated_at is not None and (newest is None or repo_updated_at > newest):
- newest = repo_updated_at
- return newest.isoformat() if newest else None
-
-
[email protected]("/api/repos/{repo_id}/health/overview")
-async def health_overview(
- repo_id: str,
- limit: int = Query(20, ge=1, le=200),
- session: AsyncSession = Depends(get_db_session), # noqa: B008
-) -> dict:
- """KPIs + lowest-scoring files + per-module rollup + meta."""
- repo = await crud.get_repository(session, repo_id)
- if repo is None:
- raise HTTPException(status_code=404, detail="Repository not found")
- summary = await crud.get_health_summary(session, repo_id)
- metrics = await crud.get_health_metrics(session, repo_id)
- findings = await crud.get_health_findings(session, repo_id)
- snapshots = await crud.list_health_snapshots(session, repo_id)
-
- # Pull hotspot_health from the latest snapshot (KPIs aren't recomputed
- # on every overview hit — the snapshot is authoritative).
- hotspot_health: float | None = None
- snapshot_taken_at = None
- if snapshots:
- latest = snapshots[-1]
- hotspot_health = round(float(latest.hotspot_health), 2)
- snapshot_taken_at = latest.taken_at
-
- last_indexed_at = _resolve_last_indexed_at(snapshot_taken_at, repo.updated_at)
-
- leads = _leads_by_file(findings)
- metric_dicts = [_metric_to_dict(m, leads.get(m.file_path)) for m in metrics]
-
- # Repo-level band (from the NLOC-weighted average) + the per-band file
- # distribution. Both derive purely from the existing score — no new data.
- avg = summary.get("average_health")
- summary = {
- **summary,
- "hotspot_health": hotspot_health,
- "severity_breakdown": _severity_breakdown(findings),
- "band": band_for(float(avg)) if avg is not None else None,
- }
- distribution = health_distribution(metric_dicts)
-
- # "Does the score find the bugs?" self-validation, derived from the same
- # metrics + findings (prior_defect biomarker) already loaded above. ``None``
- # when the repo lacks enough files / defect history to be honest.
- defect_accuracy = compute_defect_accuracy(
- [_metric_to_dict(m) for m in metrics],
- [_finding_to_dict(f) for f in findings],
- )
-
- top_findings = await _attach_symbol_ids(
- session, repo_id, [_finding_to_dict(f) for f in findings[:limit]]
- )
-
- return {
- "summary": summary,
- "distribution": distribution,
- "defect_accuracy": defect_accuracy,
- "files": metric_dicts[:limit],
- "top_findings": top_findings,
- "modules": _module_rollups(metrics),
- "biomarkers": _biomarker_breakdown(findings),
- "meta": {
- "last_indexed_at": last_indexed_at,
- # Prefer state.json's last_sync_commit over a possibly-stale DB row
- # so the freshness signal self-heals on read (see the /api/repos
- # overlay). This is the extension's primary indexed-commit source.
- "head_commit": resolve_indexed_commit(repo.head_commit, repo.local_path),
- "snapshot_count": len(snapshots),
- },
- }
-
-
-# Shields-compatible band colors. Named colors for the JSON endpoint (shields
-# resolves them) + hexes for the self-rendered SVG so it matches without a
-# round-trip to img.shields.io.
-_BADGE_COLOR_NAME: dict[str, str] = {
- "healthy": "brightgreen",
- "warning": "yellow",
- "alert": "red",
- "unknown": "lightgrey",
-}
-_BADGE_COLOR_HEX: dict[str, str] = {
- "brightgreen": "#4c1",
- "yellow": "#dfb317",
- "red": "#e05d44",
- "lightgrey": "#9f9f9f",
-}
-
-
-def _badge_fields(average_health: float | None) -> tuple[str, str, str, str]:
- """Return ``(label, message, color_name, band)`` for the health badge."""
- if average_health is None:
- return "health", "no data", _BADGE_COLOR_NAME["unknown"], "unknown"
- band = band_for(float(average_health))
- return "health", f"{average_health:.1f}/10", _BADGE_COLOR_NAME[band], band
-
-
-def _render_badge_svg(label: str, message: str, color_name: str) -> str:
- """Render a flat shields-style SVG so the badge needs no external service.
-
- Char-width estimate matches shields' Verdana ~7px/char heuristic; exact
- pixel fidelity isn't needed for a README badge.
- """
- hex_color = _BADGE_COLOR_HEX.get(color_name, "#9f9f9f")
- lw = len(label) * 7 + 10
- mw = len(message) * 7 + 10
- total = lw + mw
- lx = lw * 10 // 2
- mx = (lw + mw // 2) * 10
- return (
- f'<svg xmlns="http://www.w3.org/2000/svg" width="{total}" height="20" '
- f'role="img" aria-label="{label}: {message}">'
- f"<title>{label}: {message}</title>"
- f'<linearGradient id="s" x2="0" y2="100%">'
- f'<stop offset="0" stop-color="#bbb" stop-opacity=".1"/>'
- f'<stop offset="1" stop-opacity=".1"/></linearGradient>'
- f'<clipPath id="r"><rect width="{total}" height="20" rx="3" fill="#fff"/></clipPath>'
- f'<g clip-path="url(#r)">'
- f'<rect width="{lw}" height="20" fill="#555"/>'
- f'<rect x="{lw}" width="{mw}" height="20" fill="{hex_color}"/>'
- f'<rect width="{total}" height="20" fill="url(#s)"/></g>'
- f'<g fill="#fff" text-anchor="middle" '
- f'font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="110">'
- f'<text x="{lx}" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" '
- f'textLength="{(lw - 10) * 10}">{label}</text>'
- f'<text x="{lx}" y="140" transform="scale(.1)" textLength="{(lw - 10) * 10}">{label}</text>'
- f'<text x="{mx}" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" '
- f'textLength="{(mw - 10) * 10}">{message}</text>'
- f'<text x="{mx}" y="140" transform="scale(.1)" textLength="{(mw - 10) * 10}">{message}</text>'
- f"</g></svg>"
- )
-
-
-async def _badge_average_health(session: AsyncSession, repo_id: str) -> float | None:
- repo = await crud.get_repository(session, repo_id)
- if repo is None:
- raise HTTPException(status_code=404, detail="Repository not found")
- summary = await crud.get_health_summary(session, repo_id)
- avg = summary.get("average_health")
- return float(avg) if avg is not None else None
-
-
[email protected]("/api/repos/{repo_id}/health/badge.json")
-async def health_badge_json(
- repo_id: str,
- session: AsyncSession = Depends(get_db_session), # noqa: B008
-) -> dict:
- """Shields.io endpoint-badge payload (color + ``N.N/10`` score, no letter).
-
- Embed via ``https://img.shields.io/endpoint?url=<this-url>``.
- """
- avg = await _badge_average_health(session, repo_id)
- label, message, color, band = _badge_fields(avg)
- return {
- "schemaVersion": 1,
- "label": label,
- "message": message,
- "color": color,
- "band": band,
- }
-
-
[email protected]("/api/repos/{repo_id}/health/badge.svg")
-async def health_badge_svg(
- repo_id: str,
- session: AsyncSession = Depends(get_db_session), # noqa: B008
-) -> Response:
- """Self-rendered flat SVG health badge (no external service round-trip)."""
- avg = await _badge_average_health(session, repo_id)
- label, message, color, _band = _badge_fields(avg)
- svg = _render_badge_svg(label, message, color)
- return Response(
- content=svg,
- media_type="image/svg+xml",
- headers={"Cache-Control": "max-age=300, public"},
- )
-
-
[email protected]("/api/repos/{repo_id}/health/modules")
-async def health_modules(
- repo_id: str,
- session: AsyncSession = Depends(get_db_session), # noqa: B008
-) -> dict:
- """NLOC-weighted module rollups for the dashboard module section."""
- repo = await crud.get_repository(session, repo_id)
- if repo is None:
- raise HTTPException(status_code=404, detail="Repository not found")
- metrics = await crud.get_health_metrics(session, repo_id)
- return {"modules": _module_rollups(metrics)}
-
-
[email protected]("/api/repos/{repo_id}/health/findings")
-async def list_health_findings(
- repo_id: str,
- biomarker_type: str | None = Query(None),
- file_path: str | None = Query(None),
- min_severity: str | None = Query(None),
- dimension: str | None = Query(None),
- limit: int = Query(100, ge=1, le=1000),
- session: AsyncSession = Depends(get_db_session), # noqa: B008
-) -> list[dict]:
- findings = await crud.get_health_findings(
- session,
- repo_id,
- biomarker_type=biomarker_type,
- file_path=file_path,
- min_severity=min_severity,
- dimension=dimension,
- )
- return await _attach_symbol_ids(
- session, repo_id, [_finding_to_dict(f) for f in findings[:limit]]
- )
-
-
-_SORT_FIELDS = {
- "score",
- "max_ccn",
- "max_nesting",
- "nloc",
- "duplication_pct",
- "line_coverage_pct",
- "file_path",
-}
-
-
[email protected]("/api/repos/{repo_id}/health/files")
-async def list_health_files(
- repo_id: str,
- limit: int = Query(200, ge=1, le=2000),
- offset: int = Query(0, ge=0),
- sort: str = Query("score", description="Sort field"),
- order: str = Query("asc", pattern="^(asc|desc)$"),
- search: str | None = Query(None, description="Substring filter on file_path"),
- module: str | None = Query(None, description="Filter to a module prefix"),
- only_hotspots: bool = Query(False),
- only_untested: bool = Query(False),
- only_failing: bool = Query(False, description="score < 7"),
- session: AsyncSession = Depends(get_db_session), # noqa: B008
-) -> dict:
- if sort not in _SORT_FIELDS:
- sort = "score"
- metrics = await crud.get_health_metrics(session, repo_id)
-
- hotspot_paths: set[str] = set()
- if only_hotspots:
- git_meta = await crud.get_all_git_metadata(session, repo_id)
- hotspot_paths = {p for p, gm in git_meta.items() if getattr(gm, "is_hotspot", False)}
-
- def _keep(m: Any) -> bool:
- if search and search.lower() not in m.file_path.lower():
- return False
- if module and not m.file_path.startswith(module):
- return False
- if only_hotspots and m.file_path not in hotspot_paths:
- return False
- if only_untested and m.has_test_file:
- return False
- return not (only_failing and m.score >= 7)
-
- filtered = [m for m in metrics if _keep(m)]
-
- def _key(m: Any):
- v = getattr(m, sort, None)
- if v is None:
- return (1, 0) if order == "asc" else (0, 0)
- return (0, v) if order == "asc" else (0, -v if isinstance(v, (int, float)) else v)
-
- reverse = order == "desc" and sort == "file_path"
- if sort == "file_path":
- filtered.sort(key=lambda m: m.file_path, reverse=reverse)
- else:
- filtered.sort(key=_key, reverse=False)
-
- total = len(filtered)
- page = filtered[offset : offset + limit]
- # Leads only for the page's files — enough to carry the top-reason chip and
- # the magnitude tiebreak without loading every finding for every row.
- page_paths = {m.file_path for m in page}
- findings = await crud.get_health_findings(session, repo_id)
- leads = _leads_by_file([f for f in findings if f.file_path in page_paths])
- # Per-file performance signal for the map's performance lens: open perf-
- # finding counts + whether a perf detector ran on the file's language. Colors
- # the lens by findings/coverage instead of the uniformly-green [9,10] score.
- perf_counts: dict[str, int] = {}
- for fnd in findings:
- if (getattr(fnd, "dimension", None) or "defect") == "performance":
- perf_counts[fnd.file_path] = perf_counts.get(fnd.file_path, 0) + 1
- lang_by_path = await crud.get_file_language_map(session, repo_id)
- perf_langs = supported_perf_languages()
- return {
- "total": total,
- "offset": offset,
- "limit": limit,
- "files": [
- _metric_to_dict(
- m,
- leads.get(m.file_path),
- perf_findings=perf_counts.get(m.file_path, 0),
- perf_analyzed=lang_by_path.get(m.file_path) in perf_langs,
- )
- for m in page
- ],
- }
-
-
-def _finding_details(f: Any) -> dict:
- """Return a finding's details as a dict, from either a live ``details``
- attr (tests) or the stored ``details_json`` column (the ORM row)."""
- d = getattr(f, "details", None)
- if isinstance(d, dict):
- return d
- raw = getattr(f, "details_json", None)
- if raw:
- try:
- parsed = json.loads(raw)
- return parsed if isinstance(parsed, dict) else {}
- except Exception:
- return {}
- return {}
-
-
-def _finding_base_deduction(f: Any) -> float:
- """The pre-cap, pre-weight base deduction for one stored finding.
-
- Mirrors ``scoring.score_file``: a continuous ``deduction`` override (e.g.
- coverage scaled by the uncovered fraction, recorded in the finding's
- ``details``) takes the place of the discrete severity table. Reading the
- override here — instead of always recomputing from the severity band — is
- what lets the breakdown show the continuous coverage gradient rather than a
- band proxy.
- """
- override = _finding_details(f).get("deduction")
- if isinstance(override, (int, float)):
- return float(override)
- sev = Severity(f.severity) if not isinstance(f.severity, Severity) else f.severity
- return severity_deduction(sev)
-
-
-def _score_breakdown_from_findings(findings: list[Any]) -> dict:
- """Reconstruct per-category deductions from open findings of one file.
-
- The applied per-finding impact is read from the **stored**
- ``health_impact`` (the exact, already-weighted-and-capped value computed by
- ``scoring.score_file`` at index time), so the breakdown reproduces the
- file's score and surfaces continuous signals (the coverage gradient) instead
- of a severity-band proxy. The raw (pre-cap) figure is reconstructed with the
- same ``base x weight`` formula scoring uses, so a capped category is honest
- about how much it shed.
- """
- per_cat: dict[str, list[Any]] = {}
- for f in findings:
- per_cat.setdefault(biomarker_category(f.biomarker_type), []).append(f)
-
- categories: list[dict] = []
- total_deduction = 0.0
- for cat, cap in CATEGORY_CAPS.items():
- entries = per_cat.get(cat, [])
- if not entries:
- continue
- raw_per_finding = [
- _finding_base_deduction(f) * biomarker_weight(f.biomarker_type) for f in entries
- ]
- applied_per_finding = [float(f.health_impact or 0.0) for f in entries]
- raw_sum = sum(raw_per_finding)
- applied_sum = sum(applied_per_finding)
- categories.append(
- {
- "category": cat,
- "cap": round(cap, 2),
- "raw_deduction": round(raw_sum, 3),
- "applied_deduction": round(applied_sum, 3),
- # Category shed weight iff its applied total is held at the cap.
- "capped": applied_sum < raw_sum - 1e-6,
- "finding_count": len(entries),
- "findings": [
- {
- "id": f.id,
- "biomarker_type": f.biomarker_type,
- "severity": f.severity,
- "raw_impact": round(raw, 3),
- "applied_impact": round(applied, 3),
- "function_name": f.function_name,
- "reason": f.reason,
- }
- for f, raw, applied in zip(
- entries, raw_per_finding, applied_per_finding, strict=True
- )
- ],
- }
- )
- total_deduction += applied_sum
- score = max(1.0, min(10.0, 10.0 - total_deduction))
- return {
- "score": round(score, 2),
- "total_deduction": round(total_deduction, 3),
- "categories": categories,
- }
-
-
[email protected]("/api/repos/{repo_id}/health/files/breakdown")
-async def file_score_breakdown(
- repo_id: str,
- file_path: str = Query(..., description="File path to break down"),
- session: AsyncSession = Depends(get_db_session), # noqa: B008
-) -> dict:
- repo = await crud.get_repository(session, repo_id)
- if repo is None:
- raise HTTPException(status_code=404, detail="Repository not found")
- metrics = await crud.get_health_metrics(session, repo_id, file_paths=[file_path])
- metric = metrics[0] if metrics else None
- findings = await crud.get_health_findings(session, repo_id, file_path=file_path)
- breakdown = _score_breakdown_from_findings(findings)
- finding_dicts = await _attach_symbol_ids(
- session, repo_id, [_finding_to_dict(f) for f in findings]
- )
- snapshots = await crud.list_health_snapshots(session, repo_id)
- return {
- "file_path": file_path,
- "metric": _metric_to_dict(metric, _primary_and_magnitude(findings)) if metric else None,
- "breakdown": breakdown,
- "findings": finding_dicts,
- "suggestions": {b: _suggestion_for(b) for b in {f.biomarker_type for f in findings}},
- "trend": _file_trend_to_dict(file_trend(snapshots, file_path)),
- "signals": _file_signals_to_dict(await _load_file_signals(session, repo_id, file_path)),
- }
-
-
[email protected]("/api/repos/{repo_id}/health/files/trend")
-async def file_health_trend(
- repo_id: str,
- file_path: str = Query(..., description="File path to chart over time"),
- session: AsyncSession = Depends(get_db_session), # noqa: B008
-) -> dict:
- """A single file's score-over-time series from the snapshot history.
-
- Silent (empty ``points``) when fewer than two snapshots carry the file.
- """
- repo = await crud.get_repository(session, repo_id)
- if repo is None:
- raise HTTPException(status_code=404, detail="Repository not found")
- snapshots = await crud.list_health_snapshots(session, repo_id)
- return _file_trend_to_dict(file_trend(snapshots, file_path))
-
-
[email protected]("/api/repos/{repo_id}/health/trend")
-async def health_trend(
- repo_id: str,
- limit: int = Query(20, ge=1, le=50),
- session: AsyncSession = Depends(get_db_session), # noqa: B008
-) -> dict:
- repo = await crud.get_repository(session, repo_id)
- if repo is None:
- raise HTTPException(status_code=404, detail="Repository not found")
- snapshots = await crud.list_health_snapshots(session, repo_id)
- summary = diff_snapshots(snapshots)
-
- # Per-file delta from the last two snapshots.
- file_deltas: list[dict] = []
- if len(snapshots) >= 2:
- try:
- prev = json.loads(snapshots[-2].per_file_scores_json or "{}")
- cur = json.loads(snapshots[-1].per_file_scores_json or "{}")
- except Exception:
- prev, cur = {}, {}
- all_paths = set(prev) | set(cur)
- for p in all_paths:
- before = prev.get(p)
- after = cur.get(p)
- if before is None or after is None:
- continue
- d = round(float(after) - float(before), 2)
- if d == 0:
- continue
- file_deltas.append({"file_path": p, "before": before, "after": after, "delta": d})
- file_deltas.sort(key=lambda r: r["delta"])
-
- return {
- "history": recent_kpis(snapshots, limit=limit),
- "summary": {
- "current_hotspot_health": summary.current_hotspot_health,
- "current_average_health": summary.current_average_health,
- "previous_hotspot_health": summary.previous_hotspot_health,
- "previous_average_health": summary.previous_average_health,
- "hotspot_delta": summary.hotspot_delta,
- "average_delta": summary.average_delta,
- },
- "alerts": [
- {
- "kind": a.kind,
- "metric": a.metric,
- "current": a.current,
- "baseline": a.baseline,
- "delta": a.delta,
- "message": a.message,
- }
- for a in summary.alerts
- ],
- "file_deltas": file_deltas[:50],
- "snapshot_count": len(snapshots),
- }
-
-
-class FindingStatusUpdate(BaseModel):
- status: str = Field(..., description="open | acknowledged | resolved | false_positive")
-
-
-_ALLOWED_STATUSES = {"open", "acknowledged", "resolved", "false_positive"}
-
-
[email protected]("/api/repos/{repo_id}/health/findings/{finding_id}")
-async def update_finding_status(
- repo_id: str,
- finding_id: str,
- payload: FindingStatusUpdate,
- session: AsyncSession = Depends(get_db_session), # noqa: B008
-) -> dict:
- if payload.status not in _ALLOWED_STATUSES:
- raise HTTPException(
- status_code=400, detail=f"status must be one of {sorted(_ALLOWED_STATUSES)}"
- )
- f = await crud.update_health_finding_status(session, finding_id, payload.status)
- if f is None:
- raise HTTPException(status_code=404, detail="Finding not found")
- await session.commit()
- return _finding_to_dict(f)
-
-
-def _coverage_row_to_dict(row: Any, *, include_covered_lines: bool = False) -> dict:
- out: dict[str, Any] = {
- "file_path": row.file_path,
- "source_format": row.source_format,
- "line_coverage_pct": row.line_coverage_pct,
- "branch_coverage_pct": row.branch_coverage_pct,
- "total_coverable_lines": row.total_coverable_lines,
- "ingested_at": row.ingested_at.isoformat() if row.ingested_at else None,
- "ingested_commit_sha": row.ingested_commit_sha,
- }
- if include_covered_lines:
- try:
- out["covered_lines"] = json.loads(row.covered_lines_json or "[]")
- except Exception:
- out["covered_lines"] = []
- return out
-
-
[email protected]("/api/repos/{repo_id}/health/coverage")
-async def health_coverage(
- repo_id: str,
- file_path: str | None = Query(None),
- limit: int = Query(500, ge=1, le=5000),
- session: AsyncSession = Depends(get_db_session), # noqa: B008
-) -> dict:
- """Coverage summary + per-file rows.
-
- Pass ``file_path`` to fetch a single file's full covered-line set.
- Without ``file_path`` we return the summary + a list of per-file
- rows trimmed by ``limit`` (covered_lines arrays stripped).
- """
- repo = await crud.get_repository(session, repo_id)
- if repo is None:
- raise HTTPException(status_code=404, detail="Repository not found")
-
- summary = await crud.get_coverage_summary(session, repo_id)
- if summary.get("ingested_at") is not None:
- summary = {**summary, "ingested_at": summary["ingested_at"].isoformat()}
- rows = await crud.load_coverage_for_repo(
- session, repo_id, file_paths=[file_path] if file_path else None
- )
- metrics = await crud.get_health_metrics(session, repo_id)
- metric_by_path = {m.file_path: m for m in metrics}
-
- if file_path:
- files = [_coverage_row_to_dict(r, include_covered_lines=True) for r in rows]
- else:
- rows_sorted = sorted(rows, key=lambda r: r.line_coverage_pct)
- files = [_coverage_row_to_dict(r) for r in rows_sorted[:limit]]
- # Attach per-file health score so the UI can render a coverage
- # x score matrix without a second request.
- for f in files:
- m = metric_by_path.get(f["file_path"])
- if m is not None:
- f["health_score"] = round(m.score, 2)
- f["nloc"] = m.nloc
-
- # Aggregate by directory for module-level bars (cheap; one pass).
- modules: dict[str, dict[str, Any]] = {}
- for r in rows:
- mod = r.file_path.rsplit("/", 1)[0] if "/" in r.file_path else "(root)"
- bucket = modules.setdefault(mod, {"covered": 0, "total": 0, "files": 0})
- bucket["files"] += 1
- bucket["total"] += r.total_coverable_lines
- bucket["covered"] += round(r.line_coverage_pct / 100.0 * r.total_coverable_lines)
- module_rows = [
- {
- "module": name,
- "files": v["files"],
- "covered_lines": v["covered"],
- "total_lines": v["total"],
- "line_coverage_pct": (
- round(v["covered"] / v["total"] * 100.0, 2) if v["total"] else 0.0
- ),
- }
- for name, v in modules.items()
- ]
- module_rows.sort(key=lambda x: x["line_coverage_pct"])
-
- return {
- "summary": summary,
- "files": files,
- "modules": module_rows[:limit],
- }
-
-
-_EFFORT_BUCKETS: tuple[tuple[int, str], ...] = (
- (40, "S"),
- (150, "M"),
- (400, "L"),
-)
-
-
-def _effort_for_nloc(nloc: int) -> str:
- for ceiling, label in _EFFORT_BUCKETS:
- if nloc <= ceiling:
- return label
- return "XL"
-
-
[email protected]("/api/repos/{repo_id}/health/refactoring-targets")
-async def refactoring_targets(
- repo_id: str,
- limit: int = Query(200, ge=1, le=500),
- module: str | None = Query(None, description="Filter to files in this module path"),
- biomarker: str | None = Query(None, description="Filter to one biomarker type"),
- min_severity: str | None = Query(None),
- max_effort: str | None = Query(None, description="S | M | L | XL"),
- sort: str = Query(
- "impact_per_effort", pattern="^(impact_per_effort|total_impact|score|finding_count)$"
- ),
- session: AsyncSession = Depends(get_db_session), # noqa: B008
-) -> dict:
- """Refactoring candidates ranked by impact / effort."""
- repo = await crud.get_repository(session, repo_id)
- if repo is None:
- raise HTTPException(status_code=404, detail="Repository not found")
-
- metrics = await crud.get_health_metrics(session, repo_id)
- metric_by_path = {m.file_path: m for m in metrics}
- findings = await crud.get_health_findings(session, repo_id)
-
- by_file: dict[str, list[Any]] = {}
- for f in findings:
- if biomarker and f.biomarker_type != biomarker:
- continue
- if min_severity:
- order = _SEVERITY_ORDER
- if order.get(f.severity, 0) < order.get(min_severity, 0):
- continue
- by_file.setdefault(f.file_path, []).append(f)
-
- effort_rank = {"S": 1, "M": 2, "L": 3, "XL": 5}
- max_effort_rank = effort_rank.get(max_effort or "", 99)
-
- targets: list[dict] = []
- for file_path, fs in by_file.items():
- if module and not file_path.startswith(module):
- continue
- m = metric_by_path.get(file_path)
- nloc = m.nloc if m is not None else 0
- score = m.score if m is not None else 10.0
- primary = max(fs, key=lambda x: x.health_impact)
- total_impact = round(sum(x.health_impact for x in fs), 3)
- effort_bucket = _effort_for_nloc(nloc)
- if effort_rank[effort_bucket] > max_effort_rank:
- continue
- weight = effort_rank[effort_bucket]
- ratio = round(total_impact / weight, 3)
- targets.append(
- {
- "file_path": file_path,
- "score": round(score, 2),
- "nloc": nloc,
- "module": _clean_module(m.module) if (m and m.module) else None,
- "primary_biomarker": primary.biomarker_type,
- "primary_severity": primary.severity,
- "primary_reason": primary.reason,
- "primary_function": primary.function_name,
- "primary_line_start": primary.line_start,
- "primary_line_end": primary.line_end,
- "primary_suggestion": _suggestion_for(primary.biomarker_type),
- "primary_finding_id": primary.id,
- "total_impact": total_impact,
- "finding_count": len(fs),
- "biomarkers": sorted({x.biomarker_type for x in fs}),
- "effort_bucket": effort_bucket,
- "impact_per_effort": ratio,
- "all_findings": [_finding_to_dict(f) for f in fs],
- }
- )
-
- sort_key_map = {
- "impact_per_effort": lambda t: (-t["impact_per_effort"], -t["total_impact"]),
- "total_impact": lambda t: -t["total_impact"],
- "score": lambda t: t["score"],
- "finding_count": lambda t: -t["finding_count"],
- }
- targets.sort(key=sort_key_map[sort])
- return {"targets": targets[:limit], "total": len(targets)}
-
-
-def _churn_complexity_to_dict(p: Any) -> dict:
- return {
- "file_path": p.file_path,
- "commit_count_90d": p.commit_count_90d,
- "max_ccn": p.max_ccn,
- "nloc": p.nloc,
- "score": p.score,
- "churn_percentile": p.churn_percentile,
- }
-
-
[email protected]("/api/repos/{repo_id}/health/churn-complexity")
-async def churn_complexity(
- repo_id: str,
- limit: int = Query(300, ge=1, le=1000),
- session: AsyncSession = Depends(get_db_session), # noqa: B008
-) -> dict:
- """Churn x complexity scatter points -- the "hotspot anatomy" danger-zone view.
-
- One point per recently-changed file: x = 90-day commit count (churn),
- y = max cyclomatic complexity, dot size = NLOC, color = health band. The
- top-right corner is where churn and complexity collide -- the highest-value
- refactoring targets, plotted instead of listed.
- """
- repo = await crud.get_repository(session, repo_id)
- if repo is None:
- raise HTTPException(status_code=404, detail="Repository not found")
-
- metrics = await crud.get_health_metrics(session, repo_id)
- git_meta = await crud.get_all_git_metadata(session, repo_id)
- points = churn_complexity_points(metrics, git_meta)
- return {
- "points": [_churn_complexity_to_dict(p) for p in points[:limit]],
- "total": len(points),
- }
diff --git a/packages/server/src/repowise/server/routers/code_health/__init__.py b/packages/server/src/repowise/server/routers/code_health/__init__.py
new file mode 100644
index 000000000..e2c4ec5cf
--- /dev/null
+++ b/packages/server/src/repowise/server/routers/code_health/__init__.py
@@ -0,0 +1,43 @@
+"""/api/repos/{repo_id}/health/* — code-health endpoints.
+
+Distinct from ``routers/health.py`` (liveness / Prometheus). All routes
+here require API-key auth and operate on the ``health_findings`` /
+``health_file_metrics`` tables.
+
+This package is a pure structural split of the former ``code_health.py``
+module: the shared ``router`` lives in ``_router``, route handlers are grouped
+by endpoint family, and pure/DB helpers live in leaf modules. The public import
+path ``repowise.server.routers.code_health`` still resolves ``router`` plus
+every cross-module helper unchanged.
+"""
+
+from __future__ import annotations
+
+# import route modules for their decorator side-effects (attach routes to the shared router)
+from . import (
+ badge, # noqa: F401
+ churn_routes, # noqa: F401
+ coverage_routes, # noqa: F401
+ files_routes, # noqa: F401
+ findings_routes, # noqa: F401
+ overview_routes, # noqa: F401
+ refactoring_routes, # noqa: F401
+ trends_routes, # noqa: F401
+)
+from ._router import router
+from .badge import _badge_fields, _render_badge_svg # noqa: F401
+from .breakdown import _finding_base_deduction, _score_breakdown_from_findings # noqa: F401
+from .overview_routes import _resolve_last_indexed_at # noqa: F401
+
+# re-export helpers imported by routers/files.py + tests (keep old import path working)
+from .serializers import ( # noqa: F401
+ _churn_complexity_to_dict,
+ _file_signals_to_dict,
+ _file_trend_to_dict,
+ _finding_to_dict,
+ _leads_by_file,
+ _metric_to_dict,
+ _primary_and_magnitude,
+)
+
+__all__ = ["router"]
diff --git a/packages/server/src/repowise/server/routers/code_health/_router.py b/packages/server/src/repowise/server/routers/code_health/_router.py
new file mode 100644
index 000000000..3172728bf
--- /dev/null
+++ b/packages/server/src/repowise/server/routers/code_health/_router.py
@@ -0,0 +1,17 @@
+"""The shared code-health ``APIRouter`` instance.
+
+Leaf module so every route submodule can ``from ._router import router`` and
+attach its handlers to the one router without importing (and re-entering) the
+package ``__init__``.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends
+
+from repowise.server.deps import verify_api_key
+
+router = APIRouter(
+ tags=["code-health"],
+ dependencies=[Depends(verify_api_key)],
+)
diff --git a/packages/server/src/repowise/server/routers/code_health/aggregation.py b/packages/server/src/repowise/server/routers/code_health/aggregation.py
new file mode 100644
index 000000000..75c493750
--- /dev/null
+++ b/packages/server/src/repowise/server/routers/code_health/aggregation.py
@@ -0,0 +1,66 @@
+"""Module rollups + severity / biomarker breakdowns over finding lists."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+# Strip the trailing " (N)" suffix that community detection appends to
+# disambiguate same-named modules. The leak is harmless in the DB but
+# noisy in the dashboard.
+_MODULE_SUFFIX = re.compile(r"\s*\(\d+\)\s*$")
+
+
+def _clean_module(name: str) -> str:
+ return _MODULE_SUFFIX.sub("", name).strip()
+
+
+def _module_rollups(metrics: list[Any]) -> list[dict]:
+ """NLOC-weighted module rollups derived from ``HealthFileMetric.module``."""
+ buckets: dict[str, list[Any]] = {}
+ for m in metrics:
+ if m.module:
+ buckets.setdefault(_clean_module(m.module), []).append(m)
+ rows: list[dict] = []
+ for name, group in buckets.items():
+ total_nloc = sum(max(r.nloc, 1) for r in group)
+ avg = sum(r.score * max(r.nloc, 1) for r in group) / total_nloc if total_nloc else 10.0
+ worst = min(group, key=lambda r: r.score)
+ rows.append(
+ {
+ "module": name,
+ "file_count": len(group),
+ "nloc": sum(r.nloc for r in group),
+ "average_health": round(avg, 2),
+ "worst_performer_path": worst.file_path,
+ "worst_performer_score": round(worst.score, 2),
+ }
+ )
+ rows.sort(key=lambda r: r["average_health"])
+ return rows
+
+
+def _severity_breakdown(findings: list[Any]) -> dict[str, int]:
+ out = {"critical": 0, "high": 0, "medium": 0, "low": 0}
+ for f in findings:
+ s = (f.severity or "").lower()
+ if s in out:
+ out[s] += 1
+ return out
+
+
+def _biomarker_breakdown(findings: list[Any]) -> list[dict]:
+ """Per-biomarker counts split by severity, sorted by total."""
+ by_type: dict[str, dict[str, int]] = {}
+ for f in findings:
+ b = f.biomarker_type
+ sev = (f.severity or "").lower()
+ bucket = by_type.setdefault(
+ b, {"critical": 0, "high": 0, "medium": 0, "low": 0, "total": 0}
+ )
+ if sev in bucket:
+ bucket[sev] += 1
+ bucket["total"] += 1
+ rows = [{"biomarker_type": b, **counts} for b, counts in by_type.items()]
+ rows.sort(key=lambda r: r["total"], reverse=True)
+ return rows
diff --git a/packages/server/src/repowise/server/routers/code_health/badge.py b/packages/server/src/repowise/server/routers/code_health/badge.py
new file mode 100644
index 000000000..e24953f3a
--- /dev/null
+++ b/packages/server/src/repowise/server/routers/code_health/badge.py
@@ -0,0 +1,117 @@
+"""Shields-compatible code-health badge (JSON endpoint + self-rendered SVG)."""
+
+from __future__ import annotations
+
+from fastapi import Depends, HTTPException, Response
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from repowise.core.analysis.health.grading import band_for
+from repowise.core.persistence import crud
+from repowise.server.deps import get_db_session
+
+from ._router import router
+
+# Shields-compatible band colors. Named colors for the JSON endpoint (shields
+# resolves them) + hexes for the self-rendered SVG so it matches without a
+# round-trip to img.shields.io.
+_BADGE_COLOR_NAME: dict[str, str] = {
+ "healthy": "brightgreen",
+ "warning": "yellow",
+ "alert": "red",
+ "unknown": "lightgrey",
+}
+_BADGE_COLOR_HEX: dict[str, str] = {
+ "brightgreen": "#4c1",
+ "yellow": "#dfb317",
+ "red": "#e05d44",
+ "lightgrey": "#9f9f9f",
+}
+
+
+def _badge_fields(average_health: float | None) -> tuple[str, str, str, str]:
+ """Return ``(label, message, color_name, band)`` for the health badge."""
+ if average_health is None:
+ return "health", "no data", _BADGE_COLOR_NAME["unknown"], "unknown"
+ band = band_for(float(average_health))
+ return "health", f"{average_health:.1f}/10", _BADGE_COLOR_NAME[band], band
+
+
+def _render_badge_svg(label: str, message: str, color_name: str) -> str:
+ """Render a flat shields-style SVG so the badge needs no external service.
+
+ Char-width estimate matches shields' Verdana ~7px/char heuristic; exact
+ pixel fidelity isn't needed for a README badge.
+ """
+ hex_color = _BADGE_COLOR_HEX.get(color_name, "#9f9f9f")
+ lw = len(label) * 7 + 10
+ mw = len(message) * 7 + 10
+ total = lw + mw
+ lx = lw * 10 // 2
+ mx = (lw + mw // 2) * 10
+ return (
+ f'<svg xmlns="http://www.w3.org/2000/svg" width="{total}" height="20" '
+ f'role="img" aria-label="{label}: {message}">'
+ f"<title>{label}: {message}</title>"
+ f'<linearGradient id="s" x2="0" y2="100%">'
+ f'<stop offset="0" stop-color="#bbb" stop-opacity=".1"/>'
+ f'<stop offset="1" stop-opacity=".1"/></linearGradient>'
+ f'<clipPath id="r"><rect width="{total}" height="20" rx="3" fill="#fff"/></clipPath>'
+ f'<g clip-path="url(#r)">'
+ f'<rect width="{lw}" height="20" fill="#555"/>'
+ f'<rect x="{lw}" width="{mw}" height="20" fill="{hex_color}"/>'
+ f'<rect width="{total}" height="20" fill="url(#s)"/></g>'
+ f'<g fill="#fff" text-anchor="middle" '
+ f'font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="110">'
+ f'<text x="{lx}" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" '
+ f'textLength="{(lw - 10) * 10}">{label}</text>'
+ f'<text x="{lx}" y="140" transform="scale(.1)" textLength="{(lw - 10) * 10}">{label}</text>'
+ f'<text x="{mx}" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" '
+ f'textLength="{(mw - 10) * 10}">{message}</text>'
+ f'<text x="{mx}" y="140" transform="scale(.1)" textLength="{(mw - 10) * 10}">{message}</text>'
+ f"</g></svg>"
+ )
+
+
+async def _badge_average_health(session: AsyncSession, repo_id: str) -> float | None:
+ repo = await crud.get_repository(session, repo_id)
+ if repo is None:
+ raise HTTPException(status_code=404, detail="Repository not found")
+ summary = await crud.get_health_summary(session, repo_id)
+ avg = summary.get("average_health")
+ return float(avg) if avg is not None else None
+
+
[email protected]("/api/repos/{repo_id}/health/badge.json")
+async def health_badge_json(
+ repo_id: str,
+ session: AsyncSession = Depends(get_db_session), # noqa: B008
+) -> dict:
+ """Shields.io endpoint-badge payload (color + ``N.N/10`` score, no letter).
+
+ Embed via ``https://img.shields.io/endpoint?url=<this-url>``.
+ """
+ avg = await _badge_average_health(session, repo_id)
+ label, message, color, band = _badge_fields(avg)
+ return {
+ "schemaVersion": 1,
+ "label": label,
+ "message": message,
+ "color": color,
+ "band": band,
+ }
+
+
[email protected]("/api/repos/{repo_id}/health/badge.svg")
+async def health_badge_svg(
+ repo_id: str,
+ session: AsyncSession = Depends(get_db_session), # noqa: B008
+) -> Response:
+ """Self-rendered flat SVG health badge (no external service round-trip)."""
+ avg = await _badge_average_health(session, repo_id)
+ label, message, color, _band = _badge_fields(avg)
+ svg = _render_badge_svg(label, message, color)
+ return Response(
+ content=svg,
+ media_type="image/svg+xml",
+ headers={"Cache-Control": "max-age=300, public"},
+ )
diff --git a/packages/server/src/repowise/server/routers/code_health/breakdown.py b/packages/server/src/repowise/server/routers/code_health/breakdown.py
new file mode 100644
index 000000000..be2e0bf0e
--- /dev/null
+++ b/packages/server/src/repowise/server/routers/code_health/breakdown.py
@@ -0,0 +1,108 @@
+"""Reconstruct per-category score breakdowns from stored findings."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from repowise.core.analysis.health.models import Severity
+from repowise.core.analysis.health.scoring import (
+ CATEGORY_CAPS,
+ biomarker_category,
+ biomarker_weight,
+ severity_deduction,
+)
+
+
+def _finding_details(f: Any) -> dict:
+ """Return a finding's details as a dict, from either a live ``details``
+ attr (tests) or the stored ``details_json`` column (the ORM row)."""
+ d = getattr(f, "details", None)
+ if isinstance(d, dict):
+ return d
+ raw = getattr(f, "details_json", None)
+ if raw:
+ try:
+ parsed = json.loads(raw)
+ return parsed if isinstance(parsed, dict) else {}
+ except Exception:
+ return {}
+ return {}
+
+
+def _finding_base_deduction(f: Any) -> float:
+ """The pre-cap, pre-weight base deduction for one stored finding.
+
+ Mirrors ``scoring.score_file``: a continuous ``deduction`` override (e.g.
+ coverage scaled by the uncovered fraction, recorded in the finding's
+ ``details``) takes the place of the discrete severity table. Reading the
+ override here — instead of always recomputing from the severity band — is
+ what lets the breakdown show the continuous coverage gradient rather than a
+ band proxy.
+ """
+ override = _finding_details(f).get("deduction")
+ if isinstance(override, (int, float)):
+ return float(override)
+ sev = Severity(f.severity) if not isinstance(f.severity, Severity) else f.severity
+ return severity_deduction(sev)
+
+
+def _score_breakdown_from_findings(findings: list[Any]) -> dict:
+ """Reconstruct per-category deductions from open findings of one file.
+
+ The applied per-finding impact is read from the **stored**
+ ``health_impact`` (the exact, already-weighted-and-capped value computed by
+ ``scoring.score_file`` at index time), so the breakdown reproduces the
+ file's score and surfaces continuous signals (the coverage gradient) instead
+ of a severity-band proxy. The raw (pre-cap) figure is reconstructed with the
+ same ``base x weight`` formula scoring uses, so a capped category is honest
+ about how much it shed.
+ """
+ per_cat: dict[str, list[Any]] = {}
+ for f in findings:
+ per_cat.setdefault(biomarker_category(f.biomarker_type), []).append(f)
+
+ categories: list[dict] = []
+ total_deduction = 0.0
+ for cat, cap in CATEGORY_CAPS.items():
+ entries = per_cat.get(cat, [])
+ if not entries:
+ continue
+ raw_per_finding = [
+ _finding_base_deduction(f) * biomarker_weight(f.biomarker_type) for f in entries
+ ]
+ applied_per_finding = [float(f.health_impact or 0.0) for f in entries]
+ raw_sum = sum(raw_per_finding)
+ applied_sum = sum(applied_per_finding)
+ categories.append(
+ {
+ "category": cat,
+ "cap": round(cap, 2),
+ "raw_deduction": round(raw_sum, 3),
+ "applied_deduction": round(applied_sum, 3),
+ # Category shed weight iff its applied total is held at the cap.
+ "capped": applied_sum < raw_sum - 1e-6,
+ "finding_count": len(entries),
+ "findings": [
+ {
+ "id": f.id,
+ "biomarker_type": f.biomarker_type,
+ "severity": f.severity,
+ "raw_impact": round(raw, 3),
+ "applied_impact": round(applied, 3),
+ "function_name": f.function_name,
+ "reason": f.reason,
+ }
+ for f, raw, applied in zip(
+ entries, raw_per_finding, applied_per_finding, strict=True
+ )
+ ],
+ }
+ )
+ total_deduction += applied_sum
+ score = max(1.0, min(10.0, 10.0 - total_deduction))
+ return {
+ "score": round(score, 2),
+ "total_deduction": round(total_deduction, 3),
+ "categories": categories,
+ }
diff --git a/packages/server/src/repowise/server/routers/code_health/churn_routes.py b/packages/server/src/repowise/server/routers/code_health/churn_routes.py
new file mode 100644
index 000000000..966185318
--- /dev/null
+++ b/packages/server/src/repowise/server/routers/code_health/churn_routes.py
@@ -0,0 +1,39 @@
+"""Churn x complexity scatter route."""
+
+from __future__ import annotations
+
+from fastapi import Depends, HTTPException, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from repowise.core.analysis.health.churn_complexity import churn_complexity_points
+from repowise.core.persistence import crud
+from repowise.server.deps import get_db_session
+
+from ._router import router
+from .serializers import _churn_complexity_to_dict
+
+
[email protected]("/api/repos/{repo_id}/health/churn-complexity")
+async def churn_complexity(
+ repo_id: str,
+ limit: int = Query(300, ge=1, le=1000),
+ session: AsyncSession = Depends(get_db_session), # noqa: B008
+) -> dict:
+ """Churn x complexity scatter points -- the "hotspot anatomy" danger-zone view.
+
+ One point per recently-changed file: x = 90-day commit count (churn),
+ y = max cyclomatic complexity, dot size = NLOC, color = health band. The
+ top-right corner is where churn and complexity collide -- the highest-value
+ refactoring targets, plotted instead of listed.
+ """
+ repo = await crud.get_repository(session, repo_id)
+ if repo is None:
+ raise HTTPException(status_code=404, detail="Repository not found")
+
+ metrics = await crud.get_health_metrics(session, repo_id)
+ git_meta = await crud.get_all_git_metadata(session, repo_id)
+ points = churn_complexity_points(metrics, git_meta)
+ return {
+ "points": [_churn_complexity_to_dict(p) for p in points[:limit]],
+ "total": len(points),
+ }
diff --git a/packages/server/src/repowise/server/routers/code_health/coverage_routes.py b/packages/server/src/repowise/server/routers/code_health/coverage_routes.py
new file mode 100644
index 000000000..6fcc805c3
--- /dev/null
+++ b/packages/server/src/repowise/server/routers/code_health/coverage_routes.py
@@ -0,0 +1,100 @@
+"""Coverage summary + per-file / per-module coverage route."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from fastapi import Depends, HTTPException, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from repowise.core.persistence import crud
+from repowise.server.deps import get_db_session
+
+from ._router import router
+
+
+def _coverage_row_to_dict(row: Any, *, include_covered_lines: bool = False) -> dict:
+ out: dict[str, Any] = {
+ "file_path": row.file_path,
+ "source_format": row.source_format,
+ "line_coverage_pct": row.line_coverage_pct,
+ "branch_coverage_pct": row.branch_coverage_pct,
+ "total_coverable_lines": row.total_coverable_lines,
+ "ingested_at": row.ingested_at.isoformat() if row.ingested_at else None,
+ "ingested_commit_sha": row.ingested_commit_sha,
+ }
+ if include_covered_lines:
+ try:
+ out["covered_lines"] = json.loads(row.covered_lines_json or "[]")
+ except Exception:
+ out["covered_lines"] = []
+ return out
+
+
[email protected]("/api/repos/{repo_id}/health/coverage")
+async def health_coverage(
+ repo_id: str,
+ file_path: str | None = Query(None),
+ limit: int = Query(500, ge=1, le=5000),
+ session: AsyncSession = Depends(get_db_session), # noqa: B008
+) -> dict:
+ """Coverage summary + per-file rows.
+
+ Pass ``file_path`` to fetch a single file's full covered-line set.
+ Without ``file_path`` we return the summary + a list of per-file
+ rows trimmed by ``limit`` (covered_lines arrays stripped).
+ """
+ repo = await crud.get_repository(session, repo_id)
+ if repo is None:
+ raise HTTPException(status_code=404, detail="Repository not found")
+
+ summary = await crud.get_coverage_summary(session, repo_id)
+ if summary.get("ingested_at") is not None:
+ summary = {**summary, "ingested_at": summary["ingested_at"].isoformat()}
+ rows = await crud.load_coverage_for_repo(
+ session, repo_id, file_paths=[file_path] if file_path else None
+ )
+ metrics = await crud.get_health_metrics(session, repo_id)
+ metric_by_path = {m.file_path: m for m in metrics}
+
+ if file_path:
+ files = [_coverage_row_to_dict(r, include_covered_lines=True) for r in rows]
+ else:
+ rows_sorted = sorted(rows, key=lambda r: r.line_coverage_pct)
+ files = [_coverage_row_to_dict(r) for r in rows_sorted[:limit]]
+ # Attach per-file health score so the UI can render a coverage
+ # x score matrix without a second request.
+ for f in files:
+ m = metric_by_path.get(f["file_path"])
+ if m is not None:
+ f["health_score"] = round(m.score, 2)
+ f["nloc"] = m.nloc
+
+ # Aggregate by directory for module-level bars (cheap; one pass).
+ modules: dict[str, dict[str, Any]] = {}
+ for r in rows:
+ mod = r.file_path.rsplit("/", 1)[0] if "/" in r.file_path else "(root)"
+ bucket = modules.setdefault(mod, {"covered": 0, "total": 0, "files": 0})
+ bucket["files"] += 1
+ bucket["total"] += r.total_coverable_lines
+ bucket["covered"] += round(r.line_coverage_pct / 100.0 * r.total_coverable_lines)
+ module_rows = [
+ {
+ "module": name,
+ "files": v["files"],
+ "covered_lines": v["covered"],
+ "total_lines": v["total"],
+ "line_coverage_pct": (
+ round(v["covered"] / v["total"] * 100.0, 2) if v["total"] else 0.0
+ ),
+ }
+ for name, v in modules.items()
+ ]
+ module_rows.sort(key=lambda x: x["line_coverage_pct"])
+
+ return {
+ "summary": summary,
+ "files": files,
+ "modules": module_rows[:limit],
+ }
diff --git a/packages/server/src/repowise/server/routers/code_health/files_routes.py b/packages/server/src/repowise/server/routers/code_health/files_routes.py
new file mode 100644
index 000000000..72c78bbf6
--- /dev/null
+++ b/packages/server/src/repowise/server/routers/code_health/files_routes.py
@@ -0,0 +1,144 @@
+"""Per-file health listing + single-file score breakdown routes."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import Depends, HTTPException, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from repowise.core.analysis.health.perf.coverage import supported_perf_languages
+from repowise.core.analysis.health.suggestions import suggestion_for as _suggestion_for
+from repowise.core.analysis.health.trends import file_trend
+from repowise.core.persistence import crud
+from repowise.server.deps import get_db_session
+
+from ._router import router
+from .breakdown import _score_breakdown_from_findings
+from .loaders import _attach_symbol_ids, _load_file_signals
+from .serializers import (
+ _file_signals_to_dict,
+ _file_trend_to_dict,
+ _finding_to_dict,
+ _leads_by_file,
+ _metric_to_dict,
+ _primary_and_magnitude,
+)
+
+_SORT_FIELDS = {
+ "score",
+ "max_ccn",
+ "max_nesting",
+ "nloc",
+ "duplication_pct",
+ "line_coverage_pct",
+ "file_path",
+}
+
+
[email protected]("/api/repos/{repo_id}/health/files")
+async def list_health_files(
+ repo_id: str,
+ limit: int = Query(200, ge=1, le=2000),
+ offset: int = Query(0, ge=0),
+ sort: str = Query("score", description="Sort field"),
+ order: str = Query("asc", pattern="^(asc|desc)$"),
+ search: str | None = Query(None, description="Substring filter on file_path"),
+ module: str | None = Query(None, description="Filter to a module prefix"),
+ only_hotspots: bool = Query(False),
+ only_untested: bool = Query(False),
+ only_failing: bool = Query(False, description="score < 7"),
+ session: AsyncSession = Depends(get_db_session), # noqa: B008
+) -> dict:
+ if sort not in _SORT_FIELDS:
+ sort = "score"
+ metrics = await crud.get_health_metrics(session, repo_id)
+
+ hotspot_paths: set[str] = set()
+ if only_hotspots:
+ git_meta = await crud.get_all_git_metadata(session, repo_id)
+ hotspot_paths = {p for p, gm in git_meta.items() if getattr(gm, "is_hotspot", False)}
+
+ def _keep(m: Any) -> bool:
+ if search and search.lower() not in m.file_path.lower():
+ return False
+ if module and not m.file_path.startswith(module):
+ return False
+ if only_hotspots and m.file_path not in hotspot_paths:
+ return False
+ if only_untested and m.has_test_file:
+ return False
+ return not (only_failing and m.score >= 7)
+
+ filtered = [m for m in metrics if _keep(m)]
+
+ def _key(m: Any):
+ v = getattr(m, sort, None)
+ if v is None:
+ return (1, 0) if order == "asc" else (0, 0)
+ return (0, v) if order == "asc" else (0, -v if isinstance(v, (int, float)) else v)
+
+ reverse = order == "desc" and sort == "file_path"
+ if sort == "file_path":
+ filtered.sort(key=lambda m: m.file_path, reverse=reverse)
+ else:
+ filtered.sort(key=_key, reverse=False)
+
+ total = len(filtered)
+ page = filtered[offset : offset + limit]
+ # Leads only for the page's files — enough to carry the top-reason chip and
+ # the magnitude tiebreak without loading every finding for every row.
+ page_paths = {m.file_path for m in page}
+ findings = await crud.get_health_findings(session, repo_id)
+ leads = _leads_by_file([f for f in findings if f.file_path in page_paths])
+ # Per-file performance signal for the map's performance lens: open perf-
+ # finding counts + whether a perf detector ran on the file's language. Colors
+ # the lens by findings/coverage instead of the uniformly-green [9,10] score.
+ perf_counts: dict[str, int] = {}
+ for fnd in findings:
+ if (getattr(fnd, "dimension", None) or "defect") == "performance":
+ perf_counts[fnd.file_path] = perf_counts.get(fnd.file_path, 0) + 1
+ lang_by_path = await crud.get_file_language_map(session, repo_id)
+ perf_langs = supported_perf_languages()
+ return {
+ "total": total,
+ "offset": offset,
+ "limit": limit,
+ "files": [
+ _metric_to_dict(
+ m,
+ leads.get(m.file_path),
+ perf_findings=perf_counts.get(m.file_path, 0),
+ perf_analyzed=lang_by_path.get(m.file_path) in perf_langs,
+ )
+ for m in page
+ ],
+ }
+
+
[email protected]("/api/repos/{repo_id}/health/files/breakdown")
+async def file_score_breakdown(
+ repo_id: str,
+ file_path: str = Query(..., description="File path to break down"),
+ session: AsyncSession = Depends(get_db_session), # noqa: B008
+) -> dict:
+ repo = await crud.get_repository(session, repo_id)
+ if repo is None:
+ raise HTTPException(status_code=404, detail="Repository not found")
+ metrics = await crud.get_health_metrics(session, repo_id, file_paths=[file_path])
+ metric = metrics[0] if metrics else None
+ findings = await crud.get_health_findings(session, repo_id, file_path=file_path)
+ breakdown = _score_breakdown_from_findings(findings)
+ finding_dicts = await _attach_symbol_ids(
+ session, repo_id, [_finding_to_dict(f) for f in findings]
+ )
+ snapshots = await crud.list_health_snapshots(session, repo_id)
+ return {
+ "file_path": file_path,
+ "metric": _metric_to_dict(metric, _primary_and_magnitude(findings)) if metric else None,
+ "breakdown": breakdown,
+ "findings": finding_dicts,
+ "suggestions": {b: _suggestion_for(b) for b in {f.biomarker_type for f in findings}},
+ "trend": _file_trend_to_dict(file_trend(snapshots, file_path)),
+ "signals": _file_signals_to_dict(await _load_file_signals(session, repo_id, file_path)),
+ }
diff --git a/packages/server/src/repowise/server/routers/code_health/findings_routes.py b/packages/server/src/repowise/server/routers/code_health/findings_routes.py
new file mode 100644
index 000000000..a5cfdc4fd
--- /dev/null
+++ b/packages/server/src/repowise/server/routers/code_health/findings_routes.py
@@ -0,0 +1,62 @@
+"""Findings list + status-update routes."""
+
+from __future__ import annotations
+
+from fastapi import Depends, HTTPException, Query
+from pydantic import BaseModel, Field
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from repowise.core.persistence import crud
+from repowise.server.deps import get_db_session
+
+from ._router import router
+from .loaders import _attach_symbol_ids
+from .serializers import _finding_to_dict
+
+
[email protected]("/api/repos/{repo_id}/health/findings")
+async def list_health_findings(
+ repo_id: str,
+ biomarker_type: str | None = Query(None),
+ file_path: str | None = Query(None),
+ min_severity: str | None = Query(None),
+ dimension: str | None = Query(None),
+ limit: int = Query(100, ge=1, le=1000),
+ session: AsyncSession = Depends(get_db_session), # noqa: B008
+) -> list[dict]:
+ findings = await crud.get_health_findings(
+ session,
+ repo_id,
+ biomarker_type=biomarker_type,
+ file_path=file_path,
+ min_severity=min_severity,
+ dimension=dimension,
+ )
+ return await _attach_symbol_ids(
+ session, repo_id, [_finding_to_dict(f) for f in findings[:limit]]
+ )
+
+
+class FindingStatusUpdate(BaseModel):
+ status: str = Field(..., description="open | acknowledged | resolved | false_positive")
+
+
+_ALLOWED_STATUSES = {"open", "acknowledged", "resolved", "false_positive"}
+
+
[email protected]("/api/repos/{repo_id}/health/findings/{finding_id}")
+async def update_finding_status(
+ repo_id: str,
+ finding_id: str,
+ payload: FindingStatusUpdate,
+ session: AsyncSession = Depends(get_db_session), # noqa: B008
+) -> dict:
+ if payload.status not in _ALLOWED_STATUSES:
+ raise HTTPException(
+ status_code=400, detail=f"status must be one of {sorted(_ALLOWED_STATUSES)}"
+ )
+ f = await crud.update_health_finding_status(session, finding_id, payload.status)
+ if f is None:
+ raise HTTPException(status_code=404, detail="Finding not found")
+ await session.commit()
+ return _finding_to_dict(f)
diff --git a/packages/server/src/repowise/server/routers/code_health/loaders.py b/packages/server/src/repowise/server/routers/code_health/loaders.py
new file mode 100644
index 000000000..ea89958cc
--- /dev/null
+++ b/packages/server/src/repowise/server/routers/code_health/loaders.py
@@ -0,0 +1,80 @@
+"""Async DB helpers: read-only signal joins + symbol-id attachment."""
+
+from __future__ import annotations
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from repowise.core.analysis.health.signals import FileSignals, file_signals
+from repowise.core.persistence import crud
+from repowise.core.persistence.models import WikiSymbol
+
+
+async def _load_file_signals(session: AsyncSession, repo_id: str, file_path: str) -> FileSignals:
+ """Join git metadata + graph degree for one file (read-only, no recompute).
+
+ Degree is read only when the file is a graph node so topology stays "no
+ signal" for files absent from the graph, rather than reporting a spurious
+ zero. Shared by the drawer breakdown and the file-detail aggregate.
+ """
+ git_meta = await crud.get_git_metadata(session, repo_id, file_path)
+ node = await crud.get_graph_node(session, repo_id, file_path)
+ degrees = (
+ await crud.get_node_degree_counts(session, repo_id, file_path) if node is not None else None
+ )
+ return file_signals(git_meta, degrees)
+
+
+async def _attach_symbol_ids(
+ session: AsyncSession, repo_id: str, finding_dicts: list[dict]
+) -> list[dict]:
+ """Attach the matching ``WikiSymbol.symbol_id`` to function-level findings.
+
+ Matched by exact (file_path, function_name), falling back to the symbol
+ whose line span contains the finding's ``line_start`` (covers methods
+ recorded as ``Class.method`` vs the bare symbol name). One query for the
+ whole batch; findings with no match keep ``symbol_id = None`` so the UI
+ can degrade to the file page.
+ """
+ paths = {d["file_path"] for d in finding_dicts if d.get("function_name")}
+ if not paths:
+ return finding_dicts
+ rows = (
+ await session.execute(
+ select(
+ WikiSymbol.symbol_id,
+ WikiSymbol.file_path,
+ WikiSymbol.name,
+ WikiSymbol.start_line,
+ WikiSymbol.end_line,
+ ).where(
+ WikiSymbol.repository_id == repo_id,
+ WikiSymbol.file_path.in_(paths),
+ )
+ )
+ ).all()
+ by_name: dict[tuple[str, str], str] = {}
+ by_file: dict[str, list[tuple[int, int, str]]] = {}
+ for symbol_id, file_path, name, start_line, end_line in rows:
+ by_name.setdefault((file_path, name), symbol_id)
+ if name and "." in name:
+ by_name.setdefault((file_path, name.rsplit(".", 1)[-1]), symbol_id)
+ if start_line is not None and end_line is not None:
+ by_file.setdefault(file_path, []).append((start_line, end_line, symbol_id))
+ for d in finding_dicts:
+ fn = d.get("function_name")
+ if not fn:
+ d["symbol_id"] = None
+ continue
+ sid = by_name.get((d["file_path"], fn))
+ if sid is None and d.get("line_start") is not None:
+ line = d["line_start"]
+ spans = by_file.get(d["file_path"], [])
+ # Narrowest enclosing span wins (a method, not its class).
+ best: tuple[int, str] | None = None
+ for start, end, symbol_id in spans:
+ if start <= line <= end and (best is None or end - start < best[0]):
+ best = (end - start, symbol_id)
+ sid = best[1] if best else None
+ d["symbol_id"] = sid
+ return finding_dicts
diff --git a/packages/server/src/repowise/server/routers/code_health/overview_routes.py b/packages/server/src/repowise/server/routers/code_health/overview_routes.py
new file mode 100644
index 000000000..0e7ffe2ad
--- /dev/null
+++ b/packages/server/src/repowise/server/routers/code_health/overview_routes.py
@@ -0,0 +1,123 @@
+"""Overview + module-rollup routes."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from fastapi import Depends, HTTPException, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from repowise.core.analysis.health.defect_accuracy import compute_defect_accuracy
+from repowise.core.analysis.health.grading import band_for
+from repowise.core.analysis.health.grading import distribution as health_distribution
+from repowise.core.persistence import crud
+from repowise.server.deps import get_db_session
+from repowise.server.mcp_server._meta import resolve_indexed_commit
+
+from ._router import router
+from .aggregation import _biomarker_breakdown, _module_rollups, _severity_breakdown
+from .loaders import _attach_symbol_ids
+from .serializers import _finding_to_dict, _leads_by_file, _metric_to_dict
+
+
+def _resolve_last_indexed_at(
+ snapshot_taken_at: datetime | None, repo_updated_at: datetime | None
+) -> str | None:
+ """Newest "index brought current" time as an ISO string, or ``None``.
+
+ ``last_indexed_at`` should track the last time the index was synced to the
+ checkout, not just the last health snapshot. A no-change ``repowise update``
+ advances ``repositories.updated_at`` but takes no new snapshot, so a
+ snapshot-only value would report the index as hours stale right after a
+ refresh. Prefer whichever timestamp is newer (mirrors the overview router's
+ sync fallback). Both inputs come from the same DB, so their tz-awareness
+ matches and the comparison is safe.
+ """
+ newest = snapshot_taken_at
+ if repo_updated_at is not None and (newest is None or repo_updated_at > newest):
+ newest = repo_updated_at
+ return newest.isoformat() if newest else None
+
+
[email protected]("/api/repos/{repo_id}/health/overview")
+async def health_overview(
+ repo_id: str,
+ limit: int = Query(20, ge=1, le=200),
+ session: AsyncSession = Depends(get_db_session), # noqa: B008
+) -> dict:
+ """KPIs + lowest-scoring files + per-module rollup + meta."""
+ repo = await crud.get_repository(session, repo_id)
+ if repo is None:
+ raise HTTPException(status_code=404, detail="Repository not found")
+ summary = await crud.get_health_summary(session, repo_id)
+ metrics = await crud.get_health_metrics(session, repo_id)
+ findings = await crud.get_health_findings(session, repo_id)
+ snapshots = await crud.list_health_snapshots(session, repo_id)
+
+ # Pull hotspot_health from the latest snapshot (KPIs aren't recomputed
+ # on every overview hit — the snapshot is authoritative).
+ hotspot_health: float | None = None
+ snapshot_taken_at = None
+ if snapshots:
+ latest = snapshots[-1]
+ hotspot_health = round(float(latest.hotspot_health), 2)
+ snapshot_taken_at = latest.taken_at
+
+ last_indexed_at = _resolve_last_indexed_at(snapshot_taken_at, repo.updated_at)
+
+ leads = _leads_by_file(findings)
+ metric_dicts = [_metric_to_dict(m, leads.get(m.file_path)) for m in metrics]
+
+ # Repo-level band (from the NLOC-weighted average) + the per-band file
+ # distribution. Both derive purely from the existing score — no new data.
+ avg = summary.get("average_health")
+ summary = {
+ **summary,
+ "hotspot_health": hotspot_health,
+ "severity_breakdown": _severity_breakdown(findings),
+ "band": band_for(float(avg)) if avg is not None else None,
+ }
+ distribution = health_distribution(metric_dicts)
+
+ # "Does the score find the bugs?" self-validation, derived from the same
+ # metrics + findings (prior_defect biomarker) already loaded above. ``None``
+ # when the repo lacks enough files / defect history to be honest.
+ defect_accuracy = compute_defect_accuracy(
+ [_metric_to_dict(m) for m in metrics],
+ [_finding_to_dict(f) for f in findings],
+ )
+
+ top_findings = await _attach_symbol_ids(
+ session, repo_id, [_finding_to_dict(f) for f in findings[:limit]]
+ )
+
+ return {
+ "summary": summary,
+ "distribution": distribution,
+ "defect_accuracy": defect_accuracy,
+ "files": metric_dicts[:limit],
+ "top_findings": top_findings,
+ "modules": _module_rollups(metrics),
+ "biomarkers": _biomarker_breakdown(findings),
+ "meta": {
+ "last_indexed_at": last_indexed_at,
+ # Prefer state.json's last_sync_commit over a possibly-stale DB row
+ # so the freshness signal self-heals on read (see the /api/repos
+ # overlay). This is the extension's primary indexed-commit source.
+ "head_commit": resolve_indexed_commit(repo.head_commit, repo.local_path),
+ "snapshot_count": len(snapshots),
+ },
+ }
+
+
[email protected]("/api/repos/{repo_id}/health/modules")
+async def health_modules(
+ repo_id: str,
+ session: AsyncSession = Depends(get_db_session), # noqa: B008
+) -> dict:
+ """NLOC-weighted module rollups for the dashboard module section."""
+ repo = await crud.get_repository(session, repo_id)
+ if repo is None:
+ raise HTTPException(status_code=404, detail="Repository not found")
+ metrics = await crud.get_health_metrics(session, repo_id)
+ return {"modules": _module_rollups(metrics)}
diff --git a/packages/server/src/repowise/server/routers/code_health/refactoring_routes.py b/packages/server/src/repowise/server/routers/code_health/refactoring_routes.py
new file mode 100644
index 000000000..55bcb4b3f
--- /dev/null
+++ b/packages/server/src/repowise/server/routers/code_health/refactoring_routes.py
@@ -0,0 +1,113 @@
+"""Refactoring-target ranking route (impact / effort)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import Depends, HTTPException, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from repowise.core.analysis.health.suggestions import suggestion_for as _suggestion_for
+from repowise.core.persistence import crud
+from repowise.server.deps import get_db_session
+
+from ._router import router
+from .aggregation import _clean_module
+from .serializers import _finding_to_dict
+
+_SEVERITY_ORDER = {"low": 0, "medium": 1, "high": 2, "critical": 3}
+
+_EFFORT_BUCKETS: tuple[tuple[int, str], ...] = (
+ (40, "S"),
+ (150, "M"),
+ (400, "L"),
+)
+
+
+def _effort_for_nloc(nloc: int) -> str:
+ for ceiling, label in _EFFORT_BUCKETS:
+ if nloc <= ceiling:
+ return label
+ return "XL"
+
+
[email protected]("/api/repos/{repo_id}/health/refactoring-targets")
+async def refactoring_targets(
+ repo_id: str,
+ limit: int = Query(200, ge=1, le=500),
+ module: str | None = Query(None, description="Filter to files in this module path"),
+ biomarker: str | None = Query(None, description="Filter to one biomarker type"),
+ min_severity: str | None = Query(None),
+ max_effort: str | None = Query(None, description="S | M | L | XL"),
+ sort: str = Query(
+ "impact_per_effort", pattern="^(impact_per_effort|total_impact|score|finding_count)$"
+ ),
+ session: AsyncSession = Depends(get_db_session), # noqa: B008
+) -> dict:
+ """Refactoring candidates ranked by impact / effort."""
+ repo = await crud.get_repository(session, repo_id)
+ if repo is None:
+ raise HTTPException(status_code=404, detail="Repository not found")
+
+ metrics = await crud.get_health_metrics(session, repo_id)
+ metric_by_path = {m.file_path: m for m in metrics}
+ findings = await crud.get_health_findings(session, repo_id)
+
+ by_file: dict[str, list[Any]] = {}
+ for f in findings:
+ if biomarker and f.biomarker_type != biomarker:
+ continue
+ if min_severity:
+ order = _SEVERITY_ORDER
+ if order.get(f.severity, 0) < order.get(min_severity, 0):
+ continue
+ by_file.setdefault(f.file_path, []).append(f)
+
+ effort_rank = {"S": 1, "M": 2, "L": 3, "XL": 5}
+ max_effort_rank = effort_rank.get(max_effort or "", 99)
+
+ targets: list[dict] = []
+ for file_path, fs in by_file.items():
+ if module and not file_path.startswith(module):
+ continue
+ m = metric_by_path.get(file_path)
+ nloc = m.nloc if m is not None else 0
+ score = m.score if m is not None else 10.0
+ primary = max(fs, key=lambda x: x.health_impact)
+ total_impact = round(sum(x.health_impact for x in fs), 3)
+ effort_bucket = _effort_for_nloc(nloc)
+ if effort_rank[effort_bucket] > max_effort_rank:
+ continue
+ weight = effort_rank[effort_bucket]
+ ratio = round(total_impact / weight, 3)
+ targets.append(
+ {
+ "file_path": file_path,
+ "score": round(score, 2),
+ "nloc": nloc,
+ "module": _clean_module(m.module) if (m and m.module) else None,
+ "primary_biomarker": primary.biomarker_type,
+ "primary_severity": primary.severity,
+ "primary_reason": primary.reason,
+ "primary_function": primary.function_name,
+ "primary_line_start": primary.line_start,
+ "primary_line_end": primary.line_end,
+ "primary_suggestion": _suggestion_for(primary.biomarker_type),
+ "primary_finding_id": primary.id,
+ "total_impact": total_impact,
+ "finding_count": len(fs),
+ "biomarkers": sorted({x.biomarker_type for x in fs}),
+ "effort_bucket": effort_bucket,
+ "impact_per_effort": ratio,
+ "all_findings": [_finding_to_dict(f) for f in fs],
+ }
+ )
+
+ sort_key_map = {
+ "impact_per_effort": lambda t: (-t["impact_per_effort"], -t["total_impact"]),
+ "total_impact": lambda t: -t["total_impact"],
+ "score": lambda t: t["score"],
+ "finding_count": lambda t: -t["finding_count"],
+ }
+ targets.sort(key=sort_key_map[sort])
+ return {"targets": targets[:limit], "total": len(targets)}
diff --git a/packages/server/src/repowise/server/routers/code_health/serializers.py b/packages/server/src/repowise/server/routers/code_health/serializers.py
new file mode 100644
index 000000000..06d114ec5
--- /dev/null
+++ b/packages/server/src/repowise/server/routers/code_health/serializers.py
@@ -0,0 +1,159 @@
+"""Pure wire-shape helpers: ORM rows / dataclasses -> JSON-able dicts."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from repowise.core.analysis.health.signals import FileSignals
+from repowise.core.analysis.health.trends import FileTrend
+
+
+def _finding_to_dict(f: Any) -> dict:
+ try:
+ details = json.loads(f.details_json) if f.details_json else {}
+ except Exception:
+ details = {}
+ return {
+ "id": f.id,
+ "file_path": f.file_path,
+ "biomarker_type": f.biomarker_type,
+ "severity": f.severity,
+ "function_name": f.function_name,
+ "line_start": f.line_start,
+ "line_end": f.line_end,
+ "health_impact": round(f.health_impact, 3),
+ "reason": f.reason,
+ "details": details,
+ "status": f.status,
+ # Pillar the finding homes under (defect / maintainability / performance)
+ # so the UI can filter findings per dimension. Defaults to defect for
+ # rows that predate the split.
+ "dimension": getattr(f, "dimension", None) or "defect",
+ }
+
+
+def _round_opt(v: Any) -> float | None:
+ """Round a nullable per-dimension score, preserving ``None`` (not measured)."""
+ return round(v, 2) if v is not None else None
+
+
+def _primary_and_magnitude(findings: list[Any]) -> dict:
+ """Dominant cause + pre-clamp deduction magnitude for one file's findings.
+
+ Two presentation signals the score alone can't carry:
+
+ - ``primary_biomarker`` / ``primary_reason`` — the single worst finding, so a
+ low file can lead with "the one reason" instead of a wall of markers.
+ - ``total_deduction`` — the summed (pre-floor) ``health_impact``. Equal to
+ the breakdown endpoint's ``total_deduction`` (each finding's stored impact
+ is already the applied, capped value), so it distinguishes two files that
+ both floor at 1.0 (a -25 file from a -9 one) without touching ``score``.
+
+ All-null on an empty list: a clean file has no lead and no magnitude.
+ """
+ if not findings:
+ return {"primary_biomarker": None, "primary_reason": None, "total_deduction": None}
+ primary = max(findings, key=lambda x: x.health_impact)
+ total = sum(float(x.health_impact or 0.0) for x in findings)
+ return {
+ "primary_biomarker": primary.biomarker_type,
+ "primary_reason": primary.reason,
+ "total_deduction": round(total, 3),
+ }
+
+
+def _leads_by_file(findings: list[Any]) -> dict[str, dict]:
+ """Group findings by file and reduce each group to its dominant-cause lead."""
+ by_file: dict[str, list[Any]] = {}
+ for f in findings:
+ by_file.setdefault(f.file_path, []).append(f)
+ return {path: _primary_and_magnitude(fs) for path, fs in by_file.items()}
+
+
+def _metric_to_dict(
+ m: Any,
+ lead: dict | None = None,
+ *,
+ perf_findings: int = 0,
+ perf_analyzed: bool | None = None,
+) -> dict:
+ return {
+ "file_path": m.file_path,
+ "score": round(m.score, 2),
+ "max_ccn": m.max_ccn,
+ "max_nesting": m.max_nesting,
+ "nloc": m.nloc,
+ "has_test_file": m.has_test_file,
+ "line_coverage_pct": m.line_coverage_pct,
+ "module": m.module,
+ "duplication_pct": getattr(m, "duplication_pct", None),
+ # Per-dimension scores from the three-signal split. ``score`` above stays
+ # the overall surfaced number (== defect_score for now).
+ # ``performance_score`` is computed but not yet surfaced as its own pillar.
+ "defect_score": _round_opt(getattr(m, "defect_score", None)),
+ "maintainability_score": _round_opt(getattr(m, "maintainability_score", None)),
+ "performance_score": _round_opt(getattr(m, "performance_score", None)),
+ # Performance lens inputs for the code-health map: the open perf-finding
+ # count colors the heat, and ``perf_analyzed`` (did a detector run on this
+ # language?) separates green ("analyzed, none found") from grey ("never
+ # looked"). Presentation only — the score above is untouched.
+ "performance_findings": perf_findings,
+ "performance_analyzed": perf_analyzed,
+ # Dominant-cause lead + pre-clamp magnitude (null when findings weren't
+ # loaded for this row, or the file is clean). Additive; readers degrade.
+ "primary_biomarker": lead.get("primary_biomarker") if lead else None,
+ "primary_reason": lead.get("primary_reason") if lead else None,
+ "total_deduction": lead.get("total_deduction") if lead else None,
+ }
+
+
+def _file_trend_to_dict(t: FileTrend) -> dict:
+ """Wire shape for ``FileHealthTrend`` (types/health.ts). ``points`` is
+ empty on thin history so the UI shows a "no history yet" state."""
+ return {
+ "file_path": t.file_path,
+ "points": [
+ {
+ "taken_at": p.taken_at.isoformat() if p.taken_at else None,
+ "score": round(p.score, 2),
+ }
+ for p in t.points
+ ],
+ "current": t.current,
+ "previous": t.previous,
+ "delta": t.delta,
+ "declining": t.declining,
+ "snapshot_count": t.snapshot_count,
+ }
+
+
+def _file_signals_to_dict(s: FileSignals) -> dict:
+ """Wire shape for ``FileSignals`` (types/health.ts). Each value is null
+ when its source row is absent so the UI shows "no signal", never a
+ misleading zero. ``change_entropy_pct`` is 0-100 (the column is 0-1)."""
+ return {
+ "prior_defect_count": s.prior_defect_count,
+ "change_entropy_pct": s.change_entropy_pct,
+ "lines_added_90d": s.lines_added_90d,
+ "lines_deleted_90d": s.lines_deleted_90d,
+ "commit_count_90d": s.commit_count_90d,
+ "age_days": s.age_days,
+ "primary_owner_name": s.primary_owner_name,
+ "primary_owner_commit_pct": s.primary_owner_commit_pct,
+ "recent_owner_name": s.recent_owner_name,
+ "recent_owner_commit_pct": s.recent_owner_commit_pct,
+ "in_degree": s.in_degree,
+ "out_degree": s.out_degree,
+ }
+
+
+def _churn_complexity_to_dict(p: Any) -> dict:
+ return {
+ "file_path": p.file_path,
+ "commit_count_90d": p.commit_count_90d,
+ "max_ccn": p.max_ccn,
+ "nloc": p.nloc,
+ "score": p.score,
+ "churn_percentile": p.churn_percentile,
+ }
diff --git a/packages/server/src/repowise/server/routers/code_health/trends_routes.py b/packages/server/src/repowise/server/routers/code_health/trends_routes.py
new file mode 100644
index 000000000..4249d5070
--- /dev/null
+++ b/packages/server/src/repowise/server/routers/code_health/trends_routes.py
@@ -0,0 +1,90 @@
+"""File-level + repo-level health trend routes."""
+
+from __future__ import annotations
+
+import json
+
+from fastapi import Depends, HTTPException, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from repowise.core.analysis.health.trends import diff_snapshots, file_trend, recent_kpis
+from repowise.core.persistence import crud
+from repowise.server.deps import get_db_session
+
+from ._router import router
+from .serializers import _file_trend_to_dict
+
+
[email protected]("/api/repos/{repo_id}/health/files/trend")
+async def file_health_trend(
+ repo_id: str,
+ file_path: str = Query(..., description="File path to chart over time"),
+ session: AsyncSession = Depends(get_db_session), # noqa: B008
+) -> dict:
+ """A single file's score-over-time series from the snapshot history.
+
+ Silent (empty ``points``) when fewer than two snapshots carry the file.
+ """
+ repo = await crud.get_repository(session, repo_id)
+ if repo is None:
+ raise HTTPException(status_code=404, detail="Repository not found")
+ snapshots = await crud.list_health_snapshots(session, repo_id)
+ return _file_trend_to_dict(file_trend(snapshots, file_path))
+
+
[email protected]("/api/repos/{repo_id}/health/trend")
+async def health_trend(
+ repo_id: str,
+ limit: int = Query(20, ge=1, le=50),
+ session: AsyncSession = Depends(get_db_session), # noqa: B008
+) -> dict:
+ repo = await crud.get_repository(session, repo_id)
+ if repo is None:
+ raise HTTPException(status_code=404, detail="Repository not found")
+ snapshots = await crud.list_health_snapshots(session, repo_id)
+ summary = diff_snapshots(snapshots)
+
+ # Per-file delta from the last two snapshots.
+ file_deltas: list[dict] = []
+ if len(snapshots) >= 2:
+ try:
+ prev = json.loads(snapshots[-2].per_file_scores_json or "{}")
+ cur = json.loads(snapshots[-1].per_file_scores_json or "{}")
+ except Exception:
+ prev, cur = {}, {}
+ all_paths = set(prev) | set(cur)
+ for p in all_paths:
+ before = prev.get(p)
+ after = cur.get(p)
+ if before is None or after is None:
+ continue
+ d = round(float(after) - float(before), 2)
+ if d == 0:
+ continue
+ file_deltas.append({"file_path": p, "before": before, "after": after, "delta": d})
+ file_deltas.sort(key=lambda r: r["delta"])
+
+ return {
+ "history": recent_kpis(snapshots, limit=limit),
+ "summary": {
+ "current_hotspot_health": summary.current_hotspot_health,
+ "current_average_health": summary.current_average_health,
+ "previous_hotspot_health": summary.previous_hotspot_health,
+ "previous_average_health": summary.previous_average_health,
+ "hotspot_delta": summary.hotspot_delta,
+ "average_delta": summary.average_delta,
+ },
+ "alerts": [
+ {
+ "kind": a.kind,
+ "metric": a.metric,
+ "current": a.current,
+ "baseline": a.baseline,
+ "delta": a.delta,
+ "message": a.message,
+ }
+ for a in summary.alerts
+ ],
+ "file_deltas": file_deltas[:50],
+ "snapshot_count": len(snapshots),
+ }