paperlint 4.1.0 → 4.2.0

package/src/register.test.ts

@@ -0,0 +1,165 @@
+/**
+ * `tex/register` on real parses: sentences of the body opening with And, So, But, Nor, Or or Yet per
+ * 1000 words, reported once for the whole body when the rate runs above what accepted papers show.
+ * Both halves, what counts as a word and as a conjunction start, the floor under which a rate means
+ * nothing, and the option.
+ */
+import { describe, expect, it } from "vitest";
+import { latexReader } from "./adapters/latex/index.ts";
+import { memoryFiles } from "./adapters/memory/index.ts";
+import {
+  judgeRegister,
+  measureRegister,
+  MIN_WORDS,
+  registerRule,
+} from "./register.ts";
+
+const doc = (body: string): string =>
+  `\\documentclass{article}\n\\begin{document}\n${body}\n\\end{document}\n`;
+
+/** Fourteen words. */
+const PLAIN =
+  "The rule reads the body of the paper and counts every sentence it holds.";
+/** Thirteen words, opening with a conjunction. */
+const CONJ = "But the rule reads the body of the paper and counts each one.";
+
+/** A body of `plain` plain sentences and `conj` conjunction starts, in paragraphs. */
+const body = (plain: number, conj: number): string =>
+  [
+    ...Array.from({ length: plain }, () => PLAIN),
+    ...Array.from({ length: conj }, () => CONJ),
+  ]
+    .map((s, i) => (i % 10 === 9 ? `${s}\n\n` : `${s} `))
+    .join("");
+
+const measured = (src: string) =>
+  measureRegister(latexReader.bodyProse(doc(src)));
+
+describe("measureRegister — what the body is counted as", () => {
+  it("its words, and its sentences opening with a conjunction", () => {
+    expect(measured(`${PLAIN} ${CONJ} Yet it holds.`)).toMatchObject({
+      words: 14 + 13 + 3,
+      conjunctionStarts: 2,
+    });
+  });
+
+  it("a citation, a reference and math each read as a word", () => {
+    expect(
+      measured(
+        "We show a sample in Table~\\ref{t}. It follows~\\cite{k} with $n$ runs.",
+      ),
+    ).toMatchObject({ words: 7 + 6 });
+  });
+
+  it("🔴 a conjunction opens a sentence only as its first word and capitalised: a list item's «and», «Android», «Oracle» do not", () => {
+    expect(
+      measured(
+        "And it holds. Android ships it. Oracle runs it. Some sentences, and more.\n\\begin{itemize}\n\\item and the rest.\n\\end{itemize}",
+      ),
+    ).toMatchObject({ conjunctionStarts: 1 });
+  });
+
+  it("a sentence with no word in it — a stray mark, a lone full stop — adds nothing", () => {
+    expect(measured("\\cite{k}. . It holds here.")).toMatchObject({
+      words: 3,
+    });
+    expect(measured(". !")).toMatchObject({ words: 0 });
+    expect(measureRegister([])).toMatchObject({ words: 0, at: null });
+  });
+
+  it("the examples are the first three, as the reader sees them", () => {
+    expect(
+      measured(`${CONJ} So it goes. Or not. And again. Yet more.`).examples,
+    ).toEqual([
+      "But the rule reads the body of the paper and counts each one.",
+      "So it goes.",
+      "Or not.",
+    ]);
+  });
+});
+
+describe("judgeRegister — one finding when the rate runs above the limit", () => {
+  const judged = (src: string, limit?: number) =>
+    judgeRegister(measured(src), limit).map((f) => f.messageId);
+
+  it("a body like an accepted paper's is silent", () => {
+    // 200 × 14 + 13 = 2 813 words, 1 start: 0.36 per 1000.
+    expect(judged(body(200, 1))).toEqual([]);
+  });
+
+  it("🔴 conjunction starts above 0.8 per 1000 words are reported, once", () => {
+    // 200 × 14 + 3 × 13 = 2 839 words, 3 starts: 1.06 per 1000.
+    expect(judged(body(200, 3))).toEqual(["conjunctionStarts"]);
+  });
+
+  it("at the limit is not above it", () => {
+    expect(judged(body(200, 3), 1000 * (3 / (200 * 14 + 3 * 13)))).toEqual([]);
+  });
+
+  it("🔴 under the floor of words a rate means nothing, and nothing is reported", () => {
+    const tiny = "It holds here. But it holds.";
+    expect(measured(tiny).words).toBeLessThan(MIN_WORDS);
+    expect(judged(tiny)).toEqual([]);
+  });
+
+  it("the limit is an option: raised, the same body is silent; lowered, it reports", () => {
+    expect(judged(body(200, 3), 2)).toEqual([]);
+    expect(judged(body(200, 1), 0.2)).toEqual(["conjunctionStarts"]);
+  });
+
+  it("the finding carries the rate, the count, the limit and the examples", () => {
+    const [f] = judgeRegister(measured(body(200, 3)));
+    expect(f?.data).toMatchObject({
+      count: 3,
+      rate: "1.06",
+      limit: 0.8,
+      examples: `«${CONJ}», «${CONJ}», «${CONJ}»`,
+    });
+  });
+});
+
+describe("the rule — reported at the start of the body, the option read from the config", () => {
+  interface Seen {
+    readonly line: number;
+    readonly messageId: string;
+  }
+  const run = (src: string, options?: readonly unknown[]): Seen[] => {
+    const seen: Seen[] = [];
+    registerRule({ files: memoryFiles({}), latex: latexReader })
+      .create({
+        filename: "/p/paper.tex",
+        ...(options === undefined ? {} : { options }),
+        sourceCode: {
+          text: src,
+          getLocFromIndex: (i) => {
+            const line = src.slice(0, i).split("\n").length;
+            return { line, column: i - src.lastIndexOf("\n", i - 1) };
+          },
+        },
+        report: (d) => {
+          seen.push({
+            line: d.loc.start.line,
+            messageId: "messageId" in d ? d.messageId : d.message,
+          });
+        },
+      })
+      .root?.();
+    return seen;
+  };
+  const FOUND = { messageId: "conjunctionStarts" };
+
+  it("🔴 one finding, where the body's first sentence starts", () => {
+    expect(run(doc(body(200, 4)))).toEqual([{ line: 3, ...FOUND }]);
+  });
+
+  it("the option in the config changes the limit; an option object without it keeps the default", () => {
+    expect(run(doc(body(200, 4)), [{ conjunctionStartsPer1000: 2 }])).toEqual(
+      [],
+    );
+    expect(run(doc(body(200, 4)), [{}])).toEqual([{ line: 3, ...FOUND }]);
+  });
+
+  it("a body read without a document environment is reported at the top", () => {
+    expect(run(body(200, 4))).toEqual([{ line: 1, ...FOUND }]);
+  });
+});

package/src/register.ts

@@ -0,0 +1,177 @@
+/**
+ * `tex/register` — the body reads at the register of a paper, not of a post: sentences that open
+ * with a coordinating conjunction stay as rare as they are in accepted papers.
+ *
+ *   warn  more than 0.8 sentences per 1000 words of the body open with And, So, But, Nor, Or or Yet
+ *
+ * ── WHY ──────────────────────────────────────────────────────────────────────────
+ * Reviewers called our prose "too informal" and "a blogpost" twice. Measured against eleven accepted
+ * papers, sentence-initial conjunctions set our drafts apart (accepted 0–0.58 per 1000 words). The
+ * limit is an option; its default and the measurement behind it are on the rule's page.
+ *
+ * ── WHAT IT READS ────────────────────────────────────────────────────────────────
+ * The body's prose through the `LatexReader` port (`bodyProse`) — the parse tree of the whole paper,
+ * includes spliced — cut into sentences by the same splitter `tex/claim-provenance` uses
+ * (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 { readPaper, reportInPaper, type PaperDeps } from "./tex-paper.ts";
+import {
+  ruleDocsUrl,
+  type Located,
+  type TexRuleModule,
+} from "./tex-venue-rules.ts";
+
+/** Under this many words in the body, the rate is not judged. */
+export const MIN_WORDS = 2000;
+
+/** The limit when the config sets none, from the measurement on the rule's page. */
+export const DEFAULT_LIMIT = 0.8;
+
+/** The words that, opening a sentence, make it a conjunction start. Capitalised: only a first word. */
+const CONJUNCTIONS: ReadonlySet<string> = new Set([
+  "And",
+  "So",
+  "But",
+  "Nor",
+  "Or",
+  "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;
+  readonly conjunctionStarts: number;
+  /** The first three, as the reader sees them. */
+  readonly examples: readonly string[];
+  /** Where the body's first passage starts, for a finding about the whole body. */
+  readonly at: Span | null;
+}
+
+/** Where a passage's first piece stands. */
+function startOf(p: Passage): Span {
+  const first = p.pieces[0];
+  return first.kind === "text"
+    ? {
+        start: first.segment.at,
+        end: first.segment.at + first.segment.text.length,
+      }
+    : first.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 conj = all.filter((s) => CONJUNCTIONS.has(s.first));
+  const [first] = passages;
+  return {
+    words: all.reduce((n, s) => n + s.words, 0),
+    conjunctionStarts: conj.length,
+    examples: conj.slice(0, 3).map((s) => s.text),
+    at: first === undefined ? null : startOf(first),
+  };
+}
+
+/** One finding, at the start of the body, when the rate runs above `limit` per 1000 words. */
+export function judgeRegister(
+  m: RegisterMeasure,
+  limit: number = DEFAULT_LIMIT,
+): readonly Located[] {
+  if (m.words < MIN_WORDS) return [];
+  const rate = (1000 * m.conjunctionStarts) / m.words;
+  if (rate <= limit) return [];
+  const data = {
+    count: m.conjunctionStarts,
+    rate: rate.toFixed(2),
+    limit,
+    examples: m.examples.map((x) => `«${x}»`).join(", "),
+  };
+  return [{ messageId: "conjunctionStarts", data, at: m.at }];
+}
+
+/** The limit the config sets, or the default: ESLint has validated the option against the schema. */
+function limitOf(options: readonly unknown[] | undefined): number {
+  const [o] = options ?? [];
+  const given: Readonly<Record<string, unknown>> =
+    typeof o === "object" && o !== null
+      ? Object.fromEntries(Object.entries(o))
+      : {};
+  const v = given["conjunctionStartsPer1000"];
+  return typeof v === "number" ? v : DEFAULT_LIMIT;
+}
+
+const META: TexRuleModule["meta"] = {
+  type: "suggestion",
+  docs: {
+    description:
+      "the body reads at a paper's register: few sentences open with And, So, But, Nor, Or or Yet",
+    url: ruleDocsUrl("register"),
+  },
+  schema: [
+    {
+      type: "object",
+      properties: {
+        conjunctionStartsPer1000: { type: "number", minimum: 0 },
+      },
+      additionalProperties: false,
+    },
+  ],
+  messages: {
+    conjunctionStarts:
+      "{{count}} sentences open with And, So, But, Nor, Or or Yet — {{rate}} per 1000 words (first: {{examples}}). Accepted papers measured 0–0.58; this rule warns above {{limit}}. Join the sentence to the one before, or open with the connective a paper uses (However, Therefore, Moreover)",
+  },
+};
+
+/** The rule, over the body's prose of the whole paper, its includes spliced (`readPaper`). */
+export const registerRule = (deps: PaperDeps): TexRuleModule => ({
+  meta: META,
+  create(context) {
+    return {
+      root() {
+        const sc = context.sourceCode;
+        const paper = readPaper(context.filename, sc.raw ?? sc.text, deps);
+        reportInPaper(
+          context,
+          META.messages,
+          paper,
+          judgeRegister(
+            measureRegister(deps.latex.bodyProse(paper.text)),
+            limitOf(context.options),
+          ),
+        );
+      },
+    };
+  },
+});

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";
@@ -202,7 +212,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 +315,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 +343,39 @@ 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)),
+  },
+  "tex/missing-input": {
+    reports: {
+      tree: paper(tex("Text.\n\\input{sections/gone}")),
+      file: TEX_FILE,
+      severity: 1,
+      line: 4,
+    },
+    silent: paper(tex("Text.\n\\input{sections/here}"), {
+      [`${P}/sections/here.tex`]: "More text.\n",
+    }),
+  },
   "bib/reachable-entry": {
     reports: {
       tree: paper(inlineBib("@book{a,\n  title = {A},\n  year = {2026}\n}")),

package/src/tex-paper.test.ts

@@ -0,0 +1,131 @@
+/**
+ * `tex/missing-input` and the reading every parse-tree rule shares (`readPaper`): an include that
+ * names no file is reported where it stands in `paper.tex`, once, whether `paper.tex` wrote it or a
+ * file it includes did; an include that resolves says nothing.
+ */
+import { describe, expect, it } from "vitest";
+import { latexReader } from "./adapters/latex/index.ts";
+import { memoryFiles } from "./adapters/memory/index.ts";
+import { missingInputRule, readPaper, reportInPaper } from "./tex-paper.ts";
+
+const doc = (body: string): string =>
+  `\\documentclass{article}\n\\begin{document}\n${body}\n\\end{document}\n`;
+
+/** What the rule reports over `/p/paper.tex` holding `src`, with `files` on disk. */
+function run(src: string, files: Record<string, string> = {}) {
+  const out: { line: number; messageId: string; data: unknown }[] = [];
+  const rule = missingInputRule({
+    files: memoryFiles(files),
+    latex: latexReader,
+  });
+  rule
+    .create({
+      filename: "/p/paper.tex",
+      sourceCode: {
+        text: src,
+        getLocFromIndex: (i) => ({
+          line: src.slice(0, i).split("\n").length,
+          column: 0,
+        }),
+      },
+      report: (d) => {
+        if ("messageId" in d)
+          out.push({
+            line: d.loc.start.line,
+            messageId: d.messageId,
+            data: d.data,
+          });
+      },
+    })
+    .root?.();
+  return out;
+}
+
+describe("tex/missing-input", () => {
+  it("an \\input naming no file is reported at its line, naming the target", () => {
+    expect(run(doc("Text.\n\\input{sections/gone}"))).toEqual([
+      {
+        line: 4,
+        messageId: "missing",
+        data: { target: "sections/gone", file: "paper.tex" },
+      },
+    ]);
+  });
+
+  it("one missing in an included file is reported at the include that brought that file in", () => {
+    expect(run(doc("\\input{a}"), { "/p/a.tex": "A\n\\input{b}\n" })).toEqual([
+      { line: 3, messageId: "missingIn", data: { target: "b", file: "a.tex" } },
+    ]);
+  });
+
+  it("silent when every include resolves, with `.tex` added or not", () => {
+    expect(
+      run(doc("\\input{a}\\include{b.tex}"), {
+        "/p/a.tex": "A",
+        "/p/b.tex": "B",
+      }),
+    ).toEqual([]);
+  });
+});
+
+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");
+  });
+});
+
+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" },
+    ]);
+  });
+});