feat(v28): Supporting Zod 4.4

[RobinTail]

adds xBrand() method to Zod Plugin instead of patching exiting one.
due to #3357

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 9deb8bf2-bc0e-4990-b9ee-f2d57dd233ff

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch support-zod44

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	zod@​4.3.6 ⏵ 4.4.1	+1		+1	+8

View full report

[coveralls-official]

coverage: 100.0%. remained the same — support-zod44 into make-v28

[pullfrog]

Important

A few issues to address before merging.

Outside the diff (not commentable inline):

• README.md lines 1105, 1254, 1269 still reference .brand() as the plugin's enhanced method. These should be updated to .xBrand() as part of this v28 work.
• The zod-44-problem.md file appears to be a planning/scratch document. Consider whether it should be committed to the repo or removed before merge.
• Zod 4.4 no longer populates jsonSchema.id from .meta({ id: "..." }), which causes the example's Feature schema to become Schema1 in the generated OpenAPI spec. The framework's documentation-helpers.ts:322-383 still reads depiction.id for naming components. This is a user-facing regression for anyone relying on .meta({ id }) for stable schema names in their docs — worth documenting in the CHANGELOG or compensating for in the framework.

Task list (5/5 completed)

• Read the PR diff and understand the scope of changes
• Examine high-risk areas: zod-plugin changes, runtime code
• Examine CHANGELOG, documentation, and snapshot changes
• Check zod-44-problem.md for context
• Self-critique and submit review

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

Fixed the typo "distinguisable" → "distinguishable" in CHANGELOG.md as requested.

  ^{｜ View workflow run ｜ via Pullfrog ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

Fixed the typo ("intto" → "into") in express-zod-api/tests/env.spec.ts and pushed.

Task list (2/2 completed)

• Fix typo "intto" → "into" in env.spec.ts
• Commit, push, and reply to review comment

  ^{｜ View workflow run ｜ via Pullfrog ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

No new issues. Reviewed the following changes:

• Added filterNaming in fixReferences to preserve user-defined schema names (from .meta({ id })) while filtering out Zod's auto-generated $defs keys (matching schema\d+$), fixing the component naming regression when depiction.id is no longer populated by Zod 4.4
• Updated Zod from 4.3.6 to 4.4.1 and widened the peer/dev specifiers from ~4.3.4 to ^4.3.4/^4.4.1
• Updated snapshots to reflect Zod 4.4 behavioral changes (CUID regex pattern, undefined optionality, removal of id from JSON schema output)

Prior review feedback:

• Zod 4.4 depiction.id regression causing schema names to be lost — addressed via filterNaming fallback

  ^{｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

Acknowledged the author's fix in 2d3edc3 for the CHANGELOG grammar issue. Thread resolved — no further changes needed.

Task list (2/2 completed)

• Review author's reply to CHANGELOG grammar comment
• Acknowledge fix - no further changes needed

  ^{｜ View workflow run ｜ via Pullfrog ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

No new issues. Reviewed the following changes:

• Updated README.md references from .brand() to .xBrand() at all three locations (plugin method list, brand handling prose, and code example)

Prior review feedback:

• README.md lines 1105, 1254, 1269 still reference .brand() — addressed

  ^{｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[RobinTail]

@pullfrog please review. Tell me if I'm missing something.

[pullfrog]

Reviewed — no issues found.

The changes are well-structured and handle the Zod 4.4 compatibility correctly:

• fixReferences in documentation-helpers.ts — correctly adapts to Zod 4.4's change where .meta({ id }) no longer appears as a property in the JSON schema output but instead becomes the $defs key. The filterNaming regex correctly filters both schema0 and __schema0 auto-generated keys.
• .brand() → .xBrand() rename — clean approach that avoids conflicting with Zod 4.4's native .brand() (which is now purely structural/type-level, not runtime). The simpler defineProperty with value (instead of the set/get accessor dance) is a nice cleanup.
• No migration rule for .brand() → .xBrand() — this is the right call since Zod's native .brand() still exists and an automated rename could incorrectly transform legitimate native usages.
• Snapshot changes (undefined?: undefined → undefined: undefined) — correctly reflects Zod 4's semantics where z.undefined() means "key must be present with value undefined", not "key is optional".

Re "am I missing something": I don't see anything missing. The CHANGELOG, README, plugin README, and plugin CHANGELOG are all consistent with the code changes. The diff block in CHANGELOG correctly shows only the changes covered by the automated migration tool.

Task list (4/4 completed)

• Read the full diff to understand the scope of changes
• Investigate high-risk areas (documentation helpers, zod-plugin changes, breaking changes)
• Check for stale references or missing updates
• Submit review

  ^{｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[RobinTail]

🏁