docspack 0.3.0 → 1.0.0

package/dist/agent.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Wiring docspack into the agent tooling a project already uses.
+ *
+ * The documented setup is "paste two lines into AGENTS.md", which is manual, easy to forget, and
+ * drifts: a line pasted once says whatever docspack did at the time. This writes the same thing
+ * from the code that defines it, into a marked block that can be rewritten in place.
+ */
+export type SurfaceKind = "instructions" | "skill" | "hook" | "mcp";
+export interface AgentFile {
+    /** Path relative to the project root. */
+    readonly path: string;
+    readonly kind: SurfaceKind;
+    readonly contents: string;
+    readonly status: "create" | "update" | "unchanged";
+    /** Why this file is in the plan, for the line the CLI prints. */
+    readonly reason: string;
+}
+export interface AgentPlan {
+    readonly files: readonly AgentFile[];
+}
+export interface AgentOptions {
+    readonly cwd: string;
+    /**
+     * The three surfaces beyond the instruction block. Left unset, each is inferred from what is
+     * already on disk, so `docspack agent check` needs no flags to say whether what a project
+     * chose is still current — which is the only form of the check CI can run.
+     */
+    readonly feedback?: boolean;
+    /** Write a SessionStart hook that keeps the index in step with the lockfile. */
+    readonly hooks?: boolean;
+    /** Write the MCP server into `.mcp.json`. */
+    readonly mcp?: boolean;
+}
+/**
+ * What to write, and where. Nothing is written for a tool the project does not use: the presence
+ * of `.claude/` is what says a Claude Code user works here, and a project with neither an
+ * AGENTS.md nor a CLAUDE.md gets AGENTS.md, which is the cross-tool convention.
+ */
+export declare function planAgentSetup(options: AgentOptions): Promise<AgentPlan>;
+/** Writes a plan. A file that already carries the current text is left alone. */
+export declare function applyAgentSetup(options: AgentOptions, plan: AgentPlan): Promise<readonly AgentFile[]>;
+/**
+ * Replaces the marked block, or appends one. Everything outside the markers is left exactly as
+ * it was: these files are written by people, and a tool that rewrites them wholesale is a tool
+ * nobody runs twice.
+ */
+export declare function withBlock(document: string, block: string): string;
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAMA;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,cAAc,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;AAEpE,MAAM,WAAW,SAAS;IACxB,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,WAAW,CAAC;IACnD,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,gFAAgF;IAChF,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,6CAA6C;IAC7C,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;CACxB;AAQD;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,CAAC,CAqD9E;AAED,iFAAiF;AACjF,wBAAsB,eAAe,CACnC,OAAO,EAAE,YAAY,EACrB,IAAI,EAAE,SAAS,GACd,OAAO,CAAC,SAAS,SAAS,EAAE,CAAC,CAa/B;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAUjE"}

package/dist/agent.js

@@ -0,0 +1,243 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { DocspackError } from "./errors.js";
+import { AGENTS_SNIPPET, FEEDBACK_SNIPPET } from "./snippet.js";
+const START = "<!-- docspack:start -->";
+const END = "<!-- docspack:end -->";
+/** Files an agent reads as standing instructions, in the order they are checked. */
+const INSTRUCTION_FILES = ["AGENTS.md", "CLAUDE.md"];
+/**
+ * What to write, and where. Nothing is written for a tool the project does not use: the presence
+ * of `.claude/` is what says a Claude Code user works here, and a project with neither an
+ * AGENTS.md nor a CLAUDE.md gets AGENTS.md, which is the cross-tool convention.
+ */
+export async function planAgentSetup(options) {
+    const root = resolve(options.cwd);
+    if (!existsSync(join(root, "package.json"))) {
+        throw new DocspackError(`No package.json found in ${root}`, {
+            hint: "Run docspack from a project directory, or pass --cwd <dir>.",
+        });
+    }
+    const existing = INSTRUCTION_FILES.filter((name) => existsSync(join(root, name)));
+    const feedback = options.feedback ?? (await wantsFeedback(root, existing));
+    const files = [];
+    const block = instructionBlock(feedback);
+    const targets = existing.length > 0 ? existing : ["AGENTS.md"];
+    for (const name of targets) {
+        const before = await read(join(root, name));
+        const after = withBlock(before ?? "", block);
+        files.push({
+            path: name,
+            kind: "instructions",
+            contents: after,
+            status: before === undefined ? "create" : after === before ? "unchanged" : "update",
+            reason: before === undefined
+                ? "the cross-tool convention for standing agent instructions"
+                : "already read by the agents working here",
+        });
+    }
+    if (existsSync(join(root, ".claude"))) {
+        const path = join(".claude", "skills", "docspack", "SKILL.md");
+        const before = await read(join(root, path));
+        const contents = skill(feedback);
+        files.push({
+            path,
+            kind: "skill",
+            contents,
+            status: before === undefined ? "create" : before === contents ? "unchanged" : "update",
+            // A skill's body is loaded when it is used; instructions are loaded every session. Both
+            // are written, because only one of them survives a session that never asks a question.
+            reason: "loaded on demand, so it costs nothing in a session that asks no questions",
+        });
+    }
+    const settings = await read(join(root, ".claude", "settings.json"));
+    const wantsHook = options.hooks ?? (settings ?? "").includes("docspack sync");
+    if (wantsHook)
+        files.push(await hook(root));
+    const mcpConfig = await read(join(root, ".mcp.json"));
+    const wantsMcp = options.mcp ?? /"docspack"\s*:/.test(mcpConfig ?? "");
+    if (wantsMcp)
+        files.push(await mcpEntry(root));
+    return { files };
+}
+/** Writes a plan. A file that already carries the current text is left alone. */
+export async function applyAgentSetup(options, plan) {
+    const root = resolve(options.cwd);
+    const written = [];
+    for (const file of plan.files) {
+        if (file.status === "unchanged")
+            continue;
+        const target = join(root, file.path);
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, file.contents, "utf8");
+        written.push(file);
+    }
+    return written;
+}
+/**
+ * Replaces the marked block, or appends one. Everything outside the markers is left exactly as
+ * it was: these files are written by people, and a tool that rewrites them wholesale is a tool
+ * nobody runs twice.
+ */
+export function withBlock(document, block) {
+    const start = document.indexOf(START);
+    const end = document.indexOf(END);
+    if (start !== -1 && end > start) {
+        return `${document.slice(0, start)}${block}${document.slice(end + END.length)}`;
+    }
+    const body = document.trimEnd();
+    return body.length === 0 ? `${block}\n` : `${body}\n\n${block}\n`;
+}
+/** Whether a project already asked for the feedback half, read from what it has on disk. */
+async function wantsFeedback(root, files) {
+    for (const name of files) {
+        if ((await read(join(root, name)))?.includes("docspack feedback add") === true)
+            return true;
+    }
+    const skillFile = await read(join(root, ".claude", "skills", "docspack", "SKILL.md"));
+    return skillFile?.includes("docspack feedback add") === true;
+}
+function instructionBlock(feedback) {
+    const lines = [
+        START,
+        "## Documentation for this project's dependencies",
+        "",
+        ...AGENTS_SNIPPET,
+        ...(feedback ? ["", ...FEEDBACK_SNIPPET] : []),
+        "",
+        "<!-- Written by `docspack agent install`. Re-run it to update this block. -->",
+        END,
+    ];
+    return lines.join("\n");
+}
+/**
+ * The Claude Code skill. Its description is what decides whether the skill is reached for, and
+ * the body is loaded only once it is — so the description names the situations rather than the
+ * tool, and the body carries what the two-line instruction cannot afford to.
+ */
+function skill(feedback) {
+    return [
+        "---",
+        "name: docspack",
+        "description: >-",
+        "  Answer questions about this project's installed dependencies from local, version-matched",
+        "  documentation instead of memory. Use before writing or reviewing code that calls a",
+        "  dependency, when an API's shape is uncertain, when an import or a signature may have",
+        "  changed between versions, or when a name is not in any documentation at all.",
+        "allowed-tools: Bash",
+        "---",
+        "",
+        "# Documentation for installed dependencies",
+        "",
+        'Run `docspack ask "<question>"` for anything about a dependency of this project. It answers',
+        "from the versions in `node_modules`, offline, in about 100ms, and bounded to 3,000 tokens.",
+        "",
+        "Prefer it over recalling an API from training data. The installed version is usually newer",
+        "than the training data and the answer states which release it came from.",
+        "",
+        "## What the answer can tell you",
+        "",
+        "- A passage from a documentation package, headed by its chunk id and the version it documents.",
+        "- A declaration read from the installed build, when the question names something the",
+        "  documentation never mentions. It carries the import to write and the signature as installed.",
+        "- A note saying the name is exported but documented nowhere. That is a real answer: it means",
+        "  no prose exists, not that the search failed.",
+        "",
+        "## Other commands",
+        "",
+        "- `docspack changed <library>` — what a library's exports gained and lost between two",
+        "  installed versions. Use it when an upgrade broke something, or before writing code against",
+        "  a version newer than what you remember.",
+        "- `docspack list` — which packages are indexed here.",
+        "- `docspack sync` — index them. Run it if `ask` reports something installed but not indexed.",
+        ...(feedback
+            ? [
+                "",
+                "## Recording a problem",
+                "",
+                "If the documentation contradicts the installed package, record it:",
+                "",
+                "```bash",
+                'docspack feedback add --chunk <id> --kind <drift|incorrect|missing> --evidence "<claim>"',
+                "```",
+                "",
+                "Only claims that can be shown false. `incorrect` and `missing` also need `--expected`,",
+                "`--actual` and `--repro`, so record those only after running something. It appends to a",
+                "local file for a human to review and sends nothing.",
+            ]
+            : []),
+        "",
+    ].join("\n");
+}
+/**
+ * A SessionStart hook, so the index follows the lockfile without anyone remembering to sync.
+ *
+ * `--quiet` keeps it silent: a hook that prints on every session start spends context on a
+ * message saying nothing changed.
+ */
+async function hook(root) {
+    const path = join(".claude", "settings.json");
+    const before = await read(join(root, path));
+    const settings = parseJson(before, path);
+    // Silent and never failing: a session must not break, or print, because an index is stale.
+    const command = "npx --no-install docspack sync --quiet >/dev/null 2>&1 || true";
+    const hooks = (settings.hooks ?? {});
+    const sessionStart = Array.isArray(hooks.SessionStart) ? [...hooks.SessionStart] : [];
+    const already = JSON.stringify(sessionStart).includes("docspack sync");
+    if (!already)
+        sessionStart.push({ hooks: [{ type: "command", command }] });
+    const contents = `${JSON.stringify({ ...settings, hooks: { ...hooks, SessionStart: sessionStart } }, null, 2)}\n`;
+    return {
+        path,
+        kind: "hook",
+        contents,
+        status: before === undefined ? "create" : before === contents ? "unchanged" : "update",
+        reason: "keeps the index in step with the lockfile without anyone remembering to sync",
+    };
+}
+async function mcpEntry(root) {
+    const path = ".mcp.json";
+    const before = await read(join(root, path));
+    const config = parseJson(before, path);
+    const servers = (config.mcpServers ?? {});
+    const contents = `${JSON.stringify({
+        ...config,
+        mcpServers: {
+            ...servers,
+            docspack: { command: "npx", args: ["-y", "docspack", "mcp"] },
+        },
+    }, null, 2)}\n`;
+    return {
+        path,
+        kind: "mcp",
+        contents,
+        status: before === undefined ? "create" : before === contents ? "unchanged" : "update",
+        reason: "a declared tool, for clients that would rather have one than a shell command",
+    };
+}
+function parseJson(raw, path) {
+    if (raw === undefined || raw.trim().length === 0)
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null)
+            throw new Error("not an object");
+        return parsed;
+    }
+    catch (error) {
+        throw new DocspackError(`${path} is not valid JSON`, {
+            hint: "Fix it, or move it aside and run this again.",
+            cause: error,
+        });
+    }
+}
+async function read(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

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

package/dist/artifact.d.ts

@@ -0,0 +1,32 @@
+import type { IndexedChunk } from "./db.js";
+/**
+ * A package derived from an installed library rather than published by its author.
+ *
+ * Half of a well-documented library's exported names are mentioned nowhere in its own
+ * documentation (see `docs/design/beyond-retrieval.md`), and almost all of them are declared in
+ * the type declarations sitting in `node_modules`. Those declarations are the answer a
+ * documentation site cannot serve, because the site is not the artifact.
+ */
+export interface ArtifactPackage {
+    readonly id: string;
+    readonly name: string;
+    readonly version: string;
+    readonly chunks: readonly IndexedChunk[];
+    /**
+     * Every exported name, mapped to the chunk carrying its declaration — or to an empty string
+     * when the package exports the name without declaring it anywhere this can read.
+     *
+     * Recording those too is what keeps `changed` honest: a name re-exported from a file with no
+     * declaration in it would otherwise look like a name the release removed.
+     */
+    readonly symbols: ReadonlyMap<string, string>;
+}
+/**
+ * Derives chunks from an installed library: one per exported name, carrying the import a caller
+ * writes and the declaration as the installed build states it.
+ *
+ * Returns nothing when the package ships no type declarations. That is the common case across a
+ * dependency tree and is not a problem worth reporting.
+ */
+export declare function readArtifact(dir: string): Promise<ArtifactPackage | undefined>;
+//# sourceMappingURL=artifact.d.ts.map

package/dist/artifact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact.d.ts","sourceRoot":"","sources":["../src/artifact.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAI5C;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;IACzC;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/C;AAQD;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAgDpF"}

package/dist/artifact.js

@@ -0,0 +1,78 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { chunkId, estimateTokens, packageId } from "./spec.js";
+import { declarationsIn, readPublicSurface } from "./surface.js";
+/** Beyond this a package is generated machinery, and indexing it would drown the prose. */
+const MAX_SYMBOLS = 2000;
+/** How much of a declaration is carried. Long enough for a signature, short enough to rank. */
+const DECLARATION_LIMIT = 400;
+/**
+ * Derives chunks from an installed library: one per exported name, carrying the import a caller
+ * writes and the declaration as the installed build states it.
+ *
+ * Returns nothing when the package ships no type declarations. That is the common case across a
+ * dependency tree and is not a problem worth reporting.
+ */
+export async function readArtifact(dir) {
+    const surface = await readPublicSurface(dir);
+    if (surface === undefined || surface.name.length === 0 || surface.version.length === 0) {
+        return undefined;
+    }
+    const id = packageId(surface.name, surface.version);
+    const declared = new Map();
+    const chunks = [];
+    const symbols = new Map();
+    for (const symbol of surface.symbols.values()) {
+        symbols.set(symbol.name, "");
+        if (chunks.length >= MAX_SYMBOLS)
+            continue;
+        let declarations = declared.get(symbol.file);
+        if (declarations === undefined) {
+            try {
+                declarations = declarationsIn(await readFile(join(dir, symbol.file), "utf8"), DECLARATION_LIMIT);
+            }
+            catch {
+                declarations = new Map();
+            }
+            declared.set(symbol.file, declarations);
+        }
+        const declaration = declarations.get(symbol.name);
+        // A name that only appears in an `export { … }` list has no declaration to show. The import
+        // line alone would say nothing the name did not already say, so it is left out.
+        if (declaration === undefined)
+            continue;
+        const content = render(symbol, declaration);
+        const chunk = chunkId(id, symbol.name);
+        chunks.push({
+            chunkId: chunk,
+            filePath: symbol.file,
+            tokens: estimateTokens(content),
+            content,
+            // The name is the tag, and tags are weighted 3× against prose in the ranking.
+            tags: [symbol.name, symbol.from],
+        });
+        symbols.set(symbol.name, chunk);
+    }
+    if (symbols.size === 0)
+        return undefined;
+    return { id, name: surface.name, version: surface.version, chunks, symbols };
+}
+/**
+ * What an agent receives. The import line is first because it is the part a caller gets wrong
+ * most often — a name that exists at a subpath nobody guessed is the same failure as a name that
+ * does not exist.
+ */
+function render(symbol, declaration) {
+    return [
+        `# ${symbol.name}`,
+        "",
+        `Declared by \`${symbol.from}\`. This is the installed build's own declaration, not prose.`,
+        "",
+        "```ts",
+        `import { ${symbol.name} } from "${symbol.from}";`,
+        "",
+        declaration.trim(),
+        "```",
+    ].join("\n");
+}
+//# sourceMappingURL=artifact.js.map

package/dist/artifact.js.map

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

package/dist/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAcvC,MAAM,WAAW,YAAY;IAC3B,gDAAgD;IAChD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,wDAAwD;IACxD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,iGAAiG;IACjG,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjD;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAkBD;;;GAGG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAmE5E;AAgmBD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAqBzD"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAgBvC,MAAM,WAAW,YAAY;IAC3B,gDAAgD;IAChD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,wDAAwD;IACxD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,iGAAiG;IACjG,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjD;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAoBD;;;GAGG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAsE5E;AAqrBD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAqBzD"}

package/dist/build.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
 import { join, relative, sep } from "node:path";
 import { findEntry } from "@docspack/registry";
@@ -7,7 +8,7 @@ import { DocspackError } from "./errors.js";
 import { htmlToMarkdown, isHtml } from "./html.js";
 import { HttpClient } from "./http.js";
 import { fetchableLinks, parseLlmsTxt } from "./llms-txt.js";
-import { CHUNKS_DIR, estimateTokens, LLMS_DIR, MANIFEST_FILE, parseDocumentedLibrary, serializeManifest, } from "./spec.js";
+import { CHUNKS_DIR, estimateTokens, LLMS_DIR, MANIFEST_FILE, parseDocumentedLibrary, parseManifest, serializeManifest, } from "./spec.js";
 import { STOPWORDS } from "./stopwords.js";
 const DEFAULT_MAX_CHUNK_TOKENS = 800;
 const MARKDOWN = /\.(md|mdx|markdown)$/i;
@@ -31,8 +32,11 @@ export async function buildPackage(input) {
     if (minTokens !== undefined && minTokens > maxTokens) {
         throw new DocspackError(`minChunkTokens (${minTokens}) is larger than maxChunkTokens (${maxTokens})`, { hint: "A chunk cannot be required to be bigger than it is allowed to be." });
     }
-    const { chunks, files } = chunkDocuments(documents, maxTokens, minTokens);
+    const { chunks, files, collisions } = chunkDocuments(documents, maxTokens, minTokens);
     const llmsDir = join(options.out, LLMS_DIR);
+    // Read before the payload is removed: a chunk id is what `feedback add --chunk` pins and what
+    // an answer is headed with, so a rebuild that renames one silently orphans both.
+    warnings.push(...idWarnings(collisions, await departedChunkIds(llmsDir, chunks)));
     await rm(llmsDir, { recursive: true, force: true });
     await mkdir(join(llmsDir, CHUNKS_DIR), { recursive: true });
     for (const file of files) {
@@ -155,6 +159,7 @@ async function collectFromDirectory(dir) {
             origin: relativePath,
             text: cleaned.text,
             ...(cleaned.tags.length === 0 ? {} : { tags: cleaned.tags }),
+            ...(cleaned.documents.length === 0 ? {} : { documents: cleaned.documents }),
         });
     }
     return documents;
@@ -174,6 +179,13 @@ async function collectFromSource(options, warnings) {
     const parsed = parseLlmsTxt(index.text);
     const documents = [];
     const links = fetchableLinks(parsed).slice(0, options.pages ?? 50);
+    // Two links can name the same document. `fetchableLinks` already drops a repeated URL and a
+    // repeated fragment, but a site whose index links anchors as a query — `/v4?id=codecs` — gets
+    // one entry per anchor, and each one fetches the whole page again. Left alone that packages
+    // the same text dozens of times: an index mostly made of duplicates, which is slower to search
+    // and ranks worse, because copies of one page crowd out the rest of the corpus.
+    const seen = new Set();
+    let duplicates = 0;
     for (const link of links) {
         options.onProgress?.(`fetching ${link.url}`);
         try {
@@ -183,6 +195,12 @@ async function collectFromSource(options, warnings) {
                 warnings.push(`skipped ${link.url}: document was empty`);
                 continue;
             }
+            const fingerprint = createHash("sha256").update(text).digest("hex");
+            if (seen.has(fingerprint)) {
+                duplicates += 1;
+                continue;
+            }
+            seen.add(fingerprint);
             documents.push({
                 title: link.title.length > 0 ? link.title : (firstHeading(text) ?? link.url),
                 origin: link.url,
@@ -194,6 +212,9 @@ async function collectFromSource(options, warnings) {
             warnings.push(`skipped ${link.url}: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
+    if (duplicates > 0) {
+        warnings.push(`skipped ${duplicates} of ${links.length} linked documents whose text repeated one already packaged`);
+    }
     if (fetchableLinks(parsed).length > links.length) {
         warnings.push(`packaged ${links.length} of ${fetchableLinks(parsed).length} linked documents (raise with --pages)`);
     }
@@ -301,6 +322,7 @@ function renderOperation(method, path, operation, file) {
 function chunkDocuments(documents, maxTokens, minTokens) {
     const chunks = [];
     const files = [];
+    const collisions = [];
     const taken = new Set();
     for (const document of documents) {
         const text = collapseTablePadding(document.text);
@@ -310,7 +332,11 @@ function chunkDocuments(documents, maxTokens, minTokens) {
         for (const section of sections) {
             const directives = readDirectives(section.body);
             const body = withoutDuplicateHeading(directives.body, section.heading);
-            const id = uniqueId(chunkSlug(document.title, section.heading), taken);
+            const derived = chunkSlug(document.title, section.heading);
+            const id = uniqueId(derived, taken);
+            if (id !== derived)
+                collisions.push(derived);
+            const libraries = directives.documents.length > 0 ? directives.documents : document.documents;
             const contents = `# ${section.heading}\n\n<!-- docspack: from ${document.origin} -->\n\n${body}\n`;
             const file = `${CHUNKS_DIR}/${id}.md`;
             files.push({ path: file, contents });
@@ -330,10 +356,46 @@ function chunkDocuments(documents, maxTokens, minTokens) {
                         ...extractEntities(body),
                     ]),
                 ],
+                ...(libraries === undefined || libraries.length === 0
+                    ? {}
+                    : { documents: libraries.map(parseDocumentedLibrary) }),
             });
         }
     }
-    return { chunks, files };
+    return { chunks, files, collisions };
+}
+/**
+ * The two ways a chunk id moves without anyone deciding it should. Both are reported as one
+ * line each, however many ids are involved: a large package collides in dozens of places, and a
+ * warning per id is a wall of text nobody reads.
+ */
+function idWarnings(collisions, gone) {
+    const warnings = [];
+    if (collisions.length > 0) {
+        warnings.push(`${plural(collisions.length, "derived chunk id")} collided and ${collisions.length === 1 ? "was" : "were"} given a numeric suffix: ${list(collisions)} — which section keeps the bare id depends on the order the sources were read in`);
+    }
+    if (gone.length > 0) {
+        warnings.push(`${plural(gone.length, "chunk id")} the previous build published ${gone.length === 1 ? "is" : "are"} gone: ${list(gone)} — recorded feedback and published links pinned to ${gone.length === 1 ? "it" : "them"} no longer resolve`);
+    }
+    return warnings;
+}
+const plural = (count, noun) => `${count} ${noun}${count === 1 ? "" : "s"}`;
+const list = (ids) => `${ids.slice(0, 5).join(", ")}${ids.length > 5 ? `, and ${ids.length - 5} more` : ""}`;
+/**
+ * Chunk ids the payload on disk carries that this build does not, or nothing when there is no
+ * previous payload to compare with. An unreadable manifest is not a finding: `build` is what
+ * replaces it.
+ */
+async function departedChunkIds(llmsDir, chunks) {
+    let previous;
+    try {
+        previous = parseManifest(JSON.parse(await readFile(join(llmsDir, MANIFEST_FILE), "utf8")), `${LLMS_DIR}/${MANIFEST_FILE}`);
+    }
+    catch {
+        return [];
+    }
+    const current = new Set(chunks.map((chunk) => chunk.id));
+    return previous.chunks.map((chunk) => chunk.id).filter((id) => !current.has(id));
 }
 /**
  * Splits Markdown at `##` headings, then `###`, then paragraphs, until every piece fits the token
@@ -487,23 +549,27 @@ function matchAll(text, pattern) {
     return found;
 }
 /** One authored override under a heading: `<!-- docspack: tags=grid,columns -->`. */
-const DIRECTIVE = /^[ \t]*<!--[ \t]*docspack:[ \t]*(tags|entities)[ \t]*=([^>]*?)-->[ \t]*$/gim;
+const DIRECTIVE = /^[ \t]*<!--[ \t]*docspack:[ \t]*(tags|entities|documents)[ \t]*=([^>]*?)-->[ \t]*$/gim;
 /**
  * Reads per-section directives and removes them from the body. Front matter belongs to a whole
  * document, so a page of eighty sections cannot aim any one of them; this is that lever.
  */
 function readDirectives(body) {
-    const tags = [];
-    const entities = [];
+    const collected = { tags: [], entities: [], documents: [] };
     const text = body.replace(DIRECTIVE, (_line, key, value) => {
         const values = value
             .split(",")
             .map((item) => item.trim())
             .filter((item) => item.length > 0);
-        (key.toLowerCase() === "tags" ? tags : entities).push(...values);
+        collected[key.toLowerCase()]?.push(...values);
         return "";
     });
-    return { body: text.replace(/\n{3,}/g, "\n\n").trim(), tags, entities };
+    return {
+        body: text.replace(/\n{3,}/g, "\n\n").trim(),
+        tags: collected.tags ?? [],
+        entities: collected.entities ?? [],
+        documents: collected.documents ?? [],
+    };
 }
 /**
  * Drops a source `# Title` that repeats the heading being written above it. A single-`H1`