paperlint 8.0.0 → 9.0.0

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

@@ -5,14 +5,30 @@
 // 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. */
+/** One citation as `citationsOf` 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[];
+/** 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 (`BibEntry`, src/domain/paper-sources.ts), as far as citations use it. */
+export interface ReadEntry {
+  readonly key: string;
+  readonly fields: Readonly<Record<string, string>>;
+  readonly names: Readonly<Record<string, readonly ReadName[]>>;
+}
+
+/** The citations of a bibliography's entries, as the bibtex reader read them. */
+export declare function citationsOf(entries: readonly ReadEntry[]): Citation[];
 
 /** The title reduced to what identifies it: case, braces and punctuation removed. */
 export declare function titleIdentity(title: string): string;

package/skills/verify-citations/scripts/verify-cites.mjs

@@ -47,7 +47,13 @@
 
 import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join, extname } from "node:path";
+import { dirname, join, extname, resolve } from "node:path";
+import { bibReader } from "#src/adapters/bibtex/index";
+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 { bibliographyAt, bibliographyUnreadWhy } from "#src/paper-sources";
 import { createHash } from "node:crypto";
 import {
   consumerContactEmail,
@@ -588,116 +594,32 @@ export function reduceVerdict(citation, evidence, commitFlags = []) {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
-// .bib PARSER — small, best-effort. Extracts @article/@inproceedings/... entries
-// and (loosely) \bibitem blocks. Not a full BibTeX grammar; enough to seed cites.
+// CITATIONS — from the entries the bibtex reader read (src/ports/bib-reader.ts).
 // ─────────────────────────────────────────────────────────────────────────────
 
+/** A name of a name list, written out: `First von Last, Jr.`, or the literal it was. */
+const writtenName = (n) =>
+  n.name ??
+  [n.firstName, n.prefix, n.lastName, n.suffix].filter(Boolean).join(" ");
+
 /**
- * field(body, name) — extract a BibTeX field value from an entry body.
- *  (a) anchors `name` so `title` does NOT also match `booktitle` (S4a);
- *  (b) reads BRACE-delimited values with balanced-brace scanning, so a protected
- *      acronym `{Evaluating {LLM}-based ...}` is captured whole, not truncated at
- *      the inner `}` (S4b);
- *  also handles "quoted" and bare (numeric) values.
+ * The citations of a bibliography's entries, as the bibtex reader read them: the key as `id`, and
+ * the doi, title, year, authors and arXiv eprint each entry has.
  */
-function bibField(body, name) {
-  const re = new RegExp(`(?<![a-zA-Z])${name}\\s*=\\s*`, "i");
-  const fm = re.exec(body);
-  if (!fm) return undefined;
-  let i = fm.index + fm[0].length;
-  const ch = body[i];
-  if (ch === "{") {
-    let depth = 0;
-    let j = i;
-    for (; j < body.length; j++) {
-      if (body[j] === "{") depth++;
-      else if (body[j] === "}") {
-        depth--;
-        if (depth === 0) break;
-      }
-    }
-    return body
-      .slice(i + 1, j)
-      .replace(/\s+/g, " ")
-      .trim();
-  }
-  if (ch === '"') {
-    let j = i + 1;
-    while (j < body.length && body[j] !== '"') j++;
-    return body
-      .slice(i + 1, j)
-      .replace(/\s+/g, " ")
-      .trim();
-  }
-  // bare value (e.g. year = 2017,) — up to the next comma / newline / close brace
-  let j = i;
-  while (j < body.length && !/[,\n}]/.test(body[j])) j++;
-  const v = body.slice(i, j).replace(/\s+/g, " ").trim();
-  return v || undefined;
-}
-
-export function parseBib(text) {
-  const cites = [];
-  // @type{key,  — then read the entry body with BALANCED-BRACE scanning so that
-  // one-line entries and indented / same-line closing braces (`\n  }` or `...}`)
-  // are captured, not dropped by a `\n}`-at-column-0 requirement (S4c).
-  const headRe = /@(\w+)\s*\{\s*([^,\s}]+)\s*,/g;
-  let m;
-  while ((m = headRe.exec(text)) !== null) {
-    const type = m[1].toLowerCase();
-    if (type === "comment" || type === "string" || type === "preamble")
-      continue;
-    const key = m[2].trim();
-    // Balanced scan from just after the key's comma to the entry's closing brace.
-    let depth = 1; // the entry's opening `{` was already consumed by headRe
-    let j = headRe.lastIndex;
-    for (; j < text.length && depth > 0; j++) {
-      if (text[j] === "{") depth++;
-      else if (text[j] === "}") depth--;
-    }
-    const body = text.slice(headRe.lastIndex, j - 1);
-    headRe.lastIndex = j; // resume scanning AFTER this entry
-
-    const c = { id: key };
-    const doi = bibField(body, "doi");
-    const title = bibField(body, "title");
-    const year = bibField(body, "year");
-    const author = bibField(body, "author");
-    const eprint = bibField(body, "eprint");
-    const archive =
-      bibField(body, "archiveprefix") || bibField(body, "eprinttype");
-    if (doi) c.doi = normalizeDoi(doi);
-    if (title) c.title = title.replace(/[{}]/g, "");
-    if (year) c.year = year;
-    if (author) c.authors = author;
-    if (eprint && (!archive || /arxiv/i.test(archive)))
-      c.arxiv = normalizeArxiv(eprint);
-    cites.push(c);
-  }
-  if (cites.length > 0) return cites;
-
-  // Fallback: \bibitem — grab arXiv ids / DOIs out of each block, best-effort.
-  const itemRe =
-    /\\bibitem(?:\[[^\]]*\])?\{([^}]+)\}([\s\S]*?)(?=\\bibitem|\\end\{thebibliography\}|$)/g;
-  while ((m = itemRe.exec(text)) !== null) {
-    const key = m[1].trim();
-    const block = m[2];
-    const c = { id: key };
-    const doiM = block.match(/10\.\d{4,9}\/[-._;()/:A-Z0-9]+/i);
-    const arxivM = block.match(/arXiv:\s*(\d{4}\.\d{4,5})/i);
-    const yearM = block.match(/\b(19|20)\d{2}\b/);
-    if (doiM) c.doi = normalizeDoi(doiM[0]);
-    if (arxivM) c.arxiv = normalizeArxiv(arxivM[1]);
-    if (yearM) c.year = yearM[0];
-    // crude title: longest quoted or {\em ...} run
-    const titleM =
-      block.match(/``([^']{6,}?)''/) ||
-      block.match(/\\emph\{([^}]{6,}?)\}/) ||
-      block.match(/\{\\em\s+([^}]{6,}?)\}/);
-    if (titleM) c.title = titleM[1].replace(/\s+/g, " ").trim();
-    cites.push(c);
-  }
-  return cites;
+export function citationsOf(entries) {
+  return entries.map((e) => {
+    const f = e.fields;
+    const c = { id: e.key };
+    if (f.doi) c.doi = normalizeDoi(f.doi);
+    if (f.title) c.title = f.title.replace(/\s+/g, " ").trim();
+    if (f.year) c.year = f.year;
+    const authors = (e.names.author ?? []).map(writtenName).join(" and ");
+    if (authors) c.authors = authors;
+    const archive = f.archiveprefix || f.eprinttype;
+    if (f.eprint && (!archive || /arxiv/i.test(archive)))
+      c.arxiv = normalizeArxiv(f.eprint);
+    return c;
+  });
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -1212,11 +1134,23 @@ export async function verifyCitationLive(
 // CLI
 // ─────────────────────────────────────────────────────────────────────────────
 
+/** What `bibliographyAt` needs to read a `.bib` (src/paper-sources.ts, the one answer for a path). */
+const DEPS = {
+  files: nodeFiles,
+  codec: sourcesCodec,
+  latex: latexReader,
+  bib: bibReader,
+};
+
 function loadInput(argv) {
   const path = argv.find((a) => !a.startsWith("-"));
+  if (path && extname(path).toLowerCase() === ".bib") {
+    const r = bibliographyAt(absolutePath(resolve(path)), DEPS);
+    if (!r.ok) throw new Error(bibliographyUnreadWhy(r.error));
+    return citationsOf(r.value.texts.flatMap((t) => t.entries));
+  }
   const raw =
     path && path !== "-" ? readFileSync(path, "utf8") : readFileSync(0, "utf8"); // stdin
-  if (path && extname(path).toLowerCase() === ".bib") return parseBib(raw);
   const parsed = JSON.parse(raw);
   return Array.isArray(parsed) ? parsed : [parsed];
 }

package/skills/verify-citations/scripts/verify-cites.test.mjs

@@ -24,7 +24,7 @@ import {
   checkNvd,
   checkCommit,
   reduceVerdict,
-  parseBib,
+  citationsOf,
   parseArxivFeed,
   normalizeDoi,
   normalizeArxiv,
@@ -33,6 +33,12 @@ import {
   titleIdentity,
   isValidCveId,
 } from "./verify-cites.mjs";
+import { bibReader } from "#src/adapters/bibtex/index";
+import { absolutePath } from "#src/domain/paths";
+
+/** The citations of a BibTeX text, read by the one bibtex reader. */
+const citationsIn = (bib) =>
+  citationsOf(bibReader.readFile(absolutePath("/p/refs.bib"), bib).entries);
 
 /** One vitest case per check, named by it. */
 function ok(cond, name) {
@@ -377,7 +383,7 @@ console.log("\n(extra) .bib parser best-effort extraction:");
   eprint={1512.03385}
 }
 `;
-  const cites = parseBib(bib);
+  const cites = citationsIn(bib);
   eq(cites.length, 2, "parsed 2 entries");
   eq(cites[0].doi, "10.5555/3295222.3295349", "entry 1 doi");
   eq(cites[1].arxiv, "1512.03385", "entry 2 arxiv eprint");
@@ -724,7 +730,7 @@ console.log("\n[S4] .bib parser edge cases:");
   title = {The Real Paper Title},
   year = {2021}
 }`;
-  const a = parseBib(bibA)[0];
+  const a = citationsIn(bibA)[0];
   eq(a.title, "The Real Paper Title", "title anchored — not booktitle");
 
   // (b) brace-protected acronym must not truncate at the inner brace.
@@ -733,14 +739,14 @@ console.log("\n[S4] .bib parser edge cases:");
   year = {2026}
 }`;
   eq(
-    parseBib(bibB)[0].title,
+    citationsIn(bibB)[0].title,
     "Evaluating LLM-based Systems for Code Review",
     "brace-protected acronym kept whole",
   );
 
   // (c1) one-line entry (no \n} at column 0).
   const bibC1 = `@article{k3, title = {A One Line Entry}, year = {2020}, doi = {10.1/abc}}`;
-  const c1 = parseBib(bibC1)[0];
+  const c1 = citationsIn(bibC1)[0];
   eq(c1.title, "A One Line Entry", "one-line entry title parsed");
   eq(c1.doi, "10.1/abc", "one-line entry doi parsed");
 
@@ -750,14 +756,14 @@ console.log("\n[S4] .bib parser edge cases:");
     year = {2019}
   }`;
   eq(
-    parseBib(bibC2)[0].title,
+    citationsIn(bibC2)[0].title,
     "Indented Closing Brace",
     "indented-closing-brace entry parsed",
   );
 
   // all four parse together, in sequence (balanced-brace scan resumes correctly).
   eq(
-    parseBib(bibA + "\n" + bibB + "\n" + bibC1 + "\n" + bibC2).length,
+    citationsIn(bibA + "\n" + bibB + "\n" + bibC1 + "\n" + bibC2).length,
     4,
     "all 4 entries parsed in sequence",
   );
@@ -796,15 +802,6 @@ console.log("\n[S4] .bib parser edge cases:");
   });
   eq(n.doi, "10.1/y", "normalizeIdentifiers cleans doi");
   eq(n.arxiv, "1234.5678", "normalizeIdentifiers cleans arxiv");
-  // the exact live-reproduced break: a \bibitem DOI with a swallowed sentence period.
-  const bib = `\\begin{thebibliography}{9}
-\\bibitem{ccs23} A. Author. Title. In Proc. CCS. doi:10.1145/3576915.3623218. 2023.
-\\end{thebibliography}`;
-  eq(
-    parseBib(bib)[0].doi,
-    "10.1145/3576915.3623218",
-    "bibitem DOI trailing period not swallowed",
-  );
 }
 
 // ── Edges of the pure layer: the defensive arms, each with the input that reaches it ──────────
@@ -916,32 +913,22 @@ test("reduceVerdict: an arXiv id missed only by a non-authoritative source is un
   });
 });
 
-test("parseBib: @comment/@string/@preamble are skipped, a bare value is read, an empty one is absent", () => {
+test("citationsOf: @comment/@string/@preamble are no citations; a quoted and a bare value are read; authors written out", () => {
   const bib = [
     "@comment{c, not an entry}",
-    "@string{s, x = {y}}",
-    '@article{k1, title = "Quoted Title", year = 2017, eprint = {1706.03762}, archiveprefix = {arXiv}}',
-    "@misc{k2, title = {T}, year = ,}",
-  ].join("\n");
-  assert.deepEqual(parseBib(bib), [
-    { id: "k1", title: "Quoted Title", year: "2017", arxiv: "1706.03762" },
-    { id: "k2", title: "T" },
-  ]);
-});
-
-test("parseBib's \\bibitem fallback reads an arXiv id and an \\emph title", () => {
-  const text = [
-    "\\begin{thebibliography}{9}",
-    "\\bibitem{a} A. Author. \\emph{A Long Enough Title}. arXiv:1706.03762, 2017.",
-    "\\end{thebibliography}",
+    "@string{s = {y}}",
+    '@article{k1, title = "Quoted Title", year = 2017, eprint = {1706.03762}, archiveprefix = {arXiv}, author = {Vaswani, Ashish and von Neumann, John}}',
+    "@misc{k2, title = {T}, eprint = {x}, archiveprefix = {HAL}}",
   ].join("\n");
-  assert.deepEqual(parseBib(text), [
+  assert.deepEqual(citationsIn(bib), [
     {
-      id: "a",
-      arxiv: "1706.03762",
+      id: "k1",
+      title: "Quoted Title",
       year: "2017",
-      title: "A Long Enough Title",
+      authors: "Ashish Vaswani and John von Neumann",
+      arxiv: "1706.03762",
     },
+    { id: "k2", title: "T" },
   ]);
 });
 

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

@@ -0,0 +1,163 @@
+/**
+ * The bibtex reader over @retorquere/bibtex-parser: where each entry stands, its fields as text, its
+ * name lists as names, the `@string` and `@preamble` a copy is compared on, and an entry it cannot
+ * finish. What bibtex reads beyond it is the post-build check's (src/references.ts), measured on the
+ * planted papers in src/paper-sources.test.ts.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { absolutePath } from "../../domain/paths.ts";
+import { bibReader } from "./index.ts";
+
+const PATH = absolutePath("/p/refs.bib");
+const read = (text: string) => bibReader.readFile(PATH, text);
+
+describe("the bibtex reader", () => {
+  it("places each entry in the text, a block's within the file that holds it", () => {
+    const tex =
+      "\\begin{filecontents*}{refs.bib}\n@misc{a, title={A}}\n@Article(b, title={B})\n\\end{filecontents*}\n";
+    const body = { start: tex.indexOf("@misc"), end: tex.indexOf("\\end") };
+    const bib = bibReader.read(absolutePath("/p/paper.tex"), tex, body);
+    expect(
+      bib.entries.map((e) => [
+        e.type,
+        e.key,
+        tex.slice(e.span.start, e.span.end),
+      ]),
+    ).toEqual([
+      ["misc", "a", "@misc{a, title={A}}"],
+      ["article", "b", "@Article(b, title={B})"],
+    ]);
+  });
+
+  it("reads fields as text: LaTeX accents, a link, a list field joined", () => {
+    const [e] = read(
+      '@book{k, title={M{\\"u}ller}, howpublished={\\url{https://x.org}}, publisher={A and B}}',
+    ).entries;
+    // The parser writes `{\"u}` as u and a combining diaeresis: compared composed.
+    expect(
+      Object.fromEntries(
+        Object.entries(e?.fields ?? {}).map(([k, v]) => [
+          k,
+          v.normalize("NFC"),
+        ]),
+      ),
+    ).toEqual({
+      title: "Müller",
+      howpublished: '<a href="https://x.org">https://x.org</a>',
+      publisher: "A and B",
+    });
+  });
+
+  it("reads a name list as names: family part, particle, suffix, a literal kept whole", () => {
+    const [e] = read(
+      "@misc{k, author={Lovelace, Ada and von Neumann, Jr., John and {World Health Organization} and others}}",
+    ).entries;
+    expect(e?.names).toEqual({
+      author: [
+        { lastName: "Lovelace", firstName: "Ada" },
+        {
+          lastName: "Neumann",
+          firstName: "John",
+          prefix: "von",
+          suffix: "Jr.",
+        },
+        { name: "World Health Organization" },
+        { lastName: "others" },
+      ],
+    });
+  });
+});
+
+describe("the bibtex reader — what a copy is compared on, and what it leaves to bibtex", () => {
+  it("reads @preamble commands, and expands each @string where an entry uses it", () => {
+    const bib = read(
+      '@string{v = "Venue"}\n@preamble{"\\x"}\n@misc{k, note = v}\n@string{v = "Later"}',
+    );
+    expect([bib.preamble, bib.entries[0]?.fields]).toEqual([
+      ['"\\x"'],
+      { note: "Venue" },
+    ]);
+  });
+
+  it("keeps each entry as bibtex takes it: the value it used, LaTeX and braces as written, whitespace folded", () => {
+    const bib = read(
+      '@string{v = "Venue"}\n@Misc{k, note = v # " 2", author = {G{\\"o}del,   Kurt}, title = {{X}}, keywords = {b, a}}\n@string{v = "Later"}',
+    );
+    expect(bib.written).toEqual([
+      {
+        type: "misc",
+        key: "k",
+        fields: {
+          note: "Venue 2",
+          author: 'G{\\"o}del, Kurt',
+          title: "{X}",
+          keywords: "a, b",
+        },
+      },
+    ]);
+  });
+
+  it("an entry it cannot finish is no entry — bibtex reports that file (v6, exit 2)", () => {
+    const text = readFileSync(
+      join(
+        dirname(fileURLToPath(import.meta.url)),
+        "../../../fixtures/paper-sources/v6-unclosed/refs.bib",
+      ),
+      "utf8",
+    );
+    expect(read(text).entries.map((e) => e.key)).toEqual(["a1", "a3"]);
+  });
+});
+
+describe("the bibtex reader — databases in sequence, as bibtex reads them", () => {
+  // bibtex reads the databases of `\\bibliography{abbreviations,references}` one after the other, and an
+  // `@string` the first defines is in force in the second (fixtures/paper-sources/v27-shared-string:
+  // its .bbl typesets the expanded author and booktitle).
+  const ABBR =
+    '@string{venue = "Proceedings of the {\\"O}ld Venue"}\n@string{who = "Lovelace, Ada"}\n';
+  const REFS =
+    "@inproceedings{late, author = who, booktitle = venue # {, Main}}\n";
+  const SECOND = absolutePath("/p/references.bib");
+
+  it("🔴 an @string an earlier database defined is in force in a later one: read as one file holding both", () => {
+    const first = read(ABBR);
+    const second = bibReader.readFile(SECOND, REFS, first.strings);
+    const whole = read(ABBR + REFS);
+    expect([
+      second.entries.map((e) => [e.fields, e.names]),
+      second.written,
+    ]).toEqual([whole.entries.map((e) => [e.fields, e.names]), whole.written]);
+    expect(second.written[0]?.fields).toEqual({
+      author: "Lovelace, Ada",
+      booktitle: 'Proceedings of the {\\"O}ld Venue, Main',
+    });
+  });
+
+  it("the @strings in force after a database are those before it and its own, a redefinition winning; a block reads with them too", () => {
+    const first = read(ABBR);
+    const second = bibReader.readFile(
+      SECOND,
+      '@string{venue = "Newer"}\n',
+      first.strings,
+    );
+    expect([second.inherited, second.strings]).toEqual([
+      first.strings,
+      { VENUE: "Newer", WHO: "Lovelace, Ada" },
+    ]);
+    const tex = `\\begin{filecontents*}{refs.bib}\n${REFS}\\end{filecontents*}\n`;
+    const body = { start: tex.indexOf("@"), end: tex.indexOf("\\end") };
+    expect(
+      bibReader.read(absolutePath("/p/paper.tex"), tex, body, second.strings)
+        .written[0]?.fields.booktitle,
+    ).toBe("Newer, Main");
+  });
+
+  it("read alone, a database has nothing inherited: a name no @string defines stays unresolved", () => {
+    const alone = bibReader.readFile(SECOND, REFS);
+    expect([alone.inherited, alone.strings]).toEqual([{}, {}]);
+    expect(alone.written[0]?.fields.author).not.toBe("Lovelace, Ada");
+  });
+});

package/src/adapters/bibtex/index.ts

@@ -0,0 +1,155 @@
+/**
+ * The bibtex reader over `@retorquere/bibtex-parser` — the one `.bib` reader of paperlint
+ * (`src/ports/bib-reader.ts`).
+ *
+ * It reads a well-formed database as bibtex does: entries, fields (LaTeX read into text, so `{\"u}`
+ * is `ü` and `\url{x}` a link), name lists split into names, `@string`s expanded, `@preamble`. A
+ * second reading keeps each field as bibtex takes it, LaTeX as written: what two databases are
+ * compared by (`sameDatabase`), where `{\"u}` and `ü` must stay different. A malformed
+ * database is bibtex's to report: the build runs bibtex and fails with bibtex's own lines. The two
+ * readers also differ on one well-formed shape: bibtex has no comment syntax, so an entry behind
+ * `%` or inside `@comment{…}` is one bibtex reads and this reader does not. The build records what
+ * bibtex read, and `paper/refs-checked` names such an entry (`src/references.ts`).
+ *
+ * The parser gives each entry's text (`input`), not its place: each is found in the body in order.
+ *
+ * A database read after others starts with the `@string`s they left in force (`inherited`), as bibtex
+ * reads a paper's databases in sequence with one table of them: the parser takes them as its table of
+ * predefined `@string`s, which the database's own definitions override from where they stand. Each
+ * database is still parsed as its own text, so every entry keeps its place in the file that holds it.
+ */
+import {
+  parse,
+  type Creator,
+  type Entry,
+  type Library,
+  type Options,
+} from "@retorquere/bibtex-parser";
+import type {
+  BibEntry,
+  BibName,
+  BibStrings,
+  BibText,
+  WrittenEntry,
+} from "../../domain/paper-sources.ts";
+import type { AbsolutePath } from "../../domain/paths.ts";
+import type { Span } from "../../domain/tex-document.ts";
+import type { BibReader } from "../../ports/bib-reader.ts";
+
+/** A title as written, not sentence-cased; no field kept as raw LaTeX. */
+const OPTIONS: Readonly<Options> = { sentenceCase: false, verbatimFields: [] };
+
+/**
+ * Every field as bibtex takes it: `@string`s expanded where they are used, LaTeX left as written (no
+ * conversion, no name split, no outer braces dropped).
+ */
+const AS_WRITTEN: Readonly<Options> = {
+  raw: true,
+  sentenceCase: false,
+  verbatimFields: [/.*/],
+  removeOuterBraces: [],
+};
+
+/** A name's parts, those it has: the parser leaves the others out. */
+const nameOf = (c: Readonly<Creator>): BibName =>
+  Object.fromEntries(
+    Object.entries({
+      lastName: c.lastName,
+      firstName: c.firstName,
+      prefix: c.prefix,
+      suffix: c.suffix,
+      name: c.name,
+    }).filter((kv): kv is [string, string] => kv[1] !== undefined),
+  );
+
+const isText = (x: unknown): x is string => typeof x === "string";
+const isName = (x: unknown): x is Readonly<Creator> =>
+  typeof x === "object" && x !== null;
+
+/** An entry's fields and name lists, from the parser's one record of both. */
+function fieldsOf(e: Readonly<Entry>): Pick<BibEntry, "fields" | "names"> {
+  const pairs = Object.entries(e.fields);
+  const isNames = (k: string): boolean => e.mode[k] === "creatorlist";
+  return {
+    // A list field (`keywords`, `publisher`) is joined as BibTeX writes it.
+    fields: Object.fromEntries(
+      pairs
+        .filter(([k]) => !isNames(k))
+        .map(([k, v]) => [k, [v].flat().filter(isText).join(" and ")]),
+    ),
+    names: Object.fromEntries(
+      pairs
+        .filter(([k]) => isNames(k))
+        .map(([k, v]) => [k, [v].flat().filter(isName).map(nameOf)]),
+    ),
+  };
+}
+
+/** Each entry the parser read, placed in the text: found in `source` in order, `source` at `offset`. */
+function placed(
+  parsed: readonly Readonly<Entry>[],
+  source: string,
+  offset: number,
+): readonly BibEntry[] {
+  return parsed.reduce<{
+    readonly from: number;
+    readonly found: readonly BibEntry[];
+  }>(
+    (acc, e) => {
+      const at = source.indexOf(e.input, acc.from);
+      const end = at + e.input.length;
+      const span = { start: offset + at, end: offset + end };
+      const entry = { type: e.type.toLowerCase(), key: e.key, span };
+      return { from: end, found: [...acc.found, { ...entry, ...fieldsOf(e) }] };
+    },
+    { from: 0, found: [] },
+  ).found;
+}
+
+/** The entries the parser finished: one it could not keeps no text — it is malformed, and bibtex reports it. */
+const finished = (lib: Readonly<Library>): readonly Readonly<Entry>[] =>
+  lib.entries.filter((e) => e.input !== "");
+
+/** An entry as bibtex takes it; a list field (`keywords`) as one value. */
+const writtenOf = (e: Readonly<Entry>): WrittenEntry => ({
+  type: e.type.toLowerCase(),
+  key: e.key,
+  fields: Object.fromEntries(
+    Object.entries(e.fields).map(([k, v]) => [
+      k,
+      [v].flat().filter(isText).join(", "),
+    ]),
+  ),
+});
+
+/**
+ * The database in `body` of `text`, the text of the file at `path`, read with the `@string`s
+ * `inherited` in force. The parser is handed a copy of them: it writes into its own.
+ */
+function read(
+  path: AbsolutePath,
+  text: string,
+  body: Span,
+  inherited: BibStrings = {},
+): BibText {
+  const source = text.slice(body.start, body.end);
+  const lib = parse(source, { ...OPTIONS, strings: { ...inherited } });
+  const asWritten = parse(source, { ...AS_WRITTEN, strings: { ...inherited } });
+  return {
+    path,
+    text,
+    body,
+    entries: placed(finished(lib), source, body.start),
+    written: finished(asWritten).map(writtenOf),
+    preamble: lib.preamble,
+    inherited,
+    // Its own as bibtex takes them: the reading that keeps LaTeX as written.
+    strings: { ...inherited, ...asWritten.strings },
+  };
+}
+
+export const bibReader: BibReader = {
+  read,
+  readFile: (path, text, inherited) =>
+    read(path, text, { start: 0, end: text.length }, inherited),
+};