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

package/src/expression/RuntimeExpressionEvaluator.mjs

@@ -0,0 +1,328 @@
+import { parseRuntimeExpression } from '@usearazzo/parser';
+import { test, interpolate } from '@swaggerexpert/arazzo-runtime-expression';
+import { compile, composeRealms, evaluate as evaluateJSONPointer, JSONPointerEvaluateError } from '@swaggerexpert/json-pointer';
+import JSONEvaluationRealm from '@swaggerexpert/json-pointer/evaluate/realms/json';
+import { ApiDOMEvaluationRealm } from '@speclynx/apidom-json-pointer';
+import { toValue } from '@speclynx/apidom-core';
+import RuntimeExpressionError from "../errors/RuntimeExpressionError.mjs";
+import ArazzoDocument from "../document/ArazzoDocument.mjs";
+import OpenAPIDocument from "../document/OpenAPIDocument.mjs";
+/**
+ * Options for the RuntimeExpressionEvaluator.
+ * @public
+ */
+/**
+ * The request/response side of the context a `$request`/`$response` source is
+ * evaluated against. Both request and response contexts are assignable to this
+ * shape; sources absent from a side (e.g. `$response.query`) resolve to
+ * `undefined` naturally.
+ */
+/**
+ * Realm for drilling JSON Pointers into payload values. Composing the ApiDOM
+ * realm ahead of the JSON realm lets a single `evaluate` call handle plain JS
+ * values, ApiDOM elements, and mixed trees: the ApiDOM realm claims elements
+ * and falls through to the JSON realm for plain values. Order matters — the
+ * JSON realm would otherwise greedily claim ApiDOM elements and fail.
+ */
+const pointerRealm = composeRealms(new ApiDOMEvaluationRealm(), new JSONEvaluationRealm());
+
+/**
+ * The expression roots that describe one HTTP exchange — unavailable in a step
+ * that calls a workflow, which makes none.
+ */
+const HTTP_EXCHANGE_NODES = new Set(['UrlExpression', 'MethodExpression', 'StatusCodeExpression', 'RequestExpression', 'ResponseExpression']);
+
+/**
+ * Evaluates Arazzo runtime expressions against a context.
+ *
+ * A single evaluator is bound to one context and can evaluate many expressions
+ * against it — matching how a step executor resolves a step's parameters,
+ * success criteria, and outputs from the same state.
+ *
+ * The context holds only runtime state (`$inputs`, `$steps`, `$request`,
+ * `$response`, …). Static, document-sourced expressions are resolved on demand:
+ * `$components` and `$workflows.{workflowId}.steps.{stepId}` from the
+ * evaluator's document, and `$sourceDescriptions` from the external document
+ * (via the registry) the source name points at. A step reference resolves to
+ * the Step Object as authored — a locator, not the step's execution result.
+ *
+ * A reference resolves to `undefined` when it is absent. Runtime values
+ * originate from JSON (or ApiDOM), which cannot represent `undefined` — an
+ * absent value is a missing property and an explicit null is `null` — so
+ * `undefined` unambiguously marks "unresolved".
+ *
+ * Three modes are supported:
+ * - {@link RuntimeExpressionEvaluator.evaluate} resolves a pure expression
+ *   (e.g. `$response.body#/id`) to its typed value.
+ * - {@link RuntimeExpressionEvaluator.interpolate} renders a template with
+ *   embedded `{expression}` occurrences to a string.
+ * - {@link RuntimeExpressionEvaluator.resolve} applies Arazzo "value" semantics:
+ *   a value that is itself a complete expression resolves to a typed value,
+ *   otherwise the value is interpolated to a string.
+ * @public
+ */
+class RuntimeExpressionEvaluator {
+  #context;
+  #strict;
+  #document;
+  #registry;
+  constructor(context, options = {}) {
+    this.#context = context;
+    this.#strict = options.strict ?? true;
+    this.#document = options.document;
+    this.#registry = options.registry;
+  }
+
+  /**
+   * Evaluates a pure runtime expression to its typed value.
+   *
+   * The expression must be the bare form without surrounding braces
+   * (e.g. `$inputs.username`, `$response.body#/pets/0/id`). In strict mode an
+   * unresolvable reference throws; otherwise it returns `undefined`.
+   */
+  evaluate(expression) {
+    const node = this.#parse(expression);
+    this.#assertAvailable(node, expression);
+    const value = this.#evaluateNode(node, expression);
+    if (value === undefined && this.#strict) {
+      throw new RuntimeExpressionError(`Runtime expression "${expression}" could not be resolved against the context`, {
+        expression,
+        reason: 'unresolved-reference'
+      });
+    }
+    return value;
+  }
+
+  /**
+   * Renders a template string, replacing each embedded `{expression}` with the
+   * string form of its evaluated value. Returns a string.
+   *
+   * Object and array values are serialized with `JSON.stringify`. In non-strict
+   * mode, unresolvable references render as an empty string. A `{…}` that is not
+   * a valid embedded expression (e.g. a literal JSON payload) is left unchanged.
+   */
+  interpolate(template) {
+    return interpolate(template, expression => this.evaluate(expression));
+  }
+
+  /**
+   * Resolves an Arazzo "value" string.
+   *
+   * A value that is itself a complete runtime expression (the unbraced form,
+   * e.g. `$inputs.userId`) resolves to its typed value — "runtime expressions
+   * preserve the type of the referenced value". Any other string is an
+   * expression-string template: embedded `{expression}` occurrences are
+   * interpolated and a string is returned, so a whole-string `{expression}`
+   * yields the string representation of its value, not the typed value. A
+   * string containing no expressions is returned unchanged.
+   */
+  resolve(value) {
+    // `test` returns true only when the entire string is a valid runtime
+    // expression, so a braced or mixed string falls through to interpolation.
+    return test(value) ? this.evaluate(value) : this.interpolate(value);
+  }
+
+  /**
+   * Parses an expression to its AST, throwing on failure regardless of strict mode.
+   */
+  #parse(expression) {
+    let result;
+    try {
+      result = parseRuntimeExpression(expression);
+    } catch (error) {
+      throw new RuntimeExpressionError(`Failed to parse runtime expression "${expression}"`, {
+        cause: error,
+        expression,
+        reason: 'parse-error'
+      });
+    }
+    if (!result.result.success || result.tree === undefined) {
+      throw new RuntimeExpressionError(`Invalid runtime expression "${expression}"`, {
+        expression,
+        reason: 'invalid-expression'
+      });
+    }
+    return result.tree;
+  }
+
+  /**
+   * Rejects an HTTP-exchange expression in a step that calls a workflow. Such a
+   * step made no HTTP call, so the expression is an authoring error there — not
+   * a reference that merely did not resolve — and throws regardless of `strict`.
+   */
+  #assertAvailable(node, expression) {
+    const {
+      calledWorkflow
+    } = this.#context;
+    if (calledWorkflow === undefined || !HTTP_EXCHANGE_NODES.has(node.type)) return;
+    throw new RuntimeExpressionError(`Runtime expression "${expression}" is not available: step "${calledWorkflow.stepId}" calls workflow "${calledWorkflow.workflowId}", not an operation, so it has no HTTP request or response`, {
+      expression,
+      reason: 'unavailable-expression'
+    });
+  }
+
+  /**
+   * Walks an AST node against the context, returning the referenced value or
+   * `undefined` when the reference does not resolve.
+   */
+  #evaluateNode(node, expression) {
+    switch (node.type) {
+      case 'UrlExpression':
+        return this.#context.request?.url;
+      case 'MethodExpression':
+        return this.#context.request?.method;
+      case 'StatusCodeExpression':
+        return this.#context.response?.statusCode;
+      case 'RequestExpression':
+        return this.#source(node.source, this.#context.request);
+      case 'ResponseExpression':
+        return this.#source(node.source, this.#context.response);
+      case 'InputsExpression':
+        return this.#drill(this.#get(this.#context.inputs, node.name));
+      case 'OutputsExpression':
+        return this.#drill(this.#get(this.#context.outputs, node.name));
+      case 'StepsExpression':
+        return this.#drill(this.#get(this.#context.steps?.[node.stepId]?.outputs, node.outputName), node.jsonPointer?.value);
+      case 'WorkflowsExpression':
+        return this.#drill(this.#get(this.#context.workflows?.[node.workflowId]?.[node.field], node.fieldName), node.jsonPointer?.value);
+      case 'WorkflowsStepsExpression':
+        return this.#step(this.#document, node.workflowId, node.stepId);
+      case 'SourceDescriptionsExpression':
+        return this.#sourceDescription(node);
+      case 'ComponentsExpression':
+        return this.#component(node.componentType, node.componentName);
+      default:
+        throw new RuntimeExpressionError(`Unsupported runtime expression node "${node.type}"`, {
+          expression,
+          reason: 'unsupported-node'
+        });
+    }
+  }
+
+  /**
+   * Evaluates a `$request`/`$response` source reference against the request or
+   * response side of the context.
+   */
+  #source(source, message) {
+    const {
+      reference
+    } = source;
+    switch (reference.type) {
+      case 'HeaderReference':
+        return this.#header(message?.header, reference.token);
+      case 'QueryReference':
+        return this.#get(message?.query, reference.name);
+      case 'PathReference':
+        return this.#get(message?.path, reference.name);
+      case 'BodyReference':
+        return this.#drill(message?.body, reference.jsonPointer?.value);
+      default:
+        return undefined;
+    }
+  }
+
+  /**
+   * Resolves `$components.{field}.{name}` by drilling into the evaluator's
+   * document. Returns `undefined` when no document is configured or the
+   * component is absent.
+   */
+  #component(field, name) {
+    return this.#drillDocument(this.#document, compile(['components', field, name]));
+  }
+
+  /**
+   * Resolves `{workflowId}.steps.{stepId}` to the Step Object in an Arazzo
+   * document. Returns `undefined` when the document is absent or not Arazzo, or
+   * the workflow or step is unknown.
+   */
+  #step(document, workflowId, stepId) {
+    if (document === undefined || !ArazzoDocument.is(document)) return undefined;
+    const pointer = document.stepIndex.getStep(workflowId, stepId);
+    return pointer === undefined ? undefined : this.#drillDocument(document, pointer);
+  }
+
+  /**
+   * Resolves `$sourceDescriptions.{name}.{reference}` with the resolution
+   * priority defined by the Arazzo Specification:
+   *
+   * 1. `{reference}` is matched as an operationId (OpenAPI source) or workflowId
+   *    (Arazzo source) in the referenced document, resolving to that operation
+   *    or workflow. A `{workflowId}.steps.{stepId}` reference resolves to that
+   *    step of the referenced Arazzo document.
+   * 2. failing that, `{reference}` is matched as a field of the Source
+   *    Description Object itself (e.g. `url`, `type`) — so
+   *    `$sourceDescriptions.{name}.url` yields the source's URL. An operationId
+   *    that collides with a field name takes precedence (tier 1 wins).
+   *
+   * Returns `undefined` when nothing matches.
+   */
+  #sourceDescription({
+    sourceName,
+    reference,
+    stepsReference
+  }) {
+    const uri = this.#document?.resolveSourceDescriptionURI(sourceName);
+
+    // tier 1: operationId / workflowId / workflow step in the referenced document.
+    const apiDocument = uri === undefined ? undefined : this.#registry?.get(uri);
+    if (apiDocument !== undefined) {
+      if (stepsReference !== undefined) {
+        return this.#step(apiDocument, stepsReference.workflowId, stepsReference.stepId);
+      }
+      const pointer = OpenAPIDocument.is(apiDocument) ? apiDocument.operationIndex.get(reference) : ArazzoDocument.is(apiDocument) ? apiDocument.workflowIndex.get(reference) : undefined;
+      if (pointer !== undefined) return this.#drillDocument(apiDocument, pointer);
+    }
+
+    // tier 2: a field of the Source Description Object (url, type, ...).
+    return this.#document?.resolveSourceDescriptionField(sourceName, reference);
+  }
+
+  /**
+   * Reads a property from a context slot, or `undefined` when the slot is not
+   * an object or lacks the key. Own properties only, so prototype members
+   * (`constructor`, `toString`) never leak into a resolution.
+   */
+  #get(slot, key) {
+    if (typeof slot !== 'object' || slot === null) return undefined;
+    if (!Object.hasOwn(slot, key)) return undefined;
+    return slot[key];
+  }
+
+  /**
+   * Reads a header case-insensitively. The parser already lowercases the header
+   * token, so only the context keys (populated from an HTTP response with
+   * arbitrary casing) need normalizing to match.
+   */
+  #header(headers, token) {
+    if (headers === undefined) return undefined;
+    const key = Object.keys(headers).find(k => k.toLowerCase() === token);
+    return key === undefined ? undefined : headers[key];
+  }
+
+  /**
+   * Drills a JSON Pointer into a document's API element. Returns `undefined`
+   * when the document is absent or the pointer does not resolve.
+   */
+  #drillDocument(document, pointer) {
+    return document === undefined ? undefined : this.#drill(document.parseResult.api, pointer);
+  }
+
+  /**
+   * Drills an optional JSON Pointer into a payload value, returning the plain
+   * runtime value. `toValue` is idempotent on plain values, so the leaf is plain
+   * whether the payload was JSON or an ApiDOM element (see `pointerRealm`).
+   */
+  #drill(value, pointer) {
+    if (value === undefined) return undefined;
+    if (pointer === undefined) return toValue(value);
+    try {
+      return toValue(evaluateJSONPointer(value, pointer, {
+        realm: pointerRealm
+      }));
+    } catch (error) {
+      if (error instanceof JSONPointerEvaluateError) return undefined;
+      throw error;
+    }
+  }
+}
+export default RuntimeExpressionEvaluator;

package/src/extractor/ArazzoStepExtractor.cjs

@@ -0,0 +1,48 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomCore = require("@speclynx/apidom-core");
+var _apidomTraverse = require("@speclynx/apidom-traverse");
+var _ExtractionError = _interopRequireDefault(require("../errors/ExtractionError.cjs"));
+/**
+ * Extracts a step from an Arazzo workflow by stepId.
+ *
+ * Searches the workflow's steps array for the matching stepId.
+ * The workflow should be already extracted via ArazzoWorkflowExtractor.
+ * @public
+ */
+class ArazzoStepExtractor {
+  /**
+   * Extracts a step element by stepId from a workflow.
+   */
+  extract(workflow, stepId) {
+    const steps = workflow.steps;
+    let step;
+    if (!(0, _apidomDatamodel.isArrayElement)(steps)) {
+      throw new _ExtractionError.default(`Workflow "${(0, _apidomCore.toValue)(workflow.workflowId)}" has no steps`, {
+        workflowId: (0, _apidomCore.toValue)(workflow.workflowId)
+      });
+    }
+    (0, _apidomTraverse.traverse)(workflow, {
+      StepElement(path) {
+        if (!path.node.stepId?.equals(stepId)) return path.skip();
+        step = path.node;
+        step.meta.set('workflowId', (0, _apidomCore.toValue)(workflow.workflowId));
+        path.stop();
+      }
+    });
+    if (!step) {
+      throw new _ExtractionError.default(`Step "${stepId}" not found in workflow "${(0, _apidomCore.toValue)(workflow.workflowId)}"`, {
+        workflowId: (0, _apidomCore.toValue)(workflow.workflowId),
+        stepId
+      });
+    }
+    return step;
+  }
+}
+var _default = exports.default = ArazzoStepExtractor;

package/src/extractor/ArazzoStepExtractor.mjs

@@ -0,0 +1,41 @@
+import { isArrayElement } from '@speclynx/apidom-datamodel';
+import { toValue } from '@speclynx/apidom-core';
+import { traverse } from '@speclynx/apidom-traverse';
+import ExtractionError from "../errors/ExtractionError.mjs";
+/**
+ * Extracts a step from an Arazzo workflow by stepId.
+ *
+ * Searches the workflow's steps array for the matching stepId.
+ * The workflow should be already extracted via ArazzoWorkflowExtractor.
+ * @public
+ */
+class ArazzoStepExtractor {
+  /**
+   * Extracts a step element by stepId from a workflow.
+   */
+  extract(workflow, stepId) {
+    const steps = workflow.steps;
+    let step;
+    if (!isArrayElement(steps)) {
+      throw new ExtractionError(`Workflow "${toValue(workflow.workflowId)}" has no steps`, {
+        workflowId: toValue(workflow.workflowId)
+      });
+    }
+    traverse(workflow, {
+      StepElement(path) {
+        if (!path.node.stepId?.equals(stepId)) return path.skip();
+        step = path.node;
+        step.meta.set('workflowId', toValue(workflow.workflowId));
+        path.stop();
+      }
+    });
+    if (!step) {
+      throw new ExtractionError(`Step "${stepId}" not found in workflow "${toValue(workflow.workflowId)}"`, {
+        workflowId: toValue(workflow.workflowId),
+        stepId
+      });
+    }
+    return step;
+  }
+}
+export default ArazzoStepExtractor;

package/src/extractor/ArazzoWorkflowExtractor.cjs

@@ -0,0 +1,50 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _apidomJsonPointer = require("@speclynx/apidom-json-pointer");
+var _ExtractionError = _interopRequireDefault(require("../errors/ExtractionError.cjs"));
+/**
+ * Extracts a workflow from an Arazzo document by workflowId.
+ *
+ * The workflow is already fully dereferenced in the document,
+ * so no additional processing is needed.
+ * @public
+ */
+class ArazzoWorkflowExtractor {
+  /**
+   * Extracts a workflow element by workflowId.
+   */
+  extract(document, workflowId) {
+    const pointer = document.workflowIndex.get(workflowId);
+    let workflow;
+    if (pointer === undefined) {
+      throw new _ExtractionError.default(`Workflow "${workflowId}" not found in Arazzo document at "${document.uri}"`, {
+        workflowId,
+        uri: document.uri
+      });
+    }
+    try {
+      workflow = (0, _apidomJsonPointer.evaluate)(document.parseResult.api, pointer);
+    } catch (error) {
+      throw new _ExtractionError.default(`Failed to evaluate pointer "${pointer}" in Arazzo document at "${document.uri}"`, {
+        cause: error,
+        workflowId,
+        pointer,
+        uri: document.uri
+      });
+    }
+    if (workflow?.element !== 'workflow') {
+      throw new _ExtractionError.default(`Pointer "${pointer}" does not reference a workflow in Arazzo document at "${document.uri}"`, {
+        workflowId,
+        pointer,
+        uri: document.uri
+      });
+    }
+    return workflow;
+  }
+}
+var _default = exports.default = ArazzoWorkflowExtractor;

package/src/extractor/ArazzoWorkflowExtractor.mjs

@@ -0,0 +1,43 @@
+import { evaluate } from '@speclynx/apidom-json-pointer';
+import ExtractionError from "../errors/ExtractionError.mjs";
+/**
+ * Extracts a workflow from an Arazzo document by workflowId.
+ *
+ * The workflow is already fully dereferenced in the document,
+ * so no additional processing is needed.
+ * @public
+ */
+class ArazzoWorkflowExtractor {
+  /**
+   * Extracts a workflow element by workflowId.
+   */
+  extract(document, workflowId) {
+    const pointer = document.workflowIndex.get(workflowId);
+    let workflow;
+    if (pointer === undefined) {
+      throw new ExtractionError(`Workflow "${workflowId}" not found in Arazzo document at "${document.uri}"`, {
+        workflowId,
+        uri: document.uri
+      });
+    }
+    try {
+      workflow = evaluate(document.parseResult.api, pointer);
+    } catch (error) {
+      throw new ExtractionError(`Failed to evaluate pointer "${pointer}" in Arazzo document at "${document.uri}"`, {
+        cause: error,
+        workflowId,
+        pointer,
+        uri: document.uri
+      });
+    }
+    if (workflow?.element !== 'workflow') {
+      throw new ExtractionError(`Pointer "${pointer}" does not reference a workflow in Arazzo document at "${document.uri}"`, {
+        workflowId,
+        pointer,
+        uri: document.uri
+      });
+    }
+    return workflow;
+  }
+}
+export default ArazzoWorkflowExtractor;

package/src/extractor/OpenAPIOperationExtractor.cjs

@@ -0,0 +1,84 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _apidomJsonPointer = require("@speclynx/apidom-json-pointer");
+var _ExtractionError = _interopRequireDefault(require("../errors/ExtractionError.cjs"));
+/**
+ * Extracts an operation from an OpenAPI document.
+ *
+ * Locates the operation by operationId or operationPath (JSON Pointer)
+ * and attaches metadata (pointer, method, path) to the element.
+ * The extracted operation is not dereferenced or normalized.
+ * @public
+ */
+class OpenAPIOperationExtractor {
+  /**
+   * Extracts an operation by operationId.
+   */
+  extract(document, operationId) {
+    const pointer = document.operationIndex.get(operationId);
+    if (pointer === undefined) {
+      throw new _ExtractionError.default(`Operation "${operationId}" not found in OpenAPI document at "${document.uri}"`, {
+        operationId,
+        uri: document.uri
+      });
+    }
+    return this.extractByPointer(document, pointer);
+  }
+
+  /**
+   * Extracts an operation by JSON Pointer (operationPath).
+   */
+  extractByPointer(document, pointer) {
+    let operation;
+    let tokens;
+    try {
+      tokens = (0, _apidomJsonPointer.parse)(pointer).tree;
+    } catch (error) {
+      throw new _ExtractionError.default(`Failed to parse pointer "${pointer}"`, {
+        cause: error,
+        pointer,
+        uri: document.uri
+      });
+    }
+    // an invalid pointer does not throw: the parse result just has no tree
+    if (tokens === undefined) {
+      throw new _ExtractionError.default(`Invalid JSON Pointer "${pointer}"`, {
+        pointer,
+        uri: document.uri
+      });
+    }
+    if (tokens.length !== 3 || tokens[0] !== 'paths') {
+      throw new _ExtractionError.default(`Invalid operation pointer "${pointer}": expected /paths/{path}/{method}`, {
+        pointer,
+        uri: document.uri
+      });
+    }
+    try {
+      operation = (0, _apidomJsonPointer.evaluate)(document.parseResult.api, pointer);
+    } catch (error) {
+      throw new _ExtractionError.default(`Failed to evaluate pointer "${pointer}" in OpenAPI document at "${document.uri}"`, {
+        cause: error,
+        pointer,
+        uri: document.uri
+      });
+    }
+    if (operation?.element !== 'operation') {
+      throw new _ExtractionError.default(`Pointer "${pointer}" does not reference an operation in OpenAPI document at "${document.uri}"`, {
+        pointer,
+        uri: document.uri
+      });
+    }
+
+    // attach metadata for downstream consumers
+    operation.meta.set('pointer', pointer);
+    operation.meta.set('http-method', tokens[2]);
+    operation.meta.set('path', tokens[1]);
+    return operation;
+  }
+}
+var _default = exports.default = OpenAPIOperationExtractor;

package/src/extractor/OpenAPIOperationExtractor.mjs

@@ -0,0 +1,77 @@
+import { evaluate, parse } from '@speclynx/apidom-json-pointer';
+import ExtractionError from "../errors/ExtractionError.mjs";
+/**
+ * Extracts an operation from an OpenAPI document.
+ *
+ * Locates the operation by operationId or operationPath (JSON Pointer)
+ * and attaches metadata (pointer, method, path) to the element.
+ * The extracted operation is not dereferenced or normalized.
+ * @public
+ */
+class OpenAPIOperationExtractor {
+  /**
+   * Extracts an operation by operationId.
+   */
+  extract(document, operationId) {
+    const pointer = document.operationIndex.get(operationId);
+    if (pointer === undefined) {
+      throw new ExtractionError(`Operation "${operationId}" not found in OpenAPI document at "${document.uri}"`, {
+        operationId,
+        uri: document.uri
+      });
+    }
+    return this.extractByPointer(document, pointer);
+  }
+
+  /**
+   * Extracts an operation by JSON Pointer (operationPath).
+   */
+  extractByPointer(document, pointer) {
+    let operation;
+    let tokens;
+    try {
+      tokens = parse(pointer).tree;
+    } catch (error) {
+      throw new ExtractionError(`Failed to parse pointer "${pointer}"`, {
+        cause: error,
+        pointer,
+        uri: document.uri
+      });
+    }
+    // an invalid pointer does not throw: the parse result just has no tree
+    if (tokens === undefined) {
+      throw new ExtractionError(`Invalid JSON Pointer "${pointer}"`, {
+        pointer,
+        uri: document.uri
+      });
+    }
+    if (tokens.length !== 3 || tokens[0] !== 'paths') {
+      throw new ExtractionError(`Invalid operation pointer "${pointer}": expected /paths/{path}/{method}`, {
+        pointer,
+        uri: document.uri
+      });
+    }
+    try {
+      operation = evaluate(document.parseResult.api, pointer);
+    } catch (error) {
+      throw new ExtractionError(`Failed to evaluate pointer "${pointer}" in OpenAPI document at "${document.uri}"`, {
+        cause: error,
+        pointer,
+        uri: document.uri
+      });
+    }
+    if (operation?.element !== 'operation') {
+      throw new ExtractionError(`Pointer "${pointer}" does not reference an operation in OpenAPI document at "${document.uri}"`, {
+        pointer,
+        uri: document.uri
+      });
+    }
+
+    // attach metadata for downstream consumers
+    operation.meta.set('pointer', pointer);
+    operation.meta.set('http-method', tokens[2]);
+    operation.meta.set('path', tokens[1]);
+    return operation;
+  }
+}
+export default OpenAPIOperationExtractor;