@contractkit/openapi-to-ck 0.7.1

package/tests/convert.test.ts

@@ -0,0 +1,330 @@
+import { describe, it, expect } from 'vitest';
+import { parseCk, DiagnosticCollector } from '@contractkit/core';
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { convertOpenApiToCk } from '../src/convert.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const fixturesDir = resolve(__dirname, 'fixtures');
+
+describe('convertOpenApiToCk', () => {
+    describe('OpenAPI 3.1 Petstore', () => {
+        it('converts to split .ck files by tag', async () => {
+            const spec = JSON.parse(readFileSync(resolve(fixturesDir, 'petstore-3.1.json'), 'utf-8'));
+            const result = await convertOpenApiToCk({ input: spec, split: 'by-tag' });
+
+            expect(result.files.size).toBeGreaterThan(0);
+
+            // Should have pets and store files
+            const filenames = [...result.files.keys()];
+            expect(filenames.some(f => f.includes('pets'))).toBe(true);
+            expect(filenames.some(f => f.includes('store'))).toBe(true);
+        });
+
+        it('includes Pet model in pets file', async () => {
+            const spec = JSON.parse(readFileSync(resolve(fixturesDir, 'petstore-3.1.json'), 'utf-8'));
+            const result = await convertOpenApiToCk({ input: spec, split: 'by-tag' });
+
+            const petsFile = [...result.files.entries()].find(([k]) => k.includes('pets'));
+            expect(petsFile).toBeDefined();
+            const [, content] = petsFile!;
+
+            expect(content).toContain('contract Pet:');
+            expect(content).toContain('id: readonly uuid');
+            expect(content).toContain('name: string(min=1, max=100)');
+            expect(content).toContain('status: enum(available, pending, sold)');
+            expect(content).toContain('createdAt: readonly datetime');
+        });
+
+        it('includes operations in pets file', async () => {
+            const spec = JSON.parse(readFileSync(resolve(fixturesDir, 'petstore-3.1.json'), 'utf-8'));
+            const result = await convertOpenApiToCk({ input: spec, split: 'by-tag' });
+
+            const petsFile = [...result.files.entries()].find(([k]) => k.includes('pets'));
+            const [, content] = petsFile!;
+
+            expect(content).toContain('operation /pets:');
+            expect(content).toContain('get:');
+            expect(content).toContain('post:');
+            expect(content).toContain('operation /pets/{petId}:');
+            expect(content).toContain('sdk: listPets');
+            expect(content).toContain('sdk: createPet');
+        });
+
+        it('marks delete with security: none', async () => {
+            const spec = JSON.parse(readFileSync(resolve(fixturesDir, 'petstore-3.1.json'), 'utf-8'));
+            const result = await convertOpenApiToCk({ input: spec, split: 'by-tag' });
+
+            const petsFile = [...result.files.entries()].find(([k]) => k.includes('pets'));
+            const [, content] = petsFile!;
+
+            expect(content).toContain('security: none');
+        });
+
+        it('converts to single file', async () => {
+            const spec = JSON.parse(readFileSync(resolve(fixturesDir, 'petstore-3.1.json'), 'utf-8'));
+            const result = await convertOpenApiToCk({ input: spec, split: 'single' });
+
+            expect(result.files.size).toBe(1);
+            expect(result.files.has('api.ck')).toBe(true);
+
+            const content = result.files.get('api.ck')!;
+            expect(content).toContain('contract Pet:');
+            expect(content).toContain('operation /pets:');
+            expect(content).toContain('operation /store/inventory:');
+        });
+
+        it('includes descriptions as comments', async () => {
+            const spec = JSON.parse(readFileSync(resolve(fixturesDir, 'petstore-3.1.json'), 'utf-8'));
+            const result = await convertOpenApiToCk({ input: spec, split: 'single', includeComments: true });
+
+            const content = result.files.get('api.ck')!;
+            expect(content).toContain('# A pet in the store');
+            expect(content).toContain('# The pet identifier');
+        });
+
+        it('omits comments when includeComments is false', async () => {
+            const spec = JSON.parse(readFileSync(resolve(fixturesDir, 'petstore-3.1.json'), 'utf-8'));
+            const result = await convertOpenApiToCk({ input: spec, split: 'single', includeComments: false });
+
+            const content = result.files.get('api.ck')!;
+            expect(content).not.toContain('#');
+        });
+
+        it('handles path params', async () => {
+            const spec = JSON.parse(readFileSync(resolve(fixturesDir, 'petstore-3.1.json'), 'utf-8'));
+            const result = await convertOpenApiToCk({ input: spec, split: 'single' });
+
+            const content = result.files.get('api.ck')!;
+            expect(content).toContain('params: {');
+            expect(content).toContain('petId: uuid');
+        });
+
+        it('handles record types (additionalProperties)', async () => {
+            const spec = JSON.parse(readFileSync(resolve(fixturesDir, 'petstore-3.1.json'), 'utf-8'));
+            const result = await convertOpenApiToCk({ input: spec, split: 'single' });
+
+            const content = result.files.get('api.ck')!;
+            // Store inventory returns a record
+            expect(content).toContain('record(string, int)');
+        });
+
+        it('handles empty responses (204)', async () => {
+            const spec = JSON.parse(readFileSync(resolve(fixturesDir, 'petstore-3.1.json'), 'utf-8'));
+            const result = await convertOpenApiToCk({ input: spec, split: 'single' });
+
+            const content = result.files.get('api.ck')!;
+            expect(content).toContain('204:');
+        });
+    });
+
+    describe('inline spec object', () => {
+        it('converts a minimal spec', async () => {
+            const result = await convertOpenApiToCk({
+                input: {
+                    openapi: '3.1.0',
+                    info: { title: 'Minimal', version: '1.0' },
+                    components: {
+                        schemas: {
+                            Ping: { type: 'object', properties: { ok: { type: 'boolean' } }, required: ['ok'] },
+                        },
+                    },
+                    paths: {
+                        '/ping': {
+                            get: {
+                                operationId: 'ping',
+                                responses: {
+                                    '200': {
+                                        description: 'OK',
+                                        content: { 'application/json': { schema: { $ref: '#/components/schemas/Ping' } } },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+                split: 'single',
+            });
+
+            expect(result.files.size).toBe(1);
+            const content = result.files.get('api.ck')!;
+            expect(content).toContain('contract Ping:');
+            expect(content).toContain('ok: boolean');
+            expect(content).toContain('operation /ping:');
+        });
+    });
+
+    describe('response headers', () => {
+        it('lifts OpenAPI 3.x response headers into a typed headers block', async () => {
+            const result = await convertOpenApiToCk({
+                input: {
+                    openapi: '3.1.0',
+                    info: { title: 'T', version: '1.0' },
+                    components: {
+                        schemas: {
+                            Transfer: { type: 'object', properties: { id: { type: 'string', format: 'uuid' } }, required: ['id'] },
+                        },
+                    },
+                    paths: {
+                        '/transfers/{id}': {
+                            parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string', format: 'uuid' } }],
+                            get: {
+                                operationId: 'getTransfer',
+                                responses: {
+                                    '200': {
+                                        description: 'OK',
+                                        content: { 'application/json': { schema: { $ref: '#/components/schemas/Transfer' } } },
+                                        headers: {
+                                            'preference-applied': { schema: { type: 'string' } },
+                                            ETag: { description: 'cache validator', required: true, schema: { type: 'string' } },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+                split: 'single',
+            });
+            const ck = result.files.get('api.ck')!;
+            expect(ck).toContain('200: {');
+            expect(ck).toContain('application/json: Transfer');
+            expect(ck).toContain('headers: {');
+            expect(ck).toContain('preference-applied?: string');
+            expect(ck).toContain('ETag: string # cache validator');
+
+            // Round-trip: the generated .ck must parse cleanly back into an AST with the same headers.
+            const diag = new DiagnosticCollector();
+            const root = parseCk(ck, 'api.ck', diag);
+            expect(diag.hasErrors()).toBe(false);
+            const op = root.routes[0]!.operations[0]!;
+            const respHeaders = op.responses[0]!.headers!;
+            expect(respHeaders.map(h => h.name)).toEqual(['preference-applied', 'ETag']);
+            expect(respHeaders[0]!.optional).toBe(true);
+            expect(respHeaders[1]!.optional).toBe(false);
+        });
+
+        it('lifts response headers when the status has no body', async () => {
+            const result = await convertOpenApiToCk({
+                input: {
+                    openapi: '3.1.0',
+                    info: { title: 'T', version: '1.0' },
+                    paths: {
+                        '/resources/{id}': {
+                            parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string' } }],
+                            delete: {
+                                operationId: 'deleteResource',
+                                responses: {
+                                    '204': {
+                                        description: 'No Content',
+                                        headers: {
+                                            'x-deleted-at': { required: true, schema: { type: 'string' } },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+                split: 'single',
+            });
+            const ck = result.files.get('api.ck')!;
+            expect(ck).toContain('204: {');
+            expect(ck).toContain('headers: {');
+            expect(ck).toContain('x-deleted-at: string');
+        });
+
+        it('lifts Swagger 2.0 response headers via normalize', async () => {
+            const result = await convertOpenApiToCk({
+                input: {
+                    swagger: '2.0',
+                    info: { title: 'T', version: '1.0' },
+                    paths: {
+                        '/things': {
+                            get: {
+                                operationId: 'listThings',
+                                produces: ['application/json'],
+                                responses: {
+                                    '200': {
+                                        description: 'OK',
+                                        schema: { type: 'array', items: { type: 'string' } },
+                                        headers: {
+                                            'X-Rate-Limit': { type: 'integer', description: 'requests left' },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+                split: 'single',
+            });
+            const ck = result.files.get('api.ck')!;
+            expect(ck).toContain('headers: {');
+            expect(ck).toContain('X-Rate-Limit?: int');
+            expect(ck).toContain('requests left');
+        });
+    });
+
+    describe('warnings', () => {
+        it('collects warnings for unsupported features', async () => {
+            const warnings: string[] = [];
+            await convertOpenApiToCk({
+                input: {
+                    openapi: '3.1.0',
+                    info: { title: 'Test', version: '1.0' },
+                    components: {
+                        schemas: {
+                            WithXml: {
+                                type: 'object',
+                                xml: { name: 'thing' },
+                                properties: { id: { type: 'string' } },
+                            },
+                        },
+                    },
+                    paths: {},
+                },
+                split: 'single',
+                onWarning: w => warnings.push(w.message),
+            });
+
+            expect(warnings.some(w => w.includes('xml'))).toBe(true);
+        });
+
+        it('lowers oneOf with discriminator to a discriminatedUnion', async () => {
+            const warnings: string[] = [];
+            const result = await convertOpenApiToCk({
+                input: {
+                    openapi: '3.1.0',
+                    info: { title: 'Test', version: '1.0' },
+                    components: {
+                        schemas: {
+                            Card: {
+                                type: 'object',
+                                properties: { kind: { type: 'string', enum: ['card'] }, last4: { type: 'string' } },
+                                required: ['kind', 'last4'],
+                            },
+                            Bank: {
+                                type: 'object',
+                                properties: { kind: { type: 'string', enum: ['bank'] }, accountId: { type: 'string' } },
+                                required: ['kind', 'accountId'],
+                            },
+                            PaymentMethod: {
+                                oneOf: [{ $ref: '#/components/schemas/Card' }, { $ref: '#/components/schemas/Bank' }],
+                                discriminator: { propertyName: 'kind' },
+                            },
+                        },
+                    },
+                    paths: {},
+                },
+                split: 'single',
+                onWarning: w => warnings.push(w.message),
+            });
+
+            const content = result.files.get('api.ck')!;
+            expect(content).toContain('discriminated(by=kind');
+            expect(warnings.some(w => w.includes('discriminator'))).toBe(false);
+        });
+    });
+});

package/tests/fixtures/petstore-3.1.json

@@ -0,0 +1,187 @@
+{
+    "openapi": "3.1.0",
+    "info": {
+        "title": "Petstore",
+        "version": "1.0.0",
+        "description": "A sample pet store API"
+    },
+    "servers": [{ "url": "https://petstore.example.com/v1" }],
+    "paths": {
+        "/pets": {
+            "get": {
+                "operationId": "listPets",
+                "tags": ["pets"],
+                "summary": "List all pets",
+                "parameters": [
+                    {
+                        "name": "limit",
+                        "in": "query",
+                        "required": false,
+                        "schema": { "type": "integer", "minimum": 1, "maximum": 100 }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "A list of pets",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "array",
+                                    "items": { "$ref": "#/components/schemas/Pet" }
+                                }
+                            }
+                        }
+                    }
+                }
+            },
+            "post": {
+                "operationId": "createPet",
+                "tags": ["pets"],
+                "summary": "Create a pet",
+                "requestBody": {
+                    "required": true,
+                    "content": {
+                        "application/json": {
+                            "schema": { "$ref": "#/components/schemas/CreatePetInput" }
+                        }
+                    }
+                },
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "content": {
+                            "application/json": {
+                                "schema": { "$ref": "#/components/schemas/Pet" }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/pets/{petId}": {
+            "parameters": [
+                {
+                    "name": "petId",
+                    "in": "path",
+                    "required": true,
+                    "schema": { "type": "string", "format": "uuid" }
+                }
+            ],
+            "get": {
+                "operationId": "getPet",
+                "tags": ["pets"],
+                "summary": "Get a pet by ID",
+                "responses": {
+                    "200": {
+                        "description": "A pet",
+                        "content": {
+                            "application/json": {
+                                "schema": { "$ref": "#/components/schemas/Pet" }
+                            }
+                        }
+                    },
+                    "404": {
+                        "description": "Pet not found"
+                    }
+                }
+            },
+            "delete": {
+                "operationId": "deletePet",
+                "tags": ["pets"],
+                "summary": "Delete a pet",
+                "security": [],
+                "responses": {
+                    "204": {
+                        "description": "Deleted"
+                    }
+                }
+            }
+        },
+        "/store/inventory": {
+            "get": {
+                "operationId": "getInventory",
+                "tags": ["store"],
+                "summary": "Returns pet inventories",
+                "responses": {
+                    "200": {
+                        "description": "Inventory map",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "additionalProperties": { "type": "integer" }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "components": {
+        "schemas": {
+            "Pet": {
+                "type": "object",
+                "description": "A pet in the store",
+                "properties": {
+                    "id": {
+                        "type": "string",
+                        "format": "uuid",
+                        "readOnly": true,
+                        "description": "The pet identifier"
+                    },
+                    "name": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 100,
+                        "description": "The pet name"
+                    },
+                    "tag": {
+                        "type": "string",
+                        "description": "Optional tag"
+                    },
+                    "status": {
+                        "type": "string",
+                        "enum": ["available", "pending", "sold"],
+                        "description": "Pet status"
+                    },
+                    "createdAt": {
+                        "type": "string",
+                        "format": "date-time",
+                        "readOnly": true,
+                        "description": "Creation timestamp"
+                    }
+                },
+                "required": ["id", "name", "status", "createdAt"]
+            },
+            "CreatePetInput": {
+                "type": "object",
+                "description": "Input for creating a pet",
+                "properties": {
+                    "name": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 100
+                    },
+                    "tag": {
+                        "type": "string"
+                    },
+                    "status": {
+                        "type": "string",
+                        "enum": ["available", "pending", "sold"],
+                        "default": "available"
+                    }
+                },
+                "required": ["name", "status"]
+            },
+            "Error": {
+                "type": "object",
+                "properties": {
+                    "code": { "type": "integer" },
+                    "message": { "type": "string" }
+                },
+                "required": ["code", "message"]
+            }
+        }
+    }
+}

package/tests/helpers.ts

@@ -0,0 +1,158 @@
+import type {
+    CkRootNode,
+    ModelNode,
+    FieldNode,
+    ContractTypeNode,
+    ScalarTypeNode,
+    ArrayTypeNode,
+    TupleTypeNode,
+    RecordTypeNode,
+    EnumTypeNode,
+    LiteralTypeNode,
+    UnionTypeNode,
+    IntersectionTypeNode,
+    ModelRefTypeNode,
+    InlineObjectTypeNode,
+    LazyTypeNode,
+    SourceLocation,
+    OpRouteNode,
+    OpOperationNode,
+    OpParamNode,
+    OpRequestNode,
+    OpResponseNode,
+    HttpMethod,
+    ParamSource,
+    RouteModifier,
+    SecurityNode,
+} 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 intersectionType(...members: ContractTypeNode[]): IntersectionTypeNode {
+    return { kind: 'intersection', 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 ckRoot(overrides?: Partial<CkRootNode>): CkRootNode {
+    return {
+        kind: 'ckRoot',
+        meta: {},
+        services: {},
+        models: [],
+        routes: [],
+        file: 'test.ck',
+        ...overrides,
+    };
+}
+
+export function opParam(name: string, type: ContractTypeNode, overrides?: Partial<OpParamNode>): OpParamNode {
+    return { name, optional: false, nullable: false, type, loc: loc(), ...overrides };
+}
+
+export function opRequest(bodyType: ContractTypeNode, contentType: string = 'application/json'): OpRequestNode {
+    return {
+        bodies: [
+            {
+                contentType: contentType as OpRequestNode['bodies'][number]['contentType'],
+                bodyType,
+            },
+        ],
+    };
+}
+
+export function opResponse(statusCode: number, bodyType?: ContractTypeNode, contentType?: 'application/json'): OpResponseNode {
+    return { statusCode, contentType, bodyType };
+}
+
+/** 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(),
+        ...normalized,
+    };
+}
+
+export function opRoute(path: string, operations: OpOperationNode[], overrides?: Partial<OpRouteNode> & { params?: unknown }): OpRouteNode {
+    const normalized = { ...overrides } as Partial<OpRouteNode>;
+    if (overrides?.params !== undefined) normalized.params = normalizeParamSource(overrides.params);
+    return { path, operations, loc: loc(), ...normalized };
+}