gitnexus 1.6.9-rc.21 → 1.6.9-rc.23

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

@@ -576,16 +576,16 @@ export const JAVA_HTTP_PLUGIN = {
     language: Java,
     // routeCoverage intentionally LEFT at the default 'partial' (#2138 Part 2).
     // The graph provider set is a strict *subset* of this scan()'s provider set —
-    // ingestion does NOT emit a Route node for (1) a method-level array route
-    // nested under a class-level array-form `@RequestMapping` (ingestion suppresses
-    // it rather than drop the prefix; bare/scalar-prefixed array methods ARE now
-    // emitted — see #2280), or (2) the 2nd verb of a same-URL GET+POST pair (Route
-    // nodes are URL-keyed). Interface-inherited Spring routes ARE now emitted by
-    // ingestion (#2288), so they are no longer a coverage gap. Declaring 'complete'
-    // here would let the parse-skip drop those remaining group-only providers.
-    // Java flips to 'complete' only once ingestion provider extraction matches this
-    // scan (a follow-up: class-level array-form prefix support + per-verb Route
-    // identity — tracked in #2280).
+    // ingestion does NOT emit a Route node for a method-level array route nested
+    // under a class-level array-form `@RequestMapping` (ingestion suppresses it
+    // rather than drop the prefix; bare/scalar-prefixed array methods ARE now
+    // emitted — see #2280). Interface-inherited Spring routes ARE now emitted by
+    // ingestion (#2288), and same-URL multi-verb routes are now per-`(method,url)`
+    // Route nodes (#2289), so they are no longer coverage gaps. Declaring
+    // 'complete' here would let the parse-skip drop the remaining group-only
+    // providers (the array-prefix gap above). Java flips to 'complete' only once
+    // ingestion provider extraction matches this scan — class-level array-form
+    // prefix support is the final follow-up tracked in #2280.
     // `hasConsumerSignals` below is kept ready for that flip.
     // Consumer signals this plugin's scan() can detect: RestTemplate / WebClient /
     // OkHttp / Java-HttpClient / Apache-HttpClient call sites, OpenFeign

package/dist/core/group/extractors/manifest-extractor.js

@@ -151,10 +151,12 @@ export class ManifestExtractor {
         try {
             let rows;
             if (link.type === 'http') {
-                // Route.name is the canonicalized URL path (see
-                // core/ingestion/pipeline.ts ensureSlash + generateId('Route', ...)).
-                // Normalize the manifest contract the same way so a user-written
-                // "/api/orders" matches "api/orders" in the graph.
+                // Route.name is the canonicalized URL path. Since #2289 a Route node's
+                // *id* is `(method, url)`-composite (`routeNodeKey`), but `route.name`
+                // continues to carry the bare URL so URL-keyed group queries like this
+                // one keep working without a schema change. Normalize the manifest
+                // contract the same way so a user-written "/api/orders" matches
+                // "api/orders" in the graph.
                 //
                 // The contract may also use the explicit-method form "GET::/api/orders"
                 // recommended by buildContractId. Strip the METHOD:: prefix before

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

@@ -59,11 +59,11 @@ export declare function buildExportedTypeMapFromGraph(graph: KnowledgeGraph, sym
  */
 export declare const processRoutesFromExtracted: (graph: KnowledgeGraph, extractedRoutes: ExtractedRoute[], model: SemanticModel, onProgress?: (current: number, total: number) => void) => Promise<void>;
 /**
- * Resolve each route's handler to a real symbol UID, keyed by the normalized
- * route URL (the same key the routes phase uses for the `Route` node). This is
- * the Part 2 (#2138) groundwork that lets `HttpRouteExtractor.extractProvidersGraph`
- * read the handler symbol from the graph instead of re-parsing source via
- * `getDetections()`.
+ * Resolve each route's handler to a real symbol UID, keyed by the route's
+ * `(method, url)` identity (`routeNodeKey` — the same key the routes phase uses
+ * for the `Route` node). This is the Part 2 (#2138) groundwork that lets
+ * `HttpRouteExtractor.extractProvidersGraph` read the handler symbol from the
+ * graph instead of re-parsing source via `getDetections()`.
  *
  * Two route shapes, one resolution target — `(filePath, name) → nodeId`:
  *   - Laravel framework routes (`ExtractedRoute`) carry `controllerName` +
@@ -73,14 +73,18 @@ export declare const processRoutesFromExtracted: (graph: KnowledgeGraph, extract
  *     `handlerName` (the decorated method, captured at extraction); resolve it
  *     directly in the route's own file.
  *
- * First-writer-wins per URL, matching the routes phase's dedup (it keeps the
- * first route registered for a URL and counts the rest as duplicates). The first
- * route to claim a URL reserves it **even when its handler is unresolvable**, so
- * a later same-URL route can never stamp its handler onto the first route's Route
- * node (the routes phase made that first route the node-winner). Routes whose
- * handler cannot be *uniquely* resolved (no name, zero matches, or an ambiguous
- * same-name match) carry no `handlerSymbolId`; the extractor then falls back to
- * source scan for that route (fail-open, no regression, never a wrong handler).
+ * First-writer-wins per route identity, matching the routes phase's dedup (it
+ * keeps the first route registered for a `(method, url)` key and counts the rest
+ * as duplicates). The first route to claim a key reserves it **even when its
+ * handler is unresolvable**, so a later same-key route can never stamp its
+ * handler onto the first route's Route node (the routes phase made that first
+ * route the node-winner). Keying is `routeNodeKey(method, url)` (#2289): a
+ * same-URL multi-verb pair (`GET /x` + `POST /x`) resolves two handlers, one per
+ * node; method-less / wildcard routes key by URL alone, byte-identical to the
+ * pre-#2289 behavior. Routes whose handler cannot be *uniquely* resolved (no
+ * name, zero matches, or an ambiguous same-name match) carry no
+ * `handlerSymbolId`; the extractor then falls back to source scan for that route
+ * (fail-open, no regression, never a wrong handler).
  */
 export declare function resolveRouteHandlerSymbols(model: SemanticModel, extractedRoutes: readonly ExtractedRoute[], decoratorRoutes: readonly ExtractedDecoratorRoute[]): Map<string, string>;
 /**
@@ -97,6 +101,14 @@ export declare const extractConsumerAccessedKeys: (content: string) => string[];
  * Create FETCHES edges from extracted fetch() calls to matching Route nodes.
  * When consumerContents is provided, extracts property access patterns from
  * consumer files and encodes them in the edge reason field.
+ *
+ * Matching stays URL-only (#2289): a verb-less consumer (a `fetch()` call has
+ * no statically-known HTTP method) matches a route by URL and connects to
+ * **every** Route node sharing that URL — i.e. both the `GET /x` and `POST /x`
+ * nodes when a URL carries multiple verbs. `routeUrlToKeys` therefore maps each
+ * route URL to the list of `routeNodeKey` identities at that URL; a single-verb
+ * (or method-less) URL has a one-element list, keeping edges byte-identical to
+ * the pre-#2289 behavior.
  */
-export declare const processNextjsFetchRoutes: (graph: KnowledgeGraph, fetchCalls: ExtractedFetchCall[], routeRegistry: Map<string, string>, // routeURL → handlerFilePath
+export declare const processNextjsFetchRoutes: (graph: KnowledgeGraph, fetchCalls: ExtractedFetchCall[], routeUrlToKeys: Map<string, string[]>, // routeURL → route node keys at that URL
 consumerContents?: Map<string, string>) => void;

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

@@ -17,7 +17,7 @@
 import { generateId } from '../../lib/utils.js';
 import { yieldToEventLoop } from './utils/event-loop.js';
 import { normalizeFetchURL, routeMatches } from './route-extractors/nextjs.js';
-import { normalizeExtractedRoutePath } from './route-extractors/route-path.js';
+import { normalizeExtractedRoutePath, normalizeRouteMethod, routeNodeKey, } from './route-extractors/route-path.js';
 import { extractReturnTypeName } from './type-extractors/shared.js';
 const MAX_EXPORTS_PER_FILE = 500;
 const MAX_TYPE_NAME_LENGTH = 256;
@@ -215,11 +215,11 @@ export const processRoutesFromExtracted = async (graph, extractedRoutes, model,
     onProgress?.(extractedRoutes.length, extractedRoutes.length);
 };
 /**
- * Resolve each route's handler to a real symbol UID, keyed by the normalized
- * route URL (the same key the routes phase uses for the `Route` node). This is
- * the Part 2 (#2138) groundwork that lets `HttpRouteExtractor.extractProvidersGraph`
- * read the handler symbol from the graph instead of re-parsing source via
- * `getDetections()`.
+ * Resolve each route's handler to a real symbol UID, keyed by the route's
+ * `(method, url)` identity (`routeNodeKey` — the same key the routes phase uses
+ * for the `Route` node). This is the Part 2 (#2138) groundwork that lets
+ * `HttpRouteExtractor.extractProvidersGraph` read the handler symbol from the
+ * graph instead of re-parsing source via `getDetections()`.
  *
  * Two route shapes, one resolution target — `(filePath, name) → nodeId`:
  *   - Laravel framework routes (`ExtractedRoute`) carry `controllerName` +
@@ -229,20 +229,24 @@ export const processRoutesFromExtracted = async (graph, extractedRoutes, model,
  *     `handlerName` (the decorated method, captured at extraction); resolve it
  *     directly in the route's own file.
  *
- * First-writer-wins per URL, matching the routes phase's dedup (it keeps the
- * first route registered for a URL and counts the rest as duplicates). The first
- * route to claim a URL reserves it **even when its handler is unresolvable**, so
- * a later same-URL route can never stamp its handler onto the first route's Route
- * node (the routes phase made that first route the node-winner). Routes whose
- * handler cannot be *uniquely* resolved (no name, zero matches, or an ambiguous
- * same-name match) carry no `handlerSymbolId`; the extractor then falls back to
- * source scan for that route (fail-open, no regression, never a wrong handler).
+ * First-writer-wins per route identity, matching the routes phase's dedup (it
+ * keeps the first route registered for a `(method, url)` key and counts the rest
+ * as duplicates). The first route to claim a key reserves it **even when its
+ * handler is unresolvable**, so a later same-key route can never stamp its
+ * handler onto the first route's Route node (the routes phase made that first
+ * route the node-winner). Keying is `routeNodeKey(method, url)` (#2289): a
+ * same-URL multi-verb pair (`GET /x` + `POST /x`) resolves two handlers, one per
+ * node; method-less / wildcard routes key by URL alone, byte-identical to the
+ * pre-#2289 behavior. Routes whose handler cannot be *uniquely* resolved (no
+ * name, zero matches, or an ambiguous same-name match) carry no
+ * `handlerSymbolId`; the extractor then falls back to source scan for that route
+ * (fail-open, no regression, never a wrong handler).
  */
 export function resolveRouteHandlerSymbols(model, extractedRoutes, decoratorRoutes) {
     const out = new Map();
-    // URLs already claimed by an earlier route (resolved or not). Mirrors the
-    // routes phase `addRoute` first-writer-wins so the handler we stamp always
-    // belongs to the route that actually won the Route node.
+    // Route identities already claimed by an earlier route (resolved or not).
+    // Mirrors the routes phase `addRoute` first-writer-wins so the handler we
+    // stamp always belongs to the route that actually won the Route node.
     const claimed = new Set();
     // Resolve a single same-file symbol by name, refusing to guess on ambiguity:
     // exactly one match → its nodeId; zero or many → undefined (fail-open).
@@ -250,15 +254,16 @@ export function resolveRouteHandlerSymbols(model, extractedRoutes, decoratorRout
         const defs = model.symbols.lookupExactAll(filePath, name);
         return defs.length === 1 ? defs[0]?.nodeId : undefined;
     };
-    const claim = (routePath, prefix, symbolId) => {
+    const claim = (routePath, prefix, httpMethod, symbolId) => {
         if (!routePath)
             return;
         const url = normalizeExtractedRoutePath(routePath, prefix);
-        if (claimed.has(url))
-            return; // first-writer-wins: later same-URL routes can't override
-        claimed.add(url);
+        const key = routeNodeKey(normalizeRouteMethod(httpMethod), url);
+        if (claimed.has(key))
+            return; // first-writer-wins: later same-key routes can't override
+        claimed.add(key);
         if (symbolId)
-            out.set(url, symbolId);
+            out.set(key, symbolId);
     };
     // Laravel framework routes — controller class + method name.
     for (const route of extractedRoutes) {
@@ -276,13 +281,13 @@ export function resolveRouteHandlerSymbols(model, extractedRoutes, decoratorRout
             if (controllerDef)
                 methodId = uniqueSymbolId(controllerDef.filePath, route.methodName);
         }
-        claim(route.routePath, route.prefix ?? null, methodId);
+        claim(route.routePath, route.prefix ?? null, route.httpMethod, methodId);
     }
     // Decorator routes (Spring / FastAPI / generic) — the decorated handler in
     // the route's own file.
     for (const dr of decoratorRoutes) {
         const handlerId = dr.handlerName ? uniqueSymbolId(dr.filePath, dr.handlerName) : undefined;
-        claim(dr.routePath, dr.prefix ?? null, handlerId);
+        claim(dr.routePath, dr.prefix ?? null, dr.httpMethod, handlerId);
     }
     return out;
 }
@@ -421,16 +426,26 @@ export const extractConsumerAccessedKeys = (content) => {
  * Create FETCHES edges from extracted fetch() calls to matching Route nodes.
  * When consumerContents is provided, extracts property access patterns from
  * consumer files and encodes them in the edge reason field.
+ *
+ * Matching stays URL-only (#2289): a verb-less consumer (a `fetch()` call has
+ * no statically-known HTTP method) matches a route by URL and connects to
+ * **every** Route node sharing that URL — i.e. both the `GET /x` and `POST /x`
+ * nodes when a URL carries multiple verbs. `routeUrlToKeys` therefore maps each
+ * route URL to the list of `routeNodeKey` identities at that URL; a single-verb
+ * (or method-less) URL has a one-element list, keeping edges byte-identical to
+ * the pre-#2289 behavior.
  */
-export const processNextjsFetchRoutes = (graph, fetchCalls, routeRegistry, // routeURL → handlerFilePath
+export const processNextjsFetchRoutes = (graph, fetchCalls, routeUrlToKeys, // routeURL → route node keys at that URL
 consumerContents) => {
-    // Pre-count how many routes each consumer file matches (for confidence attribution)
+    // Pre-count how many route URLs each consumer file matches (for confidence
+    // attribution). Counts once per call that matches any URL — independent of how
+    // many verbs share that URL — so the multi-fetch heuristic is unchanged.
     const routeCountByFile = new Map();
     for (const call of fetchCalls) {
         const normalized = normalizeFetchURL(call.fetchURL);
         if (!normalized)
             continue;
-        for (const [routeURL] of routeRegistry) {
+        for (const routeURL of routeUrlToKeys.keys()) {
             if (routeMatches(normalized, routeURL)) {
                 routeCountByFile.set(call.filePath, (routeCountByFile.get(call.filePath) ?? 0) + 1);
                 break;
@@ -441,10 +456,9 @@ consumerContents) => {
         const normalized = normalizeFetchURL(call.fetchURL);
         if (!normalized)
             continue;
-        for (const [routeURL] of routeRegistry) {
+        for (const [routeURL, routeKeys] of routeUrlToKeys) {
             if (routeMatches(normalized, routeURL)) {
                 const sourceId = generateId('File', call.filePath);
-                const routeNodeId = generateId('Route', routeURL);
                 // Extract consumer accessed keys if file content is available
                 let reason = 'fetch-url-match';
                 if (consumerContents) {
@@ -461,14 +475,18 @@ consumerContents) => {
                 if (fetchCount > 1) {
                     reason = `${reason}|fetches:${fetchCount}`;
                 }
-                graph.addRelationship({
-                    id: generateId('FETCHES', `${sourceId}->${routeNodeId}`),
-                    sourceId,
-                    targetId: routeNodeId,
-                    type: 'FETCHES',
-                    confidence: 0.9,
-                    reason,
-                });
+                // Connect to every Route node at this URL (one per verb).
+                for (const routeKey of routeKeys) {
+                    const routeNodeId = generateId('Route', routeKey);
+                    graph.addRelationship({
+                        id: generateId('FETCHES', `${sourceId}->${routeNodeId}`),
+                        sourceId,
+                        targetId: routeNodeId,
+                        type: 'FETCHES',
+                        confidence: 0.9,
+                        reason,
+                    });
+                }
                 break;
             }
         }

package/dist/core/ingestion/pipeline-phases/processes.js

@@ -11,6 +11,7 @@
 import { getPhaseOutput } from './types.js';
 import { processProcesses } from '../process-processor.js';
 import { generateId } from '../../../lib/utils.js';
+import { routeNodeKey } from '../route-extractors/route-path.js';
 import { isDev } from '../utils/env.js';
 import { logger } from '../../logger.js';
 export const processesPhase = {
@@ -78,14 +79,39 @@ export const processesPhase = {
         });
         // Link Route and Tool nodes to Processes
         if (routeRegistry.size > 0 || toolDefs.length > 0) {
-            const routesByFile = new Map();
-            for (const [url, entry] of routeRegistry) {
-                let list = routesByFile.get(entry.filePath);
+            // Two-tier route lookup, mirroring the tool tables 10 lines below.
+            // Routes whose handler resolved key by `handlerSymbolId` (read from
+            // the Route node's graph properties — routes.ts stamps it there) and
+            // link ONLY to the process whose entryPoint matches; routes without a
+            // resolved handler fall back to a per-file bucket so we still attach
+            // the Route node to a same-file process (best-effort).
+            //
+            // Pre-#2289-review-P2 this was a single per-file bucket: every verb
+            // on a file's controller was linked to every process in that file,
+            // cross-wiring same-file `GET /items` and `POST /items` to each
+            // other's handler processes. The per-verb `handlerSymbolId` the
+            // routes phase stamps on the Route node was never consulted.
+            const routesByHandlerId = new Map();
+            const routesWithoutHandlerByFile = new Map();
+            for (const [, entry] of routeRegistry) {
+                // Push the Route node identity (`routeNodeKey`), not the bare URL, so the
+                // ENTRY_POINT_OF edge targets the same node id the routes phase created
+                // (#2289: a same-URL GET/POST pair is two distinct Route nodes).
+                const routeKey = routeNodeKey(entry.method, entry.url);
+                // Source of truth for handlerSymbolId is the Route node in the
+                // graph (routes.ts populates it from `routeHandlerSymbols`); the
+                // routes phase runs before processes (see `deps`), so the node is
+                // always present here.
+                const routeNode = ctx.graph.getNode(generateId('Route', routeKey));
+                const handlerSymbolId = routeNode?.properties.handlerSymbolId;
+                const targetMap = handlerSymbolId ? routesByHandlerId : routesWithoutHandlerByFile;
+                const bucketKey = handlerSymbolId ?? entry.filePath;
+                let list = targetMap.get(bucketKey);
                 if (!list) {
                     list = [];
-                    routesByFile.set(entry.filePath, list);
+                    targetMap.set(bucketKey, list);
                 }
-                list.push(url);
+                list.push(routeKey);
             }
             const toolsByHandlerId = new Map();
             const toolsWithoutHandlerByFile = new Map();
@@ -109,10 +135,12 @@ export const processesPhase = {
                 const entryFile = entryNode.properties.filePath;
                 if (!entryFile)
                     continue;
-                const routeURLs = routesByFile.get(entryFile);
-                if (routeURLs) {
-                    for (const routeURL of routeURLs) {
-                        const routeNodeId = generateId('Route', routeURL);
+                const exactRouteKeys = routesByHandlerId.get(proc.entryPointId);
+                const fallbackRouteKeys = routesWithoutHandlerByFile.get(entryFile);
+                const routeKeys = exactRouteKeys ?? fallbackRouteKeys;
+                if (routeKeys) {
+                    for (const routeKey of routeKeys) {
+                        const routeNodeId = generateId('Route', routeKey);
                         ctx.graph.addRelationship({
                             id: generateId('ENTRY_POINT_OF', `${routeNodeId}->${proc.id}`),
                             sourceId: routeNodeId,

package/dist/core/ingestion/pipeline-phases/routes.d.ts

@@ -11,10 +11,16 @@
  * @output  routeRegistry, handlerContents
  */
 import type { PipelinePhase } from './types.js';
-import { normalizeExtractedRoutePath } from '../route-extractors/route-path.js';
 export interface RouteEntry {
     filePath: string;
     source: string;
+    /**
+     * The route's URL path (leading-slash, prefix-joined). This is the Route
+     * node's `name`. Stored explicitly because the registry is keyed by the
+     * `(method, url)` identity (`routeNodeKey`), so the key is no longer the URL
+     * — downstream URL consumers (middleware/fetch matching) read this instead.
+     */
+    url: string;
     /**
      * HTTP verb for this route when ingestion knows it structurally
      * (Spring/Laravel framework routes and decorator routes carry
@@ -35,6 +41,4 @@ export interface TemplateFetchCall {
 }
 export declare const isTemplateRouteCandidate: (filePath: string) => boolean;
 export declare function extractTemplateStaticFetchCalls(filePath: string, content: string, namedRouteUrls?: ReadonlyMap<string, string>): TemplateFetchCall[];
-export { normalizeExtractedRoutePath };
-export declare function normalizeRouteMethod(raw: string | null | undefined): string | undefined;
 export declare const routesPhase: PipelinePhase<RoutesOutput>;

package/dist/core/ingestion/pipeline-phases/routes.js

@@ -18,7 +18,7 @@ import { phpFileToRouteURL } from '../route-extractors/php.js';
 import { extractResponseShapes, extractPHPResponseShapes, } from '../route-extractors/response-shapes.js';
 import { extractMiddlewareChain, extractNextjsMiddlewareConfig, compileMatcher, compiledMatcherMatchesRoute, } from '../route-extractors/middleware.js';
 import { processNextjsFetchRoutes } from '../call-processor.js';
-import { normalizeExtractedRoutePath } from '../route-extractors/route-path.js';
+import { normalizeExtractedRoutePath, normalizeRouteMethod, routeNodeKey, } from '../route-extractors/route-path.js';
 import { generateId } from '../../../lib/utils.js';
 import { readFileContents } from '../filesystem-walker.js';
 import { isDev } from '../utils/env.js';
@@ -92,39 +92,6 @@ export function extractTemplateStaticFetchCalls(filePath, content, namedRouteUrl
 function escapeRegex(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
-// Re-exported for existing consumers/tests that import it from the routes phase.
-export { normalizeExtractedRoutePath };
-/**
- * Canonicalize a route's HTTP verb for persistence on the Route node.
- * Returns an upper-cased standard method, or `undefined` when the value
- * is not a real HTTP verb. Laravel `Route::resource` / `apiResource`
- * surface `httpMethod` values like `resource` / `apiResource` (they
- * expand to several verbs at runtime), so they must not be stored as a
- * method — leaving them `undefined` keeps the column clean and lets the
- * contract extractor fall back to its source-scan path for those routes.
- */
-const VALID_HTTP_METHODS = new Set([
-    'GET',
-    'POST',
-    'PUT',
-    'PATCH',
-    'DELETE',
-    'HEAD',
-    'OPTIONS',
-    'TRACE',
-    'CONNECT',
-]);
-export function normalizeRouteMethod(raw) {
-    if (typeof raw !== 'string')
-        return undefined;
-    const verb = raw.trim().toUpperCase();
-    // '*' marks a method-agnostic route (e.g. a Django function view handles any
-    // verb). Preserve it so the contract layer emits a wildcard provider that
-    // matches consumers of any method, instead of silently narrowing to GET.
-    if (verb === '*')
-        return '*';
-    return VALID_HTTP_METHODS.has(verb) ? verb : undefined;
-}
 export const routesPhase = {
     name: 'routes',
     deps: ['parse'],
@@ -162,30 +129,44 @@ export const routesPhase = {
             if (expoAppPaths.has(p)) {
                 const expoURL = expoFileToRouteURL(p);
                 if (expoURL && !routeRegistry.has(expoURL)) {
-                    routeRegistry.set(expoURL, { filePath: p, source: 'expo-filesystem-route' });
+                    routeRegistry.set(expoURL, {
+                        filePath: p,
+                        source: 'expo-filesystem-route',
+                        url: expoURL,
+                    });
                     continue;
                 }
             }
             const nextjsURL = nextjsFileToRouteURL(p);
             if (nextjsURL && !routeRegistry.has(nextjsURL)) {
-                routeRegistry.set(nextjsURL, { filePath: p, source: 'nextjs-filesystem-route' });
+                routeRegistry.set(nextjsURL, {
+                    filePath: p,
+                    source: 'nextjs-filesystem-route',
+                    url: nextjsURL,
+                });
                 continue;
             }
             if (p.endsWith('.php')) {
                 const phpURL = phpFileToRouteURL(p);
                 if (phpURL && !routeRegistry.has(phpURL)) {
-                    routeRegistry.set(phpURL, { filePath: p, source: 'php-file-route' });
+                    routeRegistry.set(phpURL, { filePath: p, source: 'php-file-route', url: phpURL });
                 }
             }
         }
         let duplicateRoutes = 0;
         const namedRouteRegistry = new Map();
+        // Routes are keyed by their `(method, url)` identity (#2289): a same-URL
+        // multi-verb pair (`GET /x` + `POST /x`) is two entries, not one. Method-less
+        // / wildcard routes key by URL (see `routeNodeKey`), so filesystem/resource
+        // routes stay byte-identical. A true duplicate (same method AND url) is still
+        // dropped.
         const addRoute = (url, entry) => {
-            if (routeRegistry.has(url)) {
+            const key = routeNodeKey(entry.method, url);
+            if (routeRegistry.has(key)) {
                 duplicateRoutes++;
                 return;
             }
-            routeRegistry.set(url, entry);
+            routeRegistry.set(key, { ...entry, url });
         };
         for (const route of allExtractedRoutes) {
             if (!route.routePath)
@@ -212,8 +193,8 @@ export const routesPhase = {
         if (routeRegistry.size > 0) {
             const handlerPaths = [...routeRegistry.values()].map((e) => e.filePath);
             handlerContents = await readFileContents(ctx.repoPath, handlerPaths);
-            for (const [routeURL, entry] of routeRegistry) {
-                const { filePath: handlerPath, source: routeSource, method: routeMethod } = entry;
+            for (const [routeKey, entry] of routeRegistry) {
+                const { filePath: handlerPath, source: routeSource, method: routeMethod, url } = entry;
                 const content = handlerContents.get(handlerPath);
                 const { responseKeys, errorKeys } = content
                     ? handlerPath.endsWith('.php')
@@ -222,13 +203,13 @@ export const routesPhase = {
                     : { responseKeys: undefined, errorKeys: undefined };
                 const mwResult = content ? extractMiddlewareChain(content) : undefined;
                 const middleware = mwResult?.chain;
-                const routeNodeId = generateId('Route', routeURL);
-                const handlerSymbolId = routeHandlerSymbols.get(routeURL);
+                const routeNodeId = generateId('Route', routeKey);
+                const handlerSymbolId = routeHandlerSymbols.get(routeKey);
                 ctx.graph.addNode({
                     id: routeNodeId,
                     label: 'Route',
                     properties: {
-                        name: routeURL,
+                        name: url,
                         filePath: handlerPath,
                         ...(routeMethod ? { method: routeMethod } : {}),
                         ...(handlerSymbolId ? { handlerSymbolId } : {}),
@@ -272,12 +253,12 @@ export const routesPhase = {
                         .map(compileMatcher)
                         .filter((m) => m !== null);
                     let linkedCount = 0;
-                    for (const [routeURL] of routeRegistry) {
+                    for (const [routeKey, entry] of routeRegistry) {
                         const matches = compiled.length === 0 ||
-                            compiled.some((cm) => compiledMatcherMatchesRoute(cm, routeURL));
+                            compiled.some((cm) => compiledMatcherMatchesRoute(cm, entry.url));
                         if (!matches)
                             continue;
-                        const routeNodeId = generateId('Route', routeURL);
+                        const routeNodeId = generateId('Route', routeKey);
                         const existing = ctx.graph.getNode(routeNodeId);
                         if (!existing)
                             continue;
@@ -401,12 +382,19 @@ export const routesPhase = {
             }
         }
         if (routeRegistry.size > 0 && allFetchCalls.length > 0) {
-            const routeURLToFile = new Map();
-            for (const [url, entry] of routeRegistry)
-                routeURLToFile.set(url, entry.filePath);
+            // url → [route node keys at that url] (one per verb). A verb-less fetch()
+            // consumer matches by URL and connects to every Route node at that URL.
+            const routeUrlToKeys = new Map();
+            for (const [routeKey, entry] of routeRegistry) {
+                const existing = routeUrlToKeys.get(entry.url);
+                if (existing)
+                    existing.push(routeKey);
+                else
+                    routeUrlToKeys.set(entry.url, [routeKey]);
+            }
             const consumerPaths = [...new Set(allFetchCalls.map((c) => c.filePath))];
             const consumerContents = await readFileContents(ctx.repoPath, consumerPaths);
-            processNextjsFetchRoutes(ctx.graph, allFetchCalls, routeURLToFile, consumerContents);
+            processNextjsFetchRoutes(ctx.graph, allFetchCalls, routeUrlToKeys, consumerContents);
             if (isDev) {
                 logger.info(`🔗 Processed ${allFetchCalls.length} fetch() calls against ${routeRegistry.size} routes`);
             }

package/dist/core/ingestion/route-extractors/route-path.d.ts

@@ -2,10 +2,11 @@
  * Shared route-path normalization.
  *
  * Extracted from the routes phase so both the routes phase (which creates the
- * `Route` graph node, keyed by the normalized URL) and the parse phase (which
- * resolves each route's handler symbol and needs the SAME key to associate the
- * resolved id back to the route) can compute an identical route URL without a
- * phase-to-phase import cycle. Pure string logic, no dependencies.
+ * `Route` graph node, keyed by `(method, url)` via `routeNodeKey` — #2289) and
+ * the parse phase (which resolves each route's handler symbol and needs the
+ * SAME key to associate the resolved id back to the route) can compute an
+ * identical route identity without a phase-to-phase import cycle. Pure string
+ * logic, no dependencies.
  */
 /**
  * Join a route's path with its (optional) prefix into a normalized,
@@ -13,3 +14,26 @@
  * slashes and strips trailing ones; an empty result degrades to `/`.
  */
 export declare function normalizeExtractedRoutePath(routePath: string, prefix: string | null): string;
+/**
+ * Canonicalize a route's HTTP verb for persistence on the Route node and for
+ * the route identity key. Returns an upper-cased standard method, `'*'` for a
+ * method-agnostic route (e.g. a Django function view), or `undefined` when the
+ * value is not a real HTTP verb. Laravel `Route::resource` / `apiResource`
+ * surface values like `resource` / `apiResource` (they expand to several verbs
+ * at runtime), so they come back `undefined` — keeping the column clean and
+ * letting the contract extractor fall back to its source-scan path.
+ */
+export declare function normalizeRouteMethod(raw: string | null | undefined): string | undefined;
+/**
+ * The Route node identity (#2289): `(method, path)` when the verb is known and
+ * specific, falling back to URL-only when the method is `undefined` (filesystem
+ * routes, Laravel `resource`/`apiResource`) or `'*'` (method-agnostic routes,
+ * e.g. Django function views). The URL-fallback keeps those byte-identical to
+ * the pre-#2289 URL-only ids, so only genuine declaration-style multi-verb
+ * routes (`GET /x` + `POST /x`) split into separate nodes.
+ *
+ * Used by the routes phase (node id + registry key), the processes phase
+ * (ENTRY_POINT_OF), and the handler-symbol resolver — all three must key
+ * identically.
+ */
+export declare function routeNodeKey(method: string | undefined, url: string): string;

package/dist/core/ingestion/route-extractors/route-path.js

@@ -2,10 +2,11 @@
  * Shared route-path normalization.
  *
  * Extracted from the routes phase so both the routes phase (which creates the
- * `Route` graph node, keyed by the normalized URL) and the parse phase (which
- * resolves each route's handler symbol and needs the SAME key to associate the
- * resolved id back to the route) can compute an identical route URL without a
- * phase-to-phase import cycle. Pure string logic, no dependencies.
+ * `Route` graph node, keyed by `(method, url)` via `routeNodeKey` — #2289) and
+ * the parse phase (which resolves each route's handler symbol and needs the
+ * SAME key to associate the resolved id back to the route) can compute an
+ * identical route identity without a phase-to-phase import cycle. Pure string
+ * logic, no dependencies.
  */
 /**
  * Join a route's path with its (optional) prefix into a normalized,
@@ -18,3 +19,48 @@ export function normalizeExtractedRoutePath(routePath, prefix) {
     const joined = prefixPart ? `/${prefixPart}${pathPart ? `/${pathPart}` : ''}` : `/${pathPart}`;
     return joined.replace(/\/+/g, '/') || '/';
 }
+const VALID_HTTP_METHODS = new Set([
+    'GET',
+    'POST',
+    'PUT',
+    'PATCH',
+    'DELETE',
+    'HEAD',
+    'OPTIONS',
+    'TRACE',
+    'CONNECT',
+]);
+/**
+ * Canonicalize a route's HTTP verb for persistence on the Route node and for
+ * the route identity key. Returns an upper-cased standard method, `'*'` for a
+ * method-agnostic route (e.g. a Django function view), or `undefined` when the
+ * value is not a real HTTP verb. Laravel `Route::resource` / `apiResource`
+ * surface values like `resource` / `apiResource` (they expand to several verbs
+ * at runtime), so they come back `undefined` — keeping the column clean and
+ * letting the contract extractor fall back to its source-scan path.
+ */
+export function normalizeRouteMethod(raw) {
+    if (typeof raw !== 'string')
+        return undefined;
+    const verb = raw.trim().toUpperCase();
+    // '*' marks a method-agnostic route. Preserve it so the contract layer emits a
+    // wildcard provider that matches consumers of any method.
+    if (verb === '*')
+        return '*';
+    return VALID_HTTP_METHODS.has(verb) ? verb : undefined;
+}
+/**
+ * The Route node identity (#2289): `(method, path)` when the verb is known and
+ * specific, falling back to URL-only when the method is `undefined` (filesystem
+ * routes, Laravel `resource`/`apiResource`) or `'*'` (method-agnostic routes,
+ * e.g. Django function views). The URL-fallback keeps those byte-identical to
+ * the pre-#2289 URL-only ids, so only genuine declaration-style multi-verb
+ * routes (`GET /x` + `POST /x`) split into separate nodes.
+ *
+ * Used by the routes phase (node id + registry key), the processes phase
+ * (ENTRY_POINT_OF), and the handler-symbol resolver — all three must key
+ * identically.
+ */
+export function routeNodeKey(method, url) {
+    return method && method !== '*' ? `${method} ${url}` : url;
+}

package/dist/core/run-analyze.js

@@ -353,6 +353,20 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         }
         try {
             await initLbug(lbugPath);
+            // Gate on FTS availability BEFORE touching any index. createSearchFTSIndexes
+            // now DROPs each index before recreating it (so schema changes reach existing
+            // DBs); if the extension were unavailable, the drops would run and leave the
+            // DB index-less, only failing at the create step. Fail loudly first — mirrors
+            // the analyze path's `if (ftsAvailable)` gate below — so an unavailable
+            // extension never destroys the existing indexes.
+            const repairFtsAvailable = await loadFTSExtension(undefined, {
+                policy: resolveAnalyzeInstallPolicy(),
+            });
+            if (!repairFtsAvailable) {
+                throw new Error('Cannot repair FTS indexes: the LadybugDB FTS extension is unavailable ' +
+                    '(not pre-installed and could not be installed on this machine). ' +
+                    'Run `gitnexus doctor` to install it, then retry `--repair-fts`.');
+            }
             progress('fts', 85, 'Repairing search indexes...');
             await createSearchFTSIndexes({
                 onIndexStart: options.verbose
@@ -420,6 +434,27 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             `Tip: set \`pdg: ${pdgOn}\` in .gitnexusrc to pin the mode across runs.`);
         options = { ...options, force: true };
     }
+    // ── schema-version mismatch forces full rebuild (#2289 P1) ────────
+    // Mirrors the pdg-mode block above: a stamp from an older
+    // INCREMENTAL_SCHEMA_VERSION (e.g. pre-v5 URL-only Route ids) cannot be
+    // reconciled by an incremental top-up — same-commit re-analyze would
+    // strand stale rows next to new-schema writes. MUST sit before the
+    // alreadyUpToDate fast path below: an unchanged-commit clean tree would
+    // otherwise early-return without ever reaching the `isIncremental` gate
+    // that consults `schemaVersion`, defeating the bump's whole point.
+    //
+    // `schemaVersion === undefined` covers two cases that should still trip
+    // this guard: a non-git repo (which never stamps the field) and very old
+    // meta from before the field existed. Non-git repos take the
+    // `currentCommit === ''` rebuild branch below regardless, so the redundant
+    // force here is harmless; the friendlier `'pre-versioning'` log avoids a
+    // user-visible "stamped vundefined" line in that edge case.
+    if (existingMeta && existingMeta.schemaVersion !== INCREMENTAL_SCHEMA_VERSION) {
+        const stampedVersion = existingMeta.schemaVersion ?? 'pre-versioning';
+        log(`index schema changed (stamped v${stampedVersion}, this build is v${INCREMENTAL_SCHEMA_VERSION}); ` +
+            `forcing a full rebuild so persisted rows match the current schema.`);
+        options = { ...options, force: true };
+    }
     // ── Early-return: already up to date ──────────────────────────────
     if (existingMeta && !options.force && existingMeta.lastCommit === currentCommit) {
         // Non-git folders have currentCommit = '' — always rebuild since we can't detect changes

package/dist/core/search/fts-indexes.js

@@ -1,32 +1,48 @@
-import { createFTSIndex } from '../lbug/lbug-adapter.js';
+import { createFTSIndex, dropFTSIndex } from '../lbug/lbug-adapter.js';
 import { FTS_INDEXES } from './fts-schema.js';
 export async function createSearchFTSIndexes(options) {
     for (const { table, indexName, properties } of FTS_INDEXES) {
         options?.onIndexStart?.(table, indexName);
+        // Drop first so the live `properties` always win. `createFTSIndex` is
+        // idempotent-by-name (skips when the index already exists), so without the
+        // drop a schema change — e.g. adding `description` (#2299) — would never
+        // reach an existing `.lbug` DB on an incremental re-analyze or `--repair-fts`;
+        // the old name+content index would silently persist. `dropFTSIndex` no-ops
+        // when the index is absent (first-ever analyze) and clears the per-connection
+        // memo so the create below actually runs.
+        // ponytail: this rebuilds every FTS index on every analyze instead of
+        // skipping when present; FTS build is proportional to symbol-table size and
+        // runs inside the existing FTS phase. Gate on a stored schema fingerprint if
+        // this rebuild cost ever shows up in analyze profiles.
+        await dropFTSIndex(table, indexName);
         await createFTSIndex(table, indexName, [...properties]);
         options?.onIndexReady?.(table, indexName);
     }
 }
 export async function verifySearchFTSIndexes(executeQuery) {
-    const safeIdentifier = (value) => {
-        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
-            throw new Error(`Invalid FTS identifier: ${value}`);
-        }
-        return value;
-    };
+    // Read the catalog once and check each configured index both EXISTS and
+    // covers its expected columns. A queryability-only probe (CALL QUERY_FTS_INDEX
+    // ... catch) is not enough: a stale `name+content`-only index left on a
+    // pre-#2299 DB stays queryable yet silently misses `description`, so the probe
+    // would pass while doc-comment search is still broken (#2299). SHOW_INDEXES
+    // exposes `property_names` (STRING[]) per index, so we assert coverage directly.
+    const rows = await executeQuery('CALL SHOW_INDEXES() RETURN *');
+    const propsByIndex = new Map();
+    for (const row of rows) {
+        if (typeof row !== 'object' || row === null)
+            continue;
+        const record = row;
+        const indexName = record.index_name;
+        const propertyNames = record.property_names;
+        if (typeof indexName !== 'string' || !Array.isArray(propertyNames))
+            continue;
+        propsByIndex.set(indexName, propertyNames.filter((p) => typeof p === 'string'));
+    }
     const missing = [];
-    for (const { table, indexName } of FTS_INDEXES) {
-        const safeTable = safeIdentifier(table);
-        const safeIndex = safeIdentifier(indexName);
-        const probe = `
-      CALL QUERY_FTS_INDEX('${safeTable}', '${safeIndex}', '__gitnexus_fts_probe__', conjunctive := false)
-      RETURN score
-      LIMIT 1
-    `;
-        try {
-            await executeQuery(probe);
-        }
-        catch {
+    for (const { table, indexName, properties } of FTS_INDEXES) {
+        const actual = propsByIndex.get(indexName);
+        // Absent from the catalog, or present but not covering every expected column.
+        if (!actual || !properties.every((p) => actual.includes(p))) {
             missing.push(`${table}.${indexName}`);
         }
     }

package/dist/core/search/fts-schema.js

@@ -1,7 +1,40 @@
+// Shared by both index creation (`createSearchFTSIndexes`) and querying
+// (`searchFTSFromLbug` / `verifySearchFTSIndexes`) — the single source of truth
+// for which tables/columns are full-text searchable. Adding `description` here
+// makes doc comments (Javadoc/KDoc/JSDoc/Doxygen/godoc/RDoc) keyword-searchable
+// once they are populated by `descriptionExtractor` (#2270/#2286, issue #2299).
+//
+// IMPORTANT: every property must be a real column on its table (see
+// `core/lbug/schema.ts`). `File` has no `description` column, so it stays
+// name+content. All other entries below carry a `description` column.
+//
+// Tables beyond the original 5 mirror `EMBEDDABLE_LABELS` (embeddings/types.ts):
+// indexing the same set keeps a symbol's doc comment both keyword- and
+// semantically-searchable.
+const FTS_PROPERTIES = ['name', 'content', 'description'];
 export const FTS_INDEXES = [
+    // File has no `description` column — keep it name+content only.
     { table: 'File', indexName: 'file_fts', properties: ['name', 'content'] },
-    { table: 'Function', indexName: 'function_fts', properties: ['name', 'content'] },
-    { table: 'Class', indexName: 'class_fts', properties: ['name', 'content'] },
-    { table: 'Method', indexName: 'method_fts', properties: ['name', 'content'] },
-    { table: 'Interface', indexName: 'interface_fts', properties: ['name', 'content'] },
+    // Original 5 (minus File) gain `description`.
+    { table: 'Function', indexName: 'function_fts', properties: FTS_PROPERTIES },
+    { table: 'Class', indexName: 'class_fts', properties: FTS_PROPERTIES },
+    { table: 'Method', indexName: 'method_fts', properties: FTS_PROPERTIES },
+    { table: 'Interface', indexName: 'interface_fts', properties: FTS_PROPERTIES },
+    // Remaining EMBEDDABLE_LABELS symbol tables — all CODE_ELEMENT_BASE-shaped
+    // (or a superset), so all carry name + content + description columns.
+    { table: 'Constructor', indexName: 'constructor_fts', properties: FTS_PROPERTIES },
+    { table: 'Struct', indexName: 'struct_fts', properties: FTS_PROPERTIES },
+    { table: 'Enum', indexName: 'enum_fts', properties: FTS_PROPERTIES },
+    { table: 'Trait', indexName: 'trait_fts', properties: FTS_PROPERTIES },
+    { table: 'Impl', indexName: 'impl_fts', properties: FTS_PROPERTIES },
+    { table: 'Macro', indexName: 'macro_fts', properties: FTS_PROPERTIES },
+    { table: 'Namespace', indexName: 'namespace_fts', properties: FTS_PROPERTIES },
+    { table: 'TypeAlias', indexName: 'type_alias_fts', properties: FTS_PROPERTIES },
+    { table: 'Typedef', indexName: 'typedef_fts', properties: FTS_PROPERTIES },
+    { table: 'Const', indexName: 'const_fts', properties: FTS_PROPERTIES },
+    { table: 'Property', indexName: 'property_fts', properties: FTS_PROPERTIES },
+    { table: 'Record', indexName: 'record_fts', properties: FTS_PROPERTIES },
+    { table: 'Union', indexName: 'union_fts', properties: FTS_PROPERTIES },
+    { table: 'Static', indexName: 'static_fts', properties: FTS_PROPERTIES },
+    { table: 'Variable', indexName: 'variable_fts', properties: FTS_PROPERTIES },
 ];

package/dist/storage/repo-manager.d.ts

@@ -217,8 +217,14 @@ export interface RepoMeta {
  * so the engine would silently UNDER-REPORT return-value ascent on an
  * incremental top-up; force a full re-analyze instead (same contract as v2/v3).
  * This single bump covers the whole FU-C re-index window (and the later FU-B-2).
- */
-export declare const INCREMENTAL_SCHEMA_VERSION = 4;
+ * v5: `Route` node identity changed to `(method, url)` (#2289 — a same-URL
+ * GET/POST pair is now two distinct Route nodes). Every declarative-route node
+ * id moved from `Route:/x` to `Route:GET /x` (filesystem routes keep their
+ * URL-only id). The incremental writeback preserves unchanged-file rows, so a
+ * top-up against a pre-v5 index would strand old url-keyed Route nodes alongside
+ * new composite-keyed ones — force a full re-analyze instead.
+ */
+export declare const INCREMENTAL_SCHEMA_VERSION = 5;
 export interface IndexedRepo {
     repoPath: string;
     storagePath: string;

package/dist/storage/repo-manager.js

@@ -74,8 +74,14 @@ export const registryPathEquals = (a, b) => process.platform === 'win32' ? a.toL
  * so the engine would silently UNDER-REPORT return-value ascent on an
  * incremental top-up; force a full re-analyze instead (same contract as v2/v3).
  * This single bump covers the whole FU-C re-index window (and the later FU-B-2).
- */
-export const INCREMENTAL_SCHEMA_VERSION = 4;
+ * v5: `Route` node identity changed to `(method, url)` (#2289 — a same-URL
+ * GET/POST pair is now two distinct Route nodes). Every declarative-route node
+ * id moved from `Route:/x` to `Route:GET /x` (filesystem routes keep their
+ * URL-only id). The incremental writeback preserves unchanged-file rows, so a
+ * top-up against a pre-v5 index would strand old url-keyed Route nodes alongside
+ * new composite-keyed ones — force a full re-analyze instead.
+ */
+export const INCREMENTAL_SCHEMA_VERSION = 5;
 const GITNEXUS_DIR = '.gitnexus';
 const GITNEXUS_EXCLUDE_ENTRY = `${GITNEXUS_DIR}/`;
 // ─── Local Storage Helpers ─────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.9-rc.21",
+  "version": "1.6.9-rc.23",
   "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",

package/scripts/cross-platform-tests.ts

@@ -70,6 +70,7 @@ const LBUG_NATIVE = [
   'test/integration/local-backend-calltool.test.ts',
   'test/integration/search-core.test.ts',
   'test/integration/search-pool.test.ts',
+  'test/integration/fts-description-search.test.ts',
   'test/integration/staleness-and-stability.test.ts',
   'test/integration/analyze-wal-checkpoint-failure.test.ts',
 ];