clangd-query/dist/file-watcher.d.ts

Fast C++ code intelligence CLI tool for humans and AI agents. Provides semantic search, source code reading and usage lookups.

/**
 * File Watcher for clangd automatic reindexing
 *
 * This module monitors the project's C++ source files and notifies clangd about changes
 * so that it can maintain an up-to-date index. This is crucial for accurate code
 * intelligence features like symbol search, references, and type hierarchy.
 *
 * Why this is needed:
 * - When files are modified outside of clangd's editor context, it doesn't automatically
 *   detect these changes
 * - Without file watching, the index becomes stale and queries return outdated results
 * - This ensures that clangd's understanding of the codebase stays synchronized with
 *   the actual file system state
 *
 * Implementation notes:
 * - Uses chokidar v4 for efficient file system monitoring with minimal dependencies
 * - Filters to only watch C++ source files (*.cpp, *.cc, *.h, *.hpp, etc.)
 * - Respects .gitignore patterns and common build directories
 * - Debounces file change events to batch notifications and reduce overhead
 *
 * Reindexing workaround:
 * - The LSP workspace/didChangeWatchedFiles notification alone doesn't reliably trigger
 *   reindexing in clangd
 * - We work around this by forcibly closing and reopening changed files, which makes
 *   clangd re-read them from disk and update its index
 * - This workaround is implemented in ClangdClient.sendFileChangeNotification()
 */
import { Logger } from "./logger.js";
export declare enum FileChangeType {
    Created = 1,
    Changed = 2,
    Deleted = 3
}
export interface FileEvent {
    uri: string;
    type: FileChangeType;
}
export interface FileWatcherOptions {
    /**
     * The project root directory to watch
     */
    projectRoot: string;
    /**
     * Callback function to be called when file changes are detected
     */
    onFileChanges: (changes: FileEvent[]) => void;
    /**
     * Logger instance for debugging
     */
    logger?: Logger;
    /**
     * Debounce delay in milliseconds (default: 500)
     */
    debounceMs?: number;
}
/**
 * FileWatcher manages file system monitoring for C++ source files and notifies
 * about changes via batched, debounced callbacks.
 */
export declare class FileWatcher {
    private watcher;
    private changedFilesBuffer;
    private debounceTimer;
    private readonly projectRoot;
    private readonly onFileChanges;
    private readonly logger?;
    private readonly debounceMs;
    private static readonly CPP_EXTENSIONS;
    constructor(options: FileWatcherOptions);
    /**
     * Start watching for file changes
     */
    start(): Promise<void>;
    /**
     * Stop watching for file changes
     */
    stop(): Promise<void>;
    /**
     * Check if a file has a C++ extension
     */
    private isCppFile;
    /**
     * Handle a file change event
     */
    private onFileChange;
    /**
     * Debounced function to send file change notifications
     */
    private debounceSendNotification;
    /**
     * Check if compile_commands.json has changed in the recent file events
     */
    hasCompileCommandsChanged(): boolean;
}
//# sourceMappingURL=file-watcher.d.ts.map