paperlint 3.1.3 → 3.2.0

package/skills/verify-citations/scripts/bib-authors.d.mts

@@ -0,0 +1,63 @@
+// Types for bib-authors.mjs, for the exports `src/` imports — the same arrangement as
+// `verify-cites.d.mts` beside it. Only what `src/` imports is declared.
+
+/** One entry as `parseBib` returns it; a field the entry lacks is "". */
+export interface BibEntry {
+  readonly type: string;
+  readonly key: string;
+  readonly author: string;
+  readonly title: string;
+  readonly booktitle: string;
+  readonly journal: string;
+}
+
+export declare function parseBib(text: string): BibEntry[];
+
+/** True when the author list ends in `and others` — there is nothing complete to compare. */
+export declare const truncated: (authorField: string) => boolean;
+
+/** True when the entry names a venue that is not a preprint server. */
+export declare function claimsPublished(
+  entry: Pick<BibEntry, "booktitle" | "journal">,
+): boolean;
+
+/** One DBLP search hit, as `dblpHits` normalises it. */
+export interface DblpHit {
+  readonly venue: string;
+  readonly year: string;
+  readonly type: string;
+  readonly title: string;
+  readonly authors: readonly string[];
+}
+
+/** DBLP's hits for a title; throws on a failed request (with `retryable` for a 429). */
+export declare function dblpHits(title: string): Promise<DblpHit[]>;
+
+export interface AuthorFinding {
+  readonly key: string;
+  readonly venue: string;
+  readonly missing: readonly string[];
+  readonly extra: readonly string[];
+  readonly orderDiffers: boolean;
+}
+
+export interface KeyWhy {
+  readonly key: string;
+  readonly why: string;
+}
+
+/** The buckets of one comparison; an entry in none of them was a preprint entry. */
+export interface AuthorBuckets {
+  readonly findings: readonly AuthorFinding[];
+  readonly skipped: readonly KeyWhy[];
+  readonly unchecked: readonly KeyWhy[];
+  readonly matched: readonly string[];
+}
+
+export declare function checkAuthors(
+  parsed: readonly BibEntry[],
+  options?: {
+    readonly lookup?: (title: string) => Promise<readonly DblpHit[]>;
+    readonly pause?: (ms: number) => Promise<void> | void;
+  },
+): Promise<AuthorBuckets>;

package/skills/verify-citations/scripts/bib-authors.mjs

@@ -45,10 +45,7 @@
  */
 import { readFileSync, existsSync, readdirSync } from "node:fs";
 import { join, extname } from "node:path";
-import {
-  headings as mdHeadings,
-  requireMarkdown,
-} from "../../../lib/markdown.mjs";
+import { headings as mdHeadings, requireMarkdown } from "#lib/markdown";
 import { isMain } from "../../paper-pipeline/scripts/consumer.mjs";
 
 const DBLP = "https://dblp.org/search/publ/api";

package/skills/verify-citations/scripts/{verify-cites.cli.test.mjs → verify-cites.cli.test.ts}

@@ -9,7 +9,23 @@ import { readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { test } from "vitest";
-import { runNode, useTempDir, writeTree } from "../../../test/support.mjs";
+import { z } from "zod";
+import {
+  runNode,
+  useTempDir,
+  writeTree,
+  type ScriptResult,
+} from "../../../test/support.ts";
+
+/** The verdicts `verify-cites --json`… prints: one per citation, with the fields these tests read. */
+const Verdicts = z.array(
+  z.looseObject({
+    id: z.unknown().optional(),
+    verdict: z.unknown().optional(),
+    flags: z.array(z.unknown()).nullish(),
+  }),
+);
+const Cache = z.record(z.string(), z.unknown());
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const root = useTempDir("verify-cites-cli-");
@@ -48,12 +64,17 @@ writeTree(root, {
     "  return new Response(null, { status: 404 });\n};\n",
   "consumer/paperlint.json": JSON.stringify({ contactEmail: "me@example.org" }),
 });
-const offline = (args, opts = {}) =>
-  runNode(SCRIPT, [...args, "--offline"], { env, ...opts });
-const parsed = (r) => ({ ...r, stdout: JSON.parse(r.stdout) });
-const SUMMARY_PASS = (n, t, u, flagged) =>
-  `\nverify-cites: ${n} citation(s) — ${t} true, 0 false (fabrication), ${u} unresolvable` +
-  (flagged ? `, ${flagged} with hygiene flag(s)` : "") +
+const offline = (
+  args: readonly string[],
+  opts: { input?: string } = {},
+): ScriptResult => runNode(SCRIPT, [...args, "--offline"], { env, ...opts });
+const parsed = (r: ScriptResult) => ({
+  ...r,
+  stdout: Verdicts.parse(JSON.parse(r.stdout)),
+});
+const SUMMARY_PASS = (n: number, t: number, u: number, flagged: number) =>
+  `\nverify-cites: ${String(n)} citation(s) — ${String(t)} true, 0 false (fabrication), ${String(u)} unresolvable` +
+  (flagged ? `, ${String(flagged)} with hygiene flag(s)` : "") +
   "\nPASS — no fabrication (unresolvable is advisory)\n";
 
 test("-h is --help", () => {
@@ -118,9 +139,11 @@ test("online, a DOI the authority does not know is FALSE: FAIL, exit 1, and the
   assert.deepEqual(
     {
       status: r.status,
-      verdicts: JSON.parse(r.stdout).map((x) => x.verdict),
+      verdicts: Verdicts.parse(JSON.parse(r.stdout)).map((x) => x.verdict),
       tail: r.stderr.trim().split("\n").pop(),
-      cached: Object.keys(JSON.parse(readFileSync(CACHE, "utf8"))).sort(),
+      cached: Object.keys(
+        Cache.parse(JSON.parse(readFileSync(CACHE, "utf8"))),
+      ).sort(),
     },
     {
       status: 1,

package/skills/verify-citations/scripts/verify-cites.d.mts

@@ -0,0 +1,58 @@
+// Types for verify-cites.mjs, for the exports `src/` imports — the same arrangement as
+// `skills/paper-pipeline/scripts/consumer.d.mts`. Without this file TypeScript sees an untyped
+// module, and every import needed a `@ts-expect-error` plus a cast at each call.
+//
+// Only what `src/` imports is declared. The `.mjs` is not typechecked, so a declaration nobody
+// compiles against would drift without anyone noticing.
+
+/** One entry as `parseBib` returns it: the BibTeX key as `id`, plus the fields it recognised. */
+export interface Citation {
+  readonly id: string;
+  readonly [field: string]: unknown;
+}
+
+/** Every entry of a BibTeX text, `@comment`/`@string`/`@preamble` skipped. */
+export declare function parseBib(text: string): Citation[];
+
+/** The title reduced to what identifies it: case, braces and punctuation removed. */
+export declare function titleIdentity(title: string): string;
+
+/** Answers the resolvers gave, keyed by request — shared between citations and runs. */
+export type ResponseCache = Record<string, unknown>;
+
+/** Would verifying `citation` make a request, given `cache`? Answers from the cache only. */
+export declare function wouldAsk(
+  citation: Citation,
+  cache: ResponseCache,
+): Promise<boolean>;
+
+/** One run's memory of which service refused: a refusing service is not asked again. */
+export interface Breaker {
+  call<T>(
+    service: string,
+    attempt: () => Promise<
+      { ok: true; value: T } | { ok: false; reason: string }
+    >,
+  ): Promise<{ ok: true; value: T } | { ok: false; reason: string }>;
+}
+
+export declare function createBreaker(): Breaker;
+
+/** The verdict on one citation. */
+export interface CiteVerdict {
+  readonly id: string;
+  readonly verdict: "true" | "false" | "unresolvable";
+  readonly reason?: string;
+  /** "<service>: <reason>" for each question a refusing service did not answer. */
+  readonly refused?: readonly string[];
+}
+
+/** Verify ONE citation live, answering from `cache` first and writing new answers into it. */
+export declare function verifyCitationLive(
+  citation: Citation,
+  options?: {
+    readonly cache?: ResponseCache;
+    readonly offline?: boolean;
+    readonly breaker?: Breaker;
+  },
+): Promise<CiteVerdict>;

package/src/CLAUDE.md

@@ -35,7 +35,7 @@ through the `io` file category in `boundaries/dependencies`; the `process` and `
 carries `// eslint-disable-next-line <rule> -- legacy <I/O|layer>, moves behind a port in #76`.
 Unused directives are errors (`reportUnusedDisableDirectives`), so a fixed site must drop its
 comment; the per-file counts are frozen in `scripts/layer-legacy.frozen.json` and checked by
-`scripts/layer-legacy-frozen.mjs` (`npm run check`, CI), which counts ESLint's own
+`scripts/layer-legacy-frozen.ts` (`npm run check`, CI), which counts ESLint's own
 `suppressedMessages` and fails when a file's count grows, a file not in the list carries one, or
 anything under `src/domain/`, `src/ports/` or `src/adapters/` does. A NEW module that needs the
 world is a new `*.io.ts` in the adapter of the program it talks to — never a new directive.

package/src/adapters/banal/index.test.ts

@@ -2,7 +2,7 @@
  * `adapters/banal/index.ts` — banal as the two ports the app sees. What `run.test.ts` checks in
  * banal's own terms is checked here as the domain receives it: a `Geometry` whose provenance names
  * banal and the rule that found it, a reason that is one line of text, a `Ready` that says what was
- * verified. In-memory ports throughout; the real banal is `test/e2e/banal.mjs`.
+ * verified. In-memory ports throughout; the real banal is `test/e2e/banal.ts`.
  */
 import assert from "node:assert/strict";
 import { test } from "vitest";
@@ -44,15 +44,12 @@ test("with $BANAL: banal gets the .xml and a quoted $PDFTOHTML, and the geometry
   const { m, run } = measurer({ BANAL: "/own/banal" });
   const g = m.measure([]);
   assert.equal(g.kind, "measured");
-  assert.deepEqual(g.kind === "measured" && g.by, {
+  assert.deepEqual(g.by, {
     tool: "banal",
     path: "/own/banal",
     how: "$BANAL",
   });
-  assert.deepEqual(
-    g.kind === "measured" && [g.geometry.columns, g.geometry.bodyPages],
-    [2, 1],
-  );
+  assert.deepEqual([g.geometry.columns, g.geometry.bodyPages], [2, 1]);
   const c = run.calls[0];
   // Guards: the poppler-free path — banal is handed paperlint's XML, never the PDF.
   assert.match(c?.args.at(-1) ?? "", /\.xml$/);

package/src/adapters/banal/index.ts

@@ -65,12 +65,15 @@ export function banalMeasurer(
 }
 
 /** The one place banal's `Ready` is minted: from an `Installed`, whose `PinnedBanal` only run.ts mints. */
-const ready = (i: Installed): Ready =>
-  ({
-    where: i.banal.path as string,
+const ready = (i: Installed): Ready => {
+  // Widened by annotation: the brand of the path is not part of `Ready`'s shape.
+  const where: string = i.banal.path;
+  return {
+    where,
     fresh: i.fresh,
     verified: "sha256 verified, and it measured a probe page",
-  }) as Ready;
+  } as Ready;
+};
 
 /**
  * banal as the `ToolInstaller` port: download at the pin, check the sha256, accept by measuring a

package/src/adapters/banal/invocation.test.ts

@@ -51,7 +51,9 @@ test("shQuote survives a single quote", () => {
 });
 
 const root = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-stage-test-")));
-after(() => rmSync(root, { recursive: true, force: true }));
+after(() => {
+  rmSync(root, { recursive: true, force: true });
+});
 
 test("🔴 stage: on a real scratch directory the stub answers `-v` through the shell, from a path with a space and a quote", () => {
   const awkward = join(root, "it's a dir");

package/src/adapters/banal/invocation.ts

@@ -7,7 +7,7 @@
  * (`Error: Failed to run pdftohtml`, measured); told a version below 0.85 it applies a larger
  * correction and every font size moves. So `$PDFTOHTML` (banal's own override, line 166) points at a
  * stub that answers `-v` with `XML_DIALECT.version` — the pdftohtml whose XML `xml.ts` writes — and
- * refuses anything else. `test/e2e/banal.mjs` shows both failures with the real banal.
+ * refuses anything else. `test/e2e/banal.ts` shows both failures with the real banal.
  */
 import type { Opaque } from "ts-essentials";
 import type { AbsolutePath } from "../../domain/paths.ts";

package/src/adapters/banal/output.test.ts

@@ -1,6 +1,6 @@
 /**
  * `output.ts` — every way a banal run can end, as a table of `ProcessExit` → `Result`, and the
- * measurement → geometry projection. Pure: no perl, no disk. The real banal is `test/e2e/banal.mjs`.
+ * measurement → geometry projection. Pure: no perl, no disk. The real banal is `test/e2e/banal.ts`.
  */
 import assert from "node:assert/strict";
 import { test } from "vitest";

package/src/adapters/banal/run.test.ts

@@ -1,7 +1,7 @@
 /**
  * `adapters/banal/run.ts` — running and installing banal, on in-memory ports: which `Command` it builds, what it stages,
  * what it downloads and writes, and what it concludes. No perl, no disk, no network: the adapters
- * record, and each assertion reads the record. Real perl and the real banal are `test/e2e/banal.mjs`;
+ * record, and each assertion reads the record. Real perl and the real banal are `test/e2e/banal.ts`;
  * the adapters' own behaviour is `src/adapters/node/*.test.ts`.
  */
 import assert from "node:assert/strict";
@@ -45,10 +45,10 @@ test("measureGeometry: perl runs the found banal on the staged XML, and the geom
   });
   const g = measureGeometry(io, s, project, []);
   assert.equal(g.source, "banal");
-  assert.equal(g.source === "banal" && g.geometry.bodyPt, 10.3);
+  assert.equal(g.geometry.bodyPt, 10.3);
   const [c] = run.calls;
   assert.equal(c?.file, "perl");
-  assert.equal(c?.args.at(-1), "/scratch/paper.xml");
+  assert.equal(c.args.at(-1), "/scratch/paper.xml");
   // Guards: both files staged, once, and the scratch scope ended normally (cleanup ran).
   assert.deepEqual(
     workspace.written.map((w) => [w.name, w.mode]),

package/src/adapters/banal/xml.test.ts

@@ -4,7 +4,7 @@
  *
  * Every page here is written by hand. The real-PDF half — pdf.js boxes of a committed fixture,
  * written as XML, measured by the real banal and compared with banal on real pdftohtml — is
- * `test/e2e/banal.mjs`, which runs where `paperlint toolchain` has installed banal.
+ * `test/e2e/banal.ts`, which runs where `paperlint toolchain` has installed banal.
  */
 import assert from "node:assert/strict";
 import { test } from "vitest";

package/src/adapters/curl/download.test.ts

@@ -23,7 +23,9 @@ import { spawnProcess } from "../node/index.ts";
 const root = realpathSync(
   mkdtempSync(join(tmpdir(), "paperlint-download-test-")),
 );
-after(() => rmSync(root, { recursive: true, force: true }));
+after(() => {
+  rmSync(root, { recursive: true, force: true });
+});
 const at = (...p: string[]) => join(root, ...p) as AbsolutePath;
 
 const dl = (env: Record<string, string>) => {
@@ -45,7 +47,7 @@ test("Download: a URL that does not answer is a failure with curl's words", () =
   const { d } = dl({ PATH: "/usr/bin:/bin" });
   const r = d.fetch(pathToFileURL(at("missing")).href, 10_000);
   assert.equal(r.ok, false);
-  assert.ok(!r.ok && r.error.detail.length > 0);
+  assert.ok(r.error.detail.length > 0);
 });
 
 test("🔴 Download: no curl on PATH is named as that, not as a failed URL", () => {

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

@@ -10,10 +10,10 @@ import {
 import { dirname } from "node:path";
 import type { AbsolutePath } from "../../domain/paths.ts";
 import type { Files } from "../../ports/files.ts";
+import { codeOf } from "../../domain/text.ts";
 
 /** An error's errno code; anything thrown that is not an Error has none. */
-export const errorCode = (e: unknown): unknown =>
-  e instanceof Error ? (e as NodeJS.ErrnoException).code : undefined;
+export const errorCode = (e: unknown): unknown => codeOf(e);
 
 export const nodeFiles: Files = {
   isFile(p: AbsolutePath): boolean {

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

@@ -8,7 +8,9 @@ import type { AbsolutePath } from "../../domain/paths.ts";
 import { errorCode, nodeFiles } from "./files.io.ts";
 
 const root = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-files-test-")));
-after(() => rmSync(root, { recursive: true, force: true }));
+after(() => {
+  rmSync(root, { recursive: true, force: true });
+});
 const at = (...p: string[]) => join(root, ...p) as AbsolutePath;
 
 test("Files: a missing file reads as null and is not a file", () => {

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

@@ -3,6 +3,7 @@
  * it — `error`, `status`, `signal`, all nullable — and turns it into a `ProcessExit`, so no caller
  * re-derives "what happened" from three fields.
  */
+import { codeOf, printed } from "../../domain/text.ts";
 import {
   spawnSync,
   type SpawnSyncOptionsWithStringEncoding,
@@ -14,13 +15,13 @@ import type { Command, ProcessExit, RunProcess } from "../../ports/process.ts";
 export type SpawnSync = typeof spawnSync;
 
 const errno = (r: SpawnSyncReturns<string>): string | undefined =>
-  (r.error as NodeJS.ErrnoException | undefined)?.code;
+  codeOf(r.error);
 
 /** What a finished `spawnSync` came to. ENOENT is the executable itself: `c.file` was not found. */
 export function exitOf(r: SpawnSyncReturns<string>, c: Command): ProcessExit {
   const out = {
-    stdout: String(r.stdout ?? ""),
-    stderr: String(r.stderr ?? ""),
+    stdout: printed(r.stdout),
+    stderr: printed(r.stderr),
   };
   const code = errno(r);
   if (code === "ENOENT") return { kind: "not-found", file: c.file };

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

@@ -58,7 +58,7 @@ test("a program killed by a signal is `signalled`, with what it printed first",
 test("output past maxOutputBytes is a spawn failure, named by Node's own message", () => {
   const r = run.run({ ...sh("head -c 100000 /dev/zero"), maxOutputBytes: 10 });
   assert.equal(r.kind, "spawn-failed");
-  assert.match(r.kind === "spawn-failed" ? r.message : "", /ENOBUFS/);
+  assert.match(r.message, /ENOBUFS/);
 });
 
 test("cwd is the Command's when it names one", () => {

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

@@ -20,7 +20,9 @@ import { afterAll as after, test } from "vitest";
 import { tmpWorkspace } from "./workspace.io.ts";
 
 const root = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-ws-test-")));
-after(() => rmSync(root, { recursive: true, force: true }));
+after(() => {
+  rmSync(root, { recursive: true, force: true });
+});
 
 test("the directory exists inside the scope and is gone after it", () => {
   const ws = tmpWorkspace(root);

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.mjs` and `test/e2e/banal.mjs`.
+ * real-PDF half runs in `pdf-facts.harness.ts` and `test/e2e/banal.ts`.
  */
 import assert from "node:assert/strict";
 import { test } from "vitest";
@@ -34,7 +34,7 @@ const OPS = {
   showText: 5,
   showSpacedText: 6,
 };
-const glyphs = (s: string) => [[...s].map((unicode) => ({ unicode }))];
+const glyphs = (s: string) => [Array.from(s, (unicode) => ({ unicode }))];
 const ops = (...pairs: [number, unknown?][]): OperatorList => ({
   fnArray: pairs.map((p) => p[0]),
   argsArray: pairs.map((p) => p[1] ?? null),

package/src/adapters/pdfjs/fill.ts

@@ -33,9 +33,12 @@ export interface OperatorList {
 /** Text as the walk compares it: normalised, with no whitespace (items and glyphs split spaces differently). */
 const squeeze = (s: string): string => s.normalize("NFKC").replace(/\s+/g, "");
 
+/** An operator's argument list; pdf.js types it `any`, and a malformed one reads as empty. */
+const listOf = (v: unknown): readonly unknown[] => (Array.isArray(v) ? v : []);
+
 /** `setFillRGBColor`'s argument: a `#rrggbb` string in current pdf.js, three 0-255 numbers in older ones. */
 export function hexOf(args: unknown): string {
-  const a = Array.isArray(args) ? (args as unknown[]) : [];
+  const a = listOf(args);
   if (typeof a[0] === "string") return a[0].toLowerCase();
   const byte = (v: unknown): string =>
     Math.round(typeof v === "number" ? v : 0)
@@ -46,12 +49,13 @@ export function hexOf(args: unknown): string {
 
 /** The characters a show-text operator draws, from its glyph objects. */
 function glyphText(args: unknown): string {
-  const a = Array.isArray(args) ? (args as unknown[]) : [];
-  const glyphs = Array.isArray(a[0]) ? (a[0] as unknown[]) : [];
+  const glyphs = listOf(listOf(args)[0]);
   return glyphs
     .map((g) =>
       typeof g === "object" && g !== null && "unicode" in g
-        ? String((g as { unicode: unknown }).unicode ?? "")
+        ? typeof g.unicode === "string"
+          ? g.unicode
+          : ""
         : "",
     )
     .join("");
@@ -76,7 +80,7 @@ function applyState(
   else if (fn === ops.setFillRGBColor)
     s.cur.fill = { kind: "rgb", hex: hexOf(args) };
   else if (fn === ops.setTextRenderingMode)
-    s.cur.mode = Number((args as unknown[] | undefined)?.[0] ?? 0);
+    s.cur.mode = Number(listOf(args)[0] ?? 0);
   else return false;
   return true;
 }
@@ -89,7 +93,10 @@ interface Drawn {
 
 /** Every drawn character, in content order, with the fill it was drawn in. */
 export function drawnCharacters(ops: ColourOps, list: OperatorList): Drawn[] {
-  const s = { cur: { fill: { kind: "unknown" } as Fill, mode: 0 }, stack: [] };
+  const s: { cur: State; stack: State[] } = {
+    cur: { fill: { kind: "unknown" }, mode: 0 },
+    stack: [],
+  };
   const drawn: Drawn[] = [];
   list.fnArray.forEach((fn, i) => {
     const args = list.argsArray[i];
@@ -149,7 +156,7 @@ export function fillsFor<T>(
   const drawn = drawnCharacters(ops, list);
   let at = 0;
   const fillOf = (text: string): Fill => {
-    const want = [...squeeze(text)];
+    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" };

package/src/adapters/references/index.test.ts

@@ -10,7 +10,6 @@ import {
   EMPTY_LOOKUP_CACHE,
   type LookupCache,
 } from "../../domain/lookup-cache.ts";
-// @ts-expect-error — a skill script in .mjs, it has no types
 import * as cites from "../../../skills/verify-citations/scripts/verify-cites.mjs";
 
 /** The verdicts of a cold run — an empty cache, the adapter the CLI wires. */
@@ -46,29 +45,29 @@ const dblp = (title: string, authors: string[]) =>
 /** Route by URL prefix; the longest prefix wins. */
 function fakeFetch(routes: Record<string, () => Response>): string[] {
   const calls: string[] = [];
-  vi.stubGlobal("fetch", async (url: string) => {
+  vi.stubGlobal("fetch", (url: string) => {
     calls.push(url);
-    const hit = Object.keys(routes)
-      .filter((p) => url.startsWith(p))
-      .sort((a, b) => b.length - a.length)[0];
-    if (hit === undefined) return json(404);
-    return routes[hit]!();
+    const hit = Object.entries(routes)
+      .filter(([p]) => url.startsWith(p))
+      .sort(([a], [b]) => b.length - a.length)[0];
+    return Promise.resolve(hit === undefined ? json(404) : hit[1]());
   });
   return calls;
 }
 
 /** Await `p` while fake time runs, so DBLP's pauses between requests elapse at once. */
 async function settle<T>(p: Promise<T>): Promise<T> {
-  let done = false;
-  const out = p.finally(() => (done = true));
-  while (!done) await vi.advanceTimersByTimeAsync(1000);
+  // A field, not a `let`: the flag is set in a callback, which flow analysis cannot see.
+  const state = { done: false };
+  const out = p.finally(() => (state.done = true));
+  while (!state.done) await vi.advanceTimersByTimeAsync(1000);
   return out;
 }
 
 test("no service answers: not-checked, with the reason", async () => {
-  vi.stubGlobal("fetch", async () => {
-    throw new Error("getaddrinfo ENOTFOUND api.crossref.org");
-  });
+  vi.stubGlobal("fetch", () =>
+    Promise.reject(new Error("getaddrinfo ENOTFOUND api.crossref.org")),
+  );
   assert.deepEqual(await checkOnly("@misc{k, title={T}}"), {
     kind: "not-checked",
     why: "the citation services cannot be reached (getaddrinfo ENOTFOUND api.crossref.org)",
@@ -104,19 +103,19 @@ test("each entry gets its existence and its authors: confirmed, fabricated, mism
   const r = await settle(checkOnly(bib));
   assert.equal(r.kind, "checked");
   const byKey = Object.fromEntries(
-    (r.kind === "checked" ? r.entries : []).map((e) => [
-      e.key,
-      [e.exists, e.authors, e.why ?? ""],
-    ]),
+    r.entries.map((e) => [e.key, [e.exists, e.authors, e.why ?? ""]]),
   );
   assert.deepEqual(
     {
-      good: byKey["good"]!.slice(0, 2),
-      fake: byKey["fake"]!.slice(0, 2),
-      drift: byKey["drift"]!.slice(0, 2),
-      driftWhy: String(byKey["drift"]![2]).split("; ").pop(),
-      flaky: [byKey["flaky"]![1], String(byKey["flaky"]![2]).split("; ").pop()],
-      pre: byKey["pre"]!.slice(0, 2),
+      good: byKey["good"]?.slice(0, 2),
+      fake: byKey["fake"]?.slice(0, 2),
+      drift: byKey["drift"]?.slice(0, 2),
+      driftWhy: String(byKey["drift"]?.[2]).split("; ").pop(),
+      flaky: [
+        byKey["flaky"]?.[1],
+        String(byKey["flaky"]?.[2]).split("; ").pop(),
+      ],
+      pre: byKey["pre"]?.slice(0, 2),
     },
     {
       good: ["true", "match"],
@@ -209,20 +208,14 @@ test(
     slowFetch(40);
     const bib = manyBib(20);
     const serial: string[] = [];
-    for (const c of cites.parseBib(bib) as { id: string }[])
-      serial.push(
-        (
-          (await cites.verifyCitationLive(c, { cache: {} })) as {
-            verdict: string;
-          }
-        ).verdict,
-      );
+    for (const c of cites.parseBib(bib))
+      serial.push((await cites.verifyCitationLive(c, { cache: {} })).verdict);
     const t0 = Date.now();
     const r = await checkOnly(bib);
     const ms = Date.now() - t0;
     assert.equal(r.kind, "checked");
     assert.deepEqual(
-      r.kind === "checked" ? r.entries.map((e) => e.exists) : [],
+      r.entries.map((e) => e.exists),
       serial,
     );
     assert.ok(ms < (20 * 200) / 2, `${String(ms)} ms for 20 lookups`);
@@ -249,7 +242,7 @@ const PAPERS = [
   "@inproceedings{good, author={Ada Lovelace}, title={Good Paper}, booktitle={ICSE}, doi={10.1/good}}",
   "@inproceedings{other, author={Ada Lovelace}, title={Other Paper}, booktitle={ICSE}}",
   "@misc{pre, author={Ada Lovelace}, title={A Preprint}, journal={arXiv preprint}}",
-];
+] as const;
 /** Every service answers; DBLP knows "Good Paper" and nothing else. */
 const answering = () =>
   fakeFetch({
@@ -414,7 +407,7 @@ test("a failed lookup is not cached: the next run asks it again", async () => {
     "https://api.crossref.org/": () => json(200, { message: { items: [] } }),
     "https://dblp.org/": () => json(500),
   });
-  const bib = PAPERS[1]!;
+  const bib = PAPERS[1];
   const r = await settle(cached(bib, EMPTY_LOOKUP_CACHE));
   const failed: LookupCache = r.cache;
   assert.deepEqual(
@@ -427,10 +420,10 @@ test("a failed lookup is not cached: the next run asks it again", async () => {
 });
 
 test("offline with an incomplete cache: not-checked, and the cache comes back unchanged", async () => {
-  vi.stubGlobal("fetch", async () => {
-    throw new Error("getaddrinfo ENOTFOUND api.crossref.org");
-  });
-  const r = await cached(PAPERS[0]!, EMPTY_LOOKUP_CACHE);
+  vi.stubGlobal("fetch", () =>
+    Promise.reject(new Error("getaddrinfo ENOTFOUND api.crossref.org")),
+  );
+  const r = await cached(PAPERS[0], EMPTY_LOOKUP_CACHE);
   assert.deepEqual(r, {
     check: {
       kind: "not-checked",