@contractkit/plugin-typescript 0.31.2 → 0.33.0

package/src/index.ts

@@ -20,6 +20,8 @@ import {
     hashFingerprint,
     collectTransitiveModelRefs,
     collectTypeRefs,
+    computeModelsWithCaseTransform,
+    computeModelsWithDecimal,
 } from '@contractkit/core';
 import {
     generateSdk,
@@ -73,6 +75,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. */
@@ -92,7 +103,8 @@ export interface SdkConfig {
      * write-once: the files are created only when absent and are never overwritten or
      * cleaned up on later builds, so any edits you make to them are preserved.
      * Dependency ranges are derived from the contracts (always `zod` when `zod: true`;
-     * `luxon` when any covered model uses a date/time/datetime/interval scalar).
+     * `luxon` when any covered model uses a date/time/datetime/duration/interval scalar;
+     * `decimal.js` when any uses a decimal).
      */
     scaffold?: boolean;
 }
@@ -182,6 +194,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 +217,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 +344,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 +417,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 +435,9 @@ function collectServerOutput(
                         modelOutPaths: serverModelOutPaths,
                         modelsWithInput,
                         modelsWithOutput,
+                        modelsWithTransform,
                         includeInternal: config.includeInternal,
+                        validateResponses: config.validateResponses,
                     }),
                 },
             ],
@@ -433,6 +465,9 @@ function collectSdkOutput(
 
     const modelsWithInput = inputs.modelsWithInput as Set<string>;
     const modelsWithOutput = inputs.modelsWithOutput as Set<string>;
+    // Computed across every contract root, not per file: one decimal below a model taints it, and
+    // the reference that reaches it may live in another .ck file entirely.
+    const modelsWithDecimal = computeModelsWithDecimal(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 ckCommonRoot = commonDir(allFiles, rootDir);
@@ -471,6 +506,9 @@ function collectSdkOutput(
             outPathSlice: sliceOutPathMap(refs, sdkModelOutPaths, modelsWithInput, modelsWithOutput),
             modelsWithInput: sliceModelSet(refs, ownNames, modelsWithInput),
             modelsWithOutput: sliceModelSet(refs, ownNames, modelsWithOutput),
+            // Not covered by `root`: adding a decimal to a model in a *different* .ck file changes
+            // this file's revivers with no change to `root` or the config.
+            modelsWithDecimal: sliceModelSet(refs, ownNames, modelsWithDecimal),
             sdkOptionsPath,
             sub: subConfigKey,
         });
@@ -479,12 +517,16 @@ function collectSdkOutput(
             fingerprint,
             render: () => {
                 let content: string;
+                // `emitRevivers` is set for SDK type files only: a server handler receives decimals
+                // already parsed by `_ZodDecimal`, so it has nothing to rehydrate.
                 if (config.zod) {
                     content = generateContract(ast, {
                         modelOutPaths: sdkModelOutPaths,
                         currentOutPath: typeOutPath,
                         modelsWithInput,
                         modelsWithOutput,
+                        modelsWithDecimal,
+                        emitRevivers: true,
                     });
                 } else {
                     let rel = relative(dirname(typeOutPath), sdkOptionsPath).replace(/\.ts$/, '.js');
@@ -494,6 +536,8 @@ function collectSdkOutput(
                         currentOutPath: typeOutPath,
                         modelsWithInput,
                         modelsWithOutput,
+                        modelsWithDecimal,
+                        emitRevivers: true,
                         jsonValueImportPath: rel,
                     });
                 }
@@ -542,6 +586,7 @@ function collectSdkOutput(
                     outPathSlice: sliceOutPathMap(refs, sdkModelOutPaths, modelsWithInput, modelsWithOutput),
                     modelsWithInput: sliceModelSet(refs, new Set(), modelsWithInput),
                     modelsWithOutput: sliceModelSet(refs, new Set(), modelsWithOutput),
+                    modelsWithDecimal: sliceModelSet(refs, new Set(), modelsWithDecimal),
                     sdkOptionsPath,
                     className,
                     includeInternal: config.includeInternal ?? false,
@@ -560,6 +605,8 @@ function collectSdkOutput(
                                 sdkOptionsPath,
                                 modelsWithInput,
                                 modelsWithOutput,
+                                modelsWithDecimal,
+                                modelMap,
                                 includeInternal: config.includeInternal,
                                 clientClassName: className,
                             }),
@@ -582,6 +629,7 @@ function collectSdkOutput(
                 outPathSlice: sliceOutPathMap(refs, sdkModelOutPaths, modelsWithInput, modelsWithOutput),
                 modelsWithInput: sliceModelSet(refs, new Set(), modelsWithInput),
                 modelsWithOutput: sliceModelSet(refs, new Set(), modelsWithOutput),
+                modelsWithDecimal: sliceModelSet(refs, new Set(), modelsWithDecimal),
                 sdkOptionsPath,
                 includeInternal: config.includeInternal ?? false,
                 sub: subConfigKey,
@@ -599,6 +647,8 @@ function collectSdkOutput(
                             sdkOptionsPath,
                             modelsWithInput,
                             modelsWithOutput,
+                            modelsWithDecimal,
+                            modelMap,
                             includeInternal: config.includeInternal,
                         }),
                     },
@@ -680,6 +730,7 @@ function collectSdkOutput(
                 outPathSlice: sliceOutPathMap(allInlineRefs, sdkModelOutPaths, modelsWithInput, modelsWithOutput),
                 modelsWithInput: sliceModelSet(allInlineRefs, new Set(), modelsWithInput),
                 modelsWithOutput: sliceModelSet(allInlineRefs, new Set(), modelsWithOutput),
+                modelsWithDecimal: sliceModelSet(allInlineRefs, new Set(), modelsWithDecimal),
                 sdkOptionsPath,
                 includeInternal: config.includeInternal ?? false,
                 sub: subConfigKey,
@@ -694,6 +745,8 @@ function collectSdkOutput(
                     sdkOptionsPath,
                     modelsWithInput,
                     modelsWithOutput,
+                    modelsWithDecimal,
+                    modelMap,
                     includeInternal: config.includeInternal,
                 },
             }));
@@ -757,9 +810,13 @@ function collectSdkOutput(
         const coveredRoots = sdkContractEntries.map(e => e.ast);
         const deps: SdkScaffoldDeps = {
             zod: !!config.zod,
-            luxon: coveredRoots.some(
-                r => rootNeedsScalar(r, 'datetime') || rootNeedsScalar(r, 'date') || rootNeedsScalar(r, 'time') || rootNeedsScalar(r, 'interval'),
+            // `duration` belongs here too: `generateContract` imports `Duration` from luxon for it,
+            // so a contract whose only temporal scalar is a duration used to scaffold a package.json
+            // with no luxon dependency and fail to compile.
+            luxon: coveredRoots.some(r =>
+                (['datetime', 'date', 'time', 'duration', 'interval'] as const).some(name => rootNeedsScalar(r, name)),
             ),
+            decimal: coveredRoots.some(r => rootNeedsScalar(r, 'decimal')),
         };
         globalFiles.push({
             relativePath: join(sdkBase, 'package.json'),

package/src/ts-render.ts

@@ -96,6 +96,12 @@ function renderTsScalar(name: ScalarTypeNode['name'], target: TsRenderTarget): s
             return 'number';
         case 'bigint':
             return 'bigint';
+        case 'decimal':
+            // The one scalar whose wire view and server view agree — see the note on this
+            // function and on `serverTsScalar`. A `decimal` travels as a quoted string, and both
+            // the router (via `_ZodDecimal`) and the SDK (via the generated `reviveX` functions)
+            // hand the developer a real `Decimal`, so there is no `target` split to make.
+            return 'Decimal';
         case 'boolean':
             return 'boolean';
         case 'date':

package/tests/codegen-contract.test.ts

@@ -27,7 +27,7 @@ describe('renderType', () => {
         });
 
         it('throws on an unmapped scalar name', () => {
-            expect(() => renderType({ kind: 'scalar', name: 'decimal' } as any)).toThrow(/unmapped scalar 'decimal'/);
+            expect(() => renderType({ kind: 'scalar', name: 'quaternion' } as any)).toThrow(/unmapped scalar 'quaternion'/);
         });
 
         it('renders z.string() with min/max', () => {
@@ -101,6 +101,36 @@ describe('renderType', () => {
             expect(result).toBe(`z.preprocess((val) => typeof val === 'string' ? BigInt(val.replace(/n$/, '')) : val, z.bigint().min(0n).max(100n))`);
         });
 
+        it('renders bare _ZodDecimal for an unconstrained decimal', () => {
+            expect(renderType(scalarType('decimal'))).toBe('_ZodDecimal');
+        });
+
+        it('renders a scale refinement on decimal', () => {
+            expect(renderType(scalarType('decimal', { scale: 2 }))).toBe(
+                `_ZodDecimal.refine((v) => v.decimalPlaces() <= 2, { message: 'Must be at most 2 decimal places' })`,
+            );
+        });
+
+        it('compares decimal bounds as exact strings, never as floats', () => {
+            // `0.01` through `Number()` is the precision loss this scalar exists to prevent, so the
+            // bound is emitted as a quoted string for decimal.js to parse.
+            const result = renderType(scalarType('decimal', { min: '0.01', max: '999999.99' }));
+            expect(result).toBe(
+                `_ZodDecimal.refine((v) => v.gte('0.01') && v.lte('999999.99'), { message: 'Must be at least 0.01, at most 999999.99' })`,
+            );
+        });
+
+        it('renders scale and bounds together', () => {
+            const result = renderType(scalarType('decimal', { min: '0', scale: 2 }));
+            expect(result).toBe(
+                `_ZodDecimal.refine((v) => v.decimalPlaces() <= 2 && v.gte('0'), { message: 'Must be at most 2 decimal places, at least 0' })`,
+            );
+        });
+
+        it('singularises the scale message at 1', () => {
+            expect(renderType(scalarType('decimal', { scale: 1 }))).toContain(`message: 'Must be at most 1 decimal place'`);
+        });
+
         it('renders z.boolean() with string coercion preprocess', () => {
             expect(renderType(scalarType('boolean'))).toBe(`z.preprocess((v) => v === 'true' ? true : v === 'false' ? false : v, z.boolean())`);
         });
@@ -329,6 +359,99 @@ describe('generateContract', () => {
             );
         });
 
+        it('emits the decimal.js import and _ZodDecimal helper when a decimal field is present', () => {
+            const root = contractRoot([model('M', [field('amount', scalarType('decimal'))])]);
+            const output = generateContract(root);
+            // Named, not default: under NodeNext the default export resolves to decimal.js's
+            // namespace declaration and the generated SDK fails to compile.
+            expect(output).toContain(`import { Decimal } from 'decimal.js';`);
+            expect(output).toContain(`Decimal.set({ toExpNeg: -9e15, toExpPos: 9e15 });`);
+            expect(output).toContain(`const _ZodDecimal = z.preprocess(`);
+            // No output `.transform()` — `isRevalidatable` treats every scalar as idempotent under
+            // re-parse, which `server.validateResponses` depends on.
+            expect(output).not.toContain('_ZodDecimal = z.preprocess(...).transform');
+        });
+
+        it('omits the decimal runtime entirely when no decimal field is present', () => {
+            const root = contractRoot([model('M', [field('n', scalarType('number'))])]);
+            const output = generateContract(root);
+            expect(output).not.toContain('decimal.js');
+            expect(output).not.toContain('_ZodDecimal');
+            expect(output).not.toContain('Decimal.set');
+        });
+
+        it('emits revivers only when asked, and only for decimal-carrying models', () => {
+            const root = contractRoot([
+                model('Money', [field('amount', scalarType('decimal'))]),
+                model('Plain', [field('name', scalarType('string'))]),
+            ]);
+            const ctx = { modelOutPaths: new Map(), currentOutPath: '/out/t.ts' };
+
+            // Server-side schemas get decimals already parsed by `_ZodDecimal`, so no revivers.
+            const withoutRevivers = generateContract(root, ctx);
+            expect(withoutRevivers).not.toContain('reviveMoney');
+            expect(withoutRevivers).not.toContain('__dec');
+
+            const withRevivers = generateContract(root, { ...ctx, modelsWithDecimal: new Set(['Money']), emitRevivers: true });
+            expect(withRevivers).toContain('export function reviveMoney(raw: Money): Money {');
+            expect(withRevivers).toContain(`__o0["amount"] = __dec(__o0["amount"], 'Money.amount');`);
+            expect(withRevivers).not.toContain('revivePlain');
+        });
+
+        it('guards an optional or nullable decimal instead of coercing null', () => {
+            const root = contractRoot([
+                model('M', [
+                    field('a', scalarType('decimal'), { optional: true }),
+                    field('b', unionType(scalarType('decimal'), scalarType('null'))),
+                ]),
+            ]);
+            const out = generateContract(root, {
+                modelOutPaths: new Map(),
+                currentOutPath: '/out/t.ts',
+                modelsWithDecimal: new Set(['M']),
+                emitRevivers: true,
+            });
+            expect(out).toContain(`if (__o0["a"] != null) {`);
+            expect(out).toContain(`if (__o0["b"] != null) {`);
+        });
+
+        it('keys the Output reviver by the output casing while children stay camel', () => {
+            const root = contractRoot([
+                model('Money', [field('amount', scalarType('decimal'))]),
+                model('Snake', [field('grossPay', scalarType('decimal')), field('childRef', refType('Money'))], { outputCase: 'snake' }),
+            ]);
+            const out = generateContract(root, {
+                modelOutPaths: new Map(),
+                currentOutPath: '/out/t.ts',
+                modelsWithDecimal: new Set(['Money', 'Snake']),
+                emitRevivers: true,
+            });
+            expect(out).toContain('export function reviveSnakeOutput(raw: SnakeOutput): SnakeOutput {');
+            expect(out).toContain(`__o0["gross_pay"] = __dec(__o0["gross_pay"], 'Snake.gross_pay');`);
+            // `computeModelsWithOutput` propagates referrer→referenced, so Money is NOT transformed
+            // and keeps its camelCase keys — it must use the base reviver, not an Output one.
+            expect(out).toContain(`reviveMoney(__o0["child_ref"] as never);`);
+            expect(out).not.toContain('reviveMoneyOutput');
+        });
+
+        it('recurses through a self-referential model without looping', () => {
+            const root = contractRoot([
+                model('Category', [field('subtotal', scalarType('decimal')), field('children', arrayType(refType('Category')))]),
+            ]);
+            const out = generateContract(root, {
+                modelOutPaths: new Map(),
+                currentOutPath: '/out/t.ts',
+                modelsWithDecimal: new Set(['Category']),
+                emitRevivers: true,
+            });
+            expect(out).toContain('reviveCategory(__a1[__i2] as never);');
+        });
+
+        it('detects a decimal nested in an array', () => {
+            const root = contractRoot([model('M', [field('amounts', arrayType(scalarType('decimal')))])]);
+            expect(generateContract(root)).toContain(`import { Decimal } from 'decimal.js';`);
+        });
+
         it('detects DateTime in nested array types', () => {
             const root = contractRoot([model('M', [field('d', arrayType(scalarType('datetime')))])]);
             const output = generateContract(root);

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,204 @@ 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);');
+        });
+
+        it('re-validates a decimal body, which `isRevalidatable` assumes is idempotent', () => {
+            // `isRevalidatable` returns true for every scalar on the grounds that scalars are
+            // idempotent under re-parse. `_ZodDecimal` satisfies that only because it has no output
+            // `.transform()` — preprocess passes an already-`Decimal` value straight through. If it
+            // were modelled on `_ZodInterval`, which does transform, this would 500 at runtime.
+            const root = respRoot(inlineObjectType([field('amount', scalarType('decimal', { scale: 2 }))]));
+            const output = generateOp(root, V);
+            expect(output).toContain('await parseAndValidate(result,');
+            expect(output).toContain('_ZodDecimal');
+            expect(output).not.toMatch(/_ZodDecimal[^\n]*\.transform\(/);
+            // The helper references `Decimal`, so the import has to come with it.
+            expect(output).toContain(`import { Decimal } from 'decimal.js';`);
+        });
+
+        // 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' })])]);