react-doctor-cli-dev 1.0.0

package/core/rule-engine/suggestion-builder.ts

@@ -0,0 +1,209 @@
+// Takes a fired rule and the evaluation context, and produces
+// a clean Suggestion object ready for the report.
+//
+// The key job of this file is PLACEHOLDER RESOLUTION.
+// Rule messages in rules.json contain tokens like {metrics.lcp}
+// that get replaced with real values from the context.
+//
+// Example:
+//   Template: "Your LCP is {metrics.lcp}ms."
+//   Context:   metrics.lcp = 2396
+//   Output:    "Your LCP is 2396ms."
+//
+// This makes every suggestion specific to the actual project
+// being analyzed — not just generic advice.
+// ─────────────────────────────────────────────────────────────
+
+import { Suggestion } from "../../shared/src/types";
+import { RuleDefinition, EvaluationContext } from "./types";
+
+/**
+ * Builds a Suggestion object from a fired rule and the context.
+ *
+ * The returned Suggestion has:
+ *   id                — same as the rule id
+ *   title             — the rule title (no placeholders)
+ *   description       — the rule message with placeholders resolved
+ *   severity          — copied from the rule
+ *   affectedComponent — the most relevant component name (if any)
+ *   fix               — the concrete fix instructions
+ *
+ * @param rule    — the rule that fired
+ * @param context — the context used to resolve placeholders
+ */
+export function buildSuggestion(
+  rule:    RuleDefinition,
+  context: EvaluationContext,
+): Suggestion {
+  // Resolve all {placeholder} tokens in the message string.
+  // The fix string can also contain placeholders like {component}.
+  const description = resolvePlaceholders(rule.message, context);
+  const fix         = resolvePlaceholders(rule.fix,     context);
+
+  // Find the most relevant component name for this suggestion.
+  // We use this to populate the affectedComponent field, which
+  // the dashboard uses to highlight the specific component.
+  const affectedComponent = resolveAffectedComponent(rule, context);
+
+  return {
+    id:          rule.id,
+    title:       rule.title,
+    description,
+    severity:    rule.severity,
+    fix,
+    ...(affectedComponent ? { affectedComponent } : {}),
+  };
+}
+
+/**
+ * Resolves {placeholder} tokens in a template string.
+ *
+ * Supported placeholders and what they resolve to:
+ *
+ *   {metrics.lcp}     → actual LCP value rounded to nearest ms
+ *   {metrics.fcp}     → actual FCP value rounded to nearest ms
+ *   {metrics.cls}     → CLS score rounded to 3 decimal places
+ *   {metrics.inp}     → INP value rounded to nearest ms
+ *   {metrics.ttfb}    → TTFB value rounded to nearest ms
+ *   {renderTime}      → total render time in ms
+ *   {commitDuration}  → slowest React commit duration in ms
+ *   {avgCommit}       → average commit duration in ms (1 decimal)
+ *   {rerenders}       → re-render count of the top component
+ *   {component}       → name of the most re-rendered component
+ *   {domNodes}        → number of DOM nodes
+ *   {payloadMB}       → page weight in MB (2 decimal places)
+ *   {jsHeapMB}        → JS heap usage in MB (2 decimal places)
+ *   {errorCount}      → number of JS errors
+ *   {performanceScore}→ 0-100 performance score
+ *
+ * Unknown placeholders are left as-is so they don't silently
+ * disappear if there's a typo in rules.json.
+ */
+function resolvePlaceholders(
+  template: string,
+  context:  EvaluationContext,
+): string {
+  // Build a map of all known placeholder names → resolved values.
+  // We format numbers here so the messages read naturally.
+  const values: Record<string, string> = {
+    "metrics.lcp":      `${Math.round(context.metrics.lcp)}`,
+    "metrics.fcp":      `${Math.round(context.metrics.fcp)}`,
+    "metrics.cls":      `${context.metrics.cls.toFixed(3)}`,
+    "metrics.inp":      `${Math.round(context.metrics.inp)}`,
+    "metrics.ttfb":     `${Math.round(context.metrics.ttfb)}`,
+    "renderTime":       `${context.renderTime}`,
+    "commitDuration":   `${context.slowestCommit.toFixed(1)}`,
+    "avgCommit":        `${context.avgCommit.toFixed(1)}`,
+    "rerenders":        `${context.topRerenderCount}`,
+    "component":        context.topRerenderComponent || "unknown",
+    "domNodes":         `${context.domNodes}`,
+    "payloadMB":        `${context.payloadMB.toFixed(2)}`,
+    "jsHeapMB":         `${context.jsHeapMB.toFixed(2)}`,
+    "errorCount":       `${context.errorCount}`,
+    "slowCommitCount":  `${context.slowCommitCount}`,
+    "performanceScore": `${context.performanceScore}`,
+  };
+
+  // Replace every {placeholder} in the template string.
+  // The regex matches anything between { and } and looks it up
+  // in the values map above.
+  return template.replace(/\{([^}]+)\}/g, (match, key) => {
+    // If the key is known, return its value. Otherwise keep the
+    // original {key} so the developer knows something is missing.
+    return values[key] ?? match;
+  });
+}
+
+/**
+ * Determines which component is most relevant to this suggestion.
+ *
+ * Priority order:
+ *   1. If the rule is about re-renders, use the top re-render component
+ *   2. If there's a static issue matching the rule category, use that component
+ *   3. Otherwise return undefined (no specific component to blame)
+ *
+ * The affectedComponent name is shown in the dashboard to help
+ * the developer navigate directly to the problematic file.
+ */
+function resolveAffectedComponent(
+  rule:    RuleDefinition,
+  context: EvaluationContext,
+): string | undefined {
+  // For re-render related rules, the top re-render component is the target.
+  // These rules fire because a specific component is re-rendering too much,
+  // so we point the developer directly at that component.
+  //
+  // NOTE: "inline-function" is intentionally excluded here now — the new
+  // static-only "inline-functions-detected" rule should resolve its component
+  // from the static issues map below, not from the re-render data. The cross
+  // rule "inline-functions-with-high-rerenders" still uses the re-render data
+  // because it fires when both are true.
+  if (
+    rule.id.includes("excessive-rerender") ||
+    rule.id.includes("missing-memo")       ||
+    rule.id.includes("slow-commit")        ||
+    rule.id === "inline-functions-with-high-rerenders"
+  ) {
+    if (context.topRerenderComponent) {
+      return context.topRerenderComponent;
+    }
+  }
+
+  // For static rules (and cross rules with a static component), find the
+  // first matching issue's component name from the static report.
+  //
+  // The map below links each rule ID to the issue ID prefix it targets.
+  // Example: "missing-list-keys" targets issues starting with "missing-key"
+  // because generateIssueId('missing-key', file, line) is how the detector
+  // names them. startsWith() catches all of them regardless of file/line.
+  //
+  // FIX: Added "inline-functions-detected" for the new static-only rule.
+  // FIX: console-log and dead-code issues DO carry a component name from
+  //      the detector — they were already in the map and working correctly.
+  const staticPrefixMap: Record<string, string> = {
+    "console-logs-in-production":           "console-log",
+    "missing-list-keys":                    "missing-key",
+    "inline-styles-detected":               "inline-style",
+    "prop-drilling-detected":               "prop-drilling",
+    "dead-code-detected":                   "dead-code",
+    "effect-loop-risk":                     "effect-loop",
+    "missing-memo-with-rerenders":          "missing-memo",
+    "large-component-with-slow-commit":     "large-component",
+    "inline-functions-with-high-rerenders": "inline-function",
+    "inline-functions-detected":            "inline-function",  // FIX: new rule
+    "missing-memo-with-slow-commit":        "missing-memo",
+    "prop-drilling-with-rerenders":         "prop-drilling",
+  };
+
+  const prefix = staticPrefixMap[rule.id];
+  if (prefix) {
+    const matchingIssue = context.issues.find(i => i.id.startsWith(prefix));
+    if (matchingIssue?.component) {
+      return matchingIssue.component;
+    }
+  }
+
+  // Rules like slow-lcp, slow-ttfb, heavy-payload, high-dom-nodes,
+  // low-performance-score are page-level — no single component to blame.
+  return undefined;
+}
+
+/**
+ * Builds all suggestions from a list of fired rules.
+ * Sorts them by severity: critical → warning → info.
+ *
+ * @param firedRules — rules whose conditions evaluated to true
+ * @param context    — the evaluation context for placeholder resolution
+ */
+export function buildAllSuggestions(
+  firedRules: RuleDefinition[],
+  context:    EvaluationContext,
+): Suggestion[] {
+  const severityOrder = { critical: 0, warning: 1, info: 2 };
+
+  return firedRules
+    .map(rule => buildSuggestion(rule, context))
+    .sort((a, b) =>
+      (severityOrder[a.severity] ?? 3) - (severityOrder[b.severity] ?? 3),
+    );
+}

package/core/rule-engine/test-rule-engine.ts

@@ -0,0 +1,144 @@
+// Test runner for the Rule Engine.
+// Reads the existing staticreport.json and runtimereport.json
+// from core/reports/ and runs the Rule Engine against them.
+//
+// Usage:
+//   npx ts-node --compiler-options '{"module":"commonjs"}'
+//   rule-engine/test-rule-engine.ts
+// ─────────────────────────────────────────────────────────────
+
+import path from "path";
+import fs   from "fs-extra";
+import { RuleEngine }    from "./index";
+import { StaticReport, RuntimeReport } from "../../shared/src/types";
+import { RuleEngineResult } from "./types";
+
+// ── Severity badge helpers ────────────────────────────────────
+
+function severityIcon(s: string): string {
+  if (s === "critical") return "❌";
+  if (s === "warning")  return "⚠️ ";
+  return "ℹ️ ";
+}
+
+function severityLabel(s: string): string {
+  if (s === "critical") return "CRITICAL";
+  if (s === "warning")  return "WARNING";
+  return "INFO";
+}
+
+// ── Load reports ─────────────────────────────────────────────
+
+async function loadReports(): Promise<{
+  staticReport:   StaticReport  | null;
+  runtimeReports: Record<string, RuntimeReport>;
+}> {
+  // Reports live in core/reports/ — one level up from rule-engine/
+  const reportsDir = path.resolve(__dirname, "..", "reports");
+
+  const staticPath  = path.join(reportsDir, "staticreport.json");
+  const runtimePath = path.join(reportsDir, "runtimereport.json");
+
+  let staticReport: StaticReport | null = null;
+  let runtimeReports: Record<string, RuntimeReport> = {};
+
+  // Load static report if it exists
+  if (fs.existsSync(staticPath)) {
+    staticReport = await fs.readJson(staticPath);
+    console.log(`✅ Loaded staticreport.json`);
+  } else {
+    console.log(`⚠️  staticreport.json not found — running without static data`);
+  }
+
+  // Load runtime report if it exists
+  if (fs.existsSync(runtimePath)) {
+    runtimeReports = await fs.readJson(runtimePath);
+    const routeCount = Object.keys(runtimeReports).length;
+    console.log(`✅ Loaded runtimereport.json (${routeCount} route(s))`);
+  } else {
+    console.log(`⚠️  runtimereport.json not found — running without runtime data`);
+  }
+
+  return { staticReport, runtimeReports };
+}
+
+// ── Print results ─────────────────────────────────────────────
+
+function printResults(results: RuleEngineResult[]): void {
+  for (const result of results) {
+    console.log(`\n${"=".repeat(60)}`);
+    console.log(`📍 Route: ${result.route}  [${result.device}]`);
+    console.log(`${"=".repeat(60)}`);
+    console.log(`   Total suggestions: ${result.summary.total}`);
+    console.log(`   ❌ Critical: ${result.summary.critical}`);
+    console.log(`   ⚠️  Warnings: ${result.summary.warning}`);
+    console.log(`   ℹ️  Info:     ${result.summary.info}`);
+
+    if (result.suggestions.length === 0) {
+      console.log("\n   ✅ No issues found — great work!\n");
+      continue;
+    }
+
+    console.log();
+
+    for (const suggestion of result.suggestions) {
+      const icon = severityIcon(suggestion.severity);
+      const label = severityLabel(suggestion.severity);
+
+      console.log(`${icon}  [${label}] ${suggestion.title}`);
+
+      if (suggestion.affectedComponent) {
+        console.log(`   Component: ${suggestion.affectedComponent}`);
+      }
+
+      console.log(`   ${suggestion.description}`);
+      console.log();
+      console.log(`   Fix:`);
+
+      // Print each line of the fix indented for readability
+      suggestion.fix.split("\n").forEach(line => {
+        console.log(`     ${line}`);
+      });
+
+      console.log(`${"─".repeat(60)}`);
+    }
+  }
+}
+
+// ── Main ──────────────────────────────────────────────────────
+
+async function main() {
+  console.log("=========================================================");
+  console.log("🧠  REACT DOCTOR — RULE ENGINE TEST");
+  console.log("=========================================================\n");
+
+  // Load reports from disk
+  const { staticReport, runtimeReports } = await loadReports();
+
+  if (!staticReport && Object.keys(runtimeReports).length === 0) {
+    console.error(
+      "\n❌ No reports found.\n" +
+      "   Run the static analyzer or profiler first:\n" +
+      "   npx ts-node ... static-ana/test-analyzer.ts\n" +
+      "   npx ts-node ... runtime/test-runtime-profiler.ts <path>\n",
+    );
+    process.exit(1);
+  }
+
+  // Run the Rule Engine
+  const engine  = new RuleEngine();
+  const results = await engine.run(staticReport, runtimeReports);
+
+  // Print results to terminal
+  printResults(results);
+
+  console.log("\n=========================================================");
+  console.log("✅ Rule Engine test complete.");
+  console.log(`📄 Suggestions saved to: core/reports/suggestions.json`);
+  console.log("=========================================================\n");
+}
+
+main().catch(err => {
+  console.error("\n❌ Rule Engine error:", err.message);
+  process.exit(1);
+});

package/core/rule-engine/types.ts

@@ -0,0 +1,202 @@
+import { StaticReport, RuntimeReport, Suggestion } from "../../shared/src/types";
+// ─────────────────────────────────────────────────────────────
+// RULE DEFINITION
+//
+// This is the shape of each entry inside rules.json.
+// When you add a new rule, you write it as this interface.
+//
+// Example rule:
+//   {
+//     "id": "slow-lcp",
+//     "category": "runtime",
+//     "severity": "critical",
+//     "title": "LCP is too slow",
+//     "condition": { "runtime": "metrics.lcp > 2500" },
+//     "message": "Your LCP is {metrics.lcp}ms. Consider lazy-loading your hero image.",
+//     "fix": "Add loading='lazy' to your largest above-the-fold image."
+//   }
+// ─────────────────────────────────────────────────────────────
+
+export interface RuleCondition {
+  // A JavaScript expression string evaluated against the runtime report.
+  // Example: "metrics.lcp > 2500"
+  // Example: "rerenders['Divider'] >= 5"
+  // Can be undefined if this rule doesn't check runtime data.
+  runtime?: string;
+
+  // A JavaScript expression string evaluated against the static report.
+  // Example: "issues.some(i => i.id.startsWith('missing-memo'))"
+  // Example: "issues.filter(i => i.id.startsWith('console-log')).length > 0"
+  // Can be undefined if this rule doesn't check static data.
+  static?: string;
+}
+
+export interface RuleDefinition {
+  // Unique identifier for this rule — used to deduplicate suggestions
+  // and reference specific rules in tests.
+  // Example: "slow-lcp", "missing-memo-with-rerenders"
+  id: string;
+
+  // Which category this rule belongs to:
+  //   "runtime" — only uses data from the runtime profiler
+  //   "static"  — only uses data from the static analyzer
+  //   "cross"   — combines both reports for a deeper insight
+  //               Cross rules are the most powerful — they catch
+  //               problems that neither analysis alone could find.
+  category: "runtime" | "static" | "cross";
+
+  // How serious this problem is:
+  //   "critical" — must fix, directly hurts users
+  //   "warning"  — should fix, noticeable impact
+  //   "info"     — nice to fix, minor improvement
+  severity: "critical" | "warning" | "info";
+
+  // Short headline shown in the dashboard and terminal output.
+  // Example: "LCP is too slow"
+  title: string;
+
+  // The condition(s) that must be true for this rule to fire.
+  // For "runtime" category: only condition.runtime is required.
+  // For "static"  category: only condition.static is required.
+  // For "cross"   category: BOTH must be true simultaneously.
+  condition: RuleCondition;
+
+  // The explanation message shown to the developer.
+  // Supports {placeholder} tokens that get replaced with real values.
+  // Available tokens:
+  //   {metrics.lcp}     — actual LCP value from the runtime report
+  //   {metrics.fcp}     — actual FCP value
+  //   {renderTime}      — total render time
+  //   {component}       — name of the affected component (if found)
+  //   {rerenders}       — re-render count of the affected component
+  //   {commitDuration}  — slowest commit duration
+  // Example: "Your LCP is {metrics.lcp}ms — users wait too long."
+  message: string;
+
+  // A concrete, actionable fix the developer can apply right now.
+  // Be specific — not "improve performance" but "add React.lazy() to..."
+  fix: string;
+}
+
+// ─────────────────────────────────────────────────────────────
+// EVALUATION CONTEXT
+//
+// This object is assembled from both reports and passed to the
+// evaluator. It contains everything a rule condition can access.
+//
+// When a condition string like "metrics.lcp > 2500" is evaluated,
+// it runs as a JS expression with this object as its scope.
+// ─────────────────────────────────────────────────────────────
+
+export interface EvaluationContext {
+  // ── Runtime fields ──────────────────────────────────────────
+  // The 5 web vitals (all in ms except cls which is a score)
+  metrics: {
+    lcp:  number;
+    fcp:  number;
+    cls:  number;
+    inp:  number;
+    ttfb: number;
+  };
+
+  // Total time from navigation start to networkidle0 (ms)
+  renderTime: number;
+
+  // Re-render counts per component: { "Divider": 5, "App": 1, ... }
+  rerenders: Record<string, number>;
+
+  // How long each React commit took in ms: [40.2, 1.1, 8.7]
+  commitDurations: number[];
+
+  // Slowest single commit duration in ms (0 if no commits recorded)
+  slowestCommit: number;
+
+  // Average commit duration in ms (0 if no commits recorded)
+  avgCommit: number;
+
+  // Number of commits that exceeded the 16ms 60fps budget
+  slowCommitCount: number;
+
+  // Total number of DOM elements on the page
+  domNodes: number;
+
+  // Total page payload in MB (as a number, not a string)
+  payloadMB: number;
+
+  // JS heap usage in MB (as a number, not a string)
+  jsHeapMB: number;
+
+  // JS errors caught during page load
+  errors: Array<{ type: "error" | "warning"; message: string }>;
+
+  // Number of JS errors (shorthand for errors.filter(...).length)
+  errorCount: number;
+
+  // Number of console warnings
+  warningCount: number;
+
+  // The 0–100 performance score calculated by the profiler
+  performanceScore: number;
+
+  // ── Static fields ────────────────────────────────────────────
+  // All issues found by the static analyzer
+  issues: Array<{
+    id: string;
+    component: string;
+    file: string;
+    line: number;
+    severity: string;
+    message: string;
+  }>;
+
+  // Shorthand counts by severity
+  criticalIssueCount: number;
+  warningIssueCount:  number;
+
+  // True if any issue ID starts with the given prefix.
+  // Used in conditions like: hasIssue('missing-memo')
+  // This is a function placed on the context object so conditions
+  // can call it: "hasIssue('missing-memo')"
+  hasIssue: (prefix: string) => boolean;
+
+  // Returns all issues whose ID starts with the given prefix.
+  // Used when you need the actual issue objects in a condition.
+  // Example: "getIssues('large-component').length > 0"
+  getIssues: (prefix: string) => EvaluationContext["issues"];
+
+  // The name of the component most affected (highest re-render count).
+  // Used in message placeholders: "Wrap {component} in React.memo()"
+  topRerenderComponent: string;
+
+  // The re-render count of the top component above
+  topRerenderCount: number;
+}
+
+// ─────────────────────────────────────────────────────────────
+// RULE ENGINE RESULT
+//
+// The final output of the Rule Engine — what gets written to
+// suggestions.json and passed to the Report Compiler.
+// ─────────────────────────────────────────────────────────────
+
+export interface RuleEngineResult {
+  // ISO timestamp of when the rule engine ran
+  timestamp: string;
+
+  // Which route was analyzed (e.g. "/" or "/about")
+  route: string;
+
+  // Which device the runtime report came from
+  device: string;
+
+  // All generated suggestions, sorted by severity (critical first)
+  suggestions: Suggestion[];
+
+  // Summary counts for quick display
+  summary: {
+    critical: number;
+    warning:  number;
+    info:     number;
+    total:    number;
+  };
+}

package/core/runtime/profiler/browser.ts

@@ -0,0 +1,121 @@
+import os from "os";
+import path from "path";
+import fs from "fs-extra";
+import { execSync } from "child_process";
+
+/**
+ * Finds and returns the path to the Chrome/Chromium executable.
+ *
+ * Windows: checks common installation paths including per-user AppData.
+ * Linux:   checks all known system paths + tries `which` as a fallback.
+ * macOS:   checks the standard Applications folder.
+ *
+ * Throws a clear error if no browser is found.
+ */
+export function getBrowserPath(): string {
+  const platform = os.platform();
+
+  if (platform === "win32") {
+    const winPaths = [
+      "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+      "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+      `C:\\Users\\${os.userInfo().username}\\AppData\\Local\\Google\\Chrome\\Application\\chrome.exe`,
+      "C:\\Program Files\\Chromium\\Application\\chrome.exe",
+    ];
+    for (const p of winPaths) {
+      if (fs.existsSync(p)) return p;
+    }
+    throw new Error(
+      "❌ Chrome not found! Please install Google Chrome on Windows.\n" +
+      "   Download: https://www.google.com/chrome/",
+    );
+  }
+
+  if (platform === "darwin") {
+    const macPaths = [
+      "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+      "/Applications/Chromium.app/Contents/MacOS/Chromium",
+    ];
+    for (const p of macPaths) {
+      if (fs.existsSync(p)) return p;
+    }
+    throw new Error(
+      "❌ Chrome not found! Please install Google Chrome on macOS.\n" +
+      "   Download: https://www.google.com/chrome/",
+    );
+  }
+
+  // Linux — check all known install locations
+  const linuxPaths = [
+    "/usr/bin/google-chrome",
+    "/usr/bin/google-chrome-stable",
+    "/usr/bin/chromium",
+    "/usr/bin/chromium-browser",
+    "/usr/local/bin/chrome",
+    "/usr/local/bin/chromium",
+    "/opt/google/chrome/chrome",
+    "/opt/google/chrome/google-chrome",
+    "/snap/bin/chromium",
+    "/snap/bin/google-chrome",
+  ];
+
+  for (const p of linuxPaths) {
+    if (fs.existsSync(p)) return p;
+  }
+
+  // Last resort: try `which` to find it anywhere on PATH
+  for (const cmd of ["google-chrome", "google-chrome-stable", "chromium", "chromium-browser"]) {
+    try {
+      const result = execSync(`which ${cmd}`, { stdio: ["ignore", "pipe", "ignore"] })
+        .toString()
+        .trim();
+      if (result && fs.existsSync(result)) return result;
+    } catch {
+      // not found via which, try next
+    }
+  }
+
+  throw new Error(
+    "❌ No compatible browser found on Linux!\n\n" +
+    "   Install one of the following:\n" +
+    "     Ubuntu/Debian: sudo apt install chromium-browser\n" +
+    "     Fedora:        sudo dnf install chromium\n" +
+    "     Snap:          sudo snap install chromium\n" +
+    "     Or install Google Chrome from: https://www.google.com/chrome/",
+  );
+}
+
+/**
+ * Reads the web-vitals IIFE bundle from local node_modules.
+ *
+ * Uses { content } injection — NO network request, works offline.
+ */
+export function getWebVitalsScript(projectPath: string, profilerDir: string): string {
+  const filename = "web-vitals.iife.js";
+
+  const candidates: string[] = [
+    path.resolve(profilerDir, "..", "..", "..", "node_modules", "web-vitals", "dist", filename),
+    path.resolve(profilerDir, "..", "..", "..", "..", "node_modules", "web-vitals", "dist", filename),
+    path.join(projectPath, "node_modules", "web-vitals", "dist", filename),
+  ];
+
+  try {
+    const pkgJson = require.resolve("web-vitals/package.json");
+    candidates.push(path.join(path.dirname(pkgJson), "dist", filename));
+  } catch {
+    // not resolvable from this module — fine, we have other candidates
+  }
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      console.log(`   ✅ web-vitals loaded from disk (offline-safe)`);
+      return fs.readFileSync(candidate, "utf-8");
+    }
+  }
+
+  const searched = candidates.map(c => `\n      ${c}`).join("");
+  throw new Error(
+    `❌ web-vitals not found.\n\n   Searched in:${searched}\n\n` +
+    `   Fix: run "npm install web-vitals" inside react-tool/\n`,
+  );
+}