Adapted from Geoffrey Litt's explain-diff gist: background, intuition, grouped code walkthrough, 5-question quiz, saved outside the repo. Bundled template, components catalog and checker with its test suite. Row reflect; profiles full, max, dev.
255 lines
8.4 KiB
Python
Executable File
255 lines
8.4 KiB
Python
Executable File
#!/usr/bin/env python3
|
|
"""Deterministic floor for an explain-diff page.
|
|
|
|
Usage: check_explanation.py <file.html>
|
|
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-<slug>.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", "<html> 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", "<nav> lacks link(s) to: "
|
|
+ ", ".join(unlinked))]
|
|
return [("PASS", "sections", "4 sections, all linked from the TOC")]
|
|
|
|
|
|
def question_problems(index, question):
|
|
text = question.get("q", "") if isinstance(question, dict) else ""
|
|
if not str(text).strip():
|
|
return [f"Q{index} has no text"]
|
|
options = question.get("options")
|
|
if not isinstance(options, list) or len(options) < 3:
|
|
return [f"Q{index} needs 3 options or more"]
|
|
out = []
|
|
right = [o for o in options
|
|
if isinstance(o, dict) and o.get("correct") is True]
|
|
if len(right) != 1:
|
|
out.append(f"Q{index} needs exactly one correct option")
|
|
for number, option in enumerate(options, 1):
|
|
filled = isinstance(option, dict) and all(
|
|
str(option.get(k, "")).strip() for k in ("text", "why"))
|
|
if not filled:
|
|
out.append(f"Q{index} option {number} lacks text or why")
|
|
return out
|
|
|
|
|
|
def load_quiz(page):
|
|
try:
|
|
quiz = json.loads(page.quiz_text or "")
|
|
except ValueError as err:
|
|
return None, f"quiz-data is missing or not JSON ({err})"
|
|
if not isinstance(quiz, list) or len(quiz) != 5:
|
|
count = len(quiz) if isinstance(quiz, list) else "not a list"
|
|
return None, f"want 5 questions, got {count}"
|
|
return quiz, None
|
|
|
|
|
|
def check_quiz(page):
|
|
quiz, error = load_quiz(page)
|
|
if error:
|
|
return [("FAIL", "quiz", error)]
|
|
problems = [p for i, q in enumerate(quiz, 1)
|
|
for p in question_problems(i, q)]
|
|
if problems:
|
|
return [("FAIL", "quiz", "; ".join(problems))]
|
|
return [("PASS", "quiz", "5 questions, one right answer each, explained")]
|
|
|
|
|
|
def quiz_strings(page):
|
|
quiz, error = load_quiz(page)
|
|
if error:
|
|
return []
|
|
out = []
|
|
for question in quiz:
|
|
if isinstance(question, dict):
|
|
out.append(str(question.get("q", "")))
|
|
for option in question.get("options") or []:
|
|
if isinstance(option, dict):
|
|
out += [str(option.get("text", "")),
|
|
str(option.get("why", ""))]
|
|
return out
|
|
|
|
|
|
def check_code_blocks(page):
|
|
out = []
|
|
if page.pre_bad_tags:
|
|
tags = ", ".join(sorted(page.pre_bad_tags))
|
|
out.append(("FAIL", "escaping",
|
|
f"markup <{tags}> inside <pre>: code left unescaped?"))
|
|
text = "".join(page.pre_text)
|
|
if BOX_DRAWING.search(text):
|
|
out.append(("FAIL", "ascii-art", "box-drawing characters in <pre>"))
|
|
elif ASCII_BOX.search(text):
|
|
out.append(("WARN", "ascii-art", "a <pre> looks like an ASCII box"))
|
|
return out or [("PASS", "code", "code blocks escaped, no ASCII diagram")]
|
|
|
|
|
|
def check_prose(page, src):
|
|
out = []
|
|
text = "".join(page.prose) + " ".join(quiz_strings(page))
|
|
dashes = text.count(EM_DASH)
|
|
if dashes:
|
|
out.append(("FAIL", "em-dash", f"{dashes} em-dash(es) in the prose"))
|
|
if "{{" in src:
|
|
out.append(("FAIL", "placeholders", "template placeholder left"))
|
|
return out or [("PASS", "prose", "no em-dash, no placeholder left")]
|
|
|
|
|
|
def run_checks(path, src, page):
|
|
return (check_name(path) + check_location(path)
|
|
+ check_self_contained(src) + check_head(page)
|
|
+ check_sections(page) + check_quiz(page)
|
|
+ check_code_blocks(page) + check_prose(page, src))
|
|
|
|
|
|
def main(argv):
|
|
if len(argv) != 2:
|
|
print(__doc__.strip())
|
|
return 2
|
|
path = Path(argv[1]).expanduser().resolve()
|
|
try:
|
|
src = path.read_text(encoding="utf-8")
|
|
except (OSError, UnicodeDecodeError) as err:
|
|
print(f"ERROR cannot read {path}: {err}")
|
|
return 2
|
|
page = Page()
|
|
page.feed(src)
|
|
page.close()
|
|
results = run_checks(path, src, page)
|
|
for level, name, detail in results:
|
|
print(f"{level} {name}: {detail}")
|
|
failed = sum(1 for level, _, _ in results if level == "FAIL")
|
|
print(f"{'FAIL' if failed else 'OK'}: {failed} failing check(s)")
|
|
return 1 if failed else 0
|
|
|
|
|
|
if __name__ == "__main__":
|
|
sys.exit(main(sys.argv))
|