docspack 1.1.0 → 1.3.0

package/src/discovery.ts

@@ -1,7 +1,9 @@
 import { readFile } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, resolve, sep } from "node:path";
 import { DocspackError } from "./errors.js";
 import {
+  cliPackageId,
+  DISCOVERABLE_NAMES,
   isCommunityPackage,
   isDocsPackage,
   LLMS_DIR,
@@ -38,17 +40,20 @@ export interface Discovery {
 }
 
 /**
- * Finds the documentation packages a project depends on: every `@vendor/docspack` or
- * `@docspack-community/*` entry in `dependencies` or `devDependencies` that is installed and
- * ships a `.llms/manifest.json`.
+ * Finds the documentation packages a project depends on: every `@vendor/docspack`,
+ * `@vendor/<name>-docspack` or `@docspack-community/*` entry in `dependencies` or
+ * `devDependencies` that is installed and ships a `.llms/manifest.json`.
+ *
+ * A dependency that ships a payload under any other name is reported in `problems` rather than
+ * indexed, so a pack nobody can read says so instead of going missing from every answer.
  */
 export async function discoverPackages(cwd: string): Promise<Discovery> {
   const root = resolve(cwd);
-  const declared = await declaredDocsPackages(root);
+  const declared = await declaredDependencies(root);
   const packages: DiscoveredPackage[] = [];
   const problems: string[] = [];
 
-  for (const name of declared) {
+  for (const name of declared.filter(isDocsPackage)) {
     const dir = await resolvePackageDir(name, root);
     if (dir === undefined) {
       problems.push(`${name} is declared in package.json but is not installed`);
@@ -94,10 +99,62 @@ export async function discoverPackages(cwd: string): Promise<Discovery> {
     });
   }
 
+  problems.push(...(await skippedPayloads(declared.filter(isNotDocsPackage), root)));
+
   packages.sort((a, b) => a.name.localeCompare(b.name));
   return { packages, problems };
 }
 
+/**
+ * Dependencies that ship a payload under a name discovery does not match.
+ *
+ * None of them is indexed, and that is the point: the name check is what decides whether a
+ * package may put content in front of a model, and widening it to "carries a manifest" would let
+ * any transitive dependency opt itself in. But a package built by `docspack build` and then named
+ * outside the discoverable shapes is a publishing mistake — a typo, a rename, or a reading of the
+ * naming rule — and saying nothing about it is worse than refusing it. The corpus is absent from
+ * every answer while the question it should have answered is answered confidently by another pack.
+ */
+async function skippedPayloads(names: readonly string[], root: string): Promise<string[]> {
+  // Concurrent, unlike the loop over docs packages above: this one runs over every dependency
+  // the project declares rather than the handful that document something, and `docspack ask`
+  // pays for it on each question. The reads are independent, and `Promise.all` keeps the order
+  // of `names` so the report is the same on every run.
+  const found = await Promise.all(names.map((name) => skippedPayload(name, root)));
+  return found.filter((problem) => problem !== undefined);
+}
+
+async function skippedPayload(name: string, root: string): Promise<string | undefined> {
+  const dir = await resolvePackageDir(name, root);
+  if (dir === undefined) return undefined;
+
+  let raw: string;
+  try {
+    raw = await readFile(join(dir, LLMS_DIR, MANIFEST_FILE), "utf8");
+  } catch {
+    return undefined;
+  }
+
+  // Counted rather than validated: a manifest too malformed to parse is still a payload its
+  // publisher meant to be read, and the name is the problem to report either way.
+  let chunks = 0;
+  try {
+    const parsed = JSON.parse(raw) as { chunks?: unknown };
+    if (Array.isArray(parsed.chunks)) chunks = parsed.chunks.length;
+  } catch {
+    // Not JSON. Report the name anyway; `docspack doctor` is where the payload is checked.
+  }
+
+  return (
+    `${name} ships ${LLMS_DIR}/${MANIFEST_FILE} with ${chunks} ${chunks === 1 ? "chunk" : "chunks"} but was not indexed: ` +
+    `its name is not a discoverable pack shape (${DISCOVERABLE_NAMES})`
+  );
+}
+
+function isNotDocsPackage(name: string): boolean {
+  return !isDocsPackage(name);
+}
+
 /**
  * Every library this project depends on directly, installed and readable.
  *
@@ -106,7 +163,7 @@ export async function discoverPackages(cwd: string): Promise<Discovery> {
  */
 export async function discoverLibraries(cwd: string): Promise<readonly DiscoveredLibrary[]> {
   const root = resolve(cwd);
-  const names = (await declaredDependencies(root)).filter((name) => !isDocsPackage(name));
+  const names = (await declaredDependencies(root)).filter(isNotDocsPackage);
   const libraries: DiscoveredLibrary[] = [];
 
   for (const name of names) {
@@ -122,17 +179,61 @@ export async function discoverLibraries(cwd: string): Promise<readonly Discovere
   return libraries;
 }
 
+/** An installed library that describes its own command-line interface. */
+export interface DiscoveredCommandLine extends DiscoveredLibrary {
+  /** The id its commands are indexed under: the library's, marked as a CLI. */
+  readonly id: string;
+  /** Each description it names, as absolute paths inside the package. */
+  readonly documents: readonly string[];
+}
+
+/**
+ * Libraries whose `package.json` names a cmdspec document (`packages/cmdspec/SPEC.md` §13):
+ * `"cmdspec": "./cmdspec.json"`, or one per executable, `"cmdspec": { "tool": "./tool.json" }`.
+ *
+ * A path that resolves outside the package is ignored. The field is a dependency's own metadata,
+ * and reading wherever it points would let any installed package put any file on this machine
+ * into the index.
+ */
+export async function discoverCommandLines(
+  cwd: string,
+  libraries?: readonly DiscoveredLibrary[],
+): Promise<DiscoveredCommandLine[]> {
+  const found: DiscoveredCommandLine[] = [];
+  for (const library of libraries ?? (await discoverLibraries(cwd))) {
+    let field: unknown;
+    try {
+      field = (
+        JSON.parse(await readFile(join(library.dir, "package.json"), "utf8")) as {
+          cmdspec?: unknown;
+        }
+      ).cmdspec;
+    } catch {
+      continue;
+    }
+    const named =
+      typeof field === "string"
+        ? [field]
+        : typeof field === "object" && field !== null && !Array.isArray(field)
+          ? Object.values(field).filter((value): value is string => typeof value === "string")
+          : [];
+    const root = resolve(library.dir);
+    const documents = named
+      .map((path) => resolve(root, path))
+      .filter((path) => path.startsWith(`${root}${sep}`));
+    if (documents.length > 0) {
+      found.push({ ...library, id: cliPackageId(library.name, library.version), documents });
+    }
+  }
+  return found;
+}
+
 /** 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 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

package/src/doctor.ts

@@ -1,11 +1,14 @@
 import type { Dirent } from "node:fs";
 import { readdir, readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
+import { commandFindings } from "./commands.js";
 import { readBuildConfig } from "./config.js";
 import { measureCoverage } from "./coverage.js";
 import { PLACEHOLDER } from "./init/templates.js";
 import {
+  DISCOVERABLE_NAMES,
   estimateTokens,
+  isDocsPackage,
   LLMS_DIR,
   MANIFEST_FILE,
   type PackageManifest,
@@ -208,6 +211,7 @@ export async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
   }
 
   findings.push(...(await coverageFindings(options.dir, llmsDir, manifest)));
+  findings.push(...(await commandLineFindings(options.dir)));
 
   if (manifest.chunks.every((chunk) => chunk.entities.length === 0)) {
     findings.push({
@@ -347,6 +351,21 @@ function checkPackageJson(
     });
   }
 
+  // The one property that decides whether the indexer will open the package at all, and the one
+  // this check used to skip: every other check here describes a package that indexes badly, and
+  // a name outside the discoverable shapes describes one that is never read. It publishes, it
+  // installs, it passes every other check, and the corpus is absent from every answer.
+  const name = typeof pkg.name === "string" ? pkg.name : manifest.name;
+  if (!isDocsPackage(name)) {
+    findings.push({
+      check: "name-undiscoverable",
+      severity: "error",
+      message: `"${name}" is not a name the indexer discovers; the package would install and never be read`,
+      where: "package.json",
+      fix: `Rename it to one of ${DISCOVERABLE_NAMES}.`,
+    });
+  }
+
   const files = Array.isArray(pkg.files) ? pkg.files.map(String) : undefined;
   if (
     files !== undefined &&
@@ -373,6 +392,7 @@ async function newestSourceMtime(dir: string): Promise<number> {
   const config = await readBuildConfig(dir);
   const newest = await Promise.all([
     config.openapi === undefined ? 0 : mtime(join(dir, config.openapi)),
+    config.cmdspec === undefined ? 0 : mtime(join(dir, config.cmdspec)),
     config.from === undefined ? 0 : newestInTree(join(dir, config.from)),
   ]);
   return Math.max(...newest);
@@ -445,6 +465,53 @@ async function coverageFindings(
   return findings;
 }
 
+/**
+ * The configured CLI description, checked the way `build` checks it: invalid is an error, because
+ * the next build will refuse it; the rest is `commandFindings`. Nothing to check without
+ * `docspack.cmdspec`, since a package built from a flag does not say where its description is.
+ */
+async function commandLineFindings(dir: string): Promise<Finding[]> {
+  const source = (await readBuildConfig(dir)).cmdspec;
+  if (source === undefined) return [];
+  const file = join(dir, source);
+  const { convertText, readSource } = await import("@docspack/cmdspec/read");
+  const { validate } = await import("@docspack/cmdspec/validate");
+  let document: Awaited<ReturnType<typeof convertText>>["document"];
+  try {
+    ({ document } = await convertText(await readSource(file), { where: source }));
+  } catch (error) {
+    return [
+      {
+        check: "cli-unreadable",
+        severity: "error",
+        message: `${source}: ${error instanceof Error ? error.message : String(error)}`,
+        fix: "Point docspack.cmdspec at a cmdspec, OpenCLI or Usage document.",
+      },
+    ];
+  }
+  const result = validate(document);
+  if (!result.valid) {
+    return [
+      {
+        check: "cli-invalid",
+        severity: "error",
+        message: `${source} is not a valid CLI description: ${result.problems
+          .slice(0, 3)
+          .map((problem) => `${problem.at}: ${problem.message}`)
+          .join("; ")}${result.problems.length > 3 ? `; …${result.problems.length - 3} more` : ""}`,
+        where: source,
+        fix: `Run \`npx @docspack/cmdspec validate ${source}\` for every problem.`,
+      },
+    ];
+  }
+  return commandFindings(document).map((finding) => ({
+    check: "cli-incomplete",
+    severity: finding.severity,
+    message: finding.message,
+    where: source,
+  }));
+}
+
 async function readJson(path: string): Promise<Record<string, unknown> | undefined> {
   try {
     const parsed: unknown = JSON.parse(await readFile(path, "utf8"));