feat!: support both zod v3 and zod v4 (#366)

#310

- reworks the `ZodBuilder` -> `ZodV3Builder`, and uses the `/v3`
sub-path import
- introduces a `ZodV4Builder`

efforts have been made to retain support for zod v3 at this stage, and
make upgrading seamless, aside from updating the CLI parameter to
indicate v3 vs v4. An alpha release will be published and used for
regression testing against private projects before release.

BREAKING CHANGE: default schema builder now `zod-v4`, pass `zod-v3` to
continue using `zod@^3`

Author: mnahkies

.github/workflows/ci.yml

@@ -123,7 +123,7 @@ jobs:
     strategy:
       matrix:
         node-version: *node-versions
-        schema-builder: [joi, zod]
+        schema-builder: [joi, zod-v3, zod-v4]
     steps:
       - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
@@ -149,7 +149,7 @@ jobs:
       - run: pnpm integration:validate
 
       - name: Check for uncommitted changes
-        if: ${{ matrix.schema-builder == 'zod' }}
+        if: ${{ matrix.schema-builder == 'zod-v4' }}
         run: ./scripts/assert-clean-working-directory.sh
 
   e2e:
@@ -178,7 +178,10 @@ jobs:
 
       - run: pnpm install --frozen-lockfile
 
-      - run: SCHEMA_BUILDER=zod pnpm e2e:generate
+      - run: SCHEMA_BUILDER=zod-v3 pnpm e2e:generate
+      - run: pnpm e2e:validate
+
+      - run: SCHEMA_BUILDER=zod-v4 pnpm e2e:generate
       - run: pnpm e2e:validate
 
       - name: Check for uncommitted changes

e2e/package.json

@@ -21,7 +21,7 @@
     "axios": "^1.12.2",
     "express": "^5.1.0",
     "koa": "^3.0.1",
-    "zod": "3.25.74"
+    "zod": "^3.25.74"
   },
   "devDependencies": {
     "@jest/globals": "^30.2.0",

e2e/scripts/generate.sh

@@ -2,7 +2,7 @@
 
 set -e
 
-SCHEMA_BUILDER="${SCHEMA_BUILDER:-zod}"
+SCHEMA_BUILDER="${SCHEMA_BUILDER:-zod-v4}"
 
 pnpm openapi-code-generator \
   --input ./openapi.yaml \