react-doctor 0.2.14-dev.bb15252 → 0.2.14-dev.bdb9e36

package/dist/index.d.ts

@@ -5,13 +5,35 @@ import * as Cause from "effect/Cause";
 //#region src/types/config.d.ts
 type FailOnLevel = "error" | "warning" | "none";
 interface ReactDoctorIgnoreOverride {
+  /** Glob patterns the override applies to (e.g. `["src/legacy/**"]`). */
   files: string[];
+  /**
+   * Rule keys to suppress for the matched files. Omit (or leave empty) to
+   * suppress every rule for those files.
+   */
   rules?: string[];
 }
 interface ReactDoctorIgnoreConfig {
+  /**
+   * Fully-qualified rule keys (`"<plugin>/<rule>"`) whose diagnostics are
+   * dropped AFTER linting. The rule still runs; its findings are filtered
+   * out. To stop a rule from running at all, set it to `"off"` in the
+   * top-level `rules` map instead. Prefer `react-doctor rules disable
+   * <rule>` to edit this safely.
+   */
   rules?: string[];
+  /**
+   * Glob patterns whose files are excluded from scanning entirely (matched
+   * against paths relative to the scanned directory).
+   */
   files?: string[];
+  /** Per-path rule suppressions — narrower than the top-level `rules`/`files`. */
   overrides?: ReactDoctorIgnoreOverride[];
+  /**
+   * Behavioral tags whose rules are disabled BEFORE linting, skipping a
+   * whole family at once (e.g. `["design", "test-noise", "migration-hint"]`).
+   * Prefer `react-doctor rules ignore-tag <tag>` to edit this safely.
+   */
   tags?: string[];
 }
 /**
@@ -100,11 +122,11 @@ interface ReactDoctorConfig {
   deadCode?: boolean;
   verbose?: boolean;
   /**
-   * Whether to surface `"warning"`-severity diagnostics. Default: `false`
-   * — only `"error"`-severity findings reach any surface (CLI, PR comment,
-   * score, `--fail-on`).
+   * Whether to surface `"warning"`-severity diagnostics. Default: `true`
+   * — every warning reaches every surface (CLI, PR comment, score,
+   * `--fail-on`).
    *
-   * Set to `true` to surface every warning on every surface. This is the
+   * Set to `false` to surface only `"error"`-severity findings. This is the
    * master toggle and runs after per-rule / per-category severity
    * overrides: a rule the user explicitly restamps to `"warn"` (via
    * `rules` / `categories`) still shows even when `warnings` is `false`.
@@ -122,7 +144,7 @@ interface ReactDoctorConfig {
    * 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`
+   * Typical use: a monorepo root holds the only `doctor.config.*`
    * (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
@@ -420,8 +442,8 @@ interface DiagnoseOptions {
   respectInlineDisables?: boolean;
   /**
    * Per-call override for `ReactDoctorConfig.warnings`. See that field's
-   * docs — `"warning"`-severity diagnostics are hidden unless this (or
-   * the config) opts them back in.
+   * docs — `"warning"`-severity diagnostics surface by default unless this
+   * (or the config) opts out via `false`.
    */
   warnings?: boolean;
 }
@@ -444,7 +466,7 @@ interface DiagnoseResult {
  * Scan options (`deadCode`, `lint`, etc.) are flat on the entry and
  * layer on top of the global defaults — omitted fields fall through.
  * `config` is a full `ReactDoctorConfig` override that replaces the
- * on-disk `react-doctor.config.json` for this project's scan.
+ * on-disk `doctor.config.*` for this project's scan.
  */
 //#endregion
 //#region src/types/inspect.d.ts
@@ -742,7 +764,7 @@ interface BuildJsonReportInput {
   totalElapsedMilliseconds: number;
 }
 declare const buildJsonReport: (input: BuildJsonReportInput) => JsonReport; //#endregion
-//#region src/can-oxlint-extend-config.d.ts
+//#region src/build-skipped-checks.d.ts
 //#endregion
 //#region src/get-diff-files.d.ts
 /**

package/dist/index.js

@@ -1,3 +1,5 @@
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="df20b0d3-9e4e-52e0-8991-ce8a6349a04a")}catch(e){}}();
 import { createRequire } from "node:module";
 import * as Schema from "effect/Schema";
 import * as fs$1 from "node:fs";
@@ -16,6 +18,8 @@ import * as Otlp from "effect/unstable/observability/Otlp";
 import * as Context from "effect/Context";
 import os from "node:os";
 import * as Console from "effect/Console";
+import { parseJSON5 } from "confbox";
+import { createJiti } from "jiti";
 import * as Fiber from "effect/Fiber";
 import * as Filter from "effect/Filter";
 import * as Option from "effect/Option";
@@ -3289,7 +3293,14 @@ const STAGED_FILES_PROJECT_CONFIG_FILENAMES = [
 	"tsconfig.json",
 	"tsconfig.base.json",
 	"package.json",
-	"react-doctor.config.json",
+	"doctor.config.ts",
+	"doctor.config.mts",
+	"doctor.config.cts",
+	"doctor.config.js",
+	"doctor.config.mjs",
+	"doctor.config.cjs",
+	"doctor.config.json",
+	"doctor.config.jsonc",
 	"oxlint.json",
 	".oxlintrc.json"
 ];
@@ -4481,69 +4492,109 @@ const validateConfigTypes = (config) => {
 const warn = (message) => {
 	Effect.runSync(Console.warn(message));
 };
-const CONFIG_FILENAME = "react-doctor.config.json";
+const CONFIG_BASENAME = "doctor.config";
+const CONFIG_EXTENSIONS = [
+	"ts",
+	"mts",
+	"cts",
+	"js",
+	"mjs",
+	"cjs",
+	"json",
+	"jsonc"
+];
+const DATA_CONFIG_EXTENSIONS = new Set(["json", "jsonc"]);
+const PACKAGE_JSON_FILENAME = "package.json";
 const PACKAGE_JSON_CONFIG_KEY = "reactDoctor";
-const loadConfigFromDirectory = (directory) => {
-	const configFilePath = path.join(directory, CONFIG_FILENAME);
-	if (isFile(configFilePath)) try {
-		const fileContent = fs.readFileSync(configFilePath, "utf-8");
-		const parsed = JSON.parse(fileContent);
-		if (isPlainObject(parsed)) return {
-			config: validateConfigTypes(parsed),
-			sourceDirectory: directory
-		};
-		warn(`${CONFIG_FILENAME} must be a JSON object, ignoring.`);
-	} catch (error) {
-		warn(`Failed to parse ${CONFIG_FILENAME}: ${error instanceof Error ? error.message : String(error)}`);
-	}
-	const packageJsonPath = path.join(directory, "package.json");
-	if (isFile(packageJsonPath)) try {
-		const fileContent = fs.readFileSync(packageJsonPath, "utf-8");
-		const packageJson = JSON.parse(fileContent);
+const LEGACY_CONFIG_FILENAME = "react-doctor.config.json";
+const jiti = createJiti(import.meta.url);
+const formatError = (error) => error instanceof Error ? error.message : String(error);
+const loadModuleConfig = async (filePath) => {
+	const imported = await jiti.import(filePath);
+	return imported?.default ?? imported;
+};
+const readDataConfig = (filePath) => parseJSON5(fs.readFileSync(filePath, "utf-8"));
+const readEmbeddedPackageJsonConfig = (directory) => {
+	const packageJsonPath = path.join(directory, PACKAGE_JSON_FILENAME);
+	if (!isFile(packageJsonPath)) return null;
+	try {
+		const packageJson = parseJSON5(fs.readFileSync(packageJsonPath, "utf-8"));
 		if (isPlainObject(packageJson)) {
 			const embeddedConfig = packageJson[PACKAGE_JSON_CONFIG_KEY];
-			if (isPlainObject(embeddedConfig)) return {
-				config: validateConfigTypes(embeddedConfig),
-				sourceDirectory: directory
+			if (isPlainObject(embeddedConfig)) return embeddedConfig;
+		}
+	} catch {}
+	return null;
+};
+const loadPackageJsonConfig = (directory) => {
+	const embeddedConfig = readEmbeddedPackageJsonConfig(directory);
+	if (!embeddedConfig) return null;
+	return {
+		config: validateConfigTypes(embeddedConfig),
+		sourceDirectory: directory,
+		configFilePath: path.join(directory, PACKAGE_JSON_FILENAME),
+		format: "package-json"
+	};
+};
+const loadConfigFromDirectory = async (directory) => {
+	let sawBrokenConfigFile = false;
+	for (const extension of CONFIG_EXTENSIONS) {
+		const filePath = path.join(directory, `${CONFIG_BASENAME}.${extension}`);
+		if (!isFile(filePath)) continue;
+		const isDataFile = DATA_CONFIG_EXTENSIONS.has(extension);
+		try {
+			const parsed = isDataFile ? readDataConfig(filePath) : await loadModuleConfig(filePath);
+			if (isPlainObject(parsed)) return {
+				status: "found",
+				loaded: {
+					config: validateConfigTypes(parsed),
+					sourceDirectory: directory,
+					configFilePath: filePath,
+					format: isDataFile ? "json" : "module"
+				}
 			};
+			warn(`${CONFIG_BASENAME}.${extension} must export an object, ignoring.`);
+			sawBrokenConfigFile = true;
+		} catch (error) {
+			warn(`Failed to load ${CONFIG_BASENAME}.${extension}: ${formatError(error)}`);
+			sawBrokenConfigFile = true;
 		}
-	} catch {
-		return null;
 	}
-	return null;
+	const packageJsonConfig = loadPackageJsonConfig(directory);
+	if (packageJsonConfig) return {
+		status: "found",
+		loaded: packageJsonConfig
+	};
+	if (isFile(path.join(directory, LEGACY_CONFIG_FILENAME))) warn(`${LEGACY_CONFIG_FILENAME} is no longer read — rename it to ${CONFIG_BASENAME}.json (or author a ${CONFIG_BASENAME}.ts).`);
+	return {
+		status: sawBrokenConfigFile ? "invalid" : "absent",
+		loaded: null
+	};
 };
 const cachedConfigs = /* @__PURE__ */ new Map();
 const clearConfigCache = () => {
 	cachedConfigs.clear();
 };
-const loadConfigWithSource = (rootDirectory) => {
-	const cached = cachedConfigs.get(rootDirectory);
-	if (cached !== void 0) return cached;
-	const localConfig = loadConfigFromDirectory(rootDirectory);
-	if (localConfig) {
-		cachedConfigs.set(rootDirectory, localConfig);
-		return localConfig;
-	}
-	if (isProjectBoundary(rootDirectory)) {
-		cachedConfigs.set(rootDirectory, null);
-		return null;
-	}
+const loadConfigWalkingUp = async (rootDirectory) => {
+	const localResult = await loadConfigFromDirectory(rootDirectory);
+	if (localResult.status === "found") return localResult.loaded;
+	if (localResult.status === "invalid" || isProjectBoundary(rootDirectory)) return null;
 	let ancestorDirectory = path.dirname(rootDirectory);
 	while (ancestorDirectory !== path.dirname(ancestorDirectory)) {
-		const ancestorConfig = loadConfigFromDirectory(ancestorDirectory);
-		if (ancestorConfig) {
-			cachedConfigs.set(rootDirectory, ancestorConfig);
-			return ancestorConfig;
-		}
-		if (isProjectBoundary(ancestorDirectory)) {
-			cachedConfigs.set(rootDirectory, null);
-			return null;
-		}
+		const ancestorResult = await loadConfigFromDirectory(ancestorDirectory);
+		if (ancestorResult.status === "found") return ancestorResult.loaded;
+		if (isProjectBoundary(ancestorDirectory)) return null;
 		ancestorDirectory = path.dirname(ancestorDirectory);
 	}
-	cachedConfigs.set(rootDirectory, null);
 	return null;
 };
+const loadConfigWithSource = (rootDirectory) => {
+	const cached = cachedConfigs.get(rootDirectory);
+	if (cached !== void 0) return cached;
+	const loadPromise = loadConfigWalkingUp(rootDirectory);
+	cachedConfigs.set(rootDirectory, loadPromise);
+	return loadPromise;
+};
 const resolveConfigRootDir = (config, configSourceDirectory) => {
 	if (!config || !configSourceDirectory) return null;
 	const rawRootDir = config.rootDir;
@@ -4571,8 +4622,7 @@ const resolveDiagnoseTarget = (directory, options = {}) => {
 * (`inspect()`, `diagnose()`, and the CLI's `inspectAction`):
 *
 *   1. Resolve the requested directory to absolute.
-*   2. Load `react-doctor.config.(json|js)` / `package.json#reactDoctor`
-*      if present.
+*   2. Load `doctor.config.*` / `package.json#reactDoctor` if present.
 *   3. Honor `config.rootDir` to redirect the scan to a nested
 *      project root, if configured.
 *   4. Walk into a nested React subproject when the requested
@@ -4590,9 +4640,9 @@ const resolveDiagnoseTarget = (directory, options = {}) => {
 * via its own cache). Routing through `resolveScanTarget` keeps every
 * shell in agreement on what "the scan directory" means.
 */
-const resolveScanTarget = (requestedDirectory, options = {}) => {
+const resolveScanTarget = async (requestedDirectory, options = {}) => {
 	const absoluteRequested = path.resolve(requestedDirectory);
-	const loadedConfig = loadConfigWithSource(absoluteRequested);
+	const loadedConfig = await loadConfigWithSource(absoluteRequested);
 	const userConfig = loadedConfig?.config ?? null;
 	const configSourceDirectory = loadedConfig?.sourceDirectory ?? null;
 	const redirectedDirectory = resolveConfigRootDir(userConfig, configSourceDirectory);
@@ -4916,6 +4966,61 @@ const checkExpoPackageJsonConflicts = (context) => {
 	}));
 	return diagnostics;
 };
+const APP_CONFIG_JSON_FILES = ["app.config.json", "app.json"];
+const APP_CONFIG_DYNAMIC_FILES = [
+	"app.config.ts",
+	"app.config.js",
+	"app.config.cjs",
+	"app.config.mjs"
+];
+const ExpoConfigSchema = Schema.Struct({
+	newArchEnabled: Schema.optional(Schema.Boolean),
+	updates: Schema.optional(Schema.Struct({ disableAntiBrickingMeasures: Schema.optional(Schema.Boolean) }))
+});
+const AppManifestSchema = Schema.Struct({ expo: Schema.optional(ExpoConfigSchema) });
+const NO_CONFIG = {
+	config: null,
+	configFile: null
+};
+const decodeExpoConfig = (filePath) => {
+	let raw;
+	try {
+		raw = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+	} catch {
+		return null;
+	}
+	return Option.getOrNull(Schema.decodeUnknownOption(AppManifestSchema)(raw))?.expo ?? null;
+};
+const readExpoAppConfig = (rootDirectory) => {
+	if (APP_CONFIG_DYNAMIC_FILES.some((fileName) => isFile(path.join(rootDirectory, fileName)))) return NO_CONFIG;
+	for (const fileName of APP_CONFIG_JSON_FILES) {
+		const filePath = path.join(rootDirectory, fileName);
+		if (!isFile(filePath)) continue;
+		const config = decodeExpoConfig(filePath);
+		if (config) return {
+			config,
+			configFile: fileName
+		};
+	}
+	return NO_CONFIG;
+};
+const REANIMATED_PACKAGE = "react-native-reanimated";
+const WORKLETS_PACKAGE = "react-native-worklets";
+const FIRST_NEW_ARCH_ONLY_REANIMATED_MAJOR = 4;
+const checkExpoReanimatedNewArch = (context) => {
+	const reanimatedSpec = context.packageJson.dependencies?.[REANIMATED_PACKAGE] ?? context.packageJson.devDependencies?.[REANIMATED_PACKAGE];
+	const reanimatedMajor = reanimatedSpec === void 0 ? null : getLowestDependencyMajor(reanimatedSpec);
+	if (!(reanimatedMajor !== null && reanimatedMajor >= FIRST_NEW_ARCH_ONLY_REANIMATED_MAJOR || context.directDependencyNames.has(WORKLETS_PACKAGE))) return [];
+	const appConfig = readExpoAppConfig(context.rootDirectory);
+	if (appConfig.config?.newArchEnabled !== false) return [];
+	return [buildExpoDiagnostic({
+		rule: "expo-reanimated-v4-requires-new-arch",
+		severity: "error",
+		filePath: appConfig.configFile ?? "app.json",
+		message: "react-native-reanimated v4 supports only the New Architecture, but `newArchEnabled: false` is set in your app config, so the app will crash on first launch.",
+		help: "Remove `newArchEnabled: false` from your app config (the New Architecture is the default on SDK 52+), or pin react-native-reanimated to v3 if you must stay on the legacy architecture."
+	})];
+};
 const EXPO_ROUTER_REACT_NAVIGATION_MIN_SDK_MAJOR = 56;
 const EXPO_ROUTER_REACT_NAVIGATION_MAX_SDK_MAJOR_EXCLUSIVE = 57;
 const checkExpoRouterReactNavigation = (context) => {
@@ -4931,6 +5036,17 @@ const checkExpoRouterReactNavigation = (context) => {
 		help: "Remove these `@react-navigation/*` packages and replace direct imports with their expo-router equivalents. See https://docs.expo.dev/router/migrate/sdk-55-to-56/"
 	})];
 };
+const checkExpoUpdatesConfig = (context) => {
+	const appConfig = readExpoAppConfig(context.rootDirectory);
+	if (appConfig.config?.updates?.disableAntiBrickingMeasures !== true) return [];
+	return [buildExpoDiagnostic({
+		rule: "expo-updates-no-unsafe-production-config",
+		severity: "error",
+		filePath: appConfig.configFile ?? "app.json",
+		message: "`updates.disableAntiBrickingMeasures: true` disables expo-updates' recovery safeguards and is liable to leave installed apps in a permanently bricked state, so it must not be used in production.",
+		help: "Remove `disableAntiBrickingMeasures` from your app config's `updates` block. See https://docs.expo.dev/versions/latest/config/app/#updates"
+	})];
+};
 const VECTOR_ICONS_MIN_SDK_MAJOR = 56;
 const SCOPED_VECTOR_ICONS_NAMESPACE = "@react-native-vector-icons/";
 const CONFLICTING_VECTOR_ICONS_PACKAGES = ["@expo/vector-icons", "react-native-vector-icons"];
@@ -4957,7 +5073,9 @@ const checkExpoProject = (rootDirectory, project) => {
 		...checkExpoLockfile(context),
 		...checkExpoGitignore(context),
 		...checkExpoEnvLocalFiles(context),
-		...checkExpoMetroConfig(context)
+		...checkExpoMetroConfig(context),
+		...checkExpoReanimatedNewArch(context),
+		...checkExpoUpdatesConfig(context)
 	];
 };
 const PNPM_WORKSPACE_FILE = "pnpm-workspace.yaml";
@@ -5074,6 +5192,69 @@ const checkPnpmHardening = (rootDirectory) => {
 	}));
 	return diagnostics;
 };
+const BUILDER_BOB_PACKAGE = "react-native-builder-bob";
+const isBuilderBobLibrary = (packageJson) => {
+	const bobConfig = packageJson[BUILDER_BOB_PACKAGE];
+	return typeof bobConfig === "object" && bobConfig !== null;
+};
+const checkReactNativeLibraryDependencies = (rootDirectory) => {
+	const packageJson = readPackageJson(path.join(rootDirectory, "package.json"));
+	if (!isBuilderBobLibrary(packageJson)) return [];
+	const misplaced = ["react", "react-native"].filter((name) => packageJson.dependencies?.[name] !== void 0);
+	if (misplaced.length === 0) return [];
+	const quoted = misplaced.map((name) => `"${name}"`).join(" and ");
+	return [{
+		filePath: "package.json",
+		plugin: "react-doctor",
+		rule: "rn-library-react-in-dependencies",
+		severity: "warning",
+		message: `This react-native-builder-bob library lists ${quoted} in \`dependencies\` — that ships a second copy into consumer apps, causing "Invalid hook call" (duplicate React) and duplicate-native-module crashes.`,
+		help: `Move ${quoted} to \`peerDependencies\` (keep ${misplaced.length === 1 ? "it" : "them"} in \`devDependencies\` for local development).`,
+		line: 0,
+		column: 0,
+		category: "Correctness"
+	}];
+};
+const BABEL_CONFIG_FILE_NAMES = [
+	"babel.config.js",
+	"babel.config.cjs",
+	"babel.config.mjs",
+	"babel.config.json",
+	".babelrc",
+	".babelrc.js",
+	".babelrc.json"
+];
+const LEGACY_PRESET_SPEC = "module:metro-react-native-babel-preset";
+const checkReactNativeMetroBabelPreset = (rootDirectory) => {
+	for (const fileName of BABEL_CONFIG_FILE_NAMES) {
+		const filePath = path.join(rootDirectory, fileName);
+		if (!isFile(filePath)) continue;
+		let contents;
+		try {
+			contents = fs.readFileSync(filePath, "utf-8");
+		} catch {
+			continue;
+		}
+		if (!contents.includes(LEGACY_PRESET_SPEC)) continue;
+		return [{
+			filePath: fileName,
+			plugin: "react-doctor",
+			rule: "rn-no-metro-babel-preset",
+			severity: "error",
+			message: "`module:metro-react-native-babel-preset` was renamed to `@react-native/babel-preset` and is no longer installed by React Native 0.73+ — this preset reference fails to resolve and breaks the Metro/Babel transform.",
+			help: "Replace the preset with `module:@react-native/babel-preset` (or `babel-preset-expo` on Expo) and remove the old `metro-react-native-babel-preset` dependency.",
+			line: 0,
+			column: 0,
+			category: "Correctness"
+		}];
+	}
+	return [];
+};
+const isReactNativeProject = (project) => project.framework === "react-native" || project.framework === "expo" || project.hasReactNativeWorkspace || project.expoVersion !== null;
+const checkReactNativeProject = (rootDirectory, project) => {
+	if (!isReactNativeProject(project)) return [];
+	return [...checkReactNativeMetroBabelPreset(rootDirectory), ...checkReactNativeLibraryDependencies(rootDirectory)];
+};
 const REDUCED_MOTION_GREP_PATTERN = "prefers-reduced-motion|useReducedMotion|MotionConfig|reducedMotion";
 const REDUCED_MOTION_FILE_GLOBS = [
 	"*.ts",
@@ -5642,8 +5823,8 @@ var Config = class Config extends Context.Service()("react-doctor/Config") {
 		const cache = yield* Cache.make({
 			capacity: 16,
 			timeToLive: CONFIG_CACHE_TTL_MS,
-			lookup: (directory) => Effect.sync(() => {
-				const loaded = loadConfigWithSource(directory);
+			lookup: (directory) => Effect.promise(async () => {
+				const loaded = await loadConfigWithSource(directory);
 				const redirected = resolveConfigRootDir(loaded?.config ?? null, loaded?.sourceDirectory ?? null);
 				return {
 					config: loaded?.config ?? null,
@@ -7822,7 +8003,7 @@ const runInspect = (input, hooks = {}) => Effect.gen(function* () {
 	const afterLint = hooks.afterLint ?? NO_HOOKS.afterLint;
 	yield* beforeLint(project, lintIncludePaths ?? void 0);
 	const isDiffMode = input.includePaths.length > 0;
-	const showWarnings = input.warnings ?? resolvedConfig.config?.warnings ?? false;
+	const showWarnings = input.warnings ?? resolvedConfig.config?.warnings ?? true;
 	const transform = buildDiagnosticPipeline({
 		rootDirectory: scanDirectory,
 		userConfig: resolvedConfig.config,
@@ -7834,7 +8015,8 @@ const runInspect = (input, hooks = {}) => Effect.gen(function* () {
 	const environmentDiagnostics = isDiffMode ? [] : [
 		...checkReducedMotion(scanDirectory),
 		...checkPnpmHardening(scanDirectory),
-		...checkExpoProject(scanDirectory, project)
+		...checkExpoProject(scanDirectory, project),
+		...checkReactNativeProject(scanDirectory, project)
 	];
 	const envCollected = yield* Stream.runCollect(applyPerElementPipeline(Stream.fromIterable(environmentDiagnostics)));
 	const lintFailure = yield* Ref.make({
@@ -7949,7 +8131,6 @@ const runInspect = (input, hooks = {}) => Effect.gen(function* () {
 	"inspect.isCi": input.isCi,
 	"inspect.scoreSurface": input.scoreSurface ?? "score"
 } }));
-Layer.mergeAll(Project.layerNode, Config.layerNode, DeadCode.layerNode, Files.layerNode, Git.layerNode, Linter.layerOxlint, LintPartialFailures.layerLive, Progress.layerNoop, Reporter.layerNoop, Score.layerHttp);
 const parseNodeVersion = (versionString) => {
 	const [major = 0, minor = 0, patch = 0] = versionString.replace(/^v/, "").trim().split(".").map(Number);
 	return {
@@ -8248,6 +8429,26 @@ const buildJsonReport = (input) => {
 	};
 };
 /**
+* Single source of truth for the skipped-check accounting shared by the
+* CLI renderer (`react-doctor/src/inspect.ts → finalizeAndRender`) and the
+* programmatic shell (`@react-doctor/api → diagnose()`). Both surface a
+* failed lint / dead-code pass instead of a false "all clear", so the
+* branch logic lives here once.
+*/
+const buildSkippedChecks = (input) => {
+	const skippedChecks = [];
+	if (input.didLintFail) skippedChecks.push("lint");
+	if (input.didDeadCodeFail) skippedChecks.push("dead-code");
+	const skippedCheckReasons = {};
+	if (input.didLintFail && input.lintFailureReason !== null) skippedCheckReasons.lint = input.lintFailureReason;
+	else if (input.lintPartialFailures.length > 0) skippedCheckReasons["lint:partial"] = input.lintPartialFailures.join("; ");
+	if (input.didDeadCodeFail && input.deadCodeFailureReason !== null) skippedCheckReasons["dead-code"] = input.deadCodeFailureReason;
+	return {
+		skippedChecks,
+		skippedCheckReasons
+	};
+};
+/**
 * Programmatic façade over `Git.diffSelection`. Async because the
 * Git service runs through Effect's `ChildProcess` (true subprocess
 * spawn, not `spawnSync`).
@@ -8353,7 +8554,7 @@ import_picocolors.default.red, import_picocolors.default.yellow, import_picocolo
 const clearAutoSuppressionCaches = () => {};
 //#endregion
 //#region ../api/dist/index.js
-const DEFAULT_LAYER = Layer.mergeAll(Project.layerNode, Config.layerNode, DeadCode.layerNode, Files.layerNode, Git.layerNode, Linter.layerOxlint, LintPartialFailures.layerLive, Progress.layerNoop, Reporter.layerNoop, Score.layerHttp);
+const buildDiagnoseLayer = (configLayer = Config.layerNode) => Layer.mergeAll(Project.layerNode, configLayer, DeadCode.layerNode, Files.layerNode, Git.layerNode, Linter.layerOxlint, LintPartialFailures.layerLive, Progress.layerNoop, Reporter.layerNoop, Score.layerHttp);
 const buildInspectProgram = (scanTarget, options, configOverride) => {
 	const effectiveConfig = configOverride ?? scanTarget.userConfig;
 	const includePaths = options.includePaths ?? [];
@@ -8362,7 +8563,7 @@ const buildInspectProgram = (scanTarget, options, configOverride) => {
 		includePaths,
 		customRulesOnly: effectiveConfig?.customRulesOnly ?? false,
 		respectInlineDisables: options.respectInlineDisables ?? effectiveConfig?.respectInlineDisables ?? true,
-		warnings: options.warnings ?? effectiveConfig?.warnings ?? false,
+		warnings: options.warnings ?? effectiveConfig?.warnings ?? true,
 		adoptExistingLintConfig: effectiveConfig?.adoptExistingLintConfig ?? true,
 		ignoredTags: new Set(effectiveConfig?.ignore?.tags ?? []),
 		runDeadCode: options.deadCode ?? effectiveConfig?.deadCode ?? true,
@@ -8372,13 +8573,7 @@ const buildInspectProgram = (scanTarget, options, configOverride) => {
 };
 const outputToDiagnoseResult = (output, elapsedMilliseconds) => {
 	if (output.didLintFail && output.lintFailureReason !== null) console.error("Lint failed:", output.lintFailureReason);
-	const skippedChecks = [];
-	if (output.didLintFail) skippedChecks.push("lint");
-	if (output.didDeadCodeFail) skippedChecks.push("dead-code");
-	const skippedCheckReasons = {};
-	if (output.didLintFail && output.lintFailureReason !== null) skippedCheckReasons.lint = output.lintFailureReason;
-	else if (output.lintPartialFailures.length > 0) skippedCheckReasons["lint:partial"] = output.lintPartialFailures.join("; ");
-	if (output.didDeadCodeFail && output.deadCodeFailureReason !== null) skippedCheckReasons["dead-code"] = output.deadCodeFailureReason;
+	const { skippedChecks, skippedCheckReasons } = buildSkippedChecks(output);
 	return {
 		diagnostics: [...output.diagnostics],
 		score: output.score,
@@ -8390,8 +8585,8 @@ const outputToDiagnoseResult = (output, elapsedMilliseconds) => {
 };
 const diagnose = async (directory, options = {}) => {
 	const startTime = globalThis.performance.now();
-	const program = buildInspectProgram(resolveScanTarget(directory), options);
-	return outputToDiagnoseResult(await Effect.runPromise(restoreLegacyThrow(program.pipe(Effect.provide(DEFAULT_LAYER), Effect.provide(layerOtlp)))), globalThis.performance.now() - startTime);
+	const program = buildInspectProgram(await resolveScanTarget(directory), options);
+	return outputToDiagnoseResult(await Effect.runPromise(restoreLegacyThrow(program.pipe(Effect.provide(buildDiagnoseLayer()), Effect.provide(layerOtlp)))), globalThis.performance.now() - startTime);
 };
 //#endregion
 //#region src/index.ts
@@ -8424,4 +8619,5 @@ const toJsonReport = (result, options) => buildJsonReport({
 //#endregion
 export { AmbiguousProjectError, NoReactDependencyError, NotADirectoryError, PackageJsonNotFoundError, ProjectNotFoundError, ReactDoctorError, buildJsonReport, buildJsonReportError, clearCaches, diagnose, filterSourceFiles, getDiffInfo, isProjectDiscoveryError, isReactDoctorError, summarizeDiagnostics, toJsonReport };
 
-//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map
+//# debugId=df20b0d3-9e4e-52e0-8991-ce8a6349a04a

package/dist/skills/doctor-explain/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: doctor-explain
+description: Explain React Doctor rules and configure which ones run via doctor.config.* (or package.json#reactDoctor). Use when the user types `/doctor-explain` or `/doctor-config`, asks why a rule fired, disagrees with a rule, wants to disable/enable a rule, silence a category or tag, tune CI/PR noise, or asks "what does this rule mean". Covers the `react-doctor rules` CLI (list, explain, set, enable, disable, category, ignore-tag) and how config layers combine: ignore.tags disables matching rules before linting, rules over categories sets severity, surfaces controls visibility only.
+version: "1.0.0"
+---
+
+# Doctor Explain
+
+Explains React Doctor rules and edits `doctor.config.*` safely. Use this when a user wants to understand a rule or change which rules run — not for fixing diagnostics (that is the `react-doctor` skill / `/doctor`).
+
+Triggers: `/doctor-explain`, `/doctor-config`, "why did this rule fire", "I disagree with this rule", "turn this rule off", "stop flagging X", "too noisy", "disable design rules".
+
+## Workflow
+
+1. Identify the rule key from the diagnostic (e.g. `react-doctor/no-array-index-as-key`).
+2. Explain it before changing anything:
+
+```bash
+npx react-doctor@latest rules explain react-doctor/no-array-index-as-key
+```
+
+3. Pick the narrowest control that matches the user's intent (see decision guide).
+4. Apply it with a `rules` subcommand (edits your `doctor.config.*` or `package.json#reactDoctor` in place, preserving other fields and formatting).
+5. Validate the change did what they wanted:
+
+```bash
+npx react-doctor@latest --verbose --diff
+```
+
+## Commands
+
+```bash
+npx react-doctor@latest rules list                         # every rule + its effective severity
+npx react-doctor@latest rules list --configured            # only what your config changed
+npx react-doctor@latest rules list --category Performance   # filter by category
+npx react-doctor@latest rules explain <rule>               # why it matters + how to configure
+npx react-doctor@latest rules disable <rule>               # rule never runs
+npx react-doctor@latest rules enable <rule>                # turn back on at its recommended severity
+npx react-doctor@latest rules set <rule> warn              # off | warn | error
+npx react-doctor@latest rules category "React Native" off   # whole category
+npx react-doctor@latest rules ignore-tag design            # skip a rule family (design, test-noise, …)
+npx react-doctor@latest rules unignore-tag design
+```
+
+Rule references accept the full key (`react-doctor/no-danger`), the bare id (`no-danger`), or a legacy key (`react/no-danger`).
+
+## Decision guide
+
+Match the control to the intent — prefer the narrowest one:
+
+- **User disagrees with one rule / it's a false positive for them** → `rules disable <rule>` (sets `rules.<key> = "off"`; the rule stops running everywhere). This is the default for "I don't want this rule".
+- **Rule is fine but wrong severity** → `rules set <rule> warn` or `rules set <rule> error`.
+- **A disabled-by-default rule they want on** → `rules enable <rule>`.
+- **A whole area is unwanted** (e.g. all React Native rules) → `rules category "<Category>" off`.
+- **A behavioral family is noisy** (`design`, `test-noise`, `migration-hint`) → `rules ignore-tag <tag>`.
+- **Keep it locally but hide from PR comment / score / CI gate only** → do NOT disable. Edit `surfaces` in your config (`surfaces.prComment.excludeRules`, `surfaces.score.excludeTags`, `surfaces.ciFailure.excludeCategories`). The rule still shows in local `cli` output.
+
+How the layers combine: `ignore.tags` disables every rule carrying that tag **before** linting, so a tagged rule stays off even if `rules`/`categories` set it to `warn`/`error` (a rule-level override cannot re-enable a tag-ignored rule). For rules that aren't tag-disabled, `rules` overrides `categories` overrides the rule's default. `surfaces` is visibility-only and never changes whether a rule runs.
+
+## Config shape
+
+Config lives in `doctor.config.ts` (or `.js`/`.mjs`/`.cjs`/`.json`/`.jsonc`), or the `reactDoctor` key in `package.json`. The `rules` commands edit whichever exists — TS/JS edits preserve formatting (via magicast) — and create `doctor.config.json` when none does, stamping `$schema`:
+
+```ts
+// doctor.config.ts
+export default {
+  rules: { "react-doctor/no-array-index-as-key": "off" },
+  categories: { "React Native": "warn" },
+  ignore: { tags: ["design"] },
+};
+```
+
+## Educating the user
+
+When explaining a rule, lead with the "Why it matters" guidance from `rules explain` and, when they want depth, the per-rule recipe at `https://www.react.doctor/prompts/rules/<plugin>/<rule>.md`. Only after they understand it should you offer to disable it — many "bad" rules are catching real issues.

package/dist/skills/react-doctor/SKILL.md

@@ -32,6 +32,10 @@ The playbook is the single source of truth — a scan → filter → triage →
 
 Pair it with the matching per-rule prompts at `https://www.react.doctor/prompts/rules/<plugin>/<rule>.md` (fetched on demand inside the playbook) so each fix uses the canonical, reviewer-tested recipe.
 
+## Configuring or explaining rules
+
+When the user wants to understand a rule, disagrees with one, or wants to disable / tune which rules run (not fix code), use the `doctor-explain` skill (alias `/doctor-config`). Start with `npx react-doctor@latest rules explain <rule>`, then apply the narrowest control via `npx react-doctor@latest rules disable|set|category|ignore-tag …`, which edits your `doctor.config.*` (or `package.json#reactDoctor`).
+
 ## Command
 
 ```bash