@kubb/adapter-oas 5.0.0-beta.63 → 5.0.0-beta.65

package/src/schemaDiagnostics.ts

@@ -1,76 +0,0 @@
-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}`)
-    }
-  }
-}

package/src/stream.ts

@@ -1,221 +0,0 @@
-import { findCircularSchemas } from '@kubb/ast/utils'
-import { ast } from '@kubb/core'
-import type { Plan } from './dedupe.ts'
-import { oasDialect } from './dialect.ts'
-import { buildDiscriminatorChildMap, patchDiscriminatorNode } from './discriminator.ts'
-import { getOperations } from './operation.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'
-
-export type PreScanResult = {
-  refAliasMap: Map<string, ast.SchemaNode>
-  enumNames: Array<string>
-  circularNames: Array<string>
-  discriminatorChildMap: Map<string, DiscriminatorTarget> | null
-  dedupePlan: Plan | null
-}
-
-/**
- * Reads the server URL from the document's `servers` array at `serverIndex`,
- * interpolating any `serverVariables` into the URL template.
- *
- * Returns `null` when `serverIndex` is omitted or out of range.
- *
- * @example Resolve the first server
- * `resolveBaseUrl({ document, serverIndex: 0 })`
- *
- * @example Override a path variable
- * `resolveBaseUrl({ document, serverIndex: 0, serverVariables: { version: 'v2' } })`
- */
-export function resolveBaseUrl({
-  document,
-  serverIndex,
-  serverVariables,
-}: {
-  document: Document
-  serverIndex?: number
-  serverVariables?: Record<string, string>
-}): string | null {
-  const server = serverIndex !== undefined ? document.servers?.at(serverIndex) : undefined
-  return server?.url ? resolveServerUrl(server, serverVariables) : null
-}
-
-/**
- * Parses every schema once to build the lookup structures that streaming needs upfront.
- *
- * Three things happen in this single pass:
- * - `refAliasMap` records schemas that are pure `$ref` aliases so the streaming pass can inline them.
- * - `enumNames` collects the names of every enum schema so plugins skip re-scanning the stream.
- * - `circularNames` runs cycle detection, which requires all nodes in memory simultaneously.
- *   The `allNodes` array is local and drops out of scope as soon as this function returns.
- *
- * 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.
- * Holding the parsed nodes in memory here would defeat the streaming memory benefit.
- *
- * @example
- * ```ts
- * const { refAliasMap, enumNames, circularNames } = preScan({
- *   schemas,
- *   parseSchema,
- *   parserOptions,
- *   discriminator: 'strict',
- * })
- * ```
- */
-export function preScan({
-  schemas,
-  parseSchema,
-  parseOperation,
-  document,
-  parserOptions,
-  discriminator,
-  dedupe,
-}: {
-  schemas: Record<string, SchemaObject>
-  parseSchema: (entry: { schema: SchemaObject; name: string }, options: ast.ParserOptions) => ast.SchemaNode
-  parseOperation: SchemaParser['parseOperation']
-  document: Document
-  parserOptions: ast.ParserOptions
-  discriminator: AdapterOas['options']['discriminator']
-  dedupe: boolean
-}): PreScanResult {
-  const allNodes: Array<ast.SchemaNode> = []
-  const refAliasMap = new Map<string, ast.SchemaNode>()
-  const enumNames: Array<string> = []
-  const discriminatorParentNodes: Array<ast.SchemaNode> = []
-
-  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)
-    }
-    if (ast.narrowSchema(node, ast.schemaTypes.enum) && node.name) {
-      enumNames.push(node.name)
-    }
-    if (discriminator === 'inherit' && (schema.oneOf ?? schema.anyOf) && schema.discriminator?.propertyName) {
-      discriminatorParentNodes.push(node)
-    }
-  }
-
-  const circularNames = [...findCircularSchemas(allNodes)]
-  const discriminatorChildMap = discriminatorParentNodes.length > 0 ? buildDiscriminatorChildMap(discriminatorParentNodes) : null
-
-  let dedupePlan: Plan | 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.
-    const operationNodes: Array<ast.OperationNode> = []
-    for (const operation of getOperations(document)) {
-      const operationNode = parseOperation(parserOptions, operation)
-      if (operationNode) operationNodes.push(operationNode)
-    }
-
-    const circularSchemas = new Set(circularNames)
-    const usedNames = new Set(Object.keys(schemas))
-
-    dedupePlan = oasDialect.dedupe.plan([...allNodes, ...operationNodes], { circularSchemas, usedNames })
-
-    for (const definition of dedupePlan.extracted) {
-      if (definition.type === 'enum' && definition.name) enumNames.push(definition.name)
-    }
-  }
-
-  // Enum names that duplicate an earlier schema's content are never emitted, so they are not
-  // advertised to plugins either.
-  const emittedEnumNames = dedupePlan ? enumNames.filter((name) => !dedupePlan.isAlias(name)) : enumNames
-
-  return { refAliasMap, enumNames: emittedEnumNames, circularNames, discriminatorChildMap, dedupePlan }
-}
-
-/**
- * Creates a lazy `InputNode<true>` from already-resolved adapter state.
- *
- * The schema and operation iterables each start a fresh parse pass on every
- * `[Symbol.asyncIterator]()` call. This lets multiple plugins consume the same
- * stream object independently without sharing a cursor or holding all nodes in memory.
- *
- * Ref aliases in `refAliasMap` are inlined during iteration: an alias entry is replaced
- * with its target's parsed node (but keeps the alias name) so plugins never receive bare `ref` nodes.
- *
- * @example
- * ```ts
- * const streamNode = createInputStream({ schemas, parseSchema, parseOperation, document, parserOptions, refAliasMap, discriminatorChildMap, meta })
- * for await (const schema of streamNode.schemas) {
- *   // each call to for-await restarts from the first schema
- * }
- * ```
- */
-export function createInputStream({
-  schemas,
-  parseSchema,
-  parseOperation,
-  document,
-  parserOptions,
-  refAliasMap,
-  discriminatorChildMap,
-  dedupePlan,
-  meta,
-}: {
-  schemas: Record<string, SchemaObject>
-  parseSchema: SchemaParser['parseSchema']
-  parseOperation: SchemaParser['parseOperation']
-  document: Document
-  parserOptions: ast.ParserOptions
-  refAliasMap: Map<string, ast.SchemaNode>
-  discriminatorChildMap: Map<string, DiscriminatorTarget> | null
-  dedupePlan: Plan | null
-  meta: ast.InputMeta
-}): ast.InputNode<true> {
-  const schemasIterable: AsyncIterable<ast.SchemaNode> = {
-    [Symbol.asyncIterator]() {
-      return (async function* () {
-        // Extracted shared definitions are emitted first so the schema list owns the shared shapes.
-        if (dedupePlan) {
-          for (const definition of dedupePlan.extracted) yield definition
-        }
-
-        for (const [name, schema] of Object.entries(schemas)) {
-          // A top-level schema whose content duplicates an earlier one is not emitted: every
-          // ref to it is repointed at the first schema with that content, so its model would
-          // be dead code.
-          if (dedupePlan?.isAlias(name)) continue
-
-          // Inline ref aliases: replace the alias entry with its target's parsed node
-          // (keeping the alias name). Skip the first parse entirely for alias entries
-          // since that result is never used.
-          const alias = refAliasMap.get(name)
-          if (alias?.name && schemas[alias.name]) {
-            const aliasNode = { ...parseSchema({ schema: schemas[alias.name]!, name: alias.name }, parserOptions), name }
-            yield dedupePlan ? dedupePlan.applyTopLevel(aliasNode) : aliasNode
-            continue
-          }
-
-          const parsed = parseSchema({ schema, name }, parserOptions)
-          const node = discriminatorChildMap?.get(name) ? patchDiscriminatorNode(parsed, discriminatorChildMap.get(name)!) : parsed
-          yield dedupePlan ? dedupePlan.applyTopLevel(node) : node
-        }
-      })()
-    },
-  }
-
-  const operationsIterable: AsyncIterable<ast.OperationNode> = {
-    [Symbol.asyncIterator]() {
-      return (async function* () {
-        for (const operation of getOperations(document)) {
-          const node = parseOperation(parserOptions, operation)
-          if (node) yield dedupePlan ? dedupePlan.apply(node) : node
-        }
-      })()
-    },
-  }
-
-  return ast.factory.createInput({ stream: true, schemas: schemasIterable, operations: operationsIterable, meta })
-}

package/src/types.ts

@@ -1,235 +0,0 @@
-import type { AdapterFactoryOptions } from '@kubb/core'
-import type { ast } from '@kubb/core'
-import type { JSONSchema4, JSONSchema6, JSONSchema7 } from 'json-schema'
-import type { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types'
-import type { Operation } from './operation.ts'
-
-export type { Operation }
-
-/**
- * Media type used to pick a schema from an operation's request or response.
- *
- * @example
- * ```ts
- * const ct: ContentType = 'application/vnd.api+json'
- * ```
- */
-export type ContentType = 'application/json' | (string & {})
-
-/**
- * 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
- * const schema: SchemaObject = {
- *   type: 'string',
- *   const: 'dog',
- *   contentMediaType: 'application/octet-stream',
- * }
- * ```
- */
-export type SchemaObject = {
-  externalDocs?: unknown
-  xml?: unknown
-  $schema?: string
-  deprecated?: boolean
-  example?: unknown
-  examples?: Array<unknown>
-  nullable?: boolean
-  readOnly?: boolean
-  writeOnly?: boolean
-  discriminator?: DiscriminatorObject
-  'x-readme-ref-name'?: string
-  /**
-   * OAS 3.0 vendor extension: marks a schema as nullable without using `type: ['null', ...]`.
-   */
-  'x-nullable'?: boolean
-  /**
-   * OAS 3.1: constrains the schema to a single fixed value (equivalent to a one-item `enum`).
-   */
-  const?: string | number | boolean | null
-  /**
-   * OAS 3.1: media type of the schema content. `'application/octet-stream'` on a `string` schema maps to `blob`.
-   */
-  contentMediaType?: string
-  $ref?: string
-  /**
-   * OAS 3.1: positional tuple items, replacing the multi-item `items` array from OAS 3.0.
-   */
-  prefixItems?: Array<SchemaObject | ReferenceObject>
-  /**
-   * JSON Schema: maps regex patterns to sub-schemas for validating additional properties.
-   */
-  patternProperties?: Record<string, SchemaObject | boolean>
-  /**
-   * Single-schema form of `items`. Narrowed from the base type to take precedence over the tuple overload.
-   */
-  items?: SchemaObject | ReferenceObject
-  /**
-   * Allowed values for this schema.
-   */
-  enum?: Array<string | number | boolean | null>
-} & (OpenAPIV3.SchemaObject | OpenAPIV3_1.SchemaObject | JSONSchema4 | JSONSchema6 | JSONSchema7)
-
-/**
- * HTTP method in the lowercase form an OpenAPI path item uses for its keys.
- */
-export type HttpMethod = Lowercase<ast.HttpMethod>
-
-/**
- * Normalized OpenAPI document after parsing.
- */
-export type Document = (OpenAPIV3.Document | OpenAPIV3_1.Document) & Record<string, unknown>
-
-/**
- * Single operation object (the `get`/`post`/… entry on a path item) plus any vendor extensions.
- */
-export type OperationObject = (OpenAPIV3.OperationObject | OpenAPIV3_1.OperationObject) & Record<string, unknown>
-
-/**
- * Path item object holding the operations and shared parameters for a single URL path.
- */
-export type PathItemObject = OpenAPIV3.PathItemObject | OpenAPIV3_1.PathItemObject
-
-/**
- * Discriminator object for `oneOf`/`anyOf` schemas in OpenAPI.
- */
-export type DiscriminatorObject = OpenAPIV3.DiscriminatorObject | OpenAPIV3_1.DiscriminatorObject
-
-/**
- * OpenAPI reference object pointing to a schema definition via `$ref`.
- */
-export type ReferenceObject = OpenAPIV3.ReferenceObject
-
-/**
- * OpenAPI response object holding the content and headers for one status code.
- */
-export type ResponseObject = OpenAPIV3.ResponseObject | OpenAPIV3_1.ResponseObject
-
-/**
- * OpenAPI request body object that maps content types to their media type objects.
- */
-export type RequestBodyObject = OpenAPIV3.RequestBodyObject | OpenAPIV3_1.RequestBodyObject
-
-/**
- * OpenAPI media type object that maps a content-type string to its schema.
- */
-export type MediaTypeObject = OpenAPIV3.MediaTypeObject | OpenAPIV3_1.MediaTypeObject
-
-/**
- * OpenAPI parameter object, narrowed so `in` is always one of the four valid locations.
- */
-export type ParameterObject = {
-  in: 'cookie' | 'header' | 'path' | 'query'
-} & (OpenAPIV3.ParameterObject | OpenAPIV3_1.ParameterObject)
-
-/**
- * OpenAPI server object describing a base URL and its `{variable}` substitutions.
- */
-export type ServerObject = OpenAPIV3.ServerObject | OpenAPIV3_1.ServerObject
-
-/**
- * Configuration for the OpenAPI adapter: spec validation, content-type selection,
- * server URL resolution, and how schema types are derived.
- *
- * @example
- * ```ts
- * adapterOas({
- *   validate: false,
- *   dateType: 'date',
- *   serverIndex: 0,
- *   serverVariables: { env: 'prod' },
- * })
- * ```
- */
-export type AdapterOasOptions = {
-  /**
-   * Validate the OpenAPI spec with `@readme/openapi-parser` before parsing.
-   * Set to `false` only when you have a known-invalid spec you still want to
-   * generate from.
-   *
-   * @default true
-   */
-  validate?: boolean
-  /**
-   * Preferred media type when an operation defines several. Defaults to the
-   * first JSON-compatible media type found in the spec.
-   */
-  contentType?: ContentType
-  /**
-   * Index into the `servers` array from your OpenAPI spec. Used to compute the
-   * base URL for plugins that need it. Most projects pick `0` for the primary
-   * server. Omit to leave `baseURL` undefined.
-   */
-  serverIndex?: number
-  /**
-   * Override values for `{variable}` placeholders in the selected server URL.
-   * Only used when `serverIndex` is set. Variables you do not provide use
-   * their `default` value from the spec.
-   *
-   * @example
-   * ```ts
-   * // spec server: "https://api.{env}.example.com"
-   * serverVariables: { env: 'prod' }
-   * // → baseURL: "https://api.prod.example.com"
-   * ```
-   */
-  serverVariables?: Record<string, string>
-  /**
-   * How the `discriminator` field on `oneOf`/`anyOf` schemas is interpreted.
-   * - `'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
-   *   value into each child schema, so each branch's discriminator field is
-   *   precisely typed.
-   *
-   * @default 'strict'
-   */
-  discriminator?: 'strict' | 'inherit'
-  /**
-   * 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, so documentation such as
-   * `description` and `example` is ignored. Set to `false` to keep every occurrence inline
-   * and produce byte-for-byte identical output to earlier versions.
-   *
-   * @default true
-   */
-  dedupe?: boolean
-} & Partial<ast.ParserOptions>
-
-/**
- * Adapter options after defaults have been applied and schema name collisions resolved.
- */
-export type AdapterOasResolvedOptions = {
-  validate: boolean
-  contentType: AdapterOasOptions['contentType']
-  serverIndex: AdapterOasOptions['serverIndex']
-  serverVariables: AdapterOasOptions['serverVariables']
-  discriminator: NonNullable<AdapterOasOptions['discriminator']>
-  dedupe: NonNullable<AdapterOasOptions['dedupe']>
-  dateType: NonNullable<AdapterOasOptions['dateType']>
-  integerType: NonNullable<AdapterOasOptions['integerType']>
-  unknownType: NonNullable<AdapterOasOptions['unknownType']>
-  emptySchemaType: NonNullable<AdapterOasOptions['emptySchemaType']>
-  enumSuffix: AdapterOasOptions['enumSuffix']
-  /**
-   * Map from original `$ref` paths to their collision-resolved schema names.
-   * Populated once the adapter resolves a spec's schemas, on the first `stream()` or `parse()`.
-   *
-   * @example
-   * ```ts
-   * nameMapping.get('#/components/schemas/Order') // 'Order'
-   * nameMapping.get('#/components/responses/Order') // 'OrderResponse'
-   * ```
-   */
-  nameMapping: Map<string, string>
-}
-
-/**
- * `@kubb/core` adapter factory type for the OpenAPI adapter.
- */
-export type AdapterOas = AdapterFactoryOptions<'oas', AdapterOasOptions, AdapterOasResolvedOptions, Document>