feat(openapi): improvements to circular ref detection, validation errors (#1189)

## 🧰 Changes

Over the past couple weeks I've been rewriting our OpenAPI parser,
`@readme/openapi-parser`, to support a new error leveling system -- you
can read up on details on this in
readmeio/oas#943. This PR pulls in the fruits of
my labor there and across `oas` and `oas-normalize`.

* [x] Upgrades `oas-normalize` to pull in our new parser engine and
error handling. The error leveling work is not being used within `rdme`
but for things like specification validation that our parser does `rdme`
will now be able to surface more than one of these errors at a time. 🎉
  * Support for Node 18 has also been removed.
* [x] Upgrades `oas` and `@readme/oas-examples` to pull in the removal
of Node 18 support.

All told this overhaul is mostly a drop-in replacement with the
exception that instead of `SyntaxError` and `MissingPointerError`
exceptions being thrown from the parser for some invalid API definition
cases it will now always be a `ValidationError.`

Author: erunion

__tests__/commands/openapi/__snapshots__/inspect.test.ts.snap

@@ -93,8 +93,13 @@ additionalProperties:
  · #/components/schemas/ParameterizedHeader/properties/parameters/additionalProperties
 
 circularRefs:
+ · #/components/schemas/BodyPart/properties/parent
+ · #/components/schemas/MultiPart/properties/bodyParts/items
  · #/components/schemas/MultiPart/properties/parent
- · #/components/schemas/ZoneOffset/properties/rules"
+ · #/components/schemas/ZoneOffset/properties/rules
+ · #/components/schemas/ZoneOffsetTransition/properties/offsetAfter
+ · #/components/schemas/ZoneOffsetTransition/properties/offsetBefore
+ · #/components/schemas/ZoneRules/properties/transitions/items"
 `;
 
 exports[`rdme openapi inspect > feature reports > should generate a report for '@readme/oas-examples/3.0/json/schema-…' (w/ [ 'additionalProperties', …(2) ]) 1`] = `
@@ -114,8 +119,13 @@ additionalProperties:
  · #/components/schemas/ParameterizedHeader/properties/parameters/additionalProperties
 
 circularRefs:
+ · #/components/schemas/BodyPart/properties/parent
+ · #/components/schemas/MultiPart/properties/bodyParts/items
  · #/components/schemas/MultiPart/properties/parent
  · #/components/schemas/ZoneOffset/properties/rules
+ · #/components/schemas/ZoneOffsetTransition/properties/offsetAfter
+ · #/components/schemas/ZoneOffsetTransition/properties/offsetBefore
+ · #/components/schemas/ZoneRules/properties/transitions/items
 
 x-default: You do not use this.
 x-readme.code-samples: You do not use this.
@@ -128,8 +138,13 @@ x-readme.samples-languages: You do not use this."
 exports[`rdme openapi inspect > feature reports > should generate a report for '@readme/oas-examples/3.0/json/schema-…' (w/ [ 'circularRefs', 'readme' ]) 1`] = `
 "
 circularRefs:
+ · #/components/schemas/BodyPart/properties/parent
+ · #/components/schemas/MultiPart/properties/bodyParts/items
  · #/components/schemas/MultiPart/properties/parent
  · #/components/schemas/ZoneOffset/properties/rules
+ · #/components/schemas/ZoneOffsetTransition/properties/offsetAfter
+ · #/components/schemas/ZoneOffsetTransition/properties/offsetBefore
+ · #/components/schemas/ZoneRules/properties/transitions/items
 
 x-default: You do not use this.
 x-readme.code-samples: You do not use this.

__tests__/commands/openapi/__snapshots__/validate.test.ts.snap

@@ -232,7 +232,7 @@ exports[`rdme openapi validate > GHA onboarding E2E tests > should reject if use
 
 exports[`rdme openapi validate > error handling > should throw an error if an invalid API definition has many errors 1`] = `
 {
-  "error": [SyntaxError: OpenAPI schema validation failed.
+  "error": [ValidationError: OpenAPI schema validation failed.
 
 REQUIRED must have required property 'url'
 
@@ -262,7 +262,9 @@ ADDITIONAL PROPERTY must NOT have additional properties
 
 exports[`rdme openapi validate > error handling > should throw an error if an invalid OpenAPI 3.0 definition is supplied 1`] = `
 {
-  "error": [MissingPointerError: Token "Error" does not exist.],
+  "error": [ValidationError: API definition schema validation failed.
+
+Missing $ref pointer "#/components/schemas/Error". Token "Error" does not exist.],
   "stderr": "- Validating the API definition located at ./__tests__/__fixtures__/invalid-oas.json...
 ✖ Validating the API definition located at ./__tests__/__fixtures__/invalid-oas.json...
 ",
@@ -272,7 +274,7 @@ exports[`rdme openapi validate > error handling > should throw an error if an in
 
 exports[`rdme openapi validate > error handling > should throw an error if an invalid OpenAPI 3.1 definition is supplied 1`] = `
 {
-  "error": [SyntaxError: OpenAPI schema validation failed.
+  "error": [ValidationError: OpenAPI schema validation failed.
 
 REQUIRED must have required property 'name'
 
@@ -292,7 +294,7 @@ REQUIRED must have required property 'name'
 
 exports[`rdme openapi validate > error handling > should throw an error if an invalid Swagger definition is supplied 1`] = `
 {
-  "error": [SyntaxError: Swagger schema validation failed.
+  "error": [ValidationError: Swagger schema validation failed.
 
 ADDITIONAL PROPERTY must NOT have additional properties
 

package-lock.json

@@ -47,7 +47,7 @@
     "@oclif/plugin-help": "^6.2.15",
     "@oclif/plugin-not-found": "^3.2.28",
     "@oclif/plugin-warn-if-update-available": "^3.1.19",
-    "@readme/better-ajv-errors": "^2.0.0",
+    "@readme/better-ajv-errors": "^2.3.2",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "chalk": "^5.3.0",
@@ -58,8 +58,8 @@
     "ignore": "^7.0.0",
     "js-yaml": "^4.1.0",
     "mime-types": "^2.1.35",
-    "oas": "^25.3.0",
-    "oas-normalize": "^12.1.0",
+    "oas": "^26.0.1",
+    "oas-normalize": "^13.0.1",
     "ora": "^8.1.1",
     "prompts": "^2.4.2",
     "semver": "^7.5.3",
@@ -77,7 +77,7 @@
     "@commitlint/config-conventional": "^19.0.3",
     "@oclif/test": "^4.1.0",
     "@readme/eslint-config": "^14.3.0",
-    "@readme/oas-examples": "^5.10.0",
+    "@readme/oas-examples": "^5.19.1",
     "@rollup/plugin-commonjs": "^28.0.0",
     "@rollup/plugin-json": "^6.0.0",
     "@rollup/plugin-node-resolve": "^16.0.0",