paperlint 4.0.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),
+          ),
+        );
+      },
+    };
+  },
+});