docspack 0.4.0 → 1.0.0

package/src/doctor.ts

@@ -2,6 +2,7 @@ import type { Dirent } from "node:fs";
 import { readdir, readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { readBuildConfig } from "./config.js";
+import { measureCoverage } from "./coverage.js";
 import { PLACEHOLDER } from "./init/templates.js";
 import {
   estimateTokens,
@@ -48,6 +49,13 @@ export interface DoctorOptions {
   readonly pedantic?: boolean;
 }
 
+/**
+ * Below this share of a library's exported names, a package is documenting a fraction of what
+ * the library publishes. Reported, never gated on: a page listing every export and explaining
+ * none would score full marks, so this is a number for an author to read, not a wall.
+ */
+const THIN_COVERAGE = 0.6;
+
 /** Over this, a chunk crowds out the response budget; under it, a chunk answers nothing. */
 const MAX_CHUNK_TOKENS = 1500;
 const MIN_CHUNK_TOKENS = 30;
@@ -199,6 +207,8 @@ export async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
     });
   }
 
+  findings.push(...(await coverageFindings(options.dir, llmsDir, manifest)));
+
   if (manifest.chunks.every((chunk) => chunk.entities.length === 0)) {
     findings.push({
       check: "no-entities",
@@ -385,6 +395,48 @@ async function mtime(path: string): Promise<number> {
   }
 }
 
+/**
+ * How much of the documented library's public surface the package mentions.
+ *
+ * A documentation site is written page by page around tasks and an API grows name by name, so
+ * they drift apart with nobody noticing. This is the check that notices — mechanical, from two
+ * files, with no model and no judgement in it.
+ */
+async function coverageFindings(
+  dir: string,
+  llmsDir: string,
+  manifest: PackageManifest,
+): Promise<Finding[]> {
+  const findings: Finding[] = [];
+  let report: Awaited<ReturnType<typeof measureCoverage>>;
+  try {
+    report = await measureCoverage({ packageDir: dir, llmsDir, manifest, cwd: dir });
+  } catch {
+    // Coverage is a note about the documentation, never a reason a package fails to check.
+    return findings;
+  }
+
+  for (const library of report.libraries) {
+    if (library.names === 0) continue;
+    const share = library.documented / library.names;
+    const percent = Math.round(100 * share);
+    findings.push({
+      check: "coverage",
+      severity: "info",
+      message:
+        `mentions ${library.documented} of ${library.names} names ${library.library} exports (${percent}%)` +
+        (library.uncovered.length === 0 ? "" : `; missing ${library.uncovered.join(", ")}`),
+      ...(share < THIN_COVERAGE
+        ? {
+            fix: "Document the exports nobody has written about, or narrow what the package claims to document.",
+          }
+        : {}),
+    });
+  }
+
+  return findings;
+}
+
 async function readJson(path: string): Promise<Record<string, unknown> | undefined> {
   try {
     const parsed: unknown = JSON.parse(await readFile(path, "utf8"));

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 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,12 +28,19 @@ 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
@@ -45,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> {
@@ -71,33 +93,123 @@ export async function queryDocs(options: QueryOptions): Promise<QueryResult> {
     }
   }
 
-  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);
-      // 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,
-        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 }),
   };
 }
 
@@ -128,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("@");