paperlint 4.2.0 → 6.0.0

package/src/tex-paper.ts

@@ -7,11 +7,9 @@
  * 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.
+ * 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 {
@@ -23,11 +21,9 @@ 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";
+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 {
@@ -46,12 +42,62 @@ export function readPaper(
     includes: deps.latex.includes,
     documentBody: deps.latex.documentBody,
     read: (rel) => {
-      const b = deps.files.readBytes(callerPath(join(dir, 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;
@@ -113,40 +159,3 @@ export function reportInPaper(
       });
   });
 }
-
-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-requirements.ts

@@ -131,6 +131,8 @@ export interface VenueFormat {
   /** The prefix a font name of the body text starts with (`LinLibertine`). */
   readonly fontsText: string | null;
   readonly fontsTitle: string | null;
+  /** How the body is counted: null is banal's count; `references`, the pages before the references. */
+  readonly bodyEndsAt: "references" | null;
   readonly kinds: ReadonlyMap<string, KindLimits>;
 }
 
@@ -145,6 +147,7 @@ export const NO_FORMAT: VenueFormat = {
   refPtMax: null,
   fontsText: null,
   fontsTitle: null,
+  bodyEndsAt: null,
   kinds: new Map(),
 };
 
@@ -168,6 +171,8 @@ export interface PresetFile {
   readonly template: string | null;
   /** Other names the venue goes by in a paper's text; empty when the file names none. */
   readonly aliases: readonly string[];
+  /** Whether the venue reviews double-blind; null when the file does not say. */
+  readonly blind: boolean | null;
   /** Sections the venue requires; null when the file names none (a child's list replaces its parent's). */
   readonly requiredSections: readonly RequiredSection[] | null;
   /** Null when the file declares no `tex` block (allowed only with `extends`). */
@@ -192,6 +197,7 @@ interface FormatJson {
   readonly ref_pt_max?: number;
   readonly fonts_text?: string;
   readonly fonts_title?: string;
+  readonly body_ends_at?: "references";
   readonly kinds?: KindsJson;
 }
 
@@ -201,6 +207,7 @@ interface PresetJson {
   readonly name?: string;
   readonly template?: string;
   readonly aliases?: readonly string[];
+  readonly blind?: boolean;
   readonly required_sections?: readonly {
     readonly title: string;
     readonly position?: "last";
@@ -238,6 +245,7 @@ function formatOf(j: FormatJson = {}): VenueFormat {
     refPtMax: orNull(j.ref_pt_max),
     fontsText: orNull(j.fonts_text),
     fontsTitle: orNull(j.fonts_title),
+    bodyEndsAt: orNull(j.body_ends_at),
     kinds: kindsOf(j.kinds),
   };
 }
@@ -281,6 +289,7 @@ export function parsePreset(
     name: orNull(j.name),
     template: orNull(j.template),
     aliases: j.aliases ?? [],
+    blind: orNull(j.blind),
     requiredSections: sectionsOf(j.required_sections),
     tex: j.tex ? { packages: j.tex.packages, tools: j.tex.tools ?? {} } : null,
     format: formatOf(j.format),

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

@@ -13,6 +13,8 @@ import {
   judgeRequiredSections,
   judgeTemplate,
   otherVenues,
+  FORMAT_RULE_LEVELS,
+  formatRules,
   TEX_VENUE_RULE_LEVELS,
   texVenueRules,
 } from "./tex-venue-rules.ts";
@@ -66,9 +68,15 @@ function lint(
     ...extra,
   });
   const out: Finding[] = [];
-  for (const [name, rule] of Object.entries(
-    texVenueRules({ files, venuesDir: VENUES, latex: latexReader }),
-  )) {
+  const deps = { files, venuesDir: VENUES, latex: latexReader };
+  for (const [id, rule] of [
+    ...Object.entries(texVenueRules(deps)).map(
+      ([n, r]) => [`tex/${n}`, r] as const,
+    ),
+    ...Object.entries(formatRules(deps)).map(
+      ([n, r]) => [`format/${n}`, r] as const,
+    ),
+  ]) {
     const visitor = rule.create({
       filename,
       sourceCode: {
@@ -78,7 +86,7 @@ function lint(
       },
       report: (d) =>
         out.push({
-          rule: `tex/${name}`,
+          rule: id,
           // A finding from an included file arrives as a whole message, its file at the front.
           messageId: "messageId" in d ? d.messageId : "(message)",
           message:
@@ -199,7 +207,7 @@ describe("the venue rules read the whole paper: the files it \\inputs, spliced w
         "\\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.
+    // Without the file, the section is missing.
     expect(ids(lint(tex, AIDC))).toEqual(["tex/required-section:missing"]);
   });
 
@@ -720,7 +728,7 @@ describe("otherVenues", () => {
 });
 
 describe("paperlint's own config", () => {
-  it.each(Object.entries(TEX_VENUE_RULE_LEVELS))(
+  it.each(Object.entries({ ...TEX_VENUE_RULE_LEVELS, ...FORMAT_RULE_LEVELS }))(
     "turns %s on at %s for every paper.tex, and ships it",
     (id, level) => {
       const tex = buildConfig({}, { sentinel: "tex" }).find((b) =>
@@ -738,4 +746,101 @@ describe("paperlint's own config", () => {
       "tex/venue-leftover": "warn",
     });
   });
+
+  it("format/layout-override is an error: the layout it guards is the template's", () => {
+    expect(FORMAT_RULE_LEVELS).toEqual({ "format/layout-override": "error" });
+  });
+});
+
+/** A conforming AIDC paper with `preamble` after its class line, and `body` before its statement. */
+const withPreamble = (preamble: string, body = "Text.") =>
+  paper(
+    `\\documentclass[conference,compsoc]{IEEEtran}\n${preamble}`,
+    `${body}\n\\section*{LLM Usage Statement}\nNone.`,
+  );
+const overrides = (tex: string, settings: object | undefined = AIDC) =>
+  lint(tex, settings).filter((f) => f.rule === "format/layout-override");
+
+describe("format/layout-override reports", () => {
+  it("each command that changes the template's layout, on its own line", () => {
+    const tex = withPreamble(
+      [
+        "\\usepackage[margin=1in]{geometry}",
+        "\\usepackage{amsmath,geometry}",
+        "\\setlength{\\textheight}{9.5in}",
+        "\\addtolength\\textwidth{1in}",
+        "\\setlength{\\columnsep}{0.1in}",
+        "\\linespread{0.95}",
+        "\\renewcommand{\\baselinestretch}{0.9}",
+        "\\geometry{left=1cm}",
+      ].join("\n"),
+      "Text.\n\\newgeometry{top=1cm}\nMore text.",
+    );
+    expect(
+      overrides(tex).map((f) => [f.line, f.message.split("`")[1]]),
+    ).toEqual([
+      [3, "\\usepackage{geometry}"],
+      [4, "\\usepackage{geometry}"],
+      [5, "\\setlength{\\textheight}"],
+      [6, "\\addtolength{\\textwidth}"],
+      [7, "\\setlength{\\columnsep}"],
+      [8, "\\linespread{0.95}"],
+      [9, "\\renewcommand{\\baselinestretch}"],
+      [10, "\\geometry"],
+      [13, "\\newgeometry"],
+    ]);
+    expect(overrides(tex)[0]?.message).toBe(
+      "`\\usepackage{geometry}` changes the page layout aidc's template sets (`\\documentclass[conference,compsoc]{IEEEtran}`) — a desk-reject reason at venues that check the format. Remove it; if the venue allows it, disable this line with a comment saying so",
+    );
+  });
+  it("a definition's body counts: the length it sets is set wherever it is used", () => {
+    const tex = withPreamble(
+      "\\newcommand{\\tall}{\\setlength{\\textheight}{10in}}",
+    );
+    expect(overrides(tex).map((f) => f.line)).toEqual([3]);
+  });
+});
+
+describe("format/layout-override stays silent", () => {
+  it("silent on what leaves the layout alone", () => {
+    const tex = withPreamble(
+      [
+        "\\usepackage{amsmath}",
+        "\\setlength{\\parindent}{0pt}",
+        "\\renewcommand{\\thesection}{\\arabic{section}}",
+        "% \\usepackage{geometry} in a comment",
+        "\\begin{comment}\\linespread{0.9}\\end{comment}",
+        // A length command with no arguments at all names no length.
+        "{\\setlength}",
+      ].join("\n"),
+      "A \\vspace{2mm} B \\vskip 3pt C \\vskip\\baselineskip D.",
+    );
+    expect(overrides(tex)).toEqual([]);
+  });
+
+  it("silent on local space pulled back: no venue's call names a negative skip", () => {
+    const tex = withPreamble(
+      "\\newcommand{\\tight}{\\vspace{-3pt}}",
+      "A \\vspace{-2mm} B \\vspace*{-1em} C \\vskip -3pt D.",
+    );
+    expect(lint(tex, AIDC)).toEqual([]);
+  });
+
+  it("silent without a preset, or with one that names no template", () => {
+    const tex = withPreamble("\\usepackage{geometry}");
+    expect(
+      lint(tex, undefined).filter((f) => f.rule === "format/layout-override"),
+    ).toEqual([]);
+    expect(overrides(tex, { extends: null })).toEqual([]);
+    const house = {
+      [`${PAPER}/house.jsonc`]: JSON.stringify({
+        tex: { packages: { ieeetran: ["IEEEtran.cls"] } },
+      }),
+    };
+    expect(
+      lint(tex, { extends: "./house.jsonc" }, { extra: house }).filter(
+        (f) => f.rule === "format/layout-override",
+      ),
+    ).toEqual([]);
+  });
 });

package/src/tex-venue-rules.ts

@@ -8,6 +8,13 @@
  *   tex/venue-leftover    warn   the text a reader sees names ANOTHER shipped venue — its `name`
  *                                or one of its `aliases` — than the one the paper extends
  *
+ * and, in the `format` plugin (named for the requirement, not the input — paperlint#151):
+ *
+ *   format/layout-override  error  the source changes the page layout the venue's template sets for
+ *                                  the whole document — margins, text block, line spacing
+ *
+ * The `format` plugin's other rule, `format/page-limit`, judges the built PDF (`venue-rules.ts`).
+ *
  * ── WHY THEY LIVE HERE AND NOT IN `eslint-rules/` ────────────────────────────────
  * Like the `pdf/*` venue rules (`venue-rules.ts`), they need the paper's resolved preset —
  * `paperPreset`, the one answer to "which venue is this paper judged against" — and read it through
@@ -32,6 +39,7 @@ import {
   type ClassLine,
   type DocumentClass,
   type Heading,
+  type LayoutOverride,
   type Outline,
   type Place,
   type Span,
@@ -306,9 +314,26 @@ type Judge = (r: Reading) => readonly Located[];
 export type TexVenueRuleName =
   "template" | "required-section" | "venue-leftover";
 
+/** Every rule this module builds: the `tex` plugin's three and the `format` plugin's one. */
+type RuleName = TexVenueRuleName | "layout-override";
+
+/** Each layout override, where it stands. Silent for a preset that names no template. */
+export function judgeLayout(
+  overrides: readonly LayoutOverride[],
+  preset: Preset,
+): readonly Located[] {
+  const template = preset.template;
+  if (template === null) return [];
+  return overrides.map((o) => ({
+    messageId: "override",
+    data: { command: o.command, venue: preset.label, template: template.text },
+    at: spanOf(o.place),
+  }));
+}
+
 const RULES: Readonly<
   Record<
-    TexVenueRuleName,
+    RuleName,
     { readonly judge: Judge; readonly meta: TexRuleModule["meta"] }
   >
 > = {
@@ -357,6 +382,22 @@ const RULES: Readonly<
       },
     },
   },
+  "layout-override": {
+    judge: (r) => judgeLayout(r.latex.layoutOverrides(r.src), r.preset),
+    meta: {
+      type: "problem",
+      docs: {
+        description:
+          "the source changes the page layout the venue's template sets for the whole document: margins, text block, line spacing",
+        url: "https://github.com/zernie/paperlint/blob/main/docs/rules/format/layout-override.md",
+      },
+      schema: [],
+      messages: {
+        override:
+          "`{{command}}` changes the page layout {{venue}}'s template sets (`{{template}}`) — a desk-reject reason at venues that check the format. Remove it; if the venue allows it, disable this line with a comment saying so",
+      },
+    },
+  },
   "venue-leftover": {
     judge: (r) =>
       judgeLeftover(r.latex.renderedRuns(r.src), r.preset, r.others()),
@@ -385,6 +426,13 @@ export const TEX_VENUE_RULE_LEVELS: Readonly<
   "tex/venue-leftover": "warn",
 };
 
+/** The `format` plugin's rule over the source and its level, on for every `paper.tex`. */
+export const FORMAT_RULE_LEVELS: Readonly<
+  Record<"format/layout-override", "error">
+> = {
+  "format/layout-override": "error",
+};
+
 /**
  * Every shipped venue but the ones on this paper's own chain, each resolved the way a paper
  * extending it would be. A preset that does not resolve is skipped: `pdf/profile` owns that.
@@ -430,7 +478,7 @@ function readingOf(
   };
 }
 
-function rule(name: TexVenueRuleName, deps: TexVenueRuleDeps): TexRuleModule {
+function rule(name: RuleName, deps: TexVenueRuleDeps): TexRuleModule {
   const { judge, meta } = RULES[name];
   return {
     meta,
@@ -459,3 +507,10 @@ export function texVenueRules(
     "venue-leftover": rule("venue-leftover", deps),
   };
 }
+
+/** The `format` plugin's rule over the source (`page-limit`, over the PDF, is in `venue-rules.ts`). */
+export function formatRules(
+  deps: TexVenueRuleDeps,
+): Readonly<Record<"layout-override", TexRuleModule>> {
+  return { "layout-override": rule("layout-override", deps) };
+}

package/src/types.ts

@@ -26,6 +26,8 @@ export interface PaperlintConfig {
   kind?: string;
   /** The default path of the built PDF, relative to each paper. */
   pdf?: string;
+  /** What identifies the authors, for every paper (joined with a paper's own list). */
+  identity?: readonly string[];
   /** A note for humans; ignored. */
   $comment?: unknown;
 }