feat(tooling): port the docgen site generator to Ludic (no Python) (#41)

Follow-up to #31: the doc/lint/grammar checks moved to Ludic there; this ports
the remaining docgen piece (gen.py / check.py / palette.py) so nothing in the
documentation pipeline is Python any more.

Three new `x` subcommands, all in Ludic and compiled by Ludic:

  - x docs-gen [--out DIR]  the static-site generator: parses docs/language/**
    front-matter + bodies (fences, Parameters:), builds the section/symbol
    model, reads the asset templates, and emits every page + ns/color/api pages
    + the landing page + ludic-highlight.js + symbols.json + .nojekyll.
  - x docs-check [DIR]      the coverage / integrity guard (required files, a
    page per inventory.json symbol, duplicate-token and one-dir-per-namespace
    guards, highlighter link targets).
  - x docs-palette          the named-colour source of truth: the palette table
    moved into tools/x/docgen.ludic, emitting emit_color.ludic (pointer, not
    ptr) + palette.json.

Verified against the Python oracle: `x docs-gen` reproduces all 466 output files
BYTE-FOR-BYTE (a Ludic json.dumps/html.escape/front-matter port — ordered dicts,
indent=2 vs compact, ensure_ascii \uXXXX, codepoint-aware truncation), and
`x docs-check` matches check.py's pass/fail output. Wired into `x test` as a
gate (docs-gen -> docs-check on a fresh site; docs-palette stays byte-identical).

CI swap: ci.yml and docs.yml call the Ludic generator; docs.yml drops the
python:3.12 container and bootstraps the toolchain from the IR seed instead.
tools/docgen/{gen,check,palette}.py deleted; only assets/ + inventory.json
remain. Completes #31's criterion 3.

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

.forgejo/pull_request_template.md

@@ -14,7 +14,7 @@ Closes #
 - [ ] `ludic-fmt` leaves the touched files unchanged (2-space, LF, UTF-8).
 - [ ] New/changed stdlib symbols are documented under `docs/language/**` and
       registered in `tools/docgen/inventory.json`
-      (`python3 tools/docgen/check.py` passes).
+      (`bin/x docs-gen && bin/x docs-check build/pages` passes).
 - [ ] Commits follow [Conventional Commits](https://www.conventionalcommits.org).
 - [ ] No new C / Python / JS in tooling (Ludic only), and no generated
       artifacts committed outside `build/` / `bin/`.

.forgejo/workflows/ci.yml

@@ -17,20 +17,20 @@ jobs:
     # advertises `docker`, not the GitHub-ism `ubuntu-latest`.
     runs-on: docker
     # Reuse the runner's own base image (Debian bookworm with git + node already
-    # present) and add just the two things the toolchain needs: a modern clang
-    # (LLVM 16 — the IR uses opaque pointers, so clang 15+ is required) and
-    # python3 for the docs/vocabulary checks. A prebuilt image with these baked
-    # in is the obvious future speed-up (see issue #33's packaging work).
+    # present) and add just the one thing the toolchain needs: a modern clang
+    # (LLVM 16 — the IR uses opaque pointers, so clang 15+ is required). The docs
+    # generator and its guards are now Ludic, so the job carries no Python. A
+    # prebuilt image with clang baked in is the obvious future speed-up (see
+    # issue #33's packaging work).
     container: node:20-bookworm
     steps:
-      - name: Install clang-16 and python3
+      - name: Install clang-16
         run: |
           set -eu
           export DEBIAN_FRONTEND=noninteractive
           apt-get update -qq
-          apt-get install -y -qq --no-install-recommends clang-16 python3 git ca-certificates
+          apt-get install -y -qq --no-install-recommends clang-16 git ca-certificates
           clang-16 --version | head -1
-          python3 --version
 
       - name: Check out the triggering commit
         run: |
@@ -75,11 +75,12 @@ jobs:
       - name: Docs cover the implementation
         run: |
           set -eu
-          # check-impl / check-vocabulary are written in Ludic and run through
-          # x — no Python. (check-vocabulary also runs in `x test-tools`.) The
-          # site generator (gen.py) is still Python; its port is tracked.
+          # The whole docs toolchain is written in Ludic and runs through x —
+          # no Python anywhere. check-impl / check-vocabulary / check-docs guard
+          # the sources; docs-gen builds the site and docs-check is its coverage
+          # + integrity guard. (check-vocabulary also runs in `x test-tools`.)
           bin/x check-impl
           bin/x check-vocabulary
           bin/x check-docs
-          python3 tools/docgen/gen.py --out build/pages
-          python3 tools/docgen/check.py build/pages
+          bin/x docs-gen --out build/pages
+          bin/x docs-check build/pages

.forgejo/workflows/docs.yml

@@ -10,6 +10,7 @@ on:
     paths:
       - 'docs/**'
       - 'tools/docgen/**'
+      - 'tools/x/**'
       - '.forgejo/workflows/docs.yml'
   workflow_dispatch: {}
 
@@ -23,11 +24,20 @@ jobs:
     # GitHub-ism this runner does not register, so a job requesting it sits in
     # "Waiting" forever with "no online runner found matching this label".
     runs-on: docker
-    # Run in a Python image: the generator is pure-Python stdlib, and this image
-    # already has git for the clone + publish. No node actions are used, so the
-    # job never depends on the runner's base image having python installed.
-    container: python:3.12
+    # The generator is now Ludic, so this builds the toolchain from its IR seed
+    # (clang assembles the seed into bin/ludicc, which compiles bin/x) exactly
+    # like the ci workflow, then runs `x docs-gen`. node:20-bookworm carries git
+    # for the clone + publish; clang-16 is the only extra the bootstrap needs.
+    container: node:20-bookworm
     steps:
+      - name: Install clang-16
+        run: |
+          set -eu
+          export DEBIAN_FRONTEND=noninteractive
+          apt-get update -qq
+          apt-get install -y -qq --no-install-recommends clang-16 git ca-certificates
+          clang-16 --version | head -1
+
       - name: Generate the documentation site
         env:
           SOURCE_REF: ${{ github.ref_name }}
@@ -36,9 +46,19 @@ jobs:
           git config --global --add safe.directory '*'
           git clone --depth 1 --branch "${SOURCE_REF:-main}" \
             https://git.workshopsoft.io/workshopsoft/ludic.git src
-          python3 --version
-          python3 src/tools/docgen/gen.py --out public
-          python3 src/tools/docgen/check.py public
+          cd src
+          # The toolchain is macOS-first; on this Linux runner it links against a
+          # tiny C-free IR shim supplying the Darwin stdout/stderr globals over
+          # glibc's, injected through LUDIC_CC. docs-gen is a pure CLI (no
+          # windowing), so the C-free bootstrap is all it needs.
+          export LUDIC_CC="clang-16 $(pwd)/tools/ci/linux_stdio_shim.ll"
+          export LUDIC_HOME="$(pwd)"
+          mkdir -p bin
+          clang-16 tools/ci/linux_stdio_shim.ll selfhost/ludicc.seed.ll -o bin/ludicc
+          bin/ludicc tools/x/main.ludic -o bin/x
+          bin/x docs-gen --out ../public
+          bin/x docs-check ../public
+          cd ..
           echo "--- generated files ---"
           ls -la public