find-bottleneck-perf 1.0.0

package/src/analyzer.js

@@ -0,0 +1,432 @@
+/**
+ * Performance Analyzer
+ * 
+ * Analyzes extracted metrics using heuristics to determine the primary
+ * bottleneck and generate actionable evidence.
+ */
+
+const T = require('./thresholds');
+
+/**
+ * Analyze metrics and determine bottleneck.
+ * @param {object} metrics - Extracted metrics from extractor
+ * @returns {object} Analysis result with verdict, evidence, and scores
+ */
+function analyze(metrics) {
+    const nav = metrics.navigation;
+    const vitals = metrics.vitals;
+    const res = metrics.resources;
+    const api = metrics.api;
+
+    // === Calculate Derived Metrics ===
+    const jsSizeMB = res.javascript.totalBytes / 1024 / 1024;
+    const cssSizeMB = res.css.totalBytes / 1024 / 1024;
+    const imageSizeMB = res.images.totalBytes / 1024 / 1024;
+    const totalSizeMB = jsSizeMB + cssSizeMB + imageSizeMB +
+        (res.fonts.totalBytes / 1024 / 1024) + (res.other.totalBytes / 1024 / 1024);
+
+    const networkOverhead = nav.dnsLookup + nav.tcpConnection + nav.tlsHandshake;
+    const networkOverheadRatio = nav.ttfb > 0 ? networkOverhead / nav.ttfb : 0;
+    const clientRenderTime = vitals.largestContentfulPaint - nav.ttfb;
+
+    metrics.derived = {
+        jsSizeMB: parseFloat(jsSizeMB.toFixed(2)),
+        cssSizeMB: parseFloat(cssSizeMB.toFixed(2)),
+        imageSizeMB: parseFloat(imageSizeMB.toFixed(2)),
+        totalSizeMB: parseFloat(totalSizeMB.toFixed(2)),
+        networkOverhead,
+        networkOverheadRatio: parseFloat(networkOverheadRatio.toFixed(2)),
+        clientRenderTime: Math.round(clientRenderTime),
+    };
+
+    // === Scoring System ===
+    const scores = {
+        Frontend: 0,
+        Backend: 0,
+        Infra: 0,
+    };
+
+    const evidence = [];
+
+    // =========================================
+    // INFRASTRUCTURE / NETWORK ANALYSIS
+    // =========================================
+
+    // DNS Lookup
+    if (nav.dnsLookup > T.DNS.POOR) {
+        scores.Infra += 5;
+        evidence.push({
+            category: 'Infra',
+            severity: 'high',
+            metric: 'DNS Lookup',
+            value: nav.dnsLookup,
+            threshold: T.DNS.POOR,
+            message: `Slow DNS resolution (${nav.dnsLookup}ms). Consider DNS prefetching or faster resolver.`,
+        });
+    }
+
+    // TCP Connection
+    if (nav.tcpConnection > T.TCP.POOR) {
+        scores.Infra += 5;
+        evidence.push({
+            category: 'Infra',
+            severity: 'high',
+            metric: 'TCP Connection',
+            value: nav.tcpConnection,
+            threshold: T.TCP.POOR,
+            message: `High TCP latency (${nav.tcpConnection}ms). Server may be geographically distant.`,
+        });
+    }
+
+    // TLS Handshake
+    if (nav.tlsHandshake > T.TLS.POOR) {
+        scores.Infra += 4;
+        evidence.push({
+            category: 'Infra',
+            severity: 'medium',
+            metric: 'TLS Handshake',
+            value: nav.tlsHandshake,
+            threshold: T.TLS.POOR,
+            message: `Slow TLS handshake (${nav.tlsHandshake}ms). Consider TLS 1.3 or session resumption.`,
+        });
+    }
+
+    // TTFB Analysis (nuanced: check if it's network or backend)
+    if (nav.ttfb > T.TTFB.POOR) {
+        // If network overhead is high relative to TTFB, it's Infra
+        if (networkOverheadRatio > T.NETWORK_OVERHEAD_RATIO.HIGH) {
+            scores.Infra += 8;
+            evidence.push({
+                category: 'Infra',
+                severity: 'high',
+                metric: 'TTFB (Network)',
+                value: nav.ttfb,
+                threshold: T.TTFB.POOR,
+                message: `High TTFB (${nav.ttfb}ms) dominated by network overhead (${Math.round(networkOverheadRatio * 100)}%).`,
+            });
+        } else {
+            // Server processing is the bottleneck
+            scores.Backend += 8;
+            evidence.push({
+                category: 'Backend',
+                severity: 'high',
+                metric: 'TTFB (Server)',
+                value: nav.ttfb,
+                threshold: T.TTFB.POOR,
+                message: `High TTFB (${nav.ttfb}ms) due to slow server processing (${nav.serverProcessing}ms).`,
+            });
+        }
+    } else if (nav.ttfb > T.TTFB.MODERATE) {
+        scores.Backend += 3;
+        scores.Infra += 2;
+        evidence.push({
+            category: 'Backend',
+            severity: 'medium',
+            metric: 'TTFB',
+            value: nav.ttfb,
+            threshold: T.TTFB.MODERATE,
+            message: `Elevated TTFB (${nav.ttfb}ms). Room for improvement.`,
+        });
+    }
+
+    // =========================================
+    // BACKEND ANALYSIS
+    // =========================================
+
+    // API Latency - Average
+    if (api.avgLatency > T.API_LATENCY.POOR) {
+        scores.Backend += 10;
+        evidence.push({
+            category: 'Backend',
+            severity: 'high',
+            metric: 'API Latency (Avg)',
+            value: api.avgLatency,
+            threshold: T.API_LATENCY.POOR,
+            message: `Slow API responses (avg ${api.avgLatency}ms). Profile database queries and add caching.`,
+        });
+    } else if (api.avgLatency > T.API_LATENCY.MODERATE) {
+        scores.Backend += 4;
+        evidence.push({
+            category: 'Backend',
+            severity: 'medium',
+            metric: 'API Latency (Avg)',
+            value: api.avgLatency,
+            threshold: T.API_LATENCY.MODERATE,
+            message: `Moderate API latency (avg ${api.avgLatency}ms).`,
+        });
+    }
+
+    // API Latency - Max (single slow endpoint)
+    if (api.maxLatency > 500) {
+        scores.Backend += 5;
+        evidence.push({
+            category: 'Backend',
+            severity: 'medium',
+            metric: 'API Latency (Max)',
+            value: api.maxLatency,
+            threshold: 500,
+            message: `Slowest API call took ${api.maxLatency}ms. Identify and optimize this endpoint.`,
+        });
+    }
+
+    // Failed API Calls
+    if (api.failedCount > 0) {
+        scores.Backend += 6;
+        evidence.push({
+            category: 'Backend',
+            severity: 'high',
+            metric: 'Failed API Calls',
+            value: api.failedCount,
+            threshold: 0,
+            message: `${api.failedCount} API calls failed (4xx/5xx). Fix broken endpoints.`,
+        });
+    }
+
+    // =========================================
+    // FRONTEND ANALYSIS
+    // =========================================
+
+    // JavaScript Bundle Size
+    if (jsSizeMB > T.BUNDLE_SIZE_MB.POOR) {
+        scores.Frontend += 10;
+        evidence.push({
+            category: 'Frontend',
+            severity: 'high',
+            metric: 'JS Bundle Size',
+            value: jsSizeMB,
+            threshold: T.BUNDLE_SIZE_MB.POOR,
+            message: `Massive JS bundle (${jsSizeMB.toFixed(2)} MB). Implement code splitting and tree shaking.`,
+        });
+    } else if (jsSizeMB > T.BUNDLE_SIZE_MB.MODERATE) {
+        scores.Frontend += 5;
+        evidence.push({
+            category: 'Frontend',
+            severity: 'medium',
+            metric: 'JS Bundle Size',
+            value: jsSizeMB,
+            threshold: T.BUNDLE_SIZE_MB.MODERATE,
+            message: `Large JS bundle (${jsSizeMB.toFixed(2)} MB). Consider optimization.`,
+        });
+    }
+
+    // Total Blocking Time (Long Tasks)
+    if (vitals.totalBlockingTime > T.JS_EXECUTION.POOR) {
+        scores.Frontend += 10;
+        evidence.push({
+            category: 'Frontend',
+            severity: 'high',
+            metric: 'Total Blocking Time',
+            value: vitals.totalBlockingTime,
+            threshold: T.JS_EXECUTION.POOR,
+            message: `Heavy main thread blocking (${vitals.totalBlockingTime}ms). Move work to Web Workers.`,
+        });
+    } else if (vitals.totalBlockingTime > T.JS_EXECUTION.MODERATE) {
+        scores.Frontend += 4;
+        evidence.push({
+            category: 'Frontend',
+            severity: 'medium',
+            metric: 'Total Blocking Time',
+            value: vitals.totalBlockingTime,
+            threshold: T.JS_EXECUTION.MODERATE,
+            message: `Moderate main thread blocking (${vitals.totalBlockingTime}ms).`,
+        });
+    }
+
+    // Client Render Time (LCP - TTFB)
+    if (clientRenderTime > T.CLIENT_RENDER_TIME.POOR) {
+        scores.Frontend += 8;
+        evidence.push({
+            category: 'Frontend',
+            severity: 'high',
+            metric: 'Client Render Time',
+            value: clientRenderTime,
+            threshold: T.CLIENT_RENDER_TIME.POOR,
+            message: `Slow client rendering (${clientRenderTime}ms from TTFB to LCP). Optimize critical path.`,
+        });
+    }
+
+    // LCP (absolute)
+    if (vitals.largestContentfulPaint > T.LCP.POOR) {
+        scores.Frontend += 6;
+        evidence.push({
+            category: 'Frontend',
+            severity: 'high',
+            metric: 'LCP',
+            value: vitals.largestContentfulPaint,
+            threshold: T.LCP.POOR,
+            message: `Poor LCP (${vitals.largestContentfulPaint}ms). Largest element is loading too slowly.`,
+        });
+    } else if (vitals.largestContentfulPaint > T.LCP.GOOD) {
+        scores.Frontend += 3;
+        evidence.push({
+            category: 'Frontend',
+            severity: 'medium',
+            metric: 'LCP',
+            value: vitals.largestContentfulPaint,
+            threshold: T.LCP.GOOD,
+            message: `LCP needs improvement (${vitals.largestContentfulPaint}ms).`,
+        });
+    }
+
+    // Excessive API Calls (Frontend is requesting too much)
+    if (api.callCount > T.API_CALLS.EXCESSIVE) {
+        scores.Frontend += 8;
+        scores.Backend += 3;
+        evidence.push({
+            category: 'Frontend',
+            severity: 'high',
+            metric: 'API Call Count',
+            value: api.callCount,
+            threshold: T.API_CALLS.EXCESSIVE,
+            message: `Excessive API calls (${api.callCount}). Implement request batching or BFF pattern.`,
+        });
+    } else if (api.callCount > T.API_CALLS.HIGH) {
+        scores.Frontend += 4;
+        evidence.push({
+            category: 'Frontend',
+            severity: 'medium',
+            metric: 'API Call Count',
+            value: api.callCount,
+            threshold: T.API_CALLS.HIGH,
+            message: `High number of API calls (${api.callCount}). Consider aggregation.`,
+        });
+    }
+
+    // Render-blocking resources
+    if (metrics.renderBlocking.total > 5) {
+        scores.Frontend += 5;
+        evidence.push({
+            category: 'Frontend',
+            severity: 'medium',
+            metric: 'Render Blocking Resources',
+            value: metrics.renderBlocking.total,
+            threshold: 5,
+            message: `${metrics.renderBlocking.total} render-blocking resources. Use async/defer for scripts.`,
+        });
+    }
+
+    // Image Size
+    if (imageSizeMB > T.IMAGE_SIZE_MB.POOR) {
+        scores.Frontend += 6;
+        evidence.push({
+            category: 'Frontend',
+            severity: 'medium',
+            metric: 'Image Size',
+            value: imageSizeMB,
+            threshold: T.IMAGE_SIZE_MB.POOR,
+            message: `Heavy images (${imageSizeMB.toFixed(2)} MB). Use WebP/AVIF and lazy loading.`,
+        });
+    }
+
+    // =========================================
+    // DETERMINE VERDICT
+    // =========================================
+
+    const maxScore = Math.max(scores.Frontend, scores.Backend, scores.Infra);
+    let verdict;
+
+    if (maxScore < 3) {
+        verdict = 'Optimized';
+    } else {
+        verdict = Object.keys(scores).find(key => scores[key] === maxScore);
+
+        // Tie-breaking: If scores are close, report as "Mixed"
+        const sortedScores = Object.values(scores).sort((a, b) => b - a);
+        if (sortedScores[0] - sortedScores[1] < 3 && sortedScores[1] > 5) {
+            verdict = 'Mixed';
+        }
+    }
+
+    return {
+        verdict,
+        scores,
+        evidence,
+        metrics,
+    };
+}
+
+/**
+ * Generate recommendations based on verdict.
+ * @param {string} verdict - Primary bottleneck
+ * @param {array} evidence - Evidence items
+ * @returns {array} Recommendations
+ */
+function getRecommendations(verdict, evidence) {
+    const recs = [];
+
+    // Specific recommendations based on evidence
+    const categories = evidence.map(e => e.category);
+
+    if (verdict === 'Frontend' || categories.includes('Frontend')) {
+        const hasLargeBundle = evidence.some(e => e.metric.includes('Bundle Size'));
+        const hasBlockingTime = evidence.some(e => e.metric.includes('Blocking'));
+        const hasRenderIssues = evidence.some(e => e.metric.includes('Render') || e.metric === 'LCP');
+        const hasChattyApi = evidence.some(e => e.metric.includes('API Call'));
+
+        if (hasLargeBundle) {
+            recs.push('Implement code splitting (dynamic imports) and tree shaking.');
+            recs.push('Analyze bundle with webpack-bundle-analyzer or source-map-explorer.');
+        }
+        if (hasBlockingTime) {
+            recs.push('Profile JavaScript with Chrome DevTools Performance tab.');
+            recs.push('Move heavy computations to Web Workers.');
+        }
+        if (hasRenderIssues) {
+            recs.push('Inline critical CSS and defer non-essential styles.');
+            recs.push('Preload LCP image/element with <link rel="preload">.');
+        }
+        if (hasChattyApi) {
+            recs.push('Implement a Backend-for-Frontend (BFF) to aggregate requests.');
+            recs.push('Consider GraphQL for flexible data fetching.');
+        }
+    }
+
+    if (verdict === 'Backend' || categories.includes('Backend')) {
+        const hasSlowApi = evidence.some(e => e.metric.includes('API Latency'));
+        const hasFailed = evidence.some(e => e.metric.includes('Failed'));
+
+        if (hasSlowApi) {
+            recs.push('Profile database queries - check for missing indexes and N+1 queries.');
+            recs.push('Add caching layer (Redis/Memcached) for frequent queries.');
+            recs.push('Consider denormalization or read replicas for heavy queries.');
+        }
+        if (hasFailed) {
+            recs.push('Fix failing endpoints immediately - check logs for errors.');
+            recs.push('Implement proper error handling and fallbacks.');
+        }
+    }
+
+    if (verdict === 'Infra' || categories.includes('Infra')) {
+        const hasDns = evidence.some(e => e.metric.includes('DNS'));
+        const hasTcp = evidence.some(e => e.metric.includes('TCP'));
+        const hasTtfb = evidence.some(e => e.metric.includes('TTFB'));
+
+        if (hasDns) {
+            recs.push('Use faster DNS provider (e.g., Cloudflare DNS).');
+            recs.push('Add <link rel="dns-prefetch"> for third-party domains.');
+        }
+        if (hasTcp) {
+            recs.push('Deploy servers/CDN edges closer to users.');
+            recs.push('Enable HTTP/2 or HTTP/3 for multiplexing.');
+        }
+        if (hasTtfb) {
+            recs.push('Review CDN configuration and cache hit rates.');
+            recs.push('Enable Brotli/Gzip compression on responses.');
+            recs.push('For serverless: investigate cold start optimization.');
+        }
+    }
+
+    if (verdict === 'Optimized') {
+        recs.push('Performance looks healthy! Consider implementing RUM for ongoing monitoring.');
+        recs.push('Set up alerting for performance regressions.');
+    }
+
+    if (verdict === 'Mixed') {
+        recs.push('Multiple areas need attention. Prioritize based on user impact.');
+        recs.push('Consider a holistic performance audit.');
+    }
+
+    return recs;
+}
+
+module.exports = { analyze, getRecommendations };