feat(architecture): add prefer-schema-validation rule

[NisargIO]

Why

Catches hand-rolled runtime type/shape validation — a function that checks an object's structure with several typeof comparisons is a schema written by hand. Defining the shape once with a schema validator (Zod, Valibot, Yup) and parsing the value keeps the TypeScript type and the runtime check in sync, narrows the value, and removes plumbing that drifts as the shape grows.

Before:

function isUser(value: unknown): value is User {
  return (
    typeof value === "object" &&
    value !== null &&
    typeof value.id === "string" &&
    typeof value.name === "string" &&
    typeof value.age === "number"
  );
}

After:

import { z } from "zod";

const userSchema = z.object({ id: z.string(), name: z.string(), age: z.number() });

const parseUser = (value: unknown): User => userSchema.parse(value);

What changed

• Added react-doctor/prefer-schema-validation (architecture bucket → Maintainability, warn).
• Detects functions whose intent is validation — a TS type predicate / assertion (value is User, asserts input is Config) or a validator-named binding (isUser, hasFoo, validateConfig, assertX, check*, ensure*, verify*, guard*).
• Reports when such a function performs two or more distinct typeof param.member === "<tag>" checks on a single parameter.
• Allows (stays quiet on):
  • polymorphic dispatch on the parameter itself (typeof value === "string") — not a member check, so serializers and the no-polymorphic-children surface are untouched;
  • non-validator functions even with several member checks (serializers/visitors are a v1 non-goal);
  • typeof checks rooted at a different object;
  • checks inside nested functions (counted against their own validation, not the enclosing one);
  • repeated checks on the same property (optional-field guards dedupe to one);
  • dynamic computed members (value[key]) and comparisons against non-typeof string literals;
  • destructured-parameter validators (v1 non-goal).
• Resolves the validated-parameter root through as casts, parentheses, optional chaining, and non-null assertions, and resolves the function's binding name from declarations, const initializers, object/class members, and assignments.
• Adds a 24-case adversarial test suite (type guards, assertion functions, JS validators, object/class methods, member-assigned validators, as/optional-chain roots, nested paths, anonymous guards; plus the full valid/non-goal matrix).
• Regenerates the rule registry and adds a changeset.

Eval results

Scanned six large public React/TypeScript monorepos with the built CLI (--json --no-score --no-dead-code) and filtered to the rule. Every hit was inspected by hand; all were genuine hand-rolled type guards / validators (e.g. isAppendStreamOptions, isVercelApiErrorShape, isNext12ApiResponse, isValidAuthTokenPair, isDroppableData). No false positives. Repos that lean on Zod (cal.com) or are pure UI (shadcn/ui) produced zero hits, confirming the rule targets the right anti-pattern.

Check	Result
Repos scanned	6 (shadcn/ui, formbricks, trigger.dev, novu, twenty, cal.com)
Total diagnostics	~15,800
Target rule	prefer-schema-validation
Diagnostics	10 unique (0 shadcn · 2 formbricks · 4 trigger.dev · 1 novu · 3 twenty · 0 cal.com)
False positives found	0 (all 10 inspected manually)

Test plan

• pnpm exec vp test run packages/oxlint-plugin-react-doctor/src/plugin/rules/architecture/prefer-schema-validation.test.ts — 24 passed
• pnpm exec vp test run packages/react-doctor/tests/rule-metadata.test.ts — title/recommendation conventions pass
• pnpm --filter oxlint-plugin-react-doctor typecheck — passes (regenerates registry + tsc --noEmit)
• pnpm lint / pnpm format:check — pass

v1 non-goals

• Non-validator functions (serializers/visitors) doing typeof member inspection without a type predicate or validator-like name.
• Destructured-parameter validators.
• Other validation idioms (Array.isArray, "x" in obj, obj.x === undefined, instanceof) — typeof is the v1 surface.

  

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/eslint-plugin-react-doctor@740

npm i https://pkg.pr.new/oxlint-plugin-react-doctor@740

npm i https://pkg.pr.new/react-doctor@740

commit: 1df103d

[github-actions]

No React Doctor issues found. 🎉

_{Reviewed by React Doctor for commit 1df103d.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 1df103d. Configure here.}

[cursor]

Validator prefix substring false positives

Low Severity

VALIDATOR_WORD_PREFIX_PATTERN treats any function name that merely starts with substrings like guard, check, verify, or assert as a validator. Names such as guardian, checkbox, or verification can be misclassified and warned when they use two unrelated typeof member checks, despite not being validation helpers.

 

^{Reviewed by Cursor Bugbot for commit 1df103d. Configure here.}