paperlint 5.0.0 → 6.1.0

package/src/register-bands.ts

@@ -0,0 +1,291 @@
+/**
+ * THE REGISTER RULES THAT MEASURE A BODY AGAINST ITS VENUE'S ACCEPTED PAPERS — each a rate per
+ * 10,000 words, judged against the band the venue preset's anchors set (`src/domain/register.ts`):
+ *
+ *   tex/contrast-frames   warn  «X, not Y», «rather than», «instead of» … outside the band; above it,
+ *                               each frame is reported where it stands
+ *   tex/claim-emphasis    warn  claims set in bold inside a sentence outside the band; above it, each
+ *                               is reported where it stands
+ *   tex/relation-markers  warn  words naming how a sentence relates to the one before (because,
+ *                               therefore, however, for example …) outside the band
+ *
+ * ── WHY ──────────────────────────────────────────────────────────────────────────
+ * Reviewers called a paper "too informal" and "a blogpost". Its text differed from the accepted
+ * papers of the venue's parent conference in exactly these three counts, each several times over
+ * the anchors' range, while sentence length, contractions, questions and the second person did not
+ * separate them. The measurements are on the rules' pages.
+ *
+ * ── TWO-SIDED, AND THE VENUE'S OWN ───────────────────────────────────────────────
+ * Every rule judges both ends of its band: a rewrite that strips every relation marker is as far
+ * from the venue as one that stacks contrast frames. The band is the venue preset's, derived from
+ * its anchors, so a venue with other accepted papers gets another band, and a preset without
+ * anchors is not judged — there is nothing to compare, as `tex/template` is silent for a preset that
+ * names no template. A body under `MIN_WORDS` is not judged either: one sentence would decide it.
+ */
+import { basename, dirname } from "node:path";
+import {
+  bandOf,
+  bodySentences,
+  claimEmphasis,
+  contrastFrames,
+  rateOf,
+  relationMarkers,
+  wordsOf,
+  type Band,
+  type Occurrence,
+  type RegisterAnchor,
+  type RegisterMeasureName,
+} from "./domain/register.ts";
+import type { Emphasis, Passage, Span } from "./domain/tex-document.ts";
+import type { LatexReader } from "./ports/latex.ts";
+import { paperPreset } from "./presets.ts";
+import { MIN_WORDS, startOf } from "./register.ts";
+import { readPaper, reportInPaper } from "./tex-paper.ts";
+import {
+  ruleDocsUrl,
+  type Located,
+  type TexRuleContext,
+  type TexRuleModule,
+} from "./tex-venue-rules.ts";
+import type { VenueRuleDeps } from "./venue-rules.ts";
+
+/** What the three rules read: the preset store, and the LaTeX reader. */
+export interface RegisterBandDeps extends VenueRuleDeps {
+  readonly latex: LatexReader;
+}
+
+export type RegisterBandRuleName =
+  "contrast-frames" | "claim-emphasis" | "relation-markers";
+
+/** What one body measures for one rule: its words, the occurrences, where the body starts. */
+export interface BodyMeasure {
+  readonly words: number;
+  readonly occurrences: readonly Occurrence[];
+  readonly at: Span | null;
+}
+
+/** How a rate stands against a band. */
+export type Standing = "below" | "within" | "above";
+
+export const standingOf = (rate: number, band: Band): Standing =>
+  rate < band.min ? "below" : rate > band.max ? "above" : "within";
+
+const fixed = (n: number): string => n.toFixed(1);
+
+/** How many examples a finding about the whole body quotes. */
+const EXAMPLES = 3;
+
+/** What every message about a body names: its count and rate, the band, the anchors' range, examples. */
+function dataOf(
+  m: BodyMeasure,
+  band: Band,
+  venue: string,
+): Readonly<Record<string, string | number>> {
+  return {
+    count: m.occurrences.length,
+    words: m.words,
+    rate: fixed(rateOf(m.occurrences.length, m.words)),
+    venue,
+    min: fixed(band.min),
+    max: fixed(band.max),
+    anchors: band.anchors,
+    anchorMin: fixed(band.anchorMin),
+    anchorMax: fixed(band.anchorMax),
+    examples: m.occurrences
+      .slice(0, EXAMPLES)
+      .map((o) => `«${o.sentence}»`)
+      .join(", "),
+  };
+}
+
+/**
+ * A body against a band: nothing within it; outside it, one finding at the body's start naming the
+ * count, the rate, the band and the anchors' range — and, above it when `each` is set, one finding
+ * at every occurrence, so an editor shows the author where to rewrite.
+ */
+export function judgeBand(
+  m: BodyMeasure,
+  band: Band | null,
+  venue: string,
+  each: boolean,
+): readonly Located[] {
+  if (band === null || m.words < MIN_WORDS) return [];
+  const standing = standingOf(rateOf(m.occurrences.length, m.words), band);
+  if (standing === "within") return [];
+  const data = dataOf(m, band, venue);
+  const whole: Located = { messageId: standing, data, at: m.at };
+  if (standing === "below" || !each) return [whole];
+  const at = (o: Occurrence, i: number): Located => ({
+    messageId: "each",
+    data: { ...data, match: o.match, index: i + 1 },
+    at: o.at,
+  });
+  return [whole, ...m.occurrences.map(at)];
+}
+
+/** The band words every message shares: the rate, and where the venue's anchors put it. */
+const AGAINST =
+  "{{rate}} per 10,000 words; {{venue}}'s {{anchors}} anchor papers measure {{anchorMin}}–{{anchorMax}}, and this rule warns outside {{min}}–{{max}}";
+
+/** The body as the measures read it: its prose, and the phrases emphasised in it (read on demand). */
+interface Body {
+  readonly passages: readonly Passage[];
+  readonly emphasis: () => readonly Emphasis[];
+}
+
+/** What each rule counts, how it reads the paper, and what it says. */
+interface Measure {
+  readonly name: RegisterMeasureName;
+  readonly description: string;
+  /** Above the band, report every occurrence where it stands. */
+  readonly each: boolean;
+  readonly count: (body: Body) => readonly Occurrence[];
+  readonly messages: Readonly<Record<string, string>>;
+}
+
+const MEASURES: Readonly<Record<RegisterBandRuleName, Measure>> = {
+  "contrast-frames": {
+    name: "contrast_frames",
+    description:
+      "contrast frames («X, not Y», «rather than», «instead of») stay within the rate the venue's accepted papers show",
+    each: true,
+    count: (b) => contrastFrames(bodySentences(b.passages)),
+    messages: {
+      above: `{{count}} contrast frames («X, not Y», «not X but Y», «rather than», «instead of», «as opposed to») — ${AGAINST}. First: {{examples}}. Say what the thing is and why, with the evidence; keep a frame only where a reader would otherwise assume the rejected alternative`,
+      below: `{{count}} contrast frames — ${AGAINST}. A rewrite may have dropped relations the argument needs: check that each claim still says what it is set against`,
+      each: "contrast frame «{{match}}» ({{index}} of {{count}}; the body is at {{rate}} per 10,000 words, above {{venue}}'s {{max}})",
+    },
+  },
+  "claim-emphasis": {
+    name: "claim_emphasis",
+    description:
+      "claims set in bold inside a sentence stay within the rate the venue's accepted papers show",
+    each: true,
+    count: (b) => claimEmphasis(b.emphasis()),
+    messages: {
+      above: `{{count}} claims set in bold inside a sentence (a bold phrase of six words or more, or holding a number) — ${AGAINST}. First: {{examples}}. Accepted papers set a term or a label in bold; take the bold off a finding and let the sentence, a table or a figure carry it`,
+      below: `{{count}} claims set in bold inside a sentence — ${AGAINST}`,
+      each: "a claim set in bold, «{{match}}» ({{index}} of {{count}}; the body is at {{rate}} per 10,000 words, above {{venue}}'s {{max}})",
+    },
+  },
+  "relation-markers": {
+    name: "relation_markers",
+    description:
+      "words that name how a sentence relates to the one before (because, therefore, however, for example) stay within the rate the venue's accepted papers show",
+    each: false,
+    count: (b) => relationMarkers(bodySentences(b.passages)),
+    messages: {
+      below: `{{count}} words name how a sentence relates to the one before (because, therefore, however, in contrast, for example, that is …) — ${AGAINST}. Where two sentences stand side by side, say whether the second is the cause, the consequence, an example or a limit of the first`,
+      above: `{{count}} relation markers — ${AGAINST}. First: {{examples}}`,
+    },
+  },
+};
+
+/** What a body measures for a rule: its words, its occurrences, and where it starts. */
+export function measureBody(
+  rule: RegisterBandRuleName,
+  src: string,
+  latex: LatexReader,
+): BodyMeasure {
+  const passages = latex.bodyProse(src);
+  const [first] = passages;
+  const body: Body = { passages, emphasis: () => latex.bodyEmphasis(src) };
+  return {
+    words: wordsOf(bodySentences(passages)),
+    occurrences: MEASURES[rule].count(body),
+    at: first === undefined ? null : startOf(first),
+  };
+}
+
+/** Which rule counts each measure an anchor records. */
+const RULE_OF: Readonly<Record<RegisterMeasureName, RegisterBandRuleName>> = {
+  contrast_frames: "contrast-frames",
+  claim_emphasis: "claim-emphasis",
+  relation_markers: "relation-markers",
+};
+
+/**
+ * A paper as a preset records it among its anchors: its body's words and its count of every
+ * measure, by the rules' own counters — the one way an anchor is measured.
+ */
+export function anchorOf(
+  paper: string,
+  src: string,
+  latex: LatexReader,
+): RegisterAnchor {
+  const passages = latex.bodyProse(src);
+  const body: Body = { passages, emphasis: () => latex.bodyEmphasis(src) };
+  const count = (m: RegisterMeasureName): number =>
+    MEASURES[RULE_OF[m]].count(body).length;
+  return {
+    paper,
+    words: wordsOf(bodySentences(passages)),
+    counts: {
+      contrast_frames: count("contrast_frames"),
+      claim_emphasis: count("claim_emphasis"),
+      relation_markers: count("relation_markers"),
+    },
+  };
+}
+
+/** The findings for the paper whose `paper.tex` is `filename`; none when its preset has no anchors. */
+function judgePaper(
+  name: RegisterBandRuleName,
+  context: TexRuleContext,
+  deps: RegisterBandDeps,
+): void {
+  const p = paperPreset(dirname(context.filename), deps);
+  if (p.kind !== "resolved") return;
+  const measure = MEASURES[name];
+  const band = bandOf(p.preset.registerAnchors, measure.name);
+  if (band === null) return;
+  const sc = context.sourceCode;
+  const paper = readPaper(context.filename, sc.raw ?? sc.text, deps);
+  const m = measureBody(name, paper.text, deps.latex);
+  const findings = judgeBand(m, band, p.preset.label, measure.each);
+  reportInPaper(context, measure.messages, paper, findings);
+}
+
+function rule(
+  name: RegisterBandRuleName,
+  deps: RegisterBandDeps,
+): TexRuleModule {
+  const measure = MEASURES[name];
+  return {
+    meta: {
+      type: "suggestion",
+      docs: { description: measure.description, url: ruleDocsUrl(name) },
+      schema: [],
+      messages: measure.messages,
+    },
+    create(context) {
+      // Judged once per paper, on its paper.tex: the paper directory is the file's directory.
+      if (basename(context.filename) !== "paper.tex") return {};
+      return {
+        root: () => {
+          judgePaper(name, context, deps);
+        },
+      };
+    },
+  };
+}
+
+/** The three rules, as rules of the `tex` plugin. */
+export function registerBandRules(
+  deps: RegisterBandDeps,
+): Readonly<Record<RegisterBandRuleName, TexRuleModule>> {
+  return {
+    "contrast-frames": rule("contrast-frames", deps),
+    "claim-emphasis": rule("claim-emphasis", deps),
+    "relation-markers": rule("relation-markers", deps),
+  };
+}
+
+/** The level each rule is on at in paperlint's own config, for every `paper.tex`. */
+export const REGISTER_BAND_RULE_LEVELS: Readonly<
+  Record<`tex/${RegisterBandRuleName}`, "warn">
+> = {
+  "tex/contrast-frames": "warn",
+  "tex/claim-emphasis": "warn",
+  "tex/relation-markers": "warn",
+};

package/src/register.ts

@@ -15,8 +15,8 @@
  * (src/domain/sentences.ts). A citation, a cross-reference or math reads as one word, as it does on
  * the page. A body under 2 000 words is not judged: there one sentence decides the rate.
  */
-import { runText, type Passage, type Span } from "./domain/tex-document.ts";
-import { runOf, sentences } from "./domain/sentences.ts";
+import type { Passage, Span } from "./domain/tex-document.ts";
+import { bodySentences, wordsOf } from "./domain/register.ts";
 import { readPaper, reportInPaper, type PaperDeps } from "./tex-paper.ts";
 import {
   ruleDocsUrl,
@@ -24,7 +24,7 @@ import {
   type TexRuleModule,
 } from "./tex-venue-rules.ts";
 
-/** Under this many words in the body, the rate is not judged. */
+/** Under this many words in the body, a rate is not judged: one sentence would decide it. */
 export const MIN_WORDS = 2000;
 
 /** The limit when the config sets none, from the measurement on the rule's page. */
@@ -40,30 +40,6 @@ const CONJUNCTIONS: ReadonlySet<string> = new Set([
   "Yet",
 ]);
 
-/** The characters a mark or math stands as in a sentence's text (src/domain/sentences.ts). */
-const MARK = /[-]/gu;
-
-const WORDS = new Intl.Segmenter("en", { granularity: "word" });
-
-/** A sentence as the rate sees it: its text, its words, and its first word. */
-interface Sentence {
-  readonly text: string;
-  readonly words: number;
-  readonly first: string;
-}
-
-/** A sentence's words: the word-like ones, and one for each mark or math. Null when it has none of its own. */
-function sentenceOf(text: string): Sentence | null {
-  const words = [...WORDS.segment(text)].filter((w) => w.isWordLike);
-  const [first] = words;
-  if (first === undefined) return null;
-  return {
-    text: text.replace(MARK, "").replace(/\s+/gu, " ").trim(),
-    words: words.length + (text.match(MARK)?.length ?? 0),
-    first: first.segment,
-  };
-}
-
 /** What the body measures. */
 export interface RegisterMeasure {
   readonly words: number;
@@ -74,8 +50,8 @@ export interface RegisterMeasure {
   readonly at: Span | null;
 }
 
-/** Where a passage's first piece stands. */
-function startOf(p: Passage): Span {
+/** Where a passage's first piece stands: where a finding about the whole body points. */
+export function startOf(p: Passage): Span {
   const first = p.pieces[0];
   return first.kind === "text"
     ? {
@@ -87,17 +63,11 @@ function startOf(p: Passage): Span {
 
 /** The body's words, and its sentences that open with a conjunction. */
 export function measureRegister(passages: readonly Passage[]): RegisterMeasure {
-  const all = passages.flatMap((p) => {
-    const text = runText(runOf(p));
-    return sentences(text).flatMap(([from, to]) => {
-      const s = sentenceOf(text.slice(from, to));
-      return s === null ? [] : [s];
-    });
-  });
+  const all = bodySentences(passages);
   const conj = all.filter((s) => CONJUNCTIONS.has(s.first));
   const [first] = passages;
   return {
-    words: all.reduce((n, s) => n + s.words, 0),
+    words: wordsOf(all),
     conjunctionStarts: conj.length,
     examples: conj.slice(0, 3).map((s) => s.text),
     at: first === undefined ? null : startOf(first),

package/src/rule-cases.test.ts

@@ -43,11 +43,22 @@ const paper = (
 
 const PDF = "%PDF-1.5 a stand-in for the built PDF";
 const AGENTICDEV = { extends: "paperlint:agenticdev", kind: "short" };
+/** A double-blind venue's paper that declares who wrote it (`anonymity/*`). */
+const BLIND = {
+  extends: "paperlint:aidc",
+  kind: "regular",
+  identity: ["Ada Example", "adaexample"],
+};
 const ACM_TEX = tex("Text.", "\\documentclass[sigconf]{acmart}");
 
 /** The facts of a short agenticdev paper that meets every number in its preset. */
 const goodFacts = (): Record<string, unknown> => ({
-  schema: 2,
+  schema: 3,
+  pages_text: [],
+  metadata: {},
+  links: [],
+  bib_anchor_page: null,
+  appendix_anchor_page: null,
   pdf: "paper.pdf",
   pdf_sha256: sha256Hex(new TextEncoder().encode(PDF)),
   venue: "agenticdev",
@@ -157,6 +168,14 @@ const FORMAL = Array.from(
   () =>
     "The rule reads the body of the paper and counts every sentence it holds.",
 ).join(" ");
+/** FORMAL with `n` more sentences `s`: a body whose rate of one register measure is set. */
+const formalWith = (n: number, s: string): string =>
+  `${FORMAL} ${Array.from({ length: n }, () => s).join(" ")}`;
+/** FORMAL with enough relation markers for AIDC's band (above 25.4 per 10,000 words). */
+const LINKED = formalWith(
+  10,
+  "Therefore, the rule counts the sentence because the body holds it.",
+);
 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";
@@ -346,6 +365,32 @@ const CASES: Readonly<Record<string, RuleCases>> = {
     },
     silent: paper(tex(FORMAL)),
   },
+  // The three register bands judge a body against the anchors of AIDC's preset; the body opens on
+  // line 3, right after the \\section, where the finding about the whole body stands.
+  "tex/contrast-frames": {
+    reports: {
+      tree: aidc(formalWith(5, "It reads the word, not the operation.")),
+      file: TEX_FILE,
+      severity: 1,
+      line: 3,
+    },
+    silent: aidc(LINKED),
+  },
+  "tex/claim-emphasis": {
+    reports: {
+      tree: aidc(
+        formalWith(6, "We find that \\textbf{the rule counts 46 sentences}."),
+      ),
+      file: TEX_FILE,
+      severity: 1,
+      line: 3,
+    },
+    silent: aidc(LINKED),
+  },
+  "tex/relation-markers": {
+    reports: { tree: aidc(FORMAL), file: TEX_FILE, severity: 1, line: 3 },
+    silent: aidc(LINKED),
+  },
   "bib/reachable-entry": {
     reports: {
       tree: paper(inlineBib("@book{a,\n  title = {A},\n  year = {2026}\n}")),
@@ -381,16 +426,31 @@ const CASES: Readonly<Record<string, RuleCases>> = {
     reports: onPdf(built({ page_w_in: 8.264 })),
     silent: built(),
   },
-  "pdf/limits": {
+  "format/page-limit": {
     reports: onPdf(
       built({ body_pages: 9, pages_by_type: { body: 9, bib: 2 } }),
     ),
     silent: built(),
   },
   "pdf/body-size": {
-    reports: { ...onPdf(built({ body_pt: 12 })), severity: 1 },
+    reports: onPdf(built({ body_pt: 12 })),
     silent: built(),
   },
+  "anonymity/identity": {
+    reports: onPdf(
+      built({ pages_text: ["Ada Example\n", "References\n"] }, BLIND),
+    ),
+    silent: built({ pages_text: ["Anonymous\n", "References\n"] }, BLIND),
+  },
+  "format/layout-override": {
+    reports: {
+      tree: aidc("\\linespread{0.9}Text."),
+      file: TEX_FILE,
+      severity: 2,
+      line: 4,
+    },
+    silent: aidc("\\vspace{-2mm}Text."),
+  },
   "pdf/last-page-balance": {
     reports: onPdf(
       built(
@@ -472,23 +532,39 @@ describe("every registered rule has cases, and every case names a registered rul
   });
 });
 
+/**
+ * A case lints its tree through the whole CLI: a body long enough for a rate to be judged (2 000
+ * words and more) takes seconds under coverage, on a machine running every suite at once.
+ */
+const CASE_TIMEOUT_MS = 30_000;
+
 describe.each(Object.entries(CASES))("%s, through real ESLint", (id, c) => {
-  it(`reports on ${c.reports.file}:${String(c.reports.line)} at severity ${String(c.reports.severity)}`, async () => {
-    const got = (await lintTree(c.reports.tree)).filter((m) => m.ruleId === id);
-    expect(
-      got.some(
-        (m) =>
-          m.file === c.reports.file &&
-          m.line === c.reports.line &&
-          m.severity === c.reports.severity,
-      ),
-      JSON.stringify(got),
-    ).toBe(true);
-  });
+  it(
+    `reports on ${c.reports.file}:${String(c.reports.line)} at severity ${String(c.reports.severity)}`,
+    { timeout: CASE_TIMEOUT_MS },
+    async () => {
+      const got = (await lintTree(c.reports.tree)).filter(
+        (m) => m.ruleId === id,
+      );
+      expect(
+        got.some(
+          (m) =>
+            m.file === c.reports.file &&
+            m.line === c.reports.line &&
+            m.severity === c.reports.severity,
+        ),
+        JSON.stringify(got),
+      ).toBe(true);
+    },
+  );
 
-  it("stays silent on a conforming paper", async () => {
-    expect((await lintTree(c.silent)).filter((m) => m.ruleId === id)).toEqual(
-      [],
-    );
-  });
+  it(
+    "stays silent on a conforming paper",
+    { timeout: CASE_TIMEOUT_MS },
+    async () => {
+      expect((await lintTree(c.silent)).filter((m) => m.ruleId === id)).toEqual(
+        [],
+      );
+    },
+  );
 });

package/src/rule-docs.test.ts

@@ -29,12 +29,10 @@ const AWAITING_PAGE: ReadonlySet<string> = new Set([
   "paper/section-word",
   "paper/source",
   "paper/stages",
-  "pdf/body-size",
   "pdf/fonts",
   "pdf/fresh",
   "pdf/geometry",
   "pdf/last-page-balance",
-  "pdf/limits",
   "pdf/measured",
   "pdf/profile",
   "review/frontmatter",