feat: add PoC of handling discriminator for allOf case in OpenAPI 3.1 (#4959)

Author: glowcloud

packages/apidom-ast/src/traversal/visitor.ts

@@ -455,6 +455,7 @@ export const visit = (
     nodePredicate = isNode,
     nodeCloneFn = cloneNode,
     detectCycles = true,
+    detectCyclesCallback = null,
   } = {},
 ) => {
   const visitorKeys = keyMap || {};
@@ -531,6 +532,11 @@ export const visit = (
 
       // cycle detected; skipping over a sub-tree to avoid recursion
       if (detectCycles && ancestors.includes(node)) {
+        if (typeof detectCyclesCallback === 'function') {
+          // @ts-ignore
+          detectCyclesCallback(node, key, parent, path, ancestors);
+        }
+
         path.pop();
         continue;
       }
@@ -636,6 +642,7 @@ visit[Symbol.for('nodejs.util.promisify.custom')] = async (
     nodePredicate = isNode,
     nodeCloneFn = cloneNode,
     detectCycles = true,
+    detectCyclesCallback = null,
   } = {},
 ) => {
   const visitorKeys = keyMap || {};
@@ -712,6 +719,11 @@ visit[Symbol.for('nodejs.util.promisify.custom')] = async (
 
       // cycle detected; skipping over a sub-tree to avoid recursion
       if (detectCycles && ancestors.includes(node)) {
+        if (typeof detectCyclesCallback === 'function') {
+          // @ts-ignore
+          detectCyclesCallback(node, key, parent, path, ancestors);
+        }
+
         path.pop();
         continue;
       }

packages/apidom-ns-openapi-3-1/src/refractor/plugins/normalize-discriminator-mapping.ts

@@ -1,10 +1,15 @@
 import {
-  cloneDeep,
+  ArrayElement,
+  cloneShallow,
   Element,
   isArrayElement,
   ObjectElement,
   StringElement,
+  MemberElement,
   toValue,
+  visit,
+  isMemberElement,
+  isStringElement,
 } from '@swagger-api/apidom-core';
 import { isReferenceLikeElement, isDiscriminatorElement } from '@swagger-api/apidom-ns-openapi-3-0';
 
@@ -13,15 +18,21 @@ import OpenApi3_1Element from '../../elements/OpenApi3-1.ts';
 import NormalizeStorage from './normalize-header-examples/NormalizeStorage.ts';
 import { SchemaElement } from '../registration.ts';
 import { isSchemaElement } from '../../predicates.ts';
+import DiscriminatorElement from '../../elements/Discriminator.ts';
 
 /**
  * Normalization of Discriminator.mapping field.
  *
  * Discriminator.mapping fields are normalized by adding missing mappings from oneOf/anyOf items
  * of the parent Schema Object and transforming existing mappings to Schema Objects.
  *
+ * In case of allOf discriminator, the plugin will add missing mappings based on
+ * allOf items of other Schema Objects.
+ *
  * The normalized mapping is stored in the Schema.discriminator field as `x-normalized-mapping`.
  *
+ * This plugin is designed to be used on dereferenced OpenAPI 3.1 documents.
+ *
  * NOTE: this plugin is idempotent
  * @public
  */
@@ -39,12 +50,15 @@ const plugin =
   (toolbox: Toolbox) => {
     const { ancestorLineageToJSONPointer } = toolbox;
     let storage: NormalizeStorage | undefined;
+    let allOfDiscriminatorMapping: ObjectElement;
 
     return {
       visitor: {
         OpenApi3_1Element: {
           enter(element: OpenApi3_1Element) {
             storage = new NormalizeStorage(element, storageField, 'discriminator-mapping');
+            allOfDiscriminatorMapping =
+              element.getMetaProperty('allOfDiscriminatorMapping') ?? new ObjectElement();
           },
           leave() {
             storage = undefined;
@@ -80,20 +94,33 @@ const plugin =
               return;
             }
 
-            // skip if neither oneOf nor anyOf is present
-            if (!isArrayElement(schemaElement.oneOf) && !isArrayElement(schemaElement.anyOf)) {
+            const parentElement = ancestors[ancestors.length - 1];
+            const schemaName = schemaElement.getMetaProperty('schemaName');
+            const allOfMapping = allOfDiscriminatorMapping.getMember(toValue(schemaName));
+            const hasAllOfMapping =
+              // @ts-ignore
+              allOfMapping && !parentElement?.classes?.contains('json-schema-allOf');
+
+            // skip if neither oneOf, anyOf nor allOf is present
+            if (
+              !isArrayElement(schemaElement.oneOf) &&
+              !isArrayElement(schemaElement.anyOf) &&
+              !hasAllOfMapping
+            ) {
               return;
             }
 
             const mapping = schemaElement.discriminator.get('mapping') ?? new ObjectElement();
-            const normalizedMapping: ObjectElement = cloneDeep(mapping);
+            const normalizedMapping = new ObjectElement();
             let isNormalized = true;
 
             const items = isArrayElement(schemaElement.oneOf)
               ? schemaElement.oneOf
-              : schemaElement.anyOf;
+              : isArrayElement(schemaElement.anyOf)
+                ? schemaElement.anyOf
+                : (allOfMapping.value as ArrayElement);
 
-            items!.forEach((item) => {
+            items.forEach((item) => {
               if (!isSchemaElement(item)) {
                 return;
               }
@@ -111,7 +138,10 @@ const plugin =
                * handle external references and internal references
                * that don't point to components/schemas/<SchemaName>
                */
-              if (metaRefOrigin !== baseURI || (!metaSchemaName && metaRefFields)) {
+              if (
+                !hasAllOfMapping &&
+                (metaRefOrigin !== baseURI || (!metaSchemaName && metaRefFields))
+              ) {
                 let hasMatchingMapping = false;
 
                 mapping.forEach((mappingValue: StringElement, mappingKey: StringElement) => {
@@ -121,7 +151,7 @@ const plugin =
                     ?.get('$refBaseURI');
 
                   if (mappingValueSchemaRefBaseURI?.equals(metaRefFields?.$refBaseURI)) {
-                    normalizedMapping.set(toValue(mappingKey), cloneDeep(item));
+                    normalizedMapping.set(toValue(mappingKey), cloneShallow(item));
                     hasMatchingMapping = true;
                   }
                 });
@@ -145,28 +175,74 @@ const plugin =
 
                   if (
                     mappingValueSchemaName?.equals(metaSchemaName) &&
-                    mappingValueSchemaRefBaseURI?.equals(metaRefFields?.$refBaseURI)
+                    (!hasAllOfMapping ||
+                      mappingValueSchemaRefBaseURI?.equals(metaRefFields?.$refBaseURI))
                   ) {
-                    normalizedMapping.set(toValue(mappingKey), cloneDeep(item));
+                    normalizedMapping.set(toValue(mappingKey), cloneShallow(item));
                     hasMatchingMapping = true;
                   }
                 });
 
                 // add a new mapping if no matching mapping was found
                 if (!hasMatchingMapping) {
-                  normalizedMapping.set(metaSchemaName, cloneDeep(item));
+                  normalizedMapping.set(metaSchemaName, cloneShallow(item));
                 }
               }
             });
 
-            // check if any mapping is not a Schema Object
+            // check if any mapping is not a Schema Object or if any mapping was not normalized
+            const mappingKeys = mapping.keys();
+            const normalizedMappingKeys = normalizedMapping.keys();
             isNormalized =
               isNormalized &&
               normalizedMapping.filter((mappingValue: Element) => !isSchemaElement(mappingValue))
-                .length === 0;
+                .length === 0 &&
+              mappingKeys.every((mappingKey: string) => normalizedMappingKeys.includes(mappingKey));
 
             if (isNormalized) {
               schemaElement.discriminator.set('x-normalized-mapping', normalizedMapping);
+
+              // dive in and eliminate cycles that might be created by normalization
+              visit(
+                schemaElement,
+                {},
+                {
+                  // @ts-ignore
+                  detectCyclesCallback: <T extends Element>(
+                    node: T,
+                    nodeKey: string | number,
+                    nodeParent: Element | undefined,
+                  ) => {
+                    if (
+                      !nodeParent ||
+                      !isMemberElement(node) ||
+                      !isStringElement(node.key) ||
+                      !node.key.equals('discriminator') ||
+                      !isDiscriminatorElement(node.value)
+                    ) {
+                      return;
+                    }
+
+                    const discriminator = cloneShallow(node.value);
+                    const discriminatorCopy = new DiscriminatorElement();
+
+                    if (discriminator.get('mapping')) {
+                      discriminatorCopy.mapping = discriminator.get('mapping');
+                    }
+
+                    if (discriminator.get('propertyName')) {
+                      discriminatorCopy.propertyName = discriminator.get('propertyName');
+                    }
+
+                    // eslint-disable-next-line no-param-reassign
+                    nodeParent[nodeKey] = new MemberElement(
+                      new StringElement('discriminator'),
+                      discriminatorCopy,
+                    );
+                  },
+                },
+              );
+
               storage!.append(schemaJSONPointer);
             }
           },