ucn 3.7.24 → 3.7.26

package/core/project.js

@@ -14,23 +14,16 @@ const { extractImports, extractExports, resolveImport } = require('./imports');
 const { parse, parseFile, cleanHtmlScriptTags } = require('./parser');
 const { detectLanguage, getParser, getLanguageModule, safeParse } = require('../languages');
 const { getTokenTypeAtPosition } = require('../languages/utils');
-
-// Read UCN version for cache invalidation
-const UCN_VERSION = require('../package.json').version;
+const { escapeRegExp, NON_CALLABLE_TYPES } = require('./shared');
+const stacktrace = require('./stacktrace');
+const indexCache = require('./cache');
+const deadcodeModule = require('./deadcode');
+const verifyModule = require('./verify');
+const callersModule = require('./callers');
 
 // Lazy-initialized per-language keyword sets (populated on first isKeyword call)
 let LANGUAGE_KEYWORDS = null;
 
-// Symbol types that are not callable (used to filter class/struct/type declarations from call analysis)
-const NON_CALLABLE_TYPES = new Set(['class', 'struct', 'interface', 'type', 'enum', 'trait', 'state', 'impl']);
-
-/**
- * Escape special regex characters
- */
-function escapeRegExp(text) {
-    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
 /**
  * ProjectIndex - Manages symbol table for a project
  */
@@ -50,8 +43,10 @@ class ProjectIndex {
         this.config = this.loadConfig();
         this.buildTime = null;
         this.callsCache = new Map();     // filePath -> { mtime, hash, calls, content }
+        this.callsCacheDirty = false;    // set by getCachedCalls when entries are added or mutated
         this.failedFiles = new Set();    // files that failed to index (e.g. large minified bundles)
         this._opContentCache = null;     // per-operation file content cache (Map<filePath, string>)
+        this._opUsagesCache = null;      // per-operation findUsagesInCode cache (Map<"file:name", usages[]>)
     }
 
     /**
@@ -70,16 +65,65 @@ class ProjectIndex {
         return fs.readFileSync(filePath, 'utf-8');
     }
 
-    /** Start a per-operation content cache scope */
+    /** Start a per-operation content cache scope (supports nesting) */
     _beginOp() {
         if (!this._opContentCache) {
             this._opContentCache = new Map();
+            this._opUsagesCache = new Map();
+            this._opDepth = 0;
         }
+        this._opDepth++;
     }
 
-    /** End a per-operation content cache scope */
+    /** End a per-operation content cache scope (only clears when outermost scope ends) */
     _endOp() {
-        this._opContentCache = null;
+        if (--this._opDepth <= 0) {
+            this._opContentCache = null;
+            this._opUsagesCache = null;
+            this._opDepth = 0;
+        }
+    }
+
+    /**
+     * Get findUsagesInCode results with per-operation caching.
+     * Avoids redundant tree-sitter parsing when the same (file, name) is queried
+     * multiple times within one operation (e.g., about() calls both countSymbolUsages and usages).
+     * @param {string} filePath - File to scan
+     * @param {string} name - Symbol name to find
+     * @returns {Array|null} Array of usage objects or null if parsing failed
+     */
+    _getCachedUsages(filePath, name) {
+        const cacheKey = `${filePath}\0${name}`;
+        if (this._opUsagesCache) {
+            const cached = this._opUsagesCache.get(cacheKey);
+            if (cached !== undefined) return cached;
+        }
+
+        const lang = detectLanguage(filePath);
+        const langModule = getLanguageModule(lang);
+        if (!langModule || typeof langModule.findUsagesInCode !== 'function') return null;
+
+        try {
+            // Fast pre-check: skip tree-sitter parsing if name doesn't appear in file
+            const content = this._readFile(filePath);
+            if (!content.includes(name)) {
+                const empty = [];
+                if (this._opUsagesCache) {
+                    this._opUsagesCache.set(cacheKey, empty);
+                }
+                return empty;
+            }
+
+            const parser = getParser(lang);
+            if (!parser) return null;
+            const usages = langModule.findUsagesInCode(content, name, parser);
+            if (this._opUsagesCache) {
+                this._opUsagesCache.set(cacheKey, usages);
+            }
+            return usages;
+        } catch (e) {
+            return null;
+        }
     }
 
     /**
@@ -144,8 +188,9 @@ class ProjectIndex {
             }
         }
 
-        // Always invalidate completeness cache on rebuild
+        // Always invalidate caches on rebuild
         this._completenessCache = null;
+        this._attrTypeCache = null;
 
         let indexed = 0;
         if (!this.failedFiles) this.failedFiles = new Set();
@@ -172,6 +217,19 @@ class ProjectIndex {
         }
     }
 
+    /**
+     * Build a minimal index for a single file (no glob, no cache, no import graph).
+     * Used by CLI file mode to route through execute().
+     */
+    buildSingleFile(filePath) {
+        const absPath = path.resolve(filePath);
+        if (!fs.existsSync(absPath)) {
+            throw new Error(`File not found: ${filePath}`);
+        }
+        this.indexFile(absPath);
+        this.buildTime = 0;
+    }
+
     /**
      * Index a single file
      */
@@ -314,6 +372,9 @@ class ProjectIndex {
 
         // Invalidate cached call data for this file
         this.callsCache.delete(filePath);
+
+        // Invalidate attribute type cache for this file
+        if (this._attrTypeCache) this._attrTypeCache.delete(filePath);
     }
 
     /**
@@ -556,9 +617,12 @@ class ProjectIndex {
             }
         }
 
-        // Check inclusion (must be within specified directory)
+        // Check inclusion (must be within specified directory, path-boundary-aware)
         if (filters.in) {
-            if (!filePath.includes(filters.in)) {
+            const inPattern = filters.in;
+            // Match at path boundaries: start of string or after /
+            // e.g. --in=src matches "src/foo.js" and "lib/src/foo.js" but NOT "my-src-backup/foo.js"
+            if (!(filePath.startsWith(inPattern + '/') || filePath.includes('/' + inPattern + '/'))) {
                 return false;
             }
         }
@@ -602,7 +666,7 @@ class ProjectIndex {
         if (lowerTarget.includes(lowerQuery)) return 400 + (query.length / target.length) * 100;
 
         // Word boundary match (parse -> parseFile, fileParse)
-        const words = lowerTarget.split(/(?=[A-Z])|_|-/);
+        const words = target.split(/(?=[A-Z])|_|-/).map(w => w.toLowerCase());
         if (words.some(w => w.startsWith(lowerQuery))) return 300;
 
         return 0;
@@ -690,9 +754,16 @@ class ProjectIndex {
     }
 
     find(name, options = {}) {
+        this._beginOp();
+        try {
         // Glob pattern matching (e.g., _update*, handle*Request, get?ata)
         const isGlob = name.includes('*') || name.includes('?');
         if (isGlob && !options.exact) {
+            // Guard against bare wildcards that would match everything
+            const stripped = name.replace(/[*?]/g, '');
+            if (stripped.length === 0) {
+                return [];
+            }
             const globRegex = new RegExp('^' + name.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.') + '$', 'i');
             const matches = [];
             for (const [symName, symbols] of this.symbols) {
@@ -725,6 +796,7 @@ class ProjectIndex {
         }
 
         return this._applyFindFilters(matches, options);
+        } finally { this._endOp(); }
     }
 
     /**
@@ -747,6 +819,11 @@ class ProjectIndex {
             );
         }
 
+        // Skip expensive usage counting when caller doesn't need it
+        if (options.skipCounts) {
+            return filtered;
+        }
+
         // Add per-symbol usage counts for disambiguation
         const withCounts = filtered.map(m => {
             const counts = this.countSymbolUsages(m);
@@ -806,38 +883,27 @@ class ProjectIndex {
             if (!this.files.has(filePath)) continue;
 
             try {
-                const content = this._readFile(filePath);
-
-                // Try AST-based counting first
-                const language = detectLanguage(filePath);
-                const langModule = getLanguageModule(language);
-
-                if (langModule && typeof langModule.findUsagesInCode === 'function') {
-                    try {
-                        const parser = getParser(language);
-                        if (parser) {
-                            const usages = langModule.findUsagesInCode(content, name, parser);
-                            // Deduplicate same-line same-type entries (e.g., `name: obj.name` has two AST nodes)
-                            const seen = new Set();
-                            for (const u of usages) {
-                                const key = `${filePath}:${u.line}:${u.usageType}`;
-                                if (seen.has(key)) continue;
-                                seen.add(key);
-                                switch (u.usageType) {
-                                    case 'call': calls++; break;
-                                    case 'definition': definitions++; break;
-                                    case 'import': imports++; break;
-                                    default: references++; break;
-                                }
-                            }
-                            continue; // Skip to next file
+                // Try AST-based counting first (with per-operation cache)
+                const astUsages = this._getCachedUsages(filePath, name);
+                if (astUsages !== null) {
+                    // Deduplicate same-line same-type entries (e.g., `name: obj.name` has two AST nodes)
+                    const seen = new Set();
+                    for (const u of astUsages) {
+                        const key = `${filePath}:${u.line}:${u.usageType}`;
+                        if (seen.has(key)) continue;
+                        seen.add(key);
+                        switch (u.usageType) {
+                            case 'call': calls++; break;
+                            case 'definition': definitions++; break;
+                            case 'import': imports++; break;
+                            default: references++; break;
                         }
-                    } catch (e) {
-                        // Fall through to regex-based counting
                     }
+                    continue; // Skip to next file
                 }
 
                 // Fallback: count regex matches as references (unsupported language)
+                const content = this._readFile(filePath);
                 const lines = content.split('\n');
                 lines.forEach((line) => {
                     if (regex.test(line)) {
@@ -895,56 +961,48 @@ class ProjectIndex {
 
             try {
                 const content = this._readFile(filePath);
-                const lines = content.split('\n');
 
-                // Try AST-based detection first
-                const lang = detectLanguage(filePath);
-                const langModule = getLanguageModule(lang);
+                // Fast pre-check: skip if name doesn't appear in file at all
+                if (!content.includes(name)) continue;
 
-                if (langModule && typeof langModule.findUsagesInCode === 'function') {
-                    // AST-based detection
-                    try {
-                        const parser = getParser(lang);
-                        if (parser) {
-                            const astUsages = langModule.findUsagesInCode(content, name, parser);
-
-                            for (const u of astUsages) {
-                                // Skip if this is a definition line (already added above)
-                                if (definitions.some(d => d.file === filePath && d.startLine === u.line)) {
-                                    continue;
-                                }
+                const lines = content.split('\n');
 
-                                const lineContent = lines[u.line - 1] || '';
+                // Try AST-based detection first (with per-operation cache)
+                const astUsages = this._getCachedUsages(filePath, name);
+                if (astUsages !== null) {
+                    for (const u of astUsages) {
+                        // Skip if this is a definition line (already added above)
+                        if (definitions.some(d => d.file === filePath && d.startLine === u.line)) {
+                            continue;
+                        }
 
-                                const usage = {
-                                    file: filePath,
-                                    relativePath: fileEntry.relativePath,
-                                    line: u.line,
-                                    content: lineContent,
-                                    usageType: u.usageType,
-                                    isDefinition: false
-                                };
+                        const lineContent = lines[u.line - 1] || '';
 
-                                // Add context lines if requested
-                                if (options.context && options.context > 0) {
-                                    const idx = u.line - 1;
-                                    const before = [];
-                                    const after = [];
-                                    for (let i = 1; i <= options.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;
-                                }
+                        const usage = {
+                            file: filePath,
+                            relativePath: fileEntry.relativePath,
+                            line: u.line,
+                            content: lineContent,
+                            usageType: u.usageType,
+                            isDefinition: false
+                        };
 
-                                usages.push(usage);
+                        // Add context lines if requested
+                        if (options.context && options.context > 0) {
+                            const idx = u.line - 1;
+                            const before = [];
+                            const after = [];
+                            for (let i = 1; i <= options.context; i++) {
+                                if (idx - i >= 0) before.unshift(lines[idx - i]);
+                                if (idx + i < lines.length) after.push(lines[idx + i]);
                             }
-                            continue; // Skip to next file
+                            usage.before = before;
+                            usage.after = after;
                         }
-                    } catch (e) {
-                        // Fall through to regex-based detection
+
+                        usages.push(usage);
                     }
+                    continue; // Skip to next file
                 }
 
                 // Fallback to regex-based detection
@@ -1037,7 +1095,8 @@ class ProjectIndex {
                 }
 
                 // Check Go/Rust-style receiver (e.g., func (r *Router) Method())
-                if (symbol.isMethod && symbol.receiver) {
+                // Also matches Rust associated functions (have receiver but isMethod=false)
+                if (symbol.receiver) {
                     const receiverBase = symbol.receiver.replace(/^\*/, '');
                     if (receiverBase === baseTypeName) {
                         methods.push(symbol);
@@ -1080,6 +1139,12 @@ class ProjectIndex {
         if (['class', 'struct', 'interface', 'type'].includes(def.type)) {
             const methods = this.findMethodsForType(name);
 
+            let typeCallers = this.findCallers(name, { includeMethods: options.includeMethods, includeUncertain: options.includeUncertain });
+            // Apply exclude filter
+            if (options.exclude && options.exclude.length > 0) {
+                typeCallers = typeCallers.filter(c => this.matchesFilters(c.relativePath, { exclude: options.exclude }));
+            }
+
             const result = {
                 type: def.type,
                 name: name,
@@ -1095,7 +1160,7 @@ class ProjectIndex {
                     receiver: m.receiver
                 })),
                 // Also include places where the type is used in function parameters/returns
-                callers: this.findCallers(name, { includeMethods: options.includeMethods, includeUncertain: options.includeUncertain })
+                callers: typeCallers
             };
 
             if (warnings.length > 0) {
@@ -1154,343 +1219,11 @@ class ProjectIndex {
         } finally { this._endOp(); }
     }
 
-    /**
-     * Get cached calls for a file, parsing if necessary
-     * Uses mtime for fast cache validation, falls back to hash if mtime matches but content changed
-     * @param {string} filePath - Path to the file
-     * @param {object} [options] - Options
-     * @param {boolean} [options.includeContent] - Also return file content (avoids double read)
-     * @returns {Array|null|{calls: Array, content: string}} Array of calls, or object with content if requested
-     */
-    getCachedCalls(filePath, options = {}) {
-        try {
-            const cached = this.callsCache.get(filePath);
-
-            // Fast path: check mtime first (stat is much faster than read+hash)
-            const stat = fs.statSync(filePath);
-            const mtime = stat.mtimeMs;
-
-            if (cached && cached.mtime === mtime) {
-                // mtime matches - cache is likely valid
-                if (options.includeContent) {
-                    // Need content, read if not cached
-                    const content = cached.content || this._readFile(filePath);
-                    return { calls: cached.calls, content };
-                }
-                return cached.calls;
-            }
-
-            // mtime changed or no cache - need to read and possibly reparse
-            const content = this._readFile(filePath);
-            const hash = crypto.createHash('md5').update(content).digest('hex');
-
-            // Check if content actually changed (mtime can change without content change)
-            if (cached && cached.hash === hash) {
-                // Content unchanged, just update mtime
-                cached.mtime = mtime;
-                cached.content = options.includeContent ? content : undefined;
-                if (options.includeContent) {
-                    return { calls: cached.calls, content };
-                }
-                return cached.calls;
-            }
-
-            // Content changed - need to reparse
-            const language = detectLanguage(filePath);
-            if (!language) return null;
-
-            const langModule = getLanguageModule(language);
-            if (!langModule.findCallsInCode) return null;
-
-            const parser = getParser(language);
-            const calls = langModule.findCallsInCode(content, parser);
-
-            this.callsCache.set(filePath, {
-                mtime,
-                hash,
-                calls,
-                content: options.includeContent ? content : undefined
-            });
-
-            if (options.includeContent) {
-                return { calls, content };
-            }
-            return calls;
-        } catch (e) {
-            return null;
-        }
-    }
-
-    /**
-     * Find all callers of a function using AST-based detection
-     * @param {string} name - Function name to find callers for
-     * @param {object} [options] - Options
-     * @param {boolean} [options.includeMethods] - Include method calls (default: false)
-     */
-    findCallers(name, options = {}) {
-        this._beginOp();
-        try {
-        const callers = [];
-        const stats = options.stats;
-
-        // Get definition lines to exclude them
-        const definitions = this.symbols.get(name) || [];
-        const definitionLines = new Set();
-        for (const def of definitions) {
-            definitionLines.add(`${def.file}:${def.startLine}`);
-        }
-
-        for (const [filePath, fileEntry] of this.files) {
-            try {
-                const result = this.getCachedCalls(filePath, { includeContent: true });
-                if (!result) continue;
-
-                const { calls, content } = result;
-                const lines = content.split('\n');
-
-                for (const call of calls) {
-                    // Skip if not matching our target name (also check alias resolution)
-                    if (call.name !== name && call.resolvedName !== name &&
-                        !(call.resolvedNames && call.resolvedNames.includes(name))) continue;
-
-                    // For potential callbacks (function passed as arg), validate against symbol table
-                    // and skip complex binding resolution — just check the name exists
-                    if (call.isPotentialCallback) {
-                        const syms = definitions;
-                        if (!syms || syms.length === 0) continue;
-                        // Find the enclosing function
-                        const callerSymbol = this.findEnclosingFunction(filePath, call.line, true);
-                        callers.push({
-                            file: filePath,
-                            relativePath: fileEntry.relativePath,
-                            line: call.line,
-                            content: lines[call.line - 1] || '',
-                            callerName: callerSymbol ? callerSymbol.name : null,
-                            callerFile: callerSymbol ? filePath : null,
-                            callerStartLine: callerSymbol ? callerSymbol.startLine : null,
-                            callerEndLine: callerSymbol ? callerSymbol.endLine : null,
-                            isMethod: false,
-                            isFunctionReference: true
-                        });
-                        continue;
-                    }
-
-                    // Resolve binding within this file (without mutating cached call objects)
-                    let bindingId = call.bindingId;
-                    let isUncertain = call.uncertain;
-                    if (!bindingId) {
-                        let bindings = (fileEntry.bindings || []).filter(b => b.name === call.name);
-                        // For Go, also check sibling files in same directory (same package scope)
-                        if (bindings.length === 0 && fileEntry.language === 'go') {
-                            const dir = path.dirname(filePath);
-                            for (const [fp, fe] of this.files) {
-                                if (fp !== filePath && path.dirname(fp) === dir) {
-                                    const sibling = (fe.bindings || []).filter(b => b.name === call.name);
-                                    bindings = bindings.concat(sibling);
-                                }
-                            }
-                        }
-                        if (bindings.length === 1) {
-                            bindingId = bindings[0].id;
-                        } else if (bindings.length > 1 && !call.isMethod) {
-                            // For implicit same-class calls (Java: execute() means this.execute()),
-                            // try to resolve via caller's className before marking uncertain
-                            const callerSym = this.findEnclosingFunction(filePath, call.line, true);
-                            if (callerSym?.className) {
-                                const callSymbols = this.symbols.get(call.name);
-                                const sameClassSym = callSymbols?.find(s => s.className === callerSym.className);
-                                if (sameClassSym) {
-                                    const matchingBinding = bindings.find(b => b.startLine === sameClassSym.startLine);
-                                    bindingId = matchingBinding?.id || sameClassSym.bindingId;
-                                } else {
-                                    isUncertain = true;
-                                }
-                            } else {
-                                // Scope-based disambiguation for shadowed functions:
-                                // When multiple bindings exist, use indent level to determine
-                                // which binding is in scope at the call site
-                                const defs = this.symbols.get(call.name);
-                                let resolved = false;
-                                if (defs) {
-                                    // Sort bindings by indent desc (most nested first)
-                                    const scopedBindings = bindings.map(b => {
-                                        const sym = defs.find(s => s.startLine === b.startLine && s.file === filePath);
-                                        return { ...b, indent: sym?.indent ?? 0, endLine: sym?.endLine ?? b.startLine };
-                                    }).sort((a, b) => b.indent - a.indent);
-
-                                    for (const sb of scopedBindings) {
-                                        if (sb.indent === 0) {
-                                            // Module-level binding — always in scope, use as fallback
-                                            bindingId = sb.id;
-                                            resolved = true;
-                                            break;
-                                        }
-                                        // Nested binding — check if call is inside its enclosing function
-                                        const enclosing = this.findEnclosingFunction(filePath, sb.startLine, true);
-                                        if (enclosing && call.line >= enclosing.startLine && call.line <= enclosing.endLine) {
-                                            // Call is inside the same function as this binding
-                                            bindingId = sb.id;
-                                            resolved = true;
-                                            break;
-                                        }
-                                    }
-                                }
-                                if (!resolved) isUncertain = true;
-                            }
-                        } else if (bindings.length > 1 && call.isMethod) {
-                            // Multiple method bindings (e.g. Go String() on Reader vs Writer):
-                            // Don't mark uncertain — include them even if conflated.
-                            // Better to over-report than lose all callers.
-                        } else if (bindings.length !== 0) {
-                            isUncertain = true;
-                        }
-                        // Method call with no binding for the method name (JS/TS/Python only):
-                        // Mark uncertain unless receiver has binding evidence in file scope.
-                        // Go/Java/Rust excluded: callers are used for impact analysis where
-                        // over-reporting is preferred to losing callers. These languages' nominal
-                        // type systems also make method links more reliable.
-                        if (bindings.length === 0 && call.isMethod &&
-                            fileEntry.language !== 'go' && fileEntry.language !== 'java' && fileEntry.language !== 'rust') {
-                            const hasReceiverEvidence = call.receiver &&
-                                (fileEntry.bindings || []).some(b => b.name === call.receiver);
-                            if (!hasReceiverEvidence) {
-                                isUncertain = true;
-                            }
-                        }
-                    }
-
-                    // Smart method call handling — do this BEFORE uncertain check so
-                    // self/this.method() calls can be resolved by same-class matching
-                    // even when binding is ambiguous (e.g. method exists in multiple classes)
-                    let resolvedBySameClass = false;
-                    if (call.isMethod) {
-                        if (call.selfAttribute && fileEntry.language === 'python') {
-                            // self.attr.method() — resolve via attribute type inference
-                            const callerSymbol = this.findEnclosingFunction(filePath, call.line, true);
-                            if (!callerSymbol?.className) continue;
-                            const attrTypes = this.getInstanceAttributeTypes(filePath, callerSymbol.className);
-                            if (!attrTypes) continue;
-                            const targetClass = attrTypes.get(call.selfAttribute);
-                            if (!targetClass) continue;
-                            // Check if any definition of searched function belongs to targetClass
-                            const matchesDef = definitions.some(d => d.className === targetClass);
-                            if (!matchesDef) continue;
-                            resolvedBySameClass = true;
-                            // Falls through to add as caller
-                        } else if (['self', 'cls', 'this', 'super'].includes(call.receiver)) {
-                            // self/this/super.method() — resolve to same-class or parent method
-                            const callerSymbol = this.findEnclosingFunction(filePath, call.line, true);
-                            if (!callerSymbol?.className) continue;
-                            // For super(), skip same-class — only check parent chain
-                            let matchesDef = call.receiver === 'super'
-                                ? false
-                                : definitions.some(d => d.className === callerSymbol.className);
-                            // Walk inheritance chain using BFS if not found in same class
-                            if (!matchesDef) {
-                                const visited = new Set([callerSymbol.className]);
-                                const callerFile = callerSymbol.file || filePath;
-                                const startParents = this._getInheritanceParents(callerSymbol.className, callerFile) || [];
-                                const queue = startParents.map(p => ({ name: p, contextFile: callerFile }));
-                                while (queue.length > 0 && !matchesDef) {
-                                    const { name: current, contextFile } = queue.shift();
-                                    if (visited.has(current)) continue;
-                                    visited.add(current);
-                                    matchesDef = definitions.some(d => d.className === current);
-                                    if (!matchesDef) {
-                                        const resolvedFile = this._resolveClassFile(current, contextFile);
-                                        const grandparents = this._getInheritanceParents(current, resolvedFile) || [];
-                                        for (const gp of grandparents) {
-                                            if (!visited.has(gp)) queue.push({ name: gp, contextFile: resolvedFile });
-                                        }
-                                    }
-                                }
-                            }
-                            if (!matchesDef) continue;
-                            resolvedBySameClass = true;
-                            // Falls through to add as caller
-                        } else {
-                            // Go doesn't use this/self/cls - always include Go method calls
-                            // Java method calls are always obj.method() - include by default
-                            // Rust Type::method() calls - include by default (associated functions)
-                            // For other languages, skip method calls unless explicitly requested
-                            if (fileEntry.language !== 'go' && fileEntry.language !== 'java' && fileEntry.language !== 'rust' && !options.includeMethods) continue;
-                        }
-                    }
-
-                    // Skip uncertain calls unless resolved by same-class matching or explicitly requested
-                    if (isUncertain && !resolvedBySameClass && !options.includeUncertain) {
-                        if (stats) stats.uncertain = (stats.uncertain || 0) + 1;
-                        continue;
-                    }
-
-                    // Skip definition lines
-                    if (definitionLines.has(`${filePath}:${call.line}`)) continue;
-
-                    // If we have a binding id on definition, require match when available
-                    // When targetDefinitions is provided, only those definitions' bindings are valid targets
-                    const targetDefs = options.targetDefinitions || definitions;
-                    const targetBindingIds = new Set(targetDefs.map(d => d.bindingId).filter(Boolean));
-                    if (targetBindingIds.size > 0 && bindingId && !targetBindingIds.has(bindingId)) {
-                        continue;
-                    }
-
-                    // Java/Go/Rust receiver-class disambiguation:
-                    // When targetDefinitions narrows to specific class(es) and the call has a
-                    // receiver (e.g. javascriptFileService.createDataFile()), check if the
-                    // receiver name better matches a non-target class definition.
-                    // This prevents false positives like reporting obj.save() as a caller of
-                    // TargetClass.save() when obj is clearly a different type.
-                    if (call.isMethod && call.receiver && !resolvedBySameClass && !bindingId &&
-                        options.targetDefinitions && definitions.length > 1 &&
-                        (fileEntry.language === 'java' || fileEntry.language === 'go' || fileEntry.language === 'rust')) {
-                        const targetClassNames = new Set(targetDefs.map(d => d.className).filter(Boolean));
-                        if (targetClassNames.size > 0) {
-                            const receiverLower = call.receiver.toLowerCase();
-                            // Check if receiver matches any target class (camelCase convention)
-                            const matchesTarget = [...targetClassNames].some(cn => cn.toLowerCase() === receiverLower);
-                            if (!matchesTarget) {
-                                // Check if receiver matches a non-target class instead
-                                const nonTargetClasses = definitions
-                                    .filter(d => d.className && !targetClassNames.has(d.className))
-                                    .map(d => d.className);
-                                const matchesOther = nonTargetClasses.some(cn => cn.toLowerCase() === receiverLower);
-                                if (matchesOther) {
-                                    // Receiver clearly belongs to a different class
-                                    isUncertain = true;
-                                    if (!options.includeUncertain) {
-                                        if (stats) stats.uncertain = (stats.uncertain || 0) + 1;
-                                        continue;
-                                    }
-                                }
-                            }
-                        }
-                    }
-
-                    // Find the enclosing function (get full symbol info)
-                    const callerSymbol = this.findEnclosingFunction(filePath, call.line, true);
-
-                    callers.push({
-                        file: filePath,
-                        relativePath: fileEntry.relativePath,
-                        line: call.line,
-                        content: lines[call.line - 1] || '',
-                        callerName: callerSymbol ? callerSymbol.name : null,
-                        callerFile: callerSymbol ? filePath : null,
-                        callerStartLine: callerSymbol ? callerSymbol.startLine : null,
-                        callerEndLine: callerSymbol ? callerSymbol.endLine : null,
-                        isMethod: call.isMethod || false,
-                        receiver: call.receiver
-                    });
-                }
-            } catch (e) {
-                // Expected: minified files exceed tree-sitter buffer, binary files fail to parse.
-                // These are not actionable errors — silently skip.
-            }
-        }
+    /** Get cached call sites for a file, with mtime/hash validation */
+    getCachedCalls(filePath, options) { return callersModule.getCachedCalls(this, filePath, options); }
 
-        return callers;
-        } finally { this._endOp(); }
-    }
+    /** Find all callers of a function using AST-based detection */
+    findCallers(name, options) { return callersModule.findCallers(this, name, options); }
 
     /**
      * Check if a name appears inside a string literal using AST
@@ -1537,481 +1270,91 @@ class ProjectIndex {
         }
     }
 
+    /** Find all functions called by a function using AST-based detection */
+    findCallees(def, options) { return callersModule.findCallees(this, def, options); }
+
+    /**
+     * Calculate dependency weight based on usage
+     */
+    calculateWeight(callCount) {
+        if (callCount >= 10) return 'core';
+        if (callCount >= 3) return 'regular';
+        if (callCount === 1) return 'utility';
+        return 'normal';
+    }
+
     /**
-     * Find all functions called by a function using AST-based detection
-     * @param {object} def - Symbol definition with file, name, startLine, endLine
-     * @param {object} [options] - Options
-     * @param {boolean} [options.includeMethods] - Include method calls (default: false)
+     * Smart extraction: function + dependencies
      */
-    findCallees(def, options = {}) {
+    smart(name, options = {}) {
         this._beginOp();
         try {
-        try {
-            // Get all calls from the file's cache (now includes enclosingFunction)
-            const calls = this.getCachedCalls(def.file);
-            if (!calls) return [];
-
-            // Get file language for smart method call handling
-            const fileEntry = this.files.get(def.file);
-            const language = fileEntry?.language;
-
-            // Build list of inner class/struct method ranges to exclude from callee detection.
-            // Only class methods are excluded — they are independently addressable symbols.
-            // Calls within closures (named functions without className) ARE included as
-            // callees of the parent function, since closures are part of the parent's behavior.
-            const innerSymbolRanges = fileEntry ? fileEntry.symbols
-                .filter(s => !NON_CALLABLE_TYPES.has(s.type) &&
-                        s.className &&  // Only exclude class methods, not closures
-                        s.startLine > def.startLine && s.endLine <= def.endLine &&
-                        s.startLine !== def.startLine)
-                .map(s => [s.startLine, s.endLine]) : [];
-
-            const callees = new Map();  // key -> { name, bindingId, count }
-            let selfAttrCalls = null;   // collected for Python self.attr.method() resolution
-            let selfMethodCalls = null; // collected for Python self.method() resolution
-
-            for (const call of calls) {
-                // Filter to calls within this function's scope
-                // Method 1: Direct match via enclosingFunction (fast path for direct calls)
-                const isDirectMatch = call.enclosingFunction &&
-                    call.enclosingFunction.startLine === def.startLine;
-                // Method 2: Line-range containment (catches calls inside nested callbacks/closures)
-                // A call is in our scope if it's within our line range AND not inside a named inner symbol
-                const isInRange = call.line >= def.startLine && call.line <= def.endLine;
-                const isInInnerSymbol = isInRange && innerSymbolRanges.some(
-                    ([start, end]) => call.line >= start && call.line <= end);
-                const isNestedCallback = isInRange && !isInInnerSymbol && !isDirectMatch;
-
-                if (!isDirectMatch && !isNestedCallback) continue;
-
-                // Smart method call handling:
-                // - Go: include all method calls (Go doesn't use this/self/cls)
-                // - self/this.method(): resolve to same-class method (handled below)
-                // - Python self.attr.method(): resolve via selfAttribute (handled below)
-                // - Other languages: skip method calls unless explicitly requested
-                if (call.isMethod) {
-                    if (call.selfAttribute && language === 'python') {
-                        // Will be resolved in second pass below
-                    } else if (['self', 'cls', 'this'].includes(call.receiver)) {
-                        // self.method() / cls.method() / this.method() — resolve to same-class method below
-                    } else if (call.receiver === 'super') {
-                        // super().method() — resolve to parent class method below
-                    } else if (language !== 'go' && language !== 'java' && language !== 'rust' && !options.includeMethods) {
-                        continue;
-                    }
-                }
+        const { def } = this.resolveSymbol(name, { file: options.file });
+        if (!def) {
+            return null;
+        }
+        const code = this.extractCode(def);
+        const stats = { uncertain: 0 };
+        const callees = this.findCallees(def, { includeMethods: options.includeMethods, includeUncertain: options.includeUncertain, stats });
 
-                // Skip keywords and built-ins
-                if (this.isKeyword(call.name, language)) continue;
+        const filesInScope = new Set([def.file]);
+        callees.forEach(c => filesInScope.add(c.file));
+        let dynamicImports = 0;
+        for (const f of filesInScope) {
+            const fe = this.files.get(f);
+            if (fe?.dynamicImports) dynamicImports += fe.dynamicImports;
+        }
 
-                // Use resolved name (from alias tracking) if available
-                // For multi-target aliases (ternary), pick the first that exists in symbol table
-                let effectiveName = call.resolvedName || call.name;
-                if (call.resolvedNames) {
-                    for (const rn of call.resolvedNames) {
-                        if (this.symbols.has(rn)) { effectiveName = rn; break; }
-                    }
-                }
+        // Extract code for each dependency, excluding the exact same function
+        // (but keeping same-name overloads, e.g. Java toJson(Object) vs toJson(Object, Class))
+        const defBindingId = def.bindingId;
+        const dependencies = callees
+            .filter(callee => callee.bindingId !== defBindingId)
+            .map(callee => ({
+                ...callee,
+                code: this.extractCode(callee)
+            }));
 
-                // For potential callbacks (identifier args to non-HOF calls),
-                // only include if name exists as a function in symbol table
-                // AND has binding/import evidence or same-file definition.
-                // Prevents local variables (request, context) from matching
-                // unrelated functions defined elsewhere (especially test files).
-                if (call.isPotentialCallback) {
-                    const syms = this.symbols.get(effectiveName);
-                    if (!syms || !syms.some(s =>
-                        ['function', 'method', 'constructor', 'static', 'public', 'abstract'].includes(s.type))) {
-                        continue;
-                    }
-                    const hasBinding = fileEntry?.bindings?.some(b => b.name === call.name);
-                    const inSameFile = syms.some(s => s.file === def.file);
-                    if (!hasBinding && !inSameFile) {
-                        continue;
+        // Find type definitions if requested
+        const types = [];
+        if (options.withTypes) {
+            // Look for type annotations in params/return type
+            const typeNames = this.extractTypeNames(def);
+            for (const typeName of typeNames) {
+                const typeSymbols = this.symbols.get(typeName);
+                if (typeSymbols) {
+                    for (const sym of typeSymbols) {
+                        if (['type', 'interface', 'class', 'struct'].includes(sym.type)) {
+                            types.push({
+                                ...sym,
+                                code: this.extractCode(sym)
+                            });
+                        }
                     }
                 }
+            }
+        }
 
-                // Collect selfAttribute calls for second-pass resolution
-                if (call.selfAttribute && language === 'python') {
-                    if (!selfAttrCalls) selfAttrCalls = [];
-                    selfAttrCalls.push(call);
-                    continue;
-                }
-
-                // Collect self/this.method() calls for same-class resolution
-                if (call.isMethod && ['self', 'cls', 'this'].includes(call.receiver)) {
-                    if (!selfMethodCalls) selfMethodCalls = [];
-                    selfMethodCalls.push(call);
-                    continue;
-                }
+        return {
+            target: {
+                ...def,
+                code
+            },
+            dependencies,
+            types,
+            meta: {
+                complete: stats.uncertain === 0 && dynamicImports === 0,
+                skipped: 0,
+                dynamicImports,
+                uncertain: stats.uncertain
+            }
+        };
+        } finally { this._endOp(); }
+    }
 
-                // Collect super().method() calls for parent-class resolution
-                if (call.isMethod && call.receiver === 'super') {
-                    if (!selfMethodCalls) selfMethodCalls = [];
-                    selfMethodCalls.push(call);
-                    continue;
-                }
-
-                // Resolve binding within this file (without mutating cached call objects)
-                let calleeKey = call.bindingId || effectiveName;
-                let bindingResolved = call.bindingId;
-                let isUncertain = call.uncertain;
-                if (!call.bindingId && fileEntry?.bindings) {
-                    let bindings = fileEntry.bindings.filter(b => b.name === call.name);
-                    // For Go, also check sibling files in same directory (same package scope)
-                    if (bindings.length === 0 && language === 'go') {
-                        const dir = path.dirname(def.file);
-                        for (const [fp, fe] of this.files) {
-                            if (fp !== def.file && path.dirname(fp) === dir) {
-                                const sibling = (fe.bindings || []).filter(b => b.name === call.name);
-                                bindings = bindings.concat(sibling);
-                            }
-                        }
-                    }
-                    // Method call with no binding for the method name:
-                    // Different strategies by language family:
-                    if (bindings.length === 0 && call.isMethod) {
-                        if (language !== 'go' && language !== 'java' && language !== 'rust') {
-                            // JS/TS/Python: mark uncertain unless receiver has import/binding
-                            // evidence in file scope. Prevents false positives like m.get() →
-                            // repository.get() when m is just a parameter with no type info.
-                            const hasReceiverEvidence = call.receiver &&
-                                fileEntry?.bindings?.some(b => b.name === call.receiver);
-                            if (!hasReceiverEvidence) {
-                                isUncertain = true;
-                            }
-                        } else {
-                            // Go/Java/Rust: nominal type systems make single-def method links
-                            // reliable. Only mark uncertain when multiple definitions exist
-                            // (cross-type ambiguity, e.g. TypeA.Length vs TypeB.Length).
-                            const defs = this.symbols.get(call.name);
-                            if (defs && defs.length > 1) {
-                                isUncertain = true;
-                            }
-                        }
-                    }
-                    if (bindings.length === 1) {
-                        bindingResolved = bindings[0].id;
-                        calleeKey = bindingResolved;
-                    } else if (bindings.length > 1) {
-                        if (call.name === def.name) {
-                            // Calling same-name function (e.g., Java overloads)
-                            // Add ALL other overloads as potential callees
-                            const otherBindings = bindings.filter(b =>
-                                b.startLine !== def.startLine
-                            );
-                            for (const ob of otherBindings) {
-                                const existing = callees.get(ob.id);
-                                if (existing) {
-                                    existing.count += 1;
-                                } else {
-                                    callees.set(ob.id, {
-                                        name: effectiveName,
-                                        bindingId: ob.id,
-                                        count: 1
-                                    });
-                                }
-                            }
-                            continue; // Already added all overloads, skip normal add
-                        } else if (def.className && !call.isMethod) {
-                            // Implicit same-class call (Java: execute() means this.execute())
-                            // Try to resolve to a binding in the same class via symbol lookup
-                            const callSymbols = this.symbols.get(call.name);
-                            if (callSymbols) {
-                                const sameClassSym = callSymbols.find(s => s.className === def.className);
-                                if (sameClassSym) {
-                                    // Find the binding that matches this symbol's line
-                                    const matchingBinding = bindings.find(b => b.startLine === sameClassSym.startLine);
-                                    if (matchingBinding) {
-                                        bindingResolved = matchingBinding.id;
-                                        calleeKey = bindingResolved;
-                                    } else {
-                                        bindingResolved = sameClassSym.bindingId;
-                                        calleeKey = bindingResolved || `${def.className}.${call.name}`;
-                                    }
-                                } else {
-                                    isUncertain = true;
-                                }
-                            } else {
-                                isUncertain = true;
-                            }
-                        } else {
-                            // Try to resolve to a binding defined within the parent function's
-                            // scope (inner closure). E.g., hookRunnerApplication defines next()
-                            // internally — prefer that over other next() in the same file.
-                            const innerBinding = bindings.find(b =>
-                                b.startLine > def.startLine && b.startLine <= def.endLine);
-                            if (innerBinding) {
-                                bindingResolved = innerBinding.id;
-                                calleeKey = bindingResolved;
-                            } else {
-                                isUncertain = true;
-                            }
-                        }
-                    }
-                }
-
-                if (isUncertain && !options.includeUncertain) {
-                    if (options.stats) options.stats.uncertain = (options.stats.uncertain || 0) + 1;
-                    continue;
-                }
-
-                const existing = callees.get(calleeKey);
-                if (existing) {
-                    existing.count += 1;
-                } else {
-                    callees.set(calleeKey, {
-                        name: effectiveName,
-                        bindingId: bindingResolved,
-                        count: 1
-                    });
-                }
-            }
-
-            // Second pass: resolve Python self.attr.method() calls
-            if (selfAttrCalls && def.className) {
-                const attrTypes = this.getInstanceAttributeTypes(def.file, def.className);
-                if (attrTypes) {
-                    for (const call of selfAttrCalls) {
-                        const targetClass = attrTypes.get(call.selfAttribute);
-                        if (!targetClass) continue;
-
-                        // Find method in symbol table where className matches
-                        const symbols = this.symbols.get(call.name);
-                        if (!symbols) continue;
-
-                        const match = symbols.find(s => s.className === targetClass);
-                        if (!match) continue;
-
-                        const key = match.bindingId || `${targetClass}.${call.name}`;
-                        const existing = callees.get(key);
-                        if (existing) {
-                            existing.count += 1;
-                        } else {
-                            callees.set(key, {
-                                name: call.name,
-                                bindingId: match.bindingId,
-                                count: 1
-                            });
-                        }
-                    }
-                }
-            }
-
-            // Third pass: resolve self/this/super.method() calls to same-class or parent methods
-            // Falls back to walking the inheritance chain if not found in same class
-            if (selfMethodCalls && def.className) {
-                for (const call of selfMethodCalls) {
-                    const symbols = this.symbols.get(call.name);
-                    if (!symbols) continue;
-
-                    // For super().method(), skip same-class — start from parent
-                    let match = call.receiver === 'super'
-                        ? null
-                        : symbols.find(s => s.className === def.className);
-
-                    // Walk inheritance chain using BFS if not found in same class
-                    if (!match) {
-                        const visited = new Set([def.className]);
-                        const defFile = def.file;
-                        const startParents = this._getInheritanceParents(def.className, defFile) || [];
-                        const queue = startParents.map(p => ({ name: p, contextFile: defFile }));
-                        while (queue.length > 0 && !match) {
-                            const { name: current, contextFile } = queue.shift();
-                            if (visited.has(current)) continue;
-                            visited.add(current);
-                            match = symbols.find(s => s.className === current);
-                            if (!match) {
-                                const resolvedFile = this._resolveClassFile(current, contextFile);
-                                const grandparents = this._getInheritanceParents(current, resolvedFile) || [];
-                                for (const gp of grandparents) {
-                                    if (!visited.has(gp)) queue.push({ name: gp, contextFile: resolvedFile });
-                                }
-                            }
-                        }
-                    }
-
-                    if (!match) continue;
-
-                    const key = match.bindingId || `${match.className}.${call.name}`;
-                    const existing = callees.get(key);
-                    if (existing) {
-                        existing.count += 1;
-                    } else {
-                        callees.set(key, {
-                            name: call.name,
-                            bindingId: match.bindingId,
-                            count: 1
-                        });
-                    }
-                }
-            }
-
-            // Look up each callee in the symbol table
-            // For methods, prefer callees from: 1) same file, 2) same package, 3) same receiver type
-            // Also deprioritize test-file definitions when caller is in production code
-            const result = [];
-            const defDir = path.dirname(def.file);
-            const defReceiver = def.receiver;
-            const defFileEntry = fileEntry;
-            const callerIsTest = defFileEntry && isTestFile(defFileEntry.relativePath, defFileEntry.language);
-
-            for (const { name: calleeName, bindingId, count } of callees.values()) {
-                const symbols = this.symbols.get(calleeName);
-                if (symbols && symbols.length > 0) {
-                    let callee = symbols[0];
-
-                    // If we have a binding ID, find the exact matching symbol
-                    if (bindingId && symbols.length > 1) {
-                        const exactMatch = symbols.find(s => s.bindingId === bindingId);
-                        if (exactMatch) {
-                            callee = exactMatch;
-                        }
-                    } else if (symbols.length > 1) {
-                        // Priority 1: Same file, but different definition (for overloads)
-                        const sameFileDifferent = symbols.find(s => s.file === def.file && s.startLine !== def.startLine);
-                        const sameFile = symbols.find(s => s.file === def.file);
-                        if (sameFileDifferent && calleeName === def.name) {
-                            callee = sameFileDifferent;
-                        } else if (sameFile) {
-                            callee = sameFile;
-                        } else {
-                            // Priority 2: Same directory (package)
-                            const sameDir = symbols.find(s => path.dirname(s.file) === defDir);
-                            if (sameDir) {
-                                callee = sameDir;
-                            } else if (defReceiver) {
-                                // Priority 3: Same receiver type (for methods)
-                                const sameReceiver = symbols.find(s => s.receiver === defReceiver);
-                                if (sameReceiver) {
-                                    callee = sameReceiver;
-                                }
-                            }
-                        }
-                        // Priority 4: If default (symbols[0]) is a test file, prefer non-test
-                        if (!bindingId) {
-                            const calleeFileEntry = this.files.get(callee.file);
-                            if (calleeFileEntry && isTestFile(calleeFileEntry.relativePath, calleeFileEntry.language)) {
-                                const nonTest = symbols.find(s => {
-                                    const fe = this.files.get(s.file);
-                                    return fe && !isTestFile(fe.relativePath, fe.language);
-                                });
-                                if (nonTest) callee = nonTest;
-                            }
-                        }
-                    }
-
-                    // Skip test-file callees when caller is production code and
-                    // there's no binding (import) evidence linking them
-                    if (!callerIsTest && !bindingId) {
-                        const calleeFileEntry = this.files.get(callee.file);
-                        if (calleeFileEntry && isTestFile(calleeFileEntry.relativePath, calleeFileEntry.language)) {
-                            continue;
-                        }
-                    }
-
-                    result.push({
-                        ...callee,
-                        callCount: count,
-                        weight: this.calculateWeight(count)
-                    });
-                }
-            }
-
-            // Sort by call count (core dependencies first)
-            result.sort((a, b) => b.callCount - a.callCount);
-
-            return result;
-        } catch (e) {
-            // Expected: file read/parse failures (minified, binary, buffer exceeded).
-            // Return empty callees rather than crashing the entire query.
-            return [];
-        }
-        } finally { this._endOp(); }
-    }
-
-    /**
-     * Calculate dependency weight based on usage
-     */
-    calculateWeight(callCount) {
-        if (callCount >= 10) return 'core';
-        if (callCount >= 3) return 'regular';
-        if (callCount === 1) return 'utility';
-        return 'normal';
-    }
-
-    /**
-     * Smart extraction: function + dependencies
-     */
-    smart(name, options = {}) {
-        this._beginOp();
-        try {
-        const { def } = this.resolveSymbol(name, { file: options.file });
-        if (!def) {
-            return null;
-        }
-        const code = this.extractCode(def);
-        const stats = { uncertain: 0 };
-        const callees = this.findCallees(def, { includeMethods: options.includeMethods, includeUncertain: options.includeUncertain, stats });
-
-        const filesInScope = new Set([def.file]);
-        callees.forEach(c => filesInScope.add(c.file));
-        let dynamicImports = 0;
-        for (const f of filesInScope) {
-            const fe = this.files.get(f);
-            if (fe?.dynamicImports) dynamicImports += fe.dynamicImports;
-        }
-
-        // Extract code for each dependency, excluding the exact same function
-        // (but keeping same-name overloads, e.g. Java toJson(Object) vs toJson(Object, Class))
-        const defBindingId = def.bindingId;
-        const dependencies = callees
-            .filter(callee => callee.bindingId !== defBindingId)
-            .map(callee => ({
-                ...callee,
-                code: this.extractCode(callee)
-            }));
-
-        // Find type definitions if requested
-        const types = [];
-        if (options.withTypes) {
-            // Look for type annotations in params/return type
-            const typeNames = this.extractTypeNames(def);
-            for (const typeName of typeNames) {
-                const typeSymbols = this.symbols.get(typeName);
-                if (typeSymbols) {
-                    for (const sym of typeSymbols) {
-                        if (['type', 'interface', 'class', 'struct'].includes(sym.type)) {
-                            types.push({
-                                ...sym,
-                                code: this.extractCode(sym)
-                            });
-                        }
-                    }
-                }
-            }
-        }
-
-        return {
-            target: {
-                ...def,
-                code
-            },
-            dependencies,
-            types,
-            meta: {
-                complete: stats.uncertain === 0 && dynamicImports === 0,
-                skipped: 0,
-                dynamicImports,
-                uncertain: stats.uncertain
-            }
-        };
-        } finally { this._endOp(); }
-    }
-
-    // ========================================================================
-    // HELPER METHODS
-    // ========================================================================
+    // ========================================================================
+    // HELPER METHODS
+    // ========================================================================
 
     /**
      * Get line content from a file
@@ -2206,34 +1549,8 @@ class ProjectIndex {
         return returnSymbol ? best : best.name;
     }
 
-    /**
-     * Get instance attribute types for a class in a file.
-     * Returns Map<attrName, typeName> for a given className.
-     * Caches results per file.
-     */
-    getInstanceAttributeTypes(filePath, className) {
-        if (!this._attrTypeCache) this._attrTypeCache = new Map();
-
-        let fileCache = this._attrTypeCache.get(filePath);
-        if (!fileCache) {
-            const fileEntry = this.files.get(filePath);
-            if (!fileEntry || fileEntry.language !== 'python') return null;
-
-            const langModule = getLanguageModule('python');
-            if (!langModule?.findInstanceAttributeTypes) return null;
-
-            try {
-                const content = this._readFile(filePath);
-                const parser = getParser('python');
-                fileCache = langModule.findInstanceAttributeTypes(content, parser);
-                this._attrTypeCache.set(filePath, fileCache);
-            } catch {
-                return null;
-            }
-        }
-
-        return fileCache.get(className) || null;
-    }
+    /** Get instance attribute types for a class in a file */
+    getInstanceAttributeTypes(filePath, className) { return callersModule.getInstanceAttributeTypes(this, filePath, className); }
 
     /**
      * Extract type names from a function definition
@@ -2284,16 +1601,30 @@ class ProjectIndex {
             const content = this._readFile(normalizedPath);
             const { imports: rawImports } = extractImports(content, fileEntry.language);
 
+            const contentLines = content.split('\n');
+
             return rawImports.map(imp => {
+                // Skip imports with null module (e.g. Rust include! with dynamic path)
+                if (!imp.module) {
+                    return {
+                        module: null,
+                        names: imp.names,
+                        type: imp.type,
+                        resolved: null,
+                        isExternal: false,
+                        isDynamic: true,
+                        line: null
+                    };
+                }
+
                 // Dynamic imports with variable path (e.g. require(varName), import(varExpr)) can't be resolved.
                 // Only JS/TS require()/import() with dynamic=true has unresolvable paths.
                 // Go side-effect/dot imports and Rust glob uses also set dynamic=true but have valid module paths.
                 const isUnresolvableDynamic = imp.dynamic && (imp.type === 'require' || imp.type === 'dynamic');
                 if (isUnresolvableDynamic) {
-                    const lines = content.split('\n');
                     let line = null;
-                    for (let i = 0; i < lines.length; i++) {
-                        if (lines[i].includes(imp.module || 'require')) {
+                    for (let i = 0; i < contentLines.length; i++) {
+                        if (contentLines[i].includes(imp.module || 'require')) {
                             line = i + 1;
                             break;
                         }
@@ -2322,10 +1653,9 @@ class ProjectIndex {
                 }
 
                 // Find line number of import
-                const lines = content.split('\n');
                 let line = null;
-                for (let i = 0; i < lines.length; i++) {
-                    if (lines[i].includes(imp.module)) {
+                for (let i = 0; i < contentLines.length; i++) {
+                    if (contentLines[i].includes(imp.module)) {
                         line = i + 1;
                         break;
                     }
@@ -2616,11 +1946,15 @@ class ProjectIndex {
      * @param {string} filePath - File path
      * @returns {Array} Exported symbols from that file
      */
-    fileExports(filePath) {
+    fileExports(filePath, _visited) {
         const resolved = this.resolveFilePathForQuery(filePath);
         if (typeof resolved !== 'string') return resolved;
 
         const absPath = resolved;
+        const visited = _visited || new Set();
+        if (visited.has(absPath)) return [];
+        visited.add(absPath);
+
         const fileEntry = this.files.get(absPath);
         if (!fileEntry) {
             return [];
@@ -2683,7 +2017,7 @@ class ProjectIndex {
                         if (sourceEntry) {
                             // For star re-exports, include all exported symbols from source
                             if (exp.type === 're-export-all') {
-                                const sourceExports = this.fileExports(resolved);
+                                const sourceExports = this.fileExports(resolved, visited);
                                 for (const srcExp of sourceExports) {
                                     if (!matchedNames.has(srcExp.name)) {
                                         matchedNames.add(srcExp.name);
@@ -2731,396 +2065,64 @@ class ProjectIndex {
         return results;
     }
 
-    /**
-     * Check if a function is used as a callback anywhere in the codebase
-     * @param {string} name - Function name
-     * @returns {Array} Callback usages
-     */
-    findCallbackUsages(name) {
-        const usages = [];
+    /** Check if a function is used as a callback anywhere in the codebase */
+    findCallbackUsages(name) { return callersModule.findCallbackUsages(this, name); }
 
-        for (const [filePath, fileEntry] of this.files) {
-            try {
-                const content = this._readFile(filePath);
-                const language = detectLanguage(filePath);
-                if (!language) continue;
 
-                const langModule = getLanguageModule(language);
-                if (!langModule.findCallbackUsages) continue;
+    /** Build a usage index for all identifiers in the codebase (optimized for deadcode) */
+    buildUsageIndex() { return deadcodeModule.buildUsageIndex(this); }
 
-                const parser = getParser(language);
-                const callbacks = langModule.findCallbackUsages(content, name, parser);
+    /** Find dead code (unused functions/classes) */
+    deadcode(options) { return deadcodeModule.deadcode(this, options); }
 
-                for (const cb of callbacks) {
-                    usages.push({
-                        file: filePath,
-                        relativePath: fileEntry.relativePath,
-                        ...cb
-                    });
-                }
-            } catch (e) {
-                // Skip files that can't be processed
-            }
-        }
+    /**
+     * Get dependency graph for a file
+     * @param {string} filePath - Starting file
+     * @param {object} options - { direction: 'imports' | 'importers' | 'both', maxDepth }
+     * @returns {object} - Graph structure with root, nodes, edges
+     */
+    graph(filePath, options = {}) {
+        const direction = options.direction || 'both';
+        // Sanitize depth: use default for null/undefined, clamp negative to 0
+        const rawDepth = options.maxDepth ?? 5;
+        const maxDepth = Math.max(0, rawDepth);
 
-        return usages;
-    }
+        const resolved = this.resolveFilePathForQuery(filePath);
+        if (typeof resolved !== 'string') return resolved;
 
+        const targetPath = resolved;
 
-    /**
-     * Build a usage index for all identifiers in the codebase (optimized for deadcode)
-     * Scans all files ONCE and builds a reverse index: name -> [usages]
-     * @returns {Map<string, Array>} Usage index
-     */
-    buildUsageIndex() {
-        const usageIndex = new Map(); // name -> [{file, line}]
+        const buildSubgraph = (dir) => {
+            const visited = new Set();
+            const nodes = [];
+            const edges = [];
 
-        for (const [filePath, fileEntry] of this.files) {
-            try {
-                const language = detectLanguage(filePath);
-                if (!language) continue;
+            const traverse = (file, depth) => {
+                if (visited.has(file)) return;
+                visited.add(file);
 
-                const content = this._readFile(filePath);
+                const fileEntry = this.files.get(file);
+                const relPath = fileEntry ? fileEntry.relativePath : path.relative(this.root, file);
+                nodes.push({ file, relativePath: relPath, depth });
 
-                // For HTML files, parse the virtual JS content instead of raw HTML
-                // (HTML tree-sitter sees script content as raw_text, not JS identifiers)
-                let tree;
-                if (language === 'html') {
-                    const htmlModule = getLanguageModule('html');
-                    const htmlParser = getParser('html');
-                    const jsParser = getParser('javascript');
-                    const blocks = htmlModule.extractScriptBlocks(content, htmlParser);
-                    if (blocks.length === 0 && !htmlModule.extractEventHandlerCalls) continue;
-                    if (blocks.length > 0) {
-                        const virtualJS = htmlModule.buildVirtualJSContent(content, blocks);
-                        tree = safeParse(jsParser, virtualJS);
-                    }
+                // Stop traversal at max depth but still register the node above
+                if (depth >= maxDepth) return;
+
+                let neighbors = [];
+                if (dir === 'imports') {
+                    neighbors = this.importGraph.get(file) || [];
                 } else {
-                    const parser = getParser(language);
-                    if (!parser) continue;
-                    tree = safeParse(parser, content);
+                    neighbors = this.exportGraph.get(file) || [];
                 }
 
-                // Collect all identifiers from this file in one pass
-                const traverse = (node) => {
-                    // Match all identifier-like nodes across languages
-                    if (node.type === 'identifier' ||
-                        node.type === 'property_identifier' ||
-                        node.type === 'type_identifier' ||
-                        node.type === 'shorthand_property_identifier' ||
-                        node.type === 'shorthand_property_identifier_pattern' ||
-                        node.type === 'field_identifier') {
-                        const name = node.text;
-                        if (!usageIndex.has(name)) {
-                            usageIndex.set(name, []);
-                        }
-                        usageIndex.get(name).push({
-                            file: filePath,
-                            line: node.startPosition.row + 1,
-                            relativePath: fileEntry.relativePath
-                        });
-                    }
-                    for (let i = 0; i < node.childCount; i++) {
-                        traverse(node.child(i));
-                    }
-                };
-                if (tree) traverse(tree.rootNode);
-
-                // For HTML files, also extract identifiers from event handler attributes
-                // (onclick="foo()" etc. — these are in HTML, not in <script> blocks)
-                if (language === 'html') {
-                    const htmlModule = getLanguageModule('html');
-                    const htmlParser = getParser('html');
-                    const handlerCalls = htmlModule.extractEventHandlerCalls(content, htmlParser);
-                    for (const call of handlerCalls) {
-                        if (!usageIndex.has(call.name)) {
-                            usageIndex.set(call.name, []);
-                        }
-                        usageIndex.get(call.name).push({
-                            file: filePath,
-                            line: call.line,
-                            relativePath: fileEntry.relativePath
-                        });
-                    }
+                // Deduplicate neighbors (same file may be imported multiple times, e.g. Java inner classes)
+                const uniqueNeighbors = [...new Set(neighbors)];
+
+                for (const neighbor of uniqueNeighbors) {
+                    edges.push({ from: file, to: neighbor });
+                    traverse(neighbor, depth + 1);
                 }
-            } catch (e) {
-                // Skip files that can't be processed
-            }
-        }
-
-        return usageIndex;
-    }
-
-    /**
-     * Find dead code (unused functions/classes)
-     * @param {object} options - { includeExported, includeTests }
-     * @returns {Array} Unused symbols
-     */
-    deadcode(options = {}) {
-        this._beginOp();
-        try {
-        const results = [];
-        let excludedDecorated = 0;
-        let excludedExported = 0;
-
-        // Build usage index once (instead of per-symbol)
-        const usageIndex = this.buildUsageIndex();
-
-        for (const [name, symbols] of this.symbols) {
-            for (const symbol of symbols) {
-                // Skip non-function/class types
-                // Include various method types from different languages:
-                // - function: standalone functions
-                // - class, struct, interface: type definitions (skip them in deadcode)
-                // - method: class methods
-                // - static, public, abstract: Java method modifiers used as types
-                // - constructor: constructors
-                const callableTypes = ['function', 'method', 'static', 'public', 'abstract', 'constructor'];
-                if (!callableTypes.includes(symbol.type)) {
-                    continue;
-                }
-
-                const fileEntry = this.files.get(symbol.file);
-                const lang = fileEntry?.language;
-
-                // Skip bundled/minified files (webpack bundles, build artifacts)
-                if (fileEntry?.isBundled) {
-                    continue;
-                }
-
-                // Skip test files unless requested
-                if (!options.includeTests && isTestFile(symbol.relativePath, lang)) {
-                    continue;
-                }
-
-                // Apply exclude and in filters
-                if ((options.exclude && options.exclude.length > 0) || options.in) {
-                    if (!this.matchesFilters(symbol.relativePath, { exclude: options.exclude, in: options.in })) {
-                        continue;
-                    }
-                }
-
-                const mods = symbol.modifiers || [];
-
-                // Language-specific entry points (called by runtime, no AST-visible callers)
-                // Go: main() and init() are called by runtime
-                const isGoEntryPoint = lang === 'go' && (name === 'main' || name === 'init');
-
-                // Java: public static void main(String[] args) is the entry point
-                const isJavaEntryPoint = lang === 'java' && name === 'main' &&
-                    mods.includes('public') && mods.includes('static');
-
-                // Python: Magic/dunder methods are called by the interpreter, not user code
-                // test_* functions/methods are called by pytest/unittest via reflection
-                // setUp/tearDown are unittest.TestCase framework methods called by test runner
-                // pytest_* are pytest plugin hooks called by the framework
-                const isPythonEntryPoint = lang === 'python' &&
-                    (/^__\w+__$/.test(name) || /^test_/.test(name) ||
-                     /^(setUp|tearDown)(Class|Module)?$/.test(name) ||
-                     /^pytest_/.test(name));
-
-                // Rust: main() is entry point, #[test] and #[bench] functions are called by test/bench runner
-                const isRustEntryPoint = lang === 'rust' &&
-                    (name === 'main' || mods.includes('test') || mods.includes('bench'));
-
-                // Rust: trait impl methods are invoked via trait dispatch, not direct calls
-                // They can never be "dead" - the trait contract requires them to exist
-                // className for trait impls contains " for " (e.g., "PartialEq for Glob")
-                const isRustTraitImpl = lang === 'rust' && symbol.isMethod &&
-                    symbol.className && symbol.className.includes(' for ');
-
-                // Go: Test*, Benchmark*, Example* functions are called by go test
-                const isGoTestFunc = lang === 'go' &&
-                    /^(Test|Benchmark|Example)[A-Z]/.test(name);
-
-                // Java: @Test annotated methods are called by JUnit
-                const isJavaTestMethod = lang === 'java' && mods.includes('test');
-
-                // Java: @Override methods are invoked via polymorphic dispatch
-                // They implement interface/superclass contracts and can't be dead
-                const isJavaOverride = lang === 'java' && mods.includes('override');
-
-                // Skip trait impl / @Override methods entirely - they're required by the type system
-                if (isRustTraitImpl || isJavaOverride) {
-                    continue;
-                }
-
-                // JavaScript/TypeScript: framework lifecycle methods called by runtime
-                // React class components, Web Components, Angular, Vue
-                const jsLifecycleMethods = new Set([
-                    // React class component lifecycle
-                    'render', 'componentDidMount', 'componentDidUpdate', 'componentWillUnmount',
-                    'getDerivedStateFromProps', 'getDerivedStateFromError', 'componentDidCatch',
-                    'getSnapshotBeforeUpdate', 'shouldComponentUpdate',
-                    // Web Components lifecycle
-                    'connectedCallback', 'disconnectedCallback', 'attributeChangedCallback', 'adoptedCallback'
-                ]);
-                const isJsEntryPoint = (lang === 'javascript' || lang === 'typescript' || lang === 'tsx') &&
-                    symbol.isMethod && jsLifecycleMethods.has(name);
-
-                const isEntryPoint = isGoEntryPoint || isGoTestFunc ||
-                    isJavaEntryPoint || isJavaTestMethod ||
-                    isPythonEntryPoint || isRustEntryPoint || isJsEntryPoint;
-
-                // Entry points are always excluded — they're invoked by the runtime, not user code
-                if (isEntryPoint) {
-                    continue;
-                }
-
-                // Framework registration decorators — excluded by default to reduce noise
-                // Python: decorators with '.' (attribute access) like @router.get, @app.route, @celery.task
-                // Java: non-standard annotations like @Bean, @Scheduled, @GetMapping
-                // These functions are invoked by frameworks, not by user code — AST can't see the call path
-                const javaKeywords = new Set(['public', 'private', 'protected', 'static', 'final', 'abstract', 'synchronized', 'native', 'default']);
-                const hasRegistrationDecorator = (() => {
-                    if (lang === 'python') {
-                        const decorators = symbol.decorators || [];
-                        return decorators.some(d => d.includes('.'));
-                    }
-                    if (lang === 'java') {
-                        return mods.some(m => !javaKeywords.has(m));
-                    }
-                    return false;
-                })();
-
-                if (hasRegistrationDecorator && !options.includeDecorated) {
-                    excludedDecorated++;
-                    continue;
-                }
-
-                const isExported = fileEntry && (
-                    fileEntry.exports.includes(name) ||
-                    mods.includes('export') ||
-                    mods.includes('public') ||
-                    (lang === 'go' && /^[A-Z]/.test(name))
-                );
-
-                // Skip exported unless requested
-                if (isExported && !options.includeExported) {
-                    excludedExported++;
-                    continue;
-                }
-
-                // Use pre-built index for O(1) lookup instead of O(files) scan
-                const allUsages = usageIndex.get(name) || [];
-
-                // Filter out usages that are at the definition location
-                // nameLine: when decorators/annotations are present, startLine is the decorator line
-                // but the name identifier is on a different line (nameLine). Check both.
-                let nonDefUsages = allUsages.filter(u =>
-                    !(u.file === symbol.file && (u.line === symbol.startLine || u.line === symbol.nameLine))
-                );
-
-                // For exported symbols in --include-exported mode, also filter out export-site
-                // references (e.g., `module.exports = { helperC }` or `export { helperC }`).
-                // These are just re-statements of the export, not actual consumption.
-                if (isExported && options.includeExported) {
-                    nonDefUsages = nonDefUsages.filter(u => {
-                        if (u.file !== symbol.file) return true; // cross-file usage always counts
-                        // Check if same-file usage is on an export line
-                        const content = this._readFile(u.file);
-                        if (!content) return true;
-                        const lines = content.split('\n');
-                        const line = lines[u.line - 1] || '';
-                        const trimmed = line.trim();
-                        // CJS: module.exports = { ... } or exports.name = ...
-                        if (trimmed.startsWith('module.exports') || /^exports\.\w+\s*=/.test(trimmed)) return false;
-                        // ESM: export { ... } or export default
-                        if (/^export\s*\{/.test(trimmed) || /^export\s+default\s/.test(trimmed)) return false;
-                        return true;
-                    });
-                }
-
-                // Total includes all usage types (calls, references, callbacks, re-exports)
-                const totalUsages = nonDefUsages.length;
-
-                if (totalUsages === 0) {
-                    // Collect decorators/annotations for hint display
-                    // Python: symbol.decorators (e.g., ['app.route("/path")', 'login_required'])
-                    // Java/Rust/Go: symbol.modifiers may contain annotations (e.g., 'bean', 'scheduled')
-                    const decorators = symbol.decorators || [];
-                    // For Java, extract annotation-like modifiers (javaKeywords defined above)
-                    const annotations = lang === 'java'
-                        ? mods.filter(m => !javaKeywords.has(m))
-                        : [];
-
-                    results.push({
-                        name: symbol.name,
-                        type: symbol.type,
-                        file: symbol.relativePath,
-                        startLine: symbol.startLine,
-                        endLine: symbol.endLine,
-                        isExported,
-                        usageCount: 0,
-                        ...(decorators.length > 0 && { decorators }),
-                        ...(annotations.length > 0 && { annotations })
-                    });
-                }
-            }
-        }
-
-        // Sort by file then line
-        results.sort((a, b) => {
-            if (a.file !== b.file) return a.file.localeCompare(b.file);
-            return a.startLine - b.startLine;
-        });
-
-        // Attach exclusion counts as array properties (backwards-compatible)
-        results.excludedDecorated = excludedDecorated;
-        results.excludedExported = excludedExported;
-
-        return results;
-        } finally { this._endOp(); }
-    }
-
-    /**
-     * Get dependency graph for a file
-     * @param {string} filePath - Starting file
-     * @param {object} options - { direction: 'imports' | 'importers' | 'both', maxDepth }
-     * @returns {object} - Graph structure with root, nodes, edges
-     */
-    graph(filePath, options = {}) {
-        const direction = options.direction || 'both';
-        // Sanitize depth: use default for null/undefined, clamp negative to 0
-        const rawDepth = options.maxDepth ?? 5;
-        const maxDepth = Math.max(0, rawDepth);
-
-        const resolved = this.resolveFilePathForQuery(filePath);
-        if (typeof resolved !== 'string') return resolved;
-
-        const targetPath = resolved;
-
-        const buildSubgraph = (dir) => {
-            const visited = new Set();
-            const nodes = [];
-            const edges = [];
-
-            const traverse = (file, depth) => {
-                if (visited.has(file)) return;
-                visited.add(file);
-
-                const fileEntry = this.files.get(file);
-                const relPath = fileEntry ? fileEntry.relativePath : path.relative(this.root, file);
-                nodes.push({ file, relativePath: relPath, depth });
-
-                // Stop traversal at max depth but still register the node above
-                if (depth >= maxDepth) return;
-
-                let neighbors = [];
-                if (dir === 'imports') {
-                    neighbors = this.importGraph.get(file) || [];
-                } else {
-                    neighbors = this.exportGraph.get(file) || [];
-                }
-
-                // Deduplicate neighbors (same file may be imported multiple times, e.g. Java inner classes)
-                const uniqueNeighbors = [...new Set(neighbors)];
-
-                for (const neighbor of uniqueNeighbors) {
-                    edges.push({ from: file, to: neighbor });
-                    traverse(neighbor, depth + 1);
-                }
-            };
+            };
 
             traverse(targetPath, 0);
             return { nodes, edges };
@@ -3257,7 +2259,7 @@ class ProjectIndex {
         const fileEntry = this.files.get(def.file);
         if (fileEntry) {
             for (const sym of fileEntry.symbols) {
-                if (sym.name !== name && sym.type === 'function') {
+                if (sym.name !== name && !NON_CALLABLE_TYPES.has(sym.type)) {
                     related.sameFile.push({
                         name: sym.name,
                         line: sym.startLine,
@@ -3586,737 +2588,43 @@ class ProjectIndex {
         } finally { this._endOp(); }
     }
 
-    /**
-     * Plan a refactoring operation
-     * @param {string} name - Function name
-     * @param {object} options - { addParam, removeParam, renameTo, defaultValue }
-     * @returns {object} Plan with before/after signatures and affected call sites
-     */
-    plan(name, options = {}) {
-        this._beginOp();
-        try {
-        const definitions = this.symbols.get(name);
-        if (!definitions || definitions.length === 0) {
-            return { found: false, function: name };
-        }
-
-        const resolved = this.resolveSymbol(name, { file: options.file });
-        const def = resolved.def || definitions[0];
-        const impact = this.impact(name, { file: options.file });
-        const currentParams = def.paramsStructured || [];
-        const currentSignature = this.formatSignature(def);
-
-        let newParams = [...currentParams];
-        let newSignature = currentSignature;
-        let operation = null;
-        let changes = [];
-
-        if (options.addParam) {
-            operation = 'add-param';
-            const newParam = {
-                name: options.addParam,
-                ...(options.defaultValue && { default: options.defaultValue })
-            };
-            newParams.push(newParam);
-
-            // Generate new signature
-            const paramsList = newParams.map(p => {
-                let str = p.name;
-                if (p.type) str += `: ${p.type}`;
-                if (p.default) str += ` = ${p.default}`;
-                return str;
-            }).join(', ');
-            newSignature = `${name}(${paramsList})`;
-            if (def.returnType) newSignature += `: ${def.returnType}`;
-
-            // Describe changes needed at each call site
-            for (const fileGroup of impact.byFile) {
-                for (const site of fileGroup.sites) {
-                    const suggestion = options.defaultValue
-                        ? `No change needed (has default value)`
-                        : `Add argument: ${options.addParam}`;
-                    changes.push({
-                        file: site.file,
-                        line: site.line,
-                        expression: site.expression,
-                        suggestion,
-                        args: site.args
-                    });
-                }
-            }
-        }
-
-        if (options.removeParam) {
-            operation = 'remove-param';
-            const paramIndex = currentParams.findIndex(p => p.name === options.removeParam);
-            if (paramIndex === -1) {
-                return {
-                    found: true,
-                    error: `Parameter "${options.removeParam}" not found in ${name}`,
-                    currentParams: currentParams.map(p => p.name)
-                };
-            }
-
-            newParams = currentParams.filter(p => p.name !== options.removeParam);
-
-            // Generate new signature
-            const paramsList = newParams.map(p => {
-                let str = p.name;
-                if (p.type) str += `: ${p.type}`;
-                if (p.default) str += ` = ${p.default}`;
-                return str;
-            }).join(', ');
-            newSignature = `${name}(${paramsList})`;
-            if (def.returnType) newSignature += `: ${def.returnType}`;
-
-            // For Python/Rust methods, self/cls/&self/&mut self is in paramsStructured
-            // but callers don't pass it. Adjust paramIndex to caller-side position.
-            const fileEntry = this.files.get(def.file);
-            const lang = fileEntry?.language;
-            let selfOffset = 0;
-            if ((lang === 'python' || lang === 'rust') && currentParams.length > 0) {
-                const firstName = currentParams[0].name;
-                if (firstName === 'self' || firstName === 'cls' || firstName === '&self' || firstName === '&mut self') {
-                    selfOffset = 1;
-                }
-            }
-            const callerArgIndex = paramIndex - selfOffset;
-
-            // Describe changes at each call site
-            for (const fileGroup of impact.byFile) {
-                for (const site of fileGroup.sites) {
-                    if (site.args && site.argCount > callerArgIndex) {
-                        changes.push({
-                            file: site.file,
-                            line: site.line,
-                            expression: site.expression,
-                            suggestion: `Remove argument ${callerArgIndex + 1}: ${site.args[callerArgIndex] || '?'}`,
-                            args: site.args
-                        });
-                    }
-                }
-            }
-        }
-
-        if (options.renameTo) {
-            operation = 'rename';
-            newSignature = currentSignature.replace(name, options.renameTo);
-
-            // All call sites need renaming
-            for (const fileGroup of impact.byFile) {
-                for (const site of fileGroup.sites) {
-                    const newExpression = site.expression.replace(
-                        new RegExp('\\b' + escapeRegExp(name) + '\\b'),
-                        options.renameTo
-                    );
-                    changes.push({
-                        file: site.file,
-                        line: site.line,
-                        expression: site.expression,
-                        suggestion: `Rename to: ${newExpression}`,
-                        newExpression
-                    });
-                }
-            }
-        }
-
-        return {
-            found: true,
-            function: name,
-            file: def.relativePath,
-            startLine: def.startLine,
-            operation,
-            before: {
-                signature: currentSignature,
-                params: currentParams.map(p => p.name)
-            },
-            after: {
-                signature: newSignature,
-                params: newParams.map(p => p.name)
-            },
-            totalChanges: changes.length,
-            filesAffected: new Set(changes.map(c => c.file)).size,
-            changes
-        };
-        } finally { this._endOp(); }
-    }
+    /** Plan a refactoring operation */
+    plan(name, options) { return verifyModule.plan(this, name, options); }
 
-    /**
-     * Parse a stack trace and show code for each frame
-     * @param {string} stackText - Stack trace text
-     * @returns {object} Parsed frames with code context
-     */
+    /** Parse a stack trace and show code for each frame */
     parseStackTrace(stackText) {
-        const frames = [];
-        const lines = stackText.split(/\\n|\n/);
-
-        // Stack trace patterns for different languages/runtimes
-        // Order matters - more specific patterns first
-        const patterns = [
-            // JavaScript Node.js: "at functionName (file.js:line:col)" or "at file.js:line:col"
-            { regex: /at\s+(?:async\s+)?(?:(.+?)\s+\()?([^():]+):(\d+)(?::(\d+))?\)?/, extract: (m) => ({ funcName: m[1] || null, file: m[2], line: parseInt(m[3]), col: m[4] ? parseInt(m[4]) : null }) },
-            // Deno: "at functionName (file:///path/to/file.ts:line:col)"
-            { regex: /at\s+(?:async\s+)?(?:(.+?)\s+\()?file:\/\/([^:]+):(\d+)(?::(\d+))?\)?/, extract: (m) => ({ funcName: m[1] || null, file: m[2], line: parseInt(m[3]), col: m[4] ? parseInt(m[4]) : null }) },
-            // Bun: "at functionName (file.js:line:col)" - similar to Node but may have different formatting
-            { regex: /^\s+at\s+(.+?)\s+\[as\s+\w+\]\s+\(([^:]+):(\d+):(\d+)\)/, extract: (m) => ({ funcName: m[1], file: m[2], line: parseInt(m[3]), col: parseInt(m[4]) }) },
-            // Browser Chrome/V8: "at functionName (http://... or file:// ...)"
-            { regex: /at\s+(?:async\s+)?(?:(.+?)\s+\()?(?:https?:\/\/[^/]+)?([^():]+):(\d+)(?::(\d+))?\)?/, extract: (m) => ({ funcName: m[1] || null, file: m[2], line: parseInt(m[3]), col: m[4] ? parseInt(m[4]) : null }) },
-            // Firefox: "functionName@file:line:col"
-            { regex: /^(.+)@(.+):(\d+):(\d+)$/, extract: (m) => ({ funcName: m[1] || null, file: m[2], line: parseInt(m[3]), col: parseInt(m[4]) }) },
-            // Safari: "functionName@file:line:col" (similar to Firefox)
-            { regex: /^(.+)@(?:https?:\/\/[^/]+)?([^:]+):(\d+)(?::(\d+))?$/, extract: (m) => ({ funcName: m[1] || null, file: m[2], line: parseInt(m[3]), col: m[4] ? parseInt(m[4]) : null }) },
-            // Python: "File \"file.py\", line N, in function"
-            { regex: /File\s+"([^"]+)",\s+line\s+(\d+)(?:,\s+in\s+(.+))?/, extract: (m) => ({ file: m[1], line: parseInt(m[2]), funcName: m[3] || null, col: null }) },
-            // Go: "file.go:line" or "package/file.go:line +0x..."
-            { regex: /^\s*([^\s:]+\.go):(\d+)(?:\s|$)/, extract: (m) => ({ file: m[1], line: parseInt(m[2]), funcName: null, col: null }) },
-            // Go with function: "package.FunctionName()\n\tfile.go:line"
-            { regex: /^\s*([^\s(]+)\(\)$/, extract: null }, // Skip function-only lines
-            // Java: "at package.Class.method(File.java:line)"
-            { regex: /at\s+([^\(]+)\(([^:]+):(\d+)\)/, extract: (m) => ({ funcName: m[1].split('.').pop(), file: m[2], line: parseInt(m[3]), col: null }) },
-            // Rust: "at src/main.rs:line:col" or panic location
-            { regex: /(?:at\s+)?([^\s:]+\.rs):(\d+)(?::(\d+))?/, extract: (m) => ({ file: m[1], line: parseInt(m[2]), col: m[3] ? parseInt(m[3]) : null, funcName: null }) },
-            // Generic: "file:line" as last resort
-            { regex: /([^\s:]+\.\w+):(\d+)(?::(\d+))?/, extract: (m) => ({ file: m[1], line: parseInt(m[2]), col: m[3] ? parseInt(m[3]) : null, funcName: null }) }
-        ];
-
-        for (const line of lines) {
-            const trimmed = line.trim();
-            if (!trimmed) continue;
-
-            // Try each pattern until one matches
-            for (const pattern of patterns) {
-                const match = pattern.regex.exec(trimmed);
-                if (match && pattern.extract) {
-                    const extracted = pattern.extract(match);
-                    if (extracted && extracted.file && extracted.line) {
-                        frames.push(this.createStackFrame(
-                            extracted.file,
-                            extracted.line,
-                            extracted.funcName,
-                            extracted.col,
-                            trimmed
-                        ));
-                        break; // Move to next line
-                    }
-                }
-            }
-        }
-
-        return {
-            frameCount: frames.length,
-            frames
-        };
+        return stacktrace.parseStackTrace(this, stackText);
     }
 
-    /**
-     * Calculate path similarity score between two file paths
-     * Higher score = better match
-     * @param {string} query - The path from stack trace
-     * @param {string} candidate - The candidate file path
-     * @returns {number} Similarity score
-     */
+    /** Calculate path similarity score between two file paths */
     calculatePathSimilarity(query, candidate) {
-        // Normalize paths for comparison
-        const queryParts = query.replace(/\\/g, '/').split('/').filter(Boolean);
-        const candidateParts = candidate.replace(/\\/g, '/').split('/').filter(Boolean);
-
-        let score = 0;
-
-        // Exact match on full path
-        if (candidate.endsWith(query)) {
-            score += 100;
-        }
-
-        // Compare from the end (most important part)
-        let matches = 0;
-        const minLen = Math.min(queryParts.length, candidateParts.length);
-        for (let i = 0; i < minLen; i++) {
-            const queryPart = queryParts[queryParts.length - 1 - i];
-            const candPart = candidateParts[candidateParts.length - 1 - i];
-            if (queryPart === candPart) {
-                matches++;
-                // Earlier parts (closer to filename) score more
-                score += (10 - i) * 5;
-            } else {
-                break; // Stop at first mismatch
-            }
-        }
-
-        // Bonus for matching most of the query path
-        if (matches === queryParts.length) {
-            score += 50;
-        }
-
-        // Filename match is essential
-        const queryFile = queryParts[queryParts.length - 1];
-        const candFile = candidateParts[candidateParts.length - 1];
-        if (queryFile !== candFile) {
-            score = 0; // No match if filename doesn't match
-        }
-
-        return score;
+        return stacktrace.calculatePathSimilarity(query, candidate);
     }
 
-    /**
-     * Find the best matching file for a stack trace path
-     * @param {string} filePath - Path from stack trace
-     * @param {string|null} funcName - Function name for verification
-     * @param {number} lineNum - Line number for verification
-     * @returns {{path: string, relativePath: string, confidence: number}|null}
-     */
+    /** Find the best matching file for a stack trace path */
     findBestMatchingFile(filePath, funcName, lineNum) {
-        const candidates = [];
-
-        // Collect all potential matches with scores
-        for (const [absPath, fileEntry] of this.files) {
-            const score = this.calculatePathSimilarity(filePath, absPath);
-            const relScore = this.calculatePathSimilarity(filePath, fileEntry.relativePath);
-            const bestScore = Math.max(score, relScore);
-
-            if (bestScore > 0) {
-                candidates.push({
-                    absPath,
-                    relativePath: fileEntry.relativePath,
-                    score: bestScore,
-                    fileEntry
-                });
-            }
-        }
-
-        if (candidates.length === 0) {
-            // Try absolute path
-            const absPath = path.isAbsolute(filePath) ? filePath : path.join(this.root, filePath);
-            if (fs.existsSync(absPath)) {
-                return {
-                    path: absPath,
-                    relativePath: path.relative(this.root, absPath),
-                    confidence: 0.5 // Low confidence for unindexed files
-                };
-            }
-            return null;
-        }
-
-        // Sort by score descending
-        candidates.sort((a, b) => b.score - a.score);
-
-        // If there's a function name, verify it exists at the line
-        if (funcName && candidates.length > 1) {
-            for (const cand of candidates) {
-                const symbols = this.symbols.get(funcName);
-                if (symbols) {
-                    const match = symbols.find(s =>
-                        s.file === cand.absPath &&
-                        s.startLine <= lineNum && s.endLine >= lineNum
-                    );
-                    if (match) {
-                        // This candidate has the function at the right line - strong match
-                        return {
-                            path: cand.absPath,
-                            relativePath: cand.relativePath,
-                            confidence: 1.0,
-                            verifiedFunction: true
-                        };
-                    }
-                }
-            }
-        }
-
-        // Return best scoring candidate
-        const best = candidates[0];
-        const confidence = candidates.length === 1 ? 0.9 :
-                          (best.score > 100 ? 0.8 : 0.6);
-
-        return {
-            path: best.absPath,
-            relativePath: best.relativePath,
-            confidence
-        };
+        return stacktrace.findBestMatchingFile(this, filePath, funcName, lineNum);
     }
 
-    /**
-     * Create a stack frame with code context
-     */
+    /** Create a stack frame with code context */
     createStackFrame(filePath, lineNum, funcName, col, rawLine) {
-        const frame = {
-            file: filePath,
-            line: lineNum,
-            function: funcName,
-            column: col,
-            raw: rawLine,
-            found: false,
-            code: null,
-            context: null,
-            confidence: 0
-        };
-
-        // Find the best matching file using improved algorithm
-        const match = this.findBestMatchingFile(filePath, funcName, lineNum);
-
-        if (match) {
-            const resolvedPath = match.path;
-            frame.found = true;
-            frame.resolvedFile = match.relativePath;
-            frame.confidence = match.confidence;
-            if (match.verifiedFunction) {
-                frame.verifiedFunction = true;
-            }
-
-            try {
-                const content = this._readFile(resolvedPath);
-                const lines = content.split('\n');
-
-                // Get the exact line
-                if (lineNum > 0 && lineNum <= lines.length) {
-                    frame.code = lines[lineNum - 1];
-
-                    // Get context (2 lines before, 2 after)
-                    const contextLines = [];
-                    for (let i = Math.max(0, lineNum - 3); i < Math.min(lines.length, lineNum + 2); i++) {
-                        contextLines.push({
-                            line: i + 1,
-                            code: lines[i],
-                            isCurrent: i + 1 === lineNum
-                        });
-                    }
-                    frame.context = contextLines;
-                }
-
-                // Try to find function info (verify it contains the line)
-                if (funcName) {
-                    const symbols = this.symbols.get(funcName);
-                    if (symbols) {
-                        const funcMatch = symbols.find(s =>
-                            s.file === resolvedPath &&
-                            s.startLine <= lineNum && s.endLine >= lineNum
-                        );
-                        if (funcMatch) {
-                            frame.functionInfo = {
-                                name: funcMatch.name,
-                                startLine: funcMatch.startLine,
-                                endLine: funcMatch.endLine,
-                                params: funcMatch.params
-                            };
-                            frame.confidence = 1.0; // High confidence when function verified
-                        } else {
-                            // Function exists but line doesn't match - lower confidence
-                            const anyMatch = symbols.find(s => s.file === resolvedPath);
-                            if (anyMatch) {
-                                frame.functionInfo = {
-                                    name: anyMatch.name,
-                                    startLine: anyMatch.startLine,
-                                    endLine: anyMatch.endLine,
-                                    params: anyMatch.params,
-                                    lineMismatch: true
-                                };
-                                frame.confidence = Math.min(frame.confidence, 0.5);
-                            }
-                        }
-                    }
-                } else {
-                    // No function name in stack - find enclosing function
-                    const enclosing = this.findEnclosingFunction(resolvedPath, lineNum, true);
-                    if (enclosing) {
-                        frame.functionInfo = {
-                            name: enclosing.name,
-                            startLine: enclosing.startLine,
-                            endLine: enclosing.endLine,
-                            params: enclosing.params,
-                            inferred: true
-                        };
-                    }
-                }
-            } catch (e) {
-                frame.error = e.message;
-            }
-        }
-
-        return frame;
-    }
-
-    /**
-     * Verify that all call sites match a function's signature
-     * @param {string} name - Function name
-     * @returns {object} Verification results with mismatches
-     */
-    verify(name, options = {}) {
-        this._beginOp();
-        try {
-        const { def } = this.resolveSymbol(name, { file: options.file });
-        if (!def) {
-            return { found: false, function: name };
-        }
-        // For Python/Rust methods, exclude self/cls from parameter count
-        // (callers don't pass self/cls explicitly: obj.method(a, b) not obj.method(obj, a, b))
-        const fileEntry = this.files.get(def.file);
-        const lang = fileEntry?.language;
-        let params = def.paramsStructured || [];
-        if ((lang === 'python' || lang === 'rust') && params.length > 0) {
-            const firstName = params[0].name;
-            if (firstName === 'self' || firstName === 'cls' || firstName === '&self' || firstName === '&mut self') {
-                params = params.slice(1);
-            }
-        }
-        const hasRest = params.some(p => p.rest);
-        // Rest params don't count toward expected/min — they accept 0+ extra args
-        const nonRestParams = params.filter(p => !p.rest);
-        const expectedParamCount = nonRestParams.length;
-        const optionalCount = nonRestParams.filter(p => p.optional || p.default !== undefined).length;
-        const minArgs = expectedParamCount - optionalCount;
-
-        // Get all call sites
-        const usages = this.usages(name, { codeOnly: true });
-        const calls = usages.filter(u => u.usageType === 'call' && !u.isDefinition);
-
-        const valid = [];
-        const mismatches = [];
-        const uncertain = [];
-
-        // If the definition is NOT a method, filter out method calls (e.g., dict.get() vs get())
-        // This prevents false positives where a standalone function name matches method calls
-        const defIsMethod = def.isMethod || def.type === 'method' || def.className;
-
-        for (const call of calls) {
-            const analysis = this.analyzeCallSite(call, name);
-
-            // Skip method calls when verifying a non-method definition
-            if (analysis.isMethodCall && !defIsMethod) {
-                continue;
-            }
-
-            if (analysis.args === null) {
-                // Couldn't parse arguments
-                uncertain.push({
-                    file: call.relativePath,
-                    line: call.line,
-                    expression: call.content.trim(),
-                    reason: 'Could not parse call arguments'
-                });
-                continue;
-            }
-
-            if (analysis.hasSpread) {
-                // Spread args - can't verify count
-                uncertain.push({
-                    file: call.relativePath,
-                    line: call.line,
-                    expression: call.content.trim(),
-                    reason: 'Uses spread operator'
-                });
-                continue;
-            }
-
-            const argCount = analysis.argCount;
-
-            // Check if arg count is valid
-            if (hasRest) {
-                // With rest param, need at least minArgs
-                if (argCount >= minArgs) {
-                    valid.push({ file: call.relativePath, line: call.line });
-                } else {
-                    mismatches.push({
-                        file: call.relativePath,
-                        line: call.line,
-                        expression: call.content.trim(),
-                        expected: `at least ${minArgs} arg(s)`,
-                        actual: argCount,
-                        args: analysis.args
-                    });
-                }
-            } else {
-                // Without rest, need between minArgs and expectedParamCount
-                if (argCount >= minArgs && argCount <= expectedParamCount) {
-                    valid.push({ file: call.relativePath, line: call.line });
-                } else {
-                    mismatches.push({
-                        file: call.relativePath,
-                        line: call.line,
-                        expression: call.content.trim(),
-                        expected: minArgs === expectedParamCount
-                            ? `${expectedParamCount} arg(s)`
-                            : `${minArgs}-${expectedParamCount} arg(s)`,
-                        actual: argCount,
-                        args: analysis.args
-                    });
-                }
-            }
-        }
-        this._clearTreeCache();
-
-        return {
-            found: true,
-            function: name,
-            file: def.relativePath,
-            startLine: def.startLine,
-            signature: this.formatSignature(def),
-            params: params.map(p => ({
-                name: p.name,
-                optional: p.optional || p.default !== undefined,
-                hasDefault: p.default !== undefined
-            })),
-            expectedArgs: { min: minArgs, max: hasRest ? '∞' : expectedParamCount },
-            totalCalls: valid.length + mismatches.length + uncertain.length,
-            valid: valid.length,
-            mismatches: mismatches.length,
-            uncertain: uncertain.length,
-            mismatchDetails: mismatches,
-            uncertainDetails: uncertain
-        };
-        } finally { this._endOp(); }
+        return stacktrace.createStackFrame(this, filePath, lineNum, funcName, col, rawLine);
     }
 
-    /**
-     * 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) {
-        try {
-            const language = detectLanguage(call.file);
-            if (!language) return { args: null, 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 = this._readFile(call.file);
-                // HTML files need special handling: parse script blocks as JS
-                if (language === 'html') {
-                    const htmlModule = getLanguageModule('html');
-                    const htmlParser = getParser('html');
-                    const jsParser = getParser('javascript');
-                    if (!htmlParser || !jsParser) return { args: null, argCount: 0 };
-                    const blocks = htmlModule.extractScriptBlocks(content, htmlParser);
-                    if (blocks.length === 0) return { args: null, argCount: 0 };
-                    const virtualJS = htmlModule.buildVirtualJSContent(content, blocks);
-                    tree = safeParse(jsParser, virtualJS);
-                } else {
-                    const parser = getParser(language);
-                    if (!parser) return { args: null, argCount: 0 };
-                    tree = safeParse(parser, content);
-                }
-                if (!tree) return { args: null, argCount: 0 };
-                if (!this._treeCache) this._treeCache = new Map();
-                this._treeCache.set(call.file, tree);
-            }
-
-            // Call node types vary by language
-            const callTypes = new Set(['call_expression', 'call', 'method_invocation', 'object_creation_expression']);
-            const targetRow = call.line - 1; // tree-sitter is 0-indexed
-
-            // 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 };
-
-            // Check if this is a method call (obj.func()) vs a direct call (func())
-            const funcNode = callNode.childForFieldName('function') ||
-                             callNode.childForFieldName('name');
-            let isMethodCall = false;
-            if (funcNode) {
-                // member_expression (JS), attribute (Python), selector_expression (Go), field_expression (Rust)
-                if (['member_expression', 'attribute', 'selector_expression', 'field_expression'].includes(funcNode.type)) {
-                    isMethodCall = true;
-                }
-                // Java method_invocation with object
-                if (callNode.type === 'method_invocation' && callNode.childForFieldName('object')) {
-                    isMethodCall = true;
-                }
-            }
-
-            const argsNode = callNode.childForFieldName('arguments');
-            if (!argsNode) return { args: [], argCount: 0, isMethodCall };
+    /** Verify that all call sites match a function's signature */
+    verify(name, options) { return verifyModule.verify(this, name, options); }
 
-            const args = [];
-            for (let i = 0; i < argsNode.namedChildCount; i++) {
-                args.push(argsNode.namedChild(i).text.trim());
-            }
-
-            return {
-                args,
-                argCount: args.length,
-                hasSpread: args.some(a => a.startsWith('...')),
-                hasVariable: args.some(a => /^[a-zA-Z_]\w*$/.test(a)),
-                isMethodCall
-            };
-        } catch (e) {
-            return { args: null, argCount: 0 };
-        }
-    }
+    /** Analyze a call site to understand how it's being called (AST-based) */
+    analyzeCallSite(call, funcName) { return verifyModule.analyzeCallSite(this, call, funcName); }
 
-    /**
-     * 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 (callTypes.has(node.type) && node.startPosition.row === targetRow) {
-            // Java constructor: new ClassName(args) — name is in 'type' field
-            if (node.type === 'object_creation_expression') {
-                const typeNode = node.childForFieldName('type');
-                if (typeNode) {
-                    // Strip generics and package qualifiers: com.foo.Bar<T> -> Bar
-                    const typeName = typeNode.text.replace(/<.*>$/, '').split('.').pop();
-                    if (typeName === funcName) return node;
-                }
-            } else {
-                // 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;
-                }
-            }
-        }
+    /** Find a call expression node at the target line matching funcName */
+    _findCallNode(node, callTypes, targetRow, funcName) { return verifyModule.findCallNode(node, callTypes, targetRow, funcName); }
 
-        // 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;
-    }
+    /** Clear the AST tree cache (call after batch operations) */
+    _clearTreeCache() { verifyModule.clearTreeCache(this); }
 
-    /**
-     * Clear the AST tree cache (call after batch operations)
-     */
-    _clearTreeCache() {
-        this._treeCache = null;
-    }
-
-    /**
-     * Identify common calling patterns
-     */
-    identifyCallPatterns(callSites, funcName) {
-        const patterns = {
-            constantArgs: 0,    // Call sites with literal/constant arguments
-            variableArgs: 0,    // Call sites passing variables
-            chainedCalls: 0,    // Calls that are part of method chains
-            awaitedCalls: 0,    // Async calls with await
-            spreadCalls: 0      // Calls using spread operator
-        };
-
-        for (const site of callSites) {
-            const expr = site.expression;
-
-            if (site.hasSpread) patterns.spreadCalls++;
-            if (/await\s/.test(expr)) patterns.awaitedCalls++;
-            if (new RegExp('\\.' + escapeRegExp(funcName) + '\\s*\\(').test(expr)) patterns.chainedCalls++;
-
-            if (site.args && site.args.length > 0) {
-                const hasLiteral = site.args.some(a =>
-                    /^[\d'"{\[]/.test(a) || a === 'true' || a === 'false' || a === 'null'
-                );
-                if (hasLiteral) patterns.constantArgs++;
-                if (site.hasVariable) patterns.variableArgs++;
-            }
-        }
-
-        return patterns;
-    }
+    /** Identify common calling patterns */
+    identifyCallPatterns(callSites, funcName) { return verifyModule.identifyCallPatterns(callSites, funcName); }
 
     /**
      * Get complete information about a symbol - definition, usages, callers, callees, tests, code
@@ -4333,10 +2641,10 @@ class ProjectIndex {
         const maxCallees = options.all ? Infinity : (options.maxCallees || 10);
         const includeMethods = options.includeMethods ?? true;
 
-        // Find symbol definition(s)
-        const definitions = this.find(name, { exact: true, file: options.file });
+        // Find symbol definition(s) — skip counts since about() computes its own via usages()
+        const definitions = this.find(name, { exact: true, file: options.file, skipCounts: true });
         if (definitions.length === 0) {
-            // Try fuzzy match
+            // Try fuzzy match (needs counts for suggestion ranking)
             const fuzzy = this.find(name, { file: options.file });
             if (fuzzy.length === 0) {
                 return null;
@@ -4379,7 +2687,7 @@ class ProjectIndex {
         let allCallers = null;
         let allCallees = null;
         if (primary.type === 'function' || primary.params !== undefined) {
-            allCallers = this.findCallers(symbolName, { includeMethods });
+            allCallers = this.findCallers(symbolName, { includeMethods, includeUncertain: options.includeUncertain, targetDefinitions: [primary] });
             // Apply exclude filter before slicing
             if (options.exclude && options.exclude.length > 0) {
                 allCallers = allCallers.filter(c => this.matchesFilters(c.relativePath, { exclude: options.exclude }));
@@ -4470,7 +2778,7 @@ class ProjectIndex {
             otherDefinitions: (options.all ? others : others.slice(0, 3)).map(d => ({
                 file: d.relativePath,
                 line: d.startLine,
-                usageCount: d.usageCount
+                usageCount: d.usageCount ?? this.countSymbolUsages(d).total
             })),
             types,
             code,
@@ -4662,7 +2970,8 @@ class ProjectIndex {
             const functions = [];
             for (const [name, symbols] of this.symbols) {
                 for (const sym of symbols) {
-                    if (sym.type === 'function' || sym.params !== undefined) {
+                    if (sym.type === 'function' || sym.type === 'method' || sym.type === 'static' ||
+                        sym.type === 'constructor' || sym.type === 'public' || sym.type === 'abstract') {
                         const lineCount = sym.endLine - sym.startLine + 1;
                         const relativePath = sym.relativePath || (sym.file ? path.relative(this.root, sym.file) : '');
                         functions.push({
@@ -4695,7 +3004,8 @@ class ProjectIndex {
 
         for (const [filePath, fileEntry] of this.files) {
             let functions = fileEntry.symbols.filter(s =>
-                s.type === 'function' || s.type === 'method' || s.type === 'static' || s.type === 'constructor'
+                s.type === 'function' || s.type === 'method' || s.type === 'static' ||
+                s.type === 'constructor' || s.type === 'public' || s.type === 'abstract'
             );
             const classes = fileEntry.symbols.filter(s =>
                 ['class', 'interface', 'type', 'enum', 'struct', 'trait', 'impl'].includes(s.type)
@@ -4802,182 +3112,14 @@ class ProjectIndex {
     // CACHE METHODS
     // ========================================================================
 
-    /**
-     * Save index to cache file
-     *
-     * @param {string} [cachePath] - Optional custom cache path
-     * @returns {string} - Path to cache file
-     */
-    saveCache(cachePath) {
-        const cacheDir = cachePath
-            ? path.dirname(cachePath)
-            : path.join(this.root, '.ucn-cache');
-
-        if (!fs.existsSync(cacheDir)) {
-            fs.mkdirSync(cacheDir, { recursive: true });
-        }
-
-        const cacheFile = cachePath || path.join(cacheDir, 'index.json');
-
-        // Prepare callsCache for serialization (exclude content to save space)
-        const callsCacheData = [];
-        for (const [filePath, entry] of this.callsCache) {
-            callsCacheData.push([filePath, {
-                mtime: entry.mtime,
-                hash: entry.hash,
-                calls: entry.calls
-                // content is not persisted - will be read on demand
-            }]);
-        }
-
-        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(),
-            files: Array.from(this.files.entries()),
-            symbols: Array.from(this.symbols.entries()),
-            importGraph: Array.from(this.importGraph.entries()),
-            exportGraph: Array.from(this.exportGraph.entries()),
-            extendsGraph: Array.from(this.extendsGraph.entries()),
-            extendedByGraph: Array.from(this.extendedByGraph.entries()),
-            callsCache: callsCacheData,
-            failedFiles: this.failedFiles ? Array.from(this.failedFiles) : []
-        };
-
-        fs.writeFileSync(cacheFile, JSON.stringify(cacheData));
-        return cacheFile;
-    }
-
-    /**
-     * Load index from cache file
-     *
-     * @param {string} [cachePath] - Optional custom cache path
-     * @returns {boolean} - True if loaded successfully
-     */
-    loadCache(cachePath) {
-        const cacheFile = cachePath || path.join(this.root, '.ucn-cache', 'index.json');
-
-        if (!fs.existsSync(cacheFile)) {
-            return false;
-        }
-
-        try {
-            const cacheData = JSON.parse(fs.readFileSync(cacheFile, 'utf-8'));
-
-            // Check version compatibility
-            // v4 adds className, memberType, isMethod for all languages
-            // Only accept exactly version 4 (or future versions handled explicitly)
-            if (cacheData.version !== 4) {
-                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) ||
-                !Array.isArray(cacheData.importGraph) ||
-                !Array.isArray(cacheData.exportGraph)) {
-                return false;
-            }
-
-            this.files = new Map(cacheData.files);
-            this.symbols = new Map(cacheData.symbols);
-            this.importGraph = new Map(cacheData.importGraph);
-            this.exportGraph = new Map(cacheData.exportGraph);
-            this.buildTime = cacheData.buildTime;
-
-            // Restore optional graphs if present
-            if (Array.isArray(cacheData.extendsGraph)) {
-                this.extendsGraph = new Map(cacheData.extendsGraph);
-            }
-            if (Array.isArray(cacheData.extendedByGraph)) {
-                this.extendedByGraph = new Map(cacheData.extendedByGraph);
-            }
-
-            // Restore callsCache if present (v2+)
-            if (Array.isArray(cacheData.callsCache)) {
-                this.callsCache = new Map(cacheData.callsCache);
-            }
+    /** Save index to cache file */
+    saveCache(cachePath) { return indexCache.saveCache(this, cachePath); }
 
-            // Restore failedFiles if present
-            if (Array.isArray(cacheData.failedFiles)) {
-                this.failedFiles = new Set(cacheData.failedFiles);
-            }
-
-            // Rebuild derived graphs to ensure consistency with current config
-            this.buildImportGraph();
-            this.buildInheritanceGraph();
+    /** Load index from cache file */
+    loadCache(cachePath) { return indexCache.loadCache(this, cachePath); }
 
-            return true;
-        } catch (e) {
-            return false;
-        }
-    }
-
-    /**
-     * Check if cache is stale (any files changed or new files added)
-     *
-     * @returns {boolean} - True if cache needs rebuilding
-     */
-    isCacheStale() {
-        // Check for new files added to project
-        // Use same ignores as build() — .gitignore + .ucn.json exclude
-        const pattern = detectProjectPattern(this.root);
-        const globOpts = { root: this.root };
-        const gitignorePatterns = parseGitignore(this.root);
-        const configExclude = this.config.exclude || [];
-        if (gitignorePatterns.length > 0 || configExclude.length > 0) {
-            globOpts.ignores = [...DEFAULT_IGNORES, ...gitignorePatterns, ...configExclude];
-        }
-        const currentFiles = expandGlob(pattern, globOpts);
-        const cachedPaths = new Set(this.files.keys());
-
-        for (const file of currentFiles) {
-            if (!cachedPaths.has(file) && !(this.failedFiles && this.failedFiles.has(file))) {
-                return true; // New file found
-            }
-        }
-
-        // Check existing cached files for modifications/deletions
-        for (const [filePath, fileEntry] of this.files) {
-            // File deleted
-            if (!fs.existsSync(filePath)) {
-                return true;
-            }
-
-            // File modified - check size first, then mtime, then hash
-            try {
-                const stat = fs.statSync(filePath);
-
-                // If size changed, file changed
-                if (fileEntry.size !== undefined && stat.size !== fileEntry.size) {
-                    return true;
-                }
-
-                // If mtime matches, file hasn't changed
-                if (fileEntry.mtime && stat.mtimeMs === fileEntry.mtime) {
-                    continue;
-                }
-
-                // mtime changed or not stored - verify with hash
-                const content = fs.readFileSync(filePath, 'utf-8');
-                const hash = crypto.createHash('md5').update(content).digest('hex');
-                if (hash !== fileEntry.hash) {
-                    return true;
-                }
-            } catch (e) {
-                return true;
-            }
-        }
-
-        return false;
-    }
+    /** Check if cache is stale (any files changed or new files added) */
+    isCacheStale() { return indexCache.isCacheStale(this); }
 
     /**
      * Find the best usage example of a function.
@@ -5040,74 +3182,8 @@ class ProjectIndex {
         } finally { this._endOp(); }
     }
 
-    /**
-     * Analyze a call site using AST for example scoring.
-     * @private
-     */
-    _analyzeCallSiteAST(filePath, lineNum, funcName) {
-        const result = {
-            isAwait: false, isDestructured: false, isTypedAssignment: false,
-            isInReturn: false, isInCatch: false, isInConditional: false,
-            hasComment: false, isStandalone: false
-        };
-
-        try {
-            const language = detectLanguage(filePath);
-            if (!language) return result;
-
-            const parser = getParser(language);
-            const content = this._readFile(filePath);
-            const tree = safeParse(parser, content);
-            if (!tree) return result;
-
-            const row = lineNum - 1;
-            const node = tree.rootNode.descendantForPosition({ row, column: 0 });
-            if (!node) return result;
-
-            let current = node;
-            let foundCall = false;
-
-            while (current) {
-                const type = current.type;
-
-                if (!foundCall && (type === 'call_expression' || type === 'call')) {
-                    const calleeNode = current.childForFieldName('function') || current.namedChild(0);
-                    if (calleeNode && calleeNode.text === funcName) {
-                        foundCall = true;
-                    }
-                }
-
-                if (foundCall) {
-                    if (type === 'await_expression') result.isAwait = true;
-                    if (type === 'variable_declarator' || type === 'assignment_expression') {
-                        const parent = current.parent;
-                        if (parent && (parent.type === 'lexical_declaration' || parent.type === 'variable_declaration')) {
-                            result.isTypedAssignment = true;
-                        }
-                    }
-                    if (type === 'array_pattern' || type === 'object_pattern') result.isDestructured = true;
-                    if (type === 'return_statement') result.isInReturn = true;
-                    if (type === 'catch_clause' || type === 'except_clause') result.isInCatch = true;
-                    if (type === 'if_statement' || type === 'conditional_expression' || type === 'ternary_expression') result.isInConditional = true;
-                    if (type === 'expression_statement') result.isStandalone = true;
-                }
-
-                current = current.parent;
-            }
-
-            const contentLines = content.split('\n');
-            if (lineNum > 1) {
-                const prevLine = contentLines[lineNum - 2].trim();
-                if (prevLine.startsWith('//') || prevLine.startsWith('#') || prevLine.endsWith('*/')) {
-                    result.hasComment = true;
-                }
-            }
-        } catch (e) {
-            // Return default result on error
-        }
-
-        return result;
-    }
+    /** Analyze a call site using AST for example scoring */
+    _analyzeCallSiteAST(filePath, lineNum, funcName) { return verifyModule.analyzeCallSiteAST(this, filePath, lineNum, funcName); }
 
     /**
      * Diff-based impact analysis: find which functions changed and who calls them
@@ -5128,7 +3204,7 @@ class ProjectIndex {
         // Verify git repo
         let gitRoot;
         try {
-            gitRoot = execSync('git rev-parse --show-toplevel', { cwd: this.root, encoding: 'utf-8' }).trim();
+            gitRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: this.root, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
         } catch (e) {
             throw new Error('Not a git repository. diff-impact requires git.');
         }
@@ -5167,7 +3243,24 @@ class ProjectIndex {
             };
         }
 
-        const changes = parseDiff(diffText, this.root);
+        // Diff paths are git-root-relative. Resolve to this.root for file lookup.
+        // Normalize both through realpath to handle macOS /var → /private/var symlinks.
+        let realGitRoot, realProjectRoot;
+        try { realGitRoot = fs.realpathSync(gitRoot); } catch (_) { realGitRoot = gitRoot; }
+        try { realProjectRoot = fs.realpathSync(this.root); } catch (_) { realProjectRoot = this.root; }
+        const projectPrefix = realGitRoot === realProjectRoot
+            ? ''
+            : path.relative(realGitRoot, realProjectRoot);
+
+        const rawChanges = parseDiff(diffText, gitRoot);
+        // Filter to files under this.root and remap paths.
+        // Preserve gitRelativePath (repo-relative) for git show commands.
+        const changes = [];
+        for (const c of rawChanges) {
+            if (projectPrefix && !c.relativePath.startsWith(projectPrefix + '/')) continue;
+            const localRel = projectPrefix ? c.relativePath.slice(projectPrefix.length + 1) : c.relativePath;
+            changes.push({ ...c, gitRelativePath: c.relativePath, filePath: path.join(this.root, localRel), relativePath: localRel });
+        }
 
         const functions = [];
         const moduleLevelChanges = [];
@@ -5188,8 +3281,8 @@ class ProjectIndex {
                     const ref = staged ? 'HEAD' : base;
                     try {
                         const oldContent = execFileSync(
-                            'git', ['show', `${ref}:${change.relativePath}`],
-                            { cwd: this.root, encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024 }
+                            'git', ['show', `${ref}:${change.gitRelativePath}`],
+                            { cwd: this.root, encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] }
                         );
                         const oldParsed = parse(oldContent, lang);
                         for (const oldFn of extractCallableSymbols(oldParsed)) {
@@ -5292,8 +3385,8 @@ class ProjectIndex {
                 const ref = staged ? 'HEAD' : base;
                 try {
                     const oldContent = execFileSync(
-                        'git', ['show', `${ref}:${change.relativePath}`],
-                        { cwd: this.root, encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024 }
+                        'git', ['show', `${ref}:${change.gitRelativePath}`],
+                        { cwd: this.root, encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] }
                     );
                     const fileLang = detectLanguage(change.filePath);
                     if (fileLang) {