// SPDX-FileCopyrightText: 2026 Scientific Computing Studio, LLC // SPDX-License-Identifier: Apache-2.0 // What the documents say, held to what the files and the tools say. The README files, AGENTS.md files and the // hand-written documents in docs/ make claims a stranger reads first: the one-sentence description, what each // notation is, the library's modules and its example program, the library's own rules for its routines, and the // assembly census. Each test here fails when one of those claims stops being true, so a document cannot drift // from what it describes. (docs/sync-coverage.md is written by its own test and is not read here.) import test from 'node:test'; import assert from 'node:assert/strict'; import fs from 'node:fs'; import path from 'node:path'; import { spawnSync } from 'node:child_process'; import { fileURLToPath } from 'node:url'; import { studyOf, runPseudo } from '../dist/services/pseudo.js'; import { census } from '../scripts/asm-census.mjs'; const CORE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'); const LIB = path.join(CORE, 'library'); const read = (p) => fs.readFileSync(path.join(CORE, p), 'utf8'); /** The documents that describe the project in prose, in both repositories. */ const DOCUMENTS = ['README.md', 'AGENTS.md', 'docs/trust.md', 'docs/library.md', 'docs/exercises.md', 'docs/asm-coverage.md', 'library/README.md', 'library/AGENTS.md']; const SENTENCE = 'Programming+ takes a procedure from an idea to Mojo to the machine.'; /** What each name the project made up means, in the words every document uses the first time it says the name. */ const GLOSS = { lingo: 'steps in plain English', matho: 'equations written in LaTeX', pseudo: 'pseudocode precise enough to run, prove and translate', speco: 'a specification to prove against', }; const MOJO_GLOSS = "Modular's programming language, pinned to version 1.2.0"; /** A document's prose: no code blocks, no code spans, no link targets, no bold or italic marks. */ function prose(text) { return text.replace(/```[\s\S]*?```/g, ' ').replace(/`[^`\n]*`/g, ' ').replace(/\]\([^)]*\)/g, ']').replace(/\*+/g, ''); } test('every document that describes the project starts from the same sentence', () => { for (const doc of DOCUMENTS.filter((d) => !d.endsWith('asm-coverage.md'))) { assert.ok(read(doc).includes(SENTENCE), `${doc} does not say "${SENTENCE}"`); } }); test('each name the project made up is glossed, in the same words, where a document first uses it', () => { for (const doc of DOCUMENTS) { const text = prose(read(doc)); for (const [name, gloss] of Object.entries(GLOSS)) { const m = new RegExp(`(? { const notations = (doc) => read(doc).split('\n').filter((l) => /^- \*\*(lingo|matho|pseudo|speco|Mojo)\*\*: /.test(l)); const core = notations('README.md'); assert.equal(core.length, 5, 'README.md does not list the five notations'); assert.deepEqual(notations('library/README.md'), core); for (const [name, gloss] of Object.entries(GLOSS)) assert.ok(core.some((l) => l.startsWith(`- **${name}**: ${gloss}`)), `README.md: ${name}`); assert.ok(core.some((l) => l.startsWith(`- **Mojo**: ${MOJO_GLOSS}`)), 'README.md: Mojo'); for (const doc of ['AGENTS.md', 'docs/trust.md', 'docs/exercises.md']) assert.ok(read(doc).includes(MOJO_GLOSS), `${doc} does not say what Mojo is in the same words`); }); test("the library README's module table is the library's modules and routines", () => { const rows = [...read('library/README.md').matchAll(/^\| `(\w+)` \| (.*) \|$/gm)]; const table = Object.fromEntries(rows.map(([, mod, cell]) => [mod, cell.replace(/\([^)]*\)/g, '').split(',').map((x) => x.trim().split(' ')[0]).sort()])); const disk = {}; for (const mod of fs.readdirSync(path.join(LIB, 'modules'))) { const dir = path.join(LIB, 'modules', mod); if (!fs.existsSync(path.join(dir, 'module.json'))) continue; disk[mod] = fs.readdirSync(dir).filter((r) => fs.existsSync(path.join(dir, r, 'routine.json'))) .map((r) => JSON.parse(fs.readFileSync(path.join(dir, r, 'routine.json'), 'utf8')).name).sort(); } assert.deepEqual(table, disk); }); test("the library README's USE example prints what the README says it prints", () => { const readme = read('library/README.md'); const m = /A program uses a routine by name\.[^`]*```\n([\s\S]*?)```\n\nprints `([^`]*)`/.exec(readme); assert.ok(m, 'the example and its printed line are not where this test looks'); const tr = runPseudo(studyOf(m[1]), {}); assert.equal(tr.error, null, tr.error?.message); assert.equal(tr.output.join('\n'), m[2]); }); test("the core README's prove example ends with the line the README quotes", () => { const m = /pixi run cli prove (\S+)\s+# .*the last line is "([^"]+)"/.exec(read('README.md')); assert.ok(m, 'the prove example is not where this test looks'); const r = spawnSync(process.execPath, ['scripts/cli.mjs', 'prove', m[1]], { cwd: CORE, encoding: 'utf8' }); assert.equal(r.status, 0, r.stderr); assert.equal(r.stdout.trim().split('\n').pop(), m[2]); }); /** Every routine of the library, with its directory, its routine.json and its routine.pseudo. */ function routines() { const out = []; for (const mod of fs.readdirSync(path.join(LIB, 'modules'))) { const dir = path.join(LIB, 'modules', mod); if (!fs.statSync(dir).isDirectory()) continue; for (const r of fs.readdirSync(dir)) { const file = path.join(dir, r, 'routine.json'); if (!fs.existsSync(file)) continue; const json = JSON.parse(fs.readFileSync(file, 'utf8')); out.push({ id: `${mod}.${json.name}`, dir: path.join(dir, r), json, pseudo: fs.readFileSync(path.join(dir, r, 'routine.pseudo'), 'utf8') }); } } assert.ok(out.length > 0, 'no routines: is library/ checked out?'); return out; } test('library rule 6: every routine cites a paper by DOI, a book by edition and section, or a page by URL', () => { for (const r of routines()) { assert.ok(Array.isArray(r.json.sources) && r.json.sources.length, `${r.id} has no sources`); for (const s of r.json.sources) { const title = s.title || ''; assert.doesNotMatch(title, /^Any\b/, `${r.id}: "${title}" names no source`); const linked = typeof s.url === 'string' && /^https:\/\//.test(s.url); const book = /\b(sections?|formula|chapter)\b/i.test(title) && /\b(edition|ed\.)|\b(1[89]|20)\d\d\b/i.test(title); assert.ok(linked || book, `${r.id}: "${title}" has neither a URL nor an edition and section`); } } }); test('library rule 5: every tolerance has a note that says why', () => { for (const r of routines()) { for (const ref of r.json.references || []) { if (ref.rel === undefined && ref.abs === undefined) continue; assert.ok((ref.note || '').length > 40, `${r.id} ${ref.lang}/${ref.level} has a tolerance and no note that explains it`); } } }); test("library rule 4: a routine the prover leaves open says so in its comment", () => { const status = JSON.parse(fs.readFileSync(path.join(LIB, 'status.json'), 'utf8')).routines; const open = routines().filter((r) => status[r.id]?.checks?.prover?.status === 'open'); for (const r of open) { const comment = r.pseudo.split('\n').filter((l) => l.startsWith('//')).join(' '); assert.match(comment, /\bobligation\b[^.]*\bopen\b|\bopen\b[^.]*\bobligation\b/, `${r.id} is recorded open, and its comment does not say which obligation or why`); } }); /** British spellings, and words US English spells or uses differently. ("analyses" is left out: it is also the plural of analysis.) */ const BRITISH = /\b(behaviour|colour|favour|honour|labell(ed|ing)|modell(ed|ing)|travell(ed|ing)|cancell(ed|ing)|neighbour\w*|optimis\w*|memois\w*|normalis\w*|initialis\w*|serialis\w*|organis\w*|recognis\w*|minimis\w*|maximis\w*|summaris\w*|utilis\w*|realise[ds]?|analysed?|analysing|licence|centre|catalogue|grey|whilst|amongst|towards)\b/i; test("library rule 8 and core's: the documents and the routines' text are in US English", () => { const texts = DOCUMENTS.map((d) => [d, read(d)]); for (const r of routines()) { const j = r.json; texts.push([`${r.id} routine.json`, [j.summary, ...(j.tags || []), ...(j.references || []).map((x) => x.note), j.proof?.note].join('\n')]); texts.push([`${r.id} routine.pseudo`, r.pseudo.split('\n').filter((l) => l.trim().startsWith('//')).join('\n')]); } for (const mod of fs.readdirSync(path.join(LIB, 'modules'))) { const f = path.join(LIB, 'modules', mod, 'module.json'); if (fs.existsSync(f)) texts.push([`${mod}/module.json`, fs.readFileSync(f, 'utf8')]); } for (const [where, text] of texts) { const m = BRITISH.exec(text); assert.equal(m, null, `${where}: "${m?.[0]}"`); } }); test('the sources, the scripts, the tests and the regression programs are in US English too', () => { // what is written here, not what is generated, harvested or stored: a comment, a message a student reads and a // name in the code are all the project's own words const LEFT_OUT = [/^src\/mojo\/generated\//, /^src\/library\/generated\.ts$/, /^tests\/documents\.test\.mjs$/, /^tests\/snapshots\//, /^scripts\/mojo\/tests\/fixtures\//]; // words a student may write, which a reader has to know: not our prose const ALLOWED = { 'src/engines/pseudo/english.js': /initialise/g }; const files = []; const walk = (dir) => { for (const e of fs.readdirSync(dir, { withFileTypes: true })) { const f = path.join(dir, e.name); if (e.isDirectory()) { if (!['node_modules', '__pycache__'].includes(e.name)) walk(f); } else if (/\.(ts|js|mjs|py|sh|pseudo|lingo|speco|tex|md|toml|yml|mojo)$/.test(e.name)) files.push(f); } }; for (const d of ['src', 'scripts', 'tests', '.gitea', path.join('library', 'pseudo'), path.join('library', 'modules'), ...['local', 'probes', 'stress'].map((x) => path.join('library', 'mojo', x))]) if (fs.existsSync(d)) walk(d); assert.ok(files.length > 300, `${files.length} files read`); const found = []; for (const f of files) { const rel = f.split(path.sep).join('/'); if (LEFT_OUT.some((r) => r.test(rel))) continue; let text = fs.readFileSync(f, 'utf8'); if (ALLOWED[rel]) text = text.replace(ALLOWED[rel], ''); const m = BRITISH.exec(text); if (m) found.push(`${rel}: "${m[0]}"`); } assert.deepEqual(found, []); }); test('the Mojo corpus has a stored answer for every program but the compiler\'s opt-in diagnostic tests and those that do not run', () => { // what README.md and library/README.md say about godbolt's stored answers const items = JSON.parse(fs.readFileSync(path.join(LIB, 'mojo', 'golden', 'status.json'), 'utf8')).items; for (const it of items) { if (it.corpus === 'diagnostics') continue; assert.notEqual(it.verdict, 'unverified', `${it.id} has no stored answer`); if (it.verdict === 'skipped') assert.match(it.why, /no main/, `${it.id} is skipped: ${it.why}`); } }); test("docs/asm-coverage.md's table is today's assembly census", () => { const doc = read('docs/asm-coverage.md'); const now = (label) => { const m = new RegExp(`^\\| ${label} \\| [^|]* \\| ([^|]*) \\|$`, 'm').exec(doc); assert.ok(m, `no "${label}" row`); return m[1].trim(); }; const c = census(); assert.equal(now('distinct instructions in the listings'), String(c.ops.size)); assert.match(now("of which outside the model's set"), new RegExp(`^${c.missing.length} `)); assert.equal(now("the user's own functions that assemble"), `${c.userOk} of ${c.user}`); assert.equal(now('standard-library and runtime functions that assemble'), `${c.libOk} of ${c.lib}`); }); test('TypeScript is the only npm package, as README.md and AGENTS.md say', () => { const pkg = JSON.parse(read('package.json')); assert.equal(pkg.dependencies, undefined, 'package.json has runtime dependencies'); assert.deepEqual(Object.keys(pkg.devDependencies || {}), ['typescript']); }); test('no document sends a reader to a file git does not track (the owner\'s notes in work/)', () => { const tracked = (dir) => spawnSync('git', ['-C', dir, 'ls-files', '*.md'], { encoding: 'utf8' }).stdout.split('\n').filter(Boolean); const docs = [...tracked(CORE).filter((f) => !f.startsWith('library/')), ...tracked(LIB).map((f) => `library/${f}`)]; assert.ok(docs.length >= 20, `${docs.length} tracked documents`); for (const doc of docs) { for (const m of read(doc).matchAll(/`(work\/[^`\s]*\.md)`/g)) assert.fail(`${doc} names ${m[1]}, which is git-ignored and absent from a clone`); } }); test("docs/ci.md names every task `pixi run ci` runs, and mojo-corpus.md does not say CI leaves out the compiler's tasks", () => { const ci = /^ci = \{ depends-on = \[([^\]]*)\]/m.exec(read('pixi.toml')); assert.ok(ci, 'pixi.toml has no ci task with depends-on'); const tasks = [...ci[1].matchAll(/"([\w-]+)"/g)].map((m) => m[1]); assert.ok(tasks.includes('mojo-local'), 'the ci task no longer runs mojo-local: update docs/ci.md and docs/mojo-corpus.md'); const line = read('docs/ci.md').split('\n').find((l) => l.startsWith('`pixi run ci` is ')); assert.ok(line, 'docs/ci.md has no line that says what `pixi run ci` is'); for (const t of tasks) assert.ok(line.includes(`\`${t}\``), `docs/ci.md does not say that pixi run ci runs ${t}`); assert.doesNotMatch(read('docs/mojo-corpus.md'), /(?:not|never|neither) runs? in CI/, 'docs/mojo-corpus.md says a task of ci does not run in CI'); });