Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
"""``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_gitlab_is_one_issue_list_without_the_baseline(monkeypatch, tmp_path):
baseline = tmp_path / "baseline.json"
_invoke(monkeypatch, tmp_path, [_finding()], ["--write-baseline", str(baseline)])
findings = [_finding(), _finding(target="src/other.py", confidence=0.5)]
args = ["--baseline", str(baseline), "--format", "gitlab"]
result = _invoke(monkeypatch, tmp_path, findings, args, runner=_split_runner())
assert result.exit_code == 0
(issue,) = json.loads(result.stdout)
assert issue["severity"] == "minor"
assert issue["location"] == {"path": "docs/a.md", "lines": {"begin": 3}}
def test_gitlab_prints_an_empty_list_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", "gitlab"],
runner=_split_runner(),
)
assert result.exit_code == 2
assert json.loads(result.stdout) == []
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
@pytest.mark.skipif(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/"
def _scoped(monkeypatch, *changes):
from repowise.core.analysis.doc_drift import scope as scope_mod
scope = scope_mod.ChangeScope.from_changes(changes, label="main...HEAD")
monkeypatch.setattr(scope_mod, "scope_since", lambda root, revspec: scope)
def test_since_gates_only_drift_the_change_is_answerable_for(monkeypatch, tmp_path):
from repowise.core.analysis.change_health.sources import FileChange
_scoped(monkeypatch, FileChange(head_path=None, base_path="src/gone.py", status="deleted"))
findings = [_finding(), _finding(file_path="docs/b.md", target="src/old.py")]
result = _invoke(
monkeypatch, tmp_path, findings, ["--since", "main...HEAD", "--format", "json"]
)
payload = json.loads(result.output)
assert result.exit_code == 1
assert [f["file_path"] for f in payload["findings"]] == ["docs/a.md"]
assert payload["findings"][0]["scope_reason"] == "removed"
assert payload["scope"] == {
"revspec": "main...HEAD",
"documents_changed": 0,
"paths_removed": 1,
"out_of_scope": 1,
}
def test_since_passes_when_the_drift_predates_the_change(monkeypatch, tmp_path):
_scoped(monkeypatch)
result = _invoke(monkeypatch, tmp_path, [_finding()], ["--since", "main...HEAD"])
assert result.exit_code == 0
assert "Gate passed" in result.output
def test_since_markdown_names_the_scope(monkeypatch, tmp_path):
_scoped(monkeypatch)
result = _invoke(
monkeypatch, tmp_path, [_finding()], ["--since", "main...HEAD", "--format", "markdown"]
)
assert "scoped to main...HEAD, 1 outside the change" in result.output
def test_since_auto_without_a_base_exits_two(monkeypatch, tmp_path):
from repowise.core.ci import base
def _none(root, env=None):
raise base.BaseNotFoundError("no base")
monkeypatch.setattr(base, "default_revspec", _none)
result = _invoke(monkeypatch, tmp_path, [_finding()], ["--since", "auto", "--format", "json"])
assert result.exit_code == 2
assert json.loads(result.output)["error"] == "base_not_found"
def test_since_on_a_bad_revision_exits_two(monkeypatch, tmp_path):
from repowise.core.analysis.doc_drift import scope as scope_mod
def _bad(root, revspec):
raise ValueError("unknown revision")
monkeypatch.setattr(scope_mod, "scope_since", _bad)
result = _invoke(
monkeypatch, tmp_path, [_finding()], ["--since", "nope...HEAD", "--format", "json"]
)
assert result.exit_code == 2
assert json.loads(result.output)["error"] == "diff_failed"
def test_since_requires_check_and_refuses_write_baseline(monkeypatch, tmp_path):
monkeypatch.setattr(doc_drift_cmd, "_repo_path", lambda *a, **k: tmp_path)
runner = CliRunner()
alone = runner.invoke(doc_drift_cmd.doc_drift_command, ["--since", "main...HEAD"])
assert alone.exit_code == 2
both = runner.invoke(
doc_drift_cmd.doc_drift_command,
["--check", "--since", "main...HEAD", "--write-baseline", str(tmp_path / "b.json")],
)
assert both.exit_code == 2
def _symbol_history(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").mkdir()
(tmp_path / "docs").mkdir()
(tmp_path / "src" / "app.py").write_text("def parse_config():\n pass\n", encoding="utf-8")
(tmp_path / "docs" / "guide.md").write_text("Call `parse_config()`.\n", encoding="utf-8")
git("init", "-q")
git("add", ".")
git("commit", "-qm", "init")
(tmp_path / "src" / "app.py").write_text(
"def parse_conf():\n pass\n", encoding="utf-8"
)
git("commit", "-qam", "rename")
@pytest.mark.skipif(shutil.which("git") is None, reason="git not installed")
def test_check_runs_no_symbol_pass_unless_asked(monkeypatch, tmp_path):
_symbol_history(tmp_path)
async def _names(root): # an index exists, but nobody asked for symbols
raise AssertionError("the index must not be read")
monkeypatch.setattr(doc_drift_cmd, "_index_symbol_names", _names)
result = CliRunner().invoke(
doc_drift_cmd.doc_drift_command,
["--check", "--no-workspace", "--format", "json", str(tmp_path)],
)
assert result.exit_code == 0, result.output
payload = json.loads(result.output)
assert payload["findings"] == []
assert payload["references_checked"] == 0
@pytest.mark.skipif(shutil.which("git") is None, reason="git not installed")
def test_kind_symbol_without_an_index_cannot_evaluate(tmp_path):
_symbol_history(tmp_path)
result = CliRunner().invoke(
doc_drift_cmd.doc_drift_command,
["--check", "--kind", "symbol", "--no-workspace", "--format", "json", str(tmp_path)],
)
assert result.exit_code == 2, result.output
assert json.loads(result.output)["error"] == "no_index"
@pytest.mark.skipif(shutil.which("git") is None, reason="git not installed")
def test_kind_symbol_with_an_index_reports_a_renamed_symbol(monkeypatch, tmp_path):
_symbol_history(tmp_path)
async def _names(root):
return frozenset({"parse_conf"})
monkeypatch.setattr(doc_drift_cmd, "_index_symbol_names", _names)
result = CliRunner().invoke(
doc_drift_cmd.doc_drift_command,
["--check", "--kind", "symbol", "--no-workspace", "--format", "json", str(tmp_path)],
)
assert result.exit_code == 1, result.output
(finding,) = json.loads(result.output)["findings"]
assert finding["kind"] == "symbol"
assert finding["target"] == "parse_config"
assert finding["suggestion"] == "parse_conf()"
assert finding["suggestion_basis"] == "symbol_rename"
assert finding["suggested_line"] == "Call `parse_conf()`."
assert finding["suggestion_columns"] == [[7, 21]]
assert finding["defined_in"] == ["src/app.py"]
def _git(cwd, *args: str) -> None:
subprocess.run(["git", *args], cwd=cwd, check=True, capture_output=True)
def _baseline_on_main(tmp_path, findings):
"""A repository whose ``main`` commits the baseline for *findings*, on a branch off it."""
from repowise.core.analysis.doc_drift.baseline import write_baseline
_git(tmp_path, "init", "-q", "-b", "main")
for key, value in (("user.email", "[email protected]"), ("user.name", "t"), ("core.autocrlf", "false")):
_git(tmp_path, "config", key, value)
baseline = tmp_path / "baseline.json"
write_baseline(baseline, findings)
_git(tmp_path, "add", "-A")
_git(tmp_path, "commit", "-qm", "baseline")
_git(tmp_path, "switch", "-qc", "feature")
return baseline
def test_a_baseline_that_grew_over_the_base_fails(monkeypatch, tmp_path):
from repowise.core.analysis.doc_drift.baseline import write_baseline
baseline = _baseline_on_main(tmp_path, [_finding()])
findings = [_finding(), _finding(target="src/other.py")]
write_baseline(baseline, findings)
args = ["--baseline", str(baseline), "--since", "main", "--fail-on-baseline-growth"]
result = _invoke(monkeypatch, tmp_path, findings, args)
assert result.exit_code == 1
assert "docs/a.md path src/other.py" in result.output
doc = json.loads(_invoke(monkeypatch, tmp_path, findings, [*args, "--format", "json"]).stdout)
assert [e["target"] for e in doc["baseline_growth"]] == ["src/other.py"]
def test_a_baseline_that_did_not_grow_passes(monkeypatch, tmp_path):
baseline = _baseline_on_main(tmp_path, [_finding()])
args = ["--baseline", str(baseline), "--since", "main", "--fail-on-baseline-growth"]
result = _invoke(monkeypatch, tmp_path, [_finding()], args)
assert result.exit_code == 0, result.output
def test_baseline_growth_without_a_baseline_is_refused(monkeypatch, tmp_path):
result = _invoke(monkeypatch, tmp_path, [], ["--fail-on-baseline-growth"])
assert result.exit_code == 2
assert "needs --baseline" in result.output
def test_baseline_growth_refuses_write_baseline(monkeypatch, tmp_path):
args = ["--baseline", "b.json", "--write-baseline", "c.json", "--fail-on-baseline-growth"]
result = _invoke(monkeypatch, tmp_path, [], args)
assert result.exit_code == 2
assert "not --write-baseline" in result.output