react-doctor 0.1.4 → 0.1.6

package/README.md

@@ -41,17 +41,42 @@ Works with Claude Code, Cursor, Codex, OpenCode, and 50+ other agents.
 
 ## GitHub Actions
 
+A composite action ships with this repository. Drop it into `.github/workflows/react-doctor.yml`:
+
 ```yaml
-- uses: actions/checkout@v5
-  with:
-    fetch-depth: 0 # required for --diff
-- uses: millionco/react-doctor@main
-  with:
-    diff: main
-    github-token: ${{ secrets.GITHUB_TOKEN }}
+name: React Doctor
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: write # required to post PR comments
+
+jobs:
+  react-doctor:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0 # required for `diff`
+      - uses: millionco/react-doctor@main
+        with:
+          diff: main
+          github-token: ${{ secrets.GITHUB_TOKEN }}
 ```
 
-When `github-token` is set on `pull_request` events, findings are posted as a PR comment. The action also outputs a `score` (0 to 100) you can use in subsequent steps.
+When `github-token` is set on `pull_request` events, findings are posted (and updated) as a PR comment. The action also exposes a `score` output (0–100) you can use in subsequent steps.
+
+**Inputs:** `directory`, `verbose`, `project`, `diff`, `github-token`, `fail-on` (`error` / `warning` / `none`), `offline`, `node-version`. See [`action.yml`](https://github.com/millionco/react-doctor/blob/main/action.yml) for full descriptions.
+
+Prefer not to add a marketplace action? The bare `npx` form works too:
+
+```yaml
+- run: npx -y react-doctor@latest --fail-on warning
+```
 
 ## Configuration
 
@@ -64,20 +89,39 @@ Create a `react-doctor.config.json` in your project root:
     "files": ["src/generated/**"],
     "overrides": [
       {
-        "files": ["components/diff/**"],
-        "rules": ["react-doctor/no-array-index-as-key"]
+        "files": ["components/modules/diff/**"],
+        "rules": ["react-doctor/no-array-index-as-key", "react-doctor/no-render-in-render"]
+      },
+      {
+        "files": ["components/search/HighlightedSnippet.tsx"],
+        "rules": ["react/no-danger"]
       }
     ]
   }
 }
 ```
 
-`ignore.rules` silences a rule everywhere. `ignore.files` silences every rule on matched files. `ignore.overrides` silences specific rules in specific directories. You can also use the `"reactDoctor"` key in `package.json`. CLI flags always override config values.
+Three nested keys, three layers of granularity — pick the narrowest one that fits:
+
+- **`ignore.rules`** silences a rule across the whole codebase.
+- **`ignore.files`** silences **every** rule on the matched files (use sparingly — it loses coverage for unrelated rules).
+- **`ignore.overrides`** silences only the listed rules on the matched files, leaving every other rule active. This is what you want when a single file (or glob) legitimately needs an exemption from one or two rules but should still be scanned for everything else.
+
+You can also use the `"reactDoctor"` key in `package.json`. CLI flags always override config values.
 
 React Doctor respects `.gitignore`, `.eslintignore`, `.oxlintignore`, `.prettierignore`, and `linguist-vendored` / `linguist-generated` annotations in `.gitattributes`. Inline `// eslint-disable*` and `// oxlint-disable*` comments are honored too.
 
 If you have a JSON oxlint or eslint config (`.oxlintrc.json` or `.eslintrc.json`), its rules get merged into the scan automatically and count toward the score. Set `adoptExistingLintConfig: false` to opt out.
 
+#### Optional companion plugins
+
+When the following ESLint plugins are installed in the scanned project (or hoisted in your monorepo), React Doctor folds their rules into the same scan. Both are listed as **optional peer dependencies** — install only what you want.
+
+| Plugin                                                                                                                                          | Adds                                                                                                                                                                                                        | Namespace          |
+| ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
+| [`eslint-plugin-react-hooks`](https://www.npmjs.com/package/eslint-plugin-react-hooks) (v6 or v7)                                               | The React Compiler frontend's correctness rules — fired when a React Compiler is detected in the project.                                                                                                   | `react-hooks-js/*` |
+| [`eslint-plugin-react-you-might-not-need-an-effect`](https://github.com/nickjvandyke/eslint-plugin-react-you-might-not-need-an-effect) (v0.10+) | Complementary effects-as-anti-pattern rules (`no-derived-state`, `no-chain-state-updates`, `no-event-handler`, `no-pass-data-to-parent`, …) that run alongside React Doctor's native State & Effects rules. | `effect/*`         |
+
 ### Inline suppressions
 
 ```tsx
@@ -88,7 +132,24 @@ useEffect(() => {
 }, [value]);
 ```
 
-When two rules fire on the same line, comma-separate the rule ids on a single comment. Block comments work inside JSX:
+When two rules fire on the same line, you have two equivalent options. Comma-separate the rule ids on a single comment:
+
+```tsx
+// react-doctor-disable-next-line react-doctor/rerender-state-only-in-handlers, react-doctor/no-derived-useState
+const [localSearch, setLocalSearch] = useState(searchQuery);
+```
+
+Or stack one comment per rule directly above the diagnostic. Stacked comments are honored as long as nothing but other `react-doctor-disable-next-line` comments sits between them and the target line:
+
+```tsx
+// react-doctor-disable-next-line react-doctor/rerender-state-only-in-handlers
+// react-doctor-disable-next-line react-doctor/no-derived-useState
+const [localSearch, setLocalSearch] = useState(searchQuery);
+```
+
+A code line between stacked comments breaks the chain: only the comment immediately above the diagnostic (and any contiguous `react-doctor-disable-next-line` comments stacked on top of it) is honored. If a comment looks adjacent but the rule still fires, run `react-doctor --explain <file:line>` — it reports whether a nearby suppression was found, what rules it covers, and why it didn't apply.
+
+Block comments work inside JSX:
 
 <!-- prettier-ignore -->
 ```tsx
@@ -151,10 +212,11 @@ Options:
   --fail-on <level>       exit with error on diagnostics: error, warning, none
   --annotations           output diagnostics as GitHub Actions annotations
   --explain <file:line>   diagnose why a rule fired or why a suppression didn't apply
+  --why <file:line>       alias for --explain
   -h, --help              display help
 ```
 
-When a suppression isn't working, `--explain <file:line>` reports what the scanner sees at that location, including why a nearby `react-doctor-disable-next-line` didn't apply. The same hint surfaces inline with `--verbose` and in `--json` output as `diagnostic.suppressionHint`.
+When a suppression isn't working, `--explain <file:line>` (or its alias `--why <file:line>`) reports what the scanner sees at that location, including why a nearby `react-doctor-disable-next-line` didn't apply. The diagnosis distinguishes the common failure modes — adjacent comment for a different rule (use the comma form), a code line between the comment and the diagnostic (the chain is broken), or no nearby suppression at all. The same hint surfaces inline with `--verbose` for every flagged site, and in `--json` output as `diagnostic.suppressionHint`, so a single scan doubles as a suppression audit without a separate flag.
 
 `--json` produces a parsable object on stdout with all human-readable output suppressed. Errors still produce a JSON object with `ok: false`, so stdout is always a valid document.
 
@@ -211,15 +273,15 @@ Top React codebases scanned by React Doctor, ranked by score. Updated automatica
 | #  | Repo | Score |
 | -- | ---- | ----: |
 | 1  | [executor](https://github.com/RhysSullivan/executor) | 96 |
-| 2  | [nodejs.org](https://github.com/nodejs/nodejs.org) | 87 |
-| 3  | [tldraw](https://github.com/tldraw/tldraw) | 76 |
-| 4  | [t3code](https://github.com/pingdotgg/t3code) | 75 |
-| 5  | [mastra](https://github.com/mastra-ai/mastra) | 70 |
-| 6  | [excalidraw](https://github.com/excalidraw/excalidraw) | 69 |
-| 7  | [payload](https://github.com/payloadcms/payload) | 69 |
-| 8  | [better-auth](https://github.com/better-auth/better-auth) | 69 |
-| 9  | [rocket.chat](https://github.com/RocketChat/Rocket.Chat) | 67 |
-| 10 | [typebot](https://github.com/baptisteArno/typebot.io) | 66 |
+| 2  | [nodejs.org](https://github.com/nodejs/nodejs.org) | 86 |
+| 3  | [tldraw](https://github.com/tldraw/tldraw) | 70 |
+| 4  | [t3code](https://github.com/pingdotgg/t3code) | 68 |
+| 5  | [better-auth](https://github.com/better-auth/better-auth) | 64 |
+| 6  | [excalidraw](https://github.com/excalidraw/excalidraw) | 63 |
+| 7  | [mastra](https://github.com/mastra-ai/mastra) | 63 |
+| 8  | [payload](https://github.com/payloadcms/payload) | 60 |
+| 9  | [typebot](https://github.com/baptisteArno/typebot.io) | 57 |
+| 10 | [plane](https://github.com/makeplane/plane) | 56 |
 
 <!-- LEADERBOARD:END -->
 

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";
@@ -39,10 +39,18 @@ 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([
-	"node_modules",
-	"dist",
+	".git",
+	".next",
+	".nuxt",
+	".output",
+	".svelte-kit",
+	".turbo",
 	"build",
-	"coverage"
+	"coverage",
+	"dist",
+	"node_modules",
+	"out",
+	"storybook-static"
 ]);
 const CANONICAL_GITHUB_URL = "https://github.com/millionco/react-doctor";
 const SKILL_NAME = "react-doctor";
@@ -304,6 +312,47 @@ const runInstallSkill = async (options = {}) => {
 	}
 };
 //#endregion
+//#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
 const buildHiddenDiagnosticsSummary = (hiddenDiagnostics) => {
 	const errorCount = hiddenDiagnostics.filter((diagnostic) => diagnostic.severity === "error").length;
@@ -802,7 +851,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;
@@ -824,13 +873,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));
@@ -1251,9 +1308,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;
@@ -1270,9 +1327,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);
@@ -1359,7 +1429,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,
@@ -1392,36 +1463,58 @@ const hasReactDependency = (packageJson) => {
 	const allDependencies = collectAllDependencies(packageJson);
 	return Object.keys(allDependencies).some((packageName) => REACT_DEPENDENCY_NAMES.has(packageName));
 };
-const discoverReactSubprojects = (rootDirectory) => {
-	if (!fs.existsSync(rootDirectory) || !fs.statSync(rootDirectory).isDirectory()) return [];
+const toReactWorkspacePackages = (directories) => {
 	const packages = [];
-	const rootPackageJsonPath = path.join(rootDirectory, "package.json");
-	if (isFile(rootPackageJsonPath)) {
-		const rootPackageJson = readPackageJson(rootPackageJsonPath);
-		if (hasReactDependency(rootPackageJson)) {
-			const name = rootPackageJson.name ?? path.basename(rootDirectory);
-			packages.push({
-				name,
-				directory: rootDirectory
-			});
-		}
-	}
-	const entries = fs.readdirSync(rootDirectory, { withFileTypes: true });
-	for (const entry of entries) {
-		if (!entry.isDirectory() || entry.name.startsWith(".") || entry.name === "node_modules") continue;
-		const subdirectory = path.join(rootDirectory, entry.name);
-		const packageJsonPath = path.join(subdirectory, "package.json");
+	for (const directory of directories) {
+		const packageJsonPath = path.join(directory, "package.json");
 		if (!isFile(packageJsonPath)) continue;
 		const packageJson = readPackageJson(packageJsonPath);
 		if (!hasReactDependency(packageJson)) continue;
-		const name = packageJson.name ?? entry.name;
+		const name = packageJson.name ?? path.basename(directory);
 		packages.push({
 			name,
-			directory: subdirectory
+			directory
 		});
 	}
 	return packages;
 };
+const listManifestWorkspacePackages = (rootDirectory) => {
+	if (isFile(path.join(rootDirectory, "package.json"))) return listWorkspacePackages(rootDirectory);
+	const patterns = parsePnpmWorkspacePatterns(rootDirectory);
+	const nxPatterns = patterns.length > 0 ? [] : getNxWorkspaceDirectories(rootDirectory);
+	return toReactWorkspacePackages((patterns.length > 0 ? patterns : nxPatterns).flatMap((pattern) => resolveWorkspaceDirectories(rootDirectory, pattern)));
+};
+const discoverReactSubprojectsByFilesystem = (rootDirectory) => {
+	const packages = [];
+	const pendingDirectories = [rootDirectory];
+	while (pendingDirectories.length > 0) {
+		const currentDirectory = pendingDirectories.shift();
+		if (!currentDirectory) continue;
+		const packageJsonPath = path.join(currentDirectory, "package.json");
+		if (isFile(packageJsonPath)) {
+			const packageJson = readPackageJson(packageJsonPath);
+			if (hasReactDependency(packageJson)) {
+				const name = packageJson.name ?? path.basename(currentDirectory);
+				packages.push({
+					name,
+					directory: currentDirectory
+				});
+			}
+		}
+		const entries = fs.readdirSync(currentDirectory, { withFileTypes: true }).toSorted((firstEntry, secondEntry) => firstEntry.name.localeCompare(secondEntry.name));
+		for (const entry of entries) {
+			if (!entry.isDirectory() || entry.name.startsWith(".") || IGNORED_DIRECTORIES.has(entry.name)) continue;
+			pendingDirectories.push(path.join(currentDirectory, entry.name));
+		}
+	}
+	return packages;
+};
+const discoverReactSubprojects = (rootDirectory) => {
+	if (!fs.existsSync(rootDirectory) || !fs.statSync(rootDirectory).isDirectory()) return [];
+	const manifestPackages = listManifestWorkspacePackages(rootDirectory);
+	if (manifestPackages.length > 0) return manifestPackages;
+	return discoverReactSubprojectsByFilesystem(rootDirectory);
+};
 const listWorkspacePackages = (rootDirectory) => {
 	const packageJsonPath = path.join(rootDirectory, "package.json");
 	if (!isFile(packageJsonPath)) return [];
@@ -1487,15 +1580,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") {
@@ -1569,6 +1663,7 @@ const BOOLEAN_FIELD_NAMES = [
 	"respectInlineDisables",
 	"adoptExistingLintConfig"
 ];
+const STRING_FIELD_NAMES = ["rootDir"];
 const warnConfigField = (message) => {
 	process.stderr.write(`[react-doctor] ${message}\n`);
 };
@@ -1584,6 +1679,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) {
@@ -1593,6 +1692,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
@@ -1604,7 +1710,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)}`);
@@ -1615,7 +1724,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;
@@ -1624,7 +1736,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);
@@ -2260,6 +2372,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",
@@ -2304,6 +2426,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}/`;
@@ -2514,6 +2653,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: {
@@ -2526,11 +2670,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 : {},
@@ -2644,6 +2789,7 @@ const PLUGIN_CATEGORY_MAP = {
 	"react-doctor": "Other",
 	"jsx-a11y": "Accessibility",
 	knip: "Dead Code",
+	effect: "State & Effects",
 	eslint: "Correctness",
 	oxc: "Correctness",
 	typescript: "Correctness",
@@ -3591,7 +3737,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();
@@ -3600,7 +3754,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);
@@ -3612,7 +3766,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);
@@ -4128,7 +4282,7 @@ const promptProjectSelection = async (workspacePackages, rootDirectory) => {
 };
 //#endregion
 //#region src/cli.ts
-const VERSION = "0.1.4";
+const VERSION = "0.1.6";
 const VALID_FAIL_ON_LEVELS = new Set([
 	"error",
 	"warning",
@@ -4307,20 +4461,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, {
@@ -4394,7 +4556,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?.();
 			}
@@ -4438,7 +4600,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({
@@ -4457,13 +4620,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.4"
+		version: "0.1.6"
 	},
 	rules: eslintShapedRules,
 	configs: {

package/dist/index.d.ts

@@ -76,6 +76,24 @@ interface ReactDoctorConfig {
   failOn?: FailOnLevel;
   customRulesOnly?: boolean;
   share?: boolean;
+  /**
+   * Redirect react-doctor at a different project directory than the one
+   * it was invoked against. Resolved relative to the location of the
+   * config file that declared this field (NOT relative to the CWD), so
+   * the redirect is stable no matter where the CLI / `diagnose()` is
+   * run from. Absolute paths are used as-is.
+   *
+   * Typical use: a monorepo root holds the only `react-doctor.config.json`
+   * (so editor tooling and child commands all find it), but the React
+   * app lives in `apps/web`. Setting `"rootDir": "apps/web"` makes
+   * every invocation that loads this config scan that subproject
+   * without anyone needing to `cd` first or pass an explicit path.
+   *
+   * Ignored if the resolved path does not exist or is not a directory
+   * (a warning is emitted and react-doctor falls back to the originally
+   * requested directory).
+   */
+  rootDir?: string;
   textComponents?: string[];
   /**
    * Names of components that safely route string-only children through a
@@ -212,6 +230,34 @@ declare const filterSourceFiles: (filePaths: string[]) => string[];
 //#region src/utils/summarize-diagnostics.d.ts
 declare const summarizeDiagnostics: (diagnostics: Diagnostic[], worstScore?: number | null, worstScoreLabel?: string | null) => JsonReportSummary;
 //#endregion
+//#region src/errors.d.ts
+declare class ReactDoctorError extends Error {
+  readonly name: string;
+  constructor(message: string, options?: ErrorOptions);
+}
+declare class ProjectNotFoundError extends ReactDoctorError {
+  readonly name = "ProjectNotFoundError";
+  readonly directory: string;
+  constructor(directory: string, options?: ErrorOptions);
+}
+declare class NoReactDependencyError extends ReactDoctorError {
+  readonly name = "NoReactDependencyError";
+  readonly directory: string;
+  constructor(directory: string, options?: ErrorOptions);
+}
+declare class PackageJsonNotFoundError extends ReactDoctorError {
+  readonly name = "PackageJsonNotFoundError";
+  readonly directory: string;
+  constructor(directory: string, options?: ErrorOptions);
+}
+declare class AmbiguousProjectError extends ReactDoctorError {
+  readonly name = "AmbiguousProjectError";
+  readonly directory: string;
+  readonly candidates: readonly string[];
+  constructor(directory: string, candidates: readonly string[], options?: ErrorOptions);
+}
+declare const isReactDoctorError: (value: unknown) => value is ReactDoctorError;
+//#endregion
 //#region src/index.d.ts
 declare const clearCaches: () => void;
 interface ToJsonReportOptions {
@@ -222,5 +268,5 @@ interface ToJsonReportOptions {
 declare const toJsonReport: (result: DiagnoseResult, options: ToJsonReportOptions) => JsonReport;
 declare const diagnose: (directory: string, options?: DiagnoseOptions) => Promise<DiagnoseResult>;
 //#endregion
-export { type DiagnoseOptions, type DiagnoseResult, type Diagnostic, type DiffInfo, type JsonReport, type JsonReportDiffInfo, type JsonReportError, type JsonReportMode, type JsonReportProjectEntry, type JsonReportSummary, type ProjectInfo, type ReactDoctorConfig, type ScoreResult, buildJsonReport, buildJsonReportError, clearCaches, diagnose, filterSourceFiles, getDiffInfo, summarizeDiagnostics, toJsonReport };
+export { AmbiguousProjectError, type DiagnoseOptions, type DiagnoseResult, type Diagnostic, type DiffInfo, type JsonReport, type JsonReportDiffInfo, type JsonReportError, type JsonReportMode, type JsonReportProjectEntry, type JsonReportSummary, NoReactDependencyError, PackageJsonNotFoundError, type ProjectInfo, ProjectNotFoundError, type ReactDoctorConfig, ReactDoctorError, type ScoreResult, buildJsonReport, buildJsonReportError, clearCaches, diagnose, filterSourceFiles, getDiffInfo, isReactDoctorError, summarizeDiagnostics, toJsonReport };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -28,14 +28,66 @@ const KNIP_CONFIG_LOCATIONS = [
 ];
 const ADOPTABLE_LINT_CONFIG_FILENAMES = [".oxlintrc.json", ".eslintrc.json"];
 const IGNORED_DIRECTORIES = new Set([
-	"node_modules",
-	"dist",
+	".git",
+	".next",
+	".nuxt",
+	".output",
+	".svelte-kit",
+	".turbo",
 	"build",
-	"coverage"
+	"coverage",
+	"dist",
+	"node_modules",
+	"out",
+	"storybook-static"
 ]);
 const PROXY_OUTPUT_MAX_BYTES = 50 * 1024 * 1024;
 const buildNoReactDependencyError = (directory) => `No React dependency found in ${directory}/package.json. Add "react" to dependencies (or peerDependencies) and re-run.`;
 //#endregion
+//#region src/errors.ts
+var ReactDoctorError = class extends Error {
+	name = "ReactDoctorError";
+	constructor(message, options) {
+		super(message, options);
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+};
+var ProjectNotFoundError = class extends ReactDoctorError {
+	name = "ProjectNotFoundError";
+	directory;
+	constructor(directory, options) {
+		super(`No React project found in ${directory}. Expected a package.json at the directory root or a nested package.json with a React dependency.`, options);
+		this.directory = directory;
+	}
+};
+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;
+	}
+};
+var AmbiguousProjectError = class extends ReactDoctorError {
+	name = "AmbiguousProjectError";
+	directory;
+	candidates;
+	constructor(directory, candidates, options) {
+		super(`Multiple React projects found under ${directory} (${candidates.length} candidates): ${candidates.join(", ")}. Re-run diagnose() with one of those subdirectories, or iterate them yourself.`, options);
+		this.directory = directory;
+		this.candidates = candidates;
+	}
+};
+const isReactDoctorError = (value) => value instanceof ReactDoctorError;
+//#endregion
 //#region src/utils/summarize-diagnostics.ts
 const summarizeDiagnostics = (diagnostics, worstScore = null, worstScoreLabel = null) => {
 	let errorCount = 0;
@@ -770,9 +822,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;
@@ -789,9 +841,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);
@@ -878,7 +943,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,
@@ -902,6 +968,95 @@ const findReactInWorkspaces = (rootDirectory, packageJson) => {
 	}
 	return result;
 };
+const REACT_DEPENDENCY_NAMES = new Set([
+	"react",
+	"react-native",
+	"next"
+]);
+const hasReactDependency = (packageJson) => {
+	const allDependencies = collectAllDependencies(packageJson);
+	return Object.keys(allDependencies).some((packageName) => REACT_DEPENDENCY_NAMES.has(packageName));
+};
+const toReactWorkspacePackages = (directories) => {
+	const packages = [];
+	for (const directory of directories) {
+		const packageJsonPath = path.join(directory, "package.json");
+		if (!isFile(packageJsonPath)) continue;
+		const packageJson = readPackageJson(packageJsonPath);
+		if (!hasReactDependency(packageJson)) continue;
+		const name = packageJson.name ?? path.basename(directory);
+		packages.push({
+			name,
+			directory
+		});
+	}
+	return packages;
+};
+const listManifestWorkspacePackages = (rootDirectory) => {
+	if (isFile(path.join(rootDirectory, "package.json"))) return listWorkspacePackages(rootDirectory);
+	const patterns = parsePnpmWorkspacePatterns(rootDirectory);
+	const nxPatterns = patterns.length > 0 ? [] : getNxWorkspaceDirectories(rootDirectory);
+	return toReactWorkspacePackages((patterns.length > 0 ? patterns : nxPatterns).flatMap((pattern) => resolveWorkspaceDirectories(rootDirectory, pattern)));
+};
+const discoverReactSubprojectsByFilesystem = (rootDirectory) => {
+	const packages = [];
+	const pendingDirectories = [rootDirectory];
+	while (pendingDirectories.length > 0) {
+		const currentDirectory = pendingDirectories.shift();
+		if (!currentDirectory) continue;
+		const packageJsonPath = path.join(currentDirectory, "package.json");
+		if (isFile(packageJsonPath)) {
+			const packageJson = readPackageJson(packageJsonPath);
+			if (hasReactDependency(packageJson)) {
+				const name = packageJson.name ?? path.basename(currentDirectory);
+				packages.push({
+					name,
+					directory: currentDirectory
+				});
+			}
+		}
+		const entries = fs.readdirSync(currentDirectory, { withFileTypes: true }).toSorted((firstEntry, secondEntry) => firstEntry.name.localeCompare(secondEntry.name));
+		for (const entry of entries) {
+			if (!entry.isDirectory() || entry.name.startsWith(".") || IGNORED_DIRECTORIES.has(entry.name)) continue;
+			pendingDirectories.push(path.join(currentDirectory, entry.name));
+		}
+	}
+	return packages;
+};
+const discoverReactSubprojects = (rootDirectory) => {
+	if (!fs.existsSync(rootDirectory) || !fs.statSync(rootDirectory).isDirectory()) return [];
+	const manifestPackages = listManifestWorkspacePackages(rootDirectory);
+	if (manifestPackages.length > 0) return manifestPackages;
+	return discoverReactSubprojectsByFilesystem(rootDirectory);
+};
+const listWorkspacePackages = (rootDirectory) => {
+	const packageJsonPath = path.join(rootDirectory, "package.json");
+	if (!isFile(packageJsonPath)) return [];
+	const packageJson = readPackageJson(packageJsonPath);
+	const patterns = getWorkspacePatterns(rootDirectory, packageJson);
+	if (patterns.length === 0) return [];
+	const packages = [];
+	if (hasReactDependency(packageJson)) {
+		const rootName = packageJson.name ?? path.basename(rootDirectory);
+		packages.push({
+			name: rootName,
+			directory: rootDirectory
+		});
+	}
+	for (const pattern of patterns) {
+		const directories = resolveWorkspaceDirectories(rootDirectory, pattern);
+		for (const workspaceDirectory of directories) {
+			const workspacePackageJson = readPackageJson(path.join(workspaceDirectory, "package.json"));
+			if (!hasReactDependency(workspacePackageJson)) continue;
+			const name = workspacePackageJson.name ?? path.basename(workspaceDirectory);
+			packages.push({
+				name,
+				directory: workspaceDirectory
+			});
+		}
+	}
+	return packages;
+};
 const hasCompilerPackage = (packageJson) => {
 	const allDependencies = collectAllDependencies(packageJson);
 	return Object.keys(allDependencies).some((packageName) => REACT_COMPILER_PACKAGES.has(packageName));
@@ -942,15 +1097,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") {
@@ -996,6 +1152,7 @@ const BOOLEAN_FIELD_NAMES = [
 	"respectInlineDisables",
 	"adoptExistingLintConfig"
 ];
+const STRING_FIELD_NAMES = ["rootDir"];
 const warnConfigField$1 = (message) => {
 	process.stderr.write(`[react-doctor] ${message}\n`);
 };
@@ -1011,6 +1168,10 @@ const coerceMaybeBooleanString = (fieldName, value) => {
 	}
 	warnConfigField$1(`config field "${fieldName}" must be a boolean (got ${typeof value}); ignoring this field.`);
 };
+const validateString = (fieldName, value) => {
+	if (typeof value === "string") return value;
+	warnConfigField$1(`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) {
@@ -1020,6 +1181,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
@@ -1031,7 +1199,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)}`);
@@ -1042,7 +1213,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;
@@ -1054,7 +1228,7 @@ const cachedConfigs = /* @__PURE__ */ new Map();
 const clearConfigCache = () => {
 	cachedConfigs.clear();
 };
-const loadConfig = (rootDirectory) => {
+const loadConfigWithSource = (rootDirectory) => {
 	const cached = cachedConfigs.get(rootDirectory);
 	if (cached !== void 0) return cached;
 	const localConfig = loadConfigFromDirectory(rootDirectory);
@@ -1261,7 +1435,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;
@@ -1283,13 +1457,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));
@@ -1514,6 +1696,31 @@ const createNodeReadFileLinesSync = (rootDirectory) => {
 	};
 };
 //#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/resolve-diagnose-target.ts
+const resolveDiagnoseTarget = (directory) => {
+	if (isFile(path.join(directory, "package.json"))) return directory;
+	const reactSubprojects = discoverReactSubprojects(directory);
+	if (reactSubprojects.length === 0) return null;
+	if (reactSubprojects.length === 1) return reactSubprojects[0].directory;
+	throw new AmbiguousProjectError(directory, reactSubprojects.map((subproject) => path.relative(directory, subproject.directory)).toSorted());
+};
+//#endregion
 //#region src/utils/resolve-lint-include-paths.ts
 const listSourceFilesViaGit = (rootDirectory) => {
 	const result = spawnSync("git", [
@@ -1923,6 +2130,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",
@@ -1967,6 +2184,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}/`;
@@ -2177,6 +2411,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: {
@@ -2189,11 +2428,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 : {},
@@ -2307,6 +2547,7 @@ const PLUGIN_CATEGORY_MAP = {
 	"react-doctor": "Other",
 	"jsx-a11y": "Accessibility",
 	knip: "Dead Code",
+	effect: "State & Effects",
 	eslint: "Correctness",
 	oxc: "Correctness",
 	typescript: "Correctness",
@@ -3078,12 +3319,16 @@ const settledOrEmpty = (settled, label) => {
 };
 const diagnose = async (directory, options = {}) => {
 	const startTime = globalThis.performance.now();
-	const resolvedDirectory = path.resolve(directory);
-	const userConfig = loadConfig(resolvedDirectory);
+	const requestedDirectory = path.resolve(directory);
+	const initialLoadedConfig = loadConfigWithSource(requestedDirectory);
+	const directoryAfterRedirect = resolveConfigRootDir(initialLoadedConfig?.config ?? null, initialLoadedConfig?.sourceDirectory ?? null) ?? requestedDirectory;
+	const resolvedDirectory = resolveDiagnoseTarget(directoryAfterRedirect);
+	if (!resolvedDirectory) throw new ProjectNotFoundError(directoryAfterRedirect);
+	const userConfig = initialLoadedConfig?.config ?? loadConfigWithSource(resolvedDirectory)?.config ?? null;
 	const includePaths = options.includePaths ?? [];
 	const isDiffMode = includePaths.length > 0;
 	const projectInfo = discoverProject(resolvedDirectory);
-	if (!projectInfo.reactVersion) throw new Error(buildNoReactDependencyError(resolvedDirectory));
+	if (!projectInfo.reactVersion) throw new NoReactDependencyError(resolvedDirectory);
 	const lintIncludePaths = computeJsxIncludePaths(includePaths) ?? resolveLintIncludePaths(resolvedDirectory, userConfig);
 	const readFileLinesSync = createNodeReadFileLinesSync(resolvedDirectory);
 	const effectiveLint = options.lint ?? userConfig?.lint ?? true;
@@ -3126,6 +3371,6 @@ const diagnose = async (directory, options = {}) => {
 	};
 };
 //#endregion
-export { buildJsonReport, buildJsonReportError, clearCaches, diagnose, filterSourceFiles, getDiffInfo, summarizeDiagnostics, toJsonReport };
+export { AmbiguousProjectError, NoReactDependencyError, PackageJsonNotFoundError, ProjectNotFoundError, ReactDoctorError, buildJsonReport, buildJsonReportError, clearCaches, diagnose, filterSourceFiles, getDiffInfo, isReactDoctorError, summarizeDiagnostics, toJsonReport };
 
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-doctor",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Diagnose and fix React codebases for security, performance, correctness, accessibility, bundle-size, and architecture issues",
   "keywords": [
     "accessibility",
@@ -69,14 +69,19 @@
   },
   "devDependencies": {
     "@types/prompts": "^2.4.9",
-    "eslint-plugin-react-hooks": "^7.1.1"
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-you-might-not-need-an-effect": "^0.10.1"
   },
   "peerDependencies": {
-    "eslint-plugin-react-hooks": "^6 || ^7"
+    "eslint-plugin-react-hooks": "^6 || ^7",
+    "eslint-plugin-react-you-might-not-need-an-effect": "^0.10"
   },
   "peerDependenciesMeta": {
     "eslint-plugin-react-hooks": {
       "optional": true
+    },
+    "eslint-plugin-react-you-might-not-need-an-effect": {
+      "optional": true
     }
   },
   "engines": {