#!/usr/bin/env python3 """Check the user guide (`docs/guide/`) for what a machine can judge. The guide is read in three places: on GitHub, on luxe.dev, and by an agent. So its links are written the way a repository writes them, `configuration.md#github`, and the site rewrites them. This checks: frontmatter every page has a title, a summary, an order and a known group links every link to another page names a page that exists, and every anchor a heading on it; a site-style `/docs/...` link is refused, since it is dead on GitHub voice on a rewritten page: no lands/arrives/invariant, and an em-dash budget The config examples, flags and slash commands are checked against the code by the Rust test `guide_check` in `luxe-cli`, which knows the real types. python3 scripts/docs-check.py """ from __future__ import annotations import pathlib import re import sys ROOT = pathlib.Path(__file__).resolve().parent.parent GUIDE = ROOT / "docs" / "guide" # Sidebar groups, in order. `web/src/content.config.ts` holds the same list. GROUPS = ["Get started", "Using Luxe", "Customize", "Extend", "Reference"] # Pages exempt from the voice rules while a rewrite is in progress. Empty: every page follows them. # Links and frontmatter apply to every page regardless. PENDING: set[str] = set() # Words that read as generated, in the guide's prose. Matched as whole words, case-insensitively. BANNED = ["land", "lands", "landed", "arrive", "arrives", "arrived", "invariant", "invariants"] # At most one em dash per this many words of prose, and never fewer than this many allowed. DASH_WORDS = 250 DASH_FLOOR = 2 def split_frontmatter(text: str) -> tuple[dict[str, str], str]: if not text.startswith("---\n"): return {}, text end = text.index("\n---\n", 4) fields = {} for line in text[4:end].splitlines(): key, _, value = line.partition(":") fields[key.strip()] = value.strip().strip('"') return fields, text[end + 5 :] def without_code(text: str) -> str: """The page with fenced and inline code blanked, line count preserved.""" text = re.sub(r"```.*?```", lambda m: "\n" * m.group(0).count("\n"), text, flags=re.S) return re.sub(r"`[^`\n]*`", "", text) def slug(heading: str, seen: dict[str, int]) -> str: """The anchor github-slugger, which Astro uses, gives a heading.""" text = re.sub(r"`([^`]*)`", r"\1", heading) text = re.sub(r"\[([^\]]*)\]\([^)]*\)", r"\1", text) text = re.sub(r"[*_]", "", text).strip().lower() text = re.sub(r"[^\w\- ]", "", text) base = text.replace(" ", "-") count = seen.get(base, 0) seen[base] = count + 1 return base if count == 0 else f"{base}-{count}" def anchors(body: str) -> set[str]: seen: dict[str, int] = {} found = set() in_code = False for line in body.splitlines(): if line.startswith("```"): in_code = not in_code continue heading = re.match(r"#{1,6} (.+)", line) if heading and not in_code: found.add(slug(heading.group(1), seen)) return found def main() -> int: pages = {path.stem: path for path in sorted(GUIDE.glob("*.md"))} parsed = {name: split_frontmatter(path.read_text(encoding="utf-8")) for name, path in pages.items()} page_anchors = {name: anchors(body) for name, (_, body) in parsed.items()} problems: list[str] = [] for name in sorted(PENDING - pages.keys()): problems.append(f"scripts/docs-check.py: PENDING names {name}, which is not a page") for name, (fields, body) in parsed.items(): where = f"docs/guide/{name}.md" for key in ("title", "summary", "order", "group"): if not fields.get(key): problems.append(f"{where}: frontmatter has no {key}") if fields.get("group") and fields["group"] not in GROUPS: problems.append(f"{where}: group {fields['group']!r} is not one of {GROUPS}") prose = without_code(body) for number, line in enumerate(prose.splitlines(), start=1): for target in re.findall(r"\]\(([^)\s]+)\)", line): problem = check_link(target, name, pages, page_anchors) if problem: problems.append(f"{where}:{number + offset(fields)} {problem}: {target}") if name in PENDING: continue for number, line in enumerate(prose.splitlines(), start=1): for word in BANNED: if re.search(rf"\b{word}\b", line, re.IGNORECASE): problems.append(f"{where}:{number + offset(fields)} {word!r}: {line.strip()[:80]}") words = len(prose.split()) dashes = prose.count("\u2014") budget = max(DASH_FLOOR, words // DASH_WORDS) if dashes > budget: problems.append(f"{where}: {dashes} em dashes in {words} words; the budget is {budget}") if problems: print(f"docs check: {len(problems)} problem(s)") for problem in problems: print(f" {problem}") return 1 rewritten = len(pages) - len(PENDING & pages.keys()) print(f"docs check: {len(pages)} pages, {rewritten} rewritten, links and frontmatter clean") return 0 def offset(fields: dict[str, str]) -> int: """Lines the frontmatter takes, so a line number points into the file.""" return len(fields) + 2 if fields else 0 def check_link( target: str, page: str, pages: dict[str, pathlib.Path], page_anchors: dict[str, set[str]] ) -> str | None: if re.match(r"[a-z]+:", target): return None if target.startswith("/docs"): return "a site route, which is dead on GitHub; link the file, like `install.md`" if target.startswith("/"): return None file, _, anchor = target.partition("#") if file.removeprefix("./") in pages: return "a page without its file name; link the file, like `install.md`" if file.startswith("./"): return "a `./` prefix, which the site does not rewrite; link the file, like `install.md`" if file and not file.endswith(".md"): return None name = file.removesuffix(".md") if file else page if name not in pages: return "no such page" if anchor and anchor not in page_anchors[name]: return "no such heading" return None if __name__ == "__main__": sys.exit(main())