@speclynx/apidom-reference 4.2.0 → 4.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-reference",
-  "version": "4.2.0",
+  "version": "4.3.1",
   "description": "Advanced algorithms for semantic ApiDOM manipulations like dereferencing or resolution.",
   "keywords": [
     "apidom",
@@ -87,6 +87,16 @@
       "require": "./src/resolve/strategies/asyncapi-2/index.cjs",
       "types": "./types/resolve/strategies/asyncapi-2/index.d.ts"
     },
+    "./resolve/strategies/arazzo-1": {
+      "import": "./src/resolve/strategies/arazzo-1/index.mjs",
+      "require": "./src/resolve/strategies/arazzo-1/index.cjs",
+      "types": "./types/resolve/strategies/arazzo-1/index.d.ts"
+    },
+    "./resolve/strategies/overlay-1": {
+      "import": "./src/resolve/strategies/overlay-1/index.mjs",
+      "require": "./src/resolve/strategies/overlay-1/index.cjs",
+      "types": "./types/resolve/strategies/overlay-1/index.d.ts"
+    },
     "./resolve/strategies/openapi-2": {
       "import": "./src/resolve/strategies/openapi-2/index.mjs",
       "require": "./src/resolve/strategies/openapi-2/index.cjs",
@@ -122,6 +132,16 @@
       "require": "./src/parse/parsers/arazzo-yaml-1/index.cjs",
       "types": "./types/parse/parsers/arazzo-yaml-1/index.d.ts"
     },
+    "./parse/parsers/overlay-json-1": {
+      "import": "./src/parse/parsers/overlay-json-1/index.mjs",
+      "require": "./src/parse/parsers/overlay-json-1/index.cjs",
+      "types": "./types/parse/parsers/overlay-json-1/index.d.ts"
+    },
+    "./parse/parsers/overlay-yaml-1": {
+      "import": "./src/parse/parsers/overlay-yaml-1/index.mjs",
+      "require": "./src/parse/parsers/overlay-yaml-1/index.cjs",
+      "types": "./types/parse/parsers/overlay-yaml-1/index.d.ts"
+    },
     "./parse/parsers/apidom-json": {
       "import": "./src/parse/parsers/apidom-json/index.mjs",
       "require": "./src/parse/parsers/apidom-json/index.cjs",
@@ -199,6 +219,11 @@
       "require": "./src/dereference/strategies/arazzo-1/index.cjs",
       "types": "./types/dereference/strategies/arazzo-1/index.d.ts"
     },
+    "./dereference/strategies/overlay-1": {
+      "import": "./src/dereference/strategies/overlay-1/index.mjs",
+      "require": "./src/dereference/strategies/overlay-1/index.cjs",
+      "types": "./types/dereference/strategies/overlay-1/index.d.ts"
+    },
     "./dereference/strategies/openapi-2": {
       "import": "./src/dereference/strategies/openapi-2/index.mjs",
       "require": "./src/dereference/strategies/openapi-2/index.cjs",
@@ -254,38 +279,41 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime-corejs3": "^7.28.4",
-    "@speclynx/apidom-core": "4.2.0",
-    "@speclynx/apidom-datamodel": "4.2.0",
-    "@speclynx/apidom-error": "4.2.0",
-    "@speclynx/apidom-json-pointer": "4.2.0",
-    "@speclynx/apidom-ns-arazzo-1": "4.2.0",
-    "@speclynx/apidom-ns-asyncapi-2": "4.2.0",
-    "@speclynx/apidom-ns-json-schema-2020-12": "4.2.0",
-    "@speclynx/apidom-ns-openapi-2": "4.2.0",
-    "@speclynx/apidom-ns-openapi-3-0": "4.2.0",
-    "@speclynx/apidom-ns-openapi-3-1": "4.2.0",
-    "@speclynx/apidom-parser-adapter-arazzo-json-1": "4.2.0",
-    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "4.2.0",
-    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "4.2.0",
-    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "4.2.0",
-    "@speclynx/apidom-parser-adapter-json": "4.2.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-2": "4.2.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "4.2.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "4.2.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "4.2.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "4.2.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "4.2.0",
-    "@speclynx/apidom-parser-adapter-yaml-1-2": "4.2.0",
-    "@speclynx/apidom-traverse": "4.2.0",
+    "@speclynx/apidom-core": "4.3.1",
+    "@speclynx/apidom-datamodel": "4.3.1",
+    "@speclynx/apidom-error": "4.3.1",
+    "@speclynx/apidom-json-pointer": "4.3.1",
+    "@speclynx/apidom-ns-arazzo-1": "4.3.1",
+    "@speclynx/apidom-ns-asyncapi-2": "4.3.1",
+    "@speclynx/apidom-ns-json-schema-2020-12": "4.3.1",
+    "@speclynx/apidom-ns-openapi-2": "4.3.1",
+    "@speclynx/apidom-ns-openapi-3-0": "4.3.1",
+    "@speclynx/apidom-ns-openapi-3-1": "4.3.1",
+    "@speclynx/apidom-ns-overlay-1": "4.3.1",
+    "@speclynx/apidom-parser-adapter-arazzo-json-1": "4.3.1",
+    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "4.3.1",
+    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "4.3.1",
+    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "4.3.1",
+    "@speclynx/apidom-parser-adapter-json": "4.3.1",
+    "@speclynx/apidom-parser-adapter-openapi-json-2": "4.3.1",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "4.3.1",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "4.3.1",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "4.3.1",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "4.3.1",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "4.3.1",
+    "@speclynx/apidom-parser-adapter-overlay-json-1": "4.3.1",
+    "@speclynx/apidom-parser-adapter-overlay-yaml-1": "4.3.1",
+    "@speclynx/apidom-parser-adapter-yaml-1-2": "4.3.1",
+    "@speclynx/apidom-traverse": "4.3.1",
     "@swaggerexpert/arazzo-runtime-expression": "^2.0.3",
-    "axios": "^1.13.5",
-    "picomatch": "^4.0.3",
+    "axios": "^1.14.0",
+    "picomatch": "^4.0.4",
     "process": "^0.11.10",
     "ramda": "~0.32.0",
     "ramda-adjunct": "^6.0.0"
   },
   "devDependencies": {
-    "@types/picomatch": "^4.0.2",
+    "@types/picomatch": "^4.0.3",
     "axios-mock-adapter": "^2.0.0"
   },
   "files": [
@@ -298,5 +326,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "3485d180340f2d4fad149bcf062a6f618030ca9b"
+  "gitHead": "3082a613a41b54b74ad4b53946385c0bd8247b9b"
 }

package/src/configuration/saturated.cjs

@@ -8,41 +8,40 @@ var _index2 = _interopRequireDefault(require("../resolve/strategies/openapi-2/in
 var _index3 = _interopRequireDefault(require("../resolve/strategies/openapi-3-0/index.cjs"));
 var _index4 = _interopRequireDefault(require("../resolve/strategies/openapi-3-1/index.cjs"));
 var _index5 = _interopRequireDefault(require("../resolve/strategies/asyncapi-2/index.cjs"));
-var _index6 = _interopRequireDefault(require("../resolve/strategies/apidom/index.cjs"));
-var _index7 = _interopRequireDefault(require("../parse/parsers/openapi-json-2/index.cjs"));
-var _index8 = _interopRequireDefault(require("../parse/parsers/openapi-yaml-2/index.cjs"));
-var _index9 = _interopRequireDefault(require("../parse/parsers/openapi-json-3-0/index.cjs"));
-var _index0 = _interopRequireDefault(require("../parse/parsers/openapi-yaml-3-0/index.cjs"));
-var _index1 = _interopRequireDefault(require("../parse/parsers/openapi-json-3-1/index.cjs"));
-var _index10 = _interopRequireDefault(require("../parse/parsers/openapi-yaml-3-1/index.cjs"));
-var _index11 = _interopRequireDefault(require("../parse/parsers/asyncapi-json-2/index.cjs"));
-var _index12 = _interopRequireDefault(require("../parse/parsers/asyncapi-yaml-2/index.cjs"));
-var _index13 = _interopRequireDefault(require("../parse/parsers/arazzo-json-1/index.cjs"));
-var _index14 = _interopRequireDefault(require("../parse/parsers/arazzo-yaml-1/index.cjs"));
-var _index15 = _interopRequireDefault(require("../parse/parsers/apidom-json/index.cjs"));
-var _index16 = _interopRequireDefault(require("../parse/parsers/json/index.cjs"));
-var _index17 = _interopRequireDefault(require("../parse/parsers/yaml-1-2/index.cjs"));
+var _index6 = _interopRequireDefault(require("../resolve/strategies/arazzo-1/index.cjs"));
+var _index7 = _interopRequireDefault(require("../resolve/strategies/overlay-1/index.cjs"));
+var _index8 = _interopRequireDefault(require("../resolve/strategies/apidom/index.cjs"));
+var _index9 = _interopRequireDefault(require("../parse/parsers/openapi-json-2/index.cjs"));
+var _index0 = _interopRequireDefault(require("../parse/parsers/openapi-yaml-2/index.cjs"));
+var _index1 = _interopRequireDefault(require("../parse/parsers/openapi-json-3-0/index.cjs"));
+var _index10 = _interopRequireDefault(require("../parse/parsers/openapi-yaml-3-0/index.cjs"));
+var _index11 = _interopRequireDefault(require("../parse/parsers/openapi-json-3-1/index.cjs"));
+var _index12 = _interopRequireDefault(require("../parse/parsers/openapi-yaml-3-1/index.cjs"));
+var _index13 = _interopRequireDefault(require("../parse/parsers/asyncapi-json-2/index.cjs"));
+var _index14 = _interopRequireDefault(require("../parse/parsers/asyncapi-yaml-2/index.cjs"));
+var _index15 = _interopRequireDefault(require("../parse/parsers/arazzo-json-1/index.cjs"));
+var _index16 = _interopRequireDefault(require("../parse/parsers/arazzo-yaml-1/index.cjs"));
+var _index17 = _interopRequireDefault(require("../parse/parsers/overlay-json-1/index.cjs"));
+var _index18 = _interopRequireDefault(require("../parse/parsers/overlay-yaml-1/index.cjs"));
+var _index19 = _interopRequireDefault(require("../parse/parsers/apidom-json/index.cjs"));
+var _index20 = _interopRequireDefault(require("../parse/parsers/json/index.cjs"));
+var _index21 = _interopRequireDefault(require("../parse/parsers/yaml-1-2/index.cjs"));
 var _indexNode2 = _interopRequireDefault(require("../parse/parsers/binary/index-node.cjs"));
-var _index18 = _interopRequireDefault(require("../dereference/strategies/apidom/index.cjs"));
-var _index19 = _interopRequireDefault(require("../dereference/strategies/openapi-2/index.cjs"));
-var _index20 = _interopRequireDefault(require("../dereference/strategies/openapi-3-0/index.cjs"));
-var _index21 = _interopRequireDefault(require("../dereference/strategies/openapi-3-1/index.cjs"));
-var _index22 = _interopRequireDefault(require("../dereference/strategies/asyncapi-2/index.cjs"));
-var _index23 = _interopRequireDefault(require("../dereference/strategies/arazzo-1/index.cjs"));
-var _index24 = _interopRequireDefault(require("../bundle/strategies/openapi-3-1/index.cjs"));
-var _index25 = require("../index.cjs");
-Object.keys(_index25).forEach(function (key) {
+var _index22 = _interopRequireDefault(require("../dereference/strategies/apidom/index.cjs"));
+var _index23 = _interopRequireDefault(require("../dereference/strategies/openapi-2/index.cjs"));
+var _index24 = _interopRequireDefault(require("../dereference/strategies/openapi-3-0/index.cjs"));
+var _index25 = _interopRequireDefault(require("../dereference/strategies/openapi-3-1/index.cjs"));
+var _index26 = _interopRequireDefault(require("../dereference/strategies/asyncapi-2/index.cjs"));
+var _index27 = _interopRequireDefault(require("../dereference/strategies/arazzo-1/index.cjs"));
+var _index28 = _interopRequireDefault(require("../dereference/strategies/overlay-1/index.cjs"));
+var _index29 = _interopRequireDefault(require("../bundle/strategies/openapi-3-1/index.cjs"));
+var _index30 = require("../index.cjs");
+Object.keys(_index30).forEach(function (key) {
   if (key === "default" || key === "__esModule") return;
-  if (key in exports && exports[key] === _index25[key]) return;
-  exports[key] = _index25[key];
+  if (key in exports && exports[key] === _index30[key]) return;
+  exports[key] = _index30[key];
 });
-_index25.options.parse.parsers = [new _index7.default({
-  allowEmpty: true,
-  sourceMap: false
-}), new _index8.default({
-  allowEmpty: true,
-  sourceMap: false
-}), new _index9.default({
+_index30.options.parse.parsers = [new _index9.default({
   allowEmpty: true,
   sourceMap: false
 }), new _index0.default({
@@ -75,14 +74,26 @@ _index25.options.parse.parsers = [new _index7.default({
 }), new _index17.default({
   allowEmpty: true,
   sourceMap: false
+}), new _index18.default({
+  allowEmpty: true,
+  sourceMap: false
+}), new _index19.default({
+  allowEmpty: true,
+  sourceMap: false
+}), new _index20.default({
+  allowEmpty: true,
+  sourceMap: false
+}), new _index21.default({
+  allowEmpty: true,
+  sourceMap: false
 }), new _indexNode2.default({
   allowEmpty: true
 })];
-_index25.options.resolve.resolvers = [new _indexNode.default(), new _index.default({
+_index30.options.resolve.resolvers = [new _indexNode.default(), new _index.default({
   timeout: 5000,
   redirects: 5,
   withCredentials: false
 })];
-_index25.options.resolve.strategies = [new _index2.default(), new _index3.default(), new _index4.default(), new _index5.default(), new _index6.default()];
-_index25.options.dereference.strategies = [new _index19.default(), new _index20.default(), new _index21.default(), new _index22.default(), new _index23.default(), new _index18.default()];
-_index25.options.bundle.strategies = [new _index24.default()];
+_index30.options.resolve.strategies = [new _index2.default(), new _index3.default(), new _index4.default(), new _index5.default(), new _index6.default(), new _index7.default(), new _index8.default()];
+_index30.options.dereference.strategies = [new _index23.default(), new _index24.default(), new _index25.default(), new _index26.default(), new _index27.default(), new _index28.default(), new _index22.default()];
+_index30.options.bundle.strategies = [new _index29.default()];

package/src/configuration/saturated.mjs

@@ -4,6 +4,8 @@ import OpenAPI2ResolveStrategy from "../resolve/strategies/openapi-2/index.mjs";
 import OpenAPI3_0ResolveStrategy from "../resolve/strategies/openapi-3-0/index.mjs";
 import OpenAPI3_1ResolveStrategy from "../resolve/strategies/openapi-3-1/index.mjs";
 import AsyncAPI2ResolveStrategy from "../resolve/strategies/asyncapi-2/index.mjs";
+import Arazzo1ResolveStrategy from "../resolve/strategies/arazzo-1/index.mjs";
+import Overlay1ResolveStrategy from "../resolve/strategies/overlay-1/index.mjs";
 import ApiDOMResolveStrategy from "../resolve/strategies/apidom/index.mjs";
 import OpenAPIJSON2Parser from "../parse/parsers/openapi-json-2/index.mjs";
 import OpenAPIYAML2Parser from "../parse/parsers/openapi-yaml-2/index.mjs";
@@ -15,6 +17,8 @@ import AsyncAPIJSON2Parser from "../parse/parsers/asyncapi-json-2/index.mjs";
 import AsyncAPIYAML2Parser from "../parse/parsers/asyncapi-yaml-2/index.mjs";
 import ArazzoJSON1Parser from "../parse/parsers/arazzo-json-1/index.mjs";
 import ArazzoYAML1Parser from "../parse/parsers/arazzo-yaml-1/index.mjs";
+import OverlayJSON1Parser from "../parse/parsers/overlay-json-1/index.mjs";
+import OverlayYAML1Parser from "../parse/parsers/overlay-yaml-1/index.mjs";
 import APIDOMJSONParser from "../parse/parsers/apidom-json/index.mjs";
 import JSONParser from "../parse/parsers/json/index.mjs";
 import YAMLParser from "../parse/parsers/yaml-1-2/index.mjs";
@@ -25,6 +29,7 @@ import OpenAPI3_0DereferenceStrategy from "../dereference/strategies/openapi-3-0
 import OpenAPI3_1DereferenceStrategy from "../dereference/strategies/openapi-3-1/index.mjs";
 import AsyncAPI2DereferenceStrategy from "../dereference/strategies/asyncapi-2/index.mjs";
 import Arazzo1DereferenceStrategy from "../dereference/strategies/arazzo-1/index.mjs";
+import Overlay1DereferenceStrategy from "../dereference/strategies/overlay-1/index.mjs";
 import OpenAPI3_1BundleStrategy from "../bundle/strategies/openapi-3-1/index.mjs";
 import { options } from "../index.mjs";
 options.parse.parsers = [new OpenAPIJSON2Parser({
@@ -57,6 +62,12 @@ options.parse.parsers = [new OpenAPIJSON2Parser({
 }), new ArazzoYAML1Parser({
   allowEmpty: true,
   sourceMap: false
+}), new OverlayJSON1Parser({
+  allowEmpty: true,
+  sourceMap: false
+}), new OverlayYAML1Parser({
+  allowEmpty: true,
+  sourceMap: false
 }), new APIDOMJSONParser({
   allowEmpty: true,
   sourceMap: false
@@ -74,7 +85,7 @@ options.resolve.resolvers = [new FileResolver(), new HTTPResolverAxios({
   redirects: 5,
   withCredentials: false
 })];
-options.resolve.strategies = [new OpenAPI2ResolveStrategy(), new OpenAPI3_0ResolveStrategy(), new OpenAPI3_1ResolveStrategy(), new AsyncAPI2ResolveStrategy(), new ApiDOMResolveStrategy()];
-options.dereference.strategies = [new OpenAPI2DereferenceStrategy(), new OpenAPI3_0DereferenceStrategy(), new OpenAPI3_1DereferenceStrategy(), new AsyncAPI2DereferenceStrategy(), new Arazzo1DereferenceStrategy(), new ApiDOMDereferenceStrategy()];
+options.resolve.strategies = [new OpenAPI2ResolveStrategy(), new OpenAPI3_0ResolveStrategy(), new OpenAPI3_1ResolveStrategy(), new AsyncAPI2ResolveStrategy(), new Arazzo1ResolveStrategy(), new Overlay1ResolveStrategy(), new ApiDOMResolveStrategy()];
+options.dereference.strategies = [new OpenAPI2DereferenceStrategy(), new OpenAPI3_0DereferenceStrategy(), new OpenAPI3_1DereferenceStrategy(), new AsyncAPI2DereferenceStrategy(), new Arazzo1DereferenceStrategy(), new Overlay1DereferenceStrategy(), new ApiDOMDereferenceStrategy()];
 options.bundle.strategies = [new OpenAPI3_1BundleStrategy()];
 export * from "../index.mjs";

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

@@ -81,8 +81,13 @@ class Arazzo1DereferenceStrategy extends _DereferenceStrategy.default {
      */
     const shouldDereferenceSourceDescriptions = options?.dereference?.strategyOpts?.[this.name]?.sourceDescriptions ?? options?.dereference?.strategyOpts?.sourceDescriptions;
     if (shouldDereferenceSourceDescriptions) {
-      const sourceDescriptions = await (0, _sourceDescriptions.dereferenceSourceDescriptions)(dereferencedElement, reference.uri, options, this.name);
-      dereferencedElement.push(...sourceDescriptions);
+      const parseResult = dereferencedElement;
+
+      // drop any existing parse-phase source description results before pushing
+      const cleaned = parseResult.reject(item => (0, _apidomDatamodel.isParseResultElement)(item) && (0, _apidomDatamodel.includesClasses)(item, ['source-description']));
+      parseResult.content = cleaned.content;
+      const sourceDescriptions = await (0, _sourceDescriptions.dereferenceSourceDescriptions)(parseResult, reference.uri, options, this.name);
+      parseResult.push(...sourceDescriptions);
     }
 
     /**

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

@@ -1,4 +1,4 @@
-import { cloneDeep } from '@speclynx/apidom-datamodel';
+import { cloneDeep, isParseResultElement, includesClasses } from '@speclynx/apidom-datamodel';
 import { traverseAsync } from '@speclynx/apidom-traverse';
 import { isArazzoSpecification1Element, mediaTypes } from '@speclynx/apidom-ns-arazzo-1';
 import DereferenceStrategy from "../DereferenceStrategy.mjs";
@@ -69,8 +69,13 @@ class Arazzo1DereferenceStrategy extends DereferenceStrategy {
      */
     const shouldDereferenceSourceDescriptions = options?.dereference?.strategyOpts?.[this.name]?.sourceDescriptions ?? options?.dereference?.strategyOpts?.sourceDescriptions;
     if (shouldDereferenceSourceDescriptions) {
-      const sourceDescriptions = await dereferenceSourceDescriptions(dereferencedElement, reference.uri, options, this.name);
-      dereferencedElement.push(...sourceDescriptions);
+      const parseResult = dereferencedElement;
+
+      // drop any existing parse-phase source description results before pushing
+      const cleaned = parseResult.reject(item => isParseResultElement(item) && includesClasses(item, ['source-description']));
+      parseResult.content = cleaned.content;
+      const sourceDescriptions = await dereferenceSourceDescriptions(parseResult, reference.uri, options, this.name);
+      parseResult.push(...sourceDescriptions);
     }
 
     /**

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

@@ -0,0 +1,93 @@
+"use strict";
+
+var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.dereferenceExtends = dereferenceExtends;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomNsOverlay = require("@speclynx/apidom-ns-overlay-1");
+var _apidomCore = require("@speclynx/apidom-core");
+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"));
+/**
+ * Dereferences the `extends` target document from an Overlay document's ParseResult.
+ *
+ * If the extends element already has a parsed result attached (from the parse phase),
+ * it will be dereferenced in place. Otherwise, the target document will be fetched,
+ * parsed, and dereferenced.
+ *
+ * The dereferenced result is pushed into the overlay's ParseResult
+ * and always attached to the extends element's meta as 'parseResult',
+ * overriding any existing parse result from the parse phase.
+ * On failure, the result contains error annotations.
+ *
+ * @param parseResult - ParseResult containing an Overlay specification
+ * @param parseResultRetrievalURI - URI from which the parseResult was retrieved
+ * @param options - Full ReferenceOptions
+ *
+ * @public
+ */
+async function dereferenceExtends(parseResult, parseResultRetrievalURI, options) {
+  const {
+    api
+  } = parseResult;
+  const file = new _File.default({
+    uri: url.sanitize(url.stripHash(parseResultRetrievalURI))
+  });
+  if (!(0, _apidomNsOverlay.isOverlay1Element)(api)) {
+    return;
+  }
+  const extendsElement = api.get('extends');
+  if (!(0, _apidomDatamodel.isStringElement)(extendsElement)) {
+    return;
+  }
+  const extendsURI = (0, _apidomCore.toValue)(extendsElement);
+  const retrievalURI = url.sanitize(url.stripHash(url.resolve(file.uri, extendsURI)));
+  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
+        }
+      }));
+    }
+
+    // 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)
+  extendsElement.meta.set('parseResult', extendsDereferenceResult);
+
+  // drop any existing parse-phase extends results before pushing
+  const cleaned = parseResult.reject(item => (0, _apidomDatamodel.isParseResultElement)(item) && (0, _apidomDatamodel.includesClasses)(item, ['extends']));
+  parseResult.content = cleaned.content;
+  parseResult.push(extendsDereferenceResult);
+}

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

@@ -0,0 +1,87 @@
+import { ParseResultElement, AnnotationElement, isStringElement, isParseResultElement, includesClasses } from '@speclynx/apidom-datamodel';
+import { isOverlay1Element } from '@speclynx/apidom-ns-overlay-1';
+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 dereference, { dereferenceApiDOM } from "../../index.mjs";
+/**
+ * Dereferences the `extends` target document from an Overlay document's ParseResult.
+ *
+ * If the extends element already has a parsed result attached (from the parse phase),
+ * it will be dereferenced in place. Otherwise, the target document will be fetched,
+ * parsed, and dereferenced.
+ *
+ * The dereferenced result is pushed into the overlay's ParseResult
+ * and always attached to the extends element's meta as 'parseResult',
+ * overriding any existing parse result from the parse phase.
+ * On failure, the result contains error annotations.
+ *
+ * @param parseResult - ParseResult containing an Overlay specification
+ * @param parseResultRetrievalURI - URI from which the parseResult was retrieved
+ * @param options - Full ReferenceOptions
+ *
+ * @public
+ */
+export async function dereferenceExtends(parseResult, parseResultRetrievalURI, options) {
+  const {
+    api
+  } = parseResult;
+  const file = new File({
+    uri: url.sanitize(url.stripHash(parseResultRetrievalURI))
+  });
+  if (!isOverlay1Element(api)) {
+    return;
+  }
+  const extendsElement = api.get('extends');
+  if (!isStringElement(extendsElement)) {
+    return;
+  }
+  const extendsURI = toValue(extendsElement);
+  const retrievalURI = url.sanitize(url.stripHash(url.resolve(file.uri, extendsURI)));
+  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
+        }
+      }));
+    }
+
+    // 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)
+  extendsElement.meta.set('parseResult', extendsDereferenceResult);
+
+  // drop any existing parse-phase extends results before pushing
+  const cleaned = parseResult.reject(item => isParseResultElement(item) && includesClasses(item, ['extends']));
+  parseResult.content = cleaned.content;
+  parseResult.push(extendsDereferenceResult);
+}

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

@@ -0,0 +1,93 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomNsOverlay = require("@speclynx/apidom-ns-overlay-1");
+var _DereferenceStrategy = _interopRequireDefault(require("../DereferenceStrategy.cjs"));
+var _Reference = _interopRequireDefault(require("../../../Reference.cjs"));
+var _ReferenceSet = _interopRequireDefault(require("../../../ReferenceSet.cjs"));
+var _extends = require("./extends.cjs");
+exports.dereferenceExtends = _extends.dereferenceExtends;
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class Overlay1DereferenceStrategy extends _DereferenceStrategy.default {
+  constructor(options) {
+    super({
+      ...(options ?? {}),
+      name: 'overlay-1'
+    });
+  }
+  canDereference(file) {
+    // assert by media type
+    if (file.mediaType !== 'text/plain') {
+      return _apidomNsOverlay.mediaTypes.includes(file.mediaType);
+    }
+
+    // assert by inspecting ApiDOM
+    return (0, _apidomNsOverlay.isOverlay1Element)(file.parseResult?.result);
+  }
+  async dereference(file, options) {
+    const immutableRefSet = options.dereference.refSet ?? new _ReferenceSet.default();
+    const mutableRefSet = new _ReferenceSet.default();
+    let reference;
+    if (!immutableRefSet.has(file.uri)) {
+      reference = new _Reference.default({
+        uri: file.uri,
+        value: file.parseResult
+      });
+      immutableRefSet.add(reference);
+    } else {
+      // pre-computed refSet was provided as configuration option
+      reference = immutableRefSet.find(ref => ref.uri === file.uri);
+    }
+
+    /**
+     * Clone refSet due the dereferencing process being mutable.
+     * We don't want to mutate the original refSet and the references.
+     */
+    if (options.dereference.immutable) {
+      immutableRefSet.refs.map(ref => new _Reference.default({
+        ...ref,
+        value: (0, _apidomDatamodel.cloneDeep)(ref.value)
+      })).forEach(ref => mutableRefSet.add(ref));
+      reference = mutableRefSet.find(ref => ref.uri === file.uri);
+    }
+    const dereferencedElement = reference.value;
+
+    /**
+     * Dereference extends target if option is enabled.
+     */
+    const shouldDereferenceExtends = options?.dereference?.strategyOpts?.[this.name]?.extends ?? options?.dereference?.strategyOpts?.extends;
+    if (shouldDereferenceExtends) {
+      await (0, _extends.dereferenceExtends)(dereferencedElement, reference.uri, options);
+    }
+
+    /**
+     * If immutable option is set, replay refs from the refSet.
+     */
+    if (options.dereference.immutable) {
+      mutableRefSet.refs.filter(ref => ref.uri.startsWith('immutable://')).map(ref => new _Reference.default({
+        ...ref,
+        uri: ref.uri.replace(/^immutable:\/\//, '')
+      })).forEach(ref => immutableRefSet.add(ref));
+    }
+
+    /**
+     * Release all memory if this refSet was not provided as a configuration option.
+     * If provided as configuration option, then provider is responsible for cleanup.
+     */
+    if (options.dereference.refSet === null) {
+      immutableRefSet.clean();
+    }
+    mutableRefSet.clean();
+    return dereferencedElement;
+  }
+}
+var _default = exports.default = Overlay1DereferenceStrategy;