#!/usr/bin/env node // SPDX-FileCopyrightText: 2026 Scientific Computing Studio, LLC // SPDX-License-Identifier: Apache-2.0 /** * Hold core to the pinned Mojo compiler on this machine. * * Godbolt's stored answers cover the programs someone wrote down. This covers every Mojo program core can * produce or holds, built and run by the local `mojo` (pixi provides the pinned one), with no network: * * own library/mojo/probes, local and stress, as written * generated the Mojo the translator writes for every exercise, every pseudo regression program, and every * library routine on its cases * reference every Mojo reference implementation of the library, in the harness library-check runs it as * * For each program it asks four questions, and prints every "no": * * checker does the checker stay silent on a program the compiler accepts? (AGENTS.md, rule 4) * interpreter does the interpreter print what the built program prints, and end the same way, or decline? * translator does the compiler accept generated Mojo, and does it print what the pseudo prints? * godbolt does this compiler agree with godbolt's stored answer for the same text? (a different * answer means the two compilers, or the two machines, differ: worth knowing, never a bug of ours) * * One kind of difference is reported and does not fail the pass: generated Mojo whose numbers differ from the * pseudo's only in their last digits (at most ROUNDING apart, relatively). The compiled program's std.math is * its own (hypot differs in the last digit, exp and ** are good to about 3e-13 in Mojo 1.2.0), so those digits * are the compiler's to decide; docs/trust.md says so. Its arithmetic is not: every program is built with the * pin's arguments (library/mojo/pin.json build.args), contraction off among them, so a * b + c is rounded twice, * as the interpreter and the pseudo round it. * * node scripts/mojo/local.mjs [--only own|generated|reference] [--item ] [--jobs N] [--json] * [--no-cache] [--keep DIR] [--list] * * Exit status: 0 when every answer is yes (or a listed, explained exception), 1 otherwise, 2 when the local * compiler is missing or is not the pinned version. Needs a build (dist/). Answers are cached in * .tools/mojo-local/ by compiler version, arguments, input and source, so a second pass is quick; --no-cache builds * everything again and keeps none of it. * * A built program that traps (an index out of range ends in an illegal instruction) is run with its core-dump * limit set to 1, the value the kernel reads as "do not pipe this dump anywhere", so a deliberate crash does * not reach systemd-coredump or the desktop. */ import fs from 'node:fs'; import os from 'node:os'; import path from 'node:path'; import crypto from 'node:crypto'; import { spawn, spawnSync } from 'node:child_process'; import { fileURLToPath, pathToFileURL } from 'node:url'; const ROOT = fileURLToPath(new URL('../..', import.meta.url)); const dist = (p) => pathToFileURL(path.join(ROOT, 'dist', p)).href; const argv = process.argv.slice(2); const opt = (name, dflt = null) => { const i = argv.indexOf(`--${name}`); return i >= 0 ? argv[i + 1] : dflt; }; const flag = (name) => argv.includes(`--${name}`); const sha256 = (s) => crypto.createHash('sha256').update(s).digest('hex'); const readJson = (p) => JSON.parse(fs.readFileSync(p, 'utf8')); const norm = (s) => String(s ?? '').replace(/\r\n/g, '\n').replace(/\n+$/, ''); if (!fs.existsSync(path.join(ROOT, 'dist', 'mojo', 'check.js'))) { console.error('mojo-local: dist/ is missing; run `pixi run build` first'); process.exit(2); } const { MOJO_VERSION, GODBOLT_COMPILER } = await import(dist('mojo/generated/pin.js')); const { checkMojo } = await import(dist('mojo/check.js')); const { runMojo } = await import(dist('mojo/interp.js')); const { studyOf, runPseudo } = await import(dist('services/pseudo.js')); const { pseudoToMojo } = await import(dist('sync/pseudo-to-mojo.js')); const { formatAsMojo, sameOutput, outputDistance } = await import(dist('sync/compare.js')); const { EXERCISES } = await import(dist('exercises/index.js')); const { libraryModules } = await import(dist('library/registry.js')); const { readHeader } = await import(pathToFileURL(path.join(ROOT, 'scripts', 'mojo', 'listings.mjs')).href); // every program is built with the pin's arguments, then its own: on an x86-64 machine, the arguments godbolt is given const { mojoBuildArgs } = await import(dist('services/godbolt.js')); const HOST = { x86_64: process.arch === 'x64' }; /** * Differences that are right, each with its reason. A listed program that stops differing fails the pass, so * the list can only shrink. Keys are ` `. */ /** The largest relative difference between two printed numbers that still counts as rounding, not as another answer. */ export const ROUNDING = 1e-9; export const EXPECTED = { 'translator generated/18-repeat-input.pseudo': 'Mojo\'s input() opens its own buffered reader on every call, so on piped input the first call takes every line and the second raises EOF; on a terminal each call reads one line, as the notation does', 'interpreter generated/18-repeat-input.pseudo': 'the interpreter reads one line per input(), as a terminal gives them; the built program was given a pipe (see the line above)', 'interpreter probes/struct-field-loop-copy': 'a bug of Mojo 1.2.0, not of the interpreter: the built program frees a struct\'s List field twice and crashes on a later pass; the interpreter runs all three', 'interpreter probes/input-lines': 'the interpreter reads one line per input(), as a terminal gives them; on piped input the second input() raises EOF', 'translator generated/33-stops-div.pseudo': 'dividing by zero stops the notation; a Float64 division in Mojo gives inf or nan and goes on', 'translator generated/44-parallel-race.pseudo': 'the notation detects a data race in PARALLEL FOR; Mojo runs the passes in order', 'translator generated/45-parallel-neighbor-race.pseudo': 'the notation detects a data race in PARALLEL FOR; Mojo runs the passes in order', 'translator generated/35-stops-unset.pseudo': 'the pseudo reads a variable that was never given a value; the compiler rejects the Mojo, as the checker does', 'translator generated/36-stops-counter.pseudo': 'the pseudo reads a FOR counter after its loop; the compiler rejects the Mojo, as the checker does', // the one program built with contraction on, as its header asks (# args: --fp-mode contract=fast): the built // program fuses a multiply and a subtraction into one rounding; the interpreter rounds twice, as a program built // with the pin's arguments does (probes/float-contract-runtime-off) 'interpreter probes/float-contract-runtime': 'built with contraction on, as its own # args: ask, the program computes x * x - x from stdin with one rounding (a fused multiply-subtract); the interpreter rounds twice, as every program built with the pin\'s arguments does', }; /* ------------------------------------------------------------------ */ /* The programs */ /* ------------------------------------------------------------------ */ function ownPrograms() { const out = []; for (const dir of ['probes', 'local', 'stress']) { for (const f of fs.readdirSync(path.join(ROOT, 'library', 'mojo', dir)).filter((x) => x.endsWith('.mojo')).sort()) { const source = fs.readFileSync(path.join(ROOT, 'library', 'mojo', dir, f), 'utf8'); const h = readHeader(source); const stdin = h.stdin ? h.stdin.replace(/\\n/g, '\n').replace(/\\t/g, '\t') : ''; out.push({ id: `${dir}/${f.replace(/\.mojo$/, '')}`, kind: 'own', source, stdin, args: mojoBuildArgs(h.args ?? '', HOST), godboltArgs: mojoBuildArgs(h.args ?? ''), mode: h.mode ?? 'run' }); } } return out; } function generatedPrograms() { const out = []; const add = (id, pseudo, call, input) => { const st = studyOf(pseudo); if (!st.ok) return; const tr = runPseudo(st, { call, input, maxSteps: 2000000 }); const mj = pseudoToMojo(pseudo, { call }); if ('unsupported' in mj) return; const gaps = mj.notes.filter((n) => n.id === 'translate-gap'); const want = call && tr.raw.result !== undefined ? [...tr.raw.output, formatAsMojo(tr.raw.result)].join('\n') : tr.raw.output.join('\n'); out.push({ id: `generated/${id}`, kind: 'generated', source: mj.source, stdin: input.length ? `${input.join('\n')}\n` : '', args: mojoBuildArgs('', HOST), mode: 'run', pseudo: { stops: tr.error ? `${tr.error.kind}: ${tr.error.message}` : null, want }, gaps: gaps.map((g) => g.message) }); }; for (const e of EXERCISES) if (e.sources.pseudo) add(`ex:${e.id}`, e.sources.pseudo, e.call ?? null, []); const dir = path.join(ROOT, 'library', 'pseudo', 'programs'); for (const f of fs.readdirSync(dir).filter((x) => x.endsWith('.pseudo')).sort()) { const src = fs.readFileSync(path.join(dir, f), 'utf8'); add(f, src, null, [...src.matchAll(/^\/\/ INPUT: (.*)$/gm)].map((m) => m[1])); } for (const m of libraryModules()) for (const r of m.routines) { if (!r.cases.length) continue; add(`lib:${r.id}`, `USE ${r.module}.${r.name}\n${r.cases.map((c) => `OUTPUT ${c.call}`).join('\n')}\n`, null, []); } return out; } function referencePrograms() { const p = spawnSync(process.execPath, [path.join(ROOT, 'scripts', 'library.mjs'), 'mojo-sources'], { encoding: 'utf8', maxBuffer: 1 << 26 }); if (p.status !== 0) throw new Error(`scripts/library.mjs mojo-sources failed: ${p.stderr}`); const wants = new Map(); for (const m of libraryModules()) for (const r of m.routines) wants.set(r.id, r); return JSON.parse(p.stdout).map((x) => { const [rid, lvl] = x.id.split(' '); const r = wants.get(rid); const ref = r?.references.find((y) => `${y.lang}/${y.level}` === lvl); // the cases arrive on stdin, as library-check and godbolt give them: no call has literal arguments the compiler could fold return { id: `reference/${rid}/${lvl.replace('mojo/', '')}`, kind: 'reference', source: x.source, stdin: x.stdin, args: mojoBuildArgs('', HOST), mode: 'run', cases: r?.cases ?? [], rel: ref?.rel ?? 0, abs: ref?.abs ?? 0 }; }); } /* ------------------------------------------------------------------ */ /* The local compiler */ /* ------------------------------------------------------------------ */ function compilerVersion() { const p = spawnSync('mojo', ['--version'], { encoding: 'utf8' }); if (p.status !== 0) return null; return (/Mojo\s+(\S+)/.exec(p.stdout) || [])[1] ?? null; } const exec = (cmd, args, { cwd, input = '', timeout = 60000 } = {}) => new Promise((resolve) => { const c = spawn(cmd, args, { cwd, stdio: ['pipe', 'pipe', 'pipe'] }); let stdout = ''; let stderr = ''; let timedOut = false; const t = setTimeout(() => { timedOut = true; c.kill('SIGKILL'); }, timeout); c.stdout.on('data', (d) => { if (stdout.length < 1 << 22) stdout += d; }); c.stderr.on('data', (d) => { if (stderr.length < 1 << 22) stderr += d; }); c.on('error', (e) => { clearTimeout(t); resolve({ status: null, signal: null, stdout, stderr: String(e), timedOut }); }); c.on('close', (status, signal) => { clearTimeout(t); resolve({ status, signal, stdout, stderr, timedOut }); }); c.stdin.on('error', () => { }); c.stdin.end(input); }); const SIGNALS = os.constants.signals; const HAVE_PRLIMIT = spawnSync('prlimit', ['--version'], { encoding: 'utf8' }).status === 0; /** * `mojo build` compiles a program and then has the C compiler it finds on the PATH link it. When that step fails (no * C compiler, or one that links against a C library older than Mojo's runtime needs) the compiler never said * anything about the program: the answer is the machine's, so it is not kept in the cache, not held against the * checker or godbolt, and reported as what it is. */ const NOT_LINKED = /unable to find suitable c compiler|failed to link executable/; /** Build one program and run it: { compiled, buildStderr, executed, exitCode, stdout, stderr, timedOut }, in godbolt's shape. */ async function buildAndRun(p, workdir) { const dir = fs.mkdtempSync(path.join(workdir, 'p-')); // Mojo keeps compiled objects in a cache of its own, and a trap's message carries the path the source had when it was // first compiled, by whoever compiled it: any path to an example.mojo is read as godbolt's /app/example.mojo const app = (s) => s.split(`${dir}/`).join('/app/').replace(/(?:\/[^\s:"']+)?\/example\.mojo/g, '/app/example.mojo'); fs.writeFileSync(path.join(dir, 'example.mojo'), p.source); const extra = p.args.split(/\s+/).filter(Boolean); const b = await exec('mojo', ['build', ...extra, 'example.mojo', '-o', 'example'], { cwd: dir, timeout: 180000 }); if (b.status !== 0 || !fs.existsSync(path.join(dir, 'example'))) { const buildStderr = app(b.stderr || b.stdout); return { compiled: false, buildStderr, executed: false, exitCode: null, stdout: '', stderr: '', timedOut: b.timedOut, ...(NOT_LINKED.test(buildStderr) ? { notLinked: true } : {}) }; } // a trap must not become a core dump on someone's desktop: limit 1 tells the kernel not to pipe it const r = HAVE_PRLIMIT ? await exec('prlimit', ['--core=1:1', './example'], { cwd: dir, input: p.stdin, timeout: 30000 }) : await exec('./example', [], { cwd: dir, input: p.stdin, timeout: 30000 }); const exitCode = r.timedOut ? null : r.status ?? (r.signal ? 128 + (SIGNALS[r.signal] ?? 0) : null); return { compiled: true, buildStderr: app(b.stderr), executed: true, exitCode, stdout: app(r.stdout), stderr: app(r.stderr), timedOut: r.timedOut }; } /* ------------------------------------------------------------------ */ /* The questions */ /* ------------------------------------------------------------------ */ const goldenFor = (() => { let verdicts = null; return (id) => { const dir = path.join(ROOT, 'library', 'mojo', 'golden'); if (!verdicts) { try { verdicts = new Map(readJson(path.join(dir, 'status.json')).items.map((r) => [r.id, r])); } catch { verdicts = new Map(); } } const key = verdicts.get(id)?.key; return key && fs.existsSync(path.join(dir, `${key}.json`)) ? readJson(path.join(dir, `${key}.json`)) : null; }; })(); const firstError = (stderr) => (stderr.split('\n').find((l) => /error:/.test(l)) ?? stderr.split('\n')[0] ?? '').trim().slice(0, 200); /** Does a printed value agree with the pseudo's result, within a reference's stated tolerance? */ function agreesWithin(printed, want, rel, abs) { const a = Number(String(printed).trim().replace(/^(-?)inf$/i, '$1Infinity')); const b = Number(String(want).trim().replace(/^(-?)inf$/i, '$1Infinity')); if (Number.isNaN(a) || Number.isNaN(b)) return sameOutput(String(printed), String(want)); return a === b || Math.abs(a - b) <= Math.max(rel * Math.max(Math.abs(a), Math.abs(b)), abs); } function judge(p, r) { const found = []; const say = (question, detail) => found.push({ question, id: p.id, detail }); const checked = checkMojo(p.source); const errors = checked.diagnostics.filter((d) => d.severity === 'error'); // checker: never an error on a program the compiler accepts if (r.compiled && errors.length) say('checker', `the compiler accepts it, and the checker reports: ${errors.map((d) => `L${d.line} ${d.message}`).join(' | ').slice(0, 300)}`); // interpreter: what the built program prints and how it ends, or it declines if (r.compiled && r.executed && !r.timedOut && !errors.length) { const run = runMojo(checked.module, p.source, { input: p.stdin ? p.stdin.replace(/\n$/, '').split('\n') : [], maxSteps: 400000, record: false }); if (!run.refused && !run.limited && (norm(run.stdout) !== norm(r.stdout) || run.exitCode !== r.exitCode)) { say('interpreter', `printed ${JSON.stringify(norm(run.stdout).slice(0, 160))} and exited ${run.exitCode}; the compiler's program printed ${JSON.stringify(norm(r.stdout).slice(0, 160))} and exited ${r.exitCode}`); } p.interp = run.refused ? 'declined' : run.limited ? 'limited' : 'ran'; } // translator: generated Mojo compiles, and prints what the pseudo prints if (p.kind === 'generated' && !p.gaps.length) { if (!r.compiled) say('translator', `the compiler rejects the generated Mojo: ${firstError(r.buildStderr)}`); else if (p.pseudo.stops) { if (r.exitCode === 0) say('translator', `the pseudo stops (${p.pseudo.stops}); the Mojo ran to the end and printed ${JSON.stringify(norm(r.stdout).slice(0, 120))}`); } else if (r.exitCode !== 0) say('translator', `the Mojo stopped (exit ${r.exitCode}${r.timedOut ? ', timed out' : ''}): ${norm(r.stdout + r.stderr).split('\n').pop().slice(0, 160)}; the pseudo ran to the end`); else { const far = outputDistance(p.pseudo.want, r.stdout); if (far > ROUNDING) say('translator', `the pseudo printed ${JSON.stringify(p.pseudo.want.slice(0, 160))}; the Mojo printed ${JSON.stringify(norm(r.stdout).slice(0, 160))}`); else if (far > 0) say('rounding', `the last digits differ, by at most ${far.toExponential(1)} of the value`); } } // a library reference: the pseudo's recorded result on every case, within its tolerance if (p.kind === 'reference') { if (!r.compiled) say('translator', `the compiler rejects the reference: ${firstError(r.buildStderr)}`); else if (r.exitCode !== 0) say('translator', `the reference stopped (exit ${r.exitCode})`); else { const got = norm(r.stdout).split('\n'); if (got.length !== p.cases.length) say('translator', `printed ${got.length} line(s) for ${p.cases.length} case(s)`); else p.cases.forEach((c, i) => { if (c.result !== undefined && !agreesWithin(got[i], c.result, p.rel, p.abs)) say('translator', `${c.call} printed ${got[i]}; the pseudo gives ${c.result}`); }); } } // godbolt: the stored answer for the same text, arguments and input, when there is one (godbolt gives the program // its stdin as a pipe, as this pass does: probes/input-pipe-first-line, godbolt-stdin) if (p.kind === 'own') { const g = goldenFor(p.id); if (g && g.compiler === GODBOLT_COMPILER && g.sourceSha256 === sha256(p.source) && (g.args ?? '') === p.args && p.args === p.godboltArgs && (g.stdin ?? '') === p.stdin) { if (g.result.compiled !== r.compiled) say('godbolt', `godbolt ${g.result.compiled ? 'compiled' : 'rejected'} it; this compiler ${r.compiled ? 'compiled' : 'rejected'} it: ${firstError(r.buildStderr)}`); else if (g.result.executed && r.executed && (norm(g.result.stdout) !== norm(r.stdout) || g.result.exitCode !== r.exitCode)) { say('godbolt', `godbolt printed ${JSON.stringify(norm(g.result.stdout).slice(0, 160))} and exited ${g.result.exitCode}; here it printed ${JSON.stringify(norm(r.stdout).slice(0, 160))} and exited ${r.exitCode}`); } p.godbolt = 'compared'; } } return found; } /* ------------------------------------------------------------------ */ /* Run */ /* ------------------------------------------------------------------ */ const only = opt('only'); const item = opt('item'); let programs = [ ...(!only || only === 'own' ? ownPrograms() : []), ...(!only || only === 'generated' ? generatedPrograms() : []), ...(!only || only === 'reference' ? referencePrograms() : []), ]; if (item) programs = programs.filter((p) => p.id.includes(item)); if (flag('list')) { for (const p of programs) console.log(p.id); process.exit(0); } const version = compilerVersion(); if (!version) { console.error('mojo-local: no `mojo` on the PATH; run this as `pixi run mojo-local` (pixi brings the pinned compiler)'); process.exit(2); } if (version !== MOJO_VERSION) { console.error(`mojo-local: the local compiler is Mojo ${version}, and the pin is ${MOJO_VERSION}; an answer from another version says nothing about the pin`); process.exit(2); } const cacheDir = path.join(ROOT, '.tools', 'mojo-local'); fs.mkdirSync(cacheDir, { recursive: true }); const keep = opt('keep'); const workdir = keep ? (fs.mkdirSync(keep, { recursive: true }), path.resolve(keep)) : fs.mkdtempSync(path.join(os.tmpdir(), 'pplus-mojo-local-')); const jobs = Math.max(1, Number(opt('jobs', '2')) || 2); const useCache = !flag('no-cache'); const findings = []; const counts = { programs: programs.length, compiled: 0, rejected: 0, notLinked: 0, cached: 0, interpreterRan: 0, interpreterDeclined: 0, godboltCompared: 0 }; let next = 0; async function worker() { while (next < programs.length) { const p = programs[next++]; const key = sha256(JSON.stringify([version, p.args, p.stdin, p.source])); const file = path.join(cacheDir, `${key}.json`); let r = useCache && fs.existsSync(file) ? readJson(file) : null; if (r) { counts.cached++; for (const k of ['stdout', 'stderr', 'buildStderr']) r[k] = String(r[k] ?? '').replace(/(?:\/[^\s:"']+)?\/example\.mojo/g, '/app/example.mojo'); } else { r = await buildAndRun(p, workdir); if (useCache && !r.timedOut && !r.notLinked) fs.writeFileSync(file, `${JSON.stringify(r)}\n`); } if (r.notLinked) { counts.notLinked++; findings.push({ question: 'linker', id: p.id, detail: `not linked, so the compiler's answer is not known: ${firstError(r.buildStderr)}` }); continue; } if (r.compiled) counts.compiled++; else counts.rejected++; findings.push(...judge(p, r)); if (p.interp === 'ran') counts.interpreterRan++; if (p.interp === 'declined') counts.interpreterDeclined++; if (p.godbolt) counts.godboltCompared++; if (!flag('json') && process.stderr.isTTY) process.stderr.write(`\r${next}/${programs.length} `); } } await Promise.all(Array.from({ length: jobs }, worker)); if (!keep) fs.rmSync(workdir, { recursive: true, force: true }); if (!flag('json') && process.stderr.isTTY) process.stderr.write('\r'); const unexpected = []; const expected = []; const rounding = []; for (const f of findings) (f.question === 'rounding' ? rounding : EXPECTED[`${f.question} ${f.id}`] ? expected : unexpected).push(f); const ids = new Set(programs.map((p) => p.id)); const stale = item || only ? [] : Object.keys(EXPECTED).filter((k) => ids.has(k.split(' ')[1]) && !findings.some((f) => `${f.question} ${f.id}` === k)); if (flag('json')) console.log(JSON.stringify({ compiler: `Mojo ${version}`, counts, unexpected, expected, rounding, stale }, null, 2)); else { console.log(`Mojo ${version} on this machine: ${counts.programs} programs (${counts.compiled} compiled, ${counts.rejected} rejected, ${counts.cached} from the cache)`); console.log(`the interpreter ran ${counts.interpreterRan} of them and declined ${counts.interpreterDeclined}; ${counts.godboltCompared} compared with godbolt's stored answer`); if (counts.notLinked) console.log(`\n${counts.notLinked} program(s) were compiled and could not be linked. That is this machine's C compiler, which mojo build calls to link, not Mojo's answer: under pixi it is the pinned gcc and C library (pixi.toml, docs/ci.md).`); for (const q of ['linker', 'checker', 'interpreter', 'translator', 'godbolt']) { const fs_ = unexpected.filter((f) => f.question === q); if (!fs_.length) continue; console.log(`\n${q}: ${fs_.length}`); for (const f of fs_) console.log(` ${f.id}: ${f.detail}`); } if (rounding.length) { console.log(`\nsame answer, other last digits (the compiler's rounding and std.math): ${rounding.length}`); for (const f of rounding) console.log(` ${f.id}: ${f.detail}`); } if (expected.length) { console.log(`\nexpected differences: ${expected.length}`); for (const f of expected) console.log(` ${f.id}: ${EXPECTED[`${f.question} ${f.id}`]}`); } for (const k of stale) console.log(`\nno longer differs; take it off EXPECTED in scripts/mojo/local.mjs: ${k}`); if (!unexpected.length && !stale.length) console.log('\nevery answer agrees'); } process.exit(unexpected.length || stale.length ? 1 : 0);