paperlint 7.2.0 → 9.0.0

package/src/paper-includes.ts

@@ -2,10 +2,12 @@
  * THE FILES OF A PAPER'S BODY, handed to ESLint — so the rules over ESLint's LaTeX text read a paper
  * whose body is in `sections/*.tex`, and report each finding at its own file and line (#144).
  *
- * The set is what TeX reads, resolved by the reader the parse-tree rules use (`bodyFiles`,
- * src/tex-paper.ts): `paper.tex` and every file an include in its document body brings in, found in
- * the paper's directory. Not a glob over every `.tex`: a frozen version under `versions/`, a macro
- * file the preamble includes and a scratch file nothing includes are not the paper.
+ * The set is what TeX read, as the last build recorded it (`_build/sources.json`, `paperRecord` in
+ * src/paper-record.ts): `paper.tex` and the `.tex` files of the paper directory TeX read after
+ * `\\begin{document}`. Nothing here reads TeX source or looks for an include on disk. Not a glob over
+ * every `.tex`: a frozen version under `versions/`, a macro file the preamble includes and a scratch
+ * file nothing includes are not the paper. A paper with no record, or one it has changed since, is
+ * `paper.tex` alone — `paper/sources-fresh` (src/sources-rules.ts) says the rest went unlinted.
  *
  * Two blocks per paper, both relative to the paper's directory (`basePath`):
  *
@@ -16,21 +18,32 @@
  *    for the rules whose verdict is the paper's (eslint-rules/paper-context.ts).
  *
  * ── ONLY `.tex` FILES ARE HANDED TO ESLint (#153) ────────────────────────────────
- * An include may resolve to a file of another extension: `\input{paper.bbl}` in a paper that ships
- * bibtex's output instead of a `.bib`, a plot exported as `.pgf`. Handed to ESLint, such a file got
- * no language — the fragment block claims `.tex` only — and the JavaScript parser stopped at its
- * first `%`. It is not given the LaTeX language either: the fragment rules judge and `--fix` the
- * prose an author writes in that file, and a file of another extension is in practice a tool's
- * output, whose words are someone else's (the titles of cited works) and whose fix the next run of
- * the tool overwrites. TeX still reads it, and so does `readPaper`: the rules over the whole paper
- * see it spliced into `paper.tex`, where TeX typesets it.
+ * TeX may read a body file of another extension: `\\input{paper.bbl}` in a paper that ships bibtex's
+ * output instead of a `.bib`, a plot exported as `.pgf`. Handed to ESLint, such a file got no
+ * language — the fragment block claims `.tex` only — and the JavaScript parser stopped at its first
+ * `%`. It is not given the LaTeX language either: the fragment rules judge and `--fix` the prose an
+ * author writes in that file, and a file of another extension is in practice a tool's output, whose
+ * words are someone else's (the titles of cited works) and whose fix the next run of the tool
+ * overwrites. TeX still reads it, and so does `readPaper`: the rules over the whole paper see it
+ * spliced into `paper.tex`, where TeX typesets it.
+ *
+ * ── NOR IS A `.tex` TeX WROTE ────────────────────────────────────────────────────
+ * A `filecontents` block may write a `.tex` the body `\\input`s (the record lists it as an input and
+ * as written, src/domain/tex-run.ts). Its words are the block's, which the author edits in the file
+ * holding the block; a fix made in the written copy is overwritten by an `[overwrite]` block on the next
+ * build, and splits the copy from the block without one. So it is read the way TeX reads it — spliced by
+ * `readPaper`, for the rules over the whole paper — and is not handed to ESLint as a file of its own.
  */
 import { extname, join, relative } from "node:path";
 import { PAPERLINT_SETTINGS } from "#eslint-rules/paper-context";
 import { callerPath } from "./caller-path.ts";
 import type { AbsolutePath } from "./domain/paths.ts";
+import {
+  paperRecord,
+  recordedFiles,
+  type RecordReadDeps,
+} from "./paper-record.ts";
 import type { ConfigBlock } from "./rules-config.ts";
-import { bodyFiles, type PaperDeps, type Unread } from "./tex-paper.ts";
 
 /** The files the fragment block (`buildConfig`) claims: the only body files ESLint is handed. */
 export const FRAGMENT_FILES: readonly string[] = ["**/*.tex"];
@@ -38,27 +51,31 @@ export const FRAGMENT_FILES: readonly string[] = ["**/*.tex"];
 /** Whether a body file is one the fragment block claims — the extension its glob names. */
 const isFragment = (file: string): boolean => extname(file) === ".tex";
 
-/** One paper's main file and body files, and the includes that resolved nowhere. */
+/** One paper's main file and the body files of its last build. */
 export interface PaperBody {
   readonly dir: string;
   readonly main: AbsolutePath;
-  /** The body files ESLint lints, each as a fragment: the `.tex` ones. */
+  /** The body files ESLint lints, each as a fragment: the `.tex` ones TeX did not write. None without a fresh record. */
   readonly files: readonly AbsolutePath[];
-  readonly missing: readonly Unread[];
 }
 
 /** The body of each paper directory in `dirs` that has a `paper.tex`. */
 export function paperBodies(
   dirs: readonly string[],
-  deps: PaperDeps,
+  deps: RecordReadDeps,
 ): readonly PaperBody[] {
   return dirs.flatMap((dir) => {
     const main = callerPath(join(dir, "paper.tex"));
-    const bytes = deps.files.readBytes(main);
-    if (bytes === null) return [];
-    const body = bodyFiles(main, new TextDecoder().decode(bytes), deps);
-    const files = body.files.filter(isFragment);
-    return [{ dir, main, files, missing: body.missing }];
+    if (!deps.files.isFile(main)) return [];
+    const record = paperRecord(dir, deps);
+    if (record.kind !== "fresh") return [{ dir, main, files: [] }];
+    const written = new Set(
+      record.record.written.map((w) => callerPath(join(dir, w))),
+    );
+    const files = recordedFiles(dir, record.record, "body").filter(
+      (f) => f !== main && isFragment(f) && !written.has(f),
+    );
+    return [{ dir, main, files }];
   });
 }
 
@@ -80,16 +97,3 @@ export const includeBlocks = (
       },
     ];
   });
-
-/** One line per include that resolved nowhere: which text lint did not read, and why. */
-export const unreadLines = (
-  bodies: readonly PaperBody[],
-  shown: (path: string) => string,
-): readonly string[] =>
-  bodies.flatMap((b) =>
-    b.missing.map(
-      (m) =>
-        `${shown(b.main)}: lint did not read \`${m.target}\` (included by ${m.file}): ` +
-        "no such file in the paper's directory or paperlint's inputs",
-    ),
-  );

package/src/paper-prose.test.ts

@@ -0,0 +1,78 @@
+import { expect, it } from "vitest";
+import { latexReader } from "./adapters/latex/index.ts";
+import { memoryFiles } from "./adapters/memory/index.ts";
+import { sourcesCodec } from "./adapters/sources-record/index.ts";
+import { paperProse } from "./paper-prose.ts";
+import { builtFixture, builtPaper } from "../test/recorded-fixture.ts";
+
+const SRC = [
+  "\\documentclass{article}",
+  "\\usepackage{amsmath} % a preamble word count of its own",
+  "\\title{A Title}",
+  "\\begin{document}",
+  "\\maketitle",
+  "\\section{Introduction}",
+  "We measure it~\\cite{a}. % a comment",
+  "",
+  "A second paragraph \\input{body}",
+  "\\begin{filecontents*}{refs.bib}",
+  "@misc{a, author = {Ada Lovelace}, title = {Never Prose}}",
+  "\\end{filecontents*}",
+  "\\end{document}",
+].join("\n");
+
+it("the body's prose, a blank line between passages, includes spliced; the preamble, comments, the inline .bib and the title stay out", () => {
+  // The build recorded TeX reading both files; the preamble holds no include.
+  const files = memoryFiles(
+    builtPaper(
+      "/p",
+      { "paper.tex": SRC, "body.tex": "\\subsection{Method}\nends here." },
+      [
+        { path: "paper.tex", role: "body" },
+        { path: "body.tex", role: "body" },
+      ],
+    ),
+  );
+  expect(
+    paperProse("/p/paper.tex", SRC, {
+      files,
+      latex: latexReader,
+      codec: sourcesCodec,
+    }),
+  ).toEqual({
+    // A citation stands as `[1]`, where it is set; a heading — here an included one — ends a passage.
+    body: "We measure it [1].\n\nA second paragraph\n\nends here.",
+    headings: ["Introduction", "Method"],
+    files: [
+      { file: "paper.tex", text: SRC },
+      { file: "body.tex", text: "\\subsection{Method}\nends here." },
+    ],
+  });
+});
+
+it("a citation stands as `[1]` and a cross-reference as `1`, so the sentence still ends on them", () => {
+  const src =
+    "\\documentclass{article}\n\\begin{document}\nIt holds~\\cite{a}. It is shown (Section~\\ref{s}).\n\\end{document}\n";
+  expect(
+    paperProse("/p/paper.tex", src, {
+      files: memoryFiles({ "/p/paper.tex": src }),
+      latex: latexReader,
+      codec: sourcesCodec,
+    }).body,
+  ).toBe("It holds [1]. It is shown (Section 1).");
+});
+
+it("🔴 a .tex a filecontents block wrote and the body \\input's is prose once: spliced where TeX read it, the block's body no prose", () => {
+  // v29-generated-input: TeX recorded body.tex — written by the block, read after \begin{document}.
+  const files = builtFixture("v29-generated-input", "/p");
+  const src = files["/p/paper.tex"] ?? "";
+  const { body } = paperProse("/p/paper.tex", src, {
+    files: memoryFiles(files),
+    latex: latexReader,
+    codec: sourcesCodec,
+  });
+  expect(
+    body.match(/This sentence is typeset from a file a block wrote\./g),
+  ).toHaveLength(1);
+  expect(body).toMatch(/^Before the generated file\. This sentence/);
+});

package/src/paper-prose.ts

@@ -0,0 +1,67 @@
+/**
+ * THE PROSE OF A paper.tex AS PLAIN TEXT — what `grade-paper-writing/prose-lint.mjs` measures.
+ *
+ * prose-lint counts sentences and words, and every metric it prints is a fraction of the word
+ * count. Read as raw text, a `.tex` puts the preamble, the `%` comments and an inline `filecontents`
+ * bibliography into that count (8127 "words" against about 4636 real ones on one paper), so every
+ * rate comes out roughly halved. This reads the paper the way the `tex/register` rule does: the
+ * includes spliced in (`readPaper`), then the body's prose as passages (`bodyProse` — the abstract
+ * to the back matter, without headings, captions, floats or code), each passage's sentences
+ * (`bodySentences`). A blank line separates two passages, so no sentence runs across them.
+ *
+ * A citation stands as `[1]` and a cross-reference as `1`, where they are set — not left out:
+ * prose-lint judges a sentence that ENDS on one (a wasted stress position) and counts references
+ * to other parts of the paper (`(Section 1)`), and both are invisible in a sentence the marks
+ * were cut out of. Math is left out; prose-lint counts no formula.
+ */
+import { bodySentences } from "./domain/register.ts";
+import { CITATION, MATH, REFERENCE } from "./domain/sentences.ts";
+import { runText } from "./domain/tex-document.ts";
+import { readPaper, type ProseDeps } from "./tex-paper.ts";
+
+/** A sentence's text with each mark as a reader would see it set, and math left out. */
+const rendered = (raw: string): string =>
+  raw
+    .replaceAll(CITATION, "[1]")
+    .replaceAll(REFERENCE, "1")
+    .replaceAll(MATH, "")
+    .replace(/\s+/gu, " ")
+    .trim();
+
+/**
+ * A paper's body prose, one passage per paragraph, its section titles in document order, and the
+ * text of each file it is made of — `paper.tex` and every file it includes, once, named as the
+ * include names it — for what the body leaves out, such as captions.
+ */
+export interface PaperProse {
+  readonly body: string;
+  readonly headings: readonly string[];
+  readonly files: readonly { readonly file: string; readonly text: string }[];
+}
+
+/** The prose and the headings of the paper whose main file is `filename` with the text `src`. */
+export function paperProse(
+  filename: string,
+  src: string,
+  deps: ProseDeps,
+): PaperProse {
+  const { text, segments } = readPaper(filename, src, deps);
+  const passages = deps.latex
+    .bodyProse(text)
+    .map((p) =>
+      bodySentences([p])
+        .map((s) => rendered(s.raw))
+        .join(" "),
+    )
+    .filter((p) => p !== "");
+  return {
+    body: passages.join("\n\n"),
+    headings: deps.latex
+      .headings(text)
+      .filter((h) => h.command.kind === "heading" && h.argument === "title")
+      .map((h) => runText(h.title).replace(/\s+/g, " ").trim()),
+    files: [...new Map(segments.map((s) => [s.file, s.source])).entries()].map(
+      ([file, text]) => ({ file, text }),
+    ),
+  };
+}

package/src/paper-record.test.ts

@@ -0,0 +1,173 @@
+/**
+ * `paperRecord(dir)` — the one answer to "what did the last build read, and is that still the paper?",
+ * over files held in memory — and the two things the rules take from a fresh record: the files of a
+ * role, and the databases bibtex opened as the bibtex reader reads them.
+ */
+import { describe, expect, it } from "vitest";
+import { bibReader } from "./adapters/bibtex/index.ts";
+import { memoryFiles } from "./adapters/memory/index.ts";
+import { sourcesCodec } from "./adapters/sources-record/index.ts";
+import type { BibText } from "./domain/paper-sources.ts";
+import { sha256Hex } from "./domain/sha256.ts";
+import {
+  serializeSourcesRecord,
+  type SourcesRecord,
+} from "./domain/sources-record.ts";
+import { paperRecord, recordedFiles } from "./paper-record.ts";
+import { recordedBibliography } from "./recorded-bibliography.ts";
+
+const DIR = "/work/paper";
+const bytes = (s: string) => new TextEncoder().encode(s);
+const digest = (s: string) => sha256Hex(bytes(s));
+
+const TEX = "\\documentclass{article}\n";
+const BIB = "@misc{a, title={A}, author={Doe, Jane}, year={2020}}\n";
+
+const RECORD: SourcesRecord = {
+  schema: 1,
+  inputs: [
+    { path: "paper.tex", role: "body" },
+    { path: "macros.tex", role: "preamble" },
+    { path: "sections/intro.tex", role: "body" },
+  ],
+  written: [],
+  bibdata: ["refs"],
+  bibtex: {
+    ran: true,
+    databases: ["refs.bib"],
+    keys: ["a"],
+    exit: 0,
+    errors: [],
+  },
+  sha256: {
+    "paper.tex": digest(TEX),
+    "macros.tex": digest("m"),
+    "sections/intro.tex": digest("i"),
+    "refs.bib": digest(BIB),
+  },
+};
+
+/** The paper directory after a build wrote `record`: every file as it was hashed. */
+const built = (record: SourcesRecord = RECORD) =>
+  memoryFiles({
+    [`${DIR}/_build/sources.json`]: serializeSourcesRecord(record),
+    [`${DIR}/paper.tex`]: TEX,
+    [`${DIR}/macros.tex`]: "m",
+    [`${DIR}/sections/intro.tex`]: "i",
+    [`${DIR}/refs.bib`]: BIB,
+  });
+
+describe("paperRecord", () => {
+  it("a paper no build has recorded has none", () => {
+    expect(
+      paperRecord(DIR, {
+        files: memoryFiles({ [`${DIR}/paper.tex`]: TEX }),
+        codec: sourcesCodec,
+      }),
+    ).toEqual({ kind: "none", unreadable: null });
+  });
+
+  it("a record that cannot be read has none, and says why", () => {
+    const files = built();
+    files.map.set(`${DIR}/_build/sources.json`, bytes("{"));
+    expect(paperRecord(DIR, { files, codec: sourcesCodec })).toEqual({
+      kind: "none",
+      unreadable: "sources.json is not JSON",
+    });
+    files.map.set(`${DIR}/_build/sources.json`, bytes('{"schema":2}'));
+    expect(paperRecord(DIR, { files, codec: sourcesCodec })).toEqual({
+      kind: "none",
+      unreadable: "sources.json is schema 2, this paperlint reads schema 1",
+    });
+  });
+
+  it("a record whose every file is as hashed is fresh", () => {
+    expect(paperRecord(DIR, { files: built(), codec: sourcesCodec })).toEqual({
+      kind: "fresh",
+      record: RECORD,
+    });
+  });
+
+  it("a file edited since the build makes it stale, and names the file", () => {
+    const files = built();
+    files.map.set(`${DIR}/sections/intro.tex`, bytes("edited"));
+    expect(paperRecord(DIR, { files, codec: sourcesCodec })).toEqual({
+      kind: "stale",
+      changed: [{ path: "sections/intro.tex", change: "edited" }],
+    });
+  });
+
+  it("a file deleted, a database edited: every change is named, in the record's order", () => {
+    const files = built();
+    files.map.delete(`${DIR}/macros.tex`);
+    files.map.set(`${DIR}/refs.bib`, bytes("@misc{b}"));
+    expect(paperRecord(DIR, { files, codec: sourcesCodec })).toEqual({
+      kind: "stale",
+      changed: [
+        { path: "macros.tex", change: "deleted" },
+        { path: "refs.bib", change: "edited" },
+      ],
+    });
+  });
+});
+
+const keysOf = (bib: BibText): readonly string[] =>
+  bib.entries.map((e) => e.key);
+
+const DEPS = { codec: sourcesCodec, bib: bibReader };
+
+describe("what a rule takes from a record", () => {
+  it("the files of a role, as absolute paths, in the order TeX first read them", () => {
+    expect(recordedFiles(DIR, RECORD, "body")).toEqual([
+      `${DIR}/paper.tex`,
+      `${DIR}/sections/intro.tex`,
+    ]);
+    expect(recordedFiles(DIR, RECORD, "preamble")).toEqual([
+      `${DIR}/macros.tex`,
+    ]);
+  });
+
+  it("the databases bibtex opened, read as the bibtex reader reads them, a block's copy marked written, a missing one named", () => {
+    const record: SourcesRecord = {
+      ...RECORD,
+      written: ["gen.bib"],
+      bibtex: {
+        ran: true,
+        databases: ["refs.bib", "gen.bib", "gone.bib", "./refs.bib"],
+        keys: [],
+        exit: 0,
+        errors: [],
+      },
+    };
+    const files = built(record);
+    files.map.set(`${DIR}/gen.bib`, bytes("@misc{g, title={G}}"));
+    const r = recordedBibliography(DIR, { ...DEPS, files });
+    expect(
+      r.kind === "recorded"
+        ? {
+            databases: r.databases.map((d) => [
+              d.name,
+              d.written,
+              keysOf(d.bib),
+            ]),
+            unread: r.unread,
+            path: r.databases[0]?.bib.path,
+          }
+        : r,
+    ).toEqual({
+      databases: [
+        ["refs.bib", false, ["a"]],
+        ["gen.bib", true, ["g"]],
+      ],
+      unread: ["gone.bib"],
+      path: `${DIR}/refs.bib`,
+    });
+  });
+
+  it("a build that ran no bibtex opened no database", () => {
+    const record: SourcesRecord = { ...RECORD, bibtex: { ran: false } };
+    expect(
+      recordedBibliography(DIR, { ...DEPS, files: built(record) }),
+    ).toMatchObject({ kind: "recorded", databases: [], unread: [] });
+  });
+});

package/src/paper-record.ts

@@ -0,0 +1,66 @@
+/**
+ * `paperRecord(dir)` — what every consumer of the build's record asks first: is there a record of
+ * this paper, and is it still about the files on disk? The answer is one of three states, and the
+ * rules that depend on the record are silent in two of them (docs/design/paper-sources.md §1):
+ *
+ *   none    no `_build/sources.json`, or one this paperlint cannot read — the paper was not built
+ *   stale   a file the build read has other bytes now (`changed` names them)
+ *   fresh   every file is as the build hashed it; the record is TeX's answer for this paper
+ *
+ * Reads through the `Files` port alone; the one paperlint-specific question — which files make a
+ * record stale — is `changesSince` (`src/domain/sources-record.ts`).
+ */
+import { resolve } from "node:path";
+import { callerPath } from "./caller-path.ts";
+import type { AbsolutePath } from "./domain/paths.ts";
+import { sha256Hex, type Sha256 } from "./domain/sha256.ts";
+import {
+  changesSince,
+  type Change,
+  type InputRole,
+  type SourcesRecord,
+} from "./domain/sources-record.ts";
+import type { Files } from "./ports/files.ts";
+import type { SourcesCodec } from "./ports/sources-codec.ts";
+import { sourcesPath } from "./sources-record.ts";
+
+export type PaperRecord =
+  /** No record, or one that cannot be read (`unreadable` says why; null for no file). */
+  | { readonly kind: "none"; readonly unreadable: string | null }
+  | { readonly kind: "stale"; readonly changed: readonly Change[] }
+  | { readonly kind: "fresh"; readonly record: SourcesRecord };
+
+/** The digest of the file at `path` in the paper directory now, or null when there is none. */
+const digestOf =
+  (dir: string, files: Files) =>
+  (path: string): Sha256 | null => {
+    const b = files.readBytes(callerPath(resolve(dir, path)));
+    return b === null ? null : sha256Hex(b);
+  };
+
+/** What reading a record needs: the disk, and the schema its text is parsed with. */
+export interface RecordReadDeps {
+  readonly files: Files;
+  readonly codec: SourcesCodec;
+}
+
+export function paperRecord(dir: string, deps: RecordReadDeps): PaperRecord {
+  const raw = deps.files.readBytes(callerPath(sourcesPath(dir)));
+  if (raw === null) return { kind: "none", unreadable: null };
+  const parsed = deps.codec.parse(new TextDecoder().decode(raw));
+  if (!parsed.ok) return { kind: "none", unreadable: parsed.why };
+  const changed = changesSince(parsed.record, digestOf(dir, deps.files));
+  return changed.length === 0
+    ? { kind: "fresh", record: parsed.record }
+    : { kind: "stale", changed };
+}
+
+/** The files of `role` the record lists, as absolute paths, in the order TeX first read them. */
+export const recordedFiles = (
+  dir: string,
+  record: SourcesRecord,
+  role: InputRole,
+): readonly AbsolutePath[] =>
+  record.inputs
+    .filter((i) => i.role === role)
+    .map((i) => callerPath(resolve(dir, i.path)));

package/src/paper-settings-commands.test.ts

@@ -233,7 +233,7 @@ describe("paperlint lint — the venue preset's rules", () => {
     });
   });
 
-  it("🔴 an unbuilt agenticdev paper: ONE warning (pdf/measured), and no balance error", async () => {
+  it("🔴 an unbuilt agenticdev paper: two warnings (pdf/measured, paper/sources-fresh), and no balance error", async () => {
     const root = project({
       "papers/a/paperlint.json": JSON.stringify({
         extends: "paperlint:agenticdev",
@@ -245,7 +245,10 @@ describe("paperlint lint — the venue preset's rules", () => {
     });
     const r = await lint(root);
     expect(r.code).toBe(0);
-    expect(rulesIn(r.out, "a")).toEqual(["pdf/measured"]);
+    expect(rulesIn(r.out, "a")).toEqual([
+      "pdf/measured",
+      "paper/sources-fresh",
+    ]);
   });
 });
 

package/src/paper-sources.ts

@@ -0,0 +1,151 @@
+/**
+ * `bibliographyAt(path)` — the one answer to "a path a person gave → the bibliography to read", for
+ * every script that takes one (`extract-ref-facts`, `bib-authors`, `verify-cites`). A `.bib` is read
+ * alone, as named; a `.tex`, or a directory holding `paper.tex`, is the bibliography the last build's
+ * bibtex opened for that paper — TeX's answer, from `_build/sources.json` (docs/design/paper-sources.md
+ * §1), never read out of TeX source.
+ */
+import { dirname, extname, join } from "node:path";
+import { callerPath } from "./caller-path.ts";
+import { MAIN_FILE, type BibText } from "./domain/paper-sources.ts";
+import type { AbsolutePath } from "./domain/paths.ts";
+import { err, ok, type Result } from "./domain/result.ts";
+import { describeChanges } from "./domain/sources-record.ts";
+import type { PaperRecord } from "./paper-record.ts";
+import {
+  authoredTexts,
+  recordedBibliography,
+  type RecordedDeps,
+} from "./recorded-bibliography.ts";
+
+const decoded = (b: Uint8Array): string => new TextDecoder().decode(b);
+
+// ── a path a person gave → the bibliography to read ─────────────────────────────────────────
+
+/** What a path a person gave comes to: where the paper is, and the texts to read. */
+export interface PathBibliography {
+  /** The `.bib`'s directory, the `.tex`'s, or the directory named. */
+  readonly paperDir: AbsolutePath;
+  readonly texts: readonly [BibText, ...BibText[]];
+}
+
+/** Why a path a person gave has no bibliography to read. One vocabulary for every caller. */
+export type BibliographyUnread =
+  /** A `.bib` or `.tex` named that is not there. */
+  | { readonly kind: "missing"; readonly path: AbsolutePath }
+  /** A file that is neither a `.bib` nor a `.tex`. */
+  | { readonly kind: "not-bib-or-tex"; readonly path: AbsolutePath }
+  /** Not a file, and no `paper.tex` in it. */
+  | { readonly kind: "no-paper"; readonly path: AbsolutePath }
+  /** A paper with no current record of a build: what bibtex read is not known (`state` says why). */
+  | {
+      readonly kind: "not-built";
+      readonly dir: AbsolutePath;
+      readonly state: Exclude<PaperRecord, { readonly kind: "fresh" }>;
+    }
+  /** A paper whose last build's bibtex read no database, or whose databases are not on disk now. */
+  | {
+      readonly kind: "no-database";
+      readonly dir: AbsolutePath;
+      /** The databases bibtex opened: none when it ran none. */
+      readonly opened: readonly string[];
+    }
+  /**
+   * A paper whose last build's bibtex also opened databases the paper directory does not hold — found
+   * on its search path (BIBINPUTS). Reading the others alone would leave every entry of these out.
+   */
+  | {
+      readonly kind: "outside-paper";
+      readonly dir: AbsolutePath;
+      /** As bibtex names them. */
+      readonly unread: readonly [string, ...string[]];
+    };
+
+/** The texts of the paper in `dir` the last build's bibtex read, or why there are none. */
+function ofPaper(
+  dir: AbsolutePath,
+  deps: RecordedDeps,
+): Result<PathBibliography, BibliographyUnread> {
+  const r = recordedBibliography(dir, deps);
+  if (r.kind === "unrecorded")
+    return err({ kind: "not-built", dir, state: r.record });
+  const [first, ...rest] = authoredTexts(dir, r, deps);
+  if (first === undefined)
+    return err({
+      kind: "no-database",
+      dir,
+      opened: r.record.bibtex.ran ? r.record.bibtex.databases : [],
+    });
+  // Some databases read and some not is no bibliography: a script would report on part of it as on all.
+  const [outside, ...more] = r.unread;
+  return outside === undefined
+    ? ok({ paperDir: dir, texts: [first, ...rest] })
+    : err({ kind: "outside-paper", dir, unread: [outside, ...more] });
+}
+
+/**
+ * THE answer to "a path a person gave → the bibliography to read", for every script that takes one: a
+ * `.bib` is read alone, as named; a `.tex`, or a directory holding `paper.tex`, is the bibliography the
+ * last build's bibtex opened for that paper (`_build/sources.json`) — never a guess by file name, and
+ * never read out of TeX source. A paper with no current record is refused: run `npx paperlint build`
+ * first, and so is one whose bibtex also opened a database outside the paper directory — a part of the
+ * bibliography is not given as the whole. Anything else is refused in the words `bibliographyUnreadWhy`
+ * gives.
+ */
+export function bibliographyAt(
+  path: AbsolutePath,
+  deps: RecordedDeps,
+): Result<PathBibliography, BibliographyUnread> {
+  const ext = extname(path).toLowerCase();
+  if (ext === ".bib" || ext === ".tex") {
+    const bytes = deps.files.readBytes(path);
+    if (bytes === null) return err({ kind: "missing", path });
+    return ext === ".bib"
+      ? ok({
+          paperDir: callerPath(dirname(path)),
+          texts: [deps.bib.readFile(path, decoded(bytes))],
+        })
+      : ofPaper(callerPath(dirname(path)), deps);
+  }
+  if (deps.files.isFile(path)) return err({ kind: "not-bib-or-tex", path });
+  return deps.files.readBytes(callerPath(join(path, MAIN_FILE))) === null
+    ? err({ kind: "no-paper", path })
+    : ofPaper(path, deps);
+}
+
+const BUILD = "run `npx paperlint build` first";
+
+/** Why a paper has no current record, in words a person can act on. */
+function notBuiltWhy(
+  dir: AbsolutePath,
+  s: Extract<BibliographyUnread, { readonly kind: "not-built" }>["state"],
+): string {
+  switch (s.kind) {
+    case "none":
+      return s.unreadable === null
+        ? `${dir} has not been built — ${BUILD}, which records the databases bibtex reads`
+        : `the last build's record of ${dir} cannot be used (${s.unreadable}) — ${BUILD}`;
+    case "stale":
+      return `${dir} changed since the last build (${describeChanges(s.changed)}) — ${BUILD}`;
+  }
+}
+
+/** One sentence: why `bibliographyAt` refused, naming the path and what to give instead. */
+export function bibliographyUnreadWhy(e: BibliographyUnread): string {
+  switch (e.kind) {
+    case "missing":
+      return `${e.path} does not exist — nowhere to take a bibliography from`;
+    case "not-bib-or-tex":
+      return `${e.path} is neither a .bib nor a .tex — name the paper's directory, its .tex, or a .bib`;
+    case "no-paper":
+      return `no paper.tex in ${e.path} — name the paper's .tex, or a .bib to read it alone`;
+    case "not-built":
+      return notBuiltWhy(e.dir, e.state);
+    case "no-database":
+      return e.opened.length === 0
+        ? `bibtex read no database in the last build of ${e.dir} — there is nothing to read`
+        : `bibtex opened ${e.opened.join(", ")} in the last build of ${e.dir}, and none of them is on disk now`;
+    case "outside-paper":
+      return `bibtex opened ${e.unread.join(", ")} in the last build of ${e.dir} from outside it (its search path, BIBINPUTS), and paperlint reads only the paper's own databases — copy it into ${e.dir}, or name each .bib to read it alone`;
+  }
+}