@scientific-method/standard-checker 0.1.0 → 0.2.0

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;
+}

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>;