@scientific-method/standard-checker 1.0.0 → 1.1.0

package/README.md

@@ -22,6 +22,14 @@ step of the check did not run, it ends with `spec check passed with skipped step
 `Skipped: Kaitai compilation of 2 definitions (--no-ksy).` A failing run lists the skipped steps
 after its problems.
 
+Without `--base`, the checker compares the spec with where HEAD forked from `origin/$GITHUB_BASE_REF`,
+or from `origin/main` when that variable is unset. Outside a git repository, in a shallow clone, or
+when that branch was never fetched, the fork point does not resolve and the comparison does not
+run. The result line then names it, such as `Skipped: comparison with the base branch (HEAD has no
+merge-base with origin/main, fetch it with enough history or pass --base).` Without git on `PATH`
+the skipped step names the missing git instead. With `--require-base`, either case is a problem and
+the run fails.
+
 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
 `#status-14` on the site and in the copies restorations vendor, so the rule can be read on its
@@ -34,7 +42,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, 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 |
+| `--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 does not resolve, the comparison is named as skipped |
+| `--require-base` | Fail when no `--base` is given and the fork point does not resolve, instead of passing with the comparison skipped. | pass with the comparison skipped |
 | `--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 |
@@ -63,7 +72,8 @@ prints a warning naming its path, with its output.
 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 then passes
 `--require-ksc`), and exposes every option
-above as an input. Pin the action to the toolkit commit whose `packages/standard-checker` matches
+above as an input. On a pull request with no `base` input, it fetches the base branch with enough
+history for the fork point and passes `--require-base`. 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.
 
 [The documentation standard check guide](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/documentation-standard-check.md)

package/dist/checks/base.d.ts

@@ -3,6 +3,7 @@ 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, 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.
+ * it had one at the base. Without --base, a fork point that does not resolve is recorded as a
+ * skipped step, or with --require-base reported as a problem.
  */
 export declare function checkBase(ctx: Context, deviations: Map<string, Deviation>): void;

package/dist/checks/base.js

@@ -6,15 +6,16 @@ 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, 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.
+ * it had one at the base. Without --base, a fork point that does not resolve is recorded as a
+ * skipped step, or with --require-base reported as a problem.
  */
 export function checkBase(ctx, deviations) {
-    const { problem } = ctx;
+    const { problem, skip } = ctx;
     const { entries, areas } = ctx.spec;
-    const { repoDir, baseArg } = ctx.config;
+    const { repoDir, baseArg, requireBase } = ctx.config;
     // Without --base, compare with the point this branch left the base branch (the pull request's
     // target in CI), not that branch's tip: an entry added on the base branch after this branch
-    // forked is not one this branch deleted.
+    // forked is not one this branch deleted. A base that resolves but cannot be listed is a problem.
     const git = (...args) => execFileSync("git", ["-C", repoDir, ...args], { stdio: ["ignore", "pipe", "ignore"] }).toString();
     let base = baseArg;
     if (!base) {
@@ -22,68 +23,75 @@ export function checkBase(ctx, deviations) {
         try {
             base = git("merge-base", "HEAD", target).trim();
         }
-        catch {
-            base = null;
+        catch (error) {
+            // Outside a git repository, in a shallow clone, or without the base branch fetched, there is
+            // no fork point, and the deleted-ID checks cannot run. The run says so instead of reading as
+            // a full check.
+            const missing = error.code === "ENOENT"
+                ? `git was not found to look up HEAD's merge-base with ${target}, install it or pass --base`
+                : `HEAD has no merge-base with ${target}, fetch it with enough history or pass --base`;
+            if (requireBase)
+                problem(null, `${missing}. --require-base requires the comparison with the base branch`);
+            else
+                skip(`comparison with the base branch (${missing})`);
+            return;
         }
     }
-    let listing = null;
-    if (base)
+    let listing;
+    try {
+        listing = git("ls-tree", "-r", "--name-only", base, "--", "spec", "deviations");
+    }
+    catch {
+        problem(null, `cannot list spec/ at ${base}`);
+        return;
+    }
+    for (const p of listing.split("\n")) {
+        const m = /^spec\/(?:builds|sources|formats|rules|findings|experiments|bugs|screens)\/([A-Z]+-[A-Z0-9.-]+)\.md$/.exec(p);
+        if (m && !entries.has(m[1]))
+            problem(null, `${m[1]} exists at ${base} and has been deleted or renamed`, "IDENTIFIERS-6");
+        const d = /^deviations\/(DEV-[A-Z0-9]+-\d+)\.md$/.exec(p);
+        if (d && !deviations.has(d[1]))
+            problem(null, `${d[1]} exists at ${base} and has been deleted or renamed`);
+    }
+    // ./ makes the path relative to --root, which need not be the top of the repository. A file
+    // that does not exist at the base has nothing to compare, and each is read on its own so a
+    // missing README does not skip the deviation comparison.
+    const show = (path) => {
         try {
-            listing = git("ls-tree", "-r", "--name-only", base, "--", "spec", "deviations");
+            return git("show", `${base}:./${path}`).replace(/\r\n/g, "\n");
         }
         catch {
-            if (baseArg)
-                problem(null, `cannot list spec/ at ${base}`);
+            return null;
         }
-    if (listing) {
-        for (const p of listing.split("\n")) {
-            const m = /^spec\/(?:builds|sources|formats|rules|findings|experiments|bugs|screens)\/([A-Z]+-[A-Z0-9.-]+)\.md$/.exec(p);
-            if (m && !entries.has(m[1]))
-                problem(null, `${m[1]} exists at ${base} and has been deleted or renamed`, "IDENTIFIERS-6");
-            const d = /^deviations\/(DEV-[A-Z0-9]+-\d+)\.md$/.exec(p);
-            if (d && !deviations.has(d[1]))
-                problem(null, `${d[1]} exists at ${base} and has been deleted or renamed`);
-        }
-        // ./ makes the path relative to --root, which need not be the top of the repository. A file
-        // that does not exist at the base has nothing to compare, and each is read on its own so a
-        // missing README does not skip the deviation comparison.
-        const show = (path) => {
-            try {
-                return git("show", `${base}:./${path}`).replace(/\r\n/g, "\n");
-            }
-            catch {
-                return null;
-            }
-        };
-        const oldReadme = show("spec/README.md");
-        // Reads the area table the way the current README is read, so areas with or without
-        // backticks are both found.
-        const oldAreaSection = oldReadme && splitSections(oldReadme).find((s) => s.title === "Areas");
-        const oldAreaTable = oldAreaSection && tables(oldAreaSection.text)[0];
-        for (const row of (oldAreaTable || undefined)?.rows ?? []) {
-            const a = row[0].replaceAll("`", "");
-            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)
-            for (const m of oldDev.matchAll(/^## (DEV-[A-Z0-9]+-\d+)$/gm))
-                if (!deviations.has(m[1]))
-                    problem(null, `${m[1]} exists at ${base} and has been removed`);
+    };
+    const oldReadme = show("spec/README.md");
+    // Reads the area table the way the current README is read, so areas with or without
+    // backticks are both found.
+    const oldAreaSection = oldReadme && splitSections(oldReadme).find((s) => s.title === "Areas");
+    const oldAreaTable = oldAreaSection && tables(oldAreaSection.text)[0];
+    for (const row of (oldAreaTable || undefined)?.rows ?? []) {
+        const a = row[0].replaceAll("`", "");
+        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)
+        for (const m of oldDev.matchAll(/^## (DEV-[A-Z0-9]+-\d+)$/gm))
+            if (!deviations.has(m[1]))
+                problem(null, `${m[1]} exists at ${base} and has been removed`);
 }

package/dist/options.d.ts

@@ -12,6 +12,8 @@ export interface Config {
     requireKsc: boolean;
     /** --base, or null when it was not given. */
     baseArg: string | null;
+    /** --require-base: fail when no --base is given and the base branch's fork point does not resolve. */
+    requireBase: boolean;
     /** Every --glossary path, in order. */
     glossaryDrafts: string[];
     /** The --code directories, relative to repoDir. */

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", "--require-ksc"];
+const FLAGS = ["--check", "--no-ksy", "--require-ksc", "--require-base"];
 const VALUED = [
     "--root",
     "--base",
@@ -82,6 +82,7 @@ export function parseOptions(argv) {
         skipKsy,
         requireKsc,
         baseArg,
+        requireBase: options["require-base"] === true,
         glossaryDrafts: options.glossary,
         codeRoots,
         referenceRoots,

package/dist/standard-checker.js

@@ -9,7 +9,10 @@
 //   --root <dir>        the repository to check (default: the current directory)
 //   --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)
+//                       HEAD forked from origin/$GITHUB_BASE_REF or origin/main; when that does not
+//                       resolve, the result line names the comparison as skipped)
+//   --require-base      fail when no --base is given and the fork point does not resolve, instead
+//                       of passing with the comparison skipped
 //   --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

package/package.json

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