find-bottleneck-perf 1.0.0

package/README.md

@@ -0,0 +1,169 @@
+# find-bottleneck-perf 🔍
+
+**One command. One answer.** Who's slowing down your website—Frontend, Backend, or Infrastructure?
+
+```bash
+npx find-bottleneck-perf https://your-website.com
+```
+
+![Node.js](https://img.shields.io/badge/Node.js-18+-green)
+![License](https://img.shields.io/badge/License-ISC-blue)
+![npm](https://img.shields.io/npm/v/find-bottleneck-perf)
+
+---
+
+## Why?
+
+You've got a slow website. Lighthouse gives you 47 metrics. DevTools shows 200 network requests. Your PM asks: *"Is it the frontend team or the backend team?"*
+
+**find-bottleneck-perf** answers that question in seconds.
+
+---
+
+## Install
+
+```bash
+# Run directly (no install)
+npx find-bottleneck-perf https://example.com
+
+# Or install globally
+npm install -g find-bottleneck-perf
+find-bottleneck https://example.com
+```
+
+---
+
+## Usage
+
+```bash
+# Basic analysis
+find-bottleneck https://example.com
+
+# Simulate slow network (Slow 3G, Fast 3G, 4G, WiFi)
+find-bottleneck https://example.com --network slow-3g
+
+# Export full report to JSON
+find-bottleneck https://example.com --export report.json
+
+# Combine options
+find-bottleneck https://example.com --network fast-3g --export report.json
+```
+
+---
+
+## What You Get
+
+```
+════════════════════════════════════════════════════════════
+  FIND-BOTTLENECK  │  Performance Analysis Report
+════════════════════════════════════════════════════════════
+
+┌─ THE VERDICT
+│
+│  🖥️  Primary Bottleneck: FRONTEND
+│
+│  Scores: Frontend=19  Backend=5  Infra=2
+└───────────────────────────────────────────────────────────
+
+┌─ EVIDENCE
+│
+│  [Frontend]
+│    ▸ Massive JS bundle (5.66 MB). Implement code splitting.
+│    ▸ 35 render-blocking resources. Use async/defer.
+└───────────────────────────────────────────────────────────
+
+┌─ RECOMMENDATIONS
+│
+│  👉 Implement code splitting (dynamic imports) and tree shaking.
+│  👉 Profile JavaScript with Chrome DevTools Performance tab.
+└───────────────────────────────────────────────────────────
+```
+
+---
+
+## Verdicts Explained
+
+| Verdict | What It Means | Typical Causes |
+|---------|---------------|----------------|
+| **Frontend** | Browser is struggling | Large JS bundles, render-blocking resources, heavy images |
+| **Backend** | Server is slow | Slow APIs, database queries, missing caching |
+| **Infra** | Network is the problem | High latency, slow DNS, distant servers |
+| **Mixed** | Multiple issues | Problems in more than one area |
+| **Optimized** | You're good! | No significant issues detected |
+
+---
+
+## Metrics Collected
+
+| Category | Metrics |
+|----------|---------|
+| **Navigation** | DNS, TCP, TLS, TTFB, Server Processing |
+| **Web Vitals** | FCP, LCP, Total Blocking Time |
+| **Resources** | JS/CSS/Image sizes, Render-blocking count |
+| **APIs** | Request count, Avg/Max latency, Failed requests |
+
+---
+
+## Network Throttling
+
+Test how your site performs on real-world connections:
+
+```bash
+find-bottleneck https://example.com --network slow-3g
+```
+
+| Preset | Speed | Latency | Use Case |
+|--------|-------|---------|----------|
+| `slow-3g` | 500 Kbps | 400ms | Worst-case mobile |
+| `fast-3g` | 1.6 Mbps | 150ms | Typical mobile |
+| `4g` | 4 Mbps | 20ms | Good mobile |
+| `wifi` | 30 Mbps | 2ms | Office/Home WiFi |
+
+---
+
+## JSON Export
+
+```bash
+find-bottleneck https://example.com --export report.json
+```
+
+```json
+{
+  "url": "https://example.com",
+  "verdict": {
+    "primary": "Frontend",
+    "scores": { "Frontend": 15, "Backend": 5, "Infra": 2 }
+  },
+  "metrics": { ... },
+  "evidence": [
+    { "category": "Frontend", "message": "Massive JS bundle (5.15 MB)..." }
+  ],
+  "recommendations": [
+    "Implement code splitting...",
+    "Profile database queries..."
+  ]
+}
+```
+
+---
+
+## How It Works
+
+1. Launches **headless Chrome** via Puppeteer
+2. Intercepts **all network requests** (APIs, JS, CSS, images)
+3. Extracts **Navigation Timing API** and **PerformanceObserver** data
+4. Applies **weighted heuristics** to score Frontend/Backend/Infra
+5. Generates **evidence-based recommendations**
+
+---
+
+## Requirements
+
+- Node.js 18+
+- ~400MB disk space (for Chromium, installed automatically)
+
+---
+
+## License
+
+ISC © Karthik Sake

package/index.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+
+/**
+ * perf-blame-finder
+ * 
+ * A pragmatic CLI tool for identifying web performance bottlenecks.
+ * Analyzes a live URL and determines if the issue is Frontend, Backend, or Infrastructure.
+ * 
+ * Usage: perf-blame <url> [--export <path>] [--network <preset>]
+ */
+
+const { extractMetrics } = require('./src/extractor');
+const { analyze } = require('./src/analyzer');
+const { printReport, exportJson } = require('./src/reporter');
+const { colorize } = require('./src/utils');
+const { NETWORK_PRESETS } = require('./src/thresholds');
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  // --- Parse Arguments ---
+  let url = null;
+  let exportPath = null;
+  let networkPreset = null;
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--export' && args[i + 1]) {
+      exportPath = args[i + 1];
+      i++;
+    } else if (args[i] === '--network' && args[i + 1]) {
+      networkPreset = args[i + 1].toLowerCase();
+      i++;
+    } else if (args[i].startsWith('http')) {
+      url = args[i];
+    }
+  }
+
+  // --- Help / Validation ---
+  if (!url) {
+    const presetList = Object.keys(NETWORK_PRESETS).map(k => `    ${k.padEnd(12)} - ${NETWORK_PRESETS[k].name}`).join('\n');
+
+    console.log(`
+${colorize('perf-blame-finder', 'bright')} - Identify web performance bottlenecks
+
+${colorize('Usage:', 'yellow')}
+  perf-blame <url> [options]
+
+${colorize('Options:', 'yellow')}
+  --export <path>      Export full report to JSON file
+  --network <preset>   Simulate network conditions
+
+${colorize('Network Presets:', 'cyan')}
+${presetList}
+
+${colorize('Examples:', 'dim')}
+  perf-blame https://example.com
+  perf-blame https://example.com --network slow-3g
+  perf-blame https://example.com --network fast-3g --export report.json
+
+${colorize('What it measures:', 'cyan')}
+  • Navigation Timing (DNS, TCP, TLS, TTFB)
+  • Core Web Vitals (FCP, LCP, TBT)
+  • Resource sizes (JS, CSS, Images)
+  • API performance (latency, count, failures)
+  • Derived metrics (server processing, client render time)
+`);
+    process.exit(1);
+  }
+
+  // --- Validate Network Preset ---
+  let networkCondition = null;
+  if (networkPreset) {
+    if (!NETWORK_PRESETS[networkPreset]) {
+      console.error(colorize(`\n❌ Unknown network preset: ${networkPreset}`, 'red'));
+      console.log(`Available presets: ${Object.keys(NETWORK_PRESETS).join(', ')}`);
+      process.exit(1);
+    }
+    networkCondition = NETWORK_PRESETS[networkPreset];
+  }
+
+  // --- Run Analysis ---
+  console.log(colorize(`\n🚀 Launching headless browser...`, 'cyan'));
+  console.log(colorize(`   Target: ${url}`, 'dim'));
+  if (networkCondition) {
+    console.log(colorize(`   Network: ${networkCondition.name}`, 'yellow'));
+  }
+
+  try {
+    // Step 1: Extract metrics (with optional network throttling)
+    const metrics = await extractMetrics(url, { networkCondition });
+
+    // Add network condition to metrics for export
+    if (networkPreset) {
+      metrics.networkCondition = networkPreset;
+    }
+
+    // Step 2: Analyze metrics
+    const analysis = analyze(metrics);
+
+    // Step 3: Print report
+    printReport(analysis);
+
+    // Step 4: Export if requested
+    if (exportPath) {
+      exportJson(analysis, exportPath);
+    }
+
+  } catch (err) {
+    console.error(colorize(`\n❌ Analysis failed: ${err.message}`, 'red'));
+    process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,44 @@
+{
+    "name": "find-bottleneck-perf",
+    "version": "1.0.0",
+    "description": "CLI tool that analyzes web performance and tells you who to blame: Frontend, Backend, or Infrastructure",
+    "main": "index.js",
+    "bin": {
+        "find-bottleneck": "./index.js"
+    },
+    "files": [
+        "index.js",
+        "src/",
+        "README.md"
+    ],
+    "scripts": {
+        "test": "node index.js https://example.com"
+    },
+    "keywords": [
+        "performance",
+        "bottleneck",
+        "web-vitals",
+        "lcp",
+        "ttfb",
+        "lighthouse",
+        "puppeteer",
+        "cli",
+        "frontend",
+        "backend",
+        "infrastructure",
+        "devtools",
+        "network-throttling"
+    ],
+    "author": "Karthik Sake",
+    "license": "ISC",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/karthiksake/find-bottleneck-perf"
+    },
+    "engines": {
+        "node": ">=18.0.0"
+    },
+    "dependencies": {
+        "puppeteer": "^23.0.0"
+    }
+}