feat(reference): attach parse result as meta to Arazzo source descriptions (#76)

Author: char0n

packages/apidom-reference/README.md

@@ -351,6 +351,70 @@ for (const element of parseResult) {
 }
 ```
 
+##### Accessing parsed documents via SourceDescriptionElement
+
+When source descriptions parsing is enabled, a `ParseResultElement` is attached to each
+`SourceDescriptionElement`'s meta as `'parseResult'`. This attachment always happens,
+regardless of success or failure:
+
+- **On success**: The parseResult contains the parsed API document
+- **On failure**: The parseResult contains error/warning annotations explaining what went wrong
+
+```js
+import { parse } from '@speclynx/apidom-reference';
+
+const parseResult = await parse('/path/to/arazzo.json', {
+  parse: { parserOpts: { sourceDescriptions: true } },
+});
+
+// Access parsed document from source description element
+const api = parseResult.api;
+const sourceDesc = api.sourceDescriptions.get(0);
+const parsedDoc = sourceDesc.meta.get('parseResult');
+
+// Check for errors before using
+if (parsedDoc.errors.length > 0) {
+  console.log('Parsing failed:', parsedDoc.errors);
+} else {
+  console.log(parsedDoc.api.element); // e.g., 'openApi3_1'
+}
+```
+
+##### Low-level API
+
+For advanced use cases where you need to parse source descriptions from an already-parsed Arazzo document
+(e.g., when using naked parser adapters directly), the `parseSourceDescriptions` function is exported:
+
+```js
+import { parse } from '@speclynx/apidom-parser-adapter-arazzo-json-1';
+import { parseSourceDescriptions } from '@speclynx/apidom-reference/parse/parsers/arazzo-json-1';
+import { options, mergeOptions } from '@speclynx/apidom-reference';
+
+// Parse using naked parser adapter
+const parseResult = await parse(arazzoJsonString);
+
+// Parse source descriptions separately
+const sourceDescriptions = await parseSourceDescriptions(
+  parseResult,
+  '/path/to/arazzo.json',
+  mergeOptions(options, { parse: { parserOpts: { sourceDescriptions: true } } }),
+);
+
+// Access parsed document from source description element
+const sourceDesc = parseResult.api.sourceDescriptions.get(0);
+const parsedDoc = sourceDesc.meta.get('parseResult');
+```
+
+The function signature is:
+```typescript
+parseSourceDescriptions(
+  parseResult: ParseResultElement,
+  parseResultRetrievalURI: string,
+  options: ReferenceOptions,
+  parserName?: string, // defaults to 'arazzo-json-1'
+): Promise<ParseResultElement[]>
+```
+
 #### [arazzo-yaml-1](https://github.com/speclynx/apidom/tree/main/packages/apidom-reference/src/parse/parsers/arazzo-yaml-1)
 
 Wraps [@speclynx/apidom-parser-adapter-arazzo-yaml-1](https://github.com/speclynx/apidom/tree/main/packages/apidom-parser-adapter-arazzo-yaml-1) package
@@ -385,6 +449,45 @@ Parser-specific options take precedence over global options. See [arazzo-json-1]
 
 See [arazzo-json-1 Error handling](#error-handling) - the behavior is identical for both JSON and YAML parsers.
 
+##### Accessing parsed documents via SourceDescriptionElement
+
+See [arazzo-json-1 Accessing parsed documents](#accessing-parsed-documents-via-sourcedescriptionelement) - the behavior is identical for both JSON and YAML parsers.
+
+##### Low-level API
+
+For advanced use cases where you need to parse source descriptions from an already-parsed Arazzo document
+(e.g., when using naked parser adapters directly), the `parseSourceDescriptions` function is exported:
+
+```js
+import { parse } from '@speclynx/apidom-parser-adapter-arazzo-yaml-1';
+import { parseSourceDescriptions } from '@speclynx/apidom-reference/parse/parsers/arazzo-yaml-1';
+import { options, mergeOptions } from '@speclynx/apidom-reference';
+
+// Parse using naked parser adapter
+const parseResult = await parse(arazzoYamlString);
+
+// Parse source descriptions separately
+const sourceDescriptions = await parseSourceDescriptions(
+  parseResult,
+  '/path/to/arazzo.yaml',
+  mergeOptions(options, { parse: { parserOpts: { sourceDescriptions: true } } }),
+);
+
+// Access parsed document from source description element
+const sourceDesc = parseResult.api.sourceDescriptions.get(0);
+const parsedDoc = sourceDesc.meta.get('parseResult');
+```
+
+The function signature is:
+```typescript
+parseSourceDescriptions(
+  parseResult: ParseResultElement,
+  parseResultRetrievalURI: string,
+  options: ReferenceOptions,
+  parserName?: string, // defaults to 'arazzo-yaml-1'
+): Promise<ParseResultElement[]>
+```
+
 #### [json](https://github.com/speclynx/apidom/tree/main/packages/apidom-reference/src/parse/parsers/json)
 
 Wraps [@speclynx/apidom-parser-adapter-json](https://github.com/speclynx/apidom/tree/main/packages/apidom-parser-adapter-json) package
@@ -1677,6 +1780,70 @@ const resultFiltered = await dereference('/path/to/arazzo.json', {
 });
 ```
 
+###### Accessing dereferenced documents via SourceDescriptionElement
+
+When source descriptions dereferencing is enabled, a `ParseResultElement` is attached to each
+`SourceDescriptionElement`'s meta as `'parseResult'`. This attachment always happens,
+regardless of success or failure:
+
+- **On success**: The parseResult contains the dereferenced API document
+- **On failure**: The parseResult contains error/warning annotations explaining what went wrong
+
+```js
+import { dereference } from '@speclynx/apidom-reference';
+
+const parseResult = await dereference('/path/to/arazzo.json', {
+  dereference: { strategyOpts: { sourceDescriptions: true } },
+});
+
+// Access dereferenced document from source description element
+const api = parseResult.api;
+const sourceDesc = api.sourceDescriptions.get(0);
+const dereferencedDoc = sourceDesc.meta.get('parseResult');
+
+// Check for errors before using
+if (dereferencedDoc.errors.length > 0) {
+  console.log('Dereferencing failed:', dereferencedDoc.errors);
+} else {
+  console.log(dereferencedDoc.api.element); // e.g., 'openApi3_1'
+}
+```
+
+###### Low-level API
+
+For advanced use cases where you need to dereference source descriptions from an already-parsed (optionally dereferenced)
+Arazzo document (e.g., when using naked parser adapters directly), the `dereferenceSourceDescriptions` function is exported:
+
+```js
+import { parse } from '@speclynx/apidom-parser-adapter-arazzo-json-1';
+import { dereferenceSourceDescriptions } from '@speclynx/apidom-reference/dereference/strategies/arazzo-1';
+import { options, mergeOptions } from '@speclynx/apidom-reference';
+
+// Parse using naked parser adapter
+const parseResult = await parse(arazzoJsonString);
+
+// Dereference source descriptions separately
+const sourceDescriptions = await dereferenceSourceDescriptions(
+  parseResult,
+  '/path/to/arazzo.json',
+  mergeOptions(options, { dereference: { strategyOpts: { sourceDescriptions: true } } }),
+);
+
+// Access dereferenced document from source description element
+const sourceDesc = parseResult.api.sourceDescriptions.get(0);
+const dereferencedDoc = sourceDesc.meta.get('parseResult');
+```
+
+The function signature is:
+```typescript
+dereferenceSourceDescriptions(
+  parseResult: ParseResultElement,
+  parseResultRetrievalURI: string,
+  options: ReferenceOptions,
+  strategyName?: string, // defaults to 'arazzo-1'
+): Promise<ParseResultElement[]>
+```
+
 ##### [openapi-2](https://github.com/speclynx/apidom/tree/main/packages/apidom-reference/src/dereference/strategies/openapi-2)
 
 Dereference strategy for dereferencing [OpenApi 2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) definitions.

packages/apidom-reference/src/dereference/strategies/arazzo-1/source-descriptions.ts

@@ -152,6 +152,11 @@ async function dereferenceSourceDescription(
 /**
  * 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 (caller responsibility to construct)
@@ -164,6 +169,13 @@ async function dereferenceSourceDescription(
  *   - Maximum dereference depth is exceeded (error annotation)
  *   Returns an empty array when sourceDescriptions option is disabled or no names match.
  *
+ * @example
+ * ```typescript
+ * // Access dereferenced document from source description element
+ * const sourceDesc = parseResult.api.sourceDescriptions.get(0);
+ * const dereferencedDoc = sourceDesc.meta.get('parseResult');
+ * ```
+ *
  * @public
  */
 export async function dereferenceSourceDescriptions(
@@ -252,6 +264,8 @@ export async function dereferenceSourceDescriptions(
       sourceDescription,
       ctx,
     );
+    // always attach result (even on failure - contains annotations)
+    sourceDescription.meta.set('parseResult', sourceDescriptionDereferenceResult);
     results.push(sourceDescriptionDereferenceResult);
   }
 

packages/apidom-reference/src/parse/parsers/arazzo-json-1/source-descriptions.ts

@@ -151,6 +151,11 @@ async function parseSourceDescription(
 /**
  * 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)
@@ -172,6 +177,10 @@ async function parseSourceDescription(
  *   parse: { parserOpts: { sourceDescriptions: true } }
  * });
  * const results = await parseSourceDescriptions(parseResult, uri, fullOptions);
+ *
+ * // Access parsed document from source description element
+ * const sourceDesc = parseResult.api.sourceDescriptions.get(0);
+ * const parsedDoc = sourceDesc.meta.get('parseResult');
  * ```
  *
  * @public
@@ -257,6 +266,8 @@ export async function parseSourceDescriptions(
   // 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);
   }
 

packages/apidom-reference/test/dereference/strategies/arazzo-1/source-descriptions/source-descriptions.ts

@@ -145,6 +145,29 @@ describe('dereference', function () {
         assert.isTrue(sdParseResult.classes.includes('source-description'));
         assert.strictEqual(sdParseResult.meta.get('name')!.toValue(), 'petStore');
       });
+
+      specify('should attach parseResult to source description element meta', async function () {
+        const uri = path.join(__dirname, 'fixtures', 'root.json');
+        const data = fs.readFileSync(uri).toString();
+        const parseResult = await parse(data);
+
+        await dereferenceSourceDescriptions(
+          parseResult,
+          uri,
+          mergeOptions(options, {
+            dereference: { strategyOpts: { sourceDescriptions: true } },
+          }),
+        );
+
+        // verify meta is set on source description element
+        const api: any = parseResult.api!;
+        const sourceDescriptions = api.get('sourceDescriptions');
+        const sourceDesc = sourceDescriptions.get(0);
+        const attachedParseResult = sourceDesc.meta.get('parseResult') as ParseResultElement;
+
+        assert.isTrue(isParseResultElement(attachedParseResult));
+        assert.strictEqual(attachedParseResult.api?.element, 'openApi3_1');
+      });
     });
   });
 });

packages/apidom-reference/test/parse/parsers/arazzo-json-1/source-descriptions.ts

@@ -143,6 +143,27 @@ describe('parsers', function () {
         assert.isTrue(sdParseResult.classes.includes('source-description'));
         assert.strictEqual(sdParseResult.meta.get('name')!.toValue(), 'petStore');
       });
+
+      specify('should attach parseResult to source description element meta', async function () {
+        const uri = path.join(__dirname, 'fixtures', 'source-descriptions', 'root.json');
+        const data = fs.readFileSync(uri).toString();
+        const parseResult = await parse(data);
+
+        await parseSourceDescriptions(
+          parseResult,
+          uri,
+          mergeOptions(options, { parse: { parserOpts: { sourceDescriptions: true } } }),
+        );
+
+        // verify meta is set on source description element
+        const api: any = parseResult.api!;
+        const sourceDescriptions = api.get('sourceDescriptions');
+        const sourceDesc = sourceDescriptions.get(0);
+        const attachedParseResult = sourceDesc.meta.get('parseResult') as ParseResultElement;
+
+        assert.isTrue(isParseResultElement(attachedParseResult));
+        assert.strictEqual(attachedParseResult.api?.element, 'openApi3_1');
+      });
     });
   });
 });

packages/apidom-reference/test/parse/parsers/arazzo-yaml-1/source-descriptions.ts

@@ -143,6 +143,27 @@ describe('parsers', function () {
         assert.isTrue(sdParseResult.classes.includes('source-description'));
         assert.strictEqual(sdParseResult.meta.get('name')!.toValue(), 'petStore');
       });
+
+      specify('should attach parseResult to source description element meta', async function () {
+        const uri = path.join(__dirname, 'fixtures', 'source-descriptions', 'root.yaml');
+        const data = fs.readFileSync(uri).toString();
+        const parseResult = await parse(data);
+
+        await parseSourceDescriptions(
+          parseResult,
+          uri,
+          mergeOptions(options, { parse: { parserOpts: { sourceDescriptions: true } } }),
+        );
+
+        // verify meta is set on source description element
+        const api: any = parseResult.api!;
+        const sourceDescriptions = api.get('sourceDescriptions');
+        const sourceDesc = sourceDescriptions.get(0);
+        const attachedParseResult = sourceDesc.meta.get('parseResult') as ParseResultElement;
+
+        assert.isTrue(isParseResultElement(attachedParseResult));
+        assert.strictEqual(attachedParseResult.api?.element, 'openApi3_1');
+      });
     });
   });
 });