paperlint 4.2.0 → 6.0.0

package/src/paper-includes.ts

@@ -0,0 +1,77 @@
+/**
+ * THE FILES OF A PAPER'S BODY, handed to ESLint — so the rules over ESLint's LaTeX text read a paper
+ * whose body is in `sections/*.tex`, and report each finding at its own file and line (#144).
+ *
+ * The set is what TeX reads, resolved by the reader the parse-tree rules use (`bodyFiles`,
+ * src/tex-paper.ts): `paper.tex` and every file an include in its document body brings in, found in
+ * the paper's directory. Not a glob over every `.tex`: a frozen version under `versions/`, a macro
+ * file the preamble includes and a scratch file nothing includes are not the paper.
+ *
+ * Two blocks per paper, both relative to the paper's directory (`basePath`):
+ *
+ * 1. a global un-ignore of each body file by name. paperlint's scope ignores every file it does not
+ *    claim (src/paper-files.ts); the fragment block (`buildConfig`) claims every `.tex` but
+ *    `paper.tex`, so only the files named here are ever enumerated;
+ * 2. `settings.paperlint.paper` for `paper.tex` and its body files: the main file and the whole set,
+ *    for the rules whose verdict is the paper's (eslint-rules/paper-context.ts).
+ */
+import { join, relative } from "node:path";
+import { PAPERLINT_SETTINGS } from "#eslint-rules/paper-context";
+import { callerPath } from "./caller-path.ts";
+import type { AbsolutePath } from "./domain/paths.ts";
+import type { ConfigBlock } from "./rules-config.ts";
+import { bodyFiles, type PaperDeps, type Unread } from "./tex-paper.ts";
+
+/** One paper's main file and body files, and the includes that resolved nowhere. */
+export interface PaperBody {
+  readonly dir: string;
+  readonly main: AbsolutePath;
+  readonly files: readonly AbsolutePath[];
+  readonly missing: readonly Unread[];
+}
+
+/** The body of each paper directory in `dirs` that has a `paper.tex`. */
+export function paperBodies(
+  dirs: readonly string[],
+  deps: PaperDeps,
+): readonly PaperBody[] {
+  return dirs.flatMap((dir) => {
+    const main = callerPath(join(dir, "paper.tex"));
+    const bytes = deps.files.readBytes(main);
+    if (bytes === null) return [];
+    const body = bodyFiles(main, new TextDecoder().decode(bytes), deps);
+    return [{ dir, main, files: body.files, missing: body.missing }];
+  });
+}
+
+/** The config blocks that hand ESLint each paper's body files, and the paper to every one of them. */
+export const includeBlocks = (
+  bodies: readonly PaperBody[],
+): readonly ConfigBlock[] =>
+  bodies.flatMap((b) => {
+    const rel = b.files.map((f) => relative(b.dir, f));
+    const paper = { main: b.main, files: [b.main, ...b.files] };
+    return [
+      ...(rel.length > 0
+        ? [{ basePath: b.dir, ignores: rel.map((r) => `!${r}`) }]
+        : []),
+      {
+        basePath: b.dir,
+        files: ["paper.tex", ...rel],
+        settings: { [PAPERLINT_SETTINGS]: { paper } },
+      },
+    ];
+  });
+
+/** One line per include that resolved nowhere: which text lint did not read, and why. */
+export const unreadLines = (
+  bodies: readonly PaperBody[],
+  shown: (path: string) => string,
+): readonly string[] =>
+  bodies.flatMap((b) =>
+    b.missing.map(
+      (m) =>
+        `${shown(b.main)}: lint did not read \`${m.target}\` (included by ${m.file}): ` +
+        "no such file in the paper's directory or paperlint's inputs",
+    ),
+  );

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({});
+  });
+});

package/src/pdf-content.ts

@@ -0,0 +1,125 @@
+/**
+ * What a page SAYS, as pdf.js exports it — PURE. The anonymity and page-limit rules judge text, so
+ * the facts carry each page's text, the targets of its links, where the bibliography's first entry
+ * and the appendix are anchored, and the document's metadata. `pdf-facts.ts` reads the PDF and
+ * calls these; nothing here knows what a rule does with the result.
+ */
+import { fieldOf, isRecord } from "./domain/record.ts";
+
+/**
+ * A page's text: its items in content order, joined WITHOUT a separator — pdf.js emits a space as
+ * an item of its own where the glyphs leave a gap, so a word split into two items by kerning comes
+ * back whole — with a line break after every item pdf.js marks as ending a line.
+ */
+export const pageTextOf = (items: readonly unknown[]): string =>
+  items
+    .map((it) => {
+      const s = fieldOf(it, "str");
+      return `${typeof s === "string" ? s : ""}${fieldOf(it, "hasEOL") === true ? "\n" : ""}`;
+    })
+    .join("");
+
+/**
+ * The target of every link annotation on a page, once each: its `url`, else its `unsafeUrl`. A link
+ * whose text breaks across lines is one annotation per line (measured: hyperref's `\\href` gave two
+ * for one target), and one target is one fact.
+ */
+export const linkTargetsOf = (
+  annotations: readonly unknown[],
+): readonly string[] => {
+  const urls = annotations.flatMap((a) => {
+    if (fieldOf(a, "subtype") !== "Link") return [];
+    const url = fieldOf(a, "url") ?? fieldOf(a, "unsafeUrl");
+    return typeof url === "string" && url !== "" ? [url] : [];
+  });
+  return urls.filter((u, i) => urls.indexOf(u) === i);
+};
+
+/** The page reference an explicit destination starts with, or null for anything else. */
+export const refOf = (dest: unknown): object | null => {
+  const ref: unknown = Array.isArray(dest) ? dest[0] : undefined;
+  return typeof ref === "object" && ref !== null ? ref : null;
+};
+
+/**
+ * The page references of the named destinations whose name starts with `prefix`, from pdf.js's
+ * `getDestinations()` (name → explicit destination). hyperref names one `cite.<key>` per
+ * `\bibitem`, and, after `\appendix` in the standard classes, the appendix's sections
+ * `appendix.<letter>`.
+ */
+export const namedRefs = (
+  destinations: unknown,
+  prefix: string,
+): readonly object[] =>
+  isRecord(destinations)
+    ? Object.entries(destinations).flatMap(([name, dest]) => {
+        const ref = refOf(dest);
+        return name.startsWith(prefix) && ref !== null ? [ref] : [];
+      })
+    : [];
+
+/** A bookmark title that opens an appendix: «Appendix A: …», «APPENDIX», «Appendices». */
+const APPENDIX_TITLE = /^\s*appendi(?:x|ces)\b/iu;
+
+/**
+ * The destinations of the top-level bookmarks that open an appendix, from pdf.js's `getOutline()`:
+ * each a name to look up, or an explicit destination. IEEEtran's `\appendices` names its sections
+ * `section*.<n>`, so the bookmark's title is what says it is an appendix.
+ */
+export const appendixOutlineDests = (outline: unknown): readonly unknown[] =>
+  Array.isArray(outline)
+    ? outline.flatMap((item: unknown) => {
+        const title = fieldOf(item, "title");
+        return typeof title === "string" && APPENDIX_TITLE.test(title)
+          ? [fieldOf(item, "dest")]
+          : [];
+      })
+    : [];
+
+/** A value of a metadata field as text: a string, or the strings of a list; nothing else. */
+const textsOf = (v: unknown): readonly string[] =>
+  typeof v === "string"
+    ? [v]
+    : Array.isArray(v)
+      ? v.filter((x): x is string => typeof x === "string")
+      : [];
+
+const entries = (rec: unknown): readonly (readonly [string, string])[] =>
+  isRecord(rec)
+    ? Object.entries(rec).flatMap(([k, v]) => {
+        const text = textsOf(v).join("; ");
+        return text === "" ? [] : [[k, text] as const];
+      })
+    : [];
+
+/**
+ * The XMP packet pdf.js parsed, as `name → value`: its `Metadata` iterates `[name, value]` pairs.
+ * Null when the PDF carries no packet.
+ */
+export const xmpOf = (
+  packet: Iterable<unknown> | null,
+): Readonly<Record<string, unknown>> | null =>
+  packet === null
+    ? null
+    : Object.fromEntries(
+        [...packet].flatMap((e) =>
+          Array.isArray(e) && typeof e[0] === "string" ? [[e[0], e[1]]] : [],
+        ),
+      );
+
+/**
+ * The document's metadata as flat `field → text`: every string of the Info dictionary (`Author`,
+ * `Title`, …), of its custom entries (`PTEX.Fullbanner`), and of the XMP packet, whose names carry
+ * their namespace (`dc:creator`), as pdf.js's `getMetadata` returns them. `xmp` is the packet's
+ * `xmpOf`, or null when the PDF has none.
+ */
+export function metadataOf(
+  info: unknown,
+  xmp: unknown,
+): Readonly<Record<string, string>> {
+  return Object.fromEntries([
+    ...entries(info),
+    ...entries(fieldOf(info, "Custom")),
+    ...entries(xmp),
+  ]);
+}

package/src/pdf-facts.test.ts

@@ -6,6 +6,7 @@
  */
 import assert from "node:assert/strict";
 import { getResolvedPDFJS } from "unpdf";
+import { fieldOf } from "./domain/record.ts";
 import { test } from "vitest";
 import { factsOf, failureOf, rawFontOf } from "./pdf-facts.ts";
 import { present } from "../test/support.ts";
@@ -21,7 +22,11 @@ interface FakeItem {
   height: number;
 }
 /** A page whose text items and loaded fonts are given; its viewport flips y like pdf.js's. */
-function page(items: FakeItem[], fonts: Record<string, unknown>) {
+function page(
+  items: FakeItem[],
+  fonts: Record<string, unknown>,
+  said: { annotations?: unknown[] } = {},
+) {
   const objs = new Map(Object.entries(fonts));
   return {
     getOperatorList: () => Promise.resolve({ fnArray: [], argsArray: [] }),
@@ -32,6 +37,7 @@ function page(items: FakeItem[], fonts: Record<string, unknown>) {
       get: (id: string) => objs.get(id),
       [Symbol.iterator]: () => objs[Symbol.iterator](),
     },
+    getAnnotations: () => Promise.resolve(said.annotations ?? []),
     getViewport: () => ({
       width: 612,
       height: H,
@@ -40,8 +46,23 @@ function page(items: FakeItem[], fonts: Record<string, unknown>) {
     }),
   };
 }
-const doc = (pages: ReturnType<typeof page>[]) => ({
+const doc = (
+  pages: ReturnType<typeof page>[],
+  info: unknown = {},
+  destinations: unknown = {},
+  outline: unknown = null,
+) => ({
   numPages: pages.length,
+  getMetadata: () => Promise.resolve({ info, metadata: null }),
+  getDestinations: () => Promise.resolve(destinations),
+  getDestination: (id: string) =>
+    Promise.resolve(fieldOf(destinations, id) ?? null),
+  getOutline: () => Promise.resolve(outline),
+  // A reference is `{ page }` here; one without a page is one pdf.js cannot place.
+  getPageIndex: (ref: object) =>
+    "page" in ref && typeof ref.page === "number"
+      ? Promise.resolve(ref.page - 1)
+      : Promise.reject(new Error("Invalid page reference")),
   getPage: (i: number) =>
     Promise.resolve(present(pages[i - 1], `page ${String(i)}`)),
 });
@@ -152,3 +173,90 @@ test("🔴 a rejection with no value at all is a failure too, not a TypeError ou
     ],
   );
 });
+
+test("what the pages say: text, links with their page, metadata", async () => {
+  const fonts = { f1: { loadedName: "f1", name: "Named", ascent: 0.8 } };
+  const plain = page([item("f1", [10, 0, 0, 10, 50, 700])], fonts);
+  const linked = page([item("f1", [10, 0, 0, 10, 50, 700])], fonts, {
+    annotations: [{ subtype: "Link", url: "https://github.com/adaexample" }],
+  });
+  const r = await factsOf(doc([plain, linked], { Author: "Ada Example" }), lib);
+  assert.ok(r.ok);
+  assert.deepEqual(
+    [r.facts.pageTexts, r.facts.links, r.facts.metadata],
+    [
+      ["word", "word"],
+      [{ page: 2, uri: "https://github.com/adaexample" }],
+      { Author: "Ada Example" },
+    ],
+  );
+});
+
+test("the bibliography anchor: the lowest page of any cite.<key> destination", async () => {
+  const fonts = { f1: { loadedName: "f1", name: "Named", ascent: 0.8 } };
+  const pages = [1, 2, 3].map(() =>
+    page([item("f1", [10, 0, 0, 10, 50, 700])], fonts),
+  );
+  const facts = async (destinations: unknown) => {
+    const r = await factsOf(doc(pages, {}, destinations), lib);
+    assert.ok(r.ok);
+    return r.facts.bibAnchorPage;
+  };
+  assert.equal(
+    await facts({
+      "cite.b": [{ page: 3 }, { name: "XYZ" }],
+      "cite.a": [{ page: 2 }, { name: "XYZ" }],
+      "section.1": [{ page: 1 }, { name: "XYZ" }],
+      // A reference pdf.js cannot place is skipped, not fatal.
+      "cite.c": [{ num: 99 }, { name: "XYZ" }],
+    }),
+    2,
+  );
+  // No hyperref: no cite destinations, and the value says so.
+  assert.equal(await facts({ "section.1": [{ page: 1 }] }), null);
+  assert.equal(await facts(null), null);
+  // A destination that is not an explicit array is not an anchor.
+  assert.equal(await facts({ "cite.a": "named-elsewhere" }), null);
+});
+
+test("the appendix anchor: an appendix.<letter> destination, or a bookmark titled «Appendix…»", async () => {
+  const fonts = { f1: { loadedName: "f1", name: "Named", ascent: 0.8 } };
+  const pages = [1, 2, 3, 4].map(() =>
+    page([item("f1", [10, 0, 0, 10, 50, 700])], fonts),
+  );
+  const facts = async (destinations: unknown, outline: unknown) => {
+    const r = await factsOf(doc(pages, {}, destinations, outline), lib);
+    assert.ok(r.ok);
+    return r.facts.appendixAnchorPage;
+  };
+  const XYZ = { name: "XYZ" };
+  // The standard classes: hyperref names the appendix's sections `appendix.<letter>`.
+  assert.equal(
+    await facts(
+      { "appendix.B": [{ page: 4 }, XYZ], "appendix.A": [{ page: 3 }, XYZ] },
+      null,
+    ),
+    3,
+  );
+  // IEEEtran's \appendices: the sections are `section*.<n>`; the bookmark's title says appendix,
+  // its destination is a name to look up, or an explicit one.
+  const named = {
+    "section*.5": [{ page: 2 }, XYZ],
+    "section*.4": [{ page: 1 }, XYZ],
+  };
+  assert.equal(
+    await facts(named, [
+      { title: "Conclusion", dest: "section*.4", items: [] },
+      { title: "Appendix A: Details", dest: "section*.5", items: [] },
+      { title: "APPENDIX", dest: [{ page: 4 }, XYZ], items: [] },
+    ]),
+    2,
+  );
+  // No appendix anywhere, a bookmark whose name resolves to nothing, and no outline at all.
+  assert.equal(
+    await facts(named, [{ title: "Conclusion", dest: "section*.4" }]),
+    null,
+  );
+  assert.equal(await facts({}, [{ title: "Appendices", dest: "gone" }]), null);
+  assert.equal(await facts({}, { not: "a list" }), null);
+});