ucn 3.8.17 → 3.8.19

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/project.js

@@ -158,28 +158,35 @@ class ProjectIndex {
         const startTime = Date.now();
         const quiet = options.quiet !== false;
 
-        if (!pattern) {
-            pattern = detectProjectPattern(this.root);
-        }
+        // Accept pre-expanded file array (glob mode) or a pattern string
+        let files;
+        if (Array.isArray(pattern)) {
+            files = pattern;
+        } else {
+            if (!pattern) {
+                pattern = detectProjectPattern(this.root);
+            }
 
-        const globOpts = {
-            root: this.root,
-            maxFiles: options.maxFiles || this.config.maxFiles || 50000,
-            followSymlinks: options.followSymlinks
-        };
+            const globOpts = {
+                root: this.root,
+                maxFiles: options.maxFiles || this.config.maxFiles || 50000,
+                followSymlinks: options.followSymlinks
+            };
 
-        // Merge .gitignore and .ucn.json exclude into file discovery
-        const gitignorePatterns = parseGitignore(this.root);
-        const configExclude = this.config.exclude || [];
-        if (gitignorePatterns.length > 0 || configExclude.length > 0) {
-            globOpts.ignores = [...DEFAULT_IGNORES, ...gitignorePatterns, ...configExclude];
-        }
+            // Merge .gitignore and .ucn.json exclude into file discovery
+            const gitignorePatterns = parseGitignore(this.root);
+            const configExclude = this.config.exclude || [];
+            if (gitignorePatterns.length > 0 || configExclude.length > 0) {
+                globOpts.ignores = [...DEFAULT_IGNORES, ...gitignorePatterns, ...configExclude];
+            }
 
-        const files = expandGlob(pattern, globOpts);
+            files = expandGlob(pattern, globOpts);
+        }
 
         // Track if files were truncated by maxFiles limit
-        if (files.length >= globOpts.maxFiles) {
-            this.truncated = { indexed: files.length, maxFiles: globOpts.maxFiles };
+        const maxFiles = options.maxFiles || this.config.maxFiles || 50000;
+        if (!Array.isArray(pattern) && files.length >= maxFiles) {
+            this.truncated = { indexed: files.length, maxFiles };
         } else {
             this.truncated = null;
         }

package/core/registry.js

@@ -92,11 +92,11 @@ 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'],
+    about:        ['file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'includeTests', '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'],
@@ -110,7 +110,7 @@ const FLAG_APPLICABILITY = {
     usages:       ['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'],
+    tests:        ['file', 'exclude', 'className', 'callsOnly'],
     affectedTests:['file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'depth', 'minConfidence'],
     deadcode:     ['file', 'exclude', 'includeTests', 'includeExported', 'includeDecorated', 'limit', 'in'],
     entrypoints:  ['file', 'exclude', 'includeTests', 'limit', 'type', 'framework'],
@@ -123,7 +123,7 @@ const FLAG_APPLICABILITY = {
     imports:      ['file'],
     exporters:    ['file'],
     fileExports:  ['file'],
-    graph:        ['file', 'depth', 'direction'],
+    graph:        ['file', 'depth', 'direction', 'all'],
     circularDeps: ['file', 'exclude'],
     // Refactoring
     verify:       ['file', 'className'],
@@ -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 (name, term, stack, range, base, staged, max_chars 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,
 };