Initial commit
Build, test, deploy / site (push) Failing after 15m13s

This commit is contained in:
alexm committed 2026-11-12 22:24:02 -05:00
commit e092cb029c
252 files changed
+35037

No files matched your search

+69
View File
@@ -0,0 +1,69 @@
#!/usr/bin/env node
// SPDX-FileCopyrightText: 2026 Scientific Computing Studio, LLC
// SPDX-License-Identifier: Apache-2.0
// The assembled site's index.html, from the one in the repository: scripts/assemble.sh runs this on site/.
// node scripts/assemble-page.mjs <site-dir>
// It adds two things a checkout served as it is (pixi run dev) does without:
// - <meta name="pplus-version">, the commit in site/VERSION, which the footer shows (no request needed);
// - a <link rel="modulepreload"> for every module the page's static import graph reaches. Without a bundler the
// browser finds the modules one level of imports at a time, so a first visit waits for a chain of round trips
// (six levels today); with the list it asks for them all at once. The links go after the import map, which a
// browser must have read before it loads any module.
// Nothing else in the page changes, so the hashes of its inline scripts (docs/Caddyfile's CSP) still hold.
import { readFileSync, writeFileSync, existsSync } from 'node:fs';
import { resolve, dirname, relative, join } from 'node:path';
import { fileURLToPath } from 'node:url';
const IMPORT = /(?:^|[;\n}])\s*(?:import|export)\s*(?:[\w*{}\s,$]*?\sfrom\s*)?['"]([^'"]+)['"]/g;
/**
* Every module the page's entry imports, directly or through others, as hrefs relative to the page ('./dist/…',
* './core/dist/…'), shallowest first; the entry itself is not listed (its own <script> loads it).
* @param {string} root the directory that holds index.html, dist/ and core/dist/
* @param {string} [entry] the entry module, relative to root
* @returns {string[]}
*/
export function modulePreloads(root, entry = 'dist/main.js') {
const coreDist = resolve(root, 'core/dist');
const target = (from, spec) => spec.startsWith('#core/') ? join(coreDist, spec.slice('#core/'.length)) : spec.startsWith('.') ? resolve(dirname(from), spec) : null;
const start = resolve(root, entry);
const depth = new Map([[start, 0]]);
const queue = [start];
while (queue.length) {
const file = queue.shift();
const src = readFileSync(file, 'utf8');
for (const m of src.matchAll(IMPORT)) {
const t = target(file, m[1]);
if (!t || depth.has(t)) continue;
if (!existsSync(t)) throw new Error(`${relative(root, file)} imports ${m[1]}, which is not in ${root}`);
depth.set(t, depth.get(file) + 1);
queue.push(t);
}
}
return [...depth].filter(([f]) => f !== start).sort((a, b) => a[1] - b[1] || (a[0] < b[0] ? -1 : 1)).map(([f]) => `./${relative(root, f).split('\\').join('/')}`);
}
/**
* The page with the version and the preloads in it.
* @param {string} html index.html as the repository has it
* @param {{ version?: string | null, preloads?: string[] }} parts
* @returns {string}
*/
export function assemblePage(html, { version = null, preloads = [] } = {}) {
let out = html;
if (version && /^[0-9a-f]{7,40}$/.test(version)) out = out.replace(/\n<\/head>/, `\n <meta name="pplus-version" content="${version}">\n</head>`);
const map = /<script type="importmap">[^<]*<\/script>\n/.exec(out);
if (!map) throw new Error('index.html has no import map: the preloads go after it');
const links = preloads.map((h) => ` <link rel="modulepreload" href="${h}">\n`).join('');
return out.slice(0, map.index + map[0].length) + links + out.slice(map.index + map[0].length);
}
if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
const site = resolve(process.argv[2] ?? 'site');
const page = join(site, 'index.html');
const versionFile = join(site, 'VERSION');
const version = existsSync(versionFile) ? readFileSync(versionFile, 'utf8').trim() : null;
const preloads = modulePreloads(site);
writeFileSync(page, assemblePage(readFileSync(page, 'utf8'), { version, preloads }));
console.log(`index.html: ${preloads.length} module preloads${version ? `, version ${version.slice(0, 12)}` : ''}`);
}
+27
View File
@@ -0,0 +1,27 @@
#!/usr/bin/env sh
# SPDX-FileCopyrightText: 2026 Scientific Computing Studio, LLC
# SPDX-License-Identifier: Apache-2.0
# Assemble the deployable site into ./site: what a static host needs (the page, its styles and fonts, dist/, pplus-core's
# core/dist/ that the page's import map points at, and the Quarto extension).
set -eu
cd "$(dirname "$0")/.."
rm -rf site && mkdir -p site
cp -r index.html styles.css styles fonts dist site/
rm -f site/styles/course/README.md # the provenance notes stay in the repository (the fonts' LICENSE.txt goes with them)
# the license and the third-party notices go with the files they cover (CodeMirror's MIT notices among them)
cp LICENSE.md NOTICE.md THIRD_PARTY.md site/
# pplus-core's built modules, without source maps, declarations, or the lesson corpus (a test fixture)
mkdir -p site/core
cp -r core/dist site/core/
find site/core/dist \( -name '*.map' -o -name '*.d.ts' \) -delete
rm -rf site/core/dist/curriculum
# the Quarto extension, which the "With Quarto" page loads (pplus.css, pplus.js) and links to, file by file
mkdir -p site/quarto/_extensions
cp -r quarto/_extensions/pplus site/quarto/_extensions/
rm -rf site/quarto/_extensions/pplus/engine
printf '%s\n' "${GITHUB_SHA:-$(git rev-parse HEAD 2>/dev/null || echo dev)}" > site/VERSION
# the three commits it was built from (web, core, library), their versions and the pinned Mojo (scripts/build-info.mjs)
node scripts/build-info.mjs > site/build.json
# the page names the commit (the footer shows it) and preloads every module its imports reach (scripts/assemble-page.mjs)
node scripts/assemble-page.mjs site
echo "site/ assembled ($(du -sh site | cut -f1))"
+46
View File
@@ -0,0 +1,46 @@
#!/usr/bin/env node
// SPDX-FileCopyrightText: 2026 Scientific Computing Studio, LLC
// SPDX-License-Identifier: Apache-2.0
/**
* What a built site is made of, as JSON: the version and commit of each of the three repositories, and the Mojo the
* corpus is pinned to. scripts/assemble.sh writes it to site/build.json beside VERSION (which stays the site's own
* commit, for the deploy's smoke test), so the live site can say exactly which commits it was built from.
*
* node scripts/build-info.mjs print it
*
* A version is the one package.json states (pplus-library has none: its commit is its version); `describe` is
* `git describe --tags --always --dirty`, so a tagged release reads as its tag and a change not yet committed says
* so. Outside a git checkout a commit is null. GITHUB_SHA, when CI sets it, is the site's commit.
*/
import fs from 'node:fs';
import path from 'node:path';
import { spawnSync } from 'node:child_process';
import { fileURLToPath } from 'node:url';
const WEB = fileURLToPath(new URL('..', import.meta.url));
function git(dir, ...args) {
const r = spawnSync('git', ['-C', dir, ...args], { encoding: 'utf8' });
return r.status === 0 ? r.stdout.trim() : null;
}
const version = (dir) => { try { return JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')).version ?? null; } catch { return null; } };
/** One repository's entry. */
function repo(dir, name) {
return { name, version: version(dir), commit: git(dir, 'rev-parse', 'HEAD'), describe: git(dir, 'describe', '--tags', '--always', '--dirty') };
}
/** The build's description: web, core and library, and the pinned Mojo. */
export function buildInfo(web = WEB) {
const core = path.join(web, 'core');
const lib = path.join(core, 'library');
const site = repo(web, 'pplus-web');
if (process.env.GITHUB_SHA && !site.commit) site.commit = process.env.GITHUB_SHA;
let mojo = null;
try { mojo = JSON.parse(fs.readFileSync(path.join(lib, 'mojo', 'pin.json'), 'utf8')).mojo.version; } catch { /* no library checked out */ }
return { web: site, core: repo(core, 'pplus-core'), library: repo(lib, 'pplus-library'), mojo };
}
if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
process.stdout.write(`${JSON.stringify(buildInfo(), null, 2)}\n`);
}
+75
View File
@@ -0,0 +1,75 @@
// SPDX-FileCopyrightText: 2026 Scientific Computing Studio, LLC
// SPDX-License-Identifier: Apache-2.0
// Serve an assembled site/ with a real Caddy under docs/Caddyfile's own rules, and hold what it answers: the
// security headers on every answer, what a browser may keep, and where a path that is not a file goes. The tests
// read the Caddyfile as text (tests/csp.test.mjs); only Caddy says what it does with it.
//
// pixi run caddy-check assemble site/ first (pixi run site), then this
//
// Caddy comes from `pixi exec` (conda-forge), so the first run needs the network; nothing else does. The site block
// is the document's own, with two lines changed: the host (localhost, plain HTTP) and the root (./site).
import { spawn } from 'node:child_process';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
const PORT = Number(process.env.CADDY_CHECK_PORT || 8767);
const base = `http://127.0.0.1:${PORT}`;
if (!fs.existsSync('site/index.html')) { console.error('site/ is not assembled: run `pixi run site` (or scripts/assemble.sh) first'); process.exit(2); }
const doc = fs.readFileSync('docs/Caddyfile', 'utf8');
const host = /^[a-z0-9.-]+\.[a-z]+ \{$/m.exec(doc);
if (!host || !doc.includes('root * /srv/www/pplus')) { console.error('docs/Caddyfile no longer has the site block this script rewrites'); process.exit(2); }
const local = `{\n admin off\n auto_https off\n}\n${doc.replace(host[0], `http://127.0.0.1:${PORT} {`).replace('root * /srv/www/pplus', `root * ${path.resolve('site')}`)}`;
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pplus-caddy-'));
const file = path.join(dir, 'Caddyfile');
fs.writeFileSync(file, local);
const caddy = spawn('pixi', ['exec', '-s', 'caddy>=2.8', '--', 'caddy', 'run', '--config', file, '--adapter', 'caddyfile'], { stdio: ['ignore', 'ignore', 'pipe'] });
let log = '';
caddy.stderr.on('data', (d) => { log += d; });
const stop = () => { try { caddy.kill('SIGTERM'); } catch { /* already gone */ } fs.rmSync(dir, { recursive: true, force: true }); };
process.on('exit', stop);
const get = (p, headers = {}) => fetch(base + p, { redirect: 'manual', headers });
let up = false;
for (let i = 0; i < 120 && !up; i++) { try { await get('/VERSION'); up = true; } catch { await new Promise((r) => setTimeout(r, 500)); } }
if (!up) { console.error(`Caddy did not start:\n${log.slice(-2000)}`); process.exit(2); }
const problems = [];
const SECURITY = ['content-security-policy', 'referrer-policy', 'x-content-type-options', 'permissions-policy'];
/** One request, held to a status and to headers (a string must equal; a RegExp must match; null must be absent). */
async function check(what, p, status, want = {}, reqHeaders = {}) {
const r = await get(p, reqHeaders);
await r.arrayBuffer();
if (r.status !== status) problems.push(`${what}: ${p} answered ${r.status}, not ${status}`);
for (const h of SECURITY) if (!r.headers.get(h)) problems.push(`${what}: ${p} has no ${h}`);
for (const [h, v] of Object.entries(want)) {
const got = r.headers.get(h);
const ok = v === null ? got === null : v instanceof RegExp ? v.test(got ?? '') : got === v;
if (!ok) problems.push(`${what}: ${p} has ${h}: ${got}, not ${v}`);
}
return r;
}
const font = fs.readdirSync('site/fonts').find((f) => f.endsWith('.woff2'));
const page = await check('the page', '/', 200, { 'cache-control': 'no-cache', 'content-type': /^text\/html/, etag: /./ });
await check('the page by name', '/index.html', 200, { 'cache-control': 'no-cache' });
const js = await check('a module', '/dist/main.js', 200, { 'cache-control': 'no-cache', 'content-type': /javascript/, etag: /./ });
await check('a module, unchanged', '/dist/main.js', 304, { 'cache-control': 'no-cache' }, { 'if-none-match': js.headers.get('etag') });
await check('a module of core', '/core/dist/services/pseudo.js', 200, { 'cache-control': 'no-cache' });
await check('the stylesheet', '/styles.css', 200, { 'cache-control': 'no-cache', 'content-type': /^text\/css/ });
await check('a font', `/fonts/${font}`, 200, { 'cache-control': 'public, max-age=2592000', 'content-type': 'font/woff2' });
await check('VERSION', '/VERSION', 200, { 'cache-control': 'no-store' });
await check('build.json', '/build.json', 200, { 'cache-control': 'no-cache', 'content-type': /json/ });
for (const f of ['LICENSE.md', 'NOTICE.md', 'THIRD_PARTY.md']) await check('a notice', `/${f}`, 200, { 'content-type': 'text/plain; charset=utf-8' });
// a path that is not a file: a page goes to /, a file is a plain 404, and neither is kept
for (const p of ['/no/such/page', '/bridge', '/old/link?x=1']) await check('a missing page', p, 302, { location: '/', 'cache-control': 'no-store' });
for (const p of ['/dist/gone.js', '/fonts/gone.woff2', '/styles/gone.css']) await check('a missing file', p, 404, { 'cache-control': 'no-store', 'content-type': /^text\/plain/ });
// the CSP the server sends is the one the tests hold to index.html's inline scripts
const csp = page.headers.get('content-security-policy') ?? '';
for (const part of ["default-src 'self'", "frame-ancestors", 'https://godbolt.org']) if (!csp.includes(part)) problems.push(`the CSP Caddy sends has no ${part}`);
stop();
if (problems.length) { console.error(problems.join('\n')); console.error(`\n${problems.length} thing(s) wrong`); process.exit(1); }
console.log(`Caddy serves site/ as docs/Caddyfile says: security headers on every answer, caching per kind of file, a missing page sent to /, a missing file a plain 404`);
process.exit(0);
+181
View File
@@ -0,0 +1,181 @@
#!/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);
+57
View File
@@ -0,0 +1,57 @@
#!/usr/bin/env bash
# SPDX-FileCopyrightText: 2026 Scientific Computing Studio, LLC
# SPDX-License-Identifier: Apache-2.0
# Publish ./site to /srv/www/<slug> as an atomic release (DEPLOY_ROOT overrides /srv/www).
#
# scripts/deploy.sh <slug> [host]
#
# Without a host, the script runs on the server itself (the Gitea runner lives
# on the droplet). With a host (user@droplet), it rsyncs over SSH. Either way
# the layout on the server is:
#
# /srv/www/<slug> -> symlink to the live release
# /srv/www/<slug>.releases/ one directory per deployed commit, last 5 kept
#
# The symlink swap is one rename, so visitors never see a half-copied site, and
# rolling back is `ln -sfn /srv/www/<slug>.releases/<sha> /srv/www/<slug>`.
set -euo pipefail
slug="${1:?usage: deploy.sh <slug> [user@host]}"
host="${2:-}"
sha="${GITHUB_SHA:-$(git rev-parse HEAD 2>/dev/null || date +%s)}"
root="${DEPLOY_ROOT:-/srv/www}"
releases="$root/$slug.releases"
release="$releases/${sha:0:12}"
live="$root/$slug"
[ -f site/index.html ] || { echo "site/ is missing; run scripts/assemble.sh first" >&2; exit 1; }
# Everything that touches the server, as one script, so the SSH path and the local path stay identical.
remote_script=$(cat <<EOS
set -euo pipefail
mkdir -p "$releases"
rm -rf "$release.tmp"
mv "$release.incoming" "$release.tmp"
# a rebuilt commit replaces its earlier release
rm -rf "$release"
mv "$release.tmp" "$release"
# a plain directory from before releases existed is kept aside, once
if [ -d "$live" ] && [ ! -L "$live" ]; then mv "$live" "$releases/before-releases"; fi
# swap in one rename
ln -sfn "$release" "$live.next"
mv -Tf "$live.next" "$live"
# keep the five newest releases
ls -1dt "$releases"/*/ 2>/dev/null | tail -n +6 | xargs -r rm -rf
echo "live: $live -> \$(readlink "$live")"
EOS
)
if [ -z "$host" ]; then
mkdir -p "$releases"
rm -rf "$release.incoming"
if command -v rsync >/dev/null; then rsync -a --delete site/ "$release.incoming/"; else cp -a site "$release.incoming"; fi
bash -c "$remote_script"
else
ssh -o BatchMode=yes "$host" "mkdir -p '$releases'"
rsync -a --delete -e "ssh -o BatchMode=yes" site/ "$host:$release.incoming/"
ssh -o BatchMode=yes "$host" "$remote_script"
fi
+51
View File
@@ -0,0 +1,51 @@
#!/usr/bin/env python3
# SPDX-FileCopyrightText: 2026 Scientific Computing Studio, LLC
# SPDX-License-Identifier: Apache-2.0
"""Zip the repository for sharing: the files git tracks, plus new files it does not ignore.
pixi run package # writes package/programming-plus-<commit>.zip
pplus-core (the core/ submodule, with its own submodule library/) goes in as its checkouts track it. Nothing git ignores goes in: no .DS_Store, __pycache__, scratch/, dist/, site/, node_modules/ or
.pixi/. Files are stored under a top folder named programming-plus/, as the shared zips were.
Standard library only, like the corpus pipeline.
"""
import pathlib
import subprocess
import sys
import zipfile
ROOT = pathlib.Path(__file__).resolve().parent.parent
def git(*args: str) -> str:
return subprocess.run(["git", *args], cwd=ROOT, check=True, capture_output=True, text=True).stdout
def main() -> int:
try:
commit = git("rev-parse", "--short", "HEAD").strip()
except (subprocess.CalledProcessError, FileNotFoundError):
print("package: this needs a git checkout (git init and commit first)", file=sys.stderr)
return 1
dirty = bool(git("status", "--porcelain").strip())
names = sorted(set(git("ls-files", "-z", "--cached", "--others", "--exclude-standard").split("\0")) - {""})
# pplus-core (core/) is a submodule: take the files its checkout tracks, so the zip builds on its own.
subs = git("config", "-f", ".gitmodules", "--get-regexp", r"\.path$").split() if (ROOT / ".gitmodules").exists() else []
for sub in subs[1::2]:
if (ROOT / sub / ".git").exists():
tracked = subprocess.run(["git", "ls-files", "-z", "--recurse-submodules"], cwd=ROOT / sub, check=True, capture_output=True, text=True).stdout
names += [f"{sub}/{n}" for n in tracked.split("\0") if n]
names = sorted(n for n in set(names) if (ROOT / n).is_file())
out_dir = ROOT / "package"
out_dir.mkdir(exist_ok=True)
out = out_dir / f"programming-plus-{commit}{'-dirty' if dirty else ''}.zip"
with zipfile.ZipFile(out, "w", compression=zipfile.ZIP_DEFLATED) as z:
for n in names:
z.write(ROOT / n, f"programming-plus/{n}")
size = out.stat().st_size / 1e6
print(f"wrote {out.relative_to(ROOT)}: {len(names)} files, {size:.1f} MB{' (with uncommitted changes)' if dirty else ''}")
return 0
if __name__ == "__main__":
sys.exit(main())
+163
View File
@@ -0,0 +1,163 @@
#!/usr/bin/env node
// SPDX-FileCopyrightText: 2026 Scientific Computing Studio, LLC
// SPDX-License-Identifier: Apache-2.0
/**
* Write quarto/_extensions/pplus/pplus-views.css: the app's own rules for what the static views draw, so a Quarto
* page shows the flowchart, the table of values, the proof and the rest exactly as the app does.
*
* pixi run quarto-css (build first; `pixi run test` fails while the file is out of date)
*
* It renders every static view of a few catalog problems (src/quarto/render.ts, as `quarto render` would), collects
* the classes they use, and copies from styles.css every rule whose selectors use only those classes, each selector
* scoped under `.pplus-static`. The app's color tokens come along: light by default, dark when the Quarto page is
* dark (`body.quarto-dark`, or Bootstrap's `data-bs-theme="dark"`); the paper and ink follow the page's own.
*
* It also copies the course's stylesheets for the machine views (course/*.css), writes pplus-hw.css from
* styles/course/bridge.css, and copies pplus-core's KDE syntax for Mojo (core/library/syntax/mojo.xml, which core's corpus
* pipeline writes) to syntax/mojo.xml, for the listings Pandoc highlights.
*
* node scripts/quarto-css.mjs --check exit 1 if a file is not what this would write
*/
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';
const ROOT = fileURLToPath(new URL('..', import.meta.url));
const OUT = path.join(ROOT, 'quarto/_extensions/pplus/pplus-views.css');
const dist = (p) => pathToFileURL(path.join(ROOT, 'dist', p)).href;
if (!fs.existsSync(path.join(ROOT, 'dist/quarto/render.js'))) { console.error('quarto-css: dist/ is missing; run `pixi run build` first'); process.exit(1); }
const { installDocument } = await import(dist('quarto/dom.js'));
installDocument();
const { renderStatic, STATIC_VIEWS } = await import(dist('quarto/render.js'));
const { problemById } = await import(dist('core/catalog.js'));
/* ---------- the classes the views use ---------- */
const samples = [];
for (const id of ['count-base', 'count-base-proved', 'match-off-by-one', 'five-bugs', 'binary-search', 'asm-two-pointers', 'demo']) {
const p = problemById(id);
const files = Object.fromEntries(Object.entries(p.sources).filter(([, v]) => typeof v === 'string' && v.trim()));
for (const lang of Object.keys(files)) samples.push({ files, lang, call: p.call ?? null, setup: p.setup, machine: p.machine });
}
samples.push({ files: { mojo: fs.readFileSync(path.join(ROOT, 'core/library/mojo/stress/lifecycle-moves.mojo'), 'utf8') }, lang: 'mojo' });
const used = new Set();
for (const s of samples) for (const view of STATIC_VIEWS.filter((v) => v !== 'hw')) {
let html = '';
try { html = renderStatic({ ...s, view }).html; } catch { continue; }
for (const m of html.matchAll(/class="([^"]*)"/g)) for (const c of m[1].split(/\s+/)) if (c) used.add(c);
}
// the editor's token colors and the step colors, whichever a sample happened to show
for (const c of ['tok-keyword', 'tok-builtin', 'tok-string', 'tok-number', 'tok-comment', 'tok-label', 'tok-op', 'tok-error', 'tok-punct', 'tok-convention', 'tok-transfer', 'tok-name']) used.add(c);
/* ---------- styles.css as rules ---------- */
/** Top-level rules and @media blocks: { selector, body } or { media, rules }. Comments are dropped. */
function parse(css) {
css = css.replace(/\/\*[\s\S]*?\*\//g, '');
const out = [];
let i = 0;
const block = (from) => { let depth = 0; for (let k = from; k < css.length; k++) { if (css[k] === '{') depth++; else if (css[k] === '}' && --depth === 0) return k; } return css.length; };
while (i < css.length) {
const open = css.indexOf('{', i);
if (open < 0) break;
const prelude = css.slice(i, open).trim();
const close = block(open);
const body = css.slice(open + 1, close);
if (prelude.startsWith('@media')) out.push({ media: prelude, rules: parse(body) });
else if (!prelude.startsWith('@')) out.push({ selector: prelude, body: body.trim() });
i = close + 1;
}
return out;
}
const tokens = { light: new Map(), dark: new Map() };
const LIGHT = /^:root$/, DARK = /^:root\[data-theme="dark"\]$/;
const SKIP_TOKENS = new Set(['--paper', '--paper-2', '--paper-3', '--ink', '--ink-2', '--ink-3', '--line', '--line-2', '--mono', '--sans', 'color-scheme']);
/** A selector the static views can use: every class in it is one they emit, and nothing in it names the app's page. */
function keep(sel) {
if (/(^|[\s>+~(,])(html|body|:root)\b/.test(sel) || /\[data-theme|\.is-embed|\.shell|\.home|::?-webkit|:hover|:focus|:active/.test(sel)) return false;
const classes = [...sel.matchAll(/\.([\w-]+)/g)].map((m) => m[1]);
if (!classes.length) return false;
return classes.every((c) => used.has(c));
}
function scoped(rules, indent = '') {
const lines = [];
for (const r of rules) {
if (r.media) {
// the app's narrow-screen rearrangements are for its workspace; a page keeps the view's own layout
continue;
}
const sels = r.selector.split(',').map((s) => s.trim());
if (sels.length === 1 && LIGHT.test(sels[0])) { collect(r.body, tokens.light); continue; }
if (sels.length === 1 && DARK.test(sels[0])) { collect(r.body, tokens.dark); continue; }
const kept = sels.filter(keep);
if (!kept.length || !r.body) continue;
lines.push(`${indent}${kept.map((s) => `.pplus-static ${s}`).join(',\n' + indent)} {\n${r.body.split('\n').map((l) => `${indent} ${l.trim()}`).filter((l) => l.trim()).join('\n')}\n${indent}}`);
}
return lines;
}
function collect(body, into) {
for (const decl of body.split(';')) {
const k = decl.slice(0, decl.indexOf(':')).trim();
const v = decl.slice(decl.indexOf(':') + 1).trim();
if (k.startsWith('--') && v && !SKIP_TOKENS.has(k)) into.set(k, v);
}
}
const rules = scoped(parse(fs.readFileSync(path.join(ROOT, 'styles.css'), 'utf8')));
const decls = (m) => [...m].map(([k, v]) => ` ${k}: ${v};`).join('\n');
const text = `/* pplus-views.css: GENERATED by \`pixi run quarto-css\` (scripts/quarto-css.mjs) from styles.css. Do not edit.
The app's own rules for what the static views draw, scoped under .pplus-static, with the app's color tokens;
the paper and ink follow the Quarto page (Bootstrap's variables). */
.pplus-static {
--paper: var(--bs-body-bg, #ffffff);
--paper-2: color-mix(in srgb, var(--bs-body-bg, #ffffff) 94%, var(--bs-body-color, #16191f));
--paper-3: color-mix(in srgb, var(--bs-body-bg, #ffffff) 88%, var(--bs-body-color, #16191f));
--ink: var(--bs-body-color, #16191f);
--ink-2: color-mix(in srgb, var(--bs-body-color, #16191f) 68%, var(--bs-body-bg, #ffffff));
--ink-3: color-mix(in srgb, var(--bs-body-color, #16191f) 48%, var(--bs-body-bg, #ffffff));
--line: color-mix(in srgb, var(--bs-body-color, #16191f) 14%, var(--bs-body-bg, #ffffff));
--line-2: color-mix(in srgb, var(--bs-body-color, #16191f) 24%, var(--bs-body-bg, #ffffff));
--mono: var(--bs-font-monospace, "IBM Plex Mono", ui-monospace, Menlo, Consolas, monospace);
--sans: inherit;
--bg: var(--paper); --bg-2: var(--paper-2); --bg-3: var(--paper-3); --fg: var(--ink); --fg-2: var(--ink-2); --note: var(--ink-3);
--current: var(--marker-bg); --last: var(--last-bg); --radius: var(--r-lg);
${decls(tokens.light)}
}
body.quarto-dark .pplus-static,
[data-bs-theme="dark"] .pplus-static {
${decls(tokens.dark)}
}
${rules.join('\n\n')}
`;
/* ---------- the machine views: the course's stylesheets, as the board uses them ---------- */
// tokens.css, kit.css and asm86.css are the course site's own, written for Quarto pages: they go in unchanged
// (styles/course/README.md). bridge.css's :root block maps the app's tokens onto the ones a Quarto page already
// has, so a page gets the rest of it: the board's adjustments to the course views.
const EXT = path.join(ROOT, 'quarto/_extensions/pplus');
const outputs = [[OUT, text]];
for (const f of ['tokens.css', 'kit.css', 'asm86.css']) outputs.push([path.join(EXT, 'course', f), fs.readFileSync(path.join(ROOT, 'styles/course', f), 'utf8')]);
const bridge = fs.readFileSync(path.join(ROOT, 'styles/course/bridge.css'), 'utf8');
const afterRoot = bridge.slice(bridge.indexOf('}', bridge.indexOf(':root {')) + 1).replace(/^\s+/, '');
outputs.push([path.join(EXT, 'pplus-hw.css'), `/* pplus-hw.css: GENERATED by \`pixi run quarto-css\` (scripts/quarto-css.mjs) from styles/course/bridge.css. Do not edit.
The Hardware board's adjustments to the course's machine views (course/*.css), for the pplus-hw shortcodes. A Quarto
page already has the colors and fonts those files read (--bs-body-bg, --bs-body-color, body.quarto-dark). */
${afterRoot}`]);
outputs.push([path.join(EXT, 'syntax', 'mojo.xml'), fs.readFileSync(path.join(ROOT, 'core/library/syntax/mojo.xml'), 'utf8')]);
if (process.argv.includes('--check')) {
const stale = outputs.filter(([file, want]) => !fs.existsSync(file) || fs.readFileSync(file, 'utf8') !== want).map(([file]) => path.relative(ROOT, file));
if (stale.length) { console.error(`quarto-css: out of date: ${stale.join(', ')}; run \`pixi run quarto-css\``); process.exit(1); }
console.log('quarto-css: up to date');
} else {
for (const [file, want] of outputs) { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, want); }
console.log(`quarto-css: wrote ${outputs.map(([f]) => path.relative(ROOT, f)).join(', ')} (${rules.length} rules, ${used.size} classes)`);
}
process.exit(0);
+55
View File
@@ -0,0 +1,55 @@
#!/usr/bin/env node
// SPDX-FileCopyrightText: 2026 Scientific Computing Studio, LLC
// SPDX-License-Identifier: Apache-2.0
/**
* Put a built Programming+ inside a copy of the Quarto extension, so a site renders the rendered views
* ({{< pplus-run >}}, {{< pplus-steps >}}, ...) without a checkout of this repository beside it:
*
* pixi run quarto-engine ../my-site/_extensions/pplus
*
* copies dist/ (without the source maps and the interpreter's test fixture) to <dir>/engine/dist, where pplus.lua
* looks for it after pplus-engine and PPLUS_ENGINE (quarto/README.md), pplus-core's core/dist/ to
* <dir>/engine/core/dist, and a package.json that maps the app's #core/ imports to it. Run it again after rebuilding. The copy is
* the app's compiled JavaScript; the site still needs Node 20 or later on the machine that renders it.
*/
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
const ROOT = fileURLToPath(new URL('..', import.meta.url));
const dir = process.argv[2];
const die = (m) => { console.error(`quarto-engine: ${m}`); process.exit(1); };
if (!dir) die('usage: pixi run quarto-engine <a site\'s _extensions/pplus folder>');
if (!fs.existsSync(path.join(dir, 'pplus.lua'))) die(`${dir} is not the extension's folder (no pplus.lua in it); copy quarto/_extensions/pplus there first`);
const dist = path.join(ROOT, 'dist');
if (!fs.existsSync(path.join(dist, 'quarto', 'render.js'))) die('dist/ is missing; run `pixi run build` first');
const out = path.join(dir, 'engine', 'dist');
fs.rmSync(path.join(dir, 'engine'), { recursive: true, force: true });
let files = 0, bytes = 0;
fs.cpSync(dist, out, {
recursive: true,
filter: (src) => {
const rel = path.relative(dist, src);
if (rel.endsWith('.map') || rel === 'curriculum' || rel.startsWith('curriculum' + path.sep)) return false;
if (fs.statSync(src).isFile()) { files++; bytes += fs.statSync(src).size; }
return true;
},
});
// pplus-core's modules, which the app's modules import as #core/...: Node finds the mapping in engine/package.json
const coreDist = path.join(ROOT, 'core', 'dist');
if (!fs.existsSync(path.join(coreDist, 'common', 'workspace.js'))) die('core/dist/ is missing; run `pixi run build` first');
fs.cpSync(coreDist, path.join(dir, 'engine', 'core', 'dist'), {
recursive: true,
filter: (src) => {
const rel = path.relative(coreDist, src);
if (rel.endsWith('.map') || rel.endsWith('.d.ts') || rel === 'curriculum' || rel.startsWith('curriculum' + path.sep)) return false;
if (fs.statSync(src).isFile()) { files++; bytes += fs.statSync(src).size; }
return true;
},
});
fs.writeFileSync(path.join(dir, 'engine', 'package.json'), JSON.stringify({ private: true, type: 'module', imports: { '#core/*': './core/dist/*' } }, null, 2) + '\n');
// the extension's own copy of the version, so a page can say which Programming+ rendered it
let version = 'dev';
try { version = fs.readFileSync(path.join(ROOT, '.git', 'HEAD'), 'utf8').trim(); } catch { /* not a checkout */ }
fs.writeFileSync(path.join(dir, 'engine', 'VERSION'), version + '\n');
console.log(`quarto-engine: copied ${files} files (${(bytes / 1e6).toFixed(1)} MB) to ${out}`);
+48
View File
@@ -0,0 +1,48 @@
#!/usr/bin/env node
// SPDX-FileCopyrightText: 2026 Scientific Computing Studio, LLC
// SPDX-License-Identifier: Apache-2.0
/**
* Put a program from mojo/local/ next to a Quarto page, with everything the playground shows for it:
*
* pixi run quarto-export demo ../site/programmingplus/demo
*
* writes into that folder
* demo.mojo the program, header and all (the shortcode leaves the header out of the pane and listing)
* demo.asm the compiler's x86-64 for it, as the x86-64 pane shows it (from src/mojo/generated/listings.ts)
* demo.setup the setup block that goes with it: the arguments' registers and the listing's data
* and prints the shortcodes that embed the whole playground with them, and that run it with the page. Run `pixi run --manifest-path core/pixi.toml play demo` first so
* the listing is current; without one (no godbolt answer yet, or the program has no function of its own
* left at this build), only the .mojo is written and the shortcode says so.
*
* Every option the shortcode takes is at the top of quarto/_extensions/pplus/pplus.lua.
*/
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';
const ROOT = fileURLToPath(new URL('..', import.meta.url));
const [name, outDir] = process.argv.slice(2).filter((a) => !a.startsWith('--'));
const die = (m) => { console.error(`quarto:export: ${m}`); process.exit(1); };
if (!name || !outDir) die('usage: pixi run quarto-export <program in mojo/local/> <folder beside the .qmd page>');
const src = path.join(ROOT, 'core/library/mojo/local', `${name}.mojo`);
if (!fs.existsSync(src)) die(`core/library/mojo/local/${name}.mojo does not exist`);
const listingsJs = path.join(ROOT, 'core/dist/mojo/generated/listings.js');
if (!fs.existsSync(listingsJs)) die('core/dist/ is missing; run `pixi run build` first');
const { MOJO_LISTINGS } = await import(pathToFileURL(listingsJs).href);
fs.mkdirSync(outDir, { recursive: true });
const wrote = [];
const put = (file, text) => { fs.writeFileSync(path.join(outDir, file), text.endsWith('\n') ? text : text + '\n'); wrote.push(file); };
put(`${name}.mojo`, fs.readFileSync(src, 'utf8'));
const listing = MOJO_LISTINGS[name];
if (listing) { put(`${name}.asm`, listing.asm); put(`${name}.setup`, listing.setup); }
const attrs = [`mojo="${name}.mojo"`];
if (listing) attrs.push(`asm="${name}.asm"`, `setup="${name}.setup"`);
attrs.push(`area="${listing ? 'hw' : 'dev'}"`, `title="${name}"`);
console.log(`wrote ${wrote.map((f) => path.join(outDir, f)).join(', ')}`);
if (!listing) console.log(`no x86-64 listing for ${name} yet: run \`pixi run --manifest-path core/pixi.toml play ${name}\` (with # mode: both and -O0 in its header), then export again`);
console.log(`\nin the page, the whole playground:\n\n{{< pplus-playground ${attrs.join(' ')} >}}\n`);
console.log(`or, rendered with the page (no iframe):\n\n{{< pplus-run mojo="${name}.mojo" code="1" >}}\n{{< pplus-lifetimes mojo="${name}.mojo" >}}\n`);
console.log('Other arrangements: panel="compiler" (open on the compiler\'s answer), build="default", dock="closed", editor="0.6"; {{< pplus-embed view="life" >}} for one live view. The gallery at #/quarto shows them all.');
+388
View File
@@ -0,0 +1,388 @@
#!/usr/bin/env node
// SPDX-FileCopyrightText: 2026 Scientific Computing Studio, LLC
// SPDX-License-Identifier: Apache-2.0
/**
* The chain of the three repositories, checked and moved in order. pplus-web pins pplus-core (core/) by commit, and
* core pins pplus-library (core/library/) by commit; a change at the bottom reaches the site only when both pointers
* move, in that order, and each repository has pushed the commit the one above names. When that was first done by
* hand it broke twice and nobody saw it for five weeks (a pointer to a commit from before a move, a pointer to a
* commit that existed only on one machine). This script is the order written down.
*
* node scripts/release.mjs check [--offline] [--quick] [--json]
* Is the chain consistent? For each pointer (web -> core, core -> library):
* - the commit it names is in the submodule's checkout, the checkout is at it, and has no uncommitted change
* - it is on the submodule's branch (.gitmodules, `main`) on its remote: asked with `git ls-remote` unless
* --offline, else read from the last fetch; "cannot tell" when neither can say. A pointer to a commit only
* this machine has is the failure this exists for.
* and, unless --quick: the generated files are current (core's `library.mjs emit --check`, `corpus.py emit`
* writes nothing new, web's `quarto-css.mjs --check`), and Mojo, Node and Python are pinned alike in
* library/mojo/pin.json, both pixi.toml files and both pixi.lock files. --quick is what tests/chain.test.mjs
* runs: the pointers and the checkouts only, no network, no build.
* Exit status 1 when something is wrong (each line says what to run), 0 otherwise ("cannot tell" included).
*
* node scripts/release.mjs bump [--commit] [--no-gate]
* After a change in core/library (committed there) or in core: move core's pointer to the library checkout's
* commit and regenerate what core derives from the library (library-emit, mojo-emit), run core's gate; then
* move web's pointer, regenerate what web derives from core (quarto-css), run web's gate; print the commits
* to push, in order. Without --commit it stages core's new pointer and leaves the regenerated files in the
* working trees, and prints the commits to make; with --commit it makes them. It never pushes, tags or fetches.
*
* Needs a build for everything but --quick (pixi run release-check and release-bump build first). Commands run with
* the node and python on the PATH, which under pixi are the pinned ones.
*/
import fs from 'node:fs';
import path from 'node:path';
import { spawnSync } from 'node:child_process';
import { fileURLToPath } from 'node:url';
export const WEB = fileURLToPath(new URL('..', import.meta.url));
/* ------------------------------------------------------------------ */
/* git */
/* ------------------------------------------------------------------ */
const NO_PROMPT = { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_SSH_COMMAND: process.env.GIT_SSH_COMMAND || 'ssh -o BatchMode=yes -o ConnectTimeout=10' };
/** Run git in dir; the trimmed stdout, or null when it fails. */
function git(dir, args, { timeout = 30000 } = {}) {
const r = spawnSync('git', ['-C', dir, ...args], { encoding: 'utf8', env: NO_PROMPT, timeout });
return r.status === 0 ? r.stdout.trim() : null;
}
const hasGit = () => spawnSync('git', ['--version']).status === 0;
const isCheckout = (dir) => fs.existsSync(path.join(dir, '.git')) && git(dir, ['rev-parse', '--is-inside-work-tree']) === 'true';
const short = (sha) => (sha ? sha.slice(0, 10) : '?');
/** The submodules a repository's .gitmodules names: path, url and branch (main when it names none). */
function submodules(dir) {
const file = path.join(dir, '.gitmodules');
if (!fs.existsSync(file)) return [];
const out = [];
let cur = null;
for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
const head = /^\s*\[submodule "([^"]+)"\]/.exec(line);
if (head) { cur = { name: head[1], branch: 'main' }; out.push(cur); continue; }
const kv = /^\s*(\w+)\s*=\s*(.+?)\s*$/.exec(line);
if (cur && kv) cur[kv[1]] = kv[2];
}
return out.filter((s) => s.path);
}
/** The commit a repository's index records for a submodule path (what the next commit will pin). */
function pointer(dir, sub) {
const line = git(dir, ['ls-files', '--stage', '--', sub]);
const m = line && /^160000 ([0-9a-f]{40}) /.exec(line);
return m ? m[1] : null;
}
/** A repository's name: its package.json's, else its remote's (pplus-library has no package.json). */
function repoName(dir, url = null) {
const pkg = path.join(dir, 'package.json');
if (fs.existsSync(pkg)) { try { return JSON.parse(fs.readFileSync(pkg, 'utf8')).name; } catch { /* below */ } }
return path.basename(url || git(dir, ['remote', 'get-url', 'origin']) || dir).replace(/\.git$/, '');
}
/** The links of the chain from a root: web -> core -> library, each a parent, a submodule path and the child dir. */
export function chain(root = WEB) {
const links = [];
const walk = (dir, label) => {
for (const s of submodules(dir)) {
const child = path.join(dir, s.path);
const childLabel = repoName(child, s.url);
links.push({ parent: dir, parentLabel: label, path: s.path, child, childLabel, branch: s.branch, url: s.url });
walk(child, childLabel);
}
};
walk(root, repoName(root));
return links;
}
const rel = (dir) => path.relative(WEB, dir) || '.';
/* ------------------------------------------------------------------ */
/* check */
/* ------------------------------------------------------------------ */
/**
* The cheap half of check: every pointer names a commit its checkout has, and the checkout is at it. Returns a list
* of { level: 'problem' | 'note', text, unread? } (unread: there were no pointers to read). Used by tests/chain.test.mjs, so `npm test` says when a pointer is broken.
* @param {string} [root] the repository at the top of the chain (default: this one)
*/
export function quickCheck(root = WEB) {
const out = [];
if (!hasGit()) return [{ level: 'note', unread: true, text: 'git is not on the PATH: the pointers cannot be read' }];
if (!isCheckout(root)) return [{ level: 'note', unread: true, text: `${root} is not a git checkout (a package, say): no pointers to read` }];
for (const l of chain(root)) {
const name = `${l.parentLabel} -> ${l.childLabel} (${rel(l.child)})`;
const sha = pointer(l.parent, l.path);
if (!sha) { out.push({ level: 'problem', text: `${name}: ${l.parentLabel} records no commit for ${l.path}` }); continue; }
if (!isCheckout(l.child)) {
out.push({ level: 'problem', text: `${name}: ${rel(l.child)} is not checked out. Fix: git submodule update --init --recursive` });
continue;
}
const head = git(l.child, ['rev-parse', 'HEAD']);
if (git(l.child, ['cat-file', '-e', `${sha}^{commit}`]) === null) {
out.push({ level: 'problem', text: `${name}: ${l.parentLabel} pins ${short(sha)}, and ${rel(l.child)} does not have that commit. Fix: git submodule update --init --recursive (it fetches the pinned commit); if no remote has it either, it was never pushed: push ${l.childLabel} from the machine that made it, then this` });
continue;
}
if (head === sha) continue;
if (git(l.child, ['merge-base', '--is-ancestor', head, sha]) !== null) {
out.push({ level: 'problem', text: `${name}: ${rel(l.child)} is at ${short(head)}, behind the pinned ${short(sha)}, so everything built and tested here uses an older ${l.childLabel}. Fix: git submodule update --recursive` });
} else if (git(l.child, ['merge-base', '--is-ancestor', sha, head]) !== null) {
const n = git(l.child, ['rev-list', '--count', `${sha}..${head}`]);
out.push({ level: 'note', text: `${name}: ${rel(l.child)} is ${n} commit(s) ahead of the pinned ${short(sha)}; when they are done, move the pointer (pixi run release-bump)` });
} else {
out.push({ level: 'problem', text: `${name}: ${rel(l.child)} is at ${short(head)}, which is neither the pinned ${short(sha)} nor after it. Fix: git submodule update --recursive, or, if ${short(head)} is the one wanted, pixi run release-bump` });
}
}
return out;
}
/** Is a commit on the branch of the submodule's remote? { level, text } with level ok, problem or unknown. */
function onRemoteBranch(l, sha, offline) {
const dir = l.child;
const tracking = `origin/${l.branch}`;
if (!offline) {
const r = spawnSync('git', ['-C', dir, 'ls-remote', '--heads', 'origin', l.branch], { encoding: 'utf8', env: NO_PROMPT, timeout: 20000 });
if (r.status === 0) {
const remoteHead = r.stdout.split('\n')[0]?.split('\t')[0];
if (!remoteHead) return { level: 'problem', text: `the remote has no branch ${l.branch}` };
if (remoteHead === sha) return { level: 'ok', text: `${short(sha)} is the head of ${l.branch} on the remote` };
if (git(dir, ['cat-file', '-e', `${remoteHead}^{commit}`]) === null) return { level: 'unknown', text: `cannot tell: the remote's ${l.branch} is at ${short(remoteHead)}, which this checkout has not fetched (git -C ${rel(dir)} fetch, then check again)` };
if (git(dir, ['merge-base', '--is-ancestor', sha, remoteHead]) !== null) return { level: 'ok', text: `${short(sha)} is on ${l.branch} on the remote (at ${short(remoteHead)})` };
return { level: 'problem', text: `${short(sha)} is not on ${l.branch} on the remote (at ${short(remoteHead)}), so a clone of ${l.childLabel}'s ${l.branch} does not have it. Push ${l.childLabel} first; the order is library, core, web` };
}
}
const why = offline ? '--offline' : 'the remote could not be asked';
if (git(dir, ['rev-parse', '--verify', '--quiet', `refs/remotes/${tracking}`]) === null) return { level: 'unknown', text: `cannot tell: ${why}, and there is no ${tracking} from an earlier fetch` };
if (git(dir, ['merge-base', '--is-ancestor', sha, `refs/remotes/${tracking}`]) !== null) return { level: 'ok', text: `${short(sha)} is on ${tracking} as of the last fetch (${why})` };
return { level: 'unknown', text: `cannot tell for sure (${why}): ${short(sha)} is not on ${tracking} as of the last fetch, so it is unpushed or was pushed after that fetch; if unpushed, push ${l.childLabel} to ${l.branch} first` };
}
/** Run a command in dir; { ok, out }. */
function sh(dir, cmd, args, opts = {}) {
const r = spawnSync(cmd, args, { cwd: dir, encoding: 'utf8', maxBuffer: 64 << 20, ...opts });
return { ok: r.status === 0, status: r.status, out: `${r.stdout || ''}${r.stderr || ''}`.trim(), missing: r.error?.code === 'ENOENT' };
}
const python = () => (spawnSync('python3', ['--version']).status === 0 ? 'python3' : spawnSync('python', ['--version']).status === 0 ? 'python' : null);
/** Every file under the given directories of dir. */
function filesUnder(dir, watched) {
const out = [];
const walk = (p) => { if (!fs.existsSync(p)) return; if (fs.statSync(p).isDirectory()) for (const e of fs.readdirSync(p)) walk(path.join(p, e)); else out.push(p); };
for (const w of watched) walk(path.join(dir, w));
return out;
}
/** Run a generator and say which files under `watched` it changed or added; then put them back as they were. */
function writesNothing(dir, watched, cmd, args) {
const before = new Map(filesUnder(dir, watched).map((f) => [f, fs.readFileSync(f)]));
const r = sh(dir, cmd, args);
const changed = [];
for (const [f, buf] of before) if (!fs.existsSync(f) || !fs.readFileSync(f).equals(buf)) { changed.push(path.relative(dir, f)); fs.writeFileSync(f, buf); }
for (const f of filesUnder(dir, watched)) if (!before.has(f)) { changed.push(path.relative(dir, f)); fs.rmSync(f); }
return { ...r, changed };
}
/** The version a pixi.toml installs of a package, as written ("==1.2.0", ">=26.10.0,<26.11"). */
const pixiDep = (text, name) => new RegExp(`^${name} = "([^"]+)"`, 'm').exec(text)?.[1] ?? null;
/** Full check: the quick part, the remote, the generated files and the pins. */
export function fullCheck({ root = WEB, offline = false } = {}) {
const lines = [];
const add = (level, where, text) => lines.push({ level, where, text });
for (const q of quickCheck(root)) add(q.level, 'pointers', q.text);
const links = chain(root);
if (!hasGit() || !isCheckout(root)) return lines;
for (const l of links) {
const where = `${l.parentLabel} -> ${l.childLabel}`;
const sha = pointer(l.parent, l.path);
if (!sha || git(l.child, ['cat-file', '-e', `${sha}^{commit}`]) === null) continue;
add('ok', where, `${l.parentLabel} pins ${l.childLabel} at ${short(sha)}${git(l.child, ['rev-parse', 'HEAD']) === sha ? ', and the checkout is there' : ''}`);
const dirty = git(l.child, ['status', '--porcelain', '--untracked-files=no', '--ignore-submodules=dirty']);
if (dirty) add('problem', where, `${rel(l.child)} has uncommitted changes, so what is tested here is not what the pointer names: ${dirty.split('\n').slice(0, 5).map((s) => s.trim()).join('; ')}${dirty.split('\n').length > 5 ? '; ...' : ''}. Commit them in ${l.childLabel} (then pixi run release-bump) or put them aside`);
const untracked = git(l.child, ['ls-files', '--others', '--exclude-standard', '--directory']);
if (untracked) add('note', where, `${rel(l.child)} has untracked files: ${untracked.split('\n').slice(0, 5).join(', ')}${untracked.split('\n').length > 5 ? ', ...' : ''}`);
const r = onRemoteBranch(l, sha, offline);
add(r.level, where, r.text);
}
// the top of the chain: its own commit is what the push order ends with; say if it is not on its branch either
const top = { child: root, childLabel: repoName(root), branch: 'main' };
const head = git(root, ['rev-parse', 'HEAD']);
if (head) { const r = onRemoteBranch(top, head, offline); add(r.level === 'problem' ? 'note' : r.level, top.childLabel, `this checkout's own commit: ${r.text}`); }
// generated files
const core = links.find((l) => l.childLabel === 'pplus-core')?.child ?? (fs.existsSync(path.join(root, 'scripts/library.mjs')) ? root : null);
const lib = core ? path.join(core, 'library') : null;
if (core) {
if (!fs.existsSync(path.join(core, 'dist', 'library', 'registry.js'))) add('unknown', 'generated', `cannot tell whether core's registry is current: core is not built (pixi run build)`);
else {
const r = sh(core, process.execPath, ['scripts/library.mjs', 'emit', '--check']);
add(r.ok ? 'ok' : 'problem', 'generated', r.ok ? "core's registry (src/library/generated.ts) is current with the library" : `${r.out}`);
}
const py = python();
if (!py) add('unknown', 'generated', 'cannot tell whether corpus.py emit is current: no python on the PATH (run through pixi)');
else {
const r = writesNothing(core, ['src/mojo/generated', 'library/syntax'], py, ['scripts/mojo/corpus.py', 'emit']);
if (!r.ok) add('problem', 'generated', `corpus.py emit failed: ${r.out.split('\n').slice(-3).join(' ')}`);
else add(r.changed.length ? 'problem' : 'ok', 'generated', r.changed.length ? `corpus.py emit would change ${r.changed.join(', ')} (put back as they were): run core's mojo-emit task (pixi run --manifest-path core/pixi.toml mojo-emit) and commit the result in core` : 'corpus.py emit writes nothing new (src/mojo/generated/, library/syntax/mojo.xml)');
}
}
if (fs.existsSync(path.join(root, 'scripts/quarto-css.mjs'))) {
if (!fs.existsSync(path.join(root, 'dist', 'quarto', 'render.js'))) add('unknown', 'generated', 'cannot tell whether the Quarto extension\'s generated files are current: the site is not built (pixi run build)');
else {
const r = sh(root, process.execPath, ['scripts/quarto-css.mjs', '--check']);
add(r.ok ? 'ok' : 'problem', 'generated', r.ok ? "the Quarto extension's generated files are current (quarto-css --check)" : `${r.out.split('\n').slice(-3).join(' ')}: run pixi run quarto-css and commit the result`);
}
}
// the pins: Mojo, Node and Python alike everywhere
if (lib && fs.existsSync(path.join(lib, 'mojo', 'pin.json'))) {
const want = JSON.parse(fs.readFileSync(path.join(lib, 'mojo', 'pin.json'), 'utf8')).mojo.version;
const wrong = [];
for (const dir of [core, root === core ? null : root].filter(Boolean)) {
const toml = fs.readFileSync(path.join(dir, 'pixi.toml'), 'utf8');
const name = rel(path.join(dir, 'pixi.toml'));
if (pixiDep(toml, 'mojo') !== `==${want}`) wrong.push(`${name} installs mojo ${pixiDep(toml, 'mojo')}`);
const lock = fs.existsSync(path.join(dir, 'pixi.lock')) ? fs.readFileSync(path.join(dir, 'pixi.lock'), 'utf8') : '';
const locked = [...new Set([...lock.matchAll(/\/mojo-(\d+\.\d+\.\d+)-[^/]*\.conda/g)].map((m) => m[1]))];
if (locked.length !== 1 || locked[0] !== want) wrong.push(`${rel(path.join(dir, 'pixi.lock'))} locks mojo ${locked.join(', ') || 'nowhere'}`);
}
const gen = path.join(core, 'src', 'mojo', 'generated', 'pin.ts');
const genVersion = fs.existsSync(gen) ? /MOJO_VERSION = "([^"]+)"/.exec(fs.readFileSync(gen, 'utf8'))?.[1] : null;
if (genVersion !== want) wrong.push(`core's src/mojo/generated/pin.ts says ${genVersion}`);
add(wrong.length ? 'problem' : 'ok', 'pins', wrong.length ? `library/mojo/pin.json pins Mojo ${want}, and ${wrong.join('; ')}` : `Mojo ${want} in library/mojo/pin.json, core's generated pin, every pixi.toml and pixi.lock`);
if (root !== core) {
const a = fs.readFileSync(path.join(core, 'pixi.toml'), 'utf8'); const b = fs.readFileSync(path.join(root, 'pixi.toml'), 'utf8');
const differ = ['nodejs', 'python'].filter((p) => pixiDep(a, p) !== pixiDep(b, p));
add(differ.length ? 'problem' : 'ok', 'pins', differ.length ? differ.map((p) => `${p}: core pins ${pixiDep(a, p)}, web pins ${pixiDep(b, p)}`).join('; ') : `Node ${pixiDep(a, 'nodejs')} and Python ${pixiDep(a, 'python')} alike in core and web`);
}
}
return lines;
}
/* ------------------------------------------------------------------ */
/* bump */
/* ------------------------------------------------------------------ */
function step(text) { console.log(`\n== ${text}`); }
function must(r, what) {
if (r.ok) return r;
console.error(r.out.split('\n').slice(-25).join('\n'));
console.error(`\nrelease bump: ${what} failed; nothing was committed. Fix it and run release-bump again.`);
process.exit(1);
}
const testFiles = (dir) => fs.readdirSync(path.join(dir, 'tests')).filter((f) => f.endsWith('.test.mjs')).sort().map((f) => `tests/${f}`);
const tsc = () => path.join(WEB, 'node_modules', 'typescript', 'bin', 'tsc');
/** The tracked files with changes in dir (porcelain lines are "XY path"; read untrimmed, X may be a space). */
const tracked = (dir) => (spawnSync('git', ['-C', dir, 'status', '--porcelain', '--untracked-files=no', '--ignore-submodules=dirty'], { encoding: 'utf8' }).stdout || '').split('\n').filter(Boolean).map((l) => l.slice(3));
/** Move the pointers bottom up; see the header. */
export function bump({ commit = false, gate = true } = {}) {
const links = chain(WEB);
const toCore = links.find((l) => l.childLabel === 'pplus-core');
const toLib = links.find((l) => l.childLabel === 'pplus-library');
if (!toCore || !toLib) { console.error('release bump: run it in pplus-web, with core/ and core/library/ checked out (git submodule update --init --recursive)'); process.exit(2); }
const core = toCore.child; const lib = toLib.child;
const py = python();
if (!py) { console.error('release bump: no python on the PATH; run it as pixi run release-bump'); process.exit(2); }
const push = [];
// with --commit, a commit must hold the pointer and what was regenerated, and nothing else someone was editing
const editing = [...tracked(core).filter((f) => f !== 'library').map((f) => `core/${f}`), ...tracked(WEB).filter((f) => f !== 'core')];
if (commit && editing.length) { console.error(`release bump --commit: there are uncommitted changes that are not the pointers (${editing.join(', ')}); commit or put them aside first, or run without --commit`); process.exit(1); }
// 1. the library: committed, and clean
const libHead = git(lib, ['rev-parse', 'HEAD']);
const libDirty = tracked(lib);
if (libDirty.length) { console.error(`release bump: core/library has uncommitted changes (${libDirty.join(', ')}). Commit them in pplus-library first.`); process.exit(1); }
const libPinned = pointer(core, 'library');
if (libHead !== libPinned) {
if (git(lib, ['merge-base', '--is-ancestor', libPinned, libHead]) === null) console.log(`note: the library checkout (${short(libHead)}) does not descend from the commit core pinned (${short(libPinned)})`);
step(`core: move library from ${short(libPinned)} to ${short(libHead)}, and regenerate what core derives from it`);
must(sh(core, 'git', ['add', 'library']), 'git add library in core');
} else step(`core already pins the library checkout (${short(libHead)}); regenerating to be sure`);
must(sh(WEB, process.execPath, [tsc(), '-p', 'core/tsconfig.json']), 'building core');
// what core derives from the library; library CI (pplus-library's .gitea/workflows/test.yml) runs the same two
console.log(must(sh(core, process.execPath, ['scripts/library.mjs', 'emit']), 'library-emit').out);
console.log(must(sh(core, py, ['scripts/mojo/corpus.py', 'emit']), 'mojo-emit').out.split('\n').slice(-2).join('\n'));
if (tracked(lib).length) { console.error(`release bump: mojo-emit changed the library (${tracked(lib).join(', ')}): commit that in pplus-library, then run release-bump again`); process.exit(1); }
must(sh(WEB, process.execPath, [tsc(), '-p', 'core/tsconfig.json']), 'building core again, with the regenerated sources');
if (gate) {
step("core's gate: every test, and no program of ours failing");
const t = must(sh(core, process.execPath, ['--test', ...testFiles(core)]), "core's tests");
console.log(t.out.split('\n').filter((l) => /^ℹ (tests|pass|fail|skipped)/.test(l)).join('\n'));
console.log(must(sh(core, py, ['scripts/mojo/corpus.py', 'status', '--strict']), 'mojo-status-strict').out.split('\n').slice(-2).join('\n'));
console.log(must(sh(core, process.execPath, ['scripts/library.mjs', 'check']), 'library-check').out.split('\n').slice(-1).join('\n'));
if (tracked(lib).length) { console.error(`release bump: library-check rewrote ${tracked(lib).join(', ')}: the library's records were not current. Commit them in pplus-library, then run release-bump again`); process.exit(1); }
}
const coreChanges = tracked(core);
const coreMsg = `Move pplus-library to ${short(libHead)}, and regenerate what core derives from it`;
const libBranch = toLib.branch;
push.push({ repo: 'pplus-library', dir: lib, sha: libHead, branch: libBranch });
let coreSha = git(core, ['rev-parse', 'HEAD']);
if (coreChanges.length) {
if (commit) {
must(sh(core, 'git', ['add', '--', ...coreChanges]), 'git add in core');
must(sh(core, 'git', ['commit', '-q', '-m', coreMsg]), 'git commit in core');
coreSha = git(core, ['rev-parse', 'HEAD']);
console.log(`committed core ${short(coreSha)}: ${coreMsg}`);
} else {
console.log(`\nto commit in core (or run again with --commit):\n git -C core add ${coreChanges.join(' ')}\n git -C core commit -m "${coreMsg}"`);
}
} else console.log('core: nothing to commit');
push.push({ repo: 'pplus-core', dir: core, sha: coreChanges.length && !commit ? null : coreSha, branch: toCore.branch });
// 2. web: pointer to core's commit, regenerate, gate
const corePinned = pointer(WEB, 'core');
const coreMoved = coreSha !== corePinned || (coreChanges.length && !commit);
if (commit && coreSha !== corePinned) { step(`web: move core from ${short(corePinned)} to ${short(coreSha)}`); must(sh(WEB, 'git', ['add', 'core']), 'git add core in web'); }
else if (!coreMoved) step(`web already pins core at ${short(coreSha)}`);
else step("web: built and tested against core's working tree (the pointer moves when core's commit exists)");
must(sh(WEB, process.execPath, [tsc(), '-p', 'tsconfig.json']), 'building the site');
console.log(must(sh(WEB, process.execPath, ['scripts/quarto-css.mjs']), 'quarto-css').out.split('\n').slice(-2).join('\n'));
if (gate) {
step("web's gate: every test of the site");
const t = must(sh(WEB, process.execPath, ['--test', ...testFiles(WEB)]), "the site's tests");
console.log(t.out.split('\n').filter((l) => /^ℹ (tests|pass|fail|skipped)/.test(l)).join('\n'));
}
const webChanges = tracked(WEB);
const webMsg = `Move pplus-core to ${short(coreSha)}`;
let webSha = git(WEB, ['rev-parse', 'HEAD']);
if (webChanges.length && commit) {
must(sh(WEB, 'git', ['add', '--', ...webChanges]), 'git add in web');
must(sh(WEB, 'git', ['commit', '-q', '-m', webMsg]), 'git commit in web');
webSha = git(WEB, ['rev-parse', 'HEAD']);
console.log(`committed web ${short(webSha)}: ${webMsg}`);
} else if (webChanges.length || coreMoved) {
console.log(`\nto commit in web, after core's commit:\n git add core${webChanges.filter((f) => f !== 'core').map((f) => ` ${f}`).join('')}\n git commit -m "Move pplus-core to <core's new commit>"`);
}
push.push({ repo: 'pplus-web', dir: WEB, sha: webChanges.length && !commit ? null : webSha, branch: 'main' });
console.log('\nPush in this order, each before the next (a pointer may only name a pushed commit); nothing was pushed:');
push.forEach((p, i) => console.log(` ${i + 1}. ${p.repo} ${p.sha ? short(p.sha) : '(the commit above, once made)'} to ${p.branch}: git -C ${rel(p.dir)} push origin ${p.sha ?? 'HEAD'}:refs/heads/${p.branch}`));
console.log('Then pixi run release-check should say every pointer is on its branch.');
}
/* ------------------------------------------------------------------ */
/* Command line */
/* ------------------------------------------------------------------ */
if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
const args = process.argv.slice(2);
const cmd = args[0];
if (cmd === 'check') {
const lines = args.includes('--quick') ? quickCheck().map((q) => ({ ...q, where: 'pointers' })) : fullCheck({ offline: args.includes('--offline') });
if (args.includes('--json')) console.log(JSON.stringify(lines, null, 2));
else {
const tag = { ok: 'ok ', problem: 'PROBLEM ', unknown: 'cannot tell', note: 'note ' };
for (const l of lines) console.log(`${tag[l.level]} [${l.where}] ${l.text}`);
const n = (lv) => lines.filter((l) => l.level === lv).length;
console.log(`\n${n('problem') ? `${n('problem')} problem(s)` : 'the chain is consistent'}${n('unknown') ? `; ${n('unknown')} thing(s) it cannot tell` : ''}`);
}
process.exit(lines.some((l) => l.level === 'problem') ? 1 : 0);
} else if (cmd === 'bump') {
bump({ commit: args.includes('--commit'), gate: !args.includes('--no-gate') });
} else {
console.error('usage: node scripts/release.mjs check [--offline] [--quick] [--json] | bump [--commit] [--no-gate]');
process.exit(2);
}
}
+17
View File
@@ -0,0 +1,17 @@
// SPDX-FileCopyrightText: 2026 Scientific Computing Studio, LLC
// SPDX-License-Identifier: Apache-2.0
const esbuild = await import(process.env.ESBUILD_LIB || 'esbuild');
import path from 'node:path';
import fs from 'node:fs';
const here = path.dirname(new URL(import.meta.url).pathname);
const map = {
'@codemirror/state': 'state/src/index.ts', '@codemirror/view': 'view/src/index.ts', '@codemirror/language': 'language/src/index.ts',
'@codemirror/commands': 'commands/src/index.ts', '@codemirror/search': 'search/src/index.ts',
'@lezer/common': 'common/src/index.ts', '@lezer/highlight': 'highlight/src/highlight.ts', '@lezer/lr': 'lr/src/index.ts',
'style-mod': 'style-mod/src/style-mod.js', 'w3c-keyname': 'w3c-keyname/index.js', 'crelt': 'crelt/index.js', '@marijn/find-cluster-break': 'find-cluster-break/src/index.js',
};
const alias = { name: 'alias', setup(b) { b.onResolve({ filter: /^(@codemirror|@lezer|@marijn)\/|^(style-mod|w3c-keyname|crelt)$/ }, (a) => ({ path: path.join(here, map[a.path]) })); } };
const versions = Object.entries(map).map(([k, v]) => `${k}@${JSON.parse(fs.readFileSync(path.join(here, v.split('/')[0], 'package.json'), 'utf8')).version}`);
const banner = `/* CodeMirror 6, bundled for Programming+ from the packages' sources (MIT; see CODEMIRROR-LICENSE next to this file).\n * ${versions.join(' ')}\n * Rebuild with scripts/vendor/codemirror.sh; do not edit by hand. */`;
await esbuild.build({ entryPoints: [path.join(here, 'entry.ts')], bundle: true, format: 'esm', outfile: path.join(here, 'codemirror.js'), plugins: [alias], target: 'es2022', minifyWhitespace: true, minifySyntax: true, legalComments: 'none', banner: { js: banner }, logLevel: 'info' });
Vendored Executable
+47
View File
@@ -0,0 +1,47 @@
#!/usr/bin/env bash
# SPDX-FileCopyrightText: 2026 Scientific Computing Studio, LLC
# SPDX-License-Identifier: Apache-2.0
# Rebuilds src/vendor/codemirror.js (one ES module) and src/vendor/cm-types/ (its
# declarations) from the CodeMirror packages' own sources on GitHub.
#
# Programming+ ships no bundler and no runtime dependency; CodeMirror is
# vendored the way the pseudo and asm86 engines are, as a built file checked
# into the repository. Rerun this to move to newer CodeMirror releases:
#
# scripts/vendor/codemirror.sh # the packages' main branches
# scripts/vendor/codemirror.sh @6.5.0 ... # (edit PINS below for exact tags)
#
# Needs: git, node >= 20, esbuild on the PATH or in ESBUILD, and tsc.
set -euo pipefail
here="$(cd "$(dirname "$0")" && pwd)"
root="$(cd "$here/../.." && pwd)"
work="${CM_WORK:-$(mktemp -d)}"
ESBUILD="${ESBUILD:-$(command -v esbuild || true)}"
[ -n "$ESBUILD" ] || { echo "esbuild not found: npm i -g esbuild, or ESBUILD=/path/to/esbuild"; exit 1; }
# repo -> directory name the build script expects
PINS=(
"codemirror/state state" "codemirror/view view" "codemirror/language language" "codemirror/commands commands" "codemirror/search search"
"marijnh/style-mod style-mod" "marijnh/w3c-keyname w3c-keyname" "marijnh/crelt crelt" "marijnh/find-cluster-break find-cluster-break"
"lezer-parser/common common" "lezer-parser/highlight highlight" "lezer-parser/lr lr"
)
cd "$work"
for pin in "${PINS[@]}"; do
set -- $pin
[ -d "$2" ] || git clone -q --depth 1 "https://github.com/$1" "$2"
done
# two packages have no src/index.ts of their own
printf 'export * from "./commands"\nexport * from "./history"\nexport * from "./comment"\n' > commands/src/index.ts
printf 'export * from "./search"\nexport * from "./cursor"\nexport * from "./regexp"\nexport * from "./goto-line"\nexport * from "./selection-match"\n' > search/src/index.ts
cp "$here/entry.ts" "$here/build.mjs" "$here/relink.mjs" "$here/tsconfig.cm.json" .
mv tsconfig.cm.json tsconfig.json
ESBUILD_LIB="$(node -e "console.log(require.resolve('esbuild', { paths: [process.cwd(), '$(dirname "$ESBUILD")/..', '$(npm root -g)'] }))")" node build.mjs
rm -rf types && (tsc -p tsconfig.json || true) # the packages' own sources have a few strict-mode complaints; the declarations still emit
node relink.mjs
rm -rf "$root/src/vendor/cm-types"
cp codemirror.js "$root/src/vendor/codemirror.js"
cp -r types "$root/src/vendor/cm-types"
rm "$root/src/vendor/cm-types/entry.d.ts"
sed 's#"\./#"./cm-types/#g' types/entry.d.ts > "$root/src/vendor/codemirror.d.ts"
cp state/LICENSE "$root/src/vendor/CODEMIRROR-LICENSE"
echo "vendored into $root/src/vendor from $work"
+8
View File
@@ -0,0 +1,8 @@
// SPDX-FileCopyrightText: 2026 Scientific Computing Studio, LLC
// SPDX-License-Identifier: Apache-2.0
// Programming+'s CodeMirror 6 bundle: the parts the editor uses, in one ES module.
export * from '@codemirror/state';
export * from '@codemirror/view';
export { history, historyKeymap, undo, redo, defaultKeymap, indentWithTab, insertNewlineAndIndent, toggleComment, selectAll, indentMore, indentLess } from '@codemirror/commands';
export { search, searchKeymap, highlightSelectionMatches, openSearchPanel, closeSearchPanel, gotoLine } from '@codemirror/search';
export { indentUnit, bracketMatching, foldGutter, foldKeymap, codeFolding, foldService, indentService, StreamLanguage, LanguageSupport, syntaxHighlighting, HighlightStyle, defaultHighlightStyle } from '@codemirror/language';
+26
View File
@@ -0,0 +1,26 @@
// SPDX-FileCopyrightText: 2026 Scientific Computing Studio, LLC
// SPDX-License-Identifier: Apache-2.0
import fs from 'node:fs'; import path from 'node:path';
const root = path.resolve('types');
const map = {
'@codemirror/state': 'state/src/index.d.ts', '@codemirror/view': 'view/src/index.d.ts', '@codemirror/language': 'language/src/index.d.ts',
'@codemirror/commands': 'commands/src/index.d.ts', '@codemirror/search': 'search/src/index.d.ts',
'@lezer/common': 'common/src/index.d.ts', '@lezer/highlight': 'highlight/src/highlight.d.ts', '@lezer/lr': 'lr/src/index.d.ts',
'style-mod': 'style-mod/src/style-mod.d.ts', 'w3c-keyname': 'w3c-keyname/index.d.ts', 'crelt': 'crelt/index.d.ts', '@marijn/find-cluster-break': 'find-cluster-break/src/index.d.ts',
};
// the plain-JS deps' hand-written d.ts files were not emitted by tsc; copy them in
for (const [k, v] of Object.entries(map)) { const dst = path.join(root, v); if (!fs.existsSync(dst)) { fs.mkdirSync(path.dirname(dst), { recursive: true }); fs.copyFileSync(path.join(k === '@marijn/find-cluster-break' ? 'find-cluster-break/src/index.d.ts' : v), dst); } }
const walk = (d) => fs.readdirSync(d, { withFileTypes: true }).flatMap((e) => e.isDirectory() ? walk(path.join(d, e.name)) : e.name.endsWith('.d.ts') ? [path.join(d, e.name)] : []);
let n = 0;
for (const f of walk(root)) {
let s = fs.readFileSync(f, 'utf8');
const before = s;
s = s.replace(/from ["']([^"']+)["']/g, (m, spec) => {
if (!map[spec]) return m;
let rel = path.relative(path.dirname(f), path.join(root, map[spec])).replace(/\\/g, '/').replace(/\.d\.ts$/, '.js');
if (!rel.startsWith('.')) rel = './' + rel;
return `from "${rel}"`;
});
if (s !== before) { fs.writeFileSync(f, s); n++; }
}
console.log('relinked', n, 'files');
+64
View File
@@ -0,0 +1,64 @@
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"moduleResolution": "Bundler",
"lib": [
"ES2022",
"DOM",
"DOM.Iterable"
],
"declaration": true,
"emitDeclarationOnly": true,
"outDir": "types",
"rootDir": ".",
"strict": false,
"skipLibCheck": true,
"allowJs": true,
"stripInternal": true,
"types": [],
"baseUrl": ".",
"ignoreDeprecations": "6.0",
"paths": {
"@codemirror/state": [
"state/src/index.ts"
],
"@codemirror/view": [
"view/src/index.ts"
],
"@codemirror/language": [
"language/src/index.ts"
],
"@codemirror/commands": [
"commands/src/index.ts"
],
"@codemirror/search": [
"search/src/index.ts"
],
"@lezer/common": [
"common/src/index.ts"
],
"@lezer/highlight": [
"highlight/src/highlight.ts"
],
"@lezer/lr": [
"lr/src/index.ts"
],
"style-mod": [
"style-mod/src/style-mod.d.ts"
],
"w3c-keyname": [
"w3c-keyname/index.d.ts"
],
"crelt": [
"crelt/index.d.ts"
],
"@marijn/find-cluster-break": [
"find-cluster-break/src/index.d.ts"
]
}
},
"files": [
"entry.ts"
]
}