@codeyam/codeyam-cli 0.0.0 → 0.1.0-staging.036391e

package/codeyam-cli/src/utils/fileWatcher.js

@@ -0,0 +1,1576 @@
+import fs from 'fs';
+import path from 'path';
+import ts from 'typescript';
+import { upsertEntities, upsertEntityBranches, loadEntities, loadProject, deleteEntities, generateSha, loadAnalyses, loadFilePaths, } from "../../../packages/database/index.js";
+import { getEntityMetadata, getUncommittedFiles, getEntityLineRange, getFileDiffContext, isEntityUncommittedWithContext, } from "./fileMetadata.js";
+import { ProjectAnalyzer, getAllEntityNodes } from "../../../packages/analyze/index.js";
+import getFilesWithEntitiesFromRepo from "../../../background/src/lib/virtualized/project/getFilesWithEntitiesFromRepo.js";
+import createEntitiesAndSortFiles from "../../../background/src/lib/virtualized/project/createEntitiesAndSortFiles.js";
+import { populateEntityMetadata } from "./entityMetadata.js";
+import { getLatestCommittedVersion, shouldCreateNewVersion, } from "./entityVersioning.js";
+import { deleteAnalysisFiles } from "./cleanupAnalysisFiles.js";
+import { loadProject as loadProjectWithSlug } from "../../../packages/database/index.js";
+import { loadGitignorePatterns, shouldIgnorePath } from "./pathIgnoring.js";
+import { EntityCache } from "./entityCache.js";
+import { FolderBurstDetector } from "./folderBurstDetector.js";
+import { getCommittedEntityShaFromGit } from "./gitEntityLookup.js";
+import { getMemorySnapshot, logMemoryDelta } from "./memoryLogger.js";
+/**
+ * Watch files for changes and update entity metadata in the database
+ */
+export class FileWatcher {
+    constructor(options) {
+        this.watchers = [];
+        this.gitWatcher = null;
+        this.updateQueue = new Map();
+        this.DEBOUNCE_MS = 500; // Wait 500ms after last change before updating
+        this.uncommittedFiles = new Set();
+        this.projectAnalyzer = null;
+        this.knownFiles = new Set(); // Track files that exist in the database
+        this.gitignorePatterns = [];
+        this.customIgnorePatterns = [];
+        // Optimization: Entity/analysis caching to reduce DB queries
+        this.entityCache = new EntityCache();
+        // Optimization: Folder burst detection to prevent overwhelming the system
+        this.folderBurstDetector = new FolderBurstDetector();
+        // Optimization: TypeScript program refresh throttling
+        this.lastProgramRefresh = 0;
+        this.PROGRAM_REFRESH_THROTTLE = 2000; // 2 seconds
+        // Optimization: Cached project to avoid reloading on every file add
+        this.projectCache = null;
+        // Optimization: Periodic memory cleanup
+        this.cleanupInterval = null;
+        this.MAX_KNOWN_FILES = 10000;
+        // Optimization: Batch processing of file changes to avoid per-file refreshProgram() calls
+        this.pendingChanges = new Map();
+        this.batchTimeout = null;
+        this.BATCH_WINDOW_MS = 1000; // 1s after last change before processing batch
+        this.options = { watchGit: true, ...options };
+        this.customIgnorePatterns = options.customIgnorePatterns || [];
+    }
+    /**
+     * Start watching files
+     */
+    async start() {
+        const pathsToWatch = this.options.watchPaths || [
+            this.options.projectRootPath,
+        ];
+        const project = await loadProject({
+            id: this.options.projectId,
+            withFiles: true,
+        });
+        if (!project) {
+            throw new Error(`Project "${this.options.projectId}" not found in database`);
+        }
+        // Cache the project for use in handleFileAdd
+        this.projectCache = project;
+        // Memory logging: Before creating ProjectAnalyzer
+        const memBefore = await getMemorySnapshot('FileWatcher:beforeProjectAnalyzer');
+        this.projectAnalyzer = await ProjectAnalyzer.from({
+            project,
+            dirPath: this.options.projectRootPath,
+        });
+        // Memory logging: After creating ProjectAnalyzer
+        const memAfter = await getMemorySnapshot('FileWatcher:afterProjectAnalyzer');
+        void logMemoryDelta('FileWatcher:beforeProjectAnalyzer', 'FileWatcher:afterProjectAnalyzer');
+        // Initialize known files from database using lightweight path-only query
+        // This saves ~80% memory compared to loading full file objects
+        const filePaths = await loadFilePaths(this.options.projectId);
+        filePaths.forEach((path) => this.knownFiles.add(path));
+        console.log(`[FileWatcher] Initialized with ${this.knownFiles.size} known files from database`);
+        // Load gitignore patterns
+        this.gitignorePatterns = loadGitignorePatterns(this.options.projectRootPath);
+        console.log(`[FileWatcher] Loaded ${this.gitignorePatterns.length} gitignore patterns`);
+        console.log(`[FileWatcher] Custom ignore patterns: ${this.customIgnorePatterns.length}`);
+        // Perform initial sync BEFORE setting up watchers
+        // This ensures DB reflects current filesystem state
+        await this.performInitialSync();
+        for (const watchPath of pathsToWatch) {
+            const fullPath = path.isAbsolute(watchPath)
+                ? watchPath
+                : path.join(this.options.projectRootPath, watchPath);
+            try {
+                const watcher = fs.watch(fullPath, { recursive: true }, (eventType, filename) => {
+                    if (!filename)
+                        return;
+                    // Only watch TypeScript and JavaScript files
+                    if (!/\.(ts|tsx|js|jsx)$/.test(filename))
+                        return;
+                    // Always ignore these directories (hardcoded for performance)
+                    const ignoredDirs = [
+                        'node_modules',
+                        'dist',
+                        'build',
+                        '.next',
+                        '.codeyam',
+                        'coverage',
+                        'tmp',
+                        'temp',
+                        '.cache',
+                        '__tests__/__snapshots__',
+                        '__testUtils__',
+                        '__mocks__',
+                        '.turbo',
+                        '.vercel',
+                    ];
+                    if (ignoredDirs.some((dir) => filename.includes(dir))) {
+                        return;
+                    }
+                    // Check for folder bursts (e.g., test output folders)
+                    if (this.folderBurstDetector.shouldIgnore(filename)) {
+                        return; // Folder is experiencing a burst, ignore temporarily
+                    }
+                    // Check against custom ignore patterns and gitignore
+                    if (shouldIgnorePath(filename, this.customIgnorePatterns, this.gitignorePatterns)) {
+                        console.log(`[FileWatcher] Ignoring ${filename} (matches ignore pattern)`);
+                        return;
+                    }
+                    this.handleFileChange(filename);
+                });
+                this.watchers.push(watcher);
+                console.log(`Watching for file changes in: ${fullPath}`);
+            }
+            catch (error) {
+                console.error(`Failed to watch path ${fullPath}:`, error);
+            }
+        }
+        // Watch for git commits
+        if (this.options.watchGit) {
+            this.initializeUncommittedCache();
+            this.startGitWatcher();
+        }
+        // Start folder burst detector
+        this.folderBurstDetector.start();
+        // Start periodic cleanup (every 5 minutes)
+        this.cleanupInterval = setInterval(() => {
+            this.performMemoryCleanup();
+        }, 300000);
+        console.log('[FileWatcher] Started with optimizations (caching, burst detection, memory cleanup)');
+    }
+    /**
+     * Perform initial sync of all uncommitted files on startup.
+     * This ensures the database reflects the current filesystem state before we start watching.
+     * Handles:
+     * 1. Files that changed while the server was off (compares SHAs, creates new versions)
+     * 2. Files that were committed while the server was off (clears isUncommitted flag)
+     * 3. Files that were deleted and committed (removes entities)
+     */
+    async performInitialSync() {
+        console.log('[FileWatcher] Performing initial sync of uncommitted files...');
+        // Get current uncommitted files from git
+        const uncommittedFiles = getUncommittedFiles(this.options.projectRootPath);
+        const uncommittedTsFiles = Array.from(uncommittedFiles).filter((f) => /\.(ts|tsx|js|jsx)$/.test(f) && !this.shouldIgnoreFilePath(f));
+        console.log(`[FileWatcher] Found ${uncommittedTsFiles.length} uncommitted TypeScript/JavaScript files`);
+        // Sync SHA/code for uncommitted files using the same logic as runtime file changes
+        if (uncommittedTsFiles.length > 0) {
+            console.log(`[FileWatcher] Syncing ${uncommittedTsFiles.length} uncommitted files...`);
+            await this.handleFileUpdatesBatch(uncommittedTsFiles);
+        }
+        // Load all entities to find ones that need metadata updates
+        const allEntities = await loadEntities({
+            projectId: this.options.projectId,
+            branchId: this.options.branchId,
+        });
+        if (!allEntities || allEntities.length === 0) {
+            console.log('[FileWatcher] No entities in database, initial sync complete');
+            return;
+        }
+        // Find entities that were marked uncommitted but are now committed
+        // (handles commits that happened while the server was off)
+        const nowCommitted = allEntities.filter((e) => e.metadata?.isUncommitted &&
+            !e.metadata?.isSuperseded &&
+            !uncommittedFiles.has(e.filePath));
+        if (nowCommitted.length > 0) {
+            console.log(`[FileWatcher] Clearing isUncommitted from ${nowCommitted.length} now-committed entities`);
+            const updated = nowCommitted.map((e) => ({
+                ...e,
+                metadata: {
+                    ...e.metadata,
+                    isUncommitted: false,
+                },
+            }));
+            await upsertEntities(updated);
+            await upsertEntityBranches(updated.map((e) => ({
+                entitySha: e.sha,
+                branchId: this.options.branchId,
+                active: true,
+            })));
+        }
+        // Find entities that were marked isBeingDeleted and the deletion was committed
+        // (file no longer exists and is not in uncommitted list)
+        const beingDeletedAndCommitted = allEntities.filter((e) => e.metadata?.isBeingDeleted && !uncommittedFiles.has(e.filePath));
+        if (beingDeletedAndCommitted.length > 0) {
+            console.log(`[FileWatcher] Deleting ${beingDeletedAndCommitted.length} entities that were deleted and committed`);
+            await deleteEntities({
+                projectId: this.options.projectId,
+                shas: beingDeletedAndCommitted.map((e) => e.sha),
+            });
+        }
+        console.log('[FileWatcher] Initial sync complete');
+    }
+    /**
+     * Stop watching files
+     */
+    stop() {
+        for (const watcher of this.watchers) {
+            watcher.close();
+        }
+        this.watchers = [];
+        if (this.gitWatcher) {
+            this.gitWatcher.close();
+            this.gitWatcher = null;
+        }
+        // Clear any pending updates (legacy per-file queue)
+        for (const timeout of this.updateQueue.values()) {
+            clearTimeout(timeout);
+        }
+        this.updateQueue.clear();
+        // Clear pending batch changes
+        if (this.batchTimeout) {
+            clearTimeout(this.batchTimeout);
+            this.batchTimeout = null;
+        }
+        this.pendingChanges.clear();
+        // Stop periodic cleanup
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+        // Stop folder burst detector
+        this.folderBurstDetector.stop();
+        // Clear caches
+        this.entityCache.invalidateAll();
+        this.projectCache = null;
+        console.log('Stopped watching files');
+    }
+    /**
+     * Check if a file path should be ignored (test utilities, mocks, etc.)
+     */
+    shouldIgnoreFilePath(filePath) {
+        return (filePath.includes('__testUtils__') ||
+            filePath.includes('__mocks__') ||
+            filePath.includes('__tests__/__snapshots__') ||
+            filePath.includes('/mockRemixApp/') ||
+            filePath.includes('/testApps/'));
+    }
+    /**
+     * Lightweight single-file parsing for entity extraction.
+     * Uses ts.createSourceFile() which is much faster than refreshing the full TypeScript program.
+     * Only parses the AST - no type checking, no cross-file resolution.
+     */
+    parseFileForEntities(filePath) {
+        const fullPath = path.join(this.options.projectRootPath, filePath);
+        if (!fs.existsSync(fullPath))
+            return null;
+        try {
+            const content = fs.readFileSync(fullPath, 'utf-8');
+            const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true);
+            const entityNodes = getAllEntityNodes({ sourceFile });
+            return { sourceFile, entityNodes };
+        }
+        catch (error) {
+            console.error(`[FileWatcher] Failed to parse file ${filePath}:`, error);
+            return null;
+        }
+    }
+    /**
+     * Get the code for an entity from a parsed source file
+     */
+    getEntityCodeFromSourceFile(entityName, sourceFile, entityNodes) {
+        try {
+            const entityNode = entityNodes[entityName];
+            if (!entityNode)
+                return null;
+            return entityNode.getText(sourceFile);
+        }
+        catch (error) {
+            console.error(`[FileWatcher] Failed to get code for entity ${entityName}:`, error);
+            return null;
+        }
+    }
+    /**
+     * Handle file change event - accumulates changes into a batch for efficient processing.
+     * This avoids calling refreshProgram() for every file change.
+     */
+    handleFileChange(filename) {
+        console.log(`[FileWatcher] File change detected: ${filename}`);
+        // Normalize the file path
+        const filePath = filename.startsWith(this.options.projectRootPath)
+            ? path.relative(this.options.projectRootPath, filename)
+            : filename;
+        const fullPath = path.join(this.options.projectRootPath, filePath);
+        const fileExists = fs.existsSync(fullPath);
+        const isKnownFile = this.knownFiles.has(filePath);
+        // Determine the event type
+        let eventType;
+        if (!fileExists && isKnownFile) {
+            eventType = 'delete';
+        }
+        else if (fileExists && !isKnownFile) {
+            eventType = 'add';
+        }
+        else {
+            eventType = 'change';
+        }
+        console.log(`[FileWatcher] File event type: ${eventType} for ${filePath}`);
+        // Accumulate the change into pending batch (latest event type wins for same file)
+        this.pendingChanges.set(filePath, { type: eventType, filePath });
+        // Reset the batch timer - process after BATCH_WINDOW_MS of no new changes
+        if (this.batchTimeout) {
+            clearTimeout(this.batchTimeout);
+        }
+        this.batchTimeout = setTimeout(() => {
+            this.processBatch().catch((error) => {
+                console.error('[FileWatcher] Error processing batch:', error);
+            });
+        }, this.BATCH_WINDOW_MS);
+    }
+    /**
+     * Process all accumulated file changes as a batch.
+     * This is much more efficient than processing each file individually because:
+     * 1. We use lightweight single-file parsing (ts.createSourceFile) instead of refreshProgram()
+     * 2. We batch database queries (loadEntities, loadAnalyses) for all files at once
+     * 3. We batch database writes (upsertEntities, upsertEntityBranches) at the end
+     */
+    async processBatch() {
+        // Take ownership of pending changes and clear the batch state
+        const changes = new Map(this.pendingChanges);
+        this.pendingChanges.clear();
+        this.batchTimeout = null;
+        if (changes.size === 0)
+            return;
+        console.log(`[FileWatcher] Processing batch of ${changes.size} file changes`);
+        // Group changes by type
+        const deletes = [...changes.values()].filter((c) => c.type === 'delete');
+        const adds = [...changes.values()].filter((c) => c.type === 'add');
+        const updates = [...changes.values()].filter((c) => c.type === 'change');
+        console.log(`[FileWatcher] Batch breakdown: ${deletes.length} deletes, ${adds.length} adds, ${updates.length} updates`);
+        // Process each type with batched operations
+        // Order matters: deletes first (to clean up), then updates, then adds
+        if (deletes.length > 0) {
+            await this.handleFileDeletesBatch(deletes.map((d) => d.filePath));
+        }
+        if (updates.length > 0) {
+            await this.handleFileUpdatesBatch(updates.map((u) => u.filePath));
+        }
+        if (adds.length > 0) {
+            await this.handleFileAddsBatch(adds.map((a) => a.filePath));
+        }
+        console.log(`[FileWatcher] Batch processing complete`);
+    }
+    /**
+     * Handle multiple file deletions as a batch
+     */
+    async handleFileDeletesBatch(filePaths) {
+        try {
+            // Filter out ignored paths
+            const validPaths = filePaths.filter((fp) => !this.shouldIgnoreFilePath(fp));
+            if (validPaths.length === 0)
+                return;
+            console.log(`[FileWatcher] Handling batch deletion of ${validPaths.length} files`);
+            // Batch load all entities for deleted files
+            const entities = await loadEntities({
+                projectId: this.options.projectId,
+                branchId: this.options.branchId,
+                filePaths: validPaths,
+            });
+            if (!entities || entities.length === 0) {
+                console.log(`[FileWatcher] No entities found for deleted files`);
+                validPaths.forEach((fp) => this.knownFiles.delete(fp));
+                return;
+            }
+            // Mark all entities as being deleted
+            const updatedEntities = entities.map((entity) => ({
+                ...entity,
+                metadata: {
+                    ...entity.metadata,
+                    isBeingDeleted: true,
+                    editedAt: new Date().toISOString(),
+                },
+            }));
+            // Batch persist updates
+            await upsertEntities(updatedEntities);
+            await upsertEntityBranches(updatedEntities.map((e) => ({
+                entitySha: e.sha,
+                branchId: this.options.branchId,
+                active: true,
+            })));
+            // Update known files cache
+            validPaths.forEach((fp) => this.knownFiles.delete(fp));
+            console.log(`[FileWatcher] Marked ${updatedEntities.length} entities as being deleted across ${validPaths.length} files`);
+        }
+        catch (error) {
+            console.error(`[FileWatcher] Failed to handle batch file deletions:`, error);
+        }
+    }
+    /**
+     * Handle multiple file additions as a batch
+     * For adds, we still need to use the full ProjectAnalyzer because we're creating new entities
+     */
+    async handleFileAddsBatch(filePaths) {
+        // Filter out ignored paths
+        const validPaths = filePaths.filter((fp) => !this.shouldIgnoreFilePath(fp));
+        if (validPaths.length === 0)
+            return;
+        console.log(`[FileWatcher] Handling batch addition of ${validPaths.length} files`);
+        // For file adds, we delegate to the existing handler since it needs to create new entities
+        // The existing handler will use the projectAnalyzer, but we only refresh once at the start
+        if (this.projectAnalyzer) {
+            console.log(`[FileWatcher] Refreshing TypeScript program once for ${validPaths.length} new files`);
+            this.projectAnalyzer.refreshProgram();
+        }
+        // Process adds sequentially (they use complex entity creation logic)
+        for (const filePath of validPaths) {
+            await this.handleFileAddWithoutRefresh(filePath);
+        }
+    }
+    /**
+     * Handle a single file addition without refreshing the TypeScript program
+     * (assumes program was already refreshed by batch handler)
+     */
+    async handleFileAddWithoutRefresh(filePath) {
+        try {
+            console.log(`[FileWatcher] Handling new file: ${filePath}`);
+            // Use cached project or load minimal project info
+            const project = this.projectCache ||
+                (await loadProject({
+                    id: this.options.projectId,
+                    withFiles: false,
+                }));
+            if (!project) {
+                throw new Error(`Project "${this.options.projectId}" not found in database`);
+            }
+            if (!this.projectCache) {
+                this.projectCache = project;
+            }
+            if (!project.files) {
+                project.files = [];
+            }
+            // Add the new file to project.files
+            await getFilesWithEntitiesFromRepo({
+                project,
+                projectAnalyzer: this.projectAnalyzer,
+                filePath,
+                silent: true,
+            });
+            const branch = project.branches?.find((b) => b.id === this.options.branchId);
+            if (!branch) {
+                console.log(`[FileWatcher] Branch "${this.options.branchId}" not found, creating entities without branch`);
+            }
+            await createEntitiesAndSortFiles({
+                project,
+                branch: branch || { id: this.options.branchId },
+                filePath,
+                projectAnalyzer: this.projectAnalyzer,
+            });
+            const fileWithEntities = project.files.find((f) => f.path === filePath);
+            if (fileWithEntities && fileWithEntities.entities) {
+                await populateEntityMetadata([fileWithEntities], this.options.projectRootPath, this.projectAnalyzer);
+            }
+            this.knownFiles.add(filePath);
+            const entityCount = fileWithEntities?.entities?.length || 0;
+            console.log(`[FileWatcher] Created ${entityCount} entities for new file: ${filePath}`);
+        }
+        catch (error) {
+            console.error(`[FileWatcher] Failed to handle new file ${filePath}:`, error);
+        }
+    }
+    /**
+     * Handle multiple file updates as a batch using lightweight single-file parsing.
+     * This is the key optimization - no refreshProgram() calls needed!
+     */
+    async handleFileUpdatesBatch(filePaths) {
+        try {
+            // Filter out ignored paths
+            const validPaths = filePaths.filter((fp) => !this.shouldIgnoreFilePath(fp));
+            if (validPaths.length === 0)
+                return;
+            console.log(`[FileWatcher] Handling batch update of ${validPaths.length} files`);
+            // 1. Batch load all existing entities for all files at once
+            const allEntities = await loadEntities({
+                projectId: this.options.projectId,
+                branchId: this.options.branchId,
+                filePaths: validPaths,
+            });
+            // Track files with no entities - they might need to be treated as adds
+            const filesToAdd = [];
+            if (!allEntities || allEntities.length === 0) {
+                console.log(`[FileWatcher] No entities found for any updated files, treating as adds`);
+                await this.handleFileAddsBatch(validPaths);
+                return;
+            }
+            // 2. Filter out superseded entities
+            const existingEntities = allEntities.filter((e) => !e.metadata?.isSuperseded);
+            if (existingEntities.length === 0) {
+                console.log(`[FileWatcher] No non-superseded entities found`);
+                return;
+            }
+            // 3. Batch load analyses for all entities
+            const entityShas = existingEntities.map((e) => e.sha);
+            let analyses;
+            try {
+                analyses = await loadAnalyses({ entityShas });
+            }
+            catch (error) {
+                console.error(`[FileWatcher] Error loading analyses:`, error);
+                analyses = null;
+            }
+            // Map analyses to entities
+            const analysisMap = new Map();
+            if (analyses && analyses.length > 0) {
+                for (const analysis of analyses) {
+                    if (!analysisMap.has(analysis.entitySha)) {
+                        analysisMap.set(analysis.entitySha, []);
+                    }
+                    analysisMap.get(analysis.entitySha).push(analysis);
+                }
+            }
+            // Attach analyses to entities
+            for (const entity of existingEntities) {
+                entity.analyses = analysisMap.get(entity.sha) || [];
+            }
+            // 4. Group entities by file path for processing
+            const entitiesByFile = new Map();
+            for (const entity of existingEntities) {
+                if (!entitiesByFile.has(entity.filePath)) {
+                    entitiesByFile.set(entity.filePath, []);
+                }
+                entitiesByFile.get(entity.filePath).push(entity);
+            }
+            // 5. Process each file with lightweight single-file parsing
+            const updatedEntities = [];
+            const newEntities = [];
+            const supersededEntities = [];
+            for (const filePath of validPaths) {
+                const fileEntities = entitiesByFile.get(filePath);
+                // If file has no entities in DB, treat as add
+                if (!fileEntities || fileEntities.length === 0) {
+                    filesToAdd.push(filePath);
+                    continue;
+                }
+                // Use lightweight single-file parsing instead of refreshProgram()!
+                const parsed = this.parseFileForEntities(filePath);
+                if (!parsed) {
+                    console.log(`[FileWatcher] Could not parse ${filePath}, skipping`);
+                    continue;
+                }
+                const { sourceFile, entityNodes } = parsed;
+                const currentEntityNames = new Set(Object.keys(entityNodes));
+                // Get file diff context ONCE per file for efficient uncommitted checking
+                const diffContext = getFileDiffContext(filePath, this.options.projectRootPath);
+                const editedAt = new Date().toISOString();
+                // Group entities by name for this file - this is critical to avoid processing
+                // multiple versions of the same entity separately (which causes all to be superseded)
+                const entitiesByName = new Map();
+                for (const entity of fileEntities) {
+                    if (!entitiesByName.has(entity.name)) {
+                        entitiesByName.set(entity.name, []);
+                    }
+                    entitiesByName.get(entity.name).push(entity);
+                }
+                // Process each unique entity NAME (not each version)
+                // This ensures we only create ONE new version per entity name
+                for (const [entityName, entityVersions] of entitiesByName.entries()) {
+                    if (!currentEntityNames.has(entityName)) {
+                        // Entity was deleted from the file - mark ALL versions as being deleted
+                        for (const entity of entityVersions) {
+                            updatedEntities.push({
+                                ...entity,
+                                metadata: {
+                                    ...entity.metadata,
+                                    isBeingDeleted: true,
+                                    editedAt,
+                                },
+                            });
+                        }
+                        continue;
+                    }
+                    // Get current code using lightweight parsing
+                    const currentCode = this.getEntityCodeFromSourceFile(entityName, sourceFile, entityNodes);
+                    if (!currentCode) {
+                        console.error(`[FileWatcher] Failed to get code for entity ${entityName}`);
+                        continue;
+                    }
+                    const currentSha = generateSha(filePath, entityName, currentCode);
+                    // Get entity line range from the lightweight AST for uncommitted detection
+                    const entityNode = entityNodes[entityName];
+                    const entityRange = getEntityLineRange(entityNode, sourceFile);
+                    const isUncommitted = isEntityUncommittedWithContext(entityRange, diffContext);
+                    // Check if any existing version already has this SHA (code hasn't changed for that version)
+                    const matchingVersion = entityVersions.find((e) => e.sha === currentSha);
+                    if (matchingVersion) {
+                        // Found a version with matching SHA - just update its metadata
+                        // Mark all OTHER versions as superseded
+                        for (const entity of entityVersions) {
+                            if (entity.sha === currentSha) {
+                                updatedEntities.push({
+                                    ...entity,
+                                    metadata: {
+                                        ...entity.metadata,
+                                        editedAt,
+                                        isUncommitted,
+                                        isBeingDeleted: false,
+                                        isSuperseded: false, // Ensure this is the current version
+                                    },
+                                });
+                            }
+                            else {
+                                // Different SHA - mark as superseded
+                                supersededEntities.push({
+                                    ...entity,
+                                    metadata: {
+                                        ...entity.metadata,
+                                        isSuperseded: true,
+                                    },
+                                });
+                            }
+                        }
+                    }
+                    else {
+                        // No version matches current SHA - code has changed
+                        // Pick the "best" version to base the new entity on:
+                        // 1. Prefer version with analyses (to inherit them)
+                        // 2. Otherwise prefer most recently created
+                        const sortedVersions = [...entityVersions].sort((a, b) => {
+                            // Prefer version with analyses
+                            const aHasAnalyses = (a.analyses?.length || 0) > 0;
+                            const bHasAnalyses = (b.analyses?.length || 0) > 0;
+                            if (aHasAnalyses && !bHasAnalyses)
+                                return -1;
+                            if (!aHasAnalyses && bHasAnalyses)
+                                return 1;
+                            // Then by creation time (most recent first)
+                            const aTime = a.createdAt || '';
+                            const bTime = b.createdAt || '';
+                            return bTime.localeCompare(aTime);
+                        });
+                        const primaryVersion = sortedVersions[0];
+                        const createNewVersion = shouldCreateNewVersion(primaryVersion);
+                        // Get committed SHA for comparison
+                        let committedSha = getCommittedEntityShaFromGit(this.options.projectRootPath, filePath, entityName);
+                        if (!committedSha) {
+                            const latestCommitted = await getLatestCommittedVersion(this.options.projectId, this.options.branchId, filePath, entityName);
+                            committedSha = latestCommitted?.sha || null;
+                        }
+                        const isRevertToCommitted = committedSha && currentSha === committedSha;
+                        if (createNewVersion) {
+                            // Primary version has analyses - mark ALL existing versions as superseded
+                            // and create a new version inheriting from the primary
+                            for (const entity of entityVersions) {
+                                supersededEntities.push({
+                                    ...entity,
+                                    metadata: {
+                                        ...entity.metadata,
+                                        isSuperseded: true,
+                                    },
+                                });
+                            }
+                            const newEntity = {
+                                ...primaryVersion,
+                                sha: currentSha,
+                                code: currentCode,
+                                analyses: primaryVersion.analyses || [],
+                                metadata: {
+                                    ...primaryVersion.metadata,
+                                    // Clear isolatedDataStructure - it was computed for the old code
+                                    // and must be recomputed for the new code during analysis
+                                    isolatedDataStructure: undefined,
+                                    editedAt,
+                                    isUncommitted: !isRevertToCommitted,
+                                    isBeingDeleted: false,
+                                    isSuperseded: false,
+                                    previousCommittedSha: committedSha || undefined,
+                                    previousVersionWithAnalyses: primaryVersion.metadata?.previousVersionWithAnalyses ||
+                                        primaryVersion.sha,
+                                },
+                                createdAt: new Date().toISOString(),
+                            };
+                            newEntities.push(newEntity);
+                        }
+                        else {
+                            // No analyses - update the primary version in place
+                            // Mark other versions (if any) as superseded
+                            for (const entity of entityVersions) {
+                                if (entity.sha === primaryVersion.sha) {
+                                    // Update primary version in place with new SHA
+                                    updatedEntities.push({
+                                        ...primaryVersion,
+                                        sha: currentSha,
+                                        code: currentCode,
+                                        metadata: {
+                                            ...primaryVersion.metadata,
+                                            editedAt,
+                                            isUncommitted: !isRevertToCommitted,
+                                            isBeingDeleted: false,
+                                            isSuperseded: false,
+                                            previousCommittedSha: committedSha || undefined,
+                                        },
+                                    });
+                                }
+                                else {
+                                    // Mark other versions as superseded
+                                    supersededEntities.push({
+                                        ...entity,
+                                        metadata: {
+                                            ...entity.metadata,
+                                            isSuperseded: true,
+                                        },
+                                    });
+                                }
+                            }
+                        }
+                    }
+                }
+                // Update uncommitted files cache
+                const fileProcessedEntities = [
+                    ...updatedEntities,
+                    ...newEntities,
+                ].filter((e) => e.filePath === filePath);
+                const hasUncommittedEntity = fileProcessedEntities.some((e) => e.metadata?.isUncommitted);
+                if (hasUncommittedEntity) {
+                    this.uncommittedFiles.add(filePath);
+                }
+                else {
+                    this.uncommittedFiles.delete(filePath);
+                }
+            }
+            // 6. Batch persist all changes
+            if (supersededEntities.length > 0) {
+                await upsertEntities(supersededEntities);
+                await upsertEntityBranches(supersededEntities.map((e) => ({
+                    entitySha: e.sha,
+                    branchId: this.options.branchId,
+                    active: true,
+                })));
+            }
+            if (updatedEntities.length > 0) {
+                await upsertEntities(updatedEntities);
+                await upsertEntityBranches(updatedEntities.map((e) => ({
+                    entitySha: e.sha,
+                    branchId: this.options.branchId,
+                    active: true,
+                })));
+            }
+            if (newEntities.length > 0) {
+                await upsertEntities(newEntities);
+                await upsertEntityBranches(newEntities.map((e) => ({
+                    entitySha: e.sha,
+                    branchId: this.options.branchId,
+                    active: true,
+                })));
+            }
+            console.log(`[FileWatcher] Batch update complete: ${updatedEntities.length} updated, ${newEntities.length} new versions, ${supersededEntities.length} superseded`);
+            // Handle any files that need to be treated as adds
+            if (filesToAdd.length > 0) {
+                console.log(`[FileWatcher] Treating ${filesToAdd.length} files as adds (no existing entities)`);
+                await this.handleFileAddsBatch(filesToAdd);
+            }
+        }
+        catch (error) {
+            console.error(`[FileWatcher] Failed to handle batch file updates:`, error);
+        }
+    }
+    /**
+     * Process a file event (add, change, or delete)
+     * @deprecated Use processBatch() for better performance with multiple files
+     */
+    async processFileEvent(event) {
+        switch (event.type) {
+            case 'add':
+                await this.handleFileAdd(event.filePath);
+                break;
+            case 'delete':
+                await this.handleFileDelete(event.filePath);
+                break;
+            case 'change':
+                await this.updateEntitiesForFile(event.filePath);
+                break;
+        }
+    }
+    /**
+     * Handle a new file being added
+     */
+    async handleFileAdd(filePath) {
+        try {
+            // Skip test utility files
+            if (this.shouldIgnoreFilePath(filePath)) {
+                return;
+            }
+            console.log(`[FileWatcher] Handling new file: ${filePath}`);
+            // Refresh the TypeScript program to pick up the new file
+            if (this.projectAnalyzer) {
+                console.log(`[FileWatcher] Refreshing TypeScript program for new file: ${filePath}`);
+                this.projectAnalyzer.refreshProgram();
+            }
+            // Use cached project or load minimal project info (without files)
+            // We don't want to reload all files because the new file won't be there yet
+            const project = this.projectCache ||
+                (await loadProject({
+                    id: this.options.projectId,
+                    withFiles: false, // Don't reload all files - we'll add just the new one
+                }));
+            if (!project) {
+                throw new Error(`Project "${this.options.projectId}" not found in database`);
+            }
+            // Cache the project for future use
+            if (!this.projectCache) {
+                this.projectCache = project;
+            }
+            // Initialize files array if needed
+            if (!project.files) {
+                project.files = [];
+            }
+            // Add the new file to project.files
+            await getFilesWithEntitiesFromRepo({
+                project,
+                projectAnalyzer: this.projectAnalyzer,
+                filePath,
+                silent: true,
+            });
+            // Find the branch (may not exist for local CLI usage)
+            const branch = project.branches?.find((b) => b.id === this.options.branchId);
+            if (!branch) {
+                console.log(`[FileWatcher] Branch "${this.options.branchId}" not found in database (OK for local CLI usage), creating entities without branch`);
+            }
+            // Create entities for the new file
+            // In local CLI mode, branch might be undefined which is fine - entities will just have branchIds as empty array
+            await createEntitiesAndSortFiles({
+                project,
+                branch: branch || { id: this.options.branchId }, // Provide minimal branch object if not found
+                filePath,
+                projectAnalyzer: this.projectAnalyzer,
+            });
+            // Populate metadata for the new entities
+            const fileWithEntities = project.files.find((f) => f.path === filePath);
+            if (fileWithEntities && fileWithEntities.entities) {
+                await populateEntityMetadata([fileWithEntities], this.options.projectRootPath, this.projectAnalyzer);
+            }
+            // Add to known files
+            this.knownFiles.add(filePath);
+            const entityCount = fileWithEntities?.entities?.length || 0;
+            console.log(`[FileWatcher] Created ${entityCount} entities for new file: ${filePath}`);
+        }
+        catch (error) {
+            console.error(`[FileWatcher] Failed to handle new file ${filePath}:`, error);
+        }
+    }
+    /**
+     * Handle a file being deleted
+     */
+    async handleFileDelete(filePath) {
+        try {
+            // Skip test utility files
+            if (this.shouldIgnoreFilePath(filePath)) {
+                return;
+            }
+            console.log(`[FileWatcher] Handling file deletion: ${filePath}`);
+            // Load entities for this file
+            const entities = await loadEntities({
+                projectId: this.options.projectId,
+                branchId: this.options.branchId,
+                filePaths: [filePath],
+            });
+            if (!entities || entities.length === 0) {
+                console.log(`[FileWatcher] No entities found for deleted file: ${filePath}`);
+                this.knownFiles.delete(filePath);
+                return;
+            }
+            // Mark all entities as being deleted
+            const updatedEntities = entities.map((entity) => ({
+                ...entity,
+                metadata: {
+                    ...entity.metadata,
+                    isBeingDeleted: true,
+                    editedAt: new Date().toISOString(),
+                },
+            }));
+            // Persist updates to database
+            await upsertEntities(updatedEntities);
+            // Ensure entities are linked to the branch
+            await upsertEntityBranches(updatedEntities.map((e) => ({
+                entitySha: e.sha,
+                branchId: this.options.branchId,
+                active: true,
+            })));
+            console.log(`[FileWatcher] Marked ${updatedEntities.length} entities as being deleted in ${filePath}`, JSON.stringify(updatedEntities.map((e) => ({ name: e.name, isBeingDeleted: true })), null, 2));
+        }
+        catch (error) {
+            console.error(`[FileWatcher] Failed to handle file deletion ${filePath}:`, error);
+        }
+    }
+    /**
+     * Update entity metadata for a changed file
+     * Now handles entity versioning: creates new entity records when code changes
+     * and the entity already has analyses
+     */
+    async updateEntitiesForFile(filePath) {
+        try {
+            // Skip test utility files
+            if (this.shouldIgnoreFilePath(filePath)) {
+                return;
+            }
+            console.log(`Updating entities for changed file: ${filePath}`);
+            // Refresh the TypeScript program to pick up file changes
+            if (this.projectAnalyzer) {
+                console.log(`[FileWatcher] Refreshing TypeScript program for ${filePath}`);
+                this.projectAnalyzer.refreshProgram();
+            }
+            // Load existing entities from database for this file
+            const allEntities = await loadEntities({
+                projectId: this.options.projectId,
+                branchId: this.options.branchId,
+                filePaths: [filePath],
+            });
+            if (!allEntities || allEntities.length === 0) {
+                console.log(`No entities found for file: ${filePath}`);
+                // File has no entities in database yet, but might have entities in the code now
+                // Treat this as a new file addition
+                console.log(`[FileWatcher] Treating ${filePath} as new file (no existing entities)`);
+                await this.handleFileAdd(filePath);
+                return;
+            }
+            // Filter out superseded entities - we only want to process current versions
+            const existingEntities = allEntities.filter((e) => !e.metadata?.isSuperseded);
+            if (existingEntities.length === 0) {
+                console.log(`No non-superseded entities found for file: ${filePath}`);
+                return;
+            }
+            // Load analyses for these entities so we can detect if they have simulations
+            const entityShas = existingEntities.map((e) => e.sha);
+            console.log(`[FileWatcher] Loading analyses for ${entityShas.length} entity SHAs in ${filePath}:`, entityShas.map((s) => s.substring(0, 8)));
+            let analyses;
+            try {
+                analyses = await loadAnalyses({
+                    entityShas,
+                });
+                console.log(`[FileWatcher] loadAnalyses returned:`, analyses ? `${analyses.length} analyses` : 'null/undefined');
+            }
+            catch (error) {
+                console.error(`[FileWatcher] Error loading analyses:`, error);
+                analyses = null;
+            }
+            // Attach analyses to entities
+            if (analyses && analyses.length > 0) {
+                const analysisMap = new Map();
+                for (const analysis of analyses) {
+                    if (!analysisMap.has(analysis.entitySha)) {
+                        analysisMap.set(analysis.entitySha, []);
+                    }
+                    analysisMap.get(analysis.entitySha).push(analysis);
+                }
+                for (const entity of existingEntities) {
+                    entity.analyses = analysisMap.get(entity.sha) || [];
+                }
+                console.log(`[FileWatcher] Loaded ${analyses.length} analyses for ${existingEntities.length} entities in ${filePath}`, JSON.stringify(existingEntities.map((e) => ({
+                    name: e.name,
+                    sha: e.sha.substring(0, 8),
+                    isUncommitted: e.metadata?.isUncommitted,
+                    analysesCount: e.analyses?.length || 0,
+                })), null, 2));
+            }
+            else {
+                console.log(`[FileWatcher] No analyses found for entities in ${filePath} (analyses: ${analyses ? 'empty array' : 'null'})`);
+                // Still need to initialize analyses array to empty
+                for (const entity of existingEntities) {
+                    entity.analyses = [];
+                }
+            }
+            // Get current entities from the file analyzer
+            const fileAnalyzer = this.projectAnalyzer?.getFileAnalyzerByPath(filePath);
+            if (!fileAnalyzer) {
+                console.log(`No file analyzer found for ${filePath}`);
+                return;
+            }
+            const currentEntityNodes = fileAnalyzer.getAllEntityNodesOnlyAliases();
+            const currentEntityNames = new Set(Object.keys(currentEntityNodes));
+            const updatedEntities = [];
+            const newEntities = [];
+            const supersededEntities = [];
+            // Group existing entities by name to find the latest uncommitted version
+            const entitiesByName = new Map();
+            for (const entity of existingEntities) {
+                if (!entitiesByName.has(entity.name)) {
+                    entitiesByName.set(entity.name, []);
+                }
+                entitiesByName.get(entity.name).push(entity);
+            }
+            for (const entity of existingEntities) {
+                if (!currentEntityNames.has(entity.name)) {
+                    // Entity was deleted from the file
+                    updatedEntities.push({
+                        ...entity,
+                        metadata: {
+                            ...entity.metadata,
+                            isBeingDeleted: true,
+                            editedAt: new Date().toISOString(),
+                        },
+                    });
+                    console.log(`[FileWatcher] Entity ${entity.name} deleted from ${filePath}`);
+                }
+                else {
+                    // Entity still exists in file, check if code changed
+                    let currentCode;
+                    try {
+                        currentCode = fileAnalyzer.getEntityCode(entity.name);
+                    }
+                    catch (e) {
+                        console.error(`Failed to get code for entity ${entity.name}:`, e);
+                        continue;
+                    }
+                    const currentSha = generateSha(filePath, entity.name, currentCode);
+                    const entityMetadata = getEntityMetadata(filePath, this.options.projectRootPath, entity.name, this.projectAnalyzer);
+                    console.log(`[FileWatcher] SHA comparison for ${entity.name}: current=${currentSha.substring(0, 8)} vs entity=${entity.sha.substring(0, 8)} (match: ${currentSha === entity.sha})`);
+                    if (currentSha === entity.sha) {
+                        // Code hasn't changed, just update metadata
+                        console.log(`[FileWatcher] No code change for ${entity.name}, updating metadata only`);
+                        updatedEntities.push({
+                            ...entity,
+                            metadata: {
+                                ...entity.metadata,
+                                editedAt: entityMetadata.editedAt,
+                                isUncommitted: entityMetadata.isUncommitted,
+                                isBeingDeleted: false,
+                            },
+                        });
+                    }
+                    else {
+                        // Code has changed (SHA is different)
+                        console.log(`[FileWatcher] Entity ${entity.name} code changed (old SHA: ${entity.sha.substring(0, 8)}, new SHA: ${currentSha.substring(0, 8)})`);
+                        // Check if the current SHA matches any other version of this entity (revert detection)
+                        const allVersionsOfEntity = entitiesByName.get(entity.name) || [];
+                        const revertTarget = allVersionsOfEntity.find((e) => e.sha === currentSha && e.sha !== entity.sha);
+                        if (revertTarget) {
+                            // User has reverted to a previous version!
+                            console.log(`[FileWatcher] Detected revert for ${entity.name}: reverting to ${currentSha.substring(0, 8)} (was ${entity.sha.substring(0, 8)})`);
+                            // Get the latest committed version to check if this is a revert to committed state
+                            const latestCommittedForRevert = await getLatestCommittedVersion(this.options.projectId, this.options.branchId, filePath, entity.name);
+                            const isRevertToCommitted = latestCommittedForRevert &&
+                                currentSha === latestCommittedForRevert.sha;
+                            // Update the revert target to be current/uncommitted
+                            // If the revert target has analyses, clear version tracking metadata
+                            const hasAnalyses = revertTarget.analyses && revertTarget.analyses.length > 0;
+                            updatedEntities.push({
+                                ...revertTarget,
+                                metadata: {
+                                    ...revertTarget.metadata,
+                                    editedAt: entityMetadata.editedAt,
+                                    // Determine uncommitted status by comparing to committed version (avoid race condition)
+                                    isUncommitted: !isRevertToCommitted,
+                                    isBeingDeleted: false,
+                                    isSuperseded: false,
+                                    // Clear version tracking if reverting to a version with its own analyses
+                                    previousVersionWithAnalyses: hasAnalyses
+                                        ? undefined
+                                        : revertTarget.metadata?.previousVersionWithAnalyses,
+                                    previousCommittedSha: hasAnalyses
+                                        ? undefined
+                                        : revertTarget.metadata?.previousCommittedSha,
+                                },
+                            });
+                            // Mark current entity for deletion (it's now invalid)
+                            supersededEntities.push({
+                                ...entity,
+                                metadata: {
+                                    ...entity.metadata,
+                                    isSuperseded: true,
+                                    isBeingDeleted: true,
+                                },
+                            });
+                            // Mark any other intermediate versions as superseded
+                            allVersionsOfEntity.forEach((e) => {
+                                if (e.sha !== currentSha && e.sha !== entity.sha) {
+                                    supersededEntities.push({
+                                        ...e,
+                                        metadata: {
+                                            ...e.metadata,
+                                            isSuperseded: true,
+                                        },
+                                    });
+                                }
+                            });
+                            continue; // Skip normal versioning logic
+                        }
+                        // No revert detected, proceed with normal versioning
+                        // Check if we should create a new version or update existing
+                        const createNewVersion = shouldCreateNewVersion(entity);
+                        console.log(`[FileWatcher] shouldCreateNewVersion(${entity.name}): ${createNewVersion}`, JSON.stringify({
+                            isUncommitted: entity.metadata?.isUncommitted,
+                            analysesCount: entity.analyses?.length || 0,
+                            hasAnalyses: entity.analyses && entity.analyses.length > 0,
+                        }));
+                        if (createNewVersion) {
+                            // Entity has analyses, create new version
+                            console.log(`[FileWatcher] Creating new version for ${entity.name} (has ${entity.analyses?.length || 0} analyses)`);
+                            // Get the latest committed version SHA using git directly (more reliable)
+                            // Fall back to database lookup if git fails
+                            let committedSha = getCommittedEntityShaFromGit(this.options.projectRootPath, filePath, entity.name);
+                            // If git lookup failed, try database
+                            if (!committedSha) {
+                                const latestCommitted = await getLatestCommittedVersion(this.options.projectId, this.options.branchId, filePath, entity.name);
+                                committedSha = latestCommitted?.sha || null;
+                            }
+                            // Mark this entity as superseded
+                            supersededEntities.push({
+                                ...entity,
+                                metadata: {
+                                    ...entity.metadata,
+                                    isSuperseded: true,
+                                },
+                            });
+                            // Create new entity with updated SHA and code
+                            // Inherit analyses from previous version for display (they're marked as outdated via previousVersionWithAnalyses)
+                            // Check if new SHA matches the latest committed version (revert case)
+                            const isRevertToCommitted = committedSha && currentSha === committedSha;
+                            const newEntity = {
+                                ...entity,
+                                sha: currentSha,
+                                code: currentCode,
+                                analyses: entity.analyses || [], // Inherit analyses for display
+                                metadata: {
+                                    ...entity.metadata,
+                                    // Clear isolatedDataStructure - it was computed for the old code
+                                    // and must be recomputed for the new code during analysis
+                                    isolatedDataStructure: undefined,
+                                    editedAt: entityMetadata.editedAt,
+                                    // If code SHA changed, determine uncommitted status by comparing to committed version
+                                    // Don't rely on git check due to race condition
+                                    isUncommitted: !isRevertToCommitted,
+                                    isBeingDeleted: false,
+                                    isSuperseded: false,
+                                    previousCommittedSha: committedSha || undefined,
+                                    // If the previous entity already inherited analyses, maintain that chain
+                                    // Otherwise, point to the previous entity as the source
+                                    previousVersionWithAnalyses: entity.metadata?.previousVersionWithAnalyses || entity.sha,
+                                },
+                                createdAt: new Date().toISOString(),
+                            };
+                            newEntities.push(newEntity);
+                        }
+                        else {
+                            // No analyses yet, safe to update existing entity
+                            console.log(`[FileWatcher] Updating existing ${entity.name} (no analyses)`);
+                            // Get the latest committed version SHA using git directly (more reliable)
+                            // Fall back to database lookup if git fails
+                            let committedShaForUpdate = getCommittedEntityShaFromGit(this.options.projectRootPath, filePath, entity.name);
+                            // If git lookup failed, try database
+                            if (!committedShaForUpdate) {
+                                const latestCommittedForUpdate = await getLatestCommittedVersion(this.options.projectId, this.options.branchId, filePath, entity.name);
+                                committedShaForUpdate = latestCommittedForUpdate?.sha || null;
+                            }
+                            const isRevertToCommitted = committedShaForUpdate && currentSha === committedShaForUpdate;
+                            updatedEntities.push({
+                                ...entity,
+                                sha: currentSha,
+                                code: currentCode,
+                                metadata: {
+                                    ...entity.metadata,
+                                    editedAt: entityMetadata.editedAt,
+                                    // If code SHA changed, determine uncommitted status by comparing to committed version
+                                    // Don't rely on git check due to race condition
+                                    isUncommitted: !isRevertToCommitted,
+                                    isBeingDeleted: false,
+                                    previousCommittedSha: committedShaForUpdate || undefined,
+                                },
+                            });
+                        }
+                    }
+                }
+            }
+            // Persist all changes
+            if (supersededEntities.length > 0) {
+                await upsertEntities(supersededEntities);
+                // Ensure superseded entities are linked to the branch
+                await upsertEntityBranches(supersededEntities.map((e) => ({
+                    entitySha: e.sha,
+                    branchId: this.options.branchId,
+                    active: true,
+                })));
+                console.log(`[FileWatcher] Marked ${supersededEntities.length} entities as superseded`);
+            }
+            if (updatedEntities.length > 0) {
+                await upsertEntities(updatedEntities);
+                // Ensure updated entities are linked to the branch
+                await upsertEntityBranches(updatedEntities.map((e) => ({
+                    entitySha: e.sha,
+                    branchId: this.options.branchId,
+                    active: true,
+                })));
+            }
+            if (newEntities.length > 0) {
+                await upsertEntities(newEntities);
+                // Link new entities to the branch
+                await upsertEntityBranches(newEntities.map((e) => ({
+                    entitySha: e.sha,
+                    branchId: this.options.branchId,
+                    active: true,
+                })));
+                console.log(`[FileWatcher] Created ${newEntities.length} new entity versions`, JSON.stringify(newEntities.map((e) => ({
+                    name: e.name,
+                    newSha: e.sha.substring(0, 8),
+                    previousCommittedSha: e.metadata?.previousCommittedSha?.substring(0, 8),
+                })), null, 2));
+            }
+            const beingDeleted = updatedEntities.filter((e) => e.metadata?.isBeingDeleted).length;
+            const uncommitted = updatedEntities.filter((e) => e.metadata?.isUncommitted).length;
+            // Update the uncommittedFiles cache so git watcher knows about this file
+            const allProcessedEntities = [...updatedEntities, ...newEntities];
+            const hasUncommittedEntity = allProcessedEntities.some((e) => e.metadata?.isUncommitted);
+            if (hasUncommittedEntity) {
+                // File has uncommitted changes, add to cache
+                if (!this.uncommittedFiles.has(filePath)) {
+                    this.uncommittedFiles.add(filePath);
+                    console.log(`[FileWatcher] Added ${filePath} to uncommitted files cache`);
+                }
+            }
+            else if (this.uncommittedFiles.has(filePath)) {
+                // All entities are committed, remove from cache
+                this.uncommittedFiles.delete(filePath);
+                console.log(`[FileWatcher] Removed ${filePath} from uncommitted files cache`);
+            }
+            console.log(`Processed ${updatedEntities.length + newEntities.length} entities in ${filePath} (uncommitted: ${uncommitted}, being deleted: ${beingDeleted}, new versions: ${newEntities.length})`);
+        }
+        catch (error) {
+            console.error(`Failed to update entities for ${filePath}:`, error);
+        }
+    }
+    /**
+     * Initialize the cache of uncommitted files
+     */
+    initializeUncommittedCache() {
+        try {
+            this.uncommittedFiles = getUncommittedFiles(this.options.projectRootPath);
+            console.log(`[FileWatcher] Initialized with ${this.uncommittedFiles.size} uncommitted files`);
+        }
+        catch (error) {
+            console.error('[FileWatcher] Failed to initialize uncommitted cache:', error);
+        }
+    }
+    /**
+     * Start watching git directory for commits
+     */
+    startGitWatcher() {
+        try {
+            const gitPath = path.join(this.options.projectRootPath, '.git');
+            // Check if .git directory exists
+            if (!fs.existsSync(gitPath)) {
+                console.log('No .git directory found, skipping git watcher');
+                return;
+            }
+            // Watch the .git directory for changes
+            // We specifically watch for changes to HEAD and refs which indicate commits
+            this.gitWatcher = fs.watch(gitPath, { recursive: true }, (eventType, filename) => {
+                if (!filename)
+                    return;
+                // Only respond to changes in HEAD, refs/heads, or index
+                // These indicate commits, branch changes, or staged changes
+                if (filename === 'HEAD' ||
+                    filename.startsWith('refs/heads/') ||
+                    filename === 'index' ||
+                    filename.startsWith('logs/refs/heads/')) {
+                    console.log(`[FileWatcher] Git change detected: ${filename}`);
+                    this.handleGitChange();
+                }
+            });
+            console.log(`Watching for git commits in: ${gitPath}`);
+        }
+        catch (error) {
+            console.error('Failed to watch .git directory:', error);
+        }
+    }
+    /**
+     * Handle git changes (commits, etc.) with debouncing
+     */
+    handleGitChange() {
+        // Use a special key for git changes
+        const gitKey = '__git_commit__';
+        // Clear existing timeout
+        const existingTimeout = this.updateQueue.get(gitKey);
+        if (existingTimeout) {
+            clearTimeout(existingTimeout);
+        }
+        // Set new timeout to update after debounce period
+        const timeout = setTimeout(() => {
+            this.handleCommit().catch(() => { });
+            this.updateQueue.delete(gitKey);
+        }, this.DEBOUNCE_MS);
+        this.updateQueue.set(gitKey, timeout);
+    }
+    /**
+     * Handle a git commit by checking which files were committed
+     * and updating their isUncommitted status. Also handles deletion
+     * of entities marked as isBeingDeleted.
+     */
+    async handleCommit() {
+        try {
+            console.log('[FileWatcher] Checking for committed files...');
+            // Get the current list of uncommitted files
+            const currentUncommitted = getUncommittedFiles(this.options.projectRootPath);
+            console.log('[FileWatcher] currentUncommitted', JSON.stringify(Array.from(currentUncommitted), null, 2));
+            // Find files that were previously uncommitted but are now committed
+            const committedFiles = Array.from(this.uncommittedFiles).filter((file) => !currentUncommitted.has(file) && /\.(ts|tsx|js|jsx)$/.test(file));
+            console.log('[FileWatcher] committedFiles', JSON.stringify(Array.from(committedFiles), null, 2));
+            // Find files that are no longer tracked (deleted and committed)
+            const deletedFiles = Array.from(this.knownFiles).filter((file) => {
+                const fullPath = path.join(this.options.projectRootPath, file);
+                return !fs.existsSync(fullPath) && !currentUncommitted.has(file);
+            });
+            console.log('[FileWatcher] deletedFiles (committed deletions)', JSON.stringify(deletedFiles, null, 2));
+            if (committedFiles.length === 0 && deletedFiles.length === 0) {
+                console.log('[FileWatcher] No TypeScript/JavaScript files were committed or deleted');
+                this.uncommittedFiles = currentUncommitted;
+                return;
+            }
+            console.log(`[FileWatcher] Detected commit of ${committedFiles.length} files and deletion of ${deletedFiles.length} files`);
+            // Update the uncommitted files cache
+            this.uncommittedFiles = currentUncommitted;
+            // Handle committed deletions - remove entities from database
+            if (deletedFiles.length > 0) {
+                for (const deletedFile of deletedFiles) {
+                    // Load entities for the deleted file
+                    const deletedEntities = await loadEntities({
+                        projectId: this.options.projectId,
+                        branchId: this.options.branchId,
+                        filePaths: [deletedFile],
+                    });
+                    if (deletedEntities && deletedEntities.length > 0) {
+                        // Delete all entities for this file
+                        const entityShas = deletedEntities.map((e) => e.sha);
+                        await deleteEntities({
+                            projectId: this.options.projectId,
+                            shas: entityShas,
+                        });
+                        console.log(`[FileWatcher] Deleted ${entityShas.length} entities for committed deletion of ${deletedFile}`, JSON.stringify(deletedEntities.map((e) => ({ name: e.name, sha: e.sha })), null, 2));
+                    }
+                    // Remove from known files
+                    this.knownFiles.delete(deletedFile);
+                }
+            }
+            // Handle regular commits - update isUncommitted status
+            if (committedFiles.length > 0) {
+                // Load entities for all committed files
+                const allEntities = await loadEntities({
+                    projectId: this.options.projectId,
+                    branchId: this.options.branchId,
+                    filePaths: committedFiles,
+                });
+                if (!allEntities || allEntities.length === 0) {
+                    console.log('[FileWatcher] No entities found for committed files');
+                    return;
+                }
+                // Filter out superseded entities - only update current versions
+                const entities = allEntities.filter((e) => !e.metadata?.isSuperseded);
+                console.log(`[FileWatcher] Loaded ${allEntities.length} entities for committed files, ${entities.length} non-superseded`, JSON.stringify(allEntities.map((e) => ({
+                    name: e.name,
+                    sha: e.sha.substring(0, 8),
+                    isSuperseded: e.metadata?.isSuperseded,
+                    filePath: e.filePath,
+                })), null, 2));
+                if (entities.length === 0) {
+                    console.log('[FileWatcher] No non-superseded entities found for committed files');
+                    return;
+                }
+                // Separate entities that should be deleted from those that should be updated
+                const entitiesToDelete = [];
+                const entitiesToUpdate = [];
+                for (const entity of entities) {
+                    if (entity.metadata?.isBeingDeleted) {
+                        // Entity is marked for deletion and commit confirmed it
+                        entitiesToDelete.push(entity);
+                    }
+                    else {
+                        // Regular entity, update its metadata
+                        const entityMetadata = getEntityMetadata(entity.filePath, this.options.projectRootPath, entity.name, this.projectAnalyzer);
+                        entitiesToUpdate.push({
+                            ...entity,
+                            metadata: {
+                                ...entity.metadata,
+                                editedAt: entityMetadata.editedAt,
+                                isUncommitted: entityMetadata.isUncommitted,
+                                isBeingDeleted: false, // Clear the deletion flag if it was set
+                            },
+                        });
+                    }
+                }
+                // Delete entities marked for deletion
+                if (entitiesToDelete.length > 0) {
+                    const entityShas = entitiesToDelete.map((e) => e.sha);
+                    await deleteEntities({
+                        projectId: this.options.projectId,
+                        shas: entityShas,
+                    });
+                    console.log(`[FileWatcher] Deleted ${entitiesToDelete.length} entities marked as isBeingDeleted after commit`, JSON.stringify(entitiesToDelete.map((e) => ({
+                        name: e.name,
+                        filePath: e.filePath,
+                        sha: e.sha,
+                    })), null, 2));
+                }
+                // Update remaining entities
+                if (entitiesToUpdate.length > 0) {
+                    await upsertEntities(entitiesToUpdate);
+                    // Ensure entities are linked to the branch
+                    await upsertEntityBranches(entitiesToUpdate.map((e) => ({
+                        entitySha: e.sha,
+                        branchId: this.options.branchId,
+                        active: true,
+                    })));
+                    const nowCommitted = entitiesToUpdate.filter((e) => !e.metadata.isUncommitted).length;
+                    console.log(`[FileWatcher] Updated ${entitiesToUpdate.length} entities after commit (${nowCommitted} now committed)`, JSON.stringify(entitiesToUpdate.map((e) => ({
+                        name: e.name,
+                        filePath: e.filePath,
+                        isUncommitted: e.metadata.isUncommitted,
+                    })), null, 2));
+                }
+                // CLEANUP: Delete uncommitted entity versions that don't match current filesystem
+                console.log('[FileWatcher] Cleaning up uncommitted entity versions...');
+                await this.cleanupUncommittedVersions(committedFiles);
+            }
+        }
+        catch (error) {
+            console.error('[FileWatcher] Failed to handle commit:', error);
+        }
+    }
+    /**
+     * Clean up uncommitted entity versions after a commit
+     * Deletes all uncommitted versions except the one matching current filesystem
+     */
+    async cleanupUncommittedVersions(committedFiles) {
+        try {
+            // Load project to get project slug for file cleanup
+            const project = await loadProjectWithSlug({
+                id: this.options.projectId,
+            });
+            if (!project || !project.slug) {
+                console.error('[FileWatcher] Could not load project slug for cleanup');
+                return;
+            }
+            const projectSlug = project.slug;
+            for (const filePath of committedFiles) {
+                // Load all entities for this file (committed and uncommitted)
+                const allEntities = await loadEntities({
+                    projectId: this.options.projectId,
+                    branchId: this.options.branchId,
+                    filePaths: [filePath],
+                });
+                if (!allEntities || allEntities.length === 0) {
+                    continue;
+                }
+                // Get file analyzer to check current filesystem state
+                const fileAnalyzer = this.projectAnalyzer?.getFileAnalyzerByPath(filePath);
+                if (!fileAnalyzer) {
+                    console.log(`[FileWatcher] No file analyzer for ${filePath}, skipping cleanup`);
+                    continue;
+                }
+                // Group entities by name
+                const entitiesByName = new Map();
+                for (const entity of allEntities) {
+                    if (!entitiesByName.has(entity.name)) {
+                        entitiesByName.set(entity.name, []);
+                    }
+                    entitiesByName.get(entity.name).push(entity);
+                }
+                // For each entity name, clean up old uncommitted versions
+                for (const [entityName, versions] of entitiesByName.entries()) {
+                    // Get current code from filesystem
+                    let currentCode;
+                    try {
+                        currentCode = fileAnalyzer.getEntityCode(entityName);
+                    }
+                    catch (e) {
+                        console.log(`[FileWatcher] Could not get code for ${entityName}, skipping cleanup`);
+                        continue;
+                    }
+                    const currentSha = generateSha(filePath, entityName, currentCode);
+                    // Find uncommitted versions that don't match current SHA
+                    const uncommittedVersions = versions.filter((v) => v.metadata?.isUncommitted);
+                    const versionsToDelete = uncommittedVersions.filter((v) => v.sha !== currentSha);
+                    if (versionsToDelete.length === 0) {
+                        continue;
+                    }
+                    console.log(`[FileWatcher] Deleting ${versionsToDelete.length} old uncommitted versions of ${entityName} in ${filePath}`, JSON.stringify(versionsToDelete.map((v) => ({
+                        sha: v.sha.substring(0, 8),
+                        hasAnalyses: v.analyses && v.analyses.length > 0,
+                    })), null, 2));
+                    // Delete analysis files for each version
+                    for (const version of versionsToDelete) {
+                        if (version.analyses && version.analyses.length > 0) {
+                            for (const analysis of version.analyses) {
+                                deleteAnalysisFiles(projectSlug, analysis);
+                            }
+                        }
+                    }
+                    // Delete the entity records
+                    const shasToDelete = versionsToDelete.map((v) => v.sha);
+                    if (shasToDelete.length > 0) {
+                        await deleteEntities({
+                            projectId: this.options.projectId,
+                            shas: shasToDelete,
+                        });
+                    }
+                    // Clear isSuperseded flag from remaining versions
+                    const remainingVersions = versions.filter((v) => !shasToDelete.includes(v.sha));
+                    const versionsToUpdate = remainingVersions.filter((v) => v.metadata?.isSuperseded);
+                    if (versionsToUpdate.length > 0) {
+                        const updated = versionsToUpdate.map((v) => ({
+                            ...v,
+                            metadata: {
+                                ...v.metadata,
+                                isSuperseded: false,
+                            },
+                        }));
+                        await upsertEntities(updated);
+                        // Ensure entities are linked to the branch
+                        await upsertEntityBranches(updated.map((e) => ({
+                            entitySha: e.sha,
+                            branchId: this.options.branchId,
+                            active: true,
+                        })));
+                        console.log(`[FileWatcher] Cleared isSuperseded flag from ${updated.length} entities`);
+                    }
+                }
+            }
+            console.log('[FileWatcher] Cleanup completed');
+        }
+        catch (error) {
+            console.error('[FileWatcher] Error during uncommitted version cleanup:', error);
+            // Don't throw - cleanup is best-effort
+        }
+    }
+    /**
+     * Perform periodic memory cleanup
+     */
+    performMemoryCleanup() {
+        console.log('[FileWatcher] Performing memory cleanup...');
+        // Cleanup entity cache
+        this.entityCache.cleanup();
+        // Cleanup folder burst detector
+        // (already has internal cleanup, but we can get stats)
+        const burstStats = this.folderBurstDetector.getStats();
+        if (burstStats.ignoredFolders > 0) {
+            console.log(`[FileWatcher] Burst detector: ${burstStats.ignoredFolders} ignored folders, ` +
+                `${burstStats.trackedFolders} tracked`);
+        }
+        // Cleanup knownFiles if too large
+        if (this.knownFiles.size > this.MAX_KNOWN_FILES) {
+            console.warn(`[FileWatcher] knownFiles exceeded ${this.MAX_KNOWN_FILES}, clearing cache`);
+            this.knownFiles.clear();
+            // Will be repopulated on next file operation
+        }
+        // Log cache stats
+        const cacheStats = this.entityCache.getStats();
+        const mem = process.memoryUsage();
+        console.log(`[FileWatcher] Cleanup complete. ` +
+            `Cache: ${cacheStats.size} entries (~${cacheStats.memoryMB.toFixed(1)}MB), ` +
+            `Heap: ${Math.round(mem.heapUsed / 1024 / 1024)}MB / ${Math.round(mem.heapTotal / 1024 / 1024)}MB`);
+    }
+}
+/**
+ * Create and start a file watcher.
+ * Returns a promise that resolves when the watcher is fully initialized,
+ * including the initial sync of all uncommitted files.
+ */
+export async function createFileWatcher(options) {
+    const watcher = new FileWatcher(options);
+    await watcher.start();
+    return watcher;
+}
+//# sourceMappingURL=fileWatcher.js.map