galbe 0.13.0 → 0.14.0

package/bin/commands/generate/code/openapi.parser.ts

@@ -2,7 +2,6 @@ import { semver } from 'bun'
 import { transformSync } from '@swc/core'
 import { resolve, relative, dirname } from 'path'
 import { OpenAPIV3 } from 'openapi-types'
-import { inferBodyType } from '../../../../src/util'
 
 type SchemaEntry = {
   key: string
@@ -10,6 +9,13 @@ type SchemaEntry = {
   schema: string
   dependsOn: Set<string>
   usedBy: Set<string>
+  /** Response-only: the original component-level description, kept distinct
+   * from the inner schema's own description. */
+  responseDescription?: string
+  /** Response-only: content-level single example. */
+  responseExample?: any
+  /** Response-only: content-level multi-key examples. */
+  responseExamples?: Record<string, any>
 }
 type EndpointEntry = {
   version?: string
@@ -46,14 +52,15 @@ const refToPath = (ref: string, basePath?: string) => {
 const orderDeps = (deps: Record<string, SchemaEntry>) => {
   let stack = Object.keys(deps)
   let l = new Set<string>()
-  const ascend = (d: { dependsOn: Set<string> }) => {
-    for (let p of d.dependsOn.keys()) {
+  const ascend = (d: { dependsOn: Set<string> }, visiting: Set<string>) => {
+    for (let p of d.dependsOn) {
+      if (visiting.has(p) || l.has(p)) continue
       if (p in deps) {
-        ascend(deps[p])
-        if (p in deps && !l.has(p)) {
-          l.add(p)
-          stack.splice(stack.indexOf(p), 1)
-        }
+        visiting.add(p)
+        ascend(deps[p], visiting)
+        l.add(p)
+        let idx = stack.indexOf(p)
+        if (idx >= 0) stack.splice(idx, 1)
       }
     }
   }
@@ -61,7 +68,7 @@ const orderDeps = (deps: Record<string, SchemaEntry>) => {
     let k = stack.pop()
     if (!k) continue
     let d = deps[k]
-    ascend(d)
+    ascend(d, new Set([k]))
     if (!l.has(k)) {
       l.add(k)
     }
@@ -70,9 +77,12 @@ const orderDeps = (deps: Record<string, SchemaEntry>) => {
 }
 const serialize = (obj: any) => {
   return JSON.stringify(obj, (k, value) => {
-    if (k === 'pattern' && value) return `/${value}/`
+    if (k === 'pattern' && value) return `__PATTERN__${value}__ENDPATTERN__`
     return value
-  }).replace(/"\/(.*)\/([gimsuy]*)"/g, '/$1/$2')
+  }).replace(/"__PATTERN__([\s\S]*?)__ENDPATTERN__"/g, (_, body) => {
+    const decoded = JSON.parse(`"${body}"`) as string
+    return `/${decoded.replace(/\//g, '\\/')}/`
+  })
 }
 
 const writeCodeFile = async (path: string, content: string, target: 'js' | 'ts') => {
@@ -110,17 +120,22 @@ const parseOapiSchema = (
     minLength?: number
     maxLength?: number
     pattern?: string
+    format?: string
     minItems?: number
     maxItems?: number
     unique?: boolean
+    default?: any
+    examples?: any
   } = {
     ...details,
     title: os.title,
     description: details.description || os.description,
+    default: os.default,
+    ...(os.example !== undefined ? { examples: os.example } : {}),
   }
 
   let resp = ''
-  let hasOptions = Object.values(options).some(v => !!v)
+  let hasOptions = Object.values(options).some(v => v !== undefined)
   let optArg = hasOptions ? serialize(options) : ''
   let anyOf = os.oneOf || os.anyOf
   let allOf = os.allOf
@@ -139,9 +154,8 @@ const parseOapiSchema = (
   } else if (anyOf?.length) {
     if (anyOf.length === 1) resp = parseOapiSchema(anyOf[0] as OpenAPIV3.SchemaObject, details, extra)
     else {
-      resp = `$T.union([${anyOf.map(s => parseOapiSchema(s as OpenAPIV3.SchemaObject)).join(',')}], ${serialize(
-        options
-      )})`
+      const builder = os.oneOf ? '$T.oneOf' : '$T.anyOf'
+      resp = `${builder}([${anyOf.map(s => parseOapiSchema(s as OpenAPIV3.SchemaObject)).join(',')}]${optArg ? `, ${optArg}` : ''})`
     }
   } else if (allOf?.length) {
     if (allOf.length === 1) resp = parseOapiSchema(allOf[0] as OpenAPIV3.SchemaObject, details, extra)
@@ -151,7 +165,7 @@ const parseOapiSchema = (
       )})`
     }
   } else if (!os?.type) {
-    return `$T.any(${details && Object.keys(details).length ? JSON.stringify(details) : ''})`
+    return `$T.any(${hasOptions ? optArg : ''})`
   } else if (os.type === 'boolean') resp = `$T.boolean(${hasOptions ? serialize(options) : ''})`
   else if (os.type === 'number') {
     let { max, min, exclusiveMax, exclusiveMin } = {
@@ -161,7 +175,7 @@ const parseOapiSchema = (
       exclusiveMin: os.minimum !== undefined && os.exclusiveMinimum ? os.minimum : undefined,
     }
     options = { ...options, min, max, exclusiveMax, exclusiveMin }
-    hasOptions = Object.values(options).some(v => !!v)
+    hasOptions = Object.values(options).some(v => v !== undefined)
     resp = `$T.number(${hasOptions ? serialize(options) : ''})`
   } else if (os.type === 'integer') {
     let max = os.maximum !== undefined && !os.exclusiveMaximum ? os.maximum : undefined
@@ -169,35 +183,43 @@ const parseOapiSchema = (
     let exclusiveMax = os.maximum !== undefined && os.exclusiveMaximum ? os.maximum : undefined
     let exclusiveMin = os.minimum !== undefined && os.exclusiveMinimum ? os.minimum : undefined
     options = { ...options, min, max, exclusiveMax, exclusiveMin }
-    hasOptions = Object.values(options).some(v => !!v)
+    hasOptions = Object.values(options).some(v => v !== undefined)
     resp = `$T.integer(${hasOptions ? serialize(options) : ''})`
   } else if (os.type === 'string') {
     if (os.format === 'binary') resp = `$T.byteArray(${hasOptions ? serialize(options) : ''})`
     else if (os.enum?.length === 1) {
       resp = `$T.literal("${os.enum[0]}")`
     } else if (os.enum?.length) {
-      resp = `$T.union([${os.enum.map(v => `$T.literal("${v}")`).join(', ')}])`
+      const literals = os.enum.map(v => `$T.literal("${v}")`).join(', ')
+      resp = `$T.union([${literals}]${optArg ? `, ${optArg}` : ''})`
     } else {
       let minLength = os.minLength
       let maxLength = os.maxLength
       let pattern = os.pattern
-      options = { ...options, minLength, maxLength, pattern }
-      hasOptions = Object.values(options).some(v => !!v)
+      let format = os.format
+      options = { ...options, minLength, maxLength, pattern, format }
+      hasOptions = Object.values(options).some(v => v !== undefined)
       resp = `$T.string(${hasOptions ? serialize(options) : ''})`
     }
   } else if (os.type === 'array') {
-    let minItems = os.minItems
-    let maxItems = os.maxItems
+    // Galbe's ArrayOptions uses minLength/maxLength/unique (mirroring the
+    // builder API), not OpenAPI's minItems/maxItems/uniqueItems names.
+    let minLength = os.minItems
+    let maxLength = os.maxItems
     let unique = os.uniqueItems
-    options = { ...options, minItems, maxItems, unique }
-    resp = `$T.array(${parseOapiSchema(os?.items)}, ${optArg})`
+    options = { ...options, minLength, maxLength, unique }
+    hasOptions = Object.values(options).some(v => v !== undefined)
+    optArg = hasOptions ? serialize(options) : ''
+    resp = `$T.array(${parseOapiSchema(os?.items)}${optArg ? `, ${optArg}` : ''})`
   } else if (os.type === 'object') {
+    let required = new Set(os.required || [])
     let props = Object.entries(os?.properties || {})
       .map(([k, v]) => {
         v = v as OpenAPIV3.SchemaObject
+        const isRequired = required.has(k)
         const w = (s: string) => {
-          if (!v.required && v.nullable) return `$T.nullish(${s})`
-          else if (!v.required) return `$T.optional(${s})`
+          if (!isRequired && v.nullable) return `$T.nullish(${s})`
+          else if (!isRequired) return `$T.optional(${s})`
           else if (v.nullable) return `$T.nullable(${s})`
           return s
         }
@@ -222,21 +244,48 @@ const buildSchemaIndex = (def: OpenAPIV3.Document) => {
   const initSchema = (k: string, s: any, kind: 'schemas' | 'requestBodies' | 'responses') => {
     let schema = ''
     let dependsOn = new Set<string>()
+    let responseExample: any = undefined
+    let responseExamples: Record<string, any> | undefined = undefined
     if (kind === 'schemas') schema = parseOapiSchema(s, { id: k })
-    else if (kind === 'requestBodies' || kind === 'responses') {
+    else if (kind === 'requestBodies') {
       let schemas = [] as string[]
       if (!!s.content) {
-        schemas = [
-          ...new Set(
-            Object.entries((s as OpenAPIV3.RequestBodyObject)?.content || { null: {} }).map(([media, v]) => {
-              return parseOapiSchema(v.schema, { id: k }, { media })
-            })
-          ),
-        ]
+        const contentMap = (s as OpenAPIV3.RequestBodyObject)?.content || { null: {} }
+        schemas = [...new Set(Object.entries(contentMap).map(([media, v]) => parseOapiSchema(v.schema, { id: k }, { media })))]
       } else {
         schemas = [parseOapiSchema(undefined, { id: k, ...s })]
       }
       schema = schemas.length <= 0 ? '' : schemas.length === 1 ? schemas[0] : `$T.union([${schemas.join(',')}])`
+    } else if (kind === 'responses') {
+      if (!s.content) {
+        schema = parseOapiSchema(undefined, { id: k, ...s })
+      } else {
+        const contentMap = s.content as Record<string, { schema?: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject; example?: any; examples?: any }>
+        const entries = Object.entries(contentMap)
+        for (const [, v] of entries) {
+          if (v.example !== undefined && responseExample === undefined) responseExample = v.example
+          if (v.examples && Object.keys(v.examples).length) responseExamples = { ...(responseExamples || {}), ...v.examples }
+        }
+        const keyGroups: Record<string, string[]> = {}
+        for (const [media, v] of entries) {
+          const galbeKey = media
+          const schemaStr = parseOapiSchema(v.schema, {}, { media })
+          if (!keyGroups[galbeKey]) keyGroups[galbeKey] = []
+          keyGroups[galbeKey].push(schemaStr)
+        }
+        const uniqueKeys = Object.keys(keyGroups)
+        if (uniqueKeys.length <= 1) {
+          const [key] = uniqueKeys
+          const uniqueSchemas = [...new Set(keyGroups[key] || [])]
+          schema = uniqueSchemas.length === 0 ? '' : uniqueSchemas.length === 1 ? uniqueSchemas[0] : `$T.union([${uniqueSchemas.join(',')}])`
+        } else {
+          const parts = Object.entries(keyGroups).map(([k, schemas]) => {
+            const unique = [...new Set(schemas)]
+            return `"${k}": ${unique.length === 1 ? unique[0] : `$T.union([${unique.join(',')}])`}`
+          })
+          schema = `{${parts.join(',')}}`
+        }
+      }
     }
     schema = unref(schema, m => {
       let l = m.split('/')
@@ -249,6 +298,11 @@ const buildSchemaIndex = (def: OpenAPIV3.Document) => {
       schema,
       dependsOn,
       usedBy: new Set(),
+      ...(kind === 'responses' && typeof s?.description === 'string' && s.description
+        ? { responseDescription: s.description }
+        : {}),
+      ...(kind === 'responses' && responseExample !== undefined ? { responseExample } : {}),
+      ...(kind === 'responses' && responseExamples ? { responseExamples } : {}),
     }
   }
   for (let [k, v] of Object.entries(def.components?.schemas || {})) initSchema(k, v, 'schemas')
@@ -256,35 +310,77 @@ const buildSchemaIndex = (def: OpenAPIV3.Document) => {
   for (let [k, v] of Object.entries(def.components?.responses || {})) initSchema(k, v, 'responses')
 
   Object.entries(index).forEach(([k, v]) => {
-    for (let d of v.dependsOn) index[d].usedBy.add(k)
+    for (let d of v.dependsOn) index[d]?.usedBy.add(k)
   })
 
   return index
 }
 
-const parseEndpointDef = (method: string, path: string, def?: OpenAPIV3.OperationObject) => {
+const resolveParamRef = (
+  ref: string,
+  components: OpenAPIV3.ComponentsObject | undefined
+): OpenAPIV3.ParameterObject | undefined => {
+  let match = ref.match(/^#\/components\/parameters\/(.+)$/)
+  if (!match) return undefined
+  let target = components?.parameters?.[match[1]]
+  if (!target) return undefined
+  if ('$ref' in target) return resolveParamRef(target.$ref, components)
+  return target
+}
+
+const parseEndpointDef = (
+  method: string,
+  path: string,
+  def?: OpenAPIV3.OperationObject,
+  components?: OpenAPIV3.ComponentsObject
+) => {
   if (!def) return {}
-  let imports = {}
+  let imports: Record<string, string> = {}
   let p = path.replaceAll(/\{([^\}]*)\}/g, ':$1')
   // let description = def.summary || def.description
-  let pathName = path.replaceAll(/\/\{[^\}]*\}/g, 'X').replaceAll(/[^$\w\d_]+([$\w\d_])/g, (_, $1) => $1.toUpperCase())
-  let schemaName = `${method}${pathName}`.replace(/^\w/, c => c.toUpperCase())
+  let schemaName = def.operationId
+    ? def.operationId.replace(/^\w/, c => c.toUpperCase())
+    : `${method}${path
+        .replaceAll(/\{([^\}]+)\}/g, (_, p) => `By${p.replace(/^\w/, (c: string) => c.toUpperCase())}`)
+        .replaceAll(/[^$\w\d_]+([$\w\d_])/g, (_, $1) => $1.toUpperCase())
+      }`.replace(/^\w/, c => c.toUpperCase())
 
   let meta = '/**\n'
   if (def.summary) meta += ` * ${def.summary}\n *\n`
   if (def.description) meta += ` * ${def.description.replace(/\n/g, '\n * ')}\n`
   if (def.operationId) meta += ` * @operationId ${def.operationId}\n`
-  if (def.externalDocs) meta += ` * @externalDocs ${def.externalDocs}\n`
+  if (def.externalDocs?.url) meta += ` * @externalDocs ${def.externalDocs.url}\n`
   if (def.tags) meta += ` * @tags ${def.tags.join(' ')}\n`
-  if (def.deprecated) meta == ' * @deprecated\n'
+  if (Array.isArray(def.security)) {
+    if (def.security.length === 0) {
+      meta += ` * @security none\n`
+    } else {
+      for (const s of def.security) {
+        const keys = Object.keys(s)
+        if (keys.length === 0) {
+          meta += ` * @security none\n`
+        } else {
+          for (const k of keys) {
+            const scopes = (s as any)[k] as string[]
+            meta += ` * @security ${k}${scopes && scopes.length ? ` ${scopes.join(' ')}` : ''}\n`
+          }
+        }
+      }
+    }
+  }
+  if (def.deprecated) meta += ' * @deprecated\n'
   meta += ' */'
   let endpoint = `${method}("${p}", ${schemaName}, ctx => {\n  throw new NotImplementedError()\n})`
 
-  let sp = { path: {}, query: {}, header: {}, body: {}, formData: {} } // TODO handle body and formData cases
+  let sp: Record<string, Record<string, string>> = { path: {}, query: {}, header: {}, body: {}, formData: {} } // TODO handle body and formData cases
+
   for (let _p of def?.parameters || []) {
-    // @ts-ignore: TODO handle refs cases
-    if (_p.$ref) continue
-    let p = _p as OpenAPIV3.ParameterObject
+    let p: OpenAPIV3.ParameterObject | undefined
+    if ('$ref' in _p) {
+      p = resolveParamRef(_p.$ref, components)
+      if (!p) continue
+    } else p = _p as OpenAPIV3.ParameterObject
+    if (!sp[p.in]) continue
     let o = (s: string) => {
       const [_, so] = [...(s.match(/^\$T.optional\((.*)\)$/) || [])]
       s = so ?? s
@@ -335,7 +431,7 @@ const parseEndpointDef = (method: string, path: string, def?: OpenAPIV3.Operatio
           ])
         ),
       ]
-      body = bs.length ? `  body: {${bs.map(([k, v]) => `"${inferBodyType(k)}":${o(v)}`).join(',')}}` : ''
+      body = bs.length ? `  body: {${bs.map(([k, v]) => `"${k}":${o(v)}`).join(',')}}` : ''
     }
   }
 
@@ -343,7 +439,6 @@ const parseEndpointDef = (method: string, path: string, def?: OpenAPIV3.Operatio
   let r = def?.responses
   let rs = Object.fromEntries(
     Object.entries(r || {}).map(([status, sv]) => {
-      let entries: string[] = []
       let s: string = Number.isInteger(Number(status)) ? status : 'default'
 
       //@ts-ignore
@@ -354,27 +449,91 @@ const parseEndpointDef = (method: string, path: string, def?: OpenAPIV3.Operatio
             return l[l.length - 1]
           })
         : null
-      if (rootRef) {
-        return [s, [rootRef]]
-      }
-
-      for (let [_type, tv] of Object.entries((sv as OpenAPIV3.ResponseObject)?.content || {})) {
-        entries.push(
-          unref(parseOapiSchema(tv.schema), m => {
+      if (rootRef) return [s, rootRef]
+
+      const respObj = sv as OpenAPIV3.ResponseObject
+      const content = respObj?.content || {}
+
+      // Collect response-level headers
+      const headerEntries: string[] = []
+      for (const [hName, hVal] of Object.entries(respObj?.headers || {})) {
+        if ('$ref' in (hVal as any)) continue
+        const h = hVal as OpenAPIV3.HeaderObject
+        const headerSchema = unref(
+          parseOapiSchema(h.schema || ({ type: 'string' } as any), { description: h.description }),
+          m => {
             let l = m.split('/')
             imports[l[l.length - 1]] = m
             return l[l.length - 1]
-          })
+          }
         )
+        headerEntries.push(`${JSON.stringify(hName)}:${h.required ? headerSchema : `$T.optional(${headerSchema})`}`)
+      }
+      const description = typeof respObj?.description === 'string' && respObj.description ? respObj.description : undefined
+
+      if (Object.keys(content).length === 0) {
+        let nullSchema = description ? `$T.null({description:${JSON.stringify(description)}})` : `$T.null()`
+        if (headerEntries.length) nullSchema = `({...${nullSchema}, responseHeaders:{${headerEntries.join(',')}}})`
+        return [s, nullSchema]
+      }
+
+      // Group schemas by galbe body key, collect examples
+      const keyGroups: Record<string, string[]> = {}
+      const exampleParts: string[] = []
+      let singleExample: any = undefined
+      for (const [mediaType, tv] of Object.entries(content)) {
+        const galbeKey = mediaType
+        if ((tv as any).example !== undefined && singleExample === undefined) singleExample = (tv as any).example
+        if (tv.examples && Object.keys(tv.examples).length) {
+          for (const [k, ex] of Object.entries(tv.examples)) exampleParts.push(`${JSON.stringify(k)}:${JSON.stringify(ex)}`)
+        }
+        const schemaStr = unref(parseOapiSchema(tv.schema), m => {
+          let l = m.split('/')
+          imports[l[l.length - 1]] = m
+          return l[l.length - 1]
+        })
+        if (!keyGroups[galbeKey]) keyGroups[galbeKey] = []
+        keyGroups[galbeKey].push(schemaStr)
+      }
+
+      const uniqueKeys = Object.keys(keyGroups)
+
+      if (uniqueKeys.length > 1) {
+        // Multiple body keys → STResponseContent object
+        const parts: string[] = []
+        for (const [key, schemas] of Object.entries(keyGroups)) {
+          const unique = [...new Set(schemas)]
+          parts.push(`"${key}": ${unique.length === 1 ? unique[0] : `$T.union([${unique.join(',')}])`}`)
+        }
+        if (description) parts.push(`description: ${JSON.stringify(description)}`)
+        if (headerEntries.length) parts.push(`responseHeaders: {${headerEntries.join(',')}}`)
+        if (exampleParts.length) parts.push(`examples: {${exampleParts.join(',')}}`)
+        if (singleExample !== undefined) parts.push(`example: ${JSON.stringify(singleExample)}`)
+        return [s, `{${parts.join(',')}}`]
+      } else {
+        // Single body key → STResponseContent object (preserves exact media type key)
+        const [key] = uniqueKeys
+        const unique = [...new Set(keyGroups[key] || [])]
+        let schemaStr = unique.length === 0 ? `$T.null()` : unique.length === 1 ? unique[0] : `$T.union([${unique.join(',')}])`
+        // Embed per-media-type example/examples inside the schema spread so the
+        // content-map serializer can read them from the per-key body schema.
+        const perKeyExtras: string[] = []
+        if (exampleParts.length) perKeyExtras.push(`examples:{${exampleParts.join(',')}}`)
+        if (singleExample !== undefined) perKeyExtras.push(`example:${JSON.stringify(singleExample)}`)
+        if (perKeyExtras.length) schemaStr = `({...${schemaStr},${perKeyExtras.join(',')}})`
+        const parts: string[] = []
+        if (key) parts.push(`"${key}":${schemaStr}`)
+        if (description) parts.push(`description:${JSON.stringify(description)}`)
+        if (headerEntries.length) parts.push(`responseHeaders:{${headerEntries.join(',')}}`)
+        return [s, `{${parts.join(',')}}`]
       }
-      return [s, [...new Set(entries)]]
     })
   )
 
   if (Object.keys(rs).length) {
     resp = `  response: {${Object.entries(rs)
-      .filter(([_, v]) => v.length)
-      .map(([s, v]) => `${s}: ${v.length === 1 ? v[0] : v.length > 1 ? `$T.union([${v.join(',')}])` : ''}`)
+      .filter(([_, v]) => v)
+      .map(([s, v]) => `${s}: ${v}`)
       .join(',')}}`
   } else resp = ''
 
@@ -397,18 +556,34 @@ const parseEndpoints = (def: OpenAPIV3.Document) => {
   let endpoints: Record<string, EndpointEntry> = {}
   for (let [fullPath, pathVal] of Object.entries(def.paths || {})) {
     if (!pathVal) continue
-    let match = fullPath.match(/^\/?(v\d+[^\/]*\/)?(?:\/?(public|private))?\/?([^\/]+)\/?(.*)$/)
+    let match = fullPath.match(/^\/?(?:(v\d+)[^\/]*\/)?(?:\/?(public|private))?\/?([^\/]+)\/?(.*)$/)
     if (!match) continue
     let [_, version, visibility, scope, path] = [...match]
     path = `/${path}`
     let methods = ['get', 'put', 'patch', 'post', 'delete', 'options', 'head'] as const
+    let pathParams = pathVal.parameters || []
     for (let m of methods) {
       let endpointDef = pathVal?.[m]
       if (!endpointDef) continue
       let ref = `#/paths${version ? `/${version}` : ''}${visibility ? `/${visibility}` : ''}${
         scope ? `/${scope}` : ''
       }/${m}${path}`
-      let { schema, endpoint } = parseEndpointDef(m, fullPath, endpointDef)
+      let opParams = endpointDef.parameters || []
+      let opKeys = new Set(
+        opParams
+          .map(p => {
+            let resolved = '$ref' in p ? resolveParamRef(p.$ref, def.components) : (p as OpenAPIV3.ParameterObject)
+            return resolved ? `${resolved.in}:${resolved.name}` : null
+          })
+          .filter((k): k is string => k !== null)
+      )
+      let inheritedParams = pathParams.filter(p => {
+        let resolved = '$ref' in p ? resolveParamRef(p.$ref, def.components) : (p as OpenAPIV3.ParameterObject)
+        if (!resolved) return false
+        return !opKeys.has(`${resolved.in}:${resolved.name}`)
+      })
+      let mergedDef = { ...endpointDef, parameters: [...inheritedParams, ...opParams] }
+      let { schema, endpoint } = parseEndpointDef(m, fullPath, mergedDef, def.components)
       endpoints[ref] = {
         version,
         visibility: visibility as 'public' | 'private',
@@ -423,56 +598,120 @@ const parseEndpoints = (def: OpenAPIV3.Document) => {
   return endpoints
 }
 
-const writeFiles = async (
-  path: string,
-  endpoints: Record<string, EndpointEntry>,
-  schemaIndex: Record<string, SchemaEntry>,
-  target: 'js' | 'ts'
-) => {
-  const typeMap = {
-    schemas: 'commons',
-    requestBodies: 'requests',
-    responses: 'responses',
-  }
-  const parseSchemasToFile = (
-    schemas: Record<string, SchemaEntry>,
-    type: 'schemas' | 'requestBodies' | 'responses'
-  ) => {
-    if (Object.keys(schemas).length === 0) return ''
-    let imports: Record<string, string[]> = {}
-    let decl: string[] = []
-    Object.entries(schemas).forEach(([k, s]) => {
-      if (s.key === s.schema && s.dependsOn.size === 1) {
-        let depMatch = [...s.dependsOn][0].match(/^#\/components\/([^\/]+)\/([^\/]+)/)
-        if (!depMatch) return
-        let [_, depOrig, depName] = [...depMatch]
-        decl.push(`export { ${depName} } from './${typeMap[depOrig]}.schema'\n`)
-        return
-      }
-      for (let dep of [k, ...s.dependsOn]) {
-        let depMatch = dep.match(/^#\/components\/([^\/]+)\/([^\/]+)/)
-        if (!depMatch) continue
-        let [_, depOrig, depName] = [...depMatch]
-        if (depOrig !== type) {
-          if (!(depOrig in imports)) imports[depOrig] = []
-          imports[depOrig].push(depName)
-        }
+const COMPONENT_TYPE_MAP = {
+  schemas: 'commons',
+  requestBodies: 'requests',
+  responses: 'responses',
+} as const
+
+const renderComponentSchemaFile = (
+  schemas: Record<string, SchemaEntry>,
+  type: 'schemas' | 'requestBodies' | 'responses'
+): string => {
+  if (Object.keys(schemas).length === 0) return ''
+  let imports: Record<string, string[]> = {}
+  let decl: string[] = []
+  Object.entries(schemas).forEach(([k, s]) => {
+    if (s.key === s.schema && s.dependsOn.size === 1) {
+      let depMatch = [...s.dependsOn][0].match(/^#\/components\/([^\/]+)\/([^\/]+)/)
+      if (!depMatch) return
+      let [_, depOrig, depName] = [...depMatch]
+      decl.push(`export { ${depName} } from './${COMPONENT_TYPE_MAP[depOrig as keyof typeof COMPONENT_TYPE_MAP]}.schema'\n`)
+      return
+    }
+    for (let dep of [k, ...s.dependsOn]) {
+      let depMatch = dep.match(/^#\/components\/([^\/]+)\/([^\/]+)/)
+      if (!depMatch) continue
+      let [_, depOrig, depName] = [...depMatch]
+      if (depOrig !== type) {
+        if (!(depOrig in imports)) imports[depOrig] = []
+        imports[depOrig].push(depName)
       }
+    }
+    // For requestBodies/responses that are just a single ref to another schema,
+    // preserve identity by tagging a _responseId / _requestBodyId rather than
+    // aliasing it (which would lose the original component name in the spec).
+    const isSingleAlias =
+      (type === 'responses' || type === 'requestBodies') &&
+      s.dependsOn.size === 1 &&
+      s.schema.trim() === [...s.dependsOn][0].split('/').pop()
+    const responseExtras: string[] = []
+    if (type === 'responses') {
+      if (s.responseDescription) responseExtras.push(`description: ${JSON.stringify(s.responseDescription)}`)
+      if (s.responseExample !== undefined) responseExtras.push(`example: ${JSON.stringify(s.responseExample)}`)
+      if (s.responseExamples) responseExtras.push(`examples: ${JSON.stringify(s.responseExamples)}`)
+    }
+    if (isSingleAlias) {
+      const tagKey = type === 'responses' ? '_responseId' : '_requestBodyId'
+      const extras = [`${tagKey}: "${s.key}"`, ...responseExtras]
+      decl.push(
+        `export const ${s.key} = { ...${s.schema}, ${extras.join(', ')} } as typeof ${s.schema}\nexport type ${s.key} = Static<typeof ${s.key}>\n`
+      )
+    } else if (type === 'responses' && responseExtras.length) {
+      decl.push(
+        `export const ${s.key} = {...${s.schema}, ${responseExtras.join(', ')}}\nexport type ${s.key} = Static<typeof ${s.key}>\n`
+      )
+    } else {
       decl.push(`export const ${s.key} = ${s.schema}\nexport type ${s.key} = Static<typeof ${s.key}>\n`)
-    })
-    if (decl.length === 0) return ''
-    return `import type { Static } from 'galbe/schema'\nimport { $T } from 'galbe'\n${Object.entries(imports)
-      .map(([k, v]) => `import { ${[...new Set(v)].join(', ')} } from './${typeMap[k]}.schema'\n`)
-      .join('\n')}\n${decl.join('\n')}\n`
-  }
+    }
+  })
+  if (decl.length === 0) return ''
+  return `import type { Static } from 'galbe/schema'\nimport { $T } from 'galbe'\n${Object.entries(imports)
+    .map(
+      ([k, v]) =>
+        `import { ${[...new Set(v)].join(', ')} } from './${COMPONENT_TYPE_MAP[k as keyof typeof COMPONENT_TYPE_MAP]}.schema'\n`
+    )
+    .join('\n')}\n${decl.join('\n')}\n`
+}
+
+export type RoutePlanEntry = {
+  /** HTTP method, lowercase (matches the property accessed on `g`). */
+  method: string
+  /** Path as emitted in the call expression: full prefix included, OpenAPI braces converted to `:param`. Stable identity for diff/rename. */
+  path: string
+  schemaName: string
+  /** JSDoc block string (e.g. '/**\n * summary\n *\/'). */
+  meta: string
+  /** Rendered call expression body, e.g. 'get("/path", FooSchema, ctx => { ... })'. */
+  call: string
+}
+
+export type ScopePlan = {
+  /** e.g. '/main', '/v1/public/admin'. */
+  scopeKey: string
+  /** Output path without extension, e.g. 'routes/main.route'. */
+  routeFile: string
+  /** Output path without extension, e.g. 'schemas/main.schema'. */
+  schemaFile: string
+  /** Imports to inject in the scope schema file: relative path -> imported names. */
+  schemaImports: Record<string, string[]>
+  /** 'export const X = {...}' declarations for the scope schema file. */
+  schemaDecls: string[]
+  /** Schema names to import in the scope route file from its sibling schema file. */
+  routeSchemaImports: string[]
+  routes: RoutePlanEntry[]
+}
+
+export type GenerationPlan = {
+  /** Component schema files (commons/requests/responses), ready to write. Path is relative to outDir without extension. */
+  componentFiles: { path: string; content: string }[]
+  scopes: ScopePlan[]
+  target: 'js' | 'ts'
+}
 
+export const buildPlan = (
+  endpoints: Record<string, EndpointEntry>,
+  schemaIndex: Record<string, SchemaEntry>,
+  target: 'js' | 'ts'
+): GenerationPlan => {
+  const componentFiles: { path: string; content: string }[] = []
   const sMaps = [
     { g: 'commons', o: 'schemas' },
     { g: 'requests', o: 'requestBodies' },
     { g: 'responses', o: 'responses' },
   ] as const
   for (let { g, o } of sMaps) {
-    let s = parseSchemasToFile(
+    let content = renderComponentSchemaFile(
       orderDeps(
         Object.fromEntries(
           Object.entries(schemaIndex).filter(([k, _]) => {
@@ -482,69 +721,117 @@ const writeFiles = async (
       ),
       o
     )
-    if (s) await writeCodeFile(resolve(path, 'schemas', `${g}.schema`), s, target)
+    if (content) componentFiles.push({ path: `schemas/${g}.schema`, content })
   }
 
-  let scopedDefs = Object.entries(endpoints).reduce((p, [_, v]) => {
+  let scopedDefs = Object.entries(endpoints).reduce<Record<string, EndpointEntry[]>>((p, [_, v]) => {
     let scopeKey = `${v.version ? `/${v.version}` : ''}${v.visibility ? `/${v.visibility}` : ''}${
       v.scope ? `/${v.scope}` : '/main'
     }`
     if (!(scopeKey in p)) p[scopeKey] = []
     p[scopeKey].push(v)
     return p
-  }, {}) as Record<string, EndpointEntry[]>
+  }, {})
 
+  const scopes: ScopePlan[] = []
   for (let [scopeKey, def] of Object.entries(scopedDefs)) {
-    let routePath = `routes${scopeKey}.route`
-    let schemaPath = `schemas${scopeKey}.schema`
+    let routeFile = `routes${scopeKey}.route`
+    let schemaFile = `schemas${scopeKey}.schema`
 
     let sImports: Record<string, Set<string>> = {}
     let sDecl: string[] = []
-
     let rImports: Set<string> = new Set()
-    let rDecl: string[] = []
+    let routes: RoutePlanEntry[] = []
 
     for (let d of def) {
-      // schema
       Object.entries(d.schema?.imports || {}).forEach(([iK, dep]) => {
-        let k = refToPath(dep, dirname(schemaPath))
+        let k = refToPath(dep, dirname(schemaFile))
         if (!k) return
         if (!(k in sImports)) sImports[k] = new Set()
         sImports[k].add(iK)
       })
       sDecl.push(`export const ${d.schema?.name} = ${d.schema?.def}`)
 
-      // route
       let ep = d.endpoint
       if (!ep) continue
       if (d.schema?.name) rImports.add(d.schema?.name)
-      rDecl.push(`  ${ep.meta}\ng.${ep.def}`)
+      // Source of truth for the path is the rendered call expression itself —
+      // reconstructing from version/visibility/scope/path drifts on edge cases
+      // (e.g. an empty trailing segment yields `/users/` instead of `/users`).
+      const callPathMatch = (ep.def ?? '').match(/^\w+\("([^"]*)"/)
+      const emittedPath = callPathMatch?.[1] ?? ''
+      routes.push({
+        method: d.method ?? '',
+        path: emittedPath,
+        schemaName: d.schema?.name ?? '',
+        meta: ep.meta ?? '',
+        call: ep.def ?? '',
+      })
     }
 
-    let schemaFile =
-      `import { $T } from 'galbe'\n\n` +
-      `${Object.entries(sImports)
-        .map(([k, v]) => `import { ${[...v].join(', ')} } from '${k}'`)
-        .join('\n')}\n\n` +
-      `${sDecl.map(d => d).join('\n\n')}\n`
-
-    let routeFile =
-      `import { NotImplementedError, type Galbe } from 'galbe'\n` +
-      `import { ${[...rImports].join(', ')} } from '../schemas${scopeKey}.schema'\n\n` +
-      `export default (g: Galbe) => {\n` +
-      rDecl.map(d => d.replaceAll('\n', '\n  ')).join('\n\n') +
-      `\n}\n`
-
-    if (sDecl?.length) await writeCodeFile(resolve(path, schemaPath), schemaFile, target)
-    if (rDecl?.length) await writeCodeFile(resolve(path, routePath), routeFile, target)
+    scopes.push({
+      scopeKey,
+      routeFile,
+      schemaFile,
+      schemaImports: Object.fromEntries(Object.entries(sImports).map(([k, v]) => [k, [...v]])),
+      schemaDecls: sDecl,
+      routeSchemaImports: [...rImports],
+      routes,
+    })
   }
+
+  return { componentFiles, scopes, target }
 }
 
-export const generateFromOapi = async (
+export type ApplyPlanOptions = {
+  /** Override the route file content for given scope keys. When set, the value is written verbatim
+   * instead of fresh-rendering from the plan — used by the merger to preserve user code. */
+  routeContents?: Map<string, string>
+}
+
+export const applyPlan = async (plan: GenerationPlan, outDir: string, opts: ApplyPlanOptions = {}): Promise<void> => {
+  const { target } = plan
+
+  for (const f of plan.componentFiles) {
+    await writeCodeFile(resolve(outDir, f.path), f.content, target)
+  }
+
+  for (const scope of plan.scopes) {
+    if (scope.schemaDecls.length) {
+      const schemaContent =
+        `import { $T } from 'galbe'\n\n` +
+        `${Object.entries(scope.schemaImports)
+          .map(([k, v]) => `import { ${v.join(', ')} } from '${k}'`)
+          .join('\n')}\n\n` +
+        `${scope.schemaDecls.join('\n\n')}\n`
+      await writeCodeFile(resolve(outDir, scope.schemaFile), schemaContent, target)
+    }
+
+    if (scope.routes.length) {
+      const override = opts.routeContents?.get(scope.scopeKey)
+      let routeContent: string
+      if (override !== undefined) {
+        routeContent = override
+      } else {
+        const deepness = scope.scopeKey.split('/').length - 1
+        const importPath = `${Array(deepness).fill('../').join('')}schemas${scope.scopeKey}.schema`
+        const rDecl = scope.routes.map(r => `  ${r.meta}\ng.${r.call}`)
+        routeContent =
+          `import { NotImplementedError, type Galbe } from 'galbe'\n` +
+          `import { ${scope.routeSchemaImports.join(', ')} } from '${importPath}'\n\n` +
+          `export default (g: Galbe) => {\n` +
+          rDecl.map(d => d.replaceAll('\n', '\n  ')).join('\n\n') +
+          `\n}\n`
+      }
+      await writeCodeFile(resolve(outDir, scope.routeFile), routeContent, target)
+    }
+  }
+}
+
+export const planFromOapi = async (
   input: string,
-  out: string,
   { version, ext, target }: { version: string; ext: 'json' | 'yaml'; target: 'js' | 'ts' }
-) => {
+): Promise<GenerationPlan> => {
   let def: OpenAPIV3.Document =
     ext === 'json' ? await Bun.file(input).json() : Bun.YAML.parse(await Bun.file(input).text())
 
@@ -554,5 +841,13 @@ export const generateFromOapi = async (
   let schemaIndex = buildSchemaIndex(def)
   let endpointDefs = parseEndpoints(def)
 
-  await writeFiles(out, endpointDefs, schemaIndex, target)
+  return buildPlan(endpointDefs, schemaIndex, target)
+}
+
+export const generateFromOapi = async (
+  input: string,
+  out: string,
+  opts: { version: string; ext: 'json' | 'yaml'; target: 'js' | 'ts' }
+) => {
+  await applyPlan(await planFromOapi(input, opts), out)
 }