paperlint 3.2.0 → 4.1.0

package/src/adapters/latex/nodes.ts

@@ -0,0 +1,141 @@
+/** What the three readers share about unified-latex nodes: places, text, and the walk. */
+import type * as Ast from "@unified-latex/unified-latex-types";
+import { CONTINUE, SKIP, visit } from "@unified-latex/unified-latex-util-visit";
+import type { Place, Span } from "../../domain/tex-document.ts";
+import { KEY_SIGNATURES } from "./parse.ts";
+
+export { collapse } from "../../domain/tex-document.ts";
+
+/** unified-latex's node types, read-only: nothing here writes to a tree. */
+export type Node = Readonly<Ast.Node>;
+export type Macro = Readonly<Ast.Macro>;
+export type Argument = Readonly<Ast.Argument>;
+
+/** Anything the parser may have given a position: offsets of its first and past its last character. */
+interface Positioned {
+  readonly position?: {
+    readonly start: { readonly offset: number };
+    readonly end: { readonly offset: number };
+  };
+}
+
+/** Where a node stands, or that it has no position. */
+export const placeOf = (n: Positioned): Place =>
+  n.position === undefined
+    ? { kind: "unplaced" }
+    : {
+        kind: "at",
+        span: { start: n.position.start.offset, end: n.position.end.offset },
+      };
+
+/** The first mandatory (`{…}`) and optional (`[…]`) arguments' contents, and the last mandatory one's. */
+export const mandatory = (m: Macro): readonly Argument[] =>
+  (m.args ?? []).filter((a) => a.openMark === "{");
+export const optional = (m: Macro): Argument | undefined =>
+  (m.args ?? []).find((a) => a.openMark === "[");
+
+/** What a string node reads as: itself, except a tie (`~`), which is a space the reader sees. */
+export const stringText = (content: string): string =>
+  content === "~" ? " " : content;
+
+/** Which of a macro's mandatory arguments it typesets: one of them, or none at all. */
+type Shown =
+  | { readonly kind: "argument"; readonly at: number }
+  | { readonly kind: "none" };
+
+const LAST: Shown = { kind: "argument", at: -1 };
+const NONE: Shown = { kind: "none" };
+
+/**
+ * Macros that do not typeset their last mandatory argument, as data. `\texorpdfstring{shown}{bookmark}`
+ * typesets the first; a declaration (`\color{red}`, `\fontsize{10}{12}`, `\vspace{1em}`,
+ * `\setlength{\x}{0pt}`) typesets none. Every other macro typesets its last (`\textcolor{red}{x}`,
+ * `\colorbox{yellow}{x}`, `\href{url}{x}`).
+ */
+const SHOWN_ARGUMENT: ReadonlyMap<string, Shown> = new Map<string, Shown>([
+  ["texorpdfstring", { kind: "argument", at: 0 }],
+  ...["color", "fontsize", "vspace", "hspace", "setlength", "addtolength"].map(
+    (m) => [m, NONE] as const,
+  ),
+]);
+
+/** The text a (non-key) macro typesets: see `SHOWN_ARGUMENT`. */
+function shownText(m: Macro): string {
+  const shown = SHOWN_ARGUMENT.get(m.content) ?? LAST;
+  return shown.kind === "none"
+    ? ""
+    : textOf(mandatory(m).at(shown.at)?.content);
+}
+
+/**
+ * The text of a node list with markup dropped: strings, spaces, what groups hold, and the argument a
+ * formatting macro typesets — its last mandatory one (`\textbf{Usage}`, `\textcolor{red}{Usage}`,
+ * `\href{url}{Usage}` → `Usage`) unless `SHOWN_ARGUMENT` says otherwise. A key macro's arguments
+ * (`\label{…}`, `\cite{…}`) are not text.
+ */
+export const textOf = (nodes: readonly Node[] | undefined): string =>
+  (nodes ?? [])
+    .map((n) => {
+      if (n.type === "string") return stringText(n.content);
+      if (n.type === "whitespace" || n.type === "parbreak") return " ";
+      if (n.type === "group") return textOf(n.content);
+      return n.type === "macro" && !(n.content in KEY_SIGNATURES)
+        ? shownText(n)
+        : "";
+    })
+    .join("");
+
+/**
+ * A macro's place with its arguments: from its name to past the closing mark of the last argument
+ * that holds text. unified-latex positions the name and the arguments' contents, never the
+ * arguments themselves, so an empty trailing argument is not covered.
+ */
+export function macroPlace(m: Macro): Place {
+  const name = placeOf(m);
+  if (name.kind === "unplaced") return name;
+  const end = (m.args ?? []).reduce((e, a) => {
+    const last = a.content.at(-1)?.position?.end.offset;
+    return last === undefined ? e : last + a.closeMark.length;
+  }, name.span.end);
+  const span: Span = { start: name.span.start, end };
+  return { kind: "at", span };
+}
+
+/** What visit reaches: a node, an argument, or a node list (a content array, an argument list). */
+export type Visited = Readonly<Ast.Ast> | readonly (Node | Argument)[];
+
+/**
+ * Everything visit reaches under `tree`, in document order, node lists included; `skip` prunes what
+ * it is given (a node or an argument, with the node that holds it) and everything under it. visit
+ * reports through a callback and returns nothing, so the one collection point of this adapter is here.
+ */
+export function visited(
+  // eslint-disable-next-line functional/prefer-immutable-types -- visit's own parameter type is mutable
+  tree: Ast.Ast,
+  skip: (v: Visited, parent: Visited | undefined) => boolean,
+): readonly Visited[] {
+  // eslint-disable-next-line functional/prefer-immutable-types -- the one accumulator, see above
+  const seen: Visited[] = [];
+  visit(
+    tree,
+    (node, info) => {
+      // eslint-disable-next-line functional/immutable-data -- visit is callback-only; see above
+      seen.push(node);
+      return skip(node, info.parents[0]) ? SKIP : CONTINUE;
+    },
+    { includeArrays: true },
+  );
+  return seen;
+}
+
+/** A node list visit reached. `Array.isArray` alone does not narrow a readonly array. */
+export const isList = (v: Visited): v is readonly (Node | Argument)[] =>
+  Array.isArray(v);
+
+/** A macro's argument, as visit reports it. */
+export const isArgument = (v: Visited): v is Argument =>
+  !isList(v) && v.type === "argument";
+
+/** A node, as opposed to a node list or an argument (which visit also reports). */
+export const isNode = (v: Visited): v is Node =>
+  !isList(v) && v.type !== "argument" && v.type !== "root";

package/src/adapters/latex/outline.ts

@@ -0,0 +1,64 @@
+/** The document's sections, where its back matter starts, and where it ends. */
+import type * as Ast from "@unified-latex/unified-latex-types";
+import { isDefined } from "remeda";
+import type { Heading, Outline } from "../../domain/tex-document.ts";
+import {
+  collapse,
+  isNode,
+  macroPlace,
+  mandatory,
+  textOf,
+  visited,
+  type Macro,
+  type Node,
+} from "./nodes.ts";
+import { isDefinition, isUnrendered } from "./hidden.ts";
+import type { ParsedTex } from "./parse.ts";
+
+/** Macros and the environment that start the back matter: the appendix and the bibliography. */
+const BACK_MATTER_MACROS: ReadonlySet<string> = new Set([
+  "appendix",
+  "bibliography",
+  "printbibliography",
+]);
+
+const isBackMatter = (n: Node): boolean =>
+  (n.type === "macro" && BACK_MATTER_MACROS.has(n.content)) ||
+  (n.type === "environment" && n.env === "thebibliography");
+
+const isSection = (n: Node): n is Macro =>
+  n.type === "macro" && n.content === "section";
+
+const isDocument = (n: Node): n is Readonly<Ast.Environment> =>
+  n.type === "environment" && n.env === "document";
+
+/** One `\section`/`\section*`: the last mandatory argument is its title. */
+const headingOf = (m: Macro): Heading => ({
+  title: collapse(textOf(mandatory(m).at(-1)?.content)),
+  place: macroPlace(m),
+});
+
+/**
+ * The body's `\section`s (starred or not) in document order, the first back-matter node, and the
+ * end of the document. A source with no `document` environment is read whole, as a fragment. What
+ * the PDF never shows is pruned (`isUnrendered`), and so is a macro definition's body
+ * (`isDefinition`): a heading in a comment environment or in a definition is not a section.
+ */
+export function outlineOf(t: ParsedTex): Outline {
+  const doc = t.root.content.find(isDocument);
+  const nodes = visited(
+    doc?.content ?? t.root.content,
+    (v, parent) => isUnrendered(v, parent) || isDefinition(v),
+  ).filter(isNode);
+  const backMatter =
+    nodes
+      .filter(isBackMatter)
+      .map((n) => n.position?.start.offset)
+      .filter(isDefined)[0] ?? null;
+  const docEnd = doc?.position?.end.offset;
+  return {
+    sections: nodes.filter(isSection).map(headingOf),
+    backMatter,
+    end: docEnd === undefined ? null : docEnd - 1,
+  };
+}

package/src/adapters/latex/parse.ts

@@ -0,0 +1,136 @@
+/**
+ * A LaTeX source → its unified-latex tree, as one `ParsedTex` that keeps the two together.
+ *
+ * ── CITATION KEYS ARE ARGUMENTS, NOT TEXT ────────────────────────────────────────
+ * unified-latex attaches arguments only to macros it has a signature for. natbib's and biblatex's
+ * citation commands have none, so `\citep{aisec2025}` came back with its key as a separate group —
+ * readable as prose. `KEY_SIGNATURES` declares them, and the other macros whose arguments name a
+ * file, a label or a URL rather than say something, so their arguments are attached and the
+ * rendered text skips them structurally. `\href` says something in one argument and names a URL in
+ * the other, so it is signed too, and `KEY_ARGUMENT` says which of its arguments is not text.
+ */
+import type * as Ast from "@unified-latex/unified-latex-types";
+import { getParser } from "@unified-latex/unified-latex-util-parse";
+import { once } from "remeda";
+
+const signed = (
+  names: readonly string[],
+  signature: string,
+): readonly (readonly [string, { readonly signature: string }])[] =>
+  names.map((m) => [m, { signature }] as const);
+
+/** Citation commands: their `{…}` argument is a key, their `[…]` ones are notes the reader sees. */
+export const CITATION_MACROS: ReadonlySet<string> = new Set([
+  "cite",
+  "citep",
+  "citet",
+  "citealp",
+  "citealt",
+  "citeauthor",
+  "citeyear",
+  "citeyearpar",
+  "Citep",
+  "Citet",
+  "nocite",
+  "parencite",
+  "textcite",
+  "autocite",
+  "footcite",
+]);
+
+/** Macros whose arguments are keys, labels, files or URLs — never text a reader sees. */
+export const KEY_SIGNATURES: Readonly<
+  Record<string, { readonly signature: string }>
+> = Object.fromEntries([
+  ...signed([...CITATION_MACROS], "o o m"),
+  ...signed(
+    [
+      "label",
+      "ref",
+      "eqref",
+      "pageref",
+      "autoref",
+      "cref",
+      "Cref",
+      "url",
+      "input",
+      "include",
+      "bibliography",
+      "bibliographystyle",
+      "addbibresource",
+    ],
+    "m",
+  ),
+  ...signed(["includegraphics"], "s o o m"),
+  ...signed(["usepackage", "RequirePackage", "documentclass"], "o m o"),
+]);
+
+/**
+ * Macros that print some arguments and not others: the index of the one argument that is a key or
+ * a URL. A citation (`o o m`) prints its `[…]` notes, not its `{…}` key; `\href` (`m m`) prints its
+ * link text, not its URL.
+ */
+export const KEY_ARGUMENT: ReadonlyMap<string, number> = new Map([
+  ...[...CITATION_MACROS].map((m) => [m, 2] as const),
+  ["href", 0],
+]);
+
+const LINK_SIGNATURES = Object.fromEntries(signed(["href"], "m m"));
+
+/**
+ * Declarations unified-latex has no signature for: signed so their arguments (sizes, not text)
+ * attach to them instead of standing beside them as groups a reader would seem to see.
+ */
+const DECLARATION_SIGNATURES = Object.fromEntries(signed(["fontsize"], "m m"));
+
+/**
+ * Macros that define other macros or environments. A heading in a body is no section where it is
+ * written, so the outline skips these; the rendered text reads a body as written, since nothing here
+ * expands macros. `\def` and its kin get a signature so the name and the body attach to them; a
+ * parameter text (`\def\x#1{…}`) is not modelled.
+ */
+export const DEFINITION_MACROS: ReadonlySet<string> = new Set([
+  "newcommand",
+  "renewcommand",
+  "providecommand",
+  "DeclareRobustCommand",
+  "newenvironment",
+  "renewenvironment",
+  "def",
+  "gdef",
+  "edef",
+  "xdef",
+]);
+
+const DEF_SIGNATURES = Object.fromEntries(
+  signed(["def", "gdef", "edef", "xdef"], "m m"),
+);
+
+// Not exported: a `ParsedTex` carries this property, and the one way to write it is `parseLatex`.
+const PARSED = Symbol("ParsedTex");
+
+/** A source and ITS tree: only `parseLatex` makes one, so a tree cannot be paired with another source. */
+export interface ParsedTex {
+  readonly src: string;
+  readonly root: Ast.Root;
+  readonly [PARSED]: true;
+}
+
+/** One parser for the process, made on first use: building one compiles its grammar. */
+const parser = once(() =>
+  getParser({
+    macros: {
+      ...KEY_SIGNATURES,
+      ...LINK_SIGNATURES,
+      ...DECLARATION_SIGNATURES,
+      ...DEF_SIGNATURES,
+    },
+  }),
+);
+
+/** A LaTeX source → its tree. */
+export const parseLatex = (src: string): ParsedTex => ({
+  src,
+  root: parser().parse(src),
+  [PARSED]: true,
+});

package/src/adapters/latex/rendered.ts

@@ -0,0 +1,59 @@
+/** The text a reader sees, each character with the source offset it came from. */
+import { hasAtLeast, sortBy } from "remeda";
+import type { Segment, TextRun } from "../../domain/tex-document.ts";
+import { isUnrendered } from "./hidden.ts";
+import {
+  isList,
+  stringText,
+  visited,
+  type Argument,
+  type Node,
+} from "./nodes.ts";
+import type { ParsedTex } from "./parse.ts";
+
+/** A node's rendered text and where it starts, or null when it is not text (it ends a run). */
+function segmentOf(n: Node | Argument): Segment | null {
+  const at = n.position?.start.offset;
+  if (at === undefined) return null;
+  if (n.type === "whitespace" || n.type === "parbreak")
+    return { text: " ", at };
+  if (n.type !== "string") return null;
+  return { text: stringText(n.content), at };
+}
+
+/** One node list → its runs: stretches of sibling text, split wherever anything else stands. */
+function runsOf(list: readonly (Node | Argument)[]): readonly TextRun[] {
+  const { done, current } = list.reduce<{
+    readonly done: readonly (readonly Segment[])[];
+    readonly current: readonly Segment[];
+  }>(
+    (acc, n) => {
+      const seg = segmentOf(n);
+      return seg === null
+        ? { done: [...acc.done, acc.current], current: [] }
+        : { done: acc.done, current: [...acc.current, seg] };
+    },
+    { done: [], current: [] },
+  );
+  return [...done, current].flatMap((g) =>
+    hasAtLeast(g, 1) &&
+    g
+      .map((x) => x.text)
+      .join("")
+      .trim() !== ""
+      ? [{ segments: g }]
+      : [],
+  );
+}
+
+/**
+ * Runs of rendered text, in document order: stretches of sibling strings and spaces. Everything
+ * else ends a run and is entered — a group's text, a macro's arguments — except what a reader never
+ * sees (`isUnrendered`): comments, math, code, the bibliography, keys and URLs. A macro definition's
+ * body is read where it is written.
+ */
+export const renderedRuns = (t: ParsedTex): readonly TextRun[] =>
+  sortBy(
+    visited(t.root, isUnrendered).filter(isList).flatMap(runsOf),
+    (r) => r.segments[0].at,
+  );

package/src/adapters/memory/index.ts

@@ -2,7 +2,7 @@
  * In-memory adapters for the app layer's tests: every port, no disk, no processes, no network.
  * Each one RECORDS what it was asked, so a test asserts on the calls instead of on side effects.
  */
-import type { AbsolutePath } from "../../domain/paths.ts";
+import { absolutePath } from "../../domain/paths.ts";
 import type { Download } from "../../ports/download.ts";
 import type { Files } from "../../ports/files.ts";
 import type { Command, ProcessExit, RunProcess } from "../../ports/process.ts";
@@ -69,11 +69,12 @@ export interface MemoryWorkspace extends Workspace {
 export function memoryWorkspace(dir = "/scratch"): MemoryWorkspace {
   const written: MemoryWorkspace["written"] = [];
   const ended: ("returned" | "threw")[] = [];
+  const at = absolutePath(dir);
   const scratch: Scratch = {
-    dir: dir as AbsolutePath,
+    dir: at,
     write(name, content, mode) {
       written.push({ name, content, mode });
-      return `${dir}/${name}` as AbsolutePath;
+      return absolutePath(`${dir}/${name}`);
     },
   };
   return {

package/src/adapters/node/files.test.ts

@@ -4,14 +4,16 @@ import { existsSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterAll as after, test } from "vitest";
-import type { AbsolutePath } from "../../domain/paths.ts";
+import { absolutePath, joinPath } from "../../domain/paths.ts";
 import { errorCode, nodeFiles } from "./files.io.ts";
 
-const root = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-files-test-")));
+const root = absolutePath(
+  realpathSync(mkdtempSync(join(tmpdir(), "paperlint-files-test-"))),
+);
 after(() => {
   rmSync(root, { recursive: true, force: true });
 });
-const at = (...p: string[]) => join(root, ...p) as AbsolutePath;
+const at = (...p: string[]) => joinPath(root, ...p);
 
 test("Files: a missing file reads as null and is not a file", () => {
   assert.equal(nodeFiles.readBytes(at("nope")), null);

package/src/adapters/node/process.io.ts

@@ -11,8 +11,15 @@ import {
 } from "node:child_process";
 import type { Command, ProcessExit, RunProcess } from "../../ports/process.ts";
 
-/** Node's `spawnSync`, or a stand-in with its shape (a harness records the calls through one). */
-export type SpawnSync = typeof spawnSync;
+/**
+ * Node's `spawnSync` — the one overload this file calls, text in and text out — or a stand-in with its
+ * shape (a harness records the calls through one).
+ */
+export type SpawnSync = (
+  file: string,
+  args: readonly string[],
+  options: SpawnSyncOptionsWithStringEncoding,
+) => SpawnSyncReturns<string>;
 
 const errno = (r: SpawnSyncReturns<string>): string | undefined =>
   codeOf(r.error);

package/src/adapters/node/process.test.ts

@@ -5,7 +5,7 @@
  */
 import assert from "node:assert/strict";
 import { test } from "vitest";
-import type { AbsolutePath } from "../../domain/paths.ts";
+import { absolutePath } from "../../domain/paths.ts";
 import type { Command } from "../../ports/process.ts";
 import { spawnProcess } from "./process.io.ts";
 
@@ -62,19 +62,19 @@ test("output past maxOutputBytes is a spawn failure, named by Node's own message
 });
 
 test("cwd is the Command's when it names one", () => {
-  const r = run.run({ ...sh("pwd"), cwd: "/" as AbsolutePath });
+  const r = run.run({ ...sh("pwd"), cwd: absolutePath("/") });
   assert.deepEqual(r.kind === "exited" && r.stdout, "/\n");
 });
 
 test("a spawn that reports no status, no signal and no error reads as exit 1, not success", () => {
-  const silent = spawnProcess((() => ({
+  const silent = spawnProcess(() => ({
     pid: 0,
     output: [],
     stdout: "",
     stderr: "",
     status: null,
     signal: null,
-  })) as never);
+  }));
   assert.deepEqual(silent.run(sh("true")), {
     kind: "exited",
     status: 1,

package/src/adapters/node/workspace.io.ts

@@ -10,14 +10,18 @@ import {
   writeFileSync,
 } from "node:fs";
 import { join } from "node:path";
-import type { AbsolutePath } from "../../domain/paths.ts";
+import {
+  absolutePath,
+  joinPath,
+  type AbsolutePath,
+} from "../../domain/paths.ts";
 import type { NotAPromise, Scratch, Workspace } from "../../ports/workspace.ts";
 
 function scratchIn(dir: AbsolutePath): Scratch {
   return {
     dir,
     write(name, content, mode): AbsolutePath {
-      const at = join(dir, name) as AbsolutePath;
+      const at = joinPath(dir, name);
       writeFileSync(at, content);
       if (mode === "exec") chmodSync(at, 0o755);
       return at;
@@ -29,9 +33,10 @@ function scratchIn(dir: AbsolutePath): Scratch {
 export function tmpWorkspace(tmpDir: string): Workspace {
   return {
     within<T>(prefix: string, use: (s: Scratch) => NotAPromise<T>): T {
-      const dir = realpathSync(mkdtempSync(join(tmpDir, prefix)));
+      // `realpath` answers with an absolute path, whatever `tmpDir` was.
+      const dir = absolutePath(realpathSync(mkdtempSync(join(tmpDir, prefix))));
       try {
-        return use(scratchIn(dir as AbsolutePath));
+        return use(scratchIn(dir));
       } finally {
         rmSync(dir, { recursive: true, force: true });
       }

package/src/adapters/pdfjs/fill.test.ts

@@ -1,7 +1,7 @@
 /**
  * `fill.ts` — what is recovered from pdf.js's exports for each text item: whether it is upright, and
  * the fill it was drawn in (the operator-list walk). Operator lists here are written by hand; the
- * real-PDF half runs in `pdf-facts.harness.ts` and `test/e2e/banal.ts`.
+ * real-PDF half runs in `pdf-facts.harness.ts` and `test/e2e/tex/banal.e2e.ts`.
  */
 import assert from "node:assert/strict";
 import { test } from "vitest";

package/src/adapters/pdfjs/fill.ts

@@ -154,14 +154,22 @@ export function fillsFor<T>(
   textOf: (item: T) => string,
 ): { readonly item: T; readonly fill: Fill }[] {
   const drawn = drawnCharacters(ops, list);
-  let at = 0;
-  const fillOf = (text: string): Fill => {
-    const want = Array.from(squeeze(text));
-    if (want.length === 0) return { kind: "unknown" };
-    const hit = findRun(drawn, want, at);
-    if (hit === null) return { kind: "unknown" };
-    at = hit.at + want.length;
-    return hit.fill;
-  };
-  return items.map((item) => ({ item, fill: fillOf(textOf(item)) }));
+  // Each item is searched for after the previous one's match: the offset threads through.
+  const { out } = items.reduce<{
+    readonly at: number;
+    readonly out: readonly { readonly item: T; readonly fill: Fill }[];
+  }>(
+    (acc, item) => {
+      const want = Array.from(squeeze(textOf(item)));
+      const hit = want.length === 0 ? null : findRun(drawn, want, acc.at);
+      return hit === null
+        ? { at: acc.at, out: [...acc.out, { item, fill: { kind: "unknown" } }] }
+        : {
+            at: hit.at + want.length,
+            out: [...acc.out, { item, fill: hit.fill }],
+          };
+    },
+    { at: 0, out: [] },
+  );
+  return [...out];
 }

package/src/adapters/references/index.ts

@@ -44,6 +44,7 @@ import type {
   BibEntry,
 } from "../../../skills/verify-citations/scripts/bib-authors.mjs";
 import { messageOf } from "../../domain/text.ts";
+import { isRecord } from "../../domain/record.ts";
 
 const describeAuthors = (f: AuthorFinding): string =>
   [
@@ -188,12 +189,16 @@ function grown(
 ): LookupCache {
   const { cache, usable } = loaded;
   const { store, dblp } = run;
-  const fresh = Object.entries(store).filter(([k]) => !usable.citations.has(k));
+  // verify-cites stores each answer as an object; only such a value is a response the cache can hold.
+  const fresh = Object.entries(store).filter(
+    (e): e is [string, Readonly<Record<string, unknown>>] =>
+      !usable.citations.has(e[0]) && isRecord(e[1]),
+  );
   const freshDblp = [...dblp].filter(([k]) => !usable.dblp.has(k));
   if (fresh.length === 0 && freshDblp.length === 0) return cache;
   const dated = fresh.map(([k, response]): [string, CachedResponse] => [
     k,
-    { fetched: today(), response: response as CachedResponse["response"] },
+    { fetched: today(), response },
   ]);
   return {
     citations: new Map([...cache.citations, ...dated]),

package/src/build-engine.test.ts

@@ -9,6 +9,7 @@ import { dirname, join } from "node:path";
 import { test } from "vitest";
 import { useTempDir } from "../test/support.ts";
 import { prepareEngine, refusal } from "./build-engine.ts";
+import type { Runner } from "./engine.ts";
 
 const work = useTempDir("paperlint-build-engine-test-");
 const TEX = { packages: { acmart: ["acmart.cls"] }, tools: {} };
@@ -20,11 +21,12 @@ const texAt = (dir: string): string => {
   return dir;
 };
 /** kpsewhich answers per bin directory. */
-const fakeRun = (found: Record<string, string>) =>
-  ((cmd: string) => ({
+const fakeRun =
+  (found: Record<string, string>): Runner =>
+  (cmd) => ({
     stdout: found[dirname(cmd)] ?? "",
     status: 0,
-  })) as never;
+  });
 
 async function go(o: Parameters<typeof prepareEngine>[0]) {
   const out: string[] = [];
@@ -101,7 +103,10 @@ test("a complete cache is used from an environment with no PATH at all", async (
 
 test("the refusal line for a decision to use a tree names nothing missing", () => {
   assert.equal(
-    refusal({ kind: "use-cache" } as never, { system: null } as never),
+    refusal(
+      { kind: "use-cache", tree: { label: "cache", bin: "/b", missing: [] } },
+      { system: null },
+    ),
     "✗ paperlint build: no TeX Live with every package these papers need — run `npx paperlint toolchain` (missing: 0 package(s): )",
   );
 });
@@ -122,14 +127,14 @@ test("without an ask or an install given: Enter is yes, and the default install
       PAPERLINT_CTAN_MIRROR: "https://mirror.invalid/tlnet",
       PATH: join(work, "nothing"),
     },
-    run: ((cmd: string) => {
+    run: (cmd) => {
       calls.push(cmd.split("/").pop() ?? cmd);
       return {
         status: 22,
         stdout: "",
         stderr: "curl: (6) could not resolve\n",
       };
-    }) as never,
+    },
   });
   assert.deepEqual(r, { ok: false, code: 1 });
   assert.ok(calls.includes("curl"), calls.join(","));