import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { DatabaseSync } from "node:sqlite"; import { deflateSync } from "node:zlib"; import { strToU8, zipSync } from "fflate"; import { afterEach, expect, it, vi } from "vitest"; import { Devdocs } from "../src/engine.ts"; import type { RegisteredSource } from "../src/types.ts"; const engines: Devdocs[] = []; const roots: string[] = []; afterEach(async () => { for (const d of engines.splice(0)) await d.close(); for (const p of roots.splice(0)) await rm(p, { recursive: true, force: true }); vi.restoreAllMocks(); }); async function root() { const p = await mkdtemp(join(tmpdir(), "devdocs-registered-")); roots.push(p); return p; } function engine(path: string, source: RegisteredSource) { const d = new Devdocs({ databasePath: join(path, "cache.db"), sources: [source], enabledSources: [source.id], offline: !source.url, cacheBytes: 4 * 1024 * 1024, ttlMs: 60000, }); engines.push(d); return d; } async function searchRead( d: Devdocs, target: string, query: string, cwd: string, ) { const found = await d.search({ target, query, cwd }); expect(found.status).toBe("ok"); if (found.status !== "ok") throw new Error(JSON.stringify(found)); return d.read( found.results.map((x) => x.ref), 10000, cwd, ); } it("reads a configured Javadoc archive through the normal registered URL adapter", async () => { const p = await root(); const archive = zipSync({ "api/Widget.html": strToU8( '

Widget

commit()

Atomic commit operation.

', ), }); const fetch = vi.spyOn(globalThis, "fetch").mockResolvedValue( new Response(archive, { headers: { "content-type": "application/java-archive" }, }), ); const d = engine(p, { id: "java-docs", target: "widget", path: "", url: "https://docs.example/widget.jar", version: "1.0", format: "javadoc", private: false, }); const read = await searchRead(d, "widget", "commit", p); expect(read.sections.map((s) => s.content).join("\n")).toContain( "Atomic commit", ); expect(fetch).toHaveBeenCalledTimes(1); }); it("indexes installed docset symbols without attaching the foreign SQLite index to the cache", async () => { const p = await root(); const bundle = join(p, "Widget.docset"), resources = join(bundle, "Contents", "Resources"); await mkdir(join(resources, "Documents"), { recursive: true }); await writeFile( join(resources, "Documents", "Widget.html"), "

Widget

commit

Atomic commit from installed docset.

", ); const index = new DatabaseSync(join(resources, "docSet.dsidx")); index.exec( "CREATE TABLE searchIndex(id INTEGER PRIMARY KEY,name TEXT,type TEXT,path TEXT); INSERT INTO searchIndex VALUES(1,'commit','Method','Widget.html#commit');", ); index.close(); const d = engine(p, { id: "bundle", target: "widget", path: bundle, version: "1.0", format: "docset", private: false, }); const read = await searchRead(d, "widget", "commit", p); expect(read.sections.map((s) => s.content).join("\n")).toContain( "installed docset", ); }); it("reads registered documentation trees and structured glyph keys", async () => { const p = await root(); const docs = join(p, "docs"); await mkdir(docs); await writeFile( join(docs, "glyphs.json"), JSON.stringify({ "md-brain": { code: "f09d1", char: "X" } }), ); const d = engine(p, { id: "icons", target: "icons", path: docs, version: null, format: "markdown", private: false, }); const read = await searchRead(d, "icons", "md-brain", p); expect(read.sections[0]?.content).toContain("f09d1"); }); it("discovers installed dependency READMEs with package version evidence, without imports", async () => { const p = await root(); const pkg = join(p, "node_modules", "documentation-fixture"); await mkdir(pkg, { recursive: true }); await writeFile( join(pkg, "package.json"), JSON.stringify({ name: "documentation-fixture", version: "2.4.1" }), ); await writeFile( join(pkg, "README.md"), "# Transactions\n\nAtomic rollback reference.", ); const d = new Devdocs({ databasePath: join(p, "cache.db"), sources: [], enabledSources: ["local"], offline: true, cacheBytes: 1048576, ttlMs: 60000, }); engines.push(d); const found = await d.search({ target: "documentation-fixture", query: "atomic rollback", version: "2.4.1", cwd: p, }); expect(found.status).toBe("ok"); if (found.status !== "ok") throw new Error(JSON.stringify(found)); expect(found.results[0]?.version).toBe("2.4.1"); expect( (await d.read([found.results[0]!.ref])).sections[0]?.content, ).toContain("Atomic rollback"); }); it("rebuilds a recognized cache after logical FTS corruption, retaining source recovery", async () => { const p = await root(); const path = join(p, "manual.md"); await writeFile(path, "# Transactions\nAtomic commit reference."); const source: RegisteredSource = { id: "manual", target: "widget", path, format: "markdown", version: "1", private: false, }; const first = engine(p, source); await searchRead(first, "widget", "commit", p); await first.close(); const db = new DatabaseSync(join(p, "cache.db"), { defensive: false }); db.prepare("UPDATE section_fts_data SET block=? WHERE id=1").run( new Uint8Array([0]), ); db.close(); const next = engine(p, source); const read = await searchRead(next, "widget", "commit", p); expect(read.sections[0]?.content).toContain("Atomic commit"); }); it("searches different terms in a completely cached remote document after an offline restart", async () => { const p = await root(); const fetch = vi .spyOn(globalThis, "fetch") .mockResolvedValue( new Response( "# Guide\n\nAlpha reference and beta reference share one complete document.", { headers: { "content-type": "text/markdown" } }, ), ); const online = engine(p, { id: "remote", target: "guide", path: "", url: "https://docs.example/guide.md", version: null, format: "markdown", private: false, }); await searchRead(online, "guide", "alpha", p); await online.close(); fetch.mockClear(); fetch.mockRejectedValue(new Error("network must not run")); const offline = new Devdocs({ ...online.options, offline: true }); engines.push(offline); const read = await searchRead(offline, "guide", "beta", p); expect(read.sections[0]?.content).toContain("beta reference"); expect(fetch).not.toHaveBeenCalled(); }); it("isolates query-selected remote archive pages rather than reusing another query's subset", async () => { const p = await root(); const pages: Record = {}; for (let i = 0; i < 14; i++) pages["api/Other" + i + ".html"] = strToU8( "

Other

Other reference.

", ); pages["api/First.html"] = strToU8( "

First

First operation reference.

", ); pages["api/Zebra.html"] = strToU8( "

Zebra

Zebra operation reference.

", ); const archive = zipSync(pages); const fetch = vi.spyOn(globalThis, "fetch").mockImplementation( async () => new Response(archive, { headers: { "content-type": "application/java-archive" }, }), ); const docs = engine(p, { id: "archive", target: "widget", path: "", url: "https://docs.example/widget.jar", version: null, format: "javadoc", private: false, }); expect( (await searchRead(docs, "widget", "First", p)).sections[0]?.content, ).toContain("First operation"); await docs.close(); const reopened = new Devdocs(docs.options); engines.push(reopened); expect( (await searchRead(reopened, "widget", "Zebra", p)).sections[0]?.content, ).toContain("Zebra operation"); expect(fetch).toHaveBeenCalledTimes(2); }); it("rebuilds malformed discovery metadata in an owned cache", async () => { const p = await root(), path = join(p, "manual.md"); await writeFile(path, "# Transactions\nAtomic metadata recovery reference."); const source: RegisteredSource = { id: "manual", target: "widget", path, format: "markdown", version: null, private: false, }; const first = engine(p, source); await searchRead(first, "widget", "metadata", p); await first.close(); const db = new DatabaseSync(join(p, "cache.db")); db.exec("UPDATE lookups SET candidates='{'"); db.close(); const read = await searchRead(engine(p, source), "widget", "metadata", p); expect(read.sections[0]?.content).toContain("Atomic metadata recovery"); }); it.each(["sphinx", "javadoc", "doxygen"] as const)( "follows a local %s index to documentation bodies, not discovery metadata", async (format) => { const p = await root(); const directory = join(p, "docs"); await mkdir(join(directory, "api"), { recursive: true }); await writeFile( join(directory, "api", "Widget.html"), '

Widget

commit()

Atomic indexed commit body.

', ); let path: string; if (format === "sphinx") { path = join(directory, "objects.inv"); await writeFile( path, Buffer.concat([ Buffer.from( "# Sphinx inventory version 2\n# Project: Widget\n# Version: 1.0\n# The remainder of this file is compressed using zlib.\n", ), deflateSync("Widget.commit py:method 1 api/Widget.html#commit() -\n"), ]), ); } else if (format === "javadoc") { path = join(directory, "member-search-index.js"); await writeFile( path, 'memberSearchIndex = [{"p":"api","c":"Widget","l":"commit()"}];updateSearchResults();', ); } else { path = join(directory, "index.tag"); await writeFile( path, 'Widgetapi/Widget.htmlcommitapi/Widget.htmlcommit()()', ); } const docs = engine(p, { id: "indexed", target: "widget", path, format, version: "1.0", private: false, }); const read = await searchRead(docs, "widget", "commit", p); expect(read.sections.map((s) => s.content).join("\n")).toContain( "Atomic indexed commit body", ); expect( read.sections.some((s) => s.content.includes("Inventory only")), ).toBe(false); }, ); it("refuses an unrelated user SQLite file rather than rebuilding it", async () => { const p = await root(), path = join(p, "manual.md"); await writeFile(path, "# Transactions\nAtomic commit."); const db = new DatabaseSync(join(p, "cache.db")); db.exec( "CREATE TABLE user_data(secret TEXT);INSERT INTO user_data VALUES('do not delete');", ); db.close(); const d = engine(p, { id: "manual", target: "widget", path, format: "markdown", version: null, private: false, }); await expect( d.search({ target: "widget", query: "commit", cwd: p }), ).rejects.toThrow(/refused/); const verify = new DatabaseSync(join(p, "cache.db"), { readOnly: true }); expect(verify.prepare("SELECT secret FROM user_data").get()?.["secret"]).toBe( "do not delete", ); verify.close(); });