Build tooling work, commits C65d-C75: pdf-lib shim gate, impexp parity, one command-line convention

.github/actions/run-gates/action.yml

@@ -160,6 +160,23 @@ runs:
     - name: Verify the command-line parser and the tools' cases (check_cli.mjs)
       shell: bash
       run: node scripts/check_cli.mjs
+    # The book's pdf-lib shims replace pdf-lib's parser, object classes and
+    # writer, and nothing else compares what they write with what pdf-lib
+    # writes. This saves one document with each, in child processes, and
+    # compares the two object by object with streams inflated; a shim that
+    # never runs fails it too. No browser, no built tree.
+    - name: Verify the book's pdf-lib shims against stock (check_pdf_shims_equiv.mjs)
+      shell: bash
+      run: node scripts/check_pdf_shims_equiv.mjs
+    # impexp.mjs and impexp.py are one published tool in two languages, and
+    # Tools.md promises the same output and the same bytes. Both built-in test
+    # suites, then one sequence of commands through each edition, comparing
+    # exit codes, output and written files. The runner's own python3 serves;
+    # without one the gate fails here, because GitHub sets CI=true, where
+    # test.bat on a machine without Python reports it skipped.
+    - name: Verify the two impexp editions agree (check_impexp_parity.mjs)
+      shell: bash
+      run: node scripts/check_impexp_parity.mjs
     # Graphviz sizes each node box from a width table; the browser paints the
     # label with a real font. Nothing in the build compares the two, so a
     # mismatch ships as text hanging outside its box on a green build -- which

.github/workflows/checks.yml

@@ -95,8 +95,8 @@ jobs:
         # links the offline rewrite missed), and _site-pdf/book.html
         # (informational). A failing check never aborts the build -- a
         # broken link still produces a site worth inspecting -- so the
-        # step fails on the exit code: 1 for link failures, 2 for
-        # integrity failures, 3 for both.
+        # step fails on the exit code: 1 when the check found a problem,
+        # 2 when the build could not run.
         run: node builder/tbdocs.mjs --src docs --no-fetch-assets --check-audit-index
       # The gates both workflows run, in one list: see
       # .github/actions/run-gates/action.yml, which check_ci_workflows.mjs

WIP.Build.md

@@ -154,7 +154,7 @@ Older notes under `builder/PLAN-*.md` still place `check_publish_policy.mjs` and
 
 **The link and integrity check runs inside the build.** `build.bat` passes `--check-audit-index`, which implies `--check`, and the check walks the HTML on the worker lanes that produced it -- both trees' final strings are already decoded and in memory at `flush()`, so the ~270 MB the two trees weigh is never written out only to be read back. It also audits the tree index the build derives from its own records against what landed on disk -- the one direction the two-checker comparison structurally cannot see, since a spurious entry makes the oracle answer "exists" for a path that 404s in production. It catches broken intra-site links, missing pages, malformed `redirect_from` entries (the most common breakage when adding new pages or moving content between sections), duplicate ids, remote `<img src>`, badly nested tags, sitemap and search-index gaps, canonical mismatches, and (via a forbidden-prefix rule on the offline tree) any extracted link that still points at the live docs site after the offlinify rewrite. A clean `build.bat && check.bat` is the bar for "ready to commit".
 
-A failing check never aborts the build: a broken link still produces a site you want on disk to inspect. It sets the exit code instead, using the same scheme `check_links.mjs` has always used -- 1 for link failures, 2 for integrity failures, 3 for both -- so CI can tell them apart.
+A failing check never aborts the build: a broken link still produces a site you want on disk to inspect. It sets the exit code to 1 instead, whether the check found link failures, integrity failures or both (the summary lines say which), and keeps 2 for a build that could not do its job: the same scheme `check_links.mjs` uses. A 2 means a refused command line, a stall or a crash.
 
 The remote-asset rule fails the run on any `<img src>` resolving off-box (`http://`, `https://`, or protocol-relative `//host`). In the build it is unconditional -- `checkRemoteAssets: true` on both trees in `builder/check.mjs`'s `TREES` -- and is *not* reachable by a flag: `tbdocs` rejects `--check-remote-assets` as an unknown argument. That name belongs to the standalone `scripts/check_links.mjs`, where it is opt-in. The PDF pass over `book.html` is informational, so enforcement comes from the `_site/` pass -- every page in the book is also in `_site/`, making it a superset. The check is deliberately scoped to `<img>` only; `<iframe>` is untouched.
 
@@ -388,7 +388,8 @@ node scripts/check_tree_fresh.mjs --tree docs/_site-pdf --marker book.html
 **`--marker` is what makes that work on this tree.** The script identifies a tree
 by its `index.html`, which every output tree has *except* `_site-pdf/` --- that one
 holds a single `book.html`. Exit codes are the script's: **2** when the tree is
-absent, **1** when it is older than `docs/` or `builder/`.
+absent, **1** when it is older than `docs/` or `builder/`. The renderer that runs after it
+has no 1, so `book.bat`'s 1 means a stale tree (or a failed `npm install`) and nothing about the render.
 
 > **One batch detail that is easy to get wrong:** `%ERRORLEVEL%` inside a parenthesised `if errorlevel 1 (...)`
 > block expands when the block is **parsed**, not when it runs, so the value

WIP.Harness.md

@@ -445,6 +445,11 @@ Four smaller things it knows, each of which cost a run:
   starts, so the probe's first `Debug.Cls` erases the build log from `[BUILD] Starting...` on.
   `event_clearDebugConsole` writes an empty line after its clear, so the record of a second
   `Debug.Cls` begins with one.
+- **`tbrun` exits 4 when the compiler crashed**, as `tbbuild` does.
+  A crash and a failed build after a clean compile are different faults with different
+  remedies (rerun the second, isolate the probe for the first), and `check_examples` already
+  isolated a sample on `tbbuild`'s 4. `tbrun` exits 3 for no output at all, and 2 for a
+  compile that never settled, which `tbbuild` reports as 3.
 
 A reader of the console that is not `tbrun` should **compare the whole console before and
 after, not read on from an index**: new text can be appended to an entry that is still open.
@@ -1068,7 +1073,7 @@ lane's folder before the first lane starts, so the lanes inherit `TB_REGISTRY_OW
 leave the registry alone, and `finishTidy` once the last has ended. Then it checks rather
 than trusts: no project-state or recent-list entry may name a lane's folder, a second sweep
 of the remembered build targets must find none, and the add-ins' settings must be as
-recorded. Any failure is exit code 2.
+recorded. Any failure is exit code 3, which wins over a lane's failure (1): the registry is what to repair.
 
 **An add-in's own settings are the runner's too.** `SaveSetting` writes under
 `HKCU\Software\VB and VBA Program Settings\<app>`, the same key as any installed copy of the
@@ -1208,8 +1213,8 @@ probe lanes:
   recent list, two of them and then 21, identical both times.
 - With Global Search settings planted beforehand (Match case on, and one extra value), the
   lane began with every option off, and the key came back exactly, the extra value
-  included. With `settings` taken out of `lanes.mjs`, the run failed with exit code 2 and
-  named `GlobalSearchAddIn`.
+  included. With `settings` taken out of `lanes.mjs`, the run failed and named
+  `GlobalSearchAddIn`.
 - An `--only` that matches nothing was refused with exit code 2, and so, until P6 was
   answered, was a DLL in a stand-in `%APPDATA%`; now the lanes run beside it, and the P6
   lane's IDE loaded its own probe alone. `--timeout 8` ended both lanes mid-build, and left