@usearazzo/parser 1.0.1-alpha.0

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@usearazzo/parser",
+  "version": "1.0.1-alpha.0",
+  "description": "Parser for the Arazzo Specification language: documents, runtime expressions, and criterion conditions.",
+  "keywords": [
+    "arazzo",
+    "arazzo-specification",
+    "parser",
+    "datamodel",
+    "workflow",
+    "workflows",
+    "runtime-expression",
+    "criterion"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "provenance": false,
+    "tag": "latest"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.10.0"
+  },
+  "unpkg": "./dist/arazzo-parser.browser.min.js",
+  "main": "./src/index.cjs",
+  "exports": {
+    "types": "./types/parser.d.ts",
+    "import": "./src/index.mjs",
+    "require": "./src/index.cjs"
+  },
+  "types": "./types/parser.d.ts",
+  "scripts": {
+    "build": "npm run clean && run-p --max-parallel ${CPU_CORES:-2} typescript:declaration build:es build:cjs build:umd:browser",
+    "build:es": "cross-env BABEL_ENV=es babel src --out-dir src --extensions '.ts' --out-file-extension '.mjs' --root-mode 'upward'",
+    "build:cjs": "cross-env BABEL_ENV=cjs babel src --out-dir src --extensions '.ts' --out-file-extension '.cjs' --root-mode 'upward'",
+    "build:umd:browser": "cross-env BABEL_ENV=browser webpack --config config/webpack/browser.config.js --progress",
+    "lint": "eslint ./",
+    "lint:fix": "eslint ./ --fix",
+    "clean": "rimraf --glob 'src/**/*.mjs' 'src/**/*.cjs' 'test/**/*.mjs' ./dist ./types",
+    "typescript:check-types": "tsc --noEmit",
+    "typescript:declaration": "tsc -p tsconfig.declaration.json && api-extractor run -l -c ./config/api-extractor/api-extractor.json",
+    "test": "npm run build:es && cross-env BABEL_ENV=es babel test --out-dir test --extensions '.ts' --out-file-extension '.mjs' --root-mode 'upward' && cross-env NODE_ENV=test mocha",
+    "prepack": "copyfiles -u 2 ../../LICENSE . && copyfiles -u 2 ../../NOTICE .",
+    "postpack": "rimraf NOTICE LICENSE"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/usearazzo/arazzo-toolkit.git"
+  },
+  "author": "Vladimir Gorej <vladimir.gorej@gmail.com>",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@babel/runtime-corejs3": "^8.0.0",
+    "@speclynx/apidom-datamodel": "^5.2.2",
+    "@speclynx/apidom-error": "^5.2.2",
+    "@speclynx/apidom-ns-arazzo-1": "^5.2.2",
+    "@speclynx/apidom-parser-adapter-arazzo-json-1": "^5.2.2",
+    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "^5.2.2",
+    "@speclynx/apidom-parser-adapter-openapi-json-2": "^5.2.2",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "^5.2.2",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "^5.2.2",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "^5.2.2",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "^5.2.2",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "^5.2.2",
+    "@speclynx/apidom-reference": "^5.2.2",
+    "@swaggerexpert/arazzo-criterion": "^1.0.1",
+    "@swaggerexpert/arazzo-runtime-expression": "^3.2.0",
+    "ramda-adjunct": "^6.0.0",
+    "type-fest": "^5.4.4"
+  },
+  "devDependencies": {
+    "@speclynx/apidom-core": "^5.2.2"
+  },
+  "files": [
+    "src/**/*.mjs",
+    "src/**/*.cjs",
+    "dist/",
+    "types/parser.d.ts",
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "CHANGELOG.md"
+  ]
+}

package/src/errors/ParseError.cjs

@@ -0,0 +1,18 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _apidomError = require("@speclynx/apidom-error");
+/**
+ * Error thrown by `parseArazzo` and `parseOpenAPI` when parsing fails for any
+ * reason. The original error is available via the `cause` property.
+ * @public
+ */
+class ParseError extends _apidomError.ApiDOMError {
+  constructor(message, options) {
+    super(message, options);
+  }
+}
+var _default = exports.default = ParseError;

package/src/errors/ParseError.mjs

@@ -0,0 +1,13 @@
+import { ApiDOMError } from '@speclynx/apidom-error';
+
+/**
+ * Error thrown by `parseArazzo` and `parseOpenAPI` when parsing fails for any
+ * reason. The original error is available via the `cause` property.
+ * @public
+ */
+class ParseError extends ApiDOMError {
+  constructor(message, options) {
+    super(message, options);
+  }
+}
+export default ParseError;

package/src/index.cjs

@@ -0,0 +1,77 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "ArazzoCriterionParseError", {
+  enumerable: true,
+  get: function () {
+    return _parseCriterionCondition.ArazzoCriterionParseError;
+  }
+});
+Object.defineProperty(exports, "ArazzoRuntimeExpressionParseError", {
+  enumerable: true,
+  get: function () {
+    return _parseRuntimeExpression.ArazzoRuntimeExpressionParseError;
+  }
+});
+Object.defineProperty(exports, "ParseError", {
+  enumerable: true,
+  get: function () {
+    return _ParseError.default;
+  }
+});
+Object.defineProperty(exports, "defaultParseArazzoOptions", {
+  enumerable: true,
+  get: function () {
+    return _parseArazzo.defaultOptions;
+  }
+});
+Object.defineProperty(exports, "defaultParseCriterionConditionOptions", {
+  enumerable: true,
+  get: function () {
+    return _parseCriterionCondition.defaultOptions;
+  }
+});
+Object.defineProperty(exports, "defaultParseOpenAPIOptions", {
+  enumerable: true,
+  get: function () {
+    return _parseOpenapi.defaultOptions;
+  }
+});
+Object.defineProperty(exports, "defaultParseRuntimeExpressionOptions", {
+  enumerable: true,
+  get: function () {
+    return _parseRuntimeExpression.defaultOptions;
+  }
+});
+Object.defineProperty(exports, "parseArazzo", {
+  enumerable: true,
+  get: function () {
+    return _parseArazzo.parse;
+  }
+});
+Object.defineProperty(exports, "parseCriterionCondition", {
+  enumerable: true,
+  get: function () {
+    return _parseCriterionCondition.parse;
+  }
+});
+Object.defineProperty(exports, "parseOpenAPI", {
+  enumerable: true,
+  get: function () {
+    return _parseOpenapi.parse;
+  }
+});
+Object.defineProperty(exports, "parseRuntimeExpression", {
+  enumerable: true,
+  get: function () {
+    return _parseRuntimeExpression.parse;
+  }
+});
+var _ParseError = _interopRequireDefault(require("./errors/ParseError.cjs"));
+var _parseArazzo = require("./parse-arazzo.cjs");
+var _parseOpenapi = require("./parse-openapi.cjs");
+var _parseRuntimeExpression = require("./parse-runtime-expression.cjs");
+var _parseCriterionCondition = require("./parse-criterion-condition.cjs");

package/src/index.mjs

@@ -0,0 +1,5 @@
+export { default as ParseError } from "./errors/ParseError.mjs";
+export { parse as parseArazzo, defaultOptions as defaultParseArazzoOptions } from "./parse-arazzo.mjs";
+export { parse as parseOpenAPI, defaultOptions as defaultParseOpenAPIOptions } from "./parse-openapi.mjs";
+export { parse as parseRuntimeExpression, defaultOptions as defaultParseRuntimeExpressionOptions, ArazzoRuntimeExpressionParseError } from "./parse-runtime-expression.mjs";
+export { parse as parseCriterionCondition, defaultOptions as defaultParseCriterionConditionOptions, ArazzoCriterionParseError } from "./parse-criterion-condition.mjs";

package/src/options/util.cjs

@@ -0,0 +1,30 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.mergeOptions = void 0;
+var _empty = require("@speclynx/apidom-reference/configuration/empty");
+const isMemoryResolver = resolver => resolver.name === 'memory';
+
+/**
+ * Merges reference options the same way apidom-reference does, additionally keeping
+ * memory resolvers ahead of every other resolver: they serve in-memory documents and
+ * must win over any resolver that could read the same URI from disk or network.
+ */
+const mergeOptions = (target, source) => {
+  const merged = (0, _empty.mergeOptions)(target, source);
+  const {
+    resolvers
+  } = merged.resolve;
+  const memoryResolvers = resolvers.filter(isMemoryResolver);
+  if (memoryResolvers.length === 0) return merged;
+  return {
+    ...merged,
+    resolve: {
+      ...merged.resolve,
+      resolvers: [...memoryResolvers, ...resolvers.filter(r => !isMemoryResolver(r))]
+    }
+  };
+};
+exports.mergeOptions = mergeOptions;

package/src/options/util.mjs

@@ -0,0 +1,23 @@
+import { mergeOptions as mergeReferenceOptions } from '@speclynx/apidom-reference/configuration/empty';
+const isMemoryResolver = resolver => resolver.name === 'memory';
+
+/**
+ * Merges reference options the same way apidom-reference does, additionally keeping
+ * memory resolvers ahead of every other resolver: they serve in-memory documents and
+ * must win over any resolver that could read the same URI from disk or network.
+ */
+export const mergeOptions = (target, source) => {
+  const merged = mergeReferenceOptions(target, source);
+  const {
+    resolvers
+  } = merged.resolve;
+  const memoryResolvers = resolvers.filter(isMemoryResolver);
+  if (memoryResolvers.length === 0) return merged;
+  return {
+    ...merged,
+    resolve: {
+      ...merged.resolve,
+      resolvers: [...memoryResolvers, ...resolvers.filter(r => !isMemoryResolver(r))]
+    }
+  };
+};

package/src/parse-arazzo.cjs

@@ -0,0 +1,209 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.defaultOptions = void 0;
+exports.parse = parse;
+var _empty = require("@speclynx/apidom-reference/configuration/empty");
+var _arazzoJson = _interopRequireDefault(require("@speclynx/apidom-reference/parse/parsers/arazzo-json-1"));
+var _arazzoYaml = _interopRequireDefault(require("@speclynx/apidom-reference/parse/parsers/arazzo-yaml-1"));
+var _openapiJson = _interopRequireDefault(require("@speclynx/apidom-reference/parse/parsers/openapi-json-2"));
+var _openapiYaml = _interopRequireDefault(require("@speclynx/apidom-reference/parse/parsers/openapi-yaml-2"));
+var _openapiJson2 = _interopRequireDefault(require("@speclynx/apidom-reference/parse/parsers/openapi-json-3-0"));
+var _openapiYaml2 = _interopRequireDefault(require("@speclynx/apidom-reference/parse/parsers/openapi-yaml-3-0"));
+var _openapiJson3 = _interopRequireDefault(require("@speclynx/apidom-reference/parse/parsers/openapi-json-3-1"));
+var _openapiYaml3 = _interopRequireDefault(require("@speclynx/apidom-reference/parse/parsers/openapi-yaml-3-1"));
+var _file = _interopRequireDefault(require("@speclynx/apidom-reference/resolve/resolvers/file"));
+var _httpAxios = _interopRequireDefault(require("@speclynx/apidom-reference/resolve/resolvers/http-axios"));
+var _apidomParserAdapterArazzoJson = require("@speclynx/apidom-parser-adapter-arazzo-json-1");
+var _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
+var _apidomParserAdapterArazzoYaml = require("@speclynx/apidom-parser-adapter-arazzo-yaml-1");
+var _ramdaAdjunct = require("ramda-adjunct");
+var _ParseError = _interopRequireDefault(require("./errors/ParseError.cjs"));
+var _util = require("./options/util.cjs");
+var _index = _interopRequireDefault(require("./resolve/resolvers/memory/index.cjs"));
+/**
+ * Options for parsing Arazzo Documents.
+ * @public
+ */
+
+/**
+ * Default reference options for parsing Arazzo Documents.
+ * @public
+ */
+const defaultOptions = exports.defaultOptions = {
+  parse: {
+    parsers: [new _arazzoJson.default({
+      allowEmpty: false
+    }), new _arazzoYaml.default({
+      allowEmpty: false
+    }), new _openapiJson.default({
+      allowEmpty: false
+    }), new _openapiYaml.default({
+      allowEmpty: false
+    }), new _openapiJson2.default({
+      allowEmpty: false
+    }), new _openapiYaml2.default({
+      allowEmpty: false
+    }), new _openapiJson3.default({
+      allowEmpty: false
+    }), new _openapiYaml3.default({
+      allowEmpty: false
+    })],
+    parserOpts: {
+      sourceMap: false,
+      style: false,
+      strict: true,
+      sourceDescriptions: false
+    }
+  },
+  resolve: {
+    resolvers: [
+    // regex patterns, not glob strings - picomatch's glob matching never
+    // matches a dotfile basename (e.g. .arazzo.yaml) without `dot: true`,
+    // which FileResolver does not set.
+    new _file.default({
+      fileAllowList: [/\.json$/i, /\.ya?ml$/i]
+    }), new _httpAxios.default({
+      timeout: 15000,
+      redirects: 5,
+      withCredentials: false
+    })],
+    resolverOpts: {}
+  }
+};
+
+/**
+ * Parses an Arazzo Document from an object.
+ * @param source - The Arazzo Document as a plain object
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the parsed Arazzo Document as ApiDOM data model
+ * @throws ParseError - When parsing fails for any reason. The original error is available via the `cause` property.
+ * @public
+ */
+
+/**
+ * Parses an Arazzo Document from a string or URI.
+ * @param source - The Arazzo Document as string content, or a file system path / HTTP(S) URL
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the parsed Arazzo Document as ApiDOM data model
+ * @throws ParseError - When parsing fails for any reason. The original error is available via the `cause` property.
+ * @public
+ */
+
+/**
+ * Parses an Arazzo Document from a string, object, or URI.
+ * @param source - The Arazzo Document as a plain object, string content, or URI
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the parsed Arazzo Document as ApiDOM data model
+ * @throws ParseError - When parsing fails for any reason. The original error is available via the `cause` property.
+ * @public
+ */
+
+/**
+ * Parses an Arazzo Document from a string, object, or URI.
+ *
+ * The function handles three types of input:
+ * 1. Object - converts to JSON string and parses (source maps supported with `strict: false`)
+ * 2. String content - uses Arazzo detection to identify and parse inline JSON or YAML content
+ * 3. URI string - if not detected as Arazzo content, treats as file system path or HTTP(S) URL
+ *
+ * @param source - The Arazzo Document as an object, string content, or a file system path / HTTP(S) URL
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the parsed Arazzo Document as ApiDOM data model
+ * @throws ParseError - When parsing fails for any reason. The original error is available via the `cause` property.
+ *
+ * @example
+ * Parse from object
+ * ```typescript
+ * const result = await parseArazzo({ arazzo: '1.0.1', info: {...} });
+ * ```
+ *
+ * @example
+ * Parse inline JSON
+ * ```typescript
+ * const result = await parseArazzo('{"arazzo": "1.0.1", "info": {...}}');
+ * ```
+ *
+ * @example
+ * Parse from file
+ * ```typescript
+ * const result = await parseArazzo('/path/to/arazzo.json');
+ * ```
+ *
+ * @example
+ * Parse from URL
+ * ```typescript
+ * const result = await parseArazzo('https://example.com/arazzo.yaml');
+ * ```
+ *
+ * @example
+ * Parse with custom options
+ * ```typescript
+ * const result = await parseArazzo('/path/to/arazzo.json', customOptions);
+ * ```
+ * @public
+ */
+async function parse(source, options = {}) {
+  let mergedOptions = (0, _util.mergeOptions)(defaultOptions, options);
+  const strict = mergedOptions.parse?.parserOpts?.strict ?? true;
+  let sourceProvenance;
+  let document;
+  if ((0, _ramdaAdjunct.isPlainObject)(source)) {
+    document = JSON.stringify(source, null, 2);
+    source = 'memory://arazzo.json';
+    sourceProvenance = '[object]';
+  } else if (await (0, _apidomParserAdapterArazzoJson.detect)(source, {
+    strict
+  })) {
+    document = source;
+    source = 'memory://arazzo.json';
+    sourceProvenance = '[inline JSON]';
+  } else if (await (0, _apidomParserAdapterArazzoYaml.detect)(source, {
+    strict
+  })) {
+    document = source;
+    source = 'memory://arazzo.yaml';
+    sourceProvenance = '[inline YAML]';
+  } else {
+    sourceProvenance = _empty.url.isHttpUrl(source) || _empty.url.getProtocol(source) === 'file' || _empty.url.isURI(`file://${source}`) ? source : '[inline CONTENT]';
+  }
+
+  // in-memory documents are served under their synthetic memory:// URI, or under the
+  // caller-supplied base URI so that relative source description URLs resolve against
+  // a real location
+  if (document !== undefined) {
+    // raw options, not merged: mergeOptions defaults baseURI to the current working directory
+    source = options.resolve?.baseURI || source;
+    mergedOptions = (0, _util.mergeOptions)(mergedOptions, {
+      resolve: {
+        resolvers: [...mergedOptions.resolve.resolvers, new _index.default({
+          document,
+          uri: source
+        })]
+      }
+    });
+  }
+
+  // next we assume that source is either file system URI or HTTP(S) URL
+  try {
+    const parseResult = await (0, _empty.parse)(source, mergedOptions);
+
+    // set retrievalURI metadata for file/URL sources (not for inline content)
+    if (!source.startsWith('memory://')) {
+      parseResult.meta.set('retrievalURI', source);
+    }
+
+    // validate that the parsed document is an Arazzo specification
+    if (!(0, _apidomNsArazzo.isArazzoSpecification1Element)(parseResult.api)) {
+      throw new _empty.UnmatchedParserError(`Could not find a parser that can parse "${sourceProvenance}" as an Arazzo specification`);
+    }
+    return parseResult;
+  } catch (error) {
+    throw new _ParseError.default(`Failed to parse Arazzo Document from "${sourceProvenance}"`, {
+      cause: error
+    });
+  }
+}

package/src/parse-arazzo.mjs

@@ -0,0 +1,200 @@
+import { url, parse as parseURI, UnmatchedParserError } from '@speclynx/apidom-reference/configuration/empty';
+import ArazzoJSON1Parser from '@speclynx/apidom-reference/parse/parsers/arazzo-json-1';
+import ArazzoYAML1Parser from '@speclynx/apidom-reference/parse/parsers/arazzo-yaml-1';
+import OpenApiJSON2Parser from '@speclynx/apidom-reference/parse/parsers/openapi-json-2';
+import OpenApiYAML2Parser from '@speclynx/apidom-reference/parse/parsers/openapi-yaml-2';
+import OpenApiJSON3_0Parser from '@speclynx/apidom-reference/parse/parsers/openapi-json-3-0';
+import OpenApiYAML3_0Parser from '@speclynx/apidom-reference/parse/parsers/openapi-yaml-3-0';
+import OpenApiJSON3_1Parser from '@speclynx/apidom-reference/parse/parsers/openapi-json-3-1';
+import OpenApiYAML3_1Parser from '@speclynx/apidom-reference/parse/parsers/openapi-yaml-3-1';
+import FileResolver from '@speclynx/apidom-reference/resolve/resolvers/file';
+import HTTPResolverAxios from '@speclynx/apidom-reference/resolve/resolvers/http-axios';
+import { detect as detectArazzoJSON } from '@speclynx/apidom-parser-adapter-arazzo-json-1';
+import { isArazzoSpecification1Element } from '@speclynx/apidom-ns-arazzo-1';
+import { detect as detectArazzoYAML } from '@speclynx/apidom-parser-adapter-arazzo-yaml-1';
+import { isPlainObject } from 'ramda-adjunct';
+import ParseError from "./errors/ParseError.mjs";
+import { mergeOptions } from "./options/util.mjs";
+import MemoryResolver from "./resolve/resolvers/memory/index.mjs";
+/**
+ * Options for parsing Arazzo Documents.
+ * @public
+ */
+/**
+ * Default reference options for parsing Arazzo Documents.
+ * @public
+ */
+export const defaultOptions = {
+  parse: {
+    parsers: [new ArazzoJSON1Parser({
+      allowEmpty: false
+    }), new ArazzoYAML1Parser({
+      allowEmpty: false
+    }), new OpenApiJSON2Parser({
+      allowEmpty: false
+    }), new OpenApiYAML2Parser({
+      allowEmpty: false
+    }), new OpenApiJSON3_0Parser({
+      allowEmpty: false
+    }), new OpenApiYAML3_0Parser({
+      allowEmpty: false
+    }), new OpenApiJSON3_1Parser({
+      allowEmpty: false
+    }), new OpenApiYAML3_1Parser({
+      allowEmpty: false
+    })],
+    parserOpts: {
+      sourceMap: false,
+      style: false,
+      strict: true,
+      sourceDescriptions: false
+    }
+  },
+  resolve: {
+    resolvers: [
+    // regex patterns, not glob strings - picomatch's glob matching never
+    // matches a dotfile basename (e.g. .arazzo.yaml) without `dot: true`,
+    // which FileResolver does not set.
+    new FileResolver({
+      fileAllowList: [/\.json$/i, /\.ya?ml$/i]
+    }), new HTTPResolverAxios({
+      timeout: 15000,
+      redirects: 5,
+      withCredentials: false
+    })],
+    resolverOpts: {}
+  }
+};
+
+/**
+ * Parses an Arazzo Document from an object.
+ * @param source - The Arazzo Document as a plain object
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the parsed Arazzo Document as ApiDOM data model
+ * @throws ParseError - When parsing fails for any reason. The original error is available via the `cause` property.
+ * @public
+ */
+
+/**
+ * Parses an Arazzo Document from a string or URI.
+ * @param source - The Arazzo Document as string content, or a file system path / HTTP(S) URL
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the parsed Arazzo Document as ApiDOM data model
+ * @throws ParseError - When parsing fails for any reason. The original error is available via the `cause` property.
+ * @public
+ */
+
+/**
+ * Parses an Arazzo Document from a string, object, or URI.
+ * @param source - The Arazzo Document as a plain object, string content, or URI
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the parsed Arazzo Document as ApiDOM data model
+ * @throws ParseError - When parsing fails for any reason. The original error is available via the `cause` property.
+ * @public
+ */
+
+/**
+ * Parses an Arazzo Document from a string, object, or URI.
+ *
+ * The function handles three types of input:
+ * 1. Object - converts to JSON string and parses (source maps supported with `strict: false`)
+ * 2. String content - uses Arazzo detection to identify and parse inline JSON or YAML content
+ * 3. URI string - if not detected as Arazzo content, treats as file system path or HTTP(S) URL
+ *
+ * @param source - The Arazzo Document as an object, string content, or a file system path / HTTP(S) URL
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the parsed Arazzo Document as ApiDOM data model
+ * @throws ParseError - When parsing fails for any reason. The original error is available via the `cause` property.
+ *
+ * @example
+ * Parse from object
+ * ```typescript
+ * const result = await parseArazzo({ arazzo: '1.0.1', info: {...} });
+ * ```
+ *
+ * @example
+ * Parse inline JSON
+ * ```typescript
+ * const result = await parseArazzo('{"arazzo": "1.0.1", "info": {...}}');
+ * ```
+ *
+ * @example
+ * Parse from file
+ * ```typescript
+ * const result = await parseArazzo('/path/to/arazzo.json');
+ * ```
+ *
+ * @example
+ * Parse from URL
+ * ```typescript
+ * const result = await parseArazzo('https://example.com/arazzo.yaml');
+ * ```
+ *
+ * @example
+ * Parse with custom options
+ * ```typescript
+ * const result = await parseArazzo('/path/to/arazzo.json', customOptions);
+ * ```
+ * @public
+ */
+export async function parse(source, options = {}) {
+  let mergedOptions = mergeOptions(defaultOptions, options);
+  const strict = mergedOptions.parse?.parserOpts?.strict ?? true;
+  let sourceProvenance;
+  let document;
+  if (isPlainObject(source)) {
+    document = JSON.stringify(source, null, 2);
+    source = 'memory://arazzo.json';
+    sourceProvenance = '[object]';
+  } else if (await detectArazzoJSON(source, {
+    strict
+  })) {
+    document = source;
+    source = 'memory://arazzo.json';
+    sourceProvenance = '[inline JSON]';
+  } else if (await detectArazzoYAML(source, {
+    strict
+  })) {
+    document = source;
+    source = 'memory://arazzo.yaml';
+    sourceProvenance = '[inline YAML]';
+  } else {
+    sourceProvenance = url.isHttpUrl(source) || url.getProtocol(source) === 'file' || url.isURI(`file://${source}`) ? source : '[inline CONTENT]';
+  }
+
+  // in-memory documents are served under their synthetic memory:// URI, or under the
+  // caller-supplied base URI so that relative source description URLs resolve against
+  // a real location
+  if (document !== undefined) {
+    // raw options, not merged: mergeOptions defaults baseURI to the current working directory
+    source = options.resolve?.baseURI || source;
+    mergedOptions = mergeOptions(mergedOptions, {
+      resolve: {
+        resolvers: [...mergedOptions.resolve.resolvers, new MemoryResolver({
+          document,
+          uri: source
+        })]
+      }
+    });
+  }
+
+  // next we assume that source is either file system URI or HTTP(S) URL
+  try {
+    const parseResult = await parseURI(source, mergedOptions);
+
+    // set retrievalURI metadata for file/URL sources (not for inline content)
+    if (!source.startsWith('memory://')) {
+      parseResult.meta.set('retrievalURI', source);
+    }
+
+    // validate that the parsed document is an Arazzo specification
+    if (!isArazzoSpecification1Element(parseResult.api)) {
+      throw new UnmatchedParserError(`Could not find a parser that can parse "${sourceProvenance}" as an Arazzo specification`);
+    }
+    return parseResult;
+  } catch (error) {
+    throw new ParseError(`Failed to parse Arazzo Document from "${sourceProvenance}"`, {
+      cause: error
+    });
+  }
+}