ts-procedures 6.0.2 → 6.2.0

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

@@ -0,0 +1,80 @@
+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 { createStubSwiftEmitter, type SwiftEmitResult } from './ajsc-adapter.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+const ok = (code: string, rootTypeName: string, imports: string[] = []): SwiftEmitResult => ({
+  code,
+  rootTypeName,
+  extractedTypeNames: [],
+  imports,
+})
+
+describe('swift 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.swift')
+    const envelope = JSON.parse(await readFile(envelopePath, 'utf8'))
+
+    // Hand-authored slot outputs in the v7.2 nested-struct 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 structs (one per route that has one). This is correct: the
+    // integration test pins our file-assembly logic, not real ajsc per-route
+    // output. The swiftc E2E test exercises real ajsc against the same fixture
+    // and would surface any incompatibility.
+    const emitter = createStubSwiftEmitter({
+      // GetUser
+      PathParams: ok(
+        'public struct PathParams: Codable {\n    public let id: String\n}',
+        'PathParams',
+      ),
+      Response: ok(
+        'public struct Response: Codable {\n    public let id: String\n    public let name: String\n    public let createdAt: Date\n    public let address: Address\n\n    enum CodingKeys: String, CodingKey {\n        case id, name\n        case createdAt = "created-at"\n        case address\n    }\n\n    public struct Address: Codable {\n        public let street: String\n        public let city: String\n    }\n}',
+        'Response',
+        ['Foundation'],
+      ),
+      NotFound: ok(
+        'public struct NotFound: Codable {\n    public let name: String\n    public let message: String\n}',
+        'NotFound',
+      ),
+
+      // CreateUser
+      Body: ok(
+        'public enum Body: Codable {\n    case guest(GuestBody)\n    case registered(RegisteredBody)\n\n    public struct GuestBody: Codable {\n        public let kind: String\n        public let displayName: String\n    }\n\n    public struct RegisteredBody: Codable {\n        public let kind: String\n        public let email: String\n        public let name: String\n    }\n}',
+        'Body',
+      ),
+      ValidationError: ok(
+        'public struct ValidationError: Codable {\n    public let name: String\n    public let message: String\n    public let field: String?\n}',
+        'ValidationError',
+      ),
+
+      // ListUsers
+      Query: ok(
+        'public struct Query: Codable {\n    public let status: Status?\n    public let limit: Int64?\n\n    public enum Status: String, Codable {\n        case active\n        case inactive\n    }\n}',
+        'Query',
+      ),
+    })
+
+    const files = await runPipeline({
+      envelope,
+      outDir: 'out',
+      dryRun: true,
+      target: 'swift',
+      swiftEmitter: emitter,
+    })
+
+    expect(files).toHaveLength(1)
+    expect(files[0]!.path).toBe(join('out', 'Users.swift'))
+
+    await assertGoldenOrUpdate(files[0]!.code, goldenPath)
+  })
+})

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

@@ -0,0 +1,74 @@
+/**
+ * Swift-target pipeline runner. Invoked by the dispatcher in
+ * `src/codegen/pipeline.ts` when `target === 'swift'`. Emits one `.swift`
+ * file per scope via `emitSwiftScope` 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 { SwiftEmitter } from './ajsc-adapter.js'
+import { emitSwiftScope } from './emit-scope-swift.js'
+
+export interface SwiftRunInput extends TargetRunInput {
+  swiftSerializer?: 'codable' | 'none'
+  swiftAccessLevel?: 'public' | 'internal'
+  unsupportedUnions?: 'throw' | 'fallback'
+  /** Injected for tests; production wiring resolves a real ajsc emitter. */
+  swiftEmitter?: SwiftEmitter
+}
+
+/**
+ * `--array-item-naming`, `--depluralize`, `--uncountable-words` are reused
+ * across targets. The CLI parks them on `options.ajsc`; copy the relevant
+ * subset onto the scope opts here.
+ */
+const AJSC_PASSTHROUGH_KEYS = ['arrayItemNaming', 'depluralize', 'uncountableWords'] as const
+
+export async function runSwiftPipeline(input: SwiftRunInput): Promise<GeneratedFile[]> {
+  const { envelope, outDir, hash, groups, dryRun = false, cleanOutDir = false } = input
+
+  // Runtime guard for non-CLI callers (direct API consumers + tests).
+  // The CLI resolves the emitter before calling runPipeline, so end users
+  // never hit this throw. Swift currently has no required CLI flags.
+  if (input.swiftEmitter == null) {
+    throw new Error(
+      '[ts-procedures-codegen] target=swift requires a swiftEmitter (CLI resolves via resolveProductionSwiftEmitter)'
+    )
+  }
+
+  const errorSchemas = buildErrorSchemasMap(envelope.errors)
+  const ajscPassthrough = input.ajsc ?? {}
+
+  const files: GeneratedFile[] = []
+  const allSkipped: string[] = []
+  for (const group of groups) {
+    const emitted = emitSwiftScope(
+      group,
+      {
+        sourceHash: hash,
+        ...(input.swiftSerializer !== undefined ? { serializer: input.swiftSerializer } : {}),
+        ...(input.swiftAccessLevel !== undefined ? { accessLevel: input.swiftAccessLevel } : {}),
+        ...(input.unsupportedUnions !== undefined ? { unsupportedUnions: input.unsupportedUnions } : {}),
+        ...pickDefined(ajscPassthrough, AJSC_PASSTHROUGH_KEYS),
+      },
+      input.swiftEmitter,
+      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'} (swift target): ${allSkipped.join(', ')}`,
+    )
+  }
+
+  await writeGeneratedFiles(files, outDir, { dryRun, cleanOutDir })
+
+  return files
+}

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

@@ -0,0 +1,117 @@
+/**
+ * TypeScript-target pipeline runner. Invoked by the dispatcher in
+ * `src/codegen/pipeline.ts` when `target` is `'ts'` (or unset). Emits the
+ * scope `.ts` files, `_errors.ts`, `index.ts`, and — under self-contained
+ * mode — `_types.ts` + `_client.ts`, then 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 type { TargetRunInput } from '../_shared/target-run.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'
+
+export type TsRunInput = TargetRunInput
+
+export async function runTsPipeline(input: TsRunInput): Promise<GeneratedFile[]> {
+  const {
+    envelope,
+    outDir,
+    hash,
+    groups,
+    serviceName,
+    ajsc: ajscOpts,
+    clientImportPath,
+    dryRun = false,
+    namespaceTypes = false,
+    selfContained = false,
+    cleanOutDir = false,
+  } = input
+
+  const hashComment = `// Source hash: ${hash}`
+
+  // 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 groups) {
+      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 groups) {
+    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 })
+  }
+
+  // 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(groups, {
+    clientImportPath,
+    clientRuntimeImportPath,
+    hasErrors,
+    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 })
+  }
+
+  await writeGeneratedFiles(files, outDir, { dryRun, cleanOutDir })
+
+  return files
+}

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