@scientific-method/standard-checker 0.1.0 → 0.3.0

package/dist/checks/formats.js

@@ -0,0 +1,221 @@
+// The checks of a format entry: its fields, its layout and enumeration tables (including those kept
+// in value files), the status of each row, and its Kaitai definition's meta.
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { checkResolves, checkStatusCitations, completeReading, rowFacts, statusIndex } from "../evidence.js";
+import { asList, idsIn, kindOf } from "../ids.js";
+import { readCsv, tables } from "../markdown.js";
+import { BINARY_LAYOUT, CLAIM_STATUSES, ENUM_TABLE, ROW_STATUSES, TEXT_LAYOUT } from "../standard.js";
+/** The IDs cited in the last column of the tables of an entry's sections (of every section when sectionTitles is left out). */
+export function tableIds(e, sectionTitles) {
+    const ids = new Set();
+    for (const s of e.sections)
+        if (!sectionTitles || sectionTitles.includes(s.title))
+            for (const t of tables(s.text))
+                for (const r of t.rows)
+                    for (const x of idsIn(r[t.header.length - 1] ?? ""))
+                        ids.add(x);
+    return ids;
+}
+/** Checks a format entry, adding the names its tables define to formatNames. */
+export function checkFormat(ctx, e, formatNames) {
+    const { problem } = ctx;
+    const { entries, buildFiles } = ctx.spec;
+    const { enumNames, fieldNames, layouts } = formatNames;
+    const { file, meta } = e;
+    const id = meta.id;
+    const first = asList(meta.builds)[0];
+    if (meta.text === true) {
+        if (meta.definition !== null || meta.size !== null || meta.byte_order !== null)
+            problem(file, "a text format has definition, size and byte_order null");
+    }
+    else {
+        if (!["little", "big"].includes(meta.byte_order))
+            problem(file, "byte_order must be little or big for a binary format");
+        if (meta.status !== "unknown" && meta.status !== "superseded") {
+            const expected = `${id.toLowerCase().replaceAll("-", "_")}.ksy`;
+            if (meta.definition !== expected)
+                problem(file, `definition must be ${expected}`);
+            else if (!existsSync(join(dirname(file), expected)))
+                problem(file, `definition ${expected} does not exist`);
+        }
+    }
+    for (const pattern of asList(meta.files)) {
+        const re = new RegExp("^" +
+            String(pattern)
+                .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+                .replaceAll("*", "[^/]*")
+                .replaceAll("?", "[^/]") +
+            "$");
+        for (const b of asList(meta.builds))
+            if (!(buildFiles.get(b) ?? []).some((f) => re.test(f.path)))
+                problem(file, `files pattern ${pattern} matches no file of ${b}`);
+    }
+    const layout = e.sections.find((s) => s.title === "Layout");
+    const enums = e.sections.find((s) => s.title === "Enumerations and flags");
+    const names = new Set();
+    fieldNames.set(id, names);
+    let lowest = null;
+    let disputed = false;
+    const visit = (t, kindLabel) => {
+        const statusCol = t.header.indexOf("Status");
+        const evCol = t.header.indexOf("Evidence");
+        const nameCol = t.header.indexOf("Name");
+        for (const row of t.rows) {
+            if (row.length !== t.header.length) {
+                problem(file, `${kindLabel} row ${row.join(" | ")} has ${row.length} cells, not ${t.header.length}`);
+                continue;
+            }
+            const isTotal = (row[t.header.indexOf("Meaning")] ?? "").startsWith("Total") && (row[statusCol] ?? "") === "";
+            if (isTotal)
+                continue;
+            const st = row[statusCol];
+            if (!ROW_STATUSES.includes(st)) {
+                // STATUS-1 lists the statuses. That a row is never superseded is a rule of Formats, which has no
+                // numbered rules yet.
+                problem(file, `${kindLabel} row ${row[nameCol] ?? row[0]}: status ${st} is not allowed in a row`, CLAIM_STATUSES.includes(st) ? undefined : "STATUS-1");
+                continue;
+            }
+            if (st === "disputed")
+                disputed = true;
+            else if (lowest === null || statusIndex(st) < statusIndex(lowest))
+                lowest = st;
+            const ids = idsIn(row[evCol]);
+            checkResolves(ctx, file, ids, `${kindLabel} row ${row[nameCol] ?? row[0]}`);
+            const conflicting = ids.filter((x) => asList(meta.conflicting).includes(x));
+            checkStatusCitations(problem, file, st, rowFacts(entries, ids, first, completeReading(entries, e)), conflicting, `${kindLabel} row ${(row[nameCol] ?? row[0]).replaceAll("`", "")}: status`);
+            if (nameCol >= 0 && row[nameCol])
+                names.add(row[nameCol].replaceAll("`", ""));
+        }
+    };
+    // A row whose status is wrong still names a field, so the field checks of rules read every row.
+    const layoutTypes = new Map();
+    let wellFormed = true;
+    if (layout) {
+        const ts = tables(layout.text);
+        const wanted = meta.text === true ? TEXT_LAYOUT : BINARY_LAYOUT;
+        if (meta.status !== "unknown" && ts.length === 0)
+            problem(file, "Layout has no table");
+        for (const t of ts) {
+            if (t.header.join("|") !== wanted.join("|")) {
+                problem(file, `a layout table has the columns ${wanted.join(" | ")}`);
+                wellFormed = false;
+                continue;
+            }
+            visit(t, "layout");
+            const nameCol = t.header.indexOf("Name");
+            const typeCol = t.header.indexOf("Type");
+            for (const row of t.rows) {
+                // A row with the wrong number of cells may hold a field whose Name cell cannot be found.
+                if (row.length !== t.header.length) {
+                    wellFormed = false;
+                    continue;
+                }
+                if (!row[nameCol])
+                    continue;
+                // A cell that names more than one field, or a path into a field (`items[i].count`), still
+                // names the field it starts with, though not its type.
+                for (const name of (row[nameCol].match(/`[^`]+`/g) ?? [row[nameCol]]).map((n) => n.replaceAll("`", "").trim())) {
+                    const lead = /^[A-Za-z_][A-Za-z0-9_]*/.exec(name)?.[0];
+                    if (lead === name)
+                        layoutTypes.set(name, row[typeCol]);
+                    else if (lead && !layoutTypes.has(lead))
+                        layoutTypes.set(lead, "");
+                }
+            }
+        }
+    }
+    if (wellFormed)
+        layouts.set(id, layoutTypes);
+    // An enumeration table kept in a value file counts as one of the entry's tables.
+    const enumTables = enums ? [...tables(enums.text), ...valueFileTables(ctx, e, enums.text)] : [];
+    e.valueTables = enumTables.filter((t) => t.file);
+    for (const t of enumTables) {
+        if (t.header.join("|") !== ENUM_TABLE.join("|")) {
+            problem(t.file ?? file, `an enumeration table has the columns ${ENUM_TABLE.join(" | ")}`);
+            continue;
+        }
+        if (!t.heading)
+            problem(file, "an enumeration table sits under a ### heading naming its fields");
+        else
+            for (const f of (t.heading.match(/`([^`]+)`/g) ?? t.heading.split(/\s*,\s*|\s+and\s+/))
+                .map((x) => x.replaceAll("`", "").trim())
+                .filter(Boolean))
+                if (!names.has(f))
+                    problem(file, `enumeration heading names ${f}, which is not a field of the layout`);
+        visit(t, "enumeration");
+        for (const row of t.rows) {
+            if (row.length !== t.header.length)
+                continue; // visit reported it
+            const n = row[1].replaceAll("`", "");
+            if (!/^[A-Z][A-Z0-9_]*$/.test(n))
+                problem(file, `enumeration name ${n} must be upper-case letters, digits and underscores`);
+            if (!enumNames.has(n))
+                enumNames.set(n, []);
+            enumNames.get(n).push(id);
+        }
+    }
+    if (meta.status !== "superseded" && meta.status !== "unknown") {
+        const expected = disputed ? "disputed" : lowest;
+        if (expected && meta.status !== expected)
+            problem(file, `status must be ${expected}, the lowest status among its rows`);
+    }
+    const cited = tableIds(e, ["Layout", "Enumerations and flags"]);
+    for (const t of e.valueTables)
+        for (const row of t.rows)
+            for (const x of idsIn(row[t.header.length - 1]))
+                cited.add(x);
+    const listed = new Set([...asList(meta.evidence), ...asList(meta.conflicting)]);
+    for (const x of cited)
+        if (!listed.has(x) && ["FND", "EXP", "SRC"].includes(kindOf(x)))
+            problem(file, `${x} is cited in a table but not in evidence or conflicting`);
+    for (const t of tables(layout?.text ?? ""))
+        for (const row of t.rows)
+            for (const x of idsIn(row[t.header.indexOf("Meaning")]))
+                if (kindOf(x) === "RULE" && !asList(meta.related).includes(x))
+                    problem(file, `layout names ${x}; add it to related`, "ENTRY-TYPES-6");
+    // Kaitai definition
+    if (meta.definition && existsSync(join(dirname(file), meta.definition))) {
+        const ksy = readFileSync(join(dirname(file), meta.definition), "utf8");
+        const expectedId = id.toLowerCase().replaceAll("-", "_");
+        if (!new RegExp(`^\\s*id:\\s*${expectedId}\\s*$`, "m").test(ksy))
+            problem(join(dirname(file), meta.definition), `meta/id must be ${expectedId}`);
+        if (!/^\s*license:\s*\S+/m.test(ksy))
+            problem(join(dirname(file), meta.definition), "meta/license must name the licence");
+    }
+}
+// The enumeration tables an entry keeps in value files: each ### heading stays in the entry, followed
+// by a sentence naming its file, formats/<ID>.<table>.csv.
+function valueFileTables(ctx, e, text) {
+    const { problem } = ctx;
+    const out = [];
+    let heading = null;
+    let fence = false;
+    for (const line of text.split("\n")) {
+        if (/^(```|~~~)/.test(line))
+            fence = !fence;
+        if (fence)
+            continue;
+        const h = /^### (.+)$/.exec(line);
+        if (h) {
+            heading = h[1].trim();
+            continue;
+        }
+        for (const m of line.matchAll(/\b([A-Z]+-[A-Z0-9]+-\d{3,}\.[A-Za-z0-9_]+\.csv)\b/g)) {
+            // Another entry's value file holds that entry's rows, so it is not read as one of these.
+            if (!m[1].startsWith(`${e.meta.id}.`)) {
+                problem(e.file, `value file ${m[1]} belongs to another entry; an entry's value files are named ${e.meta.id}.<table>.csv`);
+                continue;
+            }
+            const path = join(dirname(e.file), m[1]);
+            if (!existsSync(path)) {
+                problem(e.file, `value file ${m[1]} does not exist`);
+                continue;
+            }
+            const csv = readCsv(path, problem);
+            if (csv)
+                out.push({ heading, header: csv.header, rows: csv.rows, file: path });
+        }
+    }
+    return out;
+}

package/dist/checks/kaitai.d.ts

@@ -0,0 +1,6 @@
+import type { Context } from "../context.ts";
+/**
+ * Checks that each .ksy file in spec/formats/ belongs to a format entry, and compiles them all with
+ * the Kaitai Struct compiler, warning when there is none. Does nothing with --no-ksy.
+ */
+export declare function compileKaitai(ctx: Context): void;

package/dist/checks/kaitai.js

@@ -0,0 +1,103 @@
+// Kaitai compilation: every definition in spec/formats/ belongs to a format entry and compiles.
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+/**
+ * Checks that each .ksy file in spec/formats/ belongs to a format entry, and compiles them all with
+ * the Kaitai Struct compiler, warning when there is none. Does nothing with --no-ksy.
+ */
+export function compileKaitai(ctx) {
+    const { problem } = ctx;
+    const { entries } = ctx.spec;
+    const { specDir, skipKsy } = ctx.config;
+    if (!skipKsy) {
+        const ksys = [];
+        const fd = join(specDir, "formats");
+        if (existsSync(fd))
+            for (const f of readdirSync(fd))
+                if (f.endsWith(".ksy"))
+                    ksys.push(join(fd, f));
+        for (const k of ksys) {
+            const id = basename(k, ".ksy")
+                .toUpperCase()
+                .replace(/^FMT_([A-Z0-9]+)_(\d+)$/, "FMT-$1-$2");
+            if (!entries.has(id))
+                problem(k, `belongs to no format entry (${id})`);
+        }
+        const compiler = findKaitai();
+        if (compiler && ksys.length) {
+            const out = mkdtempSync(join(tmpdir(), "ksy-check-"));
+            const fixed = [...compiler.args, "--target", "python", "--outdir", out, "--import-path", fd];
+            try {
+                for (const batch of kaitaiBatches([compiler.cmd, ...fixed], ksys)) {
+                    try {
+                        runTool(compiler.cmd, [...fixed, ...batch]);
+                    }
+                    catch (err) {
+                        const failure = err;
+                        problem(null, `Kaitai definitions do not compile:\n${String(failure.stdout ?? "")}${String(failure.stderr ?? "")}`);
+                    }
+                }
+            }
+            finally {
+                rmSync(out, { recursive: true, force: true });
+            }
+        }
+        else if (ksys.length)
+            console.warn("warning: no Kaitai Struct compiler found (set KSC or install kaitai-struct-compiler); definitions were not compiled.");
+    }
+}
+// cmd.exe takes a command line of at most 8,191 characters, and the compiler's .bat launcher adds
+// its class path to the arguments it is given. On Windows the definitions are compiled in batches
+// whose quoted command line stays under 4,000 characters. Every batch gets the same --import-path,
+// so imports between definitions still resolve.
+function kaitaiBatches(fixed, files) {
+    if (process.platform !== "win32")
+        return [files];
+    const limit = 4000;
+    const quoted = (a) => a.length + 3;
+    const start = fixed.reduce((n, a) => n + quoted(a), 0);
+    const batches = [];
+    let batch = [];
+    let length = start;
+    for (const f of files) {
+        if (batch.length > 0 && length + quoted(f) > limit) {
+            batches.push(batch);
+            batch = [];
+            length = start;
+        }
+        batch.push(f);
+        length += quoted(f);
+    }
+    if (batch.length > 0)
+        batches.push(batch);
+    return batches;
+}
+function findKaitai() {
+    if (process.env.KSC)
+        return { cmd: process.env.KSC, args: [] };
+    for (const cmd of ["kaitai-struct-compiler", "ksc"]) {
+        try {
+            runTool(cmd, ["--version"]);
+            return { cmd, args: [] };
+        }
+        catch { }
+    }
+    return null;
+}
+// On Windows the compiler is a .bat file, which only cmd.exe can run. Node's shell: true joins the
+// arguments without quoting them, so a path with a space would split. This quotes every argument
+// and hands cmd.exe the line as is. A % in an argument would still expand; paths here have none.
+function runTool(cmd, args) {
+    if (process.platform !== "win32")
+        return execFileSync(cmd, args, { stdio: "pipe" });
+    const line = [cmd, ...args].map((a) => `"${a}"`).join(" ");
+    // execFileSync hands its options to spawn, which reads windowsVerbatimArguments; the Node types
+    // leave it off ExecFileSyncOptions.
+    const verbatim = {
+        stdio: "pipe",
+        windowsVerbatimArguments: true,
+    };
+    return execFileSync(process.env.ComSpec ?? "cmd.exe", ["/d", "/s", "/c", `"${line}"`], verbatim);
+}

package/dist/checks/parity.d.ts

@@ -0,0 +1,30 @@
+import type { Context } from "../context.ts";
+import type { Deviation } from "./deviations.ts";
+/** The columns of a parity table. */
+export declare const PARITY_HEADER: string[];
+/** What the parity check read from parity/. */
+export interface Parity {
+    /** Spec ID -> the row's cells as written, and its file. */
+    rows: Map<string, {
+        cells: string[];
+        file: string;
+    }>;
+    /** How many rows have each Status and each Code. */
+    counts: {
+        status: Record<string, number>;
+        code: Record<string, number>;
+    };
+    /** Marked test file of a validated row -> the rows that list it. */
+    validatedTests: Map<string, Array<{
+        specId: string;
+        file: string;
+    }>>;
+    /** Whether PARITY.md still holds the rows, so the check leaves it alone. */
+    legacy: boolean;
+}
+/**
+ * Checks the rows in parity/ against the spec, the deviations and the code, and that each area is
+ * split exactly where the line limit requires. Then reports a live deviation that departs from no
+ * entry with a row.
+ */
+export declare function checkParity(ctx: Context, deviations: Map<string, Deviation>): Parity;

package/dist/checks/parity.js

@@ -0,0 +1,189 @@
+// The parity matrix. The parity rows live in parity/, one file per area, split by kind and then by
+// block where the limit requires it. PARITY.md holds the totals and is written by the check.
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { collectPlaceholders } from "../code-files.js";
+import { mayBeInterrupted, onlyEmulatedRuns } from "../evidence.js";
+import { markdownTree, walk } from "../files.js";
+import { areaOf, compareIds, kindOf } from "../ids.js";
+import { readText, tables } from "../markdown.js";
+import { LINE_LIMIT } from "../standard.js";
+import { blockOf, layout } from "../generate/layout.js";
+/** The columns of a parity table. */
+export const PARITY_HEADER = ["Spec ID", "Title", "Spec status", "Code", "Tests", "Deviations", "Status", "Notes"];
+/**
+ * Checks the rows in parity/ against the spec, the deviations and the code, and that each area is
+ * split exactly where the line limit requires. Then reports a live deviation that departs from no
+ * entry with a row.
+ */
+export function checkParity(ctx, deviations) {
+    const { problem } = ctx;
+    const { entries, areas } = ctx.spec;
+    const { repoDir } = ctx.config;
+    const parityDir = join(repoDir, "parity");
+    const parityRows = new Map(); // spec ID -> { cells, file }
+    const parityCounts = { status: {}, code: {} };
+    const validatedTests = new Map(); // marked test file of a validated row -> [{ specId, file }]
+    // A test file that reads the original's files through GAME_DIR says so with this comment. It runs
+    // only on a maintainer's machine, so its validated rows need it in VALIDATION.md; every other test
+    // runs in CI.
+    const NEEDS_GAME = /needs:\s*GAME_DIR/;
+    const needsGame = (p) => existsSync(p) && NEEDS_GAME.test(readFileSync(p, "utf8"));
+    // A PARITY.md that still holds the rows is left alone until they have moved, so the check does not
+    // overwrite them with the totals.
+    const legacyParity = existsSync(join(repoDir, "PARITY.md")) &&
+        tables(readText(join(repoDir, "PARITY.md"))).some((t) => t.header.join("|") === PARITY_HEADER.join("|"));
+    {
+        if (!existsSync(parityDir))
+            problem(null, "parity/ is missing");
+        if (legacyParity)
+            problem(join(repoDir, "PARITY.md"), "the rows move to parity/, one <AREA>.md per area, and the check writes PARITY.md");
+        const placeholders = collectPlaceholders(ctx.codeFiles());
+        const files = existsSync(parityDir) ? markdownTree(parityDir) : new Map();
+        walk(parityDir, (f) => {
+            if (!f.endsWith(".md") && basename(f) !== ".gitkeep")
+                problem(f, "is not a parity file; parity/ holds one <AREA>.md per area");
+        });
+        const byArea = new Map(); // area -> Map of path -> ids in the file
+        for (const [path, file] of files) {
+            const text = readText(file);
+            if (!text.startsWith(`# ${path}\n`))
+                problem(file, `opens with its path as a # heading: # ${path}`);
+            const [area, kind, block, ...rest] = path.split("/");
+            if (!areas.includes(area)) {
+                problem(file, `${area} is not an area in the area list`);
+                continue;
+            }
+            if (rest.length > 0 || (kind !== undefined && !["RULE", "FMT", "SCR"].includes(kind))) {
+                problem(file, "is not an area, kind or block file of parity/");
+                continue;
+            }
+            const ts = tables(text);
+            if (ts.length !== 1 || ts[0].header.join("|") !== PARITY_HEADER.join("|")) {
+                problem(file, `holds one table with the columns ${PARITY_HEADER.join(" | ")}`);
+                continue;
+            }
+            if (!byArea.has(area))
+                byArea.set(area, new Map());
+            const inFile = [];
+            byArea.get(area).set(path, inFile);
+            let previous = "";
+            for (const row of ts[0].rows) {
+                if (row.length !== PARITY_HEADER.length) {
+                    problem(file, `the row ${row.join(" | ")} has ${row.length} cells, not ${PARITY_HEADER.length}`);
+                    continue;
+                }
+                const cells = row.map((c) => c.replaceAll("`", "").trim());
+                const [specId, title, specStatus, code, tests, devs, status, notes] = cells;
+                if (parityRows.has(specId))
+                    problem(file, `${specId} has more than one row`);
+                parityRows.set(specId, { cells: row, file });
+                inFile.push(specId);
+                if (areaOf(specId) !== area || (kind && kindOf(specId) !== kind) || (block && blockOf(specId) !== block))
+                    problem(file, `${specId} does not belong in parity/${path}.md`);
+                if (compareIds(specId, previous) < 0)
+                    problem(file, `${specId} is out of ID order`);
+                previous = specId;
+                const e = entries.get(specId);
+                if (!e) {
+                    problem(file, `${specId} does not exist in the spec`);
+                    continue;
+                }
+                if (!["RULE", "FMT", "SCR"].includes(e.kind) || e.meta.status === "superseded")
+                    problem(file, `${specId} cannot have a row`);
+                if (title !== e.meta.title)
+                    problem(file, `${specId}: Title must be "${e.meta.title}"`);
+                if (specStatus !== e.meta.status)
+                    problem(file, `${specId}: Spec status must be ${e.meta.status}`);
+                if (!["missing", "partial", "complete"].includes(code))
+                    problem(file, `${specId}: Code must be missing, partial or complete`);
+                if (code === "complete" && e.meta.status === "unknown")
+                    problem(file, `${specId}: an unknown entry cannot be complete`);
+                if (code === "complete" && placeholders.has(specId))
+                    problem(file, `${specId}: a PLACEHOLDER comment cites it, so it cannot be complete`);
+                const testFiles = tests === "None"
+                    ? []
+                    : tests
+                        .split(",")
+                        .map((x) => x.trim())
+                        .filter(Boolean);
+                for (const tf of testFiles) {
+                    const p = join(repoDir, tf);
+                    if (!existsSync(p))
+                        problem(file, `${specId}: test file ${tf} does not exist`);
+                    else {
+                        const text = readFileSync(p, "utf8");
+                        if (!text.includes(specId))
+                            problem(file, `${specId}: test file ${tf} does not mention ${specId}`);
+                        if (text.includes("GAME_DIR") && !NEEDS_GAME.test(text))
+                            problem(file, `${specId}: test file ${tf} mentions GAME_DIR without a "needs: GAME_DIR" comment, so CI would skip it unseen`);
+                    }
+                }
+                const listedDevs = devs === "None"
+                    ? []
+                    : devs
+                        .split(",")
+                        .map((x) => x.trim())
+                        .filter(Boolean);
+                const expectedDevs = [...deviations]
+                    .filter(([, d]) => !d.dropped && d.departs.includes(specId))
+                    .map(([k]) => k)
+                    .sort(compareIds);
+                if (listedDevs.slice().sort(compareIds).join(",") !== expectedDevs.join(","))
+                    problem(file, `${specId}: Deviations must be ${expectedDevs.join(", ") || "None"}`);
+                let expectedStatus;
+                if (code !== "complete" || e.meta.status === "disputed")
+                    expectedStatus = e.meta.status;
+                else if (testFiles.length === 0)
+                    expectedStatus = "implemented";
+                else if (["supported", "established"].includes(e.meta.status))
+                    expectedStatus = "validated";
+                else {
+                    problem(file, `${specId}: complete with tests while the spec status is ${e.meta.status}; the evidence belongs in the spec entry first`);
+                    expectedStatus = status;
+                }
+                if (status !== expectedStatus)
+                    problem(file, `${specId}: Status must be ${expectedStatus}`);
+                if (expectedStatus === "validated")
+                    for (const tf of testFiles.filter((x) => needsGame(join(repoDir, x)))) {
+                        if (!validatedTests.has(tf))
+                            validatedTests.set(tf, []);
+                        validatedTests.get(tf).push({ specId, file });
+                    }
+                if (expectedStatus === "validated" && mayBeInterrupted(e) && onlyEmulatedRuns(entries, e))
+                    problem(file, `${specId}: another rule may interrupt it (# may run:), so tests against emulated calls alone cannot validate it`, "STATUS-15");
+                for (const cell of [code, tests, devs, notes])
+                    if (cell === "")
+                        problem(file, `${specId}: an empty cell says None`);
+                parityCounts.status[status] = (parityCounts.status[status] ?? 0) + 1;
+                parityCounts.code[code] = (parityCounts.code[code] ?? 0) + 1;
+            }
+        }
+        for (const [id, e] of entries)
+            if (["RULE", "FMT", "SCR"].includes(e.kind) && e.meta.status !== "superseded" && !parityRows.has(id))
+                problem(parityDir, `${id} has no row`);
+        // Each area is split exactly where the limit requires it, going by the rows it has.
+        for (const [area, actual] of byArea) {
+            const ids = [...actual.values()]
+                .flat()
+                .filter((x) => entries.has(x))
+                .sort(compareIds);
+            const render = (subset, path) => [
+                `# ${path}`,
+                "",
+                `| ${PARITY_HEADER.join(" | ")} |`,
+                `|${"---|".repeat(PARITY_HEADER.length)}`,
+                ...subset.map((x) => `| ${parityRows.get(x).cells.join(" | ")} |`),
+                "",
+            ].join("\n");
+            const expected = [...layout(ctx, area, ids, render, 1).keys()];
+            const found = [...actual.keys()].sort();
+            if (expected.slice().sort().join(",") !== found.join(","))
+                problem(parityDir, `the rows of ${area} belong in ${expected.map((p) => `parity/${p}.md`).join(", ")}, split only where the ${LINE_LIMIT}-line limit requires it; found ${found.map((p) => `parity/${p}.md`).join(", ")}`);
+        }
+    }
+    for (const [dev, d] of deviations)
+        if (!d.dropped && !d.departs.some((x) => parityRows.has(x)))
+            problem(d.file, `${dev} departs from no entry that has a parity row`);
+    return { rows: parityRows, counts: parityCounts, validatedTests, legacy: legacyParity };
+}

package/dist/checks/references.d.ts

@@ -0,0 +1,4 @@
+import type { Context } from "../context.ts";
+import type { Deviation } from "./deviations.ts";
+/** Checks the IDs that the code, the references, parity/ and deviations/ cite. */
+export declare function checkReferences(ctx: Context, deviations: Map<string, Deviation>): void;

package/dist/checks/references.js

@@ -0,0 +1,37 @@
+// Implementation references: every spec and deviation ID in code, tests, the parity files and the
+// deviation files resolves. A deviation keeps citing what it departed from after that is superseded.
+import { readFileSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { isSuperseded } from "../evidence.js";
+import { walk } from "../files.js";
+import { idsIn, isAlias } from "../ids.js";
+import { DEV_RE } from "../standard.js";
+/** Checks the IDs that the code, the references, parity/ and deviations/ cite. */
+export function checkReferences(ctx, deviations) {
+    const { problem } = ctx;
+    const { entries } = ctx.spec;
+    const { repoDir } = ctx.config;
+    const parityDir = join(repoDir, "parity");
+    const devDir = join(repoDir, "deviations");
+    const isDeviationFile = (f) => resolve(f).startsWith(devDir + sep);
+    const scan = ctx.codeFiles().filter(({ file }) => !file.endsWith(".fs"));
+    for (const dir of [parityDir, devDir])
+        walk(dir, (f) => {
+            if (f.endsWith(".md"))
+                scan.push({ file: f, text: readFileSync(f, "utf8") });
+        });
+    for (const { file: f, text } of scan) {
+        for (const x of idsIn(text)) {
+            if (isAlias(x) && !entries.has(x))
+                continue; // aliases can collide with ordinary words
+            if (!entries.has(x))
+                problem(f, `cites ${x}, which does not exist in the spec`);
+            else if (isSuperseded(entries, x) && !isDeviationFile(f))
+                problem(f, `cites ${x}, which is superseded; cite what replaced it`);
+        }
+        if (!isDeviationFile(f))
+            for (const x of new Set(text.match(DEV_RE) ?? []))
+                if (!deviations.has(x))
+                    problem(f, `cites ${x}, which is not in deviations/`);
+    }
+}

package/dist/checks/rules.d.ts

@@ -0,0 +1,11 @@
+import type { Context } from "../context.ts";
+import type { FormatNames } from "./formats.ts";
+/**
+ * A procedure with each string literal emptied and its comments dropped. Strings go first, so a `#`
+ * inside one does not start a comment, and a string ends on the line it starts on.
+ */
+export declare const withoutCommentsAndStrings: (code: string) => string;
+/** The names a rule's Parameters section declares: each lower-case name that opens a code span, as `n` or `n: type`. */
+export declare const parameterNames: (params: string) => string[];
+/** Checks every rule's procedure. Sets Entry.code on every rule entry, superseded ones included. */
+export declare function checkRules(ctx: Context, { enumNames }: FormatNames): void;