systemlens 1.0.0

package/src/analyzers/memory.analyzer.js

@@ -0,0 +1,107 @@
+// ─── Memory Analyzer ─────────────────────────────────────────────
+import { THRESHOLDS, SEVERITY } from '../utils/constants.js';
+import { formatBytes } from '../utils/helpers.js';
+
+export class MemoryAnalyzer {
+    /**
+     * Analyze memory data and return insights
+     * @param {Object} memData - From MemoryCollector
+     * @param {Object|null} previousData - Previous snapshot for comparison
+     * @returns {Object} Analysis results
+     */
+    analyze(memData, previousData = null) {
+        const usedPercent = memData.ram.usedPercent;
+        const issues = [];
+        const insights = [];
+
+        // ── Severity classification ──
+        let severity;
+        if (usedPercent >= THRESHOLDS.MEMORY_HIGH) {
+            severity = SEVERITY.CRITICAL;
+            issues.push({
+                type: 'memory_high',
+                severity: 'critical',
+                message: `Memory usage is critically high at ${usedPercent}% (${memData.ram.formatted.used} of ${memData.ram.formatted.total})`,
+                value: usedPercent,
+            });
+        } else if (usedPercent >= THRESHOLDS.MEMORY_WARNING) {
+            severity = SEVERITY.WARNING;
+            issues.push({
+                type: 'memory_warning',
+                severity: 'warning',
+                message: `Memory usage is elevated at ${usedPercent}% (${memData.ram.formatted.used} of ${memData.ram.formatted.total})`,
+                value: usedPercent,
+            });
+        } else if (usedPercent >= THRESHOLDS.MEMORY_MODERATE) {
+            severity = SEVERITY.INFO;
+            insights.push({
+                type: 'memory_moderate',
+                message: `Memory usage is moderate at ${usedPercent}%`,
+                value: usedPercent,
+            });
+        } else {
+            severity = SEVERITY.OK;
+            insights.push({
+                type: 'memory_ok',
+                message: `Memory usage is healthy at ${usedPercent}% — plenty of free RAM available`,
+                value: usedPercent,
+            });
+        }
+
+        // ── Available memory warning ──
+        const availableGB = memData.ram.available / (1024 * 1024 * 1024);
+        if (availableGB < 1 && usedPercent > 50) {
+            issues.push({
+                type: 'low_available_memory',
+                severity: 'warning',
+                message: `Only ${formatBytes(memData.ram.available)} of RAM is available — system may start swapping soon`,
+                value: availableGB,
+            });
+        }
+
+        // ── Swap usage ──
+        if (memData.swap.usedPercent > 20) {
+            issues.push({
+                type: 'swap_active',
+                severity: memData.swap.usedPercent > 50 ? 'critical' : 'warning',
+                message: `Swap is being used (${memData.swap.usedPercent}% — ${memData.swap.formatted.used}). This means RAM has been exhausted and the system is using slower disk storage as memory, causing significant slowdown.`,
+                value: memData.swap.usedPercent,
+            });
+        } else if (memData.swap.usedPercent > 0 && memData.swap.total > 0) {
+            insights.push({
+                type: 'swap_minor',
+                message: `Minimal swap usage detected (${memData.swap.usedPercent}%) — generally not a concern`,
+                value: memData.swap.usedPercent,
+            });
+        }
+
+        // ── Memory spike ──
+        if (previousData) {
+            const prevUsed = previousData.ram.usedPercent;
+            const delta = usedPercent - prevUsed;
+
+            if (delta >= THRESHOLDS.SPIKE_THRESHOLD) {
+                issues.push({
+                    type: 'memory_spike',
+                    severity: 'warning',
+                    message: `Memory usage spiked by ${delta.toFixed(1)}% (from ${prevUsed}% to ${usedPercent}%) — something just allocated a large chunk of memory`,
+                    value: delta,
+                });
+            }
+        }
+
+        return {
+            usedPercent,
+            severity,
+            issues,
+            insights,
+            details: {
+                total: memData.ram.total,
+                used: memData.ram.active,
+                available: memData.ram.available,
+                swapUsed: memData.swap.usedPercent,
+                formatted: memData.ram.formatted,
+            },
+        };
+    }
+}

package/src/analyzers/process.analyzer.js

@@ -0,0 +1,136 @@
+// ─── Process Analyzer ────────────────────────────────────────────
+// Identifies responsibility and patterns in process behavior
+import { THRESHOLDS, SEVERITY } from '../utils/constants.js';
+
+export class ProcessAnalyzer {
+    /**
+     * Analyze processes and determine what's causing load
+     * @param {Array} classifiedProcesses - Processes with classification
+     * @param {Object} cpuAnalysis - Results from CpuAnalyzer
+     * @param {Object} memAnalysis - Results from MemoryAnalyzer
+     * @returns {Object} Process-level insights
+     */
+    analyze(classifiedProcesses, cpuAnalysis, memAnalysis) {
+        const issues = [];
+        const insights = [];
+        const responsibilities = [];
+
+        // ── Identify CPU hogs ──
+        const cpuHogs = classifiedProcesses.filter(p => p.cpu >= THRESHOLDS.PROCESS_CPU_HIGH);
+        const cpuWarners = classifiedProcesses.filter(
+            p => p.cpu >= THRESHOLDS.PROCESS_CPU_WARNING && p.cpu < THRESHOLDS.PROCESS_CPU_HIGH
+        );
+
+        if (cpuHogs.length === 1) {
+            const hog = cpuHogs[0];
+            responsibilities.push({
+                type: 'single_cpu_dominant',
+                process: hog,
+                message: `"${hog.name}" is the primary CPU consumer at ${hog.cpu}%`,
+                severity: 'critical',
+            });
+        } else if (cpuHogs.length > 1) {
+            responsibilities.push({
+                type: 'multiple_cpu_hogs',
+                processes: cpuHogs,
+                message: `${cpuHogs.length} processes are competing for CPU: ${cpuHogs.map(p => `${p.name} (${p.cpu}%)`).join(', ')}`,
+                severity: 'critical',
+            });
+        }
+
+        // ── Identify memory hogs ──
+        const memHogs = classifiedProcesses.filter(p => p.mem >= THRESHOLDS.PROCESS_MEM_HIGH);
+
+        if (memHogs.length > 0) {
+            for (const hog of memHogs) {
+                responsibilities.push({
+                    type: 'memory_hog',
+                    process: hog,
+                    message: `"${hog.name}" is consuming ${hog.mem}% of memory (${hog.memRssFormatted})`,
+                    severity: hog.mem >= 30 ? 'critical' : 'warning',
+                });
+            }
+        }
+
+        // ── Detect "death by a thousand cuts" (many small processes adding up) ──
+        const smallProcs = classifiedProcesses.filter(
+            p => p.cpu >= 2 && p.cpu < THRESHOLDS.PROCESS_CPU_WARNING
+        );
+        const smallProcTotalCpu = smallProcs.reduce((sum, p) => sum + p.cpu, 0);
+
+        if (smallProcs.length >= 5 && smallProcTotalCpu > 30) {
+            issues.push({
+                type: 'distributed_load',
+                severity: 'warning',
+                message: `${smallProcs.length} background processes are collectively using ${smallProcTotalCpu.toFixed(1)}% CPU — no single culprit, but the combined load is significant`,
+                processes: smallProcs,
+            });
+        }
+
+        // ── Browser analysis ──
+        const browserProcs = classifiedProcesses.filter(p => p.classification.isBrowser);
+        if (browserProcs.length > 3) {
+            const totalBrowserCpu = browserProcs.reduce((sum, p) => sum + p.cpu, 0);
+            const totalBrowserMem = browserProcs.reduce((sum, p) => sum + p.mem, 0);
+            // Browsers create ~2-3 OS processes per tab (renderer, GPU, extensions, etc.)
+            // So process count ≠ tab count — estimate actual tabs
+            const estimatedTabs = Math.max(1, Math.round(browserProcs.length / 2));
+
+            if (totalBrowserCpu > 20 || totalBrowserMem > 20) {
+                issues.push({
+                    type: 'browser_heavy',
+                    severity: totalBrowserCpu > 40 ? 'critical' : 'warning',
+                    message: `Browser is using ${totalBrowserCpu.toFixed(1)}% CPU and ${totalBrowserMem.toFixed(1)}% memory across ~${estimatedTabs} tabs (${browserProcs.length} internal processes)`,
+                    processes: browserProcs,
+                    estimatedTabs,
+                });
+            }
+        }
+
+        // ── Dev server detection ──
+        const devProcs = classifiedProcesses.filter(p => p.classification.isDev);
+        const highCpuDev = devProcs.filter(p => p.cpu >= THRESHOLDS.PROCESS_CPU_WARNING);
+
+        if (highCpuDev.length > 0) {
+            for (const devProc of highCpuDev) {
+                const isHotReload = (devProc.command || '').match(/--watch|hmr|hot|dev|vite|next/i);
+                const isPossibleLoop = devProc.cpu >= 80;
+
+                insights.push({
+                    type: 'dev_process_high_cpu',
+                    message: isPossibleLoop
+                        ? `🔄 "${devProc.name}" is using ${devProc.cpu}% CPU — possible infinite loop or expensive computation in your code`
+                        : isHotReload
+                            ? `🔄 "${devProc.name}" (${devProc.cpu}% CPU) — likely running with hot reload which can intensify CPU usage during rebuilds`
+                            : `🛠️ "${devProc.name}" is using ${devProc.cpu}% CPU during development`,
+                    process: devProc,
+                    severity: isPossibleLoop ? 'critical' : 'warning',
+                });
+            }
+        }
+
+        // ── Determine overall responsibility ──
+        let primaryCause = 'balanced';
+        if (cpuHogs.length === 1 && cpuHogs[0].cpu > 50) {
+            primaryCause = 'single_process';
+        } else if (cpuHogs.length > 1) {
+            primaryCause = 'multiple_processes';
+        } else if (smallProcs.length >= 5 && smallProcTotalCpu > 30) {
+            primaryCause = 'distributed';
+        }
+
+        return {
+            primaryCause,
+            responsibilities,
+            issues,
+            insights,
+            summary: {
+                cpuHogCount: cpuHogs.length,
+                memHogCount: memHogs.length,
+                totalProcesses: classifiedProcesses.length,
+                browserProcessCount: browserProcs.length,
+                devProcessCount: devProcs.length,
+            },
+        };
+    }
+}

package/src/analyzers/spike.detector.js

@@ -0,0 +1,135 @@
+// ─── Spike Detector ──────────────────────────────────────────────
+// Tracks system metrics over time to detect patterns and sustained issues
+import { THRESHOLDS } from '../utils/constants.js';
+
+export class SpikeDetector {
+    constructor() {
+        this.cpuHistory = [];
+        this.memHistory = [];
+        this.maxHistory = 60; // ~3 minutes at 3s intervals
+    }
+
+    /**
+     * Record a new data point and detect patterns
+     * @param {Object} cpuAnalysis - Current CPU analysis results
+     * @param {Object} memAnalysis - Current Memory analysis results
+     * @returns {Object} Pattern detection results
+     */
+    record(cpuAnalysis, memAnalysis) {
+        const now = Date.now();
+
+        this.cpuHistory.push({ value: cpuAnalysis.overall, time: now });
+        this.memHistory.push({ value: memAnalysis.usedPercent, time: now });
+
+        // Trim to max history size
+        if (this.cpuHistory.length > this.maxHistory) this.cpuHistory.shift();
+        if (this.memHistory.length > this.maxHistory) this.memHistory.shift();
+
+        return {
+            cpu: this._analyzeHistory(this.cpuHistory, 'CPU'),
+            memory: this._analyzeHistory(this.memHistory, 'Memory'),
+        };
+    }
+
+    /**
+     * Analyze a metric history for patterns
+     */
+    _analyzeHistory(history, label) {
+        if (history.length < 3) {
+            return { trend: 'insufficient_data', patterns: [] };
+        }
+
+        const patterns = [];
+        const values = history.map(h => h.value);
+        const recent = values.slice(-5);
+        const older = values.slice(-15, -5);
+
+        // ── Trend detection ──
+        const recentAvg = recent.reduce((s, v) => s + v, 0) / recent.length;
+        const olderAvg = older.length > 0
+            ? older.reduce((s, v) => s + v, 0) / older.length
+            : recentAvg;
+
+        let trend = 'stable';
+        if (recentAvg > olderAvg + 10) trend = 'rising';
+        else if (recentAvg < olderAvg - 10) trend = 'falling';
+
+        // ── Sustained high detection ──
+        const highThreshold = label === 'CPU' ? THRESHOLDS.CPU_HIGH : THRESHOLDS.MEMORY_HIGH;
+        const sustainedHigh = this._detectSustained(history, highThreshold);
+
+        if (sustainedHigh) {
+            patterns.push({
+                type: 'sustained_high',
+                message: `${label} has been above ${highThreshold}% for ${sustainedHigh.durationLabel}`,
+                duration: sustainedHigh.duration,
+                severity: sustainedHigh.duration > 120000 ? 'critical' : 'warning',
+            });
+        }
+
+        // ── Oscillation detection (usage bouncing up and down) ──
+        if (values.length >= 6) {
+            const diffs = [];
+            for (let i = 1; i < values.length; i++) {
+                diffs.push(values[i] - values[i - 1]);
+            }
+            const directionChanges = diffs.filter((d, i) =>
+                i > 0 && Math.sign(d) !== Math.sign(diffs[i - 1]) && Math.abs(d) > 5
+            ).length;
+
+            if (directionChanges >= 4) {
+                patterns.push({
+                    type: 'oscillating',
+                    message: `${label} usage is oscillating — frequently jumping up and down, possibly due to periodic tasks or unstable workloads`,
+                    severity: 'info',
+                });
+            }
+        }
+
+        return {
+            trend,
+            recentAvg: parseFloat(recentAvg.toFixed(1)),
+            patterns,
+        };
+    }
+
+    /**
+     * Detect sustained high usage
+     */
+    _detectSustained(history, threshold) {
+        if (history.length < 2) return null;
+
+        let startIdx = -1;
+        for (let i = history.length - 1; i >= 0; i--) {
+            if (history[i].value < threshold) {
+                startIdx = i + 1;
+                break;
+            }
+        }
+
+        if (startIdx === -1) startIdx = 0;
+        if (startIdx >= history.length) return null;
+
+        const duration = Date.now() - history[startIdx].time;
+        if (duration < 6000) return null; // Need at least 6 seconds
+
+        const seconds = Math.round(duration / 1000);
+        let durationLabel;
+        if (seconds < 60) durationLabel = `${seconds} seconds`;
+        else if (seconds < 3600) durationLabel = `${Math.round(seconds / 60)} minutes`;
+        else durationLabel = `${(seconds / 3600).toFixed(1)} hours`;
+
+        return { duration, durationLabel };
+    }
+
+    /**
+     * Get current pattern summary
+     */
+    getSummary() {
+        return {
+            dataPoints: this.cpuHistory.length,
+            cpuHistory: this.cpuHistory.map(h => h.value),
+            memHistory: this.memHistory.map(h => h.value),
+        };
+    }
+}

package/src/classifiers/process.classifier.js

@@ -0,0 +1,127 @@
+// ─── Process Classifier ─────────────────────────────────────────
+// Classifies processes into meaningful categories for human understanding
+import { PROCESS_CATEGORIES } from '../utils/constants.js';
+
+export class ProcessClassifier {
+    constructor() {
+        // Pre-compile patterns for fast matching
+        this.compiledPatterns = {};
+        for (const [key, category] of Object.entries(PROCESS_CATEGORIES)) {
+            if (key === 'UNKNOWN') continue;
+            this.compiledPatterns[key] = {
+                ...category,
+                regex: new RegExp(
+                    category.patterns.map(p => `(^|[/\\\\])${p}(\\d*|[-_.]|$)`).join('|'),
+                    'i'
+                ),
+            };
+        }
+    }
+
+    /**
+     * Classify a single process
+     * @param {Object} process - Process data { name, command, path }
+     * @returns {Object} Category info
+     */
+    classify(process) {
+        const searchStr = `${process.name} ${process.command || ''} ${process.path || ''}`.toLowerCase();
+
+        for (const [key, compiled] of Object.entries(this.compiledPatterns)) {
+            if (compiled.regex.test(searchStr)) {
+                return {
+                    category: key,
+                    label: compiled.label,
+                    color: compiled.color,
+                    isSystem: key === 'SYSTEM' || key === 'BACKGROUND',
+                    isDev: key === 'DEV_TOOLS' || key === 'EDITORS',
+                    isBrowser: key === 'BROWSER',
+                };
+            }
+        }
+
+        return {
+            category: 'UNKNOWN',
+            label: PROCESS_CATEGORIES.UNKNOWN.label,
+            color: PROCESS_CATEGORIES.UNKNOWN.color,
+            isSystem: false,
+            isDev: false,
+            isBrowser: false,
+        };
+    }
+
+    /**
+     * Classify all processes and return enriched list
+     * @param {Array} processes - Array of process objects
+     * @returns {Array} Processes with classification added
+     */
+    classifyAll(processes) {
+        return processes.map(proc => ({
+            ...proc,
+            classification: this.classify(proc),
+        }));
+    }
+
+    /**
+     * Group processes by category
+     * @param {Array} classifiedProcesses - Array of classified process objects
+     * @returns {Object} Processes grouped by category key
+     */
+    groupByCategory(classifiedProcesses) {
+        const groups = {};
+
+        for (const proc of classifiedProcesses) {
+            const cat = proc.classification.category;
+            if (!groups[cat]) {
+                groups[cat] = {
+                    ...PROCESS_CATEGORIES[cat],
+                    processes: [],
+                    totalCpu: 0,
+                    totalMem: 0,
+                };
+            }
+            groups[cat].processes.push(proc);
+            groups[cat].totalCpu += proc.cpu || 0;
+            groups[cat].totalMem += proc.mem || 0;
+        }
+
+        // Round totals
+        for (const group of Object.values(groups)) {
+            group.totalCpu = parseFloat(group.totalCpu.toFixed(1));
+            group.totalMem = parseFloat(group.totalMem.toFixed(1));
+        }
+
+        return groups;
+    }
+
+    /**
+     * Detect if there are development-related processes running
+     * @param {Array} classifiedProcesses
+     * @returns {Object} Dev environment summary
+     */
+    detectDevEnvironment(classifiedProcesses) {
+        const devProcs = classifiedProcesses.filter(p => p.classification.isDev);
+        const editorProcs = classifiedProcesses.filter(p => p.classification.category === 'EDITORS');
+
+        const hasNodeServer = devProcs.some(p =>
+            /node\b/.test(p.name) && (p.command || '').match(/server|dev|start|next|vite|webpack/)
+        );
+
+        const hasHotReload = devProcs.some(p =>
+            (p.command || '').match(/--watch|hmr|hot|dev/)
+        );
+
+        const hasTests = devProcs.some(p =>
+            (p.command || '').match(/jest|vitest|mocha|test|spec/)
+        );
+
+        return {
+            isDevActive: devProcs.length > 0,
+            devProcessCount: devProcs.length,
+            editorActive: editorProcs.length > 0,
+            hasNodeServer,
+            hasHotReload,
+            hasTests,
+            devProcesses: devProcs,
+        };
+    }
+}

package/src/collectors/cpu.collector.js

@@ -0,0 +1,48 @@
+// ─── CPU Data Collector ──────────────────────────────────────────
+import si from 'systeminformation';
+
+export class CpuCollector {
+    /**
+     * Collect comprehensive CPU data
+     * @returns {Object} CPU info + current load + temperature
+     */
+    async collect() {
+        const [cpuInfo, load, speed, temp] = await Promise.all([
+            si.cpu(),
+            si.currentLoad(),
+            si.cpuCurrentSpeed(),
+            si.cpuTemperature().catch(() => null),
+        ]);
+
+        return {
+            info: {
+                manufacturer: cpuInfo.manufacturer,
+                brand: cpuInfo.brand,
+                cores: cpuInfo.physicalCores,
+                threads: cpuInfo.cores,
+                speed: cpuInfo.speed,
+            },
+            load: {
+                overall: parseFloat(load.currentLoad?.toFixed(1) || 0),
+                user: parseFloat(load.currentLoadUser?.toFixed(1) || 0),
+                system: parseFloat(load.currentLoadSystem?.toFixed(1) || 0),
+                idle: parseFloat(load.currentLoadIdle?.toFixed(1) || 0),
+                perCore: (load.cpus || []).map((c, i) => ({
+                    core: i,
+                    load: parseFloat(c.load?.toFixed(1) || 0),
+                })),
+            },
+            speed: {
+                current: speed.avg,
+                min: speed.min,
+                max: speed.max,
+            },
+            temperature: temp ? {
+                main: temp.main,
+                max: temp.max,
+                cores: temp.cores,
+            } : null,
+            timestamp: Date.now(),
+        };
+    }
+}

package/src/collectors/disk.collector.js

@@ -0,0 +1,41 @@
+// ─── Disk Data Collector ─────────────────────────────────────────
+import si from 'systeminformation';
+import { formatBytes, percentage } from '../utils/helpers.js';
+
+export class DiskCollector {
+    /**
+     * Collect disk usage and I/O data
+     * @returns {Object} Filesystem usage + disk I/O
+     */
+    async collect() {
+        const [fsSize, fsStats] = await Promise.all([
+            si.fsSize(),
+            si.disksIO().catch(() => null),
+        ]);
+
+        const filesystems = fsSize.map(fs => ({
+            mount: fs.mount,
+            type: fs.type,
+            size: fs.size,
+            used: fs.used,
+            available: fs.available,
+            usedPercent: parseFloat(fs.use?.toFixed(1) || 0),
+            formatted: {
+                size: formatBytes(fs.size),
+                used: formatBytes(fs.used),
+                available: formatBytes(fs.available),
+            },
+        }));
+
+        return {
+            filesystems,
+            io: fsStats ? {
+                readPerSecond: fsStats.rIO_sec || 0,
+                writePerSecond: fsStats.wIO_sec || 0,
+                totalReadBytes: fsStats.rIO || 0,
+                totalWriteBytes: fsStats.wIO || 0,
+            } : null,
+            timestamp: Date.now(),
+        };
+    }
+}

package/src/collectors/memory.collector.js

@@ -0,0 +1,41 @@
+// ─── Memory Data Collector ───────────────────────────────────────
+import si from 'systeminformation';
+import { formatBytes, percentage } from '../utils/helpers.js';
+
+export class MemoryCollector {
+    /**
+     * Collect comprehensive memory data
+     * @returns {Object} RAM + swap info
+     */
+    async collect() {
+        const mem = await si.mem();
+
+        return {
+            ram: {
+                total: mem.total,
+                used: mem.used,
+                free: mem.free,
+                active: mem.active,
+                available: mem.available,
+                usedPercent: percentage(mem.active, mem.total),
+                formatted: {
+                    total: formatBytes(mem.total),
+                    used: formatBytes(mem.active),
+                    free: formatBytes(mem.available),
+                },
+            },
+            swap: {
+                total: mem.swaptotal,
+                used: mem.swapused,
+                free: mem.swapfree,
+                usedPercent: mem.swaptotal > 0 ? percentage(mem.swapused, mem.swaptotal) : 0,
+                formatted: {
+                    total: formatBytes(mem.swaptotal),
+                    used: formatBytes(mem.swapused),
+                    free: formatBytes(mem.swapfree),
+                },
+            },
+            timestamp: Date.now(),
+        };
+    }
+}