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): suggest replacements and gate documentation drift in CI (#2631)

Raghav Chamadiya771fad9b9764
diff --git a/docs/agent/MCP_TOOLS.md b/docs/agent/MCP_TOOLS.md
index 1f1b1745d..2f1c8da9e 100644
--- a/docs/agent/MCP_TOOLS.md
+++ b/docs/agent/MCP_TOOLS.md
@@ -1077,7 +1077,8 @@ The opt-in enrichments:
imputed zero).
- **`doc_drift`** returns a `doc_drift` block: `findings` (each naming the
**document** to edit, its line, the `target` it wrongly claims exists, a
- `reason` sentence, `kind`, `origin` and `confidence`), plus `findings_total`,
+ `reason` sentence, `kind`, `origin` and `confidence`, plus `suggestion` and
+ `suggestion_basis` only when a likely replacement was found), plus `findings_total`,
`documents` and the high/medium/low `confidence` split. Its `basis` field is
load-bearing: the detector checks only references it can resolve, most
references in a typical repository are uncheckable by design, and a finding is
diff --git a/docs/layers/DOC_DRIFT.md b/docs/layers/DOC_DRIFT.md
index a763cb862..4fcbf77af 100644
--- a/docs/layers/DOC_DRIFT.md
+++ b/docs/layers/DOC_DRIFT.md
@@ -40,8 +40,8 @@ Every finding carries the line as the document wrote it, the heading trail
locating the passage, and what the resolver checked. You should be able to
decide whether it is real without opening the file.
-Findings carry a confidence, and the default floor is 0.4. Raise it when you
-want only the near-certain ones:
+Findings carry a confidence, and the analysis stores everything at or above
+0.4. Raise the floor when you want only the near-certain ones:
```bash
repowise doc-drift # everything above the floor
@@ -53,6 +53,72 @@ Confidence is about resolution, not importance. A high-confidence finding is
one the analysis is sure it resolved correctly. Whether that broken link
matters is your call.
+### Likely replacements
+
+When the tree says where a reference probably went, the finding says so too:
+
+| Basis | When it fires |
+|---|---|
+| Became a package | `src/tools/cli.py` is gone and `src/tools/cli/` exists |
+| Renamed in git | git history records the file moving, and the new path exists |
+| Similar heading | the linked heading is gone and one declared heading is a close match |
+| Similar target | the `make` or `npm run` target is gone and one declared target is a close match |
+
+A suggestion is evidence for you to check, not an edit. It never changes a
+finding's confidence, and Repowise never rewrites your documents.
+
+A path that exists on disk but sits outside the index (a test fixture, an
+excluded directory) counts as uncheckable, not missing, so it is not reported.
+
+## Silencing a finding you mean to keep
+
+Some references are deliberate: an invented path in a tutorial, a link to a
+file generated at build time. Mark them in the document itself, so the
+decision travels with the text and every surface honours it:
+
+```markdown
+<!-- repowise-drift-ignore -->
+Create `src/plugins/my_plugin.py` with the following contents.
+```
+
+The marker silences references on its own line and the line after. Put
+`<!-- repowise-drift-ignore-file -->` anywhere in a document to silence all of
+it. Silenced references are counted in the report, never dropped quietly.
+
+## In CI
+
+`--check` reads the working tree directly. It needs git and nothing else: no
+index, no model, a few seconds on a large repository. It exits `1` when a
+finding at or above `--fail-on-confidence` (default 0.7) is present, and `2`
+when it cannot evaluate.
+
+```yaml
+# .github/workflows/docs.yml
+- uses: actions/checkout@v4
+ with:
+ fetch-depth: 0 # lets the rename suggestion read history
+- run: pip install repowise
+- run: repowise doc-drift --check --format github
+```
+
+`--format github` annotates each finding on the document line and writes a
+summary to the job page. `--format sarif` produces a file for GitHub code
+scanning; `--format markdown` is for posting a comment yourself.
+
+To adopt the gate on a repository that already has drift, record what is there
+and fail only on new findings:
+
+```bash
+repowise doc-drift --check --write-baseline .doc-drift-baseline.json
+git add .doc-drift-baseline.json
+# in CI:
+repowise doc-drift --check --baseline .doc-drift-baseline.json
+```
+
+Baseline entries are keyed on the document, the reference class and the target,
+not the line number, so editing a document above a known finding does not turn
+it back into a new one.
+
## The reverse view
The question "which documents talk about this file?" is worth asking before
@@ -69,18 +135,11 @@ or rename something and want to know what will go stale.
## Where it shows up
- `repowise doc-drift` for the report, with `--format json` for a script
+- `repowise doc-drift --check` for CI, with no index
- `get_health(include=["doc_drift"])` for an agent
- The Code Health tab in the dashboard
- Refreshed on every `update`, not only on a clean index
-## Known limitation
-
-A path that exists on disk but sits outside the index reports as though it were
-missing. The reason string says the path no longer exists when it means the
-path is not indexed. Excluded directories such as test fixtures are the common
-case. Check whether the path is in your index scope before acting on a `path`
-finding that looks wrong.
-
## See also
- [CODE_HEALTH.md](CODE_HEALTH.md) — the layer this belongs to
diff --git a/docs/reference/CLI_REFERENCE.md b/docs/reference/CLI_REFERENCE.md
index dda6cebbe..408f3958a 100644
--- a/docs/reference/CLI_REFERENCE.md
+++ b/docs/reference/CLI_REFERENCE.md
@@ -739,20 +739,31 @@ Show documentation this repository's own tree no longer satisfies: a path a
document names that no longer exists, a link pointing at a heading that was
renamed, a `make` target the manifest no longer declares.
-Reads what the last `init` or `update` stored rather than re-scanning, so it
-agrees with `get_health(include=["doc_drift"])` on the same tree.
+By default it reads what the last `init` or `update` stored instead of
+re-scanning, so it agrees with `get_health(include=["doc_drift"])` on the same
+tree. With `--check` it reads the working tree directly, needs no index,
+and exits non-zero when the gate fails: the mode for CI.
It checks only references it can resolve. Most references in a typical
repository are uncheckable by design and are neither counted nor reported, so a
clean run is not a claim that every sentence is true.
+Where the analysis can see a likely replacement, a finding carries it: a module
+that became a package, a file git recorded as renamed, a heading or build target
+with a close match. It is a suggestion to check, never applied.
+
**Options:**
| Flag | Description |
|------|-------------|
-| `--min-confidence` | Hide findings below this confidence (default: 0.4) |
+| `--min-confidence` | Hide findings below this confidence (default: show everything stored) |
| `--kind` | Only this reference class: `path`, `link`, `anchor`, `command`. Repeatable |
-| `--format` | Output: `table` (default), `json` |
+| `--document` | Only findings in this document. Repeatable |
+| `--check` | Read the working tree without an index and gate on the result |
+| `--fail-on-confidence` | With `--check`, fail on findings at or above this confidence (default: 0.7) |
+| `--baseline` | With `--check`, accept the findings recorded in this file; only new ones fail |
+| `--write-baseline` | With `--check`, record the current findings to this file and exit 0 |
+| `--format` | Output: `table` (default), `json`, `markdown`, `github`, `sarif` |
| `--repo` | In workspace mode, target a specific repo (defaults to primary) |
| `--no-workspace` | Force single-repo mode |
@@ -761,11 +772,22 @@ repowise doc-drift
repowise doc-drift --kind anchor # just the renamed-heading links
repowise doc-drift --min-confidence 0.9 # the near-certain ones
repowise doc-drift --format json
+
+repowise doc-drift --check # CI gate, no index needed
+repowise doc-drift --check --format github # annotations + step summary
+repowise doc-drift --check --format sarif > drift.sarif # code scanning upload
+repowise doc-drift --check --write-baseline .doc-drift-baseline.json
+repowise doc-drift --check --baseline .doc-drift-baseline.json
```
-Exits non-zero when there is no readable index, or when the index predates
-drift storage; in both cases `--format json` still emits a document naming the
-reason, rather than an empty finding list that would read as a clean tree.
+`github` prints workflow annotations and, when `$GITHUB_STEP_SUMMARY` is set,
+appends a markdown summary to it.
+
+Without `--check`, exits non-zero when there is no readable index, or when the
+index predates drift storage; in both cases `--format json` still emits a
+document naming the reason, not an empty finding list that would read as
+a clean tree. With `--check`, exit codes are `0` gate passed, `1` gate failed,
+`2` could not evaluate (not a git repository, unreadable baseline).
---
diff --git a/packages/cli/src/repowise/cli/commands/doc_drift_cmd.py b/packages/cli/src/repowise/cli/commands/doc_drift_cmd.py
index 733de45d1..277814d86 100644
--- a/packages/cli/src/repowise/cli/commands/doc_drift_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/doc_drift_cmd.py
@@ -1,41 +1,53 @@
"""``repowise doc-drift`` - assertions this repository's documents no longer satisfy.
-Reads the findings the drift pass persisted on the last ``init`` or ``update``
-rather than re-running the analyzer, and serializes them through the same
-function ``get_health(include=["doc_drift"])`` uses, so the two surfaces read
-the same rows the same way. They still differ where the caller asks them to:
-``--kind`` and ``--min-confidence`` narrow this one and not the other.
+By default it reads the findings the last ``init``/``update`` persisted, serialized
+through the same function ``get_health(include=["doc_drift"])`` uses. ``--check``
+runs the analyzer over the working tree with no index and gates on it (the CI mode).
"""
from __future__ import annotations
from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any, NoReturn
import click
+from repowise.cli.ci import (
+ CI_FORMATS,
+ EXIT_GATE_FAILED,
+ append_step_summary,
+ cannot_evaluate,
+ ci_notices,
+)
from repowise.cli.helpers import console, repo_index_session, resolve_command_target, run_async
-from repowise.cli.output import emit_json, emit_refusal, format_option, notice_console
+from repowise.cli.output import emit_json, emit_refusal, format_option
from repowise.core.analysis.doc_drift.constants import (
DETECTION_BASIS,
+ HIGH_CONFIDENCE_THRESHOLD,
bucket_confidences,
confidence_tier,
)
from repowise.core.analysis.doc_drift.models import DriftKind
+if TYPE_CHECKING:
+ from repowise.core.analysis.doc_drift.gate import GateResult
+ from repowise.core.analysis.doc_drift.models import DocDriftReport
+
#: Sentinels. Both are distinct from "no findings": an index that cannot be
#: read, and one written before the drift table existed. Reporting either as
#: zero drift would be the detector claiming a clean bill it never checked.
_NO_INDEX = object()
_STALE_INDEX = object()
+_FORMATS = (*CI_FORMATS, "sarif")
+
def _repo_path(path: str | None, repo_alias: str | None, no_workspace: bool, fmt: str) -> Path:
"""The repository to read. One repo: a drift finding belongs to one tree."""
target = resolve_command_target(
path=path, no_workspace_flag=no_workspace, repo_alias=repo_alias
)
- target.notice(notice_console(fmt), command="doc-drift")
+ target.notice(ci_notices(fmt), command="doc-drift")
return target.single_repo_path().resolve()
@@ -65,6 +77,31 @@ async def _read(root: Path, *, min_confidence: float | None, kinds: tuple[str, .
return [serialize_doc_drift_row(r) for r in rows]
+def _read_live(
+ root: Path,
+ *,
+ min_confidence: float | None,
+ kinds: tuple[str, ...],
+) -> tuple[Any, list[dict[str, Any]]]:
+ """Run the analyzer over the working tree: ``(report, finding dicts)``."""
+ from repowise.core.analysis.doc_drift.live import run_live
+ from repowise.core.analysis.doc_drift.serialize import serialize_finding
+
+ config = {"min_confidence": min_confidence} if min_confidence is not None else None
+ report = run_live(root, config=config)
+ findings = [serialize_finding(f) for f in report.findings]
+ if kinds:
+ findings = [f for f in findings if f["kind"] in kinds]
+ return report, findings
+
+
+def _only_documents(findings: list[dict[str, Any]], documents: tuple[str, ...]) -> list[dict]:
+ if not documents:
+ return findings
+ wanted = {d.replace("\\", "/").removeprefix("./") for d in documents}
+ return [f for f in findings if f["file_path"] in wanted]
+
+
def _payload(
root: Path, findings: list[dict[str, Any]], min_confidence: float | None
) -> dict[str, Any]:
@@ -116,12 +153,143 @@ def _render(payload: dict[str, Any]) -> None:
f"[{_TIER_COLOUR[confidence_tier(f['confidence'])]}]{f['confidence']:.2f}[/] "
f"{escape(f['kind'])} {escape(f['reason'])}"
)
- for line in f["evidence"]:
+ if f.get("suggestion"):
+ console.print(
+ f" [green]likely now: {escape(f['suggestion'])}[/green] "
+ f"[dim]({escape(f.get('suggestion_basis') or '')})[/dim]"
+ )
+ for line in f.get("evidence") or []:
console.print(f" [dim]{escape(line)}[/dim]")
console.print(f"\n[dim]{escape(DETECTION_BASIS)}[/dim]")
+def _emit(
+ fmt: str,
+ payload: dict[str, Any],
+ *,
+ gate: GateResult | None = None,
+ report: DocDriftReport | None = None,
+) -> None:
+ """Write *payload* in *fmt*; *gate* and *report* exist only under ``--check``."""
+ from repowise.core.analysis.doc_drift import render
+
+ findings = payload["findings"]
+ if fmt == "json":
+ emit_json(payload)
+ elif fmt == "sarif":
+ from repowise.cli import __version__
+
+ fail_on = gate.fail_on if gate is not None else HIGH_CONFIDENCE_THRESHOLD
+ emit_json(render.render_sarif(findings, tool_version=__version__, fail_on=fail_on))
+ elif fmt in ("markdown", "github"):
+ markdown = render.render_markdown(
+ findings,
+ gate=gate,
+ documents_scanned=report.documents_scanned if report is not None else None,
+ suppressed=report.suppressed if report is not None else 0,
+ )
+ if fmt == "markdown":
+ click.echo(markdown)
+ else:
+ for line in render.render_github_annotations(findings, gate=gate):
+ click.echo(line)
+ append_step_summary(markdown)
+ else:
+ _render(payload)
+ if gate is not None:
+ _print_verdict(gate)
+
+
+def _print_verdict(gate: GateResult) -> None:
+ if gate.passed:
+ console.print(f"[green]Gate passed[/green] [dim](fails at {gate.fail_on:.2f})[/dim]")
+ return
+ accepted = f", {len(gate.baselined)} accepted by baseline" if gate.baselined else ""
+ console.print(
+ f"[red]Gate failed:[/red] {len(gate.failing)} finding(s) at or above "
+ f"{gate.fail_on:.2f}{accepted}"
+ )
+
+
+def _refuse(code: str, message: str, fmt: str, *, remedy: str, repo: str) -> NoReturn:
+ """Refuse and exit 1; machine formats other than json keep stdout empty."""
+ if fmt in ("json", "table"):
+ emit_refusal(code, message, fmt, remedy=remedy, repo=repo)
+ from rich.markup import escape
+
+ notices = ci_notices(fmt)
+ notices.print(f"[red]{escape(message)}[/red]")
+ notices.print(f"[dim]{escape(remedy)}[/dim]")
+ raise click.exceptions.Exit(1)
+
+
+def _run_check(
+ root: Path,
+ fmt: str,
+ *,
+ min_confidence: float | None,
+ kinds: tuple[str, ...],
+ documents: tuple[str, ...],
+ fail_on: float,
+ baseline_path: Path | None,
+ write_baseline_path: Path | None,
+) -> None:
+ from repowise.cli.helpers import silence_logs_for_machine_output
+ from repowise.core.analysis.doc_drift.baseline import (
+ BaselineError,
+ read_baseline,
+ write_baseline,
+ )
+ from repowise.core.analysis.doc_drift.gate import evaluate_gate
+ from repowise.core.analysis.doc_drift.live import LiveTreeError
+
+ # The analyzer's debug line would land in the report a CI log shows.
+ silence_logs_for_machine_output()
+ if min_confidence is not None and min_confidence > fail_on:
+ ci_notices(fmt).print(
+ f"[yellow]--min-confidence {min_confidence:.2f} is above --fail-on-confidence "
+ f"{fail_on:.2f}; findings between them are hidden from the gate.[/yellow]"
+ )
+ try:
+ report, findings = _read_live(root, min_confidence=min_confidence, kinds=kinds)
+ except LiveTreeError as exc:
+ cannot_evaluate(fmt, "not_a_git_repository", str(exc))
+ findings = _only_documents(findings, documents)
+
+ if write_baseline_path is not None:
+ try:
+ written = write_baseline(write_baseline_path, findings)
+ except OSError as exc:
+ cannot_evaluate(
+ fmt, "baseline_unwritable", f"cannot write baseline {write_baseline_path}: {exc}"
+ )
+ ci_notices(fmt).print(
+ f"Recorded {len(findings)} finding(s) as {written} baseline entr"
+ f"{'y' if written == 1 else 'ies'} in {write_baseline_path}."
+ )
+ return
+
+ baseline = None
+ if baseline_path is not None:
+ try:
+ baseline = read_baseline(baseline_path)
+ except BaselineError as exc:
+ cannot_evaluate(fmt, "baseline_unreadable", str(exc))
+
+ gate = evaluate_gate(findings, fail_on=fail_on, baseline=baseline)
+ payload = _payload(root, findings, min_confidence)
+ payload.update(
+ documents_scanned=report.documents_scanned,
+ references_checked=report.references_checked,
+ suppressed=report.suppressed,
+ gate=gate.to_dict(),
+ )
+ _emit(fmt, payload, gate=gate, report=report)
+ if not gate.passed:
+ raise click.exceptions.Exit(EXIT_GATE_FAILED)
+
+
@click.command("doc-drift")
@click.argument("path", required=False, default=None)
@click.option(
@@ -141,42 +309,93 @@ def _render(payload: dict[str, Any]) -> None:
type=click.Choice([k.value for k in DriftKind]),
help="Only this reference class. Repeatable.",
)
+ "--document",
+ "documents",
+ multiple=True,
+ help="Only findings in this document (repo-relative). Repeatable.",
+)
+ "--check",
+ is_flag=True,
+ default=False,
+ help="Read the working tree without an index and exit 1 when the gate fails.",
+)
+ "--fail-on-confidence",
+ type=click.FloatRange(0.0, 1.0),
+ default=HIGH_CONFIDENCE_THRESHOLD,
+ show_default=True,
+ help="With --check, fail on findings at or above this confidence.",
+)
+ "--baseline",
+ "baseline_path",
+ type=click.Path(dir_okay=False, path_type=Path),
+ default=None,
+ help="With --check, accept findings recorded in this file; only new ones fail.",
+)
+ "--write-baseline",
+ "write_baseline_path",
+ type=click.Path(dir_okay=False, path_type=Path),
+ default=None,
+ help="With --check, record the current findings to this file and exit 0.",
+)
@click.option("--repo", "repo_alias", default=None, help="In workspace mode, target one repo.")
@click.option("--no-workspace", is_flag=True, default=False, help="Force single-repo mode.")
-@format_option()
+@format_option(
+ choices=_FORMATS,
+ help="Output format. 'github' prints annotations and fills the job summary.",
+)
def doc_drift_command(
path: str | None,
min_confidence: float | None,
kinds: tuple[str, ...],
+ documents: tuple[str, ...],
+ check: bool,
+ fail_on_confidence: float,
+ baseline_path: Path | None,
+ write_baseline_path: Path | None,
repo_alias: str | None,
no_workspace: bool,
fmt: str,
) -> None:
"""Show documentation that the repository no longer matches."""
+ if not check and (baseline_path or write_baseline_path):
+ raise click.UsageError("--baseline and --write-baseline require --check.")
root = _repo_path(path, repo_alias, no_workspace, fmt)
+
+ if check:
+ _run_check(
+ root,
+ fmt,
+ min_confidence=min_confidence,
+ kinds=kinds,
+ documents=documents,
+ fail_on=fail_on_confidence,
+ baseline_path=baseline_path,
+ write_baseline_path=write_baseline_path,
+ )
+ return
+
result = run_async(_read(root, min_confidence=min_confidence, kinds=kinds))
if result is _NO_INDEX:
- emit_refusal(
+ _refuse(
"no_index",
f"No readable Repowise index at {root}.",
fmt,
- remedy="Run 'repowise init' there first.",
+ remedy="Run 'repowise init' there first, or use --check to read the tree directly.",
repo=str(root),
)
- return
if result is _STALE_INDEX:
- emit_refusal(
+ _refuse(
"index_predates_doc_drift",
f"The index at {root} was written before drift findings were stored.",
fmt,
remedy="Run 'repowise update' there to populate them.",
repo=str(root),
)
- return
- payload = _payload(root, result, min_confidence)
- if fmt == "json":
- emit_json(payload)
- return
- _render(payload)
+ _emit(fmt, _payload(root, _only_documents(result, documents), min_confidence))
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 89d3d0ea2..0fc4d706a 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/command.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/command.py
@@ -1493,7 +1493,9 @@ 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)
+ doc_drift_report = _run_doc_drift_partial(
+ graph_builder, source_map, repo_path=repo_path, timings=timings
+ )
# Partial health has consumed the per-file ``BlameIndex``; drop it before
# the metadata reaches persistence / regeneration so the transient,
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 8b3f057a3..bf3631f04 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/incremental.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/incremental.py
@@ -255,11 +255,12 @@ def _run_doc_drift_partial(
graph_builder: Any,
source_map: dict[str, bytes] | None,
*,
+ repo_path: Any | None = 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
+ graph_builder, source_map, repo_path=repo_path, log=console.print, timings=timings
)
diff --git a/packages/core/alembic/versions/0078_doc_drift_suggestions.py b/packages/core/alembic/versions/0078_doc_drift_suggestions.py
new file mode 100644
index 000000000..cf0e8d6b4
--- /dev/null
+++ b/packages/core/alembic/versions/0078_doc_drift_suggestions.py
@@ -0,0 +1,56 @@
+"""doc_drift_findings: store the likely replacement for a missing target.
+
+``suggestion`` is the path, anchor or target the finding's reference probably
+means now, and ``suggestion_basis`` names the evidence (a package split, a git
+rename, a similar heading or target). Both are null when nothing was found; a
+suggestion never changes a finding's verdict or confidence.
+
+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: 0078
+Revises: 0077
+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 = "0078"
+down_revision: str | None = "0077"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def _columns() -> set[str]:
+ inspector = sa.inspect(op.get_bind())
+ return {c["name"] for c in inspector.get_columns("doc_drift_findings")}
+
+
+def upgrade() -> None:
+ # Guarded: ``init_db``'s reconciler may already have added these on Postgres.
+ existing = _columns()
+ if "suggestion" not in existing:
+ op.add_column(
+ "doc_drift_findings",
+ sa.Column("suggestion", sa.String(length=1024), nullable=True),
+ )
+ if "suggestion_basis" not in existing:
+ op.add_column(
+ "doc_drift_findings",
+ sa.Column("suggestion_basis", sa.String(length=32), nullable=True),
+ )
+
+
+def downgrade() -> None:
+ existing = _columns()
+ if "suggestion_basis" in existing:
+ op.drop_column("doc_drift_findings", "suggestion_basis")
+ if "suggestion" in existing:
+ op.drop_column("doc_drift_findings", "suggestion")
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 81597ea63..53f29f8ec 100644
--- a/packages/core/src/repowise/core/analysis/doc_drift/analyzer.py
+++ b/packages/core/src/repowise/core/analysis/doc_drift/analyzer.py
@@ -11,17 +11,22 @@ a synchronous class taking its inputs at construction and exposing
from __future__ import annotations
+import os
+from collections.abc import Callable
from datetime import UTC, datetime
+from functools import partial
+from pathlib import Path
from typing import Any
import structlog
from .constants import (
DEFAULT_MIN_CONFIDENCE,
+ MANIFEST_NAMES,
MAX_DOC_BYTES,
bucket_confidences,
)
-from .extractor import extract, is_checkable_document, is_guide_document
+from .extractor import extract_with_suppressed, is_checkable_document, is_guide_document
from .models import (
DocDriftFindingData,
DocDriftReport,
@@ -29,12 +34,11 @@ from .models import (
DriftVerdict,
ResolvedDocReference,
)
-from .resolver import RepoIndex, resolve
+from .resolver import RepoIndex, Resolution, resolve
+from .suggest import RenameLookup, Suggestion, git_renames, suggest_all
logger = structlog.get_logger(__name__)
-_MANIFEST_NAMES = frozenset({"Makefile", "makefile", "GNUmakefile", "package.json"})
-
_REASONS: dict[str, str] = {
"path_no_candidate": "Document names {target}, which no longer exists.",
"path_no_candidate_in_guide": (
@@ -54,6 +58,11 @@ class DocDriftAnalyzer:
repo_id: str = "",
source_map: dict[str, bytes] | None = None,
tracked_paths: set[str] | frozenset[str] | None = None,
+ *,
+ repo_root: Path | None = None,
+ rename_lookup: RenameLookup | None = None,
+ on_disk: Callable[[str], bool] | None = None,
+ opaque_dirs: frozenset[str] | None = None,
) -> None:
"""
Args:
@@ -70,10 +79,25 @@ class DocDriftAnalyzer:
``source_map`` keys, which are already gitignore-filtered by
the traverser (and also honour ``.repowiseIgnore`` and
per-directory ignores, which a bare gitignore spec does not).
+ repo_root: the working tree, when there is one. Defaults
+ ``on_disk`` to a case-exact filesystem probe and
+ ``rename_lookup`` to :func:`~.suggest.git_renames`.
+ rename_lookup: old path -> new path, called once per run for
+ suggestions. ``None`` (and no root) skips rename suggestions.
+ on_disk: whether a repo-relative path exists in the working tree;
+ see :attr:`~.resolver.RepoIndex.on_disk`.
+ opaque_dirs: directories the tree cannot list (submodules); see
+ :attr:`~.resolver.RepoIndex.opaque_dirs`.
"""
self._repo_id = repo_id
self._source_map = source_map or {}
self._tracked = frozenset(tracked_paths or self._source_map.keys())
+ self._repo_root = Path(repo_root) if repo_root is not None else None
+ if self._repo_root is not None:
+ rename_lookup = rename_lookup or partial(git_renames, self._repo_root)
+ self._on_disk = on_disk
+ self._rename_lookup = rename_lookup
+ self._opaque_dirs = opaque_dirs
# -- input preparation ------------------------------------------------
@@ -103,7 +127,7 @@ class DocDriftAnalyzer:
def _manifests(self) -> dict[str, str]:
out: dict[str, str] = {}
for rel in self._source_map:
- if rel.rsplit("/", 1)[-1] not in _MANIFEST_NAMES:
+ if rel.rsplit("/", 1)[-1] not in MANIFEST_NAMES:
continue
text = self._decode(rel)
if text is not None:
@@ -132,29 +156,37 @@ class DocDriftAnalyzer:
if on_step:
on_step("collect")
+ on_disk = self._on_disk
+ if on_disk is None and self._repo_root is not None:
+ on_disk = _exact_probe(self._repo_root)
index = RepoIndex.build(
tracked_paths=self._tracked,
doc_text=documents,
manifest_text=self._manifests(),
+ on_disk=on_disk,
+ opaque_dirs=self._opaque_dirs,
)
if on_step:
on_step("index")
- findings: list[DocDriftFindingData] = []
+ misses: list[Resolution] = []
resolved: list[ResolvedDocReference] = []
verdict_counts: dict[str, int] = {v.value: 0 for v in DriftVerdict}
references_checked = 0
+ suppressed = 0
for rel, text in documents.items():
is_guide = is_guide_document(rel)
- for ref in extract(text, rel):
+ refs, silenced = extract_with_suppressed(text, rel)
+ suppressed += sum(1 for ref in silenced if ref.kind in enabled)
+ for ref in refs:
if ref.kind not in enabled:
continue
references_checked += 1
res = resolve(index, ref, is_guide=is_guide)
verdict_counts[res.verdict.value] += 1
if res.verdict is DriftVerdict.MISSING:
- findings.append(_to_finding(res))
+ misses.append(res)
elif res.resolved_target and res.resolved_target != rel:
# Retention, not recomputation. Only a resolution naming
# a real file sets ``resolved_target``, so an ambiguous or
@@ -167,8 +199,17 @@ class DocDriftAnalyzer:
on_step("resolve")
min_conf = float(cfg.get("min_confidence", DEFAULT_MIN_CONFIDENCE))
- hidden = sum(1 for f in findings if f.confidence < min_conf)
- findings = [f for f in findings if f.confidence >= min_conf]
+ shown = [res for res in misses if res.confidence >= min_conf]
+ hidden = len(misses) - len(shown)
+ # Suggestions only for findings a reader will see: the rename lookup is
+ # a git call.
+ suggestions = suggest_all(
+ shown, index, rename_lookup=self._rename_lookup, on_disk=on_disk
+ )
+ findings = [
+ _to_finding(res, suggestion)
+ for res, suggestion in zip(shown, suggestions, strict=True)
+ ]
findings.sort(key=lambda f: (-f.confidence, f.file_path, f.line_number))
logger.debug(
@@ -190,6 +231,7 @@ class DocDriftAnalyzer:
verdict_summary=verdict_counts,
anchor_renderer=index.renderers.summary(),
hidden_below_threshold=hidden,
+ suppressed=suppressed,
documents=frozenset(documents),
resolved_references=resolved,
)
@@ -206,7 +248,38 @@ def _to_resolved(res: Any) -> ResolvedDocReference:
)
-def _to_finding(res: Any) -> DocDriftFindingData:
+def _exact_probe(root: Path) -> Callable[[str], bool]:
+ """Whether a path exists beneath *root* with exactly this spelling.
+
+ Case-exact on every filesystem, so a document that differs from the tree
+ only in case is drift locally as it is on Linux CI. Paths that climb out
+ are refused. Listings are cached for the life of the probe (one run).
+ """
+ listings: dict[Path, frozenset[str]] = {}
+
+ def probe(rel: str) -> bool:
+ if not rel or rel.startswith("/") or ".." in rel.split("/"):
+ return False
+ parent = root
+ for name in rel.split("/"):
+ if name in ("", "."):
+ continue
+ names = listings.get(parent)
+ if names is None:
+ try:
+ names = frozenset(os.listdir(parent))
+ except (OSError, ValueError):
+ names = frozenset()
+ listings[parent] = names
+ if name not in names:
+ return False
+ parent = parent / name
+ return True
+
+ return probe
+
+
+def _to_finding(res: Resolution, suggestion: Suggestion = ("", "")) -> DocDriftFindingData:
ref = res.ref
target, _, fragment = ref.target.partition("#")
reason = _REASONS[res.origin].format(
@@ -232,6 +305,8 @@ def _to_finding(res: Any) -> DocDriftFindingData:
evidence=evidence,
raw=ref.raw,
context=ref.context[:300],
+ suggestion=suggestion[0],
+ suggestion_basis=suggestion[1],
)
diff --git a/packages/core/src/repowise/core/analysis/doc_drift/baseline.py b/packages/core/src/repowise/core/analysis/doc_drift/baseline.py
new file mode 100644
index 000000000..0e4d06710
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/doc_drift/baseline.py
@@ -0,0 +1,88 @@
+"""A committed file of accepted documentation drift.
+
+The baseline lets a repository adopt the gate without first fixing every
+existing finding: what it lists does not fail, anything new does. It is a file
+path the caller names, never ``.repowise/config.yaml``, because that config is
+local state and a CI policy has to live in the repository.
+
+Entries are keyed on the line-independent fingerprint and sorted, and the bytes
+are deterministic, so rewriting an unchanged baseline is a no-op diff.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable, Mapping
+from pathlib import Path
+from typing import Any
+
+from .serialize import fingerprint_of
+
+BASELINE_VERSION = 1
+
+BASELINE_BASIS = (
+ "Documentation drift accepted as known. A listed finding does not fail the "
+ "gate; it is keyed on document, kind and target, not line."
+)
+
+
+class BaselineError(ValueError):
+ """A baseline file that cannot be used; the message says why."""
+
+
+def build_baseline(findings: Iterable[Mapping[str, Any]]) -> dict:
+ """The baseline document for *findings*, one entry per fingerprint."""
+ entries: dict[str, dict] = {}
+ for finding in findings:
+ fp = fingerprint_of(finding)
+ entries.setdefault(
+ fp,
+ {
+ "fingerprint": fp,
+ "file_path": finding["file_path"],
+ "kind": str(finding["kind"]),
+ "target": finding["target"],
+ },
+ )
+ ordered = sorted(
+ entries.values(), key=lambda e: (e["file_path"], e["kind"], e["target"])
+ )
+ return {"version": BASELINE_VERSION, "basis": BASELINE_BASIS, "entries": ordered}
+
+
+def write_baseline(path: Path | str, findings: Iterable[Mapping[str, Any]]) -> int:
+ """Write the baseline for *findings* to *path*; returns entries written."""
+ doc = build_baseline(findings)
+ text = json.dumps(doc, indent=2, ensure_ascii=False) + "\n"
+ Path(path).write_text(text, encoding="utf-8")
+ return len(doc["entries"])
+
+
+def read_baseline(path: Path | str) -> frozenset[str]:
+ """The fingerprints *path* accepts; raises :class:`BaselineError` if unusable."""
+ try:
+ text = Path(path).read_text(encoding="utf-8")
+ except (OSError, UnicodeDecodeError) as exc:
+ raise BaselineError(f"cannot read baseline {path}: {exc}") from exc
+ try:
+ doc = json.loads(text)
+ except json.JSONDecodeError as exc:
+ raise BaselineError(f"baseline {path} is not valid JSON: {exc}") from exc
+ if not isinstance(doc, dict):
+ raise BaselineError(f"baseline {path} must be a JSON object")
+ version = doc.get("version")
+ if version != BASELINE_VERSION:
+ raise BaselineError(
+ f"baseline {path} has version {version!r}; this build reads "
+ f"version {BASELINE_VERSION}"
+ )
+ entries = doc.get("entries")
+ if not isinstance(entries, list):
+ raise BaselineError(f"baseline {path} has no 'entries' list")
+ out: set[str] = set()
+ for i, entry in enumerate(entries):
+ fp = entry.get("fingerprint") if isinstance(entry, dict) else None
+ if not isinstance(fp, str) or not fp:
+ raise BaselineError(f"baseline {path} entry {i} has no fingerprint")
+ out.add(fp)
+ return frozenset(out)
diff --git a/packages/core/src/repowise/core/analysis/doc_drift/constants.py b/packages/core/src/repowise/core/analysis/doc_drift/constants.py
index 87929c328..573c82297 100644
--- a/packages/core/src/repowise/core/analysis/doc_drift/constants.py
+++ b/packages/core/src/repowise/core/analysis/doc_drift/constants.py
@@ -147,6 +147,17 @@ ORIGIN_CONFIDENCE: dict[str, float] = {
#: Every origin in the ``DriftOrigin`` vocabulary, for parity checks.
DRIFT_ORIGIN_VALUES: frozenset[str] = frozenset(get_args(DriftOrigin))
+#: How a finding's suggested replacement was found. A suggestion is evidence,
+#: never a verdict: it does not move a finding's confidence.
+SuggestionBasis = Literal[
+ "package_split",
+ "git_rename",
+ "similar_heading",
+ "similar_target",
+]
+
+SUGGESTION_BASIS_VALUES: frozenset[str] = frozenset(get_args(SuggestionBasis))
+
# ---------------------------------------------------------------------------
# Document selection
@@ -206,6 +217,9 @@ GUIDE_STEM_RE = re.compile(
re.I,
)
+#: Basenames the analyzer reads command targets from.
+MANIFEST_NAMES: frozenset[str] = frozenset({"Makefile", "makefile", "GNUmakefile", "package.json"})
+
#: Ceiling for a single document, mirroring the 500KB ``max_file_size_kb``
#: that already applies to non-AST files. A document larger than this is not
#: prose anyone maintains.
diff --git a/packages/core/src/repowise/core/analysis/doc_drift/extractor.py b/packages/core/src/repowise/core/analysis/doc_drift/extractor.py
index 741eabd22..d38380bbd 100644
--- a/packages/core/src/repowise/core/analysis/doc_drift/extractor.py
+++ b/packages/core/src/repowise/core/analysis/doc_drift/extractor.py
@@ -342,12 +342,44 @@ def _from_commands(line: str, lineno: int, doc: str) -> Iterator[DocReference]:
_EXTRACTORS = (_from_links, _from_inline_code, _from_commands)
+# Inline suppression. Lives in the document, not config, because config
+# is local state, and a CI check has to agree with the author's machine.
+_IGNORE_RE = re.compile(r"<!--\s*repowise-drift-ignore(-file)?\s*-->")
+# A marker quoted in a code span is being documented, not applied.
+_CODE_SPAN_RE = re.compile(r"(`+).+?\1")
+
+
def extract(text: str, doc_path: str) -> list[DocReference]:
- """Every checkable assertion *text* makes, deduplicated, in document order."""
+ """Every checkable assertion *text* makes, deduplicated, in document order.
+
+ References silenced by a ``repowise-drift-ignore`` marker are left out; use
+ :func:`extract_with_suppressed` to count them.
+ """
+ return extract_with_suppressed(text, doc_path)[0]
+
+
+def extract_with_suppressed(
+ text: str, doc_path: str
+) -> tuple[list[DocReference], list[DocReference]]:
+ """``(references, suppressed)`` for *text*, both deduplicated, in order.
+
+ ``<!-- repowise-drift-ignore -->`` silences its own line and the next one;
+ ``<!-- repowise-drift-ignore-file -->`` silences the whole document. Both
+ count only in prose, so a fenced or backticked example does nothing.
+ """
seen: set[DocReference] = set()
out: list[DocReference] = []
+ suppressed: list[DocReference] = []
+ ignore_file = False
+ ignored_lines: set[int] = set()
trail = _SectionTrail()
for lineno, line in prose_lines(text):
+ marker = "<!--" in line and _IGNORE_RE.search(_CODE_SPAN_RE.sub("", line))
+ if marker:
+ if marker.group(1):
+ ignore_file = True
+ else:
+ ignored_lines.update((lineno, lineno + 1))
# A heading updates the trail AND is still scanned: a section title
# like "### 7.1 GitIndexer (`packages/core/ingestion/git_indexer.py`)"
# asserts a path exactly as body prose does, and skipping headings
@@ -360,10 +392,10 @@ def extract(text: str, doc_path: str) -> list[DocReference]:
if ref in seen:
continue
seen.add(ref)
- out.append(ref)
- return out
-
-
+ (suppressed if lineno in ignored_lines else out).append(ref)
+ if ignore_file:
+ return [], sorted(out + suppressed, key=lambda ref: ref.line)
+ return out, suppressed
# ---------------------------------------------------------------------------
diff --git a/packages/core/src/repowise/core/analysis/doc_drift/gate.py b/packages/core/src/repowise/core/analysis/doc_drift/gate.py
new file mode 100644
index 000000000..a710e9551
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/doc_drift/gate.py
@@ -0,0 +1,70 @@
+"""The CI verdict over documentation drift findings.
+
+A pure function over finding dicts (the :func:`~.serialize.serialize_finding`
+shape), so the CLI, the hosted platform and the PR bot reach the same verdict
+from the same findings without sharing anything but this module.
+
+A finding fails the gate when its confidence is at or above ``fail_on`` and its
+fingerprint is not in the baseline. The fingerprint leaves out the line number,
+so an accepted finding stays accepted when an edit above it shifts its line.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from .constants import HIGH_CONFIDENCE_THRESHOLD
+from .serialize import fingerprint_of
+
+
+@dataclass(frozen=True)
+class GateResult:
+ """What the gate decided, and which findings it decided on."""
+
+ passed: bool
+ #: At or above ``fail_on`` and not baselined, each with a ``fingerprint``.
+ failing: list[dict] = field(default_factory=list)
+ #: At or above ``fail_on`` but accepted by the baseline.
+ baselined: list[dict] = field(default_factory=list)
+ below_threshold: int = 0
+ fail_on: float = HIGH_CONFIDENCE_THRESHOLD
+
+ def to_dict(self) -> dict:
+ """A stable JSON shape: the verdict, its counts, the failing findings."""
+ return {
+ "passed": self.passed,
+ "fail_on": round(float(self.fail_on), 2),
+ "failing_count": len(self.failing),
+ "baselined_count": len(self.baselined),
+ "below_threshold_count": self.below_threshold,
+ "failing": [dict(f) for f in self.failing],
+ }
+
+
+def evaluate_gate(
+ findings: Iterable[Mapping[str, Any]],
+ *,
+ fail_on: float = HIGH_CONFIDENCE_THRESHOLD,
+ baseline: frozenset[str] | None = None,
+) -> GateResult:
+ """Split *findings* into failing, baselined and below-threshold."""
+ accepted = baseline or frozenset()
+ failing: list[dict] = []
+ baselined: list[dict] = []
+ below = 0
+ for finding in findings:
+ if float(finding["confidence"]) < fail_on:
+ below += 1
+ continue
+ row = dict(finding)
+ row["fingerprint"] = fingerprint_of(finding)
+ (baselined if row["fingerprint"] in accepted else failing).append(row)
+ return GateResult(
+ passed=not failing,
+ failing=failing,
+ baselined=baselined,
+ below_threshold=below,
+ fail_on=float(fail_on),
+ )
diff --git a/packages/core/src/repowise/core/analysis/doc_drift/live.py b/packages/core/src/repowise/core/analysis/doc_drift/live.py
new file mode 100644
index 000000000..ea9cd4391
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/doc_drift/live.py
@@ -0,0 +1,144 @@
+"""Index-free drift inputs for CI: the working tree, read in seconds.
+
+A CI job has a checkout and no ``.repowise`` index, so this builds the
+analyzer's inputs straight from the tree, reading only checkable markdown and
+the command manifests.
+
+A root ``.repowiseIgnore`` narrows which documents are scanned, as it does for
+an indexed run. It does not remove paths from the tracked set: an ignored file
+still exists, and a document naming it is not drift.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from repowise.core.ingestion.traverser import REPOWISE_IGNORE_FILENAME, load_extra_ignore_spec
+
+from .analyzer import DocDriftAnalyzer
+from .constants import MANIFEST_NAMES, MAX_DOC_BYTES
+from .extractor import is_checkable_document
+from .models import DocDriftReport
+
+_GIT_TIMEOUT_SECONDS = 60
+_GITLINK_MODE = "160000"
+
+
+class LiveTreeError(RuntimeError):
+ """The working tree could not be listed (git missing, or not a repository)."""
+
+
+@dataclass(frozen=True)
+class LiveInputs:
+ """What :class:`~.analyzer.DocDriftAnalyzer` needs, read from the tree."""
+
+ source_map: dict[str, bytes]
+ tracked_paths: frozenset[str]
+ root: Path
+ """The repository toplevel every path above is relative to."""
+ opaque_dirs: frozenset[str] = frozenset()
+ """Submodule paths, whose contents the superproject cannot list."""
+
+
+def _git(root: Path, *args: str) -> bytes:
+ """stdout of one git call; :class:`LiveTreeError` on any failure."""
+ try:
+ proc = subprocess.run(
+ ["git", "-C", str(root), *args],
+ capture_output=True,
+ stdin=subprocess.DEVNULL,
+ timeout=_GIT_TIMEOUT_SECONDS,
+ check=False,
+ )
+ except OSError as exc:
+ raise LiveTreeError(f"git is not available: {exc}") from exc
+ except subprocess.TimeoutExpired as exc:
+ raise LiveTreeError(f"git {args[0]} timed out in {root}") from exc
+ if proc.returncode != 0:
+ detail = proc.stderr.decode("utf-8", errors="replace").strip()
+ raise LiveTreeError(f"{root} is not a git working tree: {detail}")
+ return proc.stdout
+
+
+def _toplevel(root: Path) -> Path:
+ out = _git(root, "rev-parse", "--show-toplevel").decode("utf-8", errors="replace")
+ return Path(out.strip())
+
+
+def _list_paths(root: Path) -> frozenset[str]:
+ """Paths present in the working tree, from one ``git ls-files`` call.
+
+ Not the shared tracked-files helper: this needs ``--others --deleted -t``.
+ """
+ flags = ["-z", "-t", "--cached", "--deleted", "--others", "--exclude-standard"]
+ out = _git(root, "ls-files", *flags)
+ present: set[str] = set()
+ deleted: set[str] = set()
+ for entry in out.decode("utf-8", errors="replace").split("\0"):
+ if not entry:
+ continue
+ # ``-t`` prefixes a status tag; ``R`` is a tracked file removed on disk.
+ tag, _, path = entry.partition(" ")
+ (deleted if tag == "R" else present).add(path)
+ return frozenset(present - deleted)
+
+
+def _gitlinks(root: Path) -> frozenset[str]:
+ """Submodule paths (gitlink mode), initialized or not."""
+ found: set[str] = set()
+ for entry in _git(root, "ls-files", "-s", "-z").decode("utf-8", errors="replace").split("\0"):
+ meta, _, path = entry.partition("\t")
+ if path and meta.startswith(_GITLINK_MODE + " "):
+ found.add(path)
+ return frozenset(found)
+
+
+def _read_capped(path: Path) -> bytes | None:
+ try:
+ if path.stat().st_size > MAX_DOC_BYTES:
+ return None
+ return path.read_bytes()
+ except OSError:
+ return None
+
+
+def collect_live_inputs(root: Path) -> LiveInputs:
+ """Build the analyzer's inputs from the working tree containing *root*.
+
+ Paths are relative to the repository toplevel even when *root* is a
+ subdirectory, so findings name the files CI annotates.
+ """
+ top = _toplevel(Path(root))
+ tracked = _list_paths(top)
+ ignore = load_extra_ignore_spec(top, REPOWISE_IGNORE_FILENAME)
+ source_map: dict[str, bytes] = {}
+ for rel in sorted(tracked):
+ if rel.rsplit("/", 1)[-1] in MANIFEST_NAMES:
+ wanted = True
+ else:
+ wanted = is_checkable_document(rel) and not ignore.match_file(rel)
+ if not wanted:
+ continue
+ data = _read_capped(top / rel)
+ if data is not None:
+ source_map[rel] = data
+ return LiveInputs(
+ source_map=source_map,
+ tracked_paths=tracked,
+ root=top,
+ opaque_dirs=_gitlinks(top),
+ )
+
+
+def run_live(root: Path, *, config: dict | None = None) -> DocDriftReport:
+ """Run the drift pass over the working tree containing *root*, no index needed."""
+ inputs = collect_live_inputs(Path(root))
+ analyzer = DocDriftAnalyzer(
+ source_map=inputs.source_map,
+ tracked_paths=inputs.tracked_paths,
+ repo_root=inputs.root,
+ opaque_dirs=inputs.opaque_dirs,
+ )
+ return analyzer.analyze(config)
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 709ca4ecc..129b8ebef 100644
--- a/packages/core/src/repowise/core/analysis/doc_drift/models.py
+++ b/packages/core/src/repowise/core/analysis/doc_drift/models.py
@@ -102,6 +102,11 @@ class DocDriftFindingData:
"""Lines a reader can check for themselves."""
raw: str = ""
context: str = ""
+ suggestion: str = ""
+ """A likely replacement for ``target``, or empty. Evidence for the reader,
+ never applied: this detector does not rewrite documents."""
+ suggestion_basis: str = ""
+ """How ``suggestion`` was found, from :data:`~.constants.SuggestionBasis`."""
@dataclass(frozen=True)
@@ -151,6 +156,9 @@ 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
+ suppressed: int = 0
+ """References an inline ``repowise-drift-ignore`` marker silenced. Counted
+ so a suppression is visible and never mistaken for a clean doc."""
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
diff --git a/packages/core/src/repowise/core/analysis/doc_drift/render.py b/packages/core/src/repowise/core/analysis/doc_drift/render.py
new file mode 100644
index 000000000..197d67c14
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/doc_drift/render.py
@@ -0,0 +1,243 @@
+"""CI renderings of documentation drift: markdown, GitHub annotations, SARIF.
+
+Pure functions over finding dicts and a :class:`~.gate.GateResult`, so the CLI,
+the hosted platform and the PR bot print the same thing. Two honesty rules hold
+in every format: the document is named as the thing to edit (a finding is about
+the prose, not the target it names), and the markdown and SARIF carry
+:data:`~.constants.DETECTION_BASIS`, because a clean result from this detector
+covers only the references it can resolve. Workflow-command escaping and the
+annotation cap come from :mod:`repowise.core.ci.github`, and table cells, plurals
+and the row cap from :mod:`repowise.core.ci.markdown`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from repowise.core.ci import github, sarif
+from repowise.core.ci.markdown import ROW_LIMIT, cell, more_line, plural
+
+from .constants import DETECTION_BASIS, HIGH_CONFIDENCE_THRESHOLD
+from .gate import GateResult
+from .models import DriftKind
+from .serialize import fingerprint_of
+
+SARIF_TOOL_NAME = "repowise-doc-drift"
+SARIF_FINGERPRINT_KEY = "repowiseDocDrift/v1"
+
+_RULE_TEXT: dict[DriftKind, tuple[str, str]] = {
+ DriftKind.PATH: (
+ "Document names a file path that does not exist",
+ "A repository path written in a document resolves to no file in the tree.",
+ ),
+ DriftKind.LINK: (
+ "Document links to a file that does not exist",
+ "A relative markdown link in a document resolves to no file in the tree.",
+ ),
+ DriftKind.ANCHOR: (
+ "Document links to a heading that does not exist",
+ "A link fragment names a heading the target document no longer declares.",
+ ),
+ DriftKind.COMMAND: (
+ "Document shows a command target that is not declared",
+ "A make or npm run target shown in a document is not declared by the manifest.",
+ ),
+}
+
+
+def _order(findings: Sequence[Mapping[str, Any]]) -> list[Mapping[str, Any]]:
+ return sorted(
+ findings,
+ key=lambda f: (f["file_path"], int(f["line_number"]), str(f["kind"]), f["target"]),
+ )
+
+
+def _likely(finding: Mapping[str, Any]) -> str:
+ return (finding.get("suggestion") or "").strip()
+
+
+def _message(finding: Mapping[str, Any]) -> str:
+ """The finding's reason, plus the likely replacement when one was found."""
+ likely = _likely(finding)
+ reason = str(finding["reason"])
+ return f"{reason} Likely now: {likely}." if likely else reason
+
+
+# ---------------------------------------------------------------------------
+# Markdown
+# ---------------------------------------------------------------------------
+
+
+def render_markdown(
+ findings: Sequence[Mapping[str, Any]],
+ *,
+ gate: GateResult | None,
+ documents_scanned: int | None = None,
+ suppressed: int = 0,
+) -> str:
+ """Step-summary / PR-comment markdown: verdict first, then a capped table.
+
+ With a gate, only the failing findings are tabulated and a passing run
+ stays short. Without one, every finding is.
+ """
+ lines: list[str] = []
+ if gate is not None:
+ threshold = f"{gate.fail_on:.2f}"
+ if gate.passed:
+ lines.append(f"**No documentation drift at or above {threshold}.**")
+ else:
+ n = len(gate.failing)
+ verb = "fails" if n == 1 else "fail"
+ lines.append(
+ f"**Documentation drift: {plural(n, 'finding')} {verb} the gate** "
+ f"(confidence at or above {threshold}). Edit the document named "
+ "in each row."
+ )
+ rows = gate.failing
+ elif findings:
+ lines.append(
+ f"**Documentation drift: {plural(len(findings), 'finding')}.** "
+ "Edit the document named in each row."
+ )
+ rows = list(findings)
+ else:
+ lines.append("**No documentation drift found.**")
+ rows = []
+
+ notes: list[str] = []
+ if documents_scanned is not None:
+ notes.append(f"{plural(documents_scanned, 'document')} scanned")
+ if gate is not None and gate.baselined:
+ notes.append(f"{len(gate.baselined)} accepted by the baseline")
+ if gate is not None and gate.below_threshold:
+ notes.append(f"{gate.below_threshold} below the threshold")
+ if suppressed:
+ notes.append(f"{plural(suppressed, 'reference')} suppressed inline")
+ if notes:
+ lines.append("")
+ summary = "; ".join(notes)
+ lines.append(summary[:1].upper() + summary[1:] + ".")
+
+ if rows:
+ lines += [
+ "",
+ "| Document:line | Claims this exists | Kind | Confidence | Likely now |",
+ "| --- | --- | --- | --- | --- |",
+ ]
+ ordered = _order(rows)
+ for f in ordered[:ROW_LIMIT]:
+ lines.append(
+ f"| {cell(f['file_path'])}:{int(f['line_number'])} "
+ f"| {cell(f['target'])} | {cell(f['kind'])} "
+ f"| {float(f['confidence']):.2f} | {cell(_likely(f)) or '-'} |"
+ )
+ if len(ordered) > ROW_LIMIT:
+ lines += ["", more_line(len(ordered) - ROW_LIMIT, "findings")]
+
+ lines += ["", f"_{DETECTION_BASIS}_"]
+ return "\n".join(lines) + "\n"
+
+
+# ---------------------------------------------------------------------------
+# GitHub workflow annotations
+# ---------------------------------------------------------------------------
+
+
+def _annotation(level: str, finding: Mapping[str, Any]) -> str:
+ return github.annotation(
+ level,
+ _message(finding),
+ file=str(finding["file_path"]),
+ line=int(finding["line_number"]),
+ title=f"Doc drift ({finding['kind']})",
+ )
+
+
+def render_github_annotations(
+ findings: Sequence[Mapping[str, Any]],
+ *,
+ gate: GateResult | None,
+) -> list[str]:
+ """``::error`` for failing findings, ``::warning`` for the rest, errors first.
+
+ Baselined findings are accepted, so they are not annotated. Without a gate,
+ the high tier is an error. Capped by :func:`~repowise.core.ci.github.cap_annotations`,
+ which ends with a notice counting what it cut.
+ """
+ if gate is not None:
+ failing = {fingerprint_of(f) for f in gate.failing}
+ accepted = {fingerprint_of(f) for f in gate.baselined}
+ else:
+ failing = {
+ fingerprint_of(f)
+ for f in findings
+ if float(f["confidence"]) >= HIGH_CONFIDENCE_THRESHOLD
+ }
+ accepted = set()
+ errors: list[str] = []
+ warnings: list[str] = []
+ for f in _order(findings):
+ fp = fingerprint_of(f)
+ if fp in accepted:
+ continue
+ if fp in failing:
+ errors.append(_annotation("error", f))
+ else:
+ warnings.append(_annotation("warning", f))
+ return github.cap_annotations(errors + warnings, noun="documentation drift findings")
+
+
+# ---------------------------------------------------------------------------
+# SARIF 2.1.0
+# ---------------------------------------------------------------------------
+
+
+def _sarif_rules() -> list[dict]:
+ return [
+ sarif.rule(
+ kind.value,
+ f"DocDrift{kind.value.capitalize()}",
+ _RULE_TEXT[kind][0],
+ f"{_RULE_TEXT[kind][1]} {DETECTION_BASIS}",
+ DETECTION_BASIS,
+ )
+ for kind in DriftKind
+ ]
+
+
+def render_sarif(
+ findings: Sequence[Mapping[str, Any]],
+ *,
+ tool_version: str,
+ fail_on: float = HIGH_CONFIDENCE_THRESHOLD,
+) -> dict:
+ """One SARIF 2.1.0 run; ``partialFingerprints`` survive line shifts.
+
+ A finding at or above *fail_on* is an ``error``, so the level matches the gate.
+ """
+ results = []
+ for f in _order(findings):
+ confidence = float(f["confidence"])
+ properties: dict[str, Any] = {
+ "confidence": round(confidence, 2),
+ "origin": f["origin"],
+ "target": f["target"],
+ }
+ if likely := _likely(f):
+ properties["suggestion"] = likely
+ if f.get("suggestion_basis"):
+ properties["suggestion_basis"] = f["suggestion_basis"]
+ results.append(
+ sarif.result(
+ str(f["kind"]),
+ "error" if confidence >= fail_on else "warning",
+ _message(f),
+ str(f["file_path"]),
+ int(f["line_number"]),
+ SARIF_FINGERPRINT_KEY,
+ fingerprint_of(f),
+ properties,
+ )
+ )
+ return sarif.run(SARIF_TOOL_NAME, tool_version, _sarif_rules(), results)
diff --git a/packages/core/src/repowise/core/analysis/doc_drift/resolver.py b/packages/core/src/repowise/core/analysis/doc_drift/resolver.py
index 339752fa5..4cad295c9 100644
--- a/packages/core/src/repowise/core/analysis/doc_drift/resolver.py
+++ b/packages/core/src/repowise/core/analysis/doc_drift/resolver.py
@@ -9,6 +9,7 @@ from __future__ import annotations
import json
import re
+from collections.abc import Callable
from dataclasses import dataclass, field
from repowise.core.ingestion.special_handlers import iter_make_targets
@@ -89,6 +90,13 @@ class RepoIndex:
make_targets: frozenset[str] = frozenset()
npm_scripts: frozenset[str] = frozenset()
renderers: RendererMap = field(default_factory=lambda: RendererMap([]))
+ on_disk: Callable[[str], bool] | None = field(default=None, repr=False)
+ """Whether a repo-relative path exists in the working tree. Asked only on a
+ would-be ``MISSING`` path, so a file the index left out is uncheckable
+ and not drift. ``None`` when the caller has no checkout."""
+ opaque_dirs: frozenset[str] = frozenset()
+ """Directories whose contents the tree cannot list, such as submodules; a
+ path under one is uncheckable, never drift."""
_doc_anchors: dict[str, frozenset[str]] = field(default_factory=dict, repr=False)
_doc_text: dict[str, str] = field(default_factory=dict, repr=False)
@@ -98,6 +106,9 @@ class RepoIndex:
tracked_paths: frozenset[str] | set[str],
doc_text: dict[str, str],
manifest_text: dict[str, str] | None = None,
+ *,
+ on_disk: Callable[[str], bool] | None = None,
+ opaque_dirs: frozenset[str] | None = None,
) -> RepoIndex:
"""Compose the lookup tables.
@@ -108,6 +119,8 @@ class RepoIndex:
uncheckable rather than missing.
manifest_text: decoded ``Makefile`` / ``package.json`` contents,
keyed by path. Absent means the command class stands down.
+ on_disk: working-tree probe; see :attr:`on_disk`.
+ opaque_dirs: see :attr:`opaque_dirs`.
"""
files = frozenset(tracked_paths)
dirs: set[str] = set()
@@ -128,6 +141,8 @@ class RepoIndex:
make_targets=make_targets,
npm_scripts=npm_scripts,
renderers=RendererMap.detect(files),
+ on_disk=on_disk,
+ opaque_dirs=frozenset(opaque_dirs or ()),
_doc_text=doc_text,
)
@@ -199,7 +214,7 @@ def _scan_manifests(manifest_text: dict[str, str]) -> tuple[frozenset[str], froz
# ---------------------------------------------------------------------------
-def _join_relative(doc: str, target: str) -> str:
+def join_relative(doc: str, target: str) -> str:
"""Resolve *target* as written relative to the document that names it."""
doc_dir = doc.rsplit("/", 1)[0] if "/" in doc else ""
if not doc_dir:
@@ -229,15 +244,23 @@ def _exists(idx: RepoIndex, target: str) -> bool:
return bool(trimmed) and (trimmed in idx.files or trimmed in idx.dirs)
+def _under_opaque(idx: RepoIndex, path: str) -> bool:
+ path = path.rstrip("/")
+ return any(path == d or path.startswith(f"{d}/") for d in idx.opaque_dirs)
+
+
def _resolve_path(idx: RepoIndex, ref: DocReference, is_guide: bool) -> Resolution:
target = ref.target
if _exists(idx, target):
return Resolution(ref, DriftVerdict.RESOLVED, "exact", resolved_target=target)
- relative = _join_relative(ref.doc_path, target)
+ relative = join_relative(ref.doc_path, target)
if relative != target and _exists(idx, relative):
return Resolution(ref, DriftVerdict.RESOLVED, "relative-to-doc", resolved_target=relative)
+ if _under_opaque(idx, target) or _under_opaque(idx, relative):
+ return Resolution(ref, DriftVerdict.UNCHECKABLE, "inside-submodule")
+
# Anchoring. A reference is evidence about THIS repository only when it
# carries a separator and its first segment names a directory the
# repository actually has. Everything else is a file Repowise writes into
@@ -268,13 +291,20 @@ def _resolve_path(idx: RepoIndex, ref: DocReference, is_guide: bool) -> Resoluti
if suffix and suffix not in idx.indexed_suffixes:
return Resolution(ref, DriftVerdict.UNCHECKABLE, f"unindexed-kind:{suffix}")
+ # Present in the working tree but not the index (a fixture, an ignored
+ # file): the index cannot speak to it, and the document is not wrong.
+ if idx.on_disk is not None and (
+ idx.on_disk(target) or (relative != target and idx.on_disk(relative))
+ ):
+ return Resolution(ref, DriftVerdict.UNCHECKABLE, "outside-index")
+
origin = "path_no_candidate_in_guide" if is_guide else "path_no_candidate"
return Resolution(ref, DriftVerdict.MISSING, "no-candidate", origin)
-def _resolve_anchor(idx: RepoIndex, ref: DocReference) -> Resolution:
- target, _, frag = ref.target.partition("#")
-
+def anchor_host(idx: RepoIndex, ref: DocReference) -> str:
+ """The document an ``ANCHOR`` reference's fragment must be declared in."""
+ target = ref.target.partition("#")[0]
# Joined relative to the referring document FIRST, because that is what a
# markdown link means: every renderer resolves ``[g](guide.md#setup)`` in
# ``docs/a.md`` as ``docs/guide.md``. Preferring a verbatim root-relative
@@ -282,9 +312,15 @@ def _resolve_anchor(idx: RepoIndex, ref: DocReference) -> Resolution:
# then reported the correct link as a renamed heading at 0.95 --- the
# highest confidence this detector issues.
if target:
- relative = _join_relative(ref.doc_path, target)
+ relative = join_relative(ref.doc_path, target)
if relative in idx.files:
- target = relative
+ return relative
+ return target
+
+
+def _resolve_anchor(idx: RepoIndex, ref: DocReference) -> Resolution:
+ frag = ref.target.partition("#")[2]
+ target = anchor_host(idx, ref)
# Gated on the renderer of the document that DECLARES the anchors, because
# that is what decides the slug. Never guess an unimplemented renderer's
diff --git a/packages/core/src/repowise/core/analysis/doc_drift/serialize.py b/packages/core/src/repowise/core/analysis/doc_drift/serialize.py
index 7fb154e36..acb522ce9 100644
--- a/packages/core/src/repowise/core/analysis/doc_drift/serialize.py
+++ b/packages/core/src/repowise/core/analysis/doc_drift/serialize.py
@@ -75,6 +75,29 @@ def derive_doc_drift_id(
return hashlib.sha256(_FIELD_SEP.join(parts).encode("utf-8")).hexdigest()[:32]
+#: Namespace for :func:`derive_doc_drift_fingerprint`; distinct from the id's.
+_FINGERPRINT_NAMESPACE = "repowise.doc_drift.fingerprint.v1"
+
+
+def derive_doc_drift_fingerprint(file_path: str, kind: Any, target: str) -> str:
+ """The id minus the line number: the key a baseline or triage holds.
+
+ ``derive_doc_drift_id`` changes whenever an edit above the finding shifts
+ its line, which would turn every accepted finding back into a new one.
+ Consequence accepted: one document naming the same missing target twice
+ has one fingerprint for both.
+ """
+ parts = (_FINGERPRINT_NAMESPACE, file_path, _kind_str(kind), target)
+ return hashlib.sha256(_FIELD_SEP.join(parts).encode("utf-8")).hexdigest()[:32]
+
+
+def fingerprint_of(finding: Mapping[str, Any]) -> str:
+ """The finding dict's fingerprint, derived when it does not carry one."""
+ return finding.get("fingerprint") or derive_doc_drift_fingerprint(
+ finding["file_path"], finding["kind"], finding["target"]
+ )
+
+
def finding_dict(
*,
file_path: str,
@@ -87,6 +110,8 @@ def finding_dict(
raw: str,
context: str,
evidence: Sequence[str] | None = None,
+ suggestion: str | None = None,
+ suggestion_basis: str | None = None,
) -> dict:
"""One finding as a dict, from primitives either producer can supply.
@@ -99,6 +124,9 @@ def finding_dict(
``evidence=None`` drops the key for a caller under a response budget: its
first line restates ``file_path``, ``line_number`` and ``raw``, and the
rest is the resolver's own trace.
+
+ ``suggestion``/``suggestion_basis`` appear only when a suggestion exists,
+ so a finding without one (most of them) serializes as it always did.
"""
out = {
"file_path": file_path,
@@ -115,6 +143,10 @@ def finding_dict(
}
if evidence is not None:
out["evidence"] = [str(line) for line in evidence]
+ if suggestion:
+ out["suggestion"] = suggestion
+ if suggestion_basis:
+ out["suggestion_basis"] = suggestion_basis
return out
@@ -159,6 +191,8 @@ def serialize_finding(finding: Any, *, evidence: bool = True) -> dict:
raw=finding.raw,
context=finding.context,
evidence=list(finding.evidence or []) if evidence else None,
+ suggestion=finding.suggestion,
+ suggestion_basis=finding.suggestion_basis,
)
@@ -261,6 +295,8 @@ def serialize_report(report: Any) -> dict:
data["id"] = derive_doc_drift_id(
data["file_path"], data["kind"], data["line_number"], data["target"]
)
+ # Line-independent key for baselines; never in finding_dict, so not MCP.
+ data["fingerprint"] = fingerprint_of(data)
findings.append(data)
by_target: dict[str, list[dict]] = {}
@@ -279,4 +315,5 @@ def serialize_report(report: Any) -> dict:
"references_checked": report.references_checked,
"verdict_summary": dict(report.verdict_summary),
"anchor_renderer": report.anchor_renderer,
+ "suppressed": report.suppressed,
}
diff --git a/packages/core/src/repowise/core/analysis/doc_drift/suggest.py b/packages/core/src/repowise/core/analysis/doc_drift/suggest.py
new file mode 100644
index 000000000..ab7e0c8f6
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/doc_drift/suggest.py
@@ -0,0 +1,310 @@
+"""Likely replacements for references the tree refutes.
+
+A suggestion is evidence for the reader, never a verdict: it does not move a
+finding's confidence, and nothing here rewrites a document. Every strategy
+fires only on a unique answer, because a wrong "likely now" costs the reader
+more than no suggestion at all.
+
+Pure over :class:`~.resolver.RepoIndex` plus two injected callables, a rename
+lookup and an on-disk probe, so a host without a checkout can run it. The one
+I/O implementation, :func:`git_renames`, is a default the analyzer wires in
+when it has a repository root.
+
+A path is looked up both as written and joined relative to its document, and a
+suggestion found through the relative form is written back in that form, so it
+pastes into the same link.
+"""
+
+from __future__ import annotations
+
+import os
+import posixpath
+import subprocess
+from collections.abc import Callable, Mapping, Sequence
+from difflib import SequenceMatcher, get_close_matches
+from functools import cache
+from pathlib import Path
+from typing import Literal
+
+from .constants import SuggestionBasis
+from .models import DriftKind
+from .renderer import github_slug
+from .resolver import RepoIndex, Resolution, anchor_host, join_relative
+
+#: Where each given old repo path ended up, for as many of them as it knows.
+RenameLookup = Callable[[Sequence[str]], Mapping[str, str]]
+
+#: ``(suggestion, basis)``; both empty when no strategy found a unique answer.
+Suggestion = tuple[str, SuggestionBasis | Literal[""]]
+
+_NONE: Suggestion = ("", "")
+_PATH_KINDS = (DriftKind.PATH, DriftKind.LINK)
+
+# difflib's ratio. 0.75 admits a typo or a one-word heading edit and rejects
+# a different word of similar length.
+_CLOSE_CUTOFF = 0.75
+# Two candidates this close in ratio are a coin toss, not a suggestion.
+_TIE_MARGIN = 0.05
+
+_MAX_RENAME_PATHS = 200
+_GIT_TIMEOUT_SECONDS = 3
+# History searched for renames, bounded by a revision range (``-n`` counts
+# matching commits, not scanned ones). Older renames go unsuggested.
+_MAX_RENAME_COMMITS = 5000
+
+#: ``(repo path, written relative to the document)`` for one reference.
+_Form = tuple[str, bool]
+_DirTails = Callable[[], Mapping[str, Sequence[str]]]
+
+
+def suggest_all(
+ misses: Sequence[Resolution],
+ idx: RepoIndex,
+ *,
+ rename_lookup: RenameLookup | None = None,
+ on_disk: Callable[[str], bool] | None = None,
+) -> list[Suggestion]:
+ """One suggestion per ``MISSING`` resolution, aligned with *misses*.
+
+ Index-local strategies run first. The rename lookup is called at most once,
+ batched over the path misses they left unanswered.
+ """
+ dir_tails = cache(lambda: _dirs_by_tail(idx.dirs))
+ out = [_local(res, idx, dir_tails) for res in misses]
+ if rename_lookup is None:
+ return out
+
+ pending = {
+ i: _forms(res.ref.doc_path, res.ref.target)
+ for i, res in enumerate(misses)
+ if not out[i][0] and res.ref.kind in _PATH_KINDS
+ }
+ if not pending:
+ return out
+ wanted = sorted({path for forms in pending.values() for path, _ in forms})
+ try:
+ renames = rename_lookup(wanted)
+ except Exception: # an injected lookup must never fail the drift pass
+ return out
+ for i, forms in pending.items():
+ for path, relative in forms:
+ new = renames.get(path, "")
+ if new and (new in idx.files or (on_disk is not None and on_disk(new))):
+ out[i] = (_written(misses[i].ref.doc_path, new, relative), "git_rename")
+ break
+ return out
+
+
+def unique_close_match(word: str, candidates: frozenset[str] | set[str]) -> str:
+ """The single close match for *word*, or ``""`` when none or a near tie."""
+ matches = get_close_matches(word, sorted(candidates), n=2, cutoff=_CLOSE_CUTOFF)
+ if not matches:
+ return ""
+ if len(matches) == 2:
+ best, second = (SequenceMatcher(None, m, word).ratio() for m in matches)
+ if best - second < _TIE_MARGIN:
+ return ""
+ return matches[0]
+
+
+def _forms(doc: str, target: str) -> list[_Form]:
+ """*target* as written, then joined relative to *doc* when that differs."""
+ joined = join_relative(doc, target)
+ return [(target, False)] if joined == target else [(target, False), (joined, True)]
+
+
+def _written(doc: str, path: str, relative: bool) -> str:
+ """*path* in the form the document used."""
+ if not relative:
+ return path
+ return posixpath.relpath(path, doc.rsplit("/", 1)[0] if "/" in doc else ".")
+
+
+def _dirs_by_tail(dirs: frozenset[str]) -> dict[str, list[str]]:
+ """Directories of three or more segments, keyed by their last two."""
+ out: dict[str, list[str]] = {}
+ for d in dirs:
+ parts = d.rsplit("/", 2)
+ if len(parts) == 3:
+ out.setdefault(f"{parts[1]}/{parts[2]}", []).append(d)
+ return out
+
+
+def _local(res: Resolution, idx: RepoIndex, dir_tails: _DirTails) -> Suggestion:
+ kind = res.ref.kind
+ if kind in _PATH_KINDS:
+ return _package_split(res, idx, dir_tails)
+ if kind is DriftKind.ANCHOR:
+ return _similar_heading(res, idx)
+ if kind is DriftKind.COMMAND:
+ return _similar_target(res, idx)
+ return _NONE
+
+
+def _package_split(res: Resolution, idx: RepoIndex, dir_tails: _DirTails) -> Suggestion:
+ """``a/b/x.py`` is gone and ``a/b/x/`` exists: the module became a package."""
+ doc, target = res.ref.doc_path, res.ref.target
+ base = target.rsplit("/", 1)[-1]
+ dot = base.rfind(".")
+ if dot <= 0:
+ return _NONE
+ forms = _forms(doc, target[: len(target) - len(base) + dot])
+ for stem, relative in forms:
+ if stem in idx.dirs:
+ return f"{_written(doc, stem, relative)}/", "package_split"
+ # The package also moved (``core/ingestion/x.py`` -> ``core/src/.../ingestion/x/``):
+ # accept the one directory under the same top level ending in the last two segments.
+ for stem, relative in forms:
+ segments = stem.split("/")
+ if len(segments) < 3:
+ continue
+ top = segments[0] + "/"
+ found = [d for d in dir_tails().get("/".join(segments[-2:]), ()) if d.startswith(top)]
+ if len(found) == 1:
+ return f"{_written(doc, found[0], relative)}/", "package_split"
+ return _NONE
+
+
+def _similar_heading(res: Resolution, idx: RepoIndex) -> Suggestion:
+ ref = res.ref
+ fragment = ref.target.partition("#")[2]
+ anchors = idx.doc_anchors(anchor_host(idx, ref) or ref.doc_path)
+ match = unique_close_match(github_slug(fragment), anchors)
+ if not match:
+ return _NONE
+ return f"{ref.raw.partition('#')[0]}#{match}", "similar_heading"
+
+
+def _similar_target(res: Resolution, idx: RepoIndex) -> Suggestion:
+ ref = res.ref
+ runner, _, name = ref.target.partition(":")
+ candidates = idx.make_targets if runner == "make" else idx.npm_scripts
+ match = unique_close_match(name, candidates)
+ if not match or not ref.raw.endswith(name):
+ return _NONE
+ # The runner stays as written: ``pnpm run x`` is not rewritten to ``npm``.
+ return f"{ref.raw[: len(ref.raw) - len(name)]}{match}", "similar_target"
+
+
+# ---------------------------------------------------------------------------
+# git history
+# ---------------------------------------------------------------------------
+
+
+def _git_out(root: Path, *args: str) -> str:
+ """stdout of one short git call, or ``""`` on any failure.
+
+ Never fetches: in a blobless CI clone, rename detection would otherwise
+ pull blobs over the network.
+ """
+ env = {**os.environ, "GIT_NO_LAZY_FETCH": "1", "GIT_LITERAL_PATHSPECS": "1"}
+ try:
+ proc = subprocess.run(
+ ["git", "-C", str(root), "-c", "core.quotePath=false", *args],
+ capture_output=True,
+ text=True,
+ encoding="utf-8",
+ errors="replace",
+ stdin=subprocess.DEVNULL,
+ env=env,
+ timeout=_GIT_TIMEOUT_SECONDS,
+ check=False,
+ )
+ except (OSError, subprocess.SubprocessError, ValueError):
+ return ""
+ return proc.stdout if proc.returncode == 0 else ""
+
+
+def _pathspec_safe(path: str) -> bool:
+ return bool(path) and not path.startswith("/") and ".." not in path.split("/")
+
+
+def _commit_blocks(out: str) -> list[tuple[str, list[str]]]:
+ """``--format=commit %H`` output as ``(sha, lines)`` in output order."""
+ blocks: list[tuple[str, list[str]]] = []
+ for line in out.splitlines():
+ if line.startswith("commit ") and "\t" not in line:
+ blocks.append((line[7:].strip(), []))
+ elif line and blocks:
+ blocks[-1][1].append(line)
+ return blocks
+
+
+def _deletions(root: Path, revs: Sequence[str], paths: Sequence[str]) -> dict[str, list[str]]:
+ """Commits that deleted each of *paths*, newest first."""
+ args = ["--no-renames", "--diff-filter=D", "--format=commit %H", "--name-only"]
+ out = _git_out(root, "log", *args, *revs, "--", *paths)
+ found: dict[str, list[str]] = {}
+ for sha, lines in _commit_blocks(out):
+ for path in lines:
+ found.setdefault(path, []).append(sha)
+ return found
+
+
+def _renames_in(root: Path, shas: Sequence[str]) -> dict[str, dict[str, str]]:
+ """``{sha: {old: new}}`` for the renames each of *shas* made."""
+ out = _git_out(
+ root, "show", "-M", "--diff-filter=R", "--name-status", "--format=commit %H", *shas
+ )
+ found: dict[str, dict[str, str]] = {}
+ for sha, lines in _commit_blocks(out):
+ for line in lines:
+ parts = line.split("\t")
+ if len(parts) == 3 and parts[0].startswith("R"):
+ found.setdefault(sha, {})[parts[1]] = parts[2]
+ return found
+
+
+def git_renames(root: Path, paths: Sequence[str]) -> dict[str, str]:
+ """Where each of *paths* ended up through the renames in *root*'s history.
+
+ Per hop, a pathspec-pruned ``git log`` finds the commit that deleted the
+ path, then ``git show -M`` reads that commit alone for what it became. A
+ pathspec cannot find the rename directly: git limits the diff to it before
+ rename detection, so ``-- old.py`` sees only a deletion. A later hop counts
+ only when its commit is newer than the one before, so a chain never joins
+ an older, unrelated rename. Returns ``{}`` on any failure.
+ """
+ wanted = [p for p in dict.fromkeys(paths) if _pathspec_safe(p)][:_MAX_RENAME_PATHS]
+ if not wanted:
+ return {}
+ boundary = _git_out(
+ root, "rev-list", "--max-count=1", f"--skip={_MAX_RENAME_COMMITS}", "HEAD"
+ ).strip()
+ revs = [f"{boundary}..HEAD"] if boundary else ["HEAD"]
+
+ order: dict[str, int] = {}
+
+ def age(sha: str) -> int:
+ """Position in the bounded history, 0 at HEAD; one rev-list, on demand."""
+ if not order:
+ order.update((s, i) for i, s in enumerate(_git_out(root, "rev-list", *revs).split()))
+ return order.get(sha, len(order))
+
+ final: dict[str, str] = {}
+ seen = {p: {p} for p in wanted}
+ # start -> (current path, age of the commit that created it; None at the start)
+ active: dict[str, tuple[str, int | None]] = {p: (p, None) for p in wanted}
+ while active:
+ deletions = _deletions(root, revs, sorted({cur for cur, _ in active.values()}))
+ chosen: dict[str, str] = {}
+ for start, (cur, created) in active.items():
+ shas = deletions.get(cur, [])
+ if created is not None:
+ # The first deletion after the path arrived, never an older one.
+ shas = [s for s in shas if age(s) < created][-1:]
+ if shas:
+ chosen[start] = shas[0]
+ if not chosen:
+ break
+ renames = _renames_in(root, sorted(set(chosen.values())))
+ following: dict[str, tuple[str, int | None]] = {}
+ for start, sha in chosen.items():
+ new = renames.get(sha, {}).get(active[start][0])
+ if not new or new in seen[start]: # deleted outright, or a cycle
+ continue
+ seen[start].add(new)
+ final[start] = new
+ following[start] = (new, age(sha))
+ active = following
+ return final
diff --git a/packages/core/src/repowise/core/ci/sarif.py b/packages/core/src/repowise/core/ci/sarif.py
new file mode 100644
index 000000000..64d07928f
--- /dev/null
+++ b/packages/core/src/repowise/core/ci/sarif.py
@@ -0,0 +1,89 @@
+"""SARIF 2.1.0 envelopes for code-scanning upload. Features supply rules and results."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+from urllib.parse import quote
+
+SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json"
+INFORMATION_URI = "https://repowise.dev"
+
+
+def rule(rule_id: str, name: str, short: str, full: str, help_text: str | None = None) -> dict:
+ """One ``reportingDescriptor``."""
+ out: dict[str, Any] = {
+ "id": rule_id,
+ "name": name,
+ "shortDescription": {"text": short},
+ "fullDescription": {"text": full},
+ }
+ if help_text:
+ out["help"] = {"text": help_text}
+ return out
+
+
+def result(
+ rule_id: str,
+ level: str,
+ message: str,
+ path: str,
+ line: int,
+ fingerprint_key: str,
+ fingerprint: str,
+ properties: Mapping[str, Any] | None = None,
+) -> dict:
+ """One result, located relative to ``%SRCROOT%`` with a percent-encoded URI."""
+ out: dict[str, Any] = {
+ "ruleId": rule_id,
+ "level": level,
+ "message": {"text": message},
+ "locations": [
+ {
+ "physicalLocation": {
+ "artifactLocation": {
+ "uri": quote(path.replace("\\", "/").lstrip("/"), safe="/"),
+ "uriBaseId": "%SRCROOT%",
+ },
+ "region": {"startLine": max(1, int(line))},
+ }
+ }
+ ],
+ "partialFingerprints": {fingerprint_key: fingerprint},
+ }
+ if properties:
+ out["properties"] = dict(properties)
+ return out
+
+
+def run(
+ tool_name: str,
+ version: str,
+ rules: Sequence[Mapping[str, Any]],
+ results: Sequence[Mapping[str, Any]],
+) -> dict:
+ """A complete log with one run; ``ruleIndex`` is filled for known rule ids."""
+ index = {r["id"]: i for i, r in enumerate(rules)}
+ indexed = []
+ for res in results:
+ res = dict(res)
+ if res["ruleId"] in index:
+ res["ruleIndex"] = index[res["ruleId"]]
+ indexed.append(res)
+ return {
+ "$schema": SCHEMA,
+ "version": "2.1.0",
+ "runs": [
+ {
+ "tool": {
+ "driver": {
+ "name": tool_name,
+ "version": version,
+ "informationUri": INFORMATION_URI,
+ "rules": [dict(r) for r in rules],
+ }
+ },
+ "results": indexed,
+ }
+ ],
+ }
diff --git a/packages/core/src/repowise/core/ingestion/traverser.py b/packages/core/src/repowise/core/ingestion/traverser.py
index 832e90b36..a02a4e3d2 100644
--- a/packages/core/src/repowise/core/ingestion/traverser.py
+++ b/packages/core/src/repowise/core/ingestion/traverser.py
@@ -131,6 +131,9 @@ class TraversalStats:
log = structlog.get_logger(__name__)
+#: The root/per-directory ignore file, gitignore syntax.
+REPOWISE_IGNORE_FILENAME = ".repowiseIgnore"
+
#: Cap on the nested-repo names retained in :class:`TraversalStats`.
_MAX_NESTED_REPO_PATHS = 50
@@ -333,7 +336,7 @@ class FileTraverser:
repo_root: Path,
*,
max_file_size_kb: int = 500,
- extra_ignore_filename: str = ".repowiseIgnore",
+ extra_ignore_filename: str = REPOWISE_IGNORE_FILENAME,
extra_exclude_patterns: list[str] | None = None,
include_submodules: bool = False,
include_nested_repos: bool = False,
@@ -344,7 +347,7 @@ class FileTraverser:
self.max_file_size_bytes = max_file_size_kb * 1024
self._extra_ignore_filename = extra_ignore_filename
self._gitignore = load_gitignore_spec(self.repo_root)
- self._extra_ignore = _load_extra_ignore_spec(self.repo_root, extra_ignore_filename)
+ self._extra_ignore = load_extra_ignore_spec(self.repo_root, extra_ignore_filename)
self._blocked_patterns = _BLOCKED_FILENAME_SPEC
patterns = extra_exclude_patterns or []
self._extra_exclude = _compile_gitignore(patterns)
@@ -1247,7 +1250,8 @@ def load_gitignore_spec(repo_root: Path) -> pathspec.PathSpec:
return _compile_gitignore(lines)
-def _load_extra_ignore_spec(repo_root: Path, filename: str) -> pathspec.PathSpec:
+def load_extra_ignore_spec(repo_root: Path, filename: str) -> pathspec.PathSpec:
+ """The ignore file *filename* at *repo_root* as a spec; empty when absent."""
ignore_file = repo_root / filename
lines: list[str] = []
if ignore_file.exists():
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 71f52e520..0f2f5e4ce 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
@@ -141,6 +141,9 @@ def _row_kwargs(finding: Any, repository_id: str) -> dict:
"evidence_json": json.dumps(list(finding.evidence or [])),
"raw": finding.raw,
"context": finding.context,
+ # Empty means no suggestion; stored as NULL so the column says so.
+ "suggestion": (getattr(finding, "suggestion", "") or "")[:_PATH_COLUMN_WIDTH] or None,
+ "suggestion_basis": getattr(finding, "suggestion_basis", "") or None,
}
@@ -392,6 +395,8 @@ def serialize_doc_drift_row(row: DocDriftFinding, *, evidence: bool = True) -> d
raw=row.raw,
context=row.context,
evidence=_decode_evidence(row.evidence_json) if evidence else None,
+ suggestion=row.suggestion,
+ suggestion_basis=row.suggestion_basis,
)
diff --git a/packages/core/src/repowise/core/persistence/models.py b/packages/core/src/repowise/core/persistence/models.py
index 8dfb0143b..c76a4a2f7 100644
--- a/packages/core/src/repowise/core/persistence/models.py
+++ b/packages/core/src/repowise/core/persistence/models.py
@@ -1694,6 +1694,10 @@ class DocDriftFinding(Base):
#: The reference exactly as written, and the line it was written on.
raw: Mapped[str] = mapped_column(Text, nullable=False, default="")
context: Mapped[str] = mapped_column(Text, nullable=False, default="")
+ #: The likely replacement for a missing target, and the ``SUGGESTION_BASIS``
+ #: that produced it. Null when none was found; never changes the verdict.
+ suggestion: Mapped[str | None] = mapped_column(String(1024), nullable=True)
+ suggestion_basis: Mapped[str | None] = mapped_column(String(32), nullable=True)
detected_at: Mapped[datetime] = mapped_column(
DateTime(timezone=True), nullable=False, default=_now_utc
)
diff --git a/packages/core/src/repowise/core/pipeline/incremental.py b/packages/core/src/repowise/core/pipeline/incremental.py
index 4d8def532..487bc647f 100644
--- a/packages/core/src/repowise/core/pipeline/incremental.py
+++ b/packages/core/src/repowise/core/pipeline/incremental.py
@@ -889,6 +889,7 @@ def run_doc_drift_partial(
graph_builder: Any,
source_map: dict[str, bytes] | None,
*,
+ repo_path: Any | None = None,
log: LogFn | None = None,
timings: PhaseTimings | None = None,
) -> Any | None:
@@ -917,6 +918,7 @@ def run_doc_drift_partial(
report = DocDriftAnalyzer(
source_map=source_map,
tracked_paths=tracked_paths,
+ repo_root=Path(repo_path) if repo_path else None,
).analyze()
report.authoritative_paths = report.documents
if report.total_findings:
diff --git a/packages/core/src/repowise/core/pipeline/orchestrator.py b/packages/core/src/repowise/core/pipeline/orchestrator.py
index dc6b8daf2..d967068aa 100644
--- a/packages/core/src/repowise/core/pipeline/orchestrator.py
+++ b/packages/core/src/repowise/core/pipeline/orchestrator.py
@@ -545,6 +545,7 @@ async def run_pipeline(
_run_doc_drift_analysis(
source_map,
file_infos=file_infos,
+ repo_path=repo_path,
progress=progress,
),
)
diff --git a/packages/core/src/repowise/core/pipeline/phases/analysis.py b/packages/core/src/repowise/core/pipeline/phases/analysis.py
index c92583bde..24eb0c690 100644
--- a/packages/core/src/repowise/core/pipeline/phases/analysis.py
+++ b/packages/core/src/repowise/core/pipeline/phases/analysis.py
@@ -113,6 +113,7 @@ async def _run_doc_drift_analysis(
*,
file_infos: list[Any] | None = None,
repo_id: str = "",
+ repo_path: Path | None = None,
progress: ProgressCallback | None,
) -> Any | None:
"""Check the repository's own markdown against the tree (no LLM).
@@ -139,6 +140,7 @@ async def _run_doc_drift_analysis(
repo_id,
source_map=source_map,
tracked_paths=tracked_paths,
+ repo_root=repo_path,
)
def _step(_stage: str) -> None:
diff --git a/packages/core/src/repowise/core/workspace/update.py b/packages/core/src/repowise/core/workspace/update.py
index 50469d817..474ecf7e5 100644
--- a/packages/core/src/repowise/core/workspace/update.py
+++ b/packages/core/src/repowise/core/workspace/update.py
@@ -488,7 +488,9 @@ 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)
+ doc_drift_report = run_doc_drift_partial(
+ graph_builder, source_map, repo_path=repo_path, log=_log.info
+ )
# Partial health has consumed the per-file ``BlameIndex``; drop it before
# the metadata reaches persistence so the transient, non-serializable
diff --git a/packages/server/src/repowise/server/schemas/doc_drift.py b/packages/server/src/repowise/server/schemas/doc_drift.py
index c8e736bc6..8337a0ee3 100644
--- a/packages/server/src/repowise/server/schemas/doc_drift.py
+++ b/packages/server/src/repowise/server/schemas/doc_drift.py
@@ -14,16 +14,16 @@ claim that the tree is clean, and only a populated store can support it.
from __future__ import annotations
-from typing import Literal
+from typing import Any, Literal
-from pydantic import BaseModel
+from pydantic import BaseModel, model_validator
from repowise.core.analysis.doc_drift.constants import (
UNAVAILABLE_NO_TABLE,
UNAVAILABLE_NOT_COMPUTED,
UNAVAILABLE_READ_FAILED,
)
-from repowise.core.analysis.doc_drift.serialize import derive_doc_drift_id
+from repowise.core.analysis.doc_drift.serialize import derive_doc_drift_id, fingerprint_of
#: Why a drift answer could not be given, from the engine's own vocabulary so
#: the literal cannot be renamed on one side alone.
@@ -55,6 +55,22 @@ class DocDriftFindingResponse(BaseModel):
raw: str
context: str
evidence: list[str]
+ #: Line-independent key a baseline holds; see :func:`fingerprint_of`.
+ fingerprint: str
+ #: Likely replacement for a missing target, and the basis that found it.
+ suggestion: str | None = None
+ suggestion_basis: str | None = None
+
+ @model_validator(mode="before")
+ @classmethod
+ def _derive_fingerprint(cls, data: Any) -> Any:
+ """Fill ``fingerprint`` for dicts that lack it (hosted builds from artifacts)."""
+ if isinstance(data, dict) and not data.get("fingerprint"):
+ try:
+ return {**data, "fingerprint": fingerprint_of(data)}
+ except KeyError:
+ return data # let field validation name what is missing
+ return data
@classmethod
def from_dict(cls, data: dict) -> DocDriftFindingResponse:
@@ -76,6 +92,8 @@ class DocDriftFindingResponse(BaseModel):
raw=data["raw"],
context=data["context"],
evidence=data.get("evidence", []),
+ suggestion=data.get("suggestion") or None,
+ suggestion_basis=data.get("suggestion_basis") or None,
)
diff --git a/packages/types/src/doc-drift.ts b/packages/types/src/doc-drift.ts
index 1a76f7eb5..e2d9a101f 100644
--- a/packages/types/src/doc-drift.ts
+++ b/packages/types/src/doc-drift.ts
@@ -87,6 +87,19 @@ export function docDriftKindLabel(kind: string): string {
return DOC_DRIFT_KIND_LABELS[kind as DocDriftKind] ?? kind;
}
+/**
+ * How a finding's suggested replacement was found, in a reader's words.
+ *
+ * Keys mirror `SuggestionBasis` in `core/analysis/doc_drift/constants.py`,
+ * pinned by `tests/unit/doc_drift/test_ts_contract_parity.py`.
+ */
+export const SUGGESTION_BASIS_LABELS: Readonly<Record<string, string>> = {
+ package_split: "Became a package",
+ git_rename: "Renamed in git",
+ similar_heading: "Similar heading",
+ similar_target: "Similar target",
+};
+
export interface DocDriftFinding {
/**
* Stable across stores and rebuilds, derived from
@@ -116,6 +129,12 @@ export interface DocDriftFinding {
context: string;
/** Lines a reader can check for themselves. */
evidence: string[];
+ /** Line-independent key a CI baseline holds; survives edits above the finding. */
+ fingerprint: string;
+ /** What the missing target is likely called now. Evidence, never a verdict. */
+ suggestion?: string | null;
+ /** Key of `SUGGESTION_BASIS_LABELS` naming how `suggestion` was found. */
+ suggestion_basis?: string | null;
}
/**
diff --git a/packages/types/src/generated/http.ts b/packages/types/src/generated/http.ts
index adb26c637..28af11a54 100644
--- a/packages/types/src/generated/http.ts
+++ b/packages/types/src/generated/http.ts
@@ -1067,6 +1067,9 @@ export interface DocDriftFindingResponse {
raw: string;
context: string;
evidence: string[];
+ fingerprint: string;
+ suggestion?: string | null;
+ suggestion_basis?: string | null;
}
/**
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 7a050d443..6606f9d81 100644
--- a/packages/ui/__tests__/doc-drift/doc-drift-view.test.tsx
+++ b/packages/ui/__tests__/doc-drift/doc-drift-view.test.tsx
@@ -47,6 +47,9 @@ const FINDINGS: DocDriftFinding[] = [
"resolution: no-candidate",
"under: Architecture > Resolvers",
],
+ fingerprint: "fp1",
+ suggestion: "src/auth/",
+ suggestion_basis: "package_split",
},
{
id: "f2",
@@ -60,6 +63,7 @@ const FINDINGS: DocDriftFinding[] = [
raw: "#usage",
context: "See [usage](#usage).",
evidence: [],
+ fingerprint: "fp2",
},
];
@@ -345,6 +349,22 @@ describe("DocDriftView", () => {
expect(screen.getByText(/resolution: no-candidate/)).toBeTruthy();
});
+ it("shows the likely replacement only when the engine found one", async () => {
+ renderView(<DocDriftView adapter={makeAdapter()} />);
+ const table = await screen.findByRole("table", TABLE);
+ fireEvent.click(within(table).getByText(/docs\/architecture\.md/));
+
+ const panel = await screen.findByRole("dialog", { name: PANEL });
+ expect(within(panel).getByText("Likely now")).toBeTruthy();
+ expect(within(panel).getByText("src/auth/")).toBeTruthy();
+ expect(within(panel).getByText("Became a package")).toBeTruthy();
+
+ // The document and its own-anchor target both match; either cell opens the row.
+ fireEvent.click(within(table).getAllByText(/docs\/cli\.md/)[0]!);
+ const other = await screen.findByRole("dialog", { name: /docs\/cli\.md:7/ });
+ expect(within(other).queryByText("Likely now")).toBeNull();
+ });
+
it("repeats what a finding does and does not claim where the action is", async () => {
renderView(<DocDriftView adapter={makeAdapter()} />);
const table = await screen.findByRole("table", TABLE);
@@ -399,6 +419,7 @@ describe("DocDriftView", () => {
expect(prompt).toContain("Edit the document, not the code.");
// And it has to leave room for a deliberate example to be correct.
expect(prompt).toContain("Some findings are correct as written.");
+ expect(prompt).toContain("Likely replacement: `src/auth/` (Became a package)");
});
it("can hand the whole slice over at once", async () => {
diff --git a/packages/ui/src/doc-drift/doc-drift-detail-panel.tsx b/packages/ui/src/doc-drift/doc-drift-detail-panel.tsx
index f8ff077ed..8b4d22888 100644
--- a/packages/ui/src/doc-drift/doc-drift-detail-panel.tsx
+++ b/packages/ui/src/doc-drift/doc-drift-detail-panel.tsx
@@ -19,6 +19,7 @@ import { ExternalLink } from "lucide-react";
import {
docDriftConfidenceTier,
docDriftKindLabel,
+ SUGGESTION_BASIS_LABELS,
type DocDriftFinding,
} from "@repowise-dev/types/doc-drift";
@@ -102,6 +103,20 @@ export function DocDriftDetailPanel({
</p>
</Section>
+ {/* Evidence, not a verdict: the reader still confirms it. */}
+ {finding.suggestion && (
+ <Section title="Likely now">
+ <p className="font-mono text-xs break-all text-[var(--color-text-primary)]">
+ {finding.suggestion}
+ </p>
+ {finding.suggestion_basis && (
+ <p className="text-xs text-[var(--color-text-tertiary)]">
+ {SUGGESTION_BASIS_LABELS[finding.suggestion_basis] ?? finding.suggestion_basis}
+ </p>
+ )}
+ </Section>
+ )}
+
{finding.context && (
<Section title="The line as written">
<pre className="overflow-x-auto rounded-md bg-[var(--color-bg-inset)] p-3 text-[11px] leading-relaxed text-[var(--color-text-primary)]">
diff --git a/packages/ui/src/health/ai-prompts/doc-drift-prompt.ts b/packages/ui/src/health/ai-prompts/doc-drift-prompt.ts
index e543414f6..51ca20e3f 100644
--- a/packages/ui/src/health/ai-prompts/doc-drift-prompt.ts
+++ b/packages/ui/src/health/ai-prompts/doc-drift-prompt.ts
@@ -1,3 +1,5 @@
+import { SUGGESTION_BASIS_LABELS } from "@repowise-dev/types/doc-drift";
+
import {
bulletList,
closingSections,
@@ -27,6 +29,9 @@ export interface DocDriftPromptFinding {
raw?: string | null;
/** The resolver's trace, including the enclosing heading trail. */
evidence?: string[] | null;
+ /** What the target is likely called now; evidence the agent must verify. */
+ suggestion?: string | null;
+ suggestion_basis?: string | null;
}
export interface BuildDocDriftPromptOptions {
@@ -56,6 +61,10 @@ const EXPECTED = [
const SECTION_PREFIX = "under: ";
+function basisSuffix(basis: string | null | undefined): string {
+ return basis ? ` (${SUGGESTION_BASIS_LABELS[basis] ?? basis})` : "";
+}
+
function findingEntry(f: DocDriftPromptFinding): string {
// The heading trail locates the passage, so it gets its own label.
const trail = (f.evidence ?? []).find((line) => line.startsWith(SECTION_PREFIX));
@@ -63,6 +72,9 @@ function findingEntry(f: DocDriftPromptFinding): string {
return [
`- \`${f.file_path}:${f.line_number}\` claims \`${f.target}\` exists`,
f.reason ? ` - Why flagged: ${f.reason}` : null,
+ f.suggestion
+ ? ` - Likely replacement: \`${f.suggestion}\`${basisSuffix(f.suggestion_basis)}. A lead, not a verdict: confirm it before editing.`
+ : null,
f.context ? ` - The line as written: \`${f.context.trim()}\`` : null,
f.raw && f.raw !== f.context ? ` - The reference itself: \`${f.raw}\`` : null,
trail ? ` - Section: ${trail.slice(SECTION_PREFIX.length)}` : null,
diff --git a/tests/unit/cli/test_doc_drift_check.py b/tests/unit/cli/test_doc_drift_check.py
new file mode 100644
index 000000000..655e9a7cc
--- /dev/null
+++ b/tests/unit/cli/test_doc_drift_check.py
@@ -0,0 +1,223 @@
+"""``repowise doc-drift --check``: the index-free CI gate and its exit codes."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from types import SimpleNamespace
+
+import pytest
+from click.testing import CliRunner
+
+from repowise.cli.commands import doc_drift_cmd
+from repowise.core.analysis.doc_drift.live import LiveTreeError
+from tests.unit.cli.test_format_json_rollout import _split_runner
+
+
+def _finding(**kw):
+ out = {
+ "file_path": kw.get("file_path", "docs/a.md"),
+ "line_number": kw.get("line_number", 3),
+ "kind": kw.get("kind", "path"),
+ "target": kw.get("target", "src/gone.py"),
+ "confidence": kw.get("confidence", 0.9),
+ "origin": "path_no_candidate",
+ "reason": "Document names src/gone.py, which no longer exists.",
+ "raw": "src/gone.py",
+ "context": "see src/gone.py",
+ "evidence": ["docs/a.md:3 states `src/gone.py`"],
+ }
+ if "suggestion" in kw:
+ out["suggestion"] = kw["suggestion"]
+ out["suggestion_basis"] = "package_split"
+ return out
+
+
+def _report():
+ return SimpleNamespace(documents_scanned=4, references_checked=20, suppressed=1)
+
+
+def _invoke(monkeypatch, tmp_path, findings, args=(), env=None, runner=None):
+ monkeypatch.setattr(doc_drift_cmd, "_repo_path", lambda *a, **k: tmp_path)
+ monkeypatch.setattr(
+ doc_drift_cmd, "_read_live", lambda root, **k: (_report(), list(findings))
+ )
+ return (runner or CliRunner()).invoke(
+ doc_drift_cmd.doc_drift_command, ["--check", *args], env=env or {}
+ )
+
+
+def test_gate_fails_on_a_high_confidence_finding(monkeypatch, tmp_path):
+ result = _invoke(monkeypatch, tmp_path, [_finding()])
+ assert result.exit_code == 1
+ assert "Gate failed" in result.output
+
+
+def test_gate_passes_below_the_threshold(monkeypatch, tmp_path):
+ result = _invoke(monkeypatch, tmp_path, [_finding(confidence=0.5)])
+ assert result.exit_code == 0
+ assert "Gate passed" in result.output
+
+
+def test_fail_on_confidence_is_honoured(monkeypatch, tmp_path):
+ findings = [_finding(confidence=0.5)]
+ result = _invoke(monkeypatch, tmp_path, findings, ["--fail-on-confidence", "0.4"])
+ assert result.exit_code == 1
+
+
+def test_not_a_git_repository_exits_two_with_a_json_document(monkeypatch, tmp_path):
+ monkeypatch.setattr(doc_drift_cmd, "_repo_path", lambda *a, **k: tmp_path)
+
+ def _raise(root, **k):
+ raise LiveTreeError("not a git repository")
+
+ monkeypatch.setattr(doc_drift_cmd, "_read_live", _raise)
+ result = CliRunner().invoke(
+ doc_drift_cmd.doc_drift_command, ["--check", "--format", "json"]
+ )
+ assert result.exit_code == 2
+ assert json.loads(result.output)["error"] == "not_a_git_repository"
+
+
+def test_json_carries_the_gate_and_the_denominators(monkeypatch, tmp_path):
+ result = _invoke(monkeypatch, tmp_path, [_finding()], ["--format", "json"])
+ payload = json.loads(result.output)
+ assert result.exit_code == 1
+ assert payload["gate"]["passed"] is False
+ assert payload["documents_scanned"] == 4
+ assert payload["suppressed"] == 1
+
+
+def test_baseline_round_trip_accepts_known_findings(monkeypatch, tmp_path):
+ baseline = tmp_path / "baseline.json"
+ findings = [_finding()]
+ wrote = _invoke(monkeypatch, tmp_path, findings, ["--write-baseline", str(baseline)])
+ assert wrote.exit_code == 0
+ assert baseline.exists()
+
+ # A line shift must not turn an accepted finding back into a new one.
+ shifted = [_finding(line_number=40)]
+ result = _invoke(monkeypatch, tmp_path, shifted, ["--baseline", str(baseline)])
+ assert result.exit_code == 0
+
+ fresh = [*shifted, _finding(target="src/other.py")]
+ result = _invoke(monkeypatch, tmp_path, fresh, ["--baseline", str(baseline)])
+ assert result.exit_code == 1
+
+
+def test_unreadable_baseline_exits_two(monkeypatch, tmp_path):
+ bad = tmp_path / "bad.json"
+ bad.write_text("{not json", encoding="utf-8")
+ result = _invoke(monkeypatch, tmp_path, [_finding()], ["--baseline", str(bad)])
+ assert result.exit_code == 2
+
+
+def test_unwritable_baseline_exits_two(monkeypatch, tmp_path):
+ target = tmp_path / "missing" / "baseline.json"
+ result = _invoke(monkeypatch, tmp_path, [_finding()], ["--write-baseline", str(target)])
+ assert result.exit_code == 2
+ assert not target.exists()
+
+
+def test_github_format_emits_an_error_command_when_it_cannot_evaluate(monkeypatch, tmp_path):
+ bad = tmp_path / "bad.json"
+ bad.write_text("{not json", encoding="utf-8")
+ result = _invoke(
+ monkeypatch, tmp_path, [_finding()], ["--baseline", str(bad), "--format", "github"],
+ runner=_split_runner(),
+ )
+ assert result.exit_code == 2
+ assert result.stdout.startswith("::error::")
+
+
+def test_min_confidence_above_fail_on_warns_on_stderr(monkeypatch, tmp_path):
+ args = ["--min-confidence", "0.9", "--fail-on-confidence", "0.7", "--format", "json"]
+ result = _invoke(
+ monkeypatch, tmp_path, [_finding(confidence=0.95)], args, runner=_split_runner()
+ )
+ assert "hidden from the gate" in result.stderr
+ assert json.loads(result.stdout)["gate"]["fail_on"] == 0.7
+
+
+def test_sarif_level_follows_the_gate_threshold(monkeypatch, tmp_path):
+ args = ["--format", "sarif", "--fail-on-confidence", "0.4"]
+ result = _invoke(monkeypatch, tmp_path, [_finding(confidence=0.5)], args)
+ assert json.loads(result.output)["runs"][0]["results"][0]["level"] == "error"
+
+
+def test_baseline_flags_require_check(monkeypatch, tmp_path):
+ monkeypatch.setattr(doc_drift_cmd, "_repo_path", lambda *a, **k: tmp_path)
+ result = CliRunner().invoke(
+ doc_drift_cmd.doc_drift_command, ["--baseline", str(tmp_path / "b.json")]
+ )
+ assert result.exit_code == 2
+ assert "require --check" in result.output
+
+
+def test_github_format_annotates_and_fills_the_step_summary(monkeypatch, tmp_path):
+ summary = tmp_path / "summary.md"
+ result = _invoke(
+ monkeypatch,
+ tmp_path,
+ [_finding(suggestion="src/gone/")],
+ ["--format", "github"],
+ env={"GITHUB_STEP_SUMMARY": str(summary)},
+ )
+ assert result.exit_code == 1
+ assert result.output.startswith("::error file=docs/a.md,line=3")
+ assert "src/gone/" in result.output
+ assert "docs/a.md" in summary.read_text(encoding="utf-8")
+
+
+def test_sarif_is_one_json_document(monkeypatch, tmp_path):
+ result = _invoke(monkeypatch, tmp_path, [_finding()], ["--format", "sarif"])
+ sarif = json.loads(result.output)
+ assert sarif["version"] == "2.1.0"
+ assert sarif["runs"][0]["results"][0]["locations"][0]["physicalLocation"][
+ "artifactLocation"
+ ]["uri"] == "docs/a.md"
+
+
+def test_document_filter_narrows_the_gate(monkeypatch, tmp_path):
+ findings = [_finding(), _finding(file_path=".github/b.md")]
+ result = _invoke(
+ monkeypatch, tmp_path, findings, ["--document", "./.github/b.md", "--format", "json"]
+ )
+ payload = json.loads(result.output)
+ assert [f["file_path"] for f in payload["findings"]] == [".github/b.md"]
+
+
+def test_table_shows_the_likely_replacement(monkeypatch, tmp_path):
+ result = _invoke(monkeypatch, tmp_path, [_finding(suggestion="src/gone/")])
+ assert "likely now: src/gone/" in result.output
+
+
[email protected](shutil.which("git") is None, reason="git not installed")
+def test_end_to_end_on_a_real_working_tree(tmp_path):
+ def git(*args):
+ subprocess.run(
+ ["git", "-C", str(tmp_path), "-c", "user.email=t@t", "-c", "user.name=t", *args],
+ check=True,
+ capture_output=True,
+ )
+
+ (tmp_path / "src" / "tools" / "cli").mkdir(parents=True)
+ (tmp_path / "src" / "tools" / "cli" / "__init__.py").write_text("", encoding="utf-8")
+ (tmp_path / "docs").mkdir()
+ (tmp_path / "docs" / "overview.md").write_text(
+ "The entry point is `src/tools/cli.py`.\n", encoding="utf-8"
+ )
+ git("init", "-q")
+ git("add", ".")
+ git("commit", "-qm", "init")
+
+ result = CliRunner().invoke(
+ doc_drift_cmd.doc_drift_command,
+ ["--check", "--no-workspace", "--format", "json", str(tmp_path)],
+ )
+ payload = json.loads(result.output)
+ assert result.exit_code == 1, result.output
+ (finding,) = payload["findings"]
+ assert finding["target"] == "src/tools/cli.py"
+ assert finding["suggestion"] == "src/tools/cli/"
diff --git a/tests/unit/cli/test_doc_drift_cmd.py b/tests/unit/cli/test_doc_drift_cmd.py
index 8fdb7bbab..aa13e0800 100644
--- a/tests/unit/cli/test_doc_drift_cmd.py
+++ b/tests/unit/cli/test_doc_drift_cmd.py
@@ -16,6 +16,7 @@ from sqlalchemy.exc import OperationalError
from repowise.cli.commands import doc_drift_cmd
from repowise.core.analysis.doc_drift.constants import DETECTION_BASIS
from repowise.core.persistence.crud import serialize_doc_drift_row
+from tests.unit.cli.test_format_json_rollout import _split_runner
class _Row:
@@ -32,6 +33,8 @@ class _Row:
self.evidence_json = kw.get("evidence_json", '["docs/a.md:7 states `src/gone.py`"]')
self.raw = kw.get("raw", "src/gone.py")
self.context = kw.get("context", "see src/gone.py")
+ self.suggestion = kw.get("suggestion")
+ self.suggestion_basis = kw.get("suggestion_basis")
def _invoke(monkeypatch, tmp_path, result, args=()):
@@ -104,6 +107,22 @@ def test_an_unreadable_index_refuses_rather_than_reporting_zero(
assert "findings" not in payload
[email protected]("fmt", ["sarif", "markdown", "github"])
+def test_a_refusal_under_a_machine_format_keeps_stdout_empty(monkeypatch, tmp_path, fmt):
+ """A refusal must not land in the file a CI step redirects stdout into."""
+ monkeypatch.setattr(doc_drift_cmd, "_repo_path", lambda *a, **k: tmp_path)
+
+ def _run(coro):
+ coro.close()
+ return doc_drift_cmd._NO_INDEX
+
+ monkeypatch.setattr(doc_drift_cmd, "run_async", _run)
+ result = _split_runner().invoke(doc_drift_cmd.doc_drift_command, ["--format", fmt])
+ assert result.exit_code == 1
+ assert result.stdout == ""
+ assert "No readable Repowise index" in result.stderr
+
+
def test_a_missing_drift_table_becomes_the_stale_sentinel(monkeypatch, tmp_path):
"""An index older than the drift table makes the read raise, not return [].
diff --git a/tests/unit/doc_drift/test_analyzer.py b/tests/unit/doc_drift/test_analyzer.py
index 7f4fe1d73..d0cdecc2c 100644
--- a/tests/unit/doc_drift/test_analyzer.py
+++ b/tests/unit/doc_drift/test_analyzer.py
@@ -211,3 +211,31 @@ def test_summarize_confidence_buckets_are_exhaustive():
summary = summarize_confidence(findings)
assert summary == {"high": 2, "medium": 1, "low": 1}
assert sum(summary.values()) == len(findings)
+
+
+# ---------------------------------------------------------------------------
+# Working-tree probe and opaque directories
+# ---------------------------------------------------------------------------
+
+
+def test_disk_probe_is_case_exact(tmp_path):
+ (tmp_path / "src").mkdir()
+ (tmp_path / "src" / "fixture.json").write_text("{}")
+ doc = "See `src/fixture.json` and `src/Fixture.json`.\n"
+ source_map = {"docs/a.md": doc.encode(), "src/app.json": b""}
+ report = DocDriftAnalyzer(
+ "repo", source_map=source_map, repo_root=tmp_path, rename_lookup=lambda _p: {}
+ ).analyze()
+ # A case-insensitive filesystem would call the second uncheckable locally
+ # and CI on Linux would call it missing; the probe answers as Linux does.
+ assert [f.target for f in report.findings] == ["src/Fixture.json"]
+
+
+def test_reference_inside_a_submodule_is_uncheckable():
+ files = {"docs/a.md": "See `libs/sub/x.py` and `libs/gone.py`.\n", "libs/other.py": ""}
+ source_map = {k: v.encode() for k, v in files.items()}
+ report = DocDriftAnalyzer(
+ "repo", source_map=source_map, opaque_dirs=frozenset({"libs/sub"})
+ ).analyze()
+ assert [f.target for f in report.findings] == ["libs/gone.py"]
+ assert report.verdict_summary[DriftVerdict.UNCHECKABLE.value] == 1
diff --git a/tests/unit/doc_drift/test_baseline.py b/tests/unit/doc_drift/test_baseline.py
new file mode 100644
index 000000000..e6a62b369
--- /dev/null
+++ b/tests/unit/doc_drift/test_baseline.py
@@ -0,0 +1,98 @@
+"""The baseline file: round trip, deterministic bytes, and refusals."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from repowise.core.analysis.doc_drift.baseline import (
+ BaselineError,
+ build_baseline,
+ read_baseline,
+ write_baseline,
+)
+from repowise.core.analysis.doc_drift.gate import evaluate_gate
+from repowise.core.analysis.doc_drift.serialize import derive_doc_drift_fingerprint
+
+
+def _f(doc: str, kind: str, target: str, line: int = 1) -> dict:
+ return {
+ "file_path": doc,
+ "line_number": line,
+ "kind": kind,
+ "target": target,
+ "confidence": 0.9,
+ "origin": "path_no_candidate",
+ "reason": "r",
+ "raw": target,
+ "context": "",
+ }
+
+
+FINDINGS = [
+ _f("docs/z.md", "path", "b.py"),
+ _f("docs/a.md", "path", "ü.py"),
+ _f("docs/a.md", "anchor", "README.md#x"),
+ _f("docs/a.md", "path", "ü.py", line=9), # same fingerprint, other line
+]
+
+
+def test_round_trip_accepts_what_it_wrote(tmp_path):
+ path = tmp_path / "drift-baseline.json"
+ assert write_baseline(path, FINDINGS) == 3
+ accepted = read_baseline(path)
+ assert accepted == {
+ derive_doc_drift_fingerprint(f["file_path"], f["kind"], f["target"])
+ for f in FINDINGS
+ }
+ assert evaluate_gate(FINDINGS, baseline=accepted).passed
+
+
+def test_entries_are_sorted_and_bytes_deterministic(tmp_path):
+ a, b = tmp_path / "a.json", tmp_path / "b.json"
+ write_baseline(a, FINDINGS)
+ write_baseline(b, list(reversed(FINDINGS)))
+ assert a.read_bytes() == b.read_bytes()
+ text = a.read_text(encoding="utf-8")
+ assert text.endswith("}\n") and "ü.py" in text
+ doc = json.loads(text)
+ assert doc["version"] == 1 and doc["basis"]
+ keys = [(e["file_path"], e["kind"], e["target"]) for e in doc["entries"]]
+ assert keys == sorted(keys)
+ assert set(doc["entries"][0]) == {"fingerprint", "file_path", "kind", "target"}
+
+
+def test_empty_baseline_is_valid(tmp_path):
+ path = tmp_path / "b.json"
+ assert write_baseline(path, []) == 0
+ assert read_baseline(path) == frozenset()
+ assert build_baseline([])["entries"] == []
+
+
+ ("content", "needle"),
+ [
+ ("not json", "not valid JSON"),
+ ("[1, 2]", "JSON object"),
+ ('{"version": 2, "entries": []}', "version 2"),
+ ('{"entries": []}', "version None"),
+ ('{"version": 1}', "entries"),
+ ('{"version": 1, "entries": [{"file_path": "a"}]}', "entry 0"),
+ ('{"version": 1, "entries": ["x"]}', "entry 0"),
+ ],
+)
+def test_invalid_files_say_what_is_wrong(tmp_path, content, needle):
+ path = tmp_path / "b.json"
+ path.write_text(content, encoding="utf-8")
+ with pytest.raises(BaselineError, match=needle):
+ read_baseline(path)
+
+
+def test_missing_file_is_a_baseline_error(tmp_path):
+ with pytest.raises(BaselineError, match="cannot read"):
+ read_baseline(tmp_path / "nope.json")
+
+
+def test_baseline_error_is_a_value_error():
+ assert issubclass(BaselineError, ValueError)
diff --git a/tests/unit/doc_drift/test_gate.py b/tests/unit/doc_drift/test_gate.py
new file mode 100644
index 000000000..f8f0ee1b4
--- /dev/null
+++ b/tests/unit/doc_drift/test_gate.py
@@ -0,0 +1,92 @@
+"""The CI gate: threshold, baseline, and the shape it hands a caller."""
+
+from __future__ import annotations
+
+import json
+
+from repowise.core.analysis.doc_drift.constants import HIGH_CONFIDENCE_THRESHOLD
+from repowise.core.analysis.doc_drift.gate import GateResult, evaluate_gate
+from repowise.core.analysis.doc_drift.serialize import derive_doc_drift_fingerprint
+
+
+def _f(target: str, confidence: float, *, doc: str = "docs/a.md", line: int = 3) -> dict:
+ return {
+ "file_path": doc,
+ "line_number": line,
+ "kind": "path",
+ "target": target,
+ "confidence": confidence,
+ "origin": "path_no_candidate",
+ "reason": f"Document names {target}, which no longer exists.",
+ "raw": target,
+ "context": "",
+ }
+
+
+def test_default_threshold_is_the_high_tier():
+ result = evaluate_gate([_f("a.py", 0.9), _f("b.py", 0.5)])
+ assert result.fail_on == HIGH_CONFIDENCE_THRESHOLD
+ assert not result.passed
+ assert [f["target"] for f in result.failing] == ["a.py"]
+ assert result.below_threshold == 1
+
+
+def test_threshold_is_inclusive():
+ assert not evaluate_gate([_f("a.py", 0.7)], fail_on=0.7).passed
+ assert evaluate_gate([_f("a.py", 0.69)], fail_on=0.7).passed
+
+
+def test_no_findings_passes():
+ result = evaluate_gate([])
+ assert result.passed
+ assert result.failing == [] and result.baselined == [] and result.below_threshold == 0
+
+
+def test_baseline_accepts_a_finding_whatever_its_line():
+ fp = derive_doc_drift_fingerprint("docs/a.md", "path", "a.py")
+ result = evaluate_gate(
+ [_f("a.py", 0.9, line=40), _f("b.py", 0.9)], baseline=frozenset({fp})
+ )
+ assert [f["target"] for f in result.baselined] == ["a.py"]
+ assert [f["target"] for f in result.failing] == ["b.py"]
+
+
+def test_fully_baselined_run_passes():
+ fp = derive_doc_drift_fingerprint("docs/a.md", "path", "a.py")
+ assert evaluate_gate([_f("a.py", 0.9)], baseline=frozenset({fp})).passed
+
+
+def test_a_carried_fingerprint_is_used_as_is():
+ row = _f("a.py", 0.9) | {"fingerprint": "custom"}
+ assert evaluate_gate([row], baseline=frozenset({"custom"})).passed
+
+
+def test_input_dicts_are_not_mutated():
+ row = _f("a.py", 0.9)
+ evaluate_gate([row])
+ assert "fingerprint" not in row
+
+
+def test_to_dict_is_stable_json():
+ result = evaluate_gate([_f("a.py", 0.9), _f("b.py", 0.1)], fail_on=0.5)
+ out = result.to_dict()
+ assert out == {
+ "passed": False,
+ "fail_on": 0.5,
+ "failing_count": 1,
+ "baselined_count": 0,
+ "below_threshold_count": 1,
+ "failing": [result.failing[0]],
+ }
+ assert out["failing"][0]["fingerprint"]
+ json.dumps(out)
+
+
+def test_result_is_frozen():
+ result = evaluate_gate([])
+ assert isinstance(result, GateResult)
+ try:
+ result.passed = False # type: ignore[misc]
+ except AttributeError:
+ return
+ raise AssertionError("GateResult must be frozen")
diff --git a/tests/unit/doc_drift/test_live.py b/tests/unit/doc_drift/test_live.py
new file mode 100644
index 000000000..72a6aeef5
--- /dev/null
+++ b/tests/unit/doc_drift/test_live.py
@@ -0,0 +1,111 @@
+"""Index-free inputs from a real git working tree."""
+
+from __future__ import annotations
+
+import inspect
+import shutil
+import subprocess
+
+import pytest
+
+from repowise.core.analysis.doc_drift.analyzer import DocDriftAnalyzer
+from repowise.core.analysis.doc_drift.constants import MAX_DOC_BYTES
+from repowise.core.analysis.doc_drift.live import (
+ LiveTreeError,
+ collect_live_inputs,
+ run_live,
+)
+
+pytestmark = pytest.mark.skipif(shutil.which("git") is None, reason="git not installed")
+
+
+def _git(root, *args):
+ subprocess.run(
+ ["git", "-C", str(root), "-c", "user.email=t@t", "-c", "user.name=t", *args],
+ check=True,
+ capture_output=True,
+ )
+
+
+def repo(tmp_path):
+ files = {
+ "src/present.py": "",
+ "docs/overview.md": "See `src/present.py` and `src/gone.py`.\n",
+ "docs/private/notes.md": "See `src/also_gone.py`.\n",
+ "Makefile": "build:\n\techo hi\n",
+ ".repowiseIgnore": "docs/private/\n",
+ "docs/big.md": "x" * (MAX_DOC_BYTES + 1),
+ "src/deleted.py": "",
+ }
+ for rel, text in files.items():
+ path = tmp_path / rel
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(text, encoding="utf-8")
+ _git(tmp_path, "init", "-q")
+ _git(tmp_path, "add", ".")
+ _git(tmp_path, "commit", "-qm", "init")
+ (tmp_path / "src/deleted.py").unlink()
+ (tmp_path / "docs/new.md").write_text("Run `make build`.\n", encoding="utf-8")
+ return tmp_path
+
+
+def test_collect_reads_only_what_the_analyzer_needs(repo):
+ inputs = collect_live_inputs(repo)
+ assert set(inputs.source_map) == {"docs/overview.md", "docs/new.md", "Makefile"}
+ # Untracked files count; files deleted from the working tree do not; an
+ # ignored document still exists for resolution.
+ assert "docs/new.md" in inputs.tracked_paths
+ assert "src/deleted.py" not in inputs.tracked_paths
+ assert "docs/private/notes.md" in inputs.tracked_paths
+ assert "src/present.py" in inputs.tracked_paths
+
+
+def test_findings_from_the_working_tree(repo):
+ inputs = collect_live_inputs(repo)
+ report = DocDriftAnalyzer(
+ source_map=inputs.source_map, tracked_paths=inputs.tracked_paths
+ ).analyze()
+ assert [(f.file_path, f.target) for f in report.findings] == [
+ ("docs/overview.md", "src/gone.py")
+ ]
+ assert report.documents_scanned == 2
+
+
+ "repo_root" not in inspect.signature(DocDriftAnalyzer.__init__).parameters,
+ reason="DocDriftAnalyzer does not accept repo_root yet",
+)
+def test_run_live_end_to_end(repo):
+ report = run_live(repo)
+ assert [(f.file_path, f.target) for f in report.findings] == [
+ ("docs/overview.md", "src/gone.py")
+ ]
+
+
+def test_not_a_git_repo_raises(tmp_path):
+ with pytest.raises(LiveTreeError):
+ collect_live_inputs(tmp_path)
+
+
+def test_a_subdirectory_resolves_to_the_repository_root(repo):
+ inputs = collect_live_inputs(repo / "docs")
+ assert inputs.root.resolve() == repo.resolve()
+ assert "src/present.py" in inputs.tracked_paths
+ assert "docs/overview.md" in inputs.source_map
+ report = run_live(repo / "docs")
+ assert [(f.file_path, f.target) for f in report.findings] == [
+ ("docs/overview.md", "src/gone.py")
+ ]
+
+
+def test_gitlinks_become_opaque_directories(repo):
+ sha = subprocess.run(
+ ["git", "-C", str(repo), "rev-parse", "HEAD"], capture_output=True, text=True, check=True
+ ).stdout.strip()
+ _git(repo, "update-index", "--add", "--cacheinfo", f"160000,{sha},src/vendored")
+ (repo / "docs/sub.md").write_text("See `src/vendored/lib.py`.\n", encoding="utf-8")
+ inputs = collect_live_inputs(repo)
+ assert inputs.opaque_dirs == frozenset({"src/vendored"})
+ report = run_live(repo)
+ assert "src/vendored/lib.py" not in {f.target for f in report.findings}
diff --git a/tests/unit/doc_drift/test_render.py b/tests/unit/doc_drift/test_render.py
new file mode 100644
index 000000000..ec028bd76
--- /dev/null
+++ b/tests/unit/doc_drift/test_render.py
@@ -0,0 +1,188 @@
+"""CI renderings: markdown summary, GitHub annotations, SARIF."""
+
+from __future__ import annotations
+
+import json
+
+from repowise.core.analysis.doc_drift.constants import DETECTION_BASIS
+from repowise.core.analysis.doc_drift.gate import evaluate_gate
+from repowise.core.analysis.doc_drift.render import (
+ SARIF_FINGERPRINT_KEY,
+ render_github_annotations,
+ render_markdown,
+ render_sarif,
+)
+from repowise.core.analysis.doc_drift.serialize import derive_doc_drift_fingerprint
+from repowise.core.ci.github import ANNOTATION_LIMIT
+from repowise.core.ci.markdown import ROW_LIMIT
+
+
+def _f(
+ target: str,
+ confidence: float = 0.9,
+ *,
+ doc: str = "docs/a.md",
+ line: int = 3,
+ kind: str = "path",
+ reason: str | None = None,
+ suggestion: str = "",
+) -> dict:
+ out = {
+ "file_path": doc,
+ "line_number": line,
+ "kind": kind,
+ "target": target,
+ "confidence": confidence,
+ "origin": "path_no_candidate",
+ "reason": reason or f"Document names {target}, which no longer exists.",
+ "raw": target,
+ "context": "",
+ }
+ if suggestion:
+ out["suggestion"] = suggestion
+ out["suggestion_basis"] = "package_split"
+ return out
+
+
+# -- markdown ---------------------------------------------------------------
+
+
+def test_passing_markdown_is_short_and_says_so():
+ findings = [_f("a.py", 0.5)]
+ md = render_markdown(findings, gate=evaluate_gate(findings), documents_scanned=4)
+ assert md.startswith("**No documentation drift at or above 0.70.**")
+ assert "|" not in md
+ assert "4 documents scanned" in md and "1 below the threshold" in md
+ assert DETECTION_BASIS in md
+
+
+def test_failing_markdown_verdict_first_then_table():
+ findings = [_f("b.py", doc="docs/z.md"), _f("a.py", line=9), _f("c.py", 0.4)]
+ md = render_markdown(findings, gate=evaluate_gate(findings), suppressed=2)
+ first = md.splitlines()[0]
+ assert first.startswith("**Documentation drift: 2 findings fail the gate**")
+ assert "document" in first.lower()
+ assert "2 references suppressed inline" in md
+ rows = [line for line in md.splitlines() if line.startswith("| docs/")]
+ # Grouped by document, and the below-threshold finding stays out.
+ assert rows[0].startswith("| docs/a.md:9 ") and rows[1].startswith("| docs/z.md:3 ")
+ assert len(rows) == 2
+
+
+def test_markdown_escapes_cells_and_shows_suggestion():
+ findings = [_f("a|b`c.py", suggestion="pkg/a/")]
+ md = render_markdown(findings, gate=evaluate_gate(findings))
+ row = next(line for line in md.splitlines() if line.startswith("| docs/"))
+ assert "a\\|b\\`c.py" in row
+ assert "| pkg/a/ |" in row
+
+
+def test_markdown_caps_rows():
+ findings = [_f(f"f{i:02}.py", line=i + 1) for i in range(ROW_LIMIT + 5)]
+ md = render_markdown(findings, gate=evaluate_gate(findings))
+ rows = [line for line in md.splitlines() if line.startswith("| docs/")]
+ assert len(rows) == ROW_LIMIT
+ assert "and 5 more findings." in md
+
+
+def test_markdown_without_gate_lists_everything():
+ assert render_markdown([], gate=None).startswith("**No documentation drift found.**")
+ md = render_markdown([_f("a.py", 0.4)], gate=None)
+ assert md.startswith("**Documentation drift: 1 finding.**")
+ assert "| docs/a.md:3 " in md
+
+
+def test_markdown_reports_baselined_count():
+ findings = [_f("a.py")]
+ fp = derive_doc_drift_fingerprint("docs/a.md", "path", "a.py")
+ md = render_markdown(findings, gate=evaluate_gate(findings, baseline=frozenset({fp})))
+ assert md.startswith("**No documentation drift")
+ assert "1 accepted by the baseline" in md
+
+
+# -- annotations ------------------------------------------------------------
+
+
+def test_annotations_errors_first_and_escaped():
+ findings = [
+ _f("low.py", 0.4, doc="docs/a.md"),
+ _f("x.py", reason="50% broken\nnext", doc="docs/a,b:c.md", line=7, suggestion="y/"),
+ ]
+ lines = render_github_annotations(findings, gate=evaluate_gate(findings))
+ assert lines[0] == (
+ "::error file=docs/a%2Cb%3Ac.md,line=7,title=Doc drift (path)"
+ "::50%25 broken%0Anext Likely now: y/."
+ )
+ assert lines[1].startswith("::warning file=docs/a.md,line=3,")
+ assert len(lines) == 2
+
+
+def test_baselined_findings_are_not_annotated():
+ findings = [_f("a.py")]
+ fp = derive_doc_drift_fingerprint("docs/a.md", "path", "a.py")
+ assert render_github_annotations(
+ findings, gate=evaluate_gate(findings, baseline=frozenset({fp}))
+ ) == []
+
+
+def test_annotations_are_capped_with_errors_kept_and_the_overflow_counted():
+ findings = [_f(f"w{i}.py", 0.4, line=i + 1) for i in range(60)]
+ findings.append(_f("err.py", doc="docs/z.md"))
+ lines = render_github_annotations(findings, gate=evaluate_gate(findings))
+ assert len(lines) == ANNOTATION_LIMIT + 1
+ assert lines[0].startswith("::error ")
+ assert lines[-1].startswith("::notice::51 more documentation drift findings")
+
+
+# -- SARIF ------------------------------------------------------------------
+
+
+def test_sarif_required_fields():
+ findings = [_f("a.py", suggestion="pkg/a/"), _f("R.md#x", 0.5, kind="anchor")]
+ sarif = render_sarif(findings, tool_version="1.2.3")
+ assert sarif["$schema"] == "https://json.schemastore.org/sarif-2.1.0.json"
+ assert sarif["version"] == "2.1.0"
+ (run,) = sarif["runs"]
+ driver = run["tool"]["driver"]
+ assert driver["name"] == "repowise-doc-drift"
+ assert driver["version"] == "1.2.3"
+ assert driver["informationUri"] == "https://repowise.dev"
+ assert [r["id"] for r in driver["rules"]] == ["path", "link", "anchor", "command"]
+ assert all(DETECTION_BASIS in r["fullDescription"]["text"] for r in driver["rules"])
+
+ by_rule = {r["ruleId"]: r for r in run["results"]}
+ path = by_rule["path"]
+ assert path["level"] == "error"
+ assert path["message"]["text"].endswith("Likely now: pkg/a/.")
+ loc = path["locations"][0]["physicalLocation"]
+ assert loc["artifactLocation"] == {"uri": "docs/a.md", "uriBaseId": "%SRCROOT%"}
+ assert loc["region"] == {"startLine": 3}
+ assert path["partialFingerprints"] == {
+ SARIF_FINGERPRINT_KEY: derive_doc_drift_fingerprint("docs/a.md", "path", "a.py")
+ }
+ assert path["properties"]["suggestion"] == "pkg/a/"
+ assert by_rule["anchor"]["level"] == "warning"
+ assert "suggestion" not in by_rule["anchor"]["properties"]
+
+
+def test_sarif_level_follows_fail_on_and_uri_is_percent_encoded():
+ findings = [_f("a.py", 0.5, doc="docs/my notes#1.md")]
+ (result,) = render_sarif(findings, tool_version="x", fail_on=0.4)["runs"][0]["results"]
+ assert result["level"] == "error"
+ uri = result["locations"][0]["physicalLocation"]["artifactLocation"]["uri"]
+ assert uri == "docs/my%20notes%231.md"
+ (default,) = render_sarif(findings, tool_version="x")["runs"][0]["results"]
+ assert default["level"] == "warning"
+
+
+def test_sarif_is_deterministic():
+ findings = [_f("b.py", doc="docs/z.md"), _f("a.py"), _f("c.py", line=1)]
+ one = json.dumps(render_sarif(findings, tool_version="x"), sort_keys=True)
+ two = json.dumps(render_sarif(list(reversed(findings)), tool_version="x"), sort_keys=True)
+ assert one == two
+ uris = [
+ (r["locations"][0]["physicalLocation"]["artifactLocation"]["uri"],
+ r["locations"][0]["physicalLocation"]["region"]["startLine"])
+ for r in render_sarif(findings, tool_version="x")["runs"][0]["results"]
+ ]
+ assert uris == [("docs/a.md", 1), ("docs/a.md", 3), ("docs/z.md", 3)]
diff --git a/tests/unit/doc_drift/test_resolver.py b/tests/unit/doc_drift/test_resolver.py
index 99c06fd9c..b337751ee 100644
--- a/tests/unit/doc_drift/test_resolver.py
+++ b/tests/unit/doc_drift/test_resolver.py
@@ -246,3 +246,36 @@ def test_end_to_end_on_a_small_document():
assert (DriftKind.PATH, DriftVerdict.MISSING) in verdicts
assert (DriftKind.COMMAND, DriftVerdict.RESOLVED) in verdicts
assert (DriftKind.ANCHOR, DriftVerdict.RESOLVED) in verdicts
+
+
+# ---------------------------------------------------------------------------
+# The on-disk probe: present in the tree, absent from the index
+# ---------------------------------------------------------------------------
+
+
+def _probed_index(present: set[str], asked: list[str] | None = None) -> RepoIndex:
+ def on_disk(rel: str) -> bool:
+ if asked is not None:
+ asked.append(rel)
+ return rel in present
+
+ return RepoIndex.build(TREE, {}, {}, on_disk=on_disk)
+
+
+def test_unindexed_file_on_disk_is_uncheckable_not_missing():
+ res = resolve(_probed_index({"src/util/fixture.py"}), _ref("src/util/fixture.py"))
+ assert res.verdict is DriftVerdict.UNCHECKABLE
+ assert res.detail == "outside-index"
+
+
+def test_probe_that_finds_nothing_leaves_the_finding():
+ res = resolve(_probed_index(set()), _ref("src/util/gone.py"))
+ assert res.verdict is DriftVerdict.MISSING
+
+
+def test_probe_is_asked_only_about_would_be_misses():
+ asked: list[str] = []
+ idx = _probed_index(set(), asked)
+ resolve(idx, _ref("src/app.py"))
+ resolve(idx, _ref("CLAUDE.md"))
+ assert asked == []
diff --git a/tests/unit/doc_drift/test_serialize.py b/tests/unit/doc_drift/test_serialize.py
index a6c635f71..363125e77 100644
--- a/tests/unit/doc_drift/test_serialize.py
+++ b/tests/unit/doc_drift/test_serialize.py
@@ -24,8 +24,11 @@ from repowise.core.analysis.doc_drift.models import (
)
from repowise.core.analysis.doc_drift.serialize import (
collapse_reference_sites,
+ derive_doc_drift_fingerprint,
derive_doc_drift_id,
documents_with_drift,
+ finding_dict,
+ fingerprint_of,
serialize_finding,
serialize_reference,
serialize_report,
@@ -69,6 +72,8 @@ def _row_from(finding: DocDriftFindingData) -> DocDriftFinding:
evidence_json=json.dumps(list(finding.evidence)),
raw=finding.raw,
context=finding.context,
+ suggestion=finding.suggestion or None,
+ suggestion_basis=finding.suggestion_basis or None,
)
@@ -85,6 +90,41 @@ def test_the_evidence_toggle_agrees_on_both_paths():
assert "evidence" not in serialize_finding(finding, evidence=False)
+def test_a_suggestion_round_trips_identically_on_both_paths():
+ finding = _finding(suggestion="src/auth/", suggestion_basis="package_split")
+ served = serialize_finding(finding)
+ assert served == serialize_doc_drift_row(_row_from(finding))
+ assert served["suggestion"] == "src/auth/"
+ assert served["suggestion_basis"] == "package_split"
+
+
+def test_no_suggestion_means_no_keys_not_nulls():
+ """MCP get_health serves these dicts; most findings must not grow noise."""
+ assert "suggestion" not in serialize_finding(_finding())
+ assert "suggestion_basis" not in serialize_doc_drift_row(_row_from(_finding()))
+ served = finding_dict(
+ file_path="docs/a.md", kind="path", line_number=1, target="x",
+ confidence=0.9, origin="o", reason="r", raw="x", context="c",
+ suggestion="", suggestion_basis="",
+ )
+ assert "suggestion" not in served and "fingerprint" not in served
+
+
+def test_a_suggestion_with_a_null_basis_omits_the_basis():
+ served = finding_dict(
+ file_path="docs/a.md", kind="path", line_number=1, target="x",
+ confidence=0.9, origin="o", reason="r", raw="x", context="c",
+ suggestion="y/", suggestion_basis=None,
+ )
+ assert served["suggestion"] == "y/" and "suggestion_basis" not in served
+
+
+def test_fingerprint_of_prefers_a_carried_fingerprint():
+ row = {"file_path": "docs/a.md", "kind": "path", "target": "x"}
+ assert fingerprint_of(row) == derive_doc_drift_fingerprint("docs/a.md", "path", "x")
+ assert fingerprint_of({**row, "fingerprint": "abc"}) == "abc"
+
+
def test_a_report_reference_and_its_stored_row_serialize_identically():
reference = ResolvedDocReference(
doc_path="docs/architecture.md",
@@ -261,10 +301,11 @@ class TestSerializeReport:
assert [r["document"] for r in rows] == ["docs/a.md", "docs/b.md"]
def test_the_findings_are_the_same_dicts_a_store_would_serve(self):
- """Identical but for the id, which no store column holds."""
+ """Identical but for the id and fingerprint, which no store column holds."""
report = self._report()
payload = serialize_report(report)
- served = [{k: v for k, v in f.items() if k != "id"} for f in payload["findings"]]
+ minted = {"id", "fingerprint"}
+ served = [{k: v for k, v in f.items() if k not in minted} for f in payload["findings"]]
assert served == [
serialize_doc_drift_row(_row_from(f)) for f in report.findings
]
@@ -279,6 +320,20 @@ class TestSerializeReport:
for f in report.findings
]
+ def test_every_finding_carries_a_line_independent_fingerprint(self):
+ report = self._report()
+ payload = serialize_report(report)
+ assert [f["fingerprint"] for f in payload["findings"]] == [
+ derive_doc_drift_fingerprint(f.file_path, f.kind, f.target)
+ for f in report.findings
+ ]
+
+ def test_the_suppressed_count_survives_serialization(self):
+ report = self._report()
+ assert serialize_report(report)["suppressed"] == 0
+ report.suppressed = 3
+ assert serialize_report(report)["suppressed"] == 3
+
def test_the_uncheckable_denominator_survives_serialization(self):
"""The count that keeps the detector honest about its own coverage."""
payload = serialize_report(self._report())
diff --git a/tests/unit/doc_drift/test_suggest.py b/tests/unit/doc_drift/test_suggest.py
new file mode 100644
index 000000000..68f687390
--- /dev/null
+++ b/tests/unit/doc_drift/test_suggest.py
@@ -0,0 +1,317 @@
+"""Suggested replacements: each strategy fires only on a unique answer."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from repowise.core.analysis.doc_drift import DocDriftAnalyzer
+from repowise.core.analysis.doc_drift.models import DocReference, DriftKind, DriftVerdict
+from repowise.core.analysis.doc_drift.resolver import RepoIndex, resolve
+from repowise.core.analysis.doc_drift.suggest import (
+ git_renames,
+ suggest_all,
+ unique_close_match,
+)
+
+TREE = frozenset(
+ {
+ "README.md",
+ "docs/guide.md",
+ "src/core/ingestion/indexer/__init__.py",
+ "src/core/ingestion/indexer/walk.py",
+ "src/cli/commands/health_cmd/__init__.py",
+ "src/new/moved.py",
+ }
+)
+
+
+def _index(tree=TREE, docs=None, manifests=None) -> RepoIndex:
+ return RepoIndex.build(tree, docs or {}, manifests or {})
+
+
+def _miss(idx: RepoIndex, target: str, kind=DriftKind.PATH, doc="docs/guide.md", raw=None):
+ ref = DocReference(kind, raw or target, target, doc, 1, "ctx")
+ res = resolve(idx, ref)
+ assert res.verdict is DriftVerdict.MISSING, res.detail
+ return res
+
+
+# ---------------------------------------------------------------------------
+# package_split
+# ---------------------------------------------------------------------------
+
+
+def test_module_that_became_a_package():
+ idx = _index()
+ res = _miss(idx, "src/cli/commands/health_cmd.py")
+ assert suggest_all([res], idx) == [("src/cli/commands/health_cmd/", "package_split")]
+
+
+def test_package_that_also_moved_is_found_by_its_last_two_segments():
+ idx = _index()
+ res = _miss(idx, "src/ingestion/indexer.py")
+ assert suggest_all([res], idx) == [("src/core/ingestion/indexer/", "package_split")]
+
+
+def test_moved_package_with_two_candidates_gets_nothing():
+ idx = _index(TREE | {"src/other/ingestion/indexer/x.py"})
+ res = _miss(idx, "src/ingestion/indexer.py")
+ assert suggest_all([res], idx) == [("", "")]
+
+
+def test_relative_link_is_suggested_in_the_form_the_document_wrote():
+ tree = TREE | {"docs/api/__init__.md", "docs/api/intro.md"}
+ idx = _index(tree)
+ ref = DocReference(DriftKind.LINK, "api.md", "api.md", "docs/guide.md", 1, "ctx")
+ # Unanchored, so the resolver never reports it; the strategy still honours
+ # the relative join for anchored links written inside a subtree.
+ res = resolve(idx, ref)
+ assert res.verdict is DriftVerdict.UNCHECKABLE
+ missing = type(res)(ref, DriftVerdict.MISSING, "no-candidate", "path_no_candidate")
+ assert suggest_all([missing], idx) == [("api/", "package_split")]
+
+
+# ---------------------------------------------------------------------------
+# git_rename
+# ---------------------------------------------------------------------------
+
+
+class _Lookup:
+ def __init__(self, mapping: dict[str, str]) -> None:
+ self.mapping = mapping
+ self.calls: list[list[str]] = []
+
+ def __call__(self, paths):
+ self.calls.append(list(paths))
+ return self.mapping
+
+
+def test_rename_to_a_path_that_exists():
+ idx = _index()
+ lookup = _Lookup({"src/old/place.py": "src/new/moved.py"})
+ res = _miss(idx, "src/old/place.py")
+ assert suggest_all([res], idx, rename_lookup=lookup) == [("src/new/moved.py", "git_rename")]
+
+
+def test_rename_of_a_doc_relative_link_is_written_back_relative():
+ tree = TREE | {"packages/core/README.md", "packages/core/src/new.py"}
+ idx = _index(tree)
+ ref = DocReference(DriftKind.LINK, "src/old.py", "src/old.py", "packages/core/README.md", 1, "")
+ res = type(resolve(idx, ref))(ref, DriftVerdict.MISSING, "no-candidate", "path_no_candidate")
+ lookup = _Lookup({"packages/core/src/old.py": "packages/core/src/new.py"})
+ assert suggest_all([res], idx, rename_lookup=lookup) == [("src/new.py", "git_rename")]
+ assert lookup.calls == [["packages/core/src/old.py", "src/old.py"]]
+
+
+def test_moved_package_found_through_the_relative_form_is_written_relative():
+ tree = TREE | {"packages/core/README.md", "packages/core/src/x/ingest/walker/a.py"}
+ idx = _index(tree)
+ raw = "lib/ingest/walker.py"
+ ref = DocReference(DriftKind.LINK, raw, raw, "packages/core/README.md", 1, "")
+ res = type(resolve(idx, ref))(ref, DriftVerdict.MISSING, "no-candidate", "path_no_candidate")
+ assert suggest_all([res], idx) == [("src/x/ingest/walker/", "package_split")]
+
+
+def test_rename_to_a_path_gone_since_gets_nothing_unless_on_disk():
+ idx = _index()
+ lookup = _Lookup({"src/old/place.py": "src/gone/place.py"})
+ res = _miss(idx, "src/old/place.py")
+ assert suggest_all([res], idx, rename_lookup=lookup) == [("", "")]
+ on_disk = {"src/gone/place.py"}.__contains__
+ assert suggest_all([res], idx, rename_lookup=lookup, on_disk=on_disk) == [
+ ("src/gone/place.py", "git_rename")
+ ]
+
+
+def test_rename_lookup_is_called_once_and_only_for_unanswered_path_misses():
+ idx = _index()
+ lookup = _Lookup({})
+ misses = [
+ _miss(idx, "src/cli/commands/health_cmd.py"), # package_split answers it
+ _miss(idx, "src/old/a.py"),
+ _miss(idx, "src/old/b.py"),
+ _miss(idx, "src/old/a.py"),
+ ]
+ suggest_all(misses, idx, rename_lookup=lookup)
+ # Each target as written and joined relative to its document.
+ assert lookup.calls == [
+ ["docs/src/old/a.py", "docs/src/old/b.py", "src/old/a.py", "src/old/b.py"]
+ ]
+
+
+def test_no_path_misses_means_no_lookup():
+ idx = _index()
+ lookup = _Lookup({})
+ res = _miss(idx, "src/cli/commands/health_cmd.py")
+ suggest_all([res], idx, rename_lookup=lookup)
+ assert lookup.calls == []
+
+
+def test_a_failing_lookup_never_fails_the_pass():
+ def boom(_paths):
+ raise RuntimeError("no git")
+
+ idx = _index()
+ res = _miss(idx, "src/old/a.py")
+ assert suggest_all([res], idx, rename_lookup=boom) == [("", "")]
+
+
+# ---------------------------------------------------------------------------
+# similar_heading / similar_target
+# ---------------------------------------------------------------------------
+
+
+def test_renamed_heading_suggests_the_close_slug_as_written():
+ readme = "# Title\n\n## Quickstart in five minutes\n\n## Architecture\n"
+ idx = _index(docs={"README.md": readme})
+ frag = "quickstart-in-5-minutes"
+ res = _miss(idx, f"README.md#{frag}", DriftKind.ANCHOR, raw=f"../README.md#{frag}")
+ assert suggest_all([res], idx) == [
+ ("../README.md#quickstart-in-five-minutes", "similar_heading")
+ ]
+
+
+def test_same_document_anchor_keeps_the_bare_fragment():
+ doc = "# Guide\n\n## Optional code generation\n\nSee [below](#opt-in-code-generation).\n"
+ idx = _index(docs={"docs/guide.md": doc})
+ frag = "opt-in-code-generation"
+ res = _miss(idx, f"docs/guide.md#{frag}", DriftKind.ANCHOR, raw=f"#{frag}")
+ assert suggest_all([res], idx) == [("#optional-code-generation", "similar_heading")]
+
+
+def test_near_tie_between_headings_gets_nothing():
+ readme = "## Setup step one\n\n## Setup step two\n"
+ idx = _index(docs={"README.md": readme})
+ res = _miss(idx, "README.md#setup-step-c", DriftKind.ANCHOR)
+ assert suggest_all([res], idx) == [("", "")]
+
+
+def test_command_typo_keeps_the_runner_as_written():
+ manifests = {"package.json": '{"scripts": {"build": "x", "lint": "y"}}'}
+ idx = _index(TREE | {"package.json"}, manifests=manifests)
+ res = _miss(idx, "npm:biuld", DriftKind.COMMAND, raw="pnpm run biuld")
+ assert suggest_all([res], idx) == [("pnpm run build", "similar_target")]
+
+
+def test_make_target_with_no_close_match_gets_nothing():
+ idx = _index(TREE | {"Makefile"}, manifests={"Makefile": "test:\n\techo\n"})
+ res = _miss(idx, "make:deploy", DriftKind.COMMAND, raw="make deploy")
+ assert suggest_all([res], idx) == [("", "")]
+
+
+def test_unique_close_match_rejects_ties():
+ assert unique_close_match("tset", {"test"}) == "test"
+ assert unique_close_match("abcx", {"abcy", "abcz"}) == ""
+
+
+# ---------------------------------------------------------------------------
+# Analyzer wiring
+# ---------------------------------------------------------------------------
+
+
+def _analyzer(files: dict[str, str], **kw) -> DocDriftAnalyzer:
+ return DocDriftAnalyzer("repo", source_map={k: v.encode() for k, v in files.items()}, **kw)
+
+
+def test_suggestion_never_moves_confidence():
+ files = {"docs/a.md": "See `src/cli/commands/health_cmd.py`.\n", **{p: "" for p in TREE}}
+ report = _analyzer(files).analyze()
+ (finding,) = report.findings
+ assert finding.suggestion == "src/cli/commands/health_cmd/"
+ assert finding.suggestion_basis == "package_split"
+ assert finding.confidence == 0.90
+
+
+def test_hidden_findings_cost_no_rename_lookup():
+ lookup = _Lookup({})
+ files = {"docs/a.md": "See `src/old/a.py`.\n", "src/app.py": ""}
+ report = _analyzer(files, rename_lookup=lookup).analyze({"min_confidence": 0.99})
+ assert report.hidden_below_threshold == 1
+ assert lookup.calls == []
+
+
+def test_repo_root_defaults_the_disk_probe(tmp_path: Path):
+ (tmp_path / "src").mkdir()
+ (tmp_path / "src" / "fixture.json").write_text("{}")
+ files = {"docs/a.md": "See `src/fixture.json` and `src/gone.json`.\n", "src/app.json": ""}
+ report = _analyzer(files, repo_root=tmp_path, rename_lookup=_Lookup({})).analyze()
+ assert [f.target for f in report.findings] == ["src/gone.json"]
+ assert report.verdict_summary["uncheckable"] >= 1
+
+
+# ---------------------------------------------------------------------------
+# git_renames against a real repository
+# ---------------------------------------------------------------------------
+
+
+def _git(root: Path, *args: str) -> None:
+ subprocess.run(
+ ["git", "-C", str(root), "-c", "user.name=t", "-c", "user.email=t@t", *args],
+ check=True,
+ capture_output=True,
+ )
+
+
[email protected](shutil.which("git") is None, reason="git not installed")
+def test_git_renames_reads_history_and_follows_chains(tmp_path: Path):
+ _git(tmp_path, "init", "-q")
+ body = "\n".join(f"line {i}" for i in range(40))
+ (tmp_path / "a.py").write_text(body)
+ _git(tmp_path, "add", "-A")
+ _git(tmp_path, "commit", "-qm", "add")
+ _git(tmp_path, "mv", "a.py", "b.py")
+ _git(tmp_path, "commit", "-qm", "mv1")
+ (tmp_path / "pkg").mkdir()
+ _git(tmp_path, "mv", "b.py", "pkg/c.py")
+ _git(tmp_path, "commit", "-qm", "mv2")
+
+ assert git_renames(tmp_path, ["a.py", "never.py", "../out.py"]) == {"a.py": "pkg/c.py"}
+
+
[email protected](shutil.which("git") is None, reason="git not installed")
+def test_git_renames_never_joins_an_older_unrelated_rename(tmp_path: Path):
+ _git(tmp_path, "init", "-q")
+ (tmp_path / "b.py").write_text("\n".join(f"old {i}" for i in range(40)))
+ _git(tmp_path, "add", "-A")
+ _git(tmp_path, "commit", "-qm", "add b")
+ (tmp_path / "old").mkdir()
+ _git(tmp_path, "mv", "b.py", "old/c.py")
+ _git(tmp_path, "commit", "-qm", "b moves away")
+ (tmp_path / "a.py").write_text("\n".join(f"new {i}" for i in range(40)))
+ _git(tmp_path, "add", "-A")
+ _git(tmp_path, "commit", "-qm", "add a")
+ _git(tmp_path, "mv", "a.py", "b.py")
+ _git(tmp_path, "commit", "-qm", "a takes the name b")
+
+ # b.py -> old/c.py predates a.py arriving at b.py, so it is not a.py's hop.
+ assert git_renames(tmp_path, ["a.py"]) == {"a.py": "b.py"}
+ assert git_renames(tmp_path, ["b.py"]) == {"b.py": "old/c.py"}
+
+
[email protected](shutil.which("git") is None, reason="git not installed")
+def test_git_renames_stops_at_an_outright_deletion(tmp_path: Path):
+ _git(tmp_path, "init", "-q")
+ (tmp_path / "a.py").write_text("\n".join(f"line {i}" for i in range(40)))
+ _git(tmp_path, "add", "-A")
+ _git(tmp_path, "commit", "-qm", "add")
+ _git(tmp_path, "mv", "a.py", "b.py")
+ _git(tmp_path, "commit", "-qm", "mv")
+ _git(tmp_path, "rm", "-q", "b.py")
+ _git(tmp_path, "commit", "-qm", "rm")
+ (tmp_path / "b.py").write_text("\n".join(f"other {i}" for i in range(40)))
+ _git(tmp_path, "add", "-A")
+ _git(tmp_path, "commit", "-qm", "new b")
+ _git(tmp_path, "mv", "b.py", "d.py")
+ _git(tmp_path, "commit", "-qm", "new b moves")
+
+ # b.py was deleted after a.py arrived; the later b.py is another file.
+ assert git_renames(tmp_path, ["a.py"]) == {"a.py": "b.py"}
+
+
+def test_git_renames_outside_a_repository_is_empty(tmp_path: Path):
+ assert git_renames(tmp_path, ["a.py"]) == {}
+ assert git_renames(tmp_path, []) == {}
diff --git a/tests/unit/doc_drift/test_suppression.py b/tests/unit/doc_drift/test_suppression.py
new file mode 100644
index 000000000..112a41cb8
--- /dev/null
+++ b/tests/unit/doc_drift/test_suppression.py
@@ -0,0 +1,76 @@
+"""Inline ``repowise-drift-ignore`` markers: scope, prose-only, and counted."""
+
+from __future__ import annotations
+
+from repowise.core.analysis.doc_drift import DocDriftAnalyzer
+from repowise.core.analysis.doc_drift.extractor import extract, extract_with_suppressed
+
+LINE = "<!-- repowise-drift-ignore -->"
+FILE = "<!-- repowise-drift-ignore-file -->"
+
+
+def _targets(refs) -> list[str]:
+ return [r.target for r in refs]
+
+
+def test_line_marker_covers_its_own_line_and_the_next():
+ text = (
+ f"`src/a.py` {LINE}\n"
+ "`src/b.py`\n"
+ "`src/c.py`\n"
+ )
+ refs, silenced = extract_with_suppressed(text, "docs/x.md")
+ assert _targets(silenced) == ["src/a.py", "src/b.py"]
+ assert _targets(refs) == ["src/c.py"]
+
+
+def test_file_marker_anywhere_silences_the_whole_document():
+ text = "`src/a.py`\n\n`src/b.py`\n" + FILE + "\n"
+ refs, silenced = extract_with_suppressed(text, "docs/x.md")
+ assert refs == []
+ assert _targets(silenced) == ["src/a.py", "src/b.py"]
+
+
+def test_marker_inside_a_fence_does_nothing():
+ text = f"```markdown\n{LINE}\n{FILE}\n```\n`src/a.py`\n"
+ refs, silenced = extract_with_suppressed(text, "docs/x.md")
+ assert _targets(refs) == ["src/a.py"]
+ assert silenced == []
+
+
+def test_marker_quoted_in_a_code_span_does_nothing():
+ """A document explaining the marker must not silence itself."""
+ text = f"Put `{FILE}` in a document.\n`src/a.py`\n"
+ refs, silenced = extract_with_suppressed(text, "docs/x.md")
+ assert _targets(refs) == ["src/a.py"]
+ assert silenced == []
+
+
+def test_extract_drops_suppressed_references():
+ text = f"{LINE}\n`src/a.py`\n`src/b.py`\n"
+ assert _targets(extract(text, "docs/x.md")) == ["src/b.py"]
+
+
+def _analyze(files: dict[str, str], config: dict | None = None):
+ source_map = {k: v.encode("utf-8") for k, v in files.items()}
+ return DocDriftAnalyzer("repo", source_map=source_map).analyze(config)
+
+
+def test_report_counts_suppressed_references_instead_of_dropping_them():
+ report = _analyze(
+ {
+ "docs/a.md": f"{LINE}\nSee `src/gone.py`.\nSee `src/lost.py`.\n",
+ "src/app.py": "",
+ }
+ )
+ assert report.suppressed == 1
+ assert [f.target for f in report.findings] == ["src/lost.py"]
+
+
+def test_suppressed_count_respects_disabled_kinds():
+ report = _analyze(
+ {"docs/a.md": f"{FILE}\n`src/gone.py` and `make nope`\n", "Makefile": "all:\n"},
+ {"check_command": False},
+ )
+ assert report.suppressed == 1
+ assert report.total_findings == 0
diff --git a/tests/unit/doc_drift/test_ts_contract_parity.py b/tests/unit/doc_drift/test_ts_contract_parity.py
index d28e783ec..a425087f6 100644
--- a/tests/unit/doc_drift/test_ts_contract_parity.py
+++ b/tests/unit/doc_drift/test_ts_contract_parity.py
@@ -23,6 +23,7 @@ import pytest
from repowise.core.analysis.doc_drift.constants import (
HIGH_CONFIDENCE_THRESHOLD,
REVIEW_CONFIDENCE_THRESHOLD,
+ SUGGESTION_BASIS_VALUES,
UNAVAILABLE_NO_TABLE,
UNAVAILABLE_NOT_COMPUTED,
UNAVAILABLE_READ_FAILED,
@@ -87,6 +88,14 @@ def test_every_reference_class_has_a_reader_facing_label(contract: str) -> None:
assert labelled == {kind.value for kind in DriftKind}
+def test_every_suggestion_basis_has_a_reader_facing_label(contract: str) -> None:
+ """A basis added alone renders its slug in the detail panel and the prompt."""
+ block = re.search(r"SUGGESTION_BASIS_LABELS:.*?= \{(.*?)\};", contract, re.S)
+ assert block, "SUGGESTION_BASIS_LABELS is not declared"
+ labelled = set(re.findall(r"^\s*([a-z_]+):", block.group(1), re.M))
+ assert labelled == SUGGESTION_BASIS_VALUES
+
+
def _interface_fields(source: str, name: str) -> set[str]:
"""The field names one exported TS interface declares."""
block = re.search(rf"export interface {name} \{{(.*?)\n\}}", source, re.S)
diff --git a/tests/unit/persistence/test_doc_drift_crud.py b/tests/unit/persistence/test_doc_drift_crud.py
index f9b2983c3..35d83e2a4 100644
--- a/tests/unit/persistence/test_doc_drift_crud.py
+++ b/tests/unit/persistence/test_doc_drift_crud.py
@@ -58,6 +58,21 @@ async def test_findings_round_trip(async_session):
assert rows[0].evidence_json.startswith("[")
+async def test_a_suggestion_persists_and_its_absence_is_null(async_session):
+ repo = await insert_repo(async_session)
+ suggested = _finding(line=1)
+ suggested.suggestion = "src/gone/"
+ suggested.suggestion_basis = "package_split"
+ await replace_doc_drift_findings(
+ async_session, repo.id, [suggested, _finding(line=2)]
+ )
+ await async_session.commit()
+
+ rows = {r.line_number: r for r in await _rows(async_session, repo.id)}
+ assert (rows[1].suggestion, rows[1].suggestion_basis) == ("src/gone/", "package_split")
+ assert (rows[2].suggestion, rows[2].suggestion_basis) == (None, None)
+
+
async def test_rerunning_the_same_pass_changes_no_rows(async_session):
"""The phase exit criterion."""
repo = await insert_repo(async_session)
@@ -249,7 +264,7 @@ async def test_unreadable_evidence_degrades_to_none_rather_than_raising():
return types.SimpleNamespace(
file_path="docs/a.md", line_number=1, kind="path", target="src/gone.py",
confidence=0.9, origin="path_no_candidate", reason="r", raw="x", context="c",
- evidence_json=blob,
+ evidence_json=blob, suggestion=None, suggestion_basis=None,
)
for blob in ("{not json", '{"a": 1}', "", None):
diff --git a/tests/unit/test_ci_sarif.py b/tests/unit/test_ci_sarif.py
new file mode 100644
index 000000000..aeeb03136
--- /dev/null
+++ b/tests/unit/test_ci_sarif.py
@@ -0,0 +1,27 @@
+"""``repowise.core.ci.sarif``: the shared SARIF 2.1.0 envelope."""
+
+from __future__ import annotations
+
+from repowise.core.ci import sarif
+
+
+def test_run_indexes_known_rules_and_encodes_uris():
+ rules = [sarif.rule("path", "DocDriftPath", "short", "full", "help")]
+ results = [
+ sarif.result("path", "error", "msg", "docs/Setup #2.md", 0, "k/v1", "abc"),
+ sarif.result("other", "warning", "msg", "\\docs\\a.md", 3, "k/v1", "def", {"x": 1}),
+ ]
+ log = sarif.run("tool", "1.0", rules, results)
+
+ run = log["runs"][0]
+ assert log["version"] == "2.1.0"
+ assert run["tool"]["driver"]["rules"][0]["help"] == {"text": "help"}
+ first, second = run["results"]
+ loc = first["locations"][0]["physicalLocation"]
+ assert loc["artifactLocation"]["uri"] == "docs/Setup%20%232.md"
+ assert loc["region"]["startLine"] == 1
+ assert first["ruleIndex"] == 0
+ assert "ruleIndex" not in second
+ assert second["locations"][0]["physicalLocation"]["artifactLocation"]["uri"] == "docs/a.md"
+ assert second["properties"] == {"x": 1}
+ assert "properties" not in first
diff --git a/website/self-hosting.md b/website/self-hosting.md
index 5fb084f8d..26466e0a8 100644
--- a/website/self-hosting.md
+++ b/website/self-hosting.md
@@ -146,6 +146,15 @@ Use `--no-prose` for CI pipelines that don't need model-written prose, just the
path: dead-code-report.json
```
+Documentation drift needs no index at all, so it can gate a pull request on its
+own. It fails the job when a document names a path, heading or build target the
+tree no longer has:
+
+```yaml
+- name: Check documentation drift
+ run: repowise doc-drift --check --format github
+```
+
For full documentation generation in CI (with LLM):
```yaml