@swagger-api/apidom-ns-openapi-3-1 1.0.0-alpha.0 → 1.0.0-alpha.10

package/es/index.mjs

@@ -7,7 +7,7 @@ export { default as refractorPluginNormalizeSecurityRequirements } from "./refra
 export { default as refractorPluginNormalizeServers } from "./refractor/plugins/normalize-servers.mjs";
 export { default as refractorPluginNormalizeOperationIds } from "./refractor/plugins/normalize-operation-ids.mjs";
 export { default as refractorPluginNormalizeParameterExamples } from "./refractor/plugins/normalize-parameter-examples.mjs";
-export { default as refractorPluginNormalizeHeaderExamples } from "./refractor/plugins/normalize-header-examples.mjs";
+export { default as refractorPluginNormalizeHeaderExamples } from "./refractor/plugins/normalize-header-examples/index.mjs";
 export { default as createToolbox } from "./refractor/toolbox.mjs";
 export { default as specificationObj } from "./refractor/specification.mjs";
 export { AlternatingVisitor } from '@swagger-api/apidom-ns-openapi-3-0';

package/es/refractor/plugins/normalize-header-examples/NormalizeStorage.mjs

@@ -0,0 +1,34 @@
+import { ArrayElement, ObjectElement, isObjectElement, isArrayElement } from '@swagger-api/apidom-core';
+class NormalizeStorage {
+  internalStore;
+  constructor(storageElement, storageField, storageSubField) {
+    this.storageElement = storageElement;
+    this.storageField = storageField;
+    this.storageSubField = storageSubField;
+  }
+  get store() {
+    if (!this.internalStore) {
+      let rootStore = this.storageElement.get(this.storageField);
+      if (!isObjectElement(rootStore)) {
+        rootStore = new ObjectElement();
+        this.storageElement.set(this.storageField, rootStore);
+      }
+      let store = rootStore.get(this.storageSubField);
+      if (!isArrayElement(store)) {
+        store = new ArrayElement();
+        rootStore.set(this.storageSubField, store);
+      }
+      this.internalStore = store;
+    }
+    return this.internalStore;
+  }
+  append(pointer) {
+    if (!this.includes(pointer)) {
+      this.store.push(pointer);
+    }
+  }
+  includes(pointer) {
+    return this.store.includes(pointer);
+  }
+}
+export default NormalizeStorage;

package/es/refractor/plugins/{normalize-header-examples.mjs → normalize-header-examples/index.mjs}

@@ -1,4 +1,5 @@
 import { cloneDeep } from '@swagger-api/apidom-core';
+import NormalizeStorage from "./NormalizeStorage.mjs";
 /**
  * Override of Schema.example and Schema.examples field inside the Header Objects.
  *
@@ -10,13 +11,27 @@ import { cloneDeep } from '@swagger-api/apidom-core';
  *
  * The example value SHALL override the example provided by the schema.
  * Furthermore, if referencing a schema that contains an example, the examples value SHALL override the example provided by the schema.
+ *
+ * NOTE: this plugin is idempotent
  */
-/* eslint-disable no-param-reassign */
-const plugin = () => ({
-  predicates
-}) => {
+const plugin = ({
+  storageField = 'x-normalized'
+} = {}) => toolbox => {
+  const {
+    predicates,
+    ancestorLineageToJSONPointer
+  } = toolbox;
+  let storage;
   return {
     visitor: {
+      OpenApi3_1Element: {
+        enter(element) {
+          storage = new NormalizeStorage(element, storageField, 'header-examples');
+        },
+        leave() {
+          storage = undefined;
+        }
+      },
       HeaderElement: {
         leave(headerElement, key, parent, path, ancestors) {
           var _headerElement$schema, _headerElement$schema2;
@@ -33,6 +48,12 @@ const plugin = () => ({
           if (typeof ((_headerElement$schema = headerElement.schema) === null || _headerElement$schema === void 0 ? void 0 : _headerElement$schema.example) === 'undefined' && typeof ((_headerElement$schema2 = headerElement.schema) === null || _headerElement$schema2 === void 0 ? void 0 : _headerElement$schema2.examples) === 'undefined') {
             return;
           }
+          const headerJSONPointer = ancestorLineageToJSONPointer([...ancestors, parent, headerElement]);
+
+          // skip visiting this Header Object if it's already normalized
+          if (storage.includes(headerJSONPointer)) {
+            return;
+          }
 
           /**
            * Header.examples and Schema.examples have preferences over the older
@@ -45,9 +66,11 @@ const plugin = () => ({
             });
             if (typeof headerElement.schema.examples !== 'undefined') {
               headerElement.schema.set('examples', examples);
+              storage.append(headerJSONPointer);
             }
             if (typeof headerElement.schema.example !== 'undefined') {
-              headerElement.schema.set('example', examples);
+              headerElement.schema.set('example', examples[0]);
+              storage.append(headerJSONPointer);
             }
             return;
           }
@@ -58,9 +81,11 @@ const plugin = () => ({
           if (typeof headerElement.example !== 'undefined') {
             if (typeof headerElement.schema.examples !== 'undefined') {
               headerElement.schema.set('examples', [cloneDeep(headerElement.example)]);
+              storage.append(headerJSONPointer);
             }
             if (typeof headerElement.schema.example !== 'undefined') {
               headerElement.schema.set('example', cloneDeep(headerElement.example));
+              storage.append(headerJSONPointer);
             }
           }
         }
@@ -68,6 +93,4 @@ const plugin = () => ({
     }
   };
 };
-/* eslint-enable */
-
 export default plugin;

package/es/refractor/plugins/normalize-operation-ids.mjs

@@ -1,5 +1,6 @@
 import { last, defaultTo, groupBy } from 'ramda';
 import { toValue, cloneDeep } from '@swagger-api/apidom-core';
+import NormalizeStorage from "./normalize-header-examples/NormalizeStorage.mjs";
 const removeSpaces = operationId => {
   return operationId.replace(/\s/g, '');
 };
@@ -33,21 +34,29 @@ const normalizeOperationId = (operationId, path, method) => {
  * This plugin also guarantees the uniqueness of all defined Operation.operationId fields,
  * and make sure Link.operationId fields are pointing to correct and normalized Operation.operationId fields.
  *
+ * NOTE: this plugin is idempotent
  */
-/* eslint-disable no-param-reassign */
 
+/* eslint-disable no-param-reassign */
 const plugin = ({
+  storageField = 'x-normalized',
   operationIdNormalizer = normalizeOperationId
-} = {}) => ({
-  predicates,
-  namespace
-}) => {
-  const paths = [];
+} = {}) => toolbox => {
+  const {
+    predicates,
+    ancestorLineageToJSONPointer,
+    namespace
+  } = toolbox;
+  const pathTemplates = [];
   const normalizedOperations = [];
   const links = [];
+  let storage;
   return {
     visitor: {
       OpenApi3_1Element: {
+        enter(element) {
+          storage = new NormalizeStorage(element, storageField, 'operation-ids');
+        },
         leave() {
           // group normalized operations by normalized operationId
           const normalizedOperationGroups = groupBy(operationElement => {
@@ -84,30 +93,37 @@ const plugin = ({
           // cleanup the references
           normalizedOperations.length = 0;
           links.length = 0;
+          storage = undefined;
         }
       },
       PathItemElement: {
         enter(pathItemElement) {
           // `path` meta may not be always available, e.g. in Callback Object or Components Object
-          const path = defaultTo('path', toValue(pathItemElement.meta.get('path')));
-          paths.push(path);
+          const pathTemplate = defaultTo('path', toValue(pathItemElement.meta.get('path')));
+          pathTemplates.push(pathTemplate);
         },
         leave() {
-          paths.pop();
+          pathTemplates.pop();
         }
       },
       OperationElement: {
-        enter(operationElement) {
+        enter(operationElement, key, parent, path, ancestors) {
           // operationId field is undefined, needs no normalization
           if (typeof operationElement.operationId === 'undefined') return;
+          const operationJSONPointer = ancestorLineageToJSONPointer([...ancestors, parent, operationElement]);
+
+          // skip visiting this Operation Object if it's already normalized
+          if (storage.includes(operationJSONPointer)) {
+            return;
+          }
 
           // cast operationId to string type
           const originalOperationId = String(toValue(operationElement.operationId));
           // perform operationId normalization
-          const path = last(paths);
+          const pathTemplate = last(pathTemplates);
           // `http-method` meta may not be always available, e.g. in Callback Object or Components Object
           const method = defaultTo('method', toValue(operationElement.meta.get('http-method')));
-          const normalizedOperationId = operationIdNormalizer(originalOperationId, path, method);
+          const normalizedOperationId = operationIdNormalizer(originalOperationId, pathTemplate, method);
 
           // normalization is not necessary
           if (originalOperationId === normalizedOperationId) return;
@@ -117,6 +133,7 @@ const plugin = ({
           operationElement.set('__originalOperationId', originalOperationId);
           operationElement.meta.set('originalOperationId', originalOperationId);
           normalizedOperations.push(operationElement);
+          storage.append(operationJSONPointer);
         }
       },
       LinkElement: {

package/es/refractor/plugins/normalize-parameter-examples.mjs

@@ -1,4 +1,5 @@
 import { cloneDeep } from '@swagger-api/apidom-core';
+import NormalizeStorage from "./normalize-header-examples/NormalizeStorage.mjs";
 /**
  * Override of Schema.example and Schema.examples field inside the Parameter Objects.
  *
@@ -10,13 +11,27 @@ import { cloneDeep } from '@swagger-api/apidom-core';
  *
  * The example value SHALL override the example provided by the schema.
  * Furthermore, if referencing a schema that contains an example, the examples value SHALL override the example provided by the schema.
+ *
+ * NOTE: this plugin is idempotent
  */
-/* eslint-disable no-param-reassign */
-const plugin = () => ({
-  predicates
-}) => {
+const plugin = ({
+  storageField = 'x-normalized'
+} = {}) => toolbox => {
+  const {
+    predicates,
+    ancestorLineageToJSONPointer
+  } = toolbox;
+  let storage;
   return {
     visitor: {
+      OpenApi3_1Element: {
+        enter(element) {
+          storage = new NormalizeStorage(element, storageField, 'parameter-examples');
+        },
+        leave() {
+          storage = undefined;
+        }
+      },
       ParameterElement: {
         leave(parameterElement, key, parent, path, ancestors) {
           var _parameterElement$sch, _parameterElement$sch2;
@@ -33,6 +48,12 @@ const plugin = () => ({
           if (typeof ((_parameterElement$sch = parameterElement.schema) === null || _parameterElement$sch === void 0 ? void 0 : _parameterElement$sch.example) === 'undefined' && typeof ((_parameterElement$sch2 = parameterElement.schema) === null || _parameterElement$sch2 === void 0 ? void 0 : _parameterElement$sch2.examples) === 'undefined') {
             return;
           }
+          const parameterJSONPointer = ancestorLineageToJSONPointer([...ancestors, parent, parameterElement]);
+
+          // skip visiting this Parameter Object if it's already normalized
+          if (storage.includes(parameterJSONPointer)) {
+            return;
+          }
 
           /**
            * Parameter.examples and Schema.examples have preferences over the older
@@ -45,9 +66,11 @@ const plugin = () => ({
             });
             if (typeof parameterElement.schema.examples !== 'undefined') {
               parameterElement.schema.set('examples', examples);
+              storage.append(parameterJSONPointer);
             }
             if (typeof parameterElement.schema.example !== 'undefined') {
-              parameterElement.schema.set('example', examples);
+              parameterElement.schema.set('example', examples[0]);
+              storage.append(parameterJSONPointer);
             }
             return;
           }
@@ -58,9 +81,11 @@ const plugin = () => ({
           if (typeof parameterElement.example !== 'undefined') {
             if (typeof parameterElement.schema.examples !== 'undefined') {
               parameterElement.schema.set('examples', [cloneDeep(parameterElement.example)]);
+              storage.append(parameterJSONPointer);
             }
             if (typeof parameterElement.schema.example !== 'undefined') {
               parameterElement.schema.set('example', cloneDeep(parameterElement.example));
+              storage.append(parameterJSONPointer);
             }
           }
         }
@@ -68,6 +93,4 @@ const plugin = () => ({
     }
   };
 };
-/* eslint-enable */
-
 export default plugin;

package/es/refractor/plugins/normalize-parameters.mjs

@@ -1,6 +1,7 @@
 import { uniqWith, pathOr, last } from 'ramda';
 import { toValue } from '@swagger-api/apidom-core';
 import { OperationParametersElement } from '@swagger-api/apidom-ns-openapi-3-0';
+import NormalizeStorage from "./normalize-header-examples/NormalizeStorage.mjs";
 /**
  * Inheritance of Parameter Objects.
  *
@@ -9,11 +10,17 @@ import { OperationParametersElement } from '@swagger-api/apidom-ns-openapi-3-0';
  * A list of parameters that are applicable for this operation. If a parameter is already defined at the Path Item,
  * the new definition will override it but can never remove it. The list MUST NOT include duplicated parameters.
  * A unique parameter is defined by a combination of a name and location.
+ *
+ * NOTE: this plugin is idempotent
  */
 /* eslint-disable no-param-reassign */
-const plugin = () => ({
-  predicates
-}) => {
+const plugin = ({
+  storageField = 'x-normalized'
+} = {}) => toolbox => {
+  const {
+    predicates,
+    ancestorLineageToJSONPointer
+  } = toolbox;
   /**
    * Establishes identity between two Parameter Objects.
    *
@@ -29,8 +36,17 @@ const plugin = () => ({
     return toValue(parameter1.name) === toValue(parameter2.name) && toValue(parameter1.in) === toValue(parameter2.in);
   };
   const pathItemParameters = [];
+  let storage;
   return {
     visitor: {
+      OpenApi3_1Element: {
+        enter(element) {
+          storage = new NormalizeStorage(element, storageField, 'parameters');
+        },
+        leave() {
+          storage = undefined;
+        }
+      },
       PathItemElement: {
         enter(pathItemElement, key, parent, path, ancestors) {
           // skip visiting this Path Item
@@ -51,18 +67,25 @@ const plugin = () => ({
         }
       },
       OperationElement: {
-        leave(operationElement) {
+        leave(operationElement, key, parent, path, ancestors) {
           const parentPathItemParameters = last(pathItemParameters);
 
           // no Path Item Object parameters to inherit from
           if (!Array.isArray(parentPathItemParameters) || parentPathItemParameters.length === 0) {
             return;
           }
+          const operationJSONPointer = ancestorLineageToJSONPointer([...ancestors, parent, operationElement]);
+
+          // skip visiting this Operation Object if it's already normalized
+          if (storage.includes(operationJSONPointer)) {
+            return;
+          }
           const operationParameters = pathOr([], ['parameters', 'content'], operationElement);
 
           // prefers the first item if two items compare equal based on the predicate
           const mergedParameters = uniqWith(parameterEquals, [...operationParameters, ...parentPathItemParameters]);
           operationElement.parameters = new OperationParametersElement(mergedParameters);
+          storage.append(operationJSONPointer);
         }
       }
     }

package/es/refractor/plugins/normalize-security-requirements.mjs

@@ -1,4 +1,5 @@
 import { OperationSecurityElement } from '@swagger-api/apidom-ns-openapi-3-0';
+import NormalizeStorage from "./normalize-header-examples/NormalizeStorage.mjs";
 /**
  * Override of Security Requirement Objects.
  *
@@ -8,22 +9,30 @@ import { OperationSecurityElement } from '@swagger-api/apidom-ns-openapi-3-0';
  * To remove a top-level security declaration, an empty array can be used.
  * When a list of Security Requirement Objects is defined on the OpenAPI Object or Operation Object,
  * only one of the Security Requirement Objects in the list needs to be satisfied to authorize the request.
+ *
+ * NOTE: this plugin is idempotent
  */
-
 /* eslint-disable no-param-reassign */
-const plugin = () => ({
-  predicates
-}) => {
+const plugin = ({
+  storageField = 'x-normalized'
+} = {}) => toolbox => {
+  const {
+    predicates,
+    ancestorLineageToJSONPointer
+  } = toolbox;
   let topLevelSecurity;
+  let storage;
   return {
     visitor: {
       OpenApi3_1Element: {
         enter(openapiElement) {
+          storage = new NormalizeStorage(openapiElement, storageField, 'security-requirements');
           if (predicates.isArrayElement(openapiElement.security)) {
             topLevelSecurity = openapiElement.security;
           }
         },
         leave() {
+          storage = undefined;
           topLevelSecurity = undefined;
         }
       },
@@ -33,11 +42,18 @@ const plugin = () => ({
           if (ancestors.some(predicates.isComponentsElement)) {
             return;
           }
+          const operationJSONPointer = ancestorLineageToJSONPointer([...ancestors, parent, operationElement]);
+
+          // skip visiting this Operation Object if it's already normalized
+          if (storage.includes(operationJSONPointer)) {
+            return;
+          }
           const missingOperationLevelSecurity = typeof operationElement.security === 'undefined';
           const hasTopLevelSecurity = typeof topLevelSecurity !== 'undefined';
           if (missingOperationLevelSecurity && hasTopLevelSecurity) {
             var _topLevelSecurity;
             operationElement.security = new OperationSecurityElement((_topLevelSecurity = topLevelSecurity) === null || _topLevelSecurity === void 0 ? void 0 : _topLevelSecurity.content);
+            storage.append(operationJSONPointer);
           }
         }
       }

package/es/refractor/plugins/normalize-servers.mjs

@@ -1,4 +1,5 @@
 import { PathItemServersElement, OperationServersElement, ServersElement } from '@swagger-api/apidom-ns-openapi-3-0';
+import NormalizeStorage from "./normalize-header-examples/NormalizeStorage.mjs";
 /**
  * Override of Server Objects.
  *
@@ -11,32 +12,48 @@ import { PathItemServersElement, OperationServersElement, ServersElement } from
  * If an alternative server object is specified at the Path Item Object level, it will override OpenAPI.servers.
  * If an alternative server object is specified at the Operation Object level, it will override PathItem.servers and OpenAPI.servers respectively.
  */
-
 /* eslint-disable no-param-reassign */
-const plugin = () => ({
-  predicates,
-  namespace
-}) => {
+const plugin = ({
+  storageField = 'x-normalized'
+} = {}) => toolbox => {
+  const {
+    namespace,
+    ancestorLineageToJSONPointer,
+    predicates
+  } = toolbox;
+  let storage;
   return {
     visitor: {
-      OpenApi3_1Element(openapiElement) {
-        const isServersUndefined = typeof openapiElement.servers === 'undefined';
-        const isServersArrayElement = predicates.isArrayElement(openapiElement.servers);
-        const isServersEmpty = isServersArrayElement && openapiElement.servers.length === 0;
-        // @ts-ignore
-        const defaultServer = namespace.elements.Server.refract({
-          url: '/'
-        });
-        if (isServersUndefined || !isServersArrayElement) {
-          openapiElement.servers = new ServersElement([defaultServer]);
-        } else if (isServersArrayElement && isServersEmpty) {
-          openapiElement.servers.push(defaultServer);
+      OpenApi3_1Element: {
+        enter(openapiElement) {
+          const isServersUndefined = typeof openapiElement.servers === 'undefined';
+          const isServersArrayElement = predicates.isArrayElement(openapiElement.servers);
+          const isServersEmpty = isServersArrayElement && openapiElement.servers.length === 0;
+          // @ts-ignore
+          const defaultServer = namespace.elements.Server.refract({
+            url: '/'
+          });
+          if (isServersUndefined || !isServersArrayElement) {
+            openapiElement.servers = new ServersElement([defaultServer]);
+          } else if (isServersArrayElement && isServersEmpty) {
+            openapiElement.servers.push(defaultServer);
+          }
+          storage = new NormalizeStorage(openapiElement, storageField, 'servers');
+        },
+        leave() {
+          storage = undefined;
         }
       },
       PathItemElement(pathItemElement, key, parent, path, ancestors) {
         // skip visiting this Path Item
         if (ancestors.some(predicates.isComponentsElement)) return;
         if (!ancestors.some(predicates.isOpenApi3_1Element)) return;
+        const pathItemJSONPointer = ancestorLineageToJSONPointer([...ancestors, parent, pathItemElement]);
+
+        // skip visiting this Path Item Object if it's already normalized
+        if (storage.includes(pathItemJSONPointer)) {
+          return;
+        }
         const parentOpenapiElement = ancestors.find(predicates.isOpenApi3_1Element);
         const isServersUndefined = typeof pathItemElement.servers === 'undefined';
         const isServersArrayElement = predicates.isArrayElement(pathItemElement.servers);
@@ -54,12 +71,19 @@ const plugin = () => ({
               pathItemElement.servers.push(server);
             });
           }
+          storage.append(pathItemJSONPointer);
         }
       },
       OperationElement(operationElement, key, parent, path, ancestors) {
         // skip visiting this Operation
         if (ancestors.some(predicates.isComponentsElement)) return;
         if (!ancestors.some(predicates.isOpenApi3_1Element)) return;
+        const operationJSONPointer = ancestorLineageToJSONPointer([...ancestors, parent, operationElement]);
+
+        // skip visiting this Operation Object if it's already normalized
+        if (storage.includes(operationJSONPointer)) {
+          return;
+        }
 
         // @TODO(vladimir.gorej@gmail.com): can be replaced by Array.prototype.findLast in future
         const parentPathItemElement = [...ancestors].reverse().find(predicates.isPathItemElement);
@@ -78,6 +102,7 @@ const plugin = () => ({
               operationElement.servers.push(server);
             });
           }
+          storage.append(operationJSONPointer);
         }
       }
     }

package/es/refractor/toolbox.mjs

@@ -1,7 +1,29 @@
-import { isElement, isStringElement, isArrayElement, isObjectElement, isMemberElement, createNamespace, includesClasses, hasElementSourceMap } from '@swagger-api/apidom-core';
+import { isElement, isStringElement, isArrayElement, isObjectElement, isMemberElement, toValue, createNamespace, includesClasses, hasElementSourceMap } from '@swagger-api/apidom-core';
+import { compile as compileJSONPointerTokens } from '@swagger-api/apidom-json-pointer';
 import { isServersElement } from '@swagger-api/apidom-ns-openapi-3-0';
 import * as openApi3_1Predicates from "../predicates.mjs";
 import openApi3_1Namespace from "../namespace.mjs";
+/**
+ * Translates visitor ancestor lineage to a JSON Pointer tokens.
+ * Ancestor lineage is constructed of following visitor method arguments:
+ *
+ *  - ancestors
+ *  - parent
+ *  - element
+ */
+const ancestorLineageToJSONPointer = elementPath => {
+  const jsonPointerTokens = elementPath.reduce((path, element, index) => {
+    if (isMemberElement(element)) {
+      const token = String(toValue(element.key));
+      path.push(token);
+    } else if (isArrayElement(elementPath[index - 2])) {
+      const token = String(elementPath[index - 2].content.indexOf(element));
+      path.push(token);
+    }
+    return path;
+  }, []);
+  return compileJSONPointerTokens(jsonPointerTokens);
+};
 const createToolbox = () => {
   const namespace = createNamespace(openApi3_1Namespace);
   const predicates = {
@@ -17,6 +39,7 @@ const createToolbox = () => {
   };
   return {
     predicates,
+    ancestorLineageToJSONPointer,
     namespace
   };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swagger-api/apidom-ns-openapi-3-1",
-  "version": "1.0.0-alpha.0",
+  "version": "1.0.0-alpha.10",
   "description": "OpenAPI 3.1.x namespace for ApiDOM.",
   "publishConfig": {
     "access": "public",
@@ -45,9 +45,10 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime-corejs3": "^7.20.7",
-    "@swagger-api/apidom-ast": "^1.0.0-alpha.0",
-    "@swagger-api/apidom-core": "^1.0.0-alpha.0",
-    "@swagger-api/apidom-ns-openapi-3-0": "^1.0.0-alpha.0",
+    "@swagger-api/apidom-ast": "^1.0.0-alpha.10",
+    "@swagger-api/apidom-core": "^1.0.0-alpha.10",
+    "@swagger-api/apidom-json-pointer": "^1.0.0-alpha.10",
+    "@swagger-api/apidom-ns-openapi-3-0": "^1.0.0-alpha.10",
     "@types/ramda": "~0.30.0",
     "ramda": "~0.30.0",
     "ramda-adjunct": "^5.0.0",
@@ -63,5 +64,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "b126995cc9e0f0c986c581aaa8b3fd1c35dfbdf7"
+  "gitHead": "0fbbdb5d453d7a4661f62ce5e4b690d279e50b74"
 }