ts-procedures 6.0.2 → 6.1.0

package/src/codegen/targets/kotlin/__fixtures__/users-golden.kt

@@ -0,0 +1,121 @@
+package com.example.api
+
+// Source hash: <PLACEHOLDER>
+
+import kotlinx.serialization.Contextual
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.JsonClassDiscriminator
+
+object Users {
+    object GetUser {
+        const val method = "GET"
+        const val pathTemplate = "/users/{id}"
+        fun path(p: PathParams): String = "/users/${p.id}"
+
+        @Serializable
+        data class PathParams(
+            val id: String,
+        )
+
+        @Serializable
+        data class Response(
+            val id: String,
+            val name: String,
+            @SerialName("created-at") @Contextual val createdAt: java.time.Instant,
+            val address: Address,
+        ) {
+            @Serializable
+            data class Address(
+                val street: String,
+                val city: String,
+            )
+        }
+
+        object Errors {
+            @Serializable
+            data class NotFound(
+                val name: String = "NotFound",
+                val message: String,
+            )
+        }
+    }
+
+    object CreateUser {
+        const val method = "POST"
+        const val pathTemplate = "/users"
+        const val path = "/users"
+
+        @Serializable
+        @JsonClassDiscriminator("kind")
+        sealed interface Body {
+            @Serializable
+            @SerialName("guest")
+            data class GuestBody(
+                val displayName: String,
+            ) : Body
+
+            @Serializable
+            @SerialName("registered")
+            data class RegisteredBody(
+                val email: String,
+                val name: String,
+            ) : Body
+        }
+
+        @Serializable
+        data class Response(
+            val id: String,
+            val name: String,
+            @SerialName("created-at") @Contextual val createdAt: java.time.Instant,
+            val address: Address,
+        ) {
+            @Serializable
+            data class Address(
+                val street: String,
+                val city: String,
+            )
+        }
+
+        object Errors {
+            @Serializable
+            data class ValidationError(
+                val name: String = "ValidationError",
+                val message: String,
+                val field: String? = null,
+            )
+        }
+    }
+
+    object ListUsers {
+        const val method = "GET"
+        const val pathTemplate = "/users"
+        const val path = "/users"
+
+        @Serializable
+        data class Query(
+            val status: Status? = null,
+            val limit: Long? = null,
+        ) {
+            @Serializable
+            enum class Status {
+                @SerialName("active") ACTIVE,
+                @SerialName("inactive") INACTIVE,
+            }
+        }
+
+        @Serializable
+        data class Response(
+            val id: String,
+            val name: String,
+            @SerialName("created-at") @Contextual val createdAt: java.time.Instant,
+            val address: Address,
+        ) {
+            @Serializable
+            data class Address(
+                val street: String,
+                val city: String,
+            )
+        }
+    }
+}

package/src/codegen/targets/kotlin/__snapshots__/probe-unsupported-unions.test.ts.snap

@@ -0,0 +1,27 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`ajsc.emitKotlin — untagged oneOf behavior > produces a deterministic fallback shape for an untagged oneOf 1`] = `
+{
+  "code": "@Serializable
+data class Mixed()
+",
+  "extractedTypeNames": [],
+  "imports": [
+    "kotlinx.serialization.Serializable",
+  ],
+  "rootTypeName": "Mixed",
+}
+`;
+
+exports[`ajsc.emitKotlin — untagged oneOf behavior > silently falls back to empty data class when unsupportedUnions is not specified 1`] = `
+{
+  "code": "@Serializable
+data class Mixed()
+",
+  "extractedTypeNames": [],
+  "imports": [
+    "kotlinx.serialization.Serializable",
+  ],
+  "rootTypeName": "Mixed",
+}
+`;

package/src/codegen/targets/kotlin/ajsc-adapter.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest'
+import { createStubKotlinEmitter, resolveProductionKotlinEmitter, type KotlinEmitResult } from './ajsc-adapter.js'
+
+describe('createStubKotlinEmitter', () => {
+  it('returns the configured EmitResult for the matching root name', () => {
+    const expected: KotlinEmitResult = {
+      code: '@Serializable data class User(val id: String)',
+      rootTypeName: 'User',
+      extractedTypeNames: [],
+      imports: ['kotlinx.serialization.Serializable'],
+    }
+    const emitter = createStubKotlinEmitter({ User: expected })
+    expect(
+      emitter.emit(
+        { type: 'object' },
+        {
+          rootTypeName: 'User',
+          inlineTypes: true,
+          serializer: 'kotlinx',
+          unsupportedUnions: 'throw',
+        },
+      ),
+    ).toEqual(expected)
+  })
+
+  it('throws when asked to emit a name not in the stub map', () => {
+    const emitter = createStubKotlinEmitter({})
+    expect(() => emitter.emit({}, { rootTypeName: 'Missing' })).toThrow(/Missing/)
+  })
+})
+
+describe('resolveProductionKotlinEmitter', () => {
+  it('returns a working emitter that invokes ajsc.emitKotlin when ajsc is installed', async () => {
+    const emitter = await resolveProductionKotlinEmitter()
+    const result = emitter.emit(
+      { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
+      { rootTypeName: 'Probe' },
+    )
+    expect(typeof result.code).toBe('string')
+    expect(result.code.length).toBeGreaterThan(0)
+    expect(result.rootTypeName).toBe('Probe')
+    expect(Array.isArray(result.imports)).toBe(true)
+  })
+  // Note: testing the failure path (ajsc unavailable) requires module mocking;
+  // we leave that as a manual-verification path. The error message is pinned
+  // by the message text below so any change requires updating both call sites.
+})

package/src/codegen/targets/kotlin/ajsc-adapter.ts

@@ -0,0 +1,66 @@
+export interface KotlinEmitResult {
+  code: string
+  rootTypeName: string
+  extractedTypeNames: string[]
+  imports: string[]
+}
+
+export interface KotlinEmitOptions {
+  rootTypeName: string
+  /** Always set true at our call sites; v7.2 default is false. */
+  inlineTypes?: boolean
+  serializer?: 'kotlinx' | 'none'
+  unsupportedUnions?: 'throw' | 'fallback'
+  arrayItemNaming?: string | false
+  depluralize?: boolean
+  uncountableWords?: string[]
+}
+
+export interface KotlinEmitter {
+  emit(schema: Record<string, unknown>, opts: KotlinEmitOptions): KotlinEmitResult
+}
+
+export function createStubKotlinEmitter(
+  results: Record<string, KotlinEmitResult>,
+): KotlinEmitter {
+  return {
+    emit(_schema, opts) {
+      const result = results[opts.rootTypeName]
+      if (result == null) {
+        throw new Error(
+          `[stub-kotlin-emitter] No stubbed result for rootTypeName "${opts.rootTypeName}". ` +
+            `Provide one in the results map.`,
+        )
+      }
+      return result
+    },
+  }
+}
+
+/**
+ * Resolves the production Kotlin emitter from `ajsc`. Throws a clear error
+ * if ajsc is not installed or does not expose `emitKotlin` (e.g. consumer
+ * ran `npm install --omit=optional` since ajsc is in optionalDependencies).
+ */
+export async function resolveProductionKotlinEmitter(): Promise<KotlinEmitter> {
+  let ajsc: { emitKotlin?: unknown } | null = null
+  let importError: unknown
+  try {
+    ajsc = (await import('ajsc')) as { emitKotlin?: unknown }
+  } catch (err) {
+    importError = err
+  }
+  const emitKotlin = ajsc?.emitKotlin
+  if (typeof emitKotlin !== 'function') {
+    throw new Error(
+      '[ts-procedures-codegen] ajsc.emitKotlin is not available. ' +
+      'Install ajsc (`npm install ajsc`) — it is an optional dependency.',
+      importError !== undefined ? { cause: importError } : undefined,
+    )
+  }
+  return {
+    emit(schema, opts) {
+      return (emitKotlin as (s: unknown, o: unknown) => KotlinEmitResult)(schema, opts)
+    },
+  }
+}

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)
+  })
+})