182 lines
13 KiB
JavaScript
182 lines
13 KiB
JavaScript
#!/usr/bin/env node
|
|
// SPDX-FileCopyrightText: 2026 Scientific Computing Studio, LLC
|
|
// SPDX-License-Identifier: Apache-2.0
|
|
// Check every program a Quarto site embeds with the extension's shortcodes ({{< pplus-run >}}, {{< pplus >}}, ...):
|
|
// the .lingo, .pseudo, .speco, .tex and .mojo files next to the pages, and the shortcodes that name them, run
|
|
// through this repository's own engines (build first: pixi run build).
|
|
//
|
|
// node scripts/check-pages.mjs /path/to/site/programmingplus [more folders ...]
|
|
//
|
|
// Set PPLUS_DIR to use another checkout's dist/ (and its core/dist/); set CHECK_FILES_ONLY=1 to only check that the files
|
|
// the shortcodes name exist (no engine needed).
|
|
//
|
|
// A program file may carry expectations in comment lines at the top:
|
|
// // CALL: COUNT_BASE('A', "GATTACA") the call to run (pseudo and lingo; otherwise the engine's default)
|
|
// // INPUT: 4000 a line INPUT reads (repeatable)
|
|
// // EXPECT: 3 a line of output, in order (repeatable; a Mojo file may write # expect-stdout:); the call's result
|
|
// counts as "<NAME> returned <value>"
|
|
// // ERRORS: 1 the program is meant to be refused with this many errors
|
|
// // STOPS: race the run is meant to stop with this kind of error (race, contract, bounds, ...)
|
|
// // QUESTION: range-ends lingo: the reader is meant to ask this question
|
|
// A lingo file is also lowered to pseudo, and that pseudo must check. A .tex file (LaTeX equations) uses
|
|
// % instead of // for its header lines, is translated to pseudo, and that pseudo must check and run.
|
|
// A .mojo file uses # for its header lines. It must be free of syntax the pinned Mojo removed (fn, read),
|
|
// and when a `mojo` compiler is on the PATH (inside pixi, which pins it) it is built and run for real:
|
|
// it must exit 0 and print its EXPECT lines, or, with ERRORS, fail to compile.
|
|
import fs from 'node:fs';
|
|
import path from 'node:path';
|
|
import { pathToFileURL } from 'node:url';
|
|
import { spawnSync } from 'node:child_process';
|
|
|
|
const here = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..');
|
|
const root = process.cwd();
|
|
const folders = process.argv.slice(2);
|
|
if (!folders.length) { console.error('usage: node scripts/check-pages.mjs <folder with .qmd pages> [...]'); process.exit(2); }
|
|
const pplusDir = process.env.CHECK_FILES_ONLY ? null : (process.env.PPLUS_DIR || here);
|
|
|
|
function walk(dir, out = []) {
|
|
for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
|
|
if (e.name.startsWith('_') || e.name.startsWith('.')) continue;
|
|
const p = path.join(dir, e.name);
|
|
if (e.isDirectory()) walk(p, out); else out.push(p);
|
|
}
|
|
return out;
|
|
}
|
|
|
|
// the live shortcodes' view= values (src/core/state.ts EMBED_VIEWS), and pplus-view's (src/quarto/render.ts
|
|
// STATIC_VIEWS), kept here so CHECK_FILES_ONLY needs no build; tests/quarto.test.mjs holds them to the app's
|
|
const EMBED_VIEWS = new Set(['playground', 'trace', 'table', 'flow', 'data', 'life', 'proof', 'tests', 'problems', 'compiler', 'asm', 'lingo', 'matho', 'pseudo', 'speco', 'mojo']);
|
|
const STATIC_VIEWS = new Set(['run', 'steps', 'table', 'flow', 'data', 'dataflow', 'life', 'lifetimes', 'proof', 'tests', 'check', 'translate', 'machine', 'hw']);
|
|
// the machine's views, pplus-hw-<view> (src/quarto/machine.ts HW_NAMES), also what pplus-hw's views= may name
|
|
const HW_VIEWS = ['code', 'explain', 'registers', 'flags', 'address', 'memory', 'stack', 'dataflow', 'alu', 'branches', 'vectors', 'lines', 'cache', 'hierarchy', 'paging', 'pipeline', 'uops', 'timeline', 'bottleneck', 'counters', 'chip', 'core', 'encoding'];
|
|
// every shortcode of the extension (src/quarto/shortcodes.ts SHORTCODE_NAMES)
|
|
const SHORTCODES = new Set(['pplus', 'pplus-embed', 'pplus-playground', 'pplus-view', 'pplus-run', 'pplus-steps', 'pplus-table', 'pplus-flow', 'pplus-dataflow', 'pplus-lifetimes', 'pplus-proof', 'pplus-tests', 'pplus-check', 'pplus-translate', 'pplus-machine', 'pplus-hw', ...HW_VIEWS.map((v) => `pplus-hw-${v}`), 'pplus-listing', 'pplus-tabs', 'pplus-link']);
|
|
|
|
const files = folders.flatMap((f) => walk(path.resolve(root, f)));
|
|
const pages = files.filter((f) => f.endsWith('.qmd'));
|
|
const programs = files.filter((f) => /\.(lingo|pseudo|speco|tex|mojo)$/.test(f));
|
|
let failures = 0;
|
|
const fail = (where, msg) => { failures++; console.log(`✗ ${path.relative(root, where)}: ${msg}`); };
|
|
|
|
// 1. shortcodes name files that exist
|
|
const referenced = new Set();
|
|
for (const page of pages) {
|
|
const text = fs.readFileSync(page, 'utf8');
|
|
// {{< pplus-name ... >}}, but not an escaped {{{< ... >}}} (a page showing the shortcode as text)
|
|
for (const m of text.matchAll(/(?<!\{)\{\{<\s*(pplus(?:-[a-z]+)*)(\s+[^>]*)?>\}\}(?!\})/g)) {
|
|
const name = m[1], args = m[2] ?? '';
|
|
if (!SHORTCODES.has(name)) { fail(page, `{{< ${name} >}} is not a shortcode of the extension; they are ${[...SHORTCODES].join(', ')}`); continue; }
|
|
const view = /\bview="([^"]+)"/.exec(args)?.[1];
|
|
const views = name === 'pplus-view' ? STATIC_VIEWS : name === 'pplus-hw' ? new Set(HW_VIEWS) : EMBED_VIEWS;
|
|
if (view && !name.startsWith('pplus-hw-') && !views.has(view)) fail(page, `{{< ${name} >}} has view="${view}"; the views are ${[...views].join(', ')}`);
|
|
for (const v of (/\bviews="([^"]+)"/.exec(args)?.[1] ?? '').split(/[\s,]+/).filter(Boolean)) if (!HW_VIEWS.includes(v)) fail(page, `{{< ${name} >}} names the machine view "${v}"; the views are ${HW_VIEWS.join(', ')}`);
|
|
for (const a of args.matchAll(/\b(lingo|matho|pseudo|speco|mojo|asm|setup)="([^"]+)"/g)) {
|
|
const f = path.join(path.dirname(page), a[2]);
|
|
if (!fs.existsSync(f)) fail(page, `{{< ${name} >}} names ${a[2]}, which does not exist`);
|
|
else referenced.add(f);
|
|
}
|
|
}
|
|
}
|
|
for (const p of programs) if (!referenced.has(p) && !/\.(speco)$/.test(p)) console.log(` (note) ${path.relative(root, p)} is not embedded by any page`);
|
|
|
|
if (!pplusDir) {
|
|
console.log(`check-pages: ${programs.length} program files, ${failures} problems (files only; unset CHECK_FILES_ONLY to run them)`);
|
|
process.exit(failures ? 1 : 0);
|
|
}
|
|
|
|
// 2. every program parses, runs, and prints what it says
|
|
const dist = path.join(pplusDir, 'dist');
|
|
const coreDist = path.join(pplusDir, 'core', 'dist'); // pplus-core, built beside the app
|
|
const { studyOf, runPseudo } = await import(pathToFileURL(path.join(coreDist, 'services/pseudo.js')));
|
|
const { removedSyntax } = await import(pathToFileURL(path.join(coreDist, 'mojo/check.js')));
|
|
const { MOJO_VERSION } = await import(pathToFileURL(path.join(coreDist, 'mojo/generated/pin.js')));
|
|
// a Mojo file is run as Programming+ builds everywhere: the pin's arguments (core's mojoBuildArgs), without the
|
|
// x86-64 target on a machine that is not one
|
|
const { mojoBuildArgs } = await import(pathToFileURL(path.join(coreDist, 'services/godbolt.js')));
|
|
const MOJO_RUN_ARGS = mojoBuildArgs('', { x86_64: process.arch === 'x64' }).split(/\s+/).filter(Boolean);
|
|
const mojoVersion = (() => { const r = spawnSync('mojo', ['--version'], { encoding: 'utf8' }); return r.status === 0 ? r.stdout.trim() : null; })();
|
|
if (programs.some((f) => f.endsWith('.mojo'))) {
|
|
if (!mojoVersion) console.log(' (note) no mojo compiler on the PATH: .mojo files are checked for removed syntax only. Run inside pixi to build and run them.');
|
|
else if (!mojoVersion.includes(MOJO_VERSION)) console.log(` (warning) ${mojoVersion} is not the pinned Mojo ${MOJO_VERSION}; results may not match the site`);
|
|
}
|
|
const { readLingo, lowerLingo, runLingo } = await import(pathToFileURL(path.join(coreDist, 'services/lingo.js')));
|
|
const { parseMatho, lowerMatho, runMatho } = await import(pathToFileURL(path.join(coreDist, 'services/matho.js')));
|
|
|
|
function header(text) {
|
|
const h = { expect: [], input: [], questions: [], stops: null };
|
|
for (const line of text.split('\n')) {
|
|
const m = /^\s*(?:\/\/|%|#)\s*(CALL|INPUT|EXPECT|ERRORS|QUESTION|STOPS|expect-stdout):\s?(.*)$/.exec(line);
|
|
if (!m) continue;
|
|
if (m[1] === 'CALL') h.call = m[2].trim();
|
|
else if (m[1] === 'INPUT') h.input.push(m[2]);
|
|
else if (m[1] === 'EXPECT' || m[1] === 'expect-stdout') h.expect.push(m[2]);
|
|
else if (m[1] === 'ERRORS') h.errors = Number(m[2]);
|
|
else if (m[1] === 'QUESTION') h.questions.push(m[2].trim());
|
|
else if (m[1] === 'STOPS') h.stops = m[2].trim();
|
|
}
|
|
return h;
|
|
}
|
|
|
|
function checkRun(file, tr, h) {
|
|
if (h.stops) { if (!tr.error) fail(file, `was meant to stop with a ${h.stops} error and ran to the end`); else if (tr.error.kind !== h.stops) fail(file, `was meant to stop with a ${h.stops} error and stopped with ${tr.error.kind}: ${tr.error.message}`); return; }
|
|
if (tr.error) { fail(file, `stopped: ${tr.error.message}`); return; }
|
|
if (h.expect.length) {
|
|
const got = tr.output;
|
|
const want = h.expect;
|
|
if (JSON.stringify(got) !== JSON.stringify(want)) fail(file, `printed ${JSON.stringify(got)}, expected ${JSON.stringify(want)}`);
|
|
}
|
|
}
|
|
|
|
for (const file of programs) {
|
|
const text = fs.readFileSync(file, 'utf8');
|
|
const h = header(text);
|
|
if (file.endsWith('.pseudo')) {
|
|
const st = studyOf(text);
|
|
const errs = st.diagnostics.filter((d) => d.severity === 'error');
|
|
if (h.errors !== undefined) { if (errs.length !== h.errors) fail(file, `expected ${h.errors} errors, got ${errs.length}: ${errs.map((d) => `L${d.line} ${d.id}`).join(', ')}`); continue; }
|
|
if (errs.length) { fail(file, errs.map((d) => `L${d.line} ${d.id}: ${d.message}`).join(' | ')); continue; }
|
|
if (h.expect.length || h.call) checkRun(file, runPseudo(st, { call: h.call ?? null, input: h.input, maxSteps: 200000 }), h);
|
|
} else if (file.endsWith('.tex')) {
|
|
const r = parseMatho(text);
|
|
const errs = r.diagnostics.filter((d) => d.severity === 'error');
|
|
if (h.errors !== undefined) { if (errs.length !== h.errors) fail(file, `expected ${h.errors} errors, got ${errs.length}: ${errs.map((d) => `L${d.line} ${d.id}`).join(', ')}`); continue; }
|
|
if (errs.length) { fail(file, errs.map((d) => `L${d.line} ${d.id}: ${d.message}`).join(' | ')); continue; }
|
|
const low = lowerMatho(r, 'pseudo');
|
|
if (!low) { fail(file, 'does not translate to pseudo'); continue; }
|
|
if (h.expect.length || h.call) {
|
|
try { checkRun(file, runMatho(r, { call: h.call ?? null, input: h.input, maxSteps: 200000 }), h); }
|
|
catch (e) { fail(file, `run failed: ${e.message}`); }
|
|
}
|
|
} else if (file.endsWith('.mojo')) {
|
|
const removed = removedSyntax(text);
|
|
if (removed.length && h.errors == null) { fail(file, removed.map((d) => `L${d.line} ${d.message}`).join(' | ')); continue; }
|
|
if (!mojoVersion) continue;
|
|
const r = spawnSync('mojo', ['run', ...MOJO_RUN_ARGS, file], { input: h.input.map((l) => l + '\n').join(''), encoding: 'utf8', timeout: 120000 });
|
|
if (h.errors != null) { if (r.status === 0) fail(file, 'was meant to fail to compile, and ran'); continue; }
|
|
if (r.status !== 0) { fail(file, `mojo run exited ${r.status ?? r.signal}: ${(r.stderr || '').trim().split('\n').slice(0, 4).join(' | ')}`); continue; }
|
|
if (h.expect.length) {
|
|
const got = r.stdout.replace(/\n$/, '').split('\n');
|
|
if (JSON.stringify(got) !== JSON.stringify(h.expect)) fail(file, `printed ${JSON.stringify(got)}, expected ${JSON.stringify(h.expect)}`);
|
|
}
|
|
} else if (file.endsWith('.lingo')) {
|
|
const r = readLingo(text);
|
|
const errs = r.diagnostics.filter((d) => d.severity === 'error');
|
|
if (h.questions.length) {
|
|
for (const q of h.questions) if (!r.diagnostics.some((d) => d.id === q)) fail(file, `the reader did not ask "${q}" (asked: ${r.diagnostics.map((d) => d.id).join(', ') || 'nothing'})`);
|
|
continue;
|
|
}
|
|
if (errs.length) { fail(file, errs.map((d) => `L${d.line} ${d.id}: ${d.message}`).join(' | ')); continue; }
|
|
const low = lowerLingo(r, 'pseudo');
|
|
if (!low) { fail(file, 'does not lower to pseudo'); continue; }
|
|
const st = studyOf(low.source);
|
|
const perrs = st.diagnostics.filter((d) => d.severity === 'error');
|
|
if (perrs.length) { fail(file, 'lowered pseudo has errors: ' + perrs.map((d) => `L${d.line} ${d.message}`).join(' | ')); continue; }
|
|
if (h.expect.length || h.call) {
|
|
try { checkRun(file, runLingo(r, { call: h.call ?? null, input: h.input, maxSteps: 200000 }), h); }
|
|
catch (e) { fail(file, `run failed: ${e.message}`); }
|
|
}
|
|
}
|
|
}
|
|
console.log(`check-pages: ${programs.length} program files, ${failures} problems`);
|
|
process.exit(failures ? 1 : 0);
|