import { execFile } from "node:child_process"; import { readFileSync } from "node:fs"; import { deflateSync } from "node:zlib"; import { strToU8, zipSync } from "fflate"; import { afterEach, expect, it, vi } from "vitest"; import { readContainer } from "../src/containers.ts"; import { htmlMarkdown, readFormat } from "../src/formats.ts"; import { MAX_DOCUMENT_BYTES } from "../src/normalize.ts"; vi.mock("node:child_process", () => ({ execFile: vi.fn() })); afterEach(() => vi.resetAllMocks()); it("preserves nested Markdown fences and static HTML aliases", () => { const markdown = "# Guide\n`````md\n```\n# Not a heading\n```\n`````\n## Actual\nbody"; expect( readFormat(markdown, "markdown").map((section) => section.heading), ).toEqual(["Guide", "Guide > Actual"]); const html = '
````\n# code'; for (const format of ["html", "javadoc", "doxygen", "sphinx"] as const) { const sections = readFormat(html, format); expect(sections[0]?.locator).toBe("symbol"); expect(sections[0]?.body).toContain("````\n# code"); expect(sections[0]?.body).not.toContain("executed"); } expect(htmlMarkdown("
🚀 < &
")).toBe("🚀 < &"); }); it("keeps MDX macros inert while removing imports/wrappers, not code examples", () => { const input = readFileSync( new URL("./fixtures/guide.mdx", import.meta.url), "utf8", ); const sections = readFormat(input, "mdx"); const body = sections.map((section) => section.body).join("\n"); expect(body).not.toContain("example.invalid"); expect(body).not.toContain("body
`, ]), ); files["api/Wanted.html"] = 'Wanted method reference.
'; files["script.js"] = "execute()"; const sections = await readContainer(archive(files), "javadoc", "Wanted"); expect(sections).toHaveLength(10); expect(sections[0]?.locator).toBe("api/Wanted.html#method"); expect(sections.every((section) => !section.body.includes("execute()"))).toBe( true, ); }); it("refuses traversal, bombs, forged-small sizes and stored-size mismatches", async () => { for (const name of [ "../escape.html", "/absolute.html", "a\\escape.html", "%2e%2e/escape.html", "C:escape.html", ]) { await expect( readContainer(archive({ [name]: "text" }), "javadoc", ""), ).rejects.toThrow(/path/); } const zip = archive({ "api.html": "#".repeat(128 * 1024) }); await expect( readContainer(forgedSize(zip, MAX_DOCUMENT_BYTES + 1), "javadoc", ""), ).rejects.toThrow(/8 MiB/); await expect( readContainer(forgedSize(zip, 1), "javadoc", ""), ).rejects.toThrow(); const stored = zipSync({ "api.html": [strToU8("body"), { level: 0 }] }); await expect( readContainer(forgedSize(stored, 1), "javadoc", ""), ).rejects.toThrow(/size mismatch/); const bomb = zipSync({ "api.html": new Uint8Array(MAX_DOCUMENT_BYTES + 1) }); await expect(readContainer(bomb, "javadoc", "")).rejects.toThrow(/8 MiB/); }); it("rejects canonical aliases and malformed offsets", async () => { await expect( readContainer( archive({ "a.html": "body", "%61.html": "alias" }), "javadoc", "", ), ).rejects.toThrow(/path/); const invalid = archive({ "api.html": "body" }); new DataView(invalid.buffer).setUint32( centralOffset(invalid) + 42, 0xffffffff, true, ); await expect(readContainer(invalid, "javadoc", "")).rejects.toThrow(); }); it("bounds archive counts, malformed data, input bytes and cancellation", async () => { const entries = Object.fromEntries( Array.from({ length: 10001 }, (_, i) => [`${i}.txt`, new Uint8Array()]), ); await expect(readContainer(zipSync(entries), "javadoc", "")).rejects.toThrow( /10000/, ); await expect( readContainer(new Uint8Array([1, 2, 3]), "javadoc", ""), ).rejects.toThrow(); await expect( readContainer(new Uint8Array(MAX_DOCUMENT_BYTES + 1), "pdf", ""), ).rejects.toThrow(/8 MiB/); const controller = new AbortController(); controller.abort(); await expect( readContainer(new Uint8Array(), "pdf", "", controller.signal), ).rejects.toThrow(); expect(execFile).not.toHaveBeenCalled(); }); function inventory(body: string, version = "2"): Uint8Array { return Buffer.concat([ Buffer.from( `# Sphinx inventory version ${version}\n# Project: Example\n# Version: 3.1\n# The remainder of this file is compressed using zlib.\n`, ), deflateSync(body), ]); } it("decodes Sphinx v2 discovery metadata, terminal dollar URIs and query selection", async () => { const data = inventory( "pkg.Widget py:class 1 api.html#$ -\npkg.Other py:function -1 other.html Other label\n", ); const sections = await readContainer(data, "sphinx", "Widget"); expect(sections).toHaveLength(1); expect(sections[0]).toMatchObject({ locator: "api.html#pkg.Widget", heading: "pkg.Widget", }); expect(sections[0]?.body).toContain("Inventory only"); expect(sections[0]?.body).toContain("# Project: Example\n# Version: 3.1"); expect((await readContainer(data, "sphinx", "Other"))[0]?.heading).toBe( "Other label", ); expect(await readContainer(data, "sphinx", "absent")).toEqual([]); }); it("rejects unsupported, corrupt, unsafe and over-expanded inventories", async () => { for (const data of [ inventory("bad record"), inventory("", "1"), inventory("pkg py:class 1 javascript:alert(1) -"), inventory("pkg py:class 1 custom:command -"), inventory( Array.from( { length: 10001 }, (_, i) => `symbol${i} py:class 1 api.html -`, ).join("\n"), ), strToU8("# Sphinx inventory version 2\n"), inventory("x".repeat(MAX_DOCUMENT_BYTES + 1)), ]) { await expect(readContainer(data, "sphinx", "")).rejects.toThrow(); } const corrupt = inventory("pkg py:class 1 api.html -"); corrupt[corrupt.length - 1] = (corrupt[corrupt.length - 1] ?? 0) ^ 255; await expect(readContainer(corrupt, "sphinx", "")).rejects.toThrow(); }); it("reports absent pdftotext explicitly using fixed bounded stdin/stdout invocation", async () => { const end = vi.fn(); vi.mocked(execFile).mockImplementation((...args: unknown[]) => { const callback = args[3] as (error: Error, stdout: string) => void; queueMicrotask(() => callback(Object.assign(new Error("missing"), { code: "ENOENT" }), ""), ); return { stdin: { on: vi.fn(), end } } as unknown as ReturnType< typeof execFile >; }); const input = strToU8("%PDF-fixture"); await expect(readContainer(input, "pdf", "not an argument")).rejects.toThrow( /PDF unavailable.*pdftotext/, ); expect(execFile).toHaveBeenCalledWith( "pdftotext", ["-layout", "-enc", "UTF-8", "-", "-"], expect.objectContaining({ timeout: 10000, maxBuffer: MAX_DOCUMENT_BYTES }), expect.any(Function), ); expect(end).toHaveBeenCalledWith(input); });