paperlint 5.0.0 → 6.0.0

package/src/facts-file.test.ts

@@ -82,14 +82,24 @@ const doc = (last: PageText, geometry: Geometry = NONE) =>
     sha: "a".repeat(64),
     venue: "agenticdev",
     kind: "short",
-    read: { pages: 4, fonts: FONTS, last, layout: [] },
+    read: {
+      pages: 4,
+      fonts: FONTS,
+      last,
+      layout: [],
+      pageTexts: [],
+      links: [],
+      bibAnchorPage: null,
+      appendixAnchorPage: null,
+      metadata: {},
+    },
     geometry,
   });
 
 // ── the document ────────────────────────────────────────────────────────────────────────
-test("schema 2; a measured last page gives both heights, in both fields", () => {
+test("schema 3; a measured last page gives both heights, in both fields", () => {
   const d = doc(lastPage(60, 30));
-  assert.equal(d.schema, 2);
+  assert.equal(d.schema, 3);
   assert.deepEqual(d.last_page, { kind: "measured", columns_pt: [600, 300] });
   assert.deepEqual(d.last_page_cols_pt, [600, 300]);
   assert.equal(d.npages, 4);
@@ -150,7 +160,17 @@ const PDF_BYTES = "%PDF-pretend";
 const good: PdfReader = () =>
   Promise.resolve({
     ok: true,
-    facts: { pages: 2, fonts: FONTS, last: lastPage(60, 60), layout: [] },
+    facts: {
+      pages: 2,
+      fonts: FONTS,
+      last: lastPage(60, 60),
+      layout: [],
+      pageTexts: [],
+      links: [],
+      bibAnchorPage: null,
+      appendixAnchorPage: null,
+      metadata: {},
+    },
   });
 /** The shipped presets at their real paths: `extends` resolves through the same Files port. */
 const SHIPPED_PRESETS = Object.fromEntries(
@@ -290,6 +310,11 @@ test("a PDF with no text has an empty font list, not a failed document", () => {
       fonts: { kind: "no-text" },
       last: lastPage(0, 0),
       layout: [],
+      pageTexts: [],
+      links: [],
+      bibAnchorPage: null,
+      appendixAnchorPage: null,
+      metadata: {},
     },
     geometry: NONE,
   });
@@ -387,3 +412,74 @@ test("parseFactsText: a missing schema is reported as null, another schema by it
   const other = parse({ ...written(), schema: 1 });
   assert.deepEqual(!other.ok && other.error, { kind: "schema", got: "1" });
 });
+
+test("schema 3: what the PDF says is written, and reads back typed", () => {
+  const said = {
+    ...written(),
+    pages_text: ["Ada Example\nIntroduction", "References"],
+    metadata: { Author: "Ada Example" },
+    links: [{ page: 1, uri: "https://github.com/adaexample" }],
+    bib_anchor_page: 2,
+    appendix_anchor_page: 3,
+  };
+  const r = parse(said);
+  assert.ok(r.ok);
+  assert.deepEqual(r.value.text, {
+    pages: ["Ada Example\nIntroduction", "References"],
+    metadata: { Author: "Ada Example" },
+    links: [{ page: 1, uri: "https://github.com/adaexample" }],
+    bibAnchorPage: 2,
+    appendixAnchorPage: 3,
+  });
+  const d = factsDocument({
+    pdf: "paper.pdf",
+    sha: "a".repeat(64),
+    venue: null,
+    kind: null,
+    read: {
+      pages: 1,
+      fonts: FONTS,
+      last: lastPage(1, 0),
+      layout: [],
+      pageTexts: ["x"],
+      links: [{ page: 1, uri: "u" }],
+      bibAnchorPage: 1,
+      appendixAnchorPage: null,
+      metadata: { Title: "t" },
+    },
+    geometry: MEASURED,
+  });
+  assert.deepEqual(
+    [
+      d.pages_text,
+      d.links,
+      d.bib_anchor_page,
+      d.appendix_anchor_page,
+      d.metadata,
+    ],
+    [["x"], [{ page: 1, uri: "u" }], 1, null, { Title: "t" }],
+  );
+});
+
+test("schema 3: a missing or malformed text field is refused, naming it", () => {
+  const noText = Object.fromEntries(
+    Object.entries(written()).filter(([k]) => k !== "pages_text"),
+  );
+  assert.equal(why(noText), "`pages_text` is not a list of strings");
+  assert.equal(
+    why({ ...written(), metadata: { Author: 3 } }),
+    "`metadata` is not an object of strings",
+  );
+  assert.equal(
+    why({ ...written(), links: [{ page: 0, uri: "u" }] }),
+    "`links` is not a list of { page, uri }",
+  );
+  assert.equal(
+    why({ ...written(), bib_anchor_page: 0 }),
+    "`bib_anchor_page` is neither a page number nor null",
+  );
+  assert.equal(
+    why({ ...written(), appendix_anchor_page: "3" }),
+    "`appendix_anchor_page` is neither a page number nor null",
+  );
+});

package/src/facts-file.ts

@@ -26,6 +26,14 @@
  * fonts are all named `Type3`; `embedded` means a usable program is present, so a corrupted one is
  * false. `pdf` is now relative to the PAPER directory, not to wherever the command ran.
  *
+ * ── SCHEMA 3 (2026-09-29) ───────────────────────────────────────────────────────
+ * Adds what the PDF SAYS, for the rules that judge text rather than geometry: `pages_text` (each
+ * page's text, in content order), `metadata` (the Info dictionary and the XMP packet, flat),
+ * `links` (every link annotation's target and page), `bib_anchor_page` and `appendix_anchor_page`
+ * (the pages hyperref anchored the bibliography's first entry and the appendix on, or null). Every schema-2 field keeps its name and meaning. The number moves anyway: `anonymity/identity` and `format/page-limit` read these fields,
+ * and schema-2 facts without them would be judged as a PDF that says nothing — a clean pass over no
+ * input. A schema-2 file is refused by `pdf/fresh` with "rebuild", which is one `paperlint build`.
+ *
  * 🔴 STALENESS. The PDF is not committed, so neither are these facts: they live in `_build/` and
  * carry `pdf_sha256`. A rule compares it with the PDF on disk and refuses facts about another build.
  */
@@ -52,7 +60,7 @@ import { paperPreset, paperPresetProblem } from "./presets.ts";
 import { presetsDir } from "./package-dirs.ts";
 import { messageOf } from "./domain/text.ts";
 
-export const FACTS_SCHEMA = 2;
+export const FACTS_SCHEMA = 3;
 export const FACTS_DIR = "_build";
 export const FACTS_FILE = "paper.facts.json";
 
@@ -123,7 +131,17 @@ export type FactsDocument = {
   readonly last_page: LastPageEntry;
   /** Schema 1's field, kept: the two heights, or null when the last page is a stub or a review build. */
   readonly last_page_cols_pt: readonly [number, number] | null;
-} & FactsGeometryFields;
+} & FactsTextFields &
+  FactsGeometryFields;
+
+/** Schema 3's fields: what the PDF says (see the module header). */
+export interface FactsTextFields {
+  readonly pages_text: readonly string[];
+  readonly metadata: Readonly<Record<string, string>>;
+  readonly links: readonly { readonly page: number; readonly uri: string }[];
+  readonly bib_anchor_page: number | null;
+  readonly appendix_anchor_page: number | null;
+}
 
 export function fontEntry(f: FontFact): FontEntry {
   return {
@@ -170,6 +188,11 @@ export function factsDocument(i: FactsInput): FactsDocument {
       i.read.fonts.kind === "drawn" ? i.read.fonts.list.map(fontEntry) : [],
     last_page: last,
     last_page_cols_pt: last.kind === "measured" ? last.columns_pt : null,
+    pages_text: i.read.pageTexts,
+    metadata: i.read.metadata,
+    links: i.read.links,
+    bib_anchor_page: i.read.bibAnchorPage,
+    appendix_anchor_page: i.read.appendixAnchorPage,
     ...flatGeometry(i.geometry),
   };
 }
@@ -249,6 +272,19 @@ export interface ReadFacts {
   readonly fonts: readonly FontEntry[];
   /** The geometry columns, or null when no measurer ran (`geometry_source` is null). */
   readonly geometry: FlatGeometry | null;
+  /** What the PDF says: schema 3's fields, parsed. */
+  readonly text: TextFacts;
+}
+
+/** Schema 3's fields as a rule reads them. */
+export interface TextFacts {
+  readonly pages: readonly string[];
+  readonly metadata: Readonly<Record<string, string>>;
+  readonly links: readonly { readonly page: number; readonly uri: string }[];
+  /** The page of the first bibliography entry hyperref anchored, or null. */
+  readonly bibAnchorPage: number | null;
+  /** The page hyperref anchored the appendix on, or null. */
+  readonly appendixAnchorPage: number | null;
 }
 
 /** Why a facts file cannot be judged. */
@@ -331,6 +367,56 @@ function geometryOf(
   });
 }
 
+const isPage = (v: unknown): v is number =>
+  typeof v === "number" && Number.isInteger(v) && v > 0;
+const isPageOrNull = (v: unknown): v is number | null =>
+  v === null || isPage(v);
+const isStrings = (v: unknown): v is readonly string[] =>
+  Array.isArray(v) && v.every((x) => typeof x === "string");
+const isStringRecord = (v: unknown): v is Readonly<Record<string, string>> =>
+  isRecord(v) && Object.values(v).every((x) => typeof x === "string");
+const isLinks = (
+  v: unknown,
+): v is readonly { readonly page: number; readonly uri: string }[] =>
+  Array.isArray(v) &&
+  v.every(
+    (l) => isRecord(l) && isPage(l["page"]) && typeof l["uri"] === "string",
+  );
+
+/** Schema 3's fields, or which one is wrong. */
+function textOf(
+  d: Readonly<Record<string, unknown>>,
+): Result<TextFacts, string> {
+  const { pages_text, metadata, links } = d;
+  const { bib_anchor_page, appendix_anchor_page } = d;
+  if (!isStrings(pages_text))
+    return err("`pages_text` is not a list of strings");
+  if (!isStringRecord(metadata))
+    return err("`metadata` is not an object of strings");
+  if (!isLinks(links)) return err("`links` is not a list of { page, uri }");
+  if (!isPageOrNull(bib_anchor_page))
+    return err("`bib_anchor_page` is neither a page number nor null");
+  if (!isPageOrNull(appendix_anchor_page))
+    return err("`appendix_anchor_page` is neither a page number nor null");
+  return ok({
+    pages: pages_text,
+    metadata,
+    links,
+    bibAnchorPage: bib_anchor_page,
+    appendixAnchorPage: appendix_anchor_page,
+  });
+}
+
+/** What the PDF measures and what it says: the geometry columns and schema 3's fields. */
+function contentOf(
+  d: Readonly<Record<string, unknown>>,
+): Result<Pick<ReadFacts, "geometry" | "text">, string> {
+  const geometry = geometryOf(d);
+  if (!geometry.ok) return geometry;
+  const text = textOf(d);
+  return text.ok ? ok({ geometry: geometry.value, text: text.value }) : text;
+}
+
 /** The PDF the facts describe: its path and its sha256. */
 function artifactOf(
   d: Readonly<Record<string, unknown>>,
@@ -368,11 +454,7 @@ export function parseFactsText(text: string): Result<ReadFacts, FactsProblem> {
       kind: "broken",
       why: "`fonts` is not a list of { name, type, embedded, program }",
     });
-  const geometry = geometryOf(d);
-  if (!geometry.ok) return err({ kind: "broken", why: geometry.error });
-  return ok({
-    ...artifact.value,
-    fonts,
-    geometry: geometry.value,
-  });
+  const content = contentOf(d);
+  if (!content.ok) return err({ kind: "broken", why: content.error });
+  return ok({ ...artifact.value, fonts, ...content.value });
 }

package/src/new-paper.test.ts

@@ -51,7 +51,13 @@ describe("paperlint new — paperlint.json", () => {
     expect(String(s["$comment"])).toMatch(/paperlint:agenticdev/);
     expect(parsePaperSettings(s)).toEqual({
       ok: true,
-      value: { extends: null, kind: null, pdf: null, rules: null },
+      value: {
+        extends: null,
+        kind: null,
+        pdf: null,
+        rules: null,
+        identity: null,
+      },
     });
   });
 

package/src/paper-settings.test.ts

@@ -30,18 +30,31 @@ describe("parsePaperSettings", () => {
         kind: "research",
         pdf: null,
         rules: null,
+        identity: null,
       },
     });
     expect(parsePaperSettings({})).toEqual({
       ok: true,
-      value: { extends: null, kind: null, pdf: null, rules: null },
+      value: {
+        extends: null,
+        kind: null,
+        pdf: null,
+        rules: null,
+        identity: null,
+      },
     });
   });
 
   it("extends: null is valid and means no venue chosen yet — what `paperlint new` writes", () => {
     expect(parsePaperSettings({ extends: null })).toEqual({
       ok: true,
-      value: { extends: null, kind: null, pdf: null, rules: null },
+      value: {
+        extends: null,
+        kind: null,
+        pdf: null,
+        rules: null,
+        identity: null,
+      },
     });
   });
 });
@@ -138,6 +151,9 @@ describe("readPaperSettings — a root paperlint.json that cannot be used", () =
   });
 });
 
+/** The fields a case does not set. */
+const UNSET = { pdf: null, rules: null, identity: null };
+
 describe("readPaperSettings — the root paperlint.json's defaults, the paper's file over them", () => {
   const ROOT = "/work";
   const withFiles = (f: Record<string, string>) =>
@@ -161,8 +177,7 @@ describe("readPaperSettings — the root paperlint.json's defaults, the paper's
     ).toEqual({
       extends: "paperlint:agenticdev",
       kind: "short",
-      pdf: null,
-      rules: null,
+      ...UNSET,
     });
   });
 
@@ -172,8 +187,7 @@ describe("readPaperSettings — the root paperlint.json's defaults, the paper's
     ).toEqual({
       extends: "paperlint:aisec",
       kind: null,
-      pdf: null,
-      rules: null,
+      ...UNSET,
     });
   });
 
@@ -191,6 +205,7 @@ describe("readPaperSettings — the root paperlint.json's defaults, the paper's
       pdf: null,
       // The root's rules are the project's blocks (cli.ts), not this paper's.
       rules: { "pdf/fonts": "off" },
+      identity: null,
     });
   });
 
@@ -232,6 +247,7 @@ describe("paperRules — `rules` in paperlint.json", () => {
     kind: null,
     pdf: null,
     rules,
+    identity: null,
   });
 
   it("no rules: none", () => {
@@ -267,3 +283,44 @@ describe("paperRules — `rules` in paperlint.json", () => {
     }
   });
 });
+
+describe("readPaperSettings — identity, at both levels", () => {
+  const ROOT = "/work";
+  const withFiles = (f: Record<string, string>) =>
+    memoryFiles({ [`${ROOT}/package.json`]: "{}", ...f });
+  const read = (f: Record<string, string>) => {
+    const r = readPaperSettings(withFiles(f), PAPER);
+    if (!r.ok) throw new Error(r.error.why);
+    return r.value;
+  };
+
+  it("identity: the root's list and the paper's, joined without repeats", () => {
+    expect(
+      read({
+        [`${ROOT}/paperlint.json`]: '{"identity":["Ada Example","adaexample"]}',
+        [`${PAPER}/paperlint.json`]:
+          '{"identity":["adaexample","Bob Coauthor"]}',
+      })?.identity,
+    ).toEqual(["Ada Example", "adaexample", "Bob Coauthor"]);
+    expect(
+      read({ [`${ROOT}/paperlint.json`]: '{"identity":["Ada Example"]}' })
+        ?.identity,
+    ).toEqual(["Ada Example"]);
+  });
+
+  it("identity of the wrong shape, at either level, is refused naming it", () => {
+    const why = (f: Record<string, string>) => {
+      const r = readPaperSettings(withFiles(f), PAPER);
+      return r.ok ? "" : r.error.why;
+    };
+    expect(why({ [`${PAPER}/paperlint.json`]: '{"identity":"Ada"}' })).toMatch(
+      /"identity" must be a list of strings/,
+    );
+    expect(why({ [`${PAPER}/paperlint.json`]: '{"identity":["  "]}' })).toMatch(
+      /"identity" must be a list of strings, each with a letter or digit/,
+    );
+    expect(why({ [`${ROOT}/paperlint.json`]: '{"identity":[3]}' })).toMatch(
+      /^the root paperlint\.json: "identity" must be/,
+    );
+  });
+});

package/src/paper-settings.ts

@@ -45,6 +45,12 @@ export interface PaperSettings {
    * against the shipped rules.
    */
   readonly rules: Readonly<Record<string, unknown>> | readonly unknown[] | null;
+  /**
+   * What identifies the authors — `anonymity/identity` requires a blind venue's PDF to say none of it.
+   * The root's list and the paper's own, joined: a paper adds its co-authors to the project's author
+   * and cannot drop them by accident. Null when neither declares one.
+   */
+  readonly identity: readonly string[] | null;
 }
 
 /** Why a paper's settings cannot be read. */
@@ -86,6 +92,23 @@ export function stringFields(
   });
 }
 
+/**
+ * `identity`: absent is null; otherwise a list of strings, each with a letter or digit in it — a
+ * blank entry would match nothing and read as a declared, clean identity.
+ */
+export function identityField(
+  d: Readonly<Record<string, unknown>>,
+): Result<readonly string[] | null, string> {
+  const v = d["identity"];
+  if (v === undefined) return ok(null);
+  return Array.isArray(v) &&
+    v.every((x) => typeof x === "string" && /[\p{L}\p{N}]/u.test(x))
+    ? ok(v.filter((x): x is string => typeof x === "string"))
+    : err(
+        `"identity" must be a list of strings, each with a letter or digit, got ${JSON.stringify(v)}`,
+      );
+}
+
 /** The parsed JSON of `paperlint.json` → the settings, or one line saying what is wrong. Pure. */
 export function parsePaperSettings(
   json: unknown,
@@ -103,6 +126,8 @@ export function parsePaperSettings(
     );
   const fields = stringFields(json);
   if (!fields.ok) return fields;
+  const identity = identityField(json);
+  if (!identity.ok) return identity;
   const rules = json["rules"];
   if (rules !== undefined && !isObject(rules) && !Array.isArray(rules))
     return err(
@@ -111,6 +136,7 @@ export function parsePaperSettings(
   return ok({
     ...fields.value,
     rules: rules ?? null,
+    identity: identity.value,
   });
 }
 
@@ -144,9 +170,18 @@ function rootDefaults(
   if (!json.ok) return json;
   if (!isObject(json.value)) return ok(null);
   const fields = stringFields(json.value);
-  return fields.ok
-    ? fields
-    : err({ kind: "broken", why: `the root ${CONFIG_FILE}: ${fields.error}` });
+  const identity = identityField(json.value);
+  if (!fields.ok)
+    return err({
+      kind: "broken",
+      why: `the root ${CONFIG_FILE}: ${fields.error}`,
+    });
+  return identity.ok
+    ? ok({ ...fields.value, identity: identity.value })
+    : err({
+        kind: "broken",
+        why: `the root ${CONFIG_FILE}: ${identity.error}`,
+      });
 }
 
 /**
@@ -167,8 +202,20 @@ export function readPaperSettings(
   return ok(merge(defaults.value, parsed.value));
 }
 
-type Defaults = Pick<PaperSettings, "extends" | "kind" | "pdf">;
-const NO_DEFAULTS: Defaults = { extends: null, kind: null, pdf: null };
+type Defaults = Pick<PaperSettings, "extends" | "kind" | "pdf" | "identity">;
+const NO_DEFAULTS: Defaults = {
+  extends: null,
+  kind: null,
+  pdf: null,
+  identity: null,
+};
+
+/** Both lists, joined without repeats; null when neither side has one. */
+const joined = (
+  a: readonly string[] | null,
+  b: readonly string[] | null,
+): readonly string[] | null =>
+  a === null && b === null ? null : [...new Set([...(a ?? []), ...(b ?? [])])];
 
 /** The paper's own values win; each absent one falls back to the root's. */
 function merge(
@@ -182,6 +229,7 @@ function merge(
     kind: p.kind ?? r.kind,
     pdf: p.pdf ?? r.pdf,
     rules: p.rules,
+    identity: joined(r.identity, p.identity),
   };
   return paper === null && Object.values(merged).every((v) => v === null)
     ? null

package/src/pdf-content.test.ts

@@ -0,0 +1,71 @@
+/** What a page says, read from pdf.js's shapes: text, links, metadata. */
+import { describe, expect, it } from "vitest";
+import { linkTargetsOf, metadataOf, pageTextOf, xmpOf } from "./pdf-content.ts";
+
+describe("pageTextOf", () => {
+  it("joins items without a space, and breaks the line where pdf.js marks one", () => {
+    expect(
+      pageTextOf([
+        { str: "Ada Ex", hasEOL: false },
+        { str: "ample", hasEOL: true },
+        { type: "beginMarkedContent" },
+        { str: "", hasEOL: true },
+        { str: "Intro" },
+      ]),
+    ).toBe("Ada Example\n\nIntro");
+  });
+});
+
+describe("linkTargetsOf", () => {
+  it("each link's target once: url, else unsafeUrl; not other annotations, not empty ones", () => {
+    expect(
+      linkTargetsOf([
+        { subtype: "Link", url: "https://a.example" },
+        { subtype: "Link", url: "https://a.example" },
+        { subtype: "Link", unsafeUrl: "mailto:x@example.org" },
+        { subtype: "Link", dest: "sec:1" },
+        { subtype: "Link", url: "" },
+        { subtype: "Widget", url: "https://b.example" },
+      ]),
+    ).toEqual(["https://a.example", "mailto:x@example.org"]);
+  });
+});
+
+describe("metadataOf and xmpOf", () => {
+  it("every string of the Info dictionary, its custom entries and the XMP packet, flat", () => {
+    const xmp = xmpOf(
+      new Map<unknown, unknown>([
+        ["dc:creator", ["Ada Example", "Bob Other"]],
+        ["dc:title", "A Title"],
+        ["xmp:rating", 3],
+        [7, "not a name"],
+      ]),
+    );
+    expect(xmp).toEqual({
+      "dc:creator": ["Ada Example", "Bob Other"],
+      "dc:title": "A Title",
+      "xmp:rating": 3,
+    });
+    expect(
+      metadataOf(
+        {
+          Author: "Ada Example",
+          Subject: "",
+          Trapped: { name: "False" },
+          Custom: { "PTEX.Fullbanner": "This is pdfTeX" },
+        },
+        xmp,
+      ),
+    ).toEqual({
+      Author: "Ada Example",
+      "PTEX.Fullbanner": "This is pdfTeX",
+      "dc:creator": "Ada Example; Bob Other",
+      "dc:title": "A Title",
+    });
+  });
+
+  it("no Info and no packet: nothing", () => {
+    expect(xmpOf(null)).toBeNull();
+    expect(metadataOf(null, null)).toEqual({});
+  });
+});