ucn 3.8.13 → 3.8.14

package/cli/index.js

@@ -15,7 +15,7 @@ const { ProjectIndex } = require('../core/project');
 const { expandGlob, findProjectRoot } = require('../core/discovery');
 const output = require('../core/output');
 // pickBestDefinition moved to execute.js — no longer needed here
-const { getCliCommandSet, resolveCommand } = require('../core/registry');
+const { getCliCommandSet, resolveCommand, FLAG_APPLICABILITY, toCliName } = require('../core/registry');
 const { execute } = require('../core/execute');
 const { ExpandCache } = require('../core/expand-cache');
 
@@ -115,6 +115,12 @@ function parseFlags(tokens) {
         showConfidence: !tokens.includes('--no-confidence'),
         minConfidence: parseFloat(getValueFlag('--min-confidence') || '0') || 0,
         framework: getValueFlag('--framework'),
+        workers: (() => {
+            const v = getValueFlag('--workers');
+            if (v === null) return undefined;
+            const n = parseInt(v, 10);
+            return isNaN(n) ? undefined : n;
+        })(),
     };
 }
 
@@ -142,7 +148,7 @@ const knownFlags = new Set([
     '--max-lines', '--class-name', '--limit', '--max-files',
     '--type', '--param', '--receiver', '--returns', '--decorator', '--exported', '--unused',
     '--show-confidence', '--no-confidence', '--min-confidence',
-    '--framework'
+    '--framework', '--workers'
 ]);
 
 // Handle help flag
@@ -171,7 +177,8 @@ const VALUE_FLAGS = new Set([
     '--add-param', '--remove-param', '--rename-to', '--default',
     '--base', '--exclude', '--not', '--in', '--max-lines', '--class-name',
     '--type', '--param', '--receiver', '--returns', '--decorator',
-    '--limit', '--max-files', '--min-confidence', '--stack', '--framework'
+    '--limit', '--max-files', '--min-confidence', '--stack', '--framework',
+    '--workers'
 ]);
 
 // Remove flags from args, then add args after -- (which are all positional)
@@ -346,11 +353,9 @@ function runFileCommand(filePath, command, arg) {
             );
             break;
         case 'fn':
-            if (result.notes.length) result.notes.forEach(n => console.error('Note: ' + n));
             printOutput(result, output.formatFnResultJson, output.formatFnResult);
             break;
         case 'class':
-            if (result.notes.length) result.notes.forEach(n => console.error('Note: ' + n));
             printOutput(result, output.formatClassResultJson, output.formatClassResult);
             break;
         case 'lines':
@@ -420,7 +425,7 @@ function runProjectCommand(rootDir, command, arg) {
     // If cache was loaded but stale, force rebuild to avoid duplicates
     let needsCacheSave = false;
     if (!usedCache) {
-        index.build(null, { quiet: flags.quiet, forceRebuild: cacheWasLoaded, followSymlinks: flags.followSymlinks, maxFiles: flags.maxFiles });
+        index.build(null, { quiet: flags.quiet, forceRebuild: cacheWasLoaded, followSymlinks: flags.followSymlinks, maxFiles: flags.maxFiles, workers: flags.workers });
         needsCacheSave = flags.cache;
     }
 
@@ -428,6 +433,23 @@ function runProjectCommand(rootDir, command, arg) {
     // Resolve CLI aliases to canonical command names — dispatch on canonical
     const canonical = resolveCommand(command, 'cli') || command;
 
+    // Warn about flags that don't apply to this command
+    const applicableFlags = FLAG_APPLICABILITY[canonical];
+    if (applicableFlags) {
+        // Map from camelCase flag name to CLI flag string
+        const flagToCli = (f) => '--' + f.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+        // Flags that are global (not command-specific) or have truthy defaults — skip warning for these
+        const globalFlags = new Set(['json', 'quiet', 'cache', 'clearCache', 'followSymlinks', 'maxFiles', 'verbose', 'expand', 'interactive', 'stack', 'showConfidence']);
+        for (const [key, value] of Object.entries(flags)) {
+            if (globalFlags.has(key)) continue;
+            // Skip falsy/default values (0, undefined, false, empty array)
+            if (!value || value === 0 || (Array.isArray(value) && value.length === 0)) continue;
+            if (!applicableFlags.includes(key)) {
+                console.error(`Warning: ${flagToCli(key)} has no effect on '${toCliName(canonical)}'.`);
+            }
+        }
+    }
+
     switch (canonical) {
         // ── Commands using shared executor ───────────────────────────────
 
@@ -475,7 +497,7 @@ function runProjectCommand(rootDir, command, arg) {
         }
 
         case 'context': {
-            const { ok, result: ctx, error } = execute(index, 'context', { name: arg, ...flags });
+            const { ok, result: ctx, error, note } = execute(index, 'context', { name: arg, ...flags });
             if (!ok) fail(error);
             if (flags.json) {
                 console.log(output.formatContextJson(ctx));
@@ -513,6 +535,7 @@ function runProjectCommand(rootDir, command, arg) {
 
                 // Save expandable items to cache for 'expand' command
                 saveExpandableItems(expandable, index.root);
+                if (note) console.error(note);
             }
             break;
         }
@@ -554,16 +577,18 @@ function runProjectCommand(rootDir, command, arg) {
         }
 
         case 'impact': {
-            const { ok, result, error } = execute(index, 'impact', { name: arg, ...flags });
+            const { ok, result, error, note } = execute(index, 'impact', { name: arg, ...flags });
             if (!ok) fail(error);
             printOutput(result, output.formatImpactJson, output.formatImpact);
+            if (note) console.error(note);
             break;
         }
 
         case 'blast': {
-            const { ok, result, error } = execute(index, 'blast', { name: arg, ...flags });
+            const { ok, result, error, note } = execute(index, 'blast', { name: arg, ...flags });
             if (!ok) fail(error);
             printOutput(result, output.formatBlastJson, output.formatBlast);
+            if (note) console.error(note);
             break;
         }
 
@@ -575,16 +600,18 @@ function runProjectCommand(rootDir, command, arg) {
         }
 
         case 'trace': {
-            const { ok, result, error } = execute(index, 'trace', { name: arg, ...flags });
+            const { ok, result, error, note } = execute(index, 'trace', { name: arg, ...flags });
             if (!ok) fail(error);
             printOutput(result, output.formatTraceJson, output.formatTrace);
+            if (note) console.error(note);
             break;
         }
 
         case 'reverseTrace': {
-            const { ok, result, error } = execute(index, 'reverseTrace', { name: arg, ...flags });
+            const { ok, result, error, note } = execute(index, 'reverseTrace', { name: arg, ...flags });
             if (!ok) fail(error);
             printOutput(result, output.formatReverseTraceJson, output.formatReverseTrace);
+            if (note) console.error(note);
             break;
         }
 
@@ -603,9 +630,10 @@ function runProjectCommand(rootDir, command, arg) {
         }
 
         case 'related': {
-            const { ok, result, error } = execute(index, 'related', { name: arg, ...flags });
+            const { ok, result, error, note } = execute(index, 'related', { name: arg, ...flags });
             if (!ok) fail(error);
             printOutput(result, output.formatRelatedJson, r => output.formatRelated(r, { all: flags.all, top: flags.top }));
+            if (note) console.error(note);
             break;
         }
 
@@ -613,18 +641,18 @@ function runProjectCommand(rootDir, command, arg) {
 
         case 'fn': {
             requireArg(arg, 'Usage: ucn . fn <name>');
-            const { ok, result, error } = execute(index, 'fn', { name: arg, file: flags.file, all: flags.all });
+            const { ok, result, error, note } = execute(index, 'fn', { name: arg, file: flags.file, all: flags.all });
             if (!ok) fail(error);
-            if (result.notes.length) result.notes.forEach(n => console.error('Note: ' + n));
+            if (note) console.error(note);
             printOutput(result, output.formatFnResultJson, output.formatFnResult);
             break;
         }
 
         case 'class': {
             requireArg(arg, 'Usage: ucn . class <name>');
-            const { ok, result, error } = execute(index, 'class', { name: arg, file: flags.file, all: flags.all, maxLines: flags.maxLines });
+            const { ok, result, error, note } = execute(index, 'class', { name: arg, file: flags.file, all: flags.all, maxLines: flags.maxLines });
             if (!ok) fail(error);
-            if (result.notes.length) result.notes.forEach(n => console.error('Note: ' + n));
+            if (note) console.error(note);
             printOutput(result, output.formatClassResultJson, output.formatClassResult);
             break;
         }
@@ -640,37 +668,41 @@ function runProjectCommand(rootDir, command, arg) {
         // ── File dependency commands ────────────────────────────────────
 
         case 'imports': {
-            const { ok, result, error } = execute(index, 'imports', { file: arg });
+            const filePath = arg || flags.file;
+            const { ok, result, error } = execute(index, 'imports', { file: filePath });
             if (!ok) fail(error);
             printOutput(result,
-                r => output.formatImportsJson(r, arg),
-                r => output.formatImports(r, arg)
+                r => output.formatImportsJson(r, filePath),
+                r => output.formatImports(r, filePath)
             );
             break;
         }
 
         case 'exporters': {
-            const { ok, result, error } = execute(index, 'exporters', { file: arg });
+            const filePath = arg || flags.file;
+            const { ok, result, error } = execute(index, 'exporters', { file: filePath });
             if (!ok) fail(error);
             printOutput(result,
-                r => output.formatExportersJson(r, arg),
-                r => output.formatExporters(r, arg)
+                r => output.formatExportersJson(r, filePath),
+                r => output.formatExporters(r, filePath)
             );
             break;
         }
 
         case 'fileExports': {
-            const { ok, result, error } = execute(index, 'fileExports', { file: arg });
+            const filePath = arg || flags.file;
+            const { ok, result, error } = execute(index, 'fileExports', { file: filePath });
             if (!ok) fail(error);
             printOutput(result,
-                r => JSON.stringify({ file: arg, exports: r }, null, 2),
-                r => output.formatFileExports(r, arg)
+                r => JSON.stringify({ file: filePath, exports: r }, null, 2),
+                r => output.formatFileExports(r, filePath)
             );
             break;
         }
 
         case 'graph': {
-            const { ok, result, error } = execute(index, 'graph', { file: arg, direction: flags.direction, depth: flags.depth, all: flags.all });
+            const filePath = arg || flags.file;
+            const { ok, result, error } = execute(index, 'graph', { file: filePath, direction: flags.direction, depth: flags.depth, all: flags.all });
             if (!ok) fail(error);
             printOutput(result,
                 r => JSON.stringify({
@@ -678,7 +710,7 @@ function runProjectCommand(rootDir, command, arg) {
                     nodes: r.nodes.map(n => ({ file: n.relativePath, depth: n.depth })),
                     edges: r.edges.map(e => ({ from: path.relative(index.root, e.from), to: path.relative(index.root, e.to) }))
                 }, null, 2),
-                r => output.formatGraph(r, { showAll: flags.all || flags.depth != null, maxDepth: flags.depth != null ? parseInt(flags.depth, 10) : 2, file: arg })
+                r => output.formatGraph(r, { showAll: flags.all || flags.depth != null, maxDepth: flags.depth != null ? parseInt(flags.depth, 10) : 2, file: filePath })
             );
             break;
         }
@@ -713,19 +745,21 @@ function runProjectCommand(rootDir, command, arg) {
         }
 
         case 'affectedTests': {
-            const { ok, result, error } = execute(index, 'affectedTests', { name: arg, ...flags });
+            const { ok, result, error, note } = execute(index, 'affectedTests', { name: arg, ...flags });
             if (!ok) fail(error);
             printOutput(result, output.formatAffectedTestsJson, r => output.formatAffectedTests(r, { all: flags.all }));
+            if (note) console.error(note);
             break;
         }
 
         case 'api': {
-            const { ok, result, error, note } = execute(index, 'api', { file: arg || flags.file, limit: flags.limit });
+            const filePath = arg || flags.file;
+            const { ok, result, error, note } = execute(index, 'api', { file: filePath, limit: flags.limit });
             if (!ok) fail(error);
             if (note) console.error(note);
             printOutput(result,
-                r => output.formatApiJson(r, arg),
-                r => output.formatApi(r, arg)
+                r => output.formatApiJson(r, filePath),
+                r => output.formatApi(r, filePath)
             );
             break;
         }
@@ -864,7 +898,7 @@ function runGlobCommand(pattern, command, arg) {
     }
 
     switch (command) {
-        case 'toc':
+        case 'toc': {
             let totalFunctions = 0;
             let totalClasses = 0;
             let totalState = 0;
@@ -915,6 +949,7 @@ function runGlobCommand(pattern, command, arg) {
                 }));
             }
             break;
+        }
 
         case 'find':
             if (!arg) {
@@ -1113,33 +1148,37 @@ Common Flags:
   --file <pattern>    Filter by file path (e.g., --file=routes)
   --exclude=a,b       Exclude patterns (e.g., --exclude=test,mock)
   --in=<path>         Only in path (e.g., --in=src/core)
-  --depth=N           Trace/graph depth (default: 3, also expands all children)
+  --depth=N           Max depth: blast=3, trace=3, reverse-trace=5, graph=2, affected-tests=3
   --direction=X       Graph direction: imports, importers, or both (default: both)
-  --all               Expand truncated sections (about, trace, graph, related)
-  --top=N             Limit results (find, deadcode)
-  --limit=N           Limit result count (find, usages, search, deadcode, api, toc)
+  --all               Show full results: all callers/callees (about), full tree (trace/blast),
+                        all names (related/find/fn/class/toc), all changed (diff-impact)
+  --top=N             Limit callers/callees (about), similar functions (related), search results
+  --limit=N           Limit result count (find, usages, search, deadcode, api, toc, entrypoints, diff-impact)
   --max-files=N       Max files to index (large projects)
-  --context=N         Lines of context around matches
+  --context=N         Lines of context around matches (search, usages)
   --json              Machine-readable output
-  --code-only         Filter out comments and strings
-  --with-types        Include type definitions
+  --code-only         Filter out comments/strings (search, usages)
+  --with-types        Include type definitions (about, smart)
+  --detailed          Show all symbols in toc (not just counts)
   --include-tests     Include test files
   --class-name=X      Scope to specific class (e.g., --class-name=Repository)
   --include-methods   Include method calls (obj.fn) in caller/callee analysis
   --include-uncertain Include ambiguous/uncertain matches
-  --no-confidence     Hide confidence scores (shown by default)
-  --min-confidence=N  Filter edges below confidence threshold (0.0-1.0)
+  --no-confidence     Hide confidence scores (shown by default in about, context)
+  --min-confidence=N  Filter low-confidence edges (about, context, blast, trace,
+                        reverse-trace, smart, affected-tests)
+  --show-confidence   Show confidence scores on caller/callee edges (about, context)
   --include-exported  Include exported symbols in deadcode
   --no-regex          Force plain text search (regex is default)
   --functions         Show per-function line counts (stats command)
   --include-decorated Include decorated/annotated symbols in deadcode
   --framework=X       Filter entrypoints by framework (e.g., --framework=express,spring)
-  --exact             Exact name match only (find)
+  --exact             Exact name match only (find, typedef)
   --calls-only        Only show call/test-case matches (tests)
   --case-sensitive    Case-sensitive text search (search)
-  --detailed          List all symbols in toc (compact by default)
   --top-level         Show only top-level functions in toc
   --max-lines=N       Max source lines for class (large classes show summary)
+  --workers=N         Parallel build workers (auto-detect; 0 to disable, env: UCN_WORKERS)
   --no-cache          Disable caching
   --clear-cache       Clear cache before running
   --base=<ref>        Git ref for diff-impact (default: HEAD)
@@ -1165,7 +1204,7 @@ function runInteractive(rootDir) {
 
     console.log('Building index...');
     const index = new ProjectIndex(rootDir);
-    index.build(null, { quiet: true });
+    index.build(null, { quiet: true, workers: flags.workers });
     const iExpandCache = new ExpandCache({ maxSize: 20 });
     console.log(`Index ready: ${index.files.size} files, ${index.symbols.size} symbols`);
     console.log('Type commands (e.g., "find parseFile", "about main", "toc")');
@@ -1239,7 +1278,7 @@ Flags can be added per-command: context myFunc --include-methods
 
         if (input === 'rebuild') {
             console.log('Rebuilding index...');
-            index.build(null, { quiet: true, forceRebuild: true });
+            index.build(null, { quiet: true, forceRebuild: true, workers: flags.workers });
             console.log(`Index ready: ${index.files.size} files, ${index.symbols.size} symbols`);
             rl.prompt();
             return;
@@ -1286,25 +1325,89 @@ Flags can be added per-command: context myFunc --include-methods
 
 // parseInteractiveFlags removed — both global and interactive mode now use parseFlags()
 
+// ── Data-driven interactive command dispatch ─────────────────────────────
+//
+// Each entry maps a canonical command name to:
+//   params: (arg, iflags) => execute() params object
+//   format: (result, arg, iflags, index) => formatted string
+//
+// The generic handler calls execute(), checks errors, prints notes, and
+// formats the result. Only commands with truly unique behavior (expand
+// cache save, file writing, conditional formatters) keep explicit cases.
+
+const INTERACTIVE_DISPATCH = {
+    // ── Understanding Code ───────────────────────────────────────────
+    about:        { params: 'name', format: (r, _a, f, idx) => output.formatAbout(r, { expand: f.expand, root: idx.root, showAll: f.all, depth: f.depth, showConfidence: f.showConfidence }) },
+    smart:        { params: 'name', format: (r) => output.formatSmart(r, { uncertainHint: 'use --include-uncertain to include all' }) },
+    impact:       { params: 'name', format: (r) => output.formatImpact(r) },
+    blast:        { params: 'name', format: (r) => output.formatBlast(r) },
+    trace:        { params: 'name', format: (r) => output.formatTrace(r) },
+    reverseTrace: { params: 'name', format: (r) => output.formatReverseTrace(r) },
+    related:      { params: 'name', format: (r, _a, f) => output.formatRelated(r, { all: f.all, top: f.top }) },
+    example:      { params: (a) => ({ name: a }), format: (r, a) => output.formatExample(r, a) },
+
+    // ── Finding Code ─────────────────────────────────────────────────
+    find:          { params: 'name', format: (r, a, f) => output.formatFindDetailed(r, a, { depth: f.depth, top: f.top, all: f.all }) },
+    usages:        { params: 'name', format: (r, a) => output.formatUsages(r, a) },
+    toc:           { params: 'flags', format: (r) => output.formatToc(r, { detailedHint: 'Add --detailed to list all functions, or "about <name>" for full details on a symbol', uncertainHint: 'use --include-uncertain to include all' }) },
+    tests:         { params: 'name', format: (r, a) => output.formatTests(r, a) },
+    affectedTests: { params: 'name', format: (r, _a, f) => output.formatAffectedTests(r, { all: f.all }) },
+    typedef:       { params: 'name', format: (r, a) => output.formatTypedef(r, a) },
+
+    // ── File Dependencies ────────────────────────────────────────────
+    imports:      { params: 'file', format: (r, a, f) => output.formatImports(r, a || f.file) },
+    exporters:    { params: 'file', format: (r, a, f) => output.formatExporters(r, a || f.file) },
+    fileExports:  { params: 'file', format: (r, a, f) => output.formatFileExports(r, a || f.file) },
+    graph:        { params: (a, f) => ({ file: a || f.file, direction: f.direction, depth: f.depth, all: f.all }), format: (r, a, f) => { const d = f.depth ? parseInt(f.depth) : 2; return output.formatGraph(r, { showAll: f.all || !!f.depth, maxDepth: d, file: a || f.file }); } },
+    circularDeps: { params: (a, f) => ({ file: f.file, exclude: f.exclude }), format: (r) => output.formatCircularDeps(r) },
+
+    // ── Refactoring Helpers ──────────────────────────────────────────
+    plan:         { params: 'name', format: (r) => output.formatPlan(r) },
+    verify:       { params: 'name', format: (r) => output.formatVerify(r) },
+    diffImpact:   { params: 'flags', format: (r, _a, f) => output.formatDiffImpact(r, { all: f.all }) },
+    entrypoints:  { params: (a, f) => ({ type: f.type, framework: f.framework, file: f.file, exclude: f.exclude }), format: (r) => output.formatEntrypoints(r) },
+
+    // ── Other ────────────────────────────────────────────────────────
+    api:          { params: (a, f) => ({ file: a || f.file, limit: f.limit }), format: (r, a, f) => output.formatApi(r, a || f.file || '.') },
+    stacktrace:   { params: (a) => ({ stack: a }), format: (r) => output.formatStackTrace(r) },
+    stats:        { params: 'flags', format: (r, _a, f) => output.formatStats(r, { top: f.top }) },
+};
+
+/**
+ * Build execute() params from a dispatch entry's params descriptor.
+ *   'name'  → { name: arg, ...iflags }
+ *   'file'  → { file: arg }
+ *   'flags' → iflags (no arg)
+ *   function → custom builder
+ */
+function buildInteractiveParams(descriptor, arg, iflags) {
+    if (typeof descriptor === 'function') return descriptor(arg, iflags);
+    switch (descriptor) {
+        case 'name':  return { name: arg, ...iflags };
+        case 'file':  return { file: arg || iflags.file };
+        case 'flags': return iflags;
+        default:      return { name: arg, ...iflags };
+    }
+}
+
 function executeInteractiveCommand(index, command, arg, iflags = {}, cache = null) {
+    // ── Commands with unique behavior (not data-driven) ──────────────
     switch (command) {
 
-        // ── Extraction commands (via execute) ────────────────────────────
-
         case 'fn': {
             if (!arg) { console.log('Usage: fn <name>[,name2,...] [--file=<pattern>]'); return; }
-            const { ok, result, error } = execute(index, 'fn', { name: arg, file: iflags.file, all: iflags.all });
+            const { ok, result, error, note } = execute(index, 'fn', { name: arg, file: iflags.file, all: iflags.all });
             if (!ok) { console.log(error); return; }
-            if (result.notes.length) result.notes.forEach(n => console.log('Note: ' + n));
+            if (note) console.log(note);
             console.log(output.formatFnResult(result));
             break;
         }
 
         case 'class': {
             if (!arg) { console.log('Usage: class <name> [--file=<pattern>]'); return; }
-            const { ok, result, error } = execute(index, 'class', { name: arg, file: iflags.file, all: iflags.all, maxLines: iflags.maxLines });
+            const { ok, result, error, note } = execute(index, 'class', { name: arg, file: iflags.file, all: iflags.all, maxLines: iflags.maxLines });
             if (!ok) { console.log(error); return; }
-            if (result.notes.length) result.notes.forEach(n => console.log('Note: ' + n));
+            if (note) console.log(note);
             console.log(output.formatClassResult(result));
             break;
         }
@@ -1347,16 +1450,6 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
             break;
         }
 
-        case 'find': {
-            const { ok, result, error, note } = execute(index, 'find', { name: arg, ...iflags });
-            if (!ok) { console.log(error); return; }
-            if (note) console.log(note);
-            console.log(output.formatFindDetailed(result, arg, { depth: iflags.depth, top: iflags.top, all: iflags.all }));
-            break;
-        }
-
-        // ── context: needs expandable items cache ────────────────────────
-
         case 'context': {
             const { ok, result, error } = execute(index, 'context', { name: arg, ...iflags });
             if (!ok) { console.log(error); return; }
@@ -1375,8 +1468,6 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
             break;
         }
 
-        // ── deadcode: needs result fields for hint construction ──────────
-
         case 'deadcode': {
             const { ok, result, error } = execute(index, 'deadcode', iflags);
             if (!ok) { console.log(error); return; }
@@ -1388,126 +1479,6 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
             break;
         }
 
-        case 'entrypoints': {
-            const { ok, result, error } = execute(index, 'entrypoints', { type: iflags.type, framework: iflags.framework, file: iflags.file, exclude: iflags.exclude });
-            if (!ok) { console.log(error); return; }
-            console.log(output.formatEntrypoints(result));
-            break;
-        }
-
-        // ── Standard commands routed through execute() ───────────────────
-
-        case 'toc': {
-            const { ok, result, error } = execute(index, 'toc', iflags);
-            if (!ok) { console.log(error); return; }
-            console.log(output.formatToc(result, {
-                detailedHint: 'Add --detailed to list all functions, or "about <name>" for full details on a symbol',
-                uncertainHint: 'use --include-uncertain to include all'
-            }));
-            break;
-        }
-
-        case 'about': {
-            const { ok, result, error } = execute(index, 'about', { name: arg, ...iflags });
-            if (!ok) { console.log(error); return; }
-            console.log(output.formatAbout(result, { expand: iflags.expand, root: index.root, showAll: iflags.all, depth: iflags.depth, showConfidence: iflags.showConfidence }));
-            break;
-        }
-
-        case 'usages': {
-            const { ok, result, error } = execute(index, 'usages', { name: arg, ...iflags });
-            if (!ok) { console.log(error); return; }
-            console.log(output.formatUsages(result, arg));
-            break;
-        }
-
-        case 'smart': {
-            const { ok, result, error } = execute(index, 'smart', { name: arg, ...iflags });
-            if (!ok) { console.log(error); return; }
-            console.log(output.formatSmart(result, {
-                uncertainHint: 'use --include-uncertain to include all'
-            }));
-            break;
-        }
-
-        case 'impact': {
-            const { ok, result, error } = execute(index, 'impact', { name: arg, ...iflags });
-            if (!ok) { console.log(error); return; }
-            console.log(output.formatImpact(result));
-            break;
-        }
-
-        case 'blast': {
-            const { ok, result, error } = execute(index, 'blast', { name: arg, ...iflags });
-            if (!ok) { console.log(error); return; }
-            console.log(output.formatBlast(result));
-            break;
-        }
-
-        case 'trace': {
-            const { ok, result, error } = execute(index, 'trace', { name: arg, ...iflags });
-            if (!ok) { console.log(error); return; }
-            console.log(output.formatTrace(result));
-            break;
-        }
-
-        case 'reverseTrace': {
-            const { ok, result, error } = execute(index, 'reverseTrace', { name: arg, ...iflags });
-            if (!ok) { console.log(error); return; }
-            console.log(output.formatReverseTrace(result));
-            break;
-        }
-
-        case 'graph': {
-            const { ok, result, error } = execute(index, 'graph', { file: arg || iflags.file, direction: iflags.direction, depth: iflags.depth, all: iflags.all });
-            if (!ok) { console.log(error); return; }
-            const graphDepth = iflags.depth ? parseInt(iflags.depth) : 2;
-            console.log(output.formatGraph(result, { showAll: iflags.all || !!iflags.depth, maxDepth: graphDepth, file: arg }));
-            break;
-        }
-
-        case 'circularDeps': {
-            const { ok, result, error } = execute(index, 'circularDeps', { file: iflags.file, exclude: iflags.exclude });
-            if (!ok) { console.log(error); return; }
-            console.log(output.formatCircularDeps(result));
-            break;
-        }
-
-        case 'fileExports': {
-            const { ok, result, error } = execute(index, 'fileExports', { file: arg });
-            if (!ok) { console.log(error); return; }
-            console.log(output.formatFileExports(result, arg));
-            break;
-        }
-
-        case 'imports': {
-            const { ok, result, error } = execute(index, 'imports', { file: arg });
-            if (!ok) { console.log(error); return; }
-            console.log(output.formatImports(result, arg));
-            break;
-        }
-
-        case 'exporters': {
-            const { ok, result, error } = execute(index, 'exporters', { file: arg });
-            if (!ok) { console.log(error); return; }
-            console.log(output.formatExporters(result, arg));
-            break;
-        }
-
-        case 'tests': {
-            const { ok, result, error } = execute(index, 'tests', { name: arg, ...iflags });
-            if (!ok) { console.log(error); return; }
-            console.log(output.formatTests(result, arg));
-            break;
-        }
-
-        case 'affectedTests': {
-            const { ok, result, error } = execute(index, 'affectedTests', { name: arg, ...iflags });
-            if (!ok) { console.log(error); return; }
-            console.log(output.formatAffectedTests(result, { all: iflags.all }));
-            break;
-        }
-
         case 'search': {
             const { ok, result, error, structural } = execute(index, 'search', { term: arg, ...iflags });
             if (!ok) { console.log(error); return; }
@@ -1519,71 +1490,19 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
             break;
         }
 
-        case 'typedef': {
-            const { ok, result, error } = execute(index, 'typedef', { name: arg, ...iflags });
-            if (!ok) { console.log(error); return; }
-            console.log(output.formatTypedef(result, arg));
-            break;
-        }
-
-        case 'api': {
-            const { ok, result, error } = execute(index, 'api', { file: arg });
-            if (!ok) { console.log(error); return; }
-            console.log(output.formatApi(result, arg || '.'));
-            break;
-        }
-
-        case 'diffImpact': {
-            const { ok, result, error } = execute(index, 'diffImpact', iflags);
-            if (!ok) { console.log(error); return; }
-            console.log(output.formatDiffImpact(result, { all: iflags.all }));
-            break;
-        }
-
-        case 'stats': {
-            const { ok, result, error } = execute(index, 'stats', iflags);
-            if (!ok) { console.log(error); return; }
-            console.log(output.formatStats(result, { top: iflags.top }));
-            break;
-        }
-
-        case 'related': {
-            const { ok, result, error } = execute(index, 'related', { name: arg, ...iflags });
-            if (!ok) { console.log(error); return; }
-            console.log(output.formatRelated(result, { all: iflags.all, top: iflags.top }));
-            break;
-        }
-
-        case 'example': {
-            const { ok, result, error } = execute(index, 'example', { name: arg });
-            if (!ok) { console.log(error); return; }
-            console.log(output.formatExample(result, arg));
-            break;
-        }
-
-        case 'plan': {
-            const { ok, result, error } = execute(index, 'plan', { name: arg, ...iflags });
-            if (!ok) { console.log(error); return; }
-            console.log(output.formatPlan(result));
-            break;
-        }
-
-        case 'verify': {
-            const { ok, result, error } = execute(index, 'verify', { name: arg, ...iflags });
-            if (!ok) { console.log(error); return; }
-            console.log(output.formatVerify(result));
-            break;
-        }
-
-        case 'stacktrace': {
-            const { ok, result, error } = execute(index, 'stacktrace', { stack: arg });
+        default: {
+            // ── Data-driven dispatch for standard commands ────────────
+            const entry = INTERACTIVE_DISPATCH[command];
+            if (!entry) {
+                console.log(`Unknown command: ${command}. Type "help" for available commands.`);
+                return;
+            }
+            const params = buildInteractiveParams(entry.params, arg, iflags);
+            const { ok, result, error, note } = execute(index, command, params);
             if (!ok) { console.log(error); return; }
-            console.log(output.formatStackTrace(result));
-            break;
+            if (note) console.log(note);
+            console.log(entry.format(result, arg, iflags, index));
         }
-
-        default:
-            console.log(`Unknown command: ${command}. Type "help" for available commands.`);
     }
 }