@speclynx/apidom-reference 4.14.0 → 4.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-reference",
-  "version": "4.14.0",
+  "version": "4.15.0",
   "description": "Advanced algorithms for semantic ApiDOM manipulations like dereferencing or resolution.",
   "keywords": [
     "apidom",
@@ -263,6 +263,11 @@
       "import": "./src/bundle/strategies/openapi-3-1/index.mjs",
       "require": "./src/bundle/strategies/openapi-3-1/index.cjs",
       "types": "./types/bundle/strategies/openapi-3-1/index.d.ts"
+    },
+    "./bundle/strategies/arazzo-1": {
+      "import": "./src/bundle/strategies/arazzo-1/index.mjs",
+      "require": "./src/bundle/strategies/arazzo-1/index.cjs",
+      "types": "./types/bundle/strategies/arazzo-1/index.d.ts"
     }
   },
   "scripts": {
@@ -289,32 +294,32 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime-corejs3": "^8.0.0",
-    "@speclynx/apidom-core": "4.14.0",
-    "@speclynx/apidom-datamodel": "4.14.0",
-    "@speclynx/apidom-error": "4.14.0",
-    "@speclynx/apidom-json-pointer": "4.14.0",
-    "@speclynx/apidom-ns-arazzo-1": "4.14.0",
-    "@speclynx/apidom-ns-asyncapi-2": "4.14.0",
-    "@speclynx/apidom-ns-json-schema-2020-12": "4.14.0",
-    "@speclynx/apidom-ns-openapi-2": "4.14.0",
-    "@speclynx/apidom-ns-openapi-3-0": "4.14.0",
-    "@speclynx/apidom-ns-openapi-3-1": "4.14.0",
-    "@speclynx/apidom-ns-overlay-1": "4.14.0",
-    "@speclynx/apidom-parser-adapter-arazzo-json-1": "4.14.0",
-    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "4.14.0",
-    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "4.14.0",
-    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "4.14.0",
-    "@speclynx/apidom-parser-adapter-json": "4.14.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-2": "4.14.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "4.14.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "4.14.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "4.14.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "4.14.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "4.14.0",
-    "@speclynx/apidom-parser-adapter-overlay-json-1": "4.14.0",
-    "@speclynx/apidom-parser-adapter-overlay-yaml-1": "4.14.0",
-    "@speclynx/apidom-parser-adapter-yaml-1-2": "4.14.0",
-    "@speclynx/apidom-traverse": "4.14.0",
+    "@speclynx/apidom-core": "4.15.0",
+    "@speclynx/apidom-datamodel": "4.15.0",
+    "@speclynx/apidom-error": "4.15.0",
+    "@speclynx/apidom-json-pointer": "4.15.0",
+    "@speclynx/apidom-ns-arazzo-1": "4.15.0",
+    "@speclynx/apidom-ns-asyncapi-2": "4.15.0",
+    "@speclynx/apidom-ns-json-schema-2020-12": "4.15.0",
+    "@speclynx/apidom-ns-openapi-2": "4.15.0",
+    "@speclynx/apidom-ns-openapi-3-0": "4.15.0",
+    "@speclynx/apidom-ns-openapi-3-1": "4.15.0",
+    "@speclynx/apidom-ns-overlay-1": "4.15.0",
+    "@speclynx/apidom-parser-adapter-arazzo-json-1": "4.15.0",
+    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "4.15.0",
+    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "4.15.0",
+    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "4.15.0",
+    "@speclynx/apidom-parser-adapter-json": "4.15.0",
+    "@speclynx/apidom-parser-adapter-openapi-json-2": "4.15.0",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "4.15.0",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "4.15.0",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "4.15.0",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "4.15.0",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "4.15.0",
+    "@speclynx/apidom-parser-adapter-overlay-json-1": "4.15.0",
+    "@speclynx/apidom-parser-adapter-overlay-yaml-1": "4.15.0",
+    "@speclynx/apidom-parser-adapter-yaml-1-2": "4.15.0",
+    "@speclynx/apidom-traverse": "4.15.0",
     "@swaggerexpert/arazzo-runtime-expression": "^2.0.3",
     "axios": "^1.18.0",
     "picomatch": "^4.0.4",
@@ -336,5 +341,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "ae231056cc8865f2467fa97ca456975301bbe265"
+  "gitHead": "a3f6734745e3f4bee9c4121ebebbf2e9dbf6bc68"
 }

package/src/bundle/strategies/arazzo-1/index.cjs

@@ -0,0 +1,94 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "Arazzo1BundleVisitor", {
+  enumerable: true,
+  get: function () {
+    return _visitor.default;
+  }
+});
+exports.default = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomTraverse = require("@speclynx/apidom-traverse");
+var _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
+var _Reference = _interopRequireDefault(require("../../../Reference.cjs"));
+var _ReferenceSet = _interopRequireDefault(require("../../../ReferenceSet.cjs"));
+var _BundleStrategy = _interopRequireDefault(require("../BundleStrategy.cjs"));
+var _visitor = _interopRequireDefault(require("./visitor.cjs"));
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class Arazzo1BundleStrategy extends _BundleStrategy.default {
+  constructor(options) {
+    super({
+      ...(options ?? {}),
+      name: 'arazzo-1'
+    });
+  }
+  canBundle(file) {
+    // assert by media type
+    if (file.mediaType !== 'text/plain') {
+      return _apidomNsArazzo.mediaTypes.includes(file.mediaType);
+    }
+
+    // assert by inspecting ApiDOM
+    return (0, _apidomNsArazzo.isArazzoSpecification1Element)(file.parseResult?.result);
+  }
+  async bundle(file, options) {
+    const immutableRefSet = options.bundle.refSet ?? new _ReferenceSet.default();
+    const mutableRefSet = new _ReferenceSet.default();
+    let refSet = immutableRefSet;
+    let reference;
+
+    // determine the initial 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 bundling process being mutable.
+     * We don't want to mutate the original refSet and the references.
+     */
+    if (options.bundle.immutable) {
+      immutableRefSet.refs.map(ref => new _Reference.default({
+        ...ref,
+        value: (0, _apidomDatamodel.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,
+      options
+    });
+    await (0, _apidomTraverse.traverseAsync)(refSet.rootRef.value, visitor, {
+      mutable: true
+    });
+    const parseResult = reference.value;
+
+    /**
+     * 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.bundle.refSet === null) {
+      immutableRefSet.clean();
+    }
+    mutableRefSet.clean();
+    return parseResult;
+  }
+}
+var _default = exports.default = Arazzo1BundleStrategy;

package/src/bundle/strategies/arazzo-1/index.mjs

@@ -0,0 +1,81 @@
+import { cloneDeep } from '@speclynx/apidom-datamodel';
+import { traverseAsync } from '@speclynx/apidom-traverse';
+import { mediaTypes, isArazzoSpecification1Element } from '@speclynx/apidom-ns-arazzo-1';
+import Reference from "../../../Reference.mjs";
+import ReferenceSet from "../../../ReferenceSet.mjs";
+import BundleStrategy from "../BundleStrategy.mjs";
+import Arazzo1BundleVisitor from "./visitor.mjs";
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+class Arazzo1BundleStrategy extends BundleStrategy {
+  constructor(options) {
+    super({
+      ...(options ?? {}),
+      name: 'arazzo-1'
+    });
+  }
+  canBundle(file) {
+    // assert by media type
+    if (file.mediaType !== 'text/plain') {
+      return mediaTypes.includes(file.mediaType);
+    }
+
+    // assert by inspecting ApiDOM
+    return isArazzoSpecification1Element(file.parseResult?.result);
+  }
+  async bundle(file, options) {
+    const immutableRefSet = options.bundle.refSet ?? new ReferenceSet();
+    const mutableRefSet = new ReferenceSet();
+    let refSet = immutableRefSet;
+    let reference;
+
+    // determine the initial 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 bundling process being mutable.
+     * We don't want to mutate the original refSet and the references.
+     */
+    if (options.bundle.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 Arazzo1BundleVisitor({
+      reference: reference,
+      options
+    });
+    await traverseAsync(refSet.rootRef.value, visitor, {
+      mutable: true
+    });
+    const parseResult = reference.value;
+
+    /**
+     * 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.bundle.refSet === null) {
+      immutableRefSet.clean();
+    }
+    mutableRefSet.clean();
+    return parseResult;
+  }
+}
+export { Arazzo1BundleVisitor };
+export default Arazzo1BundleStrategy;

package/src/bundle/strategies/arazzo-1/visitor.cjs

@@ -0,0 +1,417 @@
+"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 _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
+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 _EvaluationJsonSchemaUriError = _interopRequireDefault(require("../../../errors/EvaluationJsonSchemaUriError.cjs"));
+var url = _interopRequireWildcard(require("../../../util/url.cjs"));
+var _index = _interopRequireDefault(require("../../../parse/index.cjs"));
+var _Reference = _interopRequireDefault(require("../../../Reference.cjs"));
+var _File = _interopRequireDefault(require("../../../File.cjs"));
+var _$anchor = require("../../../dereference/strategies/arazzo-1/selectors/$anchor.cjs");
+var _uri = require("../../../dereference/strategies/arazzo-1/selectors/uri.cjs");
+var _util = require("../../../dereference/strategies/arazzo-1/util.cjs");
+var _util2 = require("../../util.cjs");
+/**
+ * The Components Object field where embedded JSON Schema resources are hoisted.
+ * Sourced from the Components Object fixed fields so it cannot drift from the
+ * namespace definition.
+ */
+const cf = (0, _apidomCore.fixedFields)(_apidomNsArazzo.ComponentsElement, {
+  indexed: true
+});
+
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class Arazzo1BundleVisitor {
+  reference;
+  options;
+
+  /**
+   * The entry parse result. Derived from the shared refSet's root reference.
+   */
+  get entryParseResult() {
+    return this.reference.refSet.rootRef.value;
+  }
+
+  /**
+   * The entry document element. Embedded external schema resources are placed
+   * into its `components.inputs` object. The `canBundle` guard guarantees it is
+   * an ArazzoSpecification1Element.
+   */
+  get entryResult() {
+    return this.entryParseResult.result;
+  }
+
+  /**
+   * Shared across the entry document and every external document visitor.
+   * Guarantees each external resource is embedded exactly once, keyed by its
+   * resource URI.
+   */
+  assignments;
+
+  /**
+   * Component names already reserved per Components Object field. Reserved
+   * before recursion so collision suffixing (`Pet`, `Pet-2`, ...) accounts for
+   * components that are still being bundled.
+   */
+  reservedNames;
+  constructor({
+    reference,
+    options,
+    assignments = new Map(),
+    reservedNames = new Map()
+  }) {
+    this.reference = reference;
+    this.options = options;
+    this.assignments = assignments;
+    this.reservedNames = reservedNames;
+  }
+  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(ref => ref.uri === baseURI);
+    }
+    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;
+  }
+
+  /**
+   * 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 Components Object (and the `inputs` field within it) on
+   * the entry document, returning the field where a resource is embedded.
+   */
+  ensureInputsField() {
+    const entryResult = this.entryResult;
+    let components = entryResult.components;
+    if (!(0, _apidomDatamodel.isObjectElement)(components)) {
+      components = new _apidomNsArazzo.ComponentsElement();
+      entryResult.components = components;
+    }
+    let inputs = components.get(cf.inputs.name);
+    if (!(0, _apidomDatamodel.isObjectElement)(inputs)) {
+      inputs = new _apidomNsArazzo.ComponentsInputsElement();
+      components.set(cf.inputs.name, inputs);
+    }
+    return inputs;
+  }
+
+  /**
+   * Computes the base component name (before collision suffixing) according to
+   * the configured naming strategy.
+   */
+  baseName(element, baseURI) {
+    // strategy specific options take precedence over the top-level bundle options
+    const componentNamesStrategy = this.options.bundle.strategyOpts['arazzo-1']?.componentNamesStrategy ?? this.options.bundle.componentNamesStrategy;
+    const fallback = url.getBasename(baseURI) || 'Schema';
+    if (typeof componentNamesStrategy === 'function') {
+      const resolved = componentNamesStrategy({
+        element,
+        field: cf.inputs.name,
+        jsonPointer: '',
+        baseURI
+      });
+      if (typeof resolved === 'string' && resolved !== '') {
+        return resolved;
+      }
+      return fallback;
+    }
+    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, _util2.sanitizeComponentName)((0, _util2.toPascalCase)(title));
+        if (name !== '') return name;
+      }
+      // fall back to basename when no usable title is present
+    }
+    return fallback;
+  }
+
+  /**
+   * Computes a collision-free component name within `components.inputs`. A name
+   * is taken if it's already placed in inputs or reserved by a component that is
+   * still being bundled (reserved before recursion).
+   */
+  uniqueName(candidate) {
+    const field = cf.inputs.name;
+    const inputs = this.ensureInputsField();
+    const reserved = this.reservedNames.get(field) ?? new Set();
+    return (0, _util2.uniqueName)(candidate, name => inputs.hasKey(name) || reserved.has(name));
+  }
+
+  /**
+   * Reports a collision-forced rename according to the configured severity.
+   * A rename means two distinct targets resolved to the same name; each keeps
+   * its own component (and origin), so report the rename per severity.
+   */
+  reportNameCollision(preferredName, componentName) {
+    // strategy specific options take precedence over the top-level bundle options
+    const onComponentNameCollision = this.options.bundle.strategyOpts['arazzo-1']?.onComponentNameCollision ?? this.options.bundle.onComponentNameCollision;
+    if (componentName === preferredName || onComponentNameCollision === 'off') {
+      return;
+    }
+    const message = `Component "${preferredName}" in components/${cf.inputs.name} 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);
+  }
+
+  /**
+   * JSON Schema Objects in Arazzo (used by Input Objects and inline schemas) are
+   * a JSON Schema 2020-12 dialect — the only external reference type Arazzo
+   * defines. They are bundled per the JSON Schema Compound Document rules: the
+   * external schema RESOURCE is embedded verbatim into `components.inputs`
+   * (carrying its `$id`), and the referencing `$ref` is left UNCHANGED — it
+   * keeps resolving against the embedded resource's `$id`. This mirrors the
+   * openapi-3-1 strategy's Schema Object handling.
+   */
+  async JSONSchemaElement(path) {
+    const referencingElement = path.node;
+
+    // skip current referencing schema as $ref keyword was not defined
+    if (!(0, _apidomDatamodel.isStringElement)(referencingElement.$ref)) {
+      return;
+    }
+    const $ref = (0, _apidomCore.toValue)(referencingElement.$ref);
+    try {
+      // compute baseURI using rules around $id and $ref keywords. The current
+      // document's URI is the retrieval URI — derive it directly (not via
+      // toReference) so an internal $ref needs no resolution and never trips the
+      // resolve.maxDepth guard.
+      const retrievalURI = this.reference.uri;
+      const $refBaseURI = (0, _util.resolveSchema$refField)(retrievalURI, referencingElement);
+      const $refBaseURIStrippedHash = url.stripHash($refBaseURI);
+      const file = new _File.default({
+        uri: $refBaseURIStrippedHash
+      });
+      const isUnknownURI = (0, _ramda.none)(r => r.canRead(file), this.options.resolve.resolvers);
+      const isURL = !isUnknownURI;
+      const isInternalReference = url.stripHash(this.reference.uri) === $refBaseURIStrippedHash;
+      const isExternalReference = !isInternalReference;
+
+      // internal Schema Object $refs resolve against the in-document $id graph;
+      // leaving them untouched keeps that resolution valid. A JSON Schema $ref is
+      // never normalized to a bare fragment.
+      if (isInternalReference) {
+        return;
+      }
+
+      // honor the resolve.external switch
+      if (!this.options.resolve.external && isExternalReference) {
+        return;
+      }
+
+      // detect maximum depth of bundling before fetching the external resource
+      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
+        });
+      }
+
+      // locate the external schema resource the $ref targets, reusing the
+      // dereference strategy's classification. First try to resolve the target
+      // as a canonical URI / URL against the current document's $id graph; if
+      // that fails, fall back to fetching the external document and resolving
+      // the fragment there as a $anchor or JSON Pointer.
+      let schemaReference = this.reference;
+      try {
+        const referenceAsSchema = (0, _util.maybeRefractToJSONSchemaElement)(schemaReference.value.result);
+        (0, _uri.evaluate)($refBaseURI, referenceAsSchema);
+      } catch (error) {
+        if (isURL && error instanceof _EvaluationJsonSchemaUriError.default) {
+          if ((0, _$anchor.isAnchor)((0, _$anchor.uriToAnchor)($refBaseURI))) {
+            schemaReference = await this.toReference(url.unsanitize($refBaseURI));
+            const selector = (0, _$anchor.uriToAnchor)($refBaseURI);
+            const referenceAsSchema = (0, _util.maybeRefractToJSONSchemaElement)(schemaReference.value.result);
+            (0, _$anchor.evaluate)(selector, referenceAsSchema);
+          } else {
+            schemaReference = await this.toReference(url.unsanitize($refBaseURI));
+            const selector = _apidomJsonPointer.URIFragmentIdentifier.fromURIReference($refBaseURI);
+            const referenceAsSchema = (0, _util.maybeRefractToJSONSchemaElement)(schemaReference.value.result);
+            (0, _apidomJsonPointer.evaluate)(referenceAsSchema, selector);
+          }
+        } else {
+          throw error;
+        }
+      }
+
+      // a $ref that resolves (by $id/$anchor/pointer) within the current document
+      // is internal even when its URI form (e.g. a URN or absolute $id) is not a
+      // bare fragment. Leave it untouched — it resolves against the in-document
+      // $id graph, and embedding the current document into itself would be wrong.
+      if (url.stripHash(schemaReference.uri) === url.stripHash(this.reference.uri)) {
+        return;
+      }
+
+      // the resource to embed is the WHOLE external document (its root schema),
+      // identified by its $id. A $ref into a fragment of the document embeds the
+      // entire document resource once; the fragment keeps resolving against the
+      // embedded $id.
+      const resourceRoot = (0, _util.maybeRefractToJSONSchemaElement)(schemaReference.value.result);
+      const resourceBaseURI = (0, _util.resolveSchema$idField)(url.stripHash(schemaReference.uri), resourceRoot) ?? url.stripHash(schemaReference.uri);
+      const field = cf.inputs.name;
+      const canonicalKey = `${field}\t${resourceBaseURI}`;
+
+      // resource already embedded (or being embedded) — leave the referencing
+      // $ref untouched and stop. This also terminates circular external schema
+      // references, since the assignment is reserved BEFORE recursion.
+      if (this.assignments.has(canonicalKey)) {
+        path.skip();
+        return;
+      }
+
+      // own a copy of the resource and ensure it carries a $id so the unchanged
+      // $ref still resolves against it once embedded
+      const embeddedElement = (0, _apidomDatamodel.cloneDeep)(resourceRoot);
+      if (!(0, _apidomDatamodel.isStringElement)(embeddedElement.$id)) {
+        embeddedElement.set('$id', resourceBaseURI);
+      }
+
+      // the embedded thing is the WHOLE resource (keyed by its $id), so its name
+      // is derived from the resource URI
+      const preferredName = this.baseName(embeddedElement, resourceBaseURI);
+      const componentName = this.uniqueName(preferredName);
+      this.reportNameCollision(preferredName, componentName);
+
+      // reserve the assignment and component name before recursing so circular
+      // external schema references terminate
+      this.assignments.set(canonicalKey, `#/components/${field}/${(0, _apidomJsonPointer.escape)(componentName)}`);
+      if (!this.reservedNames.has(field)) this.reservedNames.set(field, new Set());
+      this.reservedNames.get(field).add(componentName);
+
+      // bundle external references contained within the embedded resource;
+      // nested external resources land flat in the same components.inputs
+      const visitor = new Arazzo1BundleVisitor({
+        reference: schemaReference,
+        options: this.options,
+        assignments: this.assignments,
+        reservedNames: this.reservedNames
+      });
+      const bundledElement = await (0, _apidomTraverse.traverseAsync)(embeddedElement, visitor, {
+        mutable: true
+      });
+
+      // annotate the embedded resource with info about its origin
+      if ((0, _apidomDatamodel.isElement)(bundledElement)) {
+        bundledElement.meta.set('ref-origin', schemaReference.uri);
+      }
+
+      // place the embedded resource into the entry document's components.inputs
+      this.ensureInputsField().set(componentName, bundledElement);
+
+      // the referencing $ref is left UNCHANGED — it resolves against the
+      // embedded resource's $id
+      path.skip();
+    } catch (error) {
+      this.handleError(`Error while bundling JSON Schema Object. Cannot resolve $ref "${$ref}": ${error.message}`, error, referencingElement, '$ref', $ref, path);
+      path.skip();
+    }
+  }
+}
+var _default = exports.default = Arazzo1BundleVisitor;