feat(cli): two-surface architecture with --tools and enriched context

ryanwaits · ryanwaits · commit 0845596c56af · 2026-02-14T05:28:24.000-06:00
diff --git a/bun.lock b/bun.lock
diff --git a/packages/cli/CHANGELOG.md b/packages/cli/CHANGELOG.md
@@ -1,5 +1,11 @@
 # @doccov/cli
 
+## 0.40.0
+
+### Minor Changes
+
+- Two-surface CLI: hide non-human commands from --help, default bare `drift` to scan, replace --capabilities with --tools, enrich context with per-issue detail and undocumented export locations
+
 ## 0.39.0
 
 ### Minor Changes
diff --git a/packages/cli/package.json b/packages/cli/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@driftdev/cli",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "description": "Drift CLI - Documentation coverage and drift detection for TypeScript",
   "keywords": [
     "typescript",
diff --git a/packages/cli/src/commands/context.ts b/packages/cli/src/commands/context.ts
@@ -1,14 +1,17 @@
 import { execSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import * as path from 'node:path';
-import { computeDrift } from '@driftdev/sdk';
+import type { OpenPkgSpec } from '@openpkg-ts/spec';
+import { computeDrift, isFixableDrift } from '@driftdev/sdk';
 import type { Command } from 'commander';
 import { cachedExtract } from '../cache/cached-extract';
 import { loadConfig } from '../config/loader';
 import { renderContext } from '../formatters/context';
 import {
   type ContextData,
   type PackageContext,
+  type PackageIssue,
+  type UndocumentedExport,
   renderContextMarkdown,
   writeContext,
 } from '../utils/context-writer';
@@ -26,6 +29,59 @@ function getCommitSha(): string | null {
   }
 }
 
+function buildPackageContext(name: string, spec: OpenPkgSpec): PackageContext {
+  const exports = spec.exports ?? [];
+  let documented = 0;
+  const undocumented: string[] = [];
+  const undocumentedExports: UndocumentedExport[] = [];
+
+  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 = computeDrift(spec);
+  const issues: PackageIssue[] = [];
+  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,
+        fixable: isFixableDrift(drift),
+      });
+    }
+  }
+
+  return {
+    name,
+    coverage,
+    lintIssues,
+    exports: exports.length,
+    documented,
+    undocumented,
+    issues: issues.length > 0 ? issues : undefined,
+    undocumentedExports: undocumentedExports.length > 0 ? undocumentedExports : undefined,
+  };
+}
+
 export function registerContextCommand(program: Command): void {
   program
     .command('context [entry]')
@@ -49,7 +105,6 @@ export function registerContextCommand(program: Command): void {
           const packages: PackageContext[] = [];
 
           if (options.all || !entry) {
-            // Multi-package: discover workspace packages
             const allPackages = discoverPackages(cwd);
             const pkgs =
               allPackages && allPackages.length > 0
@@ -62,26 +117,7 @@ export function registerContextCommand(program: Command): void {
               for (const pkg of pkgs) {
                 try {
                   const { spec } = await cachedExtract(pkg.entry);
-                  const exports = spec.exports ?? [];
-                  let documented = 0;
-                  const undocumented: string[] = [];
-                  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 = computeDrift(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,
@@ -94,66 +130,24 @@ export function registerContextCommand(program: Command): void {
                 }
               }
             } else {
-              // Single package fallback
               const entryFile = config.entry ? path.resolve(cwd, config.entry) : detectEntry();
               const { spec } = await cachedExtract(entryFile);
-              const exports = spec.exports ?? [];
-              let documented = 0;
-              const undocumented: string[] = [];
-              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 = computeDrift(spec);
-              let lintIssues = 0;
-              for (const [, drifts] of driftResult.exports) lintIssues += drifts.length;
-
               const pkgJsonPath = path.resolve(cwd, 'package.json');
               let name = path.basename(cwd);
               try {
                 name = JSON.parse(readFileSync(pkgJsonPath, 'utf-8')).name ?? name;
               } catch {}
-              packages.push({
-                name,
-                coverage,
-                lintIssues,
-                exports: exports.length,
-                documented,
-                undocumented,
-              });
+              packages.push(buildPackageContext(name, spec));
             }
           } else {
-            // Single entry
             const entryFile = path.resolve(cwd, entry);
             const { spec } = await cachedExtract(entryFile);
-            const exports = spec.exports ?? [];
-            let documented = 0;
-            const undocumented: string[] = [];
-            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 = computeDrift(spec);
-            let lintIssues = 0;
-            for (const [, drifts] of driftResult.exports) lintIssues += drifts.length;
-
             const pkgJsonPath = path.resolve(cwd, 'package.json');
             let name = path.basename(cwd);
             try {
               name = JSON.parse(readFileSync(pkgJsonPath, 'utf-8')).name ?? name;
             } catch {}
-            packages.push({
-              name,
-              coverage,
-              lintIssues,
-              exports: exports.length,
-              documented,
-              undocumented,
-            });
+            packages.push(buildPackageContext(name, spec));
           }
 
           const contextData: ContextData = { packages, history, config, commit: commit ?? null };
diff --git a/packages/cli/src/drift.ts b/packages/cli/src/drift.ts
@@ -39,13 +39,14 @@ const program = new Command();
 
 program
   .name('drift')
-  .description('drift — documentation quality primitives for TypeScript')
+  .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) {
@@ -95,20 +96,30 @@ registerContextCommand(program);
 // Cache management
 registerCacheCommand(program);
 
-if (process.argv.includes('--capabilities')) {
+// Hide non-human commands from --help (still functional)
+const HUMAN_COMMANDS = new Set(['scan', 'ci', 'init']);
+for (const cmd of program.commands) {
+  if (!HUMAN_COMMANDS.has(cmd.name())) {
+    (cmd as any)._hidden = true;
+  }
+}
+
+if (process.argv.includes('--tools')) {
   const caps = extractCapabilities(program);
   process.stdout.write(`${JSON.stringify(caps, null, 2)}\n`);
   process.exit(0);
 }
 
-// Smart default: bare `drift` runs init if no config, health otherwise
+// Smart default: bare `drift` runs init if no config, scan otherwise
 // Skip if user passed --help/-h/--version/-V (let commander handle those)
 const rawArgs = process.argv.slice(2);
-const hasHelpOrVersion = rawArgs.some((a) => ['-h', '--help', '-V', '--version'].includes(a));
+const hasHelpOrVersion = rawArgs.some((a) =>
+  ['-h', '--help', '-V', '--version', '--tools'].includes(a),
+);
 const userArgs = rawArgs.filter((a) => !a.startsWith('-'));
 if (userArgs.length === 0 && !hasHelpOrVersion) {
   const { configPath } = loadConfig();
-  const subcommand = configPath ? 'health' : 'init';
+  const subcommand = configPath ? 'scan' : 'init';
   process.argv.splice(2, 0, subcommand);
 }
 
diff --git a/packages/cli/src/utils/capabilities.ts b/packages/cli/src/utils/capabilities.ts
@@ -11,6 +11,7 @@ interface CommandInfo {
   description: string;
   flags: FlagInfo[];
   positional?: string;
+  examples?: string[];
 }
 
 interface EntityInfo {
@@ -21,6 +22,8 @@ interface EntityInfo {
 
 export interface Capabilities {
   version: string;
+  hint: string;
+  humanCommands: string[];
   commands: CommandInfo[];
   globalFlags: FlagInfo[];
   entities: EntityInfo[];
@@ -40,6 +43,30 @@ function extractFlags(cmd: Command): FlagInfo[] {
   }));
 }
 
+const COMMAND_EXAMPLES: Record<string, string[]> = {
+  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'],
+};
+
 export function extractCapabilities(program: Command): Capabilities {
   const commands: CommandInfo[] = [];
 
@@ -52,11 +79,14 @@ export function extractCapabilities(program: Command): Capabilities {
       ...(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: [
diff --git a/packages/cli/src/utils/context-writer.ts b/packages/cli/src/utils/context-writer.ts
@@ -4,13 +4,31 @@ import type { DriftConfig } from '../config/drift-config';
 import { getProjectDir } from '../config/global';
 import type { HistoryEntry } from './history';
 
+export interface PackageIssue {
+  export: string;
+  type: string;
+  issue: string;
+  filePath?: string;
+  line?: number;
+  fixable: boolean;
+}
+
+export interface UndocumentedExport {
+  name: string;
+  kind: string;
+  filePath?: string;
+  line?: number;
+}
+
 export interface PackageContext {
   name: string;
   coverage: number;
   lintIssues: number;
   exports: number;
   documented?: number;
   undocumented?: string[];
+  issues?: PackageIssue[];
+  undocumentedExports?: UndocumentedExport[];
 }
 
 export interface ContextData {
@@ -48,6 +66,39 @@ export function renderContextMarkdown(data: ContextData): string {
     lines.push(`**Average coverage**: ${avgCoverage}%  `);
     lines.push(`**Total lint issues**: ${totalIssues}`);
     lines.push('');
+
+    // Per-package issue details
+    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 | Fixable |');
+        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} | ${issue.fixable ? 'yes' : 'no'} |`,
+          );
+        }
+        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('');
+      }
+    }
   }
 
   // Recent Activity

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@driftdev/cli",`
`3`		`- "version": "0.39.0",`
	`3`	`+ "version": "0.40.0",`
`4`	`4`	`"description": "Drift CLI - Documentation coverage and drift detection for TypeScript",`
`5`	`5`	`"keywords": [`
`6`	`6`	`"typescript",`