paperlint 8.0.0 → 9.0.0

package/src/bib-rules.ts

@@ -0,0 +1,228 @@
+/**
+ * The `bib` rules — about the bibliography TeX read, as the last build recorded it
+ * (`_build/sources.json`, src/recorded-bibliography.ts), on `paper.tex`:
+ *
+ *   bib/reachable-entry   an entry with no doi, url or arXiv id
+ *
+ * They judge the entries of the databases bibtex OPENED, and say nothing for a paper with no record or
+ * one that changed since: `paper/sources-fresh` speaks once for it.
+ *
+ * WHERE A FINDING ABOUT AN ENTRY GOES (`entryReports`). An entry of a `.bib` TeX wrote from a block of
+ * `paper.tex` is reported on its own line there, and a disable directive above it works as everywhere.
+ * Any other entry — a `.bib` the author keeps, which ESLint does not lint, or a block that is in an
+ * included file — is reported at the top of `paper.tex`, with the file, line and column at the front of
+ * the message (the way `reportInPaper` reports text from an included file); there, the same directive
+ * written in the `.bib` on the line above the entry keeps the exception where the entry is
+ * (`directiveAbove`).
+ *
+ * The main file's blocks are read from the editor's buffer, so a finding in `paper.tex` points at the
+ * text being edited; the `.bib` files and the includes are read from disk.
+ */
+import { basename, dirname } from "node:path";
+import { callerPath } from "./caller-path.ts";
+import { MAIN_FILE, type BibEntry } from "./domain/paper-sources.ts";
+import {
+  entriesOfDatabases,
+  entryReports,
+  recordedBibliography,
+  type EntryReport,
+  type RecordedDeps,
+  type RecordedEntry,
+} from "./recorded-bibliography.ts";
+
+export type { EntryReport } from "./recorded-bibliography.ts";
+
+/** `% eslint-disable-next-line <rule>` (a reason after ` -- ` or not) on the line above `at` in `text`. */
+function directiveAbove(text: string, at: number, rule: string): boolean {
+  const lineStart = text.lastIndexOf("\n", at - 1) + 1;
+  const above = text.slice(
+    text.lastIndexOf("\n", lineStart - 2) + 1,
+    Math.max(lineStart - 1, 0),
+  );
+  const m = /^\s*%\s*eslint-disable-next-line\s+(.*?)(?:\s+--\s.*)?$/.exec(
+    above,
+  );
+  return (m?.[1] ?? "")
+    .split(",")
+    .map((r) => r.trim())
+    .includes(rule);
+}
+
+/** Whether a rule should judge this file: the paper's main file only. */
+export const isMain = (filename: string): boolean =>
+  basename(filename) === MAIN_FILE;
+
+// ── the rules ───────────────────────────────────────────────────────────────────────────
+
+interface Loc {
+  readonly line: number;
+  readonly column: number;
+}
+
+/** The slice of ESLint's rule API the `bib` rules use. */
+export interface BibRuleContext {
+  readonly filename: string;
+  /** The `tex/latex` language's source code: `raw` is the file as written. */
+  readonly sourceCode: {
+    readonly raw: string;
+    getLocFromIndex(index: number): Loc;
+  };
+  report(d: {
+    readonly loc: { readonly start: Loc; readonly end: Loc };
+    readonly messageId: string;
+    readonly data?: Readonly<Record<string, string>>;
+  }): void;
+}
+
+export interface BibRuleModule {
+  readonly meta: {
+    readonly type: "problem" | "suggestion";
+    readonly docs: { readonly description: string; readonly url: string };
+    readonly schema: readonly object[];
+    readonly messages: Readonly<Record<string, string>>;
+  };
+  create(context: BibRuleContext): { "root:exit"?: () => void };
+}
+
+type BibRuleName = "reachable-entry";
+
+const docsUrl = (name: BibRuleName): string =>
+  `https://github.com/zernie/paperlint/blob/main/docs/rules/bib/${name}.md`;
+
+/** One finding a `bib` rule makes about an entry. */
+interface EntryFinding {
+  readonly at: EntryReport;
+  readonly messageId: string;
+  readonly key: string;
+}
+
+/**
+ * One finding about an entry, where `entryReports` puts it: on the entry, or at the top of paper.tex
+ * with the `…In` message that names the entry's file, line and column first.
+ */
+function reportEntry(context: BibRuleContext, f: EntryFinding): void {
+  const loc = (i: number) => context.sourceCode.getLocFromIndex(i);
+  context.report({
+    loc: { start: loc(f.at.span.start), end: loc(f.at.span.end) },
+    ...(f.at.kind === "here"
+      ? { messageId: f.messageId, data: { key: f.key } }
+      : {
+          messageId: `${f.messageId}In`,
+          data: { key: f.key, where: f.at.where },
+        }),
+  });
+}
+
+/** What a rule judges: the rule's name, the entries it flags, and the message each flagged entry gets. */
+interface Judge {
+  readonly rule: string;
+  readonly flags: (e: BibEntry) => boolean;
+  readonly messageId: string;
+}
+
+/** A rule that judges the entries of the databases bibtex opened. */
+const entryRule = (
+  meta: BibRuleModule["meta"],
+  judge: Judge,
+  deps: RecordedDeps,
+): BibRuleModule => ({
+  meta,
+  create: (context) => ({
+    "root:exit": () => {
+      findings(context, judge, deps).forEach((f) => {
+        reportEntry(context, f);
+      });
+    },
+  }),
+});
+
+/** An entry reported outside paper.tex whose line above disables `rule` for it (in paper.tex ESLint does that). */
+const excepted = (f: RecordedEntry, at: EntryReport, rule: string): boolean =>
+  at.kind === "elsewhere" &&
+  directiveAbove(f.database.bib.text, f.entry.span.start, rule);
+
+/** The findings for the paper being linted: none for any file but its main one, none without a current record. */
+function findings(
+  context: BibRuleContext,
+  judge: Judge,
+  deps: RecordedDeps,
+): readonly EntryFinding[] {
+  if (!isMain(context.filename)) return [];
+  const main = callerPath(context.filename);
+  const dir = dirname(main);
+  const r = recordedBibliography(dir, deps);
+  if (r.kind === "unrecorded") return [];
+  const flagged = entriesOfDatabases(r.databases).filter((f) =>
+    judge.flags(f.entry),
+  );
+  const at = entryReports(
+    {
+      dir,
+      record: r.record,
+      main: { path: main, text: context.sourceCode.raw },
+    },
+    flagged,
+    deps,
+  );
+  return flagged.flatMap((f, i): readonly EntryFinding[] => {
+    const place = at[i];
+    return place === undefined || excepted(f, place, judge.rule)
+      ? []
+      : [{ at: place, messageId: judge.messageId, key: f.entry.key || "?" }];
+  });
+}
+
+/** An arXiv identifier in a field's text: `arXiv:2401.00001`, `arXiv preprint arXiv:2401.00001`. */
+const ARXIV_ID = /arxiv[:\s]*\d{4}\.\d{4,5}/i;
+/** A link the reader parsed out of `\url{…}` or `\href{…}`, in any field (`howpublished`, `note`). */
+const PARSED_LINK = '<a href="';
+
+const has = (e: BibEntry, field: string): boolean =>
+  (e.fields[field] ?? "").trim() !== "";
+
+/** A doi, a url, an arXiv eprint, or a link or arXiv id in any field: something a reader can follow. */
+const reachable = (e: BibEntry): boolean =>
+  has(e, "doi") ||
+  has(e, "url") ||
+  (has(e, "eprint") &&
+    /arxiv/i.test(e.fields["archiveprefix"] ?? e.fields["eprinttype"] ?? "")) ||
+  Object.values(e.fields).some(
+    (v) => ARXIV_ID.test(v) || v.includes(PARSED_LINK),
+  );
+
+const UNREACHABLE =
+  "`{{key}}` has no doi, url or arXiv id — a reader has nothing to follow. If none exists, keep the exception with `% eslint-disable-next-line bib/reachable-entry -- <why>` above the entry";
+/** `bib/reachable-entry`: every entry TeX reads carries something a reader can follow. */
+const REACHABLE_META: BibRuleModule["meta"] = {
+  type: "suggestion",
+  docs: {
+    description:
+      "a bibliography entry carries a doi, a url or an arXiv id — something a reader can follow",
+    url: docsUrl("reachable-entry"),
+  },
+  schema: [],
+  messages: {
+    unreachable: UNREACHABLE,
+    unreachableIn: `{{where}}: ${UNREACHABLE}`,
+  },
+};
+
+/** The `bib` plugin's rules, reading the paper's record through `deps`. They act on `paper.tex` only. */
+export const bibRules = (
+  deps: RecordedDeps,
+): Readonly<Record<BibRuleName, BibRuleModule>> => ({
+  "reachable-entry": entryRule(
+    REACHABLE_META,
+    {
+      rule: "bib/reachable-entry",
+      flags: (e) => !reachable(e),
+      messageId: "unreachable",
+    },
+    deps,
+  ),
+});
+
+/** The level each is on at for every `paper.tex` in paperlint's own config. */
+export const BIB_RULE_LEVELS = {
+  "bib/reachable-entry": "warn",
+} as const;

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]],
+    ]);
+  });
+});