@scientific-method/standard-checker 0.1.0 → 0.3.0

package/README.md

@@ -15,6 +15,12 @@ It exits with 0 when the repository passes, 1 when it reports problems (one line
 starting with the file's path), and 2 when the options are invalid. `--record-validation` cannot be
 combined with `--check`.
 
+A problem that breaks a numbered rule of the standard ends with the rule's label in brackets, such
+as `[STATUS-14]`. The standard opens that rule with the heading `###### STATUS-14`, anchored at
+`#status-14` on the site and in the copies restorations vendor, so the rule can be read on its
+own. Rules are numbered in Identifiers, Status and the shared part of Entry types so far, and
+problems under other sections carry no label yet.
+
 ## Options
 
 | Option | Meaning | Default |

package/dist/checks/base.d.ts

@@ -0,0 +1,7 @@
+import type { Context } from "../context.ts";
+import type { Deviation } from "./deviations.ts";
+/**
+ * Reports a spec ID, area or deviation that exists at the base (--base, or where HEAD forked from
+ * the base branch) and is gone now. Does nothing when there is no base to compare with.
+ */
+export declare function checkBase(ctx: Context, deviations: Map<string, Deviation>): void;

package/dist/checks/base.js

@@ -0,0 +1,72 @@
+// IDs, areas and deviations that exist on the base branch must not disappear.
+import { execFileSync } from "node:child_process";
+import { splitSections, tables } from "../markdown.js";
+/**
+ * Reports a spec ID, area or deviation that exists at the base (--base, or where HEAD forked from
+ * the base branch) and is gone now. Does nothing when there is no base to compare with.
+ */
+export function checkBase(ctx, deviations) {
+    const { problem } = ctx;
+    const { entries, areas } = ctx.spec;
+    const { repoDir, baseArg } = ctx.config;
+    // Without --base, compare with the point this branch left the base branch (the pull request's
+    // target in CI), not that branch's tip: an entry added on the base branch after this branch
+    // forked is not one this branch deleted.
+    const git = (...args) => execFileSync("git", ["-C", repoDir, ...args], { stdio: ["ignore", "pipe", "ignore"] }).toString();
+    let base = baseArg;
+    if (!base) {
+        const target = process.env.GITHUB_BASE_REF ? `origin/${process.env.GITHUB_BASE_REF}` : "origin/main";
+        try {
+            base = git("merge-base", "HEAD", target).trim();
+        }
+        catch {
+            base = null;
+        }
+    }
+    let listing = null;
+    if (base)
+        try {
+            listing = git("ls-tree", "-r", "--name-only", base, "--", "spec", "deviations");
+        }
+        catch {
+            if (baseArg)
+                problem(null, `cannot list spec/ at ${base}`);
+        }
+    if (listing) {
+        for (const p of listing.split("\n")) {
+            const m = /^spec\/(?:builds|sources|formats|rules|findings|experiments|bugs|screens)\/([A-Z]+-[A-Z0-9.-]+)\.md$/.exec(p);
+            if (m && !entries.has(m[1]))
+                problem(null, `${m[1]} exists at ${base} and has been deleted or renamed`, "IDENTIFIERS-6");
+            const d = /^deviations\/(DEV-[A-Z0-9]+-\d+)\.md$/.exec(p);
+            if (d && !deviations.has(d[1]))
+                problem(null, `${d[1]} exists at ${base} and has been deleted or renamed`);
+        }
+        // ./ makes the path relative to --root, which need not be the top of the repository. A file
+        // that does not exist at the base has nothing to compare, and each is read on its own so a
+        // missing README does not skip the deviation comparison.
+        const show = (path) => {
+            try {
+                return git("show", `${base}:./${path}`).replace(/\r\n/g, "\n");
+            }
+            catch {
+                return null;
+            }
+        };
+        const oldReadme = show("spec/README.md");
+        // Reads the area table the way the current README is read, so areas with or without
+        // backticks are both found.
+        const oldAreaSection = oldReadme && splitSections(oldReadme).find((s) => s.title === "Areas");
+        const oldAreaTable = oldAreaSection && tables(oldAreaSection.text)[0];
+        for (const row of (oldAreaTable || undefined)?.rows ?? []) {
+            const a = row[0].replaceAll("`", "");
+            if (!areas.includes(a))
+                problem(null, `area ${a} exists at ${base} and has been removed or renamed`, "IDENTIFIERS-5");
+        }
+        // A base from before the deviation log became a directory keeps its deviations in DEVIATIONS.md.
+        const oldDev = show("DEVIATIONS.md");
+        if (oldDev)
+            for (const m of oldDev.matchAll(/^## (DEV-[A-Z0-9]+-\d+)$/gm))
+                if (!deviations.has(m[1]))
+                    problem(null, `${m[1]} exists at ${base} and has been removed`);
+    }
+}

package/dist/checks/claims.d.ts

@@ -0,0 +1,4 @@
+import type { Context } from "../context.ts";
+import type { Entry } from "../types.ts";
+/** Checks the links and status of a claim: a format, rule, bug or screen. */
+export declare function checkClaim(ctx: Context, id: string, e: Entry): void;

package/dist/checks/claims.js

@@ -0,0 +1,83 @@
+// The checks of a claim's links (evidence, conflicting, related, split_with, complete_reading), of
+// its status against the evidence it cites, and of a bug's own fields.
+import { checkResolves, checkStatusCitations, evidenceFacts } from "../evidence.js";
+import { asList, kindOf } from "../ids.js";
+import { CLAIM_LINKS, FIELD_RULES, RELATED_KINDS } from "../standard.js";
+/** Checks the links and status of a claim: a format, rule, bug or screen. */
+export function checkClaim(ctx, id, e) {
+    const { problem } = ctx;
+    const { entries } = ctx.spec;
+    const { file, meta, kind } = e;
+    const status = meta.status;
+    for (const f of CLAIM_LINKS)
+        if (!Array.isArray(meta[f]))
+            problem(file, `${f} must be a list`, FIELD_RULES[f]);
+    const evidence = asList(meta.evidence);
+    const conflicting = asList(meta.conflicting);
+    const related = asList(meta.related);
+    const split = asList(meta.split_with);
+    checkResolves(ctx, file, evidence, "evidence");
+    checkResolves(ctx, file, conflicting, "conflicting");
+    checkResolves(ctx, file, related, "related");
+    checkResolves(ctx, file, split, "split_with");
+    if ("complete_reading" in meta) {
+        if (!Array.isArray(meta.complete_reading))
+            problem(file, "complete_reading must be a list");
+        const reading = asList(meta.complete_reading);
+        checkResolves(ctx, file, reading, "complete_reading");
+        const first = asList(meta.builds)[0];
+        for (const x of reading) {
+            const f = entries.get(x);
+            if (!f)
+                continue;
+            if (f.kind !== "FND" || f.meta.method !== "static")
+                problem(file, `complete_reading may hold only static findings, not ${x}`, "STATUS-4");
+            else if (!evidence.includes(x))
+                problem(file, `complete_reading names ${x}; list it in evidence as well`, "STATUS-4");
+            else if (!asList(f.meta.builds).includes(first))
+                problem(file, `complete_reading names ${x}, which does not list the first build ${first}`, "STATUS-4");
+        }
+    }
+    for (const x of evidence)
+        if (!["FND", "EXP", "SRC"].includes(kindOf(x)))
+            problem(file, `evidence may hold only findings, experiments and sources, not ${x}`, "ENTRY-TYPES-5");
+    for (const x of conflicting)
+        if (!["FND", "EXP"].includes(kindOf(x)))
+            problem(file, `conflicting may hold only findings and experiments, not ${x}`, "ENTRY-TYPES-5");
+    if (conflicting.length > 0 && status !== "disputed")
+        problem(file, "conflicting must be empty unless the status is disputed", "ENTRY-TYPES-5");
+    for (const x of related)
+        if (!RELATED_KINDS[kind].includes(kindOf(x)))
+            problem(file, `related may not link to ${x}`, "ENTRY-TYPES-6");
+    for (const s of split) {
+        const other = entries.get(s);
+        if (!other)
+            continue;
+        if (!asList(other.meta.split_with).includes(id))
+            problem(file, `${s} does not name ${id} back in split_with`, "ENTRY-TYPES-8");
+        for (const b of asList(meta.builds))
+            if (asList(other.meta.builds).includes(b))
+                problem(file, `${s} is split from this entry but also lists ${b}`, "ENTRY-TYPES-8");
+    }
+    if (status !== "superseded") {
+        const facts = evidenceFacts(entries, e);
+        checkStatusCitations(problem, file, status, facts, conflicting);
+        if (["supported", "established"].includes(status)) {
+            for (const b of asList(meta.builds)) {
+                const covered = evidence.some((x) => ["FND", "EXP"].includes(kindOf(x)) && asList(entries.get(x)?.meta.builds).includes(b));
+                if (!covered)
+                    problem(file, `lists ${b}, but no finding or experiment it cites lists that build`, "ENTRY-TYPES-7");
+            }
+        }
+    }
+    if (kind === "BUG") {
+        if (!["crash", "hang", "save-corruption", "rules", "presentation", "performance"].includes(meta.impact))
+            problem(file, "impact must be crash, hang, save-corruption, rules, presentation or performance");
+        if (!["unintended", "unclear"].includes(meta.intent))
+            problem(file, "intent must be unintended or unclear");
+        if (!["relied-on", "not-relied-on", "unknown"].includes(meta.player_reliance))
+            problem(file, "player_reliance must be relied-on, not-relied-on or unknown");
+        if (!related.some((x) => ["RULE", "FMT", "SCR"].includes(kindOf(x))))
+            problem(file, "a bug names at least one rule, format or screen in related", "ENTRY-TYPES-6");
+    }
+}

package/dist/checks/comment-addresses.d.ts

@@ -0,0 +1,3 @@
+import type { Context } from "../context.ts";
+/** Checks the addresses that comments in the --code and --references directories give. */
+export declare function checkCommentAddresses(ctx: Context): void;

package/dist/checks/comment-addresses.js

@@ -0,0 +1,111 @@
+// Addresses in code comments: an address of the original that a comment in the code gives,
+// written 0x… or as a neutral name (fn_…, g_…), is recorded in an entry the comment cites, or in an
+// entry that one of those cites as evidence. Evidence lives in the spec, so a comment that relies on
+// an address cites the finding that shows it; citing an ID only proves that the ID exists. A
+// superseded entry records nothing.
+//
+// Comments are found by reading .cs, .ts, .js and .mjs files as code, so `//` inside a string is
+// not a comment and `/* … */` is. A comment block is a run of consecutive lines that hold only
+// comment; a comment that trails code also takes the block above it and the comment lines below
+// it that start in the same column, and a comment-only line among those finds the same block. An
+// entry records an address written in its locations or its text, singly or inside a half-open
+// range, in either case. A range of more than --max-range bytes describes a section or a whole
+// table, not a place, and records only its two ends, nothing inside it: it would otherwise vouch
+// for every address in the program on behalf of each entry that cites it.
+//
+// A neutral name is always an address. A plain 0x value is one only inside an image that --images
+// gives, so colours, masks and offsets in the same notation are left alone; without --images only
+// neutral names are checked. Only flat 32-bit addresses are read: a segmented address (MZ, NE) is
+// not checked.
+import { codeComments } from "../code-comments.js";
+import { isSuperseded } from "../evidence.js";
+import { asList, idsIn } from "../ids.js";
+/** Checks the addresses that comments in the --code and --references directories give. */
+export function checkCommentAddresses(ctx) {
+    const { problem } = ctx;
+    const { entries } = ctx.spec;
+    const { images, maxRange } = ctx.config;
+    const ADDRESS_RE = /(?<![0-9A-Za-z_])(0x|fn_|g_)([0-9A-Fa-f]{8})(?![0-9A-Za-z_])/g;
+    const RANGE_RE = /(?<![0-9A-Za-z_])(?:0x|fn_|g_)([0-9A-Fa-f]{8})(?:\.\.0x([0-9A-Fa-f]{8}))?(?![0-9A-Za-z_])/g;
+    const inImage = (value) => images.some(([low, high]) => value >= low && value < high);
+    const recorded = new Map(); // entry ID -> half-open [low, high) ranges it records
+    const rangesOf = (id) => {
+        if (recorded.has(id))
+            return recorded.get(id);
+        const e = entries.get(id);
+        const ranges = [];
+        if (e && !isSuperseded(entries, id)) {
+            const text = [
+                e.body,
+                ...asList(e.meta.locations).map((loc) => loc && typeof loc === "object" && "address" in loc ? String(loc.address) : ""),
+            ].join("\n");
+            for (const [, low, high] of text.matchAll(RANGE_RE)) {
+                const range = high === undefined ? [parseInt(low, 16), parseInt(low, 16) + 1] : [parseInt(low, 16), parseInt(high, 16)];
+                if (range[1] <= range[0])
+                    continue;
+                // A larger range records only its two ends, which the entry writes out.
+                if (range[1] - range[0] <= maxRange)
+                    ranges.push(range);
+                else
+                    ranges.push([range[0], range[0] + 1], [range[1] - 1, range[1]]);
+            }
+        }
+        recorded.set(id, ranges);
+        return ranges;
+    };
+    const reach = (ids) => [
+        ...new Set([...ids, ...ids.flatMap((id) => asList(entries.get(id)?.meta.evidence).map(String))]),
+    ];
+    for (const { file, text } of ctx.codeFiles()) {
+        if (!/\.(cs|ts|js|mjs)$/.test(file))
+            continue;
+        const lines = codeComments(text, !file.endsWith(".cs"));
+        const commentOnly = (k) => k >= 0 && k < lines.length && !lines[k].code && lines[k].comments.length > 0;
+        // For each comment-only line that continues the comment trailing code on a line above (the
+        // rest of a /* … */ begun there, or a comment line starting in its column), that line.
+        const trails = [];
+        for (let k = 0; k < lines.length; k++) {
+            const t = k === 0 ? -1 : lines[k - 1].code ? (lines[k - 1].comments.length ? k - 1 : -1) : trails[k - 1];
+            const head = lines[k].comments[0];
+            trails[k] =
+                commentOnly(k) && t >= 0 && (head.continued || head.column === lines[t].comments.at(-1).column) ? t : -1;
+        }
+        const blocks = new Map(); // "first,last" -> the entries the block cites, and those within reach
+        for (let i = 0; i < lines.length; i++) {
+            const own = lines[i].comments.map((c) => c.text).join("\n");
+            const addresses = new Map();
+            for (const m of own.matchAll(ADDRESS_RE)) {
+                // The end of a half-open range is one byte past the last address it covers.
+                const rangeEnd = m.index >= 2 && own.slice(m.index - 2, m.index) === "..";
+                const value = parseInt(m[2], 16) - (rangeEnd ? 1 : 0);
+                if (m[1] === "0x" && !inImage(value))
+                    continue;
+                addresses.set(`${m[0]}@${value}`, [m[0], value]);
+            }
+            if (!addresses.size)
+                continue;
+            // A line with code, or one continuing the comment that trails it, belongs to that comment.
+            const t = lines[i].code ? i : trails[i];
+            let first = t >= 0 ? t : i, last = first;
+            while (first > 0 && (commentOnly(first - 1) || lines[first].comments[0]?.continued))
+                first--;
+            while (t >= 0 ? trails[last + 1] === t : commentOnly(last + 1))
+                last++;
+            const key = `${first},${last}`;
+            if (!blocks.has(key)) {
+                const block = lines
+                    .slice(first, last + 1)
+                    .flatMap((l) => l.comments.map((c) => c.text))
+                    .join("\n");
+                const cited = idsIn(block).filter((x) => entries.has(x));
+                blocks.set(key, { cited, scope: reach(cited) });
+            }
+            const { cited, scope } = blocks.get(key);
+            for (const [address, value] of addresses.values()) {
+                if (scope.some((x) => rangesOf(x).some(([low, high]) => value >= low && value < high)))
+                    continue;
+                problem(file, `line ${i + 1} gives ${address}, but ${cited.length ? `neither ${cited.join(", ")} nor the evidence ${cited.length === 1 ? "it cites" : "they cite"} records it` : "the comment cites no entry that records it"}; cite the finding that records it, or record it in a new one`);
+            }
+        }
+    }
+}

package/dist/checks/cross-entry.d.ts

@@ -0,0 +1,4 @@
+import type { Context } from "../context.ts";
+import type { FormatNames } from "./formats.ts";
+/** Runs the checks across entries, in order. */
+export declare function checkAcrossEntries(ctx: Context, { enumNames }: FormatNames): void;

package/dist/checks/cross-entry.js

@@ -0,0 +1,177 @@
+// Checks that look across entries: what the glossary and entry bodies cite, paths into the
+// original's data, enumeration names, saves and recordings, value files, superseded_by chains and
+// split entries.
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { isSuperseded } from "../evidence.js";
+import { asList, idsIn } from "../ids.js";
+import { readText } from "../markdown.js";
+import { KINDS } from "../standard.js";
+/** Runs the checks across entries, in order. */
+export function checkAcrossEntries(ctx, { enumNames }) {
+    const { problem, config } = ctx;
+    const { specDir } = config;
+    const { entries, glossary, glossaryFiles, glossaryDir, buildFiles } = ctx.spec;
+    const glossaryFile = (term) => glossaryFiles.get(term) ?? glossaryDir;
+    // Glossary claims
+    for (const [term, text] of glossary) {
+        for (const x of idsIn(text))
+            if (!entries.has(x))
+                problem(glossaryFile(term), `${term} cites ${x}, which does not exist`);
+            else if (isSuperseded(entries, x))
+                problem(glossaryFile(term), `${term} cites ${x}, which is superseded`);
+    }
+    // Body references
+    for (const [, e] of entries)
+        for (const x of idsIn(e.body))
+            if (!entries.has(x))
+                problem(e.file, `the body names ${x}, which does not exist`);
+    // A path into a build's data directories names a file of some build with its exact case. A
+    // directory, or a pattern whose last part holds a placeholder such as nn or xxx, is left alone.
+    // The data directories are the top-level directories of the build files unless --data-dirs
+    // names them. A build path that holds a space is matched whole, longest first, together with any
+    // path that follows it, so Dir/With Space/file.ext is read as one path.
+    {
+        const exact = new Set();
+        const folded = new Map();
+        const topDirs = new Set();
+        for (const files of buildFiles.values())
+            for (const f of files) {
+                const p = f.path;
+                if (typeof p !== "string")
+                    continue;
+                exact.add(p);
+                folded.set(p.toLowerCase(), p);
+                const parts = p.split("/");
+                if (parts.length > 1)
+                    topDirs.add(parts[0]);
+                for (let i = 1; i < parts.length; i++)
+                    exact.add(parts.slice(0, i).join("/"));
+            }
+        const dataDirs = config.dataDirs ?? [...topDirs].sort();
+        const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const tail = String.raw `[A-Za-z0-9_./-]*[A-Za-z0-9]`;
+        const spaced = [...exact]
+            .filter((p) => p.includes(" ") && dataDirs.includes(p.split("/")[0]))
+            .sort((a, b) => b.length - a.length);
+        const whole = spaced.length ? `(?:${spaced.map(escapeRe).join("|")})(?:${tail})?|` : "";
+        const dataPath = new RegExp(String.raw `(?<!\w)(?:${whole}(?:${dataDirs.map(escapeRe).join("|")})\/${tail})`, "g");
+        const dirsFolded = new Set([...exact].map((p) => p.toLowerCase()));
+        const checkPaths = (file, text) => {
+            for (const m of text.matchAll(dataPath)) {
+                const p = m[0];
+                if (exact.has(p))
+                    continue;
+                const last = p.split("/").pop();
+                if (folded.has(p.toLowerCase()))
+                    problem(file, `path ${p} is written ${folded.get(p.toLowerCase())} in the build entry`);
+                else if (dirsFolded.has(p.toLowerCase()))
+                    problem(file, `directory ${p} differs in case from the build entry`);
+                else if (/\d/.test(last) && !/nn|NN|xx|XX/.test(last))
+                    problem(file, `path ${p} is not a file of any build`);
+            }
+        };
+        if (dataDirs.length > 0) {
+            for (const [, e] of entries)
+                if (e.kind !== "BLD")
+                    checkPaths(e.file, readFileSync(e.file, "utf8"));
+            for (const [term, text] of glossary)
+                if (glossaryFiles.has(term))
+                    checkPaths(glossaryFiles.get(term), text);
+        }
+    }
+    // Enumeration names are unique apart from split formats
+    for (const [name, fmts] of enumNames) {
+        const uniq = [...new Set(fmts)];
+        if (uniq.length > 1 &&
+            !uniq.every((f) => uniq.every((g) => f === g || asList(entries.get(f).meta.split_with).includes(g))))
+            problem(null, `enumeration name ${name} is defined by ${uniq.join(", ")}`);
+    }
+    // Saves and recordings must be listed in spec/LICENSE
+    {
+        const licence = existsSync(join(specDir, "LICENSE")) ? readFileSync(join(specDir, "LICENSE"), "utf8") : "";
+        if (!licence)
+            problem(null, "spec/LICENSE is missing");
+        for (const sub of ["saves", "recordings"]) {
+            const d = join(specDir, "experiments", sub);
+            if (!existsSync(d))
+                continue;
+            for (const f of readdirSync(d)) {
+                if (f === ".gitkeep" || f.endsWith(".patch.json"))
+                    continue;
+                if (!licence.includes(`experiments/${sub}/${f}`))
+                    problem(join(d, f), "is not listed in spec/LICENSE as covered by neither licence");
+            }
+        }
+    }
+    // Every save and recording is named by some experiment.
+    {
+        const named = new Set();
+        for (const e of entries.values())
+            if (e.kind === "EXP")
+                for (const v of [e.meta.starting_state, e.meta.recording])
+                    if (typeof v === "string")
+                        named.add(v);
+        for (const sub of ["saves", "recordings"]) {
+            const d = join(specDir, "experiments", sub);
+            if (existsSync(d))
+                for (const f of readdirSync(d))
+                    if (f !== ".gitkeep" && !named.has(`${sub}/${f}`))
+                        problem(join(d, f), "is named by no experiment");
+        }
+    }
+    // Every value file belongs to the entry its name gives, in that entry's directory, and is named by it.
+    for (const { dir } of Object.values(KINDS)) {
+        const d = join(specDir, dir);
+        if (!existsSync(d))
+            continue;
+        for (const name of readdirSync(d)) {
+            if (!name.endsWith(".csv"))
+                continue;
+            const m = /^([A-Z]+-[A-Z0-9]+-\d{3,})\.[A-Za-z0-9_]+\.csv$/.exec(name);
+            const owner = m && entries.get(m[1]);
+            if (!m || !owner || owner.file !== join(d, `${m[1]}.md`)) {
+                problem(join(d, name), "belongs to no entry; a value file is named <ID>.<table>.csv and sits beside its entry");
+                continue;
+            }
+            if (!readText(owner.file).includes(name))
+                problem(join(d, name), `is not named by ${m[1]}`);
+        }
+    }
+    // No chain of superseded_by links leads back to where it started.
+    for (const [id, e] of entries) {
+        const seen = new Set();
+        const stack = [...asList(e.meta.superseded_by)];
+        while (stack.length) {
+            const x = stack.pop();
+            if (x === id) {
+                problem(e.file, "its superseded_by links lead back to it", "IDENTIFIERS-7");
+                break;
+            }
+            if (seen.has(x) || !entries.has(x))
+                continue;
+            seen.add(x);
+            stack.push(...asList(entries.get(x).meta.superseded_by));
+        }
+    }
+    // An entry that relates to a split rule or format relates to every entry of the split, and every
+    // build it lists is listed by one of them.
+    for (const [id, e] of entries) {
+        if (KINDS[e.kind].statuses !== "claim" || e.meta.status === "superseded")
+            continue;
+        const related = asList(e.meta.related);
+        for (const x of related) {
+            const other = entries.get(x);
+            // A superseded part cannot be related to, so it is left out of the group.
+            const group = other ? [x, ...asList(other.meta.split_with).filter((g) => !isSuperseded(entries, g))] : [];
+            if (group.length < 2 || group.includes(id))
+                continue;
+            for (const g of group)
+                if (!related.includes(g))
+                    problem(e.file, `relates to ${x}, which is split with ${g}; add ${g} to related`, "ENTRY-TYPES-6");
+            for (const b of asList(e.meta.builds))
+                if (!group.some((g) => asList(entries.get(g)?.meta.builds).includes(b)))
+                    problem(e.file, `lists ${b}, which no entry of the split ${group.join(", ")} lists`, "ENTRY-TYPES-8");
+        }
+    }
+}

package/dist/checks/deviations.d.ts

@@ -0,0 +1,12 @@
+import type { Context } from "../context.ts";
+/** One deviation of the log. */
+export interface Deviation {
+    /** The spec IDs its Departs from item names. */
+    departs: string[];
+    /** Whether its Dropped item says it was dropped. */
+    dropped: boolean;
+    /** Its file. */
+    file: string;
+}
+/** Reads and checks deviations/. Returns deviation ID -> the deviation. */
+export declare function checkDeviations(ctx: Context): Map<string, Deviation>;

package/dist/checks/deviations.js

@@ -0,0 +1,101 @@
+// The deviation log: one file per deviation in deviations/, named after its ID and opening with it
+// as a # heading, followed by its items.
+import { existsSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { checkResolves, isSuperseded } from "../evidence.js";
+import { termFiles } from "../files.js";
+import { areaOf, idsIn, kindOf } from "../ids.js";
+import { readText } from "../markdown.js";
+/** Reads and checks deviations/. Returns deviation ID -> the deviation. */
+export function checkDeviations(ctx) {
+    const { problem } = ctx;
+    const { entries, areas } = ctx.spec;
+    const { repoDir } = ctx.config;
+    const deviations = new Map();
+    const devDir = join(repoDir, "deviations");
+    {
+        if (existsSync(join(repoDir, "DEVIATIONS.md")))
+            problem(join(repoDir, "DEVIATIONS.md"), "the deviation log is the directory deviations/; move each ## deviation to deviations/<ID>.md with the ID as its # heading");
+        if (!existsSync(devDir))
+            problem(null, "deviations/ is missing");
+        else
+            for (const file of termFiles(devDir)) {
+                if (statSync(file).isDirectory() || !file.endsWith(".md")) {
+                    problem(file, "is not a deviation file; deviations/ holds one <ID>.md per deviation");
+                    continue;
+                }
+                const m = /^# (.+)\n?([\s\S]*)$/.exec(readText(file));
+                if (!m) {
+                    problem(file, "opens with the deviation's ID as a # heading");
+                    continue;
+                }
+                const title = m[1].trim();
+                if (!/^DEV-[A-Z][A-Z0-9]*-\d{3,}$/.test(title)) {
+                    problem(file, `heading ${title} is not a deviation ID`);
+                    continue;
+                }
+                if (basename(file) !== `${title}.md`)
+                    problem(file, `file name must be ${title}.md`);
+                if (deviations.has(title))
+                    problem(file, `${title} is used twice`);
+                if (!areas.includes(areaOf(title)))
+                    problem(file, `${title}: area is not in the area list`);
+                const items = [...m[2].matchAll(/^- ([A-Za-z ]+): (.*)$/gm)].map((x) => [x[1], x[2]]);
+                const item = Object.fromEntries(items);
+                const order = [
+                    "Departs from",
+                    "Reason",
+                    "Setting",
+                    "Default",
+                    ...("Justification" in item ? ["Justification"] : []),
+                    "Dropped",
+                ];
+                if (items
+                    .slice(0, order.length)
+                    .map((x) => x[0])
+                    .join("|") !== order.join("|"))
+                    problem(file, `${title}: items must be ${order.join(", ")} in that order`);
+                const departs = idsIn(item["Departs from"]);
+                const dropped = Boolean(item.Dropped) && item.Dropped !== "no";
+                if (dropped && !/^\d{4}-\d{2}-\d{2}\b/.test(item.Dropped))
+                    problem(file, `${title}: Dropped gives the date, YYYY-MM-DD, and the reason`);
+                checkResolves(ctx, file, departs, `${title} Departs from`);
+                if (!dropped) {
+                    if (!departs.some((x) => ["RULE", "FMT", "SCR"].includes(kindOf(x))))
+                        problem(file, `${title}: Departs from names at least one rule, format or screen`);
+                    for (const x of departs)
+                        if (isSuperseded(entries, x))
+                            problem(file, `${title} departs from ${x}, which is superseded`);
+                    checkDeviationDefault(ctx, file, title, item, departs);
+                }
+                deviations.set(title, { departs, dropped, file });
+            }
+    }
+    return deviations;
+}
+// Default is off, on or mandatory. Only the fix of an unintended, not-relied-on bug is on by right;
+// mandatory, and on for anything else, carry a Justification that the rebuild is strictly better or a
+// small judgement call that makes the game better to play.
+function checkDeviationDefault(ctx, path, title, item, departs) {
+    const { problem } = ctx;
+    const { entries } = ctx.spec;
+    const defaults = ["off", "on", "mandatory"];
+    const dflt = item.Default;
+    if (!defaults.includes(dflt))
+        return problem(path, `${title}: Default is one of ${defaults.join(", ")}`);
+    if ((item.Setting === "None") !== (dflt === "mandatory"))
+        return problem(path, `${title}: Default is mandatory exactly when Setting is None`);
+    const bugs = departs
+        .filter((x) => kindOf(x) === "BUG")
+        .map((x) => entries.get(x))
+        .filter((b) => Boolean(b));
+    const bugFix = bugs.length > 0 && bugs.every((b) => b.meta.intent === "unintended" && b.meta.player_reliance === "not-relied-on");
+    if (bugFix && dflt === "off")
+        problem(path, `${title}: Default is on or mandatory for the fix of an unintended, not-relied-on bug`);
+    const needsJustification = dflt === "mandatory" || (dflt === "on" && !bugFix);
+    const hasJustification = "Justification" in item;
+    if (needsJustification && !hasJustification)
+        problem(path, `${title}: is ${dflt} but has no Justification saying why the rebuild's behaviour is strictly better, or what the judgement call improves`);
+    if (!needsJustification && hasJustification)
+        problem(path, `${title}: has a Justification, which only a mandatory deviation or one that is on without fixing an unintended, not-relied-on bug has`);
+}

package/dist/checks/entries.d.ts

@@ -0,0 +1,7 @@
+import type { Context } from "../context.ts";
+import type { FormatNames } from "./formats.ts";
+/**
+ * Checks every entry, kind by kind, and returns the names the formats' tables define, which the
+ * rule checks read.
+ */
+export declare function checkEntries(ctx: Context): FormatNames;