apiforge-analyzer 1.3.3 → 1.3.5

package/dist/cjs/cli.js

@@ -220,7 +220,19 @@ async function main() {
     ].join('\n'), 'Running');
     const s = (0, prompts_1.spinner)();
     s.start('Starting server and analyzing routes…');
-    const serverResult = await startAndWaitForAnalysis(runCommand, 90000);
+    // If the dev command runs under nodemon, our own STATUS_FILE/LOCK_FILE
+    // writes (both plain .json files inside the project root) are themselves
+    // inside nodemon's default watch glob — writing them mid-analysis makes
+    // nodemon restart the very server we're trying to analyze, racing the old
+    // and new process for the port (EADDRINUSE) and hanging the whole run.
+    const restoreNodemonIgnore = suppressNodemonSelfRestart(process.cwd());
+    let serverResult;
+    try {
+        serverResult = await startAndWaitForAnalysis(runCommand, 90000);
+    }
+    finally {
+        restoreNodemonIgnore();
+    }
     if (serverResult.status === 'error') {
         s.stop(red(`✗ ${serverResult.message}`));
         // Give a targeted hint for common failure modes
@@ -653,11 +665,9 @@ async function microservicesFlow(config, opts) {
         child.stderr?.on('data', capture);
         // Wait up to 30 s for the status file to appear
         const routes = await waitForServiceStatusFile(statusFile, 30000);
-        // Kill service process
-        try {
-            child.kill('SIGTERM');
-        }
-        catch { }
+        // Kill service process (and its full descendant tree — see killProcessTree)
+        if (child.pid)
+            killProcessTree(child.pid);
         tryUnlink((0, path_1.join)(cwd, statusFile));
         if (routes && routes.length > 0) {
             const prefix = gatewayPrefixes[svc.name];
@@ -759,6 +769,84 @@ async function microservicesFlow(config, opts) {
     }[approval.status];
     (0, prompts_1.outro)(outroMsg);
 }
+// ─── Server subprocess ────────────────────────────────────────────────────────
+/**
+ * Kill the whole process tree rooted at `pid`, not just that one process.
+ *
+ * The dev server is started via `spawn(command, { shell: true })`, so `pid`
+ * is the shell (cmd.exe /c "npm run dev") — `child.kill()` only signals that
+ * shell. On Windows, that leaves the real descendants (npm → nodemon → node)
+ * running and still holding the port, so the very next run immediately hits
+ * EADDRINUSE. `taskkill /T` kills the shell's entire descendant tree instead.
+ * On POSIX this isn't needed the same way (SIGTERM propagates to the shell's
+ * job, and the analyzer process itself exits cleanly), so a plain kill there
+ * is enough.
+ */
+function killProcessTree(pid) {
+    if (process.platform === 'win32') {
+        try {
+            (0, child_process_1.spawn)('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore' });
+        }
+        catch { }
+    }
+    else {
+        try {
+            process.kill(pid, 'SIGTERM');
+        }
+        catch { }
+    }
+}
+const NODEMON_IGNORE_PATTERNS = ['.apiforge-status.json', '.apiforge-last-run.json', '.env.local'];
+/**
+ * If the project depends on nodemon, make sure it won't watch our own
+ * .apiforge-status.json / .apiforge-last-run.json / .env.local writes —
+ * nodemon's default watch glob includes *.json, so without this it restarts
+ * the app mid-analysis (racing the old and new process for the port) every
+ * time analyze() writes its completion signal.
+ *
+ * Uses nodemon's own `.nodemonignore` file (read automatically if present,
+ * no config changes needed). Creates it if absent, or appends any missing
+ * patterns if it already exists — then returns a function that restores
+ * whatever was there before (or removes the file if we created it).
+ */
+function suppressNodemonSelfRestart(cwd) {
+    try {
+        const pkg = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(cwd, 'package.json'), 'utf-8'));
+        const usesNodemon = !!(pkg.dependencies?.nodemon || pkg.devDependencies?.nodemon);
+        if (!usesNodemon)
+            return () => { };
+    }
+    catch {
+        return () => { };
+    }
+    const ignorePath = (0, path_1.join)(cwd, '.nodemonignore');
+    const existed = (0, fs_1.existsSync)(ignorePath);
+    const original = existed ? (0, fs_1.readFileSync)(ignorePath, 'utf-8') : '';
+    const existingLines = new Set(original.split('\n').map(l => l.trim()).filter(Boolean));
+    const missing = NODEMON_IGNORE_PATTERNS.filter(p => !existingLines.has(p));
+    if (missing.length === 0)
+        return () => { };
+    try {
+        const next = existed
+            ? original.trimEnd() + '\n' + missing.join('\n') + '\n'
+            : missing.join('\n') + '\n';
+        (0, fs_1.writeFileSync)(ignorePath, next, 'utf-8');
+    }
+    catch {
+        return () => { };
+    }
+    return () => {
+        try {
+            if (existed) {
+                (0, fs_1.writeFileSync)(ignorePath, original, 'utf-8');
+            }
+            else {
+                (0, fs_1.unlinkSync)(ignorePath);
+            }
+        }
+        catch { }
+    };
+}
 function startAndWaitForAnalysis(command, timeoutMs) {
     return new Promise(resolve => {
         const statusPath = (0, path_1.join)(process.cwd(), STATUS_FILE);
@@ -785,10 +873,8 @@ function startAndWaitForAnalysis(command, timeoutMs) {
             resolved = true;
             clearInterval(poller);
             clearTimeout(timeout);
-            try {
-                child.kill('SIGTERM');
-            }
-            catch { }
+            if (child.pid)
+                killProcessTree(child.pid);
             resolve({ ...result, serverOutput: serverOutput.trim() });
         }
         // Poll for the status file every 500 ms
@@ -899,6 +985,28 @@ function removeInjectedCode(filePath) {
         return false;
     }
 }
+// ─── Entry file detection ─────────────────────────────────────────────────────
+/**
+ * If `candidate` looks like compiled build output (dist/build/out/lib) and a
+ * TypeScript source with the same base name exists under src/, prefer that
+ * instead of the build artifact.
+ *
+ * Injecting into dist/index.js is worse than pointless when the project has
+ * a watch compiler (tsc --watch, common in a "dev" script alongside
+ * nodemon watching that same dist folder): the compiler immediately
+ * overwrites the file with a fresh, uninjected build, and that overwrite
+ * itself looks like a file change to nodemon, which restarts the server —
+ * colliding with the still-running instance that had the injected snippet
+ * and racing it for the port (EADDRINUSE). The injected code also can't be
+ * cleaned up afterward because tsc already erased it before cleanup ran.
+ */
+function preferSourceOverBuildOutput(cwd, candidate) {
+    const match = candidate.match(/^(?:dist|build|out|lib)[\\/](.+)\.(?:js|mjs|cjs)$/);
+    if (!match)
+        return candidate;
+    const srcCandidate = (0, path_1.join)('src', `${match[1]}.ts`);
+    return (0, fs_1.existsSync)((0, path_1.join)(cwd, srcCandidate)) ? srcCandidate : candidate;
+}
 /** Look for a server entry inside a single directory (checks src/ then root). */
 function findEntryInDir(absDir) {
     const names = ['index', 'server', 'app', 'main'];
@@ -924,12 +1032,12 @@ function detectMainEntry(cwd) {
     try {
         const pkg = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(cwd, 'package.json'), 'utf-8'));
         if (pkg.main && (0, fs_1.existsSync)((0, path_1.join)(cwd, pkg.main)))
-            return pkg.main;
+            return preferSourceOverBuildOutput(cwd, pkg.main);
         for (const s of ['start', 'dev', 'serve']) {
             const cmd = pkg.scripts?.[s] ?? '';
-            const m = cmd.match(/(?:node|tsx|ts-node|nodemon)\s+([^\s&|;]+\.(js|ts|mjs|cjs))/);
+            const m = cmd.match(/(?:node|tsx|ts-node|nodemon)\s+(?:-\S+\s+)*([^\s&|;]+\.(js|ts|mjs|cjs))/);
             if (m && (0, fs_1.existsSync)((0, path_1.join)(cwd, m[1])))
-                return m[1];
+                return preferSourceOverBuildOutput(cwd, m[1]);
         }
     }
     catch { }
@@ -1020,12 +1128,12 @@ function detectEntryFile(archType) {
     try {
         const pkg = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(cwd, 'package.json'), 'utf-8'));
         if (pkg.main && (0, fs_1.existsSync)((0, path_1.join)(cwd, pkg.main)))
-            return pkg.main;
+            return preferSourceOverBuildOutput(cwd, pkg.main);
         for (const s of ['start', 'dev', 'serve']) {
             const cmd = pkg.scripts?.[s] ?? '';
-            const m = cmd.match(/(?:node|tsx|ts-node|nodemon)\s+([^\s&|;]+\.(js|ts|mjs|cjs))/);
+            const m = cmd.match(/(?:node|tsx|ts-node|nodemon)\s+(?:-\S+\s+)*([^\s&|;]+\.(js|ts|mjs|cjs))/);
             if (m && (0, fs_1.existsSync)((0, path_1.join)(cwd, m[1])))
-                return m[1];
+                return preferSourceOverBuildOutput(cwd, m[1]);
         }
     }
     catch { }
@@ -1216,24 +1324,37 @@ function buildSnippet(projectName, apiKey, baseUrl, backendUrl, appVar, isESM, a
         ].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.
+    //
+    // Express exposes no "I'm done registering routes" signal, so for
+    // Express-shaped apps we poll app._router.stack briefly before giving up
+    // and collecting whatever is there — bounded well under the CLI's 30s
+    // per-service timeout so a hung connect still surfaces.
+    //
+    // Fastify DOES expose a real completion signal (`app.ready()`, resolved
+    // once every plugin/route has finished registering), so Fastify apps use
+    // that instead of the Express-shaped poll — polling `._router.stack` on a
+    // Fastify instance always looks "empty" (Fastify doesn't have that
+    // property), which used to make hasRoutes evaluate true immediately and
+    // fire analyze() before async-registered routes existed yet.
     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)`,
+            `  if (${appVar} && typeof ${appVar}.ready === 'function') {`,
+            `    ${appVar}.ready().then(() => { ${runAnalyze} }).catch(() => { ${runAnalyze} })`,
+            `  } else {`,
+            `    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()`,
             `  }`,
-            `  __apiforgeTryCollect()`,
         ].join('\n')
         : `  ${runAnalyze}`;
     if (isESM) {
@@ -1268,17 +1389,23 @@ function detectESM(filePath, content) {
     return /^(?:import|export)\s+/m.test(content);
 }
 function detectAppVariable(content) {
+    // Optional TS type annotation between the variable name and `=`, e.g.
+    // `const app: FastifyInstance = fastify()` — common in Fastify+TS
+    // projects (Fastify has first-class TS typings, unlike bare Express).
+    // Without this, none of the patterns below matched a type-annotated
+    // Fastify app at all.
+    const typeAnn = `(?:\\s*:\\s*[\\w.$]+(?:<[^>]*>)?)?`;
     const patterns = [
-        /(?:const|let|var)\s+(\w+)\s*=\s*express\s*(?:\.default)?\s*\(/,
-        /(?:const|let|var)\s+(\w+)\s*=\s*(?:fastify|Fastify)\s*\(/,
-        /(?:const|let|var)\s+(\w+)\s*=\s*new\s+Koa\s*\(/,
-        /(?:const|let|var)\s+(\w+)\s*=\s*(?:Router|createApp|createServer)\s*\(/,
+        new RegExp(`(?:const|let|var)\\s+(\\w+)${typeAnn}\\s*=\\s*express\\s*(?:\\.default)?\\s*\\(`),
+        new RegExp(`(?:const|let|var)\\s+(\\w+)${typeAnn}\\s*=\\s*(?:fastify|Fastify)\\s*\\(`),
+        new RegExp(`(?:const|let|var)\\s+(\\w+)${typeAnn}\\s*=\\s*new\\s+Koa\\s*\\(`),
+        new RegExp(`(?:const|let|var)\\s+(\\w+)${typeAnn}\\s*=\\s*(?:Router|createApp|createServer)\\s*\\(`),
         // Inline `require('fastify')(...)` / `require('express')(...)` — the app
         // factory is never bound to a local name, only its return value is. This
         // is at least as common as the named-import style above (it's the pattern
         // in Fastify's own project generator output), and the patterns above never
         // match it because there's no `fastify`/`express` identifier in the source.
-        /(?:const|let|var)\s+(\w+)\s*=\s*require\s*\(\s*['"](?:fastify|express)['"]\s*\)\s*(?:\.default\s*)?\(/,
+        new RegExp(`(?:const|let|var)\\s+(\\w+)${typeAnn}\\s*=\\s*require\\s*\\(\\s*['"](?:fastify|express)['"]\\s*\\)\\s*(?:\\.default\\s*)?\\(`),
     ];
     for (const re of patterns) {
         const m = content.match(re);

package/dist/esm/cli.js

@@ -215,7 +215,19 @@ async function main() {
     ].join('\n'), 'Running');
     const s = spinner();
     s.start('Starting server and analyzing routes…');
-    const serverResult = await startAndWaitForAnalysis(runCommand, 90000);
+    // If the dev command runs under nodemon, our own STATUS_FILE/LOCK_FILE
+    // writes (both plain .json files inside the project root) are themselves
+    // inside nodemon's default watch glob — writing them mid-analysis makes
+    // nodemon restart the very server we're trying to analyze, racing the old
+    // and new process for the port (EADDRINUSE) and hanging the whole run.
+    const restoreNodemonIgnore = suppressNodemonSelfRestart(process.cwd());
+    let serverResult;
+    try {
+        serverResult = await startAndWaitForAnalysis(runCommand, 90000);
+    }
+    finally {
+        restoreNodemonIgnore();
+    }
     if (serverResult.status === 'error') {
         s.stop(red(`✗ ${serverResult.message}`));
         // Give a targeted hint for common failure modes
@@ -648,11 +660,9 @@ async function microservicesFlow(config, opts) {
         child.stderr?.on('data', capture);
         // Wait up to 30 s for the status file to appear
         const routes = await waitForServiceStatusFile(statusFile, 30000);
-        // Kill service process
-        try {
-            child.kill('SIGTERM');
-        }
-        catch { }
+        // Kill service process (and its full descendant tree — see killProcessTree)
+        if (child.pid)
+            killProcessTree(child.pid);
         tryUnlink(join(cwd, statusFile));
         if (routes && routes.length > 0) {
             const prefix = gatewayPrefixes[svc.name];
@@ -754,6 +764,84 @@ async function microservicesFlow(config, opts) {
     }[approval.status];
     outro(outroMsg);
 }
+// ─── Server subprocess ────────────────────────────────────────────────────────
+/**
+ * Kill the whole process tree rooted at `pid`, not just that one process.
+ *
+ * The dev server is started via `spawn(command, { shell: true })`, so `pid`
+ * is the shell (cmd.exe /c "npm run dev") — `child.kill()` only signals that
+ * shell. On Windows, that leaves the real descendants (npm → nodemon → node)
+ * running and still holding the port, so the very next run immediately hits
+ * EADDRINUSE. `taskkill /T` kills the shell's entire descendant tree instead.
+ * On POSIX this isn't needed the same way (SIGTERM propagates to the shell's
+ * job, and the analyzer process itself exits cleanly), so a plain kill there
+ * is enough.
+ */
+function killProcessTree(pid) {
+    if (process.platform === 'win32') {
+        try {
+            spawn('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore' });
+        }
+        catch { }
+    }
+    else {
+        try {
+            process.kill(pid, 'SIGTERM');
+        }
+        catch { }
+    }
+}
+const NODEMON_IGNORE_PATTERNS = ['.apiforge-status.json', '.apiforge-last-run.json', '.env.local'];
+/**
+ * If the project depends on nodemon, make sure it won't watch our own
+ * .apiforge-status.json / .apiforge-last-run.json / .env.local writes —
+ * nodemon's default watch glob includes *.json, so without this it restarts
+ * the app mid-analysis (racing the old and new process for the port) every
+ * time analyze() writes its completion signal.
+ *
+ * Uses nodemon's own `.nodemonignore` file (read automatically if present,
+ * no config changes needed). Creates it if absent, or appends any missing
+ * patterns if it already exists — then returns a function that restores
+ * whatever was there before (or removes the file if we created it).
+ */
+function suppressNodemonSelfRestart(cwd) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf-8'));
+        const usesNodemon = !!(pkg.dependencies?.nodemon || pkg.devDependencies?.nodemon);
+        if (!usesNodemon)
+            return () => { };
+    }
+    catch {
+        return () => { };
+    }
+    const ignorePath = join(cwd, '.nodemonignore');
+    const existed = existsSync(ignorePath);
+    const original = existed ? readFileSync(ignorePath, 'utf-8') : '';
+    const existingLines = new Set(original.split('\n').map(l => l.trim()).filter(Boolean));
+    const missing = NODEMON_IGNORE_PATTERNS.filter(p => !existingLines.has(p));
+    if (missing.length === 0)
+        return () => { };
+    try {
+        const next = existed
+            ? original.trimEnd() + '\n' + missing.join('\n') + '\n'
+            : missing.join('\n') + '\n';
+        writeFileSync(ignorePath, next, 'utf-8');
+    }
+    catch {
+        return () => { };
+    }
+    return () => {
+        try {
+            if (existed) {
+                writeFileSync(ignorePath, original, 'utf-8');
+            }
+            else {
+                unlinkSync(ignorePath);
+            }
+        }
+        catch { }
+    };
+}
 function startAndWaitForAnalysis(command, timeoutMs) {
     return new Promise(resolve => {
         const statusPath = join(process.cwd(), STATUS_FILE);
@@ -780,10 +868,8 @@ function startAndWaitForAnalysis(command, timeoutMs) {
             resolved = true;
             clearInterval(poller);
             clearTimeout(timeout);
-            try {
-                child.kill('SIGTERM');
-            }
-            catch { }
+            if (child.pid)
+                killProcessTree(child.pid);
             resolve({ ...result, serverOutput: serverOutput.trim() });
         }
         // Poll for the status file every 500 ms
@@ -894,6 +980,28 @@ function removeInjectedCode(filePath) {
         return false;
     }
 }
+// ─── Entry file detection ─────────────────────────────────────────────────────
+/**
+ * If `candidate` looks like compiled build output (dist/build/out/lib) and a
+ * TypeScript source with the same base name exists under src/, prefer that
+ * instead of the build artifact.
+ *
+ * Injecting into dist/index.js is worse than pointless when the project has
+ * a watch compiler (tsc --watch, common in a "dev" script alongside
+ * nodemon watching that same dist folder): the compiler immediately
+ * overwrites the file with a fresh, uninjected build, and that overwrite
+ * itself looks like a file change to nodemon, which restarts the server —
+ * colliding with the still-running instance that had the injected snippet
+ * and racing it for the port (EADDRINUSE). The injected code also can't be
+ * cleaned up afterward because tsc already erased it before cleanup ran.
+ */
+function preferSourceOverBuildOutput(cwd, candidate) {
+    const match = candidate.match(/^(?:dist|build|out|lib)[\\/](.+)\.(?:js|mjs|cjs)$/);
+    if (!match)
+        return candidate;
+    const srcCandidate = join('src', `${match[1]}.ts`);
+    return existsSync(join(cwd, srcCandidate)) ? srcCandidate : candidate;
+}
 /** Look for a server entry inside a single directory (checks src/ then root). */
 function findEntryInDir(absDir) {
     const names = ['index', 'server', 'app', 'main'];
@@ -919,12 +1027,12 @@ function detectMainEntry(cwd) {
     try {
         const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf-8'));
         if (pkg.main && existsSync(join(cwd, pkg.main)))
-            return pkg.main;
+            return preferSourceOverBuildOutput(cwd, pkg.main);
         for (const s of ['start', 'dev', 'serve']) {
             const cmd = pkg.scripts?.[s] ?? '';
-            const m = cmd.match(/(?:node|tsx|ts-node|nodemon)\s+([^\s&|;]+\.(js|ts|mjs|cjs))/);
+            const m = cmd.match(/(?:node|tsx|ts-node|nodemon)\s+(?:-\S+\s+)*([^\s&|;]+\.(js|ts|mjs|cjs))/);
             if (m && existsSync(join(cwd, m[1])))
-                return m[1];
+                return preferSourceOverBuildOutput(cwd, m[1]);
         }
     }
     catch { }
@@ -1015,12 +1123,12 @@ function detectEntryFile(archType) {
     try {
         const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf-8'));
         if (pkg.main && existsSync(join(cwd, pkg.main)))
-            return pkg.main;
+            return preferSourceOverBuildOutput(cwd, pkg.main);
         for (const s of ['start', 'dev', 'serve']) {
             const cmd = pkg.scripts?.[s] ?? '';
-            const m = cmd.match(/(?:node|tsx|ts-node|nodemon)\s+([^\s&|;]+\.(js|ts|mjs|cjs))/);
+            const m = cmd.match(/(?:node|tsx|ts-node|nodemon)\s+(?:-\S+\s+)*([^\s&|;]+\.(js|ts|mjs|cjs))/);
             if (m && existsSync(join(cwd, m[1])))
-                return m[1];
+                return preferSourceOverBuildOutput(cwd, m[1]);
         }
     }
     catch { }
@@ -1211,24 +1319,37 @@ function buildSnippet(projectName, apiKey, baseUrl, backendUrl, appVar, isESM, a
         ].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.
+    //
+    // Express exposes no "I'm done registering routes" signal, so for
+    // Express-shaped apps we poll app._router.stack briefly before giving up
+    // and collecting whatever is there — bounded well under the CLI's 30s
+    // per-service timeout so a hung connect still surfaces.
+    //
+    // Fastify DOES expose a real completion signal (`app.ready()`, resolved
+    // once every plugin/route has finished registering), so Fastify apps use
+    // that instead of the Express-shaped poll — polling `._router.stack` on a
+    // Fastify instance always looks "empty" (Fastify doesn't have that
+    // property), which used to make hasRoutes evaluate true immediately and
+    // fire analyze() before async-registered routes existed yet.
     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)`,
+            `  if (${appVar} && typeof ${appVar}.ready === 'function') {`,
+            `    ${appVar}.ready().then(() => { ${runAnalyze} }).catch(() => { ${runAnalyze} })`,
+            `  } else {`,
+            `    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()`,
             `  }`,
-            `  __apiforgeTryCollect()`,
         ].join('\n')
         : `  ${runAnalyze}`;
     if (isESM) {
@@ -1263,17 +1384,23 @@ function detectESM(filePath, content) {
     return /^(?:import|export)\s+/m.test(content);
 }
 function detectAppVariable(content) {
+    // Optional TS type annotation between the variable name and `=`, e.g.
+    // `const app: FastifyInstance = fastify()` — common in Fastify+TS
+    // projects (Fastify has first-class TS typings, unlike bare Express).
+    // Without this, none of the patterns below matched a type-annotated
+    // Fastify app at all.
+    const typeAnn = `(?:\\s*:\\s*[\\w.$]+(?:<[^>]*>)?)?`;
     const patterns = [
-        /(?:const|let|var)\s+(\w+)\s*=\s*express\s*(?:\.default)?\s*\(/,
-        /(?:const|let|var)\s+(\w+)\s*=\s*(?:fastify|Fastify)\s*\(/,
-        /(?:const|let|var)\s+(\w+)\s*=\s*new\s+Koa\s*\(/,
-        /(?:const|let|var)\s+(\w+)\s*=\s*(?:Router|createApp|createServer)\s*\(/,
+        new RegExp(`(?:const|let|var)\\s+(\\w+)${typeAnn}\\s*=\\s*express\\s*(?:\\.default)?\\s*\\(`),
+        new RegExp(`(?:const|let|var)\\s+(\\w+)${typeAnn}\\s*=\\s*(?:fastify|Fastify)\\s*\\(`),
+        new RegExp(`(?:const|let|var)\\s+(\\w+)${typeAnn}\\s*=\\s*new\\s+Koa\\s*\\(`),
+        new RegExp(`(?:const|let|var)\\s+(\\w+)${typeAnn}\\s*=\\s*(?:Router|createApp|createServer)\\s*\\(`),
         // Inline `require('fastify')(...)` / `require('express')(...)` — the app
         // factory is never bound to a local name, only its return value is. This
         // is at least as common as the named-import style above (it's the pattern
         // in Fastify's own project generator output), and the patterns above never
         // match it because there's no `fastify`/`express` identifier in the source.
-        /(?:const|let|var)\s+(\w+)\s*=\s*require\s*\(\s*['"](?:fastify|express)['"]\s*\)\s*(?:\.default\s*)?\(/,
+        new RegExp(`(?:const|let|var)\\s+(\\w+)${typeAnn}\\s*=\\s*require\\s*\\(\\s*['"](?:fastify|express)['"]\\s*\\)\\s*(?:\\.default\\s*)?\\(`),
     ];
     for (const re of patterns) {
         const m = content.match(re);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "apiforge-analyzer",
-  "version": "1.3.3",
-  "description": "Universal API documentation generator for Express, Fastify, Next.js, Vite, React Router, and Node.js",
+  "version": "1.3.5",
+  "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",
@@ -54,14 +54,14 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.9.1",
-    "axios": "^1.6.0"
+    "axios": "^1.6.0",
+    "ts-morph": "^28.0.0"
   },
   "devDependencies": {
     "@types/express": "^4.17.21",
     "@types/node": "^20.0.0",
     "fastify": "^5.12.1",
-    "ts-morph": "^28.0.0",
     "typescript": "^5.3.0",
     "zod": "^4.5.4"
   }
-}
+}