@speclynx/apidom-reference 4.2.0 → 4.3.1

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

@@ -0,0 +1,87 @@
+import { cloneDeep } from '@speclynx/apidom-datamodel';
+import { isOverlay1Element, mediaTypes } from '@speclynx/apidom-ns-overlay-1';
+import DereferenceStrategy from "../DereferenceStrategy.mjs";
+import Reference from "../../../Reference.mjs";
+import ReferenceSet from "../../../ReferenceSet.mjs";
+import { dereferenceExtends } from "./extends.mjs";
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+class Overlay1DereferenceStrategy extends DereferenceStrategy {
+  constructor(options) {
+    super({
+      ...(options ?? {}),
+      name: 'overlay-1'
+    });
+  }
+  canDereference(file) {
+    // assert by media type
+    if (file.mediaType !== 'text/plain') {
+      return mediaTypes.includes(file.mediaType);
+    }
+
+    // assert by inspecting ApiDOM
+    return isOverlay1Element(file.parseResult?.result);
+  }
+  async dereference(file, options) {
+    const immutableRefSet = options.dereference.refSet ?? new ReferenceSet();
+    const mutableRefSet = new ReferenceSet();
+    let reference;
+    if (!immutableRefSet.has(file.uri)) {
+      reference = new Reference({
+        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({
+        ...ref,
+        value: 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 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({
+        ...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;
+  }
+}
+export { dereferenceExtends } from "./extends.mjs";
+export default Overlay1DereferenceStrategy;

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

@@ -0,0 +1,66 @@
+"use strict";
+
+var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.parseExtends = parseExtends;
+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 = _interopRequireDefault(require("../../index.cjs"));
+/**
+ * Parses the `extends` target document from an Overlay document's ParseResult.
+ *
+ * The parsed extends document is pushed directly into the overlay's ParseResult
+ * and always attached to the extends element's meta as 'parseResult',
+ * regardless of success or failure.
+ *
+ * @param parseResult - ParseResult containing an Overlay specification
+ * @param parseResultRetrievalURI - URI from which the parseResult was retrieved
+ * @param options - Full ReferenceOptions
+ *
+ * @public
+ */
+async function parseExtends(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 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
+      }
+    }));
+    // 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);
+  }
+
+  // always attach result to extends element meta (even on failure - contains annotations)
+  extendsElement.meta.set('parseResult', extendsParseResult);
+  parseResult.push(extendsParseResult);
+}

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

@@ -0,0 +1,60 @@
+import { ParseResultElement, AnnotationElement, isStringElement } 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 parse from "../../index.mjs";
+/**
+ * Parses the `extends` target document from an Overlay document's ParseResult.
+ *
+ * The parsed extends document is pushed directly into the overlay's ParseResult
+ * and always attached to the extends element's meta as 'parseResult',
+ * regardless of success or failure.
+ *
+ * @param parseResult - ParseResult containing an Overlay specification
+ * @param parseResultRetrievalURI - URI from which the parseResult was retrieved
+ * @param options - Full ReferenceOptions
+ *
+ * @public
+ */
+export async function parseExtends(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 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
+      }
+    }));
+    // 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);
+  }
+
+  // always attach result to extends element meta (even on failure - contains annotations)
+  extendsElement.meta.set('parseResult', extendsParseResult);
+  parseResult.push(extendsParseResult);
+}

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

@@ -0,0 +1,61 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _ramda = require("ramda");
+var _apidomParserAdapterOverlayJson = require("@speclynx/apidom-parser-adapter-overlay-json-1");
+var _ParserError = _interopRequireDefault(require("../../../errors/ParserError.cjs"));
+var _Parser = _interopRequireDefault(require("../Parser.cjs"));
+var _extends = require("./extends.cjs");
+exports.parseExtends = _extends.parseExtends;
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class OverlayJSON1Parser extends _Parser.default {
+  refractorOpts;
+  constructor(options) {
+    const {
+      fileExtensions = [],
+      mediaTypes = _apidomParserAdapterOverlayJson.mediaTypes,
+      ...rest
+    } = options ?? {};
+    super({
+      ...rest,
+      name: 'overlay-json-1',
+      fileExtensions,
+      mediaTypes
+    });
+  }
+  async canParse(file) {
+    const hasSupportedFileExtension = this.fileExtensions.length === 0 ? true : this.fileExtensions.includes(file.extension);
+    const hasSupportedMediaType = this.mediaTypes.includes(file.mediaType);
+    if (!hasSupportedFileExtension) return false;
+    if (hasSupportedMediaType) return true;
+    if (!hasSupportedMediaType) {
+      return (0, _apidomParserAdapterOverlayJson.detect)(file.toString());
+    }
+    return false;
+  }
+  async parse(file, options) {
+    const source = file.toString();
+    try {
+      const parserOpts = (0, _ramda.pick)(['sourceMap', 'style', 'strict', 'refractorOpts'], this);
+      const parseResult = await (0, _apidomParserAdapterOverlayJson.parse)(source, parserOpts);
+      const shouldParseExtends = options?.parse?.parserOpts?.[this.name]?.extends ?? options?.parse?.parserOpts?.extends;
+      if (shouldParseExtends) {
+        await (0, _extends.parseExtends)(parseResult, file.uri, options);
+      }
+      return parseResult;
+    } catch (error) {
+      throw new _ParserError.default(`Error parsing "${file.uri}"`, {
+        cause: error
+      });
+    }
+  }
+}
+var _default = exports.default = OverlayJSON1Parser;

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

@@ -0,0 +1,55 @@
+import { pick } from 'ramda';
+import { parse, mediaTypes as OverlayJSON1MediaTypes, detect } from '@speclynx/apidom-parser-adapter-overlay-json-1';
+import ParserError from "../../../errors/ParserError.mjs";
+import Parser from "../Parser.mjs";
+import { parseExtends } from "./extends.mjs";
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+class OverlayJSON1Parser extends Parser {
+  refractorOpts;
+  constructor(options) {
+    const {
+      fileExtensions = [],
+      mediaTypes = OverlayJSON1MediaTypes,
+      ...rest
+    } = options ?? {};
+    super({
+      ...rest,
+      name: 'overlay-json-1',
+      fileExtensions,
+      mediaTypes
+    });
+  }
+  async canParse(file) {
+    const hasSupportedFileExtension = this.fileExtensions.length === 0 ? true : this.fileExtensions.includes(file.extension);
+    const hasSupportedMediaType = this.mediaTypes.includes(file.mediaType);
+    if (!hasSupportedFileExtension) return false;
+    if (hasSupportedMediaType) return true;
+    if (!hasSupportedMediaType) {
+      return detect(file.toString());
+    }
+    return false;
+  }
+  async parse(file, options) {
+    const source = file.toString();
+    try {
+      const parserOpts = pick(['sourceMap', 'style', 'strict', 'refractorOpts'], this);
+      const parseResult = await parse(source, parserOpts);
+      const shouldParseExtends = options?.parse?.parserOpts?.[this.name]?.extends ?? options?.parse?.parserOpts?.extends;
+      if (shouldParseExtends) {
+        await parseExtends(parseResult, file.uri, options);
+      }
+      return parseResult;
+    } catch (error) {
+      throw new ParserError(`Error parsing "${file.uri}"`, {
+        cause: error
+      });
+    }
+  }
+}
+export { parseExtends } from "./extends.mjs";
+export default OverlayJSON1Parser;

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

@@ -0,0 +1,6 @@
+"use strict";
+
+exports.__esModule = true;
+exports.parseExtends = void 0;
+var _extends = require("../overlay-json-1/extends.cjs");
+exports.parseExtends = _extends.parseExtends;

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

@@ -0,0 +1,2 @@
+// re-export from JSON parser - extends logic is format-agnostic
+export { parseExtends } from "../overlay-json-1/extends.mjs";

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

@@ -0,0 +1,61 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _ramda = require("ramda");
+var _apidomParserAdapterOverlayYaml = require("@speclynx/apidom-parser-adapter-overlay-yaml-1");
+var _ParserError = _interopRequireDefault(require("../../../errors/ParserError.cjs"));
+var _Parser = _interopRequireDefault(require("../Parser.cjs"));
+var _extends = require("./extends.cjs");
+exports.parseExtends = _extends.parseExtends;
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class OverlayYAML1Parser extends _Parser.default {
+  refractorOpts;
+  constructor(options) {
+    const {
+      fileExtensions = [],
+      mediaTypes = _apidomParserAdapterOverlayYaml.mediaTypes,
+      ...rest
+    } = options ?? {};
+    super({
+      ...rest,
+      name: 'overlay-yaml-1',
+      fileExtensions,
+      mediaTypes
+    });
+  }
+  async canParse(file) {
+    const hasSupportedFileExtension = this.fileExtensions.length === 0 ? true : this.fileExtensions.includes(file.extension);
+    const hasSupportedMediaType = this.mediaTypes.includes(file.mediaType);
+    if (!hasSupportedFileExtension) return false;
+    if (hasSupportedMediaType) return true;
+    if (!hasSupportedMediaType) {
+      return (0, _apidomParserAdapterOverlayYaml.detect)(file.toString());
+    }
+    return false;
+  }
+  async parse(file, options) {
+    const source = file.toString();
+    try {
+      const parserOpts = (0, _ramda.pick)(['sourceMap', 'style', 'strict', 'refractorOpts'], this);
+      const parseResult = await (0, _apidomParserAdapterOverlayYaml.parse)(source, parserOpts);
+      const shouldParseExtends = options?.parse?.parserOpts?.[this.name]?.extends ?? options?.parse?.parserOpts?.extends;
+      if (shouldParseExtends) {
+        await (0, _extends.parseExtends)(parseResult, file.uri, options);
+      }
+      return parseResult;
+    } catch (error) {
+      throw new _ParserError.default(`Error parsing "${file.uri}"`, {
+        cause: error
+      });
+    }
+  }
+}
+var _default = exports.default = OverlayYAML1Parser;

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

@@ -0,0 +1,55 @@
+import { pick } from 'ramda';
+import { parse, mediaTypes as OverlayYAML1MediaTypes, detect } from '@speclynx/apidom-parser-adapter-overlay-yaml-1';
+import ParserError from "../../../errors/ParserError.mjs";
+import Parser from "../Parser.mjs";
+import { parseExtends } from "./extends.mjs";
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+class OverlayYAML1Parser extends Parser {
+  refractorOpts;
+  constructor(options) {
+    const {
+      fileExtensions = [],
+      mediaTypes = OverlayYAML1MediaTypes,
+      ...rest
+    } = options ?? {};
+    super({
+      ...rest,
+      name: 'overlay-yaml-1',
+      fileExtensions,
+      mediaTypes
+    });
+  }
+  async canParse(file) {
+    const hasSupportedFileExtension = this.fileExtensions.length === 0 ? true : this.fileExtensions.includes(file.extension);
+    const hasSupportedMediaType = this.mediaTypes.includes(file.mediaType);
+    if (!hasSupportedFileExtension) return false;
+    if (hasSupportedMediaType) return true;
+    if (!hasSupportedMediaType) {
+      return detect(file.toString());
+    }
+    return false;
+  }
+  async parse(file, options) {
+    const source = file.toString();
+    try {
+      const parserOpts = pick(['sourceMap', 'style', 'strict', 'refractorOpts'], this);
+      const parseResult = await parse(source, parserOpts);
+      const shouldParseExtends = options?.parse?.parserOpts?.[this.name]?.extends ?? options?.parse?.parserOpts?.extends;
+      if (shouldParseExtends) {
+        await parseExtends(parseResult, file.uri, options);
+      }
+      return parseResult;
+    } catch (error) {
+      throw new ParserError(`Error parsing "${file.uri}"`, {
+        cause: error
+      });
+    }
+  }
+}
+export { parseExtends } from "./extends.mjs";
+export default OverlayYAML1Parser;

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

@@ -0,0 +1,49 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _ResolveStrategy = _interopRequireDefault(require("../ResolveStrategy.cjs"));
+var _ReferenceSet = _interopRequireDefault(require("../../../ReferenceSet.cjs"));
+var _util = require("../../../options/util.cjs");
+var _UnmatchedDereferenceStrategyError = _interopRequireDefault(require("../../../errors/UnmatchedDereferenceStrategyError.cjs"));
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class Arazzo1ResolveStrategy extends _ResolveStrategy.default {
+  constructor(options) {
+    super({
+      ...(options ?? {}),
+      name: 'arazzo-1'
+    });
+  }
+  canResolve(file, options) {
+    const dereferenceStrategy = options.dereference.strategies.find(strategy => strategy.name === 'arazzo-1');
+    if (dereferenceStrategy === undefined) {
+      return false;
+    }
+    return dereferenceStrategy.canDereference(file, options);
+  }
+  async resolve(file, options) {
+    const dereferenceStrategy = options.dereference.strategies.find(strategy => strategy.name === 'arazzo-1');
+    if (dereferenceStrategy === undefined) {
+      throw new _UnmatchedDereferenceStrategyError.default(`"arazzo-1" resolve strategy requires "arazzo-1" dereference strategy to be configured for file "${file.uri}"`);
+    }
+    const refSet = new _ReferenceSet.default();
+    const mergedOptions = (0, _util.merge)(options, {
+      resolve: {
+        internal: false
+      },
+      dereference: {
+        refSet
+      }
+    });
+    await dereferenceStrategy.dereference(file, mergedOptions);
+    return refSet;
+  }
+}
+var _default = exports.default = Arazzo1ResolveStrategy;

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

@@ -0,0 +1,43 @@
+import ResolveStrategy from "../ResolveStrategy.mjs";
+import ReferenceSet from "../../../ReferenceSet.mjs";
+import { merge as mergeOptions } from "../../../options/util.mjs";
+import UnmatchedDereferenceStrategyError from "../../../errors/UnmatchedDereferenceStrategyError.mjs";
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+class Arazzo1ResolveStrategy extends ResolveStrategy {
+  constructor(options) {
+    super({
+      ...(options ?? {}),
+      name: 'arazzo-1'
+    });
+  }
+  canResolve(file, options) {
+    const dereferenceStrategy = options.dereference.strategies.find(strategy => strategy.name === 'arazzo-1');
+    if (dereferenceStrategy === undefined) {
+      return false;
+    }
+    return dereferenceStrategy.canDereference(file, options);
+  }
+  async resolve(file, options) {
+    const dereferenceStrategy = options.dereference.strategies.find(strategy => strategy.name === 'arazzo-1');
+    if (dereferenceStrategy === undefined) {
+      throw new UnmatchedDereferenceStrategyError(`"arazzo-1" resolve strategy requires "arazzo-1" dereference strategy to be configured for file "${file.uri}"`);
+    }
+    const refSet = new ReferenceSet();
+    const mergedOptions = mergeOptions(options, {
+      resolve: {
+        internal: false
+      },
+      dereference: {
+        refSet
+      }
+    });
+    await dereferenceStrategy.dereference(file, mergedOptions);
+    return refSet;
+  }
+}
+export default Arazzo1ResolveStrategy;

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

@@ -0,0 +1,49 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _ResolveStrategy = _interopRequireDefault(require("../ResolveStrategy.cjs"));
+var _ReferenceSet = _interopRequireDefault(require("../../../ReferenceSet.cjs"));
+var _util = require("../../../options/util.cjs");
+var _UnmatchedDereferenceStrategyError = _interopRequireDefault(require("../../../errors/UnmatchedDereferenceStrategyError.cjs"));
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class Overlay1ResolveStrategy extends _ResolveStrategy.default {
+  constructor(options) {
+    super({
+      ...(options ?? {}),
+      name: 'overlay-1'
+    });
+  }
+  canResolve(file, options) {
+    const dereferenceStrategy = options.dereference.strategies.find(strategy => strategy.name === 'overlay-1');
+    if (dereferenceStrategy === undefined) {
+      return false;
+    }
+    return dereferenceStrategy.canDereference(file, options);
+  }
+  async resolve(file, options) {
+    const dereferenceStrategy = options.dereference.strategies.find(strategy => strategy.name === 'overlay-1');
+    if (dereferenceStrategy === undefined) {
+      throw new _UnmatchedDereferenceStrategyError.default(`"overlay-1" resolve strategy requires "overlay-1" dereference strategy to be configured for file "${file.uri}"`);
+    }
+    const refSet = new _ReferenceSet.default();
+    const mergedOptions = (0, _util.merge)(options, {
+      resolve: {
+        internal: false
+      },
+      dereference: {
+        refSet
+      }
+    });
+    await dereferenceStrategy.dereference(file, mergedOptions);
+    return refSet;
+  }
+}
+var _default = exports.default = Overlay1ResolveStrategy;

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

@@ -0,0 +1,43 @@
+import ResolveStrategy from "../ResolveStrategy.mjs";
+import ReferenceSet from "../../../ReferenceSet.mjs";
+import { merge as mergeOptions } from "../../../options/util.mjs";
+import UnmatchedDereferenceStrategyError from "../../../errors/UnmatchedDereferenceStrategyError.mjs";
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+class Overlay1ResolveStrategy extends ResolveStrategy {
+  constructor(options) {
+    super({
+      ...(options ?? {}),
+      name: 'overlay-1'
+    });
+  }
+  canResolve(file, options) {
+    const dereferenceStrategy = options.dereference.strategies.find(strategy => strategy.name === 'overlay-1');
+    if (dereferenceStrategy === undefined) {
+      return false;
+    }
+    return dereferenceStrategy.canDereference(file, options);
+  }
+  async resolve(file, options) {
+    const dereferenceStrategy = options.dereference.strategies.find(strategy => strategy.name === 'overlay-1');
+    if (dereferenceStrategy === undefined) {
+      throw new UnmatchedDereferenceStrategyError(`"overlay-1" resolve strategy requires "overlay-1" dereference strategy to be configured for file "${file.uri}"`);
+    }
+    const refSet = new ReferenceSet();
+    const mergedOptions = mergeOptions(options, {
+      resolve: {
+        internal: false
+      },
+      dereference: {
+        refSet
+      }
+    });
+    await dereferenceStrategy.dereference(file, mergedOptions);
+    return refSet;
+  }
+}
+export default Overlay1ResolveStrategy;

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

@@ -0,0 +1,21 @@
+import { ParseResultElement } from '@speclynx/apidom-datamodel';
+import type { ReferenceOptions } from '../../../options/index.ts';
+/**
+ * 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 declare function dereferenceExtends(parseResult: ParseResultElement, parseResultRetrievalURI: string, options: ReferenceOptions): Promise<void>;