#!/usr/bin/env python3 """Deterministic floor for an explain-diff page. Usage: check_explanation.py Prints one PASS / WARN / FAIL line per check. Exit 1 when any check fails, 2 on a usage or read error. """ import json import re import subprocess import sys from html.parser import HTMLParser from pathlib import Path SECTIONS = ("background", "intuition", "code", "quiz") PRE_INLINE_TAGS = {"code", "span", "b", "strong", "em", "i", "mark", "a", "br"} BOX_DRAWING = re.compile("[─-╿]") ASCII_BOX = re.compile(r"\+-{3,}\+|\|\s{2,}\S.*\s{2,}\|") NAME = re.compile(r"^\d{4}-\d{2}-\d{2}-[a-z0-9]+(-[a-z0-9]+)*\.html$") REMOTE_TAG = re.compile( r"<(script|link|img|iframe|source|video|audio)\b[^>]*" r"\b(src|href)\s*=\s*[\"']?(https?:)?//", re.I) REMOTE_CSS = re.compile(r"@import|url\(\s*[\"']?(https?:)?//", re.I) EM_DASH = "—" class Page(HTMLParser): """Collects, in one pass, what the checks below need.""" def __init__(self): super().__init__(convert_charrefs=True) self.ids, self.toc_links, self.pre_bad_tags = set(), set(), set() self.lang, self.viewport, self.quiz_text = "", False, None self.pre_text, self.prose = [], [] self._pre = self._code = self._skip = 0 self._nav = self._quiz = False def handle_starttag(self, tag, attrs): attr = {k: v or "" for k, v in attrs} if attr.get("id"): self.ids.add(attr["id"]) if self._pre and tag not in PRE_INLINE_TAGS: self.pre_bad_tags.add(tag) handler = getattr(self, "_open_" + tag, None) if handler: handler(attr) def handle_endtag(self, tag): if tag == "pre": self._pre = max(0, self._pre - 1) elif tag == "code": self._code = max(0, self._code - 1) elif tag in ("script", "style"): self._skip, self._quiz = max(0, self._skip - 1), False elif tag == "nav": self._nav = False def handle_data(self, data): if self._quiz: self.quiz_text = (self.quiz_text or "") + data elif self._skip: return elif self._pre: self.pre_text.append(data) elif not self._code: self.prose.append(data) def _open_html(self, attr): self.lang = attr.get("lang", "").strip() def _open_meta(self, attr): if attr.get("name", "").lower() == "viewport": self.viewport = True def _open_nav(self, _attr): self._nav = True def _open_a(self, attr): href = attr.get("href", "") if self._nav and href.startswith("#"): self.toc_links.add(href[1:]) def _open_pre(self, _attr): self._pre += 1 def _open_code(self, _attr): self._code += 1 def _open_style(self, _attr): self._skip += 1 def _open_script(self, attr): self._skip += 1 self._quiz = attr.get("id") == "quiz-data" def check_name(path): if NAME.match(path.name): return [("PASS", "name", path.name)] return [("FAIL", "name", f"{path.name} must be YYYY-MM-DD-.html")] def check_location(path): try: out = subprocess.run( ["git", "-C", str(path.parent), "rev-parse", "--is-inside-work-tree"], capture_output=True, text=True, check=False).stdout.strip() except OSError: return [("WARN", "location", "git not found, location unchecked")] if out == "true": return [("FAIL", "location", "file sits inside a git work tree")] return [("PASS", "location", "outside any git work tree")] def check_self_contained(src): hits = REMOTE_TAG.findall(src) + REMOTE_CSS.findall(src) if hits: return [("FAIL", "self-contained", f"{len(hits)} remote resource(s)")] return [("PASS", "self-contained", "no remote script, style or media")] def check_head(page): out = [] if not page.lang: out.append(("FAIL", "lang", " has no lang attribute")) if not page.viewport: out.append(("FAIL", "viewport", "no viewport meta")) return out or [("PASS", "head", f"lang={page.lang}, viewport set")] def check_sections(page): missing = [s for s in SECTIONS if s not in page.ids] if missing: return [("FAIL", "sections", "missing id(s): " + ", ".join(missing))] unlinked = [s for s in SECTIONS if s not in page.toc_links] if unlinked: return [("FAIL", "toc", "