docspack 0.4.0 → 1.0.0

package/src/cli.ts

@@ -3,6 +3,9 @@ import { readFileSync } from "node:fs";
 import { posix } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
+import { applyAgentSetup, planAgentSetup } from "./agent.js";
+import { changedSurface } from "./changed.js";
+import { measureCoverage } from "./coverage.js";
 import { defaultStorePath, Store, silenceSqliteWarning } from "./db.js";
 import { discoverPackages } from "./discovery.js";
 import { type DoctorReport, runDoctor } from "./doctor.js";
@@ -27,6 +30,11 @@ const OPTIONS = {
   cwd: { type: "string" },
   store: { type: "string" },
   force: { type: "boolean" },
+  "no-artifacts": { type: "boolean" },
+  coverage: { type: "boolean" },
+  hooks: { type: "boolean" },
+  mcp: { type: "boolean" },
+  feedback: { type: "boolean" },
   package: { type: "string", short: "p" },
   limit: { type: "string" },
   "max-tokens": { type: "string" },
@@ -141,6 +149,12 @@ function reportDoctor(report: DoctorReport, quiet: boolean): void {
 }
 
 /** 0 when the query was answered; otherwise which of the two empty answers this was. */
+/** Names, capped. A hundred identifiers on one line is a wall, and `--json` has them all. */
+function listed(names: readonly string[], limit = 20): string {
+  if (names.length <= limit) return names.join(", ");
+  return `${names.slice(0, limit).join(", ")} … and ${names.length - limit} more (--json for all)`;
+}
+
 function queryExit(result: QueryResult): number {
   if (result.hits.length > 0) return 0;
   return result.unindexed.length > 0 ? EXIT_NOT_INDEXED : EXIT_NO_MATCH;
@@ -201,6 +215,7 @@ async function main(argv: readonly string[]): Promise<number> {
           cwd,
           store,
           ...(values.force === true ? { force: true } : {}),
+          ...(values["no-artifacts"] === true ? { artifacts: false } : {}),
           ...(quiet || json
             ? {}
             : {
@@ -218,8 +233,11 @@ async function main(argv: readonly string[]): Promise<number> {
         for (const pkg of result.packages) {
           const mark = pkg.status === "indexed" ? green("+") : dim("=");
           const trust = pkg.trusted ? "" : ` ${yellow("(community)")}`;
+          // Declarations read from an installed build are not documentation somebody wrote, and
+          // the listing says so rather than letting them pass for it.
+          const kind = pkg.kind === "artifact" ? ` ${dim("(declarations)")}` : "";
           process.stdout.write(
-            `${mark} ${bold(pkg.id)}  ${pkg.chunks} chunks  ${dim(pkg.status)}${trust}\n`,
+            `${mark} ${bold(pkg.id)}  ${pkg.chunks} chunks  ${dim(pkg.status)}${trust}${kind}\n`,
           );
         }
         for (const problem of result.problems) {
@@ -343,17 +361,38 @@ async function main(argv: readonly string[]): Promise<number> {
       const store = openStore(values);
       try {
         const { packages, problems } = await discoverPackages(cwd);
-        const rows = packages.map((pkg) => ({
-          id: pkg.id,
-          name: pkg.name,
-          version: pkg.version,
-          chunks: pkg.manifest.chunks.length,
-          trusted: pkg.trusted,
-          indexed: store.hasPackage(pkg.id),
-        }));
+        const wantCoverage = values.coverage === true || json;
+        const rows = [];
+        for (const pkg of packages) {
+          rows.push({
+            id: pkg.id,
+            name: pkg.name,
+            version: pkg.version,
+            chunks: pkg.manifest.chunks.length,
+            trusted: pkg.trusted,
+            indexed: store.hasPackage(pkg.id),
+            ...(wantCoverage
+              ? {
+                  coverage: await measureCoverage({
+                    packageDir: pkg.dir,
+                    llmsDir: pkg.llmsDir,
+                    manifest: pkg.manifest,
+                    cwd,
+                  }),
+                }
+              : {}),
+          });
+        }
+
+        const declarations = store
+          .listPackages()
+          .filter((pkg) => pkg.kind === "artifact")
+          .map((pkg) => ({ id: pkg.id, chunks: store.countChunks(pkg.id) }));
 
         if (json) {
-          process.stdout.write(`${JSON.stringify({ packages: rows, problems }, null, 2)}\n`);
+          process.stdout.write(
+            `${JSON.stringify({ packages: rows, declarations, problems }, null, 2)}\n`,
+          );
           return 0;
         }
         if (rows.length === 0) {
@@ -363,6 +402,24 @@ async function main(argv: readonly string[]): Promise<number> {
           const state = row.indexed ? green("indexed") : yellow("not indexed");
           const trust = row.trusted ? "" : ` ${yellow("(community)")}`;
           process.stdout.write(`${bold(row.id)}  ${row.chunks} chunks  ${state}${trust}\n`);
+          for (const library of row.coverage?.libraries ?? []) {
+            const percent =
+              library.names === 0 ? 0 : Math.round((100 * library.documented) / library.names);
+            process.stdout.write(
+              `  ${dim(`documents ${library.documented}/${library.names} (${percent}%) of ${library.library}'s exports`)}\n`,
+            );
+            if (library.uncovered.length > 0) {
+              process.stdout.write(`  ${dim(`missing: ${library.uncovered.join(", ")}`)}\n`);
+            }
+          }
+        }
+        if (declarations.length > 0 && !quiet) {
+          const chunks = declarations.reduce((total, row) => total + row.chunks, 0);
+          process.stdout.write(
+            dim(
+              `\n${declarations.length} installed libraries indexed by declaration, ${chunks} names in all.\n`,
+            ),
+          );
         }
         for (const problem of problems) process.stderr.write(`${yellow("!")} ${problem}\n`);
         return 0;
@@ -371,6 +428,106 @@ async function main(argv: readonly string[]): Promise<number> {
       }
     }
 
+    case "agent": {
+      const [sub = "install"] = rest;
+      if (sub !== "install" && sub !== "check") {
+        throw new DocspackError(`Unknown subcommand "${sub}"`, {
+          hint: "Usage: docspack agent <install|check>",
+        });
+      }
+
+      const plan = await planAgentSetup({
+        cwd,
+        ...(values.feedback === true ? { feedback: true } : {}),
+        ...(values.hooks === true ? { hooks: true } : {}),
+        ...(values.mcp === true ? { mcp: true } : {}),
+      });
+      const pending = plan.files.filter((file) => file.status !== "unchanged");
+
+      if (json) {
+        process.stdout.write(
+          `${JSON.stringify({ files: plan.files.map(({ contents, ...rest }) => rest) }, null, 2)}\n`,
+        );
+        return sub === "check" && pending.length > 0 ? 1 : 0;
+      }
+
+      // `check` is the CI half: it writes nothing and fails when the wiring is missing or stale,
+      // which is the only way a pasted instruction ever gets noticed after it drifts.
+      if (sub === "check") {
+        for (const file of plan.files) {
+          const mark = file.status === "unchanged" ? green("ok") : yellow(file.status);
+          process.stdout.write(`${mark} ${file.path}\n`);
+        }
+        if (pending.length > 0) {
+          process.stderr.write(
+            `\n${yellow("!")} ${plural(pending.length, "file")} out of date. Run \`docspack agent install\`.\n`,
+          );
+        }
+        return pending.length > 0 ? 1 : 0;
+      }
+
+      if (values["dry-run"] === true) {
+        for (const file of plan.files) {
+          process.stdout.write(
+            `${file.status === "unchanged" ? dim("=") : green("+")} ${bold(file.path)}  ${dim(file.reason)}\n`,
+          );
+        }
+        return 0;
+      }
+
+      const written = await applyAgentSetup({ cwd }, plan);
+      for (const file of plan.files) {
+        const mark = file.status === "unchanged" ? dim("=") : green("+");
+        process.stdout.write(
+          `${mark} ${bold(file.path)}  ${dim(file.status === "unchanged" ? "unchanged" : file.reason)}\n`,
+        );
+      }
+      if (written.length > 0 && !quiet) {
+        process.stdout.write(
+          `\n${dim("Commit these. Every agent working in this repository can now read the")}\n${dim("documentation of its dependencies, without anyone being told the command exists.")}\n`,
+        );
+      }
+      return 0;
+    }
+
+    case "changed": {
+      const library = rest[0];
+      if (library === undefined) {
+        throw new DocspackError("Usage: docspack changed <library>[@version]");
+      }
+
+      const store = openStore(values);
+      try {
+        const change = await changedSurface({ cwd, store, library });
+        if (json) {
+          process.stdout.write(`${JSON.stringify(change, null, 2)}\n`);
+          return 0;
+        }
+
+        process.stdout.write(
+          `${bold(`${change.library} ${change.from} → ${change.to}`)}  ${dim(
+            `${change.added.length} added, ${change.removed.length} removed`,
+          )}\n`,
+        );
+        if (change.removed.length > 0) {
+          process.stdout.write(`\n${yellow("gone")}  ${listed(change.removed)}\n`);
+        }
+        if (change.added.length > 0) {
+          process.stdout.write(`\n${green("new")}   ${listed(change.added)}\n`);
+        }
+        if (change.undocumented.length > 0) {
+          process.stdout.write(
+            `\n${dim(
+              `${plural(change.undocumented.length, "new name")} that no documentation package here mentions:`,
+            )}\n${listed(change.undocumented)}\n`,
+          );
+        }
+        return 0;
+      } finally {
+        store.close();
+      }
+    }
+
     case "verify": {
       const report = await verifyProject({
         cwd,

package/src/coverage.ts

@@ -0,0 +1,96 @@
+import { readFile } from "node:fs/promises";
+import { resolvePackageDir } from "./discovery.js";
+import { formatDocumentedLibrary, type PackageManifest, resolveChunkFile } from "./spec.js";
+import { readPublicSurface } from "./surface.js";
+import { documentedLibraries } from "./verify.js";
+
+/** How much of one library's public surface the documentation mentions. */
+export interface LibraryCoverage {
+  readonly library: string;
+  /** Exported names long enough to search prose for. */
+  readonly names: number;
+  /** Those the documentation mentions at least once, anywhere. */
+  readonly documented: number;
+  /** A sample of what it does not mention, for an author to act on. */
+  readonly uncovered: readonly string[];
+}
+
+export interface CoverageReport {
+  readonly libraries: readonly LibraryCoverage[];
+  /** Libraries the package documents whose declarations could not be read. */
+  readonly unreadable: readonly string[];
+}
+
+/**
+ * A name shorter than this is too generic to look for in prose, and its absence would say
+ * nothing: `Env`, `z`, `app`.
+ */
+const MIN_NAME = 4;
+
+/** How many uncovered names are named in the report. */
+const SAMPLE = 12;
+
+export interface CoverageOptions {
+  readonly packageDir: string;
+  readonly llmsDir: string;
+  readonly manifest: PackageManifest;
+  /** Project the library is resolved from when the docs package does not depend on it itself. */
+  readonly cwd: string;
+}
+
+/**
+ * Compares what a documentation package says against what the library it documents exports.
+ *
+ * A documentation site is written page by page around tasks and an API grows name by name, so
+ * the two drift apart with nobody noticing — measured across two well-documented projects, half
+ * of the exported surface is mentioned nowhere. This is the number that makes that visible, and
+ * it is mechanical: two files, no model, no judgement.
+ */
+export async function measureCoverage(options: CoverageOptions): Promise<CoverageReport> {
+  const libraries = await documentedLibraries(options.packageDir, options.manifest);
+  if (libraries.length === 0) return { libraries: [], unreadable: [] };
+
+  const text = await readCorpus(options);
+  const mentioned = identifiers(text);
+  const covered: LibraryCoverage[] = [];
+  const unreadable: string[] = [];
+
+  for (const library of libraries) {
+    const dir =
+      (await resolvePackageDir(library.name, options.packageDir)) ??
+      (await resolvePackageDir(library.name, options.cwd));
+    const surface = dir === undefined ? undefined : await readPublicSurface(dir);
+    if (surface === undefined) {
+      unreadable.push(formatDocumentedLibrary(library));
+      continue;
+    }
+
+    const names = [...surface.symbols.keys()].filter((name) => name.length >= MIN_NAME);
+    const uncovered = names.filter((name) => !mentioned.has(name));
+    covered.push({
+      library: formatDocumentedLibrary(library),
+      names: names.length,
+      documented: names.length - uncovered.length,
+      uncovered: uncovered.slice(0, SAMPLE),
+    });
+  }
+
+  return { libraries: covered, unreadable };
+}
+
+/** Splits text into the identifier-shaped tokens an exact mention would produce. */
+export function identifiers(text: string): Set<string> {
+  return new Set(text.split(/[^A-Za-z0-9_$]+/).filter((token) => token.length > 0));
+}
+
+async function readCorpus(options: CoverageOptions): Promise<string> {
+  const parts: string[] = [];
+  for (const chunk of options.manifest.chunks) {
+    try {
+      parts.push(await readFile(resolveChunkFile(options.llmsDir, chunk.file), "utf8"));
+    } catch {
+      // A chunk that cannot be read is doctor's finding to report, not coverage's.
+    }
+  }
+  return parts.join("\n");
+}

package/src/db.ts

@@ -8,13 +8,29 @@ import { STOPWORDS } from "./stopwords.js";
 
 const require = createRequire(import.meta.url);
 
+/**
+ * Where a package's text came from. `docs` is written by a human and published as a docs
+ * package; `artifact` is derived from an installed library's own type declarations. The
+ * distinction is not cosmetic — a signature is a fact about the build, prose is a claim by its
+ * author — so it is stored rather than inferred from the name.
+ */
+export type PackageKind = "docs" | "artifact";
+
 export interface IndexedPackage {
   readonly id: string;
   readonly name: string;
   readonly version: string;
+  readonly kind?: PackageKind;
   readonly indexedAt?: string;
 }
 
+/** An exported name and the chunk carrying its declaration. */
+export interface SymbolHit {
+  readonly name: string;
+  readonly packageId: string;
+  readonly chunkId: string;
+}
+
 export interface IndexedChunk {
   readonly chunkId: string;
   readonly filePath: string;
@@ -39,15 +55,18 @@ export interface SearchOptions {
   readonly limit?: number;
   /** Stop returning chunks once this many tokens have been collected. */
   readonly maxTokens?: number;
+  /** Restrict to packages of these kinds. Defaults to every kind. */
+  readonly kinds?: readonly PackageKind[];
 }
 
-const SCHEMA_VERSION = 1;
+const SCHEMA_VERSION = 2;
 
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS packages (
     id TEXT PRIMARY KEY,
     name TEXT NOT NULL,
     version TEXT NOT NULL,
+    kind TEXT NOT NULL DEFAULT 'docs',
     indexed_at DATETIME DEFAULT CURRENT_TIMESTAMP
 );
 
@@ -61,6 +80,15 @@ CREATE TABLE IF NOT EXISTS chunks (
 
 CREATE INDEX IF NOT EXISTS chunks_by_package ON chunks(package_id);
 
+CREATE TABLE IF NOT EXISTS symbols (
+    package_id TEXT NOT NULL REFERENCES packages(id),
+    name TEXT NOT NULL,
+    chunk_id TEXT NOT NULL,
+    PRIMARY KEY (package_id, name)
+);
+
+CREATE INDEX IF NOT EXISTS symbols_by_name ON symbols(name);
+
 CREATE VIRTUAL TABLE IF NOT EXISTS chunks_fts USING fts5(
     content,
     tags,
@@ -133,9 +161,22 @@ export class Store {
     this.#db = db;
     this.#db.exec("PRAGMA journal_mode = WAL");
     this.#db.exec(SCHEMA);
+    this.#migrate();
     this.#db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
   }
 
+  /**
+   * Brings a store written by an older version forward. `CREATE TABLE IF NOT EXISTS` covers a
+   * new table, but not a new column on one that already exists, and rebuilding the whole index
+   * to add one would make an upgrade re-read every package on the machine.
+   */
+  #migrate(): void {
+    const columns = this.#db.prepare("PRAGMA table_info(packages)").all() as { name: string }[];
+    if (!columns.some((column) => column.name === "kind")) {
+      this.#db.exec("ALTER TABLE packages ADD COLUMN kind TEXT NOT NULL DEFAULT 'docs'");
+    }
+  }
+
   static open(path: string = defaultStorePath()): Store {
     if (path !== ":memory:") mkdirSync(dirname(path), { recursive: true });
     try {
@@ -154,16 +195,115 @@ export class Store {
 
   listPackages(): IndexedPackage[] {
     const rows = this.#db
-      .prepare("SELECT id, name, version, indexed_at FROM packages ORDER BY name, version")
-      .all() as { id: string; name: string; version: string; indexed_at: string }[];
+      .prepare("SELECT id, name, version, kind, indexed_at FROM packages ORDER BY name, version")
+      .all() as {
+      id: string;
+      name: string;
+      version: string;
+      kind: string;
+      indexed_at: string;
+    }[];
     return rows.map((row) => ({
       id: row.id,
       name: row.name,
       version: row.version,
+      kind: row.kind === "artifact" ? "artifact" : "docs",
       indexedAt: row.indexed_at,
     }));
   }
 
+  /** Every version of one library in the store, newest indexing first. */
+  versionsOf(name: string): IndexedPackage[] {
+    return this.listPackages().filter((pkg) => pkg.name === name);
+  }
+
+  /**
+   * Chunks declaring an exported name, by exact match rather than by ranking.
+   *
+   * A symbol is a key, not a phrase. Ranking one is the mistake that made `docspack ask` unable
+   * to tell "the documentation does not mention this" from "nothing matched".
+   */
+  lookupSymbol(name: string, packageIds?: readonly string[]): SymbolHit[] {
+    if (packageIds !== undefined && packageIds.length === 0) return [];
+    const scope =
+      packageIds === undefined
+        ? ""
+        : ` AND package_id IN (${packageIds.map(() => "?").join(", ")})`;
+    const rows = this.#db
+      .prepare(
+        // A package that declares the name comes first: an empty chunk id means the name is
+        // exported but its declaration was not readable, which answers less.
+        `SELECT name, package_id AS packageId, chunk_id AS chunkId
+           FROM symbols WHERE name = ?${scope}
+          ORDER BY (chunk_id = '') ASC, package_id`,
+      )
+      .all(name, ...(packageIds ?? [])) as {
+      name: string;
+      packageId: string;
+      chunkId: string;
+    }[];
+    return rows.map((row) => ({ name: row.name, packageId: row.packageId, chunkId: row.chunkId }));
+  }
+
+  /** Every chunk of one package, for a check that has to read the whole corpus. */
+  chunksOf(packageId: string): SearchHit[] {
+    const rows = this.#db
+      .prepare(
+        `SELECT chunk_id AS chunkId, package_id AS packageId, file_path AS filePath,
+                tokens, content
+           FROM chunks WHERE package_id = ?`,
+      )
+      .all(packageId) as {
+      chunkId: string;
+      packageId: string;
+      filePath: string;
+      tokens: number;
+      content: string;
+    }[];
+    return rows.map((row) => ({
+      chunkId: row.chunkId,
+      packageId: row.packageId,
+      filePath: row.filePath,
+      tokens: Number(row.tokens ?? 0),
+      content: row.content,
+    }));
+  }
+
+  /** Every exported name recorded for one package. */
+  symbolsOf(packageId: string): string[] {
+    const rows = this.#db
+      .prepare("SELECT name FROM symbols WHERE package_id = ? ORDER BY name")
+      .all(packageId) as { name: string }[];
+    return rows.map((row) => row.name);
+  }
+
+  /** One chunk by its id, however it was found. */
+  chunk(chunkId: string): SearchHit | undefined {
+    const row = this.#db
+      .prepare(
+        `SELECT chunk_id AS chunkId, package_id AS packageId, file_path AS filePath,
+                tokens, content
+           FROM chunks WHERE chunk_id = ?`,
+      )
+      .get(chunkId) as
+      | {
+          chunkId: string;
+          packageId: string;
+          filePath: string;
+          tokens: number;
+          content: string;
+        }
+      | undefined;
+    if (row === undefined) return undefined;
+    return {
+      chunkId: row.chunkId,
+      packageId: row.packageId,
+      filePath: row.filePath,
+      tokens: Number(row.tokens ?? 0),
+      content: row.content,
+    };
+  }
+
   countChunks(packageId: string): number {
     const row = this.#db
       .prepare("SELECT COUNT(*) AS total FROM chunks WHERE package_id = ?")
@@ -171,10 +311,19 @@ export class Store {
     return row.total;
   }
 
-  /** Replaces a package and all of its chunks in a single transaction. */
-  indexPackage(pkg: IndexedPackage, chunks: readonly IndexedChunk[]): void {
+  /**
+   * Replaces a package, all of its chunks and its symbol table in a single transaction.
+   *
+   * `symbols` maps an exported name to the chunk declaring it, and is how a query about a name
+   * is answered without ranking anything.
+   */
+  indexPackage(
+    pkg: IndexedPackage,
+    chunks: readonly IndexedChunk[],
+    symbols?: ReadonlyMap<string, string>,
+  ): void {
     const insertPackage = this.#db.prepare(
-      "INSERT OR REPLACE INTO packages (id, name, version) VALUES (?, ?, ?)",
+      "INSERT OR REPLACE INTO packages (id, name, version, kind) VALUES (?, ?, ?, ?)",
     );
     const insertChunk = this.#db.prepare(
       "INSERT OR REPLACE INTO chunks (chunk_id, package_id, file_path, tokens, content) VALUES (?, ?, ?, ?, ?)",
@@ -182,15 +331,19 @@ export class Store {
     const insertFts = this.#db.prepare(
       "INSERT INTO chunks_fts (content, tags, package_id, chunk_id) VALUES (?, ?, ?, ?)",
     );
+    const insertSymbol = this.#db.prepare(
+      "INSERT OR REPLACE INTO symbols (package_id, name, chunk_id) VALUES (?, ?, ?)",
+    );
 
     this.#db.exec("BEGIN");
     try {
       this.#deleteChunks(pkg.id);
-      insertPackage.run(pkg.id, pkg.name, pkg.version);
+      insertPackage.run(pkg.id, pkg.name, pkg.version, pkg.kind ?? "docs");
       for (const chunk of chunks) {
         insertChunk.run(chunk.chunkId, pkg.id, chunk.filePath, chunk.tokens, chunk.content);
         insertFts.run(chunk.content, chunk.tags.join(" "), pkg.id, chunk.chunkId);
       }
+      for (const [name, chunk] of symbols ?? []) insertSymbol.run(pkg.id, name, chunk);
       this.#db.exec("COMMIT");
     } catch (error) {
       this.#db.exec("ROLLBACK");
@@ -228,6 +381,13 @@ export class Store {
       conditions.push("f.package_id LIKE ?");
       parameters.push(options.packageFilter);
     }
+    if (options.kinds !== undefined) {
+      if (options.kinds.length === 0) return [];
+      conditions.push(
+        `f.package_id IN (SELECT id FROM packages WHERE kind IN (${options.kinds.map(() => "?").join(", ")}))`,
+      );
+      parameters.push(...options.kinds);
+    }
 
     const rows = this.#db
       .prepare(
@@ -272,5 +432,6 @@ export class Store {
   #deleteChunks(packageId: string): void {
     this.#db.prepare("DELETE FROM chunks_fts WHERE package_id = ?").run(packageId);
     this.#db.prepare("DELETE FROM chunks WHERE package_id = ?").run(packageId);
+    this.#db.prepare("DELETE FROM symbols WHERE package_id = ?").run(packageId);
   }
 }

package/src/discovery.ts

@@ -23,6 +23,14 @@ export interface DiscoveredPackage {
   readonly trusted: boolean;
 }
 
+/** An ordinary dependency: a library this project installed, whatever documents it. */
+export interface DiscoveredLibrary {
+  readonly name: string;
+  readonly version: string;
+  /** Root of the installed package. */
+  readonly dir: string;
+}
+
 export interface Discovery {
   readonly packages: readonly DiscoveredPackage[];
   /** Human-readable problems that did not stop discovery, e.g. a declared but uninstalled package. */
@@ -90,19 +98,48 @@ export async function discoverPackages(cwd: string): Promise<Discovery> {
   return { packages, problems };
 }
 
+/**
+ * Every library this project depends on directly, installed and readable.
+ *
+ * Documentation packages are excluded: those are handled by `discoverPackages`, and a docs
+ * package's own type declarations describe nothing anybody asks about.
+ */
+export async function discoverLibraries(cwd: string): Promise<readonly DiscoveredLibrary[]> {
+  const root = resolve(cwd);
+  const names = (await declaredDependencies(root)).filter((name) => !isDocsPackage(name));
+  const libraries: DiscoveredLibrary[] = [];
+
+  for (const name of names) {
+    const dir = await resolvePackageDir(name, root);
+    if (dir === undefined) continue;
+    try {
+      libraries.push({ name, version: await installedVersion(name, dir), dir });
+    } catch {
+      // A dependency with no version in its manifest is not one to index.
+    }
+  }
+
+  return libraries;
+}
+
 /** Package ids installed in this project, used to scope queries to the versions actually in use. */
 export async function projectPackageIds(cwd: string): Promise<string[]> {
   const { packages } = await discoverPackages(cwd);
   return packages.map((pkg) => pkg.id);
 }
 
+/** Docs packages this project depends on, the input to `discoverPackages`. */
+async function declaredDocsPackages(cwd: string): Promise<string[]> {
+  return (await declaredDependencies(cwd)).filter(isDocsPackage);
+}
+
 /**
- * Every docs package declared by this directory or by an ancestor of it. A workspace declares
+ * Every dependency declared by this directory or by an ancestor of it. A workspace declares
  * shared tooling in the repository root and its members inherit the install, so reading only
  * `cwd/package.json` answers "this project has no documentation" for most monorepos — the same
  * upward walk `resolvePackageDir` already does for the install.
  */
-async function declaredDocsPackages(cwd: string): Promise<string[]> {
+async function declaredDependencies(cwd: string): Promise<string[]> {
   const names = new Set<string>();
   let found = false;
   let dir = cwd;
@@ -131,9 +168,7 @@ async function declaredDocsPackages(cwd: string): Promise<string[]> {
     const manifest = parsed as { dependencies?: unknown; devDependencies?: unknown };
     for (const field of [manifest.dependencies, manifest.devDependencies]) {
       if (typeof field !== "object" || field === null) continue;
-      for (const name of Object.keys(field as Record<string, unknown>)) {
-        if (isDocsPackage(name)) names.add(name);
-      }
+      for (const name of Object.keys(field as Record<string, unknown>)) names.add(name);
     }
 
     const parent = dirname(dir);