apiforge-analyzer 1.3.1 → 1.3.2

package/dist/cjs/cli.js

@@ -27,7 +27,7 @@ const green = (s) => `${gn}${s}${r}`;
 const yellow = (s) => `${yl}${s}${r}`;
 const red = (s) => `${rd}${s}${r}`;
 const white = (s) => `${wh}${s}${r}`;
-const VERSION = '1.3.1';
+const VERSION = '1.3.2';
 // Built-in URLs — users never need to configure these
 const BACKEND_PROD = 'https://apiforgeapi.brainfogagency.com';
 const DASHBOARD_PROD = 'https://apiforge.brainfogagency.com/dashboard';
@@ -395,6 +395,158 @@ function hasDockerCompose(cwd) {
     return ['docker-compose.yml', 'docker-compose.yaml', 'compose.yml', 'compose.yaml']
         .some(f => (0, fs_1.existsSync)((0, path_1.join)(cwd, f)));
 }
+/**
+ * Find the gateway among the discovered services (by name or by proxy-middleware
+ * usage) and parse its prefix → service map, e.g. { auth: '/auth', gold_rates: '/gold-rates' }.
+ * Matches the common `'/prefix': process.env.X_SERVICE_URL || ...` gateway route-table
+ * pattern (express-gateway / http-proxy-middleware style). Returns {} if no gateway
+ * or no recognizable mapping is found — callers should treat that as "no rewrite."
+ */
+function detectGatewayPrefixMap(cwd, services) {
+    const prefixMap = {};
+    for (const svc of services) {
+        const svcDir = svc.dir.replace(/^\.\//, '');
+        const relEntry = svc.entryFile ?? findEntryInDir((0, path_1.join)(cwd, svcDir));
+        if (!relEntry)
+            continue;
+        let source = '';
+        try {
+            source = (0, fs_1.readFileSync)((0, path_1.join)(cwd, svcDir, relEntry), 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        const looksLikeGateway = /gateway/i.test(svc.name) || /createProxyMiddleware|http-proxy-middleware/.test(source);
+        if (!looksLikeGateway)
+            continue;
+        // '/auth': process.env.AUTH_SERVICE_URL || `http://...`
+        const re = /['"](\/[a-zA-Z0-9_-]*)['"]\s*:\s*process\.env\.([A-Z][A-Z0-9_]*)/g;
+        let m;
+        while ((m = re.exec(source))) {
+            const prefix = m[1];
+            const serviceName = m[2].replace(/_SERVICE_URL$|_URL$/, '').toLowerCase();
+            if (!prefixMap[serviceName])
+                prefixMap[serviceName] = prefix; // first (primary) mount wins over aliases
+        }
+        if (Object.keys(prefixMap).length > 0)
+            break;
+    }
+    return prefixMap;
+}
+function withGatewayPrefix(prefix, routePath) {
+    if (routePath === '/')
+        return prefix;
+    return prefix.replace(/\/$/, '') + (routePath.startsWith('/') ? routePath : `/${routePath}`);
+}
+// ─── Postman collection enrichment ─────────────────────────────────────────────
+// Runtime introspection only sees field NAMES (via regex over handler source),
+// never real example values — a Postman collection, when present, already has
+// hand-written example bodies and descriptions. We fold those in as enrichment
+// only: matched by method + path, never adds or removes an endpoint.
+function findFileRecursive(dir, matches, maxDepth, depth = 0) {
+    if (depth > maxDepth)
+        return null;
+    let entries;
+    try {
+        entries = (0, fs_1.readdirSync)(dir, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+    for (const e of entries) {
+        if (e.isFile() && matches(e.name))
+            return (0, path_1.join)(dir, e.name);
+    }
+    for (const e of entries) {
+        if (e.isDirectory() && !['node_modules', '.git', 'dist', 'build', '.next'].includes(e.name)) {
+            const found = findFileRecursive((0, path_1.join)(dir, e.name), matches, maxDepth, depth + 1);
+            if (found)
+                return found;
+        }
+    }
+    return null;
+}
+function findPostmanCollection(cwd) {
+    const isCollection = (name) => name.endsWith('.postman_collection.json');
+    for (const dir of ['postman', 'docs/postman', '.postman', 'collections']) {
+        const dirPath = (0, path_1.join)(cwd, dir);
+        if (!(0, fs_1.existsSync)(dirPath))
+            continue;
+        try {
+            const match = (0, fs_1.readdirSync)(dirPath).find(isCollection);
+            if (match)
+                return (0, path_1.join)(dirPath, match);
+        }
+        catch { }
+    }
+    return findFileRecursive(cwd, isCollection, 3);
+}
+/** "{{baseUrl}}/gold-rates/graph/{{userId}}?interval=x" -> "/gold-rates/graph/:userId" */
+function postmanRawToRoutePath(raw) {
+    let p = raw.trim();
+    p = p.replace(/^\{\{[^}]+\}\}/, '');
+    p = p.split('?')[0];
+    p = p.replace(/\{\{([a-zA-Z0-9_]+)\}\}/g, ':$1');
+    if (!p)
+        p = '/';
+    if (!p.startsWith('/'))
+        p = '/' + p;
+    if (p !== '/' && p.endsWith('/'))
+        p = p.slice(0, -1);
+    return p;
+}
+/** Recursively walk a Postman collection's item tree (folders nest via `item`; requests carry `request`). */
+function walkPostmanItems(items, index) {
+    for (const node of items ?? []) {
+        if (Array.isArray(node.item))
+            walkPostmanItems(node.item, index);
+        if (!node.request)
+            continue;
+        const req = node.request;
+        const method = String(req.method || 'GET').toUpperCase();
+        const rawUrl = typeof req.url === 'string' ? req.url : req.url?.raw;
+        if (!rawUrl)
+            continue;
+        const key = `${method} ${postmanRawToRoutePath(rawUrl)}`;
+        if (index.has(key))
+            continue; // first match wins — collection often repeats the same endpoint in a smoke-test folder
+        const entry = {};
+        if (req.body?.mode === 'raw' && typeof req.body.raw === 'string' && req.body.raw.trim()) {
+            entry.bodyExample = req.body.raw.trim();
+        }
+        if (typeof req.description === 'string' && req.description.trim()) {
+            entry.description = req.description.trim();
+        }
+        if (entry.bodyExample || entry.description)
+            index.set(key, entry);
+    }
+}
+/** Enrich collected routes in-place with Postman example bodies/descriptions, matched by method+path. Never adds or drops routes. */
+function enrichRoutesFromPostman(cwd, routes) {
+    const collectionPath = findPostmanCollection(cwd);
+    if (!collectionPath)
+        return;
+    try {
+        const collection = JSON.parse((0, fs_1.readFileSync)(collectionPath, 'utf-8'));
+        const index = new Map();
+        walkPostmanItems(collection.item, index);
+        let enriched = 0;
+        for (const route of routes) {
+            const match = index.get(`${route.method} ${route.path}`);
+            if (!match)
+                continue;
+            if (match.bodyExample)
+                route.bodyExample = match.bodyExample;
+            if (match.description && !route.description)
+                route.description = match.description;
+            enriched++;
+        }
+        if (enriched > 0) {
+            prompts_1.log.info(dim(`Enriched ${enriched} routes with examples from ${(0, path_1.basename)(collectionPath)}`));
+        }
+    }
+    catch { }
+}
 async function microservicesFlow(config, opts) {
     const cwd = process.cwd();
     const allRoutes = [];
@@ -437,6 +589,14 @@ async function microservicesFlow(config, opts) {
         '',
         dim('Each service is started individually and its routes are collected.'),
     ].join('\n'), 'Multi-service analysis');
+    // Routes are collected at each service's own internal paths (e.g. auth's /register),
+    // not the path clients actually call through the gateway (/auth/register) — Express
+    // strips the mount prefix before the service ever sees the request. Rewrite paths
+    // here so the docs match what's actually callable.
+    const gatewayPrefixes = detectGatewayPrefixMap(cwd, config.services);
+    if (Object.keys(gatewayPrefixes).length > 0) {
+        prompts_1.log.info(dim(`Gateway prefixes detected: ${Object.entries(gatewayPrefixes).map(([s, p]) => `${s}→${p}`).join(', ')}`));
+    }
     for (const svc of config.services) {
         const svcSpin = (0, prompts_1.spinner)();
         svcSpin.start(`${bold(svc.name)} — starting…`);
@@ -465,13 +625,14 @@ async function microservicesFlow(config, opts) {
             detached: false,
         });
         // Capture output so failures are debuggable without re-running the service by hand.
-        // Bounded to the last ~4000 chars so a chatty/looping service can't blow up memory.
+        // Keep the HEAD, not the tail: Node prints "Error: ..." / "Cannot find module ..."
+        // first, then unwinds the call stack — a long stack trace must not push that
+        // opening line out of the window, so stop growing once capped instead of sliding.
         let output = '';
-        const MAX_OUTPUT = 4000;
+        const MAX_OUTPUT = 6000;
         const capture = (chunk) => {
-            output += chunk.toString();
-            if (output.length > MAX_OUTPUT)
-                output = output.slice(-MAX_OUTPUT);
+            if (output.length < MAX_OUTPUT)
+                output += chunk.toString();
         };
         child.stdout?.on('data', capture);
         child.stderr?.on('data', capture);
@@ -484,7 +645,12 @@ async function microservicesFlow(config, opts) {
         catch { }
         tryUnlink((0, path_1.join)(cwd, statusFile));
         if (routes && routes.length > 0) {
-            const annotated = routes.map((r) => ({ ...r, service: svc.name }));
+            const prefix = gatewayPrefixes[svc.name];
+            const annotated = routes.map((r) => ({
+                ...r,
+                service: svc.name,
+                path: prefix ? withGatewayPrefix(prefix, r.path) : r.path,
+            }));
             allRoutes.push(...annotated);
             serviceMeta.push({ name: svc.name, baseUrl: svc.baseUrl });
             svcSpin.stop(green(`✓ ${svc.name} — ${routes.length} routes collected`));
@@ -493,7 +659,7 @@ async function microservicesFlow(config, opts) {
             svcSpin.stop(yellow(`◌ ${svc.name} — no routes collected (timeout or error)`));
             const trimmed = output.trim();
             if (trimmed) {
-                prompts_1.log.error(dim(`   ${bold(svc.name)} output:\n` + trimmed.split('\n').slice(-20).map(l => `   ${l}`).join('\n')));
+                prompts_1.log.error(dim(`   ${bold(svc.name)} output:\n` + trimmed.split('\n').slice(0, 30).map(l => `   ${l}`).join('\n')));
             }
         }
         // Remove injected code
@@ -503,6 +669,7 @@ async function microservicesFlow(config, opts) {
     // Safety: clean up any remaining injections (e.g. if process was interrupted)
     for (const f of injectedFiles)
         removeInjectedCode(f);
+    enrichRoutesFromPostman(cwd, allRoutes);
     if (allRoutes.length === 0) {
         prompts_1.log.error(red('No routes were collected from any service.'));
         (0, prompts_1.outro)(red('Analysis failed.'));
@@ -1023,13 +1190,33 @@ function buildSnippet(projectName, apiKey, baseUrl, backendUrl, appVar, isESM, a
             `    upload: true,`,
             `    runOnce: true,`,
         ].join('\n');
+    // Collection mode: some services only mount routes inside an async bootstrap
+    // gated behind a DB/broker connect (which may hang/fail outside Docker).
+    // Poll briefly for app._router to be populated (Express-shaped apps only)
+    // before giving up and collecting whatever is there — bounded well under
+    // the CLI's 30s per-service timeout so a hung connect still surfaces.
+    const runAnalyze = `APIForge.analyze(${appVar}, {\n${opts}\n  })`;
+    const call = collectionOpts
+        ? [
+            `  let __apiforgeTries = 0`,
+            `  const __apiforgeTryCollect = () => {`,
+            `    const hasRoutes = !${appVar} || !${appVar}._router`,
+            `      ? true`,
+            `      : Array.isArray(${appVar}._router.stack) && ${appVar}._router.stack.length > 0`,
+            `    if (hasRoutes || __apiforgeTries++ >= 26) {`,
+            `      ${runAnalyze}`,
+            `    } else {`,
+            `      setTimeout(__apiforgeTryCollect, 300)`,
+            `    }`,
+            `  }`,
+            `  __apiforgeTryCollect()`,
+        ].join('\n')
+        : `  ${runAnalyze}`;
     if (isESM) {
         return [
             `// APIForge — https://apiforge.brainfogagency.com`,
             `import('apiforge-analyzer').then(({ default: APIForge }) => {`,
-            `  APIForge.analyze(${appVar}, {`,
-            opts,
-            `  })`,
+            call,
             `}).catch(() => {})`,
             '',
         ].join('\n');
@@ -1038,9 +1225,7 @@ function buildSnippet(projectName, apiKey, baseUrl, backendUrl, appVar, isESM, a
         `// APIForge — https://apiforge.brainfogagency.com`,
         `Promise.resolve().then(() => require('apiforge-analyzer')).then(mod => {`,
         `  const APIForge = mod.default || mod`,
-        `  APIForge.analyze(${appVar}, {`,
-        opts,
-        `  })`,
+        call,
         `}).catch(() => {})`,
         '',
     ].join('\n');

package/dist/esm/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { group, intro, outro, text, select, password, confirm, tasks, note, log, isCancel, cancel, spinner, } from '@clack/prompts';
 import { readFileSync, existsSync, writeFileSync, unlinkSync, readdirSync } from 'fs';
-import { join } from 'path';
+import { join, basename } from 'path';
 import { spawn } from 'child_process';
 import axios from 'axios';
 import { detectArchitectureType } from './arch-detect.js';
@@ -22,7 +22,7 @@ const green = (s) => `${gn}${s}${r}`;
 const yellow = (s) => `${yl}${s}${r}`;
 const red = (s) => `${rd}${s}${r}`;
 const white = (s) => `${wh}${s}${r}`;
-const VERSION = '1.3.1';
+const VERSION = '1.3.2';
 // Built-in URLs — users never need to configure these
 const BACKEND_PROD = 'https://apiforgeapi.brainfogagency.com';
 const DASHBOARD_PROD = 'https://apiforge.brainfogagency.com/dashboard';
@@ -390,6 +390,158 @@ function hasDockerCompose(cwd) {
     return ['docker-compose.yml', 'docker-compose.yaml', 'compose.yml', 'compose.yaml']
         .some(f => existsSync(join(cwd, f)));
 }
+/**
+ * Find the gateway among the discovered services (by name or by proxy-middleware
+ * usage) and parse its prefix → service map, e.g. { auth: '/auth', gold_rates: '/gold-rates' }.
+ * Matches the common `'/prefix': process.env.X_SERVICE_URL || ...` gateway route-table
+ * pattern (express-gateway / http-proxy-middleware style). Returns {} if no gateway
+ * or no recognizable mapping is found — callers should treat that as "no rewrite."
+ */
+function detectGatewayPrefixMap(cwd, services) {
+    const prefixMap = {};
+    for (const svc of services) {
+        const svcDir = svc.dir.replace(/^\.\//, '');
+        const relEntry = svc.entryFile ?? findEntryInDir(join(cwd, svcDir));
+        if (!relEntry)
+            continue;
+        let source = '';
+        try {
+            source = readFileSync(join(cwd, svcDir, relEntry), 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        const looksLikeGateway = /gateway/i.test(svc.name) || /createProxyMiddleware|http-proxy-middleware/.test(source);
+        if (!looksLikeGateway)
+            continue;
+        // '/auth': process.env.AUTH_SERVICE_URL || `http://...`
+        const re = /['"](\/[a-zA-Z0-9_-]*)['"]\s*:\s*process\.env\.([A-Z][A-Z0-9_]*)/g;
+        let m;
+        while ((m = re.exec(source))) {
+            const prefix = m[1];
+            const serviceName = m[2].replace(/_SERVICE_URL$|_URL$/, '').toLowerCase();
+            if (!prefixMap[serviceName])
+                prefixMap[serviceName] = prefix; // first (primary) mount wins over aliases
+        }
+        if (Object.keys(prefixMap).length > 0)
+            break;
+    }
+    return prefixMap;
+}
+function withGatewayPrefix(prefix, routePath) {
+    if (routePath === '/')
+        return prefix;
+    return prefix.replace(/\/$/, '') + (routePath.startsWith('/') ? routePath : `/${routePath}`);
+}
+// ─── Postman collection enrichment ─────────────────────────────────────────────
+// Runtime introspection only sees field NAMES (via regex over handler source),
+// never real example values — a Postman collection, when present, already has
+// hand-written example bodies and descriptions. We fold those in as enrichment
+// only: matched by method + path, never adds or removes an endpoint.
+function findFileRecursive(dir, matches, maxDepth, depth = 0) {
+    if (depth > maxDepth)
+        return null;
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+    for (const e of entries) {
+        if (e.isFile() && matches(e.name))
+            return join(dir, e.name);
+    }
+    for (const e of entries) {
+        if (e.isDirectory() && !['node_modules', '.git', 'dist', 'build', '.next'].includes(e.name)) {
+            const found = findFileRecursive(join(dir, e.name), matches, maxDepth, depth + 1);
+            if (found)
+                return found;
+        }
+    }
+    return null;
+}
+function findPostmanCollection(cwd) {
+    const isCollection = (name) => name.endsWith('.postman_collection.json');
+    for (const dir of ['postman', 'docs/postman', '.postman', 'collections']) {
+        const dirPath = join(cwd, dir);
+        if (!existsSync(dirPath))
+            continue;
+        try {
+            const match = readdirSync(dirPath).find(isCollection);
+            if (match)
+                return join(dirPath, match);
+        }
+        catch { }
+    }
+    return findFileRecursive(cwd, isCollection, 3);
+}
+/** "{{baseUrl}}/gold-rates/graph/{{userId}}?interval=x" -> "/gold-rates/graph/:userId" */
+function postmanRawToRoutePath(raw) {
+    let p = raw.trim();
+    p = p.replace(/^\{\{[^}]+\}\}/, '');
+    p = p.split('?')[0];
+    p = p.replace(/\{\{([a-zA-Z0-9_]+)\}\}/g, ':$1');
+    if (!p)
+        p = '/';
+    if (!p.startsWith('/'))
+        p = '/' + p;
+    if (p !== '/' && p.endsWith('/'))
+        p = p.slice(0, -1);
+    return p;
+}
+/** Recursively walk a Postman collection's item tree (folders nest via `item`; requests carry `request`). */
+function walkPostmanItems(items, index) {
+    for (const node of items ?? []) {
+        if (Array.isArray(node.item))
+            walkPostmanItems(node.item, index);
+        if (!node.request)
+            continue;
+        const req = node.request;
+        const method = String(req.method || 'GET').toUpperCase();
+        const rawUrl = typeof req.url === 'string' ? req.url : req.url?.raw;
+        if (!rawUrl)
+            continue;
+        const key = `${method} ${postmanRawToRoutePath(rawUrl)}`;
+        if (index.has(key))
+            continue; // first match wins — collection often repeats the same endpoint in a smoke-test folder
+        const entry = {};
+        if (req.body?.mode === 'raw' && typeof req.body.raw === 'string' && req.body.raw.trim()) {
+            entry.bodyExample = req.body.raw.trim();
+        }
+        if (typeof req.description === 'string' && req.description.trim()) {
+            entry.description = req.description.trim();
+        }
+        if (entry.bodyExample || entry.description)
+            index.set(key, entry);
+    }
+}
+/** Enrich collected routes in-place with Postman example bodies/descriptions, matched by method+path. Never adds or drops routes. */
+function enrichRoutesFromPostman(cwd, routes) {
+    const collectionPath = findPostmanCollection(cwd);
+    if (!collectionPath)
+        return;
+    try {
+        const collection = JSON.parse(readFileSync(collectionPath, 'utf-8'));
+        const index = new Map();
+        walkPostmanItems(collection.item, index);
+        let enriched = 0;
+        for (const route of routes) {
+            const match = index.get(`${route.method} ${route.path}`);
+            if (!match)
+                continue;
+            if (match.bodyExample)
+                route.bodyExample = match.bodyExample;
+            if (match.description && !route.description)
+                route.description = match.description;
+            enriched++;
+        }
+        if (enriched > 0) {
+            log.info(dim(`Enriched ${enriched} routes with examples from ${basename(collectionPath)}`));
+        }
+    }
+    catch { }
+}
 async function microservicesFlow(config, opts) {
     const cwd = process.cwd();
     const allRoutes = [];
@@ -432,6 +584,14 @@ async function microservicesFlow(config, opts) {
         '',
         dim('Each service is started individually and its routes are collected.'),
     ].join('\n'), 'Multi-service analysis');
+    // Routes are collected at each service's own internal paths (e.g. auth's /register),
+    // not the path clients actually call through the gateway (/auth/register) — Express
+    // strips the mount prefix before the service ever sees the request. Rewrite paths
+    // here so the docs match what's actually callable.
+    const gatewayPrefixes = detectGatewayPrefixMap(cwd, config.services);
+    if (Object.keys(gatewayPrefixes).length > 0) {
+        log.info(dim(`Gateway prefixes detected: ${Object.entries(gatewayPrefixes).map(([s, p]) => `${s}→${p}`).join(', ')}`));
+    }
     for (const svc of config.services) {
         const svcSpin = spinner();
         svcSpin.start(`${bold(svc.name)} — starting…`);
@@ -460,13 +620,14 @@ async function microservicesFlow(config, opts) {
             detached: false,
         });
         // Capture output so failures are debuggable without re-running the service by hand.
-        // Bounded to the last ~4000 chars so a chatty/looping service can't blow up memory.
+        // Keep the HEAD, not the tail: Node prints "Error: ..." / "Cannot find module ..."
+        // first, then unwinds the call stack — a long stack trace must not push that
+        // opening line out of the window, so stop growing once capped instead of sliding.
         let output = '';
-        const MAX_OUTPUT = 4000;
+        const MAX_OUTPUT = 6000;
         const capture = (chunk) => {
-            output += chunk.toString();
-            if (output.length > MAX_OUTPUT)
-                output = output.slice(-MAX_OUTPUT);
+            if (output.length < MAX_OUTPUT)
+                output += chunk.toString();
         };
         child.stdout?.on('data', capture);
         child.stderr?.on('data', capture);
@@ -479,7 +640,12 @@ async function microservicesFlow(config, opts) {
         catch { }
         tryUnlink(join(cwd, statusFile));
         if (routes && routes.length > 0) {
-            const annotated = routes.map((r) => ({ ...r, service: svc.name }));
+            const prefix = gatewayPrefixes[svc.name];
+            const annotated = routes.map((r) => ({
+                ...r,
+                service: svc.name,
+                path: prefix ? withGatewayPrefix(prefix, r.path) : r.path,
+            }));
             allRoutes.push(...annotated);
             serviceMeta.push({ name: svc.name, baseUrl: svc.baseUrl });
             svcSpin.stop(green(`✓ ${svc.name} — ${routes.length} routes collected`));
@@ -488,7 +654,7 @@ async function microservicesFlow(config, opts) {
             svcSpin.stop(yellow(`◌ ${svc.name} — no routes collected (timeout or error)`));
             const trimmed = output.trim();
             if (trimmed) {
-                log.error(dim(`   ${bold(svc.name)} output:\n` + trimmed.split('\n').slice(-20).map(l => `   ${l}`).join('\n')));
+                log.error(dim(`   ${bold(svc.name)} output:\n` + trimmed.split('\n').slice(0, 30).map(l => `   ${l}`).join('\n')));
             }
         }
         // Remove injected code
@@ -498,6 +664,7 @@ async function microservicesFlow(config, opts) {
     // Safety: clean up any remaining injections (e.g. if process was interrupted)
     for (const f of injectedFiles)
         removeInjectedCode(f);
+    enrichRoutesFromPostman(cwd, allRoutes);
     if (allRoutes.length === 0) {
         log.error(red('No routes were collected from any service.'));
         outro(red('Analysis failed.'));
@@ -1018,13 +1185,33 @@ function buildSnippet(projectName, apiKey, baseUrl, backendUrl, appVar, isESM, a
             `    upload: true,`,
             `    runOnce: true,`,
         ].join('\n');
+    // Collection mode: some services only mount routes inside an async bootstrap
+    // gated behind a DB/broker connect (which may hang/fail outside Docker).
+    // Poll briefly for app._router to be populated (Express-shaped apps only)
+    // before giving up and collecting whatever is there — bounded well under
+    // the CLI's 30s per-service timeout so a hung connect still surfaces.
+    const runAnalyze = `APIForge.analyze(${appVar}, {\n${opts}\n  })`;
+    const call = collectionOpts
+        ? [
+            `  let __apiforgeTries = 0`,
+            `  const __apiforgeTryCollect = () => {`,
+            `    const hasRoutes = !${appVar} || !${appVar}._router`,
+            `      ? true`,
+            `      : Array.isArray(${appVar}._router.stack) && ${appVar}._router.stack.length > 0`,
+            `    if (hasRoutes || __apiforgeTries++ >= 26) {`,
+            `      ${runAnalyze}`,
+            `    } else {`,
+            `      setTimeout(__apiforgeTryCollect, 300)`,
+            `    }`,
+            `  }`,
+            `  __apiforgeTryCollect()`,
+        ].join('\n')
+        : `  ${runAnalyze}`;
     if (isESM) {
         return [
             `// APIForge — https://apiforge.brainfogagency.com`,
             `import('apiforge-analyzer').then(({ default: APIForge }) => {`,
-            `  APIForge.analyze(${appVar}, {`,
-            opts,
-            `  })`,
+            call,
             `}).catch(() => {})`,
             '',
         ].join('\n');
@@ -1033,9 +1220,7 @@ function buildSnippet(projectName, apiKey, baseUrl, backendUrl, appVar, isESM, a
         `// APIForge — https://apiforge.brainfogagency.com`,
         `Promise.resolve().then(() => require('apiforge-analyzer')).then(mod => {`,
         `  const APIForge = mod.default || mod`,
-        `  APIForge.analyze(${appVar}, {`,
-        opts,
-        `  })`,
+        call,
         `}).catch(() => {})`,
         '',
     ].join('\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apiforge-analyzer",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "Universal API documentation generator for Express, Next.js, Vite, React Router, and Node.js",
   "type": "module",
   "main": "./dist/cjs/index.js",