#!/usr/bin/env node // SPDX-FileCopyrightText: 2026 Scientific Computing Studio, LLC // SPDX-License-Identifier: Apache-2.0 /** * The library's tools: check every routine of pplus-library (the submodule library/) at every level, record * what was found in the library, and generate core's registry from it. * * node scripts/library.mjs check [--dir library] [--only stats.Mean] every check; writes status.json, STATUS.md, goldens * node scripts/library.mjs emit [--check] library/ -> src/library/generated.ts * node scripts/library.mjs harness [--input] print the program a reference is run as (its stdin) * node scripts/library.mjs mojo-sources each Mojo reference's program and stdin, for godbolt * * The checks of one routine: * structure routine.pseudo defines exactly the routine routine.json names, and nothing else (USE lines aside) * pseudo every case runs; its result is recorded and becomes what the references are held to * prover every obligation of the routine: pass when all are proved, open when some are not, fail when broken * fuzz the fuzzer finds no input that breaks a contract or stops the run * mojo the Mojo generated from the pseudo checks, runs in core's interpreter and prints what the pseudo prints * and for each reference implementation, per way of running it: * cpython python3 runs it on every case cc -O0, cc -O2 cc compiles and runs it on every case * interpreter core's Mojo interpreter runs it compiler the pinned mojo on this machine builds and runs it * godbolt the stored answer of the pinned compiler on Compiler Explorer * and the proof, if there is one: the pinned Dafny verifies it (or its stored verdict for this exact text). * * Needs a build (dist/). Python, a C compiler and the pinned Mojo compiler (pixi brings it) are used when they are * on the PATH; without them those checks are recorded as skipped, never as passed. A Mojo compiler of another * version than the pin is not asked: its answer would say nothing about the pin. */ import fs from 'node:fs'; import os from 'node:os'; import path from 'node:path'; import crypto from 'node:crypto'; import { execFileSync, spawnSync } from 'node:child_process'; import { fileURLToPath } from 'node:url'; const CORE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'); const args = process.argv.slice(2); const cmd = args[0]; const opt = (name, dflt = null) => { const i = args.indexOf(`--${name}`); return i >= 0 ? args[i + 1] : dflt; }; const flag = (name) => args.includes(`--${name}`); const LIB = path.resolve(opt('dir', path.join(CORE, 'library'))); const GENERATED = path.join(CORE, 'src', 'library', 'generated.ts'); const sha256 = (s) => crypto.createHash('sha256').update(s).digest('hex'); const readJson = (p) => JSON.parse(fs.readFileSync(p, 'utf8')); const writeIfChanged = (p, text) => { if (!fs.existsSync(p) || fs.readFileSync(p, 'utf8') !== text) { fs.mkdirSync(path.dirname(p), { recursive: true }); fs.writeFileSync(p, text); return true; } return false; }; /* ------------------------------------------------------------------ */ /* Reading the library */ /* ------------------------------------------------------------------ */ /** Every module and routine on disk, with its sources, and the status last recorded for it. */ export function load(dir = LIB) { if (!fs.existsSync(path.join(dir, 'modules'))) throw new Error(`no library at ${dir}: check out the submodule (git submodule update --init) or pass --dir`); const status = fs.existsSync(path.join(dir, 'status.json')) ? readJson(path.join(dir, 'status.json')).routines || {} : {}; const modules = []; for (const m of fs.readdirSync(path.join(dir, 'modules')).sort()) { const mdir = path.join(dir, 'modules', m); if (!fs.existsSync(path.join(mdir, 'module.json'))) continue; const meta = readJson(path.join(mdir, 'module.json')); const routines = []; for (const r of fs.readdirSync(mdir).sort()) { const rdir = path.join(mdir, r); if (!fs.existsSync(path.join(rdir, 'routine.json'))) continue; const rm = readJson(path.join(rdir, 'routine.json')); const id = `${meta.name}.${rm.name}`; const st = status[id] || {}; routines.push({ id, module: meta.name, name: rm.name, dir: path.relative(dir, rdir).split(path.sep).join('/'), summary: rm.summary || '', tags: rm.tags || [], sources: rm.sources || [], source: fs.readFileSync(path.join(rdir, 'routine.pseudo'), 'utf8'), cases: (rm.cases || []).map((c, i) => ({ ...c, ...(st.cases?.[i]?.call === c.call ? { result: st.cases[i].result } : {}) })), references: (rm.references || []).map((ref) => ({ lang: ref.lang, level: ref.level, file: ref.file, note: ref.note || '', ...(ref.rel !== undefined ? { rel: ref.rel } : {}), ...(ref.abs !== undefined ? { abs: ref.abs } : {}), source: fs.readFileSync(path.join(rdir, ref.file), 'utf8'), checks: st.references?.[`${ref.lang}/${ref.level}`] || {}, })), ...(rm.proof ? { proof: { lang: rm.proof.lang, file: rm.proof.file, note: rm.proof.note || '', source: fs.readFileSync(path.join(rdir, rm.proof.file), 'utf8'), check: st.proof || { status: 'unverified', detail: 'not checked yet' } } } : {}), checks: st.checks || {}, }); } modules.push({ name: meta.name, title: meta.title, summary: meta.summary, routines }); } return modules; } /* ------------------------------------------------------------------ */ /* Values in other languages */ /* ------------------------------------------------------------------ */ const floatText = (v) => { const s = String(v); return /[.e]/.test(s) || !Number.isFinite(v) ? s : `${s}.0`; }; const items = (v) => (Array.isArray(v) ? v : v?.data ? v.data : []); function pyLiteral(v, t) { switch (t?.k) { case 'FLOAT': return floatText(v).replace('e+', 'e'); case 'INTEGER': return String(v); case 'BOOL': return v ? 'True' : 'False'; case 'CHAR': case 'STRING': return JSON.stringify(v); case 'LIST': case 'ARRAY': return `[${items(v).map((x) => pyLiteral(x, t.of)).join(', ')}]`; default: throw new Error(`no Python literal for ${t?.k}`); } } function mojoType(t) { switch (t?.k) { case 'FLOAT': return t.bits === 32 ? 'Float32' : 'Float64'; case 'INTEGER': return t.bits ? `${t.signed ? 'Int' : 'UInt'}${t.bits}` : 'Int'; case 'BOOL': return 'Bool'; case 'CHAR': case 'STRING': return 'String'; case 'LIST': case 'ARRAY': return `List[${mojoType(t.of)}]`; default: throw new Error(`no Mojo type for ${t?.k}`); } } /* * A compiled reference's cases arrive at run time. Its program holds no case: main reads every case's arguments * from one line of stdin, so the compiler cannot work out a call's result while it builds the program (a call on * literal arguments it may fold, with its own arithmetic and its own math library; built with contraction on, as * Mojo is by default, the fold also skips the run-time code's fused multiply-adds: probes/float-contract-runtime), * and what a runner prints is what the routine computes on inputs it did not know. A Mojo reference's program * and line go to core's interpreter, the pinned compiler on this machine and godbolt; a C reference's to cc at * each level. One line, read by one input(): on a pipe, Mojo * 1.2.0's input() returns the first line and a second call raises EOF (probes/input-pipe-first-line, input-lines). * * The line is words joined by single spaces: the number of cases, then each case's arguments in order, then * `end`. A whole number is its digits. A FLOAT is two whole numbers m and e with x = m * 2^e exactly, m odd and * below 2^53 (so Float64(m) is exact) and every doubling or halving that rebuilds x exact as well * (probes/float-scale-exact; C's ldexp): the program gets the case's number bit for bit, with no decimal * conversion in between. A String is its text with %, space and line breaks written %25, %20, %0A, %0D * (probes/split-empty-fields, string-replace-escapes). A List is its length, then its items. */ /** The words one value is sent as. */ function caseWords(v, t) { switch (t?.k) { case 'FLOAT': return floatWords(Number(v)); case 'INTEGER': return [String(v)]; case 'BOOL': return [v ? '1' : '0']; case 'CHAR': case 'STRING': return [String(v).replace(/%/g, '%25').replace(/ /g, '%20').replace(/\n/g, '%0A').replace(/\r/g, '%0D')]; case 'LIST': case 'ARRAY': { const xs = items(v); return [String(xs.length), ...xs.flatMap((x) => caseWords(x, t.of))]; } default: throw new Error(`no way to send a ${t?.k} at run time`); } } /** A double as [m, e] with x = m * 2^e exactly, m odd (or 0) and below 2^53; an infinity as 2^1024 overflowing. */ export function floatWords(x) { if (Number.isNaN(x)) throw new Error('a NaN argument cannot be sent'); if (!Number.isFinite(x)) return [x > 0 ? '1' : '-1', '1024']; if (x === 0) return [Object.is(x, -0) ? '-0' : '0', '0']; const dv = new DataView(new ArrayBuffer(8)); dv.setFloat64(0, x); const hi = dv.getUint32(0); const biased = (hi >>> 20) & 0x7ff; let m = (BigInt(hi & 0xfffff) << 32n) | BigInt(dv.getUint32(4)); let e = -1074; // a subnormal: m * 2^-1074 if (biased) { m |= 1n << 52n; e = biased - 1075; } while (m % 2n === 0n) { m /= 2n; e++; } return [`${hi >>> 31 ? '-' : ''}${m}`, String(e)]; } /** The line of stdin a compiled reference's program reads: every case's arguments. */ export function caseInput(params, calls) { const words = [String(calls.length), ...calls.flatMap((c) => c.args.flatMap((v, i) => caseWords(v, params[i].type))), 'end']; return `${words.join(' ')}\n`; } /** The helper that reads one value of type t, and the helpers it needs, defined into `defs`; returns its name. */ function mojoReader(t, defs) { const T = mojoType(t); const name = `read_${T.replace(/List\[/g, 'list_').replace(/\]/g, '').toLowerCase()}`; if (defs.has(name)) return name; const head = `def ${name}(words: List[String], mut at: Int) raises -> ${T}:`; switch (t?.k) { case 'FLOAT': if (t.bits === 32) throw new Error('no run-time reader for Float32 yet'); defs.set(name, `${head} # x = m * 2^e, sent as m and e: Float64(m) is exact (m is below 2^53), and so is each doubling or halving var x = Float64(atol(words[at])) if words[at] == "-0": x = -x var e = atol(words[at + 1]) at += 2 while e > 0: x *= 2.0 e -= 1 while e < 0: x *= 0.5 e += 1 return x`); break; case 'INTEGER': if (t.bits) throw new Error(`no run-time reader for ${T} yet`); defs.set(name, `${head}\n at += 1\n return atol(words[at - 1])`); break; case 'BOOL': defs.set(name, `${head}\n at += 1\n return atol(words[at - 1]) != 0`); break; case 'CHAR': case 'STRING': defs.set(name, `${head} # the words are split at spaces, so a space is sent as %20, a line break as %0A or %0D, and % as %25 at += 1 return words[at - 1].replace("%20", " ").replace("%0A", "\\n").replace("%0D", "\\r").replace("%25", "%")`); break; case 'LIST': case 'ARRAY': { const item = mojoReader(t.of, defs); defs.set(name, `${head} var n = atol(words[at]) at += 1 var items = ${T}() for _ in range(n): items.append(${item}(words, at)) return items^`); break; } default: throw new Error(`no run-time reader for ${t?.k}`); } return name; } /** A Mojo reference's program: its source, unchanged, then the readers and a main that reads and prints each case. */ function mojoHarness(ref, fname, params) { const defs = new Map(); const readers = params.map((p) => mojoReader(p.type, defs)); for (const name of [...defs.keys(), 'main']) if (new RegExp(`\\b${name}\\b`).test(ref.source)) throw new Error(`the reference uses the name ${name}, which its harness defines`); return `${ref.source.replace(/\s+$/, '')} ${[...defs.values()].join('\n\n\n')} def main() raises: # the cases arrive at run time, on one line of stdin: how many there are, each one's arguments, then end var words = List[String]() for w in input().split(" "): words.append(String(w)) var at = 1 for _ in range(atol(words[0])): ${readers.map((r, i) => ` var a${i} = ${r}(words, at)`).join('\n')} print(${fname}(${readers.map((_, i) => `a${i}`).join(', ')})) if at != len(words) - 1 or words[at] != "end": raise Error("the input line does not hold the cases it announces") `; } /** The readers every C harness has: they take the words of the line caseInput writes, in order. */ const C_READERS = `/* The cases arrive at run time, on one line of stdin: how many there are, each one's arguments, then end. */ static char *line_rest; static void read_line(void) { size_t cap = 256, n = 0; char *line = malloc(cap); int ch; while (line && (ch = getchar()) != EOF && ch != '\\n') { if (n + 1 >= cap) line = realloc(line, cap *= 2); if (line) line[n++] = (char)ch; } if (!line) exit(3); line[n] = '\\0'; line_rest = line; } static char *read_word(void) { if (!line_rest) { fputs("the input line ended early\\n", stderr); exit(3); } char *word = line_rest, *space = strchr(line_rest, ' '); if (space) { *space = '\\0'; line_rest = space + 1; } else line_rest = NULL; return word; } static long read_long(void) { return strtol(read_word(), NULL, 10); } /* x = m * 2^e, sent as m and e: (double)m is exact (m is below 2^53), and so is ldexp */ static double read_double(void) { const char *m = read_word(); double x = ldexp((double)strtoll(m, NULL, 10), (int)strtol(read_word(), NULL, 10)); return strcmp(m, "-0") == 0 ? -x : x; }`; /** The reader a C harness has when the routine takes a CHAR or a STRING. */ const C_READ_STRING = `/* a space is sent as %20, a line break as %0A or %0D, and % as %25 */ static char *read_string(void) { char *word = read_word(), *out = word; for (const char *p = word; *p; p++) { if (*p == '%' && p[1] && p[2]) { char hex[3] = { p[1], p[2], '\\0' }; *out++ = (char)strtol(hex, NULL, 16); p += 2; } else *out++ = *p; } *out = '\\0'; return word; }`; /** The C statements that read one argument (a list as an array and its length), and the expressions it is passed as. */ function cRead(t, name) { switch (t?.k) { case 'FLOAT': return { decls: [`double ${name} = read_double();`], args: [name] }; case 'INTEGER': return { decls: [`long ${name} = read_long();`], args: [name] }; case 'BOOL': return { decls: [`int ${name} = read_long() != 0;`], args: [name] }; case 'CHAR': return { decls: [`char ${name} = read_string()[0];`], args: [name] }; case 'STRING': return { decls: [`const char *${name} = read_string();`], args: [name] }; case 'LIST': case 'ARRAY': { if (t.of?.k !== 'FLOAT' && t.of?.k !== 'INTEGER') throw new Error('C lists hold numbers only'); const [ct, read] = t.of.k === 'FLOAT' ? ['double', 'read_double'] : ['long', 'read_long']; return { decls: [`long ${name}_n = read_long();`, `${ct} *${name} = malloc(sizeof(${ct}) * (${name}_n ? ${name}_n : 1));`, `if (!${name}) return 3;`, `for (long i = 0; i < ${name}_n; i++) ${name}[i] = ${read}();`], args: [name, `${name}_n`], free: name, }; } default: throw new Error(`no C argument for ${t?.k}`); } } /** A C reference's program: its source, unchanged, then the readers and a main that reads and prints each case. */ function cHarness(ref, fname, sub) { for (const name of ['read_line', 'read_word', 'read_long', 'read_double', 'read_string', 'line_rest', 'main']) if (new RegExp(`\\b${name}\\b`).test(ref.source)) throw new Error(`the reference uses the name ${name}, which its harness defines`); const fmt = sub.returns?.k === 'FLOAT' ? '%.17g' : '%ld'; const reads = sub.params.map((p, i) => cRead(p.type, `a${i}`)); const body = [...reads.flatMap((r) => r.decls), `printf("${fmt}\\n", ${fname}(${reads.flatMap((r) => r.args).join(', ')}));`, ...reads.filter((r) => r.free).map((r) => `free(${r.free});`)]; return `#include #include #include #include ${ref.source.replace(/\s+$/, '')} ${C_READERS} ${sub.params.some((p) => p.type?.k === 'CHAR' || p.type?.k === 'STRING') ? `\n${C_READ_STRING}\n` : ''} int main(void) { read_line(); long cases = read_long(); for (long k = 0; k < cases; k++) { ${body.map((l) => ` ${l}`).join('\n')} } if (strcmp(read_word(), "end") != 0 || line_rest) { fputs("the input line does not hold the cases it announces\\n", stderr); return 3; } return 0; } `; } /* ------------------------------------------------------------------ */ /* The checks */ /* ------------------------------------------------------------------ */ const ok = (detail) => ({ status: 'pass', detail }); const bad = (detail) => ({ status: 'fail', detail }); const skip = (detail) => ({ status: 'skipped', detail }); const open = (detail) => ({ status: 'open', detail }); const unverified = (detail) => ({ status: 'unverified', detail }); function have(cmdName) { return spawnSync(cmdName, ['--version'], { encoding: 'utf8' }).status === 0; } /** The version of the `mojo` on the PATH, or null when there is none. */ function mojoVersion() { const p = spawnSync('mojo', ['--version'], { encoding: 'utf8' }); return p.status === 0 ? (/Mojo\s+(\S+)/.exec(p.stdout) || [])[1] ?? null : null; } /** * Build a Mojo program with the local compiler and run it on `input`: { compiled, error, status, stdout }. `args` are * every build argument, the pin's (mojoBuildArgs in src/services/godbolt.ts). */ function buildAndRunMojo(src, dir, args, input = '') { fs.mkdirSync(dir, { recursive: true }); fs.writeFileSync(path.join(dir, 'example.mojo'), src); const b = spawnSync('mojo', ['build', ...args.split(' ').filter(Boolean), 'example.mojo', '-o', 'example'], { cwd: dir, encoding: 'utf8', timeout: 180000 }); if (b.status !== 0) return { compiled: false, error: ((b.stderr || '').split('\n').find((l) => /error:/.test(l)) || 'the build failed').replace(/^.*example\.mojo:/, 'line ').trim() }; // core-dump limit 1: a program that traps is not piped to systemd-coredump (see scripts/mojo/local.mjs) const limited = spawnSync('prlimit', ['--version'], { encoding: 'utf8' }).status === 0; const r = limited ? spawnSync('prlimit', ['--core=1:1', './example'], { cwd: dir, input, encoding: 'utf8', timeout: 60000 }) : spawnSync('./example', [], { cwd: dir, input, encoding: 'utf8', timeout: 60000 }); return { compiled: true, status: r.status ?? (r.signal ? `signal ${r.signal}` : 'timed out'), stdout: r.stdout || '' }; } /** Does a printed value agree with the pseudo's, within the reference's tolerance? */ function agrees(printed, want, t, rel = 0, abs = 0) { const s = String(printed).trim(); if (t?.k === 'FLOAT' || t?.k === 'INTEGER') { const got = Number(s.replace(/^inf$/i, 'Infinity').replace(/^-inf$/i, '-Infinity').replace(/^nan$/i, 'NaN')); if (Number.isNaN(got) && Number.isNaN(want)) return true; if (Number.isNaN(got)) return false; if (got === want) return true; return Math.abs(got - want) <= Math.max(rel * Math.max(Math.abs(got), Math.abs(want)), abs); } if (t?.k === 'BOOL') return ['true', '1'].includes(s.toLowerCase()) === Boolean(want); return s === String(want); } function compareLines(stdout, wants, t, rel, abs) { const got = stdout.replace(/\n$/, '').split('\n'); if (got.length !== wants.length) return `printed ${got.length} line(s) for ${wants.length} case(s)`; for (let i = 0; i < wants.length; i++) if (!agrees(got[i], wants[i].value, t, rel, abs)) return `case ${i + 1} (${wants[i].call}) printed ${got[i]}, and the pseudo gives ${wants[i].text}`; return null; } /** * The program a reference implementation is run as: its source, plus a main that prints each case. A Mojo * or C reference's program holds no case; it reads them from the line `harnessInput` gives (see caseInput). */ export function harness(lang, ref, fname, sub, calls) { const params = sub.params; if (lang === 'python') { return `import importlib.util\nspec = importlib.util.spec_from_file_location("ref", __REF__)\nref = importlib.util.module_from_spec(spec)\nspec.loader.exec_module(ref)\n${calls.map((c) => `print(repr(ref.${fname}(${c.args.map((v, i) => pyLiteral(v, params[i].type)).join(', ')})))`).join('\n')}\n`; } if (lang === 'mojo') return mojoHarness(ref, fname, params); if (lang === 'c') return cHarness(ref, fname, sub); throw new Error(`no harness for ${lang}`); } /** What a reference's program reads on stdin: every case's arguments for Mojo and C, nothing for Python. */ export function harnessInput(lang, sub, calls) { return lang === 'mojo' || lang === 'c' ? caseInput(sub.params, calls) : ''; } export async function checkLibrary(dir = LIB, only = null) { const { setLibrary } = await import(path.join(CORE, 'dist/library/registry.js')); const svc = await import(path.join(CORE, 'dist/services/pseudo.js')); const { parseExpression } = await import(path.join(CORE, 'dist/engines/pseudo/parse.js')); const { evaluateConstant } = await import(path.join(CORE, 'dist/engines/pseudo/interp.js')); const { formatValue } = await import(path.join(CORE, 'dist/engines/pseudo/lang.js')); const { pseudoToMojo, snake } = await import(path.join(CORE, 'dist/sync/pseudo-to-mojo.js')); const { checkMojo } = await import(path.join(CORE, 'dist/mojo/check.js')); const { runMojo } = await import(path.join(CORE, 'dist/mojo/interp.js')); const { sameOutput, outputDistance } = await import(path.join(CORE, 'dist/sync/compare.js')); // every Mojo program is built with the pin's arguments (library/mojo/pin.json build.args): godbolt's, and on this // machine the same, less the x86-64 CPU when this machine is not x86-64 const { mojoBuildArgs } = await import(path.join(CORE, 'dist/services/godbolt.js')); const godboltArgs = mojoBuildArgs(); const buildArgs = mojoBuildArgs('', { x86_64: process.arch === 'x64' }); const modules = load(dir); setLibrary(modules); const pin = readJson(path.join(dir, 'mojo', 'pin.json')); const dafny = (() => { try { const p = execFileSync('python3', [path.join(CORE, 'scripts', 'dafny.py'), 'path'], { encoding: 'utf8' }).trim(); return fs.existsSync(p) ? p : null; } catch { return null; } })(); const dafnyVersion = (() => { try { return readJson(path.join(CORE, 'scripts', 'dafny.json')).version; } catch { return null; } })() || (() => { const m = /VERSION = "([^"]+)"/.exec(fs.readFileSync(path.join(CORE, 'scripts', 'dafny.py'), 'utf8')); return m ? m[1] : 'unknown'; })(); const python = have('python3'); const cc = have('cc'); const localMojo = mojoVersion(); const mojoHere = localMojo === pin.mojo.version; const noCompiler = localMojo ? `the mojo on the PATH is ${localMojo}, and the pin is ${pin.mojo.version}` : 'no mojo on the PATH (pixi run library-check brings the pinned one)'; /** Numbers the compiled program may print with other last digits than the pseudo: its own std.math (docs/trust.md). Its arithmetic is the pseudo's: it is built with contraction off (library/mojo/pin.json build.args). */ const ROUNDING = 1e-9; const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'pplus-library-')); const out = {}; for (const m of modules) { for (const r of m.routines) { if (only && r.id !== only) { continue; } const rdir = path.join(dir, r.dir); const rec = { checks: {}, cases: [], references: {}, proof: undefined }; out[r.id] = rec; const st = svc.studyOf(r.source); const program = st.program?.program; // structure const subs = program ? [...program.subs.values()] : []; if (!st.ok) { rec.checks.structure = bad(`the pseudo does not check: ${st.diagnostics.filter((d) => d.severity === 'error').map((d) => `line ${d.line}: ${d.message}`).join('; ')}`); continue; } if (subs.length !== 1 || subs[0].name.toUpperCase() !== r.name.toUpperCase()) { rec.checks.structure = bad(`routine.pseudo defines ${subs.map((s) => s.name).join(', ') || 'nothing'}; it must define exactly ${r.name} (helpers are routines of their own, brought in with USE)`); continue; } if (program.main.body.length) { rec.checks.structure = bad(`routine.pseudo has lines outside ${r.name} (line ${program.main.body[0].line}); a routine file holds USE lines and the routine only`); continue; } const sub = subs[0]; rec.checks.structure = ok(`defines ${sub.kind === 'Function' ? 'FUNCTION' : 'PROCEDURE'} ${sub.name}${program.libs?.size ? `, using ${[...program.libs.values()].map((x) => x.lib.id).join(', ')}` : ''}`); // pseudo: every case const calls = []; let caseFail = null; for (const c of r.cases) { const p = parseExpression(c.call); let entry = { call: c.call }; try { if (p.diags.some((d) => d.severity === 'error') || p.expr.kind !== 'CallExpr' || p.expr.name.toUpperCase() !== r.name.toUpperCase()) throw new Error(`"${c.call}" is not a call of ${r.name}`); const vals = p.expr.args.map((a) => evaluateConstant(program, a)); const tr = svc.runPseudo(st, { call: c.call, maxSteps: 2000000 }); if (tr.error) throw new Error(`${c.call} stops: ${tr.error.message}`); const result = tr.raw.result; entry = { call: c.call, result: formatValue(result, sub.returns, { max: 1000 }) }; calls.push({ call: c.call, args: vals, value: result, text: entry.result }); } catch (e) { caseFail = caseFail || e.message; } rec.cases.push(entry); } rec.checks.pseudo = caseFail ? bad(caseFail) : ok(`${calls.length} case(s) run`); // prover // no time on the clock: what is recorded is the counted budgets' answer, the same on every machine const pr = svc.provePseudo(st, { budgetMs: Infinity }); const obs = pr.units.flatMap((u) => u.obligations); const broken = obs.filter((o) => o.status === 'broken'); const notProved = obs.filter((o) => o.status !== 'proved'); rec.checks.prover = broken.length ? bad(`${broken.length} obligation(s) broken: ${broken.map((o) => `${o.kind}@${o.line} (${o.label})`).join('; ')}`) : notProved.length ? open(`${obs.length - notProved.length} of ${obs.length} obligation(s) proved; open: ${notProved.map((o) => `${o.kind}@${o.line} (${o.label})`).join('; ')}`) : ok(`all ${obs.length} obligation(s) proved`); // fuzz const props = svc.propertiesPseudo(st, r.name)[0]; rec.checks.fuzz = !props ? skip('no routine to fuzz') : props.problem ? skip(`the fuzzer cannot generate inputs: ${props.problem}`) : props.failures.length ? bad(`${props.failures.length} failing input(s), first: ${props.failures[0].call}: ${props.failures[0].message}`) : ok(`no failure in ${props.checked} generated input(s)`); // the Mojo generated from the pseudo, on every case if (calls.length) { const prog = `USE ${r.module}.${r.name}\n${calls.map((c) => `OUTPUT ${c.call}`).join('\n')}\n`; const want = svc.runPseudo(svc.studyOf(prog), {}).output.join('\n'); const mj = pseudoToMojo(prog); if ('unsupported' in mj) rec.checks.mojo = bad(`the translator refused: ${mj.unsupported.map((d) => d.message).join('; ')}`); else { const gaps = mj.notes.filter((n) => n.id === 'translate-gap'); const ck = checkMojo(mj.source); const errs = ck.diagnostics.filter((d) => d.severity === 'error'); if (gaps.length) rec.checks.mojo = skip(`the translator has no Mojo for: ${gaps.map((g) => g.message.replace(/^.*?\(|\)\..*$/g, '')).join('; ')}`); else if (errs.length) rec.checks.mojo = bad(`the generated Mojo has checker errors: ${errs.map((d) => `L${d.line} ${d.message}`).join(' | ')}`); else { const run = runMojo(ck.module, mj.source, { maxSteps: 4000000 }); // the pinned compiler on this machine, when there is one: the interpreter's word is not the compiler's const built = mojoHere ? buildAndRunMojo(mj.source, path.join(tmp, `gen-${fname0(r)}`), buildArgs) : null; const far = built?.compiled && built.status === 0 ? outputDistance(want, built.stdout) : null; const compiled = !built ? null : !built.compiled ? bad(`Mojo ${localMojo} rejects the generated Mojo: ${built.error}`) : built.status !== 0 ? bad(`the generated Mojo, built by Mojo ${localMojo}, stopped (exit ${built.status})`) : far > ROUNDING ? bad(`the generated Mojo, built by Mojo ${localMojo}, printed ${JSON.stringify(built.stdout.slice(0, 120))}; the pseudo printed ${JSON.stringify(want.slice(0, 120))}`) : ok(far > 0 ? `built by Mojo ${localMojo}, the generated Mojo prints the pseudo's results to within ${far.toExponential(1)} of each value (the compiler's rounding and std.math)` : `built by Mojo ${localMojo}, the generated Mojo prints what the pseudo prints on every case`); const interp = run.refused ? null : run.exitCode !== 0 ? bad(`the generated Mojo stopped in core's interpreter (exit ${run.exitCode})`) : sameOutput(want, run.stdout) ? ok('the generated Mojo prints what the pseudo prints on every case, in core\'s interpreter') // the interpreter computes std.math's exact functions as Mojo does (hypot, for one), so it is held to the // pseudo as the compiler is: to the rounding of those functions, not to the last digit : outputDistance(want, run.stdout) <= ROUNDING ? ok(`in core's interpreter the generated Mojo prints the pseudo's results to within ${outputDistance(want, run.stdout).toExponential(1)} of each value (std.math, computed as Mojo computes it)`) : bad(`in core's interpreter the generated Mojo printed ${JSON.stringify(run.stdout.slice(0, 120))}; the pseudo printed ${JSON.stringify(want.slice(0, 120))}`); rec.checks.mojo = compiled?.status === 'fail' ? compiled : interp?.status === 'fail' ? interp : compiled && interp ? ok(`${compiled.detail}, and in core's interpreter`) : compiled ? ok(`${compiled.detail} (core's interpreter declines ${run.refused})`) : interp ? ok(`${interp.detail} (${noCompiler})`) : skip(`core's Mojo interpreter declines ${run.refused}, and ${noCompiler}`); } } } // references const fname = snake(r.name); for (const ref of r.references) { const checks = {}; rec.references[`${ref.lang}/${ref.level}`] = checks; if (!calls.length) { checks.cases = skip('no case ran in pseudo, so there is nothing to hold it to'); continue; } const rel = ref.rel ?? 0; const abs = ref.abs ?? 0; const tol = rel || abs ? ` (within rel ${rel}, abs ${abs})` : ' (exactly)'; try { if (ref.lang === 'python') { if (!python) { checks.cpython = skip('python3 is not on the PATH'); continue; } const h = harness('python', ref, fname, sub, calls).replace('__REF__', JSON.stringify(path.join(rdir, ref.file))); const p = spawnSync('python3', ['-c', h], { encoding: 'utf8', timeout: 60000 }); if (p.status !== 0) { checks.cpython = bad(`python3 stopped: ${(p.stderr || '').trim().split('\n').pop()}`); continue; } const diff = compareLines(p.stdout, calls, sub.returns, rel, abs); checks.cpython = diff ? bad(diff) : ok(`agrees with the pseudo on ${calls.length} case(s)${tol}`); } else if (ref.lang === 'c') { if (!cc) { checks['cc -O0'] = skip('no C compiler (cc) on the PATH'); continue; } // the program reads its cases from stdin, so at -O2 too the answer is the compiled code's, not the constant folder's const src = harness('c', ref, fname, sub, calls); const stdin = harnessInput('c', sub, calls); const file = path.join(tmp, `${fname}-${ref.level}.c`); fs.writeFileSync(file, src); for (const level of ['-O0', '-O2']) { const bin = path.join(tmp, `${fname}-${ref.level}${level}`); const c = spawnSync('cc', ['-std=c11', level, '-o', bin, file, '-lm'], { encoding: 'utf8' }); if (c.status !== 0) { checks[`cc ${level}`] = bad(`cc ${level} failed: ${(c.stderr || '').trim().split('\n')[0]}`); continue; } const p = spawnSync(bin, [], { input: stdin, encoding: 'utf8', timeout: 60000 }); const diff = p.status !== 0 ? `exited ${p.status}` : compareLines(p.stdout, calls, sub.returns, rel, abs); checks[`cc ${level}`] = diff ? bad(diff) : ok(`agrees with the pseudo on ${calls.length} case(s)${tol}`); } } else if (ref.lang === 'mojo') { // the program reads its cases from stdin, so no runner's answer is the compiler working them out as it builds const src = harness('mojo', ref, fname, sub, calls); const stdin = harnessInput('mojo', sub, calls); const ck = checkMojo(src); const errs = ck.diagnostics.filter((d) => d.severity === 'error'); if (errs.length) checks.interpreter = bad(`core's Mojo checker reports: ${errs.map((d) => `L${d.line} ${d.message}`).join(' | ')}`); else { const run = runMojo(ck.module, src, { input: [stdin.replace(/\n$/, '')], maxSteps: 4000000 }); const diff = run.refused ? null : run.exitCode !== 0 ? `stopped (exit ${run.exitCode})` : compareLines(run.stdout, calls, sub.returns, rel, abs); checks.interpreter = run.refused ? skip(`core's Mojo interpreter declines ${run.refused}`) : diff ? bad(diff) : ok(`agrees with the pseudo on ${calls.length} case(s) in core's interpreter${tol}`); } // the pinned compiler on this machine if (!mojoHere) checks.compiler = skip(noCompiler); else { const built = buildAndRunMojo(src, path.join(tmp, `ref-${fname}-${ref.level}`), buildArgs, stdin); const diff = !built.compiled ? `Mojo ${localMojo} rejects it: ${built.error}` : built.status !== 0 ? `built by Mojo ${localMojo}, it stopped (exit ${built.status})` : compareLines(built.stdout, calls, sub.returns, rel, abs); checks.compiler = diff ? bad(diff) : ok(`built by Mojo ${localMojo}, agrees with the pseudo on ${calls.length} case(s)${tol}`); } // the compiler's stored answer for this exact program const gfile = path.join(rdir, 'golden', `mojo-${ref.level}.json`); const g = fs.existsSync(gfile) ? readJson(gfile) : null; if (!g || g.source_sha256 !== sha256(src) || g.stdin !== stdin || g.args !== godboltArgs || g.compiler !== pin.godbolt.compiler) checks.godbolt = unverified(`no stored answer from ${pin.godbolt.compiler} for this program, input and build arguments: pixi run library-verify-mojo`); else if (!g.result?.compiled) checks.godbolt = bad(`${pin.godbolt.compiler} did not compile it: ${(g.result?.buildStderr || '').split('\n')[0]}`); else { const diff = g.result.exitCode !== 0 ? `exited ${g.result.exitCode}` : compareLines(g.result.stdout, calls, sub.returns, rel, abs); checks.godbolt = diff ? bad(diff) : ok(`${pin.godbolt.compiler} agrees with the pseudo on ${calls.length} case(s)${tol}`); } } else checks.cases = skip(`no runner for ${ref.lang} yet`); } catch (e) { checks.harness = bad(`could not build the harness: ${e.message}`); } } // proof if (r.proof) { const gfile = path.join(rdir, 'golden', 'dafny.json'); const src = r.proof.source; const flags = ['verify', '--resource-limit', '20000000']; if (dafny) { // without ICU on the machine .NET aborts unless told not to look for it (scripts/dafny.py) const p = spawnSync(dafny, [...flags, path.join(rdir, r.proof.file)], { encoding: 'utf8', timeout: 600000, env: { ...process.env, DOTNET_SYSTEM_GLOBALIZATION_INVARIANT: '1' } }); const summary = /Dafny program verifier finished with (.*)/.exec(p.stdout || '')?.[1] || (p.stdout || p.stderr || '').trim().split('\n').pop(); const pass = p.status === 0 && / 0 errors/.test(summary); rec.proof = pass ? ok(`Dafny ${dafnyVersion}: ${summary}`) : bad(`Dafny ${dafnyVersion}: ${summary}`); writeIfChanged(gfile, `${JSON.stringify({ tool: 'dafny', version: dafnyVersion, flags, source_sha256: sha256(src), verdict: pass ? 'verified' : 'failed', summary }, null, 2)}\n`); } else { const g = fs.existsSync(gfile) ? readJson(gfile) : null; rec.proof = g && g.source_sha256 === sha256(src) ? (g.verdict === 'verified' ? ok(`Dafny ${g.version} (stored answer): ${g.summary}`) : bad(`Dafny ${g.version} (stored answer): ${g.summary}`)) : unverified('the pinned Dafny is not fetched (pixi run dafny-fetch) and there is no stored verdict for this text'); } } } } fs.rmSync(tmp, { recursive: true, force: true }); return { modules, results: out }; } const ORDER = ['structure', 'pseudo', 'prover', 'fuzz', 'mojo']; const fname0 = (r) => r.id.replace(/[^A-Za-z0-9]+/g, '-'); function statusMarkdown(modules, results) { const mark = (c) => (!c ? '·' : { pass: 'pass', fail: '**fail**', open: 'open', skipped: 'skipped', unverified: 'unverified' }[c.status] || c.status); const lines = ['# Library status', '', '', '', 'Each routine, at each level. *pass*: checked and agrees; *open*: the prover could not finish every obligation (nothing is wrong, nothing is proved); *skipped*: the tool is not available here, or it declines the construct; *unverified*: no stored answer for this exact text yet.', '']; for (const m of modules) { lines.push(`## ${m.title} (\`${m.name}\`)`, '', '| Routine | Cases | Prover | Fuzz | Generated Mojo | References | Proof |', '| --- | --- | --- | --- | --- | --- | --- |'); for (const r of m.routines) { const res = results[r.id]; if (!res) continue; const refs = Object.entries(res.references).map(([k, checks]) => `${k}: ${Object.entries(checks).map(([how, c]) => `${how} ${mark(c)}`).join(', ')}`).join('
'); lines.push(`| \`${r.id}\` | ${mark(res.checks.pseudo)} | ${mark(res.checks.prover)} | ${mark(res.checks.fuzz)} | ${mark(res.checks.mojo)} | ${refs || '·'} | ${res.proof ? `dafny ${mark(res.proof)}` : '·'} |`); } lines.push(''); } lines.push('## Details', ''); for (const m of modules) for (const r of m.routines) { const res = results[r.id]; if (!res) continue; lines.push(`### ${r.id}`, ''); for (const k of ORDER) if (res.checks[k]) lines.push(`- ${k}: ${res.checks[k].status}. ${res.checks[k].detail}`); for (const [k, checks] of Object.entries(res.references)) for (const [how, c] of Object.entries(checks)) lines.push(`- ${k}, ${how}: ${c.status}. ${c.detail}`); if (res.proof) lines.push(`- proof: ${res.proof.status}. ${res.proof.detail}`); lines.push(''); } return lines.join('\n'); } /** * Every reference of every routine, with what it is run on: { id, ref, dir, fname, sub, calls, make, input }. * make() is the program (harness) and input() its stdin (harnessInput). Needs a build (dist/). */ export async function referencePrograms(dir = LIB) { const svc = await import(path.join(CORE, 'dist/services/pseudo.js')); const { setLibrary } = await import(path.join(CORE, 'dist/library/registry.js')); const { parseExpression } = await import(path.join(CORE, 'dist/engines/pseudo/parse.js')); const { evaluateConstant } = await import(path.join(CORE, 'dist/engines/pseudo/interp.js')); const { snake } = await import(path.join(CORE, 'dist/sync/pseudo-to-mojo.js')); const modules = load(dir); setLibrary(modules); const programs = []; for (const m of modules) for (const r of m.routines) { const st = svc.studyOf(r.source); if (!st.ok) continue; const sub = [...st.program.program.subs.values()][0]; const calls = r.cases.map((c) => ({ args: parseExpression(c.call).expr.args.map((a) => evaluateConstant(st.program.program, a)) })); const fname = snake(r.name); for (const ref of r.references) programs.push({ id: r.id, ref, dir: path.join(dir, r.dir), fname, sub, calls, make: () => harness(ref.lang, ref, fname, sub, calls), input: () => harnessInput(ref.lang, sub, calls) }); } return programs; } /* ------------------------------------------------------------------ */ /* Emitting core's registry */ /* ------------------------------------------------------------------ */ function emitText(dir = LIB) { const modules = load(dir); return `// Generated by scripts/library.mjs emit from library/ (pplus-library). Do not edit; run pixi run library-emit.\nimport type { LibraryModule } from './types.js';\n\nexport const LIBRARY_MODULES: LibraryModule[] = ${JSON.stringify(modules, null, 2)};\n`; } /* ------------------------------------------------------------------ */ /* Command line */ /* ------------------------------------------------------------------ */ if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) { if (cmd === 'check') { const only = opt('only'); const { modules, results } = await checkLibrary(LIB, only); const prior = fs.existsSync(path.join(LIB, 'status.json')) ? readJson(path.join(LIB, 'status.json')).routines || {} : {}; const merged = only ? { ...prior, ...results } : results; const sorted = Object.fromEntries(Object.keys(merged).sort().map((k) => [k, merged[k]])); writeIfChanged(path.join(LIB, 'status.json'), `${JSON.stringify({ comment: 'Written by pixi run library-check in pplus-core. Do not edit.', routines: sorted }, null, 2)}\n`); writeIfChanged(path.join(LIB, 'STATUS.md'), `${statusMarkdown(modules, sorted)}\n`); let failed = 0; for (const [id, res] of Object.entries(results)) { const all = [...Object.entries(res.checks), ...Object.entries(res.references).flatMap(([k, c]) => Object.entries(c).map(([h, v]) => [`${k} ${h}`, v])), ...(res.proof ? [['proof', res.proof]] : [])]; for (const [k, c] of all) if (c.status === 'fail') { failed++; console.log(`FAIL ${id} ${k}: ${c.detail}`); } console.log(`${id}: ${all.map(([k, c]) => `${k}=${c.status}`).join(' ')}`); } console.log(failed ? `${failed} failing check(s)` : 'no failing check'); process.exit(failed ? 1 : 0); } else if (cmd === 'emit') { const text = emitText(LIB); if (flag('check')) { const cur = fs.existsSync(GENERATED) ? fs.readFileSync(GENERATED, 'utf8') : ''; if (cur !== text) { console.error('src/library/generated.ts is out of date with library/: run pixi run library-emit'); process.exit(1); } console.log('src/library/generated.ts is up to date'); } else console.log(writeIfChanged(GENERATED, text) ? 'wrote src/library/generated.ts' : 'src/library/generated.ts unchanged'); } else if (cmd === 'harness' || cmd === 'mojo-sources') { const programs = await referencePrograms(LIB); if (cmd === 'harness') { const [id, lang, level] = args.slice(1); const p = programs.find((x) => x.id === id && x.ref.lang === lang && x.ref.level === level); if (!p) { console.error(`no reference ${lang}/${level} for ${id}`); process.exit(2); } process.stdout.write(flag('input') ? p.input() : p.make()); } else { // one entry per Mojo reference: the program and the stdin scripts/library_godbolt.py sends, and where its answer goes const list = programs.filter((p) => p.ref.lang === 'mojo').map((p) => ({ id: `${p.id} mojo/${p.ref.level}`, source: p.make(), stdin: p.input(), golden: path.join(p.dir, 'golden', `mojo-${p.ref.level}.json`) })); process.stdout.write(`${JSON.stringify(list, null, 2)}\n`); } } else { console.error('usage: node scripts/library.mjs check [--only id] | emit [--check] | harness [--input] | mojo-sources'); process.exit(2); } }