@kubb/adapter-oas 5.0.0-alpha.17 → 5.0.0-alpha.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/adapter-oas",
-  "version": "5.0.0-alpha.17",
+  "version": "5.0.0-alpha.18",
   "description": "OpenAPI / Swagger adapter for Kubb — converts OAS input into a @kubb/ast RootNode.",
   "keywords": [
     "openapi",
@@ -36,8 +36,8 @@
     "!/**/__snapshots__/**"
   ],
   "dependencies": {
-    "@kubb/fabric-core": "0.14.0",
-    "@redocly/openapi-core": "^2.24.1",
+    "@kubb/fabric-core": "0.15.1",
+    "@redocly/openapi-core": "^2.25.1",
     "@stoplight/yaml": "^4.3.0",
     "fflate": "^0.8.2",
     "jsonpointer": "^5.0.1",
@@ -46,8 +46,8 @@
     "openapi-types": "^12.1.3",
     "remeda": "^2.33.6",
     "swagger2openapi": "^7.0.8",
-    "@kubb/ast": "5.0.0-alpha.17",
-    "@kubb/core": "5.0.0-alpha.17"
+    "@kubb/ast": "5.0.0-alpha.18",
+    "@kubb/core": "5.0.0-alpha.18"
   },
   "devDependencies": {
     "@types/swagger2openapi": "^7.0.4",

package/src/adapter.ts

@@ -1,37 +1,39 @@
-import path from 'node:path'
 import { collectImports, createRoot } from '@kubb/ast'
-import type { AdapterSource } from '@kubb/core'
 import { createAdapter } from '@kubb/core'
 import { DEFAULT_PARSER_OPTIONS } from './constants.ts'
-import { resolveServerUrl } from './oas/resolveServerUrl.ts'
-import { parseFromConfig } from './oas/utils.ts'
-import { createOasParser } from './parser.ts'
-import type { OasAdapter } from './types.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 } 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 = createAdapter<OasAdapter>((options) => {
+export const adapterOas = createAdapter<AdapterOas>((options) => {
   const {
     validate = true,
-    oasClass,
     contentType,
     serverIndex,
     serverVariables,
@@ -43,25 +45,25 @@ export const adapterOas = createAdapter<OasAdapter>((options) => {
     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>()
 
   return {
     name: adapterOasName,
-    options: {
-      validate,
-      oasClass,
-      contentType,
-      serverIndex,
-      serverVariables,
-      discriminator,
-      dateType,
-      integerType,
-      unknownType,
-      emptySchemaType,
-      enumSuffix,
-      nameMapping,
+    get options() {
+      return {
+        validate,
+        contentType,
+        serverIndex,
+        serverVariables,
+        discriminator,
+        dateType,
+        integerType,
+        unknownType,
+        emptySchemaType,
+        enumSuffix,
+        nameMapping,
+      }
     },
     getImports(node, resolve) {
       return collectImports({
@@ -70,60 +72,44 @@ export const adapterOas = createAdapter<OasAdapter>((options) => {
         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 })
+      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 })
-      const root = parser.parse({ dateType, integerType, unknownType, emptySchemaType, enumSuffix })
+      const { root: parsedRoot, nameMapping: parsedNameMapping } = parseOas(document, {
+        contentType,
+        dateType,
+        integerType,
+        unknownType,
+        emptySchemaType,
+        enumSuffix,
+      })
 
-      // This must happen after parse() because legacy enum remapping is finalized there.
-      nameMapping.clear()
-      for (const [key, value] of parser.nameMapping) {
-        nameMapping.set(key, value)
-      }
+      const root = discriminator === 'inherit' ? applyDiscriminatorInheritance(parsedRoot) : parsedRoot
+
+      // This must happen after parseOas() because legacy enum remapping is finalized there.
+      nameMapping = parsedNameMapping
 
       return createRoot({
         ...root,
         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,
         },
       })
     },
   }
 })
-
-// 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,7 +1,16 @@
-import type { ParserOptions, SchemaType } from '@kubb/ast/types'
+import { schemaTypes } from '@kubb/ast'
+import type { ParserOptions, ScalarSchemaType, SchemaType } from '@kubb/ast/types'
 
 /**
- * Default values for all `Options` fields.
+ * 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',
@@ -12,36 +21,51 @@ export const DEFAULT_PARSER_OPTIONS = {
 } 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
 
 /**
- * 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`, `ipv6`, and `hostname` map to `'url'` as the closest supported scalar.
  *
- * 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',
@@ -64,7 +88,23 @@ export const formatMap = {
 } as const satisfies Record<string, 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
+
+/**
+ * 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 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,151 @@
+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 = await Promise.all(pathOrApi.map((p) => 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
+  }
+}

package/src/guards.ts

@@ -0,0 +1,68 @@
+import type { OpenAPIV2, OpenAPIV3, OpenAPIV3_1 } from 'openapi-types'
+import { isPlainObject } from 'remeda'
+import type { DiscriminatorObject, SchemaObject } from './types.ts'
+
+/**
+ * Returns `true` when `doc` is a Swagger 2.0 document (no `openapi` key).
+ *
+ * @example
+ * ```ts
+ * if (isOpenApiV2Document(doc)) {
+ *   // doc is OpenAPIV2.Document
+ * }
+ * ```
+ */
+export function isOpenApiV2Document(doc: unknown): doc is OpenAPIV2.Document {
+  return !!doc && isPlainObject(doc) && !('openapi' in doc)
+}
+
+/**
+ * Returns `true` when a schema should be treated as nullable.
+ *
+ * Recognizes all nullable signals across OAS versions: `nullable: true` (OAS 3.0),
+ * `x-nullable: true` (vendor extension), `type: 'null'`, and `type: ['null', ...]` (OAS 3.1).
+ *
+ * @example
+ * ```ts
+ * isNullable({ type: 'string', nullable: true }) // true
+ * isNullable({ type: ['string', 'null'] })       // true
+ * isNullable({ type: 'string' })                 // false
+ * ```
+ */
+export function isNullable(schema?: SchemaObject & { 'x-nullable'?: boolean }): boolean {
+  const explicitNullable = schema?.nullable ?? schema?.['x-nullable']
+  if (explicitNullable === true) return true
+
+  const schemaType = schema?.type
+  if (schemaType === 'null') return true
+  if (Array.isArray(schemaType)) return schemaType.includes('null')
+
+  return false
+}
+
+/**
+ * Returns `true` when `obj` is an OpenAPI `$ref` pointer object.
+ *
+ * @example
+ * ```ts
+ * isReference({ $ref: '#/components/schemas/Pet' }) // true
+ * isReference({ type: 'string' })                   // false
+ * ```
+ */
+export function isReference(obj?: unknown): obj is OpenAPIV3.ReferenceObject | OpenAPIV3_1.ReferenceObject {
+  return !!obj && typeof obj === 'object' && '$ref' in obj
+}
+
+/**
+ * Returns `true` when `obj` is a schema with a structured OAS 3.x `discriminator` object.
+ *
+ * @example
+ * ```ts
+ * isDiscriminator({ discriminator: { propertyName: 'type', mapping: {} } }) // true
+ * isDiscriminator({ discriminator: 'type' })                                 // false (Swagger 2 string form)
+ * ```
+ */
+export function isDiscriminator(obj?: unknown): obj is SchemaObject & { discriminator: DiscriminatorObject } {
+  const record = obj as Record<string, unknown>
+  return !!obj && !!record['discriminator'] && typeof record['discriminator'] !== 'string'
+}