Function startFileWatcher

src/core/file-watcher.ts:32–66

(opts: FileWatcherOptions)

 * Returns a stop() function that cancels the debounce timer and closes the watcher.
 */
export function startFileWatcher(opts: FileWatcherOptions): () => void {
  const { rootPath, debounceMs = 2000, extraExtensions, onReady, onChanged } = opts;
  const trackedExtensions = new Set(
    getSupportedExtensions(extraExtensions).map((extension) => extension.toLowerCase())
  );
  let debounceTimer: ReturnType<typeof setTimeout> | undefined;

  const trigger = (filePath: string) => {
    if (!isTrackedSourcePath(filePath, trackedExtensions)) return;
    if (debounceTimer !== undefined) clearTimeout(debounceTimer);
    debounceTimer = setTimeout(() => {
      debounceTimer = undefined;
      onChanged();
    }, debounceMs);
  };

  const watcher = chokidar.watch(rootPath, {
    ignored: [...EXCLUDED_GLOB_PATTERNS],
    persistent: true,
    ignoreInitial: true,
    awaitWriteFinish: { stabilityThreshold: 200, pollInterval: 100 }
  });

  watcher
    .on('ready', () => onReady?.())
    .on('add', trigger)
    .on('change', trigger)
    .on('unlink', trigger)
    .on('error', (err: unknown) => console.error('[file-watcher] error:', err));

  return () => {
    if (debounceTimer !== undefined) clearTimeout(debounceTimer);
    void watcher.close();
  };
}