paperlint 4.2.0 → 6.0.0

package/src/cli.ts

@@ -9,8 +9,8 @@
  * but that is INTERNAL machinery, and you no longer need to know it in order to run them.
  *
  * Two entry points into the tool, and both are whole now:
- *     npx paperlint lint              ← here
- *     uses: zernie/paperlint@<sha>    ← action.yml
+ *     npx paperlint lint                ← here
+ *     uses: ./node_modules/paperlint    ← action.yml, after `npm ci`
  *
  * ⚠️ THE BOUNDARY THIS UTILITY HAS NO RIGHT TO ERASE: the consumer's data stays with the consumer.
  * Where the papers are and the project's own rule blocks — that is about ONE corpus, so it lives in
@@ -42,19 +42,32 @@ import {
   asEslintResults,
 } from "./structure.ts";
 import { buildPapers, papersIn, anyFailed, remedyFor, MAIN } from "./build.ts";
+import { includeBlocks, paperBodies, unreadLines } from "./paper-includes.ts";
 import { prepareEngine } from "./build-engine.ts";
 import { cacheRoot, cachedTree, runToolchain } from "./toolchain.ts";
 import { banalInstaller, parseBanalSettings } from "./adapters/banal/index.ts";
 import { curlDownload } from "./adapters/curl/index.ts";
 import { latexReader } from "./adapters/latex/index.ts";
 import { hostDirs, nodeAdapters, nodeFiles } from "./adapters/node/index.ts";
-import { VENUE_RULE_LEVELS, venueRules } from "./venue-rules.ts";
-import { TEX_VENUE_RULE_LEVELS, texVenueRules } from "./tex-venue-rules.ts";
+import {
+  ANONYMITY_RULE_LEVELS,
+  anonymityRules,
+  PAGE_LIMIT_RULE_LEVELS,
+  pageLimitRules,
+  VENUE_RULE_LEVELS,
+  venueRules,
+} from "./venue-rules.ts";
+import {
+  FORMAT_RULE_LEVELS,
+  formatRules,
+  TEX_VENUE_RULE_LEVELS,
+  texVenueRules,
+} from "./tex-venue-rules.ts";
 import { claimProvenanceRule } from "./claim-provenance.ts";
 import { registerRule } from "./register.ts";
-import { missingInputRule } from "./tex-paper.ts";
 import {
   paperRules,
+  identityField,
   stringFields,
   type PaperSettings,
 } from "./paper-settings.ts";
@@ -125,7 +138,6 @@ export { init };
 export { nextSteps } from "./init.ts";
 
 import paperStages from "#eslint-rules/paper-stages";
-import researchQuestion from "#eslint-rules/paper-research-question";
 import typography from "#eslint-rules/paper-typography";
 import texBuild from "#eslint-rules/tex-build";
 import bibReachable from "#eslint-rules/bib-reachable-entry";
@@ -219,8 +231,9 @@ settings — paperlint.json, at two levels, one schema. Both are optional.
   blocks (files, ignores, rules) with globs relative to that file. Order, later wins: paperlint's
   own, the venue preset's, the root file's, the paper's. Optional rules (off unless turned on):
   pdf/last-page-balance. The venue rules (pdf/fresh, pdf/profile, pdf/fonts, pdf/geometry,
-  pdf/limits, pdf/body-size, pdf/measured) are on for every paper with a venue preset; set one to
-  "off" to skip it. An unknown key, in either file, is an error.
+  pdf/body-size, pdf/measured, format/page-limit, format/layout-override, anonymity/identity) are
+  on for every paper with a venue preset; set one to "off" to skip it. An unknown key, in either
+  file, is an error.
 `;
 
 /** The config the user would otherwise write by hand. The data comes from `opts`, the mechanism is here. */
@@ -228,7 +241,7 @@ export function buildConfig(
   opts: PaperlintConfig = {},
   texLanguage: unknown,
 ): ConfigBlock[] {
-  const paperRules = { ...researchQuestion.rules, ...typography.rules };
+  const paperRules = { ...typography.rules };
   // The reference rules judge `_build/references.json`, and only on `paper.tex`.
   const texPaperRules = {
     ...paperRules,
@@ -236,7 +249,6 @@ export function buildConfig(
   };
   // Each typography rule reports every occurrence where it is, and fixes it (`--fix`).
   const prose = {
-    "paper/research-question": "warn",
     "paper/section-word": "warn",
     "paper/leading-zero": "warn",
   };
@@ -264,6 +276,9 @@ export function buildConfig(
             ...venueRules({ files: nodeFiles, venuesDir: presetsDir() }),
           },
         },
+        anonymity: {
+          rules: anonymityRules({ files: nodeFiles, venuesDir: presetsDir() }),
+        },
       },
     },
     {
@@ -319,10 +334,6 @@ export function buildConfig(
               files: nodeFiles,
               latex: latexReader,
             }),
-            "missing-input": missingInputRule({
-              files: nodeFiles,
-              latex: latexReader,
-            }),
             register: registerRule({
               files: nodeFiles,
               latex: latexReader,
@@ -331,6 +342,16 @@ export function buildConfig(
         },
         paper: { rules: texPaperRules },
         bib: bibReachable,
+        format: {
+          rules: {
+            ...formatRules({
+              files: nodeFiles,
+              venuesDir: presetsDir(),
+              latex: latexReader,
+            }),
+            ...pageLimitRules({ files: nodeFiles, venuesDir: presetsDir() }),
+          },
+        },
       },
       language: "tex/latex",
       rules: {
@@ -341,26 +362,65 @@ export function buildConfig(
         "tex/future-promise": "warn",
         // A number with no owner: a prose rule, on beside the others above.
         "tex/claim-provenance": "warn",
-        "tex/missing-input": "warn",
         // Sentence-initial conjunctions over the whole body: register, not vocabulary.
         "tex/register": "warn",
         "tex/acm-frontmatter-override": "error",
         // Silent for a paper whose paperlint.json names no venue (src/venue-rules.ts).
         ...VENUE_RULE_LEVELS,
+        ...ANONYMITY_RULE_LEVELS,
         ...TEX_VENUE_RULE_LEVELS,
+        ...FORMAT_RULE_LEVELS,
+        ...PAGE_LIMIT_RULE_LEVELS,
       },
     });
+  // THE FILES A paper.tex INCLUDES FROM ITS BODY, each read on its own and reported at its own path
+  // (#144). The block claims every `.tex` but `paper.tex` — yet it is left out of the scope below, so
+  // it reaches only the files `paperlint lint` un-ignores by name for each paper (src/paper-includes.ts):
+  // a frozen version or a macro file is never enumerated. The rules are the ones that read a file as
+  // a fragment (no `document` environment: all of it is body); the whole-paper rules stay on
+  // `paper.tex`, which reads its includes itself (src/tex-paper.ts).
+  const fragments: readonly ConfigBlock[] = texLanguage
+    ? [
+        {
+          files: ["**/*.tex"],
+          ignores: ["**/paper.tex"],
+          plugins: {
+            tex: {
+              languages: { latex: texLanguage },
+              rules: { "future-promise": texBuild["future-promise"] },
+            },
+            paper: {
+              rules: {
+                "section-word": typography.rules["section-word"],
+                "leading-zero": typography.rules["leading-zero"],
+                "figure-ref-style": typography.rules["figure-ref-style"],
+              },
+            },
+          },
+          language: "tex/latex",
+          rules: {
+            "paper/section-word": "warn",
+            "paper/leading-zero": "warn",
+            "paper/figure-ref-style": "warn",
+            "tex/future-promise": "warn",
+          },
+        },
+      ]
+    : [];
   // 🔴 ONLY THE FILES THESE BLOCKS CLAIM ARE LINTED (src/paper-files.ts). Without this block ESLint's
   // built-in defaults lint every .js/.mjs/.cjs under the papers directory — a paper's vendored
   // `repro/` code failed the run with 74 parse errors and not one finding on a paper file. It goes
   // FIRST: the `.template/` ignore below must come after its directory un-ignore to win.
-  const owners = ruleOwners(cfg);
+  const owners = ruleOwners([...cfg, ...fragments]);
   cfg.unshift(scopeToOwned(ownedPatterns(cfg)));
   // The consumer's own blocks, LAST, so a later block wins — ESLint's rule. Parsed by
   // `readConfig`; each carries the settings file's directory as its `basePath`. Each is split so a
   // rule reaches only the files its plugin is registered for: `paper` is a different plugin beside
   // PIPELINE-STATUS.md than beside paper.tex, and ESLint throws on a rule its plugin lacks.
-  cfg.push(...(opts.rules ?? []).flatMap((b) => narrowToOwners(b, owners)));
+  cfg.push(
+    ...fragments,
+    ...(opts.rules ?? []).flatMap((b) => narrowToOwners(b, owners)),
+  );
   return cfg;
 }
 
@@ -501,6 +561,17 @@ export async function silentOptionalRules(
   return [...turnedOn].filter((id) => !reached.has(id));
 }
 
+/**
+ * The paper directories `paths` reach: each directory and the papers under it. A FILE named on the
+ * command line belongs to the paper it sits in.
+ */
+function paperDirs(paths: readonly string[]): readonly string[] {
+  const dirs = paths.map((p) =>
+    existsSync(p) && statSync(p).isFile() ? dirname(p) : p,
+  );
+  return [...new Set(dirs.flatMap((p) => [p, ...papersIn(p)]))];
+}
+
 /**
  * Every linted paper's rules, as ESLint blocks scoped to that paper, in two groups: what its venue
  * preset turns on, and what its own `paperlint.json` says. The caller puts the root's blocks between
@@ -510,11 +581,7 @@ export async function silentOptionalRules(
 export function paperRuleBlocks(
   paths: readonly string[],
 ): Parsed<{ preset: RuleBlock[]; own: RuleBlock[] }> {
-  // A FILE named on the command line belongs to the paper it sits in: that paper's settings apply.
-  const dirs = paths.map((p) =>
-    existsSync(p) && statSync(p).isFile() ? dirname(p) : p,
-  );
-  const papers = [...new Set(dirs.flatMap((p) => [p, ...papersIn(p)]))];
+  const papers = paperDirs(paths);
   const out: { preset: RuleBlock[]; own: RuleBlock[] } = {
     preset: [],
     own: [],
@@ -630,6 +697,8 @@ export function parseSettings(
     };
   const defaults = stringFields(raw);
   if (!defaults.ok) return { ok: false, error: `${where}: ${defaults.error}` };
+  const identity = identityField(raw);
+  if (!identity.ok) return { ok: false, error: `${where}: ${identity.error}` };
   const structure = Structure.safeParse(raw["structure"]);
   if (!structure.success)
     return {
@@ -765,28 +834,6 @@ const VALUE_FLAGS: ReadonlySet<string> = new Set([
   "--max-warnings",
 ]);
 
-/**
- * This package's own version, from the `package.json` beside `src/` and `dist/` alike. `init` pins
- * the CI action to its release tag; an unreadable manifest yields `undefined`, and init then keeps
- * the placeholder instead of guessing.
- */
-export function ownVersion(
-  readManifest: () => string = () =>
-    readFileSync(new URL("../package.json", import.meta.url), "utf8"),
-): string | undefined {
-  try {
-    const manifest: unknown = JSON.parse(readManifest());
-    return typeof manifest === "object" &&
-      manifest !== null &&
-      "version" in manifest &&
-      typeof manifest.version === "string"
-      ? manifest.version
-      : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
 /**
  * Reading the config, ONE reader for all commands. Pulled out of `run()` the moment a second
  * command needed the same config (`build`): two copies of this block would have drifted apart on
@@ -1421,7 +1468,6 @@ async function runInit(
     log,
     err,
     cwd,
-    version: ownVersion(),
     yes: a.yes,
     hooks: !a.noHooks,
     paper: a.paper,
@@ -1557,10 +1603,32 @@ export async function run(
     texLanguage = null;
   }
 
+  // Each paper's body files, resolved the way the build resolves them — only when the LaTeX language
+  // loaded, since only its rules read them. The project's papers too: `paperlint lint .` reaches
+  // papers two levels down, which a directory's immediate papers do not.
+  const bodies = texLanguage
+    ? paperBodies(paperDirs([...paths, ...papersRoots(cfg)]), {
+        files: nodeFiles,
+        latex: latexReader,
+      })
+    : [];
+  // Named only for the papers this run lints: a paper elsewhere in the project is not this run's.
+  const inScope = (dir: string) =>
+    paths.some((p) => dir === p || dir.startsWith(`${p}${sep}`));
+  unreadLines(
+    bodies.filter((b) => inScope(b.dir)),
+    (p) => shown(cwd, p),
+  ).forEach((l) => {
+    err(l);
+  });
+
   const eslint = new ESLint({
     cwd: lintRoot(root, paths),
     overrideConfigFile: true,
-    overrideConfig: eslintConfig(buildConfig(withPapers, texLanguage)),
+    overrideConfig: eslintConfig([
+      ...buildConfig(withPapers, texLanguage),
+      ...includeBlocks(bodies),
+    ]),
     fix: a.fix,
   });
 

package/src/domain/anonymity.test.ts

@@ -0,0 +1,163 @@
+import { describe, expect, it } from "vitest";
+import {
+  findLeaks,
+  spellingsOf,
+  tokenPattern,
+  type Searchable,
+} from "./anonymity.ts";
+
+const page = (text: string, n = 1): Searchable => ({
+  place: { kind: "page", page: n },
+  text,
+});
+const found = (token: string, text: string): string[] =>
+  findLeaks([token], [page(text)]).map((l) => l.found);
+
+describe("findLeaks — the spellings of one name a PDF produces", () => {
+  it("plain, and in any case (the flags fold Unicode, no locale)", () => {
+    expect(found("Ada Example", "by Ada Example, 2026")).toEqual([
+      "Ada Example",
+    ]);
+    expect(found("Ada Example", "ADA EXAMPLE")).toEqual(["ADA EXAMPLE"]);
+  });
+
+  it("Cyrillic folds too", () => {
+    expect(found("Ада Пример", "АДА ПРИМЕР пишет")).toEqual(["АДА ПРИМЕР"]);
+    expect(found("АДА", "ада")).toEqual(["ада"]);
+  });
+
+  it("items joined without a space where kerning split a word", () => {
+    expect(found("Ada Example", "AdaExample")).toEqual(["AdaExample"]);
+  });
+
+  it("letter-spaced text", () => {
+    expect(found("Ada Example", "A d a  E x a m p l e")).toEqual([
+      "A d a  E x a m p l e",
+    ]);
+  });
+
+  it("a word hyphenated across a line break, and a name broken across lines", () => {
+    expect(found("Ada Example", "Ada Exam-\nple wrote")).toEqual([
+      "Ada Exam-\nple",
+    ]);
+    expect(found("Ada Example", "by Ada\nExample")).toEqual(["Ada\nExample"]);
+    expect(found("adaexample", "ada­example")).toEqual(["ada­example"]);
+  });
+
+  it("ligatures (NFKC on both sides)", () => {
+    expect(found("Fiona", "fiona")).toEqual(["fiona"]);
+    expect(found("fiona", "Fiona")).toEqual(["Fiona"]);
+  });
+
+  it("handles and addresses, as whole tokens", () => {
+    expect(found("adaexample", "https://github.com/adaexample/tool")).toEqual([
+      "adaexample",
+    ]);
+    expect(found("ada@example.org", "mail ada@example.org.")).toEqual([
+      "ada@example.org",
+    ]);
+  });
+
+  it("does not match inside another word", () => {
+    expect(found("Ada", "Canada and adamant")).toEqual([]);
+    expect(found("MIT", "submitted")).toEqual([]);
+  });
+
+  it("says nothing about a clean text", () => {
+    expect(found("Ada Example", "Anonymous Authors")).toEqual([]);
+  });
+});
+
+describe("findLeaks — places and tokens", () => {
+  it("reports each token once per place, with the place", () => {
+    const leaks = findLeaks(
+      ["Ada Example", "ada@example.org"],
+      [
+        page("Ada Example and Ada Example", 2),
+        {
+          place: { kind: "metadata", field: "Author" },
+          text: "ada@example.org",
+        },
+        {
+          place: {
+            kind: "link",
+            page: 3,
+            uri: "https://github.com/adaexample",
+          },
+          text: "https://github.com/adaexample",
+        },
+      ],
+    );
+    expect(leaks).toEqual([
+      {
+        token: "Ada Example",
+        place: { kind: "page", page: 2 },
+        found: "Ada Example",
+      },
+      {
+        token: "ada@example.org",
+        place: { kind: "metadata", field: "Author" },
+        found: "ada@example.org",
+      },
+      {
+        token: "Ada Example",
+        place: { kind: "link", page: 3, uri: "https://github.com/adaexample" },
+        found: "adaexample",
+      },
+    ]);
+  });
+
+  it("a token of separators only has no pattern and finds nothing", () => {
+    expect(tokenPattern(" - ")).toBeNull();
+    expect(findLeaks([" "], [page("anything at all")])).toEqual([]);
+  });
+});
+
+describe("findLeaks — one text, two tokens", () => {
+  it("is one leak, under the first token declared", () => {
+    expect(
+      findLeaks(["Ada Example", "adaexample"], [page("by AdaExample")]),
+    ).toEqual([
+      {
+        token: "Ada Example",
+        place: { kind: "page", page: 1 },
+        found: "AdaExample",
+      },
+    ]);
+  });
+});
+
+describe("spellingsOf — a personal name as a reference list prints it", () => {
+  it("adds initials and surname-first forms to a name of two to four words", () => {
+    expect(spellingsOf("Ada Example")).toEqual([
+      "Ada Example",
+      "A. Example",
+      "Example, Ada",
+      "Example, A.",
+    ]);
+    expect(spellingsOf("Ada Byron Example")).toEqual([
+      "Ada Byron Example",
+      "A. B. Example",
+      "Example, Ada Byron",
+      "Example, A. B.",
+    ]);
+  });
+
+  it("leaves a handle, an address, one word, or lowercase words alone", () => {
+    expect(spellingsOf("adaexample")).toEqual(["adaexample"]);
+    expect(spellingsOf("ada@example.org")).toEqual(["ada@example.org"]);
+    expect(spellingsOf("Example")).toEqual(["Example"]);
+    expect(spellingsOf("example tool")).toEqual(["example tool"]);
+    expect(spellingsOf("A B C D E")).toEqual(["A B C D E"]);
+  });
+
+  it("a self-citation's author list finds the declared name", () => {
+    expect(
+      found("Ada Example", "[3] A. Example and B. Other, “A tool,” 2025."),
+    ).toEqual(["A. Example"]);
+    expect(found("Ada Example", "Example, A., and Other, B. (2025)")).toEqual([
+      "Example, A.",
+    ]);
+    expect(found("Ada Example", "B. Example wrote")).toEqual([]);
+  });
+});

package/src/domain/anonymity.ts

@@ -0,0 +1,129 @@
+/**
+ * WHO WROTE THIS PAPER, FOUND IN THE PAPER — the matching `anonymity/identity` judges a blind submission
+ * by. A rule cannot know who the author is, so the author DECLARES it (`identity` in
+ * `paperlint.json`); given that list, finding it is mechanical, and this module is the mechanism.
+ *
+ * ── WHAT A MATCH TOLERATES, AND WHY EACH ─────────────────────────────────────────
+ * PDF text is not the source text. pdf.js hands back runs of glyphs, and the same name comes out
+ * in several spellings of the same letters:
+ *
+ *   ligatures        `fi` for `fi`                    → both sides NFKC-normalized
+ *   case             `ADA EXAMPLE` in small caps       → Unicode case folding (the `iu` flags: no
+ *                                                         locale is consulted, Cyrillic folds too)
+ *   kerning splits   `Ex` `ample` as two items         → the page text joins items without a space
+ *   letter-spacing   `A d a  E x a m p l e`            → whitespace may stand between any two letters
+ *   line breaks      `Ada` ⏎ `Example`, `Exam-` ⏎ `ple` → so may a hyphen and a line break
+ *   soft hyphens     U+00AD inside a word              → treated like a hyphen
+ *   a reference list `A. Example`, `Example, A.`       → a personal name's bibliographic forms
+ *                                                         are searched too (`spellingsOf`)
+ *
+ * Only the ENDS of a token are anchored: the letter or digit before its first character and after
+ * its last must be absent, so `Ada` does not match inside `Canada`. Between its characters anything
+ * of the above may stand. The token's own spaces and hyphens are separators too, so
+ * `Ada Example` also finds `Ada-Example` and `AdaExample` — the same person.
+ */
+
+/** Where a declared string was found: a page's text, a metadata field, or a link's target. */
+export type LeakPlace =
+  | { readonly kind: "page"; readonly page: number }
+  | { readonly kind: "metadata"; readonly field: string }
+  | { readonly kind: "link"; readonly page: number; readonly uri: string };
+
+/** One text to search, and where it came from. */
+export interface Searchable {
+  readonly place: LeakPlace;
+  readonly text: string;
+}
+
+/** One declared string found in one place, with the text it matched as it stands there. */
+export interface Leak {
+  readonly token: string;
+  readonly place: LeakPlace;
+  readonly found: string;
+}
+
+/** What may stand between two characters of a token: whitespace, hyphens, soft hyphens. */
+const SEPARATOR = "[\\s\\u00AD-]*";
+const BEFORE = "(?<![\\p{L}\\p{N}])";
+const AFTER = "(?![\\p{L}\\p{N}])";
+
+/** `c` as a pattern that matches it literally. */
+const literal = (c: string): string =>
+  c.replace(/[.*+?^${}()|[\]\\/]/gu, "\\$&");
+
+/** The characters of a token that must appear: NFKC, without its own separators. */
+const lettersOf = (token: string): readonly string[] =>
+  token
+    .normalize("NFKC")
+    .replace(/[\s\u00AD-]/gu, "")
+    .match(/./gsu) ?? [];
+
+/** A word of a personal name: letters, with an apostrophe or a hyphen inside. */
+const NAME_WORD = /^\p{Lu}[\p{L}'’-]*$/u;
+
+/**
+ * The spellings a bibliography gives a personal name, besides the name itself. A token of two to
+ * four capitalized words (`Ada Example`, `Ada B. Example` is not one: an initial is not a word)
+ * is read as given names and a surname, and the reference list's forms are added: initials
+ * (`A. Example`), surname first (`Example, Ada`, `Example, A.`). A token that is not a name — a
+ * handle, an address, one word — has only itself.
+ */
+export function spellingsOf(token: string): readonly string[] {
+  const words = token.trim().split(/\s+/u);
+  if (
+    words.length < 2 ||
+    words.length > 4 ||
+    !words.every((w) => NAME_WORD.test(w))
+  )
+    return [token];
+  const surname = words.slice(-1).join("");
+  const given = words.slice(0, -1);
+  const initials = given.map((w) => `${w.slice(0, 1)}.`).join(" ");
+  return [
+    token,
+    `${initials} ${surname}`,
+    `${surname}, ${given.join(" ")}`,
+    `${surname}, ${initials}`,
+  ];
+}
+
+/** One spelling as a pattern body: its characters, separators allowed between any two. */
+const bodyOf = (spelling: string): string =>
+  lettersOf(spelling).map(literal).join(SEPARATOR);
+
+/**
+ * A declared token as the pattern that finds it and its bibliographic spellings (see the module
+ * header), or null for a token with nothing but separators in it — which would match everywhere,
+ * and is refused where it is read.
+ */
+export function tokenPattern(token: string): Readonly<RegExp> | null {
+  if (lettersOf(token).length === 0) return null;
+  const bodies = spellingsOf(token).map(bodyOf).join("|");
+  return new RegExp(`${BEFORE}(?:${bodies})${AFTER}`, "iu");
+}
+
+/**
+ * Every token found in the sources, once per place: its first match there. Two tokens that match
+ * the same text in the same place (`Ada Example` and `adaexample` both finding `AdaExample`) are one
+ * leak, reported under the first token declared. Pure.
+ */
+export function findLeaks(
+  tokens: readonly string[],
+  sources: readonly Searchable[],
+): readonly Leak[] {
+  const patterns = tokens.flatMap((token) => {
+    const re = tokenPattern(token);
+    return re === null ? [] : [{ token, re }];
+  });
+  return sources.flatMap((s) => {
+    const text = s.text.normalize("NFKC");
+    const leaks = patterns.flatMap(({ token, re }) => {
+      const m = re.exec(text);
+      return m === null ? [] : [{ token, place: s.place, found: m[0] }];
+    });
+    const key = (l: Leak): string => l.found.toLowerCase();
+    return leaks.filter(
+      (l, i) => leaks.findIndex((x) => key(x) === key(l)) === i,
+    );
+  });
+}