docspack 0.3.0 → 1.0.0

package/src/help.ts

@@ -37,12 +37,21 @@ export const COMMANDS: readonly CommandHelp[] = [
     summary: "Index the docs packages this project depends on",
     group: "core",
     usage: "docspack sync [options]",
-    options: [["--force", "re-index packages already in the store"]],
+    options: [
+      ["--force", "re-index packages already in the store"],
+      ["--no-artifacts", "skip the declarations derived from installed libraries"],
+    ],
     detail: [
       "Reads node_modules and indexes every @vendor/docspack and @docspack-community/<name>",
       "package this project declares. Makes no network requests.",
+      "",
+      "It also reads each installed library's own type declarations and indexes one entry per",
+      "exported name. Half of a well-documented library's exports are mentioned in no",
+      "documentation anyone published, and those declarations are the only local answer for",
+      "them. They are looked up by name, never ranked against prose, so they cannot crowd out",
+      "the documentation that does exist.",
     ],
-    examples: ["docspack sync", "docspack sync --force"],
+    examples: ["docspack sync", "docspack sync --force", "docspack sync --no-artifacts"],
   },
   {
     name: "ask",
@@ -54,6 +63,10 @@ export const COMMANDS: readonly CommandHelp[] = [
       "Answers from the installed versions, in the Markdown an agent should read. Exits 0 when",
       "chunks were returned, 3 when a docs package is installed but not indexed, and 4 when",
       "everything installed is indexed and nothing matched.",
+      "",
+      "When the question names something an installed library exports and no documentation",
+      "mentions, the answer leads with that name's declaration from the installed build and says",
+      "the documentation does not cover it. Ranking alone cannot tell that apart from a match.",
     ],
     examples: [
       'docspack ask "how do I verify a webhook signature"',
@@ -73,9 +86,57 @@ export const COMMANDS: readonly CommandHelp[] = [
     name: "list",
     summary: "Show this project's docs packages and their index state",
     group: "core",
-    usage: "docspack list",
+    usage: "docspack list [options]",
+    options: [["--coverage", "how much of each documented library's exports the prose mentions"]],
+    detail: [
+      "Coverage is mechanical: the exported names a library declares, against the names its",
+      "documentation mentions anywhere. It is reported, never gated on — a page listing every",
+      "export and explaining none would score full marks.",
+    ],
+    examples: ["docspack list", "docspack list --coverage", "docspack list --json"],
+  },
+  {
+    name: "agent",
+    summary: "Wire docspack into the agent tooling this project already uses",
+    group: "core",
+    usage: "docspack agent <install|check> [options]",
+    options: [
+      ["--feedback", "also include recording documentation problems"],
+      ["--hooks", "add a SessionStart hook that keeps the index in step"],
+      ["--mcp", "add the MCP server to .mcp.json"],
+      ["--dry-run", "print what would be written and write nothing"],
+    ],
+    detail: [
+      "`install` writes a marked block into AGENTS.md or CLAUDE.md — whichever the project",
+      "already has — and a skill into .claude/skills/docspack/ when the project uses Claude",
+      "Code. Everything outside the markers is left alone, and re-running rewrites the block",
+      "rather than appending a second copy.",
+      "",
+      "`check` writes nothing and exits non-zero when the wiring is missing or out of date, so",
+      "CI notices a pasted instruction that has drifted from what the tool now does.",
+    ],
+    examples: [
+      "docspack agent install",
+      "docspack agent install --feedback --hooks",
+      "docspack agent check",
+    ],
+  },
+  {
+    name: "changed",
+    summary: "What a library's exports gained and lost between two versions",
+    group: "core",
+    usage: "docspack changed <library>[@version]",
     options: [],
-    examples: ["docspack list", "docspack list --json"],
+    detail: [
+      "Compares two versions already in the global store, which is shared by every project on",
+      "this machine, so nothing is fetched. Without a version it compares what is installed here",
+      "against the most recently indexed other version.",
+      "",
+      "Upgrades are overwhelmingly additive: the useful answer is what exists now that an older",
+      "release did not have, and which of those names no documentation here mentions — the ones",
+      "a model can know from neither its training data nor the vendor's pages.",
+    ],
+    examples: ["docspack changed hono", "docspack changed hono@4.0.0"],
   },
   {
     name: "verify",

package/src/index.ts

@@ -1,4 +1,15 @@
+export {
+  type AgentFile,
+  type AgentOptions,
+  type AgentPlan,
+  applyAgentSetup,
+  planAgentSetup,
+  type SurfaceKind,
+  withBlock,
+} from "./agent.js";
+export { type ArtifactPackage, readArtifact } from "./artifact.js";
 export { type BuildOptions, type BuildResult, buildPackage } from "./build.js";
+export { type ChangedOptions, changedSurface, type SurfaceChange } from "./changed.js";
 export {
   type BuildConfig,
   CONFIG_KEY,
@@ -7,19 +18,30 @@ export {
   parseFeedbackChannel,
   readBuildConfig,
 } from "./config.js";
+export {
+  type CoverageOptions,
+  type CoverageReport,
+  identifiers,
+  type LibraryCoverage,
+  measureCoverage,
+} from "./coverage.js";
 export {
   defaultStorePath,
   type IndexedChunk,
   type IndexedPackage,
+  type PackageKind,
   type SearchHit,
   type SearchOptions,
   Store,
+  type SymbolHit,
   silenceSqliteWarning,
   toFtsQuery,
 } from "./db.js";
 export {
+  type DiscoveredLibrary,
   type DiscoveredPackage,
   type Discovery,
+  discoverLibraries,
   discoverPackages,
   projectPackageIds,
   resolvePackageDir,
@@ -136,6 +158,13 @@ export {
   type SubmitOptions,
   type SubmitReport,
 } from "./submit.js";
+export {
+  declarationOf,
+  type ExportedSymbol,
+  hasJsdoc,
+  type PublicSurface,
+  readPublicSurface,
+} from "./surface.js";
 export {
   type SyncedPackage,
   type SyncOptions,
@@ -145,6 +174,7 @@ export {
 } from "./sync.js";
 export {
   type DriftFinding,
+  documentedLibraries,
   type VerifiedPackage,
   type VerifyOptions,
   type VerifyReport,

package/src/mcp.ts

@@ -22,6 +22,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(" ");
 
 /**

package/src/preview.ts

@@ -85,6 +85,7 @@ export async function previewPackage(options: PreviewOptions): Promise<PreviewRe
           ...hit,
           name: manifest.name,
           version: manifest.version,
+          kind: "docs",
           trusted: !isCommunityPackage(manifest.name),
           ...(documents.length === 0 ? {} : { documents }),
         }),

package/src/search.ts

@@ -1,11 +1,20 @@
-import type { SearchHit, Store } from "./db.js";
-import { discoverPackages } from "./discovery.js";
-import { formatDocumentedLibrary, isCommunityPackage } from "./spec.js";
+import type { PackageKind, SearchHit, Store } from "./db.js";
+import { discoverLibraries, discoverPackages } from "./discovery.js";
+import { chunkId, formatDocumentedLibrary, isCommunityPackage } from "./spec.js";
 
 /** Ceiling on how much context one query may return, per the blueprint's context-exhaustion rule. */
 export const DEFAULT_MAX_TOKENS = 3000;
 export const DEFAULT_LIMIT = 3;
 
+/**
+ * How many declarations one answer may carry. A question names one or two things; more than
+ * that and the names are incidental, and pinning them would spend the budget on noise.
+ */
+const MAX_DECLARATIONS = 2;
+
+/** Below this a token is too short to be a name worth looking up: `c`, `id`. */
+const MIN_SYMBOL = 3;
+
 export interface QueryOptions {
   readonly cwd: string;
   readonly store: Store;
@@ -19,16 +28,24 @@ 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 the package documents, from its manifest. A docs package version cannot always
+   * 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
-   * answer states it rather than leaving the reader to infer it from the package name.
+   * answer states it rather than leaving the reader to infer it from the package name. A chunk
+   * that names its own libraries answers for those; otherwise the package's list stands.
    */
   readonly documents?: readonly string[];
 }
@@ -44,6 +61,12 @@ 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[];
 }
 
 export async function queryDocs(options: QueryOptions): Promise<QueryResult> {
@@ -56,40 +79,137 @@ export async function queryDocs(options: QueryOptions): Promise<QueryResult> {
 
   // Read from the installed manifests rather than the index: the store is a cache of chunk text,
   // and adding a column to it would make every existing store need a rebuild to answer this.
+  // Keyed by package id and by chunk id in the same map, because a chunk id already carries its
+  // package: `@acme/docspack@1.4.0/api-auth` cannot collide with `@acme/docspack@1.4.0`.
   const documented = new Map<string, readonly string[]>();
   for (const pkg of installed ?? []) {
     const documents = pkg.manifest.documents;
     if (documents !== undefined && documents.length > 0) {
       documented.set(pkg.id, documents.map(formatDocumentedLibrary));
     }
+    for (const chunk of pkg.manifest.chunks) {
+      if (chunk.documents === undefined || chunk.documents.length === 0) continue;
+      documented.set(chunkId(pkg.id, chunk.id), chunk.documents.map(formatDocumentedLibrary));
+    }
   }
 
-  const hits = options.store
+  const maxTokens = options.maxTokens ?? DEFAULT_MAX_TOKENS;
+  const prose = options.store
     .search(options.query, {
       ...(packageIds === undefined ? {} : { packageIds }),
       ...(options.packageFilter === undefined
         ? {}
         : { packageFilter: `%${options.packageFilter}%` }),
       limit: options.limit ?? DEFAULT_LIMIT,
-      maxTokens: options.maxTokens ?? DEFAULT_MAX_TOKENS,
+      maxTokens,
+      // Declarations are addressed by name, never ranked against prose: a library exports far
+      // more names than its documentation has pages, and ranking them together would answer
+      // every question with type machinery.
+      kinds: ["docs"],
     })
-    .map((hit): QueryHit => {
-      const { name, version } = splitPackageId(hit.packageId);
-      const documents = documented.get(hit.packageId);
-      return {
-        ...hit,
-        name,
-        version,
-        trusted: !isCommunityPackage(name),
-        ...(documents === undefined ? {} : { documents }),
-      };
-    });
+    .map((hit) => toQueryHit(hit, "docs", documented));
+
+  const { declarations, undocumented } =
+    options.artifacts === false
+      ? { declarations: [] as QueryHit[], undocumented: [] as string[] }
+      : await findDeclarations(options, prose, maxTokens);
+
+  // Declarations first: for an agent about to write a call, the signature at the installed
+  // version is the load-bearing line, and the prose explains it afterwards.
+  const hits = [...declarations, ...prose];
 
   return {
     hits,
     tokens: hits.reduce((total, hit) => total + hit.tokens, 0),
     untrusted: hits.some((hit) => !hit.trusted),
     unindexed,
+    undocumented,
+  };
+}
+
+/**
+ * Looks up the names a question used against the symbols the installed libraries export.
+ *
+ * Matching is case-sensitive on purpose. Someone asking about an API writes it as it is spelled,
+ * because they read it in a stack trace or an editor; matching loosely would let "how do I use
+ * data" pin hono's `Data` type ahead of the page that answers the question.
+ */
+async function findDeclarations(
+  options: QueryOptions,
+  prose: readonly QueryHit[],
+  maxTokens: number,
+): Promise<{ declarations: QueryHit[]; undocumented: string[] }> {
+  const scope =
+    options.scoped === false
+      ? undefined
+      : (await discoverLibraries(options.cwd)).map(
+          (library) => `${library.name}@${library.version}`,
+        );
+
+  const declarations: QueryHit[] = [];
+  const undocumented: string[] = [];
+  let spent = prose.reduce((total, hit) => total + hit.tokens, 0);
+
+  for (const term of symbolTerms(options.query)) {
+    if (declarations.length >= MAX_DECLARATIONS) break;
+
+    const found = options.store
+      .lookupSymbol(term, scope)
+      .filter(
+        (hit) =>
+          options.packageFilter === undefined || hit.packageId.includes(options.packageFilter),
+      );
+    if (found.length === 0) continue;
+
+    // The documentation covers it, so the prose that just came back is the better answer.
+    if (prose.some((hit) => mentions(hit.content, term))) continue;
+    undocumented.push(term);
+
+    // The name is exported and undocumented either way; whether a declaration can be shown for
+    // it is a separate question, and a package can export a name it declares nowhere readable.
+    const first = found[0];
+    if (first === undefined || first.chunkId.length === 0) continue;
+    const chunk = options.store.chunk(first.chunkId);
+    if (chunk === undefined) continue;
+    if (declarations.length > 0 && spent + chunk.tokens > maxTokens) break;
+
+    declarations.push(toQueryHit(chunk, "artifact", new Map()));
+    spent += chunk.tokens;
+  }
+
+  return { declarations, undocumented };
+}
+
+/** Identifier-shaped words in a question, longest first so the specific name is tried first. */
+function symbolTerms(query: string): string[] {
+  const terms = query.match(/[A-Za-z_$][\w$]*/g) ?? [];
+  const unique = [...new Set(terms.filter((term) => term.length >= MIN_SYMBOL))];
+  return unique.sort((a, b) => b.length - a.length);
+}
+
+function mentions(content: string, name: string): boolean {
+  return new RegExp(`(^|[^A-Za-z0-9_$])${escapeRegex(name)}([^A-Za-z0-9_$]|$)`).test(content);
+}
+
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function toQueryHit(
+  hit: SearchHit,
+  kind: PackageKind,
+  documented: ReadonlyMap<string, readonly string[]>,
+): QueryHit {
+  const { name, version } = splitPackageId(hit.packageId);
+  // The chunk's own libraries win: they are the narrower, and therefore the truer, claim.
+  const documents = documented.get(hit.chunkId) ?? documented.get(hit.packageId);
+  return {
+    ...hit,
+    name,
+    version,
+    kind,
+    trusted: !isCommunityPackage(name),
+    ...(documents === undefined ? {} : { documents }),
   };
 }
 
@@ -120,18 +240,32 @@ export function renderAnswer(result: QueryResult, query: string): string {
       hit.documents === undefined || hit.documents.length === 0
         ? ""
         : ` · documents ${hit.documents.join(", ")}`;
-    return [
-      `## ${hit.chunkId}${trust}`,
-      `Source: ${hit.name}@${hit.version} — ${hit.filePath}${describes}`,
-      "",
-      hit.content,
-    ].join("\n");
+    const source =
+      hit.kind === "artifact"
+        ? `Source: ${hit.name}@${hit.version} — declared in ${hit.filePath}, read from the installed package`
+        : `Source: ${hit.name}@${hit.version} — ${hit.filePath}${describes}`;
+    return [`## ${hit.chunkId}${trust}`, source, "", hit.content].join("\n");
   });
 
+  if (result.undocumented.length > 0) sections.push(undocumentedNotice(result));
   if (result.untrusted) sections.push(UNTRUSTED_NOTICE);
   return sections.join("\n\n---\n\n");
 }
 
+/**
+ * Saying what the documentation does *not* cover. A ranker always returns its best three matches
+ * and "best" is not "relevant", so without this an answer about a name nobody documented looks
+ * exactly like an answer about one they did.
+ */
+function undocumentedNotice(result: QueryResult): string {
+  const names = result.undocumented.map((name) => `\`${name}\``).join(", ");
+  const plural = result.undocumented.length === 1 ? "is" : "are";
+  const declared = result.hits.some((hit) => hit.kind === "artifact");
+  return declared
+    ? `NOTE: ${names} ${plural} exported by the installed library but mentioned in no documentation package here. The declaration above is the installed build's own, not prose anyone wrote.`
+    : `NOTE: ${names} ${plural} exported by the installed library but mentioned in no documentation package here.`;
+}
+
 /** Splits `@stripe/docspack@2025.4.1` into its name and version. */
 export function splitPackageId(id: string): { name: string; version: string } {
   const at = id.lastIndexOf("@");

package/src/spec.ts

@@ -18,6 +18,12 @@ export interface ChunkSpec {
   readonly tokens?: number;
   readonly tags: readonly string[];
   readonly entities: readonly string[];
+  /**
+   * What this chunk describes, when that is narrower than what the package describes. A
+   * repository publishing eighteen libraries at four versions from one documentation surface
+   * has a package-level answer that is true of the pack and useless about any one chunk.
+   */
+  readonly documents?: readonly DocumentedLibrary[];
 }
 
 /** A library release the package documents, e.g. `acme` at `1.4.0`. */
@@ -116,7 +122,7 @@ export function parseManifest(raw: unknown, where: string): PackageManifest {
   if (typeof version !== "string" || version.length === 0) fail('missing string field "version"');
   if (!Array.isArray(root.chunks)) fail('missing "chunks" array');
 
-  const documents = parseDocuments(root.documents, fail);
+  const packageDocuments = parseDocuments(root.documents, fail);
   const seen = new Set<string>();
   const chunks = (root.chunks as unknown[]).map((entry, index): ChunkSpec => {
     if (typeof entry !== "object" || entry === null)
@@ -142,16 +148,24 @@ export function parseManifest(raw: unknown, where: string): PackageManifest {
       return fail(`chunk "${id}" has an invalid "tokens" value; omit it to have it estimated`);
     }
 
+    const documents = parseDocuments(chunk.documents, fail);
+
     return {
       id,
       file,
       ...(typeof tokens === "number" ? { tokens } : {}),
       tags: stringArray(chunk.tags, `chunk "${id}" field "tags"`, fail),
       entities: stringArray(chunk.entities, `chunk "${id}" field "entities"`, fail),
+      ...(documents === undefined ? {} : { documents }),
     };
   });
 
-  return { name, version, ...(documents === undefined ? {} : { documents }), chunks };
+  return {
+    name,
+    version,
+    ...(packageDocuments === undefined ? {} : { documents: packageDocuments }),
+    chunks,
+  };
 }
 
 /**
@@ -192,7 +206,11 @@ export function serializeManifest(manifest: PackageManifest): string {
       name: manifest.name,
       version: manifest.version,
       ...(documents.length === 0 ? {} : { documents: documents.map(formatDocumentedLibrary) }),
-      chunks: manifest.chunks,
+      chunks: manifest.chunks.map((chunk) =>
+        chunk.documents === undefined
+          ? chunk
+          : { ...chunk, documents: chunk.documents.map(formatDocumentedLibrary) },
+      ),
     },
     null,
     2,