codecritique 1.0.0

package/src/embeddings/errors.js

@@ -0,0 +1,208 @@
+/**
+ * Embeddings Error Handling
+ *
+ * This module provides standardized error handling for the embeddings system.
+ * It includes custom error classes and error codes for different failure scenarios.
+ */
+
+/**
+ * Error codes for different embedding failure scenarios
+ */
+export const ERROR_CODES = {
+  // Model initialization errors
+  MODEL_INITIALIZATION_FAILED: 'MODEL_INITIALIZATION_FAILED',
+  MODEL_NOT_INITIALIZED: 'MODEL_NOT_INITIALIZED',
+  MODEL_LOADING_FAILED: 'MODEL_LOADING_FAILED',
+
+  // Database errors
+  DB_CONNECTION_FAILED: 'DB_CONNECTION_FAILED',
+  DB_QUERY_FAILED: 'DB_QUERY_FAILED',
+  DB_INSERTION_FAILED: 'DB_INSERTION_FAILED',
+  DB_TABLE_CREATION_FAILED: 'DB_TABLE_CREATION_FAILED',
+  DB_SCHEMA_VALIDATION_FAILED: 'DB_SCHEMA_VALIDATION_FAILED',
+
+  // Embedding generation errors
+  EMBEDDING_GENERATION_FAILED: 'EMBEDDING_GENERATION_FAILED',
+  EMBEDDING_DIMENSION_MISMATCH: 'EMBEDDING_DIMENSION_MISMATCH',
+  EMBEDDING_INVALID_INPUT: 'EMBEDDING_INVALID_INPUT',
+  EMBEDDING_TIMEOUT: 'EMBEDDING_TIMEOUT',
+
+  // File processing errors
+  FILE_NOT_FOUND: 'FILE_NOT_FOUND',
+  FILE_READ_FAILED: 'FILE_READ_FAILED',
+  FILE_TOO_LARGE: 'FILE_TOO_LARGE',
+  FILE_INVALID_FORMAT: 'FILE_INVALID_FORMAT',
+  FILE_PROCESSING_FAILED: 'FILE_PROCESSING_FAILED',
+
+  // Search and similarity errors
+  SEARCH_FAILED: 'SEARCH_FAILED',
+  SIMILARITY_CALCULATION_FAILED: 'SIMILARITY_CALCULATION_FAILED',
+  INVALID_SEARCH_QUERY: 'INVALID_SEARCH_QUERY',
+  SEARCH_TIMEOUT: 'SEARCH_TIMEOUT',
+
+  // Cache errors
+  CACHE_WRITE_FAILED: 'CACHE_WRITE_FAILED',
+  CACHE_READ_FAILED: 'CACHE_READ_FAILED',
+  CACHE_INVALIDATION_FAILED: 'CACHE_INVALIDATION_FAILED',
+
+  // Configuration errors
+  CONFIG_VALIDATION_FAILED: 'CONFIG_VALIDATION_FAILED',
+  CONFIG_MISSING_REQUIRED: 'CONFIG_MISSING_REQUIRED',
+  CONFIG_INVALID_VALUE: 'CONFIG_INVALID_VALUE',
+
+  // Network and external service errors
+  NETWORK_ERROR: 'NETWORK_ERROR',
+  SERVICE_UNAVAILABLE: 'SERVICE_UNAVAILABLE',
+  API_RATE_LIMITED: 'API_RATE_LIMITED',
+
+  // Generic errors
+  UNKNOWN_ERROR: 'UNKNOWN_ERROR',
+  VALIDATION_ERROR: 'VALIDATION_ERROR',
+  TIMEOUT_ERROR: 'TIMEOUT_ERROR',
+  MEMORY_ERROR: 'MEMORY_ERROR',
+};
+
+/**
+ * Custom error class for embeddings-related errors
+ */
+export class EmbeddingError extends Error {
+  /**
+   * Create a new EmbeddingError
+   *
+   * @param {string} message - Error message
+   * @param {string} code - Error code from ERROR_CODES
+   * @param {Error} [originalError] - Original error that caused this error
+   * @param {Object} [context] - Additional context information
+   */
+  constructor(message, code = ERROR_CODES.UNKNOWN_ERROR, originalError = null, context = {}) {
+    super(message);
+
+    this.name = 'EmbeddingError';
+    this.code = code;
+    this.originalError = originalError;
+    this.context = context;
+    this.timestamp = new Date().toISOString();
+
+    // Maintain proper stack trace for where our error was thrown (only available on V8)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, EmbeddingError);
+    }
+  }
+
+  /**
+   * Convert error to JSON for logging
+   *
+   * @returns {Object} JSON representation of the error
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      timestamp: this.timestamp,
+      context: this.context,
+      stack: this.stack,
+      originalError: this.originalError
+        ? {
+            name: this.originalError.name,
+            message: this.originalError.message,
+            stack: this.originalError.stack,
+          }
+        : null,
+    };
+  }
+
+  /**
+   * Check if this error is of a specific type
+   *
+   * @param {string} code - Error code to check
+   * @returns {boolean} True if the error matches the code
+   */
+  is(code) {
+    return this.code === code;
+  }
+
+  /**
+   * Check if this error is retryable
+   *
+   * @returns {boolean} True if the error is retryable
+   */
+  isRetryable() {
+    const retryableCodes = [
+      ERROR_CODES.NETWORK_ERROR,
+      ERROR_CODES.SERVICE_UNAVAILABLE,
+      ERROR_CODES.EMBEDDING_TIMEOUT,
+      ERROR_CODES.SEARCH_TIMEOUT,
+      ERROR_CODES.DB_CONNECTION_FAILED,
+      ERROR_CODES.CACHE_WRITE_FAILED,
+      ERROR_CODES.CACHE_READ_FAILED,
+    ];
+
+    return retryableCodes.includes(this.code);
+  }
+}
+
+/**
+ * Custom error class for validation errors
+ */
+export class ValidationError extends EmbeddingError {
+  /**
+   * Create a new ValidationError
+   *
+   * @param {string} message - Error message
+   * @param {Error} [originalError] - Original error that caused this error
+   * @param {Object} [context] - Additional context information
+   */
+  constructor(message, originalError = null, context = {}) {
+    super(message, ERROR_CODES.VALIDATION_ERROR, originalError, context);
+    this.name = 'ValidationError';
+  }
+}
+
+/**
+ * Create a specific error for model initialization failures
+ *
+ * @param {string} message - Error message
+ * @param {Error} [originalError] - Original error
+ * @param {Object} [context] - Additional context
+ * @returns {EmbeddingError} New EmbeddingError instance
+ */
+export function createModelInitializationError(message, originalError = null, context = {}) {
+  return new EmbeddingError(message, ERROR_CODES.MODEL_INITIALIZATION_FAILED, originalError, context);
+}
+
+/**
+ * Create a specific error for database failures
+ *
+ * @param {string} message - Error message
+ * @param {Error} [originalError] - Original error
+ * @param {Object} [context] - Additional context
+ * @returns {EmbeddingError} New EmbeddingError instance
+ */
+export function createDatabaseError(message, originalError = null, context = {}) {
+  return new EmbeddingError(message, ERROR_CODES.DB_QUERY_FAILED, originalError, context);
+}
+
+/**
+ * Create a specific error for embedding generation failures
+ *
+ * @param {string} message - Error message
+ * @param {Error} [originalError] - Original error
+ * @param {Object} [context] - Additional context
+ * @returns {EmbeddingError} New EmbeddingError instance
+ */
+export function createEmbeddingGenerationError(message, originalError = null, context = {}) {
+  return new EmbeddingError(message, ERROR_CODES.EMBEDDING_GENERATION_FAILED, originalError, context);
+}
+
+/**
+ * Create a specific error for file processing failures
+ *
+ * @param {string} message - Error message
+ * @param {Error} [originalError] - Original error
+ * @param {Object} [context] - Additional context
+ * @returns {EmbeddingError} New EmbeddingError instance
+ */
+export function createFileProcessingError(message, originalError = null, context = {}) {
+  return new EmbeddingError(message, ERROR_CODES.FILE_PROCESSING_FAILED, originalError, context);
+}

package/src/embeddings/factory.js

@@ -0,0 +1,447 @@
+/**
+ * Embeddings System Factory
+ *
+ * This module provides a factory pattern for creating and wiring together
+ * all components of the embeddings system. It implements dependency injection
+ * and provides both singleton and instance-based usage patterns.
+ *
+ * Features:
+ * - Dependency injection for all modules
+ * - System-wide initialization and cleanup
+ * - Configuration management
+ * - Environment setup
+ * - Module lifecycle management
+ */
+
+/**
+ * @typedef {import('./types.js').EmbeddingConfig} EmbeddingConfig
+ * @typedef {import('./types.js').SearchOptions} SearchOptions
+ * @typedef {import('./types.js').SearchResult} SearchResult
+ * @typedef {import('./types.js').ProcessingProgress} ProcessingProgress
+ */
+
+import chalk from 'chalk';
+import { ContentRetriever } from '../content-retrieval.js';
+import { CustomDocumentProcessor } from '../custom-documents.js';
+import { CacheManager } from './cache-manager.js';
+import { EMBEDDING_DIMENSIONS, MODEL_NAME_STRING, MAX_RETRIES, LANCEDB_PATH, FASTEMBED_CACHE_DIR } from './constants.js';
+import { DatabaseManager } from './database.js';
+import { EmbeddingError } from './errors.js';
+import { FileProcessor } from './file-processor.js';
+import { ModelManager } from './model-manager.js';
+
+// ============================================================================
+// EMBEDDINGS SYSTEM CLASS
+// ============================================================================
+
+/**
+ * EmbeddingsSystem class that encapsulates all embedding functionality
+ * with proper dependency injection and lifecycle management
+ */
+class EmbeddingsSystem {
+  constructor(options = {}) {
+    this.options = options;
+    this.initialized = false;
+    this.initializing = false;
+    this.initializationPromise = null;
+    this.cleaningUp = false;
+
+    // Initialize core components with dependency injection
+    this.cacheManager =
+      options.cacheManager ||
+      new CacheManager({
+        maxCacheSize: options.maxCacheSize || 1000,
+        maxEmbeddingCacheSize: options.maxEmbeddingCacheSize || 1000,
+      });
+
+    this.databaseManager =
+      options.databaseManager ||
+      new DatabaseManager({
+        dbPath: options.dbPath || LANCEDB_PATH,
+        embeddingDimensions: options.embeddingDimensions || EMBEDDING_DIMENSIONS,
+      });
+
+    this.modelManager =
+      options.modelManager ||
+      new ModelManager({
+        embeddingDimensions: options.embeddingDimensions || EMBEDDING_DIMENSIONS,
+        modelNameString: options.modelNameString || MODEL_NAME_STRING,
+        maxRetries: options.maxRetries || MAX_RETRIES,
+        cacheDir: options.cacheDir || FASTEMBED_CACHE_DIR,
+        cacheManager: this.cacheManager,
+      });
+
+    this.fileProcessor =
+      options.fileProcessor ||
+      new FileProcessor({
+        modelManager: this.modelManager,
+        databaseManager: this.databaseManager,
+        cacheManager: this.cacheManager,
+      });
+
+    this.contentRetriever =
+      options.contentRetriever ||
+      new ContentRetriever({
+        modelManager: this.modelManager,
+        database: this.databaseManager,
+        cacheManager: this.cacheManager,
+      });
+
+    this.customDocumentProcessor =
+      options.customDocumentProcessor ||
+      new CustomDocumentProcessor({
+        modelManager: this.modelManager,
+        cacheManager: this.cacheManager,
+      });
+
+    // Track initialization status
+    this.components = {
+      cacheManager: this.cacheManager,
+      databaseManager: this.databaseManager,
+      modelManager: this.modelManager,
+      fileProcessor: this.fileProcessor,
+      contentRetriever: this.contentRetriever,
+      customDocumentProcessor: this.customDocumentProcessor,
+    };
+
+    console.log(chalk.green('[EmbeddingsSystem] System created with dependency injection'));
+  }
+
+  // ============================================================================
+  // INITIALIZATION
+  // ============================================================================
+
+  /**
+   * Initialize the embeddings system
+   * @returns {Promise<void>}
+   */
+  async initialize() {
+    if (this.initialized) {
+      return;
+    }
+
+    if (this.initializing) {
+      return this.initializationPromise;
+    }
+
+    this.initializing = true;
+    this.initializationPromise = this._performInitialization();
+
+    try {
+      await this.initializationPromise;
+      this.initialized = true;
+      this.initializing = false;
+      console.log(chalk.green('[EmbeddingsSystem] System initialized successfully'));
+    } catch (error) {
+      this.initializing = false;
+      this.initializationPromise = null;
+      throw error;
+    }
+  }
+
+  /**
+   * Perform the actual initialization
+   * @private
+   */
+  async _performInitialization() {
+    console.log(chalk.blue('[EmbeddingsSystem] Initializing embeddings system...'));
+
+    try {
+      // Initialize database and tables
+      await this.databaseManager.initializeTables();
+
+      // Initialize the model
+      await this.modelManager.initialize();
+
+      console.log(chalk.green('[EmbeddingsSystem] All components initialized successfully'));
+    } catch (error) {
+      console.error(chalk.red(`[EmbeddingsSystem] Initialization failed: ${error.message}`));
+      throw new EmbeddingError(`System initialization failed: ${error.message}`, 'SYSTEM_INITIALIZATION_FAILED', error);
+    }
+  }
+
+  /**
+   * Check if the system is initialized
+   * @returns {boolean}
+   */
+  isInitialized() {
+    return this.initialized;
+  }
+
+  // ============================================================================
+  // PUBLIC API METHODS
+  // ============================================================================
+
+  /**
+   * Calculate embedding for text
+   * @param {string} text - Text to embed
+   * @returns {Promise<import('./types.js').EmbeddingVector|null>}
+   */
+  async calculateEmbedding(text) {
+    await this.initialize();
+    return this.modelManager.calculateEmbedding(text);
+  }
+
+  /**
+   * Calculate query embedding for text
+   * @param {string} text - Query text to embed
+   * @returns {Promise<import('./types.js').EmbeddingVector|null>}
+   */
+  async calculateQueryEmbedding(text) {
+    await this.initialize();
+    return this.modelManager.calculateQueryEmbedding(text);
+  }
+
+  /**
+   * Find relevant documentation
+   * @param {string} queryText - Query text
+   * @param {SearchOptions} options - Search options
+   * @returns {Promise<SearchResult[]>}
+   */
+  async findRelevantDocs(queryText, options = {}) {
+    await this.initialize();
+    return this.contentRetriever.findRelevantDocs(queryText, options);
+  }
+
+  /**
+   * Find similar code
+   * @param {string} queryText - Query text
+   * @param {SearchOptions} options - Search options
+   * @returns {Promise<SearchResult[]>}
+   */
+  async findSimilarCode(queryText, options = {}) {
+    await this.initialize();
+    return this.contentRetriever.findSimilarCode(queryText, options);
+  }
+
+  /**
+   * Process custom documents in memory
+   * @param {import('./types.js').CustomDocument[]} customDocs - Array of custom documents
+   * @param {string} projectPath - Project path
+   * @returns {Promise<import('./types.js').DocumentChunk[]>}
+   */
+  async processCustomDocumentsInMemory(customDocs, projectPath) {
+    await this.initialize();
+    return this.customDocumentProcessor.processDocumentsInMemory(customDocs, projectPath);
+  }
+
+  /**
+   * Find relevant custom document chunks
+   * @param {string} queryText - Query text
+   * @param {import('./types.js').DocumentChunk[]} chunks - Document chunks
+   * @param {SearchOptions} options - Search options
+   * @returns {Promise<SearchResult[]>}
+   */
+  async findRelevantCustomDocChunks(queryText, chunks = [], options = {}) {
+    await this.initialize();
+    return this.customDocumentProcessor.findRelevantChunks(queryText, chunks, options);
+  }
+
+  /**
+   * Get existing custom document chunks
+   * @param {string} projectPath - Project path
+   * @returns {Promise<import('./types.js').DocumentChunk[]>}
+   */
+  async getExistingCustomDocumentChunks(projectPath) {
+    await this.initialize();
+    return this.customDocumentProcessor.getExistingChunks(projectPath);
+  }
+
+  /**
+   * Process batch embeddings
+   * @param {string[]} filePaths - Array of file paths
+   * @param {import('./types.js').BatchProcessingOptions} options - Processing options
+   * @returns {Promise<ProcessingProgress>}
+   */
+  async processBatchEmbeddings(filePaths, options = {}) {
+    await this.initialize();
+    return this.fileProcessor.processBatchEmbeddings(filePaths, options);
+  }
+
+  /**
+   * Get project embeddings (compatibility method)
+   * @param {string} projectPath - Project path
+   * @returns {Object}
+   */
+  getProjectEmbeddings(projectPath = process.cwd()) {
+    // This is a sync method that returns cached data
+    return {
+      system: this,
+      projectPath,
+      components: this.components,
+      initialized: this.initialized,
+      config: this.config,
+    };
+  }
+
+  /**
+   * Clear embeddings for a project
+   * For deletion operations, we only need database connection - no need for
+   * full system initialization (models, indexes, etc.)
+   * @param {string} projectPath - Project path
+   * @returns {Promise<boolean>}
+   */
+  async clearEmbeddings(projectPath = process.cwd()) {
+    await this.databaseManager.getDBConnection();
+    return this.databaseManager.clearProjectEmbeddings(projectPath);
+  }
+
+  /**
+   * Clear all embeddings
+   * @returns {Promise<boolean>}
+   */
+  async clearAllEmbeddings() {
+    // Only ensure database connection exists, skip full initialization
+    await this.databaseManager.getDBConnection();
+    return this.databaseManager.clearAllEmbeddings();
+  }
+
+  /**
+   * Store project summary for later retrieval during reviews
+   * @param {string} projectPath - Project path
+   * @param {Object} projectSummary - Project analysis summary
+   * @returns {Promise<boolean>}
+   */
+  async storeProjectSummary(projectPath, projectSummary) {
+    await this.databaseManager.getDBConnection();
+    return this.databaseManager.storeProjectSummary(projectPath, projectSummary);
+  }
+
+  /**
+   * Get stored project summary
+   * @param {string} projectPath - Project path
+   * @returns {Promise<Object|null>}
+   */
+  async getProjectSummary(projectPath) {
+    await this.databaseManager.getDBConnection();
+    return this.databaseManager.getProjectSummary(projectPath);
+  }
+
+  // ============================================================================
+  // PR COMMENTS TABLE METHODS
+  // ============================================================================
+
+  /**
+   * Get PR comments table
+   * @returns {Promise<import('@lancedb/lancedb').Table|null>} PR comments table or null on error
+   */
+  async getPRCommentsTable() {
+    await this.initialize();
+    return this.databaseManager.getTable(this.databaseManager.prCommentsTable);
+  }
+
+  /**
+   * Update the vector index for the PR comments table
+   * @returns {Promise<void>}
+   */
+  async updatePRCommentsIndex() {
+    await this.initialize();
+    return this.databaseManager.updatePRCommentsIndex();
+  }
+
+  // ============================================================================
+  // UTILITY METHODS
+  // ============================================================================
+
+  /**
+   * Get system metrics
+   * @returns {Object}
+   */
+  getSystemMetrics() {
+    return {
+      initialized: this.initialized,
+      initializing: this.initializing,
+      config: this.config,
+      cacheMetrics: this.cacheManager.getCacheMetrics(),
+      contentRetrieverMetrics: this.contentRetriever.getPerformanceMetrics(),
+      customDocumentMetrics: this.customDocumentProcessor.getPerformanceMetrics(),
+    };
+  }
+
+  /**
+   * Get system status
+   * @returns {Object}
+   */
+  getSystemStatus() {
+    return {
+      initialized: this.initialized,
+      initializing: this.initializing,
+      modelReady: this.modelManager.isInitialized(),
+      databaseReady: this.databaseManager.tablesInitialized,
+      cacheStatus: this.cacheManager.getCacheStatus(),
+    };
+  }
+
+  // ============================================================================
+  // CLEANUP
+  // ============================================================================
+
+  /**
+   * Cleanup system resources
+   * @returns {Promise<void>}
+   */
+  async cleanup() {
+    if (this.cleaningUp) {
+      return; // Already cleaning up, prevent duplicate calls
+    }
+
+    this.cleaningUp = true;
+
+    try {
+      console.log(chalk.yellow('[EmbeddingsSystem] Cleaning up system resources...'));
+
+      // Cleanup all components
+      await Promise.all([
+        this.modelManager.cleanup(),
+        this.databaseManager.cleanup(),
+        this.fileProcessor.cleanup(),
+        this.contentRetriever.cleanup(),
+        this.customDocumentProcessor.cleanup(),
+        this.cacheManager.cleanup(),
+      ]);
+
+      // Reset state
+      this.initialized = false;
+      this.initializing = false;
+      this.initializationPromise = null;
+
+      console.log(chalk.green('[EmbeddingsSystem] System cleanup completed'));
+    } catch (error) {
+      console.error(chalk.red(`[EmbeddingsSystem] Error during cleanup: ${error.message}`));
+      throw error;
+    } finally {
+      this.cleaningUp = false;
+    }
+  }
+}
+
+// ============================================================================
+// FACTORY FUNCTIONS
+// ============================================================================
+
+/**
+ * Create a new EmbeddingsSystem instance
+ * @param {EmbeddingConfig} options - Configuration options
+ * @returns {EmbeddingsSystem}
+ */
+function createEmbeddingsSystem(options = {}) {
+  return new EmbeddingsSystem(options);
+}
+
+// ============================================================================
+// SINGLETON INSTANCE
+// ============================================================================
+
+// Create a default singleton instance for backward compatibility
+let defaultSystem = null;
+
+/**
+ * Get the default singleton EmbeddingsSystem instance
+ * @returns {EmbeddingsSystem}
+ */
+export function getDefaultEmbeddingsSystem() {
+  if (!defaultSystem) {
+    defaultSystem = createEmbeddingsSystem();
+  }
+  return defaultSystem;
+}