paperlint 3.1.3 → 3.2.0

package/src/adapters/references/index.ts

@@ -35,29 +35,15 @@ import { sleep, todayUtc } from "./clock.io.ts";
 
 /** Citations looked up at once (#107). */
 const LOOKUPS_IN_FLIGHT = 6;
-// @ts-expect-error — a skill script in .mjs, it has no types
 import * as cites from "../../../skills/verify-citations/scripts/verify-cites.mjs";
-// @ts-expect-error — a skill script in .mjs, it has no types
+import type { CiteVerdict } from "../../../skills/verify-citations/scripts/verify-cites.mjs";
 import * as authors from "../../../skills/verify-citations/scripts/bib-authors.mjs";
-
-interface CiteResult {
-  readonly id: string;
-  readonly verdict: "true" | "false" | "unresolvable";
-  readonly reason?: string;
-  /** "<service>: <reason>" for each question a refusing service did not answer (#120). */
-  readonly refused?: readonly string[];
-}
-interface AuthorFinding {
-  readonly key: string;
-  readonly venue: string;
-  readonly missing: readonly string[];
-  readonly extra: readonly string[];
-  readonly orderDiffers: boolean;
-}
-interface KeyWhy {
-  readonly key: string;
-  readonly why: string;
-}
+import type {
+  AuthorBuckets,
+  AuthorFinding,
+  BibEntry,
+} from "../../../skills/verify-citations/scripts/bib-authors.mjs";
+import { messageOf } from "../../domain/text.ts";
 
 const describeAuthors = (f: AuthorFinding): string =>
   [
@@ -68,13 +54,6 @@ const describeAuthors = (f: AuthorFinding): string =>
     .filter(Boolean)
     .join("; ") + ` (DBLP: ${f.venue})`;
 
-interface AuthorBuckets {
-  readonly findings: readonly AuthorFinding[];
-  readonly skipped: readonly KeyWhy[];
-  readonly unchecked: readonly KeyWhy[];
-  readonly matched: readonly string[];
-}
-
 const authorsOf = (key: string, a: AuthorBuckets): EntryVerdict["authors"] =>
   a.findings.some((f) => f.key === key)
     ? "mismatch"
@@ -90,7 +69,7 @@ const authorsOf = (key: string, a: AuthorBuckets): EntryVerdict["authors"] =>
  * confirmed work: a refusal after a confirmation changed nothing.
  */
 const unconfirmed = (
-  c: CiteResult | undefined,
+  c: CiteVerdict | undefined,
 ): readonly (string | undefined)[] =>
   c && c.verdict !== "true"
     ? [c.reason, ...(c.refused ?? []).map((r) => `not asked: ${r}`)]
@@ -99,7 +78,7 @@ const unconfirmed = (
 /** One entry's verdict from the two checkers' answers. */
 function entryVerdict(
   key: string,
-  found: readonly CiteResult[],
+  found: readonly CiteVerdict[],
   a: AuthorBuckets,
 ): EntryVerdict {
   const c = found.find((x) => x.id === key);
@@ -119,27 +98,21 @@ function entryVerdict(
   };
 }
 
-interface BibAuthorsEntry {
-  readonly key: string;
-  readonly title: string;
-  readonly author: string;
-}
-
 /** Whether bib-authors will ask DBLP about this entry — the filter its `checkAuthors` applies. */
-const asksDblp = (e: BibAuthorsEntry): boolean =>
+const asksDblp = (e: BibEntry): boolean =>
   Boolean(e.title && e.author) &&
-  (authors.claimsPublished(e) as boolean) &&
-  !(authors.truncated(e.author) as boolean);
+  authors.claimsPublished(e) &&
+  !authors.truncated(e.author);
 
 /** Is every question this bibliography would ask already answered in `cache`? */
 async function fullyCached(
-  citations: readonly object[],
-  entries: readonly BibAuthorsEntry[],
+  citations: readonly cites.Citation[],
+  entries: readonly BibEntry[],
   cache: LookupCache,
   store: Readonly<Record<string, unknown>>,
 ): Promise<boolean> {
   const asks = await Promise.all(
-    citations.map((c) => cites.wouldAsk(c, store) as Promise<boolean>),
+    citations.map((c) => cites.wouldAsk(c, store)),
   );
   return (
     !asks.includes(true) &&
@@ -185,11 +158,11 @@ function cachedDblp(cache: LookupCache, today: () => string) {
       if (refused !== null)
         throw new Error(`DBLP refused earlier in this run (${refused})`);
       try {
-        const hits = (await authors.dblpHits(title)) as DblpHit[];
+        const hits = await authors.dblpHits(title);
         dblp.set(dblpTitleKey(title), { fetched: today(), title, hits });
         return hits;
       } catch (e) {
-        refused = (e as Error).message;
+        refused = messageOf(e);
         throw new Error(`DBLP refused earlier in this run (${refused})`);
       }
     },
@@ -234,10 +207,8 @@ export const referencesChecker =
   async (bib, cache) => {
     // Answers past MAX_AGE_DAYS are left out, so the run asks them again (and `grown` re-dates them).
     const usable = freshPart(cache, today());
-    const citations = (cites.parseBib(bib) as { id?: string }[]).filter(
-      (c) => c.id,
-    );
-    const parsed = authors.parseBib(bib) as BibAuthorsEntry[];
+    const citations = cites.parseBib(bib);
+    const parsed = authors.parseBib(bib);
     const store: Record<string, unknown> = Object.fromEntries(
       [...usable.citations].map(([k, v]) => [k, v.response]),
     );
@@ -252,22 +223,19 @@ export const referencesChecker =
     // answer.
     // One breaker for the run: a service that refuses is not asked again, not once per citation
     // (#120). Requests already in flight when it starts refusing still land — at most six.
-    const breaker = cites.createBreaker() as unknown;
+    const breaker = cites.createBreaker();
     const d = cachedDblp(usable, today);
     const [found, a] = await Promise.all([
-      mapLimit(
-        citations,
-        LOOKUPS_IN_FLIGHT,
-        (c) =>
-          cites.verifyCitationLive(c, {
-            cache: store,
-            breaker,
-          }) as Promise<CiteResult>,
+      mapLimit(citations, LOOKUPS_IN_FLIGHT, (c) =>
+        cites.verifyCitationLive(c, {
+          cache: store,
+          breaker,
+        }),
       ),
       authors.checkAuthors(parsed, {
         lookup: d.lookup,
         pause: d.pause,
-      }) as Promise<AuthorBuckets>,
+      }),
     ]);
     const keys = new Set([
       ...found.map((c) => c.id),

package/src/adapters/references/pool.ts

@@ -10,12 +10,10 @@ export async function mapLimit<T, R>(
   fn: (item: T) => Promise<R>,
 ): Promise<R[]> {
   const out: R[] = new Array<R>(items.length);
-  let next = 0;
+  // ONE iterator shared by every worker: each `next()` hands out the next index exactly once.
+  const queue = items.entries();
   const worker = async (): Promise<void> => {
-    while (next < items.length) {
-      const i = next++;
-      out[i] = await fn(items[i] as T);
-    }
+    for (const [i, item] of queue) out[i] = await fn(item);
   };
   await Promise.all(
     Array.from({ length: Math.min(limit, items.length) }, worker),

package/src/adapters/references/reach.io.ts

@@ -1,3 +1,4 @@
+import { messageOf } from "../../domain/text.ts";
 /** Whether the citation services answer at all — the one request that decides "not checked". */
 export async function unreachable(): Promise<string | null> {
   try {
@@ -7,6 +8,6 @@ export async function unreachable(): Promise<string | null> {
     });
     return null;
   } catch (e) {
-    return `the citation services cannot be reached (${(e as Error).message})`;
+    return `the citation services cannot be reached (${messageOf(e)})`;
   }
 }

package/src/build-engine.harness.mjs

@@ -19,7 +19,7 @@ import {
 import { tmpdir } from "node:os";
 import { basename, delimiter, 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 E = await import(join(HERE, "build-engine.ts"));

package/src/build-engine.test.ts

@@ -7,7 +7,7 @@ import assert from "node:assert/strict";
 import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { test } from "vitest";
-import { useTempDir } from "../test/support.mjs";
+import { useTempDir } from "../test/support.ts";
 import { prepareEngine, refusal } from "./build-engine.ts";
 
 const work = useTempDir("paperlint-build-engine-test-");
@@ -34,7 +34,7 @@ async function go(o: Parameters<typeof prepareEngine>[0]) {
     err: (l) => err.push(l),
     platform: "linux",
     interactive: true,
-    ask: async () => "y",
+    ask: () => Promise.resolve("y"),
     ...o,
   });
   return { r, out, err };

package/src/build-engine.ts

@@ -71,7 +71,7 @@ function withDefaults(o: EngineOptions): Resolved {
   const r = {
     dryRun: false,
     interactive: false,
-    ask: async () => "",
+    ask: () => Promise.resolve(""),
     log: console.log,
     err: console.error,
     // eslint-disable-next-line no-restricted-globals -- legacy I/O, moves behind a port in #76
@@ -130,7 +130,7 @@ export function gatherFacts(o: Resolved): EngineFacts {
 }
 
 const names = (missing: readonly string[]): string =>
-  `${missing.length} package(s): ${missing.join(", ")}`;
+  `${String(missing.length)} package(s): ${missing.join(", ")}`;
 
 /** The one line a run without a human gets. It names the command and what is missing. */
 export function refusal(d: EngineDecision, facts: EngineFacts): string {

package/src/build.harness.mjs

@@ -4,7 +4,7 @@
  * The process runner is replaced by a fake that writes what pdflatex and bibtex would write, so
  * these assertions check the SHELL's decisions: what is run, with which environment, in which
  * order, and what is left on disk. Whether a real pdflatex produces a real PDF is the other half,
- * `test/e2e/build.mjs`.
+ * `test/e2e/build.ts`.
  *
  * 🔴 THE TWO THINGS PINNED DOWN HERE THAT A RETURNED OBJECT CANNOT SHOW: a paper-supplied
  * `build.sh` is never executed (checked by the trace it would leave on disk and by the list of
@@ -22,7 +22,7 @@ import {
 import { tmpdir } from "node:os";
 import { join, dirname, delimiter } 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 {

package/src/build.test.ts

@@ -8,7 +8,7 @@ import assert from "node:assert/strict";
 import { existsSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { test } from "vitest";
-import { useTempDir, writeTree } from "../test/support.mjs";
+import { useTempDir, writeTree } from "../test/support.ts";
 import {
   bibInput,
   buildPaper,
@@ -62,7 +62,7 @@ function bibtexRun(f: Fake, cwd: string) {
     ? { status: f.bibtex }
     : { status: f.bibtex, stdout: f.bibtexOut };
 }
-function fakeRun(f: Fake): BuildOptions["run"] {
+function fakeRun(f: Fake): NonNullable<BuildOptions["run"]> {
   let pass = 0;
   return ((bin: string, _args: string[], opts: { cwd: string }) => {
     if (bin === f.missing)
@@ -103,18 +103,19 @@ const page = (words: number, numbered = 0) => ({
 });
 const reader =
   (last = page(80)): PdfReader =>
-  async () => ({
-    ok: true,
-    facts: {
-      pages: 1,
-      fonts: {
-        kind: "drawn",
-        list: [{ kind: "embedded", name: "CMR10", program: "Type1" }],
+  () =>
+    Promise.resolve({
+      ok: true,
+      facts: {
+        pages: 1,
+        fonts: {
+          kind: "drawn",
+          list: [{ kind: "embedded", name: "CMR10", program: "Type1" }],
+        },
+        last,
+        layout: [],
       },
-      last,
-      layout: [],
-    },
-  });
+    });
 const quiet = () => {};
 /** buildPaper with fakes; the verdict line is what the command would print for it. */
 async function build(dir: string, f: Fake = {}, over: BuildOptions = {}) {
@@ -332,7 +333,7 @@ test("paths: a paper that IS the working directory is named by its full path", a
   const run = await buildPapers([dir], {
     cwd: dir,
     log: (l) => lines.push(l),
-    engine: async () => null,
+    engine: () => Promise.resolve(null),
   });
   assert.deepEqual(
     [run, lines],

package/src/build.ts

@@ -45,7 +45,7 @@ import { delimiter, join, relative } from "node:path";
 // eslint-disable-next-line boundaries/dependencies -- legacy layer, moves behind a port in #76
 import { getParser } from "@unified-latex/unified-latex-util-parse";
 import { packageVenuesDir } from "../skills/paper-pipeline/scripts/consumer.mjs";
-import { CONFIG_FILE } from "../lib/paper-config.mjs";
+import { CONFIG_FILE } from "#lib/paper-config";
 import {
   declaredVenue,
   factsPath,
@@ -83,6 +83,10 @@ import {
   type Step,
 } from "./latex-loop.ts";
 import type { BuildResult, PlanLine } from "./types.ts";
+import { messageOf, printed } from "./domain/text.ts";
+
+/** stdin closed, stdout and stderr captured — the tuple type spawnSync's `stdio` wants. */
+const PIPED: ["ignore", "pipe", "pipe"] = ["ignore", "pipe", "pipe"];
 
 /** A directory counts as a paper by the same markers as `structure.ts` — one shared dictionary. */
 export const PAPER_MARKERS = [
@@ -337,7 +341,7 @@ function spawnOptions(ctx: BuildContext) {
   return {
     cwd: ctx.paperDir,
     env: ctx.env,
-    stdio: ["ignore", "pipe", "pipe"] as ["ignore", "pipe", "pipe"],
+    stdio: PIPED,
     encoding: "latin1" as const,
     maxBuffer: 64 * 1024 * 1024,
   };
@@ -376,19 +380,23 @@ function latexPass(
       exitCode === 0
         ? []
         : written === null
-          ? printed(r)
+          ? lastPrinted(r)
           : errorExcerpt(log).map(fromLatin1),
   };
 }
 
+/** The two streams of a finished run, as they really arrive (see `printed`). */
+interface Streams {
+  readonly stdout: string | undefined;
+  readonly stderr: string | undefined;
+}
+
 /**
  * The last lines pdflatex printed, for the run that wrote no log — it died before opening one (a
  * format it cannot load, a missing TeX Live file). Marked by NO_LOG, which the report keys on.
  */
-function printed(r: { stdout?: unknown; stderr?: unknown }): string[] {
-  const lines = fromLatin1(
-    `${String(r.stdout ?? "")}\n${String(r.stderr ?? "")}`,
-  )
+function lastPrinted(r: Streams): string[] {
+  const lines = fromLatin1(`${printed(r.stdout)}\n${printed(r.stderr)}`)
     .split("\n")
     .filter((l) => l.trim());
   return [NO_LOG, ...lines.slice(-8).map((l) => `  ${l}`)];
@@ -410,7 +418,7 @@ function bibtexPass(ctx: BuildContext, opts: SpawnOptions): Observation | null {
     after: hashes(ctx.paperDir),
     bib,
     errorLines:
-      exitCode === 0 ? [] : bibtexExcerpt(fromLatin1(String(r.stdout ?? ""))),
+      exitCode === 0 ? [] : bibtexExcerpt(fromLatin1(printed(r.stdout))),
   };
 }
 
@@ -443,7 +451,7 @@ export function compile(ctx: BuildContext): {
 const NO_PDF = `pdflatex exited 0 but wrote no ${JOB}.pdf — does the document have any pages?`;
 
 const plural = (n: number, one: string, many: string): string =>
-  `${n} ${n === 1 ? one : many}`;
+  `${String(n)} ${n === 1 ? one : many}`;
 
 export const compileStep: BuildStep = {
   name: "compile",
@@ -467,7 +475,7 @@ export const compileStep: BuildStep = {
       const bin = end.step === "latex" ? "pdflatex" : "bibtex";
       const where =
         end.cause.kind === "exit"
-          ? `${bin} exited with ${end.cause.code}`
+          ? `${bin} exited with ${String(end.cause.code)}`
           : `${bin} did not converge`;
       const log = join(
         ctx.paperDir,
@@ -669,13 +677,14 @@ function baseDefaults({
 }
 
 /** Without a checker the record says so — never a pass. The CLI wires the real one. */
-const notWired: CheckReferences = async (_bib, cache) => ({
-  check: {
-    kind: "not-checked",
-    why: "no reference checker was wired into this build",
-  },
-  cache,
-});
+const notWired: CheckReferences = (_bib, cache) =>
+  Promise.resolve({
+    check: {
+      kind: "not-checked",
+      why: "no reference checker was wired into this build",
+    },
+    cache,
+  });
 
 /** banal as the measurer, wired from the build's environment: the one piece of root work left here (#76). */
 function defaultMeasurer(
@@ -762,7 +771,7 @@ export async function buildPaper(
       dir,
       status: "failed",
       plan: [],
-      failure: { step: "facts", lines: [(e as Error).message] },
+      failure: { step: "facts", lines: [messageOf(e)] },
     };
   }
   for (const s of facts.ignoredScripts)
@@ -853,7 +862,7 @@ export function formatResult(r: BuildResult): string {
 function formatFailure(r: BuildResult): string {
   const [head, ...rest] = r.failure?.lines ?? ["failed"];
   return [
-    `  ✗ ${r.failure?.step ?? "build"}: ${head}`,
+    `  ✗ ${r.failure?.step ?? "build"}: ${String(head)}`,
     ...rest.map((l) => `      ${l}`),
     `      ${PDF_REMOVED}`,
   ].join("\n");

package/src/cli.harness.mjs

@@ -28,8 +28,8 @@ import { spawnSync } from "node:child_process";
 import { tmpdir } from "node:os";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { PAPERS_DIR_FIELD, findProjectRoot } from "../lib/paper-config.mjs";
-import { createChecker } from "../lib/check.mjs";
+import { PAPERS_DIR_FIELD, findProjectRoot } from "../lib/paper-config.ts";
+import { createChecker } from "../lib/check.ts";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const { run, parseArgs, buildConfig, nextSteps, toPaths, runHook } =
@@ -635,7 +635,7 @@ check(
 
     // ── 7-bis. THE SKILLS: WHAT WAS LINKED, AND WHAT WAS LEFT ALONE, BY NAME ────────────
     //
-    // The links themselves are `link-skills.harness.mjs`'s subject. Here: init REPORTS them, and
+    // The links themselves are `link-skills.harness.ts`'s subject. Here: init REPORTS them, and
     // a name it refused to take does not turn a working install red. The state is handed in so
     // this block does not depend on a package being installed next to the temp project.
     {
@@ -967,7 +967,7 @@ check(
 
 // ── STRUCTURE GETS THROUGH TO THE COMMAND ──────────────────────────────────────────────
 //
-// `structure.mjs` is checked separately and in full (`structure.harness.mjs`). Here — exactly
+// `structure.mjs` is checked separately and in full (`structure.harness.ts`). Here — exactly
 // one fact that harness cannot know: that the module is WIRED IN. A correct module forgotten in
 // `run()` gives zero findings and looks like a clean corpus.
 {
@@ -1148,7 +1148,7 @@ check(
 //     pnpm: node_modules/vigiles/dist/cli.js  DOES NOT
 // The old wiring addressed the runtime from the project root and did not resolve under pnpm,
 // and `|| exit 2` on PreToolUse(Bash) turned that into a block on ANY command. The end-to-end
-// half (both installs, real processes) lives in `test/e2e/install.mjs`; here — the verdicts.
+// half (both installs, real processes) lives in `test/e2e/install.ts`; here — the verdicts.
 {
   const calls = [];
   const fake = (code) => (bin, args, opts) => {
@@ -1258,7 +1258,7 @@ console.log(
 
 // ─────────────────────────────────────────────────────────────────────────────
 // What is left after init is typed in THE SAME TERMINAL. The two `/plugin` lines are gone: the
-// hooks are written into `.claude/settings.json` by init itself (hooks-settings.harness.mjs).
+// hooks are written into `.claude/settings.json` by init itself (hooks-settings.harness.ts).
 
 {
   const steps = nextSteps("papers");

package/src/cli.test.ts

@@ -9,7 +9,7 @@ import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { test } from "vitest";
-import { runNode, useTempDir, writeTree } from "../test/support.mjs";
+import { runNode, useTempDir, writeTree } from "../test/support.ts";
 import {
   chooseVenue,
   initTexLive,
@@ -169,7 +169,12 @@ test("chooseVenue: a preset by path (inside and outside the paper), by prefixed
   const choose = (venue: string) =>
     chooseVenue(
       { venue, kind: null },
-      { paperDir, cwd: dir, interactive: false, ask: async () => "" },
+      {
+        paperDir,
+        cwd: dir,
+        interactive: false,
+        ask: () => Promise.resolve(""),
+      },
     );
   const results = await Promise.all([
     choose("./papers/p/mine.jsonc"),
@@ -354,11 +359,11 @@ test("a paper's paperlint.json that does not parse stops the lint with its path"
   });
   const r = paperRuleBlocks([join(dir, "p")]);
   assert.equal(r.ok, false);
-  assert.match(!r.ok ? r.error : "", /^.*rules-broken\/p\/paperlint\.json: /);
+  assert.match(r.error, /^.*rules-broken\/p\/paperlint\.json: /);
 });
 
 test("silentOptionalRules: a config with no rules turns nothing on", async () => {
-  assert.deepEqual(await silentOptionalRules({} as never, [], {} as never), []);
+  assert.deepEqual(await silentOptionalRules({} as never, [], {}), []);
 });
 
 test("init with no path and --format md sets up the current directory", async () => {
@@ -493,7 +498,9 @@ function newAtTerminal(cwd: string, answers: Record<string, string>) {
         child.stdin.write(answer);
       }
     });
-    child.on("close", (status) => done({ status, out }));
+    child.on("close", (status) => {
+      done({ status, out });
+    });
   });
 }
 
@@ -563,7 +570,7 @@ test("lint with its LaTeX language missing from the install still lints the mark
     "papers/p/paper.md": "# P\n\nSome prose.\n",
     "no-latex.mjs":
       "import { register } from 'node:module';\n" +
-      "register('data:text/javascript,' + encodeURIComponent(\"export async function resolve(s, c, next) { if (s.endsWith('latex-language.mjs')) throw Object.assign(new Error('gone'), { code: 'ERR_MODULE_NOT_FOUND' }); return next(s, c); }\"));\n",
+      "register('data:text/javascript,' + encodeURIComponent(\"export async function resolve(s, c, next) { if (s === '#eslint-rules/latex-language') throw Object.assign(new Error('gone'), { code: 'ERR_MODULE_NOT_FOUND' }); return next(s, c); }\"));\n",
   });
   const without = runNode(BIN, ["lint", "papers"], {
     cwd: dir,