Move the engine core into core/, a project of its own (pplus-core)

What programs mean (the languages, translators, Mojo checker and
interpreter, prover, fuzzer, machine model, catalog problems and the Mojo
corpus with godbolt's stored answers) was mixed into the site's tree, so a
change to the prover and a change to a button went through the same gate
and the same docs. This moves all of it under core/, laid out as its own
repository, ready to be extracted with its history and pinned here as a
git submodule.

- core/: src/{engines,services,sync,mojo,exercises,curriculum,common},
  mojo/, syntax/mojo.xml, its tests (with Workspace and workForProblem in
  place of the site's Session), scripts (corpus pipeline, play, the
  exercise and probe starters, engines export/diff), and its docs
  (engines, trust, mojo-corpus, exercises, coverage). Its own pixi.toml,
  package.json, README, AGENTS.md and CI workflow.
- core/tests/boundary.test.mjs: library modules use no DOM, import no
  page widget, and import nothing outside src/.
- core/scripts/cli.mjs: pixi run cli check|run|prove|fuzz|translate.
- core/scripts/dafny.py: Dafny 4.11.0 pinned by version and SHA-256 per
  platform, fetched into .tools/ (pixi run dafny-fetch, pixi run dafny).
- The site imports core only as #core/<path>.js: an import map in
  index.html, "imports" in package.json for node, core's declarations for
  tsc. The site's TypeScript builds core first (npm run build).
- assemble.sh, the Quarto engine copy, the render cache key, check-pages,
  quarto-export and quarto-css read core/dist and core/mojo; quarto-css
  copies core's syntax/mojo.xml into the extension.
- Site tests that covered engines moved to core; the rest keep Session.
- README, AGENTS.md, docs/app.md, docs/deploy.md and the CI workflow
  describe the split (checkout with submodules; core's tests and corpus
  status run against the pinned commit).

Gate: site 110 pass; core 307 pass; corpus status --strict passes.
Manual check: the assembled site opens Bridge (count-base-proved),
Developer and Hardware (count-base) with the editor, the stepper and the
board, and no module errors.

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 05:43:58 +00:00
1 parent 961a59054d
commit c5157fcad5
56 files changed
+3386 -66

No files matched your search

+107
View File
@@ -0,0 +1,107 @@
#!/usr/bin/env node
/**
* pplus: pplus-core without a browser. The same engines, translators, prover and fuzzer the app runs, on a file.
*
* pixi run cli check <file> what the language's own reader says
* pixi run cli run <file> [--call C] [--input F] run it, print what it prints
* pixi run cli prove <file> [--speco F] every obligation: proved, broken or open
* pixi run cli fuzz <file> [--seed N] [--budget N] the fuzzer's report per routine
* pixi run cli translate <file.pseudo> --to mojo|lingo|matho|speco
*
* The language comes from the extension: .pseudo, .lingo, .matho (or .tex), .speco, .mojo, .asm (or .s). Add --json
* for machine-readable output. Exit status: 0 when nothing is wrong, 1 when the command found a problem (an error,
* a broken obligation, a failing input, a run that stopped), 2 for a usage error. Build first (`pixi run build`):
* this reads dist/.
*/
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 dist = (p) => pathToFileURL(path.join(ROOT, 'dist', p)).href;
const usage = (why) => {
if (why) console.error(`pplus: ${why}`);
console.error('usage: pplus <check|run|prove|fuzz|translate> <file> [--call C] [--input F] [--speco F] [--seed N] [--budget N] [--to LANG] [--json]');
process.exit(2);
};
if (!fs.existsSync(path.join(ROOT, 'dist', 'common', 'workspace.js'))) usage('dist/ is missing; run `pixi run build` first');
const [cmd, file, ...rest] = process.argv.slice(2);
if (!cmd || !file) usage();
const opt = (name) => { const i = rest.indexOf(`--${name}`); return i >= 0 ? rest[i + 1] : undefined; };
const json = rest.includes('--json');
const LANG_OF = { '.pseudo': 'pseudo', '.lingo': 'lingo', '.matho': 'matho', '.tex': 'matho', '.speco': 'speco', '.mojo': 'mojo', '.asm': 'asm', '.s': 'asm' };
const lang = LANG_OF[path.extname(file).toLowerCase()];
if (!lang) usage(`cannot tell the language of ${file} from its extension (${Object.keys(LANG_OF).join(', ')})`);
if (!fs.existsSync(file)) usage(`${file} does not exist`);
const { Workspace } = await import(dist('common/workspace.js'));
const text = fs.readFileSync(file, 'utf8');
const sources = { [lang]: text };
const speco = opt('speco');
if (speco) sources.speco = fs.readFileSync(speco, 'utf8');
const input = opt('input') ? fs.readFileSync(opt('input'), 'utf8') : '';
const ws = new Workspace({ sources, lang, call: opt('call') ?? null, input });
const out = (obj, lines) => { if (json) console.log(JSON.stringify(obj, null, 2)); else for (const l of lines) console.log(l); };
const where = (d) => `${file}:${d.line ?? 1}:${d.col ?? 1}`;
switch (cmd) {
case 'check': {
const ds = ws.diagnostics(lang);
out(ds, ds.length ? ds.map((d) => `${where(d)}: ${d.severity}: ${d.message}${d.id ? ` [${d.id}]` : ''}`) : [`${file}: no problems`]);
process.exit(ds.some((d) => d.severity === 'error') ? 1 : 0);
}
case 'run': {
const errors = ws.diagnostics(lang).filter((d) => d.severity === 'error');
if (errors.length) { out({ errors }, errors.map((d) => `${where(d)}: error: ${d.message}`)); process.exit(1); }
const tr = ws.trace();
if (!tr) { out({ error: ws.runError ?? 'nothing to run' }, [`pplus: ${ws.runError ?? 'nothing to run'}`]); process.exit(1); }
const lines = [...(tr.output ?? [])];
if (tr.error) lines.push(`stopped at line ${tr.error.line}: ${tr.error.message}`);
out({ output: tr.output, error: tr.error, steps: tr.count }, lines);
process.exit(tr.error ? 1 : 0);
}
case 'prove': {
if (lang !== 'pseudo') usage('prove reads a .pseudo file (with --speco for a separate spec)');
const p = ws.proof();
if (!p) { out({ error: 'the pseudo does not parse' }, ['pplus: the pseudo does not parse; run `pplus check` first']); process.exit(1); }
const { report } = p;
const lines = [];
for (const u of report.units) {
lines.push(`${u.name}${u.partial ? ' (partial: not every path was examined)' : ''}`);
for (const o of u.obligations) lines.push(` ${o.status.padEnd(6)} line ${String(o.line).padEnd(4)} ${o.label}`);
for (const n of u.notes) lines.push(` note: ${n}`);
}
lines.push(`${report.counts.proved} proved, ${report.counts.broken} broken, ${report.counts.open} open`);
out(report, lines);
process.exit(report.counts.broken ? 1 : 0);
}
case 'fuzz': {
const reports = ws.fuzz({ seed: Number(opt('seed') ?? 1), budget: Number(opt('budget') ?? 300) });
const lines = [];
for (const r of reports) {
if (r.problem) { lines.push(`${r.name}: ${r.problem}`); continue; }
lines.push(`${r.name}: ${r.cases.length} cases, ${r.failures.length} failure${r.failures.length === 1 ? '' : 's'}`);
for (const f of r.failures) lines.push(` ${f.call}: ${f.message}`);
}
out(reports.map((r) => ({ name: r.name, problem: r.problem, cases: r.cases.length, failures: r.failures })), lines.length ? lines : [`${file}: no routine to fuzz`]);
process.exit(reports.some((r) => r.failures.length) ? 1 : 0);
}
case 'translate': {
if (lang !== 'pseudo') usage('translate reads a .pseudo file');
const to = opt('to');
let result;
if (to === 'mojo') result = ws.derivedMojo();
else if (to === 'speco') { const { extractSpec } = await import(dist('services/speco.js')); result = { source: extractSpec(text) ?? '' }; }
else if (to === 'lingo' || to === 'matho') {
const { SyncHub } = await import(dist('sync/hub.js'));
const f = new SyncHub({ pseudo: text }).fill();
result = { source: f.sources[to] ?? '', stale: f.stale[to] };
} else usage('--to must be mojo, lingo, matho or speco');
if (result.stale) { out({ refused: result.stale }, [`pplus: ${to} cannot say this program: ${result.stale}`]); process.exit(1); }
if (json) console.log(JSON.stringify(result, null, 2)); else process.stdout.write(result.source.endsWith('\n') ? result.source : result.source + '\n');
process.exit(0);
}
default: usage(`unknown command ${cmd}`);
}
+112
View File
@@ -0,0 +1,112 @@
#!/usr/bin/env python3
"""Dafny, pinned: fetch the release this project uses, check it, and run it.
pixi run dafny-fetch download Dafny into .tools/ once (network), checked by SHA-256
pixi run dafny verify file.dfy run the pinned Dafny (fetches first if it is missing)
pixi run dafny --version
Dafny is not on conda-forge, so pixi cannot install it directly; this script is the pin instead. It downloads the
official release zip for this machine from GitHub, refuses it unless its SHA-256 is the one written below, and unpacks
it into .tools/dafny-<version>/ (ignored by git). The zip is self-contained: it carries its own .NET runtime and the Z3
builds Dafny was tested with, so the solver is pinned too. To move to another Dafny, change VERSION and every hash in
RELEASES in one commit, and expect every stored proof answer to be asked again.
Standard library only, like the corpus pipeline.
"""
from __future__ import annotations
import hashlib
import os
import platform
import shutil
import stat
import subprocess
import sys
import urllib.request
import zipfile
from pathlib import Path
VERSION = "4.11.0"
# platform -> (release asset, SHA-256 of the zip)
RELEASES = {
("Linux", "x86_64"): ("dafny-4.11.0-x64-ubuntu-22.04.zip", "a46a9ff7cdd720f7955854c78e95df13f4cfe6b80691b05f8654fe19e8267179"),
("Darwin", "arm64"): ("dafny-4.11.0-arm64-macos-13.zip", "c90c75e7d5db9c6ccbb7127840dfe43f0ac938b039a7ebed146d8ead383a572f"),
}
URL = "https://github.com/dafny-lang/dafny/releases/download/v{version}/{asset}"
ROOT = Path(__file__).resolve().parent.parent
TOOLS = ROOT / ".tools"
HOME = TOOLS / f"dafny-{VERSION}"
EXE = HOME / "dafny" / "dafny"
def release(system: str | None = None, machine: str | None = None) -> tuple[str, str]:
key = (system or platform.system(), machine or platform.machine())
if key not in RELEASES:
raise SystemExit(f"dafny: no pinned Dafny {VERSION} for {key[0]} {key[1]}; the pinned platforms are "
+ ", ".join(f"{s} {m}" for s, m in RELEASES))
return RELEASES[key]
def sha256(path: Path) -> str:
h = hashlib.sha256()
with path.open("rb") as f:
for block in iter(lambda: f.read(1 << 20), b""):
h.update(block)
return h.hexdigest()
def unpack(zip_path: Path, into: Path) -> None:
"""Unzip, keeping each file's Unix permission bits (zipfile drops them), so dafny and z3 stay executable."""
with zipfile.ZipFile(zip_path) as z:
for info in z.infolist():
target = into / info.filename
z.extract(info, into)
mode = (info.external_attr >> 16) & 0o777
if mode and not info.is_dir():
os.chmod(target, mode | stat.S_IRUSR)
def fetch(quiet: bool = False) -> Path:
"""Make sure the pinned Dafny is in .tools/, and return its executable."""
if EXE.exists():
return EXE
asset, want = release()
TOOLS.mkdir(exist_ok=True)
zip_path = TOOLS / asset
if not zip_path.exists() or sha256(zip_path) != want:
url = URL.format(version=VERSION, asset=asset)
if not quiet:
print(f"dafny: downloading {url}", file=sys.stderr)
part = zip_path.with_suffix(".part")
with urllib.request.urlopen(url) as r, part.open("wb") as f:
shutil.copyfileobj(r, f)
part.replace(zip_path)
got = sha256(zip_path)
if got != want:
zip_path.unlink()
raise SystemExit(f"dafny: {asset} has SHA-256 {got}, not the pinned {want}; refusing it")
staging = TOOLS / f".dafny-{VERSION}.unpacking"
shutil.rmtree(staging, ignore_errors=True)
unpack(zip_path, staging)
staging.replace(HOME)
zip_path.unlink()
if not quiet:
print(f"dafny: Dafny {VERSION} is in {HOME.relative_to(ROOT)}", file=sys.stderr)
return EXE
def main(argv: list[str]) -> int:
if argv[:1] == ["fetch"]:
fetch()
print(subprocess.run([str(EXE), "--version"], capture_output=True, text=True).stdout.strip())
return 0
if argv[:1] == ["path"]:
print(fetch(quiet=True))
return 0
exe = fetch()
return subprocess.run([str(exe), *argv]).returncode
if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))
+1 -9
View File
@@ -9,7 +9,7 @@
* 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;
* course's copy (the course's stylesheets are compared in pplus-web);
* 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.
@@ -26,8 +26,6 @@ if (!dir || !fs.existsSync(path.join(dir, 'js'))) {
process.exit(2);
}
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);
/** Lines changed, whitespace ignored: the size of the symmetric difference of the two line multisets. */
@@ -67,12 +65,6 @@ for (const d of ENGINE_DIRS) {
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)) {
const a = path.join(ROOT, 'styles/course', f), b = path.join(dir, course);
const label = `styles/course/${f}`;
if (!fs.existsSync(b)) rows.push([label, 'missing in the course']);
else { const r = compare(a, b); rows.push([label, r.kind === 'content' ? `differs: ${r.n} lines` : r.kind === 'whitespace' ? 'whitespace only' : 'same']); }
}
const w = Math.max(...rows.map((r) => r[0].length));
for (const [f, v] of rows) console.log(`${f.padEnd(w)} ${v}`);
+3 -3
View File
@@ -9,7 +9,7 @@ pin and the corpus, so they cannot drift.
src/mojo/generated/tokens.ts the words of the language, from corpus/tokens/tokens.json
src/mojo/generated/editor.ts comment and indentation rules, from corpus/editor/editor.json
src/mojo/generated/programs.ts our own programs (mojo/local/), each with its verdict from the goldens
quarto/_extensions/pplus/syntax/mojo.xml the same words, as a KDE syntax for Pandoc listings (kde.py)
syntax/mojo.xml the same words, as a KDE syntax for Pandoc listings (kde.py); pplus-web copies it into its Quarto extension
"""
from __future__ import annotations
@@ -20,7 +20,7 @@ from pathlib import Path
from .common import CORPUS, GENERATED_TS, REPO, Pin, PipelineError, load_lock, read_json, write_text
from .kde import mojo_xml
QUARTO_SYNTAX = REPO / "quarto" / "_extensions" / "pplus" / "syntax"
SYNTAX_DIR = REPO / "syntax" # pplus-web copies it into its Quarto extension (its quarto-css task)
BANNER = "// Generated by scripts/mojo/corpus.py emit. Do not edit; change mojo/pin.json or re-harvest.\n"
@@ -29,7 +29,7 @@ def ts(value) -> str:
return json.dumps(value, ensure_ascii=False, indent=4).replace("\n", "\n")
def emit(pin: Pin, out_dir: Path = GENERATED_TS, corpus: Path = CORPUS, syntax_dir: Path = QUARTO_SYNTAX) -> list[Path]:
def emit(pin: Pin, out_dir: Path = GENERATED_TS, corpus: Path = CORPUS, syntax_dir: Path = SYNTAX_DIR) -> list[Path]:
written = []
lock = load_lock()
commits = {k: (v.get("commit") or f"local:{v.get('sha256', '')[:12]}") for k, v in lock.get("sources", {}).items()}
+3 -3
View File
@@ -362,12 +362,12 @@ class CommittedCorpusTests(unittest.TestCase):
committed = (common.GENERATED_TS / f).read_text(encoding="utf-8")
self.assertEqual((Path(d) / f).read_text(encoding="utf-8"), committed,
f"src/mojo/generated/{f} is stale; run `python3 scripts/mojo/corpus.py emit`")
self.assertEqual((Path(d) / "mojo.xml").read_text(encoding="utf-8"), (emit_ts.QUARTO_SYNTAX / "mojo.xml").read_text(encoding="utf-8"),
"quarto/_extensions/pplus/syntax/mojo.xml is stale; run `python3 scripts/mojo/corpus.py emit`")
self.assertEqual((Path(d) / "mojo.xml").read_text(encoding="utf-8"), (emit_ts.SYNTAX_DIR / "mojo.xml").read_text(encoding="utf-8"),
"syntax/mojo.xml is stale; run `python3 scripts/mojo/corpus.py emit`")
def test_the_quarto_syntax_is_well_formed_with_the_1_1_0_words(self):
import xml.etree.ElementTree as ET
root = ET.parse(emit_ts.QUARTO_SYNTAX / "mojo.xml").getroot()
root = ET.parse(emit_ts.SYNTAX_DIR / "mojo.xml").getroot()
lists = {l.get("name"): [i.text for i in l] for l in root.iter("list")}
self.assertIn("def", lists["keywords"])
self.assertNotIn("fn", lists["keywords"])
+43
View File
@@ -0,0 +1,43 @@
#!/usr/bin/env python3
"""Zip the repository for sharing: the files git tracks, plus new files it does not ignore.
pixi run package # writes package/pplus-core-<commit>.zip
Nothing git ignores goes in: no .DS_Store, __pycache__, scratch/, dist/, site/, node_modules/ or
.pixi/. Files are stored under a top folder named pplus-core/.
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")) - {""})
names = [n for n in names if (ROOT / n).is_file()]
out_dir = ROOT / "package"
out_dir.mkdir(exist_ok=True)
out = out_dir / f"pplus-core-{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"pplus-core/{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())
+47
View File
@@ -0,0 +1,47 @@
"""The Dafny pin, offline: every pinned platform has a release and a hash, an unpinned one is refused, and unpacking
keeps the executable bits Dafny and Z3 need."""
import os
import stat
import sys
import tempfile
import unittest
import zipfile
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
import dafny # noqa: E402
class Pin(unittest.TestCase):
def test_every_pinned_platform_names_this_version_and_a_sha256(self):
self.assertTrue(dafny.RELEASES)
for (system, machine), (asset, digest) in dafny.RELEASES.items():
self.assertIn(dafny.VERSION, asset, f"{system} {machine}")
self.assertRegex(digest, r"^[0-9a-f]{64}$", f"{system} {machine}")
def test_the_two_platforms_pixi_pins_are_covered(self):
self.assertIn(("Linux", "x86_64"), dafny.RELEASES)
self.assertIn(("Darwin", "arm64"), dafny.RELEASES)
def test_an_unpinned_platform_is_refused_by_name(self):
with self.assertRaises(SystemExit) as e:
dafny.release("Plan9", "mips")
self.assertIn("Plan9 mips", str(e.exception))
class Unpack(unittest.TestCase):
def test_unpacking_keeps_executable_bits(self):
with tempfile.TemporaryDirectory() as d:
z = Path(d) / "a.zip"
with zipfile.ZipFile(z, "w") as w:
info = zipfile.ZipInfo("dafny/dafny")
info.external_attr = (0o755 | stat.S_IFREG) << 16
w.writestr(info, "#!/bin/sh\n")
w.writestr("dafny/readme.txt", "text")
dafny.unpack(z, Path(d) / "out")
self.assertTrue(os.access(Path(d) / "out/dafny/dafny", os.X_OK))
self.assertTrue((Path(d) / "out/dafny/readme.txt").exists())
if __name__ == "__main__":
unittest.main()