Initial commit
Test / gate (push) Failing after 19m0s

This commit is contained in:
alexm committed 2026-11-12 22:23:54 -05:00
commit 401084bab3
265 files changed
+69224

No files matched your search

+240
View File
@@ -0,0 +1,240 @@
// 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(`(?<![\\w./-])${name}(?![\\w/-])`, 'i').exec(text);
if (!m) continue;
const after = text.slice(m.index + name.length, m.index + name.length + gloss.length + 8).replace(/^[\s:(]+/, '');
assert.ok(after.startsWith(gloss), `${doc}: the first "${name}" is not followed by its gloss "${gloss}" but by "${after}"`);
}
}
});
test('the two README files list the five notations in the same words', () => {
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');
});