Files
pplus-web/core/tests/practices.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

146 lines
8.8 KiB
JavaScript

// Stage 13a/13d: the best-practices rules. Every rule is held to its own example (the before and after both read,
// run, and print the same; applying the rule to the before gives the after), to the harvested standard-library
// index (every method a rewrite names exists), and to Modular's own tested programs (it must stay quiet there,
// within a small allowlist). Findings are always notes; applying every fix keeps a program passing the checker
// and printing what it printed.
import test from 'node:test';
import assert from 'node:assert/strict';
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { RULES, findPractices, applyPractices, applyQuickFix, practiceDiagnostics, PRACTICES_ORIGIN } from '../dist/mojo/practices.js';
import { checkMojo } from '../dist/mojo/check.js';
import { runMojo } from '../dist/mojo/interp.js';
import { pseudoToMojo } from '../dist/sync/pseudo-to-mojo.js';
import { programs } from './helpers/sync-programs.mjs';
import { EXERCISES } from '../dist/exercises/index.js';
const here = path.dirname(fileURLToPath(import.meta.url));
const root = path.join(here, '..');
const errorsOf = (s) => checkMojo(s).diagnostics.filter((d) => d.severity === 'error');
const run = (s) => { const m = checkMojo(s); return runMojo(m.module, s); };
test('each rule\'s example: both programs read, run, and print the same; the rule fires on the before and not the after', () => {
const ids = new Set();
for (const r of RULES) {
assert.ok(!ids.has(r.id), `duplicate rule ${r.id}`); ids.add(r.id);
assert.ok(r.title && r.why && r.docUrl.startsWith('https://mojolang.org/docs/manual/'), r.id);
const { before, after, beforeRefused } = r.example;
if (beforeRefused) assert.ok(errorsOf(before).some((d) => d.message.includes(beforeRefused)), `${r.id}: the compiler should refuse the before`);
else assert.deepEqual(errorsOf(before), [], `${r.id}: before`);
assert.deepEqual(errorsOf(after), [], `${r.id}: after`);
const a = run(after);
assert.equal(a.refused, null, `${r.id}: the interpreter runs the after (${a.refused})`);
if (!beforeRefused) {
const b = run(before);
assert.equal(b.refused, null, `${r.id}: the interpreter runs the before (${b.refused})`);
assert.equal(a.stdout, b.stdout, `${r.id}: same output`);
}
assert.ok(findPractices(before).some((f) => f.rule === r.id), `${r.id}: fires on the before`);
assert.ok(!findPractices(after).some((f) => f.rule === r.id), `${r.id}: quiet on the after`);
const first = findPractices(before).find((f) => f.rule === r.id);
if (first.fix) assert.equal(applyPractices(before, new Set([r.id])).source, after, `${r.id}: the fix turns the before into the after`);
else assert.equal(r.id, 'comptime-constant', 'only a rule that cannot promise the rewrite goes without a fix');
}
});
test('grounding: every standard-library method a rewrite names is in the harvested index', () => {
const index = JSON.parse(fs.readFileSync(path.join(root, 'mojo', 'corpus', 'stdtypes', 'stdtypes.json'), 'utf8')).structs;
let n = 0;
for (const r of RULES) for (const [type, method] of r.apis) { n++; assert.ok(index[type]?.methods.includes(method), `${r.id}: ${type}.${method}`); }
assert.ok(n >= 4);
});
function mojoFiles(dir, out = []) {
for (const f of fs.readdirSync(dir, { withFileTypes: true })) {
const p = path.join(dir, f.name);
if (f.isDirectory()) mojoFiles(p, out); else if (p.endsWith('.mojo')) out.push(p);
}
return out;
}
// What the rules say about Modular's own programs, which are tested and often written to teach one thing at a time
// (a variable declared apart from its value to show how `var` works, `imm` written out to name the convention). Each
// number is a reviewed count; a rule that starts firing more than this on code that is already good is too noisy.
const ALLOWED = { 'declare-then-assign': 10, 'augmented-assign': 6, 'argument-convention': 4, 'unneeded-raises': 3, 'comptime-constant': 3, 'codepoint-loop': 0, 'reserve': 2, 'transfer-last-use': 2, 'explicit-copy': 0 };
test('false-positive gate: over mojo/corpus/manual/ the rules fire no more than the reviewed allowlist', () => {
const files = mojoFiles(path.join(root, 'mojo', 'corpus', 'manual'));
assert.ok(files.length >= 100, `${files.length} programs`);
const counts = {};
for (const f of files) for (const x of findPractices(fs.readFileSync(f, 'utf8'))) counts[x.rule] = (counts[x.rule] ?? 0) + 1;
for (const r of RULES) assert.ok((counts[r.id] ?? 0) <= ALLOWED[r.id], `${r.id} fired ${counts[r.id] ?? 0} times on Modular's programs (allowed ${ALLOWED[r.id]})`);
});
test('findings are notes from "best practices", never errors or warnings, and a source that does not read gets none', () => {
for (const p of programs().filter((x) => x.id.startsWith('ex:'))) {
const r = pseudoToMojo(p.pseudo, { call: p.call });
if ('unsupported' in r) continue;
for (const d of practiceDiagnostics(r.source)) {
assert.equal(d.severity, 'note', p.id);
assert.equal(d.origin, PRACTICES_ORIGIN);
assert.ok(d.id.startsWith('practice-') && d.docUrl && d.message, p.id);
}
}
assert.deepEqual(findPractices('def main(:\n var x: Int\n x = 1\n'), []);
});
test('count-base: the literal translation draws the declare-then-assign, += and codepoint-loop findings', () => {
const ex = EXERCISES.find((e) => e.id === 'count-base');
const src = pseudoToMojo(ex.sources.pseudo, { call: ex.call }).source;
const found = new Set(findPractices(src).map((f) => f.rule));
for (const id of ['declare-then-assign', 'augmented-assign', 'codepoint-loop']) assert.ok(found.has(id), id);
const loop = findPractices(src).find((f) => f.rule === 'codepoint-loop');
assert.ok(loop.pseudoHint && /FOR EACH/.test(loop.pseudoHint));
// the same code pasted anywhere (the Developer area) draws the same findings
assert.deepEqual(new Set(findPractices(src.split('\n').slice(1).join('\n')).map((f) => f.rule)), found);
});
test('idiomatic version: for every exercise the safe rewrites keep the program checking and printing the same', () => {
let changed = 0, compared = 0;
for (const p of programs().filter((x) => x.id.startsWith('ex:'))) {
const r = pseudoToMojo(p.pseudo, { call: p.call });
if ('unsupported' in r) continue;
const { source, applied } = applyPractices(r.source);
if (!applied.length) { assert.equal(source, r.source); continue; }
changed++;
assert.ok(errorsOf(source).length <= errorsOf(r.source).length, `${p.id}: the rewrite introduced an error`);
const a = run(r.source), b = run(source);
if (a.refused === null && b.refused === null) { compared++; assert.equal(b.stdout, a.stdout, `${p.id}: same output`); }
else assert.equal(b.refused === null, a.refused === null, `${p.id}: the interpreter should run both or neither (${a.refused} / ${b.refused})`);
assert.ok(source.startsWith(r.source.split('\n')[0]), `${p.id}: the header comment stays`);
}
assert.ok(changed >= 5 && compared >= 5, `${changed} changed, ${compared} compared`);
});
test('Developer area: applying every fix to each mojo/local program keeps it checking and printing the same', () => {
const dir = path.join(root, 'mojo', 'local');
let fired = 0;
for (const f of fs.readdirSync(dir).filter((x) => x.endsWith('.mojo'))) {
const src = fs.readFileSync(path.join(dir, f), 'utf8');
const { source, applied } = applyPractices(src);
fired += applied.length;
assert.ok(errorsOf(source).length <= errorsOf(src).length, `${f}: an error appeared`);
const a = run(src), b = run(source);
if (a.refused === null) { assert.equal(b.refused, null, `${f}: ${b.refused}`); assert.equal(b.stdout, a.stdout, f); }
}
assert.ok(fired >= 1, 'the rules find something to say somewhere in the exercises\' own programs');
});
test('a fix is the edit the editor makes: whole lines, from line to endLine', () => {
const src = 'a\nb\nc\nd\n';
assert.equal(applyQuickFix(src, { label: '', line: 2, endLine: 3, col: 1, endCol: null, text: 'X\nY\nZ' }), 'a\nX\nY\nZ\nd\n');
});
test('every exercise\'s generated Mojo has its findings pinned (UPDATE_SNAPSHOTS=1 rewrites them for review)', () => {
const file = path.join(here, 'snapshots', 'practices.json');
const now = {};
for (const p of programs().filter((x) => x.id.startsWith('ex:'))) {
const r = pseudoToMojo(p.pseudo, { call: p.call });
if ('unsupported' in r) continue;
now[p.name] = findPractices(r.source).map((f) => `${f.line}${f.endLine ? '-' + f.endLine : ''} ${f.rule}`);
}
if (process.env.UPDATE_SNAPSHOTS) fs.writeFileSync(file, JSON.stringify(now, null, 2) + '\n');
assert.ok(fs.existsSync(file), 'no snapshot; run with UPDATE_SNAPSHOTS=1 and review the new file');
assert.deepEqual(now, JSON.parse(fs.readFileSync(file, 'utf8')), 'the findings for a generated program changed; if the change is wanted, run with UPDATE_SNAPSHOTS=1 and review the diff');
});