@speclynx/apidom-reference 1.12.1

package/src/dereference/strategies/asyncapi-2/visitor.mjs

@@ -0,0 +1,406 @@
+import { propEq } from 'ramda';
+import { isElement, isMemberElement, isPrimitiveElement, isStringElement, IdentityManager, cloneDeep, cloneShallow, visit, toValue, RefElement } from '@speclynx/apidom-core';
+import { ApiDOMError } from '@speclynx/apidom-error';
+import { evaluate, URIFragmentIdentifier } from '@speclynx/apidom-json-pointer';
+import { ChannelItemElement, getNodeType, isReferenceLikeElement, isBooleanJsonSchemaElement, isChannelItemElement, isReferenceElement, keyMap, ReferenceElement } from '@speclynx/apidom-ns-asyncapi-2';
+import MaximumDereferenceDepthError from "../../../errors/MaximumDereferenceDepthError.mjs";
+import MaximumResolveDepthError from "../../../errors/MaximumResolveDepthError.mjs";
+import { AncestorLineage } from "../../util.mjs";
+import * as url from "../../../util/url.mjs";
+import parse from "../../../parse/index.mjs";
+import Reference from "../../../Reference.mjs";
+// @ts-ignore
+const visitAsync = visit[Symbol.for('nodejs.util.promisify.custom')];
+
+// initialize element identity manager
+const identityManager = new IdentityManager();
+
+/**
+ * Custom mutation replacer.
+ * @public
+ */
+export const mutationReplacer = (newElement, oldElement, key, parent) => {
+  if (isMemberElement(parent)) {
+    parent.value = newElement;
+  } else if (Array.isArray(parent)) {
+    parent[key] = newElement;
+  }
+};
+
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class AsyncAPI2DereferenceVisitor {
+  indirections;
+  namespace;
+  reference;
+  options;
+  ancestors;
+  refractCache;
+  constructor({
+    reference,
+    namespace,
+    options,
+    indirections = [],
+    ancestors = new AncestorLineage(),
+    refractCache = new Map()
+  }) {
+    this.indirections = indirections;
+    this.namespace = namespace;
+    this.reference = reference;
+    this.options = options;
+    this.ancestors = new AncestorLineage(...ancestors);
+    this.refractCache = refractCache;
+  }
+  toBaseURI(uri) {
+    return url.resolve(this.reference.uri, url.sanitize(url.stripHash(uri)));
+  }
+  async toReference(uri) {
+    // detect maximum depth of resolution
+    if (this.reference.depth >= this.options.resolve.maxDepth) {
+      throw new MaximumResolveDepthError(`Maximum resolution depth of ${this.options.resolve.maxDepth} has been exceeded by file "${this.reference.uri}"`);
+    }
+    const baseURI = this.toBaseURI(uri);
+    const {
+      refSet
+    } = this.reference;
+
+    // we've already processed this Reference in past
+    if (refSet.has(baseURI)) {
+      return refSet.find(propEq(baseURI, 'uri'));
+    }
+    const parseResult = await parse(url.unsanitize(baseURI), {
+      ...this.options,
+      parse: {
+        ...this.options.parse,
+        mediaType: 'text/plain'
+      }
+    });
+
+    // register new mutable reference with a refSet
+    const mutableReference = new Reference({
+      uri: baseURI,
+      value: cloneDeep(parseResult),
+      depth: this.reference.depth + 1
+    });
+    refSet.add(mutableReference);
+    if (this.options.dereference.immutable) {
+      // register new immutable reference with a refSet
+      const immutableReference = new Reference({
+        uri: `immutable://${baseURI}`,
+        value: parseResult,
+        depth: this.reference.depth + 1
+      });
+      refSet.add(immutableReference);
+    }
+    return mutableReference;
+  }
+  toAncestorLineage(ancestors) {
+    /**
+     * Compute full ancestors lineage.
+     * Ancestors are flatten to unwrap all Element instances.
+     */
+    const directAncestors = new Set(ancestors.filter(isElement));
+    const ancestorsLineage = new AncestorLineage(...this.ancestors, directAncestors);
+    return [ancestorsLineage, directAncestors];
+  }
+  async ReferenceElement(referencingElement, key, parent, path, ancestors, link) {
+    // 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;
+
+    // ignore resolving internal Reference Objects
+    if (!this.options.resolve.internal && isInternalReference) {
+      // skip traversing this reference and all it's child elements
+      return false;
+    }
+    // ignore resolving external Reference Objects
+    if (!this.options.resolve.external && isExternalReference) {
+      // skip traversing this reference and all it's child elements
+      return false;
+    }
+    const reference = await this.toReference(toValue(referencingElement.$ref));
+    const $refBaseURI = url.resolve(retrievalURI, toValue(referencingElement.$ref));
+    this.indirections.push(referencingElement);
+    const jsonPointer = URIFragmentIdentifier.fromURIReference($refBaseURI);
+
+    // possibly non-semantic fragment
+    let referencedElement = evaluate(reference.value.result, jsonPointer);
+    referencedElement.id = identityManager.identify(referencedElement);
+
+    /**
+     * Applying semantics to a referenced element if semantics are missing.
+     */
+    if (isPrimitiveElement(referencedElement)) {
+      const referencedElementType = toValue(referencingElement.meta.get('referenced-element'));
+      const cacheKey = `${referencedElementType}-${toValue(identityManager.identify(referencedElement))}`;
+      if (this.refractCache.has(cacheKey)) {
+        referencedElement = this.refractCache.get(cacheKey);
+      } else if (isReferenceLikeElement(referencedElement)) {
+        // handling indirect references
+        referencedElement = ReferenceElement.refract(referencedElement);
+        referencedElement.setMetaProperty('referenced-element', referencedElementType);
+        this.refractCache.set(cacheKey, referencedElement);
+      } else {
+        // handling direct references
+        const ElementClass = this.namespace.getElementClass(referencedElementType);
+        referencedElement = ElementClass.refract(referencedElement);
+        this.refractCache.set(cacheKey, referencedElement);
+      }
+    }
+
+    // detect direct or circular reference
+    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}"`);
+    }
+
+    // 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') {
+        const refElement = new RefElement(referencedElement.id, {
+          type: 'reference',
+          uri: reference.uri,
+          $ref: toValue(referencingElement.$ref)
+        });
+        const replacer = this.options.dereference.strategyOpts['asyncapi-2']?.circularReplacer ?? this.options.dereference.circularReplacer;
+        const replacement = replacer(refElement);
+        link.replaceWith(replacement, mutationReplacer);
+        return !parent ? replacement : false;
+      }
+    }
+
+    /**
+     * 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)) {
+      // append referencing reference to ancestors lineage
+      directAncestors.add(referencingElement);
+      const visitor = new AsyncAPI2DereferenceVisitor({
+        reference,
+        namespace: this.namespace,
+        indirections: [...this.indirections],
+        options: this.options,
+        refractCache: this.refractCache,
+        ancestors: ancestorsLineage
+      });
+      referencedElement = await visitAsync(referencedElement, visitor, {
+        keyMap,
+        nodeTypeGetter: getNodeType
+      });
+
+      // remove referencing reference from ancestors lineage
+      directAncestors.delete(referencingElement);
+    }
+    this.indirections.pop();
+
+    // Boolean JSON Schemas
+    if (isBooleanJsonSchemaElement(referencedElement)) {
+      const booleanJsonSchemaElement = cloneDeep(referencedElement);
+      // assign unique id to merged element
+      booleanJsonSchemaElement.setMetaProperty('id', identityManager.generateId());
+      // annotate referenced element with info about original referencing element
+      booleanJsonSchemaElement.setMetaProperty('ref-fields', {
+        $ref: toValue(referencingElement.$ref)
+      });
+      // annotate referenced element with info about origin
+      booleanJsonSchemaElement.setMetaProperty('ref-origin', reference.uri);
+      // annotate fragment with info about referencing element
+      booleanJsonSchemaElement.setMetaProperty('ref-referencing-element-id', cloneDeep(identityManager.identify(referencingElement)));
+      link.replaceWith(booleanJsonSchemaElement, mutationReplacer);
+      return !parent ? booleanJsonSchemaElement : false;
+    }
+
+    /**
+     * Creating a new version of referenced element to avoid modifying the original one.
+     */
+    const mergedElement = cloneShallow(referencedElement);
+    // assign unique id to merged element
+    mergedElement.setMetaProperty('id', identityManager.generateId());
+    // annotate referenced element with info about original referencing element
+    mergedElement.setMetaProperty('ref-fields', {
+      $ref: toValue(referencingElement.$ref)
+    });
+    // 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)));
+
+    /**
+     * Transclude referencing element with merged referenced element.
+     */
+    link.replaceWith(mergedElement, mutationReplacer);
+
+    /**
+     * We're at the root of the tree, so we're just replacing the entire tree.
+     */
+    return !parent ? mergedElement : false;
+  }
+  async ChannelItemElement(referencingElement, key, parent, path, ancestors, link) {
+    // ignore ChannelItemElement without $ref field
+    if (!isStringElement(referencingElement.$ref)) {
+      return undefined;
+    }
+
+    // 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;
+
+    // ignore resolving internal Channel Item Objects
+    if (!this.options.resolve.internal && isInternalReference) {
+      // skip traversing this channel item but traverse all it's child elements
+      return undefined;
+    }
+    // ignore resolving external Channel Item Objects
+    if (!this.options.resolve.external && isExternalReference) {
+      // skip traversing this channel item but traverse all it's child elements
+      return undefined;
+    }
+    const reference = await this.toReference(toValue(referencingElement.$ref));
+    const $refBaseURI = url.resolve(retrievalURI, toValue(referencingElement.$ref));
+    this.indirections.push(referencingElement);
+    const jsonPointer = URIFragmentIdentifier.fromURIReference($refBaseURI);
+
+    // possibly non-semantic referenced element
+    let referencedElement = evaluate(reference.value.result, jsonPointer);
+    referencedElement.id = identityManager.identify(referencedElement);
+
+    /**
+     * Applying semantics to a referenced element if semantics are missing.
+     */
+    if (isPrimitiveElement(referencedElement)) {
+      const cacheKey = `channel-item-${toValue(identityManager.identify(referencedElement))}`;
+      if (this.refractCache.has(cacheKey)) {
+        referencedElement = this.refractCache.get(cacheKey);
+      } else {
+        referencedElement = ChannelItemElement.refract(referencedElement);
+        this.refractCache.set(cacheKey, referencedElement);
+      }
+    }
+
+    // detect direct or indirect reference
+    if (referencingElement === referencedElement) {
+      throw new ApiDOMError('Recursive Channel 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}"`);
+    }
+
+    // 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') {
+        const refElement = new RefElement(referencedElement.id, {
+          type: 'channel-item',
+          uri: reference.uri,
+          $ref: toValue(referencingElement.$ref)
+        });
+        const replacer = this.options.dereference.strategyOpts['asyncapi-2']?.circularReplacer ?? this.options.dereference.circularReplacer;
+        const replacement = replacer(refElement);
+        link.replaceWith(replacement, mutationReplacer);
+        return !parent ? replacement : undefined;
+      }
+    }
+
+    /**
+     * 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 Channel 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 || isChannelItemElement(referencedElement) && isStringElement(referencedElement.$ref) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      // append referencing reference to ancestors lineage
+      directAncestors.add(referencingElement);
+      const visitor = new AsyncAPI2DereferenceVisitor({
+        reference,
+        namespace: this.namespace,
+        indirections: [...this.indirections],
+        options: this.options,
+        refractCache: this.refractCache,
+        ancestors: ancestorsLineage
+      });
+      referencedElement = await visitAsync(referencedElement, visitor, {
+        keyMap,
+        nodeTypeGetter: getNodeType
+      });
+
+      // remove referencing reference from ancestors lineage
+      directAncestors.delete(referencingElement);
+    }
+    this.indirections.pop();
+
+    /**
+     * Creating a new version of Channel Item by merging fields from referenced Channel Item with referencing one.
+     */
+    if (isChannelItemElement(referencedElement)) {
+      const mergedElement = new ChannelItemElement([...referencedElement.content], cloneDeep(referencedElement.meta), cloneDeep(referencedElement.attributes));
+      // assign unique id to merged element
+      mergedElement.setMetaProperty('id', identityManager.generateId());
+      // existing keywords from referencing ChannelItemElement overrides ones from referenced ChannelItemElement
+      referencingElement.forEach((value, keyElement, item) => {
+        mergedElement.remove(toValue(keyElement));
+        mergedElement.content.push(item);
+      });
+      mergedElement.remove('$ref');
+
+      // annotate referenced element with info about original referencing element
+      mergedElement.setMetaProperty('ref-fields', {
+        $ref: toValue(referencingElement.$ref)
+      });
+      // annotate referenced 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)));
+      referencedElement = mergedElement;
+    }
+
+    /**
+     * Transclude referencing element with merged referenced element.
+     */
+    link.replaceWith(referencedElement, mutationReplacer);
+
+    /**
+     * We're at the root of the tree, so we're just replacing the entire tree.
+     */
+    return !parent ? referencedElement : undefined;
+  }
+}
+export default AsyncAPI2DereferenceVisitor;

package/src/dereference/strategies/openapi-2/index.cjs

@@ -0,0 +1,102 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomCore = require("@speclynx/apidom-core");
+var _apidomNsOpenapi = _interopRequireWildcard(require("@speclynx/apidom-ns-openapi-2"));
+var _DereferenceStrategy = _interopRequireDefault(require("../DereferenceStrategy.cjs"));
+var _Reference = _interopRequireDefault(require("../../../Reference.cjs"));
+var _ReferenceSet = _interopRequireDefault(require("../../../ReferenceSet.cjs"));
+var _visitor = _interopRequireDefault(require("./visitor.cjs"));
+exports.OpenAPI2DereferenceVisitor = _visitor.default;
+// @ts-ignore
+const visitAsync = _apidomCore.visit[Symbol.for('nodejs.util.promisify.custom')];
+
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class OpenAPI2DereferenceStrategy extends _DereferenceStrategy.default {
+  constructor(options) {
+    super({
+      ...(options ?? {}),
+      name: 'openapi-2'
+    });
+  }
+  canDereference(file) {
+    // assert by media type
+    if (file.mediaType !== 'text/plain') {
+      return _apidomNsOpenapi.mediaTypes.includes(file.mediaType);
+    }
+
+    // assert by inspecting ApiDOM
+    return (0, _apidomNsOpenapi.isSwaggerElement)(file.parseResult?.api);
+  }
+  async dereference(file, options) {
+    const namespace = (0, _apidomCore.createNamespace)(_apidomNsOpenapi.default);
+    const immutableRefSet = options.dereference.refSet ?? new _ReferenceSet.default();
+    const mutableRefSet = new _ReferenceSet.default();
+    let refSet = immutableRefSet;
+    let reference;
+    if (!immutableRefSet.has(file.uri)) {
+      reference = new _Reference.default({
+        uri: file.uri,
+        value: file.parseResult
+      });
+      immutableRefSet.add(reference);
+    } else {
+      // pre-computed refSet was provided as configuration option
+      reference = immutableRefSet.find(ref => ref.uri === file.uri);
+    }
+
+    /**
+     * Clone refSet due the dereferencing process being mutable.
+     * We don't want to mutate the original refSet and the references.
+     */
+    if (options.dereference.immutable) {
+      immutableRefSet.refs.map(ref => new _Reference.default({
+        ...ref,
+        value: (0, _apidomCore.cloneDeep)(ref.value)
+      })).forEach(ref => mutableRefSet.add(ref));
+      reference = mutableRefSet.find(ref => ref.uri === file.uri);
+      refSet = mutableRefSet;
+    }
+    const visitor = new _visitor.default({
+      reference: reference,
+      namespace,
+      options
+    });
+    const dereferencedElement = await visitAsync(refSet.rootRef.value, visitor, {
+      keyMap: _apidomNsOpenapi.keyMap,
+      nodeTypeGetter: _apidomNsOpenapi.getNodeType
+    });
+
+    /**
+     * If immutable option is set, replay refs from the refSet.
+     */
+    if (options.dereference.immutable) {
+      mutableRefSet.refs.filter(ref => ref.uri.startsWith('immutable://')).map(ref => new _Reference.default({
+        ...ref,
+        uri: ref.uri.replace(/^immutable:\/\//, '')
+      })).forEach(ref => immutableRefSet.add(ref));
+      reference = immutableRefSet.find(ref => ref.uri === file.uri);
+      refSet = immutableRefSet;
+    }
+
+    /**
+     * Release all memory if this refSet was not provided as a configuration option.
+     * If provided as configuration option, then provider is responsible for cleanup.
+     */
+    if (options.dereference.refSet === null) {
+      immutableRefSet.clean();
+    }
+    mutableRefSet.clean();
+    return dereferencedElement;
+  }
+}
+var _default = exports.default = OpenAPI2DereferenceStrategy;

package/src/dereference/strategies/openapi-2/index.mjs

@@ -0,0 +1,96 @@
+import { createNamespace, visit, cloneDeep } from '@speclynx/apidom-core';
+import openApi2Namespace, { getNodeType, isSwaggerElement, keyMap, mediaTypes } from '@speclynx/apidom-ns-openapi-2';
+import DereferenceStrategy from "../DereferenceStrategy.mjs";
+import Reference from "../../../Reference.mjs";
+import ReferenceSet from "../../../ReferenceSet.mjs";
+import OpenAPI2DereferenceVisitor from "./visitor.mjs";
+// @ts-ignore
+const visitAsync = visit[Symbol.for('nodejs.util.promisify.custom')];
+
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class OpenAPI2DereferenceStrategy extends DereferenceStrategy {
+  constructor(options) {
+    super({
+      ...(options ?? {}),
+      name: 'openapi-2'
+    });
+  }
+  canDereference(file) {
+    // assert by media type
+    if (file.mediaType !== 'text/plain') {
+      return mediaTypes.includes(file.mediaType);
+    }
+
+    // assert by inspecting ApiDOM
+    return isSwaggerElement(file.parseResult?.api);
+  }
+  async dereference(file, options) {
+    const namespace = createNamespace(openApi2Namespace);
+    const immutableRefSet = options.dereference.refSet ?? new ReferenceSet();
+    const mutableRefSet = new ReferenceSet();
+    let refSet = immutableRefSet;
+    let reference;
+    if (!immutableRefSet.has(file.uri)) {
+      reference = new Reference({
+        uri: file.uri,
+        value: file.parseResult
+      });
+      immutableRefSet.add(reference);
+    } else {
+      // pre-computed refSet was provided as configuration option
+      reference = immutableRefSet.find(ref => ref.uri === file.uri);
+    }
+
+    /**
+     * Clone refSet due the dereferencing process being mutable.
+     * We don't want to mutate the original refSet and the references.
+     */
+    if (options.dereference.immutable) {
+      immutableRefSet.refs.map(ref => new Reference({
+        ...ref,
+        value: cloneDeep(ref.value)
+      })).forEach(ref => mutableRefSet.add(ref));
+      reference = mutableRefSet.find(ref => ref.uri === file.uri);
+      refSet = mutableRefSet;
+    }
+    const visitor = new OpenAPI2DereferenceVisitor({
+      reference: reference,
+      namespace,
+      options
+    });
+    const dereferencedElement = await visitAsync(refSet.rootRef.value, visitor, {
+      keyMap,
+      nodeTypeGetter: getNodeType
+    });
+
+    /**
+     * If immutable option is set, replay refs from the refSet.
+     */
+    if (options.dereference.immutable) {
+      mutableRefSet.refs.filter(ref => ref.uri.startsWith('immutable://')).map(ref => new Reference({
+        ...ref,
+        uri: ref.uri.replace(/^immutable:\/\//, '')
+      })).forEach(ref => immutableRefSet.add(ref));
+      reference = immutableRefSet.find(ref => ref.uri === file.uri);
+      refSet = immutableRefSet;
+    }
+
+    /**
+     * Release all memory if this refSet was not provided as a configuration option.
+     * If provided as configuration option, then provider is responsible for cleanup.
+     */
+    if (options.dereference.refSet === null) {
+      immutableRefSet.clean();
+    }
+    mutableRefSet.clean();
+    return dereferencedElement;
+  }
+}
+export { OpenAPI2DereferenceVisitor };
+export default OpenAPI2DereferenceStrategy;