feat(reference): add additional metadata during dereference

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

@@ -119,6 +119,12 @@ const AsyncApi2_0DereferenceVisitor = stampit({
       });
       fragment = await visitAsync(fragment, visitor, { keyMap, nodeTypeGetter: getNodeType });
 
+      // annotate fragment with info about original Reference element
+      fragment = fragment.clone();
+      fragment.setMetaProperty('ref-fields', {
+        $ref: referenceElement.$ref.toValue(),
+      });
+
       this.indirections.pop();
 
       // transclude the element for a fragment

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

@@ -160,20 +160,27 @@ const OpenApi3_1DereferenceVisitor = stampit({
       });
       fragment = await visitAsync(fragment, visitor, { keyMap, nodeTypeGetter: getNodeType });
 
+      fragment = fragment.clone();
+
+      // annotate fragment with info about original Reference element
+      fragment.setMetaProperty('ref-fields', {
+        $ref: referenceElement.$ref.toValue(),
+        // @ts-ignore
+        description: referenceElement.description?.toValue(),
+        // @ts-ignore
+        summary: referenceElement.summary?.toValue(),
+      });
+
       // override description and summary (outer has higher priority then inner)
       const hasDescription = pathSatisfies(isNotUndefined, ['description'], referenceElement);
       const hasSummary = pathSatisfies(isNotUndefined, ['summary'], referenceElement);
-      if (hasDescription || hasSummary) {
-        fragment = fragment.clone();
-
-        if (hasDescription && hasIn('description', fragment)) {
-          // @ts-ignore
-          fragment.description = referenceElement.description;
-        }
-        if (hasSummary && hasIn('summary', fragment)) {
-          // @ts-ignore
-          fragment.summary = referenceElement.summary;
-        }
+      if (hasDescription && hasIn('description', fragment)) {
+        // @ts-ignore
+        fragment.description = referenceElement.description;
+      }
+      if (hasSummary && hasIn('summary', fragment)) {
+        // @ts-ignore
+        fragment.summary = referenceElement.summary;
       }
 
       this.indirections.pop();
@@ -281,6 +288,11 @@ const OpenApi3_1DereferenceVisitor = stampit({
       });
       mergedResult.remove('$ref');
 
+      // annotate referencing element with info about original referenced element
+      mergedResult.setMetaProperty('ref-fields', {
+        $ref: referencingElement.$ref?.toValue(),
+      });
+
       // transclude referencing element with merged referenced element
       return mergedResult;
     },

apidom/packages/apidom-reference/test/dereference/strategies/asyncapi-2-0/reference-object/index.ts

@@ -40,6 +40,22 @@ describe('dereference', function () {
 
             assert.isTrue(isParameterElement(fragment));
           });
+
+          specify(
+            'should annotate transcluded element with additional metadata',
+            async function () {
+              const rootFilePath = path.join(fixturePath, 'root.json');
+              const dereferenced = await dereference(rootFilePath, {
+                parse: { mediaType: 'application/vnd.oai.openapi+json;version=3.1.0' },
+              });
+              const fragment = evaluate('/0/components/parameters/userId', dereferenced);
+
+              assert.strictEqual(
+                fragment.meta.get('ref-fields').get('$ref').toValue(),
+                '#/components/parameters/indirection1',
+              );
+            },
+          );
         });
 
         context('given Reference Objects pointing internally only', function () {

apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/reference-object/index.ts

@@ -40,6 +40,26 @@ describe('dereference', function () {
 
             assert.isTrue(isParameterElement(fragment));
           });
+
+          specify(
+            'should annotate transcluded element with additional metadata',
+            async function () {
+              const rootFilePath = path.join(fixturePath, 'root.json');
+              const dereferenced = await dereference(rootFilePath, {
+                parse: { mediaType: 'application/vnd.oai.openapi+json;version=3.1.0' },
+              });
+              const fragment = evaluate('/0/components/parameters/userId', dereferenced);
+
+              assert.strictEqual(
+                fragment.meta.get('ref-fields').get('$ref').toValue(),
+                '#/components/parameters/indirection1',
+              );
+              assert.strictEqual(
+                fragment.meta.get('ref-fields').get('description').toValue(),
+                'override',
+              );
+            },
+          );
         });
       });
 

apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/schema-object/index.ts

@@ -41,6 +41,25 @@ describe('dereference', function () {
 
             assert.isTrue(isSchemaElement(fragment));
           });
+
+          specify(
+            'should annotate transcluded element with additional metadata',
+            async function () {
+              const rootFilePath = path.join(fixturePath, 'root.json');
+              const dereferenced = await dereference(rootFilePath, {
+                parse: { mediaType: 'application/vnd.oai.openapi+json;version=3.1.0' },
+              });
+              const fragment = evaluate(
+                '/0/components/schemas/User/properties/profile',
+                dereferenced,
+              );
+
+              assert.strictEqual(
+                fragment.meta.get('ref-fields').get('$ref').toValue(),
+                '#/components/schemas/UserProfile',
+              );
+            },
+          );
         });
 
         context('given Schema Objects pointing internally only', function () {