@scientific-method/standard-checker 0.3.0 → 0.4.0

package/README.md

@@ -13,7 +13,13 @@ 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`.
+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
+`Skipped:` followed by each step and why, such as
+`Skipped: Kaitai compilation of 2 definitions (--no-ksy).` A failing run lists the skipped steps
+after its problems.
 
 A problem that breaks a numbered rule of the standard ends with the rule's label in brackets, such
 as `[STATUS-14]`. The standard opens that rule with the heading `###### STATUS-14`, anchored at
@@ -28,7 +34,8 @@ 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 |
-| `--no-ksy` | Skip compiling the Kaitai definitions in `spec/formats/`. | compile |
+| `--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 |
 | `--code <dirs>` | Comma-separated directories whose files may cite spec and deviation IDs and hold `PLACEHOLDER` comments. | `src,tests,tools` |
 | `--references <dirs>` | Comma-separated directories whose files may cite IDs but whose `PLACEHOLDER` comments do not count against parity. | none |
@@ -39,12 +46,14 @@ problems under other sections carry no label yet.
 | `--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`, and warns when it finds neither.
+`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.
 
 ## In GitHub Actions
 
 The toolkit's `actions/check-documentation` composite action runs this checker with `--check`,
-installs a pinned Kaitai compiler when the repository has `.ksy` files, and exposes every option
+installs a pinned Kaitai compiler when the repository has `.ksy` files (and then passes
+`--require-ksc`), and exposes every option
 above as an input. Pin the action to the toolkit commit whose `packages/standard-checker` matches
 the version installed here, so CI and local runs apply the same checks.
 

package/dist/checks/kaitai.d.ts

@@ -1,6 +1,7 @@
 import type { Context } from "../context.ts";
 /**
  * Checks that each .ksy file in spec/formats/ belongs to a format entry, and compiles them all with
- * the Kaitai Struct compiler, warning when there is none. Does nothing with --no-ksy.
+ * the Kaitai Struct compiler. With --no-ksy, or with no compiler found, the compilation is recorded
+ * as a skipped step; with --require-ksc, a missing compiler is a problem instead.
  */
 export declare function compileKaitai(ctx: Context): void;

package/dist/checks/kaitai.js

@@ -5,47 +5,60 @@ import { tmpdir } from "node:os";
 import { basename, 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, warning when there is none. Does nothing with --no-ksy.
+ * the Kaitai Struct compiler. With --no-ksy, or with no compiler found, the compilation is recorded
+ * as a skipped step; with --require-ksc, a missing compiler is a problem instead.
  */
 export function compileKaitai(ctx) {
-    const { problem } = ctx;
+    const { problem, skip } = ctx;
     const { entries } = ctx.spec;
-    const { specDir, skipKsy } = ctx.config;
-    if (!skipKsy) {
-        const ksys = [];
-        const fd = join(specDir, "formats");
-        if (existsSync(fd))
-            for (const f of readdirSync(fd))
-                if (f.endsWith(".ksy"))
-                    ksys.push(join(fd, f));
-        for (const k of ksys) {
-            const id = basename(k, ".ksy")
-                .toUpperCase()
-                .replace(/^FMT_([A-Z0-9]+)_(\d+)$/, "FMT-$1-$2");
-            if (!entries.has(id))
-                problem(k, `belongs to no format entry (${id})`);
-        }
-        const compiler = findKaitai();
-        if (compiler && ksys.length) {
-            const out = mkdtempSync(join(tmpdir(), "ksy-check-"));
-            const fixed = [...compiler.args, "--target", "python", "--outdir", out, "--import-path", fd];
+    const { specDir, skipKsy, requireKsc } = ctx.config;
+    const ksys = [];
+    const fd = join(specDir, "formats");
+    if (existsSync(fd))
+        for (const f of readdirSync(fd))
+            if (f.endsWith(".ksy"))
+                ksys.push(join(fd, f));
+    for (const k of ksys) {
+        const id = basename(k, ".ksy")
+            .toUpperCase()
+            .replace(/^FMT_([A-Z0-9]+)_(\d+)$/, "FMT-$1-$2");
+        if (!entries.has(id))
+            problem(k, `belongs to no format entry (${id})`);
+    }
+    if (!ksys.length)
+        return;
+    const definitions = `${ksys.length} definition${ksys.length === 1 ? "" : "s"}`;
+    if (skipKsy) {
+        skip(`Kaitai compilation of ${definitions} (--no-ksy)`);
+        return;
+    }
+    const compiler = findKaitai();
+    if (!compiler) {
+        const missing = "no Kaitai Struct compiler found, set KSC or install kaitai-struct-compiler";
+        if (requireKsc)
+            problem(null, `${missing}. --require-ksc requires compiling the ${definitions} in spec/formats/`);
+        else
+            skip(`Kaitai compilation of ${definitions} (${missing})`);
+        return;
+    }
+    const out = mkdtempSync(join(tmpdir(), "ksy-check-"));
+    const fixed = [...compiler.args, "--target", "python", "--outdir", out, "--import-path", fd];
+    try {
+        for (const batch of kaitaiBatches([compiler.cmd, ...fixed], ksys)) {
             try {
-                for (const batch of kaitaiBatches([compiler.cmd, ...fixed], ksys)) {
-                    try {
-                        runTool(compiler.cmd, [...fixed, ...batch]);
-                    }
-                    catch (err) {
-                        const failure = err;
-                        problem(null, `Kaitai definitions do not compile:\n${String(failure.stdout ?? "")}${String(failure.stderr ?? "")}`);
-                    }
-                }
+                runTool(compiler.cmd, [...fixed, ...batch]);
             }
-            finally {
-                rmSync(out, { recursive: true, force: true });
+            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))}`);
             }
         }
-        else if (ksys.length)
-            console.warn("warning: no Kaitai Struct compiler found (set KSC or install kaitai-struct-compiler); definitions were not compiled.");
+    }
+    finally {
+        rmSync(out, { recursive: true, force: true });
     }
 }
 // cmd.exe takes a command line of at most 8,191 characters, and the compiler's .bat launcher adds

package/dist/context.d.ts

@@ -1,5 +1,5 @@
 import type { Config } from "./options.ts";
-import type { Problem } from "./problems.ts";
+import type { Problem, Skip } 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 {
@@ -27,6 +27,8 @@ export interface LoadContext {
 }
 /** What every phase after the load needs. */
 export interface Context extends LoadContext {
+    /** Records a step of the check that did not run. */
+    skip: Skip;
     /** The spec as loaded. */
     spec: Spec;
     /** The files of the --code and --references directories, read on first use. */

package/dist/options.d.ts

@@ -8,6 +8,8 @@ export interface Config {
     checkOnly: boolean;
     /** --no-ksy: skip compiling the Kaitai definitions. */
     skipKsy: boolean;
+    /** --require-ksc: fail when there are Kaitai definitions and no compiler is found. */
+    requireKsc: boolean;
     /** --base, or null when it was not given. */
     baseArg: string | null;
     /** Every --glossary path, in order. */

package/dist/options.js

@@ -10,7 +10,7 @@ export const dirList = (value, fallback) => value === undefined
         .split(",")
         .map((x) => x.trim())
         .filter(Boolean);
-const FLAGS = ["--check", "--no-ksy"];
+const FLAGS = ["--check", "--no-ksy", "--require-ksc"];
 const VALUED = [
     "--root",
     "--base",
@@ -52,6 +52,11 @@ export function parseOptions(argv) {
         process.exit(2);
     }
     const skipKsy = options["no-ksy"] === true;
+    const requireKsc = options["require-ksc"] === true;
+    if (skipKsy && requireKsc) {
+        console.error("--require-ksc requires the Kaitai compilation that --no-ksy skips, so they cannot be combined");
+        process.exit(2);
+    }
     const baseArg = options.base ?? null;
     const codeRoots = dirList(options.code, ["src", "tests", "tools"]);
     const referenceRoots = dirList(options.references, []);
@@ -75,6 +80,7 @@ export function parseOptions(argv) {
         specDir,
         checkOnly,
         skipKsy,
+        requireKsc,
         baseArg,
         glossaryDrafts: options.glossary,
         codeRoots,

package/dist/problems.d.ts

@@ -12,15 +12,34 @@ export type Rule = `IDENTIFIERS-${UpTo<7>}` | `STATUS-${UpTo<41>}` | `ENTRY-TYPE
  * a numbered rule names it.
  */
 export type Problem = (file: string | null, message: string, rule?: Rule) => void;
+/**
+ * Records a step of the check that did not run, with the reason, such as "Kaitai compilation of 2
+ * definitions (--no-ksy)". The result line names every skipped step, so a pass never reads as a
+ * full check when part of it did not run. The line joins the steps with "; ", so a step's text
+ * must not contain "; ".
+ */
+export type Skip = (step: string) => void;
+/** What a run found, for the result line. */
+export interface Counts {
+    /** Spec entries. */
+    entries: number;
+    /** PARITY.md rows. */
+    parityRows: number;
+    /** Deviations. */
+    deviations: number;
+}
 /** The problem collector of one run. */
 export interface Problems {
     /** Records a problem. */
     problem: Problem;
+    /** Records a skipped step. */
+    skip: Skip;
     /**
-     * Prints every distinct problem in the order found, with the summary, and exits with 1. Returns
-     * when there are none.
+     * With problems, prints every distinct one in the order found, the summary and the skipped
+     * steps, and exits with 1. With none, prints the result line: "spec check passed: " and counts,
+     * or "spec check passed with skipped steps: " and counts followed by the skipped steps.
      */
-    report(entryCount: number): void;
+    report(counts: Counts): void;
 }
 /** Creates the collector for a run over repoDir, against which problem paths are printed. */
 export declare function createProblems(repoDir: string): Problems;

package/dist/problems.js

@@ -3,6 +3,7 @@ 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 = [];
+    const skipped = [];
     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.
@@ -11,17 +12,27 @@ export function createProblems(repoDir) {
             citedRule = true;
         problems.push(`${file ? relative(repoDir, file).replaceAll("\\", "/") : "spec"}: ${message}${rule ? ` [${rule}]` : ""}`);
     };
-    const report = (entryCount) => {
+    const skip = (step) => {
+        skipped.push(step);
+    };
+    const skippedLine = () => `Skipped: ${skipped.join("; ")}.`;
+    const report = ({ entries, parityRows, deviations }) => {
+        const counts = `${entries} entries, ${parityRows} parity rows, ${deviations} deviations.`;
         // 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.`);
+            console.error(`\n${unique.length} problem(s) in ${entries} 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.");
+            if (skipped.length)
+                console.error(skippedLine());
             process.exit(1);
         }
+        console.log(skipped.length
+            ? `spec check passed with skipped steps: ${counts} ${skippedLine()}`
+            : `spec check passed: ${counts}`);
     };
-    return { problem, report };
+    return { problem, skip, report };
 }

package/dist/standard-checker.js

@@ -10,7 +10,9 @@
 //   --check             fail when an index or PARITY.md is stale instead of rewriting it
 //   --base <ref>        also fail when an ID or area that exists at <ref> is gone (default: where
 //                       HEAD forked from origin/$GITHUB_BASE_REF or origin/main, when it resolves)
-//   --no-ksy            skip compiling the Kaitai definitions
+//   --no-ksy            skip compiling the Kaitai definitions; the result line names the skip
+//   --require-ksc       fail when spec/formats/ holds Kaitai definitions and no compiler is found,
+//                       instead of passing with the compilation skipped
 //   --glossary <path>   also accept the terms of a draft glossary file, or of a directory of them
 //   --code <dirs>       comma-separated directories whose files may cite spec and deviation IDs
 //                       and hold PLACEHOLDER comments (default: src,tests,tools)
@@ -36,7 +38,13 @@
 // [STATUS-4] for the rule whose heading is anchored at #status-4.
 //
 // The KSC environment variable names the Kaitai Struct compiler. Without it, the check looks for
-// kaitai-struct-compiler or ksc on PATH, and warns when it finds neither.
+// kaitai-struct-compiler or ksc on PATH. When it finds neither, the run skips the compilation and
+// says so in its result line, or fails with --require-ksc.
+//
+// It exits with 0 when the spec passes, 1 when it reports problems, and 2 when the options are
+// invalid. A pass prints "spec check passed: " and the counts, or, when a step did not run,
+// "spec check passed with skipped steps: " and the counts followed by "Skipped: " and each step
+// with its reason.
 //
 // No dependencies. The YAML reader understands the subset the standard's front matter uses:
 // scalars, flow lists, and block lists of flat maps.
@@ -78,11 +86,11 @@ if (argv.includes("--help") || argv.includes("-h")) {
     process.exit(0);
 }
 const config = parseOptions(argv);
-const { problem, report } = createProblems(config.repoDir);
+const { problem, skip, report } = createProblems(config.repoDir);
 const spec = loadSpec({ config, problem });
 // The checker's modules all sit in this file's directory, which holds nothing else, so the code
 // checks leave the whole directory out.
-const ctx = { config, problem, spec, codeFiles: createCodeFiles(config, dirname(selfPath)) };
+const ctx = { config, problem, skip, spec, codeFiles: createCodeFiles(config, dirname(selfPath)) };
 const formatNames = checkEntries(ctx);
 checkRules(ctx, formatNames);
 checkFieldNames(ctx, formatNames);
@@ -98,5 +106,4 @@ const generated = generateIndexes(ctx);
 generateParity(ctx, parity, generated);
 writeGenerated(ctx, generated);
 checkLineLimits(ctx);
-report(spec.entries.size);
-console.log(`spec check passed: ${spec.entries.size} entries, ${parity.rows.size} parity rows, ${deviations.size} deviations.`);
+report({ entries: spec.entries.size, parityRows: parity.rows.size, deviations: deviations.size });

package/package.json

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