Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

extensions/devdocs/__serial__/providers.test.ts

Raw
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, expect, it, vi } from "vitest";
import { context7Adapter } from "../src/adapters/context7.ts";
import { devdocsAdapter } from "../src/adapters/devdocs.ts";
import { createNetwork } from "../src/adapters/network.ts";
import { Devdocs } from "../src/engine.ts";
import type { Adapter, Request } from "../src/types.ts";

const owned: { engine: Devdocs; root: string }[] = [];
afterEach(async () => {
	for (const { engine, root } of owned.splice(0)) {
		await engine.close();
		await rm(root, { recursive: true, force: true });
	}
});
const request: Request = {
	cwd: tmpdir(),
	target: "Widget",
	query: "transactions",
};
const json = (value: unknown, headers?: HeadersInit) =>
	new Response(JSON.stringify(value), headers ? { headers } : {});
async function engine(adapter: Adapter) {
	const root = await mkdtemp(join(tmpdir(), "devdocs-providers-"));
	const instance = new Devdocs(
		{
			databasePath: join(root, "cache.db"),
			enabledSources: [adapter.id],
			sources: [],
			offline: false,
			cacheBytes: 8 * 1024 * 1024,
			ttlMs: 60000,
		},
		[adapter],
	);
	owned.push({ engine: instance, root });
	return instance;
}
function context(query = "transactions", version?: unknown) {
	return {
		codeSnippets: [
			{
				codeTitle: query,
				codeDescription: `Atomic ${query} reference`,
				codeId:
					"https://github.com/acme/widget/blob/v3.2.1/docs/transactions.md#snippet",
				codeList: [{ language: "typescript", code: `db.${query}();` }],
			},
		],
		infoSnippets: [],
		...(version ? { version } : {}),
	};
}

it("searches DevDocs catalog/index/page then reads cached sections, isolating query-specific pages", async () => {
	const fetcher = vi.fn<typeof fetch>(async (input) => {
		const url = String(input);
		if (url.endsWith("docs.json"))
			return json([
				{ name: "Widget", slug: "widget~3", version: "3", release: "3.2.1" },
			]);
		if (url.endsWith("index.json"))
			return json({
				entries: [
					{ name: "transactions", path: "api/transactions#commit" },
					{ name: "installation", path: "install" },
				],
			});
		if (url.endsWith("api/transactions.html"))
			return new Response(
				"<h1>Transactions</h1><p>Atomic transactions commit safely.</p>",
				{ headers: { etag: '"transactions-1"' } },
			);
		if (url.endsWith("install.html"))
			return new Response(
				"<h1>Installation</h1><p>Installation instructions.</p>",
			);
		throw new Error("unexpected fixture URL");
	});
	const adapter = devdocsAdapter({ fetch: fetcher });
	const instance = await engine(adapter);
	const found = await instance.search({ ...request, version: "3" });
	expect(found.status).toBe("ok");
	if (found.status !== "ok") throw new Error(JSON.stringify(found));
	const read = await instance.read([found.results[0]!.ref]);
	expect(read.sections[0]?.content).toContain(
		"Atomic transactions commit safely",
	);
	expect(read.sections[0]?.version).toBe("3.2.1");
	expect(read.sections[0]?.content).toContain(
		"https://devdocs.io/widget~3/api/transactions",
	);
	const second = await instance.search({
		...request,
		query: "installation",
		version: "3",
	});
	expect(second.status).toBe("ok");
	if (second.status !== "ok") throw new Error(JSON.stringify(second));
	expect(
		(await instance.read([second.results[0]!.ref])).sections[0]?.content,
	).toContain("Installation instructions");
	expect(
		fetcher.mock.calls.some(([url]) => String(url).endsWith("db.json")),
	).toBe(false);
	expect(await adapter.discover({ ...request, version: "9999" })).toEqual([]);
});

it("preserves DevDocs name ambiguity rather than silently choosing another docset", async () => {
	const adapter = devdocsAdapter({
		fetch: async () =>
			json([
				{ name: "Widget", slug: "widget~2", release: "2.0" },
				{ name: "Widget", slug: "different-widget~3", release: "3.0" },
			]),
	});
	expect((await (await engine(adapter)).search(request)).status).toBe(
		"ambiguous",
	);
});

it("searches Context7 then reads snippets with original provenance; query changes cannot reuse partial context", async () => {
	const fetcher = vi.fn<typeof fetch>(async (input, init) => {
		expect(new Headers(init?.headers).get("authorization")).toBe(
			"Bearer injected-test-key",
		);
		const url = new URL(String(input));
		return url.pathname.endsWith("search")
			? json({
					results: [
						{ id: "/acme/widget", title: "Widget", privateMetadata: "ignored" },
					],
				})
			: json(context(url.searchParams.get("query") ?? ""));
	});
	const instance = await engine(
		context7Adapter({ fetch: fetcher, apiKey: () => "injected-test-key" }),
	);
	for (const query of ["transactions", "installation"]) {
		const found = await instance.search({ ...request, query });
		expect(found.status).toBe("ok");
		if (found.status !== "ok") throw new Error(JSON.stringify(found));
		const read = await instance.read([found.results[0]!.ref]);
		expect(read.sections[0]?.content).toContain(`db.${query}();`);
		expect(read.sections[0]?.origin).toBe("https://context7.com/acme/widget");
		expect(read.sections[0]?.content).toContain(
			"https://github.com/acme/widget/blob/v3.2.1/docs/transactions.md#snippet",
		);
		expect(JSON.stringify(read)).not.toContain("injected-test-key");
	}
});

it.each([
	undefined,
	{ requested: "v9999", served: null, status: "unverified" },
	{ requested: "v9999", served: "v3.2.1", status: "verified" },
])(
	"rejects HTTP 200 Context7 responses without matching version evidence: %j",
	async (version) => {
		const adapter = context7Adapter({
			fetch: async (input) =>
				String(input).includes("/libs/search")
					? json({ results: [{ id: "/acme/widget", title: "Widget" }] })
					: json(context("transactions", version)),
		});
		expect(await adapter.discover({ ...request, version: "v9999" })).toEqual(
			[],
		);
		expect(
			(await (await engine(adapter)).search({ ...request, version: "v9999" }))
				.status,
		).toBe("unavailable");
	},
);

it.each([undefined, { requested: "3", served: "v3.2.1", status: "verified" }])(
	"accepts Context7 version evidence from pinned snippet URLs or verified envelope: %j",
	async (version) => {
		const adapter = context7Adapter({
			fetch: async (input) =>
				String(input).includes("/libs/search")
					? json({ results: [{ id: "/acme/widget", title: "Widget" }] })
					: json(context("transactions", version)),
		});
		const found = await (await engine(adapter)).search({
			...request,
			version: "3",
		});
		expect(found.status).toBe("ok");
		if (found.status === "ok") expect(found.results[0]?.version).toBe("v3.2.1");
	},
);

it("rejects cross-origin redirects before forwarding authorization, without leaking reflected errors", async () => {
	const fetcher = vi.fn<typeof fetch>(
		async () =>
			new Response(null, {
				status: 302,
				headers: { location: "https://attacker.example/steal?token=test-key" },
			}),
	);
	const adapter = context7Adapter({ fetch: fetcher, apiKey: "test-key" });
	await expect(adapter.discover(request)).rejects.toMatchObject({
		code: "redirect",
		message: "documentation provider: redirect",
	});
	expect(fetcher).toHaveBeenCalledTimes(1);
	expect(String(fetcher.mock.calls[0]?.[0])).toMatch(
		/^https:\/\/context7.com\//,
	);
	expect(fetcher.mock.calls[0]?.[1]?.redirect).toBe("manual");
	const failed = context7Adapter({
		fetch: async () => {
			throw new Error("test-key");
		},
		apiKey: "test-key",
	});
	await expect(failed.discover(request)).rejects.toThrow(
		"documentation provider: network",
	);
});

it("bounds streamed bytes even without Content-Length and cancels oversized streams", async () => {
	const cancel = vi.fn();
	const network = createNetwork("https://context7.com", {
		fetch: async () =>
			new Response(
				new ReadableStream({
					start(controller) {
						controller.enqueue(new Uint8Array(17));
					},
					cancel,
				}),
			),
	});
	await expect(
		network("https://context7.com/api/test", { maxBytes: 16 }),
	).rejects.toMatchObject({ code: "limit" });
	expect(cancel).toHaveBeenCalled();
});

it("bounds fetch and body deadlines even when injected fetch ignores abort; honors caller cancellation", async () => {
	const network = createNetwork("https://context7.com", {
		timeoutMs: 10,
		fetch: () => new Promise(() => {}),
	});
	await expect(
		network("https://context7.com/api/test", { maxBytes: 100 }),
	).rejects.toMatchObject({ code: "timeout" });
	const body = createNetwork("https://context7.com", {
		timeoutMs: 10,
		fetch: async () => new Response(new ReadableStream({ start() {} })),
	});
	await expect(
		body("https://context7.com/api/test", { maxBytes: 100 }),
	).rejects.toMatchObject({ code: "timeout" });
	const controller = new AbortController();
	const pending = network("https://context7.com/api/test", {
		maxBytes: 100,
		signal: controller.signal,
	});
	controller.abort();
	await expect(pending).rejects.toMatchObject({ code: "aborted" });
});

it("uses HTTP validators, strips reflected credentials, and honors Retry-After without retries", async () => {
	let calls = 0;
	const network = createNetwork("https://context7.com", {
		fetch: async (_url, init) => {
			calls++;
			if (calls === 1)
				return new Response("test-key", {
					headers: {
						etag: '"e1"',
						"last-modified": "Wed, 01 Jan 2025 00:00:00 GMT",
					},
				});
			expect(new Headers(init?.headers).get("if-none-match")).toBe('"e1"');
			expect(new Headers(init?.headers).has("if-modified-since")).toBe(true);
			return new Response(null, { status: 304 });
		},
	});
	const first = await network("https://context7.com/api/test", {
		maxBytes: 100,
		apiKey: "test-key",
	});
	expect(first.text).toBe("[redacted]");
	expect(
		(
			await network("https://context7.com/api/test", {
				maxBytes: 100,
				validator: first.validator,
			})
		).unchanged,
	).toBe(true);
	const fetcher = vi.fn<typeof fetch>(
		async () =>
			new Response("secret-error", {
				status: 429,
				headers: { "retry-after": "30" },
			}),
	);
	const limited = createNetwork("https://context7.com", { fetch: fetcher });
	await expect(
		limited("https://context7.com/api/test", { maxBytes: 100 }),
	).rejects.toMatchObject({ code: "rate-limit", retryAfterMs: 30000 });
	await expect(
		limited("https://context7.com/api/test", { maxBytes: 100 }),
	).rejects.toMatchObject({ code: "rate-limit" });
	expect(fetcher).toHaveBeenCalledTimes(1);
});

it.each([
	"https://github.com/acme/widget/issues/3",
	"https://github.com/acme/widget/blob/main/examples/3/guide.md",
])("rejects incidental numbers as version evidence: %s", async (url) => {
	const data = context();
	data.codeSnippets[0]!.codeId = url;
	const adapter = context7Adapter({
		fetch: async (input) =>
			String(input).includes("/libs/search")
				? json({ results: [{ id: "/acme/widget", title: "Widget" }] })
				: json(data),
	});
	expect(await adapter.discover({ ...request, version: "3" })).toEqual([]);
});

it("removes JSON-escaped injected credentials before content reaches the cache", async () => {
	const data = context();
	data.codeSnippets[0]!.codeDescription = "transactions test-key";
	const adapter = context7Adapter({
		apiKey: "test-key",
		fetch: async (input) =>
			String(input).includes("/libs/search")
				? json({ results: [{ id: "/acme/widget", title: "Widget" }] })
				: new Response(
						JSON.stringify(data).replace("test-key", "\\u0074est-key"),
					),
	});
	const instance = await engine(adapter);
	const found = await instance.search(request);
	expect(found.status).toBe("ok");
	if (found.status !== "ok") throw new Error(JSON.stringify(found));
	expect(
		JSON.stringify(await instance.read([found.results[0]!.ref])),
	).not.toContain("test-key");
});

it("handles many backtick runs within the response byte budget", async () => {
	const data = context();
	data.codeSnippets[0]!.codeList[0]!.code = "`a".repeat(200000);
	const adapter = context7Adapter({
		fetch: async (input) =>
			String(input).includes("/libs/search")
				? json({ results: [{ id: "/acme/widget", title: "Widget" }] })
				: json(data),
	});
	const candidates = await adapter.discover(request);
	const document = await adapter.retrieve(candidates[0]!, request);
	expect(document).not.toBe("unchanged");
	if (document !== "unchanged")
		expect(document.sections[0]?.body).toContain("`a".repeat(100));
});

it("cancels a late response body when an injected fetch ignored the deadline", async () => {
	let resolve!: (response: Response) => void;
	const cancel = vi.fn();
	const network = createNetwork("https://context7.com", {
		timeoutMs: 10,
		fetch: () =>
			new Promise((done) => {
				resolve = done;
			}),
	});
	await expect(
		network("https://context7.com/api/test", { maxBytes: 100 }),
	).rejects.toMatchObject({ code: "timeout" });
	resolve(new Response(new ReadableStream({ cancel })));
	await Promise.resolve();
	expect(cancel).toHaveBeenCalledTimes(1);
});

it("propagates discovery network unavailability instead of fabricating an empty provider catalog", async () => {
	const fetcher: typeof fetch = async () => {
		throw new Error("offline");
	};
	for (const adapter of [
		devdocsAdapter({ fetch: fetcher }),
		context7Adapter({ fetch: fetcher }),
	])
		await expect(adapter.discover(request)).rejects.toMatchObject({
			code: "network",
		});
});