qa360 1.4.5 → 2.0.1

package/dist/core/cache/lru-cache.js

@@ -0,0 +1,397 @@
+/**
+ * QA360 LRU Cache Module
+ *
+ * Intelligent caching system for HTTP responses to avoid redundant requests.
+ * Features:
+ * - LRU (Least Recently Used) eviction policy
+ * - TTL (Time To Live) expiration
+ * - Size-based limits
+ * - Cache key generation based on request parameters
+ * - Thread-safe operations (async-friendly)
+ * - Metrics and statistics
+ *
+ * @example
+ * ```typescript
+ * const cache = new ResponseCache({
+ *   maxSize: 100,
+ *   ttl: 60000, // 1 minute
+ *   maxSizeBytes: 10 * 1024 * 1024 // 10MB
+ * });
+ *
+ * const response = await cache.getOrFetch('GET:/api/users', async () => {
+ *   return await fetch('/api/users');
+ * });
+ * ```
+ */
+/**
+ * LRU Response Cache
+ *
+ * Thread-safe LRU cache with TTL and size-based eviction.
+ */
+export class ResponseCache {
+    cache;
+    maxSize;
+    ttl;
+    maxSizeBytes;
+    currentSizeBytes;
+    enableStats;
+    verbose;
+    stats;
+    constructor(options = {}) {
+        this.maxSize = options.maxSize ?? 100;
+        this.ttl = options.ttl ?? 300000; // 5 minutes default
+        this.maxSizeBytes = options.maxSizeBytes ?? 10 * 1024 * 1024; // 10MB default
+        this.enableStats = options.enableStats ?? true;
+        this.verbose = options.verbose ?? false;
+        this.currentSizeBytes = 0;
+        this.cache = new Map();
+        this.stats = {
+            hits: 0,
+            misses: 0,
+            additions: 0,
+            evictions: 0,
+            size: 0,
+            sizeBytes: 0,
+            hitRate: 0,
+            avgEntrySize: 0
+        };
+    }
+    /**
+     * Get a value from cache by key
+     * Returns undefined if not found or expired
+     */
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            this._recordMiss();
+            return undefined;
+        }
+        // Check if entry has expired
+        const now = Date.now();
+        const age = now - entry.createdAt;
+        if (age > this.ttl) {
+            // Entry expired, remove it
+            this._remove(key);
+            this._recordMiss();
+            if (this.verbose) {
+                console.log(`📦 Cache EXPIRED: ${key} (age: ${age}ms, TTL: ${this.ttl}ms)`);
+            }
+            return undefined;
+        }
+        // Update last accessed time and hit count
+        entry.lastAccessed = now;
+        entry.hitCount++;
+        // Move to end of Map to mark as most recently used
+        this.cache.delete(key);
+        this.cache.set(key, entry);
+        this._recordHit();
+        if (this.verbose) {
+            console.log(`📦 Cache HIT: ${key} (age: ${age}ms, hits: ${entry.hitCount})`);
+        }
+        return entry.data;
+    }
+    /**
+     * Set a value in cache by key
+     * If key exists, updates the entry
+     * If cache is full, evicts LRU entry
+     */
+    set(key, data, size) {
+        const now = Date.now();
+        const entrySize = size ?? this._estimateSize(data);
+        // Check if we need to evict entries
+        // First, if key already exists, we'll replace it (size may be different)
+        const existing = this.cache.get(key);
+        if (existing) {
+            this.currentSizeBytes -= existing.size;
+            this.cache.delete(key);
+        }
+        // Evict entries if we're over size limits
+        while ((this.cache.size >= this.maxSize) ||
+            (this.currentSizeBytes + entrySize > this.maxSizeBytes)) {
+            this._evictLRU();
+        }
+        // Add new entry
+        const entry = {
+            data,
+            createdAt: now,
+            lastAccessed: now,
+            hitCount: 0,
+            size: entrySize,
+            key
+        };
+        this.cache.set(key, entry);
+        this.currentSizeBytes += entrySize;
+        this._recordAddition();
+        if (this.verbose) {
+            console.log(`📦 Cache SET: ${key} (size: ${entrySize} bytes, total: ${this.cache.size} entries)`);
+        }
+    }
+    /**
+     * Get a value from cache, or compute and cache it if not present
+     * This is the main method to use for caching operations
+     */
+    async getOrFetch(key, fetchFn, size) {
+        const cached = this.get(key);
+        if (cached !== undefined) {
+            return cached;
+        }
+        // Cache miss - fetch and cache
+        const data = await fetchFn();
+        this.set(key, data, size);
+        return data;
+    }
+    /**
+     * Check if a key exists in cache and is not expired
+     */
+    has(key) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return false;
+        const age = Date.now() - entry.createdAt;
+        return age <= this.ttl;
+    }
+    /**
+     * Delete a specific entry from cache
+     */
+    delete(key) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return false;
+        this.currentSizeBytes -= entry.size;
+        return this.cache.delete(key);
+    }
+    /**
+     * Clear all entries from cache
+     */
+    clear() {
+        this.cache.clear();
+        this.currentSizeBytes = 0;
+        if (this.enableStats) {
+            this.stats.hits = 0;
+            this.stats.misses = 0;
+            this.stats.additions = 0;
+            this.stats.evictions = 0;
+        }
+        if (this.verbose) {
+            console.log('📦 Cache CLEARED');
+        }
+    }
+    /**
+     * Remove expired entries from cache
+     * Returns the number of entries removed
+     */
+    purgeExpired() {
+        const now = Date.now();
+        let removed = 0;
+        const keys = Array.from(this.cache.keys());
+        for (const key of keys) {
+            const entry = this.cache.get(key);
+            if (entry) {
+                const age = now - entry.createdAt;
+                if (age > this.ttl) {
+                    this._remove(key);
+                    removed++;
+                }
+            }
+        }
+        if (this.verbose && removed > 0) {
+            console.log(`📦 Cache PURGED: ${removed} expired entries removed`);
+        }
+        return removed;
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        const totalRequests = this.stats.hits + this.stats.misses;
+        return {
+            hits: this.stats.hits,
+            misses: this.stats.misses,
+            additions: this.stats.additions,
+            evictions: this.stats.evictions,
+            size: this.cache.size,
+            sizeBytes: this.currentSizeBytes,
+            hitRate: totalRequests > 0 ? this.stats.hits / totalRequests : 0,
+            avgEntrySize: this.cache.size > 0 ? Math.round(this.currentSizeBytes / this.cache.size) : 0
+        };
+    }
+    /**
+     * Reset cache statistics
+     */
+    resetStats() {
+        this.stats.hits = 0;
+        this.stats.misses = 0;
+        this.stats.additions = 0;
+        this.stats.evictions = 0;
+    }
+    /**
+     * Get all cache keys (useful for debugging)
+     */
+    keys() {
+        return Array.from(this.cache.keys());
+    }
+    /**
+     * Get cache size
+     */
+    get size() {
+        return this.cache.size;
+    }
+    /**
+     * Check if cache is empty
+     */
+    isEmpty() {
+        return this.cache.size === 0;
+    }
+    /**
+     * Evict least recently used entry (private method)
+     * Since we move accessed entries to the end, the first entry is the LRU
+     */
+    _evictLRU() {
+        // Get the first key (least recently used)
+        const lruKey = this.cache.keys().next().value;
+        if (lruKey) {
+            const entry = this.cache.get(lruKey);
+            this._remove(lruKey);
+            this.stats.evictions++;
+            if (this.verbose) {
+                console.log(`📦 Cache EVICT: ${lruKey} (LRU, last accessed: ${entry ? new Date(entry.lastAccessed).toISOString() : 'unknown'})`);
+            }
+        }
+    }
+    /**
+     * Remove entry and update size tracking (private method)
+     */
+    _remove(key) {
+        const entry = this.cache.get(key);
+        if (entry) {
+            this.currentSizeBytes -= entry.size;
+            this.cache.delete(key);
+        }
+    }
+    /**
+     * Estimate size of data in bytes (private method)
+     */
+    _estimateSize(data) {
+        if (data === null || data === undefined) {
+            return 0;
+        }
+        if (typeof data === 'string') {
+            return data.length * 2; // UTF-16 uses 2 bytes per char
+        }
+        if (typeof data === 'number') {
+            return 8;
+        }
+        if (typeof data === 'boolean') {
+            return 4;
+        }
+        if (data instanceof ArrayBuffer || data instanceof SharedArrayBuffer) {
+            return data.byteLength;
+        }
+        if (Array.isArray(data)) {
+            return data.reduce((sum, item) => sum + this._estimateSize(item), 0);
+        }
+        if (typeof data === 'object') {
+            return JSON.stringify(data).length * 2;
+        }
+        return 100; // Default estimate
+    }
+    _recordHit() {
+        if (this.enableStats) {
+            this.stats.hits++;
+        }
+    }
+    _recordMiss() {
+        if (this.enableStats) {
+            this.stats.misses++;
+        }
+    }
+    _recordAddition() {
+        if (this.enableStats) {
+            this.stats.additions++;
+        }
+    }
+}
+/**
+ * Generate a cache key from request parameters
+ *
+ * The key is generated based on:
+ * - HTTP method
+ * - URL
+ * - Vary headers (Authorization, Content-Type, etc.)
+ * - Request body (for POST/PUT/PATCH)
+ * - Query parameters
+ */
+export function generateCacheKey(options) {
+    const parts = [];
+    // Method and URL form the base
+    parts.push(`${options.method}:${options.url}`);
+    // Add query parameters if present
+    if (options.params && Object.keys(options.params).length > 0) {
+        const sortedParams = Object.keys(options.params)
+            .sort()
+            .map(k => `${k}=${options.params[k]}`)
+            .join('&');
+        parts.push(sortedParams);
+    }
+    // Add vary headers (default: Authorization, Content-Type)
+    const varyHeaders = options.varyHeaders ?? ['authorization', 'content-type'];
+    if (options.headers) {
+        const headerValues = [];
+        for (const header of varyHeaders) {
+            const value = options.headers[header];
+            if (value) {
+                headerValues.push(`${header}:${value}`);
+            }
+        }
+        if (headerValues.length > 0) {
+            parts.push(headerValues.join(';'));
+        }
+    }
+    // Add body hash for POST/PUT/PATCH (simplified)
+    if (options.body && ['POST', 'PUT', 'PATCH'].includes(options.method)) {
+        const bodyStr = typeof options.body === 'string' ? options.body : JSON.stringify(options.body);
+        // Simple hash of body content
+        let hash = 0;
+        for (let i = 0; i < bodyStr.length; i++) {
+            const char = bodyStr.charCodeAt(i);
+            hash = ((hash << 5) - hash) + char;
+            hash = hash & hash; // Convert to 32bit integer
+        }
+        parts.push(`body:${Math.abs(hash)}`);
+    }
+    return parts.join('|');
+}
+/**
+ * Create a response cache with default options for HTTP caching
+ */
+export function createResponseCache(options) {
+    return new ResponseCache(options);
+}
+/**
+ * Global default cache instance (singleton pattern)
+ * Can be used across the application for shared caching
+ */
+let defaultCacheInstance = null;
+/**
+ * Get or create the default cache instance
+ */
+export function getDefaultCache() {
+    if (!defaultCacheInstance) {
+        defaultCacheInstance = new ResponseCache({
+            maxSize: 200,
+            ttl: 300000, // 5 minutes
+            maxSizeBytes: 20 * 1024 * 1024, // 20MB
+            enableStats: true
+        });
+    }
+    return defaultCacheInstance;
+}
+/**
+ * Reset the default cache instance
+ */
+export function resetDefaultCache() {
+    if (defaultCacheInstance) {
+        defaultCacheInstance.clear();
+    }
+    defaultCacheInstance = null;
+}

package/dist/core/coverage/analyzer.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Coverage Analyzer
+ *
+ * Analyzes coverage data to provide insights, trends, and recommendations.
+ */
+import type { FileCoverage, CoverageMetrics, CoverageResult, CoverageTrend, CoverageGap, CoverageComparison, CoverageThreshold, CoverageType, CoverageReport } from './types.js';
+/**
+ * Historical coverage data point
+ */
+interface HistoricalCoverage {
+    runId: string;
+    timestamp: number;
+    metrics: CoverageMetrics;
+}
+/**
+ * Coverage Analyzer class
+ */
+export declare class CoverageAnalyzer {
+    private history;
+    /**
+     * Analyze coverage and generate insights
+     */
+    analyze(result: CoverageResult, threshold?: CoverageThreshold): CoverageReport;
+    /**
+     * Check if coverage meets thresholds
+     */
+    checkThresholds(metrics: CoverageMetrics, threshold?: CoverageThreshold): boolean;
+    /**
+     * Check if a single file meets thresholds
+     */
+    checkFileThresholds(file: FileCoverage, threshold?: CoverageThreshold): boolean;
+    /**
+     * Find coverage gaps
+     */
+    findGaps(files: Record<string, FileCoverage>, threshold?: CoverageThreshold): CoverageGap[];
+    /**
+     * Calculate priority for covering a file
+     */
+    private calculatePriority;
+    /**
+     * Estimate effort to cover a file
+     */
+    private estimateEffort;
+    /**
+     * Generate test suggestions for a file
+     */
+    private generateSuggestions;
+    /**
+     * Group consecutive numbers into ranges
+     */
+    private groupConsecutiveNumbers;
+    /**
+     * Get top and bottom files by coverage
+     */
+    getTopFiles(files: Record<string, FileCoverage>, limit?: number): Array<{
+        path: string;
+        coverage: number;
+        type: 'best' | 'worst';
+    }>;
+    /**
+     * Compare two coverage results
+     */
+    compare(baseResult: CoverageResult, compareResult: CoverageResult): CoverageComparison;
+    /**
+     * Add historical coverage data
+     */
+    addHistory(key: string, data: HistoricalCoverage): void;
+    /**
+     * Get coverage trends
+     */
+    getTrends(key: string, type?: CoverageType, limit?: number): CoverageTrend[];
+    /**
+     * Calculate trend direction
+     */
+    getTrendDirection(trends: CoverageTrend[]): 'improving' | 'stable' | 'declining';
+    /**
+     * Predict future coverage based on trends
+     */
+    predictCoverage(key: string, type: CoverageType | undefined, targetCoverage: number): {
+        predictedReach: number | null;
+        projectedCoverage: number;
+        confidence: 'high' | 'medium' | 'low';
+    };
+    /**
+     * Generate coverage summary text
+     */
+    generateSummary(metrics: CoverageMetrics): string;
+    /**
+     * Format coverage percentage with color indicator
+     */
+    formatCoverage(percentage: number, threshold?: number): string;
+    /**
+     * Clear history
+     */
+    clearHistory(key?: string): void;
+}
+/**
+ * Create a coverage analyzer
+ */
+export declare function createCoverageAnalyzer(): CoverageAnalyzer;
+export {};