How Watch Mode in code-review-graph Detects File Changes and Triggers Incremental Updates

Watch mode in the code-review-graph VS Code extension uses a three-layer architecture combining command-based CLI entry points, VS Code FileSystemWatcher instances, and debounced callbacks to automatically detect SQLite database changes and refresh the graph view without manual intervention.

The repository tirth8205/code-review-graph implements an intelligent file monitoring system that keeps the code review graph synchronized with your evolving codebase. When enabled, watch mode tracks modifications to the underlying SQLite database and triggers incremental updates to the UI components.

Architecture Overview: The Three-Layer Detection System

The watch mode implementation spans three tightly coupled layers that work together to provide seamless real-time updates. According to the source code in src/extension.ts and src/backend/watcher.ts, the system combines CLI command registration, file system event listeners, and debounced change detection to manage the graph database lifecycle.

The architecture ensures that developers only need to enable watch mode once, after which any changes to source files that affect the graph are automatically reflected in the VS Code UI.

Layer 1: Command Registration and CLI Entry Point

The watch mode journey begins in src/extension.ts at lines 547-560, where the extension registers the codeReviewGraph.watchGraph command. When a user selects "Code Review Graph: Watch Graph" from the command palette, the extension invokes CliWrapper.watchGraph(workspaceRoot) to initialize the monitoring daemon.

This entry point serves as the bridge between user interaction and the backend file monitoring system, forwarding the workspace root path to the underlying watcher implementation.

Layer 2: Real-Time File System Monitoring

The watchGraphDb function (lines 94-136 in src/extension.ts) creates a VS Code FileSystemWatcher that listens for create, change, and delete events on the pattern **/.code-review-graph/graph.db. This watcher monitors the generated SQLite database file that stores the code review graph data.

When the underlying analysis tool rebuilds the graph, it rewrites this database file, triggering the watcher events. The handler implementation manages the SqliteReader lifecycle by closing the existing connection and opening a fresh one pointing to the updated file.

function watchGraphDb(context: vscode.ExtensionContext): void {
  const watcher = vscode.workspace.createFileSystemWatcher(
    "**/.code-review-graph/graph.db"
  );

  // Re-open the DB on change
  watcher.onDidChange(() => {
    if (sqliteReader && dbPathRef.current) {
      sqliteReader.close();
      sqliteReader = new SqliteReader(dbPathRef.current);
      vscode.commands.executeCommand("codeReviewGraph.codeGraph.refresh");
    }
  });

  // Initialize on first creation
  watcher.onDidCreate(async () => {
    const wsRoot = getWorkspaceRoot();
    if (wsRoot && !sqliteReader) {
      const dbPath = findGraphDb(wsRoot);
      if (dbPath) {
        dbPathRef.current = dbPath;
        sqliteReader = new SqliteReader(dbPath);
        vscode.commands.executeCommand("codeReviewGraph.codeGraph.refresh");
      }
    }
  });

  // Clean up on delete
  watcher.onDidDelete(() => {
    sqliteReader?.close();
    sqliteReader = undefined;
    dbPathRef.current = "";
  });

  context.subscriptions.push(watcher);
}

Layer 3: Debounced Change Detection

The GraphWatcher class in src/backend/watcher.ts (lines 25-60) provides a specialized implementation that wraps a FileSystemWatcher around the graph.db file itself. This class implements a 500ms debounce on the onChanged callback to prevent rapid successive updates when the graph database is being rebuilt.

Using vscode.RelativePattern, the watcher monitors the specific database file path and ensures that burst write operations only trigger a single refresh cycle. The class also implements the vscode.Disposable interface for proper resource cleanup.

export class GraphWatcher implements vscode.Disposable {
  constructor(dbPath: string, onChanged: () => void) {
    const dir = path.dirname(dbPath);
    const filename = path.basename(dbPath);
    this.watcher = vscode.workspace.createFileSystemWatcher(
      new vscode.RelativePattern(vscode.Uri.file(dir), filename)
    );
    const debounced = debounce(onChanged, 500);
    this.disposables.push(
      this.watcher.onDidChange(() => debounced()),
      this.watcher.onDidCreate(() => debounced()),
      this.watcher
    );
  }
  dispose() { /* cleanup implementation */ }
}

Database Lifecycle and UI Synchronization

When a file change event fires, the system executes a precise sequence to maintain data integrity and UI consistency. First, the current SqliteReader instance closes its connection to prevent file locks. Then, a new reader opens a connection to the updated database file.

Immediately after the database refresh, the extension executes the codeReviewGraph.codeGraph.refresh command to rebuild the tree view. This triggers updates across optional UI components including the graph webview, SCM decorations, and the output channel, ensuring the entire interface reflects the newest graph state.

Summary

• Watch mode in code-review-graph operates through a three-layer architecture combining CLI commands, file system watchers, and debounced detection.
• The watchGraphDb function in src/extension.ts creates a FileSystemWatcher monitoring **/.code-review-graph/graph.db for create, change, and delete events.
• The GraphWatcher class in src/backend/watcher.ts implements a 500ms debounce to optimize performance during rapid database rebuilds.
• Database connections cycle through close-and-reopen operations to prevent file locks while ensuring data freshness.
• UI updates propagate automatically via the codeReviewGraph.codeGraph.refresh command, synchronizing the tree view, SCM decorations, and webview components.

Frequently Asked Questions

What file pattern does watch mode monitor?

Watch mode monitors the SQLite database file at **/.code-review-graph/graph.db rather than individual source files. This pattern ensures the extension detects changes only after the underlying analysis tool has completed graph reconstruction, preventing partial or inconsistent updates.

How does watch mode prevent excessive updates during rapid file changes?

The GraphWatcher class implements a 500-millisecond debounce on change callbacks. When the database file undergoes rapid successive writes during graph rebuilding, the debounce mechanism consolidates multiple events into a single refresh cycle, optimizing performance and preventing UI flicker.

What happens when the graph.db file is deleted while watch mode is active?

The watchGraphDb function includes an onDidDelete event handler that closes the current SqliteReader connection and clears the database path reference. This prevents errors from stale file handles and allows the system to reinitialize cleanly when the file is recreated.

Can watch mode detect changes in multiple workspace folders simultaneously?

Yes, the architecture supports multi-root workspaces. The CliWrapper.watchGraph method accepts the workspaceRoot parameter, and the file watcher pattern **/.code-review-graph/graph.db matches database files across all workspace folders, triggering independent refresh cycles for each detected change.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}