apiforge-analyzer 1.2.1 → 1.3.0

package/README.md

@@ -1,279 +1,248 @@
-# APIForge Analyzer
+# apiforge-analyzer
 
-Universal API documentation generator for **Express**, **Next.js**, **Vite**, **React Router**, and **Node.js**.
+CLI and library for auto-generating API documentation from live Express, NestJS, Next.js, Vite, and React Router apps.
 
-Supports both **ESM** (`import`) and **CommonJS** (`require`).
+Routes are extracted at runtime by walking the framework's internal route stack — no static analysis, no decorators, no changes to your production code.
 
-## 📦 Installation
+## CLI usage
 
 ```bash
-npm install apiforge-analyzer
+npx apiforge
+```
+
+Run this from your project root. The CLI will:
+
+1. Detect your architecture (monolithic / modular-monolithic / microservices)
+2. Find your server entry file (or ask)
+3. Inject a temporary analysis snippet
+4. Start your server with the command you choose
+5. Collect all registered routes
+6. Upload to your APIForge dashboard for review
+7. Remove the injected code
+
+For **microservices**, if an `apiforge.config.json` exists the CLI iterates every service sequentially, collects routes from each, then uploads everything in one batch. If no config file exists, the CLI scans your `services/` directory, shows what it found, and writes the config file for you — so the next run is fully automatic.
+
+```json
+// apiforge.config.json — auto-created on first run, commit this file
+{
+  "projectName": "My Backend",
+  "architectureType": "microservices",
+  "services": [
+    { "name": "auth-service",  "dir": "./services/auth-service" },
+    { "name": "user-service",  "dir": "./services/user-service" },
+    { "name": "order-service", "dir": "./services/order-service" }
+  ]
+}
+```
+
+Each service entry can also include `"startCommand"` to override the default (`node <entryFile>`):
+
+```json
+{ "name": "auth-service", "dir": "./services/auth", "startCommand": "npx tsx services/auth/src/index.ts" }
 ```
 
-## 🚀 Quick Start
+## Programmatic API
+
+Install:
+
+```bash
+npm install apiforge-analyzer
+```
 
-### Express (CommonJS)
+### Express
 
-```javascript
+```js
 const express = require('express')
 const { analyze } = require('apiforge-analyzer')
 
 const app = express()
+app.use(express.json())
 
-app.get('/api/users', (req, res) => res.json({ users: [] }))
-app.post('/api/users', (req, res) => res.json({ created: true }))
+app.get('/api/users', getUsers)
+app.post('/api/users', createUser)
+app.get('/api/users/:id', getUserById)
 
+// Call after all routes are registered
 analyze(app, {
   projectName: 'My API',
-  apiKey: process.env.APIFORGE_KEY,
-  upload: true
+  apiKey: process.env.APIFORGE_API_KEY,
+  baseUrl: 'https://api.myapp.com',
+  upload: true,
 })
 
 app.listen(3000)
 ```
 
-### Express (ESM)
+### NestJS
 
-```javascript
-import express from 'express'
+```ts
 import { analyze } from 'apiforge-analyzer'
 
-const app = express()
-
-app.get('/api/users', (req, res) => res.json({ users: [] }))
+const app = await NestFactory.create(AppModule)
+await app.init()
 
-await analyze(app, {
-  projectName: 'My API',
-  apiKey: process.env.APIFORGE_KEY
+await analyze(app.getHttpServer(), {
+  projectName: 'My NestJS API',
+  apiKey: process.env.APIFORGE_API_KEY,
+  upload: true,
 })
 
-app.listen(3000)
+await app.listen(3000)
+```
+
+### Microservices — per-service
+
+When running each service independently, pass `service` to tag routes with the service name:
+
+```js
+const { analyze } = require('apiforge-analyzer')
+
+analyze(app, {
+  projectName: 'My Platform',
+  apiKey: process.env.APIFORGE_API_KEY,
+  architectureType: 'microservices',
+  service: 'auth-service',
+  upload: true,
+})
 ```
 
 ### Next.js Pages Router
 
-```javascript
-// pages/api/analyze.ts
+```ts
 import { analyzeNextPages } from 'apiforge-analyzer'
 
-export default async function handler(req, res) {
-  await analyzeNextPages({
-    projectName: 'My Next.js API',
-    apiKey: process.env.APIFORGE_KEY,
-    upload: true
-  })
-  
-  res.json({ success: true })
-}
+await analyzeNextPages({
+  projectName: 'My Next.js API',
+  apiKey: process.env.APIFORGE_API_KEY,
+  nextDir: 'pages/api',
+  upload: true,
+})
 ```
 
 ### Next.js App Router
 
-```javascript
-// app/api/analyze/route.ts
+```ts
 import { analyzeNextApp } from 'apiforge-analyzer'
 
-export async function GET() {
-  await analyzeNextApp({
-    projectName: 'My Next.js API',
-    apiKey: process.env.APIFORGE_KEY,
-    upload: true
-  })
-  
-  return Response.json({ success: true })
-}
+await analyzeNextApp({
+  projectName: 'My Next.js API',
+  apiKey: process.env.APIFORGE_API_KEY,
+  nextDir: 'app',
+  upload: true,
+})
 ```
 
 ### Vite
 
-```javascript
-// vite-analyze.js
+```ts
 import { analyzeVite } from 'apiforge-analyzer'
 
-// Analyzes proxy routes in vite.config.js
 await analyzeVite({
-  projectName: 'My Vite App',
-  apiKey: process.env.APIFORGE_KEY,
-  upload: true
+  projectName: 'My App',
+  apiKey: process.env.APIFORGE_API_KEY,
+  nextDir: 'vite.config.ts',
+  upload: true,
 })
 ```
 
-**Example Vite Config:**
-
-```javascript
-// vite.config.js
-export default {
-  server: {
-    proxy: {
-      '/api': 'http://localhost:3000',
-      '/auth': 'http://localhost:3001'
-    }
-  }
-}
-```
-
 ### React Router
 
-```javascript
-// analyze-routes.js
+```ts
 import { analyzeReactRouter } from 'apiforge-analyzer'
 
-// Analyzes routes from src/routes.tsx
 await analyzeReactRouter({
-  projectName: 'My React App',
-  apiKey: process.env.APIFORGE_KEY,
-  upload: true
+  projectName: 'My App',
+  apiKey: process.env.APIFORGE_API_KEY,
+  nextDir: 'src/routes.tsx',
+  upload: true,
 })
 ```
 
-**Example Routes File:**
+## Options
 
-```javascript
-// src/routes.tsx
-import { createBrowserRouter } from 'react-router-dom'
-
-export const router = createBrowserRouter([
-  { path: '/', element: <Home /> },
-  { path: '/users/:id', element: <UserDetail /> },
-  { path: '/about', element: <About /> }
-])
-```
-
-## ⚙️ Configuration
-
-### Options
-
-```typescript
+```ts
 interface AnalyzerOptions {
-  // Required
-  projectName: string          // Name of your project
-
-  // Optional
-  baseUrl?: string            // Base URL of your API
-  apiKey?: string             // APIForge API key
-  apiForgeUrl?: string        // APIForge server URL (default: http://localhost:3000)
-  upload?: boolean            // Upload to APIForge (default: true if apiKey provided)
-  saveJson?: boolean          // Save routes to JSON file
-  jsonPath?: string           // Path for JSON file (default: api-export.json)
-  framework?: string          // Force framework detection
-  nextDir?: string            // Next.js directory or config file path
-  skipInProduction?: boolean  // Skip in production (default: true)
-}
-```
-
-### Environment Variables
-
-```bash
-APIFORGE_KEY=your-api-key
-APIFORGE_URL=http://localhost:3000  # or https://apiforge.dev
-NODE_ENV=development  # Analysis skipped if production
-```
+  projectName: string          // required
 
-## 📚 Framework Support
+  apiKey?: string              // APIForge API key — also read from APIFORGE_API_KEY env var
+  baseUrl?: string             // base URL shown in generated docs (e.g. https://api.myapp.com)
+  apiForgeUrl?: string         // override backend URL (default: https://apiforgeapi.brainfogagency.com)
 
-| Framework | Status | Import |
-|-----------|--------|--------|
-| Express | ✅ Full | `analyzeExpress` or `analyze` |
-| Next.js Pages | ✅ Full | `analyzeNextPages` |
-| Next.js App Router | ✅ Full | `analyzeNextApp` |
-| Vite | ✅ Full | `analyzeVite` |
-| React Router | ✅ Full | `analyzeReactRouter` |
+  upload?: boolean             // upload to dashboard (default: true when apiKey is set)
+  saveJson?: boolean           // write routes to a local JSON file
+  jsonPath?: string            // path for the JSON file (default: api-export.json)
 
-## 📖 Examples
+  architectureType?: 'monolithic' | 'modular-monolithic' | 'microservices'
+  service?: string             // service name for microservices mode — stamped on every route
 
-### Export to JSON Only
+  framework?: string           // skip auto-detection and force a framework
+  nextDir?: string             // directory or config file path for Next.js / Vite / React Router
 
-```javascript
-import { analyze } from 'apiforge-analyzer'
-
-await analyze(app, {
-  projectName: 'My API',
-  saveJson: true,
-  jsonPath: './docs/api.json',
-  upload: false  // Don't upload
-})
-```
-
-### Auto-Detection
-
-```javascript
-// Framework is auto-detected
-import { analyze } from 'apiforge-analyzer'
-
-await analyze(app, { projectName: 'My API' })
-```
-
-### Custom Config Paths
-
-```javascript
-// Vite with custom config
-await analyzeVite({
-  projectName: 'My App',
-  nextDir: 'vite.config.ts'  // Custom path
-})
-
-// React Router with custom routes file
-await analyzeReactRouter({
-  projectName: 'My App',
-  nextDir: 'src/app/routes.tsx'  // Custom path
-})
+  skipInProduction?: boolean   // skip when NODE_ENV=production (default: true)
+  runOnce?: boolean            // debounce — skip if analyzed within the last 30 s (default: true)
+}
 ```
 
-### Skip in Production
-
-```javascript
-// Automatically skips if NODE_ENV=production
-await analyze(app, {
-  projectName: 'My API',
-  skipInProduction: true  // Default
-})
+## Architecture detection
+
+The CLI scores structural signals to pick the right architecture automatically:
+
+| Signal | Architecture |
+|---|---|
+| `apiforge.config.json` with `services[]` | microservices |
+| `docker-compose.yml` with 3+ node services | microservices |
+| Multiple `package.json` files in sibling dirs | microservices |
+| `src/modules/` or `src/features/` directory | modular-monolithic |
+| `*.module.ts` files (NestJS `@Module`) | modular-monolithic |
+| None of the above | monolithic |
+
+For modular-monolithic projects, routes are automatically grouped by module using path-prefix matching — `/api/users/*` gets tagged as the `users` module.
+
+## Output format
+
+Each collected route:
+
+```ts
+{
+  method: 'GET',
+  path: '/api/users/:id',
+  tag: 'users',
+  operationId: 'get-api-users-id',
+  summary: 'Get api users',
+  middleware: ['authenticate'],
+  authRequired: true,
+  pathParams: ['id'],
+  queryParams: [],
+  requestBodyFields: [],
+  responseStatuses: [200, 404],
+  framework: 'express',
+  moduleName?: 'users',        // modular-monolithic only
+  serviceName?: 'auth-service' // microservices only
+}
 ```
 
-## 🔑 Getting an API Key
-
-1. Sign up at [APIForge](https://apiforge.dev)
-2. Go to Dashboard → API Keys
-3. Generate a new key
-4. Set `APIFORGE_KEY=your-key` in `.env`
-
-## 🛠️ Module Support
+## ESM and CommonJS
 
-This package supports both **ESM** and **CommonJS**:
-
-```javascript
+```js
 // ESM
 import { analyze } from 'apiforge-analyzer'
 
 // CommonJS
 const { analyze } = require('apiforge-analyzer')
-
-// Default import (CommonJS)
-const apiforge = require('apiforge-analyzer').default
 ```
 
-## 📝 What Gets Analyzed
-
-- ✅ Route paths
-- ✅ HTTP methods (GET, POST, PUT, DELETE, etc.)
-- ✅ Path parameters (`:id`, `:userId`)
-- ✅ Middleware names
-- ✅ Route tags/groups
-- ✅ Response codes
-- ✅ Proxy configurations (Vite)
-- ✅ Frontend routes (React Router)
-
-## 🧪 Testing Locally
-
-See [NPM_LINK_TEST.md](NPM_LINK_TEST.md) for detailed testing instructions using `npm link`.
-
-## 🤝 Contributing
+## Environment variables
 
-Pull requests welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md).
+| Variable | Description |
+|---|---|
+| `APIFORGE_API_KEY` | API key — loaded automatically, no dotenv required |
+| `APIFORGE_URL` | Override backend URL |
+| `NODE_ENV` | Set to `production` to disable analysis |
 
-## 📄 License
+## Get an API key
 
-MIT © APIForge
+[apiforge.brainfogagency.com/dashboard](https://apiforge.brainfogagency.com/dashboard)
 
----
+## License
 
-**Made with ❤️ by the APIForge team**
+MIT

package/dist/cjs/arch-detect.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectArchitectureType = detectArchitectureType;
+const fs_1 = require("fs");
+const path_1 = require("path");
+function detectArchitectureType(rootDir) {
+    let microScore = 0;
+    let modularScore = 0;
+    const evidence = [];
+    const servicePaths = [];
+    const moduleNames = [];
+    // ── Microservices signals ────────────────────────────────────────────────────
+    // Definitive: config file lists services[]
+    const configPaths = [(0, path_1.join)(rootDir, 'apiforge.config.ts'), (0, path_1.join)(rootDir, '.apiforge.json')];
+    for (const configPath of configPaths) {
+        if ((0, fs_1.existsSync)(configPath)) {
+            try {
+                const raw = (0, fs_1.readFileSync)(configPath, 'utf-8');
+                if (raw.includes('"services"') || raw.includes("'services'") || raw.includes('services:')) {
+                    microScore += 50;
+                    evidence.push(`Config file with services[]: ${(0, path_1.basename)(configPath)}`);
+                }
+            }
+            catch { }
+        }
+    }
+    // docker-compose.yml with multiple node service entries
+    const composePath = (0, path_1.join)(rootDir, 'docker-compose.yml');
+    if ((0, fs_1.existsSync)(composePath)) {
+        try {
+            const compose = (0, fs_1.readFileSync)(composePath, 'utf-8');
+            const serviceMatches = compose.match(/^\s{2}\w[\w-]+:/gm) || [];
+            if (serviceMatches.length >= 3) {
+                microScore += 35;
+                evidence.push(`docker-compose.yml with ${serviceMatches.length} services`);
+            }
+        }
+        catch { }
+    }
+    // Multiple sibling package.json at depth 1
+    const siblingPackages = findSiblingPackages(rootDir);
+    if (siblingPackages.length >= 2) {
+        microScore += 40;
+        siblingPackages.forEach(p => servicePaths.push(p));
+        evidence.push(`${siblingPackages.length} sibling package.json files (${siblingPackages.join(', ')})`);
+    }
+    // ── Modular Monolithic signals ────────────────────────────────────────────────
+    // NestJS module files anywhere in src/
+    const srcDir = (0, path_1.join)(rootDir, 'src');
+    if ((0, fs_1.existsSync)(srcDir)) {
+        const nestModules = findFilesRecursive(srcDir, '.module.ts');
+        if (nestModules.length > 0) {
+            modularScore += 40;
+            nestModules.forEach(f => {
+                const name = (0, path_1.basename)(f).replace('.module.ts', '');
+                if (!moduleNames.includes(name))
+                    moduleNames.push(name);
+            });
+            evidence.push(`NestJS @Module files: ${nestModules.map(f => (0, path_1.basename)(f)).join(', ')}`);
+        }
+        // src/modules/, src/features/, or src/domains/
+        for (const dir of ['modules', 'features', 'domains']) {
+            if ((0, fs_1.existsSync)((0, path_1.join)(srcDir, dir))) {
+                modularScore += 35;
+                evidence.push(`Feature-based directory: src/${dir}/`);
+                const subdirs = (0, fs_1.readdirSync)((0, path_1.join)(srcDir, dir), { withFileTypes: true })
+                    .filter(d => d.isDirectory())
+                    .map(d => d.name);
+                subdirs.forEach(name => { if (!moduleNames.includes(name))
+                    moduleNames.push(name); });
+                break;
+            }
+        }
+    }
+    // nest-cli.json at root
+    if ((0, fs_1.existsSync)((0, path_1.join)(rootDir, 'nest-cli.json'))) {
+        modularScore += 20;
+        evidence.push('nest-cli.json found');
+    }
+    // Classify
+    let type = 'monolithic';
+    let confidence = 0.6;
+    if (microScore >= 40) {
+        type = 'microservices';
+        confidence = Math.min(0.5 + microScore / 100, 0.98);
+    }
+    else if (modularScore >= 35) {
+        type = 'modular-monolithic';
+        confidence = Math.min(0.5 + modularScore / 100, 0.95);
+    }
+    if (evidence.length === 0) {
+        evidence.push('Single package.json, flat route structure');
+    }
+    return { type, confidence, evidence, moduleNames, servicePaths };
+}
+function findSiblingPackages(rootDir) {
+    const results = [];
+    try {
+        const entries = (0, fs_1.readdirSync)(rootDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (['node_modules', '.git', 'dist', '.next', 'build'].includes(entry.name))
+                continue;
+            const pkgPath = (0, path_1.join)(rootDir, entry.name, 'package.json');
+            if ((0, fs_1.existsSync)(pkgPath)) {
+                results.push(`./${entry.name}`);
+            }
+        }
+    }
+    catch { }
+    return results;
+}
+function findFilesRecursive(dir, suffix, maxDepth = 6, depth = 0) {
+    if (depth > maxDepth)
+        return [];
+    const results = [];
+    try {
+        const entries = (0, fs_1.readdirSync)(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name === 'node_modules' || entry.name === 'dist')
+                continue;
+            if (entry.isDirectory()) {
+                results.push(...findFilesRecursive((0, path_1.join)(dir, entry.name), suffix, maxDepth, depth + 1));
+            }
+            else if (entry.isFile() && entry.name.endsWith(suffix)) {
+                results.push((0, path_1.join)(dir, entry.name));
+            }
+        }
+    }
+    catch { }
+    return results;
+}