eslint-plugin-zod 4.0.1 → 4.1.0

package/README.md

@@ -29,37 +29,39 @@ Find out more about [Oxlint's `jsPLugins`](https://oxc.rs/docs/guide/usage/linte
 💼 Configurations enabled in.\
 ✅ Set in the `recommended` configuration.\
 🔧 Automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/user-guide/command-line-interface#--fix).\
-💡 Manually fixable by [editor suggestions](https://eslint.org/docs/latest/use/core-concepts#rule-suggestions).
-
-| Name                                                                                             | Description                                                                                                                    | 💼  | 🔧  | 💡  |
-| :----------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------- | :-- | :-- | :-- |
-| [array-style](docs/rules/array-style.md)                                                         | Enforce consistent Zod array style                                                                                             | ✅  | 🔧  |     |
-| [consistent-import](docs/rules/consistent-import.md)                                             | Enforce a consistent import style for Zod                                                                                      | ✅  | 🔧  |     |
-| [consistent-import-source](docs/rules/consistent-import-source.md)                               | Enforce consistent source from Zod imports                                                                                     |     |     | 💡  |
-| [consistent-object-schema-type](docs/rules/consistent-object-schema-type.md)                     | Enforce consistent usage of Zod schema methods                                                                                 |     |     | 💡  |
-| [consistent-schema-output-type-style](docs/rules/consistent-schema-output-type-style.md)         | Enforce consistent use of z.infer or z.output for schema type inference                                                        |     | 🔧  |     |
-| [consistent-schema-var-name](docs/rules/consistent-schema-var-name.md)                           | Enforce a consistent naming convention for Zod schema variables                                                                | ✅  |     |     |
-| [no-any-schema](docs/rules/no-any-schema.md)                                                     | Disallow usage of `z.any()` in Zod schemas                                                                                     | ✅  |     | 💡  |
-| [no-empty-custom-schema](docs/rules/no-empty-custom-schema.md)                                   | Disallow usage of `z.custom()` without arguments                                                                               | ✅  |     |     |
-| [no-number-schema-with-finite](docs/rules/no-number-schema-with-finite.md)                       | Disallow deprecated `z.number().finite()`. In Zod 4+ number schemas do not allow infinite values by default, so it is a no-op. | ✅  | 🔧  |     |
-| [no-number-schema-with-int](docs/rules/no-number-schema-with-int.md)                             | Disallow usage of `z.number().int()` as it is considered legacy                                                                | ✅  | 🔧  |     |
-| [no-number-schema-with-is-finite](docs/rules/no-number-schema-with-is-finite.md)                 | Disallow using deprecated `isFinite` on a Zod number schema; in v4+ it is always `true`.                                       | ✅  |     |     |
-| [no-number-schema-with-is-int](docs/rules/no-number-schema-with-is-int.md)                       | Disallow using deprecated `isInt` on a Zod number schema; check the `format` property instead.                                 | ✅  |     |     |
-| [no-number-schema-with-safe](docs/rules/no-number-schema-with-safe.md)                           | Disallow deprecated `z.number().safe()`. Use `z.int()`; `.safe()` is now identical to `.int()`.                                | ✅  | 🔧  |     |
-| [no-number-schema-with-step](docs/rules/no-number-schema-with-step.md)                           | Disallow deprecated `z.number().step()`. Use `.multipleOf()` instead.                                                          | ✅  | 🔧  |     |
-| [no-optional-and-default-together](docs/rules/no-optional-and-default-together.md)               | Disallow using both `.optional()` and `.default()` on the same Zod schema                                                      | ✅  | 🔧  |     |
-| [no-string-schema-with-uuid](docs/rules/no-string-schema-with-uuid.md)                           | Disallow usage of `z.string().uuid()` in favor of the dedicated `z.uuid()` schema                                              | ✅  | 🔧  |     |
-| [no-throw-in-refine](docs/rules/no-throw-in-refine.md)                                           | Disallow throwing errors directly inside Zod refine callbacks                                                                  | ✅  |     |     |
-| [no-transform-in-record-key](docs/rules/no-transform-in-record-key.md)                           | Disallow transforms in z.record() key schemas, which can cause silent key mutations and data loss through key collisions       |     |     |     |
-| [no-unknown-schema](docs/rules/no-unknown-schema.md)                                             | Disallow usage of `z.unknown()` in Zod schemas                                                                                 |     |     |     |
-| [prefer-enum-over-literal-union](docs/rules/prefer-enum-over-literal-union.md)                   | Prefer `z.enum()` over `z.union()` when all members are string literals.                                                       | ✅  | 🔧  |     |
-| [prefer-meta](docs/rules/prefer-meta.md)                                                         | Enforce usage of `.meta()` over `.describe()`                                                                                  | ✅  | 🔧  |     |
-| [prefer-meta-last](docs/rules/prefer-meta-last.md)                                               | Enforce `.meta()` as last method                                                                                               | ✅  | 🔧  |     |
-| [prefer-string-schema-with-trim](docs/rules/prefer-string-schema-with-trim.md)                   | Enforce `z.string().trim()` to prevent accidental leading/trailing whitespace                                                  | ✅  | 🔧  |     |
-| [prefer-trim-before-string-length-checks](docs/rules/prefer-trim-before-string-length-checks.md) | Enforce `.trim()` is called before string length checks to ensure accurate validation                                          | ✅  | 🔧  |     |
-| [require-brand-type-parameter](docs/rules/require-brand-type-parameter.md)                       | Require type parameter on `.brand()` functions                                                                                 | ✅  |     | 💡  |
-| [require-error-message](docs/rules/require-error-message.md)                                     | Enforce that custom refinements include an error message                                                                       | ✅  | 🔧  |     |
-| [schema-error-property-style](docs/rules/schema-error-property-style.md)                         | Enforce consistent style for error messages in Zod schema validation (using ESQuery patterns)                                  |     |     |     |
+💡 Manually fixable by [editor suggestions](https://eslint.org/docs/latest/use/core-concepts#rule-suggestions).\
+❌ Deprecated.
+
+| Name                                                                                             | Description                                                                                                                    | 💼  | 🔧  | 💡  | ❌  |
+| :----------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------- | :-- | :-- | :-- | :-- |
+| [array-style](docs/rules/array-style.md)                                                         | Enforce consistent Zod array style                                                                                             | ✅  | 🔧  |     |     |
+| [consistent-import](docs/rules/consistent-import.md)                                             | Enforce a consistent import style for Zod                                                                                      | ✅  | 🔧  |     |     |
+| [consistent-import-source](docs/rules/consistent-import-source.md)                               | Enforce consistent source from Zod imports                                                                                     |     |     | 💡  |     |
+| [consistent-object-schema-type](docs/rules/consistent-object-schema-type.md)                     | Enforce consistent usage of Zod schema methods                                                                                 |     |     | 💡  |     |
+| [consistent-schema-output-type-style](docs/rules/consistent-schema-output-type-style.md)         | Enforce consistent use of z.infer or z.output for schema type inference                                                        |     | 🔧  |     |     |
+| [consistent-schema-var-name](docs/rules/consistent-schema-var-name.md)                           | Enforce a consistent naming convention for Zod schema variables                                                                | ✅  |     |     |     |
+| [no-any-schema](docs/rules/no-any-schema.md)                                                     | Disallow usage of `z.any()` in Zod schemas                                                                                     | ✅  |     | 💡  |     |
+| [no-empty-custom-schema](docs/rules/no-empty-custom-schema.md)                                   | Disallow usage of `z.custom()` without arguments                                                                               | ✅  |     |     |     |
+| [no-number-schema-with-finite](docs/rules/no-number-schema-with-finite.md)                       | Disallow deprecated `z.number().finite()`. In Zod 4+ number schemas do not allow infinite values by default, so it is a no-op. | ✅  | 🔧  |     |     |
+| [no-number-schema-with-int](docs/rules/no-number-schema-with-int.md)                             | Disallow usage of `z.number().int()` as it is considered legacy                                                                | ✅  | 🔧  |     |     |
+| [no-number-schema-with-is-finite](docs/rules/no-number-schema-with-is-finite.md)                 | Disallow using deprecated `isFinite` on a Zod number schema; in v4+ it is always `true`.                                       | ✅  |     |     |     |
+| [no-number-schema-with-is-int](docs/rules/no-number-schema-with-is-int.md)                       | Disallow using deprecated `isInt` on a Zod number schema; check the `format` property instead.                                 | ✅  |     |     |     |
+| [no-number-schema-with-safe](docs/rules/no-number-schema-with-safe.md)                           | Disallow deprecated `z.number().safe()`. Use `z.int()`; `.safe()` is now identical to `.int()`.                                | ✅  | 🔧  |     |     |
+| [no-number-schema-with-step](docs/rules/no-number-schema-with-step.md)                           | Disallow deprecated `z.number().step()`. Use `.multipleOf()` instead.                                                          | ✅  | 🔧  |     |     |
+| [no-optional-and-default-together](docs/rules/no-optional-and-default-together.md)               | Disallow using both `.optional()` and `.default()` on the same Zod schema                                                      | ✅  | 🔧  |     |     |
+| [no-string-schema-with-uuid](docs/rules/no-string-schema-with-uuid.md)                           | Disallow usage of `z.string().uuid()` in favor of the dedicated `z.uuid()` schema                                              | ✅  | 🔧  |     | ❌  |
+| [no-throw-in-refine](docs/rules/no-throw-in-refine.md)                                           | Disallow throwing errors directly inside Zod refine callbacks                                                                  | ✅  |     |     |     |
+| [no-transform-in-record-key](docs/rules/no-transform-in-record-key.md)                           | Disallow transforms in z.record() key schemas, which can cause silent key mutations and data loss through key collisions       |     |     |     |     |
+| [no-unknown-schema](docs/rules/no-unknown-schema.md)                                             | Disallow usage of `z.unknown()` in Zod schemas                                                                                 |     |     |     |     |
+| [prefer-enum-over-literal-union](docs/rules/prefer-enum-over-literal-union.md)                   | Prefer `z.enum()` over `z.union()` when all members are string literals.                                                       | ✅  | 🔧  |     |     |
+| [prefer-meta](docs/rules/prefer-meta.md)                                                         | Enforce usage of `.meta()` over `.describe()`                                                                                  | ✅  | 🔧  |     |     |
+| [prefer-meta-last](docs/rules/prefer-meta-last.md)                                               | Enforce `.meta()` as last method                                                                                               | ✅  | 🔧  |     |     |
+| [prefer-string-schema-with-trim](docs/rules/prefer-string-schema-with-trim.md)                   | Enforce `z.string().trim()` to prevent accidental leading/trailing whitespace                                                  | ✅  | 🔧  |     |     |
+| [prefer-top-level-string-formats](docs/rules/prefer-top-level-string-formats.md)                 | Prefer top-level string format schemas over deprecated `z.string().<format>()` methods                                         | ✅  | 🔧  |     |     |
+| [prefer-trim-before-string-length-checks](docs/rules/prefer-trim-before-string-length-checks.md) | Enforce `.trim()` is called before string length checks to ensure accurate validation                                          | ✅  | 🔧  |     |     |
+| [require-brand-type-parameter](docs/rules/require-brand-type-parameter.md)                       | Require type parameter on `.brand()` functions                                                                                 | ✅  |     | 💡  |     |
+| [require-error-message](docs/rules/require-error-message.md)                                     | Enforce that custom refinements include an error message                                                                       | ✅  | 🔧  |     |     |
+| [schema-error-property-style](docs/rules/schema-error-property-style.md)                         | Enforce consistent style for error messages in Zod schema validation (using ESQuery patterns)                                  |     |     |     |     |
 
 <!-- end auto-generated rules list -->
 

package/dist/index.cjs

@@ -22,6 +22,7 @@ const require_prefer_enum_over_literal_union = require("./rules/prefer-enum-over
 const require_prefer_meta_last = require("./rules/prefer-meta-last.cjs");
 const require_prefer_meta = require("./rules/prefer-meta.cjs");
 const require_prefer_string_schema_with_trim = require("./rules/prefer-string-schema-with-trim.cjs");
+const require_prefer_top_level_string_formats = require("./rules/prefer-top-level-string-formats.cjs");
 const require_prefer_trim_before_string_length_checks = require("./rules/prefer-trim-before-string-length-checks.cjs");
 const require_require_brand_type_parameter = require("./rules/require-brand-type-parameter.cjs");
 const require_require_error_message = require("./rules/require-error-message.cjs");
@@ -55,6 +56,7 @@ const eslintPluginZod = {
 		"prefer-enum-over-literal-union": require_prefer_enum_over_literal_union.preferEnumOverLiteralUnion,
 		"prefer-meta": require_prefer_meta.preferMeta,
 		"prefer-meta-last": require_prefer_meta_last.preferMetaLast,
+		"prefer-top-level-string-formats": require_prefer_top_level_string_formats.preferTopLevelStringFormats,
 		"prefer-string-schema-with-trim": require_prefer_string_schema_with_trim.preferStringSchemaWithTrim,
 		"prefer-trim-before-string-length-checks": require_prefer_trim_before_string_length_checks.preferTrimBeforeStringLengthChecks,
 		"require-brand-type-parameter": require_require_brand_type_parameter.requireBrandTypeParameter,
@@ -84,6 +86,7 @@ const recommendedConfig = {
 		"zod/prefer-enum-over-literal-union": "error",
 		"zod/prefer-meta": "error",
 		"zod/prefer-meta-last": "error",
+		"zod/prefer-top-level-string-formats": "error",
 		"zod/prefer-string-schema-with-trim": "error",
 		"zod/prefer-trim-before-string-length-checks": "error",
 		"zod/require-brand-type-parameter": "error",

package/dist/index.mjs

@@ -22,6 +22,7 @@ import { preferEnumOverLiteralUnion } from "./rules/prefer-enum-over-literal-uni
 import { preferMetaLast } from "./rules/prefer-meta-last.mjs";
 import { preferMeta } from "./rules/prefer-meta.mjs";
 import { preferStringSchemaWithTrim } from "./rules/prefer-string-schema-with-trim.mjs";
+import { preferTopLevelStringFormats } from "./rules/prefer-top-level-string-formats.mjs";
 import { preferTrimBeforeStringLengthChecks } from "./rules/prefer-trim-before-string-length-checks.mjs";
 import { requireBrandTypeParameter } from "./rules/require-brand-type-parameter.mjs";
 import { requireErrorMessage } from "./rules/require-error-message.mjs";
@@ -55,6 +56,7 @@ const eslintPluginZod = {
 		"prefer-enum-over-literal-union": preferEnumOverLiteralUnion,
 		"prefer-meta": preferMeta,
 		"prefer-meta-last": preferMetaLast,
+		"prefer-top-level-string-formats": preferTopLevelStringFormats,
 		"prefer-string-schema-with-trim": preferStringSchemaWithTrim,
 		"prefer-trim-before-string-length-checks": preferTrimBeforeStringLengthChecks,
 		"require-brand-type-parameter": requireBrandTypeParameter,
@@ -84,6 +86,7 @@ const recommendedConfig = {
 		"zod/prefer-enum-over-literal-union": "error",
 		"zod/prefer-meta": "error",
 		"zod/prefer-meta-last": "error",
+		"zod/prefer-top-level-string-formats": "error",
 		"zod/prefer-string-schema-with-trim": "error",
 		"zod/prefer-trim-before-string-length-checks": "error",
 		"zod/require-brand-type-parameter": "error",

package/dist/rules/no-string-schema-with-uuid.cjs

@@ -8,6 +8,7 @@ const noStringSchemaWithUuid = require_create_plugin_rule.createZodPluginRule({
 	meta: {
 		fixable: "code",
 		type: "problem",
+		deprecated: { message: "Use `zod/prefer-top-level-string-formats` instead" },
 		docs: {
 			description: "Disallow usage of `z.string().uuid()` in favor of the dedicated `z.uuid()` schema",
 			url: "https://zod.dev/api#uuids"

package/dist/rules/no-string-schema-with-uuid.mjs

@@ -7,6 +7,7 @@ const noStringSchemaWithUuid = createZodPluginRule({
 	meta: {
 		fixable: "code",
 		type: "problem",
+		deprecated: { message: "Use `zod/prefer-top-level-string-formats` instead" },
 		docs: {
 			description: "Disallow usage of `z.string().uuid()` in favor of the dedicated `z.uuid()` schema",
 			url: "https://zod.dev/api#uuids"

package/dist/rules/prefer-top-level-string-formats.cjs

@@ -0,0 +1,193 @@
+require("../_virtual/_rolldown/runtime.cjs");
+const require_create_plugin_rule = require("../utils/create-plugin-rule.cjs");
+let _eslint_zod_utils = require("@eslint-zod/utils");
+//#region src/rules/prefer-top-level-string-formats.ts
+const TOP_LEVEL_STRING_FORMATS_URL = "https://zod.dev/v4?id=top-level-string-formats";
+const TOP_LEVEL_STRING_FORMATS = [
+	{
+		sourceMethodName: "base64",
+		replacementMethodName: "base64"
+	},
+	{
+		sourceMethodName: "base64url",
+		replacementMethodName: "base64url"
+	},
+	{
+		sourceMethodName: "cidrv4",
+		replacementMethodName: "cidrv4"
+	},
+	{
+		sourceMethodName: "cidrv6",
+		replacementMethodName: "cidrv6"
+	},
+	{
+		sourceMethodName: "cuid",
+		replacementMethodName: "cuid"
+	},
+	{
+		sourceMethodName: "cuid2",
+		replacementMethodName: "cuid2"
+	},
+	{
+		sourceMethodName: "date",
+		replacementMethodName: "iso.date"
+	},
+	{
+		sourceMethodName: "datetime",
+		replacementMethodName: "iso.datetime"
+	},
+	{
+		sourceMethodName: "duration",
+		replacementMethodName: "iso.duration"
+	},
+	{
+		sourceMethodName: "e164",
+		replacementMethodName: "e164"
+	},
+	{
+		sourceMethodName: "email",
+		replacementMethodName: "email"
+	},
+	{
+		sourceMethodName: "emoji",
+		replacementMethodName: "emoji"
+	},
+	{
+		sourceMethodName: "guid",
+		replacementMethodName: "guid"
+	},
+	{
+		sourceMethodName: "ipv4",
+		replacementMethodName: "ipv4"
+	},
+	{
+		sourceMethodName: "ipv6",
+		replacementMethodName: "ipv6"
+	},
+	{
+		sourceMethodName: "jwt",
+		replacementMethodName: "jwt"
+	},
+	{
+		sourceMethodName: "ksuid",
+		replacementMethodName: "ksuid"
+	},
+	{
+		sourceMethodName: "nanoid",
+		replacementMethodName: "nanoid"
+	},
+	{
+		sourceMethodName: "time",
+		replacementMethodName: "iso.time"
+	},
+	{
+		sourceMethodName: "ulid",
+		replacementMethodName: "ulid"
+	},
+	{
+		sourceMethodName: "url",
+		replacementMethodName: "url"
+	},
+	{
+		sourceMethodName: "uuid",
+		replacementMethodName: "uuid"
+	},
+	{
+		sourceMethodName: "uuidv4",
+		replacementMethodName: "uuidv4"
+	},
+	{
+		sourceMethodName: "uuidv6",
+		replacementMethodName: "uuidv6"
+	},
+	{
+		sourceMethodName: "uuidv7",
+		replacementMethodName: "uuidv7"
+	},
+	{
+		sourceMethodName: "xid",
+		replacementMethodName: "xid"
+	}
+];
+const { trackZodSchemaImports } = (0, _eslint_zod_utils.createZodSchemaImportTrack)(_eslint_zod_utils.zodImportScope);
+const TOP_LEVEL_STRING_FORMAT_METHOD_NAMES = TOP_LEVEL_STRING_FORMATS.map(({ sourceMethodName }) => sourceMethodName);
+const TOP_LEVEL_STRING_FORMATS_BY_SOURCE = Object.fromEntries(TOP_LEVEL_STRING_FORMATS.map((format) => [format.sourceMethodName, format]));
+function isTopLevelStringFormatMethodName(value) {
+	return TOP_LEVEL_STRING_FORMAT_METHOD_NAMES.includes(value);
+}
+const preferTopLevelStringFormats = require_create_plugin_rule.createZodPluginRule({
+	name: "prefer-top-level-string-formats",
+	meta: {
+		type: "suggestion",
+		fixable: "code",
+		docs: {
+			description: "Prefer top-level string format schemas over deprecated `z.string().<format>()` methods",
+			url: TOP_LEVEL_STRING_FORMATS_URL
+		},
+		messages: { preferTopLevelStringFormat: "Use `z.{{replacementMethod}}()` instead of `z.string().{{sourceMethod}}()`." },
+		schema: [{
+			type: "object",
+			properties: { ignore: {
+				type: "array",
+				description: "Top-level string format methods to ignore for this rule.",
+				items: {
+					type: "string",
+					enum: [...TOP_LEVEL_STRING_FORMAT_METHOD_NAMES]
+				},
+				uniqueItems: true
+			} },
+			additionalProperties: false
+		}]
+	},
+	defaultOptions: [{}],
+	create(context, [{ ignore = [] }]) {
+		const { sourceCode } = context;
+		const ignoredMethods = new Set(ignore);
+		const { importDeclarationListener, detectZodSchemaRootNode, collectZodChainMethods } = trackZodSchemaImports();
+		return {
+			ImportDeclaration: importDeclarationListener,
+			CallExpression(node) {
+				const zodSchemaMeta = detectZodSchemaRootNode(node);
+				if (zodSchemaMeta?.schemaType !== "string") return;
+				const methods = collectZodChainMethods(node);
+				const stringIndex = methods.findIndex((method) => method.name === "string");
+				if (stringIndex === -1) return;
+				const formatMethod = methods.find((method, index) => index > stringIndex && isTopLevelStringFormatMethodName(method.name) && !ignoredMethods.has(method.name));
+				if (!formatMethod) return;
+				if (!isTopLevelStringFormatMethodName(formatMethod.name)) return;
+				const { replacementMethodName, sourceMethodName } = TOP_LEVEL_STRING_FORMATS_BY_SOURCE[formatMethod.name];
+				if (zodSchemaMeta.schemaDecl === "named") {
+					context.report({
+						node,
+						messageId: "preferTopLevelStringFormat",
+						data: {
+							replacementMethod: replacementMethodName,
+							sourceMethod: sourceMethodName
+						}
+					});
+					return;
+				}
+				context.report({
+					node,
+					messageId: "preferTopLevelStringFormat",
+					data: {
+						replacementMethod: replacementMethodName,
+						sourceMethod: sourceMethodName
+					},
+					fix(fixer) {
+						return (0, _eslint_zod_utils.buildZodChainReplacementFix)({
+							sourceCode,
+							fixer,
+							methods,
+							fromIndex: stringIndex,
+							toIndex: methods.indexOf(formatMethod),
+							toMethodName: replacementMethodName
+						});
+					}
+				});
+			}
+		};
+	}
+});
+//#endregion
+exports.preferTopLevelStringFormats = preferTopLevelStringFormats;

package/dist/rules/prefer-top-level-string-formats.mjs

@@ -0,0 +1,192 @@
+import { createZodPluginRule } from "../utils/create-plugin-rule.mjs";
+import { buildZodChainReplacementFix, createZodSchemaImportTrack, zodImportScope } from "@eslint-zod/utils";
+//#region src/rules/prefer-top-level-string-formats.ts
+const TOP_LEVEL_STRING_FORMATS_URL = "https://zod.dev/v4?id=top-level-string-formats";
+const TOP_LEVEL_STRING_FORMATS = [
+	{
+		sourceMethodName: "base64",
+		replacementMethodName: "base64"
+	},
+	{
+		sourceMethodName: "base64url",
+		replacementMethodName: "base64url"
+	},
+	{
+		sourceMethodName: "cidrv4",
+		replacementMethodName: "cidrv4"
+	},
+	{
+		sourceMethodName: "cidrv6",
+		replacementMethodName: "cidrv6"
+	},
+	{
+		sourceMethodName: "cuid",
+		replacementMethodName: "cuid"
+	},
+	{
+		sourceMethodName: "cuid2",
+		replacementMethodName: "cuid2"
+	},
+	{
+		sourceMethodName: "date",
+		replacementMethodName: "iso.date"
+	},
+	{
+		sourceMethodName: "datetime",
+		replacementMethodName: "iso.datetime"
+	},
+	{
+		sourceMethodName: "duration",
+		replacementMethodName: "iso.duration"
+	},
+	{
+		sourceMethodName: "e164",
+		replacementMethodName: "e164"
+	},
+	{
+		sourceMethodName: "email",
+		replacementMethodName: "email"
+	},
+	{
+		sourceMethodName: "emoji",
+		replacementMethodName: "emoji"
+	},
+	{
+		sourceMethodName: "guid",
+		replacementMethodName: "guid"
+	},
+	{
+		sourceMethodName: "ipv4",
+		replacementMethodName: "ipv4"
+	},
+	{
+		sourceMethodName: "ipv6",
+		replacementMethodName: "ipv6"
+	},
+	{
+		sourceMethodName: "jwt",
+		replacementMethodName: "jwt"
+	},
+	{
+		sourceMethodName: "ksuid",
+		replacementMethodName: "ksuid"
+	},
+	{
+		sourceMethodName: "nanoid",
+		replacementMethodName: "nanoid"
+	},
+	{
+		sourceMethodName: "time",
+		replacementMethodName: "iso.time"
+	},
+	{
+		sourceMethodName: "ulid",
+		replacementMethodName: "ulid"
+	},
+	{
+		sourceMethodName: "url",
+		replacementMethodName: "url"
+	},
+	{
+		sourceMethodName: "uuid",
+		replacementMethodName: "uuid"
+	},
+	{
+		sourceMethodName: "uuidv4",
+		replacementMethodName: "uuidv4"
+	},
+	{
+		sourceMethodName: "uuidv6",
+		replacementMethodName: "uuidv6"
+	},
+	{
+		sourceMethodName: "uuidv7",
+		replacementMethodName: "uuidv7"
+	},
+	{
+		sourceMethodName: "xid",
+		replacementMethodName: "xid"
+	}
+];
+const { trackZodSchemaImports } = createZodSchemaImportTrack(zodImportScope);
+const TOP_LEVEL_STRING_FORMAT_METHOD_NAMES = TOP_LEVEL_STRING_FORMATS.map(({ sourceMethodName }) => sourceMethodName);
+const TOP_LEVEL_STRING_FORMATS_BY_SOURCE = Object.fromEntries(TOP_LEVEL_STRING_FORMATS.map((format) => [format.sourceMethodName, format]));
+function isTopLevelStringFormatMethodName(value) {
+	return TOP_LEVEL_STRING_FORMAT_METHOD_NAMES.includes(value);
+}
+const preferTopLevelStringFormats = createZodPluginRule({
+	name: "prefer-top-level-string-formats",
+	meta: {
+		type: "suggestion",
+		fixable: "code",
+		docs: {
+			description: "Prefer top-level string format schemas over deprecated `z.string().<format>()` methods",
+			url: TOP_LEVEL_STRING_FORMATS_URL
+		},
+		messages: { preferTopLevelStringFormat: "Use `z.{{replacementMethod}}()` instead of `z.string().{{sourceMethod}}()`." },
+		schema: [{
+			type: "object",
+			properties: { ignore: {
+				type: "array",
+				description: "Top-level string format methods to ignore for this rule.",
+				items: {
+					type: "string",
+					enum: [...TOP_LEVEL_STRING_FORMAT_METHOD_NAMES]
+				},
+				uniqueItems: true
+			} },
+			additionalProperties: false
+		}]
+	},
+	defaultOptions: [{}],
+	create(context, [{ ignore = [] }]) {
+		const { sourceCode } = context;
+		const ignoredMethods = new Set(ignore);
+		const { importDeclarationListener, detectZodSchemaRootNode, collectZodChainMethods } = trackZodSchemaImports();
+		return {
+			ImportDeclaration: importDeclarationListener,
+			CallExpression(node) {
+				const zodSchemaMeta = detectZodSchemaRootNode(node);
+				if (zodSchemaMeta?.schemaType !== "string") return;
+				const methods = collectZodChainMethods(node);
+				const stringIndex = methods.findIndex((method) => method.name === "string");
+				if (stringIndex === -1) return;
+				const formatMethod = methods.find((method, index) => index > stringIndex && isTopLevelStringFormatMethodName(method.name) && !ignoredMethods.has(method.name));
+				if (!formatMethod) return;
+				if (!isTopLevelStringFormatMethodName(formatMethod.name)) return;
+				const { replacementMethodName, sourceMethodName } = TOP_LEVEL_STRING_FORMATS_BY_SOURCE[formatMethod.name];
+				if (zodSchemaMeta.schemaDecl === "named") {
+					context.report({
+						node,
+						messageId: "preferTopLevelStringFormat",
+						data: {
+							replacementMethod: replacementMethodName,
+							sourceMethod: sourceMethodName
+						}
+					});
+					return;
+				}
+				context.report({
+					node,
+					messageId: "preferTopLevelStringFormat",
+					data: {
+						replacementMethod: replacementMethodName,
+						sourceMethod: sourceMethodName
+					},
+					fix(fixer) {
+						return buildZodChainReplacementFix({
+							sourceCode,
+							fixer,
+							methods,
+							fromIndex: stringIndex,
+							toIndex: methods.indexOf(formatMethod),
+							toMethodName: replacementMethodName
+						});
+					}
+				});
+			}
+		};
+	}
+});
+//#endregion
+export { preferTopLevelStringFormats };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-zod",
-  "version": "4.0.1",
+  "version": "4.1.0",
   "type": "module",
   "description": "ESLint plugin that adds custom linting rules to enforce best practices when using Zod",
   "engines": {