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