@scientific-method/standard-checker 0.1.0 → 0.3.0

package/dist/checks/rules.js

@@ -0,0 +1,263 @@
+// Rules: procedures against the glossary and the formats. Reads each rule's Procedure into
+// Entry.code, then checks the names every live procedure declares, calls, reads and relies on.
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { mayBeInterrupted, onlyEmulatedRuns } from "../evidence.js";
+import { asList, idsIn, kindOf } from "../ids.js";
+import { readCsv } from "../markdown.js";
+import { KINDS, LIST_LIMIT } from "../standard.js";
+/**
+ * A procedure with each string literal emptied and its comments dropped. Strings go first, so a `#`
+ * inside one does not start a comment, and a string ends on the line it starts on.
+ */
+export const withoutCommentsAndStrings = (code) => code.replace(/"[^"\n]*"/g, '""').replace(/#.*$/gm, "");
+/** The names a rule's Parameters section declares: each lower-case name that opens a code span, as `n` or `n: type`. */
+export const parameterNames = (params) => [...params.matchAll(/`([a-z_][a-z0-9_]*)(?=`|\s*:)/g)].map((m) => m[1]);
+const BUILTINS = new Set([
+    "min",
+    "max",
+    "abs",
+    "count",
+    "append",
+    "insert",
+    "remove_at",
+    "copy",
+    "stable_sort",
+    "sprintf",
+    "floor",
+    "ceil",
+    "round_even",
+    "draw",
+    "resource",
+    "read_file",
+    "write_file",
+    "free",
+    "fmod",
+    "UINT8",
+    "INT8",
+    "UINT16",
+    "INT16",
+    "UINT32",
+    "INT32",
+    "UINT64",
+    "INT64",
+    "FLOAT32",
+    "FLOAT64",
+    "FLOAT80",
+    "REAL48",
+]);
+const KEYWORDS = new Set([
+    "for",
+    "each",
+    "in",
+    "if",
+    "else",
+    "while",
+    "break",
+    "continue",
+    "return",
+    "let",
+    "and",
+    "or",
+    "not",
+    "true",
+    "false",
+    "call",
+    "define",
+    "emit",
+    "drain",
+    "show",
+    "new",
+    "table",
+    "clock",
+    "from",
+    "Hz",
+]);
+/** Checks every rule's procedure. Sets Entry.code on every rule entry, superseded ones included. */
+export function checkRules(ctx, { enumNames }) {
+    const { problem } = ctx;
+    const { entries, glossary, glossaryDir } = ctx.spec;
+    const defined = new Map(); // function/table/clock name -> rule IDs
+    // A superseded rule keeps its procedure for history, but its declarations own no active name.
+    const historical = new Map(); // name declared by superseded rules -> rule IDs
+    for (const [id, e] of entries) {
+        if (e.kind !== "RULE")
+            continue;
+        const proc = e.sections.find((s) => s.title === "Procedure")?.text ?? "";
+        e.code = [...proc.matchAll(/```text\n([\s\S]*?)```/g)].map((m) => m[1]).join("\n");
+        const owners = e.meta.status === "superseded" ? historical : defined;
+        for (const m of e.code.matchAll(/^\s*(?:define\s+([a-z_][a-z0-9_]*)\s*\(|table\s+([a-z_][a-z0-9_]*)\s*:|clock\s+([a-z_][a-z0-9_]*)\s*:)/gm)) {
+            const name = m[1] ?? m[2] ?? m[3];
+            if (!owners.has(name))
+                owners.set(name, []);
+            owners.get(name).push(id);
+        }
+    }
+    // A live procedure cannot rely on a name only a superseded rule declares.
+    const onlyHistorical = (name) => !defined.has(name) && historical.has(name);
+    for (const [name, ids] of defined) {
+        const splitGroup = asList(entries.get(ids[0]).meta.split_with).concat(ids[0]);
+        if (ids.length > 1 && !ids.every((x) => splitGroup.includes(x)))
+            problem(null, `${name} is defined by more than one rule: ${ids.join(", ")}`);
+        if (!glossary.has(name))
+            problem(glossaryDir, `${name}, defined by ${ids[0]}, has no glossary entry`);
+    }
+    for (const [id, e] of entries) {
+        if (e.kind !== "RULE" || e.meta.status === "superseded")
+            continue;
+        const { file, meta } = e;
+        // Types in a define's signature (`define roll(n: UINT16) -> char[]:`) are not names the
+        // procedure reads, so they are dropped before the name checks.
+        const TYPE = String.raw `(?:[A-Za-z][A-Za-z0-9]*|FMT-[A-Z0-9]+-\d+)(?:\[[^\]]*\])?`;
+        const code = withoutCommentsAndStrings(e.code).replace(new RegExp(String.raw `(\bdefine\s+[a-z_][a-z0-9_]*\s*\()([^)]*)\)(\s*->\s*${TYPE})?`, "g"), (_, head, params) => `${head}${params
+            .split(",")
+            .map((p) => p.split(":")[0].trim())
+            .join(", ")})`);
+        const related = asList(meta.related);
+        const openQuestions = e.sections.find((s) => s.title === "Open questions")?.text ?? "";
+        // Names are letters, digits and underscores, so best_score does not count as listing score.
+        const listsOpen = (name) => new RegExp(`(?<![A-Za-z0-9_])${name}(?![A-Za-z0-9_])`).test(openQuestions);
+        if (meta.status !== "unknown" && e.code.trim() === "")
+            problem(file, "Procedure has no ```text block");
+        const usedTerms = new Set();
+        const useTerm = (name) => {
+            if (glossary.has(name))
+                usedTerms.add(name);
+            return glossary.has(name);
+        };
+        // Lists written out hold at most LIST_LIMIT values; a table of more takes them from a value file.
+        for (const m of code.matchAll(/=\s*\[([^\]]*)\]/g)) {
+            const count = m[1].split(",").filter((x) => x.trim() !== "").length;
+            if (count > LIST_LIMIT)
+                problem(file, `writes out a list of ${count} values; a list of more than ${LIST_LIMIT} is a table with a value file`);
+        }
+        for (const m of e.code.matchAll(/^\s*table\s+([a-z_][a-z0-9_]*)\s*:\s*[A-Za-z0-9]+\[([^\]]*)\]\s*from\s*"([^"]*)"/gm)) {
+            const [, name, count, csvName] = m;
+            const expected = `${id}.${name}.csv`;
+            if (csvName !== expected) {
+                problem(file, `table ${name} takes its values from ${expected}, not ${csvName}`);
+                continue;
+            }
+            const path = join(dirname(file), csvName);
+            if (!existsSync(path)) {
+                problem(file, `value file ${csvName} does not exist`);
+                continue;
+            }
+            const csv = readCsv(path, problem);
+            if (!csv)
+                continue;
+            if (csv.header.join("|") !== "value")
+                problem(path, "a table's value file has the single column value");
+            if (/^\d+$/.test(count.trim()) && csv.rows.length !== Number(count))
+                problem(path, `has ${csv.rows.length} values, but table ${name} has ${count}`);
+            for (const [v] of csv.rows)
+                if (!/^-?(?:0x[0-9A-Fa-f]+|\d+(?:\.\d+)?)$/.test(v.trim())) {
+                    problem(path, `${v} is not a number`);
+                    break;
+                }
+        }
+        for (const m of code.matchAll(/\bcall\s+(RULE-[A-Z0-9]+-\d+)/g))
+            if (!related.includes(m[1]))
+                problem(file, `calls ${m[1]}; add it to related`, "ENTRY-TYPES-6");
+        for (const m of code.matchAll(/\bshow\s+(SCR-[A-Z0-9]+-\d+)/g))
+            if (!related.includes(m[1]))
+                problem(file, `shows ${m[1]}; add it to related`, "ENTRY-TYPES-6");
+        for (const m of code.matchAll(/\b(FMT-[A-Z0-9]+-\d+)/g))
+            if (!related.includes(m[1]))
+                problem(file, `uses ${m[1]}; add it to related`, "ENTRY-TYPES-6");
+        for (const m of e.code.matchAll(/# may run: (RULE-[A-Z0-9]+-\d+)/g))
+            if (!related.includes(m[1]))
+                problem(file, `may be interrupted by ${m[1]}; add it to related`, "ENTRY-TYPES-6");
+        if (meta.status === "established" && mayBeInterrupted(e) && onlyEmulatedRuns(entries, e))
+            problem(file, "another rule may interrupt this procedure (# may run:), so emulated calls alone cannot establish it", "STATUS-15");
+        if (asList(meta.complete_reading).length > 0 && /# may run: RULE-/.test(e.code))
+            problem(file, "another rule may interrupt this procedure (# may run:), so a complete reading cannot establish it; leave complete_reading empty", "STATUS-4");
+        for (const x of idsIn(code))
+            if (!entries.has(x))
+                problem(file, `procedure names ${x}, which does not exist`);
+        for (const m of code.matchAll(/\bemit\s+([A-Za-z_][A-Za-z0-9_]*)/g))
+            if (!useTerm(m[1]))
+                problem(file, `emits ${m[1]}, which has no glossary entry`);
+        for (const m of code.matchAll(/\bdrain\s+([A-Za-z_][A-Za-z0-9_]*)/g))
+            if (!useTerm(m[1]))
+                problem(file, `drains ${m[1]}, which has no glossary entry`);
+        for (const m of code.matchAll(/\b((?:fn|g|scr)_[A-Za-z0-9_]+)\b/g)) {
+            if (!useTerm(m[1]))
+                problem(file, `uses the neutral name ${m[1]}, which has no glossary entry`);
+            if (!listsOpen(m[1]))
+                problem(file, `uses the neutral name ${m[1]}; list it in Open questions`);
+        }
+        const noNeutral = code.replace(/\b(?:fn|g|scr)_[A-Za-z0-9_]+\b/g, "");
+        if (/\b0x[0-9A-Fa-f]{6,}\b/.test(noNeutral) && /\b0x00[4-9A-F][0-9A-F]{5}\b/.test(noNeutral))
+            problem(file, "the procedure contains what looks like an address outside a neutral name");
+        // Functions called without `call`
+        const locals = new Set();
+        for (const m of code.matchAll(/\blet\s+([a-z_][a-z0-9_]*)/g))
+            locals.add(m[1]);
+        for (const m of code.matchAll(/\bfor\s+(?:each\s+)?([a-z_][a-z0-9_]*)\s+in\b/g))
+            locals.add(m[1]);
+        for (const m of code.matchAll(/\bdefine\s+[a-z_][a-z0-9_]*\s*\(([^)]*)\)/g))
+            for (const p of m[1].split(","))
+                locals.add(p.split(":")[0].trim());
+        const params = e.sections.find((s) => s.title === "Parameters")?.text ?? "";
+        for (const name of parameterNames(params))
+            locals.add(name);
+        for (const m of code.matchAll(/(?<![.\w])([a-z_][a-z0-9_]*)\s*\(/g)) {
+            const name = m[1];
+            if (BUILTINS.has(name) || KEYWORDS.has(name) || locals.has(name))
+                continue;
+            if (onlyHistorical(name)) {
+                problem(file, `calls ${name}(), which only superseded ${historical.get(name).join(", ")} defines`);
+                continue;
+            }
+            if (!defined.has(name) && !useTerm(name)) {
+                problem(file, `calls ${name}(), which no rule defines and the glossary does not list`);
+                continue;
+            }
+            for (const owner of defined.get(name) ?? [])
+                if (owner !== id && !related.includes(owner))
+                    problem(file, `uses ${name} from ${owner}; add ${owner} to related`, "ENTRY-TYPES-6");
+        }
+        for (const m of code.matchAll(/(?<![.\w])([A-Z][A-Z0-9_]*[A-Z0-9])(?![\w-])/g)) {
+            const name = m[1];
+            if (BUILTINS.has(name) || KINDS[name] || /^(?:FMT|RULE|SCR)$/.test(name))
+                continue;
+            if (!enumNames.has(name)) {
+                problem(file, `upper-case name ${name} is not an enumeration name of any format`);
+                continue;
+            }
+            for (const fmt of enumNames.get(name))
+                if (!related.includes(fmt))
+                    problem(file, `uses ${name} from ${fmt}; add it to related`, "ENTRY-TYPES-6");
+        }
+        // Names read or assigned without let that are neither locals nor glossary terms
+        for (const m of code.matchAll(/(?<![.\w])([a-z_][a-z0-9_]*)(?=\s*(?:\.|\[|=[^=]|$))/gm)) {
+            const name = m[1];
+            if (locals.has(name) || KEYWORDS.has(name) || BUILTINS.has(name) || defined.has(name))
+                continue;
+            if (onlyHistorical(name)) {
+                problem(file, `${name} is declared only by superseded ${historical.get(name).join(", ")}`);
+                continue;
+            }
+            if (!useTerm(name))
+                problem(file, `${name} is neither a local nor a glossary term`);
+        }
+        // A glossary claim a procedure relies on counts toward the rule's status: its evidence is the
+        // rule's evidence, and while it is (unknown) the rule lists it as an open question and is not
+        // established.
+        for (const term of usedTerms) {
+            const text = glossary.get(term);
+            for (const b of text.matchAll(/\[([^\]]*)\]/g))
+                for (const x of idsIn(b[1])) {
+                    if (["FND", "EXP"].includes(kindOf(x)) && !asList(meta.evidence).includes(x))
+                        problem(file, `relies on ${term}, whose glossary entry cites ${x}; add it to evidence`);
+                }
+            if (text.includes("(unknown)")) {
+                if (!listsOpen(term))
+                    problem(file, `relies on ${term}, a glossary claim that is (unknown); list it in Open questions`);
+                if (meta.status === "established")
+                    problem(file, `relies on ${term}, a glossary claim that is (unknown), so it cannot be established`);
+            }
+        }
+    }
+}

package/dist/checks/screens.d.ts

@@ -0,0 +1,4 @@
+import type { Context } from "../context.ts";
+import type { Entry } from "../types.ts";
+/** Checks a screen entry. */
+export declare function checkScreen(ctx: Context, e: Entry): void;

package/dist/checks/screens.js

@@ -0,0 +1,44 @@
+// The checks of a screen entry: its resolution, the tables of its sections, and the evidence and
+// related entries those tables cite.
+import { checkResolves } from "../evidence.js";
+import { asList, idsIn, kindOf } from "../ids.js";
+import { tables } from "../markdown.js";
+import { SCREEN_TABLES } from "../standard.js";
+import { tableIds } from "./formats.js";
+/** Checks a screen entry. */
+export function checkScreen(ctx, e) {
+    const { problem } = ctx;
+    const { file, meta } = e;
+    if (!/^\d+x\d+$/.test(String(meta.resolution)))
+        problem(file, "resolution must be written WIDTHxHEIGHT");
+    for (const s of e.sections) {
+        const want = SCREEN_TABLES[s.title];
+        if (!want)
+            continue;
+        const ts = tables(s.text);
+        if (ts.length === 0 && !/^\s*None( known)?\.\s*$/.test(s.text))
+            problem(file, `${s.title} has neither a table nor None known.`);
+        for (const t of ts)
+            if (t.header.join("|") !== want.join("|"))
+                problem(file, `${s.title} table has the columns ${want.join(" | ")}`);
+    }
+    const cited = tableIds(e, Object.keys(SCREEN_TABLES));
+    const listed = new Set([...asList(meta.evidence), ...asList(meta.conflicting)]);
+    for (const x of cited)
+        if (!listed.has(x) && ["FND", "EXP", "SRC"].includes(kindOf(x)))
+            problem(file, `${x} is cited in a table but not in evidence or conflicting`);
+    for (const s of e.sections)
+        for (const t of tables(s.text)) {
+            for (const col of ["Effect", "Shows"]) {
+                const c = t.header.indexOf(col);
+                if (c < 0)
+                    continue;
+                for (const row of t.rows)
+                    for (const x of idsIn(row[c]))
+                        if (["RULE", "SCR"].includes(kindOf(x)) && !asList(meta.related).includes(x))
+                            problem(file, `${col} cell names ${x}; add it to related`, "ENTRY-TYPES-6");
+            }
+        }
+    for (const x of cited)
+        checkResolves(ctx, file, [x], "a table");
+}

package/dist/checks/validation.d.ts

@@ -0,0 +1,7 @@
+import type { Context } from "../context.ts";
+import type { Parity } from "./parity.ts";
+/**
+ * With --record-validation, writes VALIDATION.md (or prints why it cannot and exits with 2). Then
+ * checks VALIDATION.md against the marked test files of the validated rows.
+ */
+export declare function checkValidation(ctx: Context, { validatedTests }: Parity): void;

package/dist/checks/validation.js

@@ -0,0 +1,116 @@
+// VALIDATION.md records the marked test files of the validated rows as they were when a maintainer ran
+// them against the original's files, which CI never holds. A file is hashed with CRLF read as LF,
+// so a Windows checkout and a Linux one give the same hash.
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { readText, tables } from "../markdown.js";
+const VALIDATION_HEADER = ["Test file", "SHA-256"];
+const testHash = (p) => createHash("sha256")
+    .update(Buffer.from(readFileSync(p).toString("latin1").replaceAll("\r\n", "\n"), "latin1"))
+    .digest("hex");
+/**
+ * With --record-validation, writes VALIDATION.md (or prints why it cannot and exits with 2). Then
+ * checks VALIDATION.md against the marked test files of the validated rows.
+ */
+export function checkValidation(ctx, { validatedTests }) {
+    const { problem } = ctx;
+    const { entries } = ctx.spec;
+    const { repoDir } = ctx.config;
+    const validationPath = join(repoDir, "VALIDATION.md");
+    if (ctx.config.recordValidation !== undefined) {
+        const builds = ctx.config.recordValidation;
+        if (!builds.length) {
+            console.error("--record-validation needs at least one build ID");
+            process.exit(2);
+        }
+        for (const b of builds)
+            if (entries.get(b)?.kind !== "BLD") {
+                console.error(`--record-validation: ${b} is not a build entry`);
+                process.exit(2);
+            }
+        let commit;
+        try {
+            commit = execFileSync("git", ["rev-parse", "HEAD"], { cwd: repoDir, encoding: "utf8" }).trim();
+        }
+        catch {
+            console.error("--record-validation: git rev-parse HEAD failed");
+            process.exit(2);
+        }
+        const files = [...validatedTests.keys()].sort();
+        if (!files.length) {
+            console.error('--record-validation: no validated row lists a test file with a "needs: GAME_DIR" comment, so there is nothing to record');
+            process.exit(2);
+        }
+        writeFileSync(validationPath, [
+            "# Validation record",
+            "",
+            "The test files of the validated parity rows that read the original's files, as they were when every test in them passed against those files.",
+            "",
+            `- Commit: ${commit}`,
+            `- Date: ${new Date().toISOString().slice(0, 10)}`,
+            `- Builds: ${builds.join(", ")}`,
+            "",
+            `| ${VALIDATION_HEADER.join(" | ")} |`,
+            `|${"---|".repeat(VALIDATION_HEADER.length)}`,
+            ...files.map((f) => `| \`${f}\` | \`${testHash(join(repoDir, f))}\` |`),
+            "",
+        ].join("\n"));
+        console.log("wrote VALIDATION.md");
+    }
+    {
+        const recorded = new Map(); // test file -> hash
+        if (existsSync(validationPath)) {
+            const text = readText(validationPath);
+            const item = (key, pattern) => {
+                const m = text.match(new RegExp(`^- ${key}: (.*)$`, "m"));
+                if (!m || !pattern.test(m[1].trim())) {
+                    problem(validationPath, `needs a "- ${key}:" item in the form the standard gives`);
+                    return null;
+                }
+                return m[1].trim();
+            };
+            item("Commit", /^[0-9a-f]{40}$/);
+            item("Date", /^\d{4}-\d{2}-\d{2}$/);
+            const builds = item("Builds", /^\S.*$/);
+            if (builds !== null)
+                for (const b of builds.split(",").map((x) => x.trim()))
+                    if (entries.get(b)?.kind !== "BLD")
+                        problem(validationPath, `Builds names ${b}, which is not a build entry`);
+            const ts = tables(text);
+            if (ts.length !== 1 || ts[0].header.join("|") !== VALIDATION_HEADER.join("|"))
+                problem(validationPath, `holds one table with the columns ${VALIDATION_HEADER.join(" | ")}`);
+            else {
+                let previous = "";
+                for (const row of ts[0].rows) {
+                    const [path, hash] = row.map((c) => c.replaceAll("`", "").trim());
+                    if (row.length !== VALIDATION_HEADER.length || !/^[0-9a-f]{64}$/.test(hash ?? "")) {
+                        problem(validationPath, `the row ${row.join(" | ")} needs a test file and its SHA-256 in lowercase hex`);
+                        continue;
+                    }
+                    if (recorded.has(path))
+                        problem(validationPath, `${path} is listed twice`);
+                    if (path < previous)
+                        problem(validationPath, `${path} is out of order; the files are sorted by path`);
+                    previous = path;
+                    recorded.set(path, hash);
+                    if (!validatedTests.has(path))
+                        problem(validationPath, `${path} is not a test file with a "needs: GAME_DIR" comment in a validated row's Tests; run the check with --record-validation again`);
+                }
+            }
+        }
+        for (const [tf, rows] of validatedTests) {
+            const p = join(repoDir, tf);
+            if (!existsSync(p))
+                continue;
+            const hash = recorded.get(tf);
+            for (const { specId, file } of rows) {
+                if (hash === undefined)
+                    problem(file, `${specId}: ${tf} is not in VALIDATION.md, so the row cannot be validated until its tests pass against the original's files and are recorded`);
+                else if (hash !== testHash(p))
+                    problem(file, `${specId}: ${tf} has changed since VALIDATION.md recorded it; run its tests against the original's files and record them again`);
+            }
+        }
+    }
+}

package/dist/code-comments.d.ts

@@ -0,0 +1,3 @@
+import type { CodeLine } from "./types.ts";
+/** Reads the comments of a C-family source file line by line, as the comment above describes. */
+export declare function codeComments(source: string, javascript: boolean): CodeLine[];

package/dist/code-comments.js

@@ -0,0 +1,150 @@
+// Reading the comments of C#, TypeScript and JavaScript source.
+// The comments of a C-family source file (C#, TypeScript, JavaScript), line by line: for each
+// line, whether it holds code and the comment text on it with the column where each piece starts.
+// String and character literals are skipped (regular, verbatim, interpolated and raw in C#;
+// template literals in JavaScript), so a `//` inside one starts no comment. An interpolation hole is
+// read as part of its string, which is enough to find comments. A JavaScript regular expression
+// literal is skipped too, so a quote or a `/*` inside one starts nothing; a `/` is read as one
+// where a value can begin. The lines of a `/* … */` after its first are marked continued.
+/** Reads the comments of a C-family source file line by line, as the comment above describes. */
+export function codeComments(source, javascript) {
+    const text = source.replace(/\r\n?/g, "\n");
+    const lines = [{ code: false, comments: [] }];
+    const line = () => lines[lines.length - 1];
+    let i = 0, column = 0;
+    const advance = (to) => {
+        for (; i < to; i++) {
+            if (text[i] === "\n") {
+                lines.push({ code: false, comments: [] });
+                column = 0;
+            }
+            else
+                column++;
+        }
+    };
+    const addComment = (from, to, col, continued = false) => line().comments.push({ column: col, text: text.slice(from, to), continued });
+    let lastCode = -1; // the index of the last character read as code
+    // A JavaScript `/` starts a regular expression unless it follows a value, where it divides.
+    const regexMayStart = () => {
+        const before = text.slice(Math.max(0, lastCode - 11), lastCode + 1);
+        return (lastCode < 0 ||
+            !/[\w$)\]}]$/.test(before) ||
+            /(?<![\w$])(?:return|typeof|case|do|else|in|of|new|delete|void|throw|instanceof|yield|await)$/.test(before));
+    };
+    // Past the closing `/` of the regular expression literal at i, if it closes on its line.
+    const regexEnd = () => {
+        let inClass = false;
+        for (let j = i + 1; j < text.length && text[j] !== "\n"; j++) {
+            if (text[j] === "\\") {
+                if (text[j + 1] === "\n")
+                    return -1;
+                j++;
+            }
+            else if (text[j] === "[")
+                inClass = true;
+            else if (text[j] === "]")
+                inClass = false;
+            else if (text[j] === "/" && !inClass)
+                return j + 1;
+        }
+        return -1;
+    };
+    // i is past the opening quote(s); stops past the closing one(s). A regular string ends at the
+    // line when it is not closed.
+    const skipString = (end, escapes, multiline) => {
+        while (i < text.length) {
+            if (escapes && text[i] === "\\") {
+                advance(i + 2);
+                continue;
+            }
+            if (text.startsWith(end, i)) {
+                if (!escapes && end === '"' && text[i + 1] === '"') {
+                    advance(i + 2);
+                    continue;
+                } // "" in a verbatim string
+                advance(i + end.length);
+                return;
+            }
+            if (text[i] === "\n" && !multiline) {
+                advance(i + 1);
+                return;
+            }
+            advance(i + 1);
+        }
+    };
+    while (i < text.length) {
+        const c = text[i];
+        if (c === "\n" || c === " " || c === "\t") {
+            advance(i + 1);
+            continue;
+        }
+        if (text.startsWith("//", i)) {
+            const nl = text.indexOf("\n", i);
+            const end = nl < 0 ? text.length : nl;
+            addComment(i, end, column);
+            advance(end);
+            continue;
+        }
+        if (text.startsWith("/*", i)) {
+            const close = text.indexOf("*/", i + 2);
+            const end = close < 0 ? text.length : close + 2;
+            let from = i, col = column, continued = false;
+            while (i < end) {
+                const nl = text.indexOf("\n", i);
+                if (nl < 0 || nl >= end) {
+                    addComment(from, end, col, continued);
+                    advance(end);
+                    break;
+                }
+                addComment(from, nl, col, continued);
+                advance(nl + 1);
+                continued = true;
+                while (i < end && (text[i] === " " || text[i] === "\t"))
+                    advance(i + 1);
+                from = i;
+                col = column;
+            }
+            continue;
+        }
+        line().code = true;
+        if (javascript) {
+            const regex = c === "/" && regexMayStart() ? regexEnd() : -1;
+            if (regex >= 0)
+                advance(regex);
+            else if (c === '"' || c === "'") {
+                advance(i + 1);
+                skipString(c, true, false);
+            }
+            else if (c === "`") {
+                advance(i + 1);
+                skipString("`", true, true);
+            }
+            else
+                advance(i + 1);
+            lastCode = i - 1;
+            continue;
+        }
+        const prefix = /^(?:\$+@?|@\$*)?(?=")/.exec(text.slice(i, i + 4))?.[0] ?? null;
+        if (prefix !== null) {
+            advance(i + prefix.length);
+            const quotes = /^"{3,}/.exec(text.slice(i, i + 64))?.[0];
+            if (quotes) {
+                advance(i + quotes.length);
+                skipString(quotes, false, true);
+            }
+            else {
+                const verbatim = prefix.includes("@");
+                advance(i + 1);
+                skipString('"', !verbatim, verbatim);
+            }
+            continue;
+        }
+        if (c === "'") {
+            advance(i + 1);
+            skipString("'", true, false);
+            continue;
+        }
+        advance(i + 1);
+    }
+    return lines;
+}

package/dist/code-files.d.ts

@@ -0,0 +1,11 @@
+import type { Config } from "./options.ts";
+import type { CodeFile } from "./types.ts";
+/**
+ * Returns a function that gives the files of the --code and --references directories, read on its
+ * first call. The checker's own source is left out, so a copy of the checker inside one of those
+ * directories does not flag the IDs its comments and messages give as examples. checkerDir is the
+ * directory that holds the checker's entry point and its modules, and nothing else.
+ */
+export declare function createCodeFiles(config: Config, checkerDir: string): () => CodeFile[];
+/** The spec IDs that PLACEHOLDER comments in the --code directories cite. */
+export declare function collectPlaceholders(codeFiles: CodeFile[]): Set<string>;

package/dist/code-files.js

@@ -0,0 +1,41 @@
+// The --code and --references directories, walked and read once for the placeholder, the
+// implementation-reference and the code comment checks.
+import { readFileSync } from "node:fs";
+import { join, sep } from "node:path";
+import { walk } from "./files.js";
+/**
+ * Returns a function that gives the files of the --code and --references directories, read on its
+ * first call. The checker's own source is left out, so a copy of the checker inside one of those
+ * directories does not flag the IDs its comments and messages give as examples. checkerDir is the
+ * directory that holds the checker's entry point and its modules, and nothing else.
+ */
+export function createCodeFiles(config, checkerDir) {
+    let cache;
+    const own = (f) => f.startsWith(checkerDir + sep);
+    return () => {
+        if (cache)
+            return cache;
+        const files = [];
+        const roots = [
+            ...config.codeRoots.map((root) => ({ root, code: true })),
+            ...config.referenceRoots.map((root) => ({ root, code: false })),
+        ];
+        for (const { root, code } of roots)
+            walk(join(config.repoDir, root), (f) => {
+                if (!own(f) && /\.(cs|ts|mjs|js|ps1|fs|md|json)$/.test(f))
+                    files.push({ code, file: f, text: readFileSync(f, "utf8") });
+            });
+        return (cache = files);
+    };
+}
+/** The spec IDs that PLACEHOLDER comments in the --code directories cite. */
+export function collectPlaceholders(codeFiles) {
+    const found = new Set();
+    for (const { code, file, text } of codeFiles) {
+        if (!code || !/\.(cs|ts|mjs|js|ps1|fs)$/.test(file))
+            continue;
+        for (const m of text.matchAll(/PLACEHOLDER:\s*((?:FMT|RULE|SCR)-[A-Z0-9]+-\d+)/g))
+            found.add(m[1]);
+    }
+    return found;
+}