@driftdev/cli 0.40.0 → 0.42.0

package/README.md

@@ -95,7 +95,7 @@ Entry auto-detects from `package.json` (`types`, `exports`, `main`, `module`, `b
 
 ```bash
 # Machine-readable list of all commands + flags
-drift --capabilities
+drift --tools
 ```
 
 ## Global Options

package/dist/drift.js

@@ -1134,6 +1134,26 @@ function registerBreakingCommand(program) {
   });
 }
 
+// src/commands/commands.ts
+var GROUPS = {
+  Composed: ["scan", "ci", "health"],
+  Analysis: ["coverage", "lint", "examples"],
+  Extraction: ["extract", "list", "get"],
+  Comparison: ["diff", "breaking", "semver", "changelog"],
+  Setup: ["init", "config", "context"],
+  Plumbing: ["validate", "filter", "cache", "report", "release"]
+};
+function registerCommandsCommand(program) {
+  program.command("commands").description("List all available commands grouped by category").action(() => {
+    const maxGroup = Math.max(...Object.keys(GROUPS).map((g) => g.length));
+    for (const [group, cmds] of Object.entries(GROUPS)) {
+      const pad2 = " ".repeat(maxGroup - group.length);
+      process.stdout.write(`  ${group}${pad2}   ${cmds.join(", ")}
+`);
+    }
+  });
+}
+
 // src/formatters/cache.ts
 function renderCacheStatus(data) {
   const lines = [];
@@ -1388,6 +1408,30 @@ function renderContextMarkdown(data) {
     lines.push(`**Average coverage**: ${avgCoverage}%  `);
     lines.push(`**Total lint issues**: ${totalIssues}`);
     lines.push("");
+    for (const pkg of data.packages) {
+      if (pkg.issues && pkg.issues.length > 0) {
+        lines.push(`### ${pkg.name} — Issues`);
+        lines.push("");
+        lines.push("| Export | Type | Location |");
+        lines.push("|--------|------|----------|");
+        for (const issue of pkg.issues) {
+          const loc = issue.filePath ? `${issue.filePath}${issue.line ? `:${issue.line}` : ""}` : "—";
+          lines.push(`| ${issue.export} | ${issue.type} | ${loc} |`);
+        }
+        lines.push("");
+      }
+      if (pkg.undocumentedExports && pkg.undocumentedExports.length > 0) {
+        lines.push(`### ${pkg.name} — Undocumented Exports`);
+        lines.push("");
+        lines.push("| Export | Kind | Location |");
+        lines.push("|--------|------|----------|");
+        for (const exp of pkg.undocumentedExports) {
+          const loc = exp.filePath ? `${exp.filePath}${exp.line ? `:${exp.line}` : ""}` : "—";
+          lines.push(`| ${exp.name} | ${exp.kind} | ${loc} |`);
+        }
+        lines.push("");
+      }
+    }
   }
   if (data.history.length > 0) {
     lines.push("## Recent Activity");
@@ -2061,6 +2105,52 @@ function getCommitSha2() {
     return null;
   }
 }
+function buildPackageContext(name, spec) {
+  const exports = spec.exports ?? [];
+  let documented = 0;
+  const undocumented = [];
+  const undocumentedExports = [];
+  for (const exp of exports) {
+    if (exp.description?.trim()) {
+      documented++;
+    } else {
+      undocumented.push(exp.name);
+      undocumentedExports.push({
+        name: exp.name,
+        kind: exp.kind,
+        filePath: exp.source?.file,
+        line: exp.source?.line
+      });
+    }
+  }
+  const coverage = exports.length > 0 ? Math.round(documented / exports.length * 100) : 100;
+  const driftResult = computeDrift2(spec);
+  const issues = [];
+  let lintIssues = 0;
+  for (const [exportName, drifts] of driftResult.exports) {
+    lintIssues += drifts.length;
+    const exp = exports.find((e) => e.name === exportName);
+    for (const drift of drifts) {
+      issues.push({
+        export: exportName,
+        type: drift.type,
+        issue: drift.issue,
+        filePath: drift.filePath ?? exp?.source?.file,
+        line: drift.line ?? exp?.source?.line
+      });
+    }
+  }
+  return {
+    name,
+    coverage,
+    lintIssues,
+    exports: exports.length,
+    documented,
+    undocumented,
+    issues: issues.length > 0 ? issues : undefined,
+    undocumentedExports: undocumentedExports.length > 0 ? undocumentedExports : undefined
+  };
+}
 function registerContextCommand(program) {
   program.command("context [entry]").description("Generate agent context file with project state").option("--all", "Include all workspace packages").option("--private", "Include private packages in --all mode").option("--output <path>", "Output path (default: ~/.drift/projects/<slug>/context.md)").action(async (entry, options) => {
     const startTime = Date.now();
@@ -2078,28 +2168,7 @@ function registerContextCommand(program) {
           for (const pkg of pkgs) {
             try {
               const { spec } = await cachedExtract(pkg.entry);
-              const exports = spec.exports ?? [];
-              let documented = 0;
-              const undocumented = [];
-              for (const exp of exports) {
-                if (exp.description?.trim())
-                  documented++;
-                else
-                  undocumented.push(exp.name);
-              }
-              const coverage = exports.length > 0 ? Math.round(documented / exports.length * 100) : 100;
-              const driftResult = computeDrift2(spec);
-              let lintIssues = 0;
-              for (const [, drifts] of driftResult.exports)
-                lintIssues += drifts.length;
-              packages.push({
-                name: pkg.name,
-                coverage,
-                lintIssues,
-                exports: exports.length,
-                documented,
-                undocumented
-              });
+              packages.push(buildPackageContext(pkg.name, spec));
             } catch {
               packages.push({
                 name: pkg.name,
@@ -2114,64 +2183,22 @@ function registerContextCommand(program) {
         } else {
           const entryFile = config.entry ? path14.resolve(cwd, config.entry) : detectEntry();
           const { spec } = await cachedExtract(entryFile);
-          const exports = spec.exports ?? [];
-          let documented = 0;
-          const undocumented = [];
-          for (const exp of exports) {
-            if (exp.description?.trim())
-              documented++;
-            else
-              undocumented.push(exp.name);
-          }
-          const coverage = exports.length > 0 ? Math.round(documented / exports.length * 100) : 100;
-          const driftResult = computeDrift2(spec);
-          let lintIssues = 0;
-          for (const [, drifts] of driftResult.exports)
-            lintIssues += drifts.length;
           const pkgJsonPath = path14.resolve(cwd, "package.json");
           let name = path14.basename(cwd);
           try {
             name = JSON.parse(readFileSync12(pkgJsonPath, "utf-8")).name ?? name;
           } catch {}
-          packages.push({
-            name,
-            coverage,
-            lintIssues,
-            exports: exports.length,
-            documented,
-            undocumented
-          });
+          packages.push(buildPackageContext(name, spec));
         }
       } else {
         const entryFile = path14.resolve(cwd, entry);
         const { spec } = await cachedExtract(entryFile);
-        const exports = spec.exports ?? [];
-        let documented = 0;
-        const undocumented = [];
-        for (const exp of exports) {
-          if (exp.description?.trim())
-            documented++;
-          else
-            undocumented.push(exp.name);
-        }
-        const coverage = exports.length > 0 ? Math.round(documented / exports.length * 100) : 100;
-        const driftResult = computeDrift2(spec);
-        let lintIssues = 0;
-        for (const [, drifts] of driftResult.exports)
-          lintIssues += drifts.length;
         const pkgJsonPath = path14.resolve(cwd, "package.json");
         let name = path14.basename(cwd);
         try {
           name = JSON.parse(readFileSync12(pkgJsonPath, "utf-8")).name ?? name;
         } catch {}
-        packages.push({
-          name,
-          coverage,
-          lintIssues,
-          exports: exports.length,
-          documented,
-          undocumented
-        });
+        packages.push(buildPackageContext(name, spec));
       }
       const contextData = { packages, history, config, commit: commit ?? null };
       if (options.output) {
@@ -3601,8 +3628,7 @@ import {
   buildExportRegistry,
   computeDrift as computeDrift4,
   detectProseDrift,
-  discoverMarkdownFiles,
-  isFixableDrift
+  discoverMarkdownFiles
 } from "@driftdev/sdk";
 
 // src/formatters/lint.ts
@@ -3715,16 +3741,9 @@ function registerLintCommand(program) {
         }
       } catch {}
       const data = { issues, count: issues.length };
-      let fixableCount = 0;
-      for (const [, drifts] of driftResult.exports) {
-        for (const d of drifts) {
-          if (isFixableDrift(d))
-            fixableCount++;
-        }
-      }
       const next = issues.length > 0 ? {
         suggested: "drift-fix skill",
-        reason: `${fixableCount} of ${issues.length} issues are auto-fixable`
+        reason: `${issues.length} issue${issues.length === 1 ? "" : "s"} found`
       } : undefined;
       formatOutput("lint", data, startTime, version, renderLint, next);
       if (issues.length > 0) {
@@ -4197,8 +4216,7 @@ import {
   buildExportRegistry as buildExportRegistry2,
   computeDrift as computeDrift8,
   detectProseDrift as detectProseDrift2,
-  discoverMarkdownFiles as discoverMarkdownFiles2,
-  isFixableDrift as isFixableDrift2
+  discoverMarkdownFiles as discoverMarkdownFiles2
 } from "@driftdev/sdk";
 
 // src/formatters/scan.ts
@@ -4387,16 +4405,9 @@ function registerScanCommand(program) {
       };
       let next;
       if (issues.length > 0) {
-        let fixableCount = 0;
-        for (const [, drs] of driftResult.exports) {
-          for (const d of drs) {
-            if (isFixableDrift2(d))
-              fixableCount++;
-          }
-        }
         next = {
           suggested: "drift-fix skill",
-          reason: `${fixableCount} of ${issues.length} issues are auto-fixable`
+          reason: `${issues.length} issue${issues.length === 1 ? "" : "s"} found`
         };
       } else if (total - documented > 0) {
         next = {
@@ -4516,6 +4527,29 @@ function extractFlags(cmd) {
     type: optionType(opt)
   }));
 }
+var COMMAND_EXAMPLES = {
+  scan: ["drift scan --json", "drift scan --all --json", "drift scan --ci --json"],
+  lint: ["drift lint --json", "drift lint --all --json"],
+  coverage: ["drift coverage --json", "drift coverage --min 80 --json"],
+  extract: ["drift extract --json"],
+  list: ["drift list --json"],
+  get: ["drift get createClient --json"],
+  diff: ["drift diff --base main --json"],
+  breaking: ["drift breaking --base main --json"],
+  semver: ["drift semver --base main --json"],
+  changelog: ["drift changelog --base main --json"],
+  ci: ["drift ci --json", "drift ci --all --json"],
+  release: ["drift release --json"],
+  context: ["drift context --json", "drift context --all --json"],
+  examples: ["drift examples --typecheck --json"],
+  health: ["drift health --json"],
+  config: ["drift config list --json", "drift config get coverage.min --json"],
+  init: ["drift init --json"],
+  validate: ["drift validate spec.json --json"],
+  filter: ["drift filter spec.json --kind function --json"],
+  report: ["drift report --json"],
+  cache: ["drift cache status", "drift cache clear"]
+};
 function extractCapabilities(program) {
   const commands = [];
   for (const cmd of program.commands) {
@@ -4524,11 +4558,14 @@ function extractCapabilities(program) {
       name: cmd.name(),
       description: cmd.description(),
       flags: extractFlags(cmd),
-      ...positionalArgs.length > 0 ? { positional: positionalArgs.map((a) => a.name()).join(" ") } : {}
+      ...positionalArgs.length > 0 ? { positional: positionalArgs.map((a) => a.name()).join(" ") } : {},
+      ...COMMAND_EXAMPLES[cmd.name()] ? { examples: COMMAND_EXAMPLES[cmd.name()] } : {}
     });
   }
   return {
     version: program.version() ?? "0.0.0",
+    hint: "Run 'drift' for human output. Use these primitives with --json for agent workflows.",
+    humanCommands: ["scan", "ci", "init"],
     commands,
     globalFlags: extractFlags(program),
     entities: [
@@ -4579,7 +4616,7 @@ var __filename2 = fileURLToPath2(import.meta.url);
 var __dirname3 = path29.dirname(__filename2);
 var packageJson = JSON.parse(readFileSync22(path29.join(__dirname3, "../package.json"), "utf-8"));
 var program = new Command;
-program.name("drift").description("drift — documentation quality primitives for TypeScript").version(packageJson.version).option("--json", "Force JSON output (default when piped)").option("--human", "Force human-readable output (default in terminal)").option("--config <path>", "Path to drift config file").option("--cwd <dir>", "Run as if started in <dir>").option("--no-cache", "Bypass spec cache").hook("preAction", (_thisCommand) => {
+program.name("drift").description("drift — documentation quality for TypeScript").version(packageJson.version).option("--json", "Force JSON output (default when piped)").option("--human", "Force human-readable output (default in terminal)").option("--config <path>", "Path to drift config file").option("--cwd <dir>", "Run as if started in <dir>").option("--no-cache", "Bypass spec cache").option("--tools", "List all available tools for agent use (JSON)").hook("preAction", (_thisCommand) => {
   const opts = program.opts();
   if (opts.cwd) {
     process.chdir(path29.resolve(opts.cwd));
@@ -4610,19 +4647,24 @@ registerInitCommand(program);
 registerConfigCommand(program);
 registerContextCommand(program);
 registerCacheCommand(program);
-if (process.argv.includes("--capabilities")) {
+registerCommandsCommand(program);
+var HUMAN_COMMANDS = new Set(["scan", "ci", "init", "commands"]);
+for (const cmd of program.commands) {
+  if (!HUMAN_COMMANDS.has(cmd.name())) {
+    cmd._hidden = true;
+  }
+}
+if (process.argv.includes("--tools")) {
   const caps = extractCapabilities(program);
   process.stdout.write(`${JSON.stringify(caps, null, 2)}
 `);
   process.exit(0);
 }
 var rawArgs = process.argv.slice(2);
-var hasHelpOrVersion = rawArgs.some((a) => ["-h", "--help", "-V", "--version"].includes(a));
+var hasHelpOrVersion = rawArgs.some((a) => ["-h", "--help", "-V", "--version", "--tools"].includes(a));
 var userArgs = rawArgs.filter((a) => !a.startsWith("-"));
 if (userArgs.length === 0 && !hasHelpOrVersion) {
-  const { configPath } = loadConfig();
-  const subcommand = configPath ? "health" : "init";
-  process.argv.splice(2, 0, subcommand);
+  process.argv.splice(2, 0, "scan");
 }
 program.parseAsync().catch(() => {
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftdev/cli",
-  "version": "0.40.0",
+  "version": "0.42.0",
   "description": "Drift CLI - Documentation coverage and drift detection for TypeScript",
   "keywords": [
     "typescript",
@@ -43,8 +43,7 @@
     "dist"
   ],
   "dependencies": {
-    "@driftdev/sdk": "^0.39.0",
-    "@driftdev/spec": "^0.36.0",
+    "@driftdev/sdk": "^0.42.0",
     "@openpkg-ts/sdk": "^0.37.0",
     "@openpkg-ts/spec": "^0.37.0",
     "chalk": "^5.4.1",