@kubb/oas 4.18.5 → 4.19.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/oas",
-  "version": "4.18.5",
+  "version": "4.19.1",
   "description": "OpenAPI Specification (OAS) utilities and helpers for Kubb, providing parsing, normalization, and manipulation of OpenAPI/Swagger schemas.",
   "keywords": [
     "openapi",
@@ -48,14 +48,14 @@
     }
   ],
   "dependencies": {
-    "@redocly/openapi-core": "^2.14.7",
+    "@redocly/openapi-core": "^2.14.9",
     "jsonpointer": "^5.0.1",
     "oas": "^28.9.0",
     "oas-normalize": "^15.7.0",
     "openapi-types": "^12.1.3",
     "remeda": "^2.33.4",
     "swagger2openapi": "^7.0.8",
-    "@kubb/core": "4.18.5"
+    "@kubb/core": "4.19.1"
   },
   "devDependencies": {
     "@stoplight/yaml": "^4.3.0",

package/src/Oas.ts

@@ -1,17 +1,31 @@
 import jsonpointer from 'jsonpointer'
 import BaseOas from 'oas'
-
 import { matchesMimeType } from 'oas/utils'
 import type { contentType, DiscriminatorObject, Document, MediaTypeObject, Operation, ReferenceObject, ResponseObject, SchemaObject } from './types.ts'
-import { isDiscriminator, isReference, STRUCTURAL_KEYS } from './utils.ts'
-
-type Options = {
+import {
+  extractSchemaFromContent,
+  flattenSchema,
+  isDiscriminator,
+  isReference,
+  legacyResolve,
+  resolveCollisions,
+  type SchemaWithMetadata,
+  sortSchemas,
+  validate,
+} from './utils.ts'
+
+type OasOptions = {
   contentType?: contentType
   discriminator?: 'strict' | 'inherit'
+  /**
+   * Resolve name collisions when schemas from different components share the same name (case-insensitive).
+   * @default false
+   */
+  collisionDetection?: boolean
 }
 
 export class Oas extends BaseOas {
-  #options: Options = {
+  #options: OasOptions = {
     discriminator: 'strict',
   }
   document: Document
@@ -22,7 +36,7 @@ export class Oas extends BaseOas {
     this.document = document
   }
 
-  setOptions(options: Options) {
+  setOptions(options: OasOptions) {
     this.#options = {
       ...this.#options,
       ...options,
@@ -33,7 +47,7 @@ export class Oas extends BaseOas {
     }
   }
 
-  get options(): Options {
+  get options(): OasOptions {
     return this.#options
   }
 
@@ -480,51 +494,64 @@ export class Oas extends BaseOas {
   }
 
   async validate() {
-    const OASNormalize = await import('oas-normalize').then((m) => m.default)
-    const oasNormalize = new OASNormalize(this.api, {
-      enablePaths: true,
-      colorizeErrors: true,
-    })
-
-    return oasNormalize.validate({
-      parser: {
-        validate: {
-          errors: {
-            colorize: true,
-          },
-        },
-      },
-    })
+    return validate(this.api)
   }
 
   flattenSchema(schema: SchemaObject | null): SchemaObject | null {
-    if (!schema?.allOf || schema.allOf.length === 0) {
-      return schema || null
-    }
+    return flattenSchema(schema)
+  }
 
-    // Never touch ref-based or structural composition
-    if (schema.allOf.some((item) => isReference(item))) {
-      return schema
+  /**
+   * Get schemas from OpenAPI components (schemas, responses, requestBodies).
+   * Returns schemas in dependency order along with name mapping for collision resolution.
+   */
+  getSchemas(options: { contentType?: contentType; includes?: Array<'schemas' | 'responses' | 'requestBodies'>; collisionDetection?: boolean } = {}): {
+    schemas: Record<string, SchemaObject>
+    nameMapping: Map<string, string>
+  } {
+    const contentType = options.contentType ?? this.#options.contentType
+    const includes = options.includes ?? ['schemas', 'requestBodies', 'responses']
+    const shouldResolveCollisions = options.collisionDetection ?? this.#options.collisionDetection ?? false
+
+    const components = this.getDefinition().components
+    const schemasWithMeta: SchemaWithMetadata[] = []
+
+    // Collect schemas from components
+    if (includes.includes('schemas')) {
+      const componentSchemas = (components?.schemas as Record<string, SchemaObject>) || {}
+      for (const [name, schema] of Object.entries(componentSchemas)) {
+        schemasWithMeta.push({ schema, source: 'schemas', originalName: name })
+      }
     }
 
-    const isPlainFragment = (item: SchemaObject) => !Object.keys(item).some((key) => STRUCTURAL_KEYS.has(key))
-
-    // Only flatten keyword-only fragments
-    if (!schema.allOf.every((item) => isPlainFragment(item as SchemaObject))) {
-      return schema
+    if (includes.includes('responses')) {
+      const responses = components?.responses || {}
+      for (const [name, response] of Object.entries(responses)) {
+        const responseObject = response as ResponseObject
+        const schema = extractSchemaFromContent(responseObject.content, contentType)
+        if (schema) {
+          schemasWithMeta.push({ schema, source: 'responses', originalName: name })
+        }
+      }
     }
 
-    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
+    if (includes.includes('requestBodies')) {
+      const requestBodies = components?.requestBodies || {}
+      for (const [name, request] of Object.entries(requestBodies)) {
+        const requestObject = request as { content?: Record<string, unknown> }
+        const schema = extractSchemaFromContent(requestObject.content, contentType)
+        if (schema) {
+          schemasWithMeta.push({ schema, source: 'requestBodies', originalName: name })
         }
       }
     }
 
-    return merged
+    // Apply collision resolution only if enabled
+    const { schemas, nameMapping } = shouldResolveCollisions ? resolveCollisions(schemasWithMeta) : legacyResolve(schemasWithMeta)
+
+    return {
+      schemas: sortSchemas(schemas),
+      nameMapping,
+    }
   }
 }

package/src/index.ts

@@ -14,4 +14,5 @@ export {
   merge,
   parse,
   parseFromConfig,
+  validate,
 } from './utils.ts'

package/src/utils.spec.ts

@@ -3,7 +3,19 @@ import { fileURLToPath } from 'node:url'
 import type { Config } from '@kubb/core'
 import yaml from '@stoplight/yaml'
 import { describe, expect, test } from 'vitest'
-import { merge, parse, parseFromConfig } from './utils.ts'
+import type { SchemaObject } from './types.ts'
+import {
+  collectRefs,
+  extractSchemaFromContent,
+  getSemanticSuffix,
+  legacyResolve,
+  merge,
+  parse,
+  parseFromConfig,
+  resolveCollisions,
+  type SchemaWithMetadata,
+  sortSchemas,
+} from './utils.ts'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
@@ -184,4 +196,279 @@ components:
     expect(oas).toBeDefined()
     expect(oas.api?.info.title).toBe('Swagger PetStore')
   })
+
+  describe('collectRefs', () => {
+    test('should collect $ref from schema', () => {
+      const schema = {
+        type: 'object',
+        properties: {
+          user: { $ref: '#/components/schemas/User' },
+          role: { $ref: '#/components/schemas/Role' },
+        },
+      }
+      const refs = collectRefs(schema)
+      expect(refs).toEqual(new Set(['User', 'Role']))
+    })
+
+    test('should collect nested $refs', () => {
+      const schema = {
+        allOf: [
+          { $ref: '#/components/schemas/Base' },
+          {
+            type: 'object',
+            properties: {
+              child: { $ref: '#/components/schemas/Child' },
+            },
+          },
+        ],
+      }
+      const refs = collectRefs(schema)
+      expect(refs).toEqual(new Set(['Base', 'Child']))
+    })
+
+    test('should handle arrays', () => {
+      const schema = {
+        type: 'array',
+        items: [{ $ref: '#/components/schemas/Item1' }, { $ref: '#/components/schemas/Item2' }],
+      }
+      const refs = collectRefs(schema)
+      expect(refs).toEqual(new Set(['Item1', 'Item2']))
+    })
+
+    test('should ignore non-component $refs', () => {
+      const schema = {
+        properties: {
+          external: { $ref: 'http://example.com/schema' },
+          internal: { $ref: '#/components/schemas/Internal' },
+        },
+      }
+      const refs = collectRefs(schema)
+      expect(refs).toEqual(new Set(['Internal']))
+    })
+  })
+
+  describe('sortSchemas', () => {
+    test('should sort schemas by dependencies', () => {
+      const schemas: Record<string, SchemaObject> = {
+        Parent: {
+          type: 'object',
+          properties: {
+            child: { $ref: '#/components/schemas/Child' },
+          },
+        },
+        Child: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+          },
+        },
+      }
+
+      const sorted = sortSchemas(schemas)
+      const keys = Object.keys(sorted)
+
+      // Child should come before Parent
+      expect(keys.indexOf('Child')).toBeLessThan(keys.indexOf('Parent'))
+    })
+
+    test('should handle circular dependencies', () => {
+      const schemas: Record<string, SchemaObject> = {
+        A: {
+          type: 'object',
+          properties: {
+            b: { $ref: '#/components/schemas/B' },
+          },
+        },
+        B: {
+          type: 'object',
+          properties: {
+            a: { $ref: '#/components/schemas/A' },
+          },
+        },
+      }
+
+      // Should not throw
+      const sorted = sortSchemas(schemas)
+      expect(Object.keys(sorted)).toHaveLength(2)
+    })
+  })
+
+  describe('extractSchemaFromContent', () => {
+    test('should extract schema from application/json content', () => {
+      const content = {
+        'application/json': {
+          schema: {
+            type: 'object',
+            properties: {
+              id: { type: 'string' },
+            },
+          },
+        },
+      }
+
+      const schema = extractSchemaFromContent(content)
+      expect(schema).toEqual({
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+        },
+      })
+    })
+
+    test('should use preferred content type', () => {
+      const content = {
+        'application/json': {
+          schema: { type: 'string' },
+        },
+        'application/xml': {
+          schema: { type: 'number' },
+        },
+      }
+
+      const schema = extractSchemaFromContent(content, 'application/xml')
+      expect(schema).toEqual({ type: 'number' })
+    })
+
+    test('should return null for $ref schemas', () => {
+      const content = {
+        'application/json': {
+          schema: {
+            $ref: '#/components/schemas/User',
+          },
+        },
+      }
+
+      const schema = extractSchemaFromContent(content)
+      expect(schema).toBeNull()
+    })
+
+    test('should return null for undefined content', () => {
+      const schema = extractSchemaFromContent(undefined)
+      expect(schema).toBeNull()
+    })
+  })
+
+  describe('getSemanticSuffix', () => {
+    test('should return correct suffix for schemas', () => {
+      expect(getSemanticSuffix('schemas')).toBe('Schema')
+    })
+
+    test('should return correct suffix for responses', () => {
+      expect(getSemanticSuffix('responses')).toBe('Response')
+    })
+
+    test('should return correct suffix for requestBodies', () => {
+      expect(getSemanticSuffix('requestBodies')).toBe('Request')
+    })
+  })
+
+  describe('legacyResolve', () => {
+    test('should use original names without collision detection', () => {
+      const schemasWithMeta: SchemaWithMetadata[] = [
+        {
+          schema: { type: 'object' },
+          source: 'schemas',
+          originalName: 'User',
+        },
+        {
+          schema: { type: 'object' },
+          source: 'responses',
+          originalName: 'User',
+        },
+      ]
+
+      const result = legacyResolve(schemasWithMeta)
+
+      // Last one wins (overwrites)
+      expect(Object.keys(result.schemas)).toEqual(['User'])
+      expect(result.nameMapping.get('#/components/responses/User')).toBe('User')
+    })
+  })
+
+  describe('resolveCollisions', () => {
+    test('should handle no collisions', () => {
+      const schemasWithMeta: SchemaWithMetadata[] = [
+        {
+          schema: { type: 'object' },
+          source: 'schemas',
+          originalName: 'User',
+        },
+        {
+          schema: { type: 'object' },
+          source: 'schemas',
+          originalName: 'Product',
+        },
+      ]
+
+      const result = resolveCollisions(schemasWithMeta)
+
+      expect(Object.keys(result.schemas)).toEqual(['User', 'Product'])
+      expect(result.nameMapping.get('#/components/schemas/User')).toBe('User')
+      expect(result.nameMapping.get('#/components/schemas/Product')).toBe('Product')
+    })
+
+    test('should add semantic suffixes for cross-component collisions', () => {
+      const schemasWithMeta: SchemaWithMetadata[] = [
+        {
+          schema: { type: 'object', properties: { id: { type: 'string' } } },
+          source: 'schemas',
+          originalName: 'Order',
+        },
+        {
+          schema: { type: 'object', properties: { items: { type: 'array' } } },
+          source: 'requestBodies',
+          originalName: 'Order',
+        },
+      ]
+
+      const result = resolveCollisions(schemasWithMeta)
+
+      expect(Object.keys(result.schemas)).toEqual(['OrderSchema', 'OrderRequest'])
+      expect(result.nameMapping.get('#/components/schemas/Order')).toBe('OrderSchema')
+      expect(result.nameMapping.get('#/components/requestBodies/Order')).toBe('OrderRequest')
+    })
+
+    test('should add numeric suffixes for same-component collisions', () => {
+      const schemasWithMeta: SchemaWithMetadata[] = [
+        {
+          schema: { type: 'string', enum: ['A', 'B'] },
+          source: 'schemas',
+          originalName: 'Variant',
+        },
+        {
+          schema: { type: 'string', enum: ['X', 'Y'] },
+          source: 'schemas',
+          originalName: 'variant',
+        },
+      ]
+
+      const result = resolveCollisions(schemasWithMeta)
+
+      expect(Object.keys(result.schemas)).toEqual(['Variant', 'variant2'])
+      expect(result.nameMapping.get('#/components/schemas/Variant')).toBe('Variant')
+      expect(result.nameMapping.get('#/components/schemas/variant')).toBe('variant2')
+    })
+
+    test('should handle case-insensitive collisions', () => {
+      const schemasWithMeta: SchemaWithMetadata[] = [
+        {
+          schema: { type: 'object', description: 'first' },
+          source: 'schemas',
+          originalName: 'User',
+        },
+        {
+          schema: { type: 'object', description: 'second' },
+          source: 'schemas',
+          originalName: 'user',
+        },
+      ]
+
+      const result = resolveCollisions(schemasWithMeta)
+
+      // Should detect as collision and add numeric suffixes
+      expect(Object.keys(result.schemas)).toEqual(['User', 'user2'])
+      expect(result.schemas['User']).toBeDefined()
+      expect(result.schemas['user2']).toBeDefined()
+    })
+  })
 })