feat(reference): incorporate dereference into overall achitecture

apidom/packages/apidom-parser-adapter-asyncapi-json-2-0/src/adapter.ts

@@ -24,6 +24,7 @@ export const parse = async (
 
   if (isNotUndefined(firstResultElement)) {
     const asyncApiElement = AsyncApi2_0Element.refract(firstResultElement, refractorOpts);
+    asyncApiElement.classes.push('result');
     parseResultElement = transclude(firstResultElement, asyncApiElement, parseResultElement);
   }
 

apidom/packages/apidom-parser-adapter-asyncapi-yaml-2-0/src/adapter.ts

@@ -24,6 +24,7 @@ export const parse = async (
 
   if (isNotUndefined(firstResultElement)) {
     const asyncApiElement = AsyncApi2_0Element.refract(firstResultElement, refractorOpts);
+    asyncApiElement.classes.push('result');
     parseResultElement = transclude(firstResultElement, asyncApiElement, parseResultElement);
   }
 

apidom/packages/apidom-parser-adapter-openapi-json-3-1/src/adapter.ts

@@ -24,6 +24,7 @@ export const parse = async (
 
   if (isNotUndefined(firstResultElement)) {
     const openApiElement = OpenApi3_1Element.refract(firstResultElement, refractorOpts);
+    openApiElement.classes.push('result');
     parseResultElement = transclude(firstResultElement, openApiElement, parseResultElement);
   }
 

apidom/packages/apidom-parser-adapter-openapi-yaml-3-1/src/adapter.ts

@@ -24,6 +24,7 @@ export const parse = async (
 
   if (isNotUndefined(firstResultElement)) {
     const openApiElement = OpenApi3_1Element.refract(firstResultElement, refractorOpts);
+    openApiElement.classes.push('result');
     parseResultElement = transclude(firstResultElement, openApiElement, parseResultElement);
   }
 

apidom/packages/apidom-reference/src/ReferenceSet.ts

@@ -48,6 +48,14 @@ const ReferenceSet: stampit.Stamp<IReferenceSet> = stampit({
     *values() {
       yield* this.refs;
     },
+
+    clean() {
+      this.refs.forEach((ref: IReference) => {
+        // eslint-disable-next-line no-param-reassign
+        ref.refSet = null;
+      });
+      this.refs = [];
+    },
   },
 });
 

apidom/packages/apidom-reference/src/dereference/index.ts

@@ -0,0 +1,57 @@
+import { isEmpty } from 'ramda';
+import { Element, ParseResultElement } from 'apidom';
+
+import File from '../util/File';
+import * as plugins from '../util/plugins';
+import { UnmatchedResolveStrategyError } from '../util/errors';
+import DereferenceError from '../util/errors/DereferenceError';
+import { ReferenceOptions as IReferenceOptions } from '../types';
+import parse from '../parse';
+import { merge as mergeOptions } from '../options/util';
+
+/**
+ * Dereferences ApiDOM with all it's external references.
+ */
+export const dereferenceApiDOM = async <T extends Element>(
+  element: T,
+  options: IReferenceOptions,
+): Promise<T> => {
+  const file = File({
+    uri: options.resolve.baseURI,
+    parseResult: element,
+    mediaType: options.parse.mediaType,
+  });
+
+  const dereferenceStrategies = plugins.filter(
+    'canDereference',
+    file,
+    options.dereference.strategies,
+  );
+
+  // we couldn't find any dereference for this File
+  if (isEmpty(dereferenceStrategies)) {
+    throw new UnmatchedResolveStrategyError(file.uri);
+  }
+
+  try {
+    const { result } = await plugins.run('dereference', [file, options], dereferenceStrategies);
+    return result;
+  } catch (error) {
+    throw new DereferenceError(`Error while dereferencing file "${file.uri}"`, error);
+  }
+};
+
+/**
+ * Dereferences a file with all it's external references.
+ */
+const dereference = async (
+  uri: string,
+  options: IReferenceOptions,
+): Promise<ParseResultElement> => {
+  const parseResult = await parse(uri, options);
+  const mergedOptions = mergeOptions(options, { resolve: { baseURI: uri } });
+
+  return dereferenceApiDOM(parseResult, mergedOptions);
+};
+
+export default dereference;

apidom/packages/apidom-reference/src/dereference/strategies/DereferenceStrategy.ts

@@ -0,0 +1,18 @@
+import stampit from 'stampit';
+
+import { DereferenceStrategy as IDereferenceStrategy } from '../../types';
+import { NotImplementedError } from '../../util/errors';
+
+const DereferenceStrategy: stampit.Stamp<IDereferenceStrategy> = stampit({
+  methods: {
+    canDereference() {
+      return false;
+    },
+
+    async dereference(): Promise<never> {
+      throw new NotImplementedError();
+    },
+  },
+});
+
+export default DereferenceStrategy;

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

@@ -0,0 +1,61 @@
+import stampit from 'stampit';
+import { createNamespace, visit, Element } from 'apidom';
+import openApi3_1Namespace, {
+  getNodeType,
+  isOpenApi3_1Element,
+  keyMap,
+} from 'apidom-ns-openapi-3-1';
+
+import DereferenceStrategy from '../DereferenceStrategy';
+import {
+  DereferenceStrategy as IDereferenceStrategy,
+  File as IFile,
+  ReferenceOptions as IReferenceOptions,
+} from '../../../types';
+import Reference from '../../../Reference';
+import ReferenceSet from '../../../ReferenceSet';
+import OpenApi3_1DereferenceVisitor from './visitor';
+
+// @ts-ignore
+const visitAsync = visit[Symbol.for('nodejs.util.promisify.custom')];
+
+const OpenApi3_1DereferenceStrategy: stampit.Stamp<IDereferenceStrategy> = stampit(
+  DereferenceStrategy,
+  {
+    methods: {
+      canDereference(file: IFile): boolean {
+        // assert by media type
+        if (file.mediaType !== 'text/plain') {
+          return [
+            'application/vnd.oai.openapi;version=3.1.0',
+            'application/vnd.oai.openapi+json;version=3.1.0',
+            'application/vnd.oai.openapi+yaml;version=3.1.0',
+          ].includes(file.mediaType);
+        }
+
+        // assert by inspecting ApiDOM
+        return isOpenApi3_1Element(file.parseResult?.api);
+      },
+
+      async dereference(file: IFile, options: IReferenceOptions): Promise<Element> {
+        const namespace = createNamespace(openApi3_1Namespace);
+        const reference = Reference({ uri: file.uri, value: file.parseResult });
+        const visitor = OpenApi3_1DereferenceVisitor({ reference, namespace, options });
+        const refSet = ReferenceSet();
+        refSet.add(reference);
+
+        const dereferencedElement = await visitAsync(refSet.rootRef.value, visitor, {
+          keyMap,
+          nodeTypeGetter: getNodeType,
+        });
+
+        // release all memory
+        refSet.clean();
+
+        return dereferencedElement;
+      },
+    },
+  },
+);
+
+export default OpenApi3_1DereferenceStrategy;