docspack 0.4.0 → 1.1.0

package/dist/local.d.ts

@@ -0,0 +1,67 @@
+import { type SearchHit, type Store } from "./db.js";
+export interface IndexLocalOptions {
+    readonly cwd: string;
+    readonly store: Store;
+    /** Directory of Markdown to index. */
+    readonly from?: string;
+    /** JSON records to index, or `-` for standard input. */
+    readonly json?: string;
+    readonly name?: string;
+    /** Re-index even when no source has changed. */
+    readonly force?: boolean;
+    readonly onProgress?: (message: string) => void;
+}
+export interface IndexLocalResult {
+    readonly id: string;
+    readonly name: string;
+    readonly chunks: number;
+    readonly tokens: number;
+    readonly status: "indexed" | "unchanged";
+    readonly sources: number;
+    /** A corpus read from a stream: nothing on disk to compare it against later. */
+    readonly streamed: boolean;
+    readonly warnings: readonly string[];
+}
+/**
+ * Indexes a working corpus into this project's own store.
+ *
+ * The payload is built in a temporary directory and thrown away. A published package is an
+ * artifact somebody installs; this is a cache of the reader's own files, and leaving a copy of it
+ * in the project would be one more thing to gitignore, review and let go stale.
+ */
+export declare function indexLocal(options: IndexLocalOptions): Promise<IndexLocalResult>;
+export interface RecallHit extends SearchHit {
+    readonly name: string;
+}
+/** A source that no longer matches what was indexed from it. */
+export interface StaleSource {
+    readonly path: string;
+    readonly reason: "changed" | "missing";
+}
+export interface RecallResult {
+    readonly hits: readonly RecallHit[];
+    readonly tokens: number;
+    /** Corpora present in the local store, whether or not they matched. */
+    readonly corpora: readonly string[];
+    readonly stale: readonly StaleSource[];
+    /** Corpora read from a stream, whose freshness cannot be checked. */
+    readonly streamed: readonly string[];
+}
+export interface RecallOptions {
+    readonly cwd: string;
+    readonly store: Store;
+    readonly query: string;
+    readonly limit?: number;
+    readonly maxTokens?: number;
+}
+/**
+ * Answers from the working corpora in this project's store, and from nothing else.
+ *
+ * Kept separate from `queryDocs` rather than added to it as a flag. `ask` promises an answer from
+ * the versions this project installed, and the one line that keeps that promise is the `kinds`
+ * filter it passes; a flag that flipped it would put a corpus of somebody's notes one typo away
+ * from an answer about a dependency.
+ */
+export declare function recallLocal(options: RecallOptions): Promise<RecallResult>;
+export declare function renderRecall(result: RecallResult, query: string): string;
+//# sourceMappingURL=local.d.ts.map

package/dist/local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../src/local.ts"],"names":[],"mappings":"AAKA,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,KAAK,EACX,MAAM,SAAS,CAAC;AAajB,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,gDAAgD;IAChD,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjD;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,WAAW,CAAC;IACzC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA4DtF;AAED,MAAM,WAAW,SAAU,SAAQ,SAAS;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,gEAAgE;AAChE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,CAAC;CACxC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS,SAAS,EAAE,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CA4B/E;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAqBxE"}

package/dist/local.js

@@ -0,0 +1,242 @@
+import { createHash } from "node:crypto";
+import { mkdir, mkdtemp, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { buildPackage, LOCAL_VERSION, localPackageName, MARKDOWN } from "./build.js";
+import { LOCAL_STORE_DIR, } from "./db.js";
+import { DocspackError } from "./errors.js";
+import { DEFAULT_LIMIT, DEFAULT_MAX_TOKENS } from "./search.js";
+import { chunkId, estimateTokens, LLMS_DIR, MANIFEST_FILE, packageId, parseManifest, resolveChunkFile, } from "./spec.js";
+/**
+ * Indexes a working corpus into this project's own store.
+ *
+ * The payload is built in a temporary directory and thrown away. A published package is an
+ * artifact somebody installs; this is a cache of the reader's own files, and leaving a copy of it
+ * in the project would be one more thing to gitignore, review and let go stale.
+ */
+export async function indexLocal(options) {
+    if (options.from === undefined && options.json === undefined) {
+        throw new DocspackError("Nothing to index", {
+            hint: "Pass --from <dir> for Markdown, or --from-json <file|-> for records.",
+        });
+    }
+    const name = options.name ?? localPackageName(options);
+    const id = packageId(name, LOCAL_VERSION);
+    const streamed = options.json === "-";
+    const sources = streamed ? [] : await fingerprint(options);
+    if (options.force !== true &&
+        !streamed &&
+        options.store.hasPackage(id) &&
+        unchanged(options.store.sourcesOf(id), sources)) {
+        return {
+            id,
+            name,
+            chunks: options.store.countChunks(id),
+            tokens: 0,
+            status: "unchanged",
+            sources: sources.length,
+            streamed,
+            warnings: [],
+        };
+    }
+    const work = await mkdtemp(join(tmpdir(), "docspack-local-"));
+    try {
+        options.onProgress?.(`indexing ${name}`);
+        const built = await buildPackage({
+            out: work,
+            local: true,
+            name,
+            version: LOCAL_VERSION,
+            ...(options.from === undefined ? {} : { from: options.from }),
+            ...(options.json === undefined ? {} : { json: options.json }),
+        });
+        const chunks = await readChunks(work, id);
+        options.store.indexPackage({ id, name, version: LOCAL_VERSION, kind: "local" }, chunks);
+        options.store.recordSources(id, sources);
+        await protectStore(options.cwd);
+        return {
+            id,
+            name,
+            chunks: chunks.length,
+            tokens: built.tokens,
+            status: "indexed",
+            sources: sources.length,
+            streamed,
+            warnings: built.warnings,
+        };
+    }
+    finally {
+        await rm(work, { recursive: true, force: true });
+    }
+}
+/**
+ * Answers from the working corpora in this project's store, and from nothing else.
+ *
+ * Kept separate from `queryDocs` rather than added to it as a flag. `ask` promises an answer from
+ * the versions this project installed, and the one line that keeps that promise is the `kinds`
+ * filter it passes; a flag that flipped it would put a corpus of somebody's notes one typo away
+ * from an answer about a dependency.
+ */
+export async function recallLocal(options) {
+    const corpora = options.store.listPackages().filter((pkg) => pkg.kind === "local");
+    const hits = options.store
+        .search(options.query, {
+        kinds: ["local"],
+        limit: options.limit ?? DEFAULT_LIMIT,
+        maxTokens: options.maxTokens ?? DEFAULT_MAX_TOKENS,
+    })
+        .map((hit) => ({ ...hit, name: splitLocalName(hit.packageId) }));
+    const stale = [];
+    const streamed = [];
+    for (const corpus of corpora) {
+        const recorded = options.store.sourcesOf(corpus.id);
+        if (recorded.length === 0) {
+            streamed.push(corpus.name);
+            continue;
+        }
+        stale.push(...(await drifted(recorded)));
+    }
+    return {
+        hits,
+        tokens: hits.reduce((total, hit) => total + hit.tokens, 0),
+        corpora: corpora.map((corpus) => corpus.name),
+        stale,
+        streamed,
+    };
+}
+export function renderRecall(result, query) {
+    if (result.hits.length === 0) {
+        if (result.corpora.length === 0) {
+            return `Nothing has been indexed into this project's corpus. Run \`docspack index --from <dir>\` first.`;
+        }
+        return `Nothing in ${result.corpora.join(", ")} matched "${query}".`;
+    }
+    const sections = result.hits.map((hit) => [`## ${hit.chunkId}`, `Source: ${hit.name} — ${hit.filePath}`, "", hit.content].join("\n"));
+    // Before the passages, not after: a reader who acts on the first thing they read has to be told
+    // the text may be superseded before they read it, not once they already have.
+    if (result.stale.length > 0)
+        sections.unshift(staleNotice(result.stale));
+    if (result.streamed.length > 0) {
+        sections.push(`NOTE: ${result.streamed.join(", ")} was indexed from a stream, so whether it still matches its source cannot be checked here.`);
+    }
+    return sections.join("\n\n---\n\n");
+}
+function staleNotice(stale) {
+    const shown = stale.slice(0, 5).map((source) => source.path);
+    const rest = stale.length - shown.length;
+    const missing = stale.filter((source) => source.reason === "missing").length;
+    const tail = rest > 0 ? `, and ${String(rest)} more` : "";
+    const gone = missing > 0 ? ` ${String(missing)} of them no longer exist.` : "";
+    return `NOTE: the corpus is out of date. ${String(stale.length)} indexed ${stale.length === 1 ? "source has" : "sources have"} changed since it was built: ${shown.join(", ")}${tail}.${gone} The passages below may be superseded — run \`docspack index\` again before relying on them.`;
+}
+/** Which recorded sources no longer match what is on disk. */
+async function drifted(recorded) {
+    const stale = [];
+    for (const source of recorded) {
+        let info;
+        try {
+            info = await stat(source.path);
+        }
+        catch {
+            stale.push({ path: source.path, reason: "missing" });
+            continue;
+        }
+        // Size and mtime first, and the hash only when one of them moved: a checkout or a formatter
+        // touches every file's mtime without changing a byte, and hashing a whole corpus on every
+        // query to find that out would make the cheap path the expensive one.
+        if (info.size === source.size && info.mtimeMs === Date.parse(source.mtime))
+            continue;
+        if ((await hashOf(source.path)) === source.hash)
+            continue;
+        stale.push({ path: source.path, reason: "changed" });
+    }
+    return stale;
+}
+/** What a corpus was built from, as it is right now. */
+async function fingerprint(options) {
+    const paths = [];
+    if (options.from !== undefined) {
+        const root = resolve(options.from);
+        const found = await readdir(root, { recursive: true, withFileTypes: true }).catch(() => {
+            throw new DocspackError(`No such directory: ${options.from ?? ""}`, {
+                hint: "Pass --from <dir> to point at the Markdown you want indexed.",
+            });
+        });
+        paths.push(...found
+            .filter((entry) => entry.isFile() && MARKDOWN.test(entry.name))
+            .map((entry) => join(entry.parentPath, entry.name))
+            .sort());
+    }
+    if (options.json !== undefined && options.json !== "-")
+        paths.push(resolve(options.json));
+    const sources = [];
+    for (const path of paths) {
+        const info = await stat(path);
+        sources.push({
+            path,
+            size: info.size,
+            mtime: new Date(info.mtimeMs).toISOString(),
+            hash: await hashOf(path),
+        });
+    }
+    return sources;
+}
+function unchanged(recorded, current) {
+    if (recorded.length !== current.length)
+        return false;
+    const before = new Map(recorded.map((source) => [source.path, source.hash]));
+    return current.every((source) => before.get(source.path) === source.hash);
+}
+async function hashOf(path) {
+    return createHash("sha256")
+        .update(await readFile(path))
+        .digest("hex");
+}
+async function readChunks(dir, id) {
+    const llmsDir = join(dir, LLMS_DIR);
+    const manifest = parseManifest(JSON.parse(await readFile(join(llmsDir, MANIFEST_FILE), "utf8")), `${LLMS_DIR}/${MANIFEST_FILE}`);
+    const chunks = [];
+    for (const chunk of manifest.chunks) {
+        const content = (await readFile(resolveChunkFile(llmsDir, chunk.file), "utf8")).trim();
+        if (content.length === 0)
+            continue;
+        chunks.push({
+            chunkId: chunkId(id, chunk.id),
+            filePath: chunk.file,
+            tokens: chunk.tokens ?? estimateTokens(content),
+            content,
+            tags: [...chunk.tags, ...chunk.entities],
+        });
+    }
+    if (chunks.length === 0) {
+        throw new DocspackError("Nothing readable to index", {
+            hint: "The sources produced no chunks. Check they contain text.",
+        });
+    }
+    return chunks;
+}
+/**
+ * Keeps the store out of version control.
+ *
+ * The index is a plaintext copy of whatever was indexed, so committing it would put the corpus in
+ * the repository a second time — and for notes, an export or a query result, somewhere nobody
+ * thought to look for it. Written next to the store rather than in the project's own
+ * `.gitignore`, which is the project's file and not this tool's to edit.
+ */
+async function protectStore(cwd) {
+    const dir = join(cwd, LOCAL_STORE_DIR);
+    await mkdir(dir, { recursive: true });
+    const ignore = join(dir, ".gitignore");
+    try {
+        await readFile(ignore, "utf8");
+    }
+    catch {
+        await writeFile(ignore, "# The local index is a copy of your own sources. Do not commit it.\n*\n");
+    }
+}
+/** `@local/notes@0.0.0/chunk` carries the corpus name; the version is never interesting. */
+function splitLocalName(packageId) {
+    const at = packageId.lastIndexOf("@");
+    return at <= 0 ? packageId : packageId.slice(0, at);
+}
+//# sourceMappingURL=local.js.map

package/dist/local.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.js","sourceRoot":"","sources":["../src/local.ts"],"names":[],"mappings":"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"}

package/dist/mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGpE,OAAO,EAAoB,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAMvD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AA4BD,wBAAgB,eAAe,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS,CA6I9D;AAED,qGAAqG;AACrG,wBAAsB,cAAc,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAMvE"}
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGpE,OAAO,EAAoB,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAMvD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AA+BD,wBAAgB,eAAe,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS,CA6I9D;AAED,qGAAqG;AACrG,wBAAsB,cAAc,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAMvE"}

package/dist/mcp.js

@@ -11,6 +11,9 @@ const DESCRIPTION = [
     "Returns Markdown excerpts from local, version-matched documentation packages.",
     "Prefer this over recalling API details from memory: the local copy matches the",
     "exact dependency versions in this project.",
+    "When the question names something an installed library exports that no",
+    "documentation mentions, the answer leads with that name's declaration from the",
+    "installed build and says the documentation does not cover it.",
 ].join(" ");
 /**
  * A tool description is the only thing shaping how a model uses it, so this one carries the

package/dist/mcp.js.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"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"}

package/dist/preview.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../src/preview.ts"],"names":[],"mappings":"AAIA,OAAO,EAAqC,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAa/E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,QAAQ,EAAE,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAkEpF"}
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../src/preview.ts"],"names":[],"mappings":"AAKA,OAAO,EAAqC,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAa/E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,QAAQ,EAAE,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CA0FpF"}

package/dist/preview.js

@@ -1,6 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { Store } from "./db.js";
+import { endpointIndex, matchEndpoints } from "./endpoints.js";
 import { DocspackError } from "./errors.js";
 import { DEFAULT_LIMIT, DEFAULT_MAX_TOKENS } from "./search.js";
 import { chunkId, estimateTokens, formatDocumentedLibrary, isCommunityPackage, LLMS_DIR, MANIFEST_FILE, packageId, parseManifest, resolveChunkFile, } from "./spec.js";
@@ -49,18 +50,36 @@ export async function previewPackage(options) {
     const store = Store.open(":memory:");
     try {
         store.indexPackage({ id, name: manifest.name, version: manifest.version }, chunks);
-        const hits = store
-            .search(options.query, {
-            limit: options.limit ?? DEFAULT_LIMIT,
-            maxTokens: options.maxTokens ?? DEFAULT_MAX_TOKENS,
-        })
-            .map((hit) => ({
+        const describe = (hit) => ({
             ...hit,
             name: manifest.name,
             version: manifest.version,
+            kind: "docs",
             trusted: !isCommunityPackage(manifest.name),
             ...(documents.length === 0 ? {} : { documents }),
-        }));
+        });
+        // The same endpoint pinning `queryDocs` does, because `preview` exists to show an author what an
+        // agent would receive. A preview that ranked where the real query path pins would send them
+        // chasing a retrieval problem they do not have.
+        const limit = options.limit ?? DEFAULT_LIMIT;
+        const maxTokens = options.maxTokens ?? DEFAULT_MAX_TOKENS;
+        const pinned = matchEndpoints(options.query, endpointIndex(manifest.chunks.map((chunk) => ({
+            chunkId: chunkId(id, chunk.id),
+            entities: chunk.entities,
+        }))))
+            .map((match) => store.chunk(match.chunkId))
+            .filter((chunk) => chunk !== undefined)
+            .map(describe);
+        const spent = pinned.reduce((total, hit) => total + hit.tokens, 0);
+        const pinnedIds = new Set(pinned.map((hit) => hit.chunkId));
+        const ranked = store
+            .search(options.query, {
+            limit: Math.max(1, limit - pinned.length),
+            maxTokens: Math.max(1, maxTokens - spent),
+        })
+            .filter((hit) => !pinnedIds.has(hit.chunkId))
+            .map(describe);
+        const hits = [...pinned, ...ranked];
         return {
             hits,
             tokens: hits.reduce((total, hit) => total + hit.tokens, 0),

package/dist/preview.js.map

@@ -1 +1 @@
-{"version":3,"file":"preview.js","sourceRoot":"","sources":["../src/preview.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"preview.js","sourceRoot":"","sources":["../src/preview.ts"],"names":[],"mappings":"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"}

package/dist/search.d.ts

@@ -1,4 +1,4 @@
-import type { SearchHit, Store } from "./db.js";
+import type { PackageKind, SearchHit, Store } from "./db.js";
 /** Ceiling on how much context one query may return, per the blueprint's context-exhaustion rule. */
 export declare const DEFAULT_MAX_TOKENS = 3000;
 export declare const DEFAULT_LIMIT = 3;
@@ -15,11 +15,18 @@ export interface QueryOptions {
      * sees documentation for a version this project does not use.
      */
     readonly scoped?: boolean;
+    /**
+     * Answer a question that names an exported symbol from the installed library's own
+     * declarations when the documentation does not mention it. On by default.
+     */
+    readonly artifacts?: boolean;
 }
 export interface QueryHit extends SearchHit {
     readonly name: string;
     readonly version: string;
     readonly trusted: boolean;
+    /** Whether this text was published as documentation or derived from the installed build. */
+    readonly kind: PackageKind;
     /**
      * Libraries this chunk documents, from its manifest. A docs package version cannot always
      * imply this — a monorepo documents many libraries at many versions from one surface — so the
@@ -39,6 +46,20 @@ export interface QueryResult {
      * covers this question".
      */
     readonly unindexed: readonly string[];
+    /**
+     * Names the question used that an installed library exports and no documentation mentions.
+     * This is the difference between "the documentation does not cover this" and "nothing
+     * matched", which a ranker alone cannot tell apart — it always returns its best three.
+     */
+    readonly undocumented: readonly string[];
+    /**
+     * Endpoints the question named that a documented operation answers, pinned rather than ranked.
+     *
+     * Reported so an answer can say *why* a chunk is first. A reader who asked about
+     * `GET /v1/charges/ch_3Ox7` and is shown `GET /v1/charges/{charge}` has been given the right
+     * chunk, and has to be told that the match was against a template.
+     */
+    readonly endpoints: readonly string[];
 }
 export declare function queryDocs(options: QueryOptions): Promise<QueryResult>;
 /**

package/dist/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAIhD,qGAAqG;AACrG,eAAO,MAAM,kBAAkB,OAAO,CAAC;AACvC,eAAO,MAAM,aAAa,IAAI,CAAC;AAE/B,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yFAAyF;IACzF,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,QAAS,SAAQ,SAAS;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,SAAS,QAAQ,EAAE,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iEAAiE;IACjE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,wBAAsB,SAAS,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAoD3E;AAMD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CA6BvE;AAED,oEAAoE;AACpE,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAI5E"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAK7D,qGAAqG;AACrG,eAAO,MAAM,kBAAkB,OAAO,CAAC;AACvC,eAAO,MAAM,aAAa,IAAI,CAAC;AAW/B,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yFAAyF;IACzF,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,QAAS,SAAQ,SAAS;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,4FAA4F;IAC5F,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,SAAS,QAAQ,EAAE,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iEAAiE;IACjE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,wBAAsB,SAAS,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAqE3E;AA4HD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CA6BvE;AAgBD,oEAAoE;AACpE,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAI5E"}