ts-procedures 6.0.2 → 6.2.0

package/src/codegen/targets/kotlin/e2e-compile.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect } from 'vitest'
+import { execFileSync, execSync } from 'node:child_process'
+import { mkdtempSync, writeFileSync, readFileSync, readdirSync, existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { runPipeline } from '../../pipeline.js'
+import { resolveProductionKotlinEmitter } from './ajsc-adapter.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+function kotlincAvailable(): boolean {
+  try {
+    execSync('kotlinc -version', { stdio: 'ignore' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+const RUN = process.env.TS_PROCEDURES_KOTLIN_E2E === '1'
+
+/**
+ * E2E: real ajsc → real .kt output → real kotlinc compile.
+ *
+ * Gated on (a) `kotlinc` on PATH and (b) opt-in via env var so default
+ * `npm test` runs stay green for contributors without the toolchain.
+ *
+ * **Classpath setup (one-time, local):**
+ *
+ * Download kotlinx-serialization jars (matching versions, e.g. 1.6.3) from
+ * Maven Central or a local Gradle/Maven cache. The classpath value is a
+ * `:`-separated list (`;` on Windows). Concrete example:
+ *
+ *   export TS_PROCEDURES_KOTLIN_E2E_CLASSPATH="\
+ *     $HOME/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlinx/kotlinx-serialization-json-jvm/1.6.3/<hash>/kotlinx-serialization-json-jvm-1.6.3.jar:\
+ *     $HOME/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlinx/kotlinx-serialization-core-jvm/1.6.3/<hash>/kotlinx-serialization-core-jvm-1.6.3.jar"
+ *
+ * If the env var is unset the compile uses kotlinc's default classpath which
+ * lacks the kotlinx jars and fails — that's the expected mode when checking
+ * gating works.
+ */
+describe('kotlin codegen — kotlinc compile (gated)', () => {
+  it.skipIf(!kotlincAvailable() || !RUN)(
+    'compiles generated output without errors',
+    async () => {
+      const emitter = await resolveProductionKotlinEmitter()
+      const envelope = JSON.parse(
+        readFileSync(join(__dirname, '../../__fixtures__/users-envelope.json'), 'utf8'),
+      )
+      const files = await runPipeline({
+        envelope,
+        outDir: 'out',
+        dryRun: true,
+        target: 'kotlin',
+        kotlinPackage: 'com.example.api',
+        kotlinEmitter: emitter,
+      })
+      const dir = mkdtempSync(join(tmpdir(), 'tsp-kotlin-e2e-'))
+      for (const f of files) {
+        writeFileSync(join(dir, f.path.split('/').pop()!), f.code)
+      }
+
+      // Expand the source glob in Node and pass kotlinc args as an array so
+      // the shell never sees user-controlled input. The classpath env var is
+      // only forwarded as a single -classpath argument; even a value with
+      // shell metachars cannot escape into command parsing.
+      const ktFiles = readdirSync(dir)
+        .filter((name) => name.endsWith('.kt'))
+        .map((name) => join(dir, name))
+
+      const outJar = join(dir, 'out.jar')
+      const cp = process.env.TS_PROCEDURES_KOTLIN_E2E_CLASSPATH
+      const args: string[] = []
+      if (cp != null && cp.length > 0) {
+        args.push('-classpath', cp)
+      }
+      args.push(...ktFiles, '-d', outJar)
+
+      execFileSync('kotlinc', args, { stdio: 'inherit' })
+
+      expect(existsSync(outJar)).toBe(true)
+    },
+  )
+})

package/src/codegen/targets/kotlin/emit-route-kotlin.test.ts

@@ -0,0 +1,239 @@
+import { describe, expect, it } from 'vitest'
+import type { AnyHttpRouteDoc } from '../../../implementations/types.js'
+import { emitKotlinRoute } from './emit-route-kotlin.js'
+import { createStubKotlinEmitter, type KotlinEmitOptions, type KotlinEmitResult } from './ajsc-adapter.js'
+
+const ok = (code: string, rootTypeName: string): KotlinEmitResult => ({
+  code,
+  rootTypeName,
+  extractedTypeNames: [],
+  imports: ['kotlinx.serialization.Serializable'],
+})
+
+const noErrors = new Map<string, unknown>()
+
+interface CapturedCall { schema: unknown; opts: KotlinEmitOptions }
+
+function makeSpyEmitter(results: Record<string, KotlinEmitResult>) {
+  const calls: CapturedCall[] = []
+  const emitter = {
+    emit(schema: unknown, opts: KotlinEmitOptions) {
+      calls.push({ schema, opts })
+      const r = results[opts.rootTypeName]
+      if (r == null) throw new Error(`No stubbed result for "${opts.rootTypeName}"`)
+      return r
+    },
+  }
+  return { emitter, calls }
+}
+
+describe('emitKotlinRoute', () => {
+  it('emits an api-kind route with path params and a response', () => {
+    const route: AnyHttpRouteDoc = {
+      kind: 'api',
+      name: 'GetUser',
+      method: 'GET',
+      fullPath: '/users/:id',
+      schema: {
+        input: {
+          pathParams: { type: 'object' },
+        },
+        returnType: { type: 'object' },
+      },
+      errors: [],
+    } as unknown as AnyHttpRouteDoc
+
+    const emitter = createStubKotlinEmitter({
+      PathParams: ok('@Serializable data class PathParams(val id: String)', 'PathParams'),
+      Response: ok('@Serializable data class Response(val id: String, val name: String)', 'Response'),
+    })
+
+    const result = emitKotlinRoute(route, emitter, noErrors)
+
+    expect(result.imports).toContain('kotlinx.serialization.Serializable')
+    expect(result.code).toContain('const val method = "GET"')
+    expect(result.code).toContain('const val pathTemplate = "/users/{id}"')
+    expect(result.code).toContain('fun path(p: PathParams): String = "/users/${p.id}"')
+    expect(result.code).toContain('@Serializable data class PathParams(val id: String)')
+    expect(result.code).toContain('@Serializable data class Response(val id: String, val name: String)')
+  })
+
+  it('emits a route with no path params using a path constant', () => {
+    const route = {
+      kind: 'api',
+      name: 'CreateUser',
+      method: 'POST',
+      fullPath: '/users',
+      schema: { input: { body: { type: 'object' } }, returnType: { type: 'object' } },
+      errors: [],
+    } as unknown as AnyHttpRouteDoc
+
+    const emitter = createStubKotlinEmitter({
+      Body: ok('@Serializable data class Body(val name: String)', 'Body'),
+      Response: ok('@Serializable data class Response(val id: String)', 'Response'),
+    })
+
+    const result = emitKotlinRoute(route, emitter, noErrors)
+    expect(result.code).toContain('const val path = "/users"')
+    expect(result.code).not.toContain('fun path(')
+  })
+
+  it('emits an Errors namespace for routes whose error keys have schemas in the envelope', () => {
+    const route = {
+      kind: 'api',
+      name: 'GetUser',
+      method: 'GET',
+      fullPath: '/users/:id',
+      schema: { input: { pathParams: { type: 'object' } }, returnType: { type: 'object' } },
+      errors: ['NotFound'],
+    } as unknown as AnyHttpRouteDoc
+
+    const emitter = createStubKotlinEmitter({
+      PathParams: ok('@Serializable data class PathParams(val id: String)', 'PathParams'),
+      Response: ok('@Serializable data class Response(val id: String)', 'Response'),
+      NotFound: ok('@Serializable data class NotFound(val name: String, val message: String)', 'NotFound'),
+    })
+
+    const errorSchemas = new Map<string, unknown>([['NotFound', { type: 'object' }]])
+    const result = emitKotlinRoute(route, emitter, errorSchemas)
+    expect(result.code).toContain('object Errors {')
+    expect(result.code).toContain('@Serializable data class NotFound(val name: String, val message: String)')
+  })
+
+  it('silently skips error keys with no schema in the envelope map', () => {
+    const route = {
+      kind: 'api', name: 'GetUser', method: 'GET', fullPath: '/users',
+      schema: {}, errors: ['UnknownTaxonomyKey'],
+    } as unknown as AnyHttpRouteDoc
+    const result = emitKotlinRoute(route, createStubKotlinEmitter({}), new Map())
+    expect(result.code).not.toContain('object Errors {')
+  })
+
+  it('returns skipped:true for stream routes', () => {
+    const route = { kind: 'stream', name: 'WatchUsers', method: 'GET', path: '/users/stream', schema: {}, errors: [] } as unknown as AnyHttpRouteDoc
+    const result = emitKotlinRoute(route, createStubKotlinEmitter({}), noErrors)
+    expect(result.code).toBe('')
+    expect(result.skipped).toBe(true)
+  })
+
+  it('passes inlineTypes:true plus serializer/unsupportedUnions to every slot emit', () => {
+    const route = {
+      kind: 'api',
+      name: 'GetUser',
+      method: 'GET',
+      fullPath: '/users/:id',
+      schema: {
+        input: { pathParams: { type: 'object' } },
+        returnType: { type: 'object' },
+      },
+      errors: ['NotFound'],
+    } as unknown as AnyHttpRouteDoc
+
+    const { emitter, calls } = makeSpyEmitter({
+      PathParams: ok('@Serializable data class PathParams(val id: String)', 'PathParams'),
+      Response: ok('@Serializable data class Response(val id: String)', 'Response'),
+      NotFound: ok('@Serializable data class NotFound(val message: String)', 'NotFound'),
+    })
+
+    emitKotlinRoute(route, emitter, new Map([['NotFound', { type: 'object' }]]), {
+      serializer: 'none',
+      unsupportedUnions: 'fallback',
+    })
+
+    // 3 emits: PathParams, Response, NotFound
+    expect(calls.length).toBe(3)
+    for (const c of calls) {
+      expect(c.opts.inlineTypes).toBe(true)
+      expect(c.opts.serializer).toBe('none')
+      expect(c.opts.unsupportedUnions).toBe('fallback')
+    }
+  })
+
+  it('preserves slot order: pathParams → query → body → response → errors', () => {
+    const route = {
+      kind: 'api',
+      name: 'X',
+      method: 'POST',
+      fullPath: '/x/:id',
+      schema: {
+        input: {
+          pathParams: { type: 'object' },
+          query: { type: 'object' },
+          body: { type: 'object' },
+        },
+        returnType: { type: 'object' },
+      },
+      errors: ['Z'],
+    } as unknown as AnyHttpRouteDoc
+
+    const { emitter, calls } = makeSpyEmitter({
+      PathParams: ok('a', 'PathParams'),
+      Query: ok('b', 'Query'),
+      Body: ok('c', 'Body'),
+      Response: ok('d', 'Response'),
+      Z: ok('e', 'Z'),
+    })
+
+    emitKotlinRoute(route, emitter, new Map([['Z', { type: 'object' }]]), {})
+
+    expect(calls.map((c) => c.opts.rootTypeName)).toEqual([
+      'PathParams', 'Query', 'Body', 'Response', 'Z',
+    ])
+  })
+
+  it('threads passthrough opts (arrayItemNaming/depluralize/uncountableWords) verbatim', () => {
+    const route = {
+      kind: 'api',
+      name: 'X',
+      method: 'GET',
+      fullPath: '/x',
+      schema: { returnType: { type: 'object' } },
+      errors: [],
+    } as unknown as AnyHttpRouteDoc
+
+    const { emitter, calls } = makeSpyEmitter({
+      Response: ok('@Serializable data class Response(val ok: Boolean)', 'Response'),
+    })
+
+    emitKotlinRoute(route, emitter, new Map(), {
+      arrayItemNaming: false,
+      depluralize: true,
+      uncountableWords: ['data', 'metadata'],
+    })
+
+    expect(calls).toHaveLength(1)
+    expect(calls[0]!.opts.arrayItemNaming).toBe(false)
+    expect(calls[0]!.opts.depluralize).toBe(true)
+    expect(calls[0]!.opts.uncountableWords).toEqual(['data', 'metadata'])
+  })
+
+  it('does not include passthrough keys when caller omits them', () => {
+    const route = {
+      kind: 'api',
+      name: 'X',
+      method: 'GET',
+      fullPath: '/x',
+      schema: { returnType: { type: 'object' } },
+      errors: [],
+    } as unknown as AnyHttpRouteDoc
+
+    const { emitter, calls } = makeSpyEmitter({
+      Response: ok('@Serializable data class Response(val ok: Boolean)', 'Response'),
+    })
+
+    emitKotlinRoute(route, emitter, new Map(), {})
+
+    expect(calls).toHaveLength(1)
+    // Conditional-spread invariant: undefined opts must NOT be forwarded as keys
+    // (otherwise ajsc would receive `{ arrayItemNaming: undefined }` etc, which
+    // could shadow ajsc-side defaults).
+    expect('arrayItemNaming' in calls[0]!.opts).toBe(false)
+    expect('depluralize' in calls[0]!.opts).toBe(false)
+    expect('uncountableWords' in calls[0]!.opts).toBe(false)
+    // serializer / unsupportedUnions same invariant
+    expect('serializer' in calls[0]!.opts).toBe(false)
+    expect('unsupportedUnions' in calls[0]!.opts).toBe(false)
+    // inlineTypes is always set
+    expect(calls[0]!.opts.inlineTypes).toBe(true)
+  })
+})

package/src/codegen/targets/kotlin/emit-route-kotlin.ts

@@ -0,0 +1,89 @@
+import type { AnyHttpRouteDoc } from '../../../implementations/types.js'
+import type { KotlinEmitter, KotlinEmitOptions } from './ajsc-adapter.js'
+import { indent } from '../_shared/indent.js'
+import { pickDefined } from '../_shared/pick-defined.js'
+import { toBracePath, pathParamNames } from '../_shared/path-utils.js'
+import { extractRouteSlots } from '../_shared/route-slots.js'
+
+export interface EmitRouteResult {
+  /** Inner body of the `object RouteName { ... }` block — already indented one level. */
+  code: string
+  /** Imports collected from every ajsc emit + any helpers this route used. */
+  imports: string[]
+  /** Outer route name used as the `object RouteName` identifier. */
+  routeName: string
+  /** True when the route was a stream (out-of-scope). Caller logs once. */
+  skipped?: boolean
+}
+
+/** Subset of KotlinEmitOptions threaded by the pipeline; per-call rootTypeName is set inside. */
+export type EmitRouteOpts = Omit<KotlinEmitOptions, 'rootTypeName' | 'inlineTypes'>
+
+function buildPathFn(bracePath: string, params: string[]): string {
+  if (params.length === 0) return `const val path = "${bracePath}"`
+  let body = bracePath
+  for (const name of params) body = body.replace(`{${name}}`, `\${p.${name}}`)
+  return `fun path(p: PathParams): String = "${body}"`
+}
+
+function emitOptsFor(rootTypeName: string, routeOpts: EmitRouteOpts): KotlinEmitOptions {
+  const PASSTHROUGH_KEYS = ['serializer', 'unsupportedUnions', 'arrayItemNaming', 'depluralize', 'uncountableWords'] as const
+  return {
+    rootTypeName,
+    inlineTypes: true,
+    ...pickDefined(routeOpts, PASSTHROUGH_KEYS),
+  }
+}
+
+export function emitKotlinRoute(
+  route: AnyHttpRouteDoc,
+  emitter: KotlinEmitter,
+  errorSchemas: Map<string, unknown>,
+  routeOpts: EmitRouteOpts = {},
+): EmitRouteResult {
+  const kind = (route as { kind?: string }).kind
+  if (kind === 'stream') {
+    return { code: '', imports: [], routeName: route.name, skipped: true }
+  }
+
+  const isApi = kind === 'api' || 'fullPath' in route
+  const rawPath = isApi ? (route as { fullPath: string }).fullPath : (route as { path: string }).path
+  const method = String((route as { method: string }).method).toUpperCase()
+  const bracePath = toBracePath(rawPath)
+  const params = pathParamNames(rawPath)
+
+  const lines: string[] = [
+    `const val method = "${method}"`,
+    `const val pathTemplate = "${bracePath}"`,
+    buildPathFn(bracePath, params),
+  ]
+  const imports: string[] = []
+
+  // Per-slot emission. Order is fixed for deterministic output.
+  for (const slot of extractRouteSlots(route)) {
+    const result = emitter.emit(slot.source as Record<string, unknown>, emitOptsFor(slot.rootName, routeOpts))
+    lines.push('')
+    lines.push(result.code)
+    imports.push(...result.imports)
+  }
+
+  // Errors namespace — route.errors is `string[]` of taxonomy keys; look up each schema
+  // from the envelope-level errors map. Keys without schemas are skipped silently
+  // (matching the existing TS scope emitter's `errorKeys` filter).
+  const routeErrorKeys = ((route as { errors?: string[] }).errors ?? [])
+    .filter((key) => errorSchemas.has(key))
+  if (routeErrorKeys.length > 0) {
+    const inner: string[] = []
+    for (const key of routeErrorKeys) {
+      const r = emitter.emit(errorSchemas.get(key) as Record<string, unknown>, emitOptsFor(key, routeOpts))
+      inner.push(r.code)
+      imports.push(...r.imports)
+    }
+    lines.push('')
+    lines.push('object Errors {')
+    lines.push(indent(inner.join('\n\n'), 1))
+    lines.push('}')
+  }
+
+  return { code: lines.join('\n'), imports, routeName: route.name, skipped: false }
+}

package/src/codegen/targets/kotlin/emit-scope-kotlin.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, it } from 'vitest'
+import type { AnyHttpRouteDoc } from '../../../implementations/types.js'
+import type { ScopeGroup } from '../../group-routes.js'
+import { emitKotlinScope } from './emit-scope-kotlin.js'
+import { createStubKotlinEmitter, type KotlinEmitOptions, type KotlinEmitResult } from './ajsc-adapter.js'
+
+const ok = (code: string, rootTypeName: string): KotlinEmitResult => ({
+  code,
+  rootTypeName,
+  extractedTypeNames: [],
+  imports: ['kotlinx.serialization.Serializable'],
+})
+
+describe('emitKotlinScope', () => {
+  it('produces a complete kotlin source file for a single-route scope', () => {
+    const route: AnyHttpRouteDoc = {
+      kind: 'api',
+      name: 'GetUser',
+      method: 'GET',
+      fullPath: '/users/:id',
+      schema: { input: { pathParams: { type: 'object' } }, returnType: { type: 'object' } },
+      errors: [],
+    } as unknown as AnyHttpRouteDoc
+
+    const group: ScopeGroup = { scopeKey: 'users', camelCase: 'users', routes: [route] }
+    const emitter = createStubKotlinEmitter({
+      PathParams: ok('@Serializable data class PathParams(val id: String)', 'PathParams'),
+      Response: ok('@Serializable data class Response(val id: String)', 'Response'),
+    })
+
+    const file = emitKotlinScope(group, { kotlinPackage: 'com.example.api', sourceHash: 'abc123' }, emitter, new Map())
+
+    expect(file.filename).toBe('Users.kt')
+    expect(file.code).toContain('package com.example.api')
+    expect(file.code).toContain('// Source hash: abc123')
+    expect(file.code).toContain('import kotlinx.serialization.Serializable')
+    expect(file.code).toContain('object Users {')
+    expect(file.code).toContain('object GetUser {')
+    expect(file.code).toContain('const val method = "GET"')
+  })
+
+  it('joins multiple routes inside one scope object', () => {
+    const route1 = { kind: 'api', name: 'GetUser', method: 'GET', fullPath: '/users/:id', schema: {}, errors: [] } as unknown as AnyHttpRouteDoc
+    const route2 = { kind: 'api', name: 'CreateUser', method: 'POST', fullPath: '/users', schema: {}, errors: [] } as unknown as AnyHttpRouteDoc
+    const group: ScopeGroup = { scopeKey: 'users', camelCase: 'users', routes: [route1, route2] }
+    const emitter = createStubKotlinEmitter({})
+
+    const file = emitKotlinScope(group, { kotlinPackage: 'com.example.api', sourceHash: 'h' }, emitter, new Map())
+    expect(file.code).toContain('object GetUser {')
+    expect(file.code).toContain('object CreateUser {')
+    // exactly one outer scope object
+    expect((file.code.match(/^object Users \{/gm) ?? []).length).toBe(1)
+  })
+
+  it('uses PascalCase scope name for the filename and outer object', () => {
+    const group: ScopeGroup = { scopeKey: 'admin-users', camelCase: 'adminUsers', routes: [] }
+    const file = emitKotlinScope(group, { kotlinPackage: 'p', sourceHash: 'h' }, createStubKotlinEmitter({}), new Map())
+    expect(file.filename).toBe('AdminUsers.kt')
+    expect(file.code).toContain('object AdminUsers {')
+  })
+
+  it('threads all 5 passthrough opts to every emitter call', () => {
+    const route = { kind: 'api', name: 'X', method: 'GET', fullPath: '/x', schema: { returnType: { type: 'object' } }, errors: [] } as unknown as AnyHttpRouteDoc
+    const group: ScopeGroup = { scopeKey: 'x', camelCase: 'x', routes: [route] }
+
+    const calls: KotlinEmitOptions[] = []
+    const emitter = {
+      emit(_s: unknown, opts: KotlinEmitOptions) {
+        calls.push(opts)
+        return { code: 'data class Response', rootTypeName: 'Response', extractedTypeNames: [], imports: [] }
+      },
+    }
+
+    emitKotlinScope(
+      group,
+      {
+        kotlinPackage: 'p',
+        sourceHash: 'h',
+        serializer: 'none',
+        unsupportedUnions: 'fallback',
+        arrayItemNaming: false,
+        depluralize: true,
+        uncountableWords: ['data', 'metadata'],
+      },
+      emitter,
+      new Map(),
+    )
+
+    expect(calls.length).toBe(1)
+    expect(calls[0]!.inlineTypes).toBe(true)
+    expect(calls[0]!.serializer).toBe('none')
+    expect(calls[0]!.unsupportedUnions).toBe('fallback')
+    expect(calls[0]!.arrayItemNaming).toBe(false)
+    expect(calls[0]!.depluralize).toBe(true)
+    expect(calls[0]!.uncountableWords).toEqual(['data', 'metadata'])
+  })
+
+  it('collects skipped stream-route names', () => {
+    const stream = { kind: 'stream', name: 'WatchUsers', method: 'GET', path: '/u/stream', schema: {}, errors: [] } as unknown as AnyHttpRouteDoc
+    const api = { kind: 'api', name: 'GetUser', method: 'GET', fullPath: '/u', schema: { returnType: { type: 'object' } }, errors: [] } as unknown as AnyHttpRouteDoc
+    const group: ScopeGroup = { scopeKey: 'u', camelCase: 'u', routes: [stream, api] }
+
+    const emitter = createStubKotlinEmitter({
+      Response: ok('data class Response(val id: String)', 'Response'),
+    })
+    const result = emitKotlinScope(group, { kotlinPackage: 'p', sourceHash: 'h' }, emitter, new Map())
+
+    expect(result.skippedStreams).toEqual(['WatchUsers'])
+    expect(result.code).toContain('object GetUser')
+    expect(result.code).not.toContain('object WatchUsers')
+  })
+})

package/src/codegen/targets/kotlin/emit-scope-kotlin.ts

@@ -0,0 +1,60 @@
+import type { ScopeGroup } from '../../group-routes.js'
+import type { KotlinEmitter } from './ajsc-adapter.js'
+import { emitKotlinRoute, type EmitRouteOpts } from './emit-route-kotlin.js'
+import { kotlinPackageDecl, kotlinSourceHashHeader, kotlinImports } from './format-kotlin.js'
+import { indent } from '../_shared/indent.js'
+import { pickDefined } from '../_shared/pick-defined.js'
+import { pascalCase } from '../_shared/pascal-case.js'
+
+export interface EmitScopeOptions extends EmitRouteOpts {
+  kotlinPackage: string
+  sourceHash: string
+}
+
+export interface EmittedKotlinFile {
+  filename: string
+  code: string
+  /** Names of stream routes within this scope that were skipped. */
+  skippedStreams: string[]
+}
+
+export function emitKotlinScope(
+  group: ScopeGroup,
+  opts: EmitScopeOptions,
+  emitter: KotlinEmitter,
+  errorSchemas: Map<string, unknown>,
+): EmittedKotlinFile {
+  const scopeName = pascalCase(group.scopeKey)
+  const allImports: string[] = []
+  const routeBlocks: string[] = []
+  const skippedStreams: string[] = []
+
+  const PASSTHROUGH_KEYS = ['serializer', 'unsupportedUnions', 'arrayItemNaming', 'depluralize', 'uncountableWords'] as const
+  const routeOpts: EmitRouteOpts = pickDefined(opts, PASSTHROUGH_KEYS)
+
+  for (const route of group.routes) {
+    const r = emitKotlinRoute(route, emitter, errorSchemas, routeOpts)
+    if (r.skipped) {
+      skippedStreams.push(r.routeName)
+      continue
+    }
+    allImports.push(...r.imports)
+    const wrapped = `object ${r.routeName} {\n${indent(r.code, 1)}\n}`
+    routeBlocks.push(wrapped)
+  }
+
+  const innerScope = routeBlocks.length === 0 ? '' : indent(routeBlocks.join('\n\n'), 1)
+  const scopeBlock = innerScope === ''
+    ? `object ${scopeName} {\n}`
+    : `object ${scopeName} {\n${innerScope}\n}`
+
+  const importsBlock = kotlinImports(allImports)
+  const parts = [
+    kotlinPackageDecl(opts.kotlinPackage),
+    kotlinSourceHashHeader(opts.sourceHash),
+    importsBlock,
+    scopeBlock,
+  ].filter((p) => p.length > 0)
+
+  return { filename: `${scopeName}.kt`, code: parts.join('\n\n') + '\n', skippedStreams }
+}

package/src/codegen/targets/kotlin/format-kotlin.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest'
+import {
+  kotlinPackageDecl,
+  kotlinSourceHashHeader,
+  kotlinImports,
+} from './format-kotlin.js'
+
+describe('format-kotlin', () => {
+  it('emits a package declaration', () => {
+    expect(kotlinPackageDecl('com.example.api')).toBe('package com.example.api')
+  })
+
+  it('emits a source-hash header line', () => {
+    expect(kotlinSourceHashHeader('abc123')).toBe('// Source hash: abc123')
+  })
+
+  it('dedupes and sorts imports', () => {
+    expect(kotlinImports(['kotlinx.serialization.Serializable', 'kotlinx.serialization.SerialName', 'kotlinx.serialization.Serializable'])).toBe(
+      'import kotlinx.serialization.SerialName\nimport kotlinx.serialization.Serializable',
+    )
+  })
+
+  it('returns empty string when no imports', () => {
+    expect(kotlinImports([])).toBe('')
+  })
+})

package/src/codegen/targets/kotlin/format-kotlin.ts

@@ -0,0 +1,13 @@
+export function kotlinPackageDecl(pkg: string): string {
+  return `package ${pkg}`
+}
+
+export function kotlinSourceHashHeader(hash: string): string {
+  return `// Source hash: ${hash}`
+}
+
+export function kotlinImports(imports: string[]): string {
+  if (imports.length === 0) return ''
+  const unique = Array.from(new Set(imports)).sort()
+  return unique.map((i) => `import ${i}`).join('\n')
+}