@usearazzo/runner 0.0.0-stage → 1.0.1-alpha.11

package/src/criterion/SimpleCriterionEvaluator.mjs

@@ -0,0 +1,43 @@
+import { evaluate as evaluateSimpleCriterion, ArazzoCriterionError } from '@swaggerexpert/arazzo-criterion';
+import CriterionError from "../errors/CriterionError.mjs";
+/**
+ * Evaluates a `simple` Arazzo criterion condition.
+ *
+ * A simple condition embeds runtime expressions directly in the condition
+ * (e.g. `$statusCode == 200 && $response.body.status == 'available'`), so —
+ * unlike `regex`/`jsonpath`/`xpath` — it has no separate `context`. Parsing,
+ * loose/case-insensitive comparison, and member/index navigation are delegated
+ * to `@swaggerexpert/arazzo-criterion`; each embedded runtime expression is
+ * resolved through the supplied resolver.
+ *
+ * An operand that resolves to `undefined` (a lenient miss) does not throw; it is
+ * compared per the library's rules (e.g. `undefined == x` and relational
+ * comparisons are false, matching the spec's "null equals only null"), so a
+ * negated or disjunctive condition may still pass. A malformed condition throws
+ * {@link CriterionError}.
+ * @public
+ */
+class SimpleCriterionEvaluator {
+  /**
+   * Evaluates the simple `condition`, resolving each embedded runtime
+   * expression via `resolve`.
+   */
+  evaluate(condition, resolve) {
+    try {
+      return evaluateSimpleCriterion(condition, {
+        resolve
+      });
+    } catch (error) {
+      if (error instanceof ArazzoCriterionError) {
+        throw new CriterionError(`Invalid simple criterion condition "${condition}"`, {
+          cause: error,
+          condition,
+          type: 'simple',
+          reason: 'invalid-simple'
+        });
+      }
+      throw error;
+    }
+  }
+}
+export default SimpleCriterionEvaluator;

package/src/criterion/XPathCriterionEvaluator.cjs

@@ -0,0 +1,117 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _fontoxpath = _interopRequireDefault(require("fontoxpath"));
+var _xmldom = require("@xmldom/xmldom");
+var _CriterionError = _interopRequireDefault(require("../errors/CriterionError.cjs"));
+// fontoxpath is CommonJS and its named exports are not statically resolvable
+// under ESM, so import the default and destructure.
+
+const {
+  evaluateXPathToBoolean,
+  evaluateXPath
+} = _fontoxpath.default;
+
+/**
+ * Evaluates an `xpath` Arazzo criterion condition against a resolved context value.
+ *
+ * The condition is an XPath 3.1 query applied to the resolved `context`, which
+ * must be XML. A string context is parsed as XML; an already-parsed DOM node is
+ * used as-is. The criterion is met by the query's Effective Boolean Value
+ * (XPath 3.1 §19.1.2), as the Arazzo specification mandates — so a boolean
+ * predicate (`//status = 'ok'`), a non-empty node set, a non-zero number, and a
+ * non-empty string all evaluate to `true`.
+ *
+ * Only XPath 3.1 is supported (`fontoxpath`'s engine); version gating happens in
+ * the facade. Per Arazzo 1.1.0, a `null` or `undefined` context fails the
+ * condition. An invalid query throws {@link CriterionError}.
+ * @public
+ */
+class XPathCriterionEvaluator {
+  /**
+   * Evaluates the XPath `condition` against the resolved context value, returning
+   * its Effective Boolean Value.
+   *
+   * Returns `false` when the context is `null` or `undefined`. Throws
+   * {@link CriterionError} when the context is not XML or the query is invalid.
+   */
+  evaluate(condition, context) {
+    if (context === null || context === undefined) return false;
+    const node = this.#toNode(condition, context);
+    try {
+      return evaluateXPathToBoolean(condition, node, null, null, {
+        language: evaluateXPath.XPATH_3_1_LANGUAGE
+      });
+    } catch (error) {
+      throw new _CriterionError.default(`Invalid xpath criterion condition "${condition}"`, {
+        cause: error,
+        condition,
+        type: 'xpath',
+        reason: 'invalid-xpath'
+      });
+    }
+  }
+
+  /**
+   * Coerces the resolved context to an XML DOM node: an already-parsed node is
+   * used as-is, a string is parsed as XML. Any other value cannot be an XPath
+   * context and throws.
+   */
+  #toNode(condition, context) {
+    if (this.#isNode(context)) return context;
+    if (typeof context !== 'string') {
+      throw new _CriterionError.default('xpath criterion context is not XML', {
+        condition,
+        type: 'xpath',
+        reason: 'invalid-context'
+      });
+    }
+
+    // capture parse errors via `onError` rather than the default handler: this
+    // both suppresses the parser writing to the console and catches *recoverable*
+    // errors (e.g. an undefined entity, stray text) that do not throw but would
+    // otherwise yield a degraded document evaluated silently.
+    let parseError;
+    try {
+      const document = new _xmldom.DOMParser({
+        onError: (_level, message) => {
+          parseError ??= message;
+        }
+      }).parseFromString(context, 'text/xml');
+      if (parseError !== undefined) {
+        throw new _CriterionError.default('xpath criterion context is not valid XML', {
+          cause: parseError,
+          condition,
+          type: 'xpath',
+          reason: 'invalid-context'
+        });
+      }
+      return document;
+    } catch (error) {
+      if (error instanceof _CriterionError.default) throw error;
+      throw new _CriterionError.default('xpath criterion context is not valid XML', {
+        cause: error,
+        condition,
+        type: 'xpath',
+        reason: 'invalid-context'
+      });
+    }
+  }
+
+  /**
+   * Duck-types a DOM node, so a caller may pass an already-parsed document
+   * instead of an XML string. Requires both a numeric `nodeType` and a string
+   * `nodeName` so a plain JSON value that happens to carry a `nodeType` property
+   * is not mistaken for a node (and is instead rejected as a non-XML context).
+   */
+  #isNode(value) {
+    if (typeof value !== 'object' || value === null) return false;
+    const node = value;
+    return typeof node.nodeType === 'number' && typeof node.nodeName === 'string';
+  }
+}
+var _default = exports.default = XPathCriterionEvaluator;

package/src/criterion/XPathCriterionEvaluator.mjs

@@ -0,0 +1,109 @@
+// fontoxpath is CommonJS and its named exports are not statically resolvable
+// under ESM, so import the default and destructure.
+import fontoxpath from 'fontoxpath';
+import { DOMParser } from '@xmldom/xmldom';
+import CriterionError from "../errors/CriterionError.mjs";
+const {
+  evaluateXPathToBoolean,
+  evaluateXPath
+} = fontoxpath;
+
+/**
+ * Evaluates an `xpath` Arazzo criterion condition against a resolved context value.
+ *
+ * The condition is an XPath 3.1 query applied to the resolved `context`, which
+ * must be XML. A string context is parsed as XML; an already-parsed DOM node is
+ * used as-is. The criterion is met by the query's Effective Boolean Value
+ * (XPath 3.1 §19.1.2), as the Arazzo specification mandates — so a boolean
+ * predicate (`//status = 'ok'`), a non-empty node set, a non-zero number, and a
+ * non-empty string all evaluate to `true`.
+ *
+ * Only XPath 3.1 is supported (`fontoxpath`'s engine); version gating happens in
+ * the facade. Per Arazzo 1.1.0, a `null` or `undefined` context fails the
+ * condition. An invalid query throws {@link CriterionError}.
+ * @public
+ */
+class XPathCriterionEvaluator {
+  /**
+   * Evaluates the XPath `condition` against the resolved context value, returning
+   * its Effective Boolean Value.
+   *
+   * Returns `false` when the context is `null` or `undefined`. Throws
+   * {@link CriterionError} when the context is not XML or the query is invalid.
+   */
+  evaluate(condition, context) {
+    if (context === null || context === undefined) return false;
+    const node = this.#toNode(condition, context);
+    try {
+      return evaluateXPathToBoolean(condition, node, null, null, {
+        language: evaluateXPath.XPATH_3_1_LANGUAGE
+      });
+    } catch (error) {
+      throw new CriterionError(`Invalid xpath criterion condition "${condition}"`, {
+        cause: error,
+        condition,
+        type: 'xpath',
+        reason: 'invalid-xpath'
+      });
+    }
+  }
+
+  /**
+   * Coerces the resolved context to an XML DOM node: an already-parsed node is
+   * used as-is, a string is parsed as XML. Any other value cannot be an XPath
+   * context and throws.
+   */
+  #toNode(condition, context) {
+    if (this.#isNode(context)) return context;
+    if (typeof context !== 'string') {
+      throw new CriterionError('xpath criterion context is not XML', {
+        condition,
+        type: 'xpath',
+        reason: 'invalid-context'
+      });
+    }
+
+    // capture parse errors via `onError` rather than the default handler: this
+    // both suppresses the parser writing to the console and catches *recoverable*
+    // errors (e.g. an undefined entity, stray text) that do not throw but would
+    // otherwise yield a degraded document evaluated silently.
+    let parseError;
+    try {
+      const document = new DOMParser({
+        onError: (_level, message) => {
+          parseError ??= message;
+        }
+      }).parseFromString(context, 'text/xml');
+      if (parseError !== undefined) {
+        throw new CriterionError('xpath criterion context is not valid XML', {
+          cause: parseError,
+          condition,
+          type: 'xpath',
+          reason: 'invalid-context'
+        });
+      }
+      return document;
+    } catch (error) {
+      if (error instanceof CriterionError) throw error;
+      throw new CriterionError('xpath criterion context is not valid XML', {
+        cause: error,
+        condition,
+        type: 'xpath',
+        reason: 'invalid-context'
+      });
+    }
+  }
+
+  /**
+   * Duck-types a DOM node, so a caller may pass an already-parsed document
+   * instead of an XML string. Requires both a numeric `nodeType` and a string
+   * `nodeName` so a plain JSON value that happens to carry a `nodeType` property
+   * is not mistaken for a node (and is instead rejected as a non-XML context).
+   */
+  #isNode(value) {
+    if (typeof value !== 'object' || value === null) return false;
+    const node = value;
+    return typeof node.nodeType === 'number' && typeof node.nodeName === 'string';
+  }
+}
+export default XPathCriterionEvaluator;

package/src/document/APIDocument.cjs

@@ -0,0 +1,35 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _apidomCore = require("@speclynx/apidom-core");
+/**
+ * Base document held by the document registry.
+ * @public
+ */
+class APIDocument {
+  uri;
+  parseResult;
+  constructor(uri, parseResult) {
+    this.uri = uri;
+    this.parseResult = parseResult;
+  }
+
+  /**
+   * Returns a JSON-serializable representation of the document's API element.
+   * Compatible with JSON.stringify() — JSON.stringify(doc) produces correct output.
+   */
+  toJSON() {
+    return (0, _apidomCore.toValue)(this.parseResult.api);
+  }
+
+  /**
+   * Serializes the document's API element to a YAML string.
+   */
+  toYAML(...args) {
+    return (0, _apidomCore.toYAML)(this.parseResult.api, ...args);
+  }
+}
+var _default = exports.default = APIDocument;

package/src/document/APIDocument.mjs

@@ -0,0 +1,30 @@
+import { toValue, toYAML } from '@speclynx/apidom-core';
+
+/**
+ * Base document held by the document registry.
+ * @public
+ */
+class APIDocument {
+  uri;
+  parseResult;
+  constructor(uri, parseResult) {
+    this.uri = uri;
+    this.parseResult = parseResult;
+  }
+
+  /**
+   * Returns a JSON-serializable representation of the document's API element.
+   * Compatible with JSON.stringify() — JSON.stringify(doc) produces correct output.
+   */
+  toJSON() {
+    return toValue(this.parseResult.api);
+  }
+
+  /**
+   * Serializes the document's API element to a YAML string.
+   */
+  toYAML(...args) {
+    return toYAML(this.parseResult.api, ...args);
+  }
+}
+export default APIDocument;

package/src/document/ArazzoDocument.cjs

@@ -0,0 +1,81 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _apidomCore = require("@speclynx/apidom-core");
+var _APIDocument = _interopRequireDefault(require("./APIDocument.cjs"));
+/**
+ * An Arazzo document held by the document registry: the parse result together
+ * with the indexes the provider built over it — a container, not a logic
+ * bearer. The methods below are thin reads of the source description index.
+ * @public
+ */
+class ArazzoDocument extends _APIDocument.default {
+  type = 'arazzo';
+  isEntry;
+  /**
+   * WorkflowId → JSON Pointer to the workflow within the parse result.
+   */
+  workflowIndex;
+  /**
+   * WorkflowId → stepId → JSON Pointer to the step within the parse result.
+   * Built by the provider, like {@link ArazzoDocument.workflowIndex}.
+   */
+  stepIndex;
+  /**
+   * Name → source description element and canonical URI (already resolved
+   * against this document's base URI). Built by the provider, like
+   * {@link ArazzoDocument.workflowIndex}.
+   */
+  sourceDescriptionIndex;
+  constructor(uri, parseResult, workflowIndex, stepIndex, sourceDescriptionIndex, isEntry = false) {
+    super(uri, parseResult);
+    this.isEntry = isEntry;
+    this.workflowIndex = workflowIndex;
+    this.stepIndex = stepIndex;
+    this.sourceDescriptionIndex = sourceDescriptionIndex;
+  }
+
+  /**
+   * Type guard for ArazzoDocument.
+   */
+  static is(doc) {
+    return doc.type === 'arazzo';
+  }
+
+  /**
+   * Resolves a source description name to its canonical URI — precomputed by
+   * the provider, resolved against this document's base URI.
+   */
+  resolveSourceDescriptionURI(sourceDescriptionName) {
+    return this.sourceDescriptionIndex.get(sourceDescriptionName)?.uri;
+  }
+
+  /**
+   * Resolves a field of a source description object (e.g. `url`, `type`).
+   *
+   * The `url` field resolves to the canonical URI (resolved against this
+   * document's base URI, as `resolveSourceDescriptionURI` does); every other
+   * field resolves to its literal value. Returns `undefined` when the source
+   * description or the field is absent.
+   */
+  resolveSourceDescriptionField(sourceDescriptionName, field) {
+    const sourceDescription = this.sourceDescriptionIndex.get(sourceDescriptionName);
+    if (sourceDescription === undefined) return undefined;
+    if (field === 'url') return sourceDescription.uri;
+    return (0, _apidomCore.toValue)(sourceDescription.element.get(field));
+  }
+
+  /**
+   * The canonical URIs of this document's source descriptions, resolved against
+   * this document's base URI, in declaration order. Sources without a resolvable
+   * url are omitted.
+   */
+  sourceDescriptionURIs() {
+    return [...this.sourceDescriptionIndex.values()].map(entry => entry.uri).filter(uri => uri !== undefined);
+  }
+}
+var _default = exports.default = ArazzoDocument;

package/src/document/ArazzoDocument.mjs

@@ -0,0 +1,74 @@
+import { toValue } from '@speclynx/apidom-core';
+import APIDocument from "./APIDocument.mjs";
+/**
+ * An Arazzo document held by the document registry: the parse result together
+ * with the indexes the provider built over it — a container, not a logic
+ * bearer. The methods below are thin reads of the source description index.
+ * @public
+ */
+class ArazzoDocument extends APIDocument {
+  type = 'arazzo';
+  isEntry;
+  /**
+   * WorkflowId → JSON Pointer to the workflow within the parse result.
+   */
+  workflowIndex;
+  /**
+   * WorkflowId → stepId → JSON Pointer to the step within the parse result.
+   * Built by the provider, like {@link ArazzoDocument.workflowIndex}.
+   */
+  stepIndex;
+  /**
+   * Name → source description element and canonical URI (already resolved
+   * against this document's base URI). Built by the provider, like
+   * {@link ArazzoDocument.workflowIndex}.
+   */
+  sourceDescriptionIndex;
+  constructor(uri, parseResult, workflowIndex, stepIndex, sourceDescriptionIndex, isEntry = false) {
+    super(uri, parseResult);
+    this.isEntry = isEntry;
+    this.workflowIndex = workflowIndex;
+    this.stepIndex = stepIndex;
+    this.sourceDescriptionIndex = sourceDescriptionIndex;
+  }
+
+  /**
+   * Type guard for ArazzoDocument.
+   */
+  static is(doc) {
+    return doc.type === 'arazzo';
+  }
+
+  /**
+   * Resolves a source description name to its canonical URI — precomputed by
+   * the provider, resolved against this document's base URI.
+   */
+  resolveSourceDescriptionURI(sourceDescriptionName) {
+    return this.sourceDescriptionIndex.get(sourceDescriptionName)?.uri;
+  }
+
+  /**
+   * Resolves a field of a source description object (e.g. `url`, `type`).
+   *
+   * The `url` field resolves to the canonical URI (resolved against this
+   * document's base URI, as `resolveSourceDescriptionURI` does); every other
+   * field resolves to its literal value. Returns `undefined` when the source
+   * description or the field is absent.
+   */
+  resolveSourceDescriptionField(sourceDescriptionName, field) {
+    const sourceDescription = this.sourceDescriptionIndex.get(sourceDescriptionName);
+    if (sourceDescription === undefined) return undefined;
+    if (field === 'url') return sourceDescription.uri;
+    return toValue(sourceDescription.element.get(field));
+  }
+
+  /**
+   * The canonical URIs of this document's source descriptions, resolved against
+   * this document's base URI, in declaration order. Sources without a resolvable
+   * url are omitted.
+   */
+  sourceDescriptionURIs() {
+    return [...this.sourceDescriptionIndex.values()].map(entry => entry.uri).filter(uri => uri !== undefined);
+  }
+}
+export default ArazzoDocument;

package/src/document/ArazzoSourceDescriptionIndex.cjs

@@ -0,0 +1,26 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+/**
+ * Unique name of a source description within an Arazzo document.
+ * @public
+ */
+
+/**
+ * One indexed source description: the parsed element and its canonical URI —
+ * already resolved against the owning document's base URI, in the exact form
+ * the document registry keys on — or `undefined` for a source with no
+ * resolvable `url`.
+ * @public
+ */
+
+/**
+ * Index mapping a source description name to its element and canonical URI in
+ * an Arazzo document.
+ * @public
+ */
+class ArazzoSourceDescriptionIndex extends Map {}
+var _default = exports.default = ArazzoSourceDescriptionIndex;

package/src/document/ArazzoSourceDescriptionIndex.mjs

@@ -0,0 +1,20 @@
+/**
+ * Unique name of a source description within an Arazzo document.
+ * @public
+ */
+
+/**
+ * One indexed source description: the parsed element and its canonical URI —
+ * already resolved against the owning document's base URI, in the exact form
+ * the document registry keys on — or `undefined` for a source with no
+ * resolvable `url`.
+ * @public
+ */
+
+/**
+ * Index mapping a source description name to its element and canonical URI in
+ * an Arazzo document.
+ * @public
+ */
+class ArazzoSourceDescriptionIndex extends Map {}
+export default ArazzoSourceDescriptionIndex;

package/src/document/ArazzoStepIndex.cjs

@@ -0,0 +1,25 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+/**
+ * Unique identifier of a step within an Arazzo workflow.
+ * @public
+ */
+
+/**
+ * Index mapping workflowId → stepId → JSON Pointer to the step in an Arazzo
+ * document. Steps are unique only within their workflow, hence the nesting.
+ * @public
+ */
+class ArazzoStepIndex extends Map {
+  /**
+   * The JSON Pointer of a step, or `undefined` when the workflow or step is absent.
+   */
+  getStep(workflowId, stepId) {
+    return this.get(workflowId)?.get(stepId);
+  }
+}
+var _default = exports.default = ArazzoStepIndex;

package/src/document/ArazzoStepIndex.mjs

@@ -0,0 +1,19 @@
+/**
+ * Unique identifier of a step within an Arazzo workflow.
+ * @public
+ */
+
+/**
+ * Index mapping workflowId → stepId → JSON Pointer to the step in an Arazzo
+ * document. Steps are unique only within their workflow, hence the nesting.
+ * @public
+ */
+class ArazzoStepIndex extends Map {
+  /**
+   * The JSON Pointer of a step, or `undefined` when the workflow or step is absent.
+   */
+  getStep(workflowId, stepId) {
+    return this.get(workflowId)?.get(stepId);
+  }
+}
+export default ArazzoStepIndex;

package/src/document/ArazzoWorkflowIndex.cjs

@@ -0,0 +1,17 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+/**
+ * Unique identifier of an Arazzo workflow.
+ * @public
+ */
+
+/**
+ * Index mapping workflowId to its JSON Pointer in an Arazzo document.
+ * @public
+ */
+class ArazzoWorkflowIndex extends Map {}
+var _default = exports.default = ArazzoWorkflowIndex;

package/src/document/ArazzoWorkflowIndex.mjs

@@ -0,0 +1,11 @@
+/**
+ * Unique identifier of an Arazzo workflow.
+ * @public
+ */
+
+/**
+ * Index mapping workflowId to its JSON Pointer in an Arazzo document.
+ * @public
+ */
+class ArazzoWorkflowIndex extends Map {}
+export default ArazzoWorkflowIndex;

package/src/document/OpenAPIDocument.cjs

@@ -0,0 +1,28 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _APIDocument = _interopRequireDefault(require("./APIDocument.cjs"));
+/**
+ * An OpenAPI document held by the document registry.
+ * @public
+ */
+class OpenAPIDocument extends _APIDocument.default {
+  type = 'openapi';
+  operationIndex;
+  constructor(uri, parseResult, operationIndex) {
+    super(uri, parseResult);
+    this.operationIndex = operationIndex;
+  }
+
+  /**
+   * Type guard for OpenAPIDocument.
+   */
+  static is(doc) {
+    return doc.type === 'openapi';
+  }
+}
+var _default = exports.default = OpenAPIDocument;

package/src/document/OpenAPIDocument.mjs

@@ -0,0 +1,21 @@
+import APIDocument from "./APIDocument.mjs";
+/**
+ * An OpenAPI document held by the document registry.
+ * @public
+ */
+class OpenAPIDocument extends APIDocument {
+  type = 'openapi';
+  operationIndex;
+  constructor(uri, parseResult, operationIndex) {
+    super(uri, parseResult);
+    this.operationIndex = operationIndex;
+  }
+
+  /**
+   * Type guard for OpenAPIDocument.
+   */
+  static is(doc) {
+    return doc.type === 'openapi';
+  }
+}
+export default OpenAPIDocument;