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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/adapter-oas",
-  "version": "5.0.0-beta.63",
+  "version": "5.0.0-beta.64",
   "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",
@@ -19,7 +19,6 @@
     "directory": "packages/adapter-oas"
   },
   "files": [
-    "src",
     "dist",
     "!/**/**.test.**",
     "!/**/__tests__/**",
@@ -43,15 +42,14 @@
   },
   "dependencies": {
     "@readme/openapi-parser": "^6.1.3",
+    "@scalar/openapi-upgrader": "^0.2.9",
     "api-ref-bundler": "0.5.1",
-    "swagger2openapi": "^7.0.8",
     "yaml": "^2.9.0",
-    "@kubb/ast": "5.0.0-beta.63",
-    "@kubb/core": "5.0.0-beta.63"
+    "@kubb/ast": "5.0.0-beta.64",
+    "@kubb/core": "5.0.0-beta.64"
   },
   "devDependencies": {
     "@types/json-schema": "^7.0.15",
-    "@types/swagger2openapi": "^7.0.4",
     "openapi-types": "^12.1.3",
     "@internals/utils": "0.0.0"
   },

package/src/adapter.bench.ts

@@ -1,60 +0,0 @@
-import path from 'node:path'
-import { existsSync } from 'node:fs'
-import { bench, describe } from 'vitest'
-import { adapterOas } from './adapter.ts'
-import { parseDocument } from './factory.ts'
-import { parseOas } from './parser.ts'
-import type { Document } from './types.ts'
-import type { AdapterSource } from '@kubb/core'
-
-const petStorePath = path.resolve(import.meta.dirname, '../mocks/petStore.yaml')
-const stripeSpecPath = '/tmp/kubb-stripe-spec3.json'
-const hasStripe = existsSync(stripeSpecPath)
-
-let petStoreDoc: Document | undefined
-
-async function getPetStoreDocument(): Promise<Document> {
-  if (!petStoreDoc) {
-    petStoreDoc = await parseDocument(petStorePath)
-  }
-  return petStoreDoc
-}
-
-describe('parseOas() performance', () => {
-  bench(
-    'petStore spec',
-    async () => {
-      const doc = await getPetStoreDocument()
-      parseOas(doc)
-    },
-    { iterations: 5, warmupIterations: 1 },
-  )
-})
-
-describe.skipIf(!hasStripe)('Stripe spec — batch vs streaming (1,385 schemas)', () => {
-  const stripeSource: AdapterSource = { type: 'path', path: stripeSpecPath }
-
-  bench(
-    'batch — adapter.parse()',
-    async () => {
-      const adapter = adapterOas({ validate: false })
-      await adapter.parse(stripeSource)
-    },
-    { iterations: 3, warmupIterations: 1 },
-  )
-
-  bench(
-    'streaming — adapter.stream() drain',
-    async () => {
-      const adapter = adapterOas({ validate: false })
-      const stream = await adapter.stream!(stripeSource)
-      for await (const _ of stream.schemas) {
-        /* drain */
-      }
-      for await (const _ of stream.operations) {
-        /* drain */
-      }
-    },
-    { iterations: 3, warmupIterations: 1 },
-  )
-})

package/src/adapter.ts

@@ -1,207 +0,0 @@
-import { ast, createAdapter } from '@kubb/core'
-import type { AdapterSource } from '@kubb/core'
-import { DEFAULT_PARSER_OPTIONS } from './constants.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'
-import type { AdapterOas, Document } from './types.ts'
-import { collect, narrowSchema } from '@kubb/ast'
-import { extractRefName } from '@kubb/ast/utils'
-
-/**
- * The `name` of `@kubb/adapter-oas`, used to identify this adapter in a Kubb config.
- */
-export const adapterOasName = 'oas' satisfies AdapterOas['name']
-
-/**
- * Default Kubb adapter for OpenAPI 2.0, 3.0, and 3.1 specifications. Reads the
- * file at `input.path`, validates it, resolves the base URL, and converts every
- * schema and operation into the universal AST that every downstream plugin
- * consumes.
- *
- * Configure once on `defineConfig`. The adapter's choices (date representation,
- * integer width, server URL) apply to every plugin in the build.
- *
- * @example
- * ```ts
- * import { defineConfig } from 'kubb'
- * import { adapterOas } from '@kubb/adapter-oas'
- * import { pluginTs } from '@kubb/plugin-ts'
- *
- * export default defineConfig({
- *   input: { path: './petStore.yaml' },
- *   output: { path: './src/gen' },
- *   adapter: adapterOas({
- *     serverIndex: 0,
- *     discriminator: 'inherit',
- *     dateType: 'date',
- *   }),
- *   plugins: [pluginTs()],
- * })
- * ```
- */
-export const adapterOas = createAdapter<AdapterOas>((options) => {
-  const {
-    validate = true,
-    contentType,
-    serverIndex,
-    serverVariables,
-    discriminator = 'strict',
-    dedupe = true,
-    dateType = DEFAULT_PARSER_OPTIONS.dateType,
-    integerType = DEFAULT_PARSER_OPTIONS.integerType,
-    unknownType = DEFAULT_PARSER_OPTIONS.unknownType,
-    enumSuffix = DEFAULT_PARSER_OPTIONS.enumSuffix,
-    emptySchemaType = unknownType || DEFAULT_PARSER_OPTIONS.emptySchemaType,
-  } = options
-
-  const parserOptions: ast.ParserOptions = {
-    ...DEFAULT_PARSER_OPTIONS,
-    dateType,
-    integerType,
-    unknownType,
-    emptySchemaType,
-    enumSuffix,
-  }
-
-  let nameMapping = new Map<string, string>()
-  let parsedDocument: Document | null = null
-
-  // Cache per source and per document so one adapter instance reused across a `defineConfig` array
-  // parses each config's spec instead of replaying the first one. Keying the document by its source
-  // object still collapses a config's concurrent `stream()` (build) and `parse()` (studio) calls,
-  // which share one source object, onto a single parse. The document-derived caches key off the
-  // resulting document, so distinct configs (distinct documents) stay isolated.
-  const documentCache = new WeakMap<AdapterSource, Promise<Document>>()
-  const schemasCache = new WeakMap<Document, Promise<ReturnType<typeof getSchemas>['schemas']>>()
-  const schemaParserCache = new WeakMap<Document, ReturnType<typeof createSchemaParser>>()
-  const preScanCache = new WeakMap<Document, ReturnType<typeof preScan>>()
-
-  function ensureDocument(source: AdapterSource): Promise<Document> {
-    const cached = documentCache.get(source)
-    if (cached) return cached
-
-    const promise = (async () => {
-      const fresh = await parseFromConfig(source)
-      if (validate) await validateDocument(fresh)
-      parsedDocument = fresh
-      return fresh
-    })()
-    documentCache.set(source, promise)
-    return promise
-  }
-
-  function ensureSchemas(document: Document): Promise<ReturnType<typeof getSchemas>['schemas']> {
-    const cached = schemasCache.get(document)
-    if (cached) return cached
-
-    const promise = Promise.resolve().then(() => {
-      const result = getSchemas(document, { contentType })
-      nameMapping = result.nameMapping
-      return result.schemas
-    })
-    schemasCache.set(document, promise)
-    return promise
-  }
-
-  function ensureSchemaParser(document: Document): ReturnType<typeof createSchemaParser> {
-    const cached = schemaParserCache.get(document)
-    if (cached) return cached
-
-    const parser = createSchemaParser({ document, contentType })
-    schemaParserCache.set(document, parser)
-    return parser
-  }
-
-  function ensurePreScan(
-    document: Document,
-    schemas: ReturnType<typeof getSchemas>['schemas'],
-    parseSchema: ReturnType<typeof ensureSchemaParser>['parseSchema'],
-    parseOperation: ReturnType<typeof ensureSchemaParser>['parseOperation'],
-  ): ReturnType<typeof preScan> {
-    const cached = preScanCache.get(document)
-    if (cached) return cached
-
-    const result = preScan({ schemas, parseSchema, parseOperation, document, parserOptions, discriminator, dedupe })
-    preScanCache.set(document, result)
-    return result
-  }
-
-  async function createStream(source: AdapterSource): Promise<ast.InputNode<true>> {
-    const document = await ensureDocument(source)
-    const schemas = await ensureSchemas(document)
-    const { parseSchema, parseOperation } = ensureSchemaParser(document)
-    const { refAliasMap, enumNames, circularNames, discriminatorChildMap, dedupePlan } = ensurePreScan(document, schemas, parseSchema, parseOperation)
-
-    return createInputStream({
-      schemas,
-      parseSchema,
-      parseOperation,
-      document,
-      parserOptions,
-      refAliasMap,
-      discriminatorChildMap,
-      dedupePlan,
-      meta: {
-        title: document.info?.title,
-        description: document.info?.description,
-        version: document.info?.version,
-        baseURL: resolveBaseUrl({ document, serverIndex, serverVariables }),
-        circularNames,
-        enumNames,
-      },
-    })
-  }
-
-  return {
-    name: adapterOasName,
-    get options() {
-      return {
-        validate,
-        contentType,
-        serverIndex,
-        serverVariables,
-        discriminator,
-        dedupe,
-        dateType,
-        integerType,
-        unknownType,
-        emptySchemaType,
-        enumSuffix,
-        nameMapping,
-      }
-    },
-    get document() {
-      return parsedDocument
-    },
-    async validate(input, options) {
-      await assertInputExists(input)
-      const document = await parseDocument(input)
-      await validateDocument(document, options)
-    },
-    getImports(node, resolve) {
-      return collect(node, {
-        schema(schemaNode) {
-          const schemaRef = narrowSchema(schemaNode, 'ref')
-          if (!schemaRef?.ref) return null
-
-          const rawName = extractRefName(schemaRef.ref)
-          const schemaName = nameMapping.get(rawName) ?? rawName
-          const result = resolve(schemaName)
-          if (!result) return null
-
-          return ast.factory.createImport({ name: [result.name], path: result.path })
-        },
-      })
-    },
-    async parse(source) {
-      const streamNode = await createStream(source)
-
-      const [schemas, operations] = await Promise.all([Array.fromAsync(streamNode.schemas), Array.fromAsync(streamNode.operations)])
-
-      return ast.factory.createInput({ schemas, operations, meta: streamNode.meta })
-    },
-    stream: createStream,
-  }
-})

package/src/bundler.ts

@@ -1,71 +0,0 @@
-import { read } from '@internals/utils'
-import { bundle } from 'api-ref-bundler'
-import { parse } from 'yaml'
-import type { Document } from './types.ts'
-
-const urlRegExp = /^https?:\/+/i
-
-async function readSource(sourcePath: string): Promise<string> {
-  if (urlRegExp.test(sourcePath)) {
-    // api-ref-bundler joins relative refs with posix normalization, collapsing `https://` to
-    // `https:/`. The WHATWG URL parser restores the double slash.
-    const url = new URL(sourcePath)
-    const response = await fetch(url)
-
-    if (!response.ok) {
-      throw new Error(`Cannot fetch the OAS document at ${url.href} (HTTP ${response.status})`)
-    }
-
-    return response.text()
-  }
-
-  return read(sourcePath)
-}
-
-async function resolveSource(sourcePath: string): Promise<object | string> {
-  const data = await readSource(sourcePath)
-
-  if (sourcePath.toLowerCase().endsWith('.md')) {
-    return data
-  }
-
-  return parse(data) as object
-}
-
-/**
- * Bundles a multi-file OpenAPI document into a single document via `api-ref-bundler`.
- *
- * External file schemas are hoisted into named `components.schemas` entries, so a property
- * pointing at `./schemas/User.yaml` ends up referencing `#/components/schemas/User`. Generators
- * can then emit a named type with an import instead of inlining the shape. Sources are read with
- * the Bun-aware `read` util for local YAML and JSON files, and with `fetch` for HTTP(S) URLs.
- *
- * @example Local file
- * `const document = await bundleDocument('./openapi.yaml')`
- *
- * @example Remote URL
- * `const document = await bundleDocument('https://example.com/openapi.yaml')`
- */
-export async function bundleDocument(pathOrUrl: string): Promise<Document> {
-  const cache = new Map<string, Promise<object | string>>()
-
-  const resolver = (sourcePath: string) => {
-    // api-ref-bundler refers to the same URL as both `https://` and the posix-normalized
-    // `https:/`, so cache on the canonical href to fetch each source once.
-    const key = urlRegExp.test(sourcePath) ? new URL(sourcePath).href : sourcePath
-    const cached = cache.get(key)
-    if (cached) {
-      return cached
-    }
-
-    const result = resolveSource(sourcePath)
-    cache.set(key, result)
-    return result
-  }
-
-  // api-ref-bundler swallows resolver errors and leaves refs unresolved, so surface an
-  // unreadable input document as a hard error before bundling.
-  await resolver(pathOrUrl)
-
-  return (await bundle(pathOrUrl, resolver)) as Document
-}

package/src/constants.ts

@@ -1,135 +0,0 @@
-import { ast } from '@kubb/core'
-
-/**
- * Default parser options applied when no explicit options are provided.
- *
- * @example
- * ```ts
- * import { DEFAULT_PARSER_OPTIONS, parseOas } from '@kubb/adapter-oas'
- *
- * const { root } = parseOas(document, { ...DEFAULT_PARSER_OPTIONS, dateType: 'date' })
- * ```
- */
-export const DEFAULT_PARSER_OPTIONS = {
-  dateType: 'string',
-  integerType: 'bigint',
-  unknownType: 'any',
-  emptySchemaType: 'any',
-  enumSuffix: 'enum',
-} as const satisfies ast.ParserOptions
-
-/**
- * JSON-Pointer prefix for schemas declared under `components.schemas` in an OpenAPI document.
- *
- * Used when building or parsing `$ref` strings.
- *
- * @example
- * ```ts
- * `${SCHEMA_REF_PREFIX}Pet` // '#/components/schemas/Pet'
- * ```
- */
-export const SCHEMA_REF_PREFIX = '#/components/schemas/' as const
-
-/**
- * HTTP methods that count as operations on an OpenAPI path item. Other keys
- * (`parameters`, `summary`, `$ref`, vendor extensions) are skipped when iterating operations.
- */
-export const SUPPORTED_METHODS: ReadonlySet<string> = new Set(['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'])
-
-/**
- * OpenAPI version string written into the stub document created during multi-spec merges.
- */
-export const MERGE_OPENAPI_VERSION = '3.0.0' as const
-
-/**
- * Fallback `info.title` placed in the stub document when merging multiple API files.
- */
-export const MERGE_DEFAULT_TITLE = 'Merged API' as const
-
-/**
- * Fallback `info.version` placed in the stub document when merging multiple API files.
- */
-export const MERGE_DEFAULT_VERSION = '1.0.0' as const
-
-/**
- * Set of JSON Schema keywords that prevent a schema fragment from being inlined during `allOf` flattening.
- *
- * A fragment that contains any of these keys carries structural meaning of its own and must stay as a separate
- * intersection member rather than being merged into the parent.
- *
- * @example
- * ```ts
- * import { structuralKeys } from '@kubb/adapter-oas'
- *
- * const isStructural = Object.keys(fragment).some((key) => structuralKeys.has(key))
- * // true when fragment has e.g. 'properties' or 'oneOf'
- * ```
- */
-export const structuralKeys = new Set(['properties', 'items', 'additionalProperties', 'oneOf', 'anyOf', 'allOf', 'not'] as const)
-
-/**
- * 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'])
-
-/**
- * Static map from OAS `format` strings to Kubb `SchemaType` values.
- *
- * Only formats whose AST type differs from the OAS `type` field appear here.
- * Formats that depend on runtime options (`int64`, `date-time`, `date`, `time`) are handled
- * separately in the parser. `ipv4` and `ipv6` map to their own dedicated schema types. `hostname`
- * and `idn-hostname` map to `'url'` as the closest generic string-format type.
- *
- * @example
- * ```ts
- * import { formatMap } from '@kubb/adapter-oas'
- *
- * formatMap['uuid']   // 'uuid'
- * formatMap['binary'] // 'blob'
- * formatMap['float']  // 'number'
- * ```
- */
-export const formatMap = {
-  uuid: 'uuid',
-  email: 'email',
-  'idn-email': 'email',
-  uri: 'url',
-  'uri-reference': 'url',
-  url: 'url',
-  ipv4: 'ipv4',
-  ipv6: 'ipv6',
-  hostname: 'url',
-  'idn-hostname': 'url',
-  binary: 'blob',
-  byte: 'blob',
-  // Numeric formats override the OAS `type` because format is more specific.
-  // See https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-validation-00#rfc.section.7
-  int32: 'integer',
-  float: 'number',
-  double: 'number',
-} as const satisfies Record<string, ast.SchemaType>
-
-/**
- * Vendor extension keys that attach human-readable labels to enum values, checked in priority order.
- *
- * @example
- * ```ts
- * import { enumExtensionKeys } from '@kubb/adapter-oas'
- *
- * const key = enumExtensionKeys.find((k) => k in schema) // 'x-enumNames' | 'x-enum-varnames' | undefined
- * ```
- */
-export const enumExtensionKeys = ['x-enumNames', 'x-enum-varnames'] as const
-
-/**
- * Maps the `unknownType`/`emptySchemaType` option string to its `ScalarSchemaType` constant.
- * A `Map` (over a plain object) lets callers test key membership with `.has()`.
- */
-export const typeOptionMap = new Map<'any' | 'unknown' | 'void', ast.ScalarSchemaType>([
-  ['any', ast.schemaTypes.any],
-  ['unknown', ast.schemaTypes.unknown],
-  ['void', ast.schemaTypes.void],
-])