What programs mean (the languages, translators, Mojo checker and
interpreter, prover, fuzzer, machine model, catalog problems and the Mojo
corpus with godbolt's stored answers) was mixed into the site's tree, so a
change to the prover and a change to a button went through the same gate
and the same docs. This moves all of it under core/, laid out as its own
repository, ready to be extracted with its history and pinned here as a
git submodule.
- core/: src/{engines,services,sync,mojo,exercises,curriculum,common},
mojo/, syntax/mojo.xml, its tests (with Workspace and workForProblem in
place of the site's Session), scripts (corpus pipeline, play, the
exercise and probe starters, engines export/diff), and its docs
(engines, trust, mojo-corpus, exercises, coverage). Its own pixi.toml,
package.json, README, AGENTS.md and CI workflow.
- core/tests/boundary.test.mjs: library modules use no DOM, import no
page widget, and import nothing outside src/.
- core/scripts/cli.mjs: pixi run cli check|run|prove|fuzz|translate.
- core/scripts/dafny.py: Dafny 4.11.0 pinned by version and SHA-256 per
platform, fetched into .tools/ (pixi run dafny-fetch, pixi run dafny).
- The site imports core only as #core/<path>.js: an import map in
index.html, "imports" in package.json for node, core's declarations for
tsc. The site's TypeScript builds core first (npm run build).
- assemble.sh, the Quarto engine copy, the render cache key, check-pages,
quarto-export and quarto-css read core/dist and core/mojo; quarto-css
copies core's syntax/mojo.xml into the extension.
- Site tests that covered engines moved to core; the rest keep Session.
- README, AGENTS.md, docs/app.md, docs/deploy.md and the CI workflow
describe the split (checkout with submodules; core's tests and corpus
status run against the pinned commit).
Gate: site 110 pass; core 307 pass; corpus status --strict passes.
Manual check: the assembled site opens Bridge (count-base-proved),
Developer and Hardware (count-base) with the editor, the stepper and the
board, and no module errors.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FgvbRdoEheAHqsRmr2WuKZ
176 lines
12 KiB
JavaScript
176 lines
12 KiB
JavaScript
#!/usr/bin/env node
|
|
// Check every program a Quarto site embeds with the extension's shortcodes ({{< pplus-run >}}, {{< pplus >}}, ...):
|
|
// the .lingo, .pseudo, .speco, .tex and .mojo files next to the pages, and the shortcodes that name them, run
|
|
// through this repository's own engines (build first: pixi run build).
|
|
//
|
|
// node scripts/check-pages.mjs /path/to/site/programmingplus [more folders ...]
|
|
//
|
|
// Set PPLUS_DIR to use another checkout's dist/ (and its core/dist/); set CHECK_FILES_ONLY=1 to only check that the files
|
|
// the shortcodes name exist (no engine needed).
|
|
//
|
|
// A program file may carry expectations in comment lines at the top:
|
|
// // CALL: COUNT_BASE('A', "GATTACA") the call to run (pseudo and lingo; otherwise the engine's default)
|
|
// // INPUT: 4000 a line INPUT reads (repeatable)
|
|
// // EXPECT: 3 a line of output, in order (repeatable; a Mojo file may write # expect-stdout:); the call's result
|
|
// counts as "<NAME> returned <value>"
|
|
// // ERRORS: 1 the program is meant to be refused with this many errors
|
|
// // STOPS: race the run is meant to stop with this kind of error (race, contract, bounds, ...)
|
|
// // QUESTION: range-ends lingo: the reader is meant to ask this question
|
|
// A lingo file is also lowered to pseudo, and that pseudo must check. A .tex file (LaTeX equations) uses
|
|
// % instead of // for its header lines, is translated to pseudo, and that pseudo must check and run.
|
|
// A .mojo file uses # for its header lines. It must be free of syntax the pinned Mojo removed (fn, read),
|
|
// and when a `mojo` compiler is on the PATH (inside pixi, which pins it) it is built and run for real:
|
|
// it must exit 0 and print its EXPECT lines, or, with ERRORS, fail to compile.
|
|
import fs from 'node:fs';
|
|
import path from 'node:path';
|
|
import { pathToFileURL } from 'node:url';
|
|
import { spawnSync } from 'node:child_process';
|
|
|
|
const here = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..');
|
|
const root = process.cwd();
|
|
const folders = process.argv.slice(2);
|
|
if (!folders.length) { console.error('usage: node scripts/check-pages.mjs <folder with .qmd pages> [...]'); process.exit(2); }
|
|
const pplusDir = process.env.CHECK_FILES_ONLY ? null : (process.env.PPLUS_DIR || here);
|
|
|
|
function walk(dir, out = []) {
|
|
for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
|
|
if (e.name.startsWith('_') || e.name.startsWith('.')) continue;
|
|
const p = path.join(dir, e.name);
|
|
if (e.isDirectory()) walk(p, out); else out.push(p);
|
|
}
|
|
return out;
|
|
}
|
|
|
|
// the live shortcodes' view= values (src/core/state.ts EMBED_VIEWS), and pplus-view's (src/quarto/render.ts
|
|
// STATIC_VIEWS), kept here so CHECK_FILES_ONLY needs no build; tests/quarto.test.mjs holds them to the app's
|
|
const EMBED_VIEWS = new Set(['playground', 'trace', 'table', 'flow', 'data', 'life', 'proof', 'tests', 'problems', 'compiler', 'asm', 'lingo', 'matho', 'pseudo', 'speco', 'mojo']);
|
|
const STATIC_VIEWS = new Set(['run', 'steps', 'table', 'flow', 'data', 'dataflow', 'life', 'lifetimes', 'proof', 'tests', 'check', 'translate', 'machine', 'hw']);
|
|
// the machine's views, pplus-hw-<view> (src/quarto/machine.ts HW_NAMES), also what pplus-hw's views= may name
|
|
const HW_VIEWS = ['code', 'explain', 'registers', 'flags', 'address', 'memory', 'stack', 'dataflow', 'alu', 'branches', 'vectors', 'lines', 'cache', 'hierarchy', 'paging', 'pipeline', 'uops', 'timeline', 'bottleneck', 'counters', 'chip', 'core', 'encoding'];
|
|
// every shortcode of the extension (src/quarto/shortcodes.ts SHORTCODE_NAMES)
|
|
const SHORTCODES = new Set(['pplus', 'pplus-embed', 'pplus-playground', 'pplus-view', 'pplus-run', 'pplus-steps', 'pplus-table', 'pplus-flow', 'pplus-dataflow', 'pplus-lifetimes', 'pplus-proof', 'pplus-tests', 'pplus-check', 'pplus-translate', 'pplus-machine', 'pplus-hw', ...HW_VIEWS.map((v) => `pplus-hw-${v}`), 'pplus-listing', 'pplus-tabs', 'pplus-link']);
|
|
|
|
const files = folders.flatMap((f) => walk(path.resolve(root, f)));
|
|
const pages = files.filter((f) => f.endsWith('.qmd'));
|
|
const programs = files.filter((f) => /\.(lingo|pseudo|speco|tex|mojo)$/.test(f));
|
|
let failures = 0;
|
|
const fail = (where, msg) => { failures++; console.log(`✗ ${path.relative(root, where)}: ${msg}`); };
|
|
|
|
// 1. shortcodes name files that exist
|
|
const referenced = new Set();
|
|
for (const page of pages) {
|
|
const text = fs.readFileSync(page, 'utf8');
|
|
// {{< pplus-name ... >}}, but not an escaped {{{< ... >}}} (a page showing the shortcode as text)
|
|
for (const m of text.matchAll(/(?<!\{)\{\{<\s*(pplus(?:-[a-z]+)?)(\s+[^>]*)?>\}\}(?!\})/g)) {
|
|
const name = m[1], args = m[2] ?? '';
|
|
if (!SHORTCODES.has(name)) { fail(page, `{{< ${name} >}} is not a shortcode of the extension; they are ${[...SHORTCODES].join(', ')}`); continue; }
|
|
const view = /\bview="([^"]+)"/.exec(args)?.[1];
|
|
const views = name === 'pplus-view' ? STATIC_VIEWS : name === 'pplus-hw' ? new Set(HW_VIEWS) : EMBED_VIEWS;
|
|
if (view && !name.startsWith('pplus-hw-') && !views.has(view)) fail(page, `{{< ${name} >}} has view="${view}"; the views are ${[...views].join(', ')}`);
|
|
for (const v of (/\bviews="([^"]+)"/.exec(args)?.[1] ?? '').split(/[\s,]+/).filter(Boolean)) if (!HW_VIEWS.includes(v)) fail(page, `{{< ${name} >}} names the machine view "${v}"; the views are ${HW_VIEWS.join(', ')}`);
|
|
for (const a of args.matchAll(/\b(lingo|matho|pseudo|speco|mojo|asm|setup)="([^"]+)"/g)) {
|
|
const f = path.join(path.dirname(page), a[2]);
|
|
if (!fs.existsSync(f)) fail(page, `{{< ${name} >}} names ${a[2]}, which does not exist`);
|
|
else referenced.add(f);
|
|
}
|
|
}
|
|
}
|
|
for (const p of programs) if (!referenced.has(p) && !/\.(speco)$/.test(p)) console.log(` (note) ${path.relative(root, p)} is not embedded by any page`);
|
|
|
|
if (!pplusDir) {
|
|
console.log(`check-pages: ${programs.length} program files, ${failures} problems (files only; unset CHECK_FILES_ONLY to run them)`);
|
|
process.exit(failures ? 1 : 0);
|
|
}
|
|
|
|
// 2. every program parses, runs, and prints what it says
|
|
const dist = path.join(pplusDir, 'dist');
|
|
const coreDist = path.join(pplusDir, 'core', 'dist'); // pplus-core, built beside the app
|
|
const { studyOf, runPseudo } = await import(pathToFileURL(path.join(coreDist, 'services/pseudo.js')));
|
|
const { removedSyntax } = await import(pathToFileURL(path.join(coreDist, 'mojo/check.js')));
|
|
const { MOJO_VERSION } = await import(pathToFileURL(path.join(coreDist, 'mojo/generated/pin.js')));
|
|
const mojoVersion = (() => { const r = spawnSync('mojo', ['--version'], { encoding: 'utf8' }); return r.status === 0 ? r.stdout.trim() : null; })();
|
|
if (programs.some((f) => f.endsWith('.mojo'))) {
|
|
if (!mojoVersion) console.log(' (note) no mojo compiler on the PATH: .mojo files are checked for removed syntax only. Run inside pixi to build and run them.');
|
|
else if (!mojoVersion.includes(MOJO_VERSION)) console.log(` (warning) ${mojoVersion} is not the pinned Mojo ${MOJO_VERSION}; results may not match the site`);
|
|
}
|
|
const { readLingo, lowerLingo, runLingo } = await import(pathToFileURL(path.join(coreDist, 'services/lingo.js')));
|
|
const { parseMatho, lowerMatho, runMatho } = await import(pathToFileURL(path.join(coreDist, 'services/matho.js')));
|
|
|
|
function header(text) {
|
|
const h = { expect: [], input: [], questions: [], stops: null };
|
|
for (const line of text.split('\n')) {
|
|
const m = /^\s*(?:\/\/|%|#)\s*(CALL|INPUT|EXPECT|ERRORS|QUESTION|STOPS|expect-stdout):\s?(.*)$/.exec(line);
|
|
if (!m) continue;
|
|
if (m[1] === 'CALL') h.call = m[2].trim();
|
|
else if (m[1] === 'INPUT') h.input.push(m[2]);
|
|
else if (m[1] === 'EXPECT' || m[1] === 'expect-stdout') h.expect.push(m[2]);
|
|
else if (m[1] === 'ERRORS') h.errors = Number(m[2]);
|
|
else if (m[1] === 'QUESTION') h.questions.push(m[2].trim());
|
|
else if (m[1] === 'STOPS') h.stops = m[2].trim();
|
|
}
|
|
return h;
|
|
}
|
|
|
|
function checkRun(file, tr, h) {
|
|
if (h.stops) { if (!tr.error) fail(file, `was meant to stop with a ${h.stops} error and ran to the end`); else if (tr.error.kind !== h.stops) fail(file, `was meant to stop with a ${h.stops} error and stopped with ${tr.error.kind}: ${tr.error.message}`); return; }
|
|
if (tr.error) { fail(file, `stopped: ${tr.error.message}`); return; }
|
|
if (h.expect.length) {
|
|
const got = tr.output;
|
|
const want = h.expect;
|
|
if (JSON.stringify(got) !== JSON.stringify(want)) fail(file, `printed ${JSON.stringify(got)}, expected ${JSON.stringify(want)}`);
|
|
}
|
|
}
|
|
|
|
for (const file of programs) {
|
|
const text = fs.readFileSync(file, 'utf8');
|
|
const h = header(text);
|
|
if (file.endsWith('.pseudo')) {
|
|
const st = studyOf(text);
|
|
const errs = st.diagnostics.filter((d) => d.severity === 'error');
|
|
if (h.errors !== undefined) { if (errs.length !== h.errors) fail(file, `expected ${h.errors} errors, got ${errs.length}: ${errs.map((d) => `L${d.line} ${d.id}`).join(', ')}`); continue; }
|
|
if (errs.length) { fail(file, errs.map((d) => `L${d.line} ${d.id}: ${d.message}`).join(' | ')); continue; }
|
|
if (h.expect.length || h.call) checkRun(file, runPseudo(st, { call: h.call ?? null, input: h.input, maxSteps: 200000 }), h);
|
|
} else if (file.endsWith('.tex')) {
|
|
const r = parseMatho(text);
|
|
const errs = r.diagnostics.filter((d) => d.severity === 'error');
|
|
if (h.errors !== undefined) { if (errs.length !== h.errors) fail(file, `expected ${h.errors} errors, got ${errs.length}: ${errs.map((d) => `L${d.line} ${d.id}`).join(', ')}`); continue; }
|
|
if (errs.length) { fail(file, errs.map((d) => `L${d.line} ${d.id}: ${d.message}`).join(' | ')); continue; }
|
|
const low = lowerMatho(r, 'pseudo');
|
|
if (!low) { fail(file, 'does not translate to pseudo'); continue; }
|
|
if (h.expect.length || h.call) {
|
|
try { checkRun(file, runMatho(r, { call: h.call ?? null, input: h.input, maxSteps: 200000 }), h); }
|
|
catch (e) { fail(file, `run failed: ${e.message}`); }
|
|
}
|
|
} else if (file.endsWith('.mojo')) {
|
|
const removed = removedSyntax(text);
|
|
if (removed.length && h.errors == null) { fail(file, removed.map((d) => `L${d.line} ${d.message}`).join(' | ')); continue; }
|
|
if (!mojoVersion) continue;
|
|
const r = spawnSync('mojo', ['run', file], { input: h.input.map((l) => l + '\n').join(''), encoding: 'utf8', timeout: 120000 });
|
|
if (h.errors != null) { if (r.status === 0) fail(file, 'was meant to fail to compile, and ran'); continue; }
|
|
if (r.status !== 0) { fail(file, `mojo run exited ${r.status ?? r.signal}: ${(r.stderr || '').trim().split('\n').slice(0, 4).join(' | ')}`); continue; }
|
|
if (h.expect.length) {
|
|
const got = r.stdout.replace(/\n$/, '').split('\n');
|
|
if (JSON.stringify(got) !== JSON.stringify(h.expect)) fail(file, `printed ${JSON.stringify(got)}, expected ${JSON.stringify(h.expect)}`);
|
|
}
|
|
} else if (file.endsWith('.lingo')) {
|
|
const r = readLingo(text);
|
|
const errs = r.diagnostics.filter((d) => d.severity === 'error');
|
|
if (h.questions.length) {
|
|
for (const q of h.questions) if (!r.diagnostics.some((d) => d.id === q)) fail(file, `the reader did not ask "${q}" (asked: ${r.diagnostics.map((d) => d.id).join(', ') || 'nothing'})`);
|
|
continue;
|
|
}
|
|
if (errs.length) { fail(file, errs.map((d) => `L${d.line} ${d.id}: ${d.message}`).join(' | ')); continue; }
|
|
const low = lowerLingo(r, 'pseudo');
|
|
if (!low) { fail(file, 'does not lower to pseudo'); continue; }
|
|
const st = studyOf(low.source);
|
|
const perrs = st.diagnostics.filter((d) => d.severity === 'error');
|
|
if (perrs.length) { fail(file, 'lowered pseudo has errors: ' + perrs.map((d) => `L${d.line} ${d.message}`).join(' | ')); continue; }
|
|
if (h.expect.length || h.call) {
|
|
try { checkRun(file, runLingo(r, { call: h.call ?? null, input: h.input, maxSteps: 200000 }), h); }
|
|
catch (e) { fail(file, `run failed: ${e.message}`); }
|
|
}
|
|
}
|
|
}
|
|
console.log(`check-pages: ${programs.length} program files, ${failures} problems`);
|
|
process.exit(failures ? 1 : 0);
|