paperlint 8.0.0 → 9.0.0

package/src/adapters/tex-output/index.test.ts

@@ -0,0 +1,171 @@
+/**
+ * The readers of what TeX writes beside a paper — `.fls` (pdflatex `-recorder`) and the errors in
+ * bibtex's `.blg` — on files captured whole from real runs of the planted papers in
+ * `fixtures/paper-sources/` (test/fixtures/tex-output/README.md), not on text written for the test.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { texOutput } from "./index.ts";
+
+const CAPTURES = join(
+  dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url))))),
+  "test",
+  "fixtures",
+  "tex-output",
+);
+const capture = (paper: string, file: string): string =>
+  readFileSync(join(CAPTURES, paper, file), "utf8");
+
+/** The lines that name a file of the paper: not the TeX tree's (absolute) files. */
+const ofPaper = (text: string) =>
+  texOutput.fls(text).lines.filter((l) => !l.path.startsWith("/"));
+
+describe("the .fls reader", () => {
+  it("reads every INPUT and OUTPUT line in order, and the directory pdflatex ran in", () => {
+    const fls = texOutput.fls(capture("v8-jobname", "paper.fls"));
+    expect(fls.pwd).toBe("/work/paper");
+    expect(fls.lines.filter((l) => !l.path.startsWith("/"))).toEqual([
+      { op: "INPUT", path: "paper.tex" },
+      { op: "OUTPUT", path: "paper.log" },
+      { op: "INPUT", path: "./paper.bib" },
+      { op: "INPUT", path: "paper.bib" },
+      { op: "OUTPUT", path: "paper.bib" },
+      { op: "INPUT", path: "./paper.aux" },
+      { op: "INPUT", path: "./paper.aux" },
+      { op: "INPUT", path: "paper.aux" },
+      { op: "OUTPUT", path: "paper.aux" },
+      { op: "INPUT", path: "./paper.bbl" },
+      { op: "INPUT", path: "./paper.bbl" },
+      { op: "INPUT", path: "paper.bbl" },
+      { op: "OUTPUT", path: "paper.pdf" },
+      { op: "INPUT", path: "paper.aux" },
+    ]);
+  });
+
+  it("keeps the TeX tree's files too, as the absolute paths TeX opened", () => {
+    const fls = texOutput.fls(capture("v3-declared", "paper.fls"));
+    expect(fls.lines.slice(0, 4)).toEqual([
+      { op: "INPUT", path: "/usr/share/texlive/texmf.cnf" },
+      { op: "INPUT", path: "/usr/share/texlive/texmf-dist/web2c/texmf.cnf" },
+      {
+        op: "INPUT",
+        path: "/usr/share/texlive/texmf-var/web2c/pdftex/pdflatex.fmt",
+      },
+      { op: "INPUT", path: "paper.tex" },
+    ]);
+  });
+});
+
+describe("the .fls reader, on the shapes of a real run", () => {
+  it("a file in a folder keeps its folder; a first pass has no .aux to read yet; a block over a .bib that is already there writes nothing", () => {
+    expect(ofPaper(capture("p1", "first-pass.fls"))).toEqual([
+      { op: "INPUT", path: "paper.tex" },
+      { op: "OUTPUT", path: "paper.log" },
+      { op: "INPUT", path: "./refs.bib" },
+      { op: "INPUT", path: "refs.bib" },
+      { op: "OUTPUT", path: "paper.aux" },
+      { op: "INPUT", path: "./sections/intro.tex" },
+      { op: "INPUT", path: "./sections/intro.tex" },
+      { op: "INPUT", path: "./sections/intro.tex" },
+      { op: "INPUT", path: "./sections/intro.tex" },
+      { op: "INPUT", path: "sections/intro.tex" },
+      { op: "OUTPUT", path: "paper.pdf" },
+      { op: "INPUT", path: "paper.aux" },
+    ]);
+  });
+
+  it("a path with a space is the whole rest of the line; text that is not a line of the format is skipped", () => {
+    expect(
+      texOutput.fls(
+        "PWD /a b/p\nINPUT my file.tex\nOUTPUT out dir/x.aux\nsomething else\nINPUT\n",
+      ),
+    ).toEqual({
+      pwd: "/a b/p",
+      lines: [
+        { op: "INPUT", path: "my file.tex" },
+        { op: "OUTPUT", path: "out dir/x.aux" },
+      ],
+    });
+  });
+
+  it("an .fls with no PWD line has no directory", () => {
+    expect(texOutput.fls("INPUT paper.tex\n")).toEqual({
+      pwd: null,
+      lines: [{ op: "INPUT", path: "paper.tex" }],
+    });
+  });
+});
+
+describe("the .blg error reader", () => {
+  it("a run that ends well reports none, warnings included", () => {
+    expect(texOutput.blgErrors(capture("v3-declared", "paper.blg"))).toEqual(
+      [],
+    );
+    expect(
+      texOutput.blgErrors(
+        "Database file #1: x.bib\nWarning--I'm ignoring a's extra \"year\" field\n--line 1 of file x.bib\n",
+      ),
+    ).toEqual([]);
+  });
+});
+
+describe("the .blg error reader, on what real runs reported", () => {
+  it("an entry never closed: the message before the dashes, the file and the line after", () => {
+    expect(texOutput.blgErrors(capture("v6-unclosed", "paper.blg"))).toEqual([
+      {
+        message: "I was expecting a `,' or a `}'",
+        file: "refs.bib",
+        line: 4,
+      },
+    ]);
+  });
+
+  it("a second \\bibdata command is an error in the .aux", () => {
+    expect(
+      texOutput.blgErrors(capture("v9-two-bibliographies", "paper.blg")),
+    ).toEqual([
+      {
+        message: "Illegal, another \\bibdata command",
+        file: "paper.aux",
+        line: 5,
+      },
+    ]);
+  });
+
+  it("dashes on the first line of the log have no message before them", () => {
+    expect(texOutput.blgErrors("---line 1 of file paper.aux\n")).toEqual([
+      { message: "", file: "paper.aux", line: 1 },
+    ]);
+  });
+
+  it("a message on the line before its dashes, and an error with no line", () => {
+    expect(
+      texOutput.blgErrors(
+        [
+          "The style file: plain.bst",
+          "I couldn't open database file paper.bib",
+          "---line 4 of file paper.aux",
+          " : \\bibdata{paper",
+          " :               }",
+          "I'm skipping whatever remains of this command",
+          "I found no database files---while reading file paper.aux",
+          'Warning--I didn\'t find a database entry for "declared2023"',
+          "(There were 2 error messages)",
+        ].join("\n"),
+      ),
+    ).toEqual([
+      {
+        message: "I couldn't open database file paper.bib",
+        file: "paper.aux",
+        line: 4,
+      },
+      {
+        message: "I found no database files",
+        file: "paper.aux",
+        line: null,
+      },
+    ]);
+  });
+});

package/src/adapters/tex-output/index.ts

@@ -0,0 +1,12 @@
+/**
+ * The readers of what TeX writes beside a paper: pdflatex's `-recorder` file and bibtex's errors.
+ * One implementation of `TexOutput` (`src/ports/tex-output.ts`).
+ */
+import type { TexOutput } from "../../ports/tex-output.ts";
+import { parseBlgErrors } from "./blg.ts";
+import { parseFls } from "./fls.ts";
+
+export const texOutput: TexOutput = {
+  fls: parseFls,
+  blgErrors: parseBlgErrors,
+};

package/src/bib-rules.test.ts

@@ -0,0 +1,356 @@
+/**
+ * The `bib` rules through real ESLint on the `tex/latex` language: `bib/reachable-entry` judges the
+ * entries of the databases the build's bibtex OPENED (`_build/sources.json`), fires, stays silent, and
+ * reports where the entry is — on its line in `paper.tex` for a `.bib` TeX wrote from a block there,
+ * at the top of `paper.tex` with `refs.bib:3:1:` first for any other. A paper with no record, or one
+ * that changed since, gets nothing from this rule (`paper/sources-fresh` speaks once instead).
+ * On the planted papers of fixtures/paper-sources too, with the record TeX wrote for each.
+ */
+import { join } from "node:path";
+import { ESLint, type Linter } from "eslint";
+import { describe, expect, it } from "vitest";
+import { texLanguage } from "../eslint-rules/latex-language.ts";
+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 { BIB_RULE_LEVELS, bibRules } from "./bib-rules.ts";
+import { eslintConfig } from "./cli.ts";
+import {
+  leftByTeX,
+  planted,
+  recordText,
+  type Shape,
+} from "../test/recorded-fixture.ts";
+import { present } from "../test/support.ts";
+
+const PAPER = "/work/papers/p";
+
+/** A paper in memory: its files by relative path, and the record its build wrote (none: not built). */
+interface Paper {
+  readonly tex: string;
+  readonly files?: Readonly<Record<string, string>>;
+  readonly record?: string | Shape | null;
+}
+
+/** Lint `paper.tex` (or `file`) of a paper laid out as TeX leaves it. */
+async function lint(
+  p: Paper,
+  { file = "paper.tex", buffer = p.tex } = {},
+): Promise<{ messages: Linter.LintMessage[] }> {
+  const all = { "paper.tex": p.tex, ...p.files };
+  const record =
+    p.record === undefined || p.record === null
+      ? null
+      : typeof p.record === "string"
+        ? p.record
+        : recordText(all, p.record);
+  const files = memoryFiles({
+    ...Object.fromEntries(
+      Object.entries(all).map(([rel, text]) => [`${PAPER}/${rel}`, text]),
+    ),
+    ...(record === null ? {} : { [`${PAPER}/_build/sources.json`]: record }),
+  });
+  const eslint = new ESLint({
+    cwd: "/work",
+    overrideConfigFile: true,
+    overrideConfig: eslintConfig([
+      {
+        files: ["**/*.tex"],
+        plugins: {
+          tex: { languages: { latex: texLanguage } },
+          bib: {
+            rules: bibRules({
+              files,
+              codec: sourcesCodec,
+              latex: latexReader,
+              bib: bibReader,
+            }),
+          },
+        },
+        language: "tex/latex",
+        linterOptions: { reportUnusedDisableDirectives: "error" },
+        rules: BIB_RULE_LEVELS,
+      },
+    ]),
+  });
+  const [res] = await eslint.lintText(buffer, {
+    filePath: join(PAPER, file),
+  });
+  const r = present(res, "one lint result");
+  expect(r.messages.filter((m) => m.fatal)).toEqual([]);
+  return { messages: r.messages };
+}
+
+const found = (
+  messages: readonly Linter.LintMessage[],
+  rule: string,
+): readonly (readonly [number, number, string])[] =>
+  messages
+    .filter((m) => m.ruleId === `bib/${rule}`)
+    .map((m) => [m.line, m.column, m.message] as const);
+
+/** A paper whose bibliography is a block, and the `.bib` TeX wrote from it, as a build leaves them. */
+const inline = (entries: string): Paper => ({
+  tex: `\\documentclass{acmart}\n\\begin{filecontents*}[overwrite]{refs.bib}\n${entries}\n\\end{filecontents*}\n\\begin{document}\nx\n\\bibliography{refs}\n\\end{document}\n`,
+  files: { "refs.bib": `${entries}\n` },
+  record: {
+    inputs: [["paper.tex", "body"]],
+    written: ["refs.bib"],
+    databases: ["refs.bib"],
+  },
+});
+
+const DECLARING =
+  "\\documentclass{acmart}\n\\begin{document}\nx\n\\bibliography{refs}\n\\end{document}\n";
+const KEPT: Shape = {
+  inputs: [
+    ["paper.tex", "body"],
+    ["refs.bib", "preamble"],
+  ],
+  databases: ["refs.bib"],
+};
+/** A paper whose bibliography is the `refs.bib` the author keeps. */
+const declaring = (bib: string): Paper => ({
+  tex: DECLARING,
+  files: { "refs.bib": bib },
+  record: KEPT,
+});
+
+describe("bib/reachable-entry", () => {
+  it("a doi, a url or an arXiv id each make an entry reachable; @string is not an entry", async () => {
+    const { messages } = await lint(
+      inline(
+        "@article{a, doi = {10.1/x}}\n@misc{b, url = {https://x.org}}\n@misc{c, note = {arXiv:2310.05736}}\n@string{v = {x}}",
+      ),
+    );
+    expect(found(messages, "reachable-entry")).toEqual([]);
+  });
+
+  // Measured on the accepted corpus: 89 entries carry their only link as `howpublished = {\url{…}}`,
+  // which the bibliography style typesets — a link the reader has.
+  it("a \\url or \\href in any field is a link the reader has; a bare address in a field the style drops is not", async () => {
+    const { messages } = await lint(
+      inline(
+        "@misc{web, howpublished = {\\url{https://x.org}}}\n@misc{ref, note = {see \\href{https://x.org}{here}}}\n@techreport{src, source = {http://x.org}}",
+      ),
+    );
+    expect(
+      found(messages, "reachable-entry").map((m) => m[2].slice(0, 5)),
+    ).toEqual(["`src`"]);
+  });
+});
+
+describe("bib/reachable-entry — keys and where a finding goes", () => {
+  it("an entry written with no key is named `?`", async () => {
+    const { messages } = await lint(inline("@article{, title = {x}}"));
+    expect(
+      found(messages, "reachable-entry").map((m) => m[2].slice(0, 3)),
+    ).toEqual(["`?`"]);
+  });
+
+  it("an entry of a `.bib` TeX wrote from a block of paper.tex is reported on its own line there", async () => {
+    const { messages } = await lint(
+      inline("@misc{ok, url = {https://x.org}}\n@article{lost, title = {x}}"),
+    );
+    expect(found(messages, "reachable-entry")).toEqual([
+      [4, 1, expect.stringMatching(/^`lost` has no doi/)],
+    ]);
+  });
+
+  it("🔴 an entry in refs.bib — a file the author keeps — is reported at the top of paper.tex, with its file and line", async () => {
+    const { messages } = await lint(
+      declaring(
+        "@misc{ok, url = {https://x.org}}\n\n@article{lost, title = {x}}\n",
+      ),
+    );
+    expect(found(messages, "reachable-entry")).toEqual([
+      [1, 1, expect.stringMatching(/^refs\.bib:3:1: `lost` has no doi/)],
+    ]);
+  });
+
+  it("in a .bib, the directive on the line above the entry keeps the exception where the entry is", async () => {
+    const { messages } = await lint(
+      declaring(
+        "% eslint-disable-next-line bib/reachable-entry -- an invited talk, no recording exists\n@misc{talk, title = {x}}\n" +
+          "% eslint-disable-next-line bib/other-rule\n@misc{lost, title = {y}}\n",
+      ),
+    );
+    expect(found(messages, "reachable-entry").map((m) => m[2])).toEqual([
+      expect.stringMatching(/^refs\.bib:4:1: `lost`/),
+    ]);
+  });
+
+  it("🔴 inside the block, a disable directive silences exactly the next entry", async () => {
+    const { messages } = await lint(
+      inline(
+        "% eslint-disable-next-line bib/reachable-entry -- an invited talk, no recording exists\n@misc{talk, title = {x}}\n@misc{lost, title = {y}}",
+      ),
+    );
+    expect(found(messages, "reachable-entry").map((m) => m[2])).toEqual([
+      expect.stringMatching(/^`lost`/),
+    ]);
+  });
+});
+
+describe("bib/reachable-entry — a block is only a lookup of where the text stands", () => {
+  it("🔴 the block is a lookup of where the text stands: when paper.tex no longer holds what TeX read, the finding is at the top, naming the .bib", async () => {
+    const p = inline("@article{lost, title = {x}}");
+    const { messages } = await lint(p, {
+      buffer: p.tex.replace("{x}", "{edited since the build}"),
+    });
+    expect(found(messages, "reachable-entry")).toEqual([
+      [1, 1, expect.stringMatching(/^refs\.bib:1:1: `lost`/)],
+    ]);
+  });
+
+  it("a block in an included file: the finding is at the top of paper.tex, naming the entry in the file that holds the block", async () => {
+    const entries =
+      "@misc{ok, url = {https://x.org}}\n@article{lost, title = {x}}";
+    const { messages } = await lint({
+      tex: "\\documentclass{acmart}\n\\input{bibblock}\n\\begin{document}\nx\n\\bibliography{refs}\n\\end{document}\n",
+      files: {
+        "bibblock.tex": `\\begin{filecontents*}{refs.bib}\n${entries}\n\\end{filecontents*}\n`,
+        "refs.bib": `${entries}\n`,
+      },
+      record: {
+        inputs: [
+          ["paper.tex", "body"],
+          ["bibblock.tex", "preamble"],
+        ],
+        written: ["refs.bib"],
+        databases: ["refs.bib"],
+      },
+    });
+    expect(found(messages, "reachable-entry")).toEqual([
+      [1, 1, expect.stringMatching(/^bibblock\.tex:3:1: `lost`/)],
+    ]);
+  });
+
+  it("🔴 two blocks with the same entries: the finding is in the block that wrote the database bibtex opened", async () => {
+    const entry = "@article{lost, title = {x}}";
+    const block = (name: string) =>
+      `\\begin{filecontents*}{${name}}\n${entry}\n\\end{filecontents*}\n`;
+    const { messages } = await lint({
+      tex: `\\documentclass{acmart}\n${block("a.bib")}${block("b.bib")}\\begin{document}\nx\n\\bibliography{b}\n\\end{document}\n`,
+      files: { "a.bib": `${entry}\n`, "b.bib": `${entry}\n` },
+      record: {
+        inputs: [["paper.tex", "body"]],
+        written: ["a.bib", "b.bib"],
+        databases: ["b.bib"],
+      },
+    });
+    expect(found(messages, "reachable-entry")).toEqual([
+      [6, 1, expect.stringMatching(/`lost`/)],
+    ]);
+  });
+});
+
+describe("bib/reachable-entry — which bibliography: the one bibtex opened", () => {
+  it("only the databases the build's bibtex opened are judged, not every .bib that lies in the folder", async () => {
+    const { messages } = await lint({
+      ...declaring("@misc{r1, title = {x}}\n"),
+      files: {
+        "refs.bib": "@misc{r1, title = {x}}\n",
+        "anon.bib": "@misc{a1, title = {x}}\n",
+      },
+    });
+    expect(
+      found(messages, "reachable-entry").map((m) => m[2].slice(0, 16)),
+    ).toEqual(["refs.bib:1:1: `r"]);
+  });
+
+  it("a paper with no record is not judged: paper/sources-fresh says it was not built", async () => {
+    const p = declaring("@misc{lost, title = {x}}\n");
+    expect(
+      found((await lint({ ...p, record: null })).messages, "reachable-entry"),
+    ).toEqual([]);
+  });
+
+  it("🔴 a record the paper has changed since is not judged either — the entries it names may be gone", async () => {
+    const p = declaring("@misc{lost, title = {x}}\n");
+    const record = recordText({ "paper.tex": p.tex, ...p.files }, KEPT);
+    expect(
+      found(
+        (
+          await lint({
+            ...p,
+            files: {
+              "refs.bib": "@misc{lost, title = {x}, note = {edited}}\n",
+            },
+            record,
+          })
+        ).messages,
+        "reachable-entry",
+      ),
+    ).toEqual([]);
+  });
+
+  it("a build whose bibtex ran none, and a database that is not on disk now, hold no entries to judge", async () => {
+    const none = declaring("@misc{lost, title = {x}}\n");
+    expect(
+      found(
+        (await lint({ ...none, record: { inputs: [["paper.tex", "body"]] } }))
+          .messages,
+        "reachable-entry",
+      ),
+    ).toEqual([]);
+    const gone = await lint({
+      tex: DECLARING,
+      files: {},
+      record: {
+        inputs: [["paper.tex", "body"]],
+        databases: ["refs.bib"],
+      },
+    });
+    expect(found(gone.messages, "reachable-entry")).toEqual([]);
+  });
+});
+
+describe("bib/reachable-entry — which file", () => {
+  it("only paper.tex is judged", async () => {
+    const { messages } = await lint(inline("@article{lost, title = {x}}"), {
+      file: "sections/a.tex",
+    });
+    expect(messages).toEqual([]);
+  });
+});
+
+// ── the planted papers ─────────────────────────────────────────────────────────────────────
+
+describe("on the planted papers (fixtures/paper-sources, the record TeX wrote in tex-truth.json)", () => {
+  // The entries of the databases bibtex opened that carry no doi, url or arXiv id. A `.bib` TeX
+  // wrote is on disk after a build (`written`), holding the lines of its block. An entry only
+  // bibtex reads (v5: behind `%`) is the post-build check's, not this rule's.
+  it.each([
+    ["v1-stale", []],
+    ["v5-percent-entry", []],
+    ["v6-unclosed", ["a3"]],
+    ["v8-jobname", ["jkey"]],
+    ["v16-included-block", ["stale"]],
+    ["v24-quoted-fields", ["q2", "q3", "q4", "q5"]],
+    ["v25-string-differs", ["k1"]],
+  ])("%s: %j", async (name, keys) => {
+    const p = planted(name);
+    const { messages } = await lint({
+      tex: p.files["paper.tex"] ?? "",
+      files: leftByTeX(p),
+      record: p.record,
+    });
+    expect(
+      messages.map((m) => [m.ruleId, /`([^`]+)`/.exec(m.message)?.[1]]),
+    ).toEqual(keys.map((k) => ["bib/reachable-entry", k]));
+  });
+
+  it("v8-jobname: the entry of the paper.bib TeX wrote is at its line in the block that wrote it", async () => {
+    const p = planted("v8-jobname");
+    const { messages } = await lint({
+      tex: p.files["paper.tex"] ?? "",
+      files: leftByTeX(p),
+      record: p.record,
+    });
+    expect(found(messages, "reachable-entry")).toEqual([
+      [3, 1, expect.stringMatching(/^`jkey` has no doi/)],
+    ]);
+  });
+});