Improve Zod error messages and user config error messages

[delucis]

Changes

• Upstreams improvements to the Zod error map that we made in Starlight. We initially copied Astro’s error map and then iterated on it. It’s still similar, just with better handling for complex types like unions, and more consistent formatting (e.g. if you look at the changed tests you’ll see we’d report errors where some stuff was wrapped with backticks and other stuff wasn’t within the same error message and that that is now fixed).

• Updates error handling for user config parse errors to use the error map. With the v5 release, we’re seeing a fair amount of the rather confusing output Invalid input error when people leave output: "hybrid" in their config and this aims to improve that.

  • This also updates the styling for these messages as they can now contain a bit more useful information. Open to feedback/suggestions on the design there. It reuses the Markdown formatter we already use for error rendering and adds some additional details for this specific context.

• Fixes a broken docs link in one of our error messages.

Example

Example error message with this change when adding output: 'hybrid', experimental: { contentLayer: true } to an astro.config file:

Currently

After this PR

Testing

• I’ve updated our existing error message tests to test for the updated message format
• I manually ran astro dev in the blog example using invalid configurations to test output.

Docs

n/a — error message improvements only

[changeset-bot]

🦋 Changeset detected

Latest commit: 2170904

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[codspeed-hq]

CodSpeed Performance Report

Merging #12634 will not alter performance

_{Comparing chris/better-error-messages (2170904) with main (22e405a)}

Summary

✅ 4 untouched benchmarks

[florian-lefebvre]

I think the error map is exported and used in astro:db, do you think you could import it and use it as is in Starlight?

[delucis]

I think the error map is exported and used in astro:db, do you think you could import it and use it as is in Starlight?

Yes! Didn't know it was available to external packages. After this PR it will be exactly the same as Starlight's so we could definitely reuse it.

[Princesseuh]

My highly-featured markdown renderer keep seeing usage 🫡