Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
fix(health): compare like-with-like populations in coordinator health (#374) (#479)
Raghav Chamadiyace66d5a31916
diff --git a/packages/core/src/repowise/core/persistence/coordinator.py b/packages/core/src/repowise/core/persistence/coordinator.pyindex dfbd1cee6..1cfa0607c 100644--- a/packages/core/src/repowise/core/persistence/coordinator.py+++ b/packages/core/src/repowise/core/persistence/coordinator.py@@ -145,14 +145,44 @@ class AtomicStorageCoordinator:raiseasync def health_check(self) -> dict:- """Compare counts across stores. Returns drift report."""+ """Compare counts across stores, *per population*. Returns a drift report.++ The page vector store is shared: it holds wiki-page vectors **and**+ decision-record vectors (under the ``decision:<id>`` namespace). A naive+ ``wiki_pages`` vs *total vector count* comparison therefore compares+ unlike populations — a store with only decision vectors reads as 100%+ page drift even though nothing is wrong with the pages (issue #374).++ This compares like with like:+ * ``wiki_pages`` <-> page vectors -> ``page_drift``+ * ``decision_records`` <-> decision vectors -> ``decision_drift``++ ``drift`` is kept as an alias of ``page_drift`` for backwards+ compatibility. ``vector_count`` remains the total (page + decision) so+ existing callers that only display it are unaffected.+ """from sqlalchemy import text- report: dict = {"sql_pages": None, "vector_count": None, "graph_nodes": None, "drift": None}+ report: dict = {+ "sql_pages": None,+ "sql_decisions": None,+ "vector_count": None,+ "vector_page_count": None,+ "vector_decision_count": None,+ "graph_nodes": None,+ "drift": None,+ "page_drift": None,+ "decision_drift": None,+ }try:res = await self._session.execute(text("SELECT COUNT(*) FROM wiki_pages"))report["sql_pages"] = int(res.scalar() or 0)except Exception as e:report["sql_pages_error"] = str(e)+ try:+ res = await self._session.execute(text("SELECT COUNT(*) FROM decision_records"))+ report["sql_decisions"] = int(res.scalar() or 0)+ except Exception as e:+ report["sql_decisions_error"] = str(e)if self._graph_builder is not None:g = getattr(self._graph_builder, "_graph", None)if g is not None:@@ -165,13 +195,25 @@ class AtomicStorageCoordinator:report["graph_nodes_error"] = str(e)if self._vector_store is not None:try:- report["vector_count"] = await _vector_count(self._vector_store)+ breakdown = await _vector_breakdown(self._vector_store)+ report["vector_count"] = breakdown["total"]+ report["vector_page_count"] = breakdown["page_count"]+ report["vector_decision_count"] = breakdown["decision_count"]except Exception as e:report["vector_count_error"] = str(e)- # Compute drift between SQL and vector if both available- if report["sql_pages"] is not None and report["vector_count"] is not None:++ # Page drift: wiki_pages vs page vectors (like with like).+ if report["sql_pages"] is not None and report["vector_page_count"] is not None:denom = max(report["sql_pages"], 1)- report["drift"] = abs(report["sql_pages"] - report["vector_count"]) / denom+ report["page_drift"] = abs(report["sql_pages"] - report["vector_page_count"]) / denom+ # Decision drift: decision_records vs decision vectors.+ if report["sql_decisions"] is not None and report["vector_decision_count"] is not None:+ denom = max(report["sql_decisions"], 1)+ report["decision_drift"] = (+ abs(report["sql_decisions"] - report["vector_decision_count"]) / denom+ )+ # Backwards-compatible alias.+ report["drift"] = report["page_drift"]return report@@ -221,3 +263,39 @@ async def _vector_count(store) -> int:ids = await list_ids()return len(ids)return -1+++async def _vector_breakdown(store) -> dict:+ """Split the store's vectors into page vs decision populations.++ The page vector store co-locates wiki-page vectors and decision-record+ vectors (the latter under the ``decision:<id>`` namespace). Health checks+ must compare each population against its own SQL table, so this enumerates+ the stored ids and buckets them by namespace.++ Returns ``{"total", "page_count", "decision_count"}``. When the store can't+ enumerate ids (only a total count is available) the population counts are+ ``None`` and ``total`` falls back to :func:`_vector_count` (which may be -1+ for unsupported stores).+ """+ from repowise.core.analysis.decisions.semantic_match import DECISION_VECTOR_PREFIX++ list_ids = getattr(store, "list_page_ids", None)+ if list_ids is not None:+ ids = await list_ids()+ if ids:+ decision = sum(1 for i in ids if i.startswith(DECISION_VECTOR_PREFIX))+ return {+ "total": len(ids),+ "page_count": len(ids) - decision,+ "decision_count": decision,+ }+ # An empty id set is ambiguous: the store may genuinely be empty, or it+ # may not implement id enumeration. Cross-check against the count.+ total = await _vector_count(store)+ if total <= 0:+ return {"total": max(total, 0), "page_count": 0, "decision_count": 0}+ return {"total": total, "page_count": None, "decision_count": None}++ total = await _vector_count(store)+ return {"total": total, "page_count": None, "decision_count": None}diff --git a/packages/server/src/repowise/server/routers/health.py b/packages/server/src/repowise/server/routers/health.pyindex caca4a114..7cef10b6b 100644--- a/packages/server/src/repowise/server/routers/health.py+++ b/packages/server/src/repowise/server/routers/health.py@@ -5,11 +5,11 @@ These endpoints are NOT protected by API key auth.from __future__ import annotations+from fastapi import APIRouter, Depends, Requestfrom sqlalchemy import func, selectfrom sqlalchemy.ext.asyncio import AsyncSessionfrom sqlalchemy.sql import text-from fastapi import APIRouter, Depends, Requestfrom repowise.core.persistence.coordinator import AtomicStorageCoordinatorfrom repowise.core.persistence.database import get_sessionfrom repowise.core.persistence.models import GenerationJob, Page@@ -93,34 +93,105 @@ async def coordinator_health(result = await coord.health_check()sql_pages: int | None = result.get("sql_pages")+ sql_decisions: int | None = result.get("sql_decisions")vector_count: int | None = result.get("vector_count")+ vector_page_count: int | None = result.get("vector_page_count")+ vector_decision_count: int | None = result.get("vector_decision_count")graph_nodes: int | None = result.get("graph_nodes")- drift: float | None = result.get("drift")+ page_drift: float | None = result.get("page_drift")+ decision_drift: float | None = result.get("decision_drift")- # Normalise vector_count: -1 means unsupported (return None)+ # Normalise vector counts: -1 means the store can't be counted (return None).if vector_count == -1:vector_count = None- # Drift percentage (0–100)- drift_pct: float | None = round(drift * 100, 2) if drift is not None else None+ # Drift percentages (0-100), compared like-with-like per population.+ page_drift_pct = round(page_drift * 100, 2) if page_drift is not None else None+ decision_drift_pct = round(decision_drift * 100, 2) if decision_drift is not None else None- if drift_pct is None:- status = "ok"- elif drift_pct <= 1.0:- status = "ok"- elif drift_pct <= 5.0:- status = "warning"- else:- status = "critical"+ page_status = _classify_drift(page_drift_pct)+ decision_status = _classify_drift(decision_drift_pct)+ status = _worst_status(page_status, decision_status)+ detail = _build_detail(+ page_drift_pct=page_drift_pct,+ decision_drift_pct=decision_drift_pct,+ sql_pages=sql_pages,+ vector_page_count=vector_page_count,+ sql_decisions=sql_decisions,+ vector_decision_count=vector_decision_count,+ )return CoordinatorHealthResponse(sql_pages=sql_pages,+ sql_decisions=sql_decisions,vector_count=vector_count,+ vector_page_count=vector_page_count,+ vector_decision_count=vector_decision_count,graph_nodes=graph_nodes,- drift_pct=drift_pct,+ drift_pct=page_drift_pct, # alias of page_drift_pct (backwards compat)+ page_drift_pct=page_drift_pct,+ decision_drift_pct=decision_drift_pct,status=status,+ detail=detail,)+_STATUS_RANK = {"ok": 0, "warning": 1, "critical": 2}+++def _classify_drift(drift_pct: float | None) -> str:+ """Map a drift percentage to an ok/warning/critical status."""+ if drift_pct is None:+ return "ok" # population not comparable (e.g. store can't enumerate ids)+ if drift_pct <= 1.0:+ return "ok"+ if drift_pct <= 5.0:+ return "warning"+ return "critical"+++def _worst_status(*statuses: str) -> str:+ """Return the most severe of the given statuses."""+ return max(statuses, key=lambda s: _STATUS_RANK.get(s, 0))+++def _build_detail(+ *,+ page_drift_pct: float | None,+ decision_drift_pct: float | None,+ sql_pages: int | None,+ vector_page_count: int | None,+ sql_decisions: int | None,+ vector_decision_count: int | None,+) -> str | None:+ """Compose a human-readable explanation, reporting each population separately."""+ parts: list[str] = []++ # Pages+ if sql_pages and vector_page_count == 0:+ parts.append(f"No page vectors for {sql_pages} wiki pages; run a sync to embed pages.")+ elif page_drift_pct is not None and page_drift_pct > 1.0:+ parts.append(+ f"Page drift {page_drift_pct:.1f}% "+ f"({sql_pages} pages vs {vector_page_count} page vectors)."+ )++ # Decisions+ if sql_decisions and vector_decision_count == 0:+ parts.append(+ f"No decision vectors for {sql_decisions} decision records; "+ f"run a sync to embed decisions."+ )+ elif decision_drift_pct is not None and decision_drift_pct > 1.0:+ parts.append(+ f"Decision drift {decision_drift_pct:.1f}% "+ f"({sql_decisions} decisions vs {vector_decision_count} decision vectors)."+ )++ if not parts:+ return "All populations in sync." if page_drift_pct is not None else None+ return " ".join(parts)++# Merge repo-scoped routes into the main router so they are registered together.router.include_router(_repo_health_router)diff --git a/packages/server/src/repowise/server/schemas/health.py b/packages/server/src/repowise/server/schemas/health.pyindex 126bf3894..911ce04c6 100644--- a/packages/server/src/repowise/server/schemas/health.py+++ b/packages/server/src/repowise/server/schemas/health.py@@ -13,7 +13,13 @@ class HealthResponse(BaseModel):class CoordinatorHealthResponse(BaseModel):sql_pages: int | None- vector_count: int | None+ sql_decisions: int | None+ vector_count: int | None # total page + decision vectors+ vector_page_count: int | None+ vector_decision_count: int | Nonegraph_nodes: int | None- drift_pct: float | None+ drift_pct: float | None # alias of page_drift_pct (backwards compat)+ page_drift_pct: float | None # wiki_pages <-> page vectors+ decision_drift_pct: float | None # decision_records <-> decision vectorsstatus: str # "ok" | "warning" | "critical"+ detail: str | None = None # human-readable explanation of the statusdiff --git a/packages/web/src/app/repos/[id]/settings/page.tsx b/packages/web/src/app/repos/[id]/settings/page.tsxindex 2344a44f8..a422d6a0d 100644--- a/packages/web/src/app/repos/[id]/settings/page.tsx+++ b/packages/web/src/app/repos/[id]/settings/page.tsx@@ -73,7 +73,10 @@ export default async function RepoSettingsPage({ params }: Props) {<Card><CardHeader><CardTitle className="text-sm font-medium">System Health</CardTitle>- <CardDescription>Coordinator drift across SQL, vector, and graph stores</CardDescription>+ <CardDescription>+ Per-population drift: wiki pages vs page vectors, and decision records vs decision+ vectors+ </CardDescription></CardHeader><CardContent className="pt-0"><CoordinatorHealthPanel repoId={id} initial={coordinatorHealth} />diff --git a/packages/web/src/components/repos/coordinator-health-panel.tsx b/packages/web/src/components/repos/coordinator-health-panel.tsxindex b44a12e5f..b9f9a334b 100644--- a/packages/web/src/components/repos/coordinator-health-panel.tsx+++ b/packages/web/src/components/repos/coordinator-health-panel.tsx@@ -63,14 +63,30 @@ export function CoordinatorHealthPanel({ repoId, initial }: Props) {{data.status}</span></div>- <StatRow label="SQL Pages" value={fmt(data.sql_pages)} />- <StatRow label="Vector Count" value={fmt(data.vector_count)} />- <StatRow label="Graph Nodes" value={fmt(data.graph_nodes)} /><StatRow- label="Drift"- value={fmtPct(data.drift_pct)}- help="How far the SQL, vector and graph stores disagree about what's indexed. 0% means all three are in sync; high drift usually means an interrupted index — run a sync to reconcile."+ label="Wiki Pages"+ value={`${fmt(data.sql_pages)} SQL / ${fmt(data.vector_page_count)} vectors`}+ help="Generated wiki pages in SQL vs the matching page vectors in the vector store."+ />+ <StatRow+ label="Page Drift"+ value={fmtPct(data.page_drift_pct)}+ help="How far the wiki-page count disagrees with the page-vector count. 0% means every page is embedded; high drift usually means an interrupted index — run a sync to reconcile."+ />+ <StatRow+ label="Decisions"+ value={`${fmt(data.sql_decisions)} SQL / ${fmt(data.vector_decision_count)} vectors`}+ help="Decision records in SQL vs the matching decision vectors. Decision vectors are counted separately from page vectors."+ />+ <StatRow+ label="Decision Drift"+ value={fmtPct(data.decision_drift_pct)}+ help="How far the decision-record count disagrees with the decision-vector count."/>+ <StatRow label="Graph Nodes" value={fmt(data.graph_nodes)} />+ {data.detail && (+ <p className="text-xs text-[var(--color-text-secondary)] pt-1.5">{data.detail}</p>+ )}</>) : (<p className="text-xs text-[var(--color-text-secondary)]">diff --git a/packages/web/src/lib/api/health.ts b/packages/web/src/lib/api/health.tsindex e3616246d..ff97c20d0 100644--- a/packages/web/src/lib/api/health.ts+++ b/packages/web/src/lib/api/health.ts@@ -7,10 +7,16 @@ export async function getHealth(): Promise<HealthResponse> {export interface CoordinatorHealth {sql_pages: number | null;+ sql_decisions: number | null;vector_count: number | null;+ vector_page_count: number | null;+ vector_decision_count: number | null;graph_nodes: number | null;drift_pct: number | null;+ page_drift_pct: number | null;+ decision_drift_pct: number | null;status: "ok" | "warning" | "critical";+ detail: string | null;}export async function getCoordinatorHealth(repoId: string): Promise<CoordinatorHealth> {diff --git a/tests/integration/test_cli.py b/tests/integration/test_cli.pyindex 8adbefdb5..54c1d530a 100644--- a/tests/integration/test_cli.py+++ b/tests/integration/test_cli.py@@ -296,7 +296,7 @@ class TestUpdateIndexOnly:cli, ["update", str(git_work_repo), "--index-only"], catch_exceptions=False)assert r1.exit_code == 0, r1.output- assert "Index-only update complete" in r1.output+ assert "index-only update complete" in r1.outputstate1 = json.loads((git_work_repo / ".repowise" / "state.json").read_text(encoding="utf-8")diff --git a/tests/unit/persistence/test_coordinator_health.py b/tests/unit/persistence/test_coordinator_health.pynew file mode 100644index 000000000..7a9f74e1f--- /dev/null+++ b/tests/unit/persistence/test_coordinator_health.py@@ -0,0 +1,156 @@+"""Regression tests for ``AtomicStorageCoordinator.health_check`` (issue #374).++The page vector store co-locates wiki-page vectors and decision-record vectors+(the latter under the ``decision:<id>`` namespace). The health check used to+compare ``COUNT(*) FROM wiki_pages`` against the *total* vector count, so a+store holding only decision vectors reported ~100% drift even though the pages+themselves were fine. These tests pin the like-with-like comparison:++ * wiki_pages <-> page vectors -> page_drift+ * decision_records <-> decision vectors -> decision_drift+"""++from __future__ import annotations++import pytest+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine+from sqlalchemy.pool import StaticPool++from repowise.core.analysis.decisions.semantic_match import DECISION_VECTOR_PREFIX+from repowise.core.persistence.coordinator import AtomicStorageCoordinator+from repowise.core.persistence.database import init_db+from repowise.core.persistence.models import DecisionRecord+from repowise.core.persistence.vector_store import InMemoryVectorStore+from repowise.core.providers.embedding.base import MockEmbedder+++async def _setup_session() -> tuple[object, AsyncSession]:+ engine = create_async_engine(+ "sqlite+aiosqlite:///:memory:",+ connect_args={"check_same_thread": False},+ poolclass=StaticPool,+ )+ await init_db(engine)+ factory = async_sessionmaker(engine, expire_on_commit=False, class_=AsyncSession)+ return engine, factory()+++async def _insert_repo(session: AsyncSession):+ from repowise.core.persistence.crud import upsert_repository++ repo = await upsert_repository(+ session, name="taskq", local_path="/tmp/taskq", url="https://github.com/example/taskq"+ )+ await session.commit()+ return repo+++async def _insert_page(session: AsyncSession, repo_id: str, page_id: str) -> None:+ from repowise.core.persistence.crud import upsert_page++ await upsert_page(+ session,+ page_id=page_id,+ repository_id=repo_id,+ page_type="file_page",+ title=page_id,+ content="body",+ target_path=page_id,+ source_hash="h",+ model_name="mock",+ provider_name="mock",+ input_tokens=1,+ output_tokens=1,+ )+ await session.commit()+++async def _insert_decision(session: AsyncSession, repo_id: str, title: str) -> str:+ rec = DecisionRecord(repository_id=repo_id, title=title, decision="because")+ session.add(rec)+ await session.commit()+ return rec.id+++async def test_consistent_store_reports_zero_drift_per_population():+ engine, session = await _setup_session()+ try:+ repo = await _insert_repo(session)+ await _insert_page(session, repo.id, "file_page:a.py")+ await _insert_page(session, repo.id, "file_page:b.py")+ d1 = await _insert_decision(session, repo.id, "Adopt Redis")++ vs = InMemoryVectorStore(MockEmbedder())+ await vs.embed_and_upsert("file_page:a.py", "a", {})+ await vs.embed_and_upsert("file_page:b.py", "b", {})+ await vs.embed_and_upsert(f"{DECISION_VECTOR_PREFIX}{d1}", "redis", {})++ coord = AtomicStorageCoordinator(session, graph_builder=None, vector_store=vs)+ report = await coord.health_check()++ assert report["sql_pages"] == 2+ assert report["sql_decisions"] == 1+ assert report["vector_count"] == 3+ assert report["vector_page_count"] == 2+ assert report["vector_decision_count"] == 1+ assert report["page_drift"] == 0.0+ assert report["decision_drift"] == 0.0+ assert report["drift"] == report["page_drift"] # backwards-compat alias+ finally:+ await session.close()+ await engine.dispose()+++async def test_only_decision_vectors_does_not_inflate_page_drift():+ """The issue #374 scenario: SQL has wiki pages, the store has only decision+ vectors. Page drift must reflect the missing *page* vectors (not be diluted+ by the decision vectors), and decision drift must read clean."""+ engine, session = await _setup_session()+ try:+ repo = await _insert_repo(session)+ await _insert_page(session, repo.id, "file_page:a.py")+ await _insert_page(session, repo.id, "file_page:b.py")+ d1 = await _insert_decision(session, repo.id, "Adopt Redis")++ vs = InMemoryVectorStore(MockEmbedder())+ # Only the decision vector exists — no page vectors were embedded.+ await vs.embed_and_upsert(f"{DECISION_VECTOR_PREFIX}{d1}", "redis", {})++ coord = AtomicStorageCoordinator(session, graph_builder=None, vector_store=vs)+ report = await coord.health_check()++ assert report["sql_pages"] == 2+ assert report["vector_page_count"] == 0+ assert report["vector_decision_count"] == 1+ # Page vectors are genuinely missing -> 100% page drift (reported clearly).+ assert report["page_drift"] == 1.0+ # Decisions are fully embedded -> no decision drift.+ assert report["decision_drift"] == 0.0+ finally:+ await session.close()+ await engine.dispose()+++async def test_missing_decision_vectors_isolated_to_decision_drift():+ engine, session = await _setup_session()+ try:+ repo = await _insert_repo(session)+ await _insert_page(session, repo.id, "file_page:a.py")+ await _insert_decision(session, repo.id, "Adopt Redis")++ vs = InMemoryVectorStore(MockEmbedder())+ await vs.embed_and_upsert("file_page:a.py", "a", {})+ # Decision vector intentionally absent.++ coord = AtomicStorageCoordinator(session, graph_builder=None, vector_store=vs)+ report = await coord.health_check()++ assert report["page_drift"] == 0.0+ assert report["vector_decision_count"] == 0+ assert report["decision_drift"] == 1.0+ finally:+ await session.close()+ await engine.dispose()diff --git a/tests/unit/server/test_coordinator_health_status.py b/tests/unit/server/test_coordinator_health_status.pynew file mode 100644index 000000000..d9d3c8bcf--- /dev/null+++ b/tests/unit/server/test_coordinator_health_status.py@@ -0,0 +1,79 @@+"""Unit tests for the coordinator-health status/detail derivation (issue #374).++These pin the pure helpers that turn per-population drift into an+ok/warning/critical status and a human-readable explanation, so the dashboard+reports page-vector and decision-vector problems separately instead of as one+opaque "drift across stores" number.+"""++from __future__ import annotations++from repowise.server.routers.health import _build_detail, _classify_drift, _worst_status+++def test_classify_drift_thresholds():+ assert _classify_drift(None) == "ok"+ assert _classify_drift(0.0) == "ok"+ assert _classify_drift(1.0) == "ok"+ assert _classify_drift(3.0) == "warning"+ assert _classify_drift(5.0) == "warning"+ assert _classify_drift(42.0) == "critical"+++def test_worst_status_picks_most_severe():+ assert _worst_status("ok", "ok") == "ok"+ assert _worst_status("ok", "warning") == "warning"+ assert _worst_status("warning", "critical") == "critical"+ assert _worst_status("critical", "ok") == "critical"+++def test_detail_calls_out_missing_page_vectors():+ detail = _build_detail(+ page_drift_pct=100.0,+ decision_drift_pct=0.0,+ sql_pages=12,+ vector_page_count=0,+ sql_decisions=3,+ vector_decision_count=3,+ )+ assert detail is not None+ assert "No page vectors for 12 wiki pages" in detail+ assert "decision" not in detail.lower() # decisions are healthy -> not mentioned+++def test_detail_reports_missing_decision_vectors_separately():+ detail = _build_detail(+ page_drift_pct=0.0,+ decision_drift_pct=100.0,+ sql_pages=12,+ vector_page_count=12,+ sql_decisions=3,+ vector_decision_count=0,+ )+ assert detail is not None+ assert "No decision vectors for 3 decision records" in detail+ assert "page" not in detail.lower()+++def test_detail_in_sync_when_no_drift():+ detail = _build_detail(+ page_drift_pct=0.0,+ decision_drift_pct=0.0,+ sql_pages=12,+ vector_page_count=12,+ sql_decisions=3,+ vector_decision_count=3,+ )+ assert detail == "All populations in sync."+++def test_detail_none_when_populations_not_comparable():+ detail = _build_detail(+ page_drift_pct=None,+ decision_drift_pct=None,+ sql_pages=None,+ vector_page_count=None,+ sql_decisions=None,+ vector_decision_count=None,+ )+ assert detail is None