namnam-skills 1.0.0 → 1.0.2

package/src/indexer.js

@@ -0,0 +1,944 @@
+/**
+ * Codebase Indexing System
+ *
+ * Provides deep code understanding through:
+ * - File scanning and hashing (change detection)
+ * - Symbol extraction (functions, classes, exports)
+ * - Import/dependency graph
+ * - Pattern detection
+ * - AI-ready context generation
+ */
+
+import fs from 'fs-extra';
+import path from 'path';
+import crypto from 'crypto';
+
+// Constants
+const INDEX_DIR = 'index';
+const META_FILE = 'meta.json';
+const FILES_FILE = 'files.json';
+const SYMBOLS_FILE = 'symbols.json';
+const IMPORTS_FILE = 'imports.json';
+const PATTERNS_FILE = 'patterns.json';
+const SUMMARIES_DIR = 'summaries';
+
+// File patterns to index
+const INDEXABLE_EXTENSIONS = [
+  '.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs',
+  '.py', '.rb', '.go', '.rs', '.java', '.kt',
+  '.c', '.cpp', '.h', '.hpp', '.cs',
+  '.vue', '.svelte', '.astro',
+  '.json', '.yaml', '.yml', '.toml',
+  '.md', '.mdx',
+  '.css', '.scss', '.less',
+  '.html', '.xml',
+  '.sql', '.graphql', '.prisma'
+];
+
+// Directories to skip
+const SKIP_DIRS = [
+  'node_modules', '.git', '.svn', '.hg',
+  'dist', 'build', 'out', '.next', '.nuxt',
+  'coverage', '.nyc_output',
+  '__pycache__', '.pytest_cache',
+  'vendor', 'target',
+  '.claude', '.cursor', '.vscode'
+];
+
+// Max file size to index (1MB)
+const MAX_FILE_SIZE = 1024 * 1024;
+
+/**
+ * Get index directory path
+ */
+export function getIndexDir(cwd = process.cwd()) {
+  return path.join(cwd, '.claude', INDEX_DIR);
+}
+
+/**
+ * Check if index exists
+ */
+export async function hasIndex(cwd = process.cwd()) {
+  const metaPath = path.join(getIndexDir(cwd), META_FILE);
+  return await fs.pathExists(metaPath);
+}
+
+/**
+ * Get index metadata
+ */
+export async function getIndexMeta(cwd = process.cwd()) {
+  const metaPath = path.join(getIndexDir(cwd), META_FILE);
+  if (!(await fs.pathExists(metaPath))) {
+    return null;
+  }
+  return await fs.readJson(metaPath);
+}
+
+/**
+ * Calculate file hash for change detection
+ */
+function hashFile(content) {
+  return crypto.createHash('md5').update(content).digest('hex');
+}
+
+/**
+ * Check if file should be indexed
+ */
+function shouldIndexFile(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  return INDEXABLE_EXTENSIONS.includes(ext);
+}
+
+/**
+ * Check if directory should be skipped
+ */
+function shouldSkipDir(dirName) {
+  return SKIP_DIRS.includes(dirName) || dirName.startsWith('.');
+}
+
+/**
+ * Scan directory for files
+ */
+async function scanDirectory(dir, baseDir = dir) {
+  const files = [];
+  const items = await fs.readdir(dir, { withFileTypes: true });
+
+  for (const item of items) {
+    const fullPath = path.join(dir, item.name);
+    const relativePath = path.relative(baseDir, fullPath);
+
+    if (item.isDirectory()) {
+      if (!shouldSkipDir(item.name)) {
+        const subFiles = await scanDirectory(fullPath, baseDir);
+        files.push(...subFiles);
+      }
+    } else if (item.isFile() && shouldIndexFile(item.name)) {
+      const stats = await fs.stat(fullPath);
+      if (stats.size <= MAX_FILE_SIZE) {
+        files.push({
+          path: relativePath.replace(/\\/g, '/'),
+          fullPath,
+          size: stats.size,
+          mtime: stats.mtime.toISOString()
+        });
+      }
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Extract symbols from JavaScript/TypeScript file
+ */
+function extractJsSymbols(content, filePath) {
+  const symbols = {
+    functions: [],
+    classes: [],
+    exports: [],
+    variables: [],
+    types: []
+  };
+
+  // Function declarations
+  const funcRegex = /(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*\(/g;
+  let match;
+  while ((match = funcRegex.exec(content)) !== null) {
+    symbols.functions.push({
+      name: match[1],
+      line: content.substring(0, match.index).split('\n').length,
+      exported: match[0].includes('export')
+    });
+  }
+
+  // Arrow functions (const name = () => or const name = async () =>)
+  const arrowRegex = /(?:export\s+)?(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s*)?\([^)]*\)\s*=>/g;
+  while ((match = arrowRegex.exec(content)) !== null) {
+    symbols.functions.push({
+      name: match[1],
+      line: content.substring(0, match.index).split('\n').length,
+      exported: match[0].includes('export'),
+      arrow: true
+    });
+  }
+
+  // Class declarations
+  const classRegex = /(?:export\s+)?class\s+(\w+)(?:\s+extends\s+(\w+))?/g;
+  while ((match = classRegex.exec(content)) !== null) {
+    symbols.classes.push({
+      name: match[1],
+      extends: match[2] || null,
+      line: content.substring(0, match.index).split('\n').length,
+      exported: match[0].includes('export')
+    });
+  }
+
+  // Export statements
+  const exportRegex = /export\s+(?:default\s+)?(?:const|let|var|function|class|type|interface)?\s*(\w+)/g;
+  while ((match = exportRegex.exec(content)) !== null) {
+    if (!symbols.exports.includes(match[1])) {
+      symbols.exports.push(match[1]);
+    }
+  }
+
+  // Named exports
+  const namedExportRegex = /export\s*\{\s*([^}]+)\s*\}/g;
+  while ((match = namedExportRegex.exec(content)) !== null) {
+    const names = match[1].split(',').map(n => n.trim().split(/\s+as\s+/)[0].trim());
+    symbols.exports.push(...names.filter(n => n && !symbols.exports.includes(n)));
+  }
+
+  // TypeScript types and interfaces
+  const typeRegex = /(?:export\s+)?(?:type|interface)\s+(\w+)/g;
+  while ((match = typeRegex.exec(content)) !== null) {
+    symbols.types.push({
+      name: match[1],
+      line: content.substring(0, match.index).split('\n').length,
+      exported: match[0].includes('export')
+    });
+  }
+
+  return symbols;
+}
+
+/**
+ * Extract imports from JavaScript/TypeScript file
+ */
+function extractJsImports(content, filePath) {
+  const imports = [];
+
+  // ES6 imports
+  const importRegex = /import\s+(?:(?:\{[^}]*\}|\*\s+as\s+\w+|\w+)\s*,?\s*)*\s*from\s*['"]([^'"]+)['"]/g;
+  let match;
+  while ((match = importRegex.exec(content)) !== null) {
+    imports.push({
+      source: match[1],
+      line: content.substring(0, match.index).split('\n').length,
+      isRelative: match[1].startsWith('.'),
+      isPackage: !match[1].startsWith('.')
+    });
+  }
+
+  // CommonJS require
+  const requireRegex = /require\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+  while ((match = requireRegex.exec(content)) !== null) {
+    imports.push({
+      source: match[1],
+      line: content.substring(0, match.index).split('\n').length,
+      isRelative: match[1].startsWith('.'),
+      isPackage: !match[1].startsWith('.'),
+      commonjs: true
+    });
+  }
+
+  return imports;
+}
+
+/**
+ * Extract symbols from Python file
+ */
+function extractPySymbols(content, filePath) {
+  const symbols = {
+    functions: [],
+    classes: [],
+    exports: [],
+    variables: []
+  };
+
+  // Function definitions
+  const funcRegex = /^(?:async\s+)?def\s+(\w+)\s*\(/gm;
+  let match;
+  while ((match = funcRegex.exec(content)) !== null) {
+    symbols.functions.push({
+      name: match[1],
+      line: content.substring(0, match.index).split('\n').length,
+      exported: !match[1].startsWith('_')
+    });
+  }
+
+  // Class definitions
+  const classRegex = /^class\s+(\w+)(?:\s*\(([^)]*)\))?/gm;
+  while ((match = classRegex.exec(content)) !== null) {
+    symbols.classes.push({
+      name: match[1],
+      extends: match[2] || null,
+      line: content.substring(0, match.index).split('\n').length,
+      exported: !match[1].startsWith('_')
+    });
+  }
+
+  return symbols;
+}
+
+/**
+ * Extract symbols based on file type
+ */
+function extractSymbols(content, filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+
+  if (['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs'].includes(ext)) {
+    return extractJsSymbols(content, filePath);
+  } else if (ext === '.py') {
+    return extractPySymbols(content, filePath);
+  }
+
+  return { functions: [], classes: [], exports: [], variables: [], types: [] };
+}
+
+/**
+ * Extract imports based on file type
+ */
+function extractImports(content, filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+
+  if (['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs'].includes(ext)) {
+    return extractJsImports(content, filePath);
+  }
+
+  return [];
+}
+
+/**
+ * Detect code patterns and conventions
+ */
+function detectPatterns(filesData) {
+  const patterns = {
+    framework: null,
+    language: 'javascript',
+    styling: null,
+    testing: null,
+    packageManager: null,
+    conventions: {
+      naming: null,
+      fileStructure: []
+    }
+  };
+
+  const fileNames = filesData.map(f => f.path.toLowerCase());
+  const hasFile = (name) => fileNames.some(f => f.includes(name));
+
+  // Detect framework
+  if (hasFile('next.config')) patterns.framework = 'Next.js';
+  else if (hasFile('nuxt.config')) patterns.framework = 'Nuxt';
+  else if (hasFile('vite.config')) patterns.framework = 'Vite';
+  else if (hasFile('angular.json')) patterns.framework = 'Angular';
+  else if (hasFile('vue.config')) patterns.framework = 'Vue';
+  else if (hasFile('svelte.config')) patterns.framework = 'Svelte';
+  else if (hasFile('remix.config')) patterns.framework = 'Remix';
+  else if (hasFile('astro.config')) patterns.framework = 'Astro';
+
+  // Detect language
+  const tsFiles = filesData.filter(f => f.path.endsWith('.ts') || f.path.endsWith('.tsx'));
+  const jsFiles = filesData.filter(f => f.path.endsWith('.js') || f.path.endsWith('.jsx'));
+  if (tsFiles.length > jsFiles.length) patterns.language = 'typescript';
+
+  // Detect styling
+  if (hasFile('tailwind.config')) patterns.styling = 'Tailwind CSS';
+  else if (fileNames.some(f => f.endsWith('.scss'))) patterns.styling = 'SCSS';
+  else if (fileNames.some(f => f.endsWith('.less'))) patterns.styling = 'Less';
+  else if (fileNames.some(f => f.includes('.module.css'))) patterns.styling = 'CSS Modules';
+  else if (fileNames.some(f => f.includes('styled'))) patterns.styling = 'Styled Components';
+
+  // Detect testing
+  if (hasFile('jest.config')) patterns.testing = 'Jest';
+  else if (hasFile('vitest.config')) patterns.testing = 'Vitest';
+  else if (hasFile('playwright.config')) patterns.testing = 'Playwright';
+  else if (hasFile('cypress.config')) patterns.testing = 'Cypress';
+
+  // Detect package manager
+  if (hasFile('pnpm-lock.yaml')) patterns.packageManager = 'pnpm';
+  else if (hasFile('yarn.lock')) patterns.packageManager = 'yarn';
+  else if (hasFile('bun.lockb')) patterns.packageManager = 'bun';
+  else if (hasFile('package-lock.json')) patterns.packageManager = 'npm';
+
+  // Detect file structure conventions
+  const dirs = [...new Set(filesData.map(f => f.path.split('/')[0]))];
+  patterns.conventions.fileStructure = dirs.filter(d => !d.includes('.'));
+
+  return patterns;
+}
+
+/**
+ * Generate file summary for AI context
+ */
+function generateFileSummary(filePath, content, symbols, imports) {
+  const lines = content.split('\n').length;
+  const ext = path.extname(filePath);
+
+  let summary = `## ${filePath}\n\n`;
+  summary += `**Type:** ${ext} | **Lines:** ${lines}\n\n`;
+
+  if (symbols.exports.length > 0) {
+    summary += `**Exports:** ${symbols.exports.join(', ')}\n\n`;
+  }
+
+  if (symbols.functions.length > 0) {
+    summary += `**Functions:**\n`;
+    symbols.functions.slice(0, 10).forEach(f => {
+      summary += `- \`${f.name}\` (line ${f.line})${f.exported ? ' [exported]' : ''}\n`;
+    });
+    if (symbols.functions.length > 10) {
+      summary += `- ... and ${symbols.functions.length - 10} more\n`;
+    }
+    summary += '\n';
+  }
+
+  if (symbols.classes.length > 0) {
+    summary += `**Classes:**\n`;
+    symbols.classes.forEach(c => {
+      summary += `- \`${c.name}\`${c.extends ? ` extends ${c.extends}` : ''} (line ${c.line})\n`;
+    });
+    summary += '\n';
+  }
+
+  if (imports.length > 0) {
+    const packages = imports.filter(i => i.isPackage).map(i => i.source);
+    const relatives = imports.filter(i => i.isRelative).map(i => i.source);
+
+    if (packages.length > 0) {
+      summary += `**Dependencies:** ${[...new Set(packages)].slice(0, 10).join(', ')}\n`;
+    }
+    if (relatives.length > 0) {
+      summary += `**Local imports:** ${relatives.slice(0, 5).join(', ')}${relatives.length > 5 ? '...' : ''}\n`;
+    }
+  }
+
+  return summary;
+}
+
+/**
+ * Build the full codebase index
+ */
+export async function buildIndex(cwd = process.cwd(), options = {}) {
+  const { onProgress = () => {} } = options;
+
+  const indexDir = getIndexDir(cwd);
+  const summariesDir = path.join(indexDir, SUMMARIES_DIR);
+
+  // Create directories
+  await fs.ensureDir(indexDir);
+  await fs.ensureDir(summariesDir);
+
+  onProgress({ phase: 'scanning', message: 'Scanning files...' });
+
+  // Scan all files
+  const scannedFiles = await scanDirectory(cwd);
+
+  onProgress({
+    phase: 'scanning',
+    message: `Found ${scannedFiles.length} files`,
+    total: scannedFiles.length
+  });
+
+  // Process each file
+  const filesIndex = [];
+  const allSymbols = {};
+  const allImports = {};
+  let processed = 0;
+
+  for (const file of scannedFiles) {
+    try {
+      const content = await fs.readFile(file.fullPath, 'utf-8');
+      const hash = hashFile(content);
+
+      // Extract symbols and imports
+      const symbols = extractSymbols(content, file.path);
+      const imports = extractImports(content, file.path);
+
+      // Store file info
+      filesIndex.push({
+        path: file.path,
+        size: file.size,
+        hash,
+        mtime: file.mtime,
+        lines: content.split('\n').length,
+        hasSymbols: symbols.functions.length > 0 || symbols.classes.length > 0
+      });
+
+      // Store symbols
+      if (symbols.functions.length > 0 || symbols.classes.length > 0 || symbols.types.length > 0) {
+        allSymbols[file.path] = symbols;
+      }
+
+      // Store imports
+      if (imports.length > 0) {
+        allImports[file.path] = imports;
+      }
+
+      // Generate summary
+      const summary = generateFileSummary(file.path, content, symbols, imports);
+      const summaryPath = path.join(summariesDir, file.path.replace(/\//g, '_').replace(/\\/g, '_') + '.md');
+      await fs.writeFile(summaryPath, summary);
+
+      processed++;
+      if (processed % 50 === 0) {
+        onProgress({
+          phase: 'indexing',
+          message: `Indexed ${processed}/${scannedFiles.length} files`,
+          current: processed,
+          total: scannedFiles.length
+        });
+      }
+    } catch (err) {
+      // Skip files that can't be read
+      console.error(`Skipping ${file.path}: ${err.message}`);
+    }
+  }
+
+  // Detect patterns
+  onProgress({ phase: 'analyzing', message: 'Analyzing patterns...' });
+  const patterns = detectPatterns(filesIndex);
+
+  // Build dependency graph
+  const dependencyGraph = buildDependencyGraph(allImports, filesIndex);
+
+  // Save all index files
+  onProgress({ phase: 'saving', message: 'Saving index...' });
+
+  const meta = {
+    version: '1.0.0',
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    stats: {
+      totalFiles: filesIndex.length,
+      totalLines: filesIndex.reduce((sum, f) => sum + f.lines, 0),
+      filesWithSymbols: Object.keys(allSymbols).length,
+      totalFunctions: Object.values(allSymbols).reduce((sum, s) => sum + s.functions.length, 0),
+      totalClasses: Object.values(allSymbols).reduce((sum, s) => sum + s.classes.length, 0)
+    },
+    patterns
+  };
+
+  await fs.writeJson(path.join(indexDir, META_FILE), meta, { spaces: 2 });
+  await fs.writeJson(path.join(indexDir, FILES_FILE), filesIndex, { spaces: 2 });
+  await fs.writeJson(path.join(indexDir, SYMBOLS_FILE), allSymbols, { spaces: 2 });
+  await fs.writeJson(path.join(indexDir, IMPORTS_FILE), allImports, { spaces: 2 });
+  await fs.writeJson(path.join(indexDir, PATTERNS_FILE), patterns, { spaces: 2 });
+
+  onProgress({
+    phase: 'complete',
+    message: `Index complete: ${filesIndex.length} files, ${meta.stats.totalFunctions} functions, ${meta.stats.totalClasses} classes`
+  });
+
+  return meta;
+}
+
+/**
+ * Build dependency graph from imports
+ */
+function buildDependencyGraph(imports, files) {
+  const graph = {
+    nodes: files.map(f => f.path),
+    edges: []
+  };
+
+  for (const [filePath, fileImports] of Object.entries(imports)) {
+    for (const imp of fileImports) {
+      if (imp.isRelative) {
+        // Resolve relative import
+        const dir = path.dirname(filePath);
+        let resolved = path.join(dir, imp.source).replace(/\\/g, '/');
+
+        // Try with extensions
+        const possiblePaths = [
+          resolved,
+          resolved + '.js',
+          resolved + '.ts',
+          resolved + '.jsx',
+          resolved + '.tsx',
+          resolved + '/index.js',
+          resolved + '/index.ts'
+        ];
+
+        const target = possiblePaths.find(p => files.some(f => f.path === p));
+        if (target) {
+          graph.edges.push({
+            from: filePath,
+            to: target
+          });
+        }
+      }
+    }
+  }
+
+  return graph;
+}
+
+/**
+ * Check for changes since last index
+ */
+export async function checkIndexChanges(cwd = process.cwd()) {
+  const meta = await getIndexMeta(cwd);
+  if (!meta) return { hasChanges: true, reason: 'no_index' };
+
+  const filesPath = path.join(getIndexDir(cwd), FILES_FILE);
+  if (!(await fs.pathExists(filesPath))) {
+    return { hasChanges: true, reason: 'missing_files_index' };
+  }
+
+  const indexedFiles = await fs.readJson(filesPath);
+  const currentFiles = await scanDirectory(cwd);
+
+  // Check for new, modified, or deleted files
+  const indexedPaths = new Set(indexedFiles.map(f => f.path));
+  const currentPaths = new Set(currentFiles.map(f => f.path));
+
+  const newFiles = currentFiles.filter(f => !indexedPaths.has(f.path));
+  const deletedFiles = indexedFiles.filter(f => !currentPaths.has(f.path));
+
+  // Check for modified files
+  const modifiedFiles = [];
+  for (const current of currentFiles) {
+    const indexed = indexedFiles.find(f => f.path === current.path);
+    if (indexed && indexed.mtime !== current.mtime) {
+      modifiedFiles.push(current.path);
+    }
+  }
+
+  if (newFiles.length > 0 || deletedFiles.length > 0 || modifiedFiles.length > 0) {
+    return {
+      hasChanges: true,
+      reason: 'files_changed',
+      newFiles: newFiles.map(f => f.path),
+      deletedFiles: deletedFiles.map(f => f.path),
+      modifiedFiles
+    };
+  }
+
+  return { hasChanges: false };
+}
+
+/**
+ * Search symbols across codebase
+ */
+export async function searchSymbols(query, cwd = process.cwd()) {
+  const symbolsPath = path.join(getIndexDir(cwd), SYMBOLS_FILE);
+  if (!(await fs.pathExists(symbolsPath))) {
+    return [];
+  }
+
+  const allSymbols = await fs.readJson(symbolsPath);
+  const results = [];
+  const queryLower = query.toLowerCase();
+
+  for (const [filePath, symbols] of Object.entries(allSymbols)) {
+    // Search functions
+    for (const func of symbols.functions || []) {
+      if (func.name.toLowerCase().includes(queryLower)) {
+        results.push({
+          type: 'function',
+          name: func.name,
+          file: filePath,
+          line: func.line,
+          exported: func.exported
+        });
+      }
+    }
+
+    // Search classes
+    for (const cls of symbols.classes || []) {
+      if (cls.name.toLowerCase().includes(queryLower)) {
+        results.push({
+          type: 'class',
+          name: cls.name,
+          file: filePath,
+          line: cls.line,
+          extends: cls.extends,
+          exported: cls.exported
+        });
+      }
+    }
+
+    // Search types
+    for (const type of symbols.types || []) {
+      if (type.name.toLowerCase().includes(queryLower)) {
+        results.push({
+          type: 'type',
+          name: type.name,
+          file: filePath,
+          line: type.line,
+          exported: type.exported
+        });
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Get files that import a specific file
+ */
+export async function getFileImporters(targetFile, cwd = process.cwd()) {
+  const importsPath = path.join(getIndexDir(cwd), IMPORTS_FILE);
+  if (!(await fs.pathExists(importsPath))) {
+    return [];
+  }
+
+  const allImports = await fs.readJson(importsPath);
+  const importers = [];
+
+  for (const [filePath, imports] of Object.entries(allImports)) {
+    for (const imp of imports) {
+      if (imp.isRelative) {
+        const dir = path.dirname(filePath);
+        const resolved = path.join(dir, imp.source).replace(/\\/g, '/');
+        if (resolved === targetFile || targetFile.startsWith(resolved)) {
+          importers.push({ file: filePath, line: imp.line });
+        }
+      }
+    }
+  }
+
+  return importers;
+}
+
+/**
+ * Get files that a specific file imports
+ */
+export async function getFileDependencies(sourceFile, cwd = process.cwd()) {
+  const importsPath = path.join(getIndexDir(cwd), IMPORTS_FILE);
+  if (!(await fs.pathExists(importsPath))) {
+    return [];
+  }
+
+  const allImports = await fs.readJson(importsPath);
+  return allImports[sourceFile] || [];
+}
+
+/**
+ * Generate context for AI consumption
+ */
+export async function generateAIContext(options = {}, cwd = process.cwd()) {
+  const {
+    files = [],           // Specific files to include
+    query = null,         // Search query to find relevant files
+    maxTokens = 50000,    // Approximate max tokens
+    includeImports = true,
+    includeSummaries = true
+  } = options;
+
+  const indexDir = getIndexDir(cwd);
+  const meta = await getIndexMeta(cwd);
+
+  if (!meta) {
+    return { error: 'No index found. Run indexing first.' };
+  }
+
+  let context = `# Codebase Context\n\n`;
+  context += `**Project:** ${path.basename(cwd)}\n`;
+  context += `**Framework:** ${meta.patterns?.framework || 'Unknown'}\n`;
+  context += `**Language:** ${meta.patterns?.language || 'Unknown'}\n`;
+  context += `**Files:** ${meta.stats.totalFiles} | **Lines:** ${meta.stats.totalLines}\n\n`;
+
+  // Add pattern info
+  if (meta.patterns) {
+    context += `## Detected Patterns\n\n`;
+    if (meta.patterns.styling) context += `- **Styling:** ${meta.patterns.styling}\n`;
+    if (meta.patterns.testing) context += `- **Testing:** ${meta.patterns.testing}\n`;
+    if (meta.patterns.packageManager) context += `- **Package Manager:** ${meta.patterns.packageManager}\n`;
+    context += '\n';
+  }
+
+  // Add file summaries
+  if (includeSummaries) {
+    const summariesDir = path.join(indexDir, SUMMARIES_DIR);
+
+    if (files.length > 0) {
+      // Include specific files
+      context += `## Requested Files\n\n`;
+      for (const file of files) {
+        const summaryPath = path.join(summariesDir, file.replace(/\//g, '_').replace(/\\/g, '_') + '.md');
+        if (await fs.pathExists(summaryPath)) {
+          const summary = await fs.readFile(summaryPath, 'utf-8');
+          context += summary + '\n---\n\n';
+        }
+      }
+    } else if (query) {
+      // Search and include relevant files
+      const results = await searchSymbols(query, cwd);
+      const relevantFiles = [...new Set(results.map(r => r.file))].slice(0, 20);
+
+      context += `## Relevant Files (query: "${query}")\n\n`;
+      for (const file of relevantFiles) {
+        const summaryPath = path.join(summariesDir, file.replace(/\//g, '_').replace(/\\/g, '_') + '.md');
+        if (await fs.pathExists(summaryPath)) {
+          const summary = await fs.readFile(summaryPath, 'utf-8');
+          context += summary + '\n---\n\n';
+        }
+      }
+    }
+  }
+
+  return {
+    context,
+    meta,
+    tokenEstimate: Math.ceil(context.length / 4)
+  };
+}
+
+/**
+ * Quick stats about the index
+ */
+export async function getIndexStats(cwd = process.cwd()) {
+  const meta = await getIndexMeta(cwd);
+  if (!meta) return null;
+
+  return {
+    ...meta.stats,
+    patterns: meta.patterns,
+    lastUpdated: meta.updatedAt,
+    indexAge: Date.now() - new Date(meta.updatedAt).getTime()
+  };
+}
+
+/**
+ * Incremental index update - only process changed files
+ */
+export async function updateIndexIncremental(changedFiles, cwd = process.cwd(), options = {}) {
+  const { onProgress = () => {} } = options;
+
+  const indexDir = getIndexDir(cwd);
+  const summariesDir = path.join(indexDir, SUMMARIES_DIR);
+
+  // Load existing index data
+  const filesPath = path.join(indexDir, FILES_FILE);
+  const symbolsPath = path.join(indexDir, SYMBOLS_FILE);
+  const importsPath = path.join(indexDir, IMPORTS_FILE);
+
+  if (!(await fs.pathExists(filesPath))) {
+    // No existing index, do full build
+    return await buildIndex(cwd, options);
+  }
+
+  let filesIndex = await fs.readJson(filesPath);
+  let allSymbols = await fs.readJson(symbolsPath);
+  let allImports = await fs.readJson(importsPath);
+
+  onProgress({ phase: 'incremental', message: `Processing ${changedFiles.length} changed files...` });
+
+  let processed = 0;
+
+  for (const change of changedFiles) {
+    const { path: filePath, fullPath, type } = change;
+
+    if (type === 'delete' || type === 'rename') {
+      // Remove from index
+      filesIndex = filesIndex.filter(f => f.path !== filePath);
+      delete allSymbols[filePath];
+      delete allImports[filePath];
+
+      // Remove summary
+      const summaryPath = path.join(summariesDir, filePath.replace(/\//g, '_').replace(/\\/g, '_') + '.md');
+      if (await fs.pathExists(summaryPath)) {
+        await fs.remove(summaryPath);
+      }
+    } else {
+      // Add or update file
+      try {
+        const resolvedPath = fullPath || path.join(cwd, filePath);
+
+        if (!(await fs.pathExists(resolvedPath))) {
+          // File was deleted
+          filesIndex = filesIndex.filter(f => f.path !== filePath);
+          delete allSymbols[filePath];
+          delete allImports[filePath];
+          continue;
+        }
+
+        const content = await fs.readFile(resolvedPath, 'utf-8');
+        const stats = await fs.stat(resolvedPath);
+        const hash = crypto.createHash('md5').update(content).digest('hex');
+
+        // Extract symbols and imports
+        const symbols = extractSymbols(content, filePath);
+        const imports = extractImports(content, filePath);
+
+        // Update file entry
+        const existingIdx = filesIndex.findIndex(f => f.path === filePath);
+        const fileEntry = {
+          path: filePath,
+          size: stats.size,
+          hash,
+          mtime: stats.mtime.toISOString(),
+          lines: content.split('\n').length,
+          hasSymbols: symbols.functions.length > 0 || symbols.classes.length > 0
+        };
+
+        if (existingIdx >= 0) {
+          filesIndex[existingIdx] = fileEntry;
+        } else {
+          filesIndex.push(fileEntry);
+        }
+
+        // Update symbols and imports
+        if (symbols.functions.length > 0 || symbols.classes.length > 0 || symbols.types.length > 0) {
+          allSymbols[filePath] = symbols;
+        } else {
+          delete allSymbols[filePath];
+        }
+
+        if (imports.length > 0) {
+          allImports[filePath] = imports;
+        } else {
+          delete allImports[filePath];
+        }
+
+        // Update summary
+        const summary = generateFileSummary(filePath, content, symbols, imports);
+        const summaryPath = path.join(summariesDir, filePath.replace(/\//g, '_').replace(/\\/g, '_') + '.md');
+        await fs.writeFile(summaryPath, summary);
+
+      } catch (err) {
+        // Skip files that can't be read
+        console.error(`Skipping ${filePath}: ${err.message}`);
+      }
+    }
+
+    processed++;
+    onProgress({
+      phase: 'incremental',
+      message: `Processed ${processed}/${changedFiles.length}`,
+      current: processed,
+      total: changedFiles.length
+    });
+  }
+
+  // Re-detect patterns
+  onProgress({ phase: 'analyzing', message: 'Analyzing patterns...' });
+  const patterns = detectPatterns(filesIndex);
+
+  // Update meta
+  const meta = {
+    version: '1.0.0',
+    createdAt: (await getIndexMeta(cwd))?.createdAt || new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    stats: {
+      totalFiles: filesIndex.length,
+      totalLines: filesIndex.reduce((sum, f) => sum + f.lines, 0),
+      filesWithSymbols: Object.keys(allSymbols).length,
+      totalFunctions: Object.values(allSymbols).reduce((sum, s) => sum + s.functions.length, 0),
+      totalClasses: Object.values(allSymbols).reduce((sum, s) => sum + s.classes.length, 0)
+    },
+    patterns,
+    lastIncrementalUpdate: {
+      timestamp: new Date().toISOString(),
+      filesProcessed: changedFiles.length
+    }
+  };
+
+  // Save updated index
+  onProgress({ phase: 'saving', message: 'Saving index...' });
+  await fs.writeJson(path.join(indexDir, META_FILE), meta, { spaces: 2 });
+  await fs.writeJson(filesPath, filesIndex, { spaces: 2 });
+  await fs.writeJson(symbolsPath, allSymbols, { spaces: 2 });
+  await fs.writeJson(importsPath, allImports, { spaces: 2 });
+  await fs.writeJson(path.join(indexDir, PATTERNS_FILE), patterns, { spaces: 2 });
+
+  onProgress({
+    phase: 'complete',
+    message: `Incremental update complete: ${changedFiles.length} files processed`
+  });
+
+  return meta;
+}