paperlint 3.1.3 → 4.0.0

package/src/references.test.ts

@@ -9,10 +9,11 @@
  */
 import { describe, expect, it } from "vitest";
 import { ESLint } from "eslint";
+import { eslintConfig } from "./cli.ts";
 import { join } from "node:path";
 import { memoryFiles } from "./adapters/memory/index.ts";
 import { ok } from "./domain/result.ts";
-import type { AbsolutePath } from "./domain/paths.ts";
+import { absolutePath } from "./domain/paths.ts";
 import type {
   CheckReferences,
   EntryVerdict,
@@ -32,8 +33,8 @@ import {
   type LookupCache,
 } from "./domain/lookup-cache.ts";
 import { referenceRules, REFERENCE_RULE_LEVELS } from "./reference-rules.ts";
-// @ts-expect-error — an ESLint language in .mjs, it has no types
-import { texLanguage } from "../eslint-rules/latex-language.mjs";
+import { texLanguage } from "../eslint-rules/latex-language.ts";
+import { present } from "../test/support.ts";
 
 const PAPER = "/work/papers/p";
 const TEX = (entries: string) =>
@@ -63,22 +64,28 @@ const verdict = (
 
 const checker =
   (entries: readonly EntryVerdict[]): CheckReferences =>
-  async (_bib, cache) => ({ check: { kind: "checked", entries }, cache });
-const offline: CheckReferences = async (_bib, cache) => ({
-  check: {
-    kind: "not-checked",
-    why: "the citation services cannot be reached (fetch failed)",
-  },
-  cache,
-});
+  (_bib, cache) =>
+    Promise.resolve({ check: { kind: "checked", entries }, cache });
+const offline: CheckReferences = (_bib, cache) =>
+  Promise.resolve({
+    check: {
+      kind: "not-checked",
+      why: "the citation services cannot be reached (fetch failed)",
+    },
+    cache,
+  });
 
 /** The step's context over `files`, with every port it does not use stubbed. */
 const ctx = (files: ReturnType<typeof memoryFiles>) => ({
   paperDir: PAPER,
   env: {},
-  run: (() => ({})) as never,
-  readPdf: (() => null) as never,
-  measure: (() => null) as never,
+  run: () => ({ status: 0 }),
+  readPdf: () => Promise.reject(new Error("the references step reads no PDF")),
+  measure: {
+    measure: () => {
+      throw new Error("the references step measures nothing");
+    },
+  },
   files,
 });
 
@@ -92,37 +99,31 @@ async function build(tex: string, check: CheckReferences) {
   return { files, out };
 }
 
-/**
- * The rules as an ESLint plugin. Their context type is the narrow one they read (a custom
- * language's SourceCode), which ESLint's JS-centred plugin type does not describe.
- */
-const asPlugin = (rules: object): ESLint.Plugin => ({ rules }) as ESLint.Plugin;
-
 /** Lint `tex` as the paper's paper.tex against what `files` recorded. */
 async function lint(files: ReturnType<typeof memoryFiles>, tex: string) {
   files.writeAtomic(
-    `${PAPER}/paper.tex` as AbsolutePath,
+    absolutePath(`${PAPER}/paper.tex`),
     new TextEncoder().encode(tex),
   );
   const eslint = new ESLint({
     cwd: "/work",
     overrideConfigFile: true,
-    overrideConfig: [
+    overrideConfig: eslintConfig([
       {
         files: ["**/paper.tex"],
         plugins: {
           tex: { languages: { latex: texLanguage } },
-          paper: asPlugin(referenceRules({ files })),
+          paper: { rules: referenceRules({ files }) },
         },
         language: "tex/latex",
         rules: REFERENCE_RULE_LEVELS,
       },
-    ],
+    ]),
   });
   const [res] = await eslint.lintText(tex, {
     filePath: join(PAPER, "paper.tex"),
   });
-  return res!.messages;
+  return present(res, "one lint result").messages;
 }
 
 describe("the references build step", () => {
@@ -135,7 +136,9 @@ describe("the references build step", () => {
     expect(out.ok).toBe(true);
     const doc = readReferences(files, PAPER);
     expect(doc?.status).toBe("checked");
-    expect(doc?.bib.sha256).toBe(bibHash(bibliographyOf(files, PAPER)!));
+    expect(doc?.bib.sha256).toBe(
+      bibHash(present(bibliographyOf(files, PAPER), "the bibliography")),
+    );
     expect(await lint(files, tex)).toEqual([]);
   });
 
@@ -148,13 +151,13 @@ describe("the references build step", () => {
     expect(msgs.map((m) => [m.ruleId, m.severity])).toEqual([
       ["paper/refs-checked", 1],
     ]);
-    expect(msgs[0]!.message).toMatch(/cannot be reached/);
+    expect(msgs[0]?.message).toMatch(/cannot be reached/);
   });
 
   it("a checker that throws is recorded as not checked, not as a failed build", async () => {
-    const { files, out } = await build(TEX(ENTRIES), async () => {
-      throw new Error("DBLP exploded");
-    });
+    const { files, out } = await build(TEX(ENTRIES), () =>
+      Promise.reject(new Error("DBLP exploded")),
+    );
     expect(out.ok).toBe(true);
     expect(readReferences(files, PAPER)?.why).toMatch(/DBLP exploded/);
   });
@@ -167,9 +170,9 @@ const ANSWER: CachedResponse = {
 /** A checker that fetches `key` unless the cache has it, recording the cache it was handed. */
 function fetching(key: string) {
   const seen: LookupCache[] = [];
-  const check: CheckReferences = async (_bib, cache) => {
+  const check: CheckReferences = (_bib, cache) => {
     seen.push(cache);
-    return {
+    return Promise.resolve({
       check: { kind: "checked", entries: [verdict("schick2023")] },
       cache: cache.citations.has(key)
         ? cache
@@ -177,12 +180,12 @@ function fetching(key: string) {
             citations: new Map([...cache.citations, [key, ANSWER]]),
             dblp: cache.dblp,
           },
-    };
+    });
   };
   return { check, seen };
 }
 const cacheText = (files: ReturnType<typeof memoryFiles>): string | null => {
-  const b = files.readBytes(lookupCachePath(PAPER) as AbsolutePath);
+  const b = files.readBytes(absolutePath(lookupCachePath(PAPER)));
   return b === null ? null : new TextDecoder().decode(b);
 };
 
@@ -210,23 +213,26 @@ describe("the lookup cache — <paper>/repro/references-cache.json", () => {
       note: "references: 1 checked, 0 failing → _build/references.json; nothing fetched",
     });
     // The second build was handed exactly what the first one wrote.
-    expect(parseLookupCache(written!)).toEqual(ok(f.seen[1]));
+    expect(parseLookupCache(present(written, "the written cache"))).toEqual(
+      ok(f.seen[1]),
+    );
     expect(cacheText(files)).toBe(written);
   });
 });
 
 describe("the lookup cache — counting and refusing", () => {
   it("two new answers are counted as two", async () => {
-    const two: CheckReferences = async (_bib, cache) => ({
-      check: { kind: "checked", entries: [verdict("schick2023")] },
-      cache: {
-        citations: new Map([
-          ["a", ANSWER],
-          ["b", ANSWER],
-        ]),
-        dblp: cache.dblp,
-      },
-    });
+    const two: CheckReferences = (_bib, cache) =>
+      Promise.resolve({
+        check: { kind: "checked", entries: [verdict("schick2023")] },
+        cache: {
+          citations: new Map([
+            ["a", ANSWER],
+            ["b", ANSWER],
+          ]),
+          dblp: cache.dblp,
+        },
+      });
     const { out } = await build(TEX(ENTRIES), two);
     expect(out).toEqual({
       ok: true,
@@ -271,8 +277,8 @@ describe("the reference rules", () => {
     );
     const msgs = await lint(files, tex);
     expect(msgs.map((m) => m.ruleId)).toEqual(["paper/author-list"]);
-    expect(msgs[0]!.line).toBe(3);
-    expect(msgs[0]!.message).toMatch(/`schick2023`.*missing hambro/);
+    expect(msgs[0]?.line).toBe(3);
+    expect(msgs[0]?.message).toMatch(/`schick2023`.*missing hambro/);
   });
 
   it("an identifier that provably fails → paper/cite-exists on that entry", async () => {
@@ -311,7 +317,7 @@ describe("the reference rules", () => {
     const files = memoryFiles({});
     const msgs = await lint(files, TEX(ENTRIES));
     expect(msgs.map((m) => m.ruleId)).toEqual(["paper/refs-checked"]);
-    expect(msgs[0]!.message).toMatch(/npx paperlint build/);
+    expect(msgs[0]?.message).toMatch(/npx paperlint build/);
   });
 
   it("a paper with no bibliography gets nothing", async () => {
@@ -354,9 +360,9 @@ const record = (
   files: ReturnType<typeof memoryFiles>,
   body: Record<string, unknown>,
 ) => {
-  const bib = bibliographyOf(files, PAPER)!;
+  const bib = present(bibliographyOf(files, PAPER), "the bibliography");
   files.writeAtomic(
-    referencesPath(PAPER) as AbsolutePath,
+    absolutePath(referencesPath(PAPER)),
     new TextEncoder().encode(
       JSON.stringify({
         schema: 1,
@@ -374,7 +380,7 @@ describe("the reference rules over a record written by hand", () => {
     record(files, { status: "not-checked", entries: [] });
     const msgs = await lint(files, tex);
     expect(msgs.map((m) => m.ruleId)).toEqual(["paper/refs-checked"]);
-    expect(msgs[0]!.message).toMatch(/no reason recorded/);
+    expect(msgs[0]?.message).toMatch(/no reason recorded/);
   });
 
   it("a verdict without a reason, and one for a key the bibliography lacks, still report", async () => {
@@ -410,16 +416,23 @@ describe("the reference rules over refs.bib, and on other files", () => {
     expect(msgs.map((m) => [m.ruleId, m.line])).toEqual([
       ["paper/author-list", 1],
     ]);
-    expect(msgs[0]!.message).toMatch(/schick2023/);
+    expect(msgs[0]?.message).toMatch(/schick2023/);
   });
 
   it("only paper.tex is judged", () => {
     const files = memoryFiles({});
     const rules = referenceRules({ files });
     for (const rule of Object.values(rules))
-      expect(rule.create({ filename: `${PAPER}/notes.tex` } as never)).toEqual(
-        {},
-      );
+      expect(
+        rule.create({
+          filename: `${PAPER}/notes.tex`,
+          cwd: "/work",
+          sourceCode: { getLocFromIndex: () => ({ line: 1, column: 0 }) },
+          report: () => {
+            throw new Error("a file that is not paper.tex is never reported");
+          },
+        }),
+      ).toEqual({});
   });
 });
 
@@ -430,13 +443,14 @@ describe("the lookup cache — refreshed answers", () => {
     const OLD: CachedResponse = { ...ANSWER, fetched: "2026-08-01" };
     const put =
       (answer: CachedResponse): CheckReferences =>
-      async (_bib, cache) => ({
-        check: { kind: "checked", entries: [verdict("schick2023")] },
-        cache: {
-          citations: new Map([...cache.citations, ["a", answer]]),
-          dblp: cache.dblp,
-        },
-      });
+      (_bib, cache) =>
+        Promise.resolve({
+          check: { kind: "checked", entries: [verdict("schick2023")] },
+          cache: {
+            citations: new Map([...cache.citations, ["a", answer]]),
+            dblp: cache.dblp,
+          },
+        });
     const { files } = await build(TEX(ENTRIES), put(OLD));
     const again = await referencesStep.run({
       ...ctx(files),

package/src/references.ts

@@ -28,7 +28,7 @@
  * a pass would be the counter that counts what it never looked at.
  */
 import { join } from "node:path";
-import type { AbsolutePath } from "./domain/paths.ts";
+import { callerPath } from "./caller-path.ts";
 import { sha256Hex } from "./domain/sha256.ts";
 import type { Files } from "./ports/files.ts";
 import {
@@ -44,8 +44,8 @@ import type {
   ReferencesCheck,
   ReferencesRun,
 } from "./ports/check-references.ts";
-// @ts-expect-error — an ESLint rule module in .mjs, it has no types
-import { bibRange } from "../eslint-rules/paper-typography.mjs";
+import { bibRange } from "#eslint-rules/paper-typography";
+import { messageOf } from "./domain/text.ts";
 
 export const REFERENCES_SCHEMA = 1;
 export const REFERENCES_FILE = "references.json";
@@ -60,9 +60,8 @@ export const lookupCachePath = (paperDir: string): string =>
 export const referencesPath = (paperDir: string): string =>
   join(paperDir, "_build", REFERENCES_FILE);
 
-const at = (p: string): AbsolutePath => p as AbsolutePath;
 const text = (files: Files, p: string): string | null => {
-  const b = files.readBytes(at(p));
+  const b = files.readBytes(callerPath(p));
   return b === null ? null : new TextDecoder().decode(b);
 };
 
@@ -109,6 +108,15 @@ export const documentOf = (
     : { status: "not-checked" as const, why: check.why, entries: [] }),
 });
 
+/** A parsed `references.json` of this schema, its entries a list. */
+const isReferencesDocument = (d: unknown): d is ReferencesDocument =>
+  typeof d === "object" &&
+  d !== null &&
+  "schema" in d &&
+  d.schema === REFERENCES_SCHEMA &&
+  "entries" in d &&
+  Array.isArray(d.entries);
+
 /** The recorded verdicts, or null when there are none or they do not parse. */
 export function readReferences(
   files: Files,
@@ -117,10 +125,8 @@ export function readReferences(
   const raw = text(files, referencesPath(paperDir));
   if (raw === null) return null;
   try {
-    const d = JSON.parse(raw) as ReferencesDocument;
-    return d?.schema === REFERENCES_SCHEMA && Array.isArray(d.entries)
-      ? d
-      : null;
+    const d: unknown = JSON.parse(raw);
+    return isReferencesDocument(d) ? d : null;
   } catch {
     return null;
   }
@@ -159,7 +165,7 @@ async function run(
   try {
     return await check(bib, cache);
   } catch (e) {
-    return { check: { kind: "not-checked", why: (e as Error).message }, cache };
+    return { check: { kind: "not-checked", why: messageOf(e) }, cache };
   }
 }
 
@@ -179,7 +185,7 @@ export async function recordReferences(
   const record = (c: ReferencesCheck): ReferencesDocument => {
     const doc = documentOf(bib, c);
     files.writeAtomic(
-      at(referencesPath(paperDir)),
+      callerPath(referencesPath(paperDir)),
       new TextEncoder().encode(`${JSON.stringify(doc, null, 2)}\n`),
     );
     return doc;
@@ -199,7 +205,7 @@ export async function recordReferences(
   const fetched = newAnswers(cache.value, result.cache);
   if (fetched > 0)
     files.writeAtomic(
-      at(lookupCachePath(paperDir)),
+      callerPath(lookupCachePath(paperDir)),
       new TextEncoder().encode(serializeLookupCache(result.cache)),
     );
   const bad = doc.entries.filter(

package/src/{rules-config.harness.mjs → rules-config.harness.ts}

@@ -3,24 +3,18 @@
  * paperlint ships. The end-to-end path (a project's paperlint.json → `paperlint lint`) is in `cli.harness.mjs`;
  * this pins the parser's output shape and each refusal.
  */
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { createChecker } from "../lib/check.mjs";
+import { createChecker } from "../lib/check.ts";
 
-const HERE = dirname(fileURLToPath(import.meta.url));
-const { parseRuleBlocks, shippedRuleIds, unknownKeys } = await import(
-  join(HERE, "rules-config.ts")
-);
+const { parseRuleBlocks, shippedRuleIds, unknownKeys } =
+  await import("./rules-config.ts");
 
 const check = createChecker();
 
 const SHIPPED = new Set(["pdf/last-page-balance", "paper/typography"]);
-const parse = (raw) => parseRuleBlocks(raw, "S", SHIPPED, "/consumer");
+const parse = (raw: unknown) => parseRuleBlocks(raw, "S", SHIPPED, "/consumer");
 
-check(
-  "no `rules` key: no blocks",
-  parse(undefined).ok && parse(undefined).value.length === 0,
-);
+const none = parse(undefined);
+check("no `rules` key: no blocks", none.ok && none.value.length === 0);
 {
   const r = parse([
     {
@@ -62,7 +56,7 @@ check(
   parse([{ rules: { "paper/typography": 0, "pdf/last-page-balance": "warn" } }])
     .ok,
 );
-const refusals = [
+const refusals: [unknown, string][] = [
   ["pdf/last-page-balance", 'S → "rules" must be { "<rule>": "<severity>" }'],
   [{ a: 1 }, '"a" is not a rule paperlint ships'],
   [[42], "S → rules[0] must be an object"],

package/src/rules-config.ts

@@ -25,7 +25,7 @@
  * would need that plugin, which JSON cannot carry. Which rules paperlint ships is read off its own
  * config (`buildConfig`), not listed a second time.
  */
-import { SETTINGS_KEYS } from "../lib/paper-config.mjs";
+import { SETTINGS_KEYS } from "#lib/paper-config";
 
 /** ESLint's severities, in both of its spellings. */
 export type Severity = "off" | "warn" | "error" | 0 | 1 | 2;
@@ -39,11 +39,40 @@ export interface RuleBlock {
   readonly rules: Readonly<Record<string, RuleEntry>>;
 }
 
+/**
+ * A plugin as a config block registers it, typed to what paperlint reads of it: its rules, and the
+ * languages it brings (`tex` brings LaTeX).
+ */
+export interface ConfigPlugin {
+  readonly rules?: Readonly<Record<string, unknown>>;
+  readonly languages?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * An ESLint config block as paperlint builds and reads one. Not `Linter.Config`: ESLint types a
+ * plugin's rule as one that runs on ANY language, and paperlint's rules are written for the language
+ * they read (LaTeX, markdown), so none of them is assignable to it. ESLint checks a block when it
+ * loads it; `eslintConfig` in cli.ts is the one place these blocks become `Linter.Config`.
+ */
+export interface ConfigBlock {
+  readonly name?: string;
+  readonly basePath?: string;
+  readonly files?: readonly (string | readonly string[])[];
+  readonly ignores?: readonly string[];
+  readonly plugins?: Readonly<Record<string, ConfigPlugin>>;
+  readonly language?: string;
+  readonly languageOptions?: Readonly<Record<string, unknown>>;
+  readonly linterOptions?: Readonly<Record<string, unknown>>;
+  readonly rules?: Readonly<Record<string, unknown>>;
+}
+
 export type Parsed<T> =
   | { readonly ok: true; readonly value: T }
   | { readonly ok: false; readonly error: string };
 
-const SEVERITIES: readonly unknown[] = ["off", "warn", "error", 0, 1, 2];
+const SEVERITIES: readonly Severity[] = ["off", "warn", "error", 0, 1, 2];
+const isSeverity = (v: unknown): v is Severity =>
+  SEVERITIES.some((s) => s === v);
 
 const BLOCK_KEYS = new Set(["files", "ignores", "rules"]);
 
@@ -61,9 +90,10 @@ const isStringList = (v: unknown): v is string[] =>
 
 /** A severity, or `[severity, ...options]`. */
 function parseEntry(v: unknown): RuleEntry | null {
-  const sev = Array.isArray(v) ? v[0] : v;
-  if (!SEVERITIES.includes(sev)) return null;
-  return v as RuleEntry;
+  const entry: readonly unknown[] = Array.isArray(v) ? v : [v];
+  const [sev, ...options] = entry;
+  if (!isSeverity(sev)) return null;
+  return Array.isArray(v) ? [sev, ...options] : sev;
 }
 
 /**
@@ -105,8 +135,8 @@ function badGlobs(o: Record<string, unknown>, at: string): string | null {
 
 /** The block's `files`/`ignores`, present only when given. */
 const globsOf = (o: Record<string, unknown>) => ({
-  ...(o["files"] ? { files: o["files"] as string[] } : {}),
-  ...(o["ignores"] ? { ignores: o["ignores"] as string[] } : {}),
+  ...(isStringList(o["files"]) ? { files: o["files"] } : {}),
+  ...(isStringList(o["ignores"]) ? { ignores: o["ignores"] } : {}),
 });
 
 const isRecord = (v: unknown): v is Record<string, unknown> =>
@@ -126,7 +156,7 @@ function parseBlock(
   const extra = Object.keys(o).filter((k) => !BLOCK_KEYS.has(k));
   if (extra.length)
     return bad(
-      `${at}: unknown key "${extra[0]}" — a block takes "files", "ignores" and "rules"`,
+      `${at}: unknown key "${String(extra[0])}" — a block takes "files", "ignores" and "rules"`,
     );
   const globs = badGlobs(o, at);
   if (globs) return bad(globs);
@@ -167,7 +197,10 @@ export function parseRuleBlocks(
     );
   const out: RuleBlock[] = [];
   for (const [i, v] of raw.entries()) {
-    const b = parseBlock(v, `${where} → rules[${i}]`, { shipped, baseDir });
+    const b = parseBlock(v, `${where} → rules[${String(i)}]`, {
+      shipped,
+      baseDir,
+    });
     if (!b.ok) return b;
     out.push(b.value);
   }
@@ -179,16 +212,15 @@ export function parseRuleBlocks(
  * `foreign` (a dependency's plugin, such as `@eslint/markdown`) are not paperlint's and are skipped.
  */
 export function shippedRuleIds(
-  config: readonly unknown[],
+  config: readonly ConfigBlock[],
   foreign: readonly unknown[],
 ): Set<string> {
   const ids = new Set<string>();
   for (const block of config) {
-    const plugins = (block as { plugins?: Record<string, unknown> }).plugins;
-    for (const [name, plugin] of Object.entries(plugins ?? {})) {
+    for (const [name, plugin] of Object.entries(block.plugins ?? {})) {
       if (foreign.includes(plugin)) continue;
-      const rules = (plugin as { rules?: Record<string, unknown> }).rules;
-      for (const rule of Object.keys(rules ?? {})) ids.add(`${name}/${rule}`);
+      for (const rule of Object.keys(plugin.rules ?? {}))
+        ids.add(`${name}/${rule}`);
     }
   }
   return ids;

package/src/rules-off.test.ts

@@ -9,9 +9,9 @@
  */
 import { ESLint, type Linter } from "eslint";
 import { describe, expect, it } from "vitest";
-// @ts-expect-error — the module is .mjs and has no types.
-import { texLanguage } from "../eslint-rules/latex-language.mjs";
+import { texLanguage } from "../eslint-rules/latex-language.ts";
 import { rulePlugins, rulesOff, SHIPPED_RULES } from "./cli.ts";
+import { present } from "../test/support.ts";
 
 const PAPER = [
   "\\documentclass{article}",
@@ -45,7 +45,7 @@ async function lintAsConsumer(
   const [res] = await eslint.lintText(PAPER, {
     filePath: "papers/a/paper.tex",
   });
-  return res!.messages;
+  return present(res, "one lint result").messages;
 }
 
 describe("rulesOff — paperlint's rules, registered and off, for a consumer's own ESLint run", () => {
@@ -100,7 +100,9 @@ describe("rulesOff — paperlint's rules, registered and off, for a consumer's o
       "// eslint-disable-next-line paper/leading-zero -- nothing to silence\nconst x = 1;\n",
       { filePath: "src/x.js" },
     );
-    expect(res!.messages.map((m) => m.message)).toEqual([
+    expect(
+      present(res, "one lint result").messages.map((m) => m.message),
+    ).toEqual([
       "Unused eslint-disable directive (no problems were reported from 'paper/leading-zero').",
     ]);
   });

package/src/{structure.harness.mjs → structure.harness.ts}

@@ -15,18 +15,27 @@ import {
 } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-import { createChecker } from "../lib/check.mjs";
+import { z } from "zod";
+import { createChecker } from "../lib/check.ts";
 
-const HERE = dirname(fileURLToPath(import.meta.url));
+/** `asEslintResults` promises only `unknown[]`; these are the fields the checks read. */
+const EslintResults = z.array(
+  z.object({
+    errorCount: z.number(),
+    warningCount: z.number(),
+    messages: z.array(
+      z.object({ ruleId: z.string().nullable(), severity: z.number() }),
+    ),
+  }),
+);
 const { checkStructure, formatStructure, asEslintResults, STRUCTURE_DEFAULTS } =
-  await import(join(HERE, "structure.ts"));
+  await import("./structure.ts");
 
 const check = createChecker();
 
 const root = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-struct-")));
 const papers = join(root, "papers");
-const paper = (name, files) => {
+const paper = (name: string, files: readonly string[]) => {
   const dir = join(papers, name);
   mkdirSync(dir, { recursive: true });
   for (const f of files) {
@@ -50,7 +59,7 @@ try {
   writeFileSync(join(papers, ".hidden", "paper.tex"), "x");
 
   const f = checkStructure([papers], undefined, { cwd: root });
-  const at = (name) => f.filter((x) => x.file.endsWith(name));
+  const at = (name: string) => f.filter((x) => x.file.endsWith(name));
 
   check(
     "a complete paper directory — NOT A SINGLE finding",
@@ -63,24 +72,26 @@ try {
   check(
     "a missing scorecard — a finding",
     at("no-scorecard").length === 1 &&
-      /missing `PIPELINE-STATUS\.md`/.test(at("no-scorecard")[0].message),
+      /missing `PIPELINE-STATUS\.md`/.test(
+        at("no-scorecard")[0]?.message ?? "",
+      ),
   );
   check(
     "and the message names the CONSEQUENCE, not a restatement of the condition",
-    /are skipped/.test(at("no-scorecard")[0].message) &&
+    /are skipped/.test(at("no-scorecard")[0]?.message ?? "") &&
       /stage, source and research-question checks/.test(
-        at("no-scorecard")[0].message,
+        at("no-scorecard")[0]?.message ?? "",
       ),
   );
   check(
     "and the consequence names THIS directory by name",
-    /no-scorecard/.test(at("no-scorecard")[0].message),
+    /no-scorecard/.test(at("no-scorecard")[0]?.message ?? ""),
   );
   check(
     "a directory with no source — a finding, and BOTH accepted forms are listed",
     at("no-source").length === 1 &&
-      /`paper\.tex`/.test(at("no-source")[0].message) &&
-      /`paper\.md`/.test(at("no-source")[0].message),
+      /`paper\.tex`/.test(at("no-source")[0]?.message ?? "") &&
+      /`paper\.md`/.test(at("no-source")[0]?.message ?? ""),
   );
 
   // 🔴 THE PAIRED HALF: detection is GENEROUS. Without this the check would scream about every
@@ -136,7 +147,7 @@ try {
   );
 
   // ── one schema for both halves ────────────────────────────────────────────────────────
-  const asResults = asEslintResults(f);
+  const asResults = EslintResults.parse(asEslintResults(f));
   check(
     "findings come back shaped like an ESLint result — `--json` stays one array",
     asResults.length === 2 &&
@@ -144,7 +155,7 @@ try {
         (r) =>
           r.errorCount === 1 &&
           r.warningCount === 0 &&
-          r.messages[0].ruleId === "structure/required-file" &&
+          r.messages[0]?.ruleId === "structure/required-file" &&
           r.messages[0].severity === 2,
       ),
   );
@@ -156,7 +167,7 @@ try {
         { require: ["PIPELINE-STATUS.md", "refs.bib"] },
         { cwd: root },
       ).filter((x) => x.file.endsWith("no-source"));
-      return asEslintResults(two)[0].errorCount === 2;
+      return EslintResults.parse(asEslintResults(two))[0]?.errorCount === 2;
     })(),
   );
   check(