@speclynx/apidom-reference 2.8.0 → 2.10.0

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [2.10.0](https://github.com/speclynx/apidom/compare/v2.9.0...v2.10.0) (2026-02-08)
+
+### Features
+
+- **reference:** add retrievalURI metadata for Arazzo Source Descriptions ([#79](https://github.com/speclynx/apidom/issues/79)) ([df78cb3](https://github.com/speclynx/apidom/commit/df78cb3226521e6f7097b85cccdbc6b0b39e7a7b))
+
+# [2.9.0](https://github.com/speclynx/apidom/compare/v2.8.0...v2.9.0) (2026-02-08)
+
+### Features
+
+- **reference:** attach parse result as meta to Arazzo source descriptions ([#76](https://github.com/speclynx/apidom/issues/76)) ([448a099](https://github.com/speclynx/apidom/commit/448a099fc6af8189302346efdcc117c95c9b6e3b))
+- **reference:** avoid re-resolving Arazzo source descriptions during dereferencing ([#77](https://github.com/speclynx/apidom/issues/77)) ([0ad63e8](https://github.com/speclynx/apidom/commit/0ad63e8d204d991a0de47b486ad391d506eb66dc))
+- **reference:** expose low level API for dereferencing Arazzo source descriptions ([#75](https://github.com/speclynx/apidom/issues/75)) ([3b1e343](https://github.com/speclynx/apidom/commit/3b1e343c58ff983201ac0509bf841845bbf7eb83))
+
 # [2.8.0](https://github.com/speclynx/apidom/compare/v2.7.0...v2.8.0) (2026-02-06)
 
 ### Features

package/README.md

@@ -301,7 +301,7 @@ Parser-specific options take precedence over global options.
   - `true` - parse all source descriptions
   - `string[]` - parse only source descriptions with matching names (e.g., `['petStore', 'paymentApi']`)
 
-  Each parsed source description is added with a `'source-description'` class and metadata (`name`, `type`).
+  Each parsed source description is added with a `'source-description'` class and metadata (`name`, `type`, `retrievalURI`).
   Only OpenAPI 2.0, OpenAPI 3.0.x, OpenAPI 3.1.x, and Arazzo 1.x documents are accepted as source descriptions.
 - **sourceDescriptionsMaxDepth** - Maximum recursion depth for parsing nested Arazzo source descriptions.
   Defaults to `+Infinity`. Circular references are automatically detected and skipped.
@@ -321,6 +321,7 @@ with an `'error'` class within the parse result:
   for parsing are not met (e.g., API is not an Arazzo specification)
 
 ```js
+import { toValue } from '@speclynx/apidom-core';
 import { parse } from '@speclynx/apidom-reference';
 
 // Parse all source descriptions
@@ -345,12 +346,89 @@ const parseResultFiltered = await parse('/path/to/arazzo.json', {
 // Access parsed source descriptions
 for (const element of parseResult) {
   if (element.classes.includes('source-description')) {
-    console.log(element.meta.get('name').toValue()); // e.g., 'petStore'
-    console.log(element.meta.get('type').toValue()); // e.g., 'openapi'
+    console.log(toValue(element.meta.get('name'))); // e.g., 'petStore'
+    console.log(toValue(element.meta.get('type'))); // e.g., 'openapi'
+    console.log(toValue(element.meta.get('retrievalURI'))); // e.g., '/path/to/petstore.json'
   }
 }
 ```
 
+##### 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 { toValue } from '@speclynx/apidom-core';
+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'
+  console.log(toValue(parsedDoc.meta.get('retrievalURI'))); // URI where it was fetched from
+}
+```
+
+##### 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.
+
+When called directly, this function always parses source descriptions (no need to pass `sourceDescriptions: true`).
+Use an array to filter by name:
+
+```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 all source descriptions
+const sourceDescriptions = await parseSourceDescriptions(
+  parseResult,
+  '/path/to/arazzo.json',
+  options,
+);
+
+// Or filter by name
+const filtered = await parseSourceDescriptions(
+  parseResult,
+  '/path/to/arazzo.json',
+  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');
+```
+
+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
@@ -376,7 +454,7 @@ Parser-specific options take precedence over global options. See [arazzo-json-1]
   - `true` - parse all source descriptions
   - `string[]` - parse only source descriptions with matching names (e.g., `['petStore', 'paymentApi']`)
 
-  Each parsed source description is added with a `'source-description'` class and metadata (`name`, `type`).
+  Each parsed source description is added with a `'source-description'` class and metadata (`name`, `type`, `retrievalURI`).
   Only OpenAPI 2.0, OpenAPI 3.0.x, OpenAPI 3.1.x, and Arazzo 1.x documents are accepted as source descriptions.
 - **sourceDescriptionsMaxDepth** - Maximum recursion depth for parsing nested Arazzo source descriptions.
   Defaults to `+Infinity`. Circular references are automatically detected and skipped.
@@ -385,6 +463,55 @@ 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.
+
+When called directly, this function always parses source descriptions (no need to pass `sourceDescriptions: true`).
+Use an array to filter by name:
+
+```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 all source descriptions
+const sourceDescriptions = await parseSourceDescriptions(
+  parseResult,
+  '/path/to/arazzo.yaml',
+  options,
+);
+
+// Or filter by name
+const filtered = await parseSourceDescriptions(
+  parseResult,
+  '/path/to/arazzo.yaml',
+  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');
+```
+
+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
@@ -1633,7 +1760,7 @@ Strategy-specific options take precedence over global options.
   - `true` - dereference all source descriptions
   - `string[]` - dereference only source descriptions with matching names (e.g., `['petStore', 'paymentApi']`)
 
-  Each dereferenced source description is added with a `'source-description'` class and metadata (`name`, `type`).
+  Each dereferenced source description is added with a `'source-description'` class and metadata (`name`, `type`, `retrievalURI`).
   Only OpenAPI 2.0, OpenAPI 3.0.x, OpenAPI 3.1.x, and Arazzo 1.x documents are accepted as source descriptions.
 - **sourceDescriptionsMaxDepth** - Maximum recursion depth for dereferencing nested Arazzo source descriptions.
   Defaults to `+Infinity`. Circular references are automatically detected and skipped.
@@ -1677,6 +1804,82 @@ 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 { toValue } from '@speclynx/apidom-core';
+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'
+  console.log(toValue(dereferencedDoc.meta.get('retrievalURI'))); // URI where it was fetched from
+}
+```
+
+###### 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.
+
+When called directly, this function always dereferences source descriptions (no need to pass `sourceDescriptions: true`).
+Use an array to filter by name:
+
+```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 all source descriptions
+const sourceDescriptions = await dereferenceSourceDescriptions(
+  parseResult,
+  '/path/to/arazzo.json',
+  options,
+);
+
+// Or filter by name
+const filtered = await dereferenceSourceDescriptions(
+  parseResult,
+  '/path/to/arazzo.json',
+  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');
+```
+
+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.