@kubb/adapter-oas 5.0.0-alpha.42 → 5.0.0-alpha.44

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/adapter-oas",
-  "version": "5.0.0-alpha.42",
+  "version": "5.0.0-alpha.44",
   "description": "OpenAPI / Swagger adapter for Kubb converts OAS input into a @kubb/ast RootNode.",
   "keywords": [
     "openapi",
@@ -37,18 +37,14 @@
   ],
   "dependencies": {
     "@redocly/openapi-core": "^2.28.1",
-    "@stoplight/yaml": "^4.3.0",
-    "fflate": "^0.8.2",
-    "jsonpointer": "^5.0.1",
     "oas": "^31.1.2",
     "oas-normalize": "^16.0.4",
-    "openapi-types": "^12.1.3",
-    "remeda": "^2.33.7",
     "swagger2openapi": "^7.0.8",
-    "@kubb/core": "5.0.0-alpha.42"
+    "@kubb/core": "5.0.0-alpha.44"
   },
   "devDependencies": {
     "@types/swagger2openapi": "^7.0.4",
+    "openapi-types": "^12.1.3",
     "@internals/utils": "0.0.0"
   },
   "engines": {
@@ -60,6 +56,9 @@
   },
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
+  "inlinedDependencies": {
+    "openapi-types": "12.1.3"
+  },
   "scripts": {
     "build": "tsdown",
     "clean": "npx rimraf ./dist",

package/src/constants.ts

@@ -19,6 +19,18 @@ export const DEFAULT_PARSER_OPTIONS = {
   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.
  */

package/src/factory.ts

@@ -1,10 +1,8 @@
 import path from 'node:path'
-import { URLPath } from '@internals/utils'
+import { mergeDeep, 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'
@@ -60,7 +58,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 with `remeda`'s `mergeDeep`.
+ * Each document is parsed independently then recursively merged via `mergeDeep` from `@internals/utils`.
  * Throws when the input array is empty.
  *
  * @example
@@ -85,9 +83,12 @@ export async function mergeDocuments(pathOrApi: Array<string | Document>): Promi
     components: { schemas: {} },
   } as Document
 
-  const merged = documents.reduce((acc, current) => mergeDeep(acc, current as Document), seed)
+  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)
+  return parseDocument(merged as Document)
 }
 
 /**
@@ -110,12 +111,7 @@ export function parseFromConfig(source: AdapterSource): Promise<Document> {
       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)
-    }
+    return parseDocument(source.data as string, { canBundle: false })
   }
 
   if (source.type === 'paths') {

package/src/guards.ts

@@ -1,5 +1,5 @@
+import { isPlainObject } from '@internals/utils'
 import type { OpenAPIV2, OpenAPIV3, OpenAPIV3_1 } from 'openapi-types'
-import { isPlainObject } from 'remeda'
 import type { DiscriminatorObject, SchemaObject } from './types.ts'
 
 /**

package/src/index.ts

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

package/src/parser.ts

@@ -1,7 +1,7 @@
 import { URLPath } from '@internals/utils'
 import { ast } from '@kubb/core'
 import BaseOas from 'oas'
-import { DEFAULT_PARSER_OPTIONS, enumExtensionKeys, typeOptionMap } from './constants.ts'
+import { DEFAULT_PARSER_OPTIONS, enumExtensionKeys, SCHEMA_REF_PREFIX, typeOptionMap } from './constants.ts'
 import { isDiscriminator, isNullable, isReference } from './guards.ts'
 import { resolveRef } from './refs.ts'
 import {
@@ -148,7 +148,7 @@ function createSchemaParser(ctx: OasParserContext) {
         if (!deref || !isDiscriminator(deref)) return true
         const parentUnion = deref.oneOf ?? deref.anyOf
         if (!parentUnion) return true
-        const childRef = `#/components/schemas/${name}`
+        const childRef = `${SCHEMA_REF_PREFIX}${name}`
         const inOneOf = parentUnion.some((oneOfItem) => isReference(oneOfItem) && oneOfItem.$ref === childRef)
         const inMapping = Object.values(deref.discriminator.mapping ?? {}).some((v) => v === childRef)
         if (inOneOf || inMapping) {
@@ -404,18 +404,24 @@ function createSchemaParser(ctx: OasParserContext) {
         | 'number'
         | 'boolean'
         | 'string'
-      const sourceValues = extensionKey
-        ? [...new Set((schema as Record<string, unknown>)[extensionKey] as Array<string | number>)]
-        : [...new Set(filteredValues)]
+      const rawEnumNames = extensionKey ? ((schema as Record<string, unknown>)[extensionKey] as Array<string | number>) : undefined
+      const uniqueValues = [...new Set(filteredValues)]
+      const seenNames = new Set<string>()
 
       return ast.createSchema({
         ...enumBase,
         primitive: enumPrimitiveType,
-        namedEnumValues: sourceValues.map((label, index) => ({
-          name: String(label),
-          value: extensionKey ? (filteredValues[index] ?? label) : label,
-          primitive: enumPrimitiveType,
-        })),
+        namedEnumValues: uniqueValues
+          .map((value, index) => ({
+            name: String(rawEnumNames?.[index] ?? value),
+            value,
+            primitive: enumPrimitiveType,
+          }))
+          .filter((entry) => {
+            if (seenNames.has(entry.name)) return false
+            seenNames.add(entry.name)
+            return true
+          }),
       })
     }
 
@@ -691,6 +697,49 @@ function createSchemaParser(ctx: OasParserContext) {
     })
   }
 
+  /**
+   * Reads the inline `requestBody` metadata (description / required / contentType) that OAS exposes
+   * outside the schema itself. Returns an empty object when the request body is missing or a `$ref`.
+   */
+  function getRequestBodyMeta(operation: Operation): { description?: string; required: boolean; contentType?: string } {
+    const body = operation.schema.requestBody
+    if (!body || isReference(body)) return { required: false }
+
+    const inline = body as { description?: string; required?: boolean; content?: Record<string, unknown> }
+    return {
+      description: inline.description,
+      required: inline.required === true,
+      contentType: inline.content ? Object.keys(inline.content)[0] : undefined,
+    }
+  }
+
+  /**
+   * Reads the inline response object (not a `$ref`) and returns its description plus its `content` map.
+   */
+  function getResponseMeta(responseObj: unknown): { description?: string; content?: Record<string, unknown> } {
+    if (typeof responseObj !== 'object' || responseObj === null || Array.isArray(responseObj)) return {}
+
+    const inline = responseObj as { description?: string; content?: Record<string, unknown> }
+    return { description: inline.description, content: inline.content }
+  }
+
+  /**
+   * Collects property names whose schema has a truthy boolean flag (`readOnly` or `writeOnly`).
+   * `$ref` entries are skipped since their flags live on the dereferenced target.
+   */
+  function collectPropertyKeysByFlag(schema: SchemaObject | null, flag: 'readOnly' | 'writeOnly'): string[] | undefined {
+    if (!schema?.properties) return undefined
+
+    const keys: string[] = []
+    for (const key in schema.properties) {
+      const prop = schema.properties[key]
+      if (prop && !isReference(prop) && (prop as Record<string, unknown>)[flag]) {
+        keys.push(key)
+      }
+    }
+    return keys.length ? keys : undefined
+  }
+
   /**
    * Converts an OAS `Operation` into an `OperationNode`.
    */
@@ -701,38 +750,15 @@ function createSchemaParser(ctx: OasParserContext) {
 
     const requestBodySchema = getRequestSchema(document, operation, { contentType: ctx.contentType })
     const requestBodySchemaNode = requestBodySchema ? parseSchema({ schema: requestBodySchema }, options) : undefined
-
-    const requestBodyDescription =
-      operation.schema.requestBody && !isReference(operation.schema.requestBody)
-        ? (operation.schema.requestBody as { description?: string }).description
-        : undefined
-
-    const requestBodyKeysToOmit = requestBodySchema?.properties
-      ? Object.entries(requestBodySchema.properties)
-          .filter(([, prop]) => !isReference(prop) && (prop as { readOnly?: boolean }).readOnly)
-          .map(([key]) => key)
-      : undefined
-
-    const requestBodyRequired =
-      operation.schema.requestBody && !isReference(operation.schema.requestBody)
-        ? (operation.schema.requestBody as { required?: boolean }).required === true
-        : false
-
-    const requestBodyContentType = (() => {
-      if (!operation.schema.requestBody || isReference(operation.schema.requestBody)) {
-        return undefined
-      }
-      const content = (operation.schema.requestBody as { content?: Record<string, unknown> }).content
-      return content ? Object.keys(content)[0] : undefined
-    })()
+    const requestBodyMeta = getRequestBodyMeta(operation)
 
     const requestBody = requestBodySchemaNode
       ? {
-          description: requestBodyDescription,
-          schema: ast.syncOptionality(requestBodySchemaNode, requestBodyRequired),
-          keysToOmit: requestBodyKeysToOmit?.length ? requestBodyKeysToOmit : undefined,
-          required: requestBodyRequired || undefined,
-          contentType: requestBodyContentType,
+          description: requestBodyMeta.description,
+          schema: ast.syncOptionality(requestBodySchemaNode, requestBodyMeta.required),
+          keysToOmit: collectPropertyKeysByFlag(requestBodySchema, 'readOnly'),
+          required: requestBodyMeta.required || undefined,
+          contentType: requestBodyMeta.contentType,
         }
       : undefined
 
@@ -745,27 +771,15 @@ function createSchemaParser(ctx: OasParserContext) {
           ? parseSchema({ schema: responseSchema }, options)
           : ast.createSchema({ type: typeOptionMap.get(options.emptySchemaType)! })
 
-      const description = typeof responseObj === 'object' && responseObj !== null && !Array.isArray(responseObj) ? responseObj.description : undefined
-
-      const rawContent =
-        typeof responseObj === 'object' && responseObj !== null && !Array.isArray(responseObj)
-          ? (responseObj as { content?: Record<string, unknown> }).content
-          : undefined
-
-      const mediaType = rawContent ? getMediaType(Object.keys(rawContent)[0] ?? '') : getMediaType(operation.contentType ?? '')
-
-      const keysToOmit = responseSchema?.properties
-        ? Object.entries(responseSchema.properties)
-            .filter(([, prop]) => !isReference(prop) && (prop as { writeOnly?: boolean }).writeOnly)
-            .map(([key]) => key)
-        : undefined
+      const { description, content } = getResponseMeta(responseObj)
+      const mediaType = content ? getMediaType(Object.keys(content)[0] ?? '') : getMediaType(operation.contentType ?? '')
 
       return ast.createResponse({
         statusCode: statusCode as ast.StatusCode,
         description,
         schema,
         mediaType,
-        keysToOmit: keysToOmit?.length ? keysToOmit : undefined,
+        keysToOmit: collectPropertyKeysByFlag(responseSchema, 'writeOnly'),
       })
     })
 

package/src/refs.ts

@@ -1,4 +1,3 @@
-import jsonpointer from 'jsonpointer'
 import { isReference } from './guards.ts'
 import type { Document } from './types.ts'
 
@@ -24,7 +23,10 @@ export function resolveRef<T = unknown>(document: Document, $ref: string): T | n
   } else {
     return null
   }
-  const current = jsonpointer.get(document, $ref)
+  const current = $ref
+    .split('/')
+    .filter(Boolean)
+    .reduce((obj: unknown, key: string) => (obj as Record<string, unknown>)?.[key], document as unknown)
 
   if (!current) {
     throw new Error(`Could not find a definition for ${origRef}.`)

package/src/resolvers.ts

@@ -3,7 +3,7 @@ import { ast } from '@kubb/core'
 import type { ParameterObject, ServerObject } from 'oas/types'
 import { isRef } from 'oas/types'
 import { matchesMimeType } from 'oas/utils'
-import { formatMap, structuralKeys } from './constants.ts'
+import { formatMap, SCHEMA_REF_PREFIX, structuralKeys } from './constants.ts'
 import { isReference } from './guards.ts'
 import { dereferenceWithRef, resolveRef } from './refs.ts'
 import type { ContentType, Document, MediaTypeObject, Operation, ResponseObject, SchemaObject } from './types.ts'
@@ -128,16 +128,15 @@ function getResponseBody(responseBody: boolean | ResponseObject, contentType?: s
 
   let availableContentType: string | undefined
   const contentTypes = Object.keys(body.content)
-  contentTypes.forEach((mt: string) => {
-    if (!availableContentType && matchesMimeType.json(mt)) {
+  for (const mt of contentTypes) {
+    if (matchesMimeType.json(mt)) {
       availableContentType = mt
+      break
     }
-  })
+  }
 
   if (!availableContentType) {
-    contentTypes.forEach((mt: string) => {
-      if (!availableContentType) availableContentType = mt
-    })
+    availableContentType = contentTypes[0]
   }
 
   if (availableContentType) {
@@ -160,14 +159,13 @@ function getResponseBody(responseBody: boolean | ResponseObject, contentType?: s
  */
 export function getResponseSchema(document: Document, operation: Operation, statusCode: string | number, options: OperationsOptions = {}): SchemaObject {
   if (operation.schema.responses) {
-    Object.keys(operation.schema.responses).forEach((key) => {
-      const schema = operation.schema.responses![key]
-      const $ref = isReference(schema) ? schema.$ref : undefined
-
-      if (schema && $ref) {
-        operation.schema.responses![key] = resolveRef<any>(document, $ref)
+    const responses = operation.schema.responses
+    for (const key in responses) {
+      const schema = responses[key]
+      if (schema && isReference(schema)) {
+        responses[key] = resolveRef<any>(document, schema.$ref)
       }
-    })
+    }
   }
 
   const responseBody = getResponseBody(operation.getResponseByStatusCode(statusCode), options.contentType)
@@ -254,19 +252,30 @@ export type GetSchemasResult = {
  * // returned unchanged — contains a $ref
  * ```
  */
+/**
+ * Returns `true` when `fragment` carries any JSON Schema keyword that makes it
+ * structurally significant on its own (see `structuralKeys`).
+ *
+ * A fragment with a structural keyword can't be safely merged into a parent schema.
+ */
+function hasStructuralKeywords(fragment: SchemaObject): boolean {
+  for (const key in fragment) {
+    if (structuralKeys.has(key as 'properties')) return true
+  }
+  return false
+}
+
 export function flattenSchema(schema: SchemaObject | null): SchemaObject | null {
   if (!schema?.allOf || schema.allOf.length === 0) return schema ?? null
-  if (schema.allOf.some((item) => isRef(item))) return schema
 
-  const isPlainFragment = (item: SchemaObject) => !Object.keys(item).some((key) => structuralKeys.has(key as 'properties'))
-  if (!schema.allOf.every((item) => isPlainFragment(item as SchemaObject))) {
-    return schema
-  }
+  const allOfFragments = schema.allOf as SchemaObject[]
+  if (allOfFragments.some((item) => isRef(item))) return schema
+  if (allOfFragments.some(hasStructuralKeywords)) return schema
 
   const merged: SchemaObject = { ...schema }
   delete merged.allOf
 
-  for (const fragment of schema.allOf as SchemaObject[]) {
+  for (const fragment of allOfFragments) {
     for (const [key, value] of Object.entries(fragment)) {
       if (merged[key as keyof typeof merged] === undefined) {
         merged[key as keyof typeof merged] = value
@@ -311,10 +320,13 @@ function collectRefs(schema: unknown, refs = new Set<string>()): Set<string> {
   }
 
   if (schema && typeof schema === 'object') {
-    for (const [key, value] of Object.entries(schema)) {
+    for (const key in schema) {
+      const value = (schema as Record<string, unknown>)[key]
       if (key === '$ref' && typeof value === 'string') {
-        const match = value.match(/^#\/components\/schemas\/(.+)$/)
-        if (match) refs.add(match[1]!)
+        if (value.startsWith(SCHEMA_REF_PREFIX)) {
+          const name = value.slice(SCHEMA_REF_PREFIX.length)
+          if (name) refs.add(name)
+        }
       } else {
         collectRefs(value, refs)
       }
@@ -424,11 +436,22 @@ export function getSchemas(document: Document, { contentType }: GetSchemasOption
 
   const schemas: Record<string, SchemaObject> = {}
   const nameMapping = new Map<string, string>()
-  const multipleSources = (items: SchemaWithMetadata[]) => new Set(items.map((i) => i.source)).size > 1
 
   for (const [, items] of normalizedNames) {
+    const isSingle = items.length === 1
+    let hasMultipleSources = false
+    if (!isSingle) {
+      const firstSource = items[0]!.source
+      for (let i = 1; i < items.length; i++) {
+        if (items[i]!.source !== firstSource) {
+          hasMultipleSources = true
+          break
+        }
+      }
+    }
+
     items.forEach((item, index) => {
-      const suffix = items.length === 1 ? '' : multipleSources(items) ? getSemanticSuffix(item.source) : index === 0 ? '' : String(index + 1)
+      const suffix = isSingle ? '' : hasMultipleSources ? getSemanticSuffix(item.source) : index === 0 ? '' : String(index + 1)
       const uniqueName = item.originalName + suffix
       schemas[uniqueName] = item.schema
       nameMapping.set(`#/components/${item.source}/${item.originalName}`, uniqueName)