apiforge-analyzer 1.3.8 → 1.3.10

package/dist/cjs/cli.js

@@ -111,6 +111,22 @@ async function main() {
         (0, prompts_1.cancel)('Cancelled.');
         process.exit(0);
     }
+    // ── Who can see the docs (APIForge spec §6.1 levels, chosen by the creator per §6.3) ──────────────────
+    const visibilityChoice = await (0, prompts_1.select)({
+        message: 'Who can see these docs?',
+        initialValue: 'PRIVATE', // "Only me" — the backend's default too
+        options: [
+            { value: 'ORG_WIDE', label: `${bold('Everyone in the org')}  ${dim('— every member of your organization')}` },
+            { value: 'TEAM', label: `${bold('Team')}  ${dim('— people you add, plus admins and the Superadmin')}` },
+            { value: 'PRIVATE', label: `${bold('Only me')}  ${dim('— you, people you add, and the Superadmin')}` },
+        ],
+    });
+    if ((0, prompts_1.isCancel)(visibilityChoice)) {
+        (0, prompts_1.cancel)('Cancelled.');
+        process.exit(0);
+    }
+    // Read by uploadRoutes — in this process and in the server this CLI starts (it inherits the environment)
+    process.env.APIFORGE_VISIBILITY = visibilityChoice;
     const isLocal = backendChoice === 'local';
     const backendUrl = isLocal ? BACKEND_LOCAL : BACKEND_PROD;
     const dashboardUrl = isLocal ? DASHBOARD_LOCAL : DASHBOARD_PROD;
@@ -671,7 +687,7 @@ async function microservicesFlow(config, opts) {
             cwd,
             stdio: ['ignore', 'pipe', 'pipe'],
             shell: true,
-            env: { ...process.env },
+            env: withExpressMountHook({ ...process.env }),
             detached: false,
         });
         // Capture output so failures are debuggable without re-running the service by hand.
@@ -1652,6 +1668,26 @@ function suppressNodemonSelfRestart(cwd) {
         catch { }
     };
 }
+/**
+ * Preloads the Express mount hook (express-preload.ts) into the user's server, so router / sub-app mount
+ * paths are recorded as they're registered — see express-mount-hook.ts. Without the built preload file
+ * (e.g. running from source) the env is returned unchanged and prefixes are read off the stack as before.
+ */
+function withExpressMountHook(env) {
+    let preload;
+    try {
+        // The bin is dist/esm/cli.js (or dist/cjs/cli.js); the preload must be the CommonJS build.
+        preload = (0, path_1.join)((0, path_1.dirname)((0, fs_1.realpathSync)(process.argv[1])), '..', 'cjs', 'express-preload.js');
+    }
+    catch {
+        return env;
+    }
+    if (!(0, fs_1.existsSync)(preload))
+        return env;
+    // Forward slashes: NODE_OPTIONS treats a backslash inside quotes as an escape.
+    const flag = `--require "${preload.replace(/\\/g, '/')}"`;
+    return { ...env, NODE_OPTIONS: env.NODE_OPTIONS ? `${env.NODE_OPTIONS} ${flag}` : flag };
+}
 function startAndWaitForAnalysis(command, timeoutMs) {
     return new Promise(resolve => {
         const statusPath = (0, path_1.join)(process.cwd(), STATUS_FILE);
@@ -1659,7 +1695,7 @@ function startAndWaitForAnalysis(command, timeoutMs) {
             cwd: process.cwd(),
             stdio: ['ignore', 'pipe', 'pipe'],
             shell: true,
-            env: { ...process.env },
+            env: withExpressMountHook({ ...process.env }),
             detached: false,
         });
         // Capture server output (head-capped) so we can show it on failure

package/dist/cjs/detect.js

@@ -47,10 +47,19 @@ function mk(name, confidence) {
 function detectFramework(app) {
     // ── Instance-based detection (highest confidence) ─────────────────────────
     if (app && typeof app === 'function') {
-        // Express: _router or lazyrouter
+        // Express 4: _router or lazyrouter
         if (app._router || (app.lazyrouter && typeof app.lazyrouter === 'function')) {
             return mk('express', 1.0);
         }
+        // Express 5 dropped both; the router is behind an `app.router` getter (which throws in Express 4).
+        // Without this, an Express 5 app in a project that also has an app/ folder was mistaken for Next.js.
+        try {
+            if (app.router && Array.isArray(app.router.stack))
+                return mk('express', 1.0);
+        }
+        catch {
+            // not Express 5
+        }
         // Koa: middleware array
         if (Array.isArray(app.middleware) && typeof app.use === 'function' && app.context) {
             return mk('koa', 0.95);

package/dist/cjs/express-mount-hook.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * Records where every router / sub-app is mounted, at the moment it is mounted.
+ *
+ * The Express analyzer reads mount prefixes back off the router stack after the fact, which loses them:
+ *  - Express 5 (router@2) keeps no path on a layer at all (only compiled matchers), so every mounted
+ *    router's routes came out without their prefix, and same-looking ones collapsed as duplicates.
+ *  - A sub-app (`app.use('/admin', express())`) is wrapped in a `mounted_app` function with no `stack`,
+ *    so none of its routes were found.
+ *  - Express 4's mount regexp for a parameterised prefix (`/users/:id/posts`) doesn't turn back into the path.
+ *
+ * Wrapping `use()` tags each layer it adds with the mount path as written, and a sub-app's layer with the
+ * sub-app itself; express.ts prefers those tags and falls back to the old regexp reading without them.
+ * Must run before the app registers its routes — the CLI preloads it (express-preload.ts).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUB_APP = exports.MOUNT_PATH = void 0;
+exports.appStack = appStack;
+exports.installExpressMountHook = installExpressMountHook;
+exports.MOUNT_PATH = '__apiforgeMountPath';
+exports.SUB_APP = '__apiforgeSubApp';
+const INSTALLED = Symbol.for('apiforge.expressMountHook');
+/** An app's router stack: `_router` in Express 4, the `router` getter in Express 5 (which throws in 4). */
+function appStack(app) {
+    const legacy = app?._router?.stack;
+    if (Array.isArray(legacy))
+        return legacy;
+    try {
+        const stack = app?.router?.stack;
+        return Array.isArray(stack) ? stack : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The mount path `use()` was given, or undefined when the first argument is already a handler (Express's own rule). */
+function mountPathArg(args) {
+    let arg = args[0];
+    while (Array.isArray(arg) && arg.length !== 0)
+        arg = arg[0];
+    return typeof arg === 'function' ? undefined : args[0];
+}
+function isApp(fn) {
+    return !!fn && typeof fn.handle === 'function' && typeof fn.set === 'function';
+}
+function wrapUse(target, stackOf) {
+    const original = target.use;
+    if (typeof original !== 'function')
+        return;
+    target.use = function apiforgeUse(...args) {
+        const before = stackOf(this)?.length ?? 0;
+        const result = original.apply(this, args);
+        try {
+            const added = (stackOf(this) ?? []).slice(before);
+            const path = mountPathArg(args) ?? '/';
+            const handlers = (mountPathArg(args) === undefined ? args : args.slice(1)).flat(Infinity);
+            const subApps = handlers.filter(isApp);
+            let next = 0;
+            for (const layer of added) {
+                layer[exports.MOUNT_PATH] = path;
+                if (layer.handle?.name === 'mounted_app' && next < subApps.length)
+                    layer[exports.SUB_APP] = subApps[next++];
+            }
+        }
+        catch {
+            // Never let documentation tagging break the user's app.
+        }
+        return result;
+    };
+}
+function installExpressMountHook(express) {
+    if (!express || express[INSTALLED])
+        return;
+    express[INSTALLED] = true;
+    // Express 5: Router is a class (router@2). Express 4: Router is the proto object itself.
+    const Router = express.Router;
+    const routerProto = typeof Router?.prototype?.use === 'function' ? Router.prototype : Router;
+    if (routerProto)
+        wrapUse(routerProto, (self) => (Array.isArray(self?.stack) ? self.stack : undefined));
+    if (express.application)
+        wrapUse(express.application, appStack);
+}

package/dist/cjs/express-preload.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Preloaded into the user's server by the CLI (`NODE_OPTIONS=--require …/dist/cjs/express-preload.js`) so
+ * the mount hook is in place before any route is registered. Loads the project's own express (resolved
+ * from the working directory); a project without express is left untouched.
+ */
+const module_1 = require("module");
+const path_1 = require("path");
+const express_mount_hook_js_1 = require("./express-mount-hook.js");
+try {
+    const projectRequire = (0, module_1.createRequire)((0, path_1.join)(process.cwd(), 'noop.js'));
+    (0, express_mount_hook_js_1.installExpressMountHook)(projectRequire('express'));
+}
+catch {
+    // No express here (npm, nodemon, a non-Express project): nothing to record.
+}

package/dist/cjs/frameworks/express.js

@@ -4,6 +4,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.analyzeExpress = analyzeExpress;
+const express_mount_hook_js_1 = require("../express-mount-hook.js");
 // ─── Path helpers ─────────────────────────────────────────────────────────────
 function normalizePath(raw) {
     return raw
@@ -52,29 +53,48 @@ function analyzeExpress(app) {
         console.warn('⚠️  No routes found — ensure routes are registered before analyze()');
         return routes;
     }
-    walkStack(stack, '', routes, seen);
+    const skipped = [];
+    walkStack(stack, '', routes, seen, skipped);
+    if (skipped.length) {
+        // Same method + path registered more than once: Express only ever serves the first, so it is
+        // documented once — but say so, so the count can be checked against the code.
+        console.warn(`⚠️  Skipped ${skipped.length} duplicate route(s) (same method + path registered twice):`);
+        for (const s of skipped)
+            console.warn(`     ${s}`);
+    }
     return routes;
 }
-function walkStack(stack, basePath, out, seen) {
+function walkStack(stack, basePath, out, seen, skipped) {
     for (const layer of stack) {
         if (layer.route) {
-            const r = buildRoute(layer.route, basePath);
-            if (r && !seen.has(r.method + r.path)) {
+            for (const r of buildRoutes(layer.route, basePath)) {
+                const key = `${r.method} ${r.path}`;
+                if (seen.has(key)) {
+                    skipped.push(key);
+                    continue;
+                }
                 out.push(r);
-                seen.add(r.method + r.path);
+                seen.add(key);
             }
         }
-        else if (layer.handle?.stack) {
-            // Router or sub-app mounted at a prefix
+        else {
+            // Router mounted at a prefix, or a sub-app (its layer only holds a `mounted_app` wrapper, so the
+            // mount hook hands over the app itself)
+            const subStack = layer.handle?.stack ?? (layer[express_mount_hook_js_1.SUB_APP] ? (0, express_mount_hook_js_1.appStack)(layer[express_mount_hook_js_1.SUB_APP]) : undefined);
+            if (!subStack)
+                continue;
+            // The path as written to use(), when the mount hook saw it; otherwise read back off the layer
             let prefix = '';
-            if (layer.regexp?.source)
+            if (typeof layer[express_mount_hook_js_1.MOUNT_PATH] === 'string')
+                prefix = normalizePath(layer[express_mount_hook_js_1.MOUNT_PATH]);
+            else if (layer.regexp?.source)
                 prefix = normalizePath(layer.regexp.source);
             else if (layer.path)
                 prefix = normalizePath(layer.path);
             else if (typeof layer.route === 'string')
                 prefix = normalizePath(layer.route);
             const combined = combinePaths(basePath, prefix);
-            walkStack(layer.handle.stack, combined, out, seen);
+            walkStack(subStack, combined, out, seen, skipped);
         }
     }
 }
@@ -91,14 +111,14 @@ const AUTH_NAMES = new Set([
     'checkToken', 'authMiddleware', 'jwt', 'bearer', 'apiKeyAuth',
     'passport.authenticate',
 ]);
-function buildRoute(route, basePath) {
+function buildRoutes(route, basePath) {
     if (!route.path)
-        return null;
+        return [];
     const methods = Object.keys(route.methods || {})
         .filter(m => route.methods[m])
         .map(m => m.toUpperCase());
     if (!methods.length)
-        return null;
+        return [];
     const cleanBase = normalizePath(basePath);
     const cleanRoute = normalizePath(route.path);
     let fullPath = (cleanBase === '/' ? '' : cleanBase) + cleanRoute;
@@ -142,19 +162,18 @@ function buildRoute(route, basePath) {
     // ── Auth detection ─────────────────────────────────────────────────────────
     const hasAuth = middleware.some(m => AUTH_NAMES.has(m) || [...AUTH_NAMES].some(a => m.toLowerCase().includes(a.toLowerCase()))) ||
         /req\.user|req\.auth|req\.currentUser|verifyToken|jwt\.verify|passport\.authenticate/.test(src);
-    const method = methods[0];
     const tag = tagFromPath(fullPath);
-    const summary = generateSummary(method, fullPath);
-    const operationId = `${method.toLowerCase()}_${fullPath
-        .replace(/[^a-zA-Z0-9]/g, '_')
-        .replace(/_+/g, '_')
-        .replace(/^_|_$/, '')}`;
-    return {
+    // One route per method: router.route('/x').get(...).put(...) registers a single layer
+    // carrying every method, and each one is its own endpoint.
+    return methods.map(method => ({
         method,
         path: fullPath,
         tag,
-        operationId,
-        summary,
+        operationId: `${method.toLowerCase()}_${fullPath
+            .replace(/[^a-zA-Z0-9]/g, '_')
+            .replace(/_+/g, '_')
+            .replace(/^_|_$/, '')}`,
+        summary: generateSummary(method, fullPath),
         middleware,
         authRequired: hasAuth,
         pathParams,
@@ -165,7 +184,7 @@ function buildRoute(route, basePath) {
         framework: 'express',
         responseStatuses: responseStatuses.length ? responseStatuses : undefined,
         headerParams: headerParams.length ? headerParams : undefined,
-    };
+    }));
 }
 // ─── Extraction helpers ───────────────────────────────────────────────────────
 function matchAll(src, re) {

package/dist/cjs/uploader.js

@@ -10,6 +10,16 @@ const axios_1 = __importDefault(require("axios"));
 const fs_1 = require("fs");
 const path_1 = require("path");
 const export_js_1 = require("./export.js");
+/** The backend's fields for a visibility choice — nothing when none was made. */
+function visibilityFields(choice) {
+    if (choice === 'ORG_WIDE')
+        return { visibility: 'ORG_WIDE', isPrivate: false };
+    if (choice === 'TEAM')
+        return { visibility: 'TEAM', isPrivate: false };
+    if (choice === 'PRIVATE')
+        return { visibility: 'TEAM', isPrivate: true };
+    return {};
+}
 /** Status file written to the project root so the CLI can detect completion. */
 const STATUS_FILE = '.apiforge-status.json';
 function writeStatusFile(status, data) {
@@ -44,6 +54,7 @@ async function uploadRoutes(routes, options) {
         framework: enrichedRoutes[0]?.framework || 'unknown',
         architectureType: options.architectureType || 'monolithic',
         services: options.services || [],
+        ...visibilityFields(options.visibility ?? process.env.APIFORGE_VISIBILITY),
     };
     try {
         const response = await axios_1.default.post(`${backendUrl}/api/cli/submit`, payload, {

package/dist/esm/cli.js

@@ -1,8 +1,8 @@
 #!/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 { readFileSync, existsSync, writeFileSync, unlinkSync, readdirSync, realpathSync } from 'fs';
 import { tmpdir } from 'os';
-import { join, basename, relative, isAbsolute } from 'path';
+import { join, basename, relative, isAbsolute, dirname } from 'path';
 import { spawn, spawnSync } from 'child_process';
 import axios from 'axios';
 import { detectArchitectureType } from './arch-detect.js';
@@ -106,6 +106,22 @@ async function main() {
         cancel('Cancelled.');
         process.exit(0);
     }
+    // ── Who can see the docs (APIForge spec §6.1 levels, chosen by the creator per §6.3) ──────────────────
+    const visibilityChoice = await select({
+        message: 'Who can see these docs?',
+        initialValue: 'PRIVATE', // "Only me" — the backend's default too
+        options: [
+            { value: 'ORG_WIDE', label: `${bold('Everyone in the org')}  ${dim('— every member of your organization')}` },
+            { value: 'TEAM', label: `${bold('Team')}  ${dim('— people you add, plus admins and the Superadmin')}` },
+            { value: 'PRIVATE', label: `${bold('Only me')}  ${dim('— you, people you add, and the Superadmin')}` },
+        ],
+    });
+    if (isCancel(visibilityChoice)) {
+        cancel('Cancelled.');
+        process.exit(0);
+    }
+    // Read by uploadRoutes — in this process and in the server this CLI starts (it inherits the environment)
+    process.env.APIFORGE_VISIBILITY = visibilityChoice;
     const isLocal = backendChoice === 'local';
     const backendUrl = isLocal ? BACKEND_LOCAL : BACKEND_PROD;
     const dashboardUrl = isLocal ? DASHBOARD_LOCAL : DASHBOARD_PROD;
@@ -666,7 +682,7 @@ async function microservicesFlow(config, opts) {
             cwd,
             stdio: ['ignore', 'pipe', 'pipe'],
             shell: true,
-            env: { ...process.env },
+            env: withExpressMountHook({ ...process.env }),
             detached: false,
         });
         // Capture output so failures are debuggable without re-running the service by hand.
@@ -1647,6 +1663,26 @@ function suppressNodemonSelfRestart(cwd) {
         catch { }
     };
 }
+/**
+ * Preloads the Express mount hook (express-preload.ts) into the user's server, so router / sub-app mount
+ * paths are recorded as they're registered — see express-mount-hook.ts. Without the built preload file
+ * (e.g. running from source) the env is returned unchanged and prefixes are read off the stack as before.
+ */
+function withExpressMountHook(env) {
+    let preload;
+    try {
+        // The bin is dist/esm/cli.js (or dist/cjs/cli.js); the preload must be the CommonJS build.
+        preload = join(dirname(realpathSync(process.argv[1])), '..', 'cjs', 'express-preload.js');
+    }
+    catch {
+        return env;
+    }
+    if (!existsSync(preload))
+        return env;
+    // Forward slashes: NODE_OPTIONS treats a backslash inside quotes as an escape.
+    const flag = `--require "${preload.replace(/\\/g, '/')}"`;
+    return { ...env, NODE_OPTIONS: env.NODE_OPTIONS ? `${env.NODE_OPTIONS} ${flag}` : flag };
+}
 function startAndWaitForAnalysis(command, timeoutMs) {
     return new Promise(resolve => {
         const statusPath = join(process.cwd(), STATUS_FILE);
@@ -1654,7 +1690,7 @@ function startAndWaitForAnalysis(command, timeoutMs) {
             cwd: process.cwd(),
             stdio: ['ignore', 'pipe', 'pipe'],
             shell: true,
-            env: { ...process.env },
+            env: withExpressMountHook({ ...process.env }),
             detached: false,
         });
         // Capture server output (head-capped) so we can show it on failure

package/dist/esm/detect.js

@@ -41,10 +41,19 @@ function mk(name, confidence) {
 export function detectFramework(app) {
     // ── Instance-based detection (highest confidence) ─────────────────────────
     if (app && typeof app === 'function') {
-        // Express: _router or lazyrouter
+        // Express 4: _router or lazyrouter
         if (app._router || (app.lazyrouter && typeof app.lazyrouter === 'function')) {
             return mk('express', 1.0);
         }
+        // Express 5 dropped both; the router is behind an `app.router` getter (which throws in Express 4).
+        // Without this, an Express 5 app in a project that also has an app/ folder was mistaken for Next.js.
+        try {
+            if (app.router && Array.isArray(app.router.stack))
+                return mk('express', 1.0);
+        }
+        catch {
+            // not Express 5
+        }
         // Koa: middleware array
         if (Array.isArray(app.middleware) && typeof app.use === 'function' && app.context) {
             return mk('koa', 0.95);

package/dist/esm/express-mount-hook.js

@@ -0,0 +1,77 @@
+/**
+ * Records where every router / sub-app is mounted, at the moment it is mounted.
+ *
+ * The Express analyzer reads mount prefixes back off the router stack after the fact, which loses them:
+ *  - Express 5 (router@2) keeps no path on a layer at all (only compiled matchers), so every mounted
+ *    router's routes came out without their prefix, and same-looking ones collapsed as duplicates.
+ *  - A sub-app (`app.use('/admin', express())`) is wrapped in a `mounted_app` function with no `stack`,
+ *    so none of its routes were found.
+ *  - Express 4's mount regexp for a parameterised prefix (`/users/:id/posts`) doesn't turn back into the path.
+ *
+ * Wrapping `use()` tags each layer it adds with the mount path as written, and a sub-app's layer with the
+ * sub-app itself; express.ts prefers those tags and falls back to the old regexp reading without them.
+ * Must run before the app registers its routes — the CLI preloads it (express-preload.ts).
+ */
+export const MOUNT_PATH = '__apiforgeMountPath';
+export const SUB_APP = '__apiforgeSubApp';
+const INSTALLED = Symbol.for('apiforge.expressMountHook');
+/** An app's router stack: `_router` in Express 4, the `router` getter in Express 5 (which throws in 4). */
+export function appStack(app) {
+    const legacy = app?._router?.stack;
+    if (Array.isArray(legacy))
+        return legacy;
+    try {
+        const stack = app?.router?.stack;
+        return Array.isArray(stack) ? stack : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The mount path `use()` was given, or undefined when the first argument is already a handler (Express's own rule). */
+function mountPathArg(args) {
+    let arg = args[0];
+    while (Array.isArray(arg) && arg.length !== 0)
+        arg = arg[0];
+    return typeof arg === 'function' ? undefined : args[0];
+}
+function isApp(fn) {
+    return !!fn && typeof fn.handle === 'function' && typeof fn.set === 'function';
+}
+function wrapUse(target, stackOf) {
+    const original = target.use;
+    if (typeof original !== 'function')
+        return;
+    target.use = function apiforgeUse(...args) {
+        const before = stackOf(this)?.length ?? 0;
+        const result = original.apply(this, args);
+        try {
+            const added = (stackOf(this) ?? []).slice(before);
+            const path = mountPathArg(args) ?? '/';
+            const handlers = (mountPathArg(args) === undefined ? args : args.slice(1)).flat(Infinity);
+            const subApps = handlers.filter(isApp);
+            let next = 0;
+            for (const layer of added) {
+                layer[MOUNT_PATH] = path;
+                if (layer.handle?.name === 'mounted_app' && next < subApps.length)
+                    layer[SUB_APP] = subApps[next++];
+            }
+        }
+        catch {
+            // Never let documentation tagging break the user's app.
+        }
+        return result;
+    };
+}
+export function installExpressMountHook(express) {
+    if (!express || express[INSTALLED])
+        return;
+    express[INSTALLED] = true;
+    // Express 5: Router is a class (router@2). Express 4: Router is the proto object itself.
+    const Router = express.Router;
+    const routerProto = typeof Router?.prototype?.use === 'function' ? Router.prototype : Router;
+    if (routerProto)
+        wrapUse(routerProto, (self) => (Array.isArray(self?.stack) ? self.stack : undefined));
+    if (express.application)
+        wrapUse(express.application, appStack);
+}

package/dist/esm/express-preload.js

@@ -0,0 +1,15 @@
+/**
+ * Preloaded into the user's server by the CLI (`NODE_OPTIONS=--require …/dist/cjs/express-preload.js`) so
+ * the mount hook is in place before any route is registered. Loads the project's own express (resolved
+ * from the working directory); a project without express is left untouched.
+ */
+import { createRequire } from 'module';
+import { join } from 'path';
+import { installExpressMountHook } from './express-mount-hook.js';
+try {
+    const projectRequire = createRequire(join(process.cwd(), 'noop.js'));
+    installExpressMountHook(projectRequire('express'));
+}
+catch {
+    // No express here (npm, nodemon, a non-Express project): nothing to record.
+}

package/dist/esm/frameworks/express.js

@@ -1,6 +1,7 @@
 /**
  * Express route analyzer — deep extraction of routes, parameters, and auth patterns
  */
+import { MOUNT_PATH, SUB_APP, appStack } from '../express-mount-hook.js';
 // ─── Path helpers ─────────────────────────────────────────────────────────────
 function normalizePath(raw) {
     return raw
@@ -49,29 +50,48 @@ export function analyzeExpress(app) {
         console.warn('⚠️  No routes found — ensure routes are registered before analyze()');
         return routes;
     }
-    walkStack(stack, '', routes, seen);
+    const skipped = [];
+    walkStack(stack, '', routes, seen, skipped);
+    if (skipped.length) {
+        // Same method + path registered more than once: Express only ever serves the first, so it is
+        // documented once — but say so, so the count can be checked against the code.
+        console.warn(`⚠️  Skipped ${skipped.length} duplicate route(s) (same method + path registered twice):`);
+        for (const s of skipped)
+            console.warn(`     ${s}`);
+    }
     return routes;
 }
-function walkStack(stack, basePath, out, seen) {
+function walkStack(stack, basePath, out, seen, skipped) {
     for (const layer of stack) {
         if (layer.route) {
-            const r = buildRoute(layer.route, basePath);
-            if (r && !seen.has(r.method + r.path)) {
+            for (const r of buildRoutes(layer.route, basePath)) {
+                const key = `${r.method} ${r.path}`;
+                if (seen.has(key)) {
+                    skipped.push(key);
+                    continue;
+                }
                 out.push(r);
-                seen.add(r.method + r.path);
+                seen.add(key);
             }
         }
-        else if (layer.handle?.stack) {
-            // Router or sub-app mounted at a prefix
+        else {
+            // Router mounted at a prefix, or a sub-app (its layer only holds a `mounted_app` wrapper, so the
+            // mount hook hands over the app itself)
+            const subStack = layer.handle?.stack ?? (layer[SUB_APP] ? appStack(layer[SUB_APP]) : undefined);
+            if (!subStack)
+                continue;
+            // The path as written to use(), when the mount hook saw it; otherwise read back off the layer
             let prefix = '';
-            if (layer.regexp?.source)
+            if (typeof layer[MOUNT_PATH] === 'string')
+                prefix = normalizePath(layer[MOUNT_PATH]);
+            else if (layer.regexp?.source)
                 prefix = normalizePath(layer.regexp.source);
             else if (layer.path)
                 prefix = normalizePath(layer.path);
             else if (typeof layer.route === 'string')
                 prefix = normalizePath(layer.route);
             const combined = combinePaths(basePath, prefix);
-            walkStack(layer.handle.stack, combined, out, seen);
+            walkStack(subStack, combined, out, seen, skipped);
         }
     }
 }
@@ -88,14 +108,14 @@ const AUTH_NAMES = new Set([
     'checkToken', 'authMiddleware', 'jwt', 'bearer', 'apiKeyAuth',
     'passport.authenticate',
 ]);
-function buildRoute(route, basePath) {
+function buildRoutes(route, basePath) {
     if (!route.path)
-        return null;
+        return [];
     const methods = Object.keys(route.methods || {})
         .filter(m => route.methods[m])
         .map(m => m.toUpperCase());
     if (!methods.length)
-        return null;
+        return [];
     const cleanBase = normalizePath(basePath);
     const cleanRoute = normalizePath(route.path);
     let fullPath = (cleanBase === '/' ? '' : cleanBase) + cleanRoute;
@@ -139,19 +159,18 @@ function buildRoute(route, basePath) {
     // ── Auth detection ─────────────────────────────────────────────────────────
     const hasAuth = middleware.some(m => AUTH_NAMES.has(m) || [...AUTH_NAMES].some(a => m.toLowerCase().includes(a.toLowerCase()))) ||
         /req\.user|req\.auth|req\.currentUser|verifyToken|jwt\.verify|passport\.authenticate/.test(src);
-    const method = methods[0];
     const tag = tagFromPath(fullPath);
-    const summary = generateSummary(method, fullPath);
-    const operationId = `${method.toLowerCase()}_${fullPath
-        .replace(/[^a-zA-Z0-9]/g, '_')
-        .replace(/_+/g, '_')
-        .replace(/^_|_$/, '')}`;
-    return {
+    // One route per method: router.route('/x').get(...).put(...) registers a single layer
+    // carrying every method, and each one is its own endpoint.
+    return methods.map(method => ({
         method,
         path: fullPath,
         tag,
-        operationId,
-        summary,
+        operationId: `${method.toLowerCase()}_${fullPath
+            .replace(/[^a-zA-Z0-9]/g, '_')
+            .replace(/_+/g, '_')
+            .replace(/^_|_$/, '')}`,
+        summary: generateSummary(method, fullPath),
         middleware,
         authRequired: hasAuth,
         pathParams,
@@ -162,7 +181,7 @@ function buildRoute(route, basePath) {
         framework: 'express',
         responseStatuses: responseStatuses.length ? responseStatuses : undefined,
         headerParams: headerParams.length ? headerParams : undefined,
-    };
+    }));
 }
 // ─── Extraction helpers ───────────────────────────────────────────────────────
 function matchAll(src, re) {