#!/usr/bin/env python3 """audit.py -- four-mode check of a built book: contrast and phone width. _extensions/notes/audit.py [--widths 320,1280] [--jobs 4] [--json out.json] is _book/ or a scratch render (quarto render --output-dir ...). It is copied to a temporary folder -- the build itself is never written to -- and audit-page.js is injected into a copy of every page. The copy is served on 127.0.0.2 (the language switcher is off on localhost) and each page is loaded in chrome-headless-shell at each width, with overlay scrollbars as on a phone. For light, dark, light + high contrast and dark + high contrast it prints the worst text contrast, every text below 4.5:1 (WCAG AA), and any page wider than the screen. Needs Playwright's headless shell: ~/.cache/ms-playwright/chromium_headless_shell-*/chrome-headless-shell-linux64/ """ import argparse, concurrent.futures as cf, glob, html, json, os, re, shutil, subprocess, sys, tempfile, threading from functools import partial from http.server import ThreadingHTTPServer, SimpleHTTPRequestHandler HERE = os.path.dirname(os.path.abspath(__file__)) SHELLS = sorted(glob.glob(os.path.expanduser( "~/.cache/ms-playwright/chromium_headless_shell-*/chrome-headless-shell-linux64/chrome-headless-shell"))) # the switcher redirects a page whose language differs from the remembered one PIN_LANG = ("") MODES = ["light", "dark", "light+hc", "dark+hc"] def mirror(src): dst = os.path.join(tempfile.mkdtemp(prefix="notes-audit-"), "site") shutil.copytree(src, dst, ignore=shutil.ignore_patterns("*.pdf", "*.ipynb", "*.zip")) shutil.copy(os.path.join(HERE, "audit-page.js"), os.path.join(dst, "__audit.js")) pages = [] for p in glob.glob(os.path.join(dst, "**", "*.html"), recursive=True): rel = os.path.relpath(p, dst) if "site_libs" in rel or "/figures/" in "/" + rel: continue s = open(p, encoding="utf-8").read() if "quarto" not in s or "", "" + PIN_LANG, s, count=1) s = s.replace("", '', 1) out = p[:-5] + ".audit.html" open(out, "w", encoding="utf-8").write(s) pages.append(os.path.relpath(out, dst)) return dst, sorted(pages) def load(shell, url, width): cmd = [shell, "--headless", "--disable-gpu", "--no-sandbox", "--hide-scrollbars", f"--window-size={width},900", "--virtual-time-budget=15000", "--dump-dom", url] try: dom = subprocess.run(cmd, capture_output=True, text=True, timeout=90).stdout except subprocess.TimeoutExpired: return {"error": "timeout"} m = re.search(r'data-audit="([^"]*)"', dom) return json.loads(html.unescape(m.group(1))) if m else {"error": "no result"} def main(): ap = argparse.ArgumentParser(description=__doc__.split("\n")[0]) ap.add_argument("built") ap.add_argument("--widths", default="320,1280") ap.add_argument("--port", type=int, default=0, help="0 = any free port") ap.add_argument("--jobs", type=int, default=4) ap.add_argument("--json") a = ap.parse_args() if not SHELLS: sys.exit("audit: no chrome-headless-shell under ~/.cache/ms-playwright") dst, pages = mirror(os.path.abspath(a.built)) class Quiet(SimpleHTTPRequestHandler): def log_message(self, *x): pass srv = ThreadingHTTPServer(("127.0.0.2", a.port), partial(Quiet, directory=dst)) port = srv.server_address[1] threading.Thread(target=srv.serve_forever, daemon=True).start() widths = [int(w) for w in a.widths.split(",")] jobs = [(p, w) for p in pages for w in widths] results = {} with cf.ThreadPoolExecutor(a.jobs) as ex: futs = {ex.submit(load, SHELLS[-1], f"http://127.0.0.2:{port}/{p}", w): (p, w) for p, w in jobs} for f in cf.as_completed(futs): results[futs[f]] = f.result() srv.shutdown() shutil.rmtree(os.path.dirname(dst), ignore_errors=True) worst = {n: (99, None) for n in MODES} fails, overflow, errors, flags_bad, no_toggle = [], [], [], [], set() for (p, w), r in sorted(results.items()): if "error" in r: errors.append(f"{p} @{w}: {r['error']}"); continue if not r.get("hasDarkToggle") or not r.get("hasHcButton"): no_toggle.add(p) for i, m in enumerate(r["modes"]): n = MODES[i] if m.get("skipped"): continue if m["dark"] != (i in (1, 3)) or m["hc"] != (i in (2, 3)): flags_bad.append(f"{p} @{w} {n}") if m["worst"] and m["worst"][0]["r"] < worst[n][0]: worst[n] = (m["worst"][0]["r"], f"{p} @{w}: {m['worst'][0]['el']} «{m['worst'][0]['text']}»") for fl in m["failList"]: fails.append((fl["r"], n, w, p, fl["el"], fl["text"], fl["fg"])) if m["overflowCount"] or m["docWidth"] > m["W"]: overflow.append((n, w, p, m["docWidth"], m["W"], m["overflow"][:3])) print(f"pages: {len(pages)} widths: {widths} runs: {len(jobs)} errors: {len(errors)}") if no_toggle: print(f"WITHOUT dark toggle or ◐ button: {len(no_toggle)} page(s), e.g. {sorted(no_toggle)[0]}") if flags_bad: print("MODE FLAGS WRONG:", flags_bad[:5]) for n in MODES: print(f" worst {n:9s} {worst[n][0]:6.2f} {worst[n][1] or '(not measured)'}") uniq = {} for f in sorted(fails): uniq.setdefault((f[1], f[4], f[6]), f) print(f"text below 4.5: {len(fails)} element-runs, {len(uniq)} distinct (mode, element, colour)") for f in list(uniq.values())[:25]: print(f" {f[0]:5.2f} {f[1]:9s} @{f[2]} {f[3]}: {f[4]} «{f[5]}» {f[6]}") print(f"overflow: {len(overflow)} page-runs") for o in overflow[:10]: print(f" {o[0]} @{o[1]} {o[2]}: page {o[3]}px in a {o[4]}px screen {o[5]}") for e in errors[:10]: print(" ERROR", e) if a.json: json.dump({f"{p}@{w}": r for (p, w), r in results.items()}, open(a.json, "w"), indent=1) sys.exit(1 if (fails or overflow or errors or flags_bad) else 0) if __name__ == "__main__": main()