Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

extensions/devdocs/__serial__/formats.test.ts

Raw
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 =
		'<h1 id="symbol">Symbol</h1><pre>````\n# code</pre><script>throw Error("executed")</script>';
	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("<p>&#x1f680; &lt; &amp;</p>")).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("<Wrapper");
	expect(body).toContain("Text {dangerous()} {{macro}}");
	expect(body).toContain("`<Keep />`");
	expect(readFormat("<https://example.test/docs>", "mdx")[0]?.body).toContain(
		"<https://example.test/docs>",
	);
	expect(body).toContain(
		["import Keep", 'from "keep";\n<Component />'].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    <script>dangerous()</script>\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("<script>dangerous()</script>");
	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<string, string>): 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`,
			`<h1 id="type">Type${i}</h1><p>body</p>`,
		]),
	);
	files["api/Wanted.html"] =
		'<h1 id="method">Wanted</h1><p>Wanted method reference.</p><script>execute()</script>';
	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);
});