feat: new scalarParse translation function

[tmastrom]

This PR adds scalarParse to oas-utils to convert the output of the parser into a more usable data object for rendering. The translation layer dereferences and groups fields for rendering as well as creates new zod schemas for parsing incoming data. We want to allow malformed data as much as possible to render what we can.

The parse.ts function is removed from @scalar/api-reference and replaced with the new scalarParse function

Todo

• decide on critical error handling
  • we can implement custom errors, refinements, and preprocessing in zod schemas as well as safe parsing data to give a good sense of what data is available
• don't blow up the bundle size - what to do with testing yaml files?
• proper yaml import process for testing

[changeset-bot]

⚠️ No Changeset found

Latest commit: 7905777

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[relativeci]

Job #959: Bundle Size — 1.97MiB (+2.77%).

8e5beeb(current) vs 3d4d83e main#954(baseline)

Warning

Bundle contains 4 duplicate packages – View duplicate packages

Warning

Bundle introduced one new package: zod – View changed packages

Bundle metrics   3 changes 2 regressions

	Current Job #959	Baseline Job #954
Initial JS	1.97MiB(+2.77%)	1.92MiB
Initial CSS	0B	0B
Cache Invalidation	100%	100%
Chunks	1	1
Assets	1	1
Modules	1044(+0.19%)	1042
Duplicate Modules	0	0
Duplicate Code	0%	0%
Packages	159(+0.63%)	158
Duplicate Packages	4	4

Bundle size by type   1 change 1 regression

	Current Job #959	Baseline Job #954
JS	1.97MiB (+2.77%)	1.92MiB

---

View job #959 report View tom/doc-1637-scalarparse branch activity View project dashboard

[geoffgscott]

We should break all the test files out into a separate repo so it can just be installed as a dev depedency and keep the spec files out of the main repo.

[tmastrom]

Moved these test files to the CDN for now while we figure out the best way to break out the test files

[hanspagel]

Great work already! Shouldn’t we keep this in @scalar/api-reference, though? It’s not useful for other people, transformResult is just too specific to our needs. 🤔

[tmastrom]

Great work already! Shouldn’t we keep this in @scalar/api-reference, though? It’s not useful for other people, transformResult is just too specific to our needs. 🤔

The only downside I see to this is adding a dependency to @scalar/api-reference but I would defer to @marclave and @geoffgscott for this decision.

[hanspagel]

Dumb question: What dependency do we need to add to @scalar/api-reference? 😳

[tmastrom]

@scalar/api-reference would need to import oas-utils to use this new translation function with the current package setup @hanspagel but it looks like it is already using this package so there would actually be no change.