paperlint 8.0.0 → 9.0.1

package/skills/paper-pipeline/scripts/extract-ref-facts.mjs

@@ -60,16 +60,15 @@
  * registry's response, not by a comparison. If the cache kept parsed entries, those readers would
  * stay uncovered while looking covered.
  */
-import {
-  readFileSync,
-  writeFileSync,
-  existsSync,
-  mkdirSync,
-  statSync,
-} from "node:fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { join, resolve, dirname, basename } from "node:path";
-import { bibRange } from "#eslint-rules/paper-typography";
+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 "./consumer.mjs";
 
 const ROOT = process.env.CLAUDE_PROJECT_DIR || process.cwd();
@@ -111,47 +110,15 @@ const joinName = (a) =>
     .trim();
 
 /**
- * 🔴 THE .bib PARSER IS AN OPTIONAL DEPENDENCY, AND THE FAILURE MUST BE LOUD AND CARRY THE CURE.
- * It weighs 15 MB out of the consumer's 56 MB install (the package itself 9 MB plus the English
- * model `wink-eng-lite-web-model` 4 MB and `unicode2latex` 2 MB) — 27% of the weight for a single
- * call that only whoever extracts bibliography facts needs. The import here is dynamic anyway, so
- * the laziness was already there; the manifest merely stopped lying about it being required.
- *
- * ⚠️ A silent skip here would be the worst of the options: a missing checker and a passing one look
- * the same, and "the bibliography was not checked" reads as "the bibliography is fine". That is why
- * the message names the command, not the fact.
+ * The facts' entries of one database, as the bibtex reader read them (src/ports/bib-reader.ts): each
+ * with its line in the file that holds it, so a finding points where the author edits (the block's
+ * lines in paper.tex, or the `.bib`'s).
  */
-export async function parseBib(
-  text,
-  { load = () => import("@retorquere/bibtex-parser") } = {},
-) {
-  let parse;
-  try {
-    ({ parse } = await load());
-  } catch (e) {
-    if (e?.code !== "ERR_MODULE_NOT_FOUND") throw e;
-    throw new Error(
-      "parsing .bib requires @retorquere/bibtex-parser — it is declared OPTIONAL because it " +
-        "weighs 15 MB and is needed only for bibliography facts.\n" +
-        "   Install:  npm i -D @retorquere/bibtex-parser\n" +
-        "   Why not our own regex: measured 26.08 — the regex gave 0 entries on both real " +
-        "files, four libraries gave the correct 27 and 51.",
-    );
-  }
-  // `sentenceCase: false` — the title is needed as written. Our normalisation folds the case
-  // anyway, but a fact has to be a fact: a paraphrased title cannot be shown to a human.
-  const res = parse(text, { sentenceCase: false, verbatimFields: [] });
-  // The entry's line in the file — found by its key. The parser gives no positions, and a finding
-  // needs an address; a key in `.bib` is unique by definition of the format, so the search is
-  // unambiguous.
-  const lines = text.split("\n");
-  const lineOfKey = (key) => {
-    const i = lines.findIndex((l) => l.includes(`{${key},`));
-    return i === -1 ? 0 : i + 1;
-  };
-  return res.entries.map((e, i) => {
-    const f = e.fields ?? {};
-    const names = Array.isArray(f.author) ? f.author : [];
+export function factEntries(bib) {
+  const lineOf = (at) => bib.text.slice(0, at).split("\n").length;
+  return bib.entries.map((e, i) => {
+    const f = e.fields;
+    const names = e.names.author ?? [];
     // `and others` is BibTeX's `et al.`. The parser returns it as an author with no first name.
     const isOthers = (a) => !a.firstName && /^others$/i.test(a.lastName ?? "");
     const truncated = names.some(isOthers);
@@ -159,29 +126,20 @@ export async function parseBib(
       .filter((a) => !isOthers(a))
       .map(joinName)
       .filter(Boolean);
-    // A field is a string in today's parser output (list fields such as `keywords` are arrays,
-    // and none of those is read); an array or a number from another parser version is joined or
-    // printed rather than dropped.
-    const str = (v) =>
-      Array.isArray(v)
-        ? v.join(" ")
-        : typeof v === "string"
-          ? v
-          : v == null
-            ? ""
-            : String(v);
+    // Every field the reader gives is text; a field the entry lacks is "".
+    const str = (v) => v ?? "";
     const venueText = [f.booktitle, f.journal, f.note, f.howpublished]
       .map(str)
       .filter(Boolean)
       .join(" ");
     return {
       n: i + 1,
-      line: lineOfKey(e.key),
+      line: lineOf(e.span.start),
       key: e.key,
       // `raw` is where identifiers are looked for: they hide in `note`, in `journal`
       // (`arXiv preprint arXiv:2107.03374`), and in a separate `doi` field.
       raw: [
-        str(f.author && authors.join(" and ")),
+        authors.join(" and "),
         str(f.title),
         venueText,
         str(f.doi),
@@ -398,40 +356,39 @@ export function recordFrom(key, cached) {
 // ── assembling the facts ─────────────────────────────────────────────────────
 
 /**
- * `paper.tex` when it embeds its `.bib` in `filecontents` → `refs.bib` → `build/custom.bib`.
- * `refs.bib` ADDED 26.08 (defect #1). The embedded one comes first, as in `paperlint build`
- * (`bibliographyOf`, src/references.ts): the author edits it there, and the `refs.bib` LaTeX
- * writes out of it is missing before a build and stale after an edit.
+ * WHICH BIBLIOGRAPHY: the one the last build's bibtex opened, as `paperlint build` recorded it
+ * (`_build/sources.json`, docs/design/paper-sources.md §1) and `bibliographyAt` reads it
+ * (src/paper-sources.ts) — never an order of file names of our own, and never read out of TeX source.
+ *
+ *   a directory   the databases bibtex opened for its paper.tex
+ *   a .tex        the same, for that file's folder
+ *   a .bib        that file, as named
+ *
+ * A paper with no current record is refused: run `npx paperlint build` first. A database TeX wrote from
+ * a `filecontents` block is read from the block, where the author edits it.
  */
-export const SOURCE_ORDER = ["paper.tex", "refs.bib", "build/custom.bib"];
-
-/** Whether `p` is a source: any `.bib`, and a `.tex` only when it carries a `.bib`. */
-const isSource = (p) =>
-  !p.endsWith(".tex") || bibRange(readFileSync(p, "utf8")) !== null;
-
-export function resolveSource(target) {
-  const t = resolve(target);
-  if (existsSync(t) && statSync(t).isFile()) return t;
-  for (const c of SOURCE_ORDER) {
-    const p = join(t, c);
-    if (existsSync(p) && isSource(p)) return p;
-  }
-  return null;
-}
+const DEPS = {
+  files: nodeFiles,
+  codec: sourcesCodec,
+  latex: latexReader,
+  bib: bibReader,
+};
 
 /**
- * The entries of a `.bib`, or of the `.bib` a `.tex` embeds (none when it embeds none) — each
- * entry's `line` its line in the file read, so a finding points where the author edits.
+ * The bibliography of `target`: the texts to read, or why there are none — `bibliographyAt`
+ * (src/paper-sources.ts) answers, in its words. `paperDir` is where the cache and the facts go.
  */
-export async function loadEntries(path) {
-  const text = readFileSync(path, "utf8");
-  if (!path.endsWith(".tex")) return parseBib(text);
-  const bib = bibRange(text);
-  if (bib === null) return [];
-  const above = text.slice(0, bib.bodyStart).split("\n").length - 1;
-  return (await parseBib(bib.body)).map((e) =>
-    e.line === 0 ? e : { ...e, line: e.line + above },
-  );
+export function bibliographyFrom(target) {
+  const r = bibliographyAt(absolutePath(resolve(target)), DEPS);
+  if (!r.ok) return { ok: false, why: bibliographyUnreadWhy(r.error) };
+  const { paperDir, texts } = r.value;
+  return { ok: true, paperDir, texts };
+}
+
+/** The entries of one text TeX reads, each with its file. */
+export function loadEntries(bib) {
+  const file = rel(bib.path);
+  return factEntries(bib).map((e) => ({ ...e, file }));
 }
 
 /** Every registry key a list of entries needs. Computed once so the requests go in one batch. */
@@ -443,7 +400,11 @@ export function keysFor(entries) {
 
 const rel = (p) => (p.startsWith(ROOT) ? p.slice(ROOT.length + 1) : p);
 
-export function buildFacts({ source, text, entries, cache, cachePath }) {
+/**
+ * The facts of a run. `source` is the file the first database was read from (the only one, for a
+ * paper with one), `sources` every one; `source_sha256` hashes those files' bytes, in order.
+ */
+export function buildFacts({ texts, entries, cache, cachePath }) {
   const withIds = entries.map((e) => {
     const ids = extractIds(e);
     return { ...e, ids, primary: primaryOf(ids), keys: allKeys(ids) };
@@ -454,9 +415,12 @@ export function buildFacts({ source, text, entries, cache, cachePath }) {
       if (!(k in records)) records[k] = recordFrom(k, cache[k]);
   return {
     schema: SCHEMA,
-    source: rel(source),
+    source: rel(texts[0].path),
+    sources: [...new Set(texts.map((b) => rel(b.path)))],
     source_kind: "bibtex",
-    source_sha256: createHash("sha256").update(text).digest("hex"),
+    source_sha256: [...new Set(texts.map((b) => b.text))]
+      .reduce((h, t) => h.update(t), createHash("sha256"))
+      .digest("hex"),
     cache: cachePath ? rel(cachePath) : null,
     generated: new Date().toISOString().slice(0, 10),
     entries: withIds,
@@ -478,24 +442,12 @@ async function main(argv) {
       .slice(1)
       .join("=");
 
-  const src = resolveSource(target);
-  if (!src) {
-    console.error(
-      `🛑 no ${SOURCE_ORDER.join(", ")} under ${resolve(target)} — nowhere to take a bibliography from.`,
-    );
-    return 1;
-  }
-  // A paper's references are read from a `.bib`, or the one a `.tex` embeds: any other file
-  // parsed as BibTeX would report zero entries for the wrong reason.
-  if (!src.endsWith(".bib") && !src.endsWith(".tex")) {
-    console.error(
-      `🛑 ${rel(src)} is neither a .bib nor a .tex — the bibliography is read from ${SOURCE_ORDER.join(", ")}.`,
-    );
+  const found = bibliographyFrom(target);
+  if (!found.ok) {
+    console.error(`🛑 ${found.why}.`);
     return 1;
   }
-  const paperDir = statSync(resolve(target)).isFile()
-    ? dirname(src)
-    : resolve(target);
+  const { paperDir, texts } = found;
   const cachePath = opt("cache")
     ? resolve(opt("cache"))
     : join(paperDir, "repro", "refs-cache.json");
@@ -503,13 +455,13 @@ async function main(argv) {
     ? resolve(opt("out"))
     : join(paperDir, "_build", "refs.facts.json");
 
-  const text = readFileSync(src, "utf8");
-  const entries = await loadEntries(src);
+  const entries = texts.flatMap(loadEntries);
+  const names = [...new Set(texts.map((b) => basename(b.path)))].join(", ");
   if (!entries.length) {
     // 🔴 Zero entries is a suspect, not a success. Facts with an empty list would look like a
     // clean bibliography, so we do not write them at all and exit with a non-zero code.
     console.error(
-      `🛑 parsed 0 entries out of ${rel(src)}. Silence here would look like a clean bibliography.`,
+      `🛑 parsed 0 entries out of ${[...new Set(texts.map((b) => rel(b.path)))].join(", ")}. Silence here would look like a clean bibliography.`,
     );
     return 1;
   }
@@ -536,12 +488,12 @@ async function main(argv) {
     if (fetched) saveCache(cachePath, cache);
   }
 
-  const facts = buildFacts({ source: src, text, entries, cache, cachePath });
+  const facts = buildFacts({ texts, entries, cache, cachePath });
   mkdirSync(dirname(out), { recursive: true });
   writeFileSync(out, `${JSON.stringify(facts, null, 2)}\n`);
   const resolved = Object.values(facts.records).filter((r) => r.found).length;
   console.log(
-    `📚 ${basename(src)} → ${rel(out)} (${entries.length} entries, ${Object.keys(facts.records).length} identifiers, ` +
+    `📚 ${names} → ${rel(out)} (${entries.length} entries, ${Object.keys(facts.records).length} identifiers, ` +
       `${resolved} resolved${offline ? ", offline" : fetched ? `, +${fetched} fetched` : ", all from cache"})`,
   );
   return 0;

package/skills/paper-pipeline/scripts/extract-ref-facts.test.mjs

@@ -9,17 +9,18 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { test } from "vitest";
 import { runNode, useTempDir, writeTree } from "../../../test/support.ts";
+import { plantedOnDisk, recordOnDisk } from "../../../test/recorded-fixture.ts";
+import { bibliographyUnreadWhy } from "#src/paper-sources";
 import {
+  bibliographyFrom,
   buildFacts,
   extractIds,
   loadCache,
   loadEntries,
-  parseBib,
   primaryOf,
   readArxiv,
   readCrossref,
   recordFrom,
-  resolveSource,
 } from "./extract-ref-facts.mjs";
 
 const SCRIPT = join(
@@ -28,10 +29,13 @@ const SCRIPT = join(
 );
 const root = useTempDir("extract-ref-facts-");
 
-test(".bib: a key the text spells with spaces has no line; a missing title or year is null, not empty", async () => {
-  const [entry] = await parseBib(
-    "@misc{ spaced ,\n  note={see arXiv:2101.00001}\n}\n",
+test(".bib: an entry's line is where its `@` stands; a missing title or year is null, not empty", () => {
+  const bib = join(root, "lines.bib");
+  writeFileSync(
+    bib,
+    "% a comment\n\n@misc{ spaced ,\n  note={see arXiv:2101.00001}\n}\n",
   );
+  const [entry] = loadEntries(bibliographyFrom(bib).texts[0]);
   assert.deepEqual(
     {
       line: entry.line,
@@ -41,7 +45,7 @@ test(".bib: a key the text spells with spaces has no line; a missing title or ye
       raw: entry.raw,
     },
     {
-      line: 0,
+      line: 3,
       title: null,
       year: null,
       authors: [],
@@ -50,52 +54,6 @@ test(".bib: a key the text spells with spaces has no line; a missing title or ye
   );
 });
 
-test(".bib from a parser that returns no fields, or list and number fields: joined and printed, not dropped", async () => {
-  const load = async () => ({
-    parse: () => ({
-      entries: [
-        { key: "bare" },
-        {
-          key: "odd",
-          fields: {
-            title: ["Split", "Title"],
-            year: 2021,
-            note: null,
-            author: [{ firstName: "Ada", lastName: "Lovelace" }],
-          },
-        },
-      ],
-    }),
-  });
-  const [bare, odd] = await parseBib("@misc{bare,}\n@misc{odd,}\n", { load });
-  assert.deepEqual(
-    [
-      bare,
-      { title: odd.title, year: odd.year, authors: odd.authors, raw: odd.raw },
-    ],
-    [
-      {
-        n: 1,
-        line: 1,
-        key: "bare",
-        raw: "",
-        authors: [],
-        truncated: false,
-        title: null,
-        year: null,
-        venue_text: "",
-        doi_field: null,
-      },
-      {
-        title: "Split Title",
-        year: "2021",
-        authors: ["Ada Lovelace"],
-        raw: "Ada Lovelace Split Title 2021",
-      },
-    ],
-  );
-});
-
 test("identifiers: a declared DOI field comes first; an entry without text fields has none", () => {
   const ids = extractIds({
     doi_field: "10.1111/field",
@@ -181,19 +139,22 @@ test("cache: no path and a corrupt file both read as empty", () => {
   assert.deepEqual([loadCache(undefined), loadCache(corrupt)], [{}, {}]);
 });
 
-test("sources: a file names itself; a .bib is read as BibTeX; facts without a cache say so", async () => {
+test("sources: a .bib named is read as itself, as BibTeX; facts without a cache say so", async () => {
   const bib = join(root, "one.bib");
   writeFileSync(bib, "@misc{k, title={T}, year={2020}}\n");
-  assert.equal(resolveSource(bib), bib);
-  const entries = await loadEntries(bib);
+  const found = bibliographyFrom(bib);
+  assert.deepEqual([found.ok, found.texts.map((t) => t.path)], [true, [bib]]);
+  const entries = loadEntries(found.texts[0]);
   const facts = buildFacts({
-    source: bib,
-    text: "",
+    texts: found.texts,
     entries,
     cache: {},
     cachePath: null,
   });
-  assert.deepEqual([facts.source_kind, facts.cache], ["bibtex", null]);
+  assert.deepEqual(
+    [facts.source_kind, facts.cache, facts.sources],
+    ["bibtex", null, [bib]],
+  );
 });
 
 // ── the command ─────────────────────────────────────────────────────────────
@@ -205,10 +166,15 @@ const CROSSREF_OK = JSON.stringify({
     issued: { "date-parts": [[2020]] },
   },
 });
+/** A paper.tex declaring `\bibliography{refs}`, with `preamble` before its document. */
+const declaring = (preamble = "") =>
+  `\\documentclass{article}\n${preamble}\\begin{document}x\\bibliography{refs}\\end{document}\n`;
 writeTree(root, {
+  "paper/paper.tex": declaring(),
   "paper/refs.bib":
     "@misc{a, author={A. A}, title={Found}, note={doi:10.1234/ok}}\n" +
     "@misc{b, author={B. B}, title={Lost}, note={doi:10.1234/down}}\n",
+  "empty/paper.tex": declaring(),
   "empty/refs.bib": "% nothing cited\n",
   "notes/notes.txt": "A. A. Found. doi:10.1234/ok\n",
   // `fetch` in the child: 10.1234/down fails at the transport, anything else is a CrossRef hit.
@@ -217,26 +183,42 @@ writeTree(root, {
     `  if (url.includes("down")) throw new Error("network down");\n` +
     `  return { status: 200, text: async () => ${JSON.stringify(CROSSREF_OK)} };\n` +
     `};\n`,
-  // The optional .bib parser, uninstalled — and broken in some other way.
-  "no-parser.mjs":
-    "import { register } from 'node:module';\n" +
-    "register('data:text/javascript,' + encodeURIComponent(\"export async function resolve(s, c, next) { if (s === '@retorquere/bibtex-parser') throw Object.assign(new Error('gone'), { code: 'ERR_MODULE_NOT_FOUND' }); return next(s, c); }\"));\n",
-  "bad-parser.mjs":
-    "import { register } from 'node:module';\n" +
-    "register('data:text/javascript,' + encodeURIComponent(\"export async function resolve(s, c, next) { if (s === '@retorquere/bibtex-parser') throw Object.assign(new Error('broken install'), { code: 'EACCES' }); return next(s, c); }\"));\n",
+  "bib/paper.tex": declaring(),
+  "switched/paper.tex":
+    "\\documentclass{article}\\newif\\ifanon\\begin{document}x\\ifanon\\bibliography{anon}\\else\\bibliography{refs}\\fi\\end{document}\n",
+  "switched/anon.bib": "@misc{anon1, title={A}, note={doi:10.1234/a}}\n",
+  "switched/refs.bib": "@misc{refs1, title={R}, note={doi:10.1234/r}}\n",
   "bib/refs.bib": "@misc{k, title={T}, note={doi:10.1234/ok}}\n",
-  // The bibliography is embedded in paper.tex; the refs.bib beside it is a stale build output.
-  "inline/paper.tex":
-    "\\documentclass{article}\n" +
+  // The bibliography is embedded in paper.tex; the refs.bib beside it is what TeX wrote from the block.
+  "inline/paper.tex": declaring(
     "\\begin{filecontents*}[overwrite]{refs.bib}\n" +
+      "@misc{a, author={A. A}, title={Found}, note={doi:10.1234/ok}}\n" +
+      "@misc{b, author={B. B}, title={Lost}, note={doi:10.1234/down}}\n" +
+      "\\end{filecontents*}\n",
+  ),
+  "inline/refs.bib":
     "@misc{a, author={A. A}, title={Found}, note={doi:10.1234/ok}}\n" +
-    "@misc{b, author={B. B}, title={Lost}, note={doi:10.1234/down}}\n" +
-    "\\end{filecontents*}\n\\begin{document}x\\end{document}\n",
-  "inline/refs.bib": "@misc{stale, title={Stale}, note={doi:10.1234/old}}\n",
-  // A paper.tex with no embedded .bib is not a source: the refs.bib beside it is.
-  "plain/paper.tex":
-    "\\documentclass{article}\\begin{document}x\\end{document}\n",
-  "plain/refs.bib": "@misc{k, title={T}, note={doi:10.1234/ok}}\n",
+    "@misc{b, author={B. B}, title={Lost}, note={doi:10.1234/down}}\n",
+  // A paper that was never built has no record: nothing says which bibliography TeX reads.
+  "unbuilt/paper.tex": declaring(),
+  "unbuilt/refs.bib": "@misc{k, title={T}, note={doi:10.1234/ok}}\n",
+});
+/** What a build records for a paper whose bibliography is the file `db` the author keeps. */
+const keeps = (db = "refs.bib") => ({
+  inputs: [
+    ["paper.tex", "body"],
+    [db, "preamble"],
+  ],
+  databases: [db],
+});
+for (const dir of ["paper", "empty", "bib"])
+  recordOnDisk(join(root, dir), keeps());
+// bibtex opened refs.bib only: the switch took its `\else`.
+recordOnDisk(join(root, "switched"), keeps());
+recordOnDisk(join(root, "inline"), {
+  inputs: [["paper.tex", "body"]],
+  written: ["refs.bib"],
+  databases: ["refs.bib"],
 });
 const cli = (args, { cwd = root, nodeArgs = [] } = {}) =>
   runNode(SCRIPT, args, {
@@ -299,11 +281,14 @@ test("no target: the current directory", () => {
   assert.equal(r.status, 0, r.stderr);
 });
 
-test("refusals: nowhere to read from, a file that is not a .bib, and zero entries (not written as a clean bibliography)", () => {
-  assert.deepEqual(cli([join(root, "nope"), "--offline"]), {
+test("refusals: no bibliography to read (in bibliographyAt's words), and zero entries (not written as a clean bibliography)", () => {
+  // The path → bibliography vocabulary is tested once, beside bibliographyAt (src/paper-sources.ts).
+  // Here: that the command speaks it, and stops.
+  const notes = join(root, "notes/notes.txt");
+  assert.deepEqual(cli([notes, "--offline"]), {
     status: 1,
     stdout: "",
-    stderr: `🛑 no paper.tex, refs.bib, build/custom.bib under ${join(root, "nope")} — nowhere to take a bibliography from.\n`,
+    stderr: `🛑 ${bibliographyUnreadWhy({ kind: "not-bib-or-tex", path: notes })}.\n`,
   });
   assert.deepEqual(cli(["empty", "--offline"]), {
     status: 1,
@@ -311,33 +296,9 @@ test("refusals: nowhere to read from, a file that is not a .bib, and zero entrie
     stderr:
       "🛑 parsed 0 entries out of empty/refs.bib. Silence here would look like a clean bibliography.\n",
   });
-  // Guards: a file that is neither a .bib nor a .tex is named, not parsed as BibTeX, and nothing is written.
-  assert.deepEqual(cli([join(root, "notes/notes.txt"), "--offline"]), {
-    status: 1,
-    stdout: "",
-    stderr:
-      "🛑 notes/notes.txt is neither a .bib nor a .tex — the bibliography is read from paper.tex, refs.bib, build/custom.bib.\n",
-  });
-});
-
-test(".bib without its optional parser: the error names the install; any other failure is not masked", () => {
-  const missing = cli(["bib", "--offline"], {
-    nodeArgs: ["--import", join(root, "no-parser.mjs")],
-  });
-  assert.equal(missing.status, 1);
-  assert.match(
-    missing.stderr,
-    /parsing \.bib requires @retorquere\/bibtex-parser[\s\S]*Install: {2}npm i -D @retorquere\/bibtex-parser/,
-  );
-  const broken = cli(["bib", "--offline"], {
-    nodeArgs: ["--import", join(root, "bad-parser.mjs")],
-  });
-  assert.equal(broken.status, 1);
-  assert.match(broken.stderr, /broken install/);
-  assert.doesNotMatch(broken.stderr, /npm i -D/);
 });
 
-test("🔴 a paper directory whose paper.tex embeds its .bib: the embedded one is read, not a stale refs.bib", () => {
+test("🔴 a paper directory whose paper.tex embeds its .bib: the entries are read from the block that wrote it, where the author edits them", () => {
   const r = cli(["inline", "--offline"]);
   // Guards: only materialized .bib files were looked for, so a paper with its bibliography in
   // `filecontents` was refused before a build and read from a stale refs.bib after an edit.
@@ -352,35 +313,81 @@ test("🔴 a paper directory whose paper.tex embeds its .bib: the embedded one i
   );
   // Each entry's line is its line in paper.tex, where the author edits it.
   assert.deepEqual(
-    facts.entries.map((e) => [e.key, e.line]),
+    facts.entries.map((e) => [e.file, e.key, e.line]),
     [
-      ["a", 3],
-      ["b", 4],
+      ["inline/paper.tex", "a", 3],
+      ["inline/paper.tex", "b", 4],
     ],
   );
 });
 
-test("a paper.tex that embeds no .bib: in a directory the refs.bib beside it is read; named alone, it has no entries", () => {
-  assert.deepEqual(
-    cli(["plain", "--offline"]).stdout,
-    "📚 refs.bib → plain/_build/refs.facts.json (1 entries, 1 identifiers, 0 resolved, offline)\n",
-  );
-  assert.deepEqual(cli([join(root, "plain/paper.tex"), "--offline"]), {
+test("a bibliography behind a switch: the database bibtex opened is read, not every candidate", () => {
+  assert.deepEqual(cli(["switched", "--offline"]), {
+    status: 0,
+    stdout:
+      "📚 refs.bib → switched/_build/refs.facts.json (1 entries, 1 identifiers, 0 resolved, offline)\n",
+    stderr: "",
+  });
+});
+
+test("🔴 a paper that was not built is refused — run `npx paperlint build` first — never read from its source", () => {
+  assert.deepEqual(cli(["unbuilt", "--offline"]), {
     status: 1,
     stdout: "",
-    stderr:
-      "🛑 parsed 0 entries out of plain/paper.tex. Silence here would look like a clean bibliography.\n",
+    stderr: `🛑 ${join(root, "unbuilt")} has not been built — run \`npx paperlint build\` first, which records the databases bibtex reads.\n`,
   });
 });
 
-test("an embedded entry whose key has no line of its own keeps line 0, not a shifted 0", async () => {
-  const tex = join(root, "spaced.tex");
-  writeFileSync(
-    tex,
-    "x\n\\begin{filecontents*}{refs.bib}\n@misc{ spaced ,\n  note={arXiv:2101.00001}\n}\n\\end{filecontents*}\n",
+test("an embedded entry's line is its line in paper.tex", () => {
+  const block = "@misc{ spaced ,\n  note={arXiv:2101.00001}\n}\n";
+  writeTree(root, {
+    "spaced/paper.tex": declaring(
+      `\\begin{filecontents*}{refs.bib}\n${block}\\end{filecontents*}\n`,
+    ),
+    "spaced/refs.bib": block,
+  });
+  recordOnDisk(join(root, "spaced"), {
+    inputs: [["paper.tex", "body"]],
+    written: ["refs.bib"],
+    databases: ["refs.bib"],
+  });
+  const found = bibliographyFrom(join(root, "spaced", "paper.tex"));
+  assert.deepEqual(
+    loadEntries(found.texts[0]).map((e) => e.line),
+    [3],
   );
+});
+
+// ── the planted papers of fixtures/paper-sources, laid out as a build leaves them ─────
+
+test.each([
+  // [paper, the file read, the keys read] — tex-truth.json beside each paper is TeX's own answer: the
+  // databases bibtex opened. A `.bib` TeX wrote from a block is read from the block (paper.tex).
+  ["v1-stale", "refs.bib", ["stale2020"]],
+  ["v2-overwrite", "paper.tex", ["inline2024"]],
+  ["v3-declared", "paper.bib", ["declared2023"]],
+  ["v4-commented", "refs.bib", ["stale2020"]],
+  // What bibtex reads beyond these — a malformed entry, or one behind `%` or inside `@comment{…}` —
+  // the build's post-build check names (src/references.ts).
+  ["v5-percent-entry", "paper.tex", ["inline2024"]],
+  ["v6-unclosed", "refs.bib", ["a1", "a3"]],
+  ["v13-percent-text", "refs.bib", ["ok1"]],
+  ["v8-jobname", "paper.tex", ["jkey"]],
+])("%s: the bibliography bibtex opened", (paper, file, keys) => {
+  const dir = join(root, "planted", paper);
+  plantedOnDisk(dir, paper);
+  const out = join(root, "planted", `${paper}.json`);
+  const r = cli([
+    dir,
+    "--offline",
+    `--out=${out}`,
+    `--cache=${join(root, "planted", "cache.json")}`,
+  ]);
+  assert.deepEqual([r.status, r.stderr], [0, ""]);
+  assert.match(r.stdout, new RegExp(`^📚 ${file} → `));
+  const facts = JSON.parse(readFileSync(out, "utf8"));
   assert.deepEqual(
-    (await loadEntries(tex)).map((e) => e.line),
-    [0],
+    facts.entries.map((e) => e.key),
+    keys,
   );
 });