test: coverage campaign and mutation testing across five packages (#628)

Coverage 83.6 to 87.36% lines, 81.63 to 84.14% branches. Mutation testing across five packages: image-engine 85, media-engine 92, doc-engine 87, shared+enterprise 86, apps/api security and jobs slice. Runs all five lanes weekly. Fixes the silently-broken mutation CI (babel pin), a redact-pdf envelope-shape test bug, an untested enterprise license valid-signature path, and an audit test that only exercised a hand-copied reproduction. Test and config only, no product code changes beyond the babel pin and one test-only oidc export. Full suite: 16,712 pass, 0 fail.
2026-08-03 07:46:42 +02:00 · 2026-07-24 17:36:57 +08:00
parent eee6f0d470
commit 301e6eb01a
129 changed files with 30900 additions and 276 deletions
@@ -1,4 +1,7 @@
-import { pdfcpuAvailable } from "@snapotter/doc-engine";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pdfcpuAvailable, qpdfPageCount } from "@snapotter/doc-engine";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { fixtures, readFixture } from "../../../fixtures/index.js";
 import {
@@ -48,6 +51,26 @@ describe.skipIf(!pdfcpuAvailable())("booklet-pdf (requires pdfcpu)", () => {
    });
    expect(dl.statusCode).toBe(200);
    expect(dl.rawPayload.subarray(0, 5).toString()).toBe("%PDF-");
+
+    // Semantic oracle: verify the booklet was actually imposed, not passed through.
+    // The fixture is a 3-page PDF. A perSheet:2 booklet pads the source up to the
+    // next multiple of 4 (3 -> 4 logical pages), then images them 2-up, so the
+    // output holds 4 / 2 = 2 physical sheet-faces. Asserting the exact count also
+    // proves it differs from a no-op (which would keep the original 3 pages).
+    const dir = mkdtempSync(join(tmpdir(), "booklet-pdf-"));
+    try {
+      const outPath = join(dir, "out.pdf");
+      writeFileSync(outPath, dl.rawPayload);
+
+      const inputPages = await qpdfPageCount(fixtures.document.pdf3);
+      expect(inputPages).toBe(3);
+
+      const outputPages = await qpdfPageCount(outPath);
+      expect(outputPages).toBe(2);
+      expect(outputPages).not.toBe(inputPages);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
  }, 60_000);
 });

@@ -1,6 +1,11 @@
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { pdfcpuAvailable } from "@snapotter/doc-engine";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { fixtures, readFixture } from "../../../fixtures/index.js";
+
 import {
  buildTestApp,
  createMultipartPayload,
@@ -8,6 +13,42 @@ import {
  type TestApp,
 } from "../../test-server.js";

+// Read every page /MediaBox and /CropBox from a PDF buffer via qpdf --json.
+// pdfcpu crop sets a shrunk /CropBox (the visible region) and leaves /MediaBox
+// at the full page size, so the crop oracle compares output CropBox to input
+// MediaBox.
+function pageBoxes(pdfBytes: Buffer): { media: number[][]; crop: number[][] } {
+  const dir = mkdtempSync(join(tmpdir(), "crop-pdf-box-"));
+  try {
+    const p = join(dir, "x.pdf");
+    writeFileSync(p, pdfBytes);
+    const json = execFileSync("qpdf", ["--json", p], { encoding: "utf8", maxBuffer: 1 << 24 });
+    const media: number[][] = [];
+    const crop: number[][] = [];
+    const walk = (node: unknown): void => {
+      if (Array.isArray(node)) {
+        for (const child of node) walk(child);
+        return;
+      }
+      if (node && typeof node === "object") {
+        for (const [k, v] of Object.entries(node)) {
+          if (k === "/MediaBox" && Array.isArray(v) && v.length === 4) {
+            media.push(v.map(Number));
+          } else if (k === "/CropBox" && Array.isArray(v) && v.length === 4) {
+            crop.push(v.map(Number));
+          } else {
+            walk(v);
+          }
+        }
+      }
+    };
+    walk(JSON.parse(json));
+    return { media, crop };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
 const PDF = readFixture(fixtures.document.pdf3);

 let testApp: TestApp;
@@ -48,6 +89,20 @@ describe.skipIf(!pdfcpuAvailable())("crop-pdf (requires pdfcpu)", () => {
    });
    expect(dl.statusCode).toBe(200);
    expect(dl.rawPayload.subarray(0, 5).toString()).toBe("%PDF-");
+
+    // Semantic oracle: cropping with margin 20 must shrink each page's MediaBox.
+    // A no-op passthrough would leave the box unchanged and still pass %PDF-.
+    const input = pageBoxes(PDF);
+    const output = pageBoxes(Buffer.from(dl.rawPayload));
+    expect(input.media.length).toBeGreaterThan(0);
+    // pdfcpu crop adds a shrunk /CropBox to every page.
+    expect(output.crop.length).toBe(input.media.length);
+    const inW = input.media[0][2] - input.media[0][0];
+    const inH = input.media[0][3] - input.media[0][1];
+    for (const b of output.crop) {
+      expect(b[2] - b[0]).toBeLessThan(inW);
+      expect(b[3] - b[1]).toBeLessThan(inH);
+    }
  }, 60_000);
 });

@@ -1,4 +1,7 @@
-import { pdfcpuAvailable } from "@snapotter/doc-engine";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pdfcpuAvailable, qpdfPageCount } from "@snapotter/doc-engine";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { fixtures, readFixture } from "../../../fixtures/index.js";
 import {
@@ -36,7 +39,7 @@ async function runTool(settings: Record<string, unknown>) {
 }

 describe.skipIf(!pdfcpuAvailable())("nup-pdf (requires pdfcpu)", () => {
-  it("arranges pages n-up and produces a valid output", async () => {
+  it("arranges pages 2-up, collapsing a 3-page PDF to 2 sheets", async () => {
    const res = await runTool({ perSheet: 2 });
    expect(res.statusCode).toBe(200);
    const envelope = JSON.parse(res.body);
@@ -48,6 +51,20 @@ describe.skipIf(!pdfcpuAvailable())("nup-pdf (requires pdfcpu)", () => {
    });
    expect(dl.statusCode).toBe(200);
    expect(dl.rawPayload.subarray(0, 5).toString()).toBe("%PDF-");
+
+    // Semantic oracle: 2-up imposition must collapse the 3-page fixture to
+    // ceil(3/2) = 2 sheets. A no-op passthrough would leave 3 pages and still
+    // pass the %PDF- magic check, so assert the actual output page count.
+    const dir = mkdtempSync(join(tmpdir(), "nup-pdf-test-"));
+    try {
+      const outPath = join(dir, "nup.pdf");
+      writeFileSync(outPath, dl.rawPayload);
+      const pages = await qpdfPageCount(outPath);
+      expect(pages).toBe(2);
+      expect(pages).toBeLessThan(3); // fewer sheets than the 3 input pages
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
  }, 60_000);
 });

@@ -1,6 +1,10 @@
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { fixtures, readFixture } from "../../../fixtures/index.js";
-import { hasFitz } from "../../../helpers/python-gate.js";
+import { hasFitz, pythonBin } from "../../../helpers/python-gate.js";
 import {
  buildTestApp,
  createMultipartPayload,
@@ -10,6 +14,41 @@ import {

 const PDF = readFixture(fixtures.document.pdf3);

+/** Build a one-page PDF containing the given text lines, using the same PyMuPDF
+ *  that gates this suite. Only called from fitz-gated tests, so pythonBin is set. */
+function makeTextPdf(lines: string[]): Buffer {
+  const dir = mkdtempSync(join(tmpdir(), "pdf-redact-in-"));
+  const out = join(dir, "doc.pdf");
+  const script = [
+    "import sys, fitz",
+    "d = fitz.open(); p = d.new_page()",
+    "y = 72",
+    "for line in sys.argv[1:-1]:",
+    "    p.insert_text((72, y), line); y += 24",
+    "d.save(sys.argv[-1]); d.close()",
+  ].join("\n");
+  const res = spawnSync(pythonBin as string, ["-c", script, ...lines, out], { encoding: "utf8" });
+  if (res.status !== 0) throw new Error(`could not build text PDF: ${res.stderr}`);
+  return readFileSync(out);
+}
+
+/** Extract the concatenated text layer of a PDF buffer via PyMuPDF, so the test
+ *  can prove what a redacted document does or does not still contain. */
+function extractText(pdf: Buffer): string {
+  const dir = mkdtempSync(join(tmpdir(), "pdf-redact-out-"));
+  const inp = join(dir, "in.pdf");
+  writeFileSync(inp, pdf);
+  const script = [
+    "import sys, fitz",
+    "d = fitz.open(sys.argv[-1])",
+    "sys.stdout.write(''.join(page.get_text() for page in d))",
+    "d.close()",
+  ].join("\n");
+  const res = spawnSync(pythonBin as string, ["-c", script, inp], { encoding: "utf8" });
+  if (res.status !== 0) throw new Error(`could not extract text: ${res.stderr}`);
+  return res.stdout;
+}
+
 let testApp: TestApp;
 let adminToken: string;

@@ -22,9 +61,13 @@ afterAll(async () => {
  await testApp.cleanup();
 }, 10_000);

-async function runTool(settings: Record<string, unknown>) {
+async function runTool(
+  settings: Record<string, unknown>,
+  content: Buffer = PDF,
+  filename = "test-3page.pdf",
+) {
  const { body, contentType } = createMultipartPayload([
-    { name: "file", filename: "test-3page.pdf", contentType: "application/pdf", content: PDF },
+    { name: "file", filename, contentType: "application/pdf", content },
    { name: "settings", content: JSON.stringify(settings) },
  ]);
  return testApp.app.inject({
@@ -41,8 +84,10 @@ describe.skipIf(!hasFitz)("redact-pdf (requires PyMuPDF)", () => {
    expect(res.statusCode).toBe(200);
    const envelope = JSON.parse(res.body);
    expect(envelope.downloadUrl).toBeDefined();
-    expect(envelope.resultPayload).toBeDefined();
-    expect(envelope.resultPayload.found).toBeGreaterThanOrEqual(0);
+    // resultPayload is spread flat into the sync envelope (tool-factory.ts), so
+    // the count lands at envelope.found, not envelope.resultPayload.found.
+    expect(typeof envelope.found).toBe("number");
+    expect(envelope.found).toBeGreaterThanOrEqual(0);

    const dl = await testApp.app.inject({
      method: "GET",
@@ -51,6 +96,36 @@ describe.skipIf(!hasFitz)("redact-pdf (requires PyMuPDF)", () => {
    expect(dl.statusCode).toBe(200);
    expect(dl.rawPayload.subarray(0, 5).toString()).toBe("%PDF-");
  }, 60_000);
+
+  it("removes redacted text from the content layer instead of only masking it", async () => {
+    // Two distinct tokens with no shared substring: one to redact, one to keep.
+    const SECRET = "CLASSIFIED7F3XSECRET";
+    const KEEPER = "PUBLICHEADERLINE";
+    const input = makeTextPdf([KEEPER, SECRET]);
+
+    // Precondition: the input genuinely carries both tokens in its text layer.
+    const before = extractText(input);
+    expect(before).toContain(SECRET);
+    expect(before).toContain(KEEPER);
+
+    const res = await runTool({ terms: [SECRET], caseSensitive: false }, input, "secret.pdf");
+    expect(res.statusCode).toBe(200);
+    const envelope = JSON.parse(res.body);
+    // The term was actually located, not merely a no-op that reports success.
+    // resultPayload spreads flat into the envelope, so the count is envelope.found.
+    expect(envelope.found).toBeGreaterThanOrEqual(1);
+
+    const dl = await testApp.app.inject({ method: "GET", url: envelope.downloadUrl });
+    expect(dl.statusCode).toBe(200);
+    expect(dl.rawPayload.subarray(0, 5).toString()).toBe("%PDF-");
+
+    // The redacted token is gone from the extractable text (true content removal,
+    // not a black box drawn over still-selectable text); untargeted text survives,
+    // proving the redaction is scoped rather than wiping the whole page.
+    const after = extractText(dl.rawPayload);
+    expect(after).not.toContain(SECRET);
+    expect(after).toContain(KEEPER);
+  }, 60_000);
 });

 describe("redact-pdf validation (ungated)", () => {
@@ -1,3 +1,4 @@
+import { execFileSync } from "node:child_process";
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -58,6 +59,44 @@ describe.skipIf(!qpdfAvailable())("rotate-pdf (requires qpdf)", () => {
      writeFileSync(outPath, dl.rawPayload);
      const pages = await qpdfPageCount(outPath);
      expect(pages).toBe(3);
+
+      // Verify pages were actually rotated to the requested 90 degrees.
+      // qpdf 12 --json exposes each page's rotation as a "/Rotate" key.
+      const jsonRaw = execFileSync("qpdf", ["--json", outPath], {
+        encoding: "utf8",
+        maxBuffer: 1 << 24,
+      });
+      const parsed = JSON.parse(jsonRaw) as Record<string, unknown>;
+
+      // Collect every "/Rotate" integer found under the page objects.
+      const rotations: number[] = [];
+      const visit = (node: unknown): void => {
+        if (Array.isArray(node)) {
+          for (const item of node) visit(item);
+          return;
+        }
+        if (node && typeof node === "object") {
+          const obj = node as Record<string, unknown>;
+          const rotate = obj["/Rotate"];
+          if (typeof rotate === "number") rotations.push(rotate);
+          for (const value of Object.values(obj)) visit(value);
+        }
+      };
+      const pageList = (parsed.pages ?? []) as unknown[];
+      visit(pageList);
+
+      if (rotations.length > 0) {
+        // Every rotated page must report the requested 90-degree rotation.
+        expect(rotations.length).toBe(3);
+        for (const rotate of rotations) {
+          expect(rotate).toBe(90);
+        }
+      } else {
+        // Fallback: qpdf nested the rotation elsewhere; assert the raw JSON
+        // carries one "/Rotate": 90 entry per page.
+        const matches = jsonRaw.match(/"\/Rotate":\s*90\b/g) ?? [];
+        expect(matches.length).toBe(3);
+      }
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }