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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usearazzo/runner",
-  "version": "1.0.1-alpha.20",
+  "version": "1.0.1-alpha.21",
   "description": "Runner for Arazzo Workflows.",
   "keywords": [
     "arazzo",
@@ -73,8 +73,8 @@
     "@swaggerexpert/json-pointer": "^3.0.2",
     "@swaggerexpert/jsonpath": "^4.0.5",
     "@swaggerexpert/media-types": "^1.0.2",
-    "@usearazzo/parser": "1.0.1-alpha.20",
-    "@usearazzo/resolver": "1.0.1-alpha.20",
+    "@usearazzo/parser": "1.0.1-alpha.21",
+    "@usearazzo/resolver": "1.0.1-alpha.21",
     "@xmldom/xmldom": "^0.9.12",
     "fontoxpath": "^3.34.0",
     "ramda": "^0.32.0",
@@ -94,5 +94,5 @@
   "devDependencies": {
     "swagger-client": "^3.38.4"
   },
-  "gitHead": "5af237fe28ae20de4d56e5c0ba6d2e17fcf90f73"
+  "gitHead": "d342b02adbd11f5362aa4850b2417521e59448ce"
 }

package/src/action/ActionResolver.cjs

@@ -9,10 +9,11 @@ var _apidomDatamodel = require("@speclynx/apidom-datamodel");
 var _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
 var _ResolverError = _interopRequireDefault(require("../errors/ResolverError.cjs"));
 /**
- * Determines whether a single criterion is met.
+ * Determines whether a single criterion of an action is met. Receives the
+ * action declaring the criterion, so a caller can attribute the outcome to it.
  *
  * Bridged to a criterion evaluator
- * (`(criterion) => criterionEvaluator.evaluate(criterion, resolve)`); an
+ * (`(criterion) => criterionEvaluator.evaluate(criterion, resolve).met`); an
  * unresolvable/failing criterion is `false`, not an error.
  * @public
  */
@@ -144,6 +145,7 @@ class ActionResolver {
         reason: 'malformed-criteria'
       });
     }
+    let met = true;
     for (const criterion of criteria) {
       if (!(0, _apidomNsArazzo.isCriterionElement)(criterion)) {
         throw new _ResolverError.default("An action's `criteria` contains an entry that is not a Criterion Object", {
@@ -152,9 +154,11 @@ class ActionResolver {
           reason: 'malformed-criterion'
         });
       }
-      if (!isCriterionMet(criterion)) return false;
+      // every criterion is evaluated, not only up to the first unmet one, so
+      // a predicate that records outcomes sees the whole list.
+      if (!isCriterionMet(criterion, action)) met = false;
     }
-    return true;
+    return met;
   }
 }
 var _default = exports.default = ActionResolver;

package/src/action/ActionResolver.mjs

@@ -2,10 +2,11 @@ import { isArrayElement } from '@speclynx/apidom-datamodel';
 import { isSuccessActionElement, isFailureActionElement, isCriterionElement } from '@speclynx/apidom-ns-arazzo-1';
 import ResolverError from "../errors/ResolverError.mjs";
 /**
- * Determines whether a single criterion is met.
+ * Determines whether a single criterion of an action is met. Receives the
+ * action declaring the criterion, so a caller can attribute the outcome to it.
  *
  * Bridged to a criterion evaluator
- * (`(criterion) => criterionEvaluator.evaluate(criterion, resolve)`); an
+ * (`(criterion) => criterionEvaluator.evaluate(criterion, resolve).met`); an
  * unresolvable/failing criterion is `false`, not an error.
  * @public
  */
@@ -134,6 +135,7 @@ class ActionResolver {
         reason: 'malformed-criteria'
       });
     }
+    let met = true;
     for (const criterion of criteria) {
       if (!isCriterionElement(criterion)) {
         throw new ResolverError("An action's `criteria` contains an entry that is not a Criterion Object", {
@@ -142,9 +144,11 @@ class ActionResolver {
           reason: 'malformed-criterion'
         });
       }
-      if (!isCriterionMet(criterion)) return false;
+      // every criterion is evaluated, not only up to the first unmet one, so
+      // a predicate that records outcomes sees the whole list.
+      if (!isCriterionMet(criterion, action)) met = false;
     }
-    return true;
+    return met;
   }
 }
 export default ActionResolver;

package/src/criterion/CriterionEvaluator.cjs

@@ -28,6 +28,11 @@ var _XPathCriterionEvaluator = _interopRequireDefault(require("./XPathCriterionE
  * @public
  */
 
+/**
+ * The outcome of evaluating one criterion.
+ * @public
+ */
+
 /**
  * Options for the CriterionEvaluator.
  *
@@ -38,7 +43,7 @@ var _XPathCriterionEvaluator = _interopRequireDefault(require("./XPathCriterionE
  */
 
 /**
- * Evaluates an Arazzo Criterion Object to a boolean.
+ * Evaluates an Arazzo Criterion Object to a {@link CriterionOutcome}.
  *
  * Dispatches on the criterion's `type` (defaulting to `simple` when omitted):
  * - `simple` — evaluates the condition directly, resolving the runtime
@@ -58,12 +63,13 @@ var _XPathCriterionEvaluator = _interopRequireDefault(require("./XPathCriterionE
  * the 1.1.0 rule to every document, which accepts more but never evaluates a
  * query under the wrong dialect.
  *
- * A condition that cannot be evaluated fails the criterion (`false`), as
+ * A condition that cannot be evaluated fails the criterion (`met: false`), as
  * Arazzo 1.1.0 requires: a syntax error in the condition, a context the
  * condition cannot apply to (non-XML data for `xpath`), or an XPath evaluation
  * error. The type-specific evaluators report these as a
- * {@link CriterionEvaluationError}, which this facade absorbs; any other error
- * they raise propagates. A criterion that is malformed as written still throws: a
+ * {@link CriterionEvaluationError}, which this facade returns as the
+ * outcome's `error` so the caller can report it; any other error they raise
+ * propagates. A criterion that is malformed as written still throws: a
  * missing `condition`, an unknown or unreadable `type`, an unsupported
  * expression `version`, or a `context` that is missing or not a runtime
  * expression.
@@ -87,7 +93,8 @@ class CriterionEvaluator {
   }
 
   /**
-   * Evaluates a criterion element, returning whether the condition is met.
+   * Evaluates a criterion element, returning whether the condition is met and,
+   * when it cannot be evaluated, why.
    *
    * `resolve` turns a runtime expression into a value: for `simple` it resolves
    * the expressions embedded in the condition; for the other types it resolves
@@ -109,23 +116,28 @@ class CriterionEvaluator {
     }
     const type = this.#resolveType(criterion);
     this.#requireValidContext(criterion, type);
+    let met;
     try {
       switch (type) {
         case 'simple':
-          return this.#simple.evaluate(condition, resolve);
+          met = this.#simple.evaluate(condition, resolve);
+          break;
         case 'regex':
-          return this.#regex.evaluate(condition, this.#resolveContext(criterion, type, resolve));
+          met = this.#regex.evaluate(condition, this.#resolveContext(criterion, type, resolve));
+          break;
         case 'jsonpath':
           // only rfc9535 is supported, Arazzo 1.1.0's default, so an omitted
           // version is accepted. draft-goessner has different semantics and is
           // rejected rather than mis-evaluated.
           this.#requireVersion(criterion, type, condition, 'rfc9535');
-          return this.#jsonpath.evaluate(condition, this.#resolveContext(criterion, type, resolve));
+          met = this.#jsonpath.evaluate(condition, this.#resolveContext(criterion, type, resolve));
+          break;
         case 'xpath':
           // only XPath 3.1 is supported; xpath-31 is Arazzo 1.1.0's default, so
           // an omitted version is accepted. Older versions are rejected.
           this.#requireVersion(criterion, type, condition, 'xpath-31');
-          return this.#xpath.evaluate(condition, this.#resolveContext(criterion, type, resolve));
+          met = this.#xpath.evaluate(condition, this.#resolveContext(criterion, type, resolve));
+          break;
         default:
           throw new _CriterionError.default(`Unknown criterion type "${type}"`, {
             condition,
@@ -136,9 +148,15 @@ class CriterionEvaluator {
     } catch (error) {
       // Arazzo 1.1.0: a condition that cannot be evaluated MUST evaluate to fail.
       // The structural checks throw a plain CriterionError and still propagate.
-      if (error instanceof _CriterionEvaluationError.default) return false;
+      if (error instanceof _CriterionEvaluationError.default) return {
+        met: false,
+        error
+      };
       throw error;
     }
+    return {
+      met
+    };
   }
 
   /**

package/src/criterion/CriterionEvaluator.mjs

@@ -20,6 +20,10 @@ import XPathCriterionEvaluator from "./XPathCriterionEvaluator.mjs";
  * lenient evaluator).
  * @public
  */
+/**
+ * The outcome of evaluating one criterion.
+ * @public
+ */
 /**
  * Options for the CriterionEvaluator.
  *
@@ -29,7 +33,7 @@ import XPathCriterionEvaluator from "./XPathCriterionEvaluator.mjs";
  * @public
  */
 /**
- * Evaluates an Arazzo Criterion Object to a boolean.
+ * Evaluates an Arazzo Criterion Object to a {@link CriterionOutcome}.
  *
  * Dispatches on the criterion's `type` (defaulting to `simple` when omitted):
  * - `simple` — evaluates the condition directly, resolving the runtime
@@ -49,12 +53,13 @@ import XPathCriterionEvaluator from "./XPathCriterionEvaluator.mjs";
  * the 1.1.0 rule to every document, which accepts more but never evaluates a
  * query under the wrong dialect.
  *
- * A condition that cannot be evaluated fails the criterion (`false`), as
+ * A condition that cannot be evaluated fails the criterion (`met: false`), as
  * Arazzo 1.1.0 requires: a syntax error in the condition, a context the
  * condition cannot apply to (non-XML data for `xpath`), or an XPath evaluation
  * error. The type-specific evaluators report these as a
- * {@link CriterionEvaluationError}, which this facade absorbs; any other error
- * they raise propagates. A criterion that is malformed as written still throws: a
+ * {@link CriterionEvaluationError}, which this facade returns as the
+ * outcome's `error` so the caller can report it; any other error they raise
+ * propagates. A criterion that is malformed as written still throws: a
  * missing `condition`, an unknown or unreadable `type`, an unsupported
  * expression `version`, or a `context` that is missing or not a runtime
  * expression.
@@ -78,7 +83,8 @@ class CriterionEvaluator {
   }
 
   /**
-   * Evaluates a criterion element, returning whether the condition is met.
+   * Evaluates a criterion element, returning whether the condition is met and,
+   * when it cannot be evaluated, why.
    *
    * `resolve` turns a runtime expression into a value: for `simple` it resolves
    * the expressions embedded in the condition; for the other types it resolves
@@ -100,23 +106,28 @@ class CriterionEvaluator {
     }
     const type = this.#resolveType(criterion);
     this.#requireValidContext(criterion, type);
+    let met;
     try {
       switch (type) {
         case 'simple':
-          return this.#simple.evaluate(condition, resolve);
+          met = this.#simple.evaluate(condition, resolve);
+          break;
         case 'regex':
-          return this.#regex.evaluate(condition, this.#resolveContext(criterion, type, resolve));
+          met = this.#regex.evaluate(condition, this.#resolveContext(criterion, type, resolve));
+          break;
         case 'jsonpath':
           // only rfc9535 is supported, Arazzo 1.1.0's default, so an omitted
           // version is accepted. draft-goessner has different semantics and is
           // rejected rather than mis-evaluated.
           this.#requireVersion(criterion, type, condition, 'rfc9535');
-          return this.#jsonpath.evaluate(condition, this.#resolveContext(criterion, type, resolve));
+          met = this.#jsonpath.evaluate(condition, this.#resolveContext(criterion, type, resolve));
+          break;
         case 'xpath':
           // only XPath 3.1 is supported; xpath-31 is Arazzo 1.1.0's default, so
           // an omitted version is accepted. Older versions are rejected.
           this.#requireVersion(criterion, type, condition, 'xpath-31');
-          return this.#xpath.evaluate(condition, this.#resolveContext(criterion, type, resolve));
+          met = this.#xpath.evaluate(condition, this.#resolveContext(criterion, type, resolve));
+          break;
         default:
           throw new CriterionError(`Unknown criterion type "${type}"`, {
             condition,
@@ -127,9 +138,15 @@ class CriterionEvaluator {
     } catch (error) {
       // Arazzo 1.1.0: a condition that cannot be evaluated MUST evaluate to fail.
       // The structural checks throw a plain CriterionError and still propagate.
-      if (error instanceof CriterionEvaluationError) return false;
+      if (error instanceof CriterionEvaluationError) return {
+        met: false,
+        error
+      };
       throw error;
     }
+    return {
+      met
+    };
   }
 
   /**

package/src/criterion/JSONPathCriterionEvaluator.cjs

@@ -34,7 +34,10 @@ class JSONPathCriterionEvaluator {
       return (0, _jsonpath.evaluate)(context, condition).length > 0;
     } catch (error) {
       if (error instanceof _jsonpath.JSONPathError) {
-        throw new _CriterionEvaluationError.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',

package/src/criterion/JSONPathCriterionEvaluator.mjs

@@ -1,4 +1,4 @@
-import { evaluate as evaluateJSONPath, JSONPathError } from '@swaggerexpert/jsonpath';
+import { evaluate as evaluateJSONPath, JSONPathError, JSONPathParseError } from '@swaggerexpert/jsonpath';
 import CriterionEvaluationError from "../errors/CriterionEvaluationError.mjs";
 import CriterionErrorReason from "./CriterionErrorReason.mjs";
 /**
@@ -27,7 +27,10 @@ class JSONPathCriterionEvaluator {
       return evaluateJSONPath(context, condition).length > 0;
     } catch (error) {
       if (error instanceof JSONPathError) {
-        throw new CriterionEvaluationError(`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',

package/src/criterion/RegexCriterionEvaluator.cjs

@@ -43,7 +43,9 @@ class RegexCriterionEvaluator {
     try {
       regExp = new RegExp(condition);
     } catch (error) {
-      throw new _CriterionEvaluationError.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',

package/src/criterion/RegexCriterionEvaluator.mjs

@@ -36,7 +36,9 @@ class RegexCriterionEvaluator {
     try {
       regExp = new RegExp(condition);
     } catch (error) {
-      throw new CriterionEvaluationError(`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',

package/src/criterion/XPathCriterionEvaluator.cjs

@@ -48,6 +48,9 @@ class XPathCriterionEvaluator {
         language: evaluateXPath.XPATH_3_1_LANGUAGE
       });
     } catch (error) {
+      // 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,

package/src/criterion/XPathCriterionEvaluator.mjs

@@ -40,6 +40,9 @@ class XPathCriterionEvaluator {
         language: evaluateXPath.XPATH_3_1_LANGUAGE
       });
     } catch (error) {
+      // 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,

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;
+    }
   }
 
   /**