docs: close nav containment, HTML-comment, and whitespace link gaps

Nav validation rejects entries that are absolute or escape docs/ before
checking existence (a ../ value resolved against the wrong root and an
escaping entry would write its llms rendition outside the built site);
llms_txt applies the same containment when collecting prose pages. Block
HTML comments join fences and code spans as inert content, so commented-out
prose is neither validated nor rewritten. Link openings tolerate the
whitespace CommonMark allows after '(' - previously ']( page.md)' and
']( <x>)' dodged both the classifier and the angle-form rejection. And
check_crossrefs fails up front on a missing site directory instead of
scanning zero pages as a clean site.

Author: maxisbey

scripts/docs/build_config.py

@@ -12,6 +12,7 @@
 
 from __future__ import annotations
 
+import posixpath
 import re
 from pathlib import Path
 
@@ -52,6 +53,10 @@ def _validate_nav(nav: list, docs_dir: Path) -> None:
     generator that writes the files, so it cannot drift.
     """
     pages = _nav_pages(nav)
+    # Containment before existence: `docs_dir / page` would happily resolve
+    # an absolute value or a `../` escape against the wrong root.
+    if escaping := sorted(p for p in pages if p.startswith("/") or posixpath.normpath(p).startswith("..")):
+        raise SystemExit(f"build_config: nav references pages outside docs/: {escaping}")
     if missing := sorted(page for page in pages if not (docs_dir / page).is_file()):
         raise SystemExit(f"build_config: nav references pages that don't exist under docs/: {missing}")
     # Dot-directories (e.g. `.overrides` theme files) are not pages: the site

scripts/docs/check_crossrefs.py

@@ -130,12 +130,18 @@ def _origin(url: str) -> str:
 
 def main() -> None:
     parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("--site-dir", default="site", help="The built site directory to scan.")
+    parser.add_argument("--site-dir", default=str(ROOT / "site"), help="The built site directory to scan.")
     args = parser.parse_args()
 
+    site_dir = Path(args.site_dir)
+    # rglob on a missing directory yields nothing, which would read as a
+    # clean site (or a bogus inventory failure); fail up front instead.
+    if not site_dir.is_dir():
+        raise SystemExit(f"check_crossrefs: {site_dir} not found (run the build first)")
+
     unlinked = _inventory_origins()
     failures: list[str] = []
-    for page in sorted(Path(args.site_dir).rglob("*.html")):
+    for page in sorted(site_dir.rglob("*.html")):
         html = page.read_text(encoding="utf-8")
         if unlinked and "autorefs-external" in html:
             for tag in _EXTERNAL_REF.finditer(html):

scripts/docs/llms_txt.py

@@ -50,14 +50,17 @@
 # own link validation only covers .md targets (a missing image or
 # directory-style link builds green even under --strict; MkDocs failed the
 # build), so everything else is validated here.
-_LINK = re.compile(r'(\]\()([^)\s]+?)(#[^)\s]*)?( +(?:"[^"]*"|\'[^\']*\'|\([^()]*\)))?(\))')
+_LINK = re.compile(r'(\]\([ \t]*)([^)\s]+?)(#[^)\s]*)?( +(?:"[^"]*"|\'[^\']*\'|\([^()]*\)))?([ \t]*\))')
 # CommonMark forms the classifier deliberately rejects rather than models:
 # angle-bracket destinations `](<target>)` and reference-style definitions
 # `[label]: target` (footnote definitions `[^label]:` are a different,
 # supported syntax). Either would otherwise dodge validation by its spelling;
 # failing loud keeps the guarantee without modelling unused syntax.
-_ANGLE_LINK = re.compile(r"\]\(<")
+_ANGLE_LINK = re.compile(r"\]\([ \t]*<")
 _REF_DEFINITION = re.compile(r"^[ \t]*\[(?!\^)[^\]]+\]:", flags=re.MULTILINE)
+# Block HTML comments are inert in rendered output: python-markdown passes
+# them through verbatim, so commented-out prose must not be validated.
+_HTML_COMMENT = re.compile(r"<!--.*?-->", flags=re.DOTALL)
 # A scheme-prefixed target (https:, mailto:, tel:, ...) is external — the
 # `://` shorthand misses scheme-only URIs like mailto:.
 _EXTERNAL = re.compile(r"[a-zA-Z][a-zA-Z0-9+.-]*:")
@@ -132,6 +135,10 @@ def _collect_pages(items: list, prose: dict[str, str | None]) -> list[str]:
         if isinstance(value, list):
             pages.extend(_collect_pages(value, prose))
         elif not _EXTERNAL.match(value) and value.endswith(".md") and not value.startswith("api/"):
+            # Contained values only: an escaping entry would write its
+            # rendition outside the built site.
+            if value.startswith("/") or posixpath.normpath(value).startswith(".."):
+                raise _BuildError(f"llms_txt: nav entry {value!r} escapes docs/")
             prose[value] = title
             pages.append(value)
     return pages
@@ -218,7 +225,8 @@ def _code_intervals(markdown: str) -> list[tuple[int, int]]:
     previous_end = 0
     for fence_start, fence_end in [*fences, (len(markdown), len(markdown))]:
         segment = markdown[previous_end:fence_start]
-        intervals += [(previous_end + m.start(), previous_end + m.end()) for m in _CODE_SPAN.finditer(segment)]
+        for pattern in (_CODE_SPAN, _HTML_COMMENT):
+            intervals += [(previous_end + m.start(), previous_end + m.end()) for m in pattern.finditer(segment)]
         previous_end = fence_end
     return intervals