react-doctor 0.2.14-dev.938376 → 0.2.14-dev.9777f1a

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[];
 }
 /**
@@ -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
@@ -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

package/dist/index.js

@@ -16,6 +16,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 +3291,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,43 +4490,80 @@ 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);
+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 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;
-	if (isFile(configFilePath)) {
+	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 fileContent = fs.readFileSync(configFilePath, "utf-8");
-			const parsed = JSON.parse(fileContent);
+			const parsed = isDataFile ? readDataConfig(filePath) : await loadModuleConfig(filePath);
 			if (isPlainObject(parsed)) return {
 				status: "found",
 				loaded: {
 					config: validateConfigTypes(parsed),
-					sourceDirectory: directory
+					sourceDirectory: directory,
+					configFilePath: filePath,
+					format: isDataFile ? "json" : "module"
 				}
 			};
-			warn(`${CONFIG_FILENAME} must be a JSON object, ignoring.`);
+			warn(`${CONFIG_BASENAME}.${extension} must export an object, ignoring.`);
+			sawBrokenConfigFile = true;
 		} catch (error) {
-			warn(`Failed to parse ${CONFIG_FILENAME}: ${error instanceof Error ? error.message : String(error)}`);
+			warn(`Failed to load ${CONFIG_BASENAME}.${extension}: ${formatError(error)}`);
+			sawBrokenConfigFile = true;
 		}
-		sawBrokenConfigFile = true;
 	}
-	const packageJsonPath = path.join(directory, "package.json");
-	if (isFile(packageJsonPath)) try {
-		const fileContent = fs.readFileSync(packageJsonPath, "utf-8");
-		const packageJson = JSON.parse(fileContent);
-		if (isPlainObject(packageJson)) {
-			const embeddedConfig = packageJson[PACKAGE_JSON_CONFIG_KEY];
-			if (isPlainObject(embeddedConfig)) return {
-				status: "found",
-				loaded: {
-					config: validateConfigTypes(embeddedConfig),
-					sourceDirectory: directory
-				}
-			};
-		}
-	} catch {}
+	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
@@ -4527,34 +4573,26 @@ const cachedConfigs = /* @__PURE__ */ new Map();
 const clearConfigCache = () => {
 	cachedConfigs.clear();
 };
-const loadConfigWithSource = (rootDirectory) => {
-	const cached = cachedConfigs.get(rootDirectory);
-	if (cached !== void 0) return cached;
-	const localResult = loadConfigFromDirectory(rootDirectory);
-	if (localResult.status === "found") {
-		cachedConfigs.set(rootDirectory, localResult.loaded);
-		return localResult.loaded;
-	}
-	if (localResult.status === "invalid" || 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 ancestorResult = loadConfigFromDirectory(ancestorDirectory);
-		if (ancestorResult.status === "found") {
-			cachedConfigs.set(rootDirectory, ancestorResult.loaded);
-			return ancestorResult.loaded;
-		}
-		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;
@@ -4582,8 +4620,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
@@ -4601,9 +4638,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);
@@ -5653,8 +5690,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,
@@ -8414,7 +8451,7 @@ const outputToDiagnoseResult = (output, elapsedMilliseconds) => {
 };
 const diagnose = async (directory, options = {}) => {
 	const startTime = globalThis.performance.now();
-	const program = buildInspectProgram(resolveScanTarget(directory), options);
+	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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-doctor",
-  "version": "0.2.14-dev.0938376",
+  "version": "0.2.14-dev.9777f1a",
   "description": "Diagnose and fix React codebases for security, performance, correctness, accessibility, bundle-size, and architecture issues",
   "keywords": [
     "accessibility",
@@ -54,13 +54,16 @@
     "@sentry/node": "^10.54.0",
     "agent-install": "0.0.5",
     "conf": "^15.1.0",
+    "confbox": "^0.2.4",
     "deslop-js": "^0.0.14",
     "effect": "4.0.0-beta.70",
     "eslint-plugin-react-hooks": "^7.1.1",
+    "jiti": "^2.7.0",
+    "magicast": "^0.5.3",
     "oxlint": "^1.66.0",
     "prompts": "^2.4.2",
     "typescript": ">=5.0.4 <7",
-    "oxlint-plugin-react-doctor": "0.2.14-dev.0938376"
+    "oxlint-plugin-react-doctor": "0.2.14-dev.9777f1a"
   },
   "devDependencies": {
     "@types/babel__code-frame": "^7.27.0",
@@ -68,8 +71,8 @@
     "@xterm/headless": "^6.0.0",
     "commander": "^14.0.3",
     "ora": "^9.4.0",
-    "@react-doctor/core": "0.2.14",
-    "@react-doctor/api": "0.2.14"
+    "@react-doctor/api": "0.2.14",
+    "@react-doctor/core": "0.2.14"
   },
   "engines": {
     "node": "^20.19.0 || >=22.12.0"