@scientific-method/standard-checker 0.1.0 → 0.2.0

package/dist/checks/entries.js

@@ -0,0 +1,130 @@
+// The checks every entry gets: its ID, fields, sections, status and links. Each kind's own checks
+// are called from here, in the order the standard lists them.
+import { checkResolves, isSuperseded } from "../evidence.js";
+import { asList, kindOf } from "../ids.js";
+import { CLAIM_STATUSES, EVIDENCE_STATUSES, FIELD_RULES, FIELDS, KINDS, SECTIONS } from "../standard.js";
+import { checkClaim } from "./claims.js";
+import { checkExperiment, checkFinding } from "./evidence-entries.js";
+import { checkFormat } from "./formats.js";
+import { checkScreen } from "./screens.js";
+function checkIdForm(ctx, file, id) {
+    const { problem } = ctx;
+    const { areas } = ctx.spec;
+    const kind = kindOf(id);
+    if (!KINDS[kind]) {
+        problem(file, `${id} is not an ID of a known kind`, "IDENTIFIERS-1");
+        return;
+    }
+    if (kind === "BLD" || kind === "SRC") {
+        if (!/^(BLD|SRC)-[A-Z][A-Z0-9.-]*$/.test(id))
+            problem(file, `${id}: an alias starts with an upper-case letter and holds only upper-case letters, digits, dots and hyphens`, "IDENTIFIERS-4");
+        return;
+    }
+    const m = /^[A-Z]+-([A-Z][A-Z0-9]*)-(\d+)$/.exec(id);
+    if (!m) {
+        problem(file, `${id} does not have the form KIND-AREA-NNN`, "IDENTIFIERS-1");
+        return;
+    }
+    if (!areas.includes(m[1]))
+        problem(file, `${id}: area ${m[1]} is not in the area list`, "IDENTIFIERS-2");
+    if (m[2].length < 3 || (m[2].length > 3 && m[2].startsWith("0")))
+        problem(file, `${id}: the number is zero-padded to exactly three digits until it passes 999`, "IDENTIFIERS-3");
+}
+/**
+ * Checks every entry, kind by kind, and returns the names the formats' tables define, which the
+ * rule checks read.
+ */
+export function checkEntries(ctx) {
+    const { problem } = ctx;
+    const { entries } = ctx.spec;
+    const names = {
+        enumNames: new Map(), // name -> format IDs
+        fieldNames: new Map(), // format ID -> Set of names
+    };
+    for (const [id, e] of entries) {
+        const { file, meta, kind } = e;
+        checkIdForm(ctx, file, id);
+        for (const f of FIELDS[kind].required)
+            if (!(f in meta))
+                problem(file, `front matter lacks ${f}`, FIELD_RULES[f]);
+        if (!Array.isArray(meta.superseded_by))
+            problem(file, "superseded_by must be a list", FIELD_RULES.superseded_by);
+        const expectedSections = SECTIONS[kind];
+        const got = e.sections.map((s) => s.title);
+        if (got.join("|") !== expectedSections.join("|"))
+            problem(file, `sections must be ${expectedSections.join(", ")} in that order; found ${got.join(", ") || "none"}`, "ENTRY-TYPES-1");
+        for (const s of e.sections)
+            if (s.text.trim() === "")
+                problem(file, `section ${s.title} is empty; write None known. or None.`, "ENTRY-TYPES-2");
+        const superseded = asList(meta.superseded_by);
+        const status = meta.status;
+        if (KINDS[kind].statuses === "claim" && !CLAIM_STATUSES.includes(status))
+            problem(file, `status ${status} is not one of ${CLAIM_STATUSES.join(", ")}`, "STATUS-1");
+        if (KINDS[kind].statuses === "evidence" && !EVIDENCE_STATUSES.includes(status))
+            problem(file, `status ${status} is not one of ${EVIDENCE_STATUSES.join(", ")}`, "STATUS-21");
+        const isSup = status === "superseded" || ((kind === "BLD" || kind === "SRC") && superseded.length > 0);
+        if (status === "superseded" && superseded.length === 0)
+            problem(file, "a superseded entry names what replaced or disproved it in superseded_by", "IDENTIFIERS-7");
+        if (status && status !== "superseded" && superseded.length > 0)
+            problem(file, "superseded_by must be empty unless the status is superseded", "ENTRY-TYPES-4");
+        checkResolves(ctx, file, superseded, "superseded_by");
+        for (const s of superseded) {
+            const k = kindOf(s);
+            const ok = ["FND", "EXP"].includes(kind)
+                ? ["FND", "EXP"].includes(k)
+                : kind === "BLD"
+                    ? k === "BLD"
+                    : kind === "SRC"
+                        ? k === "SRC"
+                        : kind === "BUG"
+                            ? true
+                            : k !== "SRC" && k !== "BLD";
+            if (!ok)
+                problem(file, `superseded_by may not name ${s}`, "IDENTIFIERS-7");
+        }
+        if (kind !== "BLD" && kind !== "SRC") {
+            const builds = asList(meta.builds);
+            if (builds.length === 0)
+                problem(file, "builds must list at least one build");
+            checkResolves(ctx, file, builds, "builds");
+            for (const b of builds)
+                if (entries.has(b) && kindOf(b) !== "BLD")
+                    problem(file, `builds lists ${b}, which is not a build`);
+        }
+        // Links that must not point at superseded entries
+        if (!isSup) {
+            const linkFields = ["builds", "evidence", "conflicting", "related"];
+            for (const f of linkFields)
+                for (const t of asList(meta[f]))
+                    if (entries.has(t) && isSuperseded(entries, t))
+                        problem(file, `${f} cites ${t}, which is superseded`, "STATUS-17");
+            for (const loc of asList(meta.locations))
+                if (loc && entries.has(loc.build) && isSuperseded(entries, loc.build))
+                    problem(file, `a location names ${loc.build}, which is superseded`, "STATUS-17");
+        }
+        if (["FND", "EXP"].includes(kind)) {
+            const rep = asList(meta.reproduced_by);
+            if (status === "reproduced" && rep.every((p) => p === meta.recorded_by))
+                problem(file, "a reproduced entry names someone other than recorded_by in reproduced_by", "STATUS-21");
+            if (status !== "reproduced" && rep.length > 0)
+                problem(file, "reproduced_by must be empty unless the status is reproduced", "STATUS-21");
+            if (typeof meta.recorded_by !== "string" || !meta.recorded_by)
+                problem(file, "recorded_by must be a GitHub username");
+        }
+        if (kind === "FND")
+            checkFinding(ctx, e);
+        if (kind === "EXP")
+            checkExperiment(ctx, id, e, isSup);
+        if (KINDS[kind].statuses === "claim")
+            checkClaim(ctx, id, e);
+        if (kind === "BLD" && ![16, 32].includes(meta.int_width))
+            problem(file, "int_width must be 16 or 32");
+        if (kind === "SRC" && meta.xxh3 !== null && !/^[0-9a-f]{32}$/.test(String(meta.xxh3)))
+            problem(file, "xxh3 must be null or 32 lower-case hex digits");
+        if (kind === "FMT")
+            checkFormat(ctx, e, names);
+        if (kind === "SCR")
+            checkScreen(ctx, e);
+    }
+    return names;
+}

package/dist/checks/evidence-entries.d.ts

@@ -0,0 +1,6 @@
+import type { Context } from "../context.ts";
+import type { Entry } from "../types.ts";
+/** Checks a finding's method, environment and locations. */
+export declare function checkFinding(ctx: Context, e: Entry): void;
+/** Checks an experiment's builds, fixture, starting state and recording. live is false once it is superseded. */
+export declare function checkExperiment(ctx: Context, id: string, e: Entry, isSup: boolean): void;

package/dist/checks/evidence-entries.js

@@ -0,0 +1,167 @@
+// The checks of findings and experiments: a finding's locations, and an experiment's fixture,
+// starting state and recording.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { isSuperseded } from "../evidence.js";
+import { asList } from "../ids.js";
+import { checkAddress, checkOffset } from "../locations.js";
+import { locationRule } from "../standard.js";
+/** Checks a finding's method, environment and locations. */
+export function checkFinding(ctx, e) {
+    const { problem } = ctx;
+    const { buildFiles, codeRanges } = ctx.spec;
+    const { file, meta } = e;
+    if (!["static", "dynamic"].includes(meta.method))
+        problem(file, "method must be static or dynamic");
+    if (meta.method === "static" && meta.environment !== null)
+        problem(file, "a static finding has environment: null");
+    if (meta.method === "dynamic" && (meta.environment === null || meta.environment === ""))
+        problem(file, "a dynamic finding gives its environment");
+    const locations = asList(meta.locations);
+    const builds = asList(meta.builds);
+    if (meta.method === "static")
+        for (const b of builds)
+            if (!locations.some((l) => l && l.build === b))
+                problem(file, `a static finding has at least one location in ${b}`);
+    for (const loc of locations) {
+        if (!loc || typeof loc !== "object") {
+            problem(file, "a location must be a map of build, file and address or offset");
+            continue;
+        }
+        if (!builds.includes(loc.build))
+            problem(file, `location build ${loc.build} is not in builds`);
+        const files = buildFiles.get(loc.build) ?? [];
+        const bf = files.find((f) => f.path === loc.file);
+        if (!bf) {
+            problem(file, `location file ${loc.file} is not in the files of ${loc.build}`);
+            continue;
+        }
+        const format = bf.unpacked?.format ?? bf.format;
+        // kind tells code from data within an executable; a data file holds no code to tell apart.
+        if (loc.kind !== undefined && !locationRule(format)?.address)
+            problem(file, `location kind ${loc.kind} in ${loc.file}: a ${format} file is not an executable, so its locations give no kind`);
+        else if (loc.kind !== undefined && loc.kind !== "code" && loc.kind !== "file-data")
+            problem(file, `location kind ${loc.kind} in ${loc.file}: kind must be code or file-data when given`);
+        const fileData = loc.kind === "file-data";
+        if (fileData && "address" in loc)
+            problem(file, `a file-data location in ${loc.file} gives a file offset, not an address`);
+        // A file-data location in a packed file may name bytes that exist only once it is unpacked,
+        // such as the relocation table an unpacker writes, by an offset into the unpacked form.
+        const intoUnpacked = loc.unpacked === true;
+        if ("unpacked" in loc && !intoUnpacked)
+            problem(file, `a location in ${loc.file} gives unpacked: true or leaves it out`);
+        else if (intoUnpacked && !fileData)
+            problem(file, `a location in ${loc.file} gives unpacked: true only with kind: file-data`);
+        else if (intoUnpacked && !bf.packer)
+            problem(file, `a location in ${loc.file} gives unpacked: true, but ${loc.file} is not packed`);
+        if ("address" in loc && "offset" in loc)
+            problem(file, "a location gives address or offset, not both");
+        if ("address" in loc) {
+            if (!fileData)
+                checkAddress(problem, file, loc.address, format);
+        }
+        else if ("offset" in loc) {
+            // Explicit file-data offsets name shipped container metadata or data, never code.
+            // Other offsets name bytes of the shipped file: data, CD audio, or MZ overlay code
+            // outside the load image. The finding must establish the overlay mapping. Like an
+            // address, an offset is judged by the unpacked format, so a packed MZ stub around LE
+            // or PE code cannot use offsets for code the loader maps.
+            const rule = locationRule(format);
+            if (!fileData && rule && !rule.offset)
+                problem(file, `location in ${loc.file} gives an offset; a ${format} executable is located by address (only MZ overlay code uses offsets)`);
+            const range = intoUnpacked && bf.packer
+                ? checkOffset(problem, file, loc.offset, { path: bf.path, size: Number(bf.unpacked?.size) }, "unpacked form of")
+                : checkOffset(problem, file, loc.offset, bf);
+            // An offset into an executable locates overlay code, so it lies wholly inside one row of
+            // the build's Code ranges. Adjacent rows are not joined: a range that crosses from one
+            // into the next, such as into another bank, fails.
+            if (!fileData && range && rule?.offset && rule.address && codeRanges.has(loc.build)) {
+                const inside = codeRanges
+                    .get(loc.build)
+                    .some((r) => r.file === loc.file && r.start <= range[0] && range[1] <= r.end);
+                if (!inside)
+                    problem(file, `offset ${loc.offset} in ${loc.file} does not lie wholly inside one of the rows the Code ranges section of ${loc.build} gives for that file`);
+            }
+        }
+        else
+            problem(file, "a location gives an address or an offset");
+    }
+}
+// A run's draws from the generator, in order. Each is named by the rule it was made under, which
+// the rebuild cites too, and never by the address of the call in the original's code. A live
+// experiment's draws cite living rules, as its other links do.
+const DRAW_KEYS = ["rule", "bound", "result"];
+function checkDraws(ctx, fixture, draws, live) {
+    const { problem } = ctx;
+    const { entries } = ctx.spec;
+    if (draws === undefined)
+        return;
+    if (!Array.isArray(draws))
+        return problem(fixture, "draws is a list");
+    draws.forEach((draw, i) => {
+        if (draw === null || typeof draw !== "object" || Array.isArray(draw))
+            return problem(fixture, `draw ${i} is an object with rule, bound and result`);
+        const extra = Object.keys(draw).filter((k) => !DRAW_KEYS.includes(k));
+        if (extra.length)
+            problem(fixture, `draw ${i} has ${extra.join(", ")}; a draw gives only rule, bound and result`);
+        if (entries.get(draw.rule)?.kind !== "RULE")
+            problem(fixture, `draw ${i} names ${draw.rule}, which is not a rule entry`);
+        else if (live && isSuperseded(entries, draw.rule))
+            problem(fixture, `draw ${i} names ${draw.rule}, which is superseded`, "STATUS-17");
+        if (!Number.isInteger(draw.bound) || !Number.isInteger(draw.result))
+            problem(fixture, `draw ${i} gives bound and result as integers`);
+    });
+}
+/** Checks an experiment's builds, fixture, starting state and recording. live is false once it is superseded. */
+export function checkExperiment(ctx, id, e, isSup) {
+    const { problem } = ctx;
+    const { buildFiles, glossary } = ctx.spec;
+    const { specDir } = ctx.config;
+    const { file, meta } = e;
+    const builds = asList(meta.builds);
+    if (builds.length !== 1)
+        problem(file, "an experiment lists exactly one build", "ENTRY-TYPES-7");
+    const fixture = meta.fixture && join(specDir, "experiments", meta.fixture);
+    if (!fixture || !existsSync(fixture))
+        problem(file, `fixture ${meta.fixture} does not exist`);
+    else {
+        try {
+            const fx = JSON.parse(readFileSync(fixture, "utf8"));
+            if (fx.experiment !== id)
+                problem(fixture, `experiment must be ${id}`);
+            if (!["new-game", "emulated-call"].includes(meta.starting_state) &&
+                !(fx.starting_state && fx.starting_state.xxh3))
+                problem(fixture, "gives the hash of the save its runs started from");
+            if (typeof meta.starting_state === "string" &&
+                meta.starting_state.endsWith(".patch.json") &&
+                !fx.starting_state?.base_xxh3)
+                problem(fixture, "a patch fixture gives the base save's hash as well");
+            for (const run of asList(fx.runs)) {
+                for (const ev of asList(run?.events))
+                    if (!glossary.has(ev?.event))
+                        problem(fixture, `event ${ev?.event} has no glossary entry`);
+                checkDraws(ctx, fixture, run?.draws, !isSup);
+            }
+            if (typeof meta.recording === "string" && meta.recording !== "" && !fx.recording_xxh3)
+                problem(fixture, "an experiment with a recording gives the recording's hash in recording_xxh3");
+        }
+        catch (err) {
+            problem(fixture, `is not valid JSON: ${err.message}`);
+        }
+    }
+    if (typeof meta.starting_state === "string" &&
+        meta.starting_state.startsWith("saves/") &&
+        !existsSync(join(specDir, "experiments", meta.starting_state)))
+        problem(file, `starting_state ${meta.starting_state} does not exist`);
+    // A recording is committed in recordings/, kept with the captures, or one of the build's files.
+    if (typeof meta.recording === "string" && meta.recording !== "") {
+        const rec = meta.recording;
+        if (rec.startsWith("recordings/")) {
+            if (!existsSync(join(specDir, "experiments", rec)))
+                problem(file, `recording ${rec} does not exist`);
+        }
+        else if (!rec.startsWith("captures/") &&
+            !builds.some((b) => (buildFiles.get(b) ?? []).some((f) => f.path === rec)))
+            problem(file, `recording ${rec} is neither in recordings/ or captures/ nor a file of ${builds.join(", ")}`);
+    }
+}

package/dist/checks/formats.d.ts

@@ -0,0 +1,13 @@
+import type { Context } from "../context.ts";
+import type { Entry } from "../types.ts";
+/** The names the formats' tables define. */
+export interface FormatNames {
+    /** Enumeration name -> the formats that define it, once per row. */
+    enumNames: Map<string, string[]>;
+    /** Format ID -> the names of its layout and enumeration rows. */
+    fieldNames: Map<string, Set<string>>;
+}
+/** The IDs cited in the last column of the tables of an entry's sections (of every section when sectionTitles is left out). */
+export declare function tableIds(e: Entry, sectionTitles?: string[]): Set<string>;
+/** Checks a format entry, adding the names its tables define to formatNames. */
+export declare function checkFormat(ctx: Context, e: Entry, formatNames: FormatNames): void;

package/dist/checks/formats.js

@@ -0,0 +1,194 @@
+// 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 } = 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("`", ""));
+        }
+    };
+    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(" | ")}`);
+            else
+                visit(t, "layout");
+        }
+    }
+    // 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;