@speclynx/apidom-reference 6.2.0 → 7.0.0

package/src/parse/parsers/yaml-1-2/index.cjs

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 var _apidomParserAdapterYaml = require("@speclynx/apidom-parser-adapter-yaml-1-2");
+var _mediaTypes = require("@swaggerexpert/media-types");
 var _ParserError = _interopRequireDefault(require("../../../errors/ParserError.cjs"));
 var _Parser = _interopRequireDefault(require("../Parser.cjs"));
 /**
@@ -32,7 +33,7 @@ class YAML1Parser extends _Parser.default {
   }
   async canParse(file) {
     const hasSupportedFileExtension = this.fileExtensions.length === 0 ? true : this.fileExtensions.includes(file.extension);
-    const hasSupportedMediaType = this.mediaTypes.includes(file.mediaType);
+    const hasSupportedMediaType = (0, _mediaTypes.selectBestMatch)(this.mediaTypes, file.mediaType) !== null;
     if (!hasSupportedFileExtension) return false;
     if (hasSupportedMediaType) return true;
     if (!hasSupportedMediaType) {

package/src/parse/parsers/yaml-1-2/index.mjs

@@ -1,4 +1,5 @@
 import { parse, mediaTypes as YAMLMediaTypes, detect } from '@speclynx/apidom-parser-adapter-yaml-1-2';
+import { selectBestMatch } from '@swaggerexpert/media-types';
 import ParserError from "../../../errors/ParserError.mjs";
 import Parser from "../Parser.mjs";
 /**
@@ -24,7 +25,7 @@ class YAML1Parser extends Parser {
   }
   async canParse(file) {
     const hasSupportedFileExtension = this.fileExtensions.length === 0 ? true : this.fileExtensions.includes(file.extension);
-    const hasSupportedMediaType = this.mediaTypes.includes(file.mediaType);
+    const hasSupportedMediaType = selectBestMatch(this.mediaTypes, file.mediaType) !== null;
     if (!hasSupportedFileExtension) return false;
     if (hasSupportedMediaType) return true;
     if (!hasSupportedMediaType) {

package/types/apidom-reference.d.ts

@@ -143,15 +143,6 @@ declare const cwd: () => string;
  */
 export declare const dereference: (uri: string, options?: {}) => Promise<ParseResultElement>;
 
-/**
- * @public
- */
-export declare class DereferenceAncestorLineage<T extends Element_2> extends Array<Set<T>> {
-    includesCycle(element: T): boolean;
-    includes(searchElement: Set<T> | T, fromIndex?: number): boolean;
-    findItem(predicate: (item: T) => boolean): T | undefined;
-}
-
 /**
  * @public
  */

package/types/dereference/strategies/DereferenceVisitor.d.ts

@@ -0,0 +1,224 @@
+import { Element } from '@speclynx/apidom-datamodel';
+import { type Path } from '@speclynx/apidom-traverse';
+import Reference from '../../Reference.ts';
+import type { ReferenceOptions } from '../../options/index.ts';
+/**
+ * Whether the element is generic ApiDOM: an instance of a primitive element class itself.
+ * Semantic elements may carry a primitive element name (e.g. a map of components named
+ * `object`), so the name alone doesn't tell.
+ * @internal
+ */
+export declare const isGenericElement: (element: Element) => boolean;
+/**
+ * A source dereferenced as one type: the source as that semantic type, with every reference
+ * within it transcluded. `element` exists from the start, so references leading back to
+ * an element still being dereferenced (cycles) can be transcluded with it.
+ * @internal
+ */
+export interface DereferencedElement {
+    element: Element;
+    done: boolean;
+    height: number;
+    alias: boolean;
+    unresolved: boolean;
+}
+/**
+ * How a referencing element is transcluded with the dereferenced target of its reference.
+ * @internal
+ */
+export interface TransclusionSpec {
+    /**
+     * The element transcluded in place of the referencing element, built from the dereferenced
+     * target (which may still be being dereferenced when the reference leads back to it).
+     */
+    readonly toTranscludedElement: (referencingElement: Element, target: Element) => Element;
+    /**
+     * Field holding the reference of an alias, for references merging their target with
+     * the fields next to them (e.g. `$ref`): a target that is an alias whose reference never
+     * reaches a value is merged without that field, so only the fields along the chain remain.
+     * Without it, a referencing element leading to such an alias is kept as written.
+     */
+    readonly aliasField?: string;
+    /**
+     * What a circular reference is reported and replaced with: the RefElement content and meta
+     * for `dereference.circular: 'replace'`, the error details for `'error'`.
+     */
+    readonly circular: {
+        readonly uri: string;
+        readonly meta: Record<string, unknown>;
+        readonly details: Record<string, unknown>;
+    };
+}
+/**
+ * A transclusion to perform.
+ * @internal
+ */
+export interface Transclusion extends TransclusionSpec {
+    readonly target: DereferencedElement;
+    readonly back: boolean;
+    readonly keep: boolean;
+    readonly attachment: boolean;
+}
+/**
+ * The target of a reference: the source element, the type the reference expects, and the
+ * document the source belongs to. `context` is passed to the visitor dereferencing the source.
+ * @internal
+ */
+export interface DereferenceTarget<TContext = unknown> {
+    readonly source: Element;
+    readonly type: string;
+    readonly reference: Reference;
+    readonly context: TContext;
+}
+/**
+ * State shared by all the visitors of a single dereference run.
+ * @internal
+ */
+export interface DereferenceRun {
+    readonly dereferenced: WeakMap<Element, Map<string, DereferencedElement>>;
+    readonly refracted: WeakMap<Element, Map<string, Element>>;
+    readonly inPlace: boolean;
+    readonly copies: WeakMap<object, object>;
+    readonly transcluded: WeakSet<Element>;
+    readonly failed: WeakSet<Element>;
+    readonly reported: Set<string>;
+    readonly undo: (() => void)[];
+}
+/**
+ * @internal
+ */
+export interface DereferenceVisitorOptions {
+    readonly reference: Reference;
+    readonly options: ReferenceOptions;
+}
+/**
+ * Dereferences a document by the type each reference expects of its target. With the immutable
+ * option the documents aren't edited and the result is a new tree; otherwise they're
+ * dereferenced in place.
+ *
+ * Every referenced structure is dereferenced once per type the references reaching it expect.
+ * A source is dereferenced as a type in two steps. First it's traversed, and for each reference
+ * within it the target is located, dereferenced as the expected type, and recorded as
+ * a transclusion. Then the referencing elements are transcluded with the dereferenced targets.
+ * A dereferenced element is shared by all the references leading to it; a reference leading
+ * to an element still being dereferenced is a cycle.
+ *
+ * Strategies provide the handlers locating the targets of their references, the refraction to
+ * their semantic types and the visitors dereferencing the targets.
+ * @internal
+ */
+declare abstract class DereferenceVisitor<TContext = unknown> {
+    protected readonly reference: Reference;
+    protected readonly options: ReferenceOptions;
+    /**
+     * Base URI of the current document for resolving relative references.
+     */
+    protected readonly baseURI: string;
+    protected run: DereferenceRun;
+    /**
+     * Map from the elements of the source the visitor traverses to their copies.
+     */
+    protected cloneMap?: WeakMap<object, object>;
+    /**
+     * Source the visitor traverses a refraction of, when it's dereferenced as another type.
+     */
+    protected refractedFrom?: Element;
+    /**
+     * Transclusions to perform, keyed by the (copy of the) referencing element.
+     */
+    protected readonly transclusions: Map<Element, Transclusion>;
+    /**
+     * Number of references followed to reach the source the visitor traverses.
+     */
+    protected depth: number;
+    /**
+     * The source the visitor traverses, dereferenced.
+     */
+    protected current?: DereferencedElement;
+    constructor({ reference, options }: DereferenceVisitorOptions);
+    /**
+     * Name of the strategy, for strategy specific options.
+     */
+    protected abstract get strategyName(): string;
+    /**
+     * Creates the visitor dereferencing a source of the given document.
+     */
+    protected abstract createVisitor(reference: Reference, context: TContext): DereferenceVisitor;
+    /**
+     * Refracts a generic element to the given type.
+     */
+    protected abstract refractTo(element: Element, type: string): Element;
+    /**
+     * Whether the element is of the given type, so it needs no refraction.
+     */
+    protected isOfType(element: Element, type: string): boolean;
+    /**
+     * Base URI of a document: its retrieval URI unless the document identifies itself otherwise.
+     */
+    protected toDocumentBaseURI(reference: Reference): string;
+    /**
+     * A document already loaded in the run identified by the URI other than by its retrieval URI.
+     */
+    protected findReferenceByIdentity(_uri: string): Reference | undefined;
+    /**
+     * Dereferences the element, which belongs to the document of the visitor's reference.
+     * With the immutable option the element isn't edited and its dereferenced copy is returned;
+     * otherwise it's dereferenced in place and returned.
+     */
+    dereference<T extends Element>(element: T, context: TContext): Promise<T>;
+    protected toBaseURI(uri: string): string;
+    protected toReference(uri: string): Promise<Reference>;
+    /**
+     * Handles an error according to the continueOnError option.
+     *
+     * For new errors: wraps in UnresolvableReferenceError with structured context
+     * (type, uri, location, codeFrame, refFieldName, refFieldValue, trace).
+     * 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),
+     * and reports the failure of a referencing element once.
+     */
+    protected handleError(message: string, error: Error, referencingElement: Element, refFieldName: string, refFieldValue: string, visitorPath: Path<Element>): void;
+    /**
+     * The source as the given semantic type: the source itself when it's of that type, otherwise
+     * its refraction to that type, made once per dereference run. The refraction is made from
+     * the source dereferenced as its own type, so it doesn't depend on which reference
+     * reaches the source first.
+     */
+    protected toSemantic(target: DereferenceTarget<TContext>, depth: number): Promise<Element>;
+    /**
+     * Dereferences the source as the given type, once per dereference run. `depth` is the number
+     * of references followed to reach the source.
+     */
+    protected dereferenceAs(target: DereferenceTarget<TContext>, depth: number): Promise<DereferencedElement>;
+    /**
+     * Dereferences the target of a reference as the expected type and records the transclusion.
+     */
+    protected addTransclusion(path: Path<Element>, target: DereferenceTarget<TContext>, spec: TransclusionSpec): Promise<void>;
+    /**
+     * Records the transclusion of a referencing element with a target that isn't dereferenced:
+     * the target as the expected type is attached as it is, e.g. an Operation Object to the Link
+     * Object pointing at it. Attached targets never form cycles.
+     */
+    protected addAttachment(path: Path<Element>, target: DereferenceTarget<TContext>, toTranscludedElement: TransclusionSpec['toTranscludedElement']): Promise<void>;
+    /**
+     * Transcludes every referencing element within the element with its dereferenced target.
+     */
+    protected transclude(element: Element): Element;
+    /**
+     * The element transcluded in place of a referencing element.
+     */
+    protected toTranscludedElement(referencingElement: Element, transclusion: Transclusion): Element;
+    /**
+     * Whether the element is transcluded in place of a referencing element, in this run or,
+     * when dereferencing in place, in an earlier one: transcluded elements carry the `ref-type` meta,
+     * which only dereferencing sets (bundling annotates hoisted elements with `ref-origin` only).
+     */
+    protected isTranscluded(element: Element): boolean;
+    /**
+     * Dereferenced in place, a source may already hold transcluded elements.
+     */
+    enter(path: Path<Element>): void;
+}
+export default DereferenceVisitor;

package/types/dereference/strategies/arazzo-1/index.d.ts

@@ -13,7 +13,6 @@ export type { default as Parser, ParserOptions } from '../../../parse/parsers/Pa
 export type { default as Resolver, ResolverOptions } from '../../../resolve/resolvers/Resolver.ts';
 export type { default as ResolveStrategy, ResolveStrategyOptions, } from '../../../resolve/strategies/ResolveStrategy.ts';
 export type { default as BundleStrategy, BundleStrategyOptions, } from '../../../bundle/strategies/BundleStrategy.ts';
-export type { AncestorLineage } from '../../util.ts';
 /**
  * @public
  */

package/types/dereference/strategies/arazzo-1/visitor.d.ts

@@ -1,70 +1,70 @@
 import { Element } from '@speclynx/apidom-datamodel';
 import { type Path } from '@speclynx/apidom-traverse';
 import { type Schema$idIndex } from './selectors/uri.ts';
+import DereferenceVisitor from '../DereferenceVisitor.ts';
 import Reference from '../../../Reference.ts';
-import { AncestorLineage } from '../../util.ts';
 import type { ReferenceOptions } from '../../../options/index.ts';
+/**
+ * Context of a source being dereferenced: the `$id`s of the JSON Schema elements enclosing it.
+ */
+interface Arazzo1DereferenceContext {
+    readonly ancestorSchema$ids: string[];
+}
 /**
  * @public
  */
 export interface Arazzo1DereferenceVisitorOptions {
     readonly reference: Reference;
     readonly options: ReferenceOptions;
-    readonly indirections?: Element[];
     readonly schema$idIndex?: Schema$idIndex;
-    readonly ancestors?: AncestorLineage<Element>;
-    readonly visited?: WeakSet<Element>;
     readonly ancestorSchema$ids?: string[];
 }
 /**
+ * Dereferences an Arazzo document. Reusable Objects expect the type of their
+ * `referenced-element` meta, JSON Schema `$ref`s expect a JSON Schema.
+ *
  * @public
  */
-declare class Arazzo1DereferenceVisitor {
-    protected readonly indirections: Element[];
-    protected readonly reference: Reference;
-    /**
-     * Base URI of the current document for resolving relative references.
-     * Honors the Arazzo `$self` field when present, otherwise falls back
-     * to the retrieval URI (`this.reference.uri`).
-     */
-    protected readonly baseURI: string;
-    protected readonly options: ReferenceOptions;
+declare class Arazzo1DereferenceVisitor extends DereferenceVisitor<Arazzo1DereferenceContext> {
     /**
-     * Index of `$id`-bearing schemas per document, shared across nested visitors
-     * of a single dereference run so it never outlives mutations of the documents.
+     * Index of `$id`-bearing schemas per document, shared across the visitors
+     * of a single dereference run.
      */
     protected readonly schema$idIndex: Schema$idIndex;
-    protected readonly visited: WeakSet<Element>;
     /**
      * `$id`s of the JSON Schema elements enclosing the traversal root within its
      * document (outermost first). Empty when the root is the document itself; a
-     * nested visitor traversing a fragment is seeded with the `$id`s of the
-     * schemas the fragment sits under, so the `$ref`s and `$id`s within resolve
-     * against the same base as they would from the document root.
+     * visitor traversing a fragment is seeded with the `$id`s of the schemas the
+     * fragment sits under, so the `$ref`s and `$id`s within resolve against the
+     * same base as they would from the document root.
      */
     protected readonly ancestorSchema$ids: string[];
+    constructor({ reference, options, schema$idIndex, ancestorSchema$ids, }: Arazzo1DereferenceVisitorOptions);
+    protected get strategyName(): string;
+    protected createVisitor(reference: Reference, { ancestorSchema$ids }: Arazzo1DereferenceContext): Arazzo1DereferenceVisitor;
+    protected refractTo(element: Element, type: string): Element;
+    protected isOfType(element: Element, type: string): boolean;
+    /**
+     * Honors the Arazzo `$self` field when present, otherwise falls back to the retrieval URI.
+     */
+    protected toDocumentBaseURI(reference: Reference): string;
+    /**
+     * Identity-based referencing: URI matches `$self` of an already processed Arazzo document.
+     */
+    protected findReferenceByIdentity(uri: string): Reference | undefined;
     /**
-     * Tracks element ancestors across dive-deep traversal boundaries.
-     * Used for cycle detection: if a referenced element is found in
-     * the ancestor lineage, a circular reference is detected.
+     * A document as JSON Schema for locating schemas within it: a generic document is
+     * refracted to JSON Schema once per dereference run, a semantic one is used as it is.
      */
-    protected readonly ancestors: AncestorLineage<Element>;
-    constructor({ reference, options, indirections, schema$idIndex, ancestors, visited, ancestorSchema$ids, }: Arazzo1DereferenceVisitorOptions);
-    protected toAncestorLineage(path: Path<Element>): [AncestorLineage<Element>, Set<Element>];
-    protected toBaseURI(uri: string): string;
-    protected toReference(uri: string): Promise<Reference>;
+    protected toJSONSchemaDocument(document: Element): Element;
     /**
-     * Handles an error according to the continueOnError option.
-     *
-     * For new errors: wraps in UnresolvableReferenceError with structured context
-     * (type, uri, location, codeFrame, refFieldName, refFieldValue, trace).
-     * 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).
+     * Indexes the `$id`-bearing schemas of a document for the run. Transcluded elements aren't
+     * indexed: they're copies of structures indexed where they're defined,
+     * and in a document dereferenced in place their shared structure would be walked once per path.
      */
-    protected handleError(message: string, error: Error, referencingElement: Element, refFieldName: string, refFieldValue: string, visitorPath: Path<Element>): void;
-    ReusableElement(path: Path<Element>): void;
+    protected index$ids(element: Element): void;
+    enter(path: Path<Element>): void;
+    ReusableElement(path: Path<Element>): Promise<void>;
     JSONSchemaElement(path: Path<Element>): Promise<void>;
 }
 export default Arazzo1DereferenceVisitor;

package/types/dereference/strategies/asyncapi-2/index.d.ts

@@ -13,7 +13,6 @@ export type { default as Parser, ParserOptions } from '../../../parse/parsers/Pa
 export type { default as Resolver, ResolverOptions } from '../../../resolve/resolvers/Resolver.ts';
 export type { default as ResolveStrategy, ResolveStrategyOptions, } from '../../../resolve/strategies/ResolveStrategy.ts';
 export type { default as BundleStrategy, BundleStrategyOptions, } from '../../../bundle/strategies/BundleStrategy.ts';
-export type { AncestorLineage } from '../../util.ts';
 /**
  * @public
  */

package/types/dereference/strategies/asyncapi-2/visitor.d.ts

@@ -1,6 +1,6 @@
 import { Element } from '@speclynx/apidom-datamodel';
-import { type Path } from '@speclynx/apidom-traverse';
-import { AncestorLineage } from '../../util.ts';
+import type { Path } from '@speclynx/apidom-traverse';
+import DereferenceVisitor from '../DereferenceVisitor.ts';
 import Reference from '../../../Reference.ts';
 import type { ReferenceOptions } from '../../../options/index.ts';
 /**
@@ -9,41 +9,25 @@ import type { ReferenceOptions } from '../../../options/index.ts';
 export interface AsyncAPI2DereferenceVisitorOptions {
     readonly reference: Reference;
     readonly options: ReferenceOptions;
-    readonly indirections?: Element[];
-    readonly refractCache?: WeakMap<Element, Element>;
-    readonly ancestors?: AncestorLineage<Element>;
-    readonly visited?: WeakSet<Element>;
 }
 /**
+ * Dereferences an AsyncAPI 2 document. Reference Objects expect the type of their
+ * `referenced-element` meta, Channel Item `$ref`s a Channel Item Object.
+ *
  * @public
  */
-declare class AsyncAPI2DereferenceVisitor {
-    protected readonly indirections: Element[];
-    protected readonly reference: Reference;
-    protected readonly options: ReferenceOptions;
-    protected readonly refractCache: WeakMap<Element, Element>;
-    protected readonly visited: WeakSet<Element>;
+declare class AsyncAPI2DereferenceVisitor extends DereferenceVisitor<undefined> {
+    protected get strategyName(): string;
+    protected createVisitor(reference: Reference): AsyncAPI2DereferenceVisitor;
     /**
-     * Tracks element ancestors across dive-deep traversal boundaries.
-     * Used for cycle detection: if a referenced element is found in
-     * the ancestor lineage, a circular reference is detected.
+     * A Reference Object stands for the type its reference expects: it's dereferenced as that type.
      */
-    protected readonly ancestors: AncestorLineage<Element>;
-    constructor({ reference, options, indirections, ancestors, refractCache, visited, }: AsyncAPI2DereferenceVisitorOptions);
-    protected toAncestorLineage(path: Path<Element>): [AncestorLineage<Element>, Set<Element>];
-    protected toBaseURI(uri: string): string;
-    protected toReference(uri: string): Promise<Reference>;
+    protected isOfType(element: Element, type: string): boolean;
     /**
-     * Handles an error according to the continueOnError option.
-     *
-     * For new errors: wraps in UnresolvableReferenceError with structured context
-     * (type, uri, location, codeFrame, refFieldName, refFieldValue, trace).
-     * 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).
+     * A generic structure holding a `$ref` is a Reference Object to the expected type,
+     * unless the type has its own `$ref` field (Channel Item Object).
      */
-    protected handleError(message: string, error: Error, referencingElement: Element, refFieldName: string, refFieldValue: string, visitorPath: Path<Element>): void;
+    protected refractTo(element: Element, type: string): Element;
     ReferenceElement(path: Path<Element>): Promise<void>;
     ChannelItemElement(path: Path<Element>): Promise<void>;
 }

package/types/dereference/strategies/openapi-2/index.d.ts

@@ -13,7 +13,6 @@ export type { default as Parser, ParserOptions } from '../../../parse/parsers/Pa
 export type { default as Resolver, ResolverOptions } from '../../../resolve/resolvers/Resolver.ts';
 export type { default as ResolveStrategy, ResolveStrategyOptions, } from '../../../resolve/strategies/ResolveStrategy.ts';
 export type { default as BundleStrategy, BundleStrategyOptions, } from '../../../bundle/strategies/BundleStrategy.ts';
-export type { AncestorLineage } from '../../util.ts';
 export type { AsyncAPI2DereferenceVisitorOptions } from '../asyncapi-2/visitor.ts';
 /**
  * @public

package/types/dereference/strategies/openapi-2/visitor.d.ts

@@ -1,6 +1,6 @@
 import { Element } from '@speclynx/apidom-datamodel';
-import { type Path } from '@speclynx/apidom-traverse';
-import { AncestorLineage } from '../../util.ts';
+import type { Path } from '@speclynx/apidom-traverse';
+import DereferenceVisitor from '../DereferenceVisitor.ts';
 import Reference from '../../../Reference.ts';
 import type { ReferenceOptions } from '../../../options/index.ts';
 /**
@@ -9,41 +9,26 @@ import type { ReferenceOptions } from '../../../options/index.ts';
 export interface OpenAPI2DereferenceVisitorOptions {
     readonly reference: Reference;
     readonly options: ReferenceOptions;
-    readonly indirections?: Element[];
-    readonly refractCache?: WeakMap<Element, Element>;
-    readonly ancestors?: AncestorLineage<Element>;
-    readonly visited?: WeakSet<Element>;
 }
 /**
+ * Dereferences an OpenAPI 2.0 document. Reference Objects and JSON Reference Objects expect
+ * the type of their `referenced-element` meta, Path Item `$ref`s a Path Item Object.
+ *
  * @public
  */
-declare class OpenAPI2DereferenceVisitor {
-    protected readonly indirections: Element[];
-    protected readonly reference: Reference;
-    protected readonly options: ReferenceOptions;
-    protected readonly refractCache: WeakMap<Element, Element>;
-    protected readonly visited: WeakSet<Element>;
+declare class OpenAPI2DereferenceVisitor extends DereferenceVisitor<undefined> {
+    protected get strategyName(): string;
+    protected createVisitor(reference: Reference): OpenAPI2DereferenceVisitor;
     /**
-     * Tracks element ancestors across dive-deep traversal boundaries.
-     * Used for cycle detection: if a referenced element is found in
-     * the ancestor lineage, a circular reference is detected.
+     * A (JSON) Reference Object stands for the type its reference expects: it's dereferenced as that type.
      */
-    protected readonly ancestors: AncestorLineage<Element>;
-    constructor({ reference, options, indirections, ancestors, refractCache, visited, }: OpenAPI2DereferenceVisitorOptions);
-    protected toAncestorLineage(path: Path<Element>): [AncestorLineage<Element>, Set<Element>];
-    protected toBaseURI(uri: string): string;
-    protected toReference(uri: string): Promise<Reference>;
+    protected isOfType(element: Element, type: string): boolean;
     /**
-     * Handles an error according to the continueOnError option.
-     *
-     * For new errors: wraps in UnresolvableReferenceError with structured context
-     * (type, uri, location, codeFrame, refFieldName, refFieldValue, trace).
-     * 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).
+     * A generic structure holding a `$ref` is a reference to the expected type: a JSON Reference
+     * Object for a Schema Object, a Reference Object otherwise, unless the type has its own `$ref`
+     * field (Path Item Object).
      */
-    protected handleError(message: string, error: Error, referencingElement: Element, refFieldName: string, refFieldValue: string, visitorPath: Path<Element>): void;
+    protected refractTo(element: Element, type: string): Element;
     ReferenceElement(path: Path<Element>): Promise<void>;
     PathItemElement(path: Path<Element>): Promise<void>;
     JSONReferenceElement(path: Path<Element>): Promise<void>;

package/types/dereference/strategies/openapi-3-0/index.d.ts

@@ -13,7 +13,6 @@ export type { default as Parser, ParserOptions } from '../../../parse/parsers/Pa
 export type { default as Resolver, ResolverOptions } from '../../../resolve/resolvers/Resolver.ts';
 export type { default as ResolveStrategy, ResolveStrategyOptions, } from '../../../resolve/strategies/ResolveStrategy.ts';
 export type { default as BundleStrategy, BundleStrategyOptions, } from '../../../bundle/strategies/BundleStrategy.ts';
-export type { AncestorLineage } from '../../util.ts';
 /**
  * @public
  */

package/types/dereference/strategies/openapi-3-0/visitor.d.ts

@@ -1,7 +1,7 @@
 import { Element } from '@speclynx/apidom-datamodel';
 import { type Path } from '@speclynx/apidom-traverse';
+import DereferenceVisitor from '../DereferenceVisitor.ts';
 import Reference from '../../../Reference.ts';
-import { AncestorLineage } from '../../util.ts';
 import type { ReferenceOptions } from '../../../options/index.ts';
 /**
  * @public
@@ -9,41 +9,26 @@ import type { ReferenceOptions } from '../../../options/index.ts';
 export interface OpenAPI3_0DereferenceVisitorOptions {
     readonly reference: Reference;
     readonly options: ReferenceOptions;
-    readonly indirections?: Element[];
-    readonly refractCache?: WeakMap<Element, Element>;
-    readonly ancestors?: AncestorLineage<Element>;
-    readonly visited?: WeakSet<Element>;
 }
 /**
+ * Dereferences an OpenAPI 3.0 document. Reference Objects expect the type of their
+ * `referenced-element` meta, Path Item `$ref`s a Path Item Object. Link Objects get the
+ * Operation Object they point at attached, Example Objects the external value.
+ *
  * @public
  */
-declare class OpenAPI3_0DereferenceVisitor {
-    protected readonly indirections: Element[];
-    protected readonly reference: Reference;
-    protected readonly options: ReferenceOptions;
-    protected readonly refractCache: WeakMap<Element, Element>;
-    protected readonly visited: WeakSet<Element>;
+declare class OpenAPI3_0DereferenceVisitor extends DereferenceVisitor<undefined> {
+    protected get strategyName(): string;
+    protected createVisitor(reference: Reference): OpenAPI3_0DereferenceVisitor;
     /**
-     * Tracks element ancestors across dive-deep traversal boundaries.
-     * Used for cycle detection: if a referenced element is found in
-     * the ancestor lineage, a circular reference is detected.
+     * A Reference Object stands for the type its reference expects: it's dereferenced as that type.
      */
-    protected readonly ancestors: AncestorLineage<Element>;
-    constructor({ reference, options, indirections, ancestors, refractCache, visited, }: OpenAPI3_0DereferenceVisitorOptions);
-    protected toAncestorLineage(path: Path<Element>): [AncestorLineage<Element>, Set<Element>];
-    protected toBaseURI(uri: string): string;
-    protected toReference(uri: string): Promise<Reference>;
+    protected isOfType(element: Element, type: string): boolean;
     /**
-     * Handles an error according to the continueOnError option.
-     *
-     * For new errors: wraps in UnresolvableReferenceError with structured context
-     * (type, uri, location, codeFrame, refFieldName, refFieldValue, trace).
-     * 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).
+     * A generic structure holding a `$ref` is a Reference Object to the expected type,
+     * unless the type has its own `$ref` field (Path Item Object).
      */
-    protected handleError(message: string, error: Error, referencingElement: Element, refFieldName: string, refFieldValue: string, visitorPath: Path<Element>): void;
+    protected refractTo(element: Element, type: string): Element;
     ReferenceElement(path: Path<Element>): Promise<void>;
     PathItemElement(path: Path<Element>): Promise<void>;
     LinkElement(path: Path<Element>): Promise<void>;

package/types/dereference/strategies/openapi-3-1/index.d.ts

@@ -13,7 +13,6 @@ export type { default as Parser, ParserOptions } from '../../../parse/parsers/Pa
 export type { default as Resolver, ResolverOptions } from '../../../resolve/resolvers/Resolver.ts';
 export type { default as ResolveStrategy, ResolveStrategyOptions, } from '../../../resolve/strategies/ResolveStrategy.ts';
 export type { default as BundleStrategy, BundleStrategyOptions, } from '../../../bundle/strategies/BundleStrategy.ts';
-export type { AncestorLineage } from '../../util.ts';
 /**
  * @public
  */