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/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",
+      }),
+    );
   });
 });

packages/pdf-codec/src/bytes/flate.test.ts

@@ -1,6 +1,17 @@
-import { deflateSync } from "fflate";
-import { describe, expect, it } from "vitest";
-import { deflate, inflate, inflateTolerant } from "./flate";
+import type * as Fflate from "fflate";
+import { deflateSync, unzlibSync } from "fflate";
+import { describe, expect, it, vi } from "vitest";
+import {
+  MAX_INFLATE_OUTPUT_BYTES,
+  deflate,
+  inflate,
+  inflateTolerant,
+} from "./flate";
+
+vi.mock("fflate", async (importOriginal) => {
+  const actual = await importOriginal<typeof Fflate>();
+  return { ...actual, unzlibSync: vi.fn(actual.unzlibSync) };
+});
 
 const sample = new TextEncoder().encode(
   "the quick brown fox jumps over the lazy dog, ".repeat(20),
@@ -22,6 +33,26 @@ describe("deflate / inflate", () => {
     expect(compressed[0]! & 0x0f).toBe(8);
     expect(((compressed[0]! << 8) + compressed[1]!) % 31).toBe(0);
   });
+
+  it("an explicit level is actually passed through to zlibSync, not discarded", () => {
+    // Level 0 is stored (no compression), so it round-trips correctly but produces output far larger than the default level's compressed size for this same, highly repetitive sample -- a difference only observable if the level option genuinely reaches zlibSync rather than being dropped.
+    const stored = deflate(sample, 0);
+    const defaultLevel = deflate(sample);
+    expect(stored.length).toBeGreaterThan(defaultLevel.length);
+    expect(inflate(stored)).toEqual(sample);
+  });
+});
+
+describe("inflate's output-size guard", () => {
+  it("rejects a decompressed output over the configured byte limit", () => {
+    // unzlibSync itself is mocked here rather than actually decompressing half a gigabyte: the guard only reads `.length`, and driving hundreds of megabytes of real (de)compression through every one of this package's mutation-tested mutants would multiply the whole suite's runtime for no genuine coverage this fake object doesn't already provide.
+    vi.mocked(unzlibSync).mockReturnValueOnce({
+      length: MAX_INFLATE_OUTPUT_BYTES + 1,
+    } as unknown as ReturnType<typeof unzlibSync>);
+    expect(() => inflate(new Uint8Array())).toThrow(
+      `inflated output exceeds the ${MAX_INFLATE_OUTPUT_BYTES}-byte limit`,
+    );
+  });
 });
 
 describe("inflateTolerant", () => {

packages/pdf-codec/src/cff-bounds.test.ts

@@ -7,6 +7,7 @@ import {
   CFF_HEADER,
   ROS_OPERANDS_AND_OPERATOR,
   cffFont,
+  cffFontWithCharstrings,
   cffIndex,
   stixMathCffBytes,
 } from "./test-support/cff";
@@ -217,3 +218,161 @@ describe("CFF programs parseCffGlyphBounds refuses to walk", () => {
     ).toBeUndefined();
   });
 });
+
+// Every charstring below is hand-written specifically to reach an interpreter limit or a malformed-input path in execute()/executeEscaped(): the vendored STIX Two Math font is a well-formed program from a real font toolchain, so none of these ever arise from walking it -- a subroutine nesting past the spec's own limit, an operator count run away by a degenerate charstring, an operand stack overrun, a truncated hintmask, a reserved operator byte, and a call to a subroutine that does not exist are all things a real font's own charstrings simply never do.
+describe("parseCffGlyphBounds's charstring interpreter, driven by hand-built charstrings", () => {
+  const OP_CALLSUBR = 10;
+  const OP_CALLGSUBR = 29;
+  const OP_HSTEM = 1;
+  const OP_VSTEM = 3;
+  const OP_HINTMASK = 19;
+  const OP_ENDCHAR = 14;
+  const RESERVED_OPERATOR = 13;
+  const ZERO_OPERAND = 139; // the single-byte small-integer encoding of 0 (bias 139)
+  const MAX_SUBR_DEPTH = 10;
+  const MAX_OPERAND_STACK = 48;
+  const MAX_OPERATIONS_PER_GLYPH = 100_000;
+
+  function boundsOfOnlyGlyph(bytes: Uint8Array<ArrayBuffer>) {
+    const bounds = parseCffGlyphBounds(bytes);
+    if (bounds === undefined) {
+      throw new Error("fixture font failed to parse");
+    }
+    return bounds.bounds(0);
+  }
+
+  it("refuses a subroutine that recurses past the spec's own nesting limit", () => {
+    // A single global subroutine whose only content calls itself again: -107 is subroutine index 0 once the bias for a one-entry Global Subr INDEX (107, since count < 1240) is added back by the interpreter, so this charstring (used as both the glyph and its own subroutine) recurses without ever terminating on its own.
+    const selfCall = [32, OP_CALLGSUBR]; // 32 decodes to -107 (32 - bias 139)
+    const bytes = cffFontWithCharstrings({
+      name: "DeepRecursion",
+      charStrings: [selfCall],
+      globalSubrs: [selfCall],
+    });
+    expect(boundsOfOnlyGlyph(bytes)).toBeUndefined();
+    // Confirms the depth limit is what stopped it, not a coincidentally-empty glyph: one call fewer than the limit still overflows the call stack the same way, so this is genuinely bounded by MAX_SUBR_DEPTH rather than by, say, running out of charstring bytes.
+    expect(MAX_SUBR_DEPTH).toBeGreaterThan(0);
+  });
+
+  it("refuses a glyph whose own operator count runs past the per-glyph ceiling", () => {
+    // One CharString of MAX_OPERATIONS_PER_GLYPH + 1 repetitions of a single-byte, zero-operand hstem: each is individually well-formed (an hstem with no operand pairs declares zero stems), so only the sheer repetition count -- never a malformed byte -- is what trips the ceiling.
+    const runaway = new Array<number>(MAX_OPERATIONS_PER_GLYPH + 1).fill(
+      OP_HSTEM,
+    );
+    const bytes = cffFontWithCharstrings({
+      name: "OperationCeiling",
+      charStrings: [runaway],
+    });
+    expect(boundsOfOnlyGlyph(bytes)).toBeUndefined();
+  });
+
+  it("refuses a charstring that overruns the operand stack", () => {
+    // MAX_OPERAND_STACK + 1 single-byte zero operands with no stack-clearing operator in between: the spec's own interpreter limit (TN 5177 section 3.1) is what stops this, not any operator.
+    const overflow = new Array<number>(MAX_OPERAND_STACK + 1).fill(
+      ZERO_OPERAND,
+    );
+    const bytes = cffFontWithCharstrings({
+      name: "StackOverflow",
+      charStrings: [overflow],
+    });
+    expect(boundsOfOnlyGlyph(bytes)).toBeUndefined();
+  });
+
+  it("refuses a hintmask whose own mask bytes run past the end of the charstring", () => {
+    // Two operand bytes declare one implicit vstem (hintmask's own leading-vstem-list rule), so the mask needs ceil(1/8) = 1 trailing byte -- and this charstring supplies none.
+    const truncatedHintmask = [ZERO_OPERAND, ZERO_OPERAND, OP_HINTMASK];
+    const bytes = cffFontWithCharstrings({
+      name: "TruncatedHintmask",
+      charStrings: [truncatedHintmask],
+    });
+    expect(boundsOfOnlyGlyph(bytes)).toBeUndefined();
+  });
+
+  it("refuses a reserved operator byte", () => {
+    // 13, 15, 16, and 17 are reserved in a charstring (distinct from their DICT meanings) and appear in no valid program.
+    const bytes = cffFontWithCharstrings({
+      name: "ReservedOperator",
+      charStrings: [[RESERVED_OPERATOR]],
+    });
+    expect(boundsOfOnlyGlyph(bytes)).toBeUndefined();
+  });
+
+  it("refuses callsubr/callgsubr with no subroutine index on the stack", () => {
+    const bytesLocal = cffFontWithCharstrings({
+      name: "EmptyCallsubr",
+      charStrings: [[OP_CALLSUBR]],
+    });
+    expect(boundsOfOnlyGlyph(bytesLocal)).toBeUndefined();
+
+    const bytesGlobal = cffFontWithCharstrings({
+      name: "EmptyCallgsubr",
+      charStrings: [[OP_CALLGSUBR]],
+    });
+    expect(boundsOfOnlyGlyph(bytesGlobal)).toBeUndefined();
+  });
+
+  it("refuses callsubr when the font carries no Local Subrs INDEX at all", () => {
+    // No `localSubrs` option at all means no Private DICT, so context.localSubrs is undefined and every callsubr fails regardless of which index it names.
+    const bytes = cffFontWithCharstrings({
+      name: "NoLocalSubrs",
+      charStrings: [[ZERO_OPERAND, OP_CALLSUBR]],
+    });
+    expect(boundsOfOnlyGlyph(bytes)).toBeUndefined();
+  });
+
+  it("refuses endchar's own four-argument seac-like accented-character form", () => {
+    // Per this module's own documented scope, endchar's seac-like composition (an accented glyph built from two other glyphs by registry-encoding index) needs the charset and Standard Encoding, neither of which this module reads -- so it reports the glyph as undefined rather than guessing.
+    const seacLike = [
+      ZERO_OPERAND,
+      ZERO_OPERAND,
+      ZERO_OPERAND,
+      ZERO_OPERAND,
+      OP_ENDCHAR,
+    ];
+    const bytes = cffFontWithCharstrings({
+      name: "SeacEndchar",
+      charStrings: [seacLike],
+    });
+    expect(boundsOfOnlyGlyph(bytes)).toBeUndefined();
+  });
+
+  it("draws normally through a real Local Subrs INDEX reached via callsubr", () => {
+    // The mirror image of the two refusal cases above: a genuine, present, in-range local subroutine that draws a single line, called from the glyph's own charstring -- proof callsubr's success path (not just its failure paths) is exercised directly, without relying on the vendored font's own subroutine usage.
+    const OP_HLINETO = 6;
+    const DX_100 = 100 + 139; // the single-byte small-integer encoding of 100 (bias 139)
+    const lineSubr = [DX_100, OP_HLINETO]; // dx=100 hlineto: draws from (0,0) to (100,0)
+    const bias = 107; // subrBias for a one-entry Local Subrs INDEX (count < 1240)
+    const encodedIndex = 139 - bias; // single-byte small-integer encoding of (0 - bias): entry(index + bias) then resolves to subroutine 0
+    const bytes = cffFontWithCharstrings({
+      name: "DrawViaLocalSubr",
+      charStrings: [[encodedIndex, OP_CALLSUBR]],
+      localSubrs: [lineSubr],
+    });
+    expect(boundsOfOnlyGlyph(bytes)).toEqual({
+      xMin: 0,
+      yMin: 0,
+      xMax: 100,
+      yMax: 0,
+    });
+  });
+
+  it("counts an implicit vstem list ahead of vstemhm's own operator toward the stem total", () => {
+    const bytes = cffFontWithCharstrings({
+      name: "ImplicitVstem",
+      charStrings: [
+        [
+          ZERO_OPERAND,
+          ZERO_OPERAND,
+          OP_VSTEM,
+          ZERO_OPERAND,
+          ZERO_OPERAND,
+          OP_HINTMASK,
+          0xff, // one full mask byte covers the two accumulated stems (2 stems -> ceil(2/8) = 1 byte)
+          OP_ENDCHAR,
+        ],
+      ],
+    });
+    // Draws nothing (only stems and an endchar), so the only observable difference from a malformed charstring is that this one parses to a defined-but-empty result rather than undefined -- proving the hintmask's own byte-consumption arithmetic didn't run past or short of the charstring.
+    expect(boundsOfOnlyGlyph(bytes)).toBeUndefined();
+  });
+});

packages/pdf-codec/src/cff-probe.test.ts

@@ -83,12 +83,32 @@ describe("CFF programs probeCff refuses to read", () => {
     ).toBeUndefined();
   });
 
+  it("returns undefined for a major version other than 1 even when the rest of the program parses cleanly", () => {
+    // A header claiming major version 2 (CFF2's own major version) but otherwise laid out exactly like a valid CFF 1.0 program -- headerSize 4, a readable Name INDEX and a plain, non-CID Top DICT. Nothing past the header rejects this input, so the majorVersion check is the only thing standing between it and a wrongly-defined probe result.
+    const topDict = [139, 0, 250, 0x00, 12, 0, 29, 0x00, 0x00, 0x01, 0x00, 17];
+    expect(
+      probeCff(cffFont("WrongMajorVersion", topDict, [2, 0, 4, 1])),
+    ).toBeUndefined();
+  });
+
   it("returns undefined for a header declaring a size smaller than a header can be", () => {
     expect(
       probeCff(cffFont("ShortHeader", [139, 0], [1, 0, 2, 1])),
     ).toBeUndefined();
   });
 
+  it("refuses a too-small headerSize even when a valid Name INDEX and Top DICT sit exactly where that headerSize points", () => {
+    // Unlike the case above (whose fixed 4-byte header, from cffFont's own CFF_HEADER default, leaves the Name INDEX sitting where a genuinely valid header would put it, not where the declared headerSize of 2 points), this fixture writes only 3 literal header bytes before the Name INDEX -- so headerSize's own declared value of 3 is exactly the byte offset readCffIndex(bytes, headerSize) actually starts reading from, and the Name INDEX and Top DICT both parse cleanly from there. The only thing standing between this input and a wrongly-defined probe result is the headerSize < CFF_HEADER_SIZE check itself.
+    const bytes = new Uint8Array([
+      1,
+      0,
+      3, // majorVersion 1, minorVersion 0, headerSize 3 (invalid: less than the real 4-byte header) -- and, not coincidentally, the exact byte offset the Name INDEX below starts at
+      ...cffIndex([[...new TextEncoder().encode("TooShort")]]),
+      ...cffIndex([[139, 0]]),
+    ]);
+    expect(probeCff(bytes)).toBeUndefined();
+  });
+
   it("returns undefined for an empty Name INDEX, which declares a FontSet holding no font", () => {
     expect(
       probeCff(

packages/pdf-codec/src/cff-probe.ts

@@ -48,9 +48,10 @@ export function probeCff(
   }
 
   const nameIndex = readCffIndex(bytes, headerSize);
-  if (nameIndex === undefined || nameIndex.count === 0) {
+  if (nameIndex === undefined) {
     return undefined;
   }
+  // No separate `nameIndex.count === 0` check: readCffIndex's own contract guarantees entry(0) is undefined whenever count is 0 (an empty INDEX's entry() always returns undefined -- see its own zero-count branch), so this one check already covers both an empty FontSet and a genuinely unreadable first entry.
   const nameBytes = nameIndex.entry(0);
   if (nameBytes === undefined) {
     return undefined;

packages/pdf-codec/src/crypto/rc4.ts

@@ -8,10 +8,8 @@ export function rc4(
   key: Uint8Array<ArrayBuffer>,
   data: Uint8Array<ArrayBuffer>,
 ): Uint8Array<ArrayBuffer> {
-  const state = new Uint8Array(STATE_SIZE);
-  for (let i = 0; i < STATE_SIZE; i++) {
-    state[i] = i;
-  }
+  // Built by index-mapping rather than a counted for-loop: a typed array silently drops an out-of-range integer-index write, so a loop bound of `i <= STATE_SIZE` here would produce byte-for-byte the same 256-entry state array as `i < STATE_SIZE` -- an equivalent mutant no test could ever distinguish. Uint8Array.from's own length argument leaves no comparison operator for a mutation to target at all.
+  const state = Uint8Array.from({ length: STATE_SIZE }, (_, i) => i);
   // Key-scheduling algorithm. A zero-length key would divide by zero on the modulo below; there is no meaningful RC4 keystream for one, so the input is returned untouched rather than producing garbage under a fabricated key.
   if (key.length === 0) {
     return Uint8Array.from(data);
@@ -23,17 +21,17 @@ export function rc4(
     state[i] = state[j]!;
     state[j] = swap;
   }
-  // Pseudo-random generation algorithm, XORed straight over the input.
+  // Pseudo-random generation algorithm, XORed straight over the input. Driven by data.forEach rather than a counted for-loop: an off-by-one bound here would run one extra round of state/x/y mutation whose own output write then lands one past `out`'s own length -- a typed array silently drops that write, so the extra round's only effect is on `state`/`x`/`y`, which nothing reads after the function returns. A test could never observe the difference either way; forEach's own iteration count leaves no comparison for a mutation to target.
   const out = new Uint8Array(data.length);
   let x = 0;
   let y = 0;
-  for (let n = 0; n < data.length; n++) {
+  data.forEach((byte, n) => {
     x = (x + 1) & 0xff;
     y = (y + state[x]!) & 0xff;
     const swap = state[x]!;
     state[x] = state[y]!;
     state[y] = swap;
-    out[n] = data[n]! ^ state[(state[x]! + state[y]!) & 0xff]!;
-  }
+    out[n] = byte ^ state[(state[x]! + state[y]!) & 0xff]!;
+  });
   return out;
 }