@usearazzo/parser 1.0.1-alpha.0

package/src/parse-criterion-condition.cjs

@@ -0,0 +1,82 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "ArazzoCriterionParseError", {
+  enumerable: true,
+  get: function () {
+    return _arazzoCriterion.ArazzoCriterionParseError;
+  }
+});
+exports.defaultOptions = void 0;
+exports.parse = parse;
+var _arazzoCriterion = require("@swaggerexpert/arazzo-criterion");
+/**
+ * Options for parsing Arazzo "simple" criterion conditions.
+ * @public
+ */
+
+/**
+ * Result of parsing an Arazzo "simple" criterion condition: the foundation
+ * ParseResult bound to the AST node type this parser produces.
+ * @public
+ */
+
+/**
+ * Default options for parsing Arazzo "simple" criterion conditions. Empty on
+ * purpose: the underlying grammar package supplies its own defaults, including
+ * a fresh ASTTranslator per call.
+ * @public
+ */
+const defaultOptions = exports.defaultOptions = {};
+
+/**
+ * Parses an Arazzo "simple" criterion condition (e.g. `$statusCode == 200`,
+ * `$response.body#/status == 'available' && $response.header.X-Rate-Limit-Remaining > 0`)
+ * into its AST.
+ *
+ * A pure, context-free syntax parser: the condition string in, an AST plus
+ * position-carrying diagnostics (`result.matched` / `result.maxMatched`) out.
+ * No evaluation is performed and no context is required; evaluating the
+ * parsed condition against runtime state is the runner's responsibility.
+ * Embedded runtime expression operands are parsed too: each `RuntimeExpression`
+ * node in the resulting AST carries its own sub-AST, produced by
+ * `@swaggerexpert/arazzo-runtime-expression` (see {@link parseRuntimeExpression}).
+ *
+ * @param condition - The "simple" criterion condition source string
+ * @param options - Parse options (uses defaultOptions when not provided)
+ * @returns The parse result: `{ result, tree, stats, trace }`. On success,
+ * `result.success` is `true` and `tree` holds the AST. On failure,
+ * `result.success` is `false`, `tree` is `undefined`, and `result.maxMatched`
+ * gives the offset into `condition` up to which parsing succeeded.
+ * @throws TypeError - When `condition` is not a string.
+ * @throws ArazzoCriterionParseError - When parsing fails for a reason other
+ * than invalid syntax (an unexpected internal error). Invalid syntax is never
+ * thrown; it is reported through the returned `result`.
+ *
+ * @example
+ * Valid condition
+ * ```typescript
+ * import { parseCriterionCondition } from '@usearazzo/parser';
+ *
+ * const { result, tree } = parseCriterionCondition('$statusCode == 200');
+ * // result.success === true
+ * // tree.type === 'BinaryExpression'
+ * ```
+ *
+ * @example
+ * Invalid condition
+ * ```typescript
+ * import { parseCriterionCondition } from '@usearazzo/parser';
+ *
+ * const { result, tree } = parseCriterionCondition('$statusCode ===');
+ * // result.success === false
+ * // tree === undefined
+ * // result.maxMatched - the offset parsing failed at
+ * ```
+ * @public
+ */
+function parse(condition, options = defaultOptions) {
+  return (0, _arazzoCriterion.parse)(condition, options);
+}

package/src/parse-criterion-condition.mjs

@@ -0,0 +1,71 @@
+import { parse as parseCriterionCondition, ArazzoCriterionParseError } from '@swaggerexpert/arazzo-criterion';
+
+/**
+ * Options for parsing Arazzo "simple" criterion conditions.
+ * @public
+ */
+
+/**
+ * Result of parsing an Arazzo "simple" criterion condition: the foundation
+ * ParseResult bound to the AST node type this parser produces.
+ * @public
+ */
+
+/**
+ * Default options for parsing Arazzo "simple" criterion conditions. Empty on
+ * purpose: the underlying grammar package supplies its own defaults, including
+ * a fresh ASTTranslator per call.
+ * @public
+ */
+export const defaultOptions = {};
+
+/**
+ * Parses an Arazzo "simple" criterion condition (e.g. `$statusCode == 200`,
+ * `$response.body#/status == 'available' && $response.header.X-Rate-Limit-Remaining > 0`)
+ * into its AST.
+ *
+ * A pure, context-free syntax parser: the condition string in, an AST plus
+ * position-carrying diagnostics (`result.matched` / `result.maxMatched`) out.
+ * No evaluation is performed and no context is required; evaluating the
+ * parsed condition against runtime state is the runner's responsibility.
+ * Embedded runtime expression operands are parsed too: each `RuntimeExpression`
+ * node in the resulting AST carries its own sub-AST, produced by
+ * `@swaggerexpert/arazzo-runtime-expression` (see {@link parseRuntimeExpression}).
+ *
+ * @param condition - The "simple" criterion condition source string
+ * @param options - Parse options (uses defaultOptions when not provided)
+ * @returns The parse result: `{ result, tree, stats, trace }`. On success,
+ * `result.success` is `true` and `tree` holds the AST. On failure,
+ * `result.success` is `false`, `tree` is `undefined`, and `result.maxMatched`
+ * gives the offset into `condition` up to which parsing succeeded.
+ * @throws TypeError - When `condition` is not a string.
+ * @throws ArazzoCriterionParseError - When parsing fails for a reason other
+ * than invalid syntax (an unexpected internal error). Invalid syntax is never
+ * thrown; it is reported through the returned `result`.
+ *
+ * @example
+ * Valid condition
+ * ```typescript
+ * import { parseCriterionCondition } from '@usearazzo/parser';
+ *
+ * const { result, tree } = parseCriterionCondition('$statusCode == 200');
+ * // result.success === true
+ * // tree.type === 'BinaryExpression'
+ * ```
+ *
+ * @example
+ * Invalid condition
+ * ```typescript
+ * import { parseCriterionCondition } from '@usearazzo/parser';
+ *
+ * const { result, tree } = parseCriterionCondition('$statusCode ===');
+ * // result.success === false
+ * // tree === undefined
+ * // result.maxMatched - the offset parsing failed at
+ * ```
+ * @public
+ */
+export function parse(condition, options = defaultOptions) {
+  return parseCriterionCondition(condition, options);
+}
+export { ArazzoCriterionParseError };

package/src/parse-openapi.cjs

@@ -0,0 +1,210 @@
+"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 _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 _apidomParserAdapterOpenapiJson = require("@speclynx/apidom-parser-adapter-openapi-json-3-1");
+var _apidomParserAdapterOpenapiYaml = require("@speclynx/apidom-parser-adapter-openapi-yaml-3-1");
+var _apidomParserAdapterOpenapiJson2 = require("@speclynx/apidom-parser-adapter-openapi-json-3-0");
+var _apidomParserAdapterOpenapiYaml2 = require("@speclynx/apidom-parser-adapter-openapi-yaml-3-0");
+var _apidomParserAdapterOpenapiJson3 = require("@speclynx/apidom-parser-adapter-openapi-json-2");
+var _apidomParserAdapterOpenapiYaml3 = require("@speclynx/apidom-parser-adapter-openapi-yaml-2");
+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"));
+var _parseArazzo = require("./parse-arazzo.cjs");
+/**
+ * Options for parsing OpenAPI Documents.
+ * @public
+ */
+
+/**
+ * Default reference options for parsing OpenAPI Documents.
+ * @public
+ */
+const defaultOptions = exports.defaultOptions = {
+  parse: {
+    parsers: [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: {
+      ..._parseArazzo.defaultOptions.parse.parserOpts
+    }
+  },
+  resolve: {
+    resolvers: [..._parseArazzo.defaultOptions.resolve.resolvers],
+    resolverOpts: {}
+  }
+};
+
+/**
+ * Parses an OpenAPI Document from an object.
+ * @param source - The OpenAPI Document as a plain object
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the parsed OpenAPI 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 OpenAPI Document from a string or URI.
+ * @param source - The OpenAPI 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 OpenAPI 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 OpenAPI Document from a string, object, or URI.
+ * @param source - The OpenAPI 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 OpenAPI 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 OpenAPI 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 OpenAPI detection to identify and parse inline JSON or YAML content
+ * 3. URI string - if not detected as OpenAPI content, treats as file system path or HTTP(S) URL
+ *
+ * @param source - The OpenAPI 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 OpenAPI 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 parseOpenAPI({ openapi: '3.1.0', info: {...} });
+ * ```
+ *
+ * @example
+ * Parse inline JSON
+ * ```typescript
+ * const result = await parseOpenAPI('{"openapi": "3.1.0", "info": {...}}');
+ * ```
+ *
+ * @example
+ * Parse from file
+ * ```typescript
+ * const result = await parseOpenAPI('/path/to/openapi.json');
+ * ```
+ *
+ * @example
+ * Parse from URL
+ * ```typescript
+ * const result = await parseOpenAPI('https://example.com/openapi.yaml');
+ * ```
+ *
+ * @example
+ * Parse with custom options
+ * ```typescript
+ * const result = await parseOpenAPI('/path/to/openapi.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://openapi.json';
+    sourceProvenance = '[object]';
+  } else if (await (0, _apidomParserAdapterOpenapiJson3.detect)(source, {
+    strict
+  })) {
+    document = source;
+    source = 'memory://openapi.json';
+    sourceProvenance = '[inline JSON]';
+  } else if (await (0, _apidomParserAdapterOpenapiYaml3.detect)(source, {
+    strict
+  })) {
+    document = source;
+    source = 'memory://openapi.yaml';
+    sourceProvenance = '[inline YAML]';
+  } else if (await (0, _apidomParserAdapterOpenapiJson2.detect)(source, {
+    strict
+  })) {
+    document = source;
+    source = 'memory://openapi.json';
+    sourceProvenance = '[inline JSON]';
+  } else if (await (0, _apidomParserAdapterOpenapiYaml2.detect)(source, {
+    strict
+  })) {
+    document = source;
+    source = 'memory://openapi.yaml';
+    sourceProvenance = '[inline YAML]';
+  } else if (await (0, _apidomParserAdapterOpenapiJson.detect)(source, {
+    strict
+  })) {
+    document = source;
+    source = 'memory://openapi.json';
+    sourceProvenance = '[inline JSON]';
+  } else if (await (0, _apidomParserAdapterOpenapiYaml.detect)(source, {
+    strict
+  })) {
+    document = source;
+    source = 'memory://openapi.yaml';
+    sourceProvenance = '[inline YAML]';
+  } else {
+    sourceProvenance = source;
+  }
+
+  // in-memory documents are served under their synthetic memory:// URI, or under the
+  // caller-supplied base URI so that relative references 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);
+    }
+    return parseResult;
+  } catch (error) {
+    throw new _ParseError.default(`Failed to parse OpenAPI Document from "${sourceProvenance}"`, {
+      cause: error
+    });
+  }
+}

package/src/parse-openapi.mjs

@@ -0,0 +1,201 @@
+import { parse as parseURI } from '@speclynx/apidom-reference/configuration/empty';
+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 { detect as detectOpenApiJSON3_1 } from '@speclynx/apidom-parser-adapter-openapi-json-3-1';
+import { detect as detectOpenApiYAML3_1 } from '@speclynx/apidom-parser-adapter-openapi-yaml-3-1';
+import { detect as detectOpenApiJSON3_0 } from '@speclynx/apidom-parser-adapter-openapi-json-3-0';
+import { detect as detectOpenApiYAML3_0 } from '@speclynx/apidom-parser-adapter-openapi-yaml-3-0';
+import { detect as detectOpenApiJSON2 } from '@speclynx/apidom-parser-adapter-openapi-json-2';
+import { detect as detectOpenApiYAML2 } from '@speclynx/apidom-parser-adapter-openapi-yaml-2';
+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";
+import { defaultOptions as arazzoDefaultOptions } from "./parse-arazzo.mjs";
+/**
+ * Options for parsing OpenAPI Documents.
+ * @public
+ */
+/**
+ * Default reference options for parsing OpenAPI Documents.
+ * @public
+ */
+export const defaultOptions = {
+  parse: {
+    parsers: [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: {
+      ...arazzoDefaultOptions.parse.parserOpts
+    }
+  },
+  resolve: {
+    resolvers: [...arazzoDefaultOptions.resolve.resolvers],
+    resolverOpts: {}
+  }
+};
+
+/**
+ * Parses an OpenAPI Document from an object.
+ * @param source - The OpenAPI Document as a plain object
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the parsed OpenAPI 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 OpenAPI Document from a string or URI.
+ * @param source - The OpenAPI 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 OpenAPI 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 OpenAPI Document from a string, object, or URI.
+ * @param source - The OpenAPI 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 OpenAPI 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 OpenAPI 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 OpenAPI detection to identify and parse inline JSON or YAML content
+ * 3. URI string - if not detected as OpenAPI content, treats as file system path or HTTP(S) URL
+ *
+ * @param source - The OpenAPI 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 OpenAPI 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 parseOpenAPI({ openapi: '3.1.0', info: {...} });
+ * ```
+ *
+ * @example
+ * Parse inline JSON
+ * ```typescript
+ * const result = await parseOpenAPI('{"openapi": "3.1.0", "info": {...}}');
+ * ```
+ *
+ * @example
+ * Parse from file
+ * ```typescript
+ * const result = await parseOpenAPI('/path/to/openapi.json');
+ * ```
+ *
+ * @example
+ * Parse from URL
+ * ```typescript
+ * const result = await parseOpenAPI('https://example.com/openapi.yaml');
+ * ```
+ *
+ * @example
+ * Parse with custom options
+ * ```typescript
+ * const result = await parseOpenAPI('/path/to/openapi.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://openapi.json';
+    sourceProvenance = '[object]';
+  } else if (await detectOpenApiJSON2(source, {
+    strict
+  })) {
+    document = source;
+    source = 'memory://openapi.json';
+    sourceProvenance = '[inline JSON]';
+  } else if (await detectOpenApiYAML2(source, {
+    strict
+  })) {
+    document = source;
+    source = 'memory://openapi.yaml';
+    sourceProvenance = '[inline YAML]';
+  } else if (await detectOpenApiJSON3_0(source, {
+    strict
+  })) {
+    document = source;
+    source = 'memory://openapi.json';
+    sourceProvenance = '[inline JSON]';
+  } else if (await detectOpenApiYAML3_0(source, {
+    strict
+  })) {
+    document = source;
+    source = 'memory://openapi.yaml';
+    sourceProvenance = '[inline YAML]';
+  } else if (await detectOpenApiJSON3_1(source, {
+    strict
+  })) {
+    document = source;
+    source = 'memory://openapi.json';
+    sourceProvenance = '[inline JSON]';
+  } else if (await detectOpenApiYAML3_1(source, {
+    strict
+  })) {
+    document = source;
+    source = 'memory://openapi.yaml';
+    sourceProvenance = '[inline YAML]';
+  } else {
+    sourceProvenance = source;
+  }
+
+  // in-memory documents are served under their synthetic memory:// URI, or under the
+  // caller-supplied base URI so that relative references 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);
+    }
+    return parseResult;
+  } catch (error) {
+    throw new ParseError(`Failed to parse OpenAPI Document from "${sourceProvenance}"`, {
+      cause: error
+    });
+  }
+}

package/src/parse-runtime-expression.cjs

@@ -0,0 +1,84 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "ArazzoRuntimeExpressionParseError", {
+  enumerable: true,
+  get: function () {
+    return _arazzoRuntimeExpression.ArazzoRuntimeExpressionParseError;
+  }
+});
+exports.defaultOptions = void 0;
+exports.parse = parse;
+var _arazzoRuntimeExpression = require("@swaggerexpert/arazzo-runtime-expression");
+/**
+ * Options for parsing Arazzo Runtime Expressions.
+ * @public
+ */
+
+/**
+ * Result of parsing an Arazzo Runtime Expression: the foundation ParseResult
+ * bound to the AST node type this parser produces.
+ * @public
+ */
+
+/**
+ * Default options for parsing Arazzo Runtime Expressions. Empty on purpose:
+ * the underlying grammar package supplies its own defaults, including a fresh
+ * ASTTranslator per call.
+ * @public
+ */
+const defaultOptions = exports.defaultOptions = {};
+
+/**
+ * Parses an Arazzo Runtime Expression (e.g. `$inputs.username`,
+ * `$steps.myStep.outputs.result`, `$response.body#/pets/0/id`) into its AST.
+ *
+ * A pure, context-free syntax parser: the expression string in, an AST plus
+ * position-carrying diagnostics (`result.matched` / `result.maxMatched`) out.
+ * No evaluation is performed and no document is required; evaluating the
+ * parsed expression against runtime state is the runner's responsibility.
+ *
+ * The expression must be the bare form without surrounding braces. Splitting a
+ * `{expression}` template into literal and expression spans is left to
+ * `@swaggerexpert/arazzo-runtime-expression`'s own `extract`/`interpolate`
+ * functions, which remain a foundation dependency rather than being wrapped
+ * here.
+ *
+ * @param expression - The runtime expression source string
+ * @param options - Parse options (uses defaultOptions when not provided)
+ * @returns The parse result: `{ result, tree, stats, trace }`. On success,
+ * `result.success` is `true` and `tree` holds the AST. On failure,
+ * `result.success` is `false`, `tree` is `undefined`, and `result.maxMatched`
+ * gives the offset into `expression` up to which parsing succeeded.
+ * @throws TypeError - When `expression` is not a string.
+ * @throws ArazzoRuntimeExpressionParseError - When parsing fails for a reason
+ * other than invalid syntax (an unexpected internal error). Invalid syntax is
+ * never thrown; it is reported through the returned `result`.
+ *
+ * @example
+ * Valid expression
+ * ```typescript
+ * import { parseRuntimeExpression } from '@usearazzo/parser';
+ *
+ * const { result, tree } = parseRuntimeExpression('$steps.myStep.outputs.result');
+ * // result.success === true
+ * // tree === { type: 'StepsExpression', stepId: 'myStep', field: 'outputs', outputName: 'result' }
+ * ```
+ *
+ * @example
+ * Invalid expression
+ * ```typescript
+ * import { parseRuntimeExpression } from '@usearazzo/parser';
+ *
+ * const { result, tree } = parseRuntimeExpression('$unknown.thing');
+ * // result.success === false
+ * // tree === undefined
+ * // result.maxMatched === 0 - the offset parsing failed at
+ * ```
+ * @public
+ */
+function parse(expression, options = defaultOptions) {
+  return (0, _arazzoRuntimeExpression.parse)(expression, options);
+}