@speclynx/apidom-reference 4.12.0 → 4.13.0

package/src/bundle/strategies/openapi-2/visitor.cjs

@@ -0,0 +1,567 @@
+"use strict";
+
+var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _ramda = require("ramda");
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomCore = require("@speclynx/apidom-core");
+var _apidomTraverse = require("@speclynx/apidom-traverse");
+var _apidomJsonPointer = require("@speclynx/apidom-json-pointer");
+var _apidomNsOpenapi = require("@speclynx/apidom-ns-openapi-2");
+var _BundleError = _interopRequireDefault(require("../../../errors/BundleError.cjs"));
+var _UnresolvableReferenceError = _interopRequireDefault(require("../../../errors/UnresolvableReferenceError.cjs"));
+var _MaximumBundleDepthError = _interopRequireDefault(require("../../../errors/MaximumBundleDepthError.cjs"));
+var _MaximumResolveDepthError = _interopRequireDefault(require("../../../errors/MaximumResolveDepthError.cjs"));
+var url = _interopRequireWildcard(require("../../../util/url.cjs"));
+var _index = _interopRequireDefault(require("../../../parse/index.cjs"));
+var _Reference = _interopRequireDefault(require("../../../Reference.cjs"));
+var _util = require("../../util.cjs");
+/**
+ * Maps the `referenced-element` meta value (set during refraction) to the
+ * top-level Swagger Object field where the referenced element should be
+ * hoisted. Unlike OpenAPI 3.x, OpenAPI 2.0 has no single Components Object;
+ * reusable definitions live directly under the document root. Field names are
+ * sourced from the Swagger Object fixed fields so they cannot drift from the
+ * namespace definition.
+ */
+const sf = (0, _apidomCore.fixedFields)(_apidomNsOpenapi.SwaggerElement, {
+  indexed: true
+});
+const fieldByReferencedElement = {
+  schema: sf.definitions.name,
+  parameter: sf.parameters.name,
+  response: sf.responses.name
+};
+
+/**
+ * Maps a top-level Swagger Object field to the named-content element the
+ * namespace uses for it, so a bundle-created field matches a parsed/refracted
+ * one (e.g. carries the `definitions` class) rather than being a generic
+ * object.
+ */
+const fieldElementByField = {
+  [sf.definitions.name]: _apidomNsOpenapi.DefinitionsElement,
+  [sf.parameters.name]: _apidomNsOpenapi.ParametersDefinitionsElement,
+  [sf.responses.name]: _apidomNsOpenapi.ResponsesDefinitionsElement
+};
+
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class OpenAPI2BundleVisitor {
+  reference;
+  options;
+
+  /**
+   * The base URI (without hash) of the entry document. A reference is
+   * considered internal when it resolves to this URI and external otherwise.
+   * Derived from the shared refSet's root reference.
+   */
+  get entryURI() {
+    return url.stripHash(this.reference.refSet?.rootRef?.uri ?? '');
+  }
+
+  /**
+   * The entry parse result. Derived from the shared refSet's root reference.
+   */
+  get entryParseResult() {
+    return this.reference.refSet.rootRef.value;
+  }
+
+  /**
+   * The entry document element. Hoisted external fragments are placed into its
+   * top-level definition fields. The `canBundle` guard guarantees it is a
+   * SwaggerElement.
+   */
+  get entryResult() {
+    return this.entryParseResult.result;
+  }
+
+  /**
+   * Shared across the entry document and every external document visitor.
+   * Guarantees each external fragment is hoisted exactly once and gives us a
+   * stable internal pointer to rewrite every referencing element to.
+   */
+  assignments;
+
+  /**
+   * Component names already reserved per definition field. Reserved before
+   * recursion so collision suffixing (`Pet`, `Pet-2`, ...) accounts for
+   * components that are still being bundled.
+   */
+  reservedNames;
+
+  /**
+   * Caches refracted fragments keyed by source element and target element type.
+   * The type is part of the key because the same source can be refracted into
+   * different semantic elements depending on the referencing context (e.g. a
+   * generic object referenced once as a Parameter and once as a Response).
+   */
+  refractCache;
+
+  /**
+   * Canonical URIs of Path Item Objects currently being inlined. Path Items
+   * are not a top-level definition field in OpenAPI 2.0, so the `assignments`
+   * map can't break their cycles. This stack guards against circular external
+   * Path Item references.
+   */
+  inlineStack;
+  constructor({
+    reference,
+    options,
+    assignments = new Map(),
+    reservedNames = new Map(),
+    refractCache = new WeakMap(),
+    inlineStack = new Set()
+  }) {
+    this.reference = reference;
+    this.options = options;
+    this.inlineStack = inlineStack;
+    this.assignments = assignments;
+    this.reservedNames = reservedNames;
+    this.refractCache = refractCache;
+  }
+  getRefracted(source, type) {
+    return this.refractCache.get(source)?.get(type);
+  }
+  setRefracted(source, type, refracted) {
+    let byType = this.refractCache.get(source);
+    if (byType === undefined) {
+      byType = new Map();
+      this.refractCache.set(source, byType);
+    }
+    byType.set(type, refracted);
+  }
+  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.default(`Maximum resolution depth of ${this.options.resolve.maxDepth} has been exceeded by file "${this.reference.uri}"`, {
+        maxDepth: this.options.resolve.maxDepth,
+        uri: 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((0, _ramda.propEq)(baseURI, 'uri'));
+    }
+    const parseResult = await (0, _index.default)(url.unsanitize(baseURI), {
+      ...this.options,
+      parse: {
+        ...this.options.parse,
+        mediaType: 'text/plain'
+      }
+    });
+    const reference = new _Reference.default({
+      uri: baseURI,
+      value: parseResult,
+      depth: this.reference.depth + 1
+    });
+    refSet.add(reference);
+    return reference;
+  }
+
+  /**
+   * Normalizes a self-file reference (e.g. `./root.json#/definitions/Pet`)
+   * to a bare fragment (`#/definitions/Pet`) so the bundled document stays
+   * transferable. Bare fragments are returned unchanged.
+   */
+  normalizeSelfFileRef(ref) {
+    return ref.startsWith('#') ? ref : url.getHash(ref);
+  }
+
+  /**
+   * Handles an error according to the `bundle.continueOnError` option.
+   *
+   * For new errors: wraps in UnresolvableReferenceError with structured
+   * context. For errors already wrapped by a nested visitor: prepends the
+   * current hop to the trace.
+   *
+   * Inner/intermediate visitors always throw to let the trace accumulate. Only
+   * the entry document visitor respects continueOnError (callback/swallow/throw).
+   */
+  handleError(message, error, referencingElement, refFieldName, refFieldValue, visitorPath) {
+    // a collision reported as `error` is a deliberate hard stop with no
+    // resolution-failure analog, so pass it through unchanged. A maxDepth
+    // breach (MaximumBundleDepthError, which also extends BundleError) is a
+    // resolution failure and flows through below — wrapped and subject to
+    // continueOnError, like dereferencing.
+    if (error instanceof _BundleError.default && !(error instanceof _MaximumBundleDepthError.default)) {
+      throw error;
+    }
+    const {
+      continueOnError
+    } = this.options.bundle;
+    const isEntryDocument = url.stripHash(this.reference.refSet?.rootRef?.uri ?? '') === this.reference.uri;
+    const uri = this.reference.uri;
+    const type = referencingElement.element;
+    const codeFrame = (0, _apidomCore.toYAML)(referencingElement);
+    const location = visitorPath.formatPath();
+    const hop = {
+      uri,
+      type,
+      refFieldName,
+      refFieldValue,
+      location,
+      codeFrame
+    };
+    let unresolvedError;
+    if (error instanceof _UnresolvableReferenceError.default) {
+      // @ts-ignore
+      error.trace = [hop, ...error.trace];
+      unresolvedError = error;
+    } else {
+      unresolvedError = new _UnresolvableReferenceError.default(message, {
+        cause: error,
+        type,
+        uri,
+        location,
+        codeFrame,
+        refFieldName,
+        refFieldValue,
+        trace: []
+      });
+    }
+    if (!isEntryDocument || continueOnError === false) throw unresolvedError;
+    if (typeof continueOnError === 'function') continueOnError(unresolvedError);
+  }
+
+  /**
+   * Lazily creates the requested top-level definition field on the entry
+   * document, returning the field where a fragment is hoisted.
+   */
+  ensureField(field) {
+    const entryResult = this.entryResult;
+    let fieldElement = entryResult.get(field);
+    if (!(0, _apidomDatamodel.isObjectElement)(fieldElement)) {
+      const FieldElement = fieldElementByField[field] ?? _apidomDatamodel.ObjectElement;
+      fieldElement = new FieldElement();
+      entryResult.set(field, fieldElement);
+    }
+    return fieldElement;
+  }
+
+  /**
+   * Derives a component name from the referenced JSON Pointer's last token,
+   * falling back to the referenced file's basename.
+   */
+  basenameOf(jsonPointer, baseURI) {
+    const tokens = (0, _apidomJsonPointer.parse)(jsonPointer).tree;
+    let candidate = tokens.length > 0 ? tokens[tokens.length - 1] : '';
+    if (candidate === '') {
+      const lastSlash = baseURI.lastIndexOf('/');
+      const lastDot = baseURI.lastIndexOf('.');
+      const fileName = baseURI.slice(lastSlash + 1);
+      // strip the extension only when the last dot belongs to the file name
+      candidate = lastDot > lastSlash ? baseURI.slice(lastSlash + 1, lastDot) : fileName;
+    }
+    if (candidate === '') candidate = 'Schema';
+    return candidate;
+  }
+
+  /**
+   * Computes the base component name (before collision suffixing) according to
+   * the configured naming strategy.
+   */
+  baseName(element, field, jsonPointer, baseURI) {
+    // strategy specific options take precedence over the top-level bundle options
+    const componentNamesStrategy = this.options.bundle.strategyOpts['openapi-2']?.componentNamesStrategy ?? this.options.bundle.componentNamesStrategy;
+    if (typeof componentNamesStrategy === 'function') {
+      const resolved = componentNamesStrategy({
+        element,
+        field,
+        jsonPointer,
+        baseURI
+      });
+      if (typeof resolved === 'string' && resolved !== '') {
+        return resolved;
+      }
+      return this.basenameOf(jsonPointer, baseURI);
+    }
+    if (componentNamesStrategy === 'title') {
+      const title = (0, _apidomDatamodel.isObjectElement)(element) ? (0, _apidomCore.toValue)(element.get('title')) : undefined;
+      if (typeof title === 'string' && title.trim() !== '') {
+        const name = (0, _util.sanitizeComponentName)((0, _util.toPascalCase)(title));
+        if (name !== '') return name;
+      }
+      // fall back to basename when no usable title is present
+    }
+    return this.basenameOf(jsonPointer, baseURI);
+  }
+
+  /**
+   * Computes a collision-free component name within the target field. A name is
+   * taken if it's already placed in the field or reserved by a component that
+   * is still being bundled (reserved before recursion).
+   */
+  uniqueName(candidate, field) {
+    const fieldElement = this.ensureField(field);
+    const reserved = this.reservedNames.get(field) ?? new Set();
+    return (0, _util.uniqueName)(candidate, name => fieldElement.hasKey(name) || reserved.has(name));
+  }
+
+  /**
+   * Bundles a Reference Object (parameters/responses) or a JSON Reference
+   * Object (schemas). The two reference flavors differ only in their predicate
+   * and refraction helpers, so the shared logic is parameterized here.
+   */
+  async bundleReference(path, referencingElement, isSemanticReference, isReferenceLike, refractReferenceFn, label) {
+    const $ref = (0, _apidomCore.toValue)(referencingElement.$ref);
+    const retrievalURI = this.toBaseURI($ref);
+    const isInternalReference = this.entryURI === retrievalURI;
+    const isExternalReference = !isInternalReference;
+    if (isInternalReference) {
+      // normalize self-file references to a bare fragment so the bundled
+      // document stays transferable; bare fragments are left untouched
+      referencingElement.set('$ref', this.normalizeSelfFileRef($ref));
+      path.skip();
+      return;
+    }
+
+    // honor the resolve.external switch
+    if (!this.options.resolve.external && isExternalReference) {
+      path.skip();
+      return;
+    }
+    const $refBaseURI = url.resolve(retrievalURI, $ref);
+    const jsonPointer = _apidomJsonPointer.URIFragmentIdentifier.fromURIReference($refBaseURI);
+
+    // the target field depends on the referencing context, so it's part of the
+    // identity: the same external target referenced as e.g. both a parameter and
+    // a response must be hoisted into both fields. The refractor sets
+    // `referenced-element` for every Reference Object position; the `schema`
+    // fallback is a defensive default for the (unexpected) untagged case.
+    const referencedElementType = referencingElement.meta.get('referenced-element');
+    const field = fieldByReferencedElement[referencedElementType] ?? fieldByReferencedElement.schema;
+    const canonicalKey = `${field}\t${retrievalURI}#${jsonPointer}`;
+
+    // already hoisted (or being hoisted) — just rewrite the pointer.
+    //
+    // this is also how circular references terminate: the assignment is
+    // reserved BEFORE recursing into the fragment (see below), so a reference
+    // that cycles back (directly or indirectly) finds its pointer already
+    // reserved here and is rewritten without recursing. Cycles are deliberately
+    // preserved as internal `$ref`s pointing at each other — that is valid,
+    // serializable output; resolving the cycle (if desired) is dereferencing's
+    // job, not bundling's.
+    if (this.assignments.has(canonicalKey)) {
+      referencingElement.set('$ref', this.assignments.get(canonicalKey));
+      path.skip();
+      return;
+    }
+    try {
+      // detect maximum depth of bundling
+      if (this.reference.depth >= this.options.bundle.maxDepth) {
+        throw new _MaximumBundleDepthError.default(`Maximum bundle depth of "${this.options.bundle.maxDepth}" has been exceeded in file "${this.reference.uri}"`, {
+          maxDepth: this.options.bundle.maxDepth,
+          uri: this.reference.uri
+        });
+      }
+      const reference = await this.toReference($ref);
+
+      // possibly non-semantic fragment
+      let referencedElement = (0, _apidomJsonPointer.evaluate)(reference.value.result, jsonPointer);
+
+      // apply semantics to the fragment so nested references become Reference Objects
+      if (referencedElement.element !== referencedElementType && !isSemanticReference(referencedElement)) {
+        const cached = this.getRefracted(referencedElement, referencedElementType);
+        if (cached !== undefined) {
+          referencedElement = cached;
+        } else if (isReferenceLike(referencedElement)) {
+          const sourceElement = referencedElement;
+          referencedElement = refractReferenceFn(referencedElement);
+          referencedElement.meta.set('referenced-element', referencedElementType);
+          this.setRefracted(sourceElement, referencedElementType, referencedElement);
+        } else {
+          const sourceElement = referencedElement;
+          referencedElement = (0, _apidomNsOpenapi.refract)(referencedElement, {
+            element: referencedElementType
+          });
+          this.setRefracted(sourceElement, referencedElementType, referencedElement);
+        }
+      }
+      const preferredName = this.baseName(referencedElement, field, jsonPointer, retrievalURI);
+      const componentName = this.uniqueName(preferredName, field);
+      const internalPointer = `#/${field}/${(0, _apidomJsonPointer.escape)(componentName)}`;
+
+      // a rename means two distinct targets resolved to the same name; each
+      // keeps its own component (and origin), so report the rename per severity.
+      // strategy specific options take precedence over the top-level bundle options
+      const onComponentNameCollision = this.options.bundle.strategyOpts['openapi-2']?.onComponentNameCollision ?? this.options.bundle.onComponentNameCollision;
+      if (componentName !== preferredName && onComponentNameCollision !== 'off') {
+        const message = `Component "${preferredName}" in ${field} is referenced with the same name but different content. Renamed to "${componentName}".`;
+        if (onComponentNameCollision === 'error') {
+          throw new _BundleError.default(message);
+        }
+        const annotation = new _apidomDatamodel.AnnotationElement(message);
+        annotation.classes.push('warning');
+        annotation.code = 'bundle-component-name-collision';
+        // append (never prepend) so the result element stays ahead of annotations
+        this.entryParseResult.content.push(annotation);
+      }
+
+      // reserve the assignment and component name before recursing so cyclic
+      // references terminate
+      this.assignments.set(canonicalKey, internalPointer);
+      if (!this.reservedNames.has(field)) this.reservedNames.set(field, new Set());
+      this.reservedNames.get(field).add(componentName);
+
+      // own a copy of the fragment and bundle its own external references
+      const hoistedElement = (0, _apidomDatamodel.cloneDeep)(referencedElement);
+      const visitor = new OpenAPI2BundleVisitor({
+        reference,
+        options: this.options,
+        assignments: this.assignments,
+        reservedNames: this.reservedNames,
+        refractCache: this.refractCache,
+        inlineStack: this.inlineStack
+      });
+      const bundledElement = await (0, _apidomTraverse.traverseAsync)(hoistedElement, visitor, {
+        mutable: true
+      });
+
+      // annotate the hoisted fragment with info about its origin
+      if ((0, _apidomDatamodel.isElement)(bundledElement)) {
+        bundledElement.meta.set('ref-origin', reference.uri);
+      }
+
+      // place the bundled fragment into the entry document's definitions
+      this.ensureField(field).set(componentName, bundledElement);
+
+      // rewrite the referencing element to point at the hoisted fragment
+      referencingElement.set('$ref', internalPointer);
+      path.skip();
+    } catch (error) {
+      this.handleError(`Error while bundling ${label}. Cannot resolve $ref "${$ref}": ${error.message}`, error, referencingElement, '$ref', $ref, path);
+      path.skip();
+    }
+  }
+
+  /**
+   * Reference Object covers reusable Parameter and Response Objects, which are
+   * hoisted into the top-level `parameters` and `responses` fields.
+   */
+  async ReferenceElement(path) {
+    await this.bundleReference(path, path.node, _apidomNsOpenapi.isReferenceElement, _apidomNsOpenapi.isReferenceLikeElement, _apidomNsOpenapi.refractReference, 'Reference Object');
+  }
+
+  /**
+   * JSON Reference Object covers reusable Schema Objects, which are hoisted
+   * into the top-level `definitions` field.
+   */
+  async JSONReferenceElement(path) {
+    await this.bundleReference(path, path.node, _apidomNsOpenapi.isJSONReferenceElement, _apidomNsOpenapi.isJSONReferenceLikeElement, _apidomNsOpenapi.refractJSONReference, 'JSON Reference Object');
+  }
+
+  /**
+   * Path Item Object is not a top-level definition field in OpenAPI 2.0, so an
+   * external Path Item reference cannot be hoisted; it is inlined in place
+   * instead, after bundling its own external references.
+   */
+  async PathItemElement(path) {
+    const pathItemElement = path.node;
+
+    // ignore Path Item Objects without a $ref field
+    if (!(0, _apidomDatamodel.isStringElement)(pathItemElement.$ref)) {
+      return;
+    }
+    const $ref = (0, _apidomCore.toValue)(pathItemElement.$ref);
+    const retrievalURI = this.toBaseURI($ref);
+    const isInternalReference = this.entryURI === retrievalURI;
+    const isExternalReference = !isInternalReference;
+    if (isInternalReference) {
+      // normalize self-file references to a bare fragment so the bundled
+      // document stays transferable; bare fragments are left untouched
+      pathItemElement.set('$ref', this.normalizeSelfFileRef($ref));
+      return;
+    }
+
+    // honor the resolve.external switch
+    if (!this.options.resolve.external && isExternalReference) {
+      return;
+    }
+    const $refBaseURI = url.resolve(retrievalURI, $ref);
+    const jsonPointer = _apidomJsonPointer.URIFragmentIdentifier.fromURIReference($refBaseURI);
+    const canonicalKey = `${retrievalURI}#${jsonPointer}`;
+
+    // a circular external Path Item reference cannot be inlined without
+    // recursing forever; leave the $ref in place to break the cycle
+    if (this.inlineStack.has(canonicalKey)) {
+      return;
+    }
+    try {
+      // detect maximum depth of bundling
+      if (this.reference.depth >= this.options.bundle.maxDepth) {
+        throw new _MaximumBundleDepthError.default(`Maximum bundle depth of "${this.options.bundle.maxDepth}" has been exceeded in file "${this.reference.uri}"`, {
+          maxDepth: this.options.bundle.maxDepth,
+          uri: this.reference.uri
+        });
+      }
+      const reference = await this.toReference($ref);
+      let referencedElement = (0, _apidomJsonPointer.evaluate)(reference.value.result, jsonPointer);
+
+      // apply Path Item semantics to the referenced fragment
+      if (!(0, _apidomNsOpenapi.isPathItemElement)(referencedElement)) {
+        const cached = this.getRefracted(referencedElement, 'pathItem');
+        if (cached !== undefined) {
+          referencedElement = cached;
+        } else {
+          const sourceElement = referencedElement;
+          referencedElement = (0, _apidomNsOpenapi.refractPathItem)(referencedElement);
+          this.setRefracted(sourceElement, 'pathItem', referencedElement);
+        }
+      }
+
+      // own a copy and bundle the external references it contains
+      const inlinedElement = (0, _apidomDatamodel.cloneDeep)(referencedElement);
+      this.inlineStack.add(canonicalKey);
+      const visitor = new OpenAPI2BundleVisitor({
+        reference,
+        options: this.options,
+        assignments: this.assignments,
+        reservedNames: this.reservedNames,
+        refractCache: this.refractCache,
+        inlineStack: this.inlineStack
+      });
+      let bundledElement;
+      try {
+        bundledElement = await (0, _apidomTraverse.traverseAsync)(inlinedElement, visitor, {
+          mutable: true
+        });
+      } finally {
+        this.inlineStack.delete(canonicalKey);
+      }
+
+      // merge sibling fields from the referencing Path Item over the referenced
+      // one. The referencing `$ref` is being resolved away and is skipped; the
+      // referenced element keeps its own `$ref` if one survived (i.e. it was
+      // left in place to break a circular external Path Item chain).
+      pathItemElement.forEach((_value, keyElement, item) => {
+        const key = (0, _apidomCore.toValue)(keyElement);
+        if (key === '$ref') return;
+        bundledElement.remove(key);
+        bundledElement.content.push(item);
+      });
+      bundledElement.meta.set('ref-origin', reference.uri);
+      path.replaceWith(bundledElement);
+    } catch (error) {
+      this.handleError(`Error while bundling Path Item Object. Cannot resolve $ref "${$ref}": ${error.message}`, error, pathItemElement, '$ref', $ref, path);
+    }
+  }
+}
+var _default = exports.default = OpenAPI2BundleVisitor;