ts-procedures 8.6.0 → 9.0.0

package/build/codegen/emit-scope.js

@@ -1,846 +1,17 @@
-import { jsonSchemaToTypeString, jsonSchemaToTypeBody, jsonSchemaToTypeBodyWithRefs, jsonSchemaToExtractedTypes, renameExtractedTypes, extractedDeclName, } from './emit-types.js';
-import { substituteModelRefs } from './model-refs.js';
-import { CODEGEN_HEADER } from './constants.js';
-import { toPascalCase } from './naming.js';
-// ---------------------------------------------------------------------------
-// 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) {
-    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) {
-    const props = schema.properties;
-    if (props == null || typeof props !== 'object')
-        return false;
-    const keys = Object.keys(props);
-    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) {
-    if (!isSseEnvelope(schema))
-        return schema;
-    const props = schema.properties;
-    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, version) {
-    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, prefix) {
-    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, ctx) {
-    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) {
-    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, ctx) {
-    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 {
-    context;
-    seenStrings = new Set();
-    seenNames = new Map();
-    constructor(context) {
-        this.context = context;
-    }
-    /** Returns the indented line to emit, or `null` for an exact duplicate. */
-    accept(decl, indentPrefix) {
-        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);
-    }
-}
-/**
- * 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, types, ctx, extraReserved) {
-    const declarations = [];
-    const refs = {};
-    if (ctx.namespaceTypes) {
-        const nsLines = [];
-        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(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, ctx) {
-    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) => `${toPascalCase(ctx.serviceName)}Errors.${k}`
-        : (k) => `_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, routePascal, errorUnion, namespaceTypes) {
-    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) {
-    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, ctx) {
-    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, nsName, // e.g. 'Req' or 'Response'
-types, ctx, taken) {
-    const refs = {};
-    const nsLines = [];
-    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, headersRef) {
-    if (bodyRef && headersRef) {
-        return `{ body: ${bodyRef}; headers: ${headersRef} }`;
-    }
-    if (bodyRef)
-        return bodyRef;
-    if (headersRef)
-        return `{ headers: ${headersRef} }`;
-    return 'void';
-}
-async function emitApiRoute(route, ctx) {
-    const pascal = toPascalCase(route.name);
-    const req = route.jsonSchema.req ?? {};
-    const res = route.jsonSchema.res ?? {};
-    // Request channels
-    const reqChannelKeys = ['pathParams', 'query', 'body', 'headers'];
-    const reqTypes = [];
-    const presentChannels = [];
-    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 = [
-        { 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 = [];
-    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(['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 = [];
-        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;
-        let headersRef;
-        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, ctx) {
-    const pascal = toPascalCase(route.name);
-    const req = route.jsonSchema.req ?? {};
-    const res = route.jsonSchema.res ?? {};
-    // Request channels
-    const reqChannelKeys = ['pathParams', 'query', 'body', 'headers'];
-    const reqTypes = [];
-    const presentChannels = [];
-    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 = [];
-    let paramsTypeName = 'void';
-    let yieldTypeName = 'unknown';
-    let returnTypeName = 'void';
-    const taken = new Set(['Req', 'Response', 'Yield', 'ReturnType']);
-    if (ctx.namespaceTypes) {
-        const nsLines = [];
-        // 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 = [{ 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 = [
-            { 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, ctx) {
-    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, options) {
-    const { ajsc: ajscOpts, clientImportPath = 'ts-procedures/client', namespaceTypes = false, serviceName = 'Api', errorKeys, idToModelName, } = options ?? {};
-    const pascal = toPascalCase(group.camelCase);
-    const referencedModels = new Set();
-    const ctx = {
-        ajsc: ajscOpts,
-        namespaceTypes,
-        scopePascal: pascal,
-        serviceName,
-        errorKeys,
-        idToModelName,
-        referencedModels,
-    };
-    const allTypeDeclarations = [];
-    const callables = [];
-    let hasStream = false;
-    let scopeHasErrors = false;
-    for (const route of group.routes) {
-        let chunks;
-        const kind = route.kind ?? inferRouteKind(route);
-        try {
-            if (kind === 'rpc') {
-                chunks = await emitRpcRoute(route, ctx);
-            }
-            else if (kind === 'api') {
-                chunks = await emitApiRoute(route, ctx);
-            }
-            else if (kind === 'stream') {
-                chunks = await emitStreamRoute(route, ctx);
-            }
-            else if (kind === 'http-stream') {
-                chunks = await emitHttpStreamRoute(route, 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;
-    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 } from './emit/scope-file.js';
 //# sourceMappingURL=emit-scope.js.map