@jentic/arazzo-parser 1.0.0-alpha.4 → 1.0.0-alpha.6

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [1.0.0-alpha.6](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.5...v1.0.0-alpha.6) (2026-02-04)
+
+### Features
+
+- **parser:** add support for parsing entire Arazzo Description ([#34](https://github.com/jentic/jentic-arazzo-tools/issues/34)) ([44b2bda](https://github.com/jentic/jentic-arazzo-tools/commit/44b2bda1c7449e1db8145af1dea457f2e09a465b))
+
+# [1.0.0-alpha.5](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.4...v1.0.0-alpha.5) (2026-01-31)
+
+**Note:** Version bump only for package @jentic/arazzo-parser
+
 # [1.0.0-alpha.4](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.3...v1.0.0-alpha.4) (2026-01-31)
 
 ### Features

package/README.md

@@ -13,17 +13,21 @@ npm install @jentic/arazzo-parser
 
 ## Usage
 
-`@jentic/arazzo-parser` provides a unified `parse` function that accepts multiple input types:
+`@jentic/arazzo-parser` provides a `parseArazzo` function for parsing Arazzo documents.
 
-1. **Plain JavaScript object** - directly refracts into ApiDOM
-2. **String content** - parses inline JSON or YAML Arazzo Documents
+## Parsing Arazzo Documents
+
+The `parseArazzo` function accepts multiple input types:
+
+1. **Plain JavaScript object** - converts to JSON and parses (source maps supported with `strict: false`)
+2. **String content** - detects Arazzo content and parses inline JSON or YAML
 3. **File system path** - resolves and parses local Arazzo Documents
 4. **HTTP(S) URL** - fetches and parses remote Arazzo Documents
 
-### Parsing from object
+### From object
 
 ```js
-import { parse } from '@jentic/arazzo-parser';
+import { parseArazzo } from '@jentic/arazzo-parser';
 
 const arazzoDocument = {
   arazzo: '1.0.1',
@@ -41,20 +45,20 @@ const arazzoDocument = {
   workflows: [],
 };
 
-const parseResult = await parse(arazzoDocument);
+const parseResult = await parseArazzo(arazzoDocument);
 // parseResult is ParseResultElement containing ArazzoSpecification1Element
 ```
 
-### Parsing from string
+### From string
 
 ```js
-import { parse } from '@jentic/arazzo-parser';
+import { parseArazzo } from '@jentic/arazzo-parser';
 
 // JSON string
-const parseResult = await parse('{"arazzo": "1.0.1", "info": {...}}');
+const parseResult = await parseArazzo('{"arazzo": "1.0.1", "info": {...}}');
 
 // YAML string
-const parseResult = await parse(`
+const parseResult = await parseArazzo(`
 arazzo: '1.0.1'
 info:
   title: My API Workflow
@@ -62,30 +66,30 @@ info:
 `);
 ```
 
-### Parsing from file
+### From file
 
 ```js
-import { parse } from '@jentic/arazzo-parser';
+import { parseArazzo } from '@jentic/arazzo-parser';
 
-const parseResult = await parse('/path/to/arazzo.json');
+const parseResult = await parseArazzo('/path/to/arazzo.json');
 ```
 
-### Parsing from URL
+### From URL
 
 ```js
-import { parse } from '@jentic/arazzo-parser';
+import { parseArazzo } from '@jentic/arazzo-parser';
 
-const parseResult = await parse('https://example.com/arazzo.yaml');
+const parseResult = await parseArazzo('https://example.com/arazzo.yaml');
 ```
 
 ## Parse options
 
-The `parse` function accepts an optional second argument with reference options compatible with [SpecLynx ApiDOM Reference Options](https://github.com/speclynx/apidom/blob/main/packages/apidom-reference/src/options/index.ts):
+The `parseArazzo` function accepts an optional second argument with reference options compatible with [SpecLynx ApiDOM Reference Options](https://github.com/speclynx/apidom/blob/main/packages/apidom-reference/src/options/index.ts):
 
 ```js
-import { parse } from '@jentic/arazzo-parser';
+import { parseArazzo } from '@jentic/arazzo-parser';
 
-const parseResult = await parse(source, {
+const parseResult = await parseArazzo(source, {
   parse: {
     parserOpts: {
       strict: true,      // Use strict parsing mode (default: true)
@@ -105,11 +109,16 @@ import { defaultOptions } from '@jentic/arazzo-parser';
 console.log(defaultOptions);
 // {
 //   parse: {
-//     parsers: [...],
-//     parserOpts: {},
+//     parsers: [
+//       ArazzoJSON1Parser, ArazzoYAML1Parser,
+//       OpenApiJSON2Parser, OpenApiYAML2Parser,
+//       OpenApiJSON3_0Parser, OpenApiYAML3_0Parser,
+//       OpenApiJSON3_1Parser, OpenApiYAML3_1Parser,
+//     ],
+//     parserOpts: { sourceMap: false, strict: true, sourceDescriptions: false },
 //   },
 //   resolve: {
-//     resolvers: [...],
+//     resolvers: [MemoryResolver, FileResolver, HTTPResolverAxios],
 //     resolverOpts: {},
 //   },
 // }
@@ -120,24 +129,49 @@ console.log(defaultOptions);
 When parsing fails, a `ParseError` is thrown. The original error is available via the `cause` property:
 
 ```js
-import { parse } from '@jentic/arazzo-parser';
+import { parseArazzo } from '@jentic/arazzo-parser';
 
 try {
-  await parse('invalid content');
+  await parseArazzo('invalid content');
 } catch (error) {
   console.error(error.message);  // 'Failed to parse Arazzo Document'
   console.error(error.cause);    // Original error from underlying parser
 }
 ```
 
+### Non-Arazzo documents
+
+When a valid document is parsed but it's not an Arazzo specification (e.g., an OpenAPI document), the parser does not throw. Instead, it returns a `ParseResultElement` with:
+
+- An error annotation explaining the issue
+- `.api` returns `undefined`
+- The parsed document remains accessible in the parse result
+
+```js
+import { parseArazzo } from '@jentic/arazzo-parser';
+
+const openApiDoc = {
+  openapi: '3.1.0',
+  info: { title: 'My API', version: '1.0.0' },
+  paths: {},
+};
+
+const result = await parseArazzo(openApiDoc);
+
+result.api;              // undefined
+result.errors.length;    // 1
+result.errors.get(0).toValue();
+// 'Document is not a valid Arazzo specification...'
+```
+
 ## Working with the result
 
-The `parse` function returns a [ParseResultElement](https://github.com/speclynx/apidom/blob/main/packages/apidom-datamodel/README.md#parseresultelement) representing the result of the parsing operation.
+The `parseArazzo` function returns a [ParseResultElement](https://github.com/speclynx/apidom/blob/main/packages/apidom-datamodel/README.md#parseresultelement) representing the result of the parsing operation.
 
 ```js
-import { parse } from '@jentic/arazzo-parser';
+import { parseArazzo } from '@jentic/arazzo-parser';
 
-const parseResult = await parse(source);
+const parseResult = await parseArazzo(source);
 
 // Access the main Arazzo specification element
 const arazzoSpec = parseResult.api;
@@ -154,10 +188,10 @@ const isEmpty = parseResult.isEmpty;
 When parsing from a file system path or HTTP(S) URL, the `retrievalURI` metadata is set on the parse result:
 
 ```js
-import { parse } from '@jentic/arazzo-parser';
+import { parseArazzo } from '@jentic/arazzo-parser';
 import { toValue } from '@speclynx/apidom-core';
 
-const parseResult = await parse('/path/to/arazzo.json');
+const parseResult = await parseArazzo('/path/to/arazzo.json');
 
 // Get the URI from which the document was retrieved
 const uri = toValue(parseResult.meta.get('retrievalURI'));
@@ -170,15 +204,17 @@ Note: `retrievalURI` is not set when parsing from inline content (string) or pla
 
 Source maps allow you to track the original position (line, column) of each element in the parsed document. This is useful for error reporting, IDE integrations, linting, and any tooling that needs to show precise locations in the original source.
 
-To enable source maps, set `sourceMap: true` in the parser options:
+
+To enable source maps, set `sourceMap: true` and `strict: false` in the parser options:
 
 ```js
-import { parse } from '@jentic/arazzo-parser';
+import { parseArazzo } from '@jentic/arazzo-parser';
 
-const parseResult = await parse('/path/to/arazzo.yaml', {
+const parseResult = await parseArazzo('/path/to/arazzo.yaml', {
   parse: {
     parserOpts: {
       sourceMap: true,
+      strict: false,
     },
   },
 });
@@ -187,10 +223,10 @@ const parseResult = await parse('/path/to/arazzo.yaml', {
 When source maps are enabled, each element in the parsed result contains positional properties stored directly on the element. Position values use UTF-16 code units for compatibility with Language Server Protocol (LSP) and JavaScript string indexing:
 
 ```js
-import { parse } from '@jentic/arazzo-parser';
+import { parseArazzo } from '@jentic/arazzo-parser';
 
-const parseResult = await parse('/path/to/arazzo.yaml', {
-  parse: { parserOpts: { sourceMap: true } },
+const parseResult = await parseArazzo('/path/to/arazzo.yaml', {
+  parse: { parserOpts: { sourceMap: true, strict: false } },
 });
 
 const arazzoSpec = parseResult.api;
@@ -210,15 +246,208 @@ console.log(`Workflow starts at line ${workflow.startLine}, column ${workflow.st
 
 For more details about source maps, see the [SpecLynx ApiDOM Data Model documentation](https://github.com/speclynx/apidom/tree/main/packages/apidom-datamodel#source-maps).
 
-**Note:** Source maps are only available when parsing from string content, file paths, or URLs. When parsing from a plain JavaScript object, source maps cannot be generated and attempting to enable them will throw a `ParseError`:
+**Note:** Source maps require `strict: false` to be set. When parsing from objects, they are converted to pretty-printed JSON strings internally (2-space indentation), so source map positions refer to this generated JSON representation, not the original object structure:
 
 ```js
-// This will throw ParseError
-await parse({ arazzo: '1.0.1', ... }, {
-  parse: { parserOpts: { sourceMap: true } },
+// Source maps with objects (requires strict: false)
+// Positions will reference the internally generated JSON string
+await parseArazzo({ arazzo: '1.0.1', ... }, {
+  parse: { parserOpts: { sourceMap: true, strict: false } },
 });
 ```
 
+## Parsing source descriptions
+
+Arazzo documents can reference external API specifications (OpenAPI, Arazzo) through [Source Descriptions](https://spec.openapis.org/arazzo/latest.html#source-description-object). The parser can automatically fetch and parse these referenced documents.
+
+**Note:** Source descriptions parsing is disabled by default for performance reasons. Enable it explicitly when you need to resolve and parse referenced API specifications.
+
+### Enabling source descriptions parsing
+
+To parse source descriptions, enable the `sourceDescriptions` option in `parserOpts`:
+
+```js
+import { parseArazzo } from '@jentic/arazzo-parser';
+
+const parseResult = await parseArazzo('/path/to/arazzo.json', {
+  parse: {
+    parserOpts: {
+      sourceDescriptions: true,
+    },
+  },
+});
+```
+
+Alternatively, you can configure it per parser for more granular control:
+
+```js
+const parseResult = await parseArazzo('/path/to/arazzo.json', {
+  parse: {
+    parserOpts: {
+      'arazzo-json-1': { sourceDescriptions: true },
+      'arazzo-yaml-1': { sourceDescriptions: true },
+    },
+  },
+});
+```
+
+### Selective parsing
+
+You can selectively parse only specific source descriptions by providing an array of names:
+
+```js
+const parseResult = await parseArazzo('/path/to/arazzo.json', {
+  parse: {
+    parserOpts: {
+      sourceDescriptions: ['petStoreApi', 'paymentApi'],
+    },
+  },
+});
+```
+
+### Result structure
+
+When source descriptions are parsed, each parsed document that is a *direct* source description of the main Arazzo document is added to the main `ParseResultElement` as an additional top-level element. The first element is always the main Arazzo document, and subsequent top-level elements are these directly parsed source descriptions. When recursive parsing discovers further source descriptions from within an already parsed source description, those recursively parsed documents are attached as nested `ParseResultElement` instances beneath the source-description element that referenced them (they are not duplicated at the top level). Consumers that need to see all documents should traverse both the top-level elements and any nested `ParseResultElement`s reachable from source-description elements.
+
+Source descriptions are parsed into their appropriate SpecLynx ApiDOM namespace data models based on document type:
+
+- **Arazzo** → [@speclynx/apidom-ns-arazzo-1](https://github.com/speclynx/apidom/tree/main/packages/apidom-ns-arazzo-1)
+- **OpenAPI 2.0** → [@speclynx/apidom-ns-openapi-2](https://github.com/speclynx/apidom/tree/main/packages/apidom-ns-openapi-2)
+- **OpenAPI 3.0.x** → [@speclynx/apidom-ns-openapi-3-0](https://github.com/speclynx/apidom/tree/main/packages/apidom-ns-openapi-3-0)
+- **OpenAPI 3.1.x** → [@speclynx/apidom-ns-openapi-3-1](https://github.com/speclynx/apidom/tree/main/packages/apidom-ns-openapi-3-1)
+
+```mermaid
+graph TD
+    PR["ParseResultElement"] --> API[".api: ArazzoSpecification1Element"]
+    PR --> SD1
+    PR --> SD2
+
+    subgraph source-descriptions [source descriptions]
+        SD1["ParseResultElement<br/>(petStoreApi)"] --> SD1_API[".api: OpenApi3_1Element"]
+        SD2["ParseResultElement<br/>(legacyApi)"] --> SD2_ERR[".errors"]
+        SD2 --> SD2_WARN[".warnings"]
+    end
+
+    style PR fill:#e7f1ff,stroke:#0366d6,stroke-width:2px
+    style SD1 fill:#f6f8fa,stroke:#586069
+    style SD2 fill:#f6f8fa,stroke:#586069
+    style API fill:#d4edda,stroke:#28a745
+    style SD1_API fill:#d4edda,stroke:#28a745
+    style SD2_ERR fill:#f8d7da,stroke:#dc3545
+    style SD2_WARN fill:#fff3cd,stroke:#ffc107
+```
+
+```js
+import { parseArazzo } from '@jentic/arazzo-parser';
+
+const parseResult = await parseArazzo('/path/to/arazzo.json', {
+  parse: {
+    parserOpts: {
+      sourceDescriptions: true,
+    },
+  },
+});
+
+// Main Arazzo document
+const arazzoSpec = parseResult.api;
+
+// Number of elements (1 main + N source descriptions)
+console.log(parseResult.length);
+
+// Access parsed source descriptions (filter by 'source-description' class)
+for (let i = 0; i < parseResult.length; i++) {
+  const element = parseResult.get(i);
+
+  if (element.classes.includes('source-description')) {
+    // Source description metadata
+    const name = element.meta.get('name')?.toValue();
+    const type = element.meta.get('type')?.toValue();
+
+    console.log(`Source description "${name}" (${type})`);
+
+    // The parsed API document
+    const api = element.api;
+  }
+}
+```
+
+### Recursive parsing
+
+When a source description is of type `arazzo`, the parser recursively parses that document's source descriptions as well. This allows you to parse entire dependency trees of Arazzo documents.
+
+### Limiting recursion depth
+
+To prevent excessive recursion or handle deeply nested documents, use the `sourceDescriptionsMaxDepth` option:
+
+```js
+const parseResult = await parseArazzo('/path/to/arazzo.json', {
+  parse: {
+    parserOpts: {
+      sourceDescriptions: true,
+      sourceDescriptionsMaxDepth: 2, // Only parse 2 levels deep
+    },
+  },
+});
+```
+
+The default value is `+Infinity` (no limit). Setting it to `0` will create error annotations instead of parsing any source descriptions.
+
+### Cycle detection
+
+The parser automatically detects circular references between Arazzo documents. When a cycle is detected, a warning annotation is added instead of causing infinite recursion:
+
+```js
+// arazzo-a.json references arazzo-b.json
+// arazzo-b.json references arazzo-a.json (cycle!)
+
+const parseResult = await parseArazzo('/path/to/arazzo-a.json', {
+  parse: {
+    parserOpts: {
+      sourceDescriptions: true,
+    },
+  },
+});
+
+// The cycle is handled gracefully - check for warning annotations
+```
+
+### Error and warning handling
+
+When issues occur during source description parsing, the parser does not throw errors. Instead, it adds annotation elements to the source description's parse result:
+
+- **`error`** class - Parsing failed (e.g., file not found, invalid document, max depth exceeded)
+- **`warning`** class - Non-fatal issues (e.g., cycle detected, type mismatch between declared and actual)
+
+This allows partial parsing to succeed even if some source descriptions have issues:
+
+```js
+const parseResult = await parseArazzo('/path/to/arazzo.json', {
+  parse: {
+    parserOpts: {
+      sourceDescriptions: true,
+    },
+  },
+});
+
+// Check each source description for errors and warnings
+for (let i = 0; i < parseResult.length; i++) {
+  const element = parseResult.get(i);
+
+  if (element.classes.includes('source-description')) {
+    const name = element.meta.get('name')?.toValue();
+
+    // Use built-in accessors for errors and warnings
+    element.errors.forEach((error) => {
+      console.error(`Error in "${name}": ${error.toValue()}`);
+    });
+
+    element.warnings.forEach((warning) => {
+      console.warn(`Warning in "${name}": ${warning.toValue()}`);
+    });
+  }
+}
+```
+
 ## SpecLynx ApiDOM tooling
 
 Since `@jentic/arazzo-parser` produces a SpecLynx ApiDOM data model, you have access to the full suite of ApiDOM tools for manipulating, traversing, and transforming the parsed document.
@@ -228,11 +457,11 @@ Since `@jentic/arazzo-parser` produces a SpecLynx ApiDOM data model, you have ac
 The [@speclynx/apidom-core](https://github.com/speclynx/apidom/tree/main/packages/apidom-core) package provides essential utilities for working with ApiDOM elements. Here are just a few examples:
 
 ```js
-import { parse } from '@jentic/arazzo-parser';
+import { parseArazzo } from '@jentic/arazzo-parser';
 import { cloneDeep, cloneShallow } from '@speclynx/apidom-datamodel';
 import { toValue, toJSON, toYAML, sexprs } from '@speclynx/apidom-core';
 
-const parseResult = await parse(source);
+const parseResult = await parseArazzo(source);
 const arazzoSpec = parseResult.api;
 
 // Convert to plain JavaScript object
@@ -257,10 +486,10 @@ const sexpr = sexprs(arazzoSpec);
 The [@speclynx/apidom-traverse](https://github.com/speclynx/apidom/tree/main/packages/apidom-traverse) package provides powerful traversal capabilities. Here is a basic example:
 
 ```js
-import { parse } from '@jentic/arazzo-parser';
+import { parseArazzo } from '@jentic/arazzo-parser';
 import { traverse } from '@speclynx/apidom-traverse';
 
-const parseResult = await parse(source);
+const parseResult = await parseArazzo(source);
 
 // Traverse and collect steps using semantic visitor hook
 const steps = [];