apiforge-analyzer 1.3.2 → 1.3.3

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

@@ -224,11 +224,18 @@ async function main() {
     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 +245,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);
@@ -749,11 +764,20 @@ function startAndWaitForAnalysis(command, timeoutMs) {
         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)
@@ -765,7 +789,7 @@ function startAndWaitForAnalysis(command, timeoutMs) {
                 child.kill('SIGTERM');
             }
             catch { }
-            resolve(result);
+            resolve({ ...result, serverOutput: serverOutput.trim() });
         }
         // Poll for the status file every 500 ms
         const poller = setInterval(() => {
@@ -1249,6 +1273,12 @@ function detectAppVariable(content) {
         /(?: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*\(/,
+        // 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*)?\(/,
     ];
     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);
 }