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 = '

Symbol

````\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("`"); expect(readFormat("", "mdx")[0]?.body).toContain( "", ); expect(body).toContain( ["import Keep", 'from "keep";\n'].join(" "), ); expect(body).toMatch(/unsupported inert text/); expect(sections.map((section) => section.heading)).toEqual([ "Guide", "Guide > End", ]); }); it("reads RST adornments/literals without executing directives or substitutions", () => { const input = "=====\nGuide\n=====\n\nLiteral::\n\n # not heading\n ```\n\nChild\n-----\n.. include:: /etc/passwd\n\n.. raw:: html\n\n \n\n|macro| survives"; const sections = readFormat(input, "rst"); expect(sections.map((section) => section.heading)).toEqual([ "Guide", "Guide > Child", ]); const body = sections.map((section) => section.body).join("\n"); expect(body).toContain(" # not heading\n ```"); expect(body).toContain(".. include:: /etc/passwd"); expect(body).toContain(""); expect(body).toContain("|macro| survives"); expect(body).toMatch(/directive unsupported/); }); it("retains exact JSON glyphs, browser keys, URLs and structured provenance", () => { const glyph = { "nf-md-test/~": { char: "󰀀", code: "f0000", source: "https://example.test/glyphs", }, }; const [section] = readFormat(JSON.stringify(glyph), "json"); expect(section?.locator).toBe("/nf-md-test~1~0"); expect(JSON.parse(section?.body ?? "null")).toEqual(glyph["nf-md-test/~"]); const compat = { api: { Widget: { __compat: { mdn_url: "https://developer.mozilla.org/en-US/docs/Web/API/Widget", source_file: "api/Widget.json", support: { chrome_android: { version_added: "110" }, safari_ios: [ { version_added: "16.4", partial_implementation: true }, ], firefox: { version_added: false }, }, }, }, }, }; const entries = readFormat(JSON.stringify(compat), "json"); expect(entries).toHaveLength(1); expect(entries[0]?.locator).toBe("/api/Widget/__compat"); expect(JSON.parse(entries[0]?.body ?? "null")).toEqual( compat.api.Widget.__compat, ); expect(() => readFormat("{broken", "json")).toThrow(); }); function archive(files: Record): Uint8Array { return zipSync( Object.fromEntries( Object.entries(files).map(([name, body]) => [name, strToU8(body)]), ), ); } function centralOffset(zip: Uint8Array): number { const view = new DataView(zip.buffer, zip.byteOffset, zip.byteLength); return view.getUint32(zip.length - 6, true); } function forgedSize(zip: Uint8Array, size: number): Uint8Array { const copy = zip.slice(); const view = new DataView(copy.buffer); view.setUint32(22, size, true); view.setUint32(centralOffset(copy) + 24, size, true); return copy; } it("selects at most ten relevant JAR HTML entries, retaining entry/anchor provenance", async () => { const files = Object.fromEntries( Array.from({ length: 14 }, (_, i) => [ `api/Type${i}.html`, `

Type${i}

body

`, ]), ); files["api/Wanted.html"] = '

Wanted

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); });