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(overview): build the overview summary from section functions (#3979)

Raghav Chamadiyac668fde04199
diff --git a/packages/server/src/repowise/server/routers/overview.py b/packages/server/src/repowise/server/routers/overview.py
index 34ef2cd10..f162718a7 100644
--- a/packages/server/src/repowise/server/routers/overview.py
+++ b/packages/server/src/repowise/server/routers/overview.py
@@ -9,41 +9,18 @@ decisions slice, savings headline, and health KPIs.
from __future__ import annotations
-import asyncio
-import contextlib
-import json
-from pathlib import Path
from typing import Any
from fastapi import APIRouter, Depends, HTTPException
-from sqlalchemy import func, select
+from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
-from repowise.core.analysis.health.aggregation import (
- severity_breakdown as health_severity_breakdown,
-)
-from repowise.core.analysis.health.grading import headline_band
-from repowise.core.analysis.health.scoring import hotspot_health
from repowise.core.forges import read_remote_url, strip_credentials
from repowise.core.persistence import crud
-from repowise.core.persistence.crud.analysis.queue_counts import unit_counts
-from repowise.core.persistence.crud.analysis.shown import ungated
-from repowise.core.persistence.models import (
- DeadCodeFinding,
- GenerationJob,
- GitMetadata,
- GraphNode,
- Page,
-)
-from repowise.core.stats_highlights import file_mix
+from repowise.core.persistence.models import GitMetadata
from repowise.server.deps import get_db_session, verify_api_key
from repowise.server.routers.git import _hotspot_from_row
-from repowise.server.services.attention import build_attention
-from repowise.server.services.knowledge_map import (
- compute_knowledge_silos,
- compute_onboarding_targets,
-)
-from repowise.server.services.module_health import top_level_module
+from repowise.server.services import overview_payload as sections
router = APIRouter(
prefix="/api/repos",
@@ -56,34 +33,6 @@ router = APIRouter(
HEALTH_HISTORY_POINTS = 12
-def _walk_index_storage_bytes(repowise_dir: Path) -> int:
- """Total on-disk size of a repo's ``.repowise/`` directory."""
- if not repowise_dir.is_dir():
- return 0
- total = 0
- for path in repowise_dir.rglob("*"):
- if path.is_file():
- with contextlib.suppress(OSError):
- total += path.stat().st_size
- return total
-
-
-async def _index_storage_bytes(repowise_dir: Path) -> int:
- """``_walk_index_storage_bytes`` off the event loop.
-
- The walk is a full recursive stat of a directory that holds the vectors,
- the wiki and the symbol store, so it is routinely hundreds of megabytes and
- tens of thousands of files. Run inline in an ``async def`` it does not just
- make this request slow: it blocks the worker's event loop for its whole
- duration, stalling every other request in flight.
-
- Ceiling: a thread is the cheap fix, and the walk still happens once per
- page load. The real fix is to stamp the size when the index is written and
- read the number back; do that if this ever shows up in a profile again.
- """
- return await asyncio.to_thread(_walk_index_storage_bytes, repowise_dir)
-
-
def _remote_url(stored_url: str | None, local_path: str | None) -> str | None:
"""Best-effort git remote for a repo, with any credentials removed.
@@ -101,49 +50,24 @@ def _remote_url(stored_url: str | None, local_path: str | None) -> str | None:
return strip_credentials(url) if url else None
-def _decision_slim(d: Any) -> dict:
- return {
- "id": d.id,
- "title": d.title,
- "status": d.status,
- "source": d.source,
- "created_at": d.created_at.isoformat() if d.created_at else None,
- "staleness_score": round(float(d.staleness_score or 0.0), 3),
- }
-
-
-async def _savings_headline(repo_local_path: str | None) -> dict:
- """Savings headline for the overview, from the one core report service.
-
- Headline figures only -- no breakdowns and no transcript scan, which reads
- agent transcripts and is far too slow for an overview payload. Every field
- here comes from the same report the savings endpoint and ``repowise saved``
- read, so the three cannot drift. They previously did, in four separate
- ways, because each aggregated and priced the ledger for itself.
-
- The measured/inferred and priced/unpriced splits travel beside the total on
- purpose. A lone headline reads as one confident number, and the evidence
- behind it is not uniform.
- """
- if not repo_local_path:
- return {"available": False}
-
- from repowise.core.savings.service import load_report
-
- report = load_report(repo_local_path)
- if report is None:
- return {"available": False}
- return {
- "available": True,
- "saved_input_tokens": report.saved_input_tokens,
- "measured_saved_input_tokens": report.measured_saved_input_tokens,
- "inferred_saved_input_tokens": report.inferred_saved_input_tokens,
- "priced_saved_input_tokens": report.priced_saved_input_tokens,
- "unpriced_saved_input_tokens": report.unpriced_saved_input_tokens,
- "estimated_usd_saved": report.priced_input_savings_usd,
- "mcp_queries_answered": report.mcp_queries_answered,
- "last_event_at": report.last_event_at,
- }
+async def _top_hotspots(session: AsyncSession, repo_id: str) -> list[dict[str, Any]]:
+ # Here rather than in the service: rows are shaped by the git router's helper.
+ rows = (
+ (
+ await session.execute(
+ select(GitMetadata)
+ .where(GitMetadata.repository_id == repo_id, GitMetadata.is_hotspot.is_(True))
+ .order_by(
+ GitMetadata.temporal_hotspot_score.desc().nulls_last(),
+ GitMetadata.churn_percentile.desc(),
+ )
+ .limit(8)
+ )
+ )
+ .scalars()
+ .all()
+ )
+ return [_hotspot_from_row(r).model_dump(mode="json") for r in rows]
@router.get("/{repo_id}/overview-summary")
@@ -156,320 +80,20 @@ async def overview_summary(
if repo is None:
raise HTTPException(status_code=404, detail="Repository not found")
- # --- Stat strip ------------------------------------------------------
- file_count = (
- await session.scalar(
- select(func.count(GraphNode.id)).where(
- GraphNode.repository_id == repo_id, GraphNode.node_type == "file"
- )
- )
- or 0
- )
- symbol_count = int(
- await session.scalar(
- select(func.sum(GraphNode.symbol_count)).where(GraphNode.repository_id == repo_id)
- )
- or 0
- )
- entry_point_count = (
- await session.scalar(
- select(func.count(GraphNode.id)).where(
- GraphNode.repository_id == repo_id,
- GraphNode.is_entry_point.is_(True),
- )
- )
- or 0
- )
- avg_confidence = float(
- await session.scalar(select(func.avg(Page.confidence)).where(Page.repository_id == repo_id))
- or 0.0
- )
- doc_coverage_pct = avg_confidence * 100
- total_pages = (
- await session.scalar(select(func.count(Page.id)).where(Page.repository_id == repo_id)) or 0
- )
- # Pages a model actually wrote, as opposed to the ones assembled from the
- # index alone. The discriminator is the provider: "template" is the stub
- # writer, so anything else means a real generation call produced the prose.
- #
- # Deliberately NOT additionally scoped to MODEL_WRITTEN_PAGE_TYPES. That
- # narrower query looks more principled and is a lie in practice: file and
- # symbol pages do get generated with a real provider on some runs, so
- # scoping by type puts model-written pages in the "assembled from the index"
- # bucket. Asking the question the honest way — did a model write this page —
- # needs no page-type carve-out, and the answer stays true whatever the
- # generator does next.
- #
- # Note a stubbed page (a provider call that failed and fell back) counts as
- # not-prose, which is correct: it has no prose.
- prose_pages = (
- await session.scalar(
- select(func.count(Page.id)).where(
- Page.repository_id == repo_id,
- Page.provider_name.is_not(None),
- Page.provider_name != "template",
- )
- )
- or 0
- )
- fresh_pages = (
- await session.scalar(
- select(func.count(Page.id)).where(
- Page.repository_id == repo_id, Page.freshness_status == "fresh"
- )
- )
- or 0
- )
- freshness_score = (fresh_pages / total_pages * 100) if total_pages > 0 else doc_coverage_pct
- dead_export_count = (
- await session.scalar(
- select(func.count(DeadCodeFinding.id)).where(
- DeadCodeFinding.repository_id == repo_id,
- DeadCodeFinding.kind == "unused_export",
- DeadCodeFinding.status == "open",
- ungated("dead_code", DeadCodeFinding.file_path, DeadCodeFinding.kind),
- )
- )
- or 0
- )
- hotspot_count = (
- await session.scalar(
- select(func.count(GitMetadata.id)).where(
- GitMetadata.repository_id == repo_id,
- GitMetadata.is_hotspot.is_(True),
- )
- )
- or 0
- )
-
- # Module-level silo counts (top-level-directory grouping — mirrors the
- # /ownership?granularity=module aggregation the page used to fetch).
- owner_rows = await session.execute(
- select(GitMetadata.file_path, GitMetadata.primary_owner_name).where(
- crud.code_file_rows(repo_id)
- )
- )
- module_owner_files: dict[str, dict[str, int]] = {}
- module_file_totals: dict[str, int] = {}
- for fp, owner in owner_rows:
- module = top_level_module(fp)
- module_file_totals[module] = module_file_totals.get(module, 0) + 1
- if owner:
- bucket = module_owner_files.setdefault(module, {})
- bucket[owner] = bucket.get(owner, 0) + 1
- silo_count = 0
- for module, owners in module_owner_files.items():
- top = max(owners.values(), default=0)
- if module_file_totals.get(module) and top / module_file_totals[module] > 0.8:
- silo_count += 1
-
- # Languages and module count come from the one rule Stats uses, so the two
- # pages cannot disagree on either number.
- # One narrow row per file node, not a GROUP BY: module_count needs paths. Fine to
- # ~100k files; past that, count languages in SQL and fetch only code paths.
- node_rows = await session.execute(
- select(GraphNode.node_id, GraphNode.language, GraphNode.external_system_id).where(
- GraphNode.repository_id == repo_id, GraphNode.node_type == "file"
- )
- )
- mix = file_mix(row._mapping for row in node_rows)
- module_count = mix["module_count"]
- languages = mix["languages"]
-
- # --- Health KPIs + deltas vs previous snapshot ------------------------
- # Loaded once and handed to both consumers below: the KPI rollup and the
- # defect-accuracy stat both want every per-file row, and letting each fetch
- # its own pulled the whole table twice per page load.
+ stats = await sections.stat_strip(session, repo_id)
+ mix = await sections.language_mix(session, repo_id)
+ # Loaded once and shared by the KPI rollup, the defect-accuracy stat and
+ # ``total_nloc``.
health_metrics = await crud.get_health_metrics(session, repo_id)
- # Every figure here is a KPI the scores counted, so the file-held rows stay
- # in; ``health.gated`` says what the finding lists leave out.
- findings = await crud.get_health_findings(session, repo_id, file_holds=False)
- health_summary = await crud.get_health_summary(
- session, repo_id, metrics=health_metrics, findings=findings
- )
# Three scopes, three reads. This payload wants the *count* of retained
# snapshots, the newest ``HEALTH_HISTORY_POINTS`` rows' scalars for the
# sparkline, and the newest two rows' per-file maps for the file-count
- # delta — and nothing else. Loading the history as entities to get that
- # pulled every row's ``per_file_scores_json``: 2.8 MB on this index, ~9 MB
- # at the retention cap, for 375 KB of actual use. Capping the read at two
- # rows instead would be wrong in two visible ways — it would flatten the
- # sparkline and report a snapshot count of 2.
+ # delta. Loading the history as entities pulled every row's
+ # ``per_file_scores_json`` (MBs per page load); capping the read at two rows
+ # would flatten the sparkline and report a snapshot count of 2.
snapshot = await crud.get_health_snapshot_headline(
session, repo_id, recent=HEALTH_HISTORY_POINTS
)
- # The headline is the *current* number, so it comes from the metrics loaded
- # above rather than off the newest snapshot: ``repowise update`` re-scores
- # health without writing a snapshot, so the stored value can lag the rows
- # every other figure on this page is built from. Costs no extra query.
- #
- # ``history`` and ``deltas`` below stay snapshot-derived on purpose. They
- # are a series of recorded runs, and there is no live value for "the run
- # before this one", so the delta means "since the last recorded snapshot".
- hotspot_paths = await crud.get_hotspot_file_paths(session, repo_id)
- hotspot_health_value = hotspot_health(health_metrics, hotspot_paths)
- last_indexed_at: str | None = None
- deltas: dict[str, float | None] = {
- "average_health": None,
- "hotspot_health": None,
- "file_count": None,
- }
- if snapshot.snapshot_count:
- last_indexed_at = snapshot.taken_at.isoformat() if snapshot.taken_at else None
- if len(snapshot.recent) >= 2:
- prev, cur = snapshot.recent[-2], snapshot.recent[-1]
- deltas["average_health"] = round(cur.average_health - prev.average_health, 2)
- if cur.hotspot_health is not None and prev.hotspot_health is not None:
- deltas["hotspot_health"] = round(cur.hotspot_health - prev.hotspot_health, 2)
- file_counts = await crud.get_health_snapshot_file_counts(session, repo_id, limit=2)
- if len(file_counts) == 2 and all(file_counts):
- deltas["file_count"] = file_counts[1] - file_counts[0]
-
- severity_breakdown = health_severity_breakdown(findings)
-
- # "Can you trust this score?" — the backtested precision of the defect
- # ranking, shown on the health card. Sourced here rather than from the stats
- # payload: this is a health number, and having the overview reach across
- # into another page's payload for it is what broke when that payload changed.
- #
- # ``prior_defect`` rows only, each carrying its parsed ``details``. Two
- # problems in one shape: the stat reads no other biomarker, so converting
- # the other ~90% of findings was waste; and it reads the fix count and the
- # window *out of* ``details``, which this call site never supplied — so
- # every flagged file reported ``recent_fixes: 1`` (333 of 999 have more, up
- # to 19) and ``window_days`` echoed the default instead of the indexed
- # value. The health dashboard computes the same stat from the real numbers,
- # so the two surfaces disagreed on one figure.
- # Parsed per row: one malformed blob must not cost the whole panel.
- prior_defect_rows: list[dict] = []
- for f in findings:
- if f.biomarker_type != "prior_defect":
- continue
- details: Any = {}
- with contextlib.suppress(Exception):
- details = json.loads(f.details_json) if f.details_json else {}
- prior_defect_rows.append(
- {
- "file_path": f.file_path,
- "biomarker_type": f.biomarker_type,
- "details": details,
- }
- )
-
- defect_accuracy = None
- try:
- from repowise.core.analysis.health.defect_accuracy import compute_defect_accuracy
- from repowise.core.analysis.health.ranking import deduction_by_path
-
- defect_accuracy = compute_defect_accuracy(
- [
- {
- "file_path": m.file_path,
- "score": m.score,
- "nloc": m.nloc,
- "has_test_file": m.has_test_file,
- "module": m.module,
- }
- for m in health_metrics
- ],
- prior_defect_rows,
- deductions=deduction_by_path(findings),
- )
- except Exception:
- # Best-effort: the card omits the panel rather than failing the page.
- defect_accuracy = None
-
- # --- Attention items + onboarding targets -----------------------------
- decision_health = await crud.get_decision_health_summary(session, repo_id)
- # Silos only. The full knowledge map also computes top owners and
- # onboarding targets, and paying for those here meant loading the content
- # of every generated page to count its words for a list this page does not
- # render.
- knowledge_silos = await compute_knowledge_silos(session, repo_id)
- # Read by the first-index experience. Its own call rather than the full
- # knowledge map, which would also aggregate owners this payload never uses.
- onboarding_targets = await compute_onboarding_targets(session, repo_id)
- # Every finding store, merged and ranked worst-first. This used to read
- # three stores and rank them by which store they came from; see
- # `core/analysis/attention` for what changed and why.
- attention_result = await build_attention(
- session,
- repo_id,
- decision_health=decision_health,
- knowledge_silos=knowledge_silos,
- )
- attention = attention_result["items"]
-
- # --- Top hotspots + recent decisions slices ---------------------------
- hotspot_rows = (
- (
- await session.execute(
- select(GitMetadata)
- .where(GitMetadata.repository_id == repo_id, GitMetadata.is_hotspot.is_(True))
- .order_by(
- GitMetadata.temporal_hotspot_score.desc().nulls_last(),
- GitMetadata.churn_percentile.desc(),
- )
- .limit(8)
- )
- )
- .scalars()
- .all()
- )
- top_hotspots = [_hotspot_from_row(r).model_dump(mode="json") for r in hotspot_rows]
-
- decisions = await crud.list_decisions(session, repo_id, limit=8)
- recent_decisions = [_decision_slim(d) for d in decisions]
-
- # --- Sync status (last completed jobs + any active one) ---------------
- job_rows = (
- (
- await session.execute(
- select(GenerationJob)
- .where(GenerationJob.repository_id == repo_id)
- .order_by(GenerationJob.created_at.desc())
- .limit(30)
- )
- )
- .scalars()
- .all()
- )
- last_sync_at: str | None = None
- last_resync_at: str | None = None
- last_resync_dt = None
- last_sync_model: str | None = None
- active_job_id: str | None = None
- for j in job_rows:
- try:
- mode = json.loads(j.config_json or "{}").get("mode")
- except Exception:
- mode = None
- if j.status in ("pending", "running") and active_job_id is None:
- active_job_id = j.id
- if j.status == "completed" and j.finished_at:
- if mode == "full_resync" and last_resync_at is None:
- last_resync_at = j.finished_at.isoformat()
- last_resync_dt = j.finished_at
- elif mode != "full_resync" and last_sync_at is None:
- last_sync_at = j.finished_at.isoformat()
- last_sync_model = j.model_name or None
-
- # Fall back to the repository's own ``updated_at`` when no completed
- # server-side sync job exists. CLI / git-hook auto-syncs (``repowise
- # update``) refresh the index and bump ``repositories.updated_at`` via
- # ``upsert_repository``, but never create a GenerationJob row, so a
- # job-only derivation reports "never synced" even though the index is
- # current. Only adopt it when it is newer than the last full re-index so a
- # re-index is not relabelled as a sync.
- if (
- last_sync_at is None
- and repo.updated_at is not None
- and (last_resync_dt is None or repo.updated_at > last_resync_dt)
- ):
- last_sync_at = repo.updated_at.isoformat()
-
- savings = await _savings_headline(repo.local_path)
- repowise_dir = Path(repo.local_path) / ".repowise" if repo.local_path else Path(".repowise")
# The same indexed commit as /api/repos and /health/overview: state.json
# and the row reconciled, the row's own value when the two diverge.
@@ -488,87 +112,24 @@ async def overview_summary(
"remote_url": _remote_url(repo.url, repo.local_path),
},
"stats": {
- "file_count": file_count,
- "symbol_count": symbol_count,
- "entry_point_count": entry_point_count,
- "doc_page_count": total_pages,
- "doc_prose_page_count": prose_pages,
- "doc_coverage_pct": doc_coverage_pct,
- "freshness_score": freshness_score,
- "dead_export_count": dead_export_count,
- "hotspot_count": hotspot_count,
- "silo_count": silo_count,
- "module_count": module_count,
- # Summed from the health metrics already loaded above, so it costs
- # nothing. It is here because Overview's only use for the whole
- # Stats "By the Numbers" endpoint was this one figure, and that
- # endpoint runs its own commit-history pass; its docstring says it
- # is scoped for its own page. Matches the field hosted's backend
- # already serves.
+ **stats,
+ "silo_count": await sections.module_silo_count(session, repo_id),
+ "module_count": mix["module_count"],
+ # Summed from the health metrics already loaded, so it costs
+ # nothing. Overview's only use for the whole Stats "By the Numbers"
+ # endpoint was this one figure, and that endpoint runs its own
+ # commit-history pass. Matches the field hosted's backend serves.
"total_nloc": sum(int(m.nloc or 0) for m in health_metrics),
- "deltas": deltas,
+ "deltas": await sections.snapshot_deltas(session, repo_id, snapshot),
},
- "health": {
- "average_health": health_summary.get("average_health"),
- # Files in a language health has no dialect for: in no figure here.
- "unanalysed_file_count": health_summary.get("unanalysed_file_count", 0),
- "analysed_share": health_summary.get("analysed_share"),
- # ``None`` when too few code files were analysed to grade the repo.
- "band": headline_band(
- health_summary.get("average_health"), health_summary.get("analysed_share")
- ),
- "hotspot_health": hotspot_health_value,
- "worst_performer_path": health_summary.get("worst_performer_path"),
- "worst_performer_score": health_summary.get("worst_performer_score"),
- "open_findings": health_summary.get("open_findings", 0),
- # The findings' count vocabulary, which the Code Health page and the
- # agent surfaces report too; ``open_findings`` stays for older readers.
- "finding_counts": (await unit_counts(session, repo_id, "findings")).as_dict(),
- # Why the finding lists hold some of those back, by language or file hold.
- "gated": await crud.gated_health_counts(session, repo_id),
- # The two co-equal pillars surfaced alongside the defect headline.
- "maintainability_average": health_summary.get("maintainability_average"),
- "performance_average": health_summary.get("performance_average"),
- "performance_findings": health_summary.get("performance_findings", 0),
- "worst_performance_path": health_summary.get("worst_performance_path"),
- "worst_performance_score": health_summary.get("worst_performance_score"),
- "severity_breakdown": severity_breakdown,
- "defect_accuracy": defect_accuracy,
- "last_indexed_at": last_indexed_at,
- # The true total, not the length of the windowed read above.
- "snapshot_count": snapshot.snapshot_count,
- "history": [
- {
- "taken_at": s.taken_at.isoformat() if s.taken_at else None,
- "average_health": round(s.average_health, 2),
- "hotspot_health": (
- round(s.hotspot_health, 2) if s.hotspot_health is not None else None
- ),
- }
- for s in snapshot.recent
- ],
- },
- "languages": languages,
+ "health": await sections.health_block(session, repo_id, health_metrics, snapshot),
+ "languages": mix["languages"],
"docs_config_languages": mix["docs_config_languages"],
- "attention": attention,
- # Counts for everything the sources hold, beside the capped list. The
- # page shows five rows out of these, and "5 open" would be a lie that
- # gets worse the more findings a repository has.
- "attention_summary": {
- "total": attention_result["total"],
- "by_source": attention_result["by_source"],
- "areas": attention_result["areas"],
- },
- "onboarding_targets": onboarding_targets,
- "top_hotspots": top_hotspots,
- "recent_decisions": recent_decisions,
- "savings": savings,
- "sync": {
- "last_sync_at": last_sync_at,
- "last_resync_at": last_resync_at,
- "last_sync_model": last_sync_model,
- "active_job_id": active_job_id,
- "page_count": total_pages,
- "index_storage_bytes": await _index_storage_bytes(repowise_dir),
- },
+ **await sections.attention_block(session, repo_id),
+ "top_hotspots": await _top_hotspots(session, repo_id),
+ "recent_decisions": await sections.recent_decisions(session, repo_id),
+ "savings": await sections.savings_block(repo.local_path),
+ "sync": await sections.sync_block(
+ session, repo_id, repo, page_count=stats["doc_page_count"]
+ ),
}
diff --git a/packages/server/src/repowise/server/services/overview_payload.py b/packages/server/src/repowise/server/services/overview_payload.py
new file mode 100644
index 000000000..699d7545a
--- /dev/null
+++ b/packages/server/src/repowise/server/services/overview_payload.py
@@ -0,0 +1,500 @@
+"""Section builders for ``/api/repos/{repo_id}/overview-summary``.
+
+Each function reads and shapes one block of the Overview payload. The router
+assembles them in its fixed key order; a private consumer mirrors that
+payload field for field, so a builder's keys and their order are its contract.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+from pathlib import Path
+from typing import Any
+
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from repowise.core.analysis.health.aggregation import (
+ severity_breakdown as health_severity_breakdown,
+)
+from repowise.core.analysis.health.grading import headline_band
+from repowise.core.analysis.health.scoring import hotspot_health
+from repowise.core.persistence import crud
+from repowise.core.persistence.crud.analysis.queue_counts import unit_counts
+from repowise.core.persistence.crud.analysis.shown import ungated
+from repowise.core.persistence.models import (
+ DeadCodeFinding,
+ GenerationJob,
+ GitMetadata,
+ GraphNode,
+ Page,
+)
+from repowise.core.stats_highlights import file_mix
+from repowise.server.services.attention import build_attention
+from repowise.server.services.knowledge_map import (
+ compute_knowledge_silos,
+ compute_onboarding_targets,
+)
+from repowise.server.services.module_health import top_level_module
+
+
+async def _count(session: AsyncSession, stmt: Any) -> int:
+ return await session.scalar(stmt) or 0
+
+
+async def docs_split(session: AsyncSession, repo_id: str) -> dict:
+ """Page counts, model-written share, coverage and freshness."""
+ avg_confidence = float(
+ await session.scalar(select(func.avg(Page.confidence)).where(Page.repository_id == repo_id))
+ or 0.0
+ )
+ doc_coverage_pct = avg_confidence * 100
+ total_pages = await _count(
+ session, select(func.count(Page.id)).where(Page.repository_id == repo_id)
+ )
+ # Pages a model actually wrote, as opposed to the ones assembled from the
+ # index alone. The discriminator is the provider: "template" is the stub
+ # writer, so anything else means a real generation call produced the prose.
+ #
+ # Deliberately NOT additionally scoped to MODEL_WRITTEN_PAGE_TYPES: file and
+ # symbol pages do get generated with a real provider on some runs, so
+ # scoping by type puts model-written pages in the "assembled from the index"
+ # bucket. Asking "did a model write this page" needs no page-type carve-out.
+ #
+ # A stubbed page (a provider call that failed and fell back) counts as
+ # not-prose, which is correct: it has no prose.
+ prose_pages = await _count(
+ session,
+ select(func.count(Page.id)).where(
+ Page.repository_id == repo_id,
+ Page.provider_name.is_not(None),
+ Page.provider_name != "template",
+ ),
+ )
+ fresh_pages = await _count(
+ session,
+ select(func.count(Page.id)).where(
+ Page.repository_id == repo_id, Page.freshness_status == "fresh"
+ ),
+ )
+ return {
+ "doc_page_count": total_pages,
+ "doc_prose_page_count": prose_pages,
+ "doc_coverage_pct": doc_coverage_pct,
+ "freshness_score": (
+ (fresh_pages / total_pages * 100) if total_pages > 0 else doc_coverage_pct
+ ),
+ }
+
+
+async def stat_strip(session: AsyncSession, repo_id: str) -> dict:
+ """Graph, docs, dead-export and hotspot counts, in payload order."""
+ file_count = await _count(
+ session,
+ select(func.count(GraphNode.id)).where(
+ GraphNode.repository_id == repo_id, GraphNode.node_type == "file"
+ ),
+ )
+ symbol_count = int(
+ await session.scalar(
+ select(func.sum(GraphNode.symbol_count)).where(GraphNode.repository_id == repo_id)
+ )
+ or 0
+ )
+ entry_point_count = await _count(
+ session,
+ select(func.count(GraphNode.id)).where(
+ GraphNode.repository_id == repo_id,
+ GraphNode.is_entry_point.is_(True),
+ ),
+ )
+ docs = await docs_split(session, repo_id)
+ dead_export_count = await _count(
+ session,
+ select(func.count(DeadCodeFinding.id)).where(
+ DeadCodeFinding.repository_id == repo_id,
+ DeadCodeFinding.kind == "unused_export",
+ DeadCodeFinding.status == "open",
+ ungated("dead_code", DeadCodeFinding.file_path, DeadCodeFinding.kind),
+ ),
+ )
+ hotspot_count = await _count(
+ session,
+ select(func.count(GitMetadata.id)).where(
+ GitMetadata.repository_id == repo_id,
+ GitMetadata.is_hotspot.is_(True),
+ ),
+ )
+ return {
+ "file_count": file_count,
+ "symbol_count": symbol_count,
+ "entry_point_count": entry_point_count,
+ **docs,
+ "dead_export_count": dead_export_count,
+ "hotspot_count": hotspot_count,
+ }
+
+
+def count_silos(rows: Any) -> int:
+ """Top-level modules where one owner holds over 80% of the files.
+
+ Mirrors the ``/ownership?granularity=module`` aggregation the page used to
+ fetch. ``rows`` are ``(file_path, primary_owner_name)`` pairs.
+ """
+ module_owner_files: dict[str, dict[str, int]] = {}
+ module_file_totals: dict[str, int] = {}
+ for fp, owner in rows:
+ module = top_level_module(fp)
+ module_file_totals[module] = module_file_totals.get(module, 0) + 1
+ if owner:
+ bucket = module_owner_files.setdefault(module, {})
+ bucket[owner] = bucket.get(owner, 0) + 1
+ silo_count = 0
+ for module, owners in module_owner_files.items():
+ top = max(owners.values(), default=0)
+ if module_file_totals.get(module) and top / module_file_totals[module] > 0.8:
+ silo_count += 1
+ return silo_count
+
+
+async def module_silo_count(session: AsyncSession, repo_id: str) -> int:
+ owner_rows = await session.execute(
+ select(GitMetadata.file_path, GitMetadata.primary_owner_name).where(
+ crud.code_file_rows(repo_id)
+ )
+ )
+ return count_silos(owner_rows)
+
+
+async def language_mix(session: AsyncSession, repo_id: str) -> dict:
+ """Languages and module count, from the one rule Stats uses.
+
+ So the two pages cannot disagree on either number. One narrow row per file
+ node, not a GROUP BY: module_count needs paths. Fine to ~100k files; past
+ that, count languages in SQL and fetch only code paths.
+ """
+ node_rows = await session.execute(
+ select(GraphNode.node_id, GraphNode.language, GraphNode.external_system_id).where(
+ GraphNode.repository_id == repo_id, GraphNode.node_type == "file"
+ )
+ )
+ return file_mix(row._mapping for row in node_rows)
+
+
+async def snapshot_deltas(session: AsyncSession, repo_id: str, snapshot: Any) -> dict:
+ """Stat-strip deltas between the two newest recorded snapshots.
+
+ Snapshot-derived on purpose: there is no live value for "the run before
+ this one", so a delta means "since the last recorded snapshot".
+ """
+ deltas: dict[str, float | None] = {
+ "average_health": None,
+ "hotspot_health": None,
+ "file_count": None,
+ }
+ if len(snapshot.recent) >= 2:
+ prev, cur = snapshot.recent[-2], snapshot.recent[-1]
+ deltas["average_health"] = round(cur.average_health - prev.average_health, 2)
+ if cur.hotspot_health is not None and prev.hotspot_health is not None:
+ deltas["hotspot_health"] = round(cur.hotspot_health - prev.hotspot_health, 2)
+ file_counts = await crud.get_health_snapshot_file_counts(session, repo_id, limit=2)
+ if len(file_counts) == 2 and all(file_counts):
+ deltas["file_count"] = file_counts[1] - file_counts[0]
+ return deltas
+
+
+def defect_accuracy(health_metrics: list[Any], findings: list[Any]) -> dict | None:
+ """Backtested precision of the defect ranking ("can you trust this score?").
+
+ Sourced here rather than from the stats payload: this is a health number,
+ and reaching into another page's payload for it is what broke when that
+ payload changed.
+
+ ``prior_defect`` rows only, each carrying its parsed ``details``. The stat
+ reads no other biomarker, and it reads the fix count and the window out of
+ ``details``; without them every flagged file reported ``recent_fixes: 1``
+ and ``window_days`` echoed the default, so this card disagreed with the
+ health dashboard on the same figure. Parsed per row: one malformed blob
+ must not cost the whole panel.
+ """
+ prior_defect_rows: list[dict] = []
+ for f in findings:
+ if f.biomarker_type != "prior_defect":
+ continue
+ details: Any = {}
+ with contextlib.suppress(Exception):
+ details = json.loads(f.details_json) if f.details_json else {}
+ prior_defect_rows.append(
+ {
+ "file_path": f.file_path,
+ "biomarker_type": f.biomarker_type,
+ "details": details,
+ }
+ )
+ try:
+ from repowise.core.analysis.health.defect_accuracy import compute_defect_accuracy
+ from repowise.core.analysis.health.ranking import deduction_by_path
+
+ return compute_defect_accuracy(
+ [
+ {
+ "file_path": m.file_path,
+ "score": m.score,
+ "nloc": m.nloc,
+ "has_test_file": m.has_test_file,
+ "module": m.module,
+ }
+ for m in health_metrics
+ ],
+ prior_defect_rows,
+ deductions=deduction_by_path(findings),
+ )
+ except Exception:
+ # Best-effort: the card omits the panel rather than failing the page.
+ return None
+
+
+def snapshot_history(snapshot: Any) -> list[dict]:
+ return [
+ {
+ "taken_at": s.taken_at.isoformat() if s.taken_at else None,
+ "average_health": round(s.average_health, 2),
+ "hotspot_health": (round(s.hotspot_health, 2) if s.hotspot_health is not None else None),
+ }
+ for s in snapshot.recent
+ ]
+
+
+async def health_block(
+ session: AsyncSession, repo_id: str, health_metrics: list[Any], snapshot: Any
+) -> dict:
+ """Health KPIs, the defect-accuracy stat and the snapshot trend.
+
+ ``health_metrics`` is loaded once by the caller and shared: the KPI rollup
+ and the defect-accuracy stat both want every per-file row, and letting each
+ fetch its own pulled the whole table twice per page load.
+
+ The headline is the *current* number, so it comes from the metrics rather
+ than the newest snapshot: ``repowise update`` re-scores health without
+ writing a snapshot, so the stored value can lag the rows every other figure
+ on this page is built from. ``history`` stays snapshot-derived: it is a
+ series of recorded runs.
+ """
+ # Every figure here is a KPI the scores counted, so the file-held rows stay
+ # in; ``gated`` says what the finding lists leave out.
+ findings = await crud.get_health_findings(session, repo_id, file_holds=False)
+ summary = await crud.get_health_summary(
+ session, repo_id, metrics=health_metrics, findings=findings
+ )
+ hotspot_paths = await crud.get_hotspot_file_paths(session, repo_id)
+ last_indexed_at = (
+ snapshot.taken_at.isoformat() if snapshot.snapshot_count and snapshot.taken_at else None
+ )
+ return {
+ "average_health": summary.get("average_health"),
+ # Files in a language health has no dialect for: in no figure here.
+ "unanalysed_file_count": summary.get("unanalysed_file_count", 0),
+ "analysed_share": summary.get("analysed_share"),
+ # ``None`` when too few code files were analysed to grade the repo.
+ "band": headline_band(summary.get("average_health"), summary.get("analysed_share")),
+ "hotspot_health": hotspot_health(health_metrics, hotspot_paths),
+ "worst_performer_path": summary.get("worst_performer_path"),
+ "worst_performer_score": summary.get("worst_performer_score"),
+ "open_findings": summary.get("open_findings", 0),
+ # The findings' count vocabulary, which the Code Health page and the
+ # agent surfaces report too; ``open_findings`` stays for older readers.
+ "finding_counts": (await unit_counts(session, repo_id, "findings")).as_dict(),
+ # Why the finding lists hold some of those back, by language or file hold.
+ "gated": await crud.gated_health_counts(session, repo_id),
+ # The two co-equal pillars surfaced alongside the defect headline.
+ "maintainability_average": summary.get("maintainability_average"),
+ "performance_average": summary.get("performance_average"),
+ "performance_findings": summary.get("performance_findings", 0),
+ "worst_performance_path": summary.get("worst_performance_path"),
+ "worst_performance_score": summary.get("worst_performance_score"),
+ "severity_breakdown": health_severity_breakdown(findings),
+ "defect_accuracy": defect_accuracy(health_metrics, findings),
+ "last_indexed_at": last_indexed_at,
+ # The true total, not the length of the windowed read.
+ "snapshot_count": snapshot.snapshot_count,
+ "history": snapshot_history(snapshot),
+ }
+
+
+async def attention_block(session: AsyncSession, repo_id: str) -> dict:
+ """``attention``, ``attention_summary`` and ``onboarding_targets``."""
+ decision_health = await crud.get_decision_health_summary(session, repo_id)
+ # Silos only. The full knowledge map also computes top owners and
+ # onboarding targets, and paying for those here meant loading the content
+ # of every generated page to count its words for a list this page does not
+ # render.
+ knowledge_silos = await compute_knowledge_silos(session, repo_id)
+ # Read by the first-index experience. Its own call rather than the full
+ # knowledge map, which would also aggregate owners this payload never uses.
+ onboarding_targets = await compute_onboarding_targets(session, repo_id)
+ # Every finding store, merged and ranked worst-first; see
+ # `core/analysis/attention` for the ranking.
+ result = await build_attention(
+ session,
+ repo_id,
+ decision_health=decision_health,
+ knowledge_silos=knowledge_silos,
+ )
+ return {
+ "attention": result["items"],
+ # Counts for everything the sources hold, beside the capped list. The
+ # page shows five rows out of these, and "5 open" would be a lie that
+ # gets worse the more findings a repository has.
+ "attention_summary": {
+ "total": result["total"],
+ "by_source": result["by_source"],
+ "areas": result["areas"],
+ },
+ "onboarding_targets": onboarding_targets,
+ }
+
+
+def decision_slim(d: Any) -> dict:
+ return {
+ "id": d.id,
+ "title": d.title,
+ "status": d.status,
+ "source": d.source,
+ "created_at": d.created_at.isoformat() if d.created_at else None,
+ "staleness_score": round(float(d.staleness_score or 0.0), 3),
+ }
+
+
+async def recent_decisions(session: AsyncSession, repo_id: str) -> list[dict]:
+ return [decision_slim(d) for d in await crud.list_decisions(session, repo_id, limit=8)]
+
+
+async def savings_block(repo_local_path: str | None) -> dict:
+ """Savings headline, from the one core report service.
+
+ Headline figures only: no breakdowns and no transcript scan, which reads
+ agent transcripts and is far too slow for an overview payload. Every field
+ comes from the same report the savings endpoint and ``repowise saved``
+ read, so the three cannot drift. They previously did, in four separate
+ ways, because each aggregated and priced the ledger for itself.
+
+ The measured/inferred and priced/unpriced splits travel beside the total on
+ purpose. A lone headline reads as one confident number, and the evidence
+ behind it is not uniform.
+ """
+ if not repo_local_path:
+ return {"available": False}
+
+ from repowise.core.savings.service import load_report
+
+ report = load_report(repo_local_path)
+ if report is None:
+ return {"available": False}
+ return {
+ "available": True,
+ "saved_input_tokens": report.saved_input_tokens,
+ "measured_saved_input_tokens": report.measured_saved_input_tokens,
+ "inferred_saved_input_tokens": report.inferred_saved_input_tokens,
+ "priced_saved_input_tokens": report.priced_saved_input_tokens,
+ "unpriced_saved_input_tokens": report.unpriced_saved_input_tokens,
+ "estimated_usd_saved": report.priced_input_savings_usd,
+ "mcp_queries_answered": report.mcp_queries_answered,
+ "last_event_at": report.last_event_at,
+ }
+
+
+def walk_index_storage_bytes(repowise_dir: Path) -> int:
+ """Total on-disk size of a repo's ``.repowise/`` directory."""
+ if not repowise_dir.is_dir():
+ return 0
+ total = 0
+ for path in repowise_dir.rglob("*"):
+ if path.is_file():
+ with contextlib.suppress(OSError):
+ total += path.stat().st_size
+ return total
+
+
+async def index_storage_bytes(repowise_dir: Path) -> int:
+ """``walk_index_storage_bytes`` off the event loop.
+
+ The walk is a full recursive stat of a directory that holds the vectors,
+ the wiki and the symbol store, routinely hundreds of megabytes and tens of
+ thousands of files. Run inline in an ``async def`` it blocks the worker's
+ event loop for its whole duration, stalling every other request in flight.
+
+ Ceiling: a thread is the cheap fix, and the walk still happens once per
+ page load. The real fix is to stamp the size when the index is written and
+ read the number back; do that if this ever shows up in a profile again.
+ """
+ return await asyncio.to_thread(walk_index_storage_bytes, repowise_dir)
+
+
+def sync_times(job_rows: list[Any], repo_updated_at: Any) -> dict:
+ """Last sync, last full re-index, its model and any active job id.
+
+ ``job_rows`` are newest first.
+ """
+ last_sync_at: str | None = None
+ last_resync_at: str | None = None
+ last_resync_dt = None
+ last_sync_model: str | None = None
+ active_job_id: str | None = None
+ for j in job_rows:
+ try:
+ mode = json.loads(j.config_json or "{}").get("mode")
+ except Exception:
+ mode = None
+ if j.status in ("pending", "running") and active_job_id is None:
+ active_job_id = j.id
+ if j.status == "completed" and j.finished_at:
+ if mode == "full_resync" and last_resync_at is None:
+ last_resync_at = j.finished_at.isoformat()
+ last_resync_dt = j.finished_at
+ elif mode != "full_resync" and last_sync_at is None:
+ last_sync_at = j.finished_at.isoformat()
+ last_sync_model = j.model_name or None
+
+ # Fall back to the repository's own ``updated_at`` when no completed
+ # server-side sync job exists. CLI / git-hook auto-syncs (``repowise
+ # update``) refresh the index and bump ``repositories.updated_at`` via
+ # ``upsert_repository``, but never create a GenerationJob row, so a
+ # job-only derivation reports "never synced" even though the index is
+ # current. Only adopt it when it is newer than the last full re-index so a
+ # re-index is not relabelled as a sync.
+ if (
+ last_sync_at is None
+ and repo_updated_at is not None
+ and (last_resync_dt is None or repo_updated_at > last_resync_dt)
+ ):
+ last_sync_at = repo_updated_at.isoformat()
+ return {
+ "last_sync_at": last_sync_at,
+ "last_resync_at": last_resync_at,
+ "last_sync_model": last_sync_model,
+ "active_job_id": active_job_id,
+ }
+
+
+async def sync_block(session: AsyncSession, repo_id: str, repo: Any, page_count: int) -> dict:
+ """Sync status from the last 30 jobs, plus page count and index size."""
+ job_rows = (
+ (
+ await session.execute(
+ select(GenerationJob)
+ .where(GenerationJob.repository_id == repo_id)
+ .order_by(GenerationJob.created_at.desc())
+ .limit(30)
+ )
+ )
+ .scalars()
+ .all()
+ )
+ repowise_dir = Path(repo.local_path) / ".repowise" if repo.local_path else Path(".repowise")
+ return {
+ **sync_times(job_rows, repo.updated_at),
+ "page_count": page_count,
+ "index_storage_bytes": await index_storage_bytes(repowise_dir),
+ }
diff --git a/tests/unit/ingestion/test_fs_walk.py b/tests/unit/ingestion/test_fs_walk.py
index d1efe3fb5..b4a8d8a3d 100644
--- a/tests/unit/ingestion/test_fs_walk.py
+++ b/tests/unit/ingestion/test_fs_walk.py
@@ -560,7 +560,7 @@ _WALK_ALLOWLIST: dict[tuple[str, str], frozenset[str]] = {
# Scans repowise's own packaged web/ui source dirs, not the user repo.
("cli", "commands/serve_cmd.py"): frozenset({"rglob"}),
# Sizes .repowise/ only — repowise-owned, cannot contain junk trees.
- ("server", "routers/overview.py"): frozenset({"rglob"}),
+ ("server", "services/overview_payload.py"): frozenset({"rglob"}),
}
diff --git a/tests/unit/server/test_health_aggregation_delegation.py b/tests/unit/server/test_health_aggregation_delegation.py
index e0169eedb..f951bea61 100644
--- a/tests/unit/server/test_health_aggregation_delegation.py
+++ b/tests/unit/server/test_health_aggregation_delegation.py
@@ -41,8 +41,8 @@ _FINDINGS = [
def test_the_repo_overview_shares_the_severity_fold_too() -> None:
- """A fourth copy of this lived in ``routers/overview.py``."""
- from repowise.server.routers.overview import health_severity_breakdown
+ """A fourth copy of this lived in the overview-summary route."""
+ from repowise.server.services.overview_payload import health_severity_breakdown
assert health_severity_breakdown is core.severity_breakdown
diff --git a/tests/unit/server/test_overview_payload_sections.py b/tests/unit/server/test_overview_payload_sections.py
new file mode 100644
index 000000000..f65f3bee0
--- /dev/null
+++ b/tests/unit/server/test_overview_payload_sections.py
@@ -0,0 +1,72 @@
+"""Pure section builders of ``services/overview_payload``."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from types import SimpleNamespace
+
+from repowise.server.services.overview_payload import (
+ count_silos,
+ defect_accuracy,
+ snapshot_history,
+ sync_times,
+)
+
+_T0 = datetime(2026, 9, 1, tzinfo=UTC)
+_T1 = datetime(2026, 9, 2, tzinfo=UTC)
+_T2 = datetime(2026, 9, 3, tzinfo=UTC)
+
+
+def test_count_silos_needs_one_owner_over_80_percent_of_files() -> None:
+ rows = [("a/x.py", "ann")] * 5 + [("b/x.py", "ann"), ("b/y.py", "bob"), ("c/z.py", None)]
+ assert count_silos(rows) == 1
+
+
+def _job(status: str, mode: str | None, finished_at=None, **kw):
+ config = "{}" if mode is None else f'{{"mode": "{mode}"}}'
+ return SimpleNamespace(
+ id=kw.get("id", "j"),
+ status=status,
+ config_json=config,
+ finished_at=finished_at,
+ model_name=kw.get("model_name"),
+ )
+
+
+def test_sync_times_splits_resync_from_sync_and_finds_active_job() -> None:
+ jobs = [
+ _job("running", None, id="active"),
+ _job("completed", "full_resync", _T2),
+ _job("completed", "incremental", _T1, model_name="m1"),
+ ]
+ assert sync_times(jobs, None) == {
+ "last_sync_at": _T1.isoformat(),
+ "last_resync_at": _T2.isoformat(),
+ "last_sync_model": "m1",
+ "active_job_id": "active",
+ }
+
+
+def test_sync_times_falls_back_to_repo_updated_at_only_after_resync() -> None:
+ resync = [_job("completed", "full_resync", _T1)]
+ assert sync_times(resync, _T2)["last_sync_at"] == _T2.isoformat()
+ assert sync_times(resync, _T0)["last_sync_at"] is None
+ assert sync_times([], _T0)["last_sync_at"] == _T0.isoformat()
+
+
+def test_defect_accuracy_survives_a_malformed_details_blob() -> None:
+ metric = SimpleNamespace(file_path="a.py", score=3.0, nloc=10, has_test_file=False, module="a")
+ bad = SimpleNamespace(
+ file_path="a.py", biomarker_type="prior_defect", details_json="{not json", health_impact=1.0
+ )
+ # Must not raise; the panel is best-effort.
+ defect_accuracy([metric], [bad])
+
+
+def test_snapshot_history_rounds_and_keeps_missing_hotspot_none() -> None:
+ snap = SimpleNamespace(
+ recent=[SimpleNamespace(taken_at=None, average_health=7.456, hotspot_health=None)]
+ )
+ assert snapshot_history(snap) == [
+ {"taken_at": None, "average_health": 7.46, "hotspot_health": None}
+ ]