gitnexus 1.6.11-rc.30 → 1.6.11-rc.31

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

@@ -1028,13 +1028,17 @@ export const PYTHON_HTTP_PLUGIN = {
     name: 'python-http',
     language: Python,
     // routeCoverage intentionally LEFT at the default 'partial' (#2138 Part 2).
-    // It would be a no-op even if set to 'complete': FastAPI decorator routes set
-    // no handlerName (generic worker path) and Django sets methodName: null, so no
-    // Python file ever resolves a handlerSymbolId and none would be parse-skipped.
-    // Declaring 'complete' now is only a latent trap for the moment a follow-up
-    // gives FastAPI routes a handlerName. `hasConsumerSignals` is kept (and is a
-    // true superset of scan()'s consumer shapes) so the precondition already holds
-    // when Python is later flipped to 'complete'.
+    // 'complete' is now an active data-loss risk rather than a no-op: FastAPI and
+    // Flask decorator routes do carry a handlerName (Python's
+    // `decoratorRouteHandlerName` hook reads the `decorated_definition`), so their
+    // files can resolve every handlerSymbolId and become parse-skip candidates.
+    // The flag asserts more than that — it asserts ingestion emits a Route node
+    // for EVERY provider route this scan() finds, and it does not: Flask's
+    // imperative `add_url_rule('/p', view_func=handler)` registration below has no
+    // ingestion counterpart, so skipping a file that mixes it with resolved
+    // decorator routes would drop those providers. `hasConsumerSignals` is kept
+    // (and is a true superset of scan()'s consumer shapes) so the consumer half of
+    // the precondition already holds once provider parity is closed.
     // Consumer signals scan() can detect: `requests.<verb>`/`requests.request`,
     // `httpx` (sync/async client), the `uri=`/`url=` keyword/variable wrapper
     // calls, plus aiohttp/urllib. Conservative — over-matching only costs a parse.

package/dist/core/group/extractors/http-route-extractor.js

@@ -571,7 +571,7 @@ export class HttpRouteExtractor {
         // removes any candidate that still needs scanning for outbound calls.
         const coveredFiles = new Set();
         const graphProviders = dbExecutor != null
-            ? await this.extractProvidersGraph(dbExecutor, getDetections, resolveDetectionSymbol, coveredFiles)
+            ? await this.extractProvidersGraph(dbExecutor, getDetections, resolveDetectionSymbol, loadFileSymbols, coveredFiles)
             : [];
         // Consumer-safety gate (#2138 Part 2): `extractProvidersGraph` marks a file
         // covered on *provider* grounds (all HANDLES_ROUTE rows resolved + a
@@ -619,7 +619,7 @@ export class HttpRouteExtractor {
         });
     }
     // ─── Graph-assisted providers ──────────────────────────────────────
-    async extractProvidersGraph(db, getDetections, resolveSymbol, coveredFiles) {
+    async extractProvidersGraph(db, getDetections, resolveSymbol, loadFileSymbols, coveredFiles) {
         const out = [];
         // Per-file coverage tracking (#2138 Part 2): a file is "fully graph-covered"
         // when every one of its HANDLES_ROUTE rows resolved a handlerSymbolId AND its
@@ -672,16 +672,11 @@ export class HttpRouteExtractor {
                     method = 'GET';
                 symbolUid = handlerSymbolId;
                 if (filePath) {
-                    try {
-                        const syms = await db(CONTAINING_QUERY, { filePath });
-                        const hit = syms.find((s) => String(s.uid ?? s[0]) === handlerSymbolId);
-                        if (hit) {
-                            symbolName = String(hit.name ?? hit[1]) || symbolName;
-                            symPath = String(hit.filePath ?? hit[2]) || filePath;
-                        }
-                    }
-                    catch {
-                        /* keep the authoritative uid + basename fallback */
+                    const syms = await loadFileSymbols(filePath);
+                    const hit = syms.find((s) => String(s.uid ?? s[0]) === handlerSymbolId);
+                    if (hit) {
+                        symbolName = String(hit.name ?? hit[1]) || symbolName;
+                        symPath = String(hit.filePath ?? hit[2]) || filePath;
                     }
                 }
             }

package/dist/core/ingestion/language-provider.d.ts

@@ -306,6 +306,27 @@ interface LanguageProviderConfig {
      * Default: undefined (no language-specific route extraction).
      */
     readonly extractDecoratorRoutes?: (tree: Parser.Tree, filePath: string, lineOffset: number) => ExtractedDecoratorRoute[];
+    /**
+     * Name of the function a route decorator captured by the worker's generic
+     * `@decorator` query applies to, given the decorator's own AST node.
+     *
+     * The worker knows a decorator is a route decorator but not how this
+     * language's grammar attaches it to a definition, so it hands the node over
+     * unchanged and takes whatever the language returns. Only languages that
+     * declare route handlers through the generic decorator captures need this;
+     * languages with a dedicated {@link extractDecoratorRoutes} extractor
+     * (JS/TS via `nest.ts`, Java via `spring.ts`) already set
+     * `ExtractedDecoratorRoute.handlerName` there and should leave this undefined.
+     *
+     * Implementations must read their own decorated-definition shape directly and
+     * return undefined for anything else — never climb ancestors to find a name,
+     * since a decorator that is not attached to a function has no handler and a
+     * borrowed enclosing name resolves `handlerSymbolId` to the wrong symbol. The
+     * routes phase treats undefined as "fall back to the file-level edge".
+     *
+     * Default: undefined (no handler name from generic decorator captures).
+     */
+    readonly decoratorRouteHandlerName?: (decoratorNode: SyntaxNode) => string | undefined;
     /**
      * Collect a project-wide, language-agnostic view of route-defining
      * class/interface declarations (`SharedSpringType`) from a parsed file.

package/dist/core/ingestion/languages/python.js

@@ -29,6 +29,7 @@ import { emitPythonScopeCaptures, pythonFunctionDefinitionLabel, interpretPython
 import { extractDjangoRoutes } from '../route-extractors/django.js';
 import { discoverDjangoRootUrls } from '../route-extractors/django-root-discovery.js';
 import { extractPythonModuleConstants } from '../route-extractors/python-const-resolver.js';
+import { pythonDecoratorRouteHandlerName } from '../route-extractors/python-decorator-handler.js';
 const BUILT_INS = new Set([
     'print',
     'len',
@@ -120,6 +121,7 @@ export const pythonProvider = defineLanguage({
     // and extraction resolve any repo-relative file regardless of parse chunking.
     discoverRootRouteFiles: (files, contentMap, reader) => discoverDjangoRootUrls(files, contentMap, reader),
     extractRoutes: (tree, filePath, reader, parser) => parser ? extractDjangoRoutes(tree, filePath, parser, reader) : [],
+    decoratorRouteHandlerName: pythonDecoratorRouteHandlerName,
     labelOverride: pythonFunctionDefinitionLabel,
     // ── RFC #909 Ring 3: scope-based resolution hooks (RFC §5) ──────────
     // Python is the first migration. See ./python/index.ts for the

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

@@ -265,28 +265,25 @@ export const routesPhase = {
         }
         let handlerContents;
         if (routeRegistry.size > 0) {
-            const handlerPathFor = (routeKey, entry) => {
-                if (entry.source !== DATA_ROUTE_TABLE_SOURCE)
-                    return entry.filePath;
-                const handlerSymbolId = routeHandlerSymbols.get(routeKey);
-                const resolvedPath = handlerSymbolId
-                    ? ctx.graph.getNode(handlerSymbolId)?.properties.filePath
+            // Resolve once so content attribution, the route stamp, and the edge use
+            // the same live graph node. Pre-seeded routes never own handler symbols.
+            const routes = [...routeRegistry].map(([routeKey, entry]) => {
+                const id = preSeededKeys.has(routeKey) ? undefined : routeHandlerSymbols.get(routeKey);
+                const node = id ? ctx.graph.getNode(id) : undefined;
+                const handlerSymbol = id && node ? { id, node } : undefined;
+                const resolvedPath = entry.source === DATA_ROUTE_TABLE_SOURCE
+                    ? handlerSymbol?.node.properties.filePath
                     : undefined;
-                return typeof resolvedPath === 'string' ? resolvedPath : entry.filePath;
-            };
-            const handlerPaths = [...routeRegistry].map(([key, entry]) => handlerPathFor(key, entry));
-            handlerContents = await readFileContents(ctx.repoPath, handlerPaths);
-            for (const [routeKey, entry] of routeRegistry) {
+                const handlerPath = typeof resolvedPath === 'string' ? resolvedPath : entry.filePath;
+                return { routeKey, entry, handlerSymbol, handlerPath };
+            });
+            handlerContents = await readFileContents(ctx.repoPath, routes.map(({ handlerPath }) => handlerPath));
+            for (const { routeKey, entry, handlerSymbol, handlerPath } of routes) {
                 const { source: routeSource, method: routeMethod, url } = entry;
-                const handlerPath = handlerPathFor(routeKey, entry);
                 const content = handlerContents.get(handlerPath);
-                // A pre-seeded route can never legitimately appear in
-                // `routeHandlerSymbols`, so a key that does is a route that LOST (#3049).
-                const handlerSymbolId = preSeededKeys.has(routeKey)
-                    ? undefined
-                    : routeHandlerSymbols.get(routeKey);
+                const handlerSymbolId = handlerSymbol?.id;
                 const analysisContent = entry.source === DATA_ROUTE_TABLE_SOURCE && content
-                    ? handlerSymbolContent(content, handlerSymbolId ? ctx.graph.getNode(handlerSymbolId) : undefined)
+                    ? handlerSymbolContent(content, handlerSymbol?.node)
                     : content;
                 const { responseKeys, errorKeys } = analysisContent
                     ? handlerPath.endsWith('.php')
@@ -318,6 +315,18 @@ export const routesPhase = {
                     confidence: 1.0,
                     reason: routeSource,
                 });
+                // Keep the file edge for existing extractor queries; add the live
+                // definition edge for explicit handler-level traversal.
+                if (handlerSymbolId) {
+                    ctx.graph.addRelationship({
+                        id: generateId('HANDLES_ROUTE', `${handlerSymbolId}->${routeNodeId}`),
+                        sourceId: handlerSymbolId,
+                        targetId: routeNodeId,
+                        type: 'HANDLES_ROUTE',
+                        confidence: 1.0,
+                        reason: routeSource,
+                    });
+                }
             }
             if (isDev) {
                 logger.info(`🗺️ Route registry: ${routeRegistry.size} routes${duplicateRoutes > 0 ? ` (${duplicateRoutes} duplicate URLs skipped)` : ''}`);

package/dist/core/ingestion/route-extractors/python-decorator-handler.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Return the function name attached to a Python decorator's immediate
+ * `decorated_definition`; reject every other shape rather than climbing.
+ */
+import type { SyntaxNode } from '../utils/ast-helpers.js';
+export declare function pythonDecoratorRouteHandlerName(decoratorNode: SyntaxNode): string | undefined;

package/dist/core/ingestion/route-extractors/python-decorator-handler.js

@@ -0,0 +1,16 @@
+/**
+ * Return the function name attached to a Python decorator's immediate
+ * `decorated_definition`; reject every other shape rather than climbing.
+ */
+export function pythonDecoratorRouteHandlerName(decoratorNode) {
+    const decorated = decoratorNode.parent;
+    if (decorated === null || decorated.type !== 'decorated_definition')
+        return undefined;
+    // `async def` is still a `function_definition` in tree-sitter-python (the
+    // `async` keyword is an anonymous child), so async handlers need no branch.
+    const definition = decorated.childForFieldName('definition');
+    if (!definition || definition.type !== 'function_definition')
+        return undefined;
+    const name = definition.childForFieldName('name')?.text;
+    return name !== undefined && name.length > 0 ? name : undefined;
+}

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

@@ -1214,12 +1214,14 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
                     const httpMethod = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'].includes(method)
                         ? method
                         : 'GET';
+                    const handlerName = provider.decoratorRouteHandlerName?.(decoratorNode);
                     const base = {
                         filePath: file.path,
                         httpMethod,
                         decoratorName,
                         lineNumber: decoratorNode.startPosition.row + lineOffset,
                         ...(decoratorReceiver ? { decoratorReceiver } : {}),
+                        ...(handlerName ? { handlerName } : {}),
                     };
                     if (decoratorArgStr) {
                         // String-literal path (the fast path, unchanged). Empty-string

package/dist/core/lbug/schema.js

@@ -342,7 +342,7 @@ const DEFINITION_ANCHOR_LABELS = NODE_TABLES.filter((label) => !NON_DEFINITION_L
  *  | `Annotation` | `frameworks/spring/conditionals.ts` CONDITIONAL_ON | `resolveDefGraphId` / `resolveCallerGraphId` |
  *  | `Community`  | `pipeline-phases/communities.ts` MEMBER_OF     | Leiden membership, `isCommunitySymbol`-gated |
  *  | `Process`    | `pipeline-phases/processes.ts` STEP_IN_PROCESS | trace step node                       |
- *  | `Route`      | `pipeline-phases/routes.ts` HANDLES_ROUTE      | `generateId('File', handlerPath)` — a literal |
+ *  | `Route`      | `pipeline-phases/routes.ts` HANDLES_ROUTE      | `generateId('File', handlerPath)` — a literal — plus, when the route's handler resolves, that definition |
  *  | `Tool`       | `pipeline-phases/tools.ts` HANDLES_TOOL        | `handlerNodeId` — whatever definition the decorator sat on |
  *  | `File`       | `languages/vue/scope-resolver.ts` BINDS_EVENT_HANDLER | handler node                    |
  *  | `Record`     | `cobol-processor.ts` × 8 external-resource sites | `scopedCallerLookup`                |
@@ -354,25 +354,35 @@ const DEFINITION_ANCHOR_LABELS = NODE_TABLES.filter((label) => !NON_DEFINITION_L
  * {@link DEFINITION_ANCHOR_LABELS} × this set covers all four plus every
  * sibling the same emitters can reach.
  *
- * TWO TARGETS ARE LABEL-GATED TODAY, and the cross product over-declares for
- * them ON PURPOSE (~47 of the 182 attachment pairs are unreachable right now):
+ * TWO TARGETS USE ONLY PART OF THEIR CROSS PRODUCT TODAY, and it over-declares
+ * for them ON PURPOSE (~45 of the 182 attachment pairs have no emitter that can
+ * reach them right now):
  *  - `Community` — `isCommunitySymbol` (`community-processor.ts`) admits only
  *    `Function` / `Class` / `Method` / `Interface` as members, so the other 22
  *    anchors cannot source a MEMBER_OF edge until that predicate widens.
- *  - `Route` — HANDLES_ROUTE sources `generateId('File', handlerPath)`, a
- *    literal `File`, so every non-`File` anchor is headroom.
+ *  - `Route` — HANDLES_ROUTE always sources the literal
+ *    `generateId('File', handlerPath)`, and additionally the route's HANDLER
+ *    DEFINITION whenever `routeHandlerSymbols` produced an id that
+ *    `ctx.graph.getNode` confirms is in the graph. That second anchor is a
+ *    lookup result the emitter never label-checks; handler resolution returns
+ *    `Function` / `Method` definitions today, so `Route` is no longer a
+ *    `File`-only target and the remaining anchors are headroom.
  *
  * Those pairs stay declared because the two sides of the error are not
  * symmetric: an UNDECLARED pair makes LadybugDB reject the edge and aborts
  * `analyze` outright on a user's repo, while an unused DECLARED pair costs
  * almost nothing — `bench/schema-pairs` measured the pre-#2801 332→450 growth
- * (118 pairs, of which these ~47 are a part) at 0.93–1.05×, i.e. inside
+ * (118 pairs, of which these ~45 are a part) at 0.93–1.05×, i.e. inside
  * run-to-run noise. #2801's 11 generated `Record` pairs bring the total to 461.
  * Its Windows measurements and noise caveats live in the benchmark README; the
  * operational production ceiling is the checked 1.5× budget.
  * Every one of the four aborts above came from re-narrowing a set to what one
  * predicate looked like it allowed — so a reading of `isCommunitySymbol` is not
- * grounds to shrink this. Widening either predicate is then a no-op here.
+ * grounds to shrink this. `Route` is the worked example in the other direction:
+ * the definition-level HANDLES_ROUTE edge started emitting `Function|Route` /
+ * `Method|Route` with no DDL change, because those pairs were already declared.
+ * Widening `isCommunitySymbol`, or handler resolution returning a further
+ * label, is likewise a no-op here.
  *
  * `Route` / `Tool` being excluded as ANCHORS (see {@link NON_DEFINITION_LABELS})
  * is likewise a SIZE choice, not something derived from a rule: they do source

package/dist/storage/parse-cache.js

@@ -700,7 +700,18 @@ import { copyV8CacheIfPresent, tryLoadV8Cache, writeV8CacheFile } from './v8-sid
 // pre-change cache would have served as zero. origin/main at allocation is 88.
 // RE-CHECK AGAINST origin/main AND OPEN PRs IMMEDIATELY BEFORE MERGING — this
 // entry was allocated 83 first, and five bumps landed upstream before it merged.
-const SCHEMA_BUMP = 89;
+// 89 -> 90 (#2865): route decorator captures now carry `handlerName` in
+// `decoratorRoutes`, which is what lets `resolveRouteHandlerSymbols` stamp
+// `handlerSymbolId` and the routes phase emit the definition-level
+// HANDLES_ROUTE edge. The field is minted in the parse WORKER and persisted
+// verbatim, so a warm v89 cache replays handler-less decorator routes: every
+// route loses its definition-level association on incremental analyze while
+// every cold-run test passes — the inert-feature trap the entries above record.
+// 89 is now taken by merged #3128. 90 is the next free value above origin/main
+// (89) and above every in-flight claim found by scanning open PRs'
+// parse-cache.ts at their exact head SHAs (highest other open claim was still
+// ≤88). RE-CHECK AGAINST origin/main AND OPEN PRs IMMEDIATELY BEFORE MERGING.
+const SCHEMA_BUMP = 90;
 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.11-rc.30",
+  "version": "1.6.11-rc.31",
   "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",