@usearazzo/runner 1.0.1-alpha.15 → 1.0.1-alpha.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usearazzo/runner",
-  "version": "1.0.1-alpha.15",
+  "version": "1.0.1-alpha.17",
   "description": "Runner for Arazzo Workflows.",
   "keywords": [
     "arazzo",
@@ -56,7 +56,7 @@
   "author": "Vladimir Gorej <vladimir.gorej@gmail.com>",
   "license": "Apache-2.0",
   "dependencies": {
-    "@babel/runtime-corejs3": "^8.0.7",
+    "@babel/runtime-corejs3": "^8.0.8",
     "@speclynx/apidom-core": "^6.1.0",
     "@speclynx/apidom-datamodel": "^6.1.0",
     "@speclynx/apidom-error": "^6.1.0",
@@ -73,8 +73,8 @@
     "@swaggerexpert/json-pointer": "^3.0.2",
     "@swaggerexpert/jsonpath": "^4.0.5",
     "@swaggerexpert/media-types": "^1.0.1",
-    "@usearazzo/parser": "1.0.1-alpha.15",
-    "@usearazzo/resolver": "1.0.1-alpha.15",
+    "@usearazzo/parser": "1.0.1-alpha.17",
+    "@usearazzo/resolver": "1.0.1-alpha.17",
     "@xmldom/xmldom": "^0.9.12",
     "fontoxpath": "^3.34.0",
     "ramda": "^0.32.0",
@@ -94,5 +94,5 @@
   "devDependencies": {
     "swagger-client": "^3.38.4"
   },
-  "gitHead": "0afacecfa7179fd95b07a8e4a5194a2d7d1c0687"
+  "gitHead": "92ccbcd1dff00a1744e6c0543db9d17ee5a91ef2"
 }

package/src/client/ParameterDelivery.cjs

@@ -4,10 +4,19 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = void 0;
+/**
+ * A key starting with an `in` value the client builds qualified keys from —
+ * the OpenAPI locations, including OpenAPI 2.0's `formData` and `body`. The
+ * client qualifies whatever `in` an operation declares, so a non-standard one
+ * is not covered.
+ */
+const QUALIFIED_KEY = /^(?:path|query|header|cookie|formData|body)\./;
+
 /**
  * The outcome of claiming a delivery key: `claimed` for a first claim,
- * `duplicate` when the same `(name, in)` parameter claims its key again, and
- * `collision` when a *different* parameter produces an already-claimed key.
+ * `duplicate` when the same `(name, in)` parameter claims its key again,
+ * `collision` when a *different* parameter produces an already-claimed key,
+ * and `misaddressed` when a bare key has the shape of a qualified one.
  * @internal
  */
 
@@ -47,8 +56,16 @@ exports.default = void 0;
  * alone identifies the claimant. A bare key and a qualified key sharing one
  * name are a collision too, even though the keys differ — the client consults
  * the bare name first for every declared parameter bearing it, so the bare
- * entry would silently capture the qualified one. What to do about a
- * collision is the caller's policy — the map only reports it.
+ * entry would silently capture the qualified one.
+ *
+ * A bare key that starts with a location the client qualifies keys with
+ * (`querystring` named `header.X-Foo`) is misaddressed even when it claims
+ * alone: the client matches it as the qualified key of every declared
+ * parameter that location and the rest of the name identify, so the value
+ * would reach the header `X-Foo` — and `OpenAPIOperationExecutor` reads such
+ * a key the same way when it delivers undeclared parameters. What to do about
+ * a collision or a misaddressed key is the caller's policy — the map only
+ * reports it.
  *
  * Diff this against the vendored bundle's lookup when bumping swagger-client.
  * @internal
@@ -71,10 +88,16 @@ class ParameterDelivery {
    * Only a `claimed` outcome entitles the caller to {@link ParameterDelivery.set}
    * the key; a `duplicate` means the same parameter already holds it, and a
    * `collision` means a different parameter does — on the same key, or across
-   * a bare/qualified pair sharing the name (see the class doc).
+   * a bare/qualified pair sharing the name (see the class doc). A
+   * `misaddressed` bare key is never claimed.
    */
   claim(location, name) {
     const key = ParameterDelivery.keyFor(location, name);
+    const bare = key === name;
+    if (bare && QUALIFIED_KEY.test(name)) return {
+      key,
+      outcome: 'misaddressed'
+    };
     const claimant = this.#claimedBy.get(key);
     if (claimant !== undefined) {
       return {
@@ -82,7 +105,6 @@ class ParameterDelivery {
         outcome: claimant === location ? 'duplicate' : 'collision'
       };
     }
-    const bare = key === name;
     if (bare ? this.#qualifiedNames.has(name) : this.#bareNames.has(name)) {
       return {
         key,

package/src/client/ParameterDelivery.mjs

@@ -1,7 +1,16 @@
+/**
+ * A key starting with an `in` value the client builds qualified keys from —
+ * the OpenAPI locations, including OpenAPI 2.0's `formData` and `body`. The
+ * client qualifies whatever `in` an operation declares, so a non-standard one
+ * is not covered.
+ */
+const QUALIFIED_KEY = /^(?:path|query|header|cookie|formData|body)\./;
+
 /**
  * The outcome of claiming a delivery key: `claimed` for a first claim,
- * `duplicate` when the same `(name, in)` parameter claims its key again, and
- * `collision` when a *different* parameter produces an already-claimed key.
+ * `duplicate` when the same `(name, in)` parameter claims its key again,
+ * `collision` when a *different* parameter produces an already-claimed key,
+ * and `misaddressed` when a bare key has the shape of a qualified one.
  * @internal
  */
 
@@ -41,8 +50,16 @@
  * alone identifies the claimant. A bare key and a qualified key sharing one
  * name are a collision too, even though the keys differ — the client consults
  * the bare name first for every declared parameter bearing it, so the bare
- * entry would silently capture the qualified one. What to do about a
- * collision is the caller's policy — the map only reports it.
+ * entry would silently capture the qualified one.
+ *
+ * A bare key that starts with a location the client qualifies keys with
+ * (`querystring` named `header.X-Foo`) is misaddressed even when it claims
+ * alone: the client matches it as the qualified key of every declared
+ * parameter that location and the rest of the name identify, so the value
+ * would reach the header `X-Foo` — and `OpenAPIOperationExecutor` reads such
+ * a key the same way when it delivers undeclared parameters. What to do about
+ * a collision or a misaddressed key is the caller's policy — the map only
+ * reports it.
  *
  * Diff this against the vendored bundle's lookup when bumping swagger-client.
  * @internal
@@ -65,10 +82,16 @@ class ParameterDelivery {
    * Only a `claimed` outcome entitles the caller to {@link ParameterDelivery.set}
    * the key; a `duplicate` means the same parameter already holds it, and a
    * `collision` means a different parameter does — on the same key, or across
-   * a bare/qualified pair sharing the name (see the class doc).
+   * a bare/qualified pair sharing the name (see the class doc). A
+   * `misaddressed` bare key is never claimed.
    */
   claim(location, name) {
     const key = ParameterDelivery.keyFor(location, name);
+    const bare = key === name;
+    if (bare && QUALIFIED_KEY.test(name)) return {
+      key,
+      outcome: 'misaddressed'
+    };
     const claimant = this.#claimedBy.get(key);
     if (claimant !== undefined) {
       return {
@@ -76,7 +99,6 @@ class ParameterDelivery {
         outcome: claimant === location ? 'duplicate' : 'collision'
       };
     }
-    const bare = key === name;
     if (bare ? this.#qualifiedNames.has(name) : this.#bareNames.has(name)) {
       return {
         key,

package/src/normalizer/ArazzoWorkflowNormalizer.cjs

@@ -159,23 +159,32 @@ class ArazzoWorkflowNormalizer {
   }
 
   /**
-   * Inherits the workflow's `successActions` / `failureActions` into each step
-   * that declares no `onSuccess` / `onFailure` of its own.
+   * Merges the workflow's `successActions` / `failureActions` into each step's
+   * `onSuccess` / `onFailure`.
    *
-   * Per Arazzo 1.0.1 both lists are "applicable for all steps described under
-   * this workflow", and a step's own list **overrides** the corresponding
-   * workflow one — wholesale, with no per-action merge, which is where this
-   * differs from the parameters above. Success and failure fall back
-   * independently: a step may override only its `onFailure` and still inherit
-   * the workflow's `successActions`.
+   * Per Arazzo both lists are "applicable for all steps described under this
+   * workflow" and "can be overridden at the step level but cannot be removed
+   * there". The required action `name` is what makes both halves hold: a
+   * step's action replaces the workflow action of the same `name`, and every
+   * workflow action the step does not name still applies. The effective list is
+   * the step's own actions in order, then the workflow actions it did not
+   * override, in theirs — order matters, as selection is first-match-wins on
+   * `criteria`. So a step with no list, or with `[]`, gets every workflow
+   * action. The step's own list is kept exactly as written, even a duplicate
+   * `name` in it, which the validator reports: inheritance only adds to it.
+   * Within the workflow's list the first action with a given `name` wins.
+   * Success and failure merge independently.
    *
-   * Presence is tested with `hasKey`, not truthiness: a step declaring an empty
-   * list (`onSuccess: []`) has *overridden* the default with an empty set of
-   * actions, not asked for one — it is skipped, as is a step whose `onSuccess`
-   * is present but not a list, for the same reason the parameters pass leaves a
-   * malformed list alone. Testing the key is also what makes the pass
-   * idempotent: after the first run the step has it, so a workflow reached again
-   * through the registry cache is skipped.
+   * An entry without a readable `name` (an unresolved Reusable Object, a
+   * scalar someone put in the list) neither overrides nor is overridden: it
+   * keeps its place, and is added only if that same element is not already in
+   * the list. A step whose `onSuccess` is present but not a list is left
+   * alone, for the same reason the parameters pass leaves a malformed list
+   * alone — overwriting it would erase what makes the document invalid.
+   *
+   * The pass is idempotent, so a workflow reached again through the registry
+   * cache is merged into once: on a second pass every inherited action is
+   * already in the step's list, under its own `name` or as the same element.
    *
    * Unlike parameters there is no step-kind filter — an action names a
    * transition within the workflow, which is as meaningful for a step targeting
@@ -202,13 +211,34 @@ class ArazzoWorkflowNormalizer {
     if (!inheritSuccess && !inheritFailure) return;
     for (const step of workflow.steps) {
       if (!(0, _apidomNsArazzo.isStepElement)(step)) continue;
-      if (inheritSuccess && !step.hasKey('onSuccess')) {
-        step.onSuccess = new _apidomNsArazzo.StepOnSuccessElement([...successActions]);
+      if (inheritSuccess && (!step.hasKey('onSuccess') || (0, _apidomDatamodel.isArrayElement)(step.onSuccess))) {
+        step.onSuccess = new _apidomNsArazzo.StepOnSuccessElement(ArazzoWorkflowNormalizer.#mergeActions([...(step.onSuccess ?? [])], [...successActions]));
+      }
+      if (inheritFailure && (!step.hasKey('onFailure') || (0, _apidomDatamodel.isArrayElement)(step.onFailure))) {
+        step.onFailure = new _apidomNsArazzo.StepOnFailureElement(ArazzoWorkflowNormalizer.#mergeActions([...(step.onFailure ?? [])], [...failureActions]));
       }
-      if (inheritFailure && !step.hasKey('onFailure')) {
-        step.onFailure = new _apidomNsArazzo.StepOnFailureElement([...failureActions]);
+    }
+  }
+
+  /**
+   * The step's actions as written, followed by each workflow action whose
+   * `name` neither the step nor an earlier workflow action carries; a nameless
+   * workflow entry is added unless that same element is already present.
+   */
+  static #mergeActions(own, inherited) {
+    const nameOf = action => (0, _apidomDatamodel.isObjectElement)(action) ? (0, _apidomCore.toValue)(action.get('name')) : undefined;
+    const names = new Set(own.map(nameOf));
+    const merged = [...own];
+    for (const action of inherited) {
+      const name = nameOf(action);
+      if (typeof name !== 'string') {
+        if (!merged.includes(action)) merged.push(action);
+      } else if (!names.has(name)) {
+        names.add(name);
+        merged.push(action);
       }
     }
+    return merged;
   }
 }
 var _default = exports.default = ArazzoWorkflowNormalizer;

package/src/normalizer/ArazzoWorkflowNormalizer.mjs

@@ -1,7 +1,7 @@
 import { uniqWith } from 'ramda';
 import { isParameterElement, isStepElement, StepParametersElement, StepOnSuccessElement, StepOnFailureElement } from '@speclynx/apidom-ns-arazzo-1';
 import { toValue } from '@speclynx/apidom-core';
-import { isArrayElement, isStringElement } from '@speclynx/apidom-datamodel';
+import { isArrayElement, isObjectElement, isStringElement } from '@speclynx/apidom-datamodel';
 import { dereferenceArazzoElement, defaultDereferenceArazzoOptions } from '@usearazzo/resolver';
 import { mergeOptions } from '@speclynx/apidom-reference/configuration/empty';
 import ParameterIdentity from "../document/ParameterIdentity.mjs";
@@ -151,23 +151,32 @@ class ArazzoWorkflowNormalizer {
   }
 
   /**
-   * Inherits the workflow's `successActions` / `failureActions` into each step
-   * that declares no `onSuccess` / `onFailure` of its own.
+   * Merges the workflow's `successActions` / `failureActions` into each step's
+   * `onSuccess` / `onFailure`.
    *
-   * Per Arazzo 1.0.1 both lists are "applicable for all steps described under
-   * this workflow", and a step's own list **overrides** the corresponding
-   * workflow one — wholesale, with no per-action merge, which is where this
-   * differs from the parameters above. Success and failure fall back
-   * independently: a step may override only its `onFailure` and still inherit
-   * the workflow's `successActions`.
+   * Per Arazzo both lists are "applicable for all steps described under this
+   * workflow" and "can be overridden at the step level but cannot be removed
+   * there". The required action `name` is what makes both halves hold: a
+   * step's action replaces the workflow action of the same `name`, and every
+   * workflow action the step does not name still applies. The effective list is
+   * the step's own actions in order, then the workflow actions it did not
+   * override, in theirs — order matters, as selection is first-match-wins on
+   * `criteria`. So a step with no list, or with `[]`, gets every workflow
+   * action. The step's own list is kept exactly as written, even a duplicate
+   * `name` in it, which the validator reports: inheritance only adds to it.
+   * Within the workflow's list the first action with a given `name` wins.
+   * Success and failure merge independently.
    *
-   * Presence is tested with `hasKey`, not truthiness: a step declaring an empty
-   * list (`onSuccess: []`) has *overridden* the default with an empty set of
-   * actions, not asked for one — it is skipped, as is a step whose `onSuccess`
-   * is present but not a list, for the same reason the parameters pass leaves a
-   * malformed list alone. Testing the key is also what makes the pass
-   * idempotent: after the first run the step has it, so a workflow reached again
-   * through the registry cache is skipped.
+   * An entry without a readable `name` (an unresolved Reusable Object, a
+   * scalar someone put in the list) neither overrides nor is overridden: it
+   * keeps its place, and is added only if that same element is not already in
+   * the list. A step whose `onSuccess` is present but not a list is left
+   * alone, for the same reason the parameters pass leaves a malformed list
+   * alone — overwriting it would erase what makes the document invalid.
+   *
+   * The pass is idempotent, so a workflow reached again through the registry
+   * cache is merged into once: on a second pass every inherited action is
+   * already in the step's list, under its own `name` or as the same element.
    *
    * Unlike parameters there is no step-kind filter — an action names a
    * transition within the workflow, which is as meaningful for a step targeting
@@ -194,13 +203,34 @@ class ArazzoWorkflowNormalizer {
     if (!inheritSuccess && !inheritFailure) return;
     for (const step of workflow.steps) {
       if (!isStepElement(step)) continue;
-      if (inheritSuccess && !step.hasKey('onSuccess')) {
-        step.onSuccess = new StepOnSuccessElement([...successActions]);
+      if (inheritSuccess && (!step.hasKey('onSuccess') || isArrayElement(step.onSuccess))) {
+        step.onSuccess = new StepOnSuccessElement(ArazzoWorkflowNormalizer.#mergeActions([...(step.onSuccess ?? [])], [...successActions]));
+      }
+      if (inheritFailure && (!step.hasKey('onFailure') || isArrayElement(step.onFailure))) {
+        step.onFailure = new StepOnFailureElement(ArazzoWorkflowNormalizer.#mergeActions([...(step.onFailure ?? [])], [...failureActions]));
       }
-      if (inheritFailure && !step.hasKey('onFailure')) {
-        step.onFailure = new StepOnFailureElement([...failureActions]);
+    }
+  }
+
+  /**
+   * The step's actions as written, followed by each workflow action whose
+   * `name` neither the step nor an earlier workflow action carries; a nameless
+   * workflow entry is added unless that same element is already present.
+   */
+  static #mergeActions(own, inherited) {
+    const nameOf = action => isObjectElement(action) ? toValue(action.get('name')) : undefined;
+    const names = new Set(own.map(nameOf));
+    const merged = [...own];
+    for (const action of inherited) {
+      const name = nameOf(action);
+      if (typeof name !== 'string') {
+        if (!merged.includes(action)) merged.push(action);
+      } else if (!names.has(name)) {
+        names.add(name);
+        merged.push(action);
       }
     }
+    return merged;
   }
 }
 export default ArazzoWorkflowNormalizer;

package/src/resolver/OpenAPIOperationParameterResolver.cjs

@@ -41,12 +41,15 @@ var _StepParameterResolver = _interopRequireDefault(require("./StepParameterReso
  * against an OpenAPI 2.0 operation, bypassing the step's `requestBody`, while
  * an unknown location reaches nothing at all. And two *different* parameters the
  * map reports as colliding cannot both be delivered, so a collision throws
- * rather than silently dropping one — whether they collide on one key (the
- * scheme is not injective: a `querystring` parameter named `header.token` and
- * a header parameter named `token` both produce `header.token`) or across a
- * bare/qualified pair sharing a name (a `querystring` `token` next to a
- * header `token`), where the client would consult the bare name first and
- * silently capture the qualified value.
+ * rather than silently dropping one — a bare/qualified pair sharing a name (a
+ * `querystring` `token` next to a header `token`), where the client would
+ * consult the bare name first and silently capture the qualified value. A
+ * `querystring` parameter whose name starts with a location the client
+ * qualifies keys with (`header.X-Foo`) throws even alone: the client would
+ * match its bare key as the qualified key of a declared header `X-Foo` and
+ * deliver it there. The same check rejects it, in either order, next to a
+ * header parameter `X-Foo` producing that very key — the scheme is not
+ * injective, so the two could otherwise collide on one key.
  * @public
  */
 class OpenAPIOperationParameterResolver extends _StepParameterResolver.default {
@@ -113,8 +116,9 @@ class OpenAPIOperationParameterResolver extends _StepParameterResolver.default {
       } = delivery.claim(location, name);
       // the same parameter declared again: the earlier, more specific one won
       if (outcome === 'duplicate') continue;
-      if (outcome === 'collision') {
-        throw new _ResolverError.default(`Parameter "${name}" (in: ${location}) collides with another parameter on the ` + `delivery key "${key}" and cannot be delivered unambiguously`, {
+      if (outcome !== 'claimed') {
+        const why = outcome === 'collision' ? `collides with another parameter on the delivery key "${key}"` : 'has a name the client reads as the delivery key of another location';
+        throw new _ResolverError.default(`Parameter "${name}" (in: ${location}) ${why} and cannot be delivered unambiguously`, {
           ...scope,
           target: name,
           reason: 'ambiguous-delivery'

package/src/resolver/OpenAPIOperationParameterResolver.mjs

@@ -34,12 +34,15 @@ import StepParameterResolver from "./StepParameterResolver.mjs";
  * against an OpenAPI 2.0 operation, bypassing the step's `requestBody`, while
  * an unknown location reaches nothing at all. And two *different* parameters the
  * map reports as colliding cannot both be delivered, so a collision throws
- * rather than silently dropping one — whether they collide on one key (the
- * scheme is not injective: a `querystring` parameter named `header.token` and
- * a header parameter named `token` both produce `header.token`) or across a
- * bare/qualified pair sharing a name (a `querystring` `token` next to a
- * header `token`), where the client would consult the bare name first and
- * silently capture the qualified value.
+ * rather than silently dropping one — a bare/qualified pair sharing a name (a
+ * `querystring` `token` next to a header `token`), where the client would
+ * consult the bare name first and silently capture the qualified value. A
+ * `querystring` parameter whose name starts with a location the client
+ * qualifies keys with (`header.X-Foo`) throws even alone: the client would
+ * match its bare key as the qualified key of a declared header `X-Foo` and
+ * deliver it there. The same check rejects it, in either order, next to a
+ * header parameter `X-Foo` producing that very key — the scheme is not
+ * injective, so the two could otherwise collide on one key.
  * @public
  */
 class OpenAPIOperationParameterResolver extends StepParameterResolver {
@@ -106,8 +109,9 @@ class OpenAPIOperationParameterResolver extends StepParameterResolver {
       } = delivery.claim(location, name);
       // the same parameter declared again: the earlier, more specific one won
       if (outcome === 'duplicate') continue;
-      if (outcome === 'collision') {
-        throw new ResolverError(`Parameter "${name}" (in: ${location}) collides with another parameter on the ` + `delivery key "${key}" and cannot be delivered unambiguously`, {
+      if (outcome !== 'claimed') {
+        const why = outcome === 'collision' ? `collides with another parameter on the delivery key "${key}"` : 'has a name the client reads as the delivery key of another location';
+        throw new ResolverError(`Parameter "${name}" (in: ${location}) ${why} and cannot be delivered unambiguously`, {
           ...scope,
           target: name,
           reason: 'ambiguous-delivery'

package/types/runner.d.ts

@@ -1202,12 +1202,15 @@ export declare interface OpenAPIOperationNormalizerOptions {
  * against an OpenAPI 2.0 operation, bypassing the step's `requestBody`, while
  * an unknown location reaches nothing at all. And two *different* parameters the
  * map reports as colliding cannot both be delivered, so a collision throws
- * rather than silently dropping one — whether they collide on one key (the
- * scheme is not injective: a `querystring` parameter named `header.token` and
- * a header parameter named `token` both produce `header.token`) or across a
- * bare/qualified pair sharing a name (a `querystring` `token` next to a
- * header `token`), where the client would consult the bare name first and
- * silently capture the qualified value.
+ * rather than silently dropping one — a bare/qualified pair sharing a name (a
+ * `querystring` `token` next to a header `token`), where the client would
+ * consult the bare name first and silently capture the qualified value. A
+ * `querystring` parameter whose name starts with a location the client
+ * qualifies keys with (`header.X-Foo`) throws even alone: the client would
+ * match its bare key as the qualified key of a declared header `X-Foo` and
+ * deliver it there. The same check rejects it, in either order, next to a
+ * header parameter `X-Foo` producing that very key — the scheme is not
+ * injective, so the two could otherwise collide on one key.
  * @public
  */
 export declare class OpenAPIOperationParameterResolver extends StepParameterResolver {