@schemashift/zod-v3-v4 0.3.0 → 0.8.0

package/README.md

@@ -0,0 +1,98 @@
+# @schemashift/zod-v3-v4
+
+Zod v3 to v4 upgrade transformer for SchemaShift. Handles 17+ breaking changes between Zod v3 and v4 with auto-transforms and runtime behavior warnings.
+
+**Tier:** Individual
+
+## Installation
+
+```bash
+npm install @schemashift/zod-v3-v4
+```
+
+## Usage
+
+```typescript
+import { createZodV3ToV4Handler } from '@schemashift/zod-v3-v4';
+import { TransformEngine } from '@schemashift/core';
+
+const engine = new TransformEngine();
+engine.registerHandler('zod-v3', 'v4', createZodV3ToV4Handler());
+```
+
+## Breaking Changes Handled
+
+### Auto-Transforms
+
+These changes are automatically applied to your code:
+
+| v3 Pattern | v4 Pattern | Notes |
+|-----------|-----------|-------|
+| `z.record(valueSchema)` | `z.record(z.string(), valueSchema)` | Explicit key type required |
+| `schemaA.merge(schemaB)` | `schemaA.extend(schemaB.shape)` | `.merge()` deprecated |
+| `z.nativeEnum(MyEnum)` | `z.enum(MyEnum)` | `nativeEnum` renamed |
+| `.superRefine(fn)` | `.check(fn)` | Callback signature identical |
+| `error.errors` | `error.issues` | Property renamed |
+| `{ invalid_type_error: 'msg' }` | `{ error: 'msg' }` | Unified error param |
+| `{ required_error: 'msg' }` | `{ error: 'msg' }` | Unified error param |
+| Both error params | `{ error: (issue) => ... }` | Function-based error |
+
+### Deprecation Warnings
+
+These methods still work but are deprecated in v4:
+
+| Method | Replacement | Warning |
+|--------|-------------|---------|
+| `.superRefine()` | `.check()` | Auto-renamed, warning emitted |
+| `.strict()` | `z.strictObject()` | Structural change, review needed |
+| `.passthrough()` | `z.looseObject()` | Structural change, review needed |
+
+### Runtime Behavior Warnings
+
+These changes do not cause compile-time errors but silently change runtime behavior:
+
+| Pattern | Issue |
+|---------|-------|
+| `instanceof Error` on ZodError | `ZodError` no longer extends `Error` in v4 |
+| `.refine()` followed by `.transform()` | `.transform()` now runs even when `.refine()` fails |
+| `.default()` + `.optional()` | `.default()` always provides a value, making `.optional()` a no-op |
+| `.pipe()` | Stricter type checking, may need explicit type annotations |
+
+### Other Detected Changes
+
+| Pattern | Warning |
+|---------|---------|
+| `.flatten()` | Removed in v4, use `.format()` instead |
+| `z.function()` | Input/output parameter changes |
+| `.uuid()` | Stricter RFC 4122 validation |
+| `z.discriminatedUnion()` | Stricter discriminator requirements |
+
+## Mappings Reference
+
+### Behavior Changes Set
+
+Methods with changed behavior in v4: `default`, `uuid`, `record`, `discriminatedUnion`, `function`, `pipe`.
+
+### Deprecated Methods Set
+
+Methods deprecated in v4: `merge`, `superRefine`, `strict`, `passthrough`.
+
+### Auto-Transformable Methods
+
+Methods that are automatically renamed: `superRefine` → `.check()`.
+
+### Error Property Renames
+
+| v3 | v4 |
+|----|----|
+| `.errors` | `.issues` |
+| `.formErrors` | `.formErrors` (unchanged) |
+| `.fieldErrors` | `.fieldErrors` (unchanged) |
+
+### Error Parameter Changes
+
+v3 accepted `invalid_type_error` and `required_error` as separate properties. v4 unifies these under a single `error` property (string or function).
+
+## License
+
+MIT

package/dist/index.cjs

@@ -48,8 +48,37 @@ var BEHAVIOR_CHANGES = /* @__PURE__ */ new Set([
   // Requires key type
   "discriminatedUnion",
   // Stricter discriminator requirements
-  "function"
+  "function",
   // Input/output parameter changes
+  "pipe",
+  // Stricter type checking in v4
+  "catch"
+  // .catch() on optional properties always returns catch value in v4
+]);
+var DEPRECATED_METHODS = /* @__PURE__ */ new Set([
+  "merge",
+  // Use .extend() instead
+  "superRefine",
+  // Use .check() instead
+  "strict",
+  // Use z.strictObject() instead
+  "passthrough"
+  // Use z.looseObject() instead
+]);
+var AUTO_TRANSFORMABLE = /* @__PURE__ */ new Set([
+  "superRefine",
+  // -> .check()
+  "flatten",
+  // error.flatten() -> z.flattenError(error)
+  "format"
+  // error.format() -> z.treeifyError(error)
+]);
+var UTILITY_TYPES = /* @__PURE__ */ new Set([
+  "ZodType",
+  "ZodSchema",
+  "ZodRawShape",
+  "ZodTypeAny",
+  "ZodFirstPartyTypeKind"
 ]);
 
 // src/transformer.ts
@@ -63,8 +92,21 @@ var ZodV3ToV4Transformer = class {
     const originalCode = sourceFile.getFullText();
     try {
       this.transformRecordCalls(sourceFile);
+      this.transformMerge(sourceFile);
+      this.transformNativeEnum(sourceFile);
+      this.transformSuperRefine(sourceFile);
       this.transformErrorProperties(sourceFile);
+      this.transformErrorParams(sourceFile);
+      this.transformFlatten(sourceFile);
+      this.transformFormat(sourceFile);
+      this.transformDefAccess(sourceFile);
+      this.checkDeprecatedMethods(sourceFile);
       this.checkBehaviorChanges(sourceFile);
+      this.checkInstanceofError(sourceFile);
+      this.checkTransformRefineOrder(sourceFile);
+      this.checkDefaultOptional(sourceFile);
+      this.checkCatchOptional(sourceFile);
+      this.checkUtilityTypeImports(sourceFile);
       return {
         success: this.errors.length === 0,
         filePath,
@@ -113,21 +155,394 @@ var ZodV3ToV4Transformer = class {
     });
   }
   /**
-   * Transform error.errors to error.issues
+   * Build a set of variable names that are likely ZodError instances.
+   * Used by transformErrorProperties, transformFlatten, and transformFormat.
+   */
+  buildZodErrorVarSet(sourceFile) {
+    const zodErrorVars = /* @__PURE__ */ new Set();
+    sourceFile.forEachDescendant((node) => {
+      if (import_ts_morph.Node.isVariableDeclaration(node)) {
+        const typeNode = node.getTypeNode();
+        if (typeNode?.getText().includes("ZodError")) {
+          zodErrorVars.add(node.getName());
+        }
+      }
+      if (import_ts_morph.Node.isCatchClause(node)) {
+        const param = node.getVariableDeclaration();
+        if (param) {
+          const block = node.getBlock();
+          const blockText = block.getText();
+          if (blockText.includes("instanceof ZodError") || blockText.includes("ZodError")) {
+            zodErrorVars.add(param.getName());
+          }
+        }
+      }
+      if (import_ts_morph.Node.isVariableDeclaration(node)) {
+        const initializer = node.getInitializer();
+        if (initializer?.getText().includes(".safeParse(")) {
+          zodErrorVars.add(`${node.getName()}.error`);
+        }
+      }
+      if (import_ts_morph.Node.isNewExpression(node)) {
+        if (node.getExpression().getText() === "ZodError") {
+          const parent = node.getParent();
+          if (parent && import_ts_morph.Node.isVariableDeclaration(parent)) {
+            zodErrorVars.add(parent.getName());
+          }
+        }
+      }
+    });
+    return zodErrorVars;
+  }
+  /**
+   * Transform error.errors to error.issues using AST-based detection
+   * instead of heuristic name matching.
    */
   transformErrorProperties(sourceFile) {
+    const filePath = sourceFile.getFilePath();
+    const zodErrorVars = this.buildZodErrorVarSet(sourceFile);
     sourceFile.forEachDescendant((node) => {
       if (import_ts_morph.Node.isPropertyAccessExpression(node)) {
         const name = node.getName();
         if (name === "errors") {
           const object = node.getExpression();
           const objectText = object.getText();
-          if (objectText.toLowerCase().includes("error") || objectText.toLowerCase().includes("err")) {
+          const isZodError = zodErrorVars.has(objectText) || // Also check if accessing .error.errors (safeParse pattern)
+          objectText.endsWith(".error") && zodErrorVars.has(`${objectText.replace(/\.error$/, "")}.error`);
+          if (isZodError) {
             const fullText = node.getText();
             const newText = fullText.replace(/\.errors$/, ".issues");
             node.replaceWithText(newText);
             this.warnings.push(
-              `${sourceFile.getFilePath()}:${node.getStartLineNumber()}: .errors renamed to .issues (ZodError property change)`
+              `${filePath}:${node.getStartLineNumber()}: .errors renamed to .issues (ZodError property change)`
+            );
+          }
+        }
+      }
+    });
+  }
+  /**
+   * Auto-transform error.flatten() to z.flattenError(error) in v4.
+   */
+  transformFlatten(sourceFile) {
+    const filePath = sourceFile.getFilePath();
+    const zodErrorVars = this.buildZodErrorVarSet(sourceFile);
+    const nodesToTransform = [];
+    sourceFile.forEachDescendant((node) => {
+      if (import_ts_morph.Node.isCallExpression(node)) {
+        const expression = node.getExpression();
+        if (import_ts_morph.Node.isPropertyAccessExpression(expression) && expression.getName() === "flatten") {
+          const objectText = expression.getExpression().getText();
+          const isZodError = zodErrorVars.has(objectText) || objectText.endsWith(".error") && zodErrorVars.has(`${objectText.replace(/\.error$/, "")}.error`);
+          if (isZodError) {
+            nodesToTransform.push({
+              node,
+              objectText,
+              lineNumber: node.getStartLineNumber()
+            });
+          } else {
+            this.warnings.push(
+              `${filePath}:${node.getStartLineNumber()}: .flatten() is removed in v4. Use z.flattenError(error) or access error.issues directly. See: https://zod.dev/v4/changelog`
+            );
+          }
+        }
+      }
+    });
+    nodesToTransform.sort((a, b) => b.node.getStart() - a.node.getStart());
+    for (const { node, objectText, lineNumber } of nodesToTransform) {
+      node.replaceWithText(`z.flattenError(${objectText})`);
+      this.warnings.push(
+        `${filePath}:${lineNumber}: .flatten() auto-transformed to z.flattenError(). Removed in v4 \u2014 now a standalone function.`
+      );
+    }
+  }
+  /**
+   * Auto-transform error.format() to z.treeifyError(error) in v4.
+   */
+  transformFormat(sourceFile) {
+    const filePath = sourceFile.getFilePath();
+    const zodErrorVars = this.buildZodErrorVarSet(sourceFile);
+    const nodesToTransform = [];
+    sourceFile.forEachDescendant((node) => {
+      if (import_ts_morph.Node.isCallExpression(node)) {
+        const expression = node.getExpression();
+        if (import_ts_morph.Node.isPropertyAccessExpression(expression) && expression.getName() === "format") {
+          const objectText = expression.getExpression().getText();
+          const isZodError = zodErrorVars.has(objectText) || objectText.endsWith(".error") && zodErrorVars.has(`${objectText.replace(/\.error$/, "")}.error`);
+          if (isZodError) {
+            nodesToTransform.push({
+              node,
+              objectText,
+              lineNumber: node.getStartLineNumber()
+            });
+          }
+        }
+      }
+    });
+    nodesToTransform.sort((a, b) => b.node.getStart() - a.node.getStart());
+    for (const { node, objectText, lineNumber } of nodesToTransform) {
+      node.replaceWithText(`z.treeifyError(${objectText})`);
+      this.warnings.push(
+        `${filePath}:${lineNumber}: .format() auto-transformed to z.treeifyError(). Removed in v4 \u2014 now a standalone function.`
+      );
+    }
+  }
+  /**
+   * Auto-transform ._def property access to ._zod.def in v4.
+   */
+  transformDefAccess(sourceFile) {
+    const filePath = sourceFile.getFilePath();
+    const nodesToTransform = [];
+    sourceFile.forEachDescendant((node) => {
+      if (import_ts_morph.Node.isPropertyAccessExpression(node) && node.getName() === "_def") {
+        nodesToTransform.push({ node, lineNumber: node.getStartLineNumber() });
+      }
+    });
+    nodesToTransform.sort((a, b) => b.node.getStart() - a.node.getStart());
+    for (const { node, lineNumber } of nodesToTransform) {
+      const objectText = node.getExpression().getText();
+      node.replaceWithText(`${objectText}._zod.def`);
+      this.warnings.push(
+        `${filePath}:${lineNumber}: ._def auto-transformed to ._zod.def. Internal API \u2014 structure may change between releases.`
+      );
+    }
+  }
+  /**
+   * Transform .merge(otherSchema) to .extend(otherSchema.shape)
+   */
+  transformMerge(sourceFile) {
+    const filePath = sourceFile.getFilePath();
+    const nodesToTransform = [];
+    sourceFile.forEachDescendant((node) => {
+      if (import_ts_morph.Node.isCallExpression(node)) {
+        const expression = node.getExpression();
+        if (import_ts_morph.Node.isPropertyAccessExpression(expression) && expression.getName() === "merge") {
+          nodesToTransform.push({ node, lineNumber: node.getStartLineNumber() });
+        }
+      }
+    });
+    nodesToTransform.sort((a, b) => b.node.getStart() - a.node.getStart());
+    for (const { node, lineNumber } of nodesToTransform) {
+      const args = node.getArguments();
+      if (args.length === 1) {
+        const argText = args[0]?.getText();
+        if (argText) {
+          const expression = node.getExpression();
+          if (import_ts_morph.Node.isPropertyAccessExpression(expression)) {
+            const objectText = expression.getExpression().getText();
+            node.replaceWithText(`${objectText}.extend(${argText}.shape)`);
+            this.warnings.push(
+              `${filePath}:${lineNumber}: .merge() renamed to .extend() with .shape access. Verify the merged schema exposes .shape.`
+            );
+          }
+        }
+      }
+    }
+  }
+  /**
+   * Transform z.nativeEnum(X) to z.enum(X)
+   */
+  transformNativeEnum(sourceFile) {
+    const filePath = sourceFile.getFilePath();
+    const fullText = sourceFile.getFullText();
+    const newText = fullText.replace(/\bz\.nativeEnum\(/g, "z.enum(");
+    if (newText !== fullText) {
+      sourceFile.replaceWithText(newText);
+      this.warnings.push(
+        `${filePath}: z.nativeEnum() renamed to z.enum() in v4. Verify enum values are compatible.`
+      );
+    }
+  }
+  /**
+   * Check for deprecated methods and add warnings
+   */
+  checkDeprecatedMethods(sourceFile) {
+    const filePath = sourceFile.getFilePath();
+    sourceFile.forEachDescendant((node) => {
+      if (import_ts_morph.Node.isCallExpression(node)) {
+        const expression = node.getExpression();
+        if (import_ts_morph.Node.isPropertyAccessExpression(expression)) {
+          const name = expression.getName();
+          if (DEPRECATED_METHODS.has(name) && !AUTO_TRANSFORMABLE.has(name)) {
+            const lineNumber = node.getStartLineNumber();
+            switch (name) {
+              case "strict":
+                this.warnings.push(
+                  `${filePath}:${lineNumber}: .strict() is deprecated in v4. Use z.strictObject() instead.`
+                );
+                break;
+              case "passthrough":
+                this.warnings.push(
+                  `${filePath}:${lineNumber}: .passthrough() is deprecated in v4. Use z.looseObject() instead.`
+                );
+                break;
+            }
+          }
+        }
+      }
+    });
+  }
+  /**
+   * Auto-transform .superRefine() to .check() — callback signature is identical.
+   */
+  transformSuperRefine(sourceFile) {
+    const filePath = sourceFile.getFilePath();
+    const nodesToTransform = [];
+    sourceFile.forEachDescendant((node) => {
+      if (import_ts_morph.Node.isPropertyAccessExpression(node) && node.getName() === "superRefine") {
+        nodesToTransform.push({ node, lineNumber: node.getStartLineNumber() });
+      }
+    });
+    nodesToTransform.sort((a, b) => b.node.getStart() - a.node.getStart());
+    for (const { node, lineNumber } of nodesToTransform) {
+      const parent = node.getParent();
+      if (parent && import_ts_morph.Node.isCallExpression(parent)) {
+        const objectText = node.getExpression().getText();
+        const args = parent.getArguments();
+        let argsText = args.map((a) => a.getText()).join(", ");
+        if (args.length > 0) {
+          const callbackText = args[0]?.getText() ?? "";
+          const paramMatch = callbackText.match(
+            /^\s*\(?\s*\w+\s*,\s*(\w+)\s*\)?(?:\s*:\s*[^)]+)?\s*=>/
+          );
+          if (paramMatch?.[1]) {
+            const ctxName = paramMatch[1];
+            const addIssuePattern = new RegExp(`${ctxName}\\.addIssue\\(`, "g");
+            if (addIssuePattern.test(callbackText)) {
+              argsText = callbackText.replace(
+                new RegExp(`${ctxName}\\.addIssue\\(`, "g"),
+                `${ctxName}.issues.push(`
+              );
+              if (args.length > 1) {
+                const remaining = args.slice(1).map((a) => a.getText()).join(", ");
+                argsText = `${argsText}, ${remaining}`;
+              }
+            }
+          }
+        }
+        parent.replaceWithText(`${objectText}.check(${argsText})`);
+        this.warnings.push(
+          `${filePath}:${lineNumber}: .superRefine() auto-transformed to .check() (deprecated in v4).`
+        );
+      }
+    }
+  }
+  /**
+   * Auto-transform invalid_type_error/required_error params to unified `error` param.
+   */
+  transformErrorParams(sourceFile) {
+    const filePath = sourceFile.getFilePath();
+    const nodesToTransform = [];
+    sourceFile.forEachDescendant((node) => {
+      if (import_ts_morph.Node.isObjectLiteralExpression(node)) {
+        const properties = node.getProperties();
+        const propNames = properties.filter((p) => import_ts_morph.Node.isPropertyAssignment(p)).map((p) => import_ts_morph.Node.isPropertyAssignment(p) ? p.getName() : "");
+        const hasInvalidType = propNames.includes("invalid_type_error");
+        const hasRequired = propNames.includes("required_error");
+        if (hasInvalidType || hasRequired) {
+          const parent = node.getParent();
+          if (parent && import_ts_morph.Node.isCallExpression(parent)) {
+            const expr = parent.getExpression();
+            if (import_ts_morph.Node.isPropertyAccessExpression(expr) && expr.getExpression().getText() === "z") {
+              nodesToTransform.push({ node, lineNumber: node.getStartLineNumber() });
+            }
+          }
+        }
+      }
+    });
+    nodesToTransform.sort((a, b) => b.node.getStart() - a.node.getStart());
+    for (const { node, lineNumber } of nodesToTransform) {
+      const properties = node.getProperties();
+      let invalidTypeValue;
+      let requiredValue;
+      const otherProps = [];
+      for (const prop of properties) {
+        if (import_ts_morph.Node.isPropertyAssignment(prop)) {
+          const name = prop.getName();
+          const value = prop.getInitializer()?.getText() ?? "";
+          if (name === "invalid_type_error") {
+            invalidTypeValue = value;
+          } else if (name === "required_error") {
+            requiredValue = value;
+          } else {
+            otherProps.push(prop.getText());
+          }
+        }
+      }
+      let errorValue;
+      if (invalidTypeValue && requiredValue) {
+        errorValue = `error: (issue) => issue.input === undefined ? ${requiredValue} : ${invalidTypeValue}`;
+      } else if (requiredValue) {
+        errorValue = `error: ${requiredValue}`;
+      } else if (invalidTypeValue) {
+        errorValue = `error: ${invalidTypeValue}`;
+      } else {
+        continue;
+      }
+      const allProps = [errorValue, ...otherProps].join(", ");
+      node.replaceWithText(`{ ${allProps} }`);
+      this.warnings.push(
+        `${filePath}:${lineNumber}: invalid_type_error/required_error auto-transformed to unified error param.`
+      );
+    }
+  }
+  /**
+   * Detect instanceof Error patterns in catch blocks that reference ZodError.
+   * In v4, ZodError no longer extends Error.
+   */
+  checkInstanceofError(sourceFile) {
+    const filePath = sourceFile.getFilePath();
+    sourceFile.forEachDescendant((node) => {
+      if (import_ts_morph.Node.isCatchClause(node)) {
+        const block = node.getBlock();
+        const blockText = block.getText();
+        if (blockText.includes("ZodError") && blockText.includes("instanceof Error")) {
+          const lineNumber = node.getStartLineNumber();
+          this.warnings.push(
+            `${filePath}:${lineNumber}: ZodError no longer extends Error in v4. \`instanceof Error\` checks on ZodError will return false. Use \`instanceof ZodError\` or check for \`.issues\` property instead.`
+          );
+        }
+      }
+    });
+  }
+  /**
+   * Detect .refine()/.superRefine() followed by .transform() in the same chain.
+   * In v4, .transform() runs even when .refine() fails.
+   */
+  checkTransformRefineOrder(sourceFile) {
+    const filePath = sourceFile.getFilePath();
+    sourceFile.forEachDescendant((node) => {
+      if (import_ts_morph.Node.isCallExpression(node)) {
+        const expression = node.getExpression();
+        if (import_ts_morph.Node.isPropertyAccessExpression(expression) && expression.getName() === "transform") {
+          const chainText = node.getText();
+          if (chainText.includes(".refine(") || chainText.includes(".superRefine(") || chainText.includes(".check(")) {
+            const lineNumber = node.getStartLineNumber();
+            this.warnings.push(
+              `${filePath}:${lineNumber}: In v4, .transform() executes even if preceding .refine() fails. Consider using .pipe() to sequence validation before transforms.`
+            );
+          }
+        }
+      }
+    });
+  }
+  /**
+   * Detect .default() combined with .optional() — behavior changed silently in v4.
+   * In v4, .default() always provides a value, making .optional() a no-op.
+   */
+  checkDefaultOptional(sourceFile) {
+    const filePath = sourceFile.getFilePath();
+    sourceFile.forEachDescendant((node) => {
+      if (import_ts_morph.Node.isCallExpression(node)) {
+        const expression = node.getExpression();
+        if (import_ts_morph.Node.isPropertyAccessExpression(expression) && (expression.getName() === "optional" || expression.getName() === "default")) {
+          const chainText = node.getText();
+          const hasDefault = chainText.includes(".default(");
+          const hasOptional = chainText.includes(".optional(");
+          if (hasDefault && hasOptional) {
+            const lineNumber = node.getStartLineNumber();
+            this.warnings.push(
+              `${filePath}:${lineNumber}: .default() + .optional() behavior changed in v4. .default() now always provides a value, making .optional() effectively a no-op. Review whether .optional() is still needed.`
             );
           }
         }
@@ -167,20 +582,55 @@ var ZodV3ToV4Transformer = class {
                   `${filePath}:${lineNumber}: z.function() parameter handling has changed. Review input/output schema definitions.`
                 );
                 break;
+              case "pipe":
+                this.warnings.push(
+                  `${filePath}:${lineNumber}: .pipe() has stricter type checking in v4. If you get type errors, add explicit type annotations to .transform() return types or cast through unknown as a last resort.`
+                );
+                break;
             }
           }
         }
       }
     });
-    const text = sourceFile.getFullText();
-    if (text.includes(".flatten()")) {
-      const matches = text.matchAll(/\.flatten\(\)/g);
-      for (const match of matches) {
-        const pos = match.index ?? 0;
-        const lineNumber = sourceFile.getLineAndColumnAtPos(pos).line;
-        this.warnings.push(
-          `${filePath}:${lineNumber}: .flatten() is removed in v4. Use error.issues directly or implement custom flattening.`
-        );
+  }
+  /**
+   * Detect .catch() combined with .optional() — behavior changed in v4.
+   * In v4, .catch() on optional properties always returns the catch value.
+   */
+  checkCatchOptional(sourceFile) {
+    const filePath = sourceFile.getFilePath();
+    sourceFile.forEachDescendant((node) => {
+      if (import_ts_morph.Node.isCallExpression(node)) {
+        const expression = node.getExpression();
+        if (import_ts_morph.Node.isPropertyAccessExpression(expression) && (expression.getName() === "optional" || expression.getName() === "catch")) {
+          const chainText = node.getText();
+          if (chainText.includes(".catch(") && chainText.includes(".optional(")) {
+            const lineNumber = node.getStartLineNumber();
+            this.warnings.push(
+              `${filePath}:${lineNumber}: .catch() + .optional() behavior changed in v4. .catch() on optional properties now always returns the catch value, even when the property is absent from input.`
+            );
+          }
+        }
+      }
+    });
+  }
+  /**
+   * Detect imports of utility types that moved to 'zod/v4/core' in v4.
+   */
+  checkUtilityTypeImports(sourceFile) {
+    const filePath = sourceFile.getFilePath();
+    for (const importDecl of sourceFile.getImportDeclarations()) {
+      const moduleSpecifier = importDecl.getModuleSpecifierValue();
+      if (moduleSpecifier !== "zod") continue;
+      const namedImports = importDecl.getNamedImports();
+      for (const namedImport of namedImports) {
+        const name = namedImport.getName();
+        if (UTILITY_TYPES.has(name)) {
+          const lineNumber = importDecl.getStartLineNumber();
+          this.warnings.push(
+            `${filePath}:${lineNumber}: '${name}' may need to be imported from 'zod/v4/core' in v4. Internal utility types have moved to a separate subpackage.`
+          );
+        }
       }
     }
   }