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

z.string().check(z.email()) instead of deprecated z.string().email(). Handles transform ordering correctly (e.g., z.string().trim().check(z.email()) trims before validating). See colinhacks/zod#4642

IP union

ip/ip_addr tags produce z.union([z.ipv4(), 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.

Redundant .min(1) removed

Format validators already reject empty strings, so required tag's .min(1) is omitted. Exception: base64/hexadecimal in v4 which accept empty strings.

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())
• renderV4FormatBase — v4 format builders (z.email(), 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

Well-structured migration after many review rounds. The major issues from prior reviews (JS string escaping via json.Marshal, convertResult struct, shared renderChain, requireIntArg/requireNumericArg validation, renderV4FormatBase panic, getValidateValues guards, WithIgnoreTags tests, boolean enum fix) have all been addressed.

Architecture highlights:

• Clean v3/v4 split with WithZodV3() opt-in
• parseStringValidators / renderStringSchema separation is a solid improvement over the original single-pass approach
• Golden file + docker type-check + vitest runtime tests provide strong end-to-end confidence
• assertSchema helper elegantly handles version-specific vs shared golden files

Remaining items (all low):

1. Potential panic in getTypeNameWithGenerics on empty generic type arg
2. Empty if-branch in getValidateCurrent could be more explicit

No high or critical issues found. The security posture is good — string interpolation paths are properly escaped, numeric arguments are validated, and invalid tag combinations panic with clear messages.

[claude]

Low: Potential panic on empty generic type argument

arg[:1] will panic with index out of range if arg is an empty string. This can happen if a generic type name has malformed syntax like Type[,T], where splitting on comma produces an empty element.

Suggested change

	sb.WriteString(strings.ToUpper(arg[:1])) // Capitalize first letter
	for _, arg := range typeArgs {
	if len(arg) == 0 {
	continue
	}
	sb.WriteString(strings.ToUpper(arg[:1])) // Capitalize first letter
	sb.WriteString(arg[1:])
	}

[claude]

Praise: Excellent test infrastructure

The golden file + docker type-check + vitest runtime test combination is a really solid approach. Dynamic schema import with version-aware skipping ensures both zod v3 and v4 outputs are validated end-to-end. The cases.ts table-driven tests complement the golden file snapshots well.