@contractkit/plugin-typescript 0.31.1 → 0.32.0

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@contractkit/plugin-typescript",
-  "version": "0.31.1",
+  "version": "0.32.0",
   "description": "ContractKit built-in plugin: TypeScript codegen (SDK clients, Koa routers, Zod schemas, plain types)",
+  "license": "MIT",
   "author": {
     "name": "Marooned Software",
     "url": "https://github.com/MaroonedSoftware/contractkit"
@@ -26,7 +27,7 @@
     ".": "./dist/index.js"
   },
   "dependencies": {
-    "@contractkit/core": "0.26.0"
+    "@contractkit/core": "0.27.0"
   },
   "devDependencies": {
     "@repo/config-eslint": "0.3.1",

package/src/codegen-operation.ts

@@ -132,6 +132,18 @@ export interface OpCodegenOptions {
      * from the generated router entirely.
      */
     includeInternal?: boolean;
+    /**
+     * Re-parse the service result through its declared response schema before writing `ctx.body`,
+     * and write the parsed value. Requires the type file to hold Zod schemas (`server.zod`) —
+     * plain interfaces are types, with no runtime schema value to validate against. Default false.
+     */
+    validateResponses?: boolean;
+    /**
+     * Set of model names whose schema applies a `format(...)` key transform, directly or through a
+     * referenced model. Response bodies touching one are left unvalidated: the service returns the
+     * post-transform shape, which the schema itself cannot re-parse.
+     */
+    modelsWithTransform?: Set<string>;
 }
 
 /**
@@ -212,13 +224,20 @@ export function generateOp(root: OpRootNode, options: OpCodegenOptions = {}): st
         body.push(`import { ${koaImports.join(', ')} } from '@maroonedsoftware/koa';`);
     }
 
-    for (const svc of services) {
+    // Services and model names come from the AST, which over-approximates two ways: a model with an
+    // Input/Output variant contributes its base name even when only the variant is ever annotated,
+    // and `collectServices`/`collectTypes` walk every operation including the `internal` ones
+    // `includeInternal: false` drops. Filtering through `uses` — the same gate every symbol above
+    // goes through — keeps the import list to what the handlers actually reference, so generated
+    // code does not trip `noUnusedLocals` in the consuming project.
+    for (const svc of services.filter(uses)) {
         const modulePath = root.services?.[svc] ?? root.meta[svc] ?? deriveModulePath(svc, options.servicePathTemplate);
         body.push(`import { ${svc} } from '${modulePath}';`);
     }
 
-    if (types.length > 0) {
-        body.push(...generateTypeImports(types, root.file, options));
+    const usedTypes = types.filter(uses);
+    if (usedTypes.length > 0) {
+        body.push(...generateTypeImports(usedTypes, root.file, options));
     }
 
     // luxon is needed for date/time/datetime (DateTime), duration (Duration) and interval (Interval);
@@ -383,9 +402,12 @@ function generateSingleStatusResult(
     const hasRespHeaders = respHeaders.length > 0;
     const headersAnnotation = hasRespHeaders ? renderHeadersAnnotation(respHeaders, options.modelsWithOutput) : '';
 
+    let bodySchema: string | undefined;
+
     if (bodies.length === 1) {
         const { annotation, prelude } = formatTypeAnnotation(bodies[0]!.bodyType, options.modelsWithOutput);
         if (prelude) lines.push(`    ${prelude}`);
+        bodySchema = responseBodySchema(bodies[0]!.bodyType, options, prelude ? 'resultType' : undefined);
         lines.push(`    const service = ctx.container.get(${className});`);
         if (hasRespHeaders) {
             lines.push(`    const result: { body: ${annotation}; headers: ${headersAnnotation} } = ${call};`);
@@ -393,7 +415,9 @@ function generateSingleStatusResult(
             lines.push(`    const result: ${annotation} = ${call};`);
         }
     } else if (bodies.length > 1) {
-        const { members, preludes } = renderResponseMembers(resp!, options, { includeStatus: false, varPrefix: 'result' });
+        const rendered = renderResponseMembers(resp!, options, { includeStatus: false, varPrefix: 'result' });
+        const { members, preludes } = rendered;
+        bodySchema = rendered.bodySchema;
         for (const prelude of preludes) lines.push(`    ${prelude}`);
         lines.push(`    const service = ctx.container.get(${className});`);
         lines.push(`    const result: ${members.join(' | ')} = ${call};`);
@@ -414,10 +438,10 @@ function generateSingleStatusResult(
 
     if (bodies.length === 1) {
         lines.push(`    ctx.type = '${bodies[0]!.contentType}';`);
-        lines.push(`    ctx.body = ${hasRespHeaders ? 'result.body' : 'result'};`);
+        lines.push(`    ctx.body = ${responseBodyExpr(hasRespHeaders ? 'result.body' : 'result', bodySchema)};`);
     } else if (bodies.length > 1) {
         lines.push(`    ctx.type = result.contentType;`);
-        lines.push(`    ctx.body = result.body;`);
+        lines.push(`    ctx.body = ${responseBodyExpr('result.body', bodySchema)};`);
     }
 
     return lines;
@@ -433,10 +457,13 @@ function generateMultiStatusResult(emitted: OpResponseNode[], className: string,
     const members: string[] = [];
     const preludes: string[] = [];
 
+    const bodySchemas = new Map<number, string | undefined>();
+
     for (const resp of emitted) {
         const rendered = renderResponseMembers(resp, options, { includeStatus: true, varPrefix: `result${resp.statusCode}` });
         members.push(...rendered.members);
         preludes.push(...rendered.preludes);
+        bodySchemas.set(resp.statusCode, rendered.bodySchema);
     }
 
     for (const prelude of preludes) lines.push(`    ${prelude}`);
@@ -452,7 +479,7 @@ function generateMultiStatusResult(emitted: OpResponseNode[], className: string,
         lines.push(...headerSetLines(resp.headers ?? [], '            '));
         if (resp.bodies.length > 0) {
             lines.push(`            ctx.type = result.contentType;`);
-            lines.push(`            ctx.body = result.body;`);
+            lines.push(`            ctx.body = ${responseBodyExpr('result.body', bodySchemas.get(resp.statusCode))};`);
         }
         lines.push(`            break;`);
     }
@@ -473,7 +500,7 @@ function renderResponseMembers(
     resp: OpResponseNode,
     options: OpCodegenOptions,
     opts: { includeStatus: boolean; varPrefix: string },
-): { members: string[]; preludes: string[] } {
+): { members: string[]; preludes: string[]; bodySchema?: string } {
     const bodies = resp.bodies;
     const headers = resp.headers ?? [];
     const leading = opts.includeStatus ? [`status: ${resp.statusCode}`] : [];
@@ -488,10 +515,18 @@ function renderResponseMembers(
     if (uniform) {
         const { annotation, prelude } = formatTypeAnnotation(bodies[0]!.bodyType, options.modelsWithOutput, `${opts.varPrefix}Type`);
         if (prelude) preludes.push(prelude);
+        const bodySchema = responseBodySchema(bodies[0]!.bodyType, options, prelude ? `${opts.varPrefix}Type` : undefined);
         const contentType = bodies.map(b => `'${b.contentType}'`).join(' | ');
-        return { members: [`{ ${[...leading, `contentType: ${contentType}`, `body: ${annotation}`, ...trailing].join('; ')} }`], preludes };
+        return {
+            members: [`{ ${[...leading, `contentType: ${contentType}`, `body: ${annotation}`, ...trailing].join('; ')} }`],
+            preludes,
+            bodySchema,
+        };
     }
 
+    // One member per mime: `contentType` and `body` stay correlated, so validating would need a
+    // second switch on `result.contentType` nested inside the status switch. Left unvalidated —
+    // note the absent `bodySchema` in the return below.
     const members = bodies.map((b, i) => {
         const { annotation, prelude } = formatTypeAnnotation(b.bodyType, options.modelsWithOutput, `${opts.varPrefix}Type${i}`);
         if (prelude) preludes.push(prelude);
@@ -660,6 +695,71 @@ function formatTypeAnnotation(bodyType: ContractTypeNode, modelsWithOutput?: Set
     };
 }
 
+/**
+ * Whether a response body can be soundly re-parsed through the schema `renderType` emits for it.
+ *
+ * False for anything transitively touching a model with a `format(...)` key transform — the service
+ * returns the post-transform value while the schema expects the pre-transform one — and for an
+ * intersection outside `renderIntersection`'s `.extend()` fast path, where `.and()` of two strict
+ * objects rejects every value because each side sees the other's keys as unrecognized.
+ */
+function isRevalidatable(type: ContractTypeNode, modelsWithOutput?: Set<string>, modelsWithTransform?: Set<string>): boolean {
+    const rec = (t: ContractTypeNode): boolean => isRevalidatable(t, modelsWithOutput, modelsWithTransform);
+    switch (type.kind) {
+        case 'ref':
+            return !modelsWithOutput?.has(type.name) && !modelsWithTransform?.has(type.name);
+        case 'array':
+            return rec(type.item);
+        case 'tuple':
+            return type.items.every(rec);
+        case 'record':
+            return rec(type.key) && rec(type.value);
+        case 'intersection': {
+            // Mirrors renderIntersection: a lone member renders as itself, `ref & (ref|object)*`
+            // renders as an `.extend()` chain, and anything else falls back to `.and()`.
+            const [first, ...rest] = type.members;
+            if (!first) return true;
+            if (rest.length === 0) return rec(first);
+            const usesExtendChain = first.kind === 'ref' && rest.every(m => m.kind === 'ref' || m.kind === 'inlineObject');
+            return usesExtendChain && type.members.every(rec);
+        }
+        case 'union':
+        case 'discriminatedUnion':
+            return type.members.every(rec);
+        case 'inlineObject':
+            return type.fields.every(f => rec(f.type));
+        case 'lazy':
+            return rec(type.inner);
+        default:
+            // scalar, enum, literal — identity or idempotent under re-parse
+            return true;
+    }
+}
+
+/**
+ * The runtime schema a handler validates a response body against, or `undefined` when the body
+ * cannot be soundly re-parsed and validation must be skipped.
+ *
+ * @param preludeVar The schema const {@link formatTypeAnnotation} already emitted for this body
+ *   (complex types only — `undefined` when it returned no prelude). Reusing it keeps a large object
+ *   literal from appearing twice in the same handler.
+ */
+function responseBodySchema(bodyType: ContractTypeNode, options: OpCodegenOptions, preludeVar: string | undefined): string | undefined {
+    if (!options.validateResponses) return undefined;
+    if (!isRevalidatable(bodyType, options.modelsWithOutput, options.modelsWithTransform)) return undefined;
+    return preludeVar ?? renderType(bodyType);
+}
+
+/**
+ * The `ctx.body = ...` right-hand side for a response body: the raw result expression, or a
+ * `parseAndValidate` of it. The `500` is deliberate — a service returning a shape its own contract
+ * rejects is a server fault, not a client one, and `@maroonedsoftware/zod` routes the field-level
+ * detail to `internalDetails` (log-only) rather than the response body at 5xx.
+ */
+function responseBodyExpr(value: string, schema: string | undefined): string {
+    return schema ? `await parseAndValidate(${value}, ${schema}, 500)` : value;
+}
+
 function generateParamValidation(
     source: ParamSource | undefined,
     ctxExpr: string,

package/src/index.ts

@@ -20,6 +20,7 @@ import {
     hashFingerprint,
     collectTransitiveModelRefs,
     collectTypeRefs,
+    computeModelsWithCaseTransform,
 } from '@contractkit/core';
 import {
     generateSdk,
@@ -73,6 +74,15 @@ export interface ServerConfig {
     servicePathTemplate?: string;
     /** Whether to emit handlers for `internal` operations. Default true. */
     includeInternal?: boolean;
+    /**
+     * When true, each handler re-parses the service result through its declared response schema
+     * before writing `ctx.body`, and writes the parsed value. Requires `zod: true` — without it
+     * `output.types` emits plain interfaces, which are types with no runtime schema value.
+     *
+     * A body that transitively references a model with `format(input=...)`/`format(output=...)`, and
+     * a status whose several mimes carry different body types, are left unvalidated. Default false.
+     */
+    validateResponses?: boolean;
 }
 
 /** TypeScript SDK client output: the client class, per-area operation clients, and their types. */
@@ -182,6 +192,15 @@ export function createTypescriptPlugin(config: TypescriptPluginConfig, rootDir:
     };
 }
 
+/** Reject config combinations that would generate code that cannot compile or cannot run. */
+function assertValidConfig(config: TypescriptPluginConfig): void {
+    if (config.server?.validateResponses && !config.server.zod) {
+        throw new Error(
+            'plugin-typescript: server.validateResponses requires server.zod: true — without it output.types emits plain TypeScript interfaces, which are types with no runtime schema value for the router to validate against.',
+        );
+    }
+}
+
 /**
  * Shared orchestration. Each sub-generator (server / sdk / zod / types) contributes a
  * set of cacheable units (per-file fingerprints) plus a set of always-regenerated global
@@ -196,6 +215,7 @@ async function runTypescriptCodegen(
     config: TypescriptPluginConfig,
     rootDir: string,
 ): Promise<void> {
+    assertValidConfig(config);
     const manifestPath = resolve(ctx.cacheDir, CACHE_MANIFEST_FILENAME);
     const prevManifest: IncrementalManifest = ctx.cacheEnabled ? readManifest(manifestPath) : emptyIncrementalManifest(TYPESCRIPT_CODEGEN_VERSION);
 
@@ -322,6 +342,10 @@ function collectServerOutput(
     const serverBase = resolve(rootDir, config.baseDir ?? '.');
     const modelsWithInput = inputs.modelsWithInput as Set<string>;
     const modelsWithOutput = inputs.modelsWithOutput as Set<string>;
+    // Not `modelsWithOutput`: that set seeds only from `format(output=...)`, because only that case
+    // needs an `Output` type alias. A `format(input=...)`-only model is just as untouchable for
+    // response validation — its schema's input casing is not what the service hands back.
+    const modelsWithTransform = computeModelsWithCaseTransform(inputs.contractRoots.flatMap(r => r.models));
     const modelMap = buildModelMap(inputs.contractRoots);
     const allFiles = [...inputs.contractRoots.map(r => r.file), ...inputs.opRoots.map(r => r.file)];
     const commonRoot = commonDir(allFiles, rootDir);
@@ -391,6 +415,10 @@ function collectServerOutput(
             modelsWithOutput: sliceModelSet(refs, new Set(), modelsWithOutput),
             servicePathTemplate: config.servicePathTemplate ?? null,
             includeInternal: config.includeInternal ?? true,
+            // Not covered by `sub`: adding `format(input=snake)` to a *different* .ck file changes
+            // this router's output with no change to `root` or the config.
+            modelsWithTransform: sliceModelSet(refs, new Set(), modelsWithTransform),
+            validateResponses: config.validateResponses ?? false,
             sub: subConfigKey,
         });
         units.push({
@@ -405,7 +433,9 @@ function collectServerOutput(
                         modelOutPaths: serverModelOutPaths,
                         modelsWithInput,
                         modelsWithOutput,
+                        modelsWithTransform,
                         includeInternal: config.includeInternal,
+                        validateResponses: config.validateResponses,
                     }),
                 },
             ],

package/tests/codegen-operation.test.ts

@@ -1,11 +1,13 @@
 import { describe, it, expect } from 'vitest';
 import { generateOp } from '../src/codegen-operation.js';
 import { SECURITY_NONE } from '@contractkit/core';
+import type { ContractTypeNode } from '@contractkit/core';
 import {
     scalarType,
     arrayType,
     refType,
     inlineObjectType,
+    intersectionType,
     field,
     opParam,
     opRequest,
@@ -61,6 +63,69 @@ describe('generateOperation', () => {
             expect(output).toContain('User');
         });
 
+        // Imports are collected from the AST, which over-approximates: a model with an Input/Output
+        // variant contributes its base name even when only the variant is annotated, and the
+        // collectors walk every operation including ones `includeInternal: false` drops. Each name
+        // is filtered back through the same `uses` gate the other symbols go through, because an
+        // import nothing references trips `noUnusedLocals` in the consuming project.
+        describe('every imported name is referenced by the generated body', () => {
+            /** Names in `import { … } from '…'` lines, minus everything the body actually mentions. */
+            const unusedImports = (output: string): string[] => {
+                const lines = output.split('\n');
+                const imported = lines
+                    .filter(l => l.startsWith('import '))
+                    .flatMap(l => l.match(/import\s+(?:type\s+)?\{([^}]*)\}/)?.[1]?.split(',') ?? [])
+                    .map(n => n.replace(/^\s*type\s+/, '').trim())
+                    .filter(Boolean);
+                const body = lines.filter(l => !l.startsWith('import ')).join('\n');
+                return imported.filter(name => !new RegExp(`\\b${name}\\b`).test(body));
+            };
+
+            it('drops the base model when only its Output variant is annotated', () => {
+                const root = opRoot([opRoute('/t', [opOperation('post', { responses: [opResponse(200, 'AuthToken', 'application/json')] })])]);
+                const output = generateOp(root, { modelsWithOutput: new Set(['AuthToken']) });
+                expect(output).toContain('AuthTokenOutput');
+                expect(output).not.toContain('import { AuthToken,');
+                expect(unusedImports(output)).toEqual([]);
+            });
+
+            it('drops the base model when only its Input variant is validated', () => {
+                const root = opRoot([opRoute('/u', [opOperation('post', { request: opRequest('CreateUser') })])]);
+                const output = generateOp(root, { modelsWithInput: new Set(['CreateUser']) });
+                expect(output).toContain('CreateUserInput');
+                expect(output).not.toContain('import { CreateUser,');
+                expect(unusedImports(output)).toEqual([]);
+            });
+
+            // `collectTypes`/`collectServices` walk every operation, so a router whose only op is
+            // dropped used to import a service and a model it had no handler to use them in.
+            it('imports nothing for a router whose only operation is an excluded internal one', () => {
+                const root = opRoot([
+                    opRoute('/i', [opOperation('get', { modifiers: ['internal'], responses: [opResponse(200, 'Secret', 'application/json')] })]),
+                ]);
+                const output = generateOp(root, { includeInternal: false });
+                expect(output).not.toContain('Secret');
+                expect(output).not.toContain('Service');
+                expect(unusedImports(output)).toEqual([]);
+            });
+
+            it('keeps the base model when the body does reference it', () => {
+                const root = opRoot([
+                    opRoute('/users', [opOperation('post', { request: opRequest('User'), responses: [opResponse(201, 'User', 'application/json')] })]),
+                ]);
+                const output = generateOp(root);
+                expect(output).toContain('User');
+                expect(unusedImports(output)).toEqual([]);
+            });
+
+            it('keeps the base model when validateResponses uses it as the runtime schema', () => {
+                const root = opRoot([opRoute('/users', [opOperation('get', { responses: [opResponse(200, 'User', 'application/json')] })])]);
+                const output = generateOp(root, { validateResponses: true });
+                expect(output).toContain('parseAndValidate(result, User, 500)');
+                expect(unusedImports(output)).toEqual([]);
+            });
+        });
+
         it('generates parseAndValidate import when route has params', () => {
             const root = opRoot([opRoute('/users/{id}', [opOperation('get')], [opParam('id', scalarType('uuid'))])]);
             const output = generateOp(root);
@@ -949,8 +1014,9 @@ describe('generateOperation', () => {
             });
 
             it('emits no _ZodBinary helper for a binary response body', () => {
-                // A response body is an annotation, not a schema — the handler never validates it,
-                // so declaring the helper would leave it unused and trip `noUnusedLocals`.
+                // Without `validateResponses` a response body is an annotation, not a schema — the
+                // handler never validates it, so declaring the helper would leave it unused and trip
+                // `noUnusedLocals`. With the flag on it is referenced, and the helper comes back.
                 const root = opRoot([
                     opRoute('/art', [
                         opOperation('get', {
@@ -1014,6 +1080,190 @@ describe('generateOperation', () => {
 
     // ─── Service inference ────────────────────────────────────────
 
+    // ─── Response body validation ──────────────────────────────────────
+
+    describe('response body validation (validateResponses)', () => {
+        const V = { validateResponses: true };
+        const respRoot = (bodyType: string | ContractTypeNode, contentType = 'application/json') =>
+            opRoot([opRoute('/users', [opOperation('get', { responses: [opResponse(200, bodyType, contentType)] })])]);
+
+        it('is off by default', () => {
+            expect(generateOp(respRoot('User'))).toContain('ctx.body = result;');
+        });
+
+        it('validates a ref response body against its schema', () => {
+            expect(generateOp(respRoot('User'), V)).toContain('ctx.body = await parseAndValidate(result, User, 500);');
+        });
+
+        // A service returning a shape its own contract rejects is a server fault, not a client one.
+        // 500 also diverts the field-level detail to `internalDetails`, keeping it off the wire.
+        it('throws 500, not the parseAndValidate default of 400', () => {
+            const output = generateOp(respRoot('User'), V);
+            expect(output).toContain('parseAndValidate(result, User, 500)');
+            expect(output).not.toContain('parseAndValidate(result, User)');
+        });
+
+        it('wraps an array response body in z.array', () => {
+            const root = respRoot(arrayType(refType('User')));
+            expect(generateOp(root, V)).toContain('ctx.body = await parseAndValidate(result, z.array(User), 500);');
+        });
+
+        it('validates a scalar response body against the rendered scalar schema', () => {
+            const root = respRoot(scalarType('string'), 'text/plain');
+            expect(generateOp(root, V)).toContain('ctx.body = await parseAndValidate(result, z.string(), 500);');
+        });
+
+        it('reuses the extracted schema const for a complex inline body', () => {
+            const root = respRoot(inlineObjectType([field('total', scalarType('int'))]));
+            const output = generateOp(root, V);
+            expect(output).toContain('const resultType = z.strictObject({');
+            expect(output).toContain('ctx.body = await parseAndValidate(result, resultType, 500);');
+        });
+
+        it('validates result.body when the status declares headers', () => {
+            const root = opRoot([
+                opRoute('/users', [
+                    opOperation('get', {
+                        responses: [
+                            {
+                                ...opResponse(200, 'User', 'application/json'),
+                                headers: [{ name: 'etag', optional: false, type: scalarType('string') }],
+                            },
+                        ],
+                    }),
+                ]),
+            ]);
+            const output = generateOp(root, V);
+            expect(output).toContain("ctx.set('etag', String(result.headers[\"etag\"]));");
+            expect(output).toContain('ctx.body = await parseAndValidate(result.body, User, 500);');
+        });
+
+        it('validates a single schema when several mimes share a body shape', () => {
+            const root = opRoot([
+                opRoute('/art', [
+                    opOperation('get', {
+                        responses: [
+                            opResponseMulti(200, [
+                                { contentType: 'image/png', bodyType: scalarType('binary') },
+                                { contentType: 'image/jpeg', bodyType: scalarType('binary') },
+                            ]),
+                        ],
+                    }),
+                ]),
+            ]);
+            const output = generateOp(root, V);
+            expect(output).toContain('ctx.body = await parseAndValidate(result.body, _ZodBinary, 500);');
+            // The helper and the zod import are gated on the generated text, so both follow.
+            expect(output).toContain('const _ZodBinary = z.custom<Buffer>');
+            expect(output).toContain("import { z } from 'zod';");
+        });
+
+        it('validates each status body in a multi-status switch', () => {
+            const root = opRoot([
+                opRoute('/art', [
+                    opOperation('get', {
+                        responses: [opResponse(200, 'Art', 'application/json'), opResponse(202, 'JobRef', 'application/json')],
+                    }),
+                ]),
+            ]);
+            const output = generateOp(root, V);
+            expect(output).toMatch(/case 200:[\s\S]*?ctx\.body = await parseAndValidate\(result\.body, Art, 500\);/);
+            expect(output).toMatch(/case 202:[\s\S]*?ctx\.body = await parseAndValidate\(result\.body, JobRef, 500\);/);
+        });
+
+        it('imports parseAndValidate for an operation with no request to validate', () => {
+            expect(generateOp(respRoot('User'), V)).toContain("import { parseAndValidate } from '@maroonedsoftware/zod';");
+        });
+
+        it('imports Interval once an interval body is validated', () => {
+            const output = generateOp(respRoot(scalarType('interval')), V);
+            expect(output).toContain("import { Interval } from 'luxon';");
+            expect(output).toContain('parseAndValidate(result, _ZodInterval, 500)');
+        });
+
+        it('writes no body for a bodyless status', () => {
+            const root = opRoot([opRoute('/users', [opOperation('delete', { responses: [opResponse(204)] })])]);
+            expect(generateOp(root, V)).not.toContain('ctx.body');
+        });
+
+        // ── Bodies the schema cannot soundly re-parse ──
+
+        it('leaves a body unvalidated when the model has an Output variant', () => {
+            const output = generateOp(respRoot('AuthToken'), { ...V, modelsWithOutput: new Set(['AuthToken']) });
+            expect(output).toContain('ctx.body = result;');
+            expect(output).not.toContain('parseAndValidate(result');
+        });
+
+        it('leaves an array unvalidated when the item model has an Output variant', () => {
+            const root = respRoot(arrayType(refType('AuthToken')));
+            const output = generateOp(root, { ...V, modelsWithOutput: new Set(['AuthToken']) });
+            expect(output).toContain('ctx.body = result;');
+            expect(output).not.toContain('parseAndValidate(result');
+        });
+
+        // `format(input=snake)` alone never reaches `modelsWithOutput` — that set seeds only from
+        // `outputCase` — but its schema is just as much a transform pipe, so re-parsing what the
+        // service returns would fail on every key. Regression guard for exactly that gap.
+        it('leaves a body unvalidated when the model has a format() key transform', () => {
+            const output = generateOp(respRoot('User'), { ...V, modelsWithTransform: new Set(['User']) });
+            expect(output).toContain('ctx.body = result;');
+            expect(output).not.toContain('parseAndValidate(result');
+        });
+
+        it('skips an inline object whose field references a transform model', () => {
+            const root = respRoot(inlineObjectType([field('token', refType('AuthToken'))]));
+            const output = generateOp(root, { ...V, modelsWithOutput: new Set(['AuthToken']) });
+            expect(output).not.toContain('parseAndValidate(result');
+        });
+
+        it('skips a multi-status case whose model has an Output variant, validating the others', () => {
+            const root = opRoot([
+                opRoute('/art', [
+                    opOperation('get', {
+                        responses: [opResponse(200, 'Art', 'application/json'), opResponse(202, 'AuthToken', 'application/json')],
+                    }),
+                ]),
+            ]);
+            const output = generateOp(root, { ...V, modelsWithOutput: new Set(['AuthToken']) });
+            expect(output).toMatch(/case 200:[\s\S]*?ctx\.body = await parseAndValidate\(result\.body, Art, 500\);/);
+            expect(output).toMatch(/case 202:[\s\S]*?ctx\.body = result\.body;/);
+        });
+
+        it('skips validation when the mimes carry different body types', () => {
+            const root = opRoot([
+                opRoute('/pets', [
+                    opOperation('get', {
+                        responses: [
+                            opResponseMulti(200, [
+                                { contentType: 'application/json', bodyType: 'Pet' },
+                                { contentType: 'text/csv', bodyType: scalarType('string') },
+                            ]),
+                        ],
+                    }),
+                ]),
+            ]);
+            const output = generateOp(root, V);
+            expect(output).toContain('ctx.body = result.body;');
+            expect(output).not.toContain('parseAndValidate(result.body');
+        });
+
+        // renderIntersection falls back to `.and()` outside its `.extend()` fast path, and `.and()`
+        // of two strict objects rejects every value — each side sees the other's keys as unknown.
+        it('skips an intersection that renders through .and()', () => {
+            const root = respRoot(
+                intersectionType(inlineObjectType([field('a', scalarType('string'))]), inlineObjectType([field('b', scalarType('string'))])),
+            );
+            expect(generateOp(root, V)).not.toContain('parseAndValidate(result');
+        });
+
+        it('validates an intersection that renders through .extend()', () => {
+            const root = respRoot(intersectionType(refType('Base'), inlineObjectType([field('extra', scalarType('string'))])));
+            const output = generateOp(root, V);
+            expect(output).toContain('const resultType = Base.extend({');
+            expect(output).toContain('ctx.body = await parseAndValidate(result, resultType, 500);');
+        });
+    });
+
     describe('service inference', () => {
         it('uses explicit service when declared', () => {
             const root = opRoot([opRoute('/users', [opOperation('post', { service: 'LedgerService.updateNesting' })])]);

package/tests/codegen-server.test.ts

@@ -216,6 +216,54 @@ describe('createTypescriptPlugin (server)', () => {
         });
     });
 
+    describe('validateResponses', () => {
+        const userRoot = () =>
+            opRoot(
+                [opRoute('/users', [opOperation('get', { responses: [opResponse(200, 'User', 'application/json')] })])],
+                '/project/contracts/users.ck',
+            );
+
+        it('throws when validateResponses is set without zod', async () => {
+            const plugin = createTypescriptPlugin({ server: { validateResponses: true } }, '/project');
+            await expect(plugin.generateTargets!(inputs(), makeCtx('/project'))).rejects.toThrow(/validateResponses requires server\.zod/);
+        });
+
+        it('accepts validateResponses alongside zod', async () => {
+            const plugin = createTypescriptPlugin({ server: { zod: true, validateResponses: true } }, '/project');
+            await expect(plugin.generateTargets!(inputs(), makeCtx('/project'))).resolves.toBeUndefined();
+        });
+
+        it('threads validateResponses into the generated router', async () => {
+            const plugin = createTypescriptPlugin({ server: { zod: true, validateResponses: true } }, '/project');
+            const ctx = makeCtx('/project');
+            await plugin.generateTargets!(inputs([userRoot()]), ctx);
+            const router = [...ctx.emitted.entries()].find(([p]) => p.endsWith('.router.ts'))![1];
+            expect(router).toContain('ctx.body = await parseAndValidate(result, User, 500);');
+        });
+
+        it('leaves routers unvalidated without the flag', async () => {
+            const plugin = createTypescriptPlugin({ server: { zod: true } }, '/project');
+            const ctx = makeCtx('/project');
+            await plugin.generateTargets!(inputs([userRoot()]), ctx);
+            const router = [...ctx.emitted.entries()].find(([p]) => p.endsWith('.router.ts'))![1];
+            expect(router).toContain('ctx.body = result;');
+        });
+
+        // The set is derived from the contract roots, not handed in via `inputs`, so a
+        // `format(input=...)` model reaches the router codegen and suppresses its validation.
+        it('derives modelsWithTransform from the contract roots', async () => {
+            const plugin = createTypescriptPlugin({ server: { zod: true, validateResponses: true } }, '/project');
+            const ctx = makeCtx('/project');
+            const contracts = [
+                contractRoot([model('User', [field('id', scalarType('uuid'))], { inputCase: 'snake' })], '/project/contracts/users.ck'),
+            ];
+            await plugin.generateTargets!({ ...inputs([userRoot()]), contractRoots: contracts } as never, ctx);
+            const router = [...ctx.emitted.entries()].find(([p]) => p.endsWith('.router.ts'))![1];
+            expect(router).toContain('ctx.body = result;');
+            expect(router).not.toContain('parseAndValidate(result');
+        });
+    });
+
     describe('default plugin export', () => {
         it('plugin has name "typescript"', async () => {
             const { default: plugin } = await import('../src/index.js');

package/tests/helpers.ts

@@ -11,6 +11,7 @@ import type {
     LiteralTypeNode,
     UnionTypeNode,
     DiscriminatedUnionTypeNode,
+    IntersectionTypeNode,
     ModelRefTypeNode,
     InlineObjectTypeNode,
     LazyTypeNode,
@@ -64,6 +65,10 @@ export function discriminatedUnionType(discriminator: string, ...members: Contra
     return { kind: 'discriminatedUnion', discriminator, members };
 }
 
+export function intersectionType(...members: ContractTypeNode[]): IntersectionTypeNode {
+    return { kind: 'intersection', members };
+}
+
 export function refType(name: string): ModelRefTypeNode {
     return { kind: 'ref', name };
 }