fix(cli): resolve allOf composition bugs in V3 OpenAPI importer

packages/cli/api-importers/v3-importer-commons/src/converters/schema/SchemaConverter.ts

@@ -31,6 +31,7 @@
         schema: OpenAPIV3_1.SchemaObject;
         inlined?: boolean;
         nameOverride?: string;
+        visitedRefs?: Set<string>;
     }
 
     export interface ConvertedSchema {
@@ -51,13 +52,23 @@
     private readonly inlined: boolean;
     private readonly audiences: string[];
     private readonly nameOverride?: string;
-
-    constructor({ context, breadcrumbs, schema, id, inlined = false, nameOverride }: SchemaConverter.Args) {
+    private readonly visitedRefs: Set<string>;
+
+    constructor({
+        context,
+        breadcrumbs,
+        schema,
+        id,
+        inlined = false,
+        nameOverride,
+        visitedRefs
+    }: SchemaConverter.Args) {
         super({ context, breadcrumbs });
         this.schema = schema;
         this.id = id;
         this.inlined = inlined;
         this.nameOverride = nameOverride;
+        this.visitedRefs = visitedRefs ?? new Set<string>();
         this.audiences =
             this.context.getAudiences({
                 operation: this.schema,
@@ -179,7 +190,8 @@
                     breadcrumbs: [...this.breadcrumbs, "allOf", "0"],
                     schema: allOfSchema,
                     id: this.id,
-                    inlined: true
+                    inlined: true,
+                    visitedRefs: this.visitedRefs
                 });
 
                 const allOfResult = allOfConverter.convert();
@@ -197,17 +209,36 @@
 
         if (shouldMergeAllOf) {
             let mergedSchema: Record<string, unknown> = {};
+            const resolvedRefs = new Set<string>(this.visitedRefs);
+            let hasCycle = false;
             for (const allOfSchema of this.schema.allOf ?? []) {
+                let schemaToMerge: OpenAPIV3_1.SchemaObject;
+
                 if (this.context.isReferenceObject(allOfSchema)) {
-                    return undefined;
+                    const refPath = allOfSchema.$ref;
+                    if (resolvedRefs.has(refPath)) {
+                        hasCycle = true;
+                        break;
+                    }
+                    resolvedRefs.add(refPath);
+
+                    const resolved = this.context.resolveMaybeReference<OpenAPIV3_1.SchemaObject>({
+                        schemaOrReference: allOfSchema,
+                        breadcrumbs: this.breadcrumbs
+                    });
+                    if (resolved == null) {
+                        return undefined;
+                    }
+                    schemaToMerge = resolved;
+                } else {
+                    schemaToMerge = allOfSchema;
                 }
 
                 // Handle bare oneOf/anyOf elements used for mutual exclusion patterns
                 // (e.g., oneOf with variants containing `not: {}` properties).
                 // Flatten variant properties into the merged schema as optional properties.
-                const variants =
-                    (allOfSchema as OpenAPIV3_1.SchemaObject).oneOf ?? (allOfSchema as OpenAPIV3_1.SchemaObject).anyOf;
-                if (variants != null && allOfSchema.type == null && allOfSchema.properties == null) {
+                const variants = schemaToMerge.oneOf ?? schemaToMerge.anyOf;
+                if (variants != null && schemaToMerge.type == null && schemaToMerge.properties == null) {
                     const flattenedProperties: Record<string, unknown> = {};
                     for (const variantSchemaOrRef of variants) {
                         const variantSchema = this.context.isReferenceObject(variantSchemaOrRef)
@@ -243,26 +274,32 @@
                     continue;
                 }
 
-                mergedSchema = mergeWith(mergedSchema, allOfSchema, (objValue, srcValue) => {
-                    if (srcValue === allOfSchema) {
+                mergedSchema = mergeWith(mergedSchema, schemaToMerge, (objValue, srcValue) => {
+                    if (srcValue === schemaToMerge) {
                         return objValue;
                     }
                     if (Array.isArray(objValue) && Array.isArray(srcValue)) {
                         return [...objValue, ...srcValue];
                     }
                     return undefined;
                 });
             }
 
+            // If a circular reference was detected, fall back to the ObjectSchemaConverter path
+            if (hasCycle) {
+                return undefined;
+            }
+
             const mergedConverter = new SchemaConverter({
                 context: this.context,
                 breadcrumbs: this.breadcrumbs,
                 schema: mergedSchema,
                 id: this.id,
-                inlined: true
+                inlined: true,
+                visitedRefs: resolvedRefs
             });
             return mergedConverter.convert();
         }
 
         return undefined;
     }

packages/cli/api-importers/v3-importer-commons/src/converters/schema/SchemaOrReferenceConverter.ts

@@ -82,26 +82,60 @@
     }
 
     private maybeConvertSingularAllOfReferenceObject(): SchemaOrReferenceConverter.Output | undefined {
-        if (
-            this.context.isReferenceObject(this.schemaOrReference) ||
-            this.schemaOrReference.allOf == null ||
-            this.schemaOrReference.allOf.length !== 1
-        ) {
+        if (this.context.isReferenceObject(this.schemaOrReference) || this.schemaOrReference.allOf == null) {
             return undefined;
         }
-        const allOfReference = this.schemaOrReference.allOf[0];
-        if (this.context.isReferenceObject(allOfReference)) {
-            const response = this.context.convertReferenceToTypeReference({
-                reference: allOfReference,
+
+        // Single $ref allOf — convert directly as a type reference
+        if (this.schemaOrReference.allOf.length === 1) {
+            const allOfReference = this.schemaOrReference.allOf[0];
+            if (this.context.isReferenceObject(allOfReference)) {
+                const response = this.context.convertReferenceToTypeReference({
+                    reference: allOfReference,
+                    breadcrumbs: this.breadcrumbs
+                });
+                if (response.ok) {
+                    return {
+                        type: this.wrapTypeReference(response.reference),
+                        inlinedTypes: {}
+                    };
+                }
+            }
+            return undefined;
+        }
+
+        // When allOf has exactly one $ref to a non-object type (e.g. enum) and the
+        // remaining elements are inline primitive constraints (no properties, no enum,
+        // no composition keywords), reference the $ref type directly instead of
+        // creating a synthetic merged copy.
+        const refElements = this.schemaOrReference.allOf.filter((s) => this.context.isReferenceObject(s));
+        const inlineElements = this.schemaOrReference.allOf.filter(
+            (s) => !this.context.isReferenceObject(s)
+        ) as OpenAPIV3_1.SchemaObject[];
+        const singleRef = refElements.length === 1 ? refElements[0] : undefined;
+
+        if (
+            singleRef != null &&
+            inlineElements.every((s) => !s.properties && !s.enum && !s.oneOf && !s.anyOf && !s.allOf)
+        ) {
+            const resolved = this.context.resolveMaybeReference<OpenAPIV3_1.SchemaObject>({
+                schemaOrReference: singleRef,
                 breadcrumbs: this.breadcrumbs
             });
-            if (response.ok) {
-                return {
-                    type: this.wrapTypeReference(response.reference),
-                    inlinedTypes: {}
-                };
+            if (resolved != null && resolved.type !== "object" && !resolved.properties) {
+                const response = this.context.convertReferenceToTypeReference({
+                    reference: singleRef as OpenAPIV3_1.ReferenceObject,
+                    breadcrumbs: this.breadcrumbs
+                });
+                if (response.ok) {
+                    return {
+                        type: this.wrapTypeReference(response.reference),
+                        inlinedTypes: {}
+                    };
+                }
             }
         }
+
         return undefined;
     }