react-doctor 0.0.21 → 0.0.23

package/README.md

@@ -15,6 +15,15 @@ One command scans your codebase for security, performance, correctness, and arch
 
 https://github.com/user-attachments/assets/07cc88d9-9589-44c3-aa73-5d603cb1c570
 
+## How it works
+
+React Doctor detects your framework (Next.js, Vite, Remix, etc.), React version, and compiler setup, then runs two analysis passes **in parallel**:
+
+1. **Lint**: Checks 60+ rules across state & effects, performance, architecture, bundle size, security, correctness, accessibility, and framework-specific categories (Next.js, React Native). Rules are toggled automatically based on your project setup.
+2. **Dead code**: Detects unused files, exports, types, and duplicates.
+
+Diagnostics are filtered through your config, then scored by severity (errors weigh more than warnings) to produce a **0–100 health score** (75+ Great, 50–74 Needs work, <50 Critical).
+
 ## Install
 
 Run this at your project root:

package/dist/cli.js

@@ -27,6 +27,7 @@ const SEPARATOR_LENGTH_CHARS = 40;
 const SUMMARY_BOX_HORIZONTAL_PADDING_CHARS = 1;
 const SUMMARY_BOX_OUTER_INDENT_CHARS = 2;
 const SCORE_API_URL = "https://www.react.doctor/api/score";
+const ESTIMATE_SCORE_API_URL = "https://www.react.doctor/api/estimate-score";
 const SHARE_BASE_URL = "https://www.react.doctor/share";
 const OPEN_BASE_URL = "https://www.react.doctor/open";
 const GIT_LS_FILES_MAX_BUFFER_BYTES = 50 * 1024 * 1024;
@@ -36,17 +37,54 @@ const DEFAULT_BRANCH_CANDIDATES = ["main", "master"];
 
 //#endregion
 //#region src/utils/calculate-score.ts
+const ERROR_RULE_PENALTY = 1.5;
+const WARNING_RULE_PENALTY = .75;
+const ERROR_ESTIMATED_FIX_RATE = .85;
+const WARNING_ESTIMATED_FIX_RATE = .8;
+const buildDiagnosticPayload = (diagnostics) => diagnostics.map((diagnostic) => ({
+	plugin: diagnostic.plugin,
+	rule: diagnostic.rule,
+	severity: diagnostic.severity
+}));
+const getScoreLabel = (score) => {
+	if (score >= SCORE_GOOD_THRESHOLD) return "Great";
+	if (score >= SCORE_OK_THRESHOLD) return "Needs work";
+	return "Critical";
+};
+const countUniqueRules = (diagnostics) => {
+	const errorRules = /* @__PURE__ */ new Set();
+	const warningRules = /* @__PURE__ */ new Set();
+	for (const diagnostic of diagnostics) {
+		const ruleKey = `${diagnostic.plugin}/${diagnostic.rule}`;
+		if (diagnostic.severity === "error") errorRules.add(ruleKey);
+		else warningRules.add(ruleKey);
+	}
+	return {
+		errorRuleCount: errorRules.size,
+		warningRuleCount: warningRules.size
+	};
+};
+const scoreFromRuleCounts = (errorRuleCount, warningRuleCount) => {
+	const penalty = errorRuleCount * ERROR_RULE_PENALTY + warningRuleCount * WARNING_RULE_PENALTY;
+	return Math.max(0, Math.round(PERFECT_SCORE - penalty));
+};
+const estimateScoreLocally = (diagnostics) => {
+	const { errorRuleCount, warningRuleCount } = countUniqueRules(diagnostics);
+	const currentScore = scoreFromRuleCounts(errorRuleCount, warningRuleCount);
+	const estimatedScore = scoreFromRuleCounts(Math.round(errorRuleCount * (1 - ERROR_ESTIMATED_FIX_RATE)), Math.round(warningRuleCount * (1 - WARNING_ESTIMATED_FIX_RATE)));
+	return {
+		currentScore,
+		currentLabel: getScoreLabel(currentScore),
+		estimatedScore,
+		estimatedLabel: getScoreLabel(estimatedScore)
+	};
+};
 const calculateScore = async (diagnostics) => {
-	const payload = diagnostics.map((diagnostic) => ({
-		plugin: diagnostic.plugin,
-		rule: diagnostic.rule,
-		severity: diagnostic.severity
-	}));
 	try {
 		const response = await fetch(SCORE_API_URL, {
 			method: "POST",
 			headers: { "Content-Type": "application/json" },
-			body: JSON.stringify({ diagnostics: payload })
+			body: JSON.stringify({ diagnostics: buildDiagnosticPayload(diagnostics) })
 		});
 		if (!response.ok) return null;
 		return await response.json();
@@ -54,6 +92,19 @@ const calculateScore = async (diagnostics) => {
 		return null;
 	}
 };
+const fetchEstimatedScore = async (diagnostics) => {
+	try {
+		const response = await fetch(ESTIMATE_SCORE_API_URL, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({ diagnostics: buildDiagnosticPayload(diagnostics) })
+		});
+		if (!response.ok) return estimateScoreLocally(diagnostics);
+		return await response.json();
+	} catch {
+		return estimateScoreLocally(diagnostics);
+	}
+};
 
 //#endregion
 //#region src/plugin/constants.ts
@@ -395,25 +446,12 @@ const filterIgnoredDiagnostics = (diagnostics, config) => {
 	return diagnostics.filter((diagnostic) => {
 		const ruleIdentifier = `${diagnostic.plugin}/${diagnostic.rule}`;
 		if (ignoredRules.has(ruleIdentifier)) return false;
-		const normalizedPath = diagnostic.filePath.replace(/\\/g, "/");
+		const normalizedPath = diagnostic.filePath.replace(/\\/g, "/").replace(/^\.\//, "");
 		if (ignoredFilePatterns.some((pattern) => pattern.test(normalizedPath))) return false;
 		return true;
 	});
 };
 
-//#endregion
-//#region src/utils/group-by.ts
-const groupBy = (items, keyFn) => {
-	const groups = /* @__PURE__ */ new Map();
-	for (const item of items) {
-		const key = keyFn(item);
-		const existing = groups.get(key) ?? [];
-		existing.push(item);
-		groups.set(key, existing);
-	}
-	return groups;
-};
-
 //#endregion
 //#region src/utils/highlighter.ts
 const highlighter = {
@@ -424,40 +462,6 @@ const highlighter = {
 	dim: pc.dim
 };
 
-//#endregion
-//#region src/utils/indent-multiline-text.ts
-const indentMultilineText = (text, linePrefix) => text.split("\n").map((lineText) => `${linePrefix}${lineText}`).join("\n");
-
-//#endregion
-//#region src/utils/load-config.ts
-const CONFIG_FILENAME = "react-doctor.config.json";
-const PACKAGE_JSON_CONFIG_KEY = "reactDoctor";
-const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-const loadConfig = (rootDirectory) => {
-	const configFilePath = path.join(rootDirectory, CONFIG_FILENAME);
-	if (fs.existsSync(configFilePath)) try {
-		const fileContent = fs.readFileSync(configFilePath, "utf-8");
-		const parsed = JSON.parse(fileContent);
-		if (!isPlainObject(parsed)) {
-			console.warn(`Warning: ${CONFIG_FILENAME} must be a JSON object, ignoring.`);
-			return null;
-		}
-		return parsed;
-	} catch (error) {
-		console.warn(`Warning: Failed to parse ${CONFIG_FILENAME}: ${error instanceof Error ? error.message : String(error)}`);
-		return null;
-	}
-	const packageJsonPath = path.join(rootDirectory, "package.json");
-	if (fs.existsSync(packageJsonPath)) try {
-		const fileContent = fs.readFileSync(packageJsonPath, "utf-8");
-		const embeddedConfig = JSON.parse(fileContent)[PACKAGE_JSON_CONFIG_KEY];
-		if (isPlainObject(embeddedConfig)) return embeddedConfig;
-	} catch {
-		return null;
-	}
-	return null;
-};
-
 //#endregion
 //#region src/utils/strip-ansi.ts
 const ANSI_ESCAPE_SEQUENCE = String.raw`\u001B\[[0-9;]*m`;
@@ -512,6 +516,80 @@ const logger = {
 	}
 };
 
+//#endregion
+//#region src/utils/framed-box.ts
+const createFramedLine = (plainText, renderedText = plainText) => ({
+	plainText,
+	renderedText
+});
+const renderFramedBoxString = (framedLines) => {
+	if (framedLines.length === 0) return "";
+	const borderColorizer = highlighter.dim;
+	const outerIndent = " ".repeat(SUMMARY_BOX_OUTER_INDENT_CHARS);
+	const horizontalPadding = " ".repeat(SUMMARY_BOX_HORIZONTAL_PADDING_CHARS);
+	const maximumLineLength = Math.max(...framedLines.map((framedLine) => framedLine.plainText.length));
+	const borderLine = "─".repeat(maximumLineLength + SUMMARY_BOX_HORIZONTAL_PADDING_CHARS * 2);
+	const lines = [];
+	lines.push(`${outerIndent}${borderColorizer(`┌${borderLine}┐`)}`);
+	for (const framedLine of framedLines) {
+		const trailingSpaces = " ".repeat(maximumLineLength - framedLine.plainText.length);
+		lines.push(`${outerIndent}${borderColorizer("│")}${horizontalPadding}${framedLine.renderedText}${trailingSpaces}${horizontalPadding}${borderColorizer("│")}`);
+	}
+	lines.push(`${outerIndent}${borderColorizer(`└${borderLine}┘`)}`);
+	return lines.join("\n");
+};
+const printFramedBox = (framedLines) => {
+	const rendered = renderFramedBoxString(framedLines);
+	if (rendered) logger.log(rendered);
+};
+
+//#endregion
+//#region src/utils/group-by.ts
+const groupBy = (items, keyFn) => {
+	const groups = /* @__PURE__ */ new Map();
+	for (const item of items) {
+		const key = keyFn(item);
+		const existing = groups.get(key) ?? [];
+		existing.push(item);
+		groups.set(key, existing);
+	}
+	return groups;
+};
+
+//#endregion
+//#region src/utils/indent-multiline-text.ts
+const indentMultilineText = (text, linePrefix) => text.split("\n").map((lineText) => `${linePrefix}${lineText}`).join("\n");
+
+//#endregion
+//#region src/utils/load-config.ts
+const CONFIG_FILENAME = "react-doctor.config.json";
+const PACKAGE_JSON_CONFIG_KEY = "reactDoctor";
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const loadConfig = (rootDirectory) => {
+	const configFilePath = path.join(rootDirectory, CONFIG_FILENAME);
+	if (fs.existsSync(configFilePath)) try {
+		const fileContent = fs.readFileSync(configFilePath, "utf-8");
+		const parsed = JSON.parse(fileContent);
+		if (!isPlainObject(parsed)) {
+			console.warn(`Warning: ${CONFIG_FILENAME} must be a JSON object, ignoring.`);
+			return null;
+		}
+		return parsed;
+	} catch (error) {
+		console.warn(`Warning: Failed to parse ${CONFIG_FILENAME}: ${error instanceof Error ? error.message : String(error)}`);
+		return null;
+	}
+	const packageJsonPath = path.join(rootDirectory, "package.json");
+	if (fs.existsSync(packageJsonPath)) try {
+		const fileContent = fs.readFileSync(packageJsonPath, "utf-8");
+		const embeddedConfig = JSON.parse(fileContent)[PACKAGE_JSON_CONFIG_KEY];
+		if (isPlainObject(embeddedConfig)) return embeddedConfig;
+	} catch {
+		return null;
+	}
+	return null;
+};
+
 //#endregion
 //#region src/utils/run-knip.ts
 const KNIP_CATEGORY_MAP = {
@@ -1138,15 +1216,11 @@ const writeDiagnosticsDirectory = (diagnostics) => {
 	writeFileSync(join(outputDirectory, "diagnostics.json"), JSON.stringify(diagnostics, null, 2));
 	return outputDirectory;
 };
-const colorizeByScore = (text, score) => {
+const colorizeByScore$1 = (text, score) => {
 	if (score >= SCORE_GOOD_THRESHOLD) return highlighter.success(text);
 	if (score >= SCORE_OK_THRESHOLD) return highlighter.warn(text);
 	return highlighter.error(text);
 };
-const createFramedLine = (plainText, renderedText = plainText) => ({
-	plainText,
-	renderedText
-});
 const buildScoreBarSegments = (score) => {
 	const filledCount = Math.round(score / PERFECT_SCORE * SCORE_BAR_WIDTH_CHARS);
 	const emptyCount = SCORE_BAR_WIDTH_CHARS - filledCount;
@@ -1161,25 +1235,11 @@ const buildPlainScoreBar = (score) => {
 };
 const buildScoreBar = (score) => {
 	const { filledSegment, emptySegment } = buildScoreBarSegments(score);
-	return colorizeByScore(filledSegment, score) + highlighter.dim(emptySegment);
-};
-const printFramedBox = (framedLines) => {
-	if (framedLines.length === 0) return;
-	const borderColorizer = highlighter.dim;
-	const outerIndent = " ".repeat(SUMMARY_BOX_OUTER_INDENT_CHARS);
-	const horizontalPadding = " ".repeat(SUMMARY_BOX_HORIZONTAL_PADDING_CHARS);
-	const maximumLineLength = Math.max(...framedLines.map((framedLine) => framedLine.plainText.length));
-	const borderLine = "─".repeat(maximumLineLength + SUMMARY_BOX_HORIZONTAL_PADDING_CHARS * 2);
-	logger.log(`${outerIndent}${borderColorizer(`┌${borderLine}┐`)}`);
-	for (const framedLine of framedLines) {
-		const trailingSpaces = " ".repeat(maximumLineLength - framedLine.plainText.length);
-		logger.log(`${outerIndent}${borderColorizer("│")}${horizontalPadding}${framedLine.renderedText}${trailingSpaces}${horizontalPadding}${borderColorizer("│")}`);
-	}
-	logger.log(`${outerIndent}${borderColorizer(`└${borderLine}┘`)}`);
+	return colorizeByScore$1(filledSegment, score) + highlighter.dim(emptySegment);
 };
 const printScoreGauge = (score, label) => {
-	const scoreDisplay = colorizeByScore(`${score}`, score);
-	const labelDisplay = colorizeByScore(label, score);
+	const scoreDisplay = colorizeByScore$1(`${score}`, score);
+	const labelDisplay = colorizeByScore$1(label, score);
 	logger.log(`  ${scoreDisplay} / ${PERFECT_SCORE}  ${labelDisplay}`);
 	logger.break();
 	logger.log(`  ${buildScoreBar(score)}`);
@@ -1193,7 +1253,7 @@ const getDoctorFace = (score) => {
 const printBranding = (score) => {
 	if (score !== void 0) {
 		const [eyes, mouth] = getDoctorFace(score);
-		const colorize = (text) => colorizeByScore(text, score);
+		const colorize = (text) => colorizeByScore$1(text, score);
 		logger.log(colorize("  ┌─────┐"));
 		logger.log(colorize(`  │ ${eyes} │`));
 		logger.log(colorize(`  │ ${mouth} │`));
@@ -1240,7 +1300,7 @@ const printSummary = (diagnostics, elapsedMilliseconds, scoreResult, projectName
 	const summaryFramedLines = [];
 	if (scoreResult) {
 		const [eyes, mouth] = getDoctorFace(scoreResult.score);
-		const scoreColorizer = (text) => colorizeByScore(text, scoreResult.score);
+		const scoreColorizer = (text) => colorizeByScore$1(text, scoreResult.score);
 		summaryFramedLines.push(createFramedLine("┌─────┐", scoreColorizer("┌─────┐")));
 		summaryFramedLines.push(createFramedLine(`│ ${eyes} │`, scoreColorizer(`│ ${eyes} │`)));
 		summaryFramedLines.push(createFramedLine(`│ ${mouth} │`, scoreColorizer(`│ ${mouth} │`)));
@@ -1248,7 +1308,7 @@ const printSummary = (diagnostics, elapsedMilliseconds, scoreResult, projectName
 		summaryFramedLines.push(createFramedLine("React Doctor (www.react.doctor)", `React Doctor ${highlighter.dim("(www.react.doctor)")}`));
 		summaryFramedLines.push(createFramedLine(""));
 		const scoreLinePlainText = `${scoreResult.score} / ${PERFECT_SCORE}  ${scoreResult.label}`;
-		const scoreLineRenderedText = `${colorizeByScore(String(scoreResult.score), scoreResult.score)} / ${PERFECT_SCORE}  ${colorizeByScore(scoreResult.label, scoreResult.score)}`;
+		const scoreLineRenderedText = `${colorizeByScore$1(String(scoreResult.score), scoreResult.score)} / ${PERFECT_SCORE}  ${colorizeByScore$1(scoreResult.label, scoreResult.score)}`;
 		summaryFramedLines.push(createFramedLine(scoreLinePlainText, scoreLineRenderedText));
 		summaryFramedLines.push(createFramedLine(""));
 		summaryFramedLines.push(createFramedLine(buildPlainScoreBar(scoreResult.score), buildScoreBar(scoreResult.score)));
@@ -1343,7 +1403,10 @@ const scan = async (directory, inputOptions = {}) => {
 	if (options.scoreOnly) {
 		if (scoreResult) logger.log(`${scoreResult.score}`);
 		else logger.dim(noScoreMessage);
-		return;
+		return {
+			diagnostics,
+			scoreResult
+		};
 	}
 	if (diagnostics.length === 0) {
 		logger.success("No issues found!");
@@ -1352,11 +1415,18 @@ const scan = async (directory, inputOptions = {}) => {
 			printBranding(scoreResult.score);
 			printScoreGauge(scoreResult.score, scoreResult.label);
 		} else logger.dim(`  ${noScoreMessage}`);
-		return;
+		return {
+			diagnostics,
+			scoreResult
+		};
 	}
 	printDiagnostics(diagnostics, options.verbose);
 	const displayedSourceFileCount = isDiffMode ? includePaths.length : projectInfo.sourceFileCount;
 	printSummary(diagnostics, elapsedMilliseconds, scoreResult, projectInfo.projectName, displayedSourceFileCount, noScoreMessage);
+	return {
+		diagnostics,
+		scoreResult
+	};
 };
 
 //#endregion
@@ -1518,11 +1588,21 @@ const shouldSelectAllChoices = (choiceStates) => {
 //#region src/utils/prompts.ts
 const require = createRequire(import.meta.url);
 const PROMPTS_MULTISELECT_MODULE_PATH = "prompts/lib/elements/multiselect";
+const PROMPTS_SELECT_MODULE_PATH = "prompts/lib/elements/select";
 let didPatchMultiselectToggleAll = false;
 let didPatchMultiselectSubmit = false;
+let didPatchSelectBanner = false;
+const selectBannerMap = /* @__PURE__ */ new Map();
+const setSelectBanner = (banner, targetIndex) => {
+	selectBannerMap.set(targetIndex, banner);
+};
+const clearSelectBanner = () => {
+	selectBannerMap.clear();
+};
 const onCancel = () => {
 	logger.break();
 	logger.log("Cancelled.");
+	logger.dim("Run `npx react-doctor@latest --fix` to fix issues.");
 	logger.break();
 	process.exit(0);
 };
@@ -1554,9 +1634,25 @@ const patchMultiselectSubmit = () => {
 		originalSubmit.call(this);
 	};
 };
+const patchSelectBanner = () => {
+	if (didPatchSelectBanner) return;
+	didPatchSelectBanner = true;
+	const selectConstructor = require(PROMPTS_SELECT_MODULE_PATH);
+	const promptsClear = require("prompts/lib/util/clear");
+	const originalRender = selectConstructor.prototype.render;
+	selectConstructor.prototype.render = function() {
+		originalRender.call(this);
+		const banner = selectBannerMap.get(this.cursor);
+		if (!banner || this.closed || this.done) return;
+		this.out.write(promptsClear(this.outputText, this.out.columns));
+		this.outputText = `${banner}\n\n${this.outputText}`;
+		this.out.write(this.outputText);
+	};
+};
 const prompts = (questions) => {
 	patchMultiselectToggleAll();
 	patchMultiselectSubmit();
+	patchSelectBanner();
 	return basePrompts(questions, { onCancel });
 };
 
@@ -1648,7 +1744,7 @@ const maybePromptSkillInstall = async (shouldSkipPrompts) => {
 	const { shouldInstall } = await prompts({
 		type: "confirm",
 		name: "shouldInstall",
-		message: "Install skill?",
+		message: "Install skill? (recommended)",
 		initial: true
 	});
 	if (shouldInstall) {
@@ -1663,9 +1759,16 @@ const maybePromptSkillInstall = async (shouldSkipPrompts) => {
 
 //#endregion
 //#region src/cli.ts
-const VERSION = "0.0.21";
-process.on("SIGINT", () => process.exit(0));
-process.on("SIGTERM", () => process.exit(0));
+const VERSION = "0.0.23";
+const exitWithFixHint = () => {
+	logger.break();
+	logger.log("Cancelled.");
+	logger.dim("Run `npx react-doctor@latest --fix` to fix issues.");
+	logger.break();
+	process.exit(0);
+};
+process.on("SIGINT", exitWithFixHint);
+process.on("SIGTERM", exitWithFixHint);
 const resolveDiffMode = async (diffInfo, effectiveDiff, shouldSkipPrompts, isScoreOnly) => {
 	if (effectiveDiff !== void 0 && effectiveDiff !== false) {
 		if (diffInfo) return true;
@@ -1688,10 +1791,10 @@ const resolveDiffMode = async (diffInfo, effectiveDiff, shouldSkipPrompts, isSco
 	});
 	return Boolean(shouldScanBranchOnly);
 };
-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("--no-lint", "skip linting").option("--no-dead-code", "skip dead code detection").option("--verbose", "show file details per rule").option("--score", "output only the score").option("-y, --yes", "skip prompts, scan all workspace projects").option("--project <name>", "select workspace project (comma-separated for multiple)").option("--diff [base]", "scan only files changed vs base branch").option("--offline", "skip telemetry (anonymous, not stored, only used to calculate score)").option("--fix", "open Ami to auto-fix all issues").option("--prompt", "copy latest scan output to clipboard").action(async (directory, flags) => {
+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("--no-lint", "skip linting").option("--no-dead-code", "skip dead code detection").option("--verbose", "show file details per rule").option("--score", "output only the score").option("-y, --yes", "skip prompts, scan all workspace projects").option("--project <name>", "select workspace project (comma-separated for multiple)").option("--diff [base]", "scan only files changed vs base branch").option("--offline", "skip telemetry (anonymous, not stored, only used to calculate score)").option("--no-ami", "skip Ami-related prompts").option("--fix", "open Ami to auto-fix all issues").option("--prompt", "copy latest scan output to clipboard").action(async (directory, flags) => {
 	const isScoreOnly = flags.score && !flags.prompt;
 	const shouldCopyPromptOutput = flags.prompt;
-	if (shouldCopyPromptOutput) startLoggerCapture();
+	startLoggerCapture();
 	try {
 		const resolvedDirectory = path.resolve(directory);
 		const userConfig = loadConfig(resolvedDirectory);
@@ -1717,6 +1820,7 @@ const program = new Command().name("react-doctor").description("Diagnose React c
 			process.env.AMI
 		].some(Boolean);
 		const shouldSkipPrompts = flags.yes || isAutomatedEnvironment || !process.stdin.isTTY;
+		const shouldSkipAmiPrompts = shouldSkipPrompts || !flags.ami;
 		const projectDirectories = await selectProjects(resolvedDirectory, flags.project, shouldSkipPrompts);
 		const effectiveDiff = isCliOverride("diff") ? flags.diff : userConfig?.diff;
 		const explicitBaseBranch = typeof effectiveDiff === "string" ? effectiveDiff : void 0;
@@ -1726,6 +1830,7 @@ const program = new Command().name("react-doctor").description("Diagnose React c
 			logger.log(`Scanning changes: ${highlighter.info(diffInfo.currentBranch)} → ${highlighter.info(diffInfo.baseBranch)}`);
 			logger.break();
 		}
+		const allDiagnostics = [];
 		for (const projectDirectory of projectDirectories) {
 			let includePaths;
 			if (isDiffMode) {
@@ -1746,28 +1851,38 @@ const program = new Command().name("react-doctor").description("Diagnose React c
 				logger.dim(`Scanning ${projectDirectory}...`);
 				logger.break();
 			}
-			await scan(projectDirectory, {
+			const scanResult = await scan(projectDirectory, {
 				...scanOptions,
 				includePaths
 			});
+			allDiagnostics.push(...scanResult.diagnostics);
 			if (!isScoreOnly) logger.break();
 		}
+		const capturedScanOutput = stopLoggerCapture();
 		if (flags.fix) openAmiToFix(resolvedDirectory);
-		if (!isScoreOnly && !flags.prompt) {
-			await maybePromptSkillInstall(shouldSkipPrompts);
-			if (!shouldSkipPrompts && !flags.fix) await maybePromptAmiFix(resolvedDirectory);
+		if (shouldCopyPromptOutput) copyPromptToClipboard(capturedScanOutput, !isScoreOnly);
+		else if (!isScoreOnly) {
+			await maybePromptSkillInstall(shouldSkipAmiPrompts);
+			if (!shouldSkipAmiPrompts && !flags.fix) await maybePromptFix(resolvedDirectory, allDiagnostics, flags.offline ? null : await fetchEstimatedScore(allDiagnostics), capturedScanOutput);
 		}
 	} catch (error) {
 		handleError(error, { shouldExit: !shouldCopyPromptOutput });
 	} finally {
-		if (shouldCopyPromptOutput) copyPromptToClipboard(stopLoggerCapture(), !isScoreOnly);
+		const remainingOutput = stopLoggerCapture();
+		if (shouldCopyPromptOutput && remainingOutput) copyPromptToClipboard(remainingOutput, !isScoreOnly);
 	}
 }).addHelpText("after", `
 ${highlighter.dim("Learn more:")}
   ${highlighter.info("https://github.com/millionco/react-doctor")}
 `);
-const AMI_INSTALL_URL = "https://ami.dev/install.sh";
+const AMI_WEBSITE_URL = "https://ami.dev";
+const AMI_INSTALL_URL = `${AMI_WEBSITE_URL}/install.sh`;
 const AMI_RELEASES_URL = "https://github.com/millionco/ami-releases/releases";
+const colorizeByScore = (text, score) => {
+	if (score >= SCORE_GOOD_THRESHOLD) return highlighter.success(text);
+	if (score >= SCORE_OK_THRESHOLD) return highlighter.warn(text);
+	return highlighter.error(text);
+};
 const DEEPLINK_FIX_PROMPT = "Run `npx -y react-doctor@latest .` to diagnose issues, then fix all reported issues one by one. After applying fixes, run it again to verify the results improved.";
 const CLIPBOARD_FIX_PROMPT = "Fix all issues reported in the react-doctor diagnostics below, one by one. After applying fixes, run `npx -y react-doctor@latest .` again to verify the results improved.";
 const REACT_DOCTOR_OUTPUT_LABEL = "react-doctor output";
@@ -1786,12 +1901,12 @@ const isAmiInstalled = () => {
 	}
 };
 const installAmi = () => {
-	logger.log("Ami not found. Installing...");
+	logger.log("Installing Ami...");
 	logger.break();
 	try {
 		execSync(`curl -fsSL ${AMI_INSTALL_URL} | bash`, { stdio: "inherit" });
 	} catch {
-		logger.error("Failed to install Ami. Visit https://ami.dev to install manually.");
+		logger.error(`Failed to install Ami. Visit ${AMI_WEBSITE_URL} to install manually.`);
 		process.exit(1);
 	}
 	logger.break();
@@ -1820,23 +1935,23 @@ const openAmiToFix = (directory) => {
 	if (!isInstalled) {
 		if (process.platform === "darwin") {
 			installAmi();
-			logger.success("Ami was installed and opened.");
+			logger.success("Ami installed successfully.");
 		} else {
 			logger.error("Ami is not installed.");
-			logger.dim(`Download it at ${highlighter.info(AMI_RELEASES_URL)}`);
+			logger.dim(`Download at ${highlighter.info(AMI_RELEASES_URL)}`);
 		}
 		logger.break();
-		logger.dim("Once Ami is running, open this link to start fixing:");
+		logger.dim("Open this link to start fixing:");
 		logger.info(webDeeplink);
 		return;
 	}
-	logger.log("Opening Ami to fix react-doctor issues...");
+	logger.log("Opening Ami...");
 	try {
 		openUrl(deeplink);
-		logger.success("Opened Ami with react-doctor fix prompt.");
+		logger.success("Ami opened. Fixing your issues now.");
 	} catch {
 		logger.break();
-		logger.dim("Could not open Ami automatically. Open this URL manually:");
+		logger.dim("Could not open Ami automatically. Open this link instead:");
 		logger.info(webDeeplink);
 	}
 };
@@ -1856,24 +1971,78 @@ const copyPromptToClipboard = (reactDoctorOutput, shouldLogResult) => {
 	logger.warn("Could not copy prompt to clipboard automatically. Use this prompt:");
 	logger.info(promptWithOutput);
 };
-const maybePromptAmiFix = async (directory) => {
-	const isInstalled = isAmiInstalled();
-	logger.break();
-	logger.log(`Fix these issues with ${highlighter.info("Ami")}?`);
-	logger.dim("   Ami is a coding agent built to understand your codebase and fix issues");
-	logger.dim(`   automatically. Learn more at ${highlighter.info("https://ami.dev")}`);
+const FIX_METHOD_AMI = "ami";
+const FIX_METHOD_CLIPBOARD = "clipboard";
+const FIX_COMMAND_HINT = "npx react-doctor@latest --fix";
+const buildAmiBanner = (issueCount, currentScore, estimatedScore) => {
+	const currentScoreDisplay = colorizeByScore(String(currentScore), currentScore);
+	const estimatedScoreDisplay = colorizeByScore(`~${estimatedScore}`, estimatedScore);
+	const issueLabel = issueCount === 1 ? "issue" : "issues";
+	return renderFramedBoxString([
+		createFramedLine(`Score: ${currentScore} → ~${estimatedScore}`, `Score: ${currentScoreDisplay} ${highlighter.dim("→")} ${estimatedScoreDisplay}`),
+		createFramedLine(""),
+		createFramedLine(`Ami is a coding agent built for React. It reads`, `${highlighter.info("Ami")} is a coding agent built for React. It reads`),
+		createFramedLine("your react-doctor report, understands your codebase,"),
+		createFramedLine(`and fixes ${issueCount} ${issueLabel} one by one — then re-runs the`, `and fixes ${highlighter.warn(String(issueCount))} ${issueLabel} one by one — then re-runs the`),
+		createFramedLine("scan to verify the score improved."),
+		createFramedLine(""),
+		createFramedLine(`Free to use. ${AMI_WEBSITE_URL}`, `Free to use. ${highlighter.info(AMI_WEBSITE_URL)}`)
+	]);
+};
+const buildClipboardWarningBanner = () => renderFramedBoxString([
+	createFramedLine("⚠ Other agents may not fix these issues well.", `${highlighter.warn("⚠")} Other agents may not fix these issues well.`),
+	createFramedLine(""),
+	createFramedLine("react-doctor diagnostics require React-specific context"),
+	createFramedLine("that general-purpose agents often miss, leading to"),
+	createFramedLine("incomplete or incorrect fixes.")
+]);
+const buildSkipBanner = (issueCount, estimatedScore) => {
+	const issueLabel = issueCount === 1 ? "issue" : "issues";
+	const estimatedScoreDisplay = colorizeByScore(`~${estimatedScore}`, estimatedScore);
+	return renderFramedBoxString([
+		createFramedLine(`Skip fixing ${issueCount} ${issueLabel} and reaching ~${estimatedScore}?`, `Skip fixing ${highlighter.warn(String(issueCount))} ${issueLabel} and reaching ${estimatedScoreDisplay}?`),
+		createFramedLine(""),
+		createFramedLine(`Run ${FIX_COMMAND_HINT} anytime to come back.`, `Run ${highlighter.info(FIX_COMMAND_HINT)} anytime to come back.`)
+	]);
+};
+const configureFixBanners = (issueCount, estimatedScoreResult) => {
+	const { currentScore, estimatedScore } = estimatedScoreResult;
+	setSelectBanner(buildAmiBanner(issueCount, currentScore, estimatedScore), 0);
+	setSelectBanner(buildClipboardWarningBanner(), 1);
+	setSelectBanner(buildSkipBanner(issueCount, estimatedScore), 2);
+};
+const maybePromptFix = async (directory, diagnostics, estimatedScoreResult, capturedScanOutput) => {
+	if (diagnostics.length === 0) return;
 	logger.break();
-	if (!isInstalled && process.platform !== "darwin") {
-		logger.dim(`Download Ami at ${highlighter.info(AMI_RELEASES_URL)}`);
-		return;
-	}
-	const { shouldFix } = await prompts({
-		type: "confirm",
-		name: "shouldFix",
-		message: isInstalled ? "Open Ami to fix?" : "Install Ami to fix?",
-		initial: true
+	if (estimatedScoreResult) configureFixBanners(diagnostics.length, estimatedScoreResult);
+	const { fixMethod } = await prompts({
+		type: "select",
+		name: "fixMethod",
+		message: "Fix issues?",
+		choices: [
+			{
+				title: "Use ami.dev (recommended)",
+				description: "Optimized coding agent for React Doctor",
+				value: FIX_METHOD_AMI
+			},
+			{
+				title: "Copy to clipboard",
+				description: "Other agents may lack context for react-doctor fixes",
+				value: FIX_METHOD_CLIPBOARD
+			},
+			{
+				title: "Skip",
+				value: "skip"
+			}
+		]
 	});
-	if (shouldFix) openAmiToFix(directory);
+	clearSelectBanner();
+	if (fixMethod === FIX_METHOD_AMI) openAmiToFix(directory);
+	else if (fixMethod === FIX_METHOD_CLIPBOARD) copyPromptToClipboard(capturedScanOutput, true);
+	else {
+		logger.break();
+		logger.dim(`  Run ${highlighter.info(FIX_COMMAND_HINT)} anytime to fix issues.`);
+	}
 };
 const fixAction = (directory) => {
 	try {