@contractkit/plugin-typescript 0.30.0 → 0.31.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractkit/plugin-typescript",
-  "version": "0.30.0",
+  "version": "0.31.1",
   "description": "ContractKit built-in plugin: TypeScript codegen (SDK clients, Koa routers, Zod schemas, plain types)",
   "author": {
     "name": "Marooned Software",
@@ -26,7 +26,7 @@
     ".": "./dist/index.js"
   },
   "dependencies": {
-    "@contractkit/core": "0.24.0"
+    "@contractkit/core": "0.26.0"
   },
   "devDependencies": {
     "@repo/config-eslint": "0.3.1",

package/src/codegen-mcp.ts

@@ -1,5 +1,5 @@
 import type { OpRootNode, OpRouteNode, OpOperationNode, McpConfigNode, ParamSource, ContractTypeNode } from '@contractkit/core';
-import { resolveModifiers } from '@contractkit/core';
+import { resolveModifiers, emittedResponses } from '@contractkit/core';
 import { renderType, renderInputType, pascalToDotCase } from './codegen-contract.js';
 import { inferService, deriveModulePath, buildArgs, deriveBaseName } from './codegen-operation.js';
 import { quoteKey, escapeSingleQuoted } from './ts-render.js';
@@ -155,14 +155,22 @@ function argsSchemaExpr(props: ArgsProp[]): string {
 
 // ─── Output schema ──────────────────────────────────────────────────────────
 
-/** Primary response = first with a body, else the first response. */
-function primaryResponse(op: OpOperationNode) {
-    return op.responses.find(r => r.bodyType) ?? op.responses[0];
+/**
+ * The body an MCP tool reports as its output: the first body the service can actually return.
+ *
+ * Documented and thrown statuses are skipped — an MCP tool describes what a successful call
+ * produces, not what the operation is allowed to document.
+ */
+function primaryResponseBody(op: OpOperationNode): ContractTypeNode | undefined {
+    for (const resp of emittedResponses(op)) {
+        if (resp.bodies[0]) return resp.bodies[0].bodyType;
+    }
+    return undefined;
 }
 
 /** MCP output schemas must be objects — only model refs and inline objects qualify. */
 function outputSchemaExpr(op: OpOperationNode): string | undefined {
-    const body = primaryResponse(op)?.bodyType;
+    const body = primaryResponseBody(op);
     if (!body) return undefined;
     if (body.kind === 'ref') return body.name;
     if (body.kind === 'inlineObject') return renderType(body);
@@ -233,7 +241,7 @@ function collectSchemaIds(ops: { route: OpRouteNode; op: OpOperationNode }[], mo
         walkSourceRefs(op.query, ids, modelsWithInput);
         walkSourceRefs(op.headers, ids, modelsWithInput);
 
-        const body = primaryResponse(op)?.bodyType;
+        const body = primaryResponseBody(op);
         if (body && (body.kind === 'ref' || body.kind === 'inlineObject')) walkTypeRefs(body, ids, 'read');
     }
     return ids;
@@ -356,7 +364,7 @@ function renderToolClass(plan: ToolPlan, file: string, options: McpCodegenOption
     const props = buildArgsProps(route, op, options.modelsWithInput);
     const destructure = props.map(p => p.key);
     const callArgs = buildArgs(route, op);
-    const isVoid = !primaryResponse(op)?.bodyType;
+    const isVoid = !primaryResponseBody(op);
     const structured = !!outExpr;
 
     lines.push('    async handle(args: Record<string, unknown>, _context: McpToolContext): Promise<CallToolResult> {');

package/src/codegen-operation.ts

@@ -1,11 +1,20 @@
-import type { OpRootNode, OpRouteNode, OpOperationNode, ContractTypeNode, ScalarTypeNode, ParamSource, ObjectMode } from '@contractkit/core';
-import { resolveModifiers, resolveSecurity, SECURITY_NONE, classifyContentType } from '@contractkit/core';
+import type {
+    OpRootNode,
+    OpRouteNode,
+    OpOperationNode,
+    OpResponseNode,
+    OpResponseHeaderNode,
+    ContractTypeNode,
+    ScalarTypeNode,
+    ParamSource,
+    ObjectMode,
+} from '@contractkit/core';
+import { resolveModifiers, resolveSecurity, SECURITY_NONE, classifyContentType, emittedResponses } from '@contractkit/core';
 import {
     renderType,
     renderInputType,
     renderQueryType,
     pascalToDotCase,
-    typeNeedsScalar,
     modeToWrapper,
 } from './codegen-contract.js';
 import { renderOutputTsType, quoteKey, headerNameToProperty, escapeJsDocLines, escapeSingleQuoted } from './ts-render.js';
@@ -140,27 +149,6 @@ export function generateOp(root: OpRootNode, options: OpCodegenOptions = {}): st
     const services = collectServices(root);
     const routerName = deriveRouterName(root.file);
 
-    const helpers: string[] = [];
-    if (opNeedsScalar(root, 'binary')) {
-        helpers.push(`const _ZodBinary = z.custom<Buffer>((val) => Buffer.isBuffer(val), { error: 'Must be binary data' });`);
-    }
-    if (opNeedsScalar(root, 'datetime')) {
-        helpers.push(
-            `const _ZodDatetime = z.preprocess((val) => typeof val === 'string' ? DateTime.fromISO(val) : val, z.custom<DateTime>((val) => val instanceof DateTime && val.isValid, { message: 'Must be in ISO 8601 format' }));`,
-        );
-    }
-    if (opNeedsScalar(root, 'interval')) {
-        helpers.push(
-            `const _ZodInterval = z.preprocess((val) => typeof val === 'string' ? Interval.fromISO(val) : val, z.custom<Interval>((val) => val instanceof Interval && val.isValid, { message: 'Must be an ISO 8601 interval' })).transform(val => val.toISO()!);`,
-        );
-    }
-    if (opNeedsScalar(root, 'json')) {
-        helpers.push(`type _JsonValue = string | number | boolean | null | _JsonValue[] | { [key: string]: _JsonValue };`);
-        helpers.push(
-            `const _ZodJson: z.ZodType<_JsonValue> = z.lazy(() => z.union([z.string(), z.number(), z.boolean(), z.null(), z.array(_ZodJson), z.record(z.string(), _ZodJson)]));`,
-        );
-    }
-
     const lines: string[] = [];
 
     lines.push('');
@@ -180,9 +168,40 @@ export function generateOp(root: OpRootNode, options: OpCodegenOptions = {}): st
         }
     }
 
-    // Imports are decided from the code we just generated, not from predicates over the AST that
-    // have to be kept in step with it by hand. A predicate that drifts leaves an unused import in
-    // every generated file, which trips `noUnusedLocals` and lint in consuming projects.
+    // Helpers and imports are both decided from the code we just generated, not from predicates
+    // over the AST that have to be kept in step with it by hand. A predicate that drifts leaves an
+    // unused declaration in every generated file, which trips `noUnusedLocals` and lint in
+    // consuming projects — `opNeedsScalar(root, 'binary')` over-approximates exactly that way,
+    // since a binary *response* body is a plain `Buffer` annotation with no schema behind it.
+    const handlerBody = lines.join('\n');
+    const references = (symbol: string) => new RegExp(`\\b${symbol}\\b`).test(handlerBody);
+
+    const helpers: string[] = [];
+    if (references('_ZodBinary')) {
+        helpers.push(`const _ZodBinary = z.custom<Buffer>((val) => Buffer.isBuffer(val), { error: 'Must be binary data' });`);
+    }
+    if (references('_ZodDatetime')) {
+        helpers.push(
+            `const _ZodDatetime = z.preprocess((val) => typeof val === 'string' ? DateTime.fromISO(val) : val, z.custom<DateTime>((val) => val instanceof DateTime && val.isValid, { message: 'Must be in ISO 8601 format' }));`,
+        );
+    }
+    if (references('_ZodInterval')) {
+        helpers.push(
+            `const _ZodInterval = z.preprocess((val) => typeof val === 'string' ? Interval.fromISO(val) : val, z.custom<Interval>((val) => val instanceof Interval && val.isValid, { message: 'Must be an ISO 8601 interval' })).transform(val => val.toISO()!);`,
+        );
+    }
+    // `_ZodJson`'s own declaration is annotated with `_JsonValue`, so the type alias comes along
+    // with it; the alias is also needed on its own for a `json` body's server-side annotation.
+    const needsZodJson = references('_ZodJson');
+    if (needsZodJson || references('_JsonValue')) {
+        helpers.push(`type _JsonValue = string | number | boolean | null | _JsonValue[] | { [key: string]: _JsonValue };`);
+    }
+    if (needsZodJson) {
+        helpers.push(
+            `const _ZodJson: z.ZodType<_JsonValue> = z.lazy(() => z.union([z.string(), z.number(), z.boolean(), z.null(), z.array(_ZodJson), z.record(z.string(), _ZodJson)]));`,
+        );
+    }
+
     const generated = [...(helpers.length ? ['', ...helpers] : []), ...lines].join('\n');
     const uses = (symbol: string) => new RegExp(`\\b${symbol}\\b`).test(generated);
 
@@ -327,66 +346,177 @@ function generateHandler(route: OpRouteNode, op: OpOperationNode, root: OpRootNo
         }
     }
 
-    // Service call — use the first response with a body as the primary response
-    const primaryResponse = op.responses.find(r => r.bodyType) ?? op.responses[0];
+    // Service call. `emittedResponses` decides which of the declared statuses the service is
+    // responsible for producing; the rest are documentation, or the thrown-error path.
+    const emitted = emittedResponses(op);
     const serviceParts = inferService(op, route, file);
-    const respHeaders = primaryResponse?.headers ?? [];
+    const call = `await service.${serviceParts.methodName}(${buildArgs(route, op)})`;
+
+    if (emitted.length > 1) {
+        lines.push(...generateMultiStatusResult(emitted, serviceParts.className, call, options));
+    } else {
+        lines.push(...generateSingleStatusResult(emitted[0], op, serviceParts.className, call, options));
+    }
+
+    lines.push(`});`);
+
+    return lines;
+}
+
+/**
+ * The service produces exactly one status (or none): the result is the body itself, or
+ * `{ body, headers }` when the status declares headers, and `ctx.status` is a constant.
+ *
+ * A status declaring several mimes also gains a `contentType` the service picks, which is the
+ * only thing here that can turn `ctx.type` from a literal into an expression.
+ */
+function generateSingleStatusResult(
+    resp: OpResponseNode | undefined,
+    op: OpOperationNode,
+    className: string,
+    call: string,
+    options: OpCodegenOptions,
+): string[] {
+    const lines: string[] = [];
+    const bodies = resp ? resp.bodies : [];
+    const respHeaders = resp?.headers ?? [];
     const hasRespHeaders = respHeaders.length > 0;
-    const headersAnnotation = hasRespHeaders
-        ? `{ ${respHeaders
-              .map(
-                  h =>
-                      `${quoteKey(headerNameToProperty(h.name))}${h.optional ? '?' : ''}: ${renderOutputTsType(h.type, options.modelsWithOutput, 'server')}`,
-              )
-              .join('; ')} }`
-        : '';
-
-    if (primaryResponse?.bodyType) {
-        const { annotation, prelude } = formatTypeAnnotation(primaryResponse.bodyType!, options.modelsWithOutput);
-        if (prelude) {
-            lines.push(`    ${prelude}`);
-        }
-        lines.push(`    const service = ctx.container.get(${serviceParts.className});`);
+    const headersAnnotation = hasRespHeaders ? renderHeadersAnnotation(respHeaders, options.modelsWithOutput) : '';
+
+    if (bodies.length === 1) {
+        const { annotation, prelude } = formatTypeAnnotation(bodies[0]!.bodyType, options.modelsWithOutput);
+        if (prelude) lines.push(`    ${prelude}`);
+        lines.push(`    const service = ctx.container.get(${className});`);
         if (hasRespHeaders) {
-            lines.push(
-                `    const result: { body: ${annotation}; headers: ${headersAnnotation} } = await service.${serviceParts.methodName}(${buildArgs(route, op)});`,
-            );
+            lines.push(`    const result: { body: ${annotation}; headers: ${headersAnnotation} } = ${call};`);
         } else {
-            lines.push(`    const result: ${annotation} = await service.${serviceParts.methodName}(${buildArgs(route, op)});`);
+            lines.push(`    const result: ${annotation} = ${call};`);
         }
+    } else if (bodies.length > 1) {
+        const { members, preludes } = renderResponseMembers(resp!, options, { includeStatus: false, varPrefix: 'result' });
+        for (const prelude of preludes) lines.push(`    ${prelude}`);
+        lines.push(`    const service = ctx.container.get(${className});`);
+        lines.push(`    const result: ${members.join(' | ')} = ${call};`);
     } else {
-        lines.push(`    const service = ctx.container.get(${serviceParts.className});`);
+        lines.push(`    const service = ctx.container.get(${className});`);
         if (hasRespHeaders) {
-            lines.push(`    const result: { headers: ${headersAnnotation} } = await service.${serviceParts.methodName}(${buildArgs(route, op)});`);
+            lines.push(`    const result: { headers: ${headersAnnotation} } = ${call};`);
         } else {
-            lines.push(`    await service.${serviceParts.methodName}(${buildArgs(route, op)});`);
+            lines.push(`    ${call};`);
         }
     }
 
     lines.push('');
-    lines.push(`    ctx.status = ${primaryResponse?.statusCode ?? 200};`);
+    // With nothing emitted, the status is still declared somewhere — fall back to the first
+    // one written, which is what a documentation-only 3xx/4xx operation means.
+    lines.push(`    ctx.status = ${resp?.statusCode ?? op.responses[0]?.statusCode ?? 200};`);
+    lines.push(...headerSetLines(respHeaders, '    '));
 
-    if (hasRespHeaders) {
-        for (const h of respHeaders) {
-            const accessor = `result.headers[${JSON.stringify(headerNameToProperty(h.name))}]`;
-            if (h.optional) {
-                lines.push(`    if (${accessor} !== undefined) ctx.set('${h.name}', String(${accessor}));`);
-            } else {
-                lines.push(`    ctx.set('${h.name}', String(${accessor}));`);
-            }
-        }
+    if (bodies.length === 1) {
+        lines.push(`    ctx.type = '${bodies[0]!.contentType}';`);
+        lines.push(`    ctx.body = ${hasRespHeaders ? 'result.body' : 'result'};`);
+    } else if (bodies.length > 1) {
+        lines.push(`    ctx.type = result.contentType;`);
+        lines.push(`    ctx.body = result.body;`);
     }
 
-    if (primaryResponse?.bodyType && primaryResponse.contentType) {
-        lines.push(`    ctx.type = '${primaryResponse.contentType}';`);
-        lines.push(`    ctx.body = ${hasRespHeaders ? 'result.body' : 'result'};`);
+    return lines;
+}
+
+/**
+ * The service chooses between several statuses: the result is a union discriminated on
+ * `status`, and the handler switches on it so each status writes only its own headers, mime
+ * and body.
+ */
+function generateMultiStatusResult(emitted: OpResponseNode[], className: string, call: string, options: OpCodegenOptions): string[] {
+    const lines: string[] = [];
+    const members: string[] = [];
+    const preludes: string[] = [];
+
+    for (const resp of emitted) {
+        const rendered = renderResponseMembers(resp, options, { includeStatus: true, varPrefix: `result${resp.statusCode}` });
+        members.push(...rendered.members);
+        preludes.push(...rendered.preludes);
     }
 
-    lines.push(`});`);
+    for (const prelude of preludes) lines.push(`    ${prelude}`);
+    lines.push(`    const service = ctx.container.get(${className});`);
+    lines.push(`    const result:`);
+    for (const member of members) lines.push(`        | ${member}`);
+    lines.push(`        = ${call};`);
+    lines.push('');
+    lines.push(`    ctx.status = result.status;`);
+    lines.push(`    switch (result.status) {`);
+    for (const resp of emitted) {
+        lines.push(`        case ${resp.statusCode}:`);
+        lines.push(...headerSetLines(resp.headers ?? [], '            '));
+        if (resp.bodies.length > 0) {
+            lines.push(`            ctx.type = result.contentType;`);
+            lines.push(`            ctx.body = result.body;`);
+        }
+        lines.push(`            break;`);
+    }
+    lines.push(`    }`);
 
     return lines;
 }
 
+/**
+ * Render one status as the members of the service-result union — its `contentType`, `body` and
+ * `headers`, plus `status` when the operation emits more than one.
+ *
+ * A status declaring several mimes collapses to a single member with a union of mime literals
+ * when the bodies are structurally identical (`image/png` and `image/jpeg` both `binary`).
+ * When they differ, it produces one member per mime so `contentType` and `body` stay correlated.
+ */
+function renderResponseMembers(
+    resp: OpResponseNode,
+    options: OpCodegenOptions,
+    opts: { includeStatus: boolean; varPrefix: string },
+): { members: string[]; preludes: string[] } {
+    const bodies = resp.bodies;
+    const headers = resp.headers ?? [];
+    const leading = opts.includeStatus ? [`status: ${resp.statusCode}`] : [];
+    const trailing = headers.length > 0 ? [`headers: ${renderHeadersAnnotation(headers, options.modelsWithOutput)}`] : [];
+    const preludes: string[] = [];
+
+    if (bodies.length === 0) {
+        return { members: [`{ ${[...leading, ...trailing].join('; ')} }`], preludes };
+    }
+
+    const uniform = bodies.every(b => bodyTypesStructurallyEqual(b.bodyType, bodies[0]!.bodyType));
+    if (uniform) {
+        const { annotation, prelude } = formatTypeAnnotation(bodies[0]!.bodyType, options.modelsWithOutput, `${opts.varPrefix}Type`);
+        if (prelude) preludes.push(prelude);
+        const contentType = bodies.map(b => `'${b.contentType}'`).join(' | ');
+        return { members: [`{ ${[...leading, `contentType: ${contentType}`, `body: ${annotation}`, ...trailing].join('; ')} }`], preludes };
+    }
+
+    const members = bodies.map((b, i) => {
+        const { annotation, prelude } = formatTypeAnnotation(b.bodyType, options.modelsWithOutput, `${opts.varPrefix}Type${i}`);
+        if (prelude) preludes.push(prelude);
+        return `{ ${[...leading, `contentType: '${b.contentType}'`, `body: ${annotation}`, ...trailing].join('; ')} }`;
+    });
+    return { members, preludes };
+}
+
+function renderHeadersAnnotation(headers: OpResponseHeaderNode[], modelsWithOutput?: Set<string>): string {
+    const fields = headers.map(
+        h => `${quoteKey(headerNameToProperty(h.name))}${h.optional ? '?' : ''}: ${renderOutputTsType(h.type, modelsWithOutput, 'server')}`,
+    );
+    return `{ ${fields.join('; ')} }`;
+}
+
+/** `ctx.set(...)` calls for a status's declared response headers, guarding the optional ones. */
+function headerSetLines(headers: OpResponseHeaderNode[], indent: string): string[] {
+    return headers.map(h => {
+        const accessor = `result.headers[${JSON.stringify(headerNameToProperty(h.name))}]`;
+        return h.optional
+            ? `${indent}if (${accessor} !== undefined) ctx.set('${h.name}', String(${accessor}));`
+            : `${indent}ctx.set('${h.name}', String(${accessor}));`;
+    });
+}
+
 // ─── Inference helpers ─────────────────────────────────────────────────────
 
 /**
@@ -508,9 +638,13 @@ function serverTsScalar(name: ScalarTypeNode['name']): string {
     }
 }
 
-function formatTypeAnnotation(bodyType: ContractTypeNode, modelsWithOutput?: Set<string>): { annotation: string; prelude?: string } {
+/**
+ * @param varName Name for the extracted schema variable. Distinct per status and per mime when
+ *   an operation emits several, so two complex bodies in one handler cannot collide.
+ */
+function formatTypeAnnotation(bodyType: ContractTypeNode, modelsWithOutput?: Set<string>, varName = 'resultType'): { annotation: string; prelude?: string } {
     if (bodyType.kind === 'array') {
-        const inner = formatTypeAnnotation(bodyType.item, modelsWithOutput);
+        const inner = formatTypeAnnotation(bodyType.item, modelsWithOutput, varName);
         return { annotation: `${inner.annotation}[]`, prelude: inner.prelude };
     }
     if (bodyType.kind === 'ref') {
@@ -521,8 +655,8 @@ function formatTypeAnnotation(bodyType: ContractTypeNode, modelsWithOutput?: Set
     // For complex types, extract schema into a variable so the result line stays readable
     const schema = renderType(bodyType);
     return {
-        annotation: 'z.infer<typeof resultType>',
-        prelude: `const resultType = ${schema};`,
+        annotation: `z.infer<typeof ${varName}>`,
+        prelude: `const ${varName} = ${schema};`,
     };
 }
 
@@ -640,9 +774,9 @@ function collectTypes(root: OpRootNode, modelsWithInput?: Set<string>, modelsWit
                 }
             }
             for (const resp of op.responses) {
-                if (resp.bodyType) {
-                    collectTypeNodeRefs(resp.bodyType, types);
-                    collectOutputTypeNodeRefs(resp.bodyType, types, modelsWithOutput);
+                for (const body of resp.bodies) {
+                    collectTypeNodeRefs(body.bodyType, types);
+                    collectOutputTypeNodeRefs(body.bodyType, types, modelsWithOutput);
                 }
                 if (resp.headers) {
                     for (const h of resp.headers) {
@@ -786,29 +920,6 @@ function collectTypeNodeRefs(type: ContractTypeNode, out: Set<string>): void {
     }
 }
 
-
-
-function paramSourceNeedsScalar(source: ParamSource | undefined, name: string): boolean {
-    if (!source) return false;
-    if (source.kind === 'ref') return false;
-    if (source.kind === 'params') return source.nodes.some(p => typeNeedsScalar(p.type, name));
-    return typeNeedsScalar(source.node, name);
-}
-
-function opNeedsScalar(root: OpRootNode, name: string): boolean {
-    return root.routes.some(
-        route =>
-            paramSourceNeedsScalar(route.params, name) ||
-            route.operations.some(
-                op =>
-                    !!op.request?.bodies.some(b => typeNeedsScalar(b.bodyType, name)) ||
-                    op.responses.some(r => r.bodyType && typeNeedsScalar(r.bodyType, name)) ||
-                    paramSourceNeedsScalar(op.query, name) ||
-                    paramSourceNeedsScalar(op.headers, name),
-            ),
-    );
-}
-
 function collectServices(root: OpRootNode): string[] {
     const services = new Set<string>();
     const inferredService = `${deriveBaseName(root.file)}Service`;