spec-gen-cli 1.2.7 → 1.2.8

package/dist/core/analyzer/env-extractor.js

@@ -0,0 +1,196 @@
+/**
+ * Environment Variable Extractor
+ *
+ * Detects env vars used in a project from two complementary sources:
+ *   1. Declaration files — .env.example, .env.local, .env (with optional comments)
+ *   2. Source code — process.env.X (JS/TS), os.environ["X"] (Python),
+ *      os.Getenv("X") (Go), ENV["X"] (Ruby)
+ *
+ * Variables found in declaration files are marked hasDefault=true when the
+ * declaration line has a non-empty value. Variables found only in source code
+ * are marked required=true (no known default).
+ */
+import { readFile } from 'node:fs/promises';
+import { extname, relative, basename } from 'node:path';
+// ============================================================================
+// ENV FILE PARSER
+// ============================================================================
+function parseEnvFile(content, relPath) {
+    const vars = [];
+    let pendingComment = '';
+    for (const rawLine of content.split('\n')) {
+        const line = rawLine.trim();
+        // Accumulate comment lines as description
+        if (line.startsWith('#')) {
+            pendingComment = line.replace(/^#+\s*/, '');
+            continue;
+        }
+        if (!line) {
+            pendingComment = '';
+            continue;
+        }
+        const eqIdx = line.indexOf('=');
+        if (eqIdx === -1) {
+            pendingComment = '';
+            continue;
+        }
+        const name = line.slice(0, eqIdx).trim();
+        if (!/^[A-Z_][A-Z0-9_]*$/.test(name)) {
+            pendingComment = '';
+            continue;
+        }
+        const rawValue = line.slice(eqIdx + 1).trim();
+        // Strip inline comment from value
+        const valueWithoutComment = rawValue.replace(/#.*$/, '').trim();
+        const inlineComment = rawValue.includes('#')
+            ? rawValue.slice(rawValue.indexOf('#') + 1).trim()
+            : '';
+        const hasDefault = valueWithoutComment.length > 0;
+        const description = inlineComment || pendingComment || undefined;
+        vars.push({ name, files: [relPath], hasDefault, required: false, description });
+        pendingComment = '';
+    }
+    return vars;
+}
+// ============================================================================
+// SOURCE CODE SCANNERS
+// ============================================================================
+// JS/TS: process.env.VAR_NAME or process.env['VAR_NAME'] or process.env["VAR_NAME"]
+const TS_ENV_RE = /process\.env\.([A-Z_][A-Z0-9_]*)|process\.env\[['"]([A-Z_][A-Z0-9_]*)['"]]/g;
+// Fallback detection: process.env.X ?? 'default' or process.env.X || 'default'
+const TS_HAS_FALLBACK_RE = /process\.env\.(?:[A-Z_][A-Z0-9_]*|\[['"][A-Z_][A-Z0-9_]*['"]])\s*(?:\?\?|(?<!\|)\|\|)/;
+// Python: os.environ["X"], os.environ['X'], os.environ.get("X"), os.getenv("X")
+const PY_ENV_RE = /os\.environ\[['"]([A-Z_][A-Z0-9_]*)['"]|os\.environ\.get\(['"]([A-Z_][A-Z0-9_]*)['"]|os\.getenv\(['"]([A-Z_][A-Z0-9_]*)['"]/g;
+// Go: os.Getenv("X")
+const GO_ENV_RE = /os\.Getenv\("([A-Z_][A-Z0-9_]*)"\)/g;
+// Ruby: ENV["X"], ENV['X'], ENV.fetch("X")
+const RUBY_ENV_RE = /ENV\[['"]([A-Z_][A-Z0-9_]*)['"]|ENV\.fetch\(['"]([A-Z_][A-Z0-9_]*)['"]/g;
+function extractFromSource(source, relPath, ext) {
+    const found = [];
+    let re;
+    let hasFallback = false;
+    if (['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'].includes(ext)) {
+        re = new RegExp(TS_ENV_RE.source, 'g');
+        hasFallback = TS_HAS_FALLBACK_RE.test(source);
+        let m;
+        while ((m = re.exec(source)) !== null) {
+            const name = m[1] ?? m[2];
+            if (name)
+                found.push({ name, required: !hasFallback });
+        }
+    }
+    else if (['.py', '.pyw'].includes(ext)) {
+        re = new RegExp(PY_ENV_RE.source, 'g');
+        let m;
+        while ((m = re.exec(source)) !== null) {
+            const name = m[1] ?? m[2] ?? m[3];
+            // os.environ.get and os.getenv have optional defaults → not strictly required
+            const isStrict = m[1] !== undefined; // only os.environ["X"] is strict
+            if (name)
+                found.push({ name, required: isStrict });
+        }
+    }
+    else if (ext === '.go') {
+        re = new RegExp(GO_ENV_RE.source, 'g');
+        let m;
+        while ((m = re.exec(source)) !== null) {
+            if (m[1])
+                found.push({ name: m[1], required: false }); // Go always uses string return, caller checks
+        }
+    }
+    else if (ext === '.rb') {
+        re = new RegExp(RUBY_ENV_RE.source, 'g');
+        let m;
+        while ((m = re.exec(source)) !== null) {
+            const name = m[1] ?? m[2];
+            const isStrict = m[1] !== undefined; // ENV.fetch has optional default
+            if (name)
+                found.push({ name, required: isStrict });
+        }
+    }
+    return found;
+}
+// ============================================================================
+// PUBLIC API
+// ============================================================================
+const ENV_DECLARATION_FILES = new Set(['.env', '.env.example', '.env.local', '.env.test', '.env.production']);
+const SOURCE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.py', '.pyw', '.go', '.rb']);
+const SKIP_DIRS = ['/node_modules/', '/.spec-gen/', '/dist/', '/build/', '/coverage/'];
+/**
+ * Extract all environment variables referenced or declared in the project.
+ */
+export async function extractEnvVars(filePaths, rootDir) {
+    const map = new Map();
+    function upsert(name, relPath, patch) {
+        const existing = map.get(name);
+        if (existing) {
+            if (!existing.files.includes(relPath))
+                existing.files.push(relPath);
+            if (patch.hasDefault)
+                existing.hasDefault = true;
+            if (patch.required)
+                existing.required = true;
+            if (patch.description && !existing.description)
+                existing.description = patch.description;
+        }
+        else {
+            map.set(name, {
+                name,
+                files: [relPath],
+                hasDefault: patch.hasDefault ?? false,
+                required: patch.required ?? false,
+                description: patch.description,
+            });
+        }
+    }
+    await Promise.all(filePaths.map(async (fp) => {
+        if (SKIP_DIRS.some(d => fp.replace(/\\/g, '/').includes(d)))
+            return;
+        const name = basename(fp);
+        const ext = extname(fp).toLowerCase();
+        const rel = relative(rootDir, fp);
+        let source;
+        try {
+            source = await readFile(fp, 'utf-8');
+        }
+        catch {
+            return;
+        }
+        // Env declaration files
+        if (ENV_DECLARATION_FILES.has(name)) {
+            for (const v of parseEnvFile(source, rel)) {
+                upsert(v.name, rel, { hasDefault: v.hasDefault, description: v.description });
+            }
+            return;
+        }
+        // Source files
+        if (!SOURCE_EXTENSIONS.has(ext))
+            return;
+        // Skip test files
+        if (fp.includes('.test.') || fp.includes('.spec.') || fp.includes('_test.') || fp.includes('_spec.'))
+            return;
+        for (const { name: varName, required } of extractFromSource(source, rel, ext)) {
+            upsert(varName, rel, { required });
+        }
+    }));
+    return [...map.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Return a compact summary string for LLM prompts.
+ */
+export function summarizeEnvVars(vars) {
+    if (vars.length === 0)
+        return '';
+    const lines = vars.map(v => {
+        const flags = [];
+        if (v.required)
+            flags.push('required');
+        if (v.hasDefault)
+            flags.push('has-default');
+        const suffix = flags.length > 0 ? ` [${flags.join(', ')}]` : '';
+        const desc = v.description ? ` — ${v.description}` : '';
+        return `  ${v.name}${suffix}${desc}`;
+    });
+    return `Environment variables (${vars.length}):\n${lines.join('\n')}`;
+}
+//# sourceMappingURL=env-extractor.js.map

package/dist/core/analyzer/env-extractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-extractor.js","sourceRoot":"","sources":["../../../src/core/analyzer/env-extractor.ts"],"names":[],"mappings":"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"}

package/dist/core/analyzer/http-route-parser.d.ts

@@ -52,10 +52,16 @@ export interface RouteDefinition {
     normalizedPath: string;
     /** Name of the handler function */
     handlerName: string;
-    /** fastapi / flask / django / starlette */
+    /** fastapi / flask / django / starlette / express / nestjs / nextjs-app etc. */
     framework: string;
     /** 1-based source line */
     line: number;
+    /** Request body type extracted from handler signature, e.g. "CreateUserDto" or "z.infer<typeof schema>" */
+    requestBodyType?: string;
+    /** Response body type extracted from handler return type annotation, e.g. "User[]" or "void" */
+    responseType?: string;
+    /** How the contract was sourced */
+    contractSource: 'annotation' | 'validator' | 'none';
 }
 /** A resolved cross-language edge */
 export interface HttpEdge {
@@ -108,4 +114,33 @@ export declare function extractAllHttpEdges(filePaths: string[]): Promise<{
     routes: RouteDefinition[];
     edges: HttpEdge[];
 }>;
+/**
+ * Extract HTTP route definitions from a TypeScript/JavaScript server file.
+ * Handles Express-style, NestJS decorators, and Next.js App Router.
+ */
+export declare function extractTsRouteDefinitions(filePath: string): Promise<RouteDefinition[]>;
+export interface RouteInventory {
+    total: number;
+    byMethod: Record<string, number>;
+    byFramework: Record<string, number>;
+    routes: Array<{
+        method: string;
+        path: string;
+        framework: string;
+        file: string;
+        handler: string;
+        requestBodyType?: string;
+        responseType?: string;
+        contractSource: 'annotation' | 'validator' | 'none';
+    }>;
+}
+/**
+ * Build a complete route inventory from all source files.
+ * Combines Python routes (extractRouteDefinitions) and TS/JS routes
+ * (extractTsRouteDefinitions) into a single summary.
+ *
+ * @param filePaths - Absolute paths to all source files in the project
+ * @param rootDir   - Project root for computing relative paths
+ */
+export declare function buildRouteInventory(filePaths: string[], rootDir: string): Promise<RouteInventory>;
 //# sourceMappingURL=http-route-parser.d.ts.map

package/dist/core/analyzer/http-route-parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-route-parser.d.ts","sourceRoot":"","sources":["../../../src/core/analyzer/http-route-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AASH,gDAAgD;AAChD,MAAM,WAAW,QAAQ;IACvB,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,GAAG,EAAE,MAAM,CAAC;IACZ,8EAA8E;IAC9E,aAAa,EAAE,MAAM,CAAC;IACtB,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,mCAAmC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,qCAAqC;AACrC,MAAM,WAAW,QAAQ;IACvB,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,eAAe,CAAC;IACvB,iCAAiC;IACjC,UAAU,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;CACxC;AAaD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAsBhD;AAuBD;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAuH5E;AAMD;;;GAGG;AACH,wBAAsB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAgI1F;AAMD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,QAAQ,EAAE,EACjB,MAAM,EAAE,eAAe,EAAE,GACxB,QAAQ,EAAE,CAgFZ;AAMD;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IACtE,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB,CAAC,CAmBD"}
+{"version":3,"file":"http-route-parser.d.ts","sourceRoot":"","sources":["../../../src/core/analyzer/http-route-parser.ts"],"names":[],"mappings":"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"}

package/dist/core/analyzer/http-route-parser.js

@@ -27,6 +27,7 @@
  */
 import { readFile } from 'node:fs/promises';
 import { extname } from 'node:path';
+import { getSkeletonContent, detectLanguage } from './code-shaper.js';
 // ============================================================================
 // NORMALISATION HELPERS
 // ============================================================================
@@ -236,6 +237,7 @@ export async function extractRouteDefinitions(filePath) {
             handlerName,
             framework: 'fastapi',
             line: lineNum,
+            contractSource: 'none',
         });
     }
     // @app.api_route("/path", methods=["GET", "POST"])
@@ -255,6 +257,7 @@ export async function extractRouteDefinitions(filePath) {
                 handlerName,
                 framework: 'fastapi',
                 line: lineNum,
+                contractSource: 'none',
             });
         }
     }
@@ -278,6 +281,7 @@ export async function extractRouteDefinitions(filePath) {
                     handlerName,
                     framework: 'flask',
                     line: lineNum,
+                    contractSource: 'none',
                 });
             }
         }
@@ -291,6 +295,7 @@ export async function extractRouteDefinitions(filePath) {
                 handlerName,
                 framework: 'flask',
                 line: lineNum,
+                contractSource: 'none',
             });
         }
     }
@@ -317,6 +322,7 @@ export async function extractRouteDefinitions(filePath) {
             handlerName,
             framework: 'django',
             line: lineNum,
+            contractSource: 'none',
         });
     }
     return routes;
@@ -463,4 +469,274 @@ function extractNextDefName(lines, decoratorLine) {
     }
     return 'unknown';
 }
+// ============================================================================
+// CONTRACT / TYPE EXTRACTION HELPERS
+// ============================================================================
+/**
+ * Extract contract information from a handler function body or surrounding context.
+ *
+ * Strategies:
+ *   1. TypeScript Request<P, ResBody, ReqBody, Q> generic → requestBodyType = ReqBody
+ *   2. NestJS @Body() dto: Type → requestBodyType = Type
+ *   3. Zod .parse( / .parseAsync( → contractSource = 'validator'
+ *   4. Promise<ResponseType> return annotation
+ */
+function extractContractFromHandler(handlerSource) {
+    let requestBodyType;
+    let responseType;
+    let contractSource = 'none';
+    // 1. TypeScript Request<P, ResBody, ReqBody, Q> generic
+    //    handler(req: Request<Params, ResBody, Body, Query>)
+    const reqGenericRe = /:\s*Request\s*<[^,>]+,\s*([^,>]+),\s*([^,>]+)/;
+    const reqGenericMatch = reqGenericRe.exec(handlerSource);
+    if (reqGenericMatch) {
+        const resBodyType = reqGenericMatch[1].trim();
+        const reqBodyType = reqGenericMatch[2].trim();
+        if (reqBodyType && reqBodyType !== 'unknown' && reqBodyType !== 'any') {
+            requestBodyType = reqBodyType;
+            contractSource = 'annotation';
+        }
+        if (resBodyType && resBodyType !== 'unknown' && resBodyType !== 'any') {
+            responseType = resBodyType;
+        }
+    }
+    // 2. NestJS @Body() dto: CreateUserDto
+    const bodyParamRe = /@Body\s*\(\s*\)\s+\w+\s*:\s*(\w+)/;
+    const bodyParamMatch = bodyParamRe.exec(handlerSource);
+    if (bodyParamMatch) {
+        requestBodyType = bodyParamMatch[1];
+        contractSource = 'annotation';
+    }
+    // 3. Zod validators: schema.parse( / schema.parseAsync( / z.infer<typeof
+    const zodRe = /\b\w+\.parse(?:Async)?\s*\(|z\.infer\s*<\s*typeof\s+(\w+)/;
+    const zodMatch = zodRe.exec(handlerSource);
+    if (zodMatch) {
+        contractSource = 'validator';
+        if (zodMatch[1]) {
+            requestBodyType = `z.infer<typeof ${zodMatch[1]}>`;
+        }
+        else {
+            // Extract schema variable name from .parse( call
+            const parseVarRe = /(\w+)\.parse(?:Async)?\s*\(/;
+            const parseVarMatch = parseVarRe.exec(handlerSource);
+            if (parseVarMatch) {
+                requestBodyType = parseVarMatch[1];
+            }
+        }
+    }
+    // 4. Promise<ResponseType> return type annotation
+    const returnTypeRe = /\):\s*Promise\s*<\s*([^>]+)>/;
+    const returnTypeMatch = returnTypeRe.exec(handlerSource);
+    if (returnTypeMatch && !responseType) {
+        const rType = returnTypeMatch[1].trim();
+        if (rType && rType !== 'void' && rType !== 'unknown' && rType !== 'any') {
+            responseType = rType;
+        }
+    }
+    return { requestBodyType, responseType, contractSource };
+}
+// ============================================================================
+// TS/JS SERVER ROUTE EXTRACTION
+// ============================================================================
+// Express / Hono / Fastify / Koa / Elysia style:
+//   app.get('/path', handler)
+//   router.post('/path', ...)
+//   app.use('/prefix', router)     ← prefix accumulation
+const EXPRESS_ROUTE_RE = /(?:^|[\s;(,])(?:app|router|server|api|r)\.(get|post|put|delete|patch|head|options|all)\s*\(\s*['"`]([^'"`]+)['"`]/gm;
+const EXPRESS_USE_RE = /(?:^|[\s;(,])(?:app|router|server|api|r)\.use\s*\(\s*['"`]([^'"`]+)['"`]/gm;
+// NestJS decorator-based:
+//   @Controller('prefix')  →  class methods with @Get / @Post etc.
+const NESTJS_CONTROLLER_RE = /@Controller\s*\(\s*['"`]([^'"`]*)['"`]\s*\)/g;
+const NESTJS_METHOD_RE = /@(Get|Post|Put|Delete|Patch|Head|Options|All)\s*\(\s*(?:['"`]([^'"`]*)['"`])?\s*\)/g;
+const NESTJS_HANDLER_RE = /(?:async\s+)?(\w+)\s*\(/;
+// Next.js App Router: export (async) function GET(...) in app/**/route.ts
+const NEXTJS_APP_ROUTER_RE = /^export\s+(?:async\s+)?function\s+(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)\s*\(/gm;
+/** Detected framework from a file's content */
+function detectTsFramework(source, filePath) {
+    if (/@Controller\s*\(/.test(source) && /@(Get|Post|Put|Delete|Patch)\s*\(/.test(source))
+        return 'nestjs';
+    if (/app\/.*\/route\.[jt]sx?$/.test(filePath.replace(/\\/g, '/')))
+        return 'nextjs-app';
+    if (/pages\/api\//.test(filePath.replace(/\\/g, '/')))
+        return 'nextjs-pages';
+    if (/from\s+['"]hono['"]/.test(source) || /new\s+Hono\s*[(<]/.test(source))
+        return 'hono';
+    if (/from\s+['"]fastify['"]/.test(source) || /fastify\s*\(/.test(source))
+        return 'fastify';
+    if (/from\s+['"]express['"]/.test(source) || /require\s*\(\s*['"]express['"]\s*\)/.test(source))
+        return 'express';
+    if (/from\s+['"]koa['"]/.test(source))
+        return 'koa';
+    if (/from\s+['"]elysia['"]/.test(source))
+        return 'elysia';
+    if (new RegExp(EXPRESS_ROUTE_RE.source).test(source))
+        return 'express';
+    return 'unknown';
+}
+/**
+ * Extract HTTP route definitions from a TypeScript/JavaScript server file.
+ * Handles Express-style, NestJS decorators, and Next.js App Router.
+ */
+export async function extractTsRouteDefinitions(filePath) {
+    let source;
+    try {
+        const { readFile } = await import('node:fs/promises');
+        // Use skeleton to strip comments — prevents false positives from comment
+        // examples inside parser/extractor files that contain route pattern strings.
+        // Line numbers in the result are approximate (skeleton line positions).
+        source = getSkeletonContent(await readFile(filePath, 'utf-8'), detectLanguage(filePath));
+    }
+    catch {
+        return [];
+    }
+    const framework = detectTsFramework(source, filePath);
+    const routes = [];
+    const lines = source.split('\n');
+    function lineOf(index) {
+        return source.slice(0, index).split('\n').length;
+    }
+    // ── Next.js App Router ────────────────────────────────────────────────────
+    if (framework === 'nextjs-app') {
+        // Derive path from file location: app/users/route.ts → /users
+        const rel = filePath.replace(/\\/g, '/');
+        const appIdx = rel.lastIndexOf('/app/');
+        let routePath = '/';
+        if (appIdx >= 0) {
+            routePath = rel.slice(appIdx + 4).replace(/\/route\.[jt]sx?$/, '') || '/';
+            // Remove dynamic segments brackets for display: [id] → :id
+            routePath = routePath.replace(/\[([^\]]+)\]/g, ':$1');
+        }
+        const re = new RegExp(NEXTJS_APP_ROUTER_RE.source, NEXTJS_APP_ROUTER_RE.flags);
+        let m;
+        while ((m = re.exec(source)) !== null) {
+            // Extract handler body for contract detection (scan next 500 chars)
+            const handlerBody = source.slice(m.index, m.index + 500);
+            const contract = extractContractFromHandler(handlerBody);
+            routes.push({
+                file: filePath,
+                method: m[1].toUpperCase(),
+                path: routePath,
+                normalizedPath: normalizeUrl(routePath),
+                handlerName: m[1],
+                framework: 'nextjs-app',
+                line: lineOf(m.index),
+                ...contract,
+            });
+        }
+        return routes;
+    }
+    // ── NestJS ────────────────────────────────────────────────────────────────
+    if (framework === 'nestjs') {
+        // Collect controller prefixes
+        const ctrlRe = new RegExp(NESTJS_CONTROLLER_RE.source, NESTJS_CONTROLLER_RE.flags);
+        let ctrlPrefix = '';
+        const ctrlMatch = ctrlRe.exec(source);
+        if (ctrlMatch) {
+            ctrlPrefix = ctrlMatch[1] ? `/${ctrlMatch[1].replace(/^\//, '')}` : '';
+        }
+        const methodRe = new RegExp(NESTJS_METHOD_RE.source, NESTJS_METHOD_RE.flags);
+        let m;
+        while ((m = methodRe.exec(source)) !== null) {
+            const httpMethod = m[1].toUpperCase();
+            const subPath = m[2] ? `/${m[2].replace(/^\//, '')}` : '';
+            const fullPath = `${ctrlPrefix}${subPath}` || '/';
+            // Find handler function name on subsequent lines
+            const afterDecorator = source.slice(m.index + m[0].length);
+            const handlerMatch = NESTJS_HANDLER_RE.exec(afterDecorator.slice(0, 200));
+            const handlerName = handlerMatch?.[1] ?? 'unknown';
+            // Extract contract from decorator + handler context (scan next 400 chars)
+            const handlerContext = source.slice(m.index, m.index + 400);
+            const contract = extractContractFromHandler(handlerContext);
+            routes.push({
+                file: filePath,
+                method: httpMethod,
+                path: fullPath,
+                normalizedPath: normalizeUrl(fullPath),
+                handlerName,
+                framework: 'nestjs',
+                line: lineOf(m.index),
+                ...contract,
+            });
+        }
+        return routes;
+    }
+    // ── Express / Hono / Fastify / Koa / Elysia ───────────────────────────────
+    // Collect prefix map from .use() calls (best-effort)
+    const prefixes = [];
+    const useRe = new RegExp(EXPRESS_USE_RE.source, EXPRESS_USE_RE.flags);
+    let um;
+    while ((um = useRe.exec(source)) !== null) {
+        prefixes.push(um[1]);
+    }
+    const routeRe = new RegExp(EXPRESS_ROUTE_RE.source, EXPRESS_ROUTE_RE.flags);
+    let m;
+    while ((m = routeRe.exec(source)) !== null) {
+        const method = m[1].toUpperCase();
+        let path = m[2];
+        // Apply a prefix if the route is relative (no leading slash)
+        if (!path.startsWith('/') && prefixes.length > 0) {
+            path = `${prefixes[0]}/${path}`;
+        }
+        // Find the handler name from the same line
+        const lineText = lines[lineOf(m.index) - 1] ?? '';
+        const handlerMatch = lineText.match(/,\s*(?:async\s+)?(?:function\s+)?(\w+)\s*[,)]/);
+        const handlerName = handlerMatch?.[1] ?? 'handler';
+        // Extract contract from route context (scan next 600 chars)
+        const routeContext = source.slice(m.index, m.index + 600);
+        const contract = extractContractFromHandler(routeContext);
+        routes.push({
+            file: filePath,
+            method,
+            path,
+            normalizedPath: normalizeUrl(path),
+            handlerName,
+            framework,
+            line: lineOf(m.index),
+            ...contract,
+        });
+    }
+    return routes;
+}
+/**
+ * Build a complete route inventory from all source files.
+ * Combines Python routes (extractRouteDefinitions) and TS/JS routes
+ * (extractTsRouteDefinitions) into a single summary.
+ *
+ * @param filePaths - Absolute paths to all source files in the project
+ * @param rootDir   - Project root for computing relative paths
+ */
+export async function buildRouteInventory(filePaths, rootDir) {
+    const { relative } = await import('node:path');
+    const allRoutes = [];
+    await Promise.all(filePaths.map(async (fp) => {
+        const ext = extname(fp).toLowerCase();
+        if (['.py', '.pyw'].includes(ext)) {
+            allRoutes.push(...await extractRouteDefinitions(fp));
+        }
+        else if (['.ts', '.tsx', '.js', '.jsx', '.mjs'].includes(ext)) {
+            allRoutes.push(...await extractTsRouteDefinitions(fp));
+        }
+    }));
+    const byMethod = {};
+    const byFramework = {};
+    for (const r of allRoutes) {
+        byMethod[r.method] = (byMethod[r.method] ?? 0) + 1;
+        byFramework[r.framework] = (byFramework[r.framework] ?? 0) + 1;
+    }
+    return {
+        total: allRoutes.length,
+        byMethod,
+        byFramework,
+        routes: allRoutes.map(r => ({
+            method: r.method,
+            path: r.path,
+            framework: r.framework,
+            file: relative(rootDir, r.file),
+            handler: r.handlerName,
+            requestBodyType: r.requestBodyType,
+            responseType: r.responseType,
+            contractSource: r.contractSource,
+        })),
+    };
+}
 //# sourceMappingURL=http-route-parser.js.map