feat: sort out $ref resolving once and for all

[P0lip]

When signing off https://github.com/stoplightio/platform-internal/issues/5218 I spotted there is at least one additional place I didn't cover... This freaked me out a little bit, and I decided to revamp our approach to $ref resolving.
I'm uncertain whether we'll merge it or not, but opening a PR to have a forum to discuss the pros and cons.

Alright, here is the idea.
Instead of resolving each $ref in place, we could simply 'trap' the whole document.
I created a small util that would do that for us stoplightio/json#72.

In other words, Graphite would do something as follows transformXyz(inlineRefResolver(node.data.resolved)) and all inline $refs would be automatically resolved as needed.

There is one significant (or maybe not?) con - we'd also potentially attempt to resolve $refs in invalid zones. OAS doesn't let you use $refs everywhere, thus the current conservative approach is perhaps a bit more correct here, but also much more difficult to maintain.
The hope is that Spectral could notify about incorrect usage, or we could bake an ignorelist in the util itself.

[marbemac]

Hmm does this mean that when we serialize and send the operation up to our backend to store in the database, that it'll end up getting stored fully dereferenced? 🤔

[lottamus]

We likely only want to resolve local references that are not nested within a "schema" object.

[P0lip]

Hmm does this mean that when we serialize and send the operation up to our backend to store in the database, that it'll end up getting stored fully dereferenced? thinking

Yeah, but we're doing the same now after all.

We likely only want to resolve local references that are not nested within a "schema" object.

hmmm, yeah, you might be right, though at the same time the openapi-schema-to-json-schema library expects all $refs to be resolved.

[marcelltoth]

@P0lip Fun fact, we are actually doing something very similar locally on the elements level: https://github.com/stoplightio/elements/blob/main/packages/elements-core/src/utils/ref-resolving/resolvedObject.ts

Not to say anything about its applicability for the greater ecosystem but it's been working fairly reliably for us, for what we use it for. It enables us to finally write and wire-up $ref-ignorant components while still handling all the resolving.

[P0lip]

We have bundling now, so gonna close this one.