ai-mind-map 1.6.1 → 1.7.0

package/dist/knowledge-graph/indexer.js

@@ -31,6 +31,28 @@ export class Indexer {
     config;
     ig;
     changelog = null;
+    // Async lock for indexing operations
+    _indexLock = Promise.resolve();
+    _lockRelease = null;
+    async acquireIndexLock() {
+        // Wait for any existing lock to release
+        await this._indexLock;
+        let release;
+        this._indexLock = new Promise(resolve => { release = resolve; });
+        this._lockRelease = release;
+        return () => {
+            this._lockRelease = null;
+            release();
+        };
+    }
+    get isIndexing() {
+        return this._lockRelease !== null;
+    }
+    // Optional watcher reference to pause/resume during full reindex
+    watcher = null;
+    setWatcher(watcher) {
+        this.watcher = watcher;
+    }
     /**
      * Per-project-root ignore patterns.
      * When multiple projects are indexed, each keeps its own .gitignore rules.
@@ -201,114 +223,130 @@ export class Indexer {
      * @returns Indexing statistics
      */
     async fullIndex(onProgress) {
-        const startTime = Date.now();
-        const stats = {
-            filesScanned: 0,
-            filesParsed: 0,
-            filesSkipped: 0,
-            filesDeleted: 0,
-            nodesCreated: 0,
-            edgesCreated: 0,
-            parseErrors: 0,
-            durationMs: 0,
-            languages: {},
-        };
-        // Phase 1: Scanning
-        onProgress?.({
-            phase: 'scanning',
-            current: 0,
-            total: 0,
-            message: 'Scanning project for source files...',
-        });
-        const files = await this.scanFiles();
-        stats.filesScanned = files.length;
-        if (files.length === 0) {
+        const release = await this.acquireIndexLock();
+        try {
+            // Pause watcher to prevent races during full reindex
+            this.watcher?.pause();
+            const startTime = Date.now();
+            const stats = {
+                filesScanned: 0,
+                filesParsed: 0,
+                filesSkipped: 0,
+                filesDeleted: 0,
+                nodesCreated: 0,
+                edgesCreated: 0,
+                parseErrors: 0,
+                durationMs: 0,
+                languages: {},
+            };
+            // Phase 1: Scanning
             onProgress?.({
-                phase: 'complete',
+                phase: 'scanning',
                 current: 0,
                 total: 0,
-                message: 'No source files found to index.',
+                message: 'Scanning project for source files...',
             });
-            stats.durationMs = Date.now() - startTime;
-            return stats;
-        }
-        // Clear only nodes belonging to THIS project (preserve other projects)
-        this.graph.clearProject(this.config.projectRoot);
-        // Phase 2: Parsing
-        onProgress?.({
-            phase: 'parsing',
-            current: 0,
-            total: files.length,
-            message: `Parsing ${files.length} files...`,
-        });
-        const parseResults = await parseFiles(files, 16, (current, total) => {
+            const files = await this.scanFiles();
+            stats.filesScanned = files.length;
+            if (files.length === 0) {
+                onProgress?.({
+                    phase: 'complete',
+                    current: 0,
+                    total: 0,
+                    message: 'No source files found to index.',
+                });
+                stats.durationMs = Date.now() - startTime;
+                return stats;
+            }
+            // Clear only nodes belonging to THIS project (preserve other projects)
+            this.graph.clearProject(this.config.projectRoot);
+            // Phase 2: Parsing
             onProgress?.({
                 phase: 'parsing',
-                current,
-                total,
-                currentFile: files[Math.min(current, files.length - 1)],
-                message: `Parsed ${current}/${total} files`,
+                current: 0,
+                total: files.length,
+                message: `Parsing ${files.length} files...`,
             });
-        });
-        // Phase 3: Storing
-        onProgress?.({
-            phase: 'storing',
-            current: 0,
-            total: parseResults.length,
-            message: 'Storing parsed data in knowledge graph...',
-        });
-        for (let i = 0; i < parseResults.length; i++) {
-            const result = parseResults[i];
-            // If any single file fails, log and continue
-            try {
-                if (result.nodes.length === 0 && result.parseErrors.length > 0) {
-                    stats.filesSkipped++;
-                    stats.parseErrors += result.parseErrors.length;
-                    continue;
-                }
-                stats.filesParsed++;
-                stats.nodesCreated += result.nodes.length;
-                stats.edgesCreated += result.edges.length;
-                // Track language distribution
-                if (result.language !== 'unknown') {
-                    stats.languages[result.language] = (stats.languages[result.language] ?? 0) + 1;
-                }
-                if (result.parseErrors.length > 0) {
-                    stats.parseErrors += result.parseErrors.length;
-                }
-                // Store in graph
-                this.graph.replaceFileData(result.filePath, result.nodes, result.edges);
-                if (i % 50 === 0) {
-                    onProgress?.({
-                        phase: 'storing',
-                        current: i + 1,
-                        total: parseResults.length,
-                        currentFile: result.filePath,
-                        message: `Stored ${i + 1}/${parseResults.length} files`,
-                    });
-                }
-                // Memory pressure check every 100 files
-                if (i % 100 === 0 && i > 0) {
-                    const mem = process.memoryUsage();
-                    if (mem.heapUsed / mem.heapTotal > MEMORY_PRESSURE_THRESHOLD) {
-                        process.stderr.write(`⚠️ Memory pressure during fullIndex at file ${i}/${parseResults.length}. Stopping early.\n`);
-                        break;
+            const parseResults = await parseFiles(files, 16, (current, total) => {
+                onProgress?.({
+                    phase: 'parsing',
+                    current,
+                    total,
+                    currentFile: files[Math.min(current, files.length - 1)],
+                    message: `Parsed ${current}/${total} files`,
+                });
+            });
+            // Phase 3: Storing
+            onProgress?.({
+                phase: 'storing',
+                current: 0,
+                total: parseResults.length,
+                message: 'Storing parsed data in knowledge graph...',
+            });
+            for (let i = 0; i < parseResults.length; i++) {
+                const result = parseResults[i];
+                // If any single file fails, log and continue
+                try {
+                    if (result.nodes.length === 0 && result.parseErrors.length > 0) {
+                        stats.filesSkipped++;
+                        stats.parseErrors += result.parseErrors.length;
+                        continue;
+                    }
+                    stats.filesParsed++;
+                    stats.nodesCreated += result.nodes.length;
+                    stats.edgesCreated += result.edges.length;
+                    // Track language distribution
+                    if (result.language !== 'unknown') {
+                        stats.languages[result.language] = (stats.languages[result.language] ?? 0) + 1;
                     }
+                    if (result.parseErrors.length > 0) {
+                        stats.parseErrors += result.parseErrors.length;
+                    }
+                    // Store in graph
+                    this.graph.replaceFileData(result.filePath, result.nodes, result.edges);
+                    if (i % 50 === 0) {
+                        onProgress?.({
+                            phase: 'storing',
+                            current: i + 1,
+                            total: parseResults.length,
+                            currentFile: result.filePath,
+                            message: `Stored ${i + 1}/${parseResults.length} files`,
+                        });
+                    }
+                    // Memory pressure check every 100 files
+                    if (i % 100 === 0 && i > 0) {
+                        const mem = process.memoryUsage();
+                        if (mem.heapUsed / mem.heapTotal > MEMORY_PRESSURE_THRESHOLD) {
+                            process.stderr.write(`⚠ Memory pressure during fullIndex at file ${i}/${parseResults.length}. Stopping early.\n`);
+                            break;
+                        }
+                    }
+                }
+                catch {
+                    stats.parseErrors++;
                 }
             }
+            // Cleanup orphaned edges after full reindex
+            try {
+                this.graph.cleanOrphanedEdges();
+            }
             catch {
-                stats.parseErrors++;
+                // Non-critical cleanup
             }
+            // Phase 4: Complete
+            stats.durationMs = Date.now() - startTime;
+            onProgress?.({
+                phase: 'complete',
+                current: stats.filesParsed,
+                total: stats.filesScanned,
+                message: `Indexing complete: ${stats.filesParsed} files, ${stats.nodesCreated} nodes, ${stats.edgesCreated} edges in ${stats.durationMs}ms`,
+            });
+            return stats;
+        }
+        finally {
+            this.watcher?.resume();
+            release();
         }
-        // Phase 4: Complete
-        stats.durationMs = Date.now() - startTime;
-        onProgress?.({
-            phase: 'complete',
-            current: stats.filesParsed,
-            total: stats.filesScanned,
-            message: `Indexing complete: ${stats.filesParsed} files, ${stats.nodesCreated} nodes, ${stats.edgesCreated} edges in ${stats.durationMs}ms`,
-        });
-        return stats;
     }
     /**
      * Perform an incremental index — only re-parse files that have changed.
@@ -320,186 +358,192 @@ export class Indexer {
      * @returns Indexing statistics
      */
     async incrementalIndex(onProgress) {
-        const startTime = Date.now();
-        const stats = {
-            filesScanned: 0,
-            filesParsed: 0,
-            filesSkipped: 0,
-            filesDeleted: 0,
-            nodesCreated: 0,
-            edgesCreated: 0,
-            parseErrors: 0,
-            durationMs: 0,
-            languages: {},
-        };
-        // Phase 1: Scanning
-        onProgress?.({
-            phase: 'scanning',
-            current: 0,
-            total: 0,
-            message: 'Scanning for changes...',
-        });
-        const currentFiles = await this.scanFiles();
-        stats.filesScanned = currentFiles.length;
-        const indexedFiles = new Set(this.graph.getIndexedFiles());
-        const currentFileSet = new Set(currentFiles);
-        // Find files to add/update and files to delete
-        const filesToParse = [];
-        const filesToDelete = [];
-        // ── mtime-first staleness detection (10x faster) ──────────
-        // First check mtime+size via stat() (~0.1ms/file). Only hash
-        // files whose metadata changed (~3ms/file). This avoids
-        // reading every file on every incremental index.
-        for (const filePath of currentFiles) {
-            const existingHash = this.graph.getFileHash(filePath);
-            if (!existingHash) {
-                // New file — always parse
-                filesToParse.push(filePath);
-                continue;
-            }
-            // Fast path: check mtime+size from file_index table
-            const fileEntry = this.graph.getFileIndexEntry(filePath);
-            try {
-                const fileStat = await stat(filePath);
-                if (fileEntry) {
-                    // If mtime AND size match, file is unchanged (fast path — 99% of cases)
-                    if (fileStat.mtimeMs === fileEntry.mtime_ms && fileStat.size === fileEntry.size_bytes) {
+        const release = await this.acquireIndexLock();
+        try {
+            const startTime = Date.now();
+            const stats = {
+                filesScanned: 0,
+                filesParsed: 0,
+                filesSkipped: 0,
+                filesDeleted: 0,
+                nodesCreated: 0,
+                edgesCreated: 0,
+                parseErrors: 0,
+                durationMs: 0,
+                languages: {},
+            };
+            // Phase 1: Scanning
+            onProgress?.({
+                phase: 'scanning',
+                current: 0,
+                total: 0,
+                message: 'Scanning for changes...',
+            });
+            const currentFiles = await this.scanFiles();
+            stats.filesScanned = currentFiles.length;
+            const indexedFiles = new Set(this.graph.getIndexedFiles());
+            const currentFileSet = new Set(currentFiles);
+            // Find files to add/update and files to delete
+            const filesToParse = [];
+            const filesToDelete = [];
+            // ── mtime-first staleness detection (10x faster) ──────────
+            // First check mtime+size via stat() (~0.1ms/file). Only hash
+            // files whose metadata changed (~3ms/file). This avoids
+            // reading every file on every incremental index.
+            for (const filePath of currentFiles) {
+                const existingHash = this.graph.getFileHash(filePath);
+                if (!existingHash) {
+                    // New file — always parse
+                    filesToParse.push(filePath);
+                    continue;
+                }
+                // Fast path: check mtime+size from file_index table
+                const fileEntry = this.graph.getFileIndexEntry(filePath);
+                try {
+                    const fileStat = await stat(filePath);
+                    if (fileEntry) {
+                        // If mtime AND size match, file is unchanged (fast path — 99% of cases)
+                        if (fileStat.mtimeMs === fileEntry.mtime_ms && fileStat.size === fileEntry.size_bytes) {
+                            stats.filesSkipped++;
+                            continue;
+                        }
+                    }
+                    // Slow path: metadata changed, verify with content hash
+                    const content = await readFile(filePath, 'utf-8');
+                    const currentHash = generateContentHash(content);
+                    if (currentHash !== existingHash) {
+                        filesToParse.push(filePath);
+                    }
+                    else {
+                        // Content unchanged despite metadata change — update file_index
+                        this.graph.upsertFileIndex(filePath, fileStat.mtimeMs, fileStat.size, currentHash);
                         stats.filesSkipped++;
-                        continue;
                     }
                 }
-                // Slow path: metadata changed, verify with content hash
-                const content = await readFile(filePath, 'utf-8');
-                const currentHash = generateContentHash(content);
-                if (currentHash !== existingHash) {
-                    filesToParse.push(filePath);
-                }
-                else {
-                    // Content unchanged despite metadata change — update file_index
-                    this.graph.upsertFileIndex(filePath, fileStat.mtimeMs, fileStat.size, currentHash);
+                catch {
                     stats.filesSkipped++;
                 }
             }
-            catch {
-                stats.filesSkipped++;
-            }
-        }
-        // Check for deleted files
-        for (const indexedFile of indexedFiles) {
-            if (!currentFileSet.has(indexedFile)) {
-                filesToDelete.push(indexedFile);
-            }
-        }
-        // Phase 2: Handle deletions
-        if (filesToDelete.length > 0) {
-            onProgress?.({
-                phase: 'cleanup',
-                current: 0,
-                total: filesToDelete.length,
-                message: `Removing ${filesToDelete.length} deleted files...`,
-            });
-            for (const filePath of filesToDelete) {
-                this.graph.deleteFileNodes(filePath);
-                this.graph.removeFileIndex(filePath);
-                stats.filesDeleted++;
-            }
-        }
-        // Phase 3: Parse changed files
-        if (filesToParse.length > 0) {
-            onProgress?.({
-                phase: 'parsing',
-                current: 0,
-                total: filesToParse.length,
-                message: `Parsing ${filesToParse.length} changed files...`,
-            });
-            // ── Memory-aware indexing ─────────────────────────────
-            // Check memory pressure before parsing. If approaching
-            // 80% heap usage, stop and report partial results.
-            const memInfo = process.memoryUsage();
-            if (memInfo.heapUsed / memInfo.heapTotal > MEMORY_PRESSURE_THRESHOLD) {
-                console.error(`[ai-mind-map] Memory pressure: ${(memInfo.heapUsed / 1024 / 1024).toFixed(0)}MB / ` +
-                    `${(memInfo.heapTotal / 1024 / 1024).toFixed(0)}MB. ` +
-                    `Skipping ${filesToParse.length} files to prevent OOM.`);
-                stats.filesSkipped += filesToParse.length;
+            // Check for deleted files
+            for (const indexedFile of indexedFiles) {
+                if (!currentFileSet.has(indexedFile)) {
+                    filesToDelete.push(indexedFile);
+                }
             }
-            else {
-                const parseResults = await parseFiles(filesToParse, 8, (current, total) => {
-                    onProgress?.({
-                        phase: 'parsing',
-                        current,
-                        total,
-                        currentFile: filesToParse[Math.min(current, filesToParse.length - 1)],
-                        message: `Parsed ${current}/${total} changed files`,
-                    });
+            // Phase 2: Handle deletions
+            if (filesToDelete.length > 0) {
+                onProgress?.({
+                    phase: 'cleanup',
+                    current: 0,
+                    total: filesToDelete.length,
+                    message: `Removing ${filesToDelete.length} deleted files...`,
                 });
-                // Phase 4: Store results
+                for (const filePath of filesToDelete) {
+                    this.graph.deleteFileNodes(filePath);
+                    this.graph.removeFileIndex(filePath);
+                    stats.filesDeleted++;
+                }
+            }
+            // Phase 3: Parse changed files
+            if (filesToParse.length > 0) {
                 onProgress?.({
-                    phase: 'storing',
+                    phase: 'parsing',
                     current: 0,
-                    total: parseResults.length,
-                    message: 'Updating knowledge graph...',
+                    total: filesToParse.length,
+                    message: `Parsing ${filesToParse.length} changed files...`,
                 });
-                for (let i = 0; i < parseResults.length; i++) {
-                    // Check memory between files
-                    if (i > 0 && i % 100 === 0) {
-                        const mem = process.memoryUsage();
-                        if (mem.heapUsed / mem.heapTotal > MEMORY_PRESSURE_THRESHOLD) {
-                            console.error(`[ai-mind-map] Memory pressure at file ${i}/${parseResults.length}. ` +
-                                `Stopping early to prevent OOM.`);
-                            stats.filesSkipped += parseResults.length - i;
-                            break;
+                // ── Memory-aware indexing ─────────────────────────────
+                // Check memory pressure before parsing. If approaching
+                // 80% heap usage, stop and report partial results.
+                const memInfo = process.memoryUsage();
+                if (memInfo.heapUsed / memInfo.heapTotal > MEMORY_PRESSURE_THRESHOLD) {
+                    console.error(`[ai-mind-map] Memory pressure: ${(memInfo.heapUsed / 1024 / 1024).toFixed(0)}MB / ` +
+                        `${(memInfo.heapTotal / 1024 / 1024).toFixed(0)}MB. ` +
+                        `Skipping ${filesToParse.length} files to prevent OOM.`);
+                    stats.filesSkipped += filesToParse.length;
+                }
+                else {
+                    const parseResults = await parseFiles(filesToParse, 8, (current, total) => {
+                        onProgress?.({
+                            phase: 'parsing',
+                            current,
+                            total,
+                            currentFile: filesToParse[Math.min(current, filesToParse.length - 1)],
+                            message: `Parsed ${current}/${total} changed files`,
+                        });
+                    });
+                    // Phase 4: Store results
+                    onProgress?.({
+                        phase: 'storing',
+                        current: 0,
+                        total: parseResults.length,
+                        message: 'Updating knowledge graph...',
+                    });
+                    for (let i = 0; i < parseResults.length; i++) {
+                        // Check memory between files
+                        if (i > 0 && i % 100 === 0) {
+                            const mem = process.memoryUsage();
+                            if (mem.heapUsed / mem.heapTotal > MEMORY_PRESSURE_THRESHOLD) {
+                                console.error(`[ai-mind-map] Memory pressure at file ${i}/${parseResults.length}. ` +
+                                    `Stopping early to prevent OOM.`);
+                                stats.filesSkipped += parseResults.length - i;
+                                break;
+                            }
                         }
-                    }
-                    const result = parseResults[i];
-                    if (result.nodes.length === 0 && result.parseErrors.length > 0) {
-                        stats.parseErrors += result.parseErrors.length;
-                        continue;
-                    }
-                    stats.filesParsed++;
-                    stats.nodesCreated += result.nodes.length;
-                    stats.edgesCreated += result.edges.length;
-                    if (result.language !== 'unknown') {
-                        stats.languages[result.language] = (stats.languages[result.language] ?? 0) + 1;
-                    }
-                    if (result.parseErrors.length > 0) {
-                        stats.parseErrors += result.parseErrors.length;
-                    }
-                    // Record changes before replacing (changelog diffing)
-                    if (this.changelog) {
+                        const result = parseResults[i];
+                        if (result.nodes.length === 0 && result.parseErrors.length > 0) {
+                            stats.parseErrors += result.parseErrors.length;
+                            continue;
+                        }
+                        stats.filesParsed++;
+                        stats.nodesCreated += result.nodes.length;
+                        stats.edgesCreated += result.edges.length;
+                        if (result.language !== 'unknown') {
+                            stats.languages[result.language] = (stats.languages[result.language] ?? 0) + 1;
+                        }
+                        if (result.parseErrors.length > 0) {
+                            stats.parseErrors += result.parseErrors.length;
+                        }
+                        // Record changes before replacing (changelog diffing)
+                        if (this.changelog) {
+                            try {
+                                const oldNodes = this.graph.getNodesForFile(result.filePath);
+                                this.changelog.recordChanges(result.filePath, oldNodes, result.nodes);
+                            }
+                            catch {
+                                // Changelog recording is non-critical
+                            }
+                        }
+                        // Replace file data atomically
+                        this.graph.replaceFileData(result.filePath, result.nodes, result.edges);
+                        // Update file_index for future mtime-first detection
                         try {
-                            const oldNodes = this.graph.getNodesForFile(result.filePath);
-                            this.changelog.recordChanges(result.filePath, oldNodes, result.nodes);
+                            const fileStat = await stat(result.filePath);
+                            const fileHash = result.nodes.find(n => n.type === 'file')?.hash ?? '';
+                            this.graph.upsertFileIndex(result.filePath, fileStat.mtimeMs, fileStat.size, fileHash);
                         }
                         catch {
-                            // Changelog recording is non-critical
+                            // File may have been deleted between parse and store
                         }
                     }
-                    // Replace file data atomically
-                    this.graph.replaceFileData(result.filePath, result.nodes, result.edges);
-                    // Update file_index for future mtime-first detection
-                    try {
-                        const fileStat = await stat(result.filePath);
-                        const fileHash = result.nodes.find(n => n.type === 'file')?.hash ?? '';
-                        this.graph.upsertFileIndex(result.filePath, fileStat.mtimeMs, fileStat.size, fileHash);
-                    }
-                    catch {
-                        // File may have been deleted between parse and store
-                    }
                 }
             }
+            // Phase 5: Complete
+            stats.durationMs = Date.now() - startTime;
+            const changeCount = filesToParse.length + filesToDelete.length;
+            onProgress?.({
+                phase: 'complete',
+                current: changeCount,
+                total: stats.filesScanned,
+                message: changeCount > 0
+                    ? `Incremental index: ${stats.filesParsed} updated, ${stats.filesDeleted} deleted in ${stats.durationMs}ms`
+                    : `No changes detected (${stats.filesScanned} files checked in ${stats.durationMs}ms)`,
+            });
+            return stats;
+        }
+        finally {
+            release();
         }
-        // Phase 5: Complete
-        stats.durationMs = Date.now() - startTime;
-        const changeCount = filesToParse.length + filesToDelete.length;
-        onProgress?.({
-            phase: 'complete',
-            current: changeCount,
-            total: stats.filesScanned,
-            message: changeCount > 0
-                ? `Incremental index: ${stats.filesParsed} updated, ${stats.filesDeleted} deleted in ${stats.durationMs}ms`
-                : `No changes detected (${stats.filesScanned} files checked in ${stats.durationMs}ms)`,
-        });
-        return stats;
     }
     /**
      * Index a single file (e.g., when file watcher detects a change).
@@ -508,46 +552,52 @@ export class Indexer {
      * @returns Parse result, or null if file was skipped
      */
     async indexFile(filePath) {
-        // Determine which project this file belongs to (multi-project support)
-        const fileProjectRoot = this.findProjectRootForFile(filePath) ?? this.config.projectRoot;
-        const fileIgnore = this.getIgnoreForFile(filePath);
-        // Check if file should be ignored using the correct project's rules
-        const relPath = relative(fileProjectRoot, filePath).replace(/\\/g, '/');
-        if (fileIgnore.ignores(relPath))
-            return null;
-        if (!isSupportedFile(filePath))
-            return null;
-        // Skip files that are too large (prevent OOM)
-        const fileStat = await stat(filePath).catch(() => null);
-        if (!fileStat || fileStat.size > MAX_FILE_SIZE_BYTES) {
-            return null;
-        }
+        const release = await this.acquireIndexLock();
         try {
-            if (fileStat.size > this.config.maxFileSize)
+            // Determine which project this file belongs to (multi-project support)
+            const fileProjectRoot = this.findProjectRootForFile(filePath) ?? this.config.projectRoot;
+            const fileIgnore = this.getIgnoreForFile(filePath);
+            // Check if file should be ignored using the correct project's rules
+            const relPath = relative(fileProjectRoot, filePath).replace(/\\/g, '/');
+            if (fileIgnore.ignores(relPath))
                 return null;
-            if (fileStat.size === 0)
+            if (!isSupportedFile(filePath))
                 return null;
-        }
-        catch {
-            // File may have been deleted
-            this.graph.deleteFileNodes(filePath);
-            return null;
-        }
-        const result = await parseFile(filePath);
-        if (result.nodes.length > 0) {
-            // Record changes before replacing (changelog diffing)
-            if (this.changelog) {
-                try {
-                    const oldNodes = this.graph.getNodesForFile(filePath);
-                    this.changelog.recordChanges(filePath, oldNodes, result.nodes);
-                }
-                catch {
-                    // Changelog recording is non-critical
+            // Skip files that are too large (prevent OOM)
+            const fileStat = await stat(filePath).catch(() => null);
+            if (!fileStat || fileStat.size > MAX_FILE_SIZE_BYTES) {
+                return null;
+            }
+            try {
+                if (fileStat.size > this.config.maxFileSize)
+                    return null;
+                if (fileStat.size === 0)
+                    return null;
+            }
+            catch {
+                // File may have been deleted
+                this.graph.deleteFileNodes(filePath);
+                return null;
+            }
+            const result = await parseFile(filePath);
+            if (result.nodes.length > 0) {
+                // Record changes before replacing (changelog diffing)
+                if (this.changelog) {
+                    try {
+                        const oldNodes = this.graph.getNodesForFile(filePath);
+                        this.changelog.recordChanges(filePath, oldNodes, result.nodes);
+                    }
+                    catch {
+                        // Changelog recording is non-critical
+                    }
                 }
+                this.graph.replaceFileData(filePath, result.nodes, result.edges);
             }
-            this.graph.replaceFileData(filePath, result.nodes, result.edges);
+            return result;
+        }
+        finally {
+            release();
         }
-        return result;
     }
     /**
      * Remove a file from the index (e.g., when file watcher detects deletion).