galbe 0.15.5 → 0.16.0

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

@@ -1,5 +1,5 @@
 import { semver } from 'bun'
-import { transformSync } from '@swc/core'
+import { transformSync } from '@swc/wasm'
 import { resolve, relative, dirname } from 'path'
 import { OpenAPIV3 } from 'openapi-types'
 
@@ -16,17 +16,46 @@ type SchemaEntry = {
   responseExample?: any
   /** Response-only: content-level multi-key examples. */
   responseExamples?: Record<string, any>
+  /** Response-only: the response's `links`, with component refs already inlined. */
+  responseLinks?: Record<string, any>
+  /** Response-only: the response's headers as `[name, schema source]` pairs. */
+  responseHeaders?: [string, string][]
+  /**
+   * Response-only: the response's bodies as `[mediaType, schema]` pairs. Kept
+   * even for a single media type so the component can be emitted in the
+   * content-map form — decorating a schema by spread would leak the response's
+   * `description`/`example` into the shared component schema it refers to.
+   */
+  responseContent?: [string, string][]
+  /** RequestBody-only: the bodies as `[mediaType, schema]` pairs, same rationale as `responseContent`. */
+  requestContent?: [string, string][]
+  /** RequestBody-only: the component-level description and requiredness. */
+  requestDescription?: string
+  requestRequired?: boolean
 }
 type EndpointEntry = {
-  version?: string
-  visibility?: 'public' | 'private'
-  scope?: string
+  /** leading literal path segments — the last one names the route file, the ones before it the directory */
+  scope: string[]
   method?: 'get' | 'put' | 'patch' | 'post' | 'delete' | 'options' | 'head'
+  /** path as emitted in the file, relative to the file's directory prefix */
   path?: string
   schema?: { imports: Record<string, string>; name: string; def: string }
   endpoint?: { meta?: string; def?: string }
 }
 
+/**
+ * A construct the spec declares and the generated Galbe sources cannot carry.
+ * Collected while planning and reported by `generate code`: a silently widened
+ * validator is a security-adjacent surprise, a warning makes it a choice.
+ */
+export type GenerationWarning = { at: string; message: string }
+let warnings: GenerationWarning[] = []
+// where the walk currently is, so a warning raised deep in a schema can say so
+let warnAt = ''
+const warn = (message: string, at = warnAt) => {
+  if (!warnings.some(w => w.at === at && w.message === message)) warnings.push({ at, message })
+}
+
 // Util
 const unref = (code: string, cb: (m: string) => string) => code.replaceAll(/%ref:([^%]*)%/g, (_, m) => cb(m))
 const refToPath = (ref: string, basePath?: string) => {
@@ -75,14 +104,21 @@ const orderDeps = (deps: Record<string, SchemaEntry>) => {
   }
   return Object.fromEntries([...l].map(k => [k, deps[k]]))
 }
+/**
+ * Marks a value that is already Galbe source — a nested `$T.…` builder — so it
+ * comes back out of `serialize` as code instead of a quoted string.
+ */
+const raw = (code: string) => `__RAW__${code}__ENDRAW__`
 const serialize = (obj: any) => {
   return JSON.stringify(obj, (k, value) => {
     if (k === 'pattern' && value) return `__PATTERN__${value}__ENDPATTERN__`
     return value
-  }).replace(/"__PATTERN__([\s\S]*?)__ENDPATTERN__"/g, (_, body) => {
-    const decoded = JSON.parse(`"${body}"`) as string
-    return `/${decoded.replace(/\//g, '\\/')}/`
   })
+    .replace(/"__PATTERN__([\s\S]*?)__ENDPATTERN__"/g, (_, body) => {
+      const decoded = JSON.parse(`"${body}"`) as string
+      return `/${decoded.replace(/\//g, '\\/')}/`
+    })
+    .replace(/"__RAW__([\s\S]*?)__ENDRAW__"/g, (_, body) => JSON.parse(`"${body}"`) as string)
 }
 
 const writeCodeFile = async (path: string, content: string, target: 'js' | 'ts') => {
@@ -93,7 +129,8 @@ const writeCodeFile = async (path: string, content: string, target: 'js' | 'ts')
           syntax: 'typescript',
         },
         preserveAllComments: true,
-        target: 'esnext',
+        // @swc/wasm's JscTarget typing lags @swc/core's; 'esnext' is supported at runtime
+        target: 'esnext' as any,
       },
     }).code
   }
@@ -102,8 +139,8 @@ const writeCodeFile = async (path: string, content: string, target: 'js' | 'ts')
 
 const parseOapiSchema = (
   os?: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject,
-  details: { id?: string; title?: string; description?: string } = {},
-  extra?: { media?: string }
+  details: { id?: string; title?: string; description?: string; deprecated?: boolean } = {},
+  extra?: { media?: string; skipNullable?: boolean; encoding?: Record<string, any>; split?: string }
 ): string => {
   if (!os) {
     return `$T.any(${details && Object.keys(details).length ? JSON.stringify(details) : ''})`
@@ -112,6 +149,11 @@ const parseOapiSchema = (
   const ref: string | undefined = os?.$ref
   if (ref) return `%ref:${ref}%`
   os = os as OpenAPIV3.SchemaObject
+  // `nullable` is valid on any schema, not only on an object's properties, so
+  // it is applied once here — array items, component schemas and composition
+  // members included. The object branch opts out through `skipNullable`: it
+  // folds nullability together with optionality into `$T.nullish`.
+  const nullable = !extra?.skipNullable && os.nullable === true
   let options: typeof details & {
     min?: number
     max?: number
@@ -119,18 +161,27 @@ const parseOapiSchema = (
     exclusiveMax?: number
     minLength?: number
     maxLength?: number
+    multipleOf?: number
     pattern?: string
     format?: string
     minItems?: number
     maxItems?: number
     unique?: boolean
+    split?: string
     default?: any
     examples?: any
+    readOnly?: boolean
+    writeOnly?: boolean
+    encoding?: Record<string, any>
+    /** already-rendered source, injected through `raw()` */
+    additionalProperties?: string
   } = {
     ...details,
     title: os.title,
     description: details.description || os.description,
     default: os.default,
+    ...(os.readOnly ? { readOnly: true } : {}),
+    ...(os.writeOnly ? { writeOnly: true } : {}),
     ...(os.example !== undefined ? { examples: os.example } : {}),
   }
 
@@ -165,7 +216,21 @@ const parseOapiSchema = (
       )})`
     }
   } else if (!os?.type) {
-    return `$T.any(${hasOptions ? optArg : ''})`
+    if (os.not) warn('`not` has no equivalent in Galbe — the constraint is dropped and the value validates as `any`')
+    resp = `$T.any(${hasOptions ? optArg : ''})`
+  } else if (
+    os.enum?.length &&
+    os.format !== 'binary' &&
+    ['string', 'integer', 'number', 'boolean'].includes(os.type as string)
+  ) {
+    // An `enum` closes the value set for any primitive type, not just strings:
+    // one value is a literal, several are a union of literals. Both carry the
+    // options — a literal that drops them loses its description.
+    const literals = os.enum.map(v => `$T.literal(${JSON.stringify(v)})`)
+    resp =
+      literals.length === 1
+        ? `$T.literal(${JSON.stringify(os.enum[0])}${optArg ? `, ${optArg}` : ''})`
+        : `$T.union([${literals.join(', ')}]${optArg ? `, ${optArg}` : ''})`
   } else if (os.type === 'boolean') resp = `$T.boolean(${hasOptions ? serialize(options) : ''})`
   else if (os.type === 'number') {
     let { max, min, exclusiveMax, exclusiveMin } = {
@@ -174,7 +239,7 @@ const parseOapiSchema = (
       exclusiveMax: os.maximum !== undefined && os.exclusiveMaximum ? os.maximum : undefined,
       exclusiveMin: os.minimum !== undefined && os.exclusiveMinimum ? os.minimum : undefined,
     }
-    options = { ...options, min, max, exclusiveMax, exclusiveMin }
+    options = { ...options, min, max, exclusiveMax, exclusiveMin, multipleOf: os.multipleOf, format: os.format }
     hasOptions = Object.values(options).some(v => v !== undefined)
     resp = `$T.number(${hasOptions ? serialize(options) : ''})`
   } else if (os.type === 'integer') {
@@ -182,17 +247,12 @@ const parseOapiSchema = (
     let min = os.minimum !== undefined && !os.exclusiveMinimum ? os.minimum : undefined
     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 }
+    options = { ...options, min, max, exclusiveMax, exclusiveMin, multipleOf: os.multipleOf, format: os.format }
     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) {
-      const literals = os.enum.map(v => `$T.literal("${v}")`).join(', ')
-      resp = `$T.union([${literals}]${optArg ? `, ${optArg}` : ''})`
-    } else {
+    else {
       let minLength = os.minLength
       let maxLength = os.maxLength
       let pattern = os.pattern
@@ -207,7 +267,7 @@ const parseOapiSchema = (
     let minLength = os.minItems
     let maxLength = os.maxItems
     let unique = os.uniqueItems
-    options = { ...options, minLength, maxLength, unique }
+    options = { ...options, minLength, maxLength, unique, split: extra?.split }
     hasOptions = Object.values(options).some(v => v !== undefined)
     optArg = hasOptions ? serialize(options) : ''
     resp = `$T.array(${parseOapiSchema(os?.items)}${optArg ? `, ${optArg}` : ''})`
@@ -223,19 +283,38 @@ const parseOapiSchema = (
           else if (v.nullable) return `$T.nullable(${s})`
           return s
         }
-        return `"${k}":${w(parseOapiSchema(v))}`
+        // `w` owns this property's nullability, so the recursive call must not
+        // also wrap it — otherwise a nullable property comes back doubly wrapped.
+        return `"${k}":${w(parseOapiSchema(v, {}, { skipNullable: true }))}`
       })
       .join(',')
+    // `additionalProperties: true` is the OpenAPI default — only the two
+    // constraining forms carry information worth emitting.
+    const apDef = os.additionalProperties
+    const ap =
+      apDef === false ? 'false' : apDef && apDef !== true ? parseOapiSchema(apDef as OpenAPIV3.SchemaObject) : undefined
+
     if (extra?.media === 'multipart/form-data') {
+      // `encoding` sits on the media type in the spec; Galbe carries it on the
+      // multipartForm schema, which is the only place it can live
+      if (extra.encoding && Object.keys(extra.encoding).length) {
+        options = { ...options, encoding: extra.encoding }
+        optArg = serialize(options)
+      }
       resp = `$T.multipartForm({${props}}${optArg ? `, ${optArg}` : ''})`
-    } else if (extra?.media === 'application/x-www-form-urlencoded') {
-      resp = `$T.object({${props}}${optArg ? `, ${optArg}` : ''})`
+    } else if (ap !== undefined && ap !== 'false' && !props) {
+      // a free-form map: no declared properties, one schema for every value
+      resp = `$T.record(${ap}${optArg ? `, ${optArg}` : ''})`
     } else {
+      if (ap !== undefined) {
+        options = { ...options, additionalProperties: raw(ap) }
+        optArg = serialize(options)
+      }
       resp = `$T.object({${props}}${optArg ? `, ${optArg}` : ''})`
     }
   } else throw new Error(`Unknown schema type ${JSON.stringify(os)}`)
 
-  return resp
+  return nullable ? `$T.nullable(${resp})` : resp
 }
 
 const buildSchemaIndex = (def: OpenAPIV3.Document) => {
@@ -246,25 +325,39 @@ const buildSchemaIndex = (def: OpenAPIV3.Document) => {
     let dependsOn = new Set<string>()
     let responseExample: any = undefined
     let responseExamples: Record<string, any> | undefined = undefined
+    let responseLinks: Record<string, any> | undefined = undefined
+    let responseHeaders: [string, string][] | undefined = undefined
+    let responseContent: [string, string][] | undefined = undefined
+    let requestContent: [string, string][] | undefined = undefined
     if (kind === 'schemas') schema = parseOapiSchema(s, { id: k })
     else if (kind === 'requestBodies') {
-      let schemas = [] as string[]
-      if (!!s.content) {
-        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(',')}])`
+      const contentMap = (s as OpenAPIV3.RequestBodyObject)?.content
+      requestContent = Object.entries(contentMap || {}).map(([media, v]) => [
+        media,
+        parseOapiSchema(v.schema, {}, { media, encoding: (v as any).encoding }),
+      ])
+      schema = `{${requestContent.map(([m, v]) => `"${m}": ${v}`).join(',')}}`
     } else if (kind === 'responses') {
+      responseLinks = resolveLinks((s as OpenAPIV3.ResponseObject)?.links as any, def.components)
+      responseHeaders = responseHeaderEntries((s as OpenAPIV3.ResponseObject)?.headers, def.components)
       if (!s.content) {
-        schema = parseOapiSchema(undefined, { id: k, ...s })
+        // a bodiless component response: no media types, description only
+        responseContent = []
       } else {
-        const contentMap = s.content as Record<string, { schema?: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject; example?: any; examples?: any }>
+        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 }
+          if (v.examples && Object.keys(v.examples).length)
+            responseExamples = {
+              ...(responseExamples || {}),
+              ...Object.fromEntries(
+                Object.entries(v.examples).map(([k, ex]) => [k, resolveExample(ex, def.components)])
+              ),
+            }
         }
         const keyGroups: Record<string, string[]> = {}
         for (const [media, v] of entries) {
@@ -273,36 +366,44 @@ const buildSchemaIndex = (def: OpenAPIV3.Document) => {
           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(',')}}`
-        }
+        responseContent = Object.entries(keyGroups).map(([k, schemas]) => {
+          const unique = [...new Set(schemas)]
+          return [k, unique.length === 1 ? unique[0]! : `$T.union([${unique.join(',')}])`]
+        })
+        schema = `{${responseContent.map(([k, v]) => `"${k}": ${v}`).join(',')}}`
       }
     }
-    schema = unref(schema, m => {
-      let l = m.split('/')
-      dependsOn.add(m)
-      return l[l.length - 1]
-    })
+    const deref = (code: string) =>
+      unref(code, m => {
+        let l = m.split('/')
+        dependsOn.add(m)
+        return l[l.length - 1]!
+      })
+    schema = deref(schema)
+    responseContent = responseContent?.map(([media, sc]) => [media, deref(sc)])
+    requestContent = requestContent?.map(([media, sc]) => [media, deref(sc)])
+    responseHeaders = responseHeaders?.map(([name, sc]) => [name, deref(sc)])
     index[`#/components/${kind}/${k}`] = {
       key: k,
       prefix: '',
       schema,
       dependsOn,
       usedBy: new Set(),
+      ...(kind === 'responses' ? { responseContent: responseContent ?? [] } : {}),
+      ...(kind === 'requestBodies'
+        ? {
+            requestContent: requestContent ?? [],
+            ...(typeof s?.description === 'string' && s.description ? { requestDescription: s.description } : {}),
+            ...(s?.required !== undefined ? { requestRequired: !!s.required } : {}),
+          }
+        : {}),
       ...(kind === 'responses' && typeof s?.description === 'string' && s.description
         ? { responseDescription: s.description }
         : {}),
       ...(kind === 'responses' && responseExample !== undefined ? { responseExample } : {}),
       ...(kind === 'responses' && responseExamples ? { responseExamples } : {}),
+      ...(kind === 'responses' && responseLinks && Object.keys(responseLinks).length ? { responseLinks } : {}),
+      ...(kind === 'responses' && responseHeaders?.length ? { responseHeaders } : {}),
     }
   }
   for (let [k, v] of Object.entries(def.components?.schemas || {})) initSchema(k, v, 'schemas')
@@ -316,6 +417,100 @@ const buildSchemaIndex = (def: OpenAPIV3.Document) => {
   return index
 }
 
+/**
+ * Inline a `#/components/examples/*` reference. Galbe carries examples as plain
+ * values on the schema, with nowhere to keep a components entry, so a `$ref`
+ * left as-is would dangle in the regenerated spec.
+ */
+const resolveExample = (ex: any, components: OpenAPIV3.ComponentsObject | undefined, seen = new Set<string>()): any => {
+  const ref: unknown = ex?.$ref
+  if (typeof ref !== 'string' || seen.has(ref)) return ex
+  let match = ref.match(/^#\/components\/examples\/(.+)$/)
+  if (!match) return ex
+  let target = components?.examples?.[match[1]!]
+  if (!target) return ex
+  seen.add(ref)
+  return resolveExample(target, components, seen)
+}
+
+/**
+ * Resolve a `#/components/headers/*` reference. Galbe carries response headers
+ * inline on the response, with nowhere to keep a components entry, so the
+ * header is inlined — the component's identity is lost but its shape is not,
+ * which beats the silent skip this replaces.
+ */
+const resolveHeaderRef = (
+  ref: string,
+  components: OpenAPIV3.ComponentsObject | undefined,
+  seen = new Set<string>()
+): OpenAPIV3.HeaderObject | undefined => {
+  if (seen.has(ref)) return undefined
+  let match = ref.match(/^#\/components\/headers\/(.+)$/)
+  if (!match) return undefined
+  let target = components?.headers?.[match[1]!]
+  if (!target) return undefined
+  seen.add(ref)
+  if ('$ref' in target) return resolveHeaderRef(target.$ref, components, seen)
+  return target
+}
+
+/**
+ * Resolve a `#/components/links/*` reference. Galbe carries links inline on the
+ * response, with nowhere to keep a components entry, so the link is inlined —
+ * the component's name is lost, its content is not.
+ */
+const resolveLinkRef = (
+  ref: string,
+  components: OpenAPIV3.ComponentsObject | undefined,
+  seen = new Set<string>()
+): any => {
+  if (seen.has(ref)) return undefined
+  let match = ref.match(/^#\/components\/links\/(.+)$/)
+  if (!match) return undefined
+  let target = (components?.links as Record<string, any> | undefined)?.[match[1]!]
+  if (!target) return undefined
+  seen.add(ref)
+  if ('$ref' in target) return resolveLinkRef(target.$ref, components, seen)
+  return target
+}
+
+/** Every link on a response, with `$ref`s inlined. Empty when the response declares none. */
+const resolveLinks = (
+  links: Record<string, any> | undefined,
+  components: OpenAPIV3.ComponentsObject | undefined
+): Record<string, any> => {
+  const out: Record<string, any> = {}
+  for (const [name, link] of Object.entries(links ?? {})) {
+    const resolved = link && '$ref' in link ? resolveLinkRef(link.$ref, components) : link
+    if (resolved) out[name] = resolved
+  }
+  return out
+}
+
+/**
+ * A response's headers as `[name, schema source]` pairs, with
+ * `#/components/headers/*` references resolved and `%ref:%` markers left in
+ * place. Deliberately strategy-free: a route file resolves those markers
+ * through its import map and a component file through its dependency set, and
+ * baking either one in is what kept component responses from carrying headers.
+ */
+const responseHeaderEntries = (
+  headers: OpenAPIV3.ResponseObject['headers'],
+  components: OpenAPIV3.ComponentsObject | undefined
+): [string, string][] => {
+  const out: [string, string][] = []
+  for (const [name, value] of Object.entries(headers ?? {})) {
+    let h: OpenAPIV3.HeaderObject | undefined
+    if ('$ref' in (value as any)) {
+      h = resolveHeaderRef((value as any).$ref, components)
+      if (!h) continue
+    } else h = value as OpenAPIV3.HeaderObject
+    const code = parseOapiSchema(h.schema || ({ type: 'string' } as any), { description: h.description })
+    out.push([name, h.required ? code : `$T.optional(${code})`])
+  }
+  return out
+}
+
 const resolveParamRef = (
   ref: string,
   components: OpenAPIV3.ComponentsObject | undefined
@@ -331,25 +526,49 @@ const resolveParamRef = (
 const parseEndpointDef = (
   method: string,
   path: string,
+  emitPath: string,
   def?: OpenAPIV3.OperationObject,
   components?: OpenAPIV3.ComponentsObject
 ) => {
   if (!def) return {}
   let imports: Record<string, string> = {}
-  let p = path.replaceAll(/\{([^\}]*)\}/g, ':$1')
+  // every `%ref:%` in this operation resolves to a name the route file imports
+  const deref = (code: string): string =>
+    unref(code, m => {
+      const l = m.split('/')
+      imports[l[l.length - 1]!] = m
+      return l[l.length - 1]!
+    })
+  // the emitted path is relative to the file's directory prefix; the schema
+  // name derives from the full path so it stays unique across scopes
+  let p = emitPath.replaceAll(/\{([^\}]*)\}/g, ':$1')
   // let description = def.summary || def.description
   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())
+        .replaceAll(/[^$\w\d_]+([$\w\d_])/g, (_, $1) => $1.toUpperCase())}`.replace(/^\w/, c => c.toUpperCase())
 
+  warnAt = `${method.toUpperCase()} ${path}`
   let meta = '/**\n'
-  if (def.summary) meta += ` * ${def.summary}\n *\n`
-  if (def.description) meta += ` * ${def.description.replace(/\n/g, '\n * ')}\n`
+  // The JSDoc head expresses "summary, then description" and nothing else, so a
+  // description with no summary needs the explicit tags: a bare `@summary`
+  // declares the empty one the head convention cannot write down.
+  const headExpressible = !def.description || !!def.summary
+  if (headExpressible) {
+    if (def.summary) meta += ` * ${def.summary}\n *\n`
+    if (def.description) meta += ` * ${def.description.replace(/\n/g, '\n * ')}\n`
+  } else {
+    if (typeof def.summary === 'string') meta += ` * @summary\n`
+    for (const line of def.description!.split('\n')) meta += ` * @description ${line}\n`
+  }
   if (def.operationId) meta += ` * @operationId ${def.operationId}\n`
-  if (def.externalDocs?.url) meta += ` * @externalDocs ${def.externalDocs.url}\n`
+  // `@externalDocs <url> [description]` — the serializer splits it back on the
+  // first whitespace, so the description survives the roundtrip.
+  if (def.externalDocs?.url)
+    meta += ` * @externalDocs ${def.externalDocs.url}${
+      def.externalDocs.description ? ` ${def.externalDocs.description}` : ''
+    }\n`
   if (def.tags) meta += ` * @tags ${def.tags.join(' ')}\n`
   if (Array.isArray(def.security)) {
     if (def.security.length === 0) {
@@ -372,7 +591,14 @@ const parseEndpointDef = (
   meta += ' */'
   let endpoint = `${method}("${p}", ${schemaName}, ctx => {\n  throw new NotImplementedError()\n})`
 
-  let sp: Record<string, Record<string, string>> = { path: {}, query: {}, header: {}, body: {}, formData: {} } // TODO handle body and formData cases
+  let sp: Record<string, Record<string, string>> = {
+    path: {},
+    query: {},
+    header: {},
+    cookie: {},
+    body: {},
+    formData: {},
+  } // TODO handle body and formData cases
 
   for (let _p of def?.parameters || []) {
     let p: OpenAPIV3.ParameterObject | undefined
@@ -386,19 +612,40 @@ const parseEndpointDef = (
       s = so ?? s
       return p.in !== 'path' && !p.required ? `$T.optional(${s})` : s
     }
+    // A parameter is typed either by `schema` or by `content` (a single media
+    // type). Galbe cannot record *which* media type it was serialized as, so
+    // the roundtrip stays lossy there — but keeping the shape beats `$T.any()`.
+    const pSchema = p.schema ?? Object.values(p.content ?? {})[0]?.schema
+    if ((p as any).allowEmptyValue)
+      warn(`parameter '${p.name}': allowEmptyValue is not modelled (OpenAPI deprecates it) and is dropped`)
+    // Only a serialization Galbe's parsers do not implement is worth reporting.
+    // A query array accepts the repeated *and* the comma form, so both explode
+    // variants of 'form' are honoured; 'pipeDelimited' and 'spaceDelimited'
+    // become the array's `split`, and 'deepObject' is an object parameter.
+    const defaultStyle = p.in === 'query' || p.in === 'cookie' ? 'form' : 'simple'
+    const style = ((p as any).style as string | undefined) ?? defaultStyle
+    const pType = (p.schema as OpenAPIV3.SchemaObject | undefined)?.type
+    const split = style === 'pipeDelimited' ? '|' : style === 'spaceDelimited' ? ' ' : undefined
+    const honoured =
+      style === defaultStyle
+        ? p.in !== 'query' || pType !== 'object' // form-on-object is `a,b,c,d`, not implemented
+        : p.in === 'query' && (style === 'deepObject' ? pType === 'object' : !!split && pType === 'array')
+    if (!honoured)
+      warn(
+        `parameter '${p.name}': style '${style}'${pType ? ` on a ${pType}` : ''} is not implemented — the generated route parses it as '${defaultStyle}'`
+      )
+    if (p.content && Object.keys(p.content).length > 1)
+      warn(`parameter '${p.name}': only the first of ${Object.keys(p.content).length} content media types is kept`)
     sp[p.in][p.name] = o(
-      unref(parseOapiSchema(p.schema, { description: p.description }), m => {
-        let l = m.split('/')
-        imports[l[l.length - 1]] = m
-        return l[l.length - 1]
-      })
+      deref(parseOapiSchema(pSchema, { description: p.description, deprecated: p.deprecated }, { split }))
     )
   }
 
-  let [schemaParams, schemaQuery, schemaHeaders] = [
+  let [schemaParams, schemaQuery, schemaHeaders, schemaCookies] = [
     { g: 'params', o: 'path' },
     { g: 'query', o: 'query' },
     { g: 'headers', o: 'header' },
+    { g: 'cookies', o: 'cookie' },
   ].map(({ g, o }) =>
     Object.keys(sp[o]).length
       ? `  ${g}: {${Object.entries(sp[o])
@@ -411,11 +658,7 @@ const parseEndpointDef = (
   if (!['get', 'delete', 'options', 'head'].includes(method)) {
     let _rb = def?.requestBody as OpenAPIV3.ReferenceObject
     if (_rb?.$ref) {
-      body = unref(`  body: %ref:${_rb.$ref}%`, m => {
-        let l = m.split('/')
-        imports[l[l.length - 1]] = m
-        return l[l.length - 1]
-      })
+      body = deref(`  body: %ref:${_rb.$ref}%`)
     } else {
       let rb = def?.requestBody as OpenAPIV3.RequestBodyObject
       let o = (s: string) => (!rb?.required ? `$T.optional(${s})` : s)
@@ -423,15 +666,17 @@ const parseEndpointDef = (
         ...new Set(
           Object.entries(rb?.content || { null: {} }).map(([media, v]) => [
             media,
-            unref(parseOapiSchema(v.schema, undefined, { media }), m => {
-              let l = m.split('/')
-              imports[l[l.length - 1]] = m
-              return l[l.length - 1]
-            }),
+            deref(parseOapiSchema(v.schema, undefined, { media, encoding: (v as any).encoding })),
           ])
         ),
       ]
-      body = bs.length ? `  body: {${bs.map(([k, v]) => `"${k}":${o(v)}`).join(',')}}` : ''
+      // The body's own description sits beside the media types, never spread
+      // onto a body schema — a spread over a schema carrying an `id` leaks it
+      // into the shared component (same failure mode as response metadata).
+      const parts = bs.map(([k, v]) => `"${k}":${o(v)}`)
+      if (typeof rb?.description === 'string' && rb.description)
+        parts.push(`description:${JSON.stringify(rb.description)}`)
+      body = parts.length ? `  body: {${parts.join(',')}}` : ''
     }
   }
 
@@ -439,41 +684,38 @@ const parseEndpointDef = (
   let r = def?.responses
   let rs = Object.fromEntries(
     Object.entries(r || {}).map(([status, sv]) => {
-      let s: string = Number.isInteger(Number(status)) ? status : 'default'
+      // `1XX`…`5XX` are status keys of their own — Galbe carries them verbatim.
+      // Anything else that is not an integer collapses onto `default`.
+      let s: string = Number.isInteger(Number(status))
+        ? status
+        : /^[1-5]XX$/i.test(status)
+          ? status.toUpperCase()
+          : 'default'
+      if (s === 'default' && status !== 'default')
+        warn(`response '${status}' is not a status Galbe can express and collapses onto 'default'`)
 
       //@ts-ignore
-      let rootRef = sv?.$ref
-        ? unref(parseOapiSchema(sv), m => {
-            let l = m.split('/')
-            imports[l[l.length - 1]] = m
-            return l[l.length - 1]
-          })
-        : null
+      let rootRef = sv?.$ref ? deref(parseOapiSchema(sv)) : null
       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
+      const headerEntries = responseHeaderEntries(respObj?.headers, components).map(
+        ([hName, code]) => `${JSON.stringify(hName)}:${deref(code)}`
+      )
+      const description =
+        typeof respObj?.description === 'string' && respObj.description ? respObj.description : undefined
+      const links = resolveLinks((respObj as any)?.links, components)
+      const hasLinks = Object.keys(links).length > 0
 
       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(',')}}})`
+        const extras = [
+          ...(headerEntries.length ? [`responseHeaders:{${headerEntries.join(',')}}`] : []),
+          ...(hasLinks ? [`responseLinks:${JSON.stringify(links)}`] : []),
+        ]
+        if (extras.length) nullSchema = `({...${nullSchema}, ${extras.join(', ')}})`
         return [s, nullSchema]
       }
 
@@ -485,13 +727,10 @@ const parseEndpointDef = (
         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)}`)
+          for (const [k, ex] of Object.entries(tv.examples))
+            exampleParts.push(`${JSON.stringify(k)}:${JSON.stringify(resolveExample(ex, components))}`)
         }
-        const schemaStr = unref(parseOapiSchema(tv.schema), m => {
-          let l = m.split('/')
-          imports[l[l.length - 1]] = m
-          return l[l.length - 1]
-        })
+        const schemaStr = deref(parseOapiSchema(tv.schema))
         if (!keyGroups[galbeKey]) keyGroups[galbeKey] = []
         keyGroups[galbeKey].push(schemaStr)
       }
@@ -507,6 +746,7 @@ const parseEndpointDef = (
         }
         if (description) parts.push(`description: ${JSON.stringify(description)}`)
         if (headerEntries.length) parts.push(`responseHeaders: {${headerEntries.join(',')}}`)
+        if (hasLinks) parts.push(`responseLinks: ${JSON.stringify(links)}`)
         if (exampleParts.length) parts.push(`examples: {${exampleParts.join(',')}}`)
         if (singleExample !== undefined) parts.push(`example: ${JSON.stringify(singleExample)}`)
         return [s, `{${parts.join(',')}}`]
@@ -514,17 +754,18 @@ const parseEndpointDef = (
         // 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(',')}})`
+        let schemaStr =
+          unique.length === 0 ? `$T.null()` : unique.length === 1 ? unique[0] : `$T.union([${unique.join(',')}])`
+        // Examples sit beside the body in the content map, never spread onto the
+        // body schema: a spread carrying `example`/`examples` over a schema with
+        // an `id` leaks them into that shared component (see _responseId above).
         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(',')}}`)
+        if (hasLinks) parts.push(`responseLinks:${JSON.stringify(links)}`)
+        if (exampleParts.length) parts.push(`examples:{${exampleParts.join(',')}}`)
+        if (singleExample !== undefined) parts.push(`example:${JSON.stringify(singleExample)}`)
         return [s, `{${parts.join(',')}}`]
       }
     })
@@ -533,11 +774,12 @@ const parseEndpointDef = (
   if (Object.keys(rs).length) {
     resp = `  response: {${Object.entries(rs)
       .filter(([_, v]) => v)
-      .map(([s, v]) => `${s}: ${v}`)
+      // a range key is not a valid bare property name — `5XX:` does not parse
+      .map(([s, v]) => `${/^\d+$/.test(s) ? s : JSON.stringify(s)}: ${v}`)
       .join(',')}}`
   } else resp = ''
 
-  let schema = [schemaHeaders, schemaParams, schemaQuery, body, resp].filter(s => s)
+  let schema = [schemaHeaders, schemaParams, schemaQuery, schemaCookies, body, resp].filter(s => s)
 
   return {
     schema: {
@@ -556,18 +798,35 @@ 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))?\/?([^\/]+)\/?(.*)$/)
-    if (!match) continue
-    let [_, version, visibility, scope, path] = [...match]
-    path = `/${path}`
+    // Directory convention: the leading literal segments pick the output file
+    // (all but the last become its directory, i.e. its dirPrefix), and the
+    // emitted path is written relative to that directory so the analyzer
+    // reconstructs the full path on load.
+    const segments = fullPath.split('/').filter(s => s !== '')
+    let nLit = 0
+    while (nLit < segments.length && !/[{}]/.test(segments[nLit]!)) nLit++
+    const scope = segments.slice(0, nLit)
+    const emitPath = `/${segments.slice(Math.max(nLit - 1, 0)).join('/')}`
     let methods = ['get', 'put', 'patch', 'post', 'delete', 'options', 'head'] as const
+    // 'trace' is deliberately absent: it is disabled across most infrastructure
+    // and Galbe has no builder for it. Say so rather than dropping it silently.
+    for (const m of Object.keys(pathVal))
+      if (
+        !(methods as readonly string[]).includes(m) &&
+        m !== 'parameters' &&
+        m !== 'summary' &&
+        m !== 'description' &&
+        m !== 'servers'
+      )
+        warn(
+          `method '${m.toUpperCase()}' has no Galbe route builder — the operation is skipped`,
+          `${m.toUpperCase()} ${fullPath}`
+        )
     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 ref = `#/paths/${m}${fullPath}`
       let opParams = endpointDef.parameters || []
       let opKeys = new Set(
         opParams
@@ -583,13 +842,11 @@ const parseEndpoints = (def: OpenAPIV3.Document) => {
         return !opKeys.has(`${resolved.in}:${resolved.name}`)
       })
       let mergedDef = { ...endpointDef, parameters: [...inheritedParams, ...opParams] }
-      let { schema, endpoint } = parseEndpointDef(m, fullPath, mergedDef, def.components)
+      let { schema, endpoint } = parseEndpointDef(m, fullPath, emitPath, mergedDef, def.components)
       endpoints[ref] = {
-        version,
-        visibility: visibility as 'public' | 'private',
         method: m,
         scope,
-        path,
+        path: emitPath,
         schema,
         endpoint,
       }
@@ -616,7 +873,9 @@ const renderComponentSchemaFile = (
       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`)
+      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]) {
@@ -628,32 +887,38 @@ const renderComponentSchemaFile = (
         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`)
+    // Responses and requestBodies are emitted in the content-map form: media
+    // types as keys, the component's own metadata beside them, and an
+    // `_responseId` / `_requestBodyId` preserving the component's name so the
+    // serializer can put it back under `components` and `$ref` it.
+    //
+    // Never a spread onto the body schema: that writes the response's
+    // `description`/`example` into the shared component schema the body refers
+    // to, which the serializer registers by `id`.
+    if (type === 'responses' || type === 'requestBodies') {
+      const isResp = type === 'responses'
+      const content = (isResp ? s.responseContent : s.requestContent) ?? []
+      const extras = [`${isResp ? '_responseId' : '_requestBodyId'}: "${s.key}"`]
+      const description = isResp ? s.responseDescription : s.requestDescription
+      if (description) extras.push(`description: ${JSON.stringify(description)}`)
+      if (isResp) {
+        if (s.responseExample !== undefined) extras.push(`example: ${JSON.stringify(s.responseExample)}`)
+        if (s.responseExamples) extras.push(`examples: ${JSON.stringify(s.responseExamples)}`)
+        if (s.responseLinks) extras.push(`responseLinks: ${JSON.stringify(s.responseLinks)}`)
+        if (s.responseHeaders?.length)
+          extras.push(
+            `responseHeaders: {${s.responseHeaders.map(([n, sc]) => `${JSON.stringify(n)}: ${sc}`).join(', ')}}`
+          )
+      } else if (s.requestRequired !== undefined) extras.push(`required: ${s.requestRequired}`)
+      const body = [...content.map(([media, sc]) => `${JSON.stringify(media)}: ${sc}`), ...extras].join(', ')
+      // the exported type is the body type, read back off the const
+      const bodyType = content.length
+        ? content.map(([media]) => `Static<(typeof ${s.key})[${JSON.stringify(media)}]>`).join(' | ')
+        : 'null'
+      decl.push(`export const ${s.key} = { ${body} }\nexport type ${s.key} = ${bodyType}\n`)
+      return
     }
+    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)
@@ -667,7 +932,7 @@ const renderComponentSchemaFile = (
 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 as emitted in the call expression: relative to the scope's `prefix`, OpenAPI braces converted to `:param`. */
   path: string
   schemaName: string
   /** JSDoc block string (e.g. '/**\n * summary\n *\/'). */
@@ -677,9 +942,11 @@ export type RoutePlanEntry = {
 }
 
 export type ScopePlan = {
-  /** e.g. '/main', '/v1/public/admin'. */
+  /** e.g. '/main', '/v1/modules'. */
   scopeKey: string
-  /** Output path without extension, e.g. 'routes/main.route'. */
+  /** The route file's directory prefix (dirPrefix reconstructs it on load), e.g. '/v1' or ''. */
+  prefix: string
+  /** Output path without extension, e.g. 'main.route', 'v1/modules.route'. */
   routeFile: string
   /** Output path without extension, e.g. 'schemas/main.schema'. */
   schemaFile: string
@@ -697,6 +964,8 @@ export type GenerationPlan = {
   componentFiles: { path: string; content: string }[]
   scopes: ScopePlan[]
   target: 'js' | 'ts'
+  /** Constructs the spec declared that the generated sources cannot carry. */
+  warnings?: GenerationWarning[]
 }
 
 export const buildPlan = (
@@ -725,9 +994,7 @@ export const buildPlan = (
   }
 
   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'
-    }`
+    let scopeKey = v.scope.length ? `/${v.scope.join('/')}` : '/main'
     if (!(scopeKey in p)) p[scopeKey] = []
     p[scopeKey].push(v)
     return p
@@ -735,7 +1002,9 @@ export const buildPlan = (
 
   const scopes: ScopePlan[] = []
   for (let [scopeKey, def] of Object.entries(scopedDefs)) {
-    let routeFile = `routes${scopeKey}.route`
+    const scope = def[0].scope
+    let prefix = scope.length > 1 ? `/${scope.slice(0, -1).join('/')}` : ''
+    let routeFile = scope.length ? `${scope.join('/')}.route` : 'main.route'
     let schemaFile = `schemas${scopeKey}.schema`
 
     let sImports: Record<string, Set<string>> = {}
@@ -771,6 +1040,7 @@ export const buildPlan = (
 
     scopes.push({
       scopeKey,
+      prefix,
       routeFile,
       schemaFile,
       schemaImports: Object.fromEntries(Object.entries(sImports).map(([k, v]) => [k, [...v]])),
@@ -783,6 +1053,12 @@ export const buildPlan = (
   return { componentFiles, scopes, target }
 }
 
+/** Relative import path from a scope's route file to its sibling schema file. */
+export const schemaImportPath = (scope: Pick<ScopePlan, 'routeFile' | 'schemaFile'>): string => {
+  const rel = relative(dirname(scope.routeFile), scope.schemaFile)
+  return rel.startsWith('.') ? rel : `./${rel}`
+}
+
 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. */
@@ -813,8 +1089,7 @@ export const applyPlan = async (plan: GenerationPlan, outDir: string, opts: Appl
       if (override !== undefined) {
         routeContent = override
       } else {
-        const deepness = scope.scopeKey.split('/').length - 1
-        const importPath = `${Array(deepness).fill('../').join('')}schemas${scope.scopeKey}.schema`
+        const importPath = schemaImportPath(scope)
         const rDecl = scope.routes.map(r => `  ${r.meta}\ng.${r.call}`)
         routeContent =
           `import { NotImplementedError, type Galbe } from 'galbe'\n` +
@@ -838,10 +1113,12 @@ export const planFromOapi = async (
   let v = def?.openapi
   if (!v || !semver.satisfies(v, version)) throw new Error('Invalid openapi version')
 
+  warnings = []
+  warnAt = ''
   let schemaIndex = buildSchemaIndex(def)
   let endpointDefs = parseEndpoints(def)
 
-  return buildPlan(endpointDefs, schemaIndex, target)
+  return { ...buildPlan(endpointDefs, schemaIndex, target), warnings }
 }
 
 export const generateFromOapi = async (