chore(docs): Fix docblock-generator OAS tool's max-stack error (#7246)

* regenerate oas to fix duplicate keys

* fix clean:oas script

* fix max-stack errors

* fix max-level condition

www/utils/packages/docblock-generator/src/classes/helpers/oas-schema.ts

@@ -26,6 +26,7 @@ class OasSchemaHelper {
   private schemas: Map<string, OpenApiSchema>
   protected schemaRefPrefix = "#/components/schemas/"
   protected formatter: Formatter
+  private MAX_LEVEL = 4
   /**
    * The path to the directory holding the base YAML files.
    */
@@ -48,12 +49,18 @@ class OasSchemaHelper {
    * Retrieve schema as a reference object and add the schema to the {@link schemas} property.
    *
    * @param schema - The schema to convert and add to the schemas property.
+   * @param level - The current depth level. Used to avoid maximum call stack size exceeded.
    * @returns The schema as a reference. If the schema doesn't have the x-schemaName property set,
    * the schema isn't converted and `undefined` is returned.
    */
   schemaToReference(
-    schema: OpenApiSchema
+    schema: OpenApiSchema,
+    level = 0
   ): OpenAPIV3.ReferenceObject | undefined {
+    if (level > this.MAX_LEVEL) {
+      return
+    }
+
     if (!schema["x-schemaName"]) {
       return
     }
@@ -76,7 +83,8 @@ class OasSchemaHelper {
           !("$ref" in propertySchema.items)
         ) {
           propertySchema.items =
-            this.schemaToReference(propertySchema.items) || propertySchema.items
+            this.schemaToReference(propertySchema.items, level + 1) ||
+            propertySchema.items
         } else if (
           propertySchema.oneOf ||
           propertySchema.allOf ||
@@ -91,12 +99,13 @@ class OasSchemaHelper {
               return
             }
 
-            schemaTarget![index] = this.schemaToReference(item) || item
+            schemaTarget![index] =
+              this.schemaToReference(item, level + 1) || item
           })
         }
 
         schema.properties![property] =
-          this.schemaToReference(propertySchema as OpenApiSchema) ||
+          this.schemaToReference(propertySchema as OpenApiSchema, level + 1) ||
           propertySchema
       })
     }

www/utils/packages/docblock-generator/src/classes/kinds/oas.ts

@@ -1718,6 +1718,7 @@ class OasKindGenerator extends FunctionKindGenerator {
   updateSchema({
     oldSchema,
     newSchema,
+    level = 1,
   }: {
     /**
      * The old schema.
@@ -1727,7 +1728,16 @@ class OasKindGenerator extends FunctionKindGenerator {
      * The new schema.
      */
     newSchema?: OpenApiSchema | OpenAPIV3.ReferenceObject
+    /**
+     * The current level in the update schema. Used to avoid
+     * maximum call stack size exceeded error
+     */
+    level?: number
   }): OpenApiSchema | undefined {
+    if (level > this.MAX_LEVEL) {
+      return
+    }
+
     const oldSchemaObj = (
       oldSchema && "$ref" in oldSchema
         ? this.oasSchemaHelper.getSchemaByName(oldSchema.$ref)?.schema
@@ -1738,6 +1748,7 @@ class OasKindGenerator extends FunctionKindGenerator {
         ? this.oasSchemaHelper.getSchemaByName(newSchema.$ref)?.schema
         : newSchema
     ) as OpenApiSchema | undefined
+
     if (!oldSchemaObj && newSchemaObj) {
       return newSchemaObj
     } else if (oldSchemaObj && !newSchemaObj) {
@@ -1784,6 +1795,7 @@ class OasKindGenerator extends FunctionKindGenerator {
                 newSchema: newSchemaObj!.properties![
                   propertyName
                 ] as OpenApiSchema,
+                level: level + 1,
               }) || propertySchema
           }
         )
@@ -1806,6 +1818,7 @@ class OasKindGenerator extends FunctionKindGenerator {
         this.updateSchema({
           oldSchema: oldSchemaObj.items as OpenApiSchema,
           newSchema: newSchemaObj!.items as OpenApiSchema,
+          level: level + 1,
         }) || oldSchemaObj.items
     }