paperlint 3.1.3 → 4.0.0

package/src/init.test.ts

@@ -34,7 +34,7 @@ import {
   reportTexLive,
   reportWorkflow,
 } from "./init.ts";
-import { runNode } from "../test/support.mjs";
+import { runNode } from "../test/support.ts";
 
 const dirs: string[] = [];
 afterEach(() => {
@@ -70,7 +70,7 @@ describe("paperlint init — a declared papers directory", () => {
       err: (s: string) => out.push(s),
       interactive: false,
       hooks: false,
-      run: (() => ({ status: 0 })) as never,
+      run: () => ({ status: 0 }),
       link: () => ({ ok: false, error: "not linked in this test" }),
     });
     const text = out.join("\n");
@@ -81,7 +81,9 @@ describe("paperlint init — a declared papers directory", () => {
     expect(code).toBe(0);
     expect(section).toMatch(/✓ papers — declared in paperlint\.json/);
     expect(section).not.toMatch(/candidates|eslint-rules|drafts/);
-    const cfg = JSON.parse(readFileSync(join(root, "paperlint.json"), "utf8"));
+    const cfg: unknown = JSON.parse(
+      readFileSync(join(root, "paperlint.json"), "utf8"),
+    );
     expect(cfg).toEqual({ papersDir: "papers" });
   });
 
@@ -93,9 +95,9 @@ describe("paperlint init — a declared papers directory", () => {
       log: () => {},
       err: () => {},
       interactive: true,
-      ask: async (q) => (asked.push(q), "n"),
+      ask: (q) => Promise.resolve((asked.push(q), "n")),
       hooks: false,
-      run: (() => ({ status: 0 })) as never,
+      run: () => ({ status: 0 }),
       link: () => ({ ok: false, error: "not linked in this test" }),
     });
     expect(asked.filter((q) => /papers roots/.test(q))).toEqual([]);
@@ -114,7 +116,7 @@ describe("paperlint init — writes paperlint.json only when something differs f
     err: () => {},
     interactive: false,
     hooks: false,
-    run: (() => ({ status: 0 })) as never,
+    run: () => ({ status: 0 }),
     link: () => ({ ok: false as const, error: "not linked in this test" }),
   };
   const fresh = (files: Record<string, string>): string => {
@@ -165,9 +167,10 @@ const texRun = async (
     log: (s: string) => out.push(s),
     err: () => {},
     interactive,
-    ask: async (q) => (asked.push(q), /TeX Live/.test(q) ? answer : ""),
+    ask: (q) =>
+      Promise.resolve((asked.push(q), /TeX Live/.test(q) ? answer : "")),
     hooks: false,
-    run: (() => ({ status: 0 })) as never,
+    run: () => ({ status: 0 }),
     link: () => ({ ok: false as const, error: "not linked in this test" }),
     tex,
   });
@@ -246,7 +249,7 @@ async function initRun(
     err: (s: string) => err.push(s),
     interactive: false,
     hooks: false,
-    run: (() => ({ status: 0 })) as never,
+    run: () => ({ status: 0 }),
     link: () => ({ ok: false, error: "not linked in this test" }),
     ...opts,
   });
@@ -277,6 +280,26 @@ describe("paperlint init — a paperlint.json it cannot use stops it before anyt
     ]);
   });
 
+  it("🔴 a paperlint.json holding JSON that is not an object is refused, not read as settings", async () => {
+    // Guards: `null` threw a TypeError reading the papers field; `[1]` was spread into a settings
+    // object and the consumer's file rewritten as `{ "0": 1, "papersDir": … }`.
+    for (const json of ["null\n", "[1]\n"]) {
+      const root = tree({
+        "paperlint.json": json,
+        "drafts/a/paper.md": "# a\n",
+      });
+      const decl = await declarePapers(root, () =>
+        choosePapers(root, { interactive: false }),
+      );
+      expect(decl).toEqual({
+        status: "unparsable",
+        path: join(root, "paperlint.json"),
+        reason: "not a JSON object",
+      });
+      expect(readFileSync(join(root, "paperlint.json"), "utf8")).toBe(json);
+    }
+  });
+
   it("a file without a trailing newline keeps having none", async () => {
     const root = tree({
       "paperlint.json": '{"x":1}',
@@ -301,7 +324,7 @@ describe("paperlint init — how several candidate directories were decided, sai
   it("picked by a human", async () => {
     const r = await initRun(several(), {
       interactive: true,
-      ask: async () => "2",
+      ask: () => Promise.resolve("2"),
     });
     expect(section(r.out)).toEqual([
       "  ✓ writing — you picked it out of 2 candidates",
@@ -319,7 +342,7 @@ describe("paperlint init — how several candidate directories were decided, sai
   it("an answer that picks nothing: the first, and said so", async () => {
     const r = await initRun(several(), {
       interactive: true,
-      ask: async () => "nine",
+      ask: () => Promise.resolve("nine"),
     });
     expect(section(r.out)[0]).toBe(
       "  ✓ drafts — 2 candidates, no answer was given, so the first one was taken",
@@ -433,7 +456,7 @@ describe("paperlint init — TeX Live and hooks failures, whole", () => {
   it("TeX Live: a failed install says to run it again", async () => {
     const t = await offerTexLive(
       { installed: () => false, install: () => 1 },
-      { interactive: true, ask: async () => "yes" },
+      { interactive: true, ask: () => Promise.resolve("yes") },
     );
     expect([t, reportTexLive(t, "")]).toEqual([
       "failed",
@@ -462,8 +485,8 @@ describe("paperlint init — a first paper", () => {
     const made: string[] = [];
     const r = await initRun(tree({}), {
       interactive: true,
-      ask: async () => "",
-      createPaper: async (_root, name) => (made.push(name), 0),
+      ask: () => Promise.resolve(""),
+      createPaper: (_root, name) => Promise.resolve((made.push(name), 0)),
     });
     expect(made).toEqual([]);
     expect(r.out[r.out.indexOf("first paper") + 1]).toBe(

package/src/init.ts

@@ -46,7 +46,13 @@ import {
 // eslint-disable-next-line boundaries/dependencies -- legacy I/O, moves behind a port in #76
 import { spawnSync } from "node:child_process";
 import { dirname, join, relative, resolve } from "node:path";
-import { doctor, detectPapers, found, PROGRAMS } from "./doctor.ts";
+import {
+  doctor,
+  detectPapers,
+  found,
+  PROGRAMS,
+  type ProgramProbe,
+} from "./doctor.ts";
 import { PAPER_MARKERS, papersIn } from "./build.ts";
 import { linkSkills, SKILLS_HOME, type LinkReport } from "./link-skills.ts";
 import { actionRef } from "./action-ref.ts";
@@ -64,13 +70,16 @@ import {
   nameProblem,
   type PaperFormat,
 } from "./new-paper.ts";
-// The one source for the consumer's config key lives in the .mjs half of the package (the ESLint
-// rules and the skill scripts import it too); its types are in lib/paper-config.d.mts.
+// The one source for the consumer's config key lives in lib/ (the ESLint rules and the skill scripts
+// import it too). It is imported compiled, from dist/, the one path that resolves the same from src/
+// and from dist/ — see CONTRIBUTING.md.
 import {
   CONFIG_FILE,
   DEFAULT_PAPERS_ROOT,
   PAPERS_DIR_FIELD,
-} from "../lib/paper-config.mjs";
+} from "#lib/paper-config";
+import { messageOf } from "./domain/text.ts";
+import { isRecord } from "./domain/record.ts";
 
 /** How the papers directory was arrived at. Printed, because a guess must not read as a fact. */
 export type PapersHow =
@@ -122,13 +131,21 @@ export function interactivity({
   return { interactive: true, why: "a terminal on both ends" };
 }
 
+/**
+ * Whether a standard stream is a terminal. Node types `isTTY` as `boolean`, but on a stream that
+ * is NOT a terminal (a pipe, a file) the property is absent — `undefined` — so it is read as the
+ * optional it really is.
+ */
+const isTty = (stream: { readonly isTTY?: boolean }): boolean =>
+  stream.isTTY === true;
+
 /** The mode of THIS process — the one place `process` is read for it. */
 export const processInteractivity = (yes: boolean) =>
   interactivity({
     // eslint-disable-next-line no-restricted-globals -- legacy I/O, moves behind a port in #76
-    stdinTTY: Boolean(process.stdin.isTTY),
+    stdinTTY: isTty(process.stdin),
     // eslint-disable-next-line no-restricted-globals -- legacy I/O, moves behind a port in #76
-    stdoutTTY: Boolean(process.stdout.isTTY),
+    stdoutTTY: isTty(process.stdout),
     // eslint-disable-next-line no-restricted-globals -- legacy I/O, moves behind a port in #76
     env: process.env,
     yes,
@@ -217,13 +234,17 @@ export async function declarePapers(
 ): Promise<DeclarationResult> {
   const path = join(root, CONFIG_FILE);
   const raw = existsSync(path) ? readFileSync(path, "utf8") : null;
-  let settings: Record<string, unknown> = {};
+  let settings: Readonly<Record<string, unknown>> = {};
   if (raw !== null) {
+    let parsed: unknown;
     try {
-      settings = JSON.parse(raw) as Record<string, unknown>;
+      parsed = JSON.parse(raw);
     } catch (e) {
-      return { status: "unparsable", path, reason: (e as Error).message };
+      return { status: "unparsable", path, reason: messageOf(e) };
     }
+    if (!isRecord(parsed))
+      return { status: "unparsable", path, reason: "not a JSON object" };
+    settings = parsed;
     const existing = settings[PAPERS_DIR_FIELD];
     if (existing !== undefined)
       return { status: "kept", path, papers: existing };
@@ -289,7 +310,7 @@ export async function offerWorkflow(
     ask?: (q: string) => Promise<string>;
     interactive: boolean;
     /** The running package's version; see `InitOptions.version`. */
-    version?: string;
+    version?: string | undefined;
   },
 ): Promise<WorkflowResult> {
   const path = join(root, WORKFLOW_PATH);
@@ -317,7 +338,7 @@ export function reportWorkflow(
     version,
     papersDir,
     why,
-  }: { version?: string; papersDir: string; why: string },
+  }: { version?: string | undefined; papersDir: string; why: string },
 ): string[] {
   const ref = actionRef(version);
   const out: string[] = [];
@@ -352,7 +373,7 @@ export function reportWorkflow(
  * passing checker produce the same silence.
  */
 export function missingPrograms(
-  run = spawnSync,
+  run: ProgramProbe = spawnSync,
 ): readonly (typeof PROGRAMS)[number][] {
   return PROGRAMS.filter((p) => !found(p.bin, run));
 }
@@ -406,7 +427,7 @@ export async function offerHooks(
     hooks: boolean;
     interactive: boolean;
     ask?: (q: string) => Promise<string>;
-    merge?: Merge;
+    merge?: Merge | undefined;
   },
 ): Promise<HooksOutcome> {
   if (!hooks) return { status: "skipped" };
@@ -438,7 +459,7 @@ export async function offerHooks(
     }
     return wireHooks(root, m, shippedWiring());
   } catch (e) {
-    return { status: "failed", reason: (e as Error).message };
+    return { status: "failed", reason: messageOf(e) };
   }
 }
 
@@ -560,7 +581,7 @@ export interface InitOptions {
   /** `false` is `--no-hooks`. */
   hooks?: boolean;
   /** vigiles' merge. Injected only so a test can observe or replace it. */
-  merge?: Merge;
+  merge?: Merge | undefined;
   /** `--paper <name>`: create this paper, even without a terminal. */
   paper?: string | null;
   /** `--format tex|md` for that paper. */
@@ -574,7 +595,7 @@ export interface InitOptions {
     name: string,
     format: PaperFormat,
   ) => Promise<number>;
-  run?: typeof spawnSync;
+  run?: ProgramProbe;
   /**
    * What `paperlint lint` would resolve from the declaration, asked of the CLI's OWN reader. A second
    * implementation here would be a second source of truth — the very defect `doctor` reports.
@@ -586,7 +607,7 @@ export interface InitOptions {
    * The version of the running package, read by the CLI from its own `package.json`. The CI
    * workflow is pinned to its release tag (`actionRef`); absent or unreleased, the placeholder.
    */
-  version?: string;
+  version?: string | undefined;
   /**
    * TeX Live for `paperlint build`: whether paperlint's own tree is installed, and how to install
    * it (`paperlint toolchain`). Passed in by the CLI; without them the step only names the command.
@@ -739,21 +760,28 @@ export async function init(
   for (const line of papersLines(decl, why)) log(line);
   log(``);
   log(`settings`);
-  if (decl.status === "written")
+  // Every step below uses the DECLARED directory. A kept declaration outranks what init
+  // measured or guessed: otherwise the first paper and the workflow would land in the
+  // guessed directory while lint and the hooks keep reading the declared one.
+  let papersDir: string;
+  if (decl.status === "written") {
+    papersDir = decl.papers;
     log(
       `  ✓ ${here(decl.path)} → { "${PAPERS_DIR_FIELD}": ${JSON.stringify(decl.papers)} }`,
     );
-  else if (decl.status === "default")
+  } else if (decl.status === "default") {
+    papersDir = decl.papers;
     log(
       `  ✓ nothing to write — "${decl.papers}" is the default, so no ${CONFIG_FILE} is needed`,
     );
-  else if (decl.status === "kept") {
+  } else if (decl.status === "kept") {
     if (typeof decl.papers !== "string") {
       err(
         `  ✗ ${here(decl.path)} declares ${PAPERS_DIR_FIELD} = ${JSON.stringify(decl.papers)} — it must be a directory path (a string)`,
       );
       return 2;
     }
+    papersDir = decl.papers;
     log(
       `  ✓ ${here(decl.path)} already declares ${PAPERS_DIR_FIELD} = ${JSON.stringify(decl.papers)} — kept, nothing overwritten`,
     );
@@ -767,10 +795,6 @@ export async function init(
     );
     return 2;
   }
-  // Every step below uses the DECLARED directory. A kept declaration outranks what init
-  // measured or guessed: otherwise the first paper and the workflow would land in the
-  // guessed directory while lint and the hooks keep reading the declared one.
-  const papersDir = decl.papers as string;
 
   // ── 3. the skills, linked where Claude Code looks for them ─────────────────────────────
   for (const line of reportSkillLinks(link(root), here)) log(line);

package/src/{latex-log.harness.mjs → latex-log.harness.ts}

@@ -5,11 +5,9 @@
  * memory: the two error spellings `-file-line-error` produces, the missing-package form, and a
  * marker that TeX broke at column 79.
  */
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { createChecker } from "../lib/check.mjs";
+import { createChecker } from "../lib/check.ts";
+import type { LogMarker } from "./latex-log.ts";
 
-const HERE = dirname(fileURLToPath(import.meta.url));
 const {
   unwrapLog,
   logMarkers,
@@ -18,7 +16,7 @@ const {
   bibtexExcerpt,
   auxBib,
   MAX_PRINT_LINE,
-} = await import(join(HERE, "latex-log.ts"));
+} = await import("./latex-log.ts");
 
 const check = createChecker();
 
@@ -78,13 +76,15 @@ const firstPass = [
 const m = logMarkers(firstPass);
 check(
   "every documented marker is recognised",
-  [
-    "rerun-requested",
-    "labels-changed",
-    "rerunfilecheck",
-    "undefined-references",
-    "undefined-citations",
-  ].every((k) => m.includes(k)),
+  (
+    [
+      "rerun-requested",
+      "labels-changed",
+      "rerunfilecheck",
+      "undefined-references",
+      "undefined-citations",
+    ] satisfies LogMarker[]
+  ).every((k) => m.includes(k)),
 );
 check(
   "a clean log carries no markers",
@@ -96,7 +96,7 @@ check(
 // Guards: matching the documented summary line rather than the word 'undefined'.
 check(
   "a single reference warning is not the end-of-run summary",
-  !logMarkers([firstPass[0]]).includes("undefined-references"),
+  !logMarkers(firstPass.slice(0, 1)).includes("undefined-references"),
 );
 
 // ── error excerpt ───────────────────────────────────────────────────────────────────────
@@ -114,7 +114,7 @@ check(
   "-file-line-error form: the error line, the l.NNN line and the rest of the source line",
   ex[0] === "./paper.tex:4: Undefined control sequence." &&
     ex[1] === "l.4 \\foo" &&
-    ex[2].includes("bar baz"),
+    (ex[2] ?? "").includes("bar baz"),
 );
 // Guards: the end of the excerpt — without it the excerpt runs into TeX's memory statistics and
 // buries the line the author needs.

package/src/{latex-loop.harness.mjs → latex-loop.harness.ts}

@@ -6,30 +6,43 @@
  * A defect in `nextStep` fails in table 1, one in `summarize` in table 2, before table 3 runs.
  *
  * The decision is pure, so none of this needs TeX. The real-pdflatex half lives in
- * `test/e2e/build.mjs`.
+ * `test/e2e/build.ts`.
  */
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { createChecker } from "../lib/check.mjs";
+import { createChecker } from "../lib/check.ts";
+import type {
+  BibInput,
+  Hashes,
+  Observation,
+  State,
+  Step,
+} from "./latex-loop.ts";
 
-const HERE = dirname(fileURLToPath(import.meta.url));
-const { nextStep, summarize, changedFiles, MAX_PASSES } = await import(
-  join(HERE, "latex-loop.ts")
-);
+const { nextStep, summarize, changedFiles, MAX_PASSES } =
+  await import("./latex-loop.ts");
 
 const check = createChecker();
 
 // ── builders ────────────────────────────────────────────────────────────────────────────
-const H = (aux, toc = null, out = null, bbl = null) => ({ aux, toc, out, bbl });
-const NO_BIB = { kind: "none" };
-const bib = (citations, bibHash = "b1") => ({
+type LatexPass = Extract<Observation, { step: "latex" }>;
+type BibtexPass = Extract<Observation, { step: "bibtex" }>;
+const H = (
+  aux: string | null,
+  toc: string | null = null,
+  out: string | null = null,
+  bbl: string | null = null,
+): Hashes => ({ aux, toc, out, bbl });
+const NO_BIB: BibInput = { kind: "none" };
+const bib = (
+  citations: readonly string[],
+  bibHash: string | null = "b1",
+): BibInput => ({
   kind: "needed",
   citations,
   databases: ["refs"],
   style: "plain",
   bibHash,
 });
-const latex = (o = {}) => ({
+const latex = (o: Partial<LatexPass> = {}): LatexPass => ({
   step: "latex",
   final: false,
   exitCode: 0,
@@ -40,7 +53,7 @@ const latex = (o = {}) => ({
   errorLines: [],
   ...o,
 });
-const bibtex = (o = {}) => ({
+const bibtex = (o: Partial<BibtexPass> = {}): BibtexPass => ({
   step: "bibtex",
   exitCode: 0,
   before: H("a1"),
@@ -49,11 +62,11 @@ const bibtex = (o = {}) => ({
   errorLines: [],
   ...o,
 });
-const kind = (s) =>
+const kind = (s: Step) =>
   s.kind === "latex" ? `latex${s.final ? "-final" : ""}` : s.kind;
 
 // ── 1. nextStep over a State ─────────────────────────────────────────────────────────────
-const S = (o = {}) => ({
+const S = (o: Partial<State> = {}): State => ({
   failed: null,
   bibOutdated: false,
   unsettled: [],
@@ -62,12 +75,12 @@ const S = (o = {}) => ({
   warnings: [],
   ...o,
 });
-const exitFail = {
+const exitFail: NonNullable<State["failed"]> = {
   step: "bibtex",
   cause: { kind: "exit", code: 2 },
   lines: ["I couldn't open database file nope.bib"],
 };
-const STATES = [
+const STATES: [string, State, string][] = [
   // Guards: the only moment paper-guards can speak — its error comes on the final pass, so testing
   // 'final' before 'exit code' would ship the undefined reference green.
   [
@@ -96,7 +109,7 @@ const STATES = [
   // Guards: the stop on a document that never settles — without it the loop runs forever; with a
   // silent cap it ships a PDF with stale cross-references.
   [
-    `Q3 cap: ${MAX_PASSES} passes and still unsettled — fail`,
+    `Q3 cap: ${String(MAX_PASSES)} passes and still unsettled — fail`,
     S({ unsettled: ["paper.aux"], latexPasses: MAX_PASSES }),
     "fail",
   ],
@@ -115,20 +128,29 @@ for (const [label, state, expected] of STATES) {
 const q1 = nextStep(S({ failed: exitFail }));
 check(
   "Q1 passes the failure through: the step, the cause and the lines verbatim",
-  q1.step === "bibtex" && q1.cause.code === 2 && q1.lines === exitFail.lines,
+  q1.kind === "fail" &&
+    q1.step === "bibtex" &&
+    q1.cause.kind === "exit" &&
+    q1.cause.code === 2 &&
+    q1.lines === exitFail.lines,
 );
 const q3cap = nextStep(
   S({ unsettled: ["paper.aux", "labels-changed"], latexPasses: MAX_PASSES }),
 );
 check(
   "the cap's failure is no-convergence and NAMES what stayed unsettled",
-  q3cap.cause.kind === "no-convergence" &&
-    q3cap.lines[0].includes("paper.aux, labels-changed"),
+  q3cap.kind === "fail" &&
+    q3cap.cause.kind === "no-convergence" &&
+    (q3cap.lines[0] ?? "").includes("paper.aux, labels-changed"),
 );
 check(
   "done carries the state's warnings",
-  nextStep(S({ finalDone: true, warnings: ["undefined-citations"] }))
-    .warnings[0] === "undefined-citations",
+  (() => {
+    const done = nextStep(
+      S({ finalDone: true, warnings: ["undefined-citations"] }),
+    );
+    return done.kind === "done" && done.warnings[0] === "undefined-citations";
+  })(),
 );
 
 // ── 2. summarize over histories ─────────────────────────────────────────────────────────
@@ -152,7 +174,10 @@ check(
   (() => {
     const f = sum([latex({ exitCode: 1, errorLines: ["l.4 \\foo"] })]).failed;
     return (
-      f?.step === "latex" && f.cause.code === 1 && f.lines[0] === "l.4 \\foo"
+      f?.step === "latex" &&
+      f.cause.kind === "exit" &&
+      f.cause.code === 1 &&
+      f.lines[0] === "l.4 \\foo"
     );
   })(),
 );
@@ -162,22 +187,22 @@ check(
 );
 check(
   "summarize: bibOutdated when the aux names a bibliography bibtex has not run on",
-  sum([latex({ bib: bib(["k"]) })]).bibOutdated === true,
+  sum([latex({ bib: bib(["k"]) })]).bibOutdated,
 );
 check(
   "summarize: bibOutdated is false once bibtex ran on exactly that input",
-  sum([latex({ bib: bib(["k"]) }), bibtex()]).bibOutdated === false,
+  !sum([latex({ bib: bib(["k"]) }), bibtex()]).bibOutdated,
 );
 // Guards: the .bib hash as an input — a corrected author or year in refs.bib would keep the old
 // .bbl, and the PDF would print the entry as it was before the fix.
 check(
   "summarize: the .bib content changed since bibtex ran — bibOutdated",
   sum([latex({ bib: bib(["k"]) }), bibtex(), latex({ bib: bib(["k"], "b2") })])
-    .bibOutdated === true,
+    .bibOutdated,
 );
 check(
   "summarize: no bibliography at all — never bibOutdated",
-  sum([latex()]).bibOutdated === false,
+  !sum([latex()]).bibOutdated,
 );
 check(
   "summarize: unsettled names every tracked file the last pass changed",
@@ -232,10 +257,10 @@ check(
 );
 
 // ── 3. composed: nextStep(summarize(history)) ───────────────────────────────────────────
-const step = (history) => nextStep(summarize(history));
+const step = (history: readonly Observation[]) => nextStep(summarize(history));
 
 // ── the histories the loop sees ───────────────────────────────────────────────────────────────────────────
-const TABLE = [
+const TABLE: [string, Observation[], string][] = [
   ["nothing ran yet — the first step is a plain pass", [], "latex"],
   [
     "a pass that created the aux — rerun",
@@ -364,7 +389,8 @@ const latexFail = step([
 ]);
 check(
   "a latex fail names the step, the exit code and the log excerpt verbatim",
-  latexFail.step === "latex" &&
+  latexFail.kind === "fail" &&
+    latexFail.step === "latex" &&
     latexFail.cause.kind === "exit" &&
     latexFail.cause.code === 1 &&
     latexFail.lines[1] === "l.4 \\foo",
@@ -380,14 +406,16 @@ check(
   "a bibtex fail names BIBTEX, not latex",
   bibFail.kind === "fail" &&
     bibFail.step === "bibtex" &&
+    bibFail.cause.kind === "exit" &&
     bibFail.cause.code === 2,
 );
 
 // ── the cap ─────────────────────────────────────────────────────────────────────────────
-const moving = (i) => latex({ before: H(`a${i}`), after: H(`a${i + 1}`) });
+const moving = (i: number) =>
+  latex({ before: H(`a${String(i)}`), after: H(`a${String(i + 1)}`) });
 const underCap = Array.from({ length: MAX_PASSES - 1 }, (_, i) => moving(i));
 check(
-  `the cap is ${MAX_PASSES} and it is not hit early: after ${MAX_PASSES - 1} moving passes, one more`,
+  `the cap is ${String(MAX_PASSES)} and it is not hit early: after ${String(MAX_PASSES - 1)} moving passes, one more`,
   MAX_PASSES === 5 && kind(step(underCap)) === "latex",
 );
 const atCap = Array.from({ length: MAX_PASSES }, (_, i) => moving(i));
@@ -398,7 +426,7 @@ check(
 );
 check(
   "the non-convergence failure NAMES the file that kept changing",
-  capped.kind === "fail" && capped.lines[0].includes("paper.aux"),
+  capped.kind === "fail" && (capped.lines[0] ?? "").includes("paper.aux"),
 );
 const cappedMarker = step(
   Array.from({ length: MAX_PASSES }, () =>
@@ -408,7 +436,7 @@ const cappedMarker = step(
 check(
   "a log that keeps asking for a rerun hits the same cap, and names the marker",
   cappedMarker.kind === "fail" &&
-    cappedMarker.lines[0].includes("labels-changed"),
+    (cappedMarker.lines[0] ?? "").includes("labels-changed"),
 );
 const convergedAtCap = [...atCap.slice(0, -1), latex()];
 check(
@@ -446,5 +474,5 @@ check(
 );
 
 console.log(
-  `✓ ${String(check.count)} assertions passed — latex-loop: nextStep over State, summarize over histories, and the two composed, including the ${MAX_PASSES}-pass cap`,
+  `✓ ${String(check.count)} assertions passed — latex-loop: nextStep over State, summarize over histories, and the two composed, including the ${String(MAX_PASSES)}-pass cap`,
 );

package/src/latex-loop.ts

@@ -3,7 +3,7 @@
  *
  * PURE. No disk, no process, no clock. The shell in `build.ts` runs a step, records what it saw
  * as an `Observation`, appends it to the history and asks `nextStep(summarize(history))` again.
- * Both halves are table tests (`latex-loop.harness.mjs`), not scenarios that need TeX.
+ * Both halves are table tests (`latex-loop.harness.ts`), not scenarios that need TeX.
  *
  * ── THE LOOP: `summarize` reduces the history to a `State`, and `nextStep` asks four questions ──
  *   1. did the last program fail?                          → fail, with its error lines
@@ -118,7 +118,7 @@ export type Step =
     };
 
 /** Non-final pdflatex passes allowed before the build is declared non-converging. */
-export const MAX_PASSES = 5;
+export const MAX_PASSES: number = 5;
 
 /** The history, reduced to the four questions `nextStep` asks. */
 export type State = {
@@ -152,7 +152,7 @@ const noConvergence = (unsettled: readonly string[]): Step => ({
   step: "latex",
   cause: { kind: "no-convergence", unsettled },
   lines: [
-    `the build does not converge: after ${MAX_PASSES} pdflatex passes, the last one still changed or asked to rerun: ${unsettled.join(", ")}.`,
+    `the build does not converge: after ${String(MAX_PASSES)} pdflatex passes, the last one still changed or asked to rerun: ${unsettled.join(", ")}.`,
     `A document whose aux keeps changing on every pass never settles; stopping here instead of`,
     `shipping a PDF with stale cross-references.`,
   ],