ucn 3.2.0 → 3.4.0

package/README.md

@@ -201,7 +201,7 @@ FIND CODE
 ═══════════════════════════════════════════════════════════════════════════════
   find <name>         Find symbol definitions (top 5 by usage count)
   usages <name>       All usages grouped: definitions, calls, imports, references
-  toc                 Table of contents (functions, classes, state)
+  toc                 Table of contents (compact; --detailed lists all symbols)
   search <term>       Text search (for simple patterns, consider grep instead)
   tests <name>        Find test files for a function
 
@@ -250,13 +250,17 @@ Common Flags:
   --top=N / --all     Limit or show all results
   --include-tests     Include test files
   --include-methods   Include method calls (obj.fn) in caller/callee analysis
+  --include-uncertain Include ambiguous/uncertain call matches
+  --include-exported  Include exported symbols in deadcode
+  --detailed          List all symbols in toc (compact counts by default)
   --no-cache          Disable caching
   --clear-cache       Clear cache before running
   --no-follow-symlinks  Don't follow symbolic links
   -i, --interactive   Keep index in memory for multiple queries
 
 Quick Start:
-  ucn toc                             # See project structure
+  ucn toc                             # See project structure (compact)
+  ucn toc --detailed                  # List all functions/classes
   ucn about handleRequest             # Understand a function
   ucn impact handleRequest            # Before modifying
   ucn fn handleRequest --file api     # Extract specific function

package/cli/index.js

@@ -46,6 +46,10 @@ const flags = {
     includeTests: args.includes('--include-tests'),
     // Deadcode options
     includeExported: args.includes('--include-exported'),
+    // Uncertain matches (off by default)
+    includeUncertain: args.includes('--include-uncertain'),
+    // Detailed listing (e.g. toc with all symbols)
+    detailed: args.includes('--detailed'),
     // Output depth
     depth: args.find(a => a.startsWith('--depth='))?.split('=')[1] || null,
     // Inline expansion for callees
@@ -78,7 +82,7 @@ const knownFlags = new Set([
     '--json', '--verbose', '--no-quiet', '--quiet',
     '--code-only', '--with-types', '--top-level', '--exact',
     '--no-cache', '--clear-cache', '--include-tests',
-    '--include-exported', '--expand', '--interactive', '-i', '--all', '--include-methods',
+    '--include-exported', '--expand', '--interactive', '-i', '--all', '--include-methods', '--include-uncertain', '--detailed',
     '--file', '--context', '--exclude', '--not', '--in',
     '--depth', '--add-param', '--remove-param', '--rename-to',
     '--default', '--top', '--no-follow-symlinks'
@@ -652,7 +656,7 @@ function runProjectCommand(rootDir, command, arg) {
 
     switch (command) {
         case 'toc': {
-            const toc = index.getToc();
+            const toc = index.getToc({ detailed: flags.detailed, topLevel: flags.topLevel });
             printOutput(toc, output.formatTocJson, printProjectToc);
             break;
         }
@@ -699,7 +703,15 @@ function runProjectCommand(rootDir, command, arg) {
 
         case 'context': {
             requireArg(arg, 'Usage: ucn . context <name>');
-            const ctx = index.context(arg, { includeMethods: flags.includeMethods, file: flags.file });
+            const ctx = index.context(arg, {
+                includeMethods: flags.includeMethods,
+                includeUncertain: flags.includeUncertain,
+                file: flags.file
+            });
+            if (!ctx) {
+                console.log(`Symbol "${arg}" not found.`);
+                break;
+            }
             printOutput(ctx,
                 output.formatContextJson,
                 r => { printContext(r, { expand: flags.expand, root: index.root }); }
@@ -730,7 +742,11 @@ function runProjectCommand(rootDir, command, arg) {
 
         case 'smart': {
             requireArg(arg, 'Usage: ucn . smart <name>');
-            const smart = index.smart(arg, { withTypes: flags.withTypes, includeMethods: flags.includeMethods });
+            const smart = index.smart(arg, {
+                withTypes: flags.withTypes,
+                includeMethods: flags.includeMethods,
+                includeUncertain: flags.includeUncertain
+            });
             if (smart) {
                 printOutput(smart, output.formatSmartJson, printSmart);
             } else {
@@ -790,7 +806,7 @@ function runProjectCommand(rootDir, command, arg) {
 
         case 'verify': {
             requireArg(arg, 'Usage: ucn . verify <name>');
-            const verifyResult = index.verify(arg);
+            const verifyResult = index.verify(arg, { file: flags.file });
             printOutput(verifyResult, r => JSON.stringify(r, null, 2), output.formatVerify);
             break;
         }
@@ -906,6 +922,9 @@ function runProjectCommand(rootDir, command, arg) {
                             const exported = item.isExported ? ' [exported]' : '';
                             console.log(`  ${output.lineRange(item.startLine, item.endLine)} ${item.name} (${item.type})${exported}`);
                         }
+                        if (!flags.includeExported) {
+                            console.log(`\nExported symbols excluded by default. Add --include-exported to include them.`);
+                        }
                     }
                 );
             }
@@ -977,26 +996,27 @@ function extractFunctionFromProject(index, name) {
         return;
     }
 
+    let match;
     if (matches.length > 1 && !flags.file) {
-        // Disambiguation needed
-        console.log(output.formatDisambiguation(matches, name, 'fn'));
-        return;
+        // Auto-select best match using same scoring as resolveSymbol
+        match = pickBestDefinition(matches);
+        console.error(`Note: Found ${matches.length} definitions for "${name}". Using ${match.relativePath}:${match.startLine}. Use --file to disambiguate.`);
+    } else {
+        match = matches[0];
     }
 
-    const match = matches[0];
+    // Extract code directly using symbol index location (works for class methods and overloads)
     const code = fs.readFileSync(match.file, 'utf-8');
-    const language = detectLanguage(match.file);
-    const { fn, code: fnCode } = extractFunction(code, language, match.name);
+    const lines = code.split('\n');
+    const fnCode = lines.slice(match.startLine - 1, match.endLine).join('\n');
 
-    if (fn) {
-        if (flags.json) {
-            console.log(output.formatFunctionJson(fn, fnCode));
-        } else {
-            console.log(`${match.relativePath}:${fn.startLine}`);
-            console.log(`${output.lineRange(fn.startLine, fn.endLine)} ${output.formatFunctionSignature(fn)}`);
-            console.log('─'.repeat(60));
-            console.log(fnCode);
-        }
+    if (flags.json) {
+        console.log(output.formatFunctionJson(match, fnCode));
+    } else {
+        console.log(`${match.relativePath}:${match.startLine}`);
+        console.log(`${output.lineRange(match.startLine, match.endLine)} ${output.formatFunctionSignature(match)}`);
+        console.log('─'.repeat(60));
+        console.log(fnCode);
     }
 }
 
@@ -1010,13 +1030,15 @@ function extractClassFromProject(index, name) {
         return;
     }
 
+    let match;
     if (matches.length > 1 && !flags.file) {
-        // Disambiguation needed
-        console.log(output.formatDisambiguation(matches, name, 'class'));
-        return;
+        // Auto-select best match using same scoring as resolveSymbol
+        match = pickBestDefinition(matches);
+        console.error(`Note: Found ${matches.length} definitions for "${name}". Using ${match.relativePath}:${match.startLine}. Use --file to disambiguate.`);
+    } else {
+        match = matches[0];
     }
 
-    const match = matches[0];
     const code = fs.readFileSync(match.file, 'utf-8');
     const language = detectLanguage(match.file);
     const { cls, code: clsCode } = extractClass(code, language, match.name);
@@ -1034,29 +1056,61 @@ function extractClassFromProject(index, name) {
 }
 
 function printProjectToc(toc) {
-    console.log(`PROJECT: ${toc.totalFiles} files, ${toc.totalLines} lines`);
-    console.log(`  ${toc.totalFunctions} functions, ${toc.totalClasses} classes, ${toc.totalState} state objects`);
-    console.log('═'.repeat(60));
+    const t = toc.totals;
+    console.log(`PROJECT: ${t.files} files, ${t.lines} lines`);
+    console.log(`  ${t.functions} functions, ${t.classes} classes, ${t.state} state objects`);
 
-    for (const file of toc.byFile) {
-        // Filter for top-level only if flag is set
-        let functions = file.functions;
-        if (flags.topLevel) {
-            functions = functions.filter(fn => !fn.isNested && (!fn.indent || fn.indent === 0));
-        }
-
-        if (functions.length === 0 && file.classes.length === 0) continue;
-
-        console.log(`\n${file.file} (${file.lines} lines)`);
+    // Show meta warnings only when there's something noteworthy
+    const meta = toc.meta || {};
+    const warnings = [];
+    if (meta.dynamicImports) warnings.push(`${meta.dynamicImports} dynamic import(s)`);
+    if (meta.uncertain) warnings.push(`${meta.uncertain} uncertain reference(s)`);
+    if (warnings.length) {
+        const hint = meta.uncertain ? ' — use --include-uncertain to include all' : '';
+        console.log(`  Note: ${warnings.join(', ')}${hint}`);
+    }
 
-        for (const fn of functions) {
-            console.log(`  ${output.lineRange(fn.startLine, fn.endLine)} ${output.formatFunctionSignature(fn)}`);
+    // Hints
+    if (toc.summary) {
+        if (toc.summary.topFunctionFiles?.length) {
+            const hint = toc.summary.topFunctionFiles.map(f => `${f.file} (${f.functions})`).join(', ');
+            console.log(`  Most functions: ${hint}`);
+        }
+        if (toc.summary.topLineFiles?.length) {
+            const hint = toc.summary.topLineFiles.map(f => `${f.file} (${f.lines})`).join(', ');
+            console.log(`  Largest files: ${hint}`);
         }
+        if (toc.summary.entryFiles?.length) {
+            console.log(`  Entry points: ${toc.summary.entryFiles.join(', ')}`);
+        }
+    }
 
-        for (const cls of file.classes) {
-            console.log(`  ${output.lineRange(cls.startLine, cls.endLine)} ${output.formatClassSignature(cls)}`);
+    console.log('═'.repeat(60));
+    const hasDetail = toc.files.some(f => f.symbols);
+    for (const file of toc.files) {
+        const parts = [`${file.lines} lines`];
+        if (file.functions) parts.push(`${file.functions} fn`);
+        if (file.classes) parts.push(`${file.classes} cls`);
+        if (file.state) parts.push(`${file.state} state`);
+
+        if (hasDetail) {
+            console.log(`\n${file.file} (${parts.join(', ')})`);
+            if (file.symbols) {
+                for (const fn of file.symbols.functions) {
+                    console.log(`  ${output.lineRange(fn.startLine, fn.endLine)} ${output.formatFunctionSignature(fn)}`);
+                }
+                for (const cls of file.symbols.classes) {
+                    console.log(`  ${output.lineRange(cls.startLine, cls.endLine)} ${output.formatClassSignature(cls)}`);
+                }
+            }
+        } else {
+            console.log(`  ${file.file} — ${parts.join(', ')}`);
         }
     }
+
+    if (!hasDetail) {
+        console.log(`\nAdd --detailed to list all functions, or "ucn . about <name>" for full details on a symbol`);
+    }
 }
 
 function printSymbols(symbols, query, options = {}) {
@@ -1506,7 +1560,7 @@ function printBestExample(index, name) {
 
 function printContext(ctx, options = {}) {
     // Handle struct/interface types differently
-    if (ctx.type && ['struct', 'interface', 'type'].includes(ctx.type)) {
+    if (ctx.type && ['class', 'struct', 'interface', 'type'].includes(ctx.type)) {
         console.log(`Context for ${ctx.type} ${ctx.name}:`);
         console.log('═'.repeat(60));
 
@@ -1568,6 +1622,17 @@ function printContext(ctx, options = {}) {
     console.log(`Context for ${ctx.function}:`);
     console.log('═'.repeat(60));
 
+    // Show meta note when results may be incomplete
+    if (ctx.meta) {
+        const notes = [];
+        if (ctx.meta.dynamicImports) notes.push(`${ctx.meta.dynamicImports} dynamic import(s)`);
+        if (ctx.meta.uncertain) notes.push(`${ctx.meta.uncertain} uncertain call(s) skipped`);
+        if (notes.length) {
+            const hint = ctx.meta.uncertain ? ' — use --include-uncertain to include all' : '';
+            console.log(`  Note: ${notes.join(', ')}${hint}`);
+        }
+    }
+
     // Display warnings if any
     if (ctx.warnings && ctx.warnings.length > 0) {
         console.log('\n⚠️  WARNINGS:');
@@ -1717,6 +1782,18 @@ function printExpandedItem(item, root) {
 function printSmart(smart) {
     console.log(`${smart.target.name} (${smart.target.file}:${smart.target.startLine})`);
     console.log('═'.repeat(60));
+
+    // Show meta note when results may be incomplete
+    if (smart.meta) {
+        const notes = [];
+        if (smart.meta.dynamicImports) notes.push(`${smart.meta.dynamicImports} dynamic import(s)`);
+        if (smart.meta.uncertain) notes.push(`${smart.meta.uncertain} uncertain call(s) skipped`);
+        if (notes.length) {
+            const hint = smart.meta.uncertain ? ' — use --include-uncertain to include all' : '';
+            console.log(`  Note: ${notes.join(', ')}${hint}`);
+        }
+    }
+
     console.log(smart.target.code);
 
     if (smart.dependencies.length > 0) {
@@ -2076,6 +2153,30 @@ function printLines(lines, range) {
     }
 }
 
+/**
+ * Pick the best definition from multiple matches using same scoring as resolveSymbol.
+ * Prefers lib/src/core over test/examples/vendor directories.
+ */
+function pickBestDefinition(matches) {
+    const typeOrder = new Set(['class', 'struct', 'interface', 'type', 'impl']);
+    const scored = matches.map(m => {
+        let score = 0;
+        const rp = m.relativePath || '';
+        // Prefer class/struct/interface types (+1000) - same as resolveSymbol
+        if (typeOrder.has(m.type)) score += 1000;
+        if (isTestFile(rp, detectLanguage(m.file))) score -= 500;
+        if (/^(examples?|docs?|vendor|third[_-]?party|benchmarks?|samples?)\//i.test(rp)) score -= 300;
+        if (/^(lib|src|core|internal|pkg|crates)\//i.test(rp)) score += 200;
+        // Tiebreaker: prefer larger function bodies (more important/complex)
+        if (m.startLine && m.endLine) {
+            score += Math.min(m.endLine - m.startLine, 100);
+        }
+        return { match: m, score };
+    });
+    scored.sort((a, b) => b.score - a.score);
+    return scored[0].match;
+}
+
 function suggestSimilar(query, names) {
     const lower = query.toLowerCase();
     const similar = names.filter(n => n.toLowerCase().includes(lower));
@@ -2109,6 +2210,7 @@ Usage:
   ucn <file> [command] [args]     Single file mode
   ucn <dir> [command] [args]      Project mode (specific directory)
   ucn "pattern" [command] [args]  Glob pattern mode
+  (Default output is text; add --json for machine-readable JSON)
 
 ═══════════════════════════════════════════════════════════════════════════════
 UNDERSTAND CODE (UCN's strength - semantic analysis)
@@ -2321,7 +2423,7 @@ function executeInteractiveCommand(index, command, arg) {
                 console.log('Usage: context <name>');
                 return;
             }
-            const ctx = index.context(arg);
+            const ctx = index.context(arg, { includeUncertain: flags.includeUncertain });
             printContext(ctx, { expand: flags.expand, root: index.root });
             break;
         }
@@ -2331,7 +2433,7 @@ function executeInteractiveCommand(index, command, arg) {
                 console.log('Usage: smart <name>');
                 return;
             }
-            const smart = index.smart(arg, {});
+            const smart = index.smart(arg, { includeUncertain: flags.includeUncertain });
             if (smart) {
                 printSmart(smart);
             } else {

package/core/imports.js

@@ -26,14 +26,15 @@ function extractImports(content, language) {
             const parser = getParser(normalizedLang);
             if (parser) {
                 const imports = langModule.findImportsInCode(content, parser);
-                return { imports };
+                const dynamicCount = imports.filter(i => i.dynamic).length;
+                return { imports, dynamicCount };
             }
         } catch (e) {
             // AST parsing failed
         }
     }
 
-    return { imports: [] };
+    return { imports: [], dynamicCount: 0 };
 }
 
 /**
@@ -115,11 +116,46 @@ function resolveImport(importPath, fromFile, config = {}) {
             if (resolved) return resolved;
         }
 
+        // Rust: crate::, super::, self:: paths and mod declarations
+        if (config.language === 'rust') {
+            const resolved = resolveRustImport(importPath, fromFile, config.root);
+            if (resolved) return resolved;
+        }
+
+        // Python: non-relative package imports (e.g., "tools.analyzer" -> "tools/analyzer.py")
+        // Try resolving dotted module path from the project root
+        if (config.language === 'python' && config.root) {
+            const modulePath = importPath.replace(/\./g, '/');
+            const fullPath = path.join(config.root, modulePath);
+            const resolved = resolveFilePath(fullPath, getExtensions('python'));
+            if (resolved) return resolved;
+        }
+
         return null;  // External package
     }
 
+    // Python relative imports: translate dot-prefix notation to file paths
+    // e.g., ".models" -> "./models", "..utils" -> "../utils", "." -> "."
+    let normalizedPath = importPath;
+    if (config.language === 'python') {
+        // Count leading dots and convert to filesystem relative path
+        const dotMatch = importPath.match(/^(\.+)(.*)/);
+        if (dotMatch) {
+            const dots = dotMatch[1];
+            const rest = dotMatch[2];
+            if (dots.length === 1) {
+                // ".models" -> "./models", "." -> "."
+                normalizedPath = rest ? './' + rest.replace(/\./g, '/') : '.';
+            } else {
+                // "..models" -> "../models", "...models" -> "../../models"
+                const upDirs = '../'.repeat(dots.length - 1);
+                normalizedPath = rest ? upDirs + rest.replace(/\./g, '/') : upDirs.slice(0, -1);
+            }
+        }
+    }
+
     // Relative imports
-    const resolved = path.resolve(fromDir, importPath);
+    const resolved = path.resolve(fromDir, normalizedPath);
     return resolveFilePath(resolved, config.extensions || getExtensions(config.language));
 }
 
@@ -200,6 +236,125 @@ function resolveGoImport(importPath, fromFile, projectRoot) {
     return null;
 }
 
+// Cache for Rust crate roots (Cargo.toml locations)
+const cargoCache = new Map();
+
+/**
+ * Find the nearest Cargo.toml and return the crate's source root
+ * @param {string} startDir - Directory to start searching from
+ * @returns {{root: string, srcDir: string}|null}
+ */
+function findCargoRoot(startDir) {
+    if (cargoCache.has(startDir)) {
+        return cargoCache.get(startDir);
+    }
+
+    let dir = startDir;
+    while (dir !== path.dirname(dir)) {
+        const cargoPath = path.join(dir, 'Cargo.toml');
+        if (fs.existsSync(cargoPath)) {
+            const srcDir = path.join(dir, 'src');
+            const result = fs.existsSync(srcDir) ? { root: dir, srcDir } : null;
+            cargoCache.set(startDir, result);
+            return result;
+        }
+        dir = path.dirname(dir);
+    }
+
+    cargoCache.set(startDir, null);
+    return null;
+}
+
+/**
+ * Try to resolve a Rust module path to a file
+ * Checks both <path>.rs and <path>/mod.rs
+ * @param {string} dir - Base directory
+ * @param {string[]} segments - Path segments to resolve
+ * @returns {string|null}
+ */
+function resolveRustModulePath(dir, segments) {
+    // Try progressively shorter paths (items at the end may be types, not modules)
+    for (let len = segments.length; len >= 1; len--) {
+        const modPath = path.join(dir, ...segments.slice(0, len));
+        // Try <path>.rs
+        const rsFile = modPath + '.rs';
+        if (fs.existsSync(rsFile) && fs.statSync(rsFile).isFile()) {
+            return rsFile;
+        }
+        // Try <path>/mod.rs
+        const modFile = path.join(modPath, 'mod.rs');
+        if (fs.existsSync(modFile) && fs.statSync(modFile).isFile()) {
+            return modFile;
+        }
+    }
+    return null;
+}
+
+/**
+ * Resolve Rust import paths to local files
+ * Handles: crate::, super::, self::, and mod declarations
+ * @param {string} importPath - Rust import path (e.g., "crate::display::Display" or "display")
+ * @param {string} fromFile - File containing the import
+ * @param {string} projectRoot - Project root directory
+ * @returns {string|null}
+ */
+function resolveRustImport(importPath, fromFile, projectRoot) {
+    const fromDir = path.dirname(fromFile);
+
+    // crate:: paths - resolve from the crate's src/ directory
+    if (importPath.startsWith('crate::')) {
+        const cargo = findCargoRoot(fromDir);
+        if (!cargo) return null;
+
+        const rest = importPath.slice('crate::'.length);
+        const segments = rest.split('::');
+        return resolveRustModulePath(cargo.srcDir, segments);
+    }
+
+    // super:: paths - resolve relative to parent directory
+    if (importPath.startsWith('super::')) {
+        let dir = fromDir;
+        let rest = importPath;
+        while (rest.startsWith('super::')) {
+            // If current file is mod.rs, go up one more directory
+            const basename = path.basename(fromFile);
+            if (basename === 'mod.rs' && dir === fromDir) {
+                dir = path.dirname(dir);
+            }
+            dir = path.dirname(dir);
+            rest = rest.slice('super::'.length);
+        }
+        const segments = rest.split('::');
+        return resolveRustModulePath(dir, segments);
+    }
+
+    // self:: paths - resolve within current module directory
+    if (importPath.startsWith('self::')) {
+        const rest = importPath.slice('self::'.length);
+        const segments = rest.split('::');
+        // If current file is mod.rs, resolve relative to its directory
+        const basename = path.basename(fromFile);
+        const dir = basename === 'mod.rs' ? fromDir : path.dirname(fromDir);
+        return resolveRustModulePath(dir, segments);
+    }
+
+    // Plain module name without :: (potential mod declaration)
+    // e.g., "display" from `mod display;` - resolve relative to declaring file
+    if (!importPath.includes('::')) {
+        // For mod declarations: <dir>/<name>.rs or <dir>/<name>/mod.rs
+        const rsFile = path.join(fromDir, importPath + '.rs');
+        if (fs.existsSync(rsFile) && fs.statSync(rsFile).isFile()) {
+            return rsFile;
+        }
+        const modFile = path.join(fromDir, importPath, 'mod.rs');
+        if (fs.existsSync(modFile) && fs.statSync(modFile).isFile()) {
+            return modFile;
+        }
+    }
+
+    return null;
+}
+
 /**
  * Try to resolve a path with various extensions
  */
@@ -215,11 +370,14 @@ function resolveFilePath(basePath, extensions) {
         if (fs.existsSync(withExt)) return withExt;
     }
 
-    // Try index files
+    // Try index files (index.js for JS/TS, __init__.py for Python)
     for (const ext of extensions) {
         const indexPath = path.join(basePath, 'index' + ext);
         if (fs.existsSync(indexPath)) return indexPath;
     }
+    // Python __init__.py
+    const initPath = path.join(basePath, '__init__.py');
+    if (fs.existsSync(initPath)) return initPath;
 
     return null;
 }