swagger-client 3.26.8 → 3.27.1

package/es/resolver/apidom/reference/dereference/strategies/openapi-3-1-swagger-client/visitors/dereference.js

@@ -1,7 +1,7 @@
 /* eslint-disable camelcase */
-import { isObjectElement, isPrimitiveElement, isStringElement, isMemberElement, IdentityManager, visit, includesClasses, toValue, cloneShallow, cloneDeep } from '@swagger-api/apidom-core';
+import { RefElement, isObjectElement, isPrimitiveElement, isStringElement, isMemberElement, IdentityManager, visit, includesClasses, toValue, cloneShallow, cloneDeep } from '@swagger-api/apidom-core';
 import { ApiDOMError } from '@swagger-api/apidom-error';
-import { isReferenceLikeElement, isBooleanJsonSchemaElement, ReferenceElement, PathItemElement, SchemaElement, getNodeType, keyMap } from '@swagger-api/apidom-ns-openapi-3-1';
+import { isReferenceLikeElement, isReferenceElement, isBooleanJsonSchemaElement, isPathItemElement, isSchemaElement, ReferenceElement, PathItemElement, SchemaElement, getNodeType, keyMap } from '@swagger-api/apidom-ns-openapi-3-1';
 import { evaluate as jsonPointerEvaluate, uriToPointer } from '@swagger-api/apidom-json-pointer';
 import { url, MaximumDereferenceDepthError, File } from '@swagger-api/apidom-reference/configuration/empty';
 import { OpenApi3_1DereferenceVisitor, resolveSchema$refField, maybeRefractToSchemaElement } from '@swagger-api/apidom-reference/dereference/strategies/openapi-3-1';
@@ -18,12 +18,6 @@ const visitAsync = visit[Symbol.for('nodejs.util.promisify.custom')];
 
 // initialize element identity manager
 const identityManager = IdentityManager();
-
-/**
- * Predicate for detecting if element was created by merging referencing
- * element with particular element identity with a referenced element.
- */
-const wasReferencedBy = referencingElement => element => element.meta.hasKey('ref-referencing-element-id') && element.meta.get('ref-referencing-element-id').equals(toValue(identityManager.identify(referencingElement)));
 const OpenApi3_1SwaggerClientDereferenceVisitor = OpenApi3_1DereferenceVisitor.compose({
   props: {
     useCircularStructures: true,
@@ -42,18 +36,11 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = OpenApi3_1DereferenceVisitor.c
   methods: {
     async ReferenceElement(referencingElement, key, parent, path, ancestors) {
       try {
-        var _this$basePath;
-        const [ancestorsLineage, directAncestors] = this.toAncestorLineage([...ancestors, parent]);
-
-        // skip already identified cycled Path Item Objects
-        if (includesClasses(['cycle'], referencingElement.$ref)) {
-          return false;
-        }
-
-        // detect possible cycle in traversal and avoid it
-        if (ancestorsLineage.includesCycle(referencingElement)) {
+        // skip current referencing element as it's already been access
+        if (this.indirections.includes(referencingElement)) {
           return false;
         }
+        const [ancestorsLineage, directAncestors] = this.toAncestorLineage([...ancestors, parent]);
         const retrievalURI = this.toBaseURI(toValue(referencingElement.$ref));
         const isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
         const isExternalReference = !isInternalReference;
@@ -73,6 +60,7 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = OpenApi3_1DereferenceVisitor.c
 
         // possibly non-semantic fragment
         let referencedElement = jsonPointerEvaluate(jsonPointer, reference.value.result);
+        referencedElement.id = identityManager.identify(referencedElement);
 
         // applying semantics to a fragment
         if (isPrimitiveElement(referencedElement)) {
@@ -94,105 +82,124 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = OpenApi3_1DereferenceVisitor.c
         }
 
         // detect direct or indirect reference
-        if (this.indirections.includes(referencedElement)) {
-          throw new ApiDOMError('Recursive JSON Pointer detected');
+        if (referencingElement === referencedElement) {
+          throw new ApiDOMError('Recursive Reference Object 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}"`);
         }
-        if (!this.useCircularStructures) {
-          const hasCycles = ancestorsLineage.includes(referencedElement);
-          if (hasCycles) {
-            if (url.isHttpUrl(retrievalURI) || url.isFileSystemPath(retrievalURI)) {
-              // make the referencing URL or file system path absolute
-              const cycledReferenceElement = new ReferenceElement({
-                $ref: $refBaseURI
-              }, cloneDeep(referencingElement.meta), cloneDeep(referencingElement.attributes));
-              cycledReferenceElement.get('$ref').classes.push('cycle');
-              return cycledReferenceElement;
+
+        // detect second deep dive into the same fragment and avoid it
+        if (ancestorsLineage.includes(referencedElement)) {
+          reference.refSet.circular = true;
+          if (this.options.dereference.circular === 'error') {
+            throw new ApiDOMError('Circular reference detected');
+          } else if (this.options.dereference.circular === 'replace') {
+            var _this$options$derefer, _this$options$derefer2;
+            const refElement = new RefElement(referencedElement.id, {
+              type: 'reference',
+              uri: reference.uri,
+              $ref: toValue(referencingElement.$ref),
+              baseURI: $refBaseURI,
+              referencingElement
+            });
+            const replacer = (_this$options$derefer = (_this$options$derefer2 = this.options.dereference.strategyOpts['openapi-3-1']) === null || _this$options$derefer2 === void 0 ? void 0 : _this$options$derefer2.circularReplacer) !== null && _this$options$derefer !== void 0 ? _this$options$derefer : this.options.dereference.circularReplacer;
+            const replacement = replacer(refElement);
+            if (isMemberElement(parent)) {
+              parent.value = replacement; // eslint-disable-line no-param-reassign
+            } else if (Array.isArray(parent)) {
+              parent[key] = replacement; // eslint-disable-line no-param-reassign
             }
-            // skip processing this reference
-            return false;
+            return !parent ? replacement : false;
           }
         }
 
-        // append referencing schema to ancestors lineage
-        directAncestors.add(referencingElement);
-
-        // 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 = this.basePath) !== null && _this$basePath !== void 0 ? _this$basePath : [...toPath([...ancestors, parent, referencingElement]), '$ref']
-        });
-        referencedElement = await visitAsync(referencedElement, visitor, {
-          keyMap,
-          nodeTypeGetter: getNodeType
-        });
+        /**
+         * Dive deep into the fragment.
+         *
+         * Cases to consider:
+         *  1. We're crossing document boundary
+         *  2. Fragment is from non-root document
+         *  3. Fragment is a Reference Object. We need to follow it to get the eventual value
+         *  4. We are dereferencing the fragment lazily/eagerly depending on circular mode
+         */
+        const isNonRootDocument = url.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
+        const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
+        if ((isExternalReference || isNonRootDocument || isReferenceElement(referencedElement) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+          var _this$basePath;
+          // append referencing reference to ancestors lineage
+          directAncestors.add(referencingElement);
+          const visitor = OpenApi3_1SwaggerClientDereferenceVisitor({
+            reference,
+            namespace: this.namespace,
+            indirections: [...this.indirections],
+            options: this.options,
+            refractCache: this.refractCache,
+            ancestors: ancestorsLineage,
+            allowMetaPatches: this.allowMetaPatches,
+            useCircularStructures: this.useCircularStructures,
+            basePath: (_this$basePath = this.basePath) !== null && _this$basePath !== void 0 ? _this$basePath : [...toPath([...ancestors, parent, referencingElement]), '$ref']
+          });
+          referencedElement = await visitAsync(referencedElement, visitor, {
+            keyMap,
+            nodeTypeGetter: getNodeType
+          });
 
-        // remove referencing schema from ancestors lineage
-        directAncestors.delete(referencingElement);
+          // remove referencing reference from ancestors lineage
+          directAncestors.delete(referencingElement);
+        }
         this.indirections.pop();
-        const mergeAndAnnotateReferencedElement = refedElement => {
-          const copy = cloneShallow(refedElement);
-
-          // annotate fragment with info about original Reference element
-          copy.setMetaProperty('ref-fields', {
-            $ref: toValue(referencingElement.$ref),
-            description: toValue(referencingElement.description),
-            summary: toValue(referencingElement.summary)
-          });
-          // annotate fragment with info about origin
-          copy.setMetaProperty('ref-origin', reference.uri);
-          // annotate fragment with info about referencing element
-          copy.setMetaProperty('ref-referencing-element-id', cloneDeep(identityManager.identify(referencingElement)));
+        const mergedElement = cloneShallow(referencedElement);
 
-          // override description and summary (outer has higher priority then inner)
-          if (isObjectElement(refedElement)) {
-            if (referencingElement.hasKey('description') && 'description' in refedElement) {
-              copy.remove('description');
-              copy.set('description', referencingElement.get('description'));
-            }
-            if (referencingElement.hasKey('summary') && 'summary' in refedElement) {
-              copy.remove('summary');
-              copy.set('summary', referencingElement.get('summary'));
-            }
+        // annotate fragment with info about original Reference element
+        mergedElement.setMetaProperty('ref-fields', {
+          $ref: toValue(referencingElement.$ref),
+          description: toValue(referencingElement.description),
+          summary: toValue(referencingElement.summary)
+        });
+        // annotate fragment with info about origin
+        mergedElement.setMetaProperty('ref-origin', reference.uri);
+        // annotate fragment with info about referencing element
+        mergedElement.setMetaProperty('ref-referencing-element-id', cloneDeep(identityManager.identify(referencingElement)));
+
+        // override description and summary (outer has higher priority then inner)
+        if (isObjectElement(referencedElement)) {
+          if (referencingElement.hasKey('description') && 'description' in referencedElement) {
+            mergedElement.remove('description');
+            mergedElement.set('description', referencingElement.get('description'));
           }
-
-          // apply meta patches
-          if (this.allowMetaPatches && isObjectElement(copy)) {
-            // apply meta patch only when not already applied
-            if (!copy.hasKey('$$ref')) {
-              const baseURI = url.resolve(retrievalURI, $refBaseURI);
-              copy.set('$$ref', baseURI);
-            }
+          if (referencingElement.hasKey('summary') && 'summary' in referencedElement) {
+            mergedElement.remove('summary');
+            mergedElement.set('summary', referencingElement.get('summary'));
           }
-          return copy;
-        };
+        }
 
-        // attempting to create cycle
-        if (ancestorsLineage.includes(referencingElement) || ancestorsLineage.includes(referencedElement)) {
-          var _ancestorsLineage$fin;
-          const replaceWith = (_ancestorsLineage$fin = ancestorsLineage.findItem(wasReferencedBy(referencingElement))) !== null && _ancestorsLineage$fin !== void 0 ? _ancestorsLineage$fin : mergeAndAnnotateReferencedElement(referencedElement);
-          if (isMemberElement(parent)) {
-            parent.value = replaceWith; // eslint-disable-line no-param-reassign
-          } else if (Array.isArray(parent)) {
-            parent[key] = replaceWith; // eslint-disable-line no-param-reassign
+        // apply meta patches
+        if (this.allowMetaPatches && isObjectElement(mergedElement)) {
+          // apply meta patch only when not already applied
+          if (!mergedElement.hasKey('$$ref')) {
+            const baseURI = url.resolve(retrievalURI, $refBaseURI);
+            mergedElement.set('$$ref', baseURI);
           }
-          return false;
         }
 
-        // transclude the element for a fragment
-        return mergeAndAnnotateReferencedElement(referencedElement);
+        /**
+         * Transclude referencing element with merged referenced element.
+         */
+        if (isMemberElement(parent)) {
+          parent.value = mergedElement; // eslint-disable-line no-param-reassign
+        } else if (Array.isArray(parent)) {
+          parent[key] = mergedElement; // eslint-disable-line no-param-reassign
+        }
+
+        /**
+         * We're at the root of the tree, so we're just replacing the entire tree.
+         */
+        return !parent ? mergedElement : false;
       } catch (error) {
-        var _this$basePath2, _this$options$derefer, _this$options$derefer2;
+        var _this$basePath2, _this$options$derefer3, _this$options$derefer4;
         const rootCause = getRootCause(error);
         const wrappedError = wrapError(rootCause, {
           baseDoc: this.reference.uri,
@@ -200,29 +207,27 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = OpenApi3_1DereferenceVisitor.c
           pointer: uriToPointer(toValue(referencingElement.$ref)),
           fullPath: (_this$basePath2 = this.basePath) !== null && _this$basePath2 !== void 0 ? _this$basePath2 : [...toPath([...ancestors, parent, referencingElement]), '$ref']
         });
-        (_this$options$derefer = this.options.dereference.dereferenceOpts) === null || _this$options$derefer === void 0 || (_this$options$derefer = _this$options$derefer.errors) === null || _this$options$derefer === void 0 || (_this$options$derefer2 = _this$options$derefer.push) === null || _this$options$derefer2 === void 0 || _this$options$derefer2.call(_this$options$derefer, wrappedError);
+        (_this$options$derefer3 = this.options.dereference.dereferenceOpts) === null || _this$options$derefer3 === void 0 || (_this$options$derefer3 = _this$options$derefer3.errors) === null || _this$options$derefer3 === void 0 || (_this$options$derefer4 = _this$options$derefer3.push) === null || _this$options$derefer4 === void 0 || _this$options$derefer4.call(_this$options$derefer3, wrappedError);
         return undefined;
       }
     },
     async PathItemElement(pathItemElement, key, parent, path, ancestors) {
       try {
-        var _this$basePath3;
-        const [ancestorsLineage, directAncestors] = this.toAncestorLineage([...ancestors, parent]);
-
         // ignore PathItemElement without $ref field
         if (!isStringElement(pathItemElement.$ref)) {
           return undefined;
         }
 
-        // skip already identified cycled Path Item Objects
-        if (includesClasses(['cycle'], pathItemElement.$ref)) {
+        // skip current referencing element as it's already been access
+        if (this.indirections.includes(pathItemElement)) {
           return false;
         }
 
-        // detect possible cycle in traversal and avoid it
-        if (ancestorsLineage.includesCycle(pathItemElement)) {
+        // skip already identified cycled Path Item Objects
+        if (includesClasses(['cycle'], pathItemElement.$ref)) {
           return false;
         }
+        const [ancestorsLineage, directAncestors] = this.toAncestorLineage([...ancestors, parent]);
         const retrievalURI = this.toBaseURI(toValue(pathItemElement.$ref));
         const isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
         const isExternalReference = !isInternalReference;
@@ -242,10 +247,11 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = OpenApi3_1DereferenceVisitor.c
 
         // possibly non-semantic referenced element
         let referencedElement = jsonPointerEvaluate(jsonPointer, reference.value.result);
+        referencedElement.id = identityManager.identify(referencedElement);
 
         // applying semantics to a referenced element
         if (isPrimitiveElement(referencedElement)) {
-          const cacheKey = `pathItem-${toValue(identityManager.identify(referencedElement))}`;
+          const cacheKey = `path-item-${toValue(identityManager.identify(referencedElement))}`;
           if (this.refractCache.has(cacheKey)) {
             referencedElement = this.refractCache.get(cacheKey);
           } else {
@@ -255,55 +261,82 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = OpenApi3_1DereferenceVisitor.c
         }
 
         // detect direct or indirect reference
-        if (this.indirections.includes(referencedElement)) {
-          throw new ApiDOMError('Recursive JSON Pointer detected');
+        if (pathItemElement === referencedElement) {
+          throw new ApiDOMError('Recursive Path Item Object reference 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}"`);
         }
-        if (!this.useCircularStructures) {
-          const hasCycles = ancestorsLineage.includes(referencedElement);
-          if (hasCycles) {
-            if (url.isHttpUrl(retrievalURI) || url.isFileSystemPath(retrievalURI)) {
-              // make the referencing URL or file system path absolute
-              const cycledPathItemElement = new PathItemElement({
-                $ref: $refBaseURI
-              }, cloneDeep(pathItemElement.meta), cloneDeep(pathItemElement.attributes));
-              cycledPathItemElement.get('$ref').classes.push('cycle');
-              return cycledPathItemElement;
+
+        // detect second deep dive into the same fragment and avoid it
+        if (ancestorsLineage.includes(referencedElement)) {
+          reference.refSet.circular = true;
+          if (this.options.dereference.circular === 'error') {
+            throw new ApiDOMError('Circular reference detected');
+          } else if (this.options.dereference.circular === 'replace') {
+            var _this$options$derefer5, _this$options$derefer6;
+            const refElement = new RefElement(referencedElement.id, {
+              type: 'path-item',
+              uri: reference.uri,
+              $ref: toValue(pathItemElement.$ref),
+              baseURI: $refBaseURI,
+              referencingElement: pathItemElement
+            });
+            const replacer = (_this$options$derefer5 = (_this$options$derefer6 = this.options.dereference.strategyOpts['openapi-3-1']) === null || _this$options$derefer6 === void 0 ? void 0 : _this$options$derefer6.circularReplacer) !== null && _this$options$derefer5 !== void 0 ? _this$options$derefer5 : this.options.dereference.circularReplacer;
+            const replacement = replacer(refElement);
+            if (isMemberElement(parent)) {
+              parent.value = replacement; // eslint-disable-line no-param-reassign
+            } else if (Array.isArray(parent)) {
+              parent[key] = replacement; // eslint-disable-line no-param-reassign
             }
-            // skip processing this path item and all it's child elements
-            return false;
+            return !parent ? replacement : false;
           }
         }
 
-        // append referencing schema to ancestors lineage
-        directAncestors.add(pathItemElement);
-
-        // dive deep into the referenced element
-        const visitor = OpenApi3_1SwaggerClientDereferenceVisitor({
-          reference,
-          namespace: this.namespace,
-          indirections: [...this.indirections],
-          options: this.options,
-          ancestors: ancestorsLineage,
-          allowMetaPatches: this.allowMetaPatches,
-          useCircularStructures: this.useCircularStructures,
-          basePath: (_this$basePath3 = this.basePath) !== null && _this$basePath3 !== void 0 ? _this$basePath3 : [...toPath([...ancestors, parent, pathItemElement]), '$ref']
-        });
-        referencedElement = await visitAsync(referencedElement, visitor, {
-          keyMap,
-          nodeTypeGetter: getNodeType
-        });
+        /**
+         * Dive deep into the fragment.
+         *
+         * Cases to consider:
+         *  1. We're crossing document boundary
+         *  2. Fragment is from non-root document
+         *  3. Fragment is a Path Item Object with $ref field. We need to follow it to get the eventual value
+         *  4. We are dereferencing the fragment lazily/eagerly depending on circular mode
+         */
+        const isNonRootDocument = url.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
+        const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
+        if ((isExternalReference || isNonRootDocument || isPathItemElement(referencedElement) && isStringElement(referencedElement.$ref) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+          var _this$basePath3;
+          // append referencing schema to ancestors lineage
+          directAncestors.add(pathItemElement);
+
+          // dive deep into the referenced element
+          const visitor = OpenApi3_1SwaggerClientDereferenceVisitor({
+            reference,
+            namespace: this.namespace,
+            indirections: [...this.indirections],
+            options: this.options,
+            ancestors: ancestorsLineage,
+            allowMetaPatches: this.allowMetaPatches,
+            useCircularStructures: this.useCircularStructures,
+            basePath: (_this$basePath3 = this.basePath) !== null && _this$basePath3 !== void 0 ? _this$basePath3 : [...toPath([...ancestors, parent, pathItemElement]), '$ref']
+          });
+          referencedElement = await visitAsync(referencedElement, visitor, {
+            keyMap,
+            nodeTypeGetter: getNodeType
+          });
 
-        // remove referencing schema from ancestors lineage
-        directAncestors.delete(pathItemElement);
+          // remove referencing schema from ancestors lineage
+          directAncestors.delete(pathItemElement);
+        }
         this.indirections.pop();
-        const mergeAndAnnotateReferencedElement = refedElement => {
-          // merge fields from referenced Path Item with referencing one
-          const mergedElement = new PathItemElement([...refedElement.content], cloneDeep(refedElement.meta), cloneDeep(refedElement.attributes));
+
+        /**
+         * Creating a new version of Path Item by merging fields from referenced Path Item with referencing one.
+         */
+        if (isPathItemElement(referencedElement)) {
+          const mergedElement = new PathItemElement([...referencedElement.content], cloneDeep(referencedElement.meta), cloneDeep(referencedElement.attributes));
           // existing keywords from referencing PathItemElement overrides ones from referenced element
           pathItemElement.forEach((value, keyElement, item) => {
             mergedElement.remove(toValue(keyElement));
@@ -328,25 +361,24 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = OpenApi3_1DereferenceVisitor.c
               mergedElement.set('$$ref', baseURI);
             }
           }
-          return mergedElement;
-        };
+          referencedElement = mergedElement;
+        }
 
-        // attempting to create cycle
-        if (ancestorsLineage.includes(pathItemElement) || ancestorsLineage.includes(referencedElement)) {
-          var _ancestorsLineage$fin2;
-          const replaceWith = (_ancestorsLineage$fin2 = ancestorsLineage.findItem(wasReferencedBy(pathItemElement))) !== null && _ancestorsLineage$fin2 !== void 0 ? _ancestorsLineage$fin2 : mergeAndAnnotateReferencedElement(referencedElement);
-          if (isMemberElement(parent)) {
-            parent.value = replaceWith; // eslint-disable-line no-param-reassign
-          } else if (Array.isArray(parent)) {
-            parent[key] = replaceWith; // eslint-disable-line no-param-reassign
-          }
-          return false;
+        /**
+         * Transclude referencing element with merged referenced element.
+         */
+        if (isMemberElement(parent)) {
+          parent.value = referencedElement; // eslint-disable-line no-param-reassign
+        } else if (Array.isArray(parent)) {
+          parent[key] = referencedElement; // eslint-disable-line no-param-reassign
         }
 
-        // transclude referencing element with merged referenced element
-        return mergeAndAnnotateReferencedElement(referencedElement);
+        /**
+         * We're at the root of the tree, so we're just replacing the entire tree.
+         */
+        return !parent ? referencedElement : undefined;
       } catch (error) {
-        var _this$basePath4, _this$options$derefer3, _this$options$derefer4;
+        var _this$basePath4, _this$options$derefer7, _this$options$derefer8;
         const rootCause = getRootCause(error);
         const wrappedError = wrapError(rootCause, {
           baseDoc: this.reference.uri,
@@ -354,30 +386,23 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = OpenApi3_1DereferenceVisitor.c
           pointer: uriToPointer(toValue(pathItemElement.$ref)),
           fullPath: (_this$basePath4 = this.basePath) !== null && _this$basePath4 !== void 0 ? _this$basePath4 : [...toPath([...ancestors, parent, pathItemElement]), '$ref']
         });
-        (_this$options$derefer3 = this.options.dereference.dereferenceOpts) === null || _this$options$derefer3 === void 0 || (_this$options$derefer3 = _this$options$derefer3.errors) === null || _this$options$derefer3 === void 0 || (_this$options$derefer4 = _this$options$derefer3.push) === null || _this$options$derefer4 === void 0 || _this$options$derefer4.call(_this$options$derefer3, wrappedError);
+        (_this$options$derefer7 = this.options.dereference.dereferenceOpts) === null || _this$options$derefer7 === void 0 || (_this$options$derefer7 = _this$options$derefer7.errors) === null || _this$options$derefer7 === void 0 || (_this$options$derefer8 = _this$options$derefer7.push) === null || _this$options$derefer8 === void 0 || _this$options$derefer8.call(_this$options$derefer7, wrappedError);
         return undefined;
       }
     },
     async SchemaElement(referencingElement, key, parent, path, ancestors) {
       try {
-        var _this$basePath5;
-        const [ancestorsLineage, directAncestors] = this.toAncestorLineage([...ancestors, parent]);
-
         // skip current referencing schema as $ref keyword was not defined
         if (!isStringElement(referencingElement.$ref)) {
           // skip traversing this schema but traverse all it's child schemas
           return undefined;
         }
 
-        // skip already identified cycled Path Item Objects
-        if (includesClasses(['cycle'], referencingElement.$ref)) {
-          return false;
-        }
-
-        // detect possible cycle in traversal and avoid it
-        if (ancestorsLineage.includesCycle(referencingElement)) {
+        // skip current referencing element as it's already been access
+        if (this.indirections.includes(referencingElement)) {
           return false;
         }
+        const [ancestorsLineage, directAncestors] = this.toAncestorLineage([...ancestors, parent]);
 
         // compute baseURI using rules around $id and $ref keywords
         let reference = await this.toReference(url.unsanitize(this.reference.uri));
@@ -391,8 +416,8 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = OpenApi3_1DereferenceVisitor.c
         });
         const isUnknownURI = !this.options.resolve.resolvers.some(r => r.canRead(file));
         const isURL = !isUnknownURI;
-        const isInternalReference = uri => url.stripHash(this.reference.uri) === uri;
-        const isExternalReference = uri => !isInternalReference(uri);
+        let isInternalReference = url.stripHash(this.reference.uri) === $refBaseURI;
+        let isExternalReference = !isInternalReference;
         this.indirections.push(referencingElement);
 
         // determining reference, proper evaluation and selection mechanism
@@ -400,25 +425,45 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = OpenApi3_1DereferenceVisitor.c
         try {
           if (isUnknownURI || isURL) {
             // we're dealing with canonical URI or URL with possible fragment
+            retrievalURI = this.toBaseURI($refBaseURI);
             const selector = $refBaseURI;
-            referencedElement = uriEvaluate(selector, maybeRefractToSchemaElement(reference.value.result));
+            const referenceAsSchema = maybeRefractToSchemaElement(reference.value.result);
+            referencedElement = uriEvaluate(selector, referenceAsSchema);
+            referencedElement = maybeRefractToSchemaElement(referencedElement);
+            referencedElement.id = identityManager.identify(referencedElement);
+
+            // ignore resolving internal Schema Objects
+            if (!this.options.resolve.internal && isInternalReference) {
+              // skip traversing this schema element but traverse all it's child elements
+              return undefined;
+            }
+            // ignore resolving external Schema Objects
+            if (!this.options.resolve.external && isExternalReference) {
+              // skip traversing this schema element but traverse all it's child elements
+              return undefined;
+            }
           } else {
             // we're assuming here that we're dealing with JSON Pointer here
-            retrievalURI = this.toBaseURI(toValue($refBaseURI));
+            retrievalURI = this.toBaseURI($refBaseURI);
+            isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
+            isExternalReference = !isInternalReference;
 
             // ignore resolving internal Schema Objects
-            if (!this.options.resolve.internal && isInternalReference(retrievalURI)) {
+            if (!this.options.resolve.internal && isInternalReference) {
               // skip traversing this schema element but traverse all it's child elements
               return undefined;
             }
             // ignore resolving external Schema Objects
-            if (!this.options.resolve.external && isExternalReference(retrievalURI)) {
+            if (!this.options.resolve.external && isExternalReference) {
               // skip traversing this schema element but traverse all it's child elements
               return undefined;
             }
             reference = await this.toReference(url.unsanitize($refBaseURI));
             const selector = uriToPointer($refBaseURI);
-            referencedElement = maybeRefractToSchemaElement(jsonPointerEvaluate(selector, reference.value.result));
+            const referenceAsSchema = maybeRefractToSchemaElement(reference.value.result);
+            referencedElement = jsonPointerEvaluate(selector, referenceAsSchema);
+            referencedElement = maybeRefractToSchemaElement(referencedElement);
+            referencedElement.id = identityManager.identify(referencedElement);
           }
         } catch (error) {
           /**
@@ -428,38 +473,47 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = OpenApi3_1DereferenceVisitor.c
           if (isURL && error instanceof EvaluationJsonSchemaUriError) {
             if (isAnchor(uriToAnchor($refBaseURI))) {
               // we're dealing with JSON Schema $anchor here
-              retrievalURI = this.toBaseURI(toValue($refBaseURI));
+              isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
+              isExternalReference = !isInternalReference;
 
               // ignore resolving internal Schema Objects
-              if (!this.options.resolve.internal && isInternalReference(retrievalURI)) {
+              if (!this.options.resolve.internal && isInternalReference) {
                 // skip traversing this schema element but traverse all it's child elements
                 return undefined;
               }
               // ignore resolving external Schema Objects
-              if (!this.options.resolve.external && isExternalReference(retrievalURI)) {
+              if (!this.options.resolve.external && isExternalReference) {
                 // skip traversing this schema element but traverse all it's child elements
                 return undefined;
               }
               reference = await this.toReference(url.unsanitize($refBaseURI));
               const selector = uriToAnchor($refBaseURI);
-              referencedElement = $anchorEvaluate(selector, maybeRefractToSchemaElement(reference.value.result));
+              const referenceAsSchema = maybeRefractToSchemaElement(reference.value.result);
+              referencedElement = $anchorEvaluate(selector, referenceAsSchema);
+              referencedElement = maybeRefractToSchemaElement(referencedElement);
+              referencedElement.id = identityManager.identify(referencedElement);
             } else {
               // we're assuming here that we're dealing with JSON Pointer here
               retrievalURI = this.toBaseURI(toValue($refBaseURI));
+              isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
+              isExternalReference = !isInternalReference;
 
               // ignore resolving internal Schema Objects
-              if (!this.options.resolve.internal && isInternalReference(retrievalURI)) {
+              if (!this.options.resolve.internal && isInternalReference) {
                 // skip traversing this schema element but traverse all it's child elements
                 return undefined;
               }
               // ignore resolving external Schema Objects
-              if (!this.options.resolve.external && isExternalReference(retrievalURI)) {
+              if (!this.options.resolve.external && isExternalReference) {
                 // skip traversing this schema element but traverse all it's child elements
                 return undefined;
               }
               reference = await this.toReference(url.unsanitize($refBaseURI));
               const selector = uriToPointer($refBaseURI);
-              referencedElement = maybeRefractToSchemaElement(jsonPointerEvaluate(selector, reference.value.result));
+              const referenceAsSchema = maybeRefractToSchemaElement(reference.value.result);
+              referencedElement = jsonPointerEvaluate(selector, referenceAsSchema);
+              referencedElement = maybeRefractToSchemaElement(referencedElement);
+              referencedElement.id = identityManager.identify(referencedElement);
             }
           } else {
             throw error;
@@ -467,7 +521,7 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = OpenApi3_1DereferenceVisitor.c
         }
 
         // detect direct or indirect reference
-        if (this.indirections.includes(referencedElement)) {
+        if (referencingElement === referencedElement) {
           throw new ApiDOMError('Recursive Schema Object reference detected');
         }
 
@@ -476,45 +530,66 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = OpenApi3_1DereferenceVisitor.c
           throw new MaximumDereferenceDepthError(`Maximum dereference depth of "${this.options.dereference.maxDepth}" has been exceeded in file "${this.reference.uri}"`);
         }
 
-        // useCircularStructures option processing
-        if (!this.useCircularStructures) {
-          const hasCycles = ancestorsLineage.includes(referencedElement);
-          if (hasCycles) {
-            if (url.isHttpUrl(retrievalURI) || url.isFileSystemPath(retrievalURI)) {
-              // make the referencing URL or file system path absolute
-              const baseURI = url.resolve(retrievalURI, $refBaseURI);
-              const cycledSchemaElement = new SchemaElement({
-                $ref: baseURI
-              }, cloneDeep(referencingElement.meta), cloneDeep(referencingElement.attributes));
-              cycledSchemaElement.get('$ref').classes.push('cycle');
-              return cycledSchemaElement;
+        // detect second deep dive into the same fragment and avoid it
+        if (ancestorsLineage.includes(referencedElement)) {
+          reference.refSet.circular = true;
+          if (this.options.dereference.circular === 'error') {
+            throw new ApiDOMError('Circular reference detected');
+          } else if (this.options.dereference.circular === 'replace') {
+            var _this$options$derefer9, _this$options$derefer10;
+            const refElement = new RefElement(referencedElement.id, {
+              type: 'json-schema',
+              uri: reference.uri,
+              $ref: toValue(referencingElement.$ref),
+              baseURI: url.resolve(retrievalURI, $refBaseURI),
+              referencingElement
+            });
+            const replacer = (_this$options$derefer9 = (_this$options$derefer10 = this.options.dereference.strategyOpts['openapi-3-1']) === null || _this$options$derefer10 === void 0 ? void 0 : _this$options$derefer10.circularReplacer) !== null && _this$options$derefer9 !== void 0 ? _this$options$derefer9 : this.options.dereference.circularReplacer;
+            const replacement = replacer(refElement);
+            if (isMemberElement(parent)) {
+              parent.value = replacement; // eslint-disable-line no-param-reassign
+            } else if (Array.isArray(parent)) {
+              parent[key] = replacement; // eslint-disable-line no-param-reassign
             }
-            // skip processing this schema and all it's child schemas
-            return false;
+            return !parent ? replacement : false;
           }
         }
 
-        // append referencing schema to ancestors lineage
-        directAncestors.add(referencingElement);
-
-        // dive deep into the fragment
-        const mergeVisitor = OpenApi3_1SwaggerClientDereferenceVisitor({
-          reference,
-          namespace: this.namespace,
-          indirections: [...this.indirections],
-          options: this.options,
-          useCircularStructures: this.useCircularStructures,
-          allowMetaPatches: this.allowMetaPatches,
-          ancestors: ancestorsLineage,
-          basePath: (_this$basePath5 = this.basePath) !== null && _this$basePath5 !== void 0 ? _this$basePath5 : [...toPath([...ancestors, parent, referencingElement]), '$ref']
-        });
-        referencedElement = await visitAsync(referencedElement, mergeVisitor, {
-          keyMap,
-          nodeTypeGetter: getNodeType
-        });
+        /**
+         * Dive deep into the fragment.
+         *
+         * Cases to consider:
+         *  1. We're crossing document boundary
+         *  2. Fragment is from non-root document
+         *  3. Fragment is a Schema Object with $ref field. We need to follow it to get the eventual value
+         *  4. We are dereferencing the fragment lazily/eagerly depending on circular mode
+         */
+        const isNonRootDocument = url.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
+        const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
+        if ((isExternalReference || isNonRootDocument || isSchemaElement(referencedElement) && isStringElement(referencedElement.$ref) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+          var _this$basePath5;
+          // append referencing schema to ancestors lineage
+          directAncestors.add(referencingElement);
+
+          // dive deep into the fragment
+          const mergeVisitor = OpenApi3_1SwaggerClientDereferenceVisitor({
+            reference,
+            namespace: this.namespace,
+            indirections: [...this.indirections],
+            options: this.options,
+            useCircularStructures: this.useCircularStructures,
+            allowMetaPatches: this.allowMetaPatches,
+            ancestors: ancestorsLineage,
+            basePath: (_this$basePath5 = this.basePath) !== null && _this$basePath5 !== void 0 ? _this$basePath5 : [...toPath([...ancestors, parent, referencingElement]), '$ref']
+          });
+          referencedElement = await visitAsync(referencedElement, mergeVisitor, {
+            keyMap,
+            nodeTypeGetter: getNodeType
+          });
 
-        // remove referencing schema from ancestors lineage
-        directAncestors.delete(referencingElement);
+          // remove referencing schema from ancestors lineage
+          directAncestors.delete(referencingElement);
+        }
         this.indirections.pop();
         if (isBooleanJsonSchemaElement(referencedElement)) {
           const booleanJsonSchemaElement = cloneDeep(referencedElement);
@@ -526,11 +601,20 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = OpenApi3_1DereferenceVisitor.c
           booleanJsonSchemaElement.setMetaProperty('ref-origin', reference.uri);
           // annotate fragment with info about referencing element
           booleanJsonSchemaElement.setMetaProperty('ref-referencing-element-id', cloneDeep(identityManager.identify(referencingElement)));
-          return booleanJsonSchemaElement;
+          if (isMemberElement(parent)) {
+            parent.value = booleanJsonSchemaElement; // eslint-disable-line no-param-reassign
+          } else if (Array.isArray(parent)) {
+            parent[key] = booleanJsonSchemaElement; // eslint-disable-line no-param-reassign
+          }
+          return !parent ? booleanJsonSchemaElement : false;
         }
-        const mergeAndAnnotateReferencedElement = refedElement => {
+
+        /**
+         * Creating a new version of Schema Object by merging fields from referenced Schema Object with referencing one.
+         */
+        if (isSchemaElement(referencedElement)) {
           // Schema Object - merge keywords from referenced schema with referencing schema
-          const mergedElement = new SchemaElement([...refedElement.content], cloneDeep(refedElement.meta), cloneDeep(refedElement.attributes));
+          const mergedElement = new SchemaElement([...referencedElement.content], cloneDeep(referencedElement.meta), cloneDeep(referencedElement.attributes));
           // existing keywords from referencing schema overrides ones from referenced schema
           referencingElement.forEach((value, keyElement, item) => {
             mergedElement.remove(toValue(keyElement));
@@ -554,32 +638,31 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = OpenApi3_1DereferenceVisitor.c
               mergedElement.set('$$ref', baseURI);
             }
           }
-          return mergedElement;
-        };
+          referencedElement = mergedElement;
+        }
 
-        // attempting to create cycle
-        if (ancestorsLineage.includes(referencingElement) || ancestorsLineage.includes(referencedElement)) {
-          var _ancestorsLineage$fin3;
-          const replaceWith = (_ancestorsLineage$fin3 = ancestorsLineage.findItem(wasReferencedBy(referencingElement))) !== null && _ancestorsLineage$fin3 !== void 0 ? _ancestorsLineage$fin3 : mergeAndAnnotateReferencedElement(referencedElement);
-          if (isMemberElement(parent)) {
-            parent.value = replaceWith; // eslint-disable-line no-param-reassign
-          } else if (Array.isArray(parent)) {
-            parent[key] = replaceWith; // eslint-disable-line no-param-reassign
-          }
-          return false;
+        /**
+         * Transclude referencing element with merged referenced element.
+         */
+        if (isMemberElement(parent)) {
+          parent.value = referencedElement; // eslint-disable-line no-param-reassign
+        } else if (Array.isArray(parent)) {
+          parent[key] = referencedElement; // eslint-disable-line no-param-reassign
         }
 
-        // transclude referencing element with merged referenced element
-        return mergeAndAnnotateReferencedElement(referencedElement);
+        /**
+         * We're at the root of the tree, so we're just replacing the entire tree.
+         */
+        return !parent ? referencedElement : undefined;
       } catch (error) {
-        var _this$basePath6, _this$options$derefer5, _this$options$derefer6;
+        var _this$basePath6, _this$options$derefer11, _this$options$derefer12;
         const rootCause = getRootCause(error);
         const wrappedError = new SchemaRefError(`Could not resolve reference: ${rootCause.message}`, {
           baseDoc: this.reference.uri,
           $ref: toValue(referencingElement.$ref),
           fullPath: (_this$basePath6 = this.basePath) !== null && _this$basePath6 !== void 0 ? _this$basePath6 : [...toPath([...ancestors, parent, referencingElement]), '$ref']
         }, rootCause);
-        (_this$options$derefer5 = this.options.dereference.dereferenceOpts) === null || _this$options$derefer5 === void 0 || (_this$options$derefer5 = _this$options$derefer5.errors) === null || _this$options$derefer5 === void 0 || (_this$options$derefer6 = _this$options$derefer5.push) === null || _this$options$derefer6 === void 0 || _this$options$derefer6.call(_this$options$derefer5, wrappedError);
+        (_this$options$derefer11 = this.options.dereference.dereferenceOpts) === null || _this$options$derefer11 === void 0 || (_this$options$derefer11 = _this$options$derefer11.errors) === null || _this$options$derefer11 === void 0 || (_this$options$derefer12 = _this$options$derefer11.push) === null || _this$options$derefer12 === void 0 || _this$options$derefer12.call(_this$options$derefer11, wrappedError);
         return undefined;
       }
     },
@@ -595,14 +678,14 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = OpenApi3_1DereferenceVisitor.c
       try {
         return await OpenApi3_1DereferenceVisitor.compose.methods.ExampleElement.call(this, exampleElement, key, parent, path, ancestors);
       } catch (error) {
-        var _this$basePath7, _this$options$derefer7, _this$options$derefer8;
+        var _this$basePath7, _this$options$derefer13, _this$options$derefer14;
         const rootCause = getRootCause(error);
         const wrappedError = wrapError(rootCause, {
           baseDoc: this.reference.uri,
           externalValue: toValue(exampleElement.externalValue),
           fullPath: (_this$basePath7 = this.basePath) !== null && _this$basePath7 !== void 0 ? _this$basePath7 : [...toPath([...ancestors, parent, exampleElement]), 'externalValue']
         });
-        (_this$options$derefer7 = this.options.dereference.dereferenceOpts) === null || _this$options$derefer7 === void 0 || (_this$options$derefer7 = _this$options$derefer7.errors) === null || _this$options$derefer7 === void 0 || (_this$options$derefer8 = _this$options$derefer7.push) === null || _this$options$derefer8 === void 0 || _this$options$derefer8.call(_this$options$derefer7, wrappedError);
+        (_this$options$derefer13 = this.options.dereference.dereferenceOpts) === null || _this$options$derefer13 === void 0 || (_this$options$derefer13 = _this$options$derefer13.errors) === null || _this$options$derefer13 === void 0 || (_this$options$derefer14 = _this$options$derefer13.push) === null || _this$options$derefer14 === void 0 || _this$options$derefer14.call(_this$options$derefer13, wrappedError);
         return undefined;
       }
     }