@scientific-method/standard-checker 0.1.0 → 0.3.0

package/dist/context.d.ts

@@ -0,0 +1,34 @@
+import type { Config } from "./options.ts";
+import type { Problem } from "./problems.ts";
+import type { CodeFile, CodeRange, Entry, Meta } from "./types.ts";
+/** The spec as the load phase read it. Later phases add to entries (Entry.code, Entry.valueTables). */
+export interface Spec {
+    /** The areas of spec/README.md, in the order it lists them. */
+    areas: string[];
+    /** Every entry by ID, in the order the kind directories were read. */
+    entries: Map<string, Entry>;
+    /** spec/glossary/. */
+    glossaryDir: string;
+    /** Glossary term -> the text after its heading, including the --glossary drafts. */
+    glossary: Map<string, string>;
+    /** Glossary term -> its file in spec/glossary/ (drafts have none). */
+    glossaryFiles: Map<string, string>;
+    /** Build ID -> the files of its manifest that are maps. */
+    buildFiles: Map<string, Meta[]>;
+    /** Build ID -> its Code ranges, for a build whose section was read. */
+    codeRanges: Map<string, CodeRange[]>;
+}
+/** What the load phase needs: the options and the problem collector. */
+export interface LoadContext {
+    /** The run's options. */
+    config: Config;
+    /** Records a problem. */
+    problem: Problem;
+}
+/** What every phase after the load needs. */
+export interface Context extends LoadContext {
+    /** The spec as loaded. */
+    spec: Spec;
+    /** The files of the --code and --references directories, read on first use. */
+    codeFiles: () => CodeFile[];
+}

package/dist/context.js

@@ -0,0 +1,2 @@
+// What the phases of a run share: the options, the problem collector and the spec as loaded.
+export {};

package/dist/evidence.d.ts

@@ -0,0 +1,37 @@
+import type { Context } from "./context.ts";
+import type { Problem } from "./problems.ts";
+import type { Entry, Facts, Yaml } from "./types.ts";
+/** The rank of a claim status on the scale, or -1 for one off it. */
+export declare const statusIndex: (s: string) => number;
+/**
+ * Whether the entry id is superseded: its status says so, or it is a build or source that names a
+ * successor. Undefined or false when it is not, or does not exist.
+ */
+export declare const isSuperseded: (entries: Map<string, Entry>, id: string) => boolean | undefined;
+/** Reports each of ids that is not an entry, as cited by what in file. */
+export declare function checkResolves(ctx: Context, file: string, ids: string[], what: string): void;
+/**
+ * What the evidence of a claim covers for the first build.
+ * A whole entry counts as read completely when complete_reading holds any valid finding; a row of
+ * its tables only when every static finding the row cites is part of that reading.
+ */
+export declare const evidenceFacts: (entries: Map<string, Entry>, e: Entry) => Facts;
+/**
+ * The static findings of a complete reading: those in complete_reading that the entry cites in
+ * evidence and that list its first build. Anything else there is reported where the field is checked.
+ */
+export declare function completeReading(entries: Map<string, Entry>, e: Entry): string[];
+/**
+ * True when all of an entry's evidence from the original running is emulated calls of single
+ * functions, which model neither interrupts nor timing.
+ */
+export declare function onlyEmulatedRuns(entries: Map<string, Entry>, e: Entry): boolean;
+/** True for a rule whose procedure says another rule may run in the middle of it (`# may run:`). */
+export declare const mayBeInterrupted: (e: Entry) => boolean;
+/** Reports a status that the facts of its evidence do not reach. label names what has the status. */
+export declare function checkStatusCitations(problem: Problem, file: string, status: Yaml, facts: Facts, conflicting: string[], label?: string): void;
+/**
+ * What the evidence ids cover for the build first. complete is the entry's complete reading, and
+ * the cited evidence counts as part of it when it holds static findings and every one of them is in it.
+ */
+export declare function rowFacts(entries: Map<string, Entry>, ids: string[], first: Yaml, complete?: string[]): Facts;

package/dist/evidence.js

@@ -0,0 +1,91 @@
+// What entries say about each other: supersession, citations that resolve, and what the evidence a
+// claim cites covers.
+import { asList } from "./ids.js";
+import { SCALE } from "./standard.js";
+/** The rank of a claim status on the scale, or -1 for one off it. */
+export const statusIndex = (s) => SCALE.indexOf(s);
+/**
+ * Whether the entry id is superseded: its status says so, or it is a build or source that names a
+ * successor. Undefined or false when it is not, or does not exist.
+ */
+export const isSuperseded = (entries, id) => entries.get(id)?.meta.status === "superseded" ||
+    (entries.get(id) &&
+        asList(entries.get(id).meta.superseded_by).length > 0 &&
+        ["BLD", "SRC"].includes(entries.get(id).kind));
+/** Reports each of ids that is not an entry, as cited by what in file. */
+export function checkResolves(ctx, file, ids, what) {
+    for (const id of ids)
+        if (!ctx.spec.entries.has(id))
+            ctx.problem(file, `${what} cites ${id}, which does not exist`);
+}
+/**
+ * What the evidence of a claim covers for the first build.
+ * A whole entry counts as read completely when complete_reading holds any valid finding; a row of
+ * its tables only when every static finding the row cites is part of that reading.
+ */
+export const evidenceFacts = (entries, e) => {
+    const reading = completeReading(entries, e);
+    return {
+        ...rowFacts(entries, asList(e.meta.evidence), asList(e.meta.builds)[0], reading),
+        completeReading: reading.length > 0,
+    };
+};
+/**
+ * The static findings of a complete reading: those in complete_reading that the entry cites in
+ * evidence and that list its first build. Anything else there is reported where the field is checked.
+ */
+export function completeReading(entries, e) {
+    const first = asList(e.meta.builds)[0];
+    const evidence = asList(e.meta.evidence);
+    return asList(e.meta.complete_reading).filter((x) => {
+        const f = entries.get(x);
+        return (f?.kind === "FND" && f.meta.method === "static" && evidence.includes(x) && asList(f.meta.builds).includes(first));
+    });
+}
+/**
+ * True when all of an entry's evidence from the original running is emulated calls of single
+ * functions, which model neither interrupts nor timing.
+ */
+export function onlyEmulatedRuns(entries, e) {
+    const runs = asList(e.meta.evidence)
+        .map((x) => entries.get(x))
+        .filter((x) => x !== undefined && (x.kind === "EXP" || (x.kind === "FND" && x.meta.method === "dynamic")));
+    return runs.length > 0 && runs.every((x) => x.kind === "EXP" && x.meta.starting_state === "emulated-call");
+}
+/** True for a rule whose procedure says another rule may run in the middle of it (`# may run:`). */
+export const mayBeInterrupted = (e) => e.kind === "RULE" && /# may run: RULE-/.test(e.code ?? "");
+/** Reports a status that the facts of its evidence do not reach. label names what has the status. */
+export function checkStatusCitations(problem, file, status, facts, conflicting, label = "status") {
+    if (status === "sourced" && facts.sources === 0)
+        problem(file, `${label} sourced needs at least one source`, "STATUS-1");
+    if (status === "supported" && facts.staticF + facts.dynamic === 0)
+        problem(file, `${label} supported needs at least one finding or experiment that lists the first build`, "STATUS-1");
+    if (status === "established" && (facts.staticF === 0 || (facts.dynamic === 0 && !facts.completeReading)))
+        problem(file, `${label} established needs a static finding and either a dynamic finding or experiment that list the first build, or a complete reading in complete_reading`, "STATUS-1");
+    if (status === "disputed" && conflicting.length === 0)
+        problem(file, `${label} disputed needs at least one finding or experiment in conflicting`, "STATUS-1");
+}
+/**
+ * What the evidence ids cover for the build first. complete is the entry's complete reading, and
+ * the cited evidence counts as part of it when it holds static findings and every one of them is in it.
+ */
+export function rowFacts(entries, ids, first, complete = []) {
+    let sources = 0, staticF = 0, dynamic = 0, outside = 0;
+    for (const id of ids) {
+        const ev = entries.get(id);
+        if (!ev)
+            continue;
+        if (ev.kind === "SRC")
+            sources++;
+        if (!["FND", "EXP"].includes(ev.kind) || !asList(ev.meta.builds).includes(first))
+            continue;
+        if (ev.kind === "EXP" || ev.meta.method === "dynamic")
+            dynamic++;
+        else if (ev.meta.method === "static") {
+            staticF++;
+            if (!complete.includes(id))
+                outside++;
+        }
+    }
+    return { sources, staticF, dynamic, completeReading: complete.length > 0 && staticF > 0 && outside === 0 };
+}

package/dist/files.d.ts

@@ -0,0 +1,11 @@
+/** A path with backslashes turned into forward slashes. */
+export declare const toSlash: (p: string) => string;
+/**
+ * Calls fn with every file under dir, depth first in directory order, skipping build output,
+ * dependencies and .git. A directory that does not exist has no files.
+ */
+export declare function walk(dir: string, fn: (path: string) => void): void;
+/** Markdown files under dir, by path relative to dir without .md. */
+export declare function markdownTree(dir: string): Map<string, string>;
+/** The paths of the files and directories in dir, apart from .gitkeep. */
+export declare const termFiles: (dir: string) => string[];

package/dist/files.js

@@ -0,0 +1,35 @@
+// Walking the repository's directories.
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+/** A path with backslashes turned into forward slashes. */
+export const toSlash = (p) => p.replaceAll("\\", "/");
+/**
+ * Calls fn with every file under dir, depth first in directory order, skipping build output,
+ * dependencies and .git. A directory that does not exist has no files.
+ */
+export function walk(dir, fn) {
+    if (!existsSync(dir))
+        return;
+    for (const name of readdirSync(dir)) {
+        if (["bin", "obj", "node_modules", ".git", "artifacts"].includes(name))
+            continue;
+        const p = join(dir, name);
+        if (statSync(p).isDirectory())
+            walk(p, fn);
+        else
+            fn(p);
+    }
+}
+/** Markdown files under dir, by path relative to dir without .md. */
+export function markdownTree(dir) {
+    const found = new Map();
+    walk(dir, (f) => {
+        if (f.endsWith(".md"))
+            found.set(toSlash(relative(dir, f)).replace(/\.md$/, ""), f);
+    });
+    return found;
+}
+/** The paths of the files and directories in dir, apart from .gitkeep. */
+export const termFiles = (dir) => readdirSync(dir)
+    .filter((name) => name !== ".gitkeep")
+    .map((name) => join(dir, name));

package/dist/generate/indexes.d.ts

@@ -0,0 +1,3 @@
+import type { Context } from "../context.ts";
+/** Renders the four indexes, split where the line limit requires. Returns absolute path -> text. */
+export declare function generateIndexes(ctx: Context): Map<string, string>;

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;