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

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;

package/src/document/OpenAPIOperationIndex.cjs

@@ -0,0 +1,24 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+/**
+ * Unique identifier of an OpenAPI operation.
+ * @public
+ */
+
+/**
+ * Index mapping operationId to its JSON Pointer in an OpenAPI document.
+ *
+ * Only used when an Arazzo step references an operation by `operationId`.
+ * When a step uses `operationPath` (a JSON Pointer), the index is bypassed
+ * and the pointer is used directly to locate the operation.
+ *
+ * Only operations with an operationId are indexed; operations without one
+ * are only reachable via `operationPath`.
+ * @public
+ */
+class OpenAPIOperationIndex extends Map {}
+var _default = exports.default = OpenAPIOperationIndex;

package/src/document/OpenAPIOperationIndex.mjs

@@ -0,0 +1,18 @@
+/**
+ * Unique identifier of an OpenAPI operation.
+ * @public
+ */
+
+/**
+ * Index mapping operationId to its JSON Pointer in an OpenAPI document.
+ *
+ * Only used when an Arazzo step references an operation by `operationId`.
+ * When a step uses `operationPath` (a JSON Pointer), the index is bypassed
+ * and the pointer is used directly to locate the operation.
+ *
+ * Only operations with an operationId are indexed; operations without one
+ * are only reachable via `operationPath`.
+ * @public
+ */
+class OpenAPIOperationIndex extends Map {}
+export default OpenAPIOperationIndex;

package/src/document/ParameterIdentity.cjs

@@ -0,0 +1,93 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _apidomCore = require("@speclynx/apidom-core");
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
+/**
+ * The `(name, in)` identity of an Arazzo Parameter Object — the one encoding
+ * of what makes two parameters "the same parameter", shared by
+ * `ArazzoWorkflowNormalizer` (which merges a workflow's parameters into its
+ * steps by it) and `OpenAPIOperationParameterResolver` (which keys delivery by
+ * it), so the two cannot drift apart.
+ *
+ * Identity is the pair — the rule ApiDOM's OpenAPI `normalize-parameters`
+ * plugin applies when inheriting a Path Item's parameters into an Operation
+ * ("a unique parameter is defined by a combination of a name and location").
+ * Arazzo's `in` is optional where OpenAPI's is required, and an absent one
+ * compares equal only to another absent one: that is a step naming a
+ * `workflowId`, where "all parameters map to workflow inputs" and there is no
+ * location to pair the name with. Names are case-sensitive per the
+ * specification, so nothing is case-folded.
+ *
+ * The location side is read three-way:
+ *
+ * - a string — the declared location, e.g. `'query'`;
+ * - `undefined` — no location: the shape of a workflow-input mapping,
+ *   meaningful for a step targeting a `workflowId` but naming no place in a
+ *   request. An explicitly empty `in:` (a YAML null) reads the same as an
+ *   omitted one — both say "no location", and treating the explicit spelling
+ *   as malformed would fail a run its `in`-omitted twin completes;
+ * - `null` — a location is declared but is not a string (`in: 1`), which
+ *   names no location and equals no other, its own duplicate included.
+ *
+ * An element without a well-formed identity has none at all
+ * ({@link ParameterIdentity.of} yields `undefined`) and is equal to nothing —
+ * an unresolved Reusable Object, a scalar someone put in the list, or a
+ * parameter whose `name` is missing or not a string. Such an entry has
+ * nothing to deduplicate on, and the normalizer's merge rebuilds the step's
+ * list, so calling it equal to another would delete authored content from the
+ * document. The OpenAPI plugin guards the same way and for the same reason.
+ * @internal
+ */
+class ParameterIdentity {
+  /**
+   * The identity of an element, or `undefined` when it has none — the element
+   * is not a Parameter Object, or its `name` is not a string.
+   */
+  static of(element) {
+    if (!(0, _apidomNsArazzo.isParameterElement)(element)) return undefined;
+    const name = (0, _apidomCore.toValue)(element.name);
+    if (typeof name !== 'string') return undefined;
+    return new ParameterIdentity(name, ParameterIdentity.locationOf(element));
+  }
+
+  /**
+   * Whether two elements are the same parameter: both have an identity, and
+   * the identities are equal. The shape `uniqWith` consumes.
+   */
+  static equal(element1, element2) {
+    const identity1 = ParameterIdentity.of(element1);
+    const identity2 = ParameterIdentity.of(element2);
+    return identity1 !== undefined && identity2 !== undefined && identity1.equals(identity2);
+  }
+
+  /**
+   * The three-way location read alone, for callers that need it without a
+   * full identity — the inheritance filter must keep a nameless-but-located
+   * entry, which has a location but no identity.
+   */
+  static locationOf(parameter) {
+    const location = parameter.in;
+    if (location === undefined || (0, _apidomDatamodel.isNullElement)(location)) return undefined;
+    return (0, _apidomDatamodel.isStringElement)(location) ? (0, _apidomCore.toValue)(location) : null;
+  }
+  name;
+  location;
+  constructor(name, location) {
+    this.name = name;
+    this.location = location;
+  }
+
+  /**
+   * Whether this and the other identity name the same parameter. A malformed
+   * location equals nothing, its own duplicate included.
+   */
+  equals(other) {
+    return this.location !== null && other.location !== null && this.name === other.name && this.location === other.location;
+  }
+}
+var _default = exports.default = ParameterIdentity;