test: adopt the stricter ADR citation check from lite-bootstrap (#120)

Author: lesnik512

tests/test_adr_citations.py

@@ -9,45 +9,65 @@
 
 _ADR_DIR: typing.Final = "docs/adr/"
 _CITATION: typing.Final = re.compile(r"docs/adr/\d{4}(?:-[a-z0-9-]+\.md)?")
+_NUMBER_PREFIX: typing.Final = "ADR-"
+_NUMBER_CITATION: typing.Final = re.compile(_NUMBER_PREFIX + r"\d{4}")
 _UNWALKED_DIR: typing.Final = "node_modules"
+# mkdocs build output: a second copy of docs/, whose citations are the originals'.
+_GENERATED_DIR: typing.Final = "site"
+_SCANNED_SUFFIXES: typing.Final = (".py", ".md", ".toml")
 
 
-def _python_files(root: pathlib.Path) -> list[pathlib.Path]:
+def _scanned_files(root: pathlib.Path) -> list[pathlib.Path]:
     found: list[pathlib.Path] = []
     for dirpath, dirnames, filenames in os.walk(root):
-        dirnames[:] = sorted(name for name in dirnames if not name.startswith(".") and name != _UNWALKED_DIR)
-        found.extend(pathlib.Path(dirpath, name) for name in sorted(filenames) if name.endswith(".py"))
+        dirnames[:] = sorted(
+            name for name in dirnames if not name.startswith(".") and name not in (_UNWALKED_DIR, _GENERATED_DIR)
+        )
+        found.extend(pathlib.Path(dirpath, name) for name in sorted(filenames) if name.endswith(_SCANNED_SUFFIXES))
     return found
 
 
-def _citations(source: str) -> set[str]:
+def _citations(file: pathlib.Path, source: str) -> set[str]:
     texts = [source]
-    texts.extend(
-        node.value
-        for node in ast.walk(ast.parse(source))
-        if isinstance(node, ast.Constant) and isinstance(node.value, str)
-    )
-    return {cited for text in texts for cited in _CITATION.findall(text)}
+    if file.suffix == ".py":
+        # Adjacent literals are joined at parse time, so a path split across them is one string
+        # in the AST and two fragments in the raw text.
+        texts.extend(
+            node.value
+            for node in ast.walk(ast.parse(source))
+            if isinstance(node, ast.Constant) and isinstance(node.value, str)
+        )
+    return {cited for text in texts for pattern in (_CITATION, _NUMBER_CITATION) for cited in pattern.findall(text)}
+
+
+def _resolves(root: pathlib.Path, cited: str) -> bool:
+    if cited.startswith(_ADR_DIR):
+        return (root / cited).is_file()
+    return any((root / _ADR_DIR).glob(f"{cited.removeprefix(_NUMBER_PREFIX)}-*.md"))
 
 
 def unresolved_citations(root: pathlib.Path) -> list[tuple[str, str]]:
     return sorted(
         (file.relative_to(root).as_posix(), cited)
-        for file in _python_files(root)
-        for cited in _citations(file.read_text(encoding="utf-8"))
-        if not (root / cited).is_file()
+        for file in _scanned_files(root)
+        for cited in _citations(file, file.read_text(encoding="utf-8"))
+        if not _resolves(root, cited)
     )
 
 
-def test_every_adr_path_cited_from_python_resolves(pytestconfig: pytest.Config) -> None:
-    """INVARIANT: a `docs/adr/NNNN-<slug>.md` path named anywhere in this repo's Python exists.
+def test_every_adr_citation_in_the_repo_resolves(pytestconfig: pytest.Config) -> None:
+    """INVARIANT: every ADR named in this repo resolves, by full path or by bare `ADR-NNNN` number.
 
-    Broken by renaming, renumbering or pruning an ADR without following its citations. The
-    offline link gate reads Markdown only, so a path in a docstring, a comment or a guard message
-    is otherwise checked by nothing, and an `INVARIANT:` docstring that names its ADR silently
-    loses the rationale the test depends on. A user who trips a guard is handed a link to follow.
-    A bare `docs/adr/NNNN` is reported as well: it names no file, so it would survive the same
-    rename or drop unnoticed and point at whatever record holds that number next.
+    Broken by renaming, renumbering or pruning an ADR without following its citations. The offline
+    link gate reads Markdown links only, so a path in a docstring, a comment, a guard message or a
+    `pyproject.toml` dependency rationale is otherwise checked by nothing, and neither is the bare
+    number form, which is how most of them are written. A user who trips a guard is handed a link
+    to follow.
+
+    The number form is checked for existence only: a citation renumbered onto a *different* live
+    ADR still resolves, and nothing here can know it now names the wrong decision.
+    A bare `docs/adr/NNNN` path is reported outright: it names no file, so it would survive a
+    rename or a drop unnoticed and point at whatever record holds that number next.
     """
     unresolved = unresolved_citations(pytestconfig.rootpath)
 
@@ -67,18 +87,6 @@ def test_a_citation_of_a_missing_adr_is_reported_with_its_citing_file(tmp_path:
     assert unresolved_citations(tmp_path) == [("pkg/mod.py", f"{_ADR_DIR}9999-missing.md")]
 
 
-def test_a_short_form_citation_is_reported_even_when_the_adr_exists(tmp_path: pathlib.Path) -> None:
-    """`docs/adr/NNNN` with no slug names nothing on disk, so a rename or a drop never breaks it."""
-    (tmp_path / _ADR_DIR).mkdir(parents=True)
-    (tmp_path / _ADR_DIR / "0002-kept.md").write_text("# kept\n", encoding="utf-8")
-    (tmp_path / "pkg").mkdir()
-    (tmp_path / "pkg" / "mod.py").write_text(
-        f'"""Argued in {_ADR_DIR}0002 and {_ADR_DIR}0002-kept.md."""\n', encoding="utf-8"
-    )
-
-    assert unresolved_citations(tmp_path) == [("pkg/mod.py", f"{_ADR_DIR}0002")]
-
-
 def test_a_citation_split_across_adjacent_string_literals_is_found(tmp_path: pathlib.Path) -> None:
     """Python joins adjacent literals at parse time, which is what the `nack` guard message relies on."""
     (tmp_path / "guard.py").write_text(
@@ -96,6 +104,41 @@ def test_a_citation_inside_a_hash_comment_is_found(tmp_path: pathlib.Path) -> No
     assert unresolved_citations(tmp_path) == [("graph.py", f"{_ADR_DIR}0009-comment.md")]
 
 
+def test_a_bare_adr_number_naming_no_file_is_reported(tmp_path: pathlib.Path) -> None:
+    """A renumber leaves `ADR-NNNN` prose behind; only the path form was ever checked."""
+    (tmp_path / _ADR_DIR).mkdir(parents=True)
+    (tmp_path / _ADR_DIR / "0001-kept.md").write_text("# kept\n", encoding="utf-8")
+    (tmp_path / "smoke.py").write_text(
+        f"# the constraint {_NUMBER_PREFIX}0001 records, unlike {_NUMBER_PREFIX}9999\n", encoding="utf-8"
+    )
+
+    assert unresolved_citations(tmp_path) == [("smoke.py", f"{_NUMBER_PREFIX}9999")]
+
+
+def test_a_bare_adr_path_is_reported_even_when_the_adr_exists(tmp_path: pathlib.Path) -> None:
+    """`docs/adr/NNNN` with no slug names nothing on disk, so a rename or a drop never breaks it."""
+    (tmp_path / _ADR_DIR).mkdir(parents=True)
+    (tmp_path / _ADR_DIR / "0002-kept.md").write_text("# kept\n", encoding="utf-8")
+    (tmp_path / "pkg").mkdir()
+    (tmp_path / "pkg" / "mod.py").write_text(
+        f'"""Argued in {_ADR_DIR}0002 and {_ADR_DIR}0002-kept.md."""\n', encoding="utf-8"
+    )
+
+    assert unresolved_citations(tmp_path) == [("pkg/mod.py", f"{_ADR_DIR}0002")]
+
+
+def test_a_citation_outside_python_is_found(tmp_path: pathlib.Path) -> None:
+    """`pyproject.toml` explains dependency floors by citing ADRs, and Markdown cites them in prose."""
+    (tmp_path / _ADR_DIR).mkdir(parents=True)
+    (tmp_path / "pyproject.toml").write_text(f"# see {_ADR_DIR}0002-floor.md\ndeps = []\n", encoding="utf-8")
+    (tmp_path / "AGENTS.md").write_text(f"Read {_NUMBER_PREFIX}0004 before editing.\n", encoding="utf-8")
+
+    assert unresolved_citations(tmp_path) == [
+        ("AGENTS.md", f"{_NUMBER_PREFIX}0004"),
+        ("pyproject.toml", f"{_ADR_DIR}0002-floor.md"),
+    ]
+
+
 def test_a_tree_with_no_citations_and_no_adr_directory_reports_nothing(tmp_path: pathlib.Path) -> None:
     (tmp_path / "plain.py").write_text("X = 1\n", encoding="utf-8")