test(documents.js): work toward 100% mutation score

packages/documents.js/src/bin-dispatch.ts

@@ -26,13 +26,15 @@ const RUNNERS: Readonly<Record<PackageManager, RunnerSpec>> = {
 };
 
 function detectPackageManager(userAgent: string | undefined): PackageManager {
-  const ua = userAgent ?? "";
-  if (ua.startsWith("yarn/")) {
+  // No npm_config_user_agent at all (Deno never sets it; running the bin via bare `node` sets nothing) falls back to npm exactly like every other unrecognised value below -- handled as its own branch, rather than defaulting `userAgent` to an empty string first, so there is no fallback string literal whose own value is unobservable (every one of the startsWith checks below is false for it) and therefore untestable.
+  if (userAgent === undefined) return "npm";
+
+  if (userAgent.startsWith("yarn/")) {
     // Yarn classic (1.x) has no `dlx` subcommand -- it is Yarn Berry (2+) only -- so classic is treated as npm and runs through npx rather than a command that fails.
-    return ua.startsWith("yarn/1.") ? "npm" : "yarn";
+    return userAgent.startsWith("yarn/1.") ? "npm" : "yarn";
   }
-  if (ua.startsWith("pnpm/")) return "pnpm";
-  if (ua.startsWith("bun/")) return "bun";
+  if (userAgent.startsWith("pnpm/")) return "pnpm";
+  if (userAgent.startsWith("bun/")) return "bun";
   // npm, and any agent that doesn't identify itself (Deno doesn't set this env var at all; running the bin via bare `node` sets nothing), falls back to npx.
   return "npm";
 }

packages/documents.js/src/bin.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it, vi } from "vitest";
+
+// bin.ts is a real executable entry point: importing it runs its top-level code immediately, which spawns a child process and calls process.exit. Every test here mocks node:child_process's spawnSync and stubs process.exit/argv/env before a fresh dynamic import, then restores them.
+
+interface SpawnSyncCall {
+  readonly command: string;
+  readonly args: readonly string[];
+  readonly options: unknown;
+}
+
+async function runBin(
+  argv: readonly string[],
+  userAgent: string | undefined,
+  status: number | null,
+): Promise<{ readonly call: SpawnSyncCall; readonly exitCode: unknown }> {
+  vi.resetModules();
+  let call: SpawnSyncCall | undefined;
+  vi.doMock("node:child_process", () => ({
+    spawnSync: (command: string, args: readonly string[], options: unknown) => {
+      call = { command, args, options };
+      return { status };
+    },
+  }));
+  const exitSpy = vi.spyOn(process, "exit").mockImplementation(() => {
+    return undefined as never;
+  });
+  const originalArgv = process.argv;
+  const originalUserAgent = process.env.npm_config_user_agent;
+  process.argv = ["node", "documents.js", ...argv];
+  if (userAgent === undefined) {
+    delete process.env.npm_config_user_agent;
+  } else {
+    process.env.npm_config_user_agent = userAgent;
+  }
+  try {
+    await import("./bin");
+  } finally {
+    process.argv = originalArgv;
+    if (originalUserAgent === undefined) {
+      delete process.env.npm_config_user_agent;
+    } else {
+      process.env.npm_config_user_agent = originalUserAgent;
+    }
+  }
+  if (call === undefined) {
+    throw new Error("expected spawnSync to have been called");
+  }
+  const exitCode = exitSpy.mock.calls[0]?.[0];
+  exitSpy.mockRestore();
+  vi.doUnmock("node:child_process");
+  return { call, exitCode };
+}
+
+describe("bin", () => {
+  it("strips the node/script argv[0..1] before resolving dispatch, not the full argv", () => {
+    return runBin(["mcp"], "npm/10.2.4 node/v20", 0).then(({ call }) => {
+      // Without process.argv.slice(2), argv[0] would be "node" (not "mcp"), never triggering the mcp dispatch path -- this only resolves to document-mcp because the strip happened.
+      expect(call.command).toBe("npx");
+      expect(call.args).toEqual(["-y", "document-mcp"]);
+    });
+  });
+
+  it("spawns with the exact resolved args array and { stdio: 'inherit' } options", () => {
+    return runBin(["convert", "a.docx"], "npm/10.2.4 node/v20", 0).then(
+      ({ call }) => {
+        expect(call.args).toEqual(["-y", "document-cli", "convert", "a.docx"]);
+        expect(call.options).toEqual({ stdio: "inherit" });
+      },
+    );
+  });
+
+  it("exits with the spawned process's own non-zero status, not always the same code", () => {
+    return runBin([], "npm/10.2.4 node/v20", 2).then(({ exitCode }) => {
+      expect(exitCode).toBe(2);
+    });
+  });
+
+  it("exits with 1 when spawnSync reports no status at all (e.g. killed by a signal)", () => {
+    return runBin([], "npm/10.2.4 node/v20", null).then(({ exitCode }) => {
+      expect(exitCode).toBe(1);
+    });
+  });
+});

packages/documents.js/src/codecs/read.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it, vi } from "vitest";
+import { CONTENT_READERS, readDocumentLayout } from "./read";
+import { encodeMarkdownText } from "../markdown/text";
+
+describe("CONTENT_READERS.markdown", () => {
+  it("forwards the images resolver through to readMarkdownContent", () => {
+    const resolver = vi.fn(() => undefined);
+    CONTENT_READERS.markdown(encodeMarkdownText("![alt](img.png)"), {
+      images: resolver,
+    });
+    expect(resolver).toHaveBeenCalledWith("img.png", expect.anything());
+  });
+
+  it("forwards the abort signal through to readMarkdownContent, which checks it before parsing", () => {
+    const controller = new AbortController();
+    controller.abort();
+    let caught: unknown;
+    try {
+      CONTENT_READERS.markdown(encodeMarkdownText("hi"), {
+        signal: controller.signal,
+      });
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toBeInstanceOf(DOMException);
+    expect((caught as DOMException).name).toBe("AbortError");
+  });
+});
+
+describe("CONTENT_READERS.rtf", () => {
+  it("forwards the abort signal through to readRtfContent, which checks it before tokenizing", () => {
+    const controller = new AbortController();
+    controller.abort();
+    let caught: unknown;
+    try {
+      CONTENT_READERS.rtf(new TextEncoder().encode("{\\rtf1 hi}"), {
+        signal: controller.signal,
+      });
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toBeInstanceOf(DOMException);
+    expect((caught as DOMException).name).toBe("AbortError");
+  });
+});
+
+describe("readDocumentLayout", () => {
+  it("forwards the signal option through to readPdf, which checks it before parsing", () => {
+    const controller = new AbortController();
+    controller.abort();
+    // A real "%PDF-" header but otherwise garbage bytes: readPdf checks the header first, then the abort signal, before it ever opens the document -- if the signal were not forwarded (an empty options object), this would fail trying to parse the document instead.
+    const bytes = new TextEncoder().encode("%PDF-1.4\n%garbage");
+    let caught: unknown;
+    try {
+      readDocumentLayout(bytes, { signal: controller.signal });
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toBeInstanceOf(DOMException);
+    expect((caught as DOMException).name).toBe("AbortError");
+  });
+});

packages/documents.js/src/codecs/registry.test.ts

@@ -7,7 +7,7 @@ import type {
 import { PAGE_SIZE_LETTER } from "document-schema.js";
 import { describe, expect, it } from "vitest";
 import type { XlsContentDocument } from "xls-codec";
-import { odsToXlsx } from "../convert/convert";
+import { docxToPdf, odsToXlsx } from "../convert/convert";
 import { readOdfFormulaContent } from "../odf/formula/read";
 import { FRACTION_FORMULA, odfFormulaBytes } from "../test-support/odf";
 import { minimalDocxBytes } from "../test-support/docx";
@@ -300,6 +300,18 @@ describe("DOCUMENT_FORMAT_CODECS: content read/write round trips", () => {
     expect(roundTripped).toEqual(expected);
   });
 
+  it("xls: content.write refuses a non-spreadsheet ContentDocument by name", () => {
+    const codec = requireContentCodec("xls");
+    const wordprocessing: ContentDocument = {
+      kind: "wordprocessing",
+      metadata: {},
+      sections: [],
+    };
+    expect(() => codec.write!(wordprocessing)).toThrow(
+      "DOCUMENT_FORMAT_CODECS.xls.content.write: expected a spreadsheet ContentDocument",
+    );
+  });
+
   // Mirrors ppt-codec's own write.test.ts fixture shape. The writer's own scope is text-box slides only (see that package's README scope note); like pptx/odp above, a black-box substantive-text check is the right-scoped proof of wiring here rather than exact equality -- ppt-codec's own reader always reports PowerPoint's fixed default text insets (0.1in left/right, 0.05in top/bottom) regardless of what a shape actually carries, since it does not yet read a shape's own OfficeArtFOPT inset override (see read.ts's own DEFAULT_INSET_LEFT_RIGHT_PT/DEFAULT_INSET_TOP_BOTTOM_PT comment), a pre-existing, documented gap this registry wiring did not introduce.
   it("ppt: read -> write -> read carries the source slide text through", () => {
     const codec = requireContentCodec("ppt");
@@ -353,6 +365,16 @@ describe("DOCUMENT_FORMAT_CODECS: pdf has a layout codec, not a content codec",
     expect(DOCUMENT_FORMAT_CODECS.pdf.content).toBeUndefined();
     expect(DOCUMENT_FORMAT_CODECS.pdf.layout).toBeDefined();
   });
+
+  it("layout.write forwards the abort signal through to writePdf's own per-page check", () => {
+    const codec = DOCUMENT_FORMAT_CODECS.pdf.layout!;
+    const layout = codec.read(docxToPdf(minimalDocxBytes()));
+    const controller = new AbortController();
+    controller.abort();
+    expect(() => {
+      codec.write(layout, { signal: controller.signal });
+    }).toThrow(DOMException);
+  });
 });
 
 describe("DOCUMENT_FORMAT_CODECS: xlsx has a content codec, no layout codec", () => {

packages/documents.js/src/convert/bridges.test.ts

@@ -616,6 +616,20 @@ describe("ods <-> xlsx: ods -> xlsx (one hop, the character-width-unit conversio
     const original = odsContentOf(richOdsBytes());
     const originalSheet = original.sheets[0]!;
 
+    // The source ODS fixture's own header row and every cell's rendered displayText: buildRichFixturePackage (test-support/ods.ts) writes a distinct text:p run for every cell alongside its office:value, and none of it is exercised by any assertion below (those check only the CONVERTED xlsx side's `.value`) -- so a header cell silently losing its label, or a cell's displayText silently losing its rendered text, would go undetected without checking the source fixture directly.
+    expect(cellAt(originalSheet, 0, 0)?.displayText).toBe("Name");
+    expect(cellAt(originalSheet, 0, 1)?.displayText).toBe("Amount");
+    expect(cellAt(originalSheet, 0, 2)?.displayText).toBe("Active");
+    expect(cellAt(originalSheet, 1, 0)?.displayText).toBe("Widget");
+    expect(cellAt(originalSheet, 1, 1)?.displayText).toBe("42.5");
+    expect(cellAt(originalSheet, 1, 2)?.displayText).toBe("TRUE");
+    expect(cellAt(originalSheet, 2, 0)?.displayText).toBe("15%");
+    expect(cellAt(originalSheet, 2, 1)?.displayText).toBe("$9.99");
+    expect(cellAt(originalSheet, 2, 2)?.displayText).toBe("2026-01-15");
+    expect(cellAt(originalSheet, 3, 0)?.displayText).toBe("14:30");
+    expect(cellAt(originalSheet, 3, 1)?.displayText).toBe("85");
+    expect(cellAt(originalSheet, 4, 0)?.displayText).toBe("Merged Cell");
+
     const xlsxBytes = odsToXlsx(richOdsBytes());
     const xlsx = xlsxContentOf(xlsxBytes);
     const sheet = xlsx.sheets[0]!;
@@ -624,6 +638,14 @@ describe("ods <-> xlsx: ods -> xlsx (one hop, the character-width-unit conversio
       kind: "string",
       value: "Name",
     });
+    expect(cellAt(sheet, 0, 1)?.value).toEqual({
+      kind: "string",
+      value: "Amount",
+    });
+    expect(cellAt(sheet, 0, 2)?.value).toEqual({
+      kind: "string",
+      value: "Active",
+    });
     expect(cellAt(sheet, 1, 0)?.value).toEqual({
       kind: "string",
       value: "Widget",

packages/documents.js/src/convert/convert-fonts.test.ts

@@ -4,7 +4,10 @@ import type { FontSubstitution } from "pdf-codec";
 import { createStandardFontMeasurer, loadMathFont, writePdf } from "pdf-codec";
 const mathMetricsAt = (sizePt: number) => loadMathFont().metricsAt(sizePt);
 import { decodePackage as decodeOdfPackage } from "odf.js";
-import { encodePackage as encodeOoxmlPackage } from "ooxml.js";
+import {
+  decodePackage as decodeOoxmlPackage,
+  encodePackage as encodeOoxmlPackage,
+} from "ooxml.js";
 import { openDocx } from "../edit/docx/editor";
 import { openPptx } from "../edit/pptx/editor";
 import { buildDocumentBytes } from "./from-package";
@@ -146,6 +149,21 @@ describe("X -> PDF: caller-supplied faces", () => {
     });
     expect(substitutions).toEqual([]);
   });
+
+  it("standardFontDocxBytes genuinely requests Arial, not merely a request no vendored substitute happens to claim", () => {
+    const content = readDocxContent(
+      decodeOoxmlPackage(standardFontDocxBytes()),
+    );
+    if (content.kind !== "wordprocessing") {
+      throw new Error("expected a wordprocessing ContentDocument");
+    }
+    const paragraph = content.sections[0]?.blocks[0];
+    expect(
+      paragraph?.kind === "paragraph"
+        ? paragraph.runs[0]?.fontFamily
+        : undefined,
+    ).toBe("Arial");
+  });
 });
 
 // The backward-compatibility guarantee this phase had to keep: wiring a FontRegistry into all six conversions must not change a single byte of output for a document that embeds no fonts and asks for no family a vendored substitute claims. Each reference below reproduces the exact pre-registry pipeline -- createStandardFontMeasurer() into the format's own layout engine, then writePdf with no `fonts` option at all -- so this is a genuine before/after byte comparison rather than a self-consistency check of the new code against itself.

packages/documents.js/src/convert/document-fonts.test.ts

@@ -72,5 +72,6 @@ describe("extractSourceFontsForFormat", () => {
       );
     }
     expect(caught.format).toBe("xlsx");
+    expect(caught.name).toBe("UnsupportedFontSourceFormatError");
   });
 });