@kubb/oas 4.33.2 → 4.33.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/oas",
-  "version": "4.33.2",
+  "version": "4.33.3",
   "description": "OpenAPI Specification (OAS) utilities and helpers for Kubb, providing parsing, normalization, and manipulation of OpenAPI/Swagger schemas.",
   "keywords": [
     "openapi",
@@ -52,14 +52,14 @@
     }
   ],
   "dependencies": {
-    "@readme/openapi-parser": "^5.5.0",
+    "@redocly/openapi-core": "^2.21.0",
     "jsonpointer": "^5.0.1",
-    "oas": "^28.9.0",
-    "oas-normalize": "^15.7.1",
+    "oas": "^31.1.2",
+    "oas-normalize": "^16.0.2",
     "openapi-types": "^12.1.3",
     "remeda": "^2.33.6",
     "swagger2openapi": "^7.0.8",
-    "@kubb/core": "4.33.2"
+    "@kubb/core": "4.33.3"
   },
   "devDependencies": {
     "@stoplight/yaml": "^4.3.0",

package/src/Oas.ts

@@ -1,5 +1,6 @@
 import jsonpointer from 'jsonpointer'
 import BaseOas from 'oas'
+import type { ParameterObject } from 'oas/types'
 import { matchesMimeType } from 'oas/utils'
 import type { contentType, DiscriminatorObject, Document, MediaTypeObject, Operation, ReferenceObject, ResponseObject, SchemaObject } from './types.ts'
 import {
@@ -432,12 +433,33 @@ export class Oas extends BaseOas {
 
   getParametersSchema(operation: Operation, inKey: 'path' | 'query' | 'header'): SchemaObject | null {
     const { contentType = operation.getContentType() } = this.#options
-    const params = operation
-      .getParameters()
-      .map((schema) => {
-        return this.dereferenceWithRef(schema)
-      })
-      .filter((v) => v.in === inKey)
+
+    // Collect parameters from both operation-level and path-level, resolving $ref pointers.
+    // oas v31+ filters out $ref parameters in getParameters(), so we access raw parameters
+    // directly and resolve refs ourselves to preserve backward compatibility.
+    // Note: dereferenceWithRef preserves the $ref property on resolved objects, so we check
+    // for 'in' and 'name' fields to validate successful resolution instead of !isReference().
+    const resolveParams = (params: unknown[]): Array<ParameterObject> =>
+      params.map((p) => this.dereferenceWithRef(p)).filter((p): p is ParameterObject => !!p && typeof p === 'object' && 'in' in p && 'name' in p)
+
+    const operationParams = resolveParams(operation.schema?.parameters || [])
+    const pathItem = this.api?.paths?.[operation.path]
+    const pathLevelParams = resolveParams(pathItem && !isReference(pathItem) && pathItem.parameters ? pathItem.parameters : [])
+
+    // Deduplicate: operation-level parameters override path-level ones with the same name+in
+    const paramMap = new Map<string, ParameterObject>()
+    for (const p of pathLevelParams) {
+      if (p.name && p.in) {
+        paramMap.set(`${p.in}:${p.name}`, p)
+      }
+    }
+    for (const p of operationParams) {
+      if (p.name && p.in) {
+        paramMap.set(`${p.in}:${p.name}`, p)
+      }
+    }
+
+    const params = Array.from(paramMap.values()).filter((v) => v.in === inKey)
 
     if (!params.length) {
       return null

package/src/utils.spec.ts

@@ -82,129 +82,6 @@ components:
     )
     expect(oas.api?.info.title).toBe('Swagger PetStore')
   })
-
-  test('parse a spec with an external file $ref resolves the ref via bundling', async () => {
-    const specPath = path.resolve(__dirname, '../mocks/petStoreExternalFileRef.yaml')
-    const oas = await parse(specPath)
-
-    expect(oas).toBeDefined()
-    expect(oas.api?.info.title).toBe('PetStore with external file ref')
-    // After bundling with external component merging, the Category schema is lifted to #/components/schemas/Category
-    const petSchema = (oas.api as any).components?.schemas?.Pet
-    expect(petSchema).toBeDefined()
-    expect(petSchema.type).toBe('object')
-    expect(petSchema.required).toEqual(['id', 'name'])
-    expect(petSchema.properties.id).toEqual({ type: 'integer', format: 'int64' })
-    expect(petSchema.properties.name).toEqual({ type: 'string' })
-    // The external schema is now referenced via an internal $ref, not inlined
-    const category = petSchema.properties.category
-    expect(category).toBeDefined()
-    expect(category.$ref).toBe('#/components/schemas/Category')
-    // The Category schema is available in the components section
-    const categorySchema = (oas.api as any).components?.schemas?.Category
-    expect(categorySchema).toBeDefined()
-    expect(categorySchema.type).toBe('object')
-    expect(categorySchema.properties.id).toEqual({ type: 'integer', format: 'int64' })
-  })
-
-  test('parse a spec with an external URL $ref resolves the ref via bundling', async () => {
-    const specPath = path.resolve(__dirname, '../../plugin-ts/mocks/petStore.yaml')
-    const oas = await parse(specPath)
-
-    expect(oas).toBeDefined()
-    expect(oas.api?.info.title).toBe('Swagger PetStore')
-    const petSchema = (oas.api as any).components?.schemas?.Pet
-    expect(petSchema).toBeDefined()
-    expect(petSchema.type).toBe('object')
-    expect(petSchema.required).toEqual(['id', 'name'])
-    expect(petSchema.properties.id).toEqual({ type: 'integer', format: 'int64' })
-    expect(petSchema.properties.name).toEqual({ type: 'string' })
-    expect(petSchema.properties.tag).toEqual({ type: 'string' })
-    // After bundling the URL $ref is resolved (inlined) when network is available;
-    // on network failure the fallback plain load preserves the original $ref pointer.
-    expect(petSchema.properties.category).toBeDefined()
-  })
-
-  test('dereference a spec with external $refs works after bundling', async () => {
-    const specPath = path.resolve(__dirname, '../mocks/petStoreExternalFileRef.yaml')
-    const oas = await parse(specPath)
-
-    // After bundling, external file refs are resolved inline so dereference() should work without issues
-    await expect(oas.dereference()).resolves.not.toThrow()
-
-    const petSchema = (oas.api as any).components?.schemas?.Pet
-    expect(petSchema).toBeDefined()
-    expect(petSchema.type).toBe('object')
-    // After bundling, the category is inlined (no external $ref remaining)
-    const category = petSchema.properties.category
-    expect(category).toBeDefined()
-    expect(category.$ref).toBeUndefined()
-    expect(category.type).toBe('object')
-  })
-
-  test('dereference a spec with an external URL $ref works after bundling', async () => {
-    const specPath = path.resolve(__dirname, '../../plugin-ts/mocks/petStore.yaml')
-    const oas = await parse(specPath)
-
-    // After bundling (or fallback to load on network error), dereference() should work
-    await expect(oas.dereference()).resolves.not.toThrow()
-
-    const petSchema = (oas.api as any).components?.schemas?.Pet
-    expect(petSchema).toBeDefined()
-    expect(petSchema.type).toBe('object')
-    expect(petSchema.properties.category).toBeDefined()
-  })
-})
-
-describe('mergeExternalFileComponents', () => {
-  test('merges external component schemas so they appear in the bundled #/components/schemas', async () => {
-    const specPath = path.resolve(__dirname, '../mocks/multiFileApi.yaml')
-    const oas = await parse(specPath)
-
-    // All schemas from the external file should be available in #/components/schemas
-    const schemas = (oas.api as any).components?.schemas
-    expect(schemas).toBeDefined()
-    expect(schemas.Parcel).toBeDefined()
-    expect(schemas.ContactDetailsType).toBeDefined()
-    expect(schemas.TypeARequest).toBeDefined()
-    expect(schemas.TypeBRequest).toBeDefined()
-    expect(schemas.Result).toBeDefined()
-  })
-
-  test('shared external response schema is referenced via #/components, not inlined per operation', async () => {
-    const specPath = path.resolve(__dirname, '../mocks/multiFileApi.yaml')
-    const oas = await parse(specPath)
-
-    // The Result schema should be referenced via $ref, not inlined
-    const resultSchema = (oas.api as any).components?.schemas?.Result
-    expect(resultSchema).toBeDefined()
-    expect(resultSchema.type).toBe('object')
-
-    // Parcel is a nested schema that should remain separate
-    const parcelSchema = (oas.api as any).components?.schemas?.Parcel
-    expect(parcelSchema).toBeDefined()
-    expect(parcelSchema.type).toBe('object')
-    expect(parcelSchema.properties.parcelNo).toEqual({ type: 'string' })
-    expect(parcelSchema.properties.trackingNumber).toEqual({ type: 'string' })
-
-    // Result.parcels items should reference Parcel via $ref
-    const parcelsItems = resultSchema.properties?.parcels?.items
-    expect(parcelsItems).toBeDefined()
-    expect(parcelsItems.$ref).toBe('#/components/schemas/Parcel')
-  })
-
-  test('getSchemas returns all external component schemas for separate file generation', async () => {
-    const specPath = path.resolve(__dirname, '../mocks/multiFileApi.yaml')
-    const oas = await parse(specPath)
-    const { schemas } = oas.getSchemas()
-
-    // All schemas from the external definitions file should be available
-    expect(Object.keys(schemas)).toContain('Parcel')
-    expect(Object.keys(schemas)).toContain('ContactDetailsType')
-    expect(Object.keys(schemas)).toContain('TypeARequest')
-    expect(Object.keys(schemas)).toContain('TypeBRequest')
-    expect(Object.keys(schemas)).toContain('Result')
-  })
 })
 
 describe('parseFromConfig', () => {

package/src/utils.ts

@@ -1,8 +1,7 @@
-import fs from 'node:fs'
 import path from 'node:path'
 import { pascalCase, URLPath } from '@internals/utils'
 import type { Config } from '@kubb/core'
-import { bundle } from '@readme/openapi-parser'
+import { bundle, loadConfig } from '@redocly/openapi-core'
 import yaml from '@stoplight/yaml'
 import type { ParameterObject, SchemaObject } from 'oas/types'
 import { isRef, isSchema } from 'oas/types'
@@ -161,135 +160,16 @@ export function getDefaultValue(schema?: SchemaObject): string | undefined {
   return undefined
 }
 
-/**
- * Recursively collect all external local-file $ref prefixes (e.g. "api-definitions.yml")
- * from an object tree. URL refs (http/https) are ignored.
- */
-function collectExternalFilePaths(obj: unknown, files: Set<string>): void {
-  if (!obj || typeof obj !== 'object') return
-  if (Array.isArray(obj)) {
-    for (const item of obj) collectExternalFilePaths(item, files)
-    return
-  }
-  for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
-    if (key === '$ref' && typeof value === 'string') {
-      const hashIdx = value.indexOf('#')
-      const filePart = hashIdx > 0 ? value.slice(0, hashIdx) : hashIdx === -1 ? value : ''
-      if (filePart && !filePart.startsWith('http://') && !filePart.startsWith('https://')) {
-        files.add(filePart)
-      }
-    } else {
-      collectExternalFilePaths(value, files)
-    }
-  }
-}
-
-/**
- * Replace all $refs that start with `externalFile#` with the corresponding
- * internal ref (i.e. just the fragment part, `#/...`).
- */
-function replaceExternalRefsInPlace(obj: unknown, externalFile: string): void {
-  if (!obj || typeof obj !== 'object') return
-  if (Array.isArray(obj)) {
-    for (const item of obj) replaceExternalRefsInPlace(item, externalFile)
-    return
-  }
-  const record = obj as Record<string, unknown>
-  for (const key of Object.keys(record)) {
-    const value = record[key]
-    if (key === '$ref' && typeof value === 'string' && value.startsWith(`${externalFile}#`)) {
-      record[key] = value.slice(externalFile.length)
-    } else if (value && typeof value === 'object') {
-      replaceExternalRefsInPlace(value, externalFile)
-    }
-  }
-}
-
-/**
- * Before bundling, scan the main spec file for external local-file references and merge
- * their `components` sections into the main document. This ensures that schemas defined
- * in external files (e.g. `api-definitions.yml#/components/schemas/Parcel`) end up in
- * `#/components/schemas/Parcel` of the bundled output, rather than being inlined as
- * anonymous path-based refs.
- *
- * Returns the merged document, or `null` if no external file components were found.
- */
-export function mergeExternalFileComponents(mainFilePath: string): Document | null {
-  let mainContent: string
-  try {
-    mainContent = fs.readFileSync(mainFilePath, 'utf-8')
-  } catch {
-    return null
-  }
-
-  const mainDoc = yaml.parse(mainContent) as Record<string, unknown> | null
-  if (!mainDoc || typeof mainDoc !== 'object') return null
-
-  const mainDir = path.dirname(mainFilePath)
-
-  const externalFiles = new Set<string>()
-  collectExternalFilePaths(mainDoc, externalFiles)
-
-  if (externalFiles.size === 0) return null
-
-  let hasMergedComponents = false
-
-  for (const externalFile of externalFiles) {
-    const externalFilePath = path.resolve(mainDir, externalFile)
-    let externalContent: string
-    try {
-      externalContent = fs.readFileSync(externalFilePath, 'utf-8')
-    } catch {
-      continue
-    }
-
-    const externalDoc = yaml.parse(externalContent) as Record<string, unknown> | null
-    if (!externalDoc?.components || typeof externalDoc.components !== 'object') continue
-
-    const mainComponents = (mainDoc.components as Record<string, unknown>) ?? {}
-    mainDoc.components = mainComponents
-
-    for (const [componentType, components] of Object.entries(externalDoc.components as Record<string, Record<string, unknown>>)) {
-      if (!components || typeof components !== 'object') continue
-      // Spread external entries first, then main doc entries last so main document wins on name conflicts
-      mainComponents[componentType] = {
-        ...(components as Record<string, unknown>),
-        ...((mainComponents[componentType] as Record<string, unknown>) ?? {}),
-      }
-      hasMergedComponents = true
-    }
-  }
-
-  if (!hasMergedComponents) return null
-
-  // Replace external file refs with their internal equivalents
-  for (const externalFile of externalFiles) {
-    replaceExternalRefsInPlace(mainDoc, externalFile)
-  }
-
-  return mainDoc as unknown as Document
-}
-
 export async function parse(
   pathOrApi: string | Document,
-  { oasClass = Oas, enablePaths = true }: { oasClass?: typeof Oas; canBundle?: boolean; enablePaths?: boolean } = {},
+  { oasClass = Oas, canBundle = true, enablePaths = true }: { oasClass?: typeof Oas; canBundle?: boolean; enablePaths?: boolean } = {},
 ): Promise<Oas> {
-  // Only attempt to bundle when pathOrApi is a file path or URL (not inline YAML/JSON strings).
-  // Inline content (YAML strings with newlines, JSON strings starting with '{') is handled by plain load.
-  const isPathOrUrl = typeof pathOrApi === 'string' && !pathOrApi.match(/\n/) && !pathOrApi.match(/^\s*\{/)
-  if (isPathOrUrl && enablePaths) {
-    // Bundle the spec using the string path directly so that relative external $refs
-    // (file and URL) are resolved with the correct base path context.
-    try {
-      // Pre-merge external file component schemas so they appear in #/components/schemas/
-      // of the bundled output rather than being inlined as anonymous path-based refs.
-      const mergedDoc = mergeExternalFileComponents(pathOrApi)
-      const bundled = await bundle((mergedDoc ?? pathOrApi) as Parameters<typeof bundle>[0])
-      return parse(bundled as Document, { oasClass, enablePaths })
-    } catch (e) {
-      // If bundling fails (e.g. unresolvable refs or network error), fall through to plain load
-      console.warn(`[kubb] Failed to bundle external $refs in "${pathOrApi}": ${(e as Error).message}. Falling back to plain load.`)
-    }
+  if (typeof pathOrApi === 'string' && canBundle) {
+    // resolve external refs
+    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, {
@@ -310,7 +190,7 @@ export async function parse(
 }
 
 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 })))
+  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.')