@usearazzo/resolver 1.0.1-alpha.2

package/src/index.mjs

@@ -0,0 +1,9 @@
+export { defaultOptions as defaultDereferenceArazzoOptions, dereference as dereferenceArazzo, dereferenceElement as dereferenceArazzoElement } from "./dereference/arazzo.mjs";
+export { defaultOptions as defaultDereferenceOpenAPIOptions, dereference as dereferenceOpenAPI, dereferenceElement as dereferenceOpenAPIElement } from "./dereference/openapi.mjs";
+export { defaultOptions as defaultResolveArazzoOptions, resolve as resolveArazzo, resolveElement as resolveArazzoElement } from "./resolve/arazzo.mjs";
+export { defaultOptions as defaultResolveOpenAPIOptions, resolve as resolveOpenAPI, resolveElement as resolveOpenAPIElement } from "./resolve/openapi.mjs";
+export { defaultOptions as defaultBundleArazzoOptions, bundle as bundleArazzo } from "./bundle/arazzo.mjs";
+export { defaultOptions as defaultBundleOpenAPIOptions, bundle as bundleOpenAPI } from "./bundle/openapi.mjs";
+export { default as DereferenceError } from "./errors/DereferenceError.mjs";
+export { default as ResolveError } from "./errors/ResolveError.mjs";
+export { default as BundleError } from "./errors/BundleError.mjs";

package/src/resolve/arazzo.cjs

@@ -0,0 +1,208 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.defaultOptions = void 0;
+exports.resolve = resolve;
+exports.resolveElement = resolveElement;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _empty = require("@speclynx/apidom-reference/configuration/empty");
+var _arazzo = _interopRequireDefault(require("@speclynx/apidom-reference/resolve/strategies/arazzo-1"));
+var _openapi = _interopRequireDefault(require("@speclynx/apidom-reference/resolve/strategies/openapi-2"));
+var _openapi2 = _interopRequireDefault(require("@speclynx/apidom-reference/resolve/strategies/openapi-3-0"));
+var _openapi3 = _interopRequireDefault(require("@speclynx/apidom-reference/resolve/strategies/openapi-3-1"));
+var _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
+var _arazzo2 = require("../dereference/arazzo.cjs");
+var _ResolveError = _interopRequireDefault(require("../errors/ResolveError.cjs"));
+/**
+ * Options for resolving Arazzo Documents.
+ * @public
+ */
+
+/**
+ * Default reference options for resolving Arazzo Documents.
+ *
+ * The resolve strategies delegate to the dereference strategies of the same name,
+ * so the dereference defaults are carried over and only the resolve strategies are added.
+ * @public
+ */
+const defaultOptions = exports.defaultOptions = {
+  resolve: {
+    resolvers: [..._arazzo2.defaultOptions.resolve.resolvers],
+    strategies: [new _arazzo.default(), new _openapi.default(), new _openapi2.default(), new _openapi3.default()]
+  },
+  parse: {
+    parsers: [..._arazzo2.defaultOptions.parse.parsers],
+    parserOpts: {
+      ..._arazzo2.defaultOptions.parse.parserOpts
+    }
+  },
+  dereference: {
+    strategies: [..._arazzo2.defaultOptions.dereference.strategies],
+    strategyOpts: {
+      ..._arazzo2.defaultOptions.dereference.strategyOpts
+    }
+  }
+};
+
+/**
+ * Resolves an Arazzo Document from a file system path or HTTP(S) URL.
+ *
+ * This function collects the Arazzo Document and every external document its
+ * JSON References ($ref) reach into a ReferenceSet. Nothing is dereferenced;
+ * the root reference of the set holds the parsed entry document.
+ *
+ * The `dereference.refSet` option is ignored: resolving always builds a fresh ReferenceSet.
+ *
+ * @param uri - A file system path or HTTP(S) URL to the Arazzo Document
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the ReferenceSet of the Arazzo Document and its external references
+ * @throws ResolveError - When resolving fails or document is not an Arazzo specification. The original error is available via the `cause` property.
+ *
+ * @example
+ * // Resolve from file
+ * const refSet = await resolveArazzo('/path/to/arazzo.json');
+ *
+ * @example
+ * // Resolve from URL
+ * const refSet = await resolveArazzo('https://example.com/arazzo.yaml');
+ *
+ * @example
+ * // Resolve with custom options
+ * const refSet = await resolveArazzo('/path/to/arazzo.json', customReferenceOptions);
+ * @public
+ */
+async function resolve(uri, options = {}) {
+  const mergedOptions = (0, _empty.mergeOptions)(defaultOptions, options);
+
+  // a relative file system path resolves against the current working directory; the string
+  // doubles as the base URI for relative references, where a relative base resolves against
+  // the filesystem root instead of the document. A leading slash or backslash (UNC,
+  // drive-rooted) is already rooted and passes through untouched. `uri` itself is left as
+  // is so error messages below quote what the caller passed in.
+  const retrievalURI = !_empty.url.isHttpUrl(uri) && _empty.url.getProtocol(uri) !== 'file' && !/^[\\/]/.test(uri) ? _empty.url.resolve(_empty.url.fromFileSystemPath(_empty.url.cwd()), uri) : uri;
+  try {
+    const refSet = await (0, _empty.resolve)(retrievalURI, withoutSeededRefSet(mergedOptions));
+    const parseResult = refSet.rootRef?.value;
+
+    // validate that the resolved document is an Arazzo specification
+    if (!(0, _apidomDatamodel.isParseResultElement)(parseResult) || !(0, _apidomNsArazzo.isArazzoSpecification1Element)(parseResult.api)) {
+      throw new _empty.UnmatchedResolveStrategyError(`Could not find a resolve strategy that can resolve "${uri}" as an Arazzo specification`);
+    }
+    parseResult.meta.set('retrievalURI', retrievalURI);
+    return refSet;
+  } catch (error) {
+    throw new _ResolveError.default(`Failed to resolve Arazzo Document at "${uri}"`, {
+      cause: error
+    });
+  }
+}
+
+/**
+ * Resolves an ApiDOM element representing an Arazzo Document.
+ *
+ * This function collects the element and every external document its
+ * JSON References ($ref) reach into a ReferenceSet. Nothing is dereferenced
+ * and the element itself is left untouched.
+ *
+ * Supported scenarios:
+ * - ParseResultElement with retrievalURI metadata: baseURI derived automatically
+ * - ParseResultElement without retrievalURI: requires `options.resolve.baseURI`
+ * - Child element (e.g., WorkflowElement) with parseResult in strategyOpts:
+ *   requires `options.dereference.strategyOpts.parseResult`,
+ *   and `options.resolve.baseURI` if parseResult lacks retrievalURI metadata
+ * - Child element without parseResult: requires `options.resolve.baseURI` and
+ *   `options.parse.mediaType`, since the element alone cannot identify the document kind
+ *
+ * For a child element the root reference of the returned set is keyed by the root document
+ * URI but holds a ParseResultElement wrapping a copy of the child, not the root document.
+ * The set describes the references reachable from the child and is not a whole-document set.
+ *
+ * The `dereference.refSet` option is ignored: resolving always builds a fresh ReferenceSet.
+ *
+ * @param element - An ApiDOM element (ParseResultElement or child element like WorkflowElement)
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the ReferenceSet of the element and its external references
+ * @throws ResolveError - When baseURI is required but not provided, when the document is not an Arazzo specification, or when resolving fails
+ *
+ * @example
+ * Resolve ParseResultElement with retrievalURI (from file parsing)
+ * ```typescript
+ * import { parseArazzo } from '@usearazzo/parser';
+ *
+ * const parseResult = await parseArazzo('/path/to/arazzo.json');
+ * const refSet = await resolveArazzoElement(parseResult);
+ * ```
+ *
+ * @example
+ * Resolve ParseResultElement without retrievalURI (from inline parsing)
+ * ```typescript
+ * const parseResult = await parseArazzo({ arazzo: '1.0.1', ... });
+ * const refSet = await resolveArazzoElement(parseResult, {
+ *   resolve: { baseURI: 'https://example.com/arazzo.json' },
+ * });
+ * ```
+ *
+ * @example
+ * Resolve child element (e.g., WorkflowElement)
+ * ```typescript
+ * const parseResult = await parseArazzo('/path/to/arazzo.json');
+ * const workflow = parseResult.api.workflows.get(0);
+ * const refSet = await resolveArazzoElement(workflow, {
+ *   dereference: { strategyOpts: { parseResult } },
+ * });
+ * ```
+ * @public
+ */
+async function resolveElement(element, options = {}) {
+  const mergedOptions = (0, _empty.mergeOptions)(defaultOptions, options);
+  const subject = (0, _apidomDatamodel.isParseResultElement)(element) ? 'a ParseResultElement' : 'a child element';
+  // a child element resolves against the URI of its root document
+  const root = (0, _apidomDatamodel.isParseResultElement)(element) ? element : mergedOptions.dereference?.strategyOpts?.parseResult;
+  let baseURI = mergedOptions.resolve?.baseURI;
+  let mediaType = mergedOptions.parse?.mediaType ?? 'text/plain';
+  if ((0, _apidomDatamodel.isParseResultElement)(root)) {
+    if (!(0, _apidomNsArazzo.isArazzoSpecification1Element)(root.api)) {
+      throw new _ResolveError.default('Failed to resolve Arazzo Document', {
+        cause: new _empty.UnmatchedResolveStrategyError(`Could not find a resolve strategy that can resolve ${subject} as an Arazzo specification`)
+      });
+    }
+    mediaType = mergedOptions.parse?.mediaType ?? _apidomNsArazzo.mediaTypes.latest();
+    if (root.hasMetaProperty('retrievalURI')) {
+      baseURI = root.meta.get('retrievalURI');
+    } else if (!baseURI) {
+      throw new _ResolveError.default(`baseURI option is required when resolving ${subject} without retrievalURI metadata`);
+    }
+  } else if (!baseURI) {
+    throw new _ResolveError.default('baseURI option is required when resolving a child element without parseResult in strategyOpts');
+  }
+  try {
+    return await (0, _empty.resolveApiDOM)(element, withoutSeededRefSet((0, _empty.mergeOptions)(mergedOptions, {
+      resolve: {
+        baseURI
+      },
+      parse: {
+        mediaType
+      }
+    })));
+  } catch (error) {
+    throw new _ResolveError.default('Failed to resolve Arazzo Document', {
+      cause: error
+    });
+  }
+}
+
+/**
+ * Drops a seeded `dereference.refSet`. The resolve strategies always build their own
+ * ReferenceSet and deep-merge it over the option, which strips the prototype of a
+ * caller-supplied instance and crashes the resolution.
+ */
+function withoutSeededRefSet(options) {
+  return (0, _empty.mergeOptions)(options, {
+    dereference: {
+      refSet: null
+    }
+  });
+}

package/src/resolve/arazzo.mjs

@@ -0,0 +1,198 @@
+import { isParseResultElement } from '@speclynx/apidom-datamodel';
+import { url, resolve as resolveURI, resolveApiDOM as resolveApiDOMElement, mergeOptions, UnmatchedResolveStrategyError } from '@speclynx/apidom-reference/configuration/empty';
+import Arazzo1ResolveStrategy from '@speclynx/apidom-reference/resolve/strategies/arazzo-1';
+import OpenAPI2ResolveStrategy from '@speclynx/apidom-reference/resolve/strategies/openapi-2';
+import OpenAPI30ResolveStrategy from '@speclynx/apidom-reference/resolve/strategies/openapi-3-0';
+import OpenAPI31ResolveStrategy from '@speclynx/apidom-reference/resolve/strategies/openapi-3-1';
+import { isArazzoSpecification1Element, mediaTypes } from '@speclynx/apidom-ns-arazzo-1';
+import { defaultOptions as dereferenceDefaultOptions } from "../dereference/arazzo.mjs";
+import ResolveError from "../errors/ResolveError.mjs";
+/**
+ * Options for resolving Arazzo Documents.
+ * @public
+ */
+/**
+ * Default reference options for resolving Arazzo Documents.
+ *
+ * The resolve strategies delegate to the dereference strategies of the same name,
+ * so the dereference defaults are carried over and only the resolve strategies are added.
+ * @public
+ */
+export const defaultOptions = {
+  resolve: {
+    resolvers: [...dereferenceDefaultOptions.resolve.resolvers],
+    strategies: [new Arazzo1ResolveStrategy(), new OpenAPI2ResolveStrategy(), new OpenAPI30ResolveStrategy(), new OpenAPI31ResolveStrategy()]
+  },
+  parse: {
+    parsers: [...dereferenceDefaultOptions.parse.parsers],
+    parserOpts: {
+      ...dereferenceDefaultOptions.parse.parserOpts
+    }
+  },
+  dereference: {
+    strategies: [...dereferenceDefaultOptions.dereference.strategies],
+    strategyOpts: {
+      ...dereferenceDefaultOptions.dereference.strategyOpts
+    }
+  }
+};
+
+/**
+ * Resolves an Arazzo Document from a file system path or HTTP(S) URL.
+ *
+ * This function collects the Arazzo Document and every external document its
+ * JSON References ($ref) reach into a ReferenceSet. Nothing is dereferenced;
+ * the root reference of the set holds the parsed entry document.
+ *
+ * The `dereference.refSet` option is ignored: resolving always builds a fresh ReferenceSet.
+ *
+ * @param uri - A file system path or HTTP(S) URL to the Arazzo Document
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the ReferenceSet of the Arazzo Document and its external references
+ * @throws ResolveError - When resolving fails or document is not an Arazzo specification. The original error is available via the `cause` property.
+ *
+ * @example
+ * // Resolve from file
+ * const refSet = await resolveArazzo('/path/to/arazzo.json');
+ *
+ * @example
+ * // Resolve from URL
+ * const refSet = await resolveArazzo('https://example.com/arazzo.yaml');
+ *
+ * @example
+ * // Resolve with custom options
+ * const refSet = await resolveArazzo('/path/to/arazzo.json', customReferenceOptions);
+ * @public
+ */
+export async function resolve(uri, options = {}) {
+  const mergedOptions = mergeOptions(defaultOptions, options);
+
+  // a relative file system path resolves against the current working directory; the string
+  // doubles as the base URI for relative references, where a relative base resolves against
+  // the filesystem root instead of the document. A leading slash or backslash (UNC,
+  // drive-rooted) is already rooted and passes through untouched. `uri` itself is left as
+  // is so error messages below quote what the caller passed in.
+  const retrievalURI = !url.isHttpUrl(uri) && url.getProtocol(uri) !== 'file' && !/^[\\/]/.test(uri) ? url.resolve(url.fromFileSystemPath(url.cwd()), uri) : uri;
+  try {
+    const refSet = await resolveURI(retrievalURI, withoutSeededRefSet(mergedOptions));
+    const parseResult = refSet.rootRef?.value;
+
+    // validate that the resolved document is an Arazzo specification
+    if (!isParseResultElement(parseResult) || !isArazzoSpecification1Element(parseResult.api)) {
+      throw new UnmatchedResolveStrategyError(`Could not find a resolve strategy that can resolve "${uri}" as an Arazzo specification`);
+    }
+    parseResult.meta.set('retrievalURI', retrievalURI);
+    return refSet;
+  } catch (error) {
+    throw new ResolveError(`Failed to resolve Arazzo Document at "${uri}"`, {
+      cause: error
+    });
+  }
+}
+
+/**
+ * Resolves an ApiDOM element representing an Arazzo Document.
+ *
+ * This function collects the element and every external document its
+ * JSON References ($ref) reach into a ReferenceSet. Nothing is dereferenced
+ * and the element itself is left untouched.
+ *
+ * Supported scenarios:
+ * - ParseResultElement with retrievalURI metadata: baseURI derived automatically
+ * - ParseResultElement without retrievalURI: requires `options.resolve.baseURI`
+ * - Child element (e.g., WorkflowElement) with parseResult in strategyOpts:
+ *   requires `options.dereference.strategyOpts.parseResult`,
+ *   and `options.resolve.baseURI` if parseResult lacks retrievalURI metadata
+ * - Child element without parseResult: requires `options.resolve.baseURI` and
+ *   `options.parse.mediaType`, since the element alone cannot identify the document kind
+ *
+ * For a child element the root reference of the returned set is keyed by the root document
+ * URI but holds a ParseResultElement wrapping a copy of the child, not the root document.
+ * The set describes the references reachable from the child and is not a whole-document set.
+ *
+ * The `dereference.refSet` option is ignored: resolving always builds a fresh ReferenceSet.
+ *
+ * @param element - An ApiDOM element (ParseResultElement or child element like WorkflowElement)
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the ReferenceSet of the element and its external references
+ * @throws ResolveError - When baseURI is required but not provided, when the document is not an Arazzo specification, or when resolving fails
+ *
+ * @example
+ * Resolve ParseResultElement with retrievalURI (from file parsing)
+ * ```typescript
+ * import { parseArazzo } from '@usearazzo/parser';
+ *
+ * const parseResult = await parseArazzo('/path/to/arazzo.json');
+ * const refSet = await resolveArazzoElement(parseResult);
+ * ```
+ *
+ * @example
+ * Resolve ParseResultElement without retrievalURI (from inline parsing)
+ * ```typescript
+ * const parseResult = await parseArazzo({ arazzo: '1.0.1', ... });
+ * const refSet = await resolveArazzoElement(parseResult, {
+ *   resolve: { baseURI: 'https://example.com/arazzo.json' },
+ * });
+ * ```
+ *
+ * @example
+ * Resolve child element (e.g., WorkflowElement)
+ * ```typescript
+ * const parseResult = await parseArazzo('/path/to/arazzo.json');
+ * const workflow = parseResult.api.workflows.get(0);
+ * const refSet = await resolveArazzoElement(workflow, {
+ *   dereference: { strategyOpts: { parseResult } },
+ * });
+ * ```
+ * @public
+ */
+export async function resolveElement(element, options = {}) {
+  const mergedOptions = mergeOptions(defaultOptions, options);
+  const subject = isParseResultElement(element) ? 'a ParseResultElement' : 'a child element';
+  // a child element resolves against the URI of its root document
+  const root = isParseResultElement(element) ? element : mergedOptions.dereference?.strategyOpts?.parseResult;
+  let baseURI = mergedOptions.resolve?.baseURI;
+  let mediaType = mergedOptions.parse?.mediaType ?? 'text/plain';
+  if (isParseResultElement(root)) {
+    if (!isArazzoSpecification1Element(root.api)) {
+      throw new ResolveError('Failed to resolve Arazzo Document', {
+        cause: new UnmatchedResolveStrategyError(`Could not find a resolve strategy that can resolve ${subject} as an Arazzo specification`)
+      });
+    }
+    mediaType = mergedOptions.parse?.mediaType ?? mediaTypes.latest();
+    if (root.hasMetaProperty('retrievalURI')) {
+      baseURI = root.meta.get('retrievalURI');
+    } else if (!baseURI) {
+      throw new ResolveError(`baseURI option is required when resolving ${subject} without retrievalURI metadata`);
+    }
+  } else if (!baseURI) {
+    throw new ResolveError('baseURI option is required when resolving a child element without parseResult in strategyOpts');
+  }
+  try {
+    return await resolveApiDOMElement(element, withoutSeededRefSet(mergeOptions(mergedOptions, {
+      resolve: {
+        baseURI
+      },
+      parse: {
+        mediaType
+      }
+    })));
+  } catch (error) {
+    throw new ResolveError('Failed to resolve Arazzo Document', {
+      cause: error
+    });
+  }
+}
+
+/**
+ * Drops a seeded `dereference.refSet`. The resolve strategies always build their own
+ * ReferenceSet and deep-merge it over the option, which strips the prototype of a
+ * caller-supplied instance and crashes the resolution.
+ */
+function withoutSeededRefSet(options) {
+  return mergeOptions(options, {
+    dereference: {
+      refSet: null
+    }
+  });
+}

package/src/resolve/openapi.cjs

@@ -0,0 +1,234 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.defaultOptions = void 0;
+exports.resolve = resolve;
+exports.resolveElement = resolveElement;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _empty = require("@speclynx/apidom-reference/configuration/empty");
+var _openapi = _interopRequireDefault(require("@speclynx/apidom-reference/resolve/strategies/openapi-2"));
+var _openapi2 = _interopRequireDefault(require("@speclynx/apidom-reference/resolve/strategies/openapi-3-0"));
+var _openapi3 = _interopRequireDefault(require("@speclynx/apidom-reference/resolve/strategies/openapi-3-1"));
+var _apidomNsOpenapi = require("@speclynx/apidom-ns-openapi-2");
+var _apidomNsOpenapi2 = require("@speclynx/apidom-ns-openapi-3-0");
+var _apidomNsOpenapi3 = require("@speclynx/apidom-ns-openapi-3-1");
+var _openapi4 = require("../dereference/openapi.cjs");
+var _ResolveError = _interopRequireDefault(require("../errors/ResolveError.cjs"));
+/**
+ * Options for resolving OpenAPI Documents.
+ * @public
+ */
+
+/**
+ * Default reference options for resolving OpenAPI Documents.
+ *
+ * The resolve strategies delegate to the dereference strategies of the same name,
+ * so the dereference defaults are carried over and only the resolve strategies are added.
+ * @public
+ */
+const defaultOptions = exports.defaultOptions = {
+  resolve: {
+    resolvers: [..._openapi4.defaultOptions.resolve.resolvers],
+    strategies: [new _openapi.default(), new _openapi2.default(), new _openapi3.default()]
+  },
+  parse: {
+    parsers: [..._openapi4.defaultOptions.parse.parsers],
+    parserOpts: {
+      ..._openapi4.defaultOptions.parse.parserOpts
+    }
+  },
+  dereference: {
+    strategies: [..._openapi4.defaultOptions.dereference.strategies],
+    strategyOpts: {
+      ..._openapi4.defaultOptions.dereference.strategyOpts
+    }
+  }
+};
+
+/**
+ * Resolves an OpenAPI Document from a file system path or HTTP(S) URL.
+ *
+ * This function collects the OpenAPI Document and every external document its
+ * JSON References ($ref) reach into a ReferenceSet. Nothing is dereferenced;
+ * the root reference of the set holds the parsed entry document.
+ *
+ * Supports OpenAPI 2.0 (Swagger), OpenAPI 3.0.x, and OpenAPI 3.1.x.
+ *
+ * The `dereference.refSet` option is ignored: resolving always builds a fresh ReferenceSet.
+ *
+ * @param uri - A file system path or HTTP(S) URL to the OpenAPI Document
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the ReferenceSet of the OpenAPI Document and its external references
+ * @throws ResolveError - When resolving fails or document is not an OpenAPI specification. The original error is available via the `cause` property.
+ *
+ * @example
+ * // Resolve from file
+ * const refSet = await resolveOpenAPI('/path/to/openapi.json');
+ *
+ * @example
+ * // Resolve from URL
+ * const refSet = await resolveOpenAPI('https://example.com/openapi.yaml');
+ *
+ * @example
+ * // Resolve with custom options
+ * const refSet = await resolveOpenAPI('/path/to/openapi.json', customReferenceOptions);
+ * @public
+ */
+async function resolve(uri, options = {}) {
+  const mergedOptions = (0, _empty.mergeOptions)(defaultOptions, options);
+
+  // a relative file system path resolves against the current working directory; the string
+  // doubles as the base URI for relative references, where a relative base resolves against
+  // the filesystem root instead of the document. A leading slash or backslash (UNC,
+  // drive-rooted) is already rooted and passes through untouched. `uri` itself is left as
+  // is so error messages below quote what the caller passed in.
+  const retrievalURI = !_empty.url.isHttpUrl(uri) && _empty.url.getProtocol(uri) !== 'file' && !/^[\\/]/.test(uri) ? _empty.url.resolve(_empty.url.fromFileSystemPath(_empty.url.cwd()), uri) : uri;
+  try {
+    const refSet = await (0, _empty.resolve)(retrievalURI, withoutSeededRefSet(mergedOptions));
+    const parseResult = refSet.rootRef?.value;
+
+    // validate that the resolved document is an OpenAPI specification
+    if (!(0, _apidomDatamodel.isParseResultElement)(parseResult) || !isOpenApiElement(parseResult.api)) {
+      throw new _empty.UnmatchedResolveStrategyError(`Could not find a resolve strategy that can resolve "${uri}" as an OpenAPI specification`);
+    }
+    parseResult.meta.set('retrievalURI', retrievalURI);
+    return refSet;
+  } catch (error) {
+    throw new _ResolveError.default(`Failed to resolve OpenAPI Document at "${uri}"`, {
+      cause: error
+    });
+  }
+}
+
+/**
+ * Resolves an ApiDOM element representing an OpenAPI Document.
+ *
+ * This function collects the element and every external document its
+ * JSON References ($ref) reach into a ReferenceSet. Nothing is dereferenced
+ * and the element itself is left untouched.
+ *
+ * Supported scenarios:
+ * - ParseResultElement with retrievalURI metadata: baseURI derived automatically
+ * - ParseResultElement without retrievalURI: requires `options.resolve.baseURI`
+ * - Child element (e.g., PathItemElement) with parseResult in strategyOpts:
+ *   requires `options.dereference.strategyOpts.parseResult`,
+ *   and `options.resolve.baseURI` if parseResult lacks retrievalURI metadata
+ * - Child element without parseResult: requires `options.resolve.baseURI` and
+ *   `options.parse.mediaType`, since the element alone cannot identify the document kind
+ *
+ * For a child element the root reference of the returned set is keyed by the root document
+ * URI but holds a ParseResultElement wrapping a copy of the child, not the root document.
+ * The set describes the references reachable from the child and is not a whole-document set.
+ *
+ * The `dereference.refSet` option is ignored: resolving always builds a fresh ReferenceSet.
+ *
+ * @param element - An ApiDOM element (ParseResultElement or child element like PathItemElement)
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the ReferenceSet of the element and its external references
+ * @throws ResolveError - When baseURI is required but not provided, when the document is not an OpenAPI specification, or when resolving fails
+ *
+ * @example
+ * Resolve ParseResultElement with retrievalURI (from file parsing)
+ * ```typescript
+ * import { parseOpenAPI } from '@usearazzo/parser';
+ *
+ * const parseResult = await parseOpenAPI('/path/to/openapi.json');
+ * const refSet = await resolveOpenAPIElement(parseResult);
+ * ```
+ *
+ * @example
+ * Resolve ParseResultElement without retrievalURI (from inline parsing)
+ * ```typescript
+ * const parseResult = await parseOpenAPI({ openapi: '3.1.0', ... });
+ * const refSet = await resolveOpenAPIElement(parseResult, {
+ *   resolve: { baseURI: 'https://example.com/openapi.json' },
+ * });
+ * ```
+ *
+ * @example
+ * Resolve child element (e.g., PathItemElement)
+ * ```typescript
+ * const parseResult = await parseOpenAPI('/path/to/openapi.json');
+ * const pathItem = parseResult.api.paths.get('/users');
+ * const refSet = await resolveOpenAPIElement(pathItem, {
+ *   dereference: { strategyOpts: { parseResult } },
+ * });
+ * ```
+ * @public
+ */
+async function resolveElement(element, options = {}) {
+  const mergedOptions = (0, _empty.mergeOptions)(defaultOptions, options);
+  const subject = (0, _apidomDatamodel.isParseResultElement)(element) ? 'a ParseResultElement' : 'a child element';
+  // a child element resolves against the URI of its root document
+  const root = (0, _apidomDatamodel.isParseResultElement)(element) ? element : mergedOptions.dereference?.strategyOpts?.parseResult;
+  let baseURI = mergedOptions.resolve?.baseURI;
+  let mediaType = mergedOptions.parse?.mediaType ?? 'text/plain';
+  if ((0, _apidomDatamodel.isParseResultElement)(root)) {
+    if (!isOpenApiElement(root.api)) {
+      throw new _ResolveError.default('Failed to resolve OpenAPI Document', {
+        cause: new _empty.UnmatchedResolveStrategyError(`Could not find a resolve strategy that can resolve ${subject} as an OpenAPI specification`)
+      });
+    }
+    mediaType = mergedOptions.parse?.mediaType ?? inferOpenApiMediaType(root.api);
+    if (root.hasMetaProperty('retrievalURI')) {
+      baseURI = root.meta.get('retrievalURI');
+    } else if (!baseURI) {
+      throw new _ResolveError.default(`baseURI option is required when resolving ${subject} without retrievalURI metadata`);
+    }
+  } else if (!baseURI) {
+    throw new _ResolveError.default('baseURI option is required when resolving a child element without parseResult in strategyOpts');
+  }
+  try {
+    return await (0, _empty.resolveApiDOM)(element, withoutSeededRefSet((0, _empty.mergeOptions)(mergedOptions, {
+      resolve: {
+        baseURI
+      },
+      parse: {
+        mediaType
+      }
+    })));
+  } catch (error) {
+    throw new _ResolveError.default('Failed to resolve OpenAPI Document', {
+      cause: error
+    });
+  }
+}
+
+/**
+ * Drops a seeded `dereference.refSet`. The resolve strategies always build their own
+ * ReferenceSet and deep-merge it over the option, which strips the prototype of a
+ * caller-supplied instance and crashes the resolution.
+ */
+function withoutSeededRefSet(options) {
+  return (0, _empty.mergeOptions)(options, {
+    dereference: {
+      refSet: null
+    }
+  });
+}
+
+/**
+ * Checks if the element is a valid OpenAPI specification element.
+ */
+function isOpenApiElement(element) {
+  return (0, _apidomNsOpenapi.isSwaggerElement)(element) || (0, _apidomNsOpenapi2.isOpenApi3_0Element)(element) || (0, _apidomNsOpenapi3.isOpenApi3_1Element)(element);
+}
+
+/**
+ * Gets the appropriate mediaType for an OpenAPI element.
+ */
+function inferOpenApiMediaType(element) {
+  if ((0, _apidomNsOpenapi.isSwaggerElement)(element)) {
+    return _apidomNsOpenapi.mediaTypes.latest();
+  }
+  if ((0, _apidomNsOpenapi2.isOpenApi3_0Element)(element)) {
+    return _apidomNsOpenapi2.mediaTypes.latest();
+  }
+  if ((0, _apidomNsOpenapi3.isOpenApi3_1Element)(element)) {
+    return _apidomNsOpenapi3.mediaTypes.latest();
+  }
+  return 'text/plain';
+}