react-doctor 0.0.47 → 0.1.1

package/dist/cli.js

@@ -3,7 +3,7 @@ import fs, { accessSync, constants, existsSync, mkdirSync, mkdtempSync, readdirS
 import os, { tmpdir } from "node:os";
 import path, { join } from "node:path";
 import { performance } from "node:perf_hooks";
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import { fileURLToPath } from "node:url";
 import { SKILL_MANIFEST_FILE, detectInstalledSkillAgents, getSkillAgentConfig, getSkillAgentTypes, installSkillsFromSource } from "agent-install";
 import pc from "picocolors";
@@ -35,6 +35,7 @@ const KNIP_CONFIG_LOCATIONS = [
 	"knip.config.ts",
 	"knip.config.js"
 ];
+const ADOPTABLE_LINT_CONFIG_FILENAMES = [".oxlintrc.json", ".eslintrc.json"];
 const OXLINT_NODE_REQUIREMENT = "^20.19.0 || >=22.12.0";
 const GIT_SHOW_MAX_BUFFER_BYTES = 10 * 1024 * 1024;
 const IGNORED_DIRECTORIES = new Set([
@@ -88,7 +89,9 @@ const highlighter = {
 	warn: pc.yellow,
 	info: pc.cyan,
 	success: pc.green,
-	dim: pc.dim
+	dim: pc.dim,
+	gray: pc.gray,
+	bold: pc.bold
 };
 //#endregion
 //#region src/utils/logger.ts
@@ -295,7 +298,47 @@ const runInstallSkill = async (options = {}) => {
 	}
 };
 //#endregion
-//#region src/core/calculate-score-locally.ts
+//#region src/utils/build-category-breakdown.ts
+const buildCategoryBreakdown = (diagnostics) => {
+	const entriesByCategory = /* @__PURE__ */ new Map();
+	for (const diagnostic of diagnostics) {
+		const existingEntry = entriesByCategory.get(diagnostic.category) ?? {
+			category: diagnostic.category,
+			totalCount: 0,
+			errorCount: 0,
+			warningCount: 0
+		};
+		existingEntry.totalCount += 1;
+		if (diagnostic.severity === "error") existingEntry.errorCount += 1;
+		else existingEntry.warningCount += 1;
+		entriesByCategory.set(diagnostic.category, existingEntry);
+	}
+	return [...entriesByCategory.values()].sort((entryA, entryB) => {
+		if (entryA.errorCount !== entryB.errorCount) return entryB.errorCount - entryA.errorCount;
+		if (entryA.totalCount !== entryB.totalCount) return entryB.totalCount - entryA.totalCount;
+		return entryA.category.localeCompare(entryB.category);
+	});
+};
+//#endregion
+//#region src/utils/build-hidden-diagnostics-summary.ts
+const buildHiddenDiagnosticsSummary = (hiddenDiagnostics) => {
+	const errorCount = hiddenDiagnostics.filter((diagnostic) => diagnostic.severity === "error").length;
+	const warningCount = hiddenDiagnostics.length - errorCount;
+	const parts = [];
+	if (errorCount > 0) parts.push({
+		severity: "error",
+		count: errorCount,
+		text: `✗ ${errorCount} more error${errorCount === 1 ? "" : "s"}`
+	});
+	if (warningCount > 0) parts.push({
+		severity: "warning",
+		count: warningCount,
+		text: `⚠ ${warningCount} more warning${warningCount === 1 ? "" : "s"}`
+	});
+	return parts;
+};
+//#endregion
+//#region src/utils/calculate-score-locally.ts
 const getScoreLabel = (score) => {
 	if (score >= 75) return "Great";
 	if (score >= 50) return "Needs work";
@@ -327,7 +370,7 @@ const calculateScoreLocally = (diagnostics) => {
 	};
 };
 //#endregion
-//#region src/core/try-score-from-api.ts
+//#region src/utils/try-score-from-api.ts
 const parseScoreResult = (value) => {
 	if (typeof value !== "object" || value === null) return null;
 	if (!("score" in value) || !("label" in value)) return null;
@@ -370,10 +413,6 @@ const tryScoreFromApi = async (diagnostics, fetchImplementation) => {
 	}
 };
 //#endregion
-//#region src/utils/calculate-score-browser.ts
-const getGlobalFetch = () => typeof fetch === "function" ? fetch : void 0;
-const calculateScore$1 = async (diagnostics, fetchImplementation = getGlobalFetch()) => await tryScoreFromApi(diagnostics, fetchImplementation) ?? calculateScoreLocally(diagnostics);
-//#endregion
 //#region src/utils/proxy-fetch.ts
 const getGlobalProcess = () => {
 	const candidate = globalThis.process;
@@ -402,8 +441,8 @@ const proxyFetch = async (url, init) => {
 	return fetch(url, fetchInit);
 };
 //#endregion
-//#region src/utils/calculate-score-node.ts
-const calculateScore = (diagnostics) => calculateScore$1(diagnostics, proxyFetch);
+//#region src/utils/calculate-score.ts
+const calculateScore = async (diagnostics) => await tryScoreFromApi(diagnostics, proxyFetch) ?? calculateScoreLocally(diagnostics);
 //#endregion
 //#region src/utils/colorize-by-score.ts
 const colorizeByScore = (text, score) => {
@@ -413,6 +452,85 @@ const colorizeByScore = (text, score) => {
 };
 //#endregion
 //#region src/plugin/constants.ts
+const FETCH_CALLEE_NAMES = new Set([
+	"fetch",
+	"ky",
+	"got",
+	"wretch",
+	"ofetch"
+]);
+const FETCH_MEMBER_OBJECTS = new Set([
+	"axios",
+	"ky",
+	"got",
+	"ofetch",
+	"wretch",
+	"request"
+]);
+const TIMER_AND_SCHEDULER_DIRECT_CALLEE_NAMES = new Set([
+	"setTimeout",
+	"setInterval",
+	"requestAnimationFrame",
+	"requestIdleCallback",
+	"queueMicrotask"
+]);
+const SUBSCRIPTION_METHOD_NAMES = new Set([
+	"subscribe",
+	"addEventListener",
+	"addListener",
+	"on",
+	"watch",
+	"listen",
+	"sub"
+]);
+new Set([
+	...new Set([
+		"unsubscribe",
+		"removeEventListener",
+		"removeListener",
+		"off",
+		"unwatch",
+		"unlisten",
+		"unsub"
+	]),
+	"cleanup",
+	"dispose",
+	"destroy",
+	"teardown"
+]);
+new Set([
+	...SUBSCRIPTION_METHOD_NAMES,
+	"connect",
+	"disconnect",
+	"open",
+	"close",
+	"fetch",
+	"post",
+	"put",
+	"patch"
+]);
+new Set([
+	...FETCH_MEMBER_OBJECTS,
+	"api",
+	"client",
+	"http",
+	"fetcher"
+]);
+new Set([...FETCH_CALLEE_NAMES, ...TIMER_AND_SCHEDULER_DIRECT_CALLEE_NAMES]);
+new Set([
+	...FETCH_CALLEE_NAMES,
+	"post",
+	"put",
+	"patch",
+	"navigate",
+	"navigateTo",
+	"showNotification",
+	"toast",
+	"alert",
+	"confirm",
+	"logVisit",
+	"captureEvent"
+]);
 const MOTION_LIBRARY_PACKAGES = new Set(["framer-motion", "motion"]);
 //#endregion
 //#region src/utils/is-file.ts
@@ -515,6 +633,13 @@ const createNodeReadFileLinesSync = (rootDirectory) => {
 	};
 };
 //#endregion
+//#region src/utils/is-plain-object.ts
+const isPlainObject = (value) => {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === null || prototype === Object.prototype;
+};
+//#endregion
 //#region src/utils/match-glob-pattern.ts
 const REGEX_SPECIAL_CHARACTERS = /[.+^${}()|[\]\\]/g;
 const compileGlobPattern = (pattern) => {
@@ -542,13 +667,232 @@ const compileGlobPattern = (pattern) => {
 	return new RegExp(regexSource);
 };
 //#endregion
-//#region src/utils/is-ignored-file.ts
+//#region src/utils/to-relative-path.ts
 const toRelativePath = (filePath, rootDirectory) => {
 	const normalizedFilePath = filePath.replace(/\\/g, "/");
 	const normalizedRoot = rootDirectory.replace(/\\/g, "/").replace(/\/$/, "") + "/";
 	if (normalizedFilePath.startsWith(normalizedRoot)) return normalizedFilePath.slice(normalizedRoot.length);
 	return normalizedFilePath.replace(/^\.\//, "");
 };
+//#endregion
+//#region src/utils/apply-ignore-overrides.ts
+const warnConfigField$1 = (message) => {
+	process.stderr.write(`[react-doctor] ${message}\n`);
+};
+const isStringArray = (value) => Array.isArray(value) && value.every((entry) => typeof entry === "string");
+const collectStringList = (value) => Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+const validateOverrideEntry = (entry, index) => {
+	if (!isPlainObject(entry)) {
+		warnConfigField$1(`ignore.overrides[${index}] must be an object with { files, rules }; ignoring this entry.`);
+		return null;
+	}
+	if (!isStringArray(entry.files)) {
+		warnConfigField$1(`ignore.overrides[${index}].files must be an array of strings; ignoring this entry.`);
+		return null;
+	}
+	if (entry.rules !== void 0 && !isStringArray(entry.rules)) {
+		warnConfigField$1(`ignore.overrides[${index}].rules must be an array of "plugin/rule" strings or omitted; treating as missing (override would suppress every rule for the matched files).`);
+		return { files: entry.files };
+	}
+	return entry.rules === void 0 ? { files: entry.files } : {
+		files: entry.files,
+		rules: entry.rules
+	};
+};
+const compileIgnoreOverrides = (userConfig) => {
+	const overrides = userConfig?.ignore?.overrides;
+	if (overrides === void 0) return [];
+	if (!Array.isArray(overrides)) {
+		warnConfigField$1(`ignore.overrides must be an array of { files, rules } entries; ignoring.`);
+		return [];
+	}
+	return overrides.flatMap((entry, index) => {
+		const validated = validateOverrideEntry(entry, index);
+		if (!validated) return [];
+		const filePatterns = collectStringList(validated.files).map(compileGlobPattern);
+		if (filePatterns.length === 0) return [];
+		return [{
+			filePatterns,
+			ruleIds: new Set(collectStringList(validated.rules))
+		}];
+	});
+};
+const isDiagnosticIgnoredByOverrides = (diagnostic, rootDirectory, overrides) => {
+	if (overrides.length === 0) return false;
+	const relativeFilePath = toRelativePath(diagnostic.filePath, rootDirectory);
+	const ruleIdentifier = `${diagnostic.plugin}/${diagnostic.rule}`;
+	return overrides.some((override) => override.filePatterns.some((pattern) => pattern.test(relativeFilePath)) && (override.ruleIds.size === 0 || override.ruleIds.has(ruleIdentifier)));
+};
+//#endregion
+//#region src/utils/find-jsx-opener-span.ts
+const JSX_OPENER_TAG_PATTERN = /<[A-Za-z][\w.]*/g;
+const JSX_TAG_NAME_FOLLOW = /[A-Za-z]/;
+const isOpenerMatchInsideLineComment = (line, openerCharIndex) => {
+	let stringDelimiter = null;
+	for (let charIndex = 0; charIndex < openerCharIndex; charIndex++) {
+		const character = line[charIndex];
+		if (stringDelimiter !== null) {
+			if (character === "\\") {
+				charIndex++;
+				continue;
+			}
+			if (character === stringDelimiter) stringDelimiter = null;
+			continue;
+		}
+		if (character === "\"" || character === "'" || character === "`") {
+			stringDelimiter = character;
+			continue;
+		}
+		if (character === "/" && line[charIndex + 1] === "/") return true;
+	}
+	return false;
+};
+const findOpenerTagOnLine = (line) => {
+	for (const match of line.matchAll(JSX_OPENER_TAG_PATTERN)) {
+		if (match.index === void 0) continue;
+		if (!isOpenerMatchInsideLineComment(line, match.index)) return { startCharIndex: match.index + match[0].length };
+	}
+	return null;
+};
+const findJsxOpenerSpan = (lines, openerLineIndex) => {
+	const openerLine = lines[openerLineIndex];
+	if (openerLine === void 0) return null;
+	const opener = findOpenerTagOnLine(openerLine);
+	if (!opener) return null;
+	const lookaheadLimit = Math.min(lines.length, openerLineIndex + 32);
+	let braceDepth = 0;
+	let innerAngleDepth = 0;
+	let stringDelimiter = null;
+	for (let lineIndex = openerLineIndex; lineIndex < lookaheadLimit; lineIndex++) {
+		const currentLine = lines[lineIndex];
+		const startCharForLine = lineIndex === openerLineIndex ? opener.startCharIndex : 0;
+		for (let charIndex = startCharForLine; charIndex < currentLine.length; charIndex++) {
+			const character = currentLine[charIndex];
+			if (stringDelimiter !== null) {
+				if (character === "\\") {
+					charIndex++;
+					continue;
+				}
+				if (character === stringDelimiter) stringDelimiter = null;
+				continue;
+			}
+			if (character === "\"" || character === "'" || character === "`") {
+				stringDelimiter = character;
+				continue;
+			}
+			if (character === "{") {
+				braceDepth++;
+				continue;
+			}
+			if (character === "}") {
+				braceDepth--;
+				continue;
+			}
+			if (braceDepth !== 0) continue;
+			if (character === "<") {
+				const followCharacter = currentLine[charIndex + 1];
+				if (followCharacter !== void 0 && JSX_TAG_NAME_FOLLOW.test(followCharacter)) innerAngleDepth++;
+				continue;
+			}
+			if (character !== ">") continue;
+			const previousCharacter = currentLine[charIndex - 1];
+			const nextCharacter = currentLine[charIndex + 1];
+			if (previousCharacter === "=" || nextCharacter === "=") continue;
+			if (innerAngleDepth > 0) {
+				innerAngleDepth--;
+				continue;
+			}
+			return lineIndex;
+		}
+	}
+	return null;
+};
+//#endregion
+//#region src/utils/find-enclosing-jsx-opener.ts
+const findEnclosingMultilineJsxOpenerStart = (lines, diagnosticLineIndex) => {
+	for (let candidateIndex = diagnosticLineIndex - 1; candidateIndex >= 0 && diagnosticLineIndex - candidateIndex <= 32; candidateIndex--) {
+		const openerCloseIndex = findJsxOpenerSpan(lines, candidateIndex);
+		if (openerCloseIndex !== null && openerCloseIndex >= diagnosticLineIndex) return candidateIndex;
+	}
+	return null;
+};
+//#endregion
+//#region src/utils/find-stacked-disable-comments.ts
+const DISABLE_NEXT_LINE_PATTERN = /(?:\/\/|\/\*)\s*react-doctor-disable-next-line\b(?:\s+([\w/\-.,\s]+?))?\s*(?:\*\/)?\s*\}?\s*$/;
+const findStackedDisableCommentsAbove = (lines, anchorIndex) => {
+	const collected = [];
+	let isStillInChain = true;
+	for (let candidateIndex = anchorIndex - 1; candidateIndex >= 0 && anchorIndex - candidateIndex <= 10; candidateIndex--) {
+		const candidateLine = lines[candidateIndex];
+		if (candidateLine === void 0) break;
+		const match = candidateLine.match(DISABLE_NEXT_LINE_PATTERN);
+		if (match) {
+			collected.push({
+				commentLineIndex: candidateIndex,
+				ruleList: match[1],
+				isInChain: isStillInChain
+			});
+			continue;
+		}
+		isStillInChain = false;
+	}
+	return collected;
+};
+//#endregion
+//#region src/utils/is-rule-listed-in-comment.ts
+const isRuleListedInComment = (ruleList, ruleId) => {
+	if (!ruleList?.trim()) return true;
+	return ruleList.split(/[,\s]+/).some((token) => token.trim() === ruleId);
+};
+//#endregion
+//#region src/utils/evaluate-suppression.ts
+const DISABLE_LINE_PATTERN = /(?:\/\/|\/\*)\s*react-doctor-disable-line\b(?:\s+([\w/\-.,\s]+?))?\s*(?:\*\/)?\s*\}?\s*$/;
+const formatLineGap = (gapLineCount) => `${gapLineCount} line${gapLineCount === 1 ? "" : "s"}`;
+const hasChainSuppressor = (comments, ruleId) => comments.some((comment) => comment.isInChain && isRuleListedInComment(comment.ruleList, ruleId));
+const findAdjacentRuleListMismatch = (comments, ruleId) => comments.find((comment) => comment.isInChain && Boolean(comment.ruleList?.trim()) && !isRuleListedInComment(comment.ruleList, ruleId));
+const findOutOfChainMatch = (comments, ruleId) => comments.find((comment) => !comment.isInChain && isRuleListedInComment(comment.ruleList, ruleId));
+const buildAdjacentMismatchHint = (comment, ruleId) => {
+	const ruleListText = comment.ruleList?.trim() ?? "";
+	return `An adjacent react-doctor-disable-next-line at line ${comment.commentLineIndex + 1} lists "${ruleListText}" — ${ruleId} is not in that list. Use the comma form: react-doctor-disable-next-line ${ruleListText}, ${ruleId}`;
+};
+const buildGapHint = (comment, diagnosticLineIndex, ruleId) => {
+	const commentLineNumber = comment.commentLineIndex + 1;
+	const diagnosticLineNumber = diagnosticLineIndex + 1;
+	return `A react-doctor-disable-next-line for ${ruleId} sits at line ${commentLineNumber}, but ${formatLineGap(diagnosticLineNumber - commentLineNumber - 1)} of code separate it from the diagnostic on line ${diagnosticLineNumber}. Move the comment immediately above line ${diagnosticLineNumber}, or extract the surrounding code into a helper so the suppression is adjacent.`;
+};
+const classifyFromComments = (commentsByAnchor, diagnosticLineIndex, ruleId) => {
+	for (const comments of commentsByAnchor) {
+		const adjacentMismatch = findAdjacentRuleListMismatch(comments, ruleId);
+		if (adjacentMismatch) return buildAdjacentMismatchHint(adjacentMismatch, ruleId);
+		const outOfChainMatch = findOutOfChainMatch(comments, ruleId);
+		if (outOfChainMatch) return buildGapHint(outOfChainMatch, diagnosticLineIndex, ruleId);
+	}
+	return null;
+};
+const evaluateSuppression = (lines, diagnosticLineIndex, ruleId) => {
+	const sameLineMatch = lines[diagnosticLineIndex]?.match(DISABLE_LINE_PATTERN);
+	if (sameLineMatch && isRuleListedInComment(sameLineMatch[1], ruleId)) return {
+		isSuppressed: true,
+		nearMissHint: null
+	};
+	const directComments = findStackedDisableCommentsAbove(lines, diagnosticLineIndex);
+	if (hasChainSuppressor(directComments, ruleId)) return {
+		isSuppressed: true,
+		nearMissHint: null
+	};
+	const openerStartIndex = findEnclosingMultilineJsxOpenerStart(lines, diagnosticLineIndex);
+	const openerComments = openerStartIndex !== null && openerStartIndex > 0 ? findStackedDisableCommentsAbove(lines, openerStartIndex) : [];
+	if (hasChainSuppressor(openerComments, ruleId)) return {
+		isSuppressed: true,
+		nearMissHint: null
+	};
+	return {
+		isSuppressed: false,
+		nearMissHint: classifyFromComments([directComments, openerComments], diagnosticLineIndex, ruleId)
+	};
+};
+//#endregion
+//#region src/utils/is-ignored-file.ts
 const compileIgnoredFilePatterns = (userConfig) => {
 	const files = userConfig?.ignore?.files;
 	if (!Array.isArray(files)) return [];
@@ -561,14 +905,12 @@ const isFileIgnoredByPatterns = (filePath, rootDirectory, patterns) => {
 };
 //#endregion
 //#region src/utils/filter-diagnostics.ts
+const OPENING_TAG_PATTERN = /<([A-Z][\w.]*)/;
 const resolveCandidateReadPath = (rootDirectory, filePath) => {
 	const normalizedFile = filePath.replace(/\\/g, "/");
 	if (normalizedFile.startsWith("/") || /^[a-zA-Z]:\//.test(normalizedFile) || /^[a-zA-Z]:\\/.test(filePath)) return filePath;
 	return `${rootDirectory.replace(/\\/g, "/").replace(/\/$/, "")}/${normalizedFile.replace(/^\.\//, "")}`;
 };
-const OPENING_TAG_PATTERN = /<([A-Z][\w.]*)/;
-const DISABLE_NEXT_LINE_PATTERN = /\/\/\s*react-doctor-disable-next-line\b(?:\s+(.+))?/;
-const DISABLE_LINE_PATTERN = /\/\/\s*react-doctor-disable-line\b(?:\s+(.+))?/;
 const createFileLinesCache = (rootDirectory, readFileLinesSync) => {
 	const cache = /* @__PURE__ */ new Map();
 	return (filePath) => {
@@ -589,13 +931,10 @@ const isInsideTextComponent = (lines, diagnosticLine, textComponentNames) => {
 	}
 	return false;
 };
-const isRuleSuppressed = (commentRules, ruleId) => {
-	if (!commentRules?.trim()) return true;
-	return commentRules.split(/[,\s]+/).some((rule) => rule.trim() === ruleId);
-};
 const filterIgnoredDiagnostics = (diagnostics, config, rootDirectory, readFileLinesSync) => {
 	const ignoredRules = new Set(Array.isArray(config.ignore?.rules) ? config.ignore.rules.filter((rule) => typeof rule === "string") : []);
 	const ignoredFilePatterns = compileIgnoredFilePatterns(config);
+	const compiledOverrides = compileIgnoreOverrides(config);
 	const textComponentNames = new Set(Array.isArray(config.textComponents) ? config.textComponents.filter((name) => typeof name === "string") : []);
 	const hasTextComponents = textComponentNames.size > 0;
 	const getFileLines = createFileLinesCache(rootDirectory, readFileLinesSync);
@@ -603,6 +942,7 @@ const filterIgnoredDiagnostics = (diagnostics, config, rootDirectory, readFileLi
 		const ruleIdentifier = `${diagnostic.plugin}/${diagnostic.rule}`;
 		if (ignoredRules.has(ruleIdentifier)) return false;
 		if (isFileIgnoredByPatterns(diagnostic.filePath, rootDirectory, ignoredFilePatterns)) return false;
+		if (isDiagnosticIgnoredByOverrides(diagnostic, rootDirectory, compiledOverrides)) return false;
 		if (hasTextComponents && diagnostic.rule === "rn-no-raw-text" && diagnostic.line > 0) {
 			const lines = getFileLines(diagnostic.filePath);
 			if (lines && isInsideTextComponent(lines, diagnostic.line, textComponentNames)) return false;
@@ -612,41 +952,36 @@ const filterIgnoredDiagnostics = (diagnostics, config, rootDirectory, readFileLi
 };
 const filterInlineSuppressions = (diagnostics, rootDirectory, readFileLinesSync) => {
 	const getFileLines = createFileLinesCache(rootDirectory, readFileLinesSync);
-	return diagnostics.filter((diagnostic) => {
-		if (diagnostic.line <= 0) return true;
+	return diagnostics.flatMap((diagnostic) => {
+		if (diagnostic.line <= 0) return [diagnostic];
 		const lines = getFileLines(diagnostic.filePath);
-		if (!lines) return true;
-		const ruleId = `${diagnostic.plugin}/${diagnostic.rule}`;
-		const currentLine = lines[diagnostic.line - 1];
-		if (currentLine) {
-			const lineMatch = currentLine.match(DISABLE_LINE_PATTERN);
-			if (lineMatch && isRuleSuppressed(lineMatch[1], ruleId)) return false;
-		}
-		if (diagnostic.line >= 2) {
-			const previousLine = lines[diagnostic.line - 2];
-			if (previousLine) {
-				const nextLineMatch = previousLine.match(DISABLE_NEXT_LINE_PATTERN);
-				if (nextLineMatch && isRuleSuppressed(nextLineMatch[1], ruleId)) return false;
-			}
-		}
-		return true;
+		if (!lines) return [diagnostic];
+		const ruleIdentifier = `${diagnostic.plugin}/${diagnostic.rule}`;
+		const evaluation = evaluateSuppression(lines, diagnostic.line - 1, ruleIdentifier);
+		if (evaluation.isSuppressed) return [];
+		return evaluation.nearMissHint ? [{
+			...diagnostic,
+			suppressionHint: evaluation.nearMissHint
+		}] : [diagnostic];
 	});
 };
 //#endregion
 //#region src/utils/merge-and-filter-diagnostics.ts
-const mergeAndFilterDiagnostics = (mergedDiagnostics, directory, userConfig, readFileLinesSync) => {
-	return filterInlineSuppressions(userConfig ? filterIgnoredDiagnostics(mergedDiagnostics, userConfig, directory, readFileLinesSync) : mergedDiagnostics, directory, readFileLinesSync);
+const mergeAndFilterDiagnostics = (mergedDiagnostics, directory, userConfig, readFileLinesSync, options = {}) => {
+	const filtered = userConfig ? filterIgnoredDiagnostics(mergedDiagnostics, userConfig, directory, readFileLinesSync) : mergedDiagnostics;
+	if (options.respectInlineDisables === false) return filtered;
+	return filterInlineSuppressions(filtered, directory, readFileLinesSync);
 };
 //#endregion
 //#region src/utils/combine-diagnostics.ts
 const combineDiagnostics = (input) => {
-	const { lintDiagnostics, deadCodeDiagnostics, directory, isDiffMode, userConfig, readFileLinesSync = createNodeReadFileLinesSync(directory), includeEnvironmentChecks = true } = input;
+	const { lintDiagnostics, deadCodeDiagnostics, directory, isDiffMode, userConfig, readFileLinesSync = createNodeReadFileLinesSync(directory), includeEnvironmentChecks = true, respectInlineDisables } = input;
 	const extraDiagnostics = isDiffMode || !includeEnvironmentChecks ? [] : checkReducedMotion(directory);
 	return mergeAndFilterDiagnostics([
 		...lintDiagnostics,
 		...deadCodeDiagnostics,
 		...extraDiagnostics
-	], directory, userConfig, readFileLinesSync);
+	], directory, userConfig, readFileLinesSync, { respectInlineDisables });
 };
 //#endregion
 //#region src/utils/jsx-include-paths.ts
@@ -670,13 +1005,6 @@ const findMonorepoRoot = (startDirectory) => {
 	return null;
 };
 //#endregion
-//#region src/utils/is-plain-object.ts
-const isPlainObject = (value) => {
-	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
-	const prototype = Object.getPrototypeOf(value);
-	return prototype === null || prototype === Object.prototype;
-};
-//#endregion
 //#region src/utils/discover-project.ts
 const REACT_COMPILER_PACKAGES = new Set([
 	"babel-plugin-react-compiler",
@@ -1074,7 +1402,7 @@ const hasCompilerInConfigFile = (filePath) => {
 	return REACT_COMPILER_ENABLED_FLAG_PATTERN.test(content) || REACT_COMPILER_PACKAGE_REFERENCE_PATTERN.test(content);
 };
 const hasCompilerInConfigFiles = (directory, filenames) => filenames.some((filename) => hasCompilerInConfigFile(path.join(directory, filename)));
-const isProjectBoundary$1 = (directory) => {
+const isProjectBoundary$2 = (directory) => {
 	if (fs.existsSync(path.join(directory, ".git"))) return true;
 	return isMonorepoRoot(directory);
 };
@@ -1084,14 +1412,14 @@ const detectReactCompiler = (directory, packageJson) => {
 	if (hasCompilerInConfigFiles(directory, BABEL_CONFIG_FILENAMES)) return true;
 	if (hasCompilerInConfigFiles(directory, VITE_CONFIG_FILENAMES)) return true;
 	if (hasCompilerInConfigFiles(directory, EXPO_APP_CONFIG_FILENAMES)) return true;
-	if (isProjectBoundary$1(directory)) return false;
+	if (isProjectBoundary$2(directory)) return false;
 	let ancestorDirectory = path.dirname(directory);
 	while (ancestorDirectory !== path.dirname(ancestorDirectory)) {
 		const ancestorPackagePath = path.join(ancestorDirectory, "package.json");
 		if (isFile(ancestorPackagePath)) {
 			if (hasCompilerPackage(readPackageJson(ancestorPackagePath))) return true;
 		}
-		if (isProjectBoundary$1(ancestorDirectory)) return false;
+		if (isProjectBoundary$2(ancestorDirectory)) return false;
 		ancestorDirectory = path.dirname(ancestorDirectory);
 	}
 	return false;
@@ -1158,32 +1486,6 @@ const formatErrorMessage = (error) => error instanceof Error ? error.message ||
 const formatErrorChain = (rootError) => collectErrorChain(rootError).map(formatErrorMessage).join(" → ");
 const getErrorChainMessages = (rootError) => collectErrorChain(rootError).map(formatErrorMessage);
 //#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(2);
-	const horizontalPadding = " ".repeat(1);
-	const maximumLineLength = Math.max(...framedLines.map((framedLine) => framedLine.plainText.length));
-	const borderLine = "─".repeat(maximumLineLength + 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();
@@ -1206,7 +1508,8 @@ const BOOLEAN_FIELD_NAMES = [
 	"verbose",
 	"customRulesOnly",
 	"share",
-	"respectInlineDisables"
+	"respectInlineDisables",
+	"adoptExistingLintConfig"
 ];
 const warnConfigField = (message) => {
 	process.stderr.write(`[react-doctor] ${message}\n`);
@@ -1261,7 +1564,7 @@ const loadConfigFromDirectory = (directory) => {
 	}
 	return null;
 };
-const isProjectBoundary = (directory) => fs.existsSync(path.join(directory, ".git")) || isMonorepoRoot(directory);
+const isProjectBoundary$1 = (directory) => fs.existsSync(path.join(directory, ".git")) || isMonorepoRoot(directory);
 const cachedConfigs = /* @__PURE__ */ new Map();
 const loadConfig = (rootDirectory) => {
 	const cached = cachedConfigs.get(rootDirectory);
@@ -1271,7 +1574,7 @@ const loadConfig = (rootDirectory) => {
 		cachedConfigs.set(rootDirectory, localConfig);
 		return localConfig;
 	}
-	if (isProjectBoundary(rootDirectory)) {
+	if (isProjectBoundary$1(rootDirectory)) {
 		cachedConfigs.set(rootDirectory, null);
 		return null;
 	}
@@ -1282,7 +1585,7 @@ const loadConfig = (rootDirectory) => {
 			cachedConfigs.set(rootDirectory, ancestorConfig);
 			return ancestorConfig;
 		}
-		if (isProjectBoundary(ancestorDirectory)) {
+		if (isProjectBoundary$1(ancestorDirectory)) {
 			cachedConfigs.set(rootDirectory, null);
 			return null;
 		}
@@ -1441,36 +1744,57 @@ const extractFailedPluginName = (error) => {
 //#region src/utils/has-knip-config.ts
 const hasKnipConfig = (directory) => KNIP_CONFIG_LOCATIONS.some((configFilename) => isFile(path.join(directory, configFilename)));
 //#endregion
+//#region src/utils/sanitize-knip-config-patterns.ts
+const isMeaningfulPattern = (value) => typeof value !== "string" || value.trim().length > 0;
+const sanitizeStringArray = (values) => values.filter((entry) => typeof entry === "string" ? entry.trim().length > 0 : true);
+const sanitizeKnipConfigPatterns = (parsedConfig) => {
+	for (const [key, value] of Object.entries(parsedConfig)) {
+		if (typeof value === "string") {
+			if (!isMeaningfulPattern(value)) delete parsedConfig[key];
+			continue;
+		}
+		if (Array.isArray(value)) {
+			if (value.length === 0) continue;
+			const sanitized = sanitizeStringArray(value);
+			if (sanitized.length === value.length) continue;
+			if (sanitized.length === 0) delete parsedConfig[key];
+			else parsedConfig[key] = sanitized;
+			continue;
+		}
+		if (isPlainObject(value)) sanitizeKnipConfigPatterns(value);
+	}
+};
+//#endregion
 //#region src/utils/run-knip.ts
-const KNIP_ISSUE_TYPE_DESCRIPTORS = {
-	files: {
+const KNIP_ISSUE_TYPE_DESCRIPTORS = new Map([
+	["files", {
 		category: "Dead Code",
 		message: "Unused file",
 		severity: "warning"
-	},
-	exports: {
+	}],
+	["exports", {
 		category: "Dead Code",
 		message: "Unused export",
 		severity: "warning"
-	},
-	types: {
+	}],
+	["types", {
 		category: "Dead Code",
 		message: "Unused type",
 		severity: "warning"
-	},
-	duplicates: {
+	}],
+	["duplicates", {
 		category: "Dead Code",
 		message: "Duplicate export",
 		severity: "warning"
-	}
-};
+	}]
+]);
 const FALLBACK_KNIP_DESCRIPTOR = {
 	category: "Dead Code",
 	message: "Issue",
 	severity: "warning"
 };
 const collectIssueRecords = (records, issueType, rootDirectory) => {
-	const descriptor = KNIP_ISSUE_TYPE_DESCRIPTORS[issueType] ?? FALLBACK_KNIP_DESCRIPTOR;
+	const descriptor = KNIP_ISSUE_TYPE_DESCRIPTORS.get(issueType) ?? FALLBACK_KNIP_DESCRIPTOR;
 	const diagnostics = [];
 	for (const issues of Object.values(records)) for (const issue of Object.values(issues)) diagnostics.push({
 		filePath: path.relative(rootDirectory, issue.filePath),
@@ -1508,7 +1832,7 @@ const TSCONFIG_FILENAMES$1 = ["tsconfig.base.json", "tsconfig.json"];
 const resolveTsConfigFile = (directory) => TSCONFIG_FILENAMES$1.find((filename) => fs.existsSync(path.join(directory, filename)));
 const tryDisableFailedPlugin = (error, parsedConfig, disabledPlugins) => {
 	const failedPlugin = extractFailedPluginName(error);
-	if (!failedPlugin || !(failedPlugin in parsedConfig) || disabledPlugins.has(failedPlugin)) return false;
+	if (!failedPlugin || !Object.hasOwn(parsedConfig, failedPlugin) || disabledPlugins.has(failedPlugin)) return false;
 	disabledPlugins.add(failedPlugin);
 	parsedConfig[failedPlugin] = false;
 	return true;
@@ -1522,6 +1846,7 @@ const runKnipWithOptions = async (knipCwd, workspaceName) => {
 		...tsConfigFile ? { tsConfigFile } : {}
 	}));
 	const parsedConfig = options.parsedConfig;
+	sanitizeKnipConfigPatterns(parsedConfig);
 	const disabledPlugins = /* @__PURE__ */ new Set();
 	let lastKnipError;
 	for (let attempt = 0; attempt < 6; attempt++) try {
@@ -1553,7 +1878,7 @@ const runKnip = async (rootDirectory) => {
 	if (!(hasNodeModules(rootDirectory) || monorepoRoot !== null && hasNodeModules(monorepoRoot))) return [];
 	const { issues } = await runKnipForProject(rootDirectory, monorepoRoot);
 	const diagnostics = [];
-	const filesDescriptor = KNIP_ISSUE_TYPE_DESCRIPTORS.files;
+	const filesDescriptor = KNIP_ISSUE_TYPE_DESCRIPTORS.get("files") ?? FALLBACK_KNIP_DESCRIPTOR;
 	for (const unusedFilePath of collectUnusedFilePaths(issues.files)) diagnostics.push({
 		filePath: path.relative(rootDirectory, unusedFilePath),
 		plugin: "knip",
@@ -1573,6 +1898,18 @@ const runKnip = async (rootDirectory) => {
 	return diagnostics;
 };
 //#endregion
+//#region src/utils/parse-react-major.ts
+const parseReactMajor = (reactVersion) => {
+	if (typeof reactVersion !== "string") return null;
+	const trimmed = reactVersion.trim();
+	if (trimmed.length === 0) return null;
+	const match = trimmed.match(/(\d+)/);
+	if (!match) return null;
+	const major = Number.parseInt(match[1], 10);
+	if (!Number.isFinite(major) || major <= 0) return null;
+	return major;
+};
+//#endregion
 //#region src/utils/batch-include-paths.ts
 const estimateArgsLength = (args) => args.reduce((total, argument) => total + argument.length + 1, 0);
 const batchIncludePaths = (baseArgs, includePaths) => {
@@ -1596,6 +1933,80 @@ const batchIncludePaths = (baseArgs, includePaths) => {
 	return batches;
 };
 //#endregion
+//#region src/utils/can-oxlint-extend-config.ts
+const EXTENDS_LOCAL_PATH_PREFIXES = [
+	"./",
+	"../",
+	"/"
+];
+const isLocalPathExtend = (entry) => {
+	for (const prefix of EXTENDS_LOCAL_PATH_PREFIXES) if (entry.startsWith(prefix)) return true;
+	return false;
+};
+const stripJsoncComments = (raw) => {
+	let result = "";
+	let cursor = 0;
+	let inString = false;
+	let stringQuote = "";
+	while (cursor < raw.length) {
+		const character = raw[cursor];
+		const nextCharacter = raw[cursor + 1];
+		if (inString) {
+			result += character;
+			if (character === "\\" && cursor + 1 < raw.length) {
+				result += nextCharacter;
+				cursor += 2;
+				continue;
+			}
+			if (character === stringQuote) inString = false;
+			cursor += 1;
+			continue;
+		}
+		if (character === "\"" || character === "'") {
+			inString = true;
+			stringQuote = character;
+			result += character;
+			cursor += 1;
+			continue;
+		}
+		if (character === "/" && nextCharacter === "/") {
+			const lineEndIndex = raw.indexOf("\n", cursor);
+			cursor = lineEndIndex === -1 ? raw.length : lineEndIndex;
+			continue;
+		}
+		if (character === "/" && nextCharacter === "*") {
+			const blockEndIndex = raw.indexOf("*/", cursor + 2);
+			cursor = blockEndIndex === -1 ? raw.length : blockEndIndex + 2;
+			continue;
+		}
+		result += character;
+		cursor += 1;
+	}
+	return result;
+};
+const parseJsonOrJsonc = (raw) => {
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return JSON.parse(stripJsoncComments(raw));
+	}
+};
+const canOxlintExtendConfig = (configPath) => {
+	if (!configPath.endsWith(".eslintrc.json")) return true;
+	let parsed;
+	try {
+		parsed = parseJsonOrJsonc(fs.readFileSync(configPath, "utf-8"));
+	} catch {
+		return true;
+	}
+	if (!isPlainObject(parsed)) return true;
+	const extendsValue = parsed.extends;
+	if (extendsValue === void 0 || extendsValue === null) return true;
+	const extendsEntries = Array.isArray(extendsValue) ? extendsValue : [extendsValue];
+	if (extendsEntries.length === 0) return true;
+	return extendsEntries.some((entry) => typeof entry === "string" && isLocalPathExtend(entry));
+};
+//#endregion
 //#region src/utils/parse-gitattributes-linguist.ts
 const LINGUIST_ATTRIBUTE_PATTERN = /^linguist-(?:vendored|generated)(?:=([a-zA-Z0-9]+))?$/i;
 const FALSY_VALUES = new Set([
@@ -1680,6 +2091,29 @@ const collectIgnorePatterns = (rootDirectory) => {
 	return patterns;
 };
 //#endregion
+//#region src/utils/detect-user-lint-config.ts
+const findFirstLintConfigInDirectory = (directory) => {
+	for (const filename of ADOPTABLE_LINT_CONFIG_FILENAMES) {
+		const candidatePath = path.join(directory, filename);
+		if (isFile(candidatePath)) return candidatePath;
+	}
+	return null;
+};
+const isProjectBoundary = (directory) => fs.existsSync(path.join(directory, ".git")) || isMonorepoRoot(directory);
+const detectUserLintConfigPaths = (rootDirectory) => {
+	const directLintConfig = findFirstLintConfigInDirectory(rootDirectory);
+	if (directLintConfig) return [directLintConfig];
+	if (isProjectBoundary(rootDirectory)) return [];
+	let ancestorDirectory = path.dirname(rootDirectory);
+	while (ancestorDirectory !== path.dirname(ancestorDirectory)) {
+		const ancestorLintConfig = findFirstLintConfigInDirectory(ancestorDirectory);
+		if (ancestorLintConfig) return [ancestorLintConfig];
+		if (isProjectBoundary(ancestorDirectory)) return [];
+		ancestorDirectory = path.dirname(ancestorDirectory);
+	}
+	return [];
+};
+//#endregion
 //#region src/oxlint-config.ts
 const esmRequire$1 = createRequire(import.meta.url);
 const NEXTJS_RULES = {
@@ -1841,18 +2275,27 @@ const BUILTIN_A11Y_RULES = {
 const GLOBAL_REACT_DOCTOR_RULES = {
 	"react-doctor/no-derived-state-effect": "warn",
 	"react-doctor/no-fetch-in-effect": "warn",
+	"react-doctor/no-mirror-prop-effect": "warn",
+	"react-doctor/no-mutable-in-deps": "error",
 	"react-doctor/no-cascading-set-state": "warn",
+	"react-doctor/no-effect-chain": "warn",
 	"react-doctor/no-effect-event-handler": "warn",
 	"react-doctor/no-effect-event-in-deps": "error",
+	"react-doctor/no-event-trigger-state": "warn",
 	"react-doctor/no-prop-callback-in-effect": "warn",
 	"react-doctor/no-derived-useState": "warn",
+	"react-doctor/no-direct-state-mutation": "warn",
+	"react-doctor/no-set-state-in-render": "warn",
+	"react-doctor/prefer-use-effect-event": "warn",
 	"react-doctor/prefer-useReducer": "warn",
+	"react-doctor/prefer-use-sync-external-store": "warn",
 	"react-doctor/rerender-lazy-state-init": "warn",
 	"react-doctor/rerender-functional-setstate": "warn",
 	"react-doctor/rerender-dependencies": "error",
 	"react-doctor/rerender-state-only-in-handlers": "warn",
 	"react-doctor/rerender-defer-reads-hook": "warn",
 	"react-doctor/advanced-event-handler-refs": "warn",
+	"react-doctor/effect-needs-cleanup": "error",
 	"react-doctor/no-giant-component": "warn",
 	"react-doctor/no-render-in-render": "warn",
 	"react-doctor/no-many-boolean-props": "warn",
@@ -1860,6 +2303,10 @@ const GLOBAL_REACT_DOCTOR_RULES = {
 	"react-doctor/no-render-prop-children": "warn",
 	"react-doctor/no-nested-component-definition": "error",
 	"react-doctor/react-compiler-destructure-method": "warn",
+	"react-doctor/no-legacy-class-lifecycles": "error",
+	"react-doctor/no-legacy-context-api": "error",
+	"react-doctor/no-default-props": "warn",
+	"react-doctor/no-react-dom-deprecated-apis": "warn",
 	"react-doctor/no-usememo-simple-expression": "warn",
 	"react-doctor/no-layout-property-animation": "error",
 	"react-doctor/rerender-memo-with-default-value": "warn",
@@ -1908,6 +2355,7 @@ const GLOBAL_REACT_DOCTOR_RULES = {
 	"react-doctor/rendering-conditional-render": "warn",
 	"react-doctor/rendering-svg-precision": "warn",
 	"react-doctor/no-prevent-default": "warn",
+	"react-doctor/no-uncontrolled-input": "warn",
 	"react-doctor/no-document-start-view-transition": "warn",
 	"react-doctor/no-flush-sync": "warn",
 	"react-doctor/server-auth-actions": "error",
@@ -1935,6 +2383,14 @@ const GLOBAL_REACT_DOCTOR_RULES = {
 	"react-doctor/no-disabled-zoom": "error",
 	"react-doctor/no-outline-none": "warn",
 	"react-doctor/no-long-transition-duration": "warn",
+	"react-doctor/design-no-bold-heading": "warn",
+	"react-doctor/design-no-redundant-padding-axes": "warn",
+	"react-doctor/design-no-redundant-size-axes": "warn",
+	"react-doctor/design-no-space-on-flex-children": "warn",
+	"react-doctor/design-no-em-dash-in-jsx-text": "warn",
+	"react-doctor/design-no-three-period-ellipsis": "warn",
+	"react-doctor/design-no-default-tailwind-palette": "warn",
+	"react-doctor/design-no-vague-button-label": "warn",
 	"react-doctor/async-parallel": "warn"
 };
 const ALL_REACT_DOCTOR_RULE_KEYS = new Set([
@@ -1944,10 +2400,38 @@ const ALL_REACT_DOCTOR_RULE_KEYS = new Set([
 	...Object.keys(TANSTACK_START_RULES),
 	...Object.keys(TANSTACK_QUERY_RULES)
 ]);
-const createOxlintConfig = ({ pluginPath, framework, hasReactCompiler, hasTanStackQuery, customRulesOnly = false }) => {
+const VERSION_GATED_RULE_IDS = new Map([
+	["react-doctor/no-react19-deprecated-apis", {
+		minMajor: 19,
+		mode: "deprecation-warning"
+	}],
+	["react-doctor/no-default-props", {
+		minMajor: 19,
+		mode: "deprecation-warning"
+	}],
+	["react-doctor/no-react-dom-deprecated-apis", {
+		minMajor: 18,
+		mode: "deprecation-warning"
+	}],
+	["react-doctor/prefer-use-effect-event", {
+		minMajor: 19,
+		mode: "prefer-newer-api"
+	}]
+]);
+const filterRulesByReactMajor = (rules, reactMajorVersion) => {
+	return Object.fromEntries(Object.entries(rules).filter(([ruleKey]) => {
+		const gate = VERSION_GATED_RULE_IDS.get(ruleKey);
+		if (gate === void 0) return true;
+		if (gate.mode === "deprecation-warning") return true;
+		if (reactMajorVersion === null) return true;
+		return reactMajorVersion >= gate.minMajor;
+	}));
+};
+const createOxlintConfig = ({ pluginPath, framework, hasReactCompiler, hasTanStackQuery, customRulesOnly = false, reactMajorVersion = null, extendsPaths = [] }) => {
 	const reactHooksJsPlugin = resolveReactHooksJsPlugin(hasReactCompiler, customRulesOnly);
 	const reactCompilerRules = reactHooksJsPlugin ? filterRulesToAvailable(REACT_COMPILER_RULES, "react-hooks-js", reactHooksJsPlugin.availableRuleNames) : {};
 	return {
+		...extendsPaths.length > 0 ? { extends: extendsPaths } : {},
 		categories: {
 			correctness: "off",
 			suspicious: "off",
@@ -1963,7 +2447,7 @@ const createOxlintConfig = ({ pluginPath, framework, hasReactCompiler, hasTanSta
 			...customRulesOnly ? {} : BUILTIN_REACT_RULES,
 			...customRulesOnly ? {} : BUILTIN_A11Y_RULES,
 			...reactCompilerRules,
-			...GLOBAL_REACT_DOCTOR_RULES,
+			...filterRulesByReactMajor(GLOBAL_REACT_DOCTOR_RULES, reactMajorVersion),
 			...framework === "nextjs" ? NEXTJS_RULES : {},
 			...framework === "expo" || framework === "react-native" ? REACT_NATIVE_RULES : {},
 			...framework === "tanstack-start" ? TANSTACK_START_RULES : {},
@@ -2075,23 +2559,43 @@ const PLUGIN_CATEGORY_MAP = {
 	"react-hooks-js": "React Compiler",
 	"react-doctor": "Other",
 	"jsx-a11y": "Accessibility",
-	knip: "Dead Code"
+	knip: "Dead Code",
+	eslint: "Correctness",
+	oxc: "Correctness",
+	typescript: "Correctness",
+	unicorn: "Correctness",
+	import: "Bundle Size",
+	promise: "Correctness",
+	n: "Correctness",
+	node: "Correctness",
+	vitest: "Correctness",
+	jest: "Correctness",
+	nextjs: "Next.js"
 };
 const RULE_CATEGORY_MAP = {
 	"react-doctor/no-derived-state-effect": "State & Effects",
 	"react-doctor/no-fetch-in-effect": "State & Effects",
+	"react-doctor/no-mirror-prop-effect": "State & Effects",
+	"react-doctor/no-mutable-in-deps": "State & Effects",
 	"react-doctor/no-cascading-set-state": "State & Effects",
+	"react-doctor/no-effect-chain": "State & Effects",
 	"react-doctor/no-effect-event-handler": "State & Effects",
 	"react-doctor/no-effect-event-in-deps": "State & Effects",
+	"react-doctor/no-event-trigger-state": "State & Effects",
 	"react-doctor/no-prop-callback-in-effect": "State & Effects",
 	"react-doctor/no-derived-useState": "State & Effects",
+	"react-doctor/no-direct-state-mutation": "State & Effects",
+	"react-doctor/no-set-state-in-render": "State & Effects",
+	"react-doctor/prefer-use-effect-event": "State & Effects",
 	"react-doctor/prefer-useReducer": "State & Effects",
+	"react-doctor/prefer-use-sync-external-store": "State & Effects",
 	"react-doctor/rerender-lazy-state-init": "Performance",
 	"react-doctor/rerender-functional-setstate": "Performance",
 	"react-doctor/rerender-dependencies": "State & Effects",
 	"react-doctor/rerender-state-only-in-handlers": "Performance",
 	"react-doctor/rerender-defer-reads-hook": "Performance",
 	"react-doctor/advanced-event-handler-refs": "Performance",
+	"react-doctor/effect-needs-cleanup": "State & Effects",
 	"react-doctor/no-generic-handler-names": "Architecture",
 	"react-doctor/no-giant-component": "Architecture",
 	"react-doctor/no-many-boolean-props": "Architecture",
@@ -2100,6 +2604,10 @@ const RULE_CATEGORY_MAP = {
 	"react-doctor/no-render-in-render": "Architecture",
 	"react-doctor/no-nested-component-definition": "Correctness",
 	"react-doctor/react-compiler-destructure-method": "Architecture",
+	"react-doctor/no-legacy-class-lifecycles": "Correctness",
+	"react-doctor/no-legacy-context-api": "Correctness",
+	"react-doctor/no-default-props": "Architecture",
+	"react-doctor/no-react-dom-deprecated-apis": "Architecture",
 	"react-doctor/no-usememo-simple-expression": "Performance",
 	"react-doctor/no-layout-property-animation": "Performance",
 	"react-doctor/rerender-memo-with-default-value": "Performance",
@@ -2133,6 +2641,7 @@ const RULE_CATEGORY_MAP = {
 	"react-doctor/rendering-conditional-render": "Correctness",
 	"react-doctor/rendering-svg-precision": "Performance",
 	"react-doctor/no-prevent-default": "Correctness",
+	"react-doctor/no-uncontrolled-input": "Correctness",
 	"react-doctor/no-document-start-view-transition": "Correctness",
 	"react-doctor/no-flush-sync": "Performance",
 	"react-doctor/nextjs-no-img-element": "Next.js",
@@ -2182,6 +2691,14 @@ const RULE_CATEGORY_MAP = {
 	"react-doctor/no-disabled-zoom": "Accessibility",
 	"react-doctor/no-outline-none": "Accessibility",
 	"react-doctor/no-long-transition-duration": "Performance",
+	"react-doctor/design-no-bold-heading": "Architecture",
+	"react-doctor/design-no-redundant-padding-axes": "Architecture",
+	"react-doctor/design-no-redundant-size-axes": "Architecture",
+	"react-doctor/design-no-space-on-flex-children": "Architecture",
+	"react-doctor/design-no-em-dash-in-jsx-text": "Architecture",
+	"react-doctor/design-no-three-period-ellipsis": "Architecture",
+	"react-doctor/design-no-default-tailwind-palette": "Architecture",
+	"react-doctor/design-no-vague-button-label": "Accessibility",
 	"react-doctor/js-flatmap-filter": "Performance",
 	"react-doctor/js-combine-iterations": "Performance",
 	"react-doctor/js-tosorted-immutable": "Performance",
@@ -2239,10 +2756,18 @@ const RULE_CATEGORY_MAP = {
 const RULE_HELP_MAP = {
 	"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} />`. See https://react.dev/learn/you-might-not-need-an-effect",
 	"no-fetch-in-effect": "Use `useQuery()` from @tanstack/react-query, `useSWR()`, or fetch in a Server Component instead",
+	"no-mirror-prop-effect": "Delete both the `useState` and the `useEffect` and read the prop directly during render. Mirroring a prop into local state forces a stale first render before the effect re-syncs",
+	"no-mutable-in-deps": "Read mutable values (`location.pathname`, `ref.current`) inside the effect body instead of in the deps array, or subscribe with `useSyncExternalStore`. Mutations to these don't trigger re-renders, so listing them in deps doesn't make the effect react to changes",
 	"no-cascading-set-state": "Combine into useReducer: `const [state, dispatch] = useReducer(reducer, initialState)`",
+	"no-effect-chain": "Compute as much as possible during render (e.g. `const isGameOver = round > 5`) and write all related state inside the event handler that originally fires the chain. Each effect link adds an extra render and makes the code rigid as requirements evolve",
 	"no-effect-event-handler": "Move the conditional logic into onClick, onChange, or onSubmit handlers directly",
+	"no-event-trigger-state": "Delete the trigger state (`useState(null)` plus the `useEffect` that watches it) and call the side-effect (`post(...)` / `navigate(...)` / `track(...)`) directly inside the event handler that previously called the setter. State should not exist purely to schedule effect runs",
 	"no-derived-useState": "Remove useState and compute the value inline: `const value = transform(propName)`",
+	"no-direct-state-mutation": "Replace the mutation with a setter call that produces a new reference: `setItems([...items, newItem])`, `setItems(items.filter(x => x !== target))`, `setItems(items.toSorted(...))`. React only re-renders on a new reference, so in-place updates are silently dropped",
+	"no-set-state-in-render": "Move the setter call into a `useEffect`, an event handler, or replace the state with a value computed during render. Calling a setter at render time triggers another render, which calls the setter again — an infinite loop",
+	"prefer-use-effect-event": "Wrap the callback with `useEffectEvent(callback)` (React 19+) and call the resulting binding from inside the sub-handler. The Effect Event captures the latest props/state without being a reactive dep, so the effect doesn't re-subscribe on every parent render. See https://react.dev/reference/react/useEffectEvent",
 	"prefer-useReducer": "Group related state: `const [state, dispatch] = useReducer(reducer, { field1, field2, ... })`",
+	"prefer-use-sync-external-store": "Replace the `useState(getSnapshot())` + `useEffect(() => store.subscribe(() => setSnapshot(getSnapshot())))` pair with `useSyncExternalStore(store.subscribe, getSnapshot)`. The hook handles tearing during concurrent renders and SSR snapshots; the manual subscribe pattern doesn't",
 	"rerender-lazy-state-init": "Wrap in an arrow function so it only runs once: `useState(() => expensiveComputation())`",
 	"rerender-functional-setstate": "Use the callback form: `setState(prev => prev + 1)` to always read the latest value",
 	"rerender-dependencies": "Extract to a useMemo, useRef, or module-level constant so the reference is stable",
@@ -2251,7 +2776,11 @@ const RULE_HELP_MAP = {
 	"no-generic-handler-names": "Rename to describe the action: e.g. `handleSubmit` → `saveUserProfile`, `handleClick` → `toggleSidebar`",
 	"no-giant-component": "Extract logical sections into focused components: `<UserHeader />`, `<UserActions />`, etc.",
 	"no-many-boolean-props": "Split into compound components or named variants: `<Button.Primary />`, `<DialogConfirm />` instead of stacking `isPrimary`, `isConfirm` flags",
-	"no-react19-deprecated-apis": "Pass `ref` as a regular prop on function components — `forwardRef` is no longer needed in React 19+. Replace `useContext(X)` with `use(X)` for branch-aware context reads.",
+	"no-react19-deprecated-apis": "Pass `ref` as a regular prop on function components — `forwardRef` is no longer needed in React 19+. Replace `useContext(X)` with `use(X)` for branch-aware context reads. Only enabled on projects detected as React 19+.",
+	"no-legacy-class-lifecycles": "Move side effects in `componentWillMount` to `componentDidMount`; replace `componentWillReceiveProps` with `componentDidUpdate` (compare prevProps) or the static `getDerivedStateFromProps` for pure state derivation; replace `componentWillUpdate` with `getSnapshotBeforeUpdate` paired with `componentDidUpdate`. The `UNSAFE_` prefix only silences the warning — React 19 removes both forms.",
+	"no-legacy-context-api": "Replace `childContextTypes` + `getChildContext` with `const MyContext = createContext(...)` + `<MyContext.Provider value={...}>`; replace `contextTypes` with `static contextType = MyContext` (single context) or `useContext()` / `use()` from a function component. The provider and every consumer must migrate together — partial migrations leave consumers reading the wrong context.",
+	"no-default-props": "React 19 removes `Component.defaultProps` for function components. Move the defaults into the destructured props parameter: `function Foo({ size = \"md\", variant = \"primary\" })` instead of `Foo.defaultProps = { size: \"md\", variant: \"primary\" }`.",
+	"no-react-dom-deprecated-apis": "Switch the legacy `react-dom` root API (`render` / `hydrate` / `unmountComponentAtNode`) to `createRoot` / `hydrateRoot` / `root.unmount()` from `react-dom/client`. Replace `findDOMNode` with a ref. The whole `react-dom/test-utils` entry point is removed in React 19 — use `act` from `react` and `fireEvent` / `render` from `@testing-library/react`. Only enabled on projects detected as React 18+.",
 	"no-render-prop-children": "Replace `renderXxx` props with compound subcomponents (e.g. `<Modal.Header>`) or `children` so the parent doesn't dictate every customization point",
 	"no-render-in-render": "Extract to a named component: `const ListItem = ({ item }) => <div>{item.name}</div>`",
 	"no-nested-component-definition": "Move to a separate file or to module scope above the parent component",
@@ -2266,6 +2795,7 @@ const RULE_HELP_MAP = {
 	"rerender-defer-reads-hook": "Read the URL state inside the handler (e.g. `new URL(window.location.href).searchParams`) so the component doesn't subscribe and re-render on every URL change",
 	"rerender-derived-state-from-hook": "Use a threshold/media-query hook (e.g. `useMediaQuery(\"(max-width: 767px)\")`) — the component re-renders only when the threshold flips, not every pixel",
 	"advanced-event-handler-refs": "Store the handler in a ref and have the listener read `handlerRef.current()` — the subscription stays put while the latest handler is always called",
+	"effect-needs-cleanup": "Return a cleanup function that releases the subscription / timer: `return () => target.removeEventListener(name, handler)` for listeners, `return () => clearInterval(id)` / `clearTimeout(id)` for timers, or `return unsubscribe` if the subscribe call already returned one",
 	"async-defer-await": "Move the `await` after the synchronous early-return guard so the skip path stays fast",
 	"async-await-in-loop": "Collect the items and use `await Promise.all(items.map(...))` to run independent operations concurrently",
 	"react-compiler-destructure-method": "Destructure the method up front: `const { push } = useRouter()` then call `push(...)` directly — clearer dependency graph and easier for React Compiler to memoize",
@@ -2312,9 +2842,18 @@ const RULE_HELP_MAP = {
 	"no-disabled-zoom": "Remove `user-scalable=no` and `maximum-scale` from the viewport meta tag. If your layout breaks at 200% zoom, fix the layout — don't punish users with disabilities",
 	"no-outline-none": "Use `:focus-visible { outline: 2px solid var(--color-accent); outline-offset: 2px }` to show focus only for keyboard users while hiding it for mouse clicks",
 	"no-long-transition-duration": "Keep UI transitions under 1s — 100-150ms for instant feedback, 200-300ms for state changes, 300-500ms for layout changes. Use longer durations only for page-load hero animations",
+	"design-no-bold-heading": "Use `font-semibold` (600) or `font-medium` (500) on headings — 700+ crushes letter counter shapes at display sizes",
+	"design-no-redundant-padding-axes": "Collapse `px-N py-N` to `p-N` when both axes match. Keep them split only when one axis varies at a breakpoint (`py-2 md:py-3`)",
+	"design-no-redundant-size-axes": "Collapse `w-N h-N` to `size-N` (Tailwind v3.4+) when both axes match",
+	"design-no-space-on-flex-children": "Use `gap-*` on the flex/grid parent. `space-x-*` / `space-y-*` produce phantom gaps when a sibling is conditionally rendered, lose vertical spacing on wrapped lines, and don't mirror in RTL",
+	"design-no-em-dash-in-jsx-text": "Replace em dashes in JSX text with commas, colons, semicolons, periods, or parentheses — em dashes read as model-output filler",
+	"design-no-three-period-ellipsis": "Use the typographic ellipsis \"…\" (or `&hellip;`) instead of three periods — pairs with action-with-followup labels (\"Rename…\", \"Loading…\")",
+	"design-no-default-tailwind-palette": "Replace `indigo-*` / `gray-*` / `slate-*` with project tokens, your brand color, or a less-default neutral (`zinc`, `neutral`, `stone`)",
+	"design-no-vague-button-label": "Name the action: \"Save changes\" instead of \"Continue\", \"Send invite\" instead of \"Submit\", \"Delete account\" instead of \"OK\". The label IS the button's accessible name",
 	"no-array-index-as-key": "Use a stable unique identifier: `key={item.id}` or `key={item.slug}` — index keys break on reorder/filter",
 	"rendering-conditional-render": "Change to `{items.length > 0 && <List />}` or use a ternary: `{items.length ? <List /> : null}`",
 	"no-prevent-default": "Use `<form action={serverAction}>` (works without JS) or `<button>` instead of `<a>` with preventDefault",
+	"no-uncontrolled-input": "Pass an explicit initial value to `useState` (e.g. `useState(\"\")` instead of `useState()`), add `onChange` (or `readOnly` to opt out) when you supply `value`, and drop `defaultValue` on controlled inputs — React ignores it",
 	"nextjs-no-img-element": "`import Image from 'next/image'` — provides automatic WebP/AVIF, lazy loading, and responsive srcset",
 	"nextjs-async-client-component": "Fetch data in a parent Server Component and pass it as props, or use useQuery/useSWR in the client component",
 	"nextjs-no-a-element": "`import Link from 'next/link'` — enables client-side navigation, prefetching, and preserves scroll position",
@@ -2397,6 +2936,7 @@ const RULE_HELP_MAP = {
 };
 const FILEPATH_WITH_LOCATION_PATTERN = /\S+\.\w+:\d+:\d+[\s\S]*$/;
 const REACT_COMPILER_MESSAGE = "React Compiler can't optimize this code";
+const lookupOwnString = (record, key) => Object.hasOwn(record, key) ? record[key] : void 0;
 const cleanDiagnosticMessage = (message, help, plugin, rule) => {
 	if (plugin === "react-hooks-js") return {
 		message: REACT_COMPILER_MESSAGE,
@@ -2404,7 +2944,7 @@ const cleanDiagnosticMessage = (message, help, plugin, rule) => {
 	};
 	return {
 		message: message.replace(FILEPATH_WITH_LOCATION_PATTERN, "").trim() || message,
-		help: help || RULE_HELP_MAP[rule] || ""
+		help: help || lookupOwnString(RULE_HELP_MAP, rule) || ""
 	};
 };
 const parseRuleCode = (code) => {
@@ -2432,7 +2972,7 @@ const resolvePluginPath = () => {
 	return pluginPath;
 };
 const resolveDiagnosticCategory = (plugin, rule) => {
-	return RULE_CATEGORY_MAP[`${plugin}/${rule}`] ?? PLUGIN_CATEGORY_MAP[plugin] ?? "Other";
+	return lookupOwnString(RULE_CATEGORY_MAP, `${plugin}/${rule}`) ?? lookupOwnString(PLUGIN_CATEGORY_MAP, plugin) ?? "Other";
 };
 const SANITIZED_ENV = (() => {
 	const sanitized = {};
@@ -2523,7 +3063,7 @@ const parseOxlintOutput = (stdout) => {
 		throw new Error(`Failed to parse oxlint output: ${stdout.slice(0, 200)}`);
 	}
 	if (!isOxlintOutput(parsed)) throw new Error(`Unexpected oxlint output shape: ${stdout.slice(0, 200)}`);
-	return parsed.diagnostics.filter((diagnostic) => diagnostic.code && JSX_FILE_PATTERN.test(diagnostic.filename)).map((diagnostic) => {
+	return parsed.diagnostics.filter((diagnostic) => diagnostic.code && SOURCE_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);
@@ -2553,8 +3093,8 @@ const validateRuleRegistration = () => {
 	const missingCategory = [];
 	for (const fullKey of ALL_REACT_DOCTOR_RULE_KEYS) {
 		const ruleName = fullKey.replace(/^react-doctor\//, "");
-		if (!(fullKey in RULE_CATEGORY_MAP)) missingCategory.push(fullKey);
-		if (!(ruleName in RULE_HELP_MAP)) missingHelp.push(fullKey);
+		if (!Object.hasOwn(RULE_CATEGORY_MAP, fullKey)) missingCategory.push(fullKey);
+		if (!Object.hasOwn(RULE_HELP_MAP, ruleName)) missingHelp.push(fullKey);
 	}
 	if (missingCategory.length > 0 || missingHelp.length > 0) {
 		const detail = [missingCategory.length > 0 ? `Missing RULE_CATEGORY_MAP entries: ${missingCategory.join(", ")}` : null, missingHelp.length > 0 ? `Missing RULE_HELP_MAP entries: ${missingHelp.join(", ")}` : null].filter((entry) => entry !== null).join("; ");
@@ -2562,26 +3102,24 @@ const validateRuleRegistration = () => {
 	}
 };
 const runOxlint = async (options) => {
-	const { rootDirectory, hasTypeScript, framework, hasReactCompiler, hasTanStackQuery, includePaths, nodeBinaryPath = process.execPath, customRulesOnly = false, respectInlineDisables = true } = options;
+	const { rootDirectory, hasTypeScript, framework, hasReactCompiler, hasTanStackQuery, reactMajorVersion = null, includePaths, nodeBinaryPath = process.execPath, customRulesOnly = false, respectInlineDisables = true, adoptExistingLintConfig = true } = options;
 	validateRuleRegistration();
 	if (includePaths !== void 0 && includePaths.length === 0) return [];
 	const configDirectory = fs.mkdtempSync(path.join(os.tmpdir(), "react-doctor-oxlintrc-"));
 	const configPath = path.join(configDirectory, "oxlintrc.json");
+	const pluginPath = resolvePluginPath();
+	const extendsPaths = (adoptExistingLintConfig && !customRulesOnly ? detectUserLintConfigPaths(rootDirectory) : []).filter(canOxlintExtendConfig);
 	const config = createOxlintConfig({
-		pluginPath: resolvePluginPath(),
+		pluginPath,
 		framework,
 		hasReactCompiler,
 		hasTanStackQuery,
-		customRulesOnly
+		customRulesOnly,
+		reactMajorVersion,
+		extendsPaths
 	});
 	const restoreDisableDirectives = respectInlineDisables ? () => {} : neutralizeDisableDirectives(rootDirectory, includePaths);
 	try {
-		const fileHandle = fs.openSync(configPath, "wx", 384);
-		try {
-			fs.writeFileSync(fileHandle, JSON.stringify(config));
-		} finally {
-			fs.closeSync(fileHandle);
-		}
 		const baseArgs = [
 			resolveOxlintBinary(),
 			"-c",
@@ -2600,12 +3138,39 @@ const runOxlint = async (options) => {
 			baseArgs.push("--ignore-path", combinedIgnorePath);
 		}
 		const fileBatches = includePaths !== void 0 ? batchIncludePaths(baseArgs, includePaths) : [["."]];
-		const allDiagnostics = [];
-		for (const batch of fileBatches) {
-			const stdout = await spawnOxlint([...baseArgs, ...batch], rootDirectory, nodeBinaryPath);
-			allDiagnostics.push(...parseOxlintOutput(stdout));
+		const writeOxlintConfig = (configToWrite) => {
+			fs.rmSync(configPath, { force: true });
+			const fileHandle = fs.openSync(configPath, "wx", 384);
+			try {
+				fs.writeFileSync(fileHandle, JSON.stringify(configToWrite));
+			} finally {
+				fs.closeSync(fileHandle);
+			}
+		};
+		const spawnLintBatches = async () => {
+			const allDiagnostics = [];
+			for (const batch of fileBatches) {
+				const stdout = await spawnOxlint([...baseArgs, ...batch], rootDirectory, nodeBinaryPath);
+				allDiagnostics.push(...parseOxlintOutput(stdout));
+			}
+			return allDiagnostics;
+		};
+		writeOxlintConfig(config);
+		try {
+			return await spawnLintBatches();
+		} catch (error) {
+			if (extendsPaths.length === 0) throw error;
+			writeOxlintConfig(createOxlintConfig({
+				pluginPath,
+				framework,
+				hasReactCompiler,
+				hasTanStackQuery,
+				customRulesOnly,
+				reactMajorVersion,
+				extendsPaths: []
+			}));
+			return await spawnLintBatches();
 		}
-		return allDiagnostics;
 	} finally {
 		restoreDisableDirectives();
 		fs.rmSync(configDirectory, {
@@ -2621,35 +3186,90 @@ const SEVERITY_ORDER = {
 	warning: 1
 };
 const colorizeBySeverity = (text, severity) => severity === "error" ? highlighter.error(text) : highlighter.warn(text);
-const sortBySeverity = (diagnosticGroups) => diagnosticGroups.toSorted(([, diagnosticsA], [, diagnosticsB]) => {
-	return SEVERITY_ORDER[diagnosticsA[0].severity] - SEVERITY_ORDER[diagnosticsB[0].severity];
+const sortByImportance = (diagnosticGroups) => diagnosticGroups.toSorted(([, diagnosticsA], [, diagnosticsB]) => {
+	const severityDelta = SEVERITY_ORDER[diagnosticsA[0].severity] - SEVERITY_ORDER[diagnosticsB[0].severity];
+	if (severityDelta !== 0) return severityDelta;
+	return diagnosticsB.length - diagnosticsA.length;
 });
 const collectAffectedFiles = (diagnostics) => new Set(diagnostics.map((diagnostic) => diagnostic.filePath));
-const buildFileLineMap = (diagnostics) => {
-	const fileLines = /* @__PURE__ */ new Map();
+const buildVerboseSiteMap = (diagnostics) => {
+	const fileSites = /* @__PURE__ */ new Map();
 	for (const diagnostic of diagnostics) {
-		const lines = fileLines.get(diagnostic.filePath) ?? [];
-		if (diagnostic.line > 0) lines.push(diagnostic.line);
-		fileLines.set(diagnostic.filePath, lines);
-	}
-	return fileLines;
-};
-const printDiagnostics = (diagnostics, isVerbose) => {
-	const sortedRuleGroups = sortBySeverity([...groupBy(diagnostics, (diagnostic) => `${diagnostic.plugin}/${diagnostic.rule}`).entries()]);
-	for (const [, ruleDiagnostics] of sortedRuleGroups) {
-		const firstDiagnostic = ruleDiagnostics[0];
-		const icon = colorizeBySeverity(firstDiagnostic.severity === "error" ? "✗" : "⚠", firstDiagnostic.severity);
-		const count = ruleDiagnostics.length;
-		const countLabel = count > 1 ? colorizeBySeverity(` (${count})`, firstDiagnostic.severity) : "";
-		logger.log(`  ${icon} ${firstDiagnostic.message}${countLabel}`);
-		if (firstDiagnostic.help) logger.dim(indentMultilineText(firstDiagnostic.help, "    "));
+		const sites = fileSites.get(diagnostic.filePath) ?? [];
+		if (diagnostic.line > 0) sites.push({
+			line: diagnostic.line,
+			suppressionHint: diagnostic.suppressionHint
+		});
+		fileSites.set(diagnostic.filePath, sites);
+	}
+	return fileSites;
+};
+const formatSiteCountBadge = (count) => count > 1 ? `×${count}` : "";
+const computeRuleNameColumnWidth = (ruleKeys) => {
+	const longestRuleNameLength = ruleKeys.reduce((longest, ruleKey) => Math.max(longest, ruleKey.length), 0);
+	return Math.max(36, longestRuleNameLength);
+};
+const padRuleNameToColumn = (ruleName, columnWidth) => {
+	if (ruleName.length >= columnWidth) return ruleName;
+	return ruleName + " ".repeat(columnWidth - ruleName.length);
+};
+const grayLine = (text) => {
+	logger.log(highlighter.gray(text));
+};
+const printCompactRuleGroupLine = (ruleKey, ruleDiagnostics, ruleNameColumnWidth) => {
+	const firstDiagnostic = ruleDiagnostics[0];
+	const icon = colorizeBySeverity(firstDiagnostic.severity === "error" ? "✗" : "⚠", firstDiagnostic.severity);
+	const siteCountBadge = formatSiteCountBadge(ruleDiagnostics.length);
+	const ruleNameRendering = siteCountBadge.length > 0 ? colorizeBySeverity(padRuleNameToColumn(ruleKey, ruleNameColumnWidth), firstDiagnostic.severity) : colorizeBySeverity(ruleKey, firstDiagnostic.severity);
+	const trailingBadge = siteCountBadge.length > 0 ? ` ${highlighter.gray(siteCountBadge)}` : "";
+	logger.log(`  ${icon} ${ruleNameRendering}${trailingBadge}`);
+};
+const printDetailedRuleGroup = (ruleKey, ruleDiagnostics, rootDirectory, ruleNameColumnWidth) => {
+	printCompactRuleGroupLine(ruleKey, ruleDiagnostics, ruleNameColumnWidth);
+	const firstDiagnostic = ruleDiagnostics[0];
+	grayLine(indentMultilineText(firstDiagnostic.message, "      "));
+	if (firstDiagnostic.help) grayLine(indentMultilineText(`→ ${firstDiagnostic.help}`, "      "));
+	const firstLocation = ruleDiagnostics.find((diagnostic) => diagnostic.line > 0);
+	if (firstLocation) grayLine(`      ${toRelativePath(firstLocation.filePath, rootDirectory)}:${firstLocation.line}`);
+	logger.break();
+};
+const printVerboseRuleGroup = (ruleKey, ruleDiagnostics, ruleNameColumnWidth) => {
+	printCompactRuleGroupLine(ruleKey, ruleDiagnostics, ruleNameColumnWidth);
+	const firstDiagnostic = ruleDiagnostics[0];
+	grayLine(indentMultilineText(firstDiagnostic.message, "      "));
+	if (firstDiagnostic.help) grayLine(indentMultilineText(`→ ${firstDiagnostic.help}`, "      "));
+	const fileSites = buildVerboseSiteMap(ruleDiagnostics);
+	for (const [filePath, sites] of fileSites) if (sites.length > 0) for (const site of sites) {
+		grayLine(`      ${filePath}:${site.line}`);
+		if (site.suppressionHint) grayLine(`        ↳ ${site.suppressionHint}`);
+	}
+	else grayLine(`      ${filePath}`);
+	logger.break();
+};
+const printDiagnostics = (diagnostics, isVerbose, rootDirectory) => {
+	const sortedRuleGroups = sortByImportance([...groupBy(diagnostics, (diagnostic) => `${diagnostic.plugin}/${diagnostic.rule}`).entries()]);
+	const visibleRuleGroups = isVerbose ? sortedRuleGroups : sortedRuleGroups.slice(0, 5);
+	const hiddenRuleGroups = isVerbose ? [] : sortedRuleGroups.slice(5);
+	const ruleNameColumnWidth = computeRuleNameColumnWidth(visibleRuleGroups.map(([ruleKey]) => ruleKey));
+	visibleRuleGroups.forEach(([ruleKey, ruleDiagnostics], visibleIndex) => {
 		if (isVerbose) {
-			const fileLines = buildFileLineMap(ruleDiagnostics);
-			for (const [filePath, lines] of fileLines) if (lines.length > 0) for (const line of lines) logger.dim(`  ${filePath}:${line}`);
-			else logger.dim(`  ${filePath}`);
+			printVerboseRuleGroup(ruleKey, ruleDiagnostics, ruleNameColumnWidth);
+			return;
 		}
-		logger.break();
-	}
+		if (visibleIndex < 1) {
+			printDetailedRuleGroup(ruleKey, ruleDiagnostics, rootDirectory, ruleNameColumnWidth);
+			return;
+		}
+		printCompactRuleGroupLine(ruleKey, ruleDiagnostics, ruleNameColumnWidth);
+	});
+	if (visibleRuleGroups.length > 1 && !isVerbose) logger.break();
+	if (hiddenRuleGroups.length > 0) printHiddenDiagnosticsSummary(hiddenRuleGroups);
+};
+const printHiddenDiagnosticsSummary = (hiddenRuleGroups) => {
+	const renderedParts = buildHiddenDiagnosticsSummary(hiddenRuleGroups.flatMap(([, ruleDiagnostics]) => ruleDiagnostics)).map((part) => colorizeBySeverity(part.text, part.severity));
+	logger.log(`  ${renderedParts.join("  ")}`);
+	grayLine("    Run `npx react-doctor@latest . --verbose` to get all details");
+	logger.break();
 };
 const formatElapsedTime = (elapsedMilliseconds) => {
 	if (elapsedMilliseconds < 1e3) return `${Math.round(elapsedMilliseconds)}ms`;
@@ -2657,7 +3277,6 @@ const formatElapsedTime = (elapsedMilliseconds) => {
 };
 const formatRuleSummary = (ruleKey, ruleDiagnostics) => {
 	const firstDiagnostic = ruleDiagnostics[0];
-	const fileLines = buildFileLineMap(ruleDiagnostics);
 	const sections = [
 		`Rule: ${ruleKey}`,
 		`Severity: ${firstDiagnostic.severity}`,
@@ -2668,14 +3287,18 @@ const formatRuleSummary = (ruleKey, ruleDiagnostics) => {
 	];
 	if (firstDiagnostic.help) sections.push("", `Suggestion: ${firstDiagnostic.help}`);
 	sections.push("", "Files:");
-	for (const [filePath, lines] of fileLines) if (lines.length > 0) for (const line of lines) sections.push(`  ${filePath}:${line}`);
+	const fileSites = buildVerboseSiteMap(ruleDiagnostics);
+	for (const [filePath, sites] of fileSites) if (sites.length > 0) for (const site of sites) {
+		sections.push(`  ${filePath}:${site.line}`);
+		if (site.suppressionHint) sections.push(`    ${site.suppressionHint}`);
+	}
 	else sections.push(`  ${filePath}`);
 	return sections.join("\n") + "\n";
 };
 const writeDiagnosticsDirectory = (diagnostics) => {
 	const outputDirectory = join(tmpdir(), `react-doctor-${randomUUID()}`);
 	mkdirSync(outputDirectory, { recursive: true });
-	const sortedRuleGroups = sortBySeverity([...groupBy(diagnostics, (diagnostic) => `${diagnostic.plugin}/${diagnostic.rule}`).entries()]);
+	const sortedRuleGroups = sortByImportance([...groupBy(diagnostics, (diagnostic) => `${diagnostic.plugin}/${diagnostic.rule}`).entries()]);
 	for (const [ruleKey, ruleDiagnostics] of sortedRuleGroups) writeFileSync(join(outputDirectory, ruleKey.replace(/\//g, "--") + ".txt"), formatRuleSummary(ruleKey, ruleDiagnostics));
 	writeFileSync(join(outputDirectory, "diagnostics.json"), JSON.stringify(diagnostics));
 	return outputDirectory;
@@ -2688,37 +3311,76 @@ const buildScoreBarSegments = (score) => {
 		emptySegment: "░".repeat(emptyCount)
 	};
 };
-const buildPlainScoreBar = (score) => {
-	const { filledSegment, emptySegment } = buildScoreBarSegments(score);
-	return `${filledSegment}${emptySegment}`;
-};
 const buildScoreBar = (score) => {
 	const { filledSegment, emptySegment } = buildScoreBarSegments(score);
 	return colorizeByScore(filledSegment, score) + highlighter.dim(emptySegment);
 };
-const printScoreGauge = (score, label) => {
-	const scoreDisplay = colorizeByScore(`${score}`, score);
-	const labelDisplay = colorizeByScore(label, score);
-	logger.log(`  ${scoreDisplay} / 100  ${labelDisplay}`);
-	logger.break();
-	logger.log(`  ${buildScoreBar(score)}`);
-	logger.break();
-};
 const getDoctorFace = (score) => {
 	if (score >= 75) return ["◠ ◠", " ▽ "];
 	if (score >= 50) return ["• •", " ─ "];
 	return ["x x", " ▽ "];
 };
-const printBranding = (score) => {
-	if (score !== void 0) {
-		const [eyes, mouth] = getDoctorFace(score);
-		const colorize = (text) => colorizeByScore(text, score);
-		logger.log(colorize("  ┌─────┐"));
-		logger.log(colorize(`  │ ${eyes} │`));
-		logger.log(colorize(`  │ ${mouth} │`));
-		logger.log(colorize("  └─────┘"));
+const BRANDING_LINE = `React Doctor ${highlighter.dim("(www.react.doctor)")}`;
+const buildFaceRenderedLines = (score) => {
+	const [eyes, mouth] = getDoctorFace(score);
+	const colorize = (text) => colorizeByScore(text, score);
+	return [
+		"┌─────┐",
+		`│ ${eyes} │`,
+		`│ ${mouth} │`,
+		"└─────┘"
+	].map(colorize);
+};
+const printScoreHeader = (scoreResult) => {
+	const renderedFaceLines = buildFaceRenderedLines(scoreResult.score);
+	const scoreNumber = colorizeByScore(`${scoreResult.score}`, scoreResult.score);
+	const scoreLabel = colorizeByScore(scoreResult.label, scoreResult.score);
+	const rightColumnLines = [
+		`${scoreNumber} ${highlighter.dim(`/ 100`)} ${scoreLabel}`,
+		buildScoreBar(scoreResult.score),
+		BRANDING_LINE,
+		""
+	];
+	for (let lineIndex = 0; lineIndex < renderedFaceLines.length; lineIndex += 1) {
+		const rightColumnContent = rightColumnLines[lineIndex] ?? "";
+		const separator = rightColumnContent.length > 0 ? "  " : "";
+		logger.log(`  ${renderedFaceLines[lineIndex]}${separator}${rightColumnContent}`);
+	}
+	logger.break();
+};
+const printBrandingOnlyHeader = () => {
+	logger.log(`  ${BRANDING_LINE}`);
+	logger.break();
+};
+const printNoScoreHeader = (noScoreMessage) => {
+	logger.log(`  ${BRANDING_LINE}`);
+	logger.log(`  ${highlighter.gray(noScoreMessage)}`);
+	logger.break();
+};
+const buildCategoryBar = (count, maximumCount, useErrorColor) => {
+	if (maximumCount === 0) return highlighter.dim("░".repeat(16));
+	const filledCount = Math.max(1, Math.round(count / maximumCount * 16));
+	const cappedFilledCount = Math.min(filledCount, 16);
+	const emptyCount = 16 - cappedFilledCount;
+	const filledSegment = "█".repeat(cappedFilledCount);
+	const emptySegment = "░".repeat(emptyCount);
+	return `${useErrorColor ? highlighter.error(filledSegment) : highlighter.warn(filledSegment)}${highlighter.dim(emptySegment)}`;
+};
+const padCategoryLabel = (categoryLabel) => {
+	if (categoryLabel.length >= 18) return categoryLabel;
+	return categoryLabel + " ".repeat(18 - categoryLabel.length);
+};
+const printCategoryBreakdown = (entries) => {
+	if (entries.length === 0) return;
+	const maximumCount = Math.max(...entries.map((entry) => entry.totalCount));
+	logger.dim("  By category");
+	for (const entry of entries) {
+		const paddedLabel = padCategoryLabel(entry.category);
+		const categoryBar = buildCategoryBar(entry.totalCount, maximumCount, entry.errorCount > 0);
+		const totalCountDisplay = String(entry.totalCount);
+		const errorBadge = entry.errorCount > 0 ? ` ${highlighter.error(`${entry.errorCount}×`)}` : "";
+		logger.log(`    ${paddedLabel}${categoryBar} ${totalCountDisplay}${errorBadge}`);
 	}
-	logger.log(`  React Doctor ${highlighter.dim("(www.react.doctor)")}`);
 	logger.break();
 };
 const buildShareUrl = (diagnostics, scoreResult, projectName) => {
@@ -2733,67 +3395,31 @@ const buildShareUrl = (diagnostics, scoreResult, projectName) => {
 	if (affectedFileCount > 0) params.set("f", String(affectedFileCount));
 	return `${SHARE_BASE_URL}?${params.toString()}`;
 };
-const buildBrandingLines = (scoreResult, noScoreMessage) => {
-	const lines = [];
-	if (scoreResult) {
-		const [eyes, mouth] = getDoctorFace(scoreResult.score);
-		const scoreColorizer = (text) => colorizeByScore(text, scoreResult.score);
-		lines.push(createFramedLine("┌─────┐", scoreColorizer("┌─────┐")));
-		lines.push(createFramedLine(`│ ${eyes} │`, scoreColorizer(`│ ${eyes} │`)));
-		lines.push(createFramedLine(`│ ${mouth} │`, scoreColorizer(`│ ${mouth} │`)));
-		lines.push(createFramedLine("└─────┘", scoreColorizer("└─────┘")));
-		lines.push(createFramedLine("React Doctor (www.react.doctor)", `React Doctor ${highlighter.dim("(www.react.doctor)")}`));
-		lines.push(createFramedLine(""));
-		const scoreLinePlainText = `${scoreResult.score} / 100  ${scoreResult.label}`;
-		const scoreLineRenderedText = `${colorizeByScore(String(scoreResult.score), scoreResult.score)} / 100  ${colorizeByScore(scoreResult.label, scoreResult.score)}`;
-		lines.push(createFramedLine(scoreLinePlainText, scoreLineRenderedText));
-		lines.push(createFramedLine(""));
-		lines.push(createFramedLine(buildPlainScoreBar(scoreResult.score), buildScoreBar(scoreResult.score)));
-		lines.push(createFramedLine(""));
-	} else {
-		lines.push(createFramedLine("React Doctor (www.react.doctor)", `React Doctor ${highlighter.dim("(www.react.doctor)")}`));
-		lines.push(createFramedLine(""));
-		lines.push(createFramedLine(noScoreMessage, highlighter.dim(noScoreMessage)));
-		lines.push(createFramedLine(""));
-	}
-	return lines;
-};
-const buildCountsSummaryLine = (diagnostics, totalSourceFileCount, elapsedMilliseconds) => {
+const printCountsSummaryLine = (diagnostics, totalSourceFileCount, elapsedMilliseconds) => {
 	const errorCount = diagnostics.filter((diagnostic) => diagnostic.severity === "error").length;
 	const warningCount = diagnostics.filter((diagnostic) => diagnostic.severity === "warning").length;
 	const affectedFileCount = collectAffectedFiles(diagnostics).size;
-	const elapsed = formatElapsedTime(elapsedMilliseconds);
-	const plainParts = [];
-	const renderedParts = [];
-	if (errorCount > 0) {
-		const errorText = `✗ ${errorCount} error${errorCount === 1 ? "" : "s"}`;
-		plainParts.push(errorText);
-		renderedParts.push(highlighter.error(errorText));
-	}
-	if (warningCount > 0) {
-		const warningText = `⚠ ${warningCount} warning${warningCount === 1 ? "" : "s"}`;
-		plainParts.push(warningText);
-		renderedParts.push(highlighter.warn(warningText));
-	}
+	const totalIssueCount = diagnostics.length;
+	const elapsedTimeLabel = formatElapsedTime(elapsedMilliseconds);
+	const issueCountColor = errorCount > 0 ? highlighter.error : warningCount > 0 ? highlighter.warn : highlighter.dim;
+	const issueCountText = `${totalIssueCount} ${totalIssueCount === 1 ? "issue" : "issues"}`;
 	const fileCountText = totalSourceFileCount > 0 ? `across ${affectedFileCount}/${totalSourceFileCount} files` : `across ${affectedFileCount} file${affectedFileCount === 1 ? "" : "s"}`;
-	const elapsedTimeText = `in ${elapsed}`;
-	plainParts.push(fileCountText, elapsedTimeText);
-	renderedParts.push(highlighter.dim(fileCountText), highlighter.dim(elapsedTimeText));
-	return createFramedLine(plainParts.join("  "), renderedParts.join("  "));
+	const elapsedTimeText = `in ${elapsedTimeLabel}`;
+	logger.log(`  ${issueCountColor(issueCountText)} ${highlighter.dim(`${fileCountText}  ${elapsedTimeText}`)}`);
 };
 const printSummary = (diagnostics, elapsedMilliseconds, scoreResult, projectName, totalSourceFileCount, noScoreMessage, isOffline) => {
-	printFramedBox([...buildBrandingLines(scoreResult, noScoreMessage), buildCountsSummaryLine(diagnostics, totalSourceFileCount, elapsedMilliseconds)]);
+	printCategoryBreakdown(buildCategoryBreakdown(diagnostics));
+	if (scoreResult) printScoreHeader(scoreResult);
+	else printNoScoreHeader(noScoreMessage);
+	printCountsSummaryLine(diagnostics, totalSourceFileCount, elapsedMilliseconds);
 	try {
 		const diagnosticsDirectory = writeDiagnosticsDirectory(diagnostics);
-		logger.break();
-		logger.dim(`  Full diagnostics written to ${diagnosticsDirectory}`);
-	} catch {
-		logger.break();
-	}
+		logger.log(highlighter.gray(`  Full diagnostics written to ${diagnosticsDirectory}`));
+	} catch {}
 	if (!isOffline) {
-		const shareUrl = buildShareUrl(diagnostics, scoreResult, projectName);
 		logger.break();
-		logger.dim(`  Share your results: ${highlighter.info(shareUrl)}`);
+		const shareUrl = buildShareUrl(diagnostics, scoreResult, projectName);
+		logger.log(`  ${highlighter.bold("→ Share your results:")} ${highlighter.info(shareUrl)}`);
 	}
 };
 const resolveOxlintNode = async (isLintEnabled, isQuiet) => {
@@ -2844,7 +3470,8 @@ const mergeScanOptions = (inputOptions, userConfig) => ({
 	includePaths: inputOptions.includePaths ?? [],
 	customRulesOnly: userConfig?.customRulesOnly ?? false,
 	share: userConfig?.share ?? true,
-	respectInlineDisables: inputOptions.respectInlineDisables ?? userConfig?.respectInlineDisables ?? true
+	respectInlineDisables: inputOptions.respectInlineDisables ?? userConfig?.respectInlineDisables ?? true,
+	adoptExistingLintConfig: userConfig?.adoptExistingLintConfig ?? true
 });
 const printProjectDetection = (projectInfo, userConfig, isDiffMode, includePaths, lintSourceFileCount) => {
 	const frameworkLabel = formatFrameworkName(projectInfo.framework);
@@ -2901,10 +3528,12 @@ const runScan = async (directory, options, userConfig, startTime) => {
 				framework: projectInfo.framework,
 				hasReactCompiler: projectInfo.hasReactCompiler,
 				hasTanStackQuery: projectInfo.hasTanStackQuery,
+				reactMajorVersion: parseReactMajor(projectInfo.reactVersion),
 				includePaths: lintIncludePaths,
 				nodeBinaryPath: resolvedNodeBinaryPath,
 				customRulesOnly: options.customRulesOnly,
-				respectInlineDisables: options.respectInlineDisables
+				respectInlineDisables: options.respectInlineDisables,
+				adoptExistingLintConfig: options.adoptExistingLintConfig
 			});
 			lintSpinner?.succeed("Running lint checks.");
 			return lintDiagnostics;
@@ -2944,7 +3573,8 @@ const runScan = async (directory, options, userConfig, startTime) => {
 		deadCodeDiagnostics,
 		directory,
 		isDiffMode,
-		userConfig
+		userConfig,
+		respectInlineDisables: options.respectInlineDisables
 	});
 	const elapsedMilliseconds = performance.now() - startTime;
 	const skippedChecks = [];
@@ -2972,15 +3602,13 @@ const runScan = async (directory, options, userConfig, startTime) => {
 		} else logger.success("No issues found!");
 		logger.break();
 		if (hasSkippedChecks) {
-			printBranding();
-			logger.dim("  Score not shown — some checks could not complete.");
-		} else if (scoreResult) {
-			printBranding(scoreResult.score);
-			printScoreGauge(scoreResult.score, scoreResult.label);
-		} else logger.dim(`  ${noScoreMessage}`);
+			printBrandingOnlyHeader();
+			logger.log(highlighter.gray("  Score not shown — some checks could not complete."));
+		} else if (scoreResult) printScoreHeader(scoreResult);
+		else printNoScoreHeader(noScoreMessage);
 		return buildResult();
 	}
-	printDiagnostics(diagnostics, options.verbose);
+	printDiagnostics(diagnostics, options.verbose, directory);
 	const displayedSourceFileCount = isDiffMode ? includePaths.length : lintSourceFileCount;
 	const shouldShowShareLink = !options.offline && options.share;
 	printSummary(diagnostics, elapsedMilliseconds, scoreResult, projectInfo.projectName, displayedSourceFileCount, noScoreMessage, !shouldShowShareLink);
@@ -3315,6 +3943,41 @@ const handleError = (error, options = DEFAULT_HANDLE_ERROR_OPTIONS) => {
 const encodeAnnotationProperty = (value) => value.replaceAll("%", "%25").replaceAll("\r", "%0D").replaceAll("\n", "%0A").replaceAll(":", "%3A").replaceAll(",", "%2C");
 const encodeAnnotationMessage = (value) => value.replaceAll("%", "%25").replaceAll("\r", "%0D").replaceAll("\n", "%0A");
 //#endregion
+//#region src/utils/find-owning-project.ts
+const findOwningProjectDirectory = (rootDirectory, filePath) => {
+	const absoluteFile = path.isAbsolute(filePath) ? filePath : path.resolve(rootDirectory, filePath);
+	const workspacePackages = listWorkspacePackages(rootDirectory);
+	const candidates = workspacePackages.length > 0 ? workspacePackages : discoverReactSubprojects(rootDirectory);
+	if (candidates.length === 0) return rootDirectory;
+	let bestMatch = null;
+	for (const candidate of candidates) {
+		const candidateDirectory = path.resolve(candidate.directory);
+		const relativeFromCandidate = path.relative(candidateDirectory, absoluteFile);
+		if (relativeFromCandidate.startsWith("..") || path.isAbsolute(relativeFromCandidate)) continue;
+		const depth = candidateDirectory.length;
+		if (!bestMatch || depth > bestMatch.depth) bestMatch = {
+			directory: candidate.directory,
+			depth
+		};
+	}
+	return bestMatch ? bestMatch.directory : rootDirectory;
+};
+//#endregion
+//#region src/utils/parse-file-line-argument.ts
+const parseFileLineArgument = (rawArgument) => {
+	const lastColonIndex = rawArgument.lastIndexOf(":");
+	if (lastColonIndex < 0) throw new Error(`Expected "<file>:<line>" (e.g. "src/foo.tsx:42"), got "${rawArgument}".`);
+	const filePath = rawArgument.slice(0, lastColonIndex);
+	const lineText = rawArgument.slice(lastColonIndex + 1);
+	if (filePath.length === 0) throw new Error(`Missing file path in "${rawArgument}".`);
+	const line = Number.parseInt(lineText, 10);
+	if (!Number.isFinite(line) || line <= 0 || String(line) !== lineText.trim()) throw new Error(`Expected a positive line number in "${rawArgument}".`);
+	return {
+		filePath,
+		line
+	};
+};
+//#endregion
 //#region src/utils/select-projects.ts
 const selectProjects = async (rootDirectory, projectFlag, skipPrompts) => {
 	let packages = listWorkspacePackages(rootDirectory);
@@ -3363,7 +4026,7 @@ const promptProjectSelection = async (workspacePackages, rootDirectory) => {
 };
 //#endregion
 //#region src/cli.ts
-const VERSION = "0.0.47";
+const VERSION = "0.1.1";
 const VALID_FAIL_ON_LEVELS = new Set([
 	"error",
 	"warning",
@@ -3492,6 +4155,46 @@ const resolveDiffMode = async (diffInfo, effectiveDiff, shouldSkipPrompts, isQui
 	});
 	return Boolean(shouldScanChangedOnly);
 };
+const colorizeRuleByDiagnostic = (text, severity) => severity === "error" ? highlighter.error(text) : highlighter.warn(text);
+const runExplain = async (fileLineArgument, context) => {
+	const { filePath, line } = parseFileLineArgument(fileLineArgument);
+	const targetDirectory = await resolveExplainTargetDirectory(filePath, context);
+	const scanResult = await scan(targetDirectory, {
+		...context.scanOptions,
+		silent: true,
+		offline: true,
+		configOverride: context.userConfig
+	});
+	const requestedRelativePath = toRelativePath(filePath, targetDirectory);
+	const matchingDiagnostics = scanResult.diagnostics.filter((diagnostic) => diagnostic.line === line && toRelativePath(diagnostic.filePath, targetDirectory) === requestedRelativePath);
+	if (matchingDiagnostics.length === 0) {
+		logger.log(`No react-doctor diagnostics at ${filePath}:${line}.`);
+		return;
+	}
+	for (const diagnostic of matchingDiagnostics) {
+		const ruleIdentifier = `${diagnostic.plugin}/${diagnostic.rule}`;
+		const severitySymbol = diagnostic.severity === "error" ? "✗" : "⚠";
+		const colorizedRule = colorizeRuleByDiagnostic(ruleIdentifier, diagnostic.severity);
+		const severityLabel = colorizeRuleByDiagnostic(diagnostic.severity, diagnostic.severity);
+		logger.log(`${severitySymbol} ${colorizedRule} ${highlighter.dim(`(${severityLabel})`)} — ${diagnostic.message}`);
+		if (diagnostic.category) logger.dim(`  Category: ${diagnostic.category}`);
+		if (diagnostic.help) logger.dim(`  ${diagnostic.help}`);
+		if (diagnostic.suppressionHint) {
+			logger.break();
+			logger.log(`  Suppression diagnosis: ${diagnostic.suppressionHint}`);
+		} else logger.dim("  No nearby react-doctor-disable-next-line comment was detected — add one immediately above this line to suppress.");
+		logger.break();
+	}
+};
+const resolveExplainTargetDirectory = async (filePath, context) => {
+	if (context.projectFlag) {
+		const matchedDirectories = await selectProjects(context.resolvedDirectory, context.projectFlag, true);
+		if (matchedDirectories.length === 0) return context.resolvedDirectory;
+		if (matchedDirectories.length > 1) throw new Error(`--explain takes a single project; --project resolved to ${matchedDirectories.length} projects.`);
+		return matchedDirectories[0];
+	}
+	return findOwningProjectDirectory(context.resolvedDirectory, filePath);
+};
 const validateModeFlags = (flags) => {
 	const coercedDiff = coerceDiffValue(flags.diff);
 	const exclusiveModes = [flags.staged ? "--staged" : null, coercedDiff !== void 0 && coercedDiff !== false ? "--diff" : null].filter((modeName) => modeName !== null);
@@ -3499,8 +4202,10 @@ const validateModeFlags = (flags) => {
 	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.annotations && (flags.json || flags.score)) throw new Error("--annotations cannot be combined with --json or --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.");
+	if ((flags.explain ?? flags.why) !== void 0 && (flags.json || flags.score || flags.annotations || flags.staged)) throw new Error("--explain cannot be combined with --json, --score, --annotations, or --staged.");
 };
-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 detection").option("--no-dead-code", "skip dead code detection").option("--verbose", "show file details per rule").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("--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("--offline", "skip telemetry (anonymous, not stored, only used to calculate score)").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", "error").option("--annotations", "output diagnostics as GitHub Actions annotations").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").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("--lint", "enable linting").option("--no-lint", "skip linting").option("--dead-code", "enable dead code detection").option("--no-dead-code", "skip dead code detection").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("--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("--offline", "skip telemetry (anonymous, not stored, only used to calculate score)").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", "error").option("--annotations", "output diagnostics as GitHub Actions annotations").option("--explain <file:line>", "diagnose why a rule fired or why a suppression didn't apply at a specific location").addOption(new Option("--why <file:line>", "alias for --explain").hideHelp()).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").action(async (directory, flags) => {
 	const isScoreOnly = flags.score;
 	const isJsonMode = flags.json;
 	const isQuiet = isScoreOnly || isJsonMode;
@@ -3514,6 +4219,16 @@ const program = new Command().name("react-doctor").description("Diagnose React c
 	try {
 		validateModeFlags(flags);
 		const userConfig = loadConfig(resolvedDirectory);
+		const explainArgument = flags.explain ?? flags.why;
+		if (explainArgument !== void 0) {
+			await runExplain(explainArgument, {
+				resolvedDirectory,
+				userConfig,
+				scanOptions: resolveCliScanOptions(flags, userConfig, program),
+				projectFlag: flags.project
+			});
+			return;
+		}
 		if (!isQuiet) {
 			logger.log(`react-doctor v${VERSION}`);
 			logger.break();