react-doctor-cli-dev 1.0.0

package/core/runtime/profiler/route-scanner.ts

@@ -0,0 +1,76 @@
+import path from "path";
+import fs from "fs-extra";
+import * as parser from "@babel/parser";
+import * as traverseLib from "@babel/traverse";
+
+const traverse: Function = (traverseLib as any).default ?? (traverseLib as any);
+
+export class RouteScanner {
+  static async scanForRoutes(projectPath: string): Promise<string[]> {
+    const routes: string[] = ["/"];
+
+    const potentialFiles = [
+      path.join(projectPath, "src", "App.tsx"),
+      path.join(projectPath, "src", "App.jsx"),
+      path.join(projectPath, "src", "main.tsx"),
+      path.join(projectPath, "src", "main.jsx"),
+      path.join(projectPath, "src", "routes.tsx"),
+      path.join(projectPath, "src", "routes.jsx"),
+      path.join(projectPath, "src", "router.tsx"),
+      path.join(projectPath, "src", "router.jsx"),
+    ];
+
+    for (const filePath of potentialFiles) {
+      if (!fs.existsSync(filePath)) continue;
+
+      try {
+        const code = await fs.readFile(filePath, "utf-8");
+        const ast  = parser.parse(code, {
+          sourceType: "module",
+          plugins: ["jsx", "typescript"],
+        });
+
+        traverse(ast, {
+          // ── React Router v5: <Route path="/foo" /> ──────────
+          JSXOpeningElement(p: any) {
+            const isRoute = (p.node.name as any).name === "Route";
+            if (isRoute) {
+              const pathAttr = p.node.attributes.find(
+                (attr: any) => attr.name?.name === "path",
+              );
+              if (
+                pathAttr &&
+                "value" in pathAttr &&
+                pathAttr.value?.type === "StringLiteral"
+              ) {
+                routes.push(pathAttr.value.value);
+              }
+            }
+          },
+
+          // ── React Router v6: createBrowserRouter([{ path: "/foo" }]) ──
+          ObjectExpression(p: any) {
+            const pathProp = p.node.properties.find(
+              (prop: any) =>
+                prop.type === "ObjectProperty" &&
+                prop.key?.name === "path" &&
+                prop.value?.type === "StringLiteral",
+            );
+            if (pathProp) {
+              const routePath = pathProp.value.value;
+              // Skip dynamic segments like /docs/:id — only add static base routes
+              if (!routePath.includes(":")) {
+                routes.push(routePath);
+              }
+            }
+          },
+        });
+      } catch {
+        // Skip files that fail to parse silently
+      }
+    }
+
+    const result = [...new Set(routes)];
+    return result.length > 0 ? result : ["/"];
+  }
+}

package/core/runtime/profiler/score.ts

@@ -0,0 +1,59 @@
+import { WebVitals, PageError } from "../../../shared/src/types";
+
+/**
+ * Calculates a 0–100 performance score from all collected metrics.
+ *
+ * Each metric is normalized to 0–100 based on its good/poor threshold,
+ * then a weighted average is computed. Weights must sum to 1.0:
+ *
+ *   LCP         0.30  — biggest impact on perceived load speed
+ *   Render time 0.20  — total time to interactive
+ *   FCP         0.15  — first sign of life
+ *   Commit avg  0.15  — React rendering efficiency
+ *   TTFB        0.10  — server response speed
+ *   CLS         0.05  — visual stability
+ *   INP         0.05  — interaction responsiveness
+ *
+ * Score bands: 90–100 Excellent, 70–89 Good, 50–69 Needs Work, <50 Poor.
+ *
+ * Penalties:
+ *   Each JS error   → -5 points (capped at -20)
+ *   Each warning    → -2 points (capped at -10)
+ */
+export function calculatePerformanceScore(
+  vitals: WebVitals,
+  renderTime: number,
+  commitDurations: number[],
+  errors: PageError[],
+): number {
+  // Normalize a value to 0–100 where lower is better
+  function normalize(value: number, good: number, poor: number): number {
+    if (value <= good) return 100;
+    if (value >= poor) return 0;
+    return Math.round(100 * (1 - (value - good) / (poor - good)));
+  }
+
+  const avgCommit = commitDurations.length > 0
+    ? commitDurations.reduce((a, b) => a + b, 0) / commitDurations.length
+    : 0;
+
+  const scores = {
+    lcp:        normalize(vitals.lcp,  2500, 4000) * 0.30,
+    renderTime: normalize(renderTime,  2000, 5000) * 0.20,
+    fcp:        normalize(vitals.fcp,  1800, 3000) * 0.15,
+    commitAvg:  normalize(avgCommit,   16,   100)  * 0.15,
+    ttfb:       normalize(vitals.ttfb, 800,  1800) * 0.10,
+    cls:        normalize(vitals.cls,  0.1,  0.25) * 0.05,
+    inp:        normalize(vitals.inp,  200,  500)  * 0.05,
+  };
+
+  let score = Object.values(scores).reduce((a, b) => a + b, 0);
+
+  const errorCount   = errors.filter(e => e.type === "error").length;
+  const warningCount = errors.filter(e => e.type === "warning").length;
+  score -= Math.min(errorCount   * 5, 20);
+  score -= Math.min(warningCount * 2, 10);
+
+  return Math.max(0, Math.min(100, Math.round(score)));
+}
+

package/core/runtime/profiler/server.ts

@@ -0,0 +1,115 @@
+import { spawn, ChildProcess, execSync } from "child_process";
+import path from "path";
+import fs from "fs-extra";
+import os from "os";
+
+/**
+ * Detects which package manager the project uses by checking
+ * for lock files, then spawns the dev server as a background
+ * child process.
+ *
+ * Windows: shell:true so npm.cmd resolves correctly.
+ * Linux:   tries /bin/bash first, falls back to /bin/sh if bash
+ *          is not present (Alpine, minimal containers, etc).
+ */
+export function spawnDevServer(projectPath: string): ChildProcess {
+  const isWin = os.platform() === "win32";
+
+  const pkgManager = fs.existsSync(path.join(projectPath, "yarn.lock"))
+    ? "yarn"
+    : fs.existsSync(path.join(projectPath, "pnpm-lock.yaml"))
+    ? "pnpm"
+    : "npm";
+
+  console.log(`📦 Starting ${pkgManager} dev server...`);
+
+  // On Linux, prefer bash but fall back to sh if bash is missing
+  const shell = isWin
+    ? true
+    : fs.existsSync("/bin/bash")
+    ? "/bin/bash"
+    : "/bin/sh";
+
+  return spawn(pkgManager, ["run", "dev"], {
+    cwd:         projectPath,
+    shell,
+    env: {
+      ...process.env,
+      ...(isWin ? {} : { PATH: process.env.PATH + ":/usr/local/bin:/usr/bin:/bin" }),
+    },
+    detached:    !isWin,
+    stdio:       ["ignore", "pipe", "pipe"],
+    windowsHide: true,
+  });
+}
+
+/**
+ * Watches the dev server's stdout and stderr for a port number.
+ *
+ * Handles both "localhost:PORT" and "127.0.0.1:PORT" since
+ * some Linux setups print the IP instead of the hostname.
+ * Also handles "port PORT" format used by some dev servers.
+ */
+export function waitForServer(devServer: ChildProcess): Promise<number> {
+  return new Promise((resolve, reject) => {
+    let resolved = false;
+
+    const timeout = setTimeout(
+      () => reject(new Error("⏱️ Dev server timed out after 60 seconds!")),
+      60000,
+    );
+
+    const onData = (data: Buffer) => {
+      // Strip ANSI color codes before running the regex
+      const output = data.toString().replace(/\x1B\[[0-9;]*[mGKHF]/g, "");
+      console.log(`   ${output.trim()}`);
+
+      // Match "localhost:PORT", "127.0.0.1:PORT", or "port PORT"
+      const match =
+        output.match(/(?:localhost|127\.0\.0\.1):(\d+)/) ??
+        output.match(/port\s+(\d+)/i);
+
+      if (match && !resolved) {
+        resolved = true;
+        clearTimeout(timeout);
+        devServer.stdout?.off("data", onData);
+        devServer.stderr?.off("data", onData);
+        const port = parseInt(match[1], 10);
+        // 2-second buffer: Vite announces port before it's fully bound
+        setTimeout(() => resolve(port), 2000);
+      }
+    };
+
+    devServer.stdout?.on("data", onData);
+    devServer.stderr?.on("data", onData);
+
+    devServer.on("error", (err) => {
+      clearTimeout(timeout);
+      reject(new Error(`❌ Dev server failed to start: ${err.message}`));
+    });
+  });
+}
+
+/**
+ * Kills the dev server process tree cleanly on both platforms.
+ *
+ * Linux:   process.kill(-pid) sends SIGTERM to the entire process group.
+ * Windows: taskkill /F /T kills the process tree.
+ * ESRCH:   process already stopped — ignored safely.
+ */
+export function killDevServer(devServer: ChildProcess): void {
+  if (!devServer.pid) return;
+
+  try {
+    if (os.platform() === "win32") {
+      spawn("taskkill", ["/pid", devServer.pid.toString(), "/f", "/t"]);
+    } else {
+      process.kill(-devServer.pid);
+    }
+  } catch (error) {
+    const err = error as any;
+    if (err.code !== "ESRCH") {
+      console.warn(`   ⚠️ Cleanup warning: ${err.message}`);
+    }
+  }
+}

package/core/runtime/profiler/types.ts

@@ -0,0 +1,65 @@
+export interface ReactProfilerData {
+  rerenders: Record<string, number>;
+  commitDurations: number[];
+  renderTime: number;
+}
+
+export type DeviceType     = "desktop" | "mobile";
+export type ThrottlePreset = "none" | "slow4g" | "3g";
+
+/**
+ * CPU throttle rate for Chrome's Emulation.setCPUThrottlingRate.
+ * 1 = real hardware speed
+ * 4 = 4x slowdown — matches Lighthouse mobile preset (mid-range Android)
+ * 6 = 6x slowdown — low-end device simulation
+ *
+ * Works on localhost because it slows JS execution itself, not network.
+ */
+export type CpuThrottle = 1 | 4 | 6;
+
+export interface ProfileOptions {
+  // Single device or array to test both in one run
+  device?: DeviceType | DeviceType[];
+  throttle?: ThrottlePreset;
+  // 1 = no throttle (default), 4 = Lighthouse mobile, 6 = low-end
+  cpuThrottle?: CpuThrottle;
+}
+
+// ─────────────────────────────────────────────────────────────
+// NETWORK PRESETS  (Chrome DevTools Protocol values)
+// downloadThroughput and uploadThroughput are in bytes/sec
+// ─────────────────────────────────────────────────────────────
+export const NETWORK_PRESETS = {
+  none: null,
+  slow4g: {
+    downloadThroughput: (9 * 1024 * 1024) / 8,
+    uploadThroughput:   (750 * 1024) / 8,
+    latency: 170,
+  },
+  "3g": {
+    downloadThroughput: (1.5 * 1024 * 1024) / 8,
+    uploadThroughput:   (750 * 1024) / 8,
+    latency: 300,
+  },
+} as const;
+
+// ─────────────────────────────────────────────────────────────
+// DEVICE PRESETS
+// ─────────────────────────────────────────────────────────────
+export const DEVICE_PRESETS = {
+  desktop: {
+    viewport:  { width: 1280, height: 720 },
+    userAgent: null,
+    hasTouch:  false,
+    isMobile:  false,
+  },
+  mobile: {
+    viewport:  { width: 390, height: 844 },  // iPhone 12 Pro
+    userAgent:
+      "Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X) " +
+      "AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.0 " +
+      "Mobile/15E148 Safari/604.1",
+    hasTouch:  true,
+    isMobile:  true,
+  },
+} as const;

package/core/runtime/test-runtime-profiler.ts

@@ -0,0 +1,226 @@
+import { RuntimeProfiler } from "./profiler";
+
+import path from "path";
+
+// ─────────────────────────────────────────────────────────────
+// STATUS HELPERS
+// ─────────────────────────────────────────────────────────────
+
+type VitalKey = "lcp" | "fcp" | "ttfb" | "inp" | "cls";
+
+const vitalThresholds: Record<VitalKey, { good: number; poor: number }> = {
+  lcp:  { good: 2500, poor: 4000 },
+  fcp:  { good: 1800, poor: 3000 },
+  ttfb: { good: 800,  poor: 1800 },
+  inp:  { good: 200,  poor: 500  },
+  cls:  { good: 0.1,  poor: 0.25 },
+};
+
+function getStatus(metric: string, value: number): string {
+  const limit = vitalThresholds[metric.toLowerCase() as VitalKey];
+  if (!limit) return "⚪ Unknown";
+  return value <= limit.good ? "🟢 Good" : value <= limit.poor ? "🟡 Needs Improvement" : "🔴 Poor";
+}
+
+type HealthKey = "heap" | "weight" | "nodes";
+
+const healthThresholds: Record<HealthKey, { good: number; poor: number }> = {
+  heap:   { good: 150,  poor: 300  },
+  weight: { good: 3,    poor: 8    },
+  nodes:  { good: 1500, poor: 3000 },
+};
+
+function getSystemStatus(metric: string, value: number): string {
+  const limit = healthThresholds[metric.toLowerCase() as HealthKey];
+  if (!limit) return "⚪ Unknown";
+  return value <= limit.good ? "🟢 Good" : value <= limit.poor ? "🟡 Needs Improvement" : "🔴 Poor";
+}
+
+function getRenderTimeStatus(ms: number): string {
+  return ms <= 2000 ? "🟢 Good" : ms <= 4000 ? "🟡 Needs Improvement" : "🔴 Poor";
+}
+
+// Score badge — clear visual band so you know at a glance how the app did
+function getScoreBadge(score: number): string {
+  if (score >= 90) return `${score}/100 🟢 Excellent`;
+  if (score >= 70) return `${score}/100 🟡 Good`;
+  if (score >= 50) return `${score}/100 🟠 Needs Work`;
+  return `${score}/100 🔴 Poor`;
+}
+
+function describeDevice(device: string): string {
+  return device === "mobile"
+    ? "📱 Mobile (iPhone 12 Pro, 390×844)"
+    : "🖥️  Desktop (1280×720)";
+}
+
+function describeThrottle(throttle: string): string {
+  if (throttle === "3g")     return "🐢 3G  (1.5 Mbps / 300ms RTT)";
+  if (throttle === "slow4g") return "🐌 Slow 4G  (9 Mbps / 170ms RTT)";
+  return "⚡ No throttle  (localhost speed)";
+}
+
+function describeCpu(rate: number): string {
+  if (rate === 4) return "⚙️  CPU 4x slowdown (Lighthouse mobile preset)";
+  if (rate === 6) return "⚙️  CPU 6x slowdown (low-end device)";
+  return "⚙️  CPU no throttle (real hardware speed)";
+}
+
+// ─────────────────────────────────────────────────────────────
+// AUDIT OPTIONS
+// ─────────────────────────────────────────────────────────────
+
+// device:      "desktop" | "mobile" | ["desktop", "mobile"]
+// throttle:    "none" | "slow4g" | "3g"
+//              ⚠️  Only meaningful against deployed URLs, not localhost.
+//
+// cpuThrottle: 1 (default) | 4 (Lighthouse mobile) | 6 (low-end)
+//              ✅ Works on localhost — slows JS execution, not data transfer.
+//              Use 4 to simulate what a mid-range Android phone feels like.
+const AUDIT_OPTIONS = {
+  device:      ["desktop", "mobile"] as ("desktop" | "mobile")[],
+  throttle:    "none" as const,
+  cpuThrottle: 1 as 1 | 4 | 6,
+};
+
+// ─────────────────────────────────────────────────────────────
+// MAIN TEST
+// ─────────────────────────────────────────────────────────────
+
+export async function startTest() {
+  console.log("=========================================================");
+  console.log("🩺  REACT DOCTOR: FULL SMART DIAGNOSTIC  🩺");
+  console.log("=========================================================");
+
+  const targetProject = path.resolve(
+    process.argv[2] || process.env.TARGET_PROJECT || process.cwd(),
+  );
+
+  console.log(`📁 Target:   ${targetProject}`);
+
+  const deviceList = Array.isArray(AUDIT_OPTIONS.device)
+    ? AUDIT_OPTIONS.device
+    : [AUDIT_OPTIONS.device];
+  deviceList.forEach(d => console.log(describeDevice(d)));
+  console.log(describeThrottle(AUDIT_OPTIONS.throttle));
+  console.log(describeCpu(AUDIT_OPTIONS.cpuThrottle));
+
+  const profiler = new RuntimeProfiler(targetProject);
+
+  try {
+    const masterReport = await profiler.profile([], AUDIT_OPTIONS);
+    const routesFound  = Object.keys(masterReport);
+
+    if (routesFound.length === 0) {
+      console.log("\n⚠️  No routes were audited.");
+      return;
+    }
+
+    routesFound.forEach((key) => {
+      const report = masterReport[key];
+      const [route] = key.includes("::") ? key.split("::") : [key];
+
+      console.log(`\n📍 ROUTE: ${route}`);
+      console.log(`   Device: ${report.deviceType} | CPU: ${report.cpuThrottling}x | Network: ${AUDIT_OPTIONS.throttle}`);
+
+      // ── PERFORMANCE SCORE ───────────────────────────────────
+      console.log(`\n🏆 PERFORMANCE SCORE: ${getScoreBadge(report.performanceScore)}`);
+      console.log("---------------------------------------------------------");
+
+      // ── TABLE 1: WEB VITALS ─────────────────────────────────
+      console.log("⚡ SPEED METRICS");
+      console.table({
+        "LCP (Paint)":    { Value: `${report.metrics.lcp.toFixed(0)}ms`,  Status: getStatus("lcp",  report.metrics.lcp)  },
+        "FCP (Content)":  { Value: `${report.metrics.fcp.toFixed(0)}ms`,  Status: getStatus("fcp",  report.metrics.fcp)  },
+        "TTFB (Server)":  { Value: `${report.metrics.ttfb.toFixed(0)}ms`, Status: getStatus("ttfb", report.metrics.ttfb) },
+        "CLS (Stability)":{ Value: report.metrics.cls.toFixed(3),         Status: getStatus("cls",  report.metrics.cls)  },
+        "INP (Response)": { Value: `${report.metrics.inp.toFixed(0)}ms`,  Status: getStatus("inp",  report.metrics.inp)  },
+      });
+
+      // ── TABLE 2: SYSTEM HEALTH ──────────────────────────────
+      console.log("🩺 SYSTEM HEALTH");
+      console.table({
+        "Memory (RAM)": { Value: `${report.stats.jsHeapMB} MB`,  Status: getSystemStatus("heap",   parseFloat(report.stats.jsHeapMB))  },
+        "Page Weight":  { Value: `${report.stats.payloadMB} MB`, Status: getSystemStatus("weight", parseFloat(report.stats.payloadMB)) },
+        "DOM Nodes":    { Value: report.stats.domNodes,          Status: getSystemStatus("nodes",  report.stats.domNodes)              },
+        "Render Time":  { Value: `${report.renderTime}ms`,       Status: getRenderTimeStatus(report.renderTime)                        },
+      });
+
+      if (report.stats.topOffender) {
+        console.log(`🔍 TOP OFFENDER: ${report.stats.topOffender.name} (${report.stats.topOffender.size.toFixed(2)} MB)`);
+      }
+
+      // ── TABLE 3: REACT PROFILER ─────────────────────────────
+      console.log("\n⚛️  REACT PROFILER");
+
+      if (report.commitDurations.length > 0) {
+        const total = report.commitDurations.reduce((a, b) => a + b, 0);
+        const avg   = (total / report.commitDurations.length).toFixed(2);
+        const max   = Math.max(...report.commitDurations).toFixed(2);
+        const slow  = report.commitDurations.filter(d => d > 16).length;
+
+        console.log(`   Commits:    ${report.commitDurations.length} total`);
+        console.log(`   Avg commit: ${avg}ms`);
+        console.log(`   Slowest:    ${max}ms`);
+        if (slow > 0) {
+          console.log(`   ⚠️  ${slow} commit(s) exceeded 16ms (60fps budget)`);
+        }
+      } else {
+        console.log("   Commits:    none recorded (app may not be in dev mode)");
+      }
+
+      const rerenderEntries = Object.entries(report.rerenders);
+      if (rerenderEntries.length > 0) {
+        console.log("\n   Re-renders per component:");
+        const rerenderTable: Record<string, { Renders: number; Status: string }> = {};
+        for (const [name, count] of rerenderEntries.sort(([, a], [, b]) => b - a)) {
+          rerenderTable[name] = {
+            Renders: count,
+            Status:  count >= 10 ? "🔴 Excessive" : count >= 5 ? "🟡 High" : "🟢 Normal",
+          };
+        }
+        console.table(rerenderTable);
+      }
+
+      // ── ERRORS & WARNINGS ───────────────────────────────────
+      console.log("\n🐛 ERRORS & WARNINGS");
+      if (report.errors.length === 0) {
+        console.log("   ✅ No errors or warnings detected");
+      } else {
+        const jsErrors  = report.errors.filter(e => e.type === "error");
+        const warnings  = report.errors.filter(e => e.type === "warning");
+
+        if (jsErrors.length > 0) {
+          console.log(`   ❌ ${jsErrors.length} error(s):`);
+          jsErrors.forEach(e => console.log(`      [${e.source}] ${e.message.slice(0, 120)}`));
+        }
+        if (warnings.length > 0) {
+          console.log(`   ⚠️  ${warnings.length} warning(s):`);
+          warnings.forEach(e => console.log(`      [${e.source}] ${e.message.slice(0, 120)}`));
+        }
+      }
+
+      // ── SCREENSHOTS ─────────────────────────────────────────
+      console.log("\n📸 SCREENSHOTS");
+      if (report.screenshots.length === 0) {
+        console.log("   No screenshots captured");
+      } else {
+        report.screenshots.forEach(s => {
+          console.log(`   ${s.label.padEnd(10)} → captured at ${s.takenAt}ms`);
+        });
+        console.log(`   📁 PNG files saved to: core/reports/screenshots/`);
+      }
+
+      console.log("---------------------------------------------------------");
+    });
+
+    console.log("\n✅ Full Diagnostic Finished Successfully.");
+  } catch (error) {
+    console.error("\n❌ PROFILER ERROR!");
+    console.error(error);
+  }
+}
+
+if (require.main === module) {
+  startTest();
+}

package/core/static-ana/static/analyzer.ts

@@ -0,0 +1,145 @@
+import fs from 'fs';
+import path from 'path';
+import { ASTParser } from './ast-parser';
+import { StaticReport, ComponentIssue } from '../../../shared/src/types';
+import { ScannedFile } from './scanner';
+
+// Import all detectors
+import {
+  detectConsoleLogs,
+  detectLargeComponents,
+  detectInlineFunctions,
+  detectDeadCode,
+  detectInfiniteLoops,
+  detectInlineStyles,
+  detectMissingKeys,
+  detectPropDrilling,
+  detectMissingMemo
+} from './detectors';
+
+export class StaticAnalyzer {
+  private parser: ASTParser;
+
+  constructor() {
+    this.parser = new ASTParser();
+  }
+
+  /**
+   * Orchestrates the analysis of multiple files
+   */
+  async analyze(files: ScannedFile[]): Promise<StaticReport> {
+    console.log(`\n${"=".repeat(70)}`);
+    console.log(`🔍 Static Analysis - Analyzing ${files.length} file(s)`);
+    console.log("=".repeat(70));
+
+    const allIssues: ComponentIssue[] = [];
+    let filesAnalyzed = 0;
+    let filesFailed = 0;
+
+    for (const file of files) {
+      try {
+        const code = fs.readFileSync(file.path, 'utf-8');
+        const ast = this.parser.parse(code, file.path);
+
+        const fileIssues = [
+          ...detectConsoleLogs(ast, file.relativePath),
+          ...detectLargeComponents(ast, file.relativePath),
+          ...detectInlineFunctions(ast, file.relativePath),
+          ...detectDeadCode(ast, file.relativePath),
+          ...detectInfiniteLoops(ast, file.relativePath),
+          ...detectInlineStyles(ast, file.relativePath),
+          ...detectMissingKeys(ast, file.relativePath),
+          ...detectPropDrilling(ast, file.relativePath),
+          ...detectMissingMemo(ast, file.relativePath),
+        ];
+
+        allIssues.push(...fileIssues);
+        filesAnalyzed++;
+
+        if (fileIssues.length > 0) {
+          console.log(`  ⚠️  ${file.relativePath.padEnd(50)} ${fileIssues.length} issue(s)`);
+        } else {
+          console.log(`  ✅ ${file.relativePath}`);
+        }
+
+      } catch (error) {
+        filesFailed++;
+        const errorMsg = error instanceof Error ? error.message : 'Unknown error';
+        console.error(`  ❌ ${file.relativePath.padEnd(50)} ${errorMsg}`);
+      }
+    }
+
+    const grade = this.calculateGrade(allIssues, filesAnalyzed);
+
+    return {
+      timestamp: new Date().toISOString(),
+      componentCount: filesAnalyzed,
+      issues: allIssues,
+      filesAnalyzed,
+      filesFailed,
+      grade
+    };
+  }
+
+  /**
+   * Persistence: Saves the results to static-report.json
+   */
+ saveReport(report: StaticReport): string {
+    // 📍 __dirname gives the directory of this current file.
+    // We go up two levels to reach the 'react_doctor' root, then into 'reports'.
+    const reportDir = path.resolve(__dirname, '../../reports'); 
+    
+    // 📁 Ensure the directory exists (create it if missing)
+    if (!fs.existsSync(reportDir)) {
+      fs.mkdirSync(reportDir, { recursive: true });
+    }
+
+    const filePath = path.join(reportDir, 'staticreport.json');
+
+    try {
+      fs.writeFileSync(filePath, JSON.stringify(report, null, 2), 'utf-8');
+      console.log(`\n📄 Static Report saved to: ${filePath}`);
+      return filePath;
+    } catch (error) {
+      throw new Error(`Failed to save Static JSON report: ${error}`);
+    }
+  }
+
+  private calculateGrade(issues: ComponentIssue[], fileCount: number): string {
+    if (fileCount === 0) return 'A+';
+    const hasCritical = issues.some(i => i.severity === 'critical');
+    
+    const totalPenalty = issues.reduce((acc, issue) => {
+      switch (issue.severity) {
+        case 'critical': return acc + 30;
+        case 'warning':  return acc + 10;
+        case 'info':     return acc + 2;
+        default:         return acc;
+      }
+    }, 0);
+
+    const scorePerFile = totalPenalty / fileCount;
+
+    if (hasCritical) return 'F';
+    if (scorePerFile === 0) return 'A+';
+    if (scorePerFile < 5)   return 'A';
+    if (scorePerFile < 15)  return 'B';
+    if (scorePerFile < 30)  return 'C';
+    if (scorePerFile < 50)  return 'D';
+    return 'F';
+  }
+
+  getSummary(report: StaticReport) {
+    const critical = report.issues.filter(i => i.severity === 'critical').length;
+    const warnings = report.issues.filter(i => i.severity === 'warning').length;
+    const info = report.issues.filter(i => i.severity === 'info').length;
+
+    const byDetector: Record<string, number> = {};
+    report.issues.forEach(issue => {
+      const detectorType = issue.id.split('-')[0];
+      byDetector[detectorType] = (byDetector[detectorType] || 0) + 1;
+    });
+
+    return { critical, warnings, info, byDetector };
+  }
+}