@girardmedia/bootspring 2.5.0 → 2.5.2

package/generators/api-docs.js

@@ -1,827 +0,0 @@
-/**
- * Bootspring API.md Auto-Generator
- *
- * Auto-generates API documentation from routes with endpoint reference,
- * request/response schemas, authentication requirements, and examples.
- *
- * @package bootspring
- * @module generators/api-docs
- */
-
-const fs = require('fs');
-const path = require('path');
-
-/**
- * HTTP methods
- */
-const HTTP_METHODS = {
-  GET: { color: 'green', description: 'Retrieve resource(s)' },
-  POST: { color: 'yellow', description: 'Create resource' },
-  PUT: { color: 'blue', description: 'Update resource (full)' },
-  PATCH: { color: 'purple', description: 'Update resource (partial)' },
-  DELETE: { color: 'red', description: 'Delete resource' },
-  OPTIONS: { color: 'gray', description: 'CORS preflight' },
-  HEAD: { color: 'gray', description: 'Get headers only' }
-};
-
-/**
- * Common response codes
- */
-const RESPONSE_CODES = {
-  200: { description: 'OK', type: 'success' },
-  201: { description: 'Created', type: 'success' },
-  204: { description: 'No Content', type: 'success' },
-  400: { description: 'Bad Request', type: 'error' },
-  401: { description: 'Unauthorized', type: 'error' },
-  403: { description: 'Forbidden', type: 'error' },
-  404: { description: 'Not Found', type: 'error' },
-  409: { description: 'Conflict', type: 'error' },
-  422: { description: 'Unprocessable Entity', type: 'error' },
-  429: { description: 'Too Many Requests', type: 'error' },
-  500: { description: 'Internal Server Error', type: 'error' }
-};
-
-/**
- * API Documentation Generator
- */
-class ApiDocsGenerator {
-  constructor(options = {}) {
-    this.projectRoot = options.projectRoot || process.cwd();
-    this.apiDataPath = path.join(this.projectRoot, '.bootspring', 'api-docs.json');
-    this.baseUrl = options.baseUrl || '/api';
-    this.version = options.version || 'v1';
-  }
-
-  /**
-   * Load API docs data
-   */
-  loadApiData() {
-    try {
-      if (fs.existsSync(this.apiDataPath)) {
-        return JSON.parse(fs.readFileSync(this.apiDataPath, 'utf-8'));
-      }
-    } catch (_err) {
-      // Return default
-    }
-
-    return {
-      project: this.getProjectName(),
-      version: this.version,
-      baseUrl: this.baseUrl,
-      endpoints: [],
-      schemas: {},
-      authentication: {},
-      metadata: {
-        created: new Date().toISOString(),
-        lastUpdated: null,
-        autoGenerated: true
-      }
-    };
-  }
-
-  /**
-   * Save API data
-   */
-  saveApiData(data) {
-    data.metadata.lastUpdated = new Date().toISOString();
-
-    const dir = path.dirname(this.apiDataPath);
-    if (!fs.existsSync(dir)) {
-      fs.mkdirSync(dir, { recursive: true });
-    }
-    fs.writeFileSync(this.apiDataPath, JSON.stringify(data, null, 2));
-  }
-
-  /**
-   * Get project name
-   */
-  getProjectName() {
-    try {
-      const pkgPath = path.join(this.projectRoot, 'package.json');
-      if (fs.existsSync(pkgPath)) {
-        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-        return pkg.name || 'API';
-      }
-    } catch (_err) {
-      // Default
-    }
-    return 'API';
-  }
-
-  /**
-   * Scan for API routes in the project
-   */
-  async scanRoutes() {
-    const endpoints = [];
-
-    // Next.js App Router
-    const appApiDir = path.join(this.projectRoot, 'app', 'api');
-    if (fs.existsSync(appApiDir)) {
-      endpoints.push(...this.scanNextJsAppRouter(appApiDir));
-    }
-
-    // Next.js Pages Router
-    const pagesApiDir = path.join(this.projectRoot, 'pages', 'api');
-    if (fs.existsSync(pagesApiDir)) {
-      endpoints.push(...this.scanNextJsPagesRouter(pagesApiDir));
-    }
-
-    // Express-style routes
-    const routesDir = path.join(this.projectRoot, 'routes');
-    if (fs.existsSync(routesDir)) {
-      endpoints.push(...this.scanExpressRoutes(routesDir));
-    }
-
-    // src/routes
-    const srcRoutesDir = path.join(this.projectRoot, 'src', 'routes');
-    if (fs.existsSync(srcRoutesDir)) {
-      endpoints.push(...this.scanExpressRoutes(srcRoutesDir));
-    }
-
-    return endpoints;
-  }
-
-  /**
-   * Scan Next.js App Router routes
-   */
-  scanNextJsAppRouter(apiDir) {
-    const endpoints = [];
-
-    const walk = (dir, basePath = '') => {
-      const entries = fs.readdirSync(dir, { withFileTypes: true });
-
-      for (const entry of entries) {
-        const fullPath = path.join(dir, entry.name);
-
-        if (entry.isDirectory()) {
-          // Handle dynamic segments [id] -> :id
-          let segment = entry.name;
-          if (segment.startsWith('[') && segment.endsWith(']')) {
-            segment = ':' + segment.slice(1, -1);
-          }
-          walk(fullPath, `${basePath}/${segment}`);
-        } else if (entry.name === 'route.ts' || entry.name === 'route.js') {
-          const endpoint = this.parseNextJsRouteFile(fullPath, basePath);
-          if (endpoint) {
-            endpoints.push(...endpoint);
-          }
-        }
-      }
-    };
-
-    walk(apiDir);
-    return endpoints;
-  }
-
-  /**
-   * Parse Next.js App Router route file
-   */
-  parseNextJsRouteFile(filePath, routePath) {
-    const endpoints = [];
-    const content = fs.readFileSync(filePath, 'utf-8');
-
-    // Extract exported methods (GET, POST, etc.)
-    const methodPattern = /export\s+(?:async\s+)?function\s+(GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD)/g;
-    let match;
-
-    while ((match = methodPattern.exec(content)) !== null) {
-      const method = match[1];
-      const endpoint = {
-        path: `/api${routePath}`,
-        method,
-        description: this.extractDescription(content, method),
-        parameters: this.extractParameters(routePath, content),
-        requestBody: this.extractRequestBody(content, method),
-        responses: this.extractResponses(content, method),
-        authentication: this.detectAuthentication(content),
-        rateLimit: this.detectRateLimit(content),
-        tags: this.extractTags(routePath),
-        source: filePath
-      };
-      endpoints.push(endpoint);
-    }
-
-    return endpoints;
-  }
-
-  /**
-   * Scan Next.js Pages Router routes
-   */
-  scanNextJsPagesRouter(apiDir) {
-    const endpoints = [];
-
-    const walk = (dir, basePath = '') => {
-      const entries = fs.readdirSync(dir, { withFileTypes: true });
-
-      for (const entry of entries) {
-        const fullPath = path.join(dir, entry.name);
-
-        if (entry.isDirectory()) {
-          let segment = entry.name;
-          if (segment.startsWith('[') && segment.endsWith(']')) {
-            segment = ':' + segment.slice(1, -1);
-          }
-          walk(fullPath, `${basePath}/${segment}`);
-        } else if (entry.name.endsWith('.ts') || entry.name.endsWith('.js')) {
-          let routeName = entry.name.replace(/\.(ts|js)$/, '');
-
-          // Handle dynamic routes
-          if (routeName.startsWith('[') && routeName.endsWith(']')) {
-            routeName = ':' + routeName.slice(1, -1);
-          }
-
-          // Skip index routes in path
-          const routePath = routeName === 'index'
-            ? basePath
-            : `${basePath}/${routeName}`;
-
-          const endpoint = this.parsePagesRouterFile(fullPath, routePath);
-          if (endpoint) {
-            endpoints.push(...endpoint);
-          }
-        }
-      }
-    };
-
-    walk(apiDir);
-    return endpoints;
-  }
-
-  /**
-   * Parse Pages Router API file
-   */
-  parsePagesRouterFile(filePath, routePath) {
-    const endpoints = [];
-    const content = fs.readFileSync(filePath, 'utf-8');
-
-    // Detect methods from switch/if statements
-    const detectedMethods = this.detectMethodsFromContent(content);
-
-    for (const method of detectedMethods) {
-      endpoints.push({
-        path: `/api${routePath}`,
-        method,
-        description: this.extractDescription(content, method),
-        parameters: this.extractParameters(routePath, content),
-        requestBody: this.extractRequestBody(content, method),
-        responses: this.extractResponses(content, method),
-        authentication: this.detectAuthentication(content),
-        rateLimit: this.detectRateLimit(content),
-        tags: this.extractTags(routePath),
-        source: filePath
-      });
-    }
-
-    return endpoints;
-  }
-
-  /**
-   * Scan Express-style routes
-   */
-  scanExpressRoutes(routesDir) {
-    const endpoints = [];
-
-    const walk = (dir) => {
-      const entries = fs.readdirSync(dir, { withFileTypes: true });
-
-      for (const entry of entries) {
-        const fullPath = path.join(dir, entry.name);
-
-        if (entry.isDirectory()) {
-          walk(fullPath);
-        } else if (entry.name.endsWith('.ts') || entry.name.endsWith('.js')) {
-          const routeEndpoints = this.parseExpressRouteFile(fullPath);
-          endpoints.push(...routeEndpoints);
-        }
-      }
-    };
-
-    walk(routesDir);
-    return endpoints;
-  }
-
-  /**
-   * Parse Express route file
-   */
-  parseExpressRouteFile(filePath) {
-    const endpoints = [];
-    const content = fs.readFileSync(filePath, 'utf-8');
-
-    // Match router.get, router.post, etc.
-    const routePattern = /router\.(get|post|put|patch|delete)\s*\(\s*['"`]([^'"`]+)['"`]/gi;
-    let match;
-
-    while ((match = routePattern.exec(content)) !== null) {
-      const method = match[1].toUpperCase();
-      const routePath = match[2];
-
-      endpoints.push({
-        path: routePath,
-        method,
-        description: '',
-        parameters: this.extractParameters(routePath, content),
-        requestBody: method !== 'GET' && method !== 'DELETE' ? { type: 'object' } : null,
-        responses: { 200: { description: 'Success' } },
-        authentication: this.detectAuthentication(content),
-        tags: this.extractTags(routePath),
-        source: filePath
-      });
-    }
-
-    return endpoints;
-  }
-
-  /**
-   * Detect methods from content
-   */
-  detectMethodsFromContent(content) {
-    const methods = new Set();
-
-    // Check for method handling patterns
-    if (content.includes("method === 'GET'") || content.includes('case "GET"') || content.includes("case 'GET'")) {
-      methods.add('GET');
-    }
-    if (content.includes("method === 'POST'") || content.includes('case "POST"') || content.includes("case 'POST'")) {
-      methods.add('POST');
-    }
-    if (content.includes("method === 'PUT'") || content.includes('case "PUT"') || content.includes("case 'PUT'")) {
-      methods.add('PUT');
-    }
-    if (content.includes("method === 'PATCH'") || content.includes('case "PATCH"') || content.includes("case 'PATCH'")) {
-      methods.add('PATCH');
-    }
-    if (content.includes("method === 'DELETE'") || content.includes('case "DELETE"') || content.includes("case 'DELETE'")) {
-      methods.add('DELETE');
-    }
-
-    // If no specific methods found, assume all common ones
-    if (methods.size === 0) {
-      methods.add('GET');
-      methods.add('POST');
-    }
-
-    return Array.from(methods);
-  }
-
-  /**
-   * Extract description from comments
-   */
-  extractDescription(content, method) {
-    // Look for JSDoc comment before method
-    const pattern = new RegExp(`\\/\\*\\*([\\s\\S]*?)\\*\\/\\s*(?:export\\s+)?(?:async\\s+)?function\\s+${method}`, 'i');
-    const match = content.match(pattern);
-
-    if (match) {
-      // Extract description from JSDoc
-      const jsdoc = match[1];
-      const descMatch = jsdoc.match(/@description\s+(.+)/);
-      if (descMatch) {
-        return descMatch[1].trim();
-      }
-
-      // Or first line
-      const lines = jsdoc.split('\n').map(l => l.replace(/^\s*\*\s?/, '').trim()).filter(Boolean);
-      if (lines.length > 0 && !lines[0].startsWith('@')) {
-        return lines[0];
-      }
-    }
-
-    return '';
-  }
-
-  /**
-   * Extract parameters from route path and content
-   */
-  extractParameters(routePath, content) {
-    const parameters = [];
-
-    // Path parameters
-    const pathParams = routePath.match(/:(\w+)/g) || [];
-    for (const param of pathParams) {
-      parameters.push({
-        name: param.slice(1),
-        in: 'path',
-        required: true,
-        type: 'string',
-        description: ''
-      });
-    }
-
-    // Query parameters (heuristic)
-    const queryMatches = content.match(/(?:searchParams|query)\.get\s*\(\s*['"`](\w+)['"`]\)/g) || [];
-    for (const match of queryMatches) {
-      const paramMatch = match.match(/['"`](\w+)['"`]/);
-      if (paramMatch) {
-        const name = paramMatch[1];
-        if (!parameters.some(p => p.name === name)) {
-          parameters.push({
-            name,
-            in: 'query',
-            required: false,
-            type: 'string',
-            description: ''
-          });
-        }
-      }
-    }
-
-    return parameters;
-  }
-
-  /**
-   * Extract request body schema
-   */
-  extractRequestBody(content, method) {
-    if (method === 'GET' || method === 'DELETE') {
-      return null;
-    }
-
-    // Look for Zod schema
-    const zodMatch = content.match(/const\s+(\w+Schema)\s*=\s*z\.object\s*\(\s*\{([^}]+)\}/);
-    if (zodMatch) {
-      return {
-        schema: zodMatch[1],
-        type: 'object',
-        description: 'Request body validated with Zod'
-      };
-    }
-
-    // Look for type annotation
-    const typeMatch = content.match(/body\s*:\s*(\w+)/);
-    if (typeMatch) {
-      return {
-        type: typeMatch[1],
-        description: ''
-      };
-    }
-
-    return {
-      type: 'object',
-      description: 'Request body'
-    };
-  }
-
-  /**
-   * Extract response schemas
-   */
-  extractResponses(content, method) {
-    const responses = {};
-
-    // Look for NextResponse.json or res.status calls
-    const responsePattern = /(?:NextResponse\.json|res\.status)\s*\(\s*(?:(\d+)\s*,\s*)?/g;
-    let match;
-
-    while ((match = responsePattern.exec(content)) !== null) {
-      const status = match[1] || '200';
-      if (!responses[status]) {
-        responses[status] = {
-          description: RESPONSE_CODES[status]?.description || 'Response'
-        };
-      }
-    }
-
-    // Add defaults
-    if (Object.keys(responses).length === 0) {
-      responses['200'] = { description: 'Success' };
-      if (method !== 'GET') {
-        responses['400'] = { description: 'Bad Request' };
-      }
-      responses['500'] = { description: 'Internal Server Error' };
-    }
-
-    return responses;
-  }
-
-  /**
-   * Detect authentication requirements
-   */
-  detectAuthentication(content) {
-    if (content.includes('getServerSession') || content.includes('auth()') || content.includes('getSession')) {
-      return { required: true, type: 'session' };
-    }
-    if (content.includes('Authorization') || content.includes('Bearer')) {
-      return { required: true, type: 'bearer' };
-    }
-    if (content.includes('apiKey') || content.includes('x-api-key')) {
-      return { required: true, type: 'apiKey' };
-    }
-    return { required: false };
-  }
-
-  /**
-   * Detect rate limiting
-   */
-  detectRateLimit(content) {
-    if (content.includes('rateLimit') || content.includes('rateLimiter')) {
-      return { enabled: true };
-    }
-    return { enabled: false };
-  }
-
-  /**
-   * Extract tags from route path
-   */
-  extractTags(routePath) {
-    const segments = routePath.split('/').filter(Boolean);
-    if (segments.length > 0) {
-      // Use first segment as tag, excluding dynamic parts
-      const tag = segments[0].replace(/^:/, '');
-      return [tag.charAt(0).toUpperCase() + tag.slice(1)];
-    }
-    return ['General'];
-  }
-
-  /**
-   * Generate API.md content
-   */
-  generate(data = null) {
-    if (!data) {
-      data = this.loadApiData();
-    }
-
-    const now = new Date().toISOString().split('T')[0];
-    const sections = [];
-
-    // Header
-    sections.push(`# API Documentation
-
-**Project:** ${data.project}
-**Version:** ${data.version}
-**Base URL:** \`${data.baseUrl}\`
-**Last Updated:** ${now}
-
----
-
-## Overview
-
-This document provides a complete reference for the ${data.project} API endpoints.
-
-### Authentication
-
-${data.authentication?.type === 'bearer' ? `
-Most endpoints require authentication via Bearer token:
-
-\`\`\`
-Authorization: Bearer <token>
-\`\`\`
-` : data.authentication?.type === 'session' ? `
-Authentication is handled via session cookies. Use the auth endpoints to obtain a session.
-` : `
-Authentication requirements vary by endpoint. Check individual endpoint documentation.
-`}
-
-### Rate Limiting
-
-${data.rateLimit?.enabled ? `
-API requests are rate limited to ${data.rateLimit.limit || 100} requests per ${data.rateLimit.window || 'minute'}.
-` : `
-Rate limiting may be applied to certain endpoints.
-`}
-
----`);
-
-    // Table of Contents
-    const endpointsByTag = this.groupEndpointsByTag(data.endpoints);
-    sections.push(`## Endpoints
-
-${Object.entries(endpointsByTag).map(([tag, endpoints]) => {
-    return `### ${tag}
-
-${endpoints.map(e => `- [\`${e.method}\` ${e.path}](#${this.slugify(e.method + '-' + e.path)})`).join('\n')}`;
-  }).join('\n\n')}
-
----`);
-
-    // Endpoint Details
-    sections.push('## Endpoint Reference\n');
-
-    for (const [tag, endpoints] of Object.entries(endpointsByTag)) {
-      sections.push(`### ${tag}\n`);
-
-      for (const endpoint of endpoints) {
-        sections.push(this.formatEndpoint(endpoint));
-      }
-    }
-
-    // Schemas
-    if (Object.keys(data.schemas).length > 0) {
-      sections.push(`## Schemas
-
-${Object.entries(data.schemas).map(([name, schema]) => `
-### ${name}
-
-\`\`\`typescript
-${JSON.stringify(schema, null, 2)}
-\`\`\`
-`).join('\n')}
-
----`);
-    }
-
-    // Error Handling
-    sections.push(`## Error Handling
-
-All endpoints return errors in a consistent format:
-
-\`\`\`json
-{
-  "error": {
-    "code": "ERROR_CODE",
-    "message": "Human-readable error message",
-    "details": {}
-  }
-}
-\`\`\`
-
-### Common Error Codes
-
-| Code | HTTP Status | Description |
-|------|-------------|-------------|
-| UNAUTHORIZED | 401 | Authentication required |
-| FORBIDDEN | 403 | Insufficient permissions |
-| NOT_FOUND | 404 | Resource not found |
-| VALIDATION_ERROR | 422 | Invalid request data |
-| RATE_LIMITED | 429 | Too many requests |
-| INTERNAL_ERROR | 500 | Server error |
-
----`);
-
-    // Footer
-    sections.push(`---
-
-*Generated by [Bootspring](https://bootspring.com) API Documentation Generator*
-
-### Commands
-
-\`\`\`bash
-bootspring docs api          # Generate API documentation
-bootspring docs api --scan   # Rescan routes
-bootspring docs api --json   # Output as JSON
-\`\`\`
-`);
-
-    return sections.join('\n\n');
-  }
-
-  /**
-   * Group endpoints by tag
-   */
-  groupEndpointsByTag(endpoints) {
-    const grouped = {};
-
-    for (const endpoint of endpoints) {
-      const tag = endpoint.tags?.[0] || 'General';
-      if (!grouped[tag]) {
-        grouped[tag] = [];
-      }
-      grouped[tag].push(endpoint);
-    }
-
-    // Sort endpoints by path within each group
-    for (const tag of Object.keys(grouped)) {
-      grouped[tag].sort((a, b) => a.path.localeCompare(b.path));
-    }
-
-    return grouped;
-  }
-
-  /**
-   * Format single endpoint
-   */
-  formatEndpoint(endpoint) {
-    const methodBadge = this.getMethodBadge(endpoint.method);
-
-    let md = `#### ${methodBadge} ${endpoint.path}
-
-${endpoint.description || '_No description available._'}
-
-`;
-
-    // Authentication
-    if (endpoint.authentication?.required) {
-      md += `**Authentication:** ${endpoint.authentication.type === 'bearer' ? '🔐 Bearer Token' : endpoint.authentication.type === 'session' ? '🔐 Session' : '🔐 Required'}\n\n`;
-    }
-
-    // Parameters
-    if (endpoint.parameters && endpoint.parameters.length > 0) {
-      md += `**Parameters:**
-
-| Name | In | Type | Required | Description |
-|------|-----|------|----------|-------------|
-${endpoint.parameters.map(p => `| \`${p.name}\` | ${p.in} | ${p.type} | ${p.required ? 'Yes' : 'No'} | ${p.description || '-'} |`).join('\n')}
-
-`;
-    }
-
-    // Request Body
-    if (endpoint.requestBody) {
-      md += `**Request Body:**
-
-\`\`\`json
-{
-  // ${endpoint.requestBody.description || endpoint.requestBody.type || 'Request body'}
-}
-\`\`\`
-
-`;
-    }
-
-    // Responses
-    if (endpoint.responses) {
-      md += `**Responses:**
-
-| Status | Description |
-|--------|-------------|
-${Object.entries(endpoint.responses).map(([code, res]) => `| ${code} | ${res.description} |`).join('\n')}
-
-`;
-    }
-
-    // Example
-    md += `**Example:**
-
-\`\`\`bash
-curl -X ${endpoint.method} "${this.baseUrl}${endpoint.path}"${endpoint.authentication?.required ? ' \\\n  -H "Authorization: Bearer <token>"' : ''}${endpoint.requestBody ? ' \\\n  -H "Content-Type: application/json" \\\n  -d \'{"key": "value"}\'' : ''}
-\`\`\`
-
----
-
-`;
-
-    return md;
-  }
-
-  /**
-   * Get method badge
-   */
-  getMethodBadge(method) {
-    const colors = {
-      GET: '🟢',
-      POST: '🟡',
-      PUT: '🔵',
-      PATCH: '🟣',
-      DELETE: '🔴'
-    };
-    return `${colors[method] || '⚪'} \`${method}\``;
-  }
-
-  /**
-   * Slugify string
-   */
-  slugify(str) {
-    return str
-      .toLowerCase()
-      .replace(/[^a-z0-9]+/g, '-')
-      .replace(/^-|-$/g, '');
-  }
-
-  /**
-   * Scan and generate
-   */
-  async scanAndGenerate() {
-    const endpoints = await this.scanRoutes();
-    const data = this.loadApiData();
-    data.endpoints = endpoints;
-    this.saveApiData(data);
-    return this.generate(data);
-  }
-}
-
-/**
- * Generate API.md
- */
-async function generate(options = {}) {
-  const generator = new ApiDocsGenerator(options);
-
-  if (options.scan !== false) {
-    return generator.scanAndGenerate();
-  }
-
-  const data = generator.loadApiData();
-  return generator.generate(data);
-}
-
-/**
- * Scan routes only
- */
-async function scanRoutes(options = {}) {
-  const generator = new ApiDocsGenerator(options);
-  return generator.scanRoutes();
-}
-
-/**
- * Load API data
- */
-function loadApiData(options = {}) {
-  const generator = new ApiDocsGenerator(options);
-  return generator.loadApiData();
-}
-
-module.exports = {
-  ApiDocsGenerator,
-  generate,
-  scanRoutes,
-  loadApiData,
-  HTTP_METHODS,
-  RESPONSE_CODES
-};