@speclynx/apidom-reference 6.1.0 → 6.1.1

package/src/dereference/strategies/openapi-3-0/visitor.mjs

@@ -194,6 +194,11 @@ class OpenAPI3_0DereferenceVisitor {
   async ReferenceElement(path) {
     const referencingElement = path.node;
 
+    // ignore Reference Object without a string $ref, e.g. an empty YAML value
+    if (!isStringElement(referencingElement.$ref)) {
+      return;
+    }
+
     // skip current referencing element as it's already been access
     if (this.indirections.includes(referencingElement)) {
       path.skip();

package/src/dereference/strategies/openapi-3-1/visitor.cjs

@@ -228,6 +228,11 @@ class OpenAPI3_1DereferenceVisitor {
   async ReferenceElement(path) {
     const referencingElement = path.node;
 
+    // ignore Reference Object without a string $ref, e.g. an empty YAML value
+    if (!(0, _apidomDatamodel.isStringElement)(referencingElement.$ref)) {
+      return;
+    }
+
     // skip current referencing element as it's already been accessed
     if (this.indirections.includes(referencingElement)) {
       path.skip();

package/src/dereference/strategies/openapi-3-1/visitor.mjs

@@ -219,6 +219,11 @@ class OpenAPI3_1DereferenceVisitor {
   async ReferenceElement(path) {
     const referencingElement = path.node;
 
+    // ignore Reference Object without a string $ref, e.g. an empty YAML value
+    if (!isStringElement(referencingElement.$ref)) {
+      return;
+    }
+
     // skip current referencing element as it's already been accessed
     if (this.indirections.includes(referencingElement)) {
       path.skip();

package/src/dereference/strategies/overlay-1/extends.cjs

@@ -13,6 +13,8 @@ var _File = _interopRequireDefault(require("../../../File.cjs"));
 var url = _interopRequireWildcard(require("../../../util/url.cjs"));
 var _util = require("../../../options/util.cjs");
 var _index = _interopRequireWildcard(require("../../index.cjs"));
+const STRATEGY_NAME = 'overlay-1';
+
 /**
  * Dereferences the `extends` target document from an Overlay document's ParseResult.
  *
@@ -54,39 +56,61 @@ async function dereferenceExtends(parseResult, parseResultRetrievalURI, options)
   const extendsDereferenceResult = new _apidomDatamodel.ParseResultElement();
   extendsDereferenceResult.classes.push('extends');
   extendsDereferenceResult.setMetaProperty('retrievalURI', retrievalURI);
-  try {
-    let extendsDereferenced;
 
-    // check if extends was already parsed (e.g., during parse phase with extends: true)
-    const existingParseResult = extendsElement.meta.get('parseResult');
-    if ((0, _apidomDatamodel.isParseResultElement)(existingParseResult)) {
-      // use existing parsed result - just dereference it (no re-fetch/re-parse)
-      extendsDereferenced = await (0, _index.dereferenceApiDOM)(existingParseResult, (0, _util.merge)(options, {
-        parse: {
-          mediaType: 'text/plain' // allow dereference strategy detection via ApiDOM inspection
-        },
-        resolve: {
-          baseURI: retrievalURI
-        }
-      }));
-    } else {
-      // no existing parse result - fetch, parse, and dereference
-      extendsDereferenced = await (0, _index.default)(retrievalURI, (0, _util.merge)(options, {
-        parse: {
-          mediaType: 'text/plain' // allow parser plugin detection
+  // URIs of the Overlays currently being dereferenced, from the root down to the current one
+  const ancestors = [...(options?.dereference?.strategyOpts?.[STRATEGY_NAME]?.extendsAncestors ?? []), file.uri];
+  const nestedOptions = {
+    dereference: {
+      strategyOpts: {
+        [STRATEGY_NAME]: {
+          extendsAncestors: ancestors
         }
-      }));
+      }
     }
+  };
 
-    // merge dereferenced result into our wrapper
-    for (const item of extendsDereferenced) {
-      extendsDereferenceResult.push(item);
-    }
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    const annotation = new _apidomDatamodel.AnnotationElement(`Error dereferencing extends target "${retrievalURI}": ${message}`);
-    annotation.classes.push('error');
+  // skip if the target is still being dereferenced higher up the chain (cycle detection)
+  if (ancestors.includes(retrievalURI)) {
+    const annotation = new _apidomDatamodel.AnnotationElement(`Extends target "${retrievalURI}" has already been visited. Skipping to prevent cycle`);
+    annotation.classes.push('warning');
     extendsDereferenceResult.push(annotation);
+  } else {
+    try {
+      let extendsDereferenced;
+
+      // check if extends was already parsed (e.g., during parse phase with extends: true)
+      const existingParseResult = extendsElement.meta.get('parseResult');
+      if ((0, _apidomDatamodel.isParseResultElement)(existingParseResult)) {
+        // use existing parsed result - just dereference it (no re-fetch/re-parse)
+        extendsDereferenced = await (0, _index.dereferenceApiDOM)(existingParseResult, (0, _util.merge)(options, {
+          ...nestedOptions,
+          parse: {
+            mediaType: 'text/plain' // allow dereference strategy detection via ApiDOM inspection
+          },
+          resolve: {
+            baseURI: retrievalURI
+          }
+        }));
+      } else {
+        // no existing parse result - fetch, parse, and dereference
+        extendsDereferenced = await (0, _index.default)(retrievalURI, (0, _util.merge)(options, {
+          ...nestedOptions,
+          parse: {
+            mediaType: 'text/plain' // allow parser plugin detection
+          }
+        }));
+      }
+
+      // merge dereferenced result into our wrapper
+      for (const item of extendsDereferenced) {
+        extendsDereferenceResult.push(item);
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const annotation = new _apidomDatamodel.AnnotationElement(`Error dereferencing extends target "${retrievalURI}": ${message}`);
+      annotation.classes.push('error');
+      extendsDereferenceResult.push(annotation);
+    }
   }
 
   // always attach result to extends element meta (even on failure - contains annotations)

package/src/dereference/strategies/overlay-1/extends.mjs

@@ -5,6 +5,8 @@ import File from "../../../File.mjs";
 import * as url from "../../../util/url.mjs";
 import { merge as mergeOptions } from "../../../options/util.mjs";
 import dereference, { dereferenceApiDOM } from "../../index.mjs";
+const STRATEGY_NAME = 'overlay-1';
+
 /**
  * Dereferences the `extends` target document from an Overlay document's ParseResult.
  *
@@ -46,39 +48,61 @@ export async function dereferenceExtends(parseResult, parseResultRetrievalURI, o
   const extendsDereferenceResult = new ParseResultElement();
   extendsDereferenceResult.classes.push('extends');
   extendsDereferenceResult.setMetaProperty('retrievalURI', retrievalURI);
-  try {
-    let extendsDereferenced;
 
-    // check if extends was already parsed (e.g., during parse phase with extends: true)
-    const existingParseResult = extendsElement.meta.get('parseResult');
-    if (isParseResultElement(existingParseResult)) {
-      // use existing parsed result - just dereference it (no re-fetch/re-parse)
-      extendsDereferenced = await dereferenceApiDOM(existingParseResult, mergeOptions(options, {
-        parse: {
-          mediaType: 'text/plain' // allow dereference strategy detection via ApiDOM inspection
-        },
-        resolve: {
-          baseURI: retrievalURI
-        }
-      }));
-    } else {
-      // no existing parse result - fetch, parse, and dereference
-      extendsDereferenced = await dereference(retrievalURI, mergeOptions(options, {
-        parse: {
-          mediaType: 'text/plain' // allow parser plugin detection
+  // URIs of the Overlays currently being dereferenced, from the root down to the current one
+  const ancestors = [...(options?.dereference?.strategyOpts?.[STRATEGY_NAME]?.extendsAncestors ?? []), file.uri];
+  const nestedOptions = {
+    dereference: {
+      strategyOpts: {
+        [STRATEGY_NAME]: {
+          extendsAncestors: ancestors
         }
-      }));
+      }
     }
+  };
 
-    // merge dereferenced result into our wrapper
-    for (const item of extendsDereferenced) {
-      extendsDereferenceResult.push(item);
-    }
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    const annotation = new AnnotationElement(`Error dereferencing extends target "${retrievalURI}": ${message}`);
-    annotation.classes.push('error');
+  // skip if the target is still being dereferenced higher up the chain (cycle detection)
+  if (ancestors.includes(retrievalURI)) {
+    const annotation = new AnnotationElement(`Extends target "${retrievalURI}" has already been visited. Skipping to prevent cycle`);
+    annotation.classes.push('warning');
     extendsDereferenceResult.push(annotation);
+  } else {
+    try {
+      let extendsDereferenced;
+
+      // check if extends was already parsed (e.g., during parse phase with extends: true)
+      const existingParseResult = extendsElement.meta.get('parseResult');
+      if (isParseResultElement(existingParseResult)) {
+        // use existing parsed result - just dereference it (no re-fetch/re-parse)
+        extendsDereferenced = await dereferenceApiDOM(existingParseResult, mergeOptions(options, {
+          ...nestedOptions,
+          parse: {
+            mediaType: 'text/plain' // allow dereference strategy detection via ApiDOM inspection
+          },
+          resolve: {
+            baseURI: retrievalURI
+          }
+        }));
+      } else {
+        // no existing parse result - fetch, parse, and dereference
+        extendsDereferenced = await dereference(retrievalURI, mergeOptions(options, {
+          ...nestedOptions,
+          parse: {
+            mediaType: 'text/plain' // allow parser plugin detection
+          }
+        }));
+      }
+
+      // merge dereferenced result into our wrapper
+      for (const item of extendsDereferenced) {
+        extendsDereferenceResult.push(item);
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const annotation = new AnnotationElement(`Error dereferencing extends target "${retrievalURI}": ${message}`);
+      annotation.classes.push('error');
+      extendsDereferenceResult.push(annotation);
+    }
   }
 
   // always attach result to extends element meta (even on failure - contains annotations)

package/src/dereference/strategies/overlay-1/index.cjs

@@ -74,25 +74,37 @@ class Overlay1DereferenceStrategy extends _DereferenceStrategy.default {
       })).forEach(ref => mutableRefSet.add(ref));
       reference = mutableRefSet.find(ref => ref.uri === file.uri);
     }
-    const dereferencedElement = reference.value;
-
-    /**
-     * Reusable Action References only occur within `actions`, so the root element is never
-     * replaced and traversing it keeps reported locations relative to the document.
-     */
     const visitor = new _visitor.default({
       reference,
       options
     });
-    await (0, _apidomTraverse.traverseAsync)(dereferencedElement.result, visitor, {
-      mutable: true
-    });
+    /**
+     * The reference for the dereferenced file is traversed rather than the refSet's root
+     * reference: dereferencing the extends target shares the refSet, whose root is then
+     * the extending Overlay. The reference may hold a lone element.
+     */
+    let dereferencedElement = reference.value;
+
+    /**
+     * A ParseResult may also carry the extends target parsed in the parse phase, whose
+     * references belong to that document, so only its result is traversed. Reusable Action
+     * References only occur within `actions`, so the result itself is never replaced.
+     */
+    if ((0, _apidomDatamodel.isParseResultElement)(dereferencedElement)) {
+      await (0, _apidomTraverse.traverseAsync)(dereferencedElement.result, visitor, {
+        mutable: true
+      });
+    } else {
+      dereferencedElement = await (0, _apidomTraverse.traverseAsync)(dereferencedElement, visitor, {
+        mutable: true
+      });
+    }
 
     /**
      * Dereference extends target if option is enabled.
      */
     const shouldDereferenceExtends = options?.dereference?.strategyOpts?.[this.name]?.extends ?? options?.dereference?.strategyOpts?.extends;
-    if (shouldDereferenceExtends) {
+    if (shouldDereferenceExtends && (0, _apidomDatamodel.isParseResultElement)(dereferencedElement)) {
       await (0, _extends.dereferenceExtends)(dereferencedElement, reference.uri, options);
     }
 

package/src/dereference/strategies/overlay-1/index.mjs

@@ -1,4 +1,4 @@
-import { cloneDeep } from '@speclynx/apidom-datamodel';
+import { cloneDeep, isParseResultElement } from '@speclynx/apidom-datamodel';
 import { isOverlay1Element, mediaTypes } from '@speclynx/apidom-ns-overlay-1';
 import { traverseAsync } from '@speclynx/apidom-traverse';
 import DereferenceStrategy from "../DereferenceStrategy.mjs";
@@ -54,25 +54,37 @@ class Overlay1DereferenceStrategy extends DereferenceStrategy {
       })).forEach(ref => mutableRefSet.add(ref));
       reference = mutableRefSet.find(ref => ref.uri === file.uri);
     }
-    const dereferencedElement = reference.value;
-
-    /**
-     * Reusable Action References only occur within `actions`, so the root element is never
-     * replaced and traversing it keeps reported locations relative to the document.
-     */
     const visitor = new Overlay1DereferenceVisitor({
       reference,
       options
     });
-    await traverseAsync(dereferencedElement.result, visitor, {
-      mutable: true
-    });
+    /**
+     * The reference for the dereferenced file is traversed rather than the refSet's root
+     * reference: dereferencing the extends target shares the refSet, whose root is then
+     * the extending Overlay. The reference may hold a lone element.
+     */
+    let dereferencedElement = reference.value;
+
+    /**
+     * A ParseResult may also carry the extends target parsed in the parse phase, whose
+     * references belong to that document, so only its result is traversed. Reusable Action
+     * References only occur within `actions`, so the result itself is never replaced.
+     */
+    if (isParseResultElement(dereferencedElement)) {
+      await traverseAsync(dereferencedElement.result, visitor, {
+        mutable: true
+      });
+    } else {
+      dereferencedElement = await traverseAsync(dereferencedElement, visitor, {
+        mutable: true
+      });
+    }
 
     /**
      * Dereference extends target if option is enabled.
      */
     const shouldDereferenceExtends = options?.dereference?.strategyOpts?.[this.name]?.extends ?? options?.dereference?.strategyOpts?.extends;
-    if (shouldDereferenceExtends) {
+    if (shouldDereferenceExtends && isParseResultElement(dereferencedElement)) {
       await dereferenceExtends(dereferencedElement, reference.uri, options);
     }
 

package/src/dereference/strategies/overlay-1/visitor.cjs

@@ -1,5 +1,6 @@
 "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
@@ -9,8 +10,10 @@ var _apidomDatamodel = require("@speclynx/apidom-datamodel");
 var _apidomCore = require("@speclynx/apidom-core");
 var _apidomError = require("@speclynx/apidom-error");
 var _apidomJsonPointer = require("@speclynx/apidom-json-pointer");
+var _apidomTraverse = require("@speclynx/apidom-traverse");
 var _apidomNsOverlay = require("@speclynx/apidom-ns-overlay-1");
 var _UnresolvableReferenceError = _interopRequireDefault(require("../../../errors/UnresolvableReferenceError.cjs"));
+var url = _interopRequireWildcard(require("../../../util/url.cjs"));
 /**
  * @public
  */
@@ -37,7 +40,14 @@ class Overlay1DereferenceVisitor {
       return;
     }
     const $ref = (0, _apidomCore.toValue)(referencingElement.$ref);
-    const overlayElement = this.reference.value.result;
+    // the reference may hold a lone element; same-document references resolve against the
+    // document registered in the refSet under the reference's URI without fragment
+    const {
+      refSet
+    } = this.reference;
+    const documentURI = url.stripHash(this.reference.uri);
+    const documentReference = refSet.find(ref => ref.uri === documentURI) ?? this.reference;
+    const overlayElement = documentReference.value.result;
     const actionElement = new _apidomNsOverlay.ActionElement();
     try {
       if (typeof $ref !== 'string') {
@@ -108,11 +118,26 @@ class Overlay1DereferenceVisitor {
       const {
         continueOnError
       } = this.options.dereference;
+
+      // find element location by identity in the document tree;
+      // falls back to the visitor path when the document doesn't contain the element
+      let location;
+      if ((0, _apidomDatamodel.isElement)(overlayElement)) {
+        (0, _apidomTraverse.traverse)(overlayElement, {
+          enter: p => {
+            if (p.node === referencingElement) {
+              location = p.formatPath();
+              p.stop();
+            }
+          }
+        });
+      }
+      location ??= path.formatPath();
       const unresolvedError = new _UnresolvableReferenceError.default(`Error while dereferencing Reusable Action Reference "${$ref}": ${error.message}`, {
         cause: error,
         type: referencingElement.element,
         uri: this.reference.uri,
-        location: path.formatPath(),
+        location,
         codeFrame: (0, _apidomCore.toYAML)(referencingElement),
         refFieldName: '$ref',
         refFieldValue: $ref,

package/src/dereference/strategies/overlay-1/visitor.mjs

@@ -1,9 +1,11 @@
-import { SourceMapElement, cloneDeep, hasElementSourceMap } from '@speclynx/apidom-datamodel';
+import { SourceMapElement, cloneDeep, hasElementSourceMap, isElement } from '@speclynx/apidom-datamodel';
 import { toValue, toYAML } from '@speclynx/apidom-core';
 import { ApiDOMStructuredError } from '@speclynx/apidom-error';
 import { evaluate as jsonPointerEvaluate, URIFragmentIdentifier } from '@speclynx/apidom-json-pointer';
+import { traverse } from '@speclynx/apidom-traverse';
 import { ActionElement, isActionElement, isReusableActionElement } from '@speclynx/apidom-ns-overlay-1';
 import UnresolvableReferenceError from "../../../errors/UnresolvableReferenceError.mjs";
+import * as url from "../../../util/url.mjs";
 /**
  * @public
  */
@@ -29,7 +31,14 @@ class Overlay1DereferenceVisitor {
       return;
     }
     const $ref = toValue(referencingElement.$ref);
-    const overlayElement = this.reference.value.result;
+    // the reference may hold a lone element; same-document references resolve against the
+    // document registered in the refSet under the reference's URI without fragment
+    const {
+      refSet
+    } = this.reference;
+    const documentURI = url.stripHash(this.reference.uri);
+    const documentReference = refSet.find(ref => ref.uri === documentURI) ?? this.reference;
+    const overlayElement = documentReference.value.result;
     const actionElement = new ActionElement();
     try {
       if (typeof $ref !== 'string') {
@@ -100,11 +109,26 @@ class Overlay1DereferenceVisitor {
       const {
         continueOnError
       } = this.options.dereference;
+
+      // find element location by identity in the document tree;
+      // falls back to the visitor path when the document doesn't contain the element
+      let location;
+      if (isElement(overlayElement)) {
+        traverse(overlayElement, {
+          enter: p => {
+            if (p.node === referencingElement) {
+              location = p.formatPath();
+              p.stop();
+            }
+          }
+        });
+      }
+      location ??= path.formatPath();
       const unresolvedError = new UnresolvableReferenceError(`Error while dereferencing Reusable Action Reference "${$ref}": ${error.message}`, {
         cause: error,
         type: referencingElement.element,
         uri: this.reference.uri,
-        location: path.formatPath(),
+        location,
         codeFrame: toYAML(referencingElement),
         refFieldName: '$ref',
         refFieldValue: $ref,

package/src/parse/parsers/overlay-json-1/extends.cjs

@@ -13,6 +13,9 @@ var _File = _interopRequireDefault(require("../../../File.cjs"));
 var url = _interopRequireWildcard(require("../../../util/url.cjs"));
 var _util = require("../../../options/util.cjs");
 var _index = _interopRequireDefault(require("../../index.cjs"));
+// shared key for recursion state (works across JSON/YAML parsers)
+const OVERLAY_RECURSION_KEY = 'overlay-1';
+
 /**
  * Parses the `extends` target document from an Overlay document's ParseResult.
  *
@@ -49,21 +52,38 @@ async function parseExtends(parseResult, parseResultRetrievalURI, options) {
   const extendsParseResult = new _apidomDatamodel.ParseResultElement();
   extendsParseResult.classes.push('extends');
   extendsParseResult.setMetaProperty('retrievalURI', retrievalURI);
-  try {
-    const targetParseResult = await (0, _index.default)(retrievalURI, (0, _util.merge)(options, {
-      parse: {
-        mediaType: 'text/plain' // force auto-detection
+
+  // URIs of the Overlays currently being parsed, from the root down to the current one
+  const ancestors = [...(options?.parse?.parserOpts?.[OVERLAY_RECURSION_KEY]?.extendsAncestors ?? []), file.uri];
+
+  // skip if the target is still being parsed higher up the chain (cycle detection)
+  if (ancestors.includes(retrievalURI)) {
+    const annotation = new _apidomDatamodel.AnnotationElement(`Extends target "${retrievalURI}" has already been visited. Skipping to prevent cycle`);
+    annotation.classes.push('warning');
+    extendsParseResult.push(annotation);
+  } else {
+    try {
+      const targetParseResult = await (0, _index.default)(retrievalURI, (0, _util.merge)(options, {
+        parse: {
+          mediaType: 'text/plain',
+          // force auto-detection
+          parserOpts: {
+            [OVERLAY_RECURSION_KEY]: {
+              extendsAncestors: ancestors
+            }
+          }
+        }
+      }));
+      // merge parsed result into our wrapper
+      for (const item of targetParseResult) {
+        extendsParseResult.push(item);
       }
-    }));
-    // merge parsed result into our wrapper
-    for (const item of targetParseResult) {
-      extendsParseResult.push(item);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const annotation = new _apidomDatamodel.AnnotationElement(`Error parsing extends target "${retrievalURI}": ${message}`);
+      annotation.classes.push('error');
+      extendsParseResult.push(annotation);
     }
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    const annotation = new _apidomDatamodel.AnnotationElement(`Error parsing extends target "${retrievalURI}": ${message}`);
-    annotation.classes.push('error');
-    extendsParseResult.push(annotation);
   }
 
   // always attach result to extends element meta (even on failure - contains annotations)

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

@@ -4,7 +4,9 @@ import { toValue } from '@speclynx/apidom-core';
 import File from "../../../File.mjs";
 import * as url from "../../../util/url.mjs";
 import { merge as mergeOptions } from "../../../options/util.mjs";
-import parse from "../../index.mjs";
+import parse from "../../index.mjs"; // shared key for recursion state (works across JSON/YAML parsers)
+const OVERLAY_RECURSION_KEY = 'overlay-1';
+
 /**
  * Parses the `extends` target document from an Overlay document's ParseResult.
  *
@@ -41,21 +43,38 @@ export async function parseExtends(parseResult, parseResultRetrievalURI, options
   const extendsParseResult = new ParseResultElement();
   extendsParseResult.classes.push('extends');
   extendsParseResult.setMetaProperty('retrievalURI', retrievalURI);
-  try {
-    const targetParseResult = await parse(retrievalURI, mergeOptions(options, {
-      parse: {
-        mediaType: 'text/plain' // force auto-detection
+
+  // URIs of the Overlays currently being parsed, from the root down to the current one
+  const ancestors = [...(options?.parse?.parserOpts?.[OVERLAY_RECURSION_KEY]?.extendsAncestors ?? []), file.uri];
+
+  // skip if the target is still being parsed higher up the chain (cycle detection)
+  if (ancestors.includes(retrievalURI)) {
+    const annotation = new AnnotationElement(`Extends target "${retrievalURI}" has already been visited. Skipping to prevent cycle`);
+    annotation.classes.push('warning');
+    extendsParseResult.push(annotation);
+  } else {
+    try {
+      const targetParseResult = await parse(retrievalURI, mergeOptions(options, {
+        parse: {
+          mediaType: 'text/plain',
+          // force auto-detection
+          parserOpts: {
+            [OVERLAY_RECURSION_KEY]: {
+              extendsAncestors: ancestors
+            }
+          }
+        }
+      }));
+      // merge parsed result into our wrapper
+      for (const item of targetParseResult) {
+        extendsParseResult.push(item);
       }
-    }));
-    // merge parsed result into our wrapper
-    for (const item of targetParseResult) {
-      extendsParseResult.push(item);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const annotation = new AnnotationElement(`Error parsing extends target "${retrievalURI}": ${message}`);
+      annotation.classes.push('error');
+      extendsParseResult.push(annotation);
     }
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    const annotation = new AnnotationElement(`Error parsing extends target "${retrievalURI}": ${message}`);
-    annotation.classes.push('error');
-    extendsParseResult.push(annotation);
   }
 
   // always attach result to extends element meta (even on failure - contains annotations)

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

@@ -110,9 +110,14 @@ declare class OpenAPI3_0BundleVisitor {
      * Path Item Object is not a Components Object field in OpenAPI 3.0
      * (unlike 3.1 which has `components.pathItems`). An external Path Item
      * reference therefore cannot be hoisted; it is inlined in place instead,
-     * after bundling its own external references.
-     */
-    PathItemElement(path: Path<Element>): Promise<void>;
+     * after bundling its own external references. It is inlined on leave, once
+     * the sibling fields of the referencing Path Item have been bundled, so the
+     * traversal doesn't descend into the inlined copy and inline the `$ref` left
+     * in it to break a cycle again.
+     */
+    readonly PathItemElement: {
+        leave: (path: Path<Element>) => Promise<void>;
+    };
     /**
      * Example Object `externalValue` points at arbitrary external content that
      * has no place in the Components Object. The referenced value is inlined into

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

@@ -1,5 +1,5 @@
 import { Element } from '@speclynx/apidom-datamodel';
-import type { Path } from '@speclynx/apidom-traverse';
+import { type Path } from '@speclynx/apidom-traverse';
 import Reference from '../../../Reference.ts';
 import type { ReferenceOptions } from '../../../options/index.ts';
 /**