@usearazzo/runner 1.0.1-alpha.19 → 1.0.1-alpha.21

package/src/criterion/JSONPathCriterionEvaluator.cjs

@@ -6,7 +6,8 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 var _jsonpath = require("@swaggerexpert/jsonpath");
-var _CriterionError = _interopRequireDefault(require("../errors/CriterionError.cjs"));
+var _CriterionEvaluationError = _interopRequireDefault(require("../errors/CriterionEvaluationError.cjs"));
+var _CriterionErrorReason = _interopRequireDefault(require("./CriterionErrorReason.cjs"));
 /**
  * Evaluates a `jsonpath` Arazzo criterion condition against a resolved context value.
  *
@@ -25,7 +26,7 @@ class JSONPathCriterionEvaluator {
    * whether it matched anything.
    *
    * Returns `false` when the context is `null` or `undefined`. Throws
-   * {@link CriterionError} when the condition is not a valid JSONPath query.
+   * {@link CriterionEvaluationError} when the condition is not a valid JSONPath query.
    */
   evaluate(condition, context) {
     if (context === null || context === undefined) return false;
@@ -33,11 +34,14 @@ class JSONPathCriterionEvaluator {
       return (0, _jsonpath.evaluate)(context, condition).length > 0;
     } catch (error) {
       if (error instanceof _jsonpath.JSONPathError) {
-        throw new _CriterionError.default(`Invalid jsonpath criterion condition "${condition}"`, {
+        // a parse error describes the query only; an evaluation error ran
+        // against the context, so its message is not surfaced.
+        const detail = error instanceof _jsonpath.JSONPathParseError ? `: ${error.message}` : '';
+        throw new _CriterionEvaluationError.default(`Invalid jsonpath criterion condition "${condition}"${detail}`, {
           cause: error,
           condition,
           type: 'jsonpath',
-          reason: 'invalid-jsonpath'
+          reason: _CriterionErrorReason.default.InvalidJSONPath
         });
       }
       throw error;

package/src/criterion/JSONPathCriterionEvaluator.mjs

@@ -1,5 +1,6 @@
-import { evaluate as evaluateJSONPath, JSONPathError } from '@swaggerexpert/jsonpath';
-import CriterionError from "../errors/CriterionError.mjs";
+import { evaluate as evaluateJSONPath, JSONPathError, JSONPathParseError } from '@swaggerexpert/jsonpath';
+import CriterionEvaluationError from "../errors/CriterionEvaluationError.mjs";
+import CriterionErrorReason from "./CriterionErrorReason.mjs";
 /**
  * Evaluates a `jsonpath` Arazzo criterion condition against a resolved context value.
  *
@@ -18,7 +19,7 @@ class JSONPathCriterionEvaluator {
    * whether it matched anything.
    *
    * Returns `false` when the context is `null` or `undefined`. Throws
-   * {@link CriterionError} when the condition is not a valid JSONPath query.
+   * {@link CriterionEvaluationError} when the condition is not a valid JSONPath query.
    */
   evaluate(condition, context) {
     if (context === null || context === undefined) return false;
@@ -26,11 +27,14 @@ class JSONPathCriterionEvaluator {
       return evaluateJSONPath(context, condition).length > 0;
     } catch (error) {
       if (error instanceof JSONPathError) {
-        throw new CriterionError(`Invalid jsonpath criterion condition "${condition}"`, {
+        // a parse error describes the query only; an evaluation error ran
+        // against the context, so its message is not surfaced.
+        const detail = error instanceof JSONPathParseError ? `: ${error.message}` : '';
+        throw new CriterionEvaluationError(`Invalid jsonpath criterion condition "${condition}"${detail}`, {
           cause: error,
           condition,
           type: 'jsonpath',
-          reason: 'invalid-jsonpath'
+          reason: CriterionErrorReason.InvalidJSONPath
         });
       }
       throw error;

package/src/criterion/RegexCriterionEvaluator.cjs

@@ -5,7 +5,8 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = void 0;
-var _CriterionError = _interopRequireDefault(require("../errors/CriterionError.cjs"));
+var _CriterionEvaluationError = _interopRequireDefault(require("../errors/CriterionEvaluationError.cjs"));
+var _CriterionErrorReason = _interopRequireDefault(require("./CriterionErrorReason.cjs"));
 /**
  * Evaluates a `regex` Arazzo criterion condition against a resolved context value.
  *
@@ -33,7 +34,7 @@ class RegexCriterionEvaluator {
    * Tests the resolved context value against the regular expression `condition`.
    *
    * The context is coerced to a string before matching. Returns `false` when the
-   * context is `null` or `undefined`. Throws {@link CriterionError} when the
+   * context is `null` or `undefined`. Throws {@link CriterionEvaluationError} when the
    * condition is not a valid regular expression.
    */
   evaluate(condition, context) {
@@ -42,11 +43,13 @@ class RegexCriterionEvaluator {
     try {
       regExp = new RegExp(condition);
     } catch (error) {
-      throw new _CriterionError.default(`Invalid regex criterion condition "${condition}"`, {
+      // the engine has seen only the pattern, never the context, so its
+      // message is safe to surface.
+      throw new _CriterionEvaluationError.default(`Invalid regex criterion condition "${condition}": ${error.message}`, {
         cause: error,
         condition,
         type: 'regex',
-        reason: 'invalid-regex'
+        reason: _CriterionErrorReason.default.InvalidRegex
       });
     }
     return regExp.test(this.#stringify(context));

package/src/criterion/RegexCriterionEvaluator.mjs

@@ -1,4 +1,5 @@
-import CriterionError from "../errors/CriterionError.mjs";
+import CriterionEvaluationError from "../errors/CriterionEvaluationError.mjs";
+import CriterionErrorReason from "./CriterionErrorReason.mjs";
 /**
  * Evaluates a `regex` Arazzo criterion condition against a resolved context value.
  *
@@ -26,7 +27,7 @@ class RegexCriterionEvaluator {
    * Tests the resolved context value against the regular expression `condition`.
    *
    * The context is coerced to a string before matching. Returns `false` when the
-   * context is `null` or `undefined`. Throws {@link CriterionError} when the
+   * context is `null` or `undefined`. Throws {@link CriterionEvaluationError} when the
    * condition is not a valid regular expression.
    */
   evaluate(condition, context) {
@@ -35,11 +36,13 @@ class RegexCriterionEvaluator {
     try {
       regExp = new RegExp(condition);
     } catch (error) {
-      throw new CriterionError(`Invalid regex criterion condition "${condition}"`, {
+      // the engine has seen only the pattern, never the context, so its
+      // message is safe to surface.
+      throw new CriterionEvaluationError(`Invalid regex criterion condition "${condition}": ${error.message}`, {
         cause: error,
         condition,
         type: 'regex',
-        reason: 'invalid-regex'
+        reason: CriterionErrorReason.InvalidRegex
       });
     }
     return regExp.test(this.#stringify(context));

package/src/criterion/SimpleCriterionEvaluator.cjs

@@ -6,7 +6,8 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 var _arazzoCriterion = require("@swaggerexpert/arazzo-criterion");
-var _CriterionError = _interopRequireDefault(require("../errors/CriterionError.cjs"));
+var _CriterionEvaluationError = _interopRequireDefault(require("../errors/CriterionEvaluationError.cjs"));
+var _CriterionErrorReason = _interopRequireDefault(require("./CriterionErrorReason.cjs"));
 /**
  * Evaluates a `simple` Arazzo criterion condition.
  *
@@ -21,7 +22,7 @@ var _CriterionError = _interopRequireDefault(require("../errors/CriterionError.c
  * 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}.
+ * {@link CriterionEvaluationError}.
  * @public
  */
 class SimpleCriterionEvaluator {
@@ -36,11 +37,11 @@ class SimpleCriterionEvaluator {
       });
     } catch (error) {
       if (error instanceof _arazzoCriterion.ArazzoCriterionError) {
-        throw new _CriterionError.default(`Invalid simple criterion condition "${condition}"`, {
+        throw new _CriterionEvaluationError.default(`Invalid simple criterion condition "${condition}"`, {
           cause: error,
           condition,
           type: 'simple',
-          reason: 'invalid-simple'
+          reason: _CriterionErrorReason.default.InvalidSimple
         });
       }
       throw error;

package/src/criterion/SimpleCriterionEvaluator.mjs

@@ -1,5 +1,6 @@
 import { evaluate as evaluateSimpleCriterion, ArazzoCriterionError } from '@swaggerexpert/arazzo-criterion';
-import CriterionError from "../errors/CriterionError.mjs";
+import CriterionEvaluationError from "../errors/CriterionEvaluationError.mjs";
+import CriterionErrorReason from "./CriterionErrorReason.mjs";
 /**
  * Evaluates a `simple` Arazzo criterion condition.
  *
@@ -14,7 +15,7 @@ import CriterionError from "../errors/CriterionError.mjs";
  * 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}.
+ * {@link CriterionEvaluationError}.
  * @public
  */
 class SimpleCriterionEvaluator {
@@ -29,11 +30,11 @@ class SimpleCriterionEvaluator {
       });
     } catch (error) {
       if (error instanceof ArazzoCriterionError) {
-        throw new CriterionError(`Invalid simple criterion condition "${condition}"`, {
+        throw new CriterionEvaluationError(`Invalid simple criterion condition "${condition}"`, {
           cause: error,
           condition,
           type: 'simple',
-          reason: 'invalid-simple'
+          reason: CriterionErrorReason.InvalidSimple
         });
       }
       throw error;

package/src/criterion/XPathCriterionEvaluator.cjs

@@ -7,7 +7,8 @@ Object.defineProperty(exports, "__esModule", {
 exports.default = void 0;
 var _fontoxpath = _interopRequireDefault(require("fontoxpath"));
 var _xmldom = require("@xmldom/xmldom");
-var _CriterionError = _interopRequireDefault(require("../errors/CriterionError.cjs"));
+var _CriterionEvaluationError = _interopRequireDefault(require("../errors/CriterionEvaluationError.cjs"));
+var _CriterionErrorReason = _interopRequireDefault(require("./CriterionErrorReason.cjs"));
 // fontoxpath is CommonJS and its named exports are not statically resolvable
 // under ESM, so import the default and destructure.
 
@@ -28,7 +29,7 @@ const {
  *
  * 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}.
+ * condition. An invalid query throws {@link CriterionEvaluationError}.
  * @public
  */
 class XPathCriterionEvaluator {
@@ -37,7 +38,7 @@ class XPathCriterionEvaluator {
    * 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.
+   * {@link CriterionEvaluationError} when the context is not XML or the query is invalid.
    */
   evaluate(condition, context) {
     if (context === null || context === undefined) return false;
@@ -47,11 +48,14 @@ class XPathCriterionEvaluator {
         language: evaluateXPath.XPATH_3_1_LANGUAGE
       });
     } catch (error) {
-      throw new _CriterionError.default(`Invalid xpath criterion condition "${condition}"`, {
+      // no engine detail: the query has run against the context, and it can
+      // put context values into its own error (a dynamic error, or fn:error
+      // with a code and description of the query's choosing).
+      throw new _CriterionEvaluationError.default(`Invalid xpath criterion condition "${condition}"`, {
         cause: error,
         condition,
         type: 'xpath',
-        reason: 'invalid-xpath'
+        reason: _CriterionErrorReason.default.InvalidXPath
       });
     }
   }
@@ -64,10 +68,10 @@ class XPathCriterionEvaluator {
   #toNode(condition, context) {
     if (this.#isNode(context)) return context;
     if (typeof context !== 'string') {
-      throw new _CriterionError.default('xpath criterion context is not XML', {
+      throw new _CriterionEvaluationError.default('xpath criterion context is not XML', {
         condition,
         type: 'xpath',
-        reason: 'invalid-context'
+        reason: _CriterionErrorReason.default.InvalidXPathContext
       });
     }
 
@@ -83,21 +87,21 @@ class XPathCriterionEvaluator {
         }
       }).parseFromString(context, 'text/xml');
       if (parseError !== undefined) {
-        throw new _CriterionError.default('xpath criterion context is not valid XML', {
+        throw new _CriterionEvaluationError.default('xpath criterion context is not valid XML', {
           cause: parseError,
           condition,
           type: 'xpath',
-          reason: 'invalid-context'
+          reason: _CriterionErrorReason.default.InvalidXPathContext
         });
       }
       return document;
     } catch (error) {
-      if (error instanceof _CriterionError.default) throw error;
-      throw new _CriterionError.default('xpath criterion context is not valid XML', {
+      if (error instanceof _CriterionEvaluationError.default) throw error;
+      throw new _CriterionEvaluationError.default('xpath criterion context is not valid XML', {
         cause: error,
         condition,
         type: 'xpath',
-        reason: 'invalid-context'
+        reason: _CriterionErrorReason.default.InvalidXPathContext
       });
     }
   }

package/src/criterion/XPathCriterionEvaluator.mjs

@@ -2,7 +2,8 @@
 // under ESM, so import the default and destructure.
 import fontoxpath from 'fontoxpath';
 import { DOMParser } from '@xmldom/xmldom';
-import CriterionError from "../errors/CriterionError.mjs";
+import CriterionEvaluationError from "../errors/CriterionEvaluationError.mjs";
+import CriterionErrorReason from "./CriterionErrorReason.mjs";
 const {
   evaluateXPathToBoolean,
   evaluateXPath
@@ -20,7 +21,7 @@ const {
  *
  * 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}.
+ * condition. An invalid query throws {@link CriterionEvaluationError}.
  * @public
  */
 class XPathCriterionEvaluator {
@@ -29,7 +30,7 @@ class XPathCriterionEvaluator {
    * 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.
+   * {@link CriterionEvaluationError} when the context is not XML or the query is invalid.
    */
   evaluate(condition, context) {
     if (context === null || context === undefined) return false;
@@ -39,11 +40,14 @@ class XPathCriterionEvaluator {
         language: evaluateXPath.XPATH_3_1_LANGUAGE
       });
     } catch (error) {
-      throw new CriterionError(`Invalid xpath criterion condition "${condition}"`, {
+      // no engine detail: the query has run against the context, and it can
+      // put context values into its own error (a dynamic error, or fn:error
+      // with a code and description of the query's choosing).
+      throw new CriterionEvaluationError(`Invalid xpath criterion condition "${condition}"`, {
         cause: error,
         condition,
         type: 'xpath',
-        reason: 'invalid-xpath'
+        reason: CriterionErrorReason.InvalidXPath
       });
     }
   }
@@ -56,10 +60,10 @@ class XPathCriterionEvaluator {
   #toNode(condition, context) {
     if (this.#isNode(context)) return context;
     if (typeof context !== 'string') {
-      throw new CriterionError('xpath criterion context is not XML', {
+      throw new CriterionEvaluationError('xpath criterion context is not XML', {
         condition,
         type: 'xpath',
-        reason: 'invalid-context'
+        reason: CriterionErrorReason.InvalidXPathContext
       });
     }
 
@@ -75,21 +79,21 @@ class XPathCriterionEvaluator {
         }
       }).parseFromString(context, 'text/xml');
       if (parseError !== undefined) {
-        throw new CriterionError('xpath criterion context is not valid XML', {
+        throw new CriterionEvaluationError('xpath criterion context is not valid XML', {
           cause: parseError,
           condition,
           type: 'xpath',
-          reason: 'invalid-context'
+          reason: CriterionErrorReason.InvalidXPathContext
         });
       }
       return document;
     } catch (error) {
-      if (error instanceof CriterionError) throw error;
-      throw new CriterionError('xpath criterion context is not valid XML', {
+      if (error instanceof CriterionEvaluationError) throw error;
+      throw new CriterionEvaluationError('xpath criterion context is not valid XML', {
         cause: error,
         condition,
         type: 'xpath',
-        reason: 'invalid-context'
+        reason: CriterionErrorReason.InvalidXPathContext
       });
     }
   }

package/src/errors/CriterionEvaluationError.cjs

@@ -0,0 +1,18 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _CriterionError = _interopRequireDefault(require("./CriterionError.cjs"));
+/**
+ * A criterion condition that cannot be evaluated: a syntax error in the
+ * condition, a context the condition cannot apply to, or an error raised while
+ * evaluating it. The type-specific criterion evaluators throw it;
+ * `CriterionEvaluator` turns it into an unmet criterion, as Arazzo 1.1.0
+ * requires.
+ * @public
+ */
+class CriterionEvaluationError extends _CriterionError.default {}
+var _default = exports.default = CriterionEvaluationError;

package/src/errors/CriterionEvaluationError.mjs

@@ -0,0 +1,11 @@
+import CriterionError from "./CriterionError.mjs";
+/**
+ * A criterion condition that cannot be evaluated: a syntax error in the
+ * condition, a context the condition cannot apply to, or an error raised while
+ * evaluating it. The type-specific criterion evaluators throw it;
+ * `CriterionEvaluator` turns it into an unmet criterion, as Arazzo 1.1.0
+ * requires.
+ * @public
+ */
+class CriterionEvaluationError extends CriterionError {}
+export default CriterionEvaluationError;

package/src/executor/StepExecutor.cjs

@@ -44,6 +44,12 @@ const STEP_TARGET_FIELDS = exports.STEP_TARGET_FIELDS = ['operationId', 'operati
  * @public
  */
 
+/**
+ * The outcome of one criterion a step evaluated: one of its `successCriteria`,
+ * or one of the `criteria` of an action it considered.
+ * @public
+ */
+
 /**
  * The outcome of executing a single step.
  * @public
@@ -190,16 +196,22 @@ class StepExecutor {
     // evaluate criteria, outputs, and the next action against the post-request
     // context (with $request / $url / $method and $response / $statusCode).
     const postContext = state.toContext(this.#requestContext(response), this.#responseContext(response));
-    const successful = this.evaluateCriteria(step, postContext);
+    const successCriteria = this.evaluateCriteria(step, postContext);
+    const successful = successCriteria.every(criterion => criterion.met);
     const outputs = this.#outputResolver.resolve(step.outputs, expression => this.#evaluate(postContext, expression), scope);
-    const matchedActions = this.selectActions(step, successful, postContext);
+    const {
+      matchedActions,
+      actionCriteria
+    } = this.selectActions(step, successful, postContext);
     return {
       stepId,
       response,
       successful,
       outputs,
       action: matchedActions[0],
-      matchedActions
+      matchedActions,
+      successCriteria,
+      actionCriteria
     };
   }
 
@@ -272,9 +284,12 @@ class StepExecutor {
   }
 
   /**
-   * Evaluates the step's `successCriteria`; all criteria must pass. A step with
-   * no criteria succeeds on a received response. An unreadable
-   * `successCriteria` throws, see {@link StepExecutor.assertSuccessCriteria}.
+   * Evaluates the step's `successCriteria`, returning one record per criterion
+   * in list order; the step succeeds when every record is met. Every criterion
+   * is evaluated, so the records explain each unmet one, not only the first. A
+   * step with no criteria returns no records and succeeds on a received
+   * response. An unreadable `successCriteria` throws, see
+   * {@link StepExecutor.assertSuccessCriteria}.
    *
    * Public for the same reason as {@link StepExecutor.selectActions}: a step
    * targeting a `workflowId` is run by the workflow executor and never reaches
@@ -284,15 +299,16 @@ class StepExecutor {
   evaluateCriteria(step, context) {
     this.assertSuccessCriteria(step);
     const criteria = step.successCriteria;
-    if (criteria === undefined) return true;
+    if (criteria === undefined) return [];
 
     // assertSuccessCriteria above guarantees every entry is a Criterion Object
-    return [...criteria].every(criterion => this.#criterionEvaluator.evaluate(criterion, expression => this.#evaluate(context, expression)));
+    return [...criteria].map(criterion => this.#evaluateCriterion(criterion, context));
   }
 
   /**
    * Selects every matching `onSuccess` / `onFailure` action for the outcome, in
-   * list order, gating each action's criteria against the context.
+   * list order, gating each action's criteria against the context, and records
+   * the outcome of every action criterion evaluated.
    *
    * The step's own list is the whole story here: a step that declares none of
    * its own already carries the workflow-level defaults, inherited by
@@ -311,25 +327,65 @@ class StepExecutor {
    * the expression context through this one method rather than wiring their own.
    */
   selectActions(step, successful, context) {
-    const isCriterionMet = criterion => {
-      try {
-        return this.#criterionEvaluator.evaluate(criterion, expression => this.#evaluate(context, expression));
-      } catch (error) {
-        // an action's criteria decide whether it applies to this outcome, and
-        // actions are shared — inherited from the workflow, reused from
-        // components. A condition on an HTTP exchange cannot apply to a step
-        // that calls a workflow, so the action does not match; the run does not
-        // abort over a default written for the operation steps.
-        if (error instanceof _RuntimeExpressionError.default && error.reason === 'unavailable-expression') {
-          return false;
-        }
-        throw error;
-      }
+    const actionCriteria = [];
+    const isCriterionMet = (criterion, action) => {
+      const record = {
+        ...this.#evaluateCriterion(criterion, context),
+        actionName: (0, _apidomCore.toValue)(action.name)
+      };
+      actionCriteria.push(record);
+      return record.met;
     };
     const scope = {
       stepId: (0, _apidomCore.toValue)(step.stepId)
     };
-    return successful ? this.#actionResolver.resolveOnSuccess(step.onSuccess, isCriterionMet, scope) : this.#actionResolver.resolveOnFailure(step.onFailure, isCriterionMet, scope);
+    const matchedActions = successful ? this.#actionResolver.resolveOnSuccess(step.onSuccess, isCriterionMet, scope) : this.#actionResolver.resolveOnFailure(step.onFailure, isCriterionMet, scope);
+    return {
+      matchedActions,
+      actionCriteria
+    };
+  }
+
+  /**
+   * Evaluates one criterion into a {@link CriterionEvaluationRecord}. A
+   * condition that cannot be evaluated is unmet and records why; any other
+   * error propagates.
+   */
+  #evaluateCriterion(criterion, context) {
+    const condition = (0, _apidomCore.toValue)(criterion.condition);
+    try {
+      const {
+        met,
+        error
+      } = this.#criterionEvaluator.evaluate(criterion, expression => this.#evaluate(context, expression));
+      if (error === undefined) return {
+        condition,
+        met
+      };
+      return {
+        condition,
+        met,
+        diagnostic: {
+          code: error.reason,
+          message: error.message
+        }
+      };
+    } catch (error) {
+      // a step that calls a workflow made no HTTP call, so a condition on one
+      // fails like any unevaluable condition; the diagnostic keeps the
+      // authoring mistake visible.
+      if (error instanceof _RuntimeExpressionError.default && error.reason === 'unavailable-expression') {
+        return {
+          condition,
+          met: false,
+          diagnostic: {
+            code: error.reason,
+            message: error.message
+          }
+        };
+      }
+      throw error;
+    }
   }
 
   /**