ts-procedures 6.0.2 → 6.2.0

package/src/codegen/index.ts

@@ -1,6 +1,8 @@
 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
@@ -11,6 +13,16 @@ export interface GenerateClientOptions extends ResolveInput {
   selfContained?: boolean
   serviceName?: string
   cleanOutDir?: boolean
+  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[]> {
@@ -25,8 +37,46 @@ export async function generateClient(options: GenerateClientOptions): Promise<Ge
     selfContained: options.selfContained,
     serviceName: options.serviceName,
     cleanOutDir: options.cleanOutDir,
+    target: options.target,
+    kotlinPackage: options.kotlinPackage,
+    kotlinSerializer: options.kotlinSerializer,
+    unsupportedUnions: options.unsupportedUnions,
+    kotlinEmitter: options.kotlinEmitter,
+    swiftSerializer: options.swiftSerializer,
+    swiftAccessLevel: options.swiftAccessLevel,
+    swiftEmitter: options.swiftEmitter,
   })
 }
 
 export type { AjscOptions } from './emit-types.js'
 export type { ResolveInput } from './resolve-envelope.js'
+
+/**
+ * @internal Subject to change with ajsc minor versions. Use for test injection
+ *   only; consumer code should not depend on this shape.
+ */
+export type { KotlinEmitter } from './targets/kotlin/ajsc-adapter.js'
+
+/**
+ * @internal Mirrors ajsc's `KotlinConverterOpts` and may shift with ajsc
+ *   minor versions. Use for test injection only.
+ */
+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.test.ts

@@ -1,6 +1,8 @@
 import { describe, it, expect, afterEach, vi } from 'vitest'
 import { generateClient } from './index.js'
 import { runPipeline } from './pipeline.js'
+import { createStubKotlinEmitter } from './targets/kotlin/ajsc-adapter.js'
+import type { KotlinEmitOptions } from './targets/kotlin/ajsc-adapter.js'
 import { mkdirSync, rmSync, readFileSync, existsSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
@@ -359,3 +361,176 @@ describe('generateClient pipeline', () => {
     )
   })
 })
+
+describe('runPipeline (kotlin target)', () => {
+  it('emits only .kt files when target is "kotlin"', async () => {
+    const envelope = {
+      basePath: '/api',
+      headers: [],
+      version: '1' as const,
+      routes: [
+        {
+          kind: 'api',
+          name: 'GetUser',
+          scope: 'users',
+          method: 'GET',
+          fullPath: '/users/:id',
+          schema: { input: { pathParams: { type: 'object' } }, returnType: { type: 'object' } },
+          errors: [],
+        },
+      ],
+      errors: [],
+    } as any
+
+    const files = await runPipeline({
+      envelope,
+      outDir: 'out',
+      dryRun: true,
+      target: 'kotlin',
+      kotlinPackage: 'com.example.api',
+      kotlinEmitter: createStubKotlinEmitter({
+        PathParams: {
+          code: '@Serializable data class PathParams(val id: String)',
+          rootTypeName: 'PathParams',
+          extractedTypeNames: [],
+          imports: ['kotlinx.serialization.Serializable'],
+        },
+        Response: {
+          code: '@Serializable data class Response(val id: String)',
+          rootTypeName: 'Response',
+          extractedTypeNames: [],
+          imports: ['kotlinx.serialization.Serializable'],
+        },
+      }),
+    })
+
+    expect(files.map((f) => f.path)).toEqual([join('out', 'Users.kt')])
+    expect(files[0]!.code).toContain('object Users {')
+  })
+
+  it('does not emit _errors.ts, index.ts, or client runtime files when target is "kotlin"', async () => {
+    const envelope = { basePath: '/api', headers: [], version: '1', routes: [], errors: [] } as any
+    const files = await runPipeline({
+      envelope,
+      outDir: 'out',
+      dryRun: true,
+      target: 'kotlin',
+      kotlinPackage: 'p',
+      kotlinEmitter: createStubKotlinEmitter({}),
+    })
+    expect(files.find((f) => f.path.endsWith('_errors.ts'))).toBeUndefined()
+    expect(files.find((f) => f.path.endsWith('index.ts'))).toBeUndefined()
+    expect(files.find((f) => f.path.endsWith('_client.ts'))).toBeUndefined()
+    expect(files.find((f) => f.path.endsWith('_types.ts'))).toBeUndefined()
+  })
+
+  it('threads kotlinSerializer and unsupportedUnions to the emitter', async () => {
+    const calls: KotlinEmitOptions[] = []
+    const captureEmitter = {
+      emit(_s: unknown, opts: KotlinEmitOptions) {
+        calls.push(opts)
+        return { code: 'data class Response(val id: String)', rootTypeName: opts.rootTypeName, extractedTypeNames: [], imports: [] }
+      },
+    }
+
+    const envelope = {
+      basePath: '/api', headers: [], version: '1' as const, errors: [],
+      routes: [
+        {
+          kind: 'api', name: 'GetUser', scope: 'users', method: 'GET', fullPath: '/users/:id',
+          schema: { input: { pathParams: { type: 'object' } }, returnType: { type: 'object' } },
+          errors: [],
+        },
+      ],
+    } as any
+
+    await runPipeline({
+      envelope, outDir: 'out', dryRun: true,
+      target: 'kotlin', kotlinPackage: 'p',
+      kotlinSerializer: 'none',
+      unsupportedUnions: 'fallback',
+      kotlinEmitter: captureEmitter,
+    })
+
+    expect(calls.length).toBeGreaterThan(0)
+    for (const c of calls) {
+      expect(c.serializer).toBe('none')
+      expect(c.unsupportedUnions).toBe('fallback')
+      expect(c.inlineTypes).toBe(true)
+    }
+  })
+
+  it('logs a single summary line for skipped stream routes', async () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    try {
+      const envelope = {
+        basePath: '/api', headers: [], version: '1' as const, errors: [],
+        routes: [
+          { kind: 'stream', name: 'WatchA', scope: 's', method: 'GET', path: '/a', schema: {}, errors: [] },
+          { kind: 'stream', name: 'WatchB', scope: 's', method: 'GET', path: '/b', schema: {}, errors: [] },
+          { kind: 'api', name: 'GetThing', scope: 's', method: 'GET', fullPath: '/c', schema: { returnType: { type: 'object' } }, errors: [] },
+        ],
+      } as any
+      await runPipeline({
+        envelope, outDir: 'out', dryRun: true,
+        target: 'kotlin', kotlinPackage: 'p',
+        kotlinEmitter: createStubKotlinEmitter({
+          Response: { code: 'data class Response(val ok: Boolean)', rootTypeName: 'Response', extractedTypeNames: [], imports: [] },
+        }),
+      })
+      const summary = logSpy.mock.calls.find((c) => String(c[0]).includes('Skipped'))
+      expect(summary).toBeDefined()
+      expect(String(summary![0])).toContain('Skipped 2 stream routes')
+      expect(String(summary![0])).toContain('WatchA')
+      expect(String(summary![0])).toContain('WatchB')
+    } finally {
+      logSpy.mockRestore()
+    }
+  })
+
+  it('does not log a summary when there are no skipped streams', async () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    try {
+      const envelope = {
+        basePath: '/api', headers: [], version: '1' as const, errors: [],
+        routes: [{ kind: 'api', name: 'X', scope: 's', method: 'GET', fullPath: '/x', schema: { returnType: { type: 'object' } }, errors: [] }],
+      } as any
+      await runPipeline({
+        envelope, outDir: 'out', dryRun: true,
+        target: 'kotlin', kotlinPackage: 'p',
+        kotlinEmitter: createStubKotlinEmitter({ Response: { code: 'data class Response(val x: Int)', rootTypeName: 'Response', extractedTypeNames: [], imports: [] } }),
+      })
+      const summary = logSpy.mock.calls.find((c) => String(c[0]).includes('Skipped'))
+      expect(summary).toBeUndefined()
+    } finally {
+      logSpy.mockRestore()
+    }
+  })
+
+  it('forwards ajsc passthroughs (arrayItemNaming/depluralize/uncountableWords) to the kotlin emitter', async () => {
+    const calls: KotlinEmitOptions[] = []
+    const captureEmitter = {
+      emit(_s: unknown, opts: KotlinEmitOptions) {
+        calls.push(opts)
+        return { code: 'data class Response(val id: String)', rootTypeName: opts.rootTypeName, extractedTypeNames: [], imports: [] }
+      },
+    }
+
+    const envelope = {
+      basePath: '/api', headers: [], version: '1' as const, errors: [],
+      routes: [{ kind: 'api', name: 'GetUser', scope: 'users', method: 'GET', fullPath: '/u', schema: { returnType: { type: 'object' } }, errors: [] }],
+    } as any
+
+    await runPipeline({
+      envelope, outDir: 'out', dryRun: true,
+      target: 'kotlin', kotlinPackage: 'p',
+      ajsc: { arrayItemNaming: 'Item', depluralize: true, uncountableWords: ['data'] },
+      kotlinEmitter: captureEmitter,
+    })
+
+    expect(calls.length).toBe(1)
+    expect(calls[0]!.arrayItemNaming).toBe('Item')
+    expect(calls[0]!.depluralize).toBe(true)
+    expect(calls[0]!.uncountableWords).toEqual(['data'])
+  })
+})

package/src/codegen/pipeline.ts

@@ -1,15 +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 { 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
@@ -21,117 +20,75 @@ export interface PipelineOptions {
   selfContained?: boolean
   serviceName?: string
   cleanOutDir?: boolean
+  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())
-
-  // 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 })
-  }
+  const groups = Array.from(groupRoutesByScope(envelope.routes).values())
 
-  // 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('')
+}

package/src/codegen/targets/_shared/path-utils.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest'
+import { COLON_PARAM_RE, toBracePath, pathParamNames } from './path-utils.js'
+
+describe('path-utils', () => {
+  describe('toBracePath', () => {
+    it('converts colon params to brace form', () => {
+      expect(toBracePath('/users/:id')).toBe('/users/{id}')
+    })
+
+    it('converts multiple params', () => {
+      expect(toBracePath('/orgs/:orgId/users/:userId')).toBe('/orgs/{orgId}/users/{userId}')
+    })
+
+    it('returns the template unchanged when there are no params', () => {
+      expect(toBracePath('/users')).toBe('/users')
+    })
+
+    it('supports underscore-prefixed param names', () => {
+      expect(toBracePath('/x/:_id')).toBe('/x/{_id}')
+    })
+
+    it('does not match leading-digit identifiers', () => {
+      // ":1abc" is not a valid identifier; should not be rewritten.
+      expect(toBracePath('/x/:1abc')).toBe('/x/:1abc')
+    })
+  })
+
+  describe('pathParamNames', () => {
+    it('returns an empty list for templates without params', () => {
+      expect(pathParamNames('/users')).toEqual([])
+    })
+
+    it('returns the single param name', () => {
+      expect(pathParamNames('/users/:id')).toEqual(['id'])
+    })
+
+    it('preserves the order of multiple params', () => {
+      expect(pathParamNames('/orgs/:orgId/users/:userId')).toEqual(['orgId', 'userId'])
+    })
+
+    it('matches identifiers with digits and underscores', () => {
+      expect(pathParamNames('/x/:user_id1')).toEqual(['user_id1'])
+    })
+  })
+
+  describe('COLON_PARAM_RE', () => {
+    it('is a global regex (so matchAll works)', () => {
+      expect(COLON_PARAM_RE.global).toBe(true)
+    })
+  })
+})

package/src/codegen/targets/_shared/path-utils.ts

@@ -0,0 +1,21 @@
+/**
+ * Language-agnostic path-template utilities used by every codegen target that
+ * emits HTTP routes. Routes carry colon-prefixed path templates (e.g.
+ * `/users/:id`); targets typically need both the brace form (`/users/{id}`)
+ * for documentation/template constants and the parameter-name list for
+ * generating typed path-builder functions.
+ */
+
+export const COLON_PARAM_RE = /:([A-Za-z_][A-Za-z0-9_]*)/g
+
+/** Converts colon-prefixed path params (`:foo`) to brace form (`{foo}`). */
+export function toBracePath(template: string): string {
+  return template.replace(COLON_PARAM_RE, '{$1}')
+}
+
+/** Extracts the parameter names from a colon-prefixed path template. */
+export function pathParamNames(template: string): string[] {
+  const names: string[] = []
+  for (const match of template.matchAll(COLON_PARAM_RE)) names.push(match[1]!)
+  return names
+}