Files
ECC/tests/test_docs_governance_audit.py
T
L4XB 49b390d243 fix(docs-governance): hide only comments that cannot cross a container
A comment that opened after text in a list item and closed in a later
block quote hid the live link between them, because the paragraph check
only looked for blank lines. Read a comment across lines only where
CommonMark makes it a top-level HTML block, a `<!--` at column 0 after a
blank line, which only its closer ends. Elsewhere a comment is hidden
only when it closes on the line it opens on, so every other line stays
audited Markdown. The fence pass uses the same rule for comment blocks.

Drop the container and ordered-list heuristics this replaces, refresh
the registry digest, and keep the three copies of the script identical.
2026-11-05 11:17:47 +01:00

1164 lines
46 KiB
Python

from __future__ import annotations
import json
import subprocess
import sys
from pathlib import Path
import pytest
ROOT = Path(__file__).resolve().parents[1]
SCRIPT = ROOT / "skills" / "docs-governance" / "scripts" / "audit-docs.py"
@pytest.fixture
def project(tmp_path: Path) -> Path:
return tmp_path
def run_audit(
project: Path, scope: str, *, timeout: float | None = None,
modules: tuple[str, ...] = (),
script: Path = SCRIPT,
) -> subprocess.CompletedProcess[str]:
module_args = [argument for module in modules for argument in ("--module", module)]
return subprocess.run(
[sys.executable, str(script), "--root", str(project), "--scope", scope, *module_args],
text=True,
capture_output=True,
check=False,
timeout=timeout,
)
def test_module_audit_checks_local_carriers_links_and_is_read_only(project: Path) -> None:
module = project / "src" / "inventory"
module.mkdir(parents=True)
(module / "AGENTS.md").write_text("[terms](CONTEXT.md)\n", encoding="utf-8")
(module / "CONTEXT.md").write_text("[contract](../../contract.md)\n", encoding="utf-8")
(project / "contract.md").write_text("# Contract\n", encoding="utf-8")
before = {path: path.read_bytes() for path in project.rglob("*") if path.is_file()}
result = run_audit(project, "modules", modules=("src/inventory",))
assert result.returncode == 0, result.stdout + result.stderr
assert "Local agents source: 'src/inventory/AGENTS.md'" in result.stdout
assert "Local context source: 'src/inventory/CONTEXT.md'" in result.stdout
assert "All local Markdown links resolve" in result.stdout
assert "semantic review" in result.stdout
after = {path: path.read_bytes() for path in project.rglob("*") if path.is_file()}
assert after == before
@pytest.mark.parametrize("distribution", ("skills", ".agents/skills", "pi/core/skills"))
@pytest.mark.parametrize("role,filename", (("agents", "AGENTS.md"), ("context", "CONTEXT.md")))
@pytest.mark.parametrize("broken", (False, True))
@pytest.mark.parametrize("module_path", (".", "src/inventory"))
def test_module_audit_checks_root_carrier_before_mapped_source(
project: Path, distribution: str, role: str, filename: str, broken: bool,
module_path: str,
) -> None:
(project / module_path).mkdir(parents=True, exist_ok=True)
(project / ".governance").mkdir()
(project / "docs").mkdir()
(project / ".governance/docs-map.json").write_text(
json.dumps({"agents": "docs/rules.md", "context": "docs/glossary.md"}),
encoding="utf-8",
)
for mapped in ("rules", "glossary"):
(project / f"docs/{mapped}.md").write_text("# Shared source\n", encoding="utf-8")
if not broken:
(project / "docs/target.md").write_text("# Link target\n", encoding="utf-8")
(project / filename).write_text("[target](docs/target.md)\n", encoding="utf-8")
before = {path: path.read_bytes() for path in project.rglob("*") if path.is_file()}
result = run_audit(
project, "modules", modules=(module_path,),
script=ROOT / distribution / "docs-governance/scripts/audit-docs.py",
)
assert result.returncode == (1 if broken else 0), result.stdout + result.stderr
source_label = f"Local {role} source" if module_path == "." else f"Shared {role} candidate"
assert f"{source_label}: '{filename}'" in result.stdout
assert (f"Broken Markdown link: '{filename}' -> 'docs/target.md'" in result.stdout) == broken
after = {path: path.read_bytes() for path in project.rglob("*") if path.is_file()}
assert after == before, "module audit must remain read-only in every distribution"
@pytest.mark.parametrize("scope", ("modules", "full"))
def test_module_audit_reports_nearest_shared_candidates(project: Path, scope: str) -> None:
(project / "src" / "inventory").mkdir(parents=True)
(project / "AGENTS.md").write_text("# Project rules\n", encoding="utf-8")
(project / "src" / "AGENTS.md").write_text("# Shared module rules\n", encoding="utf-8")
(project / "CONTEXT.md").write_text("# Shared language\n", encoding="utf-8")
result = run_audit(project, scope, modules=("src/inventory",))
assert result.returncode == 0, result.stdout + result.stderr
assert "Shared agents candidate: 'src/AGENTS.md'" in result.stdout
assert "Shared context candidate: 'CONTEXT.md'" in result.stdout
assert "confirm it covers module 'src/inventory'" in result.stdout
assert "Local agents source" not in result.stdout
def test_module_audit_reuses_mapped_sources_without_creating_shells(project: Path) -> None:
(project / "inventory").mkdir()
(project / "docs").mkdir()
(project / ".governance").mkdir()
(project / ".governance/docs-map.json").write_text(
json.dumps({"agents": "docs/rules.md", "context": "docs/glossary.md"}), encoding="utf-8"
)
for name in ("rules", "glossary"):
(project / f"docs/{name}.md").write_text(f"# {name}\n", encoding="utf-8")
result = run_audit(project, "modules", modules=("inventory",))
assert result.returncode == 0, result.stdout + result.stderr
assert "Shared agents candidate: 'docs/rules.md'" in result.stdout
assert "Shared context candidate: 'docs/glossary.md'" in result.stdout
assert list((project / "inventory").iterdir()) == []
def test_module_audit_checks_selected_carriers_in_template_named_modules(project: Path) -> None:
(project / "templates/inventory").mkdir(parents=True)
(project / "templates/inventory/AGENTS.md").write_text("[missing](missing.md)\n", encoding="utf-8")
result = run_audit(project, "modules", modules=("templates/inventory",))
assert result.returncode == 1, result.stdout + result.stderr
assert "Broken Markdown link: 'templates/inventory/AGENTS.md'" in result.stdout
def test_module_audit_missing_carriers_are_manual_review_not_failure(project: Path) -> None:
(project / "inventory").mkdir()
result = run_audit(project, "modules", modules=("inventory",))
assert result.returncode == 0, result.stdout + result.stderr
assert "No agents source found for module 'inventory'" in result.stdout
assert "No context source found for module 'inventory'" in result.stdout
assert list((project / "inventory").iterdir()) == []
@pytest.mark.parametrize("module", ("missing", "../", "/", "not-a-directory"))
def test_module_audit_rejects_invalid_directories(project: Path, module: str) -> None:
(project / "not-a-directory").write_text("not a module\n", encoding="utf-8")
result = run_audit(project, "modules", modules=(module,))
assert result.returncode == 1, result.stdout + result.stderr
assert "Module must be a repository-relative directory inside root" in result.stdout
assert "Traceback" not in result.stderr
@pytest.mark.parametrize("filename", ("AGENTS.md", "CONTEXT.md"))
def test_module_audit_does_not_read_escaping_sources(project: Path, filename: str) -> None:
module = project / "inventory"
module.mkdir()
outside = project.parent / f"outside-{filename}"
outside.write_text("[secret](secret-missing.md)\n", encoding="utf-8")
try:
(module / filename).symlink_to(outside)
result = run_audit(project, "modules", modules=("inventory",))
assert result.returncode == 1, result.stdout + result.stderr
assert "repository-contained regular file" in result.stdout
assert "secret-missing" not in result.stdout
finally:
outside.unlink(missing_ok=True)
def test_module_audit_reports_invalid_utf8_carrier(project: Path) -> None:
(project / "inventory").mkdir()
(project / "inventory/AGENTS.md").write_bytes(b"\xff")
result = run_audit(project, "modules", modules=("inventory",))
assert result.returncode == 1, result.stdout + result.stderr
assert "Cannot read module agents source" in result.stdout
def test_module_audit_reuses_link_parser_and_source_relative_resolution(project: Path) -> None:
module = project / "src/inventory"
module.mkdir(parents=True)
(module / "AGENTS.md").write_text("[terms](.\\CONTEXT.md)\n", encoding="utf-8")
(module / "CONTEXT.md").write_text("[contract](../contract.md)\n", encoding="utf-8")
(project / "contract.md").write_text("# Wrong base\n", encoding="utf-8")
result = run_audit(project, "modules", modules=("src/inventory",))
assert result.returncode == 1, result.stdout + result.stderr
assert "Broken Markdown link: 'src/inventory/CONTEXT.md' -> '../contract.md'" in result.stdout
assert "AGENTS.md' ->" not in result.stdout
def test_module_audit_requires_explicit_scope_and_boundary(project: Path) -> None:
missing = run_audit(project, "modules")
ignored = run_audit(project, "context", modules=("inventory",))
assert missing.returncode == ignored.returncode == 2
assert "requires at least one --module" in missing.stderr
assert "supported only with --scope modules or full" in ignored.stderr
def test_module_audit_checks_each_selected_boundary_once(project: Path) -> None:
for module in ("inventory", "billing"):
(project / module).mkdir()
result = run_audit(project, "modules", modules=("inventory", "billing", "inventory"))
assert result.returncode == 0, result.stdout + result.stderr
assert result.stdout.count("Selected module: 'inventory'") == 1
assert result.stdout.count("Selected module: 'billing'") == 1
@pytest.mark.parametrize("kind", ("directory", "broken-symlink"))
def test_module_audit_reports_non_file_carriers(project: Path, kind: str) -> None:
(project / "inventory").mkdir()
carrier = project / "inventory/AGENTS.md"
if kind == "directory":
carrier.mkdir()
else:
carrier.symlink_to(project / "missing.md")
result = run_audit(project, "modules", modules=("inventory",))
assert result.returncode == 1, result.stdout + result.stderr
assert "repository-contained regular file" in result.stdout
def test_module_audit_rejects_escaping_module_directory(project: Path) -> None:
(project / "escape").symlink_to(project.parent, target_is_directory=True)
result = run_audit(project, "modules", modules=("escape",))
assert result.returncode == 1, result.stdout + result.stderr
assert "Module must be a repository-relative directory inside root" in result.stdout
def configure_git(project: Path) -> None:
subprocess.run(["git", "init"], cwd=project, capture_output=True, check=True)
subprocess.run(
["git", "config", "user.email", "test@example.com"], cwd=project, check=True
)
subprocess.run(["git", "config", "user.name", "Test"], cwd=project, check=True)
def test_artifact_scope_fails_on_broken_markdown_link(project: Path) -> None:
(project / "guide.md").write_text("[missing](docs/missing.md)\n", encoding="utf-8")
result = run_audit(project, "artifacts")
assert result.returncode == 1
assert "Broken Markdown link" in result.stdout
def test_artifact_scope_resolves_windows_style_relative_markdown_links(
project: Path,
) -> None:
target = project / "docs" / "adr" / "0001.md"
target.parent.mkdir(parents=True)
target.write_text("# ADR\n", encoding="utf-8")
(project / "guide.md").write_text(
"[adr](docs\\adr\\0001.md)\n", encoding="utf-8"
)
result = run_audit(project, "artifacts")
assert result.returncode == 0, result.stdout
def test_artifact_scope_resolves_root_relative_links_inside_project(
project: Path,
) -> None:
docs = project / "docs"
docs.mkdir()
(docs / "guide.md").write_text("[status](/PROJECT_STATUS.md)\n", encoding="utf-8")
(project / "PROJECT_STATUS.md").write_text("# Status\n", encoding="utf-8")
result = run_audit(project, "artifacts")
assert result.returncode == 0, result.stdout
def test_artifact_scope_rejects_links_that_escape_project(project: Path) -> None:
outside = project.parent / "outside.md"
outside.write_text("# Outside\n", encoding="utf-8")
try:
(project / "guide.md").write_text(
"[outside](../outside.md)\n", encoding="utf-8"
)
result = run_audit(project, "artifacts")
assert result.returncode == 1
assert "Broken Markdown link" in result.stdout
finally:
outside.unlink(missing_ok=True)
def test_artifact_scope_does_not_read_markdown_symlinked_outside_project(
project: Path,
) -> None:
outside = project.parent / "outside-secret.md"
outside.write_text("[secret](missing-token-value.md)\n", encoding="utf-8")
try:
(project / "outside.md").symlink_to(outside)
result = run_audit(project, "artifacts")
assert result.returncode == 1
assert "Markdown source resolves outside the project root" in result.stdout
assert "missing-token-value" not in result.stdout
finally:
outside.unlink(missing_ok=True)
def test_artifact_scope_reports_a_broken_markdown_symlink(project: Path) -> None:
(project / "broken.md").symlink_to(project / "missing.md")
result = run_audit(project, "artifacts")
assert result.returncode == 1
assert "Markdown source is not a regular file" in result.stdout
def test_artifact_scope_reports_non_utf8_markdown(project: Path) -> None:
(project / "invalid.md").write_bytes(b"\xff\xfe")
result = run_audit(project, "artifacts")
assert result.returncode == 1
assert "Cannot read Markdown source as a UTF-8 regular file" in result.stdout
def test_artifact_scope_reports_a_nul_encoded_link_without_crashing(
project: Path,
) -> None:
(project / "guide.md").write_text("[invalid](a%00b.md)\n", encoding="utf-8")
result = run_audit(project, "artifacts")
assert result.returncode == 1
assert "Broken Markdown link" in result.stdout
assert "Traceback" not in result.stderr
def test_artifact_scope_ignores_protocol_relative_external_links(project: Path) -> None:
(project / "guide.md").write_text(
"[asset](//cdn.example.com/file.js)\n", encoding="utf-8"
)
result = run_audit(project, "artifacts")
assert result.returncode == 0, result.stdout
def test_artifact_scope_checks_unc_style_links(project: Path) -> None:
(project / "guide.md").write_text(
"[missing](\\\\server\\share\\missing.md)\n", encoding="utf-8"
)
result = run_audit(project, "artifacts")
assert result.returncode == 1
assert "Broken Markdown link" in result.stdout
assert "//server/share/missing.md" in result.stdout
def test_artifact_scope_ignores_external_uri_schemes_case_insensitively(
project: Path,
) -> None:
(project / "guide.md").write_text(
"[secure](HTTPS://example.com/guide)\n"
"[transfer](ftp://example.com/file)\n"
"[identifier](urn:isbn:9780140328721)\n"
"[paper](doi:10.1000/182)\n"
"[text](sms:+15555550123)\n"
"[location](geo:37.786971,-122.399677)\n"
"[mail](mailto:docs@example.com)\n"
"[phone](tel:+15555550123)\n"
"[inline](data:text/plain,hello)\n",
encoding="utf-8",
)
result = run_audit(project, "artifacts")
assert result.returncode == 0, result.stdout
def test_artifact_scope_ignores_opaque_external_uri_schemes(project: Path) -> None:
(project / "guide.md").write_text(
"[magnet](magnet:?xt=urn:btih:abcdef)\n"
"[chat](irc:channel)\n"
"[news](news:comp.lang.python)\n",
encoding="utf-8",
)
result = run_audit(project, "artifacts")
assert result.returncode == 0, result.stdout
def test_artifact_scope_checks_windows_drive_paths_as_local_paths(
project: Path,
) -> None:
(project / "guide.md").write_text(
"[slash](C:/docs/guide.md)\n[backslash](C:\\docs\\guide.md)\n",
encoding="utf-8",
)
result = run_audit(project, "artifacts")
assert result.returncode == 1
assert "Broken Markdown link" in result.stdout
def test_artifact_scope_checks_colon_shaped_local_paths_as_local_paths(
project: Path,
) -> None:
(project / "guide.md").write_text("[local](docs:guide.md)\n", encoding="utf-8")
result = run_audit(project, "artifacts")
assert result.returncode == 1
assert "Broken Markdown link: 'guide.md' -> 'docs:guide.md'" in result.stdout
def test_artifact_scope_escapes_percent_encoded_control_characters(
project: Path,
) -> None:
(project / "guide.md").write_text(
"[unsafe](missing%0A%1B%5B2J.md)\n", encoding="utf-8"
)
result = run_audit(project, "artifacts")
assert result.returncode == 1
assert "missing\\n\\x1b[2J.md" in result.stdout
assert "\x1b" not in result.stdout
def test_artifact_scope_ignores_query_and_fragment_in_local_links(
project: Path,
) -> None:
(project / "guide.md").write_text(
"[details](target.md?version=2#usage)\n", encoding="utf-8"
)
(project / "target.md").write_text("# Target\n", encoding="utf-8")
result = run_audit(project, "artifacts")
assert result.returncode == 0, result.stdout
def test_artifact_scope_resolves_markdown_destinations_with_parentheses_and_spaces(
project: Path,
) -> None:
(project / "topic (draft).md").write_text("# Draft\n", encoding="utf-8")
(project / "guide with spaces.md").write_text("# Guide\n", encoding="utf-8")
(project / "index.md").write_text(
"[topic](topic (draft).md)\n[guide](<guide with spaces.md>)\n",
encoding="utf-8",
)
result = run_audit(project, "artifacts")
assert result.returncode == 0, result.stdout
def test_artifact_scope_ignores_optional_markdown_link_titles(project: Path) -> None:
(project / "guide.md").write_text("# Guide\n", encoding="utf-8")
(project / "index.md").write_text(
'[plain](guide.md "Guide")\n[wrapped](<guide.md> "Guide")\n',
encoding="utf-8",
)
result = run_audit(project, "artifacts")
assert result.returncode == 0, result.stdout
def test_artifact_scope_handles_many_unclosed_inline_links_linearly(
project: Path,
) -> None:
(project / "guide.md").write_text("[link](" * 10_000, encoding="utf-8")
result = run_audit(project, "artifacts", timeout=2)
assert result.returncode == 0, result.stdout
@pytest.mark.unit
@pytest.mark.parametrize("prefix", ("<unterminated ", "unterminated "))
def test_artifact_scope_checks_link_after_unclosed_destination(
project: Path, prefix: str
) -> None:
(project / "index.md").write_text(
f"[broken]({prefix}[missing](missing-guide.md)\n",
encoding="utf-8",
)
result = run_audit(project, "artifacts")
assert result.returncode == 1
assert "Broken Markdown link: 'index.md' -> 'missing-guide.md'" in result.stdout
def test_artifact_scope_ignores_links_inside_code_examples(project: Path) -> None:
(project / "guide.md").write_text(
"`[inline](missing-inline.md)`\n\n```md\n[fenced](missing-fenced.md)\n```\n",
encoding="utf-8",
)
result = run_audit(project, "artifacts")
assert result.returncode == 0, result.stdout
def test_artifact_scope_ignores_links_inside_html_comments(project: Path) -> None:
(project / "guide.md").write_text(
"Intro <!-- [old](missing-inline.md) --> text\n\n"
"<!--\nSee [draft](missing-draft.md).\n-->\n\n"
"Text <!-- --> [after](missing-after.md)\n",
encoding="utf-8",
)
result = run_audit(project, "artifacts")
assert result.returncode == 1
assert "missing-inline.md" not in result.stdout
assert "missing-draft.md" not in result.stdout
assert "Broken Markdown link: 'guide.md' -> 'missing-after.md'" in result.stdout
def test_artifact_scope_reads_html_comments_as_commonmark_does(project: Path) -> None:
(project / "guide.md").write_text(
# -- an escaped opener is text, so the link after it is real --
"Intro \\<!-- [escaped](missing-escaped.md) -->\n\n"
# -- a comment that opens before a code span ends at its own closer --
"Note <!-- ` --> `sample` [after-code](missing-after-code.md)\n\n"
# -- a comment inside a line that does not close on it is text --
"Intro <!-- note\n\n[real](missing-real.md)\n-->\n\n"
# -- one that starts a line after a blank line is a top-level HTML block: it spans blank
# -- lines and takes the rest of the line that holds its closer --
"<!--\n[hidden](missing-hidden.md)\n\n[hidden2](missing-hidden2.md)\n-->\n\n"
"<!-- c --> [rest](missing-rest.md)\n\n"
# -- in a list item or a block quote, only a comment that closes on its line is skipped,
# -- and the rest of that line is still audited --
"- <!-- c --> [listed](missing-listed.md)\n\n"
"> <!-- c --> [quoted](missing-quoted.md)\n\n"
"- item <!-- c\n\n [item-real](missing-item-real.md)\n -->\n\n"
# -- a comment where a destination must begin does not make a definition --
"[foo]: <!-- note --> missing-definition.md\n\n[foo]\n\n"
"[bar]: <!-- only a comment -->\n\n[bar]\n\n"
# -- a title may hold comment-shaped text; the destination is still audited --
'[titled](missing-titled.md "<!-- c -->")\n\n'
# -- a fence line inside a comment block is comment text; the fence after it is real --
"<!--\n```\n-->\n```\n[fenced](missing-fenced.md)\n```\n",
encoding="utf-8",
)
result = run_audit(project, "artifacts")
assert result.returncode == 1
for reported in (
"missing-escaped.md",
"missing-after-code.md",
"missing-real.md",
"missing-listed.md",
"missing-quoted.md",
"missing-item-real.md",
"missing-titled.md",
):
assert f"Broken Markdown link: 'guide.md' -> '{reported}'" in result.stdout
for hidden in (
"missing-hidden",
"missing-rest.md",
"missing-definition.md",
"missing-fenced.md",
):
assert hidden not in result.stdout
assert result.stdout.count("Broken Markdown link") == 7, result.stdout
def test_artifact_scope_reports_a_link_that_a_comment_cannot_reach(project: Path) -> None:
(project / "guide.md").write_text(
# -- the block quote ends the list item, so the comment never closes and the link is live --
"- item <!--\ntext\n [live](missing.md)\n> > -->\n\n"
# -- a comment block at the top level hides list and quote lines up to its closer --
"<!--\n- [draft](missing-draft.md)\n> -->\n",
encoding="utf-8",
)
result = run_audit(project, "artifacts")
assert result.returncode == 1
assert "Broken Markdown link: 'guide.md' -> 'missing.md'" in result.stdout
assert "missing-draft.md" not in result.stdout
def test_artifact_scope_ignores_title_with_escaped_quotes(project: Path) -> None:
(project / "guide.md").write_text("# Guide\n", encoding="utf-8")
(project / "index.md").write_text(
'[guide](guide.md "The \\"Guide\\"")\n',
encoding="utf-8",
)
result = run_audit(project, "artifacts")
assert result.returncode == 0, result.stdout
def test_artifact_scope_ignores_title_with_closing_parenthesis(project: Path) -> None:
(project / "guide.md").write_text("# Guide\n", encoding="utf-8")
(project / "index.md").write_text(
'[guide](guide.md "Guide)")\n',
encoding="utf-8",
)
result = run_audit(project, "artifacts")
assert result.returncode == 0, result.stdout
def test_artifact_scope_ignores_link_like_text_in_title(project: Path) -> None:
(project / "guide.md").write_text("# Guide\n", encoding="utf-8")
(project / "index.md").write_text(
'[guide](guide.md "See [example](missing.md)")\n', encoding="utf-8"
)
result = run_audit(project, "artifacts")
assert result.returncode == 0, result.stdout
def test_artifact_scope_accepts_link_shaped_destination_text(project: Path) -> None:
target = project / "guide[ref](v1).md"
target.write_text("# Guide\n", encoding="utf-8")
(project / "index.md").write_text(
"[plain](guide[ref](v1).md)\n[wrapped](<guide[ref](v1).md>)\n",
encoding="utf-8",
)
result = run_audit(project, "artifacts")
assert result.returncode == 0, result.stdout
def test_artifact_scope_checks_angle_wrapped_destination_with_title(
project: Path,
) -> None:
(project / "index.md").write_text(
'[missing](<guide.md> "Guide")\n', encoding="utf-8"
)
result = run_audit(project, "artifacts")
assert result.returncode == 1
assert "Broken Markdown link: 'index.md' -> 'guide.md'" in result.stdout
@pytest.mark.parametrize(
"usage",
("[guide][docs]", "[docs][]", "[docs]"),
)
def test_artifact_scope_checks_reference_style_markdown_links(
project: Path, usage: str
) -> None:
(project / "index.md").write_text(
f"{usage}\n\n[docs]: missing-guide.md\n", encoding="utf-8"
)
result = run_audit(project, "artifacts")
assert result.returncode == 1
assert "Broken Markdown link" in result.stdout
assert "missing-guide.md" in result.stdout
def test_artifact_scope_checks_shortcut_reference_followed_by_colon(
project: Path,
) -> None:
(project / "index.md").write_text(
"See [docs]: details\n\n[docs]: missing-guide.md\n", encoding="utf-8"
)
result = run_audit(project, "artifacts")
assert result.returncode == 1
assert "Broken Markdown link: 'index.md' -> 'missing-guide.md'" in result.stdout
@pytest.mark.unit
@pytest.mark.parametrize("target_line", (" missing-guide.md", "missing-guide.md"))
def test_artifact_scope_checks_continuation_line_reference_target(
project: Path, target_line: str
) -> None:
(project / "index.md").write_text(
f"[docs]\n\n[docs]:\n{target_line}\n", encoding="utf-8"
)
result = run_audit(project, "artifacts")
assert result.returncode == 1
assert "Broken Markdown link: 'index.md' -> 'missing-guide.md'" in result.stdout
def test_adr_scope_requires_every_file_in_index(project: Path) -> None:
adr_dir = project / "docs" / "adr"
adr_dir.mkdir(parents=True)
(adr_dir / "README.md").write_text("# ADR Index\n", encoding="utf-8")
(adr_dir / "0001-storage.md").write_text(
"# ADR-0001\n\nStatus: accepted\n", encoding="utf-8"
)
result = run_audit(project, "adr")
assert result.returncode == 1
assert "ADR is missing from the canonical index" in result.stdout
def test_adr_scope_accepts_indexed_decision(project: Path) -> None:
adr_dir = project / "docs" / "adr"
adr_dir.mkdir(parents=True)
(adr_dir / "README.md").write_text(
"[decision](ADR-001-Storage.md)\n", encoding="utf-8"
)
(adr_dir / "ADR-001-Storage.md").write_text(
"# ADR-001\n\nStatus: accepted\n", encoding="utf-8"
)
result = run_audit(project, "adr")
assert result.returncode == 0, result.stdout
def test_adr_scope_accepts_documented_bold_status_metadata(project: Path) -> None:
adr_dir = project / "docs" / "adr"
adr_dir.mkdir(parents=True)
(adr_dir / "README.md").write_text(
"[decision](0001-storage.md)\n", encoding="utf-8"
)
(adr_dir / "0001-storage.md").write_text(
"# ADR-0001\n\n**Status**: accepted\n", encoding="utf-8"
)
result = run_audit(project, "adr")
assert result.returncode == 0, result.stdout
def test_adr_scope_accepts_superseded_status_with_successor(project: Path) -> None:
adr_dir = project / "docs" / "adr"
adr_dir.mkdir(parents=True)
(adr_dir / "README.md").write_text(
"[old](0001-storage.md)\n[new](0002-storage.md)\n", encoding="utf-8"
)
(adr_dir / "0001-storage.md").write_text(
"# ADR-0001\n\n**Status**: superseded by ADR-0002\n", encoding="utf-8"
)
(adr_dir / "0002-storage.md").write_text(
"# ADR-0002\n\n**Status**: accepted\n", encoding="utf-8"
)
result = run_audit(project, "adr")
assert result.returncode == 0, result.stdout
def test_adr_scope_rejects_missing_inline_superseded_successor(project: Path) -> None:
adr_dir = project / "docs" / "adr"
adr_dir.mkdir(parents=True)
(adr_dir / "README.md").write_text(
"[decision](0001-storage.md)\n", encoding="utf-8"
)
(adr_dir / "0001-storage.md").write_text(
"# ADR-0001\n\n**Status**: superseded by ADR-9999\n", encoding="utf-8"
)
result = run_audit(project, "adr")
assert result.returncode == 1
assert "ADR inline successor does not exist" in result.stdout
def test_adr_scope_rejects_superseded_status_without_successor(project: Path) -> None:
adr_dir = project / "docs" / "adr"
adr_dir.mkdir(parents=True)
(adr_dir / "README.md").write_text(
"[decision](0001-storage.md)\n", encoding="utf-8"
)
(adr_dir / "0001-storage.md").write_text(
"# ADR-0001\n\n**Status**: superseded\n", encoding="utf-8"
)
result = run_audit(project, "adr")
assert result.returncode == 1
assert "Superseded ADR is missing an inline successor" in result.stdout
def test_adr_scope_rejects_short_inline_superseded_successor(project: Path) -> None:
adr_dir = project / "docs" / "adr"
adr_dir.mkdir(parents=True)
(adr_dir / "README.md").write_text(
"[decision](0001-storage.md)\n", encoding="utf-8"
)
(adr_dir / "0001-storage.md").write_text(
"# ADR-0001\n\n**Status**: superseded by ADR-42\n", encoding="utf-8"
)
result = run_audit(project, "adr")
assert result.returncode == 1
assert "ADR has no parseable status" in result.stdout
def test_adr_scope_audits_common_adr_prefixed_filenames(project: Path) -> None:
adr_dir = project / "docs" / "adr"
adr_dir.mkdir(parents=True)
(adr_dir / "README.md").write_text(
"[decision](ADR-001-Storage.md)\n", encoding="utf-8"
)
(adr_dir / "ADR-001-Storage.md").write_text("# ADR-001\n", encoding="utf-8")
result = run_audit(project, "adr")
assert result.returncode == 1
assert "ADR has no parseable status" in result.stdout
def test_adr_scope_requires_an_actual_index_link(project: Path) -> None:
adr_dir = project / "docs" / "adr"
adr_dir.mkdir(parents=True)
(adr_dir / "README.md").write_text(
"TODO: add 0001-storage.md later\n", encoding="utf-8"
)
(adr_dir / "0001-storage.md").write_text(
"# ADR-0001\n\nStatus: accepted\n", encoding="utf-8"
)
result = run_audit(project, "adr")
assert result.returncode == 1
assert "ADR is missing from the canonical index" in result.stdout
def test_adr_scope_ignores_the_bundled_template(project: Path) -> None:
adr_dir = project / "docs" / "adr"
adr_dir.mkdir(parents=True)
(adr_dir / "README.md").write_text("# ADR index\n", encoding="utf-8")
(adr_dir / "template.md").write_text(
"# Title\n\nStatus: proposed\n", encoding="utf-8"
)
result = run_audit(project, "adr")
assert result.returncode == 0, result.stdout
def test_adr_scope_does_not_read_an_adr_symlinked_outside_project(
project: Path,
) -> None:
adr_dir = project / "docs" / "adr"
adr_dir.mkdir(parents=True)
outside = project.parent / "outside-adr.md"
outside.write_text("private ADR body\n", encoding="utf-8")
try:
(adr_dir / "README.md").write_text(
"[outside](0001-outside.md)\n", encoding="utf-8"
)
(adr_dir / "0001-outside.md").symlink_to(outside)
result = run_audit(project, "adr")
assert result.returncode == 1
assert "ADR source resolves outside the project root" in result.stdout
assert "private ADR body" not in result.stdout
finally:
outside.unlink(missing_ok=True)
def test_custom_role_map_supports_existing_adr_layout(project: Path) -> None:
adr_dir = project / "docs" / "architecture" / "decisions"
adr_dir.mkdir(parents=True)
(adr_dir / "README.md").write_text("[0001](0001-storage.md)\n", encoding="utf-8")
(adr_dir / "0001-storage.md").write_text(
"# ADR-0001\n\nStatus: accepted\n", encoding="utf-8"
)
governance = project / ".governance"
governance.mkdir()
(governance / "docs-map.json").write_text(
json.dumps(
{
"adr_dir": "docs/architecture/decisions",
"adr_index": "docs/architecture/decisions/README.md",
}
),
encoding="utf-8",
)
result = run_audit(project, "adr")
assert result.returncode == 0, result.stdout
assert "custom documentation role mapping" in result.stdout
def test_adr_scope_rejects_missing_index_link(project: Path) -> None:
adr_dir = project / "docs" / "adr"
adr_dir.mkdir(parents=True)
(adr_dir / "README.md").write_text("[missing](0002-missing.md)\n", encoding="utf-8")
result = run_audit(project, "adr")
assert result.returncode == 1
assert "ADR index link does not exist" in result.stdout
def test_adr_scope_rejects_missing_supersedes_target(project: Path) -> None:
adr_dir = project / "docs" / "adr"
adr_dir.mkdir(parents=True)
(adr_dir / "README.md").write_text("[new](0002-new.md)\n", encoding="utf-8")
(adr_dir / "0002-new.md").write_text(
"# ADR-0002\n\nStatus: accepted\n\n## Supersedes\n\n[old](0001-old.md)\n",
encoding="utf-8",
)
result = run_audit(project, "adr")
assert result.returncode == 1
assert "ADR Supersedes target does not exist" in result.stdout
def test_artifact_scope_rejects_unregistered_test_id_when_tests_ledger_exists(
project: Path,
) -> None:
docs = project / "docs"
docs.mkdir()
(project / "TESTS.md").write_text("# TESTS\n\nTEST-ORDER-001\n", encoding="utf-8")
(docs / "spec.md").write_text(
"Must be verified by TEST-ORDER-002.\n", encoding="utf-8"
)
result = run_audit(project, "artifacts")
assert result.returncode == 1
assert "TEST-IDs are missing from the test registry" in result.stdout
def test_artifact_scope_ignores_lowercase_test_hyphenated_prose(
project: Path,
) -> None:
(project / "TESTS.md").write_text("# TESTS\n\nTEST-ORDER-001\n", encoding="utf-8")
(project / "guide.md").write_text("Use a test-driven workflow.\n", encoding="utf-8")
result = run_audit(project, "artifacts")
assert result.returncode == 0, result.stdout
def test_artifact_scope_reports_a_non_utf8_test_registry(project: Path) -> None:
(project / "TESTS.md").write_bytes(b"\xff\xfe")
(project / "spec.md").write_text("Verified by TEST-ORDER-001.\n", encoding="utf-8")
result = run_audit(project, "artifacts")
assert result.returncode == 1
assert "Cannot read test registry as a UTF-8 regular file" in result.stdout
assert "Traceback" not in result.stderr
def test_log_move_to_archive_preserves_append_only_history(project: Path) -> None:
configure_git(project)
old = "# LOG\n\n## [2026-01-01] init | one\n## [2026-01-02] fix | two\n"
(project / "PROJECT_LOG.md").write_text(old, encoding="utf-8")
subprocess.run(["git", "add", "PROJECT_LOG.md"], cwd=project, check=True)
subprocess.run(
["git", "commit", "-m", "init"], cwd=project, capture_output=True, check=True
)
(project / "PROJECT_LOG.md").write_text(
"# LOG\n\n## [2026-01-02] fix | two\n", encoding="utf-8"
)
(project / "PROJECT_LOG.archive.md").write_text(
"# archive\n\n## [2026-01-01] init | one\n", encoding="utf-8"
)
result = run_audit(project, "spine")
assert result.returncode == 0, result.stdout
assert (
"Active and archived history remain append-only when combined" in result.stdout
)
def test_spine_scope_detects_recreated_root_level_deletion_zone_file(
project: Path,
) -> None:
(project / "PROJECT_STATUS.md").write_text(
"# Status\n\n## Deletion Zone\n\n- `legacy_parser.py`\n", encoding="utf-8"
)
(project / "legacy_parser.py").write_text("# recreated\n", encoding="utf-8")
result = run_audit(project, "spine")
assert result.returncode == 1
assert "Deletion-zone target has been recreated" in result.stdout
def test_spine_scope_detects_windows_path_deletion_zone_file(project: Path) -> None:
target = project / "subdir" / "legacy.py"
target.parent.mkdir()
target.write_text("# recreated\n", encoding="utf-8")
(project / "PROJECT_STATUS.md").write_text(
"# Status\n\n## Deletion Zone\n\n- `subdir\\\\legacy.py`\n",
encoding="utf-8",
)
result = run_audit(project, "spine")
assert result.returncode == 1
assert "Deletion-zone target has been recreated" in result.stdout
@pytest.mark.parametrize(
"value",
(
"ftp://example.com/legacy.py",
"mailto:legacy@example.com",
"urn:legacy:parser",
pytest.param(
r"..\legacy.py",
marks=pytest.mark.skipif(
sys.platform.startswith("win"),
reason="the Windows path would escape the temporary project",
),
),
),
)
def test_spine_scope_ignores_unsafe_deletion_zone_values(
project: Path, value: str
) -> None:
candidate = project / value
candidate.parent.mkdir(parents=True, exist_ok=True)
candidate.write_text("# unrelated\n", encoding="utf-8")
(project / "PROJECT_STATUS.md").write_text(
f"# Status\n\n## Deletion Zone\n\n- `{value}`\n", encoding="utf-8"
)
result = run_audit(project, "spine")
assert result.returncode == 0, result.stdout
def test_spine_scope_handles_missing_git_without_traceback(project: Path) -> None:
(project / "PROJECT_LOG.md").write_text(
"# LOG\n\n## [2026-01-01] init | one\n", encoding="utf-8"
)
result = subprocess.run(
[sys.executable, str(SCRIPT), "--root", str(project), "--scope", "spine"],
text=True,
capture_output=True,
check=False,
env={"PATH": ""},
)
assert result.returncode == 0, result.stdout
assert "Git history is unavailable" in result.stdout
assert "Traceback" not in result.stderr
def test_spine_scope_warns_when_root_has_no_git_head(project: Path) -> None:
(project / "PROJECT_LOG.md").write_text(
"# LOG\n\n## [2026-01-01] init | one\n", encoding="utf-8"
)
result = run_audit(project, "spine")
assert result.returncode == 0, result.stdout
assert "Git history is unavailable" in result.stdout
assert "append-only when combined" not in result.stdout
def test_log_duplicate_removal_is_detected(project: Path) -> None:
configure_git(project)
event = "## [2026-01-01] fix | same event\n"
(project / "PROJECT_LOG.md").write_text(
"# LOG\n\n" + event + event, encoding="utf-8"
)
subprocess.run(["git", "add", "PROJECT_LOG.md"], cwd=project, check=True)
subprocess.run(
["git", "commit", "-m", "init"], cwd=project, capture_output=True, check=True
)
(project / "PROJECT_LOG.md").write_text("# LOG\n\n" + event, encoding="utf-8")
result = run_audit(project, "spine")
assert result.returncode == 0, result.stdout
assert "1 working-tree history events differ from HEAD" in result.stdout
def test_role_map_rejects_absolute_paths(project: Path) -> None:
governance = project / ".governance"
governance.mkdir()
(governance / "docs-map.json").write_text(
json.dumps({"context": str(project / "CONTEXT.md")}), encoding="utf-8"
)
result = run_audit(project, "context")
assert result.returncode == 1
assert "must be repository-relative" in result.stdout
def test_role_map_rejects_a_directory_for_a_file_role(project: Path) -> None:
(project / "docs").mkdir()
governance = project / ".governance"
governance.mkdir()
(governance / "docs-map.json").write_text(
json.dumps({"context": "docs"}), encoding="utf-8"
)
result = run_audit(project, "context")
assert result.returncode == 1
assert "file role maps to a non-file" in result.stdout
def test_role_map_rejects_a_missing_mapped_source(project: Path) -> None:
governance = project / ".governance"
governance.mkdir()
(governance / "docs-map.json").write_text(
json.dumps({"contract": "docs/missing-contract.md"}), encoding="utf-8"
)
result = run_audit(project, "artifacts")
assert result.returncode == 1
assert "Mapped documentation source does not exist" in result.stdout
def test_role_map_does_not_follow_a_mapping_symlinked_outside_project(
project: Path,
) -> None:
governance = project / ".governance"
governance.mkdir()
outside = project.parent / "outside-map.json"
outside.write_text('{"context": "private-context.md"}\n', encoding="utf-8")
try:
(governance / "docs-map.json").symlink_to(outside)
result = run_audit(project, "context")
assert result.returncode == 1
assert "repository-contained regular file" in result.stdout
assert "private-context" not in result.stdout
finally:
outside.unlink(missing_ok=True)
def test_default_role_does_not_follow_a_symlink_outside_project(project: Path) -> None:
outside = project.parent / "outside-context.md"
outside.write_text("private context\n", encoding="utf-8")
try:
(project / "CONTEXT.md").symlink_to(outside)
result = run_audit(project, "context")
assert result.returncode == 1
assert "Documentation role resolves outside the project root" in result.stdout
assert "private context" not in result.stdout
finally:
outside.unlink(missing_ok=True)
def test_audit_does_not_modify_repository_files(project: Path) -> None:
(project / "guide.md").write_text("[missing](docs/missing.md)\n", encoding="utf-8")
before = {
path.relative_to(project): path.read_bytes()
for path in project.rglob("*")
if path.is_file()
}
result = run_audit(project, "full")
after = {
path.relative_to(project): path.read_bytes()
for path in project.rglob("*")
if path.is_file()
}
assert result.returncode == 1
assert after == before
@pytest.mark.parametrize("link", ("[guide](it's.md)", '[guide](it\'s.md "Guide)")'))
def test_artifact_scope_reports_missing_apostrophe_destination(
project: Path, link: str
) -> None:
(project / "index.md").write_text(link + "\n", encoding="utf-8")
result = run_audit(project, "artifacts")
assert result.returncode == 1, result.stdout
assert "Broken Markdown link" in result.stdout
assert "it's.md" in result.stdout
@pytest.mark.parametrize(
"link,filename",
(
(r"[guide](file\(1\).md)", "file(1).md"),
(r"[guide](file\).md)", "file).md"),
(r'[guide](file\(1\).md "Guide)")', "file(1).md"),
(r"[guide](<file\(1\).md>)", "file(1).md"),
),
)
def test_artifact_scope_resolves_escaped_destination_parentheses(
project: Path, link: str, filename: str
) -> None:
(project / filename).write_text("# Guide\n", encoding="utf-8")
(project / "index.md").write_text(link + "\n", encoding="utf-8")
result = run_audit(project, "artifacts")
assert result.returncode == 0, result.stdout + result.stderr
@pytest.mark.parametrize("scope", ("artifacts", "full"))
@pytest.mark.parametrize("usage", ("![diagram]", "![diagram][]", "![picture][diagram]"))
def test_audit_reports_missing_reference_images(
project: Path, scope: str, usage: str
) -> None:
(project / "index.md").write_text(
usage + "\n\n[diagram]: missing.png\n", encoding="utf-8"
)
result = run_audit(project, scope)
assert result.returncode == 1, result.stdout
assert "Broken Markdown link: 'index.md' -> 'missing.png'" in result.stdout
@pytest.mark.parametrize("usage", ("![diagram]", "![diagram][]"))
def test_artifact_scope_accepts_existing_reference_images(
project: Path, usage: str
) -> None:
(project / "diagram.png").write_bytes(b"image fixture")
(project / "index.md").write_text(
usage + "\n\n[diagram]: diagram.png\n", encoding="utf-8"
)
result = run_audit(project, "artifacts")
assert result.returncode == 0, result.stdout + result.stderr
def test_artifact_scope_ignores_escaped_reference_image_bracket(project: Path) -> None:
(project / "index.md").write_text(
r"!\[diagram]" + "\n\n[diagram]: missing.png\n", encoding="utf-8"
)
result = run_audit(project, "artifacts")
assert result.returncode == 0, result.stdout + result.stderr
@pytest.mark.parametrize("mapping", (b"\xff", b"{invalid json"))
def test_full_audit_reports_bad_role_map_and_continues_artifact_checks(
project: Path, mapping: bytes
) -> None:
(project / ".governance").mkdir()
(project / ".governance/docs-map.json").write_bytes(mapping)
(project / "index.md").write_text("[missing](missing-guide.md)\n", encoding="utf-8")
result = run_audit(project, "full")
assert result.returncode == 1
assert "Cannot read .governance/docs-map.json" in result.stdout
assert "Broken Markdown link: 'index.md' -> 'missing-guide.md'" in result.stdout
assert "Traceback" not in result.stderr
@pytest.mark.parametrize(
"link,filename",
(
(r"[guide](file\[1\].md)", "file[1].md"),
(r"[guide](it\'s.md)", "it's.md"),
(r'[guide](file\[1\].md "Guide)")', "file[1].md"),
(r"[guide](<it\'s.md>)", "it's.md"),
("[guide][docs]\n\n[docs]: " + r"file\[1\].md", "file[1].md"),
("[guide][docs]\n\n[docs]: " + r"it\'s.md", "it's.md"),
),
)
def test_artifact_scope_resolves_escaped_bracket_and_apostrophe_filenames(
project: Path, link: str, filename: str
) -> None:
(project / filename).write_text("# Guide\n", encoding="utf-8")
(project / "index.md").write_text(link + "\n", encoding="utf-8")
result = run_audit(project, "artifacts")
assert result.returncode == 0, result.stdout + result.stderr
@pytest.mark.parametrize("backslashes", range(5))
@pytest.mark.parametrize("usage", ("[diagram]", "[diagram][]"))
@pytest.mark.parametrize("scope", ("artifacts", "full"))
def test_audit_checks_reference_usage_after_even_backslash_runs(
project: Path, backslashes: int, usage: str, scope: str
) -> None:
(project / "index.md").write_text(
"\\" * backslashes + usage + "\n\n[diagram]: missing.png\n",
encoding="utf-8",
)
before = {path: path.read_bytes() for path in project.rglob("*") if path.is_file()}
result = run_audit(project, scope)
expected = 1 if backslashes % 2 == 0 else 0
assert result.returncode == expected, result.stdout + result.stderr
diagnostic = "Broken Markdown link: 'index.md' -> 'missing.png'"
assert (diagnostic in result.stdout) == (expected == 1), result.stdout
assert "Traceback" not in result.stderr
after = {path: path.read_bytes() for path in project.rglob("*") if path.is_file()}
assert after == before, "the actual audit CLI must not modify project files"