@scientific-method/standard-checker 0.1.0 → 0.3.0

package/dist/markdown.js

@@ -0,0 +1,162 @@
+// Markdown and CSV: entries with front matter, sections, tables and value files.
+import { readFileSync } from "node:fs";
+import { parseYaml } from "./yaml.js";
+/** The number of lines of text, not counting the empty one after a final newline. */
+export const lineCount = (text) => (text === "" ? 0 : text.split("\n").length - (text.endsWith("\n") ? 1 : 0));
+/** Reads a text file with CRLF line ends read as LF. */
+export const readText = (file) => readFileSync(file, "utf8").replace(/\r\n/g, "\n");
+/** Reads an entry's front matter, body and sections, or reports why it cannot and returns null. */
+export function readEntry(file, problem) {
+    const text = readFileSync(file, "utf8").replace(/\r\n/g, "\n");
+    if (!text.startsWith("---\n")) {
+        problem(file, "has no front matter");
+        return null;
+    }
+    const end = text.indexOf("\n---\n", 4);
+    if (end < 0) {
+        problem(file, "front matter is not closed");
+        return null;
+    }
+    const meta = parseYaml(text.slice(4, end), file, problem);
+    const body = text.slice(end + 5);
+    return { file, meta, body, sections: splitSections(body) };
+}
+/** The `##` sections of a Markdown body, skipping fenced code. */
+export function splitSections(body) {
+    const sections = [];
+    let current = null;
+    let fence = false;
+    for (const line of body.split("\n")) {
+        if (/^(```|~~~)/.test(line))
+            fence = !fence;
+        const m = !fence && /^## (.+)$/.exec(line);
+        if (m) {
+            current = { title: m[1].trim(), lines: [] };
+            sections.push(current);
+        }
+        else if (current)
+            current.lines.push(line);
+    }
+    return sections.map((s) => ({ title: s.title, text: s.lines.join("\n") }));
+}
+/** Every Markdown table in a section, with the `###` heading above it. */
+export function tables(text) {
+    const out = [];
+    const lines = text.split("\n");
+    let heading = null;
+    let fence = false;
+    for (let i = 0; i < lines.length; i++) {
+        if (/^(```|~~~)/.test(lines[i]))
+            fence = !fence;
+        if (fence)
+            continue;
+        const h = /^### (.+)$/.exec(lines[i]);
+        if (h)
+            heading = h[1].trim();
+        if (lines[i].startsWith("|") && i + 1 < lines.length && /^\|[\s:|-]+\|\s*$/.test(lines[i + 1])) {
+            const header = cells(lines[i]);
+            const rows = [];
+            let j = i + 2;
+            while (j < lines.length && lines[j].startsWith("|")) {
+                rows.push(cells(lines[j]));
+                j++;
+            }
+            out.push({ heading, header, rows, line: i });
+            i = j - 1;
+        }
+    }
+    return out;
+}
+/** The cells of a table row, with `\|` read as a pipe and pipes inside code spans kept. */
+export function cells(line) {
+    const parts = [];
+    let cur = "";
+    let code = false;
+    const s = line.trim().replace(/^\|/, "").replace(/\|$/, "");
+    for (let k = 0; k < s.length; k++) {
+        const ch = s[k];
+        if (ch === "`")
+            code = !code;
+        if (ch === "\\" && s[k + 1] === "|") {
+            cur += "|";
+            k++;
+            continue;
+        }
+        if (ch === "|" && !code) {
+            parts.push(cur.trim());
+            cur = "";
+            continue;
+        }
+        cur += ch;
+    }
+    parts.push(cur.trim());
+    return parts;
+}
+/**
+ * A value file: CSV as RFC 4180 defines it, with a header row. Returns { header, rows }, or null
+ * after reporting a problem.
+ */
+export function readCsv(file, problem) {
+    // Spreadsheet programs start a UTF-8 CSV with a byte order mark, which would join the first header.
+    const text = readFileSync(file, "utf8").replace(/^/, "");
+    const records = [];
+    let record = [];
+    let field = "";
+    let quoted = false;
+    let wasQuoted = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (quoted) {
+            if (ch === '"' && text[i + 1] === '"') {
+                field += '"';
+                i++;
+            }
+            else if (ch === '"')
+                quoted = false;
+            else
+                field += ch;
+        }
+        else if (ch === '"' && field === "" && !wasQuoted) {
+            quoted = true;
+            wasQuoted = true;
+        }
+        else if (ch === ",") {
+            record.push(field);
+            field = "";
+            wasQuoted = false;
+        }
+        else if (ch === "\n" || ch === "\r") {
+            if (ch === "\r" && text[i + 1] === "\n")
+                i++;
+            record.push(field);
+            records.push(record);
+            record = [];
+            field = "";
+            wasQuoted = false;
+        }
+        else
+            field += ch;
+    }
+    if (quoted) {
+        problem(file, "has a quoted field that is never closed");
+        return null;
+    }
+    if (field !== "" || record.length > 0) {
+        record.push(field);
+        records.push(record);
+    }
+    // Blank lines at the end of the file are not rows.
+    while (records.length > 0 && records.at(-1).length === 1 && records.at(-1)[0] === "")
+        records.pop();
+    if (records.length === 0) {
+        problem(file, "has no header row");
+        return null;
+    }
+    const [header, ...rows] = records;
+    for (const row of rows)
+        if (row.length !== header.length) {
+            problem(file, `the row ${row.join(",")} has ${row.length} fields, not ${header.length}`);
+            return null;
+        }
+    return { header, rows };
+}

package/dist/options.d.ts

@@ -0,0 +1,34 @@
+/** What one run of the checker was asked to do, from its command line. */
+export interface Config {
+    /** The repository being checked (--root), absolute. */
+    repoDir: string;
+    /** Its spec/ directory. */
+    specDir: string;
+    /** --check: report stale generated files instead of rewriting them. */
+    checkOnly: boolean;
+    /** --no-ksy: skip compiling the Kaitai definitions. */
+    skipKsy: boolean;
+    /** --base, or null when it was not given. */
+    baseArg: string | null;
+    /** Every --glossary path, in order. */
+    glossaryDrafts: string[];
+    /** The --code directories, relative to repoDir. */
+    codeRoots: string[];
+    /** The --references directories, relative to repoDir. */
+    referenceRoots: string[];
+    /** The --images ranges, as half-open [low, high). */
+    images: Array<[number, number]>;
+    /** --max-range in bytes. */
+    maxRange: number;
+    /** The --data-dirs directories, or undefined when the option was not given. */
+    dataDirs: string[] | undefined;
+    /** The --record-validation build IDs, or undefined when the option was not given. */
+    recordValidation: string[] | undefined;
+}
+/**
+ * Splits a comma-separated option into its trimmed, non-empty parts, or returns fallback when the
+ * option was not given.
+ */
+export declare const dirList: (value: string | undefined, fallback: string[]) => string[];
+/** Reads the arguments after the script's path. An invalid one prints why and exits with 2. */
+export declare function parseOptions(argv: string[]): Config;

package/dist/options.js

@@ -0,0 +1,87 @@
+// The command line, read into a Config. An invalid option prints why and exits with 2.
+import { join, resolve } from "node:path";
+/**
+ * Splits a comma-separated option into its trimmed, non-empty parts, or returns fallback when the
+ * option was not given.
+ */
+export const dirList = (value, fallback) => value === undefined
+    ? fallback
+    : value
+        .split(",")
+        .map((x) => x.trim())
+        .filter(Boolean);
+const FLAGS = ["--check", "--no-ksy"];
+const VALUED = [
+    "--root",
+    "--base",
+    "--glossary",
+    "--code",
+    "--references",
+    "--images",
+    "--max-range",
+    "--data-dirs",
+    "--record-validation",
+];
+/** Reads the arguments after the script's path. An invalid one prints why and exits with 2. */
+export function parseOptions(argv) {
+    const options = { glossary: [] };
+    for (let k = 0; k < argv.length; k++) {
+        const arg = argv[k];
+        if (FLAGS.includes(arg))
+            options[arg.slice(2)] = true;
+        else if (VALUED.includes(arg)) {
+            if (k + 1 >= argv.length) {
+                console.error(`${arg} needs a value; see --help`);
+                process.exit(2);
+            }
+            if (arg === "--glossary")
+                options.glossary.push(argv[++k]);
+            else
+                options[arg.slice(2)] = argv[++k];
+        }
+        else {
+            console.error(`unknown option ${arg}; see --help`);
+            process.exit(2);
+        }
+    }
+    const repoDir = resolve(options.root ?? ".");
+    const specDir = join(repoDir, "spec");
+    const checkOnly = options.check === true;
+    if (checkOnly && options["record-validation"] !== undefined) {
+        console.error("--record-validation writes VALIDATION.md, so it cannot be combined with --check");
+        process.exit(2);
+    }
+    const skipKsy = options["no-ksy"] === true;
+    const baseArg = options.base ?? null;
+    const codeRoots = dirList(options.code, ["src", "tests", "tools"]);
+    const referenceRoots = dirList(options.references, []);
+    // Half-open [low, high) ranges, as numbers: flat 32-bit addresses fit exactly.
+    const images = dirList(options.images, []).map((range) => {
+        const m = /^0x([0-9A-Fa-f]{8})\.\.0x([0-9A-Fa-f]{8})$/.exec(range);
+        const [low, high] = m ? [parseInt(m[1], 16), parseInt(m[2], 16)] : [NaN, NaN];
+        if (!m || high <= low) {
+            console.error(`--images takes half-open ranges such as 0x00400000..0x004C9000, not ${range}`);
+            process.exit(2);
+        }
+        return [low, high];
+    });
+    const maxRange = options["max-range"] === undefined ? 0x10000 : Number(options["max-range"]);
+    if (!Number.isSafeInteger(maxRange) || maxRange < 1) {
+        console.error(`--max-range takes a positive number of bytes, such as 0x10000, not ${options["max-range"]}`);
+        process.exit(2);
+    }
+    return {
+        repoDir,
+        specDir,
+        checkOnly,
+        skipKsy,
+        baseArg,
+        glossaryDrafts: options.glossary,
+        codeRoots,
+        referenceRoots,
+        images,
+        maxRange,
+        dataDirs: options["data-dirs"] === undefined ? undefined : dirList(options["data-dirs"], []),
+        recordValidation: options["record-validation"] === undefined ? undefined : dirList(options["record-validation"], []),
+    };
+}

package/dist/problems.d.ts

@@ -0,0 +1,27 @@
+/** The whole numbers from 1 to N. */
+type UpTo<N extends number, Seen extends 0[] = [0]> = Seen["length"] | (Seen["length"] extends N ? never : UpTo<N, [...Seen, 0]>);
+/**
+ * A numbered rule of the documentation standard, such as `STATUS-14`. The standard opens each rule
+ * with the heading `###### STATUS-14`, anchored at `#status-14` on the site and in vendored copies.
+ * Each count is the last rule the standard numbers in that section, so a label that names no rule
+ * does not compile. Raise a count, or add a section, when the standard numbers more rules.
+ */
+export type Rule = `IDENTIFIERS-${UpTo<7>}` | `STATUS-${UpTo<41>}` | `ENTRY-TYPES-${UpTo<8>}`;
+/**
+ * Records a problem with file (or with the spec as a whole when file is null). A problem that breaks
+ * a numbered rule names it.
+ */
+export type Problem = (file: string | null, message: string, rule?: Rule) => void;
+/** The problem collector of one run. */
+export interface Problems {
+    /** Records a problem. */
+    problem: Problem;
+    /**
+     * Prints every distinct problem in the order found, with the summary, and exits with 1. Returns
+     * when there are none.
+     */
+    report(entryCount: number): void;
+}
+/** Creates the collector for a run over repoDir, against which problem paths are printed. */
+export declare function createProblems(repoDir: string): Problems;
+export {};

package/dist/problems.js

@@ -0,0 +1,27 @@
+// The problems a run finds, kept in the order they are found and printed together at the end.
+import { relative } from "node:path";
+/** Creates the collector for a run over repoDir, against which problem paths are printed. */
+export function createProblems(repoDir) {
+    const problems = [];
+    let citedRule = false;
+    // A problem that breaks a numbered rule ends with the rule's label, so whoever fixes it can read
+    // that one rule instead of the whole section.
+    const problem = (file, message, rule) => {
+        if (rule)
+            citedRule = true;
+        problems.push(`${file ? relative(repoDir, file).replaceAll("\\", "/") : "spec"}: ${message}${rule ? ` [${rule}]` : ""}`);
+    };
+    const report = (entryCount) => {
+        // The same problem can be found twice, such as a term that cites one finding in two places.
+        const unique = [...new Set(problems)];
+        if (unique.length) {
+            for (const p of unique)
+                console.error(p);
+            console.error(`\n${unique.length} problem(s) in ${entryCount} spec entries.`);
+            if (citedRule)
+                console.error("A label in brackets, such as [STATUS-14], names the rule of the documentation standard that the problem breaks. The standard opens it with the heading ###### STATUS-14, anchored at https://dinorefurb.com/documentation-standard/#status-14 and at #status-14 in a vendored copy.");
+            process.exit(1);
+        }
+    };
+    return { problem, report };
+}