ts-procedures 8.6.0 → 9.1.0

package/src/codegen/emit-scope.ts

@@ -1,1049 +1,16 @@
-import type { ScopeGroup } from './group-routes.js'
-import type {
-  RPCHttpRouteDoc,
-  APIHttpRouteDoc,
-  StreamHttpRouteDoc,
-  HttpStreamRouteDoc,
-} from '../implementations/types.js'
-import {
-  jsonSchemaToTypeString,
-  jsonSchemaToTypeBody,
-  jsonSchemaToTypeBodyWithRefs,
-  jsonSchemaToExtractedTypes,
-  renameExtractedTypes,
-  extractedDeclName,
-  type AjscOptions,
-  type ExtractedTypeOutput,
-} from './emit-types.js'
-import { substituteModelRefs } from './model-refs.js'
-import { CODEGEN_HEADER } from './constants.js'
-import { toPascalCase } from './naming.js'
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export interface EmitScopeOptions {
-  ajsc?: AjscOptions
-  clientImportPath?: string
-  namespaceTypes?: boolean
-  /** Service identifier used to namespace generated error types (defaults to 'Api'). */
-  serviceName?: string
-  /**
-   * Error keys present in the generated `_errors.ts`. Routes may list keys
-   * that aren't emitted (e.g. no schema); those are filtered out at emit time
-   * so generated code never references undefined types.
-   */
-  errorKeys?: Set<string>
-  /**
-   * Maps a model `$id` to its shared model type name (built by the run module
-   * from ALL models — generated and imported). When present and non-empty,
-   * `$id` subschemas are rewritten to `x-named-type` nodes before ajsc; ajsc
-   * emits bare references and reports them via `referencedNamedTypes`, which
-   * drives the `import type { … } from './_models'` line. Absent/empty →
-   * identical inlining behaviour (the conversion wrappers short-circuit so
-   * output is byte-identical for envelopes without models).
-   */
-  idToModelName?: Map<string, string>
-}
-
-interface RouteChunks {
-  typeDeclarations: string[]
-  callable: string
-  hasStream: boolean
-  /** True when this route emitted an `Errors` type (drives the `_errors` import at the top of the scope file). */
-  hasErrors: boolean
-}
-
-interface EmitRouteContext {
-  ajsc?: AjscOptions
-  namespaceTypes: boolean
-  scopePascal: string
-  serviceName: string
-  errorKeys?: Set<string>
-  /** `$id` → shared model type name; drives the substitute wrappers. */
-  idToModelName?: Map<string, string>
-  /**
-   * Accumulates the model names ajsc reported as `referencedNamedTypes` across
-   * every route in the scope. Drives the `import type { … } from './_models'`
-   * line assembled in `emitScopeFile`.
-   */
-  referencedModels: Set<string>
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
 /**
- * Infers the route kind when the `kind` discriminant is missing.
- * This provides backward compatibility with servers running older ts-procedures
- * versions that don't set `kind` on route docs.
- */
-function inferRouteKind(route: Record<string, unknown>): 'rpc' | 'api' | 'stream' | 'http-stream' {
-  if ('streamMode' in route && 'fullPath' in route) return 'http-stream'
-  if ('streamMode' in route) return 'stream'
-  if ('fullPath' in route) return 'api'
-  return 'rpc'
-}
-
-/**
- * Checks whether a JSON schema looks like an SSE envelope.
- * SSE envelopes have properties: data, event, id (and optionally retry).
- */
-function isSseEnvelope(schema: Record<string, unknown>): boolean {
-  const props = schema.properties
-  if (props == null || typeof props !== 'object') return false
-  const keys = Object.keys(props as Record<string, unknown>)
-  return keys.includes('data') && keys.includes('event') && keys.includes('id')
-}
-
-/**
- * Unwraps an SSE envelope schema to return the inner `data` property schema.
- * If not an SSE envelope, returns the schema unchanged.
- */
-function unwrapSseEnvelope(
-  schema: Record<string, unknown>
-): Record<string, unknown> {
-  if (!isSseEnvelope(schema)) return schema
-  const props = schema.properties as Record<string, Record<string, unknown>>
-  const dataSchema = props['data']
-  return dataSchema ?? schema
-}
-
-/**
- * Returns the PascalCase display name for a route, appending `V{version}`
- * when version > 1. Version 1 produces no suffix for backward compatibility.
- */
-function versionedPascal(name: string, version: number | undefined): string {
-  const pascal = toPascalCase(name)
-  if (version != null && version > 1) return `${pascal}V${version}`
-  return pascal
-}
-
-// ---------------------------------------------------------------------------
-// Shared type formatting helpers
-// ---------------------------------------------------------------------------
-
-/** Indent each line of a multi-line string by a given prefix. */
-function indent(text: string, prefix: string): string {
-  return text.split('\n').map((line) => (line ? prefix + line : line)).join('\n')
-}
-
-// ---------------------------------------------------------------------------
-// Shared-model conversion wrappers (ajsc x-named-type)
-// ---------------------------------------------------------------------------
-
-/**
- * Drop-in replacement for `jsonSchemaToExtractedTypes` that, when shared models
- * are in play, rewrites every `$id` subschema into an `x-named-type` node before
- * ajsc. ajsc emits each as a bare verbatim reference and reports it via
- * `referencedNamedTypes`; this wrapper folds those names into
- * `ctx.referencedModels` so `emitScopeFile` can build the `_models` import.
- *
- * Short-circuits to the exact original call when no models are configured, so
- * output is byte-identical for envelopes without `$id` models.
- */
-async function convertExtracted(
-  schema: Record<string, unknown>,
-  ctx: EmitRouteContext,
-): Promise<ExtractedTypeOutput | undefined> {
-  if (ctx.idToModelName == null || ctx.idToModelName.size === 0) {
-    return jsonSchemaToExtractedTypes(schema, ctx.ajsc)
-  }
-  const { schema: sub } = substituteModelRefs(schema, ctx.idToModelName)
-  const result = await jsonSchemaToExtractedTypes(sub, ctx.ajsc)
-  if (result != null) {
-    assertNoModelNameCollision(result)
-    for (const name of result.referencedNamedTypes) ctx.referencedModels.add(name)
-  }
-  return result
-}
-
-/**
- * Guards ajsc's documented `x-named-type` collision caveat. If a shared-model
- * name (referenced via `x-named-type`) also matches the name ajsc derives for a
- * sibling *structural* sub-type, ajsc silently MERGES them — the model reference
- * resolves to the unrelated structural type. The merge happens inside ajsc's own
- * pass, so it can't be disentangled afterward (a post-hoc rename would rewrite
- * the model reference too, producing a silently-wrong type). Instead we detect
- * the collision — a name present in BOTH `referencedNamedTypes` AND
- * `extractedTypeNames` (ajsc's own documented collision signal) — and fail fast
- * with an actionable message. The throw is wrapped with the route's name/scope
- * by `emitScopeFile`.
- */
-function assertNoModelNameCollision(result: ExtractedTypeOutput): void {
-  if (result.referencedNamedTypes.length === 0 || result.extractedTypeNames.length === 0) return
-  const extracted = new Set(result.extractedTypeNames)
-  const collisions = result.referencedNamedTypes.filter((name) => extracted.has(name))
-  if (collisions.length === 0) return
-  const names = collisions.map((n) => `'${n}'`).join(', ')
-  throw new Error(
-    `shared model ${names} collides with a generated type of the same name derived ` +
-      `from a property in this route's schema — ajsc would silently merge them. Rename ` +
-      `the colliding property, or change the model's $id/title so the generated names differ`,
-  )
-}
-
-/**
- * Drop-in replacement for `jsonSchemaToTypeBody` mirroring {@link convertExtracted}
- * for the bare-body (flat / merged-alias) conversion path.
- */
-async function convertBody(
-  schema: Record<string, unknown>,
-  ctx: EmitRouteContext,
-): Promise<string | undefined> {
-  if (ctx.idToModelName == null || ctx.idToModelName.size === 0) {
-    return jsonSchemaToTypeBody(schema, ctx.ajsc)
-  }
-  const { schema: sub } = substituteModelRefs(schema, ctx.idToModelName)
-  const result = await jsonSchemaToTypeBodyWithRefs(sub, ctx.ajsc)
-  if (result == null) return undefined
-  for (const name of result.referencedNamedTypes) ctx.referencedModels.add(name)
-  return result.body
-}
-
-/**
- * Tracks extracted declarations emitted into a single namespace, guarding
- * against duplicate identifiers (defense-in-depth on top of the rename pass).
- *
- * - Exact-string duplicates (the same sub-type extracted from two schemas) are
- *   silently skipped.
- * - A same-name-but-different-body declaration is a genuine collision the
- *   rename pass failed to resolve; emitting it would produce an opaque
- *   `TS2300: Duplicate identifier` in the consumer's build. We fail fast at
- *   codegen with a message that names the offending identifier instead.
- *
- * Returns the indented declaration line to push, or `null` when it should be
- * skipped (exact duplicate).
- */
-class DeclarationCollector {
-  private readonly seenStrings = new Set<string>()
-  private readonly seenNames = new Map<string, string>()
-
-  constructor(private readonly context: string) {}
-
-  /** Returns the indented line to emit, or `null` for an exact duplicate. */
-  accept(decl: string, indentPrefix: string): string | null {
-    if (this.seenStrings.has(decl)) return null
-    const name = extractedDeclName(decl)
-    if (name != null) {
-      if (this.seenNames.has(name)) {
-        throw new Error(
-          `[ts-procedures-codegen] duplicate identifier '${name}' while emitting ${this.context}. ` +
-            `An extracted sub-type collided with another of the same name and could not be renamed. ` +
-            `This is a codegen bug — please report it with the offending schema.`,
-        )
-      }
-      this.seenNames.set(name, decl)
-    }
-    this.seenStrings.add(decl)
-    return indent(decl, indentPrefix)
-  }
-}
-
-interface NamedType {
-  /** Short name for namespace mode (e.g., 'Params', 'Response'). */
-  shortName: string
-  /** Schema to convert, or undefined if not present. */
-  schema: Record<string, unknown> | undefined
-}
-
-interface FormattedTypes {
-  /** Type declarations to add to the file. */
-  declarations: string[]
-  /** Map of shortName → qualified type reference (for callables). */
-  refs: Record<string, string>
-}
-
-/**
- * Converts multiple schemas into type declarations and type references.
- * In flat mode: `export type ${routePascal}${shortName} = <body>`
- * In namespace mode: extracted sub-types + named types inside `export namespace ${routePascal} { ... }`
- *
- * `extraReserved` lets the caller pre-reserve identifier names that the route
- * will inject AFTER formatTypes returns (e.g. emitApiRoute's structured
- * `Params`). Without this, an ajsc-extracted sub-type could shadow the
- * injected one and produce duplicate `export type Params` declarations.
- */
-async function formatTypes(
-  routePascal: string,
-  types: NamedType[],
-  ctx: EmitRouteContext,
-  extraReserved?: ReadonlySet<string>,
-): Promise<FormattedTypes> {
-  const declarations: string[] = []
-  const refs: Record<string, string> = {}
-
-  if (ctx.namespaceTypes) {
-    const nsLines: string[] = []
-    const collector = new DeclarationCollector(`namespace ${routePascal}`)
-
-    // Pre-reserve every name the route will declare itself (each shortName +
-    // any caller-supplied extras). Extracted sub-types whose names land in
-    // this set get renamed (e.g. `Params` → `Params_`) by renameExtractedTypes,
-    // and the body string is patched in lockstep so the reference still
-    // resolves. The set is mutated as we go, so a sub-type renamed in schema A
-    // is also reserved against schema B.
-    const taken = new Set<string>(extraReserved ?? [])
-    for (const t of types) {
-      if (t.schema != null) taken.add(t.shortName)
-    }
-
-    for (const { shortName, schema } of types) {
-      if (schema == null) continue
-
-      const rawResult = await convertExtracted(schema, ctx)
-      if (rawResult == null) continue
-
-      const result = renameExtractedTypes(rawResult, taken)
-
-      // Collect extracted sub-types (dedupe exact dups; throw on real collisions)
-      for (const decl of result.declarations) {
-        const line = collector.accept(decl, '    ')
-        if (line != null) nsLines.push(line)
-      }
-
-      nsLines.push(`    export type ${shortName} = ${result.body}`)
-      refs[shortName] = `${ctx.scopePascal}.${routePascal}.${shortName}`
-    }
-
-    if (nsLines.length > 0) {
-      declarations.push(`  export namespace ${routePascal} {\n${nsLines.join('\n')}\n  }`)
-    }
-  } else {
-    for (const { shortName, schema } of types) {
-      if (schema == null) continue
-
-      const flatName = `${routePascal}${shortName}`
-      const body = await convertBody(schema, ctx)
-      if (body == null) continue
-
-      declarations.push(`export type ${flatName} = ${body}`)
-      refs[shortName] = flatName
-    }
-  }
-
-  return { declarations, refs }
-}
-
-// ---------------------------------------------------------------------------
-// Route-level Errors union injection
-// ---------------------------------------------------------------------------
-
-/**
- * Builds the body of an `Errors` type union from the route's declared error
- * keys. Filters to keys actually emitted in `_errors.ts` so generated code
- * never references undefined types.
- *
- * In namespace mode the union uses qualified names (`ApiErrors.UseCaseError`);
- * in flat mode it uses the bundled wildcard import alias (`_errors.UseCaseError`).
- * Returns `null` when no keys remain.
- */
-function buildErrorUnion(
-  routeErrors: string[] | undefined,
-  ctx: EmitRouteContext
-): string | null {
-  if (!routeErrors || routeErrors.length === 0) return null
-  const available = ctx.errorKeys
-  const filtered = available ? routeErrors.filter((k) => available.has(k)) : routeErrors
-  if (filtered.length === 0) return null
-  const qualify = ctx.namespaceTypes
-    ? (k: string) => `${toPascalCase(ctx.serviceName)}Errors.${k}`
-    : (k: string) => `_errors.${k}`
-  return filtered.map(qualify).join(' | ')
-}
-
-/**
- * Injects `export type Errors = ...` into an existing route namespace block
- * (namespace mode) or appends a flat `export type ${pascal}Errors = ...` in
- * flat mode. Mutates the `declarations` array in place and returns whether an
- * injection happened.
- */
-function injectRouteErrors(
-  declarations: string[],
-  routePascal: string,
-  errorUnion: string | null,
-  namespaceTypes: boolean
-): boolean {
-  if (!errorUnion) return false
-  if (namespaceTypes) {
-    const lastIdx = declarations.length - 1
-    if (lastIdx < 0) return false
-    const lastDecl = declarations[lastIdx]!
-    const closingIdx = lastDecl.lastIndexOf('  }')
-    if (closingIdx === -1) return false
-    declarations[lastIdx] =
-      lastDecl.slice(0, closingIdx) +
-      `    export type Errors = ${errorUnion}\n` +
-      lastDecl.slice(closingIdx)
-    return true
-  }
-  declarations.push(`export type ${routePascal}Errors = ${errorUnion}`)
-  return true
-}
-
-// ---------------------------------------------------------------------------
-// Route emitters
-// ---------------------------------------------------------------------------
-
-/**
- * Builds the multi-line JSDoc comment for a route callable. Surfaces the
- * second `options` argument (the per-call AbortSignal/timeout seam — DX #8) and,
- * for routes that declare typed errors, points at the route's `Errors` type and
- * how to narrow it on the throwing path (DX #10). Indented for placement inside
- * the bind-object (4 spaces).
- */
-function buildCallableJsDoc(opts: {
-  methodLabel: string
-  path: string
-  errorsRef: string | null
-}): string {
-  const lines = [
-    `    /**`,
-    `     * ${opts.methodLabel} ${opts.path}`,
-    `     *`,
-    `     * @param options Optional per-call {@link ProcedureCallOptions} —`,
-    `     *   \`signal\` (cancel on dispose), \`timeout\`, \`headers\`, \`basePath\`.`,
-  ]
-  if (opts.errorsRef) {
-    lines.push(
-      `     * @throws Declared typed errors: {@link ${opts.errorsRef}}. Narrow with`,
-      `     *   \`instanceof\` on the throwing path, or call \`.safe()\` for a \`Result\`.`,
-    )
-  }
-  lines.push(`     */`)
-  return lines.join('\n')
-}
-
-async function emitRpcRoute(route: RPCHttpRouteDoc, ctx: EmitRouteContext): Promise<RouteChunks> {
-  const pascal = versionedPascal(route.name, route.version)
-
-  const { declarations, refs } = await formatTypes(pascal, [
-    { shortName: 'Params', schema: route.jsonSchema.body },
-    { shortName: 'Response', schema: route.jsonSchema.response },
-  ], ctx)
-
-  const paramsTypeName = refs['Params'] ?? 'void'
-  const responseTypeName = refs['Response'] ?? 'unknown'
-  const scopeStr = Array.isArray(route.scope) ? route.scope.join('-') : route.scope
-
-  const errorUnion = buildErrorUnion(route.errors, ctx)
-  const hasErrors = errorUnion !== null
-  const errorsRef = ctx.namespaceTypes
-    ? `${ctx.scopePascal}.${pascal}.Errors`
-    : `${pascal}Errors`
-  const helperCall = hasErrors
-    ? `client.bindCallableTyped<${paramsTypeName}, ${responseTypeName}, ${errorsRef}>`
-    : `client.bindCallable<${paramsTypeName}, ${responseTypeName}>`
-
-  const callable = [
-    buildCallableJsDoc({
-      methodLabel: route.method.toUpperCase(),
-      path: route.path,
-      errorsRef: hasErrors ? errorsRef : null,
-    }),
-    `    ${pascal}: ${helperCall}({`,
-    `      name: '${pascal}',`,
-    `      scope: '${scopeStr}',`,
-    `      path: '${route.path}',`,
-    `      method: '${route.method}',`,
-    `      kind: 'rpc',`,
-    `    }),`,
-  ].join('\n')
-
-  const hasErrorsInjected = injectRouteErrors(declarations, pascal, errorUnion, ctx.namespaceTypes)
-
-  return { typeDeclarations: declarations, callable, hasStream: false, hasErrors: hasErrorsInjected }
-}
-
-/**
- * Formats a group of named types into a nested sub-namespace block (for namespace mode).
- * Returns an array of lines to be inserted into the parent namespace, and a map of
- * shortName → qualified type reference for use in callables.
- *
- * In flat mode, returns declarations like `export type ${prefix}${shortName} = ...`
- * and refs like `${prefix}${shortName}`.
- */
-async function formatSubNamespace(
-  routePascal: string,
-  nsName: string,           // e.g. 'Req' or 'Response'
-  types: NamedType[],
-  ctx: EmitRouteContext,
-  taken: Set<string>,
-): Promise<{ nsBlock: string | null; refs: Record<string, string> }> {
-  const refs: Record<string, string> = {}
-  const nsLines: string[] = []
-  const collector = new DeclarationCollector(`namespace ${routePascal}.${nsName}`)
-
-  // Pre-reserve short names to prevent sub-type extraction collision
-  for (const t of types) {
-    if (t.schema != null) taken.add(t.shortName)
-  }
-
-  for (const { shortName, schema } of types) {
-    if (schema == null) continue
-
-    if (ctx.namespaceTypes) {
-      const rawResult = await convertExtracted(schema, ctx)
-      if (rawResult == null) continue
-
-      const result = renameExtractedTypes(rawResult, taken)
-
-      for (const decl of result.declarations) {
-        const line = collector.accept(decl, '      ')
-        if (line != null) nsLines.push(line)
-      }
-
-      nsLines.push(`      export type ${shortName} = ${result.body}`)
-      refs[shortName] = `${ctx.scopePascal}.${routePascal}.${nsName}.${shortName}`
-    } else {
-      const flatName = `${routePascal}${nsName}${shortName}`
-      const body = await convertBody(schema, ctx)
-      if (body == null) continue
-      refs[shortName] = flatName
-    }
-  }
-
-  if (ctx.namespaceTypes) {
-    if (nsLines.length === 0) return { nsBlock: null, refs }
-    const nsBlock = `    export namespace ${nsName} {\n${nsLines.join('\n')}\n    }`
-    return { nsBlock, refs }
-  }
-
-  return { nsBlock: null, refs }
-}
-
-/**
- * Builds the conditional return type string for an API or http-stream callable.
- *
- * - Both body + headers → `{ body: <Body>; headers: <Headers> }`
- * - Only body           → `<Body>`
- * - Only headers        → `{ headers: <Headers> }`
- * - Neither             → `void`
- */
-function buildApiReturnType(
-  bodyRef: string | undefined,
-  headersRef: string | undefined,
-): string {
-  if (bodyRef && headersRef) {
-    return `{ body: ${bodyRef}; headers: ${headersRef} }`
-  }
-  if (bodyRef) return bodyRef
-  if (headersRef) return `{ headers: ${headersRef} }`
-  return 'void'
-}
-
-async function emitApiRoute(route: APIHttpRouteDoc, ctx: EmitRouteContext): Promise<RouteChunks> {
-  const pascal = toPascalCase(route.name)
-  const req = route.jsonSchema.req ?? {}
-  const res = route.jsonSchema.res ?? {}
-
-  // Request channels
-  const reqChannelKeys = ['pathParams', 'query', 'body', 'headers'] as const
-  const reqTypes: NamedType[] = []
-  const presentChannels: string[] = []
-
-  for (const channel of reqChannelKeys) {
-    const schema = req[channel]
-    if (schema != null) {
-      reqTypes.push({ shortName: toPascalCase(channel), schema })
-      presentChannels.push(channel)
-    }
-  }
-
-  // Response slots
-  const resTypes: NamedType[] = [
-    { shortName: 'Body', schema: res.body },
-    { shortName: 'Headers', schema: res.headers },
-  ]
-
-  const scopeStr = route.scope ?? 'default'
-  const errorUnion = buildErrorUnion(route.errors, ctx)
-  const hasErrors = errorUnion !== null
-  const errorsRef = ctx.namespaceTypes
-    ? `${ctx.scopePascal}.${pascal}.Errors`
-    : `${pascal}Errors`
-
-  const declarations: string[] = []
-  let paramsTypeName = 'void'
-  let returnTypeName = 'void'
-
-  // Track reserved names across all sub-namespaces. Model names are reserved
-  // so an ajsc-extracted sub-type can't silently merge with a referenced model.
-  const taken = new Set<string>(['Req', 'Response'])
-
-  if (ctx.namespaceTypes) {
-    // Namespace mode: emit nested Req {} and Response {} namespaces inside route namespace.
-    // Also emit merged type aliases `export type Req = { ... }` and `export type Response = ...`
-    // so they can be used as type arguments to bindCallable (TS requires a TYPE, not a namespace).
-    const nsLines: string[] = []
-
-    const { nsBlock: reqBlock, refs: reqRefs } = await formatSubNamespace(
-      pascal, 'Req', reqTypes, ctx, taken
-    )
-    if (reqBlock) {
-      nsLines.push(reqBlock)
-      // Merged type alias for Req so it can be used as a generic type arg
-      const reqFields = presentChannels
-        .map((ch) => `${ch}: Req.${toPascalCase(ch)}`)
-        .join('; ')
-      nsLines.push(`    export type Req = { ${reqFields} }`)
-    }
-
-    const { nsBlock: resBlock, refs: resRefs } = await formatSubNamespace(
-      pascal, 'Response', resTypes, ctx, taken
-    )
-    if (resBlock) {
-      nsLines.push(resBlock)
-      // No merged Response type alias needed: we reference Response.Body / Response.Headers
-      // directly in the return type string, which are namespace-qualified paths (valid).
-    }
-
-    // Emit Errors type last (injected by injectRouteErrors below)
-    // Build the route namespace block
-    if (nsLines.length > 0) {
-      declarations.push(`  export namespace ${pascal} {\n${nsLines.join('\n\n')}\n  }`)
-    }
-
-    // Params type: use the merged Req type alias
-    if (presentChannels.length > 0) {
-      paramsTypeName = `${ctx.scopePascal}.${pascal}.Req`
-    }
-
-    // Return type
-    const bodyRef = resRefs['Body']
-    const headersRef = resRefs['Headers']
-    returnTypeName = buildApiReturnType(bodyRef, headersRef)
-  } else {
-    // Flat mode: emit individual types prefixed with route + sub-namespace name
-    for (const { shortName, schema } of reqTypes) {
-      if (schema == null) continue
-      const flatName = `${pascal}Req${shortName}`
-      const body = await convertBody(schema, ctx)
-      if (body == null) continue
-      declarations.push(`export type ${flatName} = ${body}`)
-    }
-
-    // Flat mode: compose structured Req type
-    if (presentChannels.length > 0) {
-      const structureFields = presentChannels
-        .map((ch) => `${ch}: ${pascal}Req${toPascalCase(ch)}`)
-        .join('; ')
-      declarations.push(`export type ${pascal}Req = { ${structureFields} }`)
-      paramsTypeName = `${pascal}Req`
-    }
-
-    // Flat mode: emit response types
-    let bodyRef: string | undefined
-    let headersRef: string | undefined
-
-    for (const { shortName, schema } of resTypes) {
-      if (schema == null) continue
-      const flatName = `${pascal}Response${shortName}`
-      const body = await convertBody(schema, ctx)
-      if (body == null) continue
-      declarations.push(`export type ${flatName} = ${body}`)
-      if (shortName === 'Body') bodyRef = flatName
-      if (shortName === 'Headers') headersRef = flatName
-    }
-
-    returnTypeName = buildApiReturnType(bodyRef, headersRef)
-
-    // Flat mode errors
-    if (errorUnion) {
-      declarations.push(`export type ${pascal}Errors = ${errorUnion}`)
-    }
-  }
-
-  const responseHeadersDeclared = res.headers != null
-  const helperCall = hasErrors
-    ? `client.bindCallableTyped<${paramsTypeName}, ${returnTypeName}, ${errorsRef}>`
-    : `client.bindCallable<${paramsTypeName}, ${returnTypeName}>`
-
-  const descriptorLines = [
-    `      name: '${route.name}',`,
-    `      scope: '${scopeStr}',`,
-    `      path: '${route.fullPath}',`,
-    `      method: '${route.method}',`,
-    `      kind: 'api',`,
-    ...(responseHeadersDeclared ? [`      responseHeadersDeclared: true,`] : []),
-  ]
-
-  const callable = [
-    buildCallableJsDoc({
-      methodLabel: route.method.toUpperCase(),
-      path: route.fullPath,
-      errorsRef: hasErrors ? errorsRef : null,
-    }),
-    `    ${route.name}: ${helperCall}({`,
-    ...descriptorLines,
-    `    }),`,
-  ].join('\n')
-
-  const hasErrorsInjected = ctx.namespaceTypes
-    ? injectRouteErrors(declarations, pascal, errorUnion, ctx.namespaceTypes)
-    : errorUnion !== null  // flat mode already emitted errors above
-
-  return { typeDeclarations: declarations, callable, hasStream: false, hasErrors: hasErrorsInjected }
-}
-
-async function emitHttpStreamRoute(route: HttpStreamRouteDoc, ctx: EmitRouteContext): Promise<RouteChunks> {
-  const pascal = toPascalCase(route.name)
-  const req = route.jsonSchema.req ?? {}
-  const res = route.jsonSchema.res ?? {}
-
-  // Request channels
-  const reqChannelKeys = ['pathParams', 'query', 'body', 'headers'] as const
-  const reqTypes: NamedType[] = []
-  const presentChannels: string[] = []
-
-  for (const channel of reqChannelKeys) {
-    const schema = req[channel]
-    if (schema != null) {
-      reqTypes.push({ shortName: toPascalCase(channel), schema })
-      presentChannels.push(channel)
-    }
-  }
-
-  // Yield + ReturnType
-  const yieldSchema = route.jsonSchema.yield
-  const returnSchema = route.jsonSchema.returnType
-  const resHeadersSchema = res.headers
-
-  const scopeStr = route.scope ?? 'default'
-  const declarations: string[] = []
-  let paramsTypeName = 'void'
-  let yieldTypeName = 'unknown'
-  let returnTypeName = 'void'
-
-  const taken = new Set<string>(['Req', 'Response', 'Yield', 'ReturnType'])
-
-  if (ctx.namespaceTypes) {
-    const nsLines: string[] = []
-
-    // Req sub-namespace
-    const { nsBlock: reqBlock, refs: reqRefs } = await formatSubNamespace(
-      pascal, 'Req', reqTypes, ctx, taken
-    )
-    if (reqBlock) {
-      nsLines.push(reqBlock)
-      // Merged type alias so Req can be used as a generic type arg (same pattern as emitApiRoute)
-      const reqFields = presentChannels
-        .map((ch) => `${ch}: Req.${toPascalCase(ch)}`)
-        .join('; ')
-      nsLines.push(`    export type Req = { ${reqFields} }`)
-    }
-
-    // Response sub-namespace (headers only for http-stream)
-    const resTypes: NamedType[] = [{ shortName: 'Headers', schema: resHeadersSchema }]
-    const { nsBlock: resBlock } = await formatSubNamespace(
-      pascal, 'Response', resTypes, ctx, taken
-    )
-    if (resBlock) nsLines.push(resBlock)
-
-    // Yield and ReturnType directly in the route namespace
-    const directTypes: NamedType[] = [
-      { shortName: 'Yield', schema: yieldSchema },
-      { shortName: 'ReturnType', schema: returnSchema },
-    ]
-    const collector = new DeclarationCollector(`namespace ${pascal}`)
-    for (const { shortName, schema } of directTypes) {
-      if (schema == null) continue
-      const rawResult = await convertExtracted(schema, ctx)
-      if (rawResult == null) continue
-      const result = renameExtractedTypes(rawResult, taken)
-      for (const decl of result.declarations) {
-        const line = collector.accept(decl, '    ')
-        if (line != null) nsLines.push(line)
-      }
-      nsLines.push(`    export type ${shortName} = ${result.body}`)
-    }
-
-    if (nsLines.length > 0) {
-      declarations.push(`  export namespace ${pascal} {\n${nsLines.join('\n')}\n  }`)
-    }
-
-    if (presentChannels.length > 0) {
-      paramsTypeName = `${ctx.scopePascal}.${pascal}.Req`
-    }
-
-    if (yieldSchema != null) yieldTypeName = `${ctx.scopePascal}.${pascal}.Yield`
-    if (returnSchema != null) returnTypeName = `${ctx.scopePascal}.${pascal}.ReturnType`
-  } else {
-    // Flat mode
-    for (const { shortName, schema } of reqTypes) {
-      if (schema == null) continue
-      const flatName = `${pascal}Req${shortName}`
-      const body = await convertBody(schema, ctx)
-      if (body == null) continue
-      declarations.push(`export type ${flatName} = ${body}`)
-    }
-
-    if (presentChannels.length > 0) {
-      const structureFields = presentChannels
-        .map((ch) => `${ch}: ${pascal}Req${toPascalCase(ch)}`)
-        .join('; ')
-      declarations.push(`export type ${pascal}Req = { ${structureFields} }`)
-      paramsTypeName = `${pascal}Req`
-    }
-
-    if (resHeadersSchema != null) {
-      const body = await convertBody(resHeadersSchema, ctx)
-      if (body != null) declarations.push(`export type ${pascal}ResponseHeaders = ${body}`)
-    }
-
-    if (yieldSchema != null) {
-      const body = await convertBody(yieldSchema, ctx)
-      if (body != null) {
-        declarations.push(`export type ${pascal}Yield = ${body}`)
-        yieldTypeName = `${pascal}Yield`
-      }
-    }
-
-    if (returnSchema != null) {
-      const body = await convertBody(returnSchema, ctx)
-      if (body != null) {
-        declarations.push(`export type ${pascal}ReturnType = ${body}`)
-        returnTypeName = `${pascal}ReturnType`
-      }
-    }
-  }
-
-  const callable = [
-    buildCallableJsDoc({
-      methodLabel: route.method.toUpperCase(),
-      path: route.fullPath,
-      errorsRef: null,
-    }),
-    `    ${route.name}(req: ${paramsTypeName}, options?: ProcedureCallOptions): TypedStream<${yieldTypeName}, ${returnTypeName}> {`,
-    `      return client.stream<${yieldTypeName}, ${returnTypeName}>({`,
-    `        name: '${route.name}',`,
-    `        scope: '${scopeStr}',`,
-    `        path: '${route.fullPath}',`,
-    `        method: '${route.method}',`,
-    `        kind: 'http-stream',`,
-    `        streamMode: '${route.streamMode}',`,
-    `        params: req,`,
-    `      }, options)`,
-    `    },`,
-  ].join('\n')
-
-  const hasErrors = injectRouteErrors(
-    declarations,
-    pascal,
-    buildErrorUnion(route.errors, ctx),
-    ctx.namespaceTypes
-  )
-
-  return { typeDeclarations: declarations, callable, hasStream: true, hasErrors }
-}
-
-async function emitStreamRoute(route: StreamHttpRouteDoc, ctx: EmitRouteContext): Promise<RouteChunks> {
-  const pascal = versionedPascal(route.name, route.version)
-
-  // Unwrap SSE envelope from yieldType
-  let yieldSchema = route.jsonSchema.yieldType
-  if (yieldSchema != null && route.streamMode === 'sse' && isSseEnvelope(yieldSchema)) {
-    yieldSchema = unwrapSseEnvelope(yieldSchema)
-  }
-
-  const { declarations, refs } = await formatTypes(pascal, [
-    { shortName: 'Params', schema: route.jsonSchema.params },
-    { shortName: 'Yield', schema: yieldSchema },
-    { shortName: 'Return', schema: route.jsonSchema.returnType },
-  ], ctx)
-
-  const paramsTypeName = refs['Params'] ?? 'void'
-  const yieldTypeName = refs['Yield'] ?? 'unknown'
-  const returnTypeName = refs['Return'] ?? 'void'
-  const scopeStr = Array.isArray(route.scope) ? route.scope.join('-') : route.scope
-
-  const callable = [
-    buildCallableJsDoc({
-      methodLabel: route.methods.map((m) => m.toUpperCase()).join('|'),
-      path: route.path,
-      errorsRef: null,
-    }),
-    `    ${pascal}(params: ${paramsTypeName}, options?: ProcedureCallOptions): TypedStream<${yieldTypeName}, ${returnTypeName}> {`,
-    `      return client.stream<${yieldTypeName}, ${returnTypeName}>({`,
-    `        name: '${pascal}',`,
-    `        scope: '${scopeStr}',`,
-    `        path: '${route.path}',`,
-    `        method: '${route.methods[0] ?? 'get'}',`,
-    `        kind: 'stream',`,
-    `        streamMode: '${route.streamMode}',`,
-    `        params,`,
-    `      }, options)`,
-    `    },`,
-  ].join('\n')
-
-  const hasErrors = injectRouteErrors(
-    declarations,
-    pascal,
-    buildErrorUnion(route.errors, ctx),
-    ctx.namespaceTypes
-  )
-
-  return { typeDeclarations: declarations, callable, hasStream: true, hasErrors }
-}
-
-// ---------------------------------------------------------------------------
-// emitScopeFile
-// ---------------------------------------------------------------------------
-
-/**
- * Generates a complete TypeScript scope file for a ScopeGroup.
- *
- * When `namespaceTypes` is true, types are wrapped in nested TypeScript namespaces
- * and ajsc runs with `inlineTypes: false` so formatting options (enumStyle, depluralize,
- * jsdoc, etc.) produce extracted sub-types inside each namespace.
- */
-export async function emitScopeFile(
-  group: ScopeGroup,
-  options?: EmitScopeOptions,
-): Promise<string> {
-  const {
-    ajsc: ajscOpts,
-    clientImportPath = 'ts-procedures/client',
-    namespaceTypes = false,
-    serviceName = 'Api',
-    errorKeys,
-    idToModelName,
-  } = options ?? {}
-
-  const pascal = toPascalCase(group.camelCase)
-  const referencedModels = new Set<string>()
-  const ctx: EmitRouteContext = {
-    ajsc: ajscOpts,
-    namespaceTypes,
-    scopePascal: pascal,
-    serviceName,
-    errorKeys,
-    idToModelName,
-    referencedModels,
-  }
-
-  const allTypeDeclarations: string[] = []
-  const callables: string[] = []
-  let hasStream = false
-  let scopeHasErrors = false
-
-  for (const route of group.routes) {
-    let chunks: RouteChunks
-    const kind = route.kind ?? inferRouteKind(route as Record<string, unknown>)
-
-    try {
-      if (kind === 'rpc') {
-        chunks = await emitRpcRoute(route as RPCHttpRouteDoc, ctx)
-      } else if (kind === 'api') {
-        chunks = await emitApiRoute(route as APIHttpRouteDoc, ctx)
-      } else if (kind === 'stream') {
-        chunks = await emitStreamRoute(route as StreamHttpRouteDoc, ctx)
-      } else if (kind === 'http-stream') {
-        chunks = await emitHttpStreamRoute(route as HttpStreamRouteDoc, ctx)
-      } else {
-        throw new Error(`Unknown route kind "${kind}"`)
-      }
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err)
-      throw new Error(
-        `[ts-procedures-codegen] Failed to emit route "${route.name}" (kind: ${kind}, scope: ${group.scopeKey}): ${msg}`
-      )
-    }
-
-    allTypeDeclarations.push(...chunks.typeDeclarations)
-    callables.push(chunks.callable)
-    if (chunks.hasStream) hasStream = true
-    if (chunks.hasErrors) scopeHasErrors = true
-  }
-
-  // Build client import line — Result/ResultNoTyped are no longer referenced
-  // directly in scope files; the bindCallable helpers infer them from ClientInstance.
-  const clientImports = hasStream
-    ? `import type { ClientInstance, ProcedureCallOptions, TypedStream } from '${clientImportPath}'`
-    : `import type { ClientInstance, ProcedureCallOptions } from '${clientImportPath}'`
-
-  // Build _errors import line when at least one route emits an Errors union.
-  // Namespace mode uses the qualified `${Service}Errors` namespace; flat mode
-  // pulls classes in via a wildcard alias (`_errors.UseCaseError`).
-  let errorsImport = ''
-  if (scopeHasErrors) {
-    if (namespaceTypes) {
-      errorsImport = `import type { ${toPascalCase(serviceName)}Errors } from './_errors'`
-    } else {
-      errorsImport = `import type * as _errors from './_errors'`
-    }
-  }
-
-  const callablesBlock = callables.join('\n\n')
-
-  // Assemble the type + callable section for this scope. ajsc already emitted
-  // bare model references (via `x-named-type`); `convertExtracted` / `convertBody`
-  // folded the reported names into `ctx.referencedModels`, which drives the
-  // `_models` import below. No post-pass over the body is needed.
-  let body: string
-  if (namespaceTypes) {
-    // Namespace mode: types AND `bindScope` live inside `export namespace ${pascal}`.
-    // Putting the function inside the namespace makes the merged symbol
-    // value+type, which lets `index.ts` use `export import ${pascal} = …`
-    // under `verbatimModuleSyntax: true`. (A type-only namespace would trip
-    // TS1269/TS1288.) Consumers call `${Pascal}.bindScope(client)`; the
-    // generated `index.ts` factory wires this internally.
-    const callableLines = indent(callablesBlock, '  ')
-    const namespaceMembers = [
-      ...(allTypeDeclarations.length > 0 ? [allTypeDeclarations.join('\n\n')] : []),
-      [
-        '  /** Binds every callable in this scope to a configured client. */',
-        '  export function bindScope(client: ClientInstance) {',
-        '    return {',
-        callableLines,
-        '    }',
-        '  }',
-      ].join('\n'),
-    ].join('\n\n')
-
-    body = [
-      `export namespace ${pascal} {`,
-      namespaceMembers,
-      '}',
-      '',
-    ].join('\n')
-  } else {
-    // Flat mode: types at module level, `bind${pascal}Scope` standalone.
-    const typesBlock = allTypeDeclarations.length > 0
-      ? allTypeDeclarations.join('\n') + '\n'
-      : ''
-
-    body = [
-      '// ── Types ────────────────────────────────────────',
-      '',
-      typesBlock,
-      '// ── Callables ────────────────────────────────────',
-      '',
-      `export function bind${pascal}Scope(client: ClientInstance) {`,
-      '  return {',
-      callablesBlock,
-      '  }',
-      '}',
-      '',
-    ].join('\n')
-  }
-
-  // Build the shared-models import line when any route referenced a `$id` model.
-  // Matches the `_errors` import convention exactly: `'./_models'` with no `.js`.
-  let modelsImport = ''
-  if (referencedModels.size > 0) {
-    const names = [...referencedModels].sort().join(', ')
-    modelsImport = `import type { ${names} } from './_models'`
-  }
-
-  const importsBlock = [clientImports, errorsImport, modelsImport].filter(Boolean).join('\n')
-
-  return [
-    CODEGEN_HEADER,
-    importsBlock,
-    '',
-    body,
-  ].join('\n')
-}
+ * Thin re-export barrel for the TS scope emitter, which now lives in
+ * `./emit/`. Kept so existing imports of `./emit-scope.js` keep working.
+ *
+ * Module layout:
+ * - `emit/scope-file.ts`        — `emitScopeFile` orchestration + assembly
+ * - `emit/rpc-route.ts`         — `kind: 'rpc'` emitter
+ * - `emit/api-route.ts`         — `kind: 'api'` emitter
+ * - `emit/stream-route.ts`      — `kind: 'stream'` emitter
+ * - `emit/http-stream-route.ts` — `kind: 'http-stream'` emitter
+ * - `emit/format-types.ts`      — schema→type conversion + formatTypes helpers
+ * - `emit/declarations.ts`      — `indent` + `DeclarationCollector`
+ * - `emit/route-shared.ts`      — errors-union / JSDoc / naming helpers
+ * - `emit/context.ts`           — shared `EmitRouteContext` / `RouteChunks`
+ */
+export { emitScopeFile, type EmitScopeOptions } from './emit/scope-file.js'