Make this repository the engines' home; the course copies from here

Whether the engines' changes went back to the course or the course took
them from here was an open question (docs/engines.md). Soundness fixes to
the prover cannot wait for a round trip through a repository with no engine
tests, so this repository now owns the engines.

- pixi run engines-export <course>/static builds and writes every engine
  module into the course's static/js/: JavaScript modules as written,
  TypeScript ones (logic, solver, vcgen) as built, without source maps.
- pixi run engines-diff now shows what the course has not taken yet,
  comparing the file the course would receive with its copy. Both scripts
  share the list of modules in scripts/engines-files.mjs.
- docs/engines.md describes the ownership, the prover's three modules and
  its number model, the soundness tests and the bugs found so far, the
  changes the course receives with the next export, and how to export.
- AGENTS.md gains a hard rule: never let the prover call something proved
  that a run breaks, with how to add a soundness regression first.
- docs/app.md's Known limits no longer sends engine fixes upstream.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FgvbRdoEheAHqsRmr2WuKZ
This commit is contained in:
alexmandClaude committed 2026-10-05 03:33:58 +00:00
1 parent 2416d7fc8e
commit 0d313f989d
8 files changed
+151 -42

No files matched your search

+28 -19
View File
@@ -1,19 +1,23 @@
#!/usr/bin/env node
/**
* Compare the vendored course code with a checkout of the course site.
* Compare this repository's engines with a checkout of the course site.
*
* pixi run engines-diff ../course/static
*
* <static> is the course repository's static/ directory. For each engine
* module in src/engines/ (pseudo, asm86, shared) and each stylesheet in
* styles/course/, prints whether it is the same as the course's copy, differs
* only in whitespace and line endings, or differs in content (with the number
* of changed lines, whitespace ignored), and lists files only one side has.
* It changes nothing. docs/engines.md says what to do with the answer.
* <static> is the course repository's static/ directory. This repository owns
* the engines and the course copies from here (pixi run engines-export), so
* this shows what the course has not taken yet. For each engine module (pseudo,
* asm86, shared) it compares the file the course would receive (src/engines/
* as written, or dist/engines/ for a module written in TypeScript) with the
* course's copy, and each stylesheet in styles/course/ with the course's;
* prints whether they are the same, differ only in whitespace and line
* endings, or differ in content (with the number of changed lines, whitespace
* ignored), and lists files only one side has. It changes nothing.
*/
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { engineModules, ENGINE_DIRS } from './engines-files.mjs';
const ROOT = fileURLToPath(new URL('..', import.meta.url));
const dir = process.argv[2];
@@ -22,9 +26,6 @@ if (!dir || !fs.existsSync(path.join(dir, 'js'))) {
process.exit(2);
}
const PAIRS = [
...['pseudo', 'asm86', 'shared'].map((f) => [`src/engines/${f}`, `js/${f}`, '.js']),
];
const CSS = { 'tokens.css': 'css/base/tokens.css', 'kit.css': 'css/widgets/kit.css', 'asm86.css': 'css/widgets/asm86.css' };
const squash = (s) => s.replace(/\r/g, '').split('\n').map((l) => l.replace(/\s+/g, ' ').trim()).filter(Boolean);
@@ -47,15 +48,23 @@ function compare(ours, theirs) {
}
const rows = [];
for (const [mine, course, ext] of PAIRS) {
const m = path.join(ROOT, mine), c = path.join(dir, course);
const names = new Set([...(fs.existsSync(m) ? fs.readdirSync(m) : []), ...(fs.existsSync(c) ? fs.readdirSync(c) : [])].filter((f) => f.endsWith(ext)));
for (const f of [...names].sort()) {
const a = path.join(m, f), b = path.join(c, f);
const label = `${mine}/${f}`;
if (!fs.existsSync(a)) rows.push([label, 'only in the course']);
else if (!fs.existsSync(b)) rows.push([label, 'only here']);
else { const r = compare(a, b); rows.push([label, r.kind === 'content' ? `differs: ${r.n} lines` : r.kind === 'whitespace' ? 'whitespace only' : 'same']); }
const strip = (t) => t.replace(/\n\/\/# sourceMappingURL=.*\n?$/, '\n');
const mine = engineModules(ROOT);
for (const m of mine) {
const theirs = path.join(dir, 'js', m.dir, m.file);
if (!fs.existsSync(m.ours)) rows.push([m.label, 'not built: run pixi run build']);
else if (!fs.existsSync(theirs)) rows.push([m.label, 'only here']);
else {
const a = strip(fs.readFileSync(m.ours, 'utf8')), b = fs.readFileSync(theirs, 'utf8');
const r = a === b ? { kind: 'same' } : (changed(squash(a), squash(b)) === 0 ? { kind: 'whitespace' } : { kind: 'content', n: changed(squash(a), squash(b)) });
rows.push([m.label, r.kind === 'content' ? `differs: ${r.n} lines` : r.kind === 'whitespace' ? 'whitespace only' : 'same']);
}
}
for (const d of ENGINE_DIRS) {
const c = path.join(dir, 'js', d);
if (!fs.existsSync(c)) continue;
for (const f of fs.readdirSync(c).filter((x) => x.endsWith('.js')).sort()) {
if (!mine.some((m) => m.dir === d && m.file === f)) rows.push([`js/${d}/${f}`, 'only in the course']);
}
}
for (const [f, course] of Object.entries(CSS)) {
+43
View File
@@ -0,0 +1,43 @@
#!/usr/bin/env node
/**
* Copy this repository's language engines into a checkout of the course site.
*
* pixi run engines-export ../course/static
*
* This repository owns the engines (docs/engines.md); the course copies from
* here. <static> is the course repository's static/ directory. For each
* engine directory (pseudo, asm86, shared) every module goes to
* <static>/js/<directory>/: a JavaScript module as written in src/engines/,
* a TypeScript one (logic, solver, vcgen) as built into dist/engines/, which
* is plain ES-module JavaScript the course's pages can import unchanged.
* Source maps are not copied. Prints what it wrote, and changes nothing else
* in the course. Review the course's diff before committing it there.
*/
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { engineModules } from './engines-files.mjs';
const ROOT = fileURLToPath(new URL('..', import.meta.url));
const dir = process.argv[2];
if (!dir || !fs.existsSync(path.join(dir, 'js'))) {
console.error('usage: pixi run engines-export <the course repository\'s static/ directory>');
process.exit(2);
}
let wrote = 0, same = 0, added = 0;
for (const m of engineModules(ROOT)) {
if (!fs.existsSync(m.ours)) {
console.error(`${m.label}: ${path.relative(ROOT, m.ours)} is missing; run pixi run build first`);
process.exit(1);
}
const target = path.join(dir, 'js', m.dir, m.file);
const text = fs.readFileSync(m.ours, 'utf8').replace(/\n\/\/# sourceMappingURL=.*\n?$/, '\n');
const before = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : null;
if (before === text) { same++; continue; }
fs.mkdirSync(path.dirname(target), { recursive: true });
fs.writeFileSync(target, text);
if (before === null) { added++; console.log(`added js/${m.dir}/${m.file}${m.built ? ' (built from TypeScript)' : ''}`); }
else { wrote++; console.log(`updated js/${m.dir}/${m.file}${m.built ? ' (built from TypeScript)' : ''}`); }
}
console.log(`\n${wrote} updated, ${added} added, ${same} already the same`);
+25
View File
@@ -0,0 +1,25 @@
/**
* The engine modules this repository owns, and the file of each that the course receives:
* src/engines/<dir>/<name>.js as written, or dist/engines/<dir>/<name>.js for a module written in
* TypeScript. Shared by engines-diff and engines-export.
*/
import fs from 'node:fs';
import path from 'node:path';
export const ENGINE_DIRS = ['pseudo', 'asm86', 'shared'];
/** Every engine module: { dir, file, label, ours, built }. */
export function engineModules(root) {
const out = [];
for (const dir of ENGINE_DIRS) {
const src = path.join(root, 'src/engines', dir);
for (const f of fs.readdirSync(src).sort()) {
if (f.endsWith('.js')) out.push({ dir, file: f, label: `src/engines/${dir}/${f}`, ours: path.join(src, f), built: false });
else if (f.endsWith('.ts') && !f.endsWith('.d.ts')) {
const js = f.replace(/\.ts$/, '.js');
out.push({ dir, file: js, label: `src/engines/${dir}/${f}`, ours: path.join(root, 'dist/engines', dir, js), built: true });
}
}
}
return out;
}