gitnexus 1.6.8-rc.34 → 1.6.8-rc.35

package/dist/cli/help-i18n.js

@@ -28,6 +28,7 @@ const COMMAND_DESCRIPTION_KEYS = {
     cypher: 'help.command.cypher.description',
     'detect-changes': 'help.command.detectChanges.description',
     check: 'help.command.check.description',
+    trace: 'help.command.trace.description',
     'eval-server': 'help.command.evalServer.description',
     group: 'help.command.group.description',
     'group create': 'help.command.group.create.description',
@@ -127,6 +128,14 @@ const OPTION_DESCRIPTION_KEYS = {
     'check|--json': 'help.option.json',
     'check|-r, --repo <name>': 'help.option.repo.target',
     'check|--branch <name>': 'help.option.branch',
+    'trace|--from-uid <uid>': 'help.option.trace.fromUid',
+    'trace|--from-file <path>': 'help.option.trace.fromFile',
+    'trace|--to-uid <uid>': 'help.option.trace.toUid',
+    'trace|--to-file <path>': 'help.option.trace.toFile',
+    'trace|--depth <n>': 'help.option.trace.depth',
+    'trace|--include-tests': 'help.option.trace.includeTests',
+    'trace|-r, --repo <name>': 'help.option.repo.target',
+    'trace|--branch <name>': 'help.option.branch',
     'eval-server|-p, --port <port>': 'help.option.port',
     'eval-server|--host <host>': 'help.option.evalServer.host',
     'eval-server|--idle-timeout <seconds>': 'help.option.evalServer.idleTimeout',

package/dist/cli/i18n/en.d.ts

@@ -51,6 +51,7 @@ export declare const en: {
     readonly 'tool.usage.query': "Usage: gitnexus query <search_query>";
     readonly 'tool.usage.context': "Usage: gitnexus context <symbol_name> [--uid <uid>] [--file <path>]";
     readonly 'tool.usage.impact': "Usage: gitnexus impact <symbol_name> [--uid <uid>] [--file <path>] [--kind <kind>] [--direction upstream|downstream]";
+    readonly 'tool.usage.trace': "Usage: gitnexus trace <from> <to> [--from-uid <uid>] [--to-uid <uid>] [--depth <n>]";
     readonly 'tool.usage.cypher': "Usage: gitnexus cypher <cypher_query>";
     readonly 'tool.warn.unknownKind': "--kind '{{kind}}' is not a known symbol kind (e.g. Function, Class, Method); it will not narrow the result.";
     readonly 'tool.detectChanges.noChanges': "No changes detected.";
@@ -124,6 +125,7 @@ export declare const en: {
     readonly 'help.command.query.description': "Search the knowledge graph for execution flows related to a concept";
     readonly 'help.command.context.description': "360-degree view of a code symbol: callers, callees, processes";
     readonly 'help.command.impact.description': "Blast radius analysis: what breaks if you change a symbol";
+    readonly 'help.command.trace.description': "Find the shortest directed path between two symbols (call + class-member edges)";
     readonly 'help.command.cypher.description': "Execute raw Cypher query against the knowledge graph";
     readonly 'help.command.detectChanges.description': "Map git diff hunks to indexed symbols and affected execution flows";
     readonly 'help.command.check.description': "Run structural checks against the indexed graph";
@@ -203,6 +205,12 @@ export declare const en: {
     readonly 'help.option.impact.limit': "Max symbols per depth level (default: 100)";
     readonly 'help.option.impact.offset': "Skip N symbols per depth level for pagination";
     readonly 'help.option.impact.summaryOnly': "Return counts and risk only, omit symbol list";
+    readonly 'help.option.trace.fromUid': "Source symbol UID (zero-ambiguity lookup)";
+    readonly 'help.option.trace.fromFile': "Source file path to disambiguate common names";
+    readonly 'help.option.trace.toUid': "Target symbol UID (zero-ambiguity lookup)";
+    readonly 'help.option.trace.toFile': "Target file path to disambiguate common names";
+    readonly 'help.option.trace.depth': "Max path length in hops (default: 10)";
+    readonly 'help.option.trace.includeTests': "Traverse through test-file symbols (default: false)";
     readonly 'help.option.detectChanges.scope': "What to analyze: unstaged, staged, all, or compare";
     readonly 'help.option.detectChanges.baseRef': "Branch/commit for compare scope (e.g. main)";
     readonly 'help.option.check.cycles': "Detect circular imports and fail when any are found";

package/dist/cli/i18n/en.js

@@ -51,6 +51,7 @@ export const en = {
     'tool.usage.query': 'Usage: gitnexus query <search_query>',
     'tool.usage.context': 'Usage: gitnexus context <symbol_name> [--uid <uid>] [--file <path>]',
     'tool.usage.impact': 'Usage: gitnexus impact <symbol_name> [--uid <uid>] [--file <path>] [--kind <kind>] [--direction upstream|downstream]',
+    'tool.usage.trace': 'Usage: gitnexus trace <from> <to> [--from-uid <uid>] [--to-uid <uid>] [--depth <n>]',
     'tool.usage.cypher': 'Usage: gitnexus cypher <cypher_query>',
     'tool.warn.unknownKind': "--kind '{{kind}}' is not a known symbol kind (e.g. Function, Class, Method); it will not narrow the result.",
     'tool.detectChanges.noChanges': 'No changes detected.',
@@ -124,6 +125,7 @@ export const en = {
     'help.command.query.description': 'Search the knowledge graph for execution flows related to a concept',
     'help.command.context.description': '360-degree view of a code symbol: callers, callees, processes',
     'help.command.impact.description': 'Blast radius analysis: what breaks if you change a symbol',
+    'help.command.trace.description': 'Find the shortest directed path between two symbols (call + class-member edges)',
     'help.command.cypher.description': 'Execute raw Cypher query against the knowledge graph',
     'help.command.detectChanges.description': 'Map git diff hunks to indexed symbols and affected execution flows',
     'help.command.check.description': 'Run structural checks against the indexed graph',
@@ -203,6 +205,12 @@ export const en = {
     'help.option.impact.limit': 'Max symbols per depth level (default: 100)',
     'help.option.impact.offset': 'Skip N symbols per depth level for pagination',
     'help.option.impact.summaryOnly': 'Return counts and risk only, omit symbol list',
+    'help.option.trace.fromUid': 'Source symbol UID (zero-ambiguity lookup)',
+    'help.option.trace.fromFile': 'Source file path to disambiguate common names',
+    'help.option.trace.toUid': 'Target symbol UID (zero-ambiguity lookup)',
+    'help.option.trace.toFile': 'Target file path to disambiguate common names',
+    'help.option.trace.depth': 'Max path length in hops (default: 10)',
+    'help.option.trace.includeTests': 'Traverse through test-file symbols (default: false)',
     'help.option.detectChanges.scope': 'What to analyze: unstaged, staged, all, or compare',
     'help.option.detectChanges.baseRef': 'Branch/commit for compare scope (e.g. main)',
     'help.option.check.cycles': 'Detect circular imports and fail when any are found',

package/dist/cli/i18n/resources.d.ts

@@ -52,6 +52,7 @@ export declare const cliResources: {
         readonly 'tool.usage.query': "Usage: gitnexus query <search_query>";
         readonly 'tool.usage.context': "Usage: gitnexus context <symbol_name> [--uid <uid>] [--file <path>]";
         readonly 'tool.usage.impact': "Usage: gitnexus impact <symbol_name> [--uid <uid>] [--file <path>] [--kind <kind>] [--direction upstream|downstream]";
+        readonly 'tool.usage.trace': "Usage: gitnexus trace <from> <to> [--from-uid <uid>] [--to-uid <uid>] [--depth <n>]";
         readonly 'tool.usage.cypher': "Usage: gitnexus cypher <cypher_query>";
         readonly 'tool.warn.unknownKind': "--kind '{{kind}}' is not a known symbol kind (e.g. Function, Class, Method); it will not narrow the result.";
         readonly 'tool.detectChanges.noChanges': "No changes detected.";
@@ -125,6 +126,7 @@ export declare const cliResources: {
         readonly 'help.command.query.description': "Search the knowledge graph for execution flows related to a concept";
         readonly 'help.command.context.description': "360-degree view of a code symbol: callers, callees, processes";
         readonly 'help.command.impact.description': "Blast radius analysis: what breaks if you change a symbol";
+        readonly 'help.command.trace.description': "Find the shortest directed path between two symbols (call + class-member edges)";
         readonly 'help.command.cypher.description': "Execute raw Cypher query against the knowledge graph";
         readonly 'help.command.detectChanges.description': "Map git diff hunks to indexed symbols and affected execution flows";
         readonly 'help.command.check.description': "Run structural checks against the indexed graph";
@@ -204,6 +206,12 @@ export declare const cliResources: {
         readonly 'help.option.impact.limit': "Max symbols per depth level (default: 100)";
         readonly 'help.option.impact.offset': "Skip N symbols per depth level for pagination";
         readonly 'help.option.impact.summaryOnly': "Return counts and risk only, omit symbol list";
+        readonly 'help.option.trace.fromUid': "Source symbol UID (zero-ambiguity lookup)";
+        readonly 'help.option.trace.fromFile': "Source file path to disambiguate common names";
+        readonly 'help.option.trace.toUid': "Target symbol UID (zero-ambiguity lookup)";
+        readonly 'help.option.trace.toFile': "Target file path to disambiguate common names";
+        readonly 'help.option.trace.depth': "Max path length in hops (default: 10)";
+        readonly 'help.option.trace.includeTests': "Traverse through test-file symbols (default: false)";
         readonly 'help.option.detectChanges.scope': "What to analyze: unstaged, staged, all, or compare";
         readonly 'help.option.detectChanges.baseRef': "Branch/commit for compare scope (e.g. main)";
         readonly 'help.option.check.cycles': "Detect circular imports and fail when any are found";
@@ -282,6 +290,7 @@ export declare const cliResources: {
         'tool.usage.query': string;
         'tool.usage.context': string;
         'tool.usage.impact': string;
+        'tool.usage.trace': string;
         'tool.usage.cypher': string;
         'tool.warn.unknownKind': string;
         'tool.detectChanges.noChanges': string;
@@ -355,6 +364,7 @@ export declare const cliResources: {
         'help.command.query.description': string;
         'help.command.context.description': string;
         'help.command.impact.description': string;
+        'help.command.trace.description': string;
         'help.command.cypher.description': string;
         'help.command.detectChanges.description': string;
         'help.command.check.description': string;
@@ -434,6 +444,12 @@ export declare const cliResources: {
         'help.option.impact.limit': string;
         'help.option.impact.offset': string;
         'help.option.impact.summaryOnly': string;
+        'help.option.trace.fromUid': string;
+        'help.option.trace.fromFile': string;
+        'help.option.trace.toUid': string;
+        'help.option.trace.toFile': string;
+        'help.option.trace.depth': string;
+        'help.option.trace.includeTests': string;
         'help.option.detectChanges.scope': string;
         'help.option.detectChanges.baseRef': string;
         'help.option.check.cycles': string;

package/dist/cli/i18n/zh-CN.d.ts

@@ -51,6 +51,7 @@ export declare const zhCN: {
     'tool.usage.query': string;
     'tool.usage.context': string;
     'tool.usage.impact': string;
+    'tool.usage.trace': string;
     'tool.usage.cypher': string;
     'tool.warn.unknownKind': string;
     'tool.detectChanges.noChanges': string;
@@ -124,6 +125,7 @@ export declare const zhCN: {
     'help.command.query.description': string;
     'help.command.context.description': string;
     'help.command.impact.description': string;
+    'help.command.trace.description': string;
     'help.command.cypher.description': string;
     'help.command.detectChanges.description': string;
     'help.command.check.description': string;
@@ -203,6 +205,12 @@ export declare const zhCN: {
     'help.option.impact.limit': string;
     'help.option.impact.offset': string;
     'help.option.impact.summaryOnly': string;
+    'help.option.trace.fromUid': string;
+    'help.option.trace.fromFile': string;
+    'help.option.trace.toUid': string;
+    'help.option.trace.toFile': string;
+    'help.option.trace.depth': string;
+    'help.option.trace.includeTests': string;
     'help.option.detectChanges.scope': string;
     'help.option.detectChanges.baseRef': string;
     'help.option.check.cycles': string;

package/dist/cli/i18n/zh-CN.js

@@ -51,6 +51,7 @@ export const zhCN = {
     'tool.usage.query': '用法：gitnexus query <搜索词>',
     'tool.usage.context': '用法：gitnexus context <符号名> [--uid <uid>] [--file <路径>]',
     'tool.usage.impact': '用法：gitnexus impact <符号名> [--uid <uid>] [--file <路径>] [--kind <类型>] [--direction upstream|downstream]',
+    'tool.usage.trace': '用法：gitnexus trace <起点> <终点> [--from-uid <uid>] [--to-uid <uid>] [--depth <n>]',
     'tool.usage.cypher': '用法：gitnexus cypher <Cypher 查询>',
     'tool.warn.unknownKind': "--kind '{{kind}}' 不是已知的符号类型（如 Function、Class、Method），不会用于缩小结果范围。",
     'tool.detectChanges.noChanges': '未检测到变更。',
@@ -124,6 +125,7 @@ export const zhCN = {
     'help.command.query.description': '搜索知识图谱中与概念相关的执行流程',
     'help.command.context.description': '查看代码符号的 360 度视图：调用者、被调用者、流程',
     'help.command.impact.description': '影响面分析：修改符号会影响什么',
+    'help.command.trace.description': '查找两个符号之间的最短有向路径（调用与类成员边）',
     'help.command.cypher.description': '对知识图谱执行原始 Cypher 查询',
     'help.command.detectChanges.description': '将 git diff hunk 映射到已索引符号和受影响执行流程',
     'help.command.check.description': '对已索引图谱运行结构检查',
@@ -203,6 +205,12 @@ export const zhCN = {
     'help.option.impact.limit': '每层深度最大符号数（默认：100）',
     'help.option.impact.offset': '每层深度跳过 N 个符号（分页用）',
     'help.option.impact.summaryOnly': '仅返回计数和风险等级，省略符号列表',
+    'help.option.trace.fromUid': '源符号 UID（零歧义查找）',
+    'help.option.trace.fromFile': '源文件路径，用于消除常见名称歧义',
+    'help.option.trace.toUid': '目标符号 UID（零歧义查找）',
+    'help.option.trace.toFile': '目标文件路径，用于消除常见名称歧义',
+    'help.option.trace.depth': '最大路径跳数（默认：10）',
+    'help.option.trace.includeTests': '遍历时包含测试文件中的符号（默认：false）',
     'help.option.detectChanges.scope': '分析范围：unstaged、staged、all 或 compare',
     'help.option.detectChanges.baseRef': 'compare 范围的分支/提交（例如 main）',
     'help.option.check.cycles': '检测循环导入，并在发现循环时失败',

package/dist/cli/index.js

@@ -235,6 +235,18 @@ program
     .option('--offset <n>', 'Skip N symbols per depth level for pagination')
     .option('--summary-only', 'Return counts and risk only, omit symbol list')
     .action(createLbugLazyAction(() => import('./tool.js'), 'impactCommand'));
+program
+    .command('trace <from> <to>')
+    .description('Find the shortest directed path between two symbols (call + class-member edges)')
+    .option('--from-uid <uid>', 'Source symbol UID (zero-ambiguity)')
+    .option('--from-file <path>', 'Source file path hint')
+    .option('--to-uid <uid>', 'Target symbol UID (zero-ambiguity)')
+    .option('--to-file <path>', 'Target file path hint')
+    .option('--depth <n>', 'Max path length in hops (default: 10)')
+    .option('--include-tests', 'Include test files in results')
+    .option('-r, --repo <name>', 'Target repository')
+    .option('--branch <name>', 'Scope to a specific branch index')
+    .action(createLbugLazyAction(() => import('./tool.js'), 'traceCommand'));
 program
     .command('cypher <query>')
     .description('Execute raw Cypher query against the knowledge graph')

package/dist/cli/tool.d.ts

@@ -58,3 +58,13 @@ export declare function checkCommand(options?: {
     repo?: string;
     branch?: string;
 }): Promise<void>;
+export declare function traceCommand(from?: string, to?: string, options?: {
+    fromUid?: string;
+    fromFile?: string;
+    toUid?: string;
+    toFile?: string;
+    depth?: string;
+    repo?: string;
+    branch?: string;
+    includeTests?: boolean;
+}): Promise<void>;

package/dist/cli/tool.js

@@ -207,3 +207,48 @@ export async function checkCommand(options) {
         process.exitCode = 1;
     }
 }
+export async function traceCommand(from, to, options) {
+    if (options?.fromUid?.startsWith('--') || options?.toUid?.startsWith('--')) {
+        cliErrorKey('tool.usage.trace');
+        process.exit(1);
+    }
+    if ((!from?.trim() && !options?.fromUid) || (!to?.trim() && !options?.toUid)) {
+        cliErrorKey('tool.usage.trace');
+        process.exit(1);
+    }
+    // Reject a non-numeric / non-positive --depth up front rather than forwarding
+    // NaN (which the backend would silently treat as the default).
+    if (options?.depth !== undefined) {
+        const parsedDepth = Number(options.depth);
+        if (!Number.isInteger(parsedDepth) || parsedDepth < 1) {
+            cliErrorKey('tool.usage.trace');
+            process.exit(1);
+        }
+    }
+    try {
+        const backend = await getBackend();
+        const result = await backend.callTool('trace', {
+            from: from || undefined,
+            from_uid: options?.fromUid,
+            from_file: options?.fromFile,
+            to: to || undefined,
+            to_uid: options?.toUid,
+            to_file: options?.toFile,
+            maxDepth: options?.depth ? parseInt(options.depth, 10) : undefined,
+            includeTests: options?.includeTests ?? false,
+            repo: options?.repo,
+            branch: options?.branch,
+        });
+        output(result);
+    }
+    catch (err) {
+        output({
+            status: 'error',
+            error: (err instanceof Error ? err.message : String(err)) || 'Trace analysis failed unexpectedly',
+            from: { name: from },
+            to: { name: to },
+            suggestion: 'Try gitnexus context <symbol> to see connections, or check if an interface bridges them.',
+        });
+        process.exit(1);
+    }
+}

package/dist/mcp/local/local-backend.d.ts

@@ -511,6 +511,8 @@ export declare class LocalBackend {
      * Additional refs found via text search are tagged "text_search" (lower confidence).
      */
     private rename;
+    private trace;
+    private _traceImpl;
     private impact;
     private _impactImpl;
     /**

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

@@ -1101,6 +1101,8 @@ export class LocalBackend {
                 return this.toolMap(repo, params);
             case 'api_impact':
                 return this.apiImpact(repo, params);
+            case 'trace':
+                return this.trace(repo, params);
             default:
                 throw new Error(`Unknown tool: ${method}`);
         }
@@ -3261,6 +3263,208 @@ export class LocalBackend {
             applied: !dry_run,
         };
     }
+    async trace(repo, params) {
+        try {
+            return await this._traceImpl(repo, params);
+        }
+        catch (err) {
+            return {
+                status: 'error',
+                error: (err instanceof Error ? err.message : String(err)) || 'Trace analysis failed',
+                from: { name: params.from },
+                to: { name: params.to },
+                suggestion: 'The graph query failed — try gitnexus context <symbol> to see connections, ' +
+                    'or check if an interface bridges them.',
+                ...(isWalCorruptionError(err) ? { recoverySuggestion: WAL_RECOVERY_SUGGESTION } : {}),
+            };
+        }
+    }
+    async _traceImpl(repo, params) {
+        await this.ensureInitialized(repo);
+        // resolveSymbolCandidates feeds `from`/`to` into string operations
+        // (e.g. name.includes), so a non-string param would surface a low-level
+        // "x.includes is not a function". Reject it with a clear message instead.
+        const isStringOrAbsent = (v) => v === undefined || typeof v === 'string';
+        if (!isStringOrAbsent(params.from) ||
+            !isStringOrAbsent(params.to) ||
+            !isStringOrAbsent(params.from_uid) ||
+            !isStringOrAbsent(params.to_uid)) {
+            return {
+                status: 'error',
+                error: "'from', 'to', and their *_uid variants must be strings.",
+                suggestion: 'Pass symbol names or UIDs as strings, e.g. trace from="A" to="B".',
+            };
+        }
+        const fromOutcome = await this.resolveSymbolCandidates(repo, { uid: params.from_uid, name: params.from }, { file_path: params.from_file });
+        if (fromOutcome.kind === 'not_found') {
+            return {
+                status: 'not_found',
+                error: `Source symbol '${params.from_uid ?? params.from}' not found.`,
+                suggestion: 'Check the symbol name or use --from-uid for zero-ambiguity.',
+            };
+        }
+        if (fromOutcome.kind === 'ambiguous') {
+            return {
+                status: 'ambiguous',
+                role: 'from',
+                message: `Found ${fromOutcome.candidates.length} symbols matching '${params.from}'. Disambiguate with --from-uid.`,
+                candidates: fromOutcome.candidates,
+            };
+        }
+        const toOutcome = await this.resolveSymbolCandidates(repo, { uid: params.to_uid, name: params.to }, { file_path: params.to_file });
+        if (toOutcome.kind === 'not_found') {
+            return {
+                status: 'not_found',
+                error: `Target symbol '${params.to_uid ?? params.to}' not found.`,
+                suggestion: 'Check the symbol name or use --to-uid for zero-ambiguity.',
+            };
+        }
+        if (toOutcome.kind === 'ambiguous') {
+            return {
+                status: 'ambiguous',
+                role: 'to',
+                message: `Found ${toOutcome.candidates.length} symbols matching '${params.to}'. Disambiguate with --to-uid.`,
+                candidates: toOutcome.candidates,
+            };
+        }
+        const fromSym = fromOutcome.symbol;
+        const toSym = toOutcome.symbol;
+        if (fromSym.id === toSym.id) {
+            return {
+                status: 'ok',
+                from: { name: fromSym.name, filePath: fromSym.filePath, startLine: fromSym.startLine },
+                to: { name: toSym.name, filePath: toSym.filePath, startLine: toSym.startLine },
+                hopCount: 0,
+                hops: [{ name: fromSym.name, filePath: fromSym.filePath, startLine: fromSym.startLine }],
+                edges: [],
+            };
+        }
+        // Sanitize maxDepth at the real boundary: the MCP inputSchema's
+        // minimum/maximum is advisory only (callTool is reachable directly), so a
+        // caller can pass 0, a negative, NaN, or a non-integer. `??` does NOT
+        // recover 0/NaN, and Math.min has no lower bound — left unguarded, any of
+        // those makes the BFS loop run zero iterations and return a false no_path.
+        const DEFAULT_TRACE_DEPTH = 10;
+        const MAX_TRACE_DEPTH = 30;
+        const requestedDepth = Number.isInteger(params.maxDepth) && params.maxDepth > 0
+            ? params.maxDepth
+            : DEFAULT_TRACE_DEPTH;
+        const maxDepth = Math.min(requestedDepth, MAX_TRACE_DEPTH);
+        const includeTests = params.includeTests ?? false;
+        // Traversal vocabulary: CALLS for actual calls, HAS_METHOD so a class-rooted
+        // trace can descend into its methods. Not "calls only" — per-hop edge type is
+        // surfaced in edges[] so containment hops stay distinguishable.
+        const TRAVERSAL_EDGE_TYPES = ['CALLS', 'HAS_METHOD'];
+        // Bound the traversal so a high-fanout hub (a logger/util reached by many
+        // symbols) can't materialize an unbounded frontier. Per-level rows are
+        // capped and the total visited set is capped; either cap sets `truncated`
+        // so a resulting no_path is never reported as if the graph was exhausted.
+        const PER_NODE_FANOUT_CAP = 200;
+        const ABS_ROW_CAP = 5000;
+        const MAX_VISITED = 50000;
+        let truncated = false;
+        const visited = new Set([fromSym.id]);
+        let frontier = [fromSym.id];
+        const parent = new Map();
+        let found = false;
+        // The last node discovered at the deepest reached level — surfaced as
+        // `furthest` in the no_path response to hint where the chain breaks.
+        let lastReached = null;
+        let reachedDepth = 0;
+        for (let depth = 1; depth <= maxDepth && frontier.length > 0 && !found; depth++) {
+            const nextFrontier = [];
+            // LadybugDB/Kuzu does not support a parameterized LIMIT, so the cap is
+            // interpolated (it is a derived integer, not user input).
+            const rowCap = Math.min(frontier.length * PER_NODE_FANOUT_CAP, ABS_ROW_CAP);
+            const rows = await executeParameterized(repo.lbugPath, `MATCH (n)-[r:CodeRelation]->(m)
+         WHERE n.id IN $frontierIds AND r.type IN $edgeTypes
+         RETURN n.id AS sourceId, m.id AS id, m.name AS name, labels(m)[0] AS type,
+                m.filePath AS filePath, m.startLine AS startLine,
+                r.type AS edgeType, r.confidence AS confidence
+         LIMIT ${rowCap}`, { frontierIds: frontier, edgeTypes: TRAVERSAL_EDGE_TYPES });
+            // A clipped level may have dropped a node that lies on the only shortest
+            // path, so any subsequent no_path is not authoritative.
+            if (rows.length >= rowCap)
+                truncated = true;
+            for (const row of rows) {
+                // Decode once. The `?? row[N]` fallback handles LadybugDB tuple-mode
+                // returns; the positional indices mirror the RETURN column order above.
+                const nodeId = (row.id ?? row[1]);
+                const sourceId = (row.sourceId ?? row[0]);
+                const name = (row.name ?? row[2]);
+                const filePath = (row.filePath ?? row[4]);
+                const startLine = (row.startLine ?? row[5]);
+                const edgeType = (row.edgeType ?? row[6]);
+                const storedConfidence = row.confidence ?? row[7];
+                const confidence = typeof storedConfidence === 'number' && storedConfidence > 0
+                    ? storedConfidence
+                    : confidenceForRelType(edgeType);
+                // Match the explicitly-requested target before the test-file filter.
+                // resolveSymbolCandidates does not exclude test-file symbols, so a
+                // target (or a required hop) that lives in a test file would otherwise
+                // be dropped by the includeTests guard below and produce a false
+                // no_path even when a direct edge exists.
+                if (nodeId === toSym.id) {
+                    parent.set(nodeId, { from: sourceId, name, filePath, startLine, edgeType, confidence });
+                    found = true;
+                    break;
+                }
+                // Skip non-target nodes that live in test files unless includeTests.
+                if (!includeTests && isTestFilePath(filePath))
+                    continue;
+                if (!visited.has(nodeId)) {
+                    visited.add(nodeId);
+                    parent.set(nodeId, { from: sourceId, name, filePath, startLine, edgeType, confidence });
+                    nextFrontier.push(nodeId);
+                    lastReached = { name, filePath, startLine };
+                    reachedDepth = depth;
+                }
+            }
+            frontier = nextFrontier;
+            if (visited.size >= MAX_VISITED) {
+                truncated = true;
+                break;
+            }
+        }
+        if (found) {
+            const path = [];
+            const edges = [];
+            let current = toSym.id;
+            while (current !== fromSym.id) {
+                const info = parent.get(current);
+                path.unshift({ name: info.name, filePath: info.filePath, startLine: info.startLine });
+                edges.unshift({ relType: info.edgeType, confidence: info.confidence });
+                current = info.from;
+            }
+            path.unshift({
+                name: fromSym.name,
+                filePath: fromSym.filePath,
+                startLine: fromSym.startLine,
+            });
+            return {
+                status: 'ok',
+                from: { name: fromSym.name, filePath: fromSym.filePath, startLine: fromSym.startLine },
+                to: { name: toSym.name, filePath: toSym.filePath, startLine: toSym.startLine },
+                hopCount: edges.length,
+                hops: path,
+                edges,
+            };
+        }
+        return {
+            status: 'no_path',
+            from: { name: fromSym.name, filePath: fromSym.filePath, startLine: fromSym.startLine },
+            to: { name: toSym.name, filePath: toSym.filePath, startLine: toSym.startLine },
+            furthest: lastReached ? { ...lastReached, depth: reachedDepth } : null,
+            ...(truncated ? { truncated: true } : {}),
+            suggestion: truncated
+                ? 'Search was truncated at a traversal cap before exhausting the graph — a path ' +
+                    'may still exist. Narrow the search (a lower --depth, or trace from a more ' +
+                    'specific symbol), or use gitnexus context <symbol> to inspect connections.'
+                : 'No directed path found. The call chain likely breaks at dynamic dispatch, ' +
+                    'reflection, or an external API boundary. Try gitnexus context <symbol> to see ' +
+                    "both symbols' connections, or check if an interface/abstraction bridges them.",
+        };
+    }
     async impact(repo, params) {
         try {
             return await this._impactImpl(repo, params);

package/dist/mcp/tools.js

@@ -703,6 +703,45 @@ WHEN TO USE: After changing group.yaml or re-indexing member repos.`,
             required: ['name'],
         },
     },
+    {
+        name: 'trace',
+        description: `Find the shortest directed path between two symbols over call and class-member edges.
+
+WHEN TO USE: Debugging "how does A reach B?" — answers in one call what would take 3-8 manual context/impact hops. Shows the exact chain with file:line positions plus a per-hop edge type and confidence.
+
+Traverses CALLS edges plus HAS_METHOD (class → member) edges, so a trace can descend from a class into its methods. Each hop's edge type is reported in edges[], so call hops and containment hops remain distinguishable.
+
+Returns: ordered hops with file:line, and an aligned edges[] of edge type + confidence. When no path exists, reports the furthest reachable node so you know where the chain breaks (and truncated: true if a traversal cap was hit first).`,
+        annotations: READ_ONLY_TOOL_ANNOTATIONS,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                from: { type: 'string', description: 'Source symbol name' },
+                from_uid: { type: 'string', description: 'Source symbol UID (zero-ambiguity)' },
+                from_file: { type: 'string', description: 'Source file path hint for disambiguation' },
+                to: { type: 'string', description: 'Target symbol name' },
+                to_uid: { type: 'string', description: 'Target symbol UID (zero-ambiguity)' },
+                to_file: { type: 'string', description: 'Target file path hint for disambiguation' },
+                maxDepth: {
+                    type: 'number',
+                    description: 'Maximum path length in hops (default: 10)',
+                    default: 10,
+                    minimum: 1,
+                    maximum: 30,
+                },
+                includeTests: {
+                    type: 'boolean',
+                    description: 'Include test-file symbols in traversal (default: false)',
+                    default: false,
+                },
+                repo: {
+                    type: 'string',
+                    description: 'Repository name or path. Omit if only one repo is indexed.',
+                },
+            },
+            required: [],
+        },
+    },
 ];
 /**
  * Per-repo tools that accept an optional `branch` scope (#2106). Single source
@@ -725,6 +764,7 @@ const BRANCH_SCOPED_TOOLS = new Set([
     'tool_map',
     'shape_check',
     'api_impact',
+    'trace',
 ]);
 for (const tool of GITNEXUS_TOOLS) {
     if (!BRANCH_SCOPED_TOOLS.has(tool.name))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.8-rc.34",
+  "version": "1.6.8-rc.35",
   "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/skills/gitnexus-debugging.md

@@ -45,6 +45,7 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
 | Intermittent failure | `context` → look for external calls, async deps            |
 | Performance issue    | `context` → find symbols with many callers (hot paths)     |
 | Recent regression    | `detect_changes` to see what your changes affect           |
+| "How does A reach B?" | `trace` between the two symbols — shortest call chain in one call |
 
 ## Tools
 
@@ -72,6 +73,17 @@ MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "valid
 RETURN [n IN nodes(path) | n.name] AS chain
 ```
 
+**trace** — shortest call chain between two symbols ("how does A reach B?"), one call instead of chaining `context` hops:
+
+```
+trace({ from: "processCheckout", to: "fetchRates" })
+→ status: ok, hopCount: 3
+→ hops: processCheckout → validatePayment → verifyCard → fetchRates
+→ edges: CALLS (1.0), CALLS (0.95), CALLS (1.0)
+```
+
+When no path exists, `trace` reports the furthest reachable node — exactly where the chain breaks (dynamic dispatch, reflection, or an external boundary).
+
 ## Example: "Payment endpoint returns 500 intermittently"
 
 ```

package/skills/gitnexus-guide.md

@@ -35,6 +35,7 @@ For any task involving code understanding, debugging, impact analysis, or refact
 | `query`          | Process-grouped code intelligence — execution flows related to a concept |
 | `context`        | 360-degree symbol view — categorized refs, processes it participates in  |
 | `impact`         | Symbol blast radius — what breaks at depth 1/2/3 with confidence         |
+| `trace`          | Shortest path between two symbols — "how does A reach B?" in one call     |
 | `detect_changes` | Git-diff impact — what do your current changes affect                    |
 | `rename`         | Multi-file coordinated rename with confidence-tagged edits               |
 | `cypher`         | Raw graph queries (read `gitnexus://repo/{name}/schema` first)           |
@@ -93,6 +94,16 @@ A repo indexed without `--pdg` returns a clear "no taint layer" note. Caveats: f
 
 A repo indexed without `--pdg` returns a "no PDG layer" note (or "status unknown" when the layer can't be confirmed). Intra-procedural only — cross-function flow is taint's domain (`explain`). The raw CDG/REACHING_DEF edges are also queryable via `cypher`. See the `gitnexus-pdg-query` skill for the full query surface.
 
+### Shortest path between two symbols (`trace`)
+
+`trace` answers "how does A reach B?" in one call — the shortest directed path over `CALLS` (plus `HAS_METHOD`, so a class-rooted trace descends into its methods) instead of chaining 3–8 `context`/`impact` hops by hand.
+
+- `trace { from: "validateUser", to: "executeQuery" }` — shortest path between two symbols.
+- Disambiguate common names with `from_uid`/`to_uid` (zero-ambiguity) or `from_file`/`to_file`; an ambiguous name returns ranked candidates.
+- `maxDepth` (default 10, max 30) bounds the search; `includeTests` (default false) lets the traversal pass through test-file symbols.
+
+Returns ordered `hops` (each `{ name, filePath, startLine }`) and an aligned `edges[]` of `{ relType, confidence }`, so call hops and containment (`HAS_METHOD`) hops stay distinguishable. When no path exists it reports the **furthest** reachable node (where the chain breaks) and sets `truncated: true` if a traversal cap was hit first. Every result carries a `status`: `ok` / `no_path` / `ambiguous` / `not_found` / `error`.
+
 ## Resources Reference
 
 Lightweight reads (~100-500 tokens) for navigation: