Files
pplus-web/tests/hardware.test.mjs
T
alexmandClaude 82e18f7966 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
2026-10-05 05:43:58 +00:00

210 lines
12 KiB
JavaScript

// Stage 15: the Hardware area's machine board. The course's views draw it (src/engines/asm86/views.js and
// hwviews.js) and need a DOM, so they are checked by hand; what they are given is decided DOM-free in
// core/hardware.ts and is tested here, for every problem that has assembly: which views each preset mounts and with
// what options, and the frame each one draws at every step.
import test from 'node:test';
import assert from 'node:assert/strict';
import { themeBodyClass } from '../dist/ui/theme.js';
import { BOARD_PRESETS, BOARD_VIEWS, BOARD_GROUPS, MACHINE_PRESETS, boardPreset, boardView, boardFrame, subRegisterWidths, normalizeBoard, presetOf, moveItem, addItem, removeItem, toggleWide, isWide, courseViews, parseMachine, machineName, machineSpec, machineLabel, lineTouches, asmMojoLines, relateAsmMojo } from '../dist/core/hardware.js';
import { stageOccupancy, STAGES } from '../core/dist/engines/asm86/pipeline.js';
import { coreAt } from '../core/dist/engines/asm86/ooo.js';
import { decompose } from '../core/dist/engines/asm86/uops.js';
import fs from 'node:fs';
import { stripHeader, buildListing } from '../core/scripts/mojo/listings.mjs';
import { forSimulator, simulatorSetup } from '../core/dist/mojo/att.js';
import { listingFunctions } from '../core/dist/services/godbolt.js';
import { hardwareFor, resolveMachine } from '../core/dist/engines/asm86/machine.js';
import { viewNames } from '../core/dist/engines/asm86/views.js';
import { PROBLEMS, stateForProblem } from '../dist/core/catalog.js';
import { Session } from '../dist/core/session.js';
import { normalize, emptyState } from '../dist/core/state.js';
import { SERVICES } from '../core/dist/services/index.js';
globalThis.localStorage = { getItem() { return null; }, setItem() { }, removeItem() { } };
/** Every catalog problem with an x86-64 pane, run as the Hardware area runs it. */
const WITH_ASM = PROBLEMS.filter((p) => (p.sources?.asm ?? '').trim());
const traceOf = (p, machine) => {
const st = stateForProblem(p);
if (machine) st.machine = machine;
st.lang = 'asm';
const s = new Session(st, { area: 'hw', storageId: null });
const tr = s.trace();
assert.ok(tr && tr.lang === 'asm', `${p.id}: the x86-64 pane runs`);
return { session: s, tr, raw: tr.raw.trace };
};
test('the body class follows what the page shows: the setting, the system, or a host page that forces one', () => {
assert.equal(themeBodyClass('light', true), 'quarto-light', 'a light app on a dark system draws light widgets');
assert.equal(themeBodyClass('dark', false), 'quarto-dark');
assert.equal(themeBodyClass('system', true), 'quarto-dark');
assert.equal(themeBodyClass('system', false), 'quarto-light');
for (const setting of ['light', 'dark', 'system']) for (const sys of [true, false]) {
assert.equal(themeBodyClass(setting, sys, 'dark'), 'quarto-dark', 'an embed\'s ?theme= (or the host\'s switch) wins');
assert.equal(themeBodyClass(setting, sys, 'light'), 'quarto-light');
}
});
test('every card the board offers is a course view or one of the app\'s own, in a group, and every preset is made of them', () => {
const known = new Set(viewNames());
const APP = new Set(['setup', 'output', 'problems', 'compiler', 'run', 'counters', 'lines']);
assert.ok(WITH_ASM.length >= 10, 'the problems with assembly are found');
assert.equal(new Set(BOARD_VIEWS.map((v) => v.id)).size, BOARD_VIEWS.length, 'each card once');
for (const v of BOARD_VIEWS) {
assert.ok(BOARD_GROUPS.includes(v.group), `${v.id}: a group of the add menu`);
assert.ok(v.label && v.blurb, `${v.id}: a label and a line saying what it shows`);
if (v.course) assert.ok(known.has(v.course.name), `${v.id} mounts "${v.course.name}", which views.js does not have`);
else assert.ok(APP.has(v.id), `${v.id}: drawn by the app`);
}
for (const preset of BOARD_PRESETS) {
assert.ok(preset.items.length >= 3 && preset.items.every((it) => boardView(it.id)), `${preset.id}: cards that exist`);
assert.equal(presetOf(preset.items), preset.id, 'a preset is recognized as itself');
for (const p of WITH_ASM) {
const { raw } = traceOf(p);
for (const machine of ['teaching', 'teaching+paging']) for (const c of courseViews(preset.items, raw, parseMachine(machine))) {
assert.ok(known.has(c.name));
assert.equal(typeof c.options, 'object', `${preset.id}/${c.id}: options for ${p.id}`);
}
}
}
assert.equal(boardPreset(undefined).id, 'regs', 'the board opens on registers and memory');
assert.equal(boardPreset('nonsense').id, 'regs');
assert.ok(BOARD_PRESETS.some((p) => p.items.some((it) => it.id === 'run')), 'a preset for the Mojo side');
});
test('the student\'s own arrangement: move, add, remove, widen, and what a saved one may hold', () => {
const regs = boardPreset('regs').items;
const moved = moveItem(regs, regs.length - 1, 0);
assert.equal(moved[0].id, regs[regs.length - 1].id);
assert.equal(moved.length, regs.length);
assert.equal(presetOf(moved), null, 'a changed arrangement is the student\'s own');
assert.deepEqual(moveItem(moved, 0, regs.length - 1).map((x) => x.id), regs.map((x) => x.id), 'and moves back');
assert.deepEqual(moveItem(regs, 9, 0), regs, 'a move from nowhere changes nothing');
const added = addItem(regs, 'pipeline', 0);
assert.equal(added[0].id, 'pipeline');
assert.deepEqual(addItem(added, 'pipeline'), added, 'a card is on the board once');
assert.deepEqual(addItem(regs, 'warp-drive'), regs, 'an unknown card is not added');
assert.ok(!removeItem(added, 'pipeline').some((x) => x.id === 'pipeline'));
const flags = regs.find((x) => x.id === 'flags');
assert.equal(isWide(toggleWide(regs, 'flags').find((x) => x.id === 'flags')), !isWide(flags));
assert.deepEqual(normalizeBoard([{ id: 'flags', wide: true }, 'memory', { id: 'flags' }, { id: 'nope' }, 7, null]), [{ id: 'flags', wide: true }, { id: 'memory' }], 'known cards, each once, widths kept');
assert.equal(normalizeBoard('regs'), undefined);
assert.equal(normalizeBoard(Array.from({ length: 40 }, () => 'flags')).length, 1);
assert.ok(normalizeBoard(BOARD_VIEWS.map((v) => v.id)).length <= 24, 'at most 24 cards');
// virtual memory's card mounts only with virtual memory on
const { raw } = traceOf(PROBLEMS.find((x) => x.id === 'asm-two-pointers'));
assert.deepEqual(courseViews([{ id: 'paging' }], raw, parseMachine('teaching')), []);
assert.equal(courseViews([{ id: 'paging' }], raw, parseMachine('teaching+paging')).length, 1);
});
test('the frame at every step is the one the course views expect, for every problem with assembly', () => {
for (const p of WITH_ASM) {
const { raw } = traceOf(p);
for (let t = -1; t <= raw.count + 1; t++) {
const f = boardFrame(raw, t);
const tt = Math.max(0, Math.min(t, raw.count));
assert.equal(f.t, tt);
assert.equal(f.state, raw.states[tt]);
assert.equal(f.last, tt ? raw.steps[tt - 1] : null, `${p.id}: the step that just ran`);
if (f.next) assert.equal(f.next, raw.program.instrs[f.state.pc]);
}
}
});
test('the register cards show every width the program uses', () => {
const asm = SERVICES.asm.parse(' mov eax, 7\n mov cl, byte ptr [rdi]\n add r8d, 1\n mov rbx, rsi\n ret');
assert.ok(asm.ok);
assert.deepEqual(new Set(subRegisterWidths(asm.program)), new Set(['rax', 'rcx', 'r8']), 'rbx and rsi are only used whole');
const widths = PROBLEMS.find((p) => p.id === 'asm-register-widths');
assert.ok(widths, 'the register-widths problem exists');
const { raw } = traceOf(widths);
assert.ok(subRegisterWidths(raw.program).length > 1, 'its registers show their narrower names');
});
test('the arrangement is part of the area\'s layout and normalizes', () => {
const st = emptyState();
st.layout = { hw: { board: [{ id: 'cache', wide: false }, 'flags'], dock: 0.5 } };
assert.deepEqual(normalize(JSON.parse(JSON.stringify(st))).layout.hw.board, [{ id: 'cache', wide: false }, { id: 'flags' }]);
st.layout = { hw: { board: 'warp-drive' } };
assert.equal(normalize(JSON.parse(JSON.stringify(st))).layout.hw.board, undefined);
const s = new Session(emptyState(), { area: 'hw', storageId: null });
s.setLayout({ board: [{ id: 'counters' }] });
assert.deepEqual(s.layout().board, [{ id: 'counters' }]);
});
test('each load and store shows the line it touched and how much of the line the program uses', () => {
let touched = 0, missed = 0, partial = 0;
for (const p of WITH_ASM) for (const machine of ['teaching', 'realistic', 'teaching+paging']) {
const { raw } = traceOf(p, machine);
const hw = hardwareFor(raw);
const L = hw.memory().hierarchy.line;
assert.deepEqual(lineTouches(hw, 0), [], 'nothing has run at step 0');
for (let t = 1; t <= raw.count; t++) {
const step = raw.steps[t - 1];
const xs = lineTouches(hw, t);
if (!machine.includes('paging')) {
// without virtual memory the caches see the program's own addresses: every access of the step is there
const want = step.accesses.reduce((n, a) => n + (Math.floor((a.addr + Math.max(1, a.size) - 1) / L) - Math.floor(a.addr / L) + 1), 0);
assert.equal(xs.length, want, `${p.id} step ${t}: one entry per line per access`);
}
for (const x of xs) {
touched++;
if (!x.hit) missed++;
assert.equal(x.lineSize, L);
assert.equal(x.lineAddr % L, 0);
assert.ok(x.from >= 0 && x.from < x.to && x.to <= L, `${p.id} step ${t}: the bytes are inside the line`);
assert.equal(x.hit, x.level === 'L1d', 'a hit is a line found in L1d');
for (let b = x.from; b < x.to; b++) assert.ok(x.usedSoFar.includes(b), 'the bytes used now count as used');
assert.ok(x.usedSoFar.every((b) => x.usedInRun.includes(b)), 'used so far is part of used in the run');
assert.ok(x.usedInRun.length <= L);
if (x.usedInRun.length < L) partial++;
if (!machine.includes('paging')) assert.equal(x.vaddr, x.addr);
}
}
}
assert.ok(touched > 50, 'the problems load and store');
assert.ok(missed > 0, 'the teaching machine misses on small data');
assert.ok(partial > 0, 'some lines are only partly used, which is what the view is for');
});
test('virtual memory: the line is the physical one, and the access keeps the address the program wrote', () => {
const p = PROBLEMS.find((x) => x.id === 'asm-two-pointers');
const { raw } = traceOf(p, 'teaching+paging');
const hw = hardwareFor(raw);
const all = [];
for (let t = 1; t <= raw.count; t++) all.push(...lineTouches(hw, t).map((x) => ({ x, step: raw.steps[t - 1] })));
assert.ok(all.length);
for (const { x, step } of all) assert.ok(step.accesses.some((a) => x.vaddr >= a.addr && x.vaddr < a.addr + Math.max(1, a.size)), 'the virtual address is one the instruction used');
assert.ok(all.some(({ x }) => x.vaddr !== x.addr), 'and at least one is translated to another physical address');
});
test('Mojo beside x86-64: the line table the compiler left in the pane links each instruction to its Mojo line', () => {
const asm = 'add: ; add(Int, Int)\n mov rax, rdi ; mojo line 2\n add rax, rsi ; mojo line 2\n ret\n call add ; mojo line 6';
assert.deepEqual([...asmMojoLines(asm)], [[2, 2], [3, 2], [5, 6]]);
assert.deepEqual(relateAsmMojo(asm, 'asm', 3), [2]);
assert.deepEqual(relateAsmMojo(asm, 'asm', 4), [], 'an instruction the compiler added belongs to no line');
assert.deepEqual(relateAsmMojo(asm, 'mojo', 2), [2, 3]);
assert.deepEqual(relateAsmMojo(asm, 'mojo', 9), []);
assert.equal(asmMojoLines(' mov rax, 7 ; a constant\n ret').size, 0, 'hand-written x86-64 is not linked');
// a real listing, as Open in Hardware makes it from godbolt's saved answer
const ROOT = new URL('..', import.meta.url).pathname;
let checked = 0;
for (const f of fs.readdirSync(ROOT + 'core/mojo/probes').filter((x) => x.endsWith('.mojo'))) {
const text = fs.readFileSync(ROOT + 'core/mojo/probes/' + f, 'utf8');
if (!/^# mode: (asm|both)/m.test(text)) continue;
const r = buildListing(text, ROOT + 'core/mojo/golden', { forSimulator, simulatorSetup, listingFunctions });
if (r.why) continue;
const table = asmMojoLines(r.asm);
if (!table.size) continue;
checked++;
const mojoLines = stripHeader(text).source.split('\n');
for (const [a, m] of table) {
assert.ok(m >= 1 && m <= mojoLines.length, `${f}: x86-64 line ${a} points at Mojo line ${m}, inside the program`);
assert.ok(relateAsmMojo(r.asm, 'mojo', m).includes(a), `${f}: and back`);
}
}
assert.ok(checked >= 1, 'a committed listing carries a line table');
});