apiforge-analyzer 1.2.1 → 1.3.0

package/dist/esm/frameworks/nestjs.js

@@ -0,0 +1,35 @@
+import { analyzeExpress } from './express.js';
+import { detectNestModules } from '../modules/nestjs.js';
+import { detectExpressModules, annotateRoutesWithModules } from '../modules/express.js';
+/**
+ * Analyze a NestJS application by extracting the underlying Express (or Fastify)
+ * HTTP adapter and reusing the existing Express route-walker.
+ *
+ * NestJS wraps an inner Express app under app.getHttpServer()._events.request.
+ * When that's available we get full runtime accuracy. Otherwise we warn and
+ * fall back to an empty array so the CLI can report the limitation.
+ */
+export async function analyzeNestJS(app, rootDir) {
+    if (!app || typeof app.getHttpServer !== 'function') {
+        console.warn('⚠️  APIForge: NestJS app instance required. Pass the Nest application object.');
+        return [];
+    }
+    const httpServer = app.getHttpServer();
+    // NestJS wraps Express under _events.request when using the default adapter
+    const innerApp = httpServer?._events?.request ||
+        httpServer?._events?.['request'] ||
+        null;
+    if (!innerApp || typeof innerApp !== 'function') {
+        console.warn('⚠️  APIForge: Could not access inner Express adapter from NestJS app.');
+        return [];
+    }
+    const routes = await analyzeExpress(innerApp);
+    if (routes.length === 0)
+        return [];
+    // Detect module structure and annotate each route
+    const dir = rootDir || process.cwd();
+    const modules = detectNestModules(dir).length > 0
+        ? detectNestModules(dir)
+        : detectExpressModules(dir);
+    return annotateRoutesWithModules(routes, modules);
+}

package/dist/esm/index.js

@@ -8,9 +8,13 @@ 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 { analyzeNestJS } from './frameworks/nestjs.js';
 import { detectFramework } from './detect.js';
 import { exportToJSON } from './export.js';
 import { uploadRoutes, writeStatusFile } from './uploader.js';
+import { detectArchitectureType } from './arch-detect.js';
+import { detectExpressModules, annotateRoutesWithModules } from './modules/express.js';
+import { detectNestModules } from './modules/nestjs.js';
 // ─── Env file loader — no dotenv dependency ───────────────────────────────────
 /**
  * Read a single variable from a .env-style file.
@@ -66,8 +70,10 @@ export async function analyze(app, options) {
     if (options.skipInProduction !== false && process.env.NODE_ENV === 'production') {
         return [];
     }
-    // File-based debounce — survives nodemon restarts
-    if (options.runOnce !== false) {
+    // File-based debounce — survives nodemon restarts.
+    // Skipped in collection mode (statusFile set) because the CLI controls each service start
+    // and the shared .apiforge-last-run.json would cause services 2+ to be skipped.
+    if (options.runOnce !== false && !options.statusFile) {
         const elapsed = Date.now() - readLastRunMs();
         if (elapsed < DEBOUNCE_MS) {
             console.log(`⚡ APIForge: skipped (last run ${Math.round(elapsed / 1000)}s ago)`);
@@ -103,6 +109,9 @@ export async function analyze(app, options) {
     }
     try {
         switch (framework) {
+            case 'nestjs':
+                routes = await analyzeNestJS(app, options.nextDir || process.cwd());
+                break;
             case 'express':
                 if (!app) {
                     const msg = 'Express app instance required — pass your app object to analyze()';
@@ -111,6 +120,16 @@ export async function analyze(app, options) {
                     return [];
                 }
                 routes = await analyzeExpress(app);
+                // For modular-monolithic: annotate each route with its module name
+                if (options.architectureType === 'modular-monolithic') {
+                    const dir = options.nextDir || process.cwd();
+                    const modules = detectNestModules(dir).length > 0
+                        ? detectNestModules(dir)
+                        : detectExpressModules(dir);
+                    if (modules.length > 0) {
+                        routes = annotateRoutesWithModules(routes, modules);
+                    }
+                }
                 break;
             case 'nextjs-pages':
                 routes = await analyzeNextPages(options.nextDir || 'pages/api');
@@ -147,21 +166,36 @@ export async function analyze(app, options) {
     if (options.saveJson) {
         await exportToJSON(routes, options.projectName, options.jsonPath || 'api-export.json', options.baseUrl);
     }
+    // Stamp service name on routes if running in microservices mode
+    if (options.service) {
+        routes = routes.map(r => ({ ...r, service: options.service }));
+    }
+    // Multi-service collection mode: write routes to a per-service file for the CLI to aggregate.
+    // The CLI spawns each service individually, collects via this file, then uploads once.
+    if (options.statusFile) {
+        try {
+            writeFileSync(join(process.cwd(), options.statusFile), JSON.stringify({ status: 'collected', service: options.service, routes, routeCount: routes.length }), 'utf-8');
+        }
+        catch { }
+        return routes;
+    }
     if (options.upload !== false && options.apiKey) {
         await uploadRoutes(routes, {
             projectName: options.projectName,
             apiKey: options.apiKey,
             baseUrl: options.baseUrl,
             apiForgeUrl: options.apiForgeUrl,
+            architectureType: options.architectureType,
         });
     }
     return routes;
 }
 // Re-exports for library consumers
-export { analyzeExpress, analyzeNextPages, analyzeNextApp, analyzeVite, analyzeReactRouter };
+export { analyzeExpress, analyzeNextPages, analyzeNextApp, analyzeVite, analyzeReactRouter, analyzeNestJS };
 export { exportToJSON } from './export.js';
 export { uploadRoutes } from './uploader.js';
 export { detectFramework } from './detect.js';
+export { detectArchitectureType } from './arch-detect.js';
 export default {
     analyze,
     analyzeExpress,
@@ -169,7 +203,9 @@ export default {
     analyzeNextApp,
     analyzeVite,
     analyzeReactRouter,
+    analyzeNestJS,
     exportToJSON,
     uploadRoutes,
     detectFramework,
+    detectArchitectureType,
 };

package/dist/esm/modules/express.js

@@ -0,0 +1,60 @@
+import { existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+/**
+ * Detect Express feature-module structure by scanning standard directory patterns.
+ * Works for: src/modules/, src/features/, src/domains/ conventions.
+ */
+export function detectExpressModules(rootDir) {
+    const modules = [];
+    const srcDir = join(rootDir, 'src');
+    for (const parentDir of ['modules', 'features', 'domains']) {
+        const dir = existsSync(srcDir)
+            ? join(srcDir, parentDir)
+            : join(rootDir, parentDir);
+        if (!existsSync(dir))
+            continue;
+        const subdirs = readdirSync(dir, { withFileTypes: true })
+            .filter(entry => entry.isDirectory())
+            .map(entry => entry.name);
+        for (const name of subdirs) {
+            const routePrefix = `/${name}`;
+            modules.push({ name, routePrefix });
+        }
+        if (modules.length > 0)
+            break;
+    }
+    return modules;
+}
+/**
+ * Given a route path, return the module name it belongs to.
+ * Falls back to the tag (first meaningful path segment) when no module matches.
+ */
+export function resolveModuleForPath(routePath, modules) {
+    if (modules.length === 0)
+        return undefined;
+    // Strip /api/v1/ etc. prefixes before matching
+    const normalized = routePath.replace(/^\/(api\/)?(v\d+\/)?/, '/');
+    for (const mod of modules) {
+        if (normalized.startsWith(mod.routePrefix + '/') || normalized === mod.routePrefix) {
+            return mod.name;
+        }
+    }
+    // Fallback: first non-param, non-version segment
+    const segment = normalized.split('/').filter(s => s && !s.startsWith(':'))[0];
+    return segment || undefined;
+}
+/**
+ * Annotate a list of routes with their module names using path-prefix matching.
+ */
+export function annotateRoutesWithModules(routes, modules) {
+    return routes.map(route => ({
+        ...route,
+        module: resolveModuleForPath(route.path, modules) || inferModuleFromPath(route.path),
+    }));
+}
+function inferModuleFromPath(routePath) {
+    const skip = new Set(['api', 'v1', 'v2', 'v3']);
+    return (routePath
+        .split('/')
+        .filter(s => s && !s.startsWith(':') && !skip.has(s))[0] || 'general');
+}

package/dist/esm/modules/nestjs.js

@@ -0,0 +1,47 @@
+import { existsSync, readdirSync } from 'fs';
+import { join, basename } from 'path';
+/**
+ * Detect NestJS modules by scanning for *.module.ts files and extracting
+ * their declared controllers with the @Module() decorator.
+ */
+export function detectNestModules(rootDir) {
+    const srcDir = join(rootDir, 'src');
+    const searchDir = existsSync(srcDir) ? srcDir : rootDir;
+    const moduleFiles = findModuleFiles(searchDir);
+    if (moduleFiles.length === 0)
+        return [];
+    const modules = [];
+    for (const filePath of moduleFiles) {
+        const name = basename(filePath).replace('.module.ts', '');
+        // Skip the root AppModule — it's the container, not a domain module
+        if (name === 'app')
+            continue;
+        const routePrefix = inferPrefixFromModuleName(name);
+        modules.push({ name, routePrefix });
+    }
+    return modules;
+}
+function findModuleFiles(dir, depth = 0) {
+    if (depth > 8)
+        return [];
+    const results = [];
+    try {
+        const entries = readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (['node_modules', 'dist', '.next'].includes(entry.name))
+                continue;
+            if (entry.isDirectory()) {
+                results.push(...findModuleFiles(join(dir, entry.name), depth + 1));
+            }
+            else if (entry.isFile() && entry.name.endsWith('.module.ts')) {
+                results.push(join(dir, entry.name));
+            }
+        }
+    }
+    catch { }
+    return results;
+}
+function inferPrefixFromModuleName(name) {
+    // user-profile → /user-profile, users → /users
+    return `/${name}`;
+}

package/dist/esm/uploader.js

@@ -34,13 +34,15 @@ export async function uploadRoutes(routes, options) {
         routes: enrichedRoutes,
         baseUrl: options.baseUrl,
         framework: enrichedRoutes[0]?.framework || 'unknown',
+        architectureType: options.architectureType || 'monolithic',
+        services: options.services || [],
     };
     try {
         const response = await axios.post(`${backendUrl}/api/cli/submit`, payload, {
             headers: {
                 'Content-Type': 'application/json',
                 'X-API-Key': options.apiKey,
-                'User-Agent': 'apiforge-analyzer/1.2.0',
+                'User-Agent': 'apiforge-analyzer/1.3.0',
             },
             timeout: 30000,
         });

package/dist/types/arch-detect.d.ts

@@ -0,0 +1,9 @@
+export type ArchitectureType = 'monolithic' | 'modular-monolithic' | 'microservices';
+export interface ArchDetectResult {
+    type: ArchitectureType;
+    confidence: number;
+    evidence: string[];
+    moduleNames: string[];
+    servicePaths: string[];
+}
+export declare function detectArchitectureType(rootDir: string): ArchDetectResult;

package/dist/types/export.d.ts

@@ -28,6 +28,8 @@ export interface Route {
     linkedPaths: string[];
     hasAuth: boolean;
     framework: string;
+    module?: string;
+    service?: string;
     sourceContext?: Record<string, any>;
 }
 /**

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

@@ -0,0 +1,10 @@
+import type { Route } from '../export.js';
+/**
+ * Analyze a NestJS application by extracting the underlying Express (or Fastify)
+ * HTTP adapter and reusing the existing Express route-walker.
+ *
+ * NestJS wraps an inner Express app under app.getHttpServer()._events.request.
+ * When that's available we get full runtime accuracy. Otherwise we warn and
+ * fall back to an empty array so the CLI can report the limitation.
+ */
+export declare function analyzeNestJS(app: any, rootDir?: string): Promise<Route[]>;

package/dist/types/index.d.ts

@@ -6,9 +6,12 @@ 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 { analyzeNestJS } from './frameworks/nestjs.js';
 import { detectFramework } from './detect.js';
 import { exportToJSON } from './export.js';
 import { uploadRoutes } from './uploader.js';
+import { detectArchitectureType } from './arch-detect.js';
+import type { ArchitectureType } from './arch-detect.js';
 export interface AnalyzerOptions {
     projectName: string;
     baseUrl?: string;
@@ -21,12 +24,17 @@ export interface AnalyzerOptions {
     nextDir?: string;
     skipInProduction?: boolean;
     runOnce?: boolean;
+    architectureType?: ArchitectureType;
+    service?: string;
+    /** CLI multi-service mode: write routes to this file and exit without uploading */
+    statusFile?: string;
 }
 export declare function analyze(app: any, options: AnalyzerOptions): Promise<any[]>;
-export { analyzeExpress, analyzeNextPages, analyzeNextApp, analyzeVite, analyzeReactRouter };
+export { analyzeExpress, analyzeNextPages, analyzeNextApp, analyzeVite, analyzeReactRouter, analyzeNestJS };
 export { exportToJSON } from './export.js';
 export { uploadRoutes } from './uploader.js';
 export { detectFramework } from './detect.js';
+export { detectArchitectureType } from './arch-detect.js';
 declare const _default: {
     analyze: typeof analyze;
     analyzeExpress: typeof analyzeExpress;
@@ -34,8 +42,10 @@ declare const _default: {
     analyzeNextApp: typeof analyzeNextApp;
     analyzeVite: typeof analyzeVite;
     analyzeReactRouter: typeof analyzeReactRouter;
+    analyzeNestJS: typeof analyzeNestJS;
     exportToJSON: typeof exportToJSON;
     uploadRoutes: typeof uploadRoutes;
     detectFramework: typeof detectFramework;
+    detectArchitectureType: typeof detectArchitectureType;
 };
 export default _default;

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

@@ -0,0 +1,22 @@
+export interface ModuleInfo {
+    name: string;
+    routePrefix: string;
+}
+/**
+ * Detect Express feature-module structure by scanning standard directory patterns.
+ * Works for: src/modules/, src/features/, src/domains/ conventions.
+ */
+export declare function detectExpressModules(rootDir: string): ModuleInfo[];
+/**
+ * Given a route path, return the module name it belongs to.
+ * Falls back to the tag (first meaningful path segment) when no module matches.
+ */
+export declare function resolveModuleForPath(routePath: string, modules: ModuleInfo[]): string | undefined;
+/**
+ * Annotate a list of routes with their module names using path-prefix matching.
+ */
+export declare function annotateRoutesWithModules<T extends {
+    path: string;
+}>(routes: T[], modules: ModuleInfo[]): (T & {
+    module: string;
+})[];

package/dist/types/modules/nestjs.d.ts

@@ -0,0 +1,6 @@
+import type { ModuleInfo } from './express.js';
+/**
+ * Detect NestJS modules by scanning for *.module.ts files and extracting
+ * their declared controllers with the @Module() decorator.
+ */
+export declare function detectNestModules(rootDir: string): ModuleInfo[];

package/dist/types/uploader.d.ts

@@ -1,9 +1,16 @@
 import { Route } from './export.js';
+import type { ArchitectureType } from './arch-detect.js';
+export interface ServiceMeta {
+    name: string;
+    baseUrl?: string;
+}
 export interface UploadOptions {
     projectName: string;
     baseUrl?: string;
     apiForgeUrl?: string;
     apiKey: string;
+    architectureType?: ArchitectureType;
+    services?: ServiceMeta[];
 }
 export interface UploadResult {
     pendingImportId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apiforge-analyzer",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Universal API documentation generator for Express, Next.js, Vite, React Router, and Node.js",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -26,7 +26,8 @@
     "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"
+    "prepublishOnly": "npm run build",
+    "test": "node ../test-apps/run-all.cjs"
   },
   "keywords": [
     "api",