react-doctor 0.0.18 → 0.0.20

package/dist/cli.js

@@ -5,9 +5,9 @@ import fs, { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import os, { homedir, tmpdir } from "node:os";
 import path, { join } from "node:path";
 import { Command } from "commander";
-import pc from "picocolors";
 import { randomUUID } from "node:crypto";
 import { performance } from "node:perf_hooks";
+import pc from "picocolors";
 import { main } from "knip";
 import { createOptions } from "knip/session";
 import { fileURLToPath } from "node:url";
@@ -30,84 +30,7 @@ const SCORE_API_URL = "https://www.react.doctor/api/score";
 const SHARE_BASE_URL = "https://www.react.doctor/share";
 const GIT_LS_FILES_MAX_BUFFER_BYTES = 50 * 1024 * 1024;
 const OFFLINE_MESSAGE = "You are offline, could not calculate score. Reconnect to calculate.";
-
-//#endregion
-//#region src/utils/highlighter.ts
-const highlighter = {
-	error: pc.red,
-	warn: pc.yellow,
-	info: pc.cyan,
-	success: pc.green,
-	dim: pc.dim
-};
-
-//#endregion
-//#region src/utils/strip-ansi.ts
-const ANSI_ESCAPE_SEQUENCE = String.raw`\u001B\[[0-9;]*m`;
-const ANSI_ESCAPE_PATTERN = new RegExp(ANSI_ESCAPE_SEQUENCE, "g");
-const stripAnsi = (text) => text.replace(ANSI_ESCAPE_PATTERN, "");
-
-//#endregion
-//#region src/utils/logger.ts
-const loggerCaptureState = {
-	isEnabled: false,
-	lines: []
-};
-const captureLogLine = (text) => {
-	if (!loggerCaptureState.isEnabled) return;
-	loggerCaptureState.lines.push(stripAnsi(text));
-};
-const writeLogLine = (text) => {
-	console.log(text);
-	captureLogLine(text);
-};
-const startLoggerCapture = () => {
-	loggerCaptureState.isEnabled = true;
-	loggerCaptureState.lines = [];
-};
-const stopLoggerCapture = () => {
-	const capturedOutput = loggerCaptureState.lines.join("\n");
-	loggerCaptureState.isEnabled = false;
-	loggerCaptureState.lines = [];
-	return capturedOutput;
-};
-const logger = {
-	error(...args) {
-		writeLogLine(highlighter.error(args.join(" ")));
-	},
-	warn(...args) {
-		writeLogLine(highlighter.warn(args.join(" ")));
-	},
-	info(...args) {
-		writeLogLine(highlighter.info(args.join(" ")));
-	},
-	success(...args) {
-		writeLogLine(highlighter.success(args.join(" ")));
-	},
-	dim(...args) {
-		writeLogLine(highlighter.dim(args.join(" ")));
-	},
-	log(...args) {
-		writeLogLine(args.join(" "));
-	},
-	break() {
-		writeLogLine("");
-	}
-};
-
-//#endregion
-//#region src/utils/handle-error.ts
-const DEFAULT_HANDLE_ERROR_OPTIONS = { shouldExit: true };
-const handleError = (error, options = DEFAULT_HANDLE_ERROR_OPTIONS) => {
-	logger.break();
-	logger.error("Something went wrong. Please check the error below for more details.");
-	logger.error("If the problem persists, please open an issue on GitHub.");
-	logger.error("");
-	if (error instanceof Error) logger.error(error.message);
-	logger.break();
-	if (options.shouldExit) process.exit(1);
-	process.exitCode = 1;
-};
+const DEFAULT_BRANCH_CANDIDATES = ["main", "master"];
 
 //#endregion
 //#region src/utils/calculate-score.ts
@@ -130,10 +53,56 @@ const calculateScore = async (diagnostics) => {
 	}
 };
 
+//#endregion
+//#region src/plugin/constants.ts
+const MOTION_LIBRARY_PACKAGES = new Set(["framer-motion", "motion"]);
+
 //#endregion
 //#region src/utils/read-package-json.ts
 const readPackageJson = (packageJsonPath) => JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
 
+//#endregion
+//#region src/utils/check-reduced-motion.ts
+const REDUCED_MOTION_GREP_PATTERN = "prefers-reduced-motion|useReducedMotion";
+const REDUCED_MOTION_FILE_GLOBS = "\"*.ts\" \"*.tsx\" \"*.js\" \"*.jsx\" \"*.css\" \"*.scss\"";
+const MISSING_REDUCED_MOTION_DIAGNOSTIC = {
+	filePath: "package.json",
+	plugin: "react-doctor",
+	rule: "require-reduced-motion",
+	severity: "error",
+	message: "Project uses a motion library but has no prefers-reduced-motion handling — required for accessibility (WCAG 2.3.3)",
+	help: "Add `useReducedMotion()` from your animation library, or a `@media (prefers-reduced-motion: reduce)` CSS query",
+	line: 0,
+	column: 0,
+	category: "Accessibility",
+	weight: 2
+};
+const checkReducedMotion = (rootDirectory) => {
+	const packageJsonPath = path.join(rootDirectory, "package.json");
+	if (!fs.existsSync(packageJsonPath)) return [];
+	let hasMotionLibrary = false;
+	try {
+		const packageJson = readPackageJson(packageJsonPath);
+		const allDependencies = {
+			...packageJson.dependencies,
+			...packageJson.devDependencies
+		};
+		hasMotionLibrary = Object.keys(allDependencies).some((packageName) => MOTION_LIBRARY_PACKAGES.has(packageName));
+	} catch {
+		return [];
+	}
+	if (!hasMotionLibrary) return [];
+	try {
+		execSync(`git grep -ql -E "${REDUCED_MOTION_GREP_PATTERN}" -- ${REDUCED_MOTION_FILE_GLOBS}`, {
+			cwd: rootDirectory,
+			stdio: "pipe"
+		});
+		return [];
+	} catch {
+		return [MISSING_REDUCED_MOTION_DIAGNOSTIC];
+	}
+};
+
 //#endregion
 //#region src/utils/discover-project.ts
 const REACT_COMPILER_PACKAGES = new Set([
@@ -193,6 +162,7 @@ const countSourceFiles = (rootDirectory) => {
 	return result.stdout.split("\n").filter((filePath) => filePath.length > 0 && SOURCE_FILE_PATTERN.test(filePath)).length;
 };
 const collectAllDependencies = (packageJson) => ({
+	...packageJson.peerDependencies,
 	...packageJson.dependencies,
 	...packageJson.devDependencies
 });
@@ -386,6 +356,49 @@ const discoverProject = (directory) => {
 	};
 };
 
+//#endregion
+//#region src/utils/match-glob-pattern.ts
+const REGEX_SPECIAL_CHARACTERS = /[.+^${}()|[\]\\]/g;
+const compileGlobPattern = (pattern) => {
+	const normalizedPattern = pattern.replace(/\\/g, "/");
+	let regexSource = "^";
+	let characterIndex = 0;
+	while (characterIndex < normalizedPattern.length) if (normalizedPattern[characterIndex] === "*" && normalizedPattern[characterIndex + 1] === "*") if (normalizedPattern[characterIndex + 2] === "/") {
+		regexSource += "(?:.+/)?";
+		characterIndex += 3;
+	} else {
+		regexSource += ".*";
+		characterIndex += 2;
+	}
+	else if (normalizedPattern[characterIndex] === "*") {
+		regexSource += "[^/]*";
+		characterIndex++;
+	} else if (normalizedPattern[characterIndex] === "?") {
+		regexSource += "[^/]";
+		characterIndex++;
+	} else {
+		regexSource += normalizedPattern[characterIndex].replace(REGEX_SPECIAL_CHARACTERS, "\\$&");
+		characterIndex++;
+	}
+	regexSource += "$";
+	return new RegExp(regexSource);
+};
+
+//#endregion
+//#region src/utils/filter-diagnostics.ts
+const filterIgnoredDiagnostics = (diagnostics, config) => {
+	const ignoredRules = new Set(Array.isArray(config.ignore?.rules) ? config.ignore.rules : []);
+	const ignoredFilePatterns = Array.isArray(config.ignore?.files) ? config.ignore.files.map(compileGlobPattern) : [];
+	if (ignoredRules.size === 0 && ignoredFilePatterns.length === 0) return diagnostics;
+	return diagnostics.filter((diagnostic) => {
+		const ruleIdentifier = `${diagnostic.plugin}/${diagnostic.rule}`;
+		if (ignoredRules.has(ruleIdentifier)) return false;
+		const normalizedPath = diagnostic.filePath.replace(/\\/g, "/");
+		if (ignoredFilePatterns.some((pattern) => pattern.test(normalizedPath))) return false;
+		return true;
+	});
+};
+
 //#endregion
 //#region src/utils/group-by.ts
 const groupBy = (items, keyFn) => {
@@ -400,48 +413,100 @@ const groupBy = (items, keyFn) => {
 };
 
 //#endregion
-//#region src/plugin/constants.ts
-const MOTION_LIBRARY_PACKAGES = new Set(["framer-motion", "motion"]);
+//#region src/utils/highlighter.ts
+const highlighter = {
+	error: pc.red,
+	warn: pc.yellow,
+	info: pc.cyan,
+	success: pc.green,
+	dim: pc.dim
+};
 
 //#endregion
-//#region src/utils/check-reduced-motion.ts
-const REDUCED_MOTION_GREP_PATTERN = "prefers-reduced-motion|useReducedMotion";
-const REDUCED_MOTION_FILE_GLOBS = "\"*.ts\" \"*.tsx\" \"*.js\" \"*.jsx\" \"*.css\" \"*.scss\"";
-const MISSING_REDUCED_MOTION_DIAGNOSTIC = {
-	filePath: "package.json",
-	plugin: "react-doctor",
-	rule: "require-reduced-motion",
-	severity: "error",
-	message: "Project uses a motion library but has no prefers-reduced-motion handling — required for accessibility (WCAG 2.3.3)",
-	help: "Add `useReducedMotion()` from your animation library, or a `@media (prefers-reduced-motion: reduce)` CSS query",
-	line: 0,
-	column: 0,
-	category: "Accessibility",
-	weight: 2
-};
-const checkReducedMotion = (rootDirectory) => {
+//#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)) return [];
-	let hasMotionLibrary = false;
-	try {
-		const packageJson = readPackageJson(packageJsonPath);
-		const allDependencies = {
-			...packageJson.dependencies,
-			...packageJson.devDependencies
-		};
-		hasMotionLibrary = Object.keys(allDependencies).some((packageName) => MOTION_LIBRARY_PACKAGES.has(packageName));
+	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 [];
+		return null;
 	}
-	if (!hasMotionLibrary) return [];
-	try {
-		execSync(`git grep -ql -E "${REDUCED_MOTION_GREP_PATTERN}" -- ${REDUCED_MOTION_FILE_GLOBS}`, {
-			cwd: rootDirectory,
-			stdio: "pipe"
-		});
-		return [];
-	} catch {
-		return [MISSING_REDUCED_MOTION_DIAGNOSTIC];
+	return null;
+};
+
+//#endregion
+//#region src/utils/strip-ansi.ts
+const ANSI_ESCAPE_SEQUENCE = String.raw`\u001B\[[0-9;]*m`;
+const ANSI_ESCAPE_PATTERN = new RegExp(ANSI_ESCAPE_SEQUENCE, "g");
+const stripAnsi = (text) => text.replace(ANSI_ESCAPE_PATTERN, "");
+
+//#endregion
+//#region src/utils/logger.ts
+const loggerCaptureState = {
+	isEnabled: false,
+	lines: []
+};
+const captureLogLine = (text) => {
+	if (!loggerCaptureState.isEnabled) return;
+	loggerCaptureState.lines.push(stripAnsi(text));
+};
+const writeLogLine = (text) => {
+	console.log(text);
+	captureLogLine(text);
+};
+const startLoggerCapture = () => {
+	loggerCaptureState.isEnabled = true;
+	loggerCaptureState.lines = [];
+};
+const stopLoggerCapture = () => {
+	const capturedOutput = loggerCaptureState.lines.join("\n");
+	loggerCaptureState.isEnabled = false;
+	loggerCaptureState.lines = [];
+	return capturedOutput;
+};
+const logger = {
+	error(...args) {
+		writeLogLine(highlighter.error(args.join(" ")));
+	},
+	warn(...args) {
+		writeLogLine(highlighter.warn(args.join(" ")));
+	},
+	info(...args) {
+		writeLogLine(highlighter.info(args.join(" ")));
+	},
+	success(...args) {
+		writeLogLine(highlighter.success(args.join(" ")));
+	},
+	dim(...args) {
+		writeLogLine(highlighter.dim(args.join(" ")));
+	},
+	log(...args) {
+		writeLogLine(args.join(" "));
+	},
+	break() {
+		writeLogLine("");
 	}
 };
 
@@ -700,6 +765,46 @@ const createOxlintConfig = ({ pluginPath, framework, hasReactCompiler }) => ({
 	}
 });
 
+//#endregion
+//#region src/utils/neutralize-disable-directives.ts
+const findFilesWithDisableDirectives = (rootDirectory) => {
+	const result = spawnSync("git", [
+		"grep",
+		"-l",
+		"--untracked",
+		"-E",
+		"(eslint|oxlint)-disable"
+	], {
+		cwd: rootDirectory,
+		encoding: "utf-8",
+		maxBuffer: GIT_LS_FILES_MAX_BUFFER_BYTES
+	});
+	if (result.error || result.status === null) return [];
+	return result.stdout.split("\n").filter((filePath) => filePath.length > 0 && SOURCE_FILE_PATTERN.test(filePath));
+};
+const neutralizeContent = (content) => content.replaceAll("eslint-disable", "eslint_disable").replaceAll("oxlint-disable", "oxlint_disable");
+const neutralizeDisableDirectives = (rootDirectory) => {
+	const filePaths = findFilesWithDisableDirectives(rootDirectory);
+	const originalContents = /* @__PURE__ */ new Map();
+	for (const relativePath of filePaths) {
+		const absolutePath = path.join(rootDirectory, relativePath);
+		let originalContent;
+		try {
+			originalContent = fs.readFileSync(absolutePath, "utf-8");
+		} catch {
+			continue;
+		}
+		const neutralizedContent = neutralizeContent(originalContent);
+		if (neutralizedContent !== originalContent) {
+			originalContents.set(absolutePath, originalContent);
+			fs.writeFileSync(absolutePath, neutralizedContent);
+		}
+	}
+	return () => {
+		for (const [absolutePath, originalContent] of originalContents) fs.writeFileSync(absolutePath, originalContent);
+	};
+};
+
 //#endregion
 //#region src/utils/run-oxlint.ts
 const esmRequire = createRequire(import.meta.url);
@@ -767,7 +872,7 @@ const RULE_CATEGORY_MAP = {
 	"react-doctor/async-parallel": "Performance"
 };
 const RULE_HELP_MAP = {
-	"no-derived-state-effect": "Compute during render: `const derived = computeFrom(dep1, dep2)` — no useEffect needed",
+	"no-derived-state-effect": "For derived state, compute inline: `const x = fn(dep)`. For state resets on prop change, use a key prop: `<Component key={prop} />`",
 	"no-fetch-in-effect": "Use `useQuery()` from @tanstack/react-query, `useSWR()`, or fetch in a Server Component instead",
 	"no-cascading-set-state": "Combine into useReducer: `const [state, dispatch] = useReducer(reducer, initialState)`",
 	"no-effect-event-handler": "Move the conditional logic into onClick, onChange, or onSubmit handlers directly",
@@ -861,13 +966,15 @@ const resolvePluginPath = () => {
 const resolveDiagnosticCategory = (plugin, rule) => {
 	return RULE_CATEGORY_MAP[`${plugin}/${rule}`] ?? PLUGIN_CATEGORY_MAP[plugin] ?? "Other";
 };
-const runOxlint = async (rootDirectory, hasTypeScript, framework, hasReactCompiler) => {
+const runOxlint = async (rootDirectory, hasTypeScript, framework, hasReactCompiler, includePaths) => {
+	if (includePaths !== void 0 && includePaths.length === 0) return [];
 	const configPath = path.join(os.tmpdir(), `react-doctor-oxlintrc-${process.pid}.json`);
 	const config = createOxlintConfig({
 		pluginPath: resolvePluginPath(),
 		framework,
 		hasReactCompiler
 	});
+	const restoreDisableDirectives = neutralizeDisableDirectives(rootDirectory);
 	try {
 		fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
 		const args = [
@@ -878,7 +985,8 @@ const runOxlint = async (rootDirectory, hasTypeScript, framework, hasReactCompil
 			"json"
 		];
 		if (hasTypeScript) args.push("--tsconfig", "./tsconfig.json");
-		args.push(".");
+		if (includePaths !== void 0) args.push(...includePaths);
+		else args.push(".");
 		const stdout = await new Promise((resolve, reject) => {
 			const child = spawn(process.execPath, args, { cwd: rootDirectory });
 			const stdoutBuffers = [];
@@ -905,7 +1013,7 @@ const runOxlint = async (rootDirectory, hasTypeScript, framework, hasReactCompil
 		} catch {
 			throw new Error(`Failed to parse oxlint output: ${stdout.slice(0, ERROR_PREVIEW_LENGTH_CHARS)}`);
 		}
-		return output.diagnostics.filter((diagnostic) => JSX_FILE_PATTERN.test(diagnostic.filename)).map((diagnostic) => {
+		return output.diagnostics.filter((diagnostic) => diagnostic.code && JSX_FILE_PATTERN.test(diagnostic.filename)).map((diagnostic) => {
 			const { plugin, rule } = parseRuleCode(diagnostic.code);
 			const primaryLabel = diagnostic.labels[0];
 			const cleaned = cleanDiagnosticMessage(diagnostic.message, diagnostic.help, plugin, rule);
@@ -922,6 +1030,7 @@ const runOxlint = async (rootDirectory, hasTypeScript, framework, hasReactCompil
 			};
 		});
 	} finally {
+		restoreDisableDirectives();
 		if (fs.existsSync(configPath)) fs.unlinkSync(configPath);
 	}
 };
@@ -957,10 +1066,6 @@ const spinner = (text) => ({ start() {
 	};
 } });
 
-//#endregion
-//#region src/utils/indent-multiline-text.ts
-const indentMultilineText = (text, linePrefix) => text.split("\n").map((lineText) => `${linePrefix}${lineText}`).join("\n");
-
 //#endregion
 //#region src/scan.ts
 const SEVERITY_ORDER = {
@@ -1165,9 +1270,19 @@ const printSummary = (diagnostics, elapsedMilliseconds, scoreResult, projectName
 	logger.break();
 	logger.dim(`  Share your results: ${highlighter.info(shareUrl)}`);
 };
-const scan = async (directory, options) => {
+const scan = async (directory, inputOptions = {}) => {
 	const startTime = performance.now();
 	const projectInfo = discoverProject(directory);
+	const userConfig = loadConfig(directory);
+	const options = {
+		lint: inputOptions.lint ?? userConfig?.lint ?? true,
+		deadCode: inputOptions.deadCode ?? userConfig?.deadCode ?? true,
+		verbose: inputOptions.verbose ?? userConfig?.verbose ?? false,
+		scoreOnly: inputOptions.scoreOnly ?? false,
+		includePaths: inputOptions.includePaths
+	};
+	const includePaths = options.includePaths ?? [];
+	const isDiffMode = includePaths.length > 0;
 	if (!projectInfo.reactVersion) throw new Error("No React dependency found in package.json");
 	if (!options.scoreOnly) {
 		const frameworkLabel = formatFrameworkName(projectInfo.framework);
@@ -1179,22 +1294,28 @@ const scan = async (directory, options) => {
 		completeStep(`Detecting React version. Found ${highlighter.info(`React ${projectInfo.reactVersion}`)}.`);
 		completeStep(`Detecting language. Found ${highlighter.info(languageLabel)}.`);
 		completeStep(`Detecting React Compiler. ${projectInfo.hasReactCompiler ? highlighter.info("Found React Compiler.") : "Not found."}`);
-		completeStep(`Found ${highlighter.info(`${projectInfo.sourceFileCount}`)} source files.`);
+		if (isDiffMode) completeStep(`Scanning ${highlighter.info(`${includePaths.length}`)} changed source files.`);
+		else completeStep(`Found ${highlighter.info(`${projectInfo.sourceFileCount}`)} source files.`);
+		if (userConfig) completeStep(`Loaded ${highlighter.info("react-doctor config")}.`);
 		logger.break();
 	}
+	const jsxIncludePaths = isDiffMode ? includePaths.filter((filePath) => JSX_FILE_PATTERN.test(filePath)) : void 0;
 	const lintPromise = options.lint ? (async () => {
 		const lintSpinner = options.scoreOnly ? null : spinner("Running lint checks...").start();
 		try {
-			const lintDiagnostics = await runOxlint(directory, projectInfo.hasTypeScript, projectInfo.framework, projectInfo.hasReactCompiler);
+			const lintDiagnostics = await runOxlint(directory, projectInfo.hasTypeScript, projectInfo.framework, projectInfo.hasReactCompiler, jsxIncludePaths);
 			lintSpinner?.succeed("Running lint checks.");
 			return lintDiagnostics;
 		} catch (error) {
 			lintSpinner?.fail("Lint checks failed (non-fatal, skipping).");
-			logger.error(String(error));
+			if (error instanceof Error) {
+				logger.error(error.message);
+				if (error.stack) logger.dim(error.stack);
+			} else logger.error(String(error));
 			return [];
 		}
 	})() : Promise.resolve([]);
-	const deadCodePromise = options.deadCode ? (async () => {
+	const deadCodePromise = options.deadCode && !isDiffMode ? (async () => {
 		const deadCodeSpinner = options.scoreOnly ? null : spinner("Detecting dead code...").start();
 		try {
 			const knipDiagnostics = await runKnip(directory);
@@ -1207,11 +1328,12 @@ const scan = async (directory, options) => {
 		}
 	})() : Promise.resolve([]);
 	const [lintDiagnostics, deadCodeDiagnostics] = await Promise.all([lintPromise, deadCodePromise]);
-	const diagnostics = [
+	const allDiagnostics = [
 		...lintDiagnostics,
 		...deadCodeDiagnostics,
-		...checkReducedMotion(directory)
+		...isDiffMode ? [] : checkReducedMotion(directory)
 	];
+	const diagnostics = userConfig ? filterIgnoredDiagnostics(allDiagnostics, userConfig) : allDiagnostics;
 	const elapsedMilliseconds = performance.now() - startTime;
 	const scoreResult = await calculateScore(diagnostics);
 	if (options.scoreOnly) {
@@ -1229,7 +1351,149 @@ const scan = async (directory, options) => {
 		return;
 	}
 	printDiagnostics(diagnostics, options.verbose);
-	printSummary(diagnostics, elapsedMilliseconds, scoreResult, projectInfo.projectName, projectInfo.sourceFileCount);
+	const displayedSourceFileCount = isDiffMode ? includePaths.length : projectInfo.sourceFileCount;
+	printSummary(diagnostics, elapsedMilliseconds, scoreResult, projectInfo.projectName, displayedSourceFileCount);
+};
+
+//#endregion
+//#region src/utils/copy-to-clipboard.ts
+const getClipboardCommands = () => {
+	if (process.platform === "darwin") return [{
+		command: "pbcopy",
+		args: []
+	}];
+	if (process.platform === "win32") return [{
+		command: "clip",
+		args: []
+	}];
+	return [
+		{
+			command: "wl-copy",
+			args: []
+		},
+		{
+			command: "xclip",
+			args: ["-selection", "clipboard"]
+		},
+		{
+			command: "xsel",
+			args: ["--clipboard", "--input"]
+		}
+	];
+};
+const copyToClipboard = (text) => {
+	const clipboardCommands = getClipboardCommands();
+	for (const clipboardCommand of clipboardCommands) if (spawnSync(clipboardCommand.command, clipboardCommand.args, {
+		input: text,
+		stdio: [
+			"pipe",
+			"ignore",
+			"ignore"
+		],
+		encoding: "utf8"
+	}).status === 0) return true;
+	return false;
+};
+
+//#endregion
+//#region src/utils/get-diff-files.ts
+const getCurrentBranch = (directory) => {
+	try {
+		const branch = execSync("git rev-parse --abbrev-ref HEAD", {
+			cwd: directory,
+			stdio: "pipe"
+		}).toString().trim();
+		return branch === "HEAD" ? null : branch;
+	} catch {
+		return null;
+	}
+};
+const detectDefaultBranch = (directory) => {
+	try {
+		return execSync("git symbolic-ref refs/remotes/origin/HEAD", {
+			cwd: directory,
+			stdio: "pipe"
+		}).toString().trim().replace("refs/remotes/origin/", "");
+	} catch {
+		for (const candidate of DEFAULT_BRANCH_CANDIDATES) try {
+			execSync(`git rev-parse --verify ${candidate}`, {
+				cwd: directory,
+				stdio: "pipe"
+			});
+			return candidate;
+		} catch {}
+		return null;
+	}
+};
+const getChangedFilesSinceBranch = (directory, baseBranch) => {
+	try {
+		const output = execSync(`git diff --name-only --diff-filter=ACMR --relative ${execSync(`git merge-base ${baseBranch} HEAD`, {
+			cwd: directory,
+			stdio: "pipe"
+		}).toString().trim()}`, {
+			cwd: directory,
+			stdio: "pipe"
+		}).toString().trim();
+		if (!output) return [];
+		return output.split("\n").filter(Boolean);
+	} catch {
+		return [];
+	}
+};
+const getDiffInfo = (directory, explicitBaseBranch) => {
+	const currentBranch = getCurrentBranch(directory);
+	if (!currentBranch) return null;
+	const baseBranch = explicitBaseBranch ?? detectDefaultBranch(directory);
+	if (!baseBranch) return null;
+	if (currentBranch === baseBranch) return null;
+	return {
+		currentBranch,
+		baseBranch,
+		changedFiles: getChangedFilesSinceBranch(directory, baseBranch)
+	};
+};
+const filterSourceFiles = (filePaths) => filePaths.filter((filePath) => SOURCE_FILE_PATTERN.test(filePath));
+
+//#endregion
+//#region src/utils/global-install.ts
+const isGloballyInstalled = () => {
+	try {
+		return !execSync("which react-doctor", {
+			stdio: "pipe",
+			encoding: "utf-8"
+		}).trim().includes("/_npx/");
+	} catch {
+		return false;
+	}
+};
+const maybeInstallGlobally = () => {
+	try {
+		if (isGloballyInstalled()) return;
+		const child = spawn("npm", [
+			"install",
+			"-g",
+			"react-doctor@latest"
+		], {
+			detached: true,
+			stdio: "ignore"
+		});
+		child.on("error", () => {});
+		child.unref();
+	} catch {}
+};
+
+//#endregion
+//#region src/utils/handle-error.ts
+const DEFAULT_HANDLE_ERROR_OPTIONS = { shouldExit: true };
+const handleError = (error, options = DEFAULT_HANDLE_ERROR_OPTIONS) => {
+	logger.break();
+	logger.error("Something went wrong. Please check the error below for more details.");
+	logger.error("If the problem persists, please open an issue on GitHub.");
+	logger.error("");
+	if (error instanceof Error) logger.error(error.message);
+	logger.break();
+	if (options.shouldExit) process.exit(1);
+	process.exitCode = 1;
 };
 
 //#endregion
@@ -1393,93 +1657,49 @@ const maybePromptSkillInstall = async (shouldSkipPrompts) => {
 	}
 };
 
-//#endregion
-//#region src/utils/global-install.ts
-const isGloballyInstalled = () => {
-	try {
-		return !execSync("which react-doctor", {
-			stdio: "pipe",
-			encoding: "utf-8"
-		}).trim().includes("/_npx/");
-	} catch {
-		return false;
-	}
-};
-const maybeInstallGlobally = () => {
-	try {
-		if (isGloballyInstalled()) return;
-		const child = spawn("npm", [
-			"install",
-			"-g",
-			"react-doctor@latest"
-		], {
-			detached: true,
-			stdio: "ignore"
-		});
-		child.on("error", () => {});
-		child.unref();
-	} catch {}
-};
-
-//#endregion
-//#region src/utils/copy-to-clipboard.ts
-const getClipboardCommands = () => {
-	if (process.platform === "darwin") return [{
-		command: "pbcopy",
-		args: []
-	}];
-	if (process.platform === "win32") return [{
-		command: "clip",
-		args: []
-	}];
-	return [
-		{
-			command: "wl-copy",
-			args: []
-		},
-		{
-			command: "xclip",
-			args: ["-selection", "clipboard"]
-		},
-		{
-			command: "xsel",
-			args: ["--clipboard", "--input"]
-		}
-	];
-};
-const copyToClipboard = (text) => {
-	const clipboardCommands = getClipboardCommands();
-	for (const clipboardCommand of clipboardCommands) if (spawnSync(clipboardCommand.command, clipboardCommand.args, {
-		input: text,
-		stdio: [
-			"pipe",
-			"ignore",
-			"ignore"
-		],
-		encoding: "utf8"
-	}).status === 0) return true;
-	return false;
-};
-
 //#endregion
 //#region src/cli.ts
-const VERSION = "0.0.18";
+const VERSION = "0.0.20";
 process.on("SIGINT", () => process.exit(0));
 process.on("SIGTERM", () => process.exit(0));
-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("--fix", "open Ami to auto-fix all issues").option("--prompt", "copy latest scan output to clipboard").action(async (directory, flags) => {
+const resolveDiffMode = async (diffInfo, effectiveDiff, shouldSkipPrompts, isScoreOnly) => {
+	if (effectiveDiff !== void 0 && effectiveDiff !== false) {
+		if (diffInfo) return true;
+		if (!isScoreOnly) {
+			logger.warn("Not on a feature branch or could not determine base branch. Running full scan.");
+			logger.break();
+		}
+		return false;
+	}
+	if (effectiveDiff === false || !diffInfo) return false;
+	const changedSourceFiles = filterSourceFiles(diffInfo.changedFiles);
+	if (changedSourceFiles.length === 0) return false;
+	if (shouldSkipPrompts) return true;
+	if (isScoreOnly) return false;
+	const { shouldScanBranchOnly } = await prompts({
+		type: "confirm",
+		name: "shouldScanBranchOnly",
+		message: `On branch ${diffInfo.currentBranch} (${changedSourceFiles.length} changed files vs ${diffInfo.baseBranch}). Only scan this branch?`,
+		initial: true
+	});
+	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("--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();
 	try {
 		const resolvedDirectory = path.resolve(directory);
+		const userConfig = loadConfig(resolvedDirectory);
 		if (!isScoreOnly) {
 			logger.log(`react-doctor v${VERSION}`);
 			logger.break();
 		}
+		const isCliOverride = (optionName) => program.getOptionValueSource(optionName) === "cli";
 		const scanOptions = {
-			lint: flags.lint,
-			deadCode: flags.deadCode,
-			verbose: flags.prompt || Boolean(flags.verbose),
+			lint: isCliOverride("lint") ? flags.lint : userConfig?.lint ?? flags.lint,
+			deadCode: isCliOverride("deadCode") ? flags.deadCode : userConfig?.deadCode ?? flags.deadCode,
+			verbose: flags.prompt || (isCliOverride("verbose") ? Boolean(flags.verbose) : userConfig?.verbose ?? false),
 			scoreOnly: isScoreOnly
 		};
 		const isAutomatedEnvironment = [
@@ -1493,12 +1713,38 @@ const program = new Command().name("react-doctor").description("Diagnose React c
 		].some(Boolean);
 		const shouldSkipPrompts = flags.yes || isAutomatedEnvironment || !process.stdin.isTTY;
 		const projectDirectories = await selectProjects(resolvedDirectory, flags.project, shouldSkipPrompts);
+		const effectiveDiff = isCliOverride("diff") ? flags.diff : userConfig?.diff;
+		const explicitBaseBranch = typeof effectiveDiff === "string" ? effectiveDiff : void 0;
+		const diffInfo = getDiffInfo(resolvedDirectory, explicitBaseBranch);
+		const isDiffMode = await resolveDiffMode(diffInfo, effectiveDiff, shouldSkipPrompts, isScoreOnly);
+		if (isDiffMode && diffInfo && !isScoreOnly) {
+			logger.log(`Scanning changes: ${highlighter.info(diffInfo.currentBranch)} → ${highlighter.info(diffInfo.baseBranch)}`);
+			logger.break();
+		}
 		for (const projectDirectory of projectDirectories) {
+			let includePaths;
+			if (isDiffMode) {
+				const projectDiffInfo = getDiffInfo(projectDirectory, explicitBaseBranch);
+				if (projectDiffInfo) {
+					const changedSourceFiles = filterSourceFiles(projectDiffInfo.changedFiles);
+					if (changedSourceFiles.length === 0) {
+						if (!isScoreOnly) {
+							logger.dim(`No changed source files in ${projectDirectory}, skipping.`);
+							logger.break();
+						}
+						continue;
+					}
+					includePaths = changedSourceFiles;
+				}
+			}
 			if (!isScoreOnly) {
 				logger.dim(`Scanning ${projectDirectory}...`);
 				logger.break();
 			}
-			await scan(projectDirectory, scanOptions);
+			await scan(projectDirectory, {
+				...scanOptions,
+				includePaths
+			});
 			if (!isScoreOnly) logger.break();
 		}
 		if (flags.fix) openAmiToFix(resolvedDirectory);