apiforge-analyzer 1.3.2 → 1.3.5

package/README.md

@@ -1,6 +1,6 @@
 # apiforge-analyzer
 
-CLI and library for auto-generating API documentation from live Express, NestJS, Next.js, Vite, and React Router apps.
+CLI and library for auto-generating API documentation from live Express, Fastify, NestJS, Next.js, Vite, and React Router apps.
 
 Routes are extracted at runtime by walking the framework's internal route stack — no static analysis, no decorators, no changes to your production code.
 
@@ -90,6 +90,108 @@ await analyze(app.getHttpServer(), {
 await app.listen(3000)
 ```
 
+### Fastify
+
+Routes are captured via Fastify's `onRoute` hook, so composed paths (`register(fn, { prefix })`,
+relative registrations, nested scopes) resolve to their real runtime URL rather than the literal
+string passed to `app.get(...)`. Handlers are resolved with a TypeScript checker (not a regex),
+so a handler that lives in another module — including one reached through an aliased import,
+a curried factory, or a thin delegating wrapper — is still followed to its real implementation.
+
+```js
+const fastify = require('fastify')
+const { analyze } = require('apiforge-analyzer')
+
+const app = fastify()
+
+app.register(async (v1) => {
+  v1.get('/users', listUsers)
+  v1.post('/users', createUser)
+}, { prefix: '/v1' })
+
+// Call after all routes are registered, before or after app.listen — analyze()
+// awaits app.ready() itself.
+await analyze(app, {
+  projectName: 'My API',
+  apiKey: process.env.APIFORGE_API_KEY,
+  upload: true,
+})
+
+await app.listen({ port: 3000 })
+```
+
+What's inferred automatically, with no annotation: the composed path, the handler's resolved
+source location and leading JSDoc comment (lifted verbatim into `description`), header reads,
+literal and simple-ternary response statuses, and auth — a route counts as authenticated if a
+route-level `onRequest`/`preHandler` hook looks like an auth check by name or body, or if the
+resolved handler calls a guard function (`requireScope`, `requireOperator`, or a local alias of
+either — `const operator = requireOperator` is followed, not missed).
+
+Query and body fields backed by a zod schema — matching both `schema.parse(request.query)` and
+a wrapper call like `parse(schema, request.query)` — come out typed, not as bare field names:
+`z.string().min/max/length()`, `.number()`, `.boolean()`, `.enum([...])` and `.default()` are
+read off the schema and land in the standard `Route.parameters` / `Route.requestBody` fields as
+real JSON Schema (`minLength`/`maxLength`, `enum`, `default`, etc.), the same fields
+`uploadRoutes()` and `exportToJSON()` read — not a side channel that gets dropped on the way out.
+A `.refine()` on the object doesn't drop the fields declared before it.
+
+What can't be inferred safely is reported as `"unknown"` rather than guessed — an unresolved
+handler, or a route-level hook whose name doesn't match a known auth pattern, produces
+`authRequired: "unknown"` instead of a confident `false`.
+
+#### Supplying what can't be inferred
+
+Four extra `AnalyzerOptions` fields cover metadata no static analysis can recover:
+
+```js
+await analyze(app, {
+  projectName: 'My API',
+  apiKey: process.env.APIFORGE_API_KEY,
+
+  // scope name -> extra metadata, joined onto each route's resolved auth scope
+  scopeCatalogPath: './scope-catalog.json',
+
+  // error code -> { status, retry, message, hint? }, joined onto a route by
+  // response status, or by the `errors` list in an annotation (see below)
+  errorCatalogPath: './error-catalog.json',
+
+  // per-prefix response envelope shape — required for every versioned prefix
+  // your API serves once you use this option at all; an unlisted prefix is
+  // reported as a warning rather than silently assumed bare
+  envelopes: {
+    '/v1': { bare: true },
+    '/v2': { wrapper: 'ApiEnvelope', dataField: 'data' },
+  },
+  // With `envelopes` set, `GET /v1/things` and `GET /v2/things` get *different*
+  // `responses['200']` schemas from this one declaration — `/v2`'s nests the same
+  // bare shape under `data` instead of replacing it, so it stays a strict superset.
+
+  // "METHOD /path" -> { summary?, description?, tags?, deprecated?, errors? }
+  // overrides for whatever the analyzer got wrong or couldn't see at all
+  annotationsPath: './annotations.json',
+})
+```
+
+The same per-route overrides can also be attached inline at the route, via Fastify's own
+`config` option — no sidecar file needed for a one-off:
+
+```js
+app.get('/users', {
+  config: {
+    apiforge: { summary: 'List users', tags: ['users'] },
+  },
+}, listUsers)
+```
+
+An `annotationsPath` entry that doesn't match any route Fastify actually registered (a stale
+key left behind after a route was renamed or removed) logs a warning rather than failing
+silently.
+
+We deliberately do **not** read Fastify's request-side `schema` option for documentation —
+adding a schema there gives the route a second, independent validator with its own error
+contract, and `fast-json-stringify` silently drops response fields a *response* schema doesn't
+declare. Use zod (auto-detected) or the annotation options above instead.
+
 ### Microservices — per-service
 
 When running each service independently, pass `service` to tag routes with the service name:
@@ -180,9 +282,23 @@ interface AnalyzerOptions {
 
   skipInProduction?: boolean   // skip when NODE_ENV=production (default: true)
   runOnce?: boolean            // debounce — skip if analyzed within the last 30 s (default: true)
+
+  // Fastify only — see "Supplying what can't be inferred" above
+  scopeCatalogPath?: string
+  errorCatalogPath?: string
+  envelopes?: Record<string, { wrapper: string; dataField: string; excluded?: string[] } | { bare: true }>
+  annotationsPath?: string
 }
 ```
 
+`analyze()` throws instead of resolving to `[]` when the detected or forced framework has no
+analyzer (currently: anything other than `express`, `fastify`, `nestjs`, `nextjs-pages`,
+`nextjs-app`, `vite`, `react-router`). Every other early-exit (no API key, debounced, zero
+routes found, `NODE_ENV=production`) still resolves to `[]` — only "this framework cannot be
+analyzed" is a thrown error, so a caller can tell the two apart. `detectFramework()` also
+exposes this directly: `detectFramework(app).supported` is `false` for a framework it can
+name but not analyze (currently `koa`, `hapi`, `unknown`).
+
 ## Architecture detection
 
 The CLI scores structural signals to pick the right architecture automatically:
@@ -216,11 +332,57 @@ Each collected route:
   requestBodyFields: [],
   responseStatuses: [200, 404],
   framework: 'express',
-  moduleName?: 'users',        // modular-monolithic only
-  serviceName?: 'auth-service' // microservices only
+  module?: 'users',        // modular-monolithic only
+  service?: 'auth-service' // microservices only
 }
 ```
 
+## Escape hatch — building routes yourself
+
+If your framework has no `analyze*()` function, call `uploadRoutes()` directly with a
+hand-built `Route[]`. This is the same function every `analyze*()` call ends up using
+internally — it's a supported, typed, top-level export, not a private helper.
+
+```ts
+import { uploadRoutes, type Route } from 'apiforge-analyzer'
+
+const routes: Route[] = [
+  {
+    method: 'GET',
+    path: '/api/users/:id',
+    tag: 'users',
+    operationId: 'get_api_users_id',
+    summary: 'Get a user by id',
+    middleware: [],
+    authRequired: true,
+    pathParams: ['id'],
+    queryParams: [],
+    requestBodyFields: [],
+    linkedPaths: [],
+    hasAuth: true,
+    framework: 'my-framework',
+    // routeKey?: stable dedup key the dashboard uses across uploads — see below
+  },
+]
+
+await uploadRoutes(routes, {
+  projectName: 'My API',
+  apiKey: process.env.APIFORGE_API_KEY!,
+})
+```
+
+The fields above (`method`, `path`, `tag`, `operationId`, `summary`, `middleware`,
+`authRequired`, `pathParams`, `queryParams`, `requestBodyFields`, `linkedPaths`, `hasAuth`,
+`framework`) are the only ones `Route` requires; everything else (`description`, `tags`,
+`headerParams`, `responseStatuses`, `parameters`, `requestBody`, `responses`, `module`,
+`service`, ...) is optional and gets a reasonable default from `enrichRoutes()`.
+
+**Set `routeKey` yourself.** If you don't, it defaults to `api-001`, `api-002`, ... based on
+array position — which shifts if a route is added, removed, or reordered between uploads, so
+the dashboard can no longer tell "this is the same endpoint as last time" from "this is a new
+one". Use something stable per endpoint, e.g. `` `${method} ${path}` ``, as every built-in
+analyzer does.
+
 ## ESM and CommonJS
 
 ```js

package/dist/cjs/cli.js

@@ -220,15 +220,34 @@ 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
-        if (serverResult.message.includes('API key')) {
-            prompts_1.log.warn(yellow('Hint: The CLI wrote your key to .env.local — but your server may not load it.'));
-            prompts_1.log.warn(yellow('      Add this at the top of your entry file before calling analyze():'));
-            prompts_1.log.info(`      ${cyan("require('dotenv').config({ path: '.env.local' })")}`);
-            prompts_1.log.warn(yellow('      Or install dotenv:  npm install dotenv'));
+        if (serverResult.message.includes('API key') || serverResult.message.includes('Invalid API key')) {
+            prompts_1.log.warn(yellow('Hint: Your API key was rejected by the server. Common causes:'));
+            prompts_1.log.warn(yellow(''));
+            prompts_1.log.warn(yellow('  1. Key not yet created — go to your dashboard and generate one:'));
+            prompts_1.log.info(`     ${cyan('https://apiforge.brainfogagency.com/dashboard')}`);
+            prompts_1.log.warn(yellow(''));
+            prompts_1.log.warn(yellow('  2. Key belongs to a different account — make sure you\'re logged in'));
+            prompts_1.log.warn(yellow('     to the same account that owns this project.'));
+            prompts_1.log.warn(yellow(''));
+            prompts_1.log.warn(yellow('  3. Server not loading .env.local — add this at the top of your entry file:'));
+            prompts_1.log.info(`     ${cyan("require('dotenv').config({ path: '.env.local' })")}`);
+            prompts_1.log.warn(yellow('     Or install dotenv:  npm install dotenv'));
         }
         else if (serverResult.message.includes('No routes')) {
             prompts_1.log.warn(yellow('Hint: Make sure all routes are registered before analyze() is called.'));
@@ -238,6 +257,14 @@ async function main() {
             prompts_1.log.warn(yellow('Hint: Your server might be taking too long to start, or the analyzer'));
             prompts_1.log.warn(yellow('      is not being called. Check your server logs for APIForge messages.'));
         }
+        // Show captured server output to help debug the root cause
+        const capturedOutput = serverResult.serverOutput;
+        if (capturedOutput) {
+            prompts_1.log.info('');
+            prompts_1.log.info(dim('─── Server output ───────────────────────────────'));
+            capturedOutput.split('\n').slice(0, 25).forEach((line) => prompts_1.log.info(dim(`  ${line}`)));
+            prompts_1.log.info(dim('─────────────────────────────────────────────────'));
+        }
         await offerCleanup(entryFile, injected);
         (0, prompts_1.outro)(red('Analysis failed.'));
         process.exit(1);
@@ -638,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];
@@ -744,16 +769,103 @@ 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);
         const child = (0, child_process_1.spawn)(command, {
             cwd: process.cwd(),
-            stdio: 'ignore',
+            stdio: ['ignore', 'pipe', 'pipe'],
             shell: true,
             env: { ...process.env },
             detached: false,
         });
+        // Capture server output (head-capped) so we can show it on failure
+        let serverOutput = '';
+        const MAX_OUTPUT = 4000;
+        const captureOutput = (chunk) => {
+            if (serverOutput.length < MAX_OUTPUT)
+                serverOutput += chunk.toString();
+        };
+        child.stdout?.on('data', captureOutput);
+        child.stderr?.on('data', captureOutput);
         let resolved = false;
         function finish(result) {
             if (resolved)
@@ -761,11 +873,9 @@ function startAndWaitForAnalysis(command, timeoutMs) {
             resolved = true;
             clearInterval(poller);
             clearTimeout(timeout);
-            try {
-                child.kill('SIGTERM');
-            }
-            catch { }
-            resolve(result);
+            if (child.pid)
+                killProcessTree(child.pid);
+            resolve({ ...result, serverOutput: serverOutput.trim() });
         }
         // Poll for the status file every 500 ms
         const poller = setInterval(() => {
@@ -875,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'];
@@ -900,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 { }
@@ -996,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 { }
@@ -1192,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) {
@@ -1244,11 +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.
+        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/cjs/detect.js

@@ -1,8 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_FRAMEWORKS = void 0;
 exports.detectFramework = detectFramework;
 const fs_1 = require("fs");
 const path_1 = require("path");
+/**
+ * Frameworks analyze() can actually dispatch to. Detection can identify more
+ * frameworks than this (koa, hapi) — those are named so the detector is honest
+ * about what it saw, but `supported: false` tells callers not to expect output.
+ */
+exports.SUPPORTED_FRAMEWORKS = new Set([
+    'express',
+    'fastify',
+    'nestjs',
+    'nextjs-pages',
+    'nextjs-app',
+    'vite',
+    'react-router',
+]);
 const cwd = () => process.cwd();
 function fileExists(rel) {
     return (0, fs_1.existsSync)((0, path_1.join)(cwd(), rel));
@@ -21,16 +36,19 @@ function tryResolve(mod) {
  * Detect the web framework from the live app instance + filesystem hints.
  * Confidence is used to pick the best match when multiple signals fire.
  */
+function mk(name, confidence) {
+    return { name, confidence, supported: exports.SUPPORTED_FRAMEWORKS.has(name) };
+}
 function detectFramework(app) {
     // ── 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 };
+            return mk('express', 1.0);
         }
         // Koa: middleware array
         if (Array.isArray(app.middleware) && typeof app.use === 'function' && app.context) {
-            return { name: 'koa', confidence: 0.95 };
+            return mk('koa', 0.95);
         }
     }
     // Fastify: inject method and route method
@@ -38,7 +56,7 @@ function detectFramework(app) {
         typeof app === 'object' &&
         typeof app.inject === 'function' &&
         typeof app.route === 'function') {
-        return { name: 'fastify', confidence: 1.0 };
+        return mk('fastify', 1.0);
     }
     // Hapi: server with route + start methods
     if (app &&
@@ -46,43 +64,43 @@ function detectFramework(app) {
         typeof app.route === 'function' &&
         typeof app.start === 'function' &&
         typeof app.stop === 'function') {
-        return { name: 'hapi', confidence: 0.95 };
+        return mk('hapi', 0.95);
     }
     // NestJS application
     if (app &&
         typeof app === 'object' &&
         typeof app.getHttpServer === 'function' &&
         typeof app.listen === 'function') {
-        return { name: 'nestjs', confidence: 0.95 };
+        return mk('nestjs', 0.95);
     }
     // ── Filesystem detection ──────────────────────────────────────────────────
     // Next.js App Router
     if (fileExists('app') && (fileExists('app/layout.tsx') || fileExists('app/layout.js'))) {
-        return { name: 'nextjs-app', confidence: 0.92 };
+        return mk('nextjs-app', 0.92);
     }
     // Next.js Pages Router
     if (fileExists('pages/api') || fileExists('src/pages/api')) {
-        return { name: 'nextjs-pages', confidence: 0.90 };
+        return mk('nextjs-pages', 0.90);
     }
     if (fileExists('next.config.js') ||
         fileExists('next.config.mjs') ||
         fileExists('next.config.ts')) {
-        return { name: 'nextjs-pages', confidence: 0.75 };
+        return mk('nextjs-pages', 0.75);
     }
     // ── Dependency-based detection (lowest confidence) ────────────────────────
     if (tryResolve('express'))
-        return { name: 'express', confidence: 0.70 };
+        return mk('express', 0.70);
     if (tryResolve('fastify'))
-        return { name: 'fastify', confidence: 0.70 };
+        return mk('fastify', 0.70);
     if (tryResolve('koa'))
-        return { name: 'koa', confidence: 0.70 };
+        return mk('koa', 0.70);
     if (tryResolve('@hapi/hapi') || tryResolve('hapi'))
-        return { name: 'hapi', confidence: 0.70 };
+        return mk('hapi', 0.70);
     if (tryResolve('@nestjs/core'))
-        return { name: 'nestjs', confidence: 0.70 };
+        return mk('nestjs', 0.70);
     if (tryResolve('vite'))
-        return { name: 'vite', confidence: 0.60 };
+        return mk('vite', 0.60);
     if (tryResolve('react-router-dom'))
-        return { name: 'react-router', confidence: 0.55 };
-    return { name: 'unknown', confidence: 0 };
+        return mk('react-router', 0.55);
+    return mk('unknown', 0);
 }