@scientific-method/standard-checker 0.4.0 → 0.5.1

package/README.md

@@ -12,8 +12,9 @@ pnpm exec standard-checker --check    # check, and fail on a stale index or PARI
 ```
 
 It exits with 0 when the repository passes, 1 when it reports problems (one line per problem,
-starting with the file's path), and 2 when the options are invalid. `--record-validation` cannot be
-combined with `--check`, nor `--require-ksc` with `--no-ksy`.
+starting with the file's path), and 2 when the options are invalid or `--record-validation` cannot
+write the record. `--record-validation` cannot be combined with `--check`, nor `--require-ksc` with
+`--no-ksy`.
 
 A pass ends with `spec check passed:` and the counts of entries, parity rows and deviations. When a
 step of the check did not run, it ends with `spec check passed with skipped steps:`, the counts, and
@@ -33,7 +34,7 @@ problems under other sections carry no label yet.
 |---|---|---|
 | `--root <dir>` | The repository to check. | the current directory |
 | `--check` | Fail when an index or `PARITY.md` is stale, instead of rewriting it. | rewrite |
-| `--base <ref>` | Also fail when a spec ID, area or deviation that exists at `<ref>` is gone. | where HEAD forked from `origin/$GITHUB_BASE_REF` or `origin/main`, when that resolves |
+| `--base <ref>` | Also fail when a spec ID, area or deviation that exists at `<ref>` is gone, or when a superseded format entry has no layout table although it had one at `<ref>`. | where HEAD forked from `origin/$GITHUB_BASE_REF` or `origin/main`, when that resolves |
 | `--no-ksy` | Skip compiling the Kaitai definitions in `spec/formats/`. The result line names the skipped compilation. | compile |
 | `--require-ksc` | Fail when `spec/formats/` holds Kaitai definitions and no compiler is found, instead of passing with the compilation skipped. | pass with the compilation skipped |
 | `--glossary <path>` | Also accept the terms of a draft glossary file, or of a directory of them. | none |
@@ -42,13 +43,21 @@ problems under other sections carry no label yet.
 | `--images <ranges>` | Comma-separated half-open address ranges of the original's flat 32-bit images, such as `0x00400000..0x004C9000`. A `0x` value inside one that a code comment gives must be recorded in an entry the comment cites. | none, so only `fn_` and `g_` names are checked |
 | `--max-range <bytes>` | The largest address range an entry can record an address by. A larger one, such as a whole section, records only its two ends. | `0x10000` |
 | `--data-dirs <dirs>` | Comma-separated top-level directories of the original's data. A path into one must name a file of some build, with its exact case. | the top-level directories of the files the build entries list |
-| `--record-validation <builds>` | Write `VALIDATION.md` for the marked test files of validated parity rows, naming the comma-separated build IDs the run used. Run it only after every test in those files passed with none skipped. | not written |
+| `--record-validation <builds>` | Write `VALIDATION.md` for the marked test files of validated parity rows, naming the comma-separated build IDs the run used and HEAD as the commit the run tested. Run it only after every test in those files passed with none skipped, against HEAD as committed: it refuses, with exit code 2, when the working tree differs from HEAD in anything other than `VALIDATION.md`, counting untracked files that git does not ignore. | not written |
 | `--help` | Print the options. | |
 
 The `KSC` environment variable names the Kaitai Struct compiler. Without it, the checker looks for
 `kaitai-struct-compiler` or `ksc` on `PATH`. When it finds neither, it skips the compilation and
 names it in the result line, or with `--require-ksc` reports the missing compiler as a problem.
 
+On Windows the search tries each name with the `PATHEXT` extensions, as `cmd.exe` does, so it finds
+the `.bat` launcher of the official release and skips the extensionless Unix script beside it. The
+checker then runs the launcher by its full path. A `KSC` that holds a bare name, with no directory,
+is looked up on `PATH` the same way.
+
+On every platform, a launcher found on `PATH` whose `--version` fails is not used, and the checker
+prints a warning naming its path, with its output.
+
 ## In GitHub Actions
 
 The toolkit's `actions/check-documentation` composite action runs this checker with `--check`,

package/dist/checks/base.d.ts

@@ -2,6 +2,7 @@ import type { Context } from "../context.ts";
 import type { Deviation } from "./deviations.ts";
 /**
  * Reports a spec ID, area or deviation that exists at the base (--base, or where HEAD forked from
- * the base branch) and is gone now. Does nothing when there is no base to compare with.
+ * the base branch) and is gone now, and a superseded format entry whose Layout has no table although
+ * it had one at the base. Does nothing when there is no base to compare with.
  */
 export declare function checkBase(ctx: Context, deviations: Map<string, Deviation>): void;

package/dist/checks/base.js

@@ -1,9 +1,12 @@
-// IDs, areas and deviations that exist on the base branch must not disappear.
+// IDs, areas and deviations that exist on the base branch must not disappear, and a format entry
+// superseded since the base keeps the layout table it had there.
 import { execFileSync } from "node:child_process";
+import { relative } from "node:path";
 import { splitSections, tables } from "../markdown.js";
 /**
  * Reports a spec ID, area or deviation that exists at the base (--base, or where HEAD forked from
- * the base branch) and is gone now. Does nothing when there is no base to compare with.
+ * the base branch) and is gone now, and a superseded format entry whose Layout has no table although
+ * it had one at the base. Does nothing when there is no base to compare with.
  */
 export function checkBase(ctx, deviations) {
     const { problem } = ctx;
@@ -62,6 +65,20 @@ export function checkBase(ctx, deviations) {
             if (!areas.includes(a))
                 problem(null, `area ${a} exists at ${base} and has been removed or renamed`, "IDENTIFIERS-5");
         }
+        // The format checks let a superseded entry have no layout table, so one retired from unknown
+        // keeps its None known. A superseded entry stays as it was when it was replaced (IDENTIFIERS-7),
+        // so one that had a table at the base may not drop it on the way.
+        const layoutTables = (body) => {
+            const layout = splitSections(body).find((s) => s.title === "Layout");
+            return layout ? tables(layout.text).length : 0;
+        };
+        for (const e of entries.values()) {
+            if (e.kind !== "FMT" || e.meta.status !== "superseded" || layoutTables(e.body) > 0)
+                continue;
+            const old = show(relative(repoDir, e.file).replaceAll("\\", "/"));
+            if (old && layoutTables(old) > 0)
+                problem(e.file, `Layout has no table, but it had one at ${base}`, "IDENTIFIERS-7");
+        }
         // A base from before the deviation log became a directory keeps its deviations in DEVIATIONS.md.
         const oldDev = show("DEVIATIONS.md");
         if (oldDev)

package/dist/checks/evidence-entries.js

@@ -129,13 +129,20 @@ export function checkExperiment(ctx, id, e, isSup) {
             const fx = JSON.parse(readFileSync(fixture, "utf8"));
             if (fx.experiment !== id)
                 problem(fixture, `experiment must be ${id}`);
-            if (!["new-game", "emulated-call"].includes(meta.starting_state) &&
-                !(fx.starting_state && fx.starting_state.xxh3))
-                problem(fixture, "gives the hash of the save its runs started from");
-            if (typeof meta.starting_state === "string" &&
-                meta.starting_state.endsWith(".patch.json") &&
-                !fx.starting_state?.base_xxh3)
+            // Only a new game and an emulated call start without a save. starting_state null still has
+            // one: a save that cannot be committed, kept with the captures and found by its hash.
+            const save = fx.starting_state;
+            if (!["new-game", "emulated-call"].includes(meta.starting_state) && !save?.xxh3) {
+                const where = "gives the hash of the save its runs started from in starting_state.xxh3";
+                problem(fixture, meta.starting_state === null
+                    ? `${where}; starting_state null names a save kept with the captures, and an experiment that starts without a save has starting_state new-game or emulated-call`
+                    : where);
+            }
+            if (typeof meta.starting_state === "string" && meta.starting_state.endsWith(".patch.json") && !save?.base_xxh3)
                 problem(fixture, "a patch fixture gives the base save's hash as well");
+            for (const key of ["xxh3", "base_xxh3"])
+                if (save?.[key] && !/^[0-9a-f]{32}$/.test(String(save[key])))
+                    problem(fixture, `starting_state.${key} must be 32 lower-case hex digits`);
             for (const run of asList(fx.runs)) {
                 for (const ev of asList(run?.events))
                     if (!glossary.has(ev?.event))

package/dist/checks/formats.js

@@ -25,6 +25,9 @@ export function checkFormat(ctx, e, formatNames) {
     const { file, meta } = e;
     const id = meta.id;
     const first = asList(meta.builds)[0];
+    // An unknown entry claims nothing, and a superseded entry stays as it was when it was replaced
+    // (IDENTIFIERS-7), so neither needs a definition or a layout table, nor a status set by its rows.
+    const claimsContent = meta.status !== "unknown" && meta.status !== "superseded";
     if (meta.text === true) {
         if (meta.definition !== null || meta.size !== null || meta.byte_order !== null)
             problem(file, "a text format has definition, size and byte_order null");
@@ -32,7 +35,7 @@ export function checkFormat(ctx, e, formatNames) {
     else {
         if (!["little", "big"].includes(meta.byte_order))
             problem(file, "byte_order must be little or big for a binary format");
-        if (meta.status !== "unknown" && meta.status !== "superseded") {
+        if (claimsContent) {
             const expected = `${id.toLowerCase().replaceAll("-", "_")}.ksy`;
             if (meta.definition !== expected)
                 problem(file, `definition must be ${expected}`);
@@ -94,7 +97,7 @@ export function checkFormat(ctx, e, formatNames) {
     if (layout) {
         const ts = tables(layout.text);
         const wanted = meta.text === true ? TEXT_LAYOUT : BINARY_LAYOUT;
-        if (meta.status !== "unknown" && ts.length === 0)
+        if (claimsContent && ts.length === 0)
             problem(file, "Layout has no table");
         for (const t of ts) {
             if (t.header.join("|") !== wanted.join("|")) {
@@ -155,7 +158,7 @@ export function checkFormat(ctx, e, formatNames) {
             enumNames.get(n).push(id);
         }
     }
-    if (meta.status !== "superseded" && meta.status !== "unknown") {
+    if (claimsContent) {
         const expected = disputed ? "disputed" : lowest;
         if (expected && meta.status !== expected)
             problem(file, `status must be ${expected}, the lowest status among its rows`);

package/dist/checks/kaitai.js

@@ -1,8 +1,8 @@
 // Kaitai compilation: every definition in spec/formats/ belongs to a format entry and compiles.
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { accessSync, constants, existsSync, mkdtempSync, readdirSync, rmSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { basename, join } from "node:path";
+import { basename, delimiter, extname, join } from "node:path";
 /**
  * Checks that each .ksy file in spec/formats/ belongs to a format entry, and compiles them all with
  * the Kaitai Struct compiler. With --no-ksy, or with no compiler found, the compilation is recorded
@@ -51,9 +51,7 @@ export function compileKaitai(ctx) {
             catch (err) {
                 // A compiler that cannot be started, such as a KSC naming a missing file, prints nothing,
                 // so its error message is the only account of the failure.
-                const failure = err;
-                const output = `${String(failure.stdout ?? "")}${String(failure.stderr ?? "")}`;
-                problem(null, `Kaitai definitions do not compile:\n${output || (failure.message ?? String(err))}`);
+                problem(null, `Kaitai definitions do not compile:\n${toolOutput(err)}`);
             }
         }
     }
@@ -87,16 +85,65 @@ function kaitaiBatches(fixed, files) {
         batches.push(batch);
     return batches;
 }
+// KSC is used as given, except that a bare command name is looked up on PATH like the default
+// names. A name found on PATH whose --version fails is named on stderr, so a broken launcher does
+// not read as a missing one.
 function findKaitai() {
-    if (process.env.KSC)
-        return { cmd: process.env.KSC, args: [] };
-    for (const cmd of ["kaitai-struct-compiler", "ksc"]) {
+    const ksc = process.env.KSC;
+    if (ksc)
+        return { cmd: isBareName(ksc) ? (findOnPath(ksc) ?? ksc) : ksc, args: [] };
+    for (const name of ["kaitai-struct-compiler", "ksc"]) {
+        const cmd = findOnPath(name);
+        if (!cmd)
+            continue;
         try {
             runTool(cmd, ["--version"]);
             return { cmd, args: [] };
         }
-        catch { }
+        catch (err) {
+            console.warn(`warning: ${cmd} --version failed, so it is not used:\n${toolOutput(err).trim()}`);
+        }
+    }
+    return null;
+}
+const isBareName = (cmd) => !/[\\/]/.test(cmd);
+// What a failed runTool call printed or, when it printed nothing because the program could not be
+// started, the error's message.
+function toolOutput(err) {
+    const failure = err;
+    const output = `${String(failure.stdout ?? "")}${String(failure.stderr ?? "")}`;
+    return output.trim() ? output : String(failure.message ?? err);
+}
+// The path of the first file on PATH that runs as `name`, or null when there is none. The path
+// matters on Windows: cmd.exe runs a .bat that it found on PATH under a quoted bare name with %~dp0
+// set to the working directory, and the compiler's launcher finds its jars through %~dp0. There a
+// name without one of the PATHEXT extensions is tried with each, in PATH order and then PATHEXT
+// order as cmd.exe searches, so the extensionless Unix script that ships beside the .bat launcher
+// is skipped. Elsewhere it takes the first executable file of that name, as execFileSync would.
+function findOnPath(name) {
+    const windows = process.platform === "win32";
+    let exts = [""];
+    if (windows) {
+        const pathExts = (process.env.PATHEXT || ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean);
+        if (!pathExts.some((e) => extname(name).toLowerCase() === e.toLowerCase()))
+            exts = pathExts;
     }
+    const dirs = (process.env.PATH ?? "")
+        .split(delimiter)
+        .map((d) => (windows ? d.replace(/"/g, "") : d))
+        .filter(Boolean);
+    for (const dir of dirs)
+        for (const ext of exts) {
+            const file = join(dir, name + ext);
+            try {
+                if (!statSync(file, { throwIfNoEntry: false })?.isFile())
+                    continue;
+                if (!windows)
+                    accessSync(file, constants.X_OK);
+                return file;
+            }
+            catch { }
+        }
     return null;
 }
 // On Windows the compiler is a .bat file, which only cmd.exe can run. Node's shell: true joins the

package/dist/checks/validation.js

@@ -30,6 +30,11 @@ export function checkValidation(ctx, { validatedTests }) {
                 console.error(`--record-validation: ${b} is not a build entry`);
                 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);
+        }
         let commit;
         try {
             commit = execFileSync("git", ["rev-parse", "HEAD"], { cwd: repoDir, encoding: "utf8" }).trim();
@@ -38,9 +43,68 @@ export function checkValidation(ctx, { validatedTests }) {
             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');
+        // Commit is the commit the run tested, so the run must have tested HEAD as committed. Any change
+        // to a tracked file, or an untracked file that git does not ignore, anywhere in the repository
+        // means it tested something else. Only an earlier VALIDATION.md may differ, since this run
+        // replaces it. An untracked directory is listed once, and submodules are compared whatever the
+        // repository's submodule.*.ignore or diff.ignoreSubmodules settings say.
+        const changed = [];
+        try {
+            const status = execFileSync("git", [
+                "status",
+                "--porcelain=v1",
+                "-z",
+                "--untracked-files=normal",
+                "--ignore-submodules=none",
+                "--",
+                ":/",
+                ":(exclude)VALIDATION.md",
+            ], { cwd: repoDir, encoding: "utf8", maxBuffer: 256 * 1024 * 1024 }).split("\0");
+            for (let i = 0; i < status.length; i++) {
+                if (!status[i])
+                    continue;
+                changed.push(status[i].slice(3));
+                // A rename or copy is followed by its source path.
+                if (/[RC]/.test(status[i].slice(0, 2)))
+                    i++;
+            }
+            // git status does not look at a file marked assume-unchanged or skip-worktree, so a file with
+            // either mark that is present is hashed and compared with HEAD here. A sparse checkout leaves
+            // its skip-worktree files absent, and an absent file was not part of what the run tested.
+            const top = execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd: repoDir, encoding: "utf8" }).trim();
+            const marked = execFileSync("git", ["ls-files", "-v", "-z", "--full-name", "--", ":/", ":(exclude)VALIDATION.md"], { cwd: repoDir, encoding: "utf8", maxBuffer: 256 * 1024 * 1024 })
+                .split("\0")
+                .filter((e) => e && (e[0] === "S" || /[a-z]/.test(e[0])))
+                .map((e) => e.slice(2))
+                .filter((p) => existsSync(join(top, p)));
+            if (marked.length) {
+                const worktree = execFileSync("git", ["hash-object", "--stdin-paths"], {
+                    cwd: top,
+                    encoding: "utf8",
+                    input: marked.join("\n") + "\n",
+                }).split("\n");
+                const head = new Map();
+                for (const line of execFileSync("git", ["--literal-pathspecs", "ls-tree", "-r", "-z", "HEAD", "--", ...marked], {
+                    cwd: top,
+                    encoding: "utf8",
+                }).split("\0")) {
+                    const tab = line.indexOf("\t");
+                    if (tab > 0)
+                        head.set(line.slice(tab + 1), line.slice(0, tab).split(" ")[2]);
+                }
+                marked.forEach((p, i) => {
+                    if (head.get(p) !== worktree[i])
+                        changed.push(p);
+                });
+            }
+        }
+        catch {
+            console.error("--record-validation: git status failed");
+            process.exit(2);
+        }
+        if (changed.length) {
+            const shown = changed.slice(0, 5).join(", ") + (changed.length > 5 ? `, and ${changed.length - 5} more` : "");
+            console.error(`--record-validation: the working tree differs from HEAD (${shown}), so HEAD is not the commit the run tested. Commit the change, run the marked tests against that commit, then record`);
             process.exit(2);
         }
         writeFileSync(validationPath, [

package/dist/standard-checker.js

@@ -30,8 +30,10 @@
 //   --record-validation <builds>
 //                       write VALIDATION.md for the test files of the validated rows that carry a
 //                       "needs: GAME_DIR" comment, naming the comma-separated build IDs the run
-//                       used. Run it only after every test in those files passed, with none
-//                       skipped, against the original's files
+//                       used and HEAD as the commit the run tested. Run it only after every test
+//                       in those files passed, with none skipped, against the original's files
+//                       and HEAD as committed; it refuses when the working tree differs from HEAD
+//                       in anything other than VALIDATION.md
 //
 // Each problem is one line that starts with the path it concerns, or spec for the spec as a whole.
 // A problem that breaks a numbered rule of the standard ends with the rule's label, such as

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scientific-method/standard-checker",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Checks a restoration's spec/, parity/ and deviations/ against version 1 of the dinorefurb documentation standard.",
   "type": "module",
   "license": "MIT",