@contractkit/plugin-typescript 0.29.0 → 0.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractkit/plugin-typescript",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "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.23.0"
+    "@contractkit/core": "0.24.0"
   },
   "devDependencies": {
     "@repo/config-eslint": "0.3.1",

package/src/codegen-operation.ts

@@ -5,7 +5,6 @@ import {
     renderInputType,
     renderQueryType,
     pascalToDotCase,
-    typeNeedsDateTime,
     typeNeedsScalar,
     modeToWrapper,
 } from './codegen-contract.js';
@@ -126,50 +125,20 @@ export interface OpCodegenOptions {
     includeInternal?: boolean;
 }
 
-/** Generate a Koa router module for every operation in `root`, including the imports, type aliases, and handler list. */
+/**
+ * Generate a Koa router module for every operation in `root`, including the imports, type
+ * aliases, and handler list.
+ *
+ * Imports are derived from the generated body — each candidate symbol is emitted only if it
+ * actually appears in the output. Deciding them from predicates over the AST instead means any
+ * drift between predicate and codegen leaves an unused import in every generated file, which
+ * trips `noUnusedLocals` and lint downstream.
+ */
 export function generateOp(root: OpRootNode, options: OpCodegenOptions = {}): string {
     // Collect all referenced types across all routes
     const types = collectTypes(root, options.modelsWithInput, options.modelsWithOutput);
     const services = collectServices(root);
     const routerName = deriveRouterName(root.file);
-    const needsParseAndValidate = routeNeedsValidation(root);
-
-    // Generate the body first so we can detect whether `z.` is actually referenced
-    // before deciding whether to emit the zod import.
-    const body: string[] = [];
-    const needsSignature = fileNeedsSignature(root);
-    const needsPolicy = fileNeedsPolicy(root);
-    const koaImports = ['ServerKitRouter', 'bodyParserMiddleware'];
-    if (needsPolicy) koaImports.push('requirePolicy');
-    if (needsSignature) koaImports.push('requireSignature');
-    body.push(`import { ${koaImports.join(', ')} } from '@maroonedsoftware/koa';`);
-
-    for (const svc of services) {
-        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));
-    }
-
-    // luxon is needed for date/time/datetime (DateTime), duration (Duration) and interval (Interval);
-    // the rendered Zod schemas and the service-result annotations both reference these classes.
-    const luxonImports: string[] = [];
-    if (opNeedsDateTime(root)) luxonImports.push('DateTime');
-    if (opNeedsScalar(root, 'duration')) luxonImports.push('Duration');
-    if (opNeedsScalar(root, 'interval')) luxonImports.push('Interval');
-    if (luxonImports.length > 0) {
-        body.push(`import { ${luxonImports.join(', ')} } from 'luxon';`);
-    }
-
-    if (needsParseAndValidate) {
-        body.push(`import { parseAndValidate } from '@maroonedsoftware/zod';`);
-    }
-
-    if (fileUsesMultipart(root)) {
-        body.push(`import { MultipartBody } from '@maroonedsoftware/multipart';`);
-    }
 
     const helpers: string[] = [];
     if (opNeedsScalar(root, 'binary')) {
@@ -211,6 +180,43 @@ 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.
+    const generated = [...(helpers.length ? ['', ...helpers] : []), ...lines].join('\n');
+    const uses = (symbol: string) => new RegExp(`\\b${symbol}\\b`).test(generated);
+
+    const body: string[] = [];
+
+    const koaImports = ['ServerKitRouter', 'bodyParserMiddleware', 'requirePolicy', 'requireSignature'].filter(uses);
+    if (koaImports.length > 0) {
+        body.push(`import { ${koaImports.join(', ')} } from '@maroonedsoftware/koa';`);
+    }
+
+    for (const svc of services) {
+        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));
+    }
+
+    // luxon is needed for date/time/datetime (DateTime), duration (Duration) and interval (Interval);
+    // the rendered Zod schemas and the service-result annotations both reference these classes.
+    const luxonImports = ['DateTime', 'Duration', 'Interval'].filter(uses);
+    if (luxonImports.length > 0) {
+        body.push(`import { ${luxonImports.join(', ')} } from 'luxon';`);
+    }
+
+    if (uses('parseAndValidate')) {
+        body.push(`import { parseAndValidate } from '@maroonedsoftware/zod';`);
+    }
+
+    if (uses('MultipartBody')) {
+        body.push(`import { MultipartBody } from '@maroonedsoftware/multipart';`);
+    }
+
     const allContent = [...body, ...(helpers.length ? ['', ...helpers] : []), ...lines].join('\n');
     const needsZod = /\bz\./.test(allContent);
     return (needsZod ? `import { z } from 'zod';\n` : '') + allContent;
@@ -780,26 +786,7 @@ function collectTypeNodeRefs(type: ContractTypeNode, out: Set<string>): void {
     }
 }
 
-function paramSourceNeedsDateTime(source: ParamSource | undefined): boolean {
-    if (!source) return false;
-    if (source.kind === 'ref') return false;
-    if (source.kind === 'params') return source.nodes.some(p => typeNeedsDateTime(p.type));
-    return typeNeedsDateTime(source.node);
-}
 
-function opNeedsDateTime(root: OpRootNode): boolean {
-    return root.routes.some(
-        route =>
-            paramSourceNeedsDateTime(route.params) ||
-            route.operations.some(
-                op =>
-                    !!op.request?.bodies.some(b => typeNeedsDateTime(b.bodyType)) ||
-                    op.responses.some(r => r.bodyType && typeNeedsDateTime(r.bodyType)) ||
-                    paramSourceNeedsDateTime(op.query) ||
-                    paramSourceNeedsDateTime(op.headers),
-            ),
-    );
-}
 
 function paramSourceNeedsScalar(source: ParamSource | undefined, name: string): boolean {
     if (!source) return false;
@@ -838,32 +825,10 @@ function collectServices(root: OpRootNode): string[] {
     return [...services].sort();
 }
 
-function hasParamSource(source?: ParamSource): boolean {
-    if (!source) return false;
-    if (source.kind === 'ref') return true;
-    if (source.kind === 'params') return source.nodes.length > 0;
-    return true; // type
-}
 
-function routeNeedsValidation(root: OpRootNode): boolean {
-    return root.routes.some(
-        r => hasParamSource(r.params) || r.operations.some(op => !!op.request || hasParamSource(op.query) || hasParamSource(op.headers)),
-    );
-}
 
-function fileNeedsPolicy(root: OpRootNode): boolean {
-    return root.routes.some(route => route.operations.some(op => resolveSecurity(route, op, root) !== SECURITY_NONE));
-}
 
-function fileNeedsSignature(root: OpRootNode): boolean {
-    return root.routes.some(route => route.operations.some(op => !!op.signature));
-}
 
-function fileUsesMultipart(root: OpRootNode): boolean {
-    return root.routes.some(route =>
-        route.operations.some(op => (op.request?.bodies ?? []).some(b => b.contentType === 'multipart/form-data')),
-    );
-}
 
 function isValidIdentifier(name: string): boolean {
     return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name);

package/tests/codegen-operation.test.ts

@@ -101,6 +101,66 @@ describe('generateOperation', () => {
             const output = generateOp(root);
             expect(output).not.toContain('luxon');
         });
+
+        // Every conditional import must be justified by a reference in the generated body —
+        // an unused import trips `noUnusedLocals` and lint in the consuming project.
+        it('imports bodyParserMiddleware only when an operation has a request body', () => {
+            const withBody = generateOp(opRoot([opRoute('/users', [opOperation('post', { request: opRequest('CreateUser') })])]));
+            expect(withBody).toContain('bodyParserMiddleware');
+
+            const withoutBody = generateOp(opRoot([opRoute('/users', [opOperation('get')])]));
+            expect(withoutBody).not.toContain('bodyParserMiddleware');
+        });
+
+        it('omits MultipartBody when a multipart body shares its shape with the other MIME types', () => {
+            // Structurally equal bodies collapse to a single parseAndValidate call, so nothing
+            // references MultipartBody even though the operation does declare multipart.
+            const root = opRoot([
+                opRoute('/upload', [
+                    opOperation('post', {
+                        request: opMultiRequest([
+                            ['multipart/form-data', 'UploadForm'],
+                            ['application/json', 'UploadForm'],
+                        ]),
+                    }),
+                ]),
+            ]);
+            const output = generateOp(root);
+            expect(output).not.toContain('MultipartBody');
+        });
+
+        it('imports MultipartBody when the multipart body is handled on its own', () => {
+            const root = opRoot([opRoute('/upload', [opOperation('post', { request: opMultiRequest([['multipart/form-data', 'UploadForm']]) })])]);
+            expect(generateOp(root)).toContain("import { MultipartBody } from '@maroonedsoftware/multipart';");
+        });
+
+        it('leaves no import unreferenced in the generated body', () => {
+            const root = opRoot([
+                opRoute(
+                    '/users/{id}',
+                    [
+                        opOperation('get', { security: SECURITY_NONE }),
+                        opOperation('post', { request: opRequest('CreateUser'), signature: 'webhookKey' }),
+                    ],
+                    [opParam('id', scalarType('uuid'))],
+                ),
+            ]);
+            const output = generateOp(root);
+            const importLines = output.split('\n').filter(l => l.startsWith('import '));
+            expect(importLines.length).toBeGreaterThan(0);
+
+            const bodyText = output
+                .split('\n')
+                .filter(l => !l.startsWith('import '))
+                .join('\n');
+            for (const line of importLines) {
+                const named = line.match(/^import \{([^}]*)\}/);
+                if (!named) continue;
+                for (const symbol of named[1]!.split(',').map(s => s.trim().replace(/^type /, ''))) {
+                    expect(bodyText, `${symbol} is imported but never used`).toMatch(new RegExp(`\\b${symbol}\\b`));
+                }
+            }
+        });
     });
 
     // ─── Handler signature ─────────────────────────────────────────
@@ -974,7 +1034,7 @@ describe('generateOp — route modifiers JSDoc', () => {
             const root = opRoot([opRoute('/users', [op])]);
             const out = generateOp(root);
             expect(out).not.toContain('requireSignature');
-            expect(out).toContain(`import { ServerKitRouter, bodyParserMiddleware, requirePolicy }`);
+            expect(out).toContain(`import { ServerKitRouter, requirePolicy }`);
         });
     });
 
@@ -985,7 +1045,7 @@ describe('generateOp — route modifiers JSDoc', () => {
             const op = opOperation('get');
             const root = opRoot([opRoute('/users', [op])]);
             const out = generateOp(root);
-            expect(out).toContain(`import { ServerKitRouter, bodyParserMiddleware, requirePolicy }`);
+            expect(out).toContain(`import { ServerKitRouter, requirePolicy }`);
             expect(out).toContain(`requirePolicy()`);
         });
 
@@ -1019,7 +1079,7 @@ describe('generateOp — route modifiers JSDoc', () => {
             const op = opOperation('get', { security: SECURITY_NONE });
             const root = opRoot([opRoute('/health', [op])]);
             const out = generateOp(root);
-            expect(out).toContain(`import { ServerKitRouter, bodyParserMiddleware }`);
+            expect(out).toContain(`import { ServerKitRouter } from`);
             expect(out).not.toContain('requirePolicy');
         });