paperlint 4.2.0 → 6.0.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,7 @@ import type { Include } from "../domain/paper-source.ts";
 import type {
   ClassLine,
   DocumentClass,
+  LayoutOverride,
   Outline,
   Passage,
   Span,
@@ -39,4 +40,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

@@ -83,6 +83,8 @@ 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;
@@ -196,6 +198,7 @@ export function mergeFormat(
     refPtMax: pick("refPtMax"),
     fontsText: pick("fontsText"),
     fontsTitle: pick("fontsTitle"),
+    bodyEndsAt: pick("bodyEndsAt"),
     kinds: new Map([...parent.kinds, ...child.kinds]),
   };
 }
@@ -205,18 +208,13 @@ 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,
@@ -233,6 +231,7 @@ 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),
@@ -245,6 +244,7 @@ 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,

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",
@@ -186,25 +197,6 @@ const CASES: Readonly<Record<string, RuleCases>> = {
     },
     silent: paper(tex("x")),
   },
-  "paper/research-question": {
-    reports: {
-      tree: {
-        [STATUS_FILE]: fixture(
-          "paper-research-question/shipped-no-rq/PIPELINE-STATUS.md",
-        ),
-        [TEX_FILE]: fixture("paper-research-question/shipped-no-rq/paper.tex"),
-      },
-      file: TEX_FILE,
-      severity: 1,
-      line: 1,
-    },
-    silent: {
-      [STATUS_FILE]: fixture(
-        "paper-research-question/shipped-with-rq/PIPELINE-STATUS.md",
-      ),
-      [TEX_FILE]: fixture("paper-research-question/shipped-with-rq/paper.tex"),
-    },
-  },
   "paper/section-word": {
     reports: {
       tree: paper(tex("As in §2.")),
@@ -365,17 +357,6 @@ const CASES: Readonly<Record<string, RuleCases>> = {
     },
     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}")),
@@ -411,16 +392,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(

package/src/rule-docs.test.ts

@@ -26,16 +26,13 @@ const AWAITING_PAGE: ReadonlySet<string> = new Set([
   "paper/leading-zero",
   "paper/refs-checked",
   "paper/refs-fresh",
-  "paper/research-question",
   "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",

package/src/rules-config.ts

@@ -64,6 +64,7 @@ export interface ConfigBlock {
   readonly languageOptions?: Readonly<Record<string, unknown>>;
   readonly linterOptions?: Readonly<Record<string, unknown>>;
   readonly rules?: Readonly<Record<string, unknown>>;
+  readonly settings?: Readonly<Record<string, unknown>>;
 }
 
 export type Parsed<T> =

package/src/structure.harness.ts

@@ -79,9 +79,7 @@ try {
   check(
     "and the message names the CONSEQUENCE, not a restatement of the condition",
     /are skipped/.test(at("no-scorecard")[0]?.message ?? "") &&
-      /stage, source and research-question checks/.test(
-        at("no-scorecard")[0]?.message ?? "",
-      ),
+      /stage and source checks/.test(at("no-scorecard")[0]?.message ?? ""),
   );
   check(
     "and the consequence names THIS directory by name",

package/src/structure.ts

@@ -122,7 +122,7 @@ export function checkStructure(
  */
 function whyMissingMatters(file: string, dirName: string): string {
   if (file === "PIPELINE-STATUS.md")
-    return `the stage, source and research-question checks are skipped for \`${dirName}\``;
+    return `the stage and source checks are skipped for \`${dirName}\``;
   return `declared as required by your \`structure\` configuration`;
 }
 

package/src/tex-paper.test.ts

@@ -1,81 +1,98 @@
 /**
- * `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.
+ * The reading every parse-tree rule shares (`readPaper`), the files of the paper's body that lint
+ * reads on their own (`bodyFiles`), and where a finding of the assembled text is reported
+ * (`reportInPaper`).
  */
 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";
+import { join } from "node:path";
+import { texInputsDir } from "./package-dirs.ts";
+import { bodyFiles, readPaper, reportInPaper } from "./tex-paper.ts";
 
-const doc = (body: string): string =>
-  `\\documentclass{article}\n\\begin{document}\n${body}\n\\end{document}\n`;
+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");
+  });
 
-/** 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,
+  it("an include the paper's directory lacks is found in paperlint's own inputs, as the build finds it", () => {
+    const p = readPaper("/p/paper.tex", "x\\input{guards}y", {
+      files: memoryFiles({ [join(texInputsDir(), "guards.tex")]: "G" }),
+      latex: latexReader,
+    });
+    expect({ text: p.text, missing: p.missing }).toEqual({
+      text: "xGy",
+      missing: [],
+    });
   });
-  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("the paper's directory comes first: its file wins over paperlint's of the same name", () => {
+    const p = readPaper("/p/paper.tex", "\\input{guards}", {
+      files: memoryFiles({
+        "/p/guards.tex": "mine",
+        [join(texInputsDir(), "guards.tex")]: "package",
+      }),
+      latex: latexReader,
+    });
+    expect(p.text).toBe("mine");
   });
+});
 
-  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" } },
-    ]);
+describe("bodyFiles — the files of the body lint reads on their own", () => {
+  const doc = (preamble: string, body: string): string =>
+    `\\documentclass{article}\n${preamble}\n\\begin{document}\n${body}\n\\end{document}\n`;
+  const files = (extra: Record<string, string> = {}) =>
+    memoryFiles({
+      "/p/macros.tex": "\\newcommand{\\x}{y}",
+      "/p/sections/a.tex": "A\n\\input{sections/b}\n",
+      "/p/sections/b.tex": "B",
+      [join(texInputsDir(), "guards.tex")]: "G",
+      ...extra,
+    });
+
+  it("every file an include in the document body brings in, nested ones too, by absolute path", () => {
+    expect(
+      bodyFiles("/p/paper.tex", doc("", "\\input{sections/a}"), {
+        files: files(),
+        latex: latexReader,
+      }),
+    ).toEqual({
+      files: ["/p/sections/a.tex", "/p/sections/b.tex"],
+      missing: [],
+    });
   });
 
-  it("silent when every include resolves, with `.tex` added or not", () => {
+  it("not a preamble include (macros), and not a file found only in paperlint's inputs", () => {
     expect(
-      run(doc("\\input{a}\\include{b.tex}"), {
-        "/p/a.tex": "A",
-        "/p/b.tex": "B",
+      bodyFiles(
+        "/p/paper.tex",
+        doc("\\input{macros}", "\\input{guards}\nText."),
+        { files: files(), latex: latexReader },
+      ),
+    ).toEqual({ files: [], missing: [] });
+  });
+
+  it("an include that resolves nowhere is named, with the file that wrote it", () => {
+    expect(
+      bodyFiles("/p/paper.tex", doc("", "\\input{gone}"), {
+        files: files(),
+        latex: latexReader,
       }),
-    ).toEqual([]);
+    ).toEqual({ files: [], missing: [{ file: "paper.tex", target: "gone" }] });
   });
-});
 
-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");
+  it("a main file with no document environment: every include is the body", () => {
+    expect(
+      bodyFiles("/p/paper.tex", "\\input{sections/b}", {
+        files: files(),
+        latex: latexReader,
+      }),
+    ).toEqual({ files: ["/p/sections/b.tex"], missing: [] });
   });
 });