erosolar-cli 1.7.415 → 1.7.417

package/dist/tools/localExplore.js

@@ -0,0 +1,1291 @@
+/**
+ * Local Explore Engine - Claude Code-style codebase exploration.
+ *
+ * This module implements an exploration system that mimics how Claude Code's
+ * explore agent works. It can work fully offline OR use the active AI model
+ * for enhanced query understanding and result summarization.
+ *
+ * Features:
+ * 1. Codebase indexing - Build a searchable index of files, functions, classes, imports
+ * 2. Query processing - Parse natural language questions and map to search strategies
+ * 3. Smart search - Combine glob, grep, and structure analysis
+ * 4. Answer generation - Format results in a Claude Code-like way
+ * 5. Caching - Store the index for fast subsequent queries
+ * 6. AI Enhancement (optional) - Use the active model for better query understanding
+ */
+import { readFileSync, existsSync, readdirSync, statSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, relative, extname, basename, dirname } from 'node:path';
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { buildError } from '../core/errors.js';
+// =====================================================
+// Global AI Enhancer Registry
+// =====================================================
+/**
+ * Global registry for the AI enhancer.
+ * This allows the explore tool to automatically use the active AI model
+ * without requiring explicit wiring at tool creation time.
+ *
+ * Usage:
+ * 1. When a session starts, call: setGlobalAIEnhancer(enhancerFn)
+ * 2. When the session ends, call: setGlobalAIEnhancer(null)
+ * 3. The explore tool will automatically use the registered enhancer
+ */
+let globalAIEnhancer = null;
+/**
+ * Register the global AI enhancer function.
+ * Call this when an AI session becomes available.
+ */
+export function setGlobalAIEnhancer(enhancer) {
+    globalAIEnhancer = enhancer;
+}
+/**
+ * Get the current global AI enhancer.
+ */
+export function getGlobalAIEnhancer() {
+    return globalAIEnhancer;
+}
+/**
+ * Check if an AI enhancer is available (globally or in context).
+ */
+function resolveAIEnhancer(context) {
+    return context.aiEnhancer ?? globalAIEnhancer ?? undefined;
+}
+// =====================================================
+// Constants
+// =====================================================
+const INDEX_VERSION = 1;
+const CACHE_DIR = join(homedir(), '.erosolar', 'explore-cache');
+const IGNORED_DIRS = new Set([
+    'node_modules', '.git', '.svn', '.hg', 'dist', 'build', 'out',
+    '.next', '.nuxt', '.output', 'coverage', '.nyc_output', '.cache',
+    '.turbo', '.vercel', '.netlify', '__pycache__', '.pytest_cache',
+    '.mypy_cache', '.ruff_cache', 'venv', '.venv', 'env', '.env',
+    'target', 'vendor', '.idea', '.vscode',
+]);
+const LANGUAGE_MAP = {
+    '.ts': 'TypeScript', '.tsx': 'TypeScript React', '.js': 'JavaScript',
+    '.jsx': 'JavaScript React', '.mjs': 'JavaScript', '.cjs': 'JavaScript',
+    '.py': 'Python', '.rs': 'Rust', '.go': 'Go', '.java': 'Java',
+    '.kt': 'Kotlin', '.rb': 'Ruby', '.php': 'PHP', '.cs': 'C#',
+    '.cpp': 'C++', '.c': 'C', '.h': 'C/C++ Header', '.swift': 'Swift',
+    '.vue': 'Vue', '.svelte': 'Svelte', '.md': 'Markdown',
+    '.json': 'JSON', '.yaml': 'YAML', '.yml': 'YAML', '.toml': 'TOML',
+};
+// Query type detection patterns
+const QUERY_PATTERNS = [
+    { pattern: /where\s+(?:is|are|can\s+i\s+find)\s+.*(file|module|component)/i, type: 'find_file' },
+    { pattern: /find\s+(?:the\s+)?(?:file|module|component)/i, type: 'find_file' },
+    { pattern: /which\s+file/i, type: 'find_file' },
+    { pattern: /where\s+(?:is|are)\s+(?:the\s+)?(\w+)\s+(?:defined|declared|implemented)/i, type: 'find_symbol' },
+    { pattern: /find\s+(?:the\s+)?(?:function|class|type|interface)\s+/i, type: 'find_symbol' },
+    { pattern: /definition\s+of/i, type: 'find_symbol' },
+    { pattern: /where\s+(?:is\s+)?(\w+)\s+used/i, type: 'find_usage' },
+    { pattern: /who\s+(?:uses|calls|imports)/i, type: 'find_usage' },
+    { pattern: /usages?\s+of/i, type: 'find_usage' },
+    { pattern: /how\s+(?:does|do|is)/i, type: 'understand' },
+    { pattern: /explain\s+(?:the\s+)?(?:how|what)/i, type: 'explain' },
+    { pattern: /what\s+(?:is|are|does)/i, type: 'explain' },
+    { pattern: /architecture|structure|organization|layout/i, type: 'architecture' },
+    { pattern: /dependencies|imports|relationships/i, type: 'dependencies' },
+    { pattern: /./, type: 'search' }, // Default fallback
+];
+// =====================================================
+// Local Explore Engine
+// =====================================================
+export class LocalExploreEngine {
+    workingDir;
+    index = null;
+    indexPath;
+    context;
+    constructor(workingDir, context = {}) {
+        this.workingDir = workingDir;
+        this.context = context;
+        const hash = createHash('md5').update(workingDir).digest('hex').slice(0, 12);
+        this.indexPath = join(CACHE_DIR, `index-${hash}.json`);
+    }
+    /**
+     * Set or update the AI enhancer context.
+     * Call this to enable AI-enhanced exploration with the active model.
+     */
+    setContext(context) {
+        this.context = { ...this.context, ...context };
+    }
+    /**
+     * Initialize or load the codebase index.
+     * Returns true if a fresh index was built.
+     */
+    async initialize(forceRebuild = false) {
+        if (!forceRebuild && this.tryLoadCache()) {
+            return { rebuilt: false, fileCount: this.index.files.length };
+        }
+        this.index = await this.buildIndex();
+        this.saveCache();
+        return { rebuilt: true, fileCount: this.index.files.length };
+    }
+    /**
+     * Process a natural language query and return exploration results.
+     * Automatically uses the active AI model for better results when available.
+     */
+    async explore(query, options) {
+        const startTime = Date.now();
+        if (!this.index) {
+            await this.initialize();
+        }
+        // Resolve AI enhancer (from context or global registry)
+        const useAI = options?.useAI !== false; // Default to true
+        const aiEnhancer = useAI ? resolveAIEnhancer(this.context) : undefined;
+        // Use AI for query parsing if available and enabled
+        let parsedQuery;
+        if (aiEnhancer && this.context.aiQueryParsing !== false) {
+            parsedQuery = await this.parseQueryWithAI(query, aiEnhancer);
+        }
+        else {
+            parsedQuery = this.parseQuery(query);
+        }
+        const result = await this.executeQuery(parsedQuery);
+        // Use AI for result summarization if available and enabled
+        if (aiEnhancer && this.context.aiSummarization !== false && result.files.length + result.symbols.length > 0) {
+            result.answer = await this.summarizeWithAI(query, result, aiEnhancer);
+        }
+        result.timeTaken = Date.now() - startTime;
+        return result;
+    }
+    /**
+     * Use AI to parse a natural language query into structured exploration.
+     */
+    async parseQueryWithAI(query, aiEnhancer) {
+        try {
+            const prompt = `You are helping parse a codebase exploration query. Extract the intent and keywords.
+
+Query: "${query}"
+
+Respond in this exact JSON format (no markdown, just JSON):
+{
+  "type": "find_file" | "find_symbol" | "find_usage" | "understand" | "explain" | "search" | "architecture" | "dependencies",
+  "keywords": ["keyword1", "keyword2"],
+  "symbolKind": "function" | "class" | "type" | "interface" | null,
+  "filePattern": "pattern or null"
+}
+
+Types:
+- find_file: Looking for specific files
+- find_symbol: Looking for function/class/type definitions
+- find_usage: Finding where something is used/called
+- understand/explain: Understanding how something works
+- architecture: Codebase structure overview
+- dependencies: Import/export relationships
+- search: General keyword search`;
+            const response = await aiEnhancer(prompt);
+            // Parse the JSON response
+            const jsonMatch = response.match(/\{[\s\S]*\}/);
+            if (jsonMatch) {
+                const parsed = JSON.parse(jsonMatch[0]);
+                return {
+                    type: parsed.type || 'search',
+                    keywords: Array.isArray(parsed.keywords) ? parsed.keywords : [query],
+                    filters: {
+                        symbolKind: parsed.symbolKind || undefined,
+                        filePattern: parsed.filePattern || undefined,
+                        limit: 10,
+                    },
+                    originalQuery: query,
+                };
+            }
+        }
+        catch {
+            // Fall back to rule-based parsing
+        }
+        return this.parseQuery(query);
+    }
+    /**
+     * Use AI to generate a natural language summary of exploration results.
+     */
+    async summarizeWithAI(query, result, aiEnhancer) {
+        try {
+            const filesInfo = result.files.slice(0, 5).map(f => `- ${f.path}: ${f.reason}`).join('\n');
+            const symbolsInfo = result.symbols.slice(0, 5).map(s => `- ${s.name} (${s.kind}) at ${s.file}:${s.line}`).join('\n');
+            const prompt = `Summarize these codebase exploration results concisely.
+
+User asked: "${query}"
+
+Files found (${result.files.length} total):
+${filesInfo || 'None'}
+
+Symbols found (${result.symbols.length} total):
+${symbolsInfo || 'None'}
+
+Provide a helpful 2-4 sentence summary that directly answers the user's question. Include the most relevant file paths. Be specific and actionable.`;
+            const summary = await aiEnhancer(prompt);
+            return summary.trim();
+        }
+        catch {
+            return result.answer;
+        }
+    }
+    /**
+     * Get a quick overview of the codebase.
+     */
+    getOverview() {
+        if (!this.index) {
+            return 'Index not loaded. Call initialize() first.';
+        }
+        const idx = this.index;
+        const lines = [
+            `# Codebase Overview: ${basename(idx.rootDir)}`,
+            '',
+            `**Files indexed:** ${idx.files.length}`,
+            `**Last indexed:** ${idx.createdAt}`,
+            '',
+            '## Quick Access',
+            '',
+        ];
+        if (idx.quickLookup.entryPoints.length) {
+            lines.push(`**Entry Points:** ${idx.quickLookup.entryPoints.slice(0, 5).join(', ')}`);
+        }
+        if (idx.quickLookup.configFiles.length) {
+            lines.push(`**Config Files:** ${idx.quickLookup.configFiles.slice(0, 5).join(', ')}`);
+        }
+        if (idx.quickLookup.testFiles.length) {
+            lines.push(`**Test Files:** ${idx.quickLookup.testFiles.length} files`);
+        }
+        lines.push('', '## Architecture');
+        if (idx.patterns.architecture.length) {
+            lines.push(`**Detected:** ${idx.patterns.architecture.join(', ')}`);
+        }
+        if (idx.patterns.designPatterns.length) {
+            lines.push(`**Patterns:** ${idx.patterns.designPatterns.slice(0, 5).join(', ')}`);
+        }
+        return lines.join('\n');
+    }
+    // =====================================================
+    // Private Methods
+    // =====================================================
+    tryLoadCache() {
+        try {
+            if (!existsSync(this.indexPath)) {
+                return false;
+            }
+            const content = readFileSync(this.indexPath, 'utf-8');
+            const cached = JSON.parse(content);
+            // Check version and hash
+            if (cached.version !== INDEX_VERSION) {
+                return false;
+            }
+            // Quick validation: check if file count roughly matches
+            const currentFileCount = this.countFiles(this.workingDir, 0, 4);
+            const cachedFileCount = cached.files.length;
+            const drift = Math.abs(currentFileCount - cachedFileCount);
+            // Allow 10% drift before rebuilding
+            if (drift > cachedFileCount * 0.1 && drift > 10) {
+                return false;
+            }
+            // Restore Map objects from JSON
+            this.index = {
+                ...cached,
+                symbols: {
+                    byName: new Map(Object.entries(cached.symbols.byName || {})),
+                    byKind: new Map(Object.entries(cached.symbols.byKind || {})),
+                    byFile: new Map(Object.entries(cached.symbols.byFile || {})),
+                },
+                imports: {
+                    imports: new Map(Object.entries(cached.imports.imports || {})),
+                    importedBy: new Map(Object.entries(cached.imports.importedBy || {})),
+                },
+            };
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    saveCache() {
+        try {
+            mkdirSync(CACHE_DIR, { recursive: true });
+            // Convert Maps to objects for JSON serialization
+            const serializable = {
+                ...this.index,
+                symbols: {
+                    byName: Object.fromEntries(this.index.symbols.byName),
+                    byKind: Object.fromEntries(this.index.symbols.byKind),
+                    byFile: Object.fromEntries(this.index.symbols.byFile),
+                },
+                imports: {
+                    imports: Object.fromEntries(this.index.imports.imports),
+                    importedBy: Object.fromEntries(this.index.imports.importedBy),
+                },
+            };
+            writeFileSync(this.indexPath, JSON.stringify(serializable, null, 2));
+        }
+        catch {
+            // Ignore cache save errors
+        }
+    }
+    countFiles(dir, depth, maxDepth) {
+        if (depth >= maxDepth)
+            return 0;
+        let count = 0;
+        try {
+            const entries = readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.name.startsWith('.') || IGNORED_DIRS.has(entry.name))
+                    continue;
+                if (entry.isDirectory()) {
+                    count += this.countFiles(join(dir, entry.name), depth + 1, maxDepth);
+                }
+                else if (entry.isFile() && LANGUAGE_MAP[extname(entry.name).toLowerCase()]) {
+                    count++;
+                }
+            }
+        }
+        catch {
+            // Ignore errors
+        }
+        return count;
+    }
+    async buildIndex() {
+        const files = [];
+        const symbolsByName = new Map();
+        const symbolsByKind = new Map();
+        const symbolsByFile = new Map();
+        const importsMap = new Map();
+        const importedByMap = new Map();
+        const quickLookup = {
+            entryPoints: [],
+            configFiles: [],
+            testFiles: [],
+            componentFiles: [],
+            typeFiles: [],
+            utilityFiles: [],
+            routeFiles: [],
+            modelFiles: [],
+        };
+        const patterns = {
+            architecture: [],
+            designPatterns: [],
+            namingConventions: [],
+            testPatterns: [],
+            componentPatterns: [],
+        };
+        // Collect all files
+        const allFiles = this.collectFiles(this.workingDir, 0, 6);
+        // Index each file
+        for (const filePath of allFiles) {
+            try {
+                const indexed = this.indexFile(filePath);
+                if (!indexed)
+                    continue;
+                files.push(indexed);
+                // Build symbol index
+                const relPath = indexed.path;
+                const fileSymbols = [];
+                for (const sym of [...indexed.symbols.functions, ...indexed.symbols.classes,
+                    ...indexed.symbols.interfaces, ...indexed.symbols.types]) {
+                    const location = {
+                        file: relPath,
+                        line: sym.line,
+                        kind: sym.kind,
+                        signature: sym.signature,
+                    };
+                    // By name
+                    const existing = symbolsByName.get(sym.name.toLowerCase()) || [];
+                    existing.push(location);
+                    symbolsByName.set(sym.name.toLowerCase(), existing);
+                    // By kind
+                    const byKind = symbolsByKind.get(sym.kind) || [];
+                    byKind.push(location);
+                    symbolsByKind.set(sym.kind, byKind);
+                    fileSymbols.push(sym.name);
+                }
+                symbolsByFile.set(relPath, fileSymbols);
+                // Build import graph
+                importsMap.set(relPath, indexed.imports);
+                for (const imp of indexed.imports) {
+                    const existing = importedByMap.get(imp) || [];
+                    existing.push(relPath);
+                    importedByMap.set(imp, existing);
+                }
+                // Categorize files
+                this.categorizeFile(indexed, quickLookup);
+            }
+            catch {
+                // Skip files we can't index
+            }
+        }
+        // Detect patterns
+        this.detectPatterns(files, patterns);
+        // Create hash for cache validation
+        const hash = createHash('md5')
+            .update(files.map(f => f.path).sort().join('\n'))
+            .digest('hex');
+        return {
+            version: INDEX_VERSION,
+            createdAt: new Date().toISOString(),
+            rootDir: this.workingDir,
+            hash,
+            files,
+            symbols: {
+                byName: symbolsByName,
+                byKind: symbolsByKind,
+                byFile: symbolsByFile,
+            },
+            imports: {
+                imports: importsMap,
+                importedBy: importedByMap,
+            },
+            patterns,
+            quickLookup,
+        };
+    }
+    collectFiles(dir, depth, maxDepth) {
+        if (depth >= maxDepth)
+            return [];
+        const files = [];
+        try {
+            const entries = readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.name.startsWith('.') || IGNORED_DIRS.has(entry.name))
+                    continue;
+                const fullPath = join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    files.push(...this.collectFiles(fullPath, depth + 1, maxDepth));
+                }
+                else if (entry.isFile()) {
+                    const ext = extname(entry.name).toLowerCase();
+                    if (LANGUAGE_MAP[ext]) {
+                        files.push(fullPath);
+                    }
+                }
+            }
+        }
+        catch {
+            // Ignore errors
+        }
+        return files;
+    }
+    indexFile(filePath) {
+        try {
+            const stat = statSync(filePath);
+            if (stat.size > 500000)
+                return null; // Skip large files
+            const content = readFileSync(filePath, 'utf-8');
+            const lines = content.split('\n');
+            const ext = extname(filePath).toLowerCase();
+            const language = LANGUAGE_MAP[ext] || 'Unknown';
+            const relPath = relative(this.workingDir, filePath);
+            const symbols = this.extractSymbols(content, ext);
+            const imports = this.extractImports(content, ext);
+            const exports = this.extractExports(content, ext);
+            const purpose = this.inferPurpose(basename(filePath), content, symbols);
+            const tags = this.generateTags(relPath, content, symbols, purpose);
+            return {
+                path: relPath,
+                language,
+                size: stat.size,
+                lineCount: lines.length,
+                lastModified: stat.mtimeMs,
+                symbols,
+                imports,
+                exports,
+                purpose,
+                tags,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    extractSymbols(content, ext) {
+        const symbols = {
+            functions: [],
+            classes: [],
+            interfaces: [],
+            types: [],
+            constants: [],
+            variables: [],
+        };
+        if (!['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'].includes(ext)) {
+            return symbols; // Only analyze JS/TS for now
+        }
+        const lines = content.split('\n');
+        // Extract functions
+        const funcRegex = /(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*\(([^)]*)\)/g;
+        let match;
+        while ((match = funcRegex.exec(content)) !== null) {
+            const line = content.substring(0, match.index).split('\n').length;
+            symbols.functions.push({
+                name: match[1] || '',
+                line,
+                kind: 'function',
+                isExported: content.substring(match.index - 20, match.index).includes('export'),
+                signature: `${match[1]}(${match[2]})`,
+            });
+        }
+        // Arrow functions
+        const arrowRegex = /(?:export\s+)?(?:const|let)\s+(\w+)\s*=\s*(?:async\s+)?\(?([^)=]*)\)?\s*=>/g;
+        while ((match = arrowRegex.exec(content)) !== null) {
+            const line = content.substring(0, match.index).split('\n').length;
+            symbols.functions.push({
+                name: match[1] || '',
+                line,
+                kind: 'function',
+                isExported: content.substring(match.index - 20, match.index).includes('export'),
+                signature: `${match[1]}(${match[2] || ''})`,
+            });
+        }
+        // Classes
+        const classRegex = /(?:export\s+)?class\s+(\w+)(?:\s+extends\s+(\w+))?/g;
+        while ((match = classRegex.exec(content)) !== null) {
+            const line = content.substring(0, match.index).split('\n').length;
+            symbols.classes.push({
+                name: match[1] || '',
+                line,
+                kind: 'class',
+                isExported: content.substring(match.index - 20, match.index).includes('export'),
+                signature: match[2] ? `class ${match[1]} extends ${match[2]}` : `class ${match[1]}`,
+            });
+        }
+        // Interfaces
+        const interfaceRegex = /(?:export\s+)?interface\s+(\w+)(?:\s+extends\s+([^{]+))?/g;
+        while ((match = interfaceRegex.exec(content)) !== null) {
+            const line = content.substring(0, match.index).split('\n').length;
+            symbols.interfaces.push({
+                name: match[1] || '',
+                line,
+                kind: 'interface',
+                isExported: content.substring(match.index - 20, match.index).includes('export'),
+                signature: `interface ${match[1]}`,
+            });
+        }
+        // Types
+        const typeRegex = /(?:export\s+)?type\s+(\w+)\s*=/g;
+        while ((match = typeRegex.exec(content)) !== null) {
+            const line = content.substring(0, match.index).split('\n').length;
+            symbols.types.push({
+                name: match[1] || '',
+                line,
+                kind: 'type',
+                isExported: content.substring(match.index - 20, match.index).includes('export'),
+                signature: `type ${match[1]}`,
+            });
+        }
+        // Constants
+        const constRegex = /(?:export\s+)?const\s+([A-Z][A-Z_0-9]+)\s*=/g;
+        while ((match = constRegex.exec(content)) !== null) {
+            const line = content.substring(0, match.index).split('\n').length;
+            symbols.constants.push({
+                name: match[1] || '',
+                line,
+                kind: 'const',
+                isExported: content.substring(match.index - 20, match.index).includes('export'),
+            });
+        }
+        return symbols;
+    }
+    extractImports(content, ext) {
+        const imports = [];
+        if (!['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'].includes(ext)) {
+            return imports;
+        }
+        // ES6 imports
+        const importRegex = /import\s+.*?\s+from\s+['"]([^'"]+)['"]/g;
+        let match;
+        while ((match = importRegex.exec(content)) !== null) {
+            const source = match[1] || '';
+            if (source.startsWith('.')) {
+                // Resolve relative imports
+                imports.push(source);
+            }
+        }
+        return imports;
+    }
+    extractExports(content, ext) {
+        const exports = [];
+        if (!['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'].includes(ext)) {
+            return exports;
+        }
+        // Named exports
+        const namedExportRegex = /export\s+(?:const|let|var|function|class|interface|type|enum)\s+(\w+)/g;
+        let match;
+        while ((match = namedExportRegex.exec(content)) !== null) {
+            if (match[1])
+                exports.push(match[1]);
+        }
+        // Default export
+        if (/export\s+default/.test(content)) {
+            exports.push('default');
+        }
+        return exports;
+    }
+    inferPurpose(filename, content, symbols) {
+        const lower = filename.toLowerCase();
+        if (lower.includes('test') || lower.includes('spec'))
+            return 'Test file';
+        if (lower === 'index.ts' || lower === 'index.js')
+            return 'Module entry point';
+        if (lower.includes('config'))
+            return 'Configuration';
+        if (lower.includes('type') || lower.includes('interface'))
+            return 'Type definitions';
+        if (lower.includes('util') || lower.includes('helper'))
+            return 'Utilities';
+        if (lower.includes('hook'))
+            return 'React hooks';
+        if (lower.includes('context'))
+            return 'Context provider';
+        if (lower.includes('store') || lower.includes('reducer'))
+            return 'State management';
+        if (lower.includes('service'))
+            return 'Business logic';
+        if (lower.includes('api') || lower.includes('client'))
+            return 'API client';
+        if (lower.includes('route'))
+            return 'Routes';
+        if (lower.includes('middleware'))
+            return 'Middleware';
+        if (lower.includes('model') || lower.includes('entity'))
+            return 'Data models';
+        if (lower.includes('schema'))
+            return 'Schema definitions';
+        if (lower.includes('component'))
+            return 'UI component';
+        if (symbols.classes.length > 0)
+            return `Class: ${symbols.classes[0]?.name}`;
+        if (symbols.interfaces.length > 0)
+            return `Types/Interfaces`;
+        if (symbols.functions.length > 0)
+            return `Functions: ${symbols.functions.slice(0, 3).map(f => f.name).join(', ')}`;
+        return 'General module';
+    }
+    generateTags(path, content, symbols, purpose) {
+        const tags = [];
+        // Add purpose-based tags
+        tags.push(purpose.toLowerCase().split(':')[0] || '');
+        // Add path-based tags
+        const parts = path.split('/');
+        for (const part of parts.slice(0, -1)) {
+            if (part && !part.startsWith('.')) {
+                tags.push(part.toLowerCase());
+            }
+        }
+        // Add symbol-based tags
+        for (const sym of symbols.functions) {
+            if (sym.isExported)
+                tags.push(sym.name.toLowerCase());
+        }
+        for (const sym of symbols.classes) {
+            if (sym.isExported)
+                tags.push(sym.name.toLowerCase());
+        }
+        // Add content-based tags
+        if (/useEffect|useState|useCallback/.test(content))
+            tags.push('react', 'hooks');
+        if (/async\s+function|await\s+/.test(content))
+            tags.push('async');
+        if (/express|fastify|koa/.test(content))
+            tags.push('server', 'http');
+        if (/import.*prisma|import.*mongoose/.test(content))
+            tags.push('database');
+        if (/import.*zod|import.*yup|import.*joi/.test(content))
+            tags.push('validation');
+        if (/describe\s*\(|it\s*\(|test\s*\(/.test(content))
+            tags.push('test');
+        return [...new Set(tags.filter(Boolean))];
+    }
+    categorizeFile(file, lookup) {
+        const lower = file.path.toLowerCase();
+        const name = basename(file.path).toLowerCase();
+        // Entry points
+        if (['index.ts', 'index.js', 'main.ts', 'main.js', 'app.ts', 'app.js'].includes(name)) {
+            lookup.entryPoints.push(file.path);
+        }
+        // Config files
+        if (name.includes('config') || name.includes('settings') || name.includes('.rc')) {
+            lookup.configFiles.push(file.path);
+        }
+        // Test files
+        if (lower.includes('test') || lower.includes('spec') || lower.includes('__tests__')) {
+            lookup.testFiles.push(file.path);
+        }
+        // Component files
+        if (lower.includes('component') || lower.includes('components/') ||
+            file.language.includes('React')) {
+            lookup.componentFiles.push(file.path);
+        }
+        // Type files
+        if (lower.includes('type') || lower.includes('interface') || name.endsWith('.d.ts')) {
+            lookup.typeFiles.push(file.path);
+        }
+        // Utility files
+        if (lower.includes('util') || lower.includes('helper') || lower.includes('lib/')) {
+            lookup.utilityFiles.push(file.path);
+        }
+        // Route files
+        if (lower.includes('route') || lower.includes('api/')) {
+            lookup.routeFiles.push(file.path);
+        }
+        // Model files
+        if (lower.includes('model') || lower.includes('entity') || lower.includes('schema')) {
+            lookup.modelFiles.push(file.path);
+        }
+    }
+    detectPatterns(files, patterns) {
+        const dirs = new Set();
+        for (const file of files) {
+            const dir = dirname(file.path);
+            dirs.add(dir.split('/')[0] || dir);
+        }
+        // Detect architecture patterns
+        if (dirs.has('src') && (dirs.has('components') || dirs.has('views'))) {
+            patterns.architecture.push('Component-based');
+        }
+        if (dirs.has('api') || dirs.has('routes')) {
+            patterns.architecture.push('API-driven');
+        }
+        if (dirs.has('services') && dirs.has('controllers')) {
+            patterns.architecture.push('Layered');
+        }
+        if (dirs.has('domain') || dirs.has('entities')) {
+            patterns.architecture.push('Domain-driven');
+        }
+        // Detect design patterns
+        const allContent = files.slice(0, 50).map(f => {
+            try {
+                return readFileSync(join(this.workingDir, f.path), 'utf-8');
+            }
+            catch {
+                return '';
+            }
+        }).join('\n');
+        if (/singleton|getInstance/i.test(allContent))
+            patterns.designPatterns.push('Singleton');
+        if (/factory|create\w+/i.test(allContent))
+            patterns.designPatterns.push('Factory');
+        if (/observer|subscribe|emit/i.test(allContent))
+            patterns.designPatterns.push('Observer');
+        if (/strategy|\bstrategy\b/i.test(allContent))
+            patterns.designPatterns.push('Strategy');
+        if (/decorator|@\w+/i.test(allContent))
+            patterns.designPatterns.push('Decorator');
+        // Detect naming conventions
+        const fileNames = files.map(f => basename(f.path, extname(f.path)));
+        if (fileNames.some(n => /[a-z]+-[a-z]+/.test(n)))
+            patterns.namingConventions.push('kebab-case');
+        if (fileNames.some(n => /[a-z]+[A-Z]/.test(n)))
+            patterns.namingConventions.push('camelCase');
+        if (fileNames.some(n => /^[A-Z][a-z]+[A-Z]/.test(n)))
+            patterns.namingConventions.push('PascalCase');
+        if (fileNames.some(n => /[a-z]+_[a-z]+/.test(n)))
+            patterns.namingConventions.push('snake_case');
+    }
+    parseQuery(query) {
+        const normalized = query.trim().toLowerCase();
+        let type = 'search';
+        for (const { pattern, type: queryType } of QUERY_PATTERNS) {
+            if (pattern.test(query)) {
+                type = queryType;
+                break;
+            }
+        }
+        // Extract keywords
+        const stopWords = new Set(['the', 'a', 'an', 'is', 'are', 'where', 'what', 'how', 'which', 'find', 'show', 'get', 'me', 'i', 'can', 'do', 'does', 'for', 'to', 'in', 'of']);
+        const keywords = normalized
+            .replace(/[^\w\s]/g, ' ')
+            .split(/\s+/)
+            .filter(w => w.length > 2 && !stopWords.has(w));
+        // Extract filters from query
+        const filters = { limit: 10 };
+        // File pattern filter
+        const fileMatch = query.match(/(?:in|from|file)\s+([^\s]+\.[a-z]+)/i);
+        if (fileMatch) {
+            filters.filePattern = fileMatch[1];
+        }
+        // Language filter
+        const langMatch = query.match(/(typescript|javascript|python|rust|go)/i);
+        if (langMatch) {
+            filters.language = langMatch[1];
+        }
+        // Symbol kind filter
+        const kindMatch = query.match(/(function|class|type|interface|constant)/i);
+        if (kindMatch && kindMatch[1]) {
+            filters.symbolKind = kindMatch[1].toLowerCase();
+        }
+        return {
+            type,
+            keywords,
+            filters,
+            originalQuery: query,
+        };
+    }
+    async executeQuery(query) {
+        const result = {
+            query: query.originalQuery,
+            queryType: query.type,
+            files: [],
+            symbols: [],
+            answer: '',
+            suggestions: [],
+            timeTaken: 0,
+        };
+        switch (query.type) {
+            case 'find_file':
+                this.findFiles(query, result);
+                break;
+            case 'find_symbol':
+                this.findSymbols(query, result);
+                break;
+            case 'find_usage':
+                this.findUsages(query, result);
+                break;
+            case 'architecture':
+                this.explainArchitecture(query, result);
+                break;
+            case 'dependencies':
+                this.showDependencies(query, result);
+                break;
+            case 'understand':
+            case 'explain':
+                this.explainConcept(query, result);
+                break;
+            case 'search':
+            default:
+                this.generalSearch(query, result);
+                break;
+        }
+        // Generate suggestions
+        this.generateSuggestions(query, result);
+        return result;
+    }
+    findFiles(query, result) {
+        const matches = [];
+        for (const file of this.index.files) {
+            let relevance = 0;
+            for (const keyword of query.keywords) {
+                const keywordLower = keyword.toLowerCase();
+                // Match in path
+                if (file.path.toLowerCase().includes(keywordLower)) {
+                    relevance += 10;
+                }
+                // Match in tags
+                if (file.tags.some(t => t.includes(keywordLower))) {
+                    relevance += 5;
+                }
+                // Match in purpose
+                if (file.purpose.toLowerCase().includes(keywordLower)) {
+                    relevance += 3;
+                }
+                // Match symbol names
+                const allSymbols = [...file.symbols.functions, ...file.symbols.classes];
+                if (allSymbols.some(s => s.name.toLowerCase().includes(keywordLower))) {
+                    relevance += 7;
+                }
+            }
+            // Apply filters
+            if (query.filters.filePattern && !file.path.includes(query.filters.filePattern)) {
+                relevance = 0;
+            }
+            if (query.filters.language && !file.language.toLowerCase().includes(query.filters.language.toLowerCase())) {
+                relevance = 0;
+            }
+            if (relevance > 0) {
+                matches.push({
+                    path: file.path,
+                    relevance,
+                    reason: file.purpose,
+                });
+            }
+        }
+        // Sort by relevance and limit
+        matches.sort((a, b) => b.relevance - a.relevance);
+        result.files = matches.slice(0, query.filters.limit || 10);
+        // Generate answer
+        if (result.files.length > 0) {
+            const topFiles = result.files.slice(0, 5);
+            result.answer = [
+                `Found ${result.files.length} relevant file(s) for "${query.keywords.join(' ')}":`,
+                '',
+                ...topFiles.map(f => `• **${f.path}** - ${f.reason}`),
+                result.files.length > 5 ? `\n...and ${result.files.length - 5} more files` : '',
+            ].join('\n');
+        }
+        else {
+            result.answer = `No files found matching "${query.keywords.join(' ')}". Try different keywords or check the spelling.`;
+        }
+    }
+    findSymbols(query, result) {
+        const matches = [];
+        for (const keyword of query.keywords) {
+            const keywordLower = keyword.toLowerCase();
+            const locations = this.index.symbols.byName.get(keywordLower) || [];
+            for (const loc of locations) {
+                // Check kind filter
+                if (query.filters.symbolKind && loc.kind !== query.filters.symbolKind) {
+                    continue;
+                }
+                matches.push({
+                    name: keyword,
+                    file: loc.file,
+                    line: loc.line,
+                    kind: loc.kind,
+                    relevance: 10,
+                });
+            }
+        }
+        // Also search partial matches
+        for (const [name, locations] of this.index.symbols.byName) {
+            for (const keyword of query.keywords) {
+                if (name.includes(keyword.toLowerCase()) && !matches.some(m => m.name === name)) {
+                    for (const loc of locations) {
+                        if (query.filters.symbolKind && loc.kind !== query.filters.symbolKind)
+                            continue;
+                        matches.push({
+                            name,
+                            file: loc.file,
+                            line: loc.line,
+                            kind: loc.kind,
+                            relevance: 5,
+                        });
+                    }
+                }
+            }
+        }
+        matches.sort((a, b) => b.relevance - a.relevance);
+        result.symbols = matches.slice(0, query.filters.limit || 10);
+        // Generate answer
+        if (result.symbols.length > 0) {
+            const topSymbols = result.symbols.slice(0, 5);
+            result.answer = [
+                `Found ${result.symbols.length} symbol(s) matching "${query.keywords.join(' ')}":`,
+                '',
+                ...topSymbols.map(s => `• **${s.name}** (${s.kind}) at ${s.file}:${s.line}`),
+                result.symbols.length > 5 ? `\n...and ${result.symbols.length - 5} more symbols` : '',
+            ].join('\n');
+        }
+        else {
+            result.answer = `No symbols found matching "${query.keywords.join(' ')}".`;
+        }
+    }
+    findUsages(query, result) {
+        for (const keyword of query.keywords) {
+            const keywordLower = keyword.toLowerCase();
+            // Find files that import this symbol
+            for (const file of this.index.files) {
+                // Check if file content mentions the keyword
+                const fullPath = join(this.workingDir, file.path);
+                try {
+                    const content = readFileSync(fullPath, 'utf-8');
+                    if (content.toLowerCase().includes(keywordLower)) {
+                        const lines = content.split('\n');
+                        const matchingLines = lines
+                            .map((line, i) => ({ line, num: i + 1 }))
+                            .filter(({ line }) => line.toLowerCase().includes(keywordLower))
+                            .slice(0, 3);
+                        result.files.push({
+                            path: file.path,
+                            relevance: matchingLines.length * 3,
+                            reason: `Used on line${matchingLines.length > 1 ? 's' : ''} ${matchingLines.map(l => l.num).join(', ')}`,
+                            snippets: matchingLines.map(l => l.line.trim()),
+                        });
+                    }
+                }
+                catch {
+                    // Skip unreadable files
+                }
+            }
+        }
+        result.files.sort((a, b) => b.relevance - a.relevance);
+        result.files = result.files.slice(0, query.filters.limit || 10);
+        if (result.files.length > 0) {
+            result.answer = [
+                `Found ${result.files.length} file(s) using "${query.keywords.join(' ')}":`,
+                '',
+                ...result.files.slice(0, 5).map(f => `• **${f.path}** - ${f.reason}`),
+            ].join('\n');
+        }
+        else {
+            result.answer = `No usages found for "${query.keywords.join(' ')}".`;
+        }
+    }
+    explainArchitecture(_query, result) {
+        const patterns = this.index.patterns;
+        const lookup = this.index.quickLookup;
+        const lines = [
+            '# Architecture Overview',
+            '',
+        ];
+        if (patterns.architecture.length) {
+            lines.push(`**Architectural Style:** ${patterns.architecture.join(', ')}`);
+            lines.push('');
+        }
+        if (patterns.designPatterns.length) {
+            lines.push(`**Design Patterns:** ${patterns.designPatterns.join(', ')}`);
+            lines.push('');
+        }
+        lines.push('## Key Areas');
+        lines.push('');
+        if (lookup.entryPoints.length) {
+            lines.push(`**Entry Points:** ${lookup.entryPoints.slice(0, 3).join(', ')}`);
+        }
+        if (lookup.componentFiles.length) {
+            lines.push(`**Components:** ${lookup.componentFiles.length} files`);
+        }
+        if (lookup.routeFiles.length) {
+            lines.push(`**Routes/API:** ${lookup.routeFiles.length} files`);
+        }
+        if (lookup.modelFiles.length) {
+            lines.push(`**Models:** ${lookup.modelFiles.length} files`);
+        }
+        if (lookup.testFiles.length) {
+            lines.push(`**Tests:** ${lookup.testFiles.length} files`);
+        }
+        if (patterns.namingConventions.length) {
+            lines.push('');
+            lines.push(`**Naming Conventions:** ${patterns.namingConventions.join(', ')}`);
+        }
+        result.answer = lines.join('\n');
+    }
+    showDependencies(query, result) {
+        // Find the most relevant file
+        const targetFile = query.keywords.length > 0
+            ? this.index.files.find(f => query.keywords.some(k => f.path.toLowerCase().includes(k.toLowerCase())))
+            : this.index.quickLookup.entryPoints[0];
+        if (!targetFile) {
+            result.answer = 'Specify a file to show dependencies for.';
+            return;
+        }
+        const filePath = typeof targetFile === 'string' ? targetFile : targetFile.path;
+        const imports = this.index.imports.imports.get(filePath) || [];
+        const importedBy = this.index.imports.importedBy.get(filePath) || [];
+        const lines = [
+            `# Dependencies for ${filePath}`,
+            '',
+            '## Imports (dependencies)',
+            imports.length ? imports.map(i => `• ${i}`).join('\n') : 'No local imports',
+            '',
+            '## Imported by (dependents)',
+            importedBy.length ? importedBy.map(i => `• ${i}`).join('\n') : 'Not imported by other files',
+        ];
+        result.answer = lines.join('\n');
+    }
+    explainConcept(query, result) {
+        // Combine file and symbol search for conceptual queries
+        this.findFiles(query, result);
+        this.findSymbols(query, result);
+        // Enhanced answer
+        const allMatches = result.files.length + result.symbols.length;
+        if (allMatches > 0) {
+            const parts = [
+                `Found ${allMatches} relevant result(s) for "${query.keywords.join(' ')}":`,
+                '',
+            ];
+            if (result.symbols.length > 0) {
+                parts.push('**Symbols:**');
+                for (const s of result.symbols.slice(0, 3)) {
+                    parts.push(`• ${s.name} (${s.kind}) at ${s.file}:${s.line}`);
+                }
+                parts.push('');
+            }
+            if (result.files.length > 0) {
+                parts.push('**Files:**');
+                for (const f of result.files.slice(0, 3)) {
+                    parts.push(`• ${f.path} - ${f.reason}`);
+                }
+            }
+            result.answer = parts.join('\n');
+        }
+    }
+    generalSearch(query, result) {
+        // Combine all search methods
+        this.findFiles(query, result);
+        const fileMatches = [...result.files];
+        result.files = [];
+        this.findSymbols(query, result);
+        const symbolMatches = [...result.symbols];
+        // Merge results
+        result.files = fileMatches;
+        result.symbols = symbolMatches;
+        // Generate combined answer
+        const parts = [];
+        if (symbolMatches.length > 0) {
+            parts.push(`**Symbols (${symbolMatches.length}):**`);
+            for (const s of symbolMatches.slice(0, 5)) {
+                parts.push(`  • ${s.name} (${s.kind}) → ${s.file}:${s.line}`);
+            }
+        }
+        if (fileMatches.length > 0) {
+            if (parts.length)
+                parts.push('');
+            parts.push(`**Files (${fileMatches.length}):**`);
+            for (const f of fileMatches.slice(0, 5)) {
+                parts.push(`  • ${f.path} - ${f.reason}`);
+            }
+        }
+        if (parts.length === 0) {
+            result.answer = `No results found for "${query.keywords.join(' ')}". Try different terms.`;
+        }
+        else {
+            result.answer = parts.join('\n');
+        }
+    }
+    generateSuggestions(query, result) {
+        result.suggestions = [];
+        if (result.files.length > 0) {
+            result.suggestions.push(`Explore: ${result.files[0]?.path}`);
+        }
+        if (query.type === 'find_file' && result.files.length === 0) {
+            result.suggestions.push('Try broader search terms');
+            result.suggestions.push('Check the architecture overview: "show architecture"');
+        }
+        if (query.type === 'find_symbol') {
+            result.suggestions.push('Find usages: "where is X used"');
+        }
+        // Suggest related queries based on patterns
+        const patterns = this.index.patterns;
+        if (patterns.designPatterns.length > 0) {
+            result.suggestions.push(`Explore pattern: ${patterns.designPatterns[0]}`);
+        }
+    }
+}
+export function createLocalExploreTool(workingDir, options) {
+    const context = {
+        aiEnhancer: options?.aiEnhancer,
+        aiQueryParsing: options?.aiQueryParsing,
+        aiSummarization: options?.aiSummarization,
+    };
+    const engine = new LocalExploreEngine(workingDir, context);
+    let initialized = false;
+    // Store reference for dynamic AI enhancer updates
+    const toolState = { engine, context };
+    return {
+        name: 'explore',
+        description: `Explore and understand the codebase using natural language queries.
+Works offline by default, but uses the active AI model for better results when available.
+
+Example queries:
+- "Where is authentication handled?"
+- "Find the UserService class"
+- "Show architecture overview"
+- "Where is handleSubmit used?"
+- "What are the entry points?"
+- "Show dependencies for src/app.ts"
+
+Returns file locations, symbol definitions, and explanations.`,
+        parameters: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Natural language query about the codebase',
+                },
+                rebuild: {
+                    type: 'boolean',
+                    description: 'Force rebuild of the codebase index (default: false)',
+                },
+                useAI: {
+                    type: 'boolean',
+                    description: 'Use AI for enhanced results (default: true if AI is available)',
+                },
+            },
+            required: ['query'],
+            additionalProperties: false,
+        },
+        cacheable: false,
+        // Expose engine for dynamic context updates
+        _engine: toolState,
+        handler: async (args) => {
+            try {
+                const query = args['query'];
+                const rebuild = args['rebuild'] === true;
+                const useAI = args['useAI'] !== false; // Default to true - AI is used by default
+                if (!query || !query.trim()) {
+                    return 'Error: query must be a non-empty string';
+                }
+                // Initialize on first use
+                if (!initialized || rebuild) {
+                    const { rebuilt, fileCount } = await toolState.engine.initialize(rebuild);
+                    initialized = true;
+                    if (rebuilt) {
+                        const exploreResult = await toolState.engine.explore(query, { useAI });
+                        return `Indexed ${fileCount} files. Now exploring: "${query}"\n\n${exploreResult.answer}`;
+                    }
+                }
+                // Handle special queries
+                if (query.toLowerCase() === 'overview' || query.toLowerCase() === 'help') {
+                    return toolState.engine.getOverview();
+                }
+                // Execute exploration (AI is used by default when available)
+                const result = await toolState.engine.explore(query, { useAI });
+                // Format output
+                const lines = [result.answer];
+                if (result.suggestions.length > 0 && result.files.length + result.symbols.length < 3) {
+                    lines.push('');
+                    lines.push('**Suggestions:**');
+                    for (const s of result.suggestions.slice(0, 3)) {
+                        lines.push(`• ${s}`);
+                    }
+                }
+                // Check if AI was actually available and used
+                const aiAvailable = resolveAIEnhancer(toolState.context) !== undefined;
+                const aiIndicator = aiAvailable && useAI ? ' | AI' : '';
+                lines.push('');
+                lines.push(`_Query: "${query}" | Type: ${result.queryType} | Time: ${result.timeTaken}ms${aiIndicator}_`);
+                return lines.join('\n');
+            }
+            catch (error) {
+                return buildError('exploring codebase', error, { workingDir });
+            }
+        },
+    };
+}
+/**
+ * Create all local exploration tools (explore + index management).
+ */
+export function createLocalExploreTools(workingDir, options) {
+    return [
+        createLocalExploreTool(workingDir, options),
+        createIndexTool(workingDir, options),
+    ];
+}
+function createIndexTool(workingDir, options) {
+    const context = {
+        aiEnhancer: options?.aiEnhancer,
+    };
+    const engine = new LocalExploreEngine(workingDir, context);
+    return {
+        name: 'explore_index',
+        description: 'Manage the codebase index for exploration. Use action "rebuild" to force re-index, "status" to check index state.',
+        parameters: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['rebuild', 'status'],
+                    description: 'Action to perform on the index',
+                },
+            },
+            required: ['action'],
+            additionalProperties: false,
+        },
+        cacheable: false,
+        handler: async (args) => {
+            try {
+                const action = args['action'];
+                if (action === 'rebuild') {
+                    const { fileCount } = await engine.initialize(true);
+                    return `✓ Rebuilt codebase index: ${fileCount} files analyzed`;
+                }
+                if (action === 'status') {
+                    const { rebuilt, fileCount } = await engine.initialize(false);
+                    return rebuilt
+                        ? `Built new index: ${fileCount} files`
+                        : `Using cached index: ${fileCount} files`;
+                }
+                return 'Unknown action. Use "rebuild" or "status".';
+            }
+            catch (error) {
+                return buildError('managing index', error, { workingDir });
+            }
+        },
+    };
+}
+//# sourceMappingURL=localExplore.js.map