@veewo/gitnexus 1.4.8 → 1.4.9

package/dist/cli/ai-context.js

@@ -36,13 +36,12 @@ function generateGitNexusContent(projectName, stats, skillScope, cliPackageSpec,
     return `${GITNEXUS_START_MARKER}
 # GitNexus MCP
 
-This project is indexed by GitNexus as **${projectName}** (${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${stats.processes || 0} execution flows).
-
 ## Always Start Here
 
 1. **Read \`gitnexus://repo/{name}/context\`** — codebase overview + check index freshness
 2. **Match your task to a skill below** and **read that skill file**
 3. **Follow the skill's workflow and checklist**
+4. **Follow config/state file rules:** \`docs/gitnexus-config-files.md\`
 
 > If step 1 warns the index is stale, ask user whether to rebuild index via \`gitnexus analyze\` when local CLI exists; otherwise resolve the pinned npx package spec from \`~/.gitnexus/config.json\` (\`cliPackageSpec\` first, then \`cliVersion\`) and run \`${reindexCmd}\` with that exact package spec (it reuses previous analyze scope/options by default; add \`--no-reuse-options\` to reset). If user declines, explicitly warn that retrieval may not reflect current codebase. For build/analyze/test commands, use a 10-30 minute timeout; on failure/timeout, report exact tool output and do not auto-retry or silently fall back to glob/grep.
 

package/dist/cli/analyze.js

@@ -360,9 +360,10 @@ export const analyzeCommand = async (inputPath, options) => {
             embeddings: embeddingCount,
         },
     };
+    const registeredRepo = await registerRepo(repoPath, meta, { repoAlias });
+    meta.repoId = registeredRepo.name;
     await saveMeta(storagePath, meta);
     await persistUnityParitySeed(storagePath, pipelineRuntime.unityResult?.paritySeed);
-    const registeredRepo = await registerRepo(repoPath, meta, { repoAlias });
     await addToGitignore(repoPath);
     const projectName = path.basename(repoPath);
     let aggregatedClusterCount = 0;

package/dist/cli/index.js

@@ -82,6 +82,7 @@ program
     .option('-g, --goal <text>', 'What you want to find')
     .option('-l, --limit <n>', 'Max processes to return (default: 5)')
     .option('--content', 'Include full symbol source code')
+    .option('--scope-preset <preset>', 'Scope preset for retrieval: unity-gameplay|unity-all')
     .option('--unity-resources <mode>', 'Unity resource retrieval mode: off|on|auto', 'off')
     .option('--unity-hydration <mode>', 'Unity hydration mode when resources are enabled: parity|compact', 'compact')
     .action(createLazyAction(() => import('./tool.js'), 'queryCommand'));
@@ -101,6 +102,13 @@ program
     .option('--target-path <path>', 'Unity project root (default: cwd)')
     .option('--json', 'Output JSON')
     .action(createLazyAction(() => import('./unity-bindings.js'), 'unityBindingsCommand'));
+program
+    .command('unity-ui-trace <target>')
+    .description('Query-time Unity UI evidence tracing (asset_refs|template_refs|selector_bindings)')
+    .option('-r, --repo <name>', 'Target repository (omit if only one indexed)')
+    .option('--goal <goal>', 'Trace goal: asset_refs|template_refs|selector_bindings', 'asset_refs')
+    .option('--selector-mode <mode>', 'Selector matching mode for selector_bindings: strict|balanced', 'balanced')
+    .action(createLazyAction(() => import('./tool.js'), 'unityUiTraceCommand'));
 program
     .command('impact <target>')
     .description('Blast radius analysis: what breaks if you change a symbol')

package/dist/cli/repo-manager-alias.test.js

@@ -43,6 +43,7 @@ test('saveMeta/loadMeta persists analyzeOptions for future re-index reuse', asyn
     const storagePath = path.join(tmpDir, '.gitnexus');
     await saveMeta(storagePath, {
         repoPath: tmpDir,
+        repoId: 'neonspark-v1-subset',
         lastCommit: 'abc1234',
         indexedAt: '2026-03-12T00:00:00.000Z',
         analyzeOptions: {
@@ -60,4 +61,5 @@ test('saveMeta/loadMeta persists analyzeOptions for future re-index reuse', asyn
         repoAlias: 'neonspark-v1-subset',
         embeddings: true,
     });
+    assert.equal(meta?.repoId, 'neonspark-v1-subset');
 });

package/dist/cli/tool.d.ts

@@ -21,6 +21,7 @@ export declare function queryCommand(queryText: string, options?: {
     goal?: string;
     limit?: string;
     content?: boolean;
+    scopePreset?: 'unity-gameplay' | 'unity-all';
     unityResources?: UnityResourcesMode;
     unityHydration?: UnityHydrationMode;
 }): Promise<void>;
@@ -44,3 +45,13 @@ export declare function impactCommand(target: string, options?: {
 export declare function cypherCommand(query: string, options?: {
     repo?: string;
 }): Promise<void>;
+export declare function unityUiTraceCommand(target: string, options?: {
+    repo?: string;
+    goal?: string;
+    selectorMode?: string;
+}, deps?: {
+    backend?: {
+        callTool: (method: string, params: any) => Promise<any>;
+    };
+    output?: (data: any) => void;
+}): Promise<void>;

package/dist/cli/tool.js

@@ -15,7 +15,10 @@
  * See the output() function for details (#324).
  */
 import { writeSync } from 'node:fs';
+import path from 'node:path';
 import { LocalBackend } from '../mcp/local/local-backend.js';
+import { getGitRoot } from '../storage/git.js';
+import { getStoragePaths, listRegisteredRepos, loadMeta } from '../storage/repo-manager.js';
 let _backend = null;
 async function getBackend() {
     if (_backend)
@@ -53,21 +56,45 @@ function output(data) {
         process.stderr.write(text + '\n');
     }
 }
+function isUnityUiTraceGoal(value) {
+    return value === 'asset_refs' || value === 'template_refs' || value === 'selector_bindings';
+}
+function isUnityUiSelectorMode(value) {
+    return value === 'strict' || value === 'balanced';
+}
+async function resolveRepoOption(explicitRepo) {
+    if (explicitRepo?.trim())
+        return explicitRepo.trim();
+    const gitRoot = getGitRoot(process.cwd());
+    if (!gitRoot)
+        return undefined;
+    const { storagePath } = getStoragePaths(gitRoot);
+    const meta = await loadMeta(storagePath);
+    const repoId = typeof meta?.repoId === 'string' ? meta.repoId.trim() : '';
+    if (repoId)
+        return repoId;
+    // Backward compatibility for indexes created before repoId persisted in meta.json.
+    const entries = await listRegisteredRepos({ validate: false });
+    const matched = entries.find((entry) => path.resolve(entry.path) === gitRoot);
+    return matched?.name || undefined;
+}
 export async function queryCommand(queryText, options) {
     if (!queryText?.trim()) {
         console.error('Usage: gitnexus query <search_query>');
         process.exit(1);
     }
     const backend = await getBackend();
+    const repo = await resolveRepoOption(options?.repo);
     const result = await backend.callTool('query', {
         query: queryText,
         task_context: options?.context,
         goal: options?.goal,
         limit: options?.limit ? parseInt(options.limit) : undefined,
         include_content: options?.content ?? false,
+        scope_preset: options?.scopePreset,
         unity_resources: options?.unityResources,
         unity_hydration_mode: options?.unityHydration,
-        repo: options?.repo,
+        repo,
     });
     output(result);
 }
@@ -77,6 +104,7 @@ export async function contextCommand(name, options) {
         process.exit(1);
     }
     const backend = await getBackend();
+    const repo = await resolveRepoOption(options?.repo);
     const result = await backend.callTool('context', {
         name: name || undefined,
         uid: options?.uid,
@@ -84,7 +112,7 @@ export async function contextCommand(name, options) {
         include_content: options?.content ?? false,
         unity_resources: options?.unityResources,
         unity_hydration_mode: options?.unityHydration,
-        repo: options?.repo,
+        repo,
     });
     output(result);
 }
@@ -95,6 +123,7 @@ export async function impactCommand(target, options) {
     }
     try {
         const backend = await getBackend();
+        const repo = await resolveRepoOption(options?.repo);
         const result = await backend.callTool('impact', {
             target,
             target_uid: options?.uid,
@@ -103,7 +132,7 @@ export async function impactCommand(target, options) {
             maxDepth: options?.depth ? parseInt(options.depth, 10) : undefined,
             minConfidence: options?.minConfidence ? parseFloat(options.minConfidence) : undefined,
             includeTests: options?.includeTests ?? false,
-            repo: options?.repo,
+            repo,
         });
         output(result);
     }
@@ -124,9 +153,35 @@ export async function cypherCommand(query, options) {
         process.exit(1);
     }
     const backend = await getBackend();
+    const repo = await resolveRepoOption(options?.repo);
     const result = await backend.callTool('cypher', {
         query,
-        repo: options?.repo,
+        repo,
     });
     output(result);
 }
+export async function unityUiTraceCommand(target, options, deps) {
+    if (!target?.trim()) {
+        console.error('Usage: gitnexus unity-ui-trace <target> --goal asset_refs|template_refs|selector_bindings');
+        process.exit(1);
+    }
+    const goal = String(options?.goal || 'asset_refs').trim();
+    if (!isUnityUiTraceGoal(goal)) {
+        console.error('Invalid --goal. Use one of: asset_refs, template_refs, selector_bindings');
+        process.exit(1);
+    }
+    const selectorMode = String(options?.selectorMode || 'balanced').trim();
+    if (!isUnityUiSelectorMode(selectorMode)) {
+        console.error('Invalid --selector-mode. Use one of: strict, balanced');
+        process.exit(1);
+    }
+    const backend = deps?.backend || await getBackend();
+    const repo = await resolveRepoOption(options?.repo);
+    const result = await backend.callTool('unity_ui_trace', {
+        target,
+        goal,
+        selector_mode: selectorMode,
+        repo,
+    });
+    (deps?.output || output)(result);
+}

package/dist/cli/unity-ui-trace.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/unity-ui-trace.test.js

@@ -0,0 +1,24 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { unityUiTraceCommand } from './tool.js';
+test('unity-ui-trace command forwards params and prints result', async () => {
+    const calls = [];
+    let printed = null;
+    await unityUiTraceCommand('EliteBossScreenController', { goal: 'selector_bindings', selectorMode: 'strict', repo: 'mini-unity-ui' }, {
+        backend: {
+            async callTool(method, params) {
+                calls.push({ method, params });
+                return { goal: 'selector_bindings', results: [{ evidence_chain: [{ path: 'a', line: 1 }] }], diagnostics: [] };
+            },
+        },
+        output: (value) => {
+            printed = value;
+        },
+    });
+    assert.equal(calls.length, 1);
+    assert.equal(calls[0].method, 'unity_ui_trace');
+    assert.equal(calls[0].params.target, 'EliteBossScreenController');
+    assert.equal(calls[0].params.goal, 'selector_bindings');
+    assert.equal(calls[0].params.selector_mode, 'strict');
+    assert.equal(printed.goal, 'selector_bindings');
+});

package/dist/core/ingestion/call-processor.js

@@ -35,7 +35,15 @@ const findEnclosingFunction = (node, filePath, ctx) => {
  */
 const verifyConstructorBindings = (bindings, filePath, ctx, graph) => {
     const verified = new Map();
-    for (const { scope, varName, calleeName, receiverClassName } of bindings) {
+    for (const { scope, varName, calleeName, receiverClassName, inferredTypeName } of bindings) {
+        if (inferredTypeName) {
+            const inferred = ctx.resolve(inferredTypeName, filePath);
+            const isReceivableType = inferred?.candidates.some(def => def.type === 'Class' || def.type === 'Interface' || def.type === 'Struct' || def.type === 'Enum') ?? false;
+            if (isReceivableType) {
+                verified.set(receiverKey(scope, varName), inferredTypeName);
+                continue;
+            }
+        }
         const tiered = ctx.resolve(calleeName, filePath);
         const isClass = tiered?.candidates.some(def => def.type === 'Class') ?? false;
         if (isClass) {

package/dist/core/ingestion/type-env.d.ts

@@ -46,4 +46,6 @@ export interface ConstructorBinding {
     calleeName: string;
     /** Enclosing class name when callee is a method on a known receiver (e.g. $this) */
     receiverClassName?: string;
+    /** Optional direct type hint extracted from safe generic invocation patterns. */
+    inferredTypeName?: string;
 }

package/dist/core/ingestion/type-extractors/csharp.js

@@ -1,4 +1,4 @@
-import { extractSimpleTypeName, extractVarName, findChildByType, unwrapAwait, resolveIterableElementType, methodToTypeArgPosition, extractElementTypeFromString } from './shared.js';
+import { extractSimpleTypeName, extractVarName, findChildByType, unwrapAwait, extractGenericTypeArgs, resolveIterableElementType, methodToTypeArgPosition, extractElementTypeFromString } from './shared.js';
 /** Known container property accessors that operate on the container itself (e.g., dict.Keys, dict.Values) */
 const KNOWN_CONTAINER_PROPS = new Set(['Keys', 'Values']);
 const DECLARATION_NODE_TYPES = new Set([
@@ -145,7 +145,22 @@ const scanConstructorBinding = (node) => {
     const calleeName = extractSimpleTypeName(func);
     if (!calleeName)
         return undefined;
-    return { varName: nameNode.text, calleeName };
+    // Safe generic-invocation receiver hint:
+    //   var user = GetComponentInParent<User>()
+    //   var user = svc.GetComponentInParent<User>()
+    // infer user -> User directly from the single type argument.
+    let inferredTypeName;
+    const genericCallee = func.type === 'generic_name'
+        ? func
+        : func.type === 'member_access_expression'
+            ? func.childForFieldName('name')
+            : null;
+    if (genericCallee?.type === 'generic_name') {
+        const typeArgs = extractGenericTypeArgs(genericCallee);
+        if (typeArgs.length === 1)
+            inferredTypeName = typeArgs[0];
+    }
+    return { varName: nameNode.text, calleeName, inferredTypeName };
 };
 const FOR_LOOP_NODE_TYPES = new Set([
     'foreach_statement',

package/dist/core/ingestion/type-extractors/types.d.ts

@@ -13,11 +13,14 @@ export type InitializerExtractor = (node: SyntaxNode, env: Map<string, string>,
 /** Scans an AST node for untyped `var = callee()` patterns for return-type inference.
  *  Returns { varName, calleeName } if the node matches, undefined otherwise.
  *  `receiverClassName` — optional hint for method calls on known receivers
- *  (e.g. $this->getUser() in PHP provides the enclosing class name). */
+ *  (e.g. $this->getUser() in PHP provides the enclosing class name).
+ *  `inferredTypeName` — optional direct type hint from safe generic invocations
+ *  (e.g. `var x = GetComponentInParent<User>()` gives `User`). */
 export type ConstructorBindingScanner = (node: SyntaxNode) => {
     varName: string;
     calleeName: string;
     receiverClassName?: string;
+    inferredTypeName?: string;
 } | undefined;
 /** Extracts a return type string from a method/function definition node.
  *  Used for languages where return types are expressed in comments (e.g. YARD @return [Type])

package/dist/core/unity/csharp-selector-binding.d.ts

@@ -0,0 +1,7 @@
+export interface CsharpSelectorBinding {
+    className: string;
+    line: number;
+    snippet: string;
+    isDynamic: boolean;
+}
+export declare function extractCsharpSelectorBindings(content: string): CsharpSelectorBinding[];

package/dist/core/unity/csharp-selector-binding.js

@@ -0,0 +1,32 @@
+const ADD_TO_CLASS_LIST_LITERAL = /\bAddToClassList\s*\(\s*"([^"]+)"\s*\)/g;
+const Q_CLASS_NAME_LITERAL = /\bQ\s*<[^>]*>\s*\([^)]*\bclassName\s*:\s*"([^"]+)"[^)]*\)/g;
+export function extractCsharpSelectorBindings(content) {
+    const out = [];
+    const lines = content.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        ADD_TO_CLASS_LIST_LITERAL.lastIndex = 0;
+        let addMatch = ADD_TO_CLASS_LIST_LITERAL.exec(line);
+        while (addMatch) {
+            out.push({
+                className: addMatch[1],
+                line: i + 1,
+                snippet: line.trim(),
+                isDynamic: false,
+            });
+            addMatch = ADD_TO_CLASS_LIST_LITERAL.exec(line);
+        }
+        Q_CLASS_NAME_LITERAL.lastIndex = 0;
+        let qMatch = Q_CLASS_NAME_LITERAL.exec(line);
+        while (qMatch) {
+            out.push({
+                className: qMatch[1],
+                line: i + 1,
+                snippet: line.trim(),
+                isDynamic: false,
+            });
+            qMatch = Q_CLASS_NAME_LITERAL.exec(line);
+        }
+    }
+    return out;
+}

package/dist/core/unity/csharp-selector-binding.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/unity/csharp-selector-binding.test.js

@@ -0,0 +1,14 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { extractCsharpSelectorBindings } from './csharp-selector-binding.js';
+const here = path.dirname(fileURLToPath(import.meta.url));
+const fixtureRoot = path.resolve(here, '../../../src/core/unity/__fixtures__/mini-unity-ui');
+test('extracts static-only selector bindings from csharp', async () => {
+    const source = await fs.readFile(path.join(fixtureRoot, 'Assets/Scripts/EliteBossScreenController.cs'), 'utf-8');
+    const bindings = extractCsharpSelectorBindings(source);
+    assert.equal(bindings.some((entry) => entry.className === 'tooltip-box'), true);
+    assert.equal(bindings.some((entry) => entry.isDynamic), false);
+});

package/dist/core/unity/scan-context.d.ts

@@ -19,6 +19,8 @@ export interface UnityScanContext {
     serializableSymbols: Set<string>;
     hostFieldTypeHints: Map<string, Map<string, string>>;
     assetGuidToPath?: Map<string, string>;
+    uxmlGuidToPath?: Map<string, string>;
+    ussGuidToPath?: Map<string, string>;
     resourceDocCache: Map<string, UnityObjectBlock[]>;
 }
 export declare function buildUnityScanContext(input: BuildScanContextInput): Promise<UnityScanContext>;

package/dist/core/unity/scan-context.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { createInterface } from 'node:readline';
 import { glob } from 'glob';
 import { buildAssetMetaIndex, buildMetaIndex } from './meta-index.js';
+import { buildUnityUiMetaIndex } from './ui-meta-index.js';
 import { buildSerializableTypeIndexFromFiles } from './serialized-type-index.js';
 const DECLARATION_PATTERN = /\b(?:class|struct|interface)\s+([A-Za-z_][A-Za-z0-9_]*)\b/g;
 const SCRIPT_GUID_IN_LINE_PATTERN = /\bm_Script\s*:\s*\{[^}]*\bguid\s*:\s*([0-9a-f]{32})\b/gi;
@@ -32,6 +33,7 @@ export async function buildUnityScanContext(input) {
     const guidToResourceHits = await buildGuidHitIndex(input.repoRoot, scriptPathToGuid, resourceFiles);
     const assetMetaFiles = resolveAssetMetaFiles(input.repoRoot, input.scopedPaths, scriptFiles, resourceFiles);
     const assetGuidToPath = await buildAssetMetaIndex(input.repoRoot, { metaFiles: assetMetaFiles });
+    const uiMetaIndex = await buildUnityUiMetaIndex(input.repoRoot, { scopedPaths: input.scopedPaths });
     const symbolToCanonicalScriptPath = buildCanonicalScriptPathIndex(symbolToScriptPaths, scriptPathToGuid, guidToResourceHits);
     const symbolToScriptPath = new Map(symbolToCanonicalScriptPath);
     return {
@@ -43,6 +45,8 @@ export async function buildUnityScanContext(input) {
         serializableSymbols: serializableTypeIndex.serializableSymbols,
         hostFieldTypeHints: serializableTypeIndex.hostFieldTypeHints,
         assetGuidToPath,
+        uxmlGuidToPath: uiMetaIndex.uxmlGuidToPath,
+        ussGuidToPath: uiMetaIndex.ussGuidToPath,
         resourceDocCache: new Map(),
     };
 }
@@ -114,11 +118,22 @@ export function buildUnityScanContextFromSeed(input) {
         }
     }
     const assetGuidToPath = new Map();
+    const uxmlGuidToPath = new Map();
+    const ussGuidToPath = new Map();
     for (const [guid, assetPath] of Object.entries(seed.assetGuidToPath || {})) {
         const normalizedPath = normalizeSlashes(String(assetPath || '').trim());
         if (!guid || !normalizedPath)
             continue;
         assetGuidToPath.set(guid, normalizedPath);
+        assetGuidToPath.set(guid.toLowerCase(), normalizedPath);
+        if (normalizedPath.endsWith('.uxml')) {
+            uxmlGuidToPath.set(guid, normalizedPath);
+            uxmlGuidToPath.set(guid.toLowerCase(), normalizedPath);
+        }
+        if (normalizedPath.endsWith('.uss')) {
+            ussGuidToPath.set(guid, normalizedPath);
+            ussGuidToPath.set(guid.toLowerCase(), normalizedPath);
+        }
     }
     return {
         symbolToScriptPaths,
@@ -129,6 +144,8 @@ export function buildUnityScanContextFromSeed(input) {
         serializableSymbols: new Set(),
         hostFieldTypeHints: new Map(),
         assetGuidToPath,
+        uxmlGuidToPath,
+        ussGuidToPath,
         resourceDocCache: new Map(),
     };
 }

package/dist/core/unity/ui-asset-ref-scanner.d.ts

@@ -0,0 +1,14 @@
+export interface UiAssetRefEvidence {
+    sourceType: 'prefab' | 'asset';
+    sourcePath: string;
+    line: number;
+    fieldName: string;
+    guid: string;
+    snippet: string;
+}
+export interface ScanUiAssetRefInput {
+    repoRoot: string;
+    scopedPaths?: string[];
+    targetGuids?: string[];
+}
+export declare function scanUiAssetRefs(input: ScanUiAssetRefInput): Promise<UiAssetRefEvidence[]>;