react-doctor-cli-dev 1.0.0

package/cli/dist/commands/profile.js

@@ -0,0 +1,166 @@
+"use strict";
+// ─────────────────────────────────────────────────────────────
+// 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.
+// ─────────────────────────────────────────────────────────────
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerProfileCommand = registerProfileCommand;
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const chalk_1 = __importDefault(require("chalk"));
+const ui_1 = require("../ui");
+function getCoreModule(relativePath) {
+    return require(path_1.default.resolve(__dirname, "..", "..", "..", "core", relativePath));
+}
+// ─────────────────────────────────────────────────────────────
+// REGISTER COMMAND
+// ─────────────────────────────────────────────────────────────
+function registerProfileCommand(program) {
+    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) => parseInt(v), 1)
+        .option("--throttle <preset>", "Network throttle: none | slow4g | 3g  (only meaningful against deployed URLs)", "none")
+        .option("--no-banner", "Skip the banner")
+        .action(async (projectPath, options) => {
+        const resolvedPath = path_1.default.resolve(projectPath);
+        if (!options.noBanner)
+            (0, ui_1.printBanner)();
+        // ── Validate project ────────────────────────────────────
+        if (!fs_1.default.existsSync(path_1.default.join(resolvedPath, "package.json"))) {
+            (0, ui_1.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 = wantDesktop && wantMobile ? ["desktop", "mobile"] :
+            wantMobile ? "mobile" :
+                "desktop";
+        const deviceLabel = wantDesktop && wantMobile ? "desktop + mobile" :
+            wantMobile ? "mobile" :
+                "desktop";
+        (0, ui_1.printSection)("Runtime Profiler");
+        (0, ui_1.printInfo)("Project", resolvedPath);
+        (0, ui_1.printInfo)("Device", deviceLabel);
+        (0, ui_1.printInfo)("CPU", `${options.cpu}x`);
+        (0, ui_1.printInfo)("Network", options.throttle);
+        console.log();
+        // ── Run the profiler ────────────────────────────────────
+        const spin = (0, ui_1.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,
+                cpuThrottle: options.cpu,
+            });
+            // Save to .react-doctor/
+            const outputDir = path_1.default.join(resolvedPath, ".react-doctor");
+            fs_1.default.mkdirSync(outputDir, { recursive: true });
+            fs_1.default.writeFileSync(path_1.default.join(outputDir, "runtimereport.json"), JSON.stringify(runtimeReports, null, 2));
+            const routeKeys = Object.keys(runtimeReports);
+            spin.succeed(chalk_1.default.green(`Profiling complete — ${routeKeys.length} route/device combination(s)`));
+            // ── Results ─────────────────────────────────────────────
+            (0, ui_1.printSection)("Results");
+            for (const [key, report] of Object.entries(runtimeReports)) {
+                const [route, device] = key.includes("::") ? key.split("::") : [key, "desktop"];
+                console.log();
+                console.log(`  ${chalk_1.default.bold("Route:")} ${route}  ` +
+                    `${chalk_1.default.gray(`[${device}]`)}  ` +
+                    `Score: ${(0, ui_1.scoreBadge)(report.performanceScore)}`);
+                console.log();
+                // Web vitals
+                (0, ui_1.printResult)("LCP", `${report.metrics.lcp.toFixed(0)}ms`, (0, ui_1.vitalStatus)("lcp", report.metrics.lcp));
+                (0, ui_1.printResult)("FCP", `${report.metrics.fcp.toFixed(0)}ms`, (0, ui_1.vitalStatus)("fcp", report.metrics.fcp));
+                (0, ui_1.printResult)("TTFB", `${report.metrics.ttfb.toFixed(0)}ms`, (0, ui_1.vitalStatus)("ttfb", report.metrics.ttfb));
+                (0, ui_1.printResult)("CLS", report.metrics.cls.toFixed(3), (0, ui_1.vitalStatus)("cls", report.metrics.cls));
+                (0, ui_1.printResult)("INP", `${report.metrics.inp.toFixed(0)}ms`, (0, ui_1.vitalStatus)("inp", report.metrics.inp));
+                (0, ui_1.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, b) => a + b, 0) /
+                        report.commitDurations.length).toFixed(1);
+                    const slow = report.commitDurations.filter((d) => d > 16).length;
+                    (0, ui_1.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 - a);
+                if (rerenderEntries.length > 0) {
+                    const [topName, topCount] = rerenderEntries[0];
+                    (0, ui_1.printResult)("Most re-renders", `${topName} (${topCount}x)`, topCount >= 10 ? "poor" : topCount >= 5 ? "warn" : "good");
+                }
+                // System stats
+                (0, ui_1.printResult)("Page weight", `${report.stats.payloadMB} MB`, "info");
+                (0, ui_1.printResult)("JS heap", `${report.stats.jsHeapMB} MB`, "info");
+                (0, ui_1.printResult)("DOM nodes", String(report.stats.domNodes), "info");
+                if (report.stats.topOffender) {
+                    (0, ui_1.printResult)("Heaviest file", `${report.stats.topOffender.name} (${report.stats.topOffender.size.toFixed(2)} MB)`, "warn");
+                }
+                // Errors
+                const errorCount = (report.errors ?? []).filter((e) => e.type === "error").length;
+                const warningCount = (report.errors ?? []).filter((e) => e.type === "warning").length;
+                if (errorCount > 0 || warningCount > 0) {
+                    (0, ui_1.printResult)("Issues", `${errorCount} error(s)  ${warningCount} warning(s)`, errorCount > 0 ? "poor" : "warn");
+                    (report.errors ?? []).slice(0, 3).forEach((e) => {
+                        const icon = e.type === "error" ? chalk_1.default.red("  ✗") : chalk_1.default.yellow("  !");
+                        console.log(`${icon} ${chalk_1.default.gray(e.message.slice(0, 90))}`);
+                    });
+                }
+                else {
+                    (0, ui_1.printResult)("Issues", "None detected", "good");
+                }
+                // Screenshots
+                if (report.screenshots?.length > 0) {
+                    const labels = report.screenshots.map((s) => `${s.label}@${s.takenAt}ms`).join("  ");
+                    (0, ui_1.printResult)("Screenshots", labels, "info");
+                }
+                console.log();
+            }
+            (0, ui_1.printResult)("Report saved", path_1.default.join(resolvedPath, ".react-doctor", "runtimereport.json"), "info");
+            console.log();
+            (0, ui_1.printDone)("Runtime profiling finished.");
+            console.log(chalk_1.default.gray("  Tip: run ") +
+                chalk_1.default.cyan("react-doctor full ./") +
+                chalk_1.default.gray(" to also get static analysis and improvement suggestions.\n"));
+        }
+        catch (err) {
+            spin.fail(chalk_1.default.red("Runtime profiling failed"));
+            console.log(chalk_1.default.red(`\n  ${err.message}\n`));
+            process.exit(1);
+        }
+    });
+}

package/cli/dist/index.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+"use strict";
+// ─────────────────────────────────────────────────────────────
+// 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.
+// ─────────────────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const analyze_1 = require("./commands/analyze");
+const profile_1 = require("./commands/profile");
+const full_1 = require("./commands/full");
+const install_1 = require("./commands/install");
+const program = new commander_1.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.
+(0, full_1.registerFullCommand)(program); // react-doctor full
+(0, analyze_1.registerAnalyzeCommand)(program); // react-doctor analyze
+(0, profile_1.registerProfileCommand)(program); // react-doctor profile
+(0, install_1.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/dist/ui.js

@@ -0,0 +1,113 @@
+"use strict";
+// ─────────────────────────────────────────────────────────────
+// 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.
+// ─────────────────────────────────────────────────────────────
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.printBanner = printBanner;
+exports.printSection = printSection;
+exports.spinner = spinner;
+exports.printResult = printResult;
+exports.scoreBadge = scoreBadge;
+exports.severityIcon = severityIcon;
+exports.printDone = printDone;
+exports.printFail = printFail;
+exports.printInfo = printInfo;
+exports.vitalStatus = vitalStatus;
+const chalk_1 = __importDefault(require("chalk"));
+const ora_1 = __importDefault(require("ora"));
+// ── Banner ────────────────────────────────────────────────────
+// Printed once at the start of every command run.
+function printBanner() {
+    console.log();
+    console.log(chalk_1.default.cyan.bold("  ┌─────────────────────────────────┐"));
+    console.log(chalk_1.default.cyan.bold("  │       🩺  React Doctor          │"));
+    console.log(chalk_1.default.cyan.bold("  │   React Performance Analyzer    │"));
+    console.log(chalk_1.default.cyan.bold("  └─────────────────────────────────┘"));
+    console.log();
+}
+// ── Section headers ───────────────────────────────────────────
+// Visually separates sections within a command's output.
+function printSection(title) {
+    console.log();
+    console.log(chalk_1.default.cyan.bold(`  ── ${title} `).padEnd(58, "─"));
+    console.log();
+}
+// ── Spinner ───────────────────────────────────────────────────
+// Returns a running ora spinner.
+// Caller calls .succeed() or .fail() when done.
+function spinner(text) {
+    return (0, ora_1.default)({ text: `  ${text}`, color: "cyan", spinner: "dots" }).start();
+}
+// ── Single result line ────────────────────────────────────────
+// Prints one labeled metric with a colored status dot.
+function printResult(label, value, status = "none") {
+    const dot = status === "good" ? chalk_1.default.green("●") :
+        status === "warn" ? chalk_1.default.yellow("●") :
+            status === "poor" ? chalk_1.default.red("●") :
+                status === "info" ? chalk_1.default.blue("●") :
+                    chalk_1.default.gray("·");
+    console.log(`  ${dot}  ${chalk_1.default.gray(label.padEnd(24))} ${value}`);
+}
+// ── Score badge ───────────────────────────────────────────────
+// Formats a 0-100 score with a color band.
+function scoreBadge(score) {
+    if (score >= 90)
+        return chalk_1.default.green.bold(`${score}/100`) + chalk_1.default.green("  Excellent");
+    if (score >= 70)
+        return chalk_1.default.yellow.bold(`${score}/100`) + chalk_1.default.yellow("  Good");
+    if (score >= 50)
+        return chalk_1.default.hex("#FFA500").bold(`${score}/100`) + chalk_1.default.hex("#FFA500")("  Needs Work");
+    return chalk_1.default.red.bold(`${score}/100`) + chalk_1.default.red("  Poor");
+}
+// ── Severity icon ─────────────────────────────────────────────
+function severityIcon(s) {
+    if (s === "critical")
+        return chalk_1.default.red("❌");
+    if (s === "warning")
+        return chalk_1.default.yellow("⚠️ ");
+    return chalk_1.default.blue("ℹ️ ");
+}
+// ── Done / fail ───────────────────────────────────────────────
+function printDone(message) {
+    console.log();
+    console.log(chalk_1.default.green.bold(`  ✅  ${message}`));
+    console.log();
+}
+function printFail(message) {
+    console.log();
+    console.log(chalk_1.default.red.bold(`  ❌  ${message}`));
+    console.log();
+}
+// ── Muted info line ───────────────────────────────────────────
+function printInfo(label, value) {
+    console.log(`  ${chalk_1.default.gray(label.padEnd(16))} ${chalk_1.default.white(value)}`);
+}
+// ── Web vital threshold helper ────────────────────────────────
+// Maps a metric value to good/warn/poor for colored output.
+function vitalStatus(metric, value) {
+    const thresholds = {
+        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";
+}