ucn 3.8.17 → 3.8.19

package/cli/index.js

@@ -10,11 +10,10 @@
 const fs = require('fs');
 const path = require('path');
 
-const { parseFile, detectLanguage } = require('../core/parser');
+const { detectLanguage } = require('../core/parser');
 const { ProjectIndex } = require('../core/project');
 const { expandGlob, findProjectRoot } = require('../core/discovery');
 const output = require('../core/output');
-const { escapeRegExp } = require('../core/shared');
 const { getCliCommandSet, resolveCommand, FLAG_APPLICABILITY, toCliName } = require('../core/registry');
 const { execute } = require('../core/execute');
 const { ExpandCache } = require('../core/expand-cache');
@@ -75,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'),
@@ -97,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,
@@ -110,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'),
@@ -228,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
 // ============================================================================
@@ -305,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;
     }
@@ -375,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;
+        }
     }
 }
 
@@ -444,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)}'.`);
             }
@@ -510,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
@@ -578,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;
@@ -740,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),
@@ -904,164 +922,217 @@ function runGlobCommand(pattern, command, arg) {
         process.exit(1);
     }
 
-    switch (command) {
-        case 'toc': {
-            let totalFunctions = 0;
-            let totalClasses = 0;
-            let totalState = 0;
-            let totalLines = 0;
-            const byFile = [];
-
-            for (const file of files) {
-                try {
-                    const result = parseFile(file);
-                    let functions = result.functions;
-                    if (flags.topLevel) {
-                        functions = functions.filter(fn => !fn.isNested && (!fn.indent || fn.indent === 0));
-                    }
-                    totalFunctions += functions.length;
-                    totalClasses += result.classes.length;
-                    totalState += result.stateObjects.length;
-                    totalLines += result.totalLines;
-                    byFile.push({
-                        file,
-                        language: result.language,
-                        lines: result.totalLines,
-                        functions,
-                        classes: result.classes,
-                        state: result.stateObjects
-                    });
-                } catch (e) {
-                    // Skip unparseable files
-                }
-            }
-
-            // Convert glob toc to shared formatter format
-            const toc = {
-                totals: { files: files.length, lines: totalLines, functions: totalFunctions, classes: totalClasses, state: totalState },
-                files: byFile.map(f => ({
-                    file: f.file,
-                    lines: f.lines,
-                    functions: f.functions.length,
-                    classes: f.classes.length,
-                    state: f.stateObjects ? f.stateObjects.length : (f.state ? f.state.length : 0)
-                })),
-                meta: {}
-            };
-            if (flags.json) {
-                console.log(output.formatTocJson(toc));
-            } else {
-                console.log(output.formatToc(toc, {
-                    detailedHint: 'Add --detailed to list all functions, or "ucn . about <name>" for full details on a symbol'
-                }));
-            }
-            break;
-        }
-
-        case 'find':
-            if (!arg) {
-                console.error('Usage: ucn "pattern" find <name>');
-                process.exit(1);
-            }
-            findInGlobFiles(files, arg);
-            break;
+    const canonical = resolveCommand(command, 'cli') || command;
 
-        case 'search':
-            if (!arg) {
-                console.error('Usage: ucn "pattern" search <term>');
-                process.exit(1);
-            }
-            searchGlobFiles(files, arg);
-            break;
+    // Build a temporary index over the matched files and route through execute().
+    // This gives glob mode the same semantics as project mode: test exclusions,
+    // limit, all flags — no bespoke logic, no parity drift.
+    const rootDir = findProjectRoot(path.dirname(files[0]));
+    const index = new ProjectIndex(rootDir);
+    index.build(files, { quiet: true });
+
+    // 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);
+    }
 
-        default:
-            console.error(`Command "${command}" not supported in glob mode`);
+    // Build params — same as project mode
+    const params = {};
+    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;
     }
-}
-
-function findInGlobFiles(files, name) {
-    const allMatches = [];
-    const lowerName = name.toLowerCase();
-
-    for (const file of files) {
-        try {
-            const result = parseFile(file);
-
-            for (const fn of result.functions) {
-                if (flags.exact ? fn.name === name : fn.name.toLowerCase().includes(lowerName)) {
-                    allMatches.push({ ...fn, type: 'function', relativePath: file });
-                }
-            }
+    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);
 
-            for (const cls of result.classes) {
-                if (flags.exact ? cls.name === name : cls.name.toLowerCase().includes(lowerName)) {
-                    allMatches.push({ ...cls, relativePath: file });
-                }
+    // 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)}'.`);
             }
-        } catch (e) {
-            // Skip
         }
     }
-
-    if (flags.json) {
-        console.log(output.formatSymbolJson(allMatches, name));
-    } else {
-        console.log(output.formatFindDetailed(allMatches, name, { depth: flags.depth, top: flags.top, all: flags.all }));
+    if (canonical === 'stacktrace' && arg) {
+        params.stack = arg;
     }
-}
-
-function searchGlobFiles(files, term) {
-    const results = [];
-    const useRegex = flags.regex !== false; // Default: regex ON
-    let regex;
-    if (useRegex) {
-        try { regex = new RegExp(term, flags.caseSensitive ? '' : 'i'); } catch (e) { regex = new RegExp(escapeRegExp(term), flags.caseSensitive ? '' : 'i'); }
-    } else {
-        regex = new RegExp(escapeRegExp(term), flags.caseSensitive ? '' : 'i');
+    if (canonical === 'lines' && arg) {
+        params.range = arg;
+    }
+    if (['imports', 'exporters', 'fileExports', 'graph', 'api'].includes(canonical)) {
+        if (arg) params.file = arg;
     }
 
-    for (const file of files) {
-        try {
-            const content = fs.readFileSync(file, 'utf-8');
-            const lines = content.split('\n');
-            const matches = [];
-
-            lines.forEach((line, idx) => {
-                if (regex.test(line)) {
-                    if (flags.codeOnly && isCommentOrString(line)) {
-                        return;
-                    }
-
-                    const match = { line: idx + 1, content: line };
-
-                    if (flags.context > 0) {
-                        const before = [];
-                        const after = [];
-                        for (let i = 1; i <= flags.context; i++) {
-                            if (idx - i >= 0) before.unshift(lines[idx - i]);
-                            if (idx + i < lines.length) after.push(lines[idx + i]);
-                        }
-                        match.before = before;
-                        match.after = after;
-                    }
-
-                    matches.push(match);
-                }
-            });
+    const { ok, result, error, note, structural } = execute(index, canonical, params);
+    if (!ok) fail(error);
+    if (note) console.error(note);
 
-            if (matches.length > 0) {
-                results.push({ file, matches });
+    // Format output — same formatters as project mode
+    switch (canonical) {
+        case 'toc':
+            printOutput(result, output.formatTocJson, r => output.formatToc(r, {
+                detailedHint: 'Add --detailed to list all functions, or "ucn . about <name>" for full details on a symbol'
+            }));
+            break;
+        case 'find':
+            printOutput(result,
+                r => output.formatSymbolJson(r, arg),
+                r => output.formatFindDetailed(r, arg, { depth: flags.depth, top: flags.top, all: flags.all })
+            );
+            break;
+        case 'search':
+            if (structural) {
+                printOutput(result, output.formatStructuralSearchJson, output.formatStructuralSearch);
+            } else {
+                printOutput(result,
+                    r => output.formatSearchJson(r, arg),
+                    r => output.formatSearch(r, arg)
+                );
             }
-        } catch (e) {
-            // Skip
+            break;
+        case 'fn':
+            printOutput(result, output.formatFnResultJson, output.formatFnResult);
+            break;
+        case 'class':
+            printOutput(result, output.formatClassResultJson, output.formatClassResult);
+            break;
+        case 'usages':
+            printOutput(result, r => output.formatUsagesJson(r, arg), r => output.formatUsages(r, arg));
+            break;
+        case 'deadcode':
+            printOutput(result, output.formatDeadcodeJson, r => output.formatDeadcode(r, { top: flags.top }));
+            break;
+        case 'typedef':
+            printOutput(result, r => output.formatTypedefJson(r, arg), r => output.formatTypedef(r, arg));
+            break;
+        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;
         }
-    }
-
-    if (flags.json) {
-        console.log(output.formatSearchJson(results, term));
-    } else {
-        console.log(output.formatSearch(results, term));
     }
 }
 
@@ -1069,13 +1140,6 @@ function searchGlobFiles(files, term) {
 // HELPERS
 // ============================================================================
 
-function isCommentOrString(line) {
-    const trimmed = line.trim();
-    return trimmed.startsWith('//') ||
-        trimmed.startsWith('#') ||
-        trimmed.startsWith('*') ||
-        trimmed.startsWith('/*');
-}
 
 function printUsage() {
     console.log(`UCN - Universal Code Navigator
@@ -1110,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)
 
 ═══════════════════════════════════════════════════════════════════════════════
@@ -1163,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
@@ -1258,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
@@ -1342,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) },
@@ -1396,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) {
 
@@ -1462,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),