ci: link gate checks the staged Pages tree; exit-code gate resolves named codes

Two gates passed because authors were careful, not because they enforced it.

Link gate: pages.yml ran tests/check_site_links.py on docs/ and only then
stripped contact/asset sheets, DESIGN_NOTES.md and *.md into _site. A link to a
stripped file passed CI and 404'd in production.
- scripts/site/stage_public.py is now the single staging list; pages.yml and
  validate-site both stage with it and check `--root _site`.
- check_site_links.py takes --root (default docs/ for quick local runs).
Falsified: a probe link to gallery/contact-sheets/anvil-contact-sheet.webp
passes the old docs/ check (0 failures) and fails the staged check (1).

Exit-code gate: visit_Return recorded only int literals, so `return
EXIT_CLIPPED` (12), framing passthroughs (10) and `raise SystemExit(N)` were
invisible. Now resolved: module-level int constants, shared-helper constants
and check functions read from examples/gallery_*.py (check_framing 10,
check_asset_quality 11) including `fcode = check_framing(...); return fcode`,
and raise SystemExit. All current codes are documented (passes).
Falsified: deleting the `12` row from sky-texture-sun-elevation's README fails
the new checker at :719; the old checker still passed.

Not done: flagging every unresolvable `return name` in main as unanalyzable.
277 such returns exist and all pass through other functions' results, whose
own returns are already scanned; flagging them would be noise, not signal.

Closes #325

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: TMHSDigital

.github/workflows/pages.yml

@@ -92,19 +92,14 @@ jobs:
         # drift from gallery.json. The committed docs/gallery/assets/*.webp are untouched.
         run: python scripts/build_gallery.py
 
-      - name: Check every internal link, anchor and image alt
-        run: python tests/check_site_links.py
+      - name: Stage the public site (leave out internal docs and unlinked sheets)
+        run: python scripts/site/stage_public.py --src docs --out _site
 
-      - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6
+      - name: Check every internal link, anchor and image alt (on the staged tree)
+        # Checked after staging so a link to a stripped file fails here, not in production.
+        run: python tests/check_site_links.py --root _site
 
-      - name: Stage the public site (leave out internal docs and unlinked sheets)
-        # Everything stays in the repo; only the Pages artifact shrinks. No
-        # published page links to any of these (tests/check_site_links.py).
-        run: |
-          mkdir -p _site
-          cp -r docs/. _site/
-          rm -rf _site/gallery/contact-sheets _site/gallery/asset-sheets _site/gallery/DESIGN_NOTES.md
-          rm -f _site/*.md
+      - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6
 
       - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5
         with:

.github/workflows/validate.yml

@@ -136,8 +136,11 @@ jobs:
       - name: Build landing page into docs/
         run: python scripts/site/build_site.py --repo-root . --out docs
 
-      - name: Check every internal link, anchor and image alt
-        run: python tests/check_site_links.py
+      - name: Stage the public site exactly as pages.yml does
+        run: python scripts/site/stage_public.py --src docs --out _site
+
+      - name: Check every internal link, anchor and image alt (on the staged tree)
+        run: python tests/check_site_links.py --root _site
 
   validate-manifest:
     name: Validate plugin manifest

.gitignore

@@ -48,3 +48,6 @@ build/
 
 # Playwright MCP session captures (screenshots, console logs)
 .playwright-mcp/
+
+# Staged Pages tree (scripts/site/stage_public.py)
+_site/

scripts/site/stage_public.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""Stage the public Pages tree: copy docs/ and drop what is not published.
+
+    python scripts/site/stage_public.py --src docs --out _site
+
+Everything stays in the repo; only the Pages artifact shrinks. The internal
+docs (docs/*.md, gallery/DESIGN_NOTES.md) and the unlinked contact/asset sheets
+are left out. pages.yml deploys this tree and validate-site checks it, and
+tests/check_site_links.py runs against it, so a published link to a stripped
+file fails CI instead of 404ing in production. Keep EXCLUDE the single list.
+"""
+from __future__ import annotations
+
+import argparse
+import shutil
+import sys
+from pathlib import Path
+
+# Paths relative to --src; top-level *.md files are dropped too (see stage()).
+EXCLUDE_DIRS = ("gallery/contact-sheets", "gallery/asset-sheets")
+EXCLUDE_FILES = ("gallery/DESIGN_NOTES.md",)
+
+
+def stage(src: Path, out: Path) -> None:
+    if out.exists():
+        shutil.rmtree(out)
+    shutil.copytree(src, out)
+    for d in EXCLUDE_DIRS:
+        shutil.rmtree(out / d, ignore_errors=True)
+    for f in EXCLUDE_FILES:
+        (out / f).unlink(missing_ok=True)
+    for md in out.glob("*.md"):
+        md.unlink()
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--src", type=Path, default=Path("docs"))
+    ap.add_argument("--out", type=Path, default=Path("_site"))
+    a = ap.parse_args(argv)
+    if not (a.src / "index.html").is_file():
+        print(f"ERROR: {a.src / 'index.html'} missing; build the site first", file=sys.stderr)
+        return 2
+    stage(a.src, a.out)
+    print(f"staged {a.src} -> {a.out}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tests/check_exit_code_readme.py

@@ -6,7 +6,15 @@
 Detection (AST only):
 
 - Integer literals on `return` in the file's own functions, plus literal
-  `sys.exit(N)`.
+  `sys.exit(N)` and `raise SystemExit(N)`.
+- Named codes resolve too: a module-level `NAME = <int>` constant
+  (`return EXIT_CLIPPED`), a shared-helper constant
+  (`gallery_framing.EXIT_FRAMING`), a shared-helper check call
+  (`return gallery_framing.check_framing(...)` is 10), and a local name
+  assigned from one (`fcode = gallery_framing.check_framing(...)`;
+  `return fcode`). Helper codes are read from examples/gallery_*.py, not
+  hardcoded. A `return name` that resolves to none of these is a pass-through
+  of another function's result; that function's own returns are scanned.
 - `sys.exit(main())` and `sys.exit(name)` where `name` is assigned from a
   local function call (both headless templates: `exit_code = main()`) are
   harness pass-through, not unanalyzable.
@@ -81,6 +89,51 @@ def module_function_names(tree):
     return names
 
 
+def module_int_constants(tree):
+    """Module-level `NAME = <int literal>` bindings."""
+    consts = {}
+    for node in tree.body:
+        if isinstance(node, ast.Assign) and len(node.targets) == 1                 and isinstance(node.targets[0], ast.Name):
+            code = int_literal(node.value)
+            if code is not None:
+                consts[node.targets[0].id] = code
+    return consts
+
+
+def load_helper_codes():
+    """Exit codes of the shared render-gate helpers (examples/gallery_*.py).
+
+    Returns ({(module, CONST): code}, {(module, func): code}) where func is a
+    helper function whose non-zero return is a module constant.
+    """
+    consts, funcs = {}, {}
+    base = os.path.join(ROOT, "examples")
+    for name in sorted(os.listdir(base)):
+        if not (name.startswith("gallery_") and name.endswith(".py")):
+            continue
+        mod = name[:-3]
+        tree = ast.parse(open(os.path.join(base, name), encoding="utf-8").read())
+        mconsts = module_int_constants(tree)
+        for k, v in mconsts.items():
+            consts[(mod, k)] = v
+        for node in tree.body:
+            if isinstance(node, ast.FunctionDef):
+                for r in ast.walk(node):
+                    if isinstance(r, ast.Return) and isinstance(r.value, ast.Name)                             and mconsts.get(r.value.id):
+                        funcs[(mod, node.name)] = mconsts[r.value.id]
+    return consts, funcs
+
+
+HELPER_CONSTS, HELPER_FUNCS = load_helper_codes()
+
+
+def _dotted(node):
+    """('mod', 'attr') for `mod.attr`, else None."""
+    if isinstance(node, ast.Attribute) and isinstance(node.value, ast.Name):
+        return (node.value.id, node.attr)
+    return None
+
+
 def is_passthrough_call(node, func_names):
     """sys.exit(main()) — Call of a function defined in this module."""
     return (
@@ -91,18 +144,39 @@ def is_passthrough_call(node, func_names):
 
 
 class ExitVisitor(ast.NodeVisitor):
-    def __init__(self, func_names):
+    def __init__(self, func_names, consts=None):
         self.func_names = func_names
+        self.consts = consts or {}
         self.stack = []
         self.scope_binds = [{}]
+        self.code_binds = [{}]  # name -> code, per function scope
         self.literals = []  # (code, lineno)
         self.unanalyzable = []  # (lineno, snippet)
 
     def _push_scope(self):
         self.scope_binds.append({})
+        self.code_binds.append({})
 
     def _pop_scope(self):
         self.scope_binds.pop()
+        self.code_binds.pop()
+
+    def resolve_code(self, node):
+        """Exit code a returned/exited expression names, or None if not static."""
+        code = int_literal(node)
+        if code is not None:
+            return code
+        if isinstance(node, ast.Name):
+            for binds in reversed(self.code_binds):
+                if node.id in binds:
+                    return binds[node.id]
+            return self.consts.get(node.id)
+        dotted = _dotted(node)
+        if dotted in HELPER_CONSTS:
+            return HELPER_CONSTS[dotted]
+        if isinstance(node, ast.Call):
+            return HELPER_FUNCS.get(_dotted(node.func))
+        return None
 
     def _bind(self, name, from_func):
         self.scope_binds[-1][name] = from_func
@@ -129,6 +203,11 @@ def visit_FunctionDef(self, node):
     visit_AsyncFunctionDef = visit_FunctionDef
 
     def visit_Assign(self, node):
+        if isinstance(node.value, ast.Call) and _dotted(node.value.func) in HELPER_FUNCS:
+            code = HELPER_FUNCS[_dotted(node.value.func)]
+            for target in node.targets:
+                if isinstance(target, ast.Name):
+                    self.code_binds[-1][target.id] = code
         if is_passthrough_call(node.value, self.func_names):
             func_id = node.value.func.id
             for target in node.targets:
@@ -144,11 +223,22 @@ def visit_AnnAssign(self, node):
 
     def visit_Return(self, node):
         if node.value is not None:
-            code = int_literal(node.value)
+            code = self.resolve_code(node.value)
             if code is not None:
                 self.literals.append((code, node.lineno))
         self.generic_visit(node)
 
+    def visit_Raise(self, node):
+        exc = node.exc
+        if isinstance(exc, ast.Call) and isinstance(exc.func, ast.Name)                 and exc.func.id == "SystemExit":
+            if len(exc.args) == 1 and not exc.keywords:
+                code = self.resolve_code(exc.args[0])
+                if code is not None:
+                    self.literals.append((code, node.lineno))
+                elif not is_passthrough_call(exc.args[0], self.func_names):
+                    self.unanalyzable.append((node.lineno, ast.unparse(node)))
+        self.generic_visit(node)
+
     def visit_Call(self, node):
         if not (
             isinstance(node.func, ast.Attribute)
@@ -167,7 +257,7 @@ def visit_Call(self, node):
             return
 
         arg = node.args[0]
-        code = int_literal(arg)
+        code = self.resolve_code(arg)
         if code is not None:
             if code == 1 and self._in_except():
                 self.generic_visit(node)
@@ -234,7 +324,7 @@ def check_file(path):
         errors.append(f"{rel}: cannot parse: {exc}")
         return errors
 
-    visitor = ExitVisitor(module_function_names(tree))
+    visitor = ExitVisitor(module_function_names(tree), module_int_constants(tree))
     visitor.visit(tree)
 
     for lineno, snippet in visitor.unanalyzable:

tests/check_site_links.py

@@ -5,9 +5,14 @@
 committed, so CI builds it first):
 
     python scripts/site/build_site.py --repo-root . --out docs
-    python tests/check_site_links.py
+    python scripts/site/stage_public.py --src docs --out _site
+    python tests/check_site_links.py --root _site
 
-Walks docs/index.html, docs/404.html and docs/gallery/**/index.html. Each
+Check the staged tree, not docs/: staging strips internal files, and a link to
+one of them must fail here rather than 404 in production. --root defaults to
+docs/ for a quick local pass.
+
+Walks ROOT/index.html, ROOT/404.html and ROOT/gallery/**/index.html. Each
 relative or site-absolute ``href``/``src`` must name a file under docs/ (a
 directory means its index.html), and each ``#fragment`` must match an ``id``
 on the target page; every ``srcset`` candidate counts as a reference too, and
@@ -18,6 +23,7 @@
 
 from __future__ import annotations
 
+import argparse
 import json
 import sys
 from html.parser import HTMLParser
@@ -94,9 +100,14 @@ def resolve(page: Path, url: str, base: str) -> Path | None:
     return target.resolve()
 
 
-def main() -> int:
+def main(argv: list[str] | None = None) -> int:
+    global DOCS
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--root", type=Path, default=DOCS,
+                    help="site tree to check (default: docs/; CI checks the staged _site/)")
+    DOCS = ap.parse_args(argv).root.resolve()
     if not (DOCS / "index.html").is_file():
-        print("ERROR: docs/index.html missing; run scripts/site/build_site.py first",
+        print(f"ERROR: {DOCS / 'index.html'} missing; run scripts/site/build_site.py first",
               file=sys.stderr)
         return 2
     pages = [DOCS / "index.html", DOCS / "404.html",