letfixit 0.1.0

package/server/analysis_engine.js

@@ -0,0 +1,222 @@
+const { v4: uuidv4 } = require('uuid');
+
+const THRESHOLDS = {
+  flutter: {
+    jank_ms: 16.6,
+    rebuild_per_second: 10,
+    api_limit_bytes: 512000,
+    memory_growth_mb: 5,
+    memory_growth_window_ms: 10000,
+    error_repeat_count: 3,
+    error_repeat_window_ms: 60000,
+    state_overnotify_per_second: 20,
+  },
+  android: {
+    jank_ms: 16.6,
+    anr_ms: 5000,
+    overdraw_per_second: 15,
+    api_limit_bytes: 512000,
+    crash_pattern_count: 2,
+    memory_leak_window_ms: 30000,
+  },
+};
+
+class AnalysisEngine {
+  constructor() {
+    this._rebuildCounts = new Map();
+    this._errorCounts = new Map();
+    this._stateCounts = new Map();
+    this._overdrawCounts = new Map();
+    this._memoryHistory = [];
+    this._androidMemoryHistory = [];
+    this._androidCrashCounts = new Map();
+    this._lastSecondFlush = Date.now();
+  }
+
+  processEvent(event) {
+    this._maybeFlushPerSecondCounters();
+
+    const p = event.platform;
+    if (p === 'flutter') return this._analyzeFlutter(event);
+    if (p === 'android') return this._analyzeAndroid(event);
+    return null;
+  }
+
+  _analyzeFlutter(e) {
+    if (e.event === 'frame') {
+      const ms = e.metric.value;
+      if (ms > THRESHOLDS.flutter.jank_ms) {
+        return this._finding('flutter', 'jank_detected', ms > 33 ? 'critical' : 'high', e,
+          'Jank detected: frame build+layout+paint exceeded 16.6ms budget',
+          `Frame took ${ms}ms (${(ms - 16.6).toFixed(1)}ms over budget). Build: ${e.metric.build}ms, Layout: ${e.metric.layout}ms, Paint: ${e.metric.paint}ms. This causes dropped frames visible to users.`);
+      }
+    }
+
+    if (e.event === 'rebuild') {
+      const widget = e.widget || 'Unknown';
+      const count = (this._rebuildCounts.get(widget) || 0) + 1;
+      this._rebuildCounts.set(widget, count);
+      if (count > THRESHOLDS.flutter.rebuild_per_second) {
+        return this._finding('flutter', 'rebuild_storm', 'high', e,
+          `Rebuild storm: ${widget} rebuilt ${count} times per second`,
+          `Widget "${widget}" is rebuilding excessively (${count}x/s, budget: 10/s). Common causes: missing const constructors, setState called too high in the tree, or unoptimized ChangeNotifier.`);
+      }
+    }
+
+    if (e.event === 'api') {
+      const bytes = e.metric.value;
+      if (bytes > THRESHOLDS.flutter.api_limit_bytes) {
+        const kb = (bytes / 1024).toFixed(1);
+        return this._finding('flutter', 'api_bloat', 'high', e,
+          `API bloat: ${e.metric.url || 'endpoint'} returned ${kb}KB payload`,
+          `Response payload of ${kb}KB exceeds 500KB budget. Large payloads block the main thread during JSON parsing and inflate memory usage.`);
+      }
+    }
+
+    if (e.event === 'memory') {
+      const now = Date.now();
+      this._memoryHistory.push({ ts: now, value: e.metric.value });
+      this._memoryHistory = this._memoryHistory.filter(
+        (x) => now - x.ts <= THRESHOLDS.flutter.memory_growth_window_ms
+      );
+      if (this._memoryHistory.length >= 2) {
+        const oldest = this._memoryHistory[0];
+        const newest = this._memoryHistory[this._memoryHistory.length - 1];
+        const growthMb = (newest.value - oldest.value) / (1024 * 1024);
+        if (growthMb > THRESHOLDS.flutter.memory_growth_mb) {
+          return this._finding('flutter', 'memory_growth', 'high', e,
+            `Memory growth: heap grew ${growthMb.toFixed(1)}MB in 10 seconds`,
+            `Heap increased by ${growthMb.toFixed(1)}MB over 10s (budget: 5MB). Check for retained widget trees, unclosed streams, or image cache bloat.`);
+        }
+      }
+    }
+
+    if (e.event === 'error') {
+      const key = e.metric.message || e.widget || 'unknown';
+      const entry = this._errorCounts.get(key) || { count: 0, first: Date.now() };
+      entry.count += 1;
+      this._errorCounts.set(key, entry);
+      const windowAge = Date.now() - entry.first;
+      if (entry.count > THRESHOLDS.flutter.error_repeat_count && windowAge <= THRESHOLDS.flutter.error_repeat_window_ms) {
+        return this._finding('flutter', 'error_repeat', 'critical', e,
+          `Recurring error: "${key}" seen ${entry.count} times in 60s`,
+          `Exception "${key}" is repeating (${entry.count} times, budget: 3/min). This likely indicates an unhandled async error or a broken state machine.`);
+      }
+    }
+
+    if (e.event === 'state') {
+      const key = e.widget || 'global';
+      const count = (this._stateCounts.get(key) || 0) + 1;
+      this._stateCounts.set(key, count);
+      if (count > THRESHOLDS.flutter.state_overnotify_per_second) {
+        return this._finding('flutter', 'state_overnotify', 'high', e,
+          `State overnotify: ${key} fired ${count} state events/second`,
+          `Provider/ChangeNotifier "${key}" is notifying listeners ${count} times per second (budget: 20/s). Use select() or Selector to limit rebuilds to relevant state slices.`);
+      }
+    }
+
+    return null;
+  }
+
+  _analyzeAndroid(e) {
+    if (e.event === 'frame') {
+      const ms = e.metric.value;
+      if (ms > THRESHOLDS.android.jank_ms) {
+        return this._finding('android', 'jank_detected', ms > 33 ? 'critical' : 'high', e,
+          `Jank detected: Choreographer frame took ${ms}ms`,
+          `Frame duration ${ms}ms exceeds 16.6ms budget (${(ms - 16.6).toFixed(1)}ms over). Check for expensive work on the main thread: measure, layout, or draw calls in onDraw().`);
+      }
+      if (ms > THRESHOLDS.android.anr_ms) {
+        return this._finding('android', 'anr_risk', 'critical', e,
+          `ANR risk: main thread blocked for ${ms}ms`,
+          `Main thread blocked ${ms}ms (budget: 5000ms). ANR dialog will appear. Move disk I/O, network calls, or heavy computation to a background coroutine or thread.`);
+      }
+    }
+
+    if (e.event === 'frame' && e.widget) {
+      const view = e.widget;
+      const count = (this._overdrawCounts.get(view) || 0) + 1;
+      this._overdrawCounts.set(view, count);
+      if (count > THRESHOLDS.android.overdraw_per_second) {
+        return this._finding('android', 'overdraw', 'medium', e,
+          `Overdraw: view "${view}" invalidated ${count} times/second`,
+          `View "${view}" is being invalidated ${count} times/second (budget: 15/s). Use hardware layers or consolidate invalidation calls to reduce GPU overdraw.`);
+      }
+    }
+
+    if (e.event === 'memory') {
+      const now = Date.now();
+      this._androidMemoryHistory.push({ ts: now, value: e.metric.value });
+      this._androidMemoryHistory = this._androidMemoryHistory.filter(
+        (x) => now - x.ts <= THRESHOLDS.android.memory_leak_window_ms
+      );
+      if (this._androidMemoryHistory.length >= 3) {
+        const isGrowing = this._androidMemoryHistory.every(
+          (x, i, arr) => i === 0 || x.value >= arr[i - 1].value
+        );
+        if (isGrowing) {
+          const first = this._androidMemoryHistory[0];
+          const last = this._androidMemoryHistory[this._androidMemoryHistory.length - 1];
+          // Memory events carry PSS in BYTES (aligned with the Flutter path and the
+          // dashboard), so convert to MB before comparing against the 5MB budget.
+          const growthMb = (last.value - first.value) / (1024 * 1024);
+          if (growthMb > 5) {
+            return this._finding('android', 'memory_leak', 'critical', e,
+              `Memory leak: heap grew continuously for 30 seconds (+${growthMb.toFixed(1)}MB)`,
+              `PSS heap has grown monotonically by ${growthMb.toFixed(1)}MB over 30s. Check for Activity/Context leaks, unclosed cursors, or static references to views.`);
+          }
+        }
+      }
+    }
+
+    if (e.event === 'api') {
+      const bytes = e.metric.value;
+      if (bytes > THRESHOLDS.android.api_limit_bytes) {
+        const kb = (bytes / 1024).toFixed(1);
+        return this._finding('android', 'api_bloat', 'high', e,
+          `API bloat: ${e.metric.url || 'endpoint'} returned ${kb}KB`,
+          `Response payload ${kb}KB exceeds 500KB budget. Large JSON responses block Gson/Moshi parsing on the calling thread and inflate heap usage.`);
+      }
+    }
+
+    if (e.event === 'error') {
+      const key = e.widget || e.metric.message || 'unknown';
+      const count = (this._androidCrashCounts.get(key) || 0) + 1;
+      this._androidCrashCounts.set(key, count);
+      if (count > THRESHOLDS.android.crash_pattern_count) {
+        return this._finding('android', 'crash_pattern', 'critical', e,
+          `Crash pattern: "${key}" crashed ${count} times this session`,
+          `Exception type "${key}" has occurred ${count} times (budget: 2/session). Add a try/catch with proper error reporting, or fix the underlying null-safety or state issue.`);
+      }
+    }
+
+    return null;
+  }
+
+  _finding(platform, rule, severity, event, title, hypothesis) {
+    return {
+      id: uuidv4(),
+      platform,
+      rule,
+      severity,
+      widget: event.widget || null,
+      title,
+      metric: event.metric,
+      hypothesis,
+      timestamp: Date.now(),
+      aiSuggestion: null,
+    };
+  }
+
+  _maybeFlushPerSecondCounters() {
+    const now = Date.now();
+    if (now - this._lastSecondFlush >= 1000) {
+      this._rebuildCounts.clear();
+      this._stateCounts.clear();
+      this._overdrawCounts.clear();
+      this._lastSecondFlush = now;
+    }
+  }
+}
+
+module.exports = new AnalysisEngine();

package/server/android_bridge.js

@@ -0,0 +1,124 @@
+const { WebSocketServer } = require('ws');
+const { EventEmitter } = require('events');
+
+const ANDROID_PORT = 7001;
+
+class AndroidBridge extends EventEmitter {
+  constructor() {
+    super();
+    this._wss = null;
+  }
+
+  start() {
+    this._wss = new WebSocketServer({ port: ANDROID_PORT });
+
+    this._wss.on('listening', () => {
+      console.log(`  🤖 Android bridge listening on ws://localhost:${ANDROID_PORT}`);
+    });
+
+    this._wss.on('connection', (ws) => {
+      console.log('  ✅ Android SDK connected');
+      this.emit('status', { connected: true });
+      ws.on('message', (raw) => {
+        try {
+          const data = JSON.parse(raw);
+          const normalized = this._normalize(data);
+          if (normalized) this.emit('event', normalized);
+        } catch (_) {}
+      });
+      ws.on('close', () => {
+        console.log('  ⚠️  Android SDK disconnected');
+        this.emit('status', { connected: false });
+      });
+    });
+
+    this._wss.on('error', (err) => {
+      console.error('  ❌ Android bridge error:', err.message);
+    });
+  }
+
+  _normalize(data) {
+    const type = data.type || data.event;
+
+    if (type === 'frame') {
+      return {
+        platform: 'android',
+        event: 'frame',
+        timestamp: data.timestamp || Date.now(),
+        severity: data.durationMs > 33 ? 'critical' : data.durationMs > 16.6 ? 'high' : 'low',
+        widget: data.view || null,
+        metric: {
+          value: data.durationMs,
+          unit: 'ms',
+          budget: 16.6,
+          exceededBy: data.durationMs > 16.6 ? parseFloat((data.durationMs - 16.6).toFixed(2)) : 0,
+        },
+        context: { device: data.device, osVersion: data.osVersion },
+        raw: data,
+      };
+    }
+
+    if (type === 'memory') {
+      return {
+        platform: 'android',
+        event: 'memory',
+        timestamp: data.timestamp || Date.now(),
+        severity: data.totalPss > 300000 ? 'high' : 'low',
+        widget: null,
+        metric: {
+          // Emit bytes to match the Flutter path, the dashboard, and the engine's
+          // MB-based leak rule. Incoming totalPss is in KB.
+          value: (data.totalPss || 0) * 1024,
+          unit: 'bytes',
+          dalvikHeap: data.dalvikHeap,
+          nativeHeap: data.nativeHeap,
+        },
+        context: {},
+        raw: data,
+      };
+    }
+
+    if (type === 'api') {
+      return {
+        platform: 'android',
+        event: 'api',
+        timestamp: data.timestamp || Date.now(),
+        severity: data.responseBodySize > 512000 ? 'high' : data.durationMs > 500 ? 'medium' : 'low',
+        widget: null,
+        metric: {
+          value: data.responseBodySize,
+          unit: 'bytes',
+          durationMs: data.durationMs,
+          budget: 512000,
+          exceededBy: data.responseBodySize > 512000 ? data.responseBodySize - 512000 : 0,
+          url: data.url,
+          method: data.method,
+        },
+        context: {},
+        raw: data,
+      };
+    }
+
+    if (type === 'error') {
+      return {
+        platform: 'android',
+        event: 'error',
+        timestamp: data.timestamp || Date.now(),
+        severity: data.fatal ? 'critical' : 'high',
+        widget: data.className || null,
+        metric: {
+          value: 1,
+          unit: 'occurrence',
+          message: data.message,
+          stackTrace: data.stackTrace,
+        },
+        context: {},
+        raw: data,
+      };
+    }
+
+    return null;
+  }
+}
+
+module.exports = new AndroidBridge();

package/server/android_live.js

@@ -0,0 +1,167 @@
+// ── Android native live monitor (over adb) ───────────────────────────────────
+// The Android equivalent of the Flutter VM-Service dashboard: attach to a
+// running debuggable app over adb and STREAM live metrics to the dashboard —
+// no in-app SDK required. Emits the same normalized `event` objects the Flutter
+// bridge does (platform:'android'), so the existing dashboard panels light up.
+//
+//   • frames  — poll `dumpsys gfxinfo <pkg> framestats` (real per-frame timings)
+//   • memory  — poll `dumpsys meminfo <pkg>` (TOTAL PSS)
+//   • errors  — tail `logcat --pid=<pid> *:E` (crashes / exceptions)
+const { spawn } = require('child_process');
+const { EventEmitter } = require('events');
+const adb = require('./adb_bridge');
+
+const FRAME_POLL_MS = 1000;
+const MEM_POLL_MS = 2000;
+
+class AndroidLive extends EventEmitter {
+  constructor() {
+    super();
+    this._reset();
+  }
+
+  _reset() {
+    this._serial = null;
+    this._pkg = null;
+    this._connected = false;
+    this._lastVsync = 0;
+    this._pid = null;
+    this._frameTimer = null;
+    this._memTimer = null;
+    this._logcat = null;
+    this._recentErrors = [];
+  }
+
+  get isConnected() { return this._connected; }
+
+  async start(serial, pkg) {
+    this.stop();
+    this._reset();
+    this._serial = serial;
+    this._pkg = pkg;
+    this._connected = true;
+    this.emit('status', { connected: true, pkg, serial });
+    console.log(`  📡 Android live monitor attached to ${pkg} (${serial}) — streaming frames/memory/errors`);
+
+    // Establish a fresh frame-stats baseline so we don't replay old frames.
+    await adb.resetGfx(serial, pkg).catch(() => {});
+    await this._ensureLogcat();
+
+    this._frameTimer = setInterval(() => this._pollFrames().catch(() => {}), FRAME_POLL_MS);
+    this._memTimer   = setInterval(() => this._pollMemory().catch(() => {}), MEM_POLL_MS);
+    this._frameTimer.unref?.();
+    this._memTimer.unref?.();
+  }
+
+  stop() {
+    if (this._frameTimer) clearInterval(this._frameTimer);
+    if (this._memTimer) clearInterval(this._memTimer);
+    if (this._logcat) { try { this._logcat.kill(); } catch (_) {} }
+    if (this._connected) this.emit('status', { connected: false });
+    this._reset();
+  }
+
+  // ── Frames ──────────────────────────────────────────────────────────────────
+  async _pollFrames() {
+    if (!this._connected) return;
+    const out = await adb.shell(this._serial, ['dumpsys', 'gfxinfo', this._pkg, 'framestats']).catch(() => '');
+    if (!out) return;
+    const frames = adb.parseFramestats(out);
+    for (const f of frames) {
+      if (f.intendedVsync <= this._lastVsync) continue; // already emitted
+      this._lastVsync = f.intendedVsync;
+      const totalMs = f.totalMs;
+      this.emit('event', {
+        platform: 'android',
+        event: 'frame',
+        timestamp: Date.now(),
+        severity: totalMs > 33 ? 'critical' : totalMs > 16.6 ? 'high' : 'low',
+        widget: null,
+        metric: {
+          value: totalMs, unit: 'ms',
+          fps: totalMs > 0 ? Math.min(60, Math.round(1000 / totalMs)) : 60,
+          budget: 16.6,
+          exceededBy: totalMs > 16.6 ? parseFloat((totalMs - 16.6).toFixed(2)) : 0,
+          build: f.buildMs, raster: f.rasterMs,
+        },
+        context: {},
+      });
+    }
+  }
+
+  // ── Memory (bytes, to match the Flutter path + dashboard) ─────────────────────
+  async _pollMemory() {
+    if (!this._connected) return;
+    const out = await adb.shell(this._serial, ['dumpsys', 'meminfo', this._pkg]).catch(() => '');
+    if (!out) return;
+    const { pssMb } = adb.parseMeminfo(out);
+    if (pssMb == null) return;
+    this.emit('event', {
+      platform: 'android',
+      event: 'memory',
+      timestamp: Date.now(),
+      severity: 'low',
+      widget: null,
+      metric: { value: Math.round(pssMb * 1024 * 1024), unit: 'bytes', pssMb },
+      context: {},
+    });
+  }
+
+  // ── Errors (logcat) ───────────────────────────────────────────────────────────
+  async _ensureLogcat() {
+    if (this._logcat) return;
+    this._pid = await adb.pidOf(this._serial, this._pkg);
+    // Clear the backlog so we only stream errors from now on.
+    await adb.shell(this._serial, ['logcat', '-c']).catch(() => {});
+
+    // Prefer per-pid filtering when the app is running; else error-level for all.
+    const args = [...adb.target(this._serial), 'logcat', '-v', 'brief'];
+    if (this._pid) args.push(`--pid=${this._pid}`);
+    args.push('*:E');
+
+    const proc = spawn(adb.ADB, args, { stdio: ['ignore', 'pipe', 'ignore'] });
+    this._logcat = proc;
+    let buf = '';
+    proc.stdout.on('data', (chunk) => {
+      buf += chunk.toString();
+      const lines = buf.split('\n');
+      buf = lines.pop();
+      for (const line of lines) this._handleLogLine(line);
+    });
+    proc.on('error', () => { this._logcat = null; });
+    proc.on('exit', () => { this._logcat = null; });
+
+    // If the app wasn't running yet, retry pid + reattach shortly.
+    if (!this._pid) setTimeout(() => { if (this._connected) { this._logcat && this._logcat.kill(); this._logcat = null; this._ensureLogcat(); } }, 4000);
+  }
+
+  _handleLogLine(raw) {
+    const line = raw.trim();
+    if (!line || /^-+ beginning of/.test(line)) return;
+    // "E/AndroidRuntime( 1234): FATAL EXCEPTION: main"  → strip tag/pid prefix.
+    const m = line.match(/^[VDIWEF]\/([^(]+)\(\s*\d+\):\s*(.*)$/);
+    const tag = m ? m[1].trim() : null;
+    const msg = (m ? m[2] : line).trim();
+    if (!msg) return;
+
+    const fatal = /FATAL EXCEPTION|ANR in|has died|FATAL SIGNAL/i.test(line) || tag === 'AndroidRuntime';
+    // Dedup identical messages within a short window.
+    const now = Date.now();
+    this._recentErrors = this._recentErrors.filter((e) => now - e.ts < 3000);
+    if (this._recentErrors.some((e) => e.msg === msg)) return;
+    this._recentErrors.push({ msg, ts: now });
+
+    this.emit('event', {
+      platform: 'android',
+      event: 'error',
+      timestamp: now,
+      severity: fatal ? 'critical' : 'high',
+      widget: tag,
+      title: msg.length > 120 ? msg.slice(0, 117) + '…' : msg,
+      metric: { message: msg, unit: 'error' },
+      context: {},
+    });
+  }
+}
+
+module.exports = new AndroidLive();