gitnexus 1.6.9-rc.24 → 1.6.9-rc.26

package/dist/core/group/extractors/http-patterns/python.js

@@ -1,5 +1,6 @@
 import Python from 'tree-sitter-python';
 import { compilePatterns, runCompiledPatterns, unquoteLiteral, } from '../tree-sitter-scanner.js';
+import { normalizeExtractedRoutePath } from '../../../ingestion/route-extractors/route-path.js';
 /**
  * Python HTTP plugin. Handles:
  *   - FastAPI `@app.get("/path")` provider decorators
@@ -146,6 +147,25 @@ const INCLUDE_ROUTER_NAME_PATTERNS = compilePatterns({
         },
     ],
 });
+const API_ROUTER_PREFIX_PATTERNS = compilePatterns({
+    name: 'python-fastapi-apirouter-prefix',
+    language: Python,
+    patterns: [
+        {
+            meta: {},
+            query: `
+        (assignment
+          left: (identifier) @router_name (#eq? @router_name "router")
+          right: (call
+            function: (identifier) @factory (#eq? @factory "APIRouter")
+            arguments: (argument_list
+              (keyword_argument
+                name: (identifier) @kw (#eq? @kw "prefix")
+                value: (string) @prefix))))
+      `,
+        },
+    ],
+});
 // `from .api.assistant import router` style — used together with
 // INCLUDE_ROUTER_NAME so we can map a local name back to its module
 // path, then back to the file the router was declared in.
@@ -813,10 +833,10 @@ function recordPrefix(target, key, prefix) {
 function buildPythonRepoContext(files, parser, readFile, parseSource) {
     const prefixesByLongKey = new Map();
     const prefixesByShortKey = new Map();
-    // Pre-pass over .py files. We deliberately run this even on files
-    // that don't contain `include_router` — the cost of an extra parse
-    // is bounded by the file count, and detecting `include_router`
-    // beforehand would require its own grep/scan.
+    // Cross-file pre-pass: only `include_router` sites need it — they bind a
+    // prefix declared in one file to a router defined in another. Same-file
+    // `APIRouter(prefix=...)` is resolved in scan() from the file's own tree, so
+    // APIRouter-only files are left out here and never parsed twice.
     for (const rel of files) {
         if (!rel.endsWith('.py'))
             continue;
@@ -912,14 +932,16 @@ function buildPythonRepoContext(files, parser, readFile, parseSource) {
             }
         }
     }
-    return { prefixesByLongKey, prefixesByShortKey };
+    return {
+        prefixesByLongKey,
+        prefixesByShortKey,
+    };
 }
 function joinPrefix(prefix, route) {
-    // Mirror FastAPI's path joining: trim trailing slash off prefix,
-    // ensure exactly one leading slash on the result.
-    const p = prefix.replace(/\/+$/, '');
-    const r = route.startsWith('/') ? route : `/${route}`;
-    return `${p}${r}`;
+    // Delegate to the shared route-path normalizer so the group contract and the
+    // ingestion Route node join prefixes identically — one helper, no
+    // trailing-slash drift on empty routes (`APIRouter(prefix="/x")` + `@get("")`).
+    return normalizeExtractedRoutePath(route, prefix);
 }
 export const PYTHON_HTTP_PLUGIN = {
     name: 'python-http',
@@ -979,6 +1001,19 @@ export const PYTHON_HTTP_PLUGIN = {
         // Django providers come from the graph Route nodes (includes composed by
         // the ingestion route extractor), not a per-file source scan — see the note
         // at the top of this file.
+        // Same-file `router = APIRouter(prefix="/x")` (router-only). Read from this
+        // file's own tree, so there is no cross-file map and no prefix bleed across
+        // same-stem files; it stacks under any include_router(prefix=...) below.
+        let constructorPrefix;
+        for (const m of runCompiledPatterns(API_ROUTER_PREFIX_PATTERNS, tree)) {
+            const prefixNode = m.captures.prefix;
+            if (!prefixNode)
+                continue;
+            const p = unquoteLiteral(prefixNode.text);
+            if (p === null)
+                continue;
+            constructorPrefix = p;
+        }
         // Providers: FastAPI @router.<verb>("/path") — must be joined
         // with the prefix(es) declared at the include_router site. When
         // no prefix is found we still emit the unprefixed path so this
@@ -1004,9 +1039,12 @@ export const PYTHON_HTTP_PLUGIN = {
             const shortKey = fileRel ? fileShortKey(fileRel) : '';
             const shortPrefixes = longPrefixes || !shortKey ? undefined : ctx?.prefixesByShortKey.get(shortKey);
             const prefixSet = longPrefixes ?? shortPrefixes;
+            // Stack the same-file APIRouter(prefix=...) under any cross-file
+            // include_router prefix.
+            const localPath = constructorPrefix ? joinPrefix(constructorPrefix, rawPath) : rawPath;
             const paths = prefixSet && prefixSet.size > 0
-                ? [...prefixSet].map((p) => joinPrefix(p, rawPath))
-                : [rawPath];
+                ? [...prefixSet].map((p) => joinPrefix(p, localPath))
+                : [localPath];
             for (const p of paths) {
                 out.push({
                     role: 'provider',

package/dist/core/ingestion/parsing-processor.d.ts

@@ -4,7 +4,7 @@ import { type ExportedTypeMap } from './call-processor.js';
 import type { ParsedFile } from '../../_shared/index.js';
 import { WorkerPool } from './workers/worker-pool.js';
 import type { ParseWorkerResult, ExtractedRoute, ExtractedFetchCall, ExtractedDecoratorRoute, ExtractedToolDef, FileScopeBindings, ExtractedORMQuery, FetchWrapperDef } from './workers/parse-worker.js';
-import type { ExtractedRouterImport, ExtractedRouterInclude, ExtractedRouterModuleAlias } from './route-extractors/fastapi-router-bindings.js';
+import type { ExtractedRouterConstructorPrefix, ExtractedRouterImport, ExtractedRouterInclude, ExtractedRouterModuleAlias } from './route-extractors/fastapi-router-bindings.js';
 import type { SharedSpringType } from './route-extractors/spring-shared.js';
 export type FileProgressCallback = (current: number, total: number, filePath: string) => void;
 export interface WorkerExtractedData {
@@ -14,6 +14,7 @@ export interface WorkerExtractedData {
     decoratorRoutes: ExtractedDecoratorRoute[];
     routerIncludes: ExtractedRouterInclude[];
     routerImports: ExtractedRouterImport[];
+    routerConstructorPrefixes: ExtractedRouterConstructorPrefix[];
     routerModuleAliases: ExtractedRouterModuleAlias[];
     toolDefs: ExtractedToolDef[];
     ormQueries: ExtractedORMQuery[];

package/dist/core/ingestion/parsing-processor.js

@@ -22,6 +22,7 @@ export const mergeChunkResults = (graph, symbolTable, chunkResults, exportedType
     const allDecoratorRoutes = [];
     const allRouterIncludes = [];
     const allRouterImports = [];
+    const allRouterConstructorPrefixes = [];
     const allRouterModuleAliases = [];
     const allSpringTypes = [];
     const allToolDefs = [];
@@ -70,6 +71,9 @@ export const mergeChunkResults = (graph, symbolTable, chunkResults, exportedType
             allRouterIncludes.push(item);
         for (const item of result.routerImports ?? [])
             allRouterImports.push(item);
+        for (const item of result.routerConstructorPrefixes ?? []) {
+            allRouterConstructorPrefixes.push(item);
+        }
         for (const item of result.routerModuleAliases ?? [])
             allRouterModuleAliases.push(item);
         for (const item of result.springTypes ?? [])
@@ -93,6 +97,7 @@ export const mergeChunkResults = (graph, symbolTable, chunkResults, exportedType
         decoratorRoutes: allDecoratorRoutes,
         routerIncludes: allRouterIncludes,
         routerImports: allRouterImports,
+        routerConstructorPrefixes: allRouterConstructorPrefixes,
         routerModuleAliases: allRouterModuleAliases,
         toolDefs: allToolDefs,
         ormQueries: allORMQueries,

package/dist/core/ingestion/pipeline-phases/parse-impl.js

@@ -27,6 +27,7 @@ import { isLanguageAvailable, isGrammarRuntimeSkipped, createParserForLanguage,
 import { parseSourceSafe } from '../../tree-sitter/safe-parse.js';
 import { getProvider, providers } from '../languages/index.js';
 import { createWorkerPool, workerPoolDisabledByEnv, resolveAutoPoolSize, WorkerPoolInitializationError, WorkerPoolDisabledError, } from '../workers/worker-pool.js';
+import { normalizeExtractedRoutePath } from '../route-extractors/route-path.js';
 import { resolveInheritedSpringRoutes, } from '../route-extractors/spring-shared.js';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -461,6 +462,7 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
     const allDecoratorRoutes = [];
     const allRouterIncludes = [];
     const allRouterImports = [];
+    const allRouterConstructorPrefixes = [];
     const allRouterModuleAliases = [];
     const allSpringTypes = [];
     const allToolDefs = [];
@@ -599,6 +601,11 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                     for (const item of chunkWorkerData.routerImports)
                         allRouterImports.push(item);
                 }
+                if (chunkWorkerData.routerConstructorPrefixes?.length) {
+                    for (const item of chunkWorkerData.routerConstructorPrefixes) {
+                        allRouterConstructorPrefixes.push(item);
+                    }
+                }
                 if (chunkWorkerData.routerModuleAliases?.length) {
                     for (const item of chunkWorkerData.routerModuleAliases)
                         allRouterModuleAliases.push(item);
@@ -932,7 +939,8 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
     // decorator inherits its file-basename's prefix. When a router is mounted
     // under multiple prefixes we duplicate the route entry, mirroring FastAPI's
     // runtime behaviour.
-    if (allRouterIncludes.length > 0 && allDecoratorRoutes.length > 0) {
+    if ((allRouterIncludes.length > 0 || allRouterConstructorPrefixes.length > 0) &&
+        allDecoratorRoutes.length > 0) {
         const importsByFile = new Map();
         for (const imp of allRouterImports) {
             let m = importsByFile.get(imp.filePath);
@@ -965,6 +973,11 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
         // without a corresponding import statement).
         const prefixesByLongKey = new Map();
         const prefixesByShortKey = new Map();
+        // Constructor prefixes are `router`-only (the apply gate below and the
+        // group-layer tree-sitter both pin to the literal name `router`), so a
+        // flat file-key → prefix map suffices — mirrors the group layer's shape.
+        const constructorPrefixesByLongKey = new Map();
+        const constructorPrefixesByShortKey = new Map();
         const recordPrefix = (target, key, prefix) => {
             let set = target.get(key);
             if (!set) {
@@ -1004,7 +1017,9 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                 recordPrefix(prefixesByShortKey, localImp.moduleKey, inc.prefix);
             }
         }
-        if (prefixesByLongKey.size > 0 || prefixesByShortKey.size > 0) {
+        if (prefixesByLongKey.size > 0 ||
+            prefixesByShortKey.size > 0 ||
+            allRouterConstructorPrefixes.length > 0) {
             const fileLongKey = (rel) => {
                 // Strip `.py`, then take the last two path segments. `api/users.py`
                 // → `api/users`. Files at the repo root return the empty string,
@@ -1025,6 +1040,15 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                 const file = slash >= 0 ? rel.slice(slash + 1) : rel;
                 return file.endsWith('.py') ? file.slice(0, -3) : file;
             };
+            for (const ctor of allRouterConstructorPrefixes) {
+                const longKey = fileLongKey(ctor.filePath);
+                if (longKey) {
+                    constructorPrefixesByLongKey.set(longKey, ctor.prefix);
+                }
+                else {
+                    constructorPrefixesByShortKey.set(fileShortKey(ctor.filePath), ctor.prefix);
+                }
+            }
             const expanded = [];
             for (const dr of allDecoratorRoutes) {
                 if (dr.decoratorReceiver !== 'router' || !dr.filePath.endsWith('.py')) {
@@ -1040,12 +1064,24 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                     ? undefined
                     : prefixesByShortKey.get(fileShortKey(dr.filePath));
                 const prefixes = longPrefixes ?? shortPrefixes;
+                // Constructor prefixes are keyed like include_router prefixes:
+                // long-key entries are precise, while short-key entries are only
+                // valid for repo-root/single-segment files where `fileLongKey`
+                // returns ''. Do not fall back from a missing long-key match to the
+                // short key or a root `users.py` prefix can leak onto
+                // `admin/users.py`.
+                const constructorPrefix = longKey
+                    ? constructorPrefixesByLongKey.get(longKey)
+                    : constructorPrefixesByShortKey.get(fileShortKey(dr.filePath));
+                const routePath = constructorPrefix
+                    ? normalizeExtractedRoutePath(dr.routePath, constructorPrefix)
+                    : dr.routePath;
                 if (!prefixes || prefixes.size === 0) {
-                    expanded.push(dr);
+                    expanded.push(routePath === dr.routePath ? dr : { ...dr, routePath });
                     continue;
                 }
                 for (const prefix of prefixes) {
-                    expanded.push({ ...dr, prefix });
+                    expanded.push({ ...dr, routePath, prefix });
                 }
             }
             allDecoratorRoutes.length = 0;

package/dist/core/ingestion/route-extractors/fastapi-router-bindings.d.ts

@@ -101,6 +101,10 @@ export interface ExtractedRouterModuleAlias {
     /** Long key (`<parent>/<stem>`) — non-empty for every emitted record. */
     moduleKeyLong: string;
 }
+export interface ExtractedRouterConstructorPrefix {
+    filePath: string;
+    prefix: string;
+}
 /**
  * Last `.`-separated segment of a (possibly relative) Python module
  * path. Strips any leading dots first so `from .api.assistant import
@@ -131,4 +135,4 @@ export declare function lastTwoSegmentsAsPath(text: string): string;
  * skips the alias collection — this keeps the function signature
  * back-compat with older callers (and the parse-cache replay path).
  */
-export declare function extractFastAPIRouterBindings(filePath: string, content: string, outIncludes: ExtractedRouterInclude[], outImports: ExtractedRouterImport[], outModuleAliases?: ExtractedRouterModuleAlias[]): void;
+export declare function extractFastAPIRouterBindings(filePath: string, content: string, outIncludes: ExtractedRouterInclude[], outImports: ExtractedRouterImport[], outModuleAliases?: ExtractedRouterModuleAlias[], outConstructorPrefixes?: ExtractedRouterConstructorPrefix[]): void;

package/dist/core/ingestion/route-extractors/fastapi-router-bindings.js

@@ -59,6 +59,8 @@ const INCLUDE_ROUTER_NAME_RE = /\b(?:[A-Za-z_][\w.]*)\.include_router\s*\(\s*([A
 // The latter is the common case and the only one we can map back to
 // a module stem.
 const FROM_IMPORT_ROUTER_RE = /^\s*from\s+(\.+|\.*[A-Za-z_][\w.]*)\s+import\s+([^#\n]+)/gm;
+const API_ROUTER_ASSIGN_RE = /\brouter\s*=\s*APIRouter\s*\(/g;
+const API_ROUTER_PREFIX_ARG_RE = /\bprefix\s*=\s*(['"])([^'"]*)\1/;
 /**
  * Last `.`-separated segment of a (possibly relative) Python module
  * path. Strips any leading dots first so `from .api.assistant import
@@ -94,6 +96,36 @@ export function lastTwoSegmentsAsPath(text) {
     const parent = prev >= 0 ? beforeLast.slice(prev + 1) : beforeLast;
     return `${parent}/${stem}`;
 }
+function findMatchingParen(content, openIndex) {
+    let depth = 0;
+    let quote = null;
+    for (let i = openIndex; i < content.length; i++) {
+        const ch = content[i];
+        if (quote) {
+            if (ch === '\\') {
+                i++;
+                continue;
+            }
+            if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            continue;
+        }
+        if (ch === '(' || ch === '[' || ch === '{') {
+            depth++;
+            continue;
+        }
+        if (ch === ')' || ch === ']' || ch === '}') {
+            depth--;
+            if (depth === 0 && ch === ')')
+                return i;
+        }
+    }
+    return -1;
+}
 /**
  * Scan a single Python file's source text for FastAPI router
  * `include_router` sites and `from <module> import router` imports,
@@ -107,7 +139,7 @@ export function lastTwoSegmentsAsPath(text) {
  * skips the alias collection — this keeps the function signature
  * back-compat with older callers (and the parse-cache replay path).
  */
-export function extractFastAPIRouterBindings(filePath, content, outIncludes, outImports, outModuleAliases) {
+export function extractFastAPIRouterBindings(filePath, content, outIncludes, outImports, outModuleAliases, outConstructorPrefixes) {
     if (!content.includes('include_router') && !content.includes('router'))
         return;
     // `from <module> import router [as <alias>]`. We capture every name
@@ -172,6 +204,25 @@ export function extractFastAPIRouterBindings(filePath, content, outIncludes, out
             }
         }
     }
+    if (outConstructorPrefixes && content.includes('APIRouter') && content.includes('prefix')) {
+        API_ROUTER_ASSIGN_RE.lastIndex = 0;
+        // Only `router = APIRouter(...)` is captured (the apply gate and the
+        // group-layer tree-sitter both pin to the literal name `router`).
+        while (API_ROUTER_ASSIGN_RE.exec(content) !== null) {
+            const openParen = API_ROUTER_ASSIGN_RE.lastIndex - 1;
+            const closeParen = findMatchingParen(content, openParen);
+            if (closeParen < 0)
+                continue;
+            const args = content.slice(openParen + 1, closeParen);
+            const prefixMatch = API_ROUTER_PREFIX_ARG_RE.exec(args);
+            if (!prefixMatch)
+                continue;
+            outConstructorPrefixes.push({
+                filePath,
+                prefix: prefixMatch[2],
+            });
+        }
+    }
     if (!content.includes('include_router'))
         return;
     // Shape A: `<host>.include_router(<module>.router, prefix='/x')`.

package/dist/core/ingestion/workers/parse-worker.d.ts

@@ -1,6 +1,6 @@
 import { SupportedLanguages } from '../../../_shared/index.js';
 import type { SkippedPath } from './clone-safety.js';
-import type { ExtractedRouterInclude, ExtractedRouterImport, ExtractedRouterModuleAlias } from '../route-extractors/fastapi-router-bindings.js';
+import type { ExtractedRouterConstructorPrefix, ExtractedRouterInclude, ExtractedRouterImport, ExtractedRouterModuleAlias } from '../route-extractors/fastapi-router-bindings.js';
 import { type MixedChainStep } from '../utils/call-analysis.js';
 import type { ConstructorBinding } from '../type-env.js';
 import type { NodeLabel, ParameterTypeClass } from '../../../_shared/index.js';
@@ -191,6 +191,7 @@ export interface ParseWorkerResult {
     decoratorRoutes: ExtractedDecoratorRoute[];
     routerIncludes: ExtractedRouterInclude[];
     routerImports: ExtractedRouterImport[];
+    routerConstructorPrefixes?: ExtractedRouterConstructorPrefix[];
     /**
      * Optional. Project-wide `SharedSpringType` view of route-defining
      * class/interface declarations, produced by the provider's

package/dist/core/ingestion/workers/parse-worker.js

@@ -504,6 +504,7 @@ const processBatch = (files, onProgress) => {
         decoratorRoutes: [],
         routerIncludes: [],
         routerImports: [],
+        routerConstructorPrefixes: [],
         routerModuleAliases: [],
         toolDefs: [],
         ormQueries: [],
@@ -1821,7 +1822,7 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
         // injects the resolved prefix onto each ExtractedDecoratorRoute that
         // came from a `@router.<verb>` decorator. Python-only.
         if (language === SupportedLanguages.Python) {
-            extractFastAPIRouterBindings(file.path, parseContent, result.routerIncludes, result.routerImports, (result.routerModuleAliases ??= []));
+            extractFastAPIRouterBindings(file.path, parseContent, result.routerIncludes, result.routerImports, (result.routerModuleAliases ??= []), (result.routerConstructorPrefixes ??= []));
         }
         // Language-specific decorator route extraction via provider hook.
         // The provider's extractDecoratorRoutes walks the AST for framework-specific
@@ -1870,6 +1871,7 @@ let accumulated = {
     decoratorRoutes: [],
     routerIncludes: [],
     routerImports: [],
+    routerConstructorPrefixes: [],
     routerModuleAliases: [],
     toolDefs: [],
     ormQueries: [],
@@ -1989,6 +1991,7 @@ parentPort.on('message', (msg) => {
                 decoratorRoutes: [],
                 routerIncludes: [],
                 routerImports: [],
+                routerConstructorPrefixes: [],
                 routerModuleAliases: [],
                 toolDefs: [],
                 ormQueries: [],

package/dist/core/ingestion/workers/result-merge.js

@@ -24,6 +24,10 @@ export const mergeResult = (target, src) => {
         appendAll(target.routerIncludes, src.routerIncludes);
     if (src.routerImports)
         appendAll(target.routerImports, src.routerImports);
+    if (src.routerConstructorPrefixes) {
+        target.routerConstructorPrefixes ??= [];
+        appendAll(target.routerConstructorPrefixes, src.routerConstructorPrefixes);
+    }
     if (src.routerModuleAliases) {
         target.routerModuleAliases ??= [];
         appendAll(target.routerModuleAliases, src.routerModuleAliases);

package/dist/mcp/local/local-backend.js

@@ -5157,7 +5157,7 @@ export class LocalBackend {
       RETURN n.id AS routeId, n.name AS routeName, n.filePath AS handlerFile,
              n.responseKeys AS responseKeys, n.errorKeys AS errorKeys, n.middleware AS middleware,
              consumer.name AS consumerName, consumer.filePath AS consumerFile,
-             r.reason AS fetchReason
+             r.reason AS fetchReason, n.method AS method
     `, params);
         // Strip wrapping quotes from DB array elements — CSV COPY stores ['key'] which
         // LadybugDB may return as "'key'" rather than "key"
@@ -5173,10 +5173,16 @@ export class LocalBackend {
             const consumerName = row.consumerName ?? row[6];
             const consumerFile = row.consumerFile ?? row[7];
             const fetchReason = row.fetchReason ?? row[8] ?? null;
+            // Verb is the literal '*' for method-agnostic routes (Django function
+            // views) and absent (null) for method-less routes (filesystem, Laravel
+            // resource). Appended last in RETURN so positional fallbacks for the
+            // consumer/reason columns above stay stable.
+            const method = row.method ?? row[9] ?? null;
             if (!routeMap.has(id)) {
                 routeMap.set(id, {
                     id,
                     name,
+                    method,
                     filePath,
                     responseKeys,
                     errorKeys,
@@ -5260,6 +5266,7 @@ export class LocalBackend {
         return {
             routes: routes.map((r) => ({
                 route: r.name,
+                method: r.method,
                 handler: r.filePath,
                 middleware: r.middleware || [],
                 consumers: r.consumers,
@@ -5314,6 +5321,7 @@ export class LocalBackend {
             const hasMismatches = consumers.some((c) => 'mismatched' in c && c.mismatched.length > 0);
             return {
                 route: r.name,
+                method: r.method,
                 handler: r.filePath,
                 ...(responseKeys.length > 0 ? { responseKeys } : {}),
                 ...(errorKeys.length > 0 ? { errorKeys } : {}),
@@ -5381,15 +5389,32 @@ export class LocalBackend {
             routeFilter = `AND n.filePath CONTAINS $file`;
             queryParams.file = params.file;
         }
-        const routes = await this.fetchRoutesWithConsumers(repo.lbugPath, routeFilter, queryParams);
+        // After #2302 the same URL/handler can expose one Route node per HTTP verb.
+        // An optional `method` narrows to that one verb so the response collapses to
+        // the singular shape. A method-agnostic route (method `'*'`, e.g. a Django
+        // function view) matches any selector; verbless routes (null method) never do.
+        // `method` arrives unvalidated from the MCP envelope (the JSON schema is
+        // advisory), so reject a non-string verb with a structured error instead of
+        // throwing on `.toUpperCase()`; empty/whitespace collapses to no selector.
+        const rawMethod = params.method;
+        if (rawMethod !== undefined && typeof rawMethod !== 'string') {
+            return { error: '"method" must be a string (e.g. "GET", "POST").' };
+        }
+        const wantedMethod = typeof rawMethod === 'string' ? rawMethod.trim().toUpperCase() || undefined : undefined;
+        const matched = await this.fetchRoutesWithConsumers(repo.lbugPath, routeFilter, queryParams);
+        const routes = matched.filter((r) => !wantedMethod || r.method === '*' || r.method?.toUpperCase() === wantedMethod);
         if (routes.length === 0) {
             const target = params.route || params.file;
-            return { error: `No routes found matching "${target}".` };
+            // Only append the verb when the URL/file matched routes but none used it;
+            // a non-existent URL/file gets the plain "no routes found" message.
+            const verb = wantedMethod && matched.length > 0 ? ` with method "${wantedMethod}"` : '';
+            return { error: `No routes found matching "${target}"${verb}.` };
         }
         const flowMap = await this.fetchLinkedFlowsBatch(repo.lbugPath, routes.map((r) => r.id));
-        // Count how many routes share the same handler file (for middleware partial detection)
+        // Count verbs per handler from the FULL match (before the method filter) so a
+        // method-scoped query still flags a multi-verb handler's partial middleware.
         const routeCountByHandler = new Map();
-        for (const r of routes) {
+        for (const r of matched) {
             if (r.filePath) {
                 routeCountByHandler.set(r.filePath, (routeCountByHandler.get(r.filePath) ?? 0) + 1);
             }
@@ -5459,6 +5484,7 @@ export class LocalBackend {
             const middlewarePartial = middlewareArr.length > 0 && handlerRouteCount > 1;
             return {
                 route: r.name,
+                method: r.method,
                 handler: r.filePath,
                 responseShape: {
                     success: responseKeys,
@@ -5468,7 +5494,7 @@ export class LocalBackend {
                 ...(middlewarePartial
                     ? {
                         middlewareDetection: 'partial',
-                        middlewareNote: 'Middleware captured from first HTTP method export only — other methods in this handler may use different middleware chains.',
+                        middlewareNote: 'Middleware captured from the first route export only — other route exports in this handler may use different middleware chains.',
                     }
                     : {}),
                 consumers,

package/dist/mcp/tools.d.ts

@@ -24,6 +24,14 @@ export interface ToolDefinition {
             minLength?: number;
         }>;
         required: string[];
+        /**
+         * JSON-Schema `anyOf` for cross-property constraints `required` cannot express
+         * — e.g. "at least one of route/file". Forwarded verbatim to clients by the
+         * server's ListTools handler, so MCP clients see the constraint.
+         */
+        anyOf?: Array<{
+            required: string[];
+        }>;
     };
 }
 /**

package/dist/mcp/tools.js

@@ -615,7 +615,7 @@ CONTRACT CAVEATS:
 WHEN TO USE: Understanding API consumption patterns, finding orphaned routes. For pre-change analysis, prefer \`api_impact\` which combines this data with mismatch detection and risk assessment.
 AFTER THIS: Use impact() on specific route handlers to see full blast radius.
 
-Returns: route nodes with their handlers, middleware wrapper chains (e.g., withAuth, withRateLimit), and consumers.`,
+Returns: route nodes with their handlers, middleware wrapper chains (e.g., withAuth, withRateLimit), and consumers. Each route object includes its "method" (the HTTP verb, "*" for method-agnostic routes, or null for method-less routes).`,
         annotations: READ_ONLY_TOOL_ANNOTATIONS,
         inputSchema: {
             type: 'object',
@@ -656,7 +656,7 @@ Returns: tool nodes with their handler files and descriptions.`,
 WHEN TO USE: Detecting mismatches between what an API route returns and what consumers expect. Finding shape drift. For pre-change analysis, prefer \`api_impact\` which combines this data with mismatch detection and risk assessment.
 REQUIRES: Route nodes with responseKeys (extracted from .json({...}) calls during indexing).
 
-Returns routes that have both detected response keys AND consumers. Shows top-level keys each endpoint returns (e.g., data, pagination, error) and what keys each consumer accesses. Reports MISMATCH status when a consumer accesses keys not present in the route's response shape.`,
+Returns routes that have both detected response keys AND consumers. Shows top-level keys each endpoint returns (e.g., data, pagination, error) and what keys each consumer accesses. Reports MISMATCH status when a consumer accesses keys not present in the route's response shape. Each route object includes its "method" (the HTTP verb, "*" for method-agnostic routes, or null for method-less routes).`,
         annotations: READ_ONLY_TOOL_ANNOTATIONS,
         inputSchema: {
             type: 'object',
@@ -681,16 +681,23 @@ WHEN TO USE: BEFORE modifying any API route handler. Shows what consumers depend
 
 Risk levels: LOW (0-3 consumers), MEDIUM (4-9 or any mismatches), HIGH (10+ consumers or mismatches with 4+ consumers). Mismatches with confidence "low" indicate the consumer file fetches multiple routes — property attribution is approximate.
 
-Returns: single route object when one match, or { routes: [...], total: N } for multiple matches. Combines route_map, shape_check, and impact data.`,
+Response shape is keyed on how many routes match, not on the data: exactly one match returns a single route object; two or more return { routes: [...], total: N }. The same URL can expose multiple HTTP verbs (e.g. GET and POST /api/orders are distinct routes that share the URL), so a bare-URL lookup may return the wrapped form — every route object carries its own "method" so verbs are distinguishable. Pass "method" to narrow to one verb; the single-object shape is returned only when exactly one route remains after filtering — a substring route/file match spanning several URLs can still return the wrapped form. A URL/file that exists but has no route for the given verb returns an error. Each route's "method" is the literal "*" for method-agnostic routes (e.g. Django function views), which match any "method" selector, or null for method-less routes (filesystem, Laravel resource), which never match a selector. Combines route_map, shape_check, and impact data.`,
         annotations: READ_ONLY_TOOL_ANNOTATIONS,
         inputSchema: {
             type: 'object',
             properties: {
                 route: { type: 'string', description: 'Route path (e.g., "/api/grants")' },
                 file: { type: 'string', description: 'Handler file path (alternative to route)' },
+                method: {
+                    type: 'string',
+                    description: 'Optional HTTP verb — GET, POST, PUT, PATCH, DELETE, etc. — to narrow a multi-verb route or file lookup to a single method. Returns an error if no matched route uses that verb.',
+                },
                 repo: { type: 'string', description: 'Repository name or path.' },
             },
             required: [],
+            // Exactly one lookup key is needed, but either works (route wins if both
+            // are passed) — so the structural constraint is "at least one of route/file".
+            anyOf: [{ required: ['route'] }, { required: ['file'] }],
         },
     },
     {

package/dist/storage/parse-cache.js

@@ -52,7 +52,7 @@ import { fileURLToPath } from 'url';
 // the main thread (the #1983 OOM). Because the two stores share this version,
 // any future change to the `ParsedFile` serialization shape MUST bump
 // SCHEMA_BUMP so both invalidate in lockstep.
-const SCHEMA_BUMP = 8; // #2288: ParseWorkerResult gained `springTypes` (Spring interface-inheritance) + `decoratorRoutes` semantics changed (interface routes suppressed at extraction, inherited routes appended in parse-impl)
+const SCHEMA_BUMP = 9; // #2312: ParseWorkerResult gained `routerConstructorPrefixes` for FastAPI APIRouter(prefix=...) replay
 const GITNEXUS_PKG_VERSION = (() => {
     try {
         // package.json sits at gitnexus/package.json — two levels up from

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.9-rc.24",
+  "version": "1.6.9-rc.26",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",