tods-validate/tests/test_doc_currency.py at main · ghzhost/tods-validate · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
"""Currency stamps are checked, not just written (DOC-15).

A `Last verified:` line is a claim about the outside world. These pin that the
claim is falsifiable: edit the page without re-verifying it and the check fails.
"""

from __future__ import annotations

import importlib.util
import sys
from pathlib import Path
from types import ModuleType

import pytest

ROOT = Path(__file__).parent.parent
SCRIPT = ROOT / "scripts" / "check_doc_currency.py"


def _checker() -> ModuleType:
    spec = importlib.util.spec_from_file_location("check_doc_currency", SCRIPT)
    assert spec is not None
    assert spec.loader is not None
    module = importlib.util.module_from_spec(spec)
    sys.modules[spec.name] = module
    spec.loader.exec_module(module)
    return module


def test_the_committed_stamps_are_current() -> None:
    assert _checker().main() == 0


@pytest.mark.parametrize("relative", ["docs/getting-started.md", "docs/api.md"])
def test_editing_a_stamped_page_fails_until_it_is_re_verified(
    relative: str, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
    checker = _checker()
    staged = tmp_path / relative
    staged.parent.mkdir(parents=True, exist_ok=True)
    original = (ROOT / relative).read_text(encoding="utf-8")
    staged.write_text(original, encoding="utf-8")
    monkeypatch.setattr(checker, "ROOT", tmp_path)
    assert checker.check(relative) == []

    staged.write_text(original + "\nA claim nobody verified.\n", encoding="utf-8")
    problems = checker.check(relative)
    assert problems, "an edited page must not stay stamped as verified"
    assert "changed since it was last verified" in problems[0]


def test_a_missing_stamp_is_reported(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
    checker = _checker()
    relative = "docs/api.md"
    staged = tmp_path / relative
    staged.parent.mkdir(parents=True, exist_ok=True)
    staged.write_text("# Python API\n\nNo stamp here.\n", encoding="utf-8")
    monkeypatch.setattr(checker, "ROOT", tmp_path)
    problems = checker.check(relative)
    assert any("Last verified" in problem for problem in problems)
    assert any("Recheck cadence" in problem for problem in problems)
    assert any("no fingerprint" in problem for problem in problems)


def test_the_fingerprint_a_first_run_prints_is_the_one_that_verifies(tmp_path: Path) -> None:
    # The hash covers the page but not the line holding the hash, so writing it
    # down must not change it. Otherwise recording a stamp is unresolvable.
    checker = _checker()
    page = "# Doc\n\nLast verified: 2026-08-14\nRecheck cadence: every release\n\n"
    unstamped = page + "<!-- doc-currency: sha256=PLACEHOLDER -->\n"
    computed = checker.fingerprint(unstamped)
    stamped = page + f"<!-- doc-currency: sha256={computed} -->\n"
    assert checker.fingerprint(stamped) == computed


def test_a_future_verified_date_is_rejected(
    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
    checker = _checker()
    relative = "docs/api.md"
    staged = tmp_path / relative
    staged.parent.mkdir(parents=True, exist_ok=True)
    body = "# Doc\n\nLast verified: 2999-01-01\nRecheck cadence: every release\n\n"
    staged.write_text(
        body + f"<!-- doc-currency: sha256={checker.fingerprint(body)} -->\n", encoding="utf-8"
    )
    monkeypatch.setattr(checker, "ROOT", tmp_path)
    assert any("in the future" in problem for problem in checker.check(relative))