- luxe starts on the model you last chose in this project, then the last one anywhere. Signing in opens the model picker instead of choosing for you. - Every list in a modal takes the mouse wheel and a draggable scrollbar. - The phone app shows reasoning in full, stays put while you read back through a long session, and shows a question's answer on its card. - On Windows, luxe update replaces the running luxe, and a signed-in install no longer sees setup again. - The file tree no longer shows "engine busy" in a large project, loop output is easier to follow, and the name is written lowercase. The CHANGELOG has the full list.
162 lines
6.2 KiB
Python
Executable File
162 lines
6.2 KiB
Python
Executable File
#!/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())
|