@kubb/adapter-oas 5.0.0-alpha.3 → 5.0.0-alpha.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/adapter-oas",
-  "version": "5.0.0-alpha.3",
+  "version": "5.0.0-alpha.30",
   "description": "OpenAPI / Swagger adapter for Kubb — converts OAS input into a @kubb/ast RootNode.",
   "keywords": [
     "openapi",
@@ -36,18 +36,18 @@
     "!/**/__snapshots__/**"
   ],
   "dependencies": {
-    "@kubb/fabric-core": "0.13.3",
-    "@redocly/openapi-core": "^2.22.1",
+    "@kubb/fabric-core": "0.15.1",
+    "@redocly/openapi-core": "^2.25.4",
     "@stoplight/yaml": "^4.3.0",
     "fflate": "^0.8.2",
     "jsonpointer": "^5.0.1",
     "oas": "^31.1.2",
-    "oas-normalize": "^16.0.2",
+    "oas-normalize": "^16.0.4",
     "openapi-types": "^12.1.3",
-    "remeda": "^2.33.6",
+    "remeda": "^2.33.7",
     "swagger2openapi": "^7.0.8",
-    "@kubb/ast": "5.0.0-alpha.3",
-    "@kubb/core": "5.0.0-alpha.3"
+    "@kubb/ast": "5.0.0-alpha.30",
+    "@kubb/core": "5.0.0-alpha.30"
   },
   "devDependencies": {
     "@types/swagger2openapi": "^7.0.4",

package/src/adapter.ts

@@ -1,121 +1,128 @@
-import path from 'node:path'
-import { createRoot } from '@kubb/ast'
-import type { AdapterSource } from '@kubb/core'
-import { defineAdapter } 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 { collectImports, createRoot } from '@kubb/ast'
+import type { RootNode } from '@kubb/ast/types'
+import { 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 a `RootNode` that downstream plugins consume.
  *
  * @example
  * ```ts
  * import { defineConfig } from '@kubb/core'
  * 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 = defineAdapter<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 rootNode: RootNode | 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 rootNode() {
+      return rootNode
     },
     getImports(node, resolve) {
-      return getImports({ node, nameMapping, resolve })
+      return collectImports({
+        node,
+        nameMapping,
+        resolve: (schemaName) => {
+          const result = resolve(schemaName)
+          if (!result) return
+
+          return { 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,
+      rootNode = createRoot({
+        ...node,
         meta: {
-          title: oas.api.info?.title,
-          version: oas.api.info?.version,
+          title: document.info?.title,
+          description: document.info?.description,
+          version: document.info?.version,
           baseURL,
         },
       })
+
+      return rootNode
     },
   }
 })
-
-// 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,72 @@
-import type { MediaType, SchemaType } from '@kubb/ast/types'
-import type { HttpMethods as OASHttpMethods } from 'oas/types'
+import { schemaTypes } from '@kubb/ast'
+import type { ParserOptions, ScalarSchemaType, SchemaType } from '@kubb/ast/types'
 
-// ─── 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: 'number',
+  unknownType: 'any',
+  emptySchemaType: 'any',
+  enumSuffix: 'enum',
+} as const satisfies ParserOptions
 
 /**
- * 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<string>(['properties', 'items', 'additionalProperties', 'oneOf', 'anyOf', 'allOf', 'not'])
+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 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.
+ * 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.
  *
- * Note: `ipv4`, `ipv6`, and `hostname` map to `'url'` — the closest supported
- * scalar type in the Kubb AST, even though these are not strictly URLs.
+ * @example
+ * ```ts
+ * import { formatMap } from '@kubb/adapter-oas'
+ *
+ * formatMap['uuid']   // 'uuid'
+ * formatMap['binary'] // 'blob'
+ * formatMap['float']  // 'number'
+ * ```
  */
 export const formatMap = {
   uuid: 'uuid',
@@ -44,8 +75,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',
@@ -58,53 +89,23 @@ export const formatMap = {
 } as const satisfies Record<string, SchemaType>
 
 /**
- * Exhaustive list of media types that Kubb recognizes.
- * Kept as a module-level constant to avoid re-allocating the array on every call.
- */
-export const knownMediaTypes = [
-  '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 satisfies ReadonlyArray<MediaType>
-
-/**
- * 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
 
-// ─── 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', ScalarSchemaType>([
+  ['any', schemaTypes.any],
+  ['unknown', schemaTypes.unknown],
+  ['void', schemaTypes.void],
+])

package/src/discriminator.ts

@@ -0,0 +1,99 @@
+import { createProperty, createSchema, narrowSchema, transform } from '@kubb/ast'
+import type { RootNode } from '@kubb/ast/types'
+
+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 `root.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 `RootNode` — the original is never mutated.
+ *
+ * @example
+ * ```ts
+ * const { root } = parseOas(document, options)
+ * const next = applyDiscriminatorInheritance(root)
+ * ```
+ */
+export function applyDiscriminatorInheritance(root: RootNode): RootNode {
+  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 = narrowSchema(schema, 'union')
+
+    if (!unionNode) {
+      const intersectionMembers = narrowSchema(schema, 'intersection')?.members
+      if (intersectionMembers) {
+        for (const m of intersectionMembers) {
+          const u = 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 = narrowSchema(member, 'intersection')
+      if (!intersectionNode?.members) continue
+
+      let refNode: ReturnType<typeof narrowSchema<'ref'>> | undefined
+      let objNode: ReturnType<typeof narrowSchema<'object'>> | undefined
+
+      for (const m of intersectionNode.members) {
+        refNode ??= narrowSchema(m, 'ref')
+        objNode ??= narrowSchema(m, 'object')
+      }
+
+      if (!refNode?.name || !objNode) continue
+
+      const prop = objNode.properties.find((p) => p.name === discriminatorPropertyName)
+      const enumNode = prop ? 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 transform(root, {
+    schema(node, { parent }) {
+      if (parent?.kind !== 'Root' || !node.name) return
+
+      const entry = childMap.get(node.name)
+      if (!entry) return
+
+      const objectNode = narrowSchema(node, 'object')
+      if (!objectNode) return
+
+      const { propertyName, enumValues } = entry
+      const enumSchema = createSchema({ type: 'enum', enumValues })
+      const newProp = 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 }
+    },
+  })
+}

package/src/factory.ts

@@ -0,0 +1,154 @@
+import path from 'node:path'
+import { URLPath } from '@internals/utils'
+import type { AdapterSource } from '@kubb/core'
+import { bundle, loadConfig } from '@redocly/openapi-core'
+import yaml from '@stoplight/yaml'
+import OASNormalize from 'oas-normalize'
+import { mergeDeep } from 'remeda'
+import swagger2openapi from 'swagger2openapi'
+import { MERGE_DEFAULT_TITLE, MERGE_DEFAULT_VERSION, MERGE_OPENAPI_VERSION } from './constants.ts'
+import { isOpenApiV2Document } from './guards.ts'
+import type { Document } from './types.ts'
+
+export type ParseOptions = {
+  canBundle?: boolean
+  enablePaths?: boolean
+}
+
+/**
+ * Loads and dereferences an OpenAPI document, returning the raw `Document`.
+ *
+ * Accepts a file path string or an already-parsed document object. File paths are bundled via
+ * Redocly to resolve external `$ref`s. Swagger 2.0 documents are automatically up-converted
+ * to OpenAPI 3.0 via `swagger2openapi`.
+ *
+ * @example
+ * ```ts
+ * const document = await parseDocument('./openapi.yaml')
+ * const document = await parse(rawDocumentObject, { canBundle: false })
+ * ```
+ */
+export async function parseDocument(pathOrApi: string | Document, { canBundle = true, enablePaths = true }: ParseOptions = {}): Promise<Document> {
+  if (typeof pathOrApi === 'string' && canBundle) {
+    const config = await loadConfig()
+    const bundleResults = await bundle({ ref: pathOrApi, config, base: pathOrApi })
+
+    return parseDocument(bundleResults.bundle.parsed as string, { canBundle, enablePaths })
+  }
+
+  const oasNormalize = new OASNormalize(pathOrApi, {
+    enablePaths,
+    colorizeErrors: true,
+  })
+  const document = (await oasNormalize.load()) as Document
+
+  if (isOpenApiV2Document(document)) {
+    const { openapi } = await swagger2openapi.convertObj(document, {
+      anchors: true,
+    })
+
+    return openapi as Document
+  }
+
+  return document
+}
+
+/**
+ * Deep-merges multiple OpenAPI documents into a single `Document`.
+ *
+ * Each document is parsed independently then recursively merged with `remeda`'s `mergeDeep`.
+ * Throws when the input array is empty.
+ *
+ * @example
+ * ```ts
+ * const document = await mergeDocuments(['./pets.yaml', './orders.yaml'])
+ * ```
+ */
+export async function mergeDocuments(pathOrApi: Array<string | Document>): Promise<Document> {
+  const documents: Document[] = []
+  for (const p of pathOrApi) {
+    documents.push(await parseDocument(p, { enablePaths: false, canBundle: false }))
+  }
+
+  if (documents.length === 0) {
+    throw new Error('No OAS documents provided for merging.')
+  }
+
+  const seed: Document = {
+    openapi: MERGE_OPENAPI_VERSION,
+    info: { title: MERGE_DEFAULT_TITLE, version: MERGE_DEFAULT_VERSION },
+    paths: {},
+    components: { schemas: {} },
+  } as Document
+
+  const merged = documents.reduce((acc, current) => mergeDeep(acc, current as Document), seed)
+
+  return parseDocument(merged)
+}
+
+/**
+ * Creates a `Document` from an `AdapterSource`.
+ *
+ * Handles all three source types:
+ * - `{ type: 'path' }` — resolves and bundles a local file path or remote URL.
+ * - `{ type: 'paths' }` — merges multiple file paths into a single document.
+ * - `{ type: 'data' }` — parses an inline string (YAML/JSON) or raw object.
+ *
+ * @example
+ * ```ts
+ * const document = await parseFromConfig({ type: 'path', path: './openapi.yaml' })
+ * const document = await parseFromConfig({ type: 'data', data: '{"openapi":"3.0.0",...}' })
+ * ```
+ */
+export function parseFromConfig(source: AdapterSource): Promise<Document> {
+  if (source.type === 'data') {
+    if (typeof source.data === 'object') {
+      return parseDocument(structuredClone(source.data) as Document)
+    }
+
+    try {
+      const api: string = yaml.parse(source.data as string)
+      return parseDocument(api)
+    } catch {
+      return parseDocument(source.data as string)
+    }
+  }
+
+  if (source.type === 'paths') {
+    return mergeDocuments(source.paths)
+  }
+
+  // type === 'path'
+  if (new URLPath(source.path).isURL) {
+    return parseDocument(source.path)
+  }
+
+  return parseDocument(path.resolve(path.dirname(source.path), source.path))
+}
+
+/**
+ * Validates an OpenAPI document using `oas-normalize` with colorized error output.
+ *
+ * @example
+ * ```ts
+ * await validateDocument(document)
+ * ```
+ */
+export async function validateDocument(document: Document): Promise<void> {
+  try {
+    const oasNormalize = new OASNormalize(document, {
+      enablePaths: true,
+      colorizeErrors: true,
+    })
+
+    await oasNormalize.validate({
+      parser: {
+        validate: {
+          errors: { colorize: true },
+        },
+      },
+    })
+  } catch (_err) {
+    // Validation failures are non-fatal — mirror plugin-oas behavior
+  }
+}