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
This commit is contained in:
alexmandClaude committed 2026-10-05 05:43:58 +00:00
1 parent f43bbfe0cf
commit 82e18f7966
1567 files changed
+3670 -981

No files matched your search

+182
View File
@@ -0,0 +1,182 @@
// Programming+'s Mojo interpreter, judged against the real compiler: for every program godbolt
// compiled and ran (mojo/golden), the interpreter either declines ("cannot run this yet") or
// prints exactly what godbolt's run printed and ends the same way. It never disagrees.
import test from 'node:test';
import assert from 'node:assert/strict';
import fs from 'node:fs';
import crypto from 'node:crypto';
import { parseModule } from '../dist/mojo/parse.js';
import { runMojo } from '../dist/mojo/interp.js';
const R = new URL('..', import.meta.url).pathname;
const read = (p) => JSON.parse(fs.readFileSync(R + p, 'utf8'));
const verdicts = new Map(read('mojo/golden/status.json').items.map((r) => [r.id, r]));
const golden = (key) => key && fs.existsSync(`${R}mojo/golden/${key}.json`) ? read(`mojo/golden/${key}.json`) : null;
const run = (src, input = []) => runMojo(parseModule(src), src, { input, maxSteps: 200000 });
const AGREE_AT_LEAST = 203; // raise as the interpreter learns more (3a: 171, 4a: 180, 4b: 182, 4c: 191, 7a: 201, 7b: 203)
test('the interpreter never disagrees with godbolt, and agrees on at least the ratchet', () => {
const programs = [];
for (const [dir, mf] of [['quest', 'quest'], ['manual', 'manual']]) for (const it of read(`mojo/corpus/${mf}/manifest.json`).items) programs.push([it.id, `mojo/corpus/${dir}/${it.file}`]);
for (const f of fs.readdirSync(R + 'mojo/probes')) programs.push([`probes/${f.replace('.mojo', '')}`, `mojo/probes/${f}`]);
for (const f of fs.readdirSync(R + 'mojo/local')) programs.push([`local/${f.replace('.mojo', '')}`, `mojo/local/${f}`]);
for (const f of fs.readdirSync(R + 'mojo/stress')) programs.push([`stress/${f.replace('.mojo', '')}`, `mojo/stress/${f}`]);
const disagree = []; let agree = 0;
for (const [id, file] of programs) {
const g = golden(verdicts.get(id)?.key);
// only godbolt runs to compare with; and its run mode did not deliver stdin (probes/input-lines)
if (!g || !g.result.compiled || !g.result.executed || g.mode !== 'run' || g.stdin) continue;
const src = fs.readFileSync(R + file, 'utf8');
if (g.sourceSha256 && g.sourceSha256 !== crypto.createHash('sha256').update(src).digest('hex')) continue; // an edited file waits for the next verify
const r = runMojo(parseModule(src), src, { maxSteps: 200000, record: false });
if (r.refused || r.limited) continue;
const norm = (s) => s.replace(/\r\n/g, '\n').replace(/\n+$/, '');
if (norm(r.stdout) === norm(g.result.stdout) && r.exitCode === g.result.exitCode) agree++;
else disagree.push(`${id}: printed ${JSON.stringify(norm(r.stdout).slice(0, 120))} and exited ${r.exitCode}; godbolt printed ${JSON.stringify(norm(g.result.stdout).slice(0, 120))} and exited ${g.result.exitCode}`);
}
assert.deepEqual(disagree, []);
assert.ok(agree >= AGREE_AT_LEAST, `${agree} programs agree, fewer than ${AGREE_AT_LEAST}`);
});
test('the trace has the shape the stepping views read', () => {
const r = run('def main():\n var total = 0\n for i in range(3):\n total += i\n print(total)\n');
const t = r.trace;
assert.equal(r.stdout, '3\n');
assert.equal(t.lang, 'mojo');
assert.equal(t.states.length, t.steps.length + 1, 'a state before the first step, and one after each');
const step = t.steps.find((s) => s.text.startsWith('total += i'));
assert.equal(step.line, 4);
assert.deepEqual(step.writes.map((w) => w.name), ['total']);
const last = t.states.at(-1).frames.find((f) => f.name === 'main');
assert.equal(last.vars.total.text, '3');
assert.equal(last.vars.total.type, 'Int');
assert.equal(t.hits.get(4), 3, 'the loop body ran three times');
const loopState = t.states[t.steps.findIndex((s) => s.kind === 'loop') + 1];
assert.deepEqual(loopState.loops.map((l) => [l.kind, l.line, l.pass]), [['For', 3, 1]]);
});
test('conventions: mut aliases the caller, var copies, ^ moves and empties the source', () => {
assert.equal(run('def bump(mut n: Int):\n n += 1\n\n\ndef main():\n var x = 1\n bump(x)\n print(x)\n').stdout, '2\n');
assert.equal(run('def grow(var xs: List[Int]) -> Int:\n xs.append(9)\n return len(xs)\n\n\ndef main():\n var a: List[Int] = [1]\n print(grow(a.copy()), len(a))\n').stdout, '2 1\n', 'the copy grew, not a');
const moved = run('def main():\n var a: List[Int] = [1, 2]\n var b = a^\n print(len(b))\n');
assert.equal(moved.stdout, '2\n');
const after = moved.trace.states.at(-1).frames[0].vars;
assert.equal(after.a.text, '(moved out)');
});
test('it ends the way the compiled program does', () => {
const oob = run('def main():\n var l: List[Int] = [1, 2, 3]\n var i = 3\n print(l[i])\n');
assert.equal(oob.stdout, 'At: /app/example.mojo:4:12: Assert Error: index 3 is out of bounds, valid range is 0 to 2\n');
assert.equal(oob.exitCode, 132);
const raised = run('def main() raises:\n print("before")\n raise Error("boom")\n');
assert.equal(raised.stdout, 'before\n');
assert.equal(raised.exitCode, 1);
assert.match(raised.stderr, /Unhandled exception caught during execution: boom/);
const eof = run('def main() raises:\n var s = input()\n print(s)\n');
assert.match(eof.stderr, /Unhandled exception caught during execution: EOF/, 'input() at the end of input raises EOF');
assert.equal(run('def main() raises:\n var s = input()\n print(atol(s) + 1)\n', ['41']).stdout, '42\n');
const loop = run('def main():\n var x = 0\n while True:\n x += 1\n');
assert.equal(loop.limited, true, 'an endless loop is inconclusive, not an exit');
});
const LOUD = 'struct L(Copyable, Movable):\n var n: String\n\n def __init__(out self, n: String):\n self.n = n\n print("init", n)\n\n def __init__(out self, *, copy: Self):\n self.n = copy.n + "2"\n print("copy", copy.n)\n\n def __init__(out self, *, deinit move: Self):\n self.n = move.n^\n print("move", self.n)\n\n def __deinit__(deinit self):\n print("bye", self.n)\n\n\n';
test('Stage 4: a value is destroyed at its last use, and the trace shows it', () => {
const r = run(LOUD + 'def main():\n var a = L("a")\n var b = L("b")\n print("using", a.n)\n print("end")\n');
// b is never read: it dies as its declaration ends; a dies when the print that borrows a.n returns
assert.equal(r.stdout, 'init a\ninit b\nbye b\nusing a\nbye a\nend\n');
const destroyed = r.trace.steps.filter((s) => s.kind === 'destroy').map((s) => s.text);
assert.deepEqual(destroyed, ['b is destroyed', 'a is destroyed']);
const last = r.trace.states.at(-1).frames.find((f) => f.name === 'main').vars;
assert.equal(last.a.text, '(destroyed)');
});
test('Stage 4: moves and copies run their constructors where the compiler runs them', () => {
const r = run(LOUD + 'def take(var t: L):\n print("took", t.n)\n\n\ndef main():\n var a = L("a")\n var c = a.copy()\n take(c^)\n var d = a^\n print("kept", d.n)\n');
// into a var argument, ^ moves no bytes; into a new variable the move constructor runs
assert.equal(r.stdout, 'init a\ncopy a\ntook a2\nbye a2\nmove a\nkept a\nbye a\n');
});
test('Stage 4c: a value dies where the path ahead cannot read it', () => {
// a branch that does not read it: it dies as that branch begins (probes/life-branch-one-side)
const r = run(LOUD + 'def run(flag: Bool):\n var a = L("a")\n if flag:\n print("then", a.n)\n else:\n print("else")\n print("after")\n\n\ndef main():\n run(False)\n');
assert.equal(r.stdout, 'init a\nbye a\nelse\nafter\n');
// read in every pass: it dies when the loop ends (probes/life-loop-outer-read-inside)
assert.equal(run(LOUD + 'def main():\n var a = L("a")\n for i in range(2):\n print(i, a.n)\n print("after")\n').stdout, 'init a\n0 a\n1 a\nbye a\nafter\n');
});
test('what it does not model, it declines rather than guesses', () => {
const tryBlock = run(LOUD + 'def main():\n var a = L("a")\n try:\n print(a.n)\n except e:\n print(e)\n');
assert.match(tryBlock.refused, /does not follow yet/, 'a try\'s paths are not modelled');
assert.match(tryBlock.trace.error.message, /cannot run this yet/);
assert.ok(run('from std.python import Python\n\n\ndef main() raises:\n var np = Python.import_module("numpy")\n print(np)\n').refused, 'Python interop is declined');
});
test('Stage 4: the trace records each value\'s lifecycle for the Lifetimes view', () => {
const r = run(LOUD + 'def main():\n var a = L("x")\n var b = a.copy()\n var c = a^\n print(b.n, c.n)\n');
const events = r.trace.steps.flatMap((s) => (s.life ?? []).map((e) => `${e.kind} #${e.id}${e.from ? ` from #${e.from}` : ''}${e.name ? ` as ${e.name}` : ''}`));
// a move makes a new value (#3) from the old one (#1), which ends there; c and b die after the print, newest first
assert.deepEqual(events, ['made #1', 'named #1 as a', 'copied #2 from #1', 'named #2 as b', 'moved #3 from #1', 'named #3 as c', 'destroyed #3', 'destroyed #2']);
});
test('Stage 5: a Mojo function in the shapes the flowchart and data flow read', async () => {
const { mojoRoutine, mojoFunctions } = await import('../dist/mojo/flowir.js');
const src = 'def bump(mut n: Int, by: Int):\n n += by\n\n\ndef main():\n var x = 1\n var xs: List[Int] = [1]\n if x > 0:\n bump(x, 2)\n elif x < 0:\n print("neg")\n else:\n pass\n for v in xs:\n print(v)\n xs.append(x)\n';
const mod = parseModule(src);
assert.deepEqual(mojoFunctions(mod), ['bump', 'main']);
const r = mojoRoutine(mod, 'main');
assert.deepEqual(r.body.map((s) => s.kind), ['Assign', 'Assign', 'If', 'ForEach', 'BuiltinCall']);
const ifs = r.body[2];
assert.equal(ifs.branches.length, 2, 'an elif is a second branch of one If');
assert.deepEqual(ifs.branches[0].body.map((s) => s.kind), ['MojoCall']);
assert.deepEqual(ifs.branches[0].body[0].outs.map((o) => o.name), ['x'], 'the argument to a mut parameter changes');
assert.equal(r.body[3].var, 'v');
assert.deepEqual(r.symbols, [{ name: 'xs', type: 'List[Int]' }]);
const loop = run('def main():\n for i in range(2):\n print(i)\n');
assert.equal(loop.trace.steps.filter((s) => s.text === 'no more items').length, 1, 'the loop running out is a step, as a while loop\'s final test is');
});
test('Stage 5: generated inputs find what stops a compiled Mojo program, and nothing else', async () => {
const { mojoProperties } = await import('../dist/mojo/properties.js');
const src = 'def last(xs: List[Int]) -> Int:\n return xs[len(xs) - 1]\n\n\ndef ratio(a: Int, b: Int) -> Int:\n return a // b\n\n\ndef parse(s: String) raises -> Int:\n return atol(s)\n\n\ndef spin(n: Int) -> Int:\n var i = 0\n while i != n:\n i += 2\n return i\n\n\ndef grow(mut xs: List[Int]):\n xs.append(1)\n\n\ndef main():\n pass\n';
const by = Object.fromEntries(mojoProperties(parseModule(src), src).map((r) => [r.name, r]));
assert.deepEqual(by.last.failures.map((f) => [f.kind, f.call]), [['bounds', 'last([])']], 'the smallest input that aborts');
assert.match(by.last.failures[0].message, /index -1 is out of bounds/);
assert.deepEqual(by.ratio.failures, [], 'an Int division by zero is 0 in Mojo (probes/int-div-zero), not a failure');
assert.deepEqual(by.parse.failures.map((f) => [f.kind, f.call]), [['raises-declared', 'parse("")']], 'one shape of error, its smallest input; it says raises');
assert.deepEqual(by.spin.failures.map((f) => [f.kind, f.call]), [['limit', 'spin(1)']]);
assert.match(by.grow.problem, /passed as mut/);
assert.ok(by.last.checked >= 100);
});
test('Stage 7a: overloads, with, a failing assert, exact literals, block scope, SIMD', () => {
// an overload picked by count, then by type
assert.equal(run('def area(s: Int) -> Int:\n return s * s\n\n\ndef area(w: Int, h: Int) -> Int:\n return w * h\n\n\ndef show(x: Int):\n print("int", x)\n\n\ndef show(x: String):\n print("str", x)\n\n\ndef main():\n print(area(3), area(2, 5))\n show(1)\n show("a")\n').stdout, '9 10\nint 1\nstr a\n');
// the student's context manager: __enter__, the body, __exit__; an error goes to __exit__(err), True swallows it
const cm = '@fieldwise_init\nstruct G(Copyable, Movable):\n var name: String\n\n def __enter__(self) -> Self:\n print("enter", self.name)\n return self.copy()\n\n def __exit__(self):\n print("exit", self.name)\n\n def __exit__(self, err: Error) -> Bool:\n print("exit with", err)\n return True\n\n\n';
assert.equal(run(cm + 'def main() raises:\n with G("a"):\n print("body")\n with G("b"):\n raise Error("boom")\n print("after")\n').stdout, 'enter a\nbody\nexit a\nenter b\nexit with boom\nafter\n');
// a failing assert_equal raises the compiler's AssertionError, catchable like any other (quest/MQ-950/starter)
const failed = run('from std.testing import assert_equal\n\n\ndef main() raises:\n assert_equal(150, 200)\n');
assert.match(failed.stderr, /At \/app\/example\.mojo:5:17: AssertionError: `left == right` comparison failed:\n left: 150\n right: 200/);
// literal-only arithmetic is exact (manual: 3.0 * (4.0 / 3.0 - 1.0) is 1.0)
assert.equal(run('def main():\n var three = 3.0\n print(3.0 * (4.0 / 3.0 - 1.0), three * (4.0 / three - 1.0))\n').stdout, '1.0 0.9999999999999998\n');
// var is block-scoped: an inner var shadows, and the outer one is untouched
assert.equal(run('def main():\n var num = 1\n if num == 1:\n var num = 2\n print(num)\n print(num)\n').stdout, '2\n1\n');
// SIMD (probes/simd-basics), a scalar applying to every lane
assert.equal(run('def main():\n var v = SIMD[DType.int32, 4](1, 5, 1, 9)\n print(v + 1, v.reduce_max())\n').stdout, '[2, 6, 2, 10] 9\n');
});
test('Stage 7b: closures capture as their capture lists say (the manual\'s closures chapter)', () => {
// imm holds a reference: a later change is seen (test_imm_sees_live_updates)
assert.equal(run('def main():\n var limit = 10\n\n def check(x: Int) {imm limit} -> Bool:\n return x < limit\n\n print(check(5))\n limit = 3\n print(check(5))\n').stdout, 'True\nFalse\n');
// var is a snapshot taken when the closure is made (test_var_snapshot)
assert.equal(run('def main():\n var v = 42\n\n def frozen() {var v} -> Int:\n return v\n\n v = 999\n print(frozen(), v)\n').stdout, '42 999\n');
// a default alone, and a default with an override (test_default_convention)
assert.equal(run('def main():\n var a = 1\n var b = 2\n var z = "snap"\n\n def mixed() {mut, var z} -> String:\n a += 10\n b += 20\n return String(a) + " " + String(b) + " " + z\n\n print(mixed())\n z = "changed"\n print(mixed())\n').stdout, '11 22 snap\n21 42 snap\n');
// a lambda captures as imm: a later call sees new values (manual functions/lambda)
assert.equal(run('def main():\n var x = 3\n var f = lambda (k: Int) -> Int: k * x\n print(f(2))\n x = 5\n print(f(2))\n').stdout, '6\n10\n');
// a named function passed as a value, called through the parameter
assert.equal(run('def twice(n: Int) -> Int:\n return n * 2\n\n\ndef apply(f: def(Int) -> Int, n: Int) -> Int:\n return f(n)\n\n\ndef main():\n print(apply(twice, 4))\n').stdout, '8\n');
// without a capture list, using an outer variable: the default is not documented, so declined
assert.match(run('def main():\n var a = 1\n\n def f() -> Int:\n return a\n\n print(f())\n').refused, /without a capture list/);
});