Migrate to Zod 4 and make Zod 3 opt-in

[ramilamparo]

Summary

Migrate zen to support Zod v4 as the default output, with v3 available via WithZodV3(). Includes a refactor of string schema generation and a new test infrastructure.

Zod v4 output changes

Format validators use .check() pattern

Format validators use z.string().check(z.email()) instead of z.email() as the schema base. This preserves the z.string() base so that transforms like .trim(), .min(), etc. chain correctly in any position. For example, validate:"trim,email" produces z.string().trim().check(z.email()) which trims before validating. See colinhacks/zod#4642

IP union

ip/ip_addr tags produce z.union([z.string().check(z.ipv4()), z.string().check(z.ipv6())]) with constraints distributed to each arm.

Self-referential getter pattern

get field() { return Schema; } instead of z.lazy(() => Schema).

Embedded struct spreads

...Schema.shape instead of .merge(Schema). Spreads are placed before named fields so that Go's field shadowing semantics are preserved (last key wins in JS).

Partial records

z.partialRecord() for enum-keyed maps.

Invalid combinations panic

• email,ip (format + union) and email,url (multiple formats) panic instead of producing broken output
• Enum (oneof/boolean) combined with non-enum validators (e.g. oneof=a b,contains=x) panics — oneof fully constrains the value
• dive,keys without matching endkeys panics with a clear message
• Non-numeric arguments to numeric validators (gt=abc) panic via requireIntArg/requireNumericArg

String schema generation refactor

The original validateString built Zod output directly using a strings.Builder — mixing parsing and rendering in one pass with no intermediate representation. This made v3/v4 branching difficult and led to edge cases with tag ordering.

• parseStringValidators — pure parser producing []stringValidator via knownStringTags map lookup
• renderStringSchema — version-aware renderer that classifies validators, validates combinations, and renders the complete schema in one pass
• renderChain — shared rendering for version-independent validators
• renderV3Chain — v3-specific format chains (.email(), .ip(), .regex())
• renderV4FormatCheck — v4 format check chains (.check(z.email()), .check(z.uuid()), etc.)
• Regex patterns consolidated into maps with renderRegex() helpers

Bug fixes (pre-existing)

• preprocessValidationTagPart now passes actual reflect.Type to custom tag handlers instead of always reflect.TypeOf("")
• strings.ToTitle (deprecated) replaced with strings.ToUpper
• getValidateValues guards against missing endkeys and bare dive

Security

• escapeJSString() escapes \ and " in generated JS string literals
• Numeric arguments validated for len/min/max/gt/gte/lt/lte

New public API

• WithZodV3() Opt — opt into Zod v3 output
• AddTypeWithName(input, name) — register anonymous structs with custom names

Test infrastructure

• Golden file testing via github.com/xorcare/golden — make test-update to regenerate
• Docker TypeScript testing (make docker-test) — typechecks all golden files with tsc against zod@3 and zod@4, then runs vitest runtime tests against both versions
• Table-driven tests with assertValidators + buildValidatorConverter using dynamic structs

Test plan

• All Go golden file tests pass
• TypeScript typecheck passes for v3 and v4
• 170+ runtime tests pass for both zod versions
• Invalid combinations panic
• Integration test with tms/packages/schemas consumer

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces Zod v4 schema generation as the default output format, featuring object shape spreads for embedded structs and specialized builders for string formats, while providing a legacy v3 compatibility mode and an updated golden-file-based testing suite. Feedback from the review highlights critical runtime and compatibility issues: the implementation of self-referential types using get accessors will likely trigger ReferenceError or TypeError during schema construction, and several emitted helpers—such as z.email(), z.uuid(), and z.partialRecord—are not standard Zod APIs, which would cause failures for users of the official library.

[claude]

Review Summary

The latest changes (1816be7 — .check() pattern + always emit .min(1) for required) are a major improvement that significantly simplifies the codebase:

What improved:

• .check() pattern — Format validators now use z.string().check(z.email()) instead of top-level z.email() builders. This addresses the earlier Gemini review concern about non-standard Zod APIs and eliminates the complex hasTransformBefore / formatIdx / v4AcceptsEmpty ordering logic entirely.
• required always emits .min(1) — Removes all skipRequired / keepRequired branching for format/union validators, making behavior consistent and predictable across all string schemas.
• IP unions use z.string().check() — z.union([z.string().check(z.ipv4()), z.string().check(z.ipv6())]) properly keeps the z.string() base, ensuring transforms chain correctly.
• Simplified goldenAssert — Removed the goldenMeta/goldenOpt indirection in favor of a direct (t, data, version) signature.
• resolveGolden in test infra — Tests now reference directories (e.g., "TestNestedStruct") instead of version-specific files, with automatic version resolution. Cleaner test case definitions.

Architecture highlights:

• Clean v3/v4 split with WithZodV3() opt-in — minimal branching in core logic
• parseStringValidators / renderStringSchema separation is solid
• Golden file + docker type-check + vitest runtime tests provide strong end-to-end confidence
• Security: All string interpolation paths properly escaped via escapeJSString + json.Marshal, numeric args validated via requireIntArg/requireNumericArg

No new issues found. Previous review feedback has been well addressed across all rounds. The code is clean, well-tested, and ready to merge.