dartmind 17.0.0

package/dist/v10/profiling/MemoryAnalyzer.js

@@ -0,0 +1,663 @@
+/**
+ * FlutterAI v10 - Memory Analyzer
+ *
+ * Memory usage analysis and leak detection.
+ *
+ * Features:
+ * - Memory snapshots
+ * - Heap tracking
+ * - Memory leak detection
+ * - Allocation tracking
+ * - Memory trend analysis
+ * - Threshold alerts
+ * - Memory pressure monitoring
+ *
+ * @module v10/profiling/MemoryAnalyzer
+ */
+import { EventEmitter } from 'events';
+// ============================================================================
+// Constants
+// ============================================================================
+const DEFAULT_CONFIG = {
+    snapshotInterval: 0, // Disabled by default
+    maxSnapshots: 1000,
+    autoLeakDetection: false,
+    leakDetectionWindow: 10,
+    leakGrowthThreshold: 1024 * 1024, // 1MB/sec
+    thresholds: []
+};
+// ============================================================================
+// MemoryAnalyzer Implementation
+// ============================================================================
+/**
+ * Memory usage analyzer with leak detection
+ *
+ * @example
+ * ```typescript
+ * const analyzer = new MemoryAnalyzer({
+ *   snapshotInterval: 5000, // Every 5 seconds
+ *   autoLeakDetection: true
+ * });
+ *
+ * analyzer.start();
+ *
+ * // Take manual snapshots
+ * analyzer.takeSnapshot('before_operation');
+ * await doOperation();
+ * analyzer.takeSnapshot('after_operation');
+ *
+ * // Analyze
+ * const delta = analyzer.getDelta('before_operation', 'after_operation');
+ * console.log(`Memory change: ${delta.heapUsedDelta} bytes`);
+ *
+ * // Detect leaks
+ * const leakResult = analyzer.detectLeaks();
+ * if (leakResult.detected) {
+ *   console.warn('Memory leak detected!', leakResult.recommendation);
+ * }
+ * ```
+ */
+export class MemoryAnalyzer extends EventEmitter {
+    config;
+    snapshots = new Map();
+    snapshotOrder = [];
+    allocations = [];
+    intervalId;
+    snapshotCounter = 0;
+    isRunning = false;
+    constructor(config = {}) {
+        super();
+        this.config = {
+            ...DEFAULT_CONFIG,
+            ...config,
+            thresholds: config.thresholds ? [...config.thresholds] : []
+        };
+    }
+    // --------------------------------------------------------------------------
+    // Snapshot Management
+    // --------------------------------------------------------------------------
+    /**
+     * Take a memory snapshot
+     */
+    takeSnapshot(label) {
+        const id = `snapshot_${++this.snapshotCounter}_${Date.now()}`;
+        const memory = this.getMemoryInfo();
+        const snapshot = {
+            id,
+            timestamp: Date.now(),
+            heapUsed: memory.heapUsed,
+            heapTotal: memory.heapTotal,
+            external: memory.external,
+            arrayBuffers: memory.arrayBuffers,
+            rss: memory.rss,
+            label
+        };
+        this.storeSnapshot(snapshot);
+        this.checkThresholds(snapshot);
+        this.emit('event', { type: 'snapshot_taken', snapshot });
+        // Auto leak detection
+        if (this.config.autoLeakDetection && this.snapshotOrder.length >= this.config.leakDetectionWindow) {
+            const leakResult = this.detectLeaks();
+            if (leakResult.detected) {
+                this.emit('event', { type: 'leak_detected', result: leakResult });
+            }
+        }
+        return snapshot;
+    }
+    /**
+     * Get a snapshot by ID or label
+     */
+    getSnapshot(idOrLabel) {
+        // Try ID first
+        const byId = this.snapshots.get(idOrLabel);
+        if (byId)
+            return byId;
+        // Try label
+        return Array.from(this.snapshots.values()).find(s => s.label === idOrLabel);
+    }
+    /**
+     * Get the latest snapshot
+     */
+    getLatestSnapshot() {
+        if (this.snapshotOrder.length === 0)
+            return undefined;
+        return this.snapshots.get(this.snapshotOrder[this.snapshotOrder.length - 1]);
+    }
+    /**
+     * Get all snapshots
+     */
+    getSnapshots() {
+        return this.snapshotOrder.map(id => this.snapshots.get(id));
+    }
+    /**
+     * Get snapshots within a time range
+     */
+    getSnapshotsInRange(startTime, endTime) {
+        return this.getSnapshots().filter(s => s.timestamp >= startTime && s.timestamp <= endTime);
+    }
+    /**
+     * Calculate delta between two snapshots
+     */
+    getDelta(fromIdOrLabel, toIdOrLabel) {
+        const from = this.getSnapshot(fromIdOrLabel);
+        const to = this.getSnapshot(toIdOrLabel);
+        if (!from || !to)
+            return undefined;
+        const duration = to.timestamp - from.timestamp;
+        const heapUsedDelta = to.heapUsed - from.heapUsed;
+        return {
+            fromSnapshot: from.id,
+            toSnapshot: to.id,
+            heapUsedDelta,
+            heapTotalDelta: to.heapTotal - from.heapTotal,
+            externalDelta: to.external - from.external,
+            rssDelta: to.rss - from.rss,
+            duration,
+            growthRate: duration > 0 ? (heapUsedDelta / duration) * 1000 : 0 // bytes per second
+        };
+    }
+    // --------------------------------------------------------------------------
+    // Allocation Tracking
+    // --------------------------------------------------------------------------
+    /**
+     * Track memory around an operation
+     */
+    trackAllocation(label, fn, context) {
+        const before = this.getMemoryInfo().heapUsed;
+        const result = fn();
+        const after = this.getMemoryInfo().heapUsed;
+        const entry = {
+            id: `alloc_${Date.now()}_${Math.random().toString(36).slice(2)}`,
+            label,
+            timestamp: Date.now(),
+            sizeBefore: before,
+            sizeAfter: after,
+            delta: after - before,
+            context
+        };
+        this.allocations.push(entry);
+        // Keep allocations bounded
+        while (this.allocations.length > this.config.maxSnapshots) {
+            this.allocations.shift();
+        }
+        this.emit('event', { type: 'allocation_tracked', entry });
+        return result;
+    }
+    /**
+     * Track async allocation
+     */
+    async trackAllocationAsync(label, fn, context) {
+        const before = this.getMemoryInfo().heapUsed;
+        const result = await fn();
+        const after = this.getMemoryInfo().heapUsed;
+        const entry = {
+            id: `alloc_${Date.now()}_${Math.random().toString(36).slice(2)}`,
+            label,
+            timestamp: Date.now(),
+            sizeBefore: before,
+            sizeAfter: after,
+            delta: after - before,
+            context
+        };
+        this.allocations.push(entry);
+        this.emit('event', { type: 'allocation_tracked', entry });
+        return result;
+    }
+    /**
+     * Get allocations by label
+     */
+    getAllocations(label) {
+        if (!label)
+            return [...this.allocations];
+        return this.allocations.filter(a => a.label === label);
+    }
+    /**
+     * Get allocation statistics
+     */
+    getAllocationStats(label) {
+        const allocs = this.getAllocations(label);
+        if (allocs.length === 0)
+            return undefined;
+        const deltas = allocs.map(a => a.delta);
+        const totalDelta = deltas.reduce((a, b) => a + b, 0);
+        return {
+            count: allocs.length,
+            totalDelta,
+            avgDelta: totalDelta / allocs.length,
+            maxDelta: Math.max(...deltas),
+            minDelta: Math.min(...deltas)
+        };
+    }
+    // --------------------------------------------------------------------------
+    // Leak Detection
+    // --------------------------------------------------------------------------
+    /**
+     * Detect memory leaks based on snapshot trends
+     */
+    detectLeaks(windowSize) {
+        const window = windowSize || this.config.leakDetectionWindow;
+        const snapshots = this.getSnapshots().slice(-window);
+        if (snapshots.length < 3) {
+            return {
+                detected: false,
+                confidence: 0,
+                growthRate: 0,
+                snapshots,
+                trend: 'stable',
+                recommendation: 'Not enough data for leak detection.'
+            };
+        }
+        // Calculate growth rate using linear regression
+        const { slope, r2 } = this.linearRegression(snapshots.map(s => s.timestamp), snapshots.map(s => s.heapUsed));
+        // Convert slope to bytes per second
+        const growthRate = slope * 1000;
+        const trend = this.determineTrend(growthRate, r2);
+        // Calculate confidence based on R² value
+        const confidence = r2;
+        // Detect leak if growth rate exceeds threshold and trend is consistent
+        const detected = growthRate > this.config.leakGrowthThreshold && r2 > 0.7;
+        // Calculate projected exhaustion time (if growing)
+        let projectedExhaustion;
+        if (detected && growthRate > 0) {
+            const currentHeap = snapshots[snapshots.length - 1].heapUsed;
+            const maxHeap = this.getMaxHeapSize();
+            const remainingBytes = maxHeap - currentHeap;
+            projectedExhaustion = (remainingBytes / growthRate) * 1000; // ms until exhaustion
+        }
+        const recommendation = this.generateLeakRecommendation(detected, growthRate, trend, r2);
+        return {
+            detected,
+            confidence,
+            growthRate,
+            projectedExhaustion,
+            snapshots,
+            trend,
+            recommendation
+        };
+    }
+    /**
+     * Check for memory pressure
+     */
+    checkMemoryPressure() {
+        const memory = this.getMemoryInfo();
+        const usagePercent = (memory.heapUsed / memory.heapTotal) * 100;
+        let pressure;
+        let recommendation;
+        if (usagePercent > 95) {
+            pressure = 'critical';
+            recommendation = 'Memory nearly exhausted. Immediately reduce allocations or increase heap size.';
+        }
+        else if (usagePercent > 85) {
+            pressure = 'high';
+            recommendation = 'High memory pressure. Consider reducing cache sizes or triggering GC.';
+        }
+        else if (usagePercent > 70) {
+            pressure = 'moderate';
+            recommendation = 'Moderate memory usage. Monitor for increases.';
+        }
+        else {
+            pressure = 'low';
+            recommendation = 'Memory usage is healthy.';
+        }
+        return { pressure, usagePercent, recommendation };
+    }
+    // --------------------------------------------------------------------------
+    // Statistics
+    // --------------------------------------------------------------------------
+    /**
+     * Get memory statistics
+     */
+    getStats() {
+        const snapshots = this.getSnapshots();
+        if (snapshots.length === 0)
+            return undefined;
+        const current = snapshots[snapshots.length - 1];
+        let min = snapshots[0];
+        let max = snapshots[0];
+        let sumHeapUsed = 0;
+        let sumHeapTotal = 0;
+        let sumExternal = 0;
+        let sumRss = 0;
+        for (const snapshot of snapshots) {
+            if (snapshot.heapUsed < min.heapUsed)
+                min = snapshot;
+            if (snapshot.heapUsed > max.heapUsed)
+                max = snapshot;
+            sumHeapUsed += snapshot.heapUsed;
+            sumHeapTotal += snapshot.heapTotal;
+            sumExternal += snapshot.external;
+            sumRss += snapshot.rss;
+        }
+        const count = snapshots.length;
+        const timespan = current.timestamp - snapshots[0].timestamp;
+        // Determine trend
+        const { slope, r2 } = this.linearRegression(snapshots.map(s => s.timestamp), snapshots.map(s => s.heapUsed));
+        const growthRate = slope * 1000;
+        const trend = this.determineTrend(growthRate, r2);
+        return {
+            current,
+            min,
+            max,
+            average: {
+                heapUsed: sumHeapUsed / count,
+                heapTotal: sumHeapTotal / count,
+                external: sumExternal / count,
+                rss: sumRss / count
+            },
+            trend,
+            snapshotCount: count,
+            timespan
+        };
+    }
+    // --------------------------------------------------------------------------
+    // Threshold Management
+    // --------------------------------------------------------------------------
+    /**
+     * Add a memory threshold
+     */
+    addThreshold(threshold) {
+        this.config.thresholds.push(threshold);
+    }
+    /**
+     * Remove a threshold by name
+     */
+    removeThreshold(name) {
+        const index = this.config.thresholds.findIndex(t => t.name === name);
+        if (index >= 0) {
+            this.config.thresholds.splice(index, 1);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Get all thresholds
+     */
+    getThresholds() {
+        return [...this.config.thresholds];
+    }
+    // --------------------------------------------------------------------------
+    // Automatic Monitoring
+    // --------------------------------------------------------------------------
+    /**
+     * Start automatic snapshot taking
+     */
+    start() {
+        if (this.isRunning)
+            return;
+        if (this.config.snapshotInterval <= 0)
+            return;
+        this.isRunning = true;
+        this.intervalId = setInterval(() => {
+            this.takeSnapshot();
+        }, this.config.snapshotInterval);
+    }
+    /**
+     * Stop automatic snapshot taking
+     */
+    stop() {
+        if (this.intervalId) {
+            clearInterval(this.intervalId);
+            this.intervalId = undefined;
+        }
+        this.isRunning = false;
+    }
+    /**
+     * Check if monitoring is running
+     */
+    isMonitoring() {
+        return this.isRunning;
+    }
+    // --------------------------------------------------------------------------
+    // GC Helpers
+    // --------------------------------------------------------------------------
+    /**
+     * Request garbage collection (if available)
+     */
+    requestGC() {
+        if (typeof global !== 'undefined' && typeof global.gc === 'function') {
+            const before = this.getMemoryInfo().heapUsed;
+            global.gc();
+            const after = this.getMemoryInfo().heapUsed;
+            const freed = before - after;
+            this.emit('event', { type: 'gc_triggered', before, after, freed });
+            return true;
+        }
+        return false;
+    }
+    // --------------------------------------------------------------------------
+    // Reporting
+    // --------------------------------------------------------------------------
+    /**
+     * Generate a memory report
+     */
+    generateReport() {
+        const stats = this.getStats();
+        const pressure = this.checkMemoryPressure();
+        const leakResult = this.detectLeaks();
+        const lines = [];
+        lines.push('# Memory Analysis Report');
+        lines.push('');
+        lines.push('## Current Status');
+        lines.push(`- Memory Pressure: ${pressure.pressure}`);
+        lines.push(`- Usage: ${pressure.usagePercent.toFixed(1)}%`);
+        lines.push(`- Recommendation: ${pressure.recommendation}`);
+        lines.push('');
+        if (stats) {
+            lines.push('## Statistics');
+            lines.push(`- Snapshots: ${stats.snapshotCount}`);
+            lines.push(`- Timespan: ${(stats.timespan / 1000).toFixed(1)}s`);
+            lines.push(`- Trend: ${stats.trend}`);
+            lines.push('');
+            lines.push('### Current Memory');
+            lines.push(`- Heap Used: ${this.formatBytes(stats.current.heapUsed)}`);
+            lines.push(`- Heap Total: ${this.formatBytes(stats.current.heapTotal)}`);
+            lines.push(`- External: ${this.formatBytes(stats.current.external)}`);
+            lines.push(`- RSS: ${this.formatBytes(stats.current.rss)}`);
+            lines.push('');
+            lines.push('### Averages');
+            lines.push(`- Heap Used: ${this.formatBytes(stats.average.heapUsed)}`);
+            lines.push(`- Heap Total: ${this.formatBytes(stats.average.heapTotal)}`);
+            lines.push('');
+            lines.push('### Range');
+            lines.push(`- Min Heap Used: ${this.formatBytes(stats.min.heapUsed)}`);
+            lines.push(`- Max Heap Used: ${this.formatBytes(stats.max.heapUsed)}`);
+            lines.push('');
+        }
+        lines.push('## Leak Detection');
+        lines.push(`- Detected: ${leakResult.detected ? 'Yes' : 'No'}`);
+        lines.push(`- Confidence: ${(leakResult.confidence * 100).toFixed(1)}%`);
+        lines.push(`- Growth Rate: ${this.formatBytes(leakResult.growthRate)}/s`);
+        if (leakResult.projectedExhaustion !== undefined) {
+            lines.push(`- Projected Exhaustion: ${(leakResult.projectedExhaustion / 1000 / 60).toFixed(1)} minutes`);
+        }
+        lines.push(`- Recommendation: ${leakResult.recommendation}`);
+        lines.push('');
+        // Allocation summary
+        if (this.allocations.length > 0) {
+            lines.push('## Top Allocations');
+            const sorted = [...this.allocations].sort((a, b) => b.delta - a.delta).slice(0, 5);
+            for (const alloc of sorted) {
+                lines.push(`- ${alloc.label}: ${this.formatBytes(alloc.delta)}`);
+            }
+        }
+        return lines.join('\n');
+    }
+    // --------------------------------------------------------------------------
+    // Utilities
+    // --------------------------------------------------------------------------
+    /**
+     * Clear all data
+     */
+    clear() {
+        this.snapshots.clear();
+        this.snapshotOrder = [];
+        this.allocations = [];
+    }
+    /**
+     * Shutdown analyzer
+     */
+    shutdown() {
+        this.stop();
+        this.clear();
+        this.removeAllListeners();
+    }
+    /**
+     * Format bytes to human readable
+     */
+    formatBytes(bytes) {
+        if (bytes === 0)
+            return '0 B';
+        const negative = bytes < 0;
+        bytes = Math.abs(bytes);
+        const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+        const i = Math.floor(Math.log(bytes) / Math.log(1024));
+        const value = bytes / Math.pow(1024, i);
+        return `${negative ? '-' : ''}${value.toFixed(2)} ${units[i]}`;
+    }
+    // --------------------------------------------------------------------------
+    // Private Methods
+    // --------------------------------------------------------------------------
+    getMemoryInfo() {
+        if (typeof process !== 'undefined' && process.memoryUsage) {
+            const mem = process.memoryUsage();
+            return {
+                heapUsed: mem.heapUsed,
+                heapTotal: mem.heapTotal,
+                external: mem.external,
+                arrayBuffers: mem.arrayBuffers || 0,
+                rss: mem.rss
+            };
+        }
+        // Browser fallback
+        if (typeof performance !== 'undefined') {
+            const perfMemory = performance.memory;
+            if (perfMemory) {
+                return {
+                    heapUsed: perfMemory.usedJSHeapSize,
+                    heapTotal: perfMemory.totalJSHeapSize,
+                    external: 0,
+                    arrayBuffers: 0,
+                    rss: 0
+                };
+            }
+        }
+        return { heapUsed: 0, heapTotal: 0, external: 0, arrayBuffers: 0, rss: 0 };
+    }
+    getMaxHeapSize() {
+        // Default to a reasonable max heap size
+        const heapTotal = this.getMemoryInfo().heapTotal;
+        // Estimate max as 1.5x current total
+        return heapTotal * 1.5;
+    }
+    storeSnapshot(snapshot) {
+        // Enforce max snapshots
+        while (this.snapshotOrder.length >= this.config.maxSnapshots) {
+            const oldestId = this.snapshotOrder.shift();
+            if (oldestId) {
+                this.snapshots.delete(oldestId);
+            }
+        }
+        this.snapshots.set(snapshot.id, snapshot);
+        this.snapshotOrder.push(snapshot.id);
+    }
+    checkThresholds(snapshot) {
+        for (const threshold of this.config.thresholds) {
+            let value;
+            switch (threshold.type) {
+                case 'heapUsed':
+                    value = snapshot.heapUsed;
+                    break;
+                case 'heapTotal':
+                    value = snapshot.heapTotal;
+                    break;
+                case 'rss':
+                    value = snapshot.rss;
+                    break;
+                case 'external':
+                    value = snapshot.external;
+                    break;
+            }
+            if (value > threshold.limit) {
+                this.emit('event', {
+                    type: 'threshold_exceeded',
+                    snapshot,
+                    threshold
+                });
+                if (threshold.callback) {
+                    threshold.callback(snapshot, threshold);
+                }
+            }
+        }
+    }
+    linearRegression(x, y) {
+        const n = x.length;
+        if (n < 2)
+            return { slope: 0, intercept: 0, r2: 0 };
+        const sumX = x.reduce((a, b) => a + b, 0);
+        const sumY = y.reduce((a, b) => a + b, 0);
+        const sumXY = x.reduce((acc, xi, i) => acc + xi * y[i], 0);
+        const sumX2 = x.reduce((acc, xi) => acc + xi * xi, 0);
+        // Check for degenerate case (all x values are the same)
+        const denominator = n * sumX2 - sumX * sumX;
+        if (denominator === 0 || !Number.isFinite(denominator)) {
+            return { slope: 0, intercept: sumY / n, r2: 0 };
+        }
+        const slope = (n * sumXY - sumX * sumY) / denominator;
+        // Check for invalid slope
+        if (!Number.isFinite(slope)) {
+            return { slope: 0, intercept: sumY / n, r2: 0 };
+        }
+        const intercept = (sumY - slope * sumX) / n;
+        // Calculate R²
+        const yMean = sumY / n;
+        const ssTotal = y.reduce((acc, yi) => acc + Math.pow(yi - yMean, 2), 0);
+        // If ssTotal is 0 or very small, all y values are the same - perfect fit
+        if (ssTotal < 1e-10) {
+            return { slope, intercept, r2: 1 };
+        }
+        const ssResidual = y.reduce((acc, yi, i) => {
+            const predicted = slope * x[i] + intercept;
+            return acc + Math.pow(yi - predicted, 2);
+        }, 0);
+        const r2 = 1 - (ssResidual / ssTotal);
+        return { slope, intercept, r2: Math.max(0, Math.min(1, r2)) };
+    }
+    determineTrend(growthRate, r2) {
+        // Threshold for significant growth/shrinkage: 1KB/sec
+        const threshold = 1024;
+        // If growth rate is negligible, memory is stable regardless of R²
+        if (Math.abs(growthRate) <= threshold) {
+            return 'stable';
+        }
+        // If R² is low with significant growth rate, data is volatile
+        if (r2 < 0.5)
+            return 'volatile';
+        if (growthRate > threshold)
+            return 'growing';
+        if (growthRate < -threshold)
+            return 'shrinking';
+        return 'stable';
+    }
+    generateLeakRecommendation(detected, growthRate, trend, r2) {
+        if (!detected) {
+            if (trend === 'volatile') {
+                return 'Memory usage is volatile. Consider more frequent snapshots for better analysis.';
+            }
+            if (trend === 'growing' && r2 < 0.7) {
+                return 'Memory is growing but pattern is inconsistent. Continue monitoring.';
+            }
+            return 'No memory leak detected. Memory usage appears stable.';
+        }
+        const recommendations = [];
+        recommendations.push(`Memory leak detected with growth rate of ${this.formatBytes(growthRate)}/s.`);
+        if (growthRate > 10 * 1024 * 1024) { // > 10MB/s
+            recommendations.push('Critical: Very rapid memory growth. Immediate investigation required.');
+        }
+        else if (growthRate > 1024 * 1024) { // > 1MB/s
+            recommendations.push('High severity: Significant memory growth detected.');
+        }
+        recommendations.push('Check for: unclosed connections, unbounded caches, event listener accumulation, circular references.');
+        return recommendations.join(' ');
+    }
+}
+//# sourceMappingURL=MemoryAnalyzer.js.map