react-doctor 0.2.14-dev.b3c3aa9 → 0.2.14-dev.b9e9bcb

package/dist/cli.js

@@ -30,6 +30,7 @@ import * as ChildProcess from "effect/unstable/process/ChildProcess";
 import { ChildProcessSpawner } from "effect/unstable/process/ChildProcessSpawner";
 import * as ts from "typescript";
 import { gzipSync } from "node:zlib";
+import * as Sentry from "@sentry/node";
 import { performance } from "node:perf_hooks";
 import { stripVTControlCharacters } from "node:util";
 import tty from "node:tty";
@@ -6313,6 +6314,7 @@ const STAGED_FILES_PROJECT_CONFIG_FILENAMES = [
 	".oxlintrc.json"
 ];
 const CANONICAL_GITHUB_URL = "https://github.com/millionco/react-doctor";
+const CANONICAL_DISCORD_URL = "https://react.doctor/discord";
 const SKILL_NAME = "react-doctor";
 const OXLINT_OUTPUT_MAX_BYTES = 50 * 1024 * 1024;
 const OXLINT_SPAWN_TIMEOUT_MS = 6e4;
@@ -11417,6 +11419,25 @@ const highlighter = {
 	bold: import_picocolors.default.bold
 };
 /**
+* Override picocolors' automatic color detection. picocolors decides
+* once, at import time, from `NO_COLOR` / `FORCE_COLOR` / `TERM` / TTY.
+* This lets the CLI honor an explicit `--color` / `--no-color` flag
+* (clig.dev, Output: "Disable color … if the user requested it") by
+* swapping in a fresh set of formatters. Call it before any colored
+* output is produced. Every call site reads `highlighter.<method>` at
+* call time, so reassigning the properties propagates everywhere.
+*/
+const setColorEnabled = (enabled) => {
+	const colors = import_picocolors.default.createColors(enabled);
+	highlighter.error = colors.red;
+	highlighter.warn = colors.yellow;
+	highlighter.info = colors.cyan;
+	highlighter.success = colors.green;
+	highlighter.dim = colors.dim;
+	highlighter.gray = colors.gray;
+	highlighter.bold = colors.bold;
+};
+/**
 * Canonical URL for a rule's reviewer-tested fix recipe, served at
 * `https://www.react.doctor/prompts/rules/<plugin>/<rule>.md`. The
 * `/doctor` playbook fetches it on demand so each fix follows the
@@ -11448,6 +11469,46 @@ const groupBy = (items, keyFn) => {
 */
 const hasPublishedFixRecipe = (diagnostic) => diagnostic.plugin === "react-doctor" && Object.hasOwn(reactDoctorPlugin.rules, diagnostic.rule);
 //#endregion
+//#region src/cli/utils/constants.ts
+const STAGED_FILES_TEMP_DIR_PREFIX = "react-doctor-staged-";
+const INTERNAL_ERROR_JSON_FALLBACK = "{\"schemaVersion\":1,\"ok\":false,\"error\":{\"message\":\"Internal error\",\"name\":\"Error\",\"chain\":[]}}\n";
+const SENTRY_DSN = "https://f253d570240a59b8dbd77b7a548ef133@o4510226365743104.ingest.us.sentry.io/4511487817809920";
+//#endregion
+//#region src/cli/utils/version.ts
+const VERSION = "0.2.14-dev.b9e9bcb";
+//#endregion
+//#region src/instrument.ts
+let isInitialized = false;
+const shouldEnableSentry = () => {
+	if (process.argv.includes("--no-score") || process.argv.includes("--no-telemetry")) return false;
+	if (process.env.VITEST || process.env.NODE_ENV === "test") return false;
+	return true;
+};
+/**
+* Initializes the Sentry Node SDK for CLI crash reporting. Invoked as
+* the first statement of the CLI entry (`cli/index.ts`) so the SDK's
+* global `uncaughtException` / `unhandledRejection` handlers are armed
+* before any command runs.
+*
+* Exported as a function rather than a bare side-effecting import
+* because the package declares `"sideEffects": false`, which lets the
+* bundler tree-shake side-effect-only modules. An explicit call keeps
+* the initialization in the published `dist/cli.js`.
+*
+* Scoped to the CLI application only — the programmatic
+* `@react-doctor/api` library never initializes Sentry, so importing
+* `diagnose()` into a consumer app can't hijack their telemetry.
+*/
+const initializeSentry = () => {
+	if (isInitialized || !shouldEnableSentry()) return;
+	isInitialized = true;
+	Sentry.init({
+		dsn: SENTRY_DSN,
+		sendDefaultPii: true,
+		release: VERSION
+	});
+};
+//#endregion
 //#region ../../node_modules/.pnpm/chalk@5.6.2/node_modules/chalk/source/vendor/ansi-styles/index.js
 const ANSI_BACKGROUND_OFFSET = 10;
 const wrapAnsi16 = (offset = 0) => (code) => `\u001B[${code + offset}m`;
@@ -14401,29 +14462,60 @@ const CI_ENVIRONMENT_VARIABLES = [
 	"GITLAB_CI",
 	"CIRCLECI"
 ];
-const CODING_AGENT_ENVIRONMENT_VARIABLES = [
-	"CLAUDECODE",
-	"CLAUDE_CODE",
-	"CURSOR_AGENT",
-	"CODEX_CI",
-	"CODEX_SANDBOX",
-	"CODEX_SANDBOX_NETWORK_DISABLED",
-	"OPENCODE",
-	"GOOSE_TERMINAL",
-	"AGENT_SESSION_ID",
-	"AMP_THREAD_ID",
-	"AGENT_THREAD_ID"
+const CI_PROVIDER_BY_ENVIRONMENT_VARIABLE = [
+	["GITHUB_ACTIONS", "github-actions"],
+	["GITLAB_CI", "gitlab-ci"],
+	["CIRCLECI", "circleci"],
+	["BUILDKITE", "buildkite"],
+	["JENKINS_URL", "jenkins"],
+	["TF_BUILD", "azure-pipelines"],
+	["CODEBUILD_BUILD_ID", "aws-codebuild"],
+	["TEAMCITY_VERSION", "teamcity"],
+	["BITBUCKET_BUILD_NUMBER", "bitbucket"],
+	["TRAVIS", "travis"],
+	["DRONE", "drone"]
 ];
+const CODING_AGENT_BY_ENVIRONMENT_VARIABLE = [
+	["CLAUDECODE", "claude-code"],
+	["CLAUDE_CODE", "claude-code"],
+	["CURSOR_AGENT", "cursor"],
+	["CODEX_CI", "codex"],
+	["CODEX_SANDBOX", "codex"],
+	["CODEX_SANDBOX_NETWORK_DISABLED", "codex"],
+	["OPENCODE", "opencode"],
+	["GOOSE_TERMINAL", "goose"],
+	["AMP_THREAD_ID", "amp"]
+];
+const GENERIC_CODING_AGENT_ENVIRONMENT_VARIABLES = ["AGENT_SESSION_ID", "AGENT_THREAD_ID"];
 const CODING_AGENT_ENVIRONMENT_VALUE_VARIABLES = ["AGENT"];
 const CODING_AGENT_ENVIRONMENT_VALUES = { AGENT: ["amp", "goose"] };
+[...CODING_AGENT_BY_ENVIRONMENT_VARIABLE.map(([environmentVariable]) => environmentVariable), ...GENERIC_CODING_AGENT_ENVIRONMENT_VARIABLES];
 const FALSY_CI_FLAG_VALUES = new Set([
 	"",
 	"0",
 	"false"
 ]);
 const isCiFlagSet = (value) => value !== void 0 && !FALSY_CI_FLAG_VALUES.has(value.toLowerCase());
-const isCiEnvironment = () => CI_ENVIRONMENT_VARIABLES.some((envVariable) => Boolean(process.env[envVariable])) || isCiFlagSet(process.env.CI);
-const isCodingAgentEnvironment = () => CODING_AGENT_ENVIRONMENT_VARIABLES.some((envVariable) => Boolean(process.env[envVariable])) || CODING_AGENT_ENVIRONMENT_VALUE_VARIABLES.some((envVariable) => CODING_AGENT_ENVIRONMENT_VALUES[envVariable].some((value) => process.env[envVariable]?.toLowerCase() === value));
+const isCiEnvironment = () => CI_ENVIRONMENT_VARIABLES.some((environmentVariable) => Boolean(process.env[environmentVariable])) || isCiFlagSet(process.env.CI);
+const detectCiProvider = () => {
+	for (const [environmentVariable, provider] of CI_PROVIDER_BY_ENVIRONMENT_VARIABLE) if (process.env[environmentVariable]) return provider;
+	return isCiFlagSet(process.env.CI) ? "unknown" : null;
+};
+const detectCodingAgentFromValue = () => {
+	for (const environmentVariable of CODING_AGENT_ENVIRONMENT_VALUE_VARIABLES) {
+		const value = process.env[environmentVariable]?.toLowerCase();
+		if (value && CODING_AGENT_ENVIRONMENT_VALUES[environmentVariable].includes(value)) return value;
+	}
+	return null;
+};
+const detectCodingAgent = () => {
+	for (const [environmentVariable, agent] of CODING_AGENT_BY_ENVIRONMENT_VARIABLE) if (process.env[environmentVariable]) return agent;
+	const agentFromValue = detectCodingAgentFromValue();
+	if (agentFromValue) return agentFromValue;
+	if (GENERIC_CODING_AGENT_ENVIRONMENT_VARIABLES.some((environmentVariable) => process.env[environmentVariable])) return "unknown";
+	return null;
+};
+const isCodingAgentEnvironment = () => detectCodingAgent() !== null;
 const isCiOrCodingAgentEnvironment = () => isCiEnvironment() || isCodingAgentEnvironment();
 //#endregion
 //#region src/cli/utils/is-non-interactive-environment.ts
@@ -14956,10 +15048,6 @@ const colorizeByScore = (text, score) => {
 	return highlighter.error(text);
 };
 //#endregion
-//#region src/cli/utils/constants.ts
-const STAGED_FILES_TEMP_DIR_PREFIX = "react-doctor-staged-";
-const INTERNAL_ERROR_JSON_FALLBACK = "{\"schemaVersion\":1,\"ok\":false,\"error\":{\"message\":\"Internal error\",\"name\":\"Error\",\"chain\":[]}}\n";
-//#endregion
 //#region src/cli/utils/render-score-header.ts
 const RAINBOW_HUE_SHIFT_PER_FRAME = 9;
 const RAINBOW_GRADIENT_WIDTH = 80;
@@ -15344,9 +15432,6 @@ const resolveOxlintNodeEffect = (isLintEnabled, isQuiet) => Effect.gen(function*
 });
 const resolveOxlintNode = (isLintEnabled, isQuiet) => Effect.runPromise(resolveOxlintNodeEffect(isLintEnabled, isQuiet).pipe(Effect.provide(NodeResolver.layerNode)));
 //#endregion
-//#region src/cli/utils/version.ts
-const VERSION = "0.2.14-dev.b3c3aa9";
-//#endregion
 //#region src/inspect.ts
 const silentConsole = makeNoopConsole();
 const runConsole = (effect) => {
@@ -15635,6 +15720,7 @@ const handleErrorEffect = (error) => Effect.gen(function* () {
 	yield* Console.error("");
 	yield* Console.error(highlighter.error("Something went wrong. Please check the error below for more details."));
 	yield* Console.error(highlighter.error(`If the problem persists, please open this prefilled issue: ${buildErrorIssueUrl(error)}`));
+	yield* Console.error(highlighter.error(`You can also ask for help in Discord: ${CANONICAL_DISCORD_URL}`));
 	yield* Console.error("");
 	yield* Console.error(highlighter.error(formatErrorForReport(error)));
 	yield* Console.error("");
@@ -17084,6 +17170,78 @@ const printBrandedHeader = Effect.gen(function* () {
 	yield* Console.log("");
 });
 //#endregion
+//#region src/cli/utils/build-run-context.ts
+const ROOT_SUBCOMMANDS = new Set(["install", "setup"]);
+const detectOrigin = () => {
+	if (process.env.GIT_DIR) return "git-hook";
+	if (isCodingAgentEnvironment()) return "agent";
+	if (isCiEnvironment()) return "ci";
+	return "cli";
+};
+const detectCommand = (userArguments) => {
+	for (const argument of userArguments) {
+		if (argument === "--") break;
+		if (argument.startsWith("-")) continue;
+		return ROOT_SUBCOMMANDS.has(argument) ? argument : "inspect";
+	}
+	return "inspect";
+};
+/**
+* Snapshot of the current invocation, attached to Sentry events as the
+* `run` context to make crashes triage-able (which version, platform,
+* CI/agent, how it was invoked). Every field is cheap, synchronous, and
+* safe to read at any point — cwd reads fall back, env reads are
+* booleans — so it's rebuilt lazily at capture time when runtime-only
+* signals like `jsonMode` are finally known.
+*/
+const buildRunContext = () => {
+	const userArguments = process.argv.slice(2);
+	return {
+		version: VERSION,
+		origin: detectOrigin(),
+		command: detectCommand(userArguments),
+		argv: userArguments.join(" "),
+		cwd: process.cwd(),
+		node: process.version,
+		platform: process.platform,
+		arch: process.arch,
+		ci: isCiEnvironment(),
+		ciProvider: detectCiProvider(),
+		codingAgent: detectCodingAgent(),
+		interactive: !isNonInteractiveEnvironment(),
+		jsonMode: isJsonModeActive()
+	};
+};
+//#endregion
+//#region src/cli/utils/report-error.ts
+/**
+* Sends an error to Sentry, enriched with a snapshot of the current run
+* (version, platform, CI/agent, invocation), and waits for delivery
+* before the caller exits. The CLI tears down the process synchronously
+* after rendering an error, so the awaited `flush` is what actually gets
+* the event off the machine (see the Sentry CLI/serverless flush
+* contract).
+*
+* Returns early when Sentry was never initialized (`--no-score`, tests,
+* or a missing DSN), and swallows any transport failure so telemetry can
+* never mask the user's original error.
+*/
+const reportErrorToSentry = async (error) => {
+	if (!Sentry.isInitialized()) return;
+	try {
+		const runContext = buildRunContext();
+		Sentry.setContext("run", { ...runContext });
+		Sentry.setTags({
+			origin: runContext.origin,
+			command: runContext.command,
+			ciProvider: runContext.ciProvider,
+			codingAgent: runContext.codingAgent
+		});
+		Sentry.captureException(error);
+		await Sentry.flush(2e3);
+	} catch {}
+};
+//#endregion
 //#region src/cli/utils/path-format.ts
 const toForwardSlashes = (filePath) => filePath.replaceAll("\\", "/");
 //#endregion
@@ -17278,7 +17436,7 @@ const resolveCliInspectOptions = (flags, userConfig) => {
 		respectInlineDisables: flags.respectInlineDisables,
 		warnings: flags.warnings ?? (wantsWarningGate ? true : void 0),
 		scoreOnly: flags.score === true,
-		noScore: flags.score === false || (userConfig?.noScore ?? false),
+		noScore: flags.score === false || flags.telemetry === false || (userConfig?.noScore ?? false),
 		isCi: isCiEnvironment(),
 		silent: Boolean(flags.json),
 		outputSurface: flags.prComment ? "prComment" : "cli",
@@ -17547,6 +17705,7 @@ const validateModeFlags = (flags) => {
 	if (exclusiveModes.length > 1) throw new Error(`Cannot combine ${exclusiveModes.join(" and ")}; pick one mode.`);
 	if (flags.yes && flags.full) throw new Error("Cannot combine --yes and --full; pick one.");
 	if (flags.score && flags.json) throw new Error("Cannot combine --score and --json; pick one output mode.");
+	if (flags.score && flags.telemetry === false) throw new Error("Cannot combine --score with --no-telemetry; --score prints the score that --no-telemetry disables.");
 	if (flags.prComment && (flags.json || flags.score)) throw new Error("--pr-comment cannot be combined with --json or --score.");
 	if (flags.annotations && flags.score) throw new Error("--annotations cannot be combined with --score.");
 	if (flags.explain !== void 0 && flags.why !== void 0) throw new Error("Use --explain or --why, not both — they're aliases of the same flag.");
@@ -17766,6 +17925,7 @@ const inspectAction = async (directory, flags) => {
 			})) printAgentInstallHint();
 		}
 	} catch (error) {
+		await reportErrorToSentry(error);
 		if (isJsonMode) {
 			writeJsonErrorReport(error);
 			process.exitCode = 1;
@@ -17787,10 +17947,61 @@ const installAction = async (options, command) => {
 			projectRoot: options.cwd ?? process.cwd()
 		});
 	} catch (error) {
+		await reportErrorToSentry(error);
 		handleError(error);
 	}
 };
 //#endregion
+//#region src/cli/commands/version.ts
+/**
+* oclif-style version line. 12-factor CLI Apps (#3, "What version am I
+* on?"): the `version` command is the primary place users grab debugging
+* info, so it carries the Node runtime and platform alongside the CLI
+* version. The `-v` / `-V` / `--version` flags stay terse (just the
+* number) so scripts can parse them.
+*/
+const buildVersionString = () => `react-doctor/${VERSION} ${process.platform}-${process.arch} node-${process.version}`;
+const versionAction = () => {
+	process.stdout.write(`${buildVersionString()}\n`);
+};
+//#endregion
+//#region src/cli/utils/apply-color-preference.ts
+/**
+* Resolve an explicit color preference from `--color` / `--no-color` or the
+* app-specific `REACT_DOCTOR_NO_COLOR` / `REACT_DOCTOR_FORCE_COLOR` env vars
+* (clig.dev Output; 12-factor #6), overriding picocolors' own
+* `NO_COLOR` / `FORCE_COLOR` / `TERM` / TTY detection. Flags win over env
+* vars; with neither set, picocolors' detection stands.
+*
+* A resolved preference is mirrored onto the standard `NO_COLOR` /
+* `FORCE_COLOR` env vars in addition to our picocolors highlighter, so
+* libraries with their own color stacks (the `ora` spinner, `prompts`)
+* honor it too rather than only the scan report. Scanning argv directly
+* (not Commander's parsed options) applies the preference before Commander
+* parses, so it reaches every later path. The scan stops at `--`.
+*/
+const applyColorPreference = (argv, env = process.env) => {
+	let enabled;
+	for (const argument of argv) {
+		if (argument === "--") break;
+		if (argument === "--no-color") enabled = false;
+		else if (argument === "--color") enabled = true;
+	}
+	if (enabled === void 0) {
+		if (env.REACT_DOCTOR_NO_COLOR) enabled = false;
+		else if (env.REACT_DOCTOR_FORCE_COLOR) enabled = true;
+	}
+	if (enabled === void 0) return;
+	if (enabled) {
+		env.FORCE_COLOR = "1";
+		delete env.NO_COLOR;
+	} else {
+		env.NO_COLOR = "1";
+		delete env.FORCE_COLOR;
+	}
+	setColorEnabled(enabled);
+};
+//#endregion
 //#region src/cli/utils/exit-gracefully.ts
 const exitGracefully = () => {
 	try {
@@ -17800,21 +18011,54 @@ const exitGracefully = () => {
 	process.exit(130);
 };
 //#endregion
+//#region src/cli/utils/normalize-help-command.ts
+/**
+* 12-factor CLI Apps (#1, "Great help is essential"): `mycli help` and
+* `mycli help <command>` must display help. Commander doesn't wire this
+* up once the root command has its own default action plus a positional
+* argument — it treats a leading `help` as the `[directory]` to scan,
+* which then errors with "No React project found in ./help".
+*
+* We rewrite the argv up front so the existing `--help` paths handle it:
+*   `react-doctor help`         -> `react-doctor --help`
+*   `react-doctor help install` -> `react-doctor install --help`
+*
+* Only a *leading* `help` token is rewritten, so a flag value such as
+* `--project help` is never mistaken for the help command. The target is
+* the first non-flag token after `help`, so intervening flags like
+* `help --no-color install` still resolve to `install`. An unknown target
+* (`help bogus`) falls back to root help rather than erroring.
+*/
+const normalizeHelpInvocation = (argv, knownCommands) => {
+	const nodeArguments = argv.slice(0, 2);
+	const userArguments = argv.slice(2);
+	if (userArguments[0] !== "help") return [...argv];
+	const target = userArguments.slice(1).find((argument) => !argument.startsWith("-"));
+	if (target !== void 0 && knownCommands.includes(target)) return [
+		...nodeArguments,
+		target,
+		"--help"
+	];
+	return [...nodeArguments, "--help"];
+};
+//#endregion
 //#region src/cli/utils/strip-unknown-cli-flags.ts
-const NODE_ARGUMENT_COUNT = 2;
 const ROOT_FLAG_SPEC = {
 	longOptionsWithoutValues: new Set([
 		"--annotations",
+		"--color",
 		"--dead-code",
 		"--full",
 		"--help",
 		"--json",
 		"--json-compact",
 		"--lint",
+		"--no-color",
 		"--no-dead-code",
 		"--no-lint",
 		"--no-respect-inline-disables",
 		"--no-score",
+		"--no-telemetry",
 		"--no-warnings",
 		"--pr-comment",
 		"--respect-inline-disables",
@@ -17843,8 +18087,10 @@ const ROOT_FLAG_SPEC = {
 const INSTALL_FLAG_SPEC = {
 	longOptionsWithoutValues: new Set([
 		"--agent-hooks",
+		"--color",
 		"--dry-run",
 		"--help",
+		"--no-color",
 		"--yes"
 	]),
 	longOptionsWithRequiredValues: new Set(["--cwd"]),
@@ -17852,7 +18098,21 @@ const INSTALL_FLAG_SPEC = {
 	shortOptionsWithoutValues: new Set(["-h", "-y"]),
 	shortOptionsWithRequiredValues: new Set(["-c"])
 };
-const COMMAND_FLAG_SPECS = new Map([["install", INSTALL_FLAG_SPEC], ["setup", INSTALL_FLAG_SPEC]]);
+const COMMAND_FLAG_SPECS = new Map([
+	["install", INSTALL_FLAG_SPEC],
+	["setup", INSTALL_FLAG_SPEC],
+	["version", {
+		longOptionsWithoutValues: new Set([
+			"--color",
+			"--help",
+			"--no-color"
+		]),
+		longOptionsWithRequiredValues: /* @__PURE__ */ new Set(),
+		longOptionsWithOptionalValues: /* @__PURE__ */ new Set(),
+		shortOptionsWithoutValues: new Set(["-h"]),
+		shortOptionsWithRequiredValues: /* @__PURE__ */ new Set()
+	}]
+]);
 const isFlagLike = (argument) => argument.startsWith("-") && argument !== "-";
 const getLongOptionName = (argument) => {
 	const equalsIndex = argument.indexOf("=");
@@ -17906,8 +18166,8 @@ const stripUnknownFlags = (userArguments, flagSpec) => {
 	return sanitizedArguments;
 };
 const stripUnknownCliFlags = (argv) => {
-	const nodeArguments = argv.slice(0, NODE_ARGUMENT_COUNT);
-	const userArguments = argv.slice(NODE_ARGUMENT_COUNT);
+	const nodeArguments = argv.slice(0, 2);
+	const userArguments = argv.slice(2);
 	const commandIndex = findCommandIndex(userArguments);
 	if (commandIndex === null) return [...nodeArguments, ...stripUnknownFlags(userArguments, ROOT_FLAG_SPEC)];
 	const commandName = userArguments[commandIndex];
@@ -17921,23 +18181,66 @@ const stripUnknownCliFlags = (argv) => {
 };
 //#endregion
 //#region src/cli/index.ts
+initializeSentry();
 process.on("SIGINT", exitGracefully);
 process.on("SIGTERM", exitGracefully);
 unrefStdin();
-const program = new Command().name("react-doctor").description("Diagnose React codebase health").version(VERSION, "-v, --version", "display the version number").argument("[directory]", "project directory to scan", ".").option("--lint", "enable linting").option("--no-lint", "skip linting").option("--dead-code", "enable dead-code analysis (default)").option("--no-dead-code", "skip dead-code analysis (unused files / exports / dependencies, circular imports)").option("--verbose", "show every rule and per-file details (default shows top 3 rules)").option("--score", "output only the score").option("--json", "output a single structured JSON report (suppresses other output)").option("--json-compact", "with --json, emit compact JSON (no indentation)").option("-y, --yes", "skip prompts, scan all workspace projects").option("--full", "force a full scan (overrides any `diff` value in config or `--diff`)").option("--experimental-parallel [workers]", "experimental: lint with N parallel workers (default: auto-detect CPU cores) — speeds up large repos").option("--project <name>", "select workspace project (comma-separated for multiple)").option("--diff [base]", "scan only files changed vs base branch (pass `false` to disable; overridden by --full)").option("--changed-files-from <file>", "internal: scan source files listed in a newline-delimited changed-files file").option("--no-score", "skip the score API and the share URL").option("--staged", "scan only staged (git index) files for pre-commit hooks").option("--fail-on <level>", "exit with error code on diagnostics: error, warning, none (default: none)").option("--annotations", "output diagnostics as GitHub Actions annotations").option("--pr-comment", "tune CLI output for sticky PR comments (drops weak-signal rule families like `design` from the printed list and the fail-on gate; configure via config.surfaces)").option("--explain <file:line>", "diagnose why a rule fired or why a suppression didn't apply at a specific location").option("--why <file:line>", "alias for --explain").option("--respect-inline-disables", "respect inline `// eslint-disable*` / `// oxlint-disable*` comments (default)").option("--no-respect-inline-disables", "audit mode: neutralize inline lint suppressions before scanning").option("--warnings", "show warning-severity diagnostics (errors always show)").option("--no-warnings", "hide warning-severity diagnostics (default)").addHelpText("after", `
+const formatExampleLines = (examples) => {
+	const width = Math.max(...examples.map(([command]) => command.length));
+	return examples.map(([command, description]) => `  $ ${command.padEnd(width)}  ${highlighter.dim(`# ${description}`)}`).join("\n");
+};
+const renderRootHelpEpilog = () => `
+${highlighter.dim("Examples:")}
+${formatExampleLines([
+	["react-doctor", "scan the current project"],
+	["react-doctor ./apps/web", "scan a specific directory"],
+	["react-doctor --diff main", "scan only files changed vs. main"],
+	["react-doctor --staged", "scan staged files (pre-commit hook)"],
+	["react-doctor --fail-on warning", "exit non-zero on warnings (CI gate)"],
+	["react-doctor --json > report.json", "write a machine-readable report"],
+	["react-doctor --explain src/App.tsx:42", "explain why a rule fired there"],
+	["react-doctor install", "set up the agent skill and git hook"]
+])}
+
 ${highlighter.dim("Configuration:")}
   Place a ${highlighter.info("react-doctor.config.json")} (or ${highlighter.info("\"reactDoctor\"")} key in your package.json) in the project root.
   CLI flags always override config values. See the README for the full schema.
 
+${highlighter.dim("Feedback & bug reports:")}
+  ${highlighter.info(`${CANONICAL_GITHUB_URL}/issues`)}
+
 ${highlighter.dim("Learn more:")}
   ${highlighter.info(CANONICAL_GITHUB_URL)}
-`);
+`;
+const renderInstallHelpEpilog = () => `
+${highlighter.dim("Examples:")}
+${formatExampleLines([
+	["react-doctor install", "interactive setup"],
+	["react-doctor install --yes", "non-interactive; all detected agents"],
+	["react-doctor install --dry-run", "preview without writing files"],
+	["react-doctor install --agent-hooks", "also install native agent hooks"]
+])}
+
+${highlighter.dim("Learn more:")}
+  ${highlighter.info(CANONICAL_GITHUB_URL)}
+`;
+const program = new Command().name("react-doctor").description("Diagnose React codebase health").version(VERSION, "-v, --version", "display the version number").argument("[directory]", "project directory to scan", ".").option("--lint", "enable linting").option("--no-lint", "skip linting").option("--dead-code", "enable dead-code analysis (default)").option("--no-dead-code", "skip dead-code analysis (unused files / exports / dependencies, circular imports)").option("--verbose", "show every rule and per-file details (default shows top 3 rules)").option("--score", "output only the score").option("--json", "output a single structured JSON report (suppresses other output)").option("--json-compact", "with --json, emit compact JSON (no indentation)").option("-y, --yes", "skip prompts, scan all workspace projects").option("--full", "force a full scan (overrides any `diff` value in config or `--diff`)").option("--experimental-parallel [workers]", "experimental: lint with N parallel workers (default: auto-detect CPU cores) — speeds up large repos").option("--project <name>", "select workspace project (comma-separated for multiple)").option("--diff [base]", "scan only files changed vs base branch (pass `false` to disable; overridden by --full)").option("--changed-files-from <file>", "internal: scan source files listed in a newline-delimited changed-files file").option("--no-score", "skip the score API, the share URL, and crash reporting").option("--no-telemetry", "alias for --no-score (skip the score API, share URL, and crash reporting)").option("--staged", "scan only staged (git index) files for pre-commit hooks").option("--fail-on <level>", "exit with error code on diagnostics: error, warning, none (default: none)").option("--annotations", "output diagnostics as GitHub Actions annotations").option("--pr-comment", "tune CLI output for sticky PR comments (drops weak-signal rule families like `design` from the printed list and the fail-on gate; configure via config.surfaces)").option("--explain <file:line>", "diagnose why a rule fired or why a suppression didn't apply at a specific location").option("--why <file:line>", "alias for --explain").option("--respect-inline-disables", "respect inline `// eslint-disable*` / `// oxlint-disable*` comments (default)").option("--no-respect-inline-disables", "audit mode: neutralize inline lint suppressions before scanning").option("--warnings", "show warning-severity diagnostics (errors always show)").option("--no-warnings", "hide warning-severity diagnostics (default)").option("--color", "force colored output").option("--no-color", "disable colored output (also honors NO_COLOR)").addHelpText("after", renderRootHelpEpilog);
 program.action(inspectAction);
-program.command("install").alias("setup").description("Install the react-doctor skill into your coding agents and optional git hook").option("-y, --yes", "skip prompts, install for all detected agents").option("--dry-run", "show what would be installed without writing files").option("--agent-hooks", "install native non-blocking agent hooks for Claude Code and Cursor").option("-c, --cwd <cwd>", "working directory", process.cwd()).action(installAction);
+program.command("install").alias("setup").description("Install the react-doctor skill into your coding agents and optional git hook").option("-y, --yes", "skip prompts, install for all detected agents").option("--dry-run", "show what would be installed without writing files").option("--agent-hooks", "install native non-blocking agent hooks for Claude Code and Cursor").option("-c, --cwd <cwd>", "working directory", process.cwd()).option("--color", "force colored output").option("--no-color", "disable colored output (also honors NO_COLOR)").addHelpText("after", renderInstallHelpEpilog).action(installAction);
+program.command("version").description("show the version with Node and platform info").option("--color", "force colored output").option("--no-color", "disable colored output (also honors NO_COLOR)").action(versionAction);
 process.stdout.on("error", (error) => {
 	if (error.code === "EPIPE") process.exit(0);
 });
-program.parseAsync(stripUnknownCliFlags(process.argv)).catch((error) => {
+const knownCommands = program.commands.flatMap((command) => [command.name(), ...command.aliases()]);
+const strippedArgv = stripUnknownCliFlags(process.argv);
+if (process.argv.includes("-V") && !strippedArgv.includes("-V")) {
+	process.stdout.write(`${VERSION}\n`);
+	process.exit(0);
+}
+applyColorPreference(strippedArgv);
+const argv = normalizeHelpInvocation(strippedArgv, knownCommands);
+program.parseAsync(argv).catch(async (error) => {
+	await reportErrorToSentry(error);
 	if (isJsonModeActive()) {
 		writeJsonErrorReport(error);
 		process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-doctor",
-  "version": "0.2.14-dev.b3c3aa9",
+  "version": "0.2.14-dev.b9e9bcb",
   "description": "Diagnose and fix React codebases for security, performance, correctness, accessibility, bundle-size, and architecture issues",
   "keywords": [
     "accessibility",
@@ -51,6 +51,7 @@
   "dependencies": {
     "@babel/code-frame": "^7.29.0",
     "@effect/platform-node-shared": "4.0.0-beta.70",
+    "@sentry/node": "^10.54.0",
     "agent-install": "0.0.5",
     "conf": "^15.1.0",
     "deslop-js": "^0.0.14",
@@ -59,7 +60,7 @@
     "oxlint": "^1.66.0",
     "prompts": "^2.4.2",
     "typescript": ">=5.0.4 <7",
-    "oxlint-plugin-react-doctor": "0.2.14-dev.b3c3aa9"
+    "oxlint-plugin-react-doctor": "0.2.14-dev.b9e9bcb"
   },
   "devDependencies": {
     "@types/babel__code-frame": "^7.27.0",