feat(oas): v30 release (#1053)

## 🐳 Context

Because we are experience some pretty serious performance issues with
large API definitions post-dereferencing we are adding general support
for handling `$ref` pointers into `oas`, without requiring the need for
a full dereference.

> [!IMPORTANT]
> This is a major breaking change to `oas`. Because `oas` has long
assumed that the OpenAPI definition it contained was dereferenced this
is a huge shift in departure so I expect there to be issues, and as such
will be releasing this in v30 RCs until it's stable.

## 📚 Accompanied work

* [x] #1052
* [x] #1051
* [x] #1054
* [x] #1055

## 🧠 Breaking changes

* [x] Enforced TS strict mode everywhere. Some function return types
have changed as a result of this but only to enforce what these methods
were already returning.

#### `oas`

* [x] Improved support for `$ref` pointers on the following accessors:
  * `.getAuth()` 
  * `.getPaths()`
  * `.getWebhooks()`

#### `oas/operation`

* [x] `.dereference()`. This is a new alternative to `Oas.dereference()`
and allows you to dereference a single operation, rather than needing to
dereference the **entire** API definition.
* [x] `.getCallbacks()` now always returns an array. Previously if the
operation had no callbacks it would return `false`, however that
existence check is better suited for `Operation.hasCallbacks()`.

#### `oas/types`

* [x] `isOAS30` has been removed, please use `isOpenAPI30` instead.
* [x] `isOAS31` has been removed, please use `isOpenAPI31` instead.

#### `oas/utils`

* [ ] `findSchemaDefinition` is no longer exported. If you need to
dereference a `$ref` pointer we suggest you either invoke
`Oas.dereference()` to dereference your entire API definition, use the
new `Operation.dereference()` feature in this release for dereferencing
a single API operation, or use a library like
[@apidevtools/json-schema-ref-parser](https://npm.im/@apidevtools/json-schema-ref-parser)
for dereferencing.

## 🧬 QA & Testing

I've written a good amount of new tests for these changes but the real
Q&A will have to be done within our internal repository, and I expect
this work as-is to contain issues so I'll be tagging RC's until it's
fully ready for the general public.

[^1]: Unless explicitly specified otherwise, `$ref` pointers that cannot
be resolved, either because they are invalid or circular, will be
ignored.

---------

Co-authored-by: Darren Yong <contact.darrenyong@gmail.com>
Co-authored-by: Maximilian Falco Widjaya <maximilianfalco@gmail.com>
Co-authored-by: Darren Yong <41130056+darrenyong@users.noreply.github.com>

Author: 3 people

package-lock.json

@@ -421,7 +421,7 @@ export default function oasToHar(
 
   let requestBody: SchemaWrapper | undefined;
   if (operation.hasRequestBody()) {
-    requestBody = operation.getParametersAsJSONSchema().find(payload => {
+    requestBody = operation.getParametersAsJSONSchema()?.find(payload => {
       // `formData` is used in our API Explorer for `application/x-www-form-urlencoded` endpoints
       // and if you have an operation with that, it will only ever have a `formData`. `body` is
       // used for all other payload shapes.

packages/oas-to-har/src/index.ts

@@ -87,6 +87,7 @@
     "watch": "tsc --watch"
   },
   "dependencies": {
+    "@apidevtools/json-schema-ref-parser": "^14.1.1",
     "@readme/openapi-parser": "file:../parser",
     "@types/json-schema": "^7.0.11",
     "json-schema-merge-allof": "^0.8.1",

packages/oas/package.json

@@ -221,37 +221,39 @@ export const SIMPLE_MODE = 'simple-mode';
 export const DISABLE_TAG_SORTING = 'disable-tag-sorting';
 
 export interface Extensions {
-  [CODE_SAMPLES]: {
-    /**
-     * Custom code snippet
-     * @example "curl -X POST https://api.example.com/v2/alert"
-     */
-    code: string;
-    /**
-     * Corresponding response example
-     * @see {@link https://docs.readme.com/main/docs/openapi-extensions#corresponding-response-examples}
-     */
-    correspondingExample?: string;
-    /**
-     * Library installation instructions
-     * @example "brew install httpie"
-     * @example "npm install node-fetch@2 --save"
-     */
-    install?: string;
-    /**
-     * Language for syntax highlighting
-     * @example shell
-     */
-    language: string;
-    /**
-     * Optional title for code sample
-     * @example "Custom cURL snippet"
-     */
-    name?: string;
-  }[];
+  [CODE_SAMPLES]:
+    | {
+        /**
+         * Custom code snippet
+         * @example "curl -X POST https://api.example.com/v2/alert"
+         */
+        code: string;
+        /**
+         * Corresponding response example
+         * @see {@link https://docs.readme.com/main/docs/openapi-extensions#corresponding-response-examples}
+         */
+        correspondingExample?: string;
+        /**
+         * Library installation instructions
+         * @example "brew install httpie"
+         * @example "npm install node-fetch@2 --save"
+         */
+        install?: string;
+        /**
+         * Language for syntax highlighting
+         * @example shell
+         */
+        language: string;
+        /**
+         * Optional title for code sample
+         * @example "Custom cURL snippet"
+         */
+        name?: string;
+      }[]
+    | undefined;
   [DISABLE_TAG_SORTING]: boolean;
   [EXPLORER_ENABLED]: boolean;
-  [HEADERS]: Record<string, number | string>[];
+  [HEADERS]: Record<string, number | string>[] | undefined;
   [INTERNAL]: boolean;
   [METRICS_ENABLED]: boolean;
   [OAUTH_OPTIONS]: {
@@ -377,6 +379,10 @@ export function validateParameterOrdering(
   ordering: (typeof extensionDefaults)[typeof PARAMETER_ORDERING] | undefined,
   extension: string,
 ): void {
+  if (!ordering) {
+    return;
+  }
+
   const defaultValue = extensionDefaults[PARAMETER_ORDERING];
   const requiredLength = defaultValue.length;
   const defaultsHuman = `${defaultValue.slice(0, -1).join(', ')}, and ${defaultValue.slice(-1)}`;