ts-procedures 6.0.2 → 6.1.0

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

@@ -0,0 +1,109 @@
+import type { AnyHttpRouteDoc } from '../../../implementations/types.js'
+import type { KotlinEmitter, KotlinEmitOptions } from './ajsc-adapter.js'
+import { indent, pickDefined } from './format-kotlin.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'>
+
+const COLON_PARAM_RE = /:([A-Za-z_][A-Za-z0-9_]*)/g
+
+function toBracePath(template: string): string {
+  return template.replace(COLON_PARAM_RE, '{$1}')
+}
+
+function pathParamNames(template: string): string[] {
+  const names: string[] = []
+  for (const match of template.matchAll(COLON_PARAM_RE)) names.push(match[1]!)
+  return names
+}
+
+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[] = []
+
+  const schema = (route as { schema?: Record<string, unknown> }).schema ?? {}
+  const input = (schema.input ?? {}) as Record<string, unknown>
+
+  // Per-slot emission. Order is fixed for deterministic output.
+  const slots: Array<{ rootName: string; source: unknown }> = [
+    { rootName: 'PathParams', source: input.pathParams },
+    { rootName: 'Query', source: input.query },
+    { rootName: 'Body', source: input.body },
+    { rootName: 'Response', source: schema.returnType },
+  ]
+
+  for (const slot of slots) {
+    if (slot.source == null) continue
+    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,65 @@
+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, indent, pickDefined } from './format-kotlin.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[]
+}
+
+function pascalCase(scope: string): string {
+  return scope
+    .split('-')
+    .filter((p) => p.length > 0)
+    .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+    .join('')
+}
+
+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,70 @@
+import { describe, expect, it } from 'vitest'
+import {
+  kotlinPackageDecl,
+  kotlinSourceHashHeader,
+  kotlinImports,
+  indent,
+  pickDefined,
+} 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('')
+  })
+
+  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')
+  })
+})
+
+describe('pickDefined', () => {
+  it('returns only the keys whose values are not undefined', () => {
+    expect(pickDefined({ a: 1, b: undefined, c: 3 } as { a?: number; b?: number; c?: number }, ['a', 'b', 'c']))
+      .toEqual({ a: 1, c: 3 })
+  })
+
+  it('preserves the literal `false` value for boolean opts', () => {
+    expect(pickDefined({ depluralize: false, x: undefined } as { depluralize?: boolean; x?: number }, ['depluralize', 'x']))
+      .toEqual({ depluralize: false })
+  })
+
+  it('preserves the literal `false` for `string | false` opts (e.g. arrayItemNaming)', () => {
+    type Opts = { arrayItemNaming?: string | false }
+    const result = pickDefined<Opts, keyof Opts>({ arrayItemNaming: false }, ['arrayItemNaming'])
+    expect(result).toEqual({ arrayItemNaming: false })
+    expect('arrayItemNaming' in result).toBe(true)
+  })
+
+  it('omits keys not in the keys list even if they are defined on src', () => {
+    expect(pickDefined({ a: 1, b: 2 } as { a?: number; b?: number }, ['a']))
+      .toEqual({ a: 1 })
+  })
+
+  it('returns an empty object when all keys are undefined', () => {
+    expect(pickDefined({ a: undefined, b: undefined } as { a?: number; b?: number }, ['a', 'b']))
+      .toEqual({})
+  })
+
+  it('returns an empty object when keys is empty', () => {
+    expect(pickDefined({ a: 1 }, [] as never[])).toEqual({})
+  })
+})

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

@@ -0,0 +1,45 @@
+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')
+}
+
+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')
+}
+
+/**
+ * Returns a new object containing only the keys of `src` whose values are
+ * not `undefined`. Useful for building option objects where unset keys must
+ * be ABSENT (not `undefined`-valued), so they don't shadow downstream
+ * defaults — e.g., when forwarding into `KotlinEmitOptions`.
+ *
+ * @example
+ *   pickDefined({ a: 1, b: undefined, c: false }, ['a', 'b', 'c'])
+ *   // → { a: 1, c: false }
+ */
+export function pickDefined<T extends object, K extends keyof T>(
+  src: T,
+  keys: readonly K[],
+): Partial<Pick<T, K>> {
+  const out: Partial<Pick<T, K>> = {}
+  for (const key of keys) {
+    const value = src[key]
+    if (value !== undefined) {
+      out[key] = value
+    }
+  }
+  return out
+}

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/test-helpers/golden.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it, afterEach } from 'vitest'
+import { mkdtempSync, writeFileSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { assertGoldenOrUpdate } from './golden.js'
+
+let tmpDir: string | undefined
+
+afterEach(() => {
+  if (tmpDir != null) {
+    rmSync(tmpDir, { recursive: true, force: true })
+    tmpDir = undefined
+  }
+})
+
+function makeTmp(): string {
+  tmpDir = mkdtempSync(join(tmpdir(), 'tsp-golden-'))
+  return tmpDir
+}
+
+describe('assertGoldenOrUpdate', () => {
+  it('asserts byte-equality against golden when produced matches (with hash splice)', async () => {
+    const dir = makeTmp()
+    const goldenPath = join(dir, 'expected.txt')
+    writeFileSync(goldenPath, 'hello\n// Source hash: <PLACEHOLDER>\nworld\n', 'utf-8')
+
+    const produced = 'hello\n// Source hash: abc123def456\nworld\n'
+    await expect(assertGoldenOrUpdate(produced, goldenPath)).resolves.toBeUndefined()
+  })
+
+  it('throws when produced does not match golden', async () => {
+    const dir = makeTmp()
+    const goldenPath = join(dir, 'expected.txt')
+    writeFileSync(goldenPath, 'expected content\n', 'utf-8')
+
+    const produced = 'different content\n'
+    await expect(assertGoldenOrUpdate(produced, goldenPath)).rejects.toThrow()
+  })
+
+  it('writes a portable golden when UPDATE_GOLDENS=1', async () => {
+    const original = process.env.UPDATE_GOLDENS
+    process.env.UPDATE_GOLDENS = '1'
+    try {
+      const dir = makeTmp()
+      const goldenPath = join(dir, 'expected.txt')
+      const produced = 'hello\n// Source hash: deadbeef1234\nworld\n'
+      await assertGoldenOrUpdate(produced, goldenPath)
+      const written = readFileSync(goldenPath, 'utf-8')
+      expect(written).toBe('hello\n// Source hash: <PLACEHOLDER>\nworld\n')
+    } finally {
+      if (original === undefined) delete process.env.UPDATE_GOLDENS
+      else process.env.UPDATE_GOLDENS = original
+    }
+  })
+
+  it('handles produced output without a source-hash line', async () => {
+    const dir = makeTmp()
+    const goldenPath = join(dir, 'expected.txt')
+    writeFileSync(goldenPath, 'plain content\n', 'utf-8')
+
+    // No source hash; splice is a no-op on both sides.
+    await expect(assertGoldenOrUpdate('plain content\n', goldenPath)).resolves.toBeUndefined()
+  })
+
+  it('regenerate mode handles produced output without a source-hash line', async () => {
+    const original = process.env.UPDATE_GOLDENS
+    process.env.UPDATE_GOLDENS = '1'
+    try {
+      const dir = makeTmp()
+      const goldenPath = join(dir, 'expected.txt')
+      const produced = 'no hash line here\n'
+      await assertGoldenOrUpdate(produced, goldenPath)
+      const written = readFileSync(goldenPath, 'utf-8')
+      expect(written).toBe('no hash line here\n')
+    } finally {
+      if (original === undefined) delete process.env.UPDATE_GOLDENS
+      else process.env.UPDATE_GOLDENS = original
+    }
+  })
+})

package/src/codegen/test-helpers/golden.ts

@@ -0,0 +1,34 @@
+import { expect } from 'vitest'
+import { readFile, writeFile } from 'node:fs/promises'
+
+/**
+ * Compares produced source against a golden file, with optional regeneration.
+ *
+ * - Normal mode: reads `goldenPath`, splices the produced source-hash line into
+ *   the golden's `<PLACEHOLDER>` slot, and asserts byte-equality.
+ * - Regen mode (`UPDATE_GOLDENS=1`): replaces the produced source-hash line with
+ *   `<PLACEHOLDER>` and writes the result to `goldenPath`. The next normal run
+ *   will assert against the new golden.
+ *
+ * The source-hash placeholder lets us check generated content into source
+ * control without coupling the golden to a specific envelope hash. Codegen
+ * outputs that don't include a `// Source hash:` line work too — the
+ * splice/replace is a no-op when no match is found.
+ */
+export async function assertGoldenOrUpdate(produced: string, goldenPath: string): Promise<void> {
+  if (process.env.UPDATE_GOLDENS === '1') {
+    const goldenContent = produced.replace(
+      /^\/\/ Source hash: [a-f0-9]+$/m,
+      '// Source hash: <PLACEHOLDER>',
+    )
+    await writeFile(goldenPath, goldenContent, 'utf-8')
+    // eslint-disable-next-line no-console
+    console.log(`[golden-test] Wrote golden: ${goldenPath}`)
+    return
+  }
+
+  const goldenTemplate = await readFile(goldenPath, 'utf8')
+  const sourceHashLine = produced.split('\n').find((l) => l.startsWith('// Source hash:')) ?? ''
+  const goldenWithHash = goldenTemplate.replace('// Source hash: <PLACEHOLDER>', sourceHashLine)
+  expect(produced).toBe(goldenWithHash)
+}