vitek-plugin 0.1.2-beta → 0.1.2-beta.0

package/dist/core/openapi/generate.js

@@ -0,0 +1,464 @@
+/**
+ * OpenAPI/Swagger specification generation
+ * Core logic - no Vite dependencies
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+/** Default OpenAPI info values */
+const DEFAULT_OPENAPI_INFO = {
+    title: 'Vitek API',
+    version: '1.0.0',
+    description: 'Auto-generated API documentation',
+};
+/**
+ * Generates a complete OpenAPI 3.0 specification
+ */
+export function generateOpenApiSpec(routes, options) {
+    const info = { ...DEFAULT_OPENAPI_INFO, ...options.info };
+    const spec = {
+        openapi: '3.0.3',
+        info,
+        paths: generatePaths(routes, options),
+        components: {
+            schemas: generateSchemas(routes),
+        },
+    };
+    if (options.servers && options.servers.length > 0) {
+        spec.servers = options.servers;
+    }
+    return spec;
+}
+/**
+ * Generates OpenAPI paths from routes
+ */
+function generatePaths(routes, options) {
+    const paths = {};
+    for (const route of routes) {
+        const openApiPath = convertPatternToOpenApi(route.pattern);
+        const metadata = extractMetadataFromFile(route.file);
+        if (!paths[openApiPath]) {
+            paths[openApiPath] = {};
+        }
+        const pathItem = paths[openApiPath];
+        pathItem[route.method] = generateOperationObject(route, metadata, options);
+    }
+    return paths;
+}
+/**
+ * Converts Vitek pattern to OpenAPI path format
+ * Example: "users/:id" -> "/users/{id}"
+ * Example: "posts/*ids" -> "/posts/{ids}"
+ */
+function convertPatternToOpenApi(pattern) {
+    if (!pattern || pattern === '') {
+        return '/';
+    }
+    // Convert :param to {param} and *param to {param}
+    return '/' + pattern
+        .replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, '{$1}')
+        .replace(/\*([a-zA-Z_][a-zA-Z0-9_]*)/g, '{$1}');
+}
+/**
+ * Generates an OpenAPI Operation object for a route
+ */
+function generateOperationObject(route, metadata, options) {
+    const operation = {
+        operationId: generateOperationId(route),
+        summary: metadata.summary || `${route.method.toUpperCase()} ${route.pattern}`,
+    };
+    if (metadata.description) {
+        operation.description = metadata.description;
+    }
+    if (metadata.tags && metadata.tags.length > 0) {
+        operation.tags = metadata.tags;
+    }
+    if (metadata.deprecated) {
+        operation.deprecated = true;
+    }
+    // Parameters (path, query)
+    const parameters = [];
+    // Path parameters
+    for (const param of route.params) {
+        parameters.push({
+            name: param,
+            in: 'path',
+            required: true,
+            schema: { type: 'string' },
+            description: metadata.paramDescriptions?.[param] || undefined,
+        });
+    }
+    // Query parameters (if queryType exists)
+    if (route.queryType) {
+        const queryFields = extractTypeFields(route.queryType);
+        for (const field of queryFields) {
+            parameters.push({
+                name: field.name,
+                in: 'query',
+                required: field.required,
+                schema: field.schema,
+                description: field.description,
+            });
+        }
+    }
+    if (parameters.length > 0) {
+        operation.parameters = parameters;
+    }
+    // Request body (if bodyType exists and method supports body)
+    if (route.bodyType && ['post', 'put', 'patch'].includes(route.method)) {
+        operation.requestBody = {
+            description: metadata.bodyDescription || 'Request body',
+            required: true,
+            content: {
+                'application/json': {
+                    schema: typeToSchema(route.bodyType),
+                },
+            },
+        };
+    }
+    // Responses
+    operation.responses = generateResponses(route, metadata);
+    return operation;
+}
+/**
+ * Generates a unique operation ID from route
+ */
+function generateOperationId(route) {
+    const patternParts = route.pattern
+        .split('/')
+        .filter(Boolean)
+        .map(part => {
+        // Clean parameter markers
+        const clean = part.replace(/^[:*]/, '');
+        // Capitalize
+        return clean.charAt(0).toUpperCase() + clean.slice(1);
+    });
+    return route.method + patternParts.join('');
+}
+/**
+ * Generates OpenAPI responses object
+ */
+function generateResponses(route, metadata) {
+    const responses = {};
+    if (metadata.responses && Object.keys(metadata.responses).length > 0) {
+        // Use JSDoc @response annotations
+        for (const [code, responseMeta] of Object.entries(metadata.responses)) {
+            responses[code] = {
+                description: responseMeta.description,
+                content: responseMeta.type ? {
+                    'application/json': {
+                        schema: typeStringToJsonSchema(responseMeta.type),
+                        example: responseMeta.example,
+                    },
+                } : undefined,
+            };
+        }
+    }
+    else {
+        // Default responses based on method
+        switch (route.method) {
+            case 'get':
+                responses['200'] = {
+                    description: 'Successful response',
+                    content: {
+                        'application/json': {
+                            schema: { type: 'object' },
+                        },
+                    },
+                };
+                break;
+            case 'post':
+                responses['201'] = {
+                    description: 'Created successfully',
+                    content: {
+                        'application/json': {
+                            schema: { type: 'object' },
+                        },
+                    },
+                };
+                break;
+            case 'put':
+            case 'patch':
+                responses['200'] = {
+                    description: 'Updated successfully',
+                    content: {
+                        'application/json': {
+                            schema: { type: 'object' },
+                        },
+                    },
+                };
+                break;
+            case 'delete':
+                responses['204'] = {
+                    description: 'Deleted successfully',
+                };
+                break;
+        }
+    }
+    // Always add error responses
+    responses['400'] = { description: 'Bad request' };
+    responses['401'] = { description: 'Unauthorized' };
+    responses['404'] = { description: 'Not found' };
+    responses['500'] = { description: 'Internal server error' };
+    return responses;
+}
+/**
+ * Extracts metadata from JSDoc comments in a route file
+ */
+function extractMetadataFromFile(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const metadata = {};
+        // Find JSDoc comment before default export or handler
+        const jsdocRegex = /\/\*\*([\s\S]*?)\*\/\s*(?:export\s+default|export\s+(?:async\s+)?function|const\s+handler)/;
+        const match = content.match(jsdocRegex);
+        if (!match) {
+            return metadata;
+        }
+        const jsdoc = match[1];
+        // Extract @summary or first line as summary
+        const summaryMatch = jsdoc.match(/@summary\s+(.+)$/m);
+        if (summaryMatch) {
+            metadata.summary = summaryMatch[1].trim();
+        }
+        else {
+            // First non-tag line is description/summary
+            const descMatch = jsdoc.match(/\*\s+([^@\n].+)$/m);
+            if (descMatch) {
+                metadata.summary = descMatch[1].trim();
+            }
+        }
+        // Extract @description
+        const descriptionMatch = jsdoc.match(/@description\s+([\s\S]*?)(?=\s*@|\s*\*\/|$)/);
+        if (descriptionMatch) {
+            metadata.description = descriptionMatch[1]
+                .split('\n')
+                .map(line => line.replace(/^\s*\*\s?/, '').trim())
+                .join(' ')
+                .trim();
+        }
+        // Extract @tag
+        const tagMatches = jsdoc.matchAll(/@tag\s+(\w+)/g);
+        metadata.tags = Array.from(tagMatches).map(m => m[1]);
+        // Extract @deprecated
+        metadata.deprecated = /@deprecated/.test(jsdoc);
+        // Extract @response
+        const responseMatches = jsdoc.matchAll(/@response\s+(\d+)\s+(.+?)(?:\s+-\s*(\{[^}]+\}))?(?:\s+-\s*(.+))?$/gm);
+        metadata.responses = {};
+        for (const m of responseMatches) {
+            const code = m[1];
+            const description = m[2]?.trim();
+            const type = m[3]?.replace(/[{}]/g, '').trim();
+            const exampleStr = m[4]?.trim();
+            metadata.responses[code] = {
+                description,
+                type,
+                example: exampleStr ? tryParseJson(exampleStr) : undefined,
+            };
+        }
+        // Extract @param for parameter descriptions
+        const paramMatches = jsdoc.matchAll(/@param\s+(?:\{[^}]+\}\s+)?(\w+)\s+-\s*(.+)$/gm);
+        metadata.paramDescriptions = {};
+        for (const m of paramMatches) {
+            metadata.paramDescriptions[m[1]] = m[2].trim();
+        }
+        // Extract @bodyDescription
+        const bodyDescMatch = jsdoc.match(/@bodyDescription\s+(.+)$/m);
+        if (bodyDescMatch) {
+            metadata.bodyDescription = bodyDescMatch[1].trim();
+        }
+        return metadata;
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Try to parse a string as JSON
+ */
+function tryParseJson(str) {
+    try {
+        return JSON.parse(str);
+    }
+    catch {
+        return str;
+    }
+}
+/**
+ * Extracts fields from a type definition string
+ */
+function extractTypeFields(typeStr) {
+    const fields = [];
+    // Parse object type like { limit?: number; offset?: number }
+    const cleanType = typeStr.replace(/^[\s\n]+/, '').replace(/[\s\n]+$/, '');
+    if (!cleanType.startsWith('{')) {
+        return fields;
+    }
+    // Remove outer braces
+    const inner = cleanType.slice(1, -1).trim();
+    // Split by semicolons (simplistic parsing)
+    const propLines = inner.split(';').filter(s => s.trim());
+    for (const line of propLines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        // Match: name?: type or name: type
+        const match = trimmed.match(/^(\w+)(\?)?:\s*(.+)$/);
+        if (match) {
+            const name = match[1];
+            const optional = !!match[2];
+            const type = match[3].trim();
+            fields.push({
+                name,
+                required: !optional,
+                schema: typeStringToJsonSchema(type),
+            });
+        }
+    }
+    return fields;
+}
+/**
+ * Converts a type string to JSON Schema
+ */
+function typeStringToJsonSchema(type) {
+    const cleanType = type.trim();
+    // Array types
+    if (cleanType.endsWith('[]')) {
+        const itemType = cleanType.slice(0, -2);
+        return {
+            type: 'array',
+            items: typeStringToJsonSchema(itemType),
+        };
+    }
+    // Union types (simplified)
+    if (cleanType.includes('|')) {
+        const types = cleanType.split('|').map(t => t.trim());
+        const schemas = types.map(t => typeStringToJsonSchema(t));
+        return { anyOf: schemas };
+    }
+    // Basic types
+    switch (cleanType.toLowerCase()) {
+        case 'string':
+            return { type: 'string' };
+        case 'number':
+        case 'integer':
+            return { type: 'number' };
+        case 'boolean':
+            return { type: 'boolean' };
+        case 'date':
+            return { type: 'string', format: 'date-time' };
+        case 'object':
+            return { type: 'object' };
+        case 'any':
+            return {};
+        default:
+            // Could be a custom type reference
+            if (cleanType.match(/^[A-Z]\w*$/)) {
+                return { $ref: `#/components/schemas/${cleanType}` };
+            }
+            return { type: 'object' };
+    }
+}
+/**
+ * Converts a type definition to JSON Schema
+ */
+function typeToSchema(typeStr) {
+    if (typeStr.trim().startsWith('{')) {
+        const fields = extractTypeFields(typeStr);
+        const properties = {};
+        const required = [];
+        for (const field of fields) {
+            properties[field.name] = field.schema;
+            if (field.required) {
+                required.push(field.name);
+            }
+        }
+        return {
+            type: 'object',
+            properties,
+            required: required.length > 0 ? required : undefined,
+        };
+    }
+    return typeStringToJsonSchema(typeStr);
+}
+/**
+ * Generates component schemas from route types
+ */
+function generateSchemas(routes) {
+    const schemas = {};
+    // Collect unique type names referenced in routes
+    const typeNames = new Set();
+    for (const route of routes) {
+        if (route.bodyType) {
+            const refs = extractTypeReferences(route.bodyType);
+            refs.forEach(ref => typeNames.add(ref));
+        }
+        if (route.queryType) {
+            const refs = extractTypeReferences(route.queryType);
+            refs.forEach(ref => typeNames.add(ref));
+        }
+    }
+    // For now, create placeholder schemas
+    // In a future version, we could parse actual type definitions from files
+    for (const typeName of typeNames) {
+        schemas[typeName] = {
+            type: 'object',
+            description: `${typeName} schema`,
+        };
+    }
+    return schemas;
+}
+/**
+ * Extracts type references from a type string
+ */
+function extractTypeReferences(typeStr) {
+    const refs = [];
+    // Match capitalized type names (User, Post, etc.)
+    const matches = typeStr.matchAll(/\b([A-Z][a-zA-Z0-9_]*)\b/g);
+    for (const match of matches) {
+        // Exclude primitive-like names
+        if (!['Object', 'Array', 'Date', 'String', 'Number', 'Boolean'].includes(match[1])) {
+            refs.push(match[1]);
+        }
+    }
+    return [...new Set(refs)];
+}
+/**
+ * Generates the OpenAPI JSON file
+ */
+export async function generateOpenApiFile(outputPath, routes, options) {
+    const spec = generateOpenApiSpec(routes, options);
+    // Create directory if it doesn't exist
+    const dir = path.dirname(outputPath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(outputPath, JSON.stringify(spec, null, 2), 'utf-8');
+}
+/**
+ * Generates Swagger UI HTML
+ */
+export function generateSwaggerUiHtml(apiJsonPath, title = 'API Documentation') {
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${title}</title>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css">
+</head>
+<body>
+  <div id="swagger-ui"></div>
+  <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+  <script>
+    SwaggerUIBundle({
+      url: '${apiJsonPath}',
+      dom_id: '#swagger-ui',
+      presets: [
+        SwaggerUIBundle.presets.apis,
+        SwaggerUIBundle.presets.standalone
+      ]
+    });
+  </script>
+</body>
+</html>`;
+}

package/dist/core/routing/route-matcher.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=route-matcher.test.d.ts.map

package/dist/core/routing/route-matcher.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-matcher.test.d.ts","sourceRoot":"","sources":["../../../src/core/routing/route-matcher.test.ts"],"names":[],"mappings":""}

package/dist/core/routing/route-matcher.test.js

@@ -0,0 +1,231 @@
+import { describe, it, expect } from 'vitest';
+import { matchRoute } from './route-matcher.js';
+import { createRoute } from './route-parser.js';
+function createTestRoute(parsed) {
+    return createRoute(parsed, async () => ({ success: true }));
+}
+describe('matchRoute', () => {
+    describe('basic matching', () => {
+        it('should match exact path', () => {
+            const routes = [
+                createTestRoute({
+                    method: 'get',
+                    pattern: 'health',
+                    params: [],
+                    file: '/api/health.get.ts',
+                }),
+            ];
+            const match = matchRoute(routes, '/health', 'get');
+            expect(match).not.toBeNull();
+            expect(match?.route.pattern).toBe('health');
+            expect(match?.params).toEqual({});
+        });
+        it('should match path with leading slash', () => {
+            const routes = [
+                createTestRoute({
+                    method: 'get',
+                    pattern: 'health',
+                    params: [],
+                    file: '/api/health.get.ts',
+                }),
+            ];
+            const match = matchRoute(routes, 'health', 'get');
+            expect(match).not.toBeNull();
+            expect(match?.route.pattern).toBe('health');
+        });
+        it('should return null for non-matching path', () => {
+            const routes = [
+                createTestRoute({
+                    method: 'get',
+                    pattern: 'health',
+                    params: [],
+                    file: '/api/health.get.ts',
+                }),
+            ];
+            const match = matchRoute(routes, '/users', 'get');
+            expect(match).toBeNull();
+        });
+        it('should return null for non-matching method', () => {
+            const routes = [
+                createTestRoute({
+                    method: 'get',
+                    pattern: 'health',
+                    params: [],
+                    file: '/api/health.get.ts',
+                }),
+            ];
+            const match = matchRoute(routes, '/health', 'post');
+            expect(match).toBeNull();
+        });
+    });
+    describe('dynamic parameters', () => {
+        it('should extract single parameter', () => {
+            const routes = [
+                createTestRoute({
+                    method: 'get',
+                    pattern: 'users/:id',
+                    params: ['id'],
+                    file: '/api/users/[id].get.ts',
+                }),
+            ];
+            const match = matchRoute(routes, '/users/123', 'get');
+            expect(match).not.toBeNull();
+            expect(match?.params).toEqual({ id: '123' });
+        });
+        it('should extract multiple parameters', () => {
+            const routes = [
+                createTestRoute({
+                    method: 'get',
+                    pattern: 'users/:userId/posts/:postId',
+                    params: ['userId', 'postId'],
+                    file: '/api/users/[userId]/posts/[postId].get.ts',
+                }),
+            ];
+            const match = matchRoute(routes, '/users/42/posts/99', 'get');
+            expect(match).not.toBeNull();
+            expect(match?.params).toEqual({ userId: '42', postId: '99' });
+        });
+        it('should handle parameters with special characters', () => {
+            const routes = [
+                createTestRoute({
+                    method: 'get',
+                    pattern: 'files/:filename',
+                    params: ['filename'],
+                    file: '/api/files/[filename].get.ts',
+                }),
+            ];
+            const match = matchRoute(routes, '/files/document.pdf', 'get');
+            expect(match).not.toBeNull();
+            expect(match?.params).toEqual({ filename: 'document.pdf' });
+        });
+    });
+    describe('catch-all parameters', () => {
+        it('should match catch-all route', () => {
+            const routes = [
+                createTestRoute({
+                    method: 'get',
+                    pattern: 'files/*path',
+                    params: ['path'],
+                    file: '/api/files/[...path].get.ts',
+                }),
+            ];
+            const match = matchRoute(routes, '/files/docs/folder/file.txt', 'get');
+            expect(match).not.toBeNull();
+            expect(match?.params).toEqual({ path: 'docs/folder/file.txt' });
+        });
+        it('should match catch-all with single segment', () => {
+            const routes = [
+                createTestRoute({
+                    method: 'get',
+                    pattern: 'api/*rest',
+                    params: ['rest'],
+                    file: '/api/api/[...rest].get.ts',
+                }),
+            ];
+            const match = matchRoute(routes, '/api/users', 'get');
+            expect(match).not.toBeNull();
+            expect(match?.params).toEqual({ rest: 'users' });
+        });
+    });
+    describe('method case insensitivity', () => {
+        it('should match uppercase methods', () => {
+            const routes = [
+                createTestRoute({
+                    method: 'get',
+                    pattern: 'health',
+                    params: [],
+                    file: '/api/health.get.ts',
+                }),
+            ];
+            const match = matchRoute(routes, '/health', 'GET');
+            expect(match).not.toBeNull();
+        });
+        it('should match mixed case methods', () => {
+            const routes = [
+                createTestRoute({
+                    method: 'post',
+                    pattern: 'users',
+                    params: [],
+                    file: '/api/users.post.ts',
+                }),
+            ];
+            const match = matchRoute(routes, '/users', 'Post');
+            expect(match).not.toBeNull();
+        });
+    });
+    describe('multiple routes', () => {
+        it('should return first matching route', () => {
+            const routes = [
+                createTestRoute({
+                    method: 'get',
+                    pattern: 'users/:id',
+                    params: ['id'],
+                    file: '/api/users/[id].get.ts',
+                }),
+                createTestRoute({
+                    method: 'get',
+                    pattern: 'users/me',
+                    params: [],
+                    file: '/api/users/me.get.ts',
+                }),
+            ];
+            // This will match the first route with params.id = 'me'
+            const match = matchRoute(routes, '/users/me', 'get');
+            expect(match).not.toBeNull();
+            expect(match?.route.pattern).toBe('users/:id');
+            expect(match?.params).toEqual({ id: 'me' });
+        });
+        it('should filter by method before matching', () => {
+            const routes = [
+                createTestRoute({
+                    method: 'get',
+                    pattern: 'users',
+                    params: [],
+                    file: '/api/users.get.ts',
+                }),
+                createTestRoute({
+                    method: 'post',
+                    pattern: 'users',
+                    params: [],
+                    file: '/api/users.post.ts',
+                }),
+            ];
+            const getMatch = matchRoute(routes, '/users', 'get');
+            const postMatch = matchRoute(routes, '/users', 'post');
+            expect(getMatch?.route.method).toBe('get');
+            expect(postMatch?.route.method).toBe('post');
+        });
+    });
+    describe('edge cases', () => {
+        it('should handle empty routes array', () => {
+            const match = matchRoute([], '/health', 'get');
+            expect(match).toBeNull();
+        });
+        it('should handle root path', () => {
+            const routes = [
+                createTestRoute({
+                    method: 'get',
+                    pattern: '',
+                    params: [],
+                    file: '/api/index.get.ts',
+                }),
+            ];
+            const match = matchRoute(routes, '/', 'get');
+            expect(match).not.toBeNull();
+            expect(match?.route.pattern).toBe('');
+        });
+        it('should handle empty parameter values', () => {
+            const routes = [
+                createTestRoute({
+                    method: 'get',
+                    pattern: 'users/:id',
+                    params: ['id'],
+                    file: '/api/users/[id].get.ts',
+                }),
+            ];
+            // Edge case: URL with empty segment
+            const match = matchRoute(routes, '/users/', 'get');
+            expect(match).toBeNull();
+        });
+    });
+});