paperlint 7.2.0 → 9.0.0

package/src/bibliography-at.test.ts

@@ -0,0 +1,286 @@
+/**
+ * `bibliographyAt` — a path a person gave, and the bibliography to read for it. A `.bib` is read alone,
+ * as named; a `.tex`, or a directory holding `paper.tex`, is the bibliography the last build's bibtex
+ * opened (`_build/sources.json`, docs/design/paper-sources.md §1) — read from the text the author
+ * edits: the `filecontents` block that wrote a database, or the file itself. A paper with no current
+ * record is refused, in one vocabulary, naming the command that records it.
+ */
+import { describe, expect, it } from "vitest";
+import { bibReader } from "./adapters/bibtex/index.ts";
+import { latexReader } from "./adapters/latex/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 { absolutePath } from "./domain/paths.ts";
+import { bibliographyAt, bibliographyUnreadWhy } from "./paper-sources.ts";
+import {
+  leftByTeX,
+  planted,
+  recordText,
+  type Shape,
+} from "../test/recorded-fixture.ts";
+
+const doc = (body: string): string =>
+  `\\documentclass{article}\n\\begin{document}\n${body}\n\\end{document}\n`;
+const A = "@misc{a, title = {A}}\n";
+const B = "@misc{b, title = {B}}\n";
+
+/** A directory as TeX and the build leave it: the files, and the record over them (none: not built). */
+function built(
+  dir: string,
+  files: Readonly<Record<string, string>>,
+  shape: Shape | string | null,
+): Record<string, string> {
+  const record =
+    shape === null
+      ? {}
+      : {
+          [`${dir}/_build/sources.json`]:
+            typeof shape === "string" ? shape : recordText(files, shape),
+        };
+  return {
+    ...Object.fromEntries(
+      Object.entries(files).map(([f, t]) => [`${dir}/${f}`, t]),
+    ),
+    ...record,
+  };
+}
+
+const PAPER = doc("\\bibliography{refs}");
+const SHAPE: Shape = {
+  inputs: [
+    ["paper.tex", "body"],
+    ["refs.bib", "preamble"],
+  ],
+  databases: ["refs.bib"],
+};
+const OWN = { "paper.tex": PAPER, "refs.bib": A, "other.bib": B };
+
+/** Each text read, with the keys of the entries it holds. */
+const keysIn = (
+  r: ReturnType<typeof bibliographyAt>,
+): readonly (readonly [string, readonly string[]])[] =>
+  r.ok ? r.value.texts.map((t) => [t.path, entryKeys(t)] as const) : [];
+const entryKeys = (t: BibText): readonly string[] =>
+  t.entries.map((e) => e.key);
+
+const depsOf = (disk: Readonly<Record<string, string>>) => ({
+  files: memoryFiles({ "/p/notes.txt": "notes", ...disk }),
+  codec: sourcesCodec,
+  latex: latexReader,
+  bib: bibReader,
+});
+
+/** What a path comes to: the paper's directory and the files read, or the one sentence why not. */
+const at = (disk: Readonly<Record<string, string>>, path: string) => {
+  const r = bibliographyAt(absolutePath(path), depsOf(disk));
+  return r.ok
+    ? [r.value.paperDir, r.value.texts.map((t) => t.path)]
+    : bibliographyUnreadWhy(r.error);
+};
+
+describe("bibliographyAt — the paths it reads", () => {
+  const disk = built("/p", OWN, SHAPE);
+
+  it("a .bib is read alone, as named — with no record of any build", () => {
+    expect([
+      at(built("/p", OWN, null), "/p/other.bib"),
+      at(disk, "/p/other.bib"),
+    ]).toEqual([
+      ["/p", ["/p/other.bib"]],
+      ["/p", ["/p/other.bib"]],
+    ]);
+  });
+
+  it("a .tex, or the directory of a paper.tex, is the bibliography the last build's bibtex opened — not every .bib in the folder", () => {
+    expect([at(disk, "/p/paper.tex"), at(disk, "/p")]).toEqual([
+      ["/p", ["/p/refs.bib"]],
+      ["/p", ["/p/refs.bib"]],
+    ]);
+  });
+
+  it("🔴 a .bib TeX wrote from a block is read from the block of the .tex the author edits, where its entries stand", () => {
+    const tex =
+      "\\documentclass{article}\n\\begin{filecontents*}[overwrite]{refs.bib}\n" +
+      A +
+      "\\end{filecontents*}\n\\begin{document}\nx\\bibliography{refs}\n\\end{document}\n";
+    const files = { "paper.tex": tex, "refs.bib": A };
+    const d = built("/p", files, {
+      inputs: [["paper.tex", "body"]],
+      written: ["refs.bib"],
+      databases: ["refs.bib"],
+    });
+    expect(keysIn(bibliographyAt(absolutePath("/p"), depsOf(d)))).toEqual([
+      ["/p/paper.tex", ["a"]],
+    ]);
+  });
+});
+
+describe("bibliographyAt — where a block is", () => {
+  it("a block that is in an included file is read from that file", () => {
+    const files = {
+      "paper.tex": doc("\\input{bibblock}\\bibliography{refs}"),
+      "bibblock.tex": `\\begin{filecontents*}{refs.bib}\n${A}\\end{filecontents*}\n`,
+      "refs.bib": A,
+    };
+    const d = built("/p", files, {
+      inputs: [
+        ["paper.tex", "body"],
+        ["bibblock.tex", "body"],
+      ],
+      written: ["refs.bib"],
+      databases: ["refs.bib"],
+    });
+    expect(at(d, "/p")).toEqual(["/p", ["/p/bibblock.tex"]]);
+  });
+
+  it("when no text holds what bibtex read, the file TeX left is read", () => {
+    const files = {
+      "paper.tex": doc("\\bibliography{refs}"),
+      "refs.bib": A,
+    };
+    const d = built("/p", files, {
+      inputs: [["paper.tex", "body"]],
+      written: ["refs.bib"],
+      databases: ["refs.bib"],
+    });
+    expect(at(d, "/p")).toEqual(["/p", ["/p/refs.bib"]]);
+  });
+});
+
+describe("bibliographyAt — every refusal in one vocabulary, naming the path and what to give instead", () => {
+  it("a path that is not a paper, a .bib or a .tex", () => {
+    const disk = built("/p", OWN, SHAPE);
+    expect([
+      at(disk, "/p/gone.bib"),
+      at(disk, "/nowhere"),
+      at(disk, "/p/notes.txt"),
+      at(disk, "/p/gone.tex"),
+    ]).toEqual([
+      "/p/gone.bib does not exist — nowhere to take a bibliography from",
+      "no paper.tex in /nowhere — name the paper's .tex, or a .bib to read it alone",
+      "/p/notes.txt is neither a .bib nor a .tex — name the paper's directory, its .tex, or a .bib",
+      "/p/gone.tex does not exist — nowhere to take a bibliography from",
+    ]);
+  });
+
+  it("🔴 a paper with no record of a build is not read from its source — run `npx paperlint build` first", () => {
+    const disk = built("/p", OWN, null);
+    expect([at(disk, "/p"), at(disk, "/p/paper.tex")]).toEqual([
+      "/p has not been built — run `npx paperlint build` first, which records the databases bibtex reads",
+      "/p has not been built — run `npx paperlint build` first, which records the databases bibtex reads",
+    ]);
+  });
+
+  it("a record the paper has changed since, and one that cannot be read, name the command too", () => {
+    const stale = built("/p", OWN, SHAPE);
+    stale["/p/refs.bib"] = `${A}${B}`;
+    expect(at(stale, "/p")).toBe(
+      "/p changed since the last build (refs.bib edited) — run `npx paperlint build` first",
+    );
+    const broken = built("/p", OWN, "{ not json");
+    expect(at(broken, "/p")).toMatch(
+      /^the last build's record of \/p cannot be used \(.+\) — run `npx paperlint build` first$/,
+    );
+  });
+
+  it("a build whose bibtex read no database, and one whose databases are gone, have nothing to read", () => {
+    const none = built(
+      "/q",
+      { "paper.tex": doc("no bibliography") },
+      {
+        inputs: [["paper.tex", "body"]],
+      },
+    );
+    expect(at(none, "/q")).toBe(
+      "bibtex read no database in the last build of /q — there is nothing to read",
+    );
+    const gone = built(
+      "/s",
+      { "paper.tex": doc("\\bibliography{gone}") },
+      {
+        inputs: [["paper.tex", "body"]],
+        databases: ["gone.bib"],
+      },
+    );
+    expect(at(gone, "/s")).toBe(
+      "bibtex opened gone.bib in the last build of /s, and none of them is on disk now",
+    );
+  });
+});
+
+describe("bibliographyAt — a bibliography it can read only in part", () => {
+  it("🔴 a build whose bibtex also opened a database outside the paper directory (BIBINPUTS) is refused, not read in part", () => {
+    // Measured: with BIBINPUTS=../shared, bibtex's .blg names `Database file #2: shared.bib` and the
+    // .bbl typesets its entry; the paper directory holds refs.bib only.
+    const partly = built(
+      "/r",
+      { "paper.tex": doc("\\bibliography{refs,shared}"), "refs.bib": A },
+      {
+        inputs: [["paper.tex", "body"]],
+        databases: ["refs.bib", "shared.bib"],
+      },
+    );
+    expect(at(partly, "/r")).toBe(
+      "bibtex opened shared.bib in the last build of /r from outside it (its search path, BIBINPUTS), and paperlint reads only the paper's own databases — copy it into /r, or name each .bib to read it alone",
+    );
+  });
+});
+
+describe("bibliographyAt on the planted papers, with the record TeX wrote for each", () => {
+  it.each([
+    ["v3-declared", ["/p/paper.bib"]],
+    ["v26-comment-in-names", ["/p/one.bib", "/p/two.bib"]],
+    ["v16-included-block", ["/p/refs.bib"]],
+    ["v25-string-differs", ["/p/refs.bib"]],
+    // A block that TeX wrote: read from the block where the author edits it.
+    ["v8-jobname", ["/p/paper.tex"]],
+    ["v5-percent-entry", ["/p/paper.tex"]],
+    // The block names its file on the line after \\begin: still read from the block.
+    ["v30-name-next-line", ["/p/paper.tex"]],
+  ])("%s", (name, files) => {
+    const p = planted(name);
+    const disk = built("/p", leftByTeX(p), p.record);
+    expect(at(disk, "/p")).toEqual(["/p", files]);
+  });
+});
+
+describe("bibliographyAt — an @string one database defines and a later one uses", () => {
+  /** Each text read, with each entry's author and booktitle as the reader read them. */
+  const fieldsAt = (name: string) => {
+    const p = planted(name);
+    const r = bibliographyAt(
+      absolutePath("/p"),
+      depsOf(built("/p", leftByTeX(p), p.record)),
+    );
+    return r.ok
+      ? r.value.texts.map((t) => [
+          t.path,
+          t.entries.map((e) => [
+            e.key,
+            e.names["author"],
+            e.fields["booktitle"],
+          ]),
+        ])
+      : r.error;
+  };
+  const LATE = [
+    "late",
+    [{ lastName: "Lovelace", firstName: "Ada" }],
+    "Proceedings of the Shared Venue",
+  ];
+
+  it("🔴 v27-shared-string: references.bib's entry is read with the @strings abbreviations.bib defined, as bibtex read it", () => {
+    expect(fieldsAt("v27-shared-string")).toEqual([
+      ["/p/abbreviations.bib", []],
+      ["/p/references.bib", [LATE]],
+    ]);
+  });
+
+  it("🔴 v28-shared-string-block: a block that uses them is still the database TeX wrote, read where the author edits it", () => {
+    expect(fieldsAt("v28-shared-string-block")).toEqual([
+      ["/p/abbreviations.bib", []],
+      ["/p/paper.tex", [LATE]],
+    ]);
+  });
+});

package/src/build.harness.mjs

@@ -482,7 +482,7 @@ try {
   );
 
   // ── no paper.tex: a REFUSAL, not a skip ───────────────────────────────────────────────
-  const bare = paper("bare", { "paper.md": "# x" });
+  const bare = paper("bare", { "PIPELINE-STATUS.md": "# x" });
   const ntex = fakeTex();
   const nr = await buildPaper(bare, {
     cwd: root,
@@ -546,7 +546,7 @@ try {
 
   // (c) no paper.tex: refused, and a PDF left from some earlier build goes too.
   const bareStale = paper("bare-stale", {
-    "paper.md": "# x",
+    "PIPELINE-STATUS.md": "# x",
     "paper.pdf": "%PDF-stale-from-yesterday",
   });
   const bsTex = fakeTex();

package/src/build.test.ts

@@ -22,7 +22,14 @@ import {
   type PaperFacts,
 } from "./build.ts";
 import type { Geometry } from "./domain/geometry.ts";
+import { bibReader } from "./adapters/bibtex/index.ts";
+import { nodeFiles } from "./adapters/node/index.ts";
+import { sourcesCodec } from "./adapters/sources-record/index.ts";
+import { sha256Hex } from "./domain/sha256.ts";
+import { serializeSourcesRecord } from "./domain/sources-record.ts";
+import { bibliographyReader } from "./references.ts";
 import type { PdfReader } from "./pdf-facts.ts";
+import type { Recorded, TexRun } from "./sources-record.ts";
 
 const root = useTempDir("paperlint-build-test-");
 const TEX = "\\documentclass{article}\\begin{document}x\\end{document}";
@@ -44,6 +51,8 @@ interface Fake {
   noLog?: boolean;
   /** Each pass writes a different .aux, so the loop never settles. */
   churn?: boolean;
+  /** What pdflatex's `-recorder` file holds after pass `n`; without it, pdflatex records nothing. */
+  fls?: (pass: number) => string;
 }
 /** A pdflatex pass: writes the .aux, the log unless it dies first, and a PDF when it exits 0. */
 function latexPass(f: Fake, cwd: string, pass: number) {
@@ -51,6 +60,7 @@ function latexPass(f: Fake, cwd: string, pass: number) {
   const aux = f.churn ? `\\relax % ${String(pass)}\n` : (f.aux ?? "\\relax\n");
   writeFileSync(join(cwd, "paper.aux"), aux);
   if (!f.noLog) writeFileSync(join(cwd, "paper.log"), f.log ?? "");
+  if (f.fls) writeFileSync(join(cwd, "paper.fls"), f.fls(pass));
   if (status === 0) writeFileSync(join(cwd, "paper.pdf"), "%PDF-fake");
   return f.noLog ? { status } : { status, stdout: "", stderr: "" };
 }
@@ -162,7 +172,7 @@ test("documentclass: an empty name is no class; a macro inside the name contribu
 });
 
 test("facts of a paper with no paper.tex: no class", () => {
-  assert.deepEqual(readFacts(paper({ "paper.md": "# P\n" })), {
+  assert.deepEqual(readFacts(paper({ "PIPELINE-STATUS.md": "# P\n" })), {
     main: null,
     documentclass: null,
     venue: null,
@@ -263,6 +273,55 @@ test("compile: warnings the final log still reports are named in the note", asyn
   assert.match(r.notes?.[0] ?? "", /— ⚠️ the final log still reports /);
 });
 
+test("references: without a reader the step says it was not wired; with one and no checker, the record says not checked", async () => {
+  const text = {
+    "paper.tex":
+      "\\documentclass{article}\\begin{document}x\\bibliography{refs}\\end{document}",
+    "refs.bib": "@misc{a, url = {https://example.org}}\n",
+  };
+  // What a build of this paper records: TeX read paper.tex, bibtex opened refs.bib and typeset `a`.
+  const digest = (s: string) => sha256Hex(new TextEncoder().encode(s));
+  const bib = {
+    ...text,
+    "_build/sources.json": serializeSourcesRecord({
+      schema: 1,
+      inputs: [{ path: "paper.tex", role: "body" }],
+      written: [],
+      bibdata: ["refs"],
+      bibtex: {
+        ran: true,
+        databases: ["refs.bib"],
+        keys: ["a"],
+        exit: 0,
+        errors: [],
+      },
+      sha256: {
+        "paper.tex": digest(text["paper.tex"]),
+        "refs.bib": digest(text["refs.bib"]),
+      },
+    }),
+  };
+  const unwired = await build(paper(bib));
+  assert.ok(
+    unwired.r.notes?.includes(
+      "references NOT checked — no bibliography reader was wired into this build; lint will say so",
+    ),
+    JSON.stringify(unwired.r.notes),
+  );
+  const readBibliography = bibliographyReader({
+    files: nodeFiles,
+    codec: sourcesCodec,
+    bib: bibReader,
+  });
+  const wired = await build(paper(bib), {}, { readBibliography });
+  assert.ok(
+    wired.r.notes?.includes(
+      "references NOT checked — no reference checker was wired into this build; lint will say so",
+    ),
+    JSON.stringify(wired.r.notes),
+  );
+});
+
 test("measure: a review build and a stub last page are named; a measured geometry adds nothing", async () => {
   const review = await build(paper(), {}, { readPdf: reader(page(20, 60)) });
   assert.match(
@@ -382,3 +441,154 @@ test("a failed result without its lines still says what failed", () => {
     ].join("\n"),
   );
 });
+
+// ── the record of the build's sources ────────────────────────────────────────────────────────
+
+/** What a recorder was handed, for each paper it was asked about. */
+function spyRecorder(answer: Recorded) {
+  const asked: { dir: string; run: TexRun }[] = [];
+  return {
+    asked,
+    recordSources: (dir: string, run: TexRun): Recorded => {
+      asked.push({ dir, run });
+      return answer;
+    },
+  };
+}
+const RECORDED: Recorded = {
+  kind: "recorded",
+  path: "/p/_build/sources.json",
+  record: {
+    schema: 1,
+    inputs: [{ path: "paper.tex", role: "body" }],
+    written: [],
+    bibdata: [],
+    bibtex: { ran: false },
+    sha256: {},
+  },
+};
+
+test("sources: every pdflatex pass runs with -recorder, so TeX itself says which files it read", async () => {
+  const args: (readonly string[])[] = [];
+  const run = fakeRun({});
+  await build(
+    paper(),
+    {},
+    {
+      run: (bin, a, opts) => {
+        if (bin === "pdflatex") args.push(a);
+        return run(bin, a, opts);
+      },
+    },
+  );
+  assert.ok(args.length >= 2);
+  assert.ok(
+    args.every((a) => a.includes("-recorder")),
+    JSON.stringify(args),
+  );
+});
+
+test("sources: the recorder is handed the .fls of every pass, in order, and bibtex's exit when it ran", async () => {
+  const spy = spyRecorder(RECORDED);
+  const { r } = await build(
+    paper({ "paper.tex": TEX, "refs.bib": "@misc{k}\n" }),
+    {
+      aux: "\\citation{k}\n\\bibstyle{plain}\n\\bibdata{refs}\n",
+      fls: (pass) => `pass ${String(pass)}`,
+    },
+    { recordSources: spy.recordSources },
+  );
+  assert.equal(r.status, "built");
+  const [only] = spy.asked;
+  assert.equal(spy.asked.length, 1);
+  assert.match(only?.dir ?? "", /\/p\d+$/);
+  const passes = only?.run.fls ?? [];
+  assert.ok(passes.length >= 2);
+  assert.deepEqual(
+    passes,
+    passes.map((_, i) => `pass ${String(i + 1)}`),
+  );
+  assert.equal(only?.run.bibtexExit, 0);
+  assert.match(
+    r.notes?.[0] ?? "",
+    /bibtex runs?; sources: 1 file read → _build\/sources\.json$/,
+  );
+});
+
+test("sources: a build that ran no bibtex says so to the recorder", async () => {
+  const spy = spyRecorder(RECORDED);
+  await build(
+    paper(),
+    { fls: () => "x" },
+    { recordSources: spy.recordSources },
+  );
+  assert.equal(spy.asked[0]?.run.bibtexExit, null);
+});
+
+test("sources: a paper.fls an earlier build left is not this build's: pdflatex that wrote none hands the recorder none", async () => {
+  const spy = spyRecorder(RECORDED);
+  const dir = paper({ "paper.tex": TEX, "paper.fls": "INPUT stale.tex\n" });
+  await build(dir, {}, { recordSources: spy.recordSources });
+  assert.deepEqual(spy.asked[0]?.run.fls, []);
+});
+
+test("sources: without a recorder, or when it records nothing, the build still builds and the note says it did not record", async () => {
+  const unwired = await build(paper());
+  assert.equal(unwired.r.status, "built");
+  assert.ok(
+    unwired.r.notes?.[0]?.endsWith(
+      "; sources NOT recorded — no recorder was wired into this build; lint will say so",
+    ),
+    JSON.stringify(unwired.r.notes),
+  );
+  const empty = await build(
+    paper(),
+    {},
+    {
+      recordSources: spyRecorder({
+        kind: "not-recorded",
+        why: "pdflatex wrote no paper.fls — nothing to record",
+      }).recordSources,
+    },
+  );
+  assert.equal(empty.r.status, "built");
+  assert.ok(
+    empty.r.notes?.[0]?.endsWith(
+      "; sources NOT recorded — pdflatex wrote no paper.fls — nothing to record; lint will say so",
+    ),
+    JSON.stringify(empty.r.notes),
+  );
+});
+
+test("sources: the note counts the files the record lists", async () => {
+  const two: Recorded = {
+    ...RECORDED,
+    record: {
+      ...RECORDED.record,
+      inputs: [
+        { path: "paper.tex", role: "body" },
+        { path: "sections/intro.tex", role: "body" },
+      ],
+    },
+  };
+  const { r } = await build(
+    paper(),
+    {},
+    { recordSources: spyRecorder(two).recordSources },
+  );
+  assert.ok(
+    r.notes?.[0]?.endsWith("; sources: 2 files read → _build/sources.json"),
+    JSON.stringify(r.notes),
+  );
+});
+
+test("sources: a build that fails records nothing", async () => {
+  const spy = spyRecorder(RECORDED);
+  const { r } = await build(
+    paper(),
+    { latex: 1 },
+    { recordSources: spy.recordSources },
+  );
+  assert.equal(r.status, "failed");
+  assert.deepEqual(spy.asked, []);
+});