@kubb/oas 4.27.2 → 4.27.4

package/package.json

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

package/src/index.ts

@@ -1,4 +1,3 @@
-export { findSchemaDefinition, matchesMimeType } from 'oas/utils'
 export { Oas } from './Oas.ts'
 export * from './types.ts'
 export {

package/src/utils.spec.ts

@@ -82,6 +82,75 @@ 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, the external file $ref is resolved: the Category schema is inlined
+    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 file $ref is resolved: category has the inline schema from category.yaml
+    const category = petSchema.properties.category
+    expect(category).toBeDefined()
+    expect(category.$ref).toBeUndefined()
+    expect(category.type).toBe('object')
+    expect(category.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('parseFromConfig', () => {

package/src/utils.ts

@@ -2,7 +2,7 @@ import path from 'node:path'
 import type { Config } from '@kubb/core'
 import { pascalCase } from '@kubb/core/transformers'
 import { URLPath } from '@kubb/core/utils'
-import { bundle, loadConfig } from '@redocly/openapi-core'
+import { bundle } from '@readme/openapi-parser'
 import yaml from '@stoplight/yaml'
 import type { ParameterObject, SchemaObject } from 'oas/types'
 import { isRef, isSchema } from 'oas/types'
@@ -163,14 +163,21 @@ export function getDefaultValue(schema?: SchemaObject): string | undefined {
 
 export async function parse(
   pathOrApi: string | Document,
-  { oasClass = Oas, canBundle = true, enablePaths = true }: { oasClass?: typeof Oas; canBundle?: boolean; enablePaths?: boolean } = {},
+  { oasClass = Oas, enablePaths = true }: { oasClass?: typeof Oas; canBundle?: boolean; enablePaths?: boolean } = {},
 ): Promise<Oas> {
-  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 })
+  // 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 {
+      const bundled = await bundle(pathOrApi)
+      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.`)
+    }
   }
 
   const oasNormalize = new OASNormalize(pathOrApi, {
@@ -191,7 +198,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, canBundle: false })))
+  const instances = await Promise.all(pathOrApi.map((p) => parse(p, { oasClass, enablePaths: false })))
 
   if (instances.length === 0) {
     throw new Error('No OAS instances provided for merging.')