driftdetect-core 0.1.0

package/dist/store/history-store.js

@@ -0,0 +1,707 @@
+/**
+ * History Store - Pattern change tracking and approval history
+ *
+ * Tracks pattern changes over time and stores approval history.
+ * History entries are stored in .drift/history/ directory.
+ *
+ * @requirements 4.4 - THE Pattern_Store SHALL maintain history of pattern changes in .drift/history/
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { EventEmitter } from 'node:events';
+import { HISTORY_FILE_VERSION } from './types.js';
+// ============================================================================
+// Constants
+// ============================================================================
+/** Directory name for drift configuration */
+const DRIFT_DIR = '.drift';
+/** Directory name for history */
+const HISTORY_DIR = 'history';
+/** Main history file name */
+const HISTORY_FILE = 'patterns.json';
+/** Default maximum history entries per pattern */
+const DEFAULT_MAX_ENTRIES_PER_PATTERN = 100;
+/** Default maximum age for history entries in days */
+const DEFAULT_MAX_AGE_DAYS = 365;
+// ============================================================================
+// Error Classes
+// ============================================================================
+/**
+ * Error thrown when a history operation fails
+ */
+export class HistoryStoreError extends Error {
+    errorCause;
+    constructor(message, errorCause) {
+        super(message);
+        this.name = 'HistoryStoreError';
+        this.errorCause = errorCause;
+    }
+}
+/**
+ * Error thrown when a pattern history is not found
+ */
+export class PatternHistoryNotFoundError extends Error {
+    patternId;
+    constructor(patternId) {
+        super(`Pattern history not found: ${patternId}`);
+        this.patternId = patternId;
+        this.name = 'PatternHistoryNotFoundError';
+    }
+}
+/**
+ * Default history store configuration
+ */
+export const DEFAULT_HISTORY_STORE_CONFIG = {
+    rootDir: '.',
+    maxEntriesPerPattern: DEFAULT_MAX_ENTRIES_PER_PATTERN,
+    maxAgeDays: DEFAULT_MAX_AGE_DAYS,
+    autoSave: false,
+    autoSaveDebounce: 1000,
+};
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Check if a file exists
+ */
+async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Ensure a directory exists
+ */
+async function ensureDir(dirPath) {
+    await fs.mkdir(dirPath, { recursive: true });
+}
+// ============================================================================
+// History Store Class
+// ============================================================================
+/**
+ * History Store - Manages pattern change history
+ *
+ * Tracks all pattern changes including:
+ * - Pattern created
+ * - Pattern updated
+ * - Pattern approved
+ * - Pattern ignored
+ * - Pattern deleted
+ * - Confidence changed
+ * - Locations changed
+ * - Severity changed
+ *
+ * History is stored in .drift/history/patterns.json
+ *
+ * @requirements 4.4 - Pattern history tracked in .drift/history/
+ */
+export class HistoryStore extends EventEmitter {
+    config;
+    historyDir;
+    historyFilePath;
+    histories = new Map();
+    loaded = false;
+    dirty = false;
+    saveTimeout = null;
+    constructor(config = {}) {
+        super();
+        this.config = { ...DEFAULT_HISTORY_STORE_CONFIG, ...config };
+        this.historyDir = path.join(this.config.rootDir, DRIFT_DIR, HISTORY_DIR);
+        this.historyFilePath = path.join(this.historyDir, HISTORY_FILE);
+    }
+    // ==========================================================================
+    // Initialization
+    // ==========================================================================
+    /**
+     * Initialize the history store
+     *
+     * Creates necessary directories and loads existing history.
+     */
+    async initialize() {
+        // Create directory structure
+        await ensureDir(this.historyDir);
+        // Load existing history
+        await this.load();
+        this.loaded = true;
+    }
+    // ==========================================================================
+    // Loading
+    // ==========================================================================
+    /**
+     * Load history from disk
+     *
+     * @requirements 4.4 - Load history from .drift/history/
+     */
+    async load() {
+        this.histories.clear();
+        if (!(await fileExists(this.historyFilePath))) {
+            this.emitEvent('file:loaded', undefined, { count: 0 });
+            return;
+        }
+        try {
+            const content = await fs.readFile(this.historyFilePath, 'utf-8');
+            const data = JSON.parse(content);
+            // Load pattern histories into map
+            for (const history of data.patterns) {
+                this.histories.set(history.patternId, history);
+            }
+            this.emitEvent('file:loaded', undefined, { count: this.histories.size });
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return; // File doesn't exist, skip
+            }
+            throw new HistoryStoreError(`Failed to load history file: ${this.historyFilePath}`, error);
+        }
+    }
+    // ==========================================================================
+    // Saving
+    // ==========================================================================
+    /**
+     * Save history to disk
+     *
+     * @requirements 4.4 - Persist history in .drift/history/
+     */
+    async save() {
+        const historyFile = {
+            version: HISTORY_FILE_VERSION,
+            patterns: Array.from(this.histories.values()),
+            lastUpdated: new Date().toISOString(),
+        };
+        // Ensure directory exists
+        await ensureDir(this.historyDir);
+        // Write file
+        await fs.writeFile(this.historyFilePath, JSON.stringify(historyFile, null, 2));
+        this.dirty = false;
+        this.emitEvent('file:saved', undefined, { count: this.histories.size });
+    }
+    /**
+     * Schedule an auto-save if enabled
+     */
+    scheduleAutoSave() {
+        if (!this.config.autoSave) {
+            return;
+        }
+        if (this.saveTimeout) {
+            clearTimeout(this.saveTimeout);
+        }
+        this.saveTimeout = setTimeout(async () => {
+            if (this.dirty) {
+                await this.save();
+            }
+        }, this.config.autoSaveDebounce);
+    }
+    // ==========================================================================
+    // Recording Events
+    // ==========================================================================
+    /**
+     * Record a history event for a pattern
+     *
+     * @param patternId - Pattern ID
+     * @param category - Pattern category
+     * @param eventType - Type of event
+     * @param options - Additional event options
+     */
+    recordEvent(patternId, category, eventType, options = {}) {
+        const now = new Date().toISOString();
+        // Create the event
+        const event = {
+            timestamp: now,
+            type: eventType,
+            patternId,
+            ...(options.user && { user: options.user }),
+            ...(options.previousValue !== undefined && { previousValue: options.previousValue }),
+            ...(options.newValue !== undefined && { newValue: options.newValue }),
+            ...(options.details && { details: options.details }),
+        };
+        // Get or create pattern history
+        let history = this.histories.get(patternId);
+        if (!history) {
+            history = {
+                patternId,
+                category,
+                events: [],
+                createdAt: now,
+                lastModified: now,
+            };
+            this.histories.set(patternId, history);
+        }
+        // Add event to history
+        history.events.push(event);
+        history.lastModified = now;
+        // Prune if needed
+        this.prunePatternHistory(patternId);
+        this.dirty = true;
+        this.emitEvent('event:recorded', patternId, { eventType });
+        this.scheduleAutoSave();
+        return event;
+    }
+    /**
+     * Record a pattern creation event
+     */
+    recordCreated(pattern, user) {
+        const options = {
+            newValue: {
+                name: pattern.name,
+                description: pattern.description,
+                confidence: pattern.confidence.score,
+                severity: pattern.severity,
+            },
+        };
+        if (user !== undefined) {
+            options.user = user;
+        }
+        return this.recordEvent(pattern.id, pattern.category, 'created', options);
+    }
+    /**
+     * Record a pattern update event
+     */
+    recordUpdated(pattern, previousPattern, user) {
+        const options = {
+            previousValue: {
+                name: previousPattern.name,
+                description: previousPattern.description,
+            },
+            newValue: {
+                name: pattern.name,
+                description: pattern.description,
+            },
+        };
+        if (user !== undefined) {
+            options.user = user;
+        }
+        return this.recordEvent(pattern.id, pattern.category, 'updated', options);
+    }
+    /**
+     * Record a pattern approval event
+     */
+    recordApproved(pattern, user) {
+        const options = {
+            details: {
+                confidence: pattern.confidence.score,
+                severity: pattern.severity,
+            },
+        };
+        if (user !== undefined) {
+            options.user = user;
+        }
+        return this.recordEvent(pattern.id, pattern.category, 'approved', options);
+    }
+    /**
+     * Record a pattern ignore event
+     */
+    recordIgnored(pattern, user) {
+        const options = {};
+        if (user !== undefined) {
+            options.user = user;
+        }
+        return this.recordEvent(pattern.id, pattern.category, 'ignored', options);
+    }
+    /**
+     * Record a pattern deletion event
+     */
+    recordDeleted(pattern, user) {
+        const options = {
+            previousValue: {
+                name: pattern.name,
+                status: pattern.status,
+            },
+        };
+        if (user !== undefined) {
+            options.user = user;
+        }
+        return this.recordEvent(pattern.id, pattern.category, 'deleted', options);
+    }
+    /**
+     * Record a confidence change event
+     */
+    recordConfidenceChanged(pattern, previousScore, user) {
+        const options = {
+            previousValue: previousScore,
+            newValue: pattern.confidence.score,
+        };
+        if (user !== undefined) {
+            options.user = user;
+        }
+        return this.recordEvent(pattern.id, pattern.category, 'confidence_changed', options);
+    }
+    /**
+     * Record a locations change event
+     */
+    recordLocationsChanged(pattern, previousCount, user) {
+        const options = {
+            previousValue: previousCount,
+            newValue: pattern.locations.length,
+            details: {
+                added: Math.max(0, pattern.locations.length - previousCount),
+                removed: Math.max(0, previousCount - pattern.locations.length),
+            },
+        };
+        if (user !== undefined) {
+            options.user = user;
+        }
+        return this.recordEvent(pattern.id, pattern.category, 'locations_changed', options);
+    }
+    /**
+     * Record a severity change event
+     */
+    recordSeverityChanged(pattern, previousSeverity, user) {
+        const options = {
+            previousValue: previousSeverity,
+            newValue: pattern.severity,
+        };
+        if (user !== undefined) {
+            options.user = user;
+        }
+        return this.recordEvent(pattern.id, pattern.category, 'severity_changed', options);
+    }
+    // ==========================================================================
+    // Querying
+    // ==========================================================================
+    /**
+     * Get history for a specific pattern
+     *
+     * @param patternId - Pattern ID
+     * @returns Pattern history or undefined if not found
+     */
+    getPatternHistory(patternId) {
+        return this.histories.get(patternId);
+    }
+    /**
+     * Get history for a specific pattern, throwing if not found
+     *
+     * @param patternId - Pattern ID
+     * @returns Pattern history
+     * @throws PatternHistoryNotFoundError if not found
+     */
+    getPatternHistoryOrThrow(patternId) {
+        const history = this.histories.get(patternId);
+        if (!history) {
+            throw new PatternHistoryNotFoundError(patternId);
+        }
+        return history;
+    }
+    /**
+     * Check if history exists for a pattern
+     *
+     * @param patternId - Pattern ID
+     * @returns True if history exists
+     */
+    hasPatternHistory(patternId) {
+        return this.histories.has(patternId);
+    }
+    /**
+     * Query history events with filtering and pagination
+     *
+     * @param query - Query options
+     * @returns Query result with matching events
+     */
+    query(query = {}) {
+        const startTime = Date.now();
+        // Collect all events from relevant histories
+        let events = [];
+        // Filter by pattern ID(s)
+        if (query.patternId) {
+            const history = this.histories.get(query.patternId);
+            if (history) {
+                events = [...history.events];
+            }
+        }
+        else if (query.patternIds && query.patternIds.length > 0) {
+            for (const patternId of query.patternIds) {
+                const history = this.histories.get(patternId);
+                if (history) {
+                    events.push(...history.events);
+                }
+            }
+        }
+        else {
+            // Get all events
+            for (const history of this.histories.values()) {
+                events.push(...history.events);
+            }
+        }
+        // Apply filters
+        events = this.applyFilters(events, query);
+        // Sort by timestamp descending (most recent first)
+        events.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+        // Get total before pagination
+        const total = events.length;
+        // Apply pagination
+        const offset = query.offset ?? 0;
+        const limit = query.limit ?? events.length;
+        const hasMore = offset + limit < total;
+        events = events.slice(offset, offset + limit);
+        return {
+            events,
+            total,
+            hasMore,
+            executionTime: Date.now() - startTime,
+        };
+    }
+    /**
+     * Apply filters to events
+     */
+    applyFilters(events, query) {
+        return events.filter((event) => {
+            // Filter by event type
+            if (query.eventType) {
+                const types = Array.isArray(query.eventType)
+                    ? query.eventType
+                    : [query.eventType];
+                if (!types.includes(event.type)) {
+                    return false;
+                }
+            }
+            // Filter by category
+            if (query.category) {
+                const categories = Array.isArray(query.category)
+                    ? query.category
+                    : [query.category];
+                const history = this.histories.get(event.patternId);
+                if (!history || !categories.includes(history.category)) {
+                    return false;
+                }
+            }
+            // Filter by user
+            if (query.user && event.user !== query.user) {
+                return false;
+            }
+            // Filter by date range
+            if (query.after) {
+                const eventTime = new Date(event.timestamp).getTime();
+                const afterTime = new Date(query.after).getTime();
+                if (eventTime < afterTime) {
+                    return false;
+                }
+            }
+            if (query.before) {
+                const eventTime = new Date(event.timestamp).getTime();
+                const beforeTime = new Date(query.before).getTime();
+                if (eventTime > beforeTime) {
+                    return false;
+                }
+            }
+            return true;
+        });
+    }
+    // ==========================================================================
+    // Convenience Query Methods
+    // ==========================================================================
+    /**
+     * Get all history events
+     */
+    getAllEvents() {
+        return this.query().events;
+    }
+    /**
+     * Get events by type
+     */
+    getEventsByType(eventType) {
+        return this.query({ eventType }).events;
+    }
+    /**
+     * Get events by category
+     */
+    getEventsByCategory(category) {
+        return this.query({ category }).events;
+    }
+    /**
+     * Get events in date range
+     */
+    getEventsInDateRange(after, before) {
+        return this.query({ after, before }).events;
+    }
+    /**
+     * Get recent events
+     *
+     * @param limit - Maximum number of events to return
+     */
+    getRecentEvents(limit = 50) {
+        return this.query({ limit }).events;
+    }
+    /**
+     * Get approval history
+     */
+    getApprovalHistory() {
+        return this.getEventsByType('approved');
+    }
+    /**
+     * Get events by user
+     */
+    getEventsByUser(user) {
+        return this.query({ user }).events;
+    }
+    // ==========================================================================
+    // Pruning
+    // ==========================================================================
+    /**
+     * Prune history for a specific pattern
+     *
+     * Removes old entries based on maxEntriesPerPattern and maxAgeDays config.
+     *
+     * @param patternId - Pattern ID to prune
+     */
+    prunePatternHistory(patternId) {
+        const history = this.histories.get(patternId);
+        if (!history) {
+            return;
+        }
+        const now = Date.now();
+        const maxAgeMs = this.config.maxAgeDays * 24 * 60 * 60 * 1000;
+        // Filter out old events
+        history.events = history.events.filter((event) => {
+            const eventTime = new Date(event.timestamp).getTime();
+            return now - eventTime < maxAgeMs;
+        });
+        // Limit number of entries
+        if (history.events.length > this.config.maxEntriesPerPattern) {
+            // Keep most recent events
+            history.events = history.events
+                .sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime())
+                .slice(0, this.config.maxEntriesPerPattern);
+        }
+    }
+    /**
+     * Prune all history
+     *
+     * Removes old entries based on maxEntriesPerPattern and maxAgeDays config.
+     */
+    prune() {
+        for (const patternId of this.histories.keys()) {
+            this.prunePatternHistory(patternId);
+        }
+        // Remove empty histories
+        for (const [patternId, history] of this.histories.entries()) {
+            if (history.events.length === 0) {
+                this.histories.delete(patternId);
+            }
+        }
+        this.dirty = true;
+        this.emitEvent('history:pruned', undefined, { count: this.histories.size });
+        this.scheduleAutoSave();
+    }
+    /**
+     * Delete history for a specific pattern
+     *
+     * @param patternId - Pattern ID
+     * @returns True if history was deleted
+     */
+    deletePatternHistory(patternId) {
+        const deleted = this.histories.delete(patternId);
+        if (deleted) {
+            this.dirty = true;
+            this.scheduleAutoSave();
+        }
+        return deleted;
+    }
+    // ==========================================================================
+    // Statistics
+    // ==========================================================================
+    /**
+     * Get statistics about the history store
+     */
+    getStats() {
+        const eventsByType = {
+            created: 0,
+            approved: 0,
+            ignored: 0,
+            updated: 0,
+            deleted: 0,
+            confidence_changed: 0,
+            locations_changed: 0,
+            severity_changed: 0,
+        };
+        let totalEvents = 0;
+        let oldestEvent = null;
+        let newestEvent = null;
+        for (const history of this.histories.values()) {
+            for (const event of history.events) {
+                totalEvents++;
+                eventsByType[event.type]++;
+                if (!oldestEvent || event.timestamp < oldestEvent) {
+                    oldestEvent = event.timestamp;
+                }
+                if (!newestEvent || event.timestamp > newestEvent) {
+                    newestEvent = event.timestamp;
+                }
+            }
+        }
+        return {
+            totalPatterns: this.histories.size,
+            totalEvents,
+            eventsByType,
+            oldestEvent,
+            newestEvent,
+        };
+    }
+    // ==========================================================================
+    // Event Handling
+    // ==========================================================================
+    /**
+     * Emit a history store event
+     */
+    emitEvent(type, patternId, data) {
+        const event = {
+            type,
+            timestamp: new Date().toISOString(),
+        };
+        if (patternId !== undefined) {
+            event.patternId = patternId;
+        }
+        if (data !== undefined) {
+            event.data = data;
+        }
+        this.emit(type, event);
+        this.emit('*', event); // Wildcard for all events
+    }
+    // ==========================================================================
+    // Utility Methods
+    // ==========================================================================
+    /**
+     * Get the number of patterns with history
+     */
+    get size() {
+        return this.histories.size;
+    }
+    /**
+     * Check if the store has been loaded
+     */
+    get isLoaded() {
+        return this.loaded;
+    }
+    /**
+     * Check if there are unsaved changes
+     */
+    get isDirty() {
+        return this.dirty;
+    }
+    /**
+     * Get the history directory path
+     */
+    get path() {
+        return this.historyDir;
+    }
+    /**
+     * Clear all history from memory (does not affect disk)
+     */
+    clear() {
+        this.histories.clear();
+        this.dirty = true;
+    }
+    /**
+     * Dispose of the history store
+     */
+    dispose() {
+        if (this.saveTimeout) {
+            clearTimeout(this.saveTimeout);
+            this.saveTimeout = null;
+        }
+        this.removeAllListeners();
+    }
+}
+//# sourceMappingURL=history-store.js.map