@scientific-method/standard-checker 0.1.0 → 0.2.0

package/dist/generate/indexes.js

@@ -0,0 +1,135 @@
+// The four indexes in spec/index/: by kind, by area, by status, and what cites each entry.
+import { dirname, join, relative } from "node:path";
+import { evidenceFacts } from "../evidence.js";
+import { toSlash } from "../files.js";
+import { areaOf, asList, compareIds, idsIn, isAlias, kindOf } from "../ids.js";
+import { CLAIM_STATUSES, EVIDENCE_STATUSES, KINDS } from "../standard.js";
+import { GENERATED, layout } from "./layout.js";
+/** Renders the four indexes, split where the line limit requires. Returns absolute path -> text. */
+export function generateIndexes(ctx) {
+    const { entries, areas, glossary, glossaryFiles } = ctx.spec;
+    const { specDir } = ctx.config;
+    const esc = (s) => String(s ?? "").replaceAll("|", "\\|");
+    const sortedIds = [...entries.keys()].sort(compareIds);
+    const indexDir = join(specDir, "index");
+    const linkFrom = (path) => (id) => `[${id}](${toSlash(relative(dirname(join(indexDir, `${path}.md`)), entries.get(id).file))})`;
+    const opening = (path, what) => [`# ${path}`, "", GENERATED, "", what, ""];
+    // A file of the full index lists every group, empty ones too, so its counts read as a progress
+    // report. A file of a split index lists only the groups it has entries in.
+    const isWhole = (path) => !path.includes("/");
+    function renderByKind(ids, path) {
+        const link = linkFrom(path);
+        const out = opening(path, "Entries by kind.");
+        for (const [kind, { dir }] of Object.entries(KINDS)) {
+            const kindIds = ids.filter((x) => kindOf(x) === kind);
+            if (!kindIds.length && !isWhole(path))
+                continue;
+            out.push(`## ${dir}`, "", `${kindIds.length} entries.`, "");
+            if (kindIds.length)
+                out.push("| ID | Title | Status |", "|---|---|---|", ...kindIds.map((x) => `| ${link(x)} | ${esc(entries.get(x).meta.title)} | ${entries.get(x).meta.status ?? "None"} |`), "");
+        }
+        return out.join("\n");
+    }
+    function renderByArea(ids, path) {
+        const link = linkFrom(path);
+        const out = opening(path, "Entries by area.");
+        for (const a of areas) {
+            const areaIds = ids.filter((x) => areaOf(x) === a);
+            if (!areaIds.length && !isWhole(path))
+                continue;
+            out.push(`## ${a}`, "");
+            if (!areaIds.length)
+                out.push("None.", "");
+            else
+                out.push("| ID | Title | Status |", "|---|---|---|", ...areaIds.map((x) => `| ${link(x)} | ${esc(entries.get(x).meta.title)} | ${entries.get(x).meta.status} |`), "");
+        }
+        return out.join("\n");
+    }
+    function renderByStatus(ids, path) {
+        const link = linkFrom(path);
+        const out = opening(path, "Entries by status.");
+        const section = (title, intro, list, withStatus) => {
+            if (!list.length && !isWhole(path))
+                return;
+            out.push(`## ${title}`, "");
+            if (intro)
+                out.push(intro, "");
+            if (!list.length) {
+                out.push(intro ? "None." : "0 entries.", "");
+                return;
+            }
+            if (!intro)
+                out.push(`${list.length} entries.`, "");
+            out.push(withStatus ? "| ID | Title | Status |" : "| ID | Title |", withStatus ? "|---|---|---|" : "|---|---|", ...list.map((x) => `| ${link(x)} | ${esc(entries.get(x).meta.title)} |${withStatus ? ` ${entries.get(x).meta.status} |` : ""}`), "");
+        };
+        for (const st of [...CLAIM_STATUSES, ...EVIDENCE_STATUSES.filter((x) => x !== "superseded")])
+            section(st, null, ids.filter((x) => entries.get(x).meta.status === st), false);
+        section("Established on unreproduced evidence", "Entries whose status is established and whose findings and experiments are all only recorded.", ids.filter((x) => KINDS[kindOf(x)].statuses === "claim" &&
+            entries.get(x).meta.status === "established" &&
+            asList(entries.get(x).meta.evidence)
+                .filter((y) => ["FND", "EXP"].includes(kindOf(y)))
+                .every((y) => entries.get(y)?.meta.status !== "reproduced")), false);
+        // Listed only when there are any, so that indexes written before complete readings stay fresh.
+        const byReading = ids.filter((x) => KINDS[kindOf(x)].statuses === "claim" &&
+            entries.get(x).meta.status === "established" &&
+            evidenceFacts(entries, entries.get(x)).dynamic === 0);
+        if (byReading.length)
+            section("Established by a complete reading alone", "Entries whose status is established and that no dynamic finding or experiment confirms.", byReading, false);
+        section("Open questions", "Entries whose Open questions section says more than None known.", ids.filter((x) => {
+            const s = entries.get(x).sections.find((y) => y.title === "Open questions");
+            return s && !/^\s*None( known)?\.\s*$/.test(s.text);
+        }), true);
+        return out.join("\n");
+    }
+    const refs = new Map(sortedIds.map((x) => [x, new Map()]));
+    const addRef = (to, from, how) => {
+        if (refs.has(to) && to !== from) {
+            const m = refs.get(to);
+            if (!m.has(from))
+                m.set(from, new Set());
+            m.get(from).add(how);
+        }
+    };
+    for (const [id, e] of entries) {
+        for (const f of ["evidence", "conflicting", "related", "split_with", "superseded_by", "builds"])
+            for (const x of asList(e.meta[f]))
+                addRef(x, id, f);
+        for (const loc of asList(e.meta.locations))
+            if (loc?.build)
+                addRef(loc.build, id, "locations");
+        for (const x of idsIn(e.body))
+            addRef(x, id, "body");
+    }
+    for (const [term, text] of glossary)
+        for (const x of idsIn(text))
+            addRef(x, `glossary:${term}`, "glossary");
+    // One row per entry: everything that cites it goes in one cell.
+    function renderReferences(ids, path) {
+        const link = linkFrom(path);
+        const termLink = (term) => glossaryFiles.has(term)
+            ? `[${term}](${toSlash(relative(dirname(join(indexDir, `${path}.md`)), glossaryFiles.get(term)))})`
+            : esc(term);
+        const out = opening(path, "For each entry, the entries and glossary terms that cite or relate to it, and the field they do it in.");
+        out.push("| ID | Cited by |", "|---|---|");
+        for (const x of ids) {
+            const cited = [...refs.get(x)]
+                .sort((a, b) => compareIds(a[0], b[0]))
+                .map(([from, hows]) => `${from.startsWith("glossary:") ? termLink(from.slice(9)) : link(from)} (${[...hows].sort().join(", ")})`);
+            out.push(`| ${link(x)} | ${cited.join(", ") || "None"} |`);
+        }
+        out.push("");
+        return out.join("\n");
+    }
+    const generated = new Map(); // absolute path -> text
+    const areaIds = sortedIds.filter((x) => !isAlias(x));
+    const indexes = {
+        "by-kind": [renderByKind, sortedIds],
+        "by-area": [renderByArea, areaIds],
+        "by-status": [renderByStatus, sortedIds],
+        references: [renderReferences, sortedIds],
+    };
+    for (const [name, [render, ids]] of Object.entries(indexes))
+        for (const [path, { text }] of layout(ctx, name, ids, render))
+            generated.set(join(indexDir, `${path}.md`), text);
+    return generated;
+}

package/dist/generate/layout.d.ts

@@ -0,0 +1,18 @@
+import type { Context } from "../context.ts";
+import type { Render } from "../types.ts";
+/** The block of an ID in a split file: its hundred, such as 100, or the first character of an alias. */
+export declare const blockOf: (id: string) => string;
+/**
+ * Lays out one generated file: `${name}.md` when render's text fits, otherwise a directory split only
+ * as far as the limit requires. render(ids, path) gives the text of the file at path, which has no
+ * .md and is relative to the generated tree. Returns a Map of path -> { ids, text }.
+ */
+export declare function layout(ctx: Context, name: string, ids: string[], render: Render, level?: number, out?: Map<string, {
+    ids: string[];
+    text: string;
+}>): Map<string, {
+    ids: string[];
+    text: string;
+}>;
+/** The comment every generated file carries under its heading. */
+export declare const GENERATED = "<!-- Generated by the documentation standard check. Do not edit. -->";

package/dist/generate/layout.js

@@ -0,0 +1,49 @@
+// Splitting generated files. A generated file that would pass the line limit becomes a directory of
+// the same name, split by area (BLD-SRC for builds and sources, which have no area), then by kind,
+// then by a block of 100 numbers, or by the first character of a build's or source's alias.
+import { areaOf, isAlias, kindOf } from "../ids.js";
+import { lineCount } from "../markdown.js";
+import { KINDS, LINE_LIMIT } from "../standard.js";
+const groupOf = (id) => (isAlias(id) ? "BLD-SRC" : areaOf(id));
+/** The block of an ID in a split file: its hundred, such as 100, or the first character of an alias. */
+export const blockOf = (id) => {
+    const kind = kindOf(id);
+    if (kind === "BLD" || kind === "SRC")
+        return id.charAt(kind.length + 1);
+    return String(Math.floor(Number(id.split("-")[2]) / 100) * 100).padStart(3, "0");
+};
+const SPLIT_LEVELS = [groupOf, kindOf, blockOf];
+function orderKeys(areas, level, keys) {
+    if (level === 0)
+        return [...areas.filter((a) => keys.includes(a)), ...keys.filter((k) => !areas.includes(k)).sort()];
+    if (level === 1)
+        return Object.keys(KINDS).filter((k) => keys.includes(k));
+    return keys.sort((a, b) => (/^\d+$/.test(a) && /^\d+$/.test(b) ? Number(a) - Number(b) : a < b ? -1 : a > b ? 1 : 0));
+}
+/**
+ * Lays out one generated file: `${name}.md` when render's text fits, otherwise a directory split only
+ * as far as the limit requires. render(ids, path) gives the text of the file at path, which has no
+ * .md and is relative to the generated tree. Returns a Map of path -> { ids, text }.
+ */
+export function layout(ctx, name, ids, render, level = 0, out = new Map()) {
+    const text = render(ids, name);
+    const { problem } = ctx;
+    if (lineCount(text) <= LINE_LIMIT || level === SPLIT_LEVELS.length) {
+        if (lineCount(text) > LINE_LIMIT)
+            problem(null, `${name}.md would pass ${LINE_LIMIT} lines even split by block`);
+        out.set(name, { ids, text });
+        return out;
+    }
+    const groups = new Map();
+    for (const id of ids) {
+        const key = SPLIT_LEVELS[level](id);
+        if (!groups.has(key))
+            groups.set(key, []);
+        groups.get(key).push(id);
+    }
+    for (const key of orderKeys(ctx.spec.areas, level, [...groups.keys()]))
+        layout(ctx, `${name}/${key}`, groups.get(key), render, level + 1, out);
+    return out;
+}
+/** The comment every generated file carries under its heading. */
+export const GENERATED = "<!-- Generated by the documentation standard check. Do not edit. -->";

package/dist/generate/parity-md.d.ts

@@ -0,0 +1,7 @@
+import type { Context } from "../context.ts";
+import type { Parity } from "../checks/parity.ts";
+/**
+ * Adds the text of PARITY.md to generated, unless PARITY.md still holds the rows (which the parity
+ * check reports).
+ */
+export declare function generateParity(ctx: Context, parity: Parity, generated: Map<string, string>): void;

package/dist/generate/parity-md.js

@@ -0,0 +1,44 @@
+// PARITY.md: the totals of the parity rows, and a link to each area's rows.
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { areaOf } from "../ids.js";
+import { GENERATED } from "./layout.js";
+/**
+ * Adds the text of PARITY.md to generated, unless PARITY.md still holds the rows (which the parity
+ * check reports).
+ */
+export function generateParity(ctx, parity, generated) {
+    const { areas } = ctx.spec;
+    const { repoDir } = ctx.config;
+    const parityDir = join(repoDir, "parity");
+    const { counts: parityCounts, rows: parityRows, legacy: legacyParity } = parity;
+    const out = [
+        "# Parity matrix",
+        "",
+        GENERATED,
+        "",
+        "How much of the spec in `spec/` the rebuild does. The rows are in `parity/`, one file per area.",
+        "",
+        "| Status | Rows |",
+        "|---|---|",
+        ...["unknown", "sourced", "supported", "established", "disputed", "implemented", "validated"].map((k) => `| ${k} | ${parityCounts.status[k] ?? 0} |`),
+        "",
+        "| Code | Rows |",
+        "|---|---|",
+        ...["missing", "partial", "complete"].map((k) => `| ${k} | ${parityCounts.code[k] ?? 0} |`),
+        "",
+        "## Areas",
+        "",
+    ];
+    const withRows = areas.filter((a) => existsSync(join(parityDir, `${a}.md`)) || existsSync(join(parityDir, a)));
+    if (!withRows.length)
+        out.push("None yet.");
+    else
+        out.push("| Area | Rows |", "|---|---|", ...withRows.map((a) => {
+            const target = existsSync(join(parityDir, `${a}.md`)) ? `parity/${a}.md` : `parity/${a}/`;
+            return `| [${a}](${target}) | ${[...parityRows.keys()].filter((x) => areaOf(x) === a).length} |`;
+        }));
+    out.push("");
+    if (!legacyParity)
+        generated.set(join(repoDir, "PARITY.md"), out.join("\n"));
+}

package/dist/generate/write.d.ts

@@ -0,0 +1,8 @@
+import type { Context } from "../context.ts";
+/**
+ * Writes each generated file whose text has changed and removes any other file in spec/index/,
+ * printing what it did. With --check it reports them as problems instead.
+ */
+export declare function writeGenerated(ctx: Context, generated: Map<string, string>): void;
+/** Reports every Markdown file the standard defines that is longer than LINE_LIMIT lines. */
+export declare function checkLineLimits(ctx: Context): void;

package/dist/generate/write.js

@@ -0,0 +1,75 @@
+// Writing the generated files, or with --check reporting the stale ones, and the line limit of
+// every Markdown file the standard defines.
+import { existsSync, mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { markdownTree, toSlash, walk } from "../files.js";
+import { lineCount, readText } from "../markdown.js";
+import { LINE_LIMIT } from "../standard.js";
+/**
+ * Writes each generated file whose text has changed and removes any other file in spec/index/,
+ * printing what it did. With --check it reports them as problems instead.
+ */
+export function writeGenerated(ctx, generated) {
+    const { problem } = ctx;
+    const { repoDir, specDir, checkOnly } = ctx.config;
+    const indexDir = join(specDir, "index");
+    const stale = [];
+    for (const [p, content] of generated) {
+        const current = existsSync(p) ? readText(p) : null;
+        if (current !== content)
+            stale.push(p);
+    }
+    const extra = [...(existsSync(indexDir) ? markdownTree(indexDir).values() : [])].filter((f) => !generated.has(f));
+    if (checkOnly) {
+        for (const p of stale)
+            problem(p, existsSync(p)
+                ? "is stale; run the check without --check to rewrite it"
+                : "is missing; run the check without --check to write it");
+        for (const f of extra)
+            problem(f, "is not a file the check writes; run the check without --check to remove it");
+    }
+    else {
+        for (const p of stale) {
+            mkdirSync(dirname(p), { recursive: true });
+            writeFileSync(p, generated.get(p));
+            console.log(`wrote ${toSlash(relative(repoDir, p))}`);
+        }
+        for (const f of extra) {
+            rmSync(f);
+            console.log(`removed ${toSlash(relative(repoDir, f))}`);
+        }
+        // Directories left empty by a file that moved.
+        const prune = (dir) => {
+            for (const name of readdirSync(dir)) {
+                const p = join(dir, name);
+                if (statSync(p).isDirectory())
+                    prune(p);
+            }
+            if (dir !== indexDir && readdirSync(dir).length === 0)
+                rmSync(dir, { recursive: true });
+        };
+        if (existsSync(indexDir))
+            prune(indexDir);
+    }
+}
+/** Reports every Markdown file the standard defines that is longer than LINE_LIMIT lines. */
+export function checkLineLimits(ctx) {
+    const { problem } = ctx;
+    const { repoDir, specDir } = ctx.config;
+    const validationPath = join(repoDir, "VALIDATION.md");
+    const parityDir = join(repoDir, "parity");
+    const devDir = join(repoDir, "deviations");
+    const files = [join(repoDir, "PARITY.md"), validationPath];
+    for (const dir of [specDir, parityDir, devDir])
+        walk(dir, (f) => {
+            if (f.endsWith(".md"))
+                files.push(f);
+        });
+    for (const f of files) {
+        if (!existsSync(f))
+            continue;
+        const lines = lineCount(readText(f));
+        if (lines > LINE_LIMIT)
+            problem(f, `has ${lines} lines; the documentation standard allows ${LINE_LIMIT}. Split it as the standard's File size section describes`);
+    }
+}

package/dist/ids.d.ts

@@ -0,0 +1,13 @@
+import type { Yaml } from "./types.ts";
+/** The distinct spec IDs in text, in the order they first appear. */
+export declare const idsIn: (text: unknown) => string[];
+/** The kind of an ID, such as `RULE`. */
+export declare const kindOf: (id: string) => string;
+/** The area of an ID, such as `COMBAT` (for a build or source, the start of its alias). */
+export declare const areaOf: (id: string) => string;
+/** Builds and sources have an alias in place of an area and a number. */
+export declare const isAlias: (id: string) => boolean;
+/** Compares two IDs for sorting: by number within one kind and area, otherwise by UTF-16 code unit. */
+export declare const compareIds: (a: string, b: string) => -1 | 0 | 1;
+/** A front matter value as a list: a list as is, nothing for null, undefined or "", else a list of one. */
+export declare const asList: (v: Yaml) => Yaml[];

package/dist/ids.js

@@ -0,0 +1,22 @@
+// Spec IDs: finding them in text, taking them apart and ordering them.
+import { ID_RE } from "./standard.js";
+/** The distinct spec IDs in text, in the order they first appear. */
+export const idsIn = (text) => [...new Set(String(text ?? "").match(ID_RE) ?? [])];
+/** The kind of an ID, such as `RULE`. */
+export const kindOf = (id) => id.split("-")[0];
+/** The area of an ID, such as `COMBAT` (for a build or source, the start of its alias). */
+export const areaOf = (id) => id.split("-")[1];
+/** Builds and sources have an alias in place of an area and a number. */
+export const isAlias = (id) => ["BLD", "SRC"].includes(kindOf(id));
+// Orders IDs of one kind and area by number, so RULE-A-999 comes before RULE-A-1000. Anything else
+// compares by UTF-16 code unit, as Array.prototype.sort does, so the order does not depend on the
+// machine's locale.
+const idSortKey = (id) => id.replace(/^((?:FMT|RULE|FND|EXP|BUG|SCR|DEV)-[A-Z][A-Z0-9]*-)(\d+)$/, (_, head, n) => head + n.padStart(12, "0"));
+/** Compares two IDs for sorting: by number within one kind and area, otherwise by UTF-16 code unit. */
+export const compareIds = (a, b) => {
+    const x = idSortKey(a);
+    const y = idSortKey(b);
+    return x < y ? -1 : x > y ? 1 : 0;
+};
+/** A front matter value as a list: a list as is, nothing for null, undefined or "", else a list of one. */
+export const asList = (v) => Array.isArray(v) ? v : v === null || v === undefined || v === "" ? [] : [v];

package/dist/load/builds.d.ts

@@ -0,0 +1,9 @@
+import type { LoadContext } from "../context.ts";
+import type { Entry, Meta } from "../types.ts";
+/**
+ * Reads and checks the manifest of every build entry, and reports a manifest or list of other files
+ * that belongs to no build. Returns build ID -> the items of its files list that are maps.
+ */
+export declare function loadBuildFiles({ config, problem }: LoadContext, entries: Map<string, Entry>): Map<string, Meta[]>;
+/** Checks each build's list of other files against its manifest and its Other files section. */
+export declare function checkOtherFiles({ problem }: LoadContext, entries: Map<string, Entry>, buildFiles: Map<string, Meta[]>): void;

package/dist/load/builds.js

@@ -0,0 +1,124 @@
+// Build manifests, which list a build's files, and the lists of the other files of its installation.
+import { existsSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { readText } from "../markdown.js";
+import { locationRule, unlistedFormat } from "../standard.js";
+import { parseYaml } from "../yaml.js";
+/**
+ * Reads and checks the manifest of every build entry, and reports a manifest or list of other files
+ * that belongs to no build. Returns build ID -> the items of its files list that are maps.
+ */
+export function loadBuildFiles({ config, problem }, entries) {
+    const { specDir } = config;
+    // Build manifests: builds/<ID>.files.yaml holds a build's files list and nothing else.
+    const buildFiles = new Map();
+    for (const [id, e] of entries) {
+        if (e.kind !== "BLD")
+            continue;
+        const expected = `${id}.files.yaml`;
+        if ("files" in e.meta)
+            problem(e.file, `the files list belongs in the manifest ${expected}, not in the entry`);
+        if (e.meta.manifest !== expected) {
+            problem(e.file, `manifest must be ${expected}`);
+            continue;
+        }
+        const path = join(dirname(e.file), expected);
+        if (!existsSync(path)) {
+            problem(e.file, `manifest ${expected} does not exist`);
+            continue;
+        }
+        const manifest = parseYaml(readText(path), path, problem);
+        for (const key of Object.keys(manifest))
+            if (key !== "files")
+                problem(path, `a manifest has only the key files, not ${key}`);
+        if (!Array.isArray(manifest.files)) {
+            problem(path, "files must be a list");
+            continue;
+        }
+        // Later checks read f.path, so an item that is not a map is reported and left out.
+        if (manifest.files.some((f) => !f || typeof f !== "object"))
+            problem(path, "every item of files is a map of path, format, size and xxh3");
+        const files = manifest.files.filter((f) => f && typeof f === "object");
+        buildFiles.set(id, files);
+        for (const f of files) {
+            if (!f.path)
+                problem(path, "every file has a path");
+            if (f.format === undefined || f.format === null || f.format === "")
+                problem(path, `${f.path}: every file has a format`);
+            else if (!locationRule(f.format))
+                problem(path, `${f.path}: ${unlistedFormat(f.format)}`);
+            const unpackedFormat = f.unpacked?.format;
+            if (unpackedFormat !== undefined &&
+                unpackedFormat !== null &&
+                unpackedFormat !== "" &&
+                !locationRule(unpackedFormat))
+                problem(path, `${f.path}: unpacked ${unlistedFormat(unpackedFormat)}`);
+            if (!/^[0-9a-f]{32}$/.test(String(f.xxh3)))
+                problem(path, `${f.path}: xxh3 must be 32 lower-case hex digits`);
+            if (typeof f.size !== "number")
+                problem(path, `${f.path}: size must be a number`);
+            if (f.packer && !(f.unpacked && f.unpacked.size && f.unpacked.xxh3 && f.unpacked.format && f.unpacked.tool))
+                problem(path, `${f.path}: a packed file gives the size, xxh3, format and tool of its unpacked form`);
+            if (String(f.path).includes("\\"))
+                problem(path, `${f.path}: paths use forward slashes`);
+        }
+    }
+    if (existsSync(join(specDir, "builds")))
+        for (const name of readdirSync(join(specDir, "builds"))) {
+            const m = /^(.+)\.(?:other-)?files\.yaml$/.exec(name);
+            if (m && entries.get(m[1])?.kind !== "BLD")
+                problem(join(specDir, "builds", name), `belongs to no build entry (${m[1]})`);
+        }
+    return buildFiles;
+}
+/** Checks each build's list of other files against its manifest and its Other files section. */
+export function checkOtherFiles({ problem }, entries, buildFiles) {
+    // Other files: every path of the installation's listing that the manifest leaves out, each with
+    // its reason, in the build entry's Other files section or, for a long list, in
+    // builds/<ID>.other-files.yaml, which that section names.
+    for (const [id, e] of entries) {
+        if (e.kind !== "BLD")
+            continue;
+        const name = `${id}.other-files.yaml`;
+        const path = join(dirname(e.file), name);
+        const named = (e.sections.find((s) => s.title === "Other files")?.text ?? "").includes(name);
+        if (!existsSync(path)) {
+            if (named)
+                problem(e.file, `Other files names ${name}, which does not exist`);
+            continue;
+        }
+        if (!named)
+            problem(e.file, `the Other files section names ${name}, which lists the paths the manifest leaves out`);
+        const list = parseYaml(readText(path), path, problem);
+        for (const key of Object.keys(list))
+            if (key !== "other_files")
+                problem(path, `a list of other files has only the key other_files, not ${key}`);
+        if (!Array.isArray(list.other_files)) {
+            problem(path, "other_files must be a list");
+            continue;
+        }
+        // The front matter reader turns a bare name such as 1990 into a number, so paths compare as text.
+        const inManifest = new Set((buildFiles.get(id) ?? []).map((f) => String(f.path)));
+        const seen = new Set();
+        for (const item of list.other_files) {
+            if (!item || typeof item !== "object" || Object.keys(item).sort().join(",") !== "path,reason") {
+                problem(path, "every item of other_files is a map of path and reason");
+                continue;
+            }
+            if (item.path === null || item.path === undefined || item.path === "") {
+                problem(path, "every other file has a path");
+                continue;
+            }
+            const other = String(item.path);
+            if (item.reason === null || String(item.reason).trim() === "")
+                problem(path, `${other}: every other file gives the reason the manifest leaves it out`);
+            if (other.includes("\\"))
+                problem(path, `${other}: paths use forward slashes`);
+            if (inManifest.has(other))
+                problem(path, `${other} is in the manifest, so it is not one of the other files`);
+            if (seen.has(other))
+                problem(path, `${other} is listed twice`);
+            seen.add(other);
+        }
+    }
+}

package/dist/load/code-ranges.d.ts

@@ -0,0 +1,4 @@
+import type { LoadContext } from "../context.ts";
+import type { CodeRange, Entry, Meta } from "../types.ts";
+/** Reads and checks the Code ranges section of every build entry. Returns build ID -> its ranges. */
+export declare function loadCodeRanges({ problem }: LoadContext, entries: Map<string, Entry>, buildFiles: Map<string, Meta[]>): Map<string, CodeRange[]>;

package/dist/load/code-ranges.js

@@ -0,0 +1,79 @@
+// Code ranges: the half-open ranges of each file that hold code located by offset, each with the
+// finding that shows it. A table File | Range | Overlay | Finding, or None.
+import { asList, idsIn, kindOf } from "../ids.js";
+import { checkOffset, parseOffset } from "../locations.js";
+import { tables } from "../markdown.js";
+import { locationRule } from "../standard.js";
+const CODE_RANGES = ["File", "Range", "Overlay", "Finding"];
+const unticked = (cell) => cell.replace(/^`(.*)`$/, "$1").trim();
+/** Reads and checks the Code ranges section of every build entry. Returns build ID -> its ranges. */
+export function loadCodeRanges({ problem }, entries, buildFiles) {
+    const codeRanges = new Map(); // build ID -> [{ file, start, end }]
+    for (const [id, e] of entries) {
+        if (e.kind !== "BLD")
+            continue;
+        const section = e.sections.find((s) => s.title === "Code ranges");
+        // A missing section is reported with the other sections.
+        if (!section)
+            continue;
+        const ranges = [];
+        if (/^\s*None\.\s*$/.test(section.text)) {
+            codeRanges.set(id, ranges);
+            continue;
+        }
+        const found = tables(section.text);
+        // A malformed section is reported once here; offsets into the build are then not measured
+        // against it, as with a missing section, rather than each failing again.
+        if (found.length !== 1 || found[0].header.join("|") !== CODE_RANGES.join("|") || found[0].rows.length === 0) {
+            problem(e.file, `the Code ranges section is one table with the columns ${CODE_RANGES.join(" | ")}, or None.`);
+            continue;
+        }
+        codeRanges.set(id, ranges);
+        const files = buildFiles.get(id) ?? [];
+        for (const row of found[0].rows) {
+            if (row.length !== CODE_RANGES.length) {
+                problem(e.file, `Code ranges row ${row.join(" | ")}: a row has ${CODE_RANGES.length} cells, not ${row.length}`);
+                continue;
+            }
+            const [path, range, overlay, finding] = row.map(unticked);
+            const at = `Code ranges row ${path} ${range}`;
+            const bf = files.find((f) => f.path === path);
+            if (!bf) {
+                problem(e.file, `${at}: ${path} is not in the manifest`);
+                continue;
+            }
+            // Only overlay code is located by offset, so a row is for a file whose unpacked format takes
+            // both addresses and offsets (MZ). An unlisted format is already reported against its manifest.
+            const format = bf.unpacked?.format ?? bf.format;
+            const rule = locationRule(format);
+            if (rule && !(rule.offset && rule.address))
+                problem(e.file, `${at}: ${path} is a ${format} file, which holds no code located by offset`);
+            // The notation is parseOffset's; a row additionally needs both ends of the range.
+            if (!range.includes("..") || !parseOffset(range)) {
+                problem(e.file, `${at}: the range is one half-open offset range, 0x followed by upper-case hex digits on each side of ..`);
+                continue;
+            }
+            if (!/^(?:-|\d+|0x[0-9A-F]+)$/.test(overlay))
+                problem(e.file, `${at}: the overlay is its number, or - where there is none`);
+            // A finding that does not exist is reported with the other unresolved IDs of the body.
+            const ids = idsIn(finding);
+            const cited = entries.get(ids[0]);
+            if (ids.length !== 1 || kindOf(ids[0]) !== "FND" || finding !== ids[0])
+                problem(e.file, `${at}: the finding column holds the ID of one finding`);
+            else if (cited && !asList(cited.meta.builds).includes(id))
+                problem(e.file, `${at}: ${ids[0]} does not list ${id}`);
+            else if (cited?.meta.status === "superseded")
+                problem(e.file, `${at}: cites ${ids[0]}, which is superseded`, "STATUS-17");
+            // The finding shows code in this file of this build, so it has a location there that is not
+            // file data. One with no locations there, or only file data there, shows no code in the row.
+            else if (cited &&
+                !asList(cited.meta.locations).some((loc) => loc?.build === id && loc?.file === path && loc?.kind !== "file-data")) {
+                problem(e.file, `${at}: ${ids[0]} has no code location in ${path} of ${id}, so it cannot establish a code range there`);
+            }
+            const parsed = checkOffset(problem, e.file, range, bf);
+            if (parsed)
+                ranges.push({ file: path, start: parsed[0], end: parsed[1] });
+        }
+    }
+    return codeRanges;
+}

package/dist/load/entries.d.ts

@@ -0,0 +1,7 @@
+import type { LoadContext } from "../context.ts";
+import type { Entry } from "../types.ts";
+/**
+ * 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 declare function loadEntries({ config, problem }: LoadContext): Map<string, Entry>;