ts-procedures 6.1.0 → 6.2.0

package/src/codegen/bin/cli.ts

@@ -22,8 +22,9 @@ export interface CodegenConfig {
   selfContained?: boolean
   serviceName?: string
   cleanOutDir?: boolean
-  target?: 'ts' | 'kotlin'
+  target?: 'ts' | 'kotlin' | 'swift'
   kotlin?: { package: string; serializer?: 'kotlinx' | 'none' }
+  swift?: { serializer?: 'codable' | 'none'; accessLevel?: 'public' | 'internal' }
   unsupportedUnions?: 'throw' | 'fallback'
 }
 
@@ -40,8 +41,9 @@ export interface ParsedArgs {
   selfContained: boolean
   serviceName?: string
   cleanOutDir: boolean
-  target?: 'ts' | 'kotlin'
+  target?: 'ts' | 'kotlin' | 'swift'
   kotlin?: { package: string; serializer?: 'kotlinx' | 'none' }
+  swift?: { serializer?: 'codable' | 'none'; accessLevel?: 'public' | 'internal' }
   unsupportedUnions?: 'throw' | 'fallback'
 }
 
@@ -94,9 +96,11 @@ export function parseArgs(argv: string[], config?: CodegenConfig): ParsedArgs {
   let selfContained = config?.selfContained ?? true
   let serviceName: string | undefined = config?.serviceName
   let cleanOutDir = config?.cleanOutDir ?? false
-  let target: 'ts' | 'kotlin' | undefined = config?.target
+  let target: 'ts' | 'kotlin' | 'swift' | undefined = config?.target
   let kotlinPackage: string | undefined = config?.kotlin?.package
   let kotlinSerializer: 'kotlinx' | 'none' | undefined = config?.kotlin?.serializer
+  let swiftSerializer: 'codable' | 'none' | undefined = config?.swift?.serializer
+  let swiftAccessLevel: 'public' | 'internal' | undefined = config?.swift?.accessLevel
   let unsupportedUnions: 'throw' | 'fallback' | undefined = config?.unsupportedUnions
   let configPath: string | undefined
 
@@ -149,10 +153,10 @@ export function parseArgs(argv: string[], config?: CodegenConfig): ParsedArgs {
       cleanOutDir = false
     } else if (arg === '--target') {
       const val = argv[++i]
-      if (val === 'ts' || val === 'kotlin') {
+      if (val === 'ts' || val === 'kotlin' || val === 'swift') {
         target = val
       } else {
-        throw new Error(`Invalid --target value: ${val ?? '(missing)'} (expected 'ts' or 'kotlin')`)
+        throw new Error(`Invalid --target value: ${val ?? '(missing)'} (expected 'ts', 'kotlin', or 'swift')`)
       }
     } else if (arg === '--kotlin-package') {
       kotlinPackage = argv[++i]
@@ -163,6 +167,20 @@ export function parseArgs(argv: string[], config?: CodegenConfig): ParsedArgs {
       } else {
         throw new Error(`Invalid --kotlin-serializer value: ${val ?? '(missing)'} (expected 'kotlinx' or 'none')`)
       }
+    } else if (arg === '--swift-serializer') {
+      const val = argv[++i]
+      if (val === 'codable' || val === 'none') {
+        swiftSerializer = val
+      } else {
+        throw new Error(`Invalid --swift-serializer value: ${val ?? '(missing)'} (expected 'codable' or 'none')`)
+      }
+    } else if (arg === '--swift-access-level') {
+      const val = argv[++i]
+      if (val === 'public' || val === 'internal') {
+        swiftAccessLevel = val
+      } else {
+        throw new Error(`Invalid --swift-access-level value: ${val ?? '(missing)'} (expected 'public' or 'internal')`)
+      }
     } else if (arg === '--unsupported-unions') {
       const val = argv[++i]
       if (val === 'throw' || val === 'fallback') {
@@ -178,6 +196,14 @@ export function parseArgs(argv: string[], config?: CodegenConfig): ParsedArgs {
   // configPath is consumed by the caller (main) before parseArgs is called with the loaded config.
   // When called from main, config is already loaded. When called directly (tests), configPath is ignored.
 
+  // ---------------------------------------------------------------------------
+  // Validation — fails fast on user-controllable errors before envelope resolve.
+  // Runtime checks (emitter availability, etc.) happen later in pipeline.ts;
+  // those guards are aimed at non-CLI callers (direct API consumers, tests).
+  // The CLI resolves emitters before invoking `runPipeline`, so users only ever
+  // see flag-shape errors from this block, not pipeline-internal throws.
+  // ---------------------------------------------------------------------------
+
   if (outDir === undefined) {
     throw new Error('Missing required argument: --out <dir>')
   }
@@ -186,10 +212,15 @@ export function parseArgs(argv: string[], config?: CodegenConfig): ParsedArgs {
     throw new Error('Missing required input source: provide --url <url> or --file <path>')
   }
 
+  // Kotlin target requires a package; surface this before any I/O happens.
   if (target === 'kotlin' && (kotlinPackage === undefined || kotlinPackage === '')) {
     throw new Error('Missing required argument: --kotlin-package <pkg> (required when --target kotlin)')
   }
 
+  // Swift target currently has no required flags. If that changes, add the
+  // guard here so the failure mode stays consistent (flag-shape errors fire
+  // from parseArgs; runtime/emitter wiring errors fire from pipeline.ts).
+
   return {
     url,
     file,
@@ -212,6 +243,14 @@ export function parseArgs(argv: string[], config?: CodegenConfig): ParsedArgs {
           },
         }
       : {}),
+    ...(swiftSerializer !== undefined || swiftAccessLevel !== undefined
+      ? {
+          swift: {
+            ...(swiftSerializer !== undefined ? { serializer: swiftSerializer } : {}),
+            ...(swiftAccessLevel !== undefined ? { accessLevel: swiftAccessLevel } : {}),
+          },
+        }
+      : {}),
     ...(unsupportedUnions !== undefined ? { unsupportedUnions } : {}),
   }
 }
@@ -260,6 +299,17 @@ async function runWithWatch(parsed: ParsedArgs): Promise<void> {
         }
       : {}
 
+  // Resolve the swift emitter once at watch start; it's stateless and reused per tick.
+  const swiftWiring =
+    parsed.target === 'swift'
+      ? {
+          target: 'swift' as const,
+          swiftEmitter: await (
+            await import('../targets/swift/ajsc-adapter.js')
+          ).resolveProductionSwiftEmitter(),
+        }
+      : {}
+
   let lastHash: string | undefined
 
   const run = async (): Promise<void> => {
@@ -287,7 +337,10 @@ async function runWithWatch(parsed: ParsedArgs): Promise<void> {
         cleanOutDir: parsed.cleanOutDir,
         ...(parsed.kotlin?.serializer !== undefined ? { kotlinSerializer: parsed.kotlin.serializer } : {}),
         ...(parsed.unsupportedUnions !== undefined ? { unsupportedUnions: parsed.unsupportedUnions } : {}),
+        ...(parsed.swift?.serializer !== undefined ? { swiftSerializer: parsed.swift.serializer } : {}),
+        ...(parsed.swift?.accessLevel !== undefined ? { swiftAccessLevel: parsed.swift.accessLevel } : {}),
         ...kotlinWiring,
+        ...swiftWiring,
       })
       console.log(`[ts-procedures-codegen] Generated client files → ${parsed.outDir}`)
     } catch (err) {
@@ -308,14 +361,26 @@ async function runWithWatch(parsed: ParsedArgs): Promise<void> {
 const KOTLIN_SETUP_GUIDE_URL =
   'https://bitbucket.org/thermsio/ts-procedures/src/master/docs/codegen-kotlin.md'
 
-export function printPostRunHints(parsed: { target?: 'ts' | 'kotlin' }): void {
+const SWIFT_SETUP_GUIDE_URL =
+  'https://bitbucket.org/thermsio/ts-procedures/src/master/docs/codegen-swift.md'
+
+export function printPostRunHints(parsed: { target?: 'ts' | 'kotlin' | 'swift' }): void {
   if (parsed.target === 'kotlin') {
     console.log(`[ts-procedures-codegen] Kotlin setup guide: ${KOTLIN_SETUP_GUIDE_URL}`)
   }
+  if (parsed.target === 'swift') {
+    console.log(`[ts-procedures-codegen] Swift setup guide: ${SWIFT_SETUP_GUIDE_URL}`)
+  }
 }
 
 /**
  * Warns about flags that are currently no-ops for the Kotlin target.
+ *
+ * Scope is intentionally Kotlin-only — the param type omits `'swift'` so a
+ * reader can tell at a glance this function will never act on swift. Other
+ * targets get their own warner if/when they grow no-op flags. The call site
+ * narrows `parsed.target` before invoking.
+ *
  * Currently: `--unsupported-unions` is a no-op because ajsc v7.2's Kotlin
  * emitter silently emits an empty data class for untagged oneOf regardless
  * of the flag (see docs/codegen-kotlin.md#untagged-unions).
@@ -340,7 +405,15 @@ async function main(): Promise<void> {
     console.log(`[ts-procedures-codegen] Loaded config from ${configPath ?? DEFAULT_CONFIG_NAME}`)
   }
   const parsed = parseArgs(argv, config)
-  warnIfKotlinNoOpFlags(parsed)
+  // The warner is intentionally Kotlin-only; pass the relevant fields and
+  // narrow `target` away from 'swift' here so the function's param type can
+  // stay tight.
+  if (parsed.target !== 'swift') {
+    warnIfKotlinNoOpFlags({
+      target: parsed.target,
+      ...(parsed.unsupportedUnions !== undefined ? { unsupportedUnions: parsed.unsupportedUnions } : {}),
+    })
+  }
 
   const source = parsed.url ?? parsed.file!
   console.log(`[ts-procedures-codegen] Reading docs from ${source}...`)
@@ -357,6 +430,14 @@ async function main(): Promise<void> {
           }
         : {}
 
+    const swiftWiring =
+      parsed.target === 'swift'
+        ? {
+            target: 'swift' as const,
+            swiftEmitter: await (await import('../targets/swift/ajsc-adapter.js')).resolveProductionSwiftEmitter(),
+          }
+        : {}
+
     const result = await generateClient({
       url: parsed.url,
       file: parsed.file,
@@ -370,7 +451,10 @@ async function main(): Promise<void> {
       cleanOutDir: parsed.cleanOutDir,
       ...(parsed.kotlin?.serializer !== undefined ? { kotlinSerializer: parsed.kotlin.serializer } : {}),
       ...(parsed.unsupportedUnions !== undefined ? { unsupportedUnions: parsed.unsupportedUnions } : {}),
+      ...(parsed.swift?.serializer !== undefined ? { swiftSerializer: parsed.swift.serializer } : {}),
+      ...(parsed.swift?.accessLevel !== undefined ? { swiftAccessLevel: parsed.swift.accessLevel } : {}),
       ...kotlinWiring,
+      ...swiftWiring,
     })
     if (parsed.dryRun) {
       console.log(`[ts-procedures-codegen] Dry run complete — ${result.length} files would be generated`)

package/src/codegen/index.ts

@@ -2,6 +2,7 @@ import { resolveEnvelope, type ResolveInput } from './resolve-envelope.js'
 import { runPipeline, type GeneratedFile } from './pipeline.js'
 import type { AjscOptions } from './emit-types.js'
 import type { KotlinEmitter } from './targets/kotlin/ajsc-adapter.js'
+import type { SwiftEmitter } from './targets/swift/ajsc-adapter.js'
 
 export interface GenerateClientOptions extends ResolveInput {
   outDir: string
@@ -12,12 +13,16 @@ export interface GenerateClientOptions extends ResolveInput {
   selfContained?: boolean
   serviceName?: string
   cleanOutDir?: boolean
-  target?: 'ts' | 'kotlin'
+  target?: 'ts' | 'kotlin' | 'swift'
   kotlinPackage?: string
   kotlinSerializer?: 'kotlinx' | 'none'
   unsupportedUnions?: 'throw' | 'fallback'
   /** Injected for tests; production wiring resolves a real ajsc emitter. */
   kotlinEmitter?: KotlinEmitter
+  swiftSerializer?: 'codable' | 'none'
+  swiftAccessLevel?: 'public' | 'internal'
+  /** Injected for tests; production wiring resolves a real ajsc emitter. */
+  swiftEmitter?: SwiftEmitter
 }
 
 export async function generateClient(options: GenerateClientOptions): Promise<GeneratedFile[]> {
@@ -37,6 +42,9 @@ export async function generateClient(options: GenerateClientOptions): Promise<Ge
     kotlinSerializer: options.kotlinSerializer,
     unsupportedUnions: options.unsupportedUnions,
     kotlinEmitter: options.kotlinEmitter,
+    swiftSerializer: options.swiftSerializer,
+    swiftAccessLevel: options.swiftAccessLevel,
+    swiftEmitter: options.swiftEmitter,
   })
 }
 
@@ -57,3 +65,18 @@ export type { KotlinEmitOptions } from './targets/kotlin/ajsc-adapter.js'
 
 /** Result shape produced by `KotlinEmitter.emit`; stable, useful for stub builders in tests. */
 export type { KotlinEmitResult } from './targets/kotlin/ajsc-adapter.js'
+
+/**
+ * @internal Subject to change with ajsc minor versions. Use for test injection
+ *   only; consumer code should not depend on this shape.
+ */
+export type { SwiftEmitter } from './targets/swift/ajsc-adapter.js'
+
+/**
+ * @internal Mirrors ajsc's `SwiftConverterOpts` and may shift with ajsc
+ *   minor versions. Use for test injection only.
+ */
+export type { SwiftEmitOptions } from './targets/swift/ajsc-adapter.js'
+
+/** Result shape produced by `SwiftEmitter.emit`; stable, useful for stub builders in tests. */
+export type { SwiftEmitResult } from './targets/swift/ajsc-adapter.js'

package/src/codegen/pipeline.ts

@@ -1,18 +1,14 @@
-import { mkdir, rm, writeFile } from 'node:fs/promises'
-import { join } from 'node:path'
 import { createHash } from 'node:crypto'
 import type { DocEnvelope } from '../implementations/types.js'
 import type { AjscOptions } from './emit-types.js'
 import { groupRoutesByScope } from './group-routes.js'
-import { emitScopeFile } from './emit-scope.js'
-import { emitIndexFile } from './emit-index.js'
-import { emitErrorsFile } from './emit-errors.js'
-import { emitClientTypesFile } from './emit-client-types.js'
-import { emitClientRuntimeFile } from './emit-client-runtime.js'
 import { validateServiceName } from './naming.js'
+import type { GeneratedFile } from './targets/_shared/write-files.js'
 import type { KotlinEmitter } from './targets/kotlin/ajsc-adapter.js'
-import { emitKotlinScope } from './targets/kotlin/emit-scope-kotlin.js'
-import { pickDefined } from './targets/kotlin/format-kotlin.js'
+import { runKotlinPipeline } from './targets/kotlin/run.js'
+import type { SwiftEmitter } from './targets/swift/ajsc-adapter.js'
+import { runSwiftPipeline } from './targets/swift/run.js'
+import { runTsPipeline } from './targets/ts/run.js'
 
 export interface PipelineOptions {
   envelope: DocEnvelope
@@ -24,193 +20,75 @@ export interface PipelineOptions {
   selfContained?: boolean
   serviceName?: string
   cleanOutDir?: boolean
-  target?: 'ts' | 'kotlin'
+  target?: 'ts' | 'kotlin' | 'swift'
   kotlinPackage?: string
   kotlinSerializer?: 'kotlinx' | 'none'
   unsupportedUnions?: 'throw' | 'fallback'
   /** Injected for tests; production wiring resolves a real ajsc emitter. */
   kotlinEmitter?: KotlinEmitter
+  swiftSerializer?: 'codable' | 'none'
+  swiftAccessLevel?: 'public' | 'internal'
+  /** Injected for tests; production wiring resolves a real ajsc emitter. */
+  swiftEmitter?: SwiftEmitter
 }
 
-export interface GeneratedFile {
-  path: string
-  code: string
-}
+export type { GeneratedFile } from './targets/_shared/write-files.js'
 
+/**
+ * Top-level codegen entry. Validates the service name, computes the source
+ * hash, groups routes by scope, then dispatches to the per-target run module.
+ *
+ * Per-target modules own their language-specific emission and the file-write
+ * tail (dryRun / cleanOutDir / mkdir / writeFile via
+ * `_shared/write-files.ts`).
+ */
 export async function runPipeline(options: PipelineOptions): Promise<GeneratedFile[]> {
   const { envelope, outDir, ajsc: ajscOpts, dryRun = false, namespaceTypes = false, selfContained = false, cleanOutDir = false } = options
   const serviceName = options.serviceName ?? 'Api'
   validateServiceName(serviceName)
+
   const clientImportPath = selfContained ? './_types' : options.clientImportPath
   if (selfContained && options.clientImportPath != null) {
     console.warn('[ts-procedures-codegen] --self-contained overrides --client-import-path; using ./_types')
   }
 
   const hash = createHash('md5').update(JSON.stringify(envelope)).digest('hex')
-  const hashComment = `// Source hash: ${hash}`
-
-  const groups = groupRoutesByScope(envelope.routes)
-  const groupArray = Array.from(groups.values())
-
-  if (options.target === 'kotlin') {
-    if (options.kotlinPackage == null) {
-      throw new Error('[ts-procedures-codegen] target=kotlin requires kotlinPackage')
-    }
-    if (options.kotlinEmitter == null) {
-      throw new Error(
-        '[ts-procedures-codegen] target=kotlin requires a kotlinEmitter (CLI resolves via resolveProductionKotlinEmitter)'
-      )
-    }
-
-    // Route errors are taxonomy keys (string[]); look up actual schemas from the
-    // envelope's top-level errors array. Mirrors the existing TS scope emitter.
-    const errorSchemas = new Map<string, unknown>()
-    for (const e of envelope.errors) {
-      if (e.schema != null) errorSchemas.set(e.name, e.schema)
-    }
-
-    // Spec §"CLI flags" — `--array-item-naming`, `--depluralize`, `--uncountable-words`
-    // also apply to the Kotlin target. The CLI parks them on `options.ajsc` (a TS-target
-    // structure historically); copy the Kotlin-relevant subset onto the scope opts here.
-    const ajscPassthrough = options.ajsc ?? {}
-
-    const AJSC_PASSTHROUGH_KEYS = ['arrayItemNaming', 'depluralize', 'uncountableWords'] as const
-
-    const kotlinFiles: GeneratedFile[] = []
-    const allSkipped: string[] = []
-    for (const group of groupArray) {
-      const emitted = emitKotlinScope(
-        group,
-        {
-          kotlinPackage: options.kotlinPackage,
-          sourceHash: hash,
-          ...(options.kotlinSerializer !== undefined ? { serializer: options.kotlinSerializer } : {}),
-          ...(options.unsupportedUnions !== undefined ? { unsupportedUnions: options.unsupportedUnions } : {}),
-          ...pickDefined(ajscPassthrough, AJSC_PASSTHROUGH_KEYS),
-        },
-        options.kotlinEmitter,
-        errorSchemas,
-      )
-      kotlinFiles.push({ path: join(outDir, emitted.filename), code: emitted.code })
-      allSkipped.push(...emitted.skippedStreams)
-    }
-
-    if (allSkipped.length > 0) {
-      console.log(
-        `[ts-procedures-codegen] Skipped ${allSkipped.length} stream route${allSkipped.length === 1 ? '' : 's'} (kotlin target): ${allSkipped.join(', ')}`,
-      )
-    }
-
-    if (dryRun) {
-      if (cleanOutDir) {
-        console.log(`[dry-run] Would clean outDir: ${outDir}`)
-      }
-      for (const f of kotlinFiles) {
-        const bytes = Buffer.byteLength(f.code, 'utf-8')
-        console.log(`[dry-run] Would write: ${f.path} (${bytes} bytes)`)
-      }
-    } else {
-      if (cleanOutDir) {
-        await rm(outDir, { recursive: true, force: true })
-      }
-      await mkdir(outDir, { recursive: true })
-      for (const f of kotlinFiles) {
-        await writeFile(f.path, f.code, 'utf-8')
-      }
-    }
-
-    return kotlinFiles
-  }
+  const groups = Array.from(groupRoutesByScope(envelope.routes).values())
 
-  // Error keys that will be emitted in `_errors.ts` — only those with a schema.
-  // Scope emit uses this to filter `route.errors` so generated code never
-  // references an undefined error type.
-  const errorKeys = new Set(
-    envelope.errors.filter((e) => e.schema != null).map((e) => e.name)
-  )
-
-  if (selfContained) {
-    for (const group of groupArray) {
-      if (group.scopeKey === '_types' || group.scopeKey === '_client') {
-        throw new Error(
-          `[ts-procedures-codegen] Scope "${group.scopeKey}" conflicts with self-contained mode reserved filename "${group.scopeKey}.ts". Rename the scope to avoid collision.`
-        )
-      }
-    }
-  }
-
-  const files: GeneratedFile[] = []
-
-  for (const group of groupArray) {
-    const rawCode = await emitScopeFile(group, {
-      ajsc: ajscOpts,
-      clientImportPath,
-      namespaceTypes,
-      serviceName,
-      errorKeys: errorKeys.size > 0 ? errorKeys : undefined,
-    })
-    const lines = rawCode.split('\n')
-    lines.splice(1, 0, hashComment)
-    const code = lines.join('\n')
-    files.push({ path: join(outDir, `${group.scopeKey}.ts`), code })
-  }
-
-  const errorsCode = await emitErrorsFile(envelope.errors, { ajsc: ajscOpts, clientImportPath, namespaceTypes, serviceName })
-  const hasErrors = errorsCode != null
-  if (errorsCode != null) {
-    const errorsLines = errorsCode.split('\n')
-    errorsLines.splice(1, 0, hashComment)
-    const errorsWithHash = errorsLines.join('\n')
-    files.push({ path: join(outDir, '_errors.ts'), code: errorsWithHash })
-  }
-
-  // In self-contained mode types come from `./_types` but the runtime
-  // (`createClient`) lives in `./_client`. In regular mode both share the
-  // single `clientImportPath` (e.g. `ts-procedures/client`).
-  const clientRuntimeImportPath = selfContained ? './_client' : clientImportPath
-  const rawIndexCode = emitIndexFile(groupArray, {
+  const base = {
+    envelope,
+    outDir,
+    hash,
+    groups,
+    serviceName,
+    ajsc: ajscOpts,
     clientImportPath,
-    clientRuntimeImportPath,
-    hasErrors,
+    dryRun,
     namespaceTypes,
-    serviceName,
-  })
-  const indexLines = rawIndexCode.split('\n')
-  indexLines.splice(1, 0, hashComment)
-  const indexCode = indexLines.join('\n')
-  files.push({ path: join(outDir, 'index.ts'), code: indexCode })
-
-  if (selfContained) {
-    const rawTypesCode = await emitClientTypesFile()
-    const typesLines = rawTypesCode.split('\n')
-    typesLines.splice(1, 0, hashComment)
-    const typesCode = typesLines.join('\n')
-    files.push({ path: join(outDir, '_types.ts'), code: typesCode })
-
-    const rawClientCode = await emitClientRuntimeFile()
-    const clientLines = rawClientCode.split('\n')
-    clientLines.splice(1, 0, hashComment)
-    const clientCode = clientLines.join('\n')
-    files.push({ path: join(outDir, '_client.ts'), code: clientCode })
+    selfContained,
+    cleanOutDir,
   }
 
-  if (dryRun) {
-    if (cleanOutDir) {
-      console.log(`[dry-run] Would clean outDir: ${outDir}`)
-    }
-    for (const file of files) {
-      const bytes = Buffer.byteLength(file.code, 'utf-8')
-      console.log(`[dry-run] Would write: ${file.path} (${bytes} bytes)`)
-    }
-  } else {
-    if (cleanOutDir) {
-      await rm(outDir, { recursive: true, force: true })
-    }
-    await mkdir(outDir, { recursive: true })
-    for (const file of files) {
-      await writeFile(file.path, file.code, 'utf-8')
-    }
+  switch (options.target) {
+    case 'kotlin':
+      return runKotlinPipeline({
+        ...base,
+        kotlinPackage: options.kotlinPackage,
+        kotlinSerializer: options.kotlinSerializer,
+        unsupportedUnions: options.unsupportedUnions,
+        kotlinEmitter: options.kotlinEmitter,
+      })
+    case 'swift':
+      return runSwiftPipeline({
+        ...base,
+        swiftSerializer: options.swiftSerializer,
+        swiftAccessLevel: options.swiftAccessLevel,
+        unsupportedUnions: options.unsupportedUnions,
+        swiftEmitter: options.swiftEmitter,
+      })
+    case 'ts':
+    case undefined:
+    default:
+      return runTsPipeline(base)
   }
-
-  return files
 }

package/src/codegen/targets/_shared/error-schemas.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest'
+import { buildErrorSchemasMap } from './error-schemas.js'
+import type { ErrorDoc } from '../../../implementations/types.js'
+
+describe('buildErrorSchemasMap', () => {
+  it('returns an empty map when there are no errors', () => {
+    expect(buildErrorSchemasMap([])).toEqual(new Map())
+  })
+
+  it('includes errors with schemas', () => {
+    const schemaA = { type: 'object', tag: 'a' }
+    const schemaB = { type: 'object', tag: 'b' }
+    const errors: ErrorDoc[] = [
+      { name: 'A', statusCode: 400, description: '', schema: schemaA },
+      { name: 'B', statusCode: 500, description: '', schema: schemaB },
+    ]
+    const map = buildErrorSchemasMap(errors)
+    expect(map.size).toBe(2)
+    expect(map.get('A')).toBe(schemaA)
+    expect(map.get('B')).toBe(schemaB)
+  })
+
+  it('skips errors without a schema', () => {
+    const schemaA = { type: 'object' }
+    const errors: ErrorDoc[] = [
+      { name: 'A', statusCode: 400, description: '', schema: schemaA },
+      { name: 'NoSchema', statusCode: 500, description: '' },
+    ]
+    const map = buildErrorSchemasMap(errors)
+    expect(map.size).toBe(1)
+    expect(map.has('A')).toBe(true)
+    expect(map.has('NoSchema')).toBe(false)
+  })
+
+  it('keys the map by error name', () => {
+    const schema = { type: 'object' }
+    const map = buildErrorSchemasMap([
+      { name: 'NotFound', statusCode: 404, description: '', schema },
+    ])
+    expect(Array.from(map.keys())).toEqual(['NotFound'])
+  })
+})

package/src/codegen/targets/_shared/error-schemas.ts

@@ -0,0 +1,17 @@
+import type { ErrorDoc } from '../../../implementations/types.js'
+
+/**
+ * Builds a lookup map from a {@link DocEnvelope}'s top-level `errors` array
+ * keyed by `name`. Only entries with a `schema` are included — errors
+ * documented without a schema cannot have a corresponding generated type.
+ *
+ * Targets pass this map to per-route emission so taxonomy keys on
+ * `route.errors` (a `string[]`) can be resolved to actual JSON Schemas.
+ */
+export function buildErrorSchemasMap(errors: readonly ErrorDoc[]): Map<string, unknown> {
+  const errorSchemas = new Map<string, unknown>()
+  for (const e of errors) {
+    if (e.schema != null) errorSchemas.set(e.name, e.schema)
+  }
+  return errorSchemas
+}

package/src/codegen/targets/_shared/indent.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest'
+import { indent } from './indent.js'
+
+describe('indent', () => {
+  it('indents every line by 4 spaces per level', () => {
+    expect(indent('a\nb', 1)).toBe('    a\n    b')
+    expect(indent('a', 2)).toBe('        a')
+  })
+
+  it('preserves blank lines without trailing whitespace when indenting', () => {
+    expect(indent('a\n\nb', 1)).toBe('    a\n\n    b')
+  })
+
+  it('returns the input unchanged at level 0', () => {
+    expect(indent('a\n\nb', 0)).toBe('a\n\nb')
+  })
+
+  it('indents a single line', () => {
+    expect(indent('hello', 1)).toBe('    hello')
+  })
+
+  it('returns empty string for empty input', () => {
+    expect(indent('', 1)).toBe('')
+  })
+})

package/src/codegen/targets/_shared/indent.ts

@@ -0,0 +1,12 @@
+/**
+ * Indents every non-blank line of `text` by `level * 4` spaces. Blank lines
+ * are preserved as empty (no trailing whitespace). Suitable for languages
+ * that use 4-space indentation (Kotlin, Swift).
+ */
+export function indent(text: string, level: number): string {
+  const prefix = '    '.repeat(level)
+  return text
+    .split('\n')
+    .map((line) => (line.length === 0 ? line : `${prefix}${line}`))
+    .join('\n')
+}

package/src/codegen/targets/_shared/pascal-case.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest'
+import { pascalCase } from './pascal-case.js'
+
+describe('pascalCase', () => {
+  it('converts a single-word scope', () => {
+    expect(pascalCase('users')).toBe('Users')
+  })
+
+  it('converts a kebab-case scope', () => {
+    expect(pascalCase('user-management')).toBe('UserManagement')
+  })
+
+  it('handles multi-segment kebab-case', () => {
+    expect(pascalCase('a-b-c')).toBe('ABC')
+  })
+
+  it('drops empty segments from leading/trailing/double dashes', () => {
+    expect(pascalCase('-users')).toBe('Users')
+    expect(pascalCase('users-')).toBe('Users')
+    expect(pascalCase('user--mgmt')).toBe('UserMgmt')
+  })
+
+  it('returns empty string for empty input', () => {
+    expect(pascalCase('')).toBe('')
+  })
+
+  it('preserves casing of letters after the leading character', () => {
+    expect(pascalCase('user-API')).toBe('UserAPI')
+  })
+})

package/src/codegen/targets/_shared/pascal-case.ts

@@ -0,0 +1,12 @@
+/**
+ * Converts a kebab-case (or single-word) scope key to PascalCase. Used by
+ * codegen targets to derive top-level type/namespace identifiers from scope
+ * names (e.g. `user-management` → `UserManagement`).
+ */
+export function pascalCase(scope: string): string {
+  return scope
+    .split('-')
+    .filter((p) => p.length > 0)
+    .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+    .join('')
+}