enhancement: improve error messages and add runtime detection for Zod v3/v4 (#1)

[Jesssullivan]

Hi there!

This is my stab at improving the migration flow from zod 3 --> zod 4, I like other users frequently encounter the cryptic error "No shape could be created for schema" when mistakenly using the Zod v3 adapter (zod) with Zod v4 schemas.

This appears to be a common source of confusion (see #594, #630, #649), and I for one usually forget the zod4 revisions needed when upgrading projects to the new structure.

Enhancements:

• Revise error message with hint - Add hint to "No shape could be created" error suggesting the zod4 adapter
• Runtime detection - Add console.warn() in the zod adapter when a Zod v4 schema structure is detected
• Added a test

Some questions:

1. Is the [superforms] prefix desired for warnings, or should a different format be used?
2. Should the detection also be added to zodToJSONSchema function for earlier detection?
3. Any preference on test file naming convention?

Closes #673
Closes #594

Add Runtime Detection to Zod v3 Adapter

File: src/lib/adapters/zod.ts:58-70

• console.warn is allowed by ESLint config
• Warning is emitted at adapter creation time (early detection)
• Message includes actionable fix
• Prefix [superforms] helps identify source

---

Test for Runtime Detection

File: src/tests/zod-version-detection.test.ts (new file)

To test:

cd /Users/jsullivan2/git/sveltekit-superforms
pnpm install
pnpm test
pnpm lint                    # Check code style
pnpm check                   # TypeScript checks

Manual Testing

1. Create a test project with Zod v4
2. Import { zod } (v3 adapter) instead of { zod4 }
3. Verify warning is emitted in console
4. Verify error message includes helpful hint

[vercel]

@Jesssullivan is attempting to deploy a commit to the Andreas Sderlund's projects Team on Vercel.

A member of the Team first needs to authorize it.

[ciscoheat]

Hello, thank you! Looks very good. No [superforms] prefix is needed, it's obvious what's going on. Happy to merge it and add to the next release!

[ciscoheat]

Fixed in #678