@kubb/oas 4.34.0 → 4.35.1

package/dist/index.cjs

@@ -948,6 +948,7 @@ exports.KNOWN_MEDIA_TYPES = KNOWN_MEDIA_TYPES;
 exports.KUBB_INLINE_REF_PREFIX = KUBB_INLINE_REF_PREFIX;
 exports.Oas = Oas;
 exports.STRUCTURAL_KEYS = STRUCTURAL_KEYS;
+exports.flattenSchema = flattenSchema;
 exports.getDefaultValue = getDefaultValue;
 exports.httpMethods = httpMethods;
 exports.isAllOptional = isAllOptional;

package/dist/index.d.ts

@@ -220,10 +220,15 @@ declare function merge(pathOrApi: Array<string | Document>, {
   oasClass?: typeof Oas;
 }): Promise<Oas>;
 declare function parseFromConfig(config: Config, oasClass?: typeof Oas): Promise<Oas>;
+/**
+ * Flatten allOf schemas by merging keyword-only fragments.
+ * Only flattens schemas where allOf items don't contain structural keys or $refs.
+ */
+declare function flattenSchema(schema: SchemaObject | null): SchemaObject | null;
 /**
  * Validate an OpenAPI document using oas-normalize.
  */
 declare function validate(document: Document): Promise<oas_normalize_lib_types0.ValidationResult>;
 //#endregion
-export { DiscriminatorObject, Document, ENUM_EXTENSION_KEYS, FORMAT_MAP, HttpMethod, httpMethods as HttpMethods, httpMethods, KNOWN_MEDIA_TYPES, KUBB_INLINE_REF_PREFIX, MediaTypeObject, Oas, type OasTypes, type OpenAPIV3, type OpenAPIV3_1, Operation, ReferenceObject, ResponseObject, STRUCTURAL_KEYS, SchemaObject, contentType, getDefaultValue, isAllOptional, isDiscriminator, isNullable, isOpenApiV3_1Document, isOptional, isParameterObject, isReference, isRequired, merge, parse, parseFromConfig, resolveServerUrl, validate };
+export { DiscriminatorObject, Document, ENUM_EXTENSION_KEYS, FORMAT_MAP, HttpMethod, httpMethods as HttpMethods, httpMethods, KNOWN_MEDIA_TYPES, KUBB_INLINE_REF_PREFIX, MediaTypeObject, Oas, type OasTypes, type OpenAPIV3, type OpenAPIV3_1, Operation, ReferenceObject, ResponseObject, STRUCTURAL_KEYS, SchemaObject, contentType, flattenSchema, getDefaultValue, isAllOptional, isDiscriminator, isNullable, isOpenApiV3_1Document, isOptional, isParameterObject, isReference, isRequired, merge, parse, parseFromConfig, resolveServerUrl, validate };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -913,6 +913,6 @@ function resolveServerUrl(server, overrides) {
 	return url;
 }
 //#endregion
-export { ENUM_EXTENSION_KEYS, FORMAT_MAP, httpMethods as HttpMethods, httpMethods, KNOWN_MEDIA_TYPES, KUBB_INLINE_REF_PREFIX, Oas, STRUCTURAL_KEYS, getDefaultValue, isAllOptional, isDiscriminator, isNullable, isOpenApiV3_1Document, isOptional, isParameterObject, isReference, isRequired, merge, parse, parseFromConfig, resolveServerUrl, validate };
+export { ENUM_EXTENSION_KEYS, FORMAT_MAP, httpMethods as HttpMethods, httpMethods, KNOWN_MEDIA_TYPES, KUBB_INLINE_REF_PREFIX, Oas, STRUCTURAL_KEYS, flattenSchema, getDefaultValue, isAllOptional, isDiscriminator, isNullable, isOpenApiV3_1Document, isOptional, isParameterObject, isReference, isRequired, merge, parse, parseFromConfig, resolveServerUrl, validate };
 
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/oas",
-  "version": "4.34.0",
+  "version": "4.35.1",
   "description": "OpenAPI Specification (OAS) utilities and helpers for Kubb, providing parsing, normalization, and manipulation of OpenAPI/Swagger schemas.",
   "keywords": [
     "openapi",
@@ -61,8 +61,8 @@
     "openapi-types": "^12.1.3",
     "remeda": "^2.33.6",
     "swagger2openapi": "^7.0.8",
-    "@kubb/ast": "4.34.0",
-    "@kubb/core": "4.34.0"
+    "@kubb/ast": "4.35.1",
+    "@kubb/core": "4.35.1"
   },
   "devDependencies": {
     "@types/swagger2openapi": "^7.0.4",

package/src/index.ts

@@ -3,6 +3,7 @@ export { KUBB_INLINE_REF_PREFIX, Oas } from './Oas.ts'
 export { resolveServerUrl } from './resolveServerUrl.ts'
 export * from './types.ts'
 export {
+  flattenSchema,
   getDefaultValue,
   isAllOptional,
   isDiscriminator,

package/src/parser.ts

@@ -1,1163 +0,0 @@
-import { pascalCase } from '@internals/utils'
-import {
-  collect,
-  createOperation,
-  createParameter,
-  createProperty,
-  createResponse,
-  createRoot,
-  createSchema,
-  narrowSchema,
-  schemaTypes,
-  transform,
-} from '@kubb/ast'
-import type {
-  ArraySchemaNode,
-  DateSchemaNode,
-  DatetimeSchemaNode,
-  EnumSchemaNode,
-  HttpMethod,
-  IntersectionSchemaNode,
-  MediaType,
-  NumberSchemaNode,
-  ObjectSchemaNode,
-  OperationNode,
-  ParameterLocation,
-  ParameterNode,
-  PrimitiveSchemaType,
-  PropertyNode,
-  RefSchemaNode,
-  ResponseNode,
-  RootNode,
-  ScalarSchemaNode,
-  ScalarSchemaType,
-  SchemaNode,
-  SchemaType,
-  StatusCode,
-  StringSchemaNode,
-  TimeSchemaNode,
-  UnionSchemaNode,
-} from '@kubb/ast/types'
-import type { KubbFile } from '@kubb/fabric-core/types'
-import { ENUM_EXTENSION_KEYS, FORMAT_MAP, KNOWN_MEDIA_TYPES } from './constants.ts'
-import type { Oas } from './Oas.ts'
-import type { contentType, Operation, SchemaObject } from './types.ts'
-import { flattenSchema, isDiscriminator, isNullable, isReference } from './utils.ts'
-
-/**
- * Distributive `Omit` — correctly distributes over union types so that
- * `Omit<A | B, 'kind'>` produces `Omit<A, 'kind'> | Omit<B, 'kind'>`
- * rather than `Omit<A | B, 'kind'>`.
- */
-type DistributiveOmit<TValue, TKey extends PropertyKey> = TValue extends unknown ? Omit<TValue, TKey> : never
-
-/**
- * Maps each `dateType` option value to the AST node produced by `format: 'date-time'`.
- */
-type DateTimeNodeByDateType = {
-  date: DateSchemaNode
-  string: DatetimeSchemaNode
-  stringOffset: DatetimeSchemaNode
-  stringLocal: DatetimeSchemaNode
-  false: StringSchemaNode
-}
-
-/**
- * Resolves the AST node produced by `format: 'date-time'` based on the `dateType` option.
- */
-type ResolveDateTimeNode<TDateType extends Options['dateType']> = DateTimeNodeByDateType[TDateType extends keyof DateTimeNodeByDateType ? TDateType : 'string']
-
-/**
- * Single source of truth: ordered list of `[shape, SchemaNode]` pairs.
- * `InferSchemaNode` walks this tuple in order and returns the node type of the first matching entry.
- * Parameterized over `TDateType` so `format: 'date-time'` resolves to the correct node based on the option.
- */
-type SchemaNodeMap<TDateType extends Options['dateType'] = Options['dateType']> = [
-  [{ $ref: string }, RefSchemaNode],
-  // allOf with sibling `properties` always produces an intersection (shared props are appended as a member).
-  [{ allOf: ReadonlyArray<unknown>; properties: object }, IntersectionSchemaNode],
-  // allOf with 2+ members always produces an intersection.
-  [{ allOf: readonly [unknown, unknown, ...unknown[]] }, IntersectionSchemaNode],
-  // Single-member allOf without sibling `properties` flattens to the member type.
-  [{ allOf: ReadonlyArray<unknown> }, SchemaNode],
-  [{ oneOf: ReadonlyArray<unknown> }, UnionSchemaNode],
-  [{ anyOf: ReadonlyArray<unknown> }, UnionSchemaNode],
-  [{ const: null }, ScalarSchemaNode],
-  [{ const: string | number | boolean }, EnumSchemaNode],
-  // OAS 3.1 multi-type array: `{ type: ['string', 'integer'] }` → union node.
-  [{ type: ReadonlyArray<string> }, UnionSchemaNode],
-  // `{ type: 'array', enum }` is normalized at runtime: enum moves into items → array node.
-  [{ type: 'array'; enum: ReadonlyArray<unknown> }, ArraySchemaNode],
-  [{ enum: ReadonlyArray<unknown> }, EnumSchemaNode],
-  [{ type: 'object' }, ObjectSchemaNode],
-  [{ additionalProperties: boolean | {} }, ObjectSchemaNode],
-  [{ type: 'array' }, ArraySchemaNode],
-  [{ items: object }, ArraySchemaNode],
-  [{ prefixItems: ReadonlyArray<unknown> }, ArraySchemaNode],
-  // Format entries with explicit type — placed before generic type entries so format wins.
-  [{ type: string; format: 'date-time' }, ResolveDateTimeNode<TDateType>],
-  [{ type: string; format: 'date' }, DateSchemaNode],
-  [{ type: string; format: 'time' }, TimeSchemaNode],
-  [{ format: 'date-time' }, ResolveDateTimeNode<TDateType>],
-  [{ format: 'date' }, DateSchemaNode],
-  [{ format: 'time' }, TimeSchemaNode],
-  [{ type: 'string' }, StringSchemaNode],
-  [{ type: 'number' }, NumberSchemaNode],
-  [{ type: 'integer' }, NumberSchemaNode],
-  [{ type: 'bigint' }, NumberSchemaNode],
-  [{ type: string }, ScalarSchemaNode],
-  // Inferred scalar types from constraints when no explicit type is present.
-  [{ minLength: number }, StringSchemaNode],
-  [{ maxLength: number }, StringSchemaNode],
-  [{ pattern: string }, StringSchemaNode],
-  [{ minimum: number }, NumberSchemaNode],
-  [{ maximum: number }, NumberSchemaNode],
-]
-
-export type InferSchemaNode<
-  TSchema extends SchemaObject,
-  TDateType extends Options['dateType'] = Options['dateType'],
-  TEntries extends ReadonlyArray<[object, SchemaNode]> = SchemaNodeMap<TDateType>,
-> = TEntries extends [infer TEntry extends [object, SchemaNode], ...infer TRest extends ReadonlyArray<[object, SchemaNode]>]
-  ? TSchema extends TEntry[0]
-    ? TEntry[1]
-    : InferSchemaNode<TSchema, TDateType, TRest>
-  : SchemaNode
-
-/**
- * Controls how various OAS constructs are mapped to Kubb AST nodes.
- */
-export type Options = {
-  /**
-   * How `format: 'date-time'` schemas are represented. `false` falls through to a plain string.
-   */
-  dateType: false | 'string' | 'stringOffset' | 'stringLocal' | 'date'
-  /**
-   * Whether `type: 'integer'` and `format: 'int64'` produce `number` or `bigint` nodes.
-   */
-  integerType?: 'number' | 'bigint'
-  /**
-   * AST type used when no schema type can be inferred.
-   */
-  unknownType: 'any' | 'unknown' | 'void'
-  /**
-   * AST type used for completely empty schemas (`{}`).
-   */
-  emptySchemaType: 'any' | 'unknown' | 'void'
-  /**
-   * Suffix appended to derived enum names when building property schema names.
-   */
-  enumSuffix: string
-}
-
-/**
- * Construction-time options for `createOasParser`.
- */
-type OasParserOptions = {
-  contentType?: contentType
-  collisionDetection?: boolean
-}
-
-/**
- * Default values for all `Options` fields.
- */
-const DEFAULT_OPTIONS = {
-  dateType: 'string',
-  integerType: 'number',
-  unknownType: 'any',
-  emptySchemaType: 'any',
-  enumSuffix: 'enum',
-} as const satisfies Options
-
-/**
- * Looks up the Kubb `SchemaType` for a given OAS `format` string.
- * Returns `undefined` for formats not in `FORMAT_MAP` (e.g. `int64`, `date-time`),
- * which are handled separately because their output depends on parser options.
- */
-function formatToSchemaType(format: string): SchemaType | undefined {
-  return FORMAT_MAP[format as keyof typeof FORMAT_MAP]
-}
-
-/**
- * Extracts the final path segment of a JSON Pointer `$ref` string.
- * For `#/components/schemas/Order` this returns `'Order'`.
- * Falls back to the full ref string when no slash is present.
- */
-function extractRefName($ref: string): string {
-  return $ref.split('/').at(-1) ?? $ref
-}
-
-/**
- * Maps an OAS primitive type string to its `PrimitiveSchemaType` equivalent.
- * Numeric types (`number`, `integer`, `bigint`) are returned unchanged;
- * `boolean` maps to `'boolean'`; everything else defaults to `'string'`.
- */
-function getPrimitiveType(type: string | undefined): PrimitiveSchemaType {
-  if (type === 'number' || type === 'integer' || type === 'bigint') return type
-  if (type === 'boolean') return 'boolean'
-  return 'string'
-}
-
-/**
- * Narrows a raw content-type string to the `MediaType` union recognized by Kubb.
- * Returns `undefined` for content types not present in `KNOWN_MEDIA_TYPES`.
- */
-function toMediaType(contentType: string): MediaType | undefined {
-  return KNOWN_MEDIA_TYPES.includes(contentType as MediaType) ? (contentType as MediaType) : undefined
-}
-
-/**
- * Pre-computed per-schema context passed to every `convert*` branch handler.
- * Grouping these values avoids repeating the same derivations across all branches.
- */
-type SchemaContext = {
-  schema: SchemaObject
-  name: string | undefined
-  nullable: true | undefined
-  defaultValue: unknown
-  /**
-   * Normalized single type string (first element when OAS 3.1 multi-type array).
-   */
-  type: string | undefined
-  options: Partial<Options> | undefined
-  mergedOptions: Options
-}
-
-/**
- * The public interface returned by `createOasParser`.
- */
-export type OasParser = {
-  /**
-   * Converts an OpenAPI/Swagger spec (wrapped in a Kubb `Oas` instance) into
-   * a `RootNode` — the top-level node of the `@kubb/ast` tree.
-   */
-  buildAst: <TOptions extends Partial<Options> = object>(options?: TOptions) => RootNode
-  convertSchema: <TFormat extends string, TSchema extends SchemaObject & { format?: TFormat }, TOptions extends Partial<Options> = object>(
-    params: { schema: TSchema; name?: string },
-    options?: TOptions,
-  ) => InferSchemaNode<TSchema, TOptions extends { dateType: Options['dateType'] } ? TOptions['dateType'] : (typeof DEFAULT_OPTIONS)['dateType']>
-  /**
-   * Walks `node` and replaces each `ref` value with the name returned by
-   * `resolveName`. The callback receives the full `$ref` path (e.g. `#/components/schemas/Order`)
-   * when available, falling back to the short name. Pass a no-op (`(n) => n`) to skip resolution.
-   *
-   * The optional `resolveEnumName` callback is called for inline `enum` nodes and should return
-   * the transformed name to use (e.g. with a plugin `transformers.name` applied).
-   */
-  resolveRefs: (node: SchemaNode, resolveName: (ref: string) => string | undefined, resolveEnumName?: (name: string) => string | undefined) => SchemaNode
-  /**
-   * Extracts `KubbFile.Import` entries from a `SchemaNode` tree by collecting
-   * all importable `ref` nodes. A `$ref` is considered importable when it resolves
-   * to a known component in the OAS spec (`oas.get($ref)` is truthy).
-   *
-   * The `resolve` callback is called with the schema name (last segment of the
-   * `$ref`, collision-corrected via the OAS name mapping) and must return the
-   * `{ name, path }` pair for the generated import, or `undefined` to skip it.
-   *
-   * @example
-   * ```ts
-   * const imports = parser.getImports(schemaNode, (schemaName) => ({
-   *   name: schemaManager.getName(schemaName, { type: 'type' }),
-   *   path: schemaManager.getFile(schemaName).path,
-   * }))
-   * ```
-   */
-  getImports: (node: SchemaNode, resolve: (schemaName: string) => { name: string; path: string } | undefined) => Array<KubbFile.Import>
-}
-
-/**
- * Creates an OAS parser that converts an OpenAPI/Swagger spec into
- * the `@kubb/ast` tree.
- *
- * Options are passed per-call to `buildAst` or `convertSchema` rather than
- * at construction time, keeping the factory lightweight.
- *
- * This is the **kubb-parser** stage of the compilation lifecycle:
- *   OpenAPI / Swagger  →  Kubb AST
- *
- * No code is generated here; the resulting tree is spec-agnostic and can
- * be consumed by any downstream plugin (plugin-ts, plugin-zod, …).
- *
- * @example
- * ```ts
- * const parser = createOasParser(oas)
- * const root = parser.buildAst({ emptySchemaType: 'unknown' })
- * ```
- */
-export function createOasParser(oas: Oas, { contentType, collisionDetection }: OasParserOptions = {}): OasParser {
-  // Map from original component paths to resolved schema names (after collision resolution)
-  // e.g., { '#/components/schemas/Order': 'OrderSchema', '#/components/responses/Product': 'ProductResponse' }
-  const { schemas: schemaObjects, nameMapping } = oas.getSchemas({ contentType, collisionDetection })
-
-  /**
-   * Resolves the `schemaTypes` constant for the `unknownType` option value.
-   * Used when a schema has no inferrable type (e.g. empty `additionalProperties`).
-   */
-  function getUnknownType(options: Options) {
-    if (options.unknownType === 'any') {
-      return schemaTypes.any
-    }
-    if (options.unknownType === 'void') {
-      return schemaTypes.void
-    }
-
-    return schemaTypes.unknown
-  }
-  /**
-   * Resolves the `schemaTypes` constant for the `emptySchemaType` option value.
-   * Used as the fallback type for completely empty schemas (`{}`).
-   */
-  function getEmptySchemaType(options: Options) {
-    if (options.emptySchemaType === 'any') {
-      return schemaTypes.any
-    }
-    if (options.emptySchemaType === 'void') {
-      return schemaTypes.void
-    }
-
-    return schemaTypes.unknown
-  }
-
-  /**
-   * Resolves the AST type and datetime modifiers for a date/time format, honoring the `dateType` option.
-   * Returns `undefined` when `dateType` is `false`, meaning the format should fall through to `string`.
-   */
-  function getDateType(
-    options: Options,
-    format: 'date-time' | 'date' | 'time',
-  ): { type: 'datetime'; offset?: boolean; local?: boolean } | { type: 'date' | 'time'; representation: 'date' | 'string' } | undefined {
-    if (!options.dateType) {
-      return undefined
-    }
-
-    if (format === 'date-time') {
-      if (options.dateType === 'date') {
-        return { type: 'date', representation: 'date' }
-      }
-      if (options.dateType === 'stringOffset') {
-        return { type: 'datetime', offset: true }
-      }
-      if (options.dateType === 'stringLocal') {
-        return { type: 'datetime', local: true }
-      }
-      return { type: 'datetime', offset: false }
-    }
-
-    if (format === 'date') {
-      return { type: 'date', representation: options.dateType === 'date' ? 'date' : 'string' }
-    }
-
-    // time
-    return { type: 'time', representation: options.dateType === 'date' ? 'date' : 'string' }
-  }
-
-  /**
-   * Shared metadata fields included in every `createSchema` call.
-   * Centralizes the common properties so sub-handlers don't repeat them.
-   */
-  function buildSchemaBase(schema: SchemaObject, name: string | undefined, nullable: true | undefined, defaultValue: unknown) {
-    return {
-      name,
-      nullable,
-      title: schema.title,
-      description: schema.description,
-      deprecated: schema.deprecated,
-      readOnly: schema.readOnly,
-      writeOnly: schema.writeOnly,
-      default: defaultValue,
-      example: schema.example,
-    } as const
-  }
-
-  // Branch handlers — each converts one OAS schema pattern to a SchemaNode.
-  // They are defined as function declarations so they can reference each other
-  // and `convertSchema` freely (JS hoisting).
-
-  /**
-   * Converts a `$ref` schema pointer into a `RefSchemaNode`.
-   *
-   * In OAS 3.0 siblings of `$ref` are technically ignored by the spec, but Kubb intentionally
-   * preserves them so that annotations like `pattern`, `description`, and `nullable` are
-   * reflected in generated JSDoc and type modifiers.
-   */
-  function convertRef({ schema, nullable, defaultValue }: SchemaContext): SchemaNode {
-    const schemaObject = schema as unknown as SchemaObject & { $ref: string }
-    return createSchema({
-      type: 'ref',
-      name: extractRefName(schemaObject.$ref),
-      ref: schemaObject.$ref,
-      nullable,
-      description: schemaObject.description,
-      deprecated: schemaObject.deprecated,
-      readOnly: schemaObject.readOnly,
-      writeOnly: schemaObject.writeOnly,
-      pattern: schemaObject.type === 'string' ? schemaObject.pattern : undefined,
-      example: schemaObject.example,
-      default: defaultValue,
-    })
-  }
-
-  /**
-   * Converts a `allOf` schema into either a flattened member node (single-member `allOf`)
-   * or an `IntersectionSchemaNode` (multi-member `allOf`).
-   *
-   * Single-member `allOf` without sibling structural keys is the common OAS 3.0 pattern for
-   * annotating a `$ref` or primitive with extra constraints; it is flattened to avoid
-   * producing needless intersection wrappers.
-   *
-   * The flatten path is skipped when the outer schema carries structural keys that cannot be
-   * merged into annotation fields: `properties`, `required`, or `additionalProperties`.
-   * Those cases must become an intersection so the constraints are preserved.
-   *
-   * Circular references through discriminator parents are detected and skipped to prevent
-   * infinite recursion during code generation.
-   */
-  function convertAllOf({ schema, name, nullable, defaultValue, options }: SchemaContext): SchemaNode {
-    if (
-      schema.allOf!.length === 1 &&
-      !schema.properties &&
-      !(Array.isArray(schema.required) && schema.required.length) &&
-      schema.additionalProperties === undefined
-    ) {
-      const [memberSchema] = schema.allOf as SchemaObject[]
-      const memberNode = convertSchema({ schema: memberSchema! }, options)
-      const { kind: _kind, ...memberNodeProps } = memberNode
-      const mergedNullable = nullable || memberNode.nullable || undefined
-      const mergedDefault = schema.default === null && mergedNullable ? undefined : (schema.default ?? memberNode.default)
-
-      return createSchema({
-        ...memberNodeProps,
-        name,
-        title: schema.title ?? memberNode.title,
-        description: schema.description ?? memberNode.description,
-        deprecated: schema.deprecated ?? memberNode.deprecated,
-        nullable: mergedNullable,
-        readOnly: schema.readOnly ?? memberNode.readOnly,
-        writeOnly: schema.writeOnly ?? memberNode.writeOnly,
-        default: mergedDefault,
-        example: schema.example ?? memberNode.example,
-        pattern: schema.pattern ?? ('pattern' in memberNode ? memberNode.pattern : undefined),
-      } as DistributiveOmit<SchemaNode, 'kind'>)
-    }
-
-    // When a child schema extends a discriminator parent via allOf and the parent's oneOf/anyOf
-    // references that child back, skip that allOf item to prevent a circular type reference.
-    const allOfMembers: SchemaNode[] = (schema.allOf as SchemaObject[])
-      .filter((item) => {
-        if (!isReference(item) || !name) return true
-        const deref = oas.get<SchemaObject>((item as { $ref: string }).$ref)
-        if (!deref || !isDiscriminator(deref)) return true
-        const parentUnion = (deref as SchemaObject).oneOf ?? (deref as SchemaObject).anyOf
-        if (!parentUnion) return true
-        const childRef = `#/components/schemas/${name}`
-        const inOneOf = parentUnion.some((oneOfItem) => isReference(oneOfItem) && (oneOfItem as { $ref: string }).$ref === childRef)
-        const inMapping = Object.values((deref as SchemaObject & { discriminator: { mapping?: Record<string, string> } }).discriminator.mapping ?? {}).some(
-          (v) => v === childRef,
-        )
-        return !inOneOf && !inMapping
-      })
-      .map((s) => convertSchema({ schema: s as SchemaObject }, options))
-
-    // When `required` lists keys not present in the outer `properties`, resolve them from
-    // the allOf member schemas and inject them as extra intersection members.
-    if (Array.isArray(schema.required) && schema.required.length) {
-      const outerKeys = schema.properties ? new Set(Object.keys(schema.properties)) : new Set<string>()
-      const missingRequired = schema.required.filter((key) => !outerKeys.has(key))
-
-      if (missingRequired.length) {
-        const resolvedMembers = (schema.allOf as SchemaObject[]).flatMap((item) => {
-          if (!isReference(item)) return [item]
-          const deref = oas.get<SchemaObject>(item.$ref)
-          return deref && !isReference(deref) ? [deref as SchemaObject] : []
-        })
-
-        for (const key of missingRequired) {
-          for (const resolved of resolvedMembers) {
-            if (resolved.properties?.[key]) {
-              allOfMembers.push(convertSchema({ schema: { properties: { [key]: resolved.properties[key] }, required: [key] } as SchemaObject }, options))
-              break
-            }
-          }
-        }
-      }
-    }
-
-    if (schema.properties) {
-      const { allOf: _allOf, ...schemaWithoutAllOf } = schema as SchemaObject & { allOf?: unknown[] }
-      allOfMembers.push(convertSchema({ schema: schemaWithoutAllOf as SchemaObject }, options))
-    }
-
-    return createSchema({
-      type: 'intersection',
-      members: allOfMembers,
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
-    })
-  }
-
-  /**
-   * Converts a `oneOf` / `anyOf` schema into a `UnionSchemaNode`.
-   *
-   * Both keywords are treated identically — their members are concatenated into a single union.
-   * When sibling `properties` are present alongside `oneOf`/`anyOf`, each union member is
-   * individually intersected with the shared properties node to match the OAS pattern of
-   * adding common fields next to a discriminated union.
-   */
-  function convertUnion({ schema, name, nullable, defaultValue, options }: SchemaContext): SchemaNode {
-    const unionMembers = [...(schema.oneOf ?? []), ...(schema.anyOf ?? [])]
-    const unionBase = {
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
-      discriminatorPropertyName: isDiscriminator(schema) ? schema.discriminator.propertyName : undefined,
-    }
-
-    if (schema.properties) {
-      const { oneOf: _oneOf, anyOf: _anyOf, ...schemaWithoutUnion } = schema as SchemaObject & { oneOf?: unknown[]; anyOf?: unknown[] }
-      const propertiesNode = convertSchema({ schema: schemaWithoutUnion as SchemaObject }, options)
-
-      return createSchema({
-        type: 'union',
-        ...unionBase,
-        members: unionMembers.map((s) =>
-          createSchema({
-            type: 'intersection',
-            members: [convertSchema({ schema: s as SchemaObject }, options), propertiesNode],
-          }),
-        ),
-      })
-    }
-
-    return createSchema({
-      type: 'union',
-      ...unionBase,
-      members: unionMembers.map((s) => convertSchema({ schema: s as SchemaObject }, options)),
-    })
-  }
-
-  /**
-   * Converts an OAS 3.1 `const` schema into either a null scalar or a single-value `EnumSchemaNode`.
-   * `const: null` maps to a null scalar; any other value becomes a one-item enum so that generators
-   * can produce a precise literal type.
-   */
-  function convertConst({ schema, name, nullable, defaultValue }: SchemaContext): SchemaNode {
-    const constValue = schema.const
-
-    if (constValue === null) {
-      return createSchema({
-        type: 'null',
-        primitive: 'null',
-        name,
-        title: schema.title,
-        description: schema.description,
-        deprecated: schema.deprecated,
-        nullable,
-      })
-    }
-
-    const constPrimitive = getPrimitiveType(typeof constValue === 'number' ? 'number' : typeof constValue === 'boolean' ? 'boolean' : 'string')
-    return createSchema({
-      type: 'enum',
-      primitive: constPrimitive,
-      enumValues: [constValue as string | number | boolean],
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
-    })
-  }
-
-  /**
-   * Handles `format`-based special types (date/time, uuid, email, blob, etc.).
-   * Returns `undefined` when the format should fall through to string handling
-   * (i.e. `format: 'date-time'` with `dateType: false`).
-   */
-  function convertFormat({ schema, name, nullable, defaultValue, mergedOptions }: SchemaContext): SchemaNode | undefined {
-    const base = buildSchemaBase(schema, name, nullable, defaultValue)
-
-    // int64 is option-dependent so it can't live in the static FORMAT_MAP.
-    if (schema.format === 'int64') {
-      return createSchema({
-        type: mergedOptions.integerType === 'bigint' ? 'bigint' : 'integer',
-        primitive: 'integer',
-        ...base,
-        min: schema.minimum,
-        max: schema.maximum,
-        exclusiveMinimum: typeof schema.exclusiveMinimum === 'number' ? schema.exclusiveMinimum : undefined,
-        exclusiveMaximum: typeof schema.exclusiveMaximum === 'number' ? schema.exclusiveMaximum : undefined,
-      })
-    }
-
-    // date-time / date / time are option-dependent and can't live in the static FORMAT_MAP.
-    if (schema.format === 'date-time' || schema.format === 'date' || schema.format === 'time') {
-      const dateType = getDateType(mergedOptions, schema.format)
-      if (!dateType) return undefined // dateType: false → fall through to string
-
-      if (dateType.type === 'datetime') {
-        return createSchema({ ...base, primitive: 'string' as const, type: 'datetime', offset: dateType.offset, local: dateType.local })
-      }
-      return createSchema({ ...base, primitive: 'string' as const, type: dateType.type, representation: dateType.representation })
-    }
-
-    const specialType = formatToSchemaType(schema.format!)
-    if (!specialType) return undefined
-
-    const specialPrimitive: PrimitiveSchemaType = specialType === 'number' || specialType === 'integer' || specialType === 'bigint' ? specialType : 'string'
-
-    if (specialType === 'number' || specialType === 'integer' || specialType === 'bigint') {
-      return createSchema({ ...base, primitive: specialPrimitive, type: specialType })
-    }
-    return createSchema({ ...base, primitive: specialPrimitive, type: specialType as ScalarSchemaType })
-  }
-
-  /**
-   * Converts an `enum` schema into an `EnumSchemaNode`.
-   *
-   * Handles several edge cases:
-   * - `{ type: 'array', enum }` (technically invalid OAS) — the enum is normalized into `items`.
-   * - `null` in enum values (OAS 3.0 nullable enum convention) — stripped and reflected as `nullable`.
-   * - `x-enumNames` / `x-enum-varnames` vendor extensions — produce named enum variants with explicit labels.
-   * - Numeric and boolean enums require a const-map representation because most generators cannot
-   *   use string-enum syntax for non-string values.
-   */
-  function convertEnum({ schema, name, nullable, type, options }: SchemaContext): SchemaNode {
-    // Malformed schema: `{ type: 'array', enum: [...] }` — normalize by moving the enum into items.
-    if (type === 'array') {
-      const rawSchema = schema as unknown as { items?: SchemaObject; enum?: unknown[] }
-      const isItemsObject = typeof rawSchema.items === 'object' && !Array.isArray(rawSchema.items)
-      const normalizedItems = { ...(isItemsObject ? rawSchema.items : {}), enum: schema.enum } as SchemaObject
-      const { enum: _enum, ...schemaWithoutEnum } = schema as SchemaObject & { enum?: unknown[] }
-      return convertSchema({ schema: { ...schemaWithoutEnum, items: normalizedItems } as SchemaObject, name }, options)
-    }
-
-    // `null` in enum values is the OAS 3.0 convention for a nullable enum.
-    const nullInEnum = schema.enum!.includes(null)
-    const filteredValues = (nullInEnum ? schema.enum!.filter((v) => v !== null) : schema.enum!) as Array<string | number | boolean>
-    const enumNullable = nullable || nullInEnum || undefined
-    const enumDefault = schema.default === null && enumNullable ? undefined : schema.default
-    const enumPrimitive = getPrimitiveType(type)
-
-    const enumBase = {
-      type: 'enum' as const,
-      primitive: enumPrimitive,
-      name,
-      title: schema.title,
-      description: schema.description,
-      deprecated: schema.deprecated,
-      nullable: enumNullable,
-      readOnly: schema.readOnly,
-      writeOnly: schema.writeOnly,
-      default: enumDefault,
-      example: schema.example,
-    }
-
-    // x-enumNames / x-enum-varnames: named variants with explicit labels take priority.
-    const extensionKey = ENUM_EXTENSION_KEYS.find((key) => key in schema)
-    if (extensionKey) {
-      const rawNames = (schema as Record<string, unknown>)[extensionKey] as Array<string | number>
-      const uniqueNames = [...new Set(rawNames)]
-      const enumType =
-        getPrimitiveType(type) === 'number' || getPrimitiveType(type) === 'integer'
-          ? ('number' as const)
-          : getPrimitiveType(type) === 'boolean'
-            ? ('boolean' as const)
-            : ('string' as const)
-
-      return createSchema({
-        ...enumBase,
-        enumType,
-        namedEnumValues: uniqueNames.map((label, index) => ({
-          name: String(label),
-          value: filteredValues[index] ?? label,
-          format: enumType,
-        })),
-      })
-    }
-
-    // Number / integer enum — must use a const map since most generators can't use string-enum for numbers.
-    if (type === 'number' || type === 'integer') {
-      return createSchema({
-        ...enumBase,
-        enumType: 'number' as const,
-        namedEnumValues: [...new Set(filteredValues)].map((value) => ({
-          name: String(value),
-          value: value as number,
-          format: 'number' as const,
-        })),
-      })
-    }
-
-    // Boolean enum — same const-map approach as numeric.
-    if (type === 'boolean') {
-      return createSchema({
-        ...enumBase,
-        enumType: 'boolean' as const,
-        namedEnumValues: [...new Set(filteredValues)].map((value) => ({
-          name: String(value),
-          value: value as boolean,
-          format: 'boolean' as const,
-        })),
-      })
-    }
-
-    // Plain string enum (default path).
-    return createSchema({
-      ...enumBase,
-      enumValues: [...new Set(filteredValues)],
-    })
-  }
-
-  /**
-   * Converts an object-like schema (`type: 'object'`, `properties`, `additionalProperties`,
-   * or `patternProperties`) into an `ObjectSchemaNode`.
-   *
-   * When a `discriminator` is present, the discriminator property's schema is replaced with an
-   * enum of the mapping keys so generators can produce a precise literal-union type for it.
-   *
-   * Property optionality follows OAS semantics:
-   * - required + not nullable → `required: true`
-   * - not required + not nullable → `optional: true`
-   * - not required + nullable → `nullish: true`
-   */
-  function convertObject({ schema, name, nullable, defaultValue, options, mergedOptions }: SchemaContext): SchemaNode {
-    // When a discriminator is present, override the discriminator property's schema to use
-    // an enum of the mapping keys for a precise literal-union type.
-    const resolvedSchema: SchemaObject = (() => {
-      if (!isDiscriminator(schema)) return schema
-      const propName = schema.discriminator.propertyName
-      if (!schema.properties?.[propName]) return schema
-      return {
-        ...schema,
-        properties: {
-          ...schema.properties,
-          [propName]: {
-            ...(schema.properties[propName] as SchemaObject),
-            enum: schema.discriminator.mapping ? Object.keys(schema.discriminator.mapping) : undefined,
-          },
-        },
-      } as SchemaObject
-    })()
-
-    const properties: Array<PropertyNode> = resolvedSchema.properties
-      ? Object.entries(resolvedSchema.properties).map(([propName, propSchema]) => {
-          const required = Array.isArray(resolvedSchema.required) ? resolvedSchema.required.includes(propName) : !!resolvedSchema.required
-          const resolvedPropSchema = propSchema as SchemaObject
-          const propNullable = isNullable(resolvedPropSchema)
-          const derivedPropName = name ? pascalCase([name, propName, mergedOptions.enumSuffix].filter(Boolean).join(' ')) : undefined
-
-          return createProperty({
-            name: propName,
-            schema: {
-              ...convertSchema({ schema: resolvedPropSchema, name: derivedPropName }, options),
-              nullable: propNullable || undefined,
-              optional: !required && !propNullable ? true : undefined,
-              nullish: !required && propNullable ? true : undefined,
-            },
-            required,
-          })
-        })
-      : []
-
-    const additionalProperties = resolvedSchema.additionalProperties
-    let additionalPropertiesNode: SchemaNode | true | undefined
-    if (additionalProperties === true) {
-      additionalPropertiesNode = true
-    } else if (additionalProperties && Object.keys(additionalProperties).length > 0) {
-      additionalPropertiesNode = convertSchema({ schema: additionalProperties as SchemaObject }, options)
-    } else if (additionalProperties === false) {
-      additionalPropertiesNode = undefined
-    } else if (additionalProperties) {
-      additionalPropertiesNode = createSchema({ type: getUnknownType(mergedOptions) })
-    }
-
-    const rawPatternProperties =
-      'patternProperties' in resolvedSchema ? (resolvedSchema as unknown as { patternProperties?: Record<string, SchemaObject> }).patternProperties : undefined
-
-    const patternProperties = rawPatternProperties
-      ? Object.fromEntries(
-          Object.entries(rawPatternProperties).map(([pattern, patternSchema]) => [
-            pattern,
-            (patternSchema as unknown) === true || Object.keys(patternSchema as object).length === 0
-              ? createSchema({ type: getUnknownType(mergedOptions) })
-              : convertSchema({ schema: patternSchema as SchemaObject }, options),
-          ]),
-        )
-      : undefined
-
-    return createSchema({
-      type: 'object',
-      primitive: 'object',
-      properties,
-      additionalProperties: additionalPropertiesNode,
-      patternProperties,
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
-    })
-  }
-
-  /**
-   * Converts an OAS 3.1 `prefixItems` tuple into a `TupleSchemaNode`.
-   *
-   * Each `prefixItems` element maps to a positional tuple slot. An optional `items` schema
-   * after the prefix items is mapped to the rest parameter of the tuple.
-   */
-  function convertTuple({ schema, name, nullable, defaultValue, options }: SchemaContext): SchemaNode {
-    const rawSchema = schema as unknown as { prefixItems: SchemaObject[]; items?: SchemaObject }
-    const tupleItems = rawSchema.prefixItems.map((item) => convertSchema({ schema: item }, options))
-    const rest = rawSchema.items ? convertSchema({ schema: rawSchema.items }, options) : undefined
-
-    return createSchema({
-      type: 'tuple',
-      primitive: 'array',
-      items: tupleItems,
-      rest,
-      min: schema.minItems,
-      max: schema.maxItems,
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
-    })
-  }
-
-  /**
-   * Converts a `type: 'array'` schema into an `ArraySchemaNode`.
-   *
-   * When the items schema is an inline enum, a name derived from the parent array's name and
-   * `enumSuffix` is forwarded so generators can emit a named enum declaration.
-   */
-  function convertArray({ schema, name, nullable, defaultValue, options, mergedOptions }: SchemaContext): SchemaNode {
-    const rawSchema = schema as unknown as { items?: SchemaObject }
-    // When the array items schema contains an inline enum, derive a name from the parent
-    // array's name + enumSuffix so generators can emit a named enum declaration.
-    const rawItems = rawSchema.items as SchemaObject | undefined
-    const itemName = rawItems?.enum?.length && name ? pascalCase([name, mergedOptions.enumSuffix].join(' ')) : undefined
-    const items = rawSchema.items ? [convertSchema({ schema: rawSchema.items, name: itemName }, options)] : []
-
-    return createSchema({
-      type: 'array',
-      primitive: 'array',
-      items,
-      min: schema.minItems,
-      max: schema.maxItems,
-      unique: schema.uniqueItems ?? undefined,
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
-    })
-  }
-
-  /**
-   * Converts a `type: 'string'` schema (without a special format) into a `StringSchemaNode`.
-   */
-  function convertString({ schema, name, nullable, defaultValue }: SchemaContext): SchemaNode {
-    return createSchema({
-      type: 'string',
-      primitive: 'string',
-      min: schema.minLength,
-      max: schema.maxLength,
-      pattern: schema.pattern,
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
-    })
-  }
-
-  /**
-   * Converts a `type: 'number'` schema into a `NumberSchemaNode`.
-   */
-  function convertNumber({ schema, name, nullable, defaultValue }: SchemaContext): SchemaNode {
-    return createSchema({
-      type: 'number',
-      primitive: 'number',
-      min: schema.minimum,
-      max: schema.maximum,
-      exclusiveMinimum: typeof schema.exclusiveMinimum === 'number' ? schema.exclusiveMinimum : undefined,
-      exclusiveMaximum: typeof schema.exclusiveMaximum === 'number' ? schema.exclusiveMaximum : undefined,
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
-    })
-  }
-
-  /**
-   * Converts a `type: 'integer'` schema into an `IntegerSchemaNode`.
-   */
-  function convertInteger({ schema, name, nullable, defaultValue }: SchemaContext): SchemaNode {
-    return createSchema({
-      type: 'integer',
-      primitive: 'integer',
-      min: schema.minimum,
-      max: schema.maximum,
-      exclusiveMinimum: typeof schema.exclusiveMinimum === 'number' ? schema.exclusiveMinimum : undefined,
-      exclusiveMaximum: typeof schema.exclusiveMaximum === 'number' ? schema.exclusiveMaximum : undefined,
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
-    })
-  }
-
-  /**
-   * Converts a `type: 'boolean'` schema into a `BooleanSchemaNode`.
-   */
-  function convertBoolean({ schema, name, nullable, defaultValue }: SchemaContext): SchemaNode {
-    return createSchema({
-      type: 'boolean',
-      primitive: 'boolean',
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
-    })
-  }
-
-  /**
-   * Converts an explicit `type: 'null'` or `const: null` schema into a `NullSchemaNode`.
-   */
-  function convertNull({ schema, name, nullable }: SchemaContext): SchemaNode {
-    return createSchema({
-      type: 'null',
-      primitive: 'null',
-      name,
-      title: schema.title,
-      description: schema.description,
-      deprecated: schema.deprecated,
-      nullable,
-    })
-  }
-
-  /**
-   * Central dispatcher: converts an OAS `SchemaObject` into a `SchemaNode`.
-   *
-   * Dispatch order (first match wins):
-   * 1. `$ref` pointer
-   * 2. `allOf` composition
-   * 3. `oneOf` / `anyOf` union
-   * 4. `const` literal (OAS 3.1)
-   * 5. `format`-based special type (date/time, uuid, blob, …)
-   * 6. OAS 3.1 `contentMediaType: 'application/octet-stream'` blob
-   * 7. OAS 3.1 multi-type array → union or fallthrough
-   * 8. Constraint-inferred type (minLength/maxLength → string; minimum/maximum → number)
-   * 9. `enum` values
-   * 10. Object / array / tuple / scalar by `type`
-   * 11. Empty schema fallback (`emptySchemaType` option)
-   */
-  function convertSchema({ schema, name }: { schema: SchemaObject; name?: string }, options?: Partial<Options>): SchemaNode {
-    const mergedOptions: Options = { ...DEFAULT_OPTIONS, ...options }
-    // Flatten keyword-only allOf fragments (no $ref, no structural keys) into the parent
-    // schema before parsing, so simple annotation patterns don't produce needless intersections.
-    const flattenedSchema = flattenSchema(schema as unknown as Parameters<typeof flattenSchema>[0]) as SchemaObject | null
-    if (flattenedSchema && flattenedSchema !== (schema as unknown)) {
-      return convertSchema({ schema: flattenedSchema, name }, options)
-    }
-
-    const nullable = isNullable(schema) || undefined
-    const defaultValue = schema.default === null && nullable ? undefined : schema.default
-    // Normalize OAS 3.1 multi-type array to a single type string for the dispatch below.
-    const type = Array.isArray(schema.type) ? schema.type[0] : schema.type
-
-    const ctx: SchemaContext = { schema, name, nullable, defaultValue, type, options, mergedOptions }
-
-    // $ref — pointer to another definition.
-    // In OAS 3.0 siblings of $ref are technically ignored, but Kubb intentionally preserves them
-    // so that annotations like `pattern`, `description`, and `nullable` are reflected in generated code.
-    if (isReference(schema)) return convertRef(ctx)
-
-    // Composition keywords
-    if (schema.allOf?.length) return convertAllOf(ctx)
-    const unionMembers = [...(schema.oneOf ?? []), ...(schema.anyOf ?? [])]
-    if (unionMembers.length) return convertUnion(ctx)
-
-    // OAS 3.1 const — a single fixed value, semantically equivalent to a one-item enum.
-    // `const: undefined` falls through to the empty-type fallback.
-    if ('const' in schema && schema.const !== undefined) return convertConst(ctx)
-
-    // Format-based special types take precedence over `type`.
-    // `convertFormat` returns undefined when format should fall through to string (dateType: false).
-    // see https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-validation-00#rfc.section.7
-    if (schema.format) {
-      const formatResult = convertFormat(ctx)
-      if (formatResult) return formatResult
-    }
-
-    // OAS 3.1: `contentMediaType: 'application/octet-stream'` on a string schema signals binary data.
-    if (schema.type === 'string' && (schema as SchemaObject & { contentMediaType?: string }).contentMediaType === 'application/octet-stream') {
-      return createSchema({ type: 'blob', primitive: 'string', ...buildSchemaBase(schema, name, nullable, defaultValue) })
-    }
-
-    // OAS 3.1: `type` may be an array — e.g. `["string", "integer", "null"]`.
-    // `null` in the array is the 3.1 equivalent of `nullable: true`; strip it and set the flag.
-    // When 2+ non-null types remain, produce a union; when exactly 1 non-null type remains, fall through.
-    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 createSchema({
-          type: 'union',
-          members: nonNullTypes.map((t) => convertSchema({ schema: { ...schema, type: t } as SchemaObject }, options)),
-          ...buildSchemaBase(schema, name, arrayNullable, defaultValue),
-        })
-      }
-    }
-
-    // Infer type from constraints when no explicit type is provided.
-    // minLength / maxLength / pattern → string; minimum / maximum → number.
-    // Note: minItems/maxItems do NOT infer array — arrays require an `items` key.
-    if (!type) {
-      if (schema.minLength !== undefined || schema.maxLength !== undefined || schema.pattern !== undefined) {
-        return convertString(ctx)
-      }
-      if (schema.minimum !== undefined || schema.maximum !== undefined) {
-        return convertNumber(ctx)
-      }
-    }
-
-    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 convertNumber(ctx)
-    if (type === 'integer') return convertInteger(ctx)
-    if (type === 'boolean') return convertBoolean(ctx)
-    if (type === 'null') return convertNull(ctx)
-
-    const emptyType = getEmptySchemaType(mergedOptions)
-    return createSchema({ type: emptyType as ScalarSchemaType, name, title: schema.title, description: schema.description })
-  }
-
-  /**
-   * Converts a single dereferenced OAS parameter object into a `ParameterNode`.
-   * When the parameter has no `schema` or its schema is a `$ref`, falls back to `unknownType`.
-   */
-  function parseParameter(options: Options, param: Record<string, unknown>): ParameterNode {
-    const schema =
-      param['schema'] && !isReference(param['schema'] as object)
-        ? convertSchema({ schema: param['schema'] as SchemaObject }, options)
-        : createSchema({ type: getUnknownType(options) })
-
-    return createParameter({
-      name: param['name'] as string,
-      in: param['in'] as ParameterLocation,
-      schema,
-      required: (param['required'] as boolean | undefined) ?? false,
-    })
-  }
-
-  /**
-   * Converts an OAS `Operation` into an `OperationNode`, resolving parameters,
-   * request body, and all response codes into their AST node equivalents.
-   */
-  function parseOperation(options: Options, oas: Oas, operation: Operation): OperationNode {
-    const parameters: Array<ParameterNode> = operation.getParameters().map((param) => {
-      const dereferenced = oas.dereferenceWithRef(param) as unknown as Record<string, unknown>
-
-      return parseParameter(options, dereferenced)
-    })
-
-    const requestBodySchema = oas.getRequestSchema(operation)
-    const requestBody = requestBodySchema ? convertSchema({ schema: requestBodySchema }, options) : undefined
-
-    const responses: Array<ResponseNode> = operation.getResponseStatusCodes().map((statusCode) => {
-      const responseObj = operation.getResponseByStatusCode(statusCode)
-      const responseSchema = oas.getResponseSchema(operation, statusCode)
-
-      const schema = responseSchema && Object.keys(responseSchema).length > 0 ? convertSchema({ schema: responseSchema }, options) : undefined
-
-      const description = typeof responseObj === 'object' && responseObj !== null && !Array.isArray(responseObj) ? responseObj.description : undefined
-
-      const rawContent =
-        typeof responseObj === 'object' && responseObj !== null && !Array.isArray(responseObj)
-          ? (responseObj as { content?: Record<string, unknown> }).content
-          : undefined
-
-      const mediaType = rawContent ? toMediaType(Object.keys(rawContent)[0] ?? '') : toMediaType(operation.contentType ?? '')
-
-      return createResponse({
-        statusCode: statusCode as StatusCode,
-        description,
-        schema,
-        mediaType,
-      })
-    })
-
-    return createOperation({
-      operationId: operation.getOperationId(),
-      method: operation.method.toUpperCase() as HttpMethod,
-      path: operation.path,
-      tags: operation.getTags().map((tag) => tag.name),
-      summary: operation.getSummary() || undefined,
-      description: operation.getDescription() || undefined,
-      deprecated: operation.isDeprecated() || undefined,
-      parameters,
-      requestBody,
-      responses,
-    })
-  }
-
-  /**
-   * Converts an OpenAPI/Swagger spec (wrapped in a Kubb `Oas` instance) into
-   * a `RootNode` — the top-level node of the `@kubb/ast` tree.
-   */
-  function buildAst<TOptions extends Partial<Options> = object>(options?: TOptions): RootNode {
-    const mergedOptions: Options = { ...DEFAULT_OPTIONS, ...options }
-
-    const schemas: Array<SchemaNode> = Object.entries(schemaObjects).map(([name, schemaObject]) =>
-      convertSchema({ schema: schemaObject as SchemaObject, name }, mergedOptions),
-    )
-
-    const paths = oas.getPaths()
-
-    const operations: Array<OperationNode> = Object.entries(paths).flatMap(([_path, methods]) =>
-      Object.entries(methods)
-        .map(([, operation]) => (operation ? parseOperation(mergedOptions, oas, operation) : null))
-        .filter((op): op is OperationNode => op !== null),
-    )
-
-    return createRoot({ schemas, operations })
-  }
-
-  /**
-   * Walks a `SchemaNode` tree and resolves all `ref` node names through the provided callbacks.
-   *
-   * `resolveName` handles all schema types; `resolveEnumName` (when provided) takes precedence
-   * for `enum` nodes, enabling a separate naming strategy for enums (e.g. different suffix).
-   *
-   * Collision-resolved names (from `nameMapping`) are applied before user-supplied resolvers.
-   */
-  function resolveRefs(node: SchemaNode, resolveName: (ref: string) => string | undefined, resolveEnumName?: (name: string) => string | undefined): SchemaNode {
-    return transform(node, {
-      schema(schemaNode) {
-        const schemaRef = narrowSchema(schemaNode, schemaTypes.ref)
-
-        if (schemaRef && (schemaRef.ref || schemaRef.name)) {
-          const rawRef = schemaRef.ref ?? schemaRef.name!
-          const resolved = resolveName(nameMapping.get(rawRef) ?? rawRef)
-          if (resolved) {
-            return { ...schemaNode, name: resolved }
-          }
-        }
-
-        if (schemaNode.type === 'enum' && schemaNode.name) {
-          const resolved = (resolveEnumName ?? resolveName)(schemaNode.name)
-          if (resolved) {
-            return { ...schemaNode, name: resolved }
-          }
-        }
-      },
-    }) as SchemaNode
-  }
-
-  /**
-   * Collects all `KubbFile.Import` descriptors needed by a `SchemaNode` tree.
-   *
-   * Walks the tree looking for `ref` nodes, verifies each `$ref` is resolvable in the spec,
-   * applies collision-resolved names from `nameMapping`, and calls `resolve` to obtain the
-   * import path and name. Returns an empty array for refs that cannot be resolved.
-   */
-  function getImports(node: SchemaNode, resolve: (schemaName: string) => { name: string; path: string } | undefined): Array<KubbFile.Import> {
-    return collect<KubbFile.Import>(node, {
-      schema(schemaNode): KubbFile.Import | undefined {
-        if (schemaNode.type !== 'ref' || !schemaNode.ref) return
-        // Use the OAS instance to verify this $ref is importable (exists in the spec).
-        if (!oas.get(schemaNode.ref)) return
-
-        const rawName = extractRefName(schemaNode.ref)
-
-        // Apply collision-resolved name if available.
-        const schemaName = nameMapping.get(rawName) ?? rawName
-        const result = resolve(schemaName)
-        if (!result) return
-
-        return { name: [result.name], path: result.path }
-      },
-    })
-  }
-
-  return {
-    buildAst,
-    convertSchema,
-    resolveRefs,
-    getImports,
-  } as OasParser
-}