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): 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__.pyindex 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.pyindex 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.pyindex 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.pyindex 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.pyindex 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.pyindex 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 rendererthat 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 candiff --git a/packages/core/src/repowise/core/persistence/crud/analysis/__init__.py b/packages/core/src/repowise/core/persistence/crud/analysis/__init__.pyindex 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.pyindex 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.pyindex 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.pyindex 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.pyindex 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 DocDriftAnalyzerdiff --git a/packages/core/src/repowise/core/workspace/update.py b/packages/core/src/repowise/core/workspace/update.pyindex 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 retrievaldiff --git a/tests/unit/persistence/test_doc_drift_crud.py b/tests/unit/persistence/test_doc_drift_crud.pyindex 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.pynew file mode 100644index 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