fix(reference): fix regression in OpenAPI 2.0 derferencing (#3976)

Refs #3974

packages/apidom-reference/src/dereference/strategies/openapi-2/visitor.ts

@@ -230,13 +230,17 @@ const OpenApi2DereferenceVisitor = stampit({
        *
        * Cases to consider:
        *  1. We're crossing document boundary
-       *  2. Fragment is a Reference Object. We need to follow it to get the eventual value
-       *  3. We are dereferencing the fragment lazily/eagerly depending on circular mode
+       *  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 = reference.refSet.rootRef.uri !== reference.uri;
+      const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
       if (
         (isExternalReference ||
+          isNonRootDocument ||
           isReferenceElement(referencedElement) ||
-          ['error', 'replace'].includes(this.options.dereference.circular)) &&
+          shouldDetectCircular) &&
         !ancestorsLineage.includesCycle(referencedElement)
       ) {
         // append referencing reference to ancestors lineage
@@ -398,13 +402,17 @@ const OpenApi2DereferenceVisitor = stampit({
        *
        * Cases to consider:
        *  1. We're crossing document boundary
-       *  2. Fragment is a Paht Item Object with $ref field. We need to follow it to get the eventual value
-       *  3. We are dereferencing the fragment lazily/eagerly depending on circular mode
+       *  2. Fragment is from non-root document
+       *  3. Fragment is a Paht 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 = reference.refSet.rootRef.uri !== reference.uri;
+      const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
       if (
         (isExternalReference ||
+          isNonRootDocument ||
           (isPathItemElement(referencedElement) && isStringElement(referencedElement.$ref)) ||
-          ['error', 'replace'].includes(this.options.dereference.circular)) &&
+          shouldDetectCircular) &&
         !ancestorsLineage.includesCycle(referencedElement)
       ) {
         // append referencing reference to ancestors lineage
@@ -581,13 +589,17 @@ const OpenApi2DereferenceVisitor = stampit({
        *
        * Cases to consider:
        *  1. We're crossing document boundary
-       *  2. Fragment is a JSON Reference Object. We need to follow it to get the eventual value
-       *  3. We are dereferencing the fragment lazily/eagerly depending on circular mode
+          2. Fragment is from non-root document
+       *  3. Fragment is a JSON 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 = reference.refSet.rootRef.uri !== reference.uri;
+      const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
       if (
         (isExternalReference ||
+          isNonRootDocument ||
           isJSONReferenceElement(referencedElement) ||
-          ['error', 'replace'].includes(this.options.dereference.circular)) &&
+          shouldDetectCircular) &&
         !ancestorsLineage.includesCycle(referencedElement)
       ) {
         // append referencing reference to ancestors lineage

packages/apidom-reference/test/dereference/strategies/openapi-2/reference-object/dereference-apidom.ts

@@ -1,6 +1,11 @@
 import path from 'node:path';
 import { assert } from 'chai';
-import { mediaTypes, isParameterElement, SwaggerElement } from '@swagger-api/apidom-ns-openapi-2';
+import {
+  mediaTypes,
+  isParameterElement,
+  isSchemaElement,
+  SwaggerElement,
+} from '@swagger-api/apidom-ns-openapi-2';
 import { toValue } from '@swagger-api/apidom-core';
 import { evaluate } from '@swagger-api/apidom-json-pointer';
 
@@ -119,23 +124,23 @@ describe('dereference', function () {
                   parse: { mediaType: mediaTypes.latest('json') },
                 });
                 const referenceElement = evaluate(
-                  '/paths/~1/parameters/0',
+                  '/definitions/externalSchema',
                   parseResult.api as SwaggerElement,
                 );
                 const dereferenced = await dereferenceApiDOM(referenceElement, {
                   parse: { mediaType: mediaTypes.latest('json') },
                   resolve: { baseURI: fixturePath },
                 });
 
-                assert.isTrue(isParameterElement(dereferenced));
+                assert.isTrue(isSchemaElement(dereferenced));
               });
 
               specify('should dereference and contain metadata about origin', async function () {
                 const parseResult = await parse(fixturePath, {
                   parse: { mediaType: mediaTypes.latest('json') },
                 });
                 const referenceElement = evaluate(
-                  '/paths/~1/parameters/0',
+                  '/definitions/externalSchema',
                   parseResult.api as SwaggerElement,
                 );
                 const dereferenced = await dereferenceApiDOM(referenceElement, {
@@ -169,23 +174,23 @@ describe('dereference', function () {
                   parse: { mediaType: mediaTypes.latest('json') },
                 });
                 const referenceElement = evaluate(
-                  '/paths/~1/parameters/0',
+                  '/definitions/externalSchema',
                   parseResult.api as SwaggerElement,
                 );
                 const dereferenced = await dereferenceApiDOM(referenceElement, {
                   parse: { mediaType: mediaTypes.latest('json') },
                   resolve: { baseURI: `http://localhost:${httpPort}/root.json` },
                 });
 
-                assert.isTrue(isParameterElement(dereferenced));
+                assert.isTrue(isSchemaElement(dereferenced));
               });
 
               specify('should dereference and contain metadata about origin', async function () {
                 const parseResult = await parse(fixturePath, {
                   parse: { mediaType: mediaTypes.latest('json') },
                 });
                 const referenceElement = evaluate(
-                  '/paths/~1/parameters/0',
+                  '/definitions/externalSchema',
                   parseResult.api as SwaggerElement,
                 );
                 const dereferenced = await dereferenceApiDOM(referenceElement, {

packages/apidom-reference/test/dereference/strategies/openapi-2/reference-object/fixtures/external-only/dereferenced.json

@@ -1,16 +1,16 @@
 [
   {
     "swagger": "2.0",
-    "paths": {
-      "/": {
-        "parameters": [
-          {
-            "name": "externalParameter",
-            "in": "query",
-            "description": "this is parameter stored in external file",
-            "required": true
+    "definitions": {
+      "externalSchema": {
+        "type": "object",
+        "properties": {
+          "sentAt": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Date and time when the message was sent."
           }
-        ]
+        }
       }
     }
   }

packages/apidom-reference/test/dereference/strategies/openapi-2/reference-object/fixtures/external-only/ex.json

@@ -1,8 +1,21 @@
 {
-  "externalParameter": {
-    "name": "externalParameter",
-    "in": "query",
-    "description": "this is parameter stored in external file",
-    "required": true
+  "openapi": "2.0",
+  "definitions": {
+    "schema1": {
+      "$ref": "#/definitions/somePayload"
+    },
+    "somePayload": {
+      "type": "object",
+      "properties": {
+        "sentAt": {
+          "$ref": "#/definitions/sentAt"
+        }
+      }
+    },
+    "sentAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Date and time when the message was sent."
+    }
   }
 }

packages/apidom-reference/test/dereference/strategies/openapi-2/reference-object/fixtures/external-only/root.json

@@ -1,12 +1,8 @@
 {
   "swagger": "2.0",
-  "paths": {
-    "/": {
-      "parameters": [
-        {
-          "$ref": "./ex.json#/externalParameter"
-        }
-      ]
+  "definitions": {
+    "externalSchema": {
+      "$ref": "./ex.json#/definitions/schema1"
     }
   }
 }