repositories / pi-ext
pi-ext
bugabingas pi extensions
owned by admin
extensions/devdocs/__serial__/formats.test.ts
Rawimport { 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>🚀 < &</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);
});