@usearazzo/runner 0.0.0-stage → 1.0.1-alpha.7

package/src/registry/DocumentRegistry.cjs

@@ -0,0 +1,160 @@
+"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 _empty = require("@speclynx/apidom-reference/configuration/empty");
+var _ArazzoDocument = _interopRequireDefault(require("../document/ArazzoDocument.cjs"));
+var _ArazzoDocumentRegistryProvider = _interopRequireDefault(require("./providers/ArazzoDocumentRegistryProvider.cjs"));
+var _OpenAPIDocumentRegistryProvider = _interopRequireDefault(require("./providers/OpenAPIDocumentRegistryProvider.cjs"));
+var _InvalidEntryDocumentError = _interopRequireDefault(require("../errors/InvalidEntryDocumentError.cjs"));
+var _UnmatchedProviderError = _interopRequireDefault(require("../errors/UnmatchedProviderError.cjs"));
+var constants = _interopRequireWildcard(require("../constants.cjs"));
+/**
+ * Options for the DocumentRegistry.
+ * @public
+ */
+
+/**
+ * Registry for API documents keyed by canonical URI.
+ *
+ * Acts as an LRU cache for parsed documents. The entry Arazzo document
+ * is pinned and never evicted. Providers are tried in order to detect
+ * and load documents.
+ * @public
+ */
+class DocumentRegistry {
+  #documents = new Map();
+  #providers;
+  constructor(options = {}) {
+    this.#providers = options.providers ?? [new _ArazzoDocumentRegistryProvider.default(), new _OpenAPIDocumentRegistryProvider.default()];
+  }
+
+  /**
+   * Returns the entry Arazzo document, or undefined if not yet registered.
+   */
+  get entryDocument() {
+    for (const doc of this.#documents.values()) {
+      if (_ArazzoDocument.default.is(doc) && doc.isEntry) {
+        return doc;
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Acquires a document by URI. Returns cached document if available,
+   * otherwise detects the format, loads via the matching provider,
+   * caches, and returns it.
+   */
+  async acquire(uri) {
+    const canonicalURI = this.#canonicalize(uri);
+    const cachedDocument = this.#get(canonicalURI);
+    if (cachedDocument) return cachedDocument;
+    for (const provider of this.#providers) {
+      if (await provider.canProvide(canonicalURI)) {
+        const document = await provider.provide(canonicalURI);
+        this.#set(canonicalURI, document);
+        return document;
+      }
+    }
+    throw new _UnmatchedProviderError.default(`No provider can handle the document at "${canonicalURI}"`, {
+      uri: canonicalURI
+    });
+  }
+
+  /**
+   * Returns an already-loaded document by URI, or undefined if not cached.
+   *
+   * Synchronous counterpart to `acquire`: it never loads a document, only
+   * returns one the registry already holds, marking it most recently used like
+   * any other access. Consumers that must resolve a reference without awaiting
+   * (e.g. runtime expression evaluation) use this; the executor is responsible
+   * for having acquired the document beforehand.
+   */
+  get(uri) {
+    return this.#get(this.#canonicalize(uri));
+  }
+
+  /**
+   * Canonical form of a URI, used as the cache key and handed to providers.
+   *
+   * A relative file system path resolves against the current working directory
+   * first: the canonical URI doubles as the base URI for source description
+   * URLs, 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. The working directory is encoded so a
+   * directory name containing `#`, `?` or `%` survives URL parsing.
+   */
+  #canonicalize(uri) {
+    const absoluteURI = !_empty.url.isHttpUrl(uri) && _empty.url.getProtocol(uri) !== 'file' && !/^[\\/]/.test(uri) ? _empty.url.resolve(_empty.url.fromFileSystemPath(_empty.url.cwd()), uri) : uri;
+    return _empty.url.sanitize(_empty.url.stripHash(absoluteURI));
+  }
+
+  /**
+   * Acquires the entry Arazzo document and marks it with `isEntry: true`.
+   * Validates that the document is an Arazzo specification.
+   */
+  async acquireEntryDocument(uri) {
+    const document = await this.acquire(uri);
+    if (!_ArazzoDocument.default.is(document)) {
+      throw new _InvalidEntryDocumentError.default(`Entry document at "${uri}" is not an Arazzo Document`, {
+        uri
+      });
+    }
+    document.isEntry = true;
+    return document;
+  }
+  clear() {
+    this.#documents.clear();
+  }
+
+  /**
+   * Retrieves a document and marks it as recently used.
+   */
+  #get(uri) {
+    const doc = this.#documents.get(uri);
+    if (doc === undefined) return undefined;
+
+    // move to end (most recently used)
+    this.#documents.delete(uri);
+    this.#documents.set(uri, doc);
+    return doc;
+  }
+
+  /**
+   * Registers a document in the registry.
+   *
+   * If the registry is at capacity, the least recently used document
+   * is evicted. The entry Arazzo document is never evicted.
+   */
+  #set(uri, document) {
+    if (this.#documents.has(uri)) {
+      this.#documents.delete(uri);
+    } else if (this.#documents.size >= constants.MAX_DOCUMENT_REGISTRY_SIZE) {
+      this.#evictOldest();
+    }
+    this.#documents.set(uri, document);
+  }
+
+  /**
+   * Removes a document from the registry.
+   * The entry document cannot be removed.
+   */
+  #delete(uri) {
+    const doc = this.#documents.get(uri);
+    if (doc && _ArazzoDocument.default.is(doc) && doc.isEntry) {
+      return false;
+    }
+    return this.#documents.delete(uri);
+  }
+  #evictOldest() {
+    for (const [uri] of this.#documents) {
+      if (this.#delete(uri)) return;
+    }
+  }
+}
+var _default = exports.default = DocumentRegistry;

package/src/registry/DocumentRegistry.mjs

@@ -0,0 +1,151 @@
+import { url } from '@speclynx/apidom-reference/configuration/empty';
+import ArazzoDocument from "../document/ArazzoDocument.mjs";
+import ArazzoDocumentRegistryProvider from "./providers/ArazzoDocumentRegistryProvider.mjs";
+import OpenAPIDocumentRegistryProvider from "./providers/OpenAPIDocumentRegistryProvider.mjs";
+import InvalidEntryDocumentError from "../errors/InvalidEntryDocumentError.mjs";
+import UnmatchedProviderError from "../errors/UnmatchedProviderError.mjs";
+import * as constants from "../constants.mjs";
+/**
+ * Options for the DocumentRegistry.
+ * @public
+ */
+/**
+ * Registry for API documents keyed by canonical URI.
+ *
+ * Acts as an LRU cache for parsed documents. The entry Arazzo document
+ * is pinned and never evicted. Providers are tried in order to detect
+ * and load documents.
+ * @public
+ */
+class DocumentRegistry {
+  #documents = new Map();
+  #providers;
+  constructor(options = {}) {
+    this.#providers = options.providers ?? [new ArazzoDocumentRegistryProvider(), new OpenAPIDocumentRegistryProvider()];
+  }
+
+  /**
+   * Returns the entry Arazzo document, or undefined if not yet registered.
+   */
+  get entryDocument() {
+    for (const doc of this.#documents.values()) {
+      if (ArazzoDocument.is(doc) && doc.isEntry) {
+        return doc;
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Acquires a document by URI. Returns cached document if available,
+   * otherwise detects the format, loads via the matching provider,
+   * caches, and returns it.
+   */
+  async acquire(uri) {
+    const canonicalURI = this.#canonicalize(uri);
+    const cachedDocument = this.#get(canonicalURI);
+    if (cachedDocument) return cachedDocument;
+    for (const provider of this.#providers) {
+      if (await provider.canProvide(canonicalURI)) {
+        const document = await provider.provide(canonicalURI);
+        this.#set(canonicalURI, document);
+        return document;
+      }
+    }
+    throw new UnmatchedProviderError(`No provider can handle the document at "${canonicalURI}"`, {
+      uri: canonicalURI
+    });
+  }
+
+  /**
+   * Returns an already-loaded document by URI, or undefined if not cached.
+   *
+   * Synchronous counterpart to `acquire`: it never loads a document, only
+   * returns one the registry already holds, marking it most recently used like
+   * any other access. Consumers that must resolve a reference without awaiting
+   * (e.g. runtime expression evaluation) use this; the executor is responsible
+   * for having acquired the document beforehand.
+   */
+  get(uri) {
+    return this.#get(this.#canonicalize(uri));
+  }
+
+  /**
+   * Canonical form of a URI, used as the cache key and handed to providers.
+   *
+   * A relative file system path resolves against the current working directory
+   * first: the canonical URI doubles as the base URI for source description
+   * URLs, 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. The working directory is encoded so a
+   * directory name containing `#`, `?` or `%` survives URL parsing.
+   */
+  #canonicalize(uri) {
+    const absoluteURI = !url.isHttpUrl(uri) && url.getProtocol(uri) !== 'file' && !/^[\\/]/.test(uri) ? url.resolve(url.fromFileSystemPath(url.cwd()), uri) : uri;
+    return url.sanitize(url.stripHash(absoluteURI));
+  }
+
+  /**
+   * Acquires the entry Arazzo document and marks it with `isEntry: true`.
+   * Validates that the document is an Arazzo specification.
+   */
+  async acquireEntryDocument(uri) {
+    const document = await this.acquire(uri);
+    if (!ArazzoDocument.is(document)) {
+      throw new InvalidEntryDocumentError(`Entry document at "${uri}" is not an Arazzo Document`, {
+        uri
+      });
+    }
+    document.isEntry = true;
+    return document;
+  }
+  clear() {
+    this.#documents.clear();
+  }
+
+  /**
+   * Retrieves a document and marks it as recently used.
+   */
+  #get(uri) {
+    const doc = this.#documents.get(uri);
+    if (doc === undefined) return undefined;
+
+    // move to end (most recently used)
+    this.#documents.delete(uri);
+    this.#documents.set(uri, doc);
+    return doc;
+  }
+
+  /**
+   * Registers a document in the registry.
+   *
+   * If the registry is at capacity, the least recently used document
+   * is evicted. The entry Arazzo document is never evicted.
+   */
+  #set(uri, document) {
+    if (this.#documents.has(uri)) {
+      this.#documents.delete(uri);
+    } else if (this.#documents.size >= constants.MAX_DOCUMENT_REGISTRY_SIZE) {
+      this.#evictOldest();
+    }
+    this.#documents.set(uri, document);
+  }
+
+  /**
+   * Removes a document from the registry.
+   * The entry document cannot be removed.
+   */
+  #delete(uri) {
+    const doc = this.#documents.get(uri);
+    if (doc && ArazzoDocument.is(doc) && doc.isEntry) {
+      return false;
+    }
+    return this.#documents.delete(uri);
+  }
+  #evictOldest() {
+    for (const [uri] of this.#documents) {
+      if (this.#delete(uri)) return;
+    }
+  }
+}
+export default DocumentRegistry;

package/src/registry/providers/ArazzoDocumentRegistryProvider.cjs

@@ -0,0 +1,154 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.providerOptionsOverride = exports.default = void 0;
+var _parser = require("@usearazzo/parser");
+var _empty = require("@speclynx/apidom-reference/configuration/empty");
+var _apidomCore = require("@speclynx/apidom-core");
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomTraverse = require("@speclynx/apidom-traverse");
+var _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
+var constants = _interopRequireWildcard(require("../../constants.cjs"));
+var _ArazzoDocument = _interopRequireDefault(require("../../document/ArazzoDocument.cjs"));
+var _DocumentRegistryProvider = _interopRequireWildcard(require("./DocumentRegistryProvider.cjs"));
+var _ArazzoWorkflowIndex = _interopRequireDefault(require("../../document/ArazzoWorkflowIndex.cjs"));
+var _ArazzoStepIndex = _interopRequireDefault(require("../../document/ArazzoStepIndex.cjs"));
+var _ArazzoSourceDescriptionIndex = _interopRequireDefault(require("../../document/ArazzoSourceDescriptionIndex.cjs"));
+/**
+ * Options for loading an Arazzo document.
+ * @public
+ */
+
+/**
+ * Default options for loading an Arazzo document.
+ *
+ * The provider only parses the Arazzo document; dereferencing is deferred
+ * to the normalizer when a specific workflow is accessed.
+ */
+const providerOptionsOverride = exports.providerOptionsOverride = {
+  resolve: {
+    resolverOpts: {
+      cache: {
+        maxEntries: constants.MAX_HTTP_CACHE_ENTRIES,
+        maxStaleAge: constants.MAX_HTTP_CACHE_STALE_AGE
+      }
+    }
+  },
+  dereference: {
+    immutable: false,
+    circular: 'replace',
+    circularReplacer: _DocumentRegistryProvider.circularReplacer,
+    strategyOpts: {
+      sourceDescriptions: false
+    }
+  }
+};
+
+/**
+ * Provides ArazzoDocument instances for the DocumentRegistry.
+ *
+ * Parses the Arazzo document and builds its workflow and source description
+ * indexes — the document itself is a container.
+ * @public
+ */
+class ArazzoDocumentRegistryProvider extends _DocumentRegistryProvider.default {
+  #options;
+  constructor(options = {}) {
+    super();
+    this.#options = (0, _empty.mergeOptions)(providerOptionsOverride, options);
+  }
+  async canProvide(uri) {
+    try {
+      const options = this.#buildParseOptions();
+      const data = await (0, _empty.readFile)(uri, options);
+      const file = new _empty.File({
+        uri,
+        data
+      });
+      const parsers = options.parse.parsers.filter(p => p.name.startsWith('arazzo'));
+      for (const parser of parsers) {
+        if (await parser.canParse(file)) return true;
+      }
+    } catch (error) {
+      if (error instanceof _empty.UnmatchedResolverError) return false;
+      throw error;
+    }
+    return false;
+  }
+
+  /**
+   * Loads an Arazzo document from a URI and produces an ArazzoDocument.
+   */
+  async provide(uri) {
+    const parseResult = await (0, _parser.parseArazzo)(uri, this.#buildParseOptions());
+    const {
+      workflowIndex,
+      stepIndex,
+      sourceDescriptionIndex
+    } = this.#buildIndexes(uri, parseResult);
+    return new _ArazzoDocument.default(uri, parseResult, workflowIndex, stepIndex, sourceDescriptionIndex);
+  }
+
+  /**
+   * Builds all indexes in one traversal of the parse result.
+   *
+   * A source description's canonical URI is resolved here too — against the
+   * document's base URI, into the exact form the document registry keys on —
+   * so every consumer works with a ready-to-use, non-relative URI. The first
+   * element of a duplicated source description name wins.
+   */
+  #buildIndexes(uri, parseResult) {
+    const workflowIndex = new _ArazzoWorkflowIndex.default();
+    const stepIndex = new _ArazzoStepIndex.default();
+    const sourceDescriptionIndex = new _ArazzoSourceDescriptionIndex.default();
+    (0, _apidomTraverse.traverse)(parseResult.api, {
+      WorkflowElement(path) {
+        const workflow = path.node;
+        const workflowId = (0, _apidomCore.toValue)(workflow.workflowId);
+        if (typeof workflowId !== 'string') return path.skip();
+        if (workflowId === '') return path.skip();
+        const workflowPointer = path.formatPath('jsonpointer');
+        workflowIndex.set(workflowId, workflowPointer);
+
+        // steps are indexed by list position; malformed entries are left to the
+        // executor to report, the index simply omits them.
+        const steps = new Map();
+        if ((0, _apidomDatamodel.isArrayElement)(workflow.steps)) {
+          [...workflow.steps].forEach((step, index) => {
+            if (!(0, _apidomNsArazzo.isStepElement)(step)) return;
+            const stepId = (0, _apidomCore.toValue)(step.stepId);
+            if (typeof stepId !== 'string' || stepId === '') return;
+            if (!steps.has(stepId)) steps.set(stepId, `${workflowPointer}/steps/${index}`);
+          });
+        }
+        stepIndex.set(workflowId, steps);
+        return path.skip();
+      },
+      SourceDescriptionElement(path) {
+        const element = path.node;
+        if (!(0, _apidomDatamodel.isStringElement)(element.name)) return path.skip();
+        const name = (0, _apidomCore.toValue)(element.name);
+        if (!sourceDescriptionIndex.has(name)) {
+          sourceDescriptionIndex.set(name, {
+            element,
+            uri: (0, _apidomDatamodel.isStringElement)(element.url) ? _empty.url.sanitize(_empty.url.stripHash(_empty.url.resolve(uri, (0, _apidomCore.toValue)(element.url)))) : undefined
+          });
+        }
+        return path.skip();
+      }
+    });
+    return {
+      workflowIndex,
+      stepIndex,
+      sourceDescriptionIndex
+    };
+  }
+  #buildParseOptions() {
+    return (0, _empty.mergeOptions)(_parser.defaultParseArazzoOptions, this.#options);
+  }
+}
+var _default = exports.default = ArazzoDocumentRegistryProvider;

package/src/registry/providers/ArazzoDocumentRegistryProvider.mjs

@@ -0,0 +1,146 @@
+import { parseArazzo, defaultParseArazzoOptions } from '@usearazzo/parser';
+import { readFile, File, mergeOptions, url } from '@speclynx/apidom-reference/configuration/empty';
+import { UnmatchedResolverError } from '@speclynx/apidom-reference/configuration/empty';
+import { toValue } from '@speclynx/apidom-core';
+import { isArrayElement, isStringElement } from '@speclynx/apidom-datamodel';
+import { traverse } from '@speclynx/apidom-traverse';
+import { isStepElement } from '@speclynx/apidom-ns-arazzo-1';
+import * as constants from "../../constants.mjs";
+import ArazzoDocument from "../../document/ArazzoDocument.mjs";
+import DocumentRegistryProvider, { circularReplacer } from "./DocumentRegistryProvider.mjs";
+import ArazzoWorkflowIndex from "../../document/ArazzoWorkflowIndex.mjs";
+import ArazzoStepIndex from "../../document/ArazzoStepIndex.mjs";
+import ArazzoSourceDescriptionIndex from "../../document/ArazzoSourceDescriptionIndex.mjs";
+/**
+ * Options for loading an Arazzo document.
+ * @public
+ */
+/**
+ * Default options for loading an Arazzo document.
+ *
+ * The provider only parses the Arazzo document; dereferencing is deferred
+ * to the normalizer when a specific workflow is accessed.
+ */
+export const providerOptionsOverride = {
+  resolve: {
+    resolverOpts: {
+      cache: {
+        maxEntries: constants.MAX_HTTP_CACHE_ENTRIES,
+        maxStaleAge: constants.MAX_HTTP_CACHE_STALE_AGE
+      }
+    }
+  },
+  dereference: {
+    immutable: false,
+    circular: 'replace',
+    circularReplacer,
+    strategyOpts: {
+      sourceDescriptions: false
+    }
+  }
+};
+
+/**
+ * Provides ArazzoDocument instances for the DocumentRegistry.
+ *
+ * Parses the Arazzo document and builds its workflow and source description
+ * indexes — the document itself is a container.
+ * @public
+ */
+class ArazzoDocumentRegistryProvider extends DocumentRegistryProvider {
+  #options;
+  constructor(options = {}) {
+    super();
+    this.#options = mergeOptions(providerOptionsOverride, options);
+  }
+  async canProvide(uri) {
+    try {
+      const options = this.#buildParseOptions();
+      const data = await readFile(uri, options);
+      const file = new File({
+        uri,
+        data
+      });
+      const parsers = options.parse.parsers.filter(p => p.name.startsWith('arazzo'));
+      for (const parser of parsers) {
+        if (await parser.canParse(file)) return true;
+      }
+    } catch (error) {
+      if (error instanceof UnmatchedResolverError) return false;
+      throw error;
+    }
+    return false;
+  }
+
+  /**
+   * Loads an Arazzo document from a URI and produces an ArazzoDocument.
+   */
+  async provide(uri) {
+    const parseResult = await parseArazzo(uri, this.#buildParseOptions());
+    const {
+      workflowIndex,
+      stepIndex,
+      sourceDescriptionIndex
+    } = this.#buildIndexes(uri, parseResult);
+    return new ArazzoDocument(uri, parseResult, workflowIndex, stepIndex, sourceDescriptionIndex);
+  }
+
+  /**
+   * Builds all indexes in one traversal of the parse result.
+   *
+   * A source description's canonical URI is resolved here too — against the
+   * document's base URI, into the exact form the document registry keys on —
+   * so every consumer works with a ready-to-use, non-relative URI. The first
+   * element of a duplicated source description name wins.
+   */
+  #buildIndexes(uri, parseResult) {
+    const workflowIndex = new ArazzoWorkflowIndex();
+    const stepIndex = new ArazzoStepIndex();
+    const sourceDescriptionIndex = new ArazzoSourceDescriptionIndex();
+    traverse(parseResult.api, {
+      WorkflowElement(path) {
+        const workflow = path.node;
+        const workflowId = toValue(workflow.workflowId);
+        if (typeof workflowId !== 'string') return path.skip();
+        if (workflowId === '') return path.skip();
+        const workflowPointer = path.formatPath('jsonpointer');
+        workflowIndex.set(workflowId, workflowPointer);
+
+        // steps are indexed by list position; malformed entries are left to the
+        // executor to report, the index simply omits them.
+        const steps = new Map();
+        if (isArrayElement(workflow.steps)) {
+          [...workflow.steps].forEach((step, index) => {
+            if (!isStepElement(step)) return;
+            const stepId = toValue(step.stepId);
+            if (typeof stepId !== 'string' || stepId === '') return;
+            if (!steps.has(stepId)) steps.set(stepId, `${workflowPointer}/steps/${index}`);
+          });
+        }
+        stepIndex.set(workflowId, steps);
+        return path.skip();
+      },
+      SourceDescriptionElement(path) {
+        const element = path.node;
+        if (!isStringElement(element.name)) return path.skip();
+        const name = toValue(element.name);
+        if (!sourceDescriptionIndex.has(name)) {
+          sourceDescriptionIndex.set(name, {
+            element,
+            uri: isStringElement(element.url) ? url.sanitize(url.stripHash(url.resolve(uri, toValue(element.url)))) : undefined
+          });
+        }
+        return path.skip();
+      }
+    });
+    return {
+      workflowIndex,
+      stepIndex,
+      sourceDescriptionIndex
+    };
+  }
+  #buildParseOptions() {
+    return mergeOptions(defaultParseArazzoOptions, this.#options);
+  }
+}
+export default ArazzoDocumentRegistryProvider;

package/src/registry/providers/DocumentRegistryProvider.cjs

@@ -0,0 +1,31 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = exports.circularReplacer = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+/**
+ * Replaces circular $ref references with an empty ObjectElement
+ * annotated with the original $ref value. This ensures the dereferenced
+ * output is a finite tree safe for downstream tools.
+ * @param ref - The RefElement being replaced at the cycle boundary.
+ * @public
+ */
+const circularReplacer = ref => new _apidomDatamodel.ObjectElement({
+  'x-circular': ref.meta.get('$ref')
+});
+
+/**
+ * Options for a document registry provider.
+ * @public
+ */
+exports.circularReplacer = circularReplacer;
+/**
+ * Base class for document registry providers.
+ *
+ * Subclasses implement `canProvide()` for format detection and `provide()` for loading.
+ * @public
+ */
+class DocumentRegistryProvider {}
+var _default = exports.default = DocumentRegistryProvider;

package/src/registry/providers/DocumentRegistryProvider.mjs

@@ -0,0 +1,25 @@
+import { ObjectElement } from '@speclynx/apidom-datamodel';
+/**
+ * Replaces circular $ref references with an empty ObjectElement
+ * annotated with the original $ref value. This ensures the dereferenced
+ * output is a finite tree safe for downstream tools.
+ * @param ref - The RefElement being replaced at the cycle boundary.
+ * @public
+ */
+export const circularReplacer = ref => new ObjectElement({
+  'x-circular': ref.meta.get('$ref')
+});
+
+/**
+ * Options for a document registry provider.
+ * @public
+ */
+
+/**
+ * Base class for document registry providers.
+ *
+ * Subclasses implement `canProvide()` for format detection and `provide()` for loading.
+ * @public
+ */
+class DocumentRegistryProvider {}
+export default DocumentRegistryProvider;