@scientific-method/standard-checker 0.1.0 → 0.2.0

package/dist/load/entries.js

@@ -0,0 +1,57 @@
+// The entries: one Markdown file per ID in the directory of its kind.
+import { readdirSync, statSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { isAlias, kindOf } from "../ids.js";
+import { readEntry } from "../markdown.js";
+import { KINDS } from "../standard.js";
+/**
+ * Reads every entry under spec/, by ID, and reports a directory of spec/ the standard does not
+ * define. An entry without an ID or of an unknown kind is reported and left out.
+ */
+export function loadEntries({ config, problem }) {
+    const { specDir } = config;
+    const entries = new Map();
+    for (const [kind, { dir }] of Object.entries(KINDS)) {
+        const d = join(specDir, dir);
+        if (!existsSync(d))
+            continue;
+        for (const name of readdirSync(d)) {
+            const file = join(d, name);
+            if (statSync(file).isDirectory() || !name.endsWith(".md"))
+                continue;
+            const read = readEntry(file, problem);
+            if (!read)
+                continue;
+            const entry = Object.assign(read, { kind });
+            const id = entry.meta.id;
+            if (typeof id !== "string") {
+                problem(file, "has no id", "IDENTIFIERS-1");
+                continue;
+            }
+            if (name !== `${id}.md`)
+                problem(file, `file name must be ${id}.md`);
+            // Later checks look the kind up in KINDS, so an entry of an unknown kind is reported and dropped.
+            if (!KINDS[kindOf(id)]) {
+                problem(file, `${id} is not an ID of a known kind`, "IDENTIFIERS-1");
+                continue;
+            }
+            if (kindOf(id) !== kind)
+                problem(file, `a ${kindOf(id)} entry does not belong in spec/${dir}/`);
+            // IDENTIFIERS-3 makes a number unique within its kind and area, and IDENTIFIERS-4 an alias.
+            if (entries.has(id))
+                problem(file, `ID ${id} is used twice`, isAlias(id) ? "IDENTIFIERS-4" : "IDENTIFIERS-3");
+            entries.set(id, entry);
+        }
+    }
+    // Stray Markdown anywhere else in spec/ that looks like an entry.
+    for (const dir of readdirSync(specDir)) {
+        const d = join(specDir, dir);
+        if (!statSync(d).isDirectory() ||
+            Object.values(KINDS).some((k) => k.dir === dir) ||
+            dir === "index" ||
+            dir === "glossary")
+            continue;
+        problem(d, "is not a directory the standard defines");
+    }
+    return entries;
+}

package/dist/load/glossary.d.ts

@@ -0,0 +1,12 @@
+import type { LoadContext } from "../context.ts";
+/** The glossary as read from spec/glossary/ and the --glossary drafts. */
+export interface Glossary {
+    /** spec/glossary/. */
+    glossaryDir: string;
+    /** Term -> the text after its heading. */
+    glossary: Map<string, string>;
+    /** Term -> its file in spec/glossary/. */
+    glossaryFiles: Map<string, string>;
+}
+/** Reads and checks spec/glossary/, then adds the terms of the --glossary drafts. */
+export declare function loadGlossary({ config, problem }: LoadContext): Glossary;

package/dist/load/glossary.js

@@ -0,0 +1,70 @@
+// The glossary: one file per term in spec/glossary/, named after the term and opening with it as a
+// # heading. A glossary file is not an entry, so it has no front matter.
+import { existsSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { termFiles } from "../files.js";
+import { readText } from "../markdown.js";
+import { RESERVED_NAMES } from "../standard.js";
+function readTerm(problem, file, report = true) {
+    const text = readText(file);
+    const say = (message) => {
+        if (report)
+            problem(file, message);
+    };
+    if (text.startsWith("---\n"))
+        say("a glossary file has no front matter");
+    const m = /^# (.+)\n?([\s\S]*)$/.exec(text.replace(/^---\n[\s\S]*?\n---\n/, "").replace(/^\s+/, ""));
+    if (!m) {
+        say("opens with the term as a # heading");
+        return null;
+    }
+    const term = m[1].trim().replaceAll("`", "");
+    if (basename(file) !== `${term}.md`)
+        say(`is named after its term, ${term}.md`);
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(term))
+        say(`${term} is not a name the pseudocode can use`);
+    if (RESERVED_NAMES.test(term))
+        say(`${term} is a name Windows reserves for a device, so no file can have it`);
+    return { term, text: m[2] };
+}
+/** Reads and checks spec/glossary/, then adds the terms of the --glossary drafts. */
+export function loadGlossary({ config, problem }) {
+    const { specDir } = config;
+    const glossaryDir = join(specDir, "glossary");
+    const glossary = new Map(); // term -> text after the heading
+    const glossaryFiles = new Map(); // term -> file
+    if (existsSync(join(specDir, "glossary.md")))
+        problem(join(specDir, "glossary.md"), "the glossary is the directory spec/glossary/; move each ## term to spec/glossary/<term>.md with the term as its # heading");
+    if (!existsSync(glossaryDir))
+        problem(null, "spec/glossary/ is missing");
+    else {
+        const folded = new Map();
+        for (const file of termFiles(glossaryDir)) {
+            if (statSync(file).isDirectory() || !file.endsWith(".md")) {
+                problem(file, "is not a glossary file; spec/glossary/ holds one <term>.md per term");
+                continue;
+            }
+            const t = readTerm(problem, file);
+            if (!t)
+                continue;
+            const key = t.term.toLowerCase();
+            if (folded.has(key))
+                problem(file, `${t.term} differs only in case from ${folded.get(key)}`);
+            else
+                folded.set(key, t.term);
+            glossary.set(t.term, t.text);
+            glossaryFiles.set(t.term, file);
+        }
+    }
+    // --glossary <path> adds the terms of a draft term file, or of a directory of them, for checking
+    // entries before their terms are merged into spec/glossary/.
+    for (const draft of config.glossaryDrafts) {
+        const files = statSync(draft).isDirectory() ? termFiles(draft).filter((f) => f.endsWith(".md")) : [draft];
+        for (const file of files) {
+            const t = readTerm(problem, file, false);
+            if (t && !glossary.has(t.term))
+                glossary.set(t.term, t.text);
+        }
+    }
+    return { glossaryDir, glossary, glossaryFiles };
+}

package/dist/load/readme.d.ts

@@ -0,0 +1,3 @@
+import type { LoadContext } from "../context.ts";
+/** Checks spec/README.md and returns its areas, in the order it lists them. */
+export declare function loadAreas({ config, problem }: LoadContext): string[];

package/dist/load/readme.js

@@ -0,0 +1,36 @@
+// spec/README.md: its sections and the area list.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { splitSections, tables } from "../markdown.js";
+/** Checks spec/README.md and returns its areas, in the order it lists them. */
+export function loadAreas({ config, problem }) {
+    const { specDir } = config;
+    const readme = existsSync(join(specDir, "README.md"))
+        ? readFileSync(join(specDir, "README.md"), "utf8").replace(/\r\n/g, "\n")
+        : "";
+    if (!readme)
+        problem(null, "spec/README.md is missing");
+    const areas = [];
+    const readmeSections = splitSections(readme);
+    const titles = readmeSections.map((s) => s.title);
+    const expected = ["Scope", "Standard version", "Areas"];
+    if (titles.join("|") !== expected.join("|"))
+        problem(join(specDir, "README.md"), `sections must be ${expected.join(", ")} in that order, found ${titles.join(", ")}`);
+    const areaSection = readmeSections.find((s) => s.title === "Areas");
+    const areaTable = areaSection && tables(areaSection.text)[0];
+    if (!areaTable || areaTable.header.join("|") !== "Area|Covers")
+        problem(join(specDir, "README.md"), "the area list must be a table with the columns Area | Covers");
+    else
+        for (const row of areaTable.rows) {
+            const a = row[0].replaceAll("`", "");
+            if (!/^[A-Z][A-Z0-9]*$/.test(a))
+                problem(join(specDir, "README.md"), `area ${a} must be upper-case letters and digits starting with a letter`, "IDENTIFIERS-2");
+            if (areas.includes(a))
+                problem(join(specDir, "README.md"), `area ${a} is listed twice`);
+            areas.push(a);
+        }
+    const version = readmeSections.find((s) => s.title === "Standard version");
+    if (version && !/version 1 of the/.test(version.text))
+        problem(join(specDir, "README.md"), "the Standard version section must say which version it follows (version 1)");
+    return areas;
+}

package/dist/load/spec.d.ts

@@ -0,0 +1,6 @@
+import type { LoadContext, Spec } from "../context.ts";
+/**
+ * Reads spec/ and reports what is wrong with its layout, the README, the glossary and the build
+ * manifests. Exits with 1 when there is no spec/ directory.
+ */
+export declare function loadSpec(ctx: LoadContext): Spec;

package/dist/load/spec.js

@@ -0,0 +1,25 @@
+// Reading the spec: the README's areas, the entries, the glossary and what the build entries name.
+import { existsSync } from "node:fs";
+import { checkOtherFiles, loadBuildFiles } from "./builds.js";
+import { loadCodeRanges } from "./code-ranges.js";
+import { loadEntries } from "./entries.js";
+import { loadGlossary } from "./glossary.js";
+import { loadAreas } from "./readme.js";
+/**
+ * Reads spec/ and reports what is wrong with its layout, the README, the glossary and the build
+ * manifests. Exits with 1 when there is no spec/ directory.
+ */
+export function loadSpec(ctx) {
+    const { repoDir, specDir } = ctx.config;
+    if (!existsSync(specDir)) {
+        console.error(`No spec/ directory in ${repoDir}.`);
+        process.exit(1);
+    }
+    const areas = loadAreas(ctx);
+    const entries = loadEntries(ctx);
+    const { glossaryDir, glossary, glossaryFiles } = loadGlossary(ctx);
+    const buildFiles = loadBuildFiles(ctx, entries);
+    checkOtherFiles(ctx, entries, buildFiles);
+    const codeRanges = loadCodeRanges(ctx, entries, buildFiles);
+    return { areas, entries, glossaryDir, glossary, glossaryFiles, buildFiles, codeRanges };
+}

package/dist/locations.d.ts

@@ -0,0 +1,19 @@
+import type { Problem } from "./problems.ts";
+import type { Meta, Yaml } from "./types.ts";
+/**
+ * Reports an address that is not in the notation of format. An unlisted format is already reported
+ * against its manifest, so it is skipped here.
+ */
+export declare function checkAddress(problem: Problem, file: string, value: Yaml, format: Yaml): void;
+/**
+ * An offset names one byte, or a half-open range of two: 0x20..0x3C covers 0x20 up to but not
+ * including 0x3C. Returns [start, end) as BigInts, or null when the notation is wrong.
+ */
+export declare function parseOffset(value: Yaml): [bigint, bigint] | null;
+/**
+ * An offset is into the shipped file bf, so the bytes it covers lie within bf.size. Returns the
+ * parsed range when it is well formed.
+ * `bf` is the file the offset is into, given as { path, size }: the shipped file, or the unpacked
+ * form of a packed one.
+ */
+export declare function checkOffset(problem: Problem, file: string, value: Yaml, bf: Meta, what?: string): [bigint, bigint] | null;

package/dist/locations.js

@@ -0,0 +1,57 @@
+// Addresses and offsets, the two ways a location in a build's file is given.
+import { locationRule } from "./standard.js";
+/**
+ * Reports an address that is not in the notation of format. An unlisted format is already reported
+ * against its manifest, so it is skipped here.
+ */
+export function checkAddress(problem, file, value, format) {
+    const rule = locationRule(format);
+    if (!rule)
+        return;
+    const re = rule.address;
+    if (!re) {
+        problem(file, `an address cannot be given in a file of format ${format}; use offset`);
+        return;
+    }
+    const parts = String(value).split("..");
+    if (parts.length > 2 || parts.some((p) => !re.test(p)))
+        problem(file, `address ${value} is not in the notation for a ${format} file`);
+}
+/**
+ * An offset names one byte, or a half-open range of two: 0x20..0x3C covers 0x20 up to but not
+ * including 0x3C. Returns [start, end) as BigInts, or null when the notation is wrong.
+ */
+export function parseOffset(value) {
+    const parts = String(value).split("..");
+    if (parts.length > 2 || parts.some((p) => !/^0x[0-9A-F]{2,}$/.test(p)))
+        return null;
+    const [start, end] = parts.map((p) => BigInt(p));
+    return [start, end ?? start + 1n];
+}
+/**
+ * An offset is into the shipped file bf, so the bytes it covers lie within bf.size. Returns the
+ * parsed range when it is well formed.
+ * `bf` is the file the offset is into, given as { path, size }: the shipped file, or the unpacked
+ * form of a packed one.
+ */
+export function checkOffset(problem, file, value, bf, what = "shipped file") {
+    const range = parseOffset(value);
+    if (!range) {
+        problem(file, `offset ${value} must be 0x followed by at least two upper-case hex digits, or a range of two`);
+        return null;
+    }
+    const [start, end] = range;
+    if (start > end) {
+        problem(file, "offset range is reversed");
+        return null;
+    }
+    if (start === end) {
+        problem(file, `offset range ${value} is empty; a range is half-open`);
+        return null;
+    }
+    if (Number.isSafeInteger(bf.size) && bf.size >= 0 && end > BigInt(bf.size)) {
+        problem(file, `offset ${value} is outside the ${what} ${bf.path} (${bf.size} bytes)`);
+        return null;
+    }
+    return range;
+}

package/dist/markdown.d.ts

@@ -0,0 +1,27 @@
+import type { Problem } from "./problems.ts";
+import type { Section, Table } from "./types.ts";
+/** The number of lines of text, not counting the empty one after a final newline. */
+export declare const lineCount: (text: string) => number;
+/** Reads a text file with CRLF line ends read as LF. */
+export declare const readText: (file: string) => string;
+/** Reads an entry's front matter, body and sections, or reports why it cannot and returns null. */
+export declare function readEntry(file: string, problem: Problem): {
+    file: string;
+    meta: import("./types.ts").Meta;
+    body: string;
+    sections: Section[];
+} | null;
+/** The `##` sections of a Markdown body, skipping fenced code. */
+export declare function splitSections(body: string): Section[];
+/** Every Markdown table in a section, with the `###` heading above it. */
+export declare function tables(text: string): Table[];
+/** The cells of a table row, with `\|` read as a pipe and pipes inside code spans kept. */
+export declare function cells(line: string): string[];
+/**
+ * A value file: CSV as RFC 4180 defines it, with a header row. Returns { header, rows }, or null
+ * after reporting a problem.
+ */
+export declare function readCsv(file: string, problem: Problem): {
+    header: string[];
+    rows: string[][];
+} | null;

package/dist/markdown.js

@@ -0,0 +1,162 @@
+// Markdown and CSV: entries with front matter, sections, tables and value files.
+import { readFileSync } from "node:fs";
+import { parseYaml } from "./yaml.js";
+/** The number of lines of text, not counting the empty one after a final newline. */
+export const lineCount = (text) => (text === "" ? 0 : text.split("\n").length - (text.endsWith("\n") ? 1 : 0));
+/** Reads a text file with CRLF line ends read as LF. */
+export const readText = (file) => readFileSync(file, "utf8").replace(/\r\n/g, "\n");
+/** Reads an entry's front matter, body and sections, or reports why it cannot and returns null. */
+export function readEntry(file, problem) {
+    const text = readFileSync(file, "utf8").replace(/\r\n/g, "\n");
+    if (!text.startsWith("---\n")) {
+        problem(file, "has no front matter");
+        return null;
+    }
+    const end = text.indexOf("\n---\n", 4);
+    if (end < 0) {
+        problem(file, "front matter is not closed");
+        return null;
+    }
+    const meta = parseYaml(text.slice(4, end), file, problem);
+    const body = text.slice(end + 5);
+    return { file, meta, body, sections: splitSections(body) };
+}
+/** The `##` sections of a Markdown body, skipping fenced code. */
+export function splitSections(body) {
+    const sections = [];
+    let current = null;
+    let fence = false;
+    for (const line of body.split("\n")) {
+        if (/^(```|~~~)/.test(line))
+            fence = !fence;
+        const m = !fence && /^## (.+)$/.exec(line);
+        if (m) {
+            current = { title: m[1].trim(), lines: [] };
+            sections.push(current);
+        }
+        else if (current)
+            current.lines.push(line);
+    }
+    return sections.map((s) => ({ title: s.title, text: s.lines.join("\n") }));
+}
+/** Every Markdown table in a section, with the `###` heading above it. */
+export function tables(text) {
+    const out = [];
+    const lines = text.split("\n");
+    let heading = null;
+    let fence = false;
+    for (let i = 0; i < lines.length; i++) {
+        if (/^(```|~~~)/.test(lines[i]))
+            fence = !fence;
+        if (fence)
+            continue;
+        const h = /^### (.+)$/.exec(lines[i]);
+        if (h)
+            heading = h[1].trim();
+        if (lines[i].startsWith("|") && i + 1 < lines.length && /^\|[\s:|-]+\|\s*$/.test(lines[i + 1])) {
+            const header = cells(lines[i]);
+            const rows = [];
+            let j = i + 2;
+            while (j < lines.length && lines[j].startsWith("|")) {
+                rows.push(cells(lines[j]));
+                j++;
+            }
+            out.push({ heading, header, rows, line: i });
+            i = j - 1;
+        }
+    }
+    return out;
+}
+/** The cells of a table row, with `\|` read as a pipe and pipes inside code spans kept. */
+export function cells(line) {
+    const parts = [];
+    let cur = "";
+    let code = false;
+    const s = line.trim().replace(/^\|/, "").replace(/\|$/, "");
+    for (let k = 0; k < s.length; k++) {
+        const ch = s[k];
+        if (ch === "`")
+            code = !code;
+        if (ch === "\\" && s[k + 1] === "|") {
+            cur += "|";
+            k++;
+            continue;
+        }
+        if (ch === "|" && !code) {
+            parts.push(cur.trim());
+            cur = "";
+            continue;
+        }
+        cur += ch;
+    }
+    parts.push(cur.trim());
+    return parts;
+}
+/**
+ * A value file: CSV as RFC 4180 defines it, with a header row. Returns { header, rows }, or null
+ * after reporting a problem.
+ */
+export function readCsv(file, problem) {
+    // Spreadsheet programs start a UTF-8 CSV with a byte order mark, which would join the first header.
+    const text = readFileSync(file, "utf8").replace(/^/, "");
+    const records = [];
+    let record = [];
+    let field = "";
+    let quoted = false;
+    let wasQuoted = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (quoted) {
+            if (ch === '"' && text[i + 1] === '"') {
+                field += '"';
+                i++;
+            }
+            else if (ch === '"')
+                quoted = false;
+            else
+                field += ch;
+        }
+        else if (ch === '"' && field === "" && !wasQuoted) {
+            quoted = true;
+            wasQuoted = true;
+        }
+        else if (ch === ",") {
+            record.push(field);
+            field = "";
+            wasQuoted = false;
+        }
+        else if (ch === "\n" || ch === "\r") {
+            if (ch === "\r" && text[i + 1] === "\n")
+                i++;
+            record.push(field);
+            records.push(record);
+            record = [];
+            field = "";
+            wasQuoted = false;
+        }
+        else
+            field += ch;
+    }
+    if (quoted) {
+        problem(file, "has a quoted field that is never closed");
+        return null;
+    }
+    if (field !== "" || record.length > 0) {
+        record.push(field);
+        records.push(record);
+    }
+    // Blank lines at the end of the file are not rows.
+    while (records.length > 0 && records.at(-1).length === 1 && records.at(-1)[0] === "")
+        records.pop();
+    if (records.length === 0) {
+        problem(file, "has no header row");
+        return null;
+    }
+    const [header, ...rows] = records;
+    for (const row of rows)
+        if (row.length !== header.length) {
+            problem(file, `the row ${row.join(",")} has ${row.length} fields, not ${header.length}`);
+            return null;
+        }
+    return { header, rows };
+}

package/dist/options.d.ts

@@ -0,0 +1,34 @@
+/** What one run of the checker was asked to do, from its command line. */
+export interface Config {
+    /** The repository being checked (--root), absolute. */
+    repoDir: string;
+    /** Its spec/ directory. */
+    specDir: string;
+    /** --check: report stale generated files instead of rewriting them. */
+    checkOnly: boolean;
+    /** --no-ksy: skip compiling the Kaitai definitions. */
+    skipKsy: boolean;
+    /** --base, or null when it was not given. */
+    baseArg: string | null;
+    /** Every --glossary path, in order. */
+    glossaryDrafts: string[];
+    /** The --code directories, relative to repoDir. */
+    codeRoots: string[];
+    /** The --references directories, relative to repoDir. */
+    referenceRoots: string[];
+    /** The --images ranges, as half-open [low, high). */
+    images: Array<[number, number]>;
+    /** --max-range in bytes. */
+    maxRange: number;
+    /** The --data-dirs directories, or undefined when the option was not given. */
+    dataDirs: string[] | undefined;
+    /** The --record-validation build IDs, or undefined when the option was not given. */
+    recordValidation: string[] | undefined;
+}
+/**
+ * Splits a comma-separated option into its trimmed, non-empty parts, or returns fallback when the
+ * option was not given.
+ */
+export declare const dirList: (value: string | undefined, fallback: string[]) => string[];
+/** Reads the arguments after the script's path. An invalid one prints why and exits with 2. */
+export declare function parseOptions(argv: string[]): Config;

package/dist/options.js

@@ -0,0 +1,87 @@
+// The command line, read into a Config. An invalid option prints why and exits with 2.
+import { join, resolve } from "node:path";
+/**
+ * Splits a comma-separated option into its trimmed, non-empty parts, or returns fallback when the
+ * option was not given.
+ */
+export const dirList = (value, fallback) => value === undefined
+    ? fallback
+    : value
+        .split(",")
+        .map((x) => x.trim())
+        .filter(Boolean);
+const FLAGS = ["--check", "--no-ksy"];
+const VALUED = [
+    "--root",
+    "--base",
+    "--glossary",
+    "--code",
+    "--references",
+    "--images",
+    "--max-range",
+    "--data-dirs",
+    "--record-validation",
+];
+/** Reads the arguments after the script's path. An invalid one prints why and exits with 2. */
+export function parseOptions(argv) {
+    const options = { glossary: [] };
+    for (let k = 0; k < argv.length; k++) {
+        const arg = argv[k];
+        if (FLAGS.includes(arg))
+            options[arg.slice(2)] = true;
+        else if (VALUED.includes(arg)) {
+            if (k + 1 >= argv.length) {
+                console.error(`${arg} needs a value; see --help`);
+                process.exit(2);
+            }
+            if (arg === "--glossary")
+                options.glossary.push(argv[++k]);
+            else
+                options[arg.slice(2)] = argv[++k];
+        }
+        else {
+            console.error(`unknown option ${arg}; see --help`);
+            process.exit(2);
+        }
+    }
+    const repoDir = resolve(options.root ?? ".");
+    const specDir = join(repoDir, "spec");
+    const checkOnly = options.check === true;
+    if (checkOnly && options["record-validation"] !== undefined) {
+        console.error("--record-validation writes VALIDATION.md, so it cannot be combined with --check");
+        process.exit(2);
+    }
+    const skipKsy = options["no-ksy"] === true;
+    const baseArg = options.base ?? null;
+    const codeRoots = dirList(options.code, ["src", "tests", "tools"]);
+    const referenceRoots = dirList(options.references, []);
+    // Half-open [low, high) ranges, as numbers: flat 32-bit addresses fit exactly.
+    const images = dirList(options.images, []).map((range) => {
+        const m = /^0x([0-9A-Fa-f]{8})\.\.0x([0-9A-Fa-f]{8})$/.exec(range);
+        const [low, high] = m ? [parseInt(m[1], 16), parseInt(m[2], 16)] : [NaN, NaN];
+        if (!m || high <= low) {
+            console.error(`--images takes half-open ranges such as 0x00400000..0x004C9000, not ${range}`);
+            process.exit(2);
+        }
+        return [low, high];
+    });
+    const maxRange = options["max-range"] === undefined ? 0x10000 : Number(options["max-range"]);
+    if (!Number.isSafeInteger(maxRange) || maxRange < 1) {
+        console.error(`--max-range takes a positive number of bytes, such as 0x10000, not ${options["max-range"]}`);
+        process.exit(2);
+    }
+    return {
+        repoDir,
+        specDir,
+        checkOnly,
+        skipKsy,
+        baseArg,
+        glossaryDrafts: options.glossary,
+        codeRoots,
+        referenceRoots,
+        images,
+        maxRange,
+        dataDirs: options["data-dirs"] === undefined ? undefined : dirList(options["data-dirs"], []),
+        recordValidation: options["record-validation"] === undefined ? undefined : dirList(options["record-validation"], []),
+    };
+}

package/dist/problems.d.ts

@@ -0,0 +1,27 @@
+/** The whole numbers from 1 to N. */
+type UpTo<N extends number, Seen extends 0[] = [0]> = Seen["length"] | (Seen["length"] extends N ? never : UpTo<N, [...Seen, 0]>);
+/**
+ * A numbered rule of the documentation standard, such as `STATUS-14`. The standard opens each rule
+ * with the heading `###### STATUS-14`, anchored at `#status-14` on the site and in vendored copies.
+ * Each count is the last rule the standard numbers in that section, so a label that names no rule
+ * does not compile. Raise a count, or add a section, when the standard numbers more rules.
+ */
+export type Rule = `IDENTIFIERS-${UpTo<7>}` | `STATUS-${UpTo<41>}` | `ENTRY-TYPES-${UpTo<8>}`;
+/**
+ * Records a problem with file (or with the spec as a whole when file is null). A problem that breaks
+ * a numbered rule names it.
+ */
+export type Problem = (file: string | null, message: string, rule?: Rule) => void;
+/** The problem collector of one run. */
+export interface Problems {
+    /** Records a problem. */
+    problem: Problem;
+    /**
+     * Prints every distinct problem in the order found, with the summary, and exits with 1. Returns
+     * when there are none.
+     */
+    report(entryCount: number): void;
+}
+/** Creates the collector for a run over repoDir, against which problem paths are printed. */
+export declare function createProblems(repoDir: string): Problems;
+export {};

package/dist/problems.js

@@ -0,0 +1,27 @@
+// The problems a run finds, kept in the order they are found and printed together at the end.
+import { relative } from "node:path";
+/** Creates the collector for a run over repoDir, against which problem paths are printed. */
+export function createProblems(repoDir) {
+    const problems = [];
+    let citedRule = false;
+    // A problem that breaks a numbered rule ends with the rule's label, so whoever fixes it can read
+    // that one rule instead of the whole section.
+    const problem = (file, message, rule) => {
+        if (rule)
+            citedRule = true;
+        problems.push(`${file ? relative(repoDir, file).replaceAll("\\", "/") : "spec"}: ${message}${rule ? ` [${rule}]` : ""}`);
+    };
+    const report = (entryCount) => {
+        // The same problem can be found twice, such as a term that cites one finding in two places.
+        const unique = [...new Set(problems)];
+        if (unique.length) {
+            for (const p of unique)
+                console.error(p);
+            console.error(`\n${unique.length} problem(s) in ${entryCount} spec entries.`);
+            if (citedRule)
+                console.error("A label in brackets, such as [STATUS-14], names the rule of the documentation standard that the problem breaks. The standard opens it with the heading ###### STATUS-14, anchored at https://dinorefurb.com/documentation-standard/#status-14 and at #status-14 in a vendored copy.");
+            process.exit(1);
+        }
+    };
+    return { problem, report };
+}