@kubb/oas 4.31.0 → 4.31.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/oas",
-  "version": "4.31.0",
+  "version": "4.31.2",
   "description": "OpenAPI Specification (OAS) utilities and helpers for Kubb, providing parsing, normalization, and manipulation of OpenAPI/Swagger schemas.",
   "keywords": [
     "openapi",
@@ -59,7 +59,7 @@
     "openapi-types": "^12.1.3",
     "remeda": "^2.33.6",
     "swagger2openapi": "^7.0.8",
-    "@kubb/core": "4.31.0"
+    "@kubb/core": "4.31.2"
   },
   "devDependencies": {
     "@stoplight/yaml": "^4.3.0",

package/src/utils.spec.ts

@@ -89,19 +89,22 @@ components:
 
     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
+    // 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 file $ref is resolved: category has the inline schema from category.yaml
+    // The external schema is now referenced via an internal $ref, not inlined
     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' })
+    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 () => {
@@ -153,6 +156,57 @@ components:
   })
 })
 
+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', () => {
   const petStoreV3 = path.resolve(__dirname, '../mocks/petStore.yaml')
   const petStoreV2 = path.resolve(__dirname, '../mocks/petStoreV2.json')

package/src/utils.ts

@@ -1,3 +1,4 @@
+import fs from 'node:fs'
 import path from 'node:path'
 import type { Config } from '@kubb/core'
 import { pascalCase } from '@kubb/core/transformers'
@@ -161,6 +162,115 @@ 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 } = {},
@@ -172,7 +282,10 @@ export async function parse(
     // 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)
+      // 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