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

package/src/refs.ts

@@ -1,6 +1,9 @@
+import { type Diagnostic, Diagnostics } from '@kubb/core'
 import { isReference } from './guards.ts'
 import type { Document } from './types.ts'
 
+const _refCache = new WeakMap<Document, Map<string, unknown>>()
+
 /**
  * Resolves a local JSON pointer reference from a document.
  *
@@ -18,19 +21,42 @@ export function resolveRef<T = unknown>(document: Document, $ref: string): T | n
   if ($ref === '') {
     return null
   }
-  if ($ref.startsWith('#')) {
-    $ref = globalThis.decodeURIComponent($ref.substring(1))
-  } else {
-    return null
+  if (!$ref.startsWith('#')) return null
+  $ref = globalThis.decodeURIComponent($ref.substring(1))
+
+  let docCache = _refCache.get(document)
+  if (!docCache) {
+    docCache = new Map()
+    _refCache.set(document, docCache)
+  }
+
+  if (docCache.has($ref)) {
+    return docCache.get($ref) as T
   }
+
   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}.`)
+    const diagnostic: Diagnostic = {
+      code: Diagnostics.code.refNotFound,
+      severity: 'error',
+      message: `Could not find a definition for ${origRef}.`,
+      help: 'Add the schema under `components.schemas`, or fix the `$ref`. Run `kubb validate` to check the spec.',
+      location: { kind: 'schema', pointer: origRef, ref: origRef },
+    }
+    // Report the unresolved ref into the active build and resolve to null, like any
+    // other unresolvable ref. The build collects it and keeps going. Outside a build there is no
+    // sink, so throw rather than silently returning null.
+    if (!Diagnostics.report(diagnostic)) {
+      throw new Diagnostics.Error(diagnostic)
+    }
+    return null
   }
+
+  docCache.set($ref, current)
   return current as T
 }
 

package/src/resolvers.ts

@@ -1,12 +1,12 @@
 import { pascalCase } from '@internals/utils'
-import { ast } from '@kubb/core'
-import type { ParameterObject, ServerObject } from 'oas/types'
-import { isRef } from 'oas/types'
-import { matchesMimeType } from 'oas/utils'
-import { formatMap, SCHEMA_REF_PREFIX, structuralKeys } from './constants.ts'
+import { Diagnostics } from '@kubb/core'
+import type { ast } from '@kubb/core'
+import { formatMap, SCHEMA_REF_PREFIX, specialCasedFormats, structuralKeys } from './constants.ts'
 import { isReference } from './guards.ts'
+import { isJsonMimeType } from './mime.ts'
+import { getRequestContent, getResponseByStatusCode } from './operation.ts'
 import { dereferenceWithRef, resolveRef } from './refs.ts'
-import type { ContentType, Document, MediaTypeObject, Operation, ResponseObject, SchemaObject } from './types.ts'
+import type { ContentType, Document, MediaTypeObject, Operation, ParameterObject, ResponseObject, SchemaObject, ServerObject } from './types.ts'
 
 /**
  * Replaces `{variable}` placeholders in an OpenAPI server URL with provided values.
@@ -35,7 +35,13 @@ export function resolveServerUrl(server: ServerObject, overrides?: Record<string
     }
 
     if (variable.enum?.length && !variable.enum.some((e) => String(e) === value)) {
-      throw new Error(`Invalid server variable value '${value}' for '${key}' when resolving ${server.url}. Valid values are: ${variable.enum.join(', ')}.`)
+      throw new Diagnostics.Error({
+        code: Diagnostics.code.invalidServerVariable,
+        severity: 'error',
+        message: `Invalid server variable value '${value}' for '${key}' when resolving ${server.url}. Valid values are: ${variable.enum.join(', ')}.`,
+        help: `Use one of the allowed enum values, or drop the enum on the '${key}' server variable.`,
+        location: { kind: 'document', pointer: '#/servers' },
+      })
     }
 
     url = url.replaceAll(`{${key}}`, value)
@@ -52,6 +58,16 @@ export function getSchemaType(format: string): ast.SchemaType | null {
   return formatMap[format as keyof typeof formatMap] ?? null
 }
 
+/**
+ * Whether the parser maps `format` to a dedicated type. True for any `formatMap` entry and the
+ * `specialCasedFormats` `convertFormat` handles directly. False means the format falls back to the
+ * base type, which is what `KUBB_UNSUPPORTED_FORMAT` flags. Reading both sources keeps the
+ * diagnostic in step with the parser as `formatMap` grows.
+ */
+export function isHandledFormat(format: string): boolean {
+  return getSchemaType(format) !== null || specialCasedFormats.has(format)
+}
+
 /**
  * Converts an OAS primitive type string to its `PrimitiveSchemaType` equivalent.
  * Numeric types (`number`, `integer`, `bigint`) pass through unchanged. `boolean` maps to `'boolean'`. Everything else becomes `'string'`.
@@ -63,13 +79,6 @@ export function getPrimitiveType(type: string | undefined): ast.PrimitiveSchemaT
   return 'string'
 }
 
-/**
- * Narrows a content-type string to the `MediaType` union Kubb recognizes, or returns `null`.
- */
-export function getMediaType(contentType: string): ast.MediaType | null {
-  return Object.values(ast.mediaTypes).includes(contentType as ast.MediaType) ? (contentType as ast.MediaType) : null
-}
-
 export type OperationsOptions = {
   contentType?: ContentType
 }
@@ -86,7 +95,7 @@ export type OperationsOptions = {
  * ```
  */
 export function getParameters(document: Document, operation: Operation): Array<ParameterObject> {
-  const resolveParams = (params: unknown[]): Array<ParameterObject> =>
+  const resolveParams = (params: Array<unknown>): Array<ParameterObject> =>
     params.map((p) => dereferenceWithRef(document, p)).filter((p): p is ParameterObject => !!p && typeof p === 'object' && 'in' in p && 'name' in p)
 
   const operationParams = resolveParams(operation.schema?.parameters || [])
@@ -108,7 +117,7 @@ export function getParameters(document: Document, operation: Operation): Array<P
   return Array.from(paramMap.values())
 }
 
-function getResponseBody(responseBody: boolean | ResponseObject, contentType?: string): MediaTypeObject | false | [string, MediaTypeObject, ...string[]] {
+function getResponseBody(responseBody: boolean | ResponseObject, contentType?: string): MediaTypeObject | false | [string, MediaTypeObject, ...Array<string>] {
   if (!responseBody) return false
   if (isReference(responseBody)) return false
 
@@ -123,7 +132,7 @@ function getResponseBody(responseBody: boolean | ResponseObject, contentType?: s
   let availableContentType: string | undefined
   const contentTypes = Object.keys(body.content)
   for (const mt of contentTypes) {
-    if (matchesMimeType.json(mt)) {
+    if (isJsonMimeType(mt)) {
       availableContentType = mt
       break
     }
@@ -162,7 +171,7 @@ export function getResponseSchema(document: Document, operation: Operation, stat
     }
   }
 
-  const responseBody = getResponseBody(operation.getResponseByStatusCode(statusCode), options.contentType)
+  const responseBody = getResponseBody(getResponseByStatusCode({ document, operation, statusCode }), options.contentType)
 
   if (responseBody === false) {
     return {}
@@ -190,7 +199,7 @@ export function getRequestSchema(document: Document, operation: Operation, optio
     operation.schema.requestBody = dereferenceWithRef(document, operation.schema.requestBody)
   }
 
-  const requestBody = operation.getRequestBody(options.contentType)
+  const requestBody = getRequestContent({ document, operation, mediaType: options.contentType })
 
   if (requestBody === false) {
     return null
@@ -213,7 +222,7 @@ type SchemaSourceMode = 'schemas' | 'responses' | 'requestBodies'
 /**
  * A schema annotated with its component section source and original name. Used by `resolveNameCollisions` for cross-source collision resolution.
  */
-export type SchemaWithMetadata = {
+type SchemaWithMetadata = {
   schema: SchemaObject
   source: SchemaSourceMode
   originalName: string
@@ -231,7 +240,7 @@ export type GetSchemasResult = {
 /**
  * Flattens a keyword-only `allOf` into its parent schema.
  *
- * Only flattens when every member is a plain fragment — no `$ref` and no structural keywords
+ * Only flattens when every member is a plain fragment, with no `$ref` and no structural keywords
  * (see `structuralKeys`). Outer schema values take precedence over fragment values.
  * Returns `null` for a `null` input, and the original schema unchanged when flattening is unsafe.
  *
@@ -241,7 +250,7 @@ export type GetSchemasResult = {
  * // { type: 'object', properties: {}, description: 'A pet' }
  *
  * flattenSchema({ allOf: [{ $ref: '#/components/schemas/Pet' }] })
- * // returned unchanged — contains a $ref
+ * // returned unchanged, contains a $ref
  * ```
  */
 /**
@@ -260,8 +269,8 @@ function hasStructuralKeywords(fragment: SchemaObject): boolean {
 export function flattenSchema(schema: SchemaObject | null): SchemaObject | null {
   if (!schema?.allOf || schema.allOf.length === 0) return schema ?? null
 
-  const allOfFragments = schema.allOf as SchemaObject[]
-  if (allOfFragments.some((item) => isRef(item))) return schema
+  const allOfFragments = schema.allOf as Array<SchemaObject>
+  if (allOfFragments.some((item) => isReference(item))) return schema
   if (allOfFragments.some(hasStructuralKeywords)) return schema
 
   const merged: SchemaObject = { ...schema }
@@ -281,7 +290,7 @@ export function flattenSchema(schema: SchemaObject | null): SchemaObject | null
 /**
  * Extracts the inline schema from a media-type `content` map.
  *
- * Prefers `preferredContentType` when given; otherwise uses the first key in the map.
+ * Prefers `preferredContentType` when given, otherwise uses the first key in the map.
  * Returns `null` when `content` is absent, the schema is missing, or the schema is a `$ref`.
  *
  * @example
@@ -305,27 +314,25 @@ export function extractSchemaFromContent(content: Record<string, unknown> | unde
 /**
  * Walks a schema tree and collects the names of all `#/components/schemas/<name>` `$ref`s.
  */
-function collectRefs(schema: unknown, refs = new Set<string>()): Set<string> {
+function* collectRefs(schema: unknown): Generator<string, void, undefined> {
   if (Array.isArray(schema)) {
-    for (const item of schema) collectRefs(item, refs)
-    return refs
+    for (const item of schema) yield* collectRefs(item)
+    return
   }
 
   if (schema && typeof schema === 'object') {
     for (const key in schema) {
       const value = (schema as Record<string, unknown>)[key]
-      if (key === '$ref' && typeof value === 'string') {
-        if (value.startsWith(SCHEMA_REF_PREFIX)) {
-          const name = value.slice(SCHEMA_REF_PREFIX.length)
-          if (name) refs.add(name)
-        }
-      } else {
-        collectRefs(value, refs)
+      if (!(key === '$ref' && typeof value === 'string')) {
+        yield* collectRefs(value)
+        continue
+      }
+      if (value.startsWith(SCHEMA_REF_PREFIX)) {
+        const name = value.slice(SCHEMA_REF_PREFIX.length)
+        if (name) yield name
       }
     }
   }
-
-  return refs
 }
 
 /**
@@ -341,13 +348,13 @@ function collectRefs(schema: unknown, refs = new Set<string>()): Set<string> {
  * ```
  */
 export function sortSchemas(schemas: Record<string, SchemaObject>): Record<string, SchemaObject> {
-  const deps = new Map<string, string[]>()
+  const deps = new Map<string, Array<string>>()
 
   for (const [name, schema] of Object.entries(schemas)) {
-    deps.set(name, Array.from(collectRefs(schema)))
+    deps.set(name, [...new Set(collectRefs(schema))])
   }
 
-  const sorted: string[] = []
+  const sorted: Array<string> = []
   const visited = new Set<string>()
 
   function visit(name: string, stack: Set<string>) {
@@ -404,7 +411,7 @@ function resolveSchemaRef(document: Document, schema: SchemaObject): SchemaObjec
 export function getSchemas(document: Document, { contentType }: GetSchemasOptions): GetSchemasResult {
   const components = document.components
 
-  const candidates: SchemaWithMetadata[] = [
+  const candidates: Array<SchemaWithMetadata> = [
     ...Object.entries((components?.schemas as Record<string, SchemaObject>) ?? {}).map(([name, schema]) => ({
       schema: resolveSchemaRef(document, schema),
       source: 'schemas' as const,
@@ -426,7 +433,7 @@ export function getSchemas(document: Document, { contentType }: GetSchemasOption
     ),
   ]
 
-  const normalizedNames = new Map<string, SchemaWithMetadata[]>()
+  const normalizedNames = new Map<string, Array<SchemaWithMetadata>>()
   for (const item of candidates) {
     const key = pascalCase(item.originalName)
     const bucket = normalizedNames.get(key) ?? []
@@ -463,7 +470,7 @@ export function getSchemas(document: Document, { contentType }: GetSchemasOption
 
 /**
  * Resolves the AST type descriptor for a date/time format, honoring the `dateType` option.
- * Returns `null` when `dateType: false`, signalling the format should fall through to `string`.
+ * Returns `null` when `dateType: false`, so the format falls through to `string`.
  */
 export function getDateType(
   options: ast.ParserOptions,
@@ -514,15 +521,16 @@ export function buildSchemaNode(schema: SchemaObject, name: string | null | unde
     writeOnly: schema.writeOnly,
     default: defaultValue,
     example: schema.example,
+    format: schema.format,
   } as const
 }
 
 /**
  * Returns all request body content type keys for an operation.
  *
- * The requestBody is dereferenced **in-place** when it is a `$ref` — the same mutation
- * that `getRequestSchema` already performs — so that the returned list accurately reflects
- * the available content types even for referenced bodies.
+ * The requestBody is dereferenced in place when it is a `$ref` (the same mutation that
+ * `getRequestSchema` already performs), so the returned list accurately reflects the
+ * available content types even for referenced bodies.
  *
  * @example
  * ```ts
@@ -530,7 +538,7 @@ export function buildSchemaNode(schema: SchemaObject, name: string | null | unde
  * // ['application/json', 'multipart/form-data']
  * ```
  */
-export function getRequestBodyContentTypes(document: Document, operation: Operation): string[] {
+export function getRequestBodyContentTypes(document: Document, operation: Operation): Array<string> {
   if (operation.schema.requestBody) {
     operation.schema.requestBody = dereferenceWithRef(document, operation.schema.requestBody)
   }
@@ -539,6 +547,36 @@ export function getRequestBodyContentTypes(document: Document, operation: Operat
   if (!body) return []
 
   // dereferenceWithRef keeps $ref but spreads all resolved fields (including `content`).
-  // Do not bail out on isReference — the content is already present on the merged object.
+  // Do not bail out on isReference, the content is already present on the merged object.
+  return body.content ? Object.keys(body.content) : []
+}
+
+/**
+ * Returns all response content type keys for an operation at a given status code.
+ *
+ * Response `$ref`s are resolved in place first (the same mutation `getResponseSchema` performs),
+ * so the returned list reflects the available content types even for referenced responses.
+ *
+ * @example
+ * ```ts
+ * getResponseBodyContentTypes(document, operation, 200)
+ * // ['application/json', 'application/xml']
+ * ```
+ */
+export function getResponseBodyContentTypes(document: Document, operation: Operation, statusCode: string | number): Array<string> {
+  if (operation.schema.responses) {
+    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 responseObj = getResponseByStatusCode({ document, operation, statusCode })
+  if (!responseObj || typeof responseObj !== 'object' || isReference(responseObj)) return []
+
+  const body = responseObj as { content?: Record<string, unknown> }
   return body.content ? Object.keys(body.content) : []
 }

package/src/schemaDiagnostics.ts

@@ -0,0 +1,76 @@
+import { Diagnostics } from '@kubb/core'
+import type { ast } from '@kubb/core'
+import { isHandledFormat } from './resolvers.ts'
+
+/**
+ * Reports the advisory diagnostics (`KUBB_UNSUPPORTED_FORMAT`, `KUBB_DEPRECATED`) for one
+ * top-level schema. Walks the node the parser produced during `preScan`, threading the RFC 6901
+ * pointer as it descends so a nested field reports against its full path
+ * (`#/components/schemas/Pet/properties/owner/properties/name`). Refs are not followed, so the
+ * resolved schema is reported under its own walk. Reports land in the active build run, are a
+ * no-op outside one, and repeats are deduped by the build.
+ */
+export function reportSchemaDiagnostics({ node, name }: { node: ast.SchemaNode; name: string }): void {
+  visit(node, `#/components/schemas/${escapePointerToken(name)}`)
+}
+
+/**
+ * Escapes a single JSON pointer reference token per RFC 6901 (`~` → `~0`, `/` → `~1`), so a
+ * property name with those characters maps to a distinct pointer instead of colliding in the dedupe.
+ */
+function escapePointerToken(token: string): string {
+  return token.replace(/~/g, '~0').replace(/\//g, '~1')
+}
+
+function visit(node: ast.SchemaNode, pointer: string): void {
+  if (node.deprecated) {
+    Diagnostics.report({
+      code: Diagnostics.code.deprecated,
+      severity: 'info',
+      message: 'This schema is marked as deprecated.',
+      location: { kind: 'schema', pointer },
+    })
+  }
+
+  if (typeof node.format === 'string' && !isHandledFormat(node.format)) {
+    Diagnostics.report({
+      code: Diagnostics.code.unsupportedFormat,
+      severity: 'warning',
+      message: `Kubb does not map the format "${node.format}" to a specific type, so it falls back to the base type.`,
+      help: `Use a format Kubb supports, or handle "${node.format}" with a custom parser or plugin.`,
+      location: { kind: 'schema', pointer },
+    })
+  }
+
+  if (node.type === 'object') {
+    for (const property of node.properties) {
+      visit(property.schema, `${pointer}/properties/${escapePointerToken(property.name)}`)
+    }
+    if (node.additionalProperties && typeof node.additionalProperties === 'object') {
+      visit(node.additionalProperties, `${pointer}/additionalProperties`)
+    }
+    return
+  }
+
+  if (node.type === 'array') {
+    for (const item of node.items ?? []) {
+      visit(item, `${pointer}/items`)
+    }
+    return
+  }
+
+  if (node.type === 'tuple') {
+    // Each tuple position has its own pointer, so index them. A shared `/items` would collapse
+    // distinct diagnostics in the dedupe.
+    for (const [index, item] of (node.items ?? []).entries()) {
+      visit(item, `${pointer}/items/${index}`)
+    }
+    return
+  }
+
+  if (node.type === 'union' || node.type === 'intersection') {
+    for (const [index, member] of (node.members ?? []).entries()) {
+      visit(member, `${pointer}/members/${index}`)
+    }
+  }
+}