commit
401084bab3
265 files changed
+69224
No files matched your search
@@ -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');
|
||||
});
|
||||
Reference in new issue
Block a user