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): keep documentation findings current on every update (#2307)

Raghav Chamadiyaf5cf253ff112
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/__init__.py b/packages/cli/src/repowise/cli/commands/update_cmd/__init__.py
index 9034d8dec..189e4672c 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/__init__.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/__init__.py
@@ -14,6 +14,7 @@ from .incremental import (
_build_repo_graph,
_build_update_vector_store,
_rebuild_graph_and_git,
+ _run_doc_drift_partial,
_run_partial_analysis,
)
from .mode import _resolve_index_only_mode
@@ -39,6 +40,7 @@ __all__ = [
"_refresh_workspace_editor_project_files",
"_render_update_report",
"_resolve_index_only_mode",
+ "_run_doc_drift_partial",
"_run_full_health_rescore",
"_run_partial_analysis",
"_workspace_update",
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/command.py b/packages/cli/src/repowise/cli/commands/update_cmd/command.py
index c2217ed15..03e7fd5b1 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/command.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/command.py
@@ -51,6 +51,7 @@ from .incremental import (
_load_stored_performance_callers,
_rebuild_graph_and_git,
_refresh_knowledge_graph,
+ _run_doc_drift_partial,
_run_partial_analysis,
)
from .mode import _resolve_index_only_mode
@@ -1485,6 +1486,7 @@ def run_update(
repo_function_mod_p80=repo_function_mod_p80,
timings=timings,
)
+ doc_drift_report = _run_doc_drift_partial(graph_builder, source_map, timings=timings)
# Partial health has consumed the per-file ``BlameIndex``; drop it before
# the metadata reaches persistence / regeneration so the transient,
@@ -1659,6 +1661,7 @@ def run_update(
head,
start,
persisted_changed_paths,
+ doc_drift_report=doc_drift_report,
file_diffs=file_diffs,
knowledge_graph_result=knowledge_graph_result,
parsed_files=parsed_files,
@@ -2300,6 +2303,7 @@ def run_update(
graph_builder=graph_builder,
knowledge_graph_result=knowledge_graph_result,
degraded=degraded,
+ doc_drift_report=doc_drift_report,
decay_paths=affected.decay_only,
parsed_files=parsed_files,
git_decay_map=git_decay_map,
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/incremental.py b/packages/cli/src/repowise/cli/commands/update_cmd/incremental.py
index 4c50cfc7a..8b3f057a3 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/incremental.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/incremental.py
@@ -249,3 +249,17 @@ def _run_partial_analysis(
log=console.print,
timings=timings,
)
+
+
+def _run_doc_drift_partial(
+ graph_builder: Any,
+ source_map: dict[str, bytes] | None,
+ *,
+ timings: PhaseTimings | None = None,
+) -> Any | None:
+ """Re-check the repo's markdown against the tree. Delegates to core."""
+ from repowise.core.pipeline.incremental import run_doc_drift_partial
+
+ return run_doc_drift_partial(
+ graph_builder, source_map, log=console.print, timings=timings
+ )
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 da61e54c9..3d8e2c429 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py
@@ -359,6 +359,7 @@ def _persist_index_only_update(
head: str | None,
start: float,
changed_paths: list[str],
+ doc_drift_report: Any | None = None,
file_diffs: list | None = None,
knowledge_graph_result: Any | None = None,
parsed_files: list | None = None,
@@ -409,6 +410,7 @@ def _persist_index_only_update(
dead_code_report,
partial_health_report,
changed_paths,
+ doc_drift_report=doc_drift_report,
file_diffs=file_diffs,
knowledge_graph_result=knowledge_graph_result,
parsed_files=parsed_files,
@@ -635,6 +637,7 @@ def _persist_full_update(
graph_builder: Any,
knowledge_graph_result: Any | None,
degraded: list[str],
+ doc_drift_report: Any | None = None,
decay_paths: list[str] | None = None,
parsed_files: list | None = None,
git_decay_map: dict | None = None,
@@ -675,6 +678,7 @@ def _persist_full_update(
graph_builder=graph_builder,
knowledge_graph_result=knowledge_graph_result,
degraded=degraded,
+ doc_drift_report=doc_drift_report,
decay_paths=decay_paths,
parsed_files=parsed_files,
git_decay_map=git_decay_map,
@@ -703,6 +707,7 @@ async def _persist_full_update_async(
graph_builder: Any,
knowledge_graph_result: Any | None,
degraded: list[str],
+ doc_drift_report: Any | None = None,
decay_paths: list[str] | None = None,
parsed_files: list | None = None,
git_decay_map: dict | None = None,
@@ -1119,6 +1124,21 @@ 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 findings.
+ if doc_drift_report is not None:
+ try:
+ from repowise.core.persistence.crud import (
+ replace_doc_drift_findings_guarded,
+ )
+
+ with timed(timings, "persist.doc_drift"):
+ await replace_doc_drift_findings_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/src/repowise/core/analysis/doc_drift/analyzer.py b/packages/core/src/repowise/core/analysis/doc_drift/analyzer.py
index be01a863a..f6e843f45 100644
--- a/packages/core/src/repowise/core/analysis/doc_drift/analyzer.py
+++ b/packages/core/src/repowise/core/analysis/doc_drift/analyzer.py
@@ -180,6 +180,7 @@ class DocDriftAnalyzer:
verdict_summary=verdict_counts,
anchor_renderer=index.renderers.summary(),
hidden_below_threshold=hidden,
+ documents=frozenset(documents),
)
diff --git a/packages/core/src/repowise/core/analysis/doc_drift/models.py b/packages/core/src/repowise/core/analysis/doc_drift/models.py
index db1d085e5..845261e94 100644
--- a/packages/core/src/repowise/core/analysis/doc_drift/models.py
+++ b/packages/core/src/repowise/core/analysis/doc_drift/models.py
@@ -125,6 +125,11 @@ class DocDriftReport:
"""Which renderer's slug algorithm the anchor class used, or the renderer
that caused it to stand down. See :mod:`~.renderer`."""
hidden_below_threshold: int = 0
+ documents: frozenset[str] = field(default_factory=frozenset)
+ """Every document this run actually read, of which ``documents_scanned`` is
+ the count. A document that missed ``source_map`` (transient read failure, or
+ markdown over :data:`~.constants.MAX_DOC_BYTES`) is absent, which is what
+ stops a scoped write from deleting findings it never recomputed."""
authoritative_paths: frozenset[str] | None = field(default=None)
"""Document paths this report may speak for; ``None`` means all of them.
Mirrors dead code's field of the same name so an incremental re-check can
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 efd8ad568..bd6adbf2b 100644
--- a/packages/core/src/repowise/core/persistence/crud/analysis/__init__.py
+++ b/packages/core/src/repowise/core/persistence/crud/analysis/__init__.py
@@ -40,6 +40,7 @@ from .dead_code import (
from .doc_drift import (
get_doc_drift_findings,
replace_doc_drift_findings,
+ replace_doc_drift_findings_guarded,
summarize_confidence_rows,
)
from .health import (
@@ -150,6 +151,7 @@ __all__ = [
"refactoring_facet_counts",
"replace_dead_code_findings",
"replace_doc_drift_findings",
+ "replace_doc_drift_findings_guarded",
"replace_governance_findings",
"save_coverage_files",
"save_dead_code_findings",
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 b9ac91ea4..1ca70923a 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
@@ -118,6 +118,29 @@ async def replace_doc_drift_findings(
return len(rows)
+async def replace_doc_drift_findings_guarded(
+ session: AsyncSession,
+ repository_id: str,
+ report: Any,
+) -> int:
+ """:func:`replace_doc_drift_findings` inside a savepoint, from a *report*.
+
+ Every caller reports failure as a warning rather than raising, and this is a
+ DELETE followed by an INSERT. Without the savepoint a failing insert leaves
+ the DELETE buffered in the caller's live transaction, which then commits it:
+ every drift row for the repository wiped, reported only as a warning. On
+ Postgres the same failure poisons the transaction and takes the other
+ analyses down with it.
+ """
+ async with session.begin_nested():
+ return await replace_doc_drift_findings(
+ session,
+ repository_id,
+ report.findings,
+ scope=report.authoritative_paths,
+ )
+
+
async def get_doc_drift_findings(
session: AsyncSession,
repository_id: str,
diff --git a/packages/core/src/repowise/core/pipeline/incremental.py b/packages/core/src/repowise/core/pipeline/incremental.py
index 2565d78c0..c41dd1e71 100644
--- a/packages/core/src/repowise/core/pipeline/incremental.py
+++ b/packages/core/src/repowise/core/pipeline/incremental.py
@@ -876,6 +876,48 @@ def run_partial_analysis(
return partial_health_report, dead_code_report
+def run_doc_drift_partial(
+ graph_builder: Any,
+ source_map: dict[str, bytes] | None,
+ *,
+ log: LogFn | None = None,
+ timings: PhaseTimings | None = None,
+) -> Any | None:
+ """Re-check the repository's own markdown on the incremental path.
+
+ Its own function rather than a third member of
+ :func:`run_partial_analysis`'s tuple, mirroring the full path where drift is
+ its own phase. Returns ``None`` when the pass could not run, which the
+ caller must treat as "write nothing".
+ """
+ log = log or _noop_log
+ if not source_map:
+ return None
+
+ with timed(timings, "analysis.doc_drift"):
+ try:
+ from repowise.core.analysis.doc_drift import DocDriftAnalyzer
+
+ # The traversal, not the parse set. ``source_map`` omits files that
+ # failed to read or parse, and resolving against that narrower tree
+ # turns a live path into a fabricated "missing" finding.
+ tracked_paths = getattr(graph_builder, "traversed_file_paths", None)
+ if not tracked_paths:
+ return None
+
+ report = DocDriftAnalyzer(
+ source_map=source_map,
+ tracked_paths=tracked_paths,
+ ).analyze()
+ report.authoritative_paths = report.documents
+ if report.total_findings:
+ log(f"Doc drift findings: [yellow]{report.total_findings}[/yellow]")
+ return report
+ except Exception as exc:
+ log(f"[yellow]Doc drift analysis skipped: {exc}[/yellow]")
+ return None
+
+
async def refresh_knowledge_graph(
repo_path: Any,
parsed_files: list,
@@ -1677,6 +1719,7 @@ async def persist_incremental_index(
partial_health_report: Any,
changed_paths: list[str],
*,
+ doc_drift_report: Any | None = None,
current_graph_file_paths: set[str] | None = None,
file_diffs: list[Any] | None = None,
knowledge_graph_result: Any | None = None,
@@ -1892,6 +1935,21 @@ async def persist_incremental_index(
except Exception as exc:
_skip("Dead-code persist", exc, range_scoped=True)
+ if doc_drift_report is not None:
+ try:
+ from repowise.core.persistence.crud import (
+ replace_doc_drift_findings_guarded,
+ )
+
+ with timed(timings, "persist.doc_drift"):
+ await replace_doc_drift_findings_guarded(
+ session, repo_id, doc_drift_report
+ )
+ except Exception as exc:
+ # Not range_scoped: the pass re-derives every document each
+ # run, so a skipped write heals itself on the next update.
+ _skip("Doc-drift persist", exc)
+
if partial_health_report is not None:
try:
with timed(timings, "persist.health"):
diff --git a/packages/core/src/repowise/core/pipeline/persist.py b/packages/core/src/repowise/core/pipeline/persist.py
index 9eee08939..a4cba9c5d 100644
--- a/packages/core/src/repowise/core/pipeline/persist.py
+++ b/packages/core/src/repowise/core/pipeline/persist.py
@@ -1162,11 +1162,13 @@ async def prune_deleted_file_rows(
await _prune_table(WikiSymbol, WikiSymbol.file_path, "wiki_symbols")
await _prune_table(SecurityFinding, SecurityFinding.file_path, "security_findings")
await _prune_table(DeadCodeFinding, DeadCodeFinding.file_path, "dead_code_findings")
- # Keyed on the DOCUMENT, and the drift pass does not run on the
- # incremental path, so without this a deleted document's findings are
- # never recomputed and never removed: they outlive the file until the
- # next full index. ``_FileLiveness`` asks disk and ``git ls-files``
- # rather than the parse, so a ``.md`` path is judged correctly here.
+ # Keyed on the DOCUMENT. The incremental drift pass scopes its write to the
+ # documents it read, so a deleted one is never in scope and its rows would
+ # outlive the file without this. ``_FileLiveness`` asks disk and
+ # ``git ls-files`` rather than the parse, so a ``.md`` path is judged
+ # correctly here. Note the LLM-regenerating update path never reaches this
+ # function, so drift rows for a document deleted there wait for a reindex,
+ # as dead-code and health rows already do.
await _prune_table(DocDriftFinding, DocDriftFinding.file_path, "doc_drift_findings")
await _prune_table(HealthFileMetric, HealthFileMetric.file_path, "health_file_metrics")
await _prune_table(HealthFinding, HealthFinding.file_path, "health_findings")
@@ -1914,7 +1916,7 @@ async def persist_analysis(result: Any, session: Any, repo_id: str) -> None:
from repowise.core.persistence.crud import (
bulk_upsert_decisions,
recompute_decision_staleness,
- replace_doc_drift_findings,
+ replace_doc_drift_findings_guarded,
save_coverage_files,
save_dead_code_findings,
upsert_git_function_blame_bulk,
@@ -1933,20 +1935,7 @@ async def persist_analysis(result: Any, session: Any, repo_id: str) -> None:
drift = getattr(result, "doc_drift_report", None)
if drift is not None:
try:
- # Inside a savepoint because this is a DELETE followed by an
- # INSERT and the failure is swallowed. Without one, a failing
- # insert leaves the DELETE buffered in the caller's still-live
- # transaction, which then commits it: every drift row for the
- # repository wiped, reported only as a warning. On Postgres the
- # same failure poisons the transaction and takes health,
- # coverage and decisions down with it.
- async with session.begin_nested():
- await replace_doc_drift_findings(
- session,
- repo_id,
- drift.findings,
- scope=drift.authoritative_paths,
- )
+ await replace_doc_drift_findings_guarded(session, repo_id, drift)
except Exception as exc:
logger.warning("doc_drift_persist_skipped", error=str(exc))
diff --git a/packages/core/src/repowise/core/pipeline/phases/analysis.py b/packages/core/src/repowise/core/pipeline/phases/analysis.py
index 9efce9fc3..4011f24b6 100644
--- a/packages/core/src/repowise/core/pipeline/phases/analysis.py
+++ b/packages/core/src/repowise/core/pipeline/phases/analysis.py
@@ -117,8 +117,9 @@ async def _run_doc_drift_analysis(
"""Check the repository's own markdown against the tree (no LLM).
Reads bytes ingestion already decoded rather than re-walking the tree: this
- runs on every ``init`` and every ``update``, so a second pass over the
- repository would be a real regression.
+ runs on every ``init``, and the update path runs the same analyzer through
+ :func:`~repowise.core.pipeline.incremental.run_doc_drift_partial`, so a
+ second pass over the repository would be a real regression.
"""
try:
from repowise.core.analysis.doc_drift import DocDriftAnalyzer
diff --git a/packages/core/src/repowise/core/workspace/update.py b/packages/core/src/repowise/core/workspace/update.py
index 0ab836a3f..a94d88650 100644
--- a/packages/core/src/repowise/core/workspace/update.py
+++ b/packages/core/src/repowise/core/workspace/update.py
@@ -380,6 +380,7 @@ async def _incremental_repo_update(
from ..pipeline.incremental import (
persist_incremental_index,
rebuild_graph_and_git,
+ run_doc_drift_partial,
run_partial_analysis,
)
from ..pipeline.phases.git import drop_transient_git_signals
@@ -484,6 +485,7 @@ async def _incremental_repo_update(
coverage_map=stored_coverage_map,
log=_log.info,
)
+ doc_drift_report = run_doc_drift_partial(graph_builder, source_map, log=_log.info)
# Partial health has consumed the per-file ``BlameIndex``; drop it before
# the metadata reaches persistence so the transient, non-serializable
@@ -513,6 +515,7 @@ async def _incremental_repo_update(
dead_code_report,
partial_health_report,
[fd.path for fd in file_diffs],
+ doc_drift_report=doc_drift_report,
current_graph_file_paths={pf.file_info.path for pf in parsed_files},
# Tombstones pages for deleted/renamed paths, mirroring the single-repo
# path — without this a page for a removed file misleads retrieval
diff --git a/tests/unit/persistence/test_doc_drift_crud.py b/tests/unit/persistence/test_doc_drift_crud.py
index de700b270..81b43748c 100644
--- a/tests/unit/persistence/test_doc_drift_crud.py
+++ b/tests/unit/persistence/test_doc_drift_crud.py
@@ -155,6 +155,37 @@ async def test_scoped_replace_drops_findings_outside_its_scope(async_session):
assert {r.file_path for r in await _rows(async_session, repo.id)} == {"docs/a.md"}
+async def test_an_unreadable_document_keeps_the_findings_it_earned(async_session):
+ """The incremental scope is the documents the pass actually read.
+
+ A document that exists but missed ``source_map`` this run (transient read
+ failure, or markdown over MAX_DOC_BYTES) is absent from the scope, so its
+ rows survive. A repo-wide write would delete them and nothing would put
+ them back: ``prune_deleted_file_rows`` correctly judges the file live.
+ """
+ repo = await insert_repo(async_session)
+ await replace_doc_drift_findings(
+ async_session,
+ repo.id,
+ [_finding(file_path="docs/read.md"), _finding(file_path="docs/unreadable.md")],
+ )
+ await async_session.commit()
+
+ # Second run could not open docs/unreadable.md, so it is not in scope.
+ await replace_doc_drift_findings(
+ async_session,
+ repo.id,
+ [_finding(file_path="docs/read.md")],
+ scope={"docs/read.md"},
+ )
+ await async_session.commit()
+
+ assert {r.file_path for r in await _rows(async_session, repo.id)} == {
+ "docs/read.md",
+ "docs/unreadable.md",
+ }
+
+
async def test_min_confidence_filter_on_read(async_session):
repo = await insert_repo(async_session)
await replace_doc_drift_findings(
diff --git a/tests/unit/pipeline/test_doc_drift_incremental.py b/tests/unit/pipeline/test_doc_drift_incremental.py
new file mode 100644
index 000000000..bf966f932
--- /dev/null
+++ b/tests/unit/pipeline/test_doc_drift_incremental.py
@@ -0,0 +1,169 @@
+"""The drift pass on the incremental update path.
+
+Phase 3 measured a persisted reverse index and refused it: the pass is 0.19s
+against a 125s floor for the cheapest real update, and its input is already in
+``source_map``. These pin the recompute design instead, and specifically the
+three ways it can be silently wrong.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+from repowise.core.analysis.doc_drift import DocDriftAnalyzer
+from repowise.core.pipeline import PhaseTimings
+from repowise.core.pipeline.incremental import run_doc_drift_partial
+
+
+class _Builder:
+ """Stands in for the graph builder, carrying only what the pass reads."""
+
+ def __init__(self, tracked: set[str] | None) -> None:
+ if tracked is not None:
+ self.traversed_file_paths = tracked
+
+
+def _sources(doc: bytes) -> dict[str, bytes]:
+ return {"docs/guide.md": doc, "src/real.py": b"x = 1\n"}
+
+
+def test_a_document_naming_a_live_file_is_not_a_finding() -> None:
+ report = run_doc_drift_partial(
+ _Builder({"docs/guide.md", "src/real.py"}),
+ _sources(b"# Guide\n\nSee `src/real.py` for details.\n"),
+ )
+ assert report is not None
+ assert report.total_findings == 0
+
+
+def test_a_document_naming_a_missing_file_is_a_finding() -> None:
+ report = run_doc_drift_partial(
+ _Builder({"docs/guide.md", "src/real.py"}),
+ _sources(b"# Guide\n\nSee `src/gone.py` for details.\n"),
+ )
+ assert report is not None
+ assert [f.target for f in report.findings] == ["src/gone.py"]
+
+
+def test_the_write_is_scoped_to_the_documents_actually_read() -> None:
+ """``authoritative_paths`` is the scanned set, never None.
+
+ A repo-wide scope would delete the findings of a document this run could
+ not open, and nothing would write them back: ``prune_deleted_file_rows``
+ correctly judges the file live and leaves it alone.
+ """
+ report = run_doc_drift_partial(
+ _Builder({"docs/guide.md", "docs/unread.md", "src/real.py"}),
+ _sources(b"# Guide\n\nSee `src/gone.py`.\n"),
+ )
+ assert report is not None
+ assert report.authoritative_paths == frozenset({"docs/guide.md"})
+ assert "docs/unread.md" not in report.authoritative_paths
+
+
+def test_tracked_paths_come_from_the_traversal_not_the_source_map() -> None:
+ """A file that failed to parse is still part of the tree.
+
+ ``source_map`` omits it; resolving against that narrower set would report a
+ live path as missing, which is a fabricated finding rather than drift.
+ """
+ report = run_doc_drift_partial(
+ # ``src/unparsed.py`` is tracked but absent from source_map.
+ _Builder({"docs/guide.md", "src/real.py", "src/unparsed.py"}),
+ _sources(b"# Guide\n\nSee `src/unparsed.py`.\n"),
+ )
+ assert report is not None
+ assert report.total_findings == 0
+
+
+def test_a_builder_without_a_traversal_skips_rather_than_falling_back() -> None:
+ """No tracked set means write nothing, never "use the source_map keys".
+
+ The fallback would narrow the tree and fabricate findings, and the report
+ would look perfectly valid on the way to a scoped delete.
+ """
+ assert run_doc_drift_partial(_Builder(None), _sources(b"See `src/gone.py`.\n")) is None
+ assert run_doc_drift_partial(_Builder(set()), _sources(b"See `src/gone.py`.\n")) is None
+
+
[email protected]("empty", [None, {}])
+def test_an_empty_source_map_returns_none_rather_than_an_empty_report(empty: Any) -> None:
+ """``analyze()`` does not raise on an empty source_map.
+
+ It returns a valid zero-finding report, so without this guard a run whose
+ ingestion degraded would look like a clean pass. Returning ``None`` keeps
+ "the pass did not run" distinguishable from "the pass found nothing".
+ """
+ assert run_doc_drift_partial(_Builder({"docs/guide.md"}), empty) is None
+
+
+def test_a_clean_run_still_returns_a_report_so_stale_rows_are_cleared() -> None:
+ """Zero findings is a result, not a reason to skip the write."""
+ report = run_doc_drift_partial(
+ _Builder({"docs/guide.md", "src/real.py"}),
+ _sources(b"# Guide\n\nNothing to see.\n"),
+ )
+ assert report is not None
+ assert report.findings == []
+ assert report.authoritative_paths == frozenset({"docs/guide.md"})
+
+
+def test_an_analyzer_failure_degrades_to_none(monkeypatch: pytest.MonkeyPatch) -> None:
+ """The pass is best-effort; it must never take an update down."""
+ import repowise.core.analysis.doc_drift as dd
+
+ def _boom(*_args: Any, **_kwargs: Any) -> Any:
+ raise RuntimeError("analyzer exploded")
+
+ monkeypatch.setattr(dd, "DocDriftAnalyzer", _boom)
+ messages: list[str] = []
+ assert (
+ run_doc_drift_partial(
+ _Builder({"docs/guide.md"}),
+ _sources(b"See `src/gone.py`.\n"),
+ log=messages.append,
+ )
+ is None
+ )
+ assert any("Doc drift" in m for m in messages)
+
+
+def test_the_pass_records_its_own_timing_row() -> None:
+ """Visible as ``analysis.doc_drift`` rather than absorbed into rebuild."""
+ timings = PhaseTimings()
+ run_doc_drift_partial(
+ _Builder({"docs/guide.md", "src/real.py"}),
+ _sources(b"# Guide\n"),
+ timings=timings,
+ )
+ assert "analysis.doc_drift" in timings.totals
+
+
+def test_the_incremental_pass_agrees_with_the_full_one() -> None:
+ """Same analyzer, same inputs, same findings.
+
+ This is the whole argument for recomputing instead of caching: there is no
+ second code path that can disagree with the first.
+ """
+ sources = _sources(b"# Guide\n\nSee `src/gone.py` and `src/real.py`.\n")
+ tracked = {"docs/guide.md", "src/real.py"}
+
+ full = DocDriftAnalyzer(source_map=sources, tracked_paths=tracked).analyze()
+ partial = run_doc_drift_partial(_Builder(tracked), sources)
+
+ assert partial is not None
+ assert [(f.file_path, f.target) for f in partial.findings] == [
+ (f.file_path, f.target) for f in full.findings
+ ]
+
+
+def test_documents_is_the_set_behind_documents_scanned() -> None:
+ report = DocDriftAnalyzer(
+ source_map=_sources(b"# Guide\n"),
+ tracked_paths={"docs/guide.md", "src/real.py"},
+ ).analyze()
+ assert report.documents == frozenset({"docs/guide.md"})
+ # src/real.py is in source_map but is not a document.
+ assert "src/real.py" not in report.documents