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(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.py
index 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 [], None
snaps = 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.py
index 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.py
new file mode 100644
index 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.py
index 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 when
flipped, 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 rows
diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/__init__.py b/packages/core/src/repowise/core/persistence/crud/analysis/__init__.py
index 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.py
index 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 annotations
import json
from collections.abc import Callable, Sequence
from dataclasses import dataclass
+from datetime import UTC, datetime
from typing import Any
-from sqlalchemy import delete, select
+from sqlalchemy import delete, func, select
from sqlalchemy.ext.asyncio import AsyncSession
from 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:
continue
seen.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 was
repo-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.py
index 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_language
from ....analysis.health.scoring import ADVISORY_DIMENSION, nloc_weighted_attr
from ....test_paths import is_test_related_path
from ...models import (
+ DocDriftFinding,
GraphNode,
HealthFileMetric,
HealthFinding,
@@ -771,6 +772,20 @@ HEALTH_SNAPSHOT_RETENTION: int = 50
FILE_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 two
halves 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.py
index 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.py
index 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.py
index 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 None
except (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.py
index 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 = None
history_average: float | None = None
maintainability_average: float | None = None
+ #: Stored documentation drift findings at this snapshot; ``None`` before recorded.
+ doc_drift_count: int | None = None
class HealthTrendSummary(BaseModel):
diff --git a/packages/server/src/repowise/server/schemas/doc_drift.py b/packages/server/src/repowise/server/schemas/doc_drift.py
index 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 datetime
from typing import Any, Literal
from 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 = None
suggestion_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 = None
class DocDriftResponse(BaseModel):
diff --git a/packages/types/src/doc-drift.ts b/packages/types/src/doc-drift.ts
index 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.ts
index 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.ts
index 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.tsx
index 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.tsx
index 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.tsx
index 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>
<span
className="truncate text-xs text-[var(--color-text-tertiary)]"
diff --git a/tests/unit/health/test_trends.py b/tests/unit/health/test_trends.py
index 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.py
index 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 select
from repowise.core.analysis.doc_drift.models import DocDriftFindingData, DriftKind
from 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_rows
from 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 == 2
diff --git a/tests/unit/server/test_doc_drift.py b/tests/unit/server/test_doc_drift.py
index 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.asyncio
async def test_a_count_never_travels_without_what_it_covers(
self, client: AsyncClient, app