@kubb/adapter-oas 5.0.0-alpha.73 → 5.0.0-alpha.74

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/adapter-oas",
-  "version": "5.0.0-alpha.73",
+  "version": "5.0.0-alpha.74",
   "description": "OpenAPI / Swagger adapter for Kubb converts OAS input into a @kubb/ast RootNode.",
   "keywords": [
     "adapter",
@@ -42,11 +42,11 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@redocly/openapi-core": "^2.30.1",
+    "@redocly/openapi-core": "^2.30.3",
     "oas": "^32.1.18",
     "oas-normalize": "^16.0.4",
     "swagger2openapi": "^7.0.8",
-    "@kubb/core": "5.0.0-alpha.73"
+    "@kubb/core": "5.0.0-alpha.74"
   },
   "devDependencies": {
     "@types/swagger2openapi": "^7.0.4",

package/src/parser.ts

@@ -20,10 +20,10 @@ import {
 import type { ContentType, Document, Operation, ReferenceObject, SchemaObject } from './types.ts'
 
 /**
- * Construction-time context for the OAS parser.
+ * Parser context holding the raw OpenAPI document and optional content-type override.
  *
- * Holds the raw OpenAPI document and optional content-type override used when extracting
- * request/response schemas.
+ * Passed to schema and operation converters to access the full specification
+ * and handle content negotiation when multiple media types are available.
  */
 export type OasParserContext = {
   document: Document
@@ -31,8 +31,11 @@ export type OasParserContext = {
 }
 
 /**
- * Pre-computed per-schema context passed to every `convert*` branch handler.
- * Grouping these values avoids repeating the same derivations across all branches.
+ * Pre-computed per-schema context passed to every schema converter.
+ *
+ * Centralizes schema derivations (type resolution, defaults, options) to avoid repeated
+ * computation across all conversion branches. The `type` field is normalized from OAS 3.1
+ * multi-type arrays to a single string.
  */
 type SchemaContext = {
   schema: SchemaObject
@@ -48,9 +51,12 @@ type SchemaContext = {
 }
 
 /**
- * Normalize a malformed `{ type: 'array', enum: [...] }` schema by moving the
- * enum values into the items sub-schema. This pattern is technically invalid OAS
- * but appears in the wild and must be handled gracefully.
+ * Normalizes malformed `{ type: 'array', enum: [...] }` schemas by moving enum values into items.
+ *
+ * This pattern violates the OpenAPI spec but appears in real specs. The fix moves enum values
+ * from the array to its items sub-schema, making them valid for downstream processing.
+ *
+ * @note This is a defensive measure for robustness with non-compliant specs.
  */
 function normalizeArrayEnum(schema: SchemaObject): SchemaObject {
   const isItemsObject = typeof schema.items === 'object' && !Array.isArray(schema.items)
@@ -64,10 +70,13 @@ function normalizeArrayEnum(schema: SchemaObject): SchemaObject {
 }
 
 /**
- * Builds the internal converter functions for a given `OasParserContext`.
+ * Factory function that creates schema and operation converters for a given OpenAPI context.
+ *
+ * Returns closures that share mutable state (`resolvingRefs` set for cycle detection).
+ * Each converter branch (`convertRef`, `convertAllOf`, etc.) mutually recursively calls `parseSchema`,
+ * made possible by hoisting of function declarations.
  *
- * All `convert*` functions are defined as function declarations so they can freely
- * reference each other and `parseSchema` via JS hoisting (mutual recursion).
+ * @note Not exported; called internally by `parseOas()` and `parseSchema()`.
  */
 function createSchemaParser(ctx: OasParserContext) {
   const document = ctx.document
@@ -922,12 +931,18 @@ function createSchemaParser(ctx: OasParserContext) {
 }
 
 /**
- * Converts a single `SchemaObject` into a `SchemaNode`.
+ * Parses a single OpenAPI `SchemaObject` into a `SchemaNode`.
+ *
+ * Use this for targeted schema parsing when you don't need the full spec.
+ * For complete spec parsing, use `parseOas()` instead which handles operations and all schemas together.
+ *
+ * @note Circular schema references are tracked via internal state and resolve appropriately.
  *
  * @example
  * ```ts
+ * const document = yaml.parse(fs.readFileSync('openapi.yaml', 'utf8'))
  * const ctx = { document }
- * parseSchema(ctx, { schema: { type: 'string', format: 'uuid' } })
+ * const schema = parseSchema(ctx, { schema: { type: 'string', format: 'uuid' } })
  * ```
  */
 export function parseSchema(
@@ -939,16 +954,20 @@ export function parseSchema(
 }
 
 /**
- * Converts the entire OpenAPI spec into an `InputNode` (the top-level `@kubb/ast` tree).
+ * Parses an OpenAPI specification into Kubb's universal `InputNode` AST.
  *
- * This is the main entry point: `OpenAPI / Swagger → Kubb AST`.
- * No code is generated here — the resulting tree is spec-agnostic and consumed by
- * downstream plugins (`plugin-ts`, `plugin-zod`, …).
+ * 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.
+ *
+ * Returns the AST root and a `nameMapping` for resolving schema references.
  *
  * @example
  * ```ts
+ * import { parseOas } from '@kubb/adapter-oas'
+ *
  * const document = await parseFromConfig(config)
- * const root = parseOas(document, { dateType: 'date', contentType: 'application/json' })
+ * const { root, nameMapping } = parseOas(document, { dateType: 'date', contentType: 'application/json' })
  * ```
  */
 export function parseOas(

package/src/resolvers.ts

@@ -9,10 +9,9 @@ import { dereferenceWithRef, resolveRef } from './refs.ts'
 import type { ContentType, Document, MediaTypeObject, Operation, ResponseObject, SchemaObject } from './types.ts'
 
 /**
- * Resolves `{variable}` placeholders in an OpenAPI server URL.
- *
- * Resolution order per variable: `overrides[key]` → `variable.default` → left unreplaced.
- * Throws when an override value is not in the variable's allowed `enum` list.
+ * Replaces `{variable}` placeholders in an OpenAPI server URL with provided values.
+ * Resolution order: `overrides[key]` → `variable.default` → left unreplaced.
+ * Throws if an override value is not in the variable's `enum` list.
  *
  * @example
  * ```ts
@@ -46,18 +45,16 @@ export function resolveServerUrl(server: ServerObject, overrides?: Record<string
 }
 
 /**
- * Looks up the Kubb `SchemaType` for a given OAS `format` string.
- * Returns `undefined` for formats not in `formatMap` (e.g. `int64`, `date-time`),
- * which are handled separately because their output depends on parser options.
+ * Returns the Kubb `SchemaType` for a given OAS `format` string, or `null` if not found.
+ * Formats not in `formatMap` (e.g., `int64`, `date-time`) are handled separately by parser options.
  */
 export function getSchemaType(format: string): ast.SchemaType | null {
   return formatMap[format as keyof typeof formatMap] ?? null
 }
 
 /**
- * Maps an OAS primitive type string to its `PrimitiveSchemaType` equivalent.
- * Numeric types (`number`, `integer`, `bigint`) are returned unchanged;
- * `boolean` maps to `'boolean'`; everything else defaults to `'string'`.
+ * 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'`.
  */
 export function getPrimitiveType(type: string | undefined): ast.PrimitiveSchemaType {
   if (type === 'number' || type === 'integer' || type === 'bigint') return type
@@ -67,8 +64,7 @@ export function getPrimitiveType(type: string | undefined): ast.PrimitiveSchemaT
 }
 
 /**
- * Narrows a raw content-type string to the `MediaType` union recognized by Kubb.
- * Returns `undefined` for content types not present in `KNOWN_MEDIA_TYPES`.
+ * 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
@@ -79,11 +75,9 @@ export type OperationsOptions = {
 }
 
 /**
- * Returns all resolved parameters for an operation, merging path-level and operation-level entries.
- *
- * Operation-level parameters take precedence over path-level ones with the same `in:name` key.
- * `$ref` parameters are resolved via `dereferenceWithRef` to restore backward compatibility
- * with `oas` v31+ which otherwise filters them out.
+ * Returns all parameters for an operation, merging path-level and operation-level entries.
+ * Operation-level parameters override path-level ones with the same `in:name` key.
+ * `$ref` parameters resolve via `dereferenceWithRef` for backward compatibility.
  *
  * @example
  * ```ts
@@ -184,7 +178,7 @@ export function getResponseSchema(document: Document, operation: Operation, stat
 }
 
 /**
- * Returns the request body schema for an operation, or `undefined` when absent.
+ * Returns the request body schema for an operation, or `null` when absent.
  *
  * @example
  * ```ts
@@ -217,9 +211,7 @@ export function getRequestSchema(document: Document, operation: Operation, optio
 type SchemaSourceMode = 'schemas' | 'responses' | 'requestBodies'
 
 /**
- * A schema annotated with the component section it came from and its original name.
- *
- * Used during cross-source name-collision resolution in `resolveNameCollisions`.
+ * A schema annotated with its component section source and original name. Used by `resolveNameCollisions` for cross-source collision resolution.
  */
 export type SchemaWithMetadata = {
   schema: SchemaObject

package/src/types.ts

@@ -18,19 +18,19 @@ import type { OpenAPIV3 } from 'openapi-types'
 export type { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types'
 
 /**
- * Content-type string used when selecting request/response schemas from a spec.
- *
- * Accepts `'application/json'` or any arbitrary media type string.
+ * Content-type string for selecting request/response schemas from an OpenAPI spec.
+ * Supports `'application/json'` or any other media type.
  *
  * @example
  * ```ts
- * const ct: contentType = 'application/vnd.api+json'
+ * const ct: ContentType = 'application/vnd.api+json'
  * ```
  */
 export type ContentType = 'application/json' | (string & {})
 
 /**
- * Augments `oas`'s `SchemaObject` with OAS 3.1 / JSON Schema fields the parser needs.
+ * Extended OpenAPI 3.0 schema object that includes OpenAPI 3.1 and JSON Schema fields.
+ * The parser uses these additional fields to handle newer spec versions.
  *
  * @example
  * ```ts
@@ -74,7 +74,7 @@ export type SchemaObject = OASSchemaObject & {
 }
 
 /**
- * Uppercase → lowercase HTTP method map, re-exported for backwards compatibility.
+ * Maps uppercase HTTP method names to lowercase for backwards compatibility.
  *
  * @example
  * ```ts
@@ -88,45 +88,43 @@ export const HttpMethods = Object.fromEntries(Object.entries(ast.httpMethods).ma
 >
 
 /**
- * Lowercase HTTP method string as used by the `oas` package (`'get' | 'post' | ...`).
+ * HTTP method as a lowercase string (`'get' | 'post' | ...`).
  */
 export type HttpMethod = Lowercase<ast.HttpMethod>
 
 /**
- * Normalized OpenAPI document type used throughout the adapter.
+ * Normalized OpenAPI document after parsing.
  */
 export type Document = OASDocument
 
 /**
- * Operation wrapper type returned by the `oas` package.
+ * API operation extracted from an OpenAPI document.
  */
 export type Operation = OASOperation
 
 /**
- * OpenAPI `discriminator` object attached to a `oneOf`/`anyOf` schema.
+ * Discriminator object for `oneOf`/`anyOf` schemas in OpenAPI.
  */
 export type DiscriminatorObject = OASDiscriminatorObject
 
 /**
- * OpenAPI `$ref` pointer object (`{ $ref: string }`).
+ * OpenAPI reference object pointing to a schema definition via `$ref`.
  */
 export type ReferenceObject = OpenAPIV3.ReferenceObject
 
 /**
- * OpenAPI response object type (may contain `content`, `description`, `headers`).
+ * OpenAPI response object from a spec that contains schema, status code, and headers.
  */
 export type ResponseObject = OASResponseObject
 
 /**
- * OpenAPI media type object that maps a content-type to a schema.
+ * OpenAPI media type object that maps a content-type string to its schema.
  */
 export type MediaTypeObject = OASMediaTypeObject
 
 /**
- * User-facing options for `adapterOas(...)`.
- *
- * Extends `ParserOptions` from `@kubb/ast` with adapter-specific controls
- * like spec validation and server URL selection.
+ * Configuration options for the OpenAPI adapter.
+ * Controls spec validation, content-type selection, and server URL resolution.
  *
  * @example
  * ```ts
@@ -176,7 +174,7 @@ export type AdapterOasOptions = {
 } & Partial<ast.ParserOptions>
 
 /**
- * Resolved adapter options available at runtime after defaults have been applied.
+ * Adapter options after defaults have been applied and schema name collisions resolved.
  */
 export type AdapterOasResolvedOptions = {
   validate: boolean