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(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( "

Transactions

Atomic transactions commit safely.

", { headers: { etag: '"transactions-1"' } }, ); if (url.endsWith("install.html")) return new Response( "

Installation

Installation instructions.

", ); 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(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( 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( 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", }); });