find-bottleneck-perf 1.0.0

package/src/extractor.js

@@ -0,0 +1,302 @@
+/**
+ * Metric Extractor
+ * 
+ * Uses Puppeteer to load a URL and extract comprehensive performance metrics
+ * from the browser's Performance API and network activity.
+ */
+
+const puppeteer = require('puppeteer');
+
+/**
+ * Extract all performance metrics from a URL.
+ * @param {string} url - URL to analyze
+ * @param {object} options - Configuration options
+ * @param {object} options.networkCondition - Network throttling preset
+ * @returns {Promise<object>} Extracted metrics
+ */
+async function extractMetrics(url, options = {}) {
+    const {
+        timeout = 60000,
+        waitUntil = 'networkidle2',
+        viewport = { width: 1920, height: 1080 },
+        networkCondition = null,  // Network throttling preset
+    } = options;
+
+    let browser;
+
+    try {
+        browser = await puppeteer.launch({
+            headless: 'new',
+            args: [
+                '--no-sandbox',
+                '--disable-setuid-sandbox',
+                '--disable-blink-features=AutomationControlled',  // Hide automation
+                '--disable-http2',                                  // Avoid HTTP2 protocol errors
+                '--disable-features=IsolateOrigins,site-per-process',
+                '--disable-web-security',
+                '--user-agent=Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+            ],
+        });
+
+        const page = await browser.newPage();
+        await page.setViewport(viewport);
+
+        // === Apply Network Throttling via CDP ===
+        if (networkCondition) {
+            const client = await page.target().createCDPSession();
+            await client.send('Network.enable');
+            await client.send('Network.emulateNetworkConditions', {
+                offline: networkCondition.offline || false,
+                downloadThroughput: networkCondition.downloadThroughput,
+                uploadThroughput: networkCondition.uploadThroughput,
+                latency: networkCondition.latency,
+            });
+        }
+
+        // === Network Request Tracking ===
+        const resources = {
+            scripts: [],      // JS files
+            stylesheets: [],  // CSS files
+            images: [],       // Images
+            fonts: [],        // Font files
+            apis: [],         // XHR/Fetch requests
+            other: [],        // Everything else
+        };
+
+        let failedRequests = 0;
+
+        await page.setRequestInterception(true);
+        page.on('request', (req) => req.continue());
+
+        page.on('response', async (response) => {
+            const reqUrl = response.url();
+            const resourceType = response.request().resourceType();
+            const status = response.status();
+
+            // Track failed requests
+            if (status >= 400) {
+                failedRequests++;
+            }
+
+            // Get response size (safely)
+            let size = 0;
+            try {
+                const buffer = await response.buffer();
+                size = buffer.length;
+            } catch (e) {
+                // Response body unavailable (e.g., redirects)
+            }
+
+            const timing = response.timing();
+            const duration = timing ? timing.receiveHeadersEnd : 0;
+
+            const entry = { url: reqUrl, size, duration, status };
+
+            switch (resourceType) {
+                case 'script':
+                    resources.scripts.push(entry);
+                    break;
+                case 'stylesheet':
+                    resources.stylesheets.push(entry);
+                    break;
+                case 'image':
+                    resources.images.push(entry);
+                    break;
+                case 'font':
+                    resources.fonts.push(entry);
+                    break;
+                case 'xhr':
+                case 'fetch':
+                    resources.apis.push(entry);
+                    break;
+                default:
+                    resources.other.push(entry);
+            }
+        });
+
+        // === Page Load ===
+        const loadStart = Date.now();
+        await page.goto(url, { waitUntil, timeout });
+        const totalLoadTime = Date.now() - loadStart;
+
+        // === Extract Navigation Timing ===
+        const navTiming = await page.evaluate(() => {
+            const nav = performance.getEntriesByType('navigation')[0];
+            if (!nav) return null;
+
+            return {
+                // Connection phases
+                dnsLookup: nav.domainLookupEnd - nav.domainLookupStart,
+                tcpConnection: nav.connectEnd - nav.connectStart,
+                tlsHandshake: nav.secureConnectionStart > 0
+                    ? nav.connectEnd - nav.secureConnectionStart
+                    : 0,
+
+                // Request/Response
+                ttfb: nav.responseStart - nav.requestStart,
+                responseTime: nav.responseEnd - nav.responseStart,
+
+                // Document Processing
+                domInteractive: nav.domInteractive,
+                domContentLoaded: nav.domContentLoadedEventEnd,
+                domComplete: nav.domComplete,
+                loadEvent: nav.loadEventEnd,
+
+                // Derived: Server processing time (TTFB minus network overhead)
+                serverProcessing: nav.responseStart - nav.connectEnd,
+            };
+        });
+
+        // === Extract Paint Timing ===
+        const paintTiming = await page.evaluate(() => {
+            const entries = performance.getEntriesByType('paint');
+            const fcp = entries.find(e => e.name === 'first-contentful-paint');
+            const fp = entries.find(e => e.name === 'first-paint');
+
+            return {
+                firstPaint: fp ? fp.startTime : 0,
+                firstContentfulPaint: fcp ? fcp.startTime : 0,
+            };
+        });
+
+        // === Extract LCP ===
+        const lcp = await page.evaluate(() => {
+            return new Promise((resolve) => {
+                let lcpValue = 0;
+
+                try {
+                    new PerformanceObserver((entryList) => {
+                        const entries = entryList.getEntries();
+                        lcpValue = entries[entries.length - 1]?.startTime || 0;
+                    }).observe({ type: 'largest-contentful-paint', buffered: true });
+                } catch (e) {
+                    // LCP not supported
+                }
+
+                // Wait for LCP to stabilize
+                setTimeout(() => resolve(lcpValue), 2000);
+            });
+        });
+
+        // === Extract Long Tasks (Total Blocking Time) ===
+        const longTasks = await page.evaluate(() => {
+            return new Promise((resolve) => {
+                let totalBlocking = 0;
+                let taskCount = 0;
+
+                try {
+                    new PerformanceObserver((list) => {
+                        for (const entry of list.getEntries()) {
+                            // Long task is > 50ms, blocking time is the excess
+                            const blocking = entry.duration - 50;
+                            totalBlocking += blocking > 0 ? blocking : 0;
+                            taskCount++;
+                        }
+                    }).observe({ type: 'longtask', buffered: true });
+                } catch (e) {
+                    // Long tasks not supported
+                }
+
+                setTimeout(() => resolve({ totalBlocking, taskCount }), 1500);
+            });
+        });
+
+        // === Extract Resource Hints & Render Blocking ===
+        const renderBlocking = await page.evaluate(() => {
+            // Count render-blocking resources (sync scripts in head, blocking stylesheets)
+            const blockingScripts = document.querySelectorAll('head script:not([async]):not([defer])').length;
+            const blockingStyles = document.querySelectorAll('link[rel="stylesheet"]').length;
+
+            return {
+                blockingScripts,
+                blockingStyles,
+                total: blockingScripts + blockingStyles,
+            };
+        });
+
+        await browser.close();
+
+        // === Aggregate Resource Sizes ===
+        const sumSize = (arr) => arr.reduce((sum, r) => sum + r.size, 0);
+        const avgDuration = (arr) => arr.length > 0
+            ? arr.reduce((sum, r) => sum + r.duration, 0) / arr.length
+            : 0;
+        const maxDuration = (arr) => arr.length > 0
+            ? Math.max(...arr.map(r => r.duration))
+            : 0;
+
+        // === Compile Final Metrics ===
+        return {
+            url,
+            timestamp: new Date().toISOString(),
+
+            // Navigation Timing
+            navigation: {
+                dnsLookup: Math.round(navTiming?.dnsLookup || 0),
+                tcpConnection: Math.round(navTiming?.tcpConnection || 0),
+                tlsHandshake: Math.round(navTiming?.tlsHandshake || 0),
+                ttfb: Math.round(navTiming?.ttfb || 0),
+                responseTime: Math.round(navTiming?.responseTime || 0),
+                serverProcessing: Math.round(navTiming?.serverProcessing || 0),
+                domInteractive: Math.round(navTiming?.domInteractive || 0),
+                domContentLoaded: Math.round(navTiming?.domContentLoaded || 0),
+                domComplete: Math.round(navTiming?.domComplete || 0),
+                totalLoadTime,
+            },
+
+            // Paint & Vitals
+            vitals: {
+                firstPaint: Math.round(paintTiming.firstPaint),
+                firstContentfulPaint: Math.round(paintTiming.firstContentfulPaint),
+                largestContentfulPaint: Math.round(lcp),
+                totalBlockingTime: Math.round(longTasks.totalBlocking),
+                longTaskCount: longTasks.taskCount,
+            },
+
+            // Resource Breakdown
+            resources: {
+                javascript: {
+                    count: resources.scripts.length,
+                    totalBytes: sumSize(resources.scripts),
+                },
+                css: {
+                    count: resources.stylesheets.length,
+                    totalBytes: sumSize(resources.stylesheets),
+                },
+                images: {
+                    count: resources.images.length,
+                    totalBytes: sumSize(resources.images),
+                },
+                fonts: {
+                    count: resources.fonts.length,
+                    totalBytes: sumSize(resources.fonts),
+                },
+                other: {
+                    count: resources.other.length,
+                    totalBytes: sumSize(resources.other),
+                },
+            },
+
+            // API Performance
+            api: {
+                callCount: resources.apis.length,
+                avgLatency: Math.round(avgDuration(resources.apis)),
+                maxLatency: Math.round(maxDuration(resources.apis)),
+                failedCount: resources.apis.filter(r => r.status >= 400).length,
+                totalFailedRequests: failedRequests,
+            },
+
+            // Render Blocking
+            renderBlocking,
+
+            // Derived Metrics (calculated in analyzer)
+            derived: null,
+        };
+
+    } catch (err) {
+        if (browser) await browser.close();
+        throw err;
+    }
+}
+
+module.exports = { extractMetrics };

package/src/reporter.js

@@ -0,0 +1,249 @@
+/**
+ * Performance Reporter
+ * 
+ * Formats analysis results for terminal output with colors,
+ * tables, and clear visual hierarchy.
+ */
+
+const { colors, colorize, formatMs, formatBytes, getStatus, progressBar } = require('./utils');
+const T = require('./thresholds');
+
+/**
+ * Print the full analysis report to terminal.
+ * @param {object} analysis - Analysis result from analyzer
+ */
+function printReport(analysis) {
+    const { verdict, scores, evidence, metrics } = analysis;
+    const nav = metrics.navigation;
+    const vitals = metrics.vitals;
+    const derived = metrics.derived;
+    const api = metrics.api;
+    const res = metrics.resources;
+
+    console.log('\n' + '═'.repeat(60));
+    console.log(colorize('  PERF-BLAME-FINDER  │  Performance Analysis Report', 'cyan'));
+    console.log('═'.repeat(60));
+    console.log(colorize(`  URL: ${metrics.url}`, 'dim'));
+    console.log(colorize(`  Analyzed: ${metrics.timestamp}`, 'dim'));
+    console.log('─'.repeat(60));
+
+    // === VERDICT ===
+    printVerdict(verdict, scores);
+
+    // === METRICS SUMMARY ===
+    printMetricsSummary(nav, vitals, derived, api, res);
+
+    // === EVIDENCE ===
+    printEvidence(evidence);
+
+    // === RECOMMENDATIONS ===
+    const { getRecommendations } = require('./analyzer');
+    const recs = getRecommendations(verdict, evidence);
+    printRecommendations(recs);
+
+    console.log('═'.repeat(60) + '\n');
+}
+
+function printVerdict(verdict, scores) {
+    console.log('\n' + colorize('┌─ THE VERDICT', 'bright'));
+    console.log('│');
+
+    let verdictColor, verdictIcon;
+    switch (verdict) {
+        case 'Optimized':
+            verdictColor = 'green';
+            verdictIcon = '✅';
+            break;
+        case 'Frontend':
+            verdictColor = 'blue';
+            verdictIcon = '🖥️';
+            break;
+        case 'Backend':
+            verdictColor = 'yellow';
+            verdictIcon = '⚙️';
+            break;
+        case 'Infra':
+            verdictColor = 'red';
+            verdictIcon = '🌐';
+            break;
+        case 'Mixed':
+            verdictColor = 'magenta';
+            verdictIcon = '⚠️';
+            break;
+        default:
+            verdictColor = 'white';
+            verdictIcon = '❓';
+    }
+
+    console.log(`│  ${verdictIcon}  Primary Bottleneck: ${colorize(verdict.toUpperCase(), verdictColor)}`);
+    console.log('│');
+    console.log(`│  Scores: Frontend=${scores.Frontend}  Backend=${scores.Backend}  Infra=${scores.Infra}`);
+    console.log('└' + '─'.repeat(59));
+}
+
+function printMetricsSummary(nav, vitals, derived, api, res) {
+    console.log('\n' + colorize('┌─ METRICS SUMMARY', 'bright'));
+
+    // Navigation Timing
+    console.log('│');
+    console.log('│  ' + colorize('Navigation Timing', 'cyan'));
+    printMetricRow('  DNS Lookup', nav.dnsLookup, 'ms', T.DNS);
+    printMetricRow('  TCP Connect', nav.tcpConnection, 'ms', T.TCP);
+    printMetricRow('  TLS Handshake', nav.tlsHandshake, 'ms', T.TLS);
+    printMetricRow('  TTFB', nav.ttfb, 'ms', T.TTFB);
+    printMetricRow('  Server Processing', nav.serverProcessing, 'ms', T.TTFB);
+    printMetricRow('  DOM Content Loaded', nav.domContentLoaded, 'ms');
+    printMetricRow('  Total Load Time', nav.totalLoadTime, 'ms');
+
+    // Core Web Vitals
+    console.log('│');
+    console.log('│  ' + colorize('Core Web Vitals', 'cyan'));
+    printMetricRow('  First Contentful Paint', vitals.firstContentfulPaint, 'ms', T.FCP);
+    printMetricRow('  Largest Contentful Paint', vitals.largestContentfulPaint, 'ms', T.LCP);
+    printMetricRow('  Total Blocking Time', vitals.totalBlockingTime, 'ms', T.JS_EXECUTION);
+    printMetricRow('  Long Task Count', vitals.longTaskCount);
+
+    // Resources
+    console.log('│');
+    console.log('│  ' + colorize('Resource Sizes', 'cyan'));
+    printMetricRow('  JavaScript', derived.jsSizeMB, 'MB', T.BUNDLE_SIZE_MB);
+    printMetricRow('  CSS', derived.cssSizeMB, 'MB', T.CSS_SIZE_MB);
+    printMetricRow('  Images', derived.imageSizeMB, 'MB', T.IMAGE_SIZE_MB);
+    printMetricRow('  Total', derived.totalSizeMB, 'MB');
+
+    // API
+    console.log('│');
+    console.log('│  ' + colorize('API Performance', 'cyan'));
+    printMetricRow('  Request Count', api.callCount, '', T.API_CALLS);
+    printMetricRow('  Avg Latency', api.avgLatency, 'ms', T.API_LATENCY);
+    printMetricRow('  Max Latency', api.maxLatency, 'ms');
+    printMetricRow('  Failed Requests', api.failedCount);
+
+    // Derived
+    console.log('│');
+    console.log('│  ' + colorize('Derived Metrics', 'cyan'));
+    printMetricRow('  Network Overhead', derived.networkOverhead, 'ms');
+    printMetricRow('  Network Overhead Ratio', (derived.networkOverheadRatio * 100).toFixed(0), '%');
+    printMetricRow('  Client Render Time', derived.clientRenderTime, 'ms', T.CLIENT_RENDER_TIME);
+
+    console.log('└' + '─'.repeat(59));
+}
+
+function printMetricRow(label, value, unit = '', threshold = null) {
+    const formattedValue = typeof value === 'number'
+        ? (unit === 'MB' ? value.toFixed(2) : Math.round(value))
+        : value;
+
+    let status = '  ';
+    if (threshold) {
+        // Determine status based on threshold
+        if (threshold.GOOD !== undefined && threshold.POOR !== undefined) {
+            if (value <= threshold.GOOD) status = colorize('●', 'green');
+            else if (value >= threshold.POOR) status = colorize('●', 'red');
+            else status = colorize('●', 'yellow');
+        } else if (threshold.NORMAL !== undefined) {
+            // For counts like API calls
+            if (value <= threshold.NORMAL) status = colorize('●', 'green');
+            else if (value >= threshold.EXCESSIVE) status = colorize('●', 'red');
+            else status = colorize('●', 'yellow');
+        }
+    }
+
+    const valueStr = `${formattedValue}${unit}`;
+    console.log(`│  ${status} ${label.padEnd(25)} ${valueStr.padStart(10)}`);
+}
+
+function printEvidence(evidence) {
+    console.log('\n' + colorize('┌─ EVIDENCE', 'bright'));
+
+    if (evidence.length === 0) {
+        console.log('│  No significant issues detected.');
+    } else {
+        // Group by category
+        const grouped = {};
+        for (const e of evidence) {
+            if (!grouped[e.category]) grouped[e.category] = [];
+            grouped[e.category].push(e);
+        }
+
+        for (const [category, items] of Object.entries(grouped)) {
+            console.log('│');
+            const catColor = category === 'Frontend' ? 'blue'
+                : category === 'Backend' ? 'yellow'
+                    : 'red';
+            console.log('│  ' + colorize(`[${category}]`, catColor));
+
+            for (const item of items) {
+                const severityIcon = item.severity === 'high' ? colorize('▸', 'red') : colorize('▸', 'yellow');
+                console.log(`│    ${severityIcon} ${item.message}`);
+            }
+        }
+    }
+
+    console.log('└' + '─'.repeat(59));
+}
+
+function printRecommendations(recs) {
+    console.log('\n' + colorize('┌─ RECOMMENDATIONS', 'bright'));
+    console.log('│');
+
+    for (const rec of recs) {
+        console.log(`│  👉 ${rec}`);
+    }
+
+    console.log('└' + '─'.repeat(59));
+}
+
+/**
+ * Export full analysis as JSON.
+ * @param {object} analysis - Full analysis result
+ * @param {string} filepath - Output file path
+ */
+function exportJson(analysis, filepath) {
+    const fs = require('fs');
+    const { getRecommendations } = require('./analyzer');
+
+    const { verdict, scores, evidence, metrics } = analysis;
+    const recommendations = getRecommendations(verdict, evidence);
+
+    // Build clean export object with all data
+    const exportData = {
+        url: metrics.url,
+        timestamp: metrics.timestamp,
+
+        // The verdict
+        verdict: {
+            primary: verdict,
+            scores: scores,
+        },
+
+        // All metrics
+        metrics: {
+            navigation: metrics.navigation,
+            vitals: metrics.vitals,
+            resources: metrics.resources,
+            api: metrics.api,
+            renderBlocking: metrics.renderBlocking,
+            derived: metrics.derived,
+        },
+
+        // Evidence (cleaned for JSON)
+        evidence: evidence.map(e => ({
+            category: e.category,
+            severity: e.severity,
+            metric: e.metric,
+            value: e.value,
+            threshold: e.threshold,
+            message: e.message,
+        })),
+
+        // Recommendations
+        recommendations: recommendations,
+    };
+
+    fs.writeFileSync(filepath, JSON.stringify(exportData, null, 2));
+    console.log(colorize(`\n📁 Full report exported to: ${filepath}`, 'green'));
+}
+
+module.exports = { printReport, exportJson };
+

package/src/thresholds.js

@@ -0,0 +1,138 @@
+/**
+ * Threshold configuration for performance metrics.
+ * All time values are in milliseconds, sizes in MB.
+ * 
+ * These are opinionated, production-realistic values based on:
+ * - Google's Core Web Vitals guidelines
+ * - Real-world SRE experience
+ * - Perceived performance research
+ */
+
+module.exports = {
+    // === Navigation Timing ===
+    TTFB: {
+        GOOD: 200,      // Fast server, edge-cached
+        MODERATE: 400,  // Typical origin response
+        POOR: 600,      // Noticeable delay
+    },
+
+    DNS: {
+        GOOD: 20,       // Cached or fast resolver
+        POOR: 100,      // Slow DNS or cold lookup
+    },
+
+    TCP: {
+        GOOD: 50,       // Low-latency connection
+        POOR: 200,      // High-latency or congested
+    },
+
+    TLS: {
+        GOOD: 50,       // Session resumption
+        POOR: 150,      // Full handshake
+    },
+
+    // === Core Web Vitals ===
+    LCP: {
+        GOOD: 2500,     // Google's "good" threshold
+        POOR: 4000,     // Google's "poor" threshold
+    },
+
+    FCP: {
+        GOOD: 1800,
+        POOR: 3000,
+    },
+
+    // === JavaScript ===
+    JS_EXECUTION: {
+        GOOD: 200,      // Minimal blocking
+        MODERATE: 500,  // Noticeable but acceptable
+        POOR: 800,      // Heavy blocking
+    },
+
+    BUNDLE_SIZE_MB: {
+        GOOD: 0.5,      // Well-optimized
+        MODERATE: 1.0,  // Typical SPA
+        POOR: 2.0,      // Bloated
+    },
+
+    // === API Performance ===
+    API_LATENCY: {
+        GOOD: 100,      // Snappy API
+        MODERATE: 200,  // Acceptable
+        POOR: 300,      // Sluggish
+    },
+
+    API_CALLS: {
+        NORMAL: 15,     // Reasonable for initial load
+        HIGH: 30,       // Chatty
+        EXCESSIVE: 50,  // Problematic
+    },
+
+    // === Resource Sizes (MB) ===
+    CSS_SIZE_MB: {
+        GOOD: 0.1,
+        POOR: 0.3,
+    },
+
+    IMAGE_SIZE_MB: {
+        GOOD: 1.0,
+        POOR: 3.0,
+    },
+
+    // === Derived Ratios ===
+    NETWORK_OVERHEAD_RATIO: {
+        HIGH: 0.5,      // > 50% of TTFB is network overhead
+    },
+
+    CLIENT_RENDER_TIME: {
+        GOOD: 1500,     // Fast render after TTFB
+        POOR: 2500,     // Slow client-side processing
+    },
+};
+
+/**
+ * Network Throttling Presets
+ * Based on Chrome DevTools network conditions
+ * 
+ * downloadThroughput/uploadThroughput: bytes per second
+ * latency: additional RTT in ms
+ */
+module.exports.NETWORK_PRESETS = {
+    'no-throttle': {
+        name: 'No Throttle',
+        downloadThroughput: -1,        // Unlimited
+        uploadThroughput: -1,
+        latency: 0,
+    },
+    'slow-3g': {
+        name: 'Slow 3G',
+        downloadThroughput: 500 * 1024 / 8,    // 500 Kbps
+        uploadThroughput: 500 * 1024 / 8,
+        latency: 400,                          // 400ms RTT
+    },
+    'fast-3g': {
+        name: 'Fast 3G',
+        downloadThroughput: 1.6 * 1024 * 1024 / 8,  // 1.6 Mbps
+        uploadThroughput: 750 * 1024 / 8,
+        latency: 150,                               // 150ms RTT
+    },
+    '4g': {
+        name: 'Regular 4G',
+        downloadThroughput: 4 * 1024 * 1024 / 8,    // 4 Mbps
+        uploadThroughput: 3 * 1024 * 1024 / 8,
+        latency: 20,                                 // 20ms RTT
+    },
+    'wifi': {
+        name: 'WiFi',
+        downloadThroughput: 30 * 1024 * 1024 / 8,   // 30 Mbps
+        uploadThroughput: 15 * 1024 * 1024 / 8,
+        latency: 2,                                  // 2ms RTT
+    },
+    'offline': {
+        name: 'Offline',
+        offline: true,
+        downloadThroughput: 0,
+        uploadThroughput: 0,
+        latency: 0,
+    },
+};