ucn 3.8.18 → 3.8.20

package/.claude/skills/ucn/SKILL.md

@@ -133,7 +133,7 @@ ucn entrypoints --file=routes/           # Scoped to files
 | File-level dependency tree | `ucn graph <file> --depth=1` | Visual import tree. Setting `--depth=N` expands all children. Can be noisy — use depth=1 for large projects. For function-level flow, use `trace` instead |
 | Are there circular dependencies? | `ucn circular-deps` | Detect circular import chains. `--file=<pattern>` filters to cycles involving a file. `--exclude=test` skips test files |
 | What are the framework entry points? | `ucn entrypoints` | Lists all detected routes, DI beans, tasks, etc. Filter: `--type=http`, `--framework=express` |
-| Find which tests cover a function | `ucn tests <name>` | Test files and test function names |
+| Find which tests cover a function | `ucn tests <name>` | Test files and test function names. Scope with `--file`, `--class-name`, `--exclude`, `--calls-only` |
 | Extract specific lines from a file | `ucn lines --file=<file> --range=10-20` | Pull a line range without reading the whole file |
 | Find type definitions | `ucn typedef <name>` | Interfaces, enums, structs, traits, type aliases |
 | See a project's public API | `ucn api` or `ucn api --file=<file>` | All exported/public symbols with signatures |
@@ -163,7 +163,7 @@ ucn [target] <command> [name] [--flags]
 | `--in=src/core` | Limit search to a subdirectory |
 | `--depth=N` | Control tree depth for `trace`, `graph`, and detail level for `find` (default 3). Also expands all children — no breadth limit |
 | `--all` | Expand truncated sections in `about`, `trace`, `graph`, `related` |
-| `--include-tests` | Include test files in results (excluded by default) |
+| `--include-tests` | Include test files in usage counts (`about`) and results (`find`, `usages`, `deadcode`). Callers always include tests. |
 | `--include-methods` | Include `obj.method()` calls in `context`/`smart` (only direct calls shown by default) |
 | `--base=<ref>` | Git ref for diff-impact (default: HEAD) |
 | `--staged` | Analyze staged changes (diff-impact) |

package/cli/index.js

@@ -74,19 +74,19 @@ function parseFlags(tokens) {
         exclude: parseExclude(),
         in: getValueFlag('--in'),
         includeTests: tokens.includes('--include-tests') ? true : undefined,
-        includeExported: tokens.includes('--include-exported'),
-        includeDecorated: tokens.includes('--include-decorated'),
-        includeUncertain: tokens.includes('--include-uncertain'),
+        includeExported: tokens.includes('--include-exported') || undefined,
+        includeDecorated: tokens.includes('--include-decorated') || undefined,
+        includeUncertain: tokens.includes('--include-uncertain') || undefined,
         includeMethods: tokens.some(a => a === '--include-methods=false') ? false : tokens.some(a => a === '--include-methods' || (a.startsWith('--include-methods=') && a !== '--include-methods=false')) ? true : undefined,
-        detailed: tokens.includes('--detailed'),
-        topLevel: tokens.includes('--top-level'),
-        all: tokens.includes('--all'),
-        exact: tokens.includes('--exact'),
-        callsOnly: tokens.includes('--calls-only'),
-        codeOnly: tokens.includes('--code-only'),
-        caseSensitive: tokens.includes('--case-sensitive'),
-        withTypes: tokens.includes('--with-types'),
-        expand: tokens.includes('--expand'),
+        detailed: tokens.includes('--detailed') || undefined,
+        topLevel: tokens.includes('--top-level') || undefined,
+        all: tokens.includes('--all') || undefined,
+        exact: tokens.includes('--exact') || undefined,
+        callsOnly: tokens.includes('--calls-only') || undefined,
+        codeOnly: tokens.includes('--code-only') || undefined,
+        caseSensitive: tokens.includes('--case-sensitive') || undefined,
+        withTypes: tokens.includes('--with-types') || undefined,
+        expand: tokens.includes('--expand') || undefined,
         depth: getValueFlag('--depth'),
         top: parseInt(getValueFlag('--top') || '0'),
         context: parseInt(getValueFlag('--context') || '0'),
@@ -96,10 +96,10 @@ function parseFlags(tokens) {
         renameTo: getValueFlag('--rename-to'),
         defaultValue: getValueFlag('--default'),
         base: getValueFlag('--base'),
-        staged: tokens.includes('--staged'),
+        staged: tokens.includes('--staged') || undefined,
         maxLines: getValueFlag('--max-lines') || null,
         regex: tokens.includes('--no-regex') ? false : undefined,
-        functions: tokens.includes('--functions'),
+        functions: tokens.includes('--functions') || undefined,
         className: getValueFlag('--class-name'),
         limit: parseInt(getValueFlag('--limit') || '0') || undefined,
         maxFiles: parseInt(getValueFlag('--max-files') || '0') || undefined,
@@ -109,9 +109,9 @@ function parseFlags(tokens) {
         receiver: getValueFlag('--receiver'),
         returns: getValueFlag('--returns'),
         decorator: getValueFlag('--decorator'),
-        exported: tokens.includes('--exported'),
-        unused: tokens.includes('--unused'),
-        showConfidence: !tokens.includes('--no-confidence'),
+        exported: tokens.includes('--exported') || undefined,
+        unused: tokens.includes('--unused') || undefined,
+        showConfidence: tokens.includes('--no-confidence') ? false : undefined,
         minConfidence: parseFloat(getValueFlag('--min-confidence') || '0') || 0,
         framework: getValueFlag('--framework'),
         stack: getValueFlag('--stack'),
@@ -227,6 +227,33 @@ function printOutput(result, jsonFn, textFn) {
     }
 }
 
+/**
+ * Print inline 3-line code previews for each callee (--expand support).
+ * Used by context in project, interactive, and glob modes.
+ */
+function printInlineExpand(ctx, root) {
+    if (!root || !ctx || !ctx.callees) return;
+    for (const c of ctx.callees) {
+        if (c.relativePath && c.startLine) {
+            try {
+                const filePath = path.join(root, c.relativePath);
+                const content = fs.readFileSync(filePath, 'utf-8');
+                const codeLines = content.split('\n');
+                const endLine = c.endLine || c.startLine + 5;
+                const previewLines = Math.min(3, endLine - c.startLine + 1);
+                for (let i = 0; i < previewLines && c.startLine - 1 + i < codeLines.length; i++) {
+                    console.log(`      │ ${codeLines[c.startLine - 1 + i]}`);
+                }
+                if (endLine - c.startLine + 1 > 3) {
+                    console.log(`      │ ... (${endLine - c.startLine - 2} more lines)`);
+                }
+            } catch (e) {
+                // Skip on error
+            }
+        }
+    }
+}
+
 // ============================================================================
 // MAIN
 // ============================================================================
@@ -304,6 +331,12 @@ function runFileCommand(filePath, command, arg) {
         if (['imports', 'exporters', 'fileExports', 'graph'].includes(canonical) && !arg) {
             effectiveArg = filePath;
         }
+        // Scope to the target file unless an explicit --file was provided
+        if (!flags.file) {
+            const relPath = path.relative(projectRoot, path.resolve(filePath));
+            flags.file = relPath;
+            flags._fileFromFileMode = true; // suppress inapplicable-flag warning
+        }
         runProjectCommand(projectRoot, command, effectiveArg);
         return;
     }
@@ -374,9 +407,11 @@ function runFileCommand(filePath, command, arg) {
         case 'typedef':
             printOutput(result, r => output.formatTypedefJson(r, arg), r => output.formatTypedef(r, arg));
             break;
-        case 'api':
-            printOutput(result, r => output.formatApiJson(r, arg), r => output.formatApi(r, arg));
+        case 'api': {
+            const apiFile = relativePath;
+            printOutput(result, r => output.formatApiJson(r, apiFile), r => output.formatApi(r, apiFile));
             break;
+        }
     }
 }
 
@@ -443,12 +478,14 @@ function runProjectCommand(rootDir, command, arg) {
     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', 'showConfidence']);
+        // Flags that are global (not command-specific) — skip warning for these
+        const globalFlags = new Set(['json', 'quiet', 'cache', 'clearCache', 'followSymlinks', 'maxFiles', 'verbose', 'expand', 'interactive', '_fileFromFileMode']);
         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;
+            // Skip unset values (undefined, null, 0, empty array) — but NOT false (explicit negation)
+            if (value === undefined || value === null || value === 0 || (Array.isArray(value) && value.length === 0)) continue;
+            // Skip --file when it was injected by file-mode routing, not user input
+            if (key === 'file' && flags._fileFromFileMode) continue;
             if (!applicableFlags.includes(key)) {
                 console.error(`Warning: ${flagToCli(key)} has no effect on '${toCliName(canonical)}'.`);
             }
@@ -509,33 +546,15 @@ function runProjectCommand(rootDir, command, arg) {
             } else {
                 const { text, expandable } = output.formatContext(ctx, {
                     methodsHint: 'Note: obj.method() calls excluded — use --include-methods to include them',
-                    expandHint: 'Use "ucn . expand <N>" to see code for item N',
+                    expandHint: 'Use "expand <N>" or --expand to see code for items',
                     uncertainHint: 'use --include-uncertain to include all',
-                    showConfidence: flags.showConfidence,
+                    showConfidence: flags.showConfidence !== false,
                 });
                 console.log(text);
 
                 // Inline expansion of callees when --expand flag is set
-                if (flags.expand && index.root && ctx.callees) {
-                    for (const c of ctx.callees) {
-                        if (c.relativePath && c.startLine) {
-                            try {
-                                const filePath = path.join(index.root, c.relativePath);
-                                const content = fs.readFileSync(filePath, 'utf-8');
-                                const codeLines = content.split('\n');
-                                const endLine = c.endLine || c.startLine + 5;
-                                const previewLines = Math.min(3, endLine - c.startLine + 1);
-                                for (let i = 0; i < previewLines && c.startLine - 1 + i < codeLines.length; i++) {
-                                    console.log(`      │ ${codeLines[c.startLine - 1 + i]}`);
-                                }
-                                if (endLine - c.startLine + 1 > 3) {
-                                    console.log(`      │ ... (${endLine - c.startLine - 2} more lines)`);
-                                }
-                            } catch (e) {
-                                // Skip on error
-                            }
-                        }
-                    }
+                if (flags.expand) {
+                    printInlineExpand(ctx, index.root);
                 }
 
                 // Save expandable items to cache for 'expand' command
@@ -577,7 +596,7 @@ function runProjectCommand(rootDir, command, arg) {
             if (!ok) fail(error);
             printOutput(result,
                 output.formatAboutJson,
-                r => output.formatAbout(r, { expand: flags.expand, root: index.root, depth: flags.depth, showConfidence: flags.showConfidence })
+                r => output.formatAbout(r, { expand: flags.expand, root: index.root, depth: flags.depth, showConfidence: flags.showConfidence !== false })
             );
             if (note) console.error(note);
             break;
@@ -739,7 +758,7 @@ function runProjectCommand(rootDir, command, arg) {
         }
 
         case 'tests': {
-            const { ok, result, error } = execute(index, 'tests', { name: arg, callsOnly: flags.callsOnly, className: flags.className });
+            const { ok, result, error } = execute(index, 'tests', { name: arg, callsOnly: flags.callsOnly, className: flags.className, file: flags.file, exclude: flags.exclude });
             if (!ok) fail(error);
             printOutput(result,
                 r => output.formatTestsJson(r, arg),
@@ -912,31 +931,60 @@ function runGlobCommand(pattern, command, arg) {
     const index = new ProjectIndex(rootDir);
     index.build(files, { quiet: true });
 
-    // Supported commands — anything that works with an index
-    const supportedGlobCommands = new Set(['toc', 'find', 'search', 'fn', 'class', 'usages', 'deadcode', 'typedef', 'stats']);
-    if (!supportedGlobCommands.has(canonical)) {
-        console.error(`Command "${command}" not supported in glob mode. Supported: ${[...supportedGlobCommands].join(', ')}`);
+    // Supported commands — anything that works with an index.
+    // All execute() commands are supported; only expand (requires cached state)
+    // and interactive-only commands are excluded.
+    const unsupportedGlobCommands = new Set(['expand']);
+    if (unsupportedGlobCommands.has(canonical)) {
+        console.error(`Command "${command}" not supported in glob mode.`);
         process.exit(1);
     }
 
     // Build params — same as project mode
     const params = {};
-    if (['find', 'usages', 'fn', 'class', 'typedef'].includes(canonical)) {
+    const needsName = new Set(['find', 'usages', 'fn', 'class', 'typedef', 'about', 'context',
+        'smart', 'impact', 'trace', 'blast', 'reverseTrace', 'tests', 'affectedTests',
+        'example', 'verify', 'plan', 'related']);
+    if (needsName.has(canonical)) {
         if (!arg) {
             console.error(`Usage: ucn "pattern" ${command} <name>`);
             process.exit(1);
         }
         params.name = arg;
     }
-    if (canonical === 'search') {
+    if (canonical === 'search' || canonical === 'structuralSearch') {
         if (!arg && !flags.type) {
             console.error('Usage: ucn "pattern" search <term>');
             process.exit(1);
         }
         params.term = arg;
     }
+    // Merge flags first, then set positional overrides so they aren't wiped
     Object.assign(params, flags);
 
+    // Warn about inapplicable flags (same check as project/interactive mode)
+    const applicableFlags = FLAG_APPLICABILITY[canonical];
+    if (applicableFlags) {
+        const flagToCli = (f) => '--' + f.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+        const globalFlags = new Set(['json', 'quiet', 'cache', 'clearCache', 'followSymlinks', 'maxFiles', 'verbose', 'expand', 'interactive', '_fileFromFileMode']);
+        for (const [key, value] of Object.entries(flags)) {
+            if (globalFlags.has(key)) continue;
+            if (value === undefined || value === null || value === 0 || (Array.isArray(value) && value.length === 0)) continue;
+            if (!applicableFlags.includes(key)) {
+                console.error(`Warning: ${flagToCli(key)} has no effect on '${toCliName(canonical)}'.`);
+            }
+        }
+    }
+    if (canonical === 'stacktrace' && arg) {
+        params.stack = arg;
+    }
+    if (canonical === 'lines' && arg) {
+        params.range = arg;
+    }
+    if (['imports', 'exporters', 'fileExports', 'graph', 'api'].includes(canonical)) {
+        if (arg) params.file = arg;
+    }
+
     const { ok, result, error, note, structural } = execute(index, canonical, params);
     if (!ok) fail(error);
     if (note) console.error(note);
@@ -982,6 +1030,109 @@ function runGlobCommand(pattern, command, arg) {
         case 'stats':
             printOutput(result, output.formatStatsJson, r => output.formatStats(r, { top: flags.top }));
             break;
+        case 'about':
+            printOutput(result, output.formatAboutJson,
+                r => output.formatAbout(r, { expand: flags.expand, root: index.root, depth: flags.depth, showConfidence: flags.showConfidence !== false }));
+            break;
+        case 'context':
+            if (flags.json) {
+                console.log(output.formatContextJson(result));
+            } else {
+                const { text } = output.formatContext(result, {
+                    methodsHint: 'Note: obj.method() calls excluded — use --include-methods to include them',
+                    uncertainHint: 'use --include-uncertain to include all',
+                    expandHint: 'Use --expand to see inline callee previews',
+                    showConfidence: flags.showConfidence !== false,
+                });
+                console.log(text);
+                if (flags.expand) {
+                    printInlineExpand(result, index.root);
+                }
+            }
+            break;
+        case 'smart':
+            printOutput(result, output.formatSmartJson, output.formatSmart);
+            break;
+        case 'impact':
+            printOutput(result, output.formatImpactJson, output.formatImpact);
+            break;
+        case 'related':
+            printOutput(result, output.formatRelatedJson,
+                r => output.formatRelated(r, { all: flags.all, top: flags.top }));
+            break;
+        case 'trace':
+            printOutput(result, output.formatTraceJson, output.formatTrace);
+            break;
+        case 'blast':
+            printOutput(result, output.formatBlastJson, output.formatBlast);
+            break;
+        case 'reverseTrace':
+            printOutput(result, output.formatReverseTraceJson, output.formatReverseTrace);
+            break;
+        case 'tests':
+            printOutput(result, r => output.formatTestsJson(r, arg), r => output.formatTests(r, arg));
+            break;
+        case 'affectedTests':
+            printOutput(result, output.formatAffectedTestsJson,
+                r => output.formatAffectedTests(r, { all: flags.all }));
+            break;
+        case 'example':
+            printOutput(result, r => output.formatExampleJson(r, arg), r => output.formatExample(r, arg));
+            break;
+        case 'verify':
+            printOutput(result, output.formatVerifyJson, output.formatVerify);
+            break;
+        case 'plan':
+            printOutput(result, output.formatPlanJson, output.formatPlan);
+            break;
+        case 'imports': {
+            const filePath = params.file;
+            printOutput(result, r => output.formatImportsJson(r, filePath), r => output.formatImports(r, filePath));
+            break;
+        }
+        case 'exporters': {
+            const filePath = params.file;
+            printOutput(result, r => output.formatExportersJson(r, filePath), r => output.formatExporters(r, filePath));
+            break;
+        }
+        case 'fileExports': {
+            const filePath = params.file;
+            printOutput(result, r => output.formatFileExportsJson(r, filePath), r => output.formatFileExports(r, filePath));
+            break;
+        }
+        case 'api': {
+            const filePath = params.file;
+            printOutput(result, r => output.formatApiJson(r, filePath), r => output.formatApi(r, filePath));
+            break;
+        }
+        case 'graph':
+            printOutput(result, output.formatGraphJson,
+                r => output.formatGraph(r, { showAll: flags.all || flags.depth != null, maxDepth: flags.depth }));
+            break;
+        case 'circularDeps':
+            printOutput(result, output.formatCircularDepsJson, output.formatCircularDeps);
+            break;
+        case 'entrypoints':
+            printOutput(result, output.formatEntrypointsJson, output.formatEntrypoints);
+            break;
+        case 'diffImpact':
+            printOutput(result, output.formatDiffImpactJson, output.formatDiffImpact);
+            break;
+        case 'stacktrace':
+            printOutput(result, output.formatStackTraceJson, output.formatStackTrace);
+            break;
+        case 'lines':
+            printOutput(result, output.formatLinesJson, output.formatLines);
+            break;
+        default: {
+            // Fallback: output JSON for any command without a dedicated formatter
+            if (flags.json) {
+                console.log(JSON.stringify({ meta: {}, data: result }, null, 2));
+            } else {
+                console.log(JSON.stringify(result, null, 2));
+            }
+            break;
+        }
     }
 }
 
@@ -1023,7 +1174,7 @@ FIND CODE
   toc                 Table of contents (compact; --detailed lists all symbols)
   search <term>       Text search (regex default, --context=N, --exclude=, --in=)
                       Structural: --type=function|class|call --param= --returns= --decorator= --exported --unused
-  tests <name>        Find test files for a function
+  tests <name>        Find test files for a function (--file, --class-name, --exclude, --calls-only)
   affected-tests <n>  Tests affected by a change (blast + test detection, --depth=N)
 
 ═══════════════════════════════════════════════════════════════════════════════
@@ -1076,7 +1227,7 @@ Common Flags:
   --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
+  --include-tests     Include test files in usage counts (about) and results (find, usages, deadcode)
   --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
@@ -1171,7 +1322,7 @@ Commands:
   file-exports <file>    File's exported symbols
   imports <file>         What file imports
   exporters <file>       Who imports file
-  tests <name>           Find tests (--calls-only)
+  tests <name>           Find tests (--file, --class-name, --exclude, --calls-only)
   affected-tests <n>     Tests affected by a change (--depth=N)
   search <term>          Text search (--context=N, --exclude=, --in=)
                          Structural: --type= --param= --returns= --decorator= --exported --unused
@@ -1255,7 +1406,7 @@ Flags can be added per-command: context myFunc --include-methods
 
 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 }) },
+    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 !== false }) },
     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) },
@@ -1309,6 +1460,20 @@ function buildInteractiveParams(descriptor, arg, iflags) {
 }
 
 function executeInteractiveCommand(index, command, arg, iflags = {}, cache = null) {
+    // Warn about inapplicable flags (same check as project mode)
+    const applicableFlags = FLAG_APPLICABILITY[command];
+    if (applicableFlags) {
+        const flagToCli = (f) => '--' + f.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+        const globalFlags = new Set(['json', 'quiet', 'cache', 'clearCache', 'followSymlinks', 'maxFiles', 'verbose', 'expand', 'interactive', '_fileFromFileMode']);
+        for (const [key, value] of Object.entries(iflags)) {
+            if (globalFlags.has(key)) continue;
+            if (value === undefined || value === null || value === 0 || (Array.isArray(value) && value.length === 0)) continue;
+            if (!applicableFlags.includes(key)) {
+                console.log(`Warning: ${flagToCli(key)} has no effect on '${command}'.`);
+            }
+        }
+    }
+
     // ── Commands with unique behavior (not data-driven) ──────────────
     switch (command) {
 
@@ -1375,9 +1540,12 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
                 methodsHint: 'Note: obj.method() calls excluded — use --include-methods to include them',
                 expandHint: 'Use "expand <N>" to see code for item N',
                 uncertainHint: 'use --include-uncertain to include all',
-                showConfidence: iflags.showConfidence,
+                showConfidence: iflags.showConfidence !== false,
             });
             console.log(text);
+            if (iflags.expand) {
+                printInlineExpand(result, index.root);
+            }
             if (note) console.log(note);
             if (cache) {
                 cache.save(index.root, arg, iflags.file, expandable);

package/core/analysis.js

@@ -836,8 +836,12 @@ function about(index, name, options = {}) {
         }));
     }
 
-    // Find tests
-    const tests = index.tests(symbolName);
+    // Find tests — scope to the same file/class as the primary definition
+    const tests = index.tests(symbolName, {
+        file: options.file,
+        className: options.className || primary.className,
+        exclude: options.exclude,
+    });
     const testSummary = {
         fileCount: tests.length,
         totalMatches: tests.reduce((sum, t) => sum + t.matches.length, 0),

package/core/execute.js

@@ -96,6 +96,7 @@ function buildCallerOptions(p) {
         className: p.className,
         includeMethods: p.includeMethods,
         includeUncertain: p.includeUncertain || false,
+        includeTests: p.includeTests,
         exclude: toExcludeArray(p.exclude),
         minConfidence: num(p.minConfidence, 0),
     };
@@ -592,11 +593,27 @@ const HANDLERS = {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
         applyClassMethodSyntax(p);
+        if (p.file) {
+            const fileErr = checkFilePatternMatch(index, p.file);
+            if (fileErr) return { ok: false, error: fileErr };
+            // Validate that the symbol exists in the target file
+            const defs = index.find(p.name, { exact: true, file: p.file, className: p.className });
+            if (defs.length === 0) {
+                const allDefs = index.find(p.name, { exact: true });
+                if (allDefs.length > 0) {
+                    const files = allDefs.map(d => d.relativePath).join(', ');
+                    return { ok: false, error: `Symbol "${p.name}" not found in files matching "${p.file}". Defined in: ${files}` };
+                }
+                return { ok: false, error: `Symbol "${p.name}" not found.` };
+            }
+        }
         const classErr = validateClassName(index, p.name, p.className);
         if (classErr) return { ok: false, error: classErr };
         const result = index.tests(p.name, {
             callsOnly: p.callsOnly || false,
             className: p.className,
+            file: p.file,
+            exclude: toExcludeArray(p.exclude),
         });
         return { ok: true, result };
     },

package/core/output/analysis.js

@@ -80,7 +80,7 @@ function formatContextJson(context) {
 function formatContext(ctx, options = {}) {
     if (!ctx) return { text: 'Symbol not found.', expandable: [] };
 
-    const expandHint = options.expandHint || 'Use ucn_expand with item number to see code for any item.';
+    const expandHint = options.expandHint != null ? options.expandHint : 'Use ucn_expand with item number to see code for any item.';
     const methodsHint = options.methodsHint || 'Note: obj.method() calls excluded. Use include_methods=true to include them.';
 
     const lines = [];

package/core/registry.js

@@ -92,45 +92,45 @@ const PARAM_MAP = {
 // ============================================================================
 
 // Per-command list of accepted flag names (camelCase). Source of truth for help text,
-// MCP schema validation, and architecture guards.
+// MCP param stripping, CLI inapplicable-flag warnings, and architecture guards.
 // file* = file is the command subject (required), not a filter pattern.
 const FLAG_APPLICABILITY = {
     // Understanding code
-    about:        ['file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'top', 'all', 'withTypes', 'minConfidence', 'showConfidence'],
-    context:      ['file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'minConfidence', 'showConfidence'],
-    impact:       ['file', 'exclude', 'className', 'top'],
-    blast:        ['file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'depth', 'all', 'minConfidence'],
-    reverseTrace: ['file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'depth', 'all', 'minConfidence'],
-    smart:        ['file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'withTypes', 'minConfidence'],
-    trace:        ['file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'depth', 'all', 'minConfidence'],
-    example:      ['file', 'className'],
-    related:      ['file', 'className', 'top', 'all'],
+    about:        ['name', 'file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'includeTests', 'top', 'all', 'withTypes', 'minConfidence', 'showConfidence'],
+    context:      ['name', 'file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'minConfidence', 'showConfidence'],
+    impact:       ['name', 'file', 'exclude', 'className', 'top'],
+    blast:        ['name', 'file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'depth', 'all', 'minConfidence'],
+    reverseTrace: ['name', 'file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'depth', 'all', 'minConfidence'],
+    smart:        ['name', 'file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'withTypes', 'minConfidence'],
+    trace:        ['name', 'file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'depth', 'all', 'minConfidence'],
+    example:      ['name', 'file', 'className'],
+    related:      ['name', 'file', 'className', 'top', 'all'],
     // Finding code
-    find:         ['file', 'exclude', 'className', 'includeTests', 'top', 'limit', 'exact', 'in', 'all', 'depth'],
-    usages:       ['file', 'exclude', 'className', 'includeTests', 'limit', 'codeOnly', 'context', 'in'],
+    find:         ['name', 'file', 'exclude', 'className', 'includeTests', 'top', 'limit', 'exact', 'in', 'all', 'depth'],
+    usages:       ['name', 'file', 'exclude', 'className', 'includeTests', 'limit', 'codeOnly', 'context', 'in'],
     toc:          ['file', 'exclude', 'top', 'limit', 'all', 'detailed', 'topLevel', 'in'],
-    search:       ['file', 'exclude', 'includeTests', 'top', 'limit', 'codeOnly', 'caseSensitive', 'context', 'regex', 'in', 'type', 'param', 'receiver', 'returns', 'decorator', 'exported', 'unused'],
-    tests:        ['className', 'callsOnly'],
-    affectedTests:['file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'depth', 'minConfidence'],
+    search:       ['term', 'file', 'exclude', 'includeTests', 'top', 'limit', 'codeOnly', 'caseSensitive', 'context', 'regex', 'in', 'type', 'param', 'receiver', 'returns', 'decorator', 'exported', 'unused'],
+    tests:        ['name', 'file', 'exclude', 'className', 'callsOnly'],
+    affectedTests:['name', 'file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'depth', 'minConfidence'],
     deadcode:     ['file', 'exclude', 'includeTests', 'includeExported', 'includeDecorated', 'limit', 'in'],
     entrypoints:  ['file', 'exclude', 'includeTests', 'limit', 'type', 'framework'],
     // Extracting code
-    fn:           ['file', 'className', 'all'],
-    class:        ['file', 'all', 'maxLines'],
+    fn:           ['name', 'file', 'className', 'all'],
+    class:        ['name', 'file', 'all', 'maxLines'],
     lines:        ['file', 'range'],
-    expand:       [],
+    expand:       ['item'],
     // File dependencies
     imports:      ['file'],
     exporters:    ['file'],
     fileExports:  ['file'],
-    graph:        ['file', 'depth', 'direction'],
+    graph:        ['file', 'depth', 'direction', 'all'],
     circularDeps: ['file', 'exclude'],
     // Refactoring
-    verify:       ['file', 'className'],
-    plan:         ['file', 'className', 'addParam', 'removeParam', 'renameTo', 'defaultValue'],
+    verify:       ['name', 'file', 'className'],
+    plan:         ['name', 'file', 'className', 'addParam', 'removeParam', 'renameTo', 'defaultValue'],
     diffImpact:   ['file', 'limit', 'base', 'staged', 'all'],
     // Other
-    typedef:      ['file', 'className', 'exact'],
+    typedef:      ['name', 'file', 'className', 'exact'],
     stacktrace:   ['stack'],
     api:          ['file', 'limit'],
     stats:        ['functions', 'top'],
@@ -224,11 +224,43 @@ function toCliName(canonical) {
     return canonical.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
 }
 
+/**
+ * Build a reverse map: camelCase → snake_case from PARAM_MAP.
+ * Flags not in PARAM_MAP are already snake_case-safe (single words).
+ */
+function buildReverseParamMap() {
+    const rev = {};
+    for (const [snake, camel] of Object.entries(PARAM_MAP)) {
+        rev[camel] = snake;
+    }
+    return rev;
+}
+
+const REVERSE_PARAM_MAP = buildReverseParamMap();
+
+/**
+ * Generate per-command parameter listing for the MCP tool description.
+ * Maps camelCase flags back to snake_case for MCP clients.
+ * One line per command: `about: file, exclude, class_name, ...`
+ */
+function generateMcpParamSection() {
+    const lines = ['', 'ACCEPTED FLAGS PER COMMAND (max_chars, max_files, follow_symlinks always accepted; flags not listed below are ignored):'];
+    for (const cmd of CANONICAL_COMMANDS) {
+        const flags = FLAG_APPLICABILITY[cmd];
+        if (!flags || flags.length === 0) continue;
+        const mcpCmd = toMcpName(cmd);
+        const mcpFlags = flags.map(f => REVERSE_PARAM_MAP[f] || f);
+        lines.push(`  ${mcpCmd}: ${mcpFlags.join(', ')}`);
+    }
+    return lines.join('\n');
+}
+
 module.exports = {
     CANONICAL_COMMANDS,
     CLI_ALIASES,
     MCP_ALIASES,
     PARAM_MAP,
+    REVERSE_PARAM_MAP,
     FLAG_APPLICABILITY,
     BROAD_COMMANDS,
     resolveCommand,
@@ -237,4 +269,5 @@ module.exports = {
     getMcpCommandEnum,
     toMcpName,
     toCliName,
+    generateMcpParamSection,
 };