apiforge-analyzer 1.1.0 → 1.3.0

package/dist/esm/detect.js

@@ -1,65 +1,85 @@
+import { existsSync } from 'fs';
+import { join } from 'path';
+const cwd = () => process.cwd();
+function fileExists(rel) {
+    return existsSync(join(cwd(), rel));
+}
+function tryResolve(mod) {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        require.resolve(mod, { paths: [cwd()] });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
- * Framework detection utilities
- */
-/**
- * Detect which framework is being used
+ * Detect the web framework from the live app instance + filesystem hints.
+ * Confidence is used to pick the best match when multiple signals fire.
  */
 export function detectFramework(app) {
-    // Express detection
+    // ── Instance-based detection (highest confidence) ─────────────────────────
     if (app && typeof app === 'function') {
+        // Express: _router or lazyrouter
         if (app._router || (app.lazyrouter && typeof app.lazyrouter === 'function')) {
             return { name: 'express', confidence: 1.0 };
         }
-    }
-    // Next.js detection
-    try {
-        const fs = require('fs');
-        const path = require('path');
-        // Check for Next.js Pages Router
-        if (fs.existsSync(path.join(process.cwd(), 'pages'))) {
-            const hasApiFolder = fs.existsSync(path.join(process.cwd(), 'pages', 'api'));
-            if (hasApiFolder) {
-                return { name: 'nextjs-pages', confidence: 0.9 };
-            }
-        }
-        // Check for Next.js App Router
-        if (fs.existsSync(path.join(process.cwd(), 'app'))) {
-            return { name: 'nextjs-app', confidence: 0.9 };
+        // Koa: middleware array
+        if (Array.isArray(app.middleware) && typeof app.use === 'function' && app.context) {
+            return { name: 'koa', confidence: 0.95 };
         }
-        // Check for next.config
-        if (fs.existsSync(path.join(process.cwd(), 'next.config.js')) ||
-            fs.existsSync(path.join(process.cwd(), 'next.config.mjs'))) {
-            return { name: 'nextjs-pages', confidence: 0.7 };
-        }
-    }
-    catch (e) {
-        // Ignore fs errors
     }
-    // Vite detection
-    try {
-        require.resolve('vite');
-        return { name: 'vite', confidence: 0.8 };
+    // Fastify: inject method and route method
+    if (app &&
+        typeof app === 'object' &&
+        typeof app.inject === 'function' &&
+        typeof app.route === 'function') {
+        return { name: 'fastify', confidence: 1.0 };
     }
-    catch (e) {
-        // Vite not installed
+    // Hapi: server with route + start methods
+    if (app &&
+        typeof app === 'object' &&
+        typeof app.route === 'function' &&
+        typeof app.start === 'function' &&
+        typeof app.stop === 'function') {
+        return { name: 'hapi', confidence: 0.95 };
     }
-    // React Router detection
-    try {
-        require.resolve('react-router-dom');
-        return { name: 'react-router', confidence: 0.7 };
+    // NestJS application
+    if (app &&
+        typeof app === 'object' &&
+        typeof app.getHttpServer === 'function' &&
+        typeof app.listen === 'function') {
+        return { name: 'nestjs', confidence: 0.95 };
     }
-    catch (e) {
-        // React Router not installed
+    // ── Filesystem detection ──────────────────────────────────────────────────
+    // Next.js App Router
+    if (fileExists('app') && (fileExists('app/layout.tsx') || fileExists('app/layout.js'))) {
+        return { name: 'nextjs-app', confidence: 0.92 };
     }
-    // Node HTTP detection
-    try {
-        const http = require('http');
-        if (http) {
-            return { name: 'node-http', confidence: 0.5 };
-        }
+    // Next.js Pages Router
+    if (fileExists('pages/api') || fileExists('src/pages/api')) {
+        return { name: 'nextjs-pages', confidence: 0.90 };
     }
-    catch (e) {
-        // HTTP module not available
+    if (fileExists('next.config.js') ||
+        fileExists('next.config.mjs') ||
+        fileExists('next.config.ts')) {
+        return { name: 'nextjs-pages', confidence: 0.75 };
     }
+    // ── Dependency-based detection (lowest confidence) ────────────────────────
+    if (tryResolve('express'))
+        return { name: 'express', confidence: 0.70 };
+    if (tryResolve('fastify'))
+        return { name: 'fastify', confidence: 0.70 };
+    if (tryResolve('koa'))
+        return { name: 'koa', confidence: 0.70 };
+    if (tryResolve('@hapi/hapi') || tryResolve('hapi'))
+        return { name: 'hapi', confidence: 0.70 };
+    if (tryResolve('@nestjs/core'))
+        return { name: 'nestjs', confidence: 0.70 };
+    if (tryResolve('vite'))
+        return { name: 'vite', confidence: 0.60 };
+    if (tryResolve('react-router-dom'))
+        return { name: 'react-router', confidence: 0.55 };
     return { name: 'unknown', confidence: 0 };
 }

package/dist/esm/export.js

@@ -54,6 +54,8 @@ export function enrichRoute(route, index) {
         routeKey,
         tag,
         tags: route.tags?.length ? route.tags : [tag],
+        module: route.module,
+        service: route.service,
         summary: route.summary || generateSummary(route.method, route.path),
         description: route.description || generateDescription(route.method, route.path, tag),
         authRequired,

package/dist/esm/frameworks/express.js

@@ -1,7 +1,7 @@
 /**
- * Express analyzer — accurate route + payload extraction
+ * Express route analyzer — deep extraction of routes, parameters, and auth patterns
  */
-// ─── Path normalisation ───────────────────────────────────────────────────────
+// ─── Path helpers ─────────────────────────────────────────────────────────────
 function normalizePath(raw) {
     return raw
         .replace(/\\\//g, '/')
@@ -10,11 +10,10 @@ function normalizePath(raw) {
         .replace(/\\\w/g, '')
         .replace(/[\^\$\?\\]/g, '')
         .replace(/\/+/g, '/')
-        .replace(/\/$/, '')
-        || '/';
+        .replace(/\/$/, '') || '/';
 }
 function tagFromPath(path) {
-    const skip = new Set(['api', 'v1', 'v2', 'v3', 'v4']);
+    const skip = new Set(['api', 'v1', 'v2', 'v3', 'v4', 'v5']);
     const meaningful = path
         .split('/')
         .filter(Boolean)
@@ -24,18 +23,18 @@ function tagFromPath(path) {
 function generateSummary(method, path) {
     const parts = path.split('/').filter(s => s && !s.startsWith(':'));
     const action = parts[parts.length - 1] || '';
-    const resource = parts[parts.length - 2] || '';
+    const res = parts[parts.length - 2] || '';
     const map = {
-        GET: action ? `Get ${action}` : `List ${resource}`,
-        POST: action ? `Create ${action}` : `Create ${resource}`,
-        PUT: action ? `Update ${action}` : `Update ${resource}`,
-        PATCH: action ? `Patch ${action}` : `Patch ${resource}`,
-        DELETE: action ? `Delete ${action}` : `Delete ${resource}`,
+        GET: action ? `Get ${action}` : `List ${res}`,
+        POST: action ? `Create ${action}` : `Create ${res}`,
+        PUT: action ? `Update ${action}` : `Replace ${res}`,
+        PATCH: action ? `Patch ${action}` : `Patch ${res}`,
+        DELETE: action ? `Delete ${action}` : `Delete ${res}`,
     };
     const base = map[method] || `${method} ${path}`;
     return (base.charAt(0).toUpperCase() + base.slice(1)).replace(/[-_]/g, ' ');
 }
-// ─── Main analyser ────────────────────────────────────────────────────────────
+// ─── Main export ─────────────────────────────────────────────────────────────
 export function analyzeExpress(app) {
     const routes = [];
     const seen = new Set();
@@ -50,36 +49,45 @@ export function analyzeExpress(app) {
         console.warn('⚠️  No routes found — ensure routes are registered before analyze()');
         return routes;
     }
+    walkStack(stack, '', routes, seen);
+    return routes;
+}
+function walkStack(stack, basePath, out, seen) {
     for (const layer of stack) {
         if (layer.route) {
-            const r = buildRoute(layer.route, '');
+            const r = buildRoute(layer.route, basePath);
             if (r && !seen.has(r.method + r.path)) {
-                routes.push(r);
+                out.push(r);
                 seen.add(r.method + r.path);
             }
         }
         else if (layer.handle?.stack) {
-            let base = '';
+            // Router or sub-app mounted at a prefix
+            let prefix = '';
             if (layer.regexp?.source)
-                base = normalizePath(layer.regexp.source);
+                prefix = normalizePath(layer.regexp.source);
             else if (layer.path)
-                base = normalizePath(layer.path);
+                prefix = normalizePath(layer.path);
             else if (typeof layer.route === 'string')
-                base = normalizePath(layer.route);
-            for (const sub of layer.handle.stack) {
-                if (sub.route) {
-                    const r = buildRoute(sub.route, base);
-                    if (r && !seen.has(r.method + r.path)) {
-                        routes.push(r);
-                        seen.add(r.method + r.path);
-                    }
-                }
-            }
+                prefix = normalizePath(layer.route);
+            const combined = combinePaths(basePath, prefix);
+            walkStack(layer.handle.stack, combined, out, seen);
         }
     }
-    return routes;
+}
+function combinePaths(base, suffix) {
+    const b = base === '/' ? '' : base;
+    const s = suffix === '/' ? '' : suffix;
+    return b + s || '/';
 }
 // ─── Route builder ────────────────────────────────────────────────────────────
+const AUTH_NAMES = new Set([
+    'authenticateToken', 'authenticate', 'verifyToken', 'requireAuth',
+    'auth', 'protect', 'isAuth', 'checkAuth', 'jwtAuth', 'bearerAuth',
+    'isAuthenticated', 'requireLogin', 'ensureAuth', 'verifyJWT',
+    'checkToken', 'authMiddleware', 'jwt', 'bearer', 'apiKeyAuth',
+    'passport.authenticate',
+]);
 function buildRoute(route, basePath) {
     if (!route.path)
         return null;
@@ -100,59 +108,44 @@ function buildRoute(route, basePath) {
     const middleware = stack
         .map((l) => l.name)
         .filter((n) => n && n !== '<anonymous>' && n !== 'bound dispatch' && n !== 'bound ');
-    // ── Join all handler source text ───────────────────────────────────────────
+    // ── Join all handler source ────────────────────────────────────────────────
     const src = stack.map((l) => l.handle?.toString() ?? '').join('\n');
-    // ── Path params (from route pattern) ──────────────────────────────────────
+    // ── Path params from route pattern ─────────────────────────────────────────
     const pathParams = unique([...fullPath.matchAll(/:(\w+)/g)].map(m => m[1]));
     // ── Query params ───────────────────────────────────────────────────────────
     const queryParams = unique([
-        // req.query.foo
         ...matchAll(src, /req\.query\.([a-zA-Z0-9_$]+)/g),
-        // { foo, bar } = req.query  /  { foo: renamed } = req.query
         ...destructured(src, /(?:const|let|var)\s+\{([^}]+)\}\s*=\s*req\.query/g),
-        // req.query['foo']
         ...matchAll(src, /req\.query\[['"]([a-zA-Z0-9_$]+)['"]\]/g),
     ]);
     // ── Request body fields ────────────────────────────────────────────────────
     const requestBodyFields = unique([
-        // req.body.foo
         ...matchAll(src, /req\.body\.([a-zA-Z0-9_$]+)/g),
-        // { foo, bar: alias, baz = default } = req.body
         ...destructured(src, /(?:const|let|var)\s+\{([^}]+)\}\s*=\s*req\.body/g),
-        // req.body['foo']
         ...matchAll(src, /req\.body\[['"]([a-zA-Z0-9_$]+)['"]\]/g),
-        // body.foo (when `const body = req.body`)
         ...bodyAliasFields(src),
-        // Zod: z.object({ field: z.string() }).parse(req.body)
         ...zodFields(src),
-        // Joi: Joi.object({ field: Joi.string() }).validate(req.body)
         ...joiFields(src),
+        ...typeInterfaceFields(src),
     ]);
     // ── Header params ──────────────────────────────────────────────────────────
     const headerParams = unique([
         ...matchAll(src, /req\.headers\[['"]([a-zA-Z0-9_$-]+)['"]\]/g),
         ...matchAll(src, /req\.get\s*\(\s*['"]([a-zA-Z0-9_$-]+)['"]\s*\)/g),
-        // req.headers.authorization, req.headers['x-api-key'], etc.
         ...matchAll(src, /req\.headers\.([a-zA-Z0-9_$]+)/g),
     ]);
-    // ── Response status codes from `res.status(nnn)` ──────────────────────────
+    // ── Response status codes ──────────────────────────────────────────────────
     const responseStatuses = unique([...src.matchAll(/res\.status\s*\(\s*(\d{3})\s*\)/g)].map(m => parseInt(m[1], 10)));
     // ── Auth detection ─────────────────────────────────────────────────────────
-    const AUTH_NAMES = new Set([
-        'authenticateToken', 'authenticate', 'verifyToken', 'requireAuth', 'auth',
-        'protect', 'isAuth', 'checkAuth', 'jwtAuth', 'bearerAuth', 'isAuthenticated',
-        'requireLogin', 'ensureAuth', 'verifyJWT', 'checkToken', 'authMiddleware',
-        'passport.authenticate', 'jwt', 'bearer',
-    ]);
     const hasAuth = middleware.some(m => AUTH_NAMES.has(m) || [...AUTH_NAMES].some(a => m.toLowerCase().includes(a.toLowerCase()))) ||
-        /req\.user|req\.auth|verifyToken|jwt\.verify|passport\.authenticate/.test(src);
+        /req\.user|req\.auth|req\.currentUser|verifyToken|jwt\.verify|passport\.authenticate/.test(src);
     const method = methods[0];
     const tag = tagFromPath(fullPath);
     const summary = generateSummary(method, fullPath);
     const operationId = `${method.toLowerCase()}_${fullPath
         .replace(/[^a-zA-Z0-9]/g, '_')
         .replace(/_+/g, '_')
-        .replace(/^_|_$/g, '')}`;
+        .replace(/^_|_$/, '')}`;
     return {
         method,
         path: fullPath,
@@ -172,49 +165,33 @@ function buildRoute(route, basePath) {
     };
 }
 // ─── Extraction helpers ───────────────────────────────────────────────────────
-/** Run a global regex and return capture group 1 for every match. */
 function matchAll(src, re) {
     return [...src.matchAll(re)].map(m => m[1]).filter(Boolean);
 }
-/**
- * Extract field names from all destructuring patterns like:
- *   const { a, b: alias, c = default, d: alias2 = default } = req.body
- * Runs ALL occurrences of the given regex, not just the first.
- */
 function destructured(src, re) {
     const results = [];
     for (const match of src.matchAll(re)) {
         match[1]
             .split(',')
-            .map(s => s.trim())
-            // handle "alias: original" — we want the local binding (left side)
-            .map(s => s.split(':')[0].trim())
-            // strip default value
-            .map(s => s.split('=')[0].trim())
+            .map(s => s.trim().split(':')[0].trim().split('=')[0].trim())
             .filter(Boolean)
             .forEach(f => results.push(f));
     }
     return results;
 }
-/**
- * When a developer writes `const body = req.body` and then accesses `body.foo`.
- */
 function bodyAliasFields(src) {
-    const aliasMatch = src.match(/(?:const|let|var)\s+(\w+)\s*=\s*req\.body\b/);
-    if (!aliasMatch)
+    const m = src.match(/(?:const|let|var)\s+(\w+)\s*=\s*req\.body\b/);
+    if (!m)
         return [];
-    const alias = aliasMatch[1];
+    const alias = m[1];
     if (alias === 'body')
         return matchAll(src, /body\.([a-zA-Z0-9_$]+)/g);
     const re = new RegExp(`\\b${alias}\\.([a-zA-Z0-9_$]+)`, 'g');
     return matchAll(src, re);
 }
-/** Extract field names from Zod object schemas. */
 function zodFields(src) {
     const results = [];
-    // z.object({ field: z.xxx(), ... }).parse(req.body) or .safeParse
-    const zodRe = /z\.object\s*\(\s*\{([^}]+)\}/g;
-    for (const match of src.matchAll(zodRe)) {
+    for (const match of src.matchAll(/z\.object\s*\(\s*\{([^}]+)\}/g)) {
         match[1]
             .split(',')
             .map(s => s.trim().split(':')[0].trim())
@@ -223,12 +200,9 @@ function zodFields(src) {
     }
     return results;
 }
-/** Extract field names from Joi object schemas. */
 function joiFields(src) {
     const results = [];
-    // Joi.object({ field: Joi.xxx() }) or yup.object().shape({ field: ... })
-    const joiRe = /(?:Joi|yup)\.object\s*\(?\s*(?:\.shape\s*\()?\s*\{([^}]+)\}/g;
-    for (const match of src.matchAll(joiRe)) {
+    for (const match of src.matchAll(/(?:Joi|yup)\.object\s*\(?\s*(?:\.shape\s*\()?\s*\{([^}]+)\}/g)) {
         match[1]
             .split(',')
             .map(s => s.trim().split(':')[0].trim())
@@ -237,6 +211,38 @@ function joiFields(src) {
     }
     return results;
 }
+/**
+ * Detects TypeScript interface/type fields used as request body type parameters.
+ * Handles patterns like:
+ *   const { name, email } = req.body as CreateUserDto
+ *   function handler(req: Request<{}, {}, CreateUserBody>) { ... }
+ * This runs the interface declaration through a lightweight regex rather than a
+ * full TS AST to keep the package zero-dependency.
+ */
+function typeInterfaceFields(src) {
+    const results = [];
+    // Extract type name used as body generic: Request<P, ResBody, BodyType>
+    const bodyTypeNames = new Set();
+    for (const m of src.matchAll(/Request\s*<[^,]*,[^,]*,\s*([A-Z][a-zA-Z0-9_]*)\s*[,>]/g)) {
+        bodyTypeNames.add(m[1]);
+    }
+    // `req.body as SomeType`
+    for (const m of src.matchAll(/req\.body\s+as\s+([A-Z][a-zA-Z0-9_]*)/g)) {
+        bodyTypeNames.add(m[1]);
+    }
+    for (const typeName of bodyTypeNames) {
+        // Find interface { field: type; ... } or type alias { field: type }
+        const blockRe = new RegExp(`(?:interface|type)\\s+${typeName}\\s*(?:extends[^{]+)?\\{([^}]+)\\}`, 'g');
+        for (const match of src.matchAll(blockRe)) {
+            match[1]
+                .split(/[;,\n]/)
+                .map(line => line.trim().split(/[?:]/)[0].trim())
+                .filter(f => /^[a-zA-Z_$]/.test(f))
+                .forEach(f => results.push(f));
+        }
+    }
+    return results;
+}
 function unique(items) {
     return Array.from(new Set(items.filter(Boolean)));
 }

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);
+}