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

package/src/executor/OpenAPIOperationExecutor.mjs

@@ -0,0 +1,446 @@
+import { toValue } from '@speclynx/apidom-core';
+import { isArrayElement, isObjectElement } from '@speclynx/apidom-datamodel';
+import { url as urlUtils } from '@speclynx/apidom-reference/configuration/empty';
+import { isSwaggerElement, isParameterElement } from '@speclynx/apidom-ns-openapi-2';
+import { isPlainObject } from 'ramda-adjunct';
+
+// @ts-expect-error vendored swagger-client bundle has no type declarations
+import { buildRequest, idFromPathMethodLegacy } from '../vendor/swagger-client.mjs';
+import ParameterDelivery from "../client/ParameterDelivery.mjs";
+import httpClientFetch from "../client/HTTPClientFetch.mjs";
+import OpenAPIOperationResponseNormalizer from "../client/OpenAPIOperationResponseNormalizer.mjs";
+import OpenAPIOperationExtractor from "../extractor/OpenAPIOperationExtractor.mjs";
+import OpenAPIOperationNormalizer from "../normalizer/OpenAPIOperationNormalizer.mjs";
+import OpenAPIDocumentAssembler from "../assembler/OpenAPIDocumentAssembler.mjs";
+import ClientError from "../errors/ClientError.mjs";
+/**
+ * Decorates the built request before it is handed to the {@link HTTPClient}.
+ *
+ * Receives the finalized {@link OpenAPIOperationRequest} and may mutate it in
+ * place or return a replacement; returning nothing keeps the received request.
+ * May be synchronous or asynchronous.
+ * @public
+ */
+/**
+ * Options for executing an OpenAPI operation.
+ *
+ * All fields are forwarded to the vendored swagger-client `buildRequest`
+ * (which owns parameter serialization, security application, and server URL
+ * resolution), except `requestInterceptor`, which the executor runs between
+ * building the request and sending it.
+ *
+ * Typed here are the options the runner itself drives and the ones callers
+ * routinely reach for. The rest of `buildRequest`'s surface (`securities`,
+ * `scheme`, `parameterBuilders`, `attachContentTypeForEmptyPayload`, …) is
+ * deliberately left untyped and passes through the bag's open tail unchanged —
+ * see {@link OpenAPIOperationExecuteOptionsBag}. Authentication in particular
+ * is not modeled: Arazzo is auth-agnostic, so credentials are applied with a
+ * {@link RequestInterceptor}.
+ * @public
+ */
+/**
+ * The execute options forwarded to {@link OpenAPIOperationExecutor.execute}.
+ *
+ * The {@link OpenAPIOperationExecuteOptions} fields are surfaced for
+ * type-checked callers, while the open `Record` tail keeps the bag opaque so
+ * the rest of `buildRequest`'s surface (`scheme`, `parameterBuilders`,
+ * `attachContentTypeForEmptyPayload`, …) passes through untouched.
+ *
+ * Nothing routine belongs in the tail. Credentials go through a
+ * {@link RequestInterceptor} and `server` covers every case that once needed a
+ * `contextUrl`, so reaching for either of those here means an edge case: tests
+ * standing in for a document fetched over HTTP, or credentials applied from the
+ * document's own security schemes.
+ *
+ * Two kinds of entry are inert rather than honored, since the executor owns
+ * what they used to control. The operation target always comes from the
+ * locator, so `operationId`/`operationPath` have no effect; and the options
+ * only swagger-client's `execute()` ever read — `userFetch` and
+ * `responseInterceptor`, which the runner replaces with `httpClient` and
+ * `responseNormalizer` — reach `buildRequest` but nothing acts on them.
+ * @public
+ */
+/**
+ * Options for the OpenAPIOperationExecutor.
+ * @public
+ */
+/**
+ * Executes a single OpenAPI operation named by a canonical
+ * {@link OpenAPIOperationLocator}.
+ *
+ * The pipeline extracts the operation from its owning document, normalizes it,
+ * assembles a minimal standalone OpenAPI document containing just that
+ * operation, builds the HTTP request with the vendored swagger-client
+ * `buildRequest` (parameter serialization, securities, server resolution),
+ * sends it through the pluggable {@link HTTPClient}, and normalizes the raw
+ * `Response` into the runner's response model. A non-2xx status is a valid
+ * outcome (judged by a step's `successCriteria`) and is returned, never
+ * thrown; a transport failure is wrapped as a {@link ClientError}.
+ *
+ * The executor is Arazzo-agnostic: it neither locates the operation (that is
+ * the operation locator normalizer's concern) nor resolves parameters or
+ * request bodies from runtime expressions (the step executor's concern). It
+ * receives an already-resolved locator and an opaque bag of execute options,
+ * and returns the normalized operation response carrying the request that was
+ * actually sent, so `$url` / `$method` / `$request.*` can be evaluated after
+ * execution.
+ * @public
+ */
+class OpenAPIOperationExecutor {
+  #httpClient;
+  #requestInterceptor;
+  #responseNormalizer;
+  #operationExtractor;
+  #operationNormalizer;
+  #documentAssembler;
+  constructor(options = {}) {
+    this.#httpClient = options.httpClient ?? httpClientFetch;
+    this.#requestInterceptor = options.requestInterceptor;
+    this.#responseNormalizer = options.responseNormalizer ?? new OpenAPIOperationResponseNormalizer();
+    this.#operationExtractor = options.operationExtractor ?? new OpenAPIOperationExtractor();
+    this.#operationNormalizer = options.operationNormalizer ?? new OpenAPIOperationNormalizer();
+    this.#documentAssembler = options.documentAssembler ?? new OpenAPIDocumentAssembler();
+  }
+
+  /**
+   * Executes the located operation, returning the normalized operation
+   * response.
+   *
+   * `executeOptions` is an opaque bag of `buildRequest` options (e.g. resolved
+   * `parameters`, a `requestBody` and its `requestContentType`, or a `server`).
+   * The operation target always takes precedence over it: the
+   * locator's JSON Pointer selects the operation in the assembled document, so
+   * `operationId`/`operationPath` entries in the bag cannot hijack the
+   * operation.
+   */
+  async execute(locator, executeOptions = {}) {
+    // extraction validates the locator first: a pointer naming anything but an
+    // operation would otherwise crash inside normalization
+    const operation = this.#operationExtractor.extractByPointer(locator.document, locator.jsonPointer);
+    // the legacy id (`{method}-{path}`) matches regardless of an explicit
+    // `operationId` in the assembled document
+    const operationId = idFromPathMethodLegacy(toValue(operation.meta.get('path')), toValue(operation.meta.get('http-method')));
+    const normalizedOperation = await this.#operationNormalizer.normalize(operation, locator.document);
+    const assembled = this.#documentAssembler.assemble(normalizedOperation, locator.document);
+
+    // the interceptor is consumed here, and the target always comes from the
+    // locator, so both operation keys are dropped rather than rest
+    const {
+      requestInterceptor,
+      operationId: _,
+      operationPath: __,
+      ...rest
+    } = executeOptions;
+
+    // each step derives the next options rather than editing in place
+    const withServer = this.#applyServerOptions(rest, normalizedOperation, locator.document);
+    const withBody = this.#adaptRequestBody(withServer, normalizedOperation, locator.document, locator.jsonPointer);
+    const buildOptions = this.#adaptRequestContentType(withBody, normalizedOperation, locator.document, locator.jsonPointer);
+    let request;
+    try {
+      const spec = assembled.toJSON();
+      request = buildRequest({
+        ...buildOptions,
+        spec,
+        operationId
+      });
+    } catch (error) {
+      throw new ClientError('Failed to build request for OpenAPI operation', {
+        operationPath: locator.jsonPointer,
+        cause: error
+      });
+    }
+
+    // a differing value means #adaptRequestContentType swapped the authored
+    // media type for the declared one so the body would attach; the header
+    // still goes out as authored, parameters and all
+    const authoredContentType = executeOptions.requestContentType;
+    if (typeof authoredContentType === 'string' && buildOptions.requestContentType !== authoredContentType) {
+      request.headers['Content-Type'] = authoredContentType;
+    }
+    request = await this.#finalizeRequest(request, requestInterceptor);
+
+    // capture the request as sent, so `$url` / `$method` / `$request.*` can be
+    // evaluated after execution; headers are copied so a transport-side
+    // mutation cannot rewrite the record
+    const requestInfo = {
+      url: request.url,
+      method: request.method,
+      headers: {
+        ...request.headers
+      },
+      body: request.body
+    };
+    let rawResponse;
+    try {
+      rawResponse = await this.#httpClient(request);
+    } catch (error) {
+      throw new ClientError('OpenAPI operation request failed', {
+        operationPath: locator.jsonPointer,
+        cause: error
+      });
+    }
+    return this.#responseNormalizer.normalize(rawResponse, requestInfo);
+  }
+
+  /**
+   * Derives where the request is sent, returning the options to build with.
+   *
+   * swagger-client already selects a declared server, substitutes its variables
+   * and resolves relative URLs — the one thing it gets wrong is what to do with
+   * a `server` matching nothing it declared, which it silently swaps for the
+   * first declared server. Here that value becomes an override instead: the URL
+   * you name is the URL that is called, whatever the document declares. Passing
+   * it as `baseURL` bypasses swagger-client's own server resolution, which also
+   * makes `server` work on Swagger 2.0, where it is otherwise ignored.
+   *
+   * A relative server resolves against the URL the document was loaded from,
+   * which is what `contextUrl` means, so it is derived rather than asked for.
+   * Only an HTTP(S) document URL qualifies. Swagger 2.0 falls back to the
+   * context URL's protocol when the document declares no `schemes`, so a `file:`
+   * URL would yield `file://host/basePath` instead of `http://…`. The registry
+   * normalizes `file:` URIs to bare filesystem paths, which carry no protocol
+   * and are harmless, so this is a guard on the invariant rather than on a
+   * reachable state today. A caller-supplied `contextUrl` still wins, for
+   * resolving against somewhere the document did not come from.
+   */
+  #applyServerOptions(buildOptions, operation, document) {
+    const resolved = buildOptions.contextUrl === undefined && urlUtils.isHttpUrl(document.uri) ? {
+      ...buildOptions,
+      contextUrl: document.uri
+    } : buildOptions;
+    const {
+      server,
+      ...withoutServer
+    } = resolved;
+    if (typeof server !== 'string') return resolved;
+
+    // the operation normalizer has already inherited servers down from the
+    // document root, including the spec's default `[{ url: '/' }]`. spread into
+    // a real array rather than using ArrayElement's own find(), which returns an
+    // empty ArrayElement on a miss — truthy, so every server would look declared.
+    // the members are Server elements, but isObjectElement keeps this one code
+    // path valid for every version: isServerElement is per-namespace, and the
+    // 3.1 one rejects 3.0 servers
+    const servers = operation.get('servers');
+    const declared = isArrayElement(servers) ? [...servers] : [];
+    const isDeclared = declared.some(candidate => isObjectElement(candidate) && toValue(candidate.get('url')) === server);
+    if (isDeclared) return resolved;
+    const baseURL = urlUtils.hasProtocol(server) ? server : urlUtils.resolve(resolved.contextUrl ?? '', server);
+
+    // buildRequest concatenates the base and the path verbatim, so a trailing
+    // slash would double up. swagger-client trims one in its own resolution too
+    return {
+      ...withoutServer,
+      baseURL: baseURL.replace(/\/$/, '')
+    };
+  }
+
+  /**
+   * Reconciles the requested body media type with the ones the operation
+   * declares, returning the options to build with. A rewritten
+   * `requestContentType` is what tells `execute` to restore the authored value
+   * onto the header afterwards.
+   *
+   * swagger-client attaches the body only when `requestContentType` is an exact
+   * key of `requestBody.content`, and otherwise drops the body *and* the header
+   * without a word. Media types are richer than that: they carry optional
+   * parameters and their names are case-insensitive, so the Arazzo
+   * `application/json; charset=utf-8` and `Application/JSON` both name a
+   * declared `application/json`. Both are matched here, the request is built
+   * under the declared spelling, and the authored value is restored onto the
+   * header afterwards. A type naming nothing declared is an authoring error and
+   * is raised rather than turned into an empty request.
+   *
+   * Only OpenAPI 3.x declares media types this way. A Swagger 2.0 operation has
+   * no `requestBody` to check against, so its content type passes through for
+   * `consumes` to govern.
+   */
+  #adaptRequestContentType(buildOptions, operation, document, jsonPointer) {
+    const requested = buildOptions.requestContentType;
+    if (typeof requested !== 'string' || buildOptions.requestBody === undefined) {
+      return buildOptions;
+    }
+    if (isSwaggerElement(document.parseResult.api)) return buildOptions;
+    const requestBody = operation.get('requestBody');
+    const content = isObjectElement(requestBody) ? requestBody.get('content') : undefined;
+    if (!isObjectElement(content)) {
+      throw new ClientError(`Request body media type "${requested}" cannot be sent: the operation declares ` + 'no request body content. Omit the content type to send the payload as-is', {
+        operationPath: jsonPointer
+      });
+    }
+    const declared = content.keys();
+    if (declared.includes(requested)) return buildOptions;
+
+    // media type names are case-insensitive and their parameters are not part of
+    // the name, so both are normalized away before matching
+    const baseType = requested.split(';')[0].trim().toLowerCase();
+    const [type] = baseType.split('/');
+    const covers = (mediaType, by) => {
+      const candidate = mediaType.toLowerCase();
+      if (by === 'exact') return candidate === baseType;
+      if (by === 'subtype') return candidate === `${type}/*`;
+      return candidate === '*/*';
+    };
+
+    // a form media type decides how the body is encoded, and buildRequest applies
+    // that encoding only for an exactly declared type. matching one against a
+    // range would put a JSON body behind a form Content-Type
+    const isFormEncoded = baseType === 'application/x-www-form-urlencoded' || baseType === 'multipart/form-data';
+
+    // otherwise a declared range covers a concrete type, so `*/*` (what several
+    // generators emit by default) accepts anything; the most specific wins
+    const exact = declared.find(mediaType => covers(mediaType, 'exact'));
+    const match = exact ?? (isFormEncoded ? undefined : declared.find(mediaType => covers(mediaType, 'subtype')) ?? declared.find(mediaType => covers(mediaType, 'any')));
+    if (match === undefined) {
+      throw new ClientError(isFormEncoded ? `Request body media type "${requested}" must be declared by the operation exactly, ` + `since it decides how the body is encoded (declared: [${declared.join(', ')}])` : `Request body media type "${requested}" is not declared by the operation ` + `(declared: [${declared.join(', ')}])`, {
+        operationPath: jsonPointer
+      });
+    }
+    return {
+      ...buildOptions,
+      requestContentType: match
+    };
+  }
+
+  /**
+   * Routes a request body through the convention the target OpenAPI version
+   * uses, leaving OpenAPI 3.x calls untouched.
+   *
+   * Swagger 2.0 has no request body concept — the payload is an ordinary
+   * parameter declared `in: body`, or a set of `in: formData` ones — so it must
+   * travel through `parameters` under the names the operation declares. Arazzo
+   * cannot express that itself (its parameter `in` allows only `path`, `query`,
+   * `querystring`, `header`, and `cookie`), which is why the translation lives
+   * here, where the assembled document has those parameters dereferenced and
+   * inherited.
+   *
+   * The payload travels under {@link ParameterDelivery} keys
+   * (`body.{name}`, `formData.{name}`), never bare names: a bare key would
+   * capture a same-named parameter in another location — 2.0 legally declares
+   * e.g. `petId` in `path` and in `formData` at once — per the lookup order
+   * documented on {@link ParameterDelivery}.
+   *
+   * A *bare* `parameters` entry bearing a payload target's name is rejected
+   * with {@link ClientError} rather than resolved either way: before the
+   * qualified keys the payload silently overwrote it, after them the bare key
+   * would silently outrank the payload at the client's bare-first lookup —
+   * both wrong for somebody, so the ambiguity is reported instead. Such an
+   * entry can come from a direct caller mixing bare parameters with a request
+   * body, or from the runner's own pipeline: the parameter resolver keeps a
+   * `querystring` parameter under its bare name.
+   */
+  #adaptRequestBody(buildOptions, operation, document, jsonPointer) {
+    if (!isSwaggerElement(document.parseResult.api) || buildOptions.requestBody === undefined) {
+      return buildOptions;
+    }
+    const {
+      requestBody,
+      parameters: given,
+      ...rest
+    } = buildOptions;
+    const callerParameters = given;
+    // an operation declaring none leaves `parameters` absent rather than empty,
+    // and that case still has to reach the throw below
+    const declared = operation.parameters;
+    const parameters = isArrayElement(declared) ? [...declared.filter(isParameterElement)] : [];
+
+    // the body parameter's name is arbitrary, so the payload wins over a
+    // same-keyed entry the caller supplied
+    const body = parameters.find(parameter => toValue(parameter.in) === 'body');
+    if (body !== undefined) {
+      const name = toValue(body.name);
+      this.#rejectBarePayloadConflicts(callerParameters, [name], jsonPointer);
+      return {
+        ...rest,
+        parameters: {
+          ...callerParameters,
+          [ParameterDelivery.keyFor('body', name)]: requestBody
+        }
+      };
+    }
+
+    // formData models each field as its own parameter, so the payload's keys
+    // are the parameter names; buildRequest reports any that do not match
+    const hasForm = parameters.some(parameter => toValue(parameter.in) === 'formData');
+    if (hasForm) {
+      if (!isPlainObject(requestBody)) {
+        throw new ClientError('Request body cannot be sent: the OpenAPI 2.0 operation carries it in "formData" ' + 'parameters, so the payload must be an object keyed by their names', {
+          operationPath: jsonPointer
+        });
+      }
+      const payload = requestBody;
+      this.#rejectBarePayloadConflicts(callerParameters, Object.keys(payload), jsonPointer);
+      const merged = {
+        ...callerParameters
+      };
+      for (const [field, value] of Object.entries(payload)) {
+        merged[ParameterDelivery.keyFor('formData', field)] = value;
+      }
+      return {
+        ...rest,
+        parameters: merged
+      };
+    }
+    throw new ClientError('Request body cannot be sent: the OpenAPI 2.0 operation declares no "body" or ' + '"formData" parameter to carry it', {
+      operationPath: jsonPointer
+    });
+  }
+
+  /**
+   * Rejects bare `parameters` entries bearing the names the payload is about
+   * to be delivered under — the client consults bare names before qualified
+   * keys, so such an entry would silently displace the request body (see
+   * {@link OpenAPIOperationExecutor.#adaptRequestBody}).
+   */
+  #rejectBarePayloadConflicts(callerParameters, payloadNames, jsonPointer) {
+    if (callerParameters === undefined) return;
+    const conflicts = payloadNames.filter(name => Object.hasOwn(callerParameters, name));
+    if (conflicts.length === 0) return;
+    throw new ClientError(`Request body cannot be sent: bare parameter ${conflicts.length === 1 ? 'entry' : 'entries'} ` + `[${conflicts.join(', ')}] would displace the payload at delivery. Supply the ` + `parameter under its "{in}.{name}" key, or drop the duplicate`, {
+      operationPath: jsonPointer
+    });
+  }
+
+  /**
+   * Applies the wire-level fixups swagger-client performs between building a
+   * request and fetching it, and runs the request interceptors: the
+   * executor-level one first, the per-call one from the options bag second.
+   *
+   * Ported rather than imported: upstream keeps them inline in `execute()` and
+   * `http()`, which also fetch and throw on a non-2xx. Diff against those two
+   * when bumping swagger-client.
+   */
+  async #finalizeRequest(request, perCallInterceptor) {
+    let finalized = request;
+
+    // JSON-encode plain-object and array bodies, exactly as swagger-client's
+    // execute() does before handing the request to its transport
+    if (finalized.body && (isPlainObject(finalized.body) || Array.isArray(finalized.body))) {
+      finalized.body = JSON.stringify(finalized.body);
+    }
+
+    // an embedded newline makes a header value invalid per the Fetch standard,
+    // so fetch throws a TypeError before sending anything. squashing repairs it,
+    // and since the request is captured after this, the record shows the value
+    // that actually went out
+    Object.keys(finalized.headers).forEach(headerName => {
+      const value = finalized.headers[headerName];
+      if (typeof value === 'string') {
+        finalized.headers[headerName] = value.replace(/\n+/g, ' ');
+      }
+    });
+    finalized = (await this.#requestInterceptor?.(finalized)) ?? finalized;
+    finalized = (await perCallInterceptor?.(finalized)) ?? finalized;
+
+    // for multipart/form-data, remove the built content-type so the transport
+    // sets one carrying the correct boundary
+    const contentType = finalized.headers['content-type'] ?? finalized.headers['Content-Type'];
+    if (typeof contentType === 'string' && /multipart\/form-data/i.test(contentType)) {
+      delete finalized.headers['content-type'];
+      delete finalized.headers['Content-Type'];
+    }
+    return finalized;
+  }
+}
+export default OpenAPIOperationExecutor;

package/src/executor/OpenAPIOperationLocatorNormalizer.cjs

@@ -0,0 +1,197 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _arazzoRuntimeExpression = require("@swaggerexpert/arazzo-runtime-expression");
+var _jsonPointer = require("@swaggerexpert/json-pointer");
+var _empty = require("@speclynx/apidom-reference/configuration/empty");
+var _OpenAPIDocument = _interopRequireDefault(require("../document/OpenAPIDocument.cjs"));
+var _RuntimeExpressionEvaluator = _interopRequireDefault(require("../expression/RuntimeExpressionEvaluator.cjs"));
+var _ExtractionError = _interopRequireDefault(require("../errors/ExtractionError.cjs"));
+var _SourceDescriptionsLocatorNormalizer = _interopRequireDefault(require("./SourceDescriptionsLocatorNormalizer.cjs"));
+/**
+ * A canonical OpenAPI operation locator: the OpenAPI document that owns the
+ * operation and a JSON Pointer locating the operation within it
+ * (`/paths/{path}/{method}`).
+ *
+ * A step names its operation in one of several ways — a plain `operationId`, a
+ * `$sourceDescriptions` runtime expression, or an `operationPath` — which are
+ * all locators for the same thing. The normalizer reduces any of them to this
+ * single canonical form.
+ * @public
+ */
+
+/**
+ * Normalizes a step's OpenAPI operation locator to a canonical
+ * {@link OpenAPIOperationLocator} — the OpenAPI document and a JSON Pointer to
+ * the operation within it.
+ *
+ * A step names its operation with either `operationId` or `operationPath`:
+ * - `operationId` is a plain operation name, or a whole runtime expression
+ *   `$sourceDescriptions.{name}.{operationId}`. Per the Arazzo Specification, a
+ *   plain name is only valid when a single (non-arazzo) source description is
+ *   defined; multiple sources require the expression form. A plain name is
+ *   therefore resolved against the first source description that has it.
+ * - `operationPath` embeds a `{$sourceDescriptions.{name}.url}` runtime
+ *   expression followed by a JSON Pointer to the operation.
+ *
+ * The `type` declared on a source description is not trusted (it may be absent
+ * or wrong); a source is classified by what it actually parses to. The
+ * normalizer acquires the referenced source documents from the registry on
+ * demand.
+ * @public
+ */
+class OpenAPIOperationLocatorNormalizer extends _SourceDescriptionsLocatorNormalizer.default {
+  /**
+   * Normalizes a plain or expression `operationId` to a canonical locator.
+   *
+   * A whole runtime expression (`$sourceDescriptions.{name}.{operationId}`) is
+   * resolved against its named source; a plain name is resolved against the
+   * first source description that has it.
+   */
+  async normalizeOperationId(operationId, document) {
+    if ((0, _arazzoRuntimeExpression.test)(operationId)) {
+      return this.#resolveSourced(operationId, document);
+    }
+    return this.#resolvePlainOperationId(operationId, document);
+  }
+
+  /**
+   * Normalizes an `operationPath` —
+   * `{$sourceDescriptions.{name}.url}#/json/pointer` — to a canonical locator.
+   *
+   * The reference is interpolated (resolving
+   * `{$sourceDescriptions.{name}.url}` to the source's URL) into a URI
+   * reference; its fragment is the JSON Pointer to the operation (decoded from
+   * the URI fragment representation) and the part before the fragment is the
+   * source document to acquire.
+   *
+   * The runner only needs a URL and a JSON Pointer, so it does not enforce that
+   * the source description is identified by a runtime expression rather than a
+   * literal URL (a literal URL interpolates to itself and still resolves) — that
+   * is a conformance concern for the validator. It fails only when the URL does
+   * not resolve to an OpenAPI source or the JSON Pointer is invalid.
+   */
+  async normalizeOperationPath(operationPath, document) {
+    const evaluator = new _RuntimeExpressionEvaluator.default({}, {
+      strict: false,
+      document,
+      registry: this.registry
+    });
+    const uriReference = evaluator.interpolate(operationPath);
+    const documentURI = _empty.url.sanitize(_empty.url.stripHash(uriReference));
+    if (documentURI === '') {
+      throw new _ExtractionError.default(`operationPath "${operationPath}" does not resolve to a source description URL`, {
+        pointer: operationPath,
+        uri: document.uri
+      });
+    }
+    const jsonPointer = _jsonPointer.URIFragmentIdentifier.fromURIReference(uriReference);
+    if (!(0, _jsonPointer.testJSONPointer)(jsonPointer)) {
+      throw new _ExtractionError.default(`operationPath "${operationPath}" has an invalid JSON Pointer`, {
+        pointer: operationPath,
+        uri: document.uri
+      });
+    }
+    const source = await this.registry.acquire(documentURI);
+    if (!_OpenAPIDocument.default.is(source)) {
+      throw new _ExtractionError.default(`operationPath "${operationPath}" does not reference an OpenAPI document`, {
+        pointer: operationPath,
+        uri: documentURI
+      });
+    }
+    return {
+      document: source,
+      jsonPointer
+    };
+  }
+
+  /**
+   * Parses a `$sourceDescriptions.{name}.{reference}` expression, asserting
+   * it is a source-descriptions expression.
+   */
+  #parseSourceDescriptionsExpression(expression) {
+    const parsed = this.parseSourceDescriptionsExpression(expression);
+    if (parsed === undefined) {
+      throw new _ExtractionError.default(`Unsupported operationId expression "${expression}"`, {
+        operationId: expression
+      });
+    }
+    return parsed;
+  }
+  async #resolveSourced(expression, document) {
+    const {
+      sourceName,
+      reference: operationId
+    } = this.#parseSourceDescriptionsExpression(expression);
+    const openapiDocument = await this.#sourceDocument(sourceName, document);
+    const jsonPointer = openapiDocument.operationIndex.get(operationId);
+    if (jsonPointer === undefined) {
+      throw new _ExtractionError.default(`Operation "${operationId}" not found in source description "${sourceName}"`, {
+        operationId,
+        uri: openapiDocument.uri
+      });
+    }
+    return {
+      document: openapiDocument,
+      jsonPointer
+    };
+  }
+
+  /**
+   * Resolves a plain operationId against the single OpenAPI source description.
+   *
+   * Per the Arazzo Specification a plain operationId is only valid when a single
+   * non-arazzo source description is defined; multiple such sources require the
+   * `$sourceDescriptions` expression form. The first OpenAPI source is therefore
+   * the one it targets: the operationId is looked up there and the lookup fails
+   * if it is absent — subsequent OpenAPI sources are not searched (their
+   * presence would make the plain operationId ambiguous, and hence invalid).
+   * Non-OpenAPI (arazzo) sources are skipped. Sources are acquired one at a time
+   * until the first OpenAPI source is reached.
+   */
+  async #resolvePlainOperationId(operationId, document) {
+    for (const uri of document.sourceDescriptionURIs()) {
+      const source = await this.registry.acquire(uri);
+      if (!_OpenAPIDocument.default.is(source)) continue;
+      const jsonPointer = source.operationIndex.get(operationId);
+      if (jsonPointer === undefined) {
+        throw new _ExtractionError.default(`Operation "${operationId}" not found in source description at "${source.uri}"`, {
+          operationId,
+          uri: source.uri
+        });
+      }
+      return {
+        document: source,
+        jsonPointer
+      };
+    }
+    throw new _ExtractionError.default(`Operation "${operationId}" has no OpenAPI source description`, {
+      operationId,
+      uri: document.uri
+    });
+  }
+
+  /**
+   * Acquires a source description by name and asserts it is an OpenAPI document.
+   */
+  async #sourceDocument(sourceName, document) {
+    const uri = document.resolveSourceDescriptionURI(sourceName);
+    if (uri === undefined) {
+      throw new _ExtractionError.default(`Source description "${sourceName}" not found`, {
+        uri: document.uri
+      });
+    }
+    const source = await this.registry.acquire(uri);
+    if (!_OpenAPIDocument.default.is(source)) {
+      throw new _ExtractionError.default(`Source description "${sourceName}" is not an OpenAPI document`, {
+        uri
+      });
+    }
+    return source;
+  }
+}
+var _default = exports.default = OpenAPIOperationLocatorNormalizer;