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
feat(doc-drift): record drift in health history and mark findings new since the last update (#2646)
Raghav Chamadiyaa387a148f509
diff --git a/packages/cli/src/repowise/cli/commands/health_cmd/trends.py b/packages/cli/src/repowise/cli/commands/health_cmd/trends.pyindex 235792d74..10f08110e 100644--- a/packages/cli/src/repowise/cli/commands/health_cmd/trends.py+++ b/packages/cli/src/repowise/cli/commands/health_cmd/trends.py@@ -47,7 +47,7 @@ def _render_trend(repo_path: object, *, fmt: str) -> None:if repo is None:return [], Nonesnaps = await list_health_snapshots(session, repo.id)- return recent_kpis(snaps, limit=10), diff_snapshots(snaps)+ return recent_kpis(snaps, limit=10, doc_drift=True), diff_snapshots(snaps)rows, summary = run_async(_fetch())if not rows:@@ -88,6 +88,7 @@ def _render_trend(repo_path: object, *, fmt: str) -> None:table.add_column("Average", justify="right")table.add_column("Worst", justify="right")table.add_column("Worst file", style="dim")+ table.add_column("Doc drift", justify="right")for r in rows:table.add_row((r["taken_at"] or "—")[:19],@@ -95,6 +96,7 @@ def _render_trend(repo_path: object, *, fmt: str) -> None:f"{r['average_health']:.2f}",f"{r['worst_performer_score']:.2f}" if r["worst_performer_score"] is not None else "—",r["worst_performer_path"] or "—",+ str(r["doc_drift_count"]) if r["doc_drift_count"] is not None else "—",)console.print(table)diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py b/packages/cli/src/repowise/cli/commands/update_cmd/persistence.pyindex 82b076472..43b05637a 100644--- a/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py+++ b/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py@@ -1140,6 +1140,22 @@ async def _persist_full_update_async(if timings is not None:timings.stop("persist.governance")+ # Scoped to the documents the pass actually read, so one this run+ # could not open keeps its rows in both drift tables. Before health:+ # the snapshot it takes records the stored drift count.+ if doc_drift_report is not None:+ try:+ from repowise.core.persistence.crud import (+ replace_doc_drift_guarded,+ )++ with timed(timings, "persist.doc_drift"):+ await replace_doc_drift_guarded(+ session, repo_id, doc_drift_report+ )+ except Exception as exc:+ _skip("Doc-drift persist", exc)+# Code-health findings + metrics (partial — upsert only).if partial_health_report is not None:try:@@ -1171,21 +1187,6 @@ async def _persist_full_update_async(except Exception as exc:_skip("Dead-code persist", exc)- # Scoped to the documents the pass actually read, so one this run- # could not open keeps its rows in both drift tables.- if doc_drift_report is not None:- try:- from repowise.core.persistence.crud import (- replace_doc_drift_guarded,- )-- with timed(timings, "persist.doc_drift"):- await replace_doc_drift_guarded(- session, repo_id, doc_drift_report- )- except Exception as exc:- _skip("Doc-drift persist", exc)-# Re-persist graph_nodes so symbol-level PageRank / betweenness /# community ids reflect the current build.try:diff --git a/packages/core/alembic/versions/0082_doc_drift_history.py b/packages/core/alembic/versions/0082_doc_drift_history.pynew file mode 100644index 000000000..87a480ccd--- /dev/null+++ b/packages/core/alembic/versions/0082_doc_drift_history.py@@ -0,0 +1,52 @@+"""Documentation drift history: when a finding first appeared, and the count per snapshot.++``doc_drift_findings.first_seen_at`` is carried across rewrites by the+finding's line-independent key, so a finding can be shown as new since the+last update. ``health_snapshots.doc_drift_count`` records the stored finding+count beside each snapshot's health figures. Both are nullable: null means+"not recorded", never zero.++Local SQLite stores never run Alembic -- ``init_db``'s reconciler issues+additive DDL for missing columns -- so this migration exists for managed+Postgres.++Revision ID: 0082+Revises: 0081+Create Date: 2026-09-28+"""++from __future__ import annotations++from collections.abc import Sequence++import sqlalchemy as sa+from alembic import op++# revision identifiers+revision: str = "0082"+down_revision: str | None = "0081"+branch_labels: str | Sequence[str] | None = None+depends_on: str | Sequence[str] | None = None++_COLUMNS = (+ ("doc_drift_findings", "first_seen_at", sa.DateTime(timezone=True)),+ ("health_snapshots", "doc_drift_count", sa.Integer()),+)+++def _columns(table: str) -> set[str]:+ inspector = sa.inspect(op.get_bind())+ return {c["name"] for c in inspector.get_columns(table)}+++def upgrade() -> None:+ # Guarded: ``init_db``'s reconciler may already have added these on Postgres.+ for table, name, type_ in _COLUMNS:+ if name not in _columns(table):+ op.add_column(table, sa.Column(name, type_, nullable=True))+++def downgrade() -> None:+ for table, name, _type in reversed(_COLUMNS):+ if name in _columns(table):+ op.drop_column(table, name)diff --git a/packages/core/src/repowise/core/analysis/health/trends.py b/packages/core/src/repowise/core/analysis/health/trends.pyindex d0482eedd..e0f7e6e0d 100644--- a/packages/core/src/repowise/core/analysis/health/trends.py+++ b/packages/core/src/repowise/core/analysis/health/trends.py@@ -396,6 +396,7 @@ def drop_unscoped_fields(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:"structure_average": None,"history_average": None,"maintainability_average": None,+ **({"doc_drift_count": None} if "doc_drift_count" in row else {}),}for row in rows]@@ -407,12 +408,15 @@ def _point(snap: Any, attr: str) -> float | None:return round(float(value), 2) if value is not None else None-def recent_kpis(history: list[Any], limit: int = 10) -> list[dict[str, Any]]:+def recent_kpis(+ history: list[Any], limit: int = 10, *, doc_drift: bool = False+) -> list[dict[str, Any]]:"""Serialize the most-recent *limit* snapshots for CLI / API consumers.Newest first (so the CLI table reads top-down chronologically whenflipped, which matches user expectation for "recent runs"). Each row- is a plain dict — no ORM leakage.+ is a plain dict — no ORM leakage. *doc_drift* adds ``doc_drift_count``;+ off by default so agent-facing trend rows stay as they were."""if not history:return []@@ -439,6 +443,8 @@ def recent_kpis(history: list[Any], limit: int = 10) -> list[dict[str, Any]]:"maintainability_average": _point(snap, "maintainability_average"),})+ if doc_drift:+ rows[-1]["doc_drift_count"] = getattr(snap, "doc_drift_count", None)return rowsdiff --git a/packages/core/src/repowise/core/persistence/crud/analysis/__init__.py b/packages/core/src/repowise/core/persistence/crud/analysis/__init__.pyindex 28ae23679..dedb52a87 100644--- a/packages/core/src/repowise/core/persistence/crud/analysis/__init__.py+++ b/packages/core/src/repowise/core/persistence/crud/analysis/__init__.py@@ -46,9 +46,12 @@ from .dead_code import ()from .doc_drift import (doc_drift_findings_stored,+ doc_drift_last_written,+ doc_drift_pass_ran,doc_drift_references_stored,get_doc_drift_findings,get_doc_drift_references,+ is_new_doc_drift_row,replace_doc_drift_findings,replace_doc_drift_guarded,replace_doc_drift_references,@@ -127,6 +130,8 @@ __all__ = ["coverage_row_dict","covered_source_files","doc_drift_findings_stored",+ "doc_drift_last_written",+ "doc_drift_pass_ran","doc_drift_references_stored","empty_coverage_summary","file_coverage_from_row",@@ -158,6 +163,7 @@ __all__ = ["get_refactoring_summary","get_scored_file_paths","get_test_coverage_summary",+ "is_new_doc_drift_row","list_evidence_for_opportunities","list_health_snapshots","list_opportunity_evidence",diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/doc_drift.py b/packages/core/src/repowise/core/persistence/crud/analysis/doc_drift.pyindex 0f2f5e4ce..6592957f0 100644--- a/packages/core/src/repowise/core/persistence/crud/analysis/doc_drift.py+++ b/packages/core/src/repowise/core/persistence/crud/analysis/doc_drift.py@@ -5,9 +5,10 @@ from __future__ import annotationsimport jsonfrom collections.abc import Callable, Sequencefrom dataclasses import dataclass+from datetime import UTC, datetimefrom typing import Any-from sqlalchemy import delete, select+from sqlalchemy import delete, func, selectfrom sqlalchemy.ext.asyncio import AsyncSessionfrom repowise.core.analysis.doc_drift.constants import bucket_confidences@@ -75,6 +76,7 @@ async def _replace_scoped(items: list[Any],*,scoped: frozenset[str] | None,+ stamp: Callable[[dict], None] | None = None,) -> int:"""Delete-then-insert one drift table, converging on re-run.@@ -117,6 +119,8 @@ async def _replace_scoped(if key in seen:continueseen.add(key)+ if stamp is not None:+ stamp(kwargs)rows.append(kwargs)for i in range(0, len(rows), _BATCH_SIZE):@@ -162,14 +166,91 @@ async def replace_doc_drift_findings(other three hundred it never looked at. ``None`` means the run wasrepo-wide and every row is replaceable.+ Each row's ``first_seen_at`` is carried from the row it replaces, matched+ on (document, kind, target) so an edit that moves a line keeps its age.+ Ceiling: a renamed document's findings start a new age, as the key holds+ the path; carrying them needs the rename map the incremental pass has.Returns the number of rows inserted."""+ scoped = frozenset(scope) if scope is not None else None+ written_at = datetime.now(UTC)+ prior = await _first_seen_before(session, repository_id, scoped)++ def stamp(row: dict) -> None:+ row["detected_at"] = written_at+ if prior is None:+ # First check of this repository: nothing is new, only present.+ row["first_seen_at"] = None+ else:+ row["first_seen_at"] = prior.get(_age_key(row), written_at)+return await _replace_scoped(- session,- _FINDINGS_TABLE,- repository_id,- findings,- scoped=frozenset(scope) if scope is not None else None,+ session, _FINDINGS_TABLE, repository_id, findings, scoped=scoped, stamp=stamp+ )+++def _age_key(row: Any) -> tuple[str, str, str]:+ return (row["file_path"], row["kind"], row["target"])+++async def _first_seen_before(+ session: AsyncSession, repository_id: str, scoped: frozenset[str] | None+) -> dict[tuple[str, str, str], datetime | None] | None:+ """Earliest ``first_seen_at`` per key among the rows about to be replaced.++ ``None`` when the repository has no drift rows at all, which is a first+ check rather than a clean previous one.+ """+ if not await doc_drift_pass_ran(session, repository_id):+ return None+ cols = (+ DocDriftFinding.file_path,+ DocDriftFinding.kind,+ DocDriftFinding.target,+ DocDriftFinding.first_seen_at,+ )+ base = select(*cols).where(DocDriftFinding.repository_id == repository_id)+ if scoped is None:+ results = [(await session.execute(base)).all()]+ else:+ paths = sorted(scoped)+ results = [+ (+ await session.execute(+ base.where(DocDriftFinding.file_path.in_(paths[i : i + _IN_CLAUSE_CHUNK]))+ )+ ).all()+ for i in range(0, len(paths), _IN_CLAUSE_CHUNK)+ ]+ ages: dict[tuple[str, str, str], datetime | None] = {}+ for result in results:+ for row in result:+ key = _age_key(row._mapping)+ seen = row.first_seen_at+ # A null (present at the first check) is the oldest age there is.+ if key not in ages or seen is None or (ages[key] is not None and seen < ages[key]):+ ages[key] = seen+ return ages+++async def doc_drift_last_written(session: AsyncSession, repository_id: str) -> datetime | None:+ """When the most recent drift write that stored a finding ran."""+ stmt = select(func.max(DocDriftFinding.detected_at)).where(+ DocDriftFinding.repository_id == repository_id+ )+ return await session.scalar(stmt)+++def is_new_doc_drift_row(row: DocDriftFinding, last_written: datetime | None) -> bool:+ """Whether *row* first appeared in the latest write.++ Ceiling: a later write that stores no finding leaves the previous write as+ "latest", so its findings still read as new until one does.+ """+ return (+ row.first_seen_at is not None+ and last_written is not None+ and row.first_seen_at >= last_written)@@ -343,6 +424,13 @@ async def doc_drift_findings_stored(session: AsyncSession, repository_id: str) -return (await session.execute(stmt.limit(1))).scalar_one_or_none() is not None+async def doc_drift_pass_ran(session: AsyncSession, repository_id: str) -> bool:+ """Whether the drift pass has ever stored anything here: either table counts."""+ return await doc_drift_findings_stored(+ session, repository_id+ ) or await doc_drift_references_stored(session, repository_id)++def serialize_doc_drift_reference_row(row: DocDriftReference) -> dict:"""One stored reference as a dict, for any surface that serves it.diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/health.py b/packages/core/src/repowise/core/persistence/crud/analysis/health.pyindex 04c7d8c1f..d5492122f 100644--- a/packages/core/src/repowise/core/persistence/crud/analysis/health.py+++ b/packages/core/src/repowise/core/persistence/crud/analysis/health.py@@ -30,6 +30,7 @@ from ....analysis.health.scope import scores_languagefrom ....analysis.health.scoring import ADVISORY_DIMENSION, nloc_weighted_attrfrom ....test_paths import is_test_related_pathfrom ...models import (+ DocDriftFinding,GraphNode,HealthFileMetric,HealthFinding,@@ -771,6 +772,20 @@ HEALTH_SNAPSHOT_RETENTION: int = 50FILE_TREND_SNAPSHOT_WINDOW: int = 20+async def _doc_drift_count(session: AsyncSession, repository_id: str) -> int | None:+ """Stored drift findings; ``None`` when the drift pass has never run here."""+ from .doc_drift import doc_drift_pass_ran++ count = await session.scalar(+ select(func.count(DocDriftFinding.id)).where(+ DocDriftFinding.repository_id == repository_id+ )+ )+ if not count and not await doc_drift_pass_ran(session, repository_id):+ return None+ return int(count or 0)++async def save_health_snapshot(session: AsyncSession,repository_id: str,@@ -801,6 +816,9 @@ async def save_health_snapshot(``structure_average`` / ``history_average`` are ``average_health``'s twohalves in deduction points, so a later trend can name which one moved.++ The stored doc drift count is read here rather than passed in, so every+ writer records it without a new argument; write drift before calling this."""snap = HealthSnapshot(id=_new_uuid(),@@ -818,6 +836,7 @@ async def save_health_snapshot(history_average=history_average,production_average=production_average,maintainability_average=maintainability_average,+ doc_drift_count=await _doc_drift_count(session, repository_id),)session.add(snap)await session.flush()diff --git a/packages/core/src/repowise/core/persistence/models.py b/packages/core/src/repowise/core/persistence/models.pyindex 6216abb4b..3542bf1a0 100644--- a/packages/core/src/repowise/core/persistence/models.py+++ b/packages/core/src/repowise/core/persistence/models.py@@ -1701,6 +1701,9 @@ class DocDriftFinding(Base):detected_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=_now_utc)+ #: When this (document, kind, target) was first found, carried across+ #: rewrites. Null when it was already present at the first check.+ first_seen_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)class HealthFinding(Base):@@ -2186,6 +2189,8 @@ class HealthSnapshot(Base):# the trend can draw the number a refactor is meant to move beside the one# history drags on. NULL on snapshots taken before it was recorded.maintainability_average: Mapped[float | None] = mapped_column(Float, nullable=True)+ # Stored documentation drift findings at this instant. NULL before recorded.+ doc_drift_count: Mapped[int | None] = mapped_column(Integer, nullable=True)class CoverageFile(Base):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.pyindex cde60bf13..374b9416d 100644--- a/packages/server/src/repowise/server/routers/code_health/trends_routes.py+++ b/packages/server/src/repowise/server/routers/code_health/trends_routes.py@@ -94,9 +94,9 @@ async def health_trend(return {"history": (- drop_unscoped_fields(recent_kpis(snapshots, limit=limit))+ drop_unscoped_fields(recent_kpis(snapshots, limit=limit, doc_drift=True))if narrowed- else recent_kpis(snapshots, limit=limit)+ else recent_kpis(snapshots, limit=limit, doc_drift=True)),"summary": {"current_hotspot_health": None if narrowed else summary.current_hotspot_health,diff --git a/packages/server/src/repowise/server/routers/doc_drift.py b/packages/server/src/repowise/server/routers/doc_drift.pyindex db2610c7c..13761ffee 100644--- a/packages/server/src/repowise/server/routers/doc_drift.py+++ b/packages/server/src/repowise/server/routers/doc_drift.py@@ -107,10 +107,9 @@ async def list_doc_drift(# ``?min_confidence=0.7`` over findings that all sit lower would report# a tree holding findings as one nobody has ever checked.computed = (- bool(rows)- or await crud.doc_drift_findings_stored(session, repo_id)- or await crud.doc_drift_references_stored(session, repo_id)+ bool(rows) or await crud.doc_drift_pass_ran(session, repo_id))+ last_written = await crud.doc_drift_last_written(session, repo_id) if rows else Noneexcept (SQLAlchemyError, OSError, LookupError) as exc:return DocDriftResponse(findings=[],@@ -131,11 +130,19 @@ async def list_doc_drift(rows = [row for row in rows if row.kind == kind]serialized = [crud.serialize_doc_drift_row(row) for row in rows]- emitted = serialized[:limit]+ new = [crud.is_new_doc_drift_row(row, last_written) for row in rows]+ findings = []+ for row, data, is_new in zip(rows[:limit], serialized[:limit], new, strict=False):+ finding = DocDriftFindingResponse.from_dict(data)+ finding.first_seen_at = row.first_seen_at+ finding.is_new = is_new+ findings.append(finding)+ summary = summarize_findings(serialized)+ summary["new_since_last_update"] = sum(new)return DocDriftResponse(- findings=[DocDriftFindingResponse.from_dict(f) for f in emitted],- findings_emitted=len(emitted),- summary=summarize_findings(serialized),+ findings=findings,+ findings_emitted=len(findings),+ summary=summary,)diff --git a/packages/server/src/repowise/server/schemas/code_health.py b/packages/server/src/repowise/server/schemas/code_health.pyindex d4e5a1b54..c4f779d31 100644--- a/packages/server/src/repowise/server/schemas/code_health.py+++ b/packages/server/src/repowise/server/schemas/code_health.py@@ -99,6 +99,8 @@ class HealthTrendKpiRow(BaseModel):structure_average: float | None = Nonehistory_average: float | None = Nonemaintainability_average: float | None = None+ #: Stored documentation drift findings at this snapshot; ``None`` before recorded.+ doc_drift_count: int | None = Noneclass HealthTrendSummary(BaseModel):diff --git a/packages/server/src/repowise/server/schemas/doc_drift.py b/packages/server/src/repowise/server/schemas/doc_drift.pyindex 8337a0ee3..2f5207c0f 100644--- a/packages/server/src/repowise/server/schemas/doc_drift.py+++ b/packages/server/src/repowise/server/schemas/doc_drift.py@@ -14,6 +14,7 @@ claim that the tree is clean, and only a populated store can support it.from __future__ import annotations+from datetime import datetimefrom typing import Any, Literalfrom pydantic import BaseModel, model_validator@@ -60,6 +61,11 @@ class DocDriftFindingResponse(BaseModel):#: Likely replacement for a missing target, and the basis that found it.suggestion: str | None = Nonesuggestion_basis: str | None = None+ #: When first found, carried across updates; ``None`` when present at the+ #: first check or when the store keeps no history (an artifact).+ first_seen_at: datetime | None = None+ #: First found by the latest update that stored a finding.+ is_new: bool = False@model_validator(mode="before")@classmethod@@ -111,6 +117,9 @@ class DocDriftSummaryResponse(BaseModel):by_kind: dict[str, int]#: What the counts do and do not cover. No surface may show them without it.findings_basis: str+ #: Of ``findings_total``, how many are new since the last update (0 on a+ #: first check); ``None`` from a store that keeps no history.+ new_since_last_update: int | None = Noneclass DocDriftResponse(BaseModel):diff --git a/packages/types/src/doc-drift.ts b/packages/types/src/doc-drift.tsindex e2d9a101f..f65f20034 100644--- a/packages/types/src/doc-drift.ts+++ b/packages/types/src/doc-drift.ts@@ -135,6 +135,13 @@ export interface DocDriftFinding {suggestion?: string | null;/** Key of `SUGGESTION_BASIS_LABELS` naming how `suggestion` was found. */suggestion_basis?: string | null;+ /**+ * When first found, carried across updates. `null` when it was present at+ * the first check, or when the store keeps no history.+ */+ first_seen_at?: string | null;+ /** First found by the latest update that stored a finding. */+ is_new?: boolean;}/**@@ -155,6 +162,8 @@ export interface DocDriftSummary {* uncheckable by design, so no surface may show the counts without it.*/findings_basis: string;+ /** Of `findings_total`, how many are new since the last update; `null` without history. */+ new_since_last_update?: number | null;}export interface DocDriftResponse {diff --git a/packages/types/src/generated/http.ts b/packages/types/src/generated/http.tsindex 07a0355cd..c0cb140ee 100644--- a/packages/types/src/generated/http.ts+++ b/packages/types/src/generated/http.ts@@ -1120,6 +1120,8 @@ export interface DocDriftFindingResponse {fingerprint: string;suggestion?: string | null;suggestion_basis?: string | null;+ first_seen_at?: string | null;+ is_new?: boolean;}/**@@ -1168,6 +1170,7 @@ export interface DocDriftSummaryResponse {confidence: Record<string, number>;by_kind: Record<string, number>;findings_basis: string;+ new_since_last_update?: number | null;}export interface EgoGraphResponse {@@ -1720,6 +1723,7 @@ export interface HealthTrendKpiRow {structure_average?: number | null;history_average?: number | null;maintainability_average?: number | null;+ doc_drift_count?: number | null;}export interface HealthTrendResponse {diff --git a/packages/types/src/health.ts b/packages/types/src/health.tsindex 881af651e..bf90ed82e 100644--- a/packages/types/src/health.ts+++ b/packages/types/src/health.ts@@ -958,6 +958,8 @@ export interface HealthTrendResponse {structure_average?: number | null;history_average?: number | null;maintainability_average?: number | null;+ /** Stored documentation drift findings at this snapshot; `null` before recorded. */+ doc_drift_count?: number | null;}>;summary: {/** `null` under a narrowed scope: only the average covers both populations. */diff --git a/packages/ui/__tests__/doc-drift/doc-drift-view.test.tsx b/packages/ui/__tests__/doc-drift/doc-drift-view.test.tsxindex 6606f9d81..732efaff3 100644--- a/packages/ui/__tests__/doc-drift/doc-drift-view.test.tsx+++ b/packages/ui/__tests__/doc-drift/doc-drift-view.test.tsx@@ -113,6 +113,21 @@ function renderView(node: ReactElement) {}describe("DocDriftView", () => {+ it("marks findings new since the last update and counts them in the lede", async () => {+ const [first, second] = FINDINGS;+ const listFindings = vi.fn(async () =>+ response({+ findings: [{ ...first!, is_new: true }, second!],+ summary: { ...response().summary!, new_since_last_update: 1 },+ }),+ );+ renderView(<DocDriftView adapter={makeAdapter({ listFindings })} />);++ const table = await screen.findByRole("table", TABLE);+ expect(within(table).getAllByText("new")).toHaveLength(1);+ expect(screen.getByText(/1 appeared in the last update/)).toBeTruthy();+ });+it("leads with the count and names the documents to edit", async () => {renderView(<DocDriftView adapter={makeAdapter()} />);diff --git a/packages/ui/src/doc-drift/doc-drift-lede.tsx b/packages/ui/src/doc-drift/doc-drift-lede.tsxindex 3b5c2e7ab..c783b8f0c 100644--- a/packages/ui/src/doc-drift/doc-drift-lede.tsx+++ b/packages/ui/src/doc-drift/doc-drift-lede.tsx@@ -128,6 +128,13 @@ export function DocDriftLede({</>) : null}. Each one names the document to edit, not the file it points at.+ {summary.new_since_last_update ? (+ <>+ {" "}+ {formatNumber(summary.new_since_last_update)} appeared in the last+ update.+ </>+ ) : null}</p><p className="mt-2.5">{summary.findings_basis}</p><p className="mt-2.5">diff --git a/packages/ui/src/doc-drift/drift-findings-table.tsx b/packages/ui/src/doc-drift/drift-findings-table.tsxindex e7525549b..9f9a9218c 100644--- a/packages/ui/src/doc-drift/drift-findings-table.tsx+++ b/packages/ui/src/doc-drift/drift-findings-table.tsx@@ -15,6 +15,7 @@*/import { FileText } from "lucide-react";+import { Badge } from "../ui/badge";import {docDriftConfidenceTier,docDriftKindLabel,@@ -79,6 +80,11 @@ export function DriftFindingsTable({>{f.file_path}<span className="text-[var(--color-text-tertiary)]">:{f.line_number}</span>+ {f.is_new ? (+ <Badge variant="accent" className="ml-1.5 h-4 px-1 text-[10px]">+ new+ </Badge>+ ) : null}</span><spanclassName="truncate text-xs text-[var(--color-text-tertiary)]"diff --git a/tests/unit/health/test_trends.py b/tests/unit/health/test_trends.pyindex 602156ba8..86c83cc03 100644--- a/tests/unit/health/test_trends.py+++ b/tests/unit/health/test_trends.py@@ -11,6 +11,7 @@ from repowise.core.analysis.health.trends import (DECLINE_LOOKBACK,DECLINE_THRESHOLD,diff_snapshots,+ drop_unscoped_fields,file_score_series,file_trend,recent_kpis,@@ -92,6 +93,15 @@ def test_recent_kpis_orders_newest_first():assert scores == [7.0, 6.0, 5.0]+def test_recent_kpis_carries_the_drift_count_only_when_asked():+ snaps = _series([5.0, 6.0])+ snaps[1].doc_drift_count = 3+ assert "doc_drift_count" not in recent_kpis(snaps)[0]+ rows = recent_kpis(snaps, doc_drift=True)+ assert [r["doc_drift_count"] for r in rows] == [3, None]+ assert drop_unscoped_fields(rows)[0]["doc_drift_count"] is None++# --------------------------------------------------------------------------- ## Attribution: what a decline is blamed on# --------------------------------------------------------------------------- #diff --git a/tests/unit/persistence/test_doc_drift_crud.py b/tests/unit/persistence/test_doc_drift_crud.pyindex 35d83e2a4..729bb5a06 100644--- a/tests/unit/persistence/test_doc_drift_crud.py+++ b/tests/unit/persistence/test_doc_drift_crud.py@@ -10,8 +10,11 @@ from sqlalchemy import selectfrom repowise.core.analysis.doc_drift.models import DocDriftFindingData, DriftKindfrom repowise.core.persistence.crud import (+ doc_drift_last_written,get_doc_drift_findings,+ is_new_doc_drift_row,replace_doc_drift_findings,+ save_health_snapshot,)from repowise.core.persistence.crud.analysis.doc_drift import summarize_confidence_rowsfrom repowise.core.persistence.models import DocDriftFinding@@ -269,3 +272,65 @@ async def test_unreadable_evidence_degrades_to_none_rather_than_raising():for blob in ("{not json", '{"a": 1}', "", None):assert serialize_doc_drift_row(_row(blob))["evidence"] == []+++async def test_the_first_check_marks_nothing_new(async_session):+ repo = await insert_repo(async_session)+ await replace_doc_drift_findings(async_session, repo.id, [_finding()])+ await async_session.commit()++ (row,) = await _rows(async_session, repo.id)+ assert row.first_seen_at is None+ last = await doc_drift_last_written(async_session, repo.id)+ assert not is_new_doc_drift_row(row, last)+++async def test_a_finding_keeps_its_age_when_its_line_moves(async_session):+ repo = await insert_repo(async_session)+ await replace_doc_drift_findings(async_session, repo.id, [_finding(target="src/x.py")])+ await replace_doc_drift_findings(+ async_session, repo.id, [_finding(target="src/x.py"), _finding(line=20)]+ )+ (first,) = [r for r in await _rows(async_session, repo.id) if r.line_number == 20]+ seen = first.first_seen_at+ assert seen is not None++ # The same finding, pushed down by an edit above it: same age, no longer new.+ await replace_doc_drift_findings(+ async_session, repo.id, [_finding(target="src/x.py"), _finding(line=25)]+ )+ await async_session.commit()+ rows = {r.line_number: r for r in await _rows(async_session, repo.id)}+ assert rows[25].first_seen_at == seen+ last = await doc_drift_last_written(async_session, repo.id)+ assert not is_new_doc_drift_row(rows[25], last)+ assert rows[10].first_seen_at is None+++async def test_only_the_latest_writes_arrivals_read_as_new(async_session):+ repo = await insert_repo(async_session)+ await replace_doc_drift_findings(async_session, repo.id, [_finding(target="src/a.py")])+ await replace_doc_drift_findings(+ async_session, repo.id, [_finding(target="src/a.py"), _finding(target="src/b.py")]+ )+ await async_session.commit()++ last = await doc_drift_last_written(async_session, repo.id)+ new = {r.target: is_new_doc_drift_row(r, last) for r in await _rows(async_session, repo.id)}+ assert new == {"src/a.py": False, "src/b.py": True}+++async def test_a_snapshot_records_the_stored_drift_count(async_session):+ repo = await insert_repo(async_session)+ kwargs = dict(+ hotspot_health=8.0,+ average_health=8.0,+ worst_performer_path=None,+ worst_performer_score=None,+ )+ never = await save_health_snapshot(async_session, repo.id, **kwargs)+ assert never.doc_drift_count is None++ await replace_doc_drift_findings(async_session, repo.id, [_finding(), _finding(line=2)])+ counted = await save_health_snapshot(async_session, repo.id, **kwargs)+ assert counted.doc_drift_count == 2diff --git a/tests/unit/server/test_doc_drift.py b/tests/unit/server/test_doc_drift.pyindex 89a03d874..84948a3fd 100644--- a/tests/unit/server/test_doc_drift.py+++ b/tests/unit/server/test_doc_drift.py@@ -94,6 +94,42 @@ class TestFindings:assert data["summary"]["confidence"] == {"high": 2, "medium": 1, "low": 0}assert data["summary"]["by_kind"] == {"anchor": 1, "path": 2}+ @pytest.mark.asyncio+ async def test_findings_new_since_the_last_update_are_marked(+ self, client: AsyncClient, app+ ) -> None:+ repo = await create_test_repo(client)+ await _seed(app.state.session_factory, repo["id"], findings=[_finding()])+ await _seed(+ app.state.session_factory,+ repo["id"],+ findings=[_finding(), _finding(target="src/new.py", raw="src/new.py")],+ )++ data = (await client.get(f"/api/repos/{repo['id']}/doc-drift")).json()+ new = {f["target"]: (f["is_new"], f["first_seen_at"]) for f in data["findings"]}+ assert new["src/auth.py"] == (False, None)+ assert new["src/new.py"][0] is True+ assert new["src/new.py"][1] is not None+ assert data["summary"]["new_since_last_update"] == 1++ @pytest.mark.asyncio+ async def test_a_failing_history_read_is_reported_not_raised(+ self, client: AsyncClient, app, monkeypatch+ ) -> None:+ from sqlalchemy.exc import OperationalError++ repo = await create_test_repo(client)+ await _seed(app.state.session_factory, repo["id"], findings=[_finding()])++ async def _locked(*_a, **_k):+ raise OperationalError("select", {}, Exception("database is locked"))++ monkeypatch.setattr(crud, "doc_drift_last_written", _locked)+ resp = await client.get(f"/api/repos/{repo['id']}/doc-drift")+ assert resp.status_code == 200+ assert resp.json()["unavailable"] == "drift_read_failed"+@pytest.mark.asyncioasync def test_a_count_never_travels_without_what_it_covers(self, client: AsyncClient, app