@eslint-zod/utils

Shared AST utilities for

• eslint-plugin-zod
• eslint-plugin-zod-mini
• eslint-plugin-zod-core

[!NOTE] This package is a dependency of all previously listed packages, so you do not need to install it directly.

API

Every export carries JSDoc with usage notes — refer to the linked source files (or hover in your editor) for the full description and examples. This README only lists what's available.

Root exports — @eslint-zod/utils

AST parsing, import tracking, traversal, and fixer helpers.

Rule authoring

• createRuleCreator(getRuleURL) — builds a rule factory; each rule gets its docs URL, and create receives the user's options merged over defaultOptions. Types RuleCreator (the factory) and RuleDefinition (what it takes); the types they are written against live in @eslint-zod/utils/rule-types
• createPluginMeta(packageJSONURL) — a plugin's name, version, getRuleURL and createRule, read from its package.json; rule docs are expected at docs/rules/<rule-name>.md under repository.directory. Type PluginMeta

Import tracking & scopes

• ZodImportScope — the class defining which import sources a plugin considers in-scope; scope.createTracker({ kind }) is how rules get a per-file import tracker; kind is required, and sourceCode enables the scope-aware resolvers below
• zodImportScope, zodMiniImportScope, zodCoreImportScope — pre-built ZodImportScope instances
• scope.createTracker({ kind, sourceCode? }) — the returned tracker exposes createSchemaVisitor, detectZodSchemaRootNode, isZodSchemaOfType, collectZodChainMethods, collectZodSchemaConstraints, findZodChainedMethod, and the import-lookup helpers. getZodImportBindings() returns every binding with the declaration it came from, and resolveZodImport(node) / resolveZodExport(node) resolve a node to its zod import honouring lexical scope, so a shadowed z resolves to null — use them over isZodNamespace in a rule whose fixer writes an import. createTracker({ kind }) picks which specifiers are recorded, and is required — 'value' skips import type { … } and { type … }, 'type' keeps only those, 'all' keeps both and is what a rule reading a type position needs, since either form reaches one. Schema detection is reachable only through a tracker — the raw forms need the tracker's private import maps
• tracker.resolveZodSchema(node) — the ZodSchemaMeta of the schema an expression evaluates to, followed through const bindings: with const base = z.string(), base.optional() gives methods: ['string', 'optional']. Unlike detection, the call need not be outermost. null unless every step is provably a schema — a non-zod import, a parse result, a helper call or a destructured binding is not. Needs a tracker built with sourceCode
• tracker.createSchemaVisitor({ schemaType?, localSchemas?, onSchema }) — builds the { ImportDeclaration, CallExpression } visitor a rule returns, with detection and the schemaType filter already applied. The standard shape for a schema rule; spread it to add more visitor keys. localSchemas: true also visits a chain rooted at a local const schema (base.isOptional()), with meta describing the whole schema; node is still only the local call, so check a rule's fixer before opting in. Needs a tracker built with sourceCode
• tracker.findZodChainedMethod(node, meta, methodName) — locate a method chained onto a schema (one name, or the first chained of several), for rules that flag a deprecated chained call. null means not chained; a match with member: null means chained on a chain the walker cannot name (z['number']().finite()), so report without a fix
• types ZodSchemaImportTracker, ZodChainItem, ZodChainMember, ZodChainedMethodMatch, ZodImportBinding, ZodImportKind, ZodSchemaVisitorOptions, ZodTrackerOptions

Schema detection & navigation

• findParentSchemaMatchingCondition(node, options) — search up the AST for a matching ancestor schema call
• getZodChainedMethodNames(meta) — the methods chained onto a schema, with the factory removed. ZodSchemaMeta.methods includes the factory for a namespace schema (z.number().safe() → ['number', 'safe']) but not for a named import (number().safe() → ['safe']), so a bare methods.includes(name) matches the factory of an aliased import. Use this to ask "does this schema chain method X?"
• getZodSchemaBaseType(schemaType) — map a schema factory name to its base type category; returns ZodSchemaBaseType | null, null for factories rules should not reason about
• type ZodSchemaMeta — what the tracker's detectZodSchemaRootNode returns (or null)
• types ZodSchemaConstraint, ZodChainedConstraint, ZodCheckArgumentConstraint — the normalized constraints produced by the tracker's collectZodSchemaConstraints

Fixer helpers

• buildZodChainRemoveMethodFix(opts) — remove one method from a chain
• hasCommentInRange(sourceCode, range) — whether a comment sits inside a range a fixer is about to remove or rewrite
• hasParenthesizedReceiver(member) — whether a member expression's object is wrapped in parentheses ((z.string()).min(1)), where a fixer cutting at the object's end would leave the closing parenthesis behind
• buildZodChainReplacementFix(opts) — replace a run of methods
• buildZodConstraintsRemoveFix(opts) — remove a set of ZodSchemaConstraints (chained or check-argument)
• buildZodWrapperUnwrapFix(opts) — replace a single-argument wrapper call with its argument

Zod vocabulary tables

• ZOD_IMMUTABLE_SCHEMA_TYPES — schema factory names whose parsed output is already immutable
• ZOD_MUTATING_CHECK_NAMES — Zod check names that mutate the validated value
• ZOD_NON_SCHEMA_PRODUCING_METHODS — Zod method names that do not return a schema
• ZOD_NON_SCHEMA_HELPER_NAMES / isZodNonSchemaHelperCall(meta) — top-level z exports whose call yields something other than a schema (z.toJSONSchema, z.registry, z.parse); unlike the complement of isZodSchemaFactoryCall it leaves standalone checks alone
• ZOD_SCHEMA_FACTORY_NAMES / isZodSchemaFactoryName(name) — every top-level Zod export whose call evaluates to a schema; use the predicate instead of a per-rule factory list
• isZodSchemaFactoryCall(meta) — whether a detectZodSchemaRootNode result builds a schema; resolves the iso / coerce namespaces, and rejects the helpers that only consume a schema (z.toJSONSchema, z.prettifyError)
• ZOD_STRING_FORMAT_METHODS — deprecated z.string().<format>() methods and the top-level factory replacing each; type ZodStringFormatMethodName
• ZOD_STRING_FORMAT_NAMES — top-level string-format factory names that all parse to string
• ZOD_TYPE_CHANGING_METHODS — chained methods that rebuild the schema around another type (array, or, pipe, …); a chain's earlier checks do not carry past one; type ZodTypeChangingMethod

Check vocabulary

Canonical names shared by both API styles, so rule logic compares zod's .min(2) with zod/mini's z.minLength(2) as one constraint.

• canonicalizeZodConstraintName(constraint, baseType) — reduce a constraint's spelling to its canonical name
• getZodCheckDescriptor(canonicalName) — what a check means: which base types accept it and what it bounds
• types ZodCheckDescriptor, ZodCheckBound, ZodCheckDomain

Rule types — @eslint-zod/utils/rule-types

The slice of the linter's rule API the helpers read. The types are structural, so ESLint's and typescript-eslint's own objects are assignable to them and no linter has to be installed: the package's only typescript-eslint dependency is @typescript-eslint/types, for the AST.

• RuleContext, RuleListener, RuleModule, RuleMeta — the rule itself
• JSONSchema4 — the type of meta.schema, vendored from typescript-eslint so its RuleTester accepts the rule modules
• RuleFix, RuleFixer, ReportDescriptor, ReportFixFunction, ReportSuggestionArray, SuggestionReportDescriptor — reports and fixes
• SourceCode, TokenSearchOptions, Scope, ScopeVariable, ScopeDefinition, ScopeReference — source and scope access

Shared rule builders — @eslint-zod/utils/rule-builders/<rule-name>

Each rule shared between eslint-plugin-zod and eslint-plugin-zod-mini (some also eslint-plugin-zod-core) exposes its create(...) factory from a dedicated subpath. Plugins keep rule metadata local and reuse the runtime logic.

• buildConsistentImportCreate(scope) — also exports ConsistentImportOptions; its optional type argument narrows syntax to the choices a plugin offers
• buildConsistentImportSourceCreate(scope) — also exports ConsistentImportSourceOptions
• buildConsistentObjectSchemaTypeCreate(scope) — also exports ConsistentObjectSchemaTypeOptions and ZOD_OBJECT_METHODS
• buildConsistentSchemaOutputTypeStyleCreate(scope) — also exports ConsistentSchemaOutputTypeStyleOptions and ZOD_SCHEMA_TYPE_STYLES
• buildConsistentSchemaVarNameCreate(scope) — also exports ConsistentSchemaVarNameOptions
• buildNoAnySchemaCreate(scope)
• buildNoCoerceBooleanCreate(scope)
• buildNoConflictingChecksCreate(scope) — also exports the NoConflictingChecksOptions and NoConflictingChecksMessageIds contracts
• buildNoDuplicateSchemaMethodsCreate(scope, excludedMethods) — an as const list naming a type-changing method is a type error, since the rule never reaches it; also exports NoDuplicateSchemaMethodsExclusions
• buildNoDynamicSchemaValueCreate(scope)
• buildNoEmptyCustomSchemaCreate(scope)
• buildNoFunctionScopedSchemaCreate(scope)
• buildNoNativeEnumCreate(scope)
• buildNoPromiseSchemaCreate(scope)
• buildNoThrowInRefineCreate(scope)
• buildNoTransformInRecordKeyCreate(scope, transformNames) — transformNames are matched against the key schema's factory and its constraints, so one list covers both API styles
• buildNoUnknownSchemaCreate(scope)
• buildNoUnnecessaryReadonlyCreate(scope)
• buildPreferEnumOverLiteralUnionCreate(scope)
• buildPreferNullishCreate(scope)
• buildPreferTupleOverArrayLengthCreate(scope)
• buildPreferValidateCreate(scope, api) — success-only parsing suggestions; api is a ZodValidateApiStyle (schema-method or standalone)
• buildRequireBrandTypeParameterCreate(scope)
• buildRequireErrorMessageCreate(scope)
• buildSchemaErrorPropertyStyleCreate(scope) — also exports SchemaErrorPropertyStyleOptions

The consistent-import builder additionally re-exports IMPORT_SYNTAXES and ImportSyntax: every syntax the builder can enforce. Each plugin declares the subset it offers in its own rule schema.

Rule patterns — @eslint-zod/utils/rule-patterns/<pattern-name>

Rule shapes that recur across several rules, parameterized by the names they differ in. Unlike rule builders these are not tied to one rule name, and a single plugin may use one several times.

• buildDeprecatedSchemaPropertyCreate(options) — flag a deprecated property access on a schema of a given schemaType (z.number().isInt); also exports DeprecatedSchemaPropertyOptions
• buildDeprecatedSchemaMethodCreate(options) — flag a deprecated method anywhere in a schema chain (.isOptional()); also exports DeprecatedSchemaMethodOptions
• buildCollapseEqualBoundsCreate(options) — collapse an equal lower/upper bound pair into the exact-form check of the same domain (z.string().min(3).max(3) → z.string().length(3)); also exports CollapseEqualBoundsOptions and CollapsibleBoundDomain
• buildPreferDedicatedFactoryCreate(options) — prefer a dedicated factory over a general one plus a chained modifier (z.looseObject() over z.object().passthrough()); also exports PreferDedicatedFactoryOptions
• buildPreferTopLevelFactoryCreate(options) — prefer a top-level factory over a deprecated method chained on a general one (z.uuid() over z.string().uuid()); also exports PreferTopLevelFactoryOptions and TopLevelFactoryReplacement