@speclynx/apidom-reference 2.7.0 → 2.9.0

package/src/parse/parsers/arazzo-json-1/{source-description.cjs → source-descriptions.cjs}

@@ -1,7 +1,7 @@
 "use strict";
 
-var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
 var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
 exports.__esModule = true;
 exports.parseSourceDescriptions = parseSourceDescriptions;
 var _apidomDatamodel = require("@speclynx/apidom-datamodel");
@@ -10,6 +10,7 @@ var _apidomNsOpenapi = require("@speclynx/apidom-ns-openapi-2");
 var _apidomNsOpenapi2 = require("@speclynx/apidom-ns-openapi-3-0");
 var _apidomNsOpenapi3 = require("@speclynx/apidom-ns-openapi-3-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"));
@@ -39,7 +40,9 @@ async function parseSourceDescription(sourceDescription, ctx) {
     parseResult.push(annotation);
     return parseResult;
   }
-  const retrievalURI = url.resolve(ctx.baseURI, sourceDescriptionURI);
+
+  // normalize URI for consistent cycle detection and cache key matching
+  const retrievalURI = url.sanitize(url.stripHash(url.resolve(ctx.baseURI, sourceDescriptionURI)));
 
   // skip if already visited (cycle detection)
   if (ctx.visitedUrls.has(retrievalURI)) {
@@ -50,11 +53,14 @@ async function parseSourceDescription(sourceDescription, ctx) {
   }
   ctx.visitedUrls.add(retrievalURI);
   try {
-    const sdParseResult = await (0, _index.default)(retrievalURI, (0, _util.merge)(ctx.options, {
+    const sourceDescriptionParseResult = await (0, _index.default)(retrievalURI, (0, _util.merge)(ctx.options, {
       parse: {
         mediaType: 'text/plain',
         // allow parser plugin detection
         parserOpts: {
+          // nested documents should parse all their source descriptions
+          // (parent's name filter doesn't apply to nested documents)
+          sourceDescriptions: true,
           [ARAZZO_RECURSION_KEY]: {
             sourceDescriptionsDepth: ctx.currentDepth + 1,
             sourceDescriptionsVisitedUrls: ctx.visitedUrls
@@ -63,7 +69,7 @@ async function parseSourceDescription(sourceDescription, ctx) {
       }
     }));
     // merge parsed result into our parse result
-    for (const item of sdParseResult) {
+    for (const item of sourceDescriptionParseResult) {
       parseResult.push(item);
     }
   } catch (error) {
@@ -105,10 +111,53 @@ async function parseSourceDescription(sourceDescription, ctx) {
 }
 
 /**
- * Shared function for parsing source descriptions.
+ * Parses source descriptions from an Arazzo document's ParseResult.
+ *
+ * Each source description result is attached to its corresponding
+ * SourceDescriptionElement's meta as 'parseResult' for easy access,
+ * regardless of success or failure. On failure, the ParseResultElement
+ * contains annotations explaining what went wrong.
+ *
+ * @param parseResult - ParseResult containing an Arazzo specification
+ * @param parseResultRetrievalURI - URI from which the parseResult was retrieved
+ * @param options - Full ReferenceOptions. Pass `sourceDescriptions` as an array of names
+ *   in `parse.parserOpts` to filter which source descriptions to process.
+ * @param parserName - Parser name for options lookup (defaults to 'arazzo-json-1')
+ * @returns Array of ParseResultElements. Returns one ParseResultElement per source description
+ *   (each with class 'source-description' and name/type metadata).
+ *   May return early with a single-element array containing a warning annotation when:
+ *   - The API is not an Arazzo specification
+ *   - The sourceDescriptions field is missing or not an array
+ *   - Maximum parse depth is exceeded (error annotation)
+ *   Returns an empty array when no source description names match the filter.
+ *
+ * @example
+ * ```typescript
+ * import { options, mergeOptions } from '@speclynx/apidom-reference';
+ * import { parseSourceDescriptions } from '@speclynx/apidom-reference/parse/parsers/arazzo-json-1';
+ *
+ * // Parse all source descriptions
+ * const results = await parseSourceDescriptions(parseResult, uri, options);
+ *
+ * // Filter by name
+ * const filtered = await parseSourceDescriptions(parseResult, uri, mergeOptions(options, {
+ *   parse: { parserOpts: { sourceDescriptions: ['petStore'] } }
+ * }));
+ *
+ * // Access parsed document from source description element
+ * const sourceDesc = parseResult.api.sourceDescriptions.get(0);
+ * const parsedDoc = sourceDesc.meta.get('parseResult');
+ * ```
+ *
  * @public
  */
-async function parseSourceDescriptions(parserName, api, file, options) {
+async function parseSourceDescriptions(parseResult, parseResultRetrievalURI, options, parserName = 'arazzo-json-1') {
+  const {
+    api
+  } = parseResult;
+  const file = new _File.default({
+    uri: url.sanitize(url.stripHash(parseResultRetrievalURI))
+  });
   const results = [];
 
   /**
@@ -150,13 +199,8 @@ async function parseSourceDescriptions(parserName, api, file, options) {
     visitedUrls
   };
 
-  // determine which source descriptions to parse
+  // determine which source descriptions to parse (array filters by name)
   const sourceDescriptionsOption = options?.parse?.parserOpts?.[parserName]?.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 (!(0, _apidomNsArazzo.isSourceDescriptionElement)(sd)) return false;
     const name = (0, _apidomCore.toValue)(sd.name);
@@ -166,6 +210,8 @@ async function parseSourceDescriptions(parserName, api, file, options) {
   // process sequentially to ensure proper cycle detection with shared visitedUrls
   for (const sourceDescription of sourceDescriptions) {
     const sourceDescriptionParseResult = await parseSourceDescription(sourceDescription, ctx);
+    // always attach result (even on failure - contains annotations)
+    sourceDescription.meta.set('parseResult', sourceDescriptionParseResult);
     results.push(sourceDescriptionParseResult);
   }
   return results;

package/src/parse/parsers/arazzo-json-1/{source-description.mjs → source-descriptions.mjs}

@@ -4,6 +4,7 @@ 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 File from "../../../File.mjs";
 import * as url from "../../../util/url.mjs";
 import { merge as mergeOptions } from "../../../options/util.mjs";
 import parse from "../../index.mjs"; // shared key for recursion state (works across JSON/YAML parsers)
@@ -32,7 +33,9 @@ async function parseSourceDescription(sourceDescription, ctx) {
     parseResult.push(annotation);
     return parseResult;
   }
-  const retrievalURI = url.resolve(ctx.baseURI, sourceDescriptionURI);
+
+  // normalize URI for consistent cycle detection and cache key matching
+  const retrievalURI = url.sanitize(url.stripHash(url.resolve(ctx.baseURI, sourceDescriptionURI)));
 
   // skip if already visited (cycle detection)
   if (ctx.visitedUrls.has(retrievalURI)) {
@@ -43,11 +46,14 @@ async function parseSourceDescription(sourceDescription, ctx) {
   }
   ctx.visitedUrls.add(retrievalURI);
   try {
-    const sdParseResult = await parse(retrievalURI, mergeOptions(ctx.options, {
+    const sourceDescriptionParseResult = await parse(retrievalURI, mergeOptions(ctx.options, {
       parse: {
         mediaType: 'text/plain',
         // allow parser plugin detection
         parserOpts: {
+          // nested documents should parse all their source descriptions
+          // (parent's name filter doesn't apply to nested documents)
+          sourceDescriptions: true,
           [ARAZZO_RECURSION_KEY]: {
             sourceDescriptionsDepth: ctx.currentDepth + 1,
             sourceDescriptionsVisitedUrls: ctx.visitedUrls
@@ -56,7 +62,7 @@ async function parseSourceDescription(sourceDescription, ctx) {
       }
     }));
     // merge parsed result into our parse result
-    for (const item of sdParseResult) {
+    for (const item of sourceDescriptionParseResult) {
       parseResult.push(item);
     }
   } catch (error) {
@@ -98,10 +104,53 @@ async function parseSourceDescription(sourceDescription, ctx) {
 }
 
 /**
- * Shared function for parsing source descriptions.
+ * Parses source descriptions from an Arazzo document's ParseResult.
+ *
+ * Each source description result is attached to its corresponding
+ * SourceDescriptionElement's meta as 'parseResult' for easy access,
+ * regardless of success or failure. On failure, the ParseResultElement
+ * contains annotations explaining what went wrong.
+ *
+ * @param parseResult - ParseResult containing an Arazzo specification
+ * @param parseResultRetrievalURI - URI from which the parseResult was retrieved
+ * @param options - Full ReferenceOptions. Pass `sourceDescriptions` as an array of names
+ *   in `parse.parserOpts` to filter which source descriptions to process.
+ * @param parserName - Parser name for options lookup (defaults to 'arazzo-json-1')
+ * @returns Array of ParseResultElements. Returns one ParseResultElement per source description
+ *   (each with class 'source-description' and name/type metadata).
+ *   May return early with a single-element array containing a warning annotation when:
+ *   - The API is not an Arazzo specification
+ *   - The sourceDescriptions field is missing or not an array
+ *   - Maximum parse depth is exceeded (error annotation)
+ *   Returns an empty array when no source description names match the filter.
+ *
+ * @example
+ * ```typescript
+ * import { options, mergeOptions } from '@speclynx/apidom-reference';
+ * import { parseSourceDescriptions } from '@speclynx/apidom-reference/parse/parsers/arazzo-json-1';
+ *
+ * // Parse all source descriptions
+ * const results = await parseSourceDescriptions(parseResult, uri, options);
+ *
+ * // Filter by name
+ * const filtered = await parseSourceDescriptions(parseResult, uri, mergeOptions(options, {
+ *   parse: { parserOpts: { sourceDescriptions: ['petStore'] } }
+ * }));
+ *
+ * // Access parsed document from source description element
+ * const sourceDesc = parseResult.api.sourceDescriptions.get(0);
+ * const parsedDoc = sourceDesc.meta.get('parseResult');
+ * ```
+ *
  * @public
  */
-export async function parseSourceDescriptions(parserName, api, file, options) {
+export async function parseSourceDescriptions(parseResult, parseResultRetrievalURI, options, parserName = 'arazzo-json-1') {
+  const {
+    api
+  } = parseResult;
+  const file = new File({
+    uri: url.sanitize(url.stripHash(parseResultRetrievalURI))
+  });
   const results = [];
 
   /**
@@ -143,13 +192,8 @@ export async function parseSourceDescriptions(parserName, api, file, options) {
     visitedUrls
   };
 
-  // determine which source descriptions to parse
+  // determine which source descriptions to parse (array filters by name)
   const sourceDescriptionsOption = options?.parse?.parserOpts?.[parserName]?.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);
@@ -159,6 +203,8 @@ export async function parseSourceDescriptions(parserName, api, file, options) {
   // process sequentially to ensure proper cycle detection with shared visitedUrls
   for (const sourceDescription of sourceDescriptions) {
     const sourceDescriptionParseResult = await parseSourceDescription(sourceDescription, ctx);
+    // always attach result (even on failure - contains annotations)
+    sourceDescription.meta.set('parseResult', sourceDescriptionParseResult);
     results.push(sourceDescriptionParseResult);
   }
   return results;

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

@@ -7,7 +7,8 @@ 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");
+var _sourceDescriptions = require("./source-descriptions.cjs");
+exports.parseSourceDescriptions = _sourceDescriptions.parseSourceDescriptions;
 /**
  * @public
  */
@@ -47,7 +48,7 @@ class ArazzoYAML1Parser extends _Parser.default {
       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 (0, _sourceDescription.parseSourceDescriptions)(this.name, parseResult.api, file, options);
+        const sourceDescriptions = await (0, _sourceDescriptions.parseSourceDescriptions)(parseResult, file.uri, options, this.name);
         parseResult.push(...sourceDescriptions);
       }
       return parseResult;

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

@@ -2,7 +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";
+import { parseSourceDescriptions } from "./source-descriptions.mjs";
 /**
  * @public
  */
@@ -41,7 +41,7 @@ class ArazzoYAML1Parser extends Parser {
       const parseResult = await parse(source, parserOpts);
       const shouldParseSourceDescriptions = options?.parse?.parserOpts?.[this.name]?.sourceDescriptions ?? options?.parse?.parserOpts?.sourceDescriptions;
       if (shouldParseSourceDescriptions) {
-        const sourceDescriptions = await parseSourceDescriptions(this.name, parseResult.api, file, options);
+        const sourceDescriptions = await parseSourceDescriptions(parseResult, file.uri, options, this.name);
         parseResult.push(...sourceDescriptions);
       }
       return parseResult;
@@ -52,4 +52,5 @@ class ArazzoYAML1Parser extends Parser {
     }
   }
 }
+export { parseSourceDescriptions } from "./source-descriptions.mjs";
 export default ArazzoYAML1Parser;

package/src/parse/parsers/arazzo-yaml-1/source-descriptions.cjs

@@ -0,0 +1,12 @@
+"use strict";
+
+exports.__esModule = true;
+exports.parseSourceDescriptions = void 0;
+var _sourceDescriptions = require("../arazzo-json-1/source-descriptions.cjs");
+/**
+ * @public
+ */
+const parseSourceDescriptions = (parseResult, parseResultRetrievalURI, options, parserName = 'arazzo-yaml-1') => {
+  return (0, _sourceDescriptions.parseSourceDescriptions)(parseResult, parseResultRetrievalURI, options, parserName);
+};
+exports.parseSourceDescriptions = parseSourceDescriptions;

package/src/parse/parsers/arazzo-yaml-1/source-descriptions.mjs

@@ -0,0 +1,7 @@
+import { parseSourceDescriptions as parseSourceDescriptionsBase } from "../arazzo-json-1/source-descriptions.mjs";
+/**
+ * @public
+ */
+export const parseSourceDescriptions = (parseResult, parseResultRetrievalURI, options, parserName = 'arazzo-yaml-1') => {
+  return parseSourceDescriptionsBase(parseResult, parseResultRetrievalURI, options, parserName);
+};

package/types/dereference/strategies/arazzo-1/index.d.ts

@@ -29,4 +29,5 @@ declare class Arazzo1DereferenceStrategy extends DereferenceStrategy {
 }
 export { Arazzo1DereferenceVisitor };
 export { resolveSchema$refField, resolveSchema$idField, maybeRefractToJSONSchemaElement, } from './util.ts';
+export { dereferenceSourceDescriptions } from './source-descriptions.ts';
 export default Arazzo1DereferenceStrategy;

package/types/dereference/strategies/arazzo-1/source-descriptions.d.ts

@@ -0,0 +1,41 @@
+import { ParseResultElement } from '@speclynx/apidom-datamodel';
+import type { ReferenceOptions } from '../../../options/index.ts';
+/**
+ * Dereferences source descriptions from an Arazzo document.
+ *
+ * Each source description result is attached to its corresponding
+ * SourceDescriptionElement's meta as 'parseResult' for easy access,
+ * regardless of success or failure. On failure, the ParseResultElement
+ * contains annotations explaining what went wrong.
+ *
+ * @param parseResult - ParseResult containing a parsed (optionally dereferenced) Arazzo specification
+ * @param parseResultRetrievalURI - URI from which the parseResult was retrieved
+ * @param options - Full ReferenceOptions. Pass `sourceDescriptions` as an array of names
+ *   in `dereference.strategyOpts` to filter which source descriptions to process.
+ * @param strategyName - Strategy name for options lookup (defaults to 'arazzo-1')
+ * @returns Array of ParseResultElements. Returns one ParseResultElement per source description
+ *   (each with class 'source-description' and name/type metadata).
+ *   May return early with a single-element array containing a warning annotation when:
+ *   - The API is not an Arazzo specification
+ *   - The sourceDescriptions field is missing or not an array
+ *   - Maximum dereference depth is exceeded (error annotation)
+ *   Returns an empty array when no source description names match the filter.
+ *
+ * @example
+ * ```typescript
+ * // Dereference all source descriptions
+ * await dereferenceSourceDescriptions(parseResult, uri, options);
+ *
+ * // Filter by name
+ * await dereferenceSourceDescriptions(parseResult, uri, mergeOptions(options, {
+ *   dereference: { strategyOpts: { sourceDescriptions: ['petStore'] } },
+ * }));
+ *
+ * // Access dereferenced document from source description element
+ * const sourceDesc = parseResult.api.sourceDescriptions.get(0);
+ * const dereferencedDoc = sourceDesc.meta.get('parseResult');
+ * ```
+ *
+ * @public
+ */
+export declare function dereferenceSourceDescriptions(parseResult: ParseResultElement, parseResultRetrievalURI: string, options: ReferenceOptions, strategyName?: string): Promise<ParseResultElement[]>;

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

@@ -18,4 +18,5 @@ declare class ArazzoJSON1Parser extends Parser {
     canParse(file: File): Promise<boolean>;
     parse(file: File, options?: ReferenceOptions): Promise<ParseResultElement>;
 }
+export { parseSourceDescriptions } from './source-descriptions.ts';
 export default ArazzoJSON1Parser;

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

@@ -0,0 +1,44 @@
+import { ParseResultElement } from '@speclynx/apidom-datamodel';
+import type { ReferenceOptions } from '../../../options/index.ts';
+/**
+ * Parses source descriptions from an Arazzo document's ParseResult.
+ *
+ * Each source description result is attached to its corresponding
+ * SourceDescriptionElement's meta as 'parseResult' for easy access,
+ * regardless of success or failure. On failure, the ParseResultElement
+ * contains annotations explaining what went wrong.
+ *
+ * @param parseResult - ParseResult containing an Arazzo specification
+ * @param parseResultRetrievalURI - URI from which the parseResult was retrieved
+ * @param options - Full ReferenceOptions. Pass `sourceDescriptions` as an array of names
+ *   in `parse.parserOpts` to filter which source descriptions to process.
+ * @param parserName - Parser name for options lookup (defaults to 'arazzo-json-1')
+ * @returns Array of ParseResultElements. Returns one ParseResultElement per source description
+ *   (each with class 'source-description' and name/type metadata).
+ *   May return early with a single-element array containing a warning annotation when:
+ *   - The API is not an Arazzo specification
+ *   - The sourceDescriptions field is missing or not an array
+ *   - Maximum parse depth is exceeded (error annotation)
+ *   Returns an empty array when no source description names match the filter.
+ *
+ * @example
+ * ```typescript
+ * import { options, mergeOptions } from '@speclynx/apidom-reference';
+ * import { parseSourceDescriptions } from '@speclynx/apidom-reference/parse/parsers/arazzo-json-1';
+ *
+ * // Parse all source descriptions
+ * const results = await parseSourceDescriptions(parseResult, uri, options);
+ *
+ * // Filter by name
+ * const filtered = await parseSourceDescriptions(parseResult, uri, mergeOptions(options, {
+ *   parse: { parserOpts: { sourceDescriptions: ['petStore'] } }
+ * }));
+ *
+ * // Access parsed document from source description element
+ * const sourceDesc = parseResult.api.sourceDescriptions.get(0);
+ * const parsedDoc = sourceDesc.meta.get('parseResult');
+ * ```
+ *
+ * @public
+ */
+export declare function parseSourceDescriptions(parseResult: ParseResultElement, parseResultRetrievalURI: string, options: ReferenceOptions, parserName?: string): Promise<ParseResultElement[]>;

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

@@ -18,4 +18,5 @@ declare class ArazzoYAML1Parser extends Parser {
     canParse(file: File): Promise<boolean>;
     parse(file: File, options?: ReferenceOptions): Promise<ParseResultElement>;
 }
+export { parseSourceDescriptions } from './source-descriptions.ts';
 export default ArazzoYAML1Parser;

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

@@ -0,0 +1,6 @@
+import { ParseResultElement } from '@speclynx/apidom-datamodel';
+import type { ReferenceOptions } from '../../../options/index.ts';
+/**
+ * @public
+ */
+export declare const parseSourceDescriptions: (parseResult: ParseResultElement, parseResultRetrievalURI: string, options: ReferenceOptions, parserName?: string) => Promise<ParseResultElement[]>;

package/types/dereference/strategies/arazzo-1/source-description.d.ts

@@ -1,8 +0,0 @@
-import { ParseResultElement } from '@speclynx/apidom-datamodel';
-import Reference from '../../../Reference.ts';
-import type { ReferenceOptions } from '../../../options/index.ts';
-/**
- * Dereferences source descriptions from an Arazzo document.
- * @public
- */
-export declare function dereferenceSourceDescriptions(parseResult: ParseResultElement, reference: Reference, options: ReferenceOptions): Promise<ParseResultElement[]>;

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

@@ -1,8 +0,0 @@
-import { Element, ParseResultElement } from '@speclynx/apidom-datamodel';
-import File from '../../../File.ts';
-import type { ReferenceOptions } from '../../../options/index.ts';
-/**
- * Shared function for parsing source descriptions.
- * @public
- */
-export declare function parseSourceDescriptions(parserName: string, api: Element | undefined, file: File, options: ReferenceOptions): Promise<ParseResultElement[]>;