@contractkit/openapi-to-ck 0.7.1

package/tests/normalize.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect } from 'vitest';
+import { normalize } from '../src/normalize.js';
+import { WarningCollector } from '../src/warnings.js';
+
+describe('normalize', () => {
+    describe('Swagger 2.0', () => {
+        it('converts definitions to components/schemas', () => {
+            const doc = {
+                swagger: '2.0',
+                info: { title: 'Test', version: '1.0' },
+                definitions: {
+                    User: { type: 'object', properties: { id: { type: 'string' } } },
+                },
+                paths: {},
+            };
+            const result = normalize(doc, new WarningCollector());
+            expect(result.openapi).toBe('3.1.0');
+            expect(result.components?.schemas?.User).toBeDefined();
+            expect((result.components!.schemas!.User as Record<string, unknown>).type).toBe('object');
+        });
+
+        it('converts body parameters to requestBody', () => {
+            const doc = {
+                swagger: '2.0',
+                info: { title: 'Test', version: '1.0' },
+                definitions: {},
+                paths: {
+                    '/users': {
+                        post: {
+                            parameters: [{ in: 'body', name: 'body', schema: { $ref: '#/definitions/User' } }],
+                            responses: { '200': { description: 'OK' } },
+                        },
+                    },
+                },
+            };
+            const result = normalize(doc, new WarningCollector());
+            const post = (result.paths!['/users'] as Record<string, unknown>).post as Record<string, unknown>;
+            expect(post.requestBody).toBeDefined();
+            const reqBody = post.requestBody as Record<string, unknown>;
+            expect(reqBody.content).toHaveProperty('application/json');
+        });
+
+        it('converts securityDefinitions to components/securitySchemes', () => {
+            const doc = {
+                swagger: '2.0',
+                info: { title: 'Test', version: '1.0' },
+                definitions: {},
+                securityDefinitions: {
+                    BasicAuth: { type: 'basic' },
+                    ApiKey: { type: 'apiKey', name: 'X-API-Key', in: 'header' },
+                },
+                paths: {},
+            };
+            const result = normalize(doc, new WarningCollector());
+            const schemes = result.components!.securitySchemes!;
+            expect((schemes.BasicAuth as Record<string, unknown>).type).toBe('http');
+            expect((schemes.ApiKey as Record<string, unknown>).type).toBe('apiKey');
+        });
+
+        it('builds server from host, basePath, schemes', () => {
+            const doc = {
+                swagger: '2.0',
+                info: { title: 'Test', version: '1.0' },
+                host: 'api.example.com',
+                basePath: '/v1',
+                schemes: ['https'],
+                paths: {},
+            };
+            const result = normalize(doc, new WarningCollector());
+            expect(result.servers![0]!.url).toBe('https://api.example.com/v1');
+        });
+    });
+
+    describe('OpenAPI 3.0', () => {
+        it('converts nullable: true to type array', () => {
+            const doc = {
+                openapi: '3.0.3',
+                info: { title: 'Test', version: '1.0' },
+                components: {
+                    schemas: {
+                        User: {
+                            type: 'object',
+                            properties: {
+                                name: { type: 'string', nullable: true },
+                            },
+                        },
+                    },
+                },
+            };
+            const result = normalize(doc as Record<string, unknown>, new WarningCollector());
+            expect(result.openapi).toBe('3.1.0');
+            const nameSchema = (result.components!.schemas!.User as Record<string, Record<string, unknown>>).properties!.name;
+            expect(nameSchema.type).toEqual(['string', 'null']);
+            expect(nameSchema.nullable).toBeUndefined();
+        });
+    });
+
+    describe('OpenAPI 3.1', () => {
+        it('passes through 3.1 documents unchanged', () => {
+            const doc = {
+                openapi: '3.1.0',
+                info: { title: 'Test', version: '1.0' },
+                components: {
+                    schemas: {
+                        User: { type: 'object', properties: { id: { type: 'string' } } },
+                    },
+                },
+            };
+            const result = normalize(doc as Record<string, unknown>, new WarningCollector());
+            expect(result.openapi).toBe('3.1.0');
+            expect(result.components?.schemas?.User).toBeDefined();
+        });
+    });
+});

package/tests/schema-to-ast.test.ts

@@ -0,0 +1,341 @@
+import { describe, it, expect } from 'vitest';
+import { schemaToTypeNode, schemasToModels, sanitizeName } from '../src/schema-to-ast.js';
+import type { SchemaContext } from '../src/schema-to-ast.js';
+import { WarningCollector } from '../src/warnings.js';
+import type { NormalizedSchema } from '../src/types.js';
+
+function makeCtx(overrides?: Partial<SchemaContext>): SchemaContext {
+    return {
+        circularRefs: new Set(),
+        warnings: new WarningCollector(),
+        path: '#/test',
+        includeComments: true,
+        namedSchemas: {},
+        extractedModels: [],
+        inlineCounter: 0,
+        ...overrides,
+    };
+}
+
+describe('schemaToTypeNode', () => {
+    describe('scalar types', () => {
+        it('converts string → string', () => {
+            const result = schemaToTypeNode({ type: 'string' }, makeCtx());
+            expect(result).toEqual({ kind: 'scalar', name: 'string' });
+        });
+
+        it('converts string with format email → email', () => {
+            const result = schemaToTypeNode({ type: 'string', format: 'email' }, makeCtx());
+            expect(result).toEqual({ kind: 'scalar', name: 'email' });
+        });
+
+        it('converts string with format uri → url', () => {
+            const result = schemaToTypeNode({ type: 'string', format: 'uri' }, makeCtx());
+            expect(result).toEqual({ kind: 'scalar', name: 'url' });
+        });
+
+        it('converts string with format uuid → uuid', () => {
+            const result = schemaToTypeNode({ type: 'string', format: 'uuid' }, makeCtx());
+            expect(result).toEqual({ kind: 'scalar', name: 'uuid' });
+        });
+
+        it('converts string with format date → date', () => {
+            const result = schemaToTypeNode({ type: 'string', format: 'date' }, makeCtx());
+            expect(result).toEqual({ kind: 'scalar', name: 'date' });
+        });
+
+        it('converts string with format date-time → datetime', () => {
+            const result = schemaToTypeNode({ type: 'string', format: 'date-time' }, makeCtx());
+            expect(result).toEqual({ kind: 'scalar', name: 'datetime' });
+        });
+
+        it('converts string with format binary → binary', () => {
+            const result = schemaToTypeNode({ type: 'string', format: 'binary' }, makeCtx());
+            expect(result).toEqual({ kind: 'scalar', name: 'binary' });
+        });
+
+        it('converts string with minLength/maxLength', () => {
+            const result = schemaToTypeNode({ type: 'string', minLength: 1, maxLength: 100 }, makeCtx());
+            expect(result).toEqual({ kind: 'scalar', name: 'string', min: 1, max: 100 });
+        });
+
+        it('converts string with equal min/max to len', () => {
+            const result = schemaToTypeNode({ type: 'string', minLength: 3, maxLength: 3 }, makeCtx());
+            expect(result).toEqual({ kind: 'scalar', name: 'string', len: 3 });
+        });
+
+        it('converts string with pattern', () => {
+            const result = schemaToTypeNode({ type: 'string', pattern: '^[a-z]+$' }, makeCtx());
+            expect(result).toEqual({ kind: 'scalar', name: 'string', regex: '/^[a-z]+$/' });
+        });
+
+        it('converts integer → int', () => {
+            const result = schemaToTypeNode({ type: 'integer' }, makeCtx());
+            expect(result).toEqual({ kind: 'scalar', name: 'int' });
+        });
+
+        it('converts integer with format int64 → bigint', () => {
+            const result = schemaToTypeNode({ type: 'integer', format: 'int64' }, makeCtx());
+            expect(result).toEqual({ kind: 'scalar', name: 'bigint' });
+        });
+
+        it('converts integer with min/max', () => {
+            const result = schemaToTypeNode({ type: 'integer', minimum: 0, maximum: 100 }, makeCtx());
+            expect(result).toEqual({ kind: 'scalar', name: 'int', min: 0, max: 100 });
+        });
+
+        it('converts number → number', () => {
+            const result = schemaToTypeNode({ type: 'number' }, makeCtx());
+            expect(result).toEqual({ kind: 'scalar', name: 'number' });
+        });
+
+        it('converts boolean → boolean', () => {
+            const result = schemaToTypeNode({ type: 'boolean' }, makeCtx());
+            expect(result).toEqual({ kind: 'scalar', name: 'boolean' });
+        });
+    });
+
+    describe('compound types', () => {
+        it('converts array with items', () => {
+            const result = schemaToTypeNode(
+                {
+                    type: 'array',
+                    items: { type: 'string' },
+                },
+                makeCtx(),
+            );
+            expect(result).toEqual({
+                kind: 'array',
+                item: { kind: 'scalar', name: 'string' },
+            });
+        });
+
+        it('converts array with min/maxItems', () => {
+            const result = schemaToTypeNode(
+                {
+                    type: 'array',
+                    items: { type: 'string' },
+                    minItems: 1,
+                    maxItems: 10,
+                },
+                makeCtx(),
+            );
+            expect(result).toEqual({
+                kind: 'array',
+                item: { kind: 'scalar', name: 'string' },
+                min: 1,
+                max: 10,
+            });
+        });
+
+        it('converts prefixItems to tuple', () => {
+            const result = schemaToTypeNode(
+                {
+                    type: 'array',
+                    prefixItems: [{ type: 'string' }, { type: 'integer' }],
+                },
+                makeCtx(),
+            );
+            expect(result).toEqual({
+                kind: 'tuple',
+                items: [
+                    { kind: 'scalar', name: 'string' },
+                    { kind: 'scalar', name: 'int' },
+                ],
+            });
+        });
+
+        it('converts object with additionalProperties to record', () => {
+            const result = schemaToTypeNode(
+                {
+                    type: 'object',
+                    additionalProperties: { type: 'integer' },
+                },
+                makeCtx(),
+            );
+            expect(result).toEqual({
+                kind: 'record',
+                key: { kind: 'scalar', name: 'string' },
+                value: { kind: 'scalar', name: 'int' },
+            });
+        });
+
+        it('converts enum', () => {
+            const result = schemaToTypeNode({ enum: ['asc', 'desc'] }, makeCtx());
+            expect(result).toEqual({ kind: 'enum', values: ['asc', 'desc'] });
+        });
+
+        it('converts const', () => {
+            const result = schemaToTypeNode({ const: 'hello' }, makeCtx());
+            expect(result).toEqual({ kind: 'literal', value: 'hello' });
+        });
+    });
+
+    describe('combiners', () => {
+        it('converts oneOf to union', () => {
+            const result = schemaToTypeNode(
+                {
+                    oneOf: [{ type: 'string' }, { type: 'integer' }],
+                },
+                makeCtx(),
+            );
+            expect(result).toEqual({
+                kind: 'union',
+                members: [
+                    { kind: 'scalar', name: 'string' },
+                    { kind: 'scalar', name: 'int' },
+                ],
+            });
+        });
+
+        it('converts anyOf to union', () => {
+            const result = schemaToTypeNode(
+                {
+                    anyOf: [{ type: 'string' }, { type: 'number' }],
+                },
+                makeCtx(),
+            );
+            expect(result).toEqual({
+                kind: 'union',
+                members: [
+                    { kind: 'scalar', name: 'string' },
+                    { kind: 'scalar', name: 'number' },
+                ],
+            });
+        });
+
+        it('converts allOf to intersection', () => {
+            const result = schemaToTypeNode(
+                {
+                    allOf: [
+                        { type: 'object', properties: { a: { type: 'string' } } },
+                        { type: 'object', properties: { b: { type: 'integer' } } },
+                    ],
+                },
+                makeCtx(),
+            );
+            expect(result.kind).toBe('intersection');
+        });
+    });
+
+    describe('references', () => {
+        it('converts $ref to model ref', () => {
+            const result = schemaToTypeNode({ $ref: '#/components/schemas/User' }, makeCtx());
+            expect(result).toEqual({ kind: 'ref', name: 'User' });
+        });
+
+        it('wraps circular $ref in lazy', () => {
+            const ctx = makeCtx({ circularRefs: new Set(['TreeNode']) });
+            const result = schemaToTypeNode({ $ref: '#/components/schemas/TreeNode' }, ctx);
+            expect(result).toEqual({ kind: 'lazy', inner: { kind: 'ref', name: 'TreeNode' } });
+        });
+    });
+
+    describe('nullable', () => {
+        it('converts type array with null to union', () => {
+            const result = schemaToTypeNode({ type: ['string', 'null'] } as NormalizedSchema, makeCtx());
+            expect(result).toEqual({
+                kind: 'union',
+                members: [
+                    { kind: 'scalar', name: 'string' },
+                    { kind: 'scalar', name: 'null' },
+                ],
+            });
+        });
+    });
+
+    describe('edge cases', () => {
+        it('handles schema with no type', () => {
+            const result = schemaToTypeNode({}, makeCtx());
+            expect(result).toEqual({ kind: 'scalar', name: 'unknown' });
+        });
+
+        it('handles empty object type', () => {
+            const result = schemaToTypeNode({ type: 'object' }, makeCtx());
+            expect(result).toEqual({ kind: 'scalar', name: 'object' });
+        });
+    });
+});
+
+describe('schemasToModels', () => {
+    it('converts object schemas to models with fields', () => {
+        const schemas = {
+            User: {
+                type: 'object',
+                properties: {
+                    id: { type: 'string', format: 'uuid', readOnly: true },
+                    name: { type: 'string', minLength: 1, maxLength: 100 },
+                    email: { type: 'string', format: 'email' },
+                    bio: { type: 'string', description: 'User bio' },
+                },
+                required: ['id', 'name', 'email'],
+            },
+        };
+        const ctx = makeCtx({ namedSchemas: schemas as Record<string, NormalizedSchema> });
+        const models = schemasToModels(schemas as Record<string, NormalizedSchema>, ctx);
+
+        expect(models.length).toBe(1);
+        const user = models[0]!;
+        expect(user.name).toBe('User');
+        expect(user.fields.length).toBe(4);
+
+        const idField = user.fields.find(f => f.name === 'id')!;
+        expect(idField.visibility).toBe('readonly');
+        expect(idField.optional).toBe(false);
+
+        const bioField = user.fields.find(f => f.name === 'bio')!;
+        expect(bioField.optional).toBe(true);
+        expect(bioField.description).toBe('User bio');
+    });
+
+    it('converts type aliases', () => {
+        const schemas = {
+            UserId: { type: 'string', format: 'uuid' },
+        };
+        const ctx = makeCtx({ namedSchemas: schemas as Record<string, NormalizedSchema> });
+        const models = schemasToModels(schemas as Record<string, NormalizedSchema>, ctx);
+
+        expect(models.length).toBe(1);
+        expect(models[0]!.name).toBe('UserId');
+        expect(models[0]!.type).toEqual({ kind: 'scalar', name: 'uuid' });
+        expect(models[0]!.fields.length).toBe(0);
+    });
+
+    it('converts allOf with $ref to inheritance', () => {
+        const schemas = {
+            User: {
+                type: 'object',
+                properties: { id: { type: 'string' } },
+                required: ['id'],
+            },
+            Admin: {
+                allOf: [{ $ref: '#/components/schemas/User' }, { type: 'object', properties: { role: { type: 'string' } } }],
+            },
+        };
+        const ctx = makeCtx({ namedSchemas: schemas as Record<string, NormalizedSchema> });
+        const models = schemasToModels(schemas as Record<string, NormalizedSchema>, ctx);
+
+        const admin = models.find(m => m.name === 'Admin')!;
+        expect(admin.bases).toEqual(['User']);
+        expect(admin.fields.length).toBe(1);
+        expect(admin.fields[0]!.name).toBe('role');
+    });
+});
+
+describe('sanitizeName', () => {
+    it('passes through valid names', () => {
+        expect(sanitizeName('User', new WarningCollector())).toBe('User');
+    });
+
+    it('sanitizes names with dots', () => {
+        expect(sanitizeName('user.response', new WarningCollector())).toBe('UserResponse');
+    });
+
+    it('sanitizes names with hyphens', () => {
+        expect(sanitizeName('my-model', new WarningCollector())).toBe('MyModel');
+    });
+
+    it('sanitizes names with spaces', () => {
+        expect(sanitizeName('some model', new WarningCollector())).toBe('SomeModel');
+    });
+});

package/tests/tag-splitter.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect } from 'vitest';
+import { splitByTag, mergeIntoSingle } from '../src/tag-splitter.js';
+import { model, field, scalarType, refType, arrayType, opRoute, opOperation, opResponse } from './helpers.js';
+import type { OpRouteNode } from '@contractkit/core';
+
+describe('splitByTag', () => {
+    it('splits routes into separate files by tag', () => {
+        const userModel = model('User', [field('id', scalarType('uuid'))]);
+        const postModel = model('Post', [field('id', scalarType('uuid')), field('author', refType('User'))]);
+
+        const userRoute = opRoute('/users', [opOperation('get', { responses: [opResponse(200, arrayType(refType('User')), 'application/json')] })]);
+        const postRoute = opRoute('/posts', [opOperation('get', { responses: [opResponse(200, arrayType(refType('Post')), 'application/json')] })]);
+
+        const routeTags = new Map<OpRouteNode, string>([
+            [userRoute, 'users'],
+            [postRoute, 'posts'],
+        ]);
+
+        const result = splitByTag([userModel, postModel], [userRoute, postRoute], routeTags);
+
+        expect(result.has('users.ck')).toBe(true);
+        expect(result.has('posts.ck')).toBe(true);
+
+        const usersFile = result.get('users.ck')!;
+        expect(usersFile.routes).toContain(userRoute);
+        expect(usersFile.models.some(m => m.name === 'User')).toBe(true);
+
+        const postsFile = result.get('posts.ck')!;
+        expect(postsFile.routes).toContain(postRoute);
+        expect(postsFile.models.some(m => m.name === 'Post')).toBe(true);
+    });
+
+    it('puts models referenced by multiple tags in shared.ck', () => {
+        const sharedModel = model('Pagination', [field('page', scalarType('int'))]);
+
+        const route1 = opRoute('/users', [opOperation('get', { query: 'Pagination', responses: [] })]);
+        const route2 = opRoute('/posts', [opOperation('get', { query: 'Pagination', responses: [] })]);
+
+        const routeTags = new Map<OpRouteNode, string>([
+            [route1, 'users'],
+            [route2, 'posts'],
+        ]);
+
+        const result = splitByTag([sharedModel], [route1, route2], routeTags);
+        expect(result.has('shared.ck')).toBe(true);
+        expect(result.get('shared.ck')!.models.some(m => m.name === 'Pagination')).toBe(true);
+    });
+
+    it('puts orphan models in shared.ck', () => {
+        const orphan = model('Config', [field('key', scalarType('string'))]);
+        const result = splitByTag([orphan], [], new Map());
+        expect(result.has('shared.ck')).toBe(true);
+        expect(result.get('shared.ck')!.models.some(m => m.name === 'Config')).toBe(true);
+    });
+
+    it('assigns untagged routes to default.ck', () => {
+        const route = opRoute('/health', [opOperation('get', { responses: [opResponse(200)] })]);
+        const routeTags = new Map<OpRouteNode, string>([[route, 'default']]);
+
+        const result = splitByTag([], [route], routeTags);
+        expect(result.has('default.ck')).toBe(true);
+    });
+});
+
+describe('mergeIntoSingle', () => {
+    it('merges all models and routes into one CkRootNode', () => {
+        const models = [model('User', [field('id', scalarType('uuid'))])];
+        const routes = [opRoute('/users', [opOperation('get', { responses: [] })])];
+
+        const result = mergeIntoSingle(models, routes);
+        expect(result.models).toBe(models);
+        expect(result.routes).toBe(routes);
+        expect(result.file).toBe('api.ck');
+    });
+});

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+    "extends": "@repo/config-typescript/base.json",
+    "compilerOptions": {
+        "outDir": "./dist",
+        "rootDir": "./src"
+    },
+    "include": ["src/**/*"],
+    "exclude": ["node_modules", "dist"]
+}