ucn 3.8.5 → 3.8.7

package/cli/index.js

@@ -74,7 +74,7 @@ function parseFlags(tokens) {
         file: getValueFlag('--file'),
         exclude: parseExclude(),
         in: getValueFlag('--in'),
-        includeTests: tokens.includes('--include-tests'),
+        includeTests: tokens.includes('--include-tests') ? true : undefined,
         includeExported: tokens.includes('--include-exported'),
         includeDecorated: tokens.includes('--include-decorated'),
         includeUncertain: tokens.includes('--include-uncertain'),
@@ -715,7 +715,7 @@ function runProjectCommand(rootDir, command, arg) {
         case 'affectedTests': {
             const { ok, result, error } = execute(index, 'affectedTests', { name: arg, ...flags });
             if (!ok) fail(error);
-            printOutput(result, output.formatAffectedTestsJson, output.formatAffectedTests);
+            printOutput(result, output.formatAffectedTestsJson, r => output.formatAffectedTests(r, { all: flags.all }));
             break;
         }
 
@@ -782,7 +782,7 @@ function runProjectCommand(rootDir, command, arg) {
         case 'diffImpact': {
             const { ok, result, error } = execute(index, 'diffImpact', { base: flags.base, staged: flags.staged, file: flags.file });
             if (!ok) fail(error);
-            printOutput(result, output.formatDiffImpactJson, output.formatDiffImpact);
+            printOutput(result, output.formatDiffImpactJson, r => output.formatDiffImpact(r, { all: flags.all }));
             break;
         }
 
@@ -1504,7 +1504,7 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
         case 'affectedTests': {
             const { ok, result, error } = execute(index, 'affectedTests', { name: arg, ...iflags });
             if (!ok) { console.log(error); return; }
-            console.log(output.formatAffectedTests(result));
+            console.log(output.formatAffectedTests(result, { all: iflags.all }));
             break;
         }
 
@@ -1536,7 +1536,7 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
         case 'diffImpact': {
             const { ok, result, error } = execute(index, 'diffImpact', iflags);
             if (!ok) { console.log(error); return; }
-            console.log(output.formatDiffImpact(result));
+            console.log(output.formatDiffImpact(result, { all: iflags.all }));
             break;
         }
 

package/core/entrypoints.js

@@ -174,6 +174,55 @@ const FRAMEWORK_PATTERNS = [
         pattern: /^tokio::main$/,
     },
 
+    // ── Go Runtime Entry Points ─────────────────────────────────────────
+
+    // Go main function (program entry)
+    {
+        id: 'go-main',
+        languages: new Set(['go']),
+        type: 'runtime',
+        framework: 'go',
+        detection: 'namePattern',
+        pattern: /^main$/,
+    },
+
+    // Go init functions (package initialization, called by runtime)
+    {
+        id: 'go-init',
+        languages: new Set(['go']),
+        type: 'runtime',
+        framework: 'go',
+        detection: 'namePattern',
+        pattern: /^init$/,
+    },
+
+    // Go test functions (called by go test)
+    {
+        id: 'go-test',
+        languages: new Set(['go']),
+        type: 'test',
+        framework: 'go',
+        detection: 'namePattern',
+        pattern: /^(Test|Benchmark|Example|Fuzz)[A-Z_]/,
+    },
+
+    // ── Go Framework Patterns ─────────────────────────────────────────
+
+    // Cobra CLI framework — RunE, Run, PreRunE etc. assigned to cobra.Command struct fields
+    // Detected via call-pattern: cobra.Command composite literals with function value fields
+    {
+        id: 'cobra-command',
+        languages: new Set(['go']),
+        type: 'cli',
+        framework: 'cobra',
+        detection: 'callPattern',
+        receiverPattern: /^cobra$/i,
+        methodPattern: /^Command$/,
+    },
+
+    // Go goroutine launch — go func() or go handler()
+    // (detected separately in namePattern since it's a language feature)
+
     // ── Catch-all fallbacks ─────────────────────────────────────────────
 
     // Python: any decorator with '.' (attribute access) — framework registration heuristic
@@ -308,12 +357,16 @@ function detectEntrypoints(index, options = {}) {
     const results = [];
     const seen = new Set(); // file:line:name dedup key
 
-    // 1. Scan all symbols for decorator/modifier-based patterns
+    // Collect name-based patterns for efficient matching
+    const namePatterns = FRAMEWORK_PATTERNS.filter(p => p.detection === 'namePattern');
+
+    // 1. Scan all symbols for decorator/modifier/name-based patterns
     for (const [name, symbols] of index.symbols) {
         for (const symbol of symbols) {
             const fileEntry = index.files.get(symbol.file);
             if (!fileEntry) continue;
 
+            // Check decorator/modifier-based patterns
             const match = matchDecoratorOrModifier(symbol, fileEntry.language);
             if (match) {
                 const key = `${symbol.file}:${symbol.startLine}:${name}`;
@@ -331,6 +384,30 @@ function detectEntrypoints(index, options = {}) {
                     evidence: [match.matchedOn],
                     confidence: 0.95,
                 });
+                continue;
+            }
+
+            // Check name-based patterns (main, init, TestXxx, etc.)
+            for (const np of namePatterns) {
+                if (!np.languages.has(fileEntry.language)) continue;
+                if (np.pattern.test(name)) {
+                    const key = `${symbol.file}:${symbol.startLine}:${name}`;
+                    if (seen.has(key)) continue;
+                    seen.add(key);
+
+                    results.push({
+                        name,
+                        file: symbol.relativePath || symbol.file,
+                        absoluteFile: symbol.file,
+                        line: symbol.startLine,
+                        type: np.type,
+                        framework: np.framework,
+                        patternId: np.id,
+                        evidence: [`${name}() convention`],
+                        confidence: 1.0,
+                    });
+                    break;
+                }
             }
         }
     }

package/core/execute.js

@@ -149,6 +149,23 @@ function checkFilePatternMatch(index, filePattern) {
     for (const [, fileEntry] of index.files) {
         if (fileEntry.relativePath.includes(filePattern)) return null;
     }
+    // Suggest similar directories/files to help user refine
+    const patternLower = filePattern.toLowerCase();
+    const basename = filePattern.split('/').pop().toLowerCase();
+    const suggestions = new Set();
+    for (const [, fileEntry] of index.files) {
+        const rp = fileEntry.relativePath.toLowerCase();
+        // Check if any path component contains the last segment of the pattern
+        if (basename && rp.includes(basename)) {
+            // Extract the directory containing the match
+            const dir = fileEntry.relativePath.split('/').slice(0, -1).join('/');
+            if (dir) suggestions.add(dir);
+            if (suggestions.size >= 5) break;
+        }
+    }
+    if (suggestions.size > 0) {
+        return `No files matched pattern '${filePattern}'. Similar paths:\n${[...suggestions].map(s => '  ' + s).join('\n')}`;
+    }
     return `No files matched pattern '${filePattern}'.`;
 }
 
@@ -187,17 +204,16 @@ const HANDLERS = {
         if (!result) {
             // Give better error if file/className filter is the problem
             if (p.file || p.className) {
-                const unfiltered = index.about(p.name, {
-                    withTypes: p.withTypes || false,
-                    all: false,
-                    includeMethods: p.includeMethods,
-                    includeUncertain: p.includeUncertain || false,
-                    exclude: toExcludeArray(p.exclude),
-                });
-                if (unfiltered && unfiltered.found !== false && unfiltered.symbol) {
-                    const loc = `${unfiltered.symbol.file}:${unfiltered.symbol.startLine}`;
+                // Show ALL definitions so user can pick the right file= filter
+                const allDefs = index.symbols.get(p.name) || [];
+                if (allDefs.length > 0) {
                     const filterDesc = p.className ? `class "${p.className}"` : `file "${p.file}"`;
-                    return { ok: false, error: `Symbol "${p.name}" not found in ${filterDesc}. Found in: ${loc}. Use the correct --file or Class.method syntax.` };
+                    const locations = allDefs
+                        .slice(0, 10)
+                        .map(d => `  ${d.relativePath}:${d.startLine}${d.className ? ` (${d.className})` : ''}`)
+                        .join('\n');
+                    const more = allDefs.length > 10 ? `\n  ... and ${allDefs.length - 10} more` : '';
+                    return { ok: false, error: `Symbol "${p.name}" not found in ${filterDesc}. Found ${allDefs.length} definition(s) elsewhere:\n${locations}${more}\nUse file= with a path fragment from the list above to disambiguate.` };
                 }
             }
             return { ok: false, error: `Symbol "${p.name}" not found.` };
@@ -422,6 +438,7 @@ const HANDLERS = {
             top: num(p.top, undefined),
             file: p.file,
             exclude: p.exclude,
+            in: p.in,
         });
         // Apply limit to detailed toc entries (symbols are in f.symbols.functions/classes arrays)
         const limit = num(p.limit, undefined);

package/core/output.js

@@ -1084,7 +1084,7 @@ function formatReverseTraceJson(result) {
 /**
  * Format affected-tests command output - text
  */
-function formatAffectedTests(result) {
+function formatAffectedTests(result, options = {}) {
     if (!result) return 'Function not found.';
 
     const lines = [];
@@ -1099,9 +1099,12 @@ function formatAffectedTests(result) {
     if (result.testFiles.length === 0) {
         lines.push('No test files found for any affected function.');
     } else {
+        const MAX_TEST_FILES = options.all ? Infinity : 30;
+        const displayFiles = result.testFiles.slice(0, MAX_TEST_FILES);
+        const truncatedFiles = result.testFiles.length - displayFiles.length;
         lines.push(`Test files to run (${summary.totalTestFiles}):`);
         lines.push('');
-        for (const tf of result.testFiles) {
+        for (const tf of displayFiles) {
             lines.push(`  ${tf.file} (covers: ${tf.coveredFunctions.join(', ')})`);
             // Show up to 5 key matches per file
             const keyMatches = tf.matches
@@ -1111,6 +1114,9 @@ function formatAffectedTests(result) {
                 lines.push(`    L${m.line}: ${m.content}  [${m.matchType}]`);
             }
         }
+        if (truncatedFiles > 0) {
+            lines.push(`\n  ... ${truncatedFiles} more test files (use file= and exclude= to narrow scope)`);
+        }
     }
 
     if (result.uncovered.length > 0) {
@@ -2542,10 +2548,11 @@ function formatStats(stats, options = {}) {
 // DIFF IMPACT
 // ============================================================================
 
-function formatDiffImpact(result) {
+function formatDiffImpact(result, options = {}) {
     if (!result) return 'No diff data.';
 
     const lines = [];
+    const MAX_CALLERS_PER_FN = options.all ? Infinity : 30;
 
     lines.push(`Diff Impact Analysis (vs ${result.base})`);
     lines.push('═'.repeat(60));
@@ -2574,12 +2581,17 @@ function formatDiffImpact(result) {
             }
 
             if (fn.callers.length > 0) {
+                const displayCallers = fn.callers.slice(0, MAX_CALLERS_PER_FN);
+                const truncated = fn.callers.length - displayCallers.length;
                 lines.push(`  Callers (${fn.callers.length}):`);
-                for (const c of fn.callers) {
+                for (const c of displayCallers) {
                     const caller = c.callerName ? `[${c.callerName}]` : '';
                     lines.push(`    ${c.relativePath}:${c.line} ${caller}`);
                     lines.push(`      ${c.content}`);
                 }
+                if (truncated > 0) {
+                    lines.push(`    ... ${truncated} more callers (use file= to scope diff to specific files, or use impact with class_name= for type-filtered results)`);
+                }
             } else {
                 lines.push('  Callers: none found');
             }

package/core/project.js

@@ -919,6 +919,10 @@ class ProjectIndex {
             if (d.startLine && d.endLine && d.type === 'function') {
                 score += Math.min(d.endLine - d.startLine, 100);
             }
+            // Prefer shallower paths (fewer directory levels = more central to project)
+            // Max bonus 50 for root-level files, decreasing with depth
+            const depth = (rp.match(/\//g) || []).length;
+            score += Math.max(0, 50 - depth * 10);
             return { def: d, score };
         });
 
@@ -969,10 +973,15 @@ class ProjectIndex {
         // Build warnings
         const warnings = [];
         if (definitions.length > 1) {
+            const others = definitions.filter(d => d !== def);
+            const shown = others.slice(0, 5);
+            const extra = others.length - shown.length;
+            const alsoIn = shown.map(d => `${d.relativePath}:${d.startLine}`).join(', ');
+            const suffix = extra > 0 ? `, and ${extra} more` : '';
             warnings.push({
                 type: 'ambiguous',
-                message: `Found ${definitions.length} definitions for "${name}". Using ${def.relativePath}:${def.startLine}. Also in: ${definitions.filter(d => d !== def).map(d => `${d.relativePath}:${d.startLine}`).join(', ')}. Specify a file to disambiguate.`,
-                alternatives: definitions.filter(d => d !== def).map(d => ({
+                message: `Found ${definitions.length} definitions for "${name}". Using ${def.relativePath}:${def.startLine}. Also in: ${alsoIn}${suffix}. Use file= to disambiguate.`,
+                alternatives: others.map(d => ({
                     file: d.relativePath,
                     line: d.startLine
                 }))
@@ -3255,11 +3264,29 @@ class ProjectIndex {
             // like .close(), .get() etc. where many types have the same method.
             if (def.className) {
                 const targetClassName = def.className;
+                // Pre-compute how many types share this method name
+                const _impMethodDefs = this.symbols.get(name);
+                const _impClassNames = new Set();
+                if (_impMethodDefs) {
+                    for (const d of _impMethodDefs) {
+                        if (d.className) _impClassNames.add(d.className);
+                        else if (d.receiver) _impClassNames.add(d.receiver.replace(/^\*/, ''));
+                    }
+                }
                 callerResults = callerResults.filter(c => {
                     // Keep non-method calls and self/this/cls calls (already resolved by findCallers)
                     if (!c.isMethod) return true;
                     const r = c.receiver;
-                    if (!r || ['self', 'cls', 'this', 'super'].includes(r)) return true;
+                    if (r && ['self', 'cls', 'this', 'super'].includes(r)) return true;
+                    // Use receiverType from findCallers when available (Go/Java/Rust type inference)
+                    if (c.receiverType) {
+                        return c.receiverType === targetClassName;
+                    }
+                    // No receiver (chained/complex expression): only include if method is
+                    // unique or rare across types — otherwise too many false positives
+                    if (!r) {
+                        return _impClassNames.size <= 1;
+                    }
                     // Check if receiver matches the target class name (case-insensitive camelCase convention)
                     if (r.toLowerCase().includes(targetClassName.toLowerCase())) return true;
                     // Check if receiver is an instance of the target class using local variable type inference
@@ -3341,17 +3368,8 @@ class ProjectIndex {
                     }
                     // Unique method heuristic: if the called method exists on exactly one class/type
                     // and it matches the target, include the call (no other class could match)
-                    const methodDefs = this.symbols.get(name);
-                    if (methodDefs) {
-                        const classNames = new Set();
-                        for (const d of methodDefs) {
-                            if (d.className) classNames.add(d.className);
-                            // Go/Rust: use receiver type as className equivalent
-                            else if (d.receiver) classNames.add(d.receiver.replace(/^\*/, ''));
-                        }
-                        if (classNames.size === 1 && classNames.has(targetClassName)) {
-                            return true;
-                        }
+                    if (_impClassNames.size === 1 && _impClassNames.has(targetClassName)) {
+                        return true;
                     }
                     // Type-scoped query but receiver type unknown — filter it out.
                     // Unknown receivers are likely unrelated.
@@ -4697,6 +4715,9 @@ class ProjectIndex {
             if (options.exclude && options.exclude.length > 0) {
                 if (!this.matchesFilters(fileEntry.relativePath, { exclude: options.exclude })) continue;
             }
+            if (options.in) {
+                if (!this.matchesFilters(fileEntry.relativePath, { in: options.in })) continue;
+            }
             let functions = fileEntry.symbols.filter(s =>
                 s.type === 'function' || s.type === 'method' || s.type === 'static' ||
                 s.type === 'constructor' || s.type === 'public' || s.type === 'abstract' ||
@@ -4789,6 +4810,7 @@ class ProjectIndex {
                 uncertain: 0,
                 projectLanguage: this._getPredominantLanguage(),
                 ...(fileFilter && { filteredBy: options.file, matchedFiles: files.length }),
+                ...(options.in && { scopedTo: options.in }),
                 ...(emptyFiles > 0 && fileFilter && { emptyFiles })
             },
             totals: {
@@ -5153,24 +5175,38 @@ class ProjectIndex {
                 const targetDef = targetDefs[0] || symbol;
                 if (targetDef.className && (lang === 'go' || lang === 'java' || lang === 'rust')) {
                     const targetClassName = targetDef.className;
+                    // Pre-compute how many types share this method name
+                    const methodDefs = this.symbols.get(symbol.name);
+                    const classNames = new Set();
+                    if (methodDefs) {
+                        for (const d of methodDefs) {
+                            if (d.className) classNames.add(d.className);
+                            else if (d.receiver) classNames.add(d.receiver.replace(/^\*/, ''));
+                        }
+                    }
+                    const isWidelyShared = classNames.size > 3;
                     callers = callers.filter(c => {
                         if (!c.isMethod) return true;
                         const r = c.receiver;
-                        if (!r || ['self', 'cls', 'this', 'super'].includes(r)) return true;
+                        if (r && ['self', 'cls', 'this', 'super'].includes(r)) return true;
+                        // No receiver (chained/complex expression): only include if method is
+                        // unique or rare across types — otherwise too many false positives
+                        if (!r) {
+                            return classNames.size <= 1;
+                        }
                         // Use receiverType from findCallers when available
                         if (c.receiverType) {
                             return c.receiverType === targetClassName ||
                                    c.receiverType === targetDef.receiver?.replace(/^\*/, '');
                         }
                         // Unique method heuristic: if the method exists on exactly one class/type, include
-                        const methodDefs = this.symbols.get(symbol.name);
-                        if (methodDefs) {
-                            const classNames = new Set();
-                            for (const d of methodDefs) {
-                                if (d.className) classNames.add(d.className);
-                                else if (d.receiver) classNames.add(d.receiver.replace(/^\*/, ''));
-                            }
-                            if (classNames.size === 1 && classNames.has(targetClassName)) return true;
+                        if (classNames.size === 1 && classNames.has(targetClassName)) return true;
+                        // For widely shared method names (Get, Set, Run, etc.), require same-package
+                        // evidence when receiver type is unknown
+                        if (isWidelyShared) {
+                            const callerFile = c.file || '';
+                            const targetDir = path.dirname(change.filePath);
+                            return path.dirname(callerFile) === targetDir;
                         }
                         // Unknown receiver + multiple classes with this method → filter out
                         return false;

package/core/registry.js

@@ -83,6 +83,7 @@ const PARAM_MAP = {
     default_value:     'defaultValue',
     top_level:         'topLevel',
     max_files:         'maxFiles',
+    max_chars:         'maxChars',
 };
 
 // ============================================================================

package/languages/go.js

@@ -889,6 +889,108 @@ function findCallsInCode(code, parser, options = {}) {
             }
         }
 
+        // Detect function-value assignments:
+        // Pattern 1: sched.SchedulePod = sched.schedulePod (field = method reference)
+        // Pattern 2: sched.SchedulePod = schedulePod (field = function reference)
+        // Pattern 3: var handler = processEvent (short variable = function reference)
+        // The RHS is a function reference (not a call — no parentheses)
+        if (node.type === 'assignment_statement' || node.type === 'short_var_declaration') {
+            // Skip blank identifier assignments: _ = x (used to suppress unused warnings)
+            const left = node.childForFieldName('left');
+            const isBlankAssign = left && left.text.trim() === '_';
+            const right = isBlankAssign ? null : node.childForFieldName('right');
+            if (right) {
+                // Walk through the expression list (could be multiple assignments)
+                const rhsNodes = right.type === 'expression_list' ? right.namedChildren : [right];
+                for (const rhs of rhsNodes) {
+                    // selector_expression: sched.schedulePod
+                    if (rhs.type === 'selector_expression') {
+                        const fieldNode = rhs.childForFieldName('field');
+                        const operandNode = rhs.childForFieldName('operand');
+                        if (fieldNode && operandNode) {
+                            const receiver = operandNode.type === 'identifier' ? operandNode.text : undefined;
+                            const receiverType = receiver ? getReceiverType(receiver) : undefined;
+                            const enclosingFunction = getCurrentEnclosingFunction();
+                            calls.push({
+                                name: fieldNode.text,
+                                line: rhs.startPosition.row + 1,
+                                isMethod: true,
+                                receiver,
+                                ...(receiverType && { receiverType }),
+                                enclosingFunction,
+                                isPotentialCallback: true,
+                                uncertain: false
+                            });
+                        }
+                    }
+                    // Plain identifier: schedulePod (standalone function reference)
+                    if (rhs.type === 'identifier') {
+                        const name = rhs.text;
+                        if (!GO_SKIP_IDENTS.has(name) && !GO_BUILTINS.has(name) && !importAliases.has(name) && /^[a-zA-Z]/.test(name)) {
+                            const enclosingFunction = getCurrentEnclosingFunction();
+                            calls.push({
+                                name,
+                                line: rhs.startPosition.row + 1,
+                                isMethod: false,
+                                isFunctionReference: true,
+                                isPotentialCallback: true,
+                                enclosingFunction,
+                                uncertain: false
+                            });
+                        }
+                    }
+                }
+            }
+        }
+
+        // Detect function references in composite literal fields:
+        // ResourceEventHandlerFuncs{AddFunc: addNodeToCache, UpdateFunc: updateNode}
+        // keyed_element → literal_element(key) ":" literal_element(value)
+        // Go wraps values in literal_element nodes — unwrap to get the actual expression
+        if (node.type === 'keyed_element') {
+            // The value (second child, unwrap literal_element if present)
+            let valueNode = node.namedChildCount >= 2 ? node.namedChild(node.namedChildCount - 1) : null;
+            if (valueNode && valueNode.type === 'literal_element') {
+                valueNode = valueNode.namedChildCount > 0 ? valueNode.namedChild(0) : null;
+            }
+            if (valueNode) {
+                if (valueNode.type === 'identifier') {
+                    const name = valueNode.text;
+                    if (!GO_SKIP_IDENTS.has(name) && !GO_BUILTINS.has(name) && !importAliases.has(name) && /^[a-zA-Z]/.test(name)) {
+                        const enclosingFunction = getCurrentEnclosingFunction();
+                        calls.push({
+                            name,
+                            line: valueNode.startPosition.row + 1,
+                            isMethod: false,
+                            isFunctionReference: true,
+                            isPotentialCallback: true,
+                            enclosingFunction,
+                            uncertain: false
+                        });
+                    }
+                }
+                if (valueNode.type === 'selector_expression') {
+                    const fieldNode = valueNode.childForFieldName('field');
+                    const operandNode = valueNode.childForFieldName('operand');
+                    if (fieldNode && operandNode) {
+                        const receiver = operandNode.type === 'identifier' ? operandNode.text : undefined;
+                        const receiverType = receiver ? getReceiverType(receiver) : undefined;
+                        const enclosingFunction = getCurrentEnclosingFunction();
+                        calls.push({
+                            name: fieldNode.text,
+                            line: valueNode.startPosition.row + 1,
+                            isMethod: true,
+                            receiver,
+                            ...(receiverType && { receiverType }),
+                            enclosingFunction,
+                            isPotentialCallback: true,
+                            uncertain: false
+                        });
+                    }
+                }
+            }
+        }
+
         return true;
     }, {
         onLeave: (node) => {

package/mcp/server.js

@@ -45,20 +45,18 @@ const indexCache = new Map(); // projectDir → { index, checkedAt }
 const MAX_CACHE_SIZE = 10;
 const expandCacheInstance = new ExpandCache();
 
-function getIndex(projectDir) {
+function getIndex(projectDir, options) {
+    const maxFiles = options && options.maxFiles;
     const absDir = path.resolve(projectDir);
     if (!fs.existsSync(absDir) || !fs.statSync(absDir).isDirectory()) {
         throw new Error(`Project directory not found: ${absDir}`);
     }
     const root = findProjectRoot(absDir);
     const cached = indexCache.get(root);
-    const STALE_CHECK_INTERVAL_MS = 2000;
 
-    // Throttle staleness checks — isCacheStale() re-globs and stats all files
-    if (cached) {
-        if (Date.now() - cached.checkedAt < STALE_CHECK_INTERVAL_MS) {
-            return cached.index; // Recently verified fresh
-        }
+    // Always check staleness — MCP is used in iterative agent loops where
+    // files change between requests, so a throttle causes stale results.
+    if (cached && !maxFiles) {
         if (!cached.index.isCacheStale()) {
             cached.checkedAt = Date.now();
             return cached.index;
@@ -67,12 +65,15 @@ function getIndex(projectDir) {
 
     // Build new index (or rebuild stale one)
     const index = new ProjectIndex(root);
+    const buildOpts = { quiet: true, forceRebuild: false };
+    if (maxFiles) buildOpts.maxFiles = maxFiles;
     const loaded = index.loadCache();
-    if (loaded && !index.isCacheStale()) {
-        // Disk cache is fresh
+    if (loaded && !maxFiles && !index.isCacheStale()) {
+        // Disk cache is fresh (skip when maxFiles is set — cached index may have different file count)
     } else {
-        index.build(null, { quiet: true, forceRebuild: loaded });
-        index.saveCache();
+        buildOpts.forceRebuild = !!loaded;
+        index.build(null, buildOpts);
+        if (!maxFiles) index.saveCache(); // Don't pollute disk cache with partial indexes
         // Clear expand cache entries for this project — stale after rebuild
         expandCacheInstance.clearForRoot(root);
     }
@@ -93,7 +94,10 @@ function getIndex(projectDir) {
         }
     }
 
-    indexCache.set(root, { index, checkedAt: Date.now() });
+    // Don't cache partial indexes (maxFiles) — they'd serve wrong results for full queries
+    if (!maxFiles) {
+        indexCache.set(root, { index, checkedAt: Date.now() });
+    }
     return index;
 }
 
@@ -110,16 +114,29 @@ const server = new McpServer({
 // TOOL HELPERS
 // ============================================================================
 
-const MAX_OUTPUT_CHARS = 100000; // ~100KB, safe for all MCP clients
+const DEFAULT_OUTPUT_CHARS = 30000;  // ~7.5K tokens — safe default for AI context
+const MAX_OUTPUT_CHARS = 100000;     // hard ceiling even with max_chars override
 
-function toolResult(text) {
+function toolResult(text, command, maxChars) {
     if (!text) return { content: [{ type: 'text', text: '(no output)' }] };
-    if (text.length > MAX_OUTPUT_CHARS) {
-        const truncated = text.substring(0, MAX_OUTPUT_CHARS);
+    const limit = Math.min(maxChars || DEFAULT_OUTPUT_CHARS, MAX_OUTPUT_CHARS);
+    if (text.length > limit) {
+        const fullSize = text.length;
+        const fullTokens = Math.round(fullSize / 4);
+        const truncated = text.substring(0, limit);
         // Cut at last newline to avoid breaking mid-line
         const lastNewline = truncated.lastIndexOf('\n');
-        const cleanCut = lastNewline > MAX_OUTPUT_CHARS * 0.8 ? truncated.substring(0, lastNewline) : truncated;
-        return { content: [{ type: 'text', text: cleanCut + '\n\n... (output truncated — refine query or use file/in/exclude parameters to narrow scope)' }] };
+        const cleanCut = lastNewline > limit * 0.8 ? truncated.substring(0, lastNewline) : truncated;
+        // Command-specific narrowing hints
+        let narrow = 'Use file=/in=/exclude= to narrow scope.';
+        if (command === 'toc') {
+            narrow = 'Use in= to scope to a subdirectory, or detailed=false for compact view.';
+        } else if (command === 'diff_impact') {
+            narrow = 'Use file= to scope to specific files/directories.';
+        } else if (command === 'affected_tests') {
+            narrow = 'Use file= to scope, exclude= to skip patterns.';
+        }
+        return { content: [{ type: 'text', text: cleanCut + `\n\n... OUTPUT TRUNCATED: showing ${limit} of ${fullSize} chars. Full output would be ~${fullTokens} tokens. ${narrow} Or use all=true to see everything (warning: ~${fullTokens} tokens).` }] };
     }
     return { content: [{ type: 'text', text }] };
 }
@@ -268,6 +285,7 @@ server.registerTool(
             class_name: z.string().optional().describe('Class name to scope method analysis (e.g. "MarketDataFetcher" for close)'),
             limit: z.number().optional().describe('Max results to return (default: 500). Caps find, usages, search, deadcode, api, toc --detailed.'),
             max_files: z.number().optional().describe('Max files to index (default: 10000). Use for very large codebases.'),
+            max_chars: z.number().optional().describe('Max output chars before truncation (default: 30000 ~7.5K tokens, max: 100000 ~25K tokens). Use all=true to bypass all caps, or set this for fine-grained control. Truncation message shows full size.'),
             // Structural search flags (search command)
             type: z.string().optional().describe('Symbol type filter for structural search: function, class, call, method, type. Triggers index-based search.'),
             param: z.string().optional().describe('Filter by parameter name or type (structural search). E.g. "Request", "ctx".'),
@@ -287,6 +305,11 @@ server.registerTool(
         // This eliminates per-case param selection and prevents CLI/MCP drift.
         const { command: _c, project_dir: _p, ...rawParams } = args;
         const ep = normalizeParams(rawParams);
+        // all=true bypasses both formatter caps AND char truncation (parity with CLI --all)
+        const maxChars = ep.all ? MAX_OUTPUT_CHARS : ep.maxChars;
+
+        // Wrap toolResult to auto-inject maxChars from this request
+        const tr = (text, cmd) => toolResult(text, cmd, maxChars);
 
         try {
             switch (command) {
@@ -298,10 +321,10 @@ server.registerTool(
             // ── Commands using shared executor ─────────────────────────
 
             case 'about': {
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'about', ep);
-                if (!ok) return toolResult(error); // soft error — won't kill sibling calls
-                return toolResult(output.formatAbout(result, {
+                if (!ok) return tr(error); // soft error — won't kill sibling calls
+                return tr(output.formatAbout(result, {
                     allHint: 'Repeat with all=true to show all.',
                     methodsHint: 'Note: obj.method() callers/callees excluded. Use include_methods=true to include them.',
                     showConfidence: ep.showConfidence,
@@ -309,73 +332,73 @@ server.registerTool(
             }
 
             case 'context': {
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result: ctx, error } = execute(index, 'context', ep);
-                if (!ok) return toolResult(error); // context uses soft error (not toolError)
+                if (!ok) return tr(error); // context uses soft error (not toolError)
                 const { text, expandable } = output.formatContext(ctx, {
                     expandHint: 'Use expand command with item number to see code for any item.',
                     showConfidence: ep.showConfidence,
                 });
                 expandCacheInstance.save(index.root, ep.name, ep.file, expandable);
-                return toolResult(text);
+                return tr(text);
             }
 
             case 'impact': {
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'impact', ep);
-                if (!ok) return toolResult(error); // soft error
-                return toolResult(output.formatImpact(result));
+                if (!ok) return tr(error); // soft error
+                return tr(output.formatImpact(result));
             }
 
             case 'blast': {
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'blast', ep);
-                if (!ok) return toolResult(error); // soft error
-                return toolResult(output.formatBlast(result, {
+                if (!ok) return tr(error); // soft error
+                return tr(output.formatBlast(result, {
                     allHint: 'Set depth to expand all children.',
                 }));
             }
 
             case 'smart': {
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'smart', ep);
-                if (!ok) return toolResult(error); // soft error
-                return toolResult(output.formatSmart(result));
+                if (!ok) return tr(error); // soft error
+                return tr(output.formatSmart(result));
             }
 
             case 'trace': {
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'trace', ep);
-                if (!ok) return toolResult(error); // soft error
-                return toolResult(output.formatTrace(result, {
+                if (!ok) return tr(error); // soft error
+                return tr(output.formatTrace(result, {
                     allHint: 'Set depth to expand all children.',
                     methodsHint: 'Note: obj.method() calls excluded. Use include_methods=true to include them.'
                 }));
             }
 
             case 'reverse_trace': {
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'reverseTrace', ep);
-                if (!ok) return toolResult(error);
-                return toolResult(output.formatReverseTrace(result, {
+                if (!ok) return tr(error);
+                return tr(output.formatReverseTrace(result, {
                     allHint: 'Set depth to expand all children.',
                 }));
             }
 
             case 'example': {
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'example', ep);
-                if (!ok) return toolResult(error);
-                if (!result) return toolResult(`No usage examples found for "${ep.name}".`);
-                return toolResult(output.formatExample(result, ep.name));
+                if (!ok) return tr(error);
+                if (!result) return tr(`No usage examples found for "${ep.name}".`);
+                return tr(output.formatExample(result, ep.name));
             }
 
             case 'related': {
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'related', ep);
-                if (!ok) return toolResult(error);
-                if (!result) return toolResult(`Symbol "${ep.name}" not found.`);
-                return toolResult(output.formatRelated(result, {
+                if (!ok) return tr(error);
+                if (!result) return tr(`Symbol "${ep.name}" not found.`);
+                return tr(output.formatRelated(result, {
                     all: ep.all || false, top: ep.top,
                     allHint: 'Repeat with all=true to show all.'
                 }));
@@ -384,62 +407,62 @@ server.registerTool(
             // ── Finding Code ────────────────────────────────────────────
 
             case 'find': {
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'find', ep);
-                if (!ok) return toolResult(error); // soft error
+                if (!ok) return tr(error); // soft error
                 let text = output.formatFind(result, ep.name, ep.top);
                 if (note) text += '\n\n' + note;
-                return toolResult(text);
+                return tr(text);
             }
 
             case 'usages': {
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'usages', ep);
-                if (!ok) return toolResult(error); // soft error
+                if (!ok) return tr(error); // soft error
                 let text = output.formatUsages(result, ep.name);
                 if (note) text += '\n\n' + note;
-                return toolResult(text);
+                return tr(text);
             }
 
             case 'toc': {
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'toc', ep);
-                if (!ok) return toolResult(error); // soft error
+                if (!ok) return tr(error); // soft error
                 let text = output.formatToc(result, {
                     topHint: 'Set top=N or use detailed=false for compact view.'
                 });
                 if (note) text += '\n\n' + note;
-                return toolResult(text);
+                return tr(text, 'toc');
             }
 
             case 'search': {
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result, error, structural } = execute(index, 'search', ep);
-                if (!ok) return toolResult(error); // soft error
+                if (!ok) return tr(error); // soft error
                 if (structural) {
-                    return toolResult(output.formatStructuralSearch(result));
+                    return tr(output.formatStructuralSearch(result));
                 }
-                return toolResult(output.formatSearch(result, ep.term));
+                return tr(output.formatSearch(result, ep.term));
             }
 
             case 'tests': {
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'tests', ep);
-                if (!ok) return toolResult(error); // soft error
-                return toolResult(output.formatTests(result, ep.name));
+                if (!ok) return tr(error); // soft error
+                return tr(output.formatTests(result, ep.name));
             }
 
             case 'affected_tests': {
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'affectedTests', ep);
-                if (!ok) return toolResult(error);
-                return toolResult(output.formatAffectedTests(result));
+                if (!ok) return tr(error);
+                return tr(output.formatAffectedTests(result, { all: ep.all }), 'affected_tests');
             }
 
             case 'deadcode': {
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'deadcode', ep);
-                if (!ok) return toolResult(error); // soft error
+                if (!ok) return tr(error); // soft error
                 const dcNote = note;
                 let dcText = output.formatDeadcode(result, {
                     top: ep.top || 0,
@@ -447,44 +470,44 @@ server.registerTool(
                     exportedHint: !ep.includeExported && result.excludedExported > 0 ? `${result.excludedExported} exported symbol(s) excluded (all have callers). Use include_exported=true to audit them.` : undefined
                 });
                 if (dcNote) dcText += '\n\n' + dcNote;
-                return toolResult(dcText);
+                return tr(dcText);
             }
 
             case 'entrypoints': {
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'entrypoints', ep);
-                if (!ok) return toolResult(error);
-                return toolResult(output.formatEntrypoints(result));
+                if (!ok) return tr(error);
+                return tr(output.formatEntrypoints(result));
             }
 
             // ── File Dependencies ───────────────────────────────────────
 
             case 'imports': {
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'imports', ep);
-                if (!ok) return toolResult(error); // soft error
-                return toolResult(output.formatImports(result, ep.file));
+                if (!ok) return tr(error); // soft error
+                return tr(output.formatImports(result, ep.file));
             }
 
             case 'exporters': {
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'exporters', ep);
-                if (!ok) return toolResult(error); // soft error
-                return toolResult(output.formatExporters(result, ep.file));
+                if (!ok) return tr(error); // soft error
+                return tr(output.formatExporters(result, ep.file));
             }
 
             case 'file_exports': {
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'fileExports', ep);
-                if (!ok) return toolResult(error); // soft error
-                return toolResult(output.formatFileExports(result, ep.file));
+                if (!ok) return tr(error); // soft error
+                return tr(output.formatFileExports(result, ep.file));
             }
 
             case 'graph': {
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'graph', ep);
-                if (!ok) return toolResult(error); // soft error
-                return toolResult(output.formatGraph(result, {
+                if (!ok) return tr(error); // soft error
+                return tr(output.formatGraph(result, {
                     showAll: ep.all || ep.depth !== undefined,
                     maxDepth: ep.depth ?? 2, file: ep.file,
                     depthHint: 'Set depth parameter for deeper graph.',
@@ -493,65 +516,65 @@ server.registerTool(
             }
 
             case 'circular_deps': {
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'circularDeps', ep);
-                if (!ok) return toolResult(error);
-                return toolResult(output.formatCircularDeps(result));
+                if (!ok) return tr(error);
+                return tr(output.formatCircularDeps(result));
             }
 
             // ── Refactoring ─────────────────────────────────────────────
 
             case 'verify': {
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'verify', ep);
-                if (!ok) return toolResult(error); // soft error
-                return toolResult(output.formatVerify(result));
+                if (!ok) return tr(error); // soft error
+                return tr(output.formatVerify(result));
             }
 
             case 'plan': {
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'plan', ep);
-                if (!ok) return toolResult(error); // soft error
-                return toolResult(output.formatPlan(result));
+                if (!ok) return tr(error); // soft error
+                return tr(output.formatPlan(result));
             }
 
             case 'diff_impact': {
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'diffImpact', ep);
-                if (!ok) return toolResult(error); // soft error — e.g. "not a git repo"
-                return toolResult(output.formatDiffImpact(result));
+                if (!ok) return tr(error); // soft error — e.g. "not a git repo"
+                return tr(output.formatDiffImpact(result, { all: ep.all }), 'diff_impact');
             }
 
             // ── Other ───────────────────────────────────────────────────
 
             case 'typedef': {
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'typedef', ep);
-                if (!ok) return toolResult(error); // soft error
-                return toolResult(output.formatTypedef(result, ep.name));
+                if (!ok) return tr(error); // soft error
+                return tr(output.formatTypedef(result, ep.name));
             }
 
             case 'stacktrace': {
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'stacktrace', ep);
-                if (!ok) return toolResult(error); // soft error
-                return toolResult(output.formatStackTrace(result));
+                if (!ok) return tr(error); // soft error
+                return tr(output.formatStackTrace(result));
             }
 
             case 'api': {
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'api', ep);
-                if (!ok) return toolResult(error); // soft error
+                if (!ok) return tr(error); // soft error
                 let apiText = output.formatApi(result, ep.file || '.');
                 if (note) apiText += '\n\n' + note;
-                return toolResult(apiText);
+                return tr(apiText);
             }
 
             case 'stats': {
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'stats', ep);
-                if (!ok) return toolResult(error); // soft error
-                return toolResult(output.formatStats(result, { top: ep.top || 0 }));
+                if (!ok) return tr(error); // soft error
+                return tr(output.formatStats(result, { top: ep.top || 0 }));
             }
 
             // ── Extracting Code (via execute) ────────────────────────────
@@ -559,16 +582,16 @@ server.registerTool(
             case 'fn': {
                 const err = requireName(ep.name);
                 if (err) return err;
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'fn', ep);
-                if (!ok) return toolResult(error); // soft error
+                if (!ok) return tr(error); // soft error
                 // MCP path security: validate all result files are within project root
                 for (const entry of result.entries) {
                     const check = resolveAndValidatePath(index, entry.match.relativePath || path.relative(index.root, entry.match.file));
                     if (typeof check !== 'string') return check;
                 }
                 const notes = result.notes.length ? result.notes.map(n => 'Note: ' + n).join('\n') + '\n\n' : '';
-                return toolResult(notes + output.formatFnResult(result));
+                return tr(notes + output.formatFnResult(result));
             }
 
             case 'class': {
@@ -577,41 +600,41 @@ server.registerTool(
                 if (ep.maxLines !== undefined && (!Number.isInteger(ep.maxLines) || ep.maxLines < 1)) {
                     return toolError(`Invalid max_lines: ${ep.maxLines}. Must be a positive integer.`);
                 }
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'class', ep);
-                if (!ok) return toolResult(error);  // soft error (class not found)
+                if (!ok) return tr(error);  // soft error (class not found)
                 // MCP path security: validate all result files are within project root
                 for (const entry of result.entries) {
                     const check = resolveAndValidatePath(index, entry.match.relativePath || path.relative(index.root, entry.match.file));
                     if (typeof check !== 'string') return check;
                 }
                 const notes = result.notes.length ? result.notes.map(n => 'Note: ' + n).join('\n') + '\n\n' : '';
-                return toolResult(notes + output.formatClassResult(result));
+                return tr(notes + output.formatClassResult(result));
             }
 
             case 'lines': {
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'lines', ep);
-                if (!ok) return toolResult(error); // soft error
+                if (!ok) return tr(error); // soft error
                 // MCP path security: validate file is within project root
                 const check = resolveAndValidatePath(index, result.relativePath);
                 if (typeof check !== 'string') return check;
-                return toolResult(output.formatLines(result));
+                return tr(output.formatLines(result));
             }
 
             case 'expand': {
                 if (ep.item === undefined || ep.item === null) {
                     return toolError('Item number is required (e.g. item=1).');
                 }
-                const index = getIndex(project_dir);
+                const index = getIndex(project_dir, ep);
                 const lookup = expandCacheInstance.lookup(index.root, ep.item);
                 const { ok, result, error } = execute(index, 'expand', {
                     match: lookup.match, itemNum: ep.item,
                     itemCount: lookup.itemCount, symbolName: lookup.symbolName,
                     validateRoot: true
                 });
-                if (!ok) return toolResult(error); // soft error
-                return toolResult(result.text);
+                if (!ok) return tr(error); // soft error
+                return tr(result.text);
             }
 
             default:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucn",
-  "version": "3.8.5",
+  "version": "3.8.7",
   "mcpName": "io.github.mleoca/ucn",
   "description": "Code intelligence toolkit for AI agents — extract functions, trace call chains, find callers, detect dead code without reading entire files. Works as MCP server, CLI, or agent skill. Supports JS/TS, Python, Go, Rust, Java.",
   "main": "index.js",