apiforge-analyzer 1.1.0

package/dist/esm/frameworks/nextjs-pages.js

@@ -0,0 +1,118 @@
+/**
+ * Next.js Pages Router analyzer
+ * Analyzes API routes in pages/api directory
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * Analyze Next.js Pages Router API routes
+ */
+export async function analyzeNextPages(pagesDir = 'pages/api') {
+    const routes = [];
+    try {
+        const apiDir = path.join(process.cwd(), pagesDir);
+        if (!fs.existsSync(apiDir)) {
+            console.warn('pages/api directory not found');
+            return routes;
+        }
+        // Recursively scan API directory
+        const scanDir = (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 routes like [id]
+                    const dirName = entry.name.startsWith('[') && entry.name.endsWith(']')
+                        ? `:${entry.name.slice(1, -1)}`
+                        : entry.name;
+                    scanDir(fullPath, `${basePath}/${dirName}`);
+                }
+                else if (entry.isFile() && /\.(ts|js)$/.test(entry.name)) {
+                    // Convert filename to route path
+                    const fileName = entry.name.replace(/\.(ts|js)$/, '');
+                    let routePath = basePath;
+                    if (fileName !== 'index') {
+                        // Handle dynamic params like [id].ts
+                        const paramName = fileName.startsWith('[') && fileName.endsWith(']')
+                            ? `:${fileName.slice(1, -1)}`
+                            : fileName;
+                        routePath += `/${paramName}`;
+                    }
+                    // Read file to detect HTTP methods
+                    const content = fs.readFileSync(fullPath, 'utf-8');
+                    const methods = detectMethods(content);
+                    // Create route for each detected method
+                    methods.forEach(method => {
+                        routes.push({
+                            method,
+                            path: `/api${routePath}`,
+                            description: `${method} /api${routePath}`,
+                            tags: ['api'],
+                            middleware: detectMiddleware(content),
+                            parameters: extractParameters(routePath),
+                            responses: {
+                                '200': { description: 'Successful response' }
+                            }
+                        });
+                    });
+                }
+            }
+        };
+        scanDir(apiDir);
+    }
+    catch (error) {
+        console.error('Error analyzing Next.js Pages routes:', error.message);
+    }
+    return routes;
+}
+/**
+ * Detect HTTP methods in Next.js API route
+ */
+function detectMethods(content) {
+    const methods = new Set();
+    // Check for req.method checks
+    const methodChecks = content.match(/req\.method\s*===?\s*['"`](\w+)['"`]/g) || [];
+    methodChecks.forEach(check => {
+        const match = check.match(/['"`](\w+)['"`]/);
+        if (match)
+            methods.add(match[1]);
+    });
+    // If no explicit methods found, assume it handles all methods
+    if (methods.size === 0) {
+        methods.add('GET');
+        methods.add('POST');
+    }
+    return Array.from(methods);
+}
+/**
+ * Detect middleware usage
+ */
+function detectMiddleware(content) {
+    const middleware = [];
+    // Check for common middleware patterns
+    if (content.includes('auth') || content.includes('authenticate')) {
+        middleware.push('auth');
+    }
+    if (content.includes('cors')) {
+        middleware.push('cors');
+    }
+    return middleware;
+}
+/**
+ * Extract parameters from route path
+ */
+function extractParameters(routePath) {
+    const params = [];
+    const paramMatches = routePath.match(/:(\w+)/g) || [];
+    paramMatches.forEach(param => {
+        const name = param.slice(1);
+        params.push({
+            name,
+            in: 'path',
+            required: true,
+            type: 'string',
+            description: `Path parameter: ${name}`
+        });
+    });
+    return params;
+}

package/dist/esm/frameworks/react-router.js

@@ -0,0 +1,79 @@
+/**
+ * React Router analyzer
+ * Analyzes React Router route definitions
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * Analyze React Router routes
+ */
+export async function analyzeReactRouter(routesFile = 'src/routes.tsx') {
+    const routes = [];
+    try {
+        const routesPath = path.join(process.cwd(), routesFile);
+        if (!fs.existsSync(routesPath)) {
+            console.warn(`Routes file not found: ${routesFile}`);
+            return routes;
+        }
+        const content = fs.readFileSync(routesPath, 'utf-8');
+        // Extract routes from React Router
+        // Look for <Route path="/..." />
+        const routeRegex = /<Route\s+path=["']([^"']+)["']/g;
+        let match;
+        while ((match = routeRegex.exec(content)) !== null) {
+            const routePath = match[1];
+            routes.push({
+                method: 'GET',
+                path: routePath,
+                description: `React Router: ${routePath}`,
+                tags: ['frontend'],
+                middleware: [],
+                parameters: extractParameters(routePath),
+                responses: {
+                    '200': { description: 'Page rendered' }
+                }
+            });
+        }
+        // Also check for createBrowserRouter routes
+        const browserRouterRegex = /path:\s*["']([^"']+)["']/g;
+        while ((match = browserRouterRegex.exec(content)) !== null) {
+            const routePath = match[1];
+            if (!routes.find(r => r.path === routePath)) {
+                routes.push({
+                    method: 'GET',
+                    path: routePath,
+                    description: `React Router: ${routePath}`,
+                    tags: ['frontend'],
+                    middleware: [],
+                    parameters: extractParameters(routePath),
+                    responses: {
+                        '200': { description: 'Page rendered' }
+                    }
+                });
+            }
+        }
+        console.log(`✅ Found ${routes.length} React Router routes`);
+    }
+    catch (error) {
+        console.error('Error analyzing React Router:', error.message);
+    }
+    return routes;
+}
+/**
+ * Extract parameters from route path
+ */
+function extractParameters(routePath) {
+    const params = [];
+    const paramMatches = routePath.match(/:(\w+)/g) || [];
+    paramMatches.forEach(param => {
+        const name = param.slice(1);
+        params.push({
+            name,
+            in: 'path',
+            required: true,
+            type: 'string',
+            description: `Path parameter: ${name}`
+        });
+    });
+    return params;
+}

package/dist/esm/frameworks/vite.js

@@ -0,0 +1,48 @@
+/**
+ * Vite analyzer
+ * Analyzes Vite projects with API proxy configurations
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * Analyze Vite API proxy routes
+ */
+export async function analyzeVite(viteConfigPath = 'vite.config.js') {
+    const routes = [];
+    try {
+        const configPath = path.join(process.cwd(), viteConfigPath);
+        if (!fs.existsSync(configPath)) {
+            console.warn('vite.config.js not found');
+            return routes;
+        }
+        const content = fs.readFileSync(configPath, 'utf-8');
+        // Extract proxy configurations
+        const proxyRegex = /proxy:\s*{([^}]+)}/gs;
+        const proxyMatch = content.match(proxyRegex);
+        if (proxyMatch) {
+            const proxyContent = proxyMatch[0];
+            // Extract proxy routes like '/api': { target: 'http://localhost:3000' }
+            const routeRegex = /['"`]([^'"`]+)['"`]\s*:\s*{/g;
+            let match;
+            while ((match = routeRegex.exec(proxyContent)) !== null) {
+                const proxyPath = match[1];
+                // Create route entry
+                routes.push({
+                    method: 'ALL',
+                    path: proxyPath,
+                    description: `Vite proxy: ${proxyPath}`,
+                    tags: ['proxy'],
+                    middleware: [],
+                    responses: {
+                        '200': { description: 'Proxied response' }
+                    }
+                });
+            }
+        }
+        console.log(`✅ Found ${routes.length} Vite proxy routes`);
+    }
+    catch (error) {
+        console.error('Error analyzing Vite config:', error.message);
+    }
+    return routes;
+}

package/dist/esm/index.js

@@ -0,0 +1,115 @@
+/**
+ * Main analyzer entry point with dual module support
+ */
+import { analyzeExpress } from './frameworks/express.js';
+import { analyzeNextPages } from './frameworks/nextjs-pages.js';
+import { analyzeNextApp } from './frameworks/nextjs-app.js';
+import { analyzeVite } from './frameworks/vite.js';
+import { analyzeReactRouter } from './frameworks/react-router.js';
+import { detectFramework } from './detect.js';
+import { exportToJSON } from './export.js';
+import { uploadRoutes } from './uploader.js';
+// Global state for debouncing
+const analysisState = new Map();
+const DEBOUNCE_TIME = 5000;
+/**
+ * Main analyze function with auto-detection
+ */
+export async function analyze(app, options) {
+    // Skip in production
+    if (options.skipInProduction !== false && process.env.NODE_ENV === 'production') {
+        console.log('⏭️  Skipping analysis in production');
+        return [];
+    }
+    // Debounce check
+    if (options.runOnce !== false) {
+        const cached = analysisState.get(options.projectName);
+        const now = Date.now();
+        if (cached && (now - cached.timestamp) < DEBOUNCE_TIME) {
+            console.log(`⚡ Analysis skipped - already ran ${Math.round((now - cached.timestamp) / 1000)}s ago`);
+            return cached.routes;
+        }
+    }
+    console.log(`🔍 Analyzing ${options.projectName}...`);
+    // CRITICAL: Prevent restart loops - force saveJson=false when uploading
+    if (options.upload !== false && options.apiKey) {
+        options.saveJson = false;
+    }
+    let routes = [];
+    let framework = options.framework;
+    // Auto-detect framework if not specified
+    if (!framework) {
+        const detected = detectFramework(app);
+        framework = detected.name;
+        console.log(`📦 Detected framework: ${framework}`);
+    }
+    // Analyze based on framework
+    switch (framework) {
+        case 'express':
+            if (!app) {
+                console.error('❌ Express app instance required');
+                return [];
+            }
+            routes = await analyzeExpress(app);
+            break;
+        case 'nextjs-pages':
+            routes = await analyzeNextPages(options.nextDir || 'pages/api');
+            break;
+        case 'nextjs-app':
+            routes = await analyzeNextApp(options.nextDir || 'app');
+            break;
+        case 'vite':
+            routes = await analyzeVite(options.nextDir || 'vite.config.js');
+            break;
+        case 'react-router':
+            routes = await analyzeReactRouter(options.nextDir || 'src/routes.tsx');
+            break;
+        case 'node-http':
+        case 'unknown':
+        default:
+            console.warn(`⚠️  Framework "${framework}" not supported yet`);
+            console.log('💡 Supported: express, nextjs-pages, nextjs-app, vite, react-router');
+            console.log('💡 Tip: Specify framework manually: { framework: "express" }');
+            return [];
+    }
+    console.log(`✅ Found ${routes.length} routes`);
+    // Cache results
+    if (options.runOnce !== false) {
+        analysisState.set(options.projectName, {
+            timestamp: Date.now(),
+            routes
+        });
+    }
+    // Save JSON (only if not uploading)
+    if (options.saveJson) {
+        const filePath = options.jsonPath || 'api-export.json';
+        await exportToJSON(routes, options.projectName, filePath, options.baseUrl);
+    }
+    // Upload to APIForge
+    if (options.upload !== false && options.apiKey) {
+        await uploadRoutes(routes, {
+            projectName: options.projectName,
+            apiKey: options.apiKey,
+            baseUrl: options.baseUrl,
+            apiForgeUrl: options.apiForgeUrl,
+        });
+    }
+    return routes;
+}
+// Re-export framework-specific analyzers
+export { analyzeExpress, analyzeNextPages, analyzeNextApp, analyzeVite, analyzeReactRouter };
+export { exportToJSON } from './export.js';
+export { uploadRoutes } from './uploader.js';
+export { detectFramework } from './detect.js';
+// Default export for CommonJS
+export default {
+    analyze,
+    analyzeExpress,
+    analyzeNextPages,
+    analyzeNextApp,
+    analyzeVite,
+    analyzeReactRouter,
+    exportToJSON,
+    uploadRoutes,
+    detectFramework
+};

package/dist/esm/uploader.js

@@ -0,0 +1,28 @@
+import axios from 'axios';
+import { enrichRoutes } from './export.js';
+/**
+ * Upload routes to APIForge server
+ */
+export async function uploadRoutes(routes, options) {
+    const url = options.apiForgeUrl || process.env.APIFORGE_URL || 'http://localhost:3000';
+    const enrichedRoutes = enrichRoutes(routes);
+    try {
+        const response = await axios.post(`${url}/api/upload-routes`, {
+            projectName: options.projectName,
+            routes: enrichedRoutes,
+            baseUrl: options.baseUrl,
+            framework: enrichedRoutes[0]?.framework || 'unknown',
+        }, {
+            headers: {
+                'Content-Type': 'application/json',
+                'X-API-Key': options.apiKey,
+            },
+            timeout: 30000,
+        });
+        console.log('✅ Uploaded to APIForge:', response.data);
+    }
+    catch (error) {
+        console.error('❌ Upload failed:', error.message);
+        throw error;
+    }
+}

package/dist/types/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/types/detect.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Framework detection utilities
+ */
+export type Framework = 'express' | 'nextjs-pages' | 'nextjs-app' | 'vite' | 'react-router' | 'node-http' | 'unknown';
+export interface FrameworkInfo {
+    name: Framework;
+    version?: string;
+    confidence: number;
+}
+/**
+ * Detect which framework is being used
+ */
+export declare function detectFramework(app?: any): FrameworkInfo;

package/dist/types/export.d.ts

@@ -0,0 +1,38 @@
+export interface Route {
+    id?: number;
+    routeKey?: string;
+    method: string;
+    path: string;
+    tag: string;
+    tags?: string[];
+    operationId: string;
+    summary: string;
+    description?: string;
+    middleware: string[];
+    authRequired: boolean;
+    pathParams: string[];
+    queryParams: string[];
+    requestBodyFields: string[];
+    headerParams?: string[];
+    responseStatuses?: number[];
+    parameters?: Array<{
+        name: string;
+        in: 'path' | 'query' | 'header' | 'cookie';
+        required: boolean;
+        type: string;
+        schema?: any;
+        description: string;
+    }>;
+    requestBody?: any;
+    responses?: Record<string, any>;
+    linkedPaths: string[];
+    hasAuth: boolean;
+    framework: string;
+    sourceContext?: Record<string, any>;
+}
+/**
+ * Export routes to JSON file
+ */
+export declare function exportToJSON(routes: Route[], projectName: string, filePath: string, baseUrl?: string): Promise<void>;
+export declare function enrichRoutes(routes: Route[]): Route[];
+export declare function enrichRoute(route: Route, index: number): Route;

package/dist/types/frameworks/express.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Express analyzer — accurate route + payload extraction
+ */
+export interface Route {
+    id?: number;
+    method: string;
+    path: string;
+    tag: string;
+    operationId: string;
+    summary: string;
+    middleware: string[];
+    authRequired: boolean;
+    pathParams: string[];
+    queryParams: string[];
+    requestBodyFields: string[];
+    linkedPaths: string[];
+    hasAuth: boolean;
+    framework: string;
+    responseStatuses?: number[];
+    headerParams?: string[];
+    description?: string;
+}
+export declare function analyzeExpress(app: any): Route[];

package/dist/types/frameworks/nextjs-app.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Next.js App Router analyzer
+ * Analyzes route handlers in app directory
+ */
+import { Route } from '../export.js';
+export interface AnalyzerOptions {
+    projectName: string;
+    appDir?: string;
+    saveJson?: boolean;
+    jsonPath?: string;
+    upload?: boolean;
+    apiKey?: string;
+    apiForgeUrl?: string;
+    baseUrl?: string;
+}
+/**
+ * Analyze Next.js App Router routes
+ */
+export declare function analyzeNextApp(options?: AnalyzerOptions | string): Promise<Route[]>;

package/dist/types/frameworks/nextjs-pages.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Next.js Pages Router analyzer
+ * Analyzes API routes in pages/api directory
+ */
+export interface NextPagesRoute {
+    method: string;
+    path: string;
+    description: string;
+    tags: string[];
+    middleware: string[];
+    parameters?: any[];
+    responses: Record<string, any>;
+}
+/**
+ * Analyze Next.js Pages Router API routes
+ */
+export declare function analyzeNextPages(pagesDir?: string): Promise<NextPagesRoute[]>;

package/dist/types/frameworks/react-router.d.ts

@@ -0,0 +1,17 @@
+/**
+ * React Router analyzer
+ * Analyzes React Router route definitions
+ */
+export interface Route {
+    method: string;
+    path: string;
+    description: string;
+    tags: string[];
+    middleware: string[];
+    parameters?: any[];
+    responses: Record<string, any>;
+}
+/**
+ * Analyze React Router routes
+ */
+export declare function analyzeReactRouter(routesFile?: string): Promise<Route[]>;

package/dist/types/frameworks/vite.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Vite analyzer
+ * Analyzes Vite projects with API proxy configurations
+ */
+export interface Route {
+    method: string;
+    path: string;
+    description: string;
+    tags: string[];
+    middleware: string[];
+    parameters?: any[];
+    responses: Record<string, any>;
+}
+/**
+ * Analyze Vite API proxy routes
+ */
+export declare function analyzeVite(viteConfigPath?: string): Promise<Route[]>;

package/dist/types/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Main analyzer entry point with dual module support
+ */
+import { analyzeExpress } from './frameworks/express.js';
+import { analyzeNextPages } from './frameworks/nextjs-pages.js';
+import { analyzeNextApp } from './frameworks/nextjs-app.js';
+import { analyzeVite } from './frameworks/vite.js';
+import { analyzeReactRouter } from './frameworks/react-router.js';
+import { detectFramework } from './detect.js';
+import { exportToJSON } from './export.js';
+import { uploadRoutes } from './uploader.js';
+export interface AnalyzerOptions {
+    projectName: string;
+    baseUrl?: string;
+    apiKey?: string;
+    apiForgeUrl?: string;
+    upload?: boolean;
+    saveJson?: boolean;
+    jsonPath?: string;
+    framework?: string;
+    nextDir?: string;
+    skipInProduction?: boolean;
+    runOnce?: boolean;
+}
+/**
+ * Main analyze function with auto-detection
+ */
+export declare function analyze(app: any, options: AnalyzerOptions): Promise<any[]>;
+export { analyzeExpress, analyzeNextPages, analyzeNextApp, analyzeVite, analyzeReactRouter };
+export { exportToJSON } from './export.js';
+export { uploadRoutes } from './uploader.js';
+export { detectFramework } from './detect.js';
+declare const _default: {
+    analyze: typeof analyze;
+    analyzeExpress: typeof analyzeExpress;
+    analyzeNextPages: typeof analyzeNextPages;
+    analyzeNextApp: typeof analyzeNextApp;
+    analyzeVite: typeof analyzeVite;
+    analyzeReactRouter: typeof analyzeReactRouter;
+    exportToJSON: typeof exportToJSON;
+    uploadRoutes: typeof uploadRoutes;
+    detectFramework: typeof detectFramework;
+};
+export default _default;

package/dist/types/uploader.d.ts

@@ -0,0 +1,11 @@
+import { Route } from './export.js';
+export interface UploadOptions {
+    projectName: string;
+    baseUrl?: string;
+    apiForgeUrl?: string;
+    apiKey: string;
+}
+/**
+ * Upload routes to APIForge server
+ */
+export declare function uploadRoutes(routes: Route[], options: UploadOptions): Promise<void>;

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "apiforge-analyzer",
+  "version": "1.1.0",
+  "description": "Universal API documentation generator for Express, Next.js, Vite, React Router, and Node.js",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "bin": {
+    "apiforge-analyzer": "./dist/esm/cli.js",
+    "apiforge": "./dist/esm/cli.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/types/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "npm run build:esm && npm run build:cjs && npm run build:types",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json && echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json",
+    "build:types": "tsc -p tsconfig.types.json",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "api",
+    "documentation",
+    "openapi",
+    "swagger",
+    "express",
+    "nextjs",
+    "vite",
+    "react-router",
+    "nodejs",
+    "analyzer",
+    "cli"
+  ],
+  "author": "APIForge",
+  "license": "MIT",
+  "peerDependencies": {
+    "express": "^4.0.0 || ^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.9.1",
+    "axios": "^1.6.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.3.0"
+  }
+}