@howlil/ez-agents 3.5.0 → 4.0.0

package/bin/lib/perf/db-optimizer.cjs

@@ -0,0 +1,78 @@
+/**
+ * DB Optimizer — Query analysis and index recommendations
+ * Analyzes slow queries, suggests indexes, detects N+1 patterns
+ */
+
+const { execSync } = require('child_process');
+
+class DbOptimizer {
+  constructor(dbUrl) {
+    this.dbUrl = dbUrl;
+  }
+
+  /**
+   * Analyze queries and provide optimization recommendations
+   * @param {string} dbUrl - Database connection URL
+   * @param {Array} queries - Array of queries to analyze
+   * @returns {Array} Analysis results with suggestions
+   */
+  async analyzeQueries(dbUrl, queries) {
+    const results = [];
+
+    for (const query of queries) {
+      const explain = await this.explainQuery(dbUrl, query);
+      const suggestions = [];
+
+      // Detect sequential scans
+      if (explain.scanType === 'Seq Scan' || explain.scanType === 'Sequential Scan') {
+        suggestions.push({
+          type: 'index',
+          reason: 'Sequential scan detected',
+          recommendation: `CREATE INDEX ON ${explain.table} (${explain.filterColumn || 'column'})`
+        });
+      }
+
+      // Detect N+1 patterns
+      if (explain.nestedLoops > 5) {
+        suggestions.push({
+          type: 'n-plus-one',
+          reason: 'N+1 query pattern detected',
+          recommendation: 'Use JOIN or batch loading'
+        });
+      }
+
+      results.push({ query, explain, suggestions });
+    }
+
+    return results;
+  }
+
+  /**
+   * Get EXPLAIN plan for a query
+   * @param {string} dbUrl - Database connection URL
+   * @param {string} query - Query to explain
+   * @returns {Object} Explain plan
+   */
+  async explainQuery(dbUrl, query) {
+    // Placeholder - would execute EXPLAIN QUERY in real implementation
+    return {
+      scanType: 'Unknown',
+      table: 'unknown',
+      filterColumn: null,
+      nestedLoops: 0
+    };
+  }
+}
+
+/**
+ * Analyze queries and provide optimization recommendations
+ * @param {string} dbUrl - Database connection URL
+ * @param {Array} queries - Array of queries to analyze
+ * @returns {Array} Analysis results with suggestions
+ */
+async function analyzeQueries(dbUrl, queries) {
+  const optimizer = new DbOptimizer(dbUrl);
+  return optimizer.analyzeQueries(dbUrl, queries);
+}
+
+module.exports = { DbOptimizer, analyzeQueries };

package/bin/lib/perf/frontend-performance.cjs

@@ -0,0 +1,56 @@
+/**
+ * Frontend Performance — Lighthouse integration for bundle/render analysis
+ * Measures Core Web Vitals: FCP, LCP, CLS, TTI
+ */
+
+class FrontendPerformance {
+  constructor() {
+    this.lighthouse = null;
+    this.chromeLauncher = null;
+  }
+
+  /**
+   * Run Lighthouse analysis on a URL
+   * @param {string} url - URL to analyze
+   * @returns {Object} Lighthouse results
+   */
+  async runLighthouse(url) {
+    // Placeholder - would run actual Lighthouse in real implementation
+    // Requires: npm install lighthouse chrome-launcher
+    return {
+      performance: 0,
+      metrics: {
+        fcp: 0,
+        lcp: 0,
+        cls: 0,
+        tti: 0
+      },
+      opportunities: []
+    };
+  }
+
+  /**
+   * Analyze bundle size
+   * @param {string} buildPath - Path to build directory
+   * @returns {Object} Bundle analysis
+   */
+  async analyzeBundle(buildPath) {
+    // Placeholder - would use webpack-bundle-analyzer in real implementation
+    return {
+      totalSize: 0,
+      chunks: []
+    };
+  }
+}
+
+/**
+ * Run Lighthouse analysis on a URL
+ * @param {string} url - URL to analyze
+ * @returns {Object} Lighthouse results
+ */
+async function runLighthouse(url) {
+  const perf = new FrontendPerformance();
+  return perf.runLighthouse(url);
+}
+
+module.exports = { FrontendPerformance, runLighthouse };

package/bin/lib/perf/perf-analyzer.cjs

@@ -0,0 +1,77 @@
+/**
+ * Perf Analyzer — Core performance analysis coordinator
+ * Orchestrates all analyzers and aggregates results
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+class PerfAnalyzer {
+  constructor(cwd) {
+    this.cwd = cwd || process.cwd();
+  }
+
+  /**
+   * Run all performance analyzers and aggregate results
+   * @param {Object} options - Analysis options
+   * @returns {Object} Aggregated performance results
+   */
+  async analyze(options = {}) {
+    const results = {
+      timestamp: new Date().toISOString(),
+      db: null,
+      frontend: null,
+      api: null,
+      errors: []
+    };
+
+    try {
+      // Run DB analysis if DB URL provided
+      if (options.dbUrl) {
+        const { analyzeQueries } = require('./db-optimizer.cjs');
+        results.db = await analyzeQueries(options.dbUrl, options.queries || []);
+      }
+    } catch (e) {
+      results.errors.push(`DB analysis failed: ${e.message}`);
+    }
+
+    try {
+      // Run frontend analysis if URL provided
+      if (options.url) {
+        const { runLighthouse } = require('./frontend-performance.cjs');
+        results.frontend = await runLighthouse(options.url);
+      }
+    } catch (e) {
+      results.errors.push(`Frontend analysis failed: ${e.message}`);
+    }
+
+    try {
+      // Run API analysis if API URL provided
+      if (options.apiUrl) {
+        const { trackEndpoint } = require('./api-monitor.cjs');
+        results.api = await trackEndpoint(options.apiUrl, options.endpoints || []);
+      }
+    } catch (e) {
+      results.errors.push(`API analysis failed: ${e.message}`);
+    }
+
+    return results;
+  }
+
+  /**
+   * Aggregate results from multiple analyzers
+   * @param {Array} results - Array of analysis results
+   * @returns {Object} Aggregated results
+   */
+  aggregate(results) {
+    return results.reduce((acc, r) => {
+      if (r.db) acc.db.push(r.db);
+      if (r.frontend) acc.frontend.push(r.frontend);
+      if (r.api) acc.api.push(r.api);
+      acc.errors.push(...(r.errors || []));
+      return acc;
+    }, { db: [], frontend: [], api: [], errors: [] });
+  }
+}
+
+module.exports = { PerfAnalyzer, analyze: PerfAnalyzer.prototype.analyze };

package/bin/lib/perf/perf-baseline.cjs

@@ -0,0 +1,102 @@
+/**
+ * Perf Baseline — Save and load performance baselines
+ * Stores baselines in .planning/perf-baselines/
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+class PerfBaseline {
+  constructor(cwd) {
+    this.cwd = cwd || process.cwd();
+    this.baselinesDir = path.join(this.cwd, '.planning', 'perf-baselines');
+  }
+
+  /**
+   * Save baseline metrics
+   * @param {Object} metrics - Metrics to save
+   * @param {string} name - Baseline name
+   * @returns {string} Path to saved baseline
+   */
+  saveBaseline(metrics, name = 'default') {
+    // Ensure directory exists
+    if (!fs.existsSync(this.baselinesDir)) {
+      fs.mkdirSync(this.baselinesDir, { recursive: true });
+    }
+
+    const baselinePath = path.join(this.baselinesDir, `${name}.json`);
+    const baseline = {
+      ...metrics,
+      metadata: {
+        name,
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString()
+      }
+    };
+
+    fs.writeFileSync(baselinePath, JSON.stringify(baseline, null, 2), 'utf8');
+    return baselinePath;
+  }
+
+  /**
+   * Load baseline metrics
+   * @param {string} name - Baseline name
+   * @returns {Object|null} Baseline metrics or null
+   */
+  loadBaseline(name = 'default') {
+    const baselinePath = path.join(this.baselinesDir, `${name}.json`);
+
+    if (!fs.existsSync(baselinePath)) return null;
+
+    return JSON.parse(fs.readFileSync(baselinePath, 'utf8'));
+  }
+
+  /**
+   * List all available baselines
+   * @returns {Array} Array of baseline names
+   */
+  listBaselines() {
+    if (!fs.existsSync(this.baselinesDir)) return [];
+
+    return fs.readdirSync(this.baselinesDir)
+      .filter(f => f.endsWith('.json'))
+      .map(f => f.replace('.json', ''));
+  }
+
+  /**
+   * Delete a baseline
+   * @param {string} name - Baseline name
+   * @returns {boolean} Success
+   */
+  deleteBaseline(name) {
+    const baselinePath = path.join(this.baselinesDir, `${name}.json`);
+
+    if (!fs.existsSync(baselinePath)) return false;
+
+    fs.unlinkSync(baselinePath);
+    return true;
+  }
+}
+
+/**
+ * Save baseline metrics
+ * @param {Object} metrics - Metrics to save
+ * @param {string} name - Baseline name
+ * @returns {string} Path to saved baseline
+ */
+function saveBaseline(metrics, name = 'default') {
+  const baseline = new PerfBaseline();
+  return baseline.saveBaseline(metrics, name);
+}
+
+/**
+ * Load baseline metrics
+ * @param {string} name - Baseline name
+ * @returns {Object|null} Baseline metrics or null
+ */
+function loadBaseline(name = 'default') {
+  const baseline = new PerfBaseline();
+  return baseline.loadBaseline(name);
+}
+
+module.exports = { PerfBaseline, saveBaseline, loadBaseline };

package/bin/lib/perf/perf-reporter.cjs

@@ -0,0 +1,117 @@
+/**
+ * Perf Reporter — Performance report generation
+ * Generates structured reports (temp directory)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+class PerfReporter {
+  constructor(cwd) {
+    this.cwd = cwd || process.cwd();
+  }
+
+  /**
+   * Generate structured performance report
+   * @param {Object} results - Analysis results from PerfAnalyzer
+   * @returns {Object} Structured report
+   */
+  generateReport(results) {
+    return {
+      timestamp: results.timestamp || new Date().toISOString(),
+      summary: {
+        dbIssues: results.db?.suggestions?.length || 0,
+        frontendScore: results.frontend?.performance || 0,
+        apiLatency: results.api ? this.calculateAvgLatency(results.api) : 0
+      },
+      details: {
+        db: results.db || null,
+        frontend: results.frontend || null,
+        api: results.api || null
+      },
+      errors: results.errors || [],
+      recommendations: this.generateRecommendations(results)
+    };
+  }
+
+  /**
+   * Save report to temp directory
+   * @param {Object} report - Report to save
+   * @param {string} filename - Optional filename
+   * @returns {string} Path to saved report
+   */
+  saveReport(report, filename) {
+    const logsDir = path.join(process.env.TEMP || process.env.TMPDIR || '/tmp', 'ez-agents-perf');
+    if (!fs.existsSync(logsDir)) {
+      fs.mkdirSync(logsDir, { recursive: true });
+    }
+
+    const reportFilename = filename || `perf-${Date.now()}.json`;
+    const reportPath = path.join(logsDir, reportFilename);
+
+    fs.writeFileSync(reportPath, JSON.stringify(report, null, 2), 'utf8');
+    return reportPath;
+  }
+
+  /**
+   * Calculate average latency from API results
+   * @param {Array} apiResults - API latency results
+   * @returns {number} Average latency
+   */
+  calculateAvgLatency(apiResults) {
+    if (!apiResults || apiResults.length === 0) return 0;
+    const valid = apiResults.filter(r => r.latency > 0);
+    if (valid.length === 0) return 0;
+    return Math.round(valid.reduce((sum, r) => sum + r.latency, 0) / valid.length);
+  }
+
+  /**
+   * Generate recommendations from analysis results
+   * @param {Object} results - Analysis results
+   * @returns {Array} Recommendations
+   */
+  generateRecommendations(results) {
+    const recommendations = [];
+
+    if (results.db?.suggestions?.length > 0) {
+      recommendations.push({
+        category: 'database',
+        priority: 'high',
+        suggestion: `Address ${results.db.suggestions.length} query optimization opportunities`
+      });
+    }
+
+    if (results.frontend?.performance < 50) {
+      recommendations.push({
+        category: 'frontend',
+        priority: 'critical',
+        suggestion: 'Frontend performance score is low - optimize bundle size and Core Web Vitals'
+      });
+    }
+
+    return recommendations;
+  }
+}
+
+/**
+ * Generate structured performance report
+ * @param {Object} results - Analysis results from PerfAnalyzer
+ * @returns {Object} Structured report
+ */
+function generateReport(results) {
+  const reporter = new PerfReporter();
+  return reporter.generateReport(results);
+}
+
+/**
+ * Save report to temp directory
+ * @param {Object} report - Report to save
+ * @param {string} filename - Optional filename
+ * @returns {string} Path to saved report
+ */
+function saveReport(report, filename) {
+  const reporter = new PerfReporter();
+  return reporter.saveReport(report, filename);
+}
+
+module.exports = { PerfReporter, generateReport, saveReport };

package/bin/lib/perf/regression-detector.cjs

@@ -0,0 +1,92 @@
+/**
+ * Regression Detector — Baseline comparison and regression flagging
+ * Flags >10% degradation with severity levels
+ */
+
+class RegressionDetector {
+  /**
+   * Detect regressions by comparing current metrics against baseline
+   * @param {Object} current - Current metrics
+   * @param {Object} baseline - Baseline metrics
+   * @param {number} threshold - Regression threshold percentage (default: 10)
+   * @returns {Array} Array of regression findings
+   */
+  detectRegressions(current, baseline, threshold = 10) {
+    const regressions = [];
+
+    for (const [metric, currentValue] of Object.entries(current)) {
+      const baselineValue = baseline[metric];
+      if (baselineValue === undefined || baselineValue === 0) continue;
+
+      const change = ((currentValue - baselineValue) / baselineValue) * 100;
+
+      if (change > threshold) {
+        regressions.push({
+          metric,
+          current: currentValue,
+          baseline: baselineValue,
+          changePercent: Math.round(change * 100) / 100,
+          severity: change > 50 ? 'critical' : change > 20 ? 'high' : 'medium'
+        });
+      }
+    }
+
+    return regressions;
+  }
+
+  /**
+   * Save baseline metrics
+   * @param {Object} metrics - Metrics to save
+   * @param {string} name - Baseline name
+   * @param {string} cwd - Working directory
+   */
+  saveBaseline(metrics, name = 'default', cwd) {
+    const fs = require('fs');
+    const path = require('path');
+    const baselinePath = path.join(cwd || process.cwd(), '.planning', 'perf-baselines', `${name}.json`);
+
+    // Ensure directory exists
+    const dir = path.dirname(baselinePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    fs.writeFileSync(baselinePath, JSON.stringify({
+      ...metrics,
+      metadata: {
+        name,
+        createdAt: new Date().toISOString()
+      }
+    }, null, 2));
+  }
+
+  /**
+   * Load baseline metrics
+   * @param {string} name - Baseline name
+   * @param {string} cwd - Working directory
+   * @returns {Object|null} Baseline metrics or null
+   */
+  loadBaseline(name = 'default', cwd) {
+    const fs = require('fs');
+    const path = require('path');
+    const baselinePath = path.join(cwd || process.cwd(), '.planning', 'perf-baselines', `${name}.json`);
+
+    if (!fs.existsSync(baselinePath)) return null;
+
+    return JSON.parse(fs.readFileSync(baselinePath, 'utf8'));
+  }
+}
+
+/**
+ * Detect regressions by comparing current metrics against baseline
+ * @param {Object} current - Current metrics
+ * @param {Object} baseline - Baseline metrics
+ * @param {number} threshold - Regression threshold percentage (default: 10)
+ * @returns {Array} Array of regression findings
+ */
+function detectRegressions(current, baseline, threshold = 10) {
+  const detector = new RegressionDetector();
+  return detector.detectRegressions(current, baseline, threshold);
+}
+
+module.exports = { RegressionDetector, detectRegressions };