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

package/package.json

@@ -1,6 +1,90 @@
 {
   "name": "@usearazzo/runner",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1-alpha.7",
+  "description": "Runner for Arazzo Workflows.",
+  "keywords": [
+    "arazzo",
+    "arazzo-specification",
+    "runner",
+    "workflow",
+    "workflows"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "provenance": false,
+    "tag": "latest"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.10.0"
+  },
+  "unpkg": "./dist/arazzo-runner.browser.min.js",
+  "main": "./src/index.cjs",
+  "exports": {
+    "types": "./types/runner.d.ts",
+    "import": "./src/index.mjs",
+    "require": "./src/index.cjs"
+  },
+  "types": "./types/runner.d.ts",
+  "scripts": {
+    "build": "npm run clean && npm run build:es && run-p --max-parallel ${CPU_CORES:-2} typescript:declaration build:cjs build:umd:browser",
+    "build:es": "npm run build:swagger-client && cross-env BABEL_ENV=es babel src --out-dir src --extensions '.ts' --out-file-extension '.mjs' --root-mode 'upward'",
+    "build:cjs": "cross-env BABEL_ENV=cjs babel src --out-dir src --extensions '.ts' --out-file-extension '.cjs' --root-mode 'upward'",
+    "build:umd:browser": "cross-env BABEL_ENV=browser webpack --config config/webpack/browser.config.js --progress",
+    "build:swagger-client": "webpack --config config/webpack/swagger-client.config.js --progress",
+    "lint": "eslint ./",
+    "lint:fix": "eslint ./ --fix",
+    "clean": "rimraf --glob 'src/**/*.mjs' 'src/**/*.cjs' 'test/**/*.mjs' ./dist ./types",
+    "typescript:check-types": "tsc --noEmit",
+    "typescript:declaration": "tsc -p tsconfig.declaration.json && api-extractor run -l -c ./config/api-extractor/api-extractor.json",
+    "test": "npm run build:es && cross-env BABEL_ENV=es babel test --out-dir test --extensions '.ts' --out-file-extension '.mjs' --root-mode 'upward' && cross-env NODE_ENV=test mocha",
+    "test:e2e": "npm run build:es && cross-env BABEL_ENV=es babel test --out-dir test --extensions '.ts' --out-file-extension '.mjs' --root-mode 'upward' && cross-env NODE_ENV=test mocha --config .mocharc.e2e.json",
+    "prepack": "copyfiles -u 2 ../../LICENSE . && copyfiles -u 2 ../../NOTICE .",
+    "postpack": "rimraf NOTICE LICENSE"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/usearazzo/arazzo-toolkit.git"
+  },
+  "author": "Vladimir Gorej <vladimir.gorej@gmail.com>",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@babel/runtime-corejs3": "^8.0.7",
+    "@speclynx/apidom-core": "^6.1.0",
+    "@speclynx/apidom-datamodel": "^6.1.0",
+    "@speclynx/apidom-error": "^6.1.0",
+    "@speclynx/apidom-json-pointer": "^6.1.0",
+    "@speclynx/apidom-ns-arazzo-1": "^6.1.0",
+    "@speclynx/apidom-ns-openapi-2": "^6.1.0",
+    "@speclynx/apidom-ns-openapi-3-0": "^6.1.0",
+    "@speclynx/apidom-ns-openapi-3-1": "^6.1.0",
+    "@speclynx/apidom-reference": "^6.1.0",
+    "@speclynx/apidom-traverse": "^6.1.0",
+    "@swaggerexpert/arazzo-criterion": "^1.0.1",
+    "@swaggerexpert/arazzo-runtime-expression": "^3.3.0",
+    "@swaggerexpert/json-pointer": "^3.0.2",
+    "@swaggerexpert/jsonpath": "^4.0.5",
+    "@usearazzo/parser": "1.0.1-alpha.7",
+    "@usearazzo/resolver": "1.0.1-alpha.7",
+    "@xmldom/xmldom": "^0.9.12",
+    "fontoxpath": "^3.34.0",
+    "ramda": "^0.32.0",
+    "ramda-adjunct": "^6.1.0",
+    "type-fest": "^5.10.0"
+  },
+  "files": [
+    "src/**/*.mjs",
+    "src/**/*.cjs",
+    "dist/",
+    "types/runner.d.ts",
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "devDependencies": {
+    "swagger-client": "^3.38.4"
+  }
+}

package/src/action/ActionResolver.cjs

@@ -0,0 +1,160 @@
+"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 _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
+var _ResolverError = _interopRequireDefault(require("../errors/ResolverError.cjs"));
+/**
+ * Determines whether a single criterion is met.
+ *
+ * Bridged to a criterion evaluator
+ * (`(criterion) => criterionEvaluator.evaluate(criterion, resolve)`); an
+ * unresolvable/failing criterion is `false`, not an error.
+ * @public
+ */
+
+/**
+ * The action selected for a step outcome — a Success or Failure Action element.
+ * @public
+ */
+
+/**
+ * Which of a step's two action lists is being resolved. See
+ * {@link ActionResolver.#resolveAll} for why it's needed and why it's baked
+ * in by the public method rather than taken from the caller. Internal: never
+ * leaks into the public API.
+ */
+
+/**
+ * Selects the actions to take for a step outcome from its `onSuccess` /
+ * `onFailure` list.
+ *
+ * Actions are tried in order and every one whose `criteria` all pass is
+ * returned (an action with no criteria always matches). Action elements are
+ * returned as-is — interpreting them (branching on `type`, reading
+ * `stepId`/`workflowId`/`retryAfter`/`retryLimit`) is the caller's concern, and
+ * keeping them elements preserves the document provenance. The usual caller
+ * acts on the first and takes an empty result as "no action matched", applying
+ * the path default — the next sequential step on success, break-and-return on
+ * failure.
+ *
+ * A step's list is the only list there is: Reusable Object entries are already
+ * inlined by workflow normalization, and the workflow-level
+ * `successActions` / `failureActions` a step falls back to are inherited into
+ * `onSuccess` / `onFailure` by the same pass, so a well-formed document reaches
+ * this point as the step's own list of concrete action elements.
+ * @public
+ */
+class ActionResolver {
+  /**
+   * Returns every `onSuccess` action whose criteria are all met, in list order.
+   *
+   * The whole matching chain rather than only the first, because the caller
+   * needs both: it acts on `[0]`, and the one honoring "retryLimit exhausted
+   * prior to subsequent failure actions" walks the rest, falling from an
+   * exhausted `retry` to the next matching action without re-evaluating
+   * criteria. Empty when the list is absent or nothing matches.
+   *
+   * `scope` names the step this list belongs to, for a thrown
+   * {@link ResolverError}.
+   *
+   * A well-formed list whose entry is not a Success/Failure Action Object
+   * throws rather than being skipped: an unrecognized entry is indistinguishable
+   * from a step that deliberately declared no action for it, and the `goto` /
+   * `end` its author was reaching for would otherwise never happen without a
+   * word said about why.
+   */
+  resolveOnSuccess(actions, isCriterionMet, scope) {
+    // safe: `#resolveAll` validates every entry as *a* Success/Failure Action
+    // Object, not one matching this list's own field, but a well-formed
+    // `StepOnSuccessElement` only ever refracts Success Action entries — the
+    // apidom refractor types list entries positionally at parse time.
+    return this.#resolveAll(actions, isCriterionMet, 'onSuccess', scope);
+  }
+
+  /**
+   * Returns every `onFailure` action whose criteria are all met, in list order.
+   *
+   * Same matching and error behavior as {@link ActionResolver.resolveOnSuccess} —
+   * see there for the full rationale — mirrored for the step's other list.
+   */
+  resolveOnFailure(actions, isCriterionMet, scope) {
+    // safe: see the same-named comment in `resolveOnSuccess` above.
+    return this.#resolveAll(actions, isCriterionMet, 'onFailure', scope);
+  }
+
+  /**
+   * Shared implementation behind {@link ActionResolver.resolveOnSuccess} and
+   * {@link ActionResolver.resolveOnFailure}.
+   *
+   * `field` names which of the step's two lists this is, for the same
+   * `ResolverError` reason `scope` names the step: the one case that needs it —
+   * a list that is present but not a list — is exactly the case where the
+   * element's own type no longer distinguishes them. Baked in by the public
+   * method rather than taken from the caller.
+   */
+  #resolveAll(actions, isCriterionMet, field, scope) {
+    if (actions === undefined) return [];
+    // present but scalar: walking it would fail as a bare
+    // `TypeError: actions is not iterable`.
+    if (!(0, _apidomDatamodel.isArrayElement)(actions)) {
+      throw new _ResolverError.default(`\`${field}\` is present but is not a list`, {
+        ...scope,
+        target: field,
+        reason: 'malformed-actions'
+      });
+    }
+    const matched = [];
+    for (const action of actions) {
+      if (!(0, _apidomNsArazzo.isSuccessActionElement)(action) && !(0, _apidomNsArazzo.isFailureActionElement)(action)) {
+        throw new _ResolverError.default(`\`${field}\` contains an entry that is not a Success/Failure Action Object`, {
+          ...scope,
+          target: field,
+          reason: 'malformed-action-entry'
+        });
+      }
+      if (this.#criteriaMet(action, isCriterionMet, scope)) {
+        matched.push(action);
+      }
+    }
+    return matched;
+  }
+
+  /**
+   * Whether every criterion of the action passes. An action with no criteria
+   * matches vacuously.
+   *
+   * A `criteria` that is present but not a list, or that contains an entry
+   * that is not a Criterion Object, throws either way: an entry the resolver
+   * cannot read and a container it cannot read are both a document that does
+   * not say what its author meant, the same as an unrecognized entry in the
+   * action list itself.
+   */
+  #criteriaMet(action, isCriterionMet, scope) {
+    const criteria = action.criteria;
+    if (criteria === undefined) return true;
+    if (!(0, _apidomDatamodel.isArrayElement)(criteria)) {
+      throw new _ResolverError.default("An action's `criteria` is present but is not a list", {
+        ...scope,
+        target: 'criteria',
+        reason: 'malformed-criteria'
+      });
+    }
+    for (const criterion of criteria) {
+      if (!(0, _apidomNsArazzo.isCriterionElement)(criterion)) {
+        throw new _ResolverError.default("An action's `criteria` contains an entry that is not a Criterion Object", {
+          ...scope,
+          target: 'criteria',
+          reason: 'malformed-criterion'
+        });
+      }
+      if (!isCriterionMet(criterion)) return false;
+    }
+    return true;
+  }
+}
+var _default = exports.default = ActionResolver;

package/src/action/ActionResolver.mjs

@@ -0,0 +1,150 @@
+import { isArrayElement } from '@speclynx/apidom-datamodel';
+import { isSuccessActionElement, isFailureActionElement, isCriterionElement } from '@speclynx/apidom-ns-arazzo-1';
+import ResolverError from "../errors/ResolverError.mjs";
+/**
+ * Determines whether a single criterion is met.
+ *
+ * Bridged to a criterion evaluator
+ * (`(criterion) => criterionEvaluator.evaluate(criterion, resolve)`); an
+ * unresolvable/failing criterion is `false`, not an error.
+ * @public
+ */
+/**
+ * The action selected for a step outcome — a Success or Failure Action element.
+ * @public
+ */
+/**
+ * Which of a step's two action lists is being resolved. See
+ * {@link ActionResolver.#resolveAll} for why it's needed and why it's baked
+ * in by the public method rather than taken from the caller. Internal: never
+ * leaks into the public API.
+ */
+/**
+ * Selects the actions to take for a step outcome from its `onSuccess` /
+ * `onFailure` list.
+ *
+ * Actions are tried in order and every one whose `criteria` all pass is
+ * returned (an action with no criteria always matches). Action elements are
+ * returned as-is — interpreting them (branching on `type`, reading
+ * `stepId`/`workflowId`/`retryAfter`/`retryLimit`) is the caller's concern, and
+ * keeping them elements preserves the document provenance. The usual caller
+ * acts on the first and takes an empty result as "no action matched", applying
+ * the path default — the next sequential step on success, break-and-return on
+ * failure.
+ *
+ * A step's list is the only list there is: Reusable Object entries are already
+ * inlined by workflow normalization, and the workflow-level
+ * `successActions` / `failureActions` a step falls back to are inherited into
+ * `onSuccess` / `onFailure` by the same pass, so a well-formed document reaches
+ * this point as the step's own list of concrete action elements.
+ * @public
+ */
+class ActionResolver {
+  /**
+   * Returns every `onSuccess` action whose criteria are all met, in list order.
+   *
+   * The whole matching chain rather than only the first, because the caller
+   * needs both: it acts on `[0]`, and the one honoring "retryLimit exhausted
+   * prior to subsequent failure actions" walks the rest, falling from an
+   * exhausted `retry` to the next matching action without re-evaluating
+   * criteria. Empty when the list is absent or nothing matches.
+   *
+   * `scope` names the step this list belongs to, for a thrown
+   * {@link ResolverError}.
+   *
+   * A well-formed list whose entry is not a Success/Failure Action Object
+   * throws rather than being skipped: an unrecognized entry is indistinguishable
+   * from a step that deliberately declared no action for it, and the `goto` /
+   * `end` its author was reaching for would otherwise never happen without a
+   * word said about why.
+   */
+  resolveOnSuccess(actions, isCriterionMet, scope) {
+    // safe: `#resolveAll` validates every entry as *a* Success/Failure Action
+    // Object, not one matching this list's own field, but a well-formed
+    // `StepOnSuccessElement` only ever refracts Success Action entries — the
+    // apidom refractor types list entries positionally at parse time.
+    return this.#resolveAll(actions, isCriterionMet, 'onSuccess', scope);
+  }
+
+  /**
+   * Returns every `onFailure` action whose criteria are all met, in list order.
+   *
+   * Same matching and error behavior as {@link ActionResolver.resolveOnSuccess} —
+   * see there for the full rationale — mirrored for the step's other list.
+   */
+  resolveOnFailure(actions, isCriterionMet, scope) {
+    // safe: see the same-named comment in `resolveOnSuccess` above.
+    return this.#resolveAll(actions, isCriterionMet, 'onFailure', scope);
+  }
+
+  /**
+   * Shared implementation behind {@link ActionResolver.resolveOnSuccess} and
+   * {@link ActionResolver.resolveOnFailure}.
+   *
+   * `field` names which of the step's two lists this is, for the same
+   * `ResolverError` reason `scope` names the step: the one case that needs it —
+   * a list that is present but not a list — is exactly the case where the
+   * element's own type no longer distinguishes them. Baked in by the public
+   * method rather than taken from the caller.
+   */
+  #resolveAll(actions, isCriterionMet, field, scope) {
+    if (actions === undefined) return [];
+    // present but scalar: walking it would fail as a bare
+    // `TypeError: actions is not iterable`.
+    if (!isArrayElement(actions)) {
+      throw new ResolverError(`\`${field}\` is present but is not a list`, {
+        ...scope,
+        target: field,
+        reason: 'malformed-actions'
+      });
+    }
+    const matched = [];
+    for (const action of actions) {
+      if (!isSuccessActionElement(action) && !isFailureActionElement(action)) {
+        throw new ResolverError(`\`${field}\` contains an entry that is not a Success/Failure Action Object`, {
+          ...scope,
+          target: field,
+          reason: 'malformed-action-entry'
+        });
+      }
+      if (this.#criteriaMet(action, isCriterionMet, scope)) {
+        matched.push(action);
+      }
+    }
+    return matched;
+  }
+
+  /**
+   * Whether every criterion of the action passes. An action with no criteria
+   * matches vacuously.
+   *
+   * A `criteria` that is present but not a list, or that contains an entry
+   * that is not a Criterion Object, throws either way: an entry the resolver
+   * cannot read and a container it cannot read are both a document that does
+   * not say what its author meant, the same as an unrecognized entry in the
+   * action list itself.
+   */
+  #criteriaMet(action, isCriterionMet, scope) {
+    const criteria = action.criteria;
+    if (criteria === undefined) return true;
+    if (!isArrayElement(criteria)) {
+      throw new ResolverError("An action's `criteria` is present but is not a list", {
+        ...scope,
+        target: 'criteria',
+        reason: 'malformed-criteria'
+      });
+    }
+    for (const criterion of criteria) {
+      if (!isCriterionElement(criterion)) {
+        throw new ResolverError("An action's `criteria` contains an entry that is not a Criterion Object", {
+          ...scope,
+          target: 'criteria',
+          reason: 'malformed-criterion'
+        });
+      }
+      if (!isCriterionMet(criterion)) return false;
+    }
+    return true;
+  }
+}
+export default ActionResolver;

package/src/assembler/OpenAPI2DocumentAssembler.cjs

@@ -0,0 +1,111 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _apidomCore = require("@speclynx/apidom-core");
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomJsonPointer = require("@speclynx/apidom-json-pointer");
+var _apidomNsOpenapi = require("@speclynx/apidom-ns-openapi-2");
+var _OpenAPIDocument = _interopRequireDefault(require("../document/OpenAPIDocument.cjs"));
+var _OpenAPIOperationIndex = _interopRequireDefault(require("../document/OpenAPIOperationIndex.cjs"));
+var _AssemblerError = _interopRequireDefault(require("../errors/AssemblerError.cjs"));
+/**
+ * Assembles a standalone OpenAPI 2.0 (Swagger) document from a
+ * normalized operation element.
+ *
+ * The assembled document is a valid Swagger 2.0 specification containing
+ * only the single operation with its host, basePath, schemes, and
+ * referenced security definitions from the source document.
+ * @public
+ */
+class OpenAPI2DocumentAssembler {
+  /**
+   * Assembles a standalone Swagger 2.0 document from a normalized operation.
+   */
+  assemble(operation, document) {
+    const entry = document.parseResult.api;
+    const method = (0, _apidomCore.toValue)(operation.meta.get('http-method'));
+    const path = (0, _apidomCore.toValue)(operation.meta.get('path'));
+    if (typeof method !== 'string' || typeof path !== 'string') {
+      throw new _AssemblerError.default(`Operation is missing valid "http-method" or "path" metadata. Was it produced by OpenAPIOperationExtractor?`, {
+        uri: document.uri,
+        operationId: (0, _apidomCore.toValue)(operation.operationId)
+      });
+    }
+    if (!(0, _apidomNsOpenapi.isSwaggerElement)(entry)) {
+      throw new _AssemblerError.default(`Expected OpenAPI 2.0 document at "${document.uri}"`, {
+        uri: document.uri
+      });
+    }
+
+    // build Swagger 2.0 document
+    const swagger = new _apidomNsOpenapi.SwaggerElement({
+      swagger: entry.swagger
+    }, {
+      classes: ['api']
+    });
+    // prettier-ignore
+    {
+      if ((0, _apidomDatamodel.isElement)(entry.info)) swagger.info = entry.info;
+      if ((0, _apidomDatamodel.isElement)(entry.host)) swagger.host = entry.host;
+      if ((0, _apidomDatamodel.isElement)(entry.basePath)) swagger.basePath = entry.basePath;
+      if ((0, _apidomDatamodel.isElement)(entry.schemes)) swagger.schemes = entry.schemes;
+      if ((0, _apidomDatamodel.isElement)(entry.consumes)) swagger.consumes = entry.consumes;
+      if ((0, _apidomDatamodel.isElement)(entry.produces)) swagger.produces = entry.produces;
+      if ((0, _apidomDatamodel.isElement)(entry.tags)) swagger.tags = entry.tags;
+      if ((0, _apidomDatamodel.isElement)(entry.externalDocs)) swagger.externalDocs = entry.externalDocs;
+    }
+
+    // build paths with single operation
+    const pathItem = new _apidomNsOpenapi.PathItemElement();
+    const paths = new _apidomNsOpenapi.PathsElement();
+    pathItem.set(method, operation);
+    paths.set(path, pathItem);
+    swagger.paths = paths;
+
+    // include only referenced security definitions
+    const securityDefinitions = this.#extractReferencedSecurityDefinitions(operation, entry);
+    if (securityDefinitions.length > 0) {
+      swagger.securityDefinitions = securityDefinitions;
+    }
+
+    // wrap in ParseResultElement and return as OpenAPIDocument
+    const parseResult = new _apidomDatamodel.ParseResultElement([swagger]);
+    const operationIndex = new _OpenAPIOperationIndex.default();
+    const operationId = (0, _apidomCore.toValue)(operation.operationId);
+    if (typeof operationId === 'string' && operationId.length > 0) {
+      operationIndex.set(operationId, (0, _apidomJsonPointer.compile)(['paths', path, method]));
+    }
+    return new _OpenAPIDocument.default(document.uri, parseResult, operationIndex);
+  }
+
+  /**
+   * Extracts only the security definitions referenced by the operation's
+   * security requirements.
+   */
+  #extractReferencedSecurityDefinitions(operation, entry) {
+    const securityDefinitions = new _apidomNsOpenapi.SecurityDefinitionsElement();
+    if (!(0, _apidomDatamodel.isArrayElement)(operation.security)) return securityDefinitions;
+    if (!(0, _apidomNsOpenapi.isSecurityDefinitionsElement)(entry.securityDefinitions)) return securityDefinitions;
+
+    // collect referenced names of Security Definitions
+    const referencedNames = new Set();
+    for (const securityRequirement of operation.security) {
+      if (!(0, _apidomNsOpenapi.isSecurityRequirementElement)(securityRequirement)) continue;
+      securityRequirement.forEach((_value, keyElement) => {
+        referencedNames.add((0, _apidomCore.toValue)(keyElement));
+      });
+    }
+    if (referencedNames.size === 0) return securityDefinitions;
+    for (const name of referencedNames) {
+      const securityScheme = entry.securityDefinitions.get(name);
+      if (!(0, _apidomNsOpenapi.isSecuritySchemeElement)(securityScheme)) continue;
+      securityDefinitions.set(name, securityScheme);
+    }
+    return securityDefinitions;
+  }
+}
+var _default = exports.default = OpenAPI2DocumentAssembler;

package/src/assembler/OpenAPI2DocumentAssembler.mjs

@@ -0,0 +1,104 @@
+import { toValue } from '@speclynx/apidom-core';
+import { isArrayElement, isElement, ParseResultElement } from '@speclynx/apidom-datamodel';
+import { compile } from '@speclynx/apidom-json-pointer';
+import { SwaggerElement, PathsElement, PathItemElement, SecurityDefinitionsElement, isSwaggerElement, isSecurityRequirementElement, isSecurityDefinitionsElement, isSecuritySchemeElement } from '@speclynx/apidom-ns-openapi-2';
+import OpenAPIDocument from "../document/OpenAPIDocument.mjs";
+import OpenAPIOperationIndex from "../document/OpenAPIOperationIndex.mjs";
+import AssemblerError from "../errors/AssemblerError.mjs";
+/**
+ * Assembles a standalone OpenAPI 2.0 (Swagger) document from a
+ * normalized operation element.
+ *
+ * The assembled document is a valid Swagger 2.0 specification containing
+ * only the single operation with its host, basePath, schemes, and
+ * referenced security definitions from the source document.
+ * @public
+ */
+class OpenAPI2DocumentAssembler {
+  /**
+   * Assembles a standalone Swagger 2.0 document from a normalized operation.
+   */
+  assemble(operation, document) {
+    const entry = document.parseResult.api;
+    const method = toValue(operation.meta.get('http-method'));
+    const path = toValue(operation.meta.get('path'));
+    if (typeof method !== 'string' || typeof path !== 'string') {
+      throw new AssemblerError(`Operation is missing valid "http-method" or "path" metadata. Was it produced by OpenAPIOperationExtractor?`, {
+        uri: document.uri,
+        operationId: toValue(operation.operationId)
+      });
+    }
+    if (!isSwaggerElement(entry)) {
+      throw new AssemblerError(`Expected OpenAPI 2.0 document at "${document.uri}"`, {
+        uri: document.uri
+      });
+    }
+
+    // build Swagger 2.0 document
+    const swagger = new SwaggerElement({
+      swagger: entry.swagger
+    }, {
+      classes: ['api']
+    });
+    // prettier-ignore
+    {
+      if (isElement(entry.info)) swagger.info = entry.info;
+      if (isElement(entry.host)) swagger.host = entry.host;
+      if (isElement(entry.basePath)) swagger.basePath = entry.basePath;
+      if (isElement(entry.schemes)) swagger.schemes = entry.schemes;
+      if (isElement(entry.consumes)) swagger.consumes = entry.consumes;
+      if (isElement(entry.produces)) swagger.produces = entry.produces;
+      if (isElement(entry.tags)) swagger.tags = entry.tags;
+      if (isElement(entry.externalDocs)) swagger.externalDocs = entry.externalDocs;
+    }
+
+    // build paths with single operation
+    const pathItem = new PathItemElement();
+    const paths = new PathsElement();
+    pathItem.set(method, operation);
+    paths.set(path, pathItem);
+    swagger.paths = paths;
+
+    // include only referenced security definitions
+    const securityDefinitions = this.#extractReferencedSecurityDefinitions(operation, entry);
+    if (securityDefinitions.length > 0) {
+      swagger.securityDefinitions = securityDefinitions;
+    }
+
+    // wrap in ParseResultElement and return as OpenAPIDocument
+    const parseResult = new ParseResultElement([swagger]);
+    const operationIndex = new OpenAPIOperationIndex();
+    const operationId = toValue(operation.operationId);
+    if (typeof operationId === 'string' && operationId.length > 0) {
+      operationIndex.set(operationId, compile(['paths', path, method]));
+    }
+    return new OpenAPIDocument(document.uri, parseResult, operationIndex);
+  }
+
+  /**
+   * Extracts only the security definitions referenced by the operation's
+   * security requirements.
+   */
+  #extractReferencedSecurityDefinitions(operation, entry) {
+    const securityDefinitions = new SecurityDefinitionsElement();
+    if (!isArrayElement(operation.security)) return securityDefinitions;
+    if (!isSecurityDefinitionsElement(entry.securityDefinitions)) return securityDefinitions;
+
+    // collect referenced names of Security Definitions
+    const referencedNames = new Set();
+    for (const securityRequirement of operation.security) {
+      if (!isSecurityRequirementElement(securityRequirement)) continue;
+      securityRequirement.forEach((_value, keyElement) => {
+        referencedNames.add(toValue(keyElement));
+      });
+    }
+    if (referencedNames.size === 0) return securityDefinitions;
+    for (const name of referencedNames) {
+      const securityScheme = entry.securityDefinitions.get(name);
+      if (!isSecuritySchemeElement(securityScheme)) continue;
+      securityDefinitions.set(name, securityScheme);
+    }
+    return securityDefinitions;
+  }
+}
+export default OpenAPI2DocumentAssembler;