test(pdf-codec): work toward a genuine 100% mutation score

.github/workflows/mutation.yml

@@ -47,8 +47,8 @@ jobs:
     needs: plan
     if: needs.plan.outputs.has-packages == 'true'
     runs-on: ubuntu-latest
-    # Generous, deliberately: a shard's incremental cache can only ever help (see the caching step below), never hurt, so a cold run -- no prior cache to restore, e.g. this workflow's first ever run, or a shard whose package assignment shifted since the last one that covered it -- pays the full mutation-test cost for whichever packages landed in it. documents.js alone (the single largest package, ~44k mutatable source lines) is sharded onto its own shard for exactly this reason; the timeout has to fit its cold-run cost, not a warm one.
-    timeout-minutes: 180
+    # Generous, deliberately: a shard's incremental cache can only ever help (see the caching step below), never hurt, so a cold run -- no prior cache to restore, e.g. this workflow's first ever run, or a shard whose package assignment shifted since the last one that covered it -- pays the full mutation-test cost for whichever packages landed in it. documents.js alone (the single largest package, ~44k mutatable source lines) is sharded onto its own shard for exactly this reason; the timeout has to fit its cold-run cost, not a warm one. The shared "mutation-incremental-" cache prefix is pooled across every package's every shard (see the restore-keys comment above), so a package's own incremental history can be evicted by unrelated packages' cache churn well before that package's own next run -- any shard can therefore land a fully cold run at any time, not only on a genuine first-ever run, and the budget has to cover that for every package sharded here, not just documents.js's own worst case.
+    timeout-minutes: 300
     strategy:
       fail-fast: false
       matrix: ${{ fromJson(needs.plan.outputs.matrix) }}

packages/document-operations/vitest.config.ts

@@ -1,8 +1,12 @@
 import { defineConfig } from "vitest/config";
 
+// document-output.test.ts's threshold-boundary tests each base64-encode a 5 MB buffer through documents.js's own bytesToBase64 -- real work that finishes in well under a second uninstrumented and idle (confirmed directly: ~200ms). What pushes them over vitest's 5000ms default is CI-runner scheduling contention rather than the encode itself: this workspace's CI shares its runner pool across every package's own test job in the same run, and both threshold tests landed at 5.5-5.8s wall time on two separate, otherwise-unremarkable CI runs. UNIT_TEST_TIMEOUT_MS is raised with a wide margin above both observed runs, matching the same contention-driven pattern already addressed this way in document-outline.js and pdf-codec's own vitest.config.ts, rather than tuned to the bare minimum that happened to pass once.
+const UNIT_TEST_TIMEOUT_MS = 60_000;
+
 export default defineConfig({
   test: {
     include: ["src/**/*.test.ts"],
+    testTimeout: UNIT_TEST_TIMEOUT_MS,
     coverage: {
       provider: "v8",
       include: ["src/**/*.ts"],

packages/pdf-codec/src/afm-widths.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import { STANDARD_METRICS, widthOfCode } from "./afm-widths";
 import { WINANSI_GLYPH_NAMES } from "./encoding";
 
@@ -69,11 +69,32 @@ describe("widthOfCode", () => {
     expect(widthOfCode("Courier", 105)).toBe(600);
   });
 
+  it("returns the fixed width without ever consulting the per-glyph AFM table for a monospace face", () => {
+    const getSpy = vi.spyOn(STANDARD_METRICS.Courier.widths, "get");
+    expect(widthOfCode("Courier", 65)).toBe(600);
+    expect(getSpy).not.toHaveBeenCalled();
+    getSpy.mockRestore();
+  });
+
   it("returns the AFM width for a proportional face", () => {
     expect(widthOfCode("Helvetica", 65)).toBe(667); // 'A'
   });
 
   it("throws for a code with no WinAnsi glyph mapping", () => {
     expect(() => widthOfCode("Helvetica", 1)).toThrow(/WinAnsi/);
   });
+
+  it("throws naming the face, glyph, and code when a face's own AFM table is genuinely missing a glyph its widths map should carry", () => {
+    // Every real standard-14 AFM defines a width for every WinAnsi-mapped glyph (proved by the spot-check above), so this path is unreachable through the public API with real data -- it exists as a caller-invariant guard against a future data gap, per the function's own doc comment. STANDARD_METRICS is exported specifically so a test can reach behind that invariant and exercise the guard directly, deleting one real entry and restoring it immediately after. The cast undoes only this module's own `ReadonlyMap` return type, which exists to stop ordinary callers mutating shared metrics -- the backing object is a genuine mutable Map, and this test's whole point is temporarily mutating it.
+    const widths = STANDARD_METRICS.Helvetica.widths as Map<string, number>;
+    const original = widths.get("A");
+    widths.delete("A");
+    try {
+      expect(() => widthOfCode("Helvetica", 65)).toThrow(
+        "Helvetica has no AFM width for glyph 'A' (code 65)",
+      );
+    } finally {
+      widths.set("A", original!);
+    }
+  });
 });

packages/pdf-codec/src/annotations.test.ts

@@ -1,6 +1,34 @@
 import { describe, expect, it } from "vitest";
+import { NOTES_ANNOTATION_AUTHOR } from "./notes-annotation-author";
 import { readPdf } from "./read";
-import { annotationsPdf } from "./test-support/pdf";
+import { annotationsPdf, FixtureBuilder } from "./test-support/pdf";
+
+const HELVETICA_FONT_DICT_FOR_ANNOT_FIXTURES =
+  "<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>";
+
+// A minimal one-page PDF whose single /Annots entry is exactly the given raw PDF dict literal (minus its own outer << >>, e.g. "/Type /Annot /Subtype /Highlight /Rect [10 10 50 20] /QuadPoints [1 2 3 4]") -- isolates one annotation-dict shape at a time from annotationsPdf()'s own fixture, whose entries are all otherwise well-formed.
+function pdfWithOneAnnotation(annotDictBody: string): Uint8Array<ArrayBuffer> {
+  const b = new FixtureBuilder().header();
+  b.object(1, "<< /Type /Catalog /Pages 2 0 R >>");
+  b.object(2, "<< /Type /Pages /Kids [3 0 R] /Count 1 >>");
+  b.object(
+    3,
+    "<< /Type /Page /Parent 2 0 R /MediaBox [0 0 200 100] /Resources << /Font << /F1 4 0 R >> >> /Contents 5 0 R /Annots [6 0 R] >>",
+  );
+  b.object(4, HELVETICA_FONT_DICT_FOR_ANNOT_FIXTURES);
+  b.stream(5, "<< /Length 0 >>", new Uint8Array(0));
+  b.object(6, `<< ${annotDictBody} >>`);
+  b.classicXrefAndTrailer(6, "/Root 1 0 R");
+  return b.bytes();
+}
+
+function markupPdfWithQuadPoints(
+  quadPointsLiteral: string,
+): Uint8Array<ArrayBuffer> {
+  return pdfWithOneAnnotation(
+    `/Type /Annot /Subtype /Highlight /Rect [10 10 50 20] /QuadPoints ${quadPointsLiteral}`,
+  );
+}
 
 // Annotations (#721 phase 4): genuine third-party sticky notes (/Subtype /Text without this package's own presenter-notes marker), FreeText and the /QuadPoints markup family, and the opaque kinds (Stamp, Ink, ...) carried as quarantined residue -- the annotation row's marker-plus-body and residue verdicts. Link, FileAttachment, and Widget annotations are skipped here: they are owned by the link items, the attachments table, and the AcroForm field tree respectively.
 
@@ -30,6 +58,36 @@ describe("readPdf: annotations", () => {
       contents: "Typed remark",
       author: "Reviewer",
     });
+    // A markup-family subtype's fields, never the opaque-residue fallback's -- pins that FreeText is genuinely recognised via SEMANTIC_SUBTYPES, not merely carrying its own literal subtype string through unaffected by that classification.
+    expect(freeText?.source).toBeUndefined();
+    // FreeText here carries no /QuadPoints at all -- markupFields must tolerate that rather than assuming every semantic subtype has one.
+    expect(freeText?.quads).toBeUndefined();
+  });
+
+  it("omits quads for a markup annotation whose /QuadPoints has too few numbers for even one quad", () => {
+    const doc = readPdf(markupPdfWithQuadPoints("[1 2 3 4]"));
+    const highlight = doc.pages[0]!.annotations?.find(
+      (a) => a.subtype === "Highlight",
+    );
+    expect(highlight?.quads).toBeUndefined();
+  });
+
+  it("omits quads for a markup annotation whose /QuadPoints is empty -- a length that is both below 8 and already a multiple of 8, so only the length check (not the multiple-of-8 check) can be what rejects it", () => {
+    const doc = readPdf(markupPdfWithQuadPoints("[]"));
+    const highlight = doc.pages[0]!.annotations?.find(
+      (a) => a.subtype === "Highlight",
+    );
+    expect(highlight?.quads).toBeUndefined();
+  });
+
+  it("omits quads for a markup annotation whose /QuadPoints length isn't a multiple of 8", () => {
+    const doc = readPdf(
+      markupPdfWithQuadPoints("[1 2 3 4 5 6 7 8 9 10 11 12]"),
+    );
+    const highlight = doc.pages[0]!.annotations?.find(
+      (a) => a.subtype === "Highlight",
+    );
+    expect(highlight?.quads).toBeUndefined();
   });
 
   it("reads a markup annotation's /QuadPoints transformed into page space", () => {
@@ -52,6 +110,66 @@ describe("readPdf: annotations", () => {
     ]);
   });
 
+  it("reads an Underline markup annotation's /QuadPoints transformed into page space", () => {
+    const doc = readPdf(annotationsPdf());
+    const underline = doc.pages[0]!.annotations?.find(
+      (a) => a.subtype === "Underline",
+    );
+    expect(underline).toMatchObject({
+      subtype: "Underline",
+      contents: "Underlined text",
+      author: "Third reviewer",
+    });
+    expect(underline?.quads).toEqual([
+      [
+        { xPt: 20, yPt: 82 },
+        { xPt: 80, yPt: 82 },
+        { xPt: 80, yPt: 70 },
+        { xPt: 20, yPt: 70 },
+      ],
+    ]);
+  });
+
+  it("reads a StrikeOut markup annotation's /QuadPoints transformed into page space", () => {
+    const doc = readPdf(annotationsPdf());
+    const strikeOut = doc.pages[0]!.annotations?.find(
+      (a) => a.subtype === "StrikeOut",
+    );
+    expect(strikeOut).toMatchObject({
+      subtype: "StrikeOut",
+      contents: "Struck text",
+      author: "Third reviewer",
+    });
+    expect(strikeOut?.quads).toEqual([
+      [
+        { xPt: 90, yPt: 82 },
+        { xPt: 150, yPt: 82 },
+        { xPt: 150, yPt: 70 },
+        { xPt: 90, yPt: 70 },
+      ],
+    ]);
+  });
+
+  it("reads a Squiggly markup annotation's /QuadPoints transformed into page space", () => {
+    const doc = readPdf(annotationsPdf());
+    const squiggly = doc.pages[0]!.annotations?.find(
+      (a) => a.subtype === "Squiggly",
+    );
+    expect(squiggly).toMatchObject({
+      subtype: "Squiggly",
+      contents: "Squiggly text",
+      author: "Third reviewer",
+    });
+    expect(squiggly?.quads).toEqual([
+      [
+        { xPt: 20, yPt: 97 },
+        { xPt: 80, yPt: 97 },
+        { xPt: 80, yPt: 85 },
+        { xPt: 20, yPt: 85 },
+      ],
+    ]);
+  });
+
   it("carries an opaque annotation kind as quarantined PDF-syntax residue", () => {
     const doc = readPdf(annotationsPdf());
     const stamp = doc.pages[0]!.annotations?.find((a) => a.subtype === "Stamp");
@@ -72,4 +190,56 @@ describe("readPdf: annotations", () => {
     const doc = readPdf(annotationsPdf());
     expect(doc.pages[1]!.annotations).toBeUndefined();
   });
+
+  it("reports a diagnostic and skips an annotation that carries no /Rect", () => {
+    const diagnostics: unknown[] = [];
+    const doc = readPdf(
+      pdfWithOneAnnotation("/Type /Annot /Subtype /Highlight"),
+      { sink: (d) => diagnostics.push(d) },
+    );
+    expect(doc.pages[0]!.annotations).toBeUndefined();
+    expect(diagnostics).toEqual([
+      expect.objectContaining({
+        code: "pdf/annotation-missing-rect",
+        message: "a /Highlight annotation carries no /Rect; skipping it",
+      }),
+    ]);
+  });
+
+  it.each(["Link", "FileAttachment", "Widget", "Popup"])(
+    "skips a bare %s annotation entirely, since another reader owns that kind",
+    (subtype) => {
+      const doc = readPdf(
+        pdfWithOneAnnotation(
+          `/Type /Annot /Subtype /${subtype} /Rect [10 10 50 20]`,
+        ),
+      );
+      expect(doc.pages[0]!.annotations).toBeUndefined();
+    },
+  );
+
+  it("does not skip a non-Text annotation even when its /T happens to equal the presenter-notes marker author", () => {
+    const doc = readPdf(
+      pdfWithOneAnnotation(
+        `/Type /Annot /Subtype /FreeText /Rect [10 10 50 20] /T (${NOTES_ANNOTATION_AUTHOR})`,
+      ),
+    );
+    // The presenter-notes skip check is specifically subtype === "Text"; a FreeText annotation must never be excluded by it, no matter what its /T reads.
+    expect(doc.pages[0]!.annotations).toHaveLength(1);
+  });
+
+  it("omits contents, author, and modification date entirely -- not as present keys holding undefined -- when a semantic annotation carries none of /Contents, /T, or /M", () => {
+    const doc = readPdf(
+      pdfWithOneAnnotation(
+        "/Type /Annot /Subtype /Highlight /Rect [10 10 50 20] /QuadPoints [10 20 50 20 50 10 10 10]",
+      ),
+    );
+    const highlight = doc.pages[0]!.annotations?.find(
+      (a) => a.subtype === "Highlight",
+    );
+    expect(highlight).toBeDefined();
+    expect(Object.hasOwn(highlight!, "contents")).toBe(false);
+    expect(Object.hasOwn(highlight!, "author")).toBe(false);
+    expect(Object.hasOwn(highlight!, "modifiedIso")).toBe(false);
+  });
 });

packages/pdf-codec/src/annotations.ts

@@ -11,28 +11,28 @@ import type { Matrix } from "./matrix";
 
 // Annotation reading (#721 phase 4): the /Annots walk for everything that is neither a link item (read.ts's own walk), a /FileAttachment (the attachments table owns its filespec), nor a /Widget (the AcroForm field tree owns it). The semantic set is the sticky note, FreeText, and the /QuadPoints markup family; every other kind degrades to its rect plus the raw annotation dictionary in the quarantined residue channel -- the verdict row's own split. Popup annotations are dropped outright as derivable (a popup's rect is the parent plus a fixed offset, and its contents ARE the parent's).
 
-const SEMANTIC_SUBTYPES = new Set([
-  "Text",
-  "FreeText",
-  "Highlight",
-  "Underline",
-  "StrikeOut",
-  "Squiggly",
-]);
-// Annotations another reader here already owns; listing them keeps this walk's skip set explicit rather than an else-shaped accident.
-const OWNED_ELSEWHERE_SUBTYPES = new Set([
-  "Link",
-  "FileAttachment",
-  "Widget",
-  "Popup",
-]);
-
 export function readPageAnnotations(
   page: PdfDict,
   pageMatrix: Matrix,
   resolver: PdfObjectResolver,
   sink: PdfDiagnosticSink,
 ): LayoutAnnotation[] {
+  // Both sets are scoped to this function, its only reader, rather than declared at module level: a module-level initializer runs exactly once per process, which puts every one of its literal entries permanently beyond the reach of Stryker's per-test mutation switch (see the memory note on this in the project's own notes) -- scoping them here re-evaluates them fresh on every call, where each entry is reachable again.
+  const semanticSubtypes = new Set([
+    "Text",
+    "FreeText",
+    "Highlight",
+    "Underline",
+    "StrikeOut",
+    "Squiggly",
+  ]);
+  // Annotations another reader here already owns; listing them keeps this walk's skip set explicit rather than an else-shaped accident.
+  const ownedElsewhereSubtypes = new Set([
+    "Link",
+    "FileAttachment",
+    "Widget",
+    "Popup",
+  ]);
   const annotsArr = asArray(dictGet(page, "Annots"));
   if (annotsArr === undefined) {
     return [];
@@ -44,7 +44,7 @@ export function readPageAnnotations(
       continue;
     }
     const subtype = asName(dictGet(annot, "Subtype"));
-    if (subtype === undefined || OWNED_ELSEWHERE_SUBTYPES.has(subtype)) {
+    if (subtype === undefined || ownedElsewhereSubtypes.has(subtype)) {
       continue;
     }
     // This package's own hidden presenter-notes annotation is a round-trip mechanism, not document content -- readPageNotes consumes it, and it must not also surface as a sticky note.
@@ -87,7 +87,7 @@ export function readPageAnnotations(
       ...(contents !== undefined ? { contents } : {}),
       ...(author !== undefined ? { author } : {}),
       ...(modifiedIso !== undefined ? { modifiedIso } : {}),
-      ...(SEMANTIC_SUBTYPES.has(subtype)
+      ...(semanticSubtypes.has(subtype)
         ? markupFields(annot, pageMatrix)
         : {
             source: {

packages/pdf-codec/src/attachments.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from "vitest";
+import type { PdfDiagnostic } from "./diagnostics";
 import { readPdf } from "./read";
 import { embeddedFilesPdf } from "./test-support/pdf";
 import { bytesToBase64 } from "./util/base64";
@@ -21,13 +22,39 @@ describe("readPdf: embedded files", () => {
   });
 
   it("collects a /FileAttachment annotation's filespec and a catalog /AF entry, deduplicated against the name tree by name", () => {
-    const doc = readPdf(embeddedFilesPdf());
+    const diagnostics: PdfDiagnostic[] = [];
+    const doc = readPdf(embeddedFilesPdf(), {
+      sink: (d) => diagnostics.push(d),
+    });
     const names = doc.attachments?.map((a) => a.name);
     expect(names).toEqual(["notes.txt", "logo.bin", "manifest.json"]);
     const logo = doc.attachments?.find((a) => a.name === "logo.bin");
     expect(logo?.base64).toBe(bytesToBase64(new Uint8Array([0, 1, 2])));
     expect(logo?.mimeType).toBeUndefined();
     const manifest = doc.attachments?.find((a) => a.name === "manifest.json");
     expect(manifest?.description).toBeUndefined();
+    expect(manifest?.base64).toBe(b64("{}"));
+    // The only diagnostic expected is the deliberately-broken /AF entry (object 16) tested separately below -- the second /FileAttachment annotation (object 11, the dedup case) must itself parse cleanly rather than merely happening to contribute nothing because it is malformed.
+    expect(diagnostics).toEqual([
+      expect.objectContaining({ code: "pdf/embedded-file-missing-stream" }),
+    ]);
+  });
+
+  it("warns on and drops a filespec whose /EF resolves but has neither an /F nor a /UF stream", () => {
+    const diagnostics: PdfDiagnostic[] = [];
+    const doc = readPdf(embeddedFilesPdf(), {
+      sink: (d) => diagnostics.push(d),
+    });
+    expect(
+      doc.attachments?.find((a) => a.name === "broken.bin"),
+    ).toBeUndefined();
+    expect(diagnostics).toContainEqual(
+      expect.objectContaining({
+        code: "pdf/embedded-file-missing-stream",
+        severity: "warning",
+        message:
+          "a filespec declares /EF but neither /F nor /UF resolves to an embedded stream",
+      }),
+    );
   });
 });