Files
pplus-web/core/scripts/play.mjs
T
alexmandClaude 82e18f7966 Move the engine core into core/, a project of its own (pplus-core)
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
2026-10-05 05:43:58 +00:00

185 lines
9.3 KiB
JavaScript

#!/usr/bin/env node
/**
* The fast loop for a Mojo program in mojo/local/: write it, run one command,
* and have it run, be checked on the pinned compiler, be built into the app,
* and be tested.
*
* pixi run play demo # one pass over mojo/local/demo.mojo
* pixi run play-watch demo # again on every save (tests off unless --test)
* node scripts/play.mjs demo --no-verify # skip godbolt (offline, or a quick edit)
* node scripts/play.mjs demo --no-test # skip the tests
*
* One pass is:
* 1. run the file on your own compiler (`mojo`, or `pixi run mojo-run`), if you have one
* 2. verify ask godbolt (Mojo 1.1.0) about it: its verdict, output, and x86-64 listing [network]
* 3. status judge it from the goldens and rewrite src/mojo/generated/programs.ts [offline]
* 4. build tsc
* 5. listing turn godbolt's assembly into the x86-64 pane (scripts/mojo/listings.mjs), rebuild if it changed
* 6. test the whole test suite (npm test)
*
* A step that cannot run (no local compiler, godbolt unreachable) is reported as
* skipped and the pass goes on; a program that fails to compile locally, a
* build error, or a failing test stops it or fails the pass.
* Exercises that name the program in `mojoProgram` pick up the result; to make
* one, `pixi run new-exercise <id>`.
*/
import { spawnSync } from 'node:child_process';
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';
const ROOT = fileURLToPath(new URL('..', import.meta.url));
const LOCAL = path.join(ROOT, 'mojo/local');
const PY = process.env.PYTHON || 'python3';
const argv = process.argv.slice(2);
const flags = new Set(argv.filter((a) => a.startsWith('--')));
const names = argv.filter((a) => !a.startsWith('--')).map((a) => path.basename(a).replace(/\.mojo$/, ''));
const watch = flags.has('--watch');
const doVerify = !flags.has('--no-verify');
const doTest = !flags.has('--no-test') && !(watch && !flags.has('--test'));
function sh(cmd, args, { quiet = false } = {}) {
const r = spawnSync(cmd, args, { cwd: ROOT, stdio: quiet ? ['ignore', 'pipe', 'pipe'] : ['ignore', 'inherit', 'inherit'], encoding: 'utf8' });
return { ok: r.status === 0, missing: r.error?.code === 'ENOENT', status: r.status, out: (r.stdout || '') + (r.stderr || '') };
}
const available = (cmd) => sh(cmd, ['--version'], { quiet: true }).ok;
/** Exercises whose `mojoProgram` has no file in mojo/local/. */
function danglingPrograms() {
const dir = path.join(ROOT, 'src/exercises');
const out = [];
for (const f of fs.readdirSync(dir).filter((x) => x.endsWith('.ts') && !x.startsWith('_'))) {
const m = /mojoProgram:\s*['"]([^'"]+)['"]/.exec(fs.readFileSync(path.join(dir, f), 'utf8'));
if (m && !fs.existsSync(path.join(LOCAL, `${m[1]}.mojo`))) out.push({ exercise: f.replace(/\.ts$/, ''), program: m[1] });
}
return out;
}
/** Is there an exercise whose `mojoProgram` is this program? */
function exerciseNaming(program) {
const dir = path.join(ROOT, 'src/exercises');
return fs.readdirSync(dir).some((f) => f.endsWith('.ts') && new RegExp(`mojoProgram:\\s*['"]${program}['"]`).test(fs.readFileSync(path.join(dir, f), 'utf8')));
}
const listingsFile = path.join(ROOT, 'src/mojo/generated/listings.ts');
const read = (p) => (fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : '');
async function pass(name) {
const file = path.join(LOCAL, `${name}.mojo`);
const rel = `mojo/local/${name}.mojo`;
const report = [];
const step = (what, status, note = '') => { report.push({ what, status, note }); };
const heading = (s) => console.log(`\n▸ ${s}`);
if (!fs.existsSync(file)) {
console.error(`play: ${rel} does not exist. Programs in mojo/local/: ${fs.readdirSync(LOCAL).filter((f) => f.endsWith('.mojo')).map((f) => f.replace(/\.mojo$/, '')).join(', ')}`);
return false;
}
// 1. your own compiler
heading(`run ${rel} locally`);
const runner = available('mojo') ? ['mojo', ['run', rel]] : available('pixi') ? ['pixi', ['run', 'mojo-run', rel]] : null;
if (!runner) step('run locally', 'skipped', 'no `mojo` or `pixi` on the PATH; install pixi (https://pixi.sh) and the pinned compiler comes with `pixi install`');
else {
const r = sh(runner[0], runner[1]);
if (!r.ok) { step('run locally', 'FAILED', `exit ${r.status}; fix the program first, nothing downstream ran`); return summarize(name, report); }
step('run locally', 'ok', `${runner[0]} ${runner[1].join(' ')}`);
}
// a .mojo file with no exercise yet gets one (src/exercises/<name>.ts, registered in index.ts)
if (!fs.existsSync(path.join(ROOT, 'src/exercises', `${name}.ts`)) && !exerciseNaming(name)) {
heading(`no exercise uses ${rel} yet: creating src/exercises/${name}.ts`);
const r = sh('node', ['scripts/new-exercise.mjs', name]);
if (!r.ok) { step('create exercise', 'FAILED', 'scripts/new-exercise.mjs refused; see above'); return summarize(name, report); }
step('create exercise', 'ok', `src/exercises/${name}.ts`);
}
// verify and status both rewrite src/mojo/generated/programs.ts from mojo/local/. An exercise that names a
// program with no file there would then make the whole catalog throw at import (src/core/catalog.ts), so stop first.
const dangling = danglingPrograms();
if (dangling.length) {
step('exercises name real programs', 'FAILED', dangling.map((d) => `${d.exercise} names mojo/local/${d.program}.mojo, which does not exist`).join('; ') + '. Create the file, or remove `mojoProgram` from the exercise, then run this again. Nothing was regenerated.');
return summarize(name, report);
}
// 2. godbolt
if (!doVerify) step('verify on godbolt', 'skipped', '--no-verify');
else {
heading('verify on godbolt (Mojo 1.1.0)');
const r = sh(PY, ['scripts/mojo/corpus.py', 'verify', '--item', `local/${name}`]);
step('verify on godbolt', r.ok ? 'ok' : 'skipped', r.ok ? '' : 'godbolt did not answer (offline, blocked, or rate-limited); the verdict and listing below are from the last answer on file, if any');
}
// 3. judge offline, refresh programs.ts
heading('status (offline)');
const st = sh(PY, ['scripts/mojo/corpus.py', 'status']);
if (!st.ok) { step('status', 'FAILED', 'corpus.py status failed'); return summarize(name, report); }
step('status', 'ok');
// 4. build
heading('build');
if (!sh('npx', ['tsc', '-p', 'tsconfig.json']).ok) { step('build', 'FAILED', 'tsc reported errors'); return summarize(name, report); }
step('build', 'ok');
// 5. the x86-64 listing
heading('x86-64 listing');
const before = read(listingsFile);
const li = sh('node', ['scripts/mojo/listings.mjs', name]);
if (!li.ok) { step('x86-64 listing', 'FAILED', 'listings.mjs failed'); return summarize(name, report); }
if (read(listingsFile) !== before) {
if (!sh('npx', ['tsc', '-p', 'tsconfig.json']).ok) { step('x86-64 listing', 'FAILED', 'rebuild after the listing changed failed'); return summarize(name, report); }
step('x86-64 listing', 'ok', 'updated');
} else step('x86-64 listing', 'ok', 'unchanged (see above for whether one exists)');
// what the app now says about the program
try {
const mod = await import(pathToFileURL(path.join(ROOT, 'dist/mojo/generated/programs.js')).href + `?t=${Date.now()}`);
const p = mod.MOJO_PROGRAMS[name];
step('verdict in the app', p?.verified ? 'ok' : 'note', p ? `${p.verdict}: ${p.why}` : 'the program is not in programs.ts');
} catch (e) { step('verdict in the app', 'note', String(e.message || e)); }
// 6. tests
if (!doTest) step('tests', 'skipped', watch ? 'watch mode (add --test)' : '--no-test');
else {
heading('npm test');
const t = sh('npm', ['test']);
step('tests', t.ok ? 'ok' : 'FAILED', t.ok ? '' : 'see the failures above');
}
return summarize(name, report);
}
function summarize(name, report) {
console.log(`\n── ${name} ──`);
for (const r of report) console.log(` ${r.status.padEnd(7)} ${r.what}${r.note ? ` — ${r.note}` : ''}`);
return !report.some((r) => r.status === 'FAILED');
}
if (!names.length && !watch) {
console.error('usage: pixi run play <name> (or node scripts/play.mjs <name> [--watch] [--no-verify] [--no-test] [--test])\n <name> is a program in mojo/local/ (without .mojo). To make a new one: pixi run new-exercise <id>');
process.exit(2);
}
let failed = false;
for (const n of names) if (!(await pass(n))) failed = true;
if (watch) {
const only = new Set(names);
console.log(`\nwatching mojo/local/${only.size ? ` for ${[...only].join(', ')}` : ''} (Ctrl+C to stop)`);
const queue = new Set();
let busy = false, timer = null;
const drain = async () => {
if (busy) return;
busy = true;
while (queue.size) { const n = [...queue][0]; queue.delete(n); await pass(n); console.log(`\nwatching… (${n} done)`); }
busy = false;
};
fs.watch(LOCAL, (_event, f) => {
if (!f || !f.endsWith('.mojo')) return;
const n = f.replace(/\.mojo$/, '');
if (only.size && !only.has(n)) return;
queue.add(n);
clearTimeout(timer);
timer = setTimeout(drain, 500); // editors write a file in several events
});
} else process.exit(failed ? 1 : 0);