repositories / pi-ext
pi-ext
bugabingas pi extensions
owned by admin
extensions/devdocs/__serial__/registered.test.ts
Rawimport { 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(
'<h1>Widget</h1><h2 id="commit()">commit()</h2><p>Atomic commit operation.</p>',
),
});
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"),
"<h1>Widget</h1><h2>commit</h2><p>Atomic commit from installed docset.</p>",
);
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<string, Uint8Array> = {};
for (let i = 0; i < 14; i++)
pages["api/Other" + i + ".html"] = strToU8(
"<h1>Other</h1><p>Other reference.</p>",
);
pages["api/First.html"] = strToU8(
"<h1>First</h1><p>First operation reference.</p>",
);
pages["api/Zebra.html"] = strToU8(
"<h1>Zebra</h1><p>Zebra operation reference.</p>",
);
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"),
'<h1>Widget</h1><h2 id="commit()">commit()</h2><p>Atomic indexed commit body.</p>',
);
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,
'<tagfile><compound kind="class"><name>Widget</name><filename>api/Widget.html</filename><member kind="function"><name>commit</name><anchorfile>api/Widget.html</anchorfile><anchor>commit()</anchor><arglist>()</arglist></member></compound></tagfile>',
);
}
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();
});