@kubb/adapter-oas 5.0.0-alpha.9 → 5.0.0-beta.2

package/src/oas/types.ts

@@ -1,71 +0,0 @@
-// external packages
-import type { Operation as OASOperation } from 'oas/operation'
-import type {
-  DiscriminatorObject as OASDiscriminatorObject,
-  OASDocument,
-  HttpMethods as OASHttpMethods,
-  MediaTypeObject as OASMediaTypeObject,
-  ResponseObject as OASResponseObject,
-  SchemaObject as OASSchemaObject,
-} from 'oas/types'
-import type { OpenAPIV3 } from 'openapi-types'
-
-export type { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types'
-
-export type contentType = 'application/json' | (string & {})
-
-export type SchemaObject = OASSchemaObject & {
-  /**
-   * OAS 3.1 extension: allows marking a schema as nullable even when `type` does not include `'null'`.
-   */
-  'x-nullable'?: boolean
-  /**
-   * OAS 3.1: constrains the schema to a single fixed value.
-   * Semantically equivalent to a one-item `enum`.
-   */
-  const?: string | number | boolean | null
-  /**
-   * OAS 3.1: specifies the media type of the schema content.
-   * When set to `'application/octet-stream'` on a `string` schema, the schema is treated as binary (`blob`).
-   */
-  contentMediaType?: string
-  $ref?: string
-  /**
-   * OAS 3.1 / JSON Schema: positional items in a tuple schema.
-   * Replaces the OAS 3.0 multi-item `items` array syntax.
-   */
-  prefixItems?: Array<SchemaObject | ReferenceObject>
-  /**
-   * JSON Schema: maps regex patterns to sub-schemas for additional property validation.
-   */
-  patternProperties?: Record<string, SchemaObject | boolean>
-  /**
-   * OAS 3.0 / JSON Schema: single-schema form.
-   * The OAS base type already includes this, but we re-declare it here to ensure
-   * the single-schema overload takes precedence over the multi-schema tuple form.
-   */
-  items?: SchemaObject | ReferenceObject
-  /**
-   * Enum values for this schema (narrowed from `unknown[]` in the base type).
-   */
-  enum?: Array<string | number | boolean | null>
-}
-
-/**
- * Re-exported from `constants.ts` for backwards compatibility.
- */
-export { httpMethods as HttpMethods } from '../constants.ts'
-
-export type HttpMethod = OASHttpMethods
-
-export type Document = OASDocument
-
-export type Operation = OASOperation
-
-export type DiscriminatorObject = OASDiscriminatorObject
-
-export type ReferenceObject = OpenAPIV3.ReferenceObject
-
-export type ResponseObject = OASResponseObject
-
-export type MediaTypeObject = OASMediaTypeObject

package/src/oas/utils.ts

@@ -1,402 +0,0 @@
-import path from 'node:path'
-import { pascalCase, URLPath } from '@internals/utils'
-import type { Config } from '@kubb/core'
-import { bundle, loadConfig } from '@redocly/openapi-core'
-import yaml from '@stoplight/yaml'
-import { isRef } from 'oas/types'
-import OASNormalize from 'oas-normalize'
-import type { OpenAPIV2, OpenAPIV3, OpenAPIV3_1 } from 'openapi-types'
-import { isPlainObject, mergeDeep } from 'remeda'
-import swagger2openapi from 'swagger2openapi'
-import { MERGE_DEFAULT_TITLE, MERGE_DEFAULT_VERSION, MERGE_OPENAPI_VERSION, structuralKeys } from '../constants.ts'
-import { Oas } from './Oas.ts'
-import type { contentType, Document, SchemaObject } from './types.ts'
-
-/**
- * Narrows `doc` to a Swagger 2.0 document.
- * Swagger 2.0 documents do not have an `openapi` version key.
- */
-export function isOpenApiV2Document(doc: unknown): doc is OpenAPIV2.Document {
-  return !!doc && isPlainObject(doc) && !('openapi' in doc)
-}
-
-/**
- * Narrows `doc` to an OpenAPI 3.x document.
- * Any document that has an `openapi` key is considered 3.x (including 3.1).
- */
-export function isOpenApiV3Document(doc: unknown): doc is OpenAPIV3.Document {
-  return !!doc && isPlainObject(doc) && 'openapi' in doc
-}
-
-/**
- * Narrows `doc` to an OpenAPI 3.1 document by checking the version prefix.
- */
-export function isOpenApiV3_1Document(doc: unknown): doc is OpenAPIV3_1.Document {
-  return !!doc && isPlainObject(doc) && 'openapi' in (doc as object) && (doc as { openapi: string }).openapi.startsWith('3.1')
-}
-
-/**
- * Returns `true` when a schema should be treated as nullable.
- *
- * Covers three nullable signals across OAS versions:
- * - OAS 3.0: `nullable: true` or the vendor extension `x-nullable: true`.
- * - OAS 3.1 / JSON Schema: `type: 'null'` or `type: ['null', ...]` (multi-type array).
- */
-export function isNullable(schema?: SchemaObject & { 'x-nullable'?: boolean }): boolean {
-  const explicitNullable = schema?.nullable ?? schema?.['x-nullable']
-  if (explicitNullable === true) return true
-
-  const schemaType = schema?.type
-  if (schemaType === 'null') return true
-  if (Array.isArray(schemaType)) return schemaType.includes('null')
-
-  return false
-}
-
-/**
- * Narrows `obj` to an OpenAPI `$ref` pointer object.
- * Delegates to the `oas` package's own `isRef` helper.
- */
-export function isReference(obj?: unknown): obj is OpenAPIV3.ReferenceObject | OpenAPIV3_1.ReferenceObject {
-  return !!obj && isRef(obj as object)
-}
-
-/**
- * Returns `true` when `obj` is a schema that carries a structured OAS 3.x `discriminator`
- * object — as opposed to a plain-string discriminator found in some Swagger 2 specs.
- */
-export function isDiscriminator(obj?: unknown): obj is SchemaObject & { discriminator: OpenAPIV3.DiscriminatorObject } {
-  const record = obj as Record<string, unknown>
-  return !!obj && !!record['discriminator'] && typeof record['discriminator'] !== 'string'
-}
-
-/**
- * Loads, dereferences, and wraps a raw OpenAPI document into an `Oas` instance.
- *
- * When given a file path string with `canBundle: true` (the default), Redocly's
- * bundler resolves all external `$ref`s first. Swagger 2.0 documents are
- * automatically up-converted to OpenAPI 3.0 via `swagger2openapi`.
- */
-export async function parse(
-  pathOrApi: string | Document,
-  { oasClass = Oas, canBundle = true, enablePaths = true }: { oasClass?: typeof Oas; canBundle?: boolean; enablePaths?: boolean } = {},
-): Promise<Oas> {
-  if (typeof pathOrApi === 'string' && canBundle) {
-    const config = await loadConfig()
-    const bundleResults = await bundle({ ref: pathOrApi, config, base: pathOrApi })
-
-    return parse(bundleResults.bundle.parsed as string, { oasClass, canBundle, enablePaths })
-  }
-
-  const oasNormalize = new OASNormalize(pathOrApi, {
-    enablePaths,
-    colorizeErrors: true,
-  })
-  const document = (await oasNormalize.load()) as Document
-
-  if (isOpenApiV2Document(document)) {
-    const { openapi } = await swagger2openapi.convertObj(document, {
-      anchors: true,
-    })
-
-    return new oasClass(openapi as Document)
-  }
-
-  return new oasClass(document)
-}
-
-/**
- * Deep-merges multiple OpenAPI documents into a single `Oas` instance.
- *
- * Each document is parsed independently (without path dereferencing) and then
- * recursively merged using `remeda`'s `mergeDeep`. The result is re-parsed so
- * the returned `Oas` instance is fully initialized.
- *
- * Throws when the input array is empty — at least one document is required.
- */
-export async function merge(pathOrApi: Array<string | Document>, { oasClass = Oas }: { oasClass?: typeof Oas } = {}): Promise<Oas> {
-  const instances = await Promise.all(pathOrApi.map((p) => parse(p, { oasClass, enablePaths: false, canBundle: false })))
-
-  if (instances.length === 0) {
-    throw new Error('No OAS instances provided for merging.')
-  }
-
-  const seed: Document = {
-    openapi: MERGE_OPENAPI_VERSION,
-    info: { title: MERGE_DEFAULT_TITLE, version: MERGE_DEFAULT_VERSION },
-    paths: {},
-    components: { schemas: {} },
-  } as Document
-
-  const merged = instances.reduce((acc, current) => mergeDeep(acc, current.document as Document), seed)
-
-  return parse(merged, { oasClass })
-}
-
-/**
- * Constructs an `Oas` instance from a Kubb `Config` object.
- *
- * Handles all three input forms supported by `Config`:
- * - `data` — an inline YAML string, JSON string, or pre-parsed object.
- * - Array — multiple file paths that are deep-merged via {@link merge}.
- * - `path` — a local file path or a remote URL.
- */
-export function parseFromConfig(config: Config, oasClass: typeof Oas = Oas): Promise<Oas> {
-  if ('data' in config.input) {
-    if (typeof config.input.data === 'object') {
-      return parse(structuredClone(config.input.data) as Document, { oasClass })
-    }
-
-    try {
-      const api: string = yaml.parse(config.input.data as string)
-      return parse(api, { oasClass })
-    } catch {
-      return parse(config.input.data as string, { oasClass })
-    }
-  }
-
-  if (Array.isArray(config.input)) {
-    return merge(
-      config.input.map((input) => path.resolve(config.root, input.path)),
-      { oasClass },
-    )
-  }
-
-  if (new URLPath(config.input.path).isURL) {
-    return parse(config.input.path, { oasClass })
-  }
-
-  return parse(path.resolve(config.root, config.input.path), { oasClass })
-}
-
-/**
- * Flattens a single-member or keyword-only `allOf` into its parent schema.
- *
- * Flattening is only performed when every `allOf` member is a "plain fragment" —
- * i.e. contains no structural composition keywords (see `structuralKeys`) and no
- * `$ref`. When any member carries structural meaning, the schema is returned unchanged.
- *
- * Keyword values from allOf members are merged into the parent on a first-write basis:
- * outer schema values always win over fragment values.
- */
-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 merged: SchemaObject = { ...schema }
-  delete merged.allOf
-
-  for (const fragment of schema.allOf as SchemaObject[]) {
-    for (const [key, value] of Object.entries(fragment)) {
-      if (merged[key as keyof typeof merged] === undefined) {
-        merged[key as keyof typeof merged] = value
-      }
-    }
-  }
-
-  return merged
-}
-
-/**
- * Validates an OpenAPI document using `oas-normalize`.
- * Enables path validation and colorized error output.
- */
-export async function validate(document: Document) {
-  const oasNormalize = new OASNormalize(document, {
-    enablePaths: true,
-    colorizeErrors: true,
-  })
-
-  return oasNormalize.validate({
-    parser: {
-      validate: {
-        errors: { colorize: true },
-      },
-    },
-  })
-}
-
-/**
- * Discriminates the three component sources Kubb reads schemas from.
- */
-type SchemaSourceMode = 'schemas' | 'responses' | 'requestBodies'
-
-export type SchemaWithMetadata = {
-  schema: SchemaObject
-  source: SchemaSourceMode
-  originalName: string
-}
-
-type GetSchemasResult = {
-  schemas: Record<string, SchemaObject>
-  nameMapping: Map<string, string>
-}
-
-/**
- * Walks a schema tree and collects the names of all `#/components/schemas/<name>` refs.
- * Used by `sortSchemas` to build the dependency graph.
- */
-function collectRefs(schema: unknown, refs = new Set<string>()): Set<string> {
-  if (Array.isArray(schema)) {
-    for (const item of schema) collectRefs(item, refs)
-    return refs
-  }
-
-  if (schema && typeof schema === 'object') {
-    for (const [key, value] of Object.entries(schema)) {
-      if (key === '$ref' && typeof value === 'string') {
-        const match = value.match(/^#\/components\/schemas\/(.+)$/)
-        if (match) refs.add(match[1]!)
-      } else {
-        collectRefs(value, refs)
-      }
-    }
-  }
-
-  return refs
-}
-
-/**
- * Returns a copy of `schemas` topologically sorted by `$ref` dependency.
- *
- * Schemas with no references come first; schemas that are referenced by others
- * come before those that reference them. This ensures code generators emit
- * referenced types before the types that depend on them.
- *
- * Cycles are silently skipped via the `stack` guard inside `visit`.
- */
-export function sortSchemas(schemas: Record<string, SchemaObject>): Record<string, SchemaObject> {
-  const deps = new Map<string, string[]>()
-
-  for (const [name, schema] of Object.entries(schemas)) {
-    deps.set(name, Array.from(collectRefs(schema)))
-  }
-
-  const sorted: string[] = []
-  const visited = new Set<string>()
-
-  function visit(name: string, stack: Set<string>) {
-    if (visited.has(name) || stack.has(name)) return
-    stack.add(name)
-    for (const child of deps.get(name) ?? []) {
-      if (deps.has(child)) visit(child, stack)
-    }
-    stack.delete(name)
-    visited.add(name)
-    sorted.push(name)
-  }
-
-  for (const name of Object.keys(schemas)) {
-    visit(name, new Set())
-  }
-
-  const result: Record<string, SchemaObject> = {}
-  for (const name of sorted) result[name] = schemas[name]!
-  return result
-}
-
-/**
- * Extracts the inline schema from a media-type `content` map.
- *
- * Prefers `preferredContentType` when provided; otherwise falls back to the
- * first key in the map. Returns `null` when:
- * - `content` is absent.
- * - The target content-type has no `schema` entry.
- * - The schema is a `$ref` (callers resolve refs separately).
- */
-export function extractSchemaFromContent(content: Record<string, unknown> | undefined, preferredContentType?: contentType): SchemaObject | null {
-  if (!content) return null
-
-  const firstContentType = Object.keys(content)[0] ?? 'application/json'
-  const targetContentType = preferredContentType ?? firstContentType
-  const contentSchema = content[targetContentType] as { schema?: SchemaObject } | undefined
-  const schema = contentSchema?.schema
-
-  if (schema && '$ref' in schema) return null
-  return schema ?? null
-}
-
-/**
- * Returns the PascalCase suffix appended to a component name when resolving
- * cross-source name collisions (schemas vs. responses vs. requestBodies).
- */
-function getSemanticSuffix(source: SchemaSourceMode): string {
-  switch (source) {
-    case 'schemas':
-      return 'Schema'
-    case 'responses':
-      return 'Response'
-    case 'requestBodies':
-      return 'Request'
-  }
-}
-
-/**
- * Builds `GetSchemasResult` without any collision detection.
- * Each schema is registered under its original component name and its full
- * `#/components/<source>/<name>` ref path.
- */
-export function legacyResolve(schemasWithMeta: SchemaWithMetadata[]): GetSchemasResult {
-  const schemas: Record<string, SchemaObject> = {}
-  const nameMapping = new Map<string, string>()
-
-  for (const item of schemasWithMeta) {
-    schemas[item.originalName] = item.schema
-    nameMapping.set(`#/components/${item.source}/${item.originalName}`, item.originalName)
-  }
-
-  return { schemas, nameMapping }
-}
-
-/**
- * Builds `GetSchemasResult` with automatic name-collision resolution.
- *
- * When two or more schemas normalize to the same PascalCase name:
- * - If they share the same source, a numeric suffix (`2`, `3`, …) is appended.
- * - If they come from different sources (schemas / responses / requestBodies),
- *   a semantic suffix (`Schema`, `Response`, `Request`) is appended.
- *
- * Non-colliding schemas are left unchanged.
- */
-export function resolveCollisions(schemasWithMeta: SchemaWithMetadata[]): GetSchemasResult {
-  const schemas: Record<string, SchemaObject> = {}
-  const nameMapping = new Map<string, string>()
-  const normalizedNames = new Map<string, SchemaWithMetadata[]>()
-
-  for (const item of schemasWithMeta) {
-    const normalized = pascalCase(item.originalName)
-    const bucket = normalizedNames.get(normalized) ?? []
-    bucket.push(item)
-    normalizedNames.set(normalized, bucket)
-  }
-
-  for (const [, items] of normalizedNames) {
-    if (items.length === 1) {
-      const item = items[0]!
-      schemas[item.originalName] = item.schema
-      nameMapping.set(`#/components/${item.source}/${item.originalName}`, item.originalName)
-      continue
-    }
-
-    const sources = new Set(items.map((item) => item.source))
-
-    if (sources.size === 1) {
-      items.forEach((item, index) => {
-        const uniqueName = item.originalName + (index === 0 ? '' : (index + 1).toString())
-        schemas[uniqueName] = item.schema
-        nameMapping.set(`#/components/${item.source}/${item.originalName}`, uniqueName)
-      })
-    } else {
-      items.forEach((item) => {
-        const uniqueName = item.originalName + getSemanticSuffix(item.source)
-        schemas[uniqueName] = item.schema
-        nameMapping.set(`#/components/${item.source}/${item.originalName}`, uniqueName)
-      })
-    }
-  }
-
-  return { schemas, nameMapping }
-}

package/src/utils.ts

@@ -1,168 +0,0 @@
-import { collect, createProperty, createSchema, narrowSchema } from '@kubb/ast'
-import type { SchemaNode } from '@kubb/ast/types'
-import type { KubbFile } from '@kubb/fabric-core/types'
-import { SCALAR_PRIMITIVE_TYPES } from './constants.ts'
-
-/**
- * Extracts the schema name from a `$ref` string.
- * For `#/components/schemas/Order` this returns `'Order'`.
- * Falls back to the full ref string when no slash is present.
- */
-export function extractRefName($ref: string): string {
-  return $ref.split('/').at(-1) ?? $ref
-}
-
-/**
- * Replaces the discriminator property's schema inside an `ObjectSchemaNode`
- * with an enum of the given `values`.
- *
- * - When `enumName` is provided the enum is named, which lets printers emit a
- *   standalone enum declaration + type reference (e.g. `PetTypeEnum`).
- * - When `enumName` is omitted the enum stays anonymous, so printers inline it
- *   as a literal union (e.g. `'dog'`).
- *
- * Returns the node unchanged when it is not an object or lacks the target property.
- */
-export function applyDiscriminatorEnum({
-  node,
-  propertyName,
-  values,
-  enumName,
-}: {
-  node: SchemaNode
-  propertyName: string
-  values: Array<string>
-  enumName?: string
-}): SchemaNode {
-  if (node.type !== 'object' || !node.properties?.length) return node
-
-  const hasProperty = node.properties.some((prop) => prop.name === propertyName)
-  if (!hasProperty) return node
-
-  return createSchema({
-    ...node,
-    properties: node.properties.map((prop) => {
-      if (prop.name !== propertyName) return prop
-
-      const enumSchema: SchemaNode = createSchema({
-        type: 'enum' as const,
-        primitive: 'string' as const,
-        enumValues: values,
-        name: enumName,
-        readOnly: prop.schema.readOnly,
-        writeOnly: prop.schema.writeOnly,
-      })
-
-      return createProperty({
-        ...prop,
-        schema: enumSchema,
-      })
-    }),
-  })
-}
-
-/**
- * Merges consecutive anonymous (`name`-less) `ObjectSchemaNode`s in `members` into a
- * single object by combining their `properties` arrays.
- *
- * Only adjacent pairs are merged — non-object or named nodes act as boundaries.
- * This collapses patterns like `Address & { streetNumber } & { streetName }` into
- * `Address & { streetNumber; streetName }`.
- */
-export function mergeAdjacentAnonymousObjects(members: Array<SchemaNode>): Array<SchemaNode> {
-  return members.reduce<Array<SchemaNode>>((acc, member) => {
-    const obj = narrowSchema(member, 'object')
-    if (obj && !obj.name) {
-      const prev = acc[acc.length - 1]
-      const prevObj = prev ? narrowSchema(prev, 'object') : null
-      if (prevObj && !prevObj.name) {
-        acc[acc.length - 1] = createSchema({
-          ...prevObj,
-          properties: [...(prevObj.properties ?? []), ...(obj.properties ?? [])],
-        }) as SchemaNode
-        return acc
-      }
-    }
-    acc.push(member)
-    return acc
-  }, [])
-}
-
-/**
- * Simplifies a union member list by removing `enum` nodes whose `primitive` type is
- * already represented by a broader scalar node in the same union.
- *
- * For example `['placed', 'approved'] | string` collapses to `string` because
- * `string` subsumes all string literals.  `'' | string` similarly becomes `string`.
- *
- * Only scalar primitives (`string`, `number`, `integer`, `bigint`, `boolean`) are
- * considered — object, array, and ref members are left untouched.
- *
- * Const-derived enums (those without an `enumType`, produced from an OpenAPI `const`
- * keyword) are **never** removed — `'accepted' | string` must stay as-is because the
- * literal is intentional.
- */
-export function simplifyUnionMembers(members: Array<SchemaNode>): Array<SchemaNode> {
-  const scalarPrimitives = new Set(members.filter((m) => SCALAR_PRIMITIVE_TYPES.has(m.type as 'string')).map((m) => m.type as string))
-  if (!scalarPrimitives.size) return members
-
-  return members.filter((m) => {
-    if (m.type !== 'enum') return true
-    const prim = m.primitive
-    // Keep the enum if its primitive isn't fully subsumed.
-    if (!prim) return true
-    // Const-derived enums have no `enumType`; keep them as intentional literals.
-    if (!m.enumType) return true
-    // `number` subsumes `integer` literals and vice-versa for our purposes.
-    if (scalarPrimitives.has(prim)) return false
-    if ((prim === 'integer' || prim === 'number') && (scalarPrimitives.has('integer') || scalarPrimitives.has('number'))) return false
-    return true
-  })
-}
-
-/**
- * `nameMapping`, and calls `resolve` to obtain the `{ name, path }` pair for
- * each import. When `oas` is supplied, only `$ref`s that are resolvable in the
- * spec are included; omit it to skip the existence check.
- *
- * This function is the pure, state-free alternative to `OasParser.getImports`.
- * Because it receives `nameMapping` explicitly it can be called without holding
- * a reference to the parser or the OAS instance.
- *
- * @example
- * ```ts
- * // Use adapter state directly — no parser reference needed
- * const imports = getImports({
- *   node: schemaNode,
- *   nameMapping: adapter.options.nameMapping,
- *   resolve: (schemaName) => ({
- *     name: schemaManager.getName(schemaName, { type: 'type' }),
- *     path: schemaManager.getFile(schemaName).path,
- *   }),
- * })
- * ```
- */
-export function getImports({
-  node,
-  nameMapping,
-  resolve,
-}: {
-  node: SchemaNode
-  nameMapping: Map<string, string>
-  resolve: (schemaName: string) => { name: string; path: string } | undefined
-}): Array<KubbFile.Import> {
-  return collect<KubbFile.Import>(node, {
-    schema(schemaNode): KubbFile.Import | undefined {
-      if (schemaNode.type !== 'ref' || !schemaNode.ref) return
-
-      const rawName = extractRefName(schemaNode.ref)
-
-      // Apply collision-resolved name if available.
-      const schemaName = nameMapping.get(rawName) ?? rawName
-      const result = resolve(schemaName)
-      if (!result) return
-
-      return { name: [result.name], path: result.path }
-    },
-  })
-}