feat(resolver): collect errors in ReferenceElement visitor hook

This change is specific to OpenAPI 3.1.0 resolution
strategy. Errors are now collected, instead of
thrown and visitor traversal is not interrupted.

Refs #2802

src/helpers/apidom/reference/dereference/strategies/openapi-3-1-swagger-client/visitors/dereference.js

@@ -62,132 +62,145 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = OpenApi3_1DereferenceVisitor.c
   },
   methods: {
     async ReferenceElement(referenceElement, key, parent, path, ancestors) {
-      const [ancestorsLineage, directAncestors] = this.toAncestorLineage(ancestors);
+      try {
+        const [ancestorsLineage, directAncestors] = this.toAncestorLineage(ancestors);
 
-      // skip already identified cycled Path Item Objects
-      if (includesClasses(['cycle'], referenceElement.$ref)) {
-        return false;
-      }
+        // skip already identified cycled Path Item Objects
+        if (includesClasses(['cycle'], referenceElement.$ref)) {
+          return false;
+        }
 
-      // detect possible cycle in traversal and avoid it
-      if (ancestorsLineage.some((ancs) => ancs.has(referenceElement))) {
-        // skip processing this schema and all it's child schemas
-        return false;
-      }
+        // detect possible cycle in traversal and avoid it
+        if (ancestorsLineage.some((ancs) => ancs.has(referenceElement))) {
+          // skip processing this schema and all it's child schemas
+          return false;
+        }
 
-      // ignore resolving external Reference Objects
-      if (!this.options.resolve.external && isReferenceElementExternal(referenceElement)) {
-        return false;
-      }
+        // ignore resolving external Reference Objects
+        if (!this.options.resolve.external && isReferenceElementExternal(referenceElement)) {
+          return false;
+        }
 
-      const reference = await this.toReference(referenceElement.$ref.toValue());
-      const retrievalURI = reference.uri;
-      const $refBaseURI = url.resolve(retrievalURI, referenceElement.$ref.toValue());
+        const reference = await this.toReference(referenceElement.$ref.toValue());
+        const retrievalURI = reference.uri;
+        const $refBaseURI = url.resolve(retrievalURI, referenceElement.$ref.toValue());
 
-      this.indirections.push(referenceElement);
+        this.indirections.push(referenceElement);
 
-      const jsonPointer = uriToPointer($refBaseURI);
+        const jsonPointer = uriToPointer($refBaseURI);
 
-      // possibly non-semantic fragment
-      let fragment = jsonPointerEvaluate(jsonPointer, reference.value.result);
+        // possibly non-semantic fragment
+        let fragment = jsonPointerEvaluate(jsonPointer, reference.value.result);
 
-      // applying semantics to a fragment
-      if (isPrimitiveElement(fragment)) {
-        const referencedElementType = referenceElement.meta.get('referenced-element').toValue();
+        // applying semantics to a fragment
+        if (isPrimitiveElement(fragment)) {
+          const referencedElementType = referenceElement.meta.get('referenced-element').toValue();
 
-        if (isReferenceLikeElement(fragment)) {
-          // handling indirect references
-          fragment = ReferenceElement.refract(fragment);
-          fragment.setMetaProperty('referenced-element', referencedElementType);
-        } else {
-          // handling direct references
-          const ElementClass = this.namespace.getElementClass(referencedElementType);
-          fragment = ElementClass.refract(fragment);
+          if (isReferenceLikeElement(fragment)) {
+            // handling indirect references
+            fragment = ReferenceElement.refract(fragment);
+            fragment.setMetaProperty('referenced-element', referencedElementType);
+          } else {
+            // handling direct references
+            const ElementClass = this.namespace.getElementClass(referencedElementType);
+            fragment = ElementClass.refract(fragment);
+          }
         }
-      }
-
-      // detect direct or indirect reference
-      if (this.indirections.includes(fragment)) {
-        throw new Error('Recursive JSON Pointer detected');
-      }
 
-      // detect maximum depth of dereferencing
-      if (this.indirections.length > this.options.dereference.maxDepth) {
-        throw new MaximumDereferenceDepthError(
-          `Maximum dereference depth of "${this.options.dereference.maxDepth}" has been exceeded in file "${this.reference.uri}"`
-        );
-      }
-
-      // append referencing schema to ancestors lineage
-      directAncestors.add(referenceElement);
+        // detect direct or indirect reference
+        if (this.indirections.includes(fragment)) {
+          throw new Error('Recursive JSON Pointer detected');
+        }
 
-      // dive deep into the fragment
-      const visitor = OpenApi3_1SwaggerClientDereferenceVisitor({
-        reference,
-        namespace: this.namespace,
-        indirections: [...this.indirections],
-        options: this.options,
-        ancestors: ancestorsLineage,
-        allowMetaPatches: this.allowMetaPatches,
-        useCircularStructures: this.useCircularStructures,
-        basePath: this.basePath ?? toPath([...ancestors, parent, referenceElement]),
-      });
-      fragment = await visitAsync(fragment, visitor, { keyMap, nodeTypeGetter: getNodeType });
+        // detect maximum depth of dereferencing
+        if (this.indirections.length > this.options.dereference.maxDepth) {
+          throw new MaximumDereferenceDepthError(
+            `Maximum dereference depth of "${this.options.dereference.maxDepth}" has been exceeded in file "${this.reference.uri}"`
+          );
+        }
 
-      // remove referencing schema from ancestors lineage
-      directAncestors.delete(referenceElement);
+        // append referencing schema to ancestors lineage
+        directAncestors.add(referenceElement);
+
+        // dive deep into the fragment
+        const visitor = OpenApi3_1SwaggerClientDereferenceVisitor({
+          reference,
+          namespace: this.namespace,
+          indirections: [...this.indirections],
+          options: this.options,
+          ancestors: ancestorsLineage,
+          allowMetaPatches: this.allowMetaPatches,
+          useCircularStructures: this.useCircularStructures,
+          basePath: this.basePath ?? [...toPath([...ancestors, parent, referenceElement]), '$ref'],
+        });
+        fragment = await visitAsync(fragment, visitor, { keyMap, nodeTypeGetter: getNodeType });
+
+        // remove referencing schema from ancestors lineage
+        directAncestors.delete(referenceElement);
+
+        this.indirections.pop();
+
+        if (!this.useCircularStructures) {
+          const hasCycles = ancestorsLineage.some((ancs) => ancs.has(fragment));
+          if (hasCycles) {
+            if (url.isHttpUrl(retrievalURI) || url.isFileSystemPath(retrievalURI)) {
+              // make the referencing URL or file system path absolute
+              const cycledReferenceElement = new ReferenceElement(
+                { $ref: $refBaseURI },
+                referenceElement.meta.clone(),
+                referenceElement.attributes.clone()
+              );
+              cycledReferenceElement.get('$ref').classes.push('cycle');
+              return cycledReferenceElement;
+            }
+            // skip processing this schema but traverse all it's child schemas
+            return false;
+          }
+        }
 
-      this.indirections.pop();
+        fragment = fragment.clone();
+        fragment.setMetaProperty('ref-fields', {
+          $ref: referenceElement.$ref?.toValue(),
+          description: referenceElement.description?.toValue(),
+          summary: referenceElement.summary?.toValue(),
+        });
+        // annotate fragment with info about origin
+        fragment.setMetaProperty('ref-origin', reference.uri);
+
+        // override description and summary (outer has higher priority then inner)
+        const hasDescription = typeof referenceElement.description !== 'undefined';
+        const hasSummary = typeof referenceElement.summary !== 'undefined';
+        if (hasDescription && 'description' in fragment) {
+          fragment.description = referenceElement.description;
+        }
+        if (hasSummary && 'summary' in fragment) {
+          fragment.summary = referenceElement.summary;
+        }
 
-      if (!this.useCircularStructures) {
-        const hasCycles = ancestorsLineage.some((ancs) => ancs.has(fragment));
-        if (hasCycles) {
-          if (url.isHttpUrl(retrievalURI) || url.isFileSystemPath(retrievalURI)) {
-            // make the referencing URL or file system path absolute
-            const cycledReferenceElement = new ReferenceElement(
-              { $ref: $refBaseURI },
-              referenceElement.meta.clone(),
-              referenceElement.attributes.clone()
-            );
-            cycledReferenceElement.get('$ref').classes.push('cycle');
-            return cycledReferenceElement;
+        // apply meta patches
+        if (this.allowMetaPatches && isObjectElement(fragment)) {
+          const objectFragment = fragment;
+          // apply meta patch only when not already applied
+          if (typeof objectFragment.get('$$ref') === 'undefined') {
+            const baseURI = url.resolve(retrievalURI, $refBaseURI);
+            objectFragment.set('$$ref', baseURI);
           }
-          // skip processing this schema but traverse all it's child schemas
-          return false;
         }
-      }
-
-      fragment = fragment.clone();
-      fragment.setMetaProperty('ref-fields', {
-        $ref: referenceElement.$ref?.toValue(),
-        description: referenceElement.description?.toValue(),
-        summary: referenceElement.summary?.toValue(),
-      });
-      // annotate fragment with info about origin
-      fragment.setMetaProperty('ref-origin', reference.uri);
 
-      // override description and summary (outer has higher priority then inner)
-      const hasDescription = typeof referenceElement.description !== 'undefined';
-      const hasSummary = typeof referenceElement.description !== 'undefined';
-      if (hasDescription && 'description' in fragment) {
-        fragment.description = referenceElement.description;
-      }
-      if (hasSummary && 'summary' in fragment) {
-        fragment.summary = referenceElement.summary;
-      }
+        // transclude the element for a fragment
+        return fragment;
+      } catch (error) {
+        const rootCause = getRootCause(error);
+        const wrappedError = wrapError(rootCause, {
+          baseDoc: this.reference.uri,
+          $ref: referenceElement.$ref.toValue(),
+          pointer: uriToPointer(referenceElement.$ref.toValue()),
+          fullPath: this.basePath ?? [...toPath([...ancestors, parent, referenceElement]), '$ref'],
+        });
+        this.options.dereference.dereferenceOpts?.errors?.push?.(wrappedError);
 
-      // apply meta patches
-      if (this.allowMetaPatches && isObjectElement(fragment)) {
-        const objectFragment = fragment;
-        // apply meta patch only when not already applied
-        if (typeof objectFragment.get('$$ref') === 'undefined') {
-          const baseURI = url.resolve(retrievalURI, $refBaseURI);
-          objectFragment.set('$$ref', baseURI);
-        }
+        return undefined;
       }
-
-      // transclude the element for a fragment
-      return fragment;
     },
 
     async PathItemElement(pathItemElement, key, parent, path, ancestors) {
@@ -530,7 +543,10 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = OpenApi3_1DereferenceVisitor.c
         const wrappedError = wrapError(rootCause, {
           baseDoc: this.reference.uri,
           externalValue: exampleElement.externalValue?.toValue(),
-          fullPath: this.basePath ?? toPath([...ancestors, parent, exampleElement]),
+          fullPath: this.basePath ?? [
+            ...toPath([...ancestors, parent, exampleElement]),
+            'externalValue',
+          ],
         });
         this.options.dereference.dereferenceOpts?.errors?.push?.(wrappedError);
 

test/helpers/apidom/reference/dereference/strategies/openapi-3-1-swagger-client/example-object/index.js

@@ -135,20 +135,14 @@ describe('dereference', () => {
           describe('and with unresolvable URI', () => {
             const fixturePath = path.join(rootFixturePath, 'external-value-unresolvable');
 
-            test.only('should dereference', async () => {
-              try {
-                const rootFilePath = path.join(fixturePath, 'root.json');
-                const actual = await dereference(rootFilePath, {
-                  parse: { mediaType: mediaTypes.latest('json') },
-                });
-                const expected = globalThis.loadJsonFile(
-                  path.join(fixturePath, 'dereferenced.json')
-                );
-
-                expect(toValue(actual)).toEqual(expected);
-              } catch (e) {
-                console.dir(e);
-              }
+            test('should dereference', async () => {
+              const rootFilePath = path.join(fixturePath, 'root.json');
+              const actual = await dereference(rootFilePath, {
+                parse: { mediaType: mediaTypes.latest('json') },
+              });
+              const expected = globalThis.loadJsonFile(path.join(fixturePath, 'dereferenced.json'));
+
+              expect(toValue(actual)).toEqual(expected);
             });
 
             test('should collect error', async () => {
@@ -165,7 +159,7 @@ describe('dereference', () => {
                 message: expect.stringMatching(/^Could not resolve reference: ENOENT/),
                 baseDoc: expect.stringMatching(/external-value-unresolvable\/root\.json$/),
                 externalValue: './ex.json',
-                fullPath: ['components', 'examples', 'example1'],
+                fullPath: ['components', 'examples', 'example1', 'externalValue'],
               });
             });
           });
@@ -212,7 +206,7 @@ describe('dereference', () => {
                 message: expect.stringMatching(/^Could not resolve reference: ExampleElement/),
                 baseDoc: expect.stringMatching(/external-value-value-both-defined\/root\.json$/),
                 externalValue: './ex.json',
-                fullPath: ['components', 'examples', 'example1'],
+                fullPath: ['components', 'examples', 'example1', 'externalValue'],
               });
             });
           });

test/helpers/apidom/reference/dereference/strategies/openapi-3-1-swagger-client/reference-object/__fixtures__/direct-external-circular/dereferenced.json

@@ -0,0 +1,13 @@
+[
+  {
+    "openapi": "3.1.0",
+    "components": {
+      "parameters": {
+        "externalRef": {
+          "$ref": "./root.json#/components/parameters/externalRef",
+          "description": "another ref"
+        }
+      }
+    }
+  }
+]

test/helpers/apidom/reference/dereference/strategies/openapi-3-1-swagger-client/reference-object/__fixtures__/direct-external-circular/ex.json

@@ -1,5 +1,5 @@
 {
   "externalParameter": {
-    "$ref": "./root.json#/components/parameters/userId"
+    "$ref": "./root.json#/components/parameters/externalRef"
   }
 }

test/helpers/apidom/reference/dereference/strategies/openapi-3-1-swagger-client/reference-object/__fixtures__/direct-internal-circular/dereferenced.json

@@ -0,0 +1,13 @@
+[
+  {
+    "openapi": "3.1.0",
+    "components": {
+      "parameters": {
+        "userId": {
+          "$ref": "#/components/parameters/userId",
+          "description": "description 1"
+        }
+      }
+    }
+  }
+]

test/helpers/apidom/reference/dereference/strategies/openapi-3-1-swagger-client/reference-object/__fixtures__/indirect-external-circular/dereferenced.json

@@ -0,0 +1,13 @@
+[
+  {
+    "openapi": "3.1.0",
+    "components": {
+      "parameters": {
+        "externalRef": {
+          "$ref": "./root.json#/components/parameters/externalRef",
+          "description": "another ref"
+        }
+      }
+    }
+  }
+]

test/helpers/apidom/reference/dereference/strategies/openapi-3-1-swagger-client/reference-object/__fixtures__/indirect-internal-circular/dereferenced.json

@@ -0,0 +1,25 @@
+[
+  {
+    "openapi": "3.1.0",
+    "components": {
+      "parameters": {
+        "userId": {
+          "$ref": "#/components/parameters/userId",
+          "description": "description 1"
+        },
+        "indirection1": {
+          "$ref": "#/components/parameters/userId",
+          "description": "description 1"
+        },
+        "indirection2": {
+          "$ref": "#/components/parameters/userId",
+          "description": "description 1"
+        },
+        "indirection3": {
+          "$ref": "#/components/parameters/userId",
+          "description": "description 1"
+        }
+      }
+    }
+  }
+]