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

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 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.4](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.3...v1.0.0-alpha.4) (2026-01-31)
+
+### Features
+
+- **parser:** add unified options interface & retrievalURI meta ([#16](https://github.com/jentic/jentic-arazzo-tools/issues/16)) ([2d6c3b3](https://github.com/jentic/jentic-arazzo-tools/commit/2d6c3b37f3246bc5ad775c30b508607119c9eb50))
+- **resolver:** add dereferencing support for Arazzo Document fragments ([#21](https://github.com/jentic/jentic-arazzo-tools/issues/21)) ([868dc43](https://github.com/jentic/jentic-arazzo-tools/commit/868dc434b51f6247ca102fae7422a85a0e545d09))
+- **resolver:** add dereferencing support for entry Arazzo Document ([#15](https://github.com/jentic/jentic-arazzo-tools/issues/15)) ([cf016ed](https://github.com/jentic/jentic-arazzo-tools/commit/cf016ed9130f08aac87bbb94b0e45e80c27f8fc3))
+
 # [1.0.0-alpha.3](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.2...v1.0.0-alpha.3) (2026-01-29)
 
 ### Features

package/README.md

@@ -80,37 +80,39 @@ const parseResult = await parse('https://example.com/arazzo.yaml');
 
 ## Parse options
 
-The `parse` function accepts an optional second argument with parsing 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):
 
 ```js
 import { parse } from '@jentic/arazzo-parser';
 
 const parseResult = await parse(source, {
-  strict: true,      // Use strict parsing mode (default: true)
-  sourceMap: false,  // Include source maps (default: false)
-  parserOpts: {},    // Additional parser options (default: {})
-  resolverOpts: {},  // Additional resolver options (default: {})
+  parse: {
+    parserOpts: {
+      strict: true,      // Use strict parsing mode (default: true)
+      sourceMap: false,  // Include source maps (default: false)
+    },
+  },
 });
 ```
 
-### Options
-
-| Option | Type | Default | Description                                                                                                                                          |
-|--------|------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `strict` | `boolean` | `true` | Whether to enforce strict parsing mode. Strict mode uses native JSON and YAML parsers without error recovery.                                        |
-| `sourceMap` | `boolean` | `false` | Whether to include [source maps](https://github.com/speclynx/apidom/blob/main/packages/apidom-datamodel/README.md#source-maps) in the parsed result. |
-| `parserOpts` | `Record<string, unknown>` | `{}` | Additional options passed to the underlying parsers.                                                                                                 |
-| `resolverOpts` | `Record<string, unknown>` | `{}` | Additional options passed to the underlying resolvers.                                                                                               |
-
 ### Default options
 
 You can import the default options:
 
 ```js
-import { defaultParseOptions } from '@jentic/arazzo-parser';
-
-console.log(defaultParseOptions);
-// { strict: true, sourceMap: false, parserOpts: {}, resolverOpts: {} }
+import { defaultOptions } from '@jentic/arazzo-parser';
+
+console.log(defaultOptions);
+// {
+//   parse: {
+//     parsers: [...],
+//     parserOpts: {},
+//   },
+//   resolve: {
+//     resolvers: [...],
+//     resolverOpts: {},
+//   },
+// }
 ```
 
 ## Error handling
@@ -147,6 +149,76 @@ const hasErrors = parseResult.errors.length > 0;
 const isEmpty = parseResult.isEmpty;
 ```
 
+### Retrieval URI metadata
+
+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 { toValue } from '@speclynx/apidom-core';
+
+const parseResult = await parse('/path/to/arazzo.json');
+
+// Get the URI from which the document was retrieved
+const uri = toValue(parseResult.meta.get('retrievalURI'));
+// '/path/to/arazzo.json'
+```
+
+Note: `retrievalURI` is not set when parsing from inline content (string) or plain objects.
+
+### Source maps
+
+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:
+
+```js
+import { parse } from '@jentic/arazzo-parser';
+
+const parseResult = await parse('/path/to/arazzo.yaml', {
+  parse: {
+    parserOpts: {
+      sourceMap: true,
+    },
+  },
+});
+```
+
+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';
+
+const parseResult = await parse('/path/to/arazzo.yaml', {
+  parse: { parserOpts: { sourceMap: true } },
+});
+
+const arazzoSpec = parseResult.api;
+
+// Access source map properties directly on the element
+arazzoSpec.startLine;      // 0-based line number where element begins
+arazzoSpec.startCharacter; // 0-based column number where element begins
+arazzoSpec.startOffset;    // 0-based character offset from document start
+arazzoSpec.endLine;        // 0-based line number where element ends
+arazzoSpec.endCharacter;   // 0-based column number where element ends
+arazzoSpec.endOffset;      // 0-based character offset where element ends
+
+// Access source map on nested elements
+const workflow = arazzoSpec.workflows.get(0);
+console.log(`Workflow starts at line ${workflow.startLine}, column ${workflow.startCharacter}`);
+```
+
+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`:
+
+```js
+// This will throw ParseError
+await parse({ arazzo: '1.0.1', ... }, {
+  parse: { parserOpts: { sourceMap: true } },
+});
+```
+
 ## 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.
@@ -157,7 +229,8 @@ The [@speclynx/apidom-core](https://github.com/speclynx/apidom/tree/main/package
 
 ```js
 import { parse } from '@jentic/arazzo-parser';
-import { toValue, toJSON, toYAML, clone, sexprs } from '@speclynx/apidom-core';
+import { cloneDeep, cloneShallow } from '@speclynx/apidom-datamodel';
+import { toValue, toJSON, toYAML, sexprs } from '@speclynx/apidom-core';
 
 const parseResult = await parse(source);
 const arazzoSpec = parseResult.api;
@@ -171,8 +244,9 @@ const json = toJSON(arazzoSpec);
 // Serialize to YAML string
 const yaml = toYAML(arazzoSpec);
 
-// Deep clone the element
-const cloned = clone(arazzoSpec);
+// Clone the element
+const clonedShallow = cloneShallow(arazzoSpec);
+const clonedDeep = cloneDeep(arazzoSpec);
 
 // Get S-expression representation (useful for debugging)
 const sexpr = sexprs(arazzoSpec);