@kubb/adapter-oas 5.0.0-alpha.9 → 5.0.0-beta.2

package/package.json

@@ -1,25 +1,35 @@
 {
   "name": "@kubb/adapter-oas",
-  "version": "5.0.0-alpha.9",
-  "description": "OpenAPI / Swagger adapter for Kubb — converts OAS input into a @kubb/ast RootNode.",
+  "version": "5.0.0-beta.2",
+  "description": "OpenAPI / Swagger adapter for Kubb converts OAS input into a @kubb/ast RootNode.",
   "keywords": [
-    "openapi",
-    "swagger",
-    "oas",
     "adapter",
-    "kubb",
     "codegen",
+    "kubb",
+    "oas",
+    "openapi",
+    "swagger",
     "typescript"
   ],
+  "license": "MIT",
+  "author": "stijnvanhulle",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/kubb-labs/kubb.git",
     "directory": "packages/adapter-oas"
   },
-  "license": "MIT",
-  "author": "stijnvanhulle",
-  "sideEffects": false,
+  "files": [
+    "src",
+    "dist",
+    "!/**/**.test.**",
+    "!/**/__tests__/**",
+    "!/**/__snapshots__/**"
+  ],
   "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "import": "./dist/index.js",
@@ -27,46 +37,33 @@
     },
     "./package.json": "./package.json"
   },
-  "types": "./dist/index.d.ts",
-  "files": [
-    "src",
-    "dist",
-    "!/**/**.test.**",
-    "!/**/__tests__/**",
-    "!/**/__snapshots__/**"
-  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
   "dependencies": {
-    "@kubb/fabric-core": "0.14.0",
-    "@redocly/openapi-core": "^2.24.0",
-    "@stoplight/yaml": "^4.3.0",
-    "fflate": "^0.8.2",
-    "jsonpointer": "^5.0.1",
-    "oas": "^31.1.2",
-    "oas-normalize": "^16.0.2",
-    "openapi-types": "^12.1.3",
-    "remeda": "^2.33.6",
+    "@redocly/openapi-core": "^2.30.3",
+    "oas": "^32.1.18",
+    "oas-normalize": "^16.0.4",
     "swagger2openapi": "^7.0.8",
-    "@kubb/ast": "5.0.0-alpha.9",
-    "@kubb/core": "5.0.0-alpha.9"
+    "@kubb/core": "5.0.0-beta.2"
   },
   "devDependencies": {
     "@types/swagger2openapi": "^7.0.4",
+    "openapi-types": "^12.1.3",
     "@internals/utils": "0.0.0"
   },
   "engines": {
     "node": ">=22"
   },
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
+  "inlinedDependencies": {
+    "openapi-types": "12.1.3"
   },
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
   "scripts": {
     "build": "tsdown",
     "clean": "npx rimraf ./dist",
-    "lint": "bun biome lint .",
-    "lint:fix": "bun biome lint --fix --unsafe .",
+    "lint": "oxlint .",
+    "lint:fix": "oxlint --fix .",
     "release": "pnpm publish --no-git-check",
     "release:canary": "bash ../../.github/canary.sh && node ../../scripts/build.js canary && pnpm publish --no-git-check",
     "start": "tsdown --watch",

package/src/adapter.ts

@@ -1,122 +1,126 @@
-import path from 'node:path'
-import { createRoot } from '@kubb/ast'
-import type { AdapterSource } from '@kubb/core'
-import { createAdapter } from '@kubb/core'
-import { resolveServerUrl } from './oas/resolveServerUrl.ts'
-import { parseFromConfig } from './oas/utils.ts'
-import { createOasParser } from './parser.ts'
-import type { OasAdapter } from './types.ts'
-import { getImports } from './utils.ts'
+import { ast, createAdapter } from '@kubb/core'
+import { DEFAULT_PARSER_OPTIONS } from './constants.ts'
+import { applyDiscriminatorInheritance } from './discriminator.ts'
+import { parseFromConfig, validateDocument } from './factory.ts'
+import { parseOas } from './parser.ts'
+import { resolveServerUrl } from './resolvers.ts'
+import type { AdapterOas, Document } from './types.ts'
 
-export const adapterOasName = 'oas' satisfies OasAdapter['name']
+/**
+ * Stable string identifier for the OAS adapter used in Kubb's adapter registry.
+ */
+export const adapterOasName = 'oas' satisfies AdapterOas['name']
 
 /**
- * Creates an OpenAPI / Swagger adapter for Kubb.
+ * Creates the default OpenAPI / Swagger adapter for Kubb.
  *
- * This is the default adapter — you can omit it from your config when using
- * an OpenAPI spec, but supplying it explicitly lets you pass options.
+ * Parses the spec, optionally validates it, resolves the base URL, and converts
+ * everything into an `InputNode` that downstream plugins consume.
  *
  * @example
  * ```ts
- * import { defineConfig } from '@kubb/core'
+ * import { defineConfig } from 'kubb'
  * import { adapterOas } from '@kubb/adapter-oas'
+ * import { pluginTs } from '@kubb/plugin-ts'
  *
  * export default defineConfig({
- *   adapter: adapterOas({ validate: true, dateType: 'date' }),
- *   input:   { path: './openapi.yaml' },
- *   plugins: [pluginTs(), pluginZod()],
+ *   adapter: adapterOas({ dateType: 'date', serverIndex: 0 }),
+ *   input: { path: './openapi.yaml' },
+ *   plugins: [pluginTs()],
  * })
  * ```
  */
-export const adapterOas = createAdapter<OasAdapter>((options) => {
+export const adapterOas = createAdapter<AdapterOas>((options) => {
   const {
     validate = true,
-    oasClass,
     contentType,
     serverIndex,
     serverVariables,
     discriminator = 'strict',
-    collisionDetection = false,
-    dateType = 'string',
-    integerType = 'number',
-    unknownType = 'any',
-    emptySchemaType = unknownType,
+    dateType = DEFAULT_PARSER_OPTIONS.dateType,
+    integerType = DEFAULT_PARSER_OPTIONS.integerType,
+    unknownType = DEFAULT_PARSER_OPTIONS.unknownType,
+    enumSuffix = DEFAULT_PARSER_OPTIONS.enumSuffix,
+    emptySchemaType = unknownType || DEFAULT_PARSER_OPTIONS.emptySchemaType,
   } = options
 
-  // Mutable Map shared between `options` and each `parse()` call.
-  // Populated (and replaced) on every parse so consumers always see the latest state.
-  const nameMapping = new Map<string, string>()
+  // Let-binding so parse() can replace it with a simple reassignment (no clear+loop).
+  let nameMapping = new Map<string, string>()
+  let parsedDocument: Document | null
+  let inputNode: ast.InputNode | null
 
   return {
     name: adapterOasName,
-    options: {
-      validate,
-      oasClass,
-      contentType,
-      serverIndex,
-      serverVariables,
-      discriminator,
-      collisionDetection,
-      dateType,
-      integerType,
-      unknownType,
-      emptySchemaType,
-      nameMapping,
+    get options() {
+      return {
+        validate,
+        contentType,
+        serverIndex,
+        serverVariables,
+        discriminator,
+        dateType,
+        integerType,
+        unknownType,
+        emptySchemaType,
+        enumSuffix,
+        nameMapping,
+      }
+    },
+    get document() {
+      return parsedDocument
+    },
+    get inputNode() {
+      return inputNode
     },
     getImports(node, resolve) {
-      return getImports({ node, nameMapping, resolve })
+      return ast.collectImports({
+        node,
+        nameMapping,
+        resolve: (schemaName) => {
+          const result = resolve(schemaName)
+          if (!result) return
+
+          return ast.createImport({ name: [result.name], path: result.path })
+        },
+      })
     },
     async parse(source) {
-      const fakeConfig = sourceToFakeConfig(source)
-      const oas = await parseFromConfig(fakeConfig, oasClass)
-
-      oas.setOptions({ contentType, discriminator, collisionDetection })
+      const document = await parseFromConfig(source)
 
       if (validate) {
-        try {
-          await oas.validate()
-        } catch (_err) {
-          // Validation failures are non-fatal — mirror plugin-oas behavior
-        }
+        await validateDocument(document)
       }
 
-      const server = serverIndex !== undefined ? oas.api.servers?.at(serverIndex) : undefined
+      const server = serverIndex !== undefined ? document.servers?.at(serverIndex) : undefined
       const baseURL = server?.url ? resolveServerUrl(server, serverVariables) : undefined
 
-      const parser = createOasParser(oas, { contentType, collisionDetection })
+      const { root: parsedRoot, nameMapping: parsedNameMapping } = parseOas(document, {
+        contentType,
+        dateType,
+        integerType,
+        unknownType,
+        emptySchemaType,
+        enumSuffix,
+      })
 
-      // Sync the adapter's shared nameMapping with the one computed by the parser.
-      nameMapping.clear()
-      for (const [key, value] of parser.nameMapping) {
-        nameMapping.set(key, value)
-      }
+      const node = discriminator === 'inherit' ? applyDiscriminatorInheritance(parsedRoot) : parsedRoot
 
-      const root = parser.parse({ dateType, integerType, unknownType, emptySchemaType })
+      // This must happen after parseOas() because legacy enum remapping is finalized there.
+      nameMapping = parsedNameMapping
+      // Expose the raw document so consumers (e.g. plugin-redoc) can access it.
+      parsedDocument = document
 
-      return createRoot({
-        ...root,
+      inputNode = ast.createInput({
+        ...node,
         meta: {
-          title: oas.api.info?.title,
-          description: oas.api.info?.description,
-          version: oas.api.info?.version,
+          title: document.info?.title,
+          description: document.info?.description,
+          version: document.info?.version,
           baseURL,
         },
       })
+
+      return inputNode
     },
   }
 })
-
-// TODO: remove once parseFromConfig accepts AdapterSource directly
-function sourceToFakeConfig(source: AdapterSource): Parameters<typeof parseFromConfig>[0] {
-  switch (source.type) {
-    case 'path':
-      return { root: path.dirname(source.path), input: { path: source.path } } as Parameters<typeof parseFromConfig>[0]
-    case 'data':
-      return { root: process.cwd(), input: { data: source.data } } as Parameters<typeof parseFromConfig>[0]
-    case 'paths':
-      return {
-        root: source.paths[0] ? path.dirname(source.paths[0]) : process.cwd(),
-        input: source.paths.map((p) => ({ path: p })),
-      } as Parameters<typeof parseFromConfig>[0]
-  }
-}

package/src/constants.ts

@@ -1,41 +1,83 @@
-import type { SchemaType } from '@kubb/ast/types'
-import type { HttpMethods as OASHttpMethods } from 'oas/types'
+import { ast } from '@kubb/core'
 
-// ─── Merge defaults ────────────────────────────────────────────────────────────
+/**
+ * Default parser options applied when no explicit options are provided.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_PARSER_OPTIONS } from '@kubb/adapter-oas'
+ *
+ * const parser = createOasParser(oas)
+ * const root = parser.parse({ ...DEFAULT_PARSER_OPTIONS, dateType: 'date' })
+ * ```
+ */
+export const DEFAULT_PARSER_OPTIONS = {
+  dateType: 'string',
+  integerType: 'bigint',
+  unknownType: 'any',
+  emptySchemaType: 'any',
+  enumSuffix: 'enum',
+} as const satisfies ast.ParserOptions
+
+/**
+ * JSON-Pointer prefix for schemas declared under `components.schemas` in an OpenAPI document.
+ *
+ * Used when building or parsing `$ref` strings.
+ *
+ * @example
+ * ```ts
+ * `${SCHEMA_REF_PREFIX}Pet` // '#/components/schemas/Pet'
+ * ```
+ */
+export const SCHEMA_REF_PREFIX = '#/components/schemas/' as const
 
 /**
- * OpenAPI version string written into merged document stubs.
+ * OpenAPI version string written into the stub document created during multi-spec merges.
  */
 export const MERGE_OPENAPI_VERSION = '3.0.0' as const
 
 /**
- * Fallback `info.title` used when merging multiple API documents.
+ * Fallback `info.title` placed in the stub document when merging multiple API files.
  */
 export const MERGE_DEFAULT_TITLE = 'Merged API' as const
 
 /**
- * Fallback `info.version` used when merging multiple API documents.
+ * Fallback `info.version` placed in the stub document when merging multiple API files.
  */
 export const MERGE_DEFAULT_VERSION = '1.0.0' as const
 
-// ─── Schema analysis ───────────────────────────────────────────────────────────
-
 /**
- * JSON Schema keywords that indicate structural composition.
- * A schema fragment containing any of these keys must not be inlined into its
- * parent during `allOf` flattening — it carries semantic meaning of its own.
+ * Set of JSON Schema keywords that prevent a schema fragment from being inlined during `allOf` flattening.
+ *
+ * A fragment that contains any of these keys carries structural meaning of its own and must stay as a separate
+ * intersection member rather than being merged into the parent.
+ *
+ * @example
+ * ```ts
+ * import { structuralKeys } from '@kubb/adapter-oas'
+ *
+ * const isStructural = Object.keys(fragment).some((key) => structuralKeys.has(key))
+ * // true when fragment has e.g. 'properties' or 'oneOf'
+ * ```
  */
 export const structuralKeys = new Set(['properties', 'items', 'additionalProperties', 'oneOf', 'anyOf', 'allOf', 'not'] as const)
 
 /**
- * Maps OAS/JSON Schema `format` strings to their Kubb `SchemaType` equivalents.
+ * Static map from OAS `format` strings to Kubb `SchemaType` values.
+ *
+ * Only formats whose AST type differs from the OAS `type` field appear here.
+ * Formats that depend on runtime options (`int64`, `date-time`, `date`, `time`) are handled separately
+ * in the parser. `ipv4` and `ipv6` map to their own dedicated schema types; `hostname` and
+ * `idn-hostname` map to `'url'` as the closest generic string-format type.
  *
- * Only formats that need a type different from the raw OAS `type` are listed.
- * `int64`, `date-time`, `date`, and `time` are handled separately because their
- * mapping depends on runtime parser options.
+ * @example
+ * ```ts
+ * import { formatMap } from '@kubb/adapter-oas'
  *
- * Note: `ipv4`, `ipv6`, and `hostname` map to `'url'` — the closest supported
- * scalar type in the Kubb AST, even though these are not strictly URLs.
+ * formatMap['uuid']   // 'uuid'
+ * formatMap['binary'] // 'blob'
+ * formatMap['float']  // 'number'
+ * ```
  */
 export const formatMap = {
   uuid: 'uuid',
@@ -44,8 +86,8 @@ export const formatMap = {
   uri: 'url',
   'uri-reference': 'url',
   url: 'url',
-  ipv4: 'url',
-  ipv6: 'url',
+  ipv4: 'ipv4',
+  ipv6: 'ipv6',
   hostname: 'url',
   'idn-hostname': 'url',
   binary: 'blob',
@@ -55,60 +97,26 @@ export const formatMap = {
   int32: 'integer',
   float: 'number',
   double: 'number',
-} as const satisfies Record<string, SchemaType>
-
-/**
- * Exhaustive list of media types that Kubb recognizes.
- */
-export const knownMediaTypes = new Set([
-  'application/json',
-  'application/xml',
-  'application/x-www-form-urlencoded',
-  'application/octet-stream',
-  'application/pdf',
-  'application/zip',
-  'application/graphql',
-  'multipart/form-data',
-  'text/plain',
-  'text/html',
-  'text/csv',
-  'text/xml',
-  'image/png',
-  'image/jpeg',
-  'image/gif',
-  'image/webp',
-  'image/svg+xml',
-  'audio/mpeg',
-  'video/mp4',
-] as const)
+} as const satisfies Record<string, ast.SchemaType>
 
 /**
- * Vendor extension keys used to attach human-readable labels to enum values.
- * Checked in priority order: the first key found wins.
+ * Vendor extension keys that attach human-readable labels to enum values, checked in priority order.
+ *
+ * @example
+ * ```ts
+ * import { enumExtensionKeys } from '@kubb/adapter-oas'
+ *
+ * const key = enumExtensionKeys.find((k) => k in schema) // 'x-enumNames' | 'x-enum-varnames' | undefined
+ * ```
  */
 export const enumExtensionKeys = ['x-enumNames', 'x-enum-varnames'] as const
 
 /**
- * Scalar primitive schema types used for union member simplification.
- */
-export const SCALAR_PRIMITIVE_TYPES = new Set(['string', 'number', 'integer', 'bigint', 'boolean'] as const)
-
-// ─── HTTP ──────────────────────────────────────────────────────────────────────
-
-/**
- * Canonical HTTP method names for the Kubb OAS layer.
- * Keys are uppercase (used in generated code); values are the lowercase strings
- * that the `oas` library uses internally.
- *
- * TODO(v5): remove — use `httpMethods` from `@kubb/ast`
+ * Maps `'any' | 'unknown' | 'void'` option strings to their `ScalarSchemaType` constant.
+ * Replaces a plain object lookup with a `Map` for explicit key membership testing via `.has()`.
  */
-export const httpMethods = {
-  GET: 'get',
-  POST: 'post',
-  PUT: 'put',
-  PATCH: 'patch',
-  DELETE: 'delete',
-  HEAD: 'head',
-  OPTIONS: 'options',
-  TRACE: 'trace',
-} as const satisfies Record<Uppercase<OASHttpMethods>, OASHttpMethods>
+export const typeOptionMap = new Map<'any' | 'unknown' | 'void', ast.ScalarSchemaType>([
+  ['any', ast.schemaTypes.any],
+  ['unknown', ast.schemaTypes.unknown],
+  ['void', ast.schemaTypes.void],
+])

package/src/discriminator.ts

@@ -0,0 +1,108 @@
+import { ast } from '@kubb/core'
+
+type DiscriminatorTarget = {
+  propertyName: string
+  enumValues: Array<string | number | boolean>
+}
+
+/**
+ * Injects discriminator enum values into child schemas so they know which value identifies them.
+ *
+ * Finds every union schema in `input.schemas` that has a `discriminatorPropertyName`, collects the
+ * enum value each union member is mapped to, then adds (or replaces) that property on the matching
+ * child object schema.
+ *
+ * Returns a new `InputNode` — the original is never mutated.
+ *
+ * @example
+ * ```ts
+ * const { root } = parseOas(document, options)
+ * const next = applyDiscriminatorInheritance(root)
+ * ```
+ */
+export function applyDiscriminatorInheritance(root: ast.InputNode): ast.InputNode {
+  const childMap = new Map<string, DiscriminatorTarget>()
+
+  for (const schema of root.schemas) {
+    // Case 1: top-level schema is a union (oneOf/anyOf with discriminator)
+    // Case 2: top-level schema is an intersection wrapping a union (oneOf/anyOf + shared properties)
+    let unionNode = ast.narrowSchema(schema, 'union')
+
+    if (!unionNode) {
+      const intersectionMembers = ast.narrowSchema(schema, 'intersection')?.members
+      if (intersectionMembers) {
+        for (const m of intersectionMembers) {
+          const u = ast.narrowSchema(m, 'union')
+          if (u) {
+            unionNode = u
+            break
+          }
+        }
+      }
+    }
+
+    if (!unionNode?.discriminatorPropertyName || !unionNode.members) continue
+
+    const { discriminatorPropertyName, members } = unionNode
+
+    for (const member of members) {
+      // Members with a discriminant value are intersections: [RefSchemaNode, ObjectSchemaNode]
+      const intersectionNode = ast.narrowSchema(member, 'intersection')
+      if (!intersectionNode?.members) continue
+
+      let refNode: ReturnType<typeof ast.narrowSchema<'ref'>> | undefined
+      let objNode: ReturnType<typeof ast.narrowSchema<'object'>> | undefined
+
+      for (const m of intersectionNode.members) {
+        refNode ??= ast.narrowSchema(m, 'ref')
+        objNode ??= ast.narrowSchema(m, 'object')
+      }
+
+      if (!refNode?.name || !objNode) continue
+
+      const prop = objNode.properties.find((p) => p.name === discriminatorPropertyName)
+      const enumNode = prop ? ast.narrowSchema(prop.schema, 'enum') : undefined
+      if (!enumNode?.enumValues?.length) continue
+
+      const enumValues = enumNode.enumValues.filter((v): v is string | number | boolean => v !== null)
+      if (!enumValues.length) continue
+
+      const existing = childMap.get(refNode.name)
+      if (existing) {
+        existing.enumValues.push(...enumValues)
+      } else {
+        childMap.set(refNode.name, {
+          propertyName: discriminatorPropertyName,
+          enumValues: [...enumValues],
+        })
+      }
+    }
+  }
+
+  if (childMap.size === 0) return root
+
+  return ast.transform(root, {
+    schema(node, { parent }) {
+      if (parent?.kind !== 'Input' || !node.name) return
+
+      const entry = childMap.get(node.name)
+      if (!entry) return
+
+      const objectNode = ast.narrowSchema(node, 'object')
+      if (!objectNode) return
+
+      const { propertyName, enumValues } = entry
+      const enumSchema = ast.createSchema({ type: 'enum', enumValues })
+      const newProp = ast.createProperty({
+        name: propertyName,
+        required: true,
+        schema: enumSchema,
+      })
+
+      const existingIdx = objectNode.properties.findIndex((p) => p.name === propertyName)
+      const newProperties = existingIdx >= 0 ? objectNode.properties.map((p, i) => (i === existingIdx ? newProp : p)) : [...objectNode.properties, newProp]
+
+      return { ...objectNode, properties: newProperties }
+    },
+  })
+}