@kubb/adapter-oas 5.0.0-alpha.1 → 5.0.0-alpha.11

package/src/parser.ts

@@ -1,16 +1,5 @@
-import { pascalCase } from '@internals/utils'
-import {
-  collect,
-  createOperation,
-  createParameter,
-  createProperty,
-  createResponse,
-  createRoot,
-  createSchema,
-  narrowSchema,
-  schemaTypes,
-  transform,
-} from '@kubb/ast'
+import { getUniqueName, pascalCase, URLPath } from '@internals/utils'
+import { createOperation, createParameter, createProperty, createResponse, createRoot, createSchema, narrowSchema, schemaTypes, transform } from '@kubb/ast'
 import type {
   ArraySchemaNode,
   DateSchemaNode,
@@ -38,11 +27,12 @@ import type {
   TimeSchemaNode,
   UnionSchemaNode,
 } from '@kubb/ast/types'
-import type { KubbFile } from '@kubb/fabric-core/types'
-import { enumExtensionKeys, formatMap, knownMediaTypes } from './constants.ts'
+import { DEFAULT_PARSER_OPTIONS, enumExtensionKeys, formatMap, knownMediaTypes } from './constants.ts'
 import type { Oas } from './oas/Oas.ts'
-import type { contentType, Operation, SchemaObject } from './oas/types.ts'
+import type { contentType, Operation, ReferenceObject, SchemaObject } from './oas/types.ts'
 import { flattenSchema, isDiscriminator, isNullable, isReference } from './oas/utils.ts'
+import type { ParserOptions } from './types.ts'
+import { applyDiscriminatorEnum, extractRefName, mergeAdjacentAnonymousObjects, simplifyUnionMembers } from './utils.ts'
 
 /**
  * Distributive `Omit` — correctly distributes over union types so that
@@ -65,14 +55,16 @@ type DateTimeNodeByDateType = {
 /**
  * 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']
+type ResolveDateTimeNode<TDateType extends ParserOptions['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']> = [
+type SchemaNodeMap<TDateType extends ParserOptions['dateType'] = 'string'> = [
   [{ $ref: string }, RefSchemaNode],
   // allOf with sibling `properties` always produces an intersection (shared props are appended as a member).
   [{ allOf: ReadonlyArray<unknown>; properties: object }, IntersectionSchemaNode],
@@ -116,7 +108,7 @@ type SchemaNodeMap<TDateType extends Options['dateType'] = Options['dateType']>
 
 export type InferSchemaNode<
   TSchema extends SchemaObject,
-  TDateType extends Options['dateType'] = Options['dateType'],
+  TDateType extends ParserOptions['dateType'] = 'string',
   TEntries extends ReadonlyArray<[object, SchemaNode]> = SchemaNodeMap<TDateType>,
 > = TEntries extends [infer TEntry extends [object, SchemaNode], ...infer TRest extends ReadonlyArray<[object, SchemaNode]>]
   ? TSchema extends TEntry[0]
@@ -124,32 +116,6 @@ export type InferSchemaNode<
     : 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`.
  */
@@ -158,17 +124,6 @@ export type OasParserOptions = {
   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 `formatMap` (e.g. `int64`, `date-time`),
@@ -178,15 +133,6 @@ function formatToSchemaType(format: string): SchemaType | undefined {
   return formatMap[format as keyof typeof formatMap]
 }
 
-/**
- * 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;
@@ -203,7 +149,7 @@ function getPrimitiveType(type: string | undefined): PrimitiveSchemaType {
  * Returns `undefined` for content types not present in `KNOWN_MEDIA_TYPES`.
  */
 function toMediaType(contentType: string): MediaType | undefined {
-  return knownMediaTypes.includes(contentType as MediaType) ? (contentType as MediaType) : undefined
+  return knownMediaTypes.has(contentType as MediaType) ? (contentType as MediaType) : undefined
 }
 
 /**
@@ -219,8 +165,8 @@ type SchemaContext = {
    * Normalized single type string (first element when OAS 3.1 multi-type array).
    */
   type: string | undefined
-  options: Partial<Options> | undefined
-  mergedOptions: Options
+  options: Partial<ParserOptions> | undefined
+  mergedOptions: ParserOptions
 }
 
 /**
@@ -231,11 +177,11 @@ 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.
    */
-  parse: <TOptions extends Partial<Options> = object>(options?: TOptions) => RootNode
-  convertSchema: <TFormat extends string, TSchema extends SchemaObject & { format?: TFormat }, TOptions extends Partial<Options> = object>(
+  parse: <TOptions extends Partial<ParserOptions> = object>(options?: TOptions) => RootNode
+  convertSchema: <TFormat extends string, TSchema extends SchemaObject & { format?: TFormat }, TOptions extends Partial<ParserOptions> = object>(
     params: { schema: TSchema; name?: string },
     options?: TOptions,
-  ) => InferSchemaNode<TSchema, TOptions extends { dateType: Options['dateType'] } ? TOptions['dateType'] : (typeof DEFAULT_OPTIONS)['dateType']>
+  ) => InferSchemaNode<TSchema, TOptions extends { dateType: ParserOptions['dateType'] } ? TOptions['dateType'] : 'string'>
   /**
    * 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`)
@@ -245,45 +191,15 @@ export type OasParser = {
    * 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).
+   * Map from original `$ref` paths to their collision-resolved schema names.
+   * e.g. `'#/components/schemas/Order'` → `'OrderSchema'`
    *
-   * 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,
-   * }))
-   * ```
+   * Pass this to the standalone `getImports()` to resolve imports without holding
+   * a reference to the full parser or OAS instance.
    */
-  getImports: (node: SchemaNode, resolve: (schemaName: string) => { name: string; path: string } | undefined) => Array<KubbFile.Import>
-}
-
-/**
- * When a discriminator is present, replaces the discriminator property's schema with
- * an enum of the mapping keys so downstream code emits a precise literal-union type.
- * Returns the original schema unchanged when there is no discriminator or no mapping.
- */
-function applyDiscriminatorEnum(schema: SchemaObject): 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
+  nameMapping: Map<string, string>
 }
 
 /**
@@ -310,6 +226,14 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
   // e.g., { '#/components/schemas/Order': 'OrderSchema', '#/components/responses/Product': 'ProductResponse' }
   const { schemas: schemaObjects, nameMapping } = oas.getSchemas({ contentType, collisionDetection })
 
+  // Legacy enum name deduplication: tracks used enum names and appends numeric suffixes
+  // (e.g. ParamsStatusEnum, ParamsStatusEnum2) when collisionDetection is disabled.
+  const usedEnumNames: Record<string, number> = {}
+
+  // Only apply legacy naming when collisionDetection is explicitly false.
+  // When undefined (e.g. direct parser usage without adapter), use the default (new) behavior.
+  const isLegacyNaming = collisionDetection === false
+
   /**
    * Maps an `'any' | 'unknown' | 'void'` option string to the corresponding `SchemaType` constant.
    * Used for both `unknownType` (unannotated schemas) and `emptySchemaType` (empty `{}` schemas).
@@ -325,7 +249,7 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
    * Returns `undefined` when `dateType` is `false`, meaning the format should fall through to `string`.
    */
   function getDateType(
-    options: Options,
+    options: ParserOptions,
     format: 'date-time' | 'date' | 'time',
   ): { type: 'datetime'; offset?: boolean; local?: boolean } | { type: 'date' | 'time'; representation: 'date' | 'string' } | undefined {
     if (!options.dateType) {
@@ -357,7 +281,7 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
    * 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) {
+  function renderSchemaBase(schema: SchemaObject, name: string | undefined, nullable: true | undefined, defaultValue: unknown) {
     return {
       name,
       nullable,
@@ -383,18 +307,17 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
    * 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,
+      name: extractRefName(schema.$ref!),
+      ref: schema.$ref,
       nullable,
-      description: schemaObject.description,
-      deprecated: schemaObject.deprecated,
-      readOnly: schemaObject.readOnly,
-      writeOnly: schemaObject.writeOnly,
-      pattern: schemaObject.type === 'string' ? schemaObject.pattern : undefined,
-      example: schemaObject.example,
+      description: schema.description,
+      deprecated: schema.deprecated,
+      readOnly: schema.readOnly,
+      writeOnly: schema.writeOnly,
+      pattern: schema.type === 'string' ? schema.pattern : undefined,
+      example: schema.example,
       default: defaultValue,
     })
   }
@@ -421,8 +344,8 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       !(Array.isArray(schema.required) && schema.required.length) &&
       schema.additionalProperties === undefined
     ) {
-      const [memberSchema] = schema.allOf as SchemaObject[]
-      const memberNode = convertSchema({ schema: memberSchema! }, options)
+      const [memberSchema] = schema.allOf as Array<SchemaObject | ReferenceObject>
+      const memberNode = convertSchema({ schema: memberSchema! as SchemaObject }, options)
       const { kind: _kind, ...memberNodeProps } = memberNode
       const mergedNullable = nullable || memberNode.nullable || undefined
       const mergedDefault = schema.default === null && mergedNullable ? undefined : (schema.default ?? memberNode.default)
@@ -444,22 +367,24 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
 
     // 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[])
+    const allOfMembers: Array<SchemaNode> = (schema.allOf as Array<SchemaObject | ReferenceObject>)
       .filter((item) => {
         if (!isReference(item) || !name) return true
-        const deref = oas.get<SchemaObject>((item as { $ref: string }).$ref)
+        const deref = oas.get<SchemaObject>(item.$ref)
         if (!deref || !isDiscriminator(deref)) return true
-        const parentUnion = (deref as SchemaObject).oneOf ?? (deref as SchemaObject).anyOf
+        const parentUnion = deref.oneOf ?? deref.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,
-        )
+        const inOneOf = parentUnion.some((oneOfItem) => isReference(oneOfItem) && oneOfItem.$ref === childRef)
+        const inMapping = Object.values(deref.discriminator.mapping ?? {}).some((v) => v === childRef)
         return !inOneOf && !inMapping
       })
       .map((s) => convertSchema({ schema: s as SchemaObject }, options))
 
+    // Track where allOf-derived members end so only the synthetic members added below
+    // (injected required-key objects + outer-properties object) are candidates for merging.
+    const syntheticStart = allOfMembers.length
+
     // 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) {
@@ -467,10 +392,10 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       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 resolvedMembers = (schema.allOf as Array<SchemaObject | ReferenceObject>).flatMap((item) => {
+          if (!isReference(item)) return [item as SchemaObject]
           const deref = oas.get<SchemaObject>(item.$ref)
-          return deref && !isReference(deref) ? [deref as SchemaObject] : []
+          return deref && !isReference(deref) ? [deref] : []
         })
 
         for (const key of missingRequired) {
@@ -485,14 +410,15 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
     }
 
     if (schema.properties) {
-      const { allOf: _allOf, ...schemaWithoutAllOf } = schema as SchemaObject & { allOf?: unknown[] }
-      allOfMembers.push(convertSchema({ schema: schemaWithoutAllOf as SchemaObject }, options))
+      const { allOf: _allOf, ...schemaWithoutAllOf } = schema
+      allOfMembers.push(convertSchema({ schema: schemaWithoutAllOf }, options))
     }
 
+    // Merge consecutive anonymous object members within the synthetic portion — see `mergeAdjacentAnonymousObjects`.
     return createSchema({
       type: 'intersection',
-      members: allOfMembers,
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
+      members: [...allOfMembers.slice(0, syntheticStart), ...mergeAdjacentAnonymousObjects(allOfMembers.slice(syntheticStart))],
+      ...renderSchemaBase(schema, name, nullable, defaultValue),
     })
   }
 
@@ -507,30 +433,48 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
   function convertUnion({ schema, name, nullable, defaultValue, options }: SchemaContext): SchemaNode {
     const unionMembers = [...(schema.oneOf ?? []), ...(schema.anyOf ?? [])]
     const unionBase = {
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
+      ...renderSchemaBase(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)
+      const { oneOf: _oneOf, anyOf: _anyOf, ...schemaWithoutUnion } = schema
+      const discriminator = isDiscriminator(schema) ? schema.discriminator : undefined
+
+      // Strip discriminator so convertObject won't re-apply the full mapping enum.
+      const memberBaseSchema: SchemaObject = discriminator
+        ? (Object.fromEntries(Object.entries(schemaWithoutUnion).filter(([key]) => key !== 'discriminator')) as SchemaObject)
+        : schemaWithoutUnion
+
+      // Convert shared properties once to avoid duplicate enum naming
+      // (e.g. StatusEnum appearing twice and getting a numeric suffix).
+      const sharedPropertiesNode = convertSchema({ schema: memberBaseSchema, name: isLegacyNaming ? undefined : name }, options)
 
       return createSchema({
         type: 'union',
         ...unionBase,
-        members: unionMembers.map((s) =>
-          createSchema({
+        members: unionMembers.map((s) => {
+          const ref = isReference(s) ? s.$ref : undefined
+          const discriminatorValue = discriminator?.mapping && ref ? Object.entries(discriminator.mapping).find(([, v]) => v === ref)?.[0] : undefined
+
+          let propertiesNode = sharedPropertiesNode
+
+          if (discriminatorValue && discriminator) {
+            propertiesNode = applyDiscriminatorEnum({ node: propertiesNode, propertyName: discriminator.propertyName, values: [discriminatorValue] })
+          }
+
+          return 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)),
+      members: simplifyUnionMembers(unionMembers.map((s) => convertSchema({ schema: s as SchemaObject }, options))),
     })
   }
 
@@ -559,7 +503,7 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       type: 'enum',
       primitive: constPrimitive,
       enumValues: [constValue as string | number | boolean],
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
+      ...renderSchemaBase(schema, name, nullable, defaultValue),
     })
   }
 
@@ -569,7 +513,7 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
    * (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)
+    const base = renderSchemaBase(schema, name, nullable, defaultValue)
 
     // int64 is option-dependent so it can't live in the static formatMap.
     if (schema.format === 'int64') {
@@ -603,6 +547,10 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
     if (specialType === 'number' || specialType === 'integer' || specialType === 'bigint') {
       return createSchema({ ...base, primitive: specialPrimitive, type: specialType })
     }
+    if (specialType === 'url') {
+      return createSchema({ ...base, primitive: 'string' as const, type: 'url' })
+    }
+
     return createSchema({ ...base, primitive: specialPrimitive, type: specialType as ScalarSchemaType })
   }
 
@@ -619,10 +567,9 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
   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[] }
+      const isItemsObject = typeof schema.items === 'object' && !Array.isArray(schema.items)
+      const normalizedItems: SchemaObject = { ...(isItemsObject ? (schema.items as SchemaObject) : {}), enum: schema.enum }
+      const { enum: _enum, ...schemaWithoutEnum } = schema
       return convertSchema({ schema: { ...schemaWithoutEnum, items: normalizedItems } as SchemaObject, name }, options)
     }
 
@@ -715,22 +662,69 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
    * - 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 = applyDiscriminatorEnum(schema)
+  /**
+   * Builds the propagation name for a child property during recursive schema conversion.
+   *
+   * - **Legacy naming** (`isLegacyNaming`): only the immediate property key is used
+   *   (e.g. `Params` for property `params`), keeping nested names short.
+   * - **Default naming**: the parent name is prepended so the full path is encoded
+   *   (e.g. `OrderParams` when parent is `Order`).
+   */
+  function resolveChildName(parentName: string | undefined, propName: string): string | undefined {
+    if (isLegacyNaming) {
+      return pascalCase(propName)
+    }
+    return parentName ? pascalCase([parentName, propName].join(' ')) : undefined
+  }
+
+  /**
+   * Derives the final name for an enum property schema node.
+   *
+   * The raw name always includes the enum suffix (e.g. `StatusEnum`).
+   * In legacy mode an additional deduplication step appends a numeric suffix
+   * when the same name has already been used (e.g. `ParamsStatusEnum2`).
+   */
+  function resolveEnumPropName(parentName: string | undefined, propName: string, enumSuffix: string): string {
+    const raw = pascalCase([parentName, propName, enumSuffix].filter(Boolean).join(' '))
+    return isLegacyNaming ? getUniqueName(raw, usedEnumNames) : raw
+  }
+
+  /**
+   * Given a freshly-converted property schema, returns the node with a correct
+   * `name` attached — or stripped — depending on whether the node is a named
+   * enum, a boolean const-enum (always inlined), or a regular schema.
+   */
+  function applyEnumName(propNode: SchemaNode, parentName: string | undefined, propName: string, enumSuffix: string): SchemaNode {
+    const enumNode = narrowSchema(propNode, 'enum')
 
-    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
+    // Boolean-primitive enum nodes (e.g. `const: false`) are always inlined as
+    // literal types and must not receive a named identifier.
+    if (enumNode?.primitive === 'boolean') {
+      return { ...propNode, name: undefined }
+    }
+
+    if (enumNode) {
+      return { ...propNode, name: resolveEnumPropName(parentName, propName, enumSuffix) }
+    }
+
+    return propNode
+  }
+
+  function convertObject({ schema, name, nullable, defaultValue, options, mergedOptions }: SchemaContext): SchemaNode {
+    const properties: Array<PropertyNode> = schema.properties
+      ? 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 derivedPropName = name ? pascalCase([name, propName, mergedOptions.enumSuffix].filter(Boolean).join(' ')) : undefined
+
+          const childName = resolveChildName(name, propName)
+          const propNode = convertSchema({ schema: resolvedPropSchema, name: childName }, options)
+          const schemaNode = applyEnumName(propNode, name, propName, mergedOptions.enumSuffix)
 
           return createProperty({
             name: propName,
             schema: {
-              ...convertSchema({ schema: resolvedPropSchema, name: derivedPropName }, options),
+              ...schemaNode,
               nullable: propNullable || undefined,
               optional: !required && !propNullable ? true : undefined,
               nullish: !required && propNullable ? true : undefined,
@@ -740,7 +734,7 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
         })
       : []
 
-    const additionalProperties = resolvedSchema.additionalProperties
+    const additionalProperties = schema.additionalProperties
     let additionalPropertiesNode: SchemaNode | true | undefined
     if (additionalProperties === true) {
       additionalPropertiesNode = true
@@ -752,28 +746,38 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       additionalPropertiesNode = createSchema({ type: resolveTypeOption(mergedOptions.unknownType) })
     }
 
-    const rawPatternProperties =
-      'patternProperties' in resolvedSchema ? (resolvedSchema as unknown as { patternProperties?: Record<string, SchemaObject> }).patternProperties : undefined
+    const rawPatternProperties = 'patternProperties' in schema ? schema.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
+            patternSchema === true || (typeof patternSchema === 'object' && Object.keys(patternSchema).length === 0)
               ? createSchema({ type: resolveTypeOption(mergedOptions.unknownType) })
               : convertSchema({ schema: patternSchema as SchemaObject }, options),
           ]),
         )
       : undefined
 
-    return createSchema({
+    const objectNode: SchemaNode = createSchema({
       type: 'object',
       primitive: 'object',
       properties,
       additionalProperties: additionalPropertiesNode,
       patternProperties,
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
+      ...renderSchemaBase(schema, name, nullable, defaultValue),
     })
+
+    // When a discriminator is present, replace the discriminator property's schema
+    // with an enum of the mapping keys for a precise literal-union type.
+    if (isDiscriminator(schema) && schema.discriminator.mapping) {
+      const discPropName = schema.discriminator.propertyName
+      const values = Object.keys(schema.discriminator.mapping)
+      const enumName = name ? resolveEnumPropName(name, discPropName, mergedOptions.enumSuffix) : undefined
+      return applyDiscriminatorEnum({ node: objectNode, propertyName: discPropName, values, enumName })
+    }
+
+    return objectNode
   }
 
   /**
@@ -783,9 +787,8 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
    * 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
+    const tupleItems = (schema.prefixItems ?? []).map((item) => convertSchema({ schema: item as SchemaObject }, options))
+    const rest = schema.items ? convertSchema({ schema: schema.items as SchemaObject }, options) : undefined
 
     return createSchema({
       type: 'tuple',
@@ -794,7 +797,7 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       rest,
       min: schema.minItems,
       max: schema.maxItems,
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
+      ...renderSchemaBase(schema, name, nullable, defaultValue),
     })
   }
 
@@ -805,12 +808,11 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
    * `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)] : []
+    const rawItems = schema.items as SchemaObject | undefined
+    // When the items schema contains an inline enum, derive a named identifier
+    // so generators can emit a standalone enum declaration.
+    const itemName = rawItems?.enum?.length && name ? resolveEnumPropName(undefined, name, mergedOptions.enumSuffix) : undefined
+    const items = rawItems ? [convertSchema({ schema: rawItems, name: itemName }, options)] : []
 
     return createSchema({
       type: 'array',
@@ -819,7 +821,7 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       min: schema.minItems,
       max: schema.maxItems,
       unique: schema.uniqueItems ?? undefined,
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
+      ...renderSchemaBase(schema, name, nullable, defaultValue),
     })
   }
 
@@ -833,7 +835,7 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       min: schema.minLength,
       max: schema.maxLength,
       pattern: schema.pattern,
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
+      ...renderSchemaBase(schema, name, nullable, defaultValue),
     })
   }
 
@@ -848,7 +850,7 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       max: schema.maximum,
       exclusiveMinimum: typeof schema.exclusiveMinimum === 'number' ? schema.exclusiveMinimum : undefined,
       exclusiveMaximum: typeof schema.exclusiveMaximum === 'number' ? schema.exclusiveMaximum : undefined,
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
+      ...renderSchemaBase(schema, name, nullable, defaultValue),
     })
   }
 
@@ -859,7 +861,7 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
     return createSchema({
       type: 'boolean',
       primitive: 'boolean',
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
+      ...renderSchemaBase(schema, name, nullable, defaultValue),
     })
   }
 
@@ -894,12 +896,12 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
    * 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 }
+  function convertSchema({ schema, name }: { schema: SchemaObject; name?: string }, options?: Partial<ParserOptions>): SchemaNode {
+    const mergedOptions: ParserOptions = { ...DEFAULT_PARSER_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)) {
+    const flattenedSchema = flattenSchema(schema)
+    if (flattenedSchema && flattenedSchema !== schema) {
       return convertSchema({ schema: flattenedSchema, name }, options)
     }
 
@@ -933,8 +935,8 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
     }
 
     // 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) })
+    if (schema.type === 'string' && schema.contentMediaType === 'application/octet-stream') {
+      return createSchema({ type: 'blob', primitive: 'string', ...renderSchemaBase(schema, name, nullable, defaultValue) })
     }
 
     // OAS 3.1: `type` may be an array — e.g. `["string", "integer", "null"]`.
@@ -947,8 +949,8 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       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),
+          members: nonNullTypes.map((t) => convertSchema({ schema: { ...schema, type: t } as SchemaObject, name }, options)),
+          ...renderSchemaBase(schema, name, arrayNullable, defaultValue),
         })
       }
     }
@@ -983,17 +985,23 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
    * 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)
+  function parseParameter(options: ParserOptions, param: Record<string, unknown>): ParameterNode {
+    const required = (param['required'] as boolean | undefined) ?? false
+
+    const schema: SchemaNode =
+      param['schema'] && !isReference(param['schema'])
         ? convertSchema({ schema: param['schema'] as SchemaObject }, options)
         : createSchema({ type: resolveTypeOption(options.unknownType) })
 
     return createParameter({
       name: param['name'] as string,
       in: param['in'] as ParameterLocation,
-      schema,
-      required: (param['required'] as boolean | undefined) ?? false,
+      schema: {
+        ...schema,
+        description: (param['description'] as string | undefined) ?? schema.description,
+        optional: !required || !!schema.optional ? true : undefined,
+      },
+      required,
     })
   }
 
@@ -1001,12 +1009,8 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
    * 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)
-    })
+  function parseOperation(options: ParserOptions, oas: Oas, operation: Operation): OperationNode {
+    const parameters: Array<ParameterNode> = oas.getParameters(operation).map((param) => parseParameter(options, param as unknown as Record<string, unknown>))
 
     const requestBodySchema = oas.getRequestSchema(operation)
     const requestBody = requestBodySchema ? convertSchema({ schema: requestBodySchema }, options) : undefined
@@ -1015,7 +1019,10 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       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 schema =
+        responseSchema && Object.keys(responseSchema).length > 0
+          ? convertSchema({ schema: responseSchema }, options)
+          : createSchema({ type: resolveTypeOption(options.emptySchemaType) })
 
       const description = typeof responseObj === 'object' && responseObj !== null && !Array.isArray(responseObj) ? responseObj.description : undefined
 
@@ -1037,7 +1044,7 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
     return createOperation({
       operationId: operation.getOperationId(),
       method: operation.method.toUpperCase() as HttpMethod,
-      path: operation.path,
+      path: new URLPath(operation.path).URL,
       tags: operation.getTags().map((tag) => tag.name),
       summary: operation.getSummary() || undefined,
       description: operation.getDescription() || undefined,
@@ -1052,8 +1059,8 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
    * Converts an OpenAPI/Swagger spec (wrapped in a Kubb `Oas` instance) into
    * a `RootNode` — the top-level node of the `@kubb/ast` tree.
    */
-  function parse<TOptions extends Partial<Options> = object>(options?: TOptions): RootNode {
-    const mergedOptions: Options = { ...DEFAULT_OPTIONS, ...options }
+  function parse<TOptions extends Partial<ParserOptions> = object>(options?: TOptions): RootNode {
+    const mergedOptions: ParserOptions = { ...DEFAULT_PARSER_OPTIONS, ...options }
 
     const schemas: Array<SchemaNode> = Object.entries(schemaObjects).map(([name, schemaObject]) =>
       convertSchema({ schema: schemaObject as SchemaObject, name }, mergedOptions),
@@ -1101,36 +1108,10 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
     }) 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 {
-    parse: parse,
+    parse,
     convertSchema,
     resolveRefs,
-    getImports,
+    nameMapping,
   } as OasParser
 }