paperlint 8.0.0 → 9.0.0

package/skills/verify-citations/SKILL.md

@@ -4,7 +4,7 @@ description: Verify every citation is a real work with correct metadata, and tha
 allowed-tools: [Read, Write, Edit, Grep, Glob, Bash, WebSearch, WebFetch, Agent]
 ---
 
-<!-- vigiles:sha256:faf8d55c8ddb82ed compiled from skills/verify-citations/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:fdb023ed7c613e1b compiled from skills/verify-citations/SKILL.md.spec.ts -->
 
 # verify-citations — every cite real, the delta explicit
 
@@ -165,10 +165,13 @@ heavier than a typo, and it is exactly the class §"any regalia about third part
 
 **How to run.**
 ```
-node scripts/bib-authors.mjs <paper-dir>          # or a .bib, or a .tex with a filecontents block
+node scripts/bib-authors.mjs <paper-dir>          # the databases bibtex opened in the last build; or a .bib, or a .tex
 node scripts/bib-authors.mjs <paper-dir> --json
 ```
-Exits **1** on any author-set or author-order disagreement, **0** when clean, **2** on usage/IO error.
+Exits **1** on any author-set or author-order disagreement, **0** when clean, **2** on usage/IO error. A paper
+directory or a `.tex` is read through the build's record (`_build/sources.json`): a paper that was never built,
+or changed since, is refused (exit 2) and told to run `npx paperlint build` first — the databases are TeX's answer,
+not a reading of the source. A `.bib` named is read as itself.
 
 **Source is DBLP, and that choice is the evidence.** DBLP indexes the proceedings record and the CoRR record
 **separately**, so a single query returns both lists side by side — the cleanest proof available that the
@@ -244,7 +247,7 @@ It used to be one script, `verify-refs.mjs`; the measurement half stayed a scrip
 became twelve ESLint rules over the facts it writes.
 
 ```
-# 1. measure: parse the bibliography, ask CrossRef/arXiv, write _build/refs.facts.json
+# 1. measure: parse the bibliography bibtex opened (build the paper first), ask CrossRef/arXiv, write _build/refs.facts.json
 node .claude/skills/paper-pipeline/scripts/extract-ref-facts.mjs <paper-dir>
 node .claude/skills/paper-pipeline/scripts/extract-ref-facts.mjs <paper-dir> --offline  # cached responses only
 

package/skills/verify-citations/SKILL.md.spec.ts

@@ -181,10 +181,13 @@ heavier than a typo, and it is exactly the class §"any regalia about third part
 
 **How to run.**
 \`\`\`
-node scripts/bib-authors.mjs <paper-dir>          # or a .bib, or a .tex with a filecontents block
+node scripts/bib-authors.mjs <paper-dir>          # the databases bibtex opened in the last build; or a .bib, or a .tex
 node scripts/bib-authors.mjs <paper-dir> --json
 \`\`\`
-Exits **1** on any author-set or author-order disagreement, **0** when clean, **2** on usage/IO error.
+Exits **1** on any author-set or author-order disagreement, **0** when clean, **2** on usage/IO error. A paper
+directory or a \`.tex\` is read through the build's record (\`_build/sources.json\`): a paper that was never built,
+or changed since, is refused (exit 2) and told to run \`npx paperlint build\` first — the databases are TeX's answer,
+not a reading of the source. A \`.bib\` named is read as itself.
 
 **Source is DBLP, and that choice is the evidence.** DBLP indexes the proceedings record and the CoRR record
 **separately**, so a single query returns both lists side by side — the cleanest proof available that the
@@ -260,7 +263,7 @@ It used to be one script, \`verify-refs.mjs\`; the measurement half stayed a scr
 became twelve ESLint rules over the facts it writes.
 
 \`\`\`
-# 1. measure: parse the bibliography, ask CrossRef/arXiv, write _build/refs.facts.json
+# 1. measure: parse the bibliography bibtex opened (build the paper first), ask CrossRef/arXiv, write _build/refs.facts.json
 node .claude/skills/paper-pipeline/scripts/extract-ref-facts.mjs <paper-dir>
 node .claude/skills/paper-pipeline/scripts/extract-ref-facts.mjs <paper-dir> --offline  # cached responses only
 

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

@@ -13,9 +13,15 @@ import {
   checkAuthors,
   claimsPublished,
   dblpHits,
-  parseBib,
+  authorEntries,
   surnames,
 } from "./bib-authors.mjs";
+import { bibReader } from "#src/adapters/bibtex/index";
+import { absolutePath } from "#src/domain/paths";
+
+/** This check's entries of a BibTeX text, read by the one bibtex reader. */
+const entriesIn = (bib) =>
+  authorEntries(bibReader.readFile(absolutePath("/p/refs.bib"), bib).entries);
 
 afterEach(() => vi.unstubAllGlobals());
 
@@ -215,35 +221,27 @@ test("dblpHits: no hits is an empty list; 429 is retryable; other errors are not
   );
 });
 
-test("parseBib reads quoted and bare field values, and a field that is absent", () => {
+test("authorEntries: names written family first (`and others` kept), a quoted value, a field that is absent", () => {
   assert.deepEqual(
-    parseBib(
-      '@article{k, author = "Ada Lovelace", title = {T}, journal = J, }',
+    entriesIn(
+      '@article{k, author = "Ada Lovelace and van der Berg, Jan and others", title = {The {BERT} Model}, journal = {J}}\n@misc{untitled, author = {Hopper, Grace}}',
     ),
     [
       {
         type: "article",
         key: "k",
-        author: "Ada Lovelace",
-        title: "T",
+        author: "Lovelace, Ada and van der Berg, Jan and others",
+        title: "The BERT Model",
         booktitle: "",
         journal: "J",
       },
-    ],
-  );
-});
-
-test("parseBib: braces nested inside a value, and a bare last value with no comma after it", () => {
-  assert.deepEqual(
-    parseBib("@article{k, title = {The {BERT} Model}, journal = J}"),
-    [
       {
-        type: "article",
-        key: "k",
-        author: "",
-        title: "The {BERT} Model",
+        type: "misc",
+        key: "untitled",
+        author: "Hopper, Grace",
+        title: "",
         booktitle: "",
-        journal: "J",
+        journal: "",
       },
     ],
   );

package/skills/verify-citations/scripts/bib-authors.cli.test.ts

@@ -1,7 +1,7 @@
 /**
- * bib-authors.mjs as a process: which file it picks from a paper directory, the bibliography
- * sources it reads (.bib, a .tex's filecontents or its sibling refs.bib), the file it refuses, and
- * the report and exit code for each outcome. DBLP is a preload that answers
+ * bib-authors.mjs as a process: the bibliography it reads (a .bib named, or what the last build's
+ * bibtex opened for a paper directory or a .tex — `_build/sources.json`, through `bibliographyAt`), the
+ * targets it refuses, and the report and exit code for each outcome. DBLP is a preload that answers
  * by title from a table (the documented `result.hits.hit[].info` shape) — no network.
  */
 import assert from "node:assert/strict";
@@ -15,6 +15,13 @@ import {
   useTempDir,
   writeTree,
 } from "../../../test/support.ts";
+import {
+  plantedOnDisk,
+  recordOnDisk,
+  type Shape,
+} from "../../../test/recorded-fixture.ts";
+import { absolutePath } from "#src/domain/paths";
+import { bibliographyUnreadWhy } from "#src/paper-sources";
 
 const SCRIPT = join(dirname(fileURLToPath(import.meta.url)), "bib-authors.mjs");
 const root = useTempDir("bib-authors-cli-");
@@ -32,6 +39,10 @@ const bib = (
 ) =>
   `@inproceedings{${key}, author = {${author}}, title = {${title}}, ${venue}}\n`;
 
+/** A .tex that declares the database `name`, with `preamble` before its document. */
+const declaring = (name: string, preamble = "") =>
+  `\\documentclass{article}\n${preamble}\\begin{document}x\\bibliography{${name}}\\end{document}\n`;
+
 writeTree(root, {
   // The retry backoff (1.5 s, then 3 s) and the 900 ms courtesy pause are real sleeps in the
   // script. Under CPU load they made "DBLP down" take 11.7 s once and time out. The preload
@@ -46,24 +57,53 @@ writeTree(root, {
     "  const hit = (answers[q] ?? []).map((authors) => ({ info: { title: q, venue: 'X', year: '2024',\n" +
     "    type: 'Conference and Workshop Papers', authors: { author: authors.map((text) => ({ text })) } } }));\n" +
     "  return new Response(JSON.stringify({ result: { hits: { hit } } }), { status: 200 });\n};\n",
+  "findings/paper.tex": declaring("paper"),
   "findings/paper.bib":
     bib("dropped", "Ada Lovelace and Grace Hopper", "Dropped Author") +
     bib("order", "Alan Turing and Ada Lovelace", "Swapped Order"),
   "findings/other.bib": bib("never", "X", "Never Read"),
   "twotex/b.tex": "\\documentclass{article}\n",
-  "twotex/a.tex":
-    "\\begin{filecontents*}{refs.bib}\n" +
-    bib("pre", "Ada Lovelace", "A Preprint", "journal = {arXiv preprint}") +
-    "\\end{filecontents*}\n",
-  "sibling/paper.tex": "\\documentclass{article}\n",
+  "twotex/paper.tex": declaring(
+    "refs",
+    "\\begin{filecontents*}[overwrite]{refs.bib}\n" +
+      bib("pre", "Ada Lovelace", "A Preprint", "journal = {arXiv preprint}") +
+      "\\end{filecontents*}\n",
+  ),
+  // What TeX wrote from that block: the file bibtex opened.
+  "twotex/refs.bib": bib(
+    "pre",
+    "Ada Lovelace",
+    "A Preprint",
+    "journal = {arXiv preprint}",
+  ),
+  "sibling/paper.tex": declaring("refs"),
   "sibling/refs.bib": bib("good", "Ada Lovelace", "All Good"),
-  "nobib/paper.tex": "\\documentclass{article}\n",
+  "etal/paper.tex": declaring("refs"),
   "etal/notes.txt": "not a bibliography\n",
   "etal/refs.bib":
     bib("good", "Ada Lovelace", "All Good") +
     bib("etal", "Ada Lovelace and others", "Truncated"),
+  "down/paper.tex": declaring("refs"),
   "down/refs.bib": bib("down", "Ada Lovelace", "Service Down"),
-  "empty/.keep": "",
+});
+
+/** The record of a paper whose bibliography is `db`, a file the author keeps. */
+const keeps = (db: string): Shape => ({
+  inputs: [
+    ["paper.tex", "body"],
+    [db, "preamble"],
+  ],
+  databases: [db],
+});
+recordOnDisk(join(root, "findings"), keeps("paper.bib"));
+recordOnDisk(join(root, "sibling"), keeps("refs.bib"));
+recordOnDisk(join(root, "etal"), keeps("refs.bib"));
+recordOnDisk(join(root, "down"), keeps("refs.bib"));
+// A block TeX wrote into refs.bib: the file is no input, the block is.
+recordOnDisk(join(root, "twotex"), {
+  inputs: [["paper.tex", "body"]],
+  written: ["refs.bib"],
+  databases: ["refs.bib"],
 });
 
 const run = (...args: string[]) => {
@@ -77,14 +117,16 @@ const run = (...args: string[]) => {
   };
 };
 
-test("refusals: no argument, no such path, a directory with nothing to read, a .tex with no bibliography", () => {
+test("refusals: no argument; a path with no bibliography to read, in bibliographyAt's words", () => {
+  // The path → bibliography vocabulary is tested once, beside bibliographyAt (src/paper-sources.ts).
+  // Here: that the command speaks it, and exits 2.
+  const notes = join(root, "etal", "notes.txt");
   assert.deepEqual(
-    [
-      run(),
-      run(join(root, "nope")),
-      run(join(root, "empty")),
-      run(join(root, "nobib", "paper.tex")),
-    ].map(({ status, stdout, stderr }) => ({ status, stdout, stderr })),
+    [run(), run(notes)].map(({ status, stdout, stderr }) => ({
+      status,
+      stdout,
+      stderr,
+    })),
     [
       {
         status: 2,
@@ -95,24 +137,13 @@ test("refusals: no argument, no such path, a directory with nothing to read, a .
       {
         status: 2,
         stdout: "",
-        stderr: "bib-authors: no such path: <root>/nope\n",
-      },
-      {
-        status: 2,
-        stdout: "",
-        stderr: "bib-authors: no .bib or .tex in <root>/empty\n",
-      },
-      {
-        status: 2,
-        stdout: "",
-        stderr:
-          "bib-authors: no bibliography found in <root>/nobib/paper.tex (no filecontents block, no refs.bib beside it)\n",
+        stderr: `bib-authors: ${bibliographyUnreadWhy({ kind: "not-bib-or-tex", path: absolutePath(notes) }).replaceAll(root, "<root>")}\n`,
       },
     ],
   );
 });
 
-test("a paper directory: the canonical paper.bib is read, and each difference is printed — FAIL, exit 1", () => {
+test("a paper directory: the paper.bib its \\bibliography{paper} declares is read, and each difference is printed — FAIL, exit 1", () => {
   assert.deepEqual(run(join(root, "findings")), {
     status: 1,
     stderr: "",
@@ -135,16 +166,16 @@ test("a paper directory: the canonical paper.bib is read, and each difference is
   });
 });
 
-test("two .tex files and no paper.tex: the first by name, said out loud; its filecontents is read", () => {
-  const r = run(join(root, "twotex"), "--json");
+test("a .tex named is its folder's paper: the database bibtex opened is read from the block that wrote it", () => {
+  const r = run(join(root, "twotex", "paper.tex"), "--json");
   assert.deepEqual(
     { status: r.status, stderr: r.stderr, report: parseJson(r.stdout) },
     {
       status: 0,
-      stderr:
-        "⚠️ <root>/twotex holds several .tex files and no canonical paper.tex: a.tex, b.tex — took a.tex. If that is the wrong one, name the file explicitly.\n",
+      stderr: "",
       report: {
-        file: "<root>/twotex/a.tex",
+        file: "<root>/twotex/paper.tex",
+        files: ["<root>/twotex/paper.tex"],
         entries: 1,
         findings: [],
         skipped: [],
@@ -154,7 +185,18 @@ test("two .tex files and no paper.tex: the first by name, said out loud; its fil
   );
 });
 
-test("a .tex with no filecontents reads the refs.bib beside it — PASS, exit 0", () => {
+test("a .bib named is read as itself", () => {
+  const r = run(join(root, "findings", "paper.bib"), "--json");
+  const report: unknown = parseJson(r.stdout);
+  assert.deepEqual(
+    report !== null && typeof report === "object" && "files" in report
+      ? report.files
+      : report,
+    ["<root>/findings/paper.bib"],
+  );
+});
+
+test("a .tex that declares refs and has no block reads refs.bib — PASS, exit 0", () => {
   const r = run(join(root, "sibling", "paper.tex"));
   assert.deepEqual(r, {
     status: 0,
@@ -164,16 +206,6 @@ test("a .tex with no filecontents reads the refs.bib beside it — PASS, exit 0"
   });
 });
 
-test("a file that is neither a .bib nor a .tex is refused — not swapped for the refs.bib beside it", () => {
-  const r = run(join(root, "etal", "notes.txt"));
-  assert.deepEqual(r, {
-    status: 2,
-    stdout: "",
-    stderr:
-      "bib-authors: <root>/etal/notes.txt is not a .bib or a .tex — give the paper's .bib or paper.tex\n",
-  });
-});
-
 test("an `and others` entry is printed as not applicable, not dropped", () => {
   const r = run(join(root, "etal"));
   assert.deepEqual(r, {
@@ -198,3 +230,54 @@ test("DBLP down: NOT CHECKED, PARTIAL, exit 2 — never a pass", () => {
       "PARTIAL: no disagreement among the entries reached, but 1 could not be checked — this is NOT a pass.\n",
   });
 });
+
+// The planted papers of fixtures/paper-sources, laid out as a build leaves them: the file read is the
+// one bibtex opened (tex-truth.json), or the block that wrote it.
+test.each([
+  ["v1-stale", "refs.bib"],
+  ["v2-overwrite", "paper.tex"],
+  ["v3-declared", "paper.bib"],
+  ["v4-commented", "refs.bib"],
+])("%s: reads %s", (paper, file) => {
+  const dir = join(root, "planted", paper);
+  plantedOnDisk(dir, paper);
+  const r = runNode(SCRIPT, [dir, "--json"], {
+    nodeArgs: ["--import", join(root, "dblp.mjs")],
+  });
+  const report: unknown = parseJson(r.stdout);
+  assert.deepEqual(
+    report !== null && typeof report === "object" && "files" in report
+      ? report.files
+      : report,
+    [join(dir, file)],
+  );
+});
+
+test("🔴 a paper that was not built is refused — run `npx paperlint build` first — and so is one changed since", () => {
+  const unbuilt = join(root, "unbuilt");
+  writeTree(unbuilt, {
+    "paper.tex": declaring("refs"),
+    "refs.bib": bib("good", "Ada Lovelace", "All Good"),
+  });
+  assert.deepEqual(
+    [run(unbuilt), run(join(unbuilt, "paper.tex"))].map(
+      ({ status, stdout, stderr }) => ({ status, stdout, stderr }),
+    ),
+    Array.from({ length: 2 }, () => ({
+      status: 2,
+      stdout: "",
+      stderr:
+        "bib-authors: <root>/unbuilt has not been built — run `npx paperlint build` first, which records the databases bibtex reads\n",
+    })),
+  );
+  recordOnDisk(unbuilt, keeps("refs.bib"));
+  writeTree(unbuilt, {
+    "refs.bib": bib("good", "Ada Lovelace", "All Good Edited"),
+  });
+  assert.deepEqual(run(unbuilt), {
+    status: 2,
+    stdout: "",
+    stderr:
+      "bib-authors: <root>/unbuilt changed since the last build (refs.bib edited) — run `npx paperlint build` first\n",
+  });
+});

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

@@ -1,7 +1,7 @@
 // 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 "". */
+/** One entry as `authorEntries` returns it; a field the entry lacks is "". */
 export interface BibEntry {
   readonly type: string;
   readonly key: string;
@@ -11,7 +11,27 @@ export interface BibEntry {
   readonly journal: string;
 }
 
-export declare function parseBib(text: string): BibEntry[];
+/** A name of a name list, in its parts (`BibName`). */
+export interface ReadName {
+  readonly lastName?: string;
+  readonly firstName?: string;
+  readonly prefix?: string;
+  readonly suffix?: string;
+  readonly name?: string;
+}
+
+/** An entry as the bibtex reader reads it (src/domain/paper-sources.ts), as far as this check uses it. */
+export interface ReadEntry {
+  readonly type: string;
+  readonly key: string;
+  readonly fields: Readonly<Record<string, string>>;
+  readonly names: Readonly<Record<string, readonly ReadName[]>>;
+}
+
+/** The entries this check reads, from the bibtex reader's. */
+export declare function authorEntries(
+  entries: readonly ReadEntry[],
+): BibEntry[];
 
 /** True when the author list ends in `and others` — there is nothing complete to compare. */
 export declare const truncated: (authorField: string) => boolean;

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

@@ -43,122 +43,60 @@
  * Usage:  node bib-authors.mjs <paper-dir-or-.bib-or-.tex> [--json]
  * Exit:   0 = no author-set/order differences   1 = differences found   2 = usage/IO error
  */
-import { readFileSync, existsSync, readdirSync } from "node:fs";
-import { join, extname } from "node:path";
+import { resolve } from "node:path";
+import { latexReader } from "#src/adapters/latex/index";
+import { nodeFiles } from "#src/adapters/node/index";
+import { sourcesCodec } from "#src/adapters/sources-record/index";
+import { absolutePath } from "#src/domain/paths";
+import { bibReader } from "#src/adapters/bibtex/index";
+import { bibliographyAt, bibliographyUnreadWhy } from "#src/paper-sources";
 import { isMain } from "../../paper-pipeline/scripts/consumer.mjs";
 
 const DBLP = "https://dblp.org/search/publ/api";
 
-/* ---------- input: a .bib, a .tex with filecontents, or a paper dir ---------- */
+/* ---------- input: the bibliography TeX reads, or a .bib named ---------- */
 
-function bibTextFrom(target) {
-  let file = target;
-  if (!existsSync(file)) die(`no such path: ${file}`);
-  if (!extname(file)) {
-    const names = readdirSync(file);
-    // 🔴 THE CANONICAL NAME FIRST, then the only candidate, and never "whichever
-    // turns up first" (review #189). It used to be `names.find(f => f.endsWith(".tex"))`,
-    // that is, the first in directory order. Measured: one of the papers in the corpus
-    // has FIVE drafts lying around (paper-CONSTRUCTIVE-…, paper-FOLDED-…, paper-SAFE-…),
-    // while PIPELINE-STATUS.md names `paper.tex` as the submitted source. The author
-    // check went off into a stale draft and printed a verdict about the WRONG
-    // bibliography — a gate that checks the wrong file is worse than a missing one,
-    // because it says "checked".
-    const pick = (ext) => {
-      const canon = names.find((f) => f === `paper${ext}`);
-      if (canon) return canon;
-      const all = names.filter((f) => f.endsWith(ext)).sort();
-      if (all.length === 1) return all[0];
-      if (all.length > 1) {
-        // We do not fail: a new check here would set up one more surface, and its
-        // home is decided by the ladder in the `CLAUDE.md` next to the papers, not by
-        // this script (the `frozen-checks` ratchet is what guards that). It is enough
-        // to SAY it out loud and to choose DETERMINISTICALLY — the header below prints
-        // which file was checked anyway, so the reader sees the choice.
-        console.error(
-          `⚠️ ${file} holds several ${ext} files and no canonical paper${ext}: ` +
-            `${all.join(", ")} — took ${all[0]}. If that is the wrong one, name the file explicitly.`,
-        );
-        return all[0];
-      }
-      return undefined;
-    };
-    const found = pick(".bib") || pick(".tex");
-    if (!found) die(`no .bib or .tex in ${file}`);
-    file = join(file, found);
-  }
-  const text = readFileSync(file, "utf-8");
-  if (file.endsWith(".bib")) return { text, file };
-  // Only a .bib and a .tex are read: any other file would fall through to the refs.bib beside it,
-  // and the report would name a file nobody asked about.
-  if (!file.endsWith(".tex"))
-    die(`${file} is not a .bib or a .tex — give the paper's .bib or paper.tex`);
-  // A .tex may carry the bibliography inline via filecontents — that is how our papers do it.
-  const m = text.match(
-    /\\begin\{filecontents\*?\}(?:\[[^\]]*\])?\{[^}]*\.bib\}\r?\n([\s\S]*?)\\end\{filecontents\*?\}/,
-  );
-  if (m) return { text: m[1], file };
-  const sibling = join(file, "..", "refs.bib");
-  if (existsSync(sibling))
-    return { text: readFileSync(sibling, "utf-8"), file: sibling };
-  die(
-    `no bibliography found in ${file} (no filecontents block, no refs.bib beside it)`,
-  );
-}
+const DEPS = {
+  files: nodeFiles,
+  codec: sourcesCodec,
+  latex: latexReader,
+  bib: bibReader,
+};
 
-/* ---------- a deliberately small bib reader ----------
- * Only three fields are needed (type, key, author, title, booktitle/journal), and a full
- * BibTeX grammar would be a second thing to maintain. Brace-depth counting is enough and
- * is exercised by the colocated test. */
-export function parseBib(text) {
-  const out = [];
-  const re = /@(\w+)\s*\{\s*([^,\s]+)\s*,/g;
-  let m;
-  while ((m = re.exec(text))) {
-    const [, type, key] = m;
-    let i = re.lastIndex,
-      depth = 1;
-    while (i < text.length && depth > 0) {
-      if (text[i] === "{") depth++;
-      else if (text[i] === "}") depth--;
-      i++;
-    }
-    const body = text.slice(re.lastIndex, i - 1);
-    out.push({ type: type.toLowerCase(), key, ...fields(body) });
-  }
-  return out;
+/**
+ * The texts to read: a `.bib` as named; for a paper directory or a `.tex`, the databases the last
+ * build's bibtex opened (`_build/sources.json`) — `bibliographyAt` (src/paper-sources.ts) answers, and
+ * refuses in its words, "run `npx paperlint build` first" among them.
+ */
+function bibliographyFrom(target) {
+  const r = bibliographyAt(absolutePath(resolve(target)), DEPS);
+  if (!r.ok) die(bibliographyUnreadWhy(r.error));
+  const { texts } = r.value;
+  return { files: [...new Set(texts.map((x) => x.path))], texts };
 }
 
-function fields(body) {
-  const get = (name) => {
-    const r = new RegExp(`(?:^|[,\\s])${name}\\s*=\\s*`, "i");
-    const at = body.search(r);
-    if (at === -1) return "";
-    let i = body.indexOf("=", at) + 1;
-    while (/\s/.test(body[i])) i++;
-    if (body[i] === "{") {
-      let depth = 1,
-        j = i + 1;
-      while (j < body.length && depth > 0) {
-        if (body[j] === "{") depth++;
-        else if (body[j] === "}") depth--;
-        j++;
-      }
-      return body.slice(i + 1, j - 1);
-    }
-    if (body[i] === '"') {
-      const j = body.indexOf('"', i + 1);
-      return body.slice(i + 1, j);
-    }
-    const j = body.indexOf(",", i);
-    return body.slice(i, j === -1 ? undefined : j);
-  };
-  return {
-    author: get("author"),
-    title: get("title"),
-    booktitle: get("booktitle"),
-    journal: get("journal"),
-  };
+/* ---------- entries: as the bibtex reader read them ---------- */
+
+/** A name of a name list as BibTeX writes it, family part first: `von Last, First`, or the literal. */
+const writtenName = (n) =>
+  n.name ??
+  [[n.prefix, n.lastName].filter(Boolean).join(" "), n.firstName]
+    .filter(Boolean)
+    .join(", ");
+
+/**
+ * The entries this check reads, from the bibtex reader's (src/ports/bib-reader.ts): type, key, the
+ * author list written out (`and others` kept), title, booktitle and journal; "" for a field it lacks.
+ */
+export function authorEntries(entries) {
+  return entries.map((e) => ({
+    type: e.type,
+    key: e.key,
+    author: (e.names.author ?? []).map(writtenName).join(" and "),
+    title: e.fields.title ?? "",
+    booktitle: e.fields.booktitle ?? "",
+    journal: e.fields.journal ?? "",
+  }));
 }
 
 /* ---------- normalisation: surnames only, in order ---------- */
@@ -353,14 +291,22 @@ async function main() {
   if (!args[0])
     die("usage: bib-authors.mjs <paper-dir|file.bib|file.tex> [--json]");
 
-  const { text, file } = bibTextFrom(args[0]);
-  const parsed = parseBib(text);
+  const { files, texts } = bibliographyFrom(args[0]);
+  const file = files.join(", ");
+  const parsed = texts.flatMap((t) => authorEntries(t.entries));
   const entries = parsed.filter((e) => e.title && e.author);
   const { findings, skipped, unchecked } = await checkAuthors(parsed);
   if (asJson) {
     console.log(
       JSON.stringify(
-        { file, entries: entries.length, findings, skipped, unchecked },
+        {
+          file: files[0],
+          files,
+          entries: entries.length,
+          findings,
+          skipped,
+          unchecked,
+        },
         null,
         2,
       ),

package/skills/verify-citations/scripts/verify-cites.cli.test.ts

@@ -10,6 +10,8 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { test } from "vitest";
 import { z } from "zod";
+import { absolutePath } from "#src/domain/paths";
+import { bibliographyUnreadWhy } from "#src/paper-sources";
 import {
   runNode,
   useTempDir,
@@ -92,6 +94,20 @@ test("an input that cannot be read: exit 2, named", () => {
   );
 });
 
+test("a .bib that is not there: exit 2, in bibliographyAt's words", () => {
+  // The path → bibliography vocabulary is tested once, beside bibliographyAt (src/paper-sources.ts).
+  const gone = join(root, "gone.bib");
+  const r = offline([gone]);
+  assert.deepEqual(
+    { status: r.status, stdout: r.stdout, stderr: r.stderr },
+    {
+      status: 2,
+      stdout: "",
+      stderr: `error: could not read input — ${bibliographyUnreadWhy({ kind: "missing", path: absolutePath(gone) })}\n`,
+    },
+  );
+});
+
 test("offline over a JSON list: a citation with no id is unresolvable by name, a short SHA is flagged", () => {
   const r = parsed(offline([join(root, "cites.json")]));
   assert.deepEqual(