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

package/src/document/ParameterIdentity.mjs

@@ -0,0 +1,88 @@
+import { toValue } from '@speclynx/apidom-core';
+import { isNullElement, isStringElement } from '@speclynx/apidom-datamodel';
+import { isParameterElement } from '@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 (!isParameterElement(element)) return undefined;
+    const name = 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 || isNullElement(location)) return undefined;
+    return isStringElement(location) ? 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;
+  }
+}
+export default ParameterIdentity;

package/src/document/openapi-types.cjs

@@ -0,0 +1,5 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});

package/src/document/openapi-types.mjs

@@ -0,0 +1 @@
+export {};

package/src/errors/ArazzoRunnerError.cjs

@@ -0,0 +1,10 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _apidomError = require("@speclynx/apidom-error");
+/** @public */
+class ArazzoRunnerError extends _apidomError.ApiDOMStructuredError {}
+var _default = exports.default = ArazzoRunnerError;

package/src/errors/ArazzoRunnerError.mjs

@@ -0,0 +1,5 @@
+import { ApiDOMStructuredError } from '@speclynx/apidom-error';
+
+/** @public */
+class ArazzoRunnerError extends ApiDOMStructuredError {}
+export default ArazzoRunnerError;

package/src/errors/AssemblerError.cjs

@@ -0,0 +1,11 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _ArazzoRunnerError = _interopRequireDefault(require("./ArazzoRunnerError.cjs"));
+/** @public */
+class AssemblerError extends _ArazzoRunnerError.default {}
+var _default = exports.default = AssemblerError;

package/src/errors/AssemblerError.mjs

@@ -0,0 +1,4 @@
+import ArazzoRunnerError from "./ArazzoRunnerError.mjs";
+/** @public */
+class AssemblerError extends ArazzoRunnerError {}
+export default AssemblerError;

package/src/errors/ClientError.cjs

@@ -0,0 +1,11 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _ArazzoRunnerError = _interopRequireDefault(require("./ArazzoRunnerError.cjs"));
+/** @public */
+class ClientError extends _ArazzoRunnerError.default {}
+var _default = exports.default = ClientError;

package/src/errors/ClientError.mjs

@@ -0,0 +1,4 @@
+import ArazzoRunnerError from "./ArazzoRunnerError.mjs";
+/** @public */
+class ClientError extends ArazzoRunnerError {}
+export default ClientError;

package/src/errors/CriterionError.cjs

@@ -0,0 +1,11 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _ArazzoRunnerError = _interopRequireDefault(require("./ArazzoRunnerError.cjs"));
+/** @public */
+class CriterionError extends _ArazzoRunnerError.default {}
+var _default = exports.default = CriterionError;

package/src/errors/CriterionError.mjs

@@ -0,0 +1,4 @@
+import ArazzoRunnerError from "./ArazzoRunnerError.mjs";
+/** @public */
+class CriterionError extends ArazzoRunnerError {}
+export default CriterionError;

package/src/errors/ExecutionError.cjs

@@ -0,0 +1,11 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _ArazzoRunnerError = _interopRequireDefault(require("./ArazzoRunnerError.cjs"));
+/** @public */
+class ExecutionError extends _ArazzoRunnerError.default {}
+var _default = exports.default = ExecutionError;

package/src/errors/ExecutionError.mjs

@@ -0,0 +1,4 @@
+import ArazzoRunnerError from "./ArazzoRunnerError.mjs";
+/** @public */
+class ExecutionError extends ArazzoRunnerError {}
+export default ExecutionError;

package/src/errors/ExtractionError.cjs

@@ -0,0 +1,11 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _ArazzoRunnerError = _interopRequireDefault(require("./ArazzoRunnerError.cjs"));
+/** @public */
+class ExtractionError extends _ArazzoRunnerError.default {}
+var _default = exports.default = ExtractionError;

package/src/errors/ExtractionError.mjs

@@ -0,0 +1,4 @@
+import ArazzoRunnerError from "./ArazzoRunnerError.mjs";
+/** @public */
+class ExtractionError extends ArazzoRunnerError {}
+export default ExtractionError;

package/src/errors/InvalidEntryDocumentError.cjs

@@ -0,0 +1,11 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _ArazzoRunnerError = _interopRequireDefault(require("./ArazzoRunnerError.cjs"));
+/** @public */
+class InvalidEntryDocumentError extends _ArazzoRunnerError.default {}
+var _default = exports.default = InvalidEntryDocumentError;

package/src/errors/InvalidEntryDocumentError.mjs

@@ -0,0 +1,4 @@
+import ArazzoRunnerError from "./ArazzoRunnerError.mjs";
+/** @public */
+class InvalidEntryDocumentError extends ArazzoRunnerError {}
+export default InvalidEntryDocumentError;

package/src/errors/NormalizationError.cjs

@@ -0,0 +1,11 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _ArazzoRunnerError = _interopRequireDefault(require("./ArazzoRunnerError.cjs"));
+/** @public */
+class NormalizationError extends _ArazzoRunnerError.default {}
+var _default = exports.default = NormalizationError;

package/src/errors/NormalizationError.mjs

@@ -0,0 +1,4 @@
+import ArazzoRunnerError from "./ArazzoRunnerError.mjs";
+/** @public */
+class NormalizationError extends ArazzoRunnerError {}
+export default NormalizationError;

package/src/errors/ResolverError.cjs

@@ -0,0 +1,11 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _ArazzoRunnerError = _interopRequireDefault(require("./ArazzoRunnerError.cjs"));
+/** @public */
+class ResolverError extends _ArazzoRunnerError.default {}
+var _default = exports.default = ResolverError;

package/src/errors/ResolverError.mjs

@@ -0,0 +1,4 @@
+import ArazzoRunnerError from "./ArazzoRunnerError.mjs";
+/** @public */
+class ResolverError extends ArazzoRunnerError {}
+export default ResolverError;

package/src/errors/RuntimeExpressionError.cjs

@@ -0,0 +1,11 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _ArazzoRunnerError = _interopRequireDefault(require("./ArazzoRunnerError.cjs"));
+/** @public */
+class RuntimeExpressionError extends _ArazzoRunnerError.default {}
+var _default = exports.default = RuntimeExpressionError;

package/src/errors/RuntimeExpressionError.mjs

@@ -0,0 +1,4 @@
+import ArazzoRunnerError from "./ArazzoRunnerError.mjs";
+/** @public */
+class RuntimeExpressionError extends ArazzoRunnerError {}
+export default RuntimeExpressionError;

package/src/errors/UnmatchedProviderError.cjs

@@ -0,0 +1,11 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _ArazzoRunnerError = _interopRequireDefault(require("./ArazzoRunnerError.cjs"));
+/** @public */
+class UnmatchedProviderError extends _ArazzoRunnerError.default {}
+var _default = exports.default = UnmatchedProviderError;

package/src/errors/UnmatchedProviderError.mjs

@@ -0,0 +1,4 @@
+import ArazzoRunnerError from "./ArazzoRunnerError.mjs";
+/** @public */
+class UnmatchedProviderError extends ArazzoRunnerError {}
+export default UnmatchedProviderError;

package/src/executor/ArazzoWorkflowLocatorNormalizer.cjs

@@ -0,0 +1,147 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _ArazzoDocument = _interopRequireDefault(require("../document/ArazzoDocument.cjs"));
+var _ExecutionError = _interopRequireDefault(require("../errors/ExecutionError.cjs"));
+var _SourceDescriptionsLocatorNormalizer = _interopRequireDefault(require("./SourceDescriptionsLocatorNormalizer.cjs"));
+/**
+ * A canonical Arazzo workflow locator: the Arazzo document that owns the
+ * workflow and the workflow's id within it.
+ *
+ * A workflow reference names its target in one of two ways — a plain
+ * `workflowId` of the current document, or a
+ * `$sourceDescriptions.{name}.{workflowId}` runtime expression naming a
+ * workflow of another Arazzo document. Both are locators for the same thing;
+ * the normalizer reduces either to this single canonical form. `workflowId`
+ * is the bare id either way — the key run state (`$workflows.{id}`) is
+ * recorded under, which the runtime-expression grammar can only express
+ * unqualified.
+ * @public
+ */
+
+/**
+ * A workflow reference, parsed but not yet resolved — the intermediate form
+ * between {@link ArazzoWorkflowLocatorNormalizer.normalize}'s two halves.
+ */
+
+/**
+ * The referencing context a reference is resolved in: the workflow (and step,
+ * when the reference sits on one) making the reference, stamped onto every
+ * error.
+ * @public
+ */
+
+/**
+ * Normalizes a workflow reference to a canonical {@link ArazzoWorkflowLocator}
+ * — the Arazzo document and the workflow's id within it.
+ *
+ * A reference appears in four author-facing positions — a sub-workflow step's
+ * `workflowId`, a `dependsOn` entry, a `retry` action's `workflowId`
+ * reference, and a `goto` action's transfer target — and is either a plain id
+ * of the referencing document or a whole
+ * `$sourceDescriptions.{name}.{workflowId}` runtime expression naming a
+ * workflow of another Arazzo document. Only that dotted expression form is a
+ * workflow reference; the resolver package's
+ * `$sourceDescriptions.{name}#/json/pointer` form is a `$ref`-time construct,
+ * not a runtime expression, and does not parse here.
+ *
+ * The `type` declared on a source description is not trusted (it may be
+ * absent or wrong); a source is classified by what it actually parses to,
+ * the same convention the OpenAPI operation locator follows. Source
+ * documents are acquired from the registry on demand. Whether the resolved
+ * document *defines* the workflow is deliberately left to the caller, which
+ * owns the timing of that check (eager for a `dependsOn` list validated
+ * before any prerequisite runs, lazy for a sub-workflow step resolved per
+ * attempt).
+ * @public
+ */
+class ArazzoWorkflowLocatorNormalizer extends _SourceDescriptionsLocatorNormalizer.default {
+  /**
+   * Resolves a reference — a plain workflowId or a
+   * `$sourceDescriptions.{name}.{workflowId}` expression, as written — to the
+   * canonical locator: the Arazzo document that owns the target workflow,
+   * and the bare id within it.
+   */
+  async normalize(reference, document, context) {
+    return this.#resolve(this.#parseReference(reference, context), document, context);
+  }
+
+  /**
+   * Parses a reference to its target. A reference starting with `$` must be
+   * a whole `$sourceDescriptions.{name}.{workflowId}` expression; anything
+   * else `$`-prefixed (another expression kind, or one that does not parse)
+   * is a malformed reference, rejected here rather than looked up as a
+   * literal id that cannot exist.
+   */
+  #parseReference(reference, {
+    workflowId,
+    stepId
+  }) {
+    if (!reference.startsWith('$')) {
+      return {
+        kind: 'local',
+        reference,
+        workflowId: reference
+      };
+    }
+    const parsed = this.parseSourceDescriptionsExpression(reference);
+    if (parsed === undefined) {
+      throw new _ExecutionError.default(`workflow reference "${reference}" in workflow "${workflowId}" is not a $sourceDescriptions.{name}.{workflowId} expression`, {
+        workflowId,
+        stepId,
+        reason: 'invalid-workflow-reference'
+      });
+    }
+    return {
+      kind: 'sourced',
+      reference,
+      sourceName: parsed.sourceName,
+      workflowId: parsed.reference
+    };
+  }
+
+  /**
+   * Resolves a parsed reference to the Arazzo document that owns the target
+   * workflow. A plain id resolves to the referencing document itself; an
+   * expression resolves its named source description to a URI, acquires that
+   * document from the registry, and requires it to actually be an Arazzo
+   * document.
+   */
+  async #resolve(parsed, document, context) {
+    if (parsed.kind === 'local') {
+      return {
+        document,
+        workflowId: parsed.workflowId
+      };
+    }
+    const {
+      workflowId,
+      stepId
+    } = context;
+    const uri = document.resolveSourceDescriptionURI(parsed.sourceName);
+    if (uri === undefined) {
+      throw new _ExecutionError.default(`workflow reference "${parsed.reference}" in workflow "${workflowId}" names source description "${parsed.sourceName}", which the Arazzo document at "${document.uri}" does not define`, {
+        workflowId,
+        stepId,
+        reason: 'source-description-not-found'
+      });
+    }
+    const source = await this.registry.acquire(uri);
+    if (!_ArazzoDocument.default.is(source)) {
+      throw new _ExecutionError.default(`workflow reference "${parsed.reference}" in workflow "${workflowId}" names source description "${parsed.sourceName}" at "${uri}", which is not an Arazzo document`, {
+        workflowId,
+        stepId,
+        reason: 'source-description-not-arazzo'
+      });
+    }
+    return {
+      document: source,
+      workflowId: parsed.workflowId
+    };
+  }
+}
+var _default = exports.default = ArazzoWorkflowLocatorNormalizer;

package/src/executor/ArazzoWorkflowLocatorNormalizer.mjs

@@ -0,0 +1,137 @@
+import ArazzoDocument from "../document/ArazzoDocument.mjs";
+import ExecutionError from "../errors/ExecutionError.mjs";
+import SourceDescriptionsLocatorNormalizer from "./SourceDescriptionsLocatorNormalizer.mjs";
+/**
+ * A canonical Arazzo workflow locator: the Arazzo document that owns the
+ * workflow and the workflow's id within it.
+ *
+ * A workflow reference names its target in one of two ways — a plain
+ * `workflowId` of the current document, or a
+ * `$sourceDescriptions.{name}.{workflowId}` runtime expression naming a
+ * workflow of another Arazzo document. Both are locators for the same thing;
+ * the normalizer reduces either to this single canonical form. `workflowId`
+ * is the bare id either way — the key run state (`$workflows.{id}`) is
+ * recorded under, which the runtime-expression grammar can only express
+ * unqualified.
+ * @public
+ */
+/**
+ * A workflow reference, parsed but not yet resolved — the intermediate form
+ * between {@link ArazzoWorkflowLocatorNormalizer.normalize}'s two halves.
+ */
+/**
+ * The referencing context a reference is resolved in: the workflow (and step,
+ * when the reference sits on one) making the reference, stamped onto every
+ * error.
+ * @public
+ */
+/**
+ * Normalizes a workflow reference to a canonical {@link ArazzoWorkflowLocator}
+ * — the Arazzo document and the workflow's id within it.
+ *
+ * A reference appears in four author-facing positions — a sub-workflow step's
+ * `workflowId`, a `dependsOn` entry, a `retry` action's `workflowId`
+ * reference, and a `goto` action's transfer target — and is either a plain id
+ * of the referencing document or a whole
+ * `$sourceDescriptions.{name}.{workflowId}` runtime expression naming a
+ * workflow of another Arazzo document. Only that dotted expression form is a
+ * workflow reference; the resolver package's
+ * `$sourceDescriptions.{name}#/json/pointer` form is a `$ref`-time construct,
+ * not a runtime expression, and does not parse here.
+ *
+ * The `type` declared on a source description is not trusted (it may be
+ * absent or wrong); a source is classified by what it actually parses to,
+ * the same convention the OpenAPI operation locator follows. Source
+ * documents are acquired from the registry on demand. Whether the resolved
+ * document *defines* the workflow is deliberately left to the caller, which
+ * owns the timing of that check (eager for a `dependsOn` list validated
+ * before any prerequisite runs, lazy for a sub-workflow step resolved per
+ * attempt).
+ * @public
+ */
+class ArazzoWorkflowLocatorNormalizer extends SourceDescriptionsLocatorNormalizer {
+  /**
+   * Resolves a reference — a plain workflowId or a
+   * `$sourceDescriptions.{name}.{workflowId}` expression, as written — to the
+   * canonical locator: the Arazzo document that owns the target workflow,
+   * and the bare id within it.
+   */
+  async normalize(reference, document, context) {
+    return this.#resolve(this.#parseReference(reference, context), document, context);
+  }
+
+  /**
+   * Parses a reference to its target. A reference starting with `$` must be
+   * a whole `$sourceDescriptions.{name}.{workflowId}` expression; anything
+   * else `$`-prefixed (another expression kind, or one that does not parse)
+   * is a malformed reference, rejected here rather than looked up as a
+   * literal id that cannot exist.
+   */
+  #parseReference(reference, {
+    workflowId,
+    stepId
+  }) {
+    if (!reference.startsWith('$')) {
+      return {
+        kind: 'local',
+        reference,
+        workflowId: reference
+      };
+    }
+    const parsed = this.parseSourceDescriptionsExpression(reference);
+    if (parsed === undefined) {
+      throw new ExecutionError(`workflow reference "${reference}" in workflow "${workflowId}" is not a $sourceDescriptions.{name}.{workflowId} expression`, {
+        workflowId,
+        stepId,
+        reason: 'invalid-workflow-reference'
+      });
+    }
+    return {
+      kind: 'sourced',
+      reference,
+      sourceName: parsed.sourceName,
+      workflowId: parsed.reference
+    };
+  }
+
+  /**
+   * Resolves a parsed reference to the Arazzo document that owns the target
+   * workflow. A plain id resolves to the referencing document itself; an
+   * expression resolves its named source description to a URI, acquires that
+   * document from the registry, and requires it to actually be an Arazzo
+   * document.
+   */
+  async #resolve(parsed, document, context) {
+    if (parsed.kind === 'local') {
+      return {
+        document,
+        workflowId: parsed.workflowId
+      };
+    }
+    const {
+      workflowId,
+      stepId
+    } = context;
+    const uri = document.resolveSourceDescriptionURI(parsed.sourceName);
+    if (uri === undefined) {
+      throw new ExecutionError(`workflow reference "${parsed.reference}" in workflow "${workflowId}" names source description "${parsed.sourceName}", which the Arazzo document at "${document.uri}" does not define`, {
+        workflowId,
+        stepId,
+        reason: 'source-description-not-found'
+      });
+    }
+    const source = await this.registry.acquire(uri);
+    if (!ArazzoDocument.is(source)) {
+      throw new ExecutionError(`workflow reference "${parsed.reference}" in workflow "${workflowId}" names source description "${parsed.sourceName}" at "${uri}", which is not an Arazzo document`, {
+        workflowId,
+        stepId,
+        reason: 'source-description-not-arazzo'
+      });
+    }
+    return {
+      document: source,
+      workflowId: parsed.workflowId
+    };
+  }
+}
+export default ArazzoWorkflowLocatorNormalizer;