@speclynx/apidom-reference 6.1.2 → 7.0.0

package/src/parse/parsers/overlay-json-1/index.mjs

@@ -1,5 +1,6 @@
 import { pick } from 'ramda';
 import { parse, mediaTypes as OverlayJSON1MediaTypes, detect } from '@speclynx/apidom-parser-adapter-overlay-json-1';
+import { selectBestMatch } from '@swaggerexpert/media-types';
 import ParserError from "../../../errors/ParserError.mjs";
 import Parser from "../Parser.mjs";
 import { parseExtends } from "./extends.mjs";
@@ -29,7 +30,7 @@ class OverlayJSON1Parser 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/src/parse/parsers/overlay-yaml-1/index.cjs

@@ -13,6 +13,7 @@ Object.defineProperty(exports, "parseExtends", {
 });
 var _ramda = require("ramda");
 var _apidomParserAdapterOverlayYaml = require("@speclynx/apidom-parser-adapter-overlay-yaml-1");
+var _mediaTypes = require("@swaggerexpert/media-types");
 var _ParserError = _interopRequireDefault(require("../../../errors/ParserError.cjs"));
 var _Parser = _interopRequireDefault(require("../Parser.cjs"));
 var _extends = require("./extends.cjs");
@@ -43,7 +44,7 @@ class OverlayYAML1Parser 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/overlay-yaml-1/index.mjs

@@ -1,5 +1,6 @@
 import { pick } from 'ramda';
 import { parse, mediaTypes as OverlayYAML1MediaTypes, detect } from '@speclynx/apidom-parser-adapter-overlay-yaml-1';
+import { selectBestMatch } from '@swaggerexpert/media-types';
 import ParserError from "../../../errors/ParserError.mjs";
 import Parser from "../Parser.mjs";
 import { parseExtends } from "./extends.mjs";
@@ -29,7 +30,7 @@ class OverlayYAML1Parser 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/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/src/resolve/index.cjs

@@ -29,9 +29,10 @@ const resolveApiDOM = async (element, options) => {
     elementClone.classes.push('result');
     parseResult = new _apidomDatamodel.ParseResultElement([elementClone]);
   }
-  const sanitizedURI = url.sanitize(url.stripHash(options.resolve.baseURI));
+
+  // strategies look up same-document references by a resolved, hence normalized, URI
   const file = new _File.default({
-    uri: sanitizedURI,
+    uri: url.normalize(options.resolve.baseURI),
     parseResult,
     mediaType: options.parse.mediaType
   });
@@ -59,9 +60,11 @@ const resolveApiDOM = async (element, options) => {
 exports.resolveApiDOM = resolveApiDOM;
 const resolve = async (uri, options) => {
   const parseResult = await (0, _index.default)(uri, options);
+  // the file is parsed as a whole document, so its URI has no fragment
+  const baseURI = url.normalize(url.stripHash(uri));
   const mergedOptions = (0, _util.merge)(options, {
     resolve: {
-      baseURI: url.sanitize(uri)
+      baseURI
     }
   });
   return resolveApiDOM(parseResult, mergedOptions);

package/src/resolve/index.mjs

@@ -21,9 +21,10 @@ export const resolveApiDOM = async (element, options) => {
     elementClone.classes.push('result');
     parseResult = new ParseResultElement([elementClone]);
   }
-  const sanitizedURI = url.sanitize(url.stripHash(options.resolve.baseURI));
+
+  // strategies look up same-document references by a resolved, hence normalized, URI
   const file = new File({
-    uri: sanitizedURI,
+    uri: url.normalize(options.resolve.baseURI),
     parseResult,
     mediaType: options.parse.mediaType
   });
@@ -50,9 +51,11 @@ export const resolveApiDOM = async (element, options) => {
  */
 const resolve = async (uri, options) => {
   const parseResult = await parse(uri, options);
+  // the file is parsed as a whole document, so its URI has no fragment
+  const baseURI = url.normalize(url.stripHash(uri));
   const mergedOptions = mergeOptions(options, {
     resolve: {
-      baseURI: url.sanitize(uri)
+      baseURI
     }
   });
   return resolveApiDOM(parseResult, mergedOptions);

package/src/util/url.cjs

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.unsanitize = exports.toFileSystemPath = exports.stripHash = exports.sanitize = exports.resolve = exports.relative = exports.isURI = exports.isHttpUrl = exports.isFileSystemPath = exports.hasProtocol = exports.getProtocol = exports.getHash = exports.getExtension = exports.getBasename = exports.fromFileSystemPath = exports.cwd = void 0;
+exports.unsanitize = exports.toFileSystemPath = exports.stripHash = exports.sanitize = exports.resolve = exports.relative = exports.normalize = exports.isURI = exports.isHttpUrl = exports.isFileSystemPath = exports.hasProtocol = exports.getProtocol = exports.getHash = exports.getExtension = exports.getBasename = exports.fromFileSystemPath = exports.cwd = void 0;
 var _ramda = require("ramda");
 var _ramdaAdjunct = require("ramda-adjunct");
 /**
@@ -118,21 +118,23 @@ exports.isURI = isURI;
  */
 const toFileSystemPath = (uri, options) => {
   // RegExp patterns to URL-decode special characters for local filesystem paths
-  const urlDecodePatterns = [/%23/g, '#', /%24/g, '$', /%26/g, '&', /%2C/g, ',', /%40/g, '@'];
+  const urlDecodePatterns = [/%23/g, '#', /%24/g, '$', /%26/g, '&', /%2C/g, ',', /%3F/g, '?', /%40/g, '@'];
   const keepFileProtocol = (0, _ramda.propOr)(false, 'keepFileProtocol', options);
   const isWindowsPredicate = (0, _ramda.propOr)(isWindows, 'isWindows', options);
 
-  // Step 1: `decodeURI` will decode characters such as Cyrillic characters, spaces, etc.
-  let path = decodeURI(uri);
-
-  // Step 2: Manually decode characters that are not decoded by `decodeURI`.
+  // Step 1: Manually decode characters that are not decoded by `decodeURI`.
   // This includes characters such as "#" and "?", which have special meaning in URLs,
-  // but are just normal characters in a filesystem path.
+  // but are just normal characters in a filesystem path. It runs before `decodeURI`,
+  // so that an encoded "%" (e.g. "%253F") isn't decoded twice.
+  let path = uri;
   for (let i = 0; i < urlDecodePatterns.length; i += 2) {
     // @ts-ignore
     path = path.replace(urlDecodePatterns[i], urlDecodePatterns[i + 1]);
   }
 
+  // Step 2: `decodeURI` will decode characters such as Cyrillic characters, spaces, etc.
+  path = decodeURI(path);
+
   // Step 3: If it's a "file://" URL, then format it consistently
   // or convert it to a local filesystem path
   let isFileUrl = path.substring(0, 7).toLowerCase() === 'file://';
@@ -278,6 +280,34 @@ const resolve = (from, to) => {
   return resolvedUrl.toString();
 };
 
+/**
+ * Normalizes a URI the way `resolve` normalizes its result (WHATWG URL normalization):
+ * lowercases the scheme and the host of an absolute URL, drops a default port and
+ * removes dot segments. This is not RFC 3986 syntax-based normalization: existing
+ * percent-encoding is left as is. A file system path is sanitized first, so characters
+ * not allowed in URLs (e.g. spaces, `[`, `?`) are percent-encoded; a `file://` URL has
+ * its path sanitized the same way and stays a URL. The fragment is kept as given.
+ * A URI that can't be normalized is returned unchanged.
+ * @public
+ */
+exports.resolve = resolve;
+const normalize = uri => {
+  // getHash returns the root hash ('#') for a URI without fragment
+  const fragment = uri.includes('#') ? getHash(uri) : '';
+  const documentURI = stripHash(uri);
+  try {
+    let sanitizedURI = sanitize(documentURI);
+    // sanitize turns a file:// URL into a path; keep it a URL, as references
+    // resolved against it are, e.g. file:///C:/x.json rather than file://C:/x.json
+    if (getProtocol(documentURI) === 'file') {
+      sanitizedURI = `file://${sanitizedURI.startsWith('/') ? '' : '/'}${sanitizedURI}`;
+    }
+    return resolve('', sanitizedURI) + fragment;
+  } catch {
+    return uri;
+  }
+};
+
 /**
  * Computes the URI reference that resolves to `to` against `from` — the inverse
  * of `resolve`: `resolve(from, relative(from, to)) === to`. The reference is
@@ -287,7 +317,7 @@ const resolve = (from, to) => {
  * returned unchanged.
  * @public
  */
-exports.resolve = resolve;
+exports.normalize = normalize;
 const relative = (from, to) => {
   const fromURL = new URL(from, 'resolve://');
   const toURL = new URL(to, 'resolve://');

package/src/util/url.mjs

@@ -108,21 +108,23 @@ export const isURI = uri => {
  */
 export const toFileSystemPath = (uri, options) => {
   // RegExp patterns to URL-decode special characters for local filesystem paths
-  const urlDecodePatterns = [/%23/g, '#', /%24/g, '$', /%26/g, '&', /%2C/g, ',', /%40/g, '@'];
+  const urlDecodePatterns = [/%23/g, '#', /%24/g, '$', /%26/g, '&', /%2C/g, ',', /%3F/g, '?', /%40/g, '@'];
   const keepFileProtocol = propOr(false, 'keepFileProtocol', options);
   const isWindowsPredicate = propOr(isWindows, 'isWindows', options);
 
-  // Step 1: `decodeURI` will decode characters such as Cyrillic characters, spaces, etc.
-  let path = decodeURI(uri);
-
-  // Step 2: Manually decode characters that are not decoded by `decodeURI`.
+  // Step 1: Manually decode characters that are not decoded by `decodeURI`.
   // This includes characters such as "#" and "?", which have special meaning in URLs,
-  // but are just normal characters in a filesystem path.
+  // but are just normal characters in a filesystem path. It runs before `decodeURI`,
+  // so that an encoded "%" (e.g. "%253F") isn't decoded twice.
+  let path = uri;
   for (let i = 0; i < urlDecodePatterns.length; i += 2) {
     // @ts-ignore
     path = path.replace(urlDecodePatterns[i], urlDecodePatterns[i + 1]);
   }
 
+  // Step 2: `decodeURI` will decode characters such as Cyrillic characters, spaces, etc.
+  path = decodeURI(path);
+
   // Step 3: If it's a "file://" URL, then format it consistently
   // or convert it to a local filesystem path
   let isFileUrl = path.substring(0, 7).toLowerCase() === 'file://';
@@ -263,6 +265,33 @@ export const resolve = (from, to) => {
   return resolvedUrl.toString();
 };
 
+/**
+ * Normalizes a URI the way `resolve` normalizes its result (WHATWG URL normalization):
+ * lowercases the scheme and the host of an absolute URL, drops a default port and
+ * removes dot segments. This is not RFC 3986 syntax-based normalization: existing
+ * percent-encoding is left as is. A file system path is sanitized first, so characters
+ * not allowed in URLs (e.g. spaces, `[`, `?`) are percent-encoded; a `file://` URL has
+ * its path sanitized the same way and stays a URL. The fragment is kept as given.
+ * A URI that can't be normalized is returned unchanged.
+ * @public
+ */
+export const normalize = uri => {
+  // getHash returns the root hash ('#') for a URI without fragment
+  const fragment = uri.includes('#') ? getHash(uri) : '';
+  const documentURI = stripHash(uri);
+  try {
+    let sanitizedURI = sanitize(documentURI);
+    // sanitize turns a file:// URL into a path; keep it a URL, as references
+    // resolved against it are, e.g. file:///C:/x.json rather than file://C:/x.json
+    if (getProtocol(documentURI) === 'file') {
+      sanitizedURI = `file://${sanitizedURI.startsWith('/') ? '' : '/'}${sanitizedURI}`;
+    }
+    return resolve('', sanitizedURI) + fragment;
+  } catch {
+    return uri;
+  }
+};
+
 /**
  * Computes the URI reference that resolves to `to` against `from` — the inverse
  * of `resolve`: `resolve(from, relative(from, to)) === to`. The reference is

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
  */
@@ -359,6 +350,18 @@ export declare class MaximumResolveDepthError extends ResolveError {
  */
 export declare const mergeOptions: (lObj: ApiDOMReferenceOptions, rObj: Record<string, any>) => ApiDOMReferenceOptions;
 
+/**
+ * Normalizes a URI the way `resolve` normalizes its result (WHATWG URL normalization):
+ * lowercases the scheme and the host of an absolute URL, drops a default port and
+ * removes dot segments. This is not RFC 3986 syntax-based normalization: existing
+ * percent-encoding is left as is. A file system path is sanitized first, so characters
+ * not allowed in URLs (e.g. spaces, `[`, `?`) are percent-encoded; a `file://` URL has
+ * its path sanitized the same way and stays a URL. The fragment is kept as given.
+ * A URI that can't be normalized is returned unchanged.
+ * @public
+ */
+declare const normalize: (uri: string) => string;
+
 /**
  * @public
  */
@@ -658,6 +661,7 @@ declare namespace url {
         stripHash,
         cwd,
         resolve_2 as resolve,
+        normalize,
         relative,
         sanitize,
         unsanitize

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
  */