gitnexus 1.6.2 → 1.6.3-rc.10

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

@@ -18,6 +18,7 @@ import { listRegisteredRepos, cleanupOldKuzuFiles, } from '../../storage/repo-ma
 import { GroupService } from '../../core/group/service.js';
 import { collectBestChunks } from '../../core/embeddings/types.js';
 import { EMBEDDING_TABLE_NAME, EMBEDDING_INDEX_NAME } from '../../core/lbug/schema.js';
+import { PhaseTimer } from '../../core/search/phase-timer.js';
 // AI context generation is CLI-only (gitnexus analyze)
 // import { generateAIContextFiles } from '../../cli/ai-context.js';
 /**
@@ -134,6 +135,25 @@ function logQueryError(context, err) {
     const msg = err instanceof Error ? err.message : String(err);
     console.error(`GitNexus [${context}]: ${msg}`);
 }
+/**
+ * Structured per-query latency log for production aggregation (#553).
+ *
+ * Emitted on stderr — NOT stdout — because the MCP stdio transport uses
+ * stdout exclusively for JSON-RPC responses (#324), and the CLI e2e test
+ * `tool output goes to stdout via fd 1` asserts that stdout parses cleanly
+ * as JSON. Any `console.log` from inside a tool handler would corrupt the
+ * protocol. Matches the existing `logQueryError` convention above, which
+ * uses stderr for the same reason.
+ *
+ * The `GitNexus [query:timing] …` prefix keeps lines greppable; the
+ * `phases` payload is JSON so log-scraping pipelines can parse it
+ * without custom format knowledge.
+ */
+function logQueryTiming(query, phases) {
+    const totalMs = phases.wall ?? Object.values(phases).reduce((a, b) => a + b, 0);
+    const truncated = query.length > 80 ? `${query.slice(0, 80)}…` : query;
+    console.error(`GitNexus [query:timing] query=${JSON.stringify(truncated)} totalMs=${totalMs} phases=${JSON.stringify(phases)}`);
+}
 export class LocalBackend {
     repos = new Map();
     contextCache = new Map();
@@ -449,15 +469,26 @@ export class LocalBackend {
         const maxSymbolsPerProcess = params.max_symbols || 10;
         const includeContent = params.include_content ?? false;
         const searchQuery = params.query.trim();
-        // Step 1: Run hybrid search to get matching symbols
+        // Per-phase timing instrumentation (#553). Records wall time for each
+        // observable sub-step of the search pipeline so production latency can
+        // be aggregated offline for Pareto analysis and bottleneck detection.
+        // Overhead is <0.1 ms per phase; the timer is passive and never alters
+        // query behaviour.
+        const timer = new PhaseTimer();
+        const wallStart = performance.now();
+        // Step 1: Run hybrid search to get matching symbols. BM25 and vector
+        // search run concurrently via Promise.all — use `timer.time()` for
+        // each so both get independent wall-time records without fighting
+        // over a single `current` phase slot.
         const searchLimit = processLimit * maxSymbolsPerProcess; // fetch enough raw results
         const [bm25SearchResult, semanticResults] = await Promise.all([
-            this.bm25Search(repo, searchQuery, searchLimit),
-            this.semanticSearch(repo, searchQuery, searchLimit),
+            timer.time('bm25', this.bm25Search(repo, searchQuery, searchLimit)),
+            timer.time('vector', this.semanticSearch(repo, searchQuery, searchLimit)),
         ]);
         const bm25Results = bm25SearchResult.results;
         const ftsUsed = bm25SearchResult.ftsUsed;
         // Merge via reciprocal rank fusion
+        timer.start('merge');
         const scoreMap = new Map();
         for (let i = 0; i < bm25Results.length; i++) {
             const result = bm25Results[i];
@@ -486,7 +517,9 @@ export class LocalBackend {
         const merged = Array.from(scoreMap.entries())
             .sort((a, b) => b[1].score - a[1].score)
             .slice(0, searchLimit);
+        timer.stop(); // merge
         // Step 2: For each match with a nodeId, trace to process(es)
+        timer.start('symbol_lookup');
         const processMap = new Map();
         const definitions = []; // standalone symbols not in any process
         for (const [_, item] of merged) {
@@ -590,7 +623,9 @@ export class LocalBackend {
                 }
             }
         }
+        timer.stop(); // symbol_lookup
         // Step 3: Rank processes by aggregate score + internal cohesion boost
+        timer.start('ranking');
         const rankedProcesses = Array.from(processMap.values())
             .map((p) => ({
             ...p,
@@ -598,7 +633,9 @@ export class LocalBackend {
         }))
             .sort((a, b) => b.priority - a.priority)
             .slice(0, processLimit);
+        timer.stop(); // ranking
         // Step 4: Build response
+        timer.start('formatting');
         const processes = rankedProcesses.map((p) => ({
             id: p.id,
             summary: p.heuristicLabel || p.label,
@@ -619,10 +656,18 @@ export class LocalBackend {
             seen.add(s.id);
             return true;
         });
+        timer.stop(); // formatting
+        // End-to-end wall time — deliberately a separate mark so callers can
+        // compare sum(phases) vs wall to see how much Promise.all concurrency
+        // saved. Must come before summary() so it's included.
+        timer.mark('wall', performance.now() - wallStart);
+        const timing = timer.summary();
+        logQueryTiming(searchQuery, timing);
         return {
             processes,
             process_symbols: dedupedSymbols,
             definitions: definitions.slice(0, 20), // cap standalone definitions
+            timing,
             ...(!ftsUsed && {
                 warning: 'FTS extension unavailable - keyword search degraded. Run: gitnexus analyze --force to rebuild indexes.',
             }),
@@ -908,108 +953,268 @@ export class LocalBackend {
         return result;
     }
     /**
-     * Context tool — 360-degree symbol view with categorized refs.
-     * Disambiguation when multiple symbols share a name.
-     * UID-based direct lookup. No cluster in output.
+     * Patch the `type` field on candidates whose `labels(n)[0]` projection
+     * came back empty — a known LadybugDB behaviour for several node types.
+     *
+     * Uses one scoped UNION query across the five priority labels rather
+     * than per-candidate round-trips, so cost is a single DB call regardless
+     * of how many candidates need enrichment. No-op when every candidate
+     * already has a non-empty type.
+     *
+     * Failures are swallowed: label enrichment is an optimisation for
+     * downstream scoring and #480 Class/Interface BFS seeding; if it fails
+     * the symbol still resolves, just without the kind-priority bonus.
      */
-    async context(repo, params) {
-        await this.ensureInitialized(repo.id);
-        const { name, uid, file_path, include_content } = params;
-        if (!name && !uid) {
-            return { error: 'Either "name" or "uid" parameter is required.' };
-        }
-        // Step 1: Find the symbol
-        let symbols;
-        if (uid) {
-            symbols = await executeParameterized(repo.id, `
-        MATCH (n {id: $uid})
-        RETURN n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine${include_content ? ', n.content AS content' : ''}
-        LIMIT 1
-      `, { uid });
-        }
-        else {
-            const isQualified = name.includes('/') || name.includes(':');
-            let whereClause;
-            let queryParams;
-            if (file_path) {
-                whereClause = `WHERE n.name = $symName AND n.filePath CONTAINS $filePath`;
-                queryParams = { symName: name, filePath: file_path };
-            }
-            else if (isQualified) {
-                whereClause = `WHERE n.id = $symName OR n.name = $symName`;
-                queryParams = { symName: name };
+    async enrichCandidateLabels(repo, candidates) {
+        const ids = candidates.filter((c) => c.type === '' && c.id).map((c) => c.id);
+        if (ids.length === 0)
+            return;
+        try {
+            const rows = await executeParameterized(repo.id, `
+        MATCH (n:\`Class\`) WHERE n.id IN $ids RETURN n.id AS id, 'Class' AS label
+        UNION ALL
+        MATCH (n:\`Interface\`) WHERE n.id IN $ids RETURN n.id AS id, 'Interface' AS label
+        UNION ALL
+        MATCH (n:\`Function\`) WHERE n.id IN $ids RETURN n.id AS id, 'Function' AS label
+        UNION ALL
+        MATCH (n:\`Method\`) WHERE n.id IN $ids RETURN n.id AS id, 'Method' AS label
+        UNION ALL
+        MATCH (n:\`Constructor\`) WHERE n.id IN $ids RETURN n.id AS id, 'Constructor' AS label
+        `, { ids });
+            const labelById = new Map();
+            for (const r of rows) {
+                const id = (r.id ?? r[0]);
+                const label = (r.label ?? r[1]);
+                if (id && label && !labelById.has(id))
+                    labelById.set(id, label);
             }
-            else {
-                whereClause = `WHERE n.name = $symName`;
-                queryParams = { symName: name };
+            for (const c of candidates) {
+                if (c.type === '' && labelById.has(c.id))
+                    c.type = labelById.get(c.id);
             }
-            symbols = await executeParameterized(repo.id, `
-        MATCH (n) ${whereClause}
-        RETURN n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine${include_content ? ', n.content AS content' : ''}
-        LIMIT 10
-      `, queryParams);
         }
-        if (symbols.length === 0) {
-            return { error: `Symbol '${name || uid}' not found` };
+        catch {
+            /* best-effort — downstream resolvers still work without the label */
         }
-        // Step 2: Disambiguation
-        // When multiple nodes share the same name (e.g. a Java Class and its
-        // Constructor both named 'SessionTracker'), prefer the Class node so
-        // context() returns the semantically meaningful result rather than
-        // triggering ambiguous disambiguation (#480).
-        // labels(n)[0] returns empty string in LadybugDB, so we resolve the
-        // preferred node by re-querying with explicit label filters, scoped to
-        // the candidate IDs already in symbols.
-        //
-        // Guard: only attempt Class-preference when at least one candidate has an
-        // empty/unknown type (LadybugDB limitation) or is a Constructor — meaning
-        // the ambiguity may be a Class/Constructor name collision rather than two
-        // genuinely distinct symbols (e.g. two Functions in different files).
-        //
-        // resolvedLabel is set here and threaded to Step 3 to avoid a redundant
-        // classCheck round-trip later.
-        let resolvedLabel = '';
-        if (symbols.length > 1 && !uid) {
-            const hasAmbiguousType = symbols.some((s) => {
-                const t = s.type || s[2] || '';
-                return t === '' || t === 'Constructor';
-            });
-            if (hasAmbiguousType) {
-                const candidateIds = symbols.map((s) => s.id || s[0]).filter(Boolean);
-                const PREFER_LABELS = ['Class', 'Interface'];
-                let preferred = null;
-                for (const label of PREFER_LABELS) {
-                    const match = await executeParameterized(repo.id, `
-            MATCH (n:\`${label}\`) WHERE n.id IN $candidateIds RETURN n.id AS id LIMIT 1
-          `, { candidateIds }).catch(() => []);
-                    if (match.length > 0) {
-                        preferred = symbols.find((s) => (s.id || s[0]) === (match[0].id || match[0][0]));
+    }
+    /**
+     * Score a symbol candidate for disambiguation ranking.
+     *
+     * Deterministic, no DB round-trip:
+     *   - base 0.50
+     *   - +0.40 when file_path hint matches (substring, case-insensitive)
+     *   - +0.20 when kind hint exactly matches the candidate's kind
+     *   - when no kind hint, a small priority bonus (Class > Interface >
+     *     Function > Method > Constructor) to preserve the intuition that
+     *     class-level names are usually what the user wanted.
+     *
+     * Capped at 1.0. Intentionally simple and inspectable — a future v2 can
+     * plug in BM25/embedding signals here without changing the surrounding
+     * resolver shape.
+     */
+    scoreCandidate(c, hints) {
+        let s = 0.5;
+        if (hints.file_path && c.filePath && typeof c.filePath === 'string') {
+            if (c.filePath.toLowerCase().includes(hints.file_path.toLowerCase())) {
+                s += 0.4;
+            }
+        }
+        if (hints.kind && c.kind === hints.kind) {
+            s += 0.2;
+        }
+        if (!hints.kind) {
+            const priority = {
+                Class: 5,
+                Interface: 4,
+                Function: 3,
+                Method: 2,
+                Constructor: 1,
+            };
+            s += (priority[c.kind] ?? 0) * 0.02;
+        }
+        return Math.min(1.0, s);
+    }
+    /**
+     * Shared symbol resolver used by `context` and `impact`.
+     *
+     * Returns one of:
+     *   - `{ kind: 'ok', symbol, resolvedLabel }` — single confident match
+     *     (either direct UID, only one candidate after filtering, Class/
+     *     Constructor collapse, or a top-scoring candidate with a clear gap
+     *     to the runner-up).
+     *   - `{ kind: 'ambiguous', candidates }` — multiple viable matches,
+     *     sorted by score desc. Each candidate carries a relevance score.
+     *   - `{ kind: 'not_found' }` — no matches at all.
+     *
+     * Preserves the #480 Class/Constructor preference: when the only
+     * ambiguity is between a Class and its own Constructor (same name,
+     * same filePath), the Class wins silently.
+     */
+    async resolveSymbolCandidates(repo, query, hints) {
+        const { uid, name, include_content } = query;
+        const selectClause = `n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine${include_content ? ', n.content AS content' : ''}`;
+        // Direct UID — zero-ambiguity path.
+        if (uid) {
+            const rows = await executeParameterized(repo.id, `MATCH (n {id: $uid}) RETURN ${selectClause} LIMIT 1`, { uid });
+            if (rows.length === 0)
+                return { kind: 'not_found' };
+            const r = rows[0];
+            const symbol = {
+                id: (r.id ?? r[0]),
+                name: (r.name ?? r[1]),
+                type: (r.type ?? r[2] ?? ''),
+                filePath: (r.filePath ?? r[3]),
+                startLine: (r.startLine ?? r[4]),
+                endLine: (r.endLine ?? r[5]),
+                ...(include_content ? { content: (r.content ?? r[6]) } : {}),
+            };
+            // Same LadybugDB label-enrichment as the name-based path: a UID
+            // pointing at a Class must still surface `type: 'Class'` so impact's
+            // Class/Interface BFS seed fires. No-op when type is already set.
+            await this.enrichCandidateLabels(repo, [symbol]);
+            return { kind: 'ok', symbol, resolvedLabel: symbol.type };
+        }
+        if (!name)
+            return { kind: 'not_found' };
+        const isQualified = name.includes('/') || name.includes(':');
+        let whereClause;
+        const queryParams = { symName: name };
+        if (hints.file_path) {
+            whereClause = `WHERE n.name = $symName AND n.filePath CONTAINS $filePath`;
+            queryParams.filePath = hints.file_path;
+        }
+        else if (isQualified) {
+            whereClause = `WHERE n.id = $symName OR n.name = $symName`;
+        }
+        else {
+            whereClause = `WHERE n.name = $symName`;
+        }
+        // LIMIT 20 (was 10) — scoring is the point now, so give the ranker
+        // headroom instead of arbitrary truncation.
+        const rows = await executeParameterized(repo.id, `MATCH (n) ${whereClause} RETURN ${selectClause} LIMIT 20`, queryParams);
+        if (rows.length === 0)
+            return { kind: 'not_found' };
+        // Normalise row shape across object / tuple returns from LadybugDB.
+        const normalized = rows.map((r) => ({
+            id: (r.id ?? r[0]),
+            name: (r.name ?? r[1]),
+            type: (r.type ?? r[2] ?? ''),
+            filePath: (r.filePath ?? r[3]),
+            startLine: (r.startLine ?? r[4]),
+            endLine: (r.endLine ?? r[5]),
+            ...(include_content ? { content: (r.content ?? r[6]) } : {}),
+        }));
+        // Enrich labels for any candidates where `labels(n)[0]` came back empty.
+        // LadybugDB returns an empty string for that projection on certain node
+        // types (notably Class), which left downstream consumers (impact's
+        // Class/Interface BFS seed, the kind-priority scoring bonus) unable to
+        // distinguish a Class target from "unknown kind". One scoped UNION
+        // across the five priority labels patches the type in-place without
+        // per-candidate round-trips.
+        await this.enrichCandidateLabels(repo, normalized);
+        // Preserve #480 Class/Constructor collapse: if we have exactly one
+        // Class (or Interface) candidate and one Constructor sharing name +
+        // filePath, fold into the Class. This used to require a follow-up
+        // label query because LadybugDB sometimes returns an empty labels()[0]
+        // for Class nodes — enrichment above handles the empty-type case, but
+        // the `type === 'Constructor'` gate still correctly triggers when a
+        // Class and its Constructor share the name.
+        if (!hints.kind && normalized.length > 1) {
+            const ambiguousType = normalized.some((s) => s.type === '' || s.type === 'Constructor');
+            if (ambiguousType) {
+                const candidateIds = normalized.map((s) => s.id).filter(Boolean);
+                for (const label of ['Class', 'Interface']) {
+                    const labelRows = await executeParameterized(repo.id, `MATCH (n:\`${label}\`) WHERE n.id IN $candidateIds RETURN n.id AS id LIMIT 1`, { candidateIds }).catch(() => []);
+                    if (labelRows.length > 0) {
+                        const preferredId = labelRows[0].id ?? labelRows[0][0];
+                        const preferred = normalized.find((s) => s.id === preferredId);
                         if (preferred) {
-                            resolvedLabel = label;
-                            break;
+                            return {
+                                kind: 'ok',
+                                symbol: preferred,
+                                resolvedLabel: label,
+                            };
                         }
                     }
                 }
-                if (preferred)
-                    symbols = [preferred];
             }
         }
-        if (symbols.length > 1 && !uid) {
+        if (normalized.length === 1) {
+            return {
+                kind: 'ok',
+                symbol: normalized[0],
+                resolvedLabel: '',
+            };
+        }
+        // Score, sort desc, stable tiebreak on shorter filePath then lex uid.
+        const scored = normalized.map((s) => ({
+            ...s,
+            score: this.scoreCandidate({ kind: s.type, filePath: s.filePath || '' }, hints),
+        }));
+        scored.sort((a, b) => {
+            if (b.score !== a.score)
+                return b.score - a.score;
+            const fpA = (a.filePath || '').length;
+            const fpB = (b.filePath || '').length;
+            if (fpA !== fpB)
+                return fpA - fpB;
+            return String(a.id).localeCompare(String(b.id));
+        });
+        // Confident single-result: top score ≥ 0.95 AND beats runner-up by a
+        // clear margin. This lets a very strong file_path/kind hint resolve
+        // cleanly instead of forcing the caller through a disambiguation
+        // round-trip.
+        //
+        // The gap threshold uses `> 0.09` rather than `>= 0.10` on purpose:
+        // IEEE754 addition of the scoring terms (0.50 + 0.40 + 0.20 - 0.90
+        // yields 0.09999999999999998, not exactly 0.10) would otherwise break
+        // the comparison for legitimate "top is 1.00, runner is 0.90" cases.
+        // The intent is a clearly-dominant winner; 0.09 is a large enough
+        // margin to mean that unambiguously.
+        //
+        // The `scored.length >= 2` guard is defensive. The `normalized.length === 1`
+        // early return above already handles the single-candidate path, so in
+        // practice `scored` always has at least two elements by the time we get
+        // here — keeping the guard means changes to the upstream early-return
+        // logic cannot accidentally index out of bounds at `scored[1]`.
+        if (scored.length >= 2 && scored[0].score >= 0.95 && scored[0].score - scored[1].score > 0.09) {
+            return { kind: 'ok', symbol: scored[0], resolvedLabel: scored[0].type };
+        }
+        return { kind: 'ambiguous', candidates: scored };
+    }
+    /**
+     * Context tool — 360-degree symbol view with categorized refs.
+     * Disambiguation (ranked) when multiple symbols share a name.
+     * UID-based direct lookup. No cluster in output.
+     */
+    async context(repo, params) {
+        await this.ensureInitialized(repo.id);
+        const { name, uid, file_path, kind, include_content } = params;
+        if (!name && !uid) {
+            return { error: 'Either "name" or "uid" parameter is required.' };
+        }
+        const outcome = await this.resolveSymbolCandidates(repo, { uid, name, include_content }, { file_path, kind });
+        if (outcome.kind === 'not_found') {
+            return { error: `Symbol '${name || uid}' not found` };
+        }
+        if (outcome.kind === 'ambiguous') {
             return {
                 status: 'ambiguous',
-                message: `Found ${symbols.length} symbols matching '${name}'. Use uid or file_path to disambiguate.`,
-                candidates: symbols.map((s) => ({
-                    uid: s.id || s[0],
-                    name: s.name || s[1],
-                    kind: s.type || s[2],
-                    filePath: s.filePath || s[3],
-                    line: s.startLine || s[4],
+                message: `Found ${outcome.candidates.length} symbols matching '${name}'. Use uid, file_path, or kind to disambiguate.`,
+                candidates: outcome.candidates.map((c) => ({
+                    uid: c.id,
+                    name: c.name,
+                    kind: c.type,
+                    filePath: c.filePath,
+                    line: c.startLine,
+                    score: Number(c.score.toFixed(2)),
                 })),
             };
         }
         // Step 3: Build full context
-        const sym = symbols[0];
-        const symId = sym.id || sym[0];
+        const sym = outcome.symbol;
+        const resolvedLabel = outcome.resolvedLabel;
+        const symId = sym.id;
         // Categorized incoming refs
         const incomingRows = await executeParameterized(repo.id, `
       MATCH (caller)-[r:CodeRelation]->(n {id: $symId})
@@ -1287,7 +1492,14 @@ export class LocalBackend {
         }
         let diffOutput;
         try {
-            diffOutput = execFileSync('git', diffArgs, { cwd: repo.repoPath, encoding: 'utf-8' });
+            // maxBuffer raised from Node's 1MB default to 256MB to avoid ENOBUFS on
+            // repos with large unstaged/untracked diffs (e.g. unignored build folders).
+            // See issue: spawnSync git ENOBUFS in detect_changes(scope="unstaged").
+            diffOutput = execFileSync('git', diffArgs, {
+                cwd: repo.repoPath,
+                encoding: 'utf-8',
+                maxBuffer: 256 * 1024 * 1024,
+            });
         }
         catch (err) {
             return { error: `Git diff failed: ${err.message}` };
@@ -1502,6 +1714,8 @@ export class LocalBackend {
                 cwd: repo.repoPath,
                 encoding: 'utf-8',
                 timeout: 5000,
+                // Avoid ENOBUFS on large repos: rg -l can list many files.
+                maxBuffer: 256 * 1024 * 1024,
             });
             const files = output
                 .trim()
@@ -1608,54 +1822,50 @@ export class LocalBackend {
             ];
         const includeTests = params.includeTests ?? false;
         const minConfidence = params.minConfidence ?? 0;
-        // Resolve target by name, preferring Class/Interface over Constructor
-        // (fix #480: Java class and constructor share the same name).
-        // labels(n)[0] returns empty string in LadybugDB, so we use explicit
-        // label-typed sub-queries in a single UNION ordered by priority to avoid
-        // up to 6 serial round-trips for non-Class targets.
-        let sym = null;
-        let symType = '';
-        try {
-            const rows = await executeParameterized(repo.id, `
-        MATCH (n:\`Class\`) WHERE n.name = $targetName
-        RETURN n.id AS id, n.name AS name, n.filePath AS filePath, 0 AS priority LIMIT 1
-        UNION ALL
-        MATCH (n:\`Interface\`) WHERE n.name = $targetName
-        RETURN n.id AS id, n.name AS name, n.filePath AS filePath, 1 AS priority LIMIT 1
-        UNION ALL
-        MATCH (n:\`Function\`) WHERE n.name = $targetName
-        RETURN n.id AS id, n.name AS name, n.filePath AS filePath, 2 AS priority LIMIT 1
-        UNION ALL
-        MATCH (n:\`Method\`) WHERE n.name = $targetName
-        RETURN n.id AS id, n.name AS name, n.filePath AS filePath, 3 AS priority LIMIT 1
-        UNION ALL
-        MATCH (n:\`Constructor\`) WHERE n.name = $targetName
-        RETURN n.id AS id, n.name AS name, n.filePath AS filePath, 4 AS priority LIMIT 1
-      `, { targetName: target }).catch(() => []);
-            if (rows.length > 0) {
-                // Pick the row with the lowest priority value (Class wins over Constructor)
-                const best = rows.reduce((a, b) => (a.priority ?? a[3] ?? 99) <= (b.priority ?? b[3] ?? 99) ? a : b);
-                sym = best;
-                const priorityToLabel = ['Class', 'Interface', 'Function', 'Method', 'Constructor'];
-                symType = priorityToLabel[best.priority ?? best[3]] ?? '';
-            }
-        }
-        catch {
-            /* fall through to unlabeled match */
+        // Resolve target via the shared symbol resolver. When the caller passes
+        // target_uid we skip the name lookup entirely (zero-ambiguity). Otherwise
+        // we rank candidates (#470) and either proceed with a confident single
+        // match, or return a structured ambiguous response instead of silently
+        // picking the wrong symbol.
+        //
+        // The resolver preserves the #480 Class/Constructor preference heuristic:
+        // when a Class and its Constructor share name + filePath, the Class is
+        // selected silently.
+        const outcome = await this.resolveSymbolCandidates(repo, { uid: params.target_uid, name: target }, { file_path: params.file_path, kind: params.kind });
+        if (outcome.kind === 'not_found') {
+            const missing = params.target_uid ?? target;
+            return {
+                error: `Target '${missing}' not found`,
+                target: { name: target },
+                direction,
+                impactedCount: 0,
+                risk: 'UNKNOWN',
+            };
         }
-        // Fall back to unlabeled match for any other node type
-        if (!sym) {
-            const rows = await executeParameterized(repo.id, `
-        MATCH (n)
-        WHERE n.name = $targetName
-        RETURN n.id AS id, n.name AS name, n.filePath AS filePath
-        LIMIT 1
-      `, { targetName: target });
-            if (rows.length > 0)
-                sym = rows[0];
+        if (outcome.kind === 'ambiguous') {
+            return {
+                status: 'ambiguous',
+                message: `Found ${outcome.candidates.length} symbols matching '${target}'. Use target_uid, file_path, or kind to disambiguate.`,
+                target: { name: target },
+                direction,
+                impactedCount: 0,
+                risk: 'UNKNOWN',
+                candidates: outcome.candidates.map((c) => ({
+                    uid: c.id,
+                    name: c.name,
+                    kind: c.type,
+                    filePath: c.filePath,
+                    line: c.startLine,
+                    score: Number(c.score.toFixed(2)),
+                })),
+            };
         }
-        if (!sym)
-            return { error: `Target '${target}' not found` };
+        const sym = {
+            id: outcome.symbol.id,
+            name: outcome.symbol.name,
+            filePath: outcome.symbol.filePath,
+        };
+        const symType = outcome.resolvedLabel || outcome.symbol.type || '';
         return this._runImpactBFS(repo, sym, symType, direction, {
             maxDepth,
             relationTypes,

package/dist/mcp/tools.js

@@ -133,7 +133,7 @@ Shows categorized incoming/outgoing references (calls, imports, extends, impleme
 WHEN TO USE: After query() to understand a specific symbol in depth. When you need to know all callers, callees, and what execution flows a symbol participates in.
 AFTER THIS: Use impact() if planning changes, or READ gitnexus://repo/{name}/process/{processName} for full execution trace.
 
-Handles disambiguation: if multiple symbols share the same name, returns candidates for you to pick from. Use uid param for zero-ambiguity lookup from prior results.
+Handles disambiguation: if multiple symbols share the same name, returns ranked candidates (each with a relevance score) for you to pick from. Use uid for zero-ambiguity lookup, or narrow the search with file_path and/or kind hints.
 
 NOTE: ACCESSES edges (field read/write tracking) are included in context results with reason 'read' or 'write'. CALLS edges resolve through field access chains and method-call chains (e.g., user.address.getCity().save() produces CALLS edges at each step).`,
         inputSchema: {
@@ -145,6 +145,10 @@ NOTE: ACCESSES edges (field read/write tracking) are included in context results
                     description: 'Direct symbol UID from prior tool results (zero-ambiguity lookup)',
                 },
                 file_path: { type: 'string', description: 'File path to disambiguate common names' },
+                kind: {
+                    type: 'string',
+                    description: "Kind filter to disambiguate common names (e.g. 'Function', 'Class', 'Method', 'Interface', 'Constructor')",
+                },
                 include_content: {
                     type: 'boolean',
                     description: 'Include full symbol source code (default: false)',
@@ -244,16 +248,30 @@ Depth groups:
 
 TIP: Default traversal uses CALLS/IMPORTS/EXTENDS/IMPLEMENTS. For class members, include HAS_METHOD and HAS_PROPERTY in relationTypes. For field access analysis, include ACCESSES in relationTypes.
 
+Handles disambiguation: when multiple symbols share the target name, returns ranked candidates (each with a relevance score) instead of silently picking one. Use target_uid for zero-ambiguity lookup, or narrow with file_path and/or kind hints.
+
 EdgeType: CALLS, IMPORTS, EXTENDS, IMPLEMENTS, HAS_METHOD, HAS_PROPERTY, METHOD_OVERRIDES, METHOD_IMPLEMENTS, ACCESSES
 Confidence: 1.0 = certain, <0.8 = fuzzy match`,
         inputSchema: {
             type: 'object',
             properties: {
                 target: { type: 'string', description: 'Name of function, class, or file to analyze' },
+                target_uid: {
+                    type: 'string',
+                    description: 'Direct symbol UID from prior tool results (zero-ambiguity lookup, skips target resolution)',
+                },
                 direction: {
                     type: 'string',
                     description: 'upstream (what depends on this) or downstream (what this depends on)',
                 },
+                file_path: {
+                    type: 'string',
+                    description: 'File path hint to disambiguate common names',
+                },
+                kind: {
+                    type: 'string',
+                    description: "Kind filter to disambiguate common names (e.g. 'Function', 'Class', 'Method', 'Interface', 'Constructor')",
+                },
                 maxDepth: {
                     type: 'number',
                     description: 'Max relationship depth (default: 3)',