react-doctor-cli-dev 1.0.0

package/cli/src/commands/install.ts

@@ -0,0 +1,163 @@
+// ─────────────────────────────────────────────────────────────
+// cli/src/commands/install.ts
+//
+// react-doctor install
+//
+// Installs React Doctor from GitHub into a React project.
+// Runs the equivalent of:
+//
+//   npm install --save-dev softar-dev/React_Doctor
+//
+// WHY THIS COMMAND EXISTS:
+// When React Doctor is published and another developer wants
+// to use it, they can run "npx react-doctor install" instead
+// of having to remember the GitHub package name. It also
+// detects their package manager (npm/yarn/pnpm) automatically.
+//
+// NOTE: This command is only useful once the GitHub repo is
+// public and the project is ready for other developers to use.
+// During development you run the tool directly from the
+// react-tool/ folder with ts-node, so this command is not
+// needed for your own workflow.
+// ─────────────────────────────────────────────────────────────
+
+import { Command } from "commander";
+import { spawn }   from "child_process";
+import path        from "path";
+import fs          from "fs";
+import chalk       from "chalk";
+import {
+  printBanner, printSection,
+  printDone, printFail, printInfo, spinner,
+} from "../ui";
+
+// The GitHub package identifier — owner/repo format.
+// npm, yarn, and pnpm all understand this without any registry.
+const GITHUB_PACKAGE = "softar-dev/React_Doctor";
+
+// ─────────────────────────────────────────────────────────────
+// REGISTER COMMAND
+// ─────────────────────────────────────────────────────────────
+
+export function registerInstallCommand(program: Command): void {
+  program
+    .command("install")
+    .description(`Install React Doctor from GitHub (${GITHUB_PACKAGE})`)
+    .option(
+      "-p, --path <projectPath>",
+      "Path to the React project to install into (defaults to current directory)",
+      process.cwd(),
+    )
+    .option("--no-banner", "Skip the banner")
+    .action(async (options) => {
+
+      const projectPath = path.resolve(options.path);
+
+      if (!options.noBanner) printBanner();
+
+      // ── Validate this is a React project ────────────────────
+      const pkgJsonPath = path.join(projectPath, "package.json");
+      if (!fs.existsSync(pkgJsonPath)) {
+        printFail(
+          `No package.json found at: ${projectPath}\n\n` +
+          `  Make sure you are inside a React project, or pass the path:\n` +
+          `  react-doctor install --path ./my-react-app`,
+        );
+        process.exit(1);
+      }
+
+      // Warn if React is not in the project's dependencies
+      try {
+        const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
+        const deps = { ...pkgJson.dependencies, ...pkgJson.devDependencies };
+        if (!deps["react"]) {
+          console.log(chalk.yellow(
+            "  ⚠️  React not found in this project's dependencies.\n" +
+            "     Installing anyway — make sure this is a React project.\n",
+          ));
+        }
+      } catch {
+        // If we can't read package.json, just continue
+      }
+
+      // ── Detect package manager ───────────────────────────────
+      // Check for lock files to know which package manager the
+      // project uses. Order matters — check yarn and pnpm first
+      // since npm is the fallback.
+      const pkgManager =
+        fs.existsSync(path.join(projectPath, "yarn.lock"))       ? "yarn" :
+        fs.existsSync(path.join(projectPath, "pnpm-lock.yaml"))  ? "pnpm" :
+        "npm";
+
+      printSection("Installing React Doctor");
+      printInfo("Project",  projectPath);
+      printInfo("Manager",  pkgManager);
+      printInfo("Source",   `github.com/${GITHUB_PACKAGE}`);
+      console.log();
+
+      // ── Build the install command ────────────────────────────
+      // The "owner/repo" format is understood natively by all
+      // three package managers — no npm registry needed.
+      let args: string[];
+      if (pkgManager === "yarn") {
+        args = ["add", "--dev", GITHUB_PACKAGE];
+      } else if (pkgManager === "pnpm") {
+        args = ["add", "--save-dev", GITHUB_PACKAGE];
+      } else {
+        args = ["install", "--save-dev", GITHUB_PACKAGE];
+      }
+
+      console.log(chalk.gray(`  Running: `) + chalk.cyan(`${pkgManager} ${args.join(" ")}\n`));
+
+      const spin = spinner("Downloading from GitHub...");
+
+      await new Promise<void>((resolve, reject) => {
+        const isWin = process.platform === "win32";
+
+        const proc = spawn(pkgManager, args, {
+          cwd:   projectPath,
+          shell: isWin ? true : "/bin/bash",
+          stdio: ["ignore", "pipe", "pipe"],
+        });
+
+        let output = "";
+        proc.stdout?.on("data", (d: Buffer) => { output += d.toString(); });
+        proc.stderr?.on("data", (d: Buffer) => { output += d.toString(); });
+
+        proc.on("close", (code) => {
+          if (code === 0) {
+            spin.succeed(chalk.green("Installed successfully!"));
+            resolve();
+          } else {
+            spin.fail(chalk.red("Installation failed."));
+            if (output) console.log(chalk.gray(`\n${output}`));
+            reject(new Error(`${pkgManager} exited with code ${code}`));
+          }
+        });
+
+        proc.on("error", reject);
+      });
+
+      // ── Show usage after install ─────────────────────────────
+      printSection("You are ready");
+      console.log("  Run these commands from inside your React project:\n");
+
+      const commands: [string, string][] = [
+        ["npx react-doctor full ./",           "Run the full diagnostic (recommended)"],
+        ["npx react-doctor full ./ --mobile",  "Include mobile viewport profiling"],
+        ["npx react-doctor analyze ./",        "Static code analysis only (no Chrome needed)"],
+        ["npx react-doctor profile ./",        "Runtime profiling only"],
+        ["npx react-doctor --help",            "See all available options"],
+      ];
+
+      commands.forEach(([cmd, desc]) => {
+        console.log(
+          `  ${chalk.cyan(cmd.padEnd(44))}` +
+          chalk.gray(desc),
+        );
+      });
+
+      console.log();
+      printDone("React Doctor is installed and ready.");
+    });
+}

package/cli/src/commands/profile.ts

@@ -0,0 +1,246 @@
+// ─────────────────────────────────────────────────────────────
+// cli/src/commands/profile.ts
+//
+// react-doctor profile <projectPath>
+//
+// Runs the Runtime Profiler only — needs Chrome.
+// Boots the React dev server, opens headless Chrome,
+// measures Web Vitals + React profiler data, saves
+// runtimereport.json to .react-doctor/
+//
+// Use this when:
+//   - You already ran static analysis and want performance data
+//   - You want a quick runtime check without code analysis
+//   - You want to compare desktop vs mobile performance
+//
+// Options:
+//   --mobile          also profile on mobile viewport
+//   --cpu 4           simulate 4x CPU slowdown (Lighthouse preset)
+//   --throttle slow4g simulate slow network (deployed URLs only)
+//
+// Use "react-doctor full" to run everything together.
+// ─────────────────────────────────────────────────────────────
+
+import { Command } from "commander";
+import path        from "path";
+import fs          from "fs";
+import chalk       from "chalk";
+import {
+  printBanner, printSection, printResult,
+  printDone, printFail, printInfo,
+  scoreBadge, vitalStatus, spinner,
+} from "../ui";
+
+function getCoreModule(relativePath: string) {
+  return require(path.resolve(__dirname, "..", "..", "..", "core", relativePath));
+}
+
+// ─────────────────────────────────────────────────────────────
+// REGISTER COMMAND
+// ─────────────────────────────────────────────────────────────
+
+export function registerProfileCommand(program: Command): void {
+  program
+    .command("profile")
+    .description("Run the runtime profiler only (requires Chrome)")
+    .argument(
+      "[projectPath]",
+      "Path to the React project (defaults to current directory)",
+      process.cwd(),
+    )
+    .option(
+      "--desktop",
+      "Profile on desktop viewport 1280x720 (default if neither flag is passed)",
+      false,
+    )
+    .option(
+      "--mobile",
+      "Profile on mobile viewport — iPhone 12 Pro 390x844",
+      false,
+    )
+    .option(
+      "--cpu <rate>",
+      "CPU throttle: 1 (real speed) | 4 (Lighthouse mobile) | 6 (low-end)",
+      (v: string) => parseInt(v) as 1 | 4 | 6,
+      1,
+    )
+    .option(
+      "--throttle <preset>",
+      "Network throttle: none | slow4g | 3g  (only meaningful against deployed URLs)",
+      "none",
+    )
+    .option("--no-banner", "Skip the banner")
+    .action(async (projectPath: string, options) => {
+
+      const resolvedPath = path.resolve(projectPath);
+
+      if (!options.noBanner) printBanner();
+
+      // ── Validate project ────────────────────────────────────
+      if (!fs.existsSync(path.join(resolvedPath, "package.json"))) {
+        printFail(
+          `No package.json found at: ${resolvedPath}\n\n` +
+          `  Pass the path to your React project:\n` +
+          `  react-doctor profile ./my-react-app`,
+        );
+        process.exit(1);
+      }
+
+      // ── Determine devices ────────────────────────────────────
+      // --desktop and --mobile are independent flags.
+      // If neither is passed, desktop is the default.
+      // If only --mobile is passed, only mobile runs.
+      // If both are passed, both run in one pass.
+      const wantDesktop = options.desktop || (!options.desktop && !options.mobile);
+      const wantMobile  = options.mobile ?? false;
+
+      const devices: ("desktop" | "mobile")[] | "desktop" | "mobile" =
+        wantDesktop && wantMobile ? ["desktop", "mobile"] :
+        wantMobile                ? "mobile"              :
+                                    "desktop";
+
+      const deviceLabel =
+        wantDesktop && wantMobile ? "desktop + mobile" :
+        wantMobile                ? "mobile"           :
+                                    "desktop";
+
+      printSection("Runtime Profiler");
+      printInfo("Project",  resolvedPath);
+      printInfo("Device",   deviceLabel);
+      printInfo("CPU",      `${options.cpu}x`);
+      printInfo("Network",  options.throttle);
+      console.log();
+
+      // ── Run the profiler ────────────────────────────────────
+      const spin = spinner("Starting dev server...");
+
+      try {
+        const { RuntimeProfiler } = getCoreModule("runtime/profiler/index");
+
+        const profiler = new RuntimeProfiler(resolvedPath);
+        spin.text = "  Launching headless Chrome...";
+
+        const runtimeReports = await profiler.profile([], {
+          device:      devices,
+          throttle:    options.throttle as "none" | "slow4g" | "3g",
+          cpuThrottle: options.cpu as 1 | 4 | 6,
+        });
+
+        // Save to .react-doctor/
+        const outputDir = path.join(resolvedPath, ".react-doctor");
+        fs.mkdirSync(outputDir, { recursive: true });
+        fs.writeFileSync(
+          path.join(outputDir, "runtimereport.json"),
+          JSON.stringify(runtimeReports, null, 2),
+        );
+
+        const routeKeys = Object.keys(runtimeReports);
+        spin.succeed(chalk.green(`Profiling complete — ${routeKeys.length} route/device combination(s)`));
+
+        // ── Results ─────────────────────────────────────────────
+        printSection("Results");
+
+        for (const [key, report] of Object.entries(runtimeReports) as [string, any][]) {
+          const [route, device] = key.includes("::") ? key.split("::") : [key, "desktop"];
+
+          console.log();
+          console.log(
+            `  ${chalk.bold("Route:")} ${route}  ` +
+            `${chalk.gray(`[${device}]`)}  ` +
+            `Score: ${scoreBadge(report.performanceScore)}`,
+          );
+          console.log();
+
+          // Web vitals
+          printResult("LCP",         `${report.metrics.lcp.toFixed(0)}ms`,   vitalStatus("lcp",  report.metrics.lcp));
+          printResult("FCP",         `${report.metrics.fcp.toFixed(0)}ms`,   vitalStatus("fcp",  report.metrics.fcp));
+          printResult("TTFB",        `${report.metrics.ttfb.toFixed(0)}ms`,  vitalStatus("ttfb", report.metrics.ttfb));
+          printResult("CLS",         report.metrics.cls.toFixed(3),           vitalStatus("cls",  report.metrics.cls));
+          printResult("INP",         `${report.metrics.inp.toFixed(0)}ms`,   vitalStatus("inp",  report.metrics.inp));
+          printResult("Render time", `${report.renderTime}ms`,
+            report.renderTime <= 2000 ? "good" : report.renderTime <= 4000 ? "warn" : "poor");
+
+          // React profiler
+          if (report.commitDurations?.length > 0) {
+            const avg  = (report.commitDurations.reduce((a: number, b: number) => a + b, 0) /
+                          report.commitDurations.length).toFixed(1);
+            const slow = report.commitDurations.filter((d: number) => d > 16).length;
+            printResult(
+              "React commits",
+              `${report.commitDurations.length} total, avg ${avg}ms`,
+              slow > 0 ? "warn" : "good",
+            );
+          }
+
+          // Top re-render component
+          const rerenderEntries = Object.entries(report.rerenders ?? {})
+            .sort(([, a], [, b]) => (b as number) - (a as number));
+          if (rerenderEntries.length > 0) {
+            const [topName, topCount] = rerenderEntries[0];
+            printResult(
+              "Most re-renders",
+              `${topName} (${topCount}x)`,
+              (topCount as number) >= 10 ? "poor" : (topCount as number) >= 5 ? "warn" : "good",
+            );
+          }
+
+          // System stats
+          printResult("Page weight",  `${report.stats.payloadMB} MB`, "info");
+          printResult("JS heap",      `${report.stats.jsHeapMB} MB`,  "info");
+          printResult("DOM nodes",    String(report.stats.domNodes),   "info");
+
+          if (report.stats.topOffender) {
+            printResult(
+              "Heaviest file",
+              `${report.stats.topOffender.name} (${report.stats.topOffender.size.toFixed(2)} MB)`,
+              "warn",
+            );
+          }
+
+          // Errors
+          const errorCount   = (report.errors ?? []).filter((e: any) => e.type === "error").length;
+          const warningCount = (report.errors ?? []).filter((e: any) => e.type === "warning").length;
+          if (errorCount > 0 || warningCount > 0) {
+            printResult(
+              "Issues",
+              `${errorCount} error(s)  ${warningCount} warning(s)`,
+              errorCount > 0 ? "poor" : "warn",
+            );
+            (report.errors ?? []).slice(0, 3).forEach((e: any) => {
+              const icon = e.type === "error" ? chalk.red("  ✗") : chalk.yellow("  !");
+              console.log(`${icon} ${chalk.gray(e.message.slice(0, 90))}`);
+            });
+          } else {
+            printResult("Issues", "None detected", "good");
+          }
+
+          // Screenshots
+          if (report.screenshots?.length > 0) {
+            const labels = report.screenshots.map((s: any) => `${s.label}@${s.takenAt}ms`).join("  ");
+            printResult("Screenshots", labels, "info");
+          }
+
+          console.log();
+        }
+
+        printResult(
+          "Report saved",
+          path.join(resolvedPath, ".react-doctor", "runtimereport.json"),
+          "info",
+        );
+        console.log();
+
+        printDone("Runtime profiling finished.");
+        console.log(
+          chalk.gray("  Tip: run ") +
+          chalk.cyan("react-doctor full ./") +
+          chalk.gray(" to also get static analysis and improvement suggestions.\n"),
+        );
+
+      } catch (err: any) {
+        spin.fail(chalk.red("Runtime profiling failed"));
+        console.log(chalk.red(`\n  ${err.message}\n`));
+        process.exit(1);
+      }
+    });
+}

package/cli/src/index.ts

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// ─────────────────────────────────────────────────────────────
+// cli/src/index.ts
+//
+// The CLI entry point. This is the file that runs when the
+// user types "react-doctor" in their terminal.
+//
+// HOW IT WORKS:
+// 1. Commander.js parses the command and flags from argv
+// 2. The matching command handler is called
+// 3. The handler imports core modules and runs the pipeline
+//
+// HOW THE BINARY REGISTRATION WORKS:
+// package.json has a "bin" field:
+//   "bin": { "react-doctor": "./dist/index.js" }
+//
+// After "npm link" (dev) or "npm install" (production),
+// npm creates a symlink from the system's bin directory
+// to this file. That's what makes "react-doctor" a real
+// terminal command available anywhere.
+//
+// THE SHEBANG (#!/usr/bin/env node) on line 1:
+// This tells the OS to run this file with Node.js when
+// called directly as a script. Without it, the OS doesn't
+// know which interpreter to use.
+// ─────────────────────────────────────────────────────────────
+
+import { Command } from "commander";
+import { registerAnalyzeCommand } from "./commands/analyze";
+import { registerProfileCommand } from "./commands/profile";
+import { registerFullCommand }    from "./commands/full";
+import { registerInstallCommand }  from "./commands/install";
+
+const program = new Command();
+
+// ── Program metadata ──────────────────────────────────────────
+program
+  .name("react-doctor")
+  .description("React performance analyzer — static analysis + runtime profiling + smart suggestions")
+  .version("1.0.0");
+
+// ── Register all commands ─────────────────────────────────────
+// Each function adds one command to the program.
+// The order here is the order they appear in --help output.
+
+registerFullCommand(program);      // react-doctor full
+registerAnalyzeCommand(program);   // react-doctor analyze
+registerProfileCommand(program);   // react-doctor profile
+registerInstallCommand(program);   // react-doctor install
+
+// ── Usage examples shown at bottom of --help ─────────────────
+program.addHelpText("after", `
+Examples:
+  $ react-doctor full ./my-app                       Desktop only (default)
+  $ react-doctor full ./my-app --mobile              Mobile only
+  $ react-doctor full ./my-app --desktop --mobile    Both desktop and mobile
+  $ react-doctor full ./my-app --cpu 4               Simulate slow Android device
+  $ react-doctor full ./my-app --throttle slow4g     Simulate slow 4G network
+  $ react-doctor full ./my-app --throttle 3g         Simulate 3G network
+  $ react-doctor full ./my-app --cpu 4 --throttle 3g Slow device + slow network
+  $ react-doctor full ./my-app --upload              Upload results to dashboard
+
+  $ react-doctor analyze ./my-app                    Static code analysis only
+  $ react-doctor analyze ./my-app --full             Static + runtime + rules
+
+  $ react-doctor profile ./my-app                    Desktop only (default)
+  $ react-doctor profile ./my-app --mobile           Mobile only
+  $ react-doctor profile ./my-app --desktop --mobile Both devices
+  $ react-doctor profile ./my-app --cpu 4            4x CPU slowdown simulation
+  $ react-doctor profile ./my-app --throttle slow4g  Simulate slow 4G network
+  $ react-doctor profile ./my-app --throttle 3g      Simulate 3G network
+
+  $ react-doctor install                       Install from GitHub into a project
+  $ react-doctor install --path ./my-app       Install into a specific folder
+`);
+
+// ── Show help if called with no arguments ─────────────────────
+// Without this, calling "react-doctor" with no command just
+// exits silently, which is confusing. This prints help instead.
+if (process.argv.length < 3) {
+  program.help();
+}
+
+program.parse(process.argv);

package/cli/src/ui.ts

@@ -0,0 +1,120 @@
+// ─────────────────────────────────────────────────────────────
+// cli/src/ui.ts
+//
+// Shared terminal output helpers used by every command.
+// All chalk colors, ora spinners, and print functions live
+// here so the visual style is consistent across the CLI.
+//
+// WHY ONE FILE FOR ALL UI:
+// If each command file had its own chalk/ora setup, changing
+// a color or spacing would require editing every file. This
+// way you change it once here and it applies everywhere.
+// ─────────────────────────────────────────────────────────────
+
+import chalk from "chalk";
+import ora, { Ora } from "ora";
+
+// ── Banner ────────────────────────────────────────────────────
+// Printed once at the start of every command run.
+
+export function printBanner(): void {
+  console.log();
+  console.log(chalk.cyan.bold("  ┌─────────────────────────────────┐"));
+  console.log(chalk.cyan.bold("  │       🩺  React Doctor          │"));
+  console.log(chalk.cyan.bold("  │   React Performance Analyzer    │"));
+  console.log(chalk.cyan.bold("  └─────────────────────────────────┘"));
+  console.log();
+}
+
+// ── Section headers ───────────────────────────────────────────
+// Visually separates sections within a command's output.
+
+export function printSection(title: string): void {
+  console.log();
+  console.log(chalk.cyan.bold(`  ── ${title} `).padEnd(58, "─"));
+  console.log();
+}
+
+// ── Spinner ───────────────────────────────────────────────────
+// Returns a running ora spinner.
+// Caller calls .succeed() or .fail() when done.
+
+export function spinner(text: string): Ora {
+  return ora({ text: `  ${text}`, color: "cyan", spinner: "dots" }).start();
+}
+
+// ── Single result line ────────────────────────────────────────
+// Prints one labeled metric with a colored status dot.
+
+export function printResult(
+  label:  string,
+  value:  string,
+  status: "good" | "warn" | "poor" | "info" | "none" = "none",
+): void {
+  const dot =
+    status === "good" ? chalk.green("●") :
+    status === "warn" ? chalk.yellow("●") :
+    status === "poor" ? chalk.red("●")    :
+    status === "info" ? chalk.blue("●")   :
+    chalk.gray("·");
+
+  console.log(`  ${dot}  ${chalk.gray(label.padEnd(24))} ${value}`);
+}
+
+// ── Score badge ───────────────────────────────────────────────
+// Formats a 0-100 score with a color band.
+
+export function scoreBadge(score: number): string {
+  if (score >= 90) return chalk.green.bold(`${score}/100`) + chalk.green("  Excellent");
+  if (score >= 70) return chalk.yellow.bold(`${score}/100`) + chalk.yellow("  Good");
+  if (score >= 50) return chalk.hex("#FFA500").bold(`${score}/100`) + chalk.hex("#FFA500")("  Needs Work");
+  return chalk.red.bold(`${score}/100`) + chalk.red("  Poor");
+}
+
+// ── Severity icon ─────────────────────────────────────────────
+
+export function severityIcon(s: string): string {
+  if (s === "critical") return chalk.red("❌");
+  if (s === "warning")  return chalk.yellow("⚠️ ");
+  return chalk.blue("ℹ️ ");
+}
+
+// ── Done / fail ───────────────────────────────────────────────
+
+export function printDone(message: string): void {
+  console.log();
+  console.log(chalk.green.bold(`  ✅  ${message}`));
+  console.log();
+}
+
+export function printFail(message: string): void {
+  console.log();
+  console.log(chalk.red.bold(`  ❌  ${message}`));
+  console.log();
+}
+
+// ── Muted info line ───────────────────────────────────────────
+
+export function printInfo(label: string, value: string): void {
+  console.log(`  ${chalk.gray(label.padEnd(16))} ${chalk.white(value)}`);
+}
+
+// ── Web vital threshold helper ────────────────────────────────
+// Maps a metric value to good/warn/poor for colored output.
+
+export function vitalStatus(
+  metric: "lcp" | "fcp" | "ttfb" | "inp" | "cls",
+  value:  number,
+): "good" | "warn" | "poor" {
+  const thresholds: Record<string, { 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 },
+  };
+  const t = thresholds[metric];
+  if (value <= t.good) return "good";
+  if (value <= t.poor) return "warn";
+  return "poor";
+}

package/cli/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target":                     "ES2020",
+    "module":                     "commonjs",
+    "lib":                        ["ES2020"],
+    "outDir":                     "./dist",
+    "rootDir":                    "./src",
+    "strict":                     true,
+    "esModuleInterop":            true,
+    "skipLibCheck":               true,
+    "resolveJsonModule":          true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}