@jentic/arazzo-parser 1.0.0-alpha.32 → 1.0.0-alpha.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jentic/arazzo-parser",
-  "version": "1.0.0-alpha.32",
+  "version": "1.0.0-alpha.33",
   "description": "Parser for Arazzo Documents producing SpecLynx ApiDOM data model.",
   "keywords": [
     "arazzo",
@@ -48,9 +48,14 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime-corejs3": "^8.0.0",
+    "@speclynx/apidom-core": "^5.0.1",
     "@speclynx/apidom-datamodel": "^5.0.1",
     "@speclynx/apidom-error": "^5.0.1",
+    "@speclynx/apidom-json-pointer": "^5.0.1",
     "@speclynx/apidom-ns-arazzo-1": "^5.0.1",
+    "@speclynx/apidom-ns-openapi-2": "^5.0.1",
+    "@speclynx/apidom-ns-openapi-3-0": "^5.0.1",
+    "@speclynx/apidom-ns-openapi-3-1": "^5.0.1",
     "@speclynx/apidom-parser-adapter-arazzo-json-1": "^5.0.1",
     "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "^5.0.1",
     "@speclynx/apidom-parser-adapter-openapi-json-2": "^5.0.1",
@@ -63,9 +68,6 @@
     "ramda-adjunct": "^6.0.0",
     "type-fest": "^5.4.4"
   },
-  "devDependencies": {
-    "@speclynx/apidom-core": "^5.0.1"
-  },
   "files": [
     "src/**/*.mjs",
     "src/**/*.cjs",
@@ -76,5 +78,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "a5ea37ac6a1bd3b56df95cdb308a9b62a4cc375b"
+  "gitHead": "a17270442ac27615af0348fad9c71817d818151f"
 }

package/src/index.cjs

@@ -3,6 +3,12 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
+Object.defineProperty(exports, "attachStepOperations", {
+  enumerable: true,
+  get: function () {
+    return _stepOperations.attachStepOperations;
+  }
+});
 Object.defineProperty(exports, "defaultParseArazzoOptions", {
   enumerable: true,
   get: function () {
@@ -15,6 +21,12 @@ Object.defineProperty(exports, "defaultParseOpenAPIOptions", {
     return _parseOpenapi.defaultOptions;
   }
 });
+Object.defineProperty(exports, "findStepOperation", {
+  enumerable: true,
+  get: function () {
+    return _stepOperations.findStepOperation;
+  }
+});
 Object.defineProperty(exports, "parseArazzo", {
   enumerable: true,
   get: function () {
@@ -28,4 +40,5 @@ Object.defineProperty(exports, "parseOpenAPI", {
   }
 });
 var _parseArazzo = require("./parse-arazzo.cjs");
+var _stepOperations = require("./step-operations.cjs");
 var _parseOpenapi = require("./parse-openapi.cjs");

package/src/index.mjs

@@ -1,2 +1,3 @@
 export { parse as parseArazzo, defaultOptions as defaultParseArazzoOptions } from "./parse-arazzo.mjs";
+export { findStepOperation, attachStepOperations } from "./step-operations.mjs";
 export { parse as parseOpenAPI, defaultOptions as defaultParseOpenAPIOptions } from "./parse-openapi.mjs";

package/src/step-operations.cjs

@@ -0,0 +1,156 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.attachStepOperations = attachStepOperations;
+exports.findStepOperation = findStepOperation;
+var _apidomCore = require("@speclynx/apidom-core");
+var _apidomJsonPointer = require("@speclynx/apidom-json-pointer");
+var _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
+var _apidomNsOpenapi = require("@speclynx/apidom-ns-openapi-2");
+var _apidomNsOpenapi2 = require("@speclynx/apidom-ns-openapi-3-0");
+var _apidomNsOpenapi3 = require("@speclynx/apidom-ns-openapi-3-1");
+/**
+ * HTTP method and path of the OpenAPI operation targeted by an Arazzo step.
+ * @public
+ */
+
+/**
+ * Minimal shape of a plain Arazzo Document needed to attach step operations.
+ * @public
+ */
+
+/**
+ * A plain Arazzo Document whose steps may carry the `_operation` they target. Every other field
+ * of the document type, and of its workflows and steps, is preserved as is.
+ * @public
+ */
+
+// OpenAPI 3.1 path items extend the OpenAPI 3.0 ones, so isPathItem3Element covers both
+const pathItemOperations = pathItem => ({
+  get: pathItem.getField,
+  put: pathItem.put,
+  post: pathItem.post,
+  delete: pathItem.deleteField,
+  options: pathItem.options,
+  head: pathItem.head,
+  patch: pathItem.patch,
+  trace: (0, _apidomNsOpenapi2.isPathItemElement)(pathItem) ? pathItem.trace : undefined
+});
+
+// resolves a (possibly relative) URI against the document it appears in, as far as possible
+const resolveURI = (uri, baseURI) => {
+  try {
+    return new URL(uri, baseURI).href;
+  } catch {
+    return uri;
+  }
+};
+
+// whether a literal URL targets the document of the source description, as declared or as retrieved
+const targetsSource = (sourceDescription, documentURI, baseURI) => {
+  const target = resolveURI(documentURI, baseURI);
+  const url = sourceDescription.url?.toValue();
+  const retrievalURI = sourceDescription.meta.get('parseResult')?.meta.get('retrievalURI');
+  return [url, retrievalURI].some(uri => uri !== undefined && (uri === documentURI || resolveURI(uri, baseURI) === target));
+};
+const pointerTokens = pointer => pointer.split('/').slice(1).map(token => token.replace(/~1/g, '/').replace(/~0/g, '~'));
+
+// resolves a JSON Pointer against a source document, so it can target operations of both
+// `paths` entries and reusable Path Items (`#/components/pathItems/...`)
+const operationAtPointer = (api, pointer) => {
+  const tokens = pointerTokens(pointer);
+  const withPath = method => ({
+    method: method.toUpperCase(),
+    ...(tokens[0] === 'paths' && {
+      path: tokens[1]
+    })
+  });
+  const evaluateAt = parts => {
+    try {
+      return (0, _apidomJsonPointer.evaluate)(api, (0, _apidomJsonPointer.compile)(parts));
+    } catch {
+      return undefined;
+    }
+  };
+  const target = evaluateAt(tokens);
+  // a pointer to a path item (no method) is unambiguous only when it has a single operation
+  if ((0, _apidomNsOpenapi.isPathItemElement)(target) || (0, _apidomNsOpenapi2.isPathItemElement)(target)) {
+    const defined = Object.entries(pathItemOperations(target)).filter(([, operation]) => operation);
+    return defined.length === 1 ? withPath(defined[0][0]) : undefined;
+  }
+  const method = tokens[tokens.length - 1];
+  const parent = evaluateAt(tokens.slice(0, -1));
+  if (!target || !((0, _apidomNsOpenapi.isPathItemElement)(parent) || (0, _apidomNsOpenapi2.isPathItemElement)(parent))) return undefined;
+  return Object.keys(pathItemOperations(parent)).includes(method) ? withPath(method) : undefined;
+};
+
+/**
+ * Finds the OpenAPI operation targeted by an Arazzo step in the `openapi` source descriptions
+ * parsed along with the Arazzo Document (see the `sourceDescriptions` parser option).
+ * @param parseResult - The result of parsing an Arazzo Document with source descriptions
+ * @param step - The step's `operationId` or `operationPath`
+ * @returns The operation's HTTP method and path, or undefined when it can't be located
+ * @public
+ */
+function findStepOperation(parseResult, {
+  operationId,
+  operationPath
+}) {
+  const reference = operationPath ?? operationId;
+  if (!reference || !(0, _apidomNsArazzo.isArazzoSpecification1Element)(parseResult.api)) return undefined;
+  // `$sourceDescriptions.{name}.{operationId}` and `{$sourceDescriptions.{name}.url}#{pointer}` name their source
+  const [, sourceName, qualifiedId] = /^\{?\$sourceDescriptions\.([^.]+)\.(.+)$/.exec(reference) ?? [];
+  const pointer = operationPath && _apidomJsonPointer.URIFragmentIdentifier.fromURIReference(operationPath);
+  // a literal URL (no `$sourceDescriptions` expression) names its source by the document it targets
+  const documentURI = operationPath && !sourceName ? operationPath.split('#')[0].replace(/^\{|\}$/g, '') : '';
+  const baseURI = parseResult.meta.get('retrievalURI');
+  let found;
+  parseResult.api.sourceDescriptions?.forEach(sourceDescription => {
+    if (found || !(0, _apidomNsArazzo.isSourceDescriptionElement)(sourceDescription)) return;
+    if (sourceDescription.type && sourceDescription.type.toValue() !== 'openapi') return;
+    if (sourceName && sourceDescription.name?.toValue() !== sourceName) return;
+    // the source must be the one the URL targets, and it is not searched when it failed to load
+    if (documentURI && !targetsSource(sourceDescription, documentURI, baseURI)) return;
+    const api = sourceDescription.meta.get('parseResult')?.api;
+    if (!(0, _apidomNsOpenapi.isSwaggerElement)(api) && !(0, _apidomNsOpenapi2.isOpenApi3_0Element)(api) && !(0, _apidomNsOpenapi3.isOpenApi3_1Element)(api)) return;
+    if (pointer) {
+      found = operationAtPointer(api, pointer);
+      return;
+    }
+    api.paths?.forEach((pathItem, key) => {
+      if (found || !(0, _apidomNsOpenapi.isPathItemElement)(pathItem) && !(0, _apidomNsOpenapi2.isPathItemElement)(pathItem)) return;
+      const path = String(key.toValue());
+      for (const [method, operation] of Object.entries(pathItemOperations(pathItem))) {
+        if (operation?.operationId?.toValue() === (qualifiedId ?? operationId)) {
+          found = {
+            method: method.toUpperCase(),
+            path
+          };
+          return;
+        }
+      }
+    });
+  });
+  return found;
+}
+
+/**
+ * Converts an Arazzo Document element to a plain object and sets `_operation` on every step that
+ * targets an operation of the `openapi` source descriptions parsed along with it.
+ * @param element - The Arazzo Document element, e.g. the (dereferenced) result of the parse result
+ * @param parseResult - The result of parsing the Arazzo Document with source descriptions
+ * @returns The plain Arazzo Document, typed with `_operation` on its steps and set on the resolved ones
+ * @public
+ */
+function attachStepOperations(element, parseResult) {
+  const doc = (0, _apidomCore.toValue)(element);
+  doc?.workflows?.forEach(workflow => workflow.steps?.forEach(step => {
+    const operation = findStepOperation(parseResult, step);
+    if (operation) Object.assign(step, {
+      _operation: operation
+    });
+  }));
+  return doc;
+}

package/src/step-operations.mjs

@@ -0,0 +1,150 @@
+import { toValue } from '@speclynx/apidom-core';
+import { compile, evaluate, URIFragmentIdentifier } from '@speclynx/apidom-json-pointer';
+import { isArazzoSpecification1Element, isSourceDescriptionElement } from '@speclynx/apidom-ns-arazzo-1';
+import { isSwaggerElement, isPathItemElement as isPathItem2Element } from '@speclynx/apidom-ns-openapi-2';
+import { isOpenApi3_0Element, isPathItemElement as isPathItem3Element } from '@speclynx/apidom-ns-openapi-3-0';
+import { isOpenApi3_1Element } from '@speclynx/apidom-ns-openapi-3-1';
+
+/**
+ * HTTP method and path of the OpenAPI operation targeted by an Arazzo step.
+ * @public
+ */
+
+/**
+ * Minimal shape of a plain Arazzo Document needed to attach step operations.
+ * @public
+ */
+
+/**
+ * A plain Arazzo Document whose steps may carry the `_operation` they target. Every other field
+ * of the document type, and of its workflows and steps, is preserved as is.
+ * @public
+ */
+
+// OpenAPI 3.1 path items extend the OpenAPI 3.0 ones, so isPathItem3Element covers both
+const pathItemOperations = pathItem => ({
+  get: pathItem.getField,
+  put: pathItem.put,
+  post: pathItem.post,
+  delete: pathItem.deleteField,
+  options: pathItem.options,
+  head: pathItem.head,
+  patch: pathItem.patch,
+  trace: isPathItem3Element(pathItem) ? pathItem.trace : undefined
+});
+
+// resolves a (possibly relative) URI against the document it appears in, as far as possible
+const resolveURI = (uri, baseURI) => {
+  try {
+    return new URL(uri, baseURI).href;
+  } catch {
+    return uri;
+  }
+};
+
+// whether a literal URL targets the document of the source description, as declared or as retrieved
+const targetsSource = (sourceDescription, documentURI, baseURI) => {
+  const target = resolveURI(documentURI, baseURI);
+  const url = sourceDescription.url?.toValue();
+  const retrievalURI = sourceDescription.meta.get('parseResult')?.meta.get('retrievalURI');
+  return [url, retrievalURI].some(uri => uri !== undefined && (uri === documentURI || resolveURI(uri, baseURI) === target));
+};
+const pointerTokens = pointer => pointer.split('/').slice(1).map(token => token.replace(/~1/g, '/').replace(/~0/g, '~'));
+
+// resolves a JSON Pointer against a source document, so it can target operations of both
+// `paths` entries and reusable Path Items (`#/components/pathItems/...`)
+const operationAtPointer = (api, pointer) => {
+  const tokens = pointerTokens(pointer);
+  const withPath = method => ({
+    method: method.toUpperCase(),
+    ...(tokens[0] === 'paths' && {
+      path: tokens[1]
+    })
+  });
+  const evaluateAt = parts => {
+    try {
+      return evaluate(api, compile(parts));
+    } catch {
+      return undefined;
+    }
+  };
+  const target = evaluateAt(tokens);
+  // a pointer to a path item (no method) is unambiguous only when it has a single operation
+  if (isPathItem2Element(target) || isPathItem3Element(target)) {
+    const defined = Object.entries(pathItemOperations(target)).filter(([, operation]) => operation);
+    return defined.length === 1 ? withPath(defined[0][0]) : undefined;
+  }
+  const method = tokens[tokens.length - 1];
+  const parent = evaluateAt(tokens.slice(0, -1));
+  if (!target || !(isPathItem2Element(parent) || isPathItem3Element(parent))) return undefined;
+  return Object.keys(pathItemOperations(parent)).includes(method) ? withPath(method) : undefined;
+};
+
+/**
+ * Finds the OpenAPI operation targeted by an Arazzo step in the `openapi` source descriptions
+ * parsed along with the Arazzo Document (see the `sourceDescriptions` parser option).
+ * @param parseResult - The result of parsing an Arazzo Document with source descriptions
+ * @param step - The step's `operationId` or `operationPath`
+ * @returns The operation's HTTP method and path, or undefined when it can't be located
+ * @public
+ */
+export function findStepOperation(parseResult, {
+  operationId,
+  operationPath
+}) {
+  const reference = operationPath ?? operationId;
+  if (!reference || !isArazzoSpecification1Element(parseResult.api)) return undefined;
+  // `$sourceDescriptions.{name}.{operationId}` and `{$sourceDescriptions.{name}.url}#{pointer}` name their source
+  const [, sourceName, qualifiedId] = /^\{?\$sourceDescriptions\.([^.]+)\.(.+)$/.exec(reference) ?? [];
+  const pointer = operationPath && URIFragmentIdentifier.fromURIReference(operationPath);
+  // a literal URL (no `$sourceDescriptions` expression) names its source by the document it targets
+  const documentURI = operationPath && !sourceName ? operationPath.split('#')[0].replace(/^\{|\}$/g, '') : '';
+  const baseURI = parseResult.meta.get('retrievalURI');
+  let found;
+  parseResult.api.sourceDescriptions?.forEach(sourceDescription => {
+    if (found || !isSourceDescriptionElement(sourceDescription)) return;
+    if (sourceDescription.type && sourceDescription.type.toValue() !== 'openapi') return;
+    if (sourceName && sourceDescription.name?.toValue() !== sourceName) return;
+    // the source must be the one the URL targets, and it is not searched when it failed to load
+    if (documentURI && !targetsSource(sourceDescription, documentURI, baseURI)) return;
+    const api = sourceDescription.meta.get('parseResult')?.api;
+    if (!isSwaggerElement(api) && !isOpenApi3_0Element(api) && !isOpenApi3_1Element(api)) return;
+    if (pointer) {
+      found = operationAtPointer(api, pointer);
+      return;
+    }
+    api.paths?.forEach((pathItem, key) => {
+      if (found || !isPathItem2Element(pathItem) && !isPathItem3Element(pathItem)) return;
+      const path = String(key.toValue());
+      for (const [method, operation] of Object.entries(pathItemOperations(pathItem))) {
+        if (operation?.operationId?.toValue() === (qualifiedId ?? operationId)) {
+          found = {
+            method: method.toUpperCase(),
+            path
+          };
+          return;
+        }
+      }
+    });
+  });
+  return found;
+}
+
+/**
+ * Converts an Arazzo Document element to a plain object and sets `_operation` on every step that
+ * targets an operation of the `openapi` source descriptions parsed along with it.
+ * @param element - The Arazzo Document element, e.g. the (dereferenced) result of the parse result
+ * @param parseResult - The result of parsing the Arazzo Document with source descriptions
+ * @returns The plain Arazzo Document, typed with `_operation` on its steps and set on the resolved ones
+ * @public
+ */
+export function attachStepOperations(element, parseResult) {
+  const doc = toValue(element);
+  doc?.workflows?.forEach(workflow => workflow.steps?.forEach(step => {
+    const operation = findStepOperation(parseResult, step);
+    if (operation) Object.assign(step, {
+      _operation: operation
+    });
+  }));
+  return doc;
+}

package/types/arazzo-parser.d.ts

@@ -1,7 +1,18 @@
 import type { ApiDOMReferenceOptions } from '@speclynx/apidom-reference/configuration/empty';
+import type { Element as Element_2 } from '@speclynx/apidom-datamodel';
 import { ParseResultElement } from '@speclynx/apidom-datamodel';
 import type { PartialDeep } from 'type-fest';
 
+/**
+ * Converts an Arazzo Document element to a plain object and sets `_operation` on every step that
+ * targets an operation of the `openapi` source descriptions parsed along with it.
+ * @param element - The Arazzo Document element, e.g. the (dereferenced) result of the parse result
+ * @param parseResult - The result of parsing the Arazzo Document with source descriptions
+ * @returns The plain Arazzo Document, typed with `_operation` on its steps and set on the resolved ones
+ * @public
+ */
+export declare function attachStepOperations<T extends StepOperationsDocument = StepOperationsDocument>(element: Element_2 | undefined, parseResult: ParseResultElement): StepOperationsResult<T>;
+
 /**
  * Default reference options for parsing Arazzo Documents.
  * @public
@@ -14,6 +25,19 @@ export declare const defaultParseArazzoOptions: ParseArazzoOptions;
  */
 export declare const defaultParseOpenAPIOptions: ParseOpenAPIOptions;
 
+/**
+ * Finds the OpenAPI operation targeted by an Arazzo step in the `openapi` source descriptions
+ * parsed along with the Arazzo Document (see the `sourceDescriptions` parser option).
+ * @param parseResult - The result of parsing an Arazzo Document with source descriptions
+ * @param step - The step's `operationId` or `operationPath`
+ * @returns The operation's HTTP method and path, or undefined when it can't be located
+ * @public
+ */
+export declare function findStepOperation(parseResult: ParseResultElement, { operationId, operationPath }: {
+    operationId?: string;
+    operationPath?: string;
+}): StepOperation | undefined;
+
 /**
  * Parses an Arazzo Document from an object.
  * @param source - The Arazzo Document as a plain object
@@ -88,4 +112,40 @@ export declare type ParseOpenAPIOptions = PartialDeep<ApiDOMReferenceOptions>;
 
 export { ParseResultElement }
 
+/**
+ * HTTP method and path of the OpenAPI operation targeted by an Arazzo step.
+ * @public
+ */
+export declare interface StepOperation {
+    /** upper-case HTTP method, e.g. `GET` */
+    method: string;
+    path?: string;
+}
+
+/**
+ * Minimal shape of a plain Arazzo Document needed to attach step operations.
+ * @public
+ */
+export declare interface StepOperationsDocument {
+    workflows?: {
+        steps?: {
+            operationId?: string;
+            operationPath?: string;
+        }[];
+    }[];
+}
+
+/**
+ * A plain Arazzo Document whose steps may carry the `_operation` they target. Every other field
+ * of the document type, and of its workflows and steps, is preserved as is.
+ * @public
+ */
+export declare type StepOperationsResult<T extends StepOperationsDocument = StepOperationsDocument> = {
+    [K in keyof T]: K extends 'workflows' ? NonNullable<T[K]> extends readonly (infer Workflow)[] ? {
+        [W in keyof Workflow]: W extends 'steps' ? NonNullable<Workflow[W]> extends readonly (infer Step)[] ? (Step & {
+            _operation?: StepOperation;
+        })[] : Workflow[W] : Workflow[W];
+    }[] : T[K] : T[K];
+};
+
 export { }