paperlint 3.1.2 → 3.2.0

package/scripts/{check.harness.mjs → check.harness.ts}

@@ -7,7 +7,7 @@
  * and a suite-breaking change was pushed. Writing the subset down in a doc would have produced
  * the same outcome one release later — the list would simply have been wrong instead of absent.
  *
- * So the assertions below do not check that `check.mjs` contains the right strings. They pull
+ * So the assertions below do not check that `check.ts` contains the right strings. They pull
  * the job names OUT OF `.github/workflows/ci.yml` and require every one to be accounted for.
  * Add a job to CI and this goes red the same day, naming the job nobody covered.
  *
@@ -18,13 +18,50 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { load } from "js-yaml";
-import { createChecker } from "../lib/check.mjs";
+import { z } from "zod";
+import { createChecker } from "../lib/check.ts";
+import type { Gate } from "./check.ts";
+
+/** A workflow file, as far as these checks read it. `on` is a plain key: js-yaml reads YAML 1.2. */
+const Step = z.looseObject({
+  name: z.string().optional(),
+  run: z.string().optional(),
+  uses: z.string().optional(),
+});
+const Workflow = z.looseObject({
+  on: z
+    .looseObject({
+      pull_request: z
+        .looseObject({ types: z.array(z.string()).optional() })
+        .nullish(),
+    })
+    .optional(),
+  jobs: z
+    .record(
+      z.string(),
+      z.looseObject({
+        steps: z.array(Step).optional(),
+        strategy: z
+          .looseObject({
+            matrix: z
+              .looseObject({ os: z.array(z.string()).optional() })
+              .optional(),
+          })
+          .optional(),
+      }),
+    )
+    .optional(),
+});
+type Workflow = z.infer<typeof Workflow>;
+const PackageJson = z.looseObject({
+  scripts: z.record(z.string(), z.string()).optional(),
+});
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const ROOT = dirname(HERE);
 
 const { GATES, NOT_COVERED, outcome, SKIP_EXIT, commandOf } =
-  await import("./check.mjs");
+  await import("./check.ts");
 
 const check = createChecker();
 
@@ -34,7 +71,7 @@ const check = createChecker();
 // command red for anyone without pnpm or TeX, and it would be ignored.
 check("exit 0 is a pass", outcome(0) === "pass");
 check(
-  `exit ${SKIP_EXIT} is a skip — neither a pass nor a failure`,
+  `exit ${String(SKIP_EXIT)} is a skip — neither a pass nor a failure`,
   outcome(SKIP_EXIT) === "skip",
 );
 check("the skip code is the one vigiles' runner uses (77)", SKIP_EXIT === 77);
@@ -54,7 +91,10 @@ const WF_DIR = join(ROOT, ".github", "workflows");
 const workflows = Object.fromEntries(
   readdirSync(WF_DIR)
     .filter((f) => f.endsWith(".yml"))
-    .map((f) => [f, load(readFileSync(join(WF_DIR, f), "utf-8"))]),
+    .map((f) => [
+      f,
+      Workflow.parse(load(readFileSync(join(WF_DIR, f), "utf-8"))),
+    ]),
 );
 const ciJobs = Object.values(workflows).flatMap((wf) =>
   Object.keys(wf.jobs ?? {}),
@@ -67,7 +107,8 @@ check(
 // ── macOS: a cell of the TeX job, on every push ─────────────────────────────────────────
 // install-tl-unx must work there, and issue #9 appears there alone. The trigger used to be a
 // separate once-per-PR workflow; the repository is public, so the minutes are free.
-const prTypes = (wf) => wf.on?.pull_request?.types ?? [];
+const prTypes = (wf: Workflow | undefined): string[] =>
+  wf?.on?.pull_request?.types ?? [];
 const buildOs =
   workflows["ci.yml"]?.jobs?.["build-e2e"]?.strategy?.matrix?.os ?? [];
 check(
@@ -114,7 +155,9 @@ for (const job of Object.keys(NOT_COVERED)) {
 // A gate whose script or file was renamed fails at the moment someone runs it — which is
 // exactly the moment they are trusting it. Catch it here instead.
 const scripts =
-  JSON.parse(readFileSync(join(ROOT, "package.json"), "utf-8")).scripts ?? {};
+  PackageJson.parse(
+    JSON.parse(readFileSync(join(ROOT, "package.json"), "utf-8")),
+  ).scripts ?? {};
 for (const g of GATES) {
   check(
     `gate «${g.name}» says how to run it in exactly one way (script or run)`,
@@ -130,7 +173,7 @@ for (const g of GATES) {
   // A `run` gate names files and programs directly. Every file it names must be on disk, and
   // every program other than `node` must be installed in node_modules/.bin.
   const argv = commandOf(g);
-  const files = argv.filter((a) => /\.m?js$/.test(a));
+  const files = argv.filter((a) => /\.[cm]?[jt]s$/.test(a));
   const programs = [argv[0]];
   // Guards: a gate runs SOMETHING — a script of ours, or an installed program such as `tsc`.
   check(
@@ -159,6 +202,64 @@ for (const g of GATES.filter((g) => g.job === null)) {
   );
 }
 
+// ── HALF FIVE: the gate's command RUNS in the job it names ─────────────────────────────────
+// Half two proves the job exists; it does not prove the job runs the gate. `the tests type-check`
+// claimed `gates` for weeks while no step of that job ran tsc — the claim was the only coverage.
+// So each step's `run` is split into commands (lines, `&&`, `||`, `;`) and each command into
+// tokens, and the gate's own command has to be one of them: `npm run <script>` (flags and extra
+// arguments allowed) for a script gate, its argv (an `npx` in front and extra arguments allowed)
+// for a run gate. Tokens, not a substring: `npm run lint` must not be found inside
+// `npm run lint:skills`, nor a path inside a comment.
+const commandsIn = (run: string | undefined): string[][] =>
+  (run ?? "")
+    .split(/\n|&&|\|\||;/)
+    .map((c) => c.trim().split(/\s+/).filter(Boolean))
+    .filter((t) => t.length > 0);
+const stepsOf = (job: string) =>
+  Object.values(workflows).flatMap((wf) => wf.jobs?.[job]?.steps ?? []);
+const startsWith = (tokens: readonly string[], prefix: readonly string[]) =>
+  prefix.every((p, i) => tokens[i] === p);
+const runsGate = (tokens: readonly string[], g: Gate): boolean => {
+  if (g.script)
+    return (
+      tokens[0] === "npm" &&
+      tokens[1] === "run" &&
+      tokens.slice(2).find((t) => !t.startsWith("-")) === g.script
+    );
+  const argv = commandOf(g);
+  return (
+    startsWith(tokens, argv) ||
+    (tokens[0] === "npx" && startsWith(tokens.slice(1), argv))
+  );
+};
+for (const g of GATES) {
+  if (g.job === null) continue;
+  const steps = stepsOf(g.job);
+  const { inCi } = g;
+  if (inCi) {
+    // A gate CI runs as a side effect of another step, through an npm lifecycle script: the step
+    // it names must exist in the job and install the package (npm runs lifecycle scripts there),
+    // and the lifecycle script must be the gate's own command, so the two cannot drift apart.
+    const step = steps.find((s) => s.name === inCi.step);
+    const tokens = commandsIn(step?.run)[0] ?? [];
+    check(
+      `gate «${g.name}» runs in CI job «${g.job}» through step «${inCi.step}», whose ${inCi.lifecycle} script is the gate's command`,
+      step !== undefined &&
+        tokens[0] === "npm" &&
+        ["ci", "install"].includes(tokens[1] ?? "") &&
+        typeof scripts[g.script] === "string" &&
+        scripts[inCi.lifecycle] === scripts[g.script],
+      JSON.stringify({ run: step?.run, lifecycle: scripts[inCi.lifecycle] }),
+    );
+    continue;
+  }
+  check(
+    `gate «${g.name}» runs its command (${commandOf(g).join(" ")}) in a step of CI job «${g.job}»`,
+    steps.some((s) => commandsIn(s.run).some((t) => runsGate(t, g))),
+    steps.map((s) => s.run ?? `(uses ${String(s.uses)})`).join(" | "),
+  );
+}
+
 // ── and the tail is not optional ───────────────────────────────────────────────────────────
 check(
   "NOT_COVERED is non-empty — if it ever is, either CI shrank or someone silenced the tail",
@@ -166,6 +267,6 @@ check(
 );
 
 console.log(
-  `✓ ${String(check.count)} assertions passed — npm run check: ${GATES.length} gates, ` +
-    `${ciJobs.length} CI job(s) all accounted for`,
+  `✓ ${String(check.count)} assertions passed — npm run check: ${String(GATES.length)} gates, ` +
+    `${String(ciJobs.length)} CI job(s) all accounted for`,
 );

package/scripts/{check.test.mjs → check.test.ts}

@@ -1,21 +1,24 @@
 /**
- * check.mjs's runGates — the one command run before a push — on every outcome, with an injected
+ * check.ts's runGates — the one command run before a push — on every outcome, with an injected
  * spawn: a pass, a declared skip (77) and a failure, and THE TAIL that names what it does not cover.
  */
 import assert from "node:assert/strict";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { test } from "vitest";
-import { GATES, NOT_COVERED, runGates } from "./check.mjs";
+import { GATES, NOT_COVERED, runGates, type Gate } from "./check.ts";
 
 const capture = () => {
-  const out = [];
-  const io = { log: (s) => out.push(s), err: (s) => out.push(`E ${s}`) };
+  const out: string[] = [];
+  const io = {
+    log: (s: string) => out.push(s),
+    err: (s: string) => out.push(`E ${s}`),
+  };
   return { out, io };
 };
 
 test("runGates: a pass, a declared skip (77) and a failure, then the tail naming what is not covered", () => {
-  const gates = [
+  const gates: Gate[] = [
     { name: "passes", job: "gates", run: ["true"] },
     { name: "skips", job: "gates", run: ["skipper", "--x"] },
     {
@@ -25,12 +28,12 @@ test("runGates: a pass, a declared skip (77) and a failure, then the tail naming
       run: ["false"],
     },
   ];
-  const status = { true: 0, skipper: 77, false: 3 };
-  const written = [];
+  const status: Record<string, number> = { true: 0, skipper: 77, false: 3 };
+  const written: string[] = [];
   const { out, io } = capture();
   const code = runGates({
     gates,
-    spawn: (cmd) => ({ status: status[cmd] }),
+    spawn: (cmd) => ({ status: status[cmd] ?? null }),
     write: (s) => written.push(s),
     ...io,
   });
@@ -79,7 +82,7 @@ test("runGates: all passing, with a skip, says how many passed and that the skip
 });
 
 test("run as a program with every gate passing: the plain verdict, exit 0", () => {
-  // spawnSync is replaced before check.mjs loads, so the real file runs end to end — every gate
+  // spawnSync is replaced before check.ts loads, so the real file runs end to end — every gate
   // "passes" in microseconds instead of the eleven real ones running.
   const allPass = [
     'import cp from "node:child_process";',
@@ -92,7 +95,7 @@ test("run as a program with every gate passing: the plain verdict, exit 0", () =
     [
       "--import",
       `data:text/javascript,${encodeURIComponent(allPass)}`,
-      fileURLToPath(new URL("./check.mjs", import.meta.url)),
+      fileURLToPath(new URL("./check.ts", import.meta.url)),
     ],
     { encoding: "utf8" },
   );

package/scripts/{check.mjs → check.ts}

@@ -19,7 +19,7 @@
  * boundary reads as complete, which is the same class as a counter that counts what it ignores.
  *
  * ── WHAT KEEPS THE LIST FROM GOING STALE ───────────────────────────────────────────────────
- * `check.harness.mjs` sits beside it and pulls the job names OUT OF THE WORKFLOW ITSELF,
+ * `check.harness.ts` sits beside it and pulls the job names OUT OF THE WORKFLOW ITSELF,
  * requiring every one to be either covered here or named in `NOT_COVERED` with a reason. Add a
  * job to CI and the harness goes red the same day — the list cannot quietly fall behind.
  *
@@ -53,11 +53,63 @@ const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
  * Programs installed by npm (`vigiles`, `eslint`) are found because `node_modules/.bin` is put
  * first on PATH below, the same way `npm run` does it.
  */
-export const GATES = [
+/**
+ * How CI runs a gate that has no step of its own: the step that runs it as a side effect, and the
+ * npm lifecycle script through which it does. `check.harness.ts` requires that step in the job
+ * and that lifecycle script to be the gate's own command, so the two cannot drift apart.
+ */
+export interface RunInCi {
+  readonly step: string;
+  readonly lifecycle: "prepare";
+}
+
+/**
+ * A gate runs either an npm script or a command of its own — never both. Only an npm script can be
+ * run by CI through a lifecycle script (`inCi`); every other gate has a step that runs its command.
+ */
+type GateCommand =
+  | {
+      readonly script: string;
+      readonly run?: undefined;
+      readonly inCi?: RunInCi;
+    }
+  | {
+      readonly run: readonly [string, ...string[]];
+      readonly script?: undefined;
+      readonly inCi?: undefined;
+    };
+
+/**
+ * A gate reproduces a CI job, or runs only here and says why (`job: null` needs a `reason`, or it
+ * becomes the quiet way to drop something out of CI).
+ */
+export type Gate = { readonly name: string } & GateCommand &
+  (
+    | { readonly job: string; readonly reason?: undefined }
+    | { readonly job: null; readonly reason: string }
+  );
+
+/** What `runGates` needs from a finished process: its exit status, `null` when a signal ended it. */
+export type Spawn = (
+  cmd: string,
+  args: readonly string[],
+  options: {
+    cwd: string;
+    stdio: "inherit";
+    encoding: "utf8";
+    env: NodeJS.ProcessEnv;
+  },
+) => { readonly status: number | null };
+
+export type Outcome = "pass" | "skip" | "fail";
+
+export const GATES: readonly Gate[] = [
   {
     name: "the package compiles",
     job: "gates",
     script: "build",
+    // CI has no `npm run build` step: `npm ci` runs `prepare`, which is `tsc` as well.
+    inCi: { step: "npm ci", lifecycle: "prepare" },
     // First because everything below imports from `dist/`. A stale build makes every later
     // failure a lie about its own cause.
   },
@@ -86,17 +138,6 @@ export const GATES = [
     job: "gates",
     run: ["node", "scripts/rules-see-files.mjs"],
   },
-  {
-    name: "rules read content, not the filesystem",
-    job: null,
-    // 🔴 Deliberately not in CI, and this is the one asymmetry worth stating rather than
-    // hiding: the check is about a property of the rules' source, which cannot change between
-    // a developer's tree and the runner's. Running it twice buys nothing; NOT running it
-    // locally buys a defect that reaches review.
-    reason:
-      "source-only property — identical in every environment, so CI adds nothing",
-    run: ["node", "scripts/rules-are-content-only.mjs"],
-  },
   {
     name: "every test, under coverage — vitest, then the vigiles harnesses, with c8's thresholds (npm run coverage)",
     job: "gates",
@@ -114,40 +155,42 @@ export const GATES = [
   {
     name: "legacy layer exemptions are frozen — none new, none grown (#76)",
     job: "gates",
-    run: ["node", "scripts/layer-legacy-frozen.mjs"],
+    run: ["node", "scripts/layer-legacy-frozen.ts"],
   },
   {
     name: "install e2e — pack, install under npm and pnpm, run the binary",
     job: "gates",
-    run: ["node", "test/e2e/install.mjs"],
+    run: ["node", "test/e2e/install.ts"],
   },
   {
     name: "build e2e — a real pdflatex, and the PDF's fonts are measured",
     job: "build-e2e",
-    run: ["node", "test/e2e/build.mjs"],
+    run: ["node", "test/e2e/build.ts"],
   },
   {
     name: "banal e2e — the real banal on pdf.js-written XML gives banal-on-pdftohtml's numbers",
     job: "build-e2e",
-    run: ["node", "test/e2e/banal.mjs"],
+    run: ["node", "test/e2e/banal.ts"],
   },
   {
     name: "toolchain e2e — real TeX Live into $PAPERLINT_TEXLIVE_DIR, then a build with only it on PATH",
     job: "build-e2e",
-    run: ["node", "test/e2e/toolchain.mjs"],
+    run: ["node", "test/e2e/toolchain.ts"],
   },
 ];
 
 /** The command line a gate runs, as an argument list. */
-export function commandOf(gate) {
-  return gate.script ? ["npm", "run", "-s", gate.script] : gate.run;
+export function commandOf(gate: Gate): readonly [string, ...string[]] {
+  return gate.script !== undefined
+    ? ["npm", "run", "-s", gate.script]
+    : gate.run;
 }
 
 /**
  * CI jobs this command does NOT reproduce. Each needs a reason a reader can check, because an
  * unexplained gap is indistinguishable from an oversight — which is what the harness enforces.
  */
-export const NOT_COVERED = {
+export const NOT_COVERED: Readonly<Record<string, string>> = {
   // build-e2e's macOS cell is the one part of a covered job no local command can stand in for:
   // it exists because issue #9 appeared on macOS alone (/var is a symlink to /private/var).
   merge:
@@ -169,31 +212,30 @@ export const NOT_COVERED = {
  * this loop counted that as a pass, and `skipped` below was declared and never filled: a machine
  * without pnpm or TeX printed "all gates passed" for runs that never happened.
  */
-export const SKIP_EXIT = 77;
-export function outcome(status) {
+export const SKIP_EXIT: number = 77;
+export function outcome(status: number | null): Outcome {
   if (status === 0) return "pass";
   if (status === SKIP_EXIT) return "skip";
   return "fail";
 }
 
-/**
- * Run every gate in order and print the verdict and THE TAIL. `spawn`, `log`, `err` and `write`
- * are injected so a test can drive every outcome without running eleven real gates.
- *
- * @returns the exit code: 1 when a gate failed, else 0 (a skip is not a failure, and says so).
- */
-export function runGates({
-  gates = GATES,
-  spawn = spawnSync,
-  log = console.log,
-  err = console.error,
-  write = (s) => process.stdout.write(s),
-} = {}) {
+/** The gates that did not pass, each as the line the verdict prints, split by outcome. */
+interface NotPassed {
+  failed: string[];
+  skipped: string[];
+}
+
+/** Run each gate in order; `write` announces it before it starts. */
+function runEach(
+  gates: readonly Gate[],
+  spawn: Spawn,
+  write: (text: string) => unknown,
+): NotPassed {
   const BIN_FIRST_PATH = [join(ROOT, "node_modules", ".bin"), process.env.PATH]
     .filter(Boolean)
     .join(delimiter);
-  const failed = [];
-  const skipped = [];
+  const failed: string[] = [];
+  const skipped: string[] = [];
 
   for (const g of gates) {
     write(`── ${g.name}\n`);
@@ -210,10 +252,19 @@ export function runGates({
     const o = outcome(r.status);
     if (o === "pass") continue;
     const shown = commandOf(g).join(" ");
-    if (o === "skip") skipped.push(`${g.name}  (${shown} → ${SKIP_EXIT})`);
-    else failed.push(`${g.name}  (${shown} → ${r.status})`);
+    if (o === "skip")
+      skipped.push(`${g.name}  (${shown} → ${String(SKIP_EXIT)})`);
+    else failed.push(`${g.name}  (${shown} → ${String(r.status)})`);
   }
+  return { failed, skipped };
+}
 
+/** The verdict, then THE TAIL. */
+function report(
+  gates: readonly Gate[],
+  { failed, skipped }: NotPassed,
+  { log, err }: { log: (line: string) => void; err: (line: string) => void },
+): void {
   log("");
   if (failed.length) {
     err("🔴 gates failed:");
@@ -221,7 +272,7 @@ export function runGates({
   } else {
     const passed = gates.length - skipped.length;
     log(
-      `✓ ${passed} gate(s) passed${skipped.length ? `, ${skipped.length} SKIPPED — not run, not passed` : ""}`,
+      `✓ ${String(passed)} gate(s) passed${skipped.length ? `, ${String(skipped.length)} SKIPPED — not run, not passed` : ""}`,
     );
   }
   for (const s of skipped) log(`⏳ skipped: ${s}`);
@@ -234,7 +285,30 @@ export function runGates({
   for (const g of gates.filter((x) => x.job === null)) {
     log(`  (and «${g.name}» runs ONLY here — ${g.reason})`);
   }
-  return failed.length ? 1 : 0;
+}
+
+/**
+ * Run every gate in order and print the verdict and THE TAIL. `spawn`, `log`, `err` and `write`
+ * are injected so a test can drive every outcome without running eleven real gates.
+ *
+ * @returns the exit code: 1 when a gate failed, else 0 (a skip is not a failure, and says so).
+ */
+export function runGates({
+  gates = GATES,
+  spawn = spawnSync,
+  log = console.log,
+  err = console.error,
+  write = (s: string) => process.stdout.write(s),
+}: {
+  gates?: readonly Gate[];
+  spawn?: Spawn;
+  log?: (line: string) => void;
+  err?: (line: string) => void;
+  write?: (text: string) => unknown;
+} = {}): number {
+  const notPassed = runEach(gates, spawn, write);
+  report(gates, notPassed, { log, err });
+  return notPassed.failed.length ? 1 : 0;
 }
 
 if (isMain(import.meta.url)) process.exit(runGates());