vibecodingmachine-core 2025.12.25-25 → 2026.1.22-1441

package/src/health-tracking/ide-health-tracker.js

@@ -0,0 +1,446 @@
+/**
+ * IDE Health Tracker
+ *
+ * Main class for tracking IDE reliability metrics.
+ * Tracks success/failure counters, response times, and EWMA calculations.
+ *
+ * @module ide-health-tracker
+ */
+
+const EventEmitter = require('events');
+const { JSONStorage } = require('./json-storage');
+const { InteractionRecorder } = require('./interaction-recorder');
+const { ValidationError } = require('./errors');
+const { validateIdeId, validateResponseTime } = require('./validators');
+
+/**
+ * Maximum number of response times to keep per IDE
+ */
+const MAX_RESPONSE_TIMES = 50;
+
+/**
+ * Consecutive failure threshold for emitting warning
+ */
+const CONSECUTIVE_FAILURE_THRESHOLD = 5;
+
+/**
+ * Default EWMA alpha value
+ */
+const DEFAULT_EWMA_ALPHA = 0.3;
+
+/**
+ * Tracks IDE health metrics including success/failure counts and response times
+ * @extends EventEmitter
+ */
+class IDEHealthTracker extends EventEmitter {
+  /**
+   * @param {Object} options - Configuration options
+   * @param {string} [options.storageFile] - Path to storage file
+   * @param {boolean} [options.autoSave=true] - Automatically save after updates
+   * @param {number} [options.debounceMs=500] - Debounce time for auto-save
+   */
+  constructor(options = {}) {
+    super();
+
+    this.storage = new JSONStorage({
+      storageFile: options.storageFile,
+    });
+
+    this.recorder = new InteractionRecorder(this.storage);
+
+    this.autoSave = options.autoSave !== undefined ? options.autoSave : true;
+    this.debounceMs = options.debounceMs || 500;
+    this.saveTimeout = null;
+  }
+
+  /**
+   * Record a successful IDE interaction
+   * @param {string} ideId - IDE identifier
+   * @param {number} responseTime - Response time in milliseconds
+   * @param {Object} [metadata] - Additional metadata
+   * @param {number} [metadata.continuationPromptsDetected=0] - Number of prompts handled
+   * @param {string} [metadata.requirementId] - Associated requirement ID
+   * @param {Date} [metadata.timestamp] - Override timestamp
+   * @returns {Promise<void>}
+   * @throws {ValidationError} If validation fails
+   */
+  async recordSuccess(ideId, responseTime, metadata = {}) {
+    // Validate inputs
+    validateIdeId(ideId);
+    validateResponseTime(responseTime);
+
+    // Read current data
+    const data = await this.storage.read();
+
+    // Initialize IDE record if needed
+    if (!data.ides[ideId]) {
+      data.ides[ideId] = this._createDefaultIDERecord();
+    }
+
+    const ideRecord = data.ides[ideId];
+
+    // Increment success count
+    ideRecord.successCount++;
+
+    // Reset consecutive failures
+    ideRecord.consecutiveFailures = 0;
+
+    // Update lastSuccess
+    ideRecord.lastSuccess = (metadata.timestamp || new Date()).toISOString();
+
+    // Add response time to array
+    ideRecord.responseTimes.push(responseTime);
+
+    // Enforce max response times
+    if (ideRecord.responseTimes.length > MAX_RESPONSE_TIMES) {
+      ideRecord.responseTimes = ideRecord.responseTimes.slice(-MAX_RESPONSE_TIMES);
+    }
+
+    // Recalculate EWMA
+    ideRecord.ewma = this._calculateEWMA(ideRecord.responseTimes);
+
+    // Update current timeout based on EWMA and config
+    ideRecord.currentTimeout = await this._calculateTimeout(ideRecord, data.timeoutConfig);
+
+    // Write updated data
+    await this.storage.write(data);
+
+    // Record interaction
+    await this.recorder.record({
+      ideId,
+      timestamp: metadata.timestamp || new Date(),
+      outcome: 'success',
+      responseTime,
+      timeoutUsed: ideRecord.currentTimeout,
+      continuationPromptsDetected: metadata.continuationPromptsDetected || 0,
+      requirementId: metadata.requirementId || null,
+      errorMessage: null,
+    });
+
+    // Emit event
+    this.emit('health-updated', { ideId, outcome: 'success' });
+
+    // Trigger debounced save if auto-save enabled
+    if (this.autoSave) {
+      this._debouncedSave();
+    }
+  }
+
+  /**
+   * Record a failed IDE interaction
+   * @param {string} ideId - IDE identifier
+   * @param {string} [errorMessage] - Error description
+   * @param {Object} [metadata] - Additional metadata
+   * @param {number} [metadata.timeoutUsed] - Timeout that expired
+   * @param {string} [metadata.requirementId] - Associated requirement ID
+   * @param {Date} [metadata.timestamp] - Override timestamp
+   * @returns {Promise<void>}
+   * @throws {ValidationError} If validation fails
+   */
+  async recordFailure(ideId, errorMessage, metadata = {}) {
+    // Validate inputs
+    validateIdeId(ideId);
+
+    // Read current data
+    const data = await this.storage.read();
+
+    // Initialize IDE record if needed
+    if (!data.ides[ideId]) {
+      data.ides[ideId] = this._createDefaultIDERecord();
+    }
+
+    const ideRecord = data.ides[ideId];
+
+    // Increment failure count
+    ideRecord.failureCount++;
+
+    // Increment consecutive failures
+    ideRecord.consecutiveFailures++;
+
+    // Update lastFailure
+    ideRecord.lastFailure = (metadata.timestamp || new Date()).toISOString();
+
+    // Write updated data
+    await this.storage.write(data);
+
+    // Record interaction
+    await this.recorder.record({
+      ideId,
+      timestamp: metadata.timestamp || new Date(),
+      outcome: 'failure',
+      responseTime: null,
+      timeoutUsed: metadata.timeoutUsed || ideRecord.currentTimeout,
+      continuationPromptsDetected: 0,
+      requirementId: metadata.requirementId || null,
+      errorMessage: errorMessage || 'Unknown error',
+    });
+
+    // Emit event
+    this.emit('health-updated', { ideId, outcome: 'failure' });
+
+    // Emit consecutive-failures event if threshold reached
+    if (ideRecord.consecutiveFailures === CONSECUTIVE_FAILURE_THRESHOLD) {
+      this.emit('consecutive-failures', {
+        ideId,
+        count: ideRecord.consecutiveFailures,
+        lastError: errorMessage || 'Unknown error',
+      });
+    }
+
+    // Trigger debounced save if auto-save enabled
+    if (this.autoSave) {
+      this._debouncedSave();
+    }
+  }
+
+  /**
+   * Record a quota limit event (does NOT increment success/failure counters)
+   * @param {string} ideId - IDE identifier
+   * @param {string} quotaMessage - Quota message from IDE
+   * @param {Object} [metadata] - Additional metadata
+   * @param {string} [metadata.requirementId] - Associated requirement ID
+   * @param {Date} [metadata.timestamp] - Override timestamp
+   * @returns {Promise<void>}
+   * @throws {ValidationError} If validation fails
+   */
+  async recordQuota(ideId, quotaMessage, metadata = {}) {
+    // Validate inputs
+    validateIdeId(ideId);
+
+    // Read current data
+    const data = await this.storage.read();
+
+    // Initialize IDE record if needed
+    if (!data.ides[ideId]) {
+      data.ides[ideId] = this._createDefaultIDERecord();
+    }
+
+    const ideRecord = data.ides[ideId];
+
+    // Record interaction (no counter updates per FR-008)
+    await this.recorder.record({
+      ideId,
+      timestamp: metadata.timestamp || new Date(),
+      outcome: 'quota',
+      responseTime: null,
+      timeoutUsed: ideRecord.currentTimeout,
+      continuationPromptsDetected: 0,
+      requirementId: metadata.requirementId || null,
+      errorMessage: quotaMessage,
+    });
+
+    // Emit event
+    this.emit('health-updated', { ideId, outcome: 'quota' });
+
+    // Trigger debounced save if auto-save enabled
+    if (this.autoSave) {
+      this._debouncedSave();
+    }
+  }
+
+  /**
+   * Get health metrics for a specific IDE
+   * @param {string} ideId - IDE identifier
+   * @returns {Promise<Object>} Health metrics object
+   */
+  async getHealthMetrics(ideId) {
+    const data = await this.storage.read();
+    const ideRecord = data.ides[ideId];
+
+    if (!ideRecord) {
+      // Return default metrics for unknown IDE
+      return {
+        successCount: 0,
+        failureCount: 0,
+        successRate: 0,
+        averageResponseTime: 0,
+        currentTimeout: 1800000,
+        consecutiveFailures: 0,
+        lastSuccess: null,
+        lastFailure: null,
+        totalInteractions: 0,
+        recentInteractions: [],
+      };
+    }
+
+    const totalInteractions = ideRecord.successCount + ideRecord.failureCount;
+    const successRate = totalInteractions > 0
+      ? ideRecord.successCount / totalInteractions
+      : 0;
+
+    // Get recent 10 interactions
+    const recentInteractions = await this.recorder.getInteractions(ideId, 10);
+
+    return {
+      successCount: ideRecord.successCount,
+      failureCount: ideRecord.failureCount,
+      successRate,
+      averageResponseTime: ideRecord.ewma,
+      currentTimeout: ideRecord.currentTimeout,
+      consecutiveFailures: ideRecord.consecutiveFailures,
+      lastSuccess: ideRecord.lastSuccess,
+      lastFailure: ideRecord.lastFailure,
+      totalInteractions,
+      recentInteractions,
+    };
+  }
+
+  /**
+   * Get health metrics for all tracked IDEs
+   * @returns {Promise<Map<string, Object>>} Map of IDE ID to health metrics
+   */
+  async getAllHealthMetrics() {
+    const data = await this.storage.read();
+    const metricsMap = new Map();
+
+    for (const ideId of Object.keys(data.ides)) {
+      const metrics = await this.getHealthMetrics(ideId);
+      metricsMap.set(ideId, metrics);
+    }
+
+    return metricsMap;
+  }
+
+  /**
+   * Get recommended IDE based on health metrics
+   * @param {Object} [options] - Options
+   * @param {number} [options.minInteractions=10] - Minimum total interactions to consider
+   * @param {boolean} [options.weightRecent=true] - Weight recent interactions more heavily
+   * @returns {Promise<string|null>} IDE identifier with highest success rate, or null
+   */
+  async getRecommendedIDE(options = {}) {
+    const minInteractions = options.minInteractions || 10;
+    const allMetrics = await this.getAllHealthMetrics();
+
+    let bestIDE = null;
+    let bestSuccessRate = 0;
+
+    for (const [ideId, metrics] of allMetrics) {
+      if (metrics.totalInteractions >= minInteractions) {
+        if (metrics.successRate > bestSuccessRate) {
+          bestSuccessRate = metrics.successRate;
+          bestIDE = ideId;
+        }
+      }
+    }
+
+    return bestIDE;
+  }
+
+  /**
+   * Manually trigger save operation
+   * @returns {Promise<void>}
+   * @throws {FileSystemError} If write fails
+   */
+  async save() {
+    // Cancel any pending debounced save
+    if (this.saveTimeout) {
+      clearTimeout(this.saveTimeout);
+      this.saveTimeout = null;
+    }
+
+    // Note: Data is already written in record methods,
+    // this is mainly for explicit save requests
+    const data = await this.storage.read();
+    await this.storage.write(data);
+  }
+
+  /**
+   * Reload health data from storage file
+   * @returns {Promise<void>}
+   * @throws {FileSystemError} If read fails
+   * @throws {ValidationError} If data is corrupted
+   */
+  async load() {
+    // Simply reading from storage will load and validate the data
+    await this.storage.read();
+  }
+
+  /**
+   * Create default IDE record
+   * @private
+   * @returns {Object} Default IDE record
+   */
+  _createDefaultIDERecord() {
+    return {
+      successCount: 0,
+      failureCount: 0,
+      responseTimes: [],
+      ewma: 0,
+      lastSuccess: null,
+      lastFailure: null,
+      consecutiveFailures: 0,
+      currentTimeout: 1800000, // 30 minutes
+      interactions: [],
+    };
+  }
+
+  /**
+   * Calculate EWMA from response times
+   * @private
+   * @param {number[]} responseTimes - Array of response times
+   * @param {number} [alpha] - EWMA alpha parameter
+   * @returns {number} EWMA value
+   */
+  _calculateEWMA(responseTimes, alpha = DEFAULT_EWMA_ALPHA) {
+    if (!responseTimes || responseTimes.length === 0) {
+      return 0;
+    }
+
+    let ewma = responseTimes[0];
+    for (let i = 1; i < responseTimes.length; i++) {
+      ewma = alpha * responseTimes[i] + (1 - alpha) * ewma;
+    }
+
+    return ewma;
+  }
+
+  /**
+   * Calculate timeout for IDE based on EWMA and config
+   * @private
+   * @param {Object} ideRecord - IDE health record
+   * @param {Object} timeoutConfig - Timeout configuration
+   * @returns {Promise<number>} Calculated timeout in milliseconds
+   */
+  async _calculateTimeout(ideRecord, timeoutConfig) {
+    if (!timeoutConfig || timeoutConfig.mode === 'fixed') {
+      return timeoutConfig?.defaultTimeout || 1800000;
+    }
+
+    // Adaptive mode
+    const minSamples = timeoutConfig.minSamplesForAdaptive || 10;
+    if (ideRecord.successCount < minSamples) {
+      return timeoutConfig.defaultTimeout;
+    }
+
+    const baseTimeout = ideRecord.ewma;
+    const buffer = baseTimeout * (timeoutConfig.bufferPercentage || 0.4);
+    const adaptiveTimeout = baseTimeout + buffer;
+
+    // Enforce 5-minute minimum
+    return Math.max(adaptiveTimeout, 300000);
+  }
+
+  /**
+   * Debounced save operation
+   * @private
+   */
+  _debouncedSave() {
+    if (this.saveTimeout) {
+      clearTimeout(this.saveTimeout);
+    }
+
+    this.saveTimeout = setTimeout(async () => {
+      try {
+        await this.save();
+      } catch (error) {
+        this.emit('save-error', {
+          error,
+          retryCount: 0,
+        });
+      }
+    }, this.debounceMs);
+  }
+}
+
+module.exports = { IDEHealthTracker, MAX_RESPONSE_TIMES, CONSECUTIVE_FAILURE_THRESHOLD };

package/src/health-tracking/interaction-recorder.js

@@ -0,0 +1,161 @@
+/**
+ * Interaction Recorder
+ *
+ * Records individual IDE interactions with timestamps and outcomes.
+ *
+ * @module interaction-recorder
+ */
+
+const { ValidationError } = require('./errors');
+const { validateIdeId, validateInteractionRecord } = require('./validators');
+
+/**
+ * Maximum number of interactions to keep per IDE
+ */
+const MAX_INTERACTIONS = 100;
+
+/**
+ * Default IDE health record structure
+ */
+const DEFAULT_IDE_RECORD = {
+  successCount: 0,
+  failureCount: 0,
+  responseTimes: [],
+  ewma: 0,
+  lastSuccess: null,
+  lastFailure: null,
+  consecutiveFailures: 0,
+  currentTimeout: 1800000, // 30 minutes default
+  interactions: [],
+};
+
+/**
+ * Records individual interactions for IDE health tracking
+ */
+class InteractionRecorder {
+  /**
+   * @param {StorageInterface} storage - Storage interface with read() and write() methods
+   */
+  constructor(storage) {
+    if (!storage || typeof storage.read !== 'function' || typeof storage.write !== 'function') {
+      throw new ValidationError(
+        'Storage must implement read() and write() methods',
+        'storage',
+        storage
+      );
+    }
+    this.storage = storage;
+  }
+
+  /**
+   * Record a single interaction
+   * @param {Object} interaction - Interaction object
+   * @param {string} interaction.ideId - IDE identifier
+   * @param {Date} interaction.timestamp - Interaction timestamp
+   * @param {string} interaction.outcome - 'success' | 'failure' | 'quota'
+   * @param {number|null} interaction.responseTime - Response time in ms (null for failures/quota)
+   * @param {number} interaction.timeoutUsed - Timeout value used
+   * @param {number} interaction.continuationPromptsDetected - Number of prompts detected
+   * @param {string|null} interaction.requirementId - Associated requirement ID
+   * @param {string|null} interaction.errorMessage - Error message (for failures)
+   * @returns {Promise<void>}
+   * @throws {ValidationError} If validation fails
+   */
+  async record(interaction) {
+    // Validate ideId
+    validateIdeId(interaction.ideId);
+
+    // Convert Date to ISO string
+    const timestamp = interaction.timestamp instanceof Date
+      ? interaction.timestamp.toISOString()
+      : interaction.timestamp;
+
+    // Create interaction record
+    const record = {
+      timestamp,
+      outcome: interaction.outcome,
+      responseTime: interaction.responseTime,
+      timeoutUsed: interaction.timeoutUsed,
+      continuationPromptsDetected: interaction.continuationPromptsDetected || 0,
+      requirementId: interaction.requirementId || null,
+      errorMessage: interaction.errorMessage || null,
+    };
+
+    // Validate interaction record
+    validateInteractionRecord(record, interaction.ideId);
+
+    // Read current data
+    const data = await this.storage.read();
+
+    // Initialize IDE record if it doesn't exist
+    if (!data.ides[interaction.ideId]) {
+      data.ides[interaction.ideId] = JSON.parse(JSON.stringify(DEFAULT_IDE_RECORD));
+    }
+
+    // Add interaction to array
+    data.ides[interaction.ideId].interactions.push(record);
+
+    // Enforce max interactions limit
+    if (data.ides[interaction.ideId].interactions.length > MAX_INTERACTIONS) {
+      // Remove oldest interactions
+      data.ides[interaction.ideId].interactions = data.ides[interaction.ideId].interactions.slice(-MAX_INTERACTIONS);
+    }
+
+    // Write updated data
+    await this.storage.write(data);
+  }
+
+  /**
+   * Get interactions for a specific IDE
+   * @param {string} ideId - IDE identifier
+   * @param {number} [limit] - Maximum number of interactions to return (most recent)
+   * @returns {Promise<Array>} Array of interaction records
+   */
+  async getInteractions(ideId, limit) {
+    const data = await this.storage.read();
+
+    if (!data.ides[ideId] || !data.ides[ideId].interactions) {
+      return [];
+    }
+
+    const interactions = data.ides[ideId].interactions;
+
+    if (limit && limit > 0) {
+      return interactions.slice(-limit);
+    }
+
+    return interactions;
+  }
+
+  /**
+   * Clear all interactions for a specific IDE
+   * @param {string} ideId - IDE identifier
+   * @returns {Promise<void>}
+   */
+  async clearInteractions(ideId) {
+    const data = await this.storage.read();
+
+    if (data.ides[ideId]) {
+      data.ides[ideId].interactions = [];
+      await this.storage.write(data);
+    }
+  }
+
+  /**
+   * Get default IDE record structure
+   * @returns {Object} Default IDE record
+   */
+  static getDefaultRecord() {
+    return JSON.parse(JSON.stringify(DEFAULT_IDE_RECORD));
+  }
+
+  /**
+   * Get maximum interactions limit
+   * @returns {number} Max interactions per IDE
+   */
+  static getMaxInteractions() {
+    return MAX_INTERACTIONS;
+  }
+}
+
+module.exports = { InteractionRecorder, MAX_INTERACTIONS, DEFAULT_IDE_RECORD };