test.bat

@rem Tests the toolchain has to pass, and the reason they are separate
@rem from check.bat: a content edit cannot change what most of them say,
@rem so writing a reference page should not pay for them.
@rem
@rem "Most", not "none": saying none routes an author straight past the one
@rem gate that would catch their defect.
@rem check_code_regions.mjs sweeps every markdown file under docs/, and
@rem check_gate_lists.mjs reads README.md and every page under
@rem docs/Documentation/. Run this file too after adding an unusual code
@rem construct -- a fence holding a fence marker, a 4-space indented
@rem block, an admonition wrapping a fence -- and after editing a
@rem developer page that says how many gates a wrapper runs.
@rem
@rem Otherwise run it when the change touches builder/, scripts/, lib/,
@rem book/, eval/, wisdom/, a wrapper or a workflow. Both CI workflows run it
@rem unconditionally, so a tooling regression cannot reach staging by
@rem someone skipping it.
@rem
@rem The split is by what a gate INTERROGATES, not by what it happens to
@rem open: check_axe_patch_equiv.mjs loads a built page, but only because
@rem the probe needs some document to run in -- what it is testing is the
@rem axe source patch. A new gate belongs here if it would still be worth
@rem running against an empty docs/.
@pushd "%~dp0"
@rem The publish allowlist is enforced inside the build, so a clean
@rem build.bat already says nothing unpublishable is in docs/. It does
@rem NOT say the allowlist still refuses anything -- one widened to refuse
@rem nothing reports the same clean pass. This asserts the
@rem refusals against named probes: a stray .bak, a .pem, a scratch .md
@rem with no frontmatter. No tree, no browser, ~40 ms, so it goes first.
node scripts/check_publish_policy.mjs
@if errorlevel 1 goto :fail
@rem Tools.md's two numbered gate lists against the two wrappers that
@rem actually run them, and then every gate count stated in prose on any
@rem developer page. A stale count breaks no link and fails no other
@rem gate; check_gate_lists.mjs's header says why. Pure text, no tree, no browser, ~50 ms.
node scripts/check_gate_lists.mjs
@if errorlevel 1 goto :fail
@rem The same question asked of the two CI workflows, which nothing else
@rem reads: do they run every gate this file and check.bat run, with the
@rem same arguments and in the same order, and build as build.bat does?
@rem A step dropped from one would leave CI green over a check it had
@rem stopped making. The differences that are meant are listed, each with
@rem where it is recorded. Its probes ride along. No tree, no browser,
@rem ~100 ms.
node scripts/check_ci_workflows.mjs
@if errorlevel 1 goto :fail
@rem Biome over the tooling, with the rules that find defects and none
@rem about style (biome.jsonc). Moving and deleting code leaves unused
@rem imports and undeclared names behind, and nothing else reads the
@rem tooling for them. Warnings fail too: Biome reports an unused import
@rem as a warning and exits 0 on one. Lint before every commit. No tree,
@rem no browser, ~0.25 s.
node scripts/check_lint.mjs
@if errorlevel 1 goto :fail
@rem Unit tests for builder/search.mjs: the search-data.json generator's
@rem heading split, generic-section folding (search.fold_headings), the
@rem titleFound/prefix-entry logic and output determinism, against small
@rem synthetic pages -- see WIP.Search.md's "Design" §1 and §5. No tree,
@rem no browser, well under a second.
node --test test/search.test.mjs
@if errorlevel 1 goto :fail
@rem Unit tests for builder/render.mjs's markdown-it plugins, on inputs
@rem the corpus does not hold, so a plugin that is wrong only there still
@rem fails. No tree, no browser, well under a second.
node --test test/render.test.mjs
@if errorlevel 1 goto :fail
@rem Unit tests for builder/strftime.mjs, the footer's date formatter,
@rem which no build calls today because no page sets a date for it.
@rem No tree, no browser, well under a second.
node --test test/strftime.test.mjs
@if errorlevel 1 goto :fail
@rem Unit tests for the pictures of a bug reproducer: scripts/lib/png.mjs
@rem (PNG decoding, comparing and the side-by-side image), the files and
@rem judgements behind repro.json's images and expect.imagesDiffer, and
@rem bug_repro.mjs's own refusals, over fixtures. Starts no IDE and no VB6.
@rem No tree, no browser, about 4 s.
node --test test/png.test.mjs
@if errorlevel 1 goto :fail
@rem check_examples.mjs's probes: batching, crash isolation through a fake
@rem lane, the canaries and the fence classifier. check_examples.mjs needs a
@rem twinBASIC install, so it runs only by hand; its probes need none.
@rem No tree, no browser, well under a second.
node --test test/example-batches.test.mjs
@if errorlevel 1 goto :fail
@rem Unit tests for scripts/lib/tb-ports.mjs, which claims the DevTools
@rem ports the harness's IDEs use: two claims at once are disjoint, a port
@rem in use and a live lock are passed over, a stale lock is taken over.
@rem Starts no IDE. No tree, no browser, about 2 s.
node --test test/ports.test.mjs
@if errorlevel 1 goto :fail
@rem A regex that backtracks exponentially is a hang waiting for the
@rem right input, and nothing that reads the site can see it: the corpus
@rem passes until some page happens to contain the trigger, and then the
@rem build stops rather than failing. Reads literals and every new
@rem RegExp(...) whose arguments the source decides, since assembling a
@rem pattern from constants would otherwise be a way out. Its own probes ride along
@rem in the same run, so a green line cannot be a dead gate. No tree, no
@rem browser, ~10 s.
node scripts/check_regex_safety.mjs
@if errorlevel 1 goto :fail
@rem The pre-render rewrites in render.mjs run over RAW markdown, so none
@rem of them knows what is code -- and this site's subject matter is code.
@rem Such a rewrite can strip Liquid tags inside fences, lose an
@rem admonition body's code indentation, percent-encode media-URL spaces
@rem inside a fence or delete a YAML sample's closing ---. No other gate
@rem catches it, because the damage is inside <code>.
@rem
@rem Tokenise, rewrite, re-tokenise, compare the literal regions. Its own
@rem probes ride along, so a clean corpus cannot masquerade as a working
@rem gate. No tree, no browser, ~2 s.
node scripts/check_code_regions.mjs
@if errorlevel 1 goto :fail
@rem The page-count drift guard reports nothing on a healthy tree, so
@rem every ordinary build sounds exactly like one whose guard has stopped
@rem working. These probes make the other assertion, against a scratch
@rem baseline file rather than the committed one. The first replays a
@rem whole package lost to an exclude rule, which a guard that only knows
@rem a floor cannot see. No tree, no browser, ~60 ms.
node scripts/check_page_baseline.mjs
@if errorlevel 1 goto :fail
@rem The book-coverage warnings say nothing when every page has an entry
@rem in docs\_book.yml -- in a part, or in left_out with a reason -- which
@rem is also all a check that had stopped working would say. Without the
@rem warnings, whole sections drop out of the PDF without a word.
@rem These probes give each of the five findings a fault to report, on a
@rem manifest and pages built in memory, so they mean the same against an
@rem empty docs\. No tree, no browser, well under a second.
node scripts/check_book_coverage.mjs
@if errorlevel 1 goto :fail
@rem The symbol index (tB/symbols.json) is read by the IDE help add-in,
@rem and a build that indexes the reference cleanly says nothing about the
@rem rules that did not fire on it. These probes assert each one against
@rem the case that made it necessary: the .twin scanner's traps, the rules
@rem that place a symbol on a page or heading, and the drift guard's
@rem refusal of a URL the index has stopped publishing -- a reworded
@rem heading moves its anchor, and an installed add-in keeps the old one.
@rem Fixtures only: no tree, no install, ~100 ms.
node scripts/check_symbol_index.mjs
@if errorlevel 1 goto :fail
@rem The scanners of twinBASIC source and of Attributes.md misread in
@rem silence: a line read as the wrong kind is counted, generated or skipped
@rem as that kind. These probes run the shared modifier list through all
@rem three scanners, and assert the census's declaration kinds and the probe
@rem generator's targets against the shapes each can get wrong. Fixed
@rem inputs only: no tree, no install.
node scripts/check_twin_parsers.mjs
@if errorlevel 1 goto :fail
@rem The attribute sweep asks the compiler where every attribute is legal, and
@rem none of its failures announces itself: a wrong site skeleton reads as
@rem "every attribute is refused here", an ignored control as a recognised
@rem attribute, a refusal taken for an acceptance as a finding about the
@rem compiler. The IDE is what cannot run here, so the parts that decide what an
@rem answer means are probed on fixed inputs: no IDE, no tree, no install.
node scripts/check_attribute_sweep.mjs
@if errorlevel 1 goto :fail
@rem Nothing else tests how a tool reads its command line, which is how a
@rem value flag given no value can be read as NaN or as the next flag.
@rem lib/cli.mjs's probes, then each tool's recorded command-line errors:
@rem the tool runs with an IDE and a browser that do not exist, so a case
@rem that gets past its command line fails rather than starting either.
@rem No tree, no browser, no install, ~1 s.
node scripts/check_cli.mjs
@if errorlevel 1 goto :fail
@rem The book's pdf-lib shims replace pdf-lib's parser, object classes and
@rem writer for speed, and nothing else compares what they write with what
@rem pdf-lib writes. One document, written here without pdf-lib, is loaded,
@rem changed and saved by stock pdf-lib and by pdf-lib with the shims, each
@rem in a child process, and the two files are compared object by object
@rem with streams inflated. A shim none of whose functions runs fails it too,
@rem since the document then no longer tests it, or the book does not need
@rem it. No tree, no browser, ~0.5 s.
node scripts/check_pdf_shims_equiv.mjs
@if errorlevel 1 goto :fail
@rem impexp.mjs and impexp.py are one published tool in two languages, and
@rem Tools.md promises they print the same and write the same bytes. Both
@rem built-in test suites must pass with the same names, and one sequence
@rem of commands runs through each edition, comparing exit codes, output
@rem and written files. Without Python it says SKIPPED and passes here;
@rem in CI (CI=true) it fails instead. No tree, no browser, ~4 s, most of
@rem it Python starting 21 times.
node scripts/check_impexp_parity.mjs
@if errorlevel 1 goto :fail
@rem check_a11y.mjs injects a PATCHED axe bundle (plain-color-fields,
@rem -26 % on a realistic page set). The patch asserts its substitution
@rem targets, so an axe-core bump fails loudly; this catches the other
@rem case, where the text still matches but the colour maths has changed.
@rem The fingerprint gate cannot see that -- it compares `incomplete` as
@rem a rule-id set.
@rem
@rem Needs a browser and any one built page (it loads /404.html from
@rem docs\_site-offline\ and never touches its DOM), so run build.bat
@rem first. Staleness does not matter here, which is why this does not
@rem sit behind check_tree_fresh.mjs.
node scripts/check_axe_patch_equiv.mjs
@if errorlevel 1 goto :fail
@popd
@exit /b 0
:fail
@rem Capture before popd, which would otherwise reset ERRORLEVEL to 0
@rem and report a clean run.
@set "TEST_ERR=%ERRORLEVEL%"
@popd
@exit /b %TEST_ERR%