react-doctor 0.1.3 → 0.1.5

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, Option } from "commander";
+import { Command } from "commander";
 import { fileURLToPath } from "node:url";
 import { SKILL_MANIFEST_FILE, detectInstalledSkillAgents, getSkillAgentConfig, getSkillAgentTypes, installSkillsFromSource } from "agent-install";
 import pc from "picocolors";
@@ -214,7 +214,7 @@ const finalize = (method, originalText, displayText) => {
 	sharedInstance.stop();
 	ora({
 		text: displayText,
-		indent: 2
+		indent: 0
 	}).start()[method](displayText);
 	const [remainingText] = pendingTexts;
 	if (remainingText) sharedInstance.text = remainingText;
@@ -226,7 +226,7 @@ const spinner = (text) => ({ start() {
 	pendingTexts.add(text);
 	if (!sharedInstance) sharedInstance = ora({
 		text,
-		indent: 2
+		indent: 0
 	}).start();
 	else sharedInstance.text = text;
 	const handle = {
@@ -304,26 +304,45 @@ const runInstallSkill = async (options = {}) => {
 	}
 };
 //#endregion
-//#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);
-	});
+//#region src/errors.ts
+var ReactDoctorError = class extends Error {
+	name = "ReactDoctorError";
+	constructor(message, options) {
+		super(message, options);
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+};
+var NoReactDependencyError = class extends ReactDoctorError {
+	name = "NoReactDependencyError";
+	directory;
+	constructor(directory, options) {
+		super(buildNoReactDependencyError(directory), options);
+		this.directory = directory;
+	}
+};
+var PackageJsonNotFoundError = class extends ReactDoctorError {
+	name = "PackageJsonNotFoundError";
+	directory;
+	constructor(directory, options) {
+		super(`No package.json found in ${directory}`, options);
+		this.directory = directory;
+	}
+};
+//#endregion
+//#region src/utils/resolve-config-root-dir.ts
+const resolveConfigRootDir = (config, configSourceDirectory) => {
+	if (!config || !configSourceDirectory) return null;
+	const rawRootDir = config.rootDir;
+	if (typeof rawRootDir !== "string") return null;
+	const trimmedRootDir = rawRootDir.trim();
+	if (trimmedRootDir.length === 0) return null;
+	const resolvedRootDir = path.isAbsolute(trimmedRootDir) ? trimmedRootDir : path.resolve(configSourceDirectory, trimmedRootDir);
+	if (resolvedRootDir === configSourceDirectory) return null;
+	if (!fs.existsSync(resolvedRootDir) || !fs.statSync(resolvedRootDir).isDirectory()) {
+		logger.warn(`react-doctor config "rootDir" points to "${rawRootDir}" (resolved to ${resolvedRootDir}), which is not a directory. Ignoring.`);
+		return null;
+	}
+	return resolvedRootDir;
 };
 //#endregion
 //#region src/utils/build-hidden-diagnostics-summary.ts
@@ -824,7 +843,7 @@ const findEnclosingMultilineJsxOpenerStart = (lines, diagnosticLineIndex) => {
 };
 //#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 DISABLE_NEXT_LINE_PATTERN = /(?:\/\/|\/\*)\s*react-doctor-disable-next-line\b(?:\s+([^\r\n]*?))?\s*(?:\*\/)?\s*\}?\s*$/;
 const findStackedDisableCommentsAbove = (lines, anchorIndex) => {
 	const collected = [];
 	let isStillInChain = true;
@@ -846,13 +865,21 @@ const findStackedDisableCommentsAbove = (lines, anchorIndex) => {
 };
 //#endregion
 //#region src/utils/is-rule-listed-in-comment.ts
+const stripDescriptionTail = (ruleList) => {
+	const descriptionMatch = ruleList.match(/(?:^|\s)--\s/);
+	if (!descriptionMatch || descriptionMatch.index === void 0) return ruleList;
+	return ruleList.slice(0, descriptionMatch.index);
+};
 const isRuleListedInComment = (ruleList, ruleId) => {
-	if (!ruleList?.trim()) return true;
-	return ruleList.split(/[,\s]+/).some((token) => token.trim() === ruleId);
+	const trimmed = ruleList?.trim();
+	if (!trimmed) return true;
+	const ruleSection = stripDescriptionTail(trimmed).trim();
+	if (!ruleSection) return true;
+	return ruleSection.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 DISABLE_LINE_PATTERN = /(?:\/\/|\/\*)\s*react-doctor-disable-line\b(?:\s+([^\r\n]*?))?\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));
@@ -1273,9 +1300,9 @@ const resolveCatalogVersionFromCollection = (catalogs, packageName, catalogRefer
 	for (const namedCatalog of Object.values(catalogs.namedCatalogs)) if (namedCatalog[packageName]) return namedCatalog[packageName];
 	return null;
 };
-const resolveCatalogVersion = (packageJson, packageName, rootDirectory) => {
+const resolveCatalogVersion = (packageJson, packageName, rootDirectory, explicitCatalogReference) => {
 	const rawVersion = collectAllDependencies(packageJson)[packageName];
-	const catalogName = rawVersion ? extractCatalogName(rawVersion) : null;
+	const catalogName = explicitCatalogReference ?? (rawVersion ? extractCatalogName(rawVersion) : null);
 	if (isPlainObject(packageJson.catalog)) {
 		const version = resolveVersionFromCatalog(packageJson.catalog, packageName);
 		if (version) return version;
@@ -1292,9 +1319,22 @@ const resolveCatalogVersion = (packageJson, packageName, rootDirectory) => {
 		}
 	}
 	const workspaces = packageJson.workspaces;
-	if (workspaces && !Array.isArray(workspaces) && isPlainObject(workspaces.catalog)) {
-		const version = resolveVersionFromCatalog(workspaces.catalog, packageName);
-		if (version) return version;
+	if (workspaces && !Array.isArray(workspaces)) {
+		if (isPlainObject(workspaces.catalog)) {
+			const version = resolveVersionFromCatalog(workspaces.catalog, packageName);
+			if (version) return version;
+		}
+		if (isPlainObject(workspaces.catalogs)) {
+			const namedCatalog = catalogName ? workspaces.catalogs[catalogName] : void 0;
+			if (namedCatalog && isPlainObject(namedCatalog)) {
+				const version = resolveVersionFromCatalog(namedCatalog, packageName);
+				if (version) return version;
+			}
+			for (const catalogEntries of Object.values(workspaces.catalogs)) if (isPlainObject(catalogEntries)) {
+				const version = resolveVersionFromCatalog(catalogEntries, packageName);
+				if (version) return version;
+			}
+		}
 	}
 	if (rootDirectory) {
 		const pnpmVersion = resolveCatalogVersionFromCollection(parsePnpmWorkspaceCatalogs(rootDirectory), packageName, catalogName);
@@ -1381,7 +1421,8 @@ const findDependencyInfoFromMonorepoRoot = (directory) => {
 	};
 	const rootPackageJson = readPackageJson(monorepoPackageJsonPath);
 	const rootInfo = extractDependencyInfo(rootPackageJson);
-	const catalogVersion = resolveCatalogVersion(rootPackageJson, "react", monorepoRoot);
+	const leafPackageJsonPath = path.join(directory, "package.json");
+	const catalogVersion = resolveCatalogVersion(rootPackageJson, "react", monorepoRoot, isFile(leafPackageJsonPath) ? extractCatalogName(collectAllDependencies(readPackageJson(leafPackageJsonPath)).react ?? "") ?? null : null);
 	const workspaceInfo = findReactInWorkspaces(monorepoRoot, rootPackageJson);
 	return {
 		reactVersion: rootInfo.reactVersion ?? catalogVersion ?? workspaceInfo.reactVersion,
@@ -1509,15 +1550,16 @@ const discoverProject = (directory) => {
 	const cached = cachedProjectInfos.get(directory);
 	if (cached !== void 0) return cached;
 	const packageJsonPath = path.join(directory, "package.json");
-	if (!isFile(packageJsonPath)) throw new Error(`No package.json found in ${directory}`);
+	if (!isFile(packageJsonPath)) throw new PackageJsonNotFoundError(directory);
 	const packageJson = readPackageJson(packageJsonPath);
 	let { reactVersion, framework } = extractDependencyInfo(packageJson);
-	if (!reactVersion) reactVersion = resolveCatalogVersion(packageJson, "react", directory);
+	const leafCatalogReference = extractCatalogName(collectAllDependencies(packageJson).react ?? "") ?? null;
+	if (!reactVersion) reactVersion = resolveCatalogVersion(packageJson, "react", directory, leafCatalogReference);
 	if (!reactVersion) {
 		const monorepoRoot = findMonorepoRoot(directory);
 		if (monorepoRoot) {
 			const monorepoPackageJsonPath = path.join(monorepoRoot, "package.json");
-			if (isFile(monorepoPackageJsonPath)) reactVersion = resolveCatalogVersion(readPackageJson(monorepoPackageJsonPath), "react", monorepoRoot);
+			if (isFile(monorepoPackageJsonPath)) reactVersion = resolveCatalogVersion(readPackageJson(monorepoPackageJsonPath), "react", monorepoRoot, leafCatalogReference);
 		}
 	}
 	if (!reactVersion || framework === "unknown") {
@@ -1591,6 +1633,7 @@ const BOOLEAN_FIELD_NAMES = [
 	"respectInlineDisables",
 	"adoptExistingLintConfig"
 ];
+const STRING_FIELD_NAMES = ["rootDir"];
 const warnConfigField = (message) => {
 	process.stderr.write(`[react-doctor] ${message}\n`);
 };
@@ -1606,6 +1649,10 @@ const coerceMaybeBooleanString = (fieldName, value) => {
 	}
 	warnConfigField(`config field "${fieldName}" must be a boolean (got ${typeof value}); ignoring this field.`);
 };
+const validateString = (fieldName, value) => {
+	if (typeof value === "string") return value;
+	warnConfigField(`config field "${fieldName}" must be a string (got ${typeof value}); ignoring this field.`);
+};
 const validateConfigTypes = (config) => {
 	const validated = { ...config };
 	for (const fieldName of BOOLEAN_FIELD_NAMES) {
@@ -1615,6 +1662,13 @@ const validateConfigTypes = (config) => {
 		if (coerced === void 0) delete validated[fieldName];
 		else validated[fieldName] = coerced;
 	}
+	for (const fieldName of STRING_FIELD_NAMES) {
+		const original = config[fieldName];
+		if (original === void 0) continue;
+		const validatedString = validateString(fieldName, original);
+		if (validatedString === void 0) delete validated[fieldName];
+		else validated[fieldName] = validatedString;
+	}
 	return validated;
 };
 //#endregion
@@ -1626,7 +1680,10 @@ const loadConfigFromDirectory = (directory) => {
 	if (isFile(configFilePath)) try {
 		const fileContent = fs.readFileSync(configFilePath, "utf-8");
 		const parsed = JSON.parse(fileContent);
-		if (isPlainObject(parsed)) return validateConfigTypes(parsed);
+		if (isPlainObject(parsed)) return {
+			config: validateConfigTypes(parsed),
+			sourceDirectory: directory
+		};
 		logger.warn(`${CONFIG_FILENAME} must be a JSON object, ignoring.`);
 	} catch (error) {
 		logger.warn(`Failed to parse ${CONFIG_FILENAME}: ${error instanceof Error ? error.message : String(error)}`);
@@ -1637,7 +1694,10 @@ const loadConfigFromDirectory = (directory) => {
 		const packageJson = JSON.parse(fileContent);
 		if (isPlainObject(packageJson)) {
 			const embeddedConfig = packageJson[PACKAGE_JSON_CONFIG_KEY];
-			if (isPlainObject(embeddedConfig)) return validateConfigTypes(embeddedConfig);
+			if (isPlainObject(embeddedConfig)) return {
+				config: validateConfigTypes(embeddedConfig),
+				sourceDirectory: directory
+			};
 		}
 	} catch {
 		return null;
@@ -1646,7 +1706,7 @@ const loadConfigFromDirectory = (directory) => {
 };
 const isProjectBoundary$1 = (directory) => fs.existsSync(path.join(directory, ".git")) || isMonorepoRoot(directory);
 const cachedConfigs = /* @__PURE__ */ new Map();
-const loadConfig = (rootDirectory) => {
+const loadConfigWithSource = (rootDirectory) => {
 	const cached = cachedConfigs.get(rootDirectory);
 	if (cached !== void 0) return cached;
 	const localConfig = loadConfigFromDirectory(rootDirectory);
@@ -1675,6 +1735,32 @@ const loadConfig = (rootDirectory) => {
 	return null;
 };
 //#endregion
+//#region src/utils/wrap-indented-text.ts
+const wrapLine = (lineText, contentWidth) => {
+	if (lineText.length <= contentWidth) return [lineText];
+	const wrappedLines = [];
+	let remainingText = lineText.trim();
+	while (remainingText.length > contentWidth) {
+		const candidateText = remainingText.slice(0, contentWidth);
+		const breakIndex = candidateText.lastIndexOf(" ");
+		if (breakIndex <= 0) {
+			wrappedLines.push(candidateText);
+			remainingText = remainingText.slice(contentWidth).trimStart();
+			continue;
+		}
+		wrappedLines.push(remainingText.slice(0, breakIndex));
+		remainingText = remainingText.slice(breakIndex + 1).trimStart();
+	}
+	if (remainingText.length > 0) wrappedLines.push(remainingText);
+	return wrappedLines;
+};
+const wrapIndentedText = (text, linePrefix, width) => {
+	const contentWidth = width - linePrefix.length;
+	if (contentWidth <= 0) return indentOnly(text, linePrefix);
+	return text.split("\n").flatMap((lineText) => wrapLine(lineText, contentWidth)).map((lineText) => `${linePrefix}${lineText}`).join("\n");
+};
+const indentOnly = (text, linePrefix) => text.split("\n").map((lineText) => `${linePrefix}${lineText}`).join("\n");
+//#endregion
 //#region src/utils/resolve-compatible-node.ts
 const parseNodeVersion = (versionString) => {
 	const [major = 0, minor = 0, patch = 0] = versionString.replace(/^v/, "").trim().split(".").map(Number);
@@ -2256,6 +2342,16 @@ const TANSTACK_START_RULES = {
 	"react-doctor/tanstack-start-redirect-in-try-catch": "warn",
 	"react-doctor/tanstack-start-loader-parallel-fetch": "warn"
 };
+const YOU_MIGHT_NOT_NEED_EFFECT_RULES = {
+	"effect/no-derived-state": "warn",
+	"effect/no-chain-state-updates": "warn",
+	"effect/no-event-handler": "warn",
+	"effect/no-adjust-state-on-prop-change": "warn",
+	"effect/no-reset-all-state-on-prop-change": "warn",
+	"effect/no-pass-live-state-to-parent": "warn",
+	"effect/no-pass-data-to-parent": "warn",
+	"effect/no-initialize-state": "warn"
+};
 const REACT_COMPILER_RULES = {
 	"react-hooks-js/set-state-in-render": "error",
 	"react-hooks-js/immutability": "error",
@@ -2300,6 +2396,23 @@ const resolveReactHooksJsPlugin = (hasReactCompiler, customRulesOnly) => {
 		availableRuleNames: readPluginRuleNames(pluginSpecifier)
 	};
 };
+const YOU_MIGHT_NOT_NEED_EFFECT_NAMESPACE = "effect";
+const resolveYouMightNotNeedEffectPlugin = (customRulesOnly) => {
+	if (customRulesOnly) return null;
+	let pluginSpecifier;
+	try {
+		pluginSpecifier = esmRequire$1.resolve("eslint-plugin-react-you-might-not-need-an-effect");
+	} catch {
+		return null;
+	}
+	return {
+		entry: {
+			name: YOU_MIGHT_NOT_NEED_EFFECT_NAMESPACE,
+			specifier: pluginSpecifier
+		},
+		availableRuleNames: readPluginRuleNames(pluginSpecifier)
+	};
+};
 const filterRulesToAvailable = (rules, pluginNamespace, availableRuleNames) => {
 	if (availableRuleNames.size === 0) return rules;
 	const ruleKeyPrefix = `${pluginNamespace}/`;
@@ -2510,6 +2623,11 @@ const filterRulesByReactMajor = (rules, reactMajorVersion) => {
 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) : {};
+	const youMightNotNeedEffectPlugin = resolveYouMightNotNeedEffectPlugin(customRulesOnly);
+	const youMightNotNeedEffectRules = youMightNotNeedEffectPlugin ? filterRulesToAvailable(YOU_MIGHT_NOT_NEED_EFFECT_RULES, YOU_MIGHT_NOT_NEED_EFFECT_NAMESPACE, youMightNotNeedEffectPlugin.availableRuleNames) : {};
+	const jsPlugins = [];
+	if (reactHooksJsPlugin) jsPlugins.push(reactHooksJsPlugin.entry);
+	if (youMightNotNeedEffectPlugin) jsPlugins.push(youMightNotNeedEffectPlugin.entry);
 	return {
 		...extendsPaths.length > 0 ? { extends: extendsPaths } : {},
 		categories: {
@@ -2522,11 +2640,12 @@ const createOxlintConfig = ({ pluginPath, framework, hasReactCompiler, hasTanSta
 			nursery: "off"
 		},
 		plugins: customRulesOnly ? [] : ["react", "jsx-a11y"],
-		jsPlugins: reactHooksJsPlugin ? [reactHooksJsPlugin.entry, pluginPath] : [pluginPath],
+		jsPlugins: [...jsPlugins, pluginPath],
 		rules: {
 			...customRulesOnly ? {} : BUILTIN_REACT_RULES,
 			...customRulesOnly ? {} : BUILTIN_A11Y_RULES,
 			...reactCompilerRules,
+			...youMightNotNeedEffectRules,
 			...filterRulesByReactMajor(GLOBAL_REACT_DOCTOR_RULES, reactMajorVersion),
 			...framework === "nextjs" ? NEXTJS_RULES : {},
 			...framework === "expo" || framework === "react-native" ? REACT_NATIVE_RULES : {},
@@ -2640,6 +2759,7 @@ const PLUGIN_CATEGORY_MAP = {
 	"react-doctor": "Other",
 	"jsx-a11y": "Accessibility",
 	knip: "Dead Code",
+	effect: "State & Effects",
 	eslint: "Correctness",
 	oxc: "Correctness",
 	typescript: "Correctness",
@@ -3154,6 +3274,7 @@ const parseOxlintOutput = (stdout) => {
 			severity: diagnostic.severity,
 			message: cleaned.message,
 			help: cleaned.help,
+			url: diagnostic.url,
 			line: primaryLabel?.span.line ?? 0,
 			column: primaryLabel?.span.column ?? 0,
 			category: resolveDiagnosticCategory(plugin, rule)
@@ -3285,6 +3406,11 @@ const buildVerboseSiteMap = (diagnostics) => {
 	return fileSites;
 };
 const formatSiteCountBadge = (count) => count > 1 ? `×${count}` : "";
+const formatIssueCount = (count) => `${count} ${count === 1 ? "issue" : "issues"}`;
+const toRuleTitle = (ruleName) => {
+	const readableRuleName = ruleName.replace(/^(no|prefer|require|use)-/, "").replace(/^(nextjs|tanstack-start)-/, "").replaceAll("-", " ");
+	return (readableRuleName.charAt(0).toUpperCase() + readableRuleName.slice(1)).replace(/\b(css|html|url|svg|jsx|api|ua)\b/gi, (match) => match.toUpperCase());
+};
 const computeRuleNameColumnWidth = (ruleKeys) => {
 	const longestRuleNameLength = ruleKeys.reduce((longest, ruleKey) => Math.max(longest, ruleKey.length), 0);
 	return Math.max(36, longestRuleNameLength);
@@ -3296,6 +3422,9 @@ const padRuleNameToColumn = (ruleName, columnWidth) => {
 const grayLine = (text) => {
 	logger.log(highlighter.gray(text));
 };
+const grayWrappedLine = (text, linePrefix) => {
+	grayLine(wrapIndentedText(text, linePrefix, 88));
+};
 const printCompactRuleGroupLine = (ruleKey, ruleDiagnostics, ruleNameColumnWidth) => {
 	const firstDiagnostic = ruleDiagnostics[0];
 	const icon = colorizeBySeverity(firstDiagnostic.severity === "error" ? "✗" : "⚠", firstDiagnostic.severity);
@@ -3304,13 +3433,38 @@ const printCompactRuleGroupLine = (ruleKey, ruleDiagnostics, ruleNameColumnWidth
 	const trailingBadge = siteCountBadge.length > 0 ? ` ${highlighter.gray(siteCountBadge)}` : "";
 	logger.log(`  ${icon} ${ruleNameRendering}${trailingBadge}`);
 };
-const printDetailedRuleGroup = (ruleKey, ruleDiagnostics, rootDirectory, ruleNameColumnWidth) => {
-	printCompactRuleGroupLine(ruleKey, ruleDiagnostics, ruleNameColumnWidth);
+const getWorstSeverity = (diagnostics) => diagnostics.some((diagnostic) => diagnostic.severity === "error") ? "error" : "warning";
+const buildCategoryDiagnosticGroups = (diagnostics) => {
+	return [...groupBy(diagnostics, (diagnostic) => diagnostic.category).entries()].map(([category, categoryDiagnostics]) => {
+		return {
+			category,
+			diagnostics: categoryDiagnostics,
+			ruleGroups: sortByImportance([...groupBy(categoryDiagnostics, (diagnostic) => `${diagnostic.plugin}/${diagnostic.rule}`).entries()])
+		};
+	}).toSorted((categoryGroupA, categoryGroupB) => {
+		const severityDelta = SEVERITY_ORDER[getWorstSeverity(categoryGroupA.diagnostics)] - SEVERITY_ORDER[getWorstSeverity(categoryGroupB.diagnostics)];
+		if (severityDelta !== 0) return severityDelta;
+		if (categoryGroupA.diagnostics.length !== categoryGroupB.diagnostics.length) return categoryGroupB.diagnostics.length - categoryGroupA.diagnostics.length;
+		return categoryGroupA.category.localeCompare(categoryGroupB.category);
+	});
+};
+const printDefaultRuleGroup = (ruleKey, ruleDiagnostics, rootDirectory) => {
 	const firstDiagnostic = ruleDiagnostics[0];
-	grayLine(indentMultilineText(firstDiagnostic.message, "      "));
-	if (firstDiagnostic.help) grayLine(indentMultilineText(`→ ${firstDiagnostic.help}`, "      "));
+	const ruleTitle = toRuleTitle(firstDiagnostic.rule);
+	const icon = colorizeBySeverity(firstDiagnostic.severity === "error" ? "✗" : "⚠", firstDiagnostic.severity);
+	const siteCountBadge = formatSiteCountBadge(ruleDiagnostics.length);
+	const trailingBadge = siteCountBadge.length > 0 ? ` ${highlighter.gray(siteCountBadge)}` : "";
+	logger.log(`  ${icon} ${ruleTitle}${trailingBadge}`);
+	grayWrappedLine(firstDiagnostic.message, "    ");
+	if (firstDiagnostic.help) grayWrappedLine(firstDiagnostic.help, "    ");
+	if (firstDiagnostic.url) grayLine(`    ${firstDiagnostic.url}`);
 	const firstLocation = ruleDiagnostics.find((diagnostic) => diagnostic.line > 0);
-	if (firstLocation) grayLine(`      ${toRelativePath(firstLocation.filePath, rootDirectory)}:${firstLocation.line}`);
+	if (firstLocation) grayLine(`    ${toRelativePath(firstLocation.filePath, rootDirectory)}:${firstLocation.line}`);
+};
+const printDefaultCategoryGroup = (categoryGroup, visibleRuleGroups, rootDirectory) => {
+	const issueCount = formatIssueCount(categoryGroup.diagnostics.length);
+	logger.log(`${highlighter.bold(categoryGroup.category)} ${highlighter.dim(issueCount)}`);
+	for (const [ruleKey, ruleDiagnostics] of visibleRuleGroups) printDefaultRuleGroup(ruleKey, ruleDiagnostics, rootDirectory);
 	logger.break();
 };
 const printVerboseRuleGroup = (ruleKey, ruleDiagnostics, ruleNameColumnWidth) => {
@@ -3326,22 +3480,36 @@ const printVerboseRuleGroup = (ruleKey, ruleDiagnostics, ruleNameColumnWidth) =>
 	else grayLine(`      ${filePath}`);
 	logger.break();
 };
+const printDefaultDiagnostics = (diagnostics, rootDirectory) => {
+	const categoryGroups = buildCategoryDiagnosticGroups(diagnostics);
+	const hiddenRuleGroups = [];
+	const visibleCategoryGroups = categoryGroups.slice(0, 5);
+	const hiddenCategoryGroups = categoryGroups.slice(5);
+	for (const categoryGroup of visibleCategoryGroups) {
+		const visibleRuleGroups = categoryGroup.ruleGroups.slice(0, 3);
+		const remainingRuleGroups = categoryGroup.ruleGroups.slice(3);
+		printDefaultCategoryGroup(categoryGroup, visibleRuleGroups, rootDirectory);
+		hiddenRuleGroups.push(...remainingRuleGroups);
+	}
+	hiddenRuleGroups.push(...hiddenCategoryGroups.flatMap((categoryGroup) => categoryGroup.ruleGroups));
+	if (hiddenRuleGroups.length > 0) printHiddenDiagnosticsSummary(hiddenRuleGroups);
+};
 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);
+	if (!isVerbose) {
+		printDefaultDiagnostics(diagnostics, rootDirectory);
+		return;
+	}
+	const visibleRuleGroups = sortByImportance([...groupBy(diagnostics, (diagnostic) => `${diagnostic.plugin}/${diagnostic.rule}`).entries()]);
 	const ruleNameColumnWidth = computeRuleNameColumnWidth(visibleRuleGroups.map(([ruleKey]) => ruleKey));
 	visibleRuleGroups.forEach(([ruleKey, ruleDiagnostics]) => {
-		if (isVerbose) {
-			printVerboseRuleGroup(ruleKey, ruleDiagnostics, ruleNameColumnWidth);
-			return;
-		}
-		printDetailedRuleGroup(ruleKey, ruleDiagnostics, rootDirectory, ruleNameColumnWidth);
+		printVerboseRuleGroup(ruleKey, ruleDiagnostics, ruleNameColumnWidth);
 	});
-	if (hiddenRuleGroups.length > 0) printHiddenDiagnosticsSummary(hiddenRuleGroups);
 };
 const printHiddenDiagnosticsSummary = (hiddenRuleGroups) => {
-	const renderedParts = buildHiddenDiagnosticsSummary(hiddenRuleGroups.flatMap(([, ruleDiagnostics]) => ruleDiagnostics)).map((part) => colorizeBySeverity(part.text, part.severity));
+	const renderedParts = buildHiddenDiagnosticsSummary(hiddenRuleGroups.flatMap(([, ruleDiagnostics]) => ruleDiagnostics)).map((part) => {
+		const [icon, ...labelParts] = part.text.split(" ");
+		return `${colorizeBySeverity(icon, part.severity)} ${highlighter.dim(labelParts.join(" "))}`;
+	});
 	logger.log(`  ${renderedParts.join("  ")}`);
 	grayLine("    Run `npx react-doctor@latest . --verbose` to get all details");
 	logger.break();
@@ -3361,6 +3529,7 @@ const formatRuleSummary = (ruleKey, ruleDiagnostics) => {
 		firstDiagnostic.message
 	];
 	if (firstDiagnostic.help) sections.push("", `Suggestion: ${firstDiagnostic.help}`);
+	if (firstDiagnostic.url) sections.push("", `Docs: ${firstDiagnostic.url}`);
 	sections.push("", "Files:");
 	const fileSites = buildVerboseSiteMap(ruleDiagnostics);
 	for (const [filePath, sites] of fileSites) if (sites.length > 0) for (const site of sites) {
@@ -3432,32 +3601,6 @@ const printNoScoreHeader = (noScoreMessage) => {
 	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.break();
-};
 const buildShareUrl = (diagnostics, scoreResult, projectName) => {
 	const errorCount = diagnostics.filter((diagnostic) => diagnostic.severity === "error").length;
 	const warningCount = diagnostics.filter((diagnostic) => diagnostic.severity === "warning").length;
@@ -3483,7 +3626,6 @@ const printCountsSummaryLine = (diagnostics, totalSourceFileCount, elapsedMillis
 	logger.log(`  ${issueCountColor(issueCountText)} ${highlighter.dim(`${fileCountText}  ${elapsedTimeText}`)}`);
 };
 const printSummary = (diagnostics, elapsedMilliseconds, scoreResult, projectName, totalSourceFileCount, noScoreMessage, isOffline) => {
-	printCategoryBreakdown(buildCategoryBreakdown(diagnostics));
 	if (scoreResult) printScoreHeader(scoreResult);
 	else printNoScoreHeader(noScoreMessage);
 	printCountsSummaryLine(diagnostics, totalSourceFileCount, elapsedMilliseconds);
@@ -3565,7 +3707,15 @@ const printProjectDetection = (projectInfo, userConfig, isDiffMode, includePaths
 };
 const scan = async (directory, inputOptions = {}) => {
 	const startTime = performance.now();
-	const userConfig = inputOptions.configOverride !== void 0 ? inputOptions.configOverride : loadConfig(directory);
+	let scanDirectory = directory;
+	let userConfig;
+	if (inputOptions.configOverride !== void 0) userConfig = inputOptions.configOverride;
+	else {
+		const loadedConfig = loadConfigWithSource(directory);
+		const redirectedDirectory = resolveConfigRootDir(loadedConfig?.config ?? null, loadedConfig?.sourceDirectory ?? null);
+		if (redirectedDirectory) scanDirectory = redirectedDirectory;
+		userConfig = loadedConfig?.config ?? null;
+	}
 	const options = mergeScanOptions(inputOptions, userConfig);
 	const wasLoggerSilent = isLoggerSilent();
 	const wasSpinnerSilent = isSpinnerSilent();
@@ -3574,7 +3724,7 @@ const scan = async (directory, inputOptions = {}) => {
 		setSpinnerSilent(true);
 	}
 	try {
-		return await runScan(directory, options, userConfig, startTime);
+		return await runScan(scanDirectory, options, userConfig, startTime);
 	} finally {
 		if (options.silent) {
 			setLoggerSilent(wasLoggerSilent);
@@ -3586,7 +3736,7 @@ const runScan = async (directory, options, userConfig, startTime) => {
 	const projectInfo = discoverProject(directory);
 	const { includePaths } = options;
 	const isDiffMode = includePaths.length > 0;
-	if (!projectInfo.reactVersion) throw new Error(buildNoReactDependencyError(directory));
+	if (!projectInfo.reactVersion) throw new NoReactDependencyError(directory);
 	const lintIncludePaths = computeJsxIncludePaths(includePaths) ?? resolveLintIncludePaths(directory, userConfig);
 	const lintSourceFileCount = lintIncludePaths?.length ?? projectInfo.sourceFileCount;
 	if (!options.scoreOnly) printProjectDetection(projectInfo, userConfig, isDiffMode, includePaths, lintSourceFileCount);
@@ -4102,7 +4252,7 @@ const promptProjectSelection = async (workspacePackages, rootDirectory) => {
 };
 //#endregion
 //#region src/cli.ts
-const VERSION = "0.1.3";
+const VERSION = "0.1.5";
 const VALID_FAIL_ON_LEVELS = new Set([
 	"error",
 	"warning",
@@ -4281,20 +4431,28 @@ const validateModeFlags = (flags) => {
 	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 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 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").option("--why <file:line>", "alias for --explain").option("--respect-inline-disables", "respect inline `// eslint-disable*` / `// oxlint-disable*` comments (default)").option("--no-respect-inline-disables", "audit mode: neutralize inline lint suppressions before scanning").action(async (directory, flags) => {
 	const isScoreOnly = flags.score;
 	const isJsonMode = flags.json;
 	const isQuiet = isScoreOnly || isJsonMode;
-	const resolvedDirectory = path.resolve(directory);
+	const requestedDirectory = path.resolve(directory);
 	const jsonStartTime = performance.now();
 	isJsonModeActive = isJsonMode;
 	isCompactJsonOutput = Boolean(flags.jsonCompact);
-	resolvedDirectoryForCancel = resolvedDirectory;
+	resolvedDirectoryForCancel = requestedDirectory;
 	cancelStartTime = jsonStartTime;
 	if (isJsonMode) setLoggerSilent(true);
 	try {
 		validateModeFlags(flags);
-		const userConfig = loadConfig(resolvedDirectory);
+		const loadedConfig = loadConfigWithSource(requestedDirectory);
+		const userConfig = loadedConfig?.config ?? null;
+		const redirectedDirectory = resolveConfigRootDir(loadedConfig?.config ?? null, loadedConfig?.sourceDirectory ?? null);
+		const resolvedDirectory = redirectedDirectory ?? requestedDirectory;
+		resolvedDirectoryForCancel = resolvedDirectory;
+		if (redirectedDirectory && !isQuiet) {
+			logger.dim(`Redirected to ${highlighter.info(toRelativePath(resolvedDirectory, requestedDirectory))} via react-doctor config "rootDir".`);
+			logger.break();
+		}
 		const explainArgument = flags.explain ?? flags.why;
 		if (explainArgument !== void 0) {
 			await runExplain(explainArgument, {
@@ -4368,7 +4526,7 @@ const program = new Command().name("react-doctor").description("Diagnose React c
 					totalElapsedMilliseconds: performance.now() - jsonStartTime
 				}));
 				if (flags.annotations) printAnnotations(remappedDiagnostics, isJsonMode);
-				if (shouldFailForDiagnostics(remappedDiagnostics, resolveFailOnLevel(program, flags, userConfig))) process.exitCode = 1;
+				if (!isScoreOnly && shouldFailForDiagnostics(remappedDiagnostics, resolveFailOnLevel(program, flags, userConfig))) process.exitCode = 1;
 			} finally {
 				cleanupSnapshot?.();
 			}
@@ -4412,7 +4570,8 @@ const program = new Command().name("react-doctor").description("Diagnose React c
 			}
 			const scanResult = await scan(projectDirectory, {
 				...scanOptions,
-				includePaths
+				includePaths,
+				configOverride: userConfig
 			});
 			allDiagnostics.push(...scanResult.diagnostics);
 			completedScans.push({
@@ -4431,13 +4590,13 @@ const program = new Command().name("react-doctor").description("Diagnose React c
 			totalElapsedMilliseconds: performance.now() - jsonStartTime
 		}));
 		if (flags.annotations) printAnnotations(allDiagnostics, isJsonMode);
-		if (shouldFailForDiagnostics(allDiagnostics, resolveFailOnLevel(program, flags, userConfig))) process.exitCode = 1;
+		if (!isScoreOnly && shouldFailForDiagnostics(allDiagnostics, resolveFailOnLevel(program, flags, userConfig))) process.exitCode = 1;
 	} catch (error) {
 		try {
 			if (isJsonMode) {
 				writeJsonReport(buildJsonReportError({
 					version: VERSION,
-					directory: resolvedDirectory,
+					directory: resolvedDirectoryForCancel ?? requestedDirectory,
 					error,
 					elapsedMilliseconds: performance.now() - jsonStartTime,
 					mode: currentReportMode

package/dist/eslint-plugin.js

@@ -6946,7 +6946,7 @@ const ALL_RULES_AT_RECOMMENDED_SEVERITY = {
 const eslintPlugin = {
 	meta: {
 		name: PLUGIN_NAMESPACE,
-		version: "0.1.3"
+		version: "0.1.5"
 	},
 	rules: eslintShapedRules,
 	configs: {