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

1"""Fail when a Mermaid diagram in the docs does not parse (ADR 0014). 

2 

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""" 

8 

9from __future__ import annotations 

10 

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 

23 

24from mermaid_fences import ANY_FENCE, DIAGRAM 

25 

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""" 

50 

51 

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"))] 

57 

58 

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. 

61 

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 

76 

77 

78def unchecked(paths: list[Path]) -> list[str]: 

79 return [problem for path in paths for problem in scan(path)[1]] 

80 

81 

82def diagrams(paths: list[Path]) -> list[dict[str, str]]: 

83 return [diagram for path in paths for diagram in scan(path)[0]] 

84 

85 

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 

90 

91 

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 ) 

101 

102 

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 ")] 

118 

119 

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.""" 

123 

124 

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 

130 

131 

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() 

164 

165 

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 

192 

193 

194if __name__ == "__main__": 

195 sys.exit(main(sys.argv[1:]))