paperlint 4.1.0 → 5.0.0

package/src/rule-cases.test.ts

@@ -128,6 +128,9 @@ const AIDC = {
 };
 const IEEE = "\\documentclass[conference,compsoc]{IEEEtran}";
 const STATEMENT = "\\section*{LLM Usage Statement}\nNone.";
+/** Two `\\documentclass` lines behind a switch: `article` for one venue, `second` for this one. */
+const switched = (second: string): string =>
+  `\\def\\venue{2}\n\\if\\venue1\n\\documentclass{article}\n\\fi\n\\if\\venue2\n${second}\n\\fi`;
 const aidc = (body: string, cls = IEEE) =>
   paper(tex(`\\section{Introduction}\n${body}\n${STATEMENT}`, cls), AIDC);
 
@@ -147,6 +150,13 @@ interface RuleCases {
 }
 
 const TEX_FILE = `${P}/paper.tex`;
+
+/** A body of 200 sentences of 14 words: enough words for `tex/register` to judge a rate. */
+const FORMAL = Array.from(
+  { length: 200 },
+  () =>
+    "The rule reads the body of the paper and counts every sentence it holds.",
+).join(" ");
 const STATUS_FILE = `${P}/PIPELINE-STATUS.md`;
 const SHIPPED_STATUS =
   "---\nstages:\n  - stage: submitted\n    date: 2026-07-22\n    pdf: versions/a.pdf\n    bytes: 1\n---\n# PIPELINE-STATUS\n";
@@ -176,25 +186,6 @@ const CASES: Readonly<Record<string, RuleCases>> = {
     },
     silent: paper(tex("x")),
   },
-  "paper/research-question": {
-    reports: {
-      tree: {
-        [STATUS_FILE]: fixture(
-          "paper-research-question/shipped-no-rq/PIPELINE-STATUS.md",
-        ),
-        [TEX_FILE]: fixture("paper-research-question/shipped-no-rq/paper.tex"),
-      },
-      file: TEX_FILE,
-      severity: 1,
-      line: 1,
-    },
-    silent: {
-      [STATUS_FILE]: fixture(
-        "paper-research-question/shipped-with-rq/PIPELINE-STATUS.md",
-      ),
-      [TEX_FILE]: fixture("paper-research-question/shipped-with-rq/paper.tex"),
-    },
-  },
   "paper/section-word": {
     reports: {
       tree: paper(tex("As in §2.")),
@@ -202,7 +193,13 @@ const CASES: Readonly<Record<string, RuleCases>> = {
       severity: 1,
       line: 3,
     },
-    silent: paper(tex("As in Section~2.")),
+    // A cleveref name definition sets a label, it is not prose.
+    silent: paper(
+      tex(
+        "As in Section~2.",
+        "\\documentclass{article}\n\\usepackage{cleveref}\n\\crefname{section}{§}{§§}",
+      ),
+    ),
   },
   "paper/leading-zero": {
     reports: {
@@ -299,14 +296,15 @@ const CASES: Readonly<Record<string, RuleCases>> = {
     },
     silent: paper(fixture("tex-build/frontmatter-clean.tex")),
   },
+  // The class picked behind a TeX switch: two candidates, one of them the venue's or none.
   "tex/template": {
     reports: {
-      tree: aidc("Text.", "\\documentclass[conference]{IEEEtran}"),
+      tree: aidc("Text.", switched("\\documentclass[conference]{IEEEtran}")),
       file: TEX_FILE,
       severity: 2,
-      line: 1,
+      line: 3,
     },
-    silent: aidc("Text."),
+    silent: aidc("Text.", switched(IEEE)),
   },
   "tex/required-section": {
     reports: {
@@ -326,6 +324,28 @@ const CASES: Readonly<Record<string, RuleCases>> = {
     },
     silent: aidc("Text."),
   },
+  "tex/claim-provenance": {
+    reports: {
+      tree: paper(tex("Text.\nAgents ignore 42\\% of the rules.")),
+      file: TEX_FILE,
+      severity: 1,
+      line: 4,
+    },
+    silent: paper(
+      tex(
+        "Text.\nWe measured that agents ignore 42\\% of the rules.\nThey run on Claude 3 and Python 3.12.",
+      ),
+    ),
+  },
+  "tex/register": {
+    reports: {
+      tree: paper(tex(`${FORMAL} But it holds. So it goes. And it ends.`)),
+      file: TEX_FILE,
+      severity: 1,
+      line: 3,
+    },
+    silent: paper(tex(FORMAL)),
+  },
   "bib/reachable-entry": {
     reports: {
       tree: paper(inlineBib("@book{a,\n  title = {A},\n  year = {2026}\n}")),

package/src/rule-docs.test.ts

@@ -26,7 +26,6 @@ const AWAITING_PAGE: ReadonlySet<string> = new Set([
   "paper/leading-zero",
   "paper/refs-checked",
   "paper/refs-fresh",
-  "paper/research-question",
   "paper/section-word",
   "paper/source",
   "paper/stages",

package/src/rules-config.ts

@@ -64,6 +64,7 @@ export interface ConfigBlock {
   readonly languageOptions?: Readonly<Record<string, unknown>>;
   readonly linterOptions?: Readonly<Record<string, unknown>>;
   readonly rules?: Readonly<Record<string, unknown>>;
+  readonly settings?: Readonly<Record<string, unknown>>;
 }
 
 export type Parsed<T> =

package/src/structure.harness.ts

@@ -79,9 +79,7 @@ try {
   check(
     "and the message names the CONSEQUENCE, not a restatement of the condition",
     /are skipped/.test(at("no-scorecard")[0]?.message ?? "") &&
-      /stage, source and research-question checks/.test(
-        at("no-scorecard")[0]?.message ?? "",
-      ),
+      /stage and source checks/.test(at("no-scorecard")[0]?.message ?? ""),
   );
   check(
     "and the consequence names THIS directory by name",

package/src/structure.ts

@@ -122,7 +122,7 @@ export function checkStructure(
  */
 function whyMissingMatters(file: string, dirName: string): string {
   if (file === "PIPELINE-STATUS.md")
-    return `the stage, source and research-question checks are skipped for \`${dirName}\``;
+    return `the stage and source checks are skipped for \`${dirName}\``;
   return `declared as required by your \`structure\` configuration`;
 }
 

package/src/tex-paper.test.ts

@@ -0,0 +1,148 @@
+/**
+ * The reading every parse-tree rule shares (`readPaper`), the files of the paper's body that lint
+ * reads on their own (`bodyFiles`), and where a finding of the assembled text is reported
+ * (`reportInPaper`).
+ */
+import { describe, expect, it } from "vitest";
+import { latexReader } from "./adapters/latex/index.ts";
+import { memoryFiles } from "./adapters/memory/index.ts";
+import { join } from "node:path";
+import { texInputsDir } from "./package-dirs.ts";
+import { bodyFiles, readPaper, reportInPaper } from "./tex-paper.ts";
+
+describe("readPaper — the paper as the rules read it", () => {
+  it("reads includes from the paper's own directory", () => {
+    const p = readPaper("/p/paper.tex", "x\\input{s/a}y", {
+      files: memoryFiles({ "/p/s/a.tex": "AAA" }),
+      latex: latexReader,
+    });
+    expect(p.text).toBe("xAAAy");
+    expect(p.main).toBe("paper.tex");
+  });
+
+  it("an include the paper's directory lacks is found in paperlint's own inputs, as the build finds it", () => {
+    const p = readPaper("/p/paper.tex", "x\\input{guards}y", {
+      files: memoryFiles({ [join(texInputsDir(), "guards.tex")]: "G" }),
+      latex: latexReader,
+    });
+    expect({ text: p.text, missing: p.missing }).toEqual({
+      text: "xGy",
+      missing: [],
+    });
+  });
+
+  it("the paper's directory comes first: its file wins over paperlint's of the same name", () => {
+    const p = readPaper("/p/paper.tex", "\\input{guards}", {
+      files: memoryFiles({
+        "/p/guards.tex": "mine",
+        [join(texInputsDir(), "guards.tex")]: "package",
+      }),
+      latex: latexReader,
+    });
+    expect(p.text).toBe("mine");
+  });
+});
+
+describe("bodyFiles — the files of the body lint reads on their own", () => {
+  const doc = (preamble: string, body: string): string =>
+    `\\documentclass{article}\n${preamble}\n\\begin{document}\n${body}\n\\end{document}\n`;
+  const files = (extra: Record<string, string> = {}) =>
+    memoryFiles({
+      "/p/macros.tex": "\\newcommand{\\x}{y}",
+      "/p/sections/a.tex": "A\n\\input{sections/b}\n",
+      "/p/sections/b.tex": "B",
+      [join(texInputsDir(), "guards.tex")]: "G",
+      ...extra,
+    });
+
+  it("every file an include in the document body brings in, nested ones too, by absolute path", () => {
+    expect(
+      bodyFiles("/p/paper.tex", doc("", "\\input{sections/a}"), {
+        files: files(),
+        latex: latexReader,
+      }),
+    ).toEqual({
+      files: ["/p/sections/a.tex", "/p/sections/b.tex"],
+      missing: [],
+    });
+  });
+
+  it("not a preamble include (macros), and not a file found only in paperlint's inputs", () => {
+    expect(
+      bodyFiles(
+        "/p/paper.tex",
+        doc("\\input{macros}", "\\input{guards}\nText."),
+        { files: files(), latex: latexReader },
+      ),
+    ).toEqual({ files: [], missing: [] });
+  });
+
+  it("an include that resolves nowhere is named, with the file that wrote it", () => {
+    expect(
+      bodyFiles("/p/paper.tex", doc("", "\\input{gone}"), {
+        files: files(),
+        latex: latexReader,
+      }),
+    ).toEqual({ files: [], missing: [{ file: "paper.tex", target: "gone" }] });
+  });
+
+  it("a main file with no document environment: every include is the body", () => {
+    expect(
+      bodyFiles("/p/paper.tex", "\\input{sections/b}", {
+        files: files(),
+        latex: latexReader,
+      }),
+    ).toEqual({ files: ["/p/sections/b.tex"], missing: [] });
+  });
+});
+
+describe("reportInPaper — where a finding of the assembled text is reported", () => {
+  const paper = readPaper("/p/paper.tex", "x\n\\input{a}\ny", {
+    files: memoryFiles({ "/p/a.tex": "one\ntwo" }),
+    latex: latexReader,
+  });
+  const report = (
+    at: { start: number; end: number } | null,
+    messageId = "m",
+  ) => {
+    const out: unknown[] = [];
+    reportInPaper(
+      {
+        filename: "/p/paper.tex",
+        sourceCode: {
+          text: "",
+          getLocFromIndex: (i) => ({ line: i, column: 0 }),
+        },
+        report: (d) =>
+          out.push(
+            "messageId" in d
+              ? { at: d.loc.start.line, id: d.messageId }
+              : { at: d.loc.start.line, message: d.message },
+          ),
+      },
+      { m: "said {{w}}" },
+      paper,
+      [{ messageId, data: { w: "so" }, at }],
+    );
+    return out;
+  };
+
+  it("in the main file: at its own place, by its id", () => {
+    expect(report({ start: 0, end: 1 })).toEqual([{ at: 0, id: "m" }]);
+  });
+
+  it("in an included file: at the include, the file, line and column in front of the filled message", () => {
+    // "x\n" then "one\ntwo": offset 6 is the `t` of `two`, line 2 column 1 of a.tex.
+    expect(report({ start: 6, end: 9 })).toEqual([
+      { at: 2, message: "a.tex:2:1: said so" },
+    ]);
+  });
+
+  it("no place, or a place outside the text: the top of the file; an unknown id is printed as itself", () => {
+    expect(report(null)).toEqual([{ at: 0, id: "m" }]);
+    expect(report({ start: 99, end: 99 })).toEqual([{ at: 0, id: "m" }]);
+    expect(report({ start: 6, end: 9 }, "unknown")).toEqual([
+      { at: 2, message: "a.tex:2:1: unknown" },
+    ]);
+  });
+});

package/src/tex-paper.ts

@@ -0,0 +1,161 @@
+/**
+ * THE PAPER, NOT ITS MAIN FILE — what every rule over the LaTeX parse tree reads, and how it reports.
+ *
+ * `readPaper` gives a rule `paper.tex` with every `\input`, `\include` and `\subfile` spliced in, the
+ * way TeX reads it (`assemblePaper`, src/domain/paper-source.ts). `reportInPaper` puts each finding
+ * back where its text came from: a finding in `paper.tex` at its own place; a finding in an included
+ * file at the include in `paper.tex` that brought it in — the one place ESLint can point to in this
+ * file — with the included file, line and column at the front of the message.
+ *
+ * An include is looked for where the build tells TeX to look (`texSearchPath`): the paper's own
+ * directory, then paperlint's inputs. `bodyFiles` names the files of the paper's BODY the author
+ * wrote — what the rules over ESLint's own LaTeX text read one by one, each at its own path.
+ */
+import { basename, dirname, join } from "node:path";
+import {
+  assemblePaper,
+  originOf,
+  type PaperSource,
+} from "./domain/paper-source.ts";
+import type { Span } from "./domain/tex-document.ts";
+import type { LatexReader } from "./ports/latex.ts";
+import type { Files } from "./ports/files.ts";
+import { callerPath } from "./caller-path.ts";
+import type { AbsolutePath } from "./domain/paths.ts";
+import { texSearchPath } from "./package-dirs.ts";
+import type { Located, TexRuleContext } from "./tex-venue-rules.ts";
+
+/** What reading a paper needs: the disk, and the LaTeX reader. */
+export interface PaperDeps {
+  readonly files: Files;
+  readonly latex: LatexReader;
+}
+
+/** The paper whose main file is `filename` with the text `src`, its includes spliced. */
+export function readPaper(
+  filename: string,
+  src: string,
+  deps: PaperDeps,
+): PaperSource {
+  const dir = dirname(filename);
+  return assemblePaper(basename(filename), src, {
+    includes: deps.latex.includes,
+    documentBody: deps.latex.documentBody,
+    read: (rel) => {
+      const at = located(dir, rel, deps.files);
+      const b = at === null ? null : deps.files.readBytes(at);
+      return b === null ? null : new TextDecoder().decode(b);
+    },
+  });
+}
+
+/** `rel` in the first directory of the paper's TeX search path that holds it, or null. */
+const located = (dir: string, rel: string, files: Files): AbsolutePath | null =>
+  texSearchPath(dir)
+    .map((d) => callerPath(join(d, rel)))
+    .find((p) => files.isFile(p)) ?? null;
+
+/** An include that resolved nowhere: the file that wrote it, and the path as written. */
+export interface Unread {
+  readonly file: string;
+  readonly target: string;
+}
+
+/**
+ * The files of the body of the paper whose main file is `filename`: every file an include inside its
+ * `document` environment brings in, nested ones too, found in the paper's own directory. Not a
+ * preamble include (macros are not the body), and not a file found only in paperlint's inputs (not
+ * the author's text). `missing` is every include, anywhere, that resolved nowhere.
+ */
+export function bodyFiles(
+  filename: string,
+  src: string,
+  deps: PaperDeps,
+): {
+  readonly files: readonly AbsolutePath[];
+  readonly missing: readonly Unread[];
+} {
+  const dir = dirname(filename);
+  const paper = readPaper(filename, src, deps);
+  const body = deps.latex.documentBody(src);
+  const inBody = (via: Span | null): boolean =>
+    via !== null &&
+    (body === null || (via.start >= body.start && via.end <= body.end));
+  const own = (rel: string): AbsolutePath | null => {
+    const at = located(dir, rel, deps.files);
+    return at === callerPath(join(dir, rel)) ? at : null;
+  };
+  return {
+    files: [
+      ...new Set(
+        paper.segments
+          .filter((s) => s.file !== paper.main && inBody(s.via))
+          .map((s) => own(s.file))
+          .filter((f): f is AbsolutePath => f !== null),
+      ),
+    ],
+    missing: paper.missing.map(({ file, target }) => ({ file, target })),
+  };
+}
+
+/** Line and column (1-based) of an offset in a text. */
+function lineColumn(text: string, at: number): string {
+  const line = text.slice(0, at).split("\n").length;
+  const column = at - text.lastIndexOf("\n", at - 1);
+  return `${String(line)}:${String(column)}`;
+}
+
+/** A message template with its data filled in, the way ESLint fills it. */
+const filled = (
+  template: string,
+  data: Readonly<Record<string, string | number>> = {},
+): string =>
+  Object.entries(data).reduce(
+    (m, [k, v]) => m.replaceAll(`{{${k}}}`, String(v)),
+    template,
+  );
+
+/** Where a finding stands in the main file, and — when its text came from another file — which. */
+interface Placed {
+  readonly at: Span | null;
+  readonly from: string | null;
+}
+
+/** A finding's span of the assembled text, as a place in the main file. */
+function placed(paper: PaperSource, at: Span | null): Placed {
+  const origin = at === null ? null : originOf(paper, at);
+  if (origin === null) return { at: null, from: null };
+  if (origin.file === paper.main) return { at: origin.span, from: null };
+  return {
+    at: origin.via,
+    from: `${origin.file}:${lineColumn(origin.source, origin.span.start)}`,
+  };
+}
+
+/**
+ * Each finding reported in the main file: at its own place, or at the include that brought its text
+ * in, named in the message (`sections/results.tex:12:3: …`). Offsets are the assembled text's.
+ */
+export function reportInPaper(
+  context: TexRuleContext,
+  messages: Readonly<Record<string, string>>,
+  paper: PaperSource,
+  findings: readonly Located[],
+): void {
+  const loc = (i: number) => context.sourceCode.getLocFromIndex(i);
+  findings.forEach((f) => {
+    const p = placed(paper, f.at);
+    const where = {
+      start: loc(p.at?.start ?? 0),
+      end: loc(p.at?.end ?? 0),
+    };
+    if (p.from === null)
+      context.report({ loc: where, messageId: f.messageId, data: f.data });
+    else
+      context.report({
+        loc: where,
+        // A message id the rule does not define is printed as itself rather than dropped.
+        message: `${p.from}: ${filled(messages[f.messageId] ?? f.messageId, f.data)}`,
+      });
+  });
+}

package/src/tex-venue-rules.test.ts

@@ -79,11 +79,16 @@ function lint(
       report: (d) =>
         out.push({
           rule: `tex/${name}`,
-          messageId: d.messageId,
-          message: Object.entries(d.data ?? {}).reduce(
-            (m, [k, v]) => m.replaceAll(`{{${k}}}`, String(v)),
-            rule.meta.messages[d.messageId] ?? `(no message ${d.messageId})`,
-          ),
+          // A finding from an included file arrives as a whole message, its file at the front.
+          messageId: "messageId" in d ? d.messageId : "(message)",
+          message:
+            "messageId" in d
+              ? Object.entries(d.data ?? {}).reduce(
+                  (m, [k, v]) => m.replaceAll(`{{${k}}}`, String(v)),
+                  rule.meta.messages[d.messageId] ??
+                    `(no message ${d.messageId})`,
+                )
+              : d.message,
           line: d.loc.start.line,
         }),
     });
@@ -183,6 +188,83 @@ describe("tex/template — the class line's states: missing, empty, commented ou
   });
 });
 
+describe("the venue rules read the whole paper: the files it \\inputs, spliced where they stand", () => {
+  it("🔴 a required section kept in an included file is found, and its order judged in the paper", () => {
+    const tex = paper(
+      "\\documentclass[conference,compsoc]{IEEEtran}",
+      "Text.\n\\input{sections/closing}",
+    );
+    const extra = {
+      [`${PAPER}/sections/closing.tex`]:
+        "\\section*{LLM Usage Statement}\nNone.\n",
+    };
+    expect(lint(tex, AIDC, { extra })).toEqual([]);
+    // Without the file, the section is missing.
+    expect(ids(lint(tex, AIDC))).toEqual(["tex/required-section:missing"]);
+  });
+
+  it("a leftover venue name in an included file is reported at the \\input, naming the file and line", () => {
+    const tex = paper(
+      "\\documentclass[conference,compsoc]{IEEEtran}",
+      "Text.\n\\input{intro}\n\\section*{LLM Usage Statement}\nNone.",
+    );
+    const fs = lint(tex, AIDC, {
+      extra: {
+        [`${PAPER}/intro.tex`]: "One line.\nFirst written for AgenticDev.\n",
+      },
+    });
+    expect(fs.map((f) => [f.line, f.message.split(": ")[0]])).toEqual([
+      [5, "intro.tex:2:19"],
+    ]);
+  });
+});
+
+describe("tex/template — several \\documentclass lines behind a TeX switch", () => {
+  /** One source for two venues, the class picked by `\\if` — as an accepted ACSAC paper does it. */
+  const switched = (a: string, b: string) =>
+    paper(
+      `\\def\\venue{2}\n\\if\\venue1\n${a}\n\\fi\n\\if\\venue2\n${b}\n\\fi`,
+    );
+
+  it("passes when one of the candidates is the preset's class with its options", () => {
+    expect(
+      lint(
+        switched(
+          "\\documentclass[letterpaper,twocolumn]{article}",
+          "\\documentclass[conference,compsoc]{IEEEtran}",
+        ),
+        AIDC,
+      ),
+    ).toEqual([]);
+  });
+
+  it("reports once, at the first candidate, naming every candidate, when none is the preset's", () => {
+    const fs = lint(
+      switched(
+        "\\documentclass{article}",
+        "\\documentclass[conference]{IEEEtran}",
+      ),
+      AIDC,
+    );
+    expect(ids(fs)).toEqual(["tex/template:noCandidate"]);
+    // Line 4: the first candidate, after the comment, `\\def` and `\\if` lines.
+    expect(fs[0]?.line).toBe(4);
+    expect(fs[0]?.message).toBe(
+      "none of the 2 \\documentclass lines is `\\documentclass[conference,compsoc]{IEEEtran}`, which aidc requires: `\\documentclass{article}`, `\\documentclass[conference]{IEEEtran}`. The source picks one behind a TeX switch, which is not evaluated; make one of them the venue's",
+    );
+  });
+
+  it("an empty candidate is named as such", () => {
+    const fs = lint(
+      switched("\\documentclass{}", "\\documentclass{article}"),
+      AIDC,
+    );
+    expect(fs[0]?.message).toMatch(
+      /`\\documentclass\{\}`, `\\documentclass\{article\}`/,
+    );
+  });
+});
+
 describe("tex/template — the shipped ACM and ACL templates", () => {
   it("🔴 acmart without sigconf — the manuscript format — fails every ACM preset", () => {
     for (const settings of [