@usearazzo/runner 1.0.1-alpha.23 → 1.0.1-alpha.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usearazzo/runner",
-  "version": "1.0.1-alpha.23",
+  "version": "1.0.1-alpha.25",
   "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.23",
-    "@usearazzo/resolver": "1.0.1-alpha.23",
+    "@usearazzo/parser": "1.0.1-alpha.25",
+    "@usearazzo/resolver": "1.0.1-alpha.25",
     "@xmldom/xmldom": "^0.9.12",
     "fontoxpath": "^3.34.0",
     "ramda": "^0.32.0",
@@ -94,5 +94,5 @@
   "devDependencies": {
     "swagger-client": "^3.38.4"
   },
-  "gitHead": "49de409b1fb851453c8c8c19cfdc12ec88545ca1"
+  "gitHead": "37de6e45a52dabf8a924f09fed3ae4d41396be7d"
 }

package/src/action/ActionResolver.cjs

@@ -106,7 +106,7 @@ class ActionResolver {
       throw new _ResolverError.default(`\`${field}\` is present but is not a list`, {
         ...scope,
         target: field,
-        reason: 'malformed-actions'
+        reason: _ResolverError.default.MalformedActions
       });
     }
     const matched = [];
@@ -115,7 +115,7 @@ class ActionResolver {
         throw new _ResolverError.default(`\`${field}\` contains an entry that is not a Success/Failure Action Object`, {
           ...scope,
           target: field,
-          reason: 'malformed-action-entry'
+          reason: _ResolverError.default.MalformedActionEntry
         });
       }
       if (this.#criteriaMet(action, isCriterionMet, scope)) {
@@ -142,7 +142,7 @@ class ActionResolver {
       throw new _ResolverError.default("An action's `criteria` is present but is not a list", {
         ...scope,
         target: 'criteria',
-        reason: 'malformed-criteria'
+        reason: _ResolverError.default.MalformedCriteria
       });
     }
     let met = true;
@@ -151,7 +151,7 @@ class ActionResolver {
         throw new _ResolverError.default("An action's `criteria` contains an entry that is not a Criterion Object", {
           ...scope,
           target: 'criteria',
-          reason: 'malformed-criterion'
+          reason: _ResolverError.default.MalformedCriterion
         });
       }
       // every criterion is evaluated, not only up to the first unmet one, so

package/src/action/ActionResolver.mjs

@@ -96,7 +96,7 @@ class ActionResolver {
       throw new ResolverError(`\`${field}\` is present but is not a list`, {
         ...scope,
         target: field,
-        reason: 'malformed-actions'
+        reason: ResolverError.MalformedActions
       });
     }
     const matched = [];
@@ -105,7 +105,7 @@ class ActionResolver {
         throw new ResolverError(`\`${field}\` contains an entry that is not a Success/Failure Action Object`, {
           ...scope,
           target: field,
-          reason: 'malformed-action-entry'
+          reason: ResolverError.MalformedActionEntry
         });
       }
       if (this.#criteriaMet(action, isCriterionMet, scope)) {
@@ -132,7 +132,7 @@ class ActionResolver {
       throw new ResolverError("An action's `criteria` is present but is not a list", {
         ...scope,
         target: 'criteria',
-        reason: 'malformed-criteria'
+        reason: ResolverError.MalformedCriteria
       });
     }
     let met = true;
@@ -141,7 +141,7 @@ class ActionResolver {
         throw new ResolverError("An action's `criteria` contains an entry that is not a Criterion Object", {
           ...scope,
           target: 'criteria',
-          reason: 'malformed-criterion'
+          reason: ResolverError.MalformedCriterion
         });
       }
       // every criterion is evaluated, not only up to the first unmet one, so

package/src/criterion/CriterionEvaluator.cjs

@@ -11,7 +11,6 @@ var _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
 var _arazzoRuntimeExpression = require("@swaggerexpert/arazzo-runtime-expression");
 var _CriterionError = _interopRequireDefault(require("../errors/CriterionError.cjs"));
 var _CriterionEvaluationError = _interopRequireDefault(require("../errors/CriterionEvaluationError.cjs"));
-var _CriterionErrorReason = _interopRequireDefault(require("./CriterionErrorReason.cjs"));
 var _RegexCriterionEvaluator = _interopRequireDefault(require("./RegexCriterionEvaluator.cjs"));
 var _SimpleCriterionEvaluator = _interopRequireDefault(require("./SimpleCriterionEvaluator.cjs"));
 var _JSONPathCriterionEvaluator = _interopRequireDefault(require("./JSONPathCriterionEvaluator.cjs"));
@@ -103,7 +102,7 @@ class CriterionEvaluator {
   evaluate(criterion, resolve) {
     if (!(0, _apidomNsArazzo.isCriterionElement)(criterion)) {
       throw new _CriterionError.default('Element is not a Criterion Object', {
-        reason: _CriterionErrorReason.default.InvalidCriterion
+        reason: _CriterionError.default.InvalidCriterion
       });
     }
     const condition = (0, _apidomDatamodel.isStringElement)(criterion.condition) ? (0, _apidomCore.toValue)(criterion.condition) : undefined;
@@ -111,7 +110,7 @@ class CriterionEvaluator {
     // (e.g. an empty regex would match unconditionally), so reject it too.
     if (condition === undefined || condition === '') {
       throw new _CriterionError.default('Criterion is missing a "condition"', {
-        reason: _CriterionErrorReason.default.MissingCondition
+        reason: _CriterionError.default.MissingCondition
       });
     }
     const type = this.#resolveType(criterion);
@@ -142,7 +141,7 @@ class CriterionEvaluator {
           throw new _CriterionError.default(`Unknown criterion type "${type}"`, {
             condition,
             type,
-            reason: _CriterionErrorReason.default.UnknownType
+            reason: _CriterionError.default.UnknownType
           });
       }
     } catch (error) {
@@ -173,7 +172,7 @@ class CriterionEvaluator {
     }
     if ((0, _apidomDatamodel.isStringElement)(type)) return (0, _apidomCore.toValue)(type);
     throw new _CriterionError.default('Criterion has an invalid "type"', {
-      reason: _CriterionErrorReason.default.InvalidType
+      reason: _CriterionError.default.InvalidType
     });
   }
 
@@ -193,7 +192,7 @@ class CriterionEvaluator {
       return (0, _apidomCore.toValue)(type.version);
     }
     throw new _CriterionError.default('Criterion has an invalid expression type "version"', {
-      reason: _CriterionErrorReason.default.InvalidVersion
+      reason: _CriterionError.default.InvalidVersion
     });
   }
 
@@ -208,7 +207,7 @@ class CriterionEvaluator {
       throw new _CriterionError.default(`Unsupported ${type} version "${version}" (only ${supported})`, {
         condition,
         type,
-        reason: _CriterionErrorReason.default.UnsupportedVersion
+        reason: _CriterionError.default.UnsupportedVersion
       });
     }
   }
@@ -226,7 +225,7 @@ class CriterionEvaluator {
     if (!(0, _apidomDatamodel.isStringElement)(context) || !(0, _arazzoRuntimeExpression.test)((0, _apidomCore.toValue)(context))) {
       throw new _CriterionError.default('Criterion has a "context" that is not a valid runtime expression', {
         type,
-        reason: _CriterionErrorReason.default.InvalidContext
+        reason: _CriterionError.default.InvalidContext
       });
     }
   }
@@ -241,7 +240,7 @@ class CriterionEvaluator {
     if (!(0, _apidomDatamodel.isStringElement)(criterion.context)) {
       throw new _CriterionError.default(`Criterion type "${type}" requires a "context"`, {
         type,
-        reason: _CriterionErrorReason.default.MissingContext
+        reason: _CriterionError.default.MissingContext
       });
     }
     return resolve((0, _apidomCore.toValue)(criterion.context));

package/src/criterion/CriterionEvaluator.mjs

@@ -4,7 +4,6 @@ import { isCriterionElement, isCriterionExpressionTypeElement } from '@speclynx/
 import { test as isRuntimeExpression } from '@swaggerexpert/arazzo-runtime-expression';
 import CriterionError from "../errors/CriterionError.mjs";
 import CriterionEvaluationError from "../errors/CriterionEvaluationError.mjs";
-import CriterionErrorReason from "./CriterionErrorReason.mjs";
 import RegexCriterionEvaluator from "./RegexCriterionEvaluator.mjs";
 import SimpleCriterionEvaluator from "./SimpleCriterionEvaluator.mjs";
 import JSONPathCriterionEvaluator from "./JSONPathCriterionEvaluator.mjs";
@@ -93,7 +92,7 @@ class CriterionEvaluator {
   evaluate(criterion, resolve) {
     if (!isCriterionElement(criterion)) {
       throw new CriterionError('Element is not a Criterion Object', {
-        reason: CriterionErrorReason.InvalidCriterion
+        reason: CriterionError.InvalidCriterion
       });
     }
     const condition = isStringElement(criterion.condition) ? toValue(criterion.condition) : undefined;
@@ -101,7 +100,7 @@ class CriterionEvaluator {
     // (e.g. an empty regex would match unconditionally), so reject it too.
     if (condition === undefined || condition === '') {
       throw new CriterionError('Criterion is missing a "condition"', {
-        reason: CriterionErrorReason.MissingCondition
+        reason: CriterionError.MissingCondition
       });
     }
     const type = this.#resolveType(criterion);
@@ -132,7 +131,7 @@ class CriterionEvaluator {
           throw new CriterionError(`Unknown criterion type "${type}"`, {
             condition,
             type,
-            reason: CriterionErrorReason.UnknownType
+            reason: CriterionError.UnknownType
           });
       }
     } catch (error) {
@@ -163,7 +162,7 @@ class CriterionEvaluator {
     }
     if (isStringElement(type)) return toValue(type);
     throw new CriterionError('Criterion has an invalid "type"', {
-      reason: CriterionErrorReason.InvalidType
+      reason: CriterionError.InvalidType
     });
   }
 
@@ -183,7 +182,7 @@ class CriterionEvaluator {
       return toValue(type.version);
     }
     throw new CriterionError('Criterion has an invalid expression type "version"', {
-      reason: CriterionErrorReason.InvalidVersion
+      reason: CriterionError.InvalidVersion
     });
   }
 
@@ -198,7 +197,7 @@ class CriterionEvaluator {
       throw new CriterionError(`Unsupported ${type} version "${version}" (only ${supported})`, {
         condition,
         type,
-        reason: CriterionErrorReason.UnsupportedVersion
+        reason: CriterionError.UnsupportedVersion
       });
     }
   }
@@ -216,7 +215,7 @@ class CriterionEvaluator {
     if (!isStringElement(context) || !isRuntimeExpression(toValue(context))) {
       throw new CriterionError('Criterion has a "context" that is not a valid runtime expression', {
         type,
-        reason: CriterionErrorReason.InvalidContext
+        reason: CriterionError.InvalidContext
       });
     }
   }
@@ -231,7 +230,7 @@ class CriterionEvaluator {
     if (!isStringElement(criterion.context)) {
       throw new CriterionError(`Criterion type "${type}" requires a "context"`, {
         type,
-        reason: CriterionErrorReason.MissingContext
+        reason: CriterionError.MissingContext
       });
     }
     return resolve(toValue(criterion.context));

package/src/criterion/JSONPathCriterionEvaluator.cjs

@@ -7,7 +7,6 @@ Object.defineProperty(exports, "__esModule", {
 exports.default = void 0;
 var _jsonpath = require("@swaggerexpert/jsonpath");
 var _CriterionEvaluationError = _interopRequireDefault(require("../errors/CriterionEvaluationError.cjs"));
-var _CriterionErrorReason = _interopRequireDefault(require("./CriterionErrorReason.cjs"));
 /**
  * Evaluates a `jsonpath` Arazzo criterion condition against a resolved context value.
  *
@@ -41,7 +40,7 @@ class JSONPathCriterionEvaluator {
           cause: error,
           condition,
           type: 'jsonpath',
-          reason: _CriterionErrorReason.default.InvalidJSONPath
+          reason: _CriterionEvaluationError.default.InvalidJSONPath
         });
       }
       throw error;

package/src/criterion/JSONPathCriterionEvaluator.mjs

@@ -1,6 +1,5 @@
 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.
  *
@@ -34,7 +33,7 @@ class JSONPathCriterionEvaluator {
           cause: error,
           condition,
           type: 'jsonpath',
-          reason: CriterionErrorReason.InvalidJSONPath
+          reason: CriterionEvaluationError.InvalidJSONPath
         });
       }
       throw error;

package/src/criterion/RegexCriterionEvaluator.cjs

@@ -6,7 +6,6 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 var _CriterionEvaluationError = _interopRequireDefault(require("../errors/CriterionEvaluationError.cjs"));
-var _CriterionErrorReason = _interopRequireDefault(require("./CriterionErrorReason.cjs"));
 /**
  * Evaluates a `regex` Arazzo criterion condition against a resolved context value.
  *
@@ -49,7 +48,7 @@ class RegexCriterionEvaluator {
         cause: error,
         condition,
         type: 'regex',
-        reason: _CriterionErrorReason.default.InvalidRegex
+        reason: _CriterionEvaluationError.default.InvalidRegex
       });
     }
     return regExp.test(this.#stringify(context));

package/src/criterion/RegexCriterionEvaluator.mjs

@@ -1,5 +1,4 @@
 import CriterionEvaluationError from "../errors/CriterionEvaluationError.mjs";
-import CriterionErrorReason from "./CriterionErrorReason.mjs";
 /**
  * Evaluates a `regex` Arazzo criterion condition against a resolved context value.
  *
@@ -42,7 +41,7 @@ class RegexCriterionEvaluator {
         cause: error,
         condition,
         type: 'regex',
-        reason: CriterionErrorReason.InvalidRegex
+        reason: CriterionEvaluationError.InvalidRegex
       });
     }
     return regExp.test(this.#stringify(context));

package/src/criterion/SimpleCriterionEvaluator.cjs

@@ -7,7 +7,6 @@ Object.defineProperty(exports, "__esModule", {
 exports.default = void 0;
 var _arazzoCriterion = require("@swaggerexpert/arazzo-criterion");
 var _CriterionEvaluationError = _interopRequireDefault(require("../errors/CriterionEvaluationError.cjs"));
-var _CriterionErrorReason = _interopRequireDefault(require("./CriterionErrorReason.cjs"));
 /**
  * Evaluates a `simple` Arazzo criterion condition.
  *
@@ -41,7 +40,7 @@ class SimpleCriterionEvaluator {
           cause: error,
           condition,
           type: 'simple',
-          reason: _CriterionErrorReason.default.InvalidSimple
+          reason: _CriterionEvaluationError.default.InvalidSimple
         });
       }
       throw error;

package/src/criterion/SimpleCriterionEvaluator.mjs

@@ -1,6 +1,5 @@
 import { evaluate as evaluateSimpleCriterion, ArazzoCriterionError } from '@swaggerexpert/arazzo-criterion';
 import CriterionEvaluationError from "../errors/CriterionEvaluationError.mjs";
-import CriterionErrorReason from "./CriterionErrorReason.mjs";
 /**
  * Evaluates a `simple` Arazzo criterion condition.
  *
@@ -34,7 +33,7 @@ class SimpleCriterionEvaluator {
           cause: error,
           condition,
           type: 'simple',
-          reason: CriterionErrorReason.InvalidSimple
+          reason: CriterionEvaluationError.InvalidSimple
         });
       }
       throw error;

package/src/criterion/XPathCriterionEvaluator.cjs

@@ -8,7 +8,6 @@ exports.default = void 0;
 var _fontoxpath = _interopRequireDefault(require("fontoxpath"));
 var _xmldom = require("@xmldom/xmldom");
 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.
 
@@ -55,7 +54,7 @@ class XPathCriterionEvaluator {
         cause: error,
         condition,
         type: 'xpath',
-        reason: _CriterionErrorReason.default.InvalidXPath
+        reason: _CriterionEvaluationError.default.InvalidXPath
       });
     }
   }
@@ -71,7 +70,7 @@ class XPathCriterionEvaluator {
       throw new _CriterionEvaluationError.default('xpath criterion context is not XML', {
         condition,
         type: 'xpath',
-        reason: _CriterionErrorReason.default.InvalidXPathContext
+        reason: _CriterionEvaluationError.default.InvalidXPathContext
       });
     }
 
@@ -91,7 +90,7 @@ class XPathCriterionEvaluator {
           cause: parseError,
           condition,
           type: 'xpath',
-          reason: _CriterionErrorReason.default.InvalidXPathContext
+          reason: _CriterionEvaluationError.default.InvalidXPathContext
         });
       }
       return document;
@@ -101,7 +100,7 @@ class XPathCriterionEvaluator {
         cause: error,
         condition,
         type: 'xpath',
-        reason: _CriterionErrorReason.default.InvalidXPathContext
+        reason: _CriterionEvaluationError.default.InvalidXPathContext
       });
     }
   }

package/src/criterion/XPathCriterionEvaluator.mjs

@@ -3,7 +3,6 @@
 import fontoxpath from 'fontoxpath';
 import { DOMParser } from '@xmldom/xmldom';
 import CriterionEvaluationError from "../errors/CriterionEvaluationError.mjs";
-import CriterionErrorReason from "./CriterionErrorReason.mjs";
 const {
   evaluateXPathToBoolean,
   evaluateXPath
@@ -47,7 +46,7 @@ class XPathCriterionEvaluator {
         cause: error,
         condition,
         type: 'xpath',
-        reason: CriterionErrorReason.InvalidXPath
+        reason: CriterionEvaluationError.InvalidXPath
       });
     }
   }
@@ -63,7 +62,7 @@ class XPathCriterionEvaluator {
       throw new CriterionEvaluationError('xpath criterion context is not XML', {
         condition,
         type: 'xpath',
-        reason: CriterionErrorReason.InvalidXPathContext
+        reason: CriterionEvaluationError.InvalidXPathContext
       });
     }
 
@@ -83,7 +82,7 @@ class XPathCriterionEvaluator {
           cause: parseError,
           condition,
           type: 'xpath',
-          reason: CriterionErrorReason.InvalidXPathContext
+          reason: CriterionEvaluationError.InvalidXPathContext
         });
       }
       return document;
@@ -93,7 +92,7 @@ class XPathCriterionEvaluator {
         cause: error,
         condition,
         type: 'xpath',
-        reason: CriterionErrorReason.InvalidXPathContext
+        reason: CriterionEvaluationError.InvalidXPathContext
       });
     }
   }

package/src/document/ArazzoDocument.cjs

@@ -6,11 +6,19 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 var _apidomCore = require("@speclynx/apidom-core");
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomJsonPointer = require("@speclynx/apidom-json-pointer");
 var _APIDocument = _interopRequireDefault(require("./APIDocument.cjs"));
+/**
+ * A workflow of an Arazzo document, as listed by
+ * {@link ArazzoDocument.listWorkflows}.
+ * @public
+ */
+
 /**
  * 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.
+ * bearer. The methods below are thin reads of those indexes.
  * @public
  */
 class ArazzoDocument extends _APIDocument.default {
@@ -46,6 +54,30 @@ class ArazzoDocument extends _APIDocument.default {
     return doc.type === 'arazzo';
   }
 
+  /**
+   * The workflows of this document that can be addressed by `workflowId`, in
+   * document order. Reads this document only: source descriptions are neither
+   * loaded nor listed.
+   */
+  listWorkflows() {
+    return [...this.workflowIndex].map(([workflowId, jsonPointer]) => {
+      const {
+        summary,
+        description
+      } = (0, _apidomJsonPointer.evaluate)(this.parseResult.api, jsonPointer);
+      return {
+        workflowId,
+        jsonPointer,
+        ...((0, _apidomDatamodel.isStringElement)(summary) && {
+          summary: (0, _apidomCore.toValue)(summary)
+        }),
+        ...((0, _apidomDatamodel.isStringElement)(description) && {
+          description: (0, _apidomCore.toValue)(description)
+        })
+      };
+    });
+  }
+
   /**
    * Resolves a source description name to its canonical URI — precomputed by
    * the provider, resolved against this document's base URI.

package/src/document/ArazzoDocument.mjs

@@ -1,9 +1,16 @@
 import { toValue } from '@speclynx/apidom-core';
+import { isStringElement } from '@speclynx/apidom-datamodel';
+import { evaluate } from '@speclynx/apidom-json-pointer';
 import APIDocument from "./APIDocument.mjs";
+/**
+ * A workflow of an Arazzo document, as listed by
+ * {@link ArazzoDocument.listWorkflows}.
+ * @public
+ */
 /**
  * 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.
+ * bearer. The methods below are thin reads of those indexes.
  * @public
  */
 class ArazzoDocument extends APIDocument {
@@ -39,6 +46,30 @@ class ArazzoDocument extends APIDocument {
     return doc.type === 'arazzo';
   }
 
+  /**
+   * The workflows of this document that can be addressed by `workflowId`, in
+   * document order. Reads this document only: source descriptions are neither
+   * loaded nor listed.
+   */
+  listWorkflows() {
+    return [...this.workflowIndex].map(([workflowId, jsonPointer]) => {
+      const {
+        summary,
+        description
+      } = evaluate(this.parseResult.api, jsonPointer);
+      return {
+        workflowId,
+        jsonPointer,
+        ...(isStringElement(summary) && {
+          summary: toValue(summary)
+        }),
+        ...(isStringElement(description) && {
+          description: toValue(description)
+        })
+      };
+    });
+  }
+
   /**
    * Resolves a source description name to its canonical URI — precomputed by
    * the provider, resolved against this document's base URI.

package/src/errors/CriterionError.cjs

@@ -6,6 +6,56 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 var _ArazzoRunnerError = _interopRequireDefault(require("./ArazzoRunnerError.cjs"));
-/** @public */
-class CriterionError extends _ArazzoRunnerError.default {}
+/**
+ * Carries a `reason`, one of the class's static reason fields.
+ *
+ * Every static on this class is a reason: {@link CriterionErrorReason} is
+ * derived from the class's own statics, so a non-reason static would join the
+ * union.
+ * @public
+ */
+class CriterionError extends _ArazzoRunnerError.default {
+  /** The element is not a Criterion Object. */
+  static InvalidCriterion = 'invalid-criterion';
+  /** The `condition` is missing or empty. */
+  static MissingCondition = 'missing-condition';
+  /** The `type` is present but unreadable. */
+  static InvalidType = 'invalid-type';
+  /** The `type` names no known criterion type. */
+  static UnknownType = 'unknown-type';
+  /** The expression type `version` is present but not a string. */
+  static InvalidVersion = 'invalid-version';
+  /** The expression type `version` is not the one this runner supports. */
+  static UnsupportedVersion = 'unsupported-version';
+  /** The `context` is not a runtime expression. */
+  static InvalidContext = 'invalid-context';
+  /** A `regex`, `jsonpath` or `xpath` criterion has no `context`. */
+  static MissingContext = 'missing-context';
+  /** The `simple` condition cannot be parsed. */
+  static InvalidSimple = 'invalid-simple';
+  /** The `regex` condition is not a valid regular expression. */
+  static InvalidRegex = 'invalid-regex';
+  /** The `jsonpath` condition is not a valid JSONPath query. */
+  static InvalidJSONPath = 'invalid-jsonpath';
+  /** The `xpath` condition is invalid or fails to evaluate. */
+  static InvalidXPath = 'invalid-xpath';
+  /** The resolved `xpath` context is not XML. */
+  static InvalidXPathContext = 'invalid-xpath-context';
+  constructor(message, options) {
+    super(message, options);
+  }
+}
+
+/**
+ * One of the reasons a {@link CriterionError} carries: a `CriterionError`
+ * static such as `CriterionError.InvalidRegex`.
+ *
+ * Structural reasons mark a criterion that is malformed as written; they are
+ * thrown as a plain `CriterionError`. Evaluation reasons (`InvalidSimple`,
+ * `InvalidRegex`, `InvalidJSONPath`, `InvalidXPath`, `InvalidXPathContext`) mark
+ * a condition that cannot be evaluated; they are thrown as a
+ * {@link CriterionEvaluationError}, which `CriterionEvaluator` turns into an
+ * unmet criterion.
+ * @public
+ */
 var _default = exports.default = CriterionError;

package/src/errors/CriterionError.mjs

@@ -1,4 +1,55 @@
 import ArazzoRunnerError from "./ArazzoRunnerError.mjs";
-/** @public */
-class CriterionError extends ArazzoRunnerError {}
+/**
+ * Carries a `reason`, one of the class's static reason fields.
+ *
+ * Every static on this class is a reason: {@link CriterionErrorReason} is
+ * derived from the class's own statics, so a non-reason static would join the
+ * union.
+ * @public
+ */
+class CriterionError extends ArazzoRunnerError {
+  /** The element is not a Criterion Object. */
+  static InvalidCriterion = 'invalid-criterion';
+  /** The `condition` is missing or empty. */
+  static MissingCondition = 'missing-condition';
+  /** The `type` is present but unreadable. */
+  static InvalidType = 'invalid-type';
+  /** The `type` names no known criterion type. */
+  static UnknownType = 'unknown-type';
+  /** The expression type `version` is present but not a string. */
+  static InvalidVersion = 'invalid-version';
+  /** The expression type `version` is not the one this runner supports. */
+  static UnsupportedVersion = 'unsupported-version';
+  /** The `context` is not a runtime expression. */
+  static InvalidContext = 'invalid-context';
+  /** A `regex`, `jsonpath` or `xpath` criterion has no `context`. */
+  static MissingContext = 'missing-context';
+  /** The `simple` condition cannot be parsed. */
+  static InvalidSimple = 'invalid-simple';
+  /** The `regex` condition is not a valid regular expression. */
+  static InvalidRegex = 'invalid-regex';
+  /** The `jsonpath` condition is not a valid JSONPath query. */
+  static InvalidJSONPath = 'invalid-jsonpath';
+  /** The `xpath` condition is invalid or fails to evaluate. */
+  static InvalidXPath = 'invalid-xpath';
+  /** The resolved `xpath` context is not XML. */
+  static InvalidXPathContext = 'invalid-xpath-context';
+  constructor(message, options) {
+    super(message, options);
+  }
+}
+
+/**
+ * One of the reasons a {@link CriterionError} carries: a `CriterionError`
+ * static such as `CriterionError.InvalidRegex`.
+ *
+ * Structural reasons mark a criterion that is malformed as written; they are
+ * thrown as a plain `CriterionError`. Evaluation reasons (`InvalidSimple`,
+ * `InvalidRegex`, `InvalidJSONPath`, `InvalidXPath`, `InvalidXPathContext`) mark
+ * a condition that cannot be evaluated; they are thrown as a
+ * {@link CriterionEvaluationError}, which `CriterionEvaluator` turns into an
+ * unmet criterion.
+ * @public
+ */
+
 export default CriterionError;