@veewo/gitnexus 1.4.8 → 1.4.9

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

@@ -13,6 +13,18 @@ import { type RegistryEntry } from '../../storage/repo-manager.js';
  * Matches common test file patterns across all supported languages.
  */
 export declare function isTestFilePath(filePath: string): boolean;
+export interface ExpandedSymbolCandidate {
+    id: string;
+    name: string;
+    type: string;
+    filePath: string;
+    startLine?: number;
+    endLine?: number;
+}
+export declare function filterBm25ResultsByScopePreset<T extends {
+    filePath?: string;
+}>(rows: T[], scopePreset?: string): T[];
+export declare function rankExpandedSymbolsForQuery(symbols: ExpandedSymbolCandidate[], query: string, limit?: number, scopePreset?: string): ExpandedSymbolCandidate[];
 export declare function mergeUnityBindings(baseBindings: ResolvedUnityBinding[], resolvedByPath: Map<string, ResolvedUnityBinding[]>): ResolvedUnityBinding[];
 export declare function mergeParityUnityBindings(baseNonLightweightBindings: ResolvedUnityBinding[], resolvedBindings: ResolvedUnityBinding[]): ResolvedUnityBinding[];
 export declare function attachUnityHydrationMeta(payload: UnityContextPayload, input: Pick<UnityHydrationMeta, 'requestedMode' | 'effectiveMode' | 'elapsedMs' | 'fallbackToCompact'> & {
@@ -97,6 +109,7 @@ export declare class LocalBackend {
         stats?: any;
     }>>;
     callTool(method: string, params: any): Promise<any>;
+    private unityUiTrace;
     /**
      * Query tool — process-grouped search.
      *

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

@@ -8,6 +8,7 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { initLbug, executeQuery, executeParameterized, closeLbug, isLbugReady } from '../core/lbug-adapter.js';
+import { runUnityUiTrace } from '../../core/unity/ui-trace.js';
 // Embedding imports are lazy (dynamic import) to avoid loading onnxruntime-node
 // at MCP server startup — crashes on unsupported Node ABI versions (#89)
 // git utilities available if needed
@@ -32,6 +33,120 @@ export function isTestFilePath(filePath) {
 function normalizePath(filePath) {
     return String(filePath || '').replace(/\\/g, '/');
 }
+const UNITY_GAMEPLAY_INCLUDE_PREFIXES = ['assets/'];
+const UNITY_GAMEPLAY_EXCLUDE_PREFIXES = [
+    'assets/plugins/',
+    'packages/',
+    'library/',
+    'projectsettings/',
+    'usersettings/',
+    'temp/',
+];
+const UNITY_PLUGIN_INTENT_TOKENS = new Set(['plugin', 'plugins', 'fmod', 'steam', 'crash', 'sdk', 'package']);
+const QUERY_STOP_WORDS = new Set([
+    'the', 'and', 'for', 'from', 'with', 'that', 'this', 'into',
+    'using', 'use', 'in', 'on', 'of', 'to', 'a', 'an',
+]);
+function tokenizeQuery(query) {
+    const normalized = String(query || '').toLowerCase();
+    return normalized
+        .split(/[^a-z0-9_]+/)
+        .map((token) => token.trim())
+        .filter((token) => token.length >= 2 && !QUERY_STOP_WORDS.has(token));
+}
+function matchesAnyPrefix(pathLower, prefixes) {
+    return prefixes.some((prefix) => pathLower.startsWith(prefix));
+}
+function isUnityPluginPath(filePath) {
+    const p = normalizePath(filePath).toLowerCase();
+    return p.startsWith('assets/plugins/') || p.startsWith('packages/') || p.startsWith('library/packagecache/');
+}
+function isUnityGameplayPath(filePath) {
+    const p = normalizePath(filePath).toLowerCase();
+    return p.startsWith('assets/') && !isUnityPluginPath(p);
+}
+function resolveQueryScopePreset(scopePreset) {
+    if (!scopePreset)
+        return undefined;
+    const normalized = String(scopePreset).trim().toLowerCase();
+    if (normalized === 'unity-gameplay' || normalized === 'unity-all') {
+        return normalized;
+    }
+    return undefined;
+}
+export function filterBm25ResultsByScopePreset(rows, scopePreset) {
+    const preset = resolveQueryScopePreset(scopePreset);
+    if (!preset || preset === 'unity-all')
+        return rows;
+    if (preset === 'unity-gameplay') {
+        return rows.filter((row) => {
+            const p = normalizePath(row.filePath || '').toLowerCase();
+            if (!p)
+                return false;
+            if (!matchesAnyPrefix(p, UNITY_GAMEPLAY_INCLUDE_PREFIXES))
+                return false;
+            if (matchesAnyPrefix(p, UNITY_GAMEPLAY_EXCLUDE_PREFIXES))
+                return false;
+            return true;
+        });
+    }
+    return rows;
+}
+function scoreExpandedSymbolForQuery(symbol, queryTokens, scopePreset) {
+    const name = String(symbol.name || '').toLowerCase();
+    const filePath = normalizePath(symbol.filePath || '').toLowerCase();
+    const pathText = filePath.replace(/[^a-z0-9_]+/g, ' ');
+    const hasPluginIntent = queryTokens.some((token) => UNITY_PLUGIN_INTENT_TOKENS.has(token));
+    let score = 0;
+    for (const token of queryTokens) {
+        if (name === token)
+            score += 8;
+        else if (name.includes(token))
+            score += 3;
+        if (pathText.includes(token))
+            score += 1;
+    }
+    if (queryTokens.length > 0) {
+        const fileName = filePath.split('/').pop() || '';
+        const fileNameNoExt = fileName.replace(/\.[a-z0-9]+$/i, '');
+        if (queryTokens.includes(fileNameNoExt)) {
+            score += 2;
+        }
+    }
+    if (isUnityPluginPath(filePath) && !hasPluginIntent) {
+        score -= scopePreset === 'unity-gameplay' ? 10 : 4;
+    }
+    else if (scopePreset === 'unity-gameplay' && isUnityGameplayPath(filePath)) {
+        score += 2;
+    }
+    return score;
+}
+export function rankExpandedSymbolsForQuery(symbols, query, limit = 3, scopePreset) {
+    const queryTokens = tokenizeQuery(query);
+    return [...symbols]
+        .sort((a, b) => {
+        const scoreDelta = scoreExpandedSymbolForQuery(b, queryTokens, scopePreset)
+            - scoreExpandedSymbolForQuery(a, queryTokens, scopePreset);
+        if (scoreDelta !== 0)
+            return scoreDelta;
+        const aLine = a.startLine ?? Number.MAX_SAFE_INTEGER;
+        const bLine = b.startLine ?? Number.MAX_SAFE_INTEGER;
+        if (aLine !== bLine)
+            return aLine - bLine;
+        return String(a.name || '').localeCompare(String(b.name || ''));
+    })
+        .slice(0, Math.max(1, limit));
+}
+function getUnityPathScoreMultiplier(filePath, queryTokens, scopePreset) {
+    const hasPluginIntent = queryTokens.some((token) => UNITY_PLUGIN_INTENT_TOKENS.has(token));
+    if (isUnityPluginPath(filePath) && !hasPluginIntent) {
+        return scopePreset === 'unity-gameplay' ? 0.1 : 0.45;
+    }
+    if (scopePreset === 'unity-gameplay' && isUnityGameplayPath(filePath)) {
+        return 1.15;
+    }
+    return 1;
+}
 function bindingIdentity(binding) {
     return [
         normalizePath(binding.resourcePath),
@@ -330,6 +445,8 @@ export class LocalBackend {
                 return this.context(repo, params);
             case 'impact':
                 return this.impact(repo, params);
+            case 'unity_ui_trace':
+                return this.unityUiTrace(repo, params);
             case 'detect_changes':
                 return this.detectChanges(repo, params);
             case 'rename':
@@ -345,6 +462,31 @@ export class LocalBackend {
                 throw new Error(`Unknown tool: ${method}`);
         }
     }
+    async unityUiTrace(repo, params) {
+        const target = String(params?.target || '').trim();
+        const goal = params?.goal;
+        const selectorMode = params?.selector_mode || 'balanced';
+        if (!target) {
+            return { error: 'target parameter is required and cannot be empty.' };
+        }
+        if (goal !== 'asset_refs' && goal !== 'template_refs' && goal !== 'selector_bindings') {
+            return { error: 'goal must be one of: asset_refs, template_refs, selector_bindings.' };
+        }
+        if (selectorMode !== 'strict' && selectorMode !== 'balanced') {
+            return { error: 'selector_mode must be one of: strict, balanced.' };
+        }
+        try {
+            return await runUnityUiTrace({
+                repoRoot: repo.repoPath,
+                target,
+                goal,
+                selectorMode,
+            });
+        }
+        catch (err) {
+            return { error: err?.message || 'unity_ui_trace failed' };
+        }
+    }
     // ─── Tool Implementations ────────────────────────────────────────
     /**
      * Query tool — process-grouped search.
@@ -366,7 +508,7 @@ export class LocalBackend {
         // Step 1: Run hybrid search to get matching symbols
         const searchLimit = processLimit * maxSymbolsPerProcess; // fetch enough raw results
         const [bm25Results, semanticResults] = await Promise.all([
-            this.bm25Search(repo, searchQuery, searchLimit),
+            this.bm25Search(repo, searchQuery, searchLimit, params.scope_preset),
             this.semanticSearch(repo, searchQuery, searchLimit),
         ]);
         // Merge via reciprocal rank fusion
@@ -540,8 +682,9 @@ export class LocalBackend {
     /**
      * BM25 keyword search helper - uses LadybugDB FTS for always-fresh results
      */
-    async bm25Search(repo, query, limit) {
+    async bm25Search(repo, query, limit, scopePreset) {
         const { searchFTSFromLbug } = await import('../../core/search/bm25-index.js');
+        const queryTokens = tokenizeQuery(query);
         let bm25Results;
         try {
             bm25Results = await searchFTSFromLbug(query, limit, repo.id);
@@ -550,26 +693,36 @@ export class LocalBackend {
             console.error('GitNexus: BM25/FTS search failed (FTS indexes may not exist) -', err.message);
             return [];
         }
+        bm25Results = filterBm25ResultsByScopePreset(bm25Results, scopePreset);
         const results = [];
         for (const bm25Result of bm25Results) {
             const fullPath = bm25Result.filePath;
+            const adjustedScore = Number(bm25Result.score || 0) * getUnityPathScoreMultiplier(fullPath, queryTokens, scopePreset);
             try {
                 const symbols = await executeParameterized(repo.id, `
           MATCH (n)
           WHERE n.filePath = $filePath
           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
-          LIMIT 3
+          LIMIT 50
         `, { filePath: fullPath });
                 if (symbols.length > 0) {
-                    for (const sym of symbols) {
+                    const rankedSymbols = rankExpandedSymbolsForQuery(symbols.map((sym) => ({
+                        id: sym.id || sym[0],
+                        name: sym.name || sym[1],
+                        type: sym.type || sym[2],
+                        filePath: sym.filePath || sym[3],
+                        startLine: sym.startLine || sym[4],
+                        endLine: sym.endLine || sym[5],
+                    })), query, 3, scopePreset);
+                    for (const sym of rankedSymbols) {
                         results.push({
-                            nodeId: sym.id || sym[0],
-                            name: sym.name || sym[1],
-                            type: sym.type || sym[2],
-                            filePath: sym.filePath || sym[3],
-                            startLine: sym.startLine || sym[4],
-                            endLine: sym.endLine || sym[5],
-                            bm25Score: bm25Result.score,
+                            nodeId: sym.id,
+                            name: sym.name,
+                            type: sym.type,
+                            filePath: sym.filePath,
+                            startLine: sym.startLine,
+                            endLine: sym.endLine,
+                            bm25Score: adjustedScore,
                         });
                     }
                 }
@@ -579,7 +732,7 @@ export class LocalBackend {
                         name: fileName,
                         type: 'File',
                         filePath: bm25Result.filePath,
-                        bm25Score: bm25Result.score,
+                        bm25Score: adjustedScore,
                     });
                 }
             }
@@ -589,11 +742,11 @@ export class LocalBackend {
                     name: fileName,
                     type: 'File',
                     filePath: bm25Result.filePath,
-                    bm25Score: bm25Result.score,
+                    bm25Score: adjustedScore,
                 });
             }
         }
-        return results;
+        return results.sort((a, b) => (Number(b.bm25Score || 0) - Number(a.bm25Score || 0)));
     }
     /**
      * Semantic vector search helper
@@ -858,20 +1011,63 @@ export class LocalBackend {
         // Step 3: Build full context
         const sym = symbols[0];
         const symId = sym.id || sym[0];
-        // Categorized incoming refs
-        const incomingRows = await executeParameterized(repo.id, `
+        // Direct incoming refs for the selected symbol.
+        const directIncomingRows = await executeParameterized(repo.id, `
       MATCH (caller)-[r:CodeRelation]->(n {id: $symId})
       WHERE r.type IN ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS']
       RETURN r.type AS relType, caller.id AS uid, caller.name AS name, caller.filePath AS filePath, labels(caller)[0] AS kind
       LIMIT 30
     `, { symId });
-        // Categorized outgoing refs
-        const outgoingRows = await executeParameterized(repo.id, `
+        // Direct outgoing refs for the selected symbol.
+        const directOutgoingRows = await executeParameterized(repo.id, `
       MATCH (n {id: $symId})-[r:CodeRelation]->(target)
       WHERE r.type IN ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS']
       RETURN r.type AS relType, target.id AS uid, target.name AS name, target.filePath AS filePath, labels(target)[0] AS kind
       LIMIT 30
     `, { symId });
+        const kind = sym.type || sym[2];
+        const symIdLower = String(symId).toLowerCase();
+        const isMethodContainer = new Set(['Class', 'Interface', 'Struct', 'Trait', 'Impl', 'Record']).has(kind)
+            || symIdLower.startsWith('class:')
+            || symIdLower.startsWith('interface:')
+            || symIdLower.startsWith('struct:')
+            || symIdLower.startsWith('trait:')
+            || symIdLower.startsWith('impl:')
+            || symIdLower.startsWith('record:');
+        let incomingRows = [...directIncomingRows];
+        let outgoingRows = [...directOutgoingRows];
+        if (isMethodContainer) {
+            const methodIncomingRows = await executeParameterized(repo.id, `
+        MATCH (n {id: $symId})-[:CodeRelation {type: 'HAS_METHOD'}]->(m)
+        MATCH (caller)-[r:CodeRelation]->(m)
+        WHERE r.type IN ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS']
+        RETURN r.type AS relType, caller.id AS uid, caller.name AS name, caller.filePath AS filePath, labels(caller)[0] AS kind
+        LIMIT 60
+      `, { symId });
+            const methodOutgoingRows = await executeParameterized(repo.id, `
+        MATCH (n {id: $symId})-[:CodeRelation {type: 'HAS_METHOD'}]->(m)
+        MATCH (m)-[r:CodeRelation]->(target)
+        WHERE r.type IN ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS']
+        RETURN r.type AS relType, target.id AS uid, target.name AS name, target.filePath AS filePath, labels(target)[0] AS kind
+        LIMIT 60
+      `, { symId });
+            const dedupe = (rows) => {
+                const seen = new Set();
+                const out = [];
+                for (const row of rows) {
+                    const relType = row.relType || row[0] || '';
+                    const uidVal = row.uid || row[1] || '';
+                    const key = `${relType}:${uidVal}`;
+                    if (seen.has(key))
+                        continue;
+                    seen.add(key);
+                    out.push(row);
+                }
+                return out;
+            };
+            incomingRows = dedupe([...directIncomingRows, ...methodIncomingRows]);
+            outgoingRows = dedupe([...directOutgoingRows, ...methodOutgoingRows]);
+        }
         // Process participation
         let processRows = [];
         try {
@@ -905,7 +1101,7 @@ export class LocalBackend {
             symbol: {
                 uid: sym.id || sym[0],
                 name: sym.name || sym[1],
-                kind: sym.type || sym[2],
+                kind,
                 filePath: sym.filePath || sym[3],
                 startLine: sym.startLine || sym[4],
                 endLine: sym.endLine || sym[5],
@@ -913,6 +1109,8 @@ export class LocalBackend {
             },
             incoming: categorize(incomingRows),
             outgoing: categorize(outgoingRows),
+            directIncoming: categorize(directIncomingRows),
+            directOutgoing: categorize(directOutgoingRows),
             processes: processRows.map((r) => ({
                 id: r.pid || r[0],
                 name: r.label || r[1],
@@ -1279,22 +1477,41 @@ export class LocalBackend {
     }
     async _impactImpl(repo, params) {
         await this.ensureInitialized(repo.id);
-        const { target, direction } = params;
+        const { target, target_uid, file_path, direction } = params;
         const maxDepth = params.maxDepth || 3;
+        const usesDefaultRelationTypes = !params.relationTypes || params.relationTypes.length === 0;
         const rawRelTypes = params.relationTypes && params.relationTypes.length > 0
             ? params.relationTypes.filter(t => VALID_RELATION_TYPES.has(t))
             : ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS'];
         const relationTypes = rawRelTypes.length > 0 ? rawRelTypes : ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS'];
         const includeTests = params.includeTests ?? false;
         const minConfidence = params.minConfidence ?? 0;
+        const shouldBridgeClassMethods = usesDefaultRelationTypes;
         const relTypeFilter = relationTypes.map(t => `'${t}'`).join(', ');
         const confidenceFilter = minConfidence > 0 ? ` AND r.confidence >= ${minConfidence}` : '';
+        const targetQueryParts = [];
+        const targetParams = { targetName: target };
+        if (target_uid) {
+            targetQueryParts.push('n.id = $targetUid');
+            targetParams.targetUid = target_uid;
+        }
+        else if (file_path) {
+            targetQueryParts.push('n.name = $targetName');
+            targetQueryParts.push('n.filePath CONTAINS $filePath');
+            targetParams.filePath = file_path;
+        }
+        else if (target.includes('/') || target.includes(':')) {
+            targetQueryParts.push('(n.id = $targetName OR n.name = $targetName)');
+        }
+        else {
+            targetQueryParts.push('n.name = $targetName');
+        }
         const targets = await executeParameterized(repo.id, `
       MATCH (n)
-      WHERE n.name = $targetName
+      WHERE ${targetQueryParts.join(' AND ')}
       RETURN n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath
-      LIMIT 1
-    `, { targetName: target });
+      LIMIT 10
+    `, targetParams);
         if (targets.length === 0)
             return { error: `Target '${target}' not found` };
         const sym = targets[0];
@@ -1302,11 +1519,63 @@ export class LocalBackend {
         const impacted = [];
         const visited = new Set([symId]);
         let frontier = [symId];
+        let frontierKindById = new Map([[symId, sym.type || sym[2] || '']]);
         let traversalComplete = true;
         for (let depth = 1; depth <= maxDepth && frontier.length > 0; depth++) {
             const nextFrontier = [];
+            let traversalFrontier = [...frontier];
+            // Bridge class-like symbols through HAS_METHOD so class-level impact includes method-level dependencies.
+            if (shouldBridgeClassMethods) {
+                if (frontier.length > 0) {
+                    const bridgeIdList = frontier.map(id => `'${id.replace(/'/g, "''")}'`).join(', ');
+                    try {
+                        const bridgeRows = await executeQuery(repo.id, `
+              MATCH (container)-[r:CodeRelation {type: 'HAS_METHOD'}]->(method)
+              WHERE container.id IN [${bridgeIdList}]${confidenceFilter}
+              RETURN container.id AS containerId, method.id AS methodId, method.name AS methodName, labels(method)[0] AS methodType, method.filePath AS methodFilePath
+            `);
+                        for (const bridge of bridgeRows) {
+                            const methodId = bridge.methodId || bridge[1];
+                            const methodType = bridge.methodType || bridge[3];
+                            if (!methodId)
+                                continue;
+                            if (!frontierKindById.has(methodId)) {
+                                frontierKindById.set(methodId, methodType || '');
+                            }
+                            if (direction === 'upstream') {
+                                traversalFrontier.push(methodId);
+                            }
+                            else {
+                                const methodFilePath = bridge.methodFilePath || bridge[4] || '';
+                                if (!includeTests && isTestFilePath(methodFilePath))
+                                    continue;
+                                if (!visited.has(methodId)) {
+                                    visited.add(methodId);
+                                    nextFrontier.push(methodId);
+                                    impacted.push({
+                                        depth,
+                                        id: methodId,
+                                        name: bridge.methodName || bridge[2],
+                                        type: methodType,
+                                        filePath: methodFilePath,
+                                        relationType: 'HAS_METHOD',
+                                        confidence: 1.0,
+                                    });
+                                }
+                            }
+                        }
+                    }
+                    catch (e) {
+                        logQueryError('impact:class-method-bridge', e);
+                        traversalComplete = false;
+                        break;
+                    }
+                }
+            }
+            // de-dupe traversal frontier (class + bridged methods)
+            traversalFrontier = [...new Set(traversalFrontier)];
             // Batch frontier nodes into a single Cypher query per depth level
-            const idList = frontier.map(id => `'${id.replace(/'/g, "''")}'`).join(', ');
+            const idList = traversalFrontier.map(id => `'${id.replace(/'/g, "''")}'`).join(', ');
             const query = direction === 'upstream'
                 ? `MATCH (caller)-[r:CodeRelation]->(n) WHERE n.id IN [${idList}] AND r.type IN [${relTypeFilter}]${confidenceFilter} RETURN n.id AS sourceId, caller.id AS id, caller.name AS name, labels(caller)[0] AS type, caller.filePath AS filePath, r.type AS relType, r.confidence AS confidence`
                 : `MATCH (n)-[r:CodeRelation]->(callee) WHERE n.id IN [${idList}] AND r.type IN [${relTypeFilter}]${confidenceFilter} RETURN n.id AS sourceId, callee.id AS id, callee.name AS name, labels(callee)[0] AS type, callee.filePath AS filePath, r.type AS relType, r.confidence AS confidence`;
@@ -1320,11 +1589,15 @@ export class LocalBackend {
                     if (!visited.has(relId)) {
                         visited.add(relId);
                         nextFrontier.push(relId);
+                        const relType = rel.type || rel[3];
+                        if (!frontierKindById.has(relId)) {
+                            frontierKindById.set(relId, relType || '');
+                        }
                         impacted.push({
                             depth,
                             id: relId,
                             name: rel.name || rel[2],
-                            type: rel.type || rel[3],
+                            type: relType,
                             filePath,
                             relationType: rel.relType || rel[5],
                             confidence: rel.confidence || rel[6] || 1.0,

package/dist/mcp/tools.js

@@ -36,6 +36,9 @@ Returns results grouped by process (execution flow):
 - definitions: standalone types/interfaces not in any process
 
 Hybrid ranking: BM25 keyword + semantic vector search, ranked by Reciprocal Rank Fusion.
+Supports optional scope controls for noisy codebases:
+- scope_preset=unity-gameplay to prioritize project gameplay code and suppress plugin-heavy paths.
+- scope_preset=unity-all (default behavior) to keep full Unity search scope.
 
 Includes optional Unity retrieval contract:
 - Set unity_resources=on|auto to include Unity resource evidence.
@@ -50,6 +53,11 @@ Includes optional Unity retrieval contract:
                 limit: { type: 'number', description: 'Max processes to return (default: 5)', default: 5 },
                 max_symbols: { type: 'number', description: 'Max symbols per process (default: 10)', default: 10 },
                 include_content: { type: 'boolean', description: 'Include full symbol source code (default: false)', default: false },
+                scope_preset: {
+                    type: 'string',
+                    enum: ['unity-gameplay', 'unity-all'],
+                    description: 'Optional retrieval preset. unity-gameplay reduces plugin/package noise in Unity projects.',
+                },
                 unity_resources: {
                     type: 'string',
                     enum: ['off', 'on', 'auto'],
@@ -197,6 +205,39 @@ Each edit is tagged with confidence:
             required: ['new_name'],
         },
     },
+    {
+        name: 'unity_ui_trace',
+        description: `Resolve Unity UI evidence chains (query-time only, no graph writes).
+
+Supports three goals:
+- asset_refs: which prefab/asset points to a target UXML
+- template_refs: which UXML templates are referenced by a target UXML
+- selector_bindings: static C# selector bindings traced to USS selectors
+
+Selector matching modes for selector_bindings:
+- balanced (default): match class tokens inside composite selectors (higher recall)
+- strict: only exact \`.className\` selectors (higher precision)
+
+Output enforces unique-result policy and includes path+line evidence hops.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                target: { type: 'string', description: 'Target C# class or UXML path' },
+                goal: {
+                    type: 'string',
+                    enum: ['asset_refs', 'template_refs', 'selector_bindings'],
+                    description: 'Trace goal',
+                },
+                selector_mode: {
+                    type: 'string',
+                    enum: ['strict', 'balanced'],
+                    description: 'Selector matching mode for selector_bindings (default: balanced)',
+                },
+                repo: { type: 'string', description: 'Repository name or path. Omit if only one repo is indexed.' },
+            },
+            required: ['target', 'goal'],
+        },
+    },
     {
         name: 'impact',
         description: `Analyze the blast radius of changing a code symbol.

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

@@ -7,6 +7,7 @@
  */
 export interface RepoMeta {
     repoPath: string;
+    repoId?: string;
     lastCommit: string;
     indexedAt: string;
     analyzeOptions?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veewo/gitnexus",
-  "version": "1.4.8",
+  "version": "1.4.9",
   "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",
@@ -51,6 +51,7 @@
     "check:neonspark-target": "node -e \"const p=(process.env.GITNEXUS_NEONSPARK_TARGET_PATH||'').trim();if(!p){console.error('Missing env: GITNEXUS_NEONSPARK_TARGET_PATH');process.exit(1);}\"",
     "check:u2-e2e-target": "node -e \"const p=(process.env.GITNEXUS_U2_E2E_TARGET_PATH||'').trim();if(!p){console.error('Missing env: GITNEXUS_U2_E2E_TARGET_PATH');process.exit(1);}\"",
     "test:unity": "npm run build && node --test dist/core/unity/*.test.js",
+    "test:unity-ui-trace:smoke": "npm run build && node --test dist/core/unity/ui-trace.acceptance.test.js dist/core/unity/ui-trace.test.js dist/cli/unity-ui-trace.test.js",
     "test:u3:gates": "npm run check:release-paths && npm run build && node --test dist/benchmark/u2-e2e/*.test.js dist/mcp/local/unity-enrichment.test.js dist/core/ingestion/unity-resource-processor.test.js",
     "test:benchmark": "npm run build && node --test dist/benchmark/*.test.js && node --test dist/cli/*.test.js",
     "benchmark:quick": "npm run build && node dist/cli/index.js benchmark-unity ../benchmarks/unity-baseline/v1 --profile quick --target-path ../benchmarks/fixtures/unity-mini",

package/skills/gitnexus-cli.md

@@ -113,6 +113,35 @@ Rules:
 - If response `hydrationMeta.needsParityRetry=true`, rerun with `--unity-hydration parity`.
 - `--unity-hydration parity` is completeness-first mode for advanced verification.
 
+### unity-ui-trace — Unity UI evidence tracing workflow
+
+```bash
+$GN unity-ui-trace "Assets/NEON/VeewoUI/Uxml/BarScreen/Patch/PatchItemPreview.uxml" --goal asset_refs --repo neonspark
+$GN unity-ui-trace "Assets/NEON/VeewoUI/Uxml/BarScreen/CoreScreen.uxml" --goal template_refs --repo neonspark
+$GN unity-ui-trace "Assets/NEON/VeewoUI/Uxml/BarScreen/Patch/PatchItemPreview.uxml" --goal selector_bindings --selector-mode balanced --repo neonspark
+```
+
+Supported goals:
+- `asset_refs`: 哪些 prefab/asset 引用了目标 UXML
+- `template_refs`: 目标 UXML 里引用了哪些模板 UXML
+- `selector_bindings`: C# `AddToClassList/Q(className)` 到 USS 选择器证据链
+
+Selector mode（仅 `selector_bindings` 生效）:
+- `--selector-mode balanced`（默认）: 复合选择器 token 匹配，召回更高
+- `--selector-mode strict`: 仅匹配精确 `.className` 选择器，精度更高
+
+输出字段解读:
+- `results[].evidence_chain`: 每跳都有 `path + line + snippet`
+- `results[].score`: 排序分数（越高越优先）
+- `results[].confidence`: `high|medium|low`（基于 score）
+- `diagnostics`: `not_found|ambiguous` 诊断
+
+推荐排查顺序（实仓）:
+1. 先跑 `asset_refs`，确认资源链是否存在
+2. 再跑 `template_refs`，确认模板链是否存在
+3. 最后跑 `selector_bindings`，默认 `balanced`
+4. 若怀疑误报，复跑 `--selector-mode strict` 对比
+
 ## After Indexing
 
 1. **Read `gitnexus://repo/{name}/context`** to verify the index loaded

package/skills/gitnexus-guide.md

@@ -37,6 +37,7 @@ For any task involving code understanding, debugging, impact analysis, or refact
 | `impact`         | Symbol blast radius — what breaks at depth 1/2/3 with confidence         |
 | `detect_changes` | Git-diff impact — what do your current changes affect                    |
 | `rename`         | Multi-file coordinated rename with confidence-tagged edits               |
+| `unity_ui_trace` | Unity UI query-time evidence chains (`asset_refs/template_refs/selector_bindings`) |
 | `cypher`         | Raw graph queries (read `gitnexus://repo/{name}/schema` first)           |
 | `list_repos`     | Discover indexed repos                                                   |
 
@@ -55,6 +56,28 @@ Recommended default workflow:
    - `isComplete: true` → keep compact result
 3. Treat parity as the completeness path for advanced verification.
 
+### Unity UI Trace Contract (`unity_ui_trace` / `gitnexus unity-ui-trace`)
+
+Input:
+- `target`: C# class 名或 UXML 路径
+- `goal`: `asset_refs | template_refs | selector_bindings`
+- `selector_mode`（可选）: `balanced`（默认）或 `strict`
+
+Modes:
+- `balanced`: 复合选择器 token 匹配，召回优先
+- `strict`: 仅精确 `.className` 选择器，精度优先
+
+Output:
+- `results[].evidence_chain`: 严格 `path + line + snippet` 证据跳
+- `results[].score`: 排序分数（高分优先）
+- `results[].confidence`: `high|medium|low`
+- `diagnostics`: `not_found|ambiguous`
+
+Recommended workflow:
+1. 先跑 `asset_refs`（确认资源引用链存在）
+2. 再跑 `template_refs`（确认模板引用链存在）
+3. 最后跑 `selector_bindings`（先 `balanced`，必要时切 `strict` 验证）
+
 ## Resources Reference
 
 Lightweight reads (~100-500 tokens) for navigation: