@kubb/adapter-oas 5.0.0-beta.6 → 5.0.0-beta.61

package/src/discriminator.ts

@@ -1,29 +1,22 @@
 import { ast } from '@kubb/core'
+import type { SchemaNodeByType } from '@kubb/ast'
 
-type DiscriminatorTarget = {
+export type DiscriminatorTarget = {
   propertyName: string
   enumValues: Array<string | number | boolean>
 }
 
 /**
- * Injects discriminator enum values into child schemas so they know which value identifies them.
+ * Builds a map of child schema names → discriminator patch data by scanning the given
+ * top-level AST schema nodes for union schemas that carry a `discriminatorPropertyName`.
  *
- * 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)
- * ```
+ * The streaming path calls this on a small pre-parsed subset of schemas (only the
+ * discriminator parents) rather than on all schemas at once.
  */
-export function applyDiscriminatorInheritance(root: ast.InputNode): ast.InputNode {
+export function buildDiscriminatorChildMap(schemas: Array<ast.SchemaNode>): Map<string, DiscriminatorTarget> {
   const childMap = new Map<string, DiscriminatorTarget>()
 
-  for (const schema of root.schemas) {
+  for (const schema of 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')
@@ -50,8 +43,8 @@ export function applyDiscriminatorInheritance(root: ast.InputNode): ast.InputNod
       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
+      let refNode: SchemaNodeByType['ref'] | null = null
+      let objNode: SchemaNodeByType['object'] | null = null
 
       for (const m of intersectionNode.members) {
         refNode ??= ast.narrowSchema(m, 'ref')
@@ -61,48 +54,79 @@ export function applyDiscriminatorInheritance(root: ast.InputNode): ast.InputNod
       if (!refNode?.name || !objNode) continue
 
       const prop = objNode.properties.find((p) => p.name === discriminatorPropertyName)
-      const enumNode = prop ? ast.narrowSchema(prop.schema, 'enum') : undefined
+      const enumNode = prop ? ast.narrowSchema(prop.schema, 'enum') : null
       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 (!existing) {
+        childMap.set(refNode.name, { propertyName: discriminatorPropertyName, enumValues: [...enumValues] })
+        continue
       }
+      existing.enumValues.push(...enumValues)
     }
   }
 
-  if (childMap.size === 0) return root
+  return childMap
+}
 
-  return ast.transform(root, {
-    schema(node, { parent }) {
-      if (parent?.kind !== 'Input' || !node.name) return
+/**
+ * Patches a single top-level `SchemaNode` with its discriminator entry (adds or replaces
+ * the discriminant property). Used by the streaming path to apply patches inline per yield
+ * without buffering all schemas.
+ */
+export function patchDiscriminatorNode(node: ast.SchemaNode, entry: { propertyName: string; enumValues: Array<string | number | boolean> }): ast.SchemaNode {
+  const objectNode = ast.narrowSchema(node, 'object')
+  if (!objectNode) return node
+
+  const { propertyName, enumValues } = entry
+  const enumSchema = ast.factory.createSchema({ type: 'enum', enumValues })
+  const newProp = ast.factory.createProperty({ name: propertyName, required: true, schema: enumSchema })
 
-      const entry = childMap.get(node.name)
-      if (!entry) return
+  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]
 
-      const objectNode = ast.narrowSchema(node, 'object')
-      if (!objectNode) return
+  return { ...objectNode, properties: newProperties }
+}
 
-      const { propertyName, enumValues } = entry
-      const enumSchema = ast.createSchema({ type: 'enum', enumValues })
-      const newProp = ast.createProperty({
+/**
+ * Creates a single-property object schema used as a discriminator literal.
+ *
+ * @example
+ * ```ts
+ * createDiscriminantNode({ propertyName: 'type', value: 'dog' })
+ * // -> { type: 'object', properties: [{ name: 'type', required: true, schema: enum('dog') }] }
+ * ```
+ */
+export function createDiscriminantNode({ propertyName, value }: { propertyName: string; value: string }): ast.SchemaNode {
+  return ast.factory.createSchema({
+    type: 'object',
+    primitive: 'object',
+    properties: [
+      ast.factory.createProperty({
         name: propertyName,
+        schema: ast.factory.createSchema({
+          type: 'enum',
+          primitive: 'string',
+          enumValues: [value],
+        }),
         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 }
-    },
+      }),
+    ],
   })
 }
+
+/**
+ * Returns the discriminator key whose mapping value matches `ref`, or `null` when there is no match.
+ *
+ * @example
+ * ```ts
+ * findDiscriminator({ dog: '#/components/schemas/Dog' }, '#/components/schemas/Dog') // 'dog'
+ * ```
+ */
+export function findDiscriminator(mapping: Record<string, string> | undefined, ref: string | undefined): string | null {
+  if (!mapping || !ref) return null
+  return Object.entries(mapping).find(([, value]) => value === ref)?.[0] ?? null
+}

package/src/factory.ts

@@ -1,16 +1,16 @@
 import path from 'node:path'
-import { mergeDeep, URLPath } from '@internals/utils'
+import { exists, mergeDeep, Url } from '@internals/utils'
+import { Diagnostics } from '@kubb/core'
 import type { AdapterSource } from '@kubb/core'
-import { bundle, loadConfig } from '@redocly/openapi-core'
-import OASNormalize from 'oas-normalize'
-import swagger2openapi from 'swagger2openapi'
+import { compileErrors, validate } from '@readme/openapi-parser'
+import { parse } from 'yaml'
+import { bundleDocument } from './bundler.ts'
 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 = {
@@ -20,9 +20,10 @@ export type ValidateDocumentOptions = {
 /**
  * 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`.
+ * Accepts a file path string or an already-parsed document object. File paths and URLs are
+ * bundled via `api-ref-bundler`, hoisting external file schemas into named `components.schemas`
+ * entries so generators can emit named types and imports. Swagger 2.0 documents are
+ * automatically up-converted to OpenAPI 3.0 via `swagger2openapi`.
  *
  * @example
  * ```ts
@@ -30,28 +31,19 @@ export type ValidateDocumentOptions = {
  * const document = await parse(rawDocumentObject, { canBundle: false })
  * ```
  */
-export async function parseDocument(pathOrApi: string | Document, { canBundle = true, enablePaths = true }: ParseOptions = {}): Promise<Document> {
+export async function parseDocument(pathOrApi: string | Document, { canBundle = true }: ParseOptions = {}): Promise<Document> {
   if (typeof pathOrApi === 'string' && canBundle) {
-    const config = await loadConfig()
-    const bundleResults = await bundle({
-      ref: pathOrApi,
-      config,
-      base: pathOrApi,
-    })
+    const bundled = await bundleDocument(pathOrApi)
 
-    return parseDocument(bundleResults.bundle.parsed as string, {
-      canBundle,
-      enablePaths,
-    })
+    return parseDocument(bundled, { canBundle: false })
   }
 
-  const oasNormalize = new OASNormalize(pathOrApi, {
-    enablePaths,
-    colorizeErrors: true,
-  })
-  const document = (await oasNormalize.load()) as Document
+  // A string here is always inline YAML/JSON content: file paths and URLs are read and parsed by
+  // `bundleDocument` first. `yaml.parse` also parses JSON, since JSON is a subset of YAML.
+  const document = (typeof pathOrApi === 'string' ? parse(pathOrApi) : pathOrApi) as Document
 
   if (isOpenApiV2Document(document)) {
+    const { default: swagger2openapi } = await import('swagger2openapi')
     const { openapi } = await swagger2openapi.convertObj(document, {
       anchors: true,
     })
@@ -65,7 +57,7 @@ export async function parseDocument(pathOrApi: string | Document, { canBundle =
 /**
  * Deep-merges multiple OpenAPI documents into a single `Document`.
  *
- * Each document is parsed independently then recursively merged via `mergeDeep` from `@internals/utils`.
+ * Each document is parsed independently, then deep-merged into one in array order.
  * Throws when the input array is empty.
  *
  * @example
@@ -74,13 +66,16 @@ export async function parseDocument(pathOrApi: string | Document, { canBundle =
  * ```
  */
 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 }))
-  }
+  const documents = await Promise.all(pathOrApi.map((p) => parseDocument(p, { canBundle: false })))
 
   if (documents.length === 0) {
-    throw new Error('No OAS documents provided for merging.')
+    throw new Diagnostics.Error({
+      code: Diagnostics.code.inputRequired,
+      severity: 'error',
+      message: 'No OAS documents were provided for merging.',
+      help: 'Pass at least one path or document to `input.path`.',
+      location: { kind: 'config' },
+    })
   }
 
   const seed: Document = {
@@ -102,9 +97,9 @@ export async function mergeDocuments(pathOrApi: Array<string | Document>): Promi
  * 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.
+ * - `{ 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
@@ -112,7 +107,7 @@ export async function mergeDocuments(pathOrApi: Array<string | Document>): Promi
  * const document = await parseFromConfig({ type: 'data', data: '{"openapi":"3.0.0",...}' })
  * ```
  */
-export function parseFromConfig(source: AdapterSource): Promise<Document> {
+export async function parseFromConfig(source: AdapterSource): Promise<Document> {
   if (source.type === 'data') {
     if (typeof source.data === 'object') {
       return parseDocument(structuredClone(source.data) as Document)
@@ -126,15 +121,37 @@ export function parseFromConfig(source: AdapterSource): Promise<Document> {
   }
 
   // type === 'path'
-  if (new URLPath(source.path).isURL) {
+  if (Url.canParse(source.path)) {
     return parseDocument(source.path)
   }
 
-  return parseDocument(path.resolve(path.dirname(source.path), source.path))
+  const resolved = path.resolve(path.dirname(source.path), source.path)
+  await assertInputExists(resolved)
+  return parseDocument(resolved)
 }
 
 /**
- * Validates an OpenAPI document using `oas-normalize` with colorized error output.
+ * Throws a coded `KUBB_INPUT_NOT_FOUND` diagnostic when a local input path does not exist.
+ * URLs are skipped, and a malformed but readable file is left for `parseDocument` to surface
+ * its parse error instead.
+ */
+export async function assertInputExists(input: string): Promise<void> {
+  if (Url.canParse(input)) {
+    return
+  }
+  if (!(await exists(input))) {
+    throw new Diagnostics.Error({
+      code: Diagnostics.code.inputNotFound,
+      severity: 'error',
+      message: `Cannot read the file set in \`input.path\` (or via \`kubb generate PATH\`): ${input}`,
+      help: 'Check that the path exists and is readable, then set it in `input.path` or pass it as `kubb generate PATH`.',
+      location: { kind: 'config' },
+    })
+  }
+}
+
+/**
+ * Validates an OpenAPI document using `@readme/openapi-parser` with colorized error output.
  *
  * @example
  * ```ts
@@ -143,23 +160,21 @@ export function parseFromConfig(source: AdapterSource): Promise<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 },
-        },
+    // `validate` dereferences its input in place, so clone to keep the cached document intact.
+    const result = await validate(structuredClone(document), {
+      validate: {
+        errors: { colorize: true },
       },
     })
+
+    if (!result.valid) {
+      throw new Error(compileErrors(result))
+    }
   } catch (error) {
     if (throwOnError) {
       throw error
     }
 
-    // Validation failures are non-fatal — mirror plugin-oas behavior
+    // Validation failures are non-fatal, mirror plugin-oas behavior
   }
 }

package/src/index.ts

@@ -1,6 +1,4 @@
 export { adapterOas, adapterOasName } from './adapter.ts'
-export type { ValidateDocumentOptions } from './factory.ts'
-export { mergeDocuments } from './factory.ts'
 export type {
   AdapterOas,
   AdapterOasOptions,
@@ -15,4 +13,3 @@ export type {
   ResponseObject,
   SchemaObject,
 } from './types.ts'
-export { HttpMethods } from './types.ts'

package/src/mime.ts

@@ -0,0 +1,22 @@
+/**
+ * MIME type fragments that mark a media type as JSON-like.
+ *
+ * Matches the substrings used by the `oas` library's `matchesMimeType.json`, so a content type is
+ * JSON when it contains any of these. The `+json` entry catches structured-syntax suffixes such as
+ * `application/vnd.api+json`.
+ */
+const jsonMimeFragments = ['application/json', 'application/x-json', 'text/json', 'text/x-json', '+json'] as const
+
+/**
+ * Returns `true` when a media type string is JSON-like.
+ *
+ * @example
+ * ```ts
+ * isJsonMimeType('application/json')         // true
+ * isJsonMimeType('application/vnd.api+json') // true
+ * isJsonMimeType('multipart/form-data')      // false
+ * ```
+ */
+export function isJsonMimeType(mimeType: string): boolean {
+  return jsonMimeFragments.some((fragment) => mimeType.includes(fragment))
+}

package/src/operation.ts

@@ -0,0 +1,194 @@
+import { SUPPORTED_METHODS } from './constants.ts'
+import { isReference } from './guards.ts'
+import { isJsonMimeType } from './mime.ts'
+import { resolveRef } from './refs.ts'
+import type { Document, MediaTypeObject, OperationObject, PathItemObject, ReferenceObject, RequestBodyObject, ResponseObject } from './types.ts'
+
+/**
+ * A single OpenAPI operation: its URL path, HTTP method, and the raw operation object.
+ *
+ * `schema` is a live reference into the document, so any in-place `$ref` resolution the resolvers
+ * perform is visible here too.
+ */
+export type Operation = {
+  path: string
+  method: string
+  schema: OperationObject
+}
+
+/**
+ * The document plus the operation being read. Shared by the request/response accessors so they can
+ * resolve `$ref`s against the document.
+ */
+type OperationContext = {
+  document: Document
+  operation: Operation
+}
+
+/**
+ * Slugifies a path for the `operationId` fallback: non-alphanumerics collapse to single dashes,
+ * with no leading or trailing dash.
+ */
+function slugify(value: string): string {
+  return value
+    .replace(/[^a-zA-Z0-9]/g, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/^-|-$/g, '')
+}
+
+/**
+ * Returns the operation's `operationId`, falling back to `<method>_<slugified-path>` when absent.
+ */
+export function getOperationId({ path, method, schema }: Operation): string {
+  const { operationId } = schema
+  if (typeof operationId === 'string' && operationId.length > 0) {
+    return operationId
+  }
+  return `${method}_${slugify(path).toLowerCase()}`
+}
+
+/**
+ * Returns the declared response status codes, skipping `x-` extensions and non-object entries.
+ */
+export function getResponseStatusCodes({ schema }: Operation): Array<string> {
+  const responses = schema.responses as Record<string, unknown> | undefined
+  if (!responses || isReference(responses)) {
+    return []
+  }
+  return Object.keys(responses).filter((key) => !key.startsWith('x-') && !!responses[key] && typeof responses[key] === 'object')
+}
+
+/**
+ * Returns the response object for a status code, resolving a `$ref` in place. `false` when absent.
+ */
+export function getResponseByStatusCode({ document, operation, statusCode }: OperationContext & { statusCode: string | number }): ResponseObject | false {
+  const responses = operation.schema.responses as Record<string, ResponseObject | ReferenceObject> | undefined
+  if (!responses || isReference(responses)) {
+    return false
+  }
+  const response = responses[statusCode]
+  if (!response) {
+    return false
+  }
+  if (isReference(response)) {
+    const resolved = resolveRef<ResponseObject>(document, response.$ref)
+    responses[statusCode] = resolved as ResponseObject
+    if (!resolved || isReference(resolved)) {
+      return false
+    }
+    return resolved
+  }
+  return response
+}
+
+/**
+ * Resolves the request body (dereferencing a `$ref` in place) and returns its content map, or
+ * `undefined` when the operation has no request body.
+ */
+function getRequestBodyContent({ document, operation }: OperationContext): Record<string, MediaTypeObject> | undefined {
+  const { schema } = operation
+  let requestBody = schema.requestBody as RequestBodyObject | ReferenceObject | undefined
+  if (!requestBody) {
+    return undefined
+  }
+  if (isReference(requestBody)) {
+    const resolved = resolveRef<RequestBodyObject>(document, requestBody.$ref)
+    ;(schema as { requestBody?: unknown }).requestBody = resolved
+    if (!resolved || isReference(resolved)) {
+      return undefined
+    }
+    requestBody = resolved
+  }
+  return requestBody.content
+}
+
+/**
+ * Returns the request body media type. With `mediaType` set, returns that entry or `false`.
+ * Otherwise picks the first JSON-like media type, then the first declared one, as a
+ * `[mediaType, object]` tuple.
+ */
+export function getRequestContent({
+  document,
+  operation,
+  mediaType,
+}: OperationContext & { mediaType?: string }): MediaTypeObject | false | [string, MediaTypeObject] {
+  const content = getRequestBodyContent({ document, operation })
+  if (!content) {
+    return false
+  }
+  if (mediaType) {
+    return mediaType in content ? content[mediaType]! : false
+  }
+  const mediaTypes = Object.keys(content)
+  const available = mediaTypes.find((mt) => isJsonMimeType(mt)) ?? mediaTypes[0]
+  return available ? [available, content[available]!] : false
+}
+
+/**
+ * Returns the primary request content type. Prefers a JSON-like media type (the last one wins,
+ * matching the previous behavior), then the first declared one, defaulting to `'application/json'`.
+ */
+export function getRequestContentType({ document, operation }: OperationContext): string {
+  const content = getRequestBodyContent({ document, operation })
+  const mediaTypes = content ? Object.keys(content) : []
+
+  let result = mediaTypes[0] ?? 'application/json'
+  for (const mt of mediaTypes) {
+    if (isJsonMimeType(mt)) {
+      result = mt
+    }
+  }
+  return result
+}
+
+/**
+ * Builds an `Operation` for every supported HTTP method on every path, in document order.
+ * `x-` path keys and unresolvable path-item `$ref`s are skipped.
+ *
+ * @example
+ * ```ts
+ * for (const operation of getOperations(document)) {
+ *   parseOperation(options, operation)
+ * }
+ * ```
+ */
+export function getOperations(document: Document): Array<Operation> {
+  const operations: Array<Operation> = []
+  const paths = document.paths
+  if (!paths) {
+    return operations
+  }
+
+  for (const path of Object.keys(paths)) {
+    if (path.startsWith('x-')) {
+      continue
+    }
+
+    let pathItem = paths[path] as PathItemObject | ReferenceObject | undefined
+    if (!pathItem) {
+      continue
+    }
+    if (isReference(pathItem)) {
+      const resolved = resolveRef<PathItemObject>(document, pathItem.$ref)
+      ;(paths as Record<string, unknown>)[path] = resolved
+      if (!resolved || isReference(resolved)) {
+        continue
+      }
+      pathItem = resolved
+    }
+
+    const item = pathItem as Record<string, unknown>
+    for (const method of Object.keys(item)) {
+      if (!SUPPORTED_METHODS.has(method)) {
+        continue
+      }
+      const schema = item[method]
+      if (!schema || typeof schema !== 'object') {
+        continue
+      }
+      operations.push({ path, method, schema: schema as OperationObject })
+    }
+  }
+
+  return operations
+}