Coverage for scripts/check_diagrams.py: 100%
99 statements
« prev ^ index » next coverage.py v7.17.3, created at 2026-11-12 12:29 +0000
« prev ^ index » next coverage.py v7.17.3, created at 2026-11-12 12:29 +0000
1"""Fail when a Mermaid diagram in the docs does not parse (ADR 0014).
3`mkdocs build --strict` cannot catch it: the browser renders the diagrams, and a
4broken one shows its source on the live site in silence. This parses each one
5with the Mermaid file and hash that overrides/main.html pins for the site, in a headless
6Chromium-based browser: Chrome in CI, Edge on Windows.
7"""
9from __future__ import annotations
11import functools
12import html
13import http.server
14import json
15import os
16import re
17import shutil
18import subprocess
19import sys
20import tempfile
21import threading
22from pathlib import Path
24from mermaid_fences import ANY_FENCE, DIAGRAM
26# The tag the site loads (overrides/main.html): CI parses with the same file,
27# under the same integrity hash, so a changed file fails here as it would there.
28PINNED = re.compile(
29 r'<script src="(https://unpkg\.com/mermaid@[0-9.]+/dist/mermaid\.min\.js)"'
30 r'\s+integrity="(sha384-[A-Za-z0-9+/=]+)"'
31)
32OUT = re.compile(r'<pre id="out">(.*?)</pre>', re.DOTALL)
33BROWSERS = ("google-chrome", "chromium", "chromium-browser", "msedge")
34EDGE = Path(r"C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe")
35# Parsing is synchronous after the script loads; the budget covers the download.
36BUDGET_MS = 20_000
37SCRIPT = """
38mermaid.initialize({startOnLoad: false});
39(async () => {
40 const lines = [];
41 // render, not parse: some errors only appear when a diagram is laid out.
42 for (const [i, d] of DIAGRAMS.entries()) {
43 try { await mermaid.render("d" + i, d.src); lines.push("OK " + d.id); }
44 catch (e) { lines.push("FAIL " + d.id + ": " + String(e.message || e)); }
45 }
46 // JSON: a Mermaid error message spans several lines.
47 document.getElementById("out").textContent = JSON.stringify(lines);
48})();
49"""
52def documents(root: Path) -> list[Path]:
53 # The site includes CHANGELOG.md and MIGRATION.md from the root; the stubs
54 # in docs/ hold only the include line.
55 roots = [root / name for name in ("README.md", "CHANGELOG.md", "MIGRATION.md")]
56 return [*roots, *sorted((root / "docs").rglob("*.md"))]
59def scan(path: Path) -> tuple[list[dict[str, str]], list[str]]:
60 """The diagrams in a file, and every Mermaid fence written in another form.
62 Each fence is judged where it starts: counting them would let an extracted
63 example inside a ```` block hide an indented diagram nothing extracts.
64 """
65 text = path.read_text(encoding="utf-8")
66 found: list[dict[str, str]] = []
67 problems: list[str] = []
68 for fence in ANY_FENCE.finditer(text):
69 diagram = DIAGRAM.match(text, fence.start())
70 if diagram:
71 found.append({"id": f"{path}#{len(found) + 1}", "src": diagram.group(1)})
72 else:
73 line = text.count("\n", 0, fence.start()) + 1
74 problems.append(f"{path}:{line}: a Mermaid fence written in a form not checked")
75 return found, problems
78def unchecked(paths: list[Path]) -> list[str]:
79 return [problem for path in paths for problem in scan(path)[1]]
82def diagrams(paths: list[Path]) -> list[dict[str, str]]:
83 return [diagram for path in paths for diagram in scan(path)[0]]
86def site_mermaid(template: Path) -> tuple[str, str] | None:
87 """The pinned Mermaid URL and its integrity hash, as the site loads them."""
88 match = PINNED.search(template.read_text(encoding="utf-8"))
89 return (match.group(1), match.group(2)) if match else None
92def page(found: list[dict[str, str]], mermaid: tuple[str, str]) -> str:
93 # "<" escaped: a label holding "</script>" would end the script early.
94 data = json.dumps(found).replace("<", "\\u003c")
95 script = SCRIPT.replace("DIAGRAMS", data)
96 return (
97 '<html><body><pre id="out">pending</pre>'
98 f'<script src="{mermaid[0]}" integrity="{mermaid[1]}" crossorigin="anonymous">'
99 f"</script><script>{script}</script></body></html>"
100 )
103def failures(dom: str, expected: int) -> list[str]:
104 match = OUT.search(dom)
105 text = html.unescape(match.group(1)) if match else ""
106 try:
107 lines = json.loads(text)
108 except json.JSONDecodeError:
109 lines = [text]
110 # Anything but one verdict per diagram (the page left "pending" because
111 # Mermaid never loaded, a crash half-way) means nothing was proven.
112 verdicts = isinstance(lines, list) and all(
113 isinstance(line, str) and line.startswith(("OK ", "FAIL ")) for line in lines
114 )
115 if not verdicts or len(lines) != expected:
116 return [f"expected {expected} results, got: {lines!r}"]
117 return [line for line in lines if line.startswith("FAIL ")]
120class _QuietHandler(http.server.SimpleHTTPRequestHandler):
121 def log_message(self, format: str, *args: object) -> None:
122 """One request per run; the verdict is the output that matters."""
125def browser() -> str | None:
126 named = os.environ.get("DIAGRAM_BROWSER") or next(filter(shutil.which, BROWSERS), None)
127 if named:
128 return shutil.which(named) or named
129 return str(EDGE) if EDGE.is_file() else None
132def render(executable: str, content: str) -> subprocess.CompletedProcess[str]:
133 with tempfile.TemporaryDirectory() as directory:
134 Path(directory, "index.html").write_text(content, encoding="utf-8")
135 # Served over HTTP, not file://, where the browser may refuse the script.
136 handler = functools.partial(_QuietHandler, directory=directory)
137 with http.server.ThreadingHTTPServer(("127.0.0.1", 0), handler) as server:
138 threading.Thread(target=server.serve_forever, daemon=True).start()
139 url = f"http://127.0.0.1:{server.server_address[1]}/index.html"
140 # The browser sandbox stays on: the page runs a third-party script.
141 command = [
142 executable,
143 "--headless=new",
144 "--disable-gpu",
145 f"--virtual-time-budget={BUDGET_MS}",
146 "--dump-dom",
147 url,
148 ]
149 try:
150 # The verdict is the page, not the exit code: a browser that
151 # failed to start leaves no verdicts, which failures() reports.
152 # S603: the arguments are this script's own, no untrusted input.
153 return subprocess.run( # noqa: S603
154 command,
155 check=False,
156 capture_output=True,
157 # The DOM is UTF-8 whatever the locale, cp1252 on Windows.
158 encoding="utf-8",
159 errors="replace",
160 timeout=120,
161 )
162 finally:
163 server.shutdown()
166def main(argv: list[str]) -> int:
167 paths = documents(Path())
168 skipped = unchecked(paths)
169 if skipped:
170 print("\n".join([*skipped, "write each diagram as a ```mermaid fence at the line start"]))
171 return 1
172 found = diagrams(paths)
173 mermaid = site_mermaid(Path("overrides/main.html"))
174 if mermaid is None:
175 print("overrides/main.html: no pinned Mermaid with an integrity hash to check with")
176 return 1
177 executable = browser()
178 if executable is None:
179 print("no Chrome, Chromium or Edge found; set DIAGRAM_BROWSER")
180 return 1
181 try:
182 done = render(executable, page(found, mermaid))
183 except (OSError, subprocess.TimeoutExpired) as error:
184 print(f"could not run {executable}: {error}")
185 return 1
186 problems = failures(done.stdout, expected=len(found))
187 if problems and not any(problem.startswith("FAIL ") for problem in problems):
188 # No verdicts at all: the cause is in the browser's own output.
189 problems.append(f"browser exit {done.returncode}: {done.stderr[-2000:]}")
190 print("\n".join(problems) or f"all {len(found)} Mermaid diagrams parse")
191 return 1 if problems else 0
194if __name__ == "__main__":
195 sys.exit(main(sys.argv[1:]))