eyelang 1.6.0 → 1.7.0

package/test/run-regression.mjs

@@ -0,0 +1,1215 @@
+#!/usr/bin/env node
+// Supplemental regression runner.
+// This file collects focused checks that do not belong to the public
+// conformance corpus or the example-output corpus: CLI regressions, public API
+// checks, and small white-box tests for maintenance-sensitive internals.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import * as publicApi from '../src/index.js';
+import {
+  run,
+  Program,
+  makeProgram,
+  Solver,
+  Env,
+  BuiltinRegistry,
+  createDefaultRegistry,
+  atom,
+  compound,
+  listFromItems,
+  numberTerm,
+  stringTerm,
+  variable,
+  copyResolved,
+  flattenConjunction,
+  properListItems,
+  termIsGround,
+  termToString,
+  unify,
+  variantTerms,
+  parseProgramText,
+} from '../src/index.js';
+import { parseGoalText } from '../src/parser.js';
+import { selectClauseCandidates } from '../src/program.js';
+import { TestReporter, isMainModule } from './test-style.mjs';
+import { hashHex } from '../src/hash.js';
+
+const testRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)));
+const packageRoot = path.resolve(testRoot, '..');
+const runtimeRoot = path.join(packageRoot, 'src');
+const bin = path.join(runtimeRoot, 'bin.js');
+const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+let tmp = null;
+let tmpCounter = 0;
+
+export function runRegression(reporter = new TestReporter()) {
+  tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'eyelang-regression.'));
+  tmpCounter = 0;
+
+  try {
+    runSection(reporter, 'Regression', regressionCases());
+    runSection(reporter, 'Documentation sync', documentationSyncCases());
+    runSection(reporter, 'API', apiCases());
+    runSection(reporter, 'White-box', whiteBoxCases());
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+    tmp = null;
+  }
+}
+
+function regressionCases() {
+  return [
+    {
+      name: '--proof rule fact explanation output',
+      run: () => runWhy({
+        program: 'type(socrates, man).\ntype(?x, mortal) :- type(?x, man).\n',
+        goalText: 'type(socrates, mortal)',
+        expected: `type(socrates, mortal).
+why(
+  type(socrates, mortal),
+  proof(
+    goal(type(socrates, mortal)),
+    by(rule("__FILE__", clause(2))),
+    bindings([binding("?x", socrates)]),
+    uses([
+      proof(
+        goal(type(socrates, man)),
+        by(fact("__FILE__", clause(1)))
+      )
+    ])
+  )
+).
+
+`,
+      }),
+    },
+    {
+      name: '--proof numeric builtin explanation output',
+      run: () => runWhy({
+        program: 'p(?x) :- between(536, 536, ?x).\n',
+        goalText: 'p(536)',
+        expected: `p(536).
+why(
+  p(536),
+  proof(
+    goal(p(536)),
+    by(rule("__FILE__", clause(1))),
+    bindings([binding("?x", 536)]),
+    uses([
+      proof(
+        goal(between(536, 536, 536)),
+        by(builtin(between, 3))
+      )
+    ])
+  )
+).
+
+`,
+      }),
+    },
+    {
+      name: '--proof list builtin explanation output',
+      run: () => runWhy({
+        program: 'p(?x) :- member(?x, [a]).\n',
+        goalText: 'p(a)',
+        expected: `p(a).
+why(
+  p(a),
+  proof(
+    goal(p(a)),
+    by(rule("__FILE__", clause(1))),
+    bindings([binding("?x", a)]),
+    uses([
+      proof(
+        goal(member(a, [a])),
+        by(builtin(member, 2))
+      )
+    ])
+  )
+).
+
+`,
+      }),
+    },
+    {
+      name: 'explanation backtracks across earlier subgoal alternatives',
+      run: () => {
+        const result = runWhyLoose({
+          program: 'p(ok) :- q(?x), r(?x).\nq(a).\nq(b).\nr(b).\n',
+          goalText: 'p(ok)',
+        });
+        assertIncludes(result.stdout, 'goal(q(b)),\n        by(fact("', 'stdout');
+        assertIncludes(result.stdout, 'goal(r(b)),\n        by(fact("', 'stdout');
+        assertNotIncludes(result.stdout, 'no_proof', 'stdout');
+      },
+    },
+    {
+      name: 'explanation releases active call before caller rest goals',
+      run: () => {
+        const result = runWhyLoose({
+          program: 'p(ok) :- q(1), q(1).\nq(0).\nq(1) :- q(0).\n',
+          goalText: 'p(ok)',
+        });
+        assertIncludes(result.stdout, 'goal(p(ok)),\n    by(rule("', 'stdout');
+        assertIncludes(result.stdout, 'goal(q(1)),\n        by(rule("', 'stdout');
+        assertNotIncludes(result.stdout, 'no_proof', 'stdout');
+      },
+    },
+    {
+      name: 'EYELANG_LOCAL_TIME fixes local_time builtin',
+      run: () => {
+        const result = runCli(['-'], {
+          input: 'materialize(local_time_answer, 1).\nlocal_time_answer(?d) :- local_time(?d).\n',
+          env: { EYELANG_LOCAL_TIME: '2024-01-02' },
+        });
+        assertEqual(result.status, 0, 'exit status');
+        assertEqual(result.stdout, 'local_time_answer("2024-01-02").\n', 'stdout');
+        assertEqual(result.stderr, '', 'stderr');
+      },
+    },
+    {
+      name: 'help with no arguments',
+      run: () => {
+        const result = runCli([]);
+        assertEqual(result.status, 0, 'exit status');
+        assertIncludes(result.stdout, 'Usage:\n  eyelang [options] [file-or-url.eye|- ...]', 'stdout');
+        assertIncludes(result.stdout, '-p, --proof', 'stdout');
+        assertIncludes(result.stdout, '-s, --stats', 'stdout');
+        assertIncludes(result.stdout, '-w, --warnings', 'stdout');
+        assertEqual(result.stderr, '', 'stderr');
+      },
+    },
+    {
+      name: 'version comes from package.json',
+      run: () => {
+        const result = runCli(['--version']);
+        assertEqual(result.status, 0, 'exit status');
+        assertEqual(result.stdout, `eyelang ${pkg.version}\n`, 'stdout');
+        assertEqual(result.stderr, '', 'stderr');
+      },
+    },
+    {
+      name: 'npm exec can run package CLI bin from checkout',
+      run: () => {
+        const result = spawnSync('npm', ['exec', '--', 'eyelang', '--version'], {
+          cwd: packageRoot,
+          encoding: 'utf8',
+          env: { ...process.env, npm_config_update_notifier: 'false' },
+        });
+        assertEqual(result.status, 0, 'exit status');
+        assertEqual(result.stdout, `eyelang ${pkg.version}\n`, 'stdout');
+        assertEqual(result.stderr, '', 'stderr');
+      },
+    },
+    {
+      name: 'stdin input is accepted',
+      run: () => {
+        const result = runCli(['-'], { input: 'p(a, b).\nq(?x, ?y) :- p(?x, ?y).\n' });
+        assertEqual(result.status, 0, 'exit status');
+        assertEqual(result.stdout, 'q(a, b).\n', 'stdout');
+        assertEqual(result.stderr, '', 'stderr');
+      },
+    },
+
+    {
+      name: '--proof enables materialization explanations',
+      run: () => {
+        const result = runCli(['--proof', '-'], { input: 'p(a, b).\nq(?x, ?y) :- p(?x, ?y).\n' });
+        assertEqual(result.status, 0, 'exit status');
+        assertIncludes(result.stdout, 'q(a, b).\nwhy(', 'stdout');
+        assertEqual(result.stderr, '', 'stderr');
+      },
+    },
+    {
+      name: '-p enables materialization explanations',
+      run: () => {
+        const result = runCli(['-p', '-'], { input: 'p(a, b).\nq(?x, ?y) :- p(?x, ?y).\n' });
+        assertEqual(result.status, 0, 'exit status');
+        assertIncludes(result.stdout, 'q(a, b).\nwhy(', 'stdout');
+        assertEqual(result.stderr, '', 'stderr');
+      },
+    },
+
+
+    {
+      name: '--stats prints solver statistics to stderr',
+      run: () => {
+        const result = runCli(['--stats', '-'], { input: 'p(a, b).\nq(?x, ?y) :- p(?x, ?y).\n' });
+        assertEqual(result.status, 0, 'exit status');
+        assertEqual(result.stdout, 'q(a, b).\n', 'stdout');
+        assertIncludes(result.stderr, 'eyelang stats:\n', 'stderr');
+        assertIncludes(result.stderr, '  solve_goals_calls:', 'stderr');
+      },
+    },
+    {
+      name: '-s prints solver statistics to stderr',
+      run: () => {
+        const result = runCli(['-s', '-'], { input: 'p(a, b).\nq(?x, ?y) :- p(?x, ?y).\n' });
+        assertEqual(result.status, 0, 'exit status');
+        assertEqual(result.stdout, 'q(a, b).\n', 'stdout');
+        assertIncludes(result.stderr, 'eyelang stats:\n', 'stderr');
+        assertIncludes(result.stderr, '  solve_goals_calls:', 'stderr');
+      },
+    },
+    {
+      name: '--warnings prints unstratified negation diagnostics without failing',
+      run: () => {
+        const input = [
+          'materialize(answer, 1).',
+          'p(a) :- not(q(a)).',
+          'q(a) :- not(p(a)).',
+          'answer(ok).',
+          '',
+        ].join('\n');
+        const result = runCli(['--warnings', '-'], { input });
+        assertEqual(result.status, 0, 'exit status');
+        assertEqual(result.stdout, '', 'stdout');
+        assertIncludes(result.stderr, 'eyelang warning: unstratified negation\n', 'stderr');
+        assertIncludes(result.stderr, 'p/1 depends negatively on q/1', 'stderr');
+        assertIncludes(result.stderr, 'q/1 depends negatively on p/1', 'stderr');
+      },
+    },
+    {
+      name: '-w prints unstratified negation diagnostics without failing',
+      run: () => {
+        const input = [
+          'materialize(answer, 1).',
+          'p(a) :- not(q(a)).',
+          'q(a) :- not(p(a)).',
+          'answer(ok).',
+          '',
+        ].join('\n');
+        const result = runCli(['-w', '-'], { input });
+        assertEqual(result.status, 0, 'exit status');
+        assertEqual(result.stdout, '', 'stdout');
+        assertIncludes(result.stderr, 'eyelang warning: unstratified negation\n', 'stderr');
+      },
+    },
+    {
+      name: '--warnings stays quiet for stratified negation',
+      run: () => {
+        const input = 'materialize(answer, 1).\np(a).\nanswer(ok) :- not(q(a)).\n';
+        const result = runCli(['--warnings', '-'], { input });
+        assertEqual(result.status, 0, 'exit status');
+        assertEqual(result.stdout, 'answer(ok).\n', 'stdout');
+        assertEqual(result.stderr, '', 'stderr');
+      },
+    },
+    {
+      name: 'double dash permits option-shaped file names',
+      run: () => {
+        const file = path.join(tmp, '-h');
+        fs.writeFileSync(file, 'p(a, b).\nq(?x, ?y) :- p(?x, ?y).\n');
+        const result = runCli(['--', file]);
+        assertEqual(result.status, 0, 'exit status');
+        assertEqual(result.stdout, 'q(a, b).\n', 'stdout');
+        assertEqual(result.stderr, '', 'stderr');
+      },
+    },
+  ];
+}
+
+
+function documentationSyncCases() {
+  return [
+    {
+      name: 'language reference builtins match runtime registry',
+      run: () => assertArrayEqual(languageReferenceBuiltinNames(), registeredBuiltinNames(), 'builtins'),
+    },
+    {
+      name: 'guide builtin catalog matches runtime registry',
+      run: () => {
+        assertArrayEqual(guideBuiltinNames(), registeredBuiltinNames(), 'builtins');
+        const summary = guideBuiltinSummary();
+        const actual = registeredBuiltinSummary();
+        assertEqual(summary.entries, actual.entries, 'builtin entry count');
+        assertEqual(summary.names, actual.names, 'builtin predicate name count');
+      },
+    },
+    {
+      name: 'guide example catalog source and output links match examples directory',
+      run: () => assertArrayEqual(guideExampleCatalogIssues(), [], 'guide example catalog'),
+    },
+    {
+      name: 'playground example catalog and relative loaders match examples directory',
+      run: () => assertArrayEqual(playgroundExampleIssues(), [], 'playground examples'),
+    },
+    {
+      name: 'playground static page is browser-ready and packaged',
+      run: () => assertArrayEqual(playgroundStaticIssues(), [], 'playground static page'),
+    },
+    {
+      name: 'documentation local links and anchors resolve',
+      run: () => assertArrayEqual(findBrokenDocLinks(), [], 'broken documentation links'),
+    },
+    {
+      name: 'documentation uses eyelang source style',
+      run: () => assertArrayEqual(documentationSourceStyleIssues(), [], 'documentation source style'),
+    },
+    {
+      name: 'documented npm scripts exist in package.json',
+      run: () => assertArrayEqual(missingDocumentedPackageScripts(), [], 'missing documented npm scripts'),
+    },
+    {
+      name: 'source-checkout setup docs match package bin',
+      run: () => {
+        assertEqual(pkg.bin?.eyelang, './bin/eyelang.js', 'package eyelang bin');
+        const binPath = path.join(packageRoot, pkg.bin.eyelang);
+        const binText = fs.readFileSync(binPath, 'utf8');
+        assertEqual(binText.startsWith('#!/usr/bin/env node\n'), true, 'bin shebang');
+        assertArrayEqual(misleadingDependencyInstallDocs(), [], 'misleading dependency install docs');
+      },
+    },
+  ];
+}
+
+function apiCases() {
+  return [
+    {
+      name: 'public type declarations match runtime exports',
+      run: () => assertArrayEqual(declaredValueExportNames(), runtimeExportNames(), 'public value exports'),
+    },
+    {
+      name: 'run materialization through public API without proof by default',
+      run: () => {
+        const result = run('p(a, b).\nq(?x, ?y) :- p(?x, ?y).\n');
+        assertEqual(result.stdout, 'q(a, b).\n', 'stdout');
+      },
+    },
+
+    {
+      name: 'compound factory canonicalizes zero arity to atoms',
+      run: () => {
+        const nil = compound('nil', []);
+        assertEqual(nil.type, 'atom', 'type');
+        assertEqual(nil.name, 'nil', 'name');
+        assertEqual(nil.arity, 0, 'arity');
+        assertEqual(termToString(nil, new Env(), true), 'nil', 'readback');
+        assertEqual(unify(nil, atom('nil'), new Env()), true, 'unifies with atom');
+      },
+    },
+
+    {
+      name: 'portable hash helpers match standard vectors',
+      run: () => {
+        assertEqual(hashHex('md5', 'abc'), '900150983cd24fb0d6963f7d28e17f72', 'md5');
+        assertEqual(hashHex('sha', 'abc'), 'a9993e364706816aba3e25717850c26c9cd0d89d', 'sha1');
+        assertEqual(hashHex('sha256', 'abc'), 'ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad', 'sha256');
+        assertEqual(hashHex('sha512', 'abc'), 'ddaf35a193617abacc417349ae20413112e6fa4e89a97ea20a9eeee64b55d39a2192992a274fc1a836ba3c23a3feebbd454d4423643ce80e2a9ac94fa54ca49f', 'sha512');
+      },
+    },
+
+
+    {
+      name: 'run materialization can enable proof explanations',
+      run: () => {
+        const result = run('p(a, b).\nq(?x, ?y) :- p(?x, ?y).\n', { proof: true });
+        assertIncludes(result.stdout, 'q(a, b).\nwhy(', 'stdout');
+      },
+    },
+
+    {
+      name: 'run accepts Program instances',
+      run: () => {
+        const program = Program.parse('p(a, b).\nq(?x, ?y) :- p(?x, ?y).\n');
+        const result = run(program);
+        assertEqual(result.stdout, 'q(a, b).\n', 'stdout');
+      },
+    },
+    {
+      name: 'run keeps recursive materializations independent in one solver',
+      run: () => {
+        const text = fs.readFileSync(path.join(packageRoot, 'examples', 'alignment-demo.eye'), 'utf8');
+        const program = Program.parseSources([{ text, filename: 'alignment-demo.eye' }]);
+        const result = run(program);
+        assertIncludes(result.stdout, 'broaderTransitive(anpr_passenger_car, ref_car).\n', 'stdout');
+        assertIncludes(result.stdout, 'narrowerOrEqualOf(anpr_passenger_car, ref_car).\n', 'stdout');
+      },
+    },
+    {
+      name: 'makeProgram creates indexed programs',
+      run: () => {
+        const program = makeProgram('edge(a, b).\npath(?x, ?y) :- edge(?x, ?y).\n');
+        const group = program.findGroup('path', 2);
+        assertEqual(Boolean(group), true, 'path/2 group exists');
+        assertEqual(group.groupName ?? group.name, 'path', 'group name');
+        assertEqual(group.arity, 2, 'group arity');
+      },
+    },
+    {
+      name: 'program keeps negation diagnostics lazy by default',
+      run: () => {
+        const program = Program.parse('p(a).\nq(?x) :- not(p(?x)).\n');
+        assertEqual(program._negationAnalysis, null, 'analysis starts lazy');
+        assertEqual(program.negationDependencies.length, 1, 'dependency count');
+        assertEqual(program._negationAnalysis !== null, true, 'analysis computed on demand');
+      },
+    },
+    {
+      name: 'analyzeNegation option computes diagnostics eagerly',
+      run: () => {
+        const program = Program.parse('p(a).\nq(?x) :- not(p(?x)).\n', { analyzeNegation: true });
+        assertEqual(program._negationAnalysis !== null, true, 'analysis computed eagerly');
+        assertEqual(program.stratifiedNegation, true, 'stratified negation');
+      },
+    },
+    {
+      name: 'program reports stratified negation metadata',
+      run: () => {
+        const program = Program.parse(`
+materialize(open, 1).
+candidate(a).
+blocked(b).
+closed(?x) :- blocked(?x).
+open(?x) :- candidate(?x), not(closed(?x)).
+`);
+        assertEqual(program.isStratifiedNegation(), true, 'stratified negation');
+        assertEqual(program.negationStratificationErrors.length, 0, 'stratification errors');
+        assertEqual(program.findGroup('closed', 1).negationStratum, 0, 'closed stratum');
+        assertEqual(program.findGroup('open', 1).negationStratum, 1, 'open stratum');
+      },
+    },
+    {
+      name: 'program detects unstratified negation cycles',
+      run: () => {
+        const program = Program.parse('p(?x) :- q(?x).\nq(?x) :- not(p(?x)).\n');
+        assertEqual(program.isStratifiedNegation(), false, 'unstratified negation');
+        assertEqual(program.negationStratificationErrors.length, 1, 'stratification error count');
+        assertEqual(program.negationStratificationErrors[0].from, 'q/1', 'error source');
+        assertEqual(program.negationStratificationErrors[0].to, 'p/1', 'error target');
+        let threw = false;
+        try { program.assertStratifiedNegation(); } catch (err) {
+          threw = true;
+          assertIncludes(err.message, 'unstratified negation', 'error message');
+        }
+        assertEqual(threw, true, 'assertion throws');
+      },
+    },
+    {
+      name: 'strictNegation option rejects unstratified programs',
+      run: () => {
+        let threw = false;
+        try { Program.parse('p(?x) :- not(p(?x)).\n', { strictNegation: true }); } catch (err) {
+          threw = true;
+          assertIncludes(err.message, 'p/1 depends negatively on p/1', 'error message');
+        }
+        assertEqual(threw, true, 'strict negation throws');
+      },
+    },
+    {
+      name: 'program and solver public classes',
+      run: () => {
+        const program = Program.parse('p(a).\np(b).\n');
+        const solver = new Solver(program);
+        const goal = parseGoalText('p(?x)');
+        const answers = [...solver.solve([goal], new Env(), 0)].map((env) => termToString(goal, env, true));
+        assertEqual(answers.join('\n'), 'p(a)\np(b)', 'answers');
+      },
+    },
+    {
+      name: 'solver honors solution limits',
+      run: () => {
+        const program = Program.parse('p(a).\np(b).\np(c).\n');
+        const solver = new Solver(program, { solutionLimit: 2 });
+        const goal = parseGoalText('p(?x)');
+        const answers = [...solver.solve([goal], new Env(), 0)].map((env) => termToString(goal, env, true));
+        assertEqual(answers.join('\n'), 'p(a)\np(b)', 'answers');
+      },
+    },
+    {
+      name: 'custom builtin registry can be embedded',
+      run: () => {
+        const registry = new BuiltinRegistry();
+        registry.add('hello', 1, function* ({ goal, env }) {
+          const next = env.clone();
+          if (unify(goal.args[0], atom('world'), next)) yield next;
+        });
+        const program = Program.parse('answer(?x) :- hello(?x).\n');
+        const solver = new Solver(program, { registry });
+        const goal = parseGoalText('answer(?x)');
+        const answers = [...solver.solve([goal], new Env(), 0)].map((env) => termToString(goal, env, true));
+        assertEqual(answers.join('\n'), 'answer(world)', 'answers');
+      },
+    },
+    {
+      name: 'default builtin registry exposes expected metadata',
+      run: () => {
+        const registry = createDefaultRegistry();
+        const between = registry.get('between', 3);
+        const append = registry.get('append', 3);
+        assertEqual(Boolean(between), true, 'between/3 exists');
+        assertEqual(Boolean(append), true, 'append/3 exists');
+        assertEqual(between.name, 'between', 'between name');
+        assertEqual(append.arity, 3, 'append arity');
+      },
+    },
+  ];
+}
+
+function whiteBoxCases() {
+  return [
+    {
+      name: 'unification binds variables in Env',
+      run: () => {
+        const env = new Env();
+        assertEqual(unify(variable('?x'), atom('socrates'), env), true, 'unify result');
+        assertEqual(termToString(variable('?x'), env, true), 'socrates', 'binding');
+      },
+    },
+    {
+      name: 'copyResolved and termIsGround follow bindings',
+      run: () => {
+        const env = new Env();
+        const term = compound('p', [variable('?x'), atom('b')]);
+        assertEqual(termIsGround(term, env), false, 'not ground before binding');
+        assertEqual(unify(variable('?x'), atom('a'), env), true, 'bind ?x');
+        const resolved = copyResolved(term, env);
+        assertEqual(termToString(resolved, new Env(), true), 'p(a, b)', 'resolved term');
+        assertEqual(termIsGround(resolved), true, 'ground after copy');
+      },
+    },
+
+    {
+      name: 'parser rejects non-Prolog unquoted atom spelling',
+      run: () => {
+        let threw = false;
+        try { parseProgramText('value(a-b, ok).\n'); } catch (_) { threw = true; }
+        assertEqual(threw, true, 'a-b must be quoted');
+      },
+    },
+    {
+      name: 'parser rejects zero-arity compound syntax',
+      run: () => {
+        let threw = false;
+        try { parseProgramText('value(nil(), ok).\n'); } catch (_) { threw = true; }
+        assertEqual(threw, true, 'zero-arity compound rejection');
+      },
+    },
+    {
+      name: 'parser preserves list syntax readback',
+      run: () => {
+        const goal = parseGoalText('member(?x, [a, b])');
+        assertEqual(termToString(goal, new Env(), true), 'member(?x, [a, b])', 'goal');
+      },
+    },
+    {
+      name: 'parser accepts question-mark variables',
+      run: () => {
+        const goal = parseGoalText('member(?x, [a, b])');
+        assertEqual(termToString(goal, new Env(), true), 'member(?x, [a, b])', 'goal');
+      },
+    },
+    {
+      name: 'parser treats question-mark underscore as anonymous',
+      run: () => {
+        const clauses = parseProgramText('p(?_, ?_).\n');
+        const left = clauses[0].head.args[0].name;
+        const right = clauses[0].head.args[1].name;
+        assertEqual(left.startsWith('__anon'), true, 'left anonymous');
+        assertEqual(right.startsWith('__anon'), true, 'right anonymous');
+        assertEqual(left === right, false, 'fresh anonymous variables');
+      },
+    },
+    {
+      name: 'parser rejects old uppercase variable spelling',
+      run: () => {
+        let threw = false;
+        try { parseProgramText('p(X).\n'); } catch (_) { threw = true; }
+        assertEqual(threw, true, 'uppercase variable syntax rejected');
+      },
+    },
+    {
+      name: 'parser rejects bare underscore variable spelling',
+      run: () => {
+        let threw = false;
+        try { parseProgramText('p(_).\n'); } catch (_) { threw = true; }
+        assertEqual(threw, true, 'bare underscore syntax rejected');
+      },
+    },
+    {
+      name: 'parser rejects unquoted dotted atoms to stay ISO-compatible',
+      run: () => {
+        let threw = false;
+        try { parseProgramText('p(web(be.ugent, josd)).\n'); } catch (_) { threw = true; }
+        assertEqual(threw, true, 'unquoted dotted atoms must be quoted');
+      },
+    },
+    {
+      name: 'parser preserves quoted dotted atoms for web-style terms',
+      run: () => {
+        const clauses = parseProgramText("p(web('be.ugent', josd), 'org.schema').\n");
+        assertEqual(termToString(clauses[0].head, new Env(), true), "p(web('be.ugent', josd), 'org.schema')", 'head');
+      },
+    },
+    {
+      name: 'parser accepts angle-bracket absolute IRI atoms',
+      run: () => {
+        const clauses = parseProgramText('p(<https://example.org/alice>, <urn:example:bob>).\n');
+        assertEqual(termToString(clauses[0].head, new Env(), true), 'p(<https://example.org/alice>, <urn:example:bob>)', 'head');
+      },
+    },
+    {
+      name: 'readback prints absolute IRI atoms with angle brackets',
+      run: () => {
+        const clauses = parseProgramText("p('https://example.org/alice').\n");
+        assertEqual(termToString(clauses[0].head, new Env(), true), 'p(<https://example.org/alice>)', 'head');
+      },
+    },
+    {
+      name: 'angle IRI syntax does not steal graphic atom syntax',
+      run: () => {
+        const clauses = parseProgramText('p(<=>).\n');
+        assertEqual(termToString(clauses[0].head, new Env(), true), 'p(<=>)', 'head');
+      },
+    },
+    {
+      name: 'list construction round-trips through properListItems',
+      run: () => {
+        const list = listFromItems([atom('a'), numberTerm(2), stringTerm('c')]);
+        const items = properListItems(list, new Env());
+        assertEqual(items.length, 3, 'length');
+        assertEqual(termToString(list, new Env(), true), '[a, 2, "c"]', 'list text');
+      },
+    },
+    {
+      name: 'variantTerms recognizes alpha-equivalent goals',
+      run: () => {
+        const left = parseGoalText('edge(?x, ?y)');
+        const right = parseGoalText('edge(?a, ?b)');
+        const nonVariant = parseGoalText('edge(?a, ?a)');
+        assertEqual(variantTerms(left, new Env(), right, new Env()), true, 'variant');
+        assertEqual(variantTerms(left, new Env(), nonVariant, new Env()), false, 'non-variant');
+      },
+    },
+    {
+      name: 'flattenConjunction preserves left-to-right order',
+      run: () => {
+        const goal = parseGoalText('(a, b, c)');
+        const parts = flattenConjunction(goal).map((part) => termToString(part, new Env(), true));
+        assertEqual(parts.join(' | '), 'a | b | c', 'order');
+      },
+    },
+    {
+      name: 'parseProgramText returns clause objects',
+      run: () => {
+        const clauses = parseProgramText('p(a).\nq(?x) :- p(?x).\n');
+        assertEqual(clauses.length, 2, 'clause count');
+        assertEqual(termToString(clauses[1].head, new Env(), true), 'q(?x)', 'rule head');
+        assertEqual(clauses[1].body.length, 1, 'body length');
+      },
+    },
+    {
+      name: 'clause candidate selection uses scalar indexes with fallback',
+      run: () => {
+        const program = Program.parse('edge(a, b).\nedge(c, d).\nedge(?x, z).\n');
+        const group = program.findGroup('edge', 2);
+        const goal = parseGoalText('edge(a, ?y)');
+        const candidates = selectClauseCandidates(group, goal, new Env());
+        assertEqual(candidates.primary.length, 1, 'primary bucket length');
+        assertEqual(candidates.fallback.length, 1, 'fallback length');
+        assertEqual(termToString(candidates.primary[0].head, new Env(), true), 'edge(a, b)', 'primary head');
+      },
+    },
+    {
+      name: 'table declaration marks predicate group tabled',
+      run: () => {
+        const program = Program.parse('table(path, 2).\nedge(a, b).\npath(?x, ?y) :- edge(?x, ?y).\n');
+        const group = program.findGroup('path', 2);
+        assertEqual(Boolean(group), true, 'path/2 group exists');
+        assertEqual(group.tabled, true, 'path/2 tabled through table/2');
+      },
+    },
+    {
+      name: 'memoize fact does not table predicates',
+      run: () => {
+        const program = Program.parse('memoize(path, 2).\nedge(a, b).\npath(?x, ?y) :- edge(?x, ?y).\n');
+        const group = program.findGroup('path', 2);
+        assertEqual(Boolean(group), true, 'path/2 group exists');
+        assertEqual(group.tabled, false, 'memoize/2 is not a table declaration');
+      },
+    },
+    {
+      name: 'mode and determinism declarations annotate predicate groups',
+      run: () => {
+        const program = Program.parse('mode(path, 2, [in, out]).\ndet(path, 2).\nedge(a, b).\npath(?x, ?y) :- edge(?x, ?y).\n');
+        const group = program.findGroup('path', 2);
+        assertEqual(Boolean(group), true, 'path/2 group exists');
+        assertEqual(group.mode.join(','), 'in,out', 'path/2 mode');
+        assertEqual(group.determinism, 'det', 'path/2 determinism');
+      },
+    },
+    {
+      name: 'semidet declaration annotates predicate groups',
+      run: () => {
+        const program = Program.parse('semidet(edge, 2).\nedge(a, b).\n');
+        const group = program.findGroup('edge', 2);
+        assertEqual(Boolean(group), true, 'edge/2 group exists');
+        assertEqual(group.determinism, 'semidet', 'edge/2 determinism');
+      },
+    },
+    {
+      name: 'challenging examples keep dynamic-programming predicates tabled',
+      run: () => {
+        const checks = [
+          ['binomial-vandermonde.eye', 'choose_step', 5, true],
+          ['catalan-convolution.eye', 'catalan', 2, false],
+          ['chart-parser.eye', 'span', 4, true],
+          ['continued-fraction-sqrt2.eye', 'conv', 3, true],
+          ['critical-path-schedule.eye', 'earliest_start', 2, false],
+          ['critical-path-schedule.eye', 'finish_time', 2, false],
+          ['integer-partitions.eye', 'partitions', 3, true],
+          ['matrix-chain-order.eye', 'cost', 3, false],
+          ['modular-exponentiation.eye', 'pow_mod', 4, true],
+          ['pell-equation.eye', 'pell', 3, true],
+          ['stirling-bell-numbers.eye', 'stirling2', 3, true],
+          ['totient-summatory.eye', 'gcd', 3, true],
+          ['totient-summatory.eye', 'totient', 2, false],
+          ['weighted-interval-scheduling.eye', 'best_from', 2, true],
+        ];
+        for (const [filename, name, arity, recursive] of checks) {
+          const text = fs.readFileSync(path.join(packageRoot, 'examples', filename), 'utf8');
+          const program = Program.parseSources([{ text, filename }]);
+          const group = program.findGroup(name, arity);
+          assertEqual(Boolean(group), true, `${filename} ${name}/${arity} group exists`);
+          assertEqual(group.tabled, true, `${filename} ${name}/${arity} tabled`);
+          assertEqual(group.recursive, recursive, `${filename} ${name}/${arity} recursive`);
+        }
+      },
+    },
+    {
+      name: 'n-queens example keeps diagonal checks tabled',
+      run: () => {
+        const text = fs.readFileSync(path.join(packageRoot, 'examples', 'n-queens-8.eye'), 'utf8');
+        const program = Program.parseSources([{ text, filename: 'n-queens-8.eye' }]);
+        const group = program.findGroup('no_diagonal_attack', 3);
+        assertEqual(Boolean(group), true, 'no_diagonal_attack/3 group exists');
+        assertEqual(group.tabled, true, 'no_diagonal_attack/3 tabled');
+        assertEqual(group.recursive, true, 'no_diagonal_attack/3 recursive');
+      },
+    },
+    {
+      name: 'collatz example keeps recursive trajectory predicate tabled',
+      run: () => {
+        const text = fs.readFileSync(path.join(packageRoot, 'examples', 'collatz-1000.eye'), 'utf8');
+        const program = Program.parseSources([{ text, filename: 'collatz-1000.eye' }]);
+        const group = program.findGroup('collatz', 2);
+        assertEqual(Boolean(group), true, 'collatz/2 group exists');
+        assertEqual(group.tabled, true, 'collatz/2 tabled');
+        assertEqual(group.recursive, true, 'collatz/2 recursive');
+      },
+    },
+    {
+      name: 'collatz example remains stack-safe for browser-sized stacks',
+      run: () => {
+        // Use a deliberately tiny stack to catch browser-worker recursion regressions.
+        const result = spawnSync(process.execPath, ['--stack-size=100', bin, 'examples/collatz-1000.eye'], {
+          cwd: packageRoot,
+          encoding: 'utf8',
+        });
+        assertEqual(result.status, 0, `exit status${result.stderr ? `\nstderr: ${result.stderr}` : ''}`);
+        assertEqual(result.stderr, '', 'stderr');
+        assertIncludes(result.stdout, 'collatzTrajectory(1000, [1000, 500, 250, 125', 'stdout');
+        assertIncludes(result.stdout, 'collatzTrajectory(1, [1]).\n', 'stdout');
+      },
+    },
+  ];
+}
+
+function runSection(reporter, name, cases) {
+  reporter.section(name);
+  for (const testCase of cases) reporter.test(testCase.name, testCase.run);
+  reporter.sectionTotal(sectionLabel(name));
+}
+
+function sectionLabel(name) {
+  if (name === 'Documentation sync') return 'documentation sync';
+  if (name === 'API') return 'API';
+  if (name === 'White-box') return 'white-box';
+  return name.toLowerCase();
+}
+
+function runWhy({ program, goalText, expected }) {
+  const programFile = path.join(tmp, `${++tmpCounter}.eye`);
+  fs.writeFileSync(programFile, program);
+  const goal = parseGoalText(goalText);
+  fs.appendFileSync(programFile, `\nmaterialize(${goal.name}, ${goal.arity}).\n`);
+  const result = runCli(['--proof', programFile]);
+  assertEqual(result.status, 0, 'exit status');
+  assertEqual(result.stderr, '', 'stderr');
+  const expectedText = expected.replaceAll('__FILE__', path.basename(programFile));
+  assertEqual(result.stdout, expectedText, 'stdout');
+
+  Program.parse(result.stdout);
+  assertIncludes(result.stdout, '  proof(\n', 'stdout');
+  assertIncludes(result.stdout, ' by(rule("', 'stdout');
+  assertIncludes(result.stdout, ', clause(', 'stdout');
+  assertNotIncludes(result.stdout, 'source(head(', 'stdout');
+  assertIncludes(result.stdout, '\n).\n\n', 'stdout');
+}
+
+function runWhyLoose({ program, goalText }) {
+  const programFile = path.join(tmp, `${++tmpCounter}.eye`);
+  fs.writeFileSync(programFile, program);
+  const goal = parseGoalText(goalText);
+  fs.appendFileSync(programFile, `\nmaterialize(${goal.name}, ${goal.arity}).\n`);
+  const result = runCli(['--proof', programFile]);
+  assertEqual(result.status, 0, 'exit status');
+  assertEqual(result.stderr, '', 'stderr');
+  Program.parse(result.stdout);
+  assertIncludes(result.stdout, '\n).\n\n', 'stdout');
+  return result;
+}
+
+function listExampleNames() {
+  return fs.readdirSync(path.join(packageRoot, 'examples'))
+    .filter((name) => name.endsWith('.eye'))
+    .map((name) => name.slice(0, -4))
+    .sort();
+}
+
+function guideExampleCatalogIssues() {
+  const issues = [];
+  const expected = listExampleNames();
+  const guide = fs.readFileSync(path.join(packageRoot, 'docs', 'guide.md'), 'utf8');
+  const section = between(guide, '## Example catalog', '## Golden outputs, tests, and conformance');
+  const rows = [...section.matchAll(/^\| \[`([A-Za-z0-9_-]+)\.eye`\]\(\.\.\/examples\/\1\.eye\) \|[^|]+\| \[`output\/\1\.eye`\]\(\.\.\/examples\/output\/\1\.eye\) \|$/gm)]
+    .map((match) => match[1]);
+  const sourceNames = [...section.matchAll(/\.\.\/examples\/([A-Za-z0-9_-]+)\.eye/g)].map((match) => match[1]).sort();
+  const outputNames = [...section.matchAll(/\.\.\/examples\/output\/([A-Za-z0-9_-]+)\.eye/g)].map((match) => match[1]).sort();
+  if (rows.length !== expected.length) issues.push(`expected ${expected.length} complete example rows, found ${rows.length}`);
+  issues.push(...arrayDiffMessages(rows.sort(), expected, 'complete example rows'));
+  issues.push(...arrayDiffMessages(sourceNames, expected, 'source links'));
+  issues.push(...arrayDiffMessages(outputNames, expected, 'output links'));
+  for (const name of expected) {
+    const outputPath = path.join(packageRoot, 'examples', 'output', `${name}.eye`);
+    if (!fs.existsSync(outputPath)) issues.push(`missing examples/output/${name}.eye`);
+  }
+  return issues.sort();
+}
+
+function playgroundExampleIssues() {
+  const issues = [];
+  const expected = listExampleNames();
+  const html = fs.readFileSync(path.join(packageRoot, 'playground.html'), 'utf8');
+  const match = html.match(/const EXAMPLES = (\[[\s\S]*?\]);/);
+  if (match == null) return ['playground EXAMPLES array not found'];
+  const examples = JSON.parse(match[1]).sort();
+  issues.push(...arrayDiffMessages(examples, expected, 'playground EXAMPLES'));
+  if (!html.includes('new URL(`./examples/${name}.eye`, location.href)')) {
+    issues.push('playground must load selected examples from relative ./examples/*.eye URLs');
+  }
+  if (!html.includes("fetch(exampleUrl, { cache: 'no-store' })")) {
+    issues.push('playground must fetch selected example source from its relative URL');
+  }
+  return issues.sort();
+}
+
+function playgroundStaticIssues() {
+  const issues = [];
+  const playgroundPath = path.join(packageRoot, 'playground.html');
+  const html = fs.readFileSync(playgroundPath, 'utf8');
+  const readme = fs.readFileSync(path.join(packageRoot, 'README.md'), 'utf8');
+  if (!pkg.files?.includes('playground.html')) issues.push('package files must include playground.html');
+  if (!readme.includes('[Playground](https://eyereasoner.github.io/eyelang/playground)')) issues.push('README must link to the GitHub Pages playground URL');
+  if (!html.includes('<meta name="viewport" content="width=device-width, initial-scale=1">')) issues.push('missing mobile viewport meta');
+  if (!html.includes('main {') || !html.includes('display: block;')) {
+    issues.push('playground must use a simple vertical layout');
+  }
+  if (!html.includes('@media (max-width: 560px)') || !html.includes('button,') || !html.includes('width: 100%')) {
+    issues.push('playground must make controls usable at phone widths');
+  }
+  if (!html.includes('<summary id="advanced-heading">⚙ Advanced configuration</summary>')) {
+    issues.push('playground must keep URL/proof controls inside advanced configuration');
+  }
+  if (!html.includes('id="load-background"') || !html.includes('backgroundSource') || !html.includes('combinedSource()')) {
+    issues.push('playground must support loading URL content as background knowledge');
+  }
+  if (!html.includes('HIGHLIGHT_LIMIT') || !html.includes('text.length > HIGHLIGHT_LIMIT')) {
+    issues.push('playground must avoid full syntax coloring for very large examples');
+  }
+  if (!html.includes('<script type="module">')) issues.push('playground script must be an ES module');
+  if (!html.includes("new URL('./src/index.js', location.href)")) issues.push('playground must import the public browser API');
+  if (!html.includes('class="editor"') || !html.includes('id="highlight"') || !html.includes('id="source"')) {
+    issues.push('playground must include layered syntax-colored editor');
+  }
+  if (!html.includes('--editor-bg: #ffffff') || !html.includes('background: var(--editor-bg)')) {
+    issues.push('playground editor must use a light editor background');
+  }
+  if (!html.includes('id="error-line-marker"') || !html.includes('extractParseErrorLine') || !html.includes('markSyntaxErrorLine') || !html.includes('--editor-error-line')) {
+    issues.push('playground must highlight syntax-error lines in the editor');
+  }
+  if (!html.includes('id="line-numbers"') || !html.includes('updateLineNumbers') || !html.includes('lineNumbersInner.style.transform') || !html.includes('--line-number-bg')) {
+    issues.push('playground editor must include synced line numbers');
+  }
+  if (!html.includes('MAX_SHARE_URL_LENGTH') || !html.includes('buildReferenceShareLink') || !html.includes("params.set('example'") || !html.includes("params.set('url'")) {
+    issues.push('playground share links must avoid embedding large example or URL-loaded sources');
+  }
+  if (!html.includes('id="create-gist"') || !html.includes('createGistShare') || !html.includes('GIST_STATE_FILENAME') || !html.includes("fetch('https://api.github.com/gists'")) {
+    issues.push('playground must support Gist-backed sharing for large programs');
+  }
+  if (!html.includes('await createGistShare({') || html.includes('Use “Create Gist share” instead')) {
+    issues.push('playground Copy share link must automatically fall back to Gist sharing for large programs');
+  }
+  if (!html.includes("params.has('state-url')") || !html.includes('#state-url=')) {
+    issues.push('playground must restore state from raw Gist state URLs');
+  }
+  if (!html.includes('id="example-search"') || !html.includes('id="examples"')) issues.push('playground must include searchable examples');
+  const scriptMatch = html.match(new RegExp('<script type="module">\\n([\\s\\S]*?)\\n  <\\/script>'));
+  if (scriptMatch == null) {
+    issues.push('module script not found');
+  } else {
+    const scriptFile = path.join(tmp, 'playground-script.mjs');
+    fs.writeFileSync(scriptFile, scriptMatch[1]);
+    const result = spawnSync(process.execPath, ['--check', scriptFile], { encoding: 'utf8' });
+    if (result.status !== 0) issues.push(`playground module syntax check failed: ${result.stderr.trim()}`);
+  }
+  return issues.sort();
+}
+
+function registeredBuiltinNames() {
+  return [...createDefaultRegistry().defs.keys()].sort();
+}
+
+function registeredBuiltinSummary() {
+  const names = registeredBuiltinNames();
+  return {
+    entries: names.length,
+    names: new Set(names.map((name) => name.split('/')[0])).size,
+  };
+}
+
+function guideBuiltinNames() {
+  const guide = fs.readFileSync(path.join(packageRoot, 'docs', 'guide.md'), 'utf8');
+  return documentedBuiltinNames(between(guide, '### Builtins', '## Aggregation helpers'));
+}
+
+function guideBuiltinSummary() {
+  const guide = fs.readFileSync(path.join(packageRoot, 'docs', 'guide.md'), 'utf8');
+  const section = between(guide, '### Builtins', '## Aggregation helpers');
+  const match = section.match(/currently registers (\d+) name\/arity entries across (\d+) predicate names/);
+  if (match == null) throw new Error('guide builtin summary not found');
+  return { entries: Number(match[1]), names: Number(match[2]) };
+}
+
+function languageReferenceBuiltinNames() {
+  const reference = fs.readFileSync(path.join(packageRoot, 'docs', 'language-reference.md'), 'utf8');
+  return documentedBuiltinNames(between(reference, '## 9. Standard built-in predicates', '## 10. Implementation-specific built-ins'));
+}
+
+function documentedBuiltinNames(section) {
+  const names = [];
+  for (const line of section.split('\n')) {
+    if (!line.trim().startsWith('|') || !line.includes('`')) continue;
+    for (const match of line.matchAll(/`([A-Za-z_][A-Za-z0-9_]*)\(([^`)]*)\)`/g)) {
+      const arity = match[2].trim() === '' ? 0 : match[2].split(',').length;
+      names.push(`${match[1]}/${arity}`);
+    }
+    for (const match of line.matchAll(/`([A-Za-z_][A-Za-z0-9_]*)\/(\d+)`/g)) {
+      names.push(`${match[1]}/${match[2]}`);
+    }
+  }
+  return [...new Set(names)].sort();
+}
+
+function runtimeExportNames() {
+  return Object.keys(publicApi).sort();
+}
+
+function declaredValueExportNames() {
+  const dts = fs.readFileSync(path.join(packageRoot, 'index.d.ts'), 'utf8');
+  return [...dts.matchAll(/^export\s+(?:declare\s+)?(?:class|function|const)\s+([A-Za-z_][A-Za-z0-9_]*)/gm)]
+    .map((match) => match[1])
+    .filter((name, index, names) => names.indexOf(name) === index)
+    .sort();
+}
+
+function missingDocumentedPackageScripts() {
+  const docs = documentationFiles();
+  const missing = [];
+  const nativeCommands = new Set(['exec', 'install', 'link']);
+  for (const file of docs) {
+    const text = fs.readFileSync(file, 'utf8');
+    for (const line of text.split('\n')) {
+      const trimmed = line.trim();
+      const commandTexts = [];
+      if (trimmed.startsWith('npm ')) commandTexts.push(trimmed);
+      for (const match of line.matchAll(/`([^`]*\bnpm\s+[^`]*)`/g)) commandTexts.push(match[1].trim());
+      for (const commandText of commandTexts) {
+        const match = commandText.match(/^npm\s+(?:run\s+)?([A-Za-z0-9:_-]+)/);
+        if (match == null) continue;
+        const command = match[1];
+        if (nativeCommands.has(command)) continue;
+        const script = command === 'test' ? 'test' : command;
+        if (!pkg.scripts?.[script]) missing.push(`${path.relative(packageRoot, file)}: npm ${command === 'test' ? 'test' : `run ${script}`}`);
+      }
+    }
+  }
+  return [...new Set(missing)].sort();
+}
+
+function misleadingDependencyInstallDocs() {
+  const misleading = [];
+  for (const file of documentationFiles()) {
+    const text = fs.readFileSync(file, 'utf8');
+    if (text.includes('Install dependencies')) misleading.push(`${path.relative(packageRoot, file)}: Install dependencies`);
+    if (text.includes('npm install\n```') || text.includes('npm install\r\n```')) {
+      misleading.push(`${path.relative(packageRoot, file)}: bare npm install setup block`);
+    }
+  }
+  return [...new Set(misleading)].sort();
+}
+
+function documentationSourceStyleIssues() {
+  const issues = [];
+  const docsRoot = path.join(packageRoot, 'docs');
+  const docs = [
+    path.join(docsRoot, 'guide.md'),
+    path.join(docsRoot, 'language-reference.md'),
+  ];
+  for (const file of docs) {
+    const text = fs.readFileSync(file, 'utf8');
+    if (text.includes('```prolog')) {
+      issues.push(`${path.relative(packageRoot, file)}: use eyelang code fences instead of prolog fences`);
+    }
+  }
+
+  const reference = fs.readFileSync(path.join(docsRoot, 'language-reference.md'), 'utf8');
+  const builtins = between(reference, '## 9. Standard built-in predicates', '## 10. Implementation-specific built-ins');
+  const staleMetaVariables = /`[^`]*(?<!\?)(?:\b(?:A|B|C|D|N|T|Low|High|Start|Needle|Context|Search|Generator|Test|Goal)\b)[^`]*`/;
+  for (const [index, line] of builtins.split('\n').entries()) {
+    if (!line.trim().startsWith('|')) continue;
+    if (line.includes('EYELANG_LOCAL_TIME=')) continue;
+    if (staleMetaVariables.test(line)) {
+      issues.push(`docs/language-reference.md section 9 line ${index + 1}: stale Prolog-style metavariable in built-in description: ${line.trim()}`);
+    }
+  }
+  return issues.sort();
+}
+
+function findBrokenDocLinks() {
+  const broken = [];
+  const anchorsByFile = new Map();
+  for (const file of documentationFiles()) {
+    const text = fs.readFileSync(file, 'utf8');
+    for (const target of markdownLinkTargets(text)) {
+      if (/^(?:https?:|mailto:)/i.test(target)) continue;
+      const [targetPathRaw, fragmentRaw] = target.split('#');
+      const targetPath = targetPathRaw === '' ? file : path.resolve(path.dirname(file), decodeURI(targetPathRaw));
+      const display = `${path.relative(packageRoot, file)} -> ${target}`;
+      if (!fs.existsSync(targetPath)) {
+        broken.push(`${display} (missing target)`);
+        continue;
+      }
+      if (fragmentRaw != null && fragmentRaw !== '') {
+        const anchors = anchorsByFile.get(targetPath) ?? markdownAnchors(targetPath);
+        anchorsByFile.set(targetPath, anchors);
+        if (!anchors.has(fragmentRaw)) broken.push(`${display} (missing heading #${fragmentRaw})`);
+      }
+    }
+  }
+  return broken.sort();
+}
+
+function documentationFiles() {
+  return [
+    path.join(packageRoot, 'README.md'),
+    path.join(packageRoot, 'docs', 'guide.md'),
+    path.join(packageRoot, 'docs', 'language-reference.md'),
+  ];
+}
+
+function markdownLinkTargets(text) {
+  return [...text.matchAll(/!?\[[^\]\n]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g)].map((match) => match[1]);
+}
+
+function markdownAnchors(file) {
+  if (!file.endsWith('.md')) return new Set();
+  const text = fs.readFileSync(file, 'utf8');
+  const anchors = new Set();
+  const counts = new Map();
+  for (const match of text.matchAll(/^#{1,6}\s+(.+)$/gm)) {
+    const base = githubSlug(match[1]);
+    const count = counts.get(base) ?? 0;
+    counts.set(base, count + 1);
+    anchors.add(count === 0 ? base : `${base}-${count}`);
+  }
+  return anchors;
+}
+
+function githubSlug(heading) {
+  return heading
+    .replace(/`([^`]*)`/g, '$1')
+    .replace(/<[^>]+>/g, '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^\p{Letter}\p{Number}\s-]/gu, '')
+    .trim()
+    .replace(/\s+/g, '-');
+}
+
+function between(text, startMarker, endMarker) {
+  const start = text.indexOf(startMarker);
+  if (start === -1) throw new Error(`${startMarker} not found`);
+  const contentStart = start + startMarker.length;
+  const end = text.indexOf(endMarker, contentStart);
+  if (end === -1) throw new Error(`${endMarker} not found`);
+  return text.slice(contentStart, end);
+}
+
+function runCli(args, options = {}) {
+  return spawnSync(process.execPath, [bin, ...args], {
+    cwd: packageRoot,
+    encoding: 'utf8',
+    env: options.env ? { ...process.env, ...options.env } : process.env,
+    input: options.input ?? undefined,
+  });
+}
+
+function assertEqual(actual, expected, label) {
+  if (actual !== expected) throw new Error(`${label} mismatch\nexpected: ${format(expected)}\nactual:   ${format(actual)}`);
+}
+
+function assertIncludes(actual, expected, label) {
+  if (!actual.includes(expected)) throw new Error(`${label} did not include ${format(expected)}\nactual: ${format(actual)}`);
+}
+
+function assertNotIncludes(actual, expected, label) {
+  if (String(actual).includes(expected)) throw new Error(`${label} unexpectedly included ${format(expected)}\nactual: ${format(actual)}`);
+}
+
+function arrayDiffMessages(actual, expected, label) {
+  const messages = [];
+  const actualSet = new Set(actual);
+  const expectedSet = new Set(expected);
+  for (const item of expected) if (!actualSet.has(item)) messages.push(`${label} missing ${item}`);
+  for (const item of actual) if (!expectedSet.has(item)) messages.push(`${label} has unexpected ${item}`);
+  if (new Set(actual).size !== actual.length) messages.push(`${label} has duplicate entries`);
+  return messages;
+}
+
+function assertArrayEqual(actual, expected, label) {
+  const actualText = actual.join('\n');
+  const expectedText = expected.join('\n');
+  if (actualText !== expectedText) {
+    const onlyActual = actual.filter((item) => !expected.includes(item));
+    const onlyExpected = expected.filter((item) => !actual.includes(item));
+    throw new Error(`${label} mismatch\nonly actual: ${format(onlyActual)}\nonly expected: ${format(onlyExpected)}`);
+  }
+}
+
+function format(value) {
+  return typeof value === 'string' ? JSON.stringify(value) : String(value);
+}
+
+if (isMainModule(import.meta.url)) {
+  const reporter = new TestReporter();
+  try {
+    runRegression(reporter);
+    reporter.totalLine();
+  } catch (_) {
+    process.exit(1);
+  }
+}