@kubb/adapter-oas 5.0.0-beta.75 → 5.0.0-beta.76

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@kubb/adapter-oas",
-  "version": "5.0.0-beta.75",
-  "description": "OpenAPI / Swagger adapter for Kubb converts OAS input into a @kubb/ast RootNode.",
+  "version": "5.0.0-beta.76",
+  "description": "OpenAPI and Swagger adapter for Kubb. Parses and validates OAS 2.0/3.x specifications into a @kubb/ast RootNode for downstream code generation plugins.",
   "keywords": [
     "adapter",
     "codegen",
     "kubb",
+    "meta-framework",
     "oas",
     "openapi",
     "swagger",
@@ -19,7 +20,6 @@
     "directory": "packages/adapter-oas"
   },
   "files": [
-    "src",
     "dist",
     "!/**/**.test.**",
     "!/**/__tests__/**",
@@ -42,14 +42,15 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@redocly/openapi-core": "^2.30.3",
-    "oas": "^32.1.18",
-    "oas-normalize": "^16.0.4",
-    "swagger2openapi": "^7.0.8",
-    "@kubb/core": "5.0.0-beta.75"
+    "@readme/openapi-parser": "^6.1.3",
+    "@scalar/openapi-upgrader": "^0.2.9",
+    "api-ref-bundler": "0.5.1",
+    "yaml": "^2.9.0",
+    "@kubb/ast": "5.0.0-beta.76",
+    "@kubb/core": "5.0.0-beta.76"
   },
   "devDependencies": {
-    "@types/swagger2openapi": "^7.0.4",
+    "@types/json-schema": "^7.0.15",
     "openapi-types": "^12.1.3",
     "@internals/utils": "0.0.0"
   },
@@ -57,15 +58,18 @@
     "node": ">=22"
   },
   "inlinedDependencies": {
+    "@types/json-schema": "7.0.15",
     "openapi-types": "12.1.3"
   },
   "scripts": {
+    "bench": "vitest bench",
     "build": "tsdown",
-    "clean": "npx rimraf ./dist",
+    "clean": "node -e \"require('node:fs').rmSync('./dist', {recursive:true,force:true})\"",
     "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",
+    "release:stage": "pnpm stage publish --no-git-check",
     "start": "tsdown --watch",
     "test": "vitest --passWithNoTests",
     "typecheck": "tsc -p ./tsconfig.json --noEmit --emitDeclarationOnly false"

package/src/adapter.ts

@@ -1,126 +0,0 @@
-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'
-
-/**
- * Stable string identifier for the OAS adapter used in Kubb's adapter registry.
- */
-export const adapterOasName = 'oas' satisfies AdapterOas['name']
-
-/**
- * Creates the default OpenAPI / Swagger adapter for Kubb.
- *
- * 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'
- * import { adapterOas } from '@kubb/adapter-oas'
- * import { pluginTs } from '@kubb/plugin-ts'
- *
- * export default defineConfig({
- *   adapter: adapterOas({ dateType: 'date', serverIndex: 0 }),
- *   input: { path: './openapi.yaml' },
- *   plugins: [pluginTs()],
- * })
- * ```
- */
-export const adapterOas = createAdapter<AdapterOas>((options) => {
-  const {
-    validate = true,
-    contentType,
-    serverIndex,
-    serverVariables,
-    discriminator = 'strict',
-    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
-
-  // 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,
-    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 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 document = await parseFromConfig(source)
-
-      if (validate) {
-        await validateDocument(document)
-      }
-
-      const server = serverIndex !== undefined ? document.servers?.at(serverIndex) : undefined
-      const baseURL = server?.url ? resolveServerUrl(server, serverVariables) : undefined
-
-      const { root: parsedRoot, nameMapping: parsedNameMapping } = parseOas(document, {
-        contentType,
-        dateType,
-        integerType,
-        unknownType,
-        emptySchemaType,
-        enumSuffix,
-      })
-
-      const node = discriminator === 'inherit' ? applyDiscriminatorInheritance(parsedRoot) : parsedRoot
-
-      // 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
-
-      inputNode = ast.createInput({
-        ...node,
-        meta: {
-          title: document.info?.title,
-          description: document.info?.description,
-          version: document.info?.version,
-          baseURL,
-        },
-      })
-
-      return inputNode
-    },
-  }
-})

package/src/constants.ts

@@ -1,122 +0,0 @@
-import { ast } from '@kubb/core'
-
-/**
- * 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 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 the stub document created during multi-spec merges.
- */
-export const MERGE_OPENAPI_VERSION = '3.0.0' as const
-
-/**
- * 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` placed in the stub document when merging multiple API files.
- */
-export const MERGE_DEFAULT_VERSION = '1.0.0' as const
-
-/**
- * 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)
-
-/**
- * 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.
- *
- * @example
- * ```ts
- * import { formatMap } from '@kubb/adapter-oas'
- *
- * formatMap['uuid']   // 'uuid'
- * formatMap['binary'] // 'blob'
- * formatMap['float']  // 'number'
- * ```
- */
-export const formatMap = {
-  uuid: 'uuid',
-  email: 'email',
-  'idn-email': 'email',
-  uri: 'url',
-  'uri-reference': 'url',
-  url: 'url',
-  ipv4: 'ipv4',
-  ipv6: 'ipv6',
-  hostname: 'url',
-  'idn-hostname': 'url',
-  binary: 'blob',
-  byte: 'blob',
-  // Numeric formats override the OAS `type` because format is more specific.
-  // See https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-validation-00#rfc.section.7
-  int32: 'integer',
-  float: 'number',
-  double: 'number',
-} as const satisfies Record<string, ast.SchemaType>
-
-/**
- * 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', ast.ScalarSchemaType>([
-  ['any', ast.schemaTypes.any],
-  ['unknown', ast.schemaTypes.unknown],
-  ['void', ast.schemaTypes.void],
-])

package/src/discriminator.ts

@@ -1,108 +0,0 @@
-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 }
-    },
-  })
-}

package/src/factory.ts

@@ -1,165 +0,0 @@
-import path from 'node:path'
-import { mergeDeep, URLPath } from '@internals/utils'
-import type { AdapterSource } from '@kubb/core'
-import { bundle, loadConfig } from '@redocly/openapi-core'
-import OASNormalize from 'oas-normalize'
-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
-}
-
-export type ValidateDocumentOptions = {
-  throwOnError?: 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 via `mergeDeep` from `@internals/utils`.
- * 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 as Record<string, unknown>, current as Record<string, unknown>),
-    seed as Record<string, unknown>,
-  )
-
-  return parseDocument(merged as Document)
-}
-
-/**
- * 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)
-    }
-
-    return parseDocument(source.data as string, { canBundle: false })
-  }
-
-  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, { throwOnError = false }: ValidateDocumentOptions = {}): Promise<void> {
-  try {
-    const oasNormalize = new OASNormalize(document, {
-      enablePaths: true,
-      colorizeErrors: true,
-    })
-
-    await oasNormalize.validate({
-      parser: {
-        validate: {
-          errors: { colorize: true },
-        },
-      },
-    })
-  } catch (error) {
-    if (throwOnError) {
-      throw error
-    }
-
-    // Validation failures are non-fatal — mirror plugin-oas behavior
-  }
-}

package/src/guards.ts

@@ -1,68 +0,0 @@
-import { isPlainObject } from '@internals/utils'
-import type { OpenAPIV2, OpenAPIV3, OpenAPIV3_1 } from 'openapi-types'
-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'
-}

package/src/index.ts

@@ -1,18 +0,0 @@
-export { adapterOas, adapterOasName } from './adapter.ts'
-export type { ParseOptions, ValidateDocumentOptions } from './factory.ts'
-export { mergeDocuments, parseDocument, parseFromConfig, validateDocument } from './factory.ts'
-export type {
-  AdapterOas,
-  AdapterOasOptions,
-  AdapterOasResolvedOptions,
-  ContentType,
-  DiscriminatorObject,
-  Document,
-  HttpMethod,
-  MediaTypeObject,
-  Operation,
-  ReferenceObject,
-  ResponseObject,
-  SchemaObject,
-} from './types.ts'
-export { HttpMethods } from './types.ts'