// 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'); });