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

package/src/resolvers.ts

@@ -59,9 +59,9 @@ export function getSchemaType(format: string): ast.SchemaType | null {
 }
 
 /**
- * Whether the parser maps `format` to a dedicated type. True for any `formatMap` entry and the
- * `specialCasedFormats` `convertFormat` handles directly. False means the format falls back to the
- * base type, which is what `KUBB_UNSUPPORTED_FORMAT` flags. Reading both sources keeps the
+ * Whether the parser maps `format` to a dedicated type. True for any `formatMap` entry, plus the
+ * `specialCasedFormats` that `convertFormat` handles directly. False means the format falls back to
+ * the base type, which is what `KUBB_UNSUPPORTED_FORMAT` flags. Reading both sources keeps the
  * diagnostic in step with the parser as `formatMap` grows.
  */
 export function isHandledFormat(format: string): boolean {
@@ -86,7 +86,7 @@ export type OperationsOptions = {
 /**
  * Returns all parameters for an operation, merging path-level and operation-level entries.
  * Operation-level parameters override path-level ones with the same `in:name` key.
- * `$ref` parameters resolve via `dereferenceWithRef` for backward compatibility.
+ * Each `$ref` parameter is dereferenced via `dereferenceWithRef` before merging.
  *
  * @example
  * ```ts
@@ -220,7 +220,8 @@ export function getRequestSchema(document: Document, operation: Operation, optio
 type SchemaSourceMode = 'schemas' | 'responses' | 'requestBodies'
 
 /**
- * A schema annotated with its component section source and original name. Used by `resolveNameCollisions` for cross-source collision resolution.
+ * A schema annotated with its component section source and original name. `getSchemas` uses this
+ * to resolve name collisions across sources.
  */
 type SchemaWithMetadata = {
   schema: SchemaObject
@@ -234,6 +235,10 @@ export type GetSchemasOptions = {
 
 export type GetSchemasResult = {
   schemas: Record<string, SchemaObject>
+  /**
+   * Maps each original component pointer (`#/components/<source>/<name>`) to the
+   * collision-resolved unique name used as the key in `schemas`.
+   */
   nameMapping: Map<string, string>
 }
 
@@ -248,7 +253,10 @@ export type GetSchemasResult = {
  * ```ts
  * flattenSchema({ allOf: [{ description: 'A pet' }], type: 'object', properties: {} })
  * // { type: 'object', properties: {}, description: 'A pet' }
+ * ```
  *
+ * @example
+ * ```ts
  * flattenSchema({ allOf: [{ $ref: '#/components/schemas/Pet' }] })
  * // returned unchanged, contains a $ref
  * ```

package/src/stream.ts

@@ -1,6 +1,7 @@
-import { containsCircularRef, findCircularSchemas } from '@kubb/ast/utils'
+import { findCircularSchemas } from '@kubb/ast/utils'
 import { ast } from '@kubb/core'
-import { SCHEMA_REF_PREFIX } from './constants.ts'
+import type { Plan } from './dedupe.ts'
+import { oasDialect } from './dialect.ts'
 import { buildDiscriminatorChildMap, patchDiscriminatorNode } from './discriminator.ts'
 import { getOperations } from './operation.ts'
 import type { SchemaParser } from './parser.ts'
@@ -14,53 +15,7 @@ export type PreScanResult = {
   enumNames: Array<string>
   circularNames: Array<string>
   discriminatorChildMap: Map<string, DiscriminatorTarget> | null
-  dedupePlan: ast.DedupePlan | null
-}
-
-/**
- * Builds the deduplication plan from the already-parsed top-level schema nodes plus a
- * single extra parse pass over operations (so duplicates in request/response bodies are seen).
- *
- * Only enums and objects are candidates, and object shapes that reference a circular schema are
- * rejected to avoid hoisting recursive structures. Inline shapes reuse their context-derived
- * name (collision-resolved against existing component names). Shapes without a name stay inline.
- */
-function createDedupePlan({
-  schemaNodes,
-  operationNodes,
-  schemaNames,
-  circularNames,
-}: {
-  schemaNodes: Array<ast.SchemaNode>
-  operationNodes: Array<ast.OperationNode>
-  schemaNames: Array<string>
-  circularNames: Array<string>
-}): ast.DedupePlan {
-  const circularSchemas = new Set(circularNames)
-  const usedNames = new Set(schemaNames)
-
-  return ast.buildDedupePlan([...schemaNodes, ...operationNodes], {
-    isCandidate: (node) => {
-      if (node.type === 'enum') return true
-      if (node.type !== 'object') return false
-      // Skip object shapes that are part of a circular chain, hoisting them would break the cycle.
-      if (node.name && circularSchemas.has(node.name)) return false
-      return !containsCircularRef(node, { circularSchemas })
-    },
-    nameFor: (node) => {
-      const base = node.name
-      if (!base) return null
-
-      let name = base
-      let counter = 2
-      while (usedNames.has(name)) {
-        name = `${base}${counter++}`
-      }
-      usedNames.add(name)
-      return name
-    },
-    refFor: (name) => `${SCHEMA_REF_PREFIX}${name}`,
-  })
+  dedupePlan: Plan | null
 }
 
 /**
@@ -153,7 +108,7 @@ export function preScan({
   const circularNames = [...findCircularSchemas(allNodes)]
   const discriminatorChildMap = discriminatorParentNodes.length > 0 ? buildDiscriminatorChildMap(discriminatorParentNodes) : null
 
-  let dedupePlan: ast.DedupePlan | null = null
+  let dedupePlan: Plan | null = null
   if (dedupe) {
     // One extra parse pass over operations so duplicates in request/response bodies are seen.
     // Reuses the already-parsed `allNodes` for schemas, no second schema parse.
@@ -163,17 +118,19 @@ export function preScan({
       if (operationNode) operationNodes.push(operationNode)
     }
 
-    dedupePlan = createDedupePlan({ schemaNodes: allNodes, operationNodes, schemaNames: Object.keys(schemas), circularNames })
+    const circularSchemas = new Set(circularNames)
+    const usedNames = new Set(Object.keys(schemas))
 
-    for (const definition of dedupePlan.hoisted) {
+    dedupePlan = oasDialect.dedupe.plan([...allNodes, ...operationNodes], { circularSchemas, usedNames })
+
+    for (const definition of dedupePlan.extracted) {
       if (definition.type === 'enum' && definition.name) enumNames.push(definition.name)
     }
   }
 
   // Enum names that duplicate an earlier schema's content are never emitted, so they are not
   // advertised to plugins either.
-  const aliasNames = dedupePlan?.aliasNames
-  const emittedEnumNames = aliasNames && aliasNames.size > 0 ? enumNames.filter((name) => !aliasNames.has(name)) : enumNames
+  const emittedEnumNames = dedupePlan ? enumNames.filter((name) => !dedupePlan.isAlias(name)) : enumNames
 
   return { refAliasMap, enumNames: emittedEnumNames, circularNames, discriminatorChildMap, dedupePlan }
 }
@@ -214,55 +171,36 @@ export function createInputStream({
   parserOptions: ast.ParserOptions
   refAliasMap: Map<string, ast.SchemaNode>
   discriminatorChildMap: Map<string, DiscriminatorTarget> | null
-  dedupePlan: ast.DedupePlan | null
+  dedupePlan: Plan | null
   meta: ast.InputMeta
 }): ast.InputNode<true> {
-  // Rewrites a top-level schema against the dedupe plan: a structurally identical sibling
-  // becomes a `ref` alias to the canonical one (keeping its own name). Otherwise nested
-  // duplicates are collapsed while the schema's own root is preserved.
-  const rewriteTopLevelSchema = (node: ast.SchemaNode): ast.SchemaNode => {
-    if (!dedupePlan) return node
-
-    const canonical = dedupePlan.canonicalBySignature.get(ast.signatureOf(node))
-    if (canonical && canonical.name !== node.name) {
-      return ast.factory.createSchema({
-        type: 'ref',
-        name: node.name ?? null,
-        ref: canonical.ref,
-        description: node.description,
-        deprecated: node.deprecated,
-      })
-    }
-
-    return ast.applyDedupe(node, dedupePlan, true)
-  }
-
   const schemasIterable: AsyncIterable<ast.SchemaNode> = {
     [Symbol.asyncIterator]() {
       return (async function* () {
-        // Hoisted canonical definitions are emitted first so the schema list owns the shared shapes.
+        // Extracted shared definitions are emitted first so the schema list owns the shared shapes.
         if (dedupePlan) {
-          for (const definition of dedupePlan.hoisted) yield definition
+          for (const definition of dedupePlan.extracted) yield definition
         }
 
         for (const [name, schema] of Object.entries(schemas)) {
           // A top-level schema whose content duplicates an earlier one is not emitted: every
           // ref to it is repointed at the first schema with that content, so its model would
           // be dead code.
-          if (dedupePlan?.aliasNames.has(name)) continue
+          if (dedupePlan?.isAlias(name)) continue
 
           // Inline ref aliases: replace the alias entry with its target's parsed node
           // (keeping the alias name). Skip the first parse entirely for alias entries
           // since that result is never used.
           const alias = refAliasMap.get(name)
           if (alias?.name && schemas[alias.name]) {
-            yield rewriteTopLevelSchema({ ...parseSchema({ schema: schemas[alias.name]!, name: alias.name }, parserOptions), name })
+            const aliasNode = { ...parseSchema({ schema: schemas[alias.name]!, name: alias.name }, parserOptions), name }
+            yield dedupePlan ? dedupePlan.applyTopLevel(aliasNode) : aliasNode
             continue
           }
 
           const parsed = parseSchema({ schema, name }, parserOptions)
           const node = discriminatorChildMap?.get(name) ? patchDiscriminatorNode(parsed, discriminatorChildMap.get(name)!) : parsed
-          yield rewriteTopLevelSchema(node)
+          yield dedupePlan ? dedupePlan.applyTopLevel(node) : node
         }
       })()
     },
@@ -273,7 +211,7 @@ export function createInputStream({
       return (async function* () {
         for (const operation of getOperations(document)) {
           const node = parseOperation(parserOptions, operation)
-          if (node) yield dedupePlan ? ast.applyDedupe(node, dedupePlan) : node
+          if (node) yield dedupePlan ? dedupePlan.apply(node) : node
         }
       })()
     },

package/src/types.ts

@@ -218,7 +218,7 @@ export type AdapterOasResolvedOptions = {
   enumSuffix: AdapterOasOptions['enumSuffix']
   /**
    * Map from original `$ref` paths to their collision-resolved schema names.
-   * Populated after each `parse()` call.
+   * Populated once the adapter resolves a spec's schemas, on the first `stream()` or `parse()`.
    *
    * @example
    * ```ts