@contractkit/plugin-typescript 0.16.1

package/tests/codegen-server.test.ts

@@ -0,0 +1,192 @@
+import { describe, it, expect } from 'vitest';
+import { createTypescriptPlugin } from '../src/index.js';
+import type { PluginContext } from '@contractkit/core';
+import { opRoot, opRoute, opOperation, opParam, opRequest, opResponse, scalarType, refType, contractRoot, model, field } from './helpers.js';
+
+// ─── Helpers ───────────────────────────────────────────────────────────────
+
+function makeCtx(rootDir = '/project', options: Record<string, unknown> = {}): PluginContext & { emitted: Map<string, string> } {
+    const emitted = new Map<string, string>();
+    return {
+        rootDir,
+        options,
+        emitFile: (outPath: string, content: string) => {
+            emitted.set(outPath, content);
+        },
+        emitted,
+    };
+}
+
+function inputs(opRoots = [opRoot([opRoute('/users', [opOperation('get')])], '/project/contracts/users.ck')], contractRoots = []) {
+    return {
+        contractRoots,
+        opRoots,
+        modelOutPaths: new Map<string, string>(),
+        modelsWithInput: new Set<string>(),
+        modelsWithOutput: new Set<string>(),
+    };
+}
+
+// ─── Tests ─────────────────────────────────────────────────────────────────
+
+describe('createTypescriptPlugin (server)', () => {
+    describe('output path computation', () => {
+        it('uses template variable {filename} in routes output path', async () => {
+            const plugin = createTypescriptPlugin({ server: { output: { routes: 'src/routes/{filename}.router.ts' } } }, '/project');
+            const ctx = makeCtx('/project');
+            await plugin.generateTargets!(inputs(), ctx);
+            expect([...ctx.emitted.keys()].some(p => p.endsWith('users.router.ts'))).toBe(true);
+        });
+
+        it('respects baseDir when computing output path', async () => {
+            const plugin = createTypescriptPlugin({ server: { baseDir: 'apps/api', output: { routes: 'src/{filename}.router.ts' } } }, '/project');
+            const ctx = makeCtx('/project');
+            await plugin.generateTargets!(inputs(), ctx);
+            const [outPath] = [...ctx.emitted.keys()];
+            expect(outPath).toContain('apps/api');
+        });
+
+        it('defaults to {filename}.router.ts when no output template', async () => {
+            const plugin = createTypescriptPlugin({ server: {} }, '/project');
+            const ctx = makeCtx('/project');
+            await plugin.generateTargets!(inputs(), ctx);
+            expect([...ctx.emitted.keys()].some(p => p.endsWith('users.router.ts'))).toBe(true);
+        });
+
+        it('emits one route file per op root', async () => {
+            const plugin = createTypescriptPlugin({ server: {} }, '/project');
+            const ctx = makeCtx('/project');
+            await plugin.generateTargets!(
+                inputs([
+                    opRoot([opRoute('/users', [opOperation('get')])], '/project/contracts/users.ck'),
+                    opRoot([opRoute('/payments', [opOperation('get')])], '/project/contracts/payments.ck'),
+                ]),
+                ctx,
+            );
+            expect(ctx.emitted.size).toBe(2);
+        });
+
+        it('emits type files alongside routes when output.types is configured', async () => {
+            const plugin = createTypescriptPlugin(
+                {
+                    server: {
+                        output: {
+                            routes: 'src/routes/{filename}.router.ts',
+                            types: 'src/types/{filename}.ts',
+                        },
+                    },
+                },
+                '/project',
+            );
+            const ctx = makeCtx('/project');
+            const contractRoots = [contractRoot([model('User', [field('id', scalarType('uuid'))])], '/project/contracts/users.ck')];
+            await plugin.generateTargets!(inputs(undefined, contractRoots as any), ctx);
+            expect([...ctx.emitted.keys()].some(p => p.includes('src/types'))).toBe(true);
+        });
+
+        it('emits Zod schemas for types when zod: true', async () => {
+            const plugin = createTypescriptPlugin(
+                {
+                    server: {
+                        zod: true,
+                        output: { types: 'src/types/{filename}.ts' },
+                    },
+                },
+                '/project',
+            );
+            const ctx = makeCtx('/project');
+            const contractRoots = [contractRoot([model('User', [field('id', scalarType('uuid'))])], '/project/contracts/users.ck')];
+            await plugin.generateTargets!(inputs([], contractRoots as any), ctx);
+            const typeContent = [...ctx.emitted.values()].find(c => c.includes('z.'));
+            expect(typeContent).toBeDefined();
+        });
+
+        it('emits plain TypeScript types when zod is not set', async () => {
+            const plugin = createTypescriptPlugin(
+                {
+                    server: {
+                        output: { types: 'src/types/{filename}.ts' },
+                    },
+                },
+                '/project',
+            );
+            const ctx = makeCtx('/project');
+            const contractRoots = [contractRoot([model('User', [field('id', scalarType('uuid'))])], '/project/contracts/users.ck')];
+            await plugin.generateTargets!(inputs([], contractRoots as any), ctx);
+            const typeContent = [...ctx.emitted.values()][0]!;
+            expect(typeContent).not.toContain('z.');
+            expect(typeContent).toContain('export interface User');
+        });
+    });
+
+    describe('generated content', () => {
+        it('emits a Koa router', async () => {
+            const plugin = createTypescriptPlugin({ server: {} }, '/project');
+            const ctx = makeCtx('/project');
+            await plugin.generateTargets!(inputs(), ctx);
+            const content = [...ctx.emitted.values()][0]!;
+            expect(content).toContain('ServerKitRouter');
+        });
+
+        it('includes route path', async () => {
+            const plugin = createTypescriptPlugin({ server: {} }, '/project');
+            const ctx = makeCtx('/project');
+            await plugin.generateTargets!(inputs([opRoot([opRoute('/payments/{id}', [opOperation('get')])], '/project/contracts/payments.ck')]), ctx);
+            const content = [...ctx.emitted.values()][0]!;
+            expect(content).toContain('/payments');
+        });
+
+        it('includes service call when servicePathTemplate is set', async () => {
+            const plugin = createTypescriptPlugin({ server: { servicePathTemplate: '#services/{module}.service.js' } }, '/project');
+            const ctx = makeCtx('/project');
+            const root = opRoot([opRoute('/users', [opOperation('get', { service: 'UserService.list' })])], '/project/contracts/users.ck');
+            await plugin.generateTargets!(inputs([root]), ctx);
+            const content = [...ctx.emitted.values()][0]!;
+            expect(content).toContain('UserService');
+        });
+
+        it('includes request body validation when route has a POST body', async () => {
+            const plugin = createTypescriptPlugin({ server: {} }, '/project');
+            const ctx = makeCtx('/project');
+            const root = opRoot([opRoute('/users', [opOperation('post', { request: opRequest('CreateUser') })])], '/project/contracts/users.ck');
+            await plugin.generateTargets!(inputs([root]), ctx);
+            const content = [...ctx.emitted.values()][0]!;
+            expect(content).toContain('parseAndValidate');
+        });
+
+        it('includes uuid param validation', async () => {
+            const plugin = createTypescriptPlugin({ server: {} }, '/project');
+            const ctx = makeCtx('/project');
+            const root = opRoot([opRoute('/users/{id}', [opOperation('get')], [opParam('id', scalarType('uuid'))])], '/project/contracts/users.ck');
+            await plugin.generateTargets!(inputs([root]), ctx);
+            const content = [...ctx.emitted.values()][0]!;
+            expect(content).toContain('parseAndValidate');
+        });
+
+        it('includes response type reference when response has model ref', async () => {
+            const plugin = createTypescriptPlugin({ server: {} }, '/project');
+            const ctx = makeCtx('/project');
+            const root = opRoot(
+                [opRoute('/users', [opOperation('get', { responses: [opResponse(200, 'User', 'application/json')] })])],
+                '/project/contracts/users.ck',
+            );
+            await plugin.generateTargets!(inputs([root]), ctx);
+            const content = [...ctx.emitted.values()][0]!;
+            expect(content).toContain('User');
+        });
+    });
+
+    describe('default plugin export', () => {
+        it('plugin has name "typescript"', async () => {
+            const { default: plugin } = await import('../src/index.js');
+            expect(plugin.name).toBe('typescript');
+        });
+
+        it('plugin reads server config from ctx.options.server', async () => {
+            const { default: plugin } = await import('../src/index.js');
+            const ctx = makeCtx('/project', { server: { output: { routes: 'src/routes/{filename}.router.ts' } } });
+            await plugin.generateTargets!(inputs(), ctx);
+            expect([...ctx.emitted.keys()].some(p => p.endsWith('users.router.ts'))).toBe(true);
+        });
+    });
+});

package/tests/helpers.ts

@@ -0,0 +1,247 @@
+import type {
+    ContractRootNode,
+    ModelNode,
+    FieldNode,
+    ContractTypeNode,
+    ScalarTypeNode,
+    ArrayTypeNode,
+    TupleTypeNode,
+    RecordTypeNode,
+    EnumTypeNode,
+    LiteralTypeNode,
+    UnionTypeNode,
+    DiscriminatedUnionTypeNode,
+    ModelRefTypeNode,
+    InlineObjectTypeNode,
+    LazyTypeNode,
+    SourceLocation,
+    OpRootNode,
+    OpRouteNode,
+    OpOperationNode,
+    OpParamNode,
+    OpRequestNode,
+    OpResponseNode,
+    HttpMethod,
+    ParamSource,
+    RouteModifier,
+} from '@contractkit/core';
+
+// ─── AST Builder Helpers ────────────────────────────────────────────────────
+
+export function loc(line = 1, file = 'test.ck'): SourceLocation {
+    return { file, line };
+}
+
+export function scalarType(name: ScalarTypeNode['name'], mods?: Partial<ScalarTypeNode>): ScalarTypeNode {
+    return { kind: 'scalar', name, ...mods };
+}
+
+export function arrayType(item: ContractTypeNode, mods?: { min?: number; max?: number }): ArrayTypeNode {
+    return { kind: 'array', item, ...mods };
+}
+
+export function tupleType(...items: ContractTypeNode[]): TupleTypeNode {
+    return { kind: 'tuple', items };
+}
+
+export function recordType(key: ContractTypeNode, value: ContractTypeNode): RecordTypeNode {
+    return { kind: 'record', key, value };
+}
+
+export function enumType(...values: string[]): EnumTypeNode {
+    return { kind: 'enum', values };
+}
+
+export function literalType(value: string | number | boolean): LiteralTypeNode {
+    return { kind: 'literal', value };
+}
+
+export function unionType(...members: ContractTypeNode[]): UnionTypeNode {
+    return { kind: 'union', members };
+}
+
+export function discriminatedUnionType(discriminator: string, ...members: ContractTypeNode[]): DiscriminatedUnionTypeNode {
+    return { kind: 'discriminatedUnion', discriminator, members };
+}
+
+export function refType(name: string): ModelRefTypeNode {
+    return { kind: 'ref', name };
+}
+
+export function inlineObjectType(fields: FieldNode[]): InlineObjectTypeNode {
+    return { kind: 'inlineObject', fields };
+}
+
+export function lazyType(inner: ContractTypeNode): LazyTypeNode {
+    return { kind: 'lazy', inner };
+}
+
+export function field(name: string, type: ContractTypeNode, overrides?: Partial<FieldNode>): FieldNode {
+    return {
+        name,
+        optional: false,
+        nullable: false,
+        visibility: 'normal',
+        type,
+        loc: loc(),
+        ...overrides,
+    };
+}
+
+export function model(name: string, fields: FieldNode[], overrides?: Partial<ModelNode>): ModelNode {
+    return {
+        kind: 'model',
+        name,
+        fields,
+        loc: loc(),
+        ...overrides,
+    };
+}
+
+export function contractRoot(models: ModelNode[], file = 'test.ck'): ContractRootNode {
+    return { kind: 'contractRoot', meta: {}, models, file };
+}
+
+export function opParam(name: string, type: ContractTypeNode): OpParamNode {
+    return { name, type, loc: loc(1, 'test.op') };
+}
+
+export function paramNodes(nodes: OpParamNode[]): ParamSource {
+    return { kind: 'params', nodes };
+}
+
+export function paramRef(name: string): ParamSource {
+    return { kind: 'ref', name };
+}
+
+export function paramType(node: ContractTypeNode): ParamSource {
+    return { kind: 'type', node };
+}
+
+export function opRequest(bodyType: string | ContractTypeNode, contentType: string = 'application/json'): OpRequestNode {
+    const bt: ContractTypeNode = typeof bodyType === 'string' ? refType(bodyType) : bodyType;
+    return { bodies: [{ contentType, bodyType: bt }] };
+}
+
+export function opMultiRequest(entries: Array<[string, string | ContractTypeNode]>): OpRequestNode {
+    return {
+        bodies: entries.map(([contentType, body]) => ({
+            contentType,
+            bodyType: typeof body === 'string' ? refType(body) : body,
+        })),
+    };
+}
+
+export function opResponse(statusCode: number, bodyType?: string | ContractTypeNode, contentType?: string): OpResponseNode {
+    const bt: ContractTypeNode | undefined =
+        bodyType === undefined ? undefined : typeof bodyType === 'string' ? parseBodyTypeString(bodyType) : bodyType;
+    return { statusCode, contentType, bodyType: bt };
+}
+
+function parseBodyTypeString(s: string): ContractTypeNode {
+    const arrayMatch = s.match(/^array\((.+)\)$/);
+    if (arrayMatch?.[1]) {
+        return { kind: 'array', item: refType(arrayMatch[1]) };
+    }
+    return refType(s);
+}
+
+/** Normalize a raw param value (old bare format or new discriminated union) to ParamSource. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function normalizeParamSource(value: any): ParamSource {
+    if (!value) return value;
+    if (typeof value === 'string') return { kind: 'ref', name: value };
+    if (Array.isArray(value)) return { kind: 'params', nodes: value };
+    if (value.kind === 'params' || value.kind === 'ref' || value.kind === 'type') return value as ParamSource;
+    return { kind: 'type', node: value as ContractTypeNode };
+}
+
+export function opOperation(method: HttpMethod, overrides?: Partial<OpOperationNode> & { query?: unknown; headers?: unknown }): OpOperationNode {
+    const normalized = { ...overrides } as Partial<OpOperationNode>;
+    if (overrides?.query !== undefined) normalized.query = normalizeParamSource(overrides.query);
+    if (overrides?.headers !== undefined) normalized.headers = normalizeParamSource(overrides.headers);
+    return {
+        method,
+        responses: [],
+        loc: loc(1, 'test.op'),
+        ...normalized,
+    };
+}
+
+export function opRoute(
+    path: string,
+    operations: OpOperationNode[],
+    params?: ParamSource | OpParamNode[] | string,
+    modifiers?: RouteModifier[],
+): OpRouteNode {
+    const normalizedParams = params !== undefined ? normalizeParamSource(params) : undefined;
+    return { path, params: normalizedParams, operations, modifiers, loc: loc(1, 'test.op') };
+}
+
+export function opRoot(routes: OpRouteNode[], file = 'users.op', meta: Record<string, string> = {}): OpRootNode {
+    return { kind: 'opRoot', meta, routes, file };
+}
+
+// ─── DSL Fixture Strings ────────────────────────────────────────────────────
+
+export const SIMPLE_USER_CONTRACT = `\
+contract User: {
+    id: readonly uuid
+    name: string
+    email: email
+    age?: number
+    active: boolean = true
+}
+`;
+
+export const VISIBILITY_CONTRACT = `\
+contract User: {
+    id: readonly uuid
+    name: string
+    password: writeonly string
+}
+`;
+
+export const INHERITANCE_CONTRACT = `\
+contract Admin: User & {
+    role: enum(admin, superadmin)
+}
+`;
+
+export const SIMPLE_USERS_OP = `\
+operation /users: {
+    get: {
+        response: {
+            200: {
+                application/json: array(User)
+            }
+        }
+    }
+    post: {
+        request: {
+            application/json: CreateUserInput
+        }
+        response: {
+            201: {
+                application/json: User
+            }
+        }
+    }
+}
+`;
+
+export const PARAMETERIZED_OP = `\
+operation /users/{id}: {
+    params: {
+        id: uuid
+    }
+    get: {
+        response: {
+            200: {
+                application/json: User
+            }
+        }
+    }
+    delete: {}
+}
+`;