gitnexus 1.6.13-rc.66 → 1.6.13-rc.67

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

@@ -26,7 +26,7 @@ import type { ExtractedRoute } from './route-extractors/laravel.js';
 import type { SharedSpringType } from './route-extractors/spring-shared.js';
 import type { ModuleConstants, Operand, RepoConstants } from './route-extractors/constant-resolver.js';
 import type Parser from 'tree-sitter';
-import type { ExtractedDecoratorRoute } from './workers/parse-worker.js';
+import type { ExtractedDecoratorRoute, ExtractedToolDef } from './workers/parse-worker.js';
 import type { SemanticModel } from './model/semantic-model.js';
 /** What a provider's {@link LanguageProviderConfig.resolveRouteHandler} can see. */
 export interface RouteHandlerResolutionHookContext {
@@ -430,6 +430,9 @@ interface LanguageProviderConfig {
      * Default: undefined (no text-route extraction).
      */
     readonly extractTextRoutes?: (filePath: string, content: string) => ExtractedRoute[];
+    /** Extract tool registrations after captures, using only emitted callable identities.
+     * The map keys are declaration-name AST node IDs, local to this parsed tree. */
+    readonly extractToolDefinitions?: (tree: Parser.Tree, filePath: string, lineOffset: number, callableBindings: ReadonlyMap<number, string>) => ExtractedToolDef[];
     /**
      * Extract routes that a parsed file declares in its own AST.
      *

package/dist/core/ingestion/languages/typescript/tool-definitions.d.ts

@@ -0,0 +1,4 @@
+import type Parser from 'tree-sitter';
+import type { ExtractedToolDef } from '../../workers/parse-worker.js';
+/** Direct SDK registrations only; no wrapper, alias-chain or runtime-value inference. */
+export declare function extractToolDefinitions(tree: Parser.Tree, filePath: string, lineOffset?: number, callableBindings?: ReadonlyMap<number, string>): ExtractedToolDef[];

package/dist/core/ingestion/languages/typescript/tool-definitions.js

@@ -0,0 +1,355 @@
+import { plainString, propertyName } from '../../route-extractors/data-route-table.js';
+const FUNCTIONS = new Set([
+    'function_declaration',
+    'generator_function_declaration',
+    'function_expression',
+    'generator_function',
+    'arrow_function',
+    'method_definition',
+]);
+const BLOCKS = new Set([
+    'statement_block',
+    'for_statement',
+    'for_in_statement',
+    'switch_body',
+    'catch_clause',
+    'class_body',
+]);
+const SDK_MODULES = new Set([
+    '@modelcontextprotocol/sdk/server/mcp.js',
+    '@modelcontextprotocol/sdk/server/mcp',
+]);
+function lookup(scope, name) {
+    for (let current = scope; current; current = current.parent) {
+        const binding = current.bindings.get(name);
+        if (binding)
+            return binding;
+    }
+}
+/** Only binding/assignment patterns: never descend into keys, types or defaults.
+ * Member assignment targets are reported separately from binding names. */
+function patternNames(pattern, onMember) {
+    const names = [];
+    const pending = [pattern];
+    while (pending.length) {
+        const node = pending.pop();
+        if (node.type === 'identifier' || node.type === 'shorthand_property_identifier_pattern') {
+            names.push(node);
+        }
+        else if (node.type === 'member_expression' || node.type === 'subscript_expression') {
+            onMember?.(node);
+        }
+        else if (node.type === 'pair_pattern') {
+            const value = node.childForFieldName('value');
+            if (value)
+                pending.push(value);
+        }
+        else if (node.type === 'assignment_pattern' || node.type === 'object_assignment_pattern') {
+            const left = node.childForFieldName('left');
+            if (left)
+                pending.push(left);
+        }
+        else if (node.type === 'array_pattern' ||
+            node.type === 'object_pattern' ||
+            node.type === 'rest_pattern') {
+            pending.push(...node.namedChildren);
+        }
+    }
+    return names;
+}
+function declare(scope, name, details = {}) {
+    const previous = scope.bindings.get(name.text);
+    if (previous) {
+        previous.invalid = true;
+    }
+    else {
+        scope.bindings.set(name.text, { name, scope, kind: 'unknown', ...details });
+    }
+}
+function variableScope(scope) {
+    while (!scope.functionScope && scope.parent)
+        scope = scope.parent;
+    return scope;
+}
+function collectBindings(root) {
+    const moduleScope = { functionScope: true, bindings: new Map() };
+    const scopes = new Map();
+    const calls = [];
+    const writes = [];
+    const pending = [{ node: root, scope: moduleScope }];
+    while (pending.length) {
+        const entry = pending.pop();
+        const node = entry.node;
+        let scope = entry.scope;
+        const isFunction = FUNCTIONS.has(node.type);
+        const name = node.childForFieldName('name');
+        if (node.type === 'function_declaration' || node.type === 'generator_function_declaration') {
+            if (name)
+                declare(scope, name, { kind: 'function', value: node, immutable: true });
+        }
+        else if ([
+            'class_declaration',
+            'interface_declaration',
+            'type_alias_declaration',
+            'enum_declaration',
+        ].includes(node.type)) {
+            if (name)
+                declare(scope, name);
+        }
+        if (isFunction ||
+            BLOCKS.has(node.type) ||
+            node.type === 'class' ||
+            node.type === 'class_declaration') {
+            scope = { parent: scope, functionScope: isFunction, bindings: new Map() };
+        }
+        scopes.set(node.id, scope);
+        if (node.type === 'class' && name)
+            declare(scope, name);
+        if (isFunction) {
+            if (name && (node.type === 'function_expression' || node.type === 'generator_function')) {
+                declare(scope, name, { kind: 'function', value: node, immutable: true });
+            }
+            const parameters = node.childForFieldName('parameters');
+            const single = node.childForFieldName('parameter');
+            for (const parameter of parameters?.namedChildren ?? (single ? [single] : [])) {
+                const pattern = parameter.childForFieldName('pattern') ?? parameter;
+                const type = parameter.childForFieldName('type')?.namedChildren[0];
+                for (const bindingName of patternNames(pattern)) {
+                    declare(scope, bindingName, {
+                        kind: 'parameter',
+                        ...(pattern.type === 'identifier' && type ? { type } : {}),
+                    });
+                }
+            }
+        }
+        else if (node.type === 'import_statement') {
+            const source = node.childForFieldName('source');
+            const sdk = source !== null && SDK_MODULES.has(plainString(source) ?? '');
+            const typeOnly = node.children.some((child) => child.type === 'type');
+            const clause = node.namedChildren.find((child) => child.type === 'import_clause');
+            for (const child of clause?.namedChildren ?? []) {
+                if (child.type === 'identifier')
+                    declare(scope, child);
+                else if (child.type === 'namespace_import') {
+                    const local = child.namedChildren[0];
+                    if (local)
+                        declare(scope, local, { kind: sdk ? 'sdk-namespace' : 'unknown', typeOnly });
+                }
+                else if (child.type === 'named_imports') {
+                    for (const specifier of child.namedChildren) {
+                        const imported = specifier.childForFieldName('name');
+                        const local = specifier.childForFieldName('alias') ?? imported;
+                        if (local)
+                            declare(scope, local, {
+                                kind: sdk && imported?.text === 'McpServer' ? 'sdk' : 'unknown',
+                                typeOnly: typeOnly || specifier.children.some((part) => part.type === 'type'),
+                            });
+                    }
+                }
+            }
+        }
+        else if (node.type === 'variable_declarator') {
+            if (name) {
+                const target = node.parent?.type === 'variable_declaration' ? variableScope(scope) : scope;
+                for (const bindingName of patternNames(name)) {
+                    declare(target, bindingName, {
+                        kind: 'variable',
+                        immutable: node.parent?.childForFieldName('kind')?.type === 'const',
+                        ...(name.type === 'identifier'
+                            ? { value: node.childForFieldName('value') ?? undefined }
+                            : {}),
+                    });
+                }
+            }
+        }
+        else if (node.type === 'catch_clause') {
+            const parameter = node.childForFieldName('parameter');
+            if (parameter)
+                for (const bindingName of patternNames(parameter))
+                    declare(scope, bindingName);
+        }
+        else if (node.type === 'for_in_statement') {
+            const left = node.childForFieldName('left');
+            const kind = node.childForFieldName('kind');
+            if (left && kind) {
+                const target = kind.type === 'var' ? variableScope(scope) : scope;
+                for (const bindingName of patternNames(left))
+                    declare(target, bindingName);
+            }
+            else if (left)
+                writes.push(left);
+        }
+        else if (node.type === 'type_parameter') {
+            if (name)
+                declare(scope, name);
+        }
+        if (node.type === 'call_expression')
+            calls.push(node);
+        if (node.type === 'assignment_expression' || node.type === 'augmented_assignment_expression') {
+            const left = node.childForFieldName('left');
+            if (left)
+                writes.push(left);
+        }
+        else if (node.type === 'update_expression' ||
+            (node.type === 'unary_expression' && node.children.some((child) => child.type === 'delete'))) {
+            const argument = node.childForFieldName('argument');
+            if (argument)
+                writes.push(argument);
+        }
+        for (let index = node.namedChildCount - 1; index >= 0; index--) {
+            pending.push({ node: node.namedChild(index), scope });
+        }
+    }
+    // Resolve writes after declarations so later declarations also shadow outer names.
+    while (writes.length) {
+        let target = writes.pop();
+        const scope = scopes.get(target.id);
+        const members = [];
+        while (target.type === 'member_expression' || target.type === 'subscript_expression') {
+            const object = target.childForFieldName('object');
+            if (!object)
+                break;
+            const property = target.childForFieldName('property');
+            const index = target.childForFieldName('index');
+            members.push(property ? propertyName(property) : index ? plainString(index) : null);
+            target = object;
+        }
+        // Nested member targets must pass the same guard as direct property writes.
+        for (const name of patternNames(target, (member) => writes.push(member))) {
+            const binding = lookup(scope, name.text);
+            // Lifecycle callbacks and other known properties do not replace the receiver
+            // or its registration methods. Unknown keys and constructor mutations remain unsafe.
+            if (binding?.kind !== 'sdk' &&
+                binding?.kind !== 'sdk-namespace' &&
+                members.length > 0 &&
+                members.every((member) => member !== null) &&
+                !['tool', 'registerTool', '__proto__'].includes(members[members.length - 1]))
+                continue;
+            if (binding)
+                binding.invalid = true;
+        }
+    }
+    return { scopes, calls };
+}
+function sdkBinding(node, scope, forType = false) {
+    let kind = 'sdk';
+    if (node.type === (forType ? 'nested_type_identifier' : 'member_expression')) {
+        const namespace = node.childForFieldName(forType ? 'module' : 'object');
+        const member = node.childForFieldName(forType ? 'name' : 'property');
+        if (namespace?.type !== 'identifier' || member?.text !== 'McpServer')
+            return false;
+        node = namespace;
+        kind = 'sdk-namespace';
+    }
+    if (node.type !== 'identifier' && node.type !== 'type_identifier')
+        return false;
+    const binding = lookup(scope, node.text);
+    return binding?.kind === kind && !binding.invalid && (forType || !binding.typeOnly);
+}
+function sdkReceiver(node, scope, scopes) {
+    if (node.type !== 'identifier')
+        return false;
+    const binding = lookup(scope, node.text);
+    if (!binding || binding.invalid)
+        return false;
+    if (binding.kind === 'parameter' && binding.type) {
+        return sdkBinding(binding.type, binding.scope, true);
+    }
+    const value = binding.value;
+    if (binding.kind !== 'variable' || value?.type !== 'new_expression')
+        return false;
+    if (value.endIndex > node.startIndex && variableScope(binding.scope) === variableScope(scope))
+        return false;
+    const constructor = value.childForFieldName('constructor');
+    return constructor !== null && sdkBinding(constructor, scopes.get(value.id));
+}
+/** An unknown later property can replace description; a later explicit property restores proof. */
+function descriptionFromConfig(config) {
+    let description = '';
+    if (config.type !== 'object')
+        return description;
+    for (const child of config.namedChildren) {
+        if (child.type === 'comment')
+            continue;
+        const key = child.childForFieldName('key') ?? child.childForFieldName('name');
+        const name = child.type === 'shorthand_property_identifier' ? child.text : key && propertyName(key);
+        if (child.type === 'pair' && name === 'description') {
+            const value = child.childForFieldName('value');
+            description = value ? (plainString(value) ?? '') : '';
+        }
+        else if (!name || name === 'description') {
+            description = '';
+        }
+    }
+    return description;
+}
+function handlerNodeId(node, scope, callableBindings) {
+    if (node.type !== 'identifier')
+        return undefined;
+    const binding = lookup(scope, node.text);
+    if (!binding || binding.invalid)
+        return undefined;
+    if (binding.kind === 'variable') {
+        const value = binding.value;
+        if (!binding.immutable ||
+            !value ||
+            (value.type !== 'arrow_function' && value.type !== 'function_expression'))
+            return undefined;
+        if (value.endIndex > node.startIndex && variableScope(binding.scope) === variableScope(scope))
+            return undefined;
+    }
+    else if (binding.kind !== 'function')
+        return undefined;
+    return callableBindings?.get(binding.name.id);
+}
+/** Direct SDK registrations only; no wrapper, alias-chain or runtime-value inference. */
+export function extractToolDefinitions(tree, filePath, lineOffset = 0, callableBindings) {
+    // Ordinary files need no lexical walk; every supported receiver originates here.
+    const importsSdk = tree.rootNode.namedChildren.some((node) => {
+        if (node.type !== 'import_statement')
+            return false;
+        const source = node.childForFieldName('source');
+        return source !== null && SDK_MODULES.has(plainString(source) ?? '');
+    });
+    if (!importsSdk)
+        return [];
+    const { scopes, calls } = collectBindings(tree.rootNode);
+    const definitions = [];
+    for (const call of calls) {
+        const callee = call.childForFieldName('function');
+        if (call.hasError || callee?.type !== 'member_expression')
+            continue;
+        const receiver = callee.childForFieldName('object');
+        const method = callee.childForFieldName('property');
+        if (!receiver ||
+            method?.type !== 'property_identifier' ||
+            (method.text !== 'registerTool' && method.text !== 'tool') ||
+            !sdkReceiver(receiver, scopes.get(call.id), scopes))
+            continue;
+        const args = call
+            .childForFieldName('arguments')
+            ?.namedChildren.filter((child) => child.type !== 'comment') ?? [];
+        if (args.some((arg) => arg.type === 'spread_element'))
+            continue;
+        if (method.text === 'registerTool' ? args.length !== 3 : args.length < 2 || args.length > 5)
+            continue;
+        const toolName = plainString(args[0]);
+        if (toolName === null)
+            continue;
+        const description = method.text === 'registerTool'
+            ? descriptionFromConfig(args[1])
+            : args.length > 2
+                ? (plainString(args[1]) ?? '')
+                : '';
+        const handler = handlerNodeId(args[args.length - 1], scopes.get(call.id), callableBindings);
+        definitions.push({
+            filePath,
+            toolName,
+            description,
+            lineNumber: call.startPosition.row + 1 + lineOffset,
+            ...(handler !== undefined ? { handlerNodeId: handler } : {}),
+            allowFileFallback: false,
+        });
+    }
+    return definitions;
+}

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

@@ -77,6 +77,7 @@ import { extractDataRouteTableRoutes } from '../route-extractors/data-route-tabl
 import { extractNestRoutes } from '../route-extractors/nest.js';
 import { extractTrpcRoutes, shouldScanForTrpcRoutes } from '../route-extractors/trpc.js';
 import { extractConvexEndpointProperties } from './typescript/convex-endpoint-metadata.js';
+import { extractToolDefinitions } from './typescript/tool-definitions.js';
 const extractJsTsRoutes = (...args) => [
     ...extractDispatchGuardRoutes(...args),
     ...extractDataRouteTableRoutes(...args),
@@ -415,6 +416,7 @@ export const typescriptProvider = defineLanguage({
     // Content-based (not AST): tRPC procedure routers are scanned from source text.
     // Path-gate lives here (language provider), not in the shared parse worker.
     extractTextRoutes: extractJsTsTextRoutes,
+    extractToolDefinitions,
 });
 export const javascriptProvider = defineLanguage({
     id: SupportedLanguages.JavaScript,
@@ -494,4 +496,5 @@ export const javascriptProvider = defineLanguage({
     extractDecoratorRoutes: extractJsTsRoutes,
     // Content-based (not AST): tRPC procedure routers are scanned from source text.
     extractTextRoutes: extractJsTsTextRoutes,
+    extractToolDefinitions,
 });

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

@@ -261,6 +261,8 @@ export const processesPhase = {
             const toolsByHandlerId = new Map();
             const toolsWithoutHandlerByFile = new Map();
             for (const td of toolDefs) {
+                if (!td.handlerNodeId && td.allowFileFallback === false)
+                    continue;
                 const key = td.handlerNodeId ?? td.filePath;
                 const targetMap = td.handlerNodeId ? toolsByHandlerId : toolsWithoutHandlerByFile;
                 let list = targetMap.get(key);

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

@@ -14,6 +14,7 @@ export interface ToolDef {
     filePath: string;
     description: string;
     handlerNodeId?: string;
+    allowFileFallback?: false;
 }
 export interface ToolsOutput {
     toolDefs: ToolDef[];

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

@@ -30,6 +30,7 @@ export const toolsPhase = {
                 filePath: td.filePath,
                 description: td.description,
                 ...(handlerNodeId !== undefined ? { handlerNodeId } : {}),
+                ...(td.allowFileFallback === false ? { allowFileFallback: false } : {}),
             });
         }
         // TS tool definition arrays — require inputSchema nearby

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

@@ -196,6 +196,8 @@ export interface ExtractedToolDef {
     description: string;
     lineNumber: number;
     handlerNodeId?: string;
+    /** Unresolved registrations must not inherit unrelated same-file flows. */
+    allowFileFallback?: false;
 }
 export interface ExtractedORMQuery {
     filePath: string;

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

@@ -1087,6 +1087,7 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
         // node id → graph node id for classes THIS file's capture loop materialized.
         // Keyed by in-memory AST identity (never persisted); filled below.
         const classOwnersByNodeId = new Map();
+        const callableBindings = new Map();
         // #2687: ONE pass over `matches` yields both suppression sets — the
         // definition-name claims by rank (callable > Property > value), so the dedup
         // below cannot depend on tree-sitter's match order, and the concrete-typedef
@@ -2328,6 +2329,10 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
                     ...(returnShapeProperty ? { fromReturnShape: true, isDetail: true } : {}),
                 }),
             });
+            // Keep actual emitted identities; providers must not reconstruct graph IDs.
+            if (nameNode && (nodeLabel === 'Function' || nodeLabel === 'Method')) {
+                callableBindings.set(nameNode.id, nodeId);
+            }
             // enclosingClassId already computed above (before nodeId generation)
             const ownerId = enclosingClassId ?? objectLiteralOwnerInfo?.ownerId;
             result.symbols.push({
@@ -2419,6 +2424,22 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
                 }
             }
         }
+        if (provider.extractToolDefinitions) {
+            // Distinct lexical declarations can share a graph ID (for example, sibling
+            // block-scoped functions). Such IDs cannot prove which handler owns a tool.
+            const seenCallableIds = new Set();
+            const ambiguousCallableIds = new Set();
+            for (const nodeId of callableBindings.values()) {
+                if (seenCallableIds.has(nodeId))
+                    ambiguousCallableIds.add(nodeId);
+                seenCallableIds.add(nodeId);
+            }
+            for (const [bindingId, nodeId] of callableBindings) {
+                if (ambiguousCallableIds.has(nodeId))
+                    callableBindings.delete(bindingId);
+            }
+            result.toolDefs.push(...provider.extractToolDefinitions(tree, file.path, lineOffset, callableBindings));
+        }
         // Extract framework routes via provider detection (e.g., Laravel routes.php)
         if (provider.isRouteFile?.(file.path)) {
             const extractedRoutes = extractLaravelRoutes(tree, file.path);

package/dist/storage/parse-cache.js

@@ -817,7 +817,14 @@ import { copyV8CacheIfPresent, tryLoadV8Cache, writeV8CacheFile } from './v8-sid
 // `handlerReceiver` hint. Warm v123 Go worker results carry no routes.
 // v125 (#3402): Go route hints now honor lexical declarations and captured writes;
 // namespace imports retain whether their local name comes from the package clause.
-const SCHEMA_BUMP = 125;
+// v126 (#3446): SDK positional tool registrations now emit tool definitions,
+// exact handler identities, and an opt-out from unrelated file-level flows.
+// Warm v125 worker results omit these definitions and must be re-extracted.
+// v127 (#3450): Destructured member writes invalidate SDK registration evidence.
+// Warm v126 worker results can retain false tools after a method replacement.
+// v128 (#3450): SDK namespace imports now prove positional tool receivers.
+// Warm v127 worker results omit these definitions and must be re-extracted.
+const SCHEMA_BUMP = 128;
 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.13-rc.66",
+  "version": "1.6.13-rc.67",
   "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",