bluera-knowledge 0.9.21

package/src/services/watch.service.test.ts

@@ -0,0 +1,553 @@
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import { WatchService } from './watch.service.js';
+import type { IndexService } from './index.service.js';
+import type { LanceStore } from '../db/lance.js';
+import type { FileStore, RepoStore } from '../types/store.js';
+
+// Create fresh mock watcher for each call
+const createMockWatcher = () => ({
+  on: vi.fn().mockReturnThis(),
+  close: vi.fn().mockResolvedValue(undefined),
+});
+
+let mockWatchers: ReturnType<typeof createMockWatcher>[] = [];
+
+// Mock chokidar
+vi.mock('chokidar', () => ({
+  watch: vi.fn(() => {
+    const watcher = createMockWatcher();
+    mockWatchers.push(watcher);
+    return watcher;
+  }),
+}));
+
+describe('WatchService', () => {
+  let watchService: WatchService;
+  let mockIndexService: IndexService;
+  let mockLanceStore: LanceStore;
+  let mockFileStore: FileStore;
+  let mockRepoStore: RepoStore;
+
+  beforeEach(async () => {
+    // Clear mock watchers array
+    mockWatchers = [];
+
+    // Reset mocks
+    vi.clearAllMocks();
+    vi.useFakeTimers();
+
+    // Create mock services
+    mockIndexService = {
+      indexStore: vi.fn().mockResolvedValue({ ok: true }),
+    } as unknown as IndexService;
+
+    mockLanceStore = {
+      initialize: vi.fn().mockResolvedValue(undefined),
+    } as unknown as LanceStore;
+
+    mockFileStore = {
+      id: 'file-store-1',
+      type: 'file',
+      path: '/test/path',
+      name: 'Test File Store',
+      description: 'Test store',
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    };
+
+    mockRepoStore = {
+      id: 'repo-store-1',
+      type: 'repo',
+      path: '/test/repo',
+      name: 'Test Repo Store',
+      description: 'Test repo',
+      url: 'https://github.com/test/repo',
+      branch: 'main',
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    };
+
+    watchService = new WatchService(mockIndexService, mockLanceStore);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe('watch - Lifecycle', () => {
+    it('starts watching a file store', async () => {
+      const { watch } = await import('chokidar');
+
+      await watchService.watch(mockFileStore);
+
+      expect(watch).toHaveBeenCalledWith(mockFileStore.path, expect.objectContaining({
+        ignored: expect.any(RegExp),
+        persistent: true,
+        ignoreInitial: true,
+      }));
+    });
+
+    it('starts watching a repo store', async () => {
+      const { watch } = await import('chokidar');
+
+      await watchService.watch(mockRepoStore);
+
+      expect(watch).toHaveBeenCalledWith(mockRepoStore.path, expect.any(Object));
+    });
+
+    it('sets up event handlers on watcher', async () => {
+      await watchService.watch(mockFileStore);
+
+      const watcher = mockWatchers[0];
+      expect(watcher?.on).toHaveBeenCalledWith('all', expect.any(Function));
+      expect(watcher?.on).toHaveBeenCalledWith('error', expect.any(Function));
+    });
+
+    it('does not start watching if already watching the same store', async () => {
+      const { watch } = await import('chokidar');
+
+      await watchService.watch(mockFileStore);
+      const callCount1 = (watch as ReturnType<typeof vi.fn>).mock.calls.length;
+
+      await watchService.watch(mockFileStore);
+      const callCount2 = (watch as ReturnType<typeof vi.fn>).mock.calls.length;
+
+      expect(callCount2).toBe(callCount1);
+    });
+
+    it('allows watching multiple different stores', async () => {
+      const { watch } = await import('chokidar');
+
+      await watchService.watch(mockFileStore);
+      await watchService.watch(mockRepoStore);
+
+      expect(watch).toHaveBeenCalledTimes(2);
+    });
+
+    it('resolves immediately when store is already being watched', async () => {
+      await watchService.watch(mockFileStore);
+
+      const startTime = Date.now();
+      await watchService.watch(mockFileStore);
+      const endTime = Date.now();
+
+      // Should resolve immediately
+      expect(endTime - startTime).toBeLessThan(10);
+    });
+  });
+
+  describe('watch - Debounce Logic', () => {
+    it('debounces rapid file changes with default timeout', async () => {
+      await watchService.watch(mockFileStore);
+
+      const watcher = mockWatchers[0];
+      const allHandler = (watcher?.on as ReturnType<typeof vi.fn>).mock.calls.find(
+        (call: unknown[]) => call[0] === 'all'
+      )?.[1] as (() => void) | undefined;
+
+      // Trigger multiple rapid changes
+      allHandler?.();
+      allHandler?.();
+      allHandler?.();
+
+      // Fast-forward less than debounce time
+      vi.advanceTimersByTime(500);
+
+      // Should not have triggered reindex yet
+      expect(mockIndexService.indexStore).not.toHaveBeenCalled();
+
+      // Fast-forward past debounce time
+      vi.advanceTimersByTime(600);
+      await vi.runAllTimersAsync();
+
+      // Should have triggered reindex only once
+      expect(mockIndexService.indexStore).toHaveBeenCalledTimes(1);
+    });
+
+    it('uses custom debounce timeout', async () => {
+      await watchService.watch(mockFileStore, 2000);
+
+      const watcher = mockWatchers[0];
+      const allHandler = (watcher?.on as ReturnType<typeof vi.fn>).mock.calls.find(
+        (call: unknown[]) => call[0] === 'all'
+      )?.[1] as (() => void) | undefined;
+
+      allHandler?.();
+
+      // Advance less than custom debounce
+      vi.advanceTimersByTime(1500);
+      expect(mockIndexService.indexStore).not.toHaveBeenCalled();
+
+      // Advance past custom debounce
+      vi.advanceTimersByTime(600);
+      await vi.runAllTimersAsync();
+
+      expect(mockIndexService.indexStore).toHaveBeenCalledTimes(1);
+    });
+
+    it('resets debounce timer on each change', async () => {
+      await watchService.watch(mockFileStore, 1000);
+
+      const watcher = mockWatchers[0];
+      const allHandler = (watcher?.on as ReturnType<typeof vi.fn>).mock.calls.find(
+        (call: unknown[]) => call[0] === 'all'
+      )?.[1] as (() => void) | undefined;
+
+      // Trigger change
+      allHandler?.();
+      vi.advanceTimersByTime(800);
+
+      // Trigger another change (should reset timer)
+      allHandler?.();
+      vi.advanceTimersByTime(800);
+
+      // Still no reindex (timer was reset)
+      expect(mockIndexService.indexStore).not.toHaveBeenCalled();
+
+      // Complete the timeout
+      vi.advanceTimersByTime(300);
+      await vi.runAllTimersAsync();
+
+      expect(mockIndexService.indexStore).toHaveBeenCalledTimes(1);
+    });
+
+    it('clears previous timeout on new change', async () => {
+      await watchService.watch(mockFileStore, 1000);
+
+      const watcher = mockWatchers[0];
+      const allHandler = (watcher?.on as ReturnType<typeof vi.fn>).mock.calls.find(
+        (call: unknown[]) => call[0] === 'all'
+      )?.[1] as (() => void) | undefined;
+
+      // Multiple rapid changes
+      for (let i = 0; i < 10; i++) {
+        allHandler?.();
+        vi.advanceTimersByTime(100);
+      }
+
+      await vi.runAllTimersAsync();
+
+      // Should only index once despite 10 changes
+      expect(mockIndexService.indexStore).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('watch - Reindexing', () => {
+    it('initializes lance store before reindexing', async () => {
+      await watchService.watch(mockFileStore);
+
+      const watcher = mockWatchers[0];
+      const allHandler = (watcher?.on as ReturnType<typeof vi.fn>).mock.calls.find(
+        (call: unknown[]) => call[0] === 'all'
+      )?.[1] as (() => void) | undefined;
+
+      allHandler?.();
+      vi.advanceTimersByTime(1100);
+      await vi.runAllTimersAsync();
+
+      expect(mockLanceStore.initialize).toHaveBeenCalledWith(mockFileStore.id);
+      expect(mockLanceStore.initialize).toHaveBeenCalledBefore(
+        mockIndexService.indexStore as ReturnType<typeof vi.fn>
+      );
+    });
+
+    it('calls indexStore with correct store', async () => {
+      await watchService.watch(mockFileStore);
+
+      const watcher = mockWatchers[0];
+      const allHandler = (watcher?.on as ReturnType<typeof vi.fn>).mock.calls.find(
+        (call: unknown[]) => call[0] === 'all'
+      )?.[1] as (() => void) | undefined;
+
+      allHandler?.();
+      vi.advanceTimersByTime(1100);
+      await vi.runAllTimersAsync();
+
+      expect(mockIndexService.indexStore).toHaveBeenCalledWith(mockFileStore);
+    });
+
+    it('calls onReindex callback after successful reindex', async () => {
+      const onReindex = vi.fn();
+
+      await watchService.watch(mockFileStore, 1000, onReindex);
+
+      const watcher = mockWatchers[0];
+      const allHandler = (watcher?.on as ReturnType<typeof vi.fn>).mock.calls.find(
+        (call: unknown[]) => call[0] === 'all'
+      )?.[1] as (() => void) | undefined;
+
+      allHandler?.();
+      vi.advanceTimersByTime(1100);
+      await vi.runAllTimersAsync();
+
+      expect(onReindex).toHaveBeenCalledTimes(1);
+    });
+
+    it('does not call onReindex if not provided', async () => {
+      await watchService.watch(mockFileStore);
+
+      const watcher = mockWatchers[0];
+      const allHandler = (watcher?.on as ReturnType<typeof vi.fn>).mock.calls.find(
+        (call: unknown[]) => call[0] === 'all'
+      )?.[1] as (() => void) | undefined;
+
+      allHandler?.();
+      vi.advanceTimersByTime(1100);
+      await vi.runAllTimersAsync();
+
+      // Should not throw
+      expect(mockIndexService.indexStore).toHaveBeenCalled();
+    });
+
+    it('handles concurrent reindexing for different stores', async () => {
+      await watchService.watch(mockFileStore);
+      await watchService.watch(mockRepoStore);
+
+      const watcher1 = mockWatchers[0];
+      const watcher2 = mockWatchers[1];
+
+      const handler1 = (watcher1?.on as ReturnType<typeof vi.fn>).mock.calls.find(
+        (call: unknown[]) => call[0] === 'all'
+      )?.[1] as (() => void) | undefined;
+
+      const handler2 = (watcher2?.on as ReturnType<typeof vi.fn>).mock.calls.find(
+        (call: unknown[]) => call[0] === 'all'
+      )?.[1] as (() => void) | undefined;
+
+      handler1?.();
+      handler2?.();
+
+      vi.advanceTimersByTime(1100);
+      await vi.runAllTimersAsync();
+
+      expect(mockIndexService.indexStore).toHaveBeenCalledTimes(2);
+      expect(mockIndexService.indexStore).toHaveBeenCalledWith(mockFileStore);
+      expect(mockIndexService.indexStore).toHaveBeenCalledWith(mockRepoStore);
+    });
+  });
+
+  describe('watch - Error Handling', () => {
+    it('logs error when reindexing fails', async () => {
+      const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+      mockIndexService.indexStore = vi.fn().mockRejectedValue(new Error('Index failed'));
+
+      await watchService.watch(mockFileStore);
+
+      const watcher = mockWatchers[0];
+      const allHandler = (watcher?.on as ReturnType<typeof vi.fn>).mock.calls.find(
+        (call: unknown[]) => call[0] === 'all'
+      )?.[1] as (() => void) | undefined;
+
+      allHandler?.();
+      vi.advanceTimersByTime(1100);
+      await vi.runAllTimersAsync();
+
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        'Error during reindexing:',
+        expect.any(Error)
+      );
+
+      consoleErrorSpy.mockRestore();
+    });
+
+    it('logs error when lance initialization fails', async () => {
+      const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+      mockLanceStore.initialize = vi.fn().mockRejectedValue(new Error('Init failed'));
+
+      await watchService.watch(mockFileStore);
+
+      const watcher = mockWatchers[0];
+      const allHandler = (watcher?.on as ReturnType<typeof vi.fn>).mock.calls.find(
+        (call: unknown[]) => call[0] === 'all'
+      )?.[1] as (() => void) | undefined;
+
+      allHandler?.();
+      vi.advanceTimersByTime(1100);
+      await vi.runAllTimersAsync();
+
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        'Error during reindexing:',
+        expect.any(Error)
+      );
+
+      consoleErrorSpy.mockRestore();
+    });
+
+    it('handles watcher errors', async () => {
+      const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+      await watchService.watch(mockFileStore);
+
+      const watcher = mockWatchers[0];
+      const errorHandler = (watcher?.on as ReturnType<typeof vi.fn>).mock.calls.find(
+        (call: unknown[]) => call[0] === 'error'
+      )?.[1] as ((error: Error) => void) | undefined;
+
+      const testError = new Error('Watcher error');
+      errorHandler?.(testError);
+
+      expect(consoleErrorSpy).toHaveBeenCalledWith('Watcher error:', testError);
+
+      consoleErrorSpy.mockRestore();
+    });
+
+    it('continues watching after error during reindex', async () => {
+      const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+      // First call fails
+      mockIndexService.indexStore = vi.fn()
+        .mockRejectedValueOnce(new Error('First fail'))
+        .mockResolvedValueOnce({ ok: true });
+
+      await watchService.watch(mockFileStore);
+
+      const watcher = mockWatchers[0];
+      const allHandler = (watcher?.on as ReturnType<typeof vi.fn>).mock.calls.find(
+        (call: unknown[]) => call[0] === 'all'
+      )?.[1] as (() => void) | undefined;
+
+      // First change - will fail
+      allHandler?.();
+      vi.advanceTimersByTime(1100);
+      await vi.runAllTimersAsync();
+
+      // Second change - should succeed
+      allHandler?.();
+      vi.advanceTimersByTime(1100);
+      await vi.runAllTimersAsync();
+
+      expect(mockIndexService.indexStore).toHaveBeenCalledTimes(2);
+      expect(consoleErrorSpy).toHaveBeenCalledTimes(1);
+
+      consoleErrorSpy.mockRestore();
+    });
+  });
+
+  describe('unwatch', () => {
+    it('stops watching a store', async () => {
+      await watchService.watch(mockFileStore);
+
+      const watcher = mockWatchers[0];
+      await watchService.unwatch(mockFileStore.id);
+
+      expect(watcher?.close).toHaveBeenCalled();
+    });
+
+    it('removes watcher from internal map', async () => {
+      const { watch } = await import('chokidar');
+
+      await watchService.watch(mockFileStore);
+      await watchService.unwatch(mockFileStore.id);
+
+      // Trying to watch again should create new watcher
+      await watchService.watch(mockFileStore);
+
+      expect(watch).toHaveBeenCalledTimes(2);
+    });
+
+    it('does nothing when unwatching non-existent store', async () => {
+      // Should not throw
+      await expect(watchService.unwatch('non-existent-id')).resolves.toBeUndefined();
+    });
+
+    it('does not affect other watchers', async () => {
+      await watchService.watch(mockFileStore);
+      await watchService.watch(mockRepoStore);
+
+      const watcher1 = mockWatchers[0];
+      const watcher2 = mockWatchers[1];
+
+      await watchService.unwatch(mockFileStore.id);
+
+      expect(watcher1?.close).toHaveBeenCalled();
+      expect(watcher2?.close).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('unwatchAll', () => {
+    it('stops all watchers', async () => {
+      await watchService.watch(mockFileStore);
+      await watchService.watch(mockRepoStore);
+
+      const watcher1 = mockWatchers[0];
+      const watcher2 = mockWatchers[1];
+
+      await watchService.unwatchAll();
+
+      expect(watcher1?.close).toHaveBeenCalled();
+      expect(watcher2?.close).toHaveBeenCalled();
+    });
+
+    it('clears all watchers from map', async () => {
+      const { watch } = await import('chokidar');
+
+      await watchService.watch(mockFileStore);
+      await watchService.watch(mockRepoStore);
+
+      await watchService.unwatchAll();
+
+      // Watching again should create new watchers
+      await watchService.watch(mockFileStore);
+
+      expect(watch).toHaveBeenCalledTimes(3); // 2 initial + 1 after unwatchAll
+    });
+
+    it('does nothing when no watchers exist', async () => {
+      // Should not throw
+      await expect(watchService.unwatchAll()).resolves.toBeUndefined();
+    });
+  });
+
+  describe('File Watching Configuration', () => {
+    it('ignores .git directories', async () => {
+      const { watch } = await import('chokidar');
+
+      await watchService.watch(mockFileStore);
+
+      const config = (watch as ReturnType<typeof vi.fn>).mock.calls[0]?.[1];
+      expect(config.ignored).toBeInstanceOf(RegExp);
+      expect(config.ignored.test('.git')).toBe(true);
+      expect(config.ignored.test('some/path/.git/file')).toBe(true);
+    });
+
+    it('ignores node_modules directories', async () => {
+      const { watch } = await import('chokidar');
+
+      await watchService.watch(mockFileStore);
+
+      const config = (watch as ReturnType<typeof vi.fn>).mock.calls[0]?.[1];
+      expect(config.ignored.test('.node_modules')).toBe(true);
+      expect(config.ignored.test('some/path/.node_modules/pkg')).toBe(true);
+    });
+
+    it('ignores dist and build directories', async () => {
+      const { watch } = await import('chokidar');
+
+      await watchService.watch(mockFileStore);
+
+      const config = (watch as ReturnType<typeof vi.fn>).mock.calls[0]?.[1];
+      expect(config.ignored.test('.dist')).toBe(true);
+      expect(config.ignored.test('.build')).toBe(true);
+    });
+
+    it('sets persistent to true', async () => {
+      const { watch } = await import('chokidar');
+
+      await watchService.watch(mockFileStore);
+
+      const config = (watch as ReturnType<typeof vi.fn>).mock.calls[0]?.[1];
+      expect(config.persistent).toBe(true);
+    });
+
+    it('sets ignoreInitial to true', async () => {
+      const { watch } = await import('chokidar');
+
+      await watchService.watch(mockFileStore);
+
+      const config = (watch as ReturnType<typeof vi.fn>).mock.calls[0]?.[1];
+      expect(config.ignoreInitial).toBe(true);
+    });
+  });
+});

package/src/services/watch.service.ts

@@ -0,0 +1,71 @@
+import { watch, type FSWatcher } from 'chokidar';
+import type { FileStore, RepoStore } from '../types/store.js';
+import type { IndexService } from './index.service.js';
+import type { LanceStore } from '../db/lance.js';
+
+export class WatchService {
+  private readonly watchers: Map<string, FSWatcher> = new Map();
+  private readonly indexService: IndexService;
+  private readonly lanceStore: LanceStore;
+
+  constructor(indexService: IndexService, lanceStore: LanceStore) {
+    this.indexService = indexService;
+    this.lanceStore = lanceStore;
+  }
+
+  async watch(
+    store: FileStore | RepoStore,
+    debounceMs = 1000,
+    onReindex?: () => void
+  ): Promise<void> {
+    if (this.watchers.has(store.id)) {
+      return Promise.resolve(); // Already watching
+    }
+
+    let timeout: NodeJS.Timeout | null = null;
+
+    const watcher = watch(store.path, {
+      ignored: /(^|[/\\])\.(git|node_modules|dist|build)/,
+      persistent: true,
+      ignoreInitial: true,
+    });
+
+    const reindexHandler = (): void => {
+      if (timeout) clearTimeout(timeout);
+      timeout = setTimeout(() => {
+        void (async (): Promise<void> => {
+          try {
+            await this.lanceStore.initialize(store.id);
+            await this.indexService.indexStore(store);
+            onReindex?.();
+          } catch (error) {
+            console.error('Error during reindexing:', error);
+          }
+        })();
+      }, debounceMs);
+    };
+
+    watcher.on('all', reindexHandler);
+
+    watcher.on('error', (error) => {
+      console.error('Watcher error:', error);
+    });
+
+    this.watchers.set(store.id, watcher);
+    return Promise.resolve();
+  }
+
+  async unwatch(storeId: string): Promise<void> {
+    const watcher = this.watchers.get(storeId);
+    if (watcher) {
+      await watcher.close();
+      this.watchers.delete(storeId);
+    }
+  }
+
+  async unwatchAll(): Promise<void> {
+    for (const [id] of this.watchers) {
+      await this.unwatch(id);
+    }
+  }
+}

package/src/types/brands.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect } from 'vitest';
+import { createStoreId, createDocumentId, isStoreId, isDocumentId } from './brands.js';
+
+describe('branded types', () => {
+  describe('StoreId', () => {
+    it('creates a valid store ID', () => {
+      const id = createStoreId('store-123');
+      expect(id).toBe('store-123');
+    });
+
+    it('validates store ID format', () => {
+      expect(isStoreId('valid-store-id')).toBe(true);
+      expect(isStoreId('')).toBe(false);
+      expect(isStoreId('has spaces')).toBe(false);
+    });
+
+    it('throws error for invalid store ID', () => {
+      expect(() => createStoreId('invalid id with spaces')).toThrow('Invalid store ID: invalid id with spaces');
+    });
+
+    it('throws error for empty store ID', () => {
+      expect(() => createStoreId('')).toThrow('Invalid store ID: ');
+    });
+  });
+
+  describe('DocumentId', () => {
+    it('creates a valid document ID', () => {
+      const id = createDocumentId('doc-456');
+      expect(id).toBe('doc-456');
+    });
+
+    it('validates document ID format', () => {
+      expect(isDocumentId('valid-doc-id')).toBe(true);
+      expect(isDocumentId('')).toBe(false);
+    });
+
+    it('throws error for invalid document ID', () => {
+      expect(() => createDocumentId('invalid@id')).toThrow('Invalid document ID: invalid@id');
+    });
+
+    it('throws error for empty document ID', () => {
+      expect(() => createDocumentId('')).toThrow('Invalid document ID: ');
+    });
+  });
+});

package/src/types/brands.ts

@@ -0,0 +1,32 @@
+// Branded type symbols
+declare const StoreIdBrand: unique symbol;
+declare const DocumentIdBrand: unique symbol;
+
+// Branded types
+export type StoreId = string & { readonly [StoreIdBrand]: typeof StoreIdBrand };
+export type DocumentId = string & { readonly [DocumentIdBrand]: typeof DocumentIdBrand };
+
+// Valid ID pattern: alphanumeric, hyphens, underscores
+const ID_PATTERN = /^[a-zA-Z0-9_-]+$/;
+
+export function isStoreId(value: string): value is StoreId {
+  return value.length > 0 && ID_PATTERN.test(value);
+}
+
+export function isDocumentId(value: string): value is DocumentId {
+  return value.length > 0 && ID_PATTERN.test(value);
+}
+
+export function createStoreId(value: string): StoreId {
+  if (!isStoreId(value)) {
+    throw new Error(`Invalid store ID: ${value}`);
+  }
+  return value;
+}
+
+export function createDocumentId(value: string): DocumentId {
+  if (!isDocumentId(value)) {
+    throw new Error(`Invalid document ID: ${value}`);
+  }
+  return value;
+}