paperlint 4.1.0 → 4.2.0

package/src/tex-paper.ts

@@ -0,0 +1,152 @@
+/**
+ * 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.
+ *
+ *   tex/missing-input  warn  an `\input`, `\include` or `\subfile` names a file that is not there
+ *
+ * A missing file is a finding, not a silent skip: the rules would otherwise report a clean body for
+ * text they never read, and TeX stops on it too. Warn, not error: a file a build step writes (a
+ * table of generated numbers) is legitimately absent before that step has run.
+ */
+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 {
+  Located,
+  TexRuleContext,
+  TexRuleModule,
+} 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 b = deps.files.readBytes(callerPath(join(dir, rel)));
+      return b === null ? null : new TextDecoder().decode(b);
+    },
+  });
+}
+
+/** 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)}`,
+      });
+  });
+}
+
+const MISSING_META: TexRuleModule["meta"] = {
+  type: "problem",
+  docs: {
+    description:
+      "an \\input, \\include or \\subfile names a file that is not there, so no rule read its text",
+    url: "https://github.com/zernie/paperlint/blob/main/docs/rules/tex/missing-input.md",
+  },
+  schema: [],
+  messages: {
+    missing:
+      "`{{target}}` is not there (tried `{{target}}.tex` and `{{target}}`, from the paper's directory): TeX stops on it, and no rule read what it should hold",
+    missingIn:
+      "`{{target}}`, which {{file}} includes, is not there (tried `{{target}}.tex` and `{{target}}`, from the paper's directory): TeX stops on it, and no rule read what it should hold",
+  },
+};
+
+/** The includes that name no file, each reported where it stands in the main file. */
+export const missingInputRule = (deps: PaperDeps): TexRuleModule => ({
+  meta: MISSING_META,
+  create(context) {
+    return {
+      root() {
+        const sc = context.sourceCode;
+        const paper = readPaper(context.filename, sc.raw ?? sc.text, deps);
+        const loc = (i: number) => sc.getLocFromIndex(i);
+        paper.missing.forEach((m) => {
+          context.report({
+            loc: { start: loc(m.via.start), end: loc(m.via.end) },
+            messageId: m.file === paper.main ? "missing" : "missingIn",
+            data: { target: m.target, file: m.file },
+          });
+        });
+      },
+    };
+  },
+});

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 — and tex/missing-input (not a venue rule) says why.
+    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 [

package/src/tex-venue-rules.ts

@@ -28,6 +28,7 @@ import {
   missingOptions,
   runText,
   spanIn,
+  type ClassCandidate,
   type ClassLine,
   type DocumentClass,
   type Heading,
@@ -44,6 +45,8 @@ import {
   shippedPresets,
   type Preset,
 } from "./presets.ts";
+import type { PaperSource } from "./domain/paper-source.ts";
+import { readPaper, reportInPaper } from "./tex-paper.ts";
 import type { RequiredSection } from "./tex-requirements.ts";
 import type { Finding, VenueRuleDeps } from "./venue-rules.ts";
 
@@ -55,19 +58,27 @@ export interface Located extends Finding {
 /** The slice of ESLint's rule context these rules use. `raw` exists on the `.tex` language's. */
 export interface TexRuleContext {
   readonly filename: string;
+  /** The rule's options from the config, as ESLint validated them against its schema. */
+  readonly options?: readonly unknown[];
   readonly sourceCode: {
     readonly text: string;
     readonly raw?: string;
     getLocFromIndex(index: number): Readonly<{ line: number; column: number }>;
   };
-  report(d: {
-    readonly loc: {
-      readonly start: { line: number; column: number };
-      readonly end: { line: number; column: number };
-    };
-    readonly messageId: string;
-    readonly data?: Readonly<Record<string, string | number>>;
-  }): void;
+  report(
+    d: {
+      readonly loc: {
+        readonly start: { line: number; column: number };
+        readonly end: { line: number; column: number };
+      };
+    } & (
+      | {
+          readonly messageId: string;
+          readonly data?: Readonly<Record<string, string | number>>;
+        }
+      | { readonly message: string }
+    ),
+  ): void;
 }
 
 export interface TexRuleModule {
@@ -110,6 +121,30 @@ function judgeClass(
   }));
 }
 
+/** A candidate as the message names it: its line, or an empty `\documentclass{}`. */
+const candidateLine = (c: ClassCandidate): string =>
+  c.kind === "class" ? documentClassLine(c) : "\\documentclass{}";
+
+/**
+ * Several class lines behind a TeX switch: satisfied when any candidate is the template's class
+ * with its options; otherwise one finding, at the first candidate, naming every one.
+ */
+function judgeCandidates(
+  candidates: readonly [ClassCandidate, ...ClassCandidate[]],
+  want: DocumentClass,
+  data: TemplateData,
+): readonly Located[] {
+  const matches = candidates.some(
+    (c) => c.kind === "class" && judgeClass(c, want, data).length === 0,
+  );
+  if (matches) return [];
+  const named = candidates.map((c) => `\`${candidateLine(c)}\``).join(", ");
+  const found = { ...data, count: candidates.length, candidates: named };
+  return [
+    { messageId: "noCandidate", data: found, at: spanOf(candidates[0].place) },
+  ];
+}
+
 /** The paper's class line against a template that was read: present, naming a class, that class. */
 function judgeClassLine(
   line: ClassLine,
@@ -123,6 +158,8 @@ function judgeClassLine(
       return [{ messageId: "emptyClass", data, at: spanOf(line.place) }];
     case "class":
       return judgeClass(line, want, data);
+    case "ambiguous":
+      return judgeCandidates(line.candidates, want, data);
   }
 }
 
@@ -252,7 +289,9 @@ export function judgeLeftover(
 }
 
 /** Where a rule's page lives: `docs/rules/tex/<name>.md` on the default branch. */
-export const ruleDocsUrl = (name: TexVenueRuleName): string =>
+export const ruleDocsUrl = (
+  name: TexVenueRuleName | "claim-provenance" | "register",
+): string =>
   `https://github.com/zernie/paperlint/blob/main/docs/rules/tex/${name}.md`;
 
 /** What a judge reads: the paper's source through the reader, its preset, the other venues. */
@@ -295,6 +334,8 @@ const RULES: Readonly<
           "the class is `{{got}}`, and {{venue}} requires `{{template}}` — the page size, fonts and layout the venue checks come from the class",
         missingOption:
           "the class option `{{option}}` is missing: {{venue}} requires `{{template}}`",
+        noCandidate:
+          "none of the {{count}} \\documentclass lines is `{{template}}`, which {{venue}} requires: {{candidates}}. The source picks one behind a TeX switch, which is not evaluated; make one of them the venue's",
       },
     },
   },
@@ -368,35 +409,25 @@ export interface TexVenueRuleDeps extends VenueRuleDeps {
 }
 
 /**
- * What a judge reads for the paper whose `paper.tex` is `filename`, or null when the paper has no
- * resolved preset (`pdf/measured` and `pdf/profile` already say so).
+ * What a judge reads for the paper whose `paper.tex` is `filename` — the paper with its includes
+ * spliced (`readPaper`) — or null when the paper has no resolved preset (`pdf/measured` and
+ * `pdf/profile` already say so).
  */
 function readingOf(
   filename: string,
   src: string,
   deps: TexVenueRuleDeps,
-): Reading | null {
+): { readonly reading: Reading; readonly paper: PaperSource } | null {
   const dir = dirname(filename);
   const p = paperPreset(dir, deps);
   if (p.kind !== "resolved") return null;
   const preset = p.preset;
   const others = () => otherVenues(preset, join(dir, CONFIG_FILE), deps);
-  return { src, latex: deps.latex, preset, others };
-}
-
-/** Each finding reported at its span, or at the top of the file when it has none. */
-function reportAll(
-  context: TexRuleContext,
-  findings: readonly Located[],
-): void {
-  const at = (i: number) => context.sourceCode.getLocFromIndex(i);
-  findings.forEach((f) => {
-    context.report({
-      loc: { start: at(f.at?.start ?? 0), end: at(f.at?.end ?? 0) },
-      messageId: f.messageId,
-      data: f.data,
-    });
-  });
+  const paper = readPaper(filename, src, deps);
+  return {
+    reading: { src: paper.text, latex: deps.latex, preset, others },
+    paper,
+  };
 }
 
 function rule(name: TexVenueRuleName, deps: TexVenueRuleDeps): TexRuleModule {
@@ -409,8 +440,9 @@ function rule(name: TexVenueRuleName, deps: TexVenueRuleDeps): TexRuleModule {
       return {
         root() {
           const sc = context.sourceCode;
-          const reading = readingOf(context.filename, sc.raw ?? sc.text, deps);
-          if (reading !== null) reportAll(context, judge(reading));
+          const r = readingOf(context.filename, sc.raw ?? sc.text, deps);
+          if (r !== null)
+            reportInPaper(context, meta.messages, r.paper, judge(r.reading));
         },
       };
     },

package/skills/harden-paper/fixtures/uncited-assertions-sample.md

@@ -1,43 +0,0 @@
-# Uncited-assertion fixture (markdown path)
-
-Documents the `.md` behaviour of the uncited-assertion checker. Keep in the repo (it IS the contract).
-<!-- Since 2026-08-27 the checker is the ESLint rule `paper/uncited-assertion`
-(`eslint-rules/paper-claims.mjs`); this file is its test — see `eslint-rules/paper-claims.harness.mjs`. -->
-
-Transformers outperform RNNs by 12%.
-<!-- MUST FLAG: uncited empirical claim about prior work -->
-
-Transformers outperform RNNs by 12% [@vaswani2017].
-<!-- MUST NOT FLAG: pandoc [@key] citation attached -->
-
-Prior work reports a large improvement over baselines.[^1]
-<!-- MUST NOT FLAG: markdown footnote marker counts as a citation -->
-
-The majority of detectors fail on adversarial inputs, per a recent survey ([link](https://example.org/survey)).
-<!-- MUST NOT FLAG: markdown link/URL counts as a citation -->
-
-Most prior detectors silently miss adversarial inputs.
-<!-- MUST FLAG: bare fuzzy quantifier, no citation -->
-
-We observe a 6% reduction in false positives.
-<!-- MUST NOT FLAG: paper's own result (we-guard) -->
-
-Transformers outperform RNNs by 12% [12].
-<!-- MUST NOT FLAG (S6): numeric citation [12] counts as a cite -->
-
-Prior detectors reduce error by 20% [3, 4].
-<!-- MUST NOT FLAG (S6): citation list [3, 4] counts -->
-
-US-based detectors reject 40% of benign inputs.
-<!-- MUST FLAG (S5): bare country "US" is not the paper's own result -->
-
-Our reading of the literature shows transformers outperform every prior baseline.
-<!-- MUST FLAG (S5): claim about OTHERS, "our reading" is not an own result -->
-
-Our method reduces false positives by 6% over the strongest baseline.
-<!-- MUST NOT FLAG (S5): genuine own result, "our method" is the subject -->
-
-2. Prior detectors silently miss most adversarial inputs.
-<!-- MUST FLAG (S10): ordered-list marker "2." must not be a false boundary / stray number; the claim itself still flags -->
-
-[^1]: Some prior study, 2021.

package/skills/harden-paper/fixtures/uncited-assertions-sample.tex

@@ -1,77 +0,0 @@
-% fixtures/uncited-assertions-sample.tex
-% Contract fixture for the uncited-assertion checker — documents exactly what MUST and MUST NOT flag.
-% Since 2026-08-27 that checker is the ESLint rule `paper/uncited-assertion` (eslint-rules/paper-claims.mjs);
-% this file is its test, run by eslint-rules/paper-claims.harness.mjs.
-% Each numbered case is annotated with the expected verdict. Keep in the repo (it IS the contract).
-\documentclass{article}
-\begin{document}
-
-% (1) MUST FLAG — uncited empirical claim about prior work (percentage + verb, no cite, no "we").
-Transformers outperform RNNs by 12\%.
-
-% (2) MUST NOT FLAG — same claim, now carrying a citation.
-Transformers outperform RNNs by 12\% \cite{vaswani2017}.
-
-% (3) MUST NOT FLAG — float pointer; the verb refers to a Table, not to prior work.
-Table 2 shows the aggregated results across all runs.
-
-% (4) MUST NOT FLAG — the only number is a year (year guard).
-In 2026, the field continued to attract new benchmarks.
-
-% (5) MUST NOT FLAG — the paper's OWN reported result (we/our guard); numbers allowed uncited.
-We find a 6\% reduction in false positives (p<0.05) over the baseline.
-
-% (6) MUST NOT FLAG — a definition sentence, even though it contains a number.
-A transformer block is defined as a stack of 6 attention sub-layers.
-
-% (7) MUST NOT FLAG — version-number guard (v2.1) and a math-mode number ($n = 512$) both skipped;
-%     no "we", so this isolates the version + math guards (no empirical signal survives).
-The baseline model ships as release v2.1 with a hidden size of $n = 512$.
-
-% (8) MUST FLAG — bare fuzzy quantifier making a claim about prior work, no cite.
-Most prior detectors silently miss adversarial inputs.
-
-% ── regression cases for the adversarial-review fixes (S5–S10) ──────────────────
-
-% (S6) MUST NOT FLAG — numeric-style citation [12] is a citation (dominant CS style).
-Transformers outperform RNNs by 12\% [12].
-
-% (S6b) MUST NOT FLAG — citation range/list [3, 4] and [1]--[3] both count.
-Prior detectors reduce error by 20\% [3, 4].
-
-% (S7) MUST NOT FLAG — biblatex \footcite is a citation macro.
-Prior work improves accuracy by 15\% \footcite{smith2020}.
-
-% (S7b) MUST NOT FLAG — \citeauthor / \parencite are citation macros too.
-\citeauthor{jones2019} shows a 9\% reduction over the baseline \parencite{jones2019}.
-
-% (S8) MUST NOT FLAG — "cf." must NOT sever the trailing \cite into its own segment.
-RNN baselines underperform on long sequences, cf. \cite{vaswani2017}.
-
-% (S8b) MUST NOT FLAG — "e.g." before a capital must not break the sentence off its cite.
-Several detectors miss adversarial inputs, e.g. Gradient attacks \cite{goodfellow2015}.
-
-% (S9) MUST NOT FLAG — float pointer via \ref-macro (no literal digit); verb refers to a Table.
-Table~\ref{tab:results} shows the aggregated numbers across all runs.
-
-% (S9b) MUST NOT FLAG — \autoref / \Cref float pointers, verb-only.
-\Cref{fig:overview} demonstrates the pipeline end to end.
-
-% (S10) MUST NOT FLAG — tabular body: numeric rows are data, not a prose claim.
-The results appear below.
-\begin{tabular}{lll}
-Model & Acc & F1 \\
-BERT  & 0.91 & 0.89 \\
-GPT   & 0.94 & 0.93 \\
-\end{tabular}
-
-% (S5) MUST FLAG — bare country "US" must NOT be read as the paper's own result ("us").
-US-based detectors reject 40\% of benign inputs.
-
-% (S5b) MUST FLAG — "Our reading of the literature" is a claim about OTHERS, not an own result.
-Our reading of the literature shows transformers outperform every prior baseline.
-
-% (S5c) MUST NOT FLAG — genuine own result: "our method" is the subject.
-Our method reduces false positives by 6\% over the strongest baseline.
-
-\end{document}