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.

feat(overview): docs counts with AI/auto split, denser health card (#879)

Raghav Chamadiya09de0694a893
diff --git a/packages/server/src/repowise/server/routers/overview.py b/packages/server/src/repowise/server/routers/overview.py
index c9a49e7b7..1f64193c9 100644
--- a/packages/server/src/repowise/server/routers/overview.py
+++ b/packages/server/src/repowise/server/routers/overview.py
@@ -214,6 +214,17 @@ async def overview_summary(
total_pages = (
await session.scalar(select(func.count(Page.id)).where(Page.repository_id == repo_id)) or 0
)
+ # Template-provider pages are the deterministic coverage tail (zero LLM);
+ # everything else came out of a model. Same discriminator the page schema
+ # uses for the "Auto" badge.
+ auto_pages = (
+ await session.scalar(
+ select(func.count(Page.id)).where(
+ Page.repository_id == repo_id, Page.provider_name == "template"
+ )
+ )
+ or 0
+ )
fresh_pages = (
await session.scalar(
select(func.count(Page.id)).where(
@@ -406,6 +417,8 @@ async def overview_summary(
"file_count": file_count,
"symbol_count": symbol_count,
"entry_point_count": entry_point_count,
+ "doc_page_count": total_pages,
+ "doc_auto_page_count": auto_pages,
"doc_coverage_pct": doc_coverage_pct,
"freshness_score": freshness_score,
"dead_export_count": dead_export_count,
diff --git a/packages/types/src/overview.ts b/packages/types/src/overview.ts
index cf2c57c78..cd56e3982 100644
--- a/packages/types/src/overview.ts
+++ b/packages/types/src/overview.ts
@@ -33,6 +33,19 @@ export interface OverviewStats {
file_count: number;
symbol_count: number;
entry_point_count: number;
+ /**
+ * Total generated wiki pages. Optional: a server that predates this field
+ * omits it, and hosted bumps the ui/types packages independently of its
+ * backend deploy — treat absent as unknown rather than rendering NaN.
+ */
+ doc_page_count?: number;
+ /**
+ * Of `doc_page_count`, the deterministic template-generated ("Auto") pages —
+ * the zero-LLM coverage tail. AI-written pages are the remainder. Both sides
+ * derive this from the page's `provider_name === "template"`, the same
+ * discriminator behind the "Auto" badge.
+ */
+ doc_auto_page_count?: number;
doc_coverage_pct: number;
freshness_score: number;
dead_export_count: number;
diff --git a/packages/ui/__tests__/dashboard/index-storage-mini.test.tsx b/packages/ui/__tests__/dashboard/index-storage-mini.test.tsx
index cb72f8a2a..9ae8650f0 100644
--- a/packages/ui/__tests__/dashboard/index-storage-mini.test.tsx
+++ b/packages/ui/__tests__/dashboard/index-storage-mini.test.tsx
@@ -3,7 +3,7 @@ import { render, screen } from "@testing-library/react";
import { IndexStorageMini } from "../../src/dashboard/index-storage-mini";
describe("IndexStorageMini", () => {
- it("renders formatted storage and doc coverage", () => {
+ it("renders formatted storage and average doc confidence", () => {
render(
<IndexStorageMini
data={{
@@ -16,6 +16,6 @@ describe("IndexStorageMini", () => {
expect(screen.getByText("Index storage")).toBeInTheDocument();
expect(screen.getByText("1.5 MB")).toBeInTheDocument();
- expect(screen.getByText(/87% doc coverage/)).toBeInTheDocument();
+ expect(screen.getByText(/87% avg doc confidence/)).toBeInTheDocument();
});
});
diff --git a/packages/ui/src/dashboard/health-overview-card.tsx b/packages/ui/src/dashboard/health-overview-card.tsx
index 8d1367274..2992b28d3 100644
--- a/packages/ui/src/dashboard/health-overview-card.tsx
+++ b/packages/ui/src/dashboard/health-overview-card.tsx
@@ -7,6 +7,7 @@ import {
ArrowRight,
Wrench,
Gauge,
+ Target,
} from "lucide-react";
import { Card, CardContent, CardHeader, CardTitle } from "../ui/card";
import { fileEntityPath } from "../shared/entity/routes";
@@ -41,12 +42,33 @@ export interface HealthOverviewData {
snapshot_count: number;
}
+/**
+ * Structural slice of the defect-accuracy rollup this card needs. Matches the
+ * slim `StatsDefectAccuracy` from stats-highlights as well as the full
+ * `DefectAccuracy` from health/overview, so either payload fits.
+ */
+export interface HealthOverviewAccuracy {
+ /** How many of the K lowest-health files were bug-fixed in the window. */
+ hits: number;
+ k: number;
+ /** Precision over the repo-wide base rate; null when not computable. */
+ lift: number | null;
+ base_rate: number;
+ window_days: number;
+}
+
interface HealthOverviewCardProps {
data: HealthOverviewData;
repoId: string;
/** Delta vs the previous snapshot (1–10 scale); drives the trend chips. */
averageDelta?: number | null;
hotspotDelta?: number | null;
+ /**
+ * "Does this score find the bugs?" validation, rendered as a thin strip under
+ * the scores. Null/omitted when the repo lacks enough files or defect history
+ * to answer honestly — in which case the strip hides rather than guessing.
+ */
+ defectAccuracy?: HealthOverviewAccuracy | null;
className?: string;
}
@@ -85,63 +107,49 @@ function TrendChip({ delta }: { delta: number | null | undefined }) {
);
}
-/** Severity-mix donut whose center is the open-findings headline count. */
-function SeverityDonut({
+/**
+ * Open findings as one quiet line: label, a thin severity-mix bar, and the
+ * count. Findings are a secondary read next to the health scores above, so this
+ * deliberately stays a single row — no donut, no headline number, no legend
+ * block. The severity split lives in the segment tooltips and, in full, one
+ * click away on the triage tab.
+ */
+function FindingsLine({
+ href,
segments,
total,
count,
}: {
+ href: string;
segments: { key: string; count: number; color: string }[];
total: number;
count: number;
}) {
- const size = 88;
- const stroke = 10;
- const radius = (size - stroke) / 2;
- const circ = 2 * Math.PI * radius;
- let offset = 0;
-
return (
- <div className="relative shrink-0" style={{ width: size, height: size }}>
- <svg width={size} height={size} className="-rotate-90">
- <circle
- cx={size / 2}
- cy={size / 2}
- r={radius}
- fill="none"
- stroke="var(--color-bg-inset)"
- strokeWidth={stroke}
- />
- {total > 0 &&
- segments.map((s) => {
- const len = (s.count / total) * circ;
- const dash = `${len} ${circ - len}`;
- const el = (
- <circle
- key={s.key}
- cx={size / 2}
- cy={size / 2}
- r={radius}
- fill="none"
- stroke={s.color}
- strokeWidth={stroke}
- strokeDasharray={dash}
- strokeDashoffset={-offset}
- />
- );
- offset += len;
- return el;
- })}
- </svg>
- <div className="absolute inset-0 flex flex-col items-center justify-center">
- <span className="text-lg font-bold tabular-nums leading-none text-[var(--color-text-primary)]">
- {count.toLocaleString()}
- </span>
- <span className="text-[10px] uppercase tracking-wider text-[var(--color-text-tertiary)]">
- findings
- </span>
- </div>
- </div>
+ <a
+ href={href}
+ className="group flex items-center gap-3 text-xs text-[var(--color-text-tertiary)] transition-colors hover:text-[var(--color-accent-primary)]"
+ >
+ <span className="flex shrink-0 items-center gap-1.5 font-medium uppercase tracking-wider">
+ <ShieldAlert className="h-3 w-3" />
+ Open findings
+ </span>
+ <span
+ className="flex h-1.5 min-w-0 flex-1 overflow-hidden rounded-full bg-[var(--color-bg-inset)]"
+ title={segments.map((s) => `${s.key}: ${s.count.toLocaleString()}`).join(" · ")}
+ >
+ {segments.map((s) => (
+ <span
+ key={s.key}
+ className="h-full"
+ style={{ width: `${(s.count / total) * 100}%`, background: s.color }}
+ />
+ ))}
+ </span>
+ <span className="shrink-0 tabular-nums text-[var(--color-text-secondary)]">
+ {count.toLocaleString()}
+ </span>
+ </a>
);
}
@@ -202,6 +210,39 @@ function MetricTile({
);
}
+/**
+ * Thin self-validation strip: of the K lowest-health files, how many actually
+ * got bug-fixed in the recent window, against the repo's own base rate. The
+ * scores above are a claim; this is the one line that says whether the claim
+ * holds on *this* repo. Full breakdown (per-K table, the flagged files, the
+ * honesty note) lives on the Code Health page.
+ */
+function AccuracyStrip({ data, href }: { data: HealthOverviewAccuracy; href: string }) {
+ const months = Math.max(1, Math.round(data.window_days / 30));
+ const windowLabel = months === 1 ? "month" : `${months} months`;
+ const basePct = Math.round(data.base_rate * 100);
+
+ return (
+ <a
+ href={href}
+ className="group flex flex-wrap items-center gap-x-2 gap-y-0.5 border-t border-[var(--color-border-default)] px-4 py-2.5 text-xs transition-colors hover:bg-[var(--color-bg-elevated)]"
+ >
+ <Target className="h-3 w-3 shrink-0 text-[var(--color-accent-primary)]" aria-hidden />
+ <span className="font-medium text-[var(--color-text-secondary)]">
+ <span className="tabular-nums text-[var(--color-text-primary)]">
+ {data.hits}/{data.k}
+ </span>{" "}
+ lowest-health files were bug-fixed in the last {windowLabel}
+ </span>
+ {data.lift != null && (
+ <span className="font-semibold tabular-nums text-[var(--color-accent-primary)]">
+ {data.lift}× the {basePct}% baseline
+ </span>
+ )}
+ </a>
+ );
+}
+
/**
* Code Health hero for the Overview page — the product's moat surfaced first.
* Renders the repo-wide biomarker health and hotspot health (1–10, with trend
@@ -214,6 +255,7 @@ export function HealthOverviewCard({
repoId,
averageDelta,
hotspotDelta,
+ defectAccuracy,
className,
}: HealthOverviewCardProps) {
const reportHref = `/repos/${repoId}/code-health`;
@@ -275,38 +317,28 @@ export function HealthOverviewCard({
/>
</div>
+ {/* The scores above, checked against this repo's own git history. */}
+ {defectAccuracy && (
+ <AccuracyStrip data={defectAccuracy} href={`${reportHref}?tab=triage`} />
+ )}
+
{/* Findings + worst performer */}
<div className="px-4 py-3.5 space-y-3">
- <a
- href={`${reportHref}?tab=triage`}
- className="flex items-center gap-1.5 text-xs font-medium uppercase tracking-wider text-[var(--color-text-tertiary)] hover:text-[var(--color-accent-primary)] transition-colors"
- >
- <ShieldAlert className="h-3 w-3" />
- Open findings
- </a>
-
{severityTotal > 0 ? (
- <div className="flex items-center gap-4">
- <SeverityDonut
- segments={severities}
- total={severityTotal}
- count={data.open_findings}
- />
- <div className="flex flex-col gap-1">
- {severities.map((s) => (
- <span
- key={s.key}
- className="flex items-center gap-1.5 text-xs text-[var(--color-text-secondary)] capitalize"
- >
- <span className="h-2 w-2 rounded-full" style={{ background: s.color }} />
- {s.key}
- <span className="tabular-nums text-[var(--color-text-tertiary)]">{s.count}</span>
- </span>
- ))}
- </div>
- </div>
+ <FindingsLine
+ href={`${reportHref}?tab=triage`}
+ segments={severities}
+ total={severityTotal}
+ count={data.open_findings}
+ />
) : (
- <p className="text-xs text-[var(--color-success)]">No open findings — clean bill of health.</p>
+ <a
+ href={`${reportHref}?tab=triage`}
+ className="flex items-center gap-1.5 text-xs text-[var(--color-success)] hover:underline"
+ >
+ <ShieldAlert className="h-3 w-3" />
+ No open findings — clean bill of health.
+ </a>
)}
{data.worst_performer_path && data.worst_performer_score != null && (
diff --git a/packages/ui/src/dashboard/index-storage-mini.tsx b/packages/ui/src/dashboard/index-storage-mini.tsx
index 48ae81c25..3187bda44 100644
--- a/packages/ui/src/dashboard/index-storage-mini.tsx
+++ b/packages/ui/src/dashboard/index-storage-mini.tsx
@@ -7,7 +7,11 @@ export interface IndexStorageMiniData {
index_storage_bytes: number;
/** Wiki page count — used for a secondary line when docs exist. */
page_count?: number;
- /** Average doc confidence as 0–100 — shown when pages exist. */
+ /**
+ * Average doc *confidence* as 0–100. Named `doc_coverage_pct` for the wire
+ * contract, but it is a mean page confidence, not a share of files covered —
+ * so it is labelled as confidence here rather than coverage.
+ */
doc_coverage_pct?: number;
}
@@ -21,7 +25,7 @@ interface IndexStorageMiniProps {
*/
export function IndexStorageMini({ data }: IndexStorageMiniProps) {
const hasDocs = (data.page_count ?? 0) > 0;
- const coverage =
+ const confidence =
data.doc_coverage_pct != null ? formatPercent(data.doc_coverage_pct / 100) : null;
return (
@@ -39,7 +43,7 @@ export function IndexStorageMini({ data }: IndexStorageMiniProps) {
</span>
<p className="text-xs text-[var(--color-text-tertiary)]">
wiki.db + vectors on disk
- {hasDocs && coverage ? ` · ${coverage} doc coverage` : ""}
+ {hasDocs && confidence ? ` · ${confidence} avg doc confidence` : ""}
</p>
</div>
</CardContent>
diff --git a/packages/ui/src/dashboard/kpi-strip.tsx b/packages/ui/src/dashboard/kpi-strip.tsx
index 3cdeade6d..71f48c45b 100644
--- a/packages/ui/src/dashboard/kpi-strip.tsx
+++ b/packages/ui/src/dashboard/kpi-strip.tsx
@@ -5,6 +5,8 @@ export interface KpiItem {
label: string;
value: string;
href: string;
+ /** One-line context beneath the value (e.g. an AI-vs-auto docs split). */
+ description?: string;
/**
* `positive` is a *good-vs-bad* flag (green/up vs red/down), NOT up-vs-down:
* a metric can grow while still being neutral or bad. Set `neutral` to render
@@ -73,6 +75,7 @@ export function KpiStrip({ items, LinkComponent, className }: KpiStripProps) {
label={kpi.label}
value={kpi.value}
href={kpi.href}
+ {...(kpi.description ? { description: kpi.description } : {})}
{...(kpi.delta ? { delta: kpi.delta } : {})}
{...(LinkComponent ? { LinkComponent } : {})}
{...(typeof kpi.gauge === "number"
diff --git a/packages/ui/src/dashboard/savings-mini.tsx b/packages/ui/src/dashboard/savings-mini.tsx
index 5129d3b97..91ebe02b6 100644
--- a/packages/ui/src/dashboard/savings-mini.tsx
+++ b/packages/ui/src/dashboard/savings-mini.tsx
@@ -18,6 +18,14 @@ interface SavingsMiniProps {
data?: SavingsMiniData | null;
/** Repo id, for the "View costs →" link. */
repoId: string;
+ /**
+ * Whether savings can ever be tracked on this deployment. Savings come from
+ * a local `.repowise/omissions` sidecar written by the CLI, so hosted has no
+ * way to populate them: it passes `false` to get the indexing-cost framing
+ * instead of an empty state pitching a CLI the viewer isn't running.
+ * Defaults to true (the local CLI dashboard).
+ */
+ trackable?: boolean;
}
/**
@@ -25,7 +33,7 @@ interface SavingsMiniProps {
* value priced at the detected agent model, and a distill-vs-MCP split, with a
* jump to the full Costs results page.
*/
-export function SavingsMini({ data, repoId }: SavingsMiniProps) {
+export function SavingsMini({ data, repoId, trackable = true }: SavingsMiniProps) {
const distillSaved = data?.saved_tokens ?? 0;
const mcpSaved = data?.mcp_tokens ?? 0;
const total = distillSaved + mcpSaved;
@@ -41,7 +49,7 @@ export function SavingsMini({ data, repoId }: SavingsMiniProps) {
<CardTitle className="text-sm flex items-center justify-between">
<span className="flex items-center gap-2">
<Sparkles className="h-4 w-4 text-[var(--color-accent-secondary)]" />
- Agent savings
+ {trackable ? "Agent savings" : "Costs"}
</span>
<a
href={costsHref}
@@ -118,8 +126,17 @@ export function SavingsMini({ data, repoId }: SavingsMiniProps) {
) : (
<div className="space-y-2 py-1">
<p className="text-xs text-[var(--color-text-secondary)] leading-snug">
- Trim what your agent reads with <code>repowise distill</code> and the MCP tools —
- savings show up here.
+ {trackable ? (
+ <>
+ Trim what your agent reads with <code>repowise distill</code> and the MCP tools —
+ savings show up here.
+ </>
+ ) : (
+ // Agent savings are written by the local CLI sidecar, so there
+ // is nothing to earn here on hosted. Point at what the Costs
+ // page *does* show instead of teasing a number that never lands.
+ <>What this repo&apos;s indexing and doc generation cost, per sync.</>
+ )}
</p>
<a
href={costsHref}
diff --git a/packages/web/src/app/repos/[id]/overview/page.tsx b/packages/web/src/app/repos/[id]/overview/page.tsx
index ca69b8d42..d35816b8a 100644
--- a/packages/web/src/app/repos/[id]/overview/page.tsx
+++ b/packages/web/src/app/repos/[id]/overview/page.tsx
@@ -12,7 +12,7 @@ import { FirstIndexExperience } from "@/components/repos/first-index-experience"
import { HealthOverviewCard } from "@repowise-dev/ui/dashboard/health-overview-card";
import { AttentionPanel } from "@repowise-dev/ui/dashboard/attention-panel";
import { KpiStrip, kpiDelta, type KpiItem } from "@repowise-dev/ui/dashboard/kpi-strip";
-import { OverviewGrid } from "@repowise-dev/ui/dashboard/overview-grid";
+import { OverviewGrid, OverviewPanelPair } from "@repowise-dev/ui/dashboard/overview-grid";
import { SavingsMini } from "@repowise-dev/ui/dashboard/savings-mini";
import { IndexStorageMini } from "@repowise-dev/ui/dashboard/index-storage-mini";
import { LanguageDonut } from "@repowise-dev/ui/dashboard/language-donut";
@@ -50,11 +50,17 @@ export default async function OverviewPage({ params }: Props) {
const { repo, stats, health, sync } = summary;
const isFresh = stats.file_count === 0;
+ // Fall back to the sync page count so the tile still reads on a server that
+ // predates the AI/auto split; the split line just hides.
+ const docPages = stats.doc_page_count ?? sync.page_count ?? 0;
+ const autoPages = stats.doc_auto_page_count;
+ const aiPages = autoPages != null ? Math.max(0, docPages - autoPages) : null;
+
const kpis: KpiItem[] = [
{
label: "Files",
value: formatNumber(stats.file_count),
- href: `/repos/${id}/architecture?view=graph`,
+ href: `/repos/${id}/files`,
// File-count growth is neutral, not "good" — render the delta uncolored.
delta: kpiDelta(stats.deltas.file_count, true),
},
@@ -64,10 +70,15 @@ export default async function OverviewPage({ params }: Props) {
href: `/repos/${id}/architecture?view=symbols`,
},
{
- label: "Doc Coverage",
- value: `${Math.round(stats.doc_coverage_pct)}%`,
- href: `/repos/${id}/docs/coverage`,
- gauge: stats.doc_coverage_pct,
+ label: "Docs",
+ value: formatNumber(docPages),
+ href: `/repos/${id}/docs`,
+ // The AI/auto split is the interesting part of a page count: it says how
+ // much of the wiki a model wrote vs what was templated from structure.
+ description:
+ docPages > 0 && aiPages != null && autoPages != null
+ ? `${formatNumber(aiPages)} AI · ${formatNumber(autoPages)} auto`
+ : undefined,
},
{
label: "Dead Exports",
@@ -148,21 +159,27 @@ export default async function OverviewPage({ params }: Props) {
repoId={id}
averageDelta={stats.deltas.average_health}
hotspotDelta={stats.deltas.hotspot_health}
+ defectAccuracy={statsHighlights?.quality.defect_accuracy ?? null}
/>
<ContributorsStripCard repoId={id} />
+ {/* The two short tiles sit two-up here rather than stacked in
+ the rail: it keeps the main column from bottoming out well
+ above the taller Attention panel beside it. */}
+ <OverviewPanelPair>
+ <SavingsMini data={summary.savings} repoId={id} />
+ <IndexStorageMini
+ data={{
+ index_storage_bytes: sync.index_storage_bytes ?? 0,
+ page_count: sync.page_count,
+ doc_coverage_pct: stats.doc_coverage_pct,
+ }}
+ />
+ </OverviewPanelPair>
</>
}
rail={
<>
{statsHighlights && <StatsTeaserCard repoId={id} data={statsHighlights} />}
- <IndexStorageMini
- data={{
- index_storage_bytes: sync.index_storage_bytes ?? 0,
- page_count: sync.page_count,
- doc_coverage_pct: stats.doc_coverage_pct,
- }}
- />
- <SavingsMini data={summary.savings} repoId={id} />
<AttentionPanel items={attentionItems} repoId={id} previewCount={5} repoName={repo.name} />
</>
}
diff --git a/tests/unit/server/test_overview_docs_split.py b/tests/unit/server/test_overview_docs_split.py
new file mode 100644
index 000000000..c0cdd8261
--- /dev/null
+++ b/tests/unit/server/test_overview_docs_split.py
@@ -0,0 +1,72 @@
+"""Tests for the docs counts in /api/repos/{id}/overview-summary.
+
+The Overview's Docs tile reports total generated pages plus how many of them
+are the deterministic template ("Auto") coverage tail, so a reader can tell
+model-written docs from structure-derived ones. ``provider_name == "template"``
+is the discriminator, matching the page schema's ``is_deterministic``.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+import pytest
+from httpx import AsyncClient
+
+from repowise.core.persistence.database import get_session
+from repowise.core.persistence.models import Page
+from tests.unit.server.conftest import create_test_repo
+
+_NOW = datetime(2026, 1, 1, tzinfo=UTC)
+
+
+def _page(repo_id: str, path: str, provider: str) -> Page:
+ return Page(
+ id=f"file_page:{path}",
+ repository_id=repo_id,
+ page_type="file_page",
+ title=path,
+ content=f"# {path}",
+ summary="",
+ target_path=path,
+ source_hash=f"h-{path}",
+ model_name="mock",
+ provider_name=provider,
+ generation_level=4,
+ confidence=0.9,
+ freshness_status="fresh",
+ metadata_json="{}",
+ created_at=_NOW,
+ updated_at=_NOW,
+ )
+
+
+async def test_docs_counts_split_ai_from_template_pages(client: AsyncClient, app) -> None:
+ """Total counts every page; auto counts only the template-provider ones."""
+ repo = await create_test_repo(client)
+
+ async with get_session(app.state.session_factory) as session:
+ session.add(_page(repo["id"], "a.py", "anthropic"))
+ session.add(_page(repo["id"], "b.py", "anthropic"))
+ session.add(_page(repo["id"], "c.py", "template"))
+
+ resp = await client.get(f"/api/repos/{repo['id']}/overview-summary")
+ assert resp.status_code == 200
+ stats = resp.json()["stats"]
+
+ assert stats["doc_page_count"] == 3
+ assert stats["doc_auto_page_count"] == 1
+
+
+async def test_docs_counts_are_zero_without_pages(client: AsyncClient) -> None:
+ """An index-only repo has no wiki: both counts read zero, not null."""
+ repo = await create_test_repo(client)
+
+ resp = await client.get(f"/api/repos/{repo['id']}/overview-summary")
+ assert resp.status_code == 200
+ stats = resp.json()["stats"]
+
+ assert stats["doc_page_count"] == 0
+ assert stats["doc_auto_page_count"] == 0