@vibesdotdev/kit 0.0.0-stage → 1.0.0-rc.4

package/dist/lib/server/api/openapi-registry.js

@@ -0,0 +1,625 @@
+/**
+ * OpenAPI Registry
+ *
+ * Global registry for API endpoints that automatically generates OpenAPI/Swagger documentation.
+ * Routes register themselves when imported, and the spec is generated on-demand.
+ */
+import * as z from 'zod/v4';
+import { DEV } from 'esm-env';
+import { failureClass } from '../../failure-class';
+import { kitLogger } from '../../kit-logger';
+import { loadKitConfigDefaults } from "../../config/kit.config.descriptor.js";
+import { settle, settleNow } from './settled';
+const logger = kitLogger('openapi-registry');
+/**
+ * Copy the config so later mutation of the caller's objects cannot change what
+ * is documented. Zod schemas are carried by reference: their prototype chain
+ * and internals must stay intact.
+ */
+function cloneRouteConfig(config) {
+    const { metadata, validation, auth, responses, rateLimit } = config;
+    return {
+        ...config,
+        metadata: metadata
+            ? { ...metadata, tags: metadata.tags ? [...metadata.tags] : undefined }
+            : undefined,
+        validation: validation ? { ...validation } : undefined,
+        auth: auth
+            ? {
+                ...auth,
+                permissions: auth.permissions ? [...auth.permissions] : undefined,
+                roles: auth.roles ? [...auth.roles] : undefined
+            }
+            : undefined,
+        responses: responses
+            ? Object.fromEntries(Object.entries(responses).map(([status, response]) => [status, { ...response }]))
+            : undefined,
+        rateLimit: rateLimit ? { ...rateLimit } : undefined
+    };
+}
+/**
+ * Build a minimal JSON Schema from a Zod v4 schema's own structure. Used when
+ * the generator output lacks the properties/items a schema plainly declares
+ * (for example a self-referential object, which the generator emits as a $ref).
+ */
+function minimalJsonSchema(schema) {
+    if (schema instanceof z.core.$ZodArray) {
+        return {
+            type: 'array',
+            description: 'Array of items',
+            items: minimalJsonSchema(schema._zod.def.element)
+        };
+    }
+    if (schema instanceof z.core.$ZodObject) {
+        const properties = minimalProperties(schema);
+        const count = Object.keys(properties).length;
+        return {
+            type: 'object',
+            description: count > 0 ? `Object with ${count} properties` : 'Empty object',
+            properties
+        };
+    }
+    if (schema instanceof z.core.$ZodNullable || schema instanceof z.core.$ZodOptional) {
+        return minimalJsonSchema(schema._zod.def.innerType);
+    }
+    if (schema instanceof z.core.$ZodRecord) {
+        return { type: 'object', description: 'Record object' };
+    }
+    if (schema instanceof z.core.$ZodString) {
+        const format = declaredFormat(schema);
+        if (format === 'uuid')
+            return { type: 'string', format: 'uuid', description: 'UUID string' };
+        if (format === 'datetime') {
+            return { type: 'string', format: 'date-time', description: 'Date-time string' };
+        }
+        return { type: 'string', description: 'String value' };
+    }
+    if (schema instanceof z.core.$ZodNumber) {
+        const isInteger = declaredFormat(schema)?.includes('int') ?? false;
+        return { type: isInteger ? 'integer' : 'number', description: 'Numeric value' };
+    }
+    if (schema instanceof z.core.$ZodBoolean) {
+        return { type: 'boolean', description: 'Boolean value' };
+    }
+    return { type: 'object', description: 'Schema object' };
+}
+/**
+ * The format a string or number schema declares: the schema itself when it is a
+ * format type (`z.uuid()`, `z.int()`), else its last format check
+ * (`z.string().uuid()`, `z.number().int()`). Zod no longer mirrors these into
+ * `_zod.bag`, so the check definitions are the source.
+ */
+function declaredFormat(schema) {
+    let format;
+    for (const check of [schema, ...(schema._zod.def.checks ?? [])]) {
+        if (check instanceof z.core.$ZodCheckStringFormat ||
+            check instanceof z.core.$ZodCheckNumberFormat) {
+            format = check._zod.def.format;
+        }
+    }
+    return format;
+}
+function minimalProperties(schema) {
+    // Zod names this member `shape`; it maps each property name to its schema.
+    const members = schema._zod.def['shape'];
+    return Object.fromEntries(Object.entries(members).map(([name, member]) => [name, minimalJsonSchema(member)]));
+}
+/** True when a hand-written (non-Zod) schema object carries JSON Schema vocabulary. */
+function looksLikeJsonSchema(schema) {
+    if ('~standard' in schema || 'def' in schema || 'element' in schema) {
+        return false;
+    }
+    return (z.string().safeParse(schema.type).success ||
+        Array.isArray(schema.type) ||
+        'properties' in schema ||
+        '$ref' in schema ||
+        'oneOf' in schema ||
+        'anyOf' in schema ||
+        'allOf' in schema ||
+        'items' in schema);
+}
+/** Convert with Zod's generator, then fill missing array items / object properties from the Zod definition. Throws when Zod cannot convert. */
+function convertZodSchema(schema, io) {
+    const converted = z.toJSONSchema(schema, {
+        target: 'openapi-3.0',
+        io,
+        unrepresentable: 'any'
+    });
+    if (schema instanceof z.core.$ZodArray) {
+        const minimalItem = minimalJsonSchema(schema._zod.def.element);
+        const items = converted.items;
+        if (!items) {
+            converted.items = minimalItem;
+        }
+        else if (items !== true && !Array.isArray(items)) {
+            const existing = items.properties;
+            if ((!existing || Object.keys(existing).length === 0) && minimalItem.properties) {
+                items.properties = minimalItem.properties;
+            }
+        }
+    }
+    if (schema instanceof z.core.$ZodObject) {
+        const hasProperties = converted.properties && Object.keys(converted.properties).length > 0;
+        if (!hasProperties) {
+            converted.properties = minimalProperties(schema);
+        }
+    }
+    return converted;
+}
+function schemaDescription(schema) {
+    return schema === true || schema === false ? undefined : schema.description;
+}
+export class OpenAPIRegistry {
+    expectedRoutes;
+    coverageOptions = {};
+    /**
+     * The default registry leaves the coverage inventory to the host's declared
+     * routes; a registry built for one mount compares against what it holds.
+     */
+    #coverageDefaults = true;
+    /**
+     * Host facts for the development-only coverage check: the project root and the
+     * host filesystem the route-file scan and report go through. Without a
+     * `fileSystem` the scan and report do not happen.
+     */
+    setCoverageOptions(options) {
+        this.coverageOptions = options;
+    }
+    /** The exported handlers belonging to an explicit mount, including undocumented routes. */
+    setExpectedRoutes(routes) {
+        this.#coverageDefaults = false;
+        this.expectedRoutes = routes.map((route) => ({
+            method: route.method.toUpperCase(),
+            path: this.convertToOpenAPIPath(route.path)
+        }));
+    }
+    routes = new Map();
+    componentSchemas = new Map();
+    /**
+     * Register a route with its configuration
+     */
+    register(method, path, config, options = {}) {
+        // Skip registration while the host declares a build, to avoid noise
+        if (options.building && !options.allowDuringBuild) {
+            return;
+        }
+        // Convert SvelteKit dynamic segments to OpenAPI format
+        const openAPIPath = this.convertToOpenAPIPath(path);
+        const key = `${method.toUpperCase()}:${openAPIPath}`;
+        // Only log in development, not during build
+        if (DEV && path !== 'unknown') {
+            logger.info('Registering endpoint', { key });
+        }
+        this.routes.set(key, {
+            method: method.toUpperCase(),
+            path: openAPIPath,
+            config: cloneRouteConfig(config)
+        });
+    }
+    /**
+     * Convert SvelteKit route pattern to OpenAPI path
+     * [param] -> {param}
+     * [...rest] -> {rest}
+     * [[optional]] -> {optional}
+     */
+    convertToOpenAPIPath(path) {
+        const normalizedPath = path.replace(/\\/g, '/');
+        const hasServerModuleSuffix = /(?:^|\/)\+server\.(?:[cm]?[jt]s)$/.test(normalizedPath);
+        let pathFromRoutes = normalizedPath;
+        if (hasServerModuleSuffix) {
+            if (normalizedPath.startsWith('src/routes/')) {
+                pathFromRoutes = normalizedPath.slice('src/routes'.length);
+            }
+            else if (normalizedPath.startsWith('/src/routes/')) {
+                pathFromRoutes = normalizedPath.slice('/src/routes'.length);
+            }
+            else {
+                const routesRootIndex = normalizedPath.indexOf('/src/routes/');
+                if (routesRootIndex >= 0) {
+                    pathFromRoutes = normalizedPath.slice(routesRootIndex + '/src/routes'.length);
+                }
+            }
+        }
+        let converted = pathFromRoutes
+            .replace(/\/\+server\.(?:[cm]?[jt]s)$/, '')
+            .replace(/\[\.\.\.([^\]]+)\]/g, '{$1}')
+            .replace(/\[\[([^\]]+)\]\]/g, '{$1}')
+            .replace(/\[([^\]]+)\]/g, '{$1}');
+        if (converted.startsWith('/api')) {
+            converted = converted.replace(/^\/api/, '') || '/';
+        }
+        if (!converted.startsWith('/')) {
+            converted = `/${converted}`;
+        }
+        return converted || '/';
+    }
+    /**
+     * Convert a Zod schema to an OpenAPI JSON Schema using Zod v4's built-in generator.
+     * A hand-written JSON Schema object is passed through with a description added.
+     */
+    zodToOpenAPISchema(schema, io = 'input') {
+        if (!schema) {
+            return { type: 'object', description: 'Empty schema' };
+        }
+        if (!(schema instanceof z.core.$ZodType)) {
+            if (looksLikeJsonSchema(schema)) {
+                // Ensure it has the properties openapi-to-graphql needs
+                const validated = { ...schema };
+                if (!z.string().safeParse(validated.description).success) {
+                    validated.description = validated.type
+                        ? `Schema of type ${String(validated.type)}`
+                        : 'Schema object';
+                }
+                return validated;
+            }
+            logger.warn('Failed to convert schema: neither a Zod schema nor a JSON Schema object', {
+                constructor: schema.constructor.name
+            });
+            return { type: 'object', description: 'Schema conversion fallback', properties: {} };
+        }
+        const converted = settleNow(() => convertZodSchema(schema, io));
+        if (converted.ok)
+            return converted.value;
+        logger.warn('Failed to convert Zod schema', {
+            reason: failureClass(converted.error),
+            constructor: schema.constructor.name
+        });
+        // Return a simple fallback schema instead of trying to convert
+        return {
+            type: 'object',
+            description: 'Schema conversion fallback',
+            properties: {}
+        };
+    }
+    /**
+     * Extract path parameters from OpenAPI path
+     */
+    extractPathParams(path) {
+        const matches = path.match(/{([^}]+)}/g);
+        return matches ? matches.map((m) => m.slice(1, -1)) : [];
+    }
+    /** Turn the top-level properties of a converted schema into OpenAPI parameters. */
+    parametersFromSchema(schema, location) {
+        return Object.entries(schema.properties ?? {}).map(([name, property]) => ({
+            name,
+            in: location,
+            required: schema.required?.includes(name) || false,
+            schema: property,
+            description: schemaDescription(property)
+        }));
+    }
+    /**
+     * Generate OpenAPI operation object
+     */
+    generateOperation(route) {
+        const { method, path, config } = route;
+        const parameters = [];
+        const operation = {
+            summary: config.metadata?.summary || `${method} ${path}`,
+            description: config.metadata?.description,
+            tags: config.metadata?.tags || ['API'],
+            deprecated: config.metadata?.deprecated || false,
+            operationId: config.metadata?.operationId || `${method.toLowerCase()}${path.replace(/[^\w]/g, '')}`,
+            parameters,
+            responses: this.generateResponses(config)
+        };
+        // Add security requirements
+        if (config.auth?.required !== false) {
+            operation.security = [
+                config.auth?.permissions?.length
+                    ? { sessionAuth: [], permissions: config.auth.permissions }
+                    : { sessionAuth: [] }
+            ];
+        }
+        // Add path parameters
+        for (const param of this.extractPathParams(path)) {
+            parameters.push({
+                name: param,
+                in: 'path',
+                required: true,
+                schema: { type: 'string' },
+                description: `${param} parameter`
+            });
+        }
+        // Add query parameters
+        if (config.validation?.query) {
+            parameters.push(...this.parametersFromSchema(this.zodToOpenAPISchema(config.validation.query), 'query'));
+        }
+        // Add header parameters
+        if (config.validation?.headers) {
+            parameters.push(...this.parametersFromSchema(this.zodToOpenAPISchema(config.validation.headers), 'header'));
+        }
+        // Add request body
+        if (config.validation?.body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+            operation.requestBody = {
+                required: true,
+                content: {
+                    'application/json': {
+                        schema: this.zodToOpenAPISchema(config.validation.body)
+                    }
+                }
+            };
+        }
+        return operation;
+    }
+    /**
+     * Generate responses object
+     */
+    generateResponses(config) {
+        const responses = {};
+        // Add custom responses if defined
+        if (config.responses) {
+            for (const [statusCode, response] of Object.entries(config.responses)) {
+                responses[statusCode] = {
+                    description: response.description,
+                    content: response.schema
+                        ? {
+                            'application/json': {
+                                schema: this.zodToOpenAPISchema(response.schema, 'output')
+                            }
+                        }
+                        : undefined
+                };
+            }
+        }
+        // Add default success response if not defined
+        if (!responses['200']) {
+            responses['200'] = {
+                description: 'Successful response',
+                content: {
+                    'application/json': {
+                        schema: { type: 'object' }
+                    }
+                }
+            };
+        }
+        // Add standard error responses
+        responses['400'] = {
+            description: 'Bad Request - Invalid input',
+            content: {
+                'application/json': {
+                    schema: {
+                        type: 'object',
+                        properties: {
+                            message: { type: 'string' },
+                            errors: {
+                                type: 'array',
+                                items: {
+                                    type: 'object',
+                                    properties: {
+                                        field: { type: 'string' },
+                                        message: { type: 'string' }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        };
+        // Add auth error if auth is required
+        if (config.auth?.required !== false) {
+            responses['401'] = {
+                description: 'Unauthorized - Authentication required',
+                content: {
+                    'application/json': {
+                        schema: {
+                            type: 'object',
+                            properties: {
+                                message: { type: 'string' }
+                            }
+                        }
+                    }
+                }
+            };
+            // Add permission error if specific permissions are required
+            if (config.auth?.permissions?.length ||
+                config.auth?.roles?.length ||
+                config.auth?.superuser) {
+                responses['403'] = {
+                    description: 'Forbidden - Insufficient permissions',
+                    content: {
+                        'application/json': {
+                            schema: {
+                                type: 'object',
+                                properties: {
+                                    message: { type: 'string' },
+                                    required: {
+                                        type: 'object',
+                                        properties: {
+                                            permissions: {
+                                                type: 'array',
+                                                items: { type: 'string' }
+                                            },
+                                            roles: {
+                                                type: 'array',
+                                                items: { type: 'string' }
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                };
+            }
+        }
+        // Add rate limit error if configured
+        if (config.rateLimit) {
+            responses['429'] = {
+                description: 'Too Many Requests - Rate limit exceeded',
+                content: {
+                    'application/json': {
+                        schema: {
+                            type: 'object',
+                            properties: {
+                                message: { type: 'string' },
+                                retryAfter: { type: 'integer', description: 'Seconds until next request allowed' }
+                            }
+                        }
+                    }
+                }
+            };
+        }
+        return responses;
+    }
+    /**
+    /**
+     * Generate complete OpenAPI specification.
+     *
+     * The contact origin is configuration, never a literal here: it is the
+     * `docsContactOrigin` of the kit config the caller resolved through the
+     * runtime (`loadKitConfig(runtime)` — a composed `kit` manifest, else the
+     * environment catalog for the runtime's tier) and handed in as
+     * `options.contactOrigin`. Omitted means the schema's declared production
+     * default (`loadKitConfigDefaults()`).
+     */
+    generateSpec(options = {}) {
+        // Run coverage analysis in development after routes are loaded
+        if (DEV) {
+            // Settles internally (a failure is logged, never thrown), so nothing is left to catch.
+            void this.checkCoverageAfterGeneration();
+        }
+        // Group routes by path
+        const pathMap = new Map();
+        for (const route of this.routes.values()) {
+            const pathItem = pathMap.get(route.path) ?? {};
+            pathItem[route.method.toLowerCase()] = this.generateOperation(route);
+            pathMap.set(route.path, pathItem);
+        }
+        // Collect unique tags
+        const tags = new Set();
+        for (const route of this.routes.values()) {
+            for (const tag of route.config.metadata?.tags ?? [])
+                tags.add(tag);
+        }
+        // The contact origin is configuration: the caller resolved it through
+        // the runtime's kit config (`loadKitConfig(runtime).docsContactOrigin`);
+        // the declared schema default covers callers with no runtime to hand
+        // (build-time static export).
+        const contactOrigin = options.contactOrigin ?? loadKitConfigDefaults().docsContactOrigin;
+        return {
+            openapi: '3.0.3',
+            info: {
+                title: options.title || 'API',
+                version: options.version || '1.0.0',
+                description: options.description || 'API documentation',
+                contact: {
+                    name: 'API Team',
+                    url: contactOrigin
+                },
+                license: {
+                    name: 'MIT',
+                    url: 'https://opensource.org/licenses/MIT'
+                }
+            },
+            servers: options.servers || [
+                {
+                    url: '/api',
+                    description: 'API Server'
+                }
+            ],
+            paths: Object.fromEntries(pathMap),
+            components: {
+                schemas: Object.fromEntries(this.componentSchemas),
+                securitySchemes: {
+                    sessionAuth: {
+                        type: 'apiKey',
+                        in: 'cookie',
+                        name: 'session',
+                        description: 'Session-based authentication'
+                    },
+                    apiKey: {
+                        type: 'apiKey',
+                        in: 'header',
+                        name: 'X-API-Key',
+                        description: 'API key authentication'
+                    }
+                }
+            },
+            tags: Array.from(tags)
+                .sort()
+                .map((tag) => ({
+                name: tag,
+                description: `${tag} operations`
+            }))
+        };
+    }
+    /**
+     * Clear all registered routes (useful for testing)
+     */
+    clear() {
+        this.routes.clear();
+        this.componentSchemas.clear();
+        this.expectedRoutes = undefined;
+    }
+    /**
+     * Get statistics about registered routes
+     */
+    getStats() {
+        const methodCounts = new Map();
+        const tagCounts = new Map();
+        for (const route of this.routes.values()) {
+            // Count methods
+            methodCounts.set(route.method, (methodCounts.get(route.method) || 0) + 1);
+            // Count tags
+            if (route.config.metadata?.tags) {
+                route.config.metadata.tags.forEach((tag) => {
+                    tagCounts.set(tag, (tagCounts.get(tag) || 0) + 1);
+                });
+            }
+        }
+        return {
+            totalRoutes: this.routes.size,
+            byMethod: Object.fromEntries(methodCounts),
+            byTag: Object.fromEntries(tagCounts),
+            paths: Array.from(new Set(Array.from(this.routes.values()).map((r) => r.path))).sort()
+        };
+    }
+    /**
+     * Get all registered routes for coverage analysis
+     */
+    getRegisteredRoutes() {
+        return Array.from(this.routes.values()).map((route) => ({
+            method: route.method,
+            path: route.path,
+            hasMetadata: !!(route.config.metadata?.summary || route.config.metadata?.description)
+        }));
+    }
+    /**
+     * Check OpenAPI coverage after spec generation (when routes are loaded)
+     */
+    async checkCoverageAfterGeneration() {
+        const checked = await settle(async () => {
+            const { checkOpenAPIMetadataWarnings } = await import('./docs/metadata-warnings.js');
+            await checkOpenAPIMetadataWarnings(this, this.expectedRoutes ?? (this.#coverageDefaults ? undefined : this.getRegisteredRoutes()), this.coverageOptions);
+        });
+        if (!checked.ok) {
+            logger.warn('Failed to run OpenAPI coverage check', {
+                reason: failureClass(checked.error)
+            });
+        }
+    }
+    /**
+     * Register a reusable schema component
+     */
+    registerSchema(name, schema) {
+        this.componentSchemas.set(name, this.zodToOpenAPISchema(schema));
+    }
+}
+/** Create an independent registry for an explicit API surface. */
+export function createOpenAPIRegistry() {
+    return new OpenAPIRegistry();
+}
+let defaultRegistry;
+/**
+ * The default registry for callers that have not declared their mount
+ * inventory: neither an explicit `registry` nor `routeModules`. Created on first
+ * use and shared by every such caller in this process, so import-time
+ * registration and the documentation request still meet. A mount that declares
+ * its inventory gets its own registry through `createOpenAPIRegistry()` instead.
+ */
+export function defaultOpenAPIRegistry() {
+    defaultRegistry ??= new OpenAPIRegistry();
+    return defaultRegistry;
+}