@kubb/adapter-oas 5.0.0-beta.36 → 5.0.0-beta.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/adapter-oas",
-  "version": "5.0.0-beta.36",
+  "version": "5.0.0-beta.37",
   "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",
@@ -47,7 +47,7 @@
     "oas": "^32.1.18",
     "oas-normalize": "^16.0.4",
     "swagger2openapi": "^7.0.8",
-    "@kubb/core": "5.0.0-beta.36"
+    "@kubb/core": "5.0.0-beta.37"
   },
   "devDependencies": {
     "@types/swagger2openapi": "^7.0.4",

package/src/adapter.ts

@@ -3,7 +3,7 @@ import { ast, createAdapter } from '@kubb/core'
 import type { AdapterSource } from '@kubb/core'
 import BaseOas from 'oas'
 import { DEFAULT_PARSER_OPTIONS } from './constants.ts'
-import { parseDocument, parseFromConfig, validateDocument } from './factory.ts'
+import { assertInputExists, parseDocument, parseFromConfig, validateDocument } from './factory.ts'
 import { createSchemaParser } from './parser.ts'
 import { getSchemas } from './resolvers.ts'
 import { createInputStream, preScan, resolveBaseUrl } from './stream.ts'
@@ -144,6 +144,7 @@ export const adapterOas = createAdapter<AdapterOas>((options) => {
       return parsedDocument
     },
     async validate(input, options) {
+      await assertInputExists(input)
       const document = await parseDocument(input)
       await validateDocument(document, options)
     },

package/src/constants.ts

@@ -79,6 +79,14 @@ export const structuralKeys = new Set(['properties', 'items', 'additionalPropert
  * formatMap['float']  // 'number'
  * ```
  */
+/**
+ * Formats `convertFormat` maps to a dedicated type without going through `formatMap`:
+ * `int64` and the date/time family. Keep this in sync with the `convertFormat`
+ * special-cases in `parser.ts`. `isHandledFormat` reads it so the
+ * `KUBB_UNSUPPORTED_FORMAT` diagnostic and the parser agree on what is handled.
+ */
+export const specialCasedFormats: ReadonlySet<string> = new Set(['int64', 'date-time', 'date', 'time'])
+
 export const formatMap = {
   uuid: 'uuid',
   email: 'email',

package/src/dialect.ts

@@ -4,13 +4,13 @@ import { resolveRef } from './refs.ts'
 import type { SchemaObject } from './types.ts'
 
 /**
- * The OpenAPI / Swagger dialect — the default used by `@kubb/adapter-oas`.
+ * The OpenAPI / Swagger dialect, the default used by `@kubb/adapter-oas`.
  *
  * Implements the spec-agnostic {@link ast.SchemaDialect} contract: it isolates the
  * decisions that differ between specs (nullability, `$ref`, discriminator, binary,
  * ref resolution) so the converter pipeline and dispatch rules stay shared. A
- * future adapter (e.g. AsyncAPI) ships its own dialect — `type: ['null', …]`
- * nullability, no discriminator object, binary via `contentEncoding` — and reuses
+ * future adapter (e.g. AsyncAPI) ships its own dialect, `type: ['null', …]`
+ * nullability, no discriminator object, binary via `contentEncoding` and reuses
  * the rest unchanged.
  *
  * Formats (`uuid`, `email`, dates, …) are intentionally NOT here: they are shared

package/src/factory.ts

@@ -1,5 +1,6 @@
 import path from 'node:path'
-import { mergeDeep, URLPath } from '@internals/utils'
+import { exists, mergeDeep, URLPath } from '@internals/utils'
+import { diagnosticCode, DiagnosticError } from '@kubb/core'
 import type { AdapterSource } from '@kubb/core'
 import { bundle, loadConfig } from '@redocly/openapi-core'
 import OASNormalize from 'oas-normalize'
@@ -77,7 +78,13 @@ export async function mergeDocuments(pathOrApi: Array<string | Document>): Promi
   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.')
+    throw new DiagnosticError({
+      code: diagnosticCode.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 = {
@@ -99,9 +106,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
@@ -109,7 +116,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)
@@ -127,7 +134,29 @@ export function parseFromConfig(source: AdapterSource): Promise<Document> {
     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)
+}
+
+/**
+ * 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 (new URLPath(input).isURL) {
+    return
+  }
+  if (!(await exists(input))) {
+    throw new DiagnosticError({
+      code: diagnosticCode.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' },
+    })
+  }
 }
 
 /**
@@ -157,6 +186,6 @@ export async function validateDocument(document: Document, { throwOnError = fals
       throw error
     }
 
-    // Validation failures are non-fatal — mirror plugin-oas behavior
+    // Validation failures are non-fatal, mirror plugin-oas behavior
   }
 }

package/src/parser.ts

@@ -60,7 +60,7 @@ type SchemaContext = {
 }
 
 /**
- * One entry in this adapter's schema-dispatch table — a {@link ast.DispatchRule} specialized
+ * One entry in this adapter's schema-dispatch table, a {@link ast.DispatchRule} specialized
  * to OAS schema context and Kubb `SchemaNode` output. See {@link ast.dispatch} for the contract
  * a future adapter (e.g. AsyncAPI) follows: define a context type and an ordered rules table.
  */
@@ -97,7 +97,7 @@ function normalizeArrayEnum(schema: SchemaObject): SchemaObject {
 export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect = oasDialect) {
   const document = ctx.document
 
-  // Branch handlers — each converts one OAS schema pattern to a SchemaNode.
+  // Branch handlers, each converts one OAS schema pattern to a SchemaNode.
 
   /**
    * Tracks `$ref` paths that are currently being resolved to prevent infinite
@@ -106,16 +106,12 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
   const resolvingRefs = new Set<string>()
 
   /**
-   * Cache of already-resolved `$ref` schemas within this parser instance.
+   * Cache of `$ref` schemas already resolved in this parser instance, keyed by ref path.
    *
-   * Without this, the same referenced schema (e.g. `customer`) is fully re-expanded
-   * every time it appears as a `$ref` in a different parent schema. In heavily
-   * cross-referenced specs like Stripe (~1 400 schemas), this causes exponential
-   * blowup — `customer` alone may be referenced from dozens of top-level schemas,
-   * each triggering a fresh recursive expansion of its entire sub-tree.
-   *
-   * Memoizing by `$ref` path reduces the overall work from O(2^depth) to O(N)
-   * where N is the number of unique schema names.
+   * Without it, a shared schema (e.g. `customer`) is re-expanded for every `$ref` that points at
+   * it. In cross-referenced specs like Stripe (~1400 schemas) that becomes exponential blowup,
+   * since one schema can be referenced from dozens of parents, each re-walking its whole subtree.
+   * Memoizing by ref path drops the work from O(2^depth) to O(N) unique schema names.
    */
   const resolvedRefCache = new Map<string, ast.SchemaNode | null>()
 
@@ -253,7 +249,7 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
 
     if (schema.properties) {
       const { allOf: _allOf, ...schemaWithoutAllOf } = schema
-      // Don't pass `name` here — the result must stay anonymous so it can be merged with the
+      // Don't pass `name` here, the result must stay anonymous so it can be merged with the
       // adjacent synthetic object in `mergeAdjacentObjectsLazy`. Nested enum qualification
       // happens upstream via `convertObject`'s `setEnumName` propagation.
       allOfMembers.push(parseSchema({ schema: schemaWithoutAllOf }, rawOptions))
@@ -495,7 +491,7 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
     const nullInEnum = schema.enum!.includes(null)
     const filteredValues = (nullInEnum ? schema.enum!.filter((v) => v !== null) : schema.enum!) as Array<string | number | boolean>
 
-    // drf-spectacular `NullEnum` ({ enum: [null] }) is just `null`; an empty enum node would
+    // drf-spectacular `NullEnum` ({ enum: [null] }) is just `null`. An empty enum node would
     // render as `never` (plugin-ts) / invalid `z.enum([])` (plugin-zod). Mirror the `const: null`
     // branch so it renders as a clean `null` (not `z.null().nullable()`).
     if (nullInEnum && filteredValues.length === 0) {
@@ -777,7 +773,7 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
   /**
    * Ordered schema-dispatch table. Order is significant: composition keywords (`$ref`, `allOf`,
    * `oneOf`/`anyOf`) take precedence over `const`/`format`, which take precedence over the plain
-   * `type`. The first matching rule that produces a node wins; see {@link SchemaRule} for the
+   * `type`. The first matching rule that produces a node wins. See {@link SchemaRule} for the
    * match/convert/fall-through contract.
    */
   const schemaRules: Array<SchemaRule> = [
@@ -1058,8 +1054,7 @@ export function parseSchema(
  * Parses an OpenAPI specification into Kubb's universal `InputNode` AST.
  *
  * This is the main entry point for `@kubb/adapter-oas`. It converts OpenAPI/Swagger specs into a spec-agnostic tree
- * that downstream plugins (`plugin-ts`, `plugin-zod`, etc.) consume for code generation. No code is generated here —
- * the tree is a pure data structure representing all schemas and operations.
+ * that downstream plugins (`plugin-ts`, `plugin-zod`, etc.) consume for code generation. No code is generated here,  * the tree is a pure data structure representing all schemas and operations.
  *
  * Returns the AST root and a `nameMapping` for resolving schema references.
  *

package/src/refs.ts

@@ -1,3 +1,4 @@
+import { type Diagnostic, diagnosticCode, Diagnostics } from '@kubb/core'
 import { isReference } from './guards.ts'
 import type { Document } from './types.ts'
 
@@ -39,7 +40,17 @@ export function resolveRef<T = unknown>(document: Document, $ref: string): T | n
     .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: diagnosticCode.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.
+    Diagnostics.report(diagnostic)
+    return null
   }
 
   docCache.set($ref, current)

package/src/resolvers.ts

@@ -1,9 +1,10 @@
 import { pascalCase } from '@internals/utils'
+import { diagnosticCode, DiagnosticError } from '@kubb/core'
 import type { 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 { formatMap, SCHEMA_REF_PREFIX, specialCasedFormats, 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'
@@ -35,7 +36,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 DiagnosticError({
+        code: diagnosticCode.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 +59,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'`.
@@ -224,7 +241,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.
  *
@@ -234,7 +251,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
  * ```
  */
 /**
@@ -274,7 +291,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
@@ -512,9 +529,9 @@ export function buildSchemaNode(schema: SchemaObject, name: string | null | unde
 /**
  * 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
@@ -531,14 +548,14 @@ 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 —
+ * 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

package/src/schemaDiagnostics.ts

@@ -0,0 +1,59 @@
+import { diagnosticCode, 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/${name}`)
+}
+
+function visit(node: ast.SchemaNode, pointer: string): void {
+  if (node.deprecated) {
+    Diagnostics.report({
+      code: diagnosticCode.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: diagnosticCode.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/${property.name}`)
+    }
+    if (node.additionalProperties && typeof node.additionalProperties === 'object') {
+      visit(node.additionalProperties, `${pointer}/additionalProperties`)
+    }
+    return
+  }
+
+  if (node.type === 'array' || node.type === 'tuple') {
+    for (const item of node.items ?? []) {
+      visit(item, `${pointer}/items`)
+    }
+    return
+  }
+
+  if (node.type === 'union' || node.type === 'intersection') {
+    for (const member of node.members ?? []) {
+      visit(member, pointer)
+    }
+  }
+}

package/src/stream.ts

@@ -4,6 +4,7 @@ import { SCHEMA_REF_PREFIX } from './constants.ts'
 import { buildDiscriminatorChildMap, patchDiscriminatorNode } from './discriminator.ts'
 import type { SchemaParser } from './parser.ts'
 import { resolveServerUrl } from './resolvers.ts'
+import { reportSchemaDiagnostics } from './schemaDiagnostics.ts'
 import type { DiscriminatorTarget } from './discriminator.ts'
 import type { AdapterOas, Document, SchemaObject } from './types.ts'
 
@@ -41,7 +42,7 @@ function createDedupePlan({
     isCandidate: (node) => {
       if (node.type === 'enum') return true
       if (node.type !== 'object') return false
-      // Skip object shapes that are part of a circular chain — hoisting them would break the cycle.
+      // Skip object shapes that are part of a circular chain, hoisting them would break the cycle.
       if (node.name && circularSchemas.has(node.name)) return false
       return !ast.containsCircularRef(node, { circularSchemas })
     },
@@ -98,7 +99,7 @@ export function resolveBaseUrl({
  * After this call, only `refAliasMap` and `discriminatorChildMap` stay alive in the adapter closure.
  * Both are proportional to the number of aliases or discriminator parents, not total schema count.
  *
- * Each schema is parsed again during the streaming pass — this is intentional.
+ * Each schema is parsed again during the streaming pass. This is intentional.
  * Holding the parsed nodes in memory here would defeat the streaming memory benefit.
  *
  * @example
@@ -136,6 +137,7 @@ export function preScan({
   for (const [name, schema] of Object.entries(schemas)) {
     const node = parseSchema({ schema, name }, parserOptions)
     allNodes.push(node)
+    reportSchemaDiagnostics({ node, name })
     if (node.type === 'ref' && node.name && node.name !== name) {
       refAliasMap.set(name, node)
     }
@@ -153,7 +155,7 @@ export function preScan({
   let dedupePlan: ast.DedupePlan | null = null
   if (dedupe) {
     // One extra parse pass over operations so duplicates in request/response bodies are seen.
-    // Reuses the already-parsed `allNodes` for schemas — no second schema parse.
+    // Reuses the already-parsed `allNodes` for schemas, no second schema parse.
     const operationNodes: Array<ast.OperationNode> = []
     for (const methods of Object.values(baseOas.getPaths())) {
       for (const operation of Object.values(methods)) {

package/src/types.ts

@@ -172,9 +172,9 @@ export type AdapterOasOptions = {
   serverVariables?: Record<string, string>
   /**
    * How the `discriminator` field on `oneOf`/`anyOf` schemas is interpreted.
-   * - `'strict'` — child schemas stay exactly as written; the discriminator
+   * - `'strict'` child schemas stay exactly as written. The discriminator
    *   narrows types at the call site but child shapes are not modified.
-   * - `'inherit'` — Kubb propagates the discriminator property as a literal
+   * - `'inherit'` Kubb propagates the discriminator property as a literal
    *   value into each child schema, so each branch's discriminator field is
    *   precisely typed.
    *
@@ -185,9 +185,9 @@ export type AdapterOasOptions = {
    * Collapse structurally identical schemas and enums into a single shared definition.
    *
    * Duplicated inline shapes (especially enums repeated across many properties) are hoisted
-   * into one named schema; every other occurrence — and any structurally identical top-level
-   * component — becomes a `ref` to it. Equality is shape-only: documentation such as
-   * `description` and `example` is ignored. Enabled by default; set to `false` to keep every
+   * into one named schema. Every other occurrence, and any structurally identical top-level
+   * component, becomes a `ref` to it. Equality is shape-only: documentation such as
+   * `description` and `example` is ignored. Enabled by default. Set to `false` to keep every
    * occurrence inline and produce byte-for-byte identical output to earlier versions.
    *
    * @default true