react-doctor 0.2.0-beta.4 → 0.2.0-beta.5

package/README.md

@@ -113,6 +113,25 @@ React Doctor respects `.gitignore`, `.eslintignore`, `.oxlintignore`, `.prettier
 
 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.
 
+#### Surface controls (CLI, PR comments, score, CI failure)
+
+Diagnostics flow through four independent surfaces — `cli`, `prComment`, `score`, and `ciFailure` — and each one can be tuned per tag, category, or rule id. By default the `design` tag (Tailwind shorthand cleanup like `w-5 h-5 → size-5`, pure-black backgrounds, gradient text, …) stays visible on the local CLI but is excluded from the PR comment, the score, and the `--fail-on` gate so style cleanup can't dilute meaningful React findings:
+
+```json
+{
+  "surfaces": {
+    "prComment": {
+      "includeTags": ["design"],
+      "excludeCategories": ["Performance"]
+    },
+    "score": { "includeRules": ["react-doctor/design-no-redundant-size-axes"] },
+    "ciFailure": { "excludeTags": ["test-noise"] }
+  }
+}
+```
+
+Each surface accepts `includeTags`, `excludeTags`, `includeCategories`, `excludeCategories`, `includeRules`, and `excludeRules`. Include wins over exclude when both match. Run the CLI with `--pr-comment` (the GitHub Action passes it automatically when `github-token` is set) to apply the `prComment` surface to the printed output destined for sticky PR comments.
+
 #### 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.
@@ -210,6 +229,8 @@ Options:
   --offline               skip the score API and share URL (no score shown)
   --fail-on <level>       exit with error on diagnostics: error, warning, none
   --annotations           output diagnostics as GitHub Actions annotations
+  --pr-comment            tune CLI output for sticky PR comments (drops design
+                          cleanup from the printed list and fail-on gate)
   --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
@@ -235,6 +256,7 @@ When a suppression isn't working, `--explain <file:line>` (or its alias `--why <
 | `offline`                  | `boolean`                        | `false`  |
 | `textComponents`           | `string[]`                       | `[]`     |
 | `rawTextWrapperComponents` | `string[]`                       | `[]`     |
+| `serverAuthFunctionNames`  | `string[]`                       | `[]`     |
 | `respectInlineDisables`    | `boolean`                        | `true`   |
 | `adoptExistingLintConfig`  | `boolean`                        | `true`   |
 | `ignore.tags`              | `string[]`                       | `[]`     |
@@ -243,10 +265,34 @@ When a suppression isn't working, `--explain <file:line>` (or its alias `--why <
 
 `rawTextWrapperComponents` is the narrower option for components that are not text elements but safely route string-only children through an internal `<Text>` (e.g. `heroui-native`'s `Button`, which stringifies its children and renders them through a `ButtonLabel`). Listed wrappers suppress `rn-no-raw-text` only when their children are entirely stringifiable. A wrapper with mixed children — e.g. `<Button>Save<Icon /></Button>` — still reports because the wrapper can't safely route raw text alongside a sibling JSX element.
 
+`serverAuthFunctionNames` teaches `server-auth-actions` about custom auth guards your codebase wraps around its auth library (e.g. `requireWorkspaceMember`, `ensureSignedIn`). Listed names are accepted as a valid top-of-action auth check whether called bare (`requireWorkspaceMember()`) or as a member (`guards.requireWorkspaceMember()`), and — unlike the built-in default list — are treated as distinctive so the receiver is not re-validated.
+
 `ignore.tags` suppresses entire categories of rules by tag. For example, `"tags": ["design"]` disables all opinionated design rules (gradient text, pure black backgrounds, side tab borders, default Tailwind palettes). Available tags: `"design"`.
 
 `offline` skips the score API entirely — no score is shown and no share URL is generated. Automatically enabled in CI environments (GitHub Actions, GitLab CI, CircleCI) so CI runs don't depend on the network.
 
+### React Native rules in mixed monorepos
+
+`rn-*` rules respect per-package boundaries automatically. In a mixed React Native + web monorepo (`apps/mobile` alongside `apps/web` / `apps/vite-app` / `packages/storybook` / `apps/docs`), every `rn-*` rule walks up to the file's nearest `package.json` before running:
+
+- Packages that declare `react-native`, `react-native-tvos`, `expo`, `expo-router`, `@expo/*`, `react-native-windows`, `react-native-macos`, anything under the `@react-native/` or `@react-native-` namespaces (`@react-native-firebase/app`, `@react-native-async-storage/async-storage`, …), or Metro's top-level `"react-native"` resolution field → rules ON.
+- Packages that declare a web-only framework (`next`, `vite`, `react-scripts`, `gatsby`, `@remix-run/*`, `@docusaurus/*`, `@storybook/*`, or plain `react-dom` without an RN sibling) → rules OFF.
+- Packages with no clear local signal → fall back to the project-level framework detection.
+
+File extensions override the package classification when they're unambiguous: `*.web.tsx` / `*.web.jsx` are always skipped (Metro resolves these only against `react-native-web`); `*.ios.tsx` / `*.android.tsx` / `*.native.tsx` are always scanned (mobile-only).
+
+The detection is bidirectional: a web-rooted monorepo (root `package.json` declares `next` or `vite`) still loads the `rn-*` rules when any workspace targets React Native — the file-level boundary then keeps them silent on the web workspaces and active on the mobile ones.
+
+`rn-no-raw-text` additionally short-circuits raw text inside platform-fork branches:
+
+- `if (Platform.OS === "web") { … }` consequent — and the `else` branch of `if (Platform.OS !== "web")`.
+- `Platform.OS === "web" ? <X /> : …` ternaries, `Platform.OS === "web" && <X />` short-circuits, and the reversed-operand form `"web" === Platform.OS`.
+- `switch (Platform.OS) { case "web": … }` case bodies (other cases still report).
+- `Platform.select({ web: <X />, default: <Y /> })` — only the `web` arm is exempt.
+- `Platform?.OS === "web"` (optional chain) and `Platform.OS! === "web"` (TS non-null assertion) parse the same way as the bare form.
+
+The walker stops at function and `Program` boundaries — JSX defined inside a callback hoisted out of a `Platform.OS` branch does not inherit the parent guard. Negative platform checks like `Platform.OS === "ios"` are deliberately NOT treated as web exemptions; only the explicit web branch is.
+
 ## Scoring
 
 The health score formula: `100 - (unique_error_rules x 1.5) - (unique_warning_rules x 0.75)`.

package/dist/cli.js

@@ -12,6 +12,25 @@ import { randomUUID } from "node:crypto";
 import basePrompts from "prompts";
 import { fileURLToPath } from "node:url";
 import { SKILL_MANIFEST_FILE, detectInstalledSkillAgents, getSkillAgentConfig, getSkillAgentTypes, installSkillsFromSource } from "agent-install";
+//#region ../types/dist/index.js
+const REACT_NATIVE_DEPENDENCY_NAMES = new Set([
+	"react-native",
+	"react-native-tvos",
+	"expo",
+	"expo-router",
+	"@expo/cli",
+	"@expo/metro-config",
+	"@expo/metro-runtime",
+	"react-native-windows",
+	"react-native-macos"
+]);
+const REACT_NATIVE_DEPENDENCY_PREFIXES = ["@react-native/", "@react-native-"];
+const isReactNativeDependencyName = (dependencyName) => {
+	if (REACT_NATIVE_DEPENDENCY_NAMES.has(dependencyName)) return true;
+	for (const prefix of REACT_NATIVE_DEPENDENCY_PREFIXES) if (dependencyName.startsWith(prefix)) return true;
+	return false;
+};
+//#endregion
 //#region ../project-info/dist/index.js
 var ReactDoctorError = class extends Error {
 	name = "ReactDoctorError";
@@ -648,6 +667,34 @@ const findDependencyInfoFromMonorepoRoot = (directory) => {
 		framework: rootInfo.framework !== "unknown" ? rootInfo.framework : workspaceInfo.framework
 	};
 };
+const containsAnyReactNativeDependency = (section) => {
+	if (!section) return false;
+	for (const dependencyName of Object.keys(section)) if (isReactNativeDependencyName(dependencyName)) return true;
+	return false;
+};
+const isPackageJsonReactNativeAware = (packageJson) => {
+	if (typeof packageJson["react-native"] === "string") return true;
+	if (containsAnyReactNativeDependency(packageJson.dependencies)) return true;
+	if (containsAnyReactNativeDependency(packageJson.devDependencies)) return true;
+	if (containsAnyReactNativeDependency(packageJson.peerDependencies)) return true;
+	if (containsAnyReactNativeDependency(packageJson.optionalDependencies)) return true;
+	return false;
+};
+const hasReactNativeWorkspaceAnywhere = (rootDirectory, rootPackageJson) => {
+	if (isPackageJsonReactNativeAware(rootPackageJson)) return true;
+	const patterns = getWorkspacePatterns(rootDirectory, rootPackageJson);
+	if (patterns.length === 0) return false;
+	const visitedDirectories = /* @__PURE__ */ new Set();
+	for (const pattern of patterns) {
+		const directories = resolveWorkspaceDirectories(rootDirectory, pattern);
+		for (const workspaceDirectory of directories) {
+			if (visitedDirectories.has(workspaceDirectory)) continue;
+			visitedDirectories.add(workspaceDirectory);
+			if (isPackageJsonReactNativeAware(readPackageJson(path.join(workspaceDirectory, "package.json")))) return true;
+		}
+	}
+	return false;
+};
 const TANSTACK_QUERY_PACKAGES = new Set([
 	"@tanstack/react-query",
 	"@tanstack/query-core",
@@ -820,6 +867,7 @@ const discoverProject = (directory) => {
 	const projectName = packageJson.name ?? path.basename(directory);
 	const hasTypeScript = fs.existsSync(path.join(directory, "tsconfig.json"));
 	const sourceFileCount = countSourceFiles(directory);
+	const hasReactNativeWorkspace = framework === "expo" || framework === "react-native" || hasReactNativeWorkspaceAnywhere(directory, packageJson);
 	const projectInfo = {
 		rootDirectory: directory,
 		projectName,
@@ -830,6 +878,7 @@ const discoverProject = (directory) => {
 		hasTypeScript,
 		hasReactCompiler: detectReactCompiler(directory, packageJson),
 		hasTanStackQuery: hasTanStackQuery(packageJson),
+		hasReactNativeWorkspace,
 		sourceFileCount
 	};
 	cachedProjectInfos.set(directory, projectInfo);
@@ -1850,6 +1899,71 @@ const detectUserLintConfigPaths = (rootDirectory) => {
 	}
 	return [];
 };
+const DIAGNOSTIC_SURFACES = [
+	"cli",
+	"prComment",
+	"score",
+	"ciFailure"
+];
+const isDiagnosticSurface = (value) => typeof value === "string" && DIAGNOSTIC_SURFACES.includes(value);
+/**
+* Built-in surface exclusions applied before any user config.
+*
+* `design`-tagged rules are weak-signal style cleanup — they still ship
+* to the local CLI so developers see them while editing, but they're
+* removed from the PR comment surface, the score, and the CI gate so
+* they can't bury real React findings or fail a build over a Tailwind
+* shorthand. Override per-surface via `config.surfaces.<surface>` to
+* promote individual rules back in by tag, category, or rule id.
+*/
+const DEFAULT_SURFACE_EXCLUDED_TAGS = {
+	cli: [],
+	prComment: ["design"],
+	score: ["design"],
+	ciFailure: ["design"]
+};
+const toStringSet = (values) => {
+	if (!values || values.length === 0) return /* @__PURE__ */ new Set();
+	const collected = /* @__PURE__ */ new Set();
+	for (const value of values) if (typeof value === "string" && value.length > 0) collected.add(value);
+	return collected;
+};
+const buildResolvedControls = (surface, userControls) => {
+	const baseExcludeTags = new Set(DEFAULT_SURFACE_EXCLUDED_TAGS[surface]);
+	const userIncludeTags = toStringSet(userControls?.includeTags);
+	for (const includedTag of userIncludeTags) baseExcludeTags.delete(includedTag);
+	const userExcludeTags = toStringSet(userControls?.excludeTags);
+	for (const excludedTag of userExcludeTags) baseExcludeTags.add(excludedTag);
+	return {
+		includeTags: userIncludeTags,
+		excludeTags: baseExcludeTags,
+		includeCategories: toStringSet(userControls?.includeCategories),
+		excludeCategories: toStringSet(userControls?.excludeCategories),
+		includeRuleKeys: toStringSet(userControls?.includeRules),
+		excludeRuleKeys: toStringSet(userControls?.excludeRules)
+	};
+};
+const getRuleTags = (diagnostic) => {
+	if (diagnostic.plugin !== "react-doctor") return [];
+	return reactDoctorPlugin.rules[diagnostic.rule]?.tags ?? [];
+};
+const intersectsAny = (values, candidateSet) => {
+	for (const value of values) if (candidateSet.has(value)) return true;
+	return false;
+};
+const isDiagnosticOnSurface = (diagnostic, surface, config) => {
+	const resolved = buildResolvedControls(surface, config?.surfaces?.[surface]);
+	const ruleKey = `${diagnostic.plugin}/${diagnostic.rule}`;
+	const tags = getRuleTags(diagnostic);
+	if (resolved.includeRuleKeys.has(ruleKey)) return true;
+	if (resolved.includeCategories.has(diagnostic.category)) return true;
+	if (intersectsAny(tags, resolved.includeTags)) return true;
+	if (resolved.excludeRuleKeys.has(ruleKey)) return false;
+	if (resolved.excludeCategories.has(diagnostic.category)) return false;
+	if (intersectsAny(tags, resolved.excludeTags)) return false;
+	return true;
+};
+const filterDiagnosticsForSurface = (diagnostics, surface, config) => diagnostics.filter((diagnostic) => isDiagnosticOnSurface(diagnostic, surface, config));
 const runGit = (cwd, args) => {
 	const result = spawnSync("git", args, {
 		cwd,
@@ -1996,6 +2110,61 @@ 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 SURFACE_CONTROL_FIELD_NAMES = [
+	"includeTags",
+	"excludeTags",
+	"includeCategories",
+	"excludeCategories",
+	"includeRules",
+	"excludeRules"
+];
+const validateStringArrayField = (fieldName, value) => {
+	if (value === void 0) return void 0;
+	if (!Array.isArray(value)) {
+		warnConfigField(`config field "${fieldName}" must be an array of strings (got ${typeof value}); ignoring this field.`);
+		return;
+	}
+	const collected = [];
+	for (const entry of value) {
+		if (typeof entry !== "string") {
+			warnConfigField(`config field "${fieldName}" contains a non-string entry (${typeof entry}); ignoring the entry.`);
+			continue;
+		}
+		collected.push(entry);
+	}
+	return collected;
+};
+const validateSurfaceControls = (surface, rawControls) => {
+	if (rawControls === void 0) return void 0;
+	if (typeof rawControls !== "object" || rawControls === null || Array.isArray(rawControls)) {
+		warnConfigField(`config field "surfaces.${surface}" must be an object (got ${typeof rawControls}); ignoring this surface.`);
+		return;
+	}
+	const validated = {};
+	for (const fieldName of SURFACE_CONTROL_FIELD_NAMES) {
+		const value = rawControls[fieldName];
+		const validatedValue = validateStringArrayField(`surfaces.${surface}.${fieldName}`, value);
+		if (validatedValue !== void 0) validated[fieldName] = validatedValue;
+	}
+	return validated;
+};
+const validateSurfacesField = (rawSurfaces) => {
+	if (rawSurfaces === void 0) return void 0;
+	if (typeof rawSurfaces !== "object" || rawSurfaces === null || Array.isArray(rawSurfaces)) {
+		warnConfigField(`config field "surfaces" must be an object (got ${typeof rawSurfaces}); ignoring this field.`);
+		return;
+	}
+	const validated = {};
+	for (const [key, value] of Object.entries(rawSurfaces)) {
+		if (!isDiagnosticSurface(key)) {
+			warnConfigField(`config field "surfaces.${key}" is not a known surface (expected one of: ${DIAGNOSTIC_SURFACES.join(", ")}); ignoring.`);
+			continue;
+		}
+		const controls = validateSurfaceControls(key, value);
+		if (controls !== void 0) validated[key] = controls;
+	}
+	return validated;
+};
 const validateConfigTypes = (config) => {
 	const validated = { ...config };
 	for (const fieldName of BOOLEAN_FIELD_NAMES) {
@@ -2012,6 +2181,11 @@ const validateConfigTypes = (config) => {
 		if (validatedString === void 0) delete validated[fieldName];
 		else validated[fieldName] = validatedString;
 	}
+	if (config.surfaces !== void 0) {
+		const validatedSurfaces = validateSurfacesField(config.surfaces);
+		if (validatedSurfaces === void 0) delete validated.surfaces;
+		else validated.surfaces = validatedSurfaces;
+	}
 	return validated;
 };
 const CONFIG_FILENAME = "react-doctor.config.json";
@@ -2313,7 +2487,7 @@ const dedupeDiagnostics = (diagnostics) => {
 const buildCapabilities = (project) => {
 	const capabilities = /* @__PURE__ */ new Set();
 	capabilities.add(project.framework);
-	if (project.framework === "expo" || project.framework === "react-native") capabilities.add("react-native");
+	if (project.framework === "expo" || project.framework === "react-native" || project.hasReactNativeWorkspace) capabilities.add("react-native");
 	const reactMajor = project.reactMajorVersion;
 	if (reactMajor !== null) for (let major = 17; major <= reactMajor; major++) capabilities.add(`react:${major}`);
 	if (project.tailwindVersion !== null) {
@@ -2453,7 +2627,11 @@ const BUILTIN_A11Y_RULES = {
 	"jsx-a11y/no-distracting-elements": "error",
 	"jsx-a11y/iframe-has-title": "warn"
 };
-const createOxlintConfig = ({ pluginPath, project, customRulesOnly = false, extendsPaths = [], ignoredTags = /* @__PURE__ */ new Set() }) => {
+const resolveSettingsRootDirectory = (rootDirectory) => {
+	if (!fs.existsSync(rootDirectory)) return rootDirectory;
+	return fs.realpathSync(rootDirectory);
+};
+const createOxlintConfig = ({ pluginPath, project, customRulesOnly = false, extendsPaths = [], ignoredTags = /* @__PURE__ */ new Set(), serverAuthFunctionNames }) => {
 	const reactHooksJsPlugin = resolveReactHooksJsPlugin(project.hasReactCompiler, customRulesOnly);
 	const reactCompilerRules = reactHooksJsPlugin ? filterRulesToAvailable(REACT_COMPILER_RULES, "react-hooks-js", reactHooksJsPlugin.availableRuleNames) : {};
 	const youMightNotNeedEffectPlugin = resolveYouMightNotNeedEffectPlugin(customRulesOnly);
@@ -2482,6 +2660,11 @@ const createOxlintConfig = ({ pluginPath, project, customRulesOnly = false, exte
 		},
 		plugins: customRulesOnly ? [] : ["react", "jsx-a11y"],
 		jsPlugins: [...jsPlugins, pluginPath],
+		settings: { "react-doctor": {
+			framework: project.framework,
+			rootDirectory: resolveSettingsRootDirectory(project.rootDirectory),
+			...serverAuthFunctionNames && serverAuthFunctionNames.length > 0 ? { serverAuthFunctionNames: [...serverAuthFunctionNames] } : {}
+		} },
 		rules: {
 			...customRulesOnly ? {} : BUILTIN_REACT_RULES,
 			...customRulesOnly ? {} : BUILTIN_A11Y_RULES,
@@ -2784,7 +2967,25 @@ const shouldSuppressLocalUseHookDiagnostic = (diagnostic, rootDirectory) => {
 	const bindingResolution = resolveUseCallBinding(sourceText, absolutePath, primaryLabel.span.offset);
 	return bindingResolution !== null && !bindingResolution.isReactUseBinding;
 };
-const getRuleRecommendation = (ruleName) => reactDoctorPlugin.rules[ruleName]?.recommendation;
+const getPublicEnvPrefix = (framework) => {
+	switch (framework) {
+		case "nextjs": return "NEXT_PUBLIC_*";
+		case "vite":
+		case "tanstack-start": return "VITE_*";
+		case "cra": return "REACT_APP_*";
+		case "gatsby": return "GATSBY_*";
+		default: return null;
+	}
+};
+const buildNoSecretsRecommendation = (project, fallbackRecommendation) => {
+	const publicEnvPrefix = getPublicEnvPrefix(project.framework);
+	if (!publicEnvPrefix) return fallbackRecommendation;
+	return `Move secrets to server-only code. In ${formatFrameworkName(project.framework)}, only \`${publicEnvPrefix}\` env vars are exposed to the browser, and they must not contain secrets`;
+};
+const getRuleRecommendation = (ruleName, project) => {
+	if (ruleName === "no-secrets-in-client-code") return buildNoSecretsRecommendation(project, reactDoctorPlugin.rules["no-secrets-in-client-code"]?.recommendation ?? "Move secrets to server-only code");
+	return reactDoctorPlugin.rules[ruleName]?.recommendation;
+};
 const getRuleCategory = (ruleName) => reactDoctorPlugin.rules[ruleName]?.category;
 const esmRequire = createRequire(import.meta.url);
 const PLUGIN_CATEGORY_MAP = {
@@ -2809,14 +3010,14 @@ const PLUGIN_CATEGORY_MAP = {
 const FILEPATH_WITH_LOCATION_PATTERN = /\S+\.\w+:\d+:\d+[\s\S]*$/;
 const REACT_COMPILER_MESSAGE = "React Compiler can't optimize this code";
 const lookupOwnString = (record, key) => Object.hasOwn(record, key) ? record[key] : void 0;
-const cleanDiagnosticMessage = (message, help, plugin, rule) => {
+const cleanDiagnosticMessage = (message, help, plugin, rule, project) => {
 	if (plugin === "react-hooks-js") return {
 		message: REACT_COMPILER_MESSAGE,
 		help: message.replace(FILEPATH_WITH_LOCATION_PATTERN, "").trim() || help
 	};
 	return {
 		message: message.replace(FILEPATH_WITH_LOCATION_PATTERN, "").trim() || message,
-		help: help || getRuleRecommendation(rule) || ""
+		help: help || getRuleRecommendation(rule, project) || ""
 	};
 };
 const parseRuleCode = (code) => {
@@ -2919,7 +3120,7 @@ const isOxlintOutput = (value) => {
 	const candidate = value;
 	return Array.isArray(candidate.diagnostics);
 };
-const parseOxlintOutput = (stdout, rootDirectory) => {
+const parseOxlintOutput = (stdout, project, rootDirectory) => {
 	if (!stdout) return [];
 	const jsonStart = stdout.indexOf("{");
 	const sanitizedStdout = jsonStart > 0 ? stdout.slice(jsonStart) : stdout;
@@ -2933,7 +3134,7 @@ const parseOxlintOutput = (stdout, rootDirectory) => {
 	return parsed.diagnostics.filter((diagnostic) => diagnostic.code && SOURCE_FILE_PATTERN.test(diagnostic.filename) && !shouldSuppressLocalUseHookDiagnostic(diagnostic, rootDirectory)).map((diagnostic) => {
 		const { plugin, rule } = parseRuleCode(diagnostic.code);
 		const primaryLabel = diagnostic.labels[0];
-		const cleaned = cleanDiagnosticMessage(diagnostic.message, diagnostic.help, plugin, rule);
+		const cleaned = cleanDiagnosticMessage(diagnostic.message, diagnostic.help, plugin, rule, project);
 		return {
 			filePath: diagnostic.filename,
 			plugin,
@@ -2963,7 +3164,7 @@ const validateRuleRegistration = () => {
 	for (const fullKey of ALL_REACT_DOCTOR_RULE_KEYS) {
 		const ruleName = fullKey.replace(/^react-doctor\//, "");
 		if (!getRuleCategory(ruleName)) missingCategory.push(fullKey);
-		if (!getRuleRecommendation(ruleName)) missingHelp.push(fullKey);
+		if (!reactDoctorPlugin.rules[ruleName]?.recommendation) missingHelp.push(fullKey);
 		if (FRAMEWORK_SPECIFIC_RULE_KEYS.has(fullKey) && !reactDoctorPlugin.rules[ruleName]?.requires) missingMetadata.push(fullKey);
 	}
 	if (missingCategory.length > 0 || missingHelp.length > 0 || missingMetadata.length > 0) {
@@ -2976,7 +3177,8 @@ const validateRuleRegistration = () => {
 	}
 };
 const runOxlint = async (options) => {
-	const { rootDirectory, project, includePaths, nodeBinaryPath = process.execPath, customRulesOnly = false, respectInlineDisables = true, adoptExistingLintConfig = true, ignoredTags = /* @__PURE__ */ new Set(), onPartialFailure } = options;
+	const { rootDirectory, project, includePaths, nodeBinaryPath = process.execPath, customRulesOnly = false, respectInlineDisables = true, adoptExistingLintConfig = true, ignoredTags = /* @__PURE__ */ new Set(), userConfig, onPartialFailure } = options;
+	const serverAuthFunctionNames = Array.isArray(userConfig?.serverAuthFunctionNames) ? userConfig.serverAuthFunctionNames.filter((entry) => typeof entry === "string" && entry.length > 0) : void 0;
 	validateRuleRegistration();
 	if (includePaths !== void 0 && includePaths.length === 0) return [];
 	const configDirectory = fs.mkdtempSync(path.join(os.tmpdir(), "react-doctor-oxlintrc-"));
@@ -2988,7 +3190,8 @@ const runOxlint = async (options) => {
 		project,
 		customRulesOnly,
 		extendsPaths,
-		ignoredTags
+		ignoredTags,
+		serverAuthFunctionNames
 	});
 	const restoreDisableDirectives = respectInlineDisables ? () => {} : neutralizeDisableDirectives(rootDirectory, includePaths);
 	try {
@@ -3025,7 +3228,7 @@ const runOxlint = async (options) => {
 			const spawnLintBatch = async (batch) => {
 				const batchArgs = [...baseArgs, ...batch];
 				try {
-					return parseOxlintOutput(await spawnOxlint(batchArgs, rootDirectory, nodeBinaryPath), rootDirectory);
+					return parseOxlintOutput(await spawnOxlint(batchArgs, rootDirectory, nodeBinaryPath), project, rootDirectory);
 				} catch (error) {
 					if (!isSplittableOxlintBatchError(error)) throw error;
 					if (batch.length <= 1) {
@@ -3055,7 +3258,8 @@ const runOxlint = async (options) => {
 				project,
 				customRulesOnly,
 				extendsPaths: [],
-				ignoredTags
+				ignoredTags,
+				serverAuthFunctionNames
 			}));
 			return await spawnLintBatches();
 		}
@@ -3585,7 +3789,8 @@ const mergeInspectOptions = (inputOptions, userConfig) => ({
 	share: userConfig?.share ?? true,
 	respectInlineDisables: inputOptions.respectInlineDisables ?? userConfig?.respectInlineDisables ?? true,
 	adoptExistingLintConfig: userConfig?.adoptExistingLintConfig ?? true,
-	ignoredTags: buildIgnoredTags(userConfig)
+	ignoredTags: buildIgnoredTags(userConfig),
+	outputSurface: inputOptions.outputSurface ?? "cli"
 });
 const inspect = async (directory, inputOptions = {}) => {
 	const startTime = performance.now();
@@ -3643,6 +3848,7 @@ const runInspect = async (directory, options, userConfig, startTime) => {
 					respectInlineDisables: options.respectInlineDisables,
 					adoptExistingLintConfig: options.adoptExistingLintConfig,
 					ignoredTags: options.ignoredTags,
+					userConfig,
 					onPartialFailure: (reason) => lintPartialFailures.push(reason)
 				});
 				lintSpinner?.succeed("Running lint checks.");
@@ -3670,7 +3876,8 @@ const runInspect = async (directory, options, userConfig, startTime) => {
 	const skippedChecks = [];
 	if (didLintFail) skippedChecks.push("lint");
 	const hasSkippedChecks = skippedChecks.length > 0;
-	const scoreResult = options.offline ? null : await calculateScore(diagnostics);
+	const scoreDiagnostics = filterDiagnosticsForSurface(diagnostics, "score", userConfig);
+	const scoreResult = options.offline ? null : await calculateScore(scoreDiagnostics);
 	const noScoreMessage = options.offline ? "Score unavailable in offline mode." : "Score unavailable (could not reach the score API).";
 	const skippedCheckReasons = {};
 	if (didLintFail && lintFailureReason !== null) skippedCheckReasons.lint = lintFailureReason;
@@ -3688,11 +3895,14 @@ const runInspect = async (directory, options, userConfig, startTime) => {
 		else logger.dim(noScoreMessage);
 		return buildResult();
 	}
-	if (diagnostics.length === 0) {
+	const surfaceDiagnostics = filterDiagnosticsForSurface(diagnostics, options.outputSurface, userConfig);
+	const demotedDiagnosticCount = diagnostics.length - surfaceDiagnostics.length;
+	if (surfaceDiagnostics.length === 0) {
 		if (hasSkippedChecks) {
 			const skippedLabel = skippedChecks.join(" and ");
 			logger.warn(`No issues detected, but ${skippedLabel} checks failed — results are incomplete.`);
-		} else logger.success("No issues found!");
+		} else if (demotedDiagnosticCount > 0) logger.success(`No issues found! (${demotedDiagnosticCount} demoted from the ${options.outputSurface} surface — see config.surfaces.)`);
+		else logger.success("No issues found!");
 		logger.break();
 		if (hasSkippedChecks) {
 			printBrandingOnlyHeader();
@@ -3702,10 +3912,14 @@ const runInspect = async (directory, options, userConfig, startTime) => {
 		return buildResult();
 	}
 	logger.break();
-	printDiagnostics(diagnostics, options.verbose, directory);
+	printDiagnostics(surfaceDiagnostics, options.verbose, directory);
+	if (demotedDiagnosticCount > 0) {
+		logger.log(highlighter.gray(`  ${demotedDiagnosticCount} demoted from the ${options.outputSurface} surface (e.g. design cleanup) — run \`npx react-doctor@latest .\` locally for the full list.`));
+		logger.break();
+	}
 	const displayedSourceFileCount = isDiffMode ? includePaths.length : lintSourceFileCount;
 	const shouldShowShareLink = !options.offline && options.share;
-	printSummary(diagnostics, elapsedMilliseconds, scoreResult, projectInfo.projectName, displayedSourceFileCount, noScoreMessage, !shouldShowShareLink);
+	printSummary(surfaceDiagnostics, elapsedMilliseconds, scoreResult, projectInfo.projectName, displayedSourceFileCount, noScoreMessage, !shouldShowShareLink);
 	if (hasSkippedChecks) {
 		const skippedLabel = skippedChecks.join(" and ");
 		logger.break();
@@ -3805,7 +4019,7 @@ const CI_ENVIRONMENT_VARIABLES = [
 const isCiEnvironment = () => CI_ENVIRONMENT_VARIABLES.some((envVariable) => Boolean(process.env[envVariable])) || process.env.CI === "true";
 //#endregion
 //#region src/cli/utils/version.ts
-const VERSION = "0.2.0-beta.4";
+const VERSION = "0.2.0-beta.5";
 //#endregion
 //#region src/cli/utils/json-mode.ts
 let context = null;
@@ -3871,7 +4085,8 @@ const resolveCliInspectOptions = (flags, userConfig) => ({
 	scoreOnly: Boolean(flags.score),
 	offline: Boolean(flags.offline) || (userConfig?.offline ?? false) || isCiEnvironment(),
 	silent: Boolean(flags.json),
-	respectInlineDisables: flags.respectInlineDisables ?? userConfig?.respectInlineDisables ?? true
+	respectInlineDisables: flags.respectInlineDisables ?? userConfig?.respectInlineDisables ?? true,
+	outputSurface: flags.prComment ? "prComment" : "cli"
 });
 //#endregion
 //#region src/cli/utils/resolve-diff-mode.ts
@@ -4096,6 +4311,7 @@ const validateModeFlags = (flags) => {
 	if (exclusiveModes.length > 1) throw new Error(`Cannot combine ${exclusiveModes.join(" and ")}; pick one mode.`);
 	if (flags.yes && flags.full) throw new Error("Cannot combine --yes and --full; pick one.");
 	if (flags.score && flags.json) throw new Error("Cannot combine --score and --json; pick one output mode.");
+	if (flags.prComment && (flags.json || flags.score)) throw new Error("--pr-comment cannot be combined with --json or --score.");
 	if (flags.annotations && (flags.json || flags.score)) throw new Error("--annotations cannot be combined with --json or --score.");
 	if (flags.explain !== void 0 && flags.why !== void 0) throw new Error("Use --explain or --why, not both — they're aliases of the same flag.");
 	if ((flags.explain ?? flags.why) !== void 0 && (flags.json || flags.score || flags.annotations || flags.staged)) throw new Error("--explain cannot be combined with --json, --score, --annotations, or --staged.");
@@ -4193,7 +4409,8 @@ const inspectAction = async (directory, flags) => {
 					totalElapsedMilliseconds: performance.now() - startTime
 				}));
 				if (flags.annotations) printAnnotations(remappedDiagnostics, isJsonMode);
-				if (!isScoreOnly && shouldFailForDiagnostics(remappedDiagnostics, resolveFailOnLevel(flags, userConfig))) process.exitCode = 1;
+				const ciFailureDiagnostics = filterDiagnosticsForSurface(remappedDiagnostics, "ciFailure", userConfig);
+				if (!isScoreOnly && shouldFailForDiagnostics(ciFailureDiagnostics, resolveFailOnLevel(flags, userConfig))) process.exitCode = 1;
 			} finally {
 				snapshot.cleanup();
 			}
@@ -4256,7 +4473,8 @@ const inspectAction = async (directory, flags) => {
 			totalElapsedMilliseconds: performance.now() - startTime
 		}));
 		if (flags.annotations) printAnnotations(allDiagnostics, isJsonMode);
-		if (!isScoreOnly && shouldFailForDiagnostics(allDiagnostics, resolveFailOnLevel(flags, userConfig))) process.exitCode = 1;
+		const ciFailureDiagnostics = filterDiagnosticsForSurface(allDiagnostics, "ciFailure", userConfig);
+		if (!isScoreOnly && shouldFailForDiagnostics(ciFailureDiagnostics, resolveFailOnLevel(flags, userConfig))) process.exitCode = 1;
 	} catch (error) {
 		if (isJsonMode) {
 			writeJsonErrorReport(error);
@@ -4387,7 +4605,7 @@ const exitGracefully = () => {
 //#region src/cli/index.ts
 process.on("SIGINT", exitGracefully);
 process.on("SIGTERM", exitGracefully);
-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("--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 the score API and the share URL (no score is shown)").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 (default: 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").addHelpText("after", `
+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("--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 the score API and the share URL (no score is shown)").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 (default: error)").option("--annotations", "output diagnostics as GitHub Actions annotations").option("--pr-comment", "tune CLI output for sticky PR comments (drops weak-signal rule families like `design` from the printed list and the fail-on gate; configure via config.surfaces)").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").addHelpText("after", `
 ${highlighter.dim("Configuration:")}
   Place a ${highlighter.info("react-doctor.config.json")} (or ${highlighter.info("\"reactDoctor\"")} key in your package.json) in the project root.
   CLI flags always override config values. See the README for the full schema.

package/dist/index.d.ts

@@ -11,6 +11,52 @@ interface ReactDoctorIgnoreConfig {
   overrides?: ReactDoctorIgnoreOverride[];
   tags?: string[];
 }
+/**
+ * Discrete output channels a diagnostic can flow through after a scan.
+ * Each surface is filtered independently so a rule can be visible
+ * locally but excluded from PR comments, the score, or the CI gate:
+ *
+ * - `cli` — local terminal output from `react-doctor` (`printDiagnostics`).
+ * - `prComment` — output captured by the GitHub Action for the sticky
+ *   PR comment. Enabled when the CLI is run with `--pr-comment` (the
+ *   action sets this automatically when `github-token` is provided).
+ * - `score` — diagnostics shipped to the React Doctor score API
+ *   (or counted toward local score calculations).
+ * - `ciFailure` — diagnostics that count toward the `--fail-on` exit
+ *   code gate. A diagnostic excluded from this surface never fails the
+ *   build, regardless of severity.
+ *
+ * Defaults: design rules (tag `"design"`) are excluded from `prComment`,
+ * `score`, and `ciFailure` so style cleanup doesn't dilute meaningful
+ * React findings. They remain in `cli` so locally-running developers
+ * still see the suggestion when they touch the file.
+ */
+type DiagnosticSurface = "cli" | "prComment" | "score" | "ciFailure";
+interface SurfaceControls {
+  /**
+   * Tag names whose diagnostics should be force-included on the surface,
+   * even if a default or category-level exclusion would otherwise drop
+   * them. Include wins over exclude when both apply to the same rule.
+   */
+  includeTags?: string[];
+  /**
+   * Tag names whose diagnostics should be excluded from the surface.
+   * Use this to silence whole rule families (e.g. `["design"]`,
+   * `["test-noise"]`) for a single channel without touching others.
+   */
+  excludeTags?: string[];
+  /** Category names (e.g. `"Architecture"`) to force-include. */
+  includeCategories?: string[];
+  /** Category names (e.g. `"Architecture"`) to exclude. */
+  excludeCategories?: string[];
+  /**
+   * Fully-qualified rule keys (`"<plugin>/<rule>"`, e.g.
+   * `"react-doctor/design-no-redundant-size-axes"`) to force-include.
+   */
+  includeRules?: string[];
+  /** Fully-qualified rule keys to exclude from this surface. */
+  excludeRules?: string[];
+}
 interface ReactDoctorConfig {
   ignore?: ReactDoctorIgnoreConfig;
   lint?: boolean;
@@ -56,6 +102,20 @@ interface ReactDoctorConfig {
    * suppresses regardless of sibling content.
    */
   rawTextWrapperComponents?: string[];
+  /**
+   * Project-level allowlist of function names that the
+   * `server-auth-actions` rule treats as an auth check at the top of
+   * a server action. Names are accepted whether called as a bare
+   * identifier (`myAuthGuard()`) or as the final property of a
+   * member call (`ctx.myAuthGuard()`); unlike the built-in default
+   * list, user-provided names are treated as distinctive and never
+   * subject to receiver-object disambiguation.
+   *
+   * Use this to teach react-doctor about custom auth guards in
+   * codebases that wrap their auth library — e.g. a project-local
+   * `requireWorkspaceMember` or `ensureSignedIn`.
+   */
+  serverAuthFunctionNames?: string[];
   /**
    * Whether to respect inline `// eslint-disable*`, `// oxlint-disable*`,
    * and `// react-doctor-disable*` comments in source files. Default: `true`.
@@ -96,6 +156,26 @@ interface ReactDoctorConfig {
    * Set to `false` to scan only react-doctor's curated rule set.
    */
   adoptExistingLintConfig?: boolean;
+  /**
+   * Per-surface include/exclude controls. Each `DiagnosticSurface` is
+   * resolved independently against rule tags, category, and id so a
+   * single rule can be visible locally yet hidden from PR comments,
+   * neutralized from the score, and excluded from `--fail-on` — all
+   * without touching the rule's severity or activation.
+   *
+   * Defaults (applied before user overrides):
+   *
+   * - `prComment` excludes tag `"design"`
+   * - `score` excludes tag `"design"`
+   * - `ciFailure` excludes tag `"design"`
+   *
+   * Pass any controls block (even an empty `{}`) to keep the default
+   * exclusions; the user's include/exclude entries layer on top.
+   * Include entries always win over exclude entries — handy for
+   * promoting a single high-signal `design-*` rule back into the
+   * score or PR-comment surface.
+   */
+  surfaces?: Partial<Record<DiagnosticSurface, SurfaceControls>>;
 } //#endregion
 //#region src/diagnostic.d.ts
 interface Diagnostic {
@@ -124,6 +204,20 @@ interface ProjectInfo {
   hasTypeScript: boolean;
   hasReactCompiler: boolean;
   hasTanStackQuery: boolean;
+  /**
+   * `true` when the project (or any of its workspace packages) declares
+   * React Native or Expo as a dependency. Enables the `react-native`
+   * capability — and therefore every `rn-*` rule — even on web-rooted
+   * monorepos where the entry-point `package.json` is Next / Vite /
+   * Remix but a sibling workspace (`apps/mobile`, `packages/native-ui`)
+   * targets React Native. The file-level package-boundary check in
+   * `oxlint-plugin-react-doctor` still keeps the rules silent on the
+   * web workspaces.
+   *
+   * `false` collapses the gate to the legacy "framework is RN" behavior
+   * — no `rn-*` rules load for the project at all.
+   */
+  hasReactNativeWorkspace: boolean;
   sourceFileCount: number;
 }
 //#endregion

package/dist/index.js

@@ -5,6 +5,25 @@ import { spawn, spawnSync } from "node:child_process";
 import reactDoctorPlugin, { ALL_REACT_DOCTOR_RULE_KEYS, FRAMEWORK_SPECIFIC_RULE_KEYS, MOTION_LIBRARY_PACKAGES } from "oxlint-plugin-react-doctor";
 import os from "node:os";
 import * as ts from "typescript";
+//#region ../types/dist/index.js
+const REACT_NATIVE_DEPENDENCY_NAMES = new Set([
+	"react-native",
+	"react-native-tvos",
+	"expo",
+	"expo-router",
+	"@expo/cli",
+	"@expo/metro-config",
+	"@expo/metro-runtime",
+	"react-native-windows",
+	"react-native-macos"
+]);
+const REACT_NATIVE_DEPENDENCY_PREFIXES = ["@react-native/", "@react-native-"];
+const isReactNativeDependencyName = (dependencyName) => {
+	if (REACT_NATIVE_DEPENDENCY_NAMES.has(dependencyName)) return true;
+	for (const prefix of REACT_NATIVE_DEPENDENCY_PREFIXES) if (dependencyName.startsWith(prefix)) return true;
+	return false;
+};
+//#endregion
 //#region ../project-info/dist/index.js
 var ReactDoctorError = class extends Error {
 	name = "ReactDoctorError";
@@ -225,6 +244,18 @@ const FRAMEWORK_PACKAGES = {
 	expo: "expo",
 	"react-native": "react-native"
 };
+const FRAMEWORK_DISPLAY_NAMES = {
+	nextjs: "Next.js",
+	"tanstack-start": "TanStack Start",
+	vite: "Vite",
+	cra: "Create React App",
+	remix: "Remix",
+	gatsby: "Gatsby",
+	expo: "Expo",
+	"react-native": "React Native",
+	unknown: "React"
+};
+const formatFrameworkName = (framework) => FRAMEWORK_DISPLAY_NAMES[framework];
 const detectFramework = (dependencies) => {
 	for (const [packageName, frameworkName] of Object.entries(FRAMEWORK_PACKAGES)) if (dependencies[packageName]) return frameworkName;
 	return "unknown";
@@ -651,6 +682,34 @@ const findDependencyInfoFromMonorepoRoot = (directory) => {
 		framework: rootInfo.framework !== "unknown" ? rootInfo.framework : workspaceInfo.framework
 	};
 };
+const containsAnyReactNativeDependency = (section) => {
+	if (!section) return false;
+	for (const dependencyName of Object.keys(section)) if (isReactNativeDependencyName(dependencyName)) return true;
+	return false;
+};
+const isPackageJsonReactNativeAware = (packageJson) => {
+	if (typeof packageJson["react-native"] === "string") return true;
+	if (containsAnyReactNativeDependency(packageJson.dependencies)) return true;
+	if (containsAnyReactNativeDependency(packageJson.devDependencies)) return true;
+	if (containsAnyReactNativeDependency(packageJson.peerDependencies)) return true;
+	if (containsAnyReactNativeDependency(packageJson.optionalDependencies)) return true;
+	return false;
+};
+const hasReactNativeWorkspaceAnywhere = (rootDirectory, rootPackageJson) => {
+	if (isPackageJsonReactNativeAware(rootPackageJson)) return true;
+	const patterns = getWorkspacePatterns(rootDirectory, rootPackageJson);
+	if (patterns.length === 0) return false;
+	const visitedDirectories = /* @__PURE__ */ new Set();
+	for (const pattern of patterns) {
+		const directories = resolveWorkspaceDirectories(rootDirectory, pattern);
+		for (const workspaceDirectory of directories) {
+			if (visitedDirectories.has(workspaceDirectory)) continue;
+			visitedDirectories.add(workspaceDirectory);
+			if (isPackageJsonReactNativeAware(readPackageJson(path.join(workspaceDirectory, "package.json")))) return true;
+		}
+	}
+	return false;
+};
 const TANSTACK_QUERY_PACKAGES = new Set([
 	"@tanstack/react-query",
 	"@tanstack/query-core",
@@ -826,6 +885,7 @@ const discoverProject = (directory) => {
 	const projectName = packageJson.name ?? path.basename(directory);
 	const hasTypeScript = fs.existsSync(path.join(directory, "tsconfig.json"));
 	const sourceFileCount = countSourceFiles(directory);
+	const hasReactNativeWorkspace = framework === "expo" || framework === "react-native" || hasReactNativeWorkspaceAnywhere(directory, packageJson);
 	const projectInfo = {
 		rootDirectory: directory,
 		projectName,
@@ -836,6 +896,7 @@ const discoverProject = (directory) => {
 		hasTypeScript,
 		hasReactCompiler: detectReactCompiler(directory, packageJson),
 		hasTanStackQuery: hasTanStackQuery(packageJson),
+		hasReactNativeWorkspace,
 		sourceFileCount
 	};
 	cachedProjectInfos.set(directory, projectInfo);
@@ -1843,6 +1904,13 @@ const detectUserLintConfigPaths = (rootDirectory) => {
 	}
 	return [];
 };
+const DIAGNOSTIC_SURFACES = [
+	"cli",
+	"prComment",
+	"score",
+	"ciFailure"
+];
+const isDiagnosticSurface = (value) => typeof value === "string" && DIAGNOSTIC_SURFACES.includes(value);
 const runGit = (cwd, args) => {
 	const result = spawnSync("git", args, {
 		cwd,
@@ -1989,6 +2057,61 @@ 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 SURFACE_CONTROL_FIELD_NAMES = [
+	"includeTags",
+	"excludeTags",
+	"includeCategories",
+	"excludeCategories",
+	"includeRules",
+	"excludeRules"
+];
+const validateStringArrayField = (fieldName, value) => {
+	if (value === void 0) return void 0;
+	if (!Array.isArray(value)) {
+		warnConfigField(`config field "${fieldName}" must be an array of strings (got ${typeof value}); ignoring this field.`);
+		return;
+	}
+	const collected = [];
+	for (const entry of value) {
+		if (typeof entry !== "string") {
+			warnConfigField(`config field "${fieldName}" contains a non-string entry (${typeof entry}); ignoring the entry.`);
+			continue;
+		}
+		collected.push(entry);
+	}
+	return collected;
+};
+const validateSurfaceControls = (surface, rawControls) => {
+	if (rawControls === void 0) return void 0;
+	if (typeof rawControls !== "object" || rawControls === null || Array.isArray(rawControls)) {
+		warnConfigField(`config field "surfaces.${surface}" must be an object (got ${typeof rawControls}); ignoring this surface.`);
+		return;
+	}
+	const validated = {};
+	for (const fieldName of SURFACE_CONTROL_FIELD_NAMES) {
+		const value = rawControls[fieldName];
+		const validatedValue = validateStringArrayField(`surfaces.${surface}.${fieldName}`, value);
+		if (validatedValue !== void 0) validated[fieldName] = validatedValue;
+	}
+	return validated;
+};
+const validateSurfacesField = (rawSurfaces) => {
+	if (rawSurfaces === void 0) return void 0;
+	if (typeof rawSurfaces !== "object" || rawSurfaces === null || Array.isArray(rawSurfaces)) {
+		warnConfigField(`config field "surfaces" must be an object (got ${typeof rawSurfaces}); ignoring this field.`);
+		return;
+	}
+	const validated = {};
+	for (const [key, value] of Object.entries(rawSurfaces)) {
+		if (!isDiagnosticSurface(key)) {
+			warnConfigField(`config field "surfaces.${key}" is not a known surface (expected one of: ${DIAGNOSTIC_SURFACES.join(", ")}); ignoring.`);
+			continue;
+		}
+		const controls = validateSurfaceControls(key, value);
+		if (controls !== void 0) validated[key] = controls;
+	}
+	return validated;
+};
 const validateConfigTypes = (config) => {
 	const validated = { ...config };
 	for (const fieldName of BOOLEAN_FIELD_NAMES) {
@@ -2005,6 +2128,11 @@ const validateConfigTypes = (config) => {
 		if (validatedString === void 0) delete validated[fieldName];
 		else validated[fieldName] = validatedString;
 	}
+	if (config.surfaces !== void 0) {
+		const validatedSurfaces = validateSurfacesField(config.surfaces);
+		if (validatedSurfaces === void 0) delete validated.surfaces;
+		else validated.surfaces = validatedSurfaces;
+	}
 	return validated;
 };
 const CONFIG_FILENAME = "react-doctor.config.json";
@@ -2242,7 +2370,7 @@ const dedupeDiagnostics = (diagnostics) => {
 const buildCapabilities = (project) => {
 	const capabilities = /* @__PURE__ */ new Set();
 	capabilities.add(project.framework);
-	if (project.framework === "expo" || project.framework === "react-native") capabilities.add("react-native");
+	if (project.framework === "expo" || project.framework === "react-native" || project.hasReactNativeWorkspace) capabilities.add("react-native");
 	const reactMajor = project.reactMajorVersion;
 	if (reactMajor !== null) for (let major = 17; major <= reactMajor; major++) capabilities.add(`react:${major}`);
 	if (project.tailwindVersion !== null) {
@@ -2382,7 +2510,11 @@ const BUILTIN_A11Y_RULES = {
 	"jsx-a11y/no-distracting-elements": "error",
 	"jsx-a11y/iframe-has-title": "warn"
 };
-const createOxlintConfig = ({ pluginPath, project, customRulesOnly = false, extendsPaths = [], ignoredTags = /* @__PURE__ */ new Set() }) => {
+const resolveSettingsRootDirectory = (rootDirectory) => {
+	if (!fs.existsSync(rootDirectory)) return rootDirectory;
+	return fs.realpathSync(rootDirectory);
+};
+const createOxlintConfig = ({ pluginPath, project, customRulesOnly = false, extendsPaths = [], ignoredTags = /* @__PURE__ */ new Set(), serverAuthFunctionNames }) => {
 	const reactHooksJsPlugin = resolveReactHooksJsPlugin(project.hasReactCompiler, customRulesOnly);
 	const reactCompilerRules = reactHooksJsPlugin ? filterRulesToAvailable(REACT_COMPILER_RULES, "react-hooks-js", reactHooksJsPlugin.availableRuleNames) : {};
 	const youMightNotNeedEffectPlugin = resolveYouMightNotNeedEffectPlugin(customRulesOnly);
@@ -2411,6 +2543,11 @@ const createOxlintConfig = ({ pluginPath, project, customRulesOnly = false, exte
 		},
 		plugins: customRulesOnly ? [] : ["react", "jsx-a11y"],
 		jsPlugins: [...jsPlugins, pluginPath],
+		settings: { "react-doctor": {
+			framework: project.framework,
+			rootDirectory: resolveSettingsRootDirectory(project.rootDirectory),
+			...serverAuthFunctionNames && serverAuthFunctionNames.length > 0 ? { serverAuthFunctionNames: [...serverAuthFunctionNames] } : {}
+		} },
 		rules: {
 			...customRulesOnly ? {} : BUILTIN_REACT_RULES,
 			...customRulesOnly ? {} : BUILTIN_A11Y_RULES,
@@ -2713,7 +2850,25 @@ const shouldSuppressLocalUseHookDiagnostic = (diagnostic, rootDirectory) => {
 	const bindingResolution = resolveUseCallBinding(sourceText, absolutePath, primaryLabel.span.offset);
 	return bindingResolution !== null && !bindingResolution.isReactUseBinding;
 };
-const getRuleRecommendation = (ruleName) => reactDoctorPlugin.rules[ruleName]?.recommendation;
+const getPublicEnvPrefix = (framework) => {
+	switch (framework) {
+		case "nextjs": return "NEXT_PUBLIC_*";
+		case "vite":
+		case "tanstack-start": return "VITE_*";
+		case "cra": return "REACT_APP_*";
+		case "gatsby": return "GATSBY_*";
+		default: return null;
+	}
+};
+const buildNoSecretsRecommendation = (project, fallbackRecommendation) => {
+	const publicEnvPrefix = getPublicEnvPrefix(project.framework);
+	if (!publicEnvPrefix) return fallbackRecommendation;
+	return `Move secrets to server-only code. In ${formatFrameworkName(project.framework)}, only \`${publicEnvPrefix}\` env vars are exposed to the browser, and they must not contain secrets`;
+};
+const getRuleRecommendation = (ruleName, project) => {
+	if (ruleName === "no-secrets-in-client-code") return buildNoSecretsRecommendation(project, reactDoctorPlugin.rules["no-secrets-in-client-code"]?.recommendation ?? "Move secrets to server-only code");
+	return reactDoctorPlugin.rules[ruleName]?.recommendation;
+};
 const getRuleCategory = (ruleName) => reactDoctorPlugin.rules[ruleName]?.category;
 const esmRequire = createRequire(import.meta.url);
 const PLUGIN_CATEGORY_MAP = {
@@ -2738,14 +2893,14 @@ const PLUGIN_CATEGORY_MAP = {
 const FILEPATH_WITH_LOCATION_PATTERN = /\S+\.\w+:\d+:\d+[\s\S]*$/;
 const REACT_COMPILER_MESSAGE = "React Compiler can't optimize this code";
 const lookupOwnString = (record, key) => Object.hasOwn(record, key) ? record[key] : void 0;
-const cleanDiagnosticMessage = (message, help, plugin, rule) => {
+const cleanDiagnosticMessage = (message, help, plugin, rule, project) => {
 	if (plugin === "react-hooks-js") return {
 		message: REACT_COMPILER_MESSAGE,
 		help: message.replace(FILEPATH_WITH_LOCATION_PATTERN, "").trim() || help
 	};
 	return {
 		message: message.replace(FILEPATH_WITH_LOCATION_PATTERN, "").trim() || message,
-		help: help || getRuleRecommendation(rule) || ""
+		help: help || getRuleRecommendation(rule, project) || ""
 	};
 };
 const parseRuleCode = (code) => {
@@ -2848,7 +3003,7 @@ const isOxlintOutput = (value) => {
 	const candidate = value;
 	return Array.isArray(candidate.diagnostics);
 };
-const parseOxlintOutput = (stdout, rootDirectory) => {
+const parseOxlintOutput = (stdout, project, rootDirectory) => {
 	if (!stdout) return [];
 	const jsonStart = stdout.indexOf("{");
 	const sanitizedStdout = jsonStart > 0 ? stdout.slice(jsonStart) : stdout;
@@ -2862,7 +3017,7 @@ const parseOxlintOutput = (stdout, rootDirectory) => {
 	return parsed.diagnostics.filter((diagnostic) => diagnostic.code && SOURCE_FILE_PATTERN.test(diagnostic.filename) && !shouldSuppressLocalUseHookDiagnostic(diagnostic, rootDirectory)).map((diagnostic) => {
 		const { plugin, rule } = parseRuleCode(diagnostic.code);
 		const primaryLabel = diagnostic.labels[0];
-		const cleaned = cleanDiagnosticMessage(diagnostic.message, diagnostic.help, plugin, rule);
+		const cleaned = cleanDiagnosticMessage(diagnostic.message, diagnostic.help, plugin, rule, project);
 		return {
 			filePath: diagnostic.filename,
 			plugin,
@@ -2892,7 +3047,7 @@ const validateRuleRegistration = () => {
 	for (const fullKey of ALL_REACT_DOCTOR_RULE_KEYS) {
 		const ruleName = fullKey.replace(/^react-doctor\//, "");
 		if (!getRuleCategory(ruleName)) missingCategory.push(fullKey);
-		if (!getRuleRecommendation(ruleName)) missingHelp.push(fullKey);
+		if (!reactDoctorPlugin.rules[ruleName]?.recommendation) missingHelp.push(fullKey);
 		if (FRAMEWORK_SPECIFIC_RULE_KEYS.has(fullKey) && !reactDoctorPlugin.rules[ruleName]?.requires) missingMetadata.push(fullKey);
 	}
 	if (missingCategory.length > 0 || missingHelp.length > 0 || missingMetadata.length > 0) {
@@ -2905,7 +3060,8 @@ const validateRuleRegistration = () => {
 	}
 };
 const runOxlint = async (options) => {
-	const { rootDirectory, project, includePaths, nodeBinaryPath = process.execPath, customRulesOnly = false, respectInlineDisables = true, adoptExistingLintConfig = true, ignoredTags = /* @__PURE__ */ new Set(), onPartialFailure } = options;
+	const { rootDirectory, project, includePaths, nodeBinaryPath = process.execPath, customRulesOnly = false, respectInlineDisables = true, adoptExistingLintConfig = true, ignoredTags = /* @__PURE__ */ new Set(), userConfig, onPartialFailure } = options;
+	const serverAuthFunctionNames = Array.isArray(userConfig?.serverAuthFunctionNames) ? userConfig.serverAuthFunctionNames.filter((entry) => typeof entry === "string" && entry.length > 0) : void 0;
 	validateRuleRegistration();
 	if (includePaths !== void 0 && includePaths.length === 0) return [];
 	const configDirectory = fs.mkdtempSync(path.join(os.tmpdir(), "react-doctor-oxlintrc-"));
@@ -2917,7 +3073,8 @@ const runOxlint = async (options) => {
 		project,
 		customRulesOnly,
 		extendsPaths,
-		ignoredTags
+		ignoredTags,
+		serverAuthFunctionNames
 	});
 	const restoreDisableDirectives = respectInlineDisables ? () => {} : neutralizeDisableDirectives(rootDirectory, includePaths);
 	try {
@@ -2954,7 +3111,7 @@ const runOxlint = async (options) => {
 			const spawnLintBatch = async (batch) => {
 				const batchArgs = [...baseArgs, ...batch];
 				try {
-					return parseOxlintOutput(await spawnOxlint(batchArgs, rootDirectory, nodeBinaryPath), rootDirectory);
+					return parseOxlintOutput(await spawnOxlint(batchArgs, rootDirectory, nodeBinaryPath), project, rootDirectory);
 				} catch (error) {
 					if (!isSplittableOxlintBatchError(error)) throw error;
 					if (batch.length <= 1) {
@@ -2984,7 +3141,8 @@ const runOxlint = async (options) => {
 				project,
 				customRulesOnly,
 				extendsPaths: [],
-				ignoredTags
+				ignoredTags,
+				serverAuthFunctionNames
 			}));
 			return await spawnLintBatches();
 		}
@@ -3048,7 +3206,8 @@ const diagnose = async (directory, options = {}) => {
 			customRulesOnly: userConfig?.customRulesOnly ?? false,
 			respectInlineDisables: effectiveRespectInlineDisables,
 			adoptExistingLintConfig: userConfig?.adoptExistingLintConfig ?? true,
-			ignoredTags
+			ignoredTags,
+			userConfig
 		}).catch((error) => {
 			console.error("Lint failed:", error);
 			return EMPTY_DIAGNOSTICS;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-doctor",
-  "version": "0.2.0-beta.4",
+  "version": "0.2.0-beta.5",
   "description": "Diagnose and fix React codebases for security, performance, correctness, accessibility, bundle-size, and architecture issues",
   "keywords": [
     "accessibility",
@@ -56,15 +56,15 @@
     "picocolors": "^1.1.1",
     "prompts": "^2.4.2",
     "typescript": ">=5.0.4 <7",
-    "oxlint-plugin-react-doctor": "0.2.0-beta.4"
+    "oxlint-plugin-react-doctor": "0.2.0-beta.5"
   },
   "devDependencies": {
     "@types/prompts": "^2.4.9",
     "eslint-plugin-react-hooks": "^7.1.1",
     "eslint-plugin-react-you-might-not-need-an-effect": "^0.10.1",
-    "@react-doctor/core": "0.2.0-beta.4",
-    "@react-doctor/project-info": "0.2.0-beta.2",
-    "@react-doctor/types": "0.2.0-beta.2"
+    "@react-doctor/types": "0.2.0-beta.3",
+    "@react-doctor/project-info": "0.2.0-beta.3",
+    "@react-doctor/core": "0.2.0-beta.5"
   },
   "peerDependencies": {
     "eslint-plugin-react-hooks": "^6 || ^7",