@kubb/adapter-oas 5.0.0-beta.6 → 5.0.0-beta.61

package/src/parser.ts

@@ -1,18 +1,20 @@
-import { URLPath } from '@internals/utils'
+import { pascalCase } from '@internals/utils'
+import { macroDiscriminatorEnum, macroEnumName, macroSimplifyUnion } from '@kubb/ast/macros'
+import { childName, enumPropName, extractRefName, mergeAdjacentObjectsLazy } from '@kubb/ast/utils'
 import { ast } from '@kubb/core'
-import BaseOas from 'oas'
 import { DEFAULT_PARSER_OPTIONS, enumExtensionKeys, SCHEMA_REF_PREFIX, typeOptionMap } from './constants.ts'
-import { isDiscriminator, isNullable, isReference } from './guards.ts'
-import { resolveRef } from './refs.ts'
+import { oasDialect, type OasDialect } from './dialect.ts'
+import { createDiscriminantNode, findDiscriminator } from './discriminator.ts'
+import { getOperationId, getOperations, getRequestContentType, getResponseByStatusCode, getResponseStatusCodes } from './operation.ts'
 import {
   buildSchemaNode,
   flattenSchema,
   getDateType,
-  getMediaType,
   getParameters,
   getPrimitiveType,
   getRequestBodyContentTypes,
   getRequestSchema,
+  getResponseBodyContentTypes,
   getResponseSchema,
   getSchemas,
   getSchemaType,
@@ -30,6 +32,16 @@ export type OasParserContext = {
   contentType?: ContentType
 }
 
+/**
+ * The object returned by {@link createSchemaParser}.
+ * Contains parser functions bound to a specific document.
+ */
+export type SchemaParser = {
+  parseSchema: (entry: { schema: SchemaObject; name?: string | null }, options?: Partial<ast.ParserOptions>) => ast.SchemaNode
+  parseOperation: (options: ast.ParserOptions, operation: Operation) => ast.OperationNode
+  parseParameter: (options: ast.ParserOptions, param: Record<string, unknown>) => ast.ParameterNode
+}
+
 /**
  * Pre-computed per-schema context passed to every schema converter.
  *
@@ -50,13 +62,33 @@ type SchemaContext = {
   options: ast.ParserOptions
 }
 
+/**
+ * One entry in the ordered schema rule table: a predicate paired with a converter. A rule whose
+ * `match` returns `true` may still `convert` to `null` to defer to the next rule (e.g. a `format`
+ * that is not convertible falls through to plain `type` handling).
+ */
+type SchemaRule = {
+  /**
+   * Identifies the rule when reading the table or debugging which branch ran.
+   */
+  name: string
+  /**
+   * Returns `true` when this rule is responsible for the given context.
+   */
+  match: (context: SchemaContext) => boolean
+  /**
+   * Produces a node for the context, or `null` to fall through to the next rule.
+   */
+  convert: (context: SchemaContext) => ast.SchemaNode | null
+}
+
 /**
  * Normalizes malformed `{ type: 'array', enum: [...] }` schemas by moving enum values into items.
  *
  * This pattern violates the OpenAPI spec but appears in real specs. The fix moves enum values
- * from the array to its items sub-schema, making them valid for downstream processing.
+ * from the array to its items sub-schema, so they are valid for downstream processing.
  *
- * @note This is a defensive measure for robustness with non-compliant specs.
+ * @note A defensive measure for non-compliant specs.
  */
 function normalizeArrayEnum(schema: SchemaObject): SchemaObject {
   const isItemsObject = typeof schema.items === 'object' && !Array.isArray(schema.items)
@@ -69,19 +101,36 @@ function normalizeArrayEnum(schema: SchemaObject): SchemaObject {
   return { ...schemaWithoutEnum, items: normalizedItems } as SchemaObject
 }
 
+/**
+ * Names the inline enums on a property's schema, and on each item when the property is a tuple, from
+ * the parent and property name. Wraps `macroEnumName` at the property construction site.
+ */
+function nameEnums(node: ast.SchemaNode, options: { parentName: string | null | undefined; propName: string; enumSuffix: string }): ast.SchemaNode {
+  const macro = macroEnumName(options)
+  const named = ast.applyMacros(node, [macro], { depth: 'shallow' })
+  const tupleNode = ast.narrowSchema(named, 'tuple')
+  if (tupleNode?.items) {
+    const namedItems = tupleNode.items.map((item) => ast.applyMacros(item, [macro], { depth: 'shallow' }))
+    if (namedItems.some((item, i) => item !== tupleNode.items![i])) {
+      return { ...tupleNode, items: namedItems }
+    }
+  }
+  return named
+}
+
 /**
  * Factory function that creates schema and operation converters for a given OpenAPI context.
  *
  * Returns closures that share mutable state (`resolvingRefs` set for cycle detection).
  * Each converter branch (`convertRef`, `convertAllOf`, etc.) mutually recursively calls `parseSchema`,
- * made possible by hoisting of function declarations.
+ * which works because function declarations hoist.
  *
- * @note Not exported; called internally by `parseOas()` and `parseSchema()`.
+ * @internal
  */
-function createSchemaParser(ctx: OasParserContext) {
+export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect = oasDialect) {
   const document = ctx.document
 
-  // Branch handlers — each converts one OAS schema pattern to a SchemaNode.
+  // Branch handlers, each converts one OAS schema pattern to a SchemaNode.
 
   /**
    * Tracks `$ref` paths that are currently being resolved to prevent infinite
@@ -89,6 +138,16 @@ function createSchemaParser(ctx: OasParserContext) {
    */
   const resolvingRefs = new Set<string>()
 
+  /**
+   * Cache of `$ref` schemas already resolved in this parser instance, keyed by ref path.
+   *
+   * Without it, a shared schema (e.g. `customer`) is re-expanded for every `$ref` that points at
+   * it. In cross-referenced specs like Stripe (~1400 schemas) that becomes exponential blowup,
+   * since one schema can be referenced from dozens of parents, each re-walking its whole subtree.
+   * Memoizing by ref path drops the work from O(2^depth) to O(N) unique schema names.
+   */
+  const resolvedRefCache = new Map<string, ast.SchemaNode | null>()
+
   /**
    * Converts a `$ref` schema into a `RefSchemaNode`.
    *
@@ -98,25 +157,29 @@ function createSchemaParser(ctx: OasParserContext) {
    * Circular refs are detected via `resolvingRefs` and leave `schema` as `undefined`.
    */
   function convertRef({ schema, name, nullable, defaultValue, rawOptions }: SchemaContext): ast.SchemaNode {
-    let resolvedSchema: ast.SchemaNode | undefined
+    let resolvedSchema: ast.SchemaNode | null = null
     const refPath = schema.$ref
     if (refPath && !resolvingRefs.has(refPath)) {
-      try {
-        const referenced = resolveRef<SchemaObject>(document, refPath)
-        if (referenced) {
-          resolvingRefs.add(refPath)
-          resolvedSchema = parseSchema({ schema: referenced }, rawOptions)
-          resolvingRefs.delete(refPath)
+      if (!resolvedRefCache.has(refPath)) {
+        try {
+          const referenced = dialect.resolveRef<SchemaObject>(document, refPath)
+          if (referenced) {
+            resolvingRefs.add(refPath)
+            resolvedSchema = parseSchema({ schema: referenced }, rawOptions)
+            resolvingRefs.delete(refPath)
+          }
+        } catch {
+          // Ref cannot be resolved in this document (e.g. unit tests with minimal documents).
         }
-      } catch {
-        // Ref cannot be resolved in this document (e.g. unit tests with minimal documents).
+        resolvedRefCache.set(refPath, resolvedSchema)
       }
+      resolvedSchema = resolvedRefCache.get(refPath) ?? null
     }
 
-    return ast.createSchema({
+    return ast.factory.createSchema({
       ...buildSchemaNode(schema, name, nullable, defaultValue),
       type: 'ref',
-      name: ast.extractRefName(schema.$ref!),
+      name: extractRefName(schema.$ref!),
       ref: schema.$ref,
       schema: resolvedSchema,
     })
@@ -133,12 +196,12 @@ function createSchemaParser(ctx: OasParserContext) {
       schema.additionalProperties === undefined
     ) {
       const [memberSchema] = schema.allOf as Array<SchemaObject | ReferenceObject>
-      const memberNode = parseSchema({ schema: memberSchema! as SchemaObject, name: null }, rawOptions)
+      const memberNode = parseSchema({ schema: memberSchema! as SchemaObject, name }, rawOptions)
       const { kind: _kind, ...memberNodeProps } = memberNode
       const mergedNullable = nullable || memberNode.nullable || undefined
       const mergedDefault = schema.default === null && mergedNullable ? undefined : (schema.default ?? memberNode.default)
 
-      return ast.createSchema({
+      return ast.factory.createSchema({
         ...memberNodeProps,
         name,
         title: schema.title ?? memberNode.title,
@@ -150,6 +213,7 @@ function createSchemaParser(ctx: OasParserContext) {
         default: mergedDefault,
         example: schema.example ?? memberNode.example,
         pattern: schema.pattern ?? ('pattern' in memberNode ? memberNode.pattern : undefined),
+        format: schema.format ?? memberNode.format,
       } as ast.DistributiveOmit<ast.SchemaNode, 'kind'>)
     }
 
@@ -159,16 +223,16 @@ function createSchemaParser(ctx: OasParserContext) {
     }> = []
     const allOfMembers: Array<ast.SchemaNode> = (schema.allOf as Array<SchemaObject | ReferenceObject>)
       .filter((item) => {
-        if (!isReference(item) || !name) return true
-        const deref = resolveRef<SchemaObject>(document, item.$ref)
-        if (!deref || !isDiscriminator(deref)) return true
+        if (!dialect.isReference(item) || !name) return true
+        const deref = dialect.resolveRef<SchemaObject>(document, item.$ref)
+        if (!deref || !dialect.isDiscriminator(deref)) return true
         const parentUnion = deref.oneOf ?? deref.anyOf
         if (!parentUnion) return true
         const childRef = `${SCHEMA_REF_PREFIX}${name}`
-        const inOneOf = parentUnion.some((oneOfItem) => isReference(oneOfItem) && oneOfItem.$ref === childRef)
+        const inOneOf = parentUnion.some((oneOfItem) => dialect.isReference(oneOfItem) && oneOfItem.$ref === childRef)
         const inMapping = Object.values(deref.discriminator.mapping ?? {}).some((v) => v === childRef)
         if (inOneOf || inMapping) {
-          const discriminatorValue = ast.findDiscriminator(deref.discriminator.mapping, childRef)
+          const discriminatorValue = findDiscriminator(deref.discriminator.mapping, childRef)
           if (discriminatorValue) {
             filteredDiscriminantValues.push({
               propertyName: deref.discriminator.propertyName,
@@ -179,7 +243,7 @@ function createSchemaParser(ctx: OasParserContext) {
         }
         return true
       })
-      .map((s) => parseSchema({ schema: s as SchemaObject }, rawOptions))
+      .map((s) => parseSchema({ schema: s as SchemaObject, name }, rawOptions))
 
     const syntheticStart = allOfMembers.length
 
@@ -189,9 +253,9 @@ function createSchemaParser(ctx: OasParserContext) {
 
       if (missingRequired.length) {
         const resolvedMembers = (schema.allOf as Array<SchemaObject | ReferenceObject>).flatMap((item) => {
-          if (!isReference(item)) return [item as SchemaObject]
-          const deref = resolveRef<SchemaObject>(document, item.$ref)
-          return deref && !isReference(deref) ? [deref] : []
+          if (!dialect.isReference(item)) return [item as SchemaObject]
+          const deref = dialect.resolveRef<SchemaObject>(document, item.$ref)
+          return deref && !dialect.isReference(deref) ? [deref] : []
         })
 
         for (const key of missingRequired) {
@@ -204,6 +268,7 @@ function createSchemaParser(ctx: OasParserContext) {
                       properties: { [key]: resolved.properties[key] },
                       required: [key],
                     } as SchemaObject,
+                    name,
                   },
                   rawOptions,
                 ),
@@ -217,16 +282,19 @@ function createSchemaParser(ctx: OasParserContext) {
 
     if (schema.properties) {
       const { allOf: _allOf, ...schemaWithoutAllOf } = schema
+      // Don't pass `name` here, the result must stay anonymous so it can be merged with the
+      // adjacent synthetic object in `mergeAdjacentObjectsLazy`. Nested enum qualification
+      // happens upstream via `convertObject`'s `setEnumName` propagation.
       allOfMembers.push(parseSchema({ schema: schemaWithoutAllOf }, rawOptions))
     }
 
     for (const { propertyName, value } of filteredDiscriminantValues) {
-      allOfMembers.push(ast.createDiscriminantNode({ propertyName, value }))
+      allOfMembers.push(createDiscriminantNode({ propertyName, value }))
     }
 
-    return ast.createSchema({
+    return ast.factory.createSchema({
       type: 'intersection',
-      members: [...ast.mergeAdjacentObjects(allOfMembers.slice(0, syntheticStart)), ...ast.mergeAdjacentObjects(allOfMembers.slice(syntheticStart))],
+      members: [...mergeAdjacentObjectsLazy(allOfMembers.slice(0, syntheticStart)), ...mergeAdjacentObjectsLazy(allOfMembers.slice(syntheticStart))],
       ...buildSchemaNode(schema, name, nullable, defaultValue),
     })
   }
@@ -243,7 +311,7 @@ function createSchemaParser(ctx: OasParserContext) {
         return null
       }
 
-      return ast.createSchema({
+      return ast.factory.createSchema({
         type: 'object',
         primitive: 'object',
         properties: [discriminatorProperty],
@@ -254,10 +322,10 @@ function createSchemaParser(ctx: OasParserContext) {
     const strategy: 'one' | 'any' = schema.oneOf ? 'one' : 'any'
     const unionBase = {
       ...buildSchemaNode(schema, name, nullable, defaultValue),
-      discriminatorPropertyName: isDiscriminator(schema) ? schema.discriminator.propertyName : undefined,
+      discriminatorPropertyName: dialect.isDiscriminator(schema) ? schema.discriminator.propertyName : undefined,
       strategy,
     }
-    const discriminator = isDiscriminator(schema) ? schema.discriminator : undefined
+    const discriminator = dialect.isDiscriminator(schema) ? schema.discriminator : undefined
     const sharedPropertiesNode = schema.properties
       ? (() => {
           const { oneOf: _oneOf, anyOf: _anyOf, ...schemaWithoutUnion } = schema
@@ -270,9 +338,9 @@ function createSchemaParser(ctx: OasParserContext) {
 
     if (sharedPropertiesNode || discriminator?.mapping) {
       const members = unionMembers.map((s) => {
-        const ref = isReference(s) ? s.$ref : undefined
-        const discriminatorValue = ast.findDiscriminator(discriminator?.mapping, ref)
-        const memberNode = parseSchema({ schema: s as SchemaObject }, rawOptions)
+        const ref = dialect.isReference(s) ? s.$ref : undefined
+        const discriminatorValue = findDiscriminator(discriminator?.mapping, ref)
+        const memberNode = parseSchema({ schema: s as SchemaObject, name }, rawOptions)
 
         if (!discriminatorValue || !discriminator) {
           return memberNode
@@ -280,21 +348,19 @@ function createSchemaParser(ctx: OasParserContext) {
 
         const narrowedDiscriminatorNode = sharedPropertiesNode
           ? pickDiscriminatorPropertyNode(
-              ast.setDiscriminatorEnum({
-                node: sharedPropertiesNode,
-                propertyName: discriminator.propertyName,
-                values: [discriminatorValue],
+              ast.applyMacros(sharedPropertiesNode, [macroDiscriminatorEnum({ propertyName: discriminator.propertyName, values: [discriminatorValue] })], {
+                depth: 'shallow',
               }),
               discriminator.propertyName,
             )
           : undefined
 
-        return ast.createSchema({
+        return ast.factory.createSchema({
           type: 'intersection',
           members: [
             memberNode,
             narrowedDiscriminatorNode ??
-              ast.createDiscriminantNode({
+              createDiscriminantNode({
                 propertyName: discriminator.propertyName,
                 value: discriminatorValue,
               }),
@@ -302,7 +368,7 @@ function createSchemaParser(ctx: OasParserContext) {
         })
       })
 
-      const unionNode = ast.createSchema({
+      const unionNode = ast.factory.createSchema({
         type: 'union',
         ...unionBase,
         members,
@@ -312,18 +378,20 @@ function createSchemaParser(ctx: OasParserContext) {
         return unionNode
       }
 
-      return ast.createSchema({
+      return ast.factory.createSchema({
         type: 'intersection',
         ...buildSchemaNode(schema, name, nullable, defaultValue),
         members: [unionNode, sharedPropertiesNode],
       })
     }
 
-    return ast.createSchema({
+    const unionNode = ast.factory.createSchema({
       type: 'union',
       ...unionBase,
-      members: ast.simplifyUnion(unionMembers.map((s) => parseSchema({ schema: s as SchemaObject }, rawOptions))),
+      members: unionMembers.map((s) => parseSchema({ schema: s as SchemaObject, name }, rawOptions)),
     })
+
+    return ast.applyMacros(unionNode, [macroSimplifyUnion], { depth: 'shallow' })
   }
 
   /**
@@ -333,18 +401,19 @@ function createSchemaParser(ctx: OasParserContext) {
     const constValue = schema.const
 
     if (constValue === null) {
-      return ast.createSchema({
+      return ast.factory.createSchema({
         type: 'null',
         primitive: 'null',
         name,
         title: schema.title,
         description: schema.description,
         deprecated: schema.deprecated,
+        format: schema.format,
       })
     }
 
     const constPrimitive = getPrimitiveType(typeof constValue === 'number' ? 'number' : typeof constValue === 'boolean' ? 'boolean' : 'string')
-    return ast.createSchema({
+    return ast.factory.createSchema({
       type: 'enum',
       primitive: constPrimitive,
       enumValues: [constValue as string | number | boolean],
@@ -360,7 +429,7 @@ function createSchemaParser(ctx: OasParserContext) {
     const base = buildSchemaNode(schema, name, nullable, defaultValue)
 
     if (schema.format === 'int64') {
-      return ast.createSchema({
+      return ast.factory.createSchema({
         type: options.integerType === 'bigint' ? 'bigint' : 'integer',
         primitive: 'integer',
         ...base,
@@ -376,7 +445,7 @@ function createSchemaParser(ctx: OasParserContext) {
       if (!dateType) return null
 
       if (dateType.type === 'datetime') {
-        return ast.createSchema({
+        return ast.factory.createSchema({
           ...base,
           primitive: 'string' as const,
           type: 'datetime',
@@ -384,7 +453,7 @@ function createSchemaParser(ctx: OasParserContext) {
           local: dateType.local,
         })
       }
-      return ast.createSchema({
+      return ast.factory.createSchema({
         ...base,
         primitive: 'string' as const,
         type: dateType.type,
@@ -398,14 +467,14 @@ function createSchemaParser(ctx: OasParserContext) {
     const specialPrimitive: ast.PrimitiveSchemaType = specialType === 'number' || specialType === 'integer' || specialType === 'bigint' ? specialType : 'string'
 
     if (specialType === 'number' || specialType === 'integer' || specialType === 'bigint') {
-      return ast.createSchema({
+      return ast.factory.createSchema({
         ...base,
         primitive: specialPrimitive,
         type: specialType,
       })
     }
     if (specialType === 'url') {
-      return ast.createSchema({
+      return ast.factory.createSchema({
         ...base,
         primitive: 'string' as const,
         type: 'url',
@@ -414,21 +483,21 @@ function createSchemaParser(ctx: OasParserContext) {
       })
     }
     if (specialType === 'ipv4') {
-      return ast.createSchema({
+      return ast.factory.createSchema({
         ...base,
         primitive: 'string' as const,
         type: 'ipv4',
       })
     }
     if (specialType === 'ipv6') {
-      return ast.createSchema({
+      return ast.factory.createSchema({
         ...base,
         primitive: 'string' as const,
         type: 'ipv6',
       })
     }
     if (specialType === 'uuid' || specialType === 'email') {
-      return ast.createSchema({
+      return ast.factory.createSchema({
         ...base,
         primitive: 'string' as const,
         type: specialType,
@@ -437,7 +506,7 @@ function createSchemaParser(ctx: OasParserContext) {
       })
     }
 
-    return ast.createSchema({
+    return ast.factory.createSchema({
       ...base,
       primitive: specialPrimitive,
       type: specialType as ast.ScalarSchemaType,
@@ -454,6 +523,22 @@ function createSchemaParser(ctx: OasParserContext) {
 
     const nullInEnum = schema.enum!.includes(null)
     const filteredValues = (nullInEnum ? schema.enum!.filter((v) => v !== null) : schema.enum!) as Array<string | number | boolean>
+
+    // drf-spectacular `NullEnum` ({ enum: [null] }) is just `null`. An empty enum node would
+    // render as `never` (plugin-ts) / invalid `z.enum([])` (plugin-zod). Mirror the `const: null`
+    // branch so it renders as a clean `null` (not `z.null().nullable()`).
+    if (nullInEnum && filteredValues.length === 0) {
+      return ast.factory.createSchema({
+        type: 'null',
+        primitive: 'null',
+        name,
+        title: schema.title,
+        description: schema.description,
+        deprecated: schema.deprecated,
+        format: schema.format,
+      })
+    }
+
     const enumNullable = nullable || nullInEnum || undefined
     const enumDefault = schema.default === null && enumNullable ? undefined : schema.default
     const enumPrimitive = getPrimitiveType(type)
@@ -470,6 +555,7 @@ function createSchemaParser(ctx: OasParserContext) {
       writeOnly: schema.writeOnly,
       default: enumDefault,
       example: schema.example,
+      format: schema.format,
     }
 
     const extensionKey = enumExtensionKeys.find((key) => key in schema)
@@ -482,7 +568,7 @@ function createSchemaParser(ctx: OasParserContext) {
       const uniqueValues = [...new Set(filteredValues)]
       const seenNames = new Set<string>()
 
-      return ast.createSchema({
+      return ast.factory.createSchema({
         ...enumBase,
         primitive: enumPrimitiveType,
         namedEnumValues: uniqueValues
@@ -499,7 +585,7 @@ function createSchemaParser(ctx: OasParserContext) {
       })
     }
 
-    return ast.createSchema({
+    return ast.factory.createSchema({
       ...enumBase,
       enumValues: [...new Set(filteredValues)],
     })
@@ -513,21 +599,13 @@ function createSchemaParser(ctx: OasParserContext) {
       ? Object.entries(schema.properties).map(([propName, propSchema]) => {
           const required = Array.isArray(schema.required) ? schema.required.includes(propName) : !!schema.required
           const resolvedPropSchema = propSchema as SchemaObject
-          const propNullable = isNullable(resolvedPropSchema)
+          const propNullable = dialect.isNullable(resolvedPropSchema)
 
-          const resolvedChildName = ast.childName(name, propName)
+          const resolvedChildName = childName(name, propName)
           const propNode = parseSchema({ schema: resolvedPropSchema, name: resolvedChildName }, rawOptions)
-          let schemaNode = ast.setEnumName(propNode, name, propName, options.enumSuffix)
-
-          const tupleNode = ast.narrowSchema(schemaNode, 'tuple')
-          if (tupleNode?.items) {
-            const namedItems = tupleNode.items.map((item) => ast.setEnumName(item, name, propName, options.enumSuffix))
-            if (namedItems.some((item, i) => item !== tupleNode.items![i])) {
-              schemaNode = { ...tupleNode, items: namedItems }
-            }
-          }
+          const schemaNode = nameEnums(propNode, { parentName: name, propName, enumSuffix: options.enumSuffix })
 
-          return ast.createProperty({
+          return ast.factory.createProperty({
             name: propName,
             schema: {
               ...schemaNode,
@@ -539,18 +617,15 @@ function createSchemaParser(ctx: OasParserContext) {
       : []
 
     const additionalProperties = schema.additionalProperties
-    let additionalPropertiesNode: ast.SchemaNode | boolean | undefined
-    if (additionalProperties === true) {
-      additionalPropertiesNode = true
-    } else if (additionalProperties && Object.keys(additionalProperties).length > 0) {
-      additionalPropertiesNode = parseSchema({ schema: additionalProperties as SchemaObject }, rawOptions)
-    } else if (additionalProperties === false) {
-      additionalPropertiesNode = false
-    } else if (additionalProperties) {
-      additionalPropertiesNode = ast.createSchema({
-        type: typeOptionMap.get(options.unknownType)!,
-      })
-    }
+    const additionalPropertiesNode: ast.SchemaNode | boolean | undefined = (() => {
+      if (additionalProperties === true) return true
+      if (additionalProperties === false) return false
+      if (additionalProperties && Object.keys(additionalProperties).length > 0) {
+        return parseSchema({ schema: additionalProperties as SchemaObject }, rawOptions)
+      }
+      if (additionalProperties) return ast.factory.createSchema({ type: typeOptionMap.get(options.unknownType)! })
+      return undefined
+    })()
 
     const rawPatternProperties = 'patternProperties' in schema ? schema.patternProperties : undefined
 
@@ -559,7 +634,7 @@ function createSchemaParser(ctx: OasParserContext) {
           Object.entries(rawPatternProperties).map(([pattern, patternSchema]) => [
             pattern,
             patternSchema === true || (typeof patternSchema === 'object' && Object.keys(patternSchema).length === 0)
-              ? ast.createSchema({
+              ? ast.factory.createSchema({
                   type: typeOptionMap.get(options.unknownType)!,
                 })
               : parseSchema({ schema: patternSchema as SchemaObject }, rawOptions),
@@ -567,7 +642,7 @@ function createSchemaParser(ctx: OasParserContext) {
         )
       : undefined
 
-    const objectNode: ast.SchemaNode = ast.createSchema({
+    const objectNode: ast.SchemaNode = ast.factory.createSchema({
       type: 'object',
       primitive: 'object',
       properties,
@@ -578,16 +653,11 @@ function createSchemaParser(ctx: OasParserContext) {
       ...buildSchemaNode(schema, name, nullable, defaultValue),
     })
 
-    if (isDiscriminator(schema) && schema.discriminator.mapping) {
+    if (dialect.isDiscriminator(schema) && schema.discriminator.mapping) {
       const discPropName = schema.discriminator.propertyName
       const values = Object.keys(schema.discriminator.mapping)
-      const enumName = name ? ast.enumPropName(name, discPropName, options.enumSuffix) : undefined
-      return ast.setDiscriminatorEnum({
-        node: objectNode,
-        propertyName: discPropName,
-        values,
-        enumName,
-      })
+      const enumName = name ? enumPropName(name, discPropName, options.enumSuffix) : undefined
+      return ast.applyMacros(objectNode, [macroDiscriminatorEnum({ propertyName: discPropName, values, enumName })], { depth: 'shallow' })
     }
 
     return objectNode
@@ -598,9 +668,9 @@ function createSchemaParser(ctx: OasParserContext) {
    */
   function convertTuple({ schema, name, nullable, defaultValue, rawOptions }: SchemaContext): ast.SchemaNode {
     const tupleItems = (schema.prefixItems ?? []).map((item) => parseSchema({ schema: item as SchemaObject }, rawOptions))
-    const rest = schema.items ? parseSchema({ schema: schema.items as SchemaObject }, rawOptions) : ast.createSchema({ type: 'any' })
+    const rest = schema.items ? parseSchema({ schema: schema.items as SchemaObject }, rawOptions) : ast.factory.createSchema({ type: 'any' })
 
-    return ast.createSchema({
+    return ast.factory.createSchema({
       type: 'tuple',
       primitive: 'array',
       items: tupleItems,
@@ -616,10 +686,10 @@ function createSchemaParser(ctx: OasParserContext) {
    */
   function convertArray({ schema, name, nullable, defaultValue, rawOptions, options }: SchemaContext): ast.SchemaNode {
     const rawItems = schema.items as SchemaObject | undefined
-    const itemName = rawItems?.enum?.length && name ? ast.enumPropName(undefined, name, options.enumSuffix) : undefined
+    const itemName = rawItems?.enum?.length && name ? enumPropName(null, name, options.enumSuffix) : name
     const items = rawItems ? [parseSchema({ schema: rawItems, name: itemName }, rawOptions)] : []
 
-    return ast.createSchema({
+    return ast.factory.createSchema({
       type: 'array',
       primitive: 'array',
       items,
@@ -634,7 +704,7 @@ function createSchemaParser(ctx: OasParserContext) {
    * Converts a `type: 'string'` schema into a `StringSchemaNode`.
    */
   function convertString({ schema, name, nullable, defaultValue }: SchemaContext): ast.SchemaNode {
-    return ast.createSchema({
+    return ast.factory.createSchema({
       type: 'string',
       primitive: 'string',
       min: schema.minLength,
@@ -648,7 +718,7 @@ function createSchemaParser(ctx: OasParserContext) {
    * Converts a `type: 'number'` or `type: 'integer'` schema.
    */
   function convertNumeric({ schema, name, nullable, defaultValue }: SchemaContext, type: 'number' | 'integer'): ast.SchemaNode {
-    return ast.createSchema({
+    return ast.factory.createSchema({
       type,
       primitive: type,
       min: schema.minimum,
@@ -664,7 +734,7 @@ function createSchemaParser(ctx: OasParserContext) {
    * Converts a `type: 'boolean'` schema.
    */
   function convertBoolean({ schema, name, nullable, defaultValue }: SchemaContext): ast.SchemaNode {
-    return ast.createSchema({
+    return ast.factory.createSchema({
       type: 'boolean',
       primitive: 'boolean',
       ...buildSchemaNode(schema, name, nullable, defaultValue),
@@ -675,7 +745,7 @@ function createSchemaParser(ctx: OasParserContext) {
    * Converts an explicit `type: 'null'` schema.
    */
   function convertNull({ schema, name, nullable }: SchemaContext): ast.SchemaNode {
-    return ast.createSchema({
+    return ast.factory.createSchema({
       type: 'null',
       primitive: 'null',
       name,
@@ -683,15 +753,90 @@ function createSchemaParser(ctx: OasParserContext) {
       description: schema.description,
       deprecated: schema.deprecated,
       nullable,
+      format: schema.format,
     })
   }
 
   /**
-   * Central dispatcher that converts an OAS `SchemaObject` into a `SchemaNode`.
+   * Converts a binary string schema (`type: 'string'`, `contentMediaType: 'application/octet-stream'`)
+   * into a `blob` node.
+   */
+  function convertBlob({ schema, name, nullable, defaultValue }: SchemaContext): ast.SchemaNode {
+    return ast.factory.createSchema({
+      type: 'blob',
+      primitive: 'string',
+      ...buildSchemaNode(schema, name, nullable, defaultValue),
+    })
+  }
+
+  /**
+   * Converts an OAS 3.1 multi-type array (e.g. `type: ['string', 'number']`) into a `UnionSchemaNode`.
    *
-   * Dispatch order (first match wins): `$ref` → `allOf` → `oneOf`/`anyOf` → `const` → `format`
-   * → octet-stream blob → multi-type array → constraint-inferred type → `enum` → object/array/tuple/scalar
-   * → empty-schema fallback (`emptySchemaType` option).
+   * Returns `null` when only one non-`null` type remains (e.g. `['string', 'null']`), so `parseSchema`
+   * falls through and handles it as that single type with nullability already folded in.
+   */
+  function convertMultiType({ schema, name, nullable, defaultValue, rawOptions }: SchemaContext): ast.SchemaNode | null {
+    const types = schema.type as Array<string>
+    const nonNullTypes = types.filter((t) => t !== 'null')
+    if (nonNullTypes.length <= 1) return null
+
+    const arrayNullable = types.includes('null') || nullable || undefined
+    return ast.factory.createSchema({
+      type: 'union',
+      members: nonNullTypes.map((t) => parseSchema({ schema: { ...schema, type: t } as SchemaObject, name }, rawOptions)),
+      ...buildSchemaNode(schema, name, arrayNullable, defaultValue),
+    })
+  }
+
+  /**
+   * Ordered schema rule table. Order is significant: composition keywords (`$ref`, `allOf`,
+   * `oneOf`/`anyOf`) take precedence over `const`/`format`, which take precedence over the plain
+   * `type`. The first matching rule that produces a node wins. See {@link SchemaRule} for the
+   * match/convert/fall-through contract.
+   */
+  const schemaRules: Array<SchemaRule> = [
+    { name: 'ref', match: ({ schema }) => dialect.isReference(schema), convert: convertRef },
+    { name: 'allOf', match: ({ schema }) => !!schema.allOf?.length, convert: convertAllOf },
+    { name: 'union', match: ({ schema }) => !!(schema.oneOf?.length || schema.anyOf?.length), convert: convertUnion },
+    { name: 'const', match: ({ schema }) => 'const' in schema && schema.const !== undefined, convert: convertConst },
+    { name: 'format', match: ({ schema }) => !!schema.format, convert: convertFormat },
+    {
+      name: 'blob',
+      match: ({ schema }) => dialect.isBinary(schema),
+      convert: convertBlob,
+    },
+    { name: 'multi-type', match: ({ schema }) => Array.isArray(schema.type) && schema.type.length > 1, convert: convertMultiType },
+    {
+      name: 'constrained-string',
+      match: ({ schema, type }) => !type && (schema.minLength !== undefined || schema.maxLength !== undefined || schema.pattern !== undefined),
+      convert: convertString,
+    },
+    {
+      name: 'constrained-number',
+      match: ({ schema, type }) => !type && (schema.minimum !== undefined || schema.maximum !== undefined),
+      convert: (ctx) => convertNumeric(ctx, 'number'),
+    },
+    { name: 'enum', match: ({ schema }) => !!schema.enum?.length, convert: convertEnum },
+    {
+      name: 'object',
+      match: ({ schema, type }) => type === 'object' || !!schema.properties || !!schema.additionalProperties || 'patternProperties' in schema,
+      convert: convertObject,
+    },
+    { name: 'tuple', match: ({ schema }) => 'prefixItems' in schema, convert: convertTuple },
+    { name: 'array', match: ({ schema, type }) => type === 'array' || 'items' in schema, convert: convertArray },
+    { name: 'string', match: ({ type }) => type === 'string', convert: convertString },
+    { name: 'number', match: ({ type }) => type === 'number', convert: (ctx) => convertNumeric(ctx, 'number') },
+    { name: 'integer', match: ({ type }) => type === 'integer', convert: (ctx) => convertNumeric(ctx, 'integer') },
+    { name: 'boolean', match: ({ type }) => type === 'boolean', convert: convertBoolean },
+    { name: 'null', match: ({ type }) => type === 'null', convert: convertNull },
+  ]
+
+  /**
+   * Converts an OAS `SchemaObject` into a `SchemaNode`.
+   *
+   * Builds the per-schema context, then walks the ordered {@link schemaRules} table and returns
+   * the first converter that produces a node. When none match, falls back to the configured
+   * `emptySchemaType`.
    */
   function parseSchema({ schema, name }: { schema: SchemaObject; name?: string | null }, rawOptions?: Partial<ast.ParserOptions>): ast.SchemaNode {
     const options: ast.ParserOptions = {
@@ -703,11 +848,11 @@ function createSchemaParser(ctx: OasParserContext) {
       return parseSchema({ schema: flattenedSchema, name }, rawOptions)
     }
 
-    const nullable = isNullable(schema) || undefined
+    const nullable = dialect.isNullable(schema) || undefined
     const defaultValue = schema.default === null && nullable ? undefined : schema.default
     const type = Array.isArray(schema.type) ? schema.type[0] : schema.type
 
-    const ctx: SchemaContext = {
+    const schemaCtx: SchemaContext = {
       schema,
       name,
       nullable,
@@ -717,80 +862,36 @@ function createSchemaParser(ctx: OasParserContext) {
       options,
     }
 
-    if (isReference(schema)) return convertRef(ctx)
-
-    if (schema.allOf?.length) return convertAllOf(ctx)
-    const unionMembers = [...(schema.oneOf ?? []), ...(schema.anyOf ?? [])]
-    if (unionMembers.length) return convertUnion(ctx)
-
-    if ('const' in schema && schema.const !== undefined) return convertConst(ctx)
-
-    if (schema.format) {
-      const formatResult = convertFormat(ctx)
-      if (formatResult) return formatResult
-    }
-
-    if (schema.type === 'string' && schema.contentMediaType === 'application/octet-stream') {
-      return ast.createSchema({
-        type: 'blob',
-        primitive: 'string',
-        ...buildSchemaNode(schema, name, nullable, defaultValue),
-      })
-    }
-
-    if (Array.isArray(schema.type) && schema.type.length > 1) {
-      const nonNullTypes = schema.type.filter((t) => t !== 'null') as string[]
-      const arrayNullable = schema.type.includes('null') || nullable || undefined
-
-      if (nonNullTypes.length > 1) {
-        return ast.createSchema({
-          type: 'union',
-          members: nonNullTypes.map((t) => parseSchema({ schema: { ...schema, type: t } as SchemaObject, name }, rawOptions)),
-          ...buildSchemaNode(schema, name, arrayNullable, defaultValue),
-        })
-      }
+    for (const rule of schemaRules) {
+      if (!rule.match(schemaCtx)) continue
+      const node = rule.convert(schemaCtx)
+      if (node) return node
     }
 
-    if (!type) {
-      if (schema.minLength !== undefined || schema.maxLength !== undefined || schema.pattern !== undefined) {
-        return convertString(ctx)
-      }
-      if (schema.minimum !== undefined || schema.maximum !== undefined) {
-        return convertNumeric(ctx, 'number')
-      }
-    }
-
-    if (schema.enum?.length) return convertEnum(ctx)
-    if (type === 'object' || schema.properties || schema.additionalProperties || 'patternProperties' in schema) return convertObject(ctx)
-    if ('prefixItems' in schema) return convertTuple(ctx)
-    if (type === 'array' || 'items' in schema) return convertArray(ctx)
-    if (type === 'string') return convertString(ctx)
-    if (type === 'number') return convertNumeric(ctx, 'number')
-    if (type === 'integer') return convertNumeric(ctx, 'integer')
-    if (type === 'boolean') return convertBoolean(ctx)
-    if (type === 'null') return convertNull(ctx)
-
     const emptyType = typeOptionMap.get(options.emptySchemaType)!
-    return ast.createSchema({
+    return ast.factory.createSchema({
       type: emptyType as ast.ScalarSchemaType,
       name,
       title: schema.title,
       description: schema.description,
+      format: schema.format,
     })
   }
 
   /**
    * Converts a dereferenced OAS parameter object into a `ParameterNode`.
    */
-  function parseParameter(options: ast.ParserOptions, param: Record<string, unknown>): ast.ParameterNode {
+  function parseParameter(options: ast.ParserOptions, param: Record<string, unknown>, parentName?: string): ast.ParameterNode {
     const required = (param['required'] as boolean | undefined) ?? false
+    const paramName = param['name'] as string
+    const schemaName = parentName && paramName ? pascalCase(`${parentName} ${paramName}`) : undefined
 
     const schema: ast.SchemaNode = param['schema']
-      ? parseSchema({ schema: param['schema'] as SchemaObject }, options)
-      : ast.createSchema({ type: typeOptionMap.get(options.unknownType)! })
+      ? parseSchema({ schema: param['schema'] as SchemaObject, name: schemaName }, options)
+      : ast.factory.createSchema({ type: typeOptionMap.get(options.unknownType)! })
 
-    return ast.createParameter({
-      name: param['name'] as string,
+    return ast.factory.createParameter({
+      name: paramName,
       in: param['in'] as ast.ParameterLocation,
       schema: {
         ...schema,
@@ -839,25 +940,27 @@ function createSchemaParser(ctx: OasParserContext) {
    * Collects property names whose schema has a truthy boolean flag (`readOnly` or `writeOnly`).
    * `$ref` entries are skipped since their flags live on the dereferenced target.
    */
-  function collectPropertyKeysByFlag(schema: SchemaObject | null, flag: 'readOnly' | 'writeOnly'): string[] | undefined {
-    if (!schema?.properties) return undefined
+  function collectPropertyKeysByFlag(schema: SchemaObject | null, flag: 'readOnly' | 'writeOnly'): Array<string> | null {
+    if (!schema?.properties) return null
 
-    const keys: string[] = []
+    const keys: Array<string> = []
     for (const key in schema.properties) {
       const prop = schema.properties[key]
-      if (prop && !isReference(prop) && (prop as Record<string, unknown>)[flag]) {
+      if (prop && !dialect.isReference(prop) && (prop as Record<string, unknown>)[flag]) {
         keys.push(key)
       }
     }
-    return keys.length ? keys : undefined
+    return keys.length ? keys : null
   }
 
   /**
    * Converts an OAS `Operation` into an `OperationNode`.
    */
   function parseOperation(options: ast.ParserOptions, operation: Operation): ast.OperationNode {
+    const operationId = getOperationId(operation)
+    const operationName = operationId ? pascalCase(operationId) : undefined
     const parameters: Array<ast.ParameterNode> = getParameters(document, operation).map((param) =>
-      parseParameter(options, param as unknown as Record<string, unknown>),
+      parseParameter(options, param as unknown as Record<string, unknown>, operationName),
     )
 
     // Determine which content types to include in requestBody.content.
@@ -866,6 +969,7 @@ function createSchemaParser(ctx: OasParserContext) {
     const allContentTypes = ctx.contentType ? [ctx.contentType] : getRequestBodyContentTypes(document, operation)
 
     const requestBodyMeta = getRequestBodyMeta(operation)
+    const requestBodyName = operationName ? `${operationName}Request` : undefined
 
     const content = allContentTypes.flatMap((ct) => {
       const schema = getRequestSchema(document, operation, { contentType: ct })
@@ -873,7 +977,7 @@ function createSchemaParser(ctx: OasParserContext) {
       return [
         {
           contentType: ct,
-          schema: ast.syncOptionality(parseSchema({ schema }, options), requestBodyMeta.required),
+          schema: ast.syncOptionality(parseSchema({ schema, name: requestBodyName }, options), requestBodyMeta.required),
           keysToOmit: collectPropertyKeysByFlag(schema, 'readOnly'),
         },
       ]
@@ -888,39 +992,60 @@ function createSchemaParser(ctx: OasParserContext) {
           }
         : undefined
 
-    const responses: Array<ast.ResponseNode> = operation.getResponseStatusCodes().map((statusCode) => {
-      const responseObj = operation.getResponseByStatusCode(statusCode)
-      const responseSchema = getResponseSchema(document, operation, statusCode, { contentType: ctx.contentType })
+    const responses: Array<ast.ResponseNode> = getResponseStatusCodes(operation).map((statusCode) => {
+      const responseObj = getResponseByStatusCode({ document, operation, statusCode })
+
+      // Use `Status<code>` (matching plugin-ts's resolveResponseStatusName convention) so the
+      // qualified names for nested enums don't collide with top-level component schemas that
+      // happen to be named `<operation><statusCode>` (e.g. `GetMaintenance200`).
+      const responseName = operationName ? `${operationName}Status${statusCode}` : undefined
+      const { description } = getResponseMeta(responseObj)
+
+      const parseEntrySchema = (contentType?: string) => {
+        const raw = getResponseSchema(document, operation, statusCode, { contentType })
+        const node =
+          raw && Object.keys(raw).length > 0
+            ? parseSchema({ schema: raw, name: responseName }, options)
+            : ast.factory.createSchema({ type: typeOptionMap.get(options.emptySchemaType)! })
+        return { schema: node, keysToOmit: collectPropertyKeysByFlag(raw, 'writeOnly') }
+      }
 
-      const schema =
-        responseSchema && Object.keys(responseSchema).length > 0
-          ? parseSchema({ schema: responseSchema }, options)
-          : ast.createSchema({
-              type: typeOptionMap.get(options.emptySchemaType)!,
-            })
+      // Build one entry per declared response content type so plugins can union the variants.
+      // When a global contentType is configured, restrict to that single type (mirrors requestBody).
+      const responseContentTypes = ctx.contentType ? [ctx.contentType] : getResponseBodyContentTypes(document, operation, statusCode)
+      const content = responseContentTypes.map((contentType) => ({ contentType, ...parseEntrySchema(contentType) }))
 
-      const { description, content } = getResponseMeta(responseObj)
-      const mediaType = content ? getMediaType(Object.keys(content)[0] ?? '') : getMediaType(operation.contentType ?? '')
+      // Body-less responses keep a single fallback entry so the response still resolves to a
+      // (void/any) schema, matching how `requestBody` only carries schemas inside `content`.
+      if (content.length === 0) {
+        content.push({ contentType: getRequestContentType({ document, operation }) || 'application/json', ...parseEntrySchema(ctx.contentType) })
+      }
 
-      return ast.createResponse({
+      return ast.factory.createResponse({
         statusCode: statusCode as ast.StatusCode,
         description,
-        schema,
-        mediaType,
-        keysToOmit: collectPropertyKeysByFlag(responseSchema, 'writeOnly'),
+        content,
       })
     })
 
-    const urlPath = new URLPath(operation.path)
+    const pathItem = document.paths?.[operation.path]
+    const pathItemDoc = pathItem && !dialect.isReference(pathItem) ? (pathItem as { summary?: unknown; description?: unknown }) : undefined
+    const pickDoc = (key: 'summary' | 'description'): string | undefined => {
+      const own = operation.schema[key]
+      if (typeof own === 'string') return own
+      const fallback = pathItemDoc?.[key]
+      return typeof fallback === 'string' ? fallback : undefined
+    }
 
-    return ast.createOperation({
-      operationId: operation.getOperationId(),
+    return ast.factory.createOperation({
+      operationId,
+      protocol: 'http',
       method: operation.method.toUpperCase() as ast.HttpMethod,
-      path: urlPath.path,
-      tags: operation.getTags().map((tag) => tag.name),
-      summary: operation.getSummary() || undefined,
-      description: operation.getDescription() || undefined,
-      deprecated: operation.isDeprecated() || undefined,
+      path: operation.path,
+      tags: Array.isArray(operation.schema.tags) ? operation.schema.tags.map(String) : [],
+      summary: pickDoc('summary') || undefined,
+      description: pickDoc('description') || undefined,
+      deprecated: operation.schema.deprecated || undefined,
       parameters,
       requestBody,
       responses,
@@ -933,10 +1058,11 @@ function createSchemaParser(ctx: OasParserContext) {
 /**
  * Parses a single OpenAPI `SchemaObject` into a `SchemaNode`.
  *
- * Use this for targeted schema parsing when you don't need the full spec.
- * For complete spec parsing, use `parseOas()` instead which handles operations and all schemas together.
+ * Reach for this when you only need one schema, not the whole spec. To parse a full spec
+ * with its operations and schemas, call `parseOas()`.
  *
- * @note Circular schema references are tracked via internal state and resolve appropriately.
+ * @note Internal state tracks `$ref` paths under resolution, so circular schemas stop
+ * recursing instead of looping.
  *
  * @example
  * ```ts
@@ -957,8 +1083,8 @@ export function parseSchema(
  * Parses an OpenAPI specification into Kubb's universal `InputNode` AST.
  *
  * This is the main entry point for `@kubb/adapter-oas`. It converts OpenAPI/Swagger specs into a spec-agnostic tree
- * that downstream plugins (`plugin-ts`, `plugin-zod`, etc.) consume for code generation. No code is generated here —
- * the tree is a pure data structure representing all schemas and operations.
+ * that downstream plugins (`plugin-ts`, `plugin-zod`, etc.) consume for code generation. No code is generated here.
+ * The tree is a pure data structure of all schemas and operations.
  *
  * Returns the AST root and a `nameMapping` for resolving schema references.
  *
@@ -987,16 +1113,11 @@ export function parseOas(
 
   const schemas: Array<ast.SchemaNode> = Object.entries(schemaObjects).map(([name, schema]) => _parseSchema({ schema, name }, mergedOptions))
 
-  const baseOas = new BaseOas(document)
-  const paths = baseOas.getPaths()
-
-  const operations: Array<ast.OperationNode> = Object.entries(paths).flatMap(([_path, methods]) =>
-    Object.entries(methods)
-      .map(([, operation]) => (operation ? _parseOperation(mergedOptions, operation) : null))
-      .filter((op): op is ast.OperationNode => op !== null),
-  )
+  const operations: Array<ast.OperationNode> = getOperations(document)
+    .map((operation) => _parseOperation(mergedOptions, operation))
+    .filter((op): op is ast.OperationNode => op !== null)
 
-  const root = ast.createInput({ schemas, operations })
+  const root = ast.factory.createInput({ schemas, operations })
 
   return { root, nameMapping }
 }