docspack 0.4.0 → 1.1.0

package/src/cli.ts

@@ -3,7 +3,10 @@ import { readFileSync } from "node:fs";
 import { posix } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
-import { defaultStorePath, Store, silenceSqliteWarning } from "./db.js";
+import { applyAgentSetup, planAgentSetup } from "./agent.js";
+import { changedSurface } from "./changed.js";
+import { measureCoverage } from "./coverage.js";
+import { defaultStorePath, localStorePath, Store, silenceSqliteWarning } from "./db.js";
 import { discoverPackages } from "./discovery.js";
 import { type DoctorReport, runDoctor } from "./doctor.js";
 import { DocspackError } from "./errors.js";
@@ -27,11 +30,17 @@ 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" },
   all: { type: "boolean" },
   from: { type: "string" },
+  "from-json": { type: "string" },
   openapi: { type: "string" },
   out: { type: "string" },
   name: { type: "string" },
@@ -39,6 +48,7 @@ const OPTIONS = {
   pages: { type: "string" },
   "max-chunk-tokens": { type: "string" },
   "min-chunk-tokens": { type: "string" },
+  local: { type: "boolean" },
   documents: { type: "string", multiple: true },
   "min-hit-rate": { type: "string" },
   mirror: { type: "string" },
@@ -141,6 +151,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;
@@ -150,6 +166,11 @@ function openStore(values: Values): Store {
   return Store.open(values.store ?? defaultStorePath());
 }
 
+/** The project's own corpus, which is never the machine-wide store unless asked for by path. */
+function openLocalStore(values: Values, cwd: string): Store {
+  return Store.open(values.store ?? localStorePath(cwd));
+}
+
 async function main(argv: readonly string[]): Promise<number> {
   let values: Values;
   let positionals: string[];
@@ -201,6 +222,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 +240,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) {
@@ -284,6 +309,83 @@ async function main(argv: readonly string[]): Promise<number> {
       }
     }
 
+    case "index": {
+      const { indexLocal } = await import("./local.js");
+      const store = openLocalStore(values, cwd);
+      try {
+        const result = await indexLocal({
+          cwd,
+          store,
+          ...(values.from === undefined ? {} : { from: values.from }),
+          ...(values["from-json"] === undefined ? {} : { json: values["from-json"] }),
+          ...(values.name === undefined ? {} : { name: values.name }),
+          ...(values.force === true ? { force: true } : {}),
+          ...(quiet || json
+            ? {}
+            : {
+                onProgress: (message: string): void => {
+                  process.stderr.write(`${dim(message)}\n`);
+                },
+              }),
+        });
+
+        if (json) {
+          process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+          return 0;
+        }
+        const state =
+          result.status === "unchanged"
+            ? dim("unchanged")
+            : `${String(result.chunks)} chunks  ${dim(`~${String(result.tokens)} tokens`)}`;
+        process.stdout.write(`${green("+")} ${bold(result.name)}  ${state}\n`);
+        for (const warning of result.warnings) process.stderr.write(`${yellow("!")} ${warning}\n`);
+        if (!quiet) {
+          process.stdout.write(
+            result.streamed
+              ? `\nIndexed from a stream, so nothing can tell later whether it is still current.\nAsk it with \`docspack recall "<question>"\`.\n`
+              : `\nAsk it with \`docspack recall "<question>"\`. Re-run this after editing the sources.\n`,
+          );
+        }
+        return 0;
+      } finally {
+        store.close();
+      }
+    }
+
+    case "recall": {
+      const question = rest.join(" ");
+      if (question.length === 0) {
+        throw new DocspackError('Usage: docspack recall "<question>"');
+      }
+
+      const { recallLocal, renderRecall } = await import("./local.js");
+      const store = openLocalStore(values, cwd);
+      try {
+        const result = await recallLocal({
+          cwd,
+          store,
+          query: question,
+          ...(() => {
+            const limit = integer(values.limit, "--limit");
+            return limit === undefined ? {} : { limit };
+          })(),
+          ...(() => {
+            const maxTokens = integer(values["max-tokens"], "--max-tokens");
+            return maxTokens === undefined ? {} : { maxTokens };
+          })(),
+        });
+
+        if (json) {
+          process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        } else {
+          process.stdout.write(`${renderRecall(result, question)}\n`);
+        }
+        return result.hits.length === 0 ? 1 : 0;
+      } finally {
+        store.close();
+      }
+    }
+
     case "search": {
       const query = rest.join(" ");
       if (query.length === 0) throw new DocspackError("Usage: docspack search <query>");
@@ -330,6 +432,11 @@ async function main(argv: readonly string[]): Promise<number> {
           }
           process.stdout.write("\n");
         }
+        if (result.endpoints.length > 0) {
+          // Which hits were addressed rather than ranked. A reader who asked about a concrete URL
+          // and got a chunk about a template path needs to see that the match was the template.
+          process.stdout.write(dim(`matched by endpoint: ${result.endpoints.join(", ")}\n`));
+        }
         process.stdout.write(
           dim(`${result.tokens} tokens across ${plural(result.hits.length, "chunk")}\n`),
         );
@@ -343,17 +450,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 +491,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 +517,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,
@@ -605,7 +851,9 @@ async function main(argv: readonly string[]): Promise<number> {
         out: values.out ?? cwd,
         ...(rest[0] === undefined ? {} : { source: rest[0] }),
         ...(values.from === undefined ? {} : { from: values.from }),
+        ...(values["from-json"] === undefined ? {} : { json: values["from-json"] }),
         ...(values.openapi === undefined ? {} : { openapi: values.openapi }),
+        ...(values.local === true ? { local: true } : {}),
         ...(values.name === undefined ? {} : { name: values.name }),
         ...(values["pkg-version"] === undefined ? {} : { version: values["pkg-version"] }),
         ...(() => {
@@ -639,8 +887,11 @@ async function main(argv: readonly string[]): Promise<number> {
       );
       for (const warning of result.warnings) process.stderr.write(`${yellow("!")} ${warning}\n`);
       if (!quiet) {
+        // A local build is not going to npm, so the publishing instruction would be wrong advice.
         process.stdout.write(
-          `\nWrote ${result.dir}/.llms and ${result.dir}/llms.txt.\nPublish with \`npm publish\`, then add it to a project and run \`docspack sync\`.\n`,
+          values.local === true
+            ? `\nWrote ${result.dir}/.llms and ${result.dir}/llms.txt.\nTo index a corpus into this project instead, use \`docspack index\`.\n`
+            : `\nWrote ${result.dir}/.llms and ${result.dir}/llms.txt.\nPublish with \`npm publish\`, then add it to a project and run \`docspack sync\`.\n`,
         );
       }
       return 0;

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");
+}