@speclynx/apidom-reference 2.8.0 → 2.10.0

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

@@ -33,7 +33,10 @@ 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)));
+  parseResult.setMetaProperty('retrievalURI', retrievalURI);
 
   // skip if already visited (cycle detection)
   if (ctx.visitedUrls.has(retrievalURI)) {
@@ -49,6 +52,9 @@ async function parseSourceDescription(sourceDescription, ctx) {
         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
@@ -101,27 +107,42 @@ async function parseSourceDescription(sourceDescription, ctx) {
 /**
  * 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 (caller responsibility to construct)
+ * @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. On success, returns one ParseResultElement per
- *   source description (each with class 'source-description' and name/type metadata).
+ * @returns Array of ParseResultElements. Returns one ParseResultElement per source description
+ *   (each with class 'source-description' and metadata: name, type, retrievalURI).
  *   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 sourceDescriptions option is disabled or no names match.
+ *   Returns an empty array when no source description names match the filter.
  *
  * @example
  * ```typescript
+ * import { toValue } from '@speclynx/apidom-core';
  * import { options, mergeOptions } from '@speclynx/apidom-reference';
  * import { parseSourceDescriptions } from '@speclynx/apidom-reference/parse/parsers/arazzo-json-1';
  *
- * const fullOptions = mergeOptions(options, {
- *   parse: { parserOpts: { sourceDescriptions: true } }
- * });
- * const results = await parseSourceDescriptions(parseResult, uri, fullOptions);
+ * // 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');
+ * const retrievalURI = toValue(parsedDoc.meta.get('retrievalURI'));
  * ```
  *
  * @public
@@ -174,13 +195,8 @@ export async function parseSourceDescriptions(parseResult, parseResultRetrievalU
     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);
@@ -190,6 +206,8 @@ export async function parseSourceDescriptions(parseResult, parseResultRetrievalU
   // 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/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,44 @@
+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 metadata: name, type, retrievalURI).
+ *   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
+ * import { toValue } from '@speclynx/apidom-core';
+ *
+ * // 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');
+ * const retrievalURI = toValue(dereferencedDoc.meta.get('retrievalURI'));
+ * ```
+ *
+ * @public
+ */
+export declare function dereferenceSourceDescriptions(parseResult: ParseResultElement, parseResultRetrievalURI: string, options: ReferenceOptions, strategyName?: string): Promise<ParseResultElement[]>;

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

@@ -3,27 +3,42 @@ 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 (caller responsibility to construct)
+ * @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. On success, returns one ParseResultElement per
- *   source description (each with class 'source-description' and name/type metadata).
+ * @returns Array of ParseResultElements. Returns one ParseResultElement per source description
+ *   (each with class 'source-description' and metadata: name, type, retrievalURI).
  *   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 sourceDescriptions option is disabled or no names match.
+ *   Returns an empty array when no source description names match the filter.
  *
  * @example
  * ```typescript
+ * import { toValue } from '@speclynx/apidom-core';
  * import { options, mergeOptions } from '@speclynx/apidom-reference';
  * import { parseSourceDescriptions } from '@speclynx/apidom-reference/parse/parsers/arazzo-json-1';
  *
- * const fullOptions = mergeOptions(options, {
- *   parse: { parserOpts: { sourceDescriptions: true } }
- * });
- * const results = await parseSourceDescriptions(parseResult, uri, fullOptions);
+ * // 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');
+ * const retrievalURI = toValue(parsedDoc.meta.get('retrievalURI'));
  * ```
  *
  * @public

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[]>;