ucn 3.1.7 → 3.2.0

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

@@ -2,76 +2,141 @@
 name: ucn
 description: Universal Code Navigator - extracts specific functions and their relationships (callers, callees, dependencies) without reading entire files. Use when you need one function from a large file or need to understand what calls/is called by a function. Saves context in codebases 1000+ LOC. Skip for simple text search, tiny codebases, or unsupported languages (only JS/TS, Python, Go, Rust, Java).
 allowed-tools: Bash(ucn *), Bash(npx ucn *)
-argument-hint: "[command] [symbol-name]"
+argument-hint: "[command] [symbol-name] [--flags]"
 ---
 
-# UCN - Semantic Code Navigation
+# UCN - Universal Code Navigator
 
-## When to Use
+UCN uses tree-sitter ASTs to understand code structure: functions, classes, callers, callees, imports, and dependencies. It works on JavaScript/TypeScript, Python, Go, Rust, and Java.
 
-UCN parses code into ASTs, so it understands structure - not just text patterns.
+## When to Use vs Skip
 
-**Use UCN when:**
-- You need to understand relationships (callers, callees, dependencies)
-- You're about to modify code and need to know the impact
-- You want to extract a specific function without reading the whole file
-- Codebase is 1000+ LOC (indexing overhead pays off)
+**Use UCN when** the codebase is 1000+ LOC and you need:
+- Who calls a function or what it calls
+- What breaks if you change something
+- One function from a large file (without reading the whole file)
+- Unused code detection, dependency graphs
 
 **Skip UCN when:**
-- Simple text search (error messages, TODOs, literals)
-- Codebase is tiny (< 500 LOC) - just read the files
-- Language not supported (C, Ruby, PHP, etc.)
+- Simple text search (TODOs, error messages) — use grep
+- Codebase < 500 LOC — just read the files
+- Language not supported — use grep/read
+- Finding files by name — use glob
 
-## Commands
+## Command Format
 
-### Understanding Code
-```bash
-ucn about <name>      # Definition, callers, callees, tests, code
-ucn context <name>    # Callers + callees
-ucn smart <name>      # Function + dependencies inline
-ucn impact <name>     # All call sites by file
-ucn trace <name>      # Call tree
-ucn example <name>    # Best usage example with context
+```
+ucn [target] <command> [name] [--flags]
 ```
 
-### Finding Code
+**Target** (optional, defaults to current directory):
+- Omit or `.` — current project directory (most common)
+- `path/to/file.js` — single file mode
+- `path/to/dir` — specific project directory
+- `"src/**/*.py"` — glob pattern (quote it)
+
+**Examples of correct invocation:**
 ```bash
-ucn find <name>       # Find definitions
-ucn usages <name>     # All usages by type
-ucn toc               # Table of contents
-ucn tests <name>      # Find tests for a function
-ucn deadcode          # Find unused functions/classes
+ucn about handleRequest
+ucn fn parseConfig --file=utils
+ucn toc
+ucn src/api/routes.js fn handleRequest
+ucn impact createUser --exclude=test
 ```
 
-### Extracting Code
+## Commands
+
+### Understand Code
+| Command | Args | What it returns |
+|---------|------|-----------------|
+| `about <name>` | symbol name | Definition + callers + callees + tests + source code. **Start here.** |
+| `context <name>` | symbol name | Callers and callees (numbered — use `expand N` to see code) |
+| `smart <name>` | symbol name | Function source + all helper functions it calls, inline |
+| `impact <name>` | symbol name | Every call site grouped by file. Use before modifying a function. |
+| `trace <name>` | symbol name | Call tree (who calls who) at `--depth=N` (default 3) |
+| `example <name>` | symbol name | Best real usage example with surrounding context |
+
+### Find Code
+| Command | Args | What it returns |
+|---------|------|-----------------|
+| `find <name>` | symbol name | Definitions ranked by usage count (top 5) |
+| `usages <name>` | symbol name | All usages grouped: definitions, calls, imports, references |
+| `toc` | none | Table of contents: all functions, classes, exports |
+| `tests <name>` | symbol name | Test files and test functions for the given symbol |
+| `search <text>` | search term | Text search (grep-like, but respects project ignores) |
+| `deadcode` | none | Lists all functions/classes with zero callers |
+
+### Extract Code
+| Command | Args | What it returns |
+|---------|------|-----------------|
+| `fn <name>` | function name | Full function source code |
+| `class <name>` | class name | Full class source code |
+| `lines <range>` | e.g. `50-100` | Lines from file. In project mode requires `--file=<path>` |
+| `expand <N>` | number | Source code for numbered item from last `context` output |
+
+### Dependencies
+| Command | Args | What it returns |
+|---------|------|-----------------|
+| `imports <file>` | relative path | What the file imports (modules, symbols) |
+| `exporters <file>` | relative path | Which files import this file |
+| `file-exports <file>` | relative path | What the file exports |
+| `graph <file>` | relative path | Dependency tree at `--depth=N` |
+
+### Refactoring
+| Command | Args | What it returns |
+|---------|------|-----------------|
+| `verify <name>` | function name | Checks all call sites match the function's signature |
+| `plan <name>` | function name | Preview refactoring with `--rename-to`, `--add-param`, `--remove-param` |
+| `related <name>` | symbol name | Functions in same file or sharing dependencies |
+
+## Key Flags
+
+| Flag | Works with | Effect |
+|------|-----------|--------|
+| `--file=<pattern>` | any symbol command | Filter by file path when name is ambiguous (e.g., `--file=routes`) |
+| `--exclude=a,b` | any | Exclude files matching patterns (e.g., `--exclude=test,mock`) |
+| `--in=<path>` | any | Only search within path (e.g., `--in=src/core`) |
+| `--include-tests` | any | Include test files in results (excluded by default) |
+| `--include-methods` | `context`, `smart` | Include `obj.method()` calls (only direct calls shown by default) |
+| `--depth=N` | `trace`, `graph`, `about`, `find` | Tree/expansion depth (default 3) |
+| `--context=N` | `usages`, `search` | Lines of context around each match |
+| `--json` | any | Machine-readable JSON output |
+| `--code-only` | `search` | Exclude matches in comments and strings |
+| `--with-types` | `smart`, `about` | Include type definitions |
+| `--top=N` / `--all` | `find`, `usages` | Limit results to top N, or show all |
+| `--no-cache` | any | Skip cached index (use after file changes) |
+| `--clear-cache` | any | Delete cached index before running |
+
+## Common Patterns
+
+**Investigate a function (first stop):**
 ```bash
-ucn fn <name>                    # Extract function
-ucn fn <name> --file routes      # Disambiguate by path
-ucn class <name>                 # Extract class
+ucn about handleRequest
 ```
 
-### Dependencies
+**Before modifying a function:**
 ```bash
-ucn imports <file>      # What this file imports
-ucn exporters <file>    # Who imports this file
-ucn file-exports <file> # What this file exports
-ucn graph <file>        # Dependency tree
+ucn impact handleRequest          # See all callers
+ucn smart handleRequest           # See function + its helpers
 ```
 
-## Flags
+**Extract one function from a large file:**
+```bash
+ucn fn handleRequest --file=api   # Disambiguate by file path
+```
 
-- `--file <pattern>` - Filter by file path
-- `--exclude=test,mock` - Exclude files
-- `--depth=N` - Tree depth
-- `--context=N` - Lines of context around matches
-- `--code-only` - Filter out comments and strings
-- `--include-methods` - Include obj.method() calls
-- `--include-tests` - Include test files
-- `--no-cache` - Disable caching
-- `--clear-cache` - Clear cache before running
+**Find unused code:**
+```bash
+ucn deadcode
+```
 
-## More Info
+**Understand a file's role:**
+```bash
+ucn imports core/project.js       # What it depends on
+ucn exporters core/project.js     # Who depends on it
+```
 
+**Multiple queries (keeps index in memory):**
 ```bash
-ucn --help            # Full command reference
+ucn --interactive
 ```

package/README.md

@@ -1,38 +1,140 @@
 # UCN - Universal Code Navigator
 
-When working with large codebases or even vibe coding all into a single large file, AI agents often need to read entire files just to understand a single function. This eats up the context rather fast, so the intent is to keep the agents perform better with their context clean than rather cluttered.
+AI agents working with large codebases often read entire files just to understand a single function. UCN uses tree-sitter ASTs to extract exactly what you need — functions, callers, callees, dependencies — without wasting context.
 
-## Example
+## Examples
 
-A 2000-line file and need to understand `handleRequest`:
+**Extract a function** from a large file without reading it:
+```
+$ ucn fn expandGlob
+core/discovery.js:135
+[ 135- 166] expandGlob(pattern, options = {})
+────────────────────────────────────────────────────────────
+function expandGlob(pattern, options = {}) {
+    const root = path.resolve(options.root || process.cwd());
+    const ignores = options.ignores || DEFAULT_IGNORES;
+    ...
+    return files.sort(compareNames);
+}
+```
 
-```bash
-$ ucn fn handleRequest
-src/api/routes.js:145
-[145-162] handleRequest(req, res)
-────────────────────────────────────────────────────────
-function handleRequest(req, res) {
-  const validated = validateInput(req.body);
-  const result = processData(validated);
-  return sendResponse(res, result);
+**See who calls a function and what it calls:**
+```
+$ ucn context expandGlob
+Context for expandGlob:
+════════════════════════════════════════════════════════════
+
+CALLERS (7):
+  [1] cli/index.js:1847 [runGlobCommand]
+    const files = expandGlob(pattern);
+  [2] core/project.js:81
+    const files = expandGlob(pattern, {
+  [3] core/project.js:3434
+    const currentFiles = expandGlob(pattern, { root: this.root });
+  ...
+
+CALLEES (2):
+  [8] parseGlobPattern [utility] - core/discovery.js:171
+  [9] walkDir [utility] - core/discovery.js:227
+```
+
+**See what breaks if you change a function:**
+```
+$ ucn impact shouldIgnore
+Impact analysis for shouldIgnore
+════════════════════════════════════════════════════════════
+core/discovery.js:289
+shouldIgnore (name, ignores, parentDir)
+
+CALL SITES: 2
+  Files affected: 1
+
+BY FILE:
+
+core/discovery.js (2 calls)
+  :255 [walkDir]
+    if (shouldIgnore(entry.name, options.ignores, dir)) continue;
+    args: entry.name, options.ignores, dir
+  :373 [detectProjectPattern]
+    !shouldIgnore(entry.name, DEFAULT_IGNORES)) {
+    args: entry.name, DEFAULT_IGNORES
+```
+
+**Get a function with all its dependencies inline:**
+```
+$ ucn smart shouldIgnore
+shouldIgnore (/Users/mihail/ucn/core/discovery.js:289)
+════════════════════════════════════════════════════════════
+function shouldIgnore(name, ignores, parentDir) {
+    for (const pattern of ignores) {
+        if (pattern.includes('*')) {
+            const regex = globToRegex(pattern);
+            ...
+        }
+    }
+    ...
 }
 
-$ ucn context handleRequest
-CALLERS (3):
-  src/server.js:45 [startServer]
-  src/middleware.js:23 [authMiddleware]
-  test/api.test.js:67 [testHandler]
+─── DEPENDENCIES ───
 
-CALLEES (3):
-  validateInput - src/utils/validation.js:12
-  processData - src/services/data.js:89
-  sendResponse - src/utils/response.js:34
+// globToRegex [utility] (core/discovery.js:208)
+function globToRegex(glob) {
+    let regex = glob.replace(/[.+^$[\]\\]/g, '\\$&');
+    ...
+    return new RegExp('^' + regex + '$');
+}
 ```
 
-18 lines of context instead of 2000.
+**Trace the call tree:**
+```
+$ ucn trace expandGlob --depth=2
+Call tree for expandGlob
+════════════════════════════════════════════════════════════
+
+expandGlob
+├── parseGlobPattern (core/discovery.js:171) [utility] 1x
+│   └── globToRegex (core/discovery.js:208) [utility] 1x
+└── walkDir (core/discovery.js:227) [utility] 1x
+    └── shouldIgnore (core/discovery.js:289) [utility] 1x
+```
+
+**Find unused code:**
+```
+$ ucn deadcode
+Dead code: 15 unused symbol(s)
+
+cli/index.js
+  [1649-1654] extractFunctionNameFromContent (function)
+core/project.js
+  [1664-1694] findReExportsOf (method)
+  [1998-2020] withCompleteness (method)
+...
+```
+
+**See a file's dependencies:**
+```
+$ ucn imports core/project.js
+Imports in core/project.js:
+
+INTERNAL:
+  ./discovery
+    -> core/discovery.js
+    expandGlob, findProjectRoot, detectProjectPattern, isTestFile
+  ./imports
+    -> core/imports.js
+    extractImports, extractExports, resolveImport
+  ./parser
+    -> core/parser.js
+    parseFile
+  ../languages
+    -> languages/index.js
+    detectLanguage, getParser, getLanguageModule, PARSE_OPTIONS, safeParse
+
+EXTERNAL:
+  fs, path, crypto
+```
 
 ## Supported Languages
-The supported languages can grow as tree-sitter supports many, but for my use cases I've added support for:  
 
 JavaScript, TypeScript, Python, Go, Rust, Java
 
@@ -75,49 +177,65 @@ cp -r ucn/.claude/skills/ucn ~/.agents/skills/
 ## Usage
 
 ```
+UCN - Universal Code Navigator
+
+Supported: JavaScript, TypeScript, Python, Go, Rust, Java
+
 Usage:
   ucn [command] [args]            Project mode (current directory)
   ucn <file> [command] [args]     Single file mode
   ucn <dir> [command] [args]      Project mode (specific directory)
   ucn "pattern" [command] [args]  Glob pattern mode
 
-UNDERSTAND CODE
-  about <name>        Full picture (definition, callers, callees, tests, code)
-  context <name>      Who calls this + what it calls
+═══════════════════════════════════════════════════════════════════════════════
+UNDERSTAND CODE (UCN's strength - semantic analysis)
+═══════════════════════════════════════════════════════════════════════════════
+  about <name>        RECOMMENDED: Full picture (definition, callers, callees, tests, code)
+  context <name>      Who calls this + what it calls (numbered for expand)
   smart <name>        Function + all dependencies inline
   impact <name>       What breaks if changed (call sites grouped by file)
   trace <name>        Call tree visualization (--depth=N)
 
+═══════════════════════════════════════════════════════════════════════════════
 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)
-  search <term>       Text search
+  search <term>       Text search (for simple patterns, consider grep instead)
   tests <name>        Find test files for a function
 
+═══════════════════════════════════════════════════════════════════════════════
 EXTRACT CODE
+═══════════════════════════════════════════════════════════════════════════════
   fn <name>           Extract function (--file to disambiguate)
   class <name>        Extract class
   lines <range>       Extract line range (e.g., lines 50-100)
   expand <N>          Show code for item N from context output
 
+═══════════════════════════════════════════════════════════════════════════════
 FILE DEPENDENCIES
+═══════════════════════════════════════════════════════════════════════════════
   imports <file>      What does file import
   exporters <file>    Who imports this file
   file-exports <file> What does file export
   graph <file>        Full dependency tree (--depth=N)
 
+═══════════════════════════════════════════════════════════════════════════════
 REFACTORING HELPERS
+═══════════════════════════════════════════════════════════════════════════════
   plan <name>         Preview refactoring (--add-param, --remove-param, --rename-to)
   verify <name>       Check all call sites match signature
   deadcode            Find unused functions/classes
   related <name>      Find similar functions (same file, shared deps)
 
+═══════════════════════════════════════════════════════════════════════════════
 OTHER
+═══════════════════════════════════════════════════════════════════════════════
   api                 Show exported/public symbols
   typedef <name>      Find type definitions
   stats               Project statistics
-  stacktrace <text>   Parse stack trace, show code at each frame
+  stacktrace <text>   Parse stack trace, show code at each frame (alias: stack)
   example <name>      Best usage example with context
 
 Common Flags:
@@ -134,7 +252,15 @@ Common Flags:
   --include-methods   Include method calls (obj.fn) in caller/callee analysis
   --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 about handleRequest             # Understand a function
+  ucn impact handleRequest            # Before modifying
+  ucn fn handleRequest --file api     # Extract specific function
+  ucn --interactive                   # Multiple queries
 ```
 
 ## License

package/cli/index.js

@@ -529,57 +529,11 @@ function usagesInFile(code, lines, name, filePath, result) {
                 return;
             }
         } catch (e) {
-            // Fall through to regex-based detection
+            // AST parsing failed — usages will be empty, only definitions shown
         }
     }
 
-    // Fallback to regex-based detection (for unsupported languages)
-    const regex = new RegExp('\\b' + escapeRegExp(name) + '\\b');
-    lines.forEach((line, idx) => {
-        const lineNum = idx + 1;
-
-        // Skip definition lines
-        if (defs.some(d => d.startLine === lineNum)) {
-            return;
-        }
-
-        if (regex.test(line)) {
-            if (flags.codeOnly && isCommentOrString(line)) {
-                return;
-            }
-
-            // Skip if the match is inside a string literal
-            if (isInsideString(line, name)) {
-                return;
-            }
-
-            const usageType = classifyUsage(line, name);
-            const usage = {
-                file: filePath,
-                relativePath: filePath,
-                line: lineNum,
-                content: line,
-                usageType,
-                isDefinition: false
-            };
-
-            // Add context
-            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]);
-                }
-                usage.before = before;
-                usage.after = after;
-            }
-
-            usages.push(usage);
-        }
-    });
-
-    // Add definitions to result
+    // Output definitions + any usages found via AST
     const allUsages = [
         ...defs.map(d => ({
             ...d,
@@ -2137,27 +2091,6 @@ function escapeRegExp(text) {
     return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
-function classifyUsage(line, name) {
-    // Check if it's an import first
-    if (/^\s*(import|from|require|use)\b/.test(line)) {
-        return 'import';
-    }
-    // Check if it's a function call (but not a method call)
-    if (new RegExp('\\b' + escapeRegExp(name) + '\\s*\\(').test(line)) {
-        // Exclude method calls (obj.name, this.name, JSON.name, etc.)
-        if (!isMethodCall(line, name)) {
-            return 'call';
-        }
-    }
-    return 'reference';
-}
-
-function isMethodCall(line, name) {
-    // Check if there's a dot or ] immediately before the name
-    const methodPattern = new RegExp('[.\\]]\\s*' + escapeRegExp(name) + '\\s*\\(');
-    return methodPattern.test(line);
-}
-
 function isCommentOrString(line) {
     const trimmed = line.trim();
     return trimmed.startsWith('//') ||
@@ -2166,31 +2099,6 @@ function isCommentOrString(line) {
         trimmed.startsWith('/*');
 }
 
-function isInsideString(line, name) {
-    // Simple heuristic: check if name appears inside quotes
-    // Find all string regions in the line
-    const stringRegex = /(['"`])(?:(?!\1|\\).|\\.)*\1/g;
-    let match;
-
-    while ((match = stringRegex.exec(line)) !== null) {
-        const stringContent = match[0];
-        const stringStart = match.index;
-        const stringEnd = stringStart + stringContent.length;
-
-        // Find where the name appears in the line
-        const nameRegex = new RegExp('\\b' + escapeRegExp(name) + '\\b', 'g');
-        let nameMatch;
-        while ((nameMatch = nameRegex.exec(line)) !== null) {
-            const nameStart = nameMatch.index;
-            // Check if this name occurrence is inside the string
-            if (nameStart > stringStart && nameStart < stringEnd) {
-                return true;
-            }
-        }
-    }
-    return false;
-}
-
 function printUsage() {
     console.log(`UCN - Universal Code Navigator
 

package/core/discovery.js

@@ -107,8 +107,7 @@ const TEST_PATTERNS = {
     ],
     rust: [
         /.*_test\.rs$/,
-        /\/tests\//,
-        /mod tests/
+        /\/tests\//
     ]
 };
 

package/core/imports.js

@@ -9,49 +9,6 @@ const fs = require('fs');
 const path = require('path');
 const { getParser, getLanguageModule } = require('../languages');
 
-/**
- * Import patterns by language
- * @deprecated Use AST-based findImportsInCode() from language modules instead.
- * Kept only as fallback for unsupported languages or when AST parsing fails.
- */
-const IMPORT_PATTERNS = {
-    javascript: {
-        importDefault: /import\s+(\w+)\s+from\s+['"]([^'"]+)['"]/g,
-        importNamed: /import\s*\{([^}]+)\}\s*from\s*['"]([^'"]+)['"]/g,
-        importNamespace: /import\s*\*\s*as\s+(\w+)\s+from\s+['"]([^'"]+)['"]/g,
-        require: /(?:const|let|var)\s+(?:\{[^}]+\}|(\w+))\s*=\s*require\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
-        exportNamed: /^\s*export\s+(?:async\s+)?(?:function|class|const|let|var|interface|type)\s+(\w+)/gm,
-        exportDefault: /^\s*export\s+default\s+(?:(?:async\s+)?(?:function|class)\s+)?(\w+)?/gm,
-        exportList: /^\s*export\s*\{([^}]+)\}/gm,
-        moduleExports: /^module\.exports\s*=\s*(?:\{([^}]+)\}|(\w+))/gm,
-        exportsNamed: /^exports\.(\w+)\s*=[^=]/gm,
-        importType: /import\s+type\s*\{([^}]+)\}\s*from\s*['"]([^'"]+)['"]/g,
-        importSideEffect: /import\s+['"]([^'"]+)['"]/g,
-        importDynamic: /(?:await\s+)?import\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
-        reExportNamed: /^\s*export\s*\{([^}]+)\}\s*from\s*['"]([^'"]+)['"]/gm,
-        reExportAll: /^\s*export\s*\*\s*from\s*['"]([^'"]+)['"]/gm
-    },
-    python: {
-        importModule: /^import\s+([\w.]+)(?:\s+as\s+(\w+))?/gm,
-        fromImport: /^from\s+([.\w]+)\s+import\s+(.+)/gm,
-        exportAll: /__all__\s*=\s*\[([^\]]+)\]/g
-    },
-    go: {
-        importSingle: /import\s+"([^"]+)"/g,
-        importBlock: /import\s*\(\s*([\s\S]*?)\s*\)/g,
-        exportedFunc: /^func\s+(?:\([^)]+\)\s+)?([A-Z]\w*)\s*\(/gm,
-        exportedType: /^type\s+([A-Z]\w*)\s+/gm
-    },
-    java: {
-        importStatement: /import\s+(?:static\s+)?([\w.]+(?:\.\*)?)\s*;/g,
-        exportedClass: /public\s+(?:abstract\s+)?(?:final\s+)?(?:class|interface|enum)\s+(\w+)/g
-    },
-    rust: {
-        useStatement: /^use\s+([^;]+);/gm,
-        modDecl: /^\s*mod\s+(\w+)\s*;/gm
-    }
-};
-
 /**
  * Extract imports from file content using AST
  *
@@ -63,7 +20,6 @@ function extractImports(content, language) {
     // Normalize language name for parser
     const normalizedLang = (language === 'typescript' || language === 'tsx') ? 'javascript' : language;
 
-    // Try AST-based extraction first
     const langModule = getLanguageModule(normalizedLang);
     if (langModule && typeof langModule.findImportsInCode === 'function') {
         try {
@@ -73,176 +29,11 @@ function extractImports(content, language) {
                 return { imports };
             }
         } catch (e) {
-            // Fall through to regex-based extraction
+            // AST parsing failed
         }
     }
 
-    // Fallback to regex-based extraction (deprecated)
-    const imports = [];
-    if (language === 'javascript' || language === 'typescript' || language === 'tsx') {
-        extractJSImports(content, imports);
-    } else if (language === 'python') {
-        extractPythonImports(content, imports);
-    } else if (language === 'go') {
-        extractGoImports(content, imports);
-    } else if (language === 'java') {
-        extractJavaImports(content, imports);
-    } else if (language === 'rust') {
-        extractRustImports(content, imports);
-    }
-
-    return { imports };
-}
-
-/**
- * @deprecated Use AST-based findImportsInCode() from language modules.
- */
-function extractJSImports(content, imports) {
-    const patterns = IMPORT_PATTERNS.javascript;
-    let match;
-
-    // Default imports
-    let regex = new RegExp(patterns.importDefault.source, 'g');
-    while ((match = regex.exec(content)) !== null) {
-        imports.push({ module: match[2], names: [match[1]], type: 'default' });
-    }
-
-    // Named imports
-    regex = new RegExp(patterns.importNamed.source, 'g');
-    while ((match = regex.exec(content)) !== null) {
-        const names = match[1].split(',').map(n => n.trim().split(/\s+as\s+/)[0].trim()).filter(n => n);
-        imports.push({ module: match[2], names, type: 'named' });
-    }
-
-    // Namespace imports
-    regex = new RegExp(patterns.importNamespace.source, 'g');
-    while ((match = regex.exec(content)) !== null) {
-        imports.push({ module: match[2], names: [match[1]], type: 'namespace' });
-    }
-
-    // Require
-    regex = new RegExp(patterns.require.source, 'g');
-    while ((match = regex.exec(content)) !== null) {
-        imports.push({ module: match[2], names: match[1] ? [match[1]] : [], type: 'require' });
-    }
-
-    // Type imports
-    regex = new RegExp(patterns.importType.source, 'g');
-    while ((match = regex.exec(content)) !== null) {
-        const names = match[1].split(',').map(n => n.trim().split(/\s+as\s+/)[0].trim()).filter(n => n);
-        imports.push({ module: match[2], names, type: 'type' });
-    }
-
-    // Side-effect imports
-    regex = new RegExp(patterns.importSideEffect.source, 'g');
-    while ((match = regex.exec(content)) !== null) {
-        const module = match[1];
-        if (!imports.some(i => i.module === module)) {
-            imports.push({ module, names: [], type: 'side-effect' });
-        }
-    }
-
-    // Dynamic imports
-    regex = new RegExp(patterns.importDynamic.source, 'g');
-    while ((match = regex.exec(content)) !== null) {
-        const module = match[1];
-        if (!imports.some(i => i.module === module)) {
-            imports.push({ module, names: [], type: 'dynamic' });
-        }
-    }
-
-    // Re-exports
-    regex = new RegExp(patterns.reExportNamed.source, 'gm');
-    while ((match = regex.exec(content)) !== null) {
-        const names = match[1].split(',').map(n => n.trim().split(/\s+as\s+/)[0].trim()).filter(n => n);
-        imports.push({ module: match[2], names, type: 're-export' });
-    }
-
-    regex = new RegExp(patterns.reExportAll.source, 'gm');
-    while ((match = regex.exec(content)) !== null) {
-        imports.push({ module: match[1], names: ['*'], type: 're-export-all' });
-    }
-}
-
-/** @deprecated Use AST-based findImportsInCode() from language modules. */
-function extractPythonImports(content, imports) {
-    const patterns = IMPORT_PATTERNS.python;
-    let match;
-
-    let regex = new RegExp(patterns.importModule.source, 'gm');
-    while ((match = regex.exec(content)) !== null) {
-        const moduleName = match[1];
-        const alias = match[2] || moduleName.split('.').pop();
-        imports.push({ module: moduleName, names: [alias], type: 'module' });
-    }
-
-    regex = new RegExp(patterns.fromImport.source, 'gm');
-    while ((match = regex.exec(content)) !== null) {
-        const moduleName = match[1];
-        const importList = match[2].trim();
-
-        if (importList === '*') {
-            imports.push({ module: moduleName, names: ['*'], type: 'star' });
-        } else {
-            const names = importList.split(',').map(n => n.trim().split(/\s+as\s+/)[0].trim()).filter(n => n && n !== '(');
-            imports.push({ module: moduleName, names, type: 'from' });
-        }
-    }
-}
-
-/** @deprecated Use AST-based findImportsInCode() from language modules. */
-function extractGoImports(content, imports) {
-    const patterns = IMPORT_PATTERNS.go;
-    let match;
-
-    let regex = new RegExp(patterns.importSingle.source, 'g');
-    while ((match = regex.exec(content)) !== null) {
-        const pkg = match[1];
-        imports.push({ module: pkg, names: [path.basename(pkg)], type: 'single' });
-    }
-
-    regex = new RegExp(patterns.importBlock.source, 'g');
-    while ((match = regex.exec(content)) !== null) {
-        const block = match[1];
-        const pkgMatches = block.matchAll(/"([^"]+)"/g);
-        for (const pkgMatch of pkgMatches) {
-            const pkg = pkgMatch[1];
-            imports.push({ module: pkg, names: [path.basename(pkg)], type: 'block' });
-        }
-    }
-}
-
-/** @deprecated Use AST-based findImportsInCode() from language modules. */
-function extractJavaImports(content, imports) {
-    const patterns = IMPORT_PATTERNS.java;
-    let match;
-
-    let regex = new RegExp(patterns.importStatement.source, 'g');
-    while ((match = regex.exec(content)) !== null) {
-        const fullImport = match[1];
-        const parts = fullImport.split('.');
-        const name = parts[parts.length - 1];
-        imports.push({ module: fullImport, names: name === '*' ? ['*'] : [name], type: 'import' });
-    }
-}
-
-/** @deprecated Use AST-based findImportsInCode() from language modules. */
-function extractRustImports(content, imports) {
-    const patterns = IMPORT_PATTERNS.rust;
-    let match;
-
-    let regex = new RegExp(patterns.useStatement.source, 'gm');
-    while ((match = regex.exec(content)) !== null) {
-        let raw = match[1].trim().split('{')[0].trim().split(' as ')[0].trim().replace(/::$/, '');
-        if (raw) {
-            imports.push({ module: raw, names: [], type: 'use' });
-        }
-    }
-
-    regex = new RegExp(patterns.modDecl.source, 'gm');
-    while ((match = regex.exec(content)) !== null) {
-        imports.push({ module: `self::${match[1]}`, names: [match[1]], type: 'mod' });
-    }
+    return { imports: [] };
 }
 
 /**
@@ -252,7 +43,6 @@ function extractExports(content, language) {
     // Normalize language name for parser
     const normalizedLang = (language === 'typescript' || language === 'tsx') ? 'javascript' : language;
 
-    // Try AST-based extraction first
     const langModule = getLanguageModule(normalizedLang);
     if (langModule && typeof langModule.findExportsInCode === 'function') {
         try {
@@ -262,123 +52,11 @@ function extractExports(content, language) {
                 return { exports: foundExports };
             }
         } catch (e) {
-            // Fall through to regex-based extraction
-        }
-    }
-
-    // Fallback to regex-based extraction (deprecated)
-    const foundExports = [];
-    if (language === 'javascript' || language === 'typescript' || language === 'tsx') {
-        extractJSExports(content, foundExports);
-    } else if (language === 'python') {
-        extractPythonExports(content, foundExports);
-    } else if (language === 'go') {
-        extractGoExports(content, foundExports);
-    } else if (language === 'java') {
-        extractJavaExports(content, foundExports);
-    }
-
-    return { exports: foundExports };
-}
-
-/** @deprecated Use AST-based findExportsInCode() from language modules. */
-function extractJSExports(content, exports) {
-    const patterns = IMPORT_PATTERNS.javascript;
-    let match;
-
-    let regex = new RegExp(patterns.exportNamed.source, 'gm');
-    while ((match = regex.exec(content)) !== null) {
-        exports.push({ name: match[1], type: 'named' });
-    }
-
-    regex = new RegExp(patterns.exportDefault.source, 'gm');
-    while ((match = regex.exec(content)) !== null) {
-        exports.push({ name: match[1] || 'default', type: 'default' });
-    }
-
-    regex = new RegExp(patterns.exportList.source, 'gm');
-    while ((match = regex.exec(content)) !== null) {
-        const names = match[1].split(',').map(n => n.trim().split(/\s+as\s+/)[0].trim()).filter(n => n);
-        for (const name of names) {
-            exports.push({ name, type: 'list' });
-        }
-    }
-
-    regex = new RegExp(patterns.exportsNamed.source, 'gm');
-    while ((match = regex.exec(content)) !== null) {
-        exports.push({ name: match[1], type: 'commonjs-named' });
-    }
-
-    // module.exports = { a, b, c } or module.exports = identifier
-    regex = new RegExp(patterns.moduleExports.source, 'gm');
-    while ((match = regex.exec(content)) !== null) {
-        if (match[1]) {
-            // Object literal: module.exports = { a, b, c }
-            const names = match[1].split(',').map(n => n.trim().split(/\s*:\s*/)[0].trim()).filter(n => n && !n.includes('('));
-            for (const name of names) {
-                exports.push({ name, type: 'commonjs-object' });
-            }
-        } else if (match[2]) {
-            // Single identifier: module.exports = SomeClass
-            exports.push({ name: match[2], type: 'commonjs-default' });
-        }
-    }
-}
-
-/** @deprecated Use AST-based findExportsInCode() from language modules. */
-function extractPythonExports(content, exports) {
-    let match;
-
-    // Check for __all__
-    let regex = new RegExp(IMPORT_PATTERNS.python.exportAll.source, 'g');
-    while ((match = regex.exec(content)) !== null) {
-        const names = match[1].split(',').map(n => n.trim().replace(/['"]/g, '')).filter(n => n);
-        for (const name of names) {
-            exports.push({ name, type: 'explicit' });
+            // AST parsing failed
         }
     }
 
-    // If no __all__, look for public names
-    if (exports.length === 0) {
-        const funcRegex = /^def\s+([a-zA-Z]\w*)\s*\(/gm;
-        while ((match = funcRegex.exec(content)) !== null) {
-            if (!match[1].startsWith('_')) {
-                exports.push({ name: match[1], type: 'function' });
-            }
-        }
-
-        const classRegex = /^class\s+([a-zA-Z]\w*)/gm;
-        while ((match = classRegex.exec(content)) !== null) {
-            if (!match[1].startsWith('_')) {
-                exports.push({ name: match[1], type: 'class' });
-            }
-        }
-    }
-}
-
-/** @deprecated Use AST-based findExportsInCode() from language modules. */
-function extractGoExports(content, exports) {
-    const patterns = IMPORT_PATTERNS.go;
-    let match;
-
-    let regex = new RegExp(patterns.exportedFunc.source, 'gm');
-    while ((match = regex.exec(content)) !== null) {
-        exports.push({ name: match[1], type: 'function' });
-    }
-
-    regex = new RegExp(patterns.exportedType.source, 'gm');
-    while ((match = regex.exec(content)) !== null) {
-        exports.push({ name: match[1], type: 'type' });
-    }
-}
-
-/** @deprecated Use AST-based findExportsInCode() from language modules. */
-function extractJavaExports(content, exports) {
-    let match;
-    let regex = new RegExp(IMPORT_PATTERNS.java.exportedClass.source, 'g');
-    while ((match = regex.exec(content)) !== null) {
-        exports.push({ name: match[1], type: 'class' });
-    }
+    return { exports: [] };
 }
 
 // Cache for tsconfig lookups
@@ -636,6 +314,5 @@ function stripJsonComments(content) {
 module.exports = {
     extractImports,
     extractExports,
-    resolveImport,
-    IMPORT_PATTERNS
+    resolveImport
 };

package/core/project.js

@@ -11,9 +11,15 @@ const crypto = require('crypto');
 const { expandGlob, findProjectRoot, detectProjectPattern, isTestFile } = require('./discovery');
 const { extractImports, extractExports, resolveImport } = require('./imports');
 const { parseFile } = require('./parser');
-const { detectLanguage, getParser, getLanguageModule, PARSE_OPTIONS } = require('../languages');
+const { detectLanguage, getParser, getLanguageModule, PARSE_OPTIONS, safeParse } = require('../languages');
 const { getTokenTypeAtPosition } = require('../languages/utils');
 
+// Read UCN version for cache invalidation
+const UCN_VERSION = require('../package.json').version;
+
+// Lazy-initialized per-language keyword sets (populated on first isKeyword call)
+let LANGUAGE_KEYWORDS = null;
+
 /**
  * Escape special regex characters
  */
@@ -413,25 +419,6 @@ class ProjectIndex {
         return withCounts;
     }
 
-    /**
-     * Count usages of a symbol across the codebase
-     */
-    countUsages(name) {
-        let count = 0;
-        const regex = new RegExp('\\b' + escapeRegExp(name) + '\\b', 'g');
-
-        for (const [filePath, fileEntry] of this.files) {
-            try {
-                const content = fs.readFileSync(filePath, 'utf-8');
-                const matches = content.match(regex);
-                if (matches) count += matches.length;
-            } catch (e) {
-                // Skip unreadable files
-            }
-        }
-
-        return count;
-    }
 
     /**
      * Count usages of a specific symbol (not just by name)
@@ -1004,7 +991,7 @@ class ProjectIndex {
                 }
 
                 // Skip keywords and built-ins
-                if (this.isKeyword(call.name)) continue;
+                if (this.isKeyword(call.name, language)) continue;
 
                 callees.set(call.name, (callees.get(call.name) || 0) + 1);
             }
@@ -1237,20 +1224,53 @@ class ProjectIndex {
     /**
      * Check if a name is a language keyword
      */
-    isKeyword(name) {
-        const keywords = new Set([
-            'if', 'else', 'for', 'while', 'do', 'switch', 'case', 'break',
-            'continue', 'return', 'function', 'class', 'const', 'let', 'var',
-            'new', 'this', 'super', 'import', 'export', 'default', 'from',
-            'try', 'catch', 'finally', 'throw', 'async', 'await', 'yield',
-            'typeof', 'instanceof', 'in', 'of', 'delete', 'void', 'with',
-            'def', 'print', 'range', 'len', 'str', 'int', 'float', 'list',
-            'dict', 'set', 'tuple', 'True', 'False', 'None', 'self', 'cls',
-            'func', 'type', 'struct', 'interface', 'package', 'make', 'append',
-            'fn', 'impl', 'pub', 'mod', 'use', 'crate', 'self', 'super',
-            'match', 'loop', 'unsafe', 'move', 'ref', 'mut', 'where'
-        ]);
-        return keywords.has(name);
+    isKeyword(name, language) {
+        if (!LANGUAGE_KEYWORDS) {
+            // Initialize on first use
+            LANGUAGE_KEYWORDS = {
+                javascript: new Set([
+                    'if', 'else', 'for', 'while', 'do', 'switch', 'case', 'break',
+                    'continue', 'return', 'function', 'class', 'const', 'let', 'var',
+                    'new', 'this', 'super', 'import', 'export', 'default', 'from',
+                    'try', 'catch', 'finally', 'throw', 'async', 'await', 'yield',
+                    'typeof', 'instanceof', 'in', 'of', 'delete', 'void', 'with'
+                ]),
+                python: new Set([
+                    'if', 'else', 'elif', 'for', 'while', 'def', 'class', 'return',
+                    'import', 'from', 'try', 'except', 'finally', 'raise', 'async',
+                    'await', 'yield', 'with', 'as', 'lambda', 'pass', 'break',
+                    'continue', 'del', 'global', 'nonlocal', 'assert', 'is', 'not',
+                    'and', 'or', 'in', 'True', 'False', 'None', 'self', 'cls'
+                ]),
+                go: new Set([
+                    'if', 'else', 'for', 'switch', 'case', 'break', 'continue',
+                    'return', 'func', 'type', 'struct', 'interface', 'package',
+                    'import', 'go', 'defer', 'select', 'chan', 'map', 'range',
+                    'fallthrough', 'goto', 'var', 'const', 'default'
+                ]),
+                rust: new Set([
+                    'if', 'else', 'for', 'while', 'loop', 'fn', 'impl', 'pub',
+                    'mod', 'use', 'crate', 'self', 'super', 'match', 'unsafe',
+                    'move', 'ref', 'mut', 'where', 'let', 'const', 'struct',
+                    'enum', 'trait', 'async', 'await', 'return', 'break',
+                    'continue', 'type', 'as', 'in', 'dyn', 'static'
+                ]),
+                java: new Set([
+                    'if', 'else', 'for', 'while', 'do', 'switch', 'case', 'break',
+                    'continue', 'return', 'class', 'interface', 'enum', 'extends',
+                    'implements', 'new', 'this', 'super', 'import', 'package',
+                    'try', 'catch', 'finally', 'throw', 'throws', 'abstract',
+                    'static', 'final', 'synchronized', 'volatile', 'transient',
+                    'native', 'void', 'instanceof', 'default'
+                ])
+            };
+            // TypeScript/TSX share JavaScript keywords
+            LANGUAGE_KEYWORDS.typescript = LANGUAGE_KEYWORDS.javascript;
+            LANGUAGE_KEYWORDS.tsx = LANGUAGE_KEYWORDS.javascript;
+        }
+
+        const keywords = LANGUAGE_KEYWORDS[language];
+        return keywords ? keywords.has(name) : false;
     }
 
     /**
@@ -2261,6 +2281,7 @@ class ProjectIndex {
                 ...analysis
             };
         });
+        this._clearTreeCache();
 
         // Group by file if requested
         const byFile = new Map();
@@ -2806,6 +2827,7 @@ class ProjectIndex {
                 }
             }
         }
+        this._clearTreeCache();
 
         return {
             found: true,
@@ -2829,87 +2851,89 @@ class ProjectIndex {
     }
 
     /**
-     * Analyze a call site to understand how it's being called
+     * Analyze a call site to understand how it's being called (AST-based)
+     * @param {object} call - Usage object with file, line, content
+     * @param {string} funcName - Function name to find
+     * @returns {object} { args, argCount, hasSpread, hasVariable }
      */
     analyzeCallSite(call, funcName) {
-        const content = call.content;
+        try {
+            const language = detectLanguage(call.file);
+            if (!language) return { args: null, argCount: 0 };
 
-        // Extract arguments from the call
-        const callMatch = new RegExp('\\b' + escapeRegExp(funcName) + '\\s*\\(([^)]*)\\)').exec(content);
-        if (!callMatch) {
-            return { args: null, argCount: 0 };
-        }
+            const parser = getParser(language);
+            if (!parser) return { args: null, argCount: 0 };
 
-        const argsStr = callMatch[1].trim();
-        if (!argsStr) {
-            return { args: [], argCount: 0 };
-        }
+            // Use tree cache to avoid re-parsing the same file in batch operations
+            let tree = this._treeCache?.get(call.file);
+            if (!tree) {
+                const content = fs.readFileSync(call.file, 'utf-8');
+                tree = safeParse(parser, content);
+                if (!tree) return { args: null, argCount: 0 };
+                if (!this._treeCache) this._treeCache = new Map();
+                this._treeCache.set(call.file, tree);
+            }
 
-        // Simple arg parsing (doesn't handle nested parens/strings perfectly but good enough)
-        const args = this.parseArguments(argsStr);
+            // Call node types vary by language
+            const callTypes = new Set(['call_expression', 'call', 'method_invocation']);
+            const targetRow = call.line - 1; // tree-sitter is 0-indexed
 
-        return {
-            args,
-            argCount: args.length,
-            hasSpread: args.some(a => a.startsWith('...')),
-            hasVariable: args.some(a => /^[a-zA-Z_]\w*$/.test(a))
-        };
-    }
+            // Find the call expression at the target line matching funcName
+            const callNode = this._findCallNode(tree.rootNode, callTypes, targetRow, funcName);
+            if (!callNode) return { args: null, argCount: 0 };
 
-    /**
-     * Parse function call arguments (simple version)
-     */
-    parseArguments(argsStr) {
-        const args = [];
-        let current = '';
-        let depth = 0;
-        let inString = false;
-        let stringChar = '';
-
-        for (let i = 0; i < argsStr.length; i++) {
-            const ch = argsStr[i];
-
-            if (inString) {
-                current += ch;
-                if (ch === stringChar && argsStr[i - 1] !== '\\') {
-                    inString = false;
-                }
-                continue;
-            }
+            const argsNode = callNode.childForFieldName('arguments');
+            if (!argsNode) return { args: [], argCount: 0 };
 
-            if (ch === '"' || ch === "'" || ch === '`') {
-                inString = true;
-                stringChar = ch;
-                current += ch;
-                continue;
+            const args = [];
+            for (let i = 0; i < argsNode.namedChildCount; i++) {
+                args.push(argsNode.namedChild(i).text.trim());
             }
 
-            if (ch === '(' || ch === '[' || ch === '{') {
-                depth++;
-                current += ch;
-                continue;
-            }
+            return {
+                args,
+                argCount: args.length,
+                hasSpread: args.some(a => a.startsWith('...')),
+                hasVariable: args.some(a => /^[a-zA-Z_]\w*$/.test(a))
+            };
+        } catch (e) {
+            return { args: null, argCount: 0 };
+        }
+    }
 
-            if (ch === ')' || ch === ']' || ch === '}') {
-                depth--;
-                current += ch;
-                continue;
-            }
+    /**
+     * Find a call expression node at the target line matching funcName
+     */
+    _findCallNode(node, callTypes, targetRow, funcName) {
+        if (node.startPosition.row > targetRow || node.endPosition.row < targetRow) {
+            return null; // Skip nodes that don't contain the target line
+        }
 
-            if (ch === ',' && depth === 0) {
-                args.push(current.trim());
-                current = '';
-                continue;
+        if (callTypes.has(node.type) && node.startPosition.row === targetRow) {
+            // Check if this call is for our target function
+            const funcNode = node.childForFieldName('function') ||
+                             node.childForFieldName('name'); // Java method_invocation uses 'name'
+            if (funcNode) {
+                const funcText = funcNode.type === 'member_expression' || funcNode.type === 'selector_expression' || funcNode.type === 'field_expression' || funcNode.type === 'attribute'
+                    ? (funcNode.childForFieldName('property') || funcNode.childForFieldName('field') || funcNode.childForFieldName('attribute') || funcNode.namedChild(funcNode.namedChildCount - 1))?.text
+                    : funcNode.text;
+                if (funcText === funcName) return node;
             }
-
-            current += ch;
         }
 
-        if (current.trim()) {
-            args.push(current.trim());
+        // Recurse into children
+        for (let i = 0; i < node.childCount; i++) {
+            const result = this._findCallNode(node.child(i), callTypes, targetRow, funcName);
+            if (result) return result;
         }
+        return null;
+    }
 
-        return args;
+    /**
+     * Clear the AST tree cache (call after batch operations)
+     */
+    _clearTreeCache() {
+        this._treeCache = null;
     }
 
     /**
@@ -3317,6 +3341,7 @@ class ProjectIndex {
 
         const cacheData = {
             version: 4,  // v4: className, memberType, isMethod for all languages
+            ucnVersion: UCN_VERSION,  // Invalidate cache when UCN is updated
             root: this.root,
             buildTime: this.buildTime,
             timestamp: Date.now(),
@@ -3356,6 +3381,11 @@ class ProjectIndex {
                 return false;
             }
 
+            // Invalidate cache when UCN version changes (logic may have changed)
+            if (cacheData.ucnVersion !== UCN_VERSION) {
+                return false;
+            }
+
             // Validate cache structure has required fields
             if (!Array.isArray(cacheData.files) ||
                 !Array.isArray(cacheData.symbols) ||

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucn",
-  "version": "3.1.7",
+  "version": "3.2.0",
   "description": "Code navigation built by AI, for AI. Reduces context usage when working with large codebases.",
   "main": "index.js",
   "bin": {