@speclynx/apidom-reference 2.5.1 → 2.6.1

package/src/parse/parsers/arazzo-json-1/source-description.mjs

@@ -0,0 +1,171 @@
+import { ParseResultElement, AnnotationElement, isArrayElement, isStringElement, cloneDeep } from '@speclynx/apidom-datamodel';
+import { isArazzoSpecification1Element, isSourceDescriptionElement } from '@speclynx/apidom-ns-arazzo-1';
+import { isSwaggerElement } from '@speclynx/apidom-ns-openapi-2';
+import { isOpenApi3_0Element } from '@speclynx/apidom-ns-openapi-3-0';
+import { isOpenApi3_1Element } from '@speclynx/apidom-ns-openapi-3-1';
+import { toValue } from '@speclynx/apidom-core';
+import * as url from "../../../util/url.mjs";
+import { merge as mergeOptions } from "../../../options/util.mjs"; // shared key for recursion state (works across JSON/YAML parsers)
+const ARAZZO_RECURSION_KEY = 'arazzo-1';
+/**
+ * Parses a single source description element.
+ * Returns ParseResultElement on success, or undefined if skipped.
+ */
+async function parseSourceDescription(sourceDescription, ctx) {
+  const parseResult = new ParseResultElement();
+  if (!isSourceDescriptionElement(sourceDescription)) {
+    const annotation = new AnnotationElement('Element is not a valid SourceDescriptionElement. Skipping.');
+    annotation.classes.push('warning');
+    parseResult.push(annotation);
+    return parseResult;
+  }
+
+  // set class and metadata from source description element
+  parseResult.classes.push('source-description');
+  if (isStringElement(sourceDescription.name)) parseResult.setMetaProperty('name', cloneDeep(sourceDescription.name));
+  if (isStringElement(sourceDescription.type)) parseResult.setMetaProperty('type', cloneDeep(sourceDescription.type));
+  const sourceDescriptionURI = toValue(sourceDescription.url);
+  if (typeof sourceDescriptionURI !== 'string') {
+    const annotation = new AnnotationElement('Source description URL is missing or not a string. Skipping.');
+    annotation.classes.push('warning');
+    parseResult.push(annotation);
+    return parseResult;
+  }
+  const retrievalURI = url.resolve(ctx.baseURI, sourceDescriptionURI);
+
+  // skip if already visited (cycle detection)
+  if (ctx.visitedUrls.has(retrievalURI)) {
+    const annotation = new AnnotationElement(`Source description "${retrievalURI}" has already been visited. Skipping to prevent cycle.`);
+    annotation.classes.push('warning');
+    parseResult.push(annotation);
+    return parseResult;
+  }
+  ctx.visitedUrls.add(retrievalURI);
+  try {
+    const sdParseResult = await ctx.parseFn(retrievalURI, mergeOptions(ctx.options, {
+      parse: {
+        mediaType: 'text/plain',
+        // allow parser plugin detection
+        parserOpts: {
+          [ARAZZO_RECURSION_KEY]: {
+            sourceDescriptionsDepth: ctx.currentDepth + 1,
+            sourceDescriptionsVisitedUrls: ctx.visitedUrls
+          }
+        }
+      }
+    }));
+    // merge parsed result into our parse result
+    for (const item of sdParseResult) {
+      parseResult.push(item);
+    }
+  } catch (error) {
+    // create error annotation instead of failing entire parse
+    const message = error instanceof Error ? error.message : String(error);
+    const annotation = new AnnotationElement(`Error parsing source description "${retrievalURI}": ${message}`);
+    annotation.classes.push('error');
+    parseResult.push(annotation);
+    return parseResult;
+  }
+
+  // only allow OpenAPI and Arazzo as source descriptions
+  const {
+    api: sourceDescriptionAPI
+  } = parseResult;
+  const isOpenApi = isSwaggerElement(sourceDescriptionAPI) || isOpenApi3_0Element(sourceDescriptionAPI) || isOpenApi3_1Element(sourceDescriptionAPI);
+  const isArazzo = isArazzoSpecification1Element(sourceDescriptionAPI);
+  if (!isOpenApi && !isArazzo) {
+    const annotation = new AnnotationElement(`Source description "${retrievalURI}" is not an OpenAPI or Arazzo document. Skipping.`);
+    annotation.classes.push('warning');
+    parseResult.push(annotation);
+    return parseResult;
+  }
+
+  // validate declared type matches actual parsed type
+  const declaredType = toValue(sourceDescription.type);
+  if (typeof declaredType === 'string') {
+    if (declaredType === 'openapi' && !isOpenApi) {
+      const annotation = new AnnotationElement(`Source description "${retrievalURI}" declared as "openapi" but parsed as Arazzo document.`);
+      annotation.classes.push('warning');
+      parseResult.push(annotation);
+    } else if (declaredType === 'arazzo' && !isArazzo) {
+      const annotation = new AnnotationElement(`Source description "${retrievalURI}" declared as "arazzo" but parsed as OpenAPI document.`);
+      annotation.classes.push('warning');
+      parseResult.push(annotation);
+    }
+  }
+  return parseResult;
+}
+
+/**
+ * Shared function for parsing source descriptions.
+ * Call with `.call(this, ...)` where `this` has `name` and `parseFn` properties.
+ * @public
+ */
+export async function parseSourceDescriptions(api, file, options) {
+  const results = [];
+
+  /**
+   * Validate prerequisites for parsing source descriptions.
+   * Return warning annotations if validation fails.
+   */
+  if (!isArazzoSpecification1Element(api)) {
+    const annotation = new AnnotationElement('Cannot parse source descriptions: API is not an Arazzo specification.');
+    annotation.classes.push('warning');
+    return [new ParseResultElement([annotation])];
+  }
+  if (!isArrayElement(api.sourceDescriptions)) {
+    const annotation = new AnnotationElement('Cannot parse source descriptions: sourceDescriptions field is missing or not an array.');
+    annotation.classes.push('warning');
+    return [new ParseResultElement([annotation])];
+  }
+  if (typeof this.parseFn !== 'function') {
+    const annotation = new AnnotationElement('Source descriptions found but parseFn is not configured. Skipping source description parsing.');
+    annotation.classes.push('error');
+    return [new ParseResultElement([annotation])];
+  }
+
+  // user config: parser-specific options take precedence over global parserOpts
+  const maxDepth = options?.parse?.parserOpts?.[this.name]?.sourceDescriptionsMaxDepth ?? options?.parse?.parserOpts?.sourceDescriptionsMaxDepth ?? +Infinity;
+
+  // recursion state comes from shared key (works across JSON/YAML)
+  const sharedOpts = options?.parse?.parserOpts?.[ARAZZO_RECURSION_KEY] ?? {};
+  const currentDepth = sharedOpts.sourceDescriptionsDepth ?? 0;
+  const visitedUrls = sharedOpts.sourceDescriptionsVisitedUrls ?? new Set();
+
+  // add current file to visited URLs to prevent cycles
+  visitedUrls.add(file.uri);
+  if (currentDepth >= maxDepth) {
+    const annotation = new AnnotationElement(`Maximum parse depth of ${maxDepth} has been exceeded by file "${file.uri}"`);
+    annotation.classes.push('error');
+    const parseResult = new ParseResultElement([annotation]);
+    parseResult.classes.push('source-description');
+    return [parseResult];
+  }
+  const ctx = {
+    parseFn: this.parseFn,
+    baseURI: file.uri,
+    options,
+    currentDepth,
+    visitedUrls
+  };
+
+  // determine which source descriptions to parse
+  const sourceDescriptionsOption = options?.parse?.parserOpts?.[this.name]?.sourceDescriptions ?? options?.parse?.parserOpts?.sourceDescriptions;
+
+  // handle false or other falsy values - no source descriptions should be parsed
+  if (!sourceDescriptionsOption) {
+    return results;
+  }
+  const sourceDescriptions = Array.isArray(sourceDescriptionsOption) ? api.sourceDescriptions.filter(sd => {
+    if (!isSourceDescriptionElement(sd)) return false;
+    const name = toValue(sd.name);
+    return typeof name === 'string' && sourceDescriptionsOption.includes(name);
+  }) : api.sourceDescriptions;
+
+  // process sequentially to ensure proper cycle detection with shared visitedUrls
+  for (const sourceDescription of sourceDescriptions) {
+    const sourceDescriptionParseResult = await parseSourceDescription(sourceDescription, ctx);
+    results.push(sourceDescriptionParseResult);
+  }
+  return results;
+}

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

@@ -7,6 +7,7 @@ var _ramda = require("ramda");
 var _apidomParserAdapterArazzoYaml = require("@speclynx/apidom-parser-adapter-arazzo-yaml-1");
 var _ParserError = _interopRequireDefault(require("../../../errors/ParserError.cjs"));
 var _Parser = _interopRequireDefault(require("../Parser.cjs"));
+var _sourceDescription = require("../arazzo-json-1/source-description.cjs");
 /**
  * @public
  */
@@ -16,8 +17,10 @@ var _Parser = _interopRequireDefault(require("../Parser.cjs"));
  */
 class ArazzoYAML1Parser extends _Parser.default {
   refractorOpts;
+  parseFn;
   constructor(options) {
     const {
+      parseFn,
       fileExtensions = [],
       mediaTypes = _apidomParserAdapterArazzoYaml.mediaTypes,
       ...rest
@@ -28,6 +31,7 @@ class ArazzoYAML1Parser extends _Parser.default {
       fileExtensions,
       mediaTypes
     });
+    this.parseFn = parseFn;
   }
   async canParse(file) {
     const hasSupportedFileExtension = this.fileExtensions.length === 0 ? true : this.fileExtensions.includes(file.extension);
@@ -39,11 +43,17 @@ class ArazzoYAML1Parser extends _Parser.default {
     }
     return false;
   }
-  async parse(file) {
+  async parse(file, options) {
     const source = file.toString();
     try {
       const parserOpts = (0, _ramda.pick)(['sourceMap', 'strict', 'refractorOpts'], this);
-      return await (0, _apidomParserAdapterArazzoYaml.parse)(source, parserOpts);
+      const parseResult = await (0, _apidomParserAdapterArazzoYaml.parse)(source, parserOpts);
+      const shouldParseSourceDescriptions = options?.parse?.parserOpts?.[this.name]?.sourceDescriptions ?? options?.parse?.parserOpts?.sourceDescriptions;
+      if (shouldParseSourceDescriptions) {
+        const sourceDescriptions = await _sourceDescription.parseSourceDescriptions.call(this, parseResult.api, file, options);
+        parseResult.push(...sourceDescriptions);
+      }
+      return parseResult;
     } catch (error) {
       throw new _ParserError.default(`Error parsing "${file.uri}"`, {
         cause: error

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

@@ -2,6 +2,7 @@ import { pick } from 'ramda';
 import { parse, mediaTypes as ArazzoYAML1MediaTypes, detect } from '@speclynx/apidom-parser-adapter-arazzo-yaml-1';
 import ParserError from "../../../errors/ParserError.mjs";
 import Parser from "../Parser.mjs";
+import { parseSourceDescriptions } from "../arazzo-json-1/source-description.mjs";
 /**
  * @public
  */
@@ -10,8 +11,10 @@ import Parser from "../Parser.mjs";
  */
 class ArazzoYAML1Parser extends Parser {
   refractorOpts;
+  parseFn;
   constructor(options) {
     const {
+      parseFn,
       fileExtensions = [],
       mediaTypes = ArazzoYAML1MediaTypes,
       ...rest
@@ -22,6 +25,7 @@ class ArazzoYAML1Parser extends Parser {
       fileExtensions,
       mediaTypes
     });
+    this.parseFn = parseFn;
   }
   async canParse(file) {
     const hasSupportedFileExtension = this.fileExtensions.length === 0 ? true : this.fileExtensions.includes(file.extension);
@@ -33,11 +37,17 @@ class ArazzoYAML1Parser extends Parser {
     }
     return false;
   }
-  async parse(file) {
+  async parse(file, options) {
     const source = file.toString();
     try {
       const parserOpts = pick(['sourceMap', 'strict', 'refractorOpts'], this);
-      return await parse(source, parserOpts);
+      const parseResult = await parse(source, parserOpts);
+      const shouldParseSourceDescriptions = options?.parse?.parserOpts?.[this.name]?.sourceDescriptions ?? options?.parse?.parserOpts?.sourceDescriptions;
+      if (shouldParseSourceDescriptions) {
+        const sourceDescriptions = await parseSourceDescriptions.call(this, parseResult.api, file, options);
+        parseResult.push(...sourceDescriptions);
+      }
+      return parseResult;
     } catch (error) {
       throw new ParserError(`Error parsing "${file.uri}"`, {
         cause: error

package/src/resolve/index.cjs

@@ -35,9 +35,9 @@ const resolveApiDOM = async (element, options) => {
   });
   const resolveStrategies = await plugins.filter('canResolve', [file, options], options.resolve.strategies);
 
-  // we couldn't find any resolver for this File
+  // we couldn't find any resolve strategy for this File
   if ((0, _ramda.isEmpty)(resolveStrategies)) {
-    throw new _UnmatchedResolveStrategyError.default(file.uri);
+    throw new _UnmatchedResolveStrategyError.default(`Could not find a resolve strategy that can resolve the file "${file.uri}"`);
   }
   try {
     const {

package/src/resolve/index.mjs

@@ -29,9 +29,9 @@ export const resolveApiDOM = async (element, options) => {
   });
   const resolveStrategies = await plugins.filter('canResolve', [file, options], options.resolve.strategies);
 
-  // we couldn't find any resolver for this File
+  // we couldn't find any resolve strategy for this File
   if (isEmpty(resolveStrategies)) {
-    throw new UnmatchedResolveStrategyError(file.uri);
+    throw new UnmatchedResolveStrategyError(`Could not find a resolve strategy that can resolve the file "${file.uri}"`);
   }
   try {
     const {

package/src/resolve/strategies/apidom/index.cjs

@@ -31,7 +31,7 @@ class ApiDOMResolveStrategy extends _ResolveStrategy.default {
   async resolve(file, options) {
     const dereferenceStrategy = options.dereference.strategies.find(strategy => strategy.name === 'apidom');
     if (dereferenceStrategy === undefined) {
-      throw new _UnmatchedDereferenceStrategyError.default('"apidom" dereference strategy is not available.');
+      throw new _UnmatchedDereferenceStrategyError.default(`"apidom" resolve strategy requires "apidom" dereference strategy to be configured for file "${file.uri}"`);
     }
     const refSet = new _ReferenceSet.default();
     const mergedOptions = (0, _util.merge)(options, {

package/src/resolve/strategies/apidom/index.mjs

@@ -25,7 +25,7 @@ class ApiDOMResolveStrategy extends ResolveStrategy {
   async resolve(file, options) {
     const dereferenceStrategy = options.dereference.strategies.find(strategy => strategy.name === 'apidom');
     if (dereferenceStrategy === undefined) {
-      throw new UnmatchedDereferenceStrategyError('"apidom" dereference strategy is not available.');
+      throw new UnmatchedDereferenceStrategyError(`"apidom" resolve strategy requires "apidom" dereference strategy to be configured for file "${file.uri}"`);
     }
     const refSet = new ReferenceSet();
     const mergedOptions = mergeOptions(options, {

package/src/resolve/strategies/asyncapi-2/index.cjs

@@ -31,7 +31,7 @@ class AsyncAPI2ResolveStrategy extends _ResolveStrategy.default {
   async resolve(file, options) {
     const dereferenceStrategy = options.dereference.strategies.find(strategy => strategy.name === 'asyncapi-2');
     if (dereferenceStrategy === undefined) {
-      throw new _UnmatchedDereferenceStrategyError.default('"asyncapi-2" dereference strategy is not available.');
+      throw new _UnmatchedDereferenceStrategyError.default(`"asyncapi-2" resolve strategy requires "asyncapi-2" dereference strategy to be configured for file "${file.uri}"`);
     }
     const refSet = new _ReferenceSet.default();
     const mergedOptions = (0, _util.merge)(options, {

package/src/resolve/strategies/asyncapi-2/index.mjs

@@ -25,7 +25,7 @@ class AsyncAPI2ResolveStrategy extends ResolveStrategy {
   async resolve(file, options) {
     const dereferenceStrategy = options.dereference.strategies.find(strategy => strategy.name === 'asyncapi-2');
     if (dereferenceStrategy === undefined) {
-      throw new UnmatchedDereferenceStrategyError('"asyncapi-2" dereference strategy is not available.');
+      throw new UnmatchedDereferenceStrategyError(`"asyncapi-2" resolve strategy requires "asyncapi-2" dereference strategy to be configured for file "${file.uri}"`);
     }
     const refSet = new ReferenceSet();
     const mergedOptions = mergeOptions(options, {

package/src/resolve/strategies/openapi-2/index.cjs

@@ -31,7 +31,7 @@ class OpenAPI2ResolveStrategy extends _ResolveStrategy.default {
   async resolve(file, options) {
     const dereferenceStrategy = options.dereference.strategies.find(strategy => strategy.name === 'openapi-2');
     if (dereferenceStrategy === undefined) {
-      throw new _UnmatchedDereferenceStrategyError.default('"openapi-2" dereference strategy is not available.');
+      throw new _UnmatchedDereferenceStrategyError.default(`"openapi-2" resolve strategy requires "openapi-2" dereference strategy to be configured for file "${file.uri}"`);
     }
     const refSet = new _ReferenceSet.default();
     const mergedOptions = (0, _util.merge)(options, {

package/src/resolve/strategies/openapi-2/index.mjs

@@ -25,7 +25,7 @@ class OpenAPI2ResolveStrategy extends ResolveStrategy {
   async resolve(file, options) {
     const dereferenceStrategy = options.dereference.strategies.find(strategy => strategy.name === 'openapi-2');
     if (dereferenceStrategy === undefined) {
-      throw new UnmatchedDereferenceStrategyError('"openapi-2" dereference strategy is not available.');
+      throw new UnmatchedDereferenceStrategyError(`"openapi-2" resolve strategy requires "openapi-2" dereference strategy to be configured for file "${file.uri}"`);
     }
     const refSet = new ReferenceSet();
     const mergedOptions = mergeOptions(options, {

package/src/resolve/strategies/openapi-3-0/index.cjs

@@ -31,7 +31,7 @@ class OpenAPI3_0ResolveStrategy extends _ResolveStrategy.default {
   async resolve(file, options) {
     const dereferenceStrategy = options.dereference.strategies.find(strategy => strategy.name === 'openapi-3-0');
     if (dereferenceStrategy === undefined) {
-      throw new _UnmatchedDereferenceStrategyError.default('"openapi-3-0" dereference strategy is not available.');
+      throw new _UnmatchedDereferenceStrategyError.default(`"openapi-3-0" resolve strategy requires "openapi-3-0" dereference strategy to be configured for file "${file.uri}"`);
     }
     const refSet = new _ReferenceSet.default();
     const mergedOptions = (0, _util.merge)(options, {

package/src/resolve/strategies/openapi-3-0/index.mjs

@@ -25,7 +25,7 @@ class OpenAPI3_0ResolveStrategy extends ResolveStrategy {
   async resolve(file, options) {
     const dereferenceStrategy = options.dereference.strategies.find(strategy => strategy.name === 'openapi-3-0');
     if (dereferenceStrategy === undefined) {
-      throw new UnmatchedDereferenceStrategyError('"openapi-3-0" dereference strategy is not available.');
+      throw new UnmatchedDereferenceStrategyError(`"openapi-3-0" resolve strategy requires "openapi-3-0" dereference strategy to be configured for file "${file.uri}"`);
     }
     const refSet = new ReferenceSet();
     const mergedOptions = mergeOptions(options, {

package/src/resolve/strategies/openapi-3-1/index.cjs

@@ -31,7 +31,7 @@ class OpenAPI3_1ResolveStrategy extends _ResolveStrategy.default {
   async resolve(file, options) {
     const dereferenceStrategy = options.dereference.strategies.find(strategy => strategy.name === 'openapi-3-1');
     if (dereferenceStrategy === undefined) {
-      throw new _UnmatchedDereferenceStrategyError.default('"openapi-3-1" dereference strategy is not available.');
+      throw new _UnmatchedDereferenceStrategyError.default(`"openapi-3-1" resolve strategy requires "openapi-3-1" dereference strategy to be configured for file "${file.uri}"`);
     }
     const refSet = new _ReferenceSet.default();
     const mergedOptions = (0, _util.merge)(options, {

package/src/resolve/strategies/openapi-3-1/index.mjs

@@ -25,7 +25,7 @@ class OpenAPI3_1ResolveStrategy extends ResolveStrategy {
   async resolve(file, options) {
     const dereferenceStrategy = options.dereference.strategies.find(strategy => strategy.name === 'openapi-3-1');
     if (dereferenceStrategy === undefined) {
-      throw new UnmatchedDereferenceStrategyError('"openapi-3-1" dereference strategy is not available.');
+      throw new UnmatchedDereferenceStrategyError(`"openapi-3-1" resolve strategy requires "openapi-3-1" dereference strategy to be configured for file "${file.uri}"`);
     }
     const refSet = new ReferenceSet();
     const mergedOptions = mergeOptions(options, {

package/src/resolve/util.cjs

@@ -21,12 +21,12 @@ const readFile = async (file, options) => {
 
   // we couldn't find any resolver for this File
   if ((0, _ramda.isEmpty)(resolvers)) {
-    throw new _UnmatchedResolverError.default(file.uri);
+    throw new _UnmatchedResolverError.default(`Could not find a resolver that can read the file "${file.uri}"`);
   }
   try {
     const {
       result
-    } = await plugins.run('read', [file], resolvers);
+    } = await plugins.run('read', [file, options], resolvers);
     return result;
   } catch (error) {
     throw new _ResolveError.default(`Error while reading file "${file.uri}"`, {

package/src/resolve/util.mjs

@@ -15,12 +15,12 @@ export const readFile = async (file, options) => {
 
   // we couldn't find any resolver for this File
   if (isEmpty(resolvers)) {
-    throw new UnmatchedResolverError(file.uri);
+    throw new UnmatchedResolverError(`Could not find a resolver that can read the file "${file.uri}"`);
   }
   try {
     const {
       result
-    } = await plugins.run('read', [file], resolvers);
+    } = await plugins.run('read', [file, options], resolvers);
     return result;
   } catch (error) {
     throw new ResolveError(`Error while reading file "${file.uri}"`, {

package/types/apidom-reference.d.ts

@@ -344,8 +344,8 @@ export declare abstract class Parser {
      */
     mediaTypes: string[];
     constructor({ name, allowEmpty, sourceMap, strict, fileExtensions, mediaTypes, }: ParserOptions);
-    abstract canParse(file: File_2): boolean | Promise<boolean>;
-    abstract parse(file: File_2): ParseResultElement | Promise<ParseResultElement>;
+    abstract canParse(file: File_2, options?: ApiDOMReferenceOptions): boolean | Promise<boolean>;
+    abstract parse(file: File_2, options?: ApiDOMReferenceOptions): ParseResultElement | Promise<ParseResultElement>;
 }
 
 /**
@@ -457,8 +457,8 @@ export declare class ResolveError extends ApiDOMError {
 export declare abstract class Resolver {
     readonly name: string;
     constructor({ name }: ResolverOptions);
-    abstract canRead(file: File_2): boolean;
-    abstract read(file: File_2): Promise<Buffer>;
+    abstract canRead(file: File_2, options?: ApiDOMReferenceOptions): boolean;
+    abstract read(file: File_2, options?: ApiDOMReferenceOptions): Promise<Buffer>;
 }
 
 /**
@@ -533,6 +533,12 @@ export declare class UnmatchedBundleStrategyError extends BundleError {
 export declare class UnmatchedDereferenceStrategyError extends DereferenceError {
 }
 
+/**
+ * @public
+ */
+export declare class UnmatchedParserError extends ParserError {
+}
+
 /**
  * @public
  */

package/types/errors/UnmatchedParserError.d.ts

@@ -0,0 +1,7 @@
+import ParserError from './ParserError.ts';
+/**
+ * @public
+ */
+declare class UnmatchedParserError extends ParserError {
+}
+export default UnmatchedParserError;

package/types/index.d.ts

@@ -45,6 +45,7 @@ export { default as ResolverError } from './errors/ResolverError.ts';
 export { default as UnmatchedDereferenceStrategyError } from './errors/UnmatchedDereferenceStrategyError.ts';
 export { default as UnmatchedResolveStrategyError } from './errors/UnmatchedResolveStrategyError.ts';
 export { default as UnmatchedResolverError } from './errors/UnmatchedResolverError.ts';
+export { default as UnmatchedParserError } from './errors/UnmatchedParserError.ts';
 /**
  * @public
  */

package/types/parse/parsers/Parser.d.ts

@@ -1,5 +1,6 @@
 import { ParseResultElement } from '@speclynx/apidom-datamodel';
 import File from '../../File.ts';
+import type { ReferenceOptions } from '../../options/index.ts';
 /**
  * @public
  */
@@ -37,7 +38,7 @@ declare abstract class Parser {
      */
     mediaTypes: string[];
     constructor({ name, allowEmpty, sourceMap, strict, fileExtensions, mediaTypes, }: ParserOptions);
-    abstract canParse(file: File): boolean | Promise<boolean>;
-    abstract parse(file: File): ParseResultElement | Promise<ParseResultElement>;
+    abstract canParse(file: File, options?: ReferenceOptions): boolean | Promise<boolean>;
+    abstract parse(file: File, options?: ReferenceOptions): ParseResultElement | Promise<ParseResultElement>;
 }
 export default Parser;

package/types/parse/parsers/arazzo-json-1/index.d.ts

@@ -1,20 +1,24 @@
 import { ParseResultElement } from '@speclynx/apidom-datamodel';
 import Parser, { ParserOptions } from '../Parser.ts';
 import File from '../../../File.ts';
+import type { ReferenceOptions } from '../../../options/index.ts';
+import type ParseFn from '../../index.ts';
 export type { default as Parser, ParserOptions } from '../Parser.ts';
 export type { default as File, FileOptions } from '../../../File.ts';
 /**
  * @public
  */
 export interface ArazzoJSON1ParserOptions extends Omit<ParserOptions, 'name'> {
+    readonly parseFn?: typeof ParseFn;
 }
 /**
  * @public
  */
 declare class ArazzoJSON1Parser extends Parser {
     refractorOpts: object;
+    parseFn?: typeof ParseFn;
     constructor(options?: ArazzoJSON1ParserOptions);
     canParse(file: File): Promise<boolean>;
-    parse(file: File): Promise<ParseResultElement>;
+    parse(file: File, options?: ReferenceOptions): Promise<ParseResultElement>;
 }
 export default ArazzoJSON1Parser;

package/types/parse/parsers/arazzo-json-1/source-description.d.ts

@@ -0,0 +1,13 @@
+import { Element, ParseResultElement } from '@speclynx/apidom-datamodel';
+import File from '../../../File.ts';
+import type { ReferenceOptions } from '../../../options/index.ts';
+import type ParseFn from '../../index.ts';
+/**
+ * Shared function for parsing source descriptions.
+ * Call with `.call(this, ...)` where `this` has `name` and `parseFn` properties.
+ * @public
+ */
+export declare function parseSourceDescriptions(this: {
+    name: string;
+    parseFn?: typeof ParseFn;
+}, api: Element | undefined, file: File, options: ReferenceOptions): Promise<ParseResultElement[]>;

package/types/parse/parsers/arazzo-yaml-1/index.d.ts

@@ -1,20 +1,24 @@
 import { ParseResultElement } from '@speclynx/apidom-datamodel';
 import Parser, { ParserOptions } from '../Parser.ts';
 import File from '../../../File.ts';
+import type { ReferenceOptions } from '../../../options/index.ts';
+import type ParseFn from '../../index.ts';
 export type { default as Parser, ParserOptions } from '../Parser.ts';
 export type { default as File, FileOptions } from '../../../File.ts';
 /**
  * @public
  */
 export interface ArazzoYAML1ParserOptions extends Omit<ParserOptions, 'name'> {
+    readonly parseFn?: typeof ParseFn;
 }
 /**
  * @public
  */
 declare class ArazzoYAML1Parser extends Parser {
     refractorOpts: object;
+    parseFn?: typeof ParseFn;
     constructor(options?: ArazzoYAML1ParserOptions);
     canParse(file: File): Promise<boolean>;
-    parse(file: File): Promise<ParseResultElement>;
+    parse(file: File, options?: ReferenceOptions): Promise<ParseResultElement>;
 }
 export default ArazzoYAML1Parser;

package/types/resolve/resolvers/Resolver.d.ts

@@ -1,4 +1,5 @@
 import File from '../../File.ts';
+import type { ReferenceOptions } from '../../options/index.ts';
 /**
  * @public
  */
@@ -11,7 +12,7 @@ export interface ResolverOptions {
 declare abstract class Resolver {
     readonly name: string;
     constructor({ name }: ResolverOptions);
-    abstract canRead(file: File): boolean;
-    abstract read(file: File): Promise<Buffer>;
+    abstract canRead(file: File, options?: ReferenceOptions): boolean;
+    abstract read(file: File, options?: ReferenceOptions): Promise<Buffer>;
 }
 export default Resolver;