ts-procedures 6.0.2 → 6.2.0

package/src/codegen/targets/kotlin/integration.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vitest'
+import { readFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { runPipeline } from '../../pipeline.js'
+import { assertGoldenOrUpdate } from '../../test-helpers/golden.js'
+import { createStubKotlinEmitter, type KotlinEmitResult } from './ajsc-adapter.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+const ok = (code: string, rootTypeName: string, imports: string[] = ['kotlinx.serialization.Serializable']): KotlinEmitResult => ({
+  code,
+  rootTypeName,
+  extractedTypeNames: [],
+  imports,
+})
+
+describe('kotlin codegen — integration', () => {
+  it('produces byte-identical output against the golden fixture', async () => {
+    const envelopePath = join(__dirname, '../../__fixtures__/users-envelope.json')
+    const goldenPath = join(__dirname, '__fixtures__/users-golden.kt')
+    const envelope = JSON.parse(await readFile(envelopePath, 'utf8'))
+
+    // Hand-authored slot outputs in the v7.2 nested-class shape (inlineTypes: true).
+    //
+    // The stub map is keyed on rootTypeName, NOT on (route, slot). Both GetUser
+    // and CreateUser have a slot named "Response" — they intentionally share the
+    // single stub entry below. The golden file therefore shows three identical
+    // Response data classes (one per route that has one). This is correct: the
+    // integration test pins our file-assembly logic, not real ajsc per-route
+    // output. The kotlinc E2E (Task 11) exercises real ajsc against the same
+    // fixture and would surface any incompatibility.
+    const emitter = createStubKotlinEmitter({
+      // GetUser
+      PathParams: ok('@Serializable\ndata class PathParams(\n    val id: String,\n)', 'PathParams'),
+      Response: ok(
+        '@Serializable\ndata class Response(\n    val id: String,\n    val name: String,\n    @SerialName("created-at") @Contextual val createdAt: java.time.Instant,\n    val address: Address,\n) {\n    @Serializable\n    data class Address(\n        val street: String,\n        val city: String,\n    )\n}',
+        'Response',
+        ['kotlinx.serialization.Serializable', 'kotlinx.serialization.SerialName', 'kotlinx.serialization.Contextual'],
+      ),
+      NotFound: ok(
+        '@Serializable\ndata class NotFound(\n    val name: String = "NotFound",\n    val message: String,\n)',
+        'NotFound',
+      ),
+
+      // CreateUser
+      Body: ok(
+        '@Serializable\n@JsonClassDiscriminator("kind")\nsealed interface Body {\n    @Serializable\n    @SerialName("guest")\n    data class GuestBody(\n        val displayName: String,\n    ) : Body\n\n    @Serializable\n    @SerialName("registered")\n    data class RegisteredBody(\n        val email: String,\n        val name: String,\n    ) : Body\n}',
+        'Body',
+        ['kotlinx.serialization.Serializable', 'kotlinx.serialization.SerialName', 'kotlinx.serialization.json.JsonClassDiscriminator'],
+      ),
+      ValidationError: ok(
+        '@Serializable\ndata class ValidationError(\n    val name: String = "ValidationError",\n    val message: String,\n    val field: String? = null,\n)',
+        'ValidationError',
+      ),
+
+      // ListUsers
+      Query: ok(
+        '@Serializable\ndata class Query(\n    val status: Status? = null,\n    val limit: Long? = null,\n) {\n    @Serializable\n    enum class Status {\n        @SerialName("active") ACTIVE,\n        @SerialName("inactive") INACTIVE,\n    }\n}',
+        'Query',
+        ['kotlinx.serialization.Serializable', 'kotlinx.serialization.SerialName'],
+      ),
+    })
+
+    const files = await runPipeline({
+      envelope, outDir: 'out', dryRun: true,
+      target: 'kotlin', kotlinPackage: 'com.example.api',
+      kotlinEmitter: emitter,
+    })
+
+    expect(files).toHaveLength(1)
+    expect(files[0]!.path).toBe(join('out', 'Users.kt'))
+
+    await assertGoldenOrUpdate(files[0]!.code, goldenPath)
+  })
+})

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

@@ -0,0 +1,64 @@
+import { describe, it, expect } from 'vitest'
+
+let ajscResolvable = false
+let emitKotlinFn:
+  | ((
+      schema: unknown,
+      opts: unknown,
+    ) => { code: string; imports: string[]; rootTypeName: string; extractedTypeNames: string[] })
+  | undefined
+
+try {
+  const ajsc = await import('ajsc')
+  if (typeof (ajsc as { emitKotlin?: unknown }).emitKotlin === 'function') {
+    ajscResolvable = true
+    emitKotlinFn = (ajsc as { emitKotlin: typeof emitKotlinFn }).emitKotlin!
+  }
+} catch {
+  // ajsc not installed (e.g. npm install --omit=optional); test skips below.
+}
+
+describe('ajsc.emitKotlin — untagged oneOf behavior', () => {
+  it.skipIf(!ajscResolvable)(
+    'produces a deterministic fallback shape for an untagged oneOf',
+    () => {
+      const schema = {
+        oneOf: [{ type: 'string' }, { type: 'integer' }],
+      }
+      const result = emitKotlinFn!(schema, {
+        rootTypeName: 'Mixed',
+        inlineTypes: true,
+        unsupportedUnions: 'fallback',
+      })
+
+      // Snapshot pins the current ajsc behavior. If ajsc changes the fallback
+      // shape, this diff prompts an intentional review and a corresponding
+      // update to docs/codegen-kotlin.md.
+      expect({
+        code: result.code,
+        imports: result.imports.slice().sort(),
+        rootTypeName: result.rootTypeName,
+        extractedTypeNames: result.extractedTypeNames.slice().sort(),
+      }).toMatchSnapshot()
+    },
+  )
+
+  // Companion to test 1: confirms 'fallback' is not load-bearing — ajsc emits the
+  // same shape with or without it. If these snapshots ever diverge, that's a
+  // meaningful behavior change worth surfacing in docs/codegen-kotlin.md.
+  it.skipIf(!ajscResolvable)(
+    'silently falls back to empty data class when unsupportedUnions is not specified',
+    () => {
+      const schema = { oneOf: [{ type: 'string' }, { type: 'integer' }] }
+      const result = emitKotlinFn!(schema, { rootTypeName: 'Mixed', inlineTypes: true })
+      // When unsupportedUnions defaults (not explicitly set), ajsc does NOT throw.
+      // Instead it silently emits an empty data class.
+      expect({
+        code: result.code,
+        imports: result.imports.slice().sort(),
+        rootTypeName: result.rootTypeName,
+        extractedTypeNames: result.extractedTypeNames.slice().sort(),
+      }).toMatchSnapshot()
+    },
+  )
+})

package/src/codegen/targets/kotlin/run.ts

@@ -0,0 +1,78 @@
+/**
+ * Kotlin-target pipeline runner. Invoked by the dispatcher in
+ * `src/codegen/pipeline.ts` when `target === 'kotlin'`. Emits one `.kt` file
+ * per scope via `emitKotlinScope` and commits via the shared
+ * `writeGeneratedFiles` tail.
+ */
+import { join } from 'node:path'
+import type { GeneratedFile } from '../_shared/write-files.js'
+import { writeGeneratedFiles } from '../_shared/write-files.js'
+import { buildErrorSchemasMap } from '../_shared/error-schemas.js'
+import { pickDefined } from '../_shared/pick-defined.js'
+import type { TargetRunInput } from '../_shared/target-run.js'
+import type { KotlinEmitter } from './ajsc-adapter.js'
+import { emitKotlinScope } from './emit-scope-kotlin.js'
+
+export interface KotlinRunInput extends TargetRunInput {
+  kotlinPackage?: string
+  kotlinSerializer?: 'kotlinx' | 'none'
+  unsupportedUnions?: 'throw' | 'fallback'
+  /** Injected for tests; production wiring resolves a real ajsc emitter. */
+  kotlinEmitter?: KotlinEmitter
+}
+
+/**
+ * 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 AJSC_PASSTHROUGH_KEYS = ['arrayItemNaming', 'depluralize', 'uncountableWords'] as const
+
+export async function runKotlinPipeline(input: KotlinRunInput): Promise<GeneratedFile[]> {
+  const { envelope, outDir, hash, groups, dryRun = false, cleanOutDir = false } = input
+
+  // Runtime guards for non-CLI callers (direct API consumers + tests).
+  // The CLI validates --kotlin-package in parseArgs and resolves the emitter
+  // before calling runPipeline, so end users never hit these throws.
+  if (input.kotlinPackage == null) {
+    throw new Error('[ts-procedures-codegen] target=kotlin requires kotlinPackage')
+  }
+  if (input.kotlinEmitter == null) {
+    throw new Error(
+      '[ts-procedures-codegen] target=kotlin requires a kotlinEmitter (CLI resolves via resolveProductionKotlinEmitter)'
+    )
+  }
+
+  const errorSchemas = buildErrorSchemasMap(envelope.errors)
+  const ajscPassthrough = input.ajsc ?? {}
+
+  const files: GeneratedFile[] = []
+  const allSkipped: string[] = []
+  for (const group of groups) {
+    const emitted = emitKotlinScope(
+      group,
+      {
+        kotlinPackage: input.kotlinPackage,
+        sourceHash: hash,
+        ...(input.kotlinSerializer !== undefined ? { serializer: input.kotlinSerializer } : {}),
+        ...(input.unsupportedUnions !== undefined ? { unsupportedUnions: input.unsupportedUnions } : {}),
+        ...pickDefined(ajscPassthrough, AJSC_PASSTHROUGH_KEYS),
+      },
+      input.kotlinEmitter,
+      errorSchemas,
+    )
+    files.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(', ')}`,
+    )
+  }
+
+  await writeGeneratedFiles(files, outDir, { dryRun, cleanOutDir })
+
+  return files
+}

package/src/codegen/targets/swift/__fixtures__/users-golden.swift

@@ -0,0 +1,123 @@
+// Generated by ts-procedures-codegen — do not edit.
+// Source hash: <PLACEHOLDER>
+
+import Foundation
+
+public enum Users {
+    public enum GetUser {
+        public static let method = "GET"
+        public static let pathTemplate = "/users/{id}"
+        public static func path(_ p: PathParams) -> String { return "/users/\(p.id)" }
+
+        public struct PathParams: Codable {
+            public let id: String
+        }
+
+        public struct Response: Codable {
+            public let id: String
+            public let name: String
+            public let createdAt: Date
+            public let address: Address
+
+            enum CodingKeys: String, CodingKey {
+                case id, name
+                case createdAt = "created-at"
+                case address
+            }
+
+            public struct Address: Codable {
+                public let street: String
+                public let city: String
+            }
+        }
+
+        public enum Errors {
+            public struct NotFound: Codable {
+                public let name: String
+                public let message: String
+            }
+        }
+    }
+
+    public enum CreateUser {
+        public static let method = "POST"
+        public static let pathTemplate = "/users"
+        public static let path = "/users"
+
+        public enum Body: Codable {
+            case guest(GuestBody)
+            case registered(RegisteredBody)
+
+            public struct GuestBody: Codable {
+                public let kind: String
+                public let displayName: String
+            }
+
+            public struct RegisteredBody: Codable {
+                public let kind: String
+                public let email: String
+                public let name: String
+            }
+        }
+
+        public struct Response: Codable {
+            public let id: String
+            public let name: String
+            public let createdAt: Date
+            public let address: Address
+
+            enum CodingKeys: String, CodingKey {
+                case id, name
+                case createdAt = "created-at"
+                case address
+            }
+
+            public struct Address: Codable {
+                public let street: String
+                public let city: String
+            }
+        }
+
+        public enum Errors {
+            public struct ValidationError: Codable {
+                public let name: String
+                public let message: String
+                public let field: String?
+            }
+        }
+    }
+
+    public enum ListUsers {
+        public static let method = "GET"
+        public static let pathTemplate = "/users"
+        public static let path = "/users"
+
+        public struct Query: Codable {
+            public let status: Status?
+            public let limit: Int64?
+
+            public enum Status: String, Codable {
+                case active
+                case inactive
+            }
+        }
+
+        public struct Response: Codable {
+            public let id: String
+            public let name: String
+            public let createdAt: Date
+            public let address: Address
+
+            enum CodingKeys: String, CodingKey {
+                case id, name
+                case createdAt = "created-at"
+                case address
+            }
+
+            public struct Address: Codable {
+                public let street: String
+                public let city: String
+            }
+        }
+    }
+}

package/src/codegen/targets/swift/access-level.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from 'vitest'
+import type { DocEnvelope } from '../../../implementations/types.js'
+import { runPipeline } from '../../pipeline.js'
+import { resolveProductionSwiftEmitter } from './ajsc-adapter.js'
+
+/**
+ * End-to-end regression for `--swift-access-level`.
+ *
+ * Closes a coverage gap: existing unit tests verify our scope/route
+ * scaffolding (the outer `enum` keywords) honor the access level, but
+ * nothing asserts that real ajsc actually emits `internal struct` /
+ * `internal let` in its own output. If ajsc renamed `accessLevel` or
+ * changed its semantics, our codegen would silently regress to `public`.
+ *
+ * This test runs the production pipeline with the real ajsc emitter
+ * and pins the keyword presence in the generated source. No toolchain
+ * (no swiftc) is required — we only assert string contents.
+ */
+const envelope: DocEnvelope = {
+  basePath: '/api',
+  headers: [],
+  errors: [],
+  routes: [
+    {
+      kind: 'api',
+      name: 'GetThing',
+      scope: 'things',
+      method: 'get',
+      path: '/things/:id',
+      fullPath: '/things/:id',
+      jsonSchema: {},
+      // The swift route emitter reads `route.schema.input.*` and
+      // `route.schema.returnType` directly; mirror what the codegen
+      // pipeline downstream expects rather than the doc-builder
+      // `jsonSchema` shape.
+      schema: {
+        input: {
+          pathParams: {
+            type: 'object',
+            properties: { id: { type: 'string' } },
+            required: ['id'],
+          },
+        },
+        returnType: {
+          type: 'object',
+          properties: { id: { type: 'string' } },
+          required: ['id'],
+        },
+      },
+      errors: [],
+    } as unknown as DocEnvelope['routes'][number],
+  ],
+}
+
+describe('swift codegen — --swift-access-level (real ajsc)', () => {
+  it('emits `internal` keywords on ajsc-generated structs when accessLevel="internal"', async () => {
+    const emitter = await resolveProductionSwiftEmitter()
+    const files = await runPipeline({
+      envelope,
+      outDir: 'out',
+      dryRun: true,
+      target: 'swift',
+      swiftAccessLevel: 'internal',
+      swiftEmitter: emitter,
+    })
+
+    expect(files).toHaveLength(1)
+    const code = files[0]!.code
+
+    // Real ajsc output for the PathParams + Response slots.
+    expect(code).toContain('internal struct PathParams')
+    expect(code).toContain('internal struct Response')
+    // Property declarations should also flip to internal.
+    expect(code).toContain('internal let id: String')
+
+    // Our scope/route scaffolding flips too — see emit-scope-swift.ts
+    // and emit-route-swift.ts, which both consume `accessLevel`.
+    expect(code).toContain('internal enum Things')
+    expect(code).toContain('internal enum GetThing')
+
+    // Hard guarantee: nothing in the file leaks `public` declarations.
+    // If ajsc silently ignored `accessLevel: 'internal'`, this would fail.
+    expect(code).not.toMatch(/\bpublic\s+(struct|enum|let|var|func|static)\b/)
+  })
+
+  it('emits `public` keywords on ajsc-generated structs when accessLevel defaults to public', async () => {
+    const emitter = await resolveProductionSwiftEmitter()
+    const files = await runPipeline({
+      envelope,
+      outDir: 'out',
+      dryRun: true,
+      target: 'swift',
+      // intentionally omit swiftAccessLevel — default is 'public'
+      swiftEmitter: emitter,
+    })
+
+    expect(files).toHaveLength(1)
+    const code = files[0]!.code
+
+    expect(code).toContain('public struct PathParams')
+    expect(code).toContain('public struct Response')
+    expect(code).toContain('public enum Things')
+    expect(code).toContain('public enum GetThing')
+
+    // No `internal` declarations should appear when access level is public.
+    expect(code).not.toMatch(/\binternal\s+(struct|enum|let|var|func|static)\b/)
+  })
+})

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

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest'
+import { createStubSwiftEmitter, resolveProductionSwiftEmitter, type SwiftEmitResult } from './ajsc-adapter.js'
+
+describe('createStubSwiftEmitter', () => {
+  it('returns the configured EmitResult for the matching root name', () => {
+    const expected: SwiftEmitResult = {
+      code: 'public struct User: Codable { public let id: String }',
+      rootTypeName: 'User',
+      extractedTypeNames: [],
+      imports: ['Foundation'],
+    }
+    const emitter = createStubSwiftEmitter({ User: expected })
+    expect(
+      emitter.emit(
+        { type: 'object' },
+        {
+          rootTypeName: 'User',
+          inlineTypes: true,
+          serializer: 'codable',
+          unsupportedUnions: 'throw',
+        },
+      ),
+    ).toEqual(expected)
+  })
+
+  it('throws when asked to emit a name not in the stub map', () => {
+    const emitter = createStubSwiftEmitter({})
+    expect(() => emitter.emit({}, { rootTypeName: 'Missing' })).toThrow(/Missing/)
+  })
+})
+
+describe('resolveProductionSwiftEmitter', () => {
+  it('returns a working emitter that invokes ajsc.emitSwift when ajsc is installed', async () => {
+    const emitter = await resolveProductionSwiftEmitter()
+    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/swift/ajsc-adapter.ts

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

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

@@ -0,0 +1,66 @@
+import { describe, it, expect } from 'vitest'
+import { execFileSync, execSync } from 'node:child_process'
+import { mkdtempSync, writeFileSync, readFileSync, 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 { resolveProductionSwiftEmitter } from './ajsc-adapter.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+function swiftcAvailable(): boolean {
+  try {
+    execSync('swiftc --version', { stdio: 'ignore' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+const RUN = process.env.TS_PROCEDURES_SWIFT_E2E === '1'
+
+/**
+ * E2E: real ajsc → real .swift output → real swiftc parse.
+ *
+ * Gated on (a) `swiftc` on PATH and (b) opt-in via env var so default
+ * `npm test` runs stay green for contributors without the toolchain.
+ *
+ * Unlike Kotlin, Swift's stdlib + Foundation already ship with `Codable`,
+ * so no extra classpath/jars are needed — `swiftc -parse` against a single
+ * file is sufficient to validate the output is syntactically well-formed.
+ */
+describe('swift codegen — swiftc compile (gated)', () => {
+  it.skipIf(!swiftcAvailable() || !RUN)(
+    'parses generated output without errors',
+    async () => {
+      const emitter = await resolveProductionSwiftEmitter()
+      const envelope = JSON.parse(
+        readFileSync(join(__dirname, '../../__fixtures__/users-envelope.json'), 'utf8'),
+      )
+      const files = await runPipeline({
+        envelope,
+        outDir: 'out',
+        dryRun: true,
+        target: 'swift',
+        swiftEmitter: emitter,
+      })
+
+      const dir = mkdtempSync(join(tmpdir(), 'tsp-swift-e2e-'))
+      const filePaths: string[] = []
+      for (const f of files) {
+        const dest = join(dir, f.path.split('/').pop()!)
+        writeFileSync(dest, f.code)
+        filePaths.push(dest)
+      }
+
+      // -parse only checks syntax; no codegen, no linking, no module deps.
+      execFileSync('swiftc', ['-parse', ...filePaths], { stdio: 'inherit' })
+
+      // Sanity check — at least one .swift file was generated and persisted.
+      expect(filePaths.length).toBeGreaterThan(0)
+      for (const p of filePaths) expect(existsSync(p)).toBe(true)
+    },
+  )
+})