paperlint 5.0.0 → 6.1.0

package/src/pdf-facts.ts

@@ -34,6 +34,15 @@ import {
 import type { PageLayout, TextBox } from "./domain/page-layout.ts";
 // eslint-disable-next-line boundaries/dependencies -- legacy layer, moves behind a port in #76
 import { fillsFor, isUpright } from "./adapters/pdfjs/fill.ts";
+import {
+  appendixOutlineDests,
+  linkTargetsOf,
+  metadataOf,
+  namedRefs,
+  pageTextOf,
+  refOf,
+  xmpOf,
+} from "./pdf-content.ts";
 import { messageOf } from "./domain/text.ts";
 import { fieldOf, isRecord, numbersOf } from "./domain/record.ts";
 
@@ -83,12 +92,27 @@ interface Page {
     [Symbol.iterator](): Iterator<readonly unknown[]>;
   };
   getViewport(params: { scale: number }): Viewport;
+  /** pdf.js's annotations; the link ones carry `url`. */
+  getAnnotations(): Promise<readonly unknown[]>;
 }
 
 /** A document as this module reads it; pdf.js's `PDFDocumentProxy` is one. */
 interface Doc {
   readonly numPages: number;
   getPage(pageNumber: number): Promise<Page>;
+  /** The Info dictionary, and the XMP packet when there is one. */
+  getMetadata(): Promise<{
+    readonly info: unknown;
+    readonly metadata: Iterable<unknown> | null;
+  }>;
+  /** Every named destination: name → explicit destination. */
+  getDestinations(): Promise<unknown>;
+  /** The 0-based index of the page a destination's reference names. */
+  getPageIndex(ref: object): Promise<number>;
+  /** One named destination, or null. */
+  getDestination(id: string): Promise<unknown>;
+  /** The bookmarks: `{ title, dest, items }`, or null. */
+  getOutline(): Promise<unknown>;
 }
 
 /** A viewport point, which pdf.js types as `any[]`: the two numbers it holds. */
@@ -106,6 +130,22 @@ export interface PdfFacts {
   readonly fonts: Fonts;
   readonly last: PageText;
   readonly layout: readonly PageLayout[];
+  /** Each page's text, in content order, a line break after each line (`pageTextOf`). */
+  readonly pageTexts: readonly string[];
+  /** The target of every link, with its 1-based page. */
+  readonly links: readonly PdfLink[];
+  /** The 1-based page of the first bibliography entry hyperref anchored, or null without one. */
+  readonly bibAnchorPage: number | null;
+  /** The 1-based page the appendix starts on, from hyperref's destinations and bookmarks, or null. */
+  readonly appendixAnchorPage: number | null;
+  /** The Info dictionary and XMP packet, flat (`metadataOf`). */
+  readonly metadata: Readonly<Record<string, string>>;
+}
+
+/** A link annotation's target, and the page it is on. */
+export interface PdfLink {
+  readonly page: number;
+  readonly uri: string;
 }
 
 export type PdfReadFailure =
@@ -198,10 +238,17 @@ async function readPage(
   page: Page,
   seen: ReadonlySet<string>,
   lib: PdfJs,
-): Promise<{ raw: RawPage; items: TextItem[]; layout: PageLayout }> {
+): Promise<{
+  raw: RawPage;
+  items: TextItem[];
+  layout: PageLayout;
+  text: string;
+  links: readonly string[];
+}> {
   // The operator list is what makes pdf.js load a page's fonts into `commonObjs`.
   const ops = await page.getOperatorList();
-  const items = (await page.getTextContent()).items.filter(isText);
+  const all = (await page.getTextContent()).items;
+  const items = all.filter(isText);
   const loaded = loadedFonts(page);
   const named = new Set(items.map((it) => it.fontName));
   const fonts = [...loaded.values()].filter(
@@ -211,6 +258,8 @@ async function readPage(
     raw: { hasText: items.length > 0, fonts },
     items,
     layout: layoutOf(page, items, ops, lib),
+    text: pageTextOf(all),
+    links: linkTargetsOf(await page.getAnnotations()),
   };
 }
 
@@ -310,12 +359,7 @@ function layoutOf(
  * transform, no pages) — `readPdf` below is the one production caller.
  */
 export async function factsOf(doc: Doc, lib: PdfJs): Promise<PdfRead> {
-  const read: {
-    page: Page;
-    raw: RawPage;
-    items: TextItem[];
-    layout: PageLayout;
-  }[] = [];
+  const read: (Awaited<ReturnType<typeof readPage>> & { page: Page })[] = [];
   const seen = new Set<string>();
   for (let i = 1; i <= doc.numPages; i++) {
     const page = await doc.getPage(i);
@@ -340,10 +384,64 @@ export async function factsOf(doc: Doc, lib: PdfJs): Promise<PdfRead> {
       fonts,
       last: pageText(last.page, last.items),
       layout: read.map((r) => r.layout),
+      ...saidOf(read, await doc.getMetadata()),
+      ...(await anchorsOf(doc)),
     },
   };
 }
 
+/**
+ * Where hyperref anchored the bibliography's first entry (the lowest page of a `cite.<key>`
+ * destination) and the appendix (the lowest page of an `appendix.<letter>` destination or of a
+ * bookmark titled «Appendix…»). A reference pdf.js cannot place is skipped.
+ */
+async function anchorsOf(
+  doc: Doc,
+): Promise<Pick<PdfFacts, "bibAnchorPage" | "appendixAnchorPage">> {
+  const destinations = await doc.getDestinations();
+  const bookmarked = await Promise.all(
+    appendixOutlineDests(await doc.getOutline()).map(async (d) =>
+      refOf(typeof d === "string" ? await doc.getDestination(d) : d),
+    ),
+  );
+  return {
+    bibAnchorPage: await lowestPage(doc, namedRefs(destinations, "cite.")),
+    appendixAnchorPage: await lowestPage(doc, [
+      ...namedRefs(destinations, "appendix."),
+      ...bookmarked.filter((r): r is object => r !== null),
+    ]),
+  };
+}
+
+/** The lowest 1-based page any of `refs` names, or null when none can be placed. */
+async function lowestPage(
+  doc: Doc,
+  refs: readonly object[],
+): Promise<number | null> {
+  const pages = await Promise.all(
+    refs.map((r) =>
+      doc.getPageIndex(r).then(
+        (i) => [i + 1],
+        () => [],
+      ),
+    ),
+  );
+  const found = pages.flat();
+  return found.length === 0 ? null : Math.min(...found);
+}
+
+/** What the pages say, from each page's read, and the document's metadata. */
+function saidOf(
+  read: readonly Pick<Awaited<ReturnType<typeof readPage>>, "text" | "links">[],
+  meta: Awaited<ReturnType<Doc["getMetadata"]>>,
+): Pick<PdfFacts, "pageTexts" | "links" | "metadata"> {
+  return {
+    pageTexts: read.map((r) => r.text),
+    links: read.flatMap((r, i) => r.links.map((uri) => ({ page: i + 1, uri }))),
+    metadata: metadataOf(meta.info, xmpOf(meta.metadata)),
+  };
+}
+
 /** pdf.js's own exception names for the two conditions a caller can act on. */
 export function failureOf(e: unknown): PdfRead {
   const name = fieldOf(e, "name");

package/src/ports/latex.ts

@@ -6,6 +6,8 @@ import type { Include } from "../domain/paper-source.ts";
 import type {
   ClassLine,
   DocumentClass,
+  Emphasis,
+  LayoutOverride,
   Outline,
   Passage,
   Span,
@@ -25,6 +27,11 @@ export interface LatexReader {
    * code or the title block. Citations, links and cross-references stay in place as marks.
    */
   readonly bodyProse: (src: string) => readonly Passage[];
+  /**
+   * The phrases set in bold, italics or underline inside that same prose, in document order — never
+   * a heading, a run-in heading (`\textbf{Threats.} …`), a caption, a float or a table.
+   */
+  readonly bodyEmphasis: (src: string) => readonly Emphasis[];
   /** Every `\input`, `\include` and `\subfile`, in source order: the path as written, where it stands. */
   readonly includes: (src: string) => readonly Include[];
   /** The span of the `document` environment's body, or null when the source has none. */
@@ -39,4 +46,6 @@ export interface LatexReader {
    * option `want` names (the author's own options stay), or it has none.
    */
   readonly withDocumentClass: (src: string, want: DocumentClass) => string;
+  /** Every command that changes the page layout the class sets: margins, text block, line spacing. */
+  readonly layoutOverrides: (src: string) => readonly LayoutOverride[];
 }

package/src/presets.ts

@@ -19,7 +19,7 @@
  *   tex        union — a child never removes a package its parent needs
  *   format     per key, the child wins; `kinds` by kind name, a child's kind replaces that kind
  *   rules      per rule id, the child wins
- *   template   the child wins; so does `name`, and `required_sections` (the whole list)
+ *   template   the child wins; so does `name`, and `required_sections` and `register` (each whole)
  *   aliases    union, with every `name` — what the venue is called along the chain
  *
  * ── THE LABEL ─────────────────────────────────────────────────────────────────────
@@ -51,6 +51,7 @@ import {
 } from "./paper-settings.ts";
 import { CONFIG_FILE } from "#lib/paper-config";
 import { messageOf } from "./domain/text.ts";
+import type { RegisterAnchor } from "./domain/register.ts";
 
 /** The prefix of a shipped preset's spec. */
 export const SHIPPED_PREFIX = "paperlint:";
@@ -83,10 +84,14 @@ export interface Preset {
   readonly template: PresetTemplate | null;
   /** Every `name` and `aliases` along the chain: what this venue is called in a paper's text. */
   readonly aliases: readonly string[];
+  /** Whether the venue reviews double-blind (`anonymity/identity`); false when no file of the chain says. */
+  readonly blind: boolean;
   readonly requiredSections: readonly RequiredSection[];
   readonly tex: TexRequirements;
   readonly format: VenueFormat;
   readonly rules: Readonly<Record<string, unknown>>;
+  /** The accepted papers the register rules measure a body against; empty when no file names any. */
+  readonly registerAnchors: readonly RegisterAnchor[];
 }
 
 /** Why a spec does not resolve. */
@@ -196,6 +201,7 @@ export function mergeFormat(
     refPtMax: pick("refPtMax"),
     fontsText: pick("fontsText"),
     fontsTitle: pick("fontsTitle"),
+    bodyEndsAt: pick("bodyEndsAt"),
     kinds: new Map([...parent.kinds, ...child.kinds]),
   };
 }
@@ -205,22 +211,18 @@ function merged(
   spec: string,
   rootFirst: readonly { readonly preset: PresetFile; readonly file: string }[],
 ): Preset {
-  const base: {
-    name: string | null;
-    template: PresetTemplate | null;
-    aliases: readonly string[];
-    requiredSections: readonly RequiredSection[];
-    tex: TexRequirements;
-    format: VenueFormat;
-    rules: Readonly<Record<string, unknown>>;
+  const base: Omit<Preset, "label" | "chain"> & {
+    readonly name: string | null;
   } = {
     name: null,
     template: null,
     aliases: [],
+    blind: false,
     requiredSections: [],
     tex: NO_REQUIREMENTS,
     format: NO_FORMAT,
     rules: {},
+    registerAnchors: [],
   };
   const m = rootFirst.reduce(
     (acc, { preset: p, file }) => ({
@@ -233,10 +235,12 @@ function merged(
           ...p.aliases,
         ]),
       ],
+      blind: p.blind ?? acc.blind,
       requiredSections: p.requiredSections ?? acc.requiredSections,
       tex: p.tex ? mergeRequirements(acc.tex, p.tex) : acc.tex,
       format: mergeFormat(acc.format, p.format),
       rules: { ...acc.rules, ...p.rules },
+      registerAnchors: p.registerAnchors ?? acc.registerAnchors,
     }),
     base,
   );
@@ -245,10 +249,12 @@ function merged(
     chain: rootFirst.map((x) => x.file),
     template: m.template,
     aliases: m.aliases,
+    blind: m.blind,
     requiredSections: m.requiredSections,
     tex: m.tex,
     format: m.format,
     rules: m.rules,
+    registerAnchors: m.registerAnchors,
   };
 }
 

package/src/register-bands.test.ts

@@ -0,0 +1,327 @@
+/**
+ * The register band rules on REAL papers — the accepted ones in `fixtures/accepted-papers/`, and
+ * variants derived from their sources, one change each:
+ *
+ * - every anchor the AIDC preset records is re-measured from its fixture and must equal the preset's
+ *   numbers, so a counter cannot change without the anchors (and so the band) changing with it;
+ * - every accepted ACSAC paper stands inside AIDC's band on every measure — a rule that fires on a
+ *   paper the venue accepted is wrong about the venue;
+ * - a variant that adds contrast frames, sets numbers in bold, or strips the relation markers from
+ *   one of those papers leaves the band on exactly that measure.
+ *
+ * `judgeBand` itself, on constructed measures: both ends, the floor of words, and what it reports.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { latexReader } from "./adapters/latex/index.ts";
+import { nodeFiles } from "./adapters/node/index.ts";
+import {
+  bandOf,
+  rateOf,
+  REGISTER_MEASURES,
+  type Band,
+  type RegisterAnchor,
+  type RegisterMeasureName,
+} from "./domain/register.ts";
+import { presetsDir } from "./package-dirs.ts";
+import { resolvePreset } from "./presets.ts";
+import { MIN_WORDS } from "./register.ts";
+import {
+  anchorOf,
+  judgeBand,
+  measureBody,
+  registerBandRules,
+  standingOf,
+} from "./register-bands.ts";
+import { readPaper } from "./tex-paper.ts";
+import { useTempDir, writeTree } from "../test/support.ts";
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const CORPUS = join(ROOT, "fixtures", "accepted-papers");
+
+/** The AIDC preset, resolved as a paper extending it would resolve it. */
+const aidc = (() => {
+  const r = resolvePreset(
+    "paperlint:aidc",
+    join(ROOT, "papers", "p", "paperlint.json"),
+    { files: nodeFiles, venuesDir: presetsDir() },
+  );
+  if (!r.ok) throw new Error(JSON.stringify(r.error));
+  return r.value;
+})();
+
+/** A fixture paper's text, its includes spliced, as the rules read it. */
+const sourceOf = (paper: string): string => {
+  const file = join(CORPUS, paper, "paper.tex");
+  return readPaper(file, readFileSync(file, "utf8"), {
+    files: nodeFiles,
+    latex: latexReader,
+  }).text;
+};
+
+const measured = new Map<string, RegisterAnchor>();
+/** A fixture paper measured the way an anchor is (cached: each parse costs a second). */
+const anchorFor = (paper: string, src = sourceOf(paper)): RegisterAnchor => {
+  const key = `${paper}\n${src}`;
+  const hit = measured.get(key);
+  if (hit) return hit;
+  const a = anchorOf(paper, src, latexReader);
+  measured.set(key, a);
+  return a;
+};
+
+/** Where each measure of a paper stands against AIDC's band. */
+const standings = (
+  a: RegisterAnchor,
+): Readonly<Record<RegisterMeasureName, string>> => {
+  const at = (m: RegisterMeasureName): string => {
+    const band = bandOf(aidc.registerAnchors, m);
+    return band === null
+      ? "no band"
+      : standingOf(rateOf(a.counts[m], a.words), band);
+  };
+  return {
+    contrast_frames: at("contrast_frames"),
+    claim_emphasis: at("claim_emphasis"),
+    relation_markers: at("relation_markers"),
+  };
+};
+
+const WITHIN = {
+  contrast_frames: "within",
+  claim_emphasis: "within",
+  relation_markers: "within",
+};
+
+const ACSAC = readdirSync(CORPUS).filter((d) => /acsac\d\d$/u.test(d));
+
+/** Parsing a real paper takes a second or more, several under coverage with every suite running. */
+const PAPER_TIMEOUT_MS = 60_000;
+
+describe("AIDC's anchors are the accepted ACSAC papers, as the counters measure them today", () => {
+  it("🔴 the preset records every ACSAC paper of the corpus, and nothing else", () => {
+    expect(aidc.registerAnchors.map((a) => a.paper).sort()).toEqual(
+      [...ACSAC].sort(),
+    );
+  });
+
+  it.each(aidc.registerAnchors.map((a) => [a.paper, a] as const))(
+    "🔴 %s: words and every count equal the fixture's, re-measured",
+    { timeout: PAPER_TIMEOUT_MS },
+    (paper, recorded) => {
+      expect(anchorFor(paper)).toEqual(recorded);
+    },
+  );
+});
+
+describe("every accepted ACSAC paper stands inside AIDC's band on every measure", () => {
+  it.each(ACSAC)("%s", { timeout: PAPER_TIMEOUT_MS }, (paper) => {
+    expect(standings(anchorFor(paper))).toEqual(WITHIN);
+  });
+});
+
+/** `src` with the first `n` matches of `re` after `\begin{document}` rewritten by `to`. */
+function inBody(
+  src: string,
+  re: RegExp,
+  to: (match: string) => string,
+  n: number,
+): string {
+  const start = src.indexOf("\\begin{document}");
+  const matches = new Set(
+    [...src.slice(start).matchAll(re)].slice(0, n).map((m) => m.index + start),
+  );
+  return src.replace(re, (m: string, ...rest: readonly unknown[]) => {
+    const at = rest.find((x) => typeof x === "number");
+    return typeof at === "number" && matches.has(at) ? to(m) : m;
+  });
+}
+
+/** The markers `tex/relation-markers` counts, as a writer who leaves the relation to the reader drops them. */
+const ADVERBIAL =
+  /\b(?:however|therefore|thus|hence|consequently|as a result|in contrast|specifically|for example|for instance|in particular),\s*/giu;
+
+describe("variants of real accepted papers, one change each, leave the band on that measure only", () => {
+  it(
+    "🔴 secure-acsac24 with a contrast frame after 20 mentions of the model: contrast frames above",
+    { timeout: PAPER_TIMEOUT_MS },
+    () => {
+      const src = inBody(
+        sourceOf("secure-acsac24"),
+        /\bthe model\b/gu,
+        () => "the model, not the prompt",
+        20,
+      );
+      expect(standings(anchorFor("secure-acsac24", src))).toEqual({
+        ...WITHIN,
+        contrast_frames: "above",
+      });
+    },
+  );
+
+  it(
+    "🔴 llm-splained-acsac25 with its first 20 percentages set in bold: claims in bold above",
+    { timeout: PAPER_TIMEOUT_MS },
+    () => {
+      const src = inBody(
+        sourceOf("llm-splained-acsac25"),
+        /\b\d+(?:\.\d+)?\\%/gu,
+        (m) => `\\textbf{${m}}`,
+        20,
+      );
+      expect(standings(anchorFor("llm-splained-acsac25", src))).toEqual({
+        ...WITHIN,
+        claim_emphasis: "above",
+      });
+    },
+  );
+
+  it(
+    "🔴 rr-dataset-quality-acsac24 with its relations left to the reader: relation markers below",
+    { timeout: PAPER_TIMEOUT_MS },
+    () => {
+      // One change: the sentence adverbials that name a relation are dropped, and «because» becomes
+      // «as» — the same claims, the relation between them no longer named.
+      const dropped = inBody(
+        sourceOf("rr-dataset-quality-acsac24"),
+        ADVERBIAL,
+        () => "",
+        Number.POSITIVE_INFINITY,
+      );
+      const src = inBody(
+        dropped,
+        /\bbecause\b/gu,
+        () => "as",
+        Number.POSITIVE_INFINITY,
+      );
+      expect(standings(anchorFor("rr-dataset-quality-acsac24", src))).toEqual({
+        ...WITHIN,
+        relation_markers: "below",
+      });
+    },
+  );
+});
+
+describe("judgeBand — a body's rate against a band", () => {
+  const band: Band = {
+    min: 20,
+    max: 10_000 * (5 / MIN_WORDS),
+    anchorMin: 30,
+    anchorMax: 20,
+    anchors: 5,
+  };
+  const occurrence = (i: number) => ({
+    match: `m${String(i)}`,
+    sentence: `s${String(i)}`,
+    at: { start: i, end: i + 1 },
+  });
+  const body = (n: number, words = MIN_WORDS) => ({
+    words,
+    occurrences: Array.from({ length: n }, (_, i) => occurrence(i)),
+    at: { start: 0, end: 1 },
+  });
+  const ids = (n: number, each = true, words = MIN_WORDS) =>
+    judgeBand(body(n, words), band, "aidc", each).map((f) => f.messageId);
+
+  it("inside the band, including its edges, nothing", () => {
+    expect(ids(5)).toEqual([]);
+    expect(ids(4)).toEqual([]);
+  });
+
+  it("🔴 above it: one finding for the body, then one at every occurrence", () => {
+    expect(ids(6)).toEqual([
+      "above",
+      ...Array.from({ length: 6 }, () => "each"),
+    ]);
+    expect(ids(6, false)).toEqual(["above"]);
+  });
+
+  it("🔴 below it: one finding for the body, never one per occurrence", () => {
+    expect(ids(3)).toEqual(["below"]);
+  });
+
+  it("under the floor of words, or without a band, nothing", () => {
+    expect(ids(1, true, MIN_WORDS - 1)).toEqual([]);
+    expect(judgeBand(body(99), null, "aidc", true)).toEqual([]);
+  });
+
+  it("the finding names the count, the rate, the band, the anchors' range and the first examples", () => {
+    const [f] = judgeBand(body(6), band, "aidc", true);
+    expect(f?.data).toMatchObject({
+      count: 6,
+      rate: "30.0",
+      min: "20.0",
+      max: "25.0",
+      anchors: 5,
+      venue: "aidc",
+      examples: "«s0», «s1», «s2»",
+    });
+  });
+});
+
+describe("the measures a preset may set a band for", () => {
+  it("each of them is recorded for every anchor", () => {
+    aidc.registerAnchors.forEach((a) => {
+      expect(Object.keys(a.counts).sort()).toEqual(
+        [...REGISTER_MEASURES].sort(),
+      );
+    });
+  });
+});
+
+describe("the rules, as ESLint calls them", () => {
+  /** A paper directory extending `extends`, and what one rule reports on its paper.tex. */
+  const reported = (
+    rule: "contrast-frames" | "claim-emphasis" | "relation-markers",
+    src: string,
+    file = "paper.tex",
+  ): string[] => {
+    const dir = writeTree(useTempDir("paperlint-register-bands-"), {
+      "paperlint.json": JSON.stringify({ extends: "paperlint:aidc" }),
+    });
+    const seen: string[] = [];
+    const deps = {
+      files: nodeFiles,
+      venuesDir: presetsDir(),
+      latex: latexReader,
+    };
+    registerBandRules(deps)
+      [rule].create({
+        filename: join(dir, file),
+        // No `raw`: the rule falls back to the text ESLint gives every language.
+        sourceCode: {
+          text: src,
+          getLocFromIndex: () => ({ line: 1, column: 0 }),
+        },
+        report: (d) => {
+          seen.push("messageId" in d ? d.messageId : d.message);
+        },
+      })
+      .root?.();
+    return seen;
+  };
+  const LONG = `\\documentclass{article}\n\\begin{document}\n${Array.from(
+    { length: 200 },
+    () =>
+      "The rule reads the body of the paper and counts every sentence it holds.",
+  ).join(" ")}\n\\end{document}\n`;
+
+  it("🔴 reads the paper's text when the language gives no raw source", () => {
+    expect(reported("relation-markers", LONG)).toEqual(["below"]);
+  });
+
+  it("judges a paper once, on its paper.tex, and nothing else", () => {
+    expect(reported("relation-markers", LONG, "intro.tex")).toEqual([]);
+  });
+
+  it("an empty body is measured as no words, reported nowhere", () => {
+    const m = measureBody(
+      "contrast-frames",
+      "\\documentclass{article}\n\\begin{document}\n\\end{document}\n",
+      latexReader,
+    );
+    expect(m).toEqual({ words: 0, occurrences: [], at: null });
+  });
+});