paperlint 2.1.0 → 3.1.0

package/src/reference-rules.ts

@@ -0,0 +1,229 @@
+/**
+ * The reference rules — `paper/author-list`, `paper/cite-exists`, `paper/refs-checked`,
+ * `paper/refs-fresh` — judge `_build/references.json` (`references.ts`), offline. `paperlint build`
+ * does the online work; lint never touches the network.
+ *
+ *   entry whose authors are the preprint's   paper/author-list (error), on the entry
+ *   entry whose identifier provably fails    paper/cite-exists (error), on the entry
+ *   no record, or recorded "not checked"     paper/refs-checked (warn) — like pdf/measured
+ *   bibliography edited after the build      paper/refs-fresh (error) — like pdf/fresh
+ *
+ * While the record is stale, the per-entry rules are silent: they would judge a bibliography
+ * that no longer exists, and refs-fresh already says so once. A paper with no bibliography gets
+ * nothing.
+ *
+ * `paper/author-list` used to live on PIPELINE-STATUS.md and ask whether the scorecard mentioned
+ * a run. It lives here now because its subject is the bibliography, and the record of the run is
+ * the run's own output.
+ */
+import { basename, dirname } from "node:path";
+import type { Files } from "./ports/files.ts";
+import {
+  bibHash,
+  bibliographyOf,
+  readReferences,
+  REFERENCES_FILE,
+  type Bibliography,
+} from "./references.ts";
+
+interface Loc {
+  readonly line: number;
+  readonly column: number;
+}
+interface RuleContext {
+  readonly filename: string;
+  readonly cwd: string;
+  readonly sourceCode: {
+    getLocFromIndex(i: number): Loc;
+  };
+  report(d: {
+    loc: { start: Loc; end: Loc };
+    messageId: string;
+    data?: Record<string, string>;
+  }): void;
+}
+export interface ReferenceRuleModule {
+  readonly meta: {
+    readonly type: "problem" | "suggestion";
+    readonly docs: { readonly description: string };
+    readonly schema: readonly object[];
+    readonly messages: Readonly<Record<string, string>>;
+  };
+  create(context: RuleContext): { "root:exit"?: () => void };
+}
+
+type Name = "author-list" | "cite-exists" | "refs-checked" | "refs-fresh";
+
+/** What one lint run knows about a paper's references. */
+type Assessment =
+  | { readonly kind: "no-bibliography" }
+  | { readonly kind: "unrecorded" }
+  | { readonly kind: "not-checked"; readonly why: string }
+  | { readonly kind: "stale" }
+  | {
+      readonly kind: "ready";
+      readonly bib: Bibliography;
+      readonly failing: readonly {
+        readonly key: string;
+        readonly rule: "author-list" | "cite-exists";
+        readonly why: string;
+      }[];
+    };
+
+function assess(files: Files, paperDir: string): Assessment {
+  const bib = bibliographyOf(files, paperDir);
+  if (bib === null) return { kind: "no-bibliography" };
+  const doc = readReferences(files, paperDir);
+  if (doc === null) return { kind: "unrecorded" };
+  if (doc.bib.sha256 !== bibHash(bib)) return { kind: "stale" };
+  if (doc.status === "not-checked")
+    return { kind: "not-checked", why: doc.why ?? "no reason recorded" };
+  const failing = doc.entries.flatMap((e) => [
+    ...(e.authors === "mismatch"
+      ? [{ key: e.key, rule: "author-list" as const, why: e.why ?? "" }]
+      : []),
+    ...(e.exists === "false"
+      ? [{ key: e.key, rule: "cite-exists" as const, why: e.why ?? "" }]
+      : []),
+  ]);
+  return { kind: "ready", bib, failing };
+}
+
+/** Where entry `key` starts in the source file: its `@type{key,` line, or the file's start. */
+function entryOffset(bib: Bibliography, key: string): number {
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const m = new RegExp(`^@\\w+\\s*\\{\\s*${escaped}\\s*,`, "m").exec(bib.text);
+  return m ? bib.offset + m.index : 0;
+}
+
+const BUILD = "`npx paperlint build`";
+
+const META: Readonly<Record<Name, ReferenceRuleModule["meta"]>> = {
+  "author-list": {
+    type: "problem",
+    docs: {
+      description:
+        "each entry's authors are those of the version it cites, not the preprint's (recorded by paperlint build)",
+    },
+    schema: [],
+    messages: {
+      mismatch:
+        "`{{key}}`: the authors are not those of the version cited — {{why}}. The citation resolves and the id resolves, and the list is the PREPRINT's under a published venue",
+    },
+  },
+  "cite-exists": {
+    type: "problem",
+    docs: {
+      description:
+        "each entry's identifier resolves to the work cited (recorded by paperlint build)",
+    },
+    schema: [],
+    messages: {
+      missing: "`{{key}}` does not resolve to the work cited — {{why}}",
+    },
+  },
+  "refs-checked": {
+    type: "suggestion",
+    docs: {
+      description:
+        "the build checked the references online (existence, title, authors); a warning when it could not",
+    },
+    schema: [],
+    messages: {
+      unrecorded: `the references have not been checked — ${BUILD} checks them online and records the result in _build/${REFERENCES_FILE}`,
+      notChecked: `the last build could not check the references ({{why}}) — run ${BUILD} with network`,
+    },
+  },
+  "refs-fresh": {
+    type: "problem",
+    docs: {
+      description:
+        "the recorded reference verdicts are about the bibliography on disk, not an earlier one",
+    },
+    schema: [],
+    messages: {
+      stale: `the references changed since the last build checked them — run ${BUILD}`,
+    },
+  },
+};
+
+type Report = { at: number; messageId: string; data?: Record<string, string> };
+
+const JUDGES: Readonly<Record<Name, (a: Assessment) => Report[]>> = {
+  "author-list": (a) =>
+    a.kind === "ready"
+      ? a.failing
+          .filter((f) => f.rule === "author-list")
+          .map((f) => ({
+            at: entryOffset(a.bib, f.key),
+            messageId: "mismatch",
+            data: { key: f.key, why: f.why },
+          }))
+      : [],
+  "cite-exists": (a) =>
+    a.kind === "ready"
+      ? a.failing
+          .filter((f) => f.rule === "cite-exists")
+          .map((f) => ({
+            at: entryOffset(a.bib, f.key),
+            messageId: "missing",
+            data: { key: f.key, why: f.why },
+          }))
+      : [],
+  "refs-checked": (a) =>
+    a.kind === "unrecorded"
+      ? [{ at: 0, messageId: "unrecorded" }]
+      : a.kind === "not-checked"
+        ? [{ at: 0, messageId: "notChecked", data: { why: a.why } }]
+        : [],
+  "refs-fresh": (a) =>
+    a.kind === "stale" ? [{ at: 0, messageId: "stale" }] : [],
+};
+
+/** The four rules, reading through `files`. They act on `paper.tex` only. */
+export function referenceRules({
+  files,
+}: {
+  files: Files;
+}): Record<Name, ReferenceRuleModule> {
+  const make = (name: Name): ReferenceRuleModule => ({
+    meta: META[name],
+    create: (context) =>
+      basename(context.filename) !== "paper.tex"
+        ? {}
+        : {
+            "root:exit": () => {
+              const paperDir = dirname(context.filename);
+              const a = assess(files, paperDir);
+              // An external refs.bib: the entry is not in this file, so the finding sits at its
+              // start and names the key.
+              const external =
+                a.kind === "ready" && a.bib.source !== "paper.tex";
+              for (const r of JUDGES[name](a)) {
+                const loc = context.sourceCode.getLocFromIndex(
+                  external ? 0 : r.at,
+                );
+                context.report({
+                  loc: { start: loc, end: loc },
+                  messageId: r.messageId,
+                  ...(r.data ? { data: r.data } : {}),
+                });
+              }
+            },
+          },
+  });
+  return {
+    "author-list": make("author-list"),
+    "cite-exists": make("cite-exists"),
+    "refs-checked": make("refs-checked"),
+    "refs-fresh": make("refs-fresh"),
+  };
+}
+
+/** The level each is on at for every `paper.tex` in paperlint's own config. */
+export const REFERENCE_RULE_LEVELS = {
+  "paper/author-list": "error",
+  "paper/cite-exists": "error",
+  "paper/refs-checked": "warn",
+  "paper/refs-fresh": "error",
+} as const;

package/src/references.test.ts

@@ -0,0 +1,209 @@
+/**
+ * The references a build checked, end to end without a network: the `references` build step
+ * records what a (fake) checker answers, and the offline rules judge that record.
+ *
+ *   a pass is recorded, with the hash of the bibliography checked
+ *   one mismatched entry → paper/author-list on THAT entry's line
+ *   the bibliography edited after the build → paper/refs-fresh, and the per-entry rules go quiet
+ *   offline → the step still succeeds (the build is not failed) and paper/refs-checked warns
+ */
+import { describe, expect, it } from "vitest";
+import { ESLint } from "eslint";
+import { join } from "node:path";
+import { memoryFiles } from "./adapters/memory/index.ts";
+import type { AbsolutePath } from "./domain/paths.ts";
+import type {
+  CheckReferences,
+  EntryVerdict,
+} from "./ports/check-references.ts";
+import { referencesStep } from "./build.ts";
+import {
+  bibHash,
+  bibliographyOf,
+  readReferences,
+  referencesPath,
+} from "./references.ts";
+import { referenceRules, REFERENCE_RULE_LEVELS } from "./reference-rules.ts";
+// @ts-expect-error — an ESLint language in .mjs, it has no types
+import { texLanguage } from "../eslint-rules/latex-language.mjs";
+
+const PAPER = "/work/papers/p";
+const TEX = (entries: string) =>
+  [
+    "\\documentclass{acmart}",
+    "\\begin{filecontents*}{refs.bib}",
+    entries,
+    "\\end{filecontents*}",
+    "\\begin{document}",
+    "x",
+    "\\end{document}",
+    "",
+  ].join("\n");
+const ENTRIES =
+  "@inproceedings{schick2023,\n  title = {Toolformer},\n  author = {Schick, Timo},\n  booktitle = {NeurIPS}\n}\n@misc{other,\n  title = {Other},\n  url = {https://x.org}\n}";
+
+const verdict = (
+  key: string,
+  authors: EntryVerdict["authors"] = "match",
+  exists: EntryVerdict["exists"] = "true",
+): EntryVerdict => ({
+  key,
+  exists,
+  authors,
+  ...(authors === "mismatch" ? { why: "missing hambro" } : {}),
+});
+
+const checker =
+  (entries: readonly EntryVerdict[]): CheckReferences =>
+  async () => ({ kind: "checked", entries });
+const offline: CheckReferences = async () => ({
+  kind: "not-checked",
+  why: "the citation services cannot be reached (fetch failed)",
+});
+
+/** Run the build step on a paper held in memory; returns the files and the step's outcome. */
+async function build(tex: string, check: CheckReferences) {
+  const files = memoryFiles({ [`${PAPER}/paper.tex`]: tex });
+  const out = await referencesStep.run({
+    paperDir: PAPER,
+    env: {},
+    run: (() => ({})) as never,
+    readPdf: (() => null) as never,
+    measure: (() => null) as never,
+    files,
+    checkReferences: check,
+  });
+  return { files, out };
+}
+
+/**
+ * The rules as an ESLint plugin. Their context type is the narrow one they read (a custom
+ * language's SourceCode), which ESLint's JS-centred plugin type does not describe.
+ */
+const asPlugin = (rules: object): ESLint.Plugin => ({ rules }) as ESLint.Plugin;
+
+/** Lint `tex` as the paper's paper.tex against what `files` recorded. */
+async function lint(files: ReturnType<typeof memoryFiles>, tex: string) {
+  files.writeAtomic(
+    `${PAPER}/paper.tex` as AbsolutePath,
+    new TextEncoder().encode(tex),
+  );
+  const eslint = new ESLint({
+    cwd: "/work",
+    overrideConfigFile: true,
+    overrideConfig: [
+      {
+        files: ["**/paper.tex"],
+        plugins: {
+          tex: { languages: { latex: texLanguage } },
+          paper: asPlugin(referenceRules({ files })),
+        },
+        language: "tex/latex",
+        rules: REFERENCE_RULE_LEVELS,
+      },
+    ],
+  });
+  const [res] = await eslint.lintText(tex, {
+    filePath: join(PAPER, "paper.tex"),
+  });
+  return res!.messages;
+}
+
+describe("the references build step", () => {
+  it("records a pass, with the hash of the bibliography it checked", async () => {
+    const tex = TEX(ENTRIES);
+    const { files, out } = await build(
+      tex,
+      checker([verdict("schick2023"), verdict("other")]),
+    );
+    expect(out.ok).toBe(true);
+    const doc = readReferences(files, PAPER);
+    expect(doc?.status).toBe("checked");
+    expect(doc?.bib.sha256).toBe(bibHash(bibliographyOf(files, PAPER)!));
+    expect(await lint(files, tex)).toEqual([]);
+  });
+
+  it("🔴 offline: the step succeeds — the build is not failed — and lint warns once", async () => {
+    const tex = TEX(ENTRIES);
+    const { files, out } = await build(tex, offline);
+    expect(out.ok).toBe(true);
+    expect(readReferences(files, PAPER)?.status).toBe("not-checked");
+    const msgs = await lint(files, tex);
+    expect(msgs.map((m) => [m.ruleId, m.severity])).toEqual([
+      ["paper/refs-checked", 1],
+    ]);
+    expect(msgs[0]!.message).toMatch(/cannot be reached/);
+  });
+
+  it("a checker that throws is recorded as not checked, not as a failed build", async () => {
+    const { files, out } = await build(TEX(ENTRIES), async () => {
+      throw new Error("DBLP exploded");
+    });
+    expect(out.ok).toBe(true);
+    expect(readReferences(files, PAPER)?.why).toMatch(/DBLP exploded/);
+  });
+});
+
+describe("the reference rules", () => {
+  it("one mismatched entry → paper/author-list on that entry's own line", async () => {
+    const tex = TEX(ENTRIES);
+    const { files } = await build(
+      tex,
+      checker([verdict("schick2023", "mismatch"), verdict("other")]),
+    );
+    const msgs = await lint(files, tex);
+    expect(msgs.map((m) => m.ruleId)).toEqual(["paper/author-list"]);
+    expect(msgs[0]!.line).toBe(3);
+    expect(msgs[0]!.message).toMatch(/`schick2023`.*missing hambro/);
+  });
+
+  it("an identifier that provably fails → paper/cite-exists on that entry", async () => {
+    const tex = TEX(ENTRIES);
+    const { files } = await build(
+      tex,
+      checker([verdict("schick2023"), verdict("other", "skipped", "false")]),
+    );
+    const msgs = await lint(files, tex);
+    expect(msgs.map((m) => [m.ruleId, m.line])).toEqual([
+      ["paper/cite-exists", 8],
+    ]);
+  });
+
+  it("🔴 the bibliography edited after the build → refs-fresh, and the stale verdicts are not judged", async () => {
+    const { files } = await build(
+      TEX(ENTRIES),
+      checker([verdict("schick2023", "mismatch"), verdict("other")]),
+    );
+    const edited = TEX(
+      ENTRIES.replace("Schick, Timo", "Schick, Timo and Hambro, Eric"),
+    );
+    const msgs = await lint(files, edited);
+    expect(msgs.map((m) => [m.ruleId, m.severity])).toEqual([
+      ["paper/refs-fresh", 2],
+    ]);
+  });
+
+  it("the same bibliography, unchanged → silent", async () => {
+    const tex = TEX(ENTRIES);
+    const { files } = await build(tex, checker([verdict("schick2023")]));
+    expect(await lint(files, tex)).toEqual([]);
+  });
+
+  it("never built → one warning naming the command", async () => {
+    const files = memoryFiles({});
+    const msgs = await lint(files, TEX(ENTRIES));
+    expect(msgs.map((m) => m.ruleId)).toEqual(["paper/refs-checked"]);
+    expect(msgs[0]!.message).toMatch(/npx paperlint build/);
+  });
+
+  it("a paper with no bibliography gets nothing", async () => {
+    const files = memoryFiles({});
+    expect(
+      await lint(
+        files,
+        "\\documentclass{article}\n\\begin{document}x\\end{document}\n",
+      ),
+    ).toEqual([]);
+    expect(referencesPath(PAPER)).toBe(`${PAPER}/_build/references.json`);
+  });
+});

package/src/references.ts

@@ -0,0 +1,138 @@
+/**
+ * THE REFERENCES A BUILD CHECKED — `<paper>/_build/references.json`, written by `paperlint build`
+ * and read, offline, by the lint rules in `reference-rules.ts`.
+ *
+ * The package ships two online checks: `verify-cites` (the cited work exists and its title
+ * matches) and `bib-authors` (the authors are those of the version cited, not the preprint's).
+ * Until 3.0.0 lint could only ask whether someone had run them — by finding the word
+ * "bib-authors" in a scorecard table, or a command the project configured. Now the build runs
+ * them and records the result as data, beside the facts it already writes about the PDF:
+ *
+ *   { "schema": 1,
+ *     "bib": { "source": "paper.tex", "sha256": "…" },       the bibliography that was checked
+ *     "status": "checked" | "not-checked", "why": "…",       not-checked: nothing could be asked
+ *     "entries": [ { "key", "exists", "authors", "why" } ] }
+ *
+ * A sibling file, not a new field of `paper.facts.json`: those facts are about ONE PDF and are
+ * stale when it changes (`pdf_sha256`); these are about the bibliography and are stale when IT
+ * changes (`bib.sha256`). One staleness key per file, the way `pdf/fresh` already works.
+ *
+ * 🔴 THE STEP NEVER FAILS THE BUILD. A build without network still builds the PDF; the reference
+ * step records `not-checked` and the lint rule says so, as a warning. Recording "not checked" as
+ * a pass would be the counter that counts what it never looked at.
+ */
+import { join } from "node:path";
+import type { AbsolutePath } from "./domain/paths.ts";
+import { sha256Hex } from "./domain/sha256.ts";
+import type { Files } from "./ports/files.ts";
+import type {
+  CheckReferences,
+  EntryVerdict,
+  ReferencesCheck,
+} from "./ports/check-references.ts";
+// @ts-expect-error — an ESLint rule module in .mjs, it has no types
+import { bibRange } from "../eslint-rules/paper-typography.mjs";
+
+export const REFERENCES_SCHEMA = 1;
+export const REFERENCES_FILE = "references.json";
+
+/** Where a paper's reference verdicts live — beside `paper.facts.json`. */
+export const referencesPath = (paperDir: string): string =>
+  join(paperDir, "_build", REFERENCES_FILE);
+
+const at = (p: string): AbsolutePath => p as AbsolutePath;
+const text = (files: Files, p: string): string | null => {
+  const b = files.readBytes(at(p));
+  return b === null ? null : new TextDecoder().decode(b);
+};
+
+/** The bibliography a paper carries: inside `paper.tex` (`filecontents`), else `refs.bib`. */
+export interface Bibliography {
+  readonly source: "paper.tex" | "refs.bib";
+  readonly text: string;
+  /** Where `text` starts in the source file — so a finding can point at an entry. */
+  readonly offset: number;
+}
+
+export function bibliographyOf(
+  files: Files,
+  paperDir: string,
+): Bibliography | null {
+  const tex = text(files, join(paperDir, "paper.tex"));
+  const inline = tex === null ? null : bibRange(tex);
+  if (inline)
+    return { source: "paper.tex", text: inline.body, offset: inline.bodyStart };
+  const bib = text(files, join(paperDir, "refs.bib"));
+  return bib === null ? null : { source: "refs.bib", text: bib, offset: 0 };
+}
+
+export const bibHash = (b: Bibliography): string =>
+  sha256Hex(new TextEncoder().encode(b.text));
+
+/** What `_build/references.json` holds. */
+export interface ReferencesDocument {
+  readonly schema: number;
+  readonly bib: { readonly source: string; readonly sha256: string };
+  readonly status: "checked" | "not-checked";
+  readonly why?: string;
+  readonly entries: readonly EntryVerdict[];
+}
+
+export const documentOf = (
+  bib: Bibliography,
+  check: ReferencesCheck,
+): ReferencesDocument => ({
+  schema: REFERENCES_SCHEMA,
+  bib: { source: bib.source, sha256: bibHash(bib) },
+  ...(check.kind === "checked"
+    ? { status: "checked" as const, entries: check.entries }
+    : { status: "not-checked" as const, why: check.why, entries: [] }),
+});
+
+/** The recorded verdicts, or null when there are none or they do not parse. */
+export function readReferences(
+  files: Files,
+  paperDir: string,
+): ReferencesDocument | null {
+  const raw = text(files, referencesPath(paperDir));
+  if (raw === null) return null;
+  try {
+    const d = JSON.parse(raw) as ReferencesDocument;
+    return d?.schema === REFERENCES_SCHEMA && Array.isArray(d.entries)
+      ? d
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The build step's work: check the bibliography and record the verdicts. Returns the one-line
+ * note the build prints. A checker that throws is recorded as `not-checked` — the step reports,
+ * it never refuses.
+ */
+export async function recordReferences(
+  files: Files,
+  paperDir: string,
+  check: CheckReferences,
+): Promise<string> {
+  const bib = bibliographyOf(files, paperDir);
+  if (bib === null) return "no bibliography — nothing to check";
+  let result: ReferencesCheck;
+  try {
+    result = await check(bib.text);
+  } catch (e) {
+    result = { kind: "not-checked", why: (e as Error).message };
+  }
+  const doc = documentOf(bib, result);
+  files.writeAtomic(
+    at(referencesPath(paperDir)),
+    new TextEncoder().encode(`${JSON.stringify(doc, null, 2)}\n`),
+  );
+  if (doc.status === "not-checked")
+    return `references NOT checked — ${doc.why ?? "no reason given"}; lint will say so`;
+  const bad = doc.entries.filter(
+    (e) => e.exists === "false" || e.authors === "mismatch",
+  ).length;
+  return `references: ${String(doc.entries.length)} checked, ${String(bad)} failing → _build/${REFERENCES_FILE}`;
+}

package/src/rules-config.harness.mjs

@@ -1,6 +1,6 @@
 /**
  * `rules-config.ts` — parsing the `rules` key into ESLint config blocks, and deriving which rules
- * paperlint ships. The end-to-end path (a consumer's package.json → `paperlint lint`) is in `cli.harness.mjs`;
+ * paperlint ships. The end-to-end path (a project's paperlint.json → `paperlint lint`) is in `cli.harness.mjs`;
  * this pins the parser's output shape and each refusal.
  */
 import assert from "node:assert/strict";
@@ -46,23 +46,39 @@ check(
     JSON.stringify(r),
   );
 }
+{
+  const r = parse({ "pdf/last-page-balance": "error" });
+  check(
+    "the object form is ONE block with no `files` — narrowed to each rule's own files later",
+    r.ok &&
+      JSON.stringify(r.value) ===
+        JSON.stringify([
+          {
+            basePath: "/consumer",
+            rules: { "pdf/last-page-balance": "error" },
+          },
+        ]),
+    JSON.stringify(r),
+  );
+}
 check(
   "both severity spellings are accepted",
   parse([{ rules: { "paper/typography": 0, "pdf/last-page-balance": "warn" } }])
     .ok,
 );
 const refusals = [
-  [{ a: 1 }, "S.rules must be a list"],
-  [[42], "S.rules[0] must be an object"],
-  [[{ rules: [] }], "S.rules[0].rules must be an object"],
-  [[{ files: [], rules: {} }], "S.rules[0].files must be a non-empty list"],
+  ["pdf/last-page-balance", 'S → "rules" must be { "<rule>": "<severity>" }'],
+  [{ a: 1 }, '"a" is not a rule paperlint ships'],
+  [[42], "S → rules[0] must be an object"],
+  [[{ rules: [] }], "S → rules[0].rules must be an object"],
+  [[{ files: [], rules: {} }], "S → rules[0].files must be a non-empty list"],
   [
     [{ files: ["x"], ignores: [1], rules: {} }],
-    "S.rules[0].ignores must be a non-empty list",
+    "S → rules[0].ignores must be a non-empty list",
   ],
   [
     [{ languageOptions: {}, rules: {} }],
-    'S.rules[0]: unknown key "languageOptions"',
+    'S → rules[0]: unknown key "languageOptions"',
   ],
   [
     [{ rules: { "markdown/no-html": "error" } }],
@@ -70,7 +86,7 @@ const refusals = [
   ],
   [
     [{ rules: { "paper/typography": ["loud"] } }],
-    'S.rules[0].rules["paper/typography"]: ["loud"] is not a severity',
+    'S → rules[0].rules["paper/typography"]: ["loud"] is not a severity',
   ],
 ];
 for (const [raw, says] of refusals) {