@veewo/gitnexus 1.4.8 → 1.4.9

package/dist/core/unity/ui-trace.js

@@ -0,0 +1,363 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { glob } from 'glob';
+import { scanUiAssetRefs } from './ui-asset-ref-scanner.js';
+import { parseUxmlRefs } from './uxml-ref-parser.js';
+import { parseUssSelectors } from './uss-selector-parser.js';
+import { extractCsharpSelectorBindings } from './csharp-selector-binding.js';
+import { buildUnityUiMetaIndex } from './ui-meta-index.js';
+import { buildMetaIndex } from './meta-index.js';
+export async function runUnityUiTrace(input) {
+    const target = String(input.target || '').trim();
+    const goal = input.goal;
+    const selectorMode = input.selectorMode || 'balanced';
+    const key = canonicalKey(target);
+    const uiMeta = await buildUnityUiMetaIndex(input.repoRoot);
+    const uxmlCandidates = resolveTargetUxmlCandidates(input.repoRoot, target, key, uiMeta.uxmlGuidToPath);
+    const diagnostics = [];
+    if (uxmlCandidates.length === 0) {
+        return {
+            goal,
+            target,
+            results: [],
+            diagnostics: [
+                {
+                    code: 'not_found',
+                    message: 'No matching UXML target found.',
+                    candidates: [],
+                },
+            ],
+        };
+    }
+    if (uxmlCandidates.length > 1) {
+        return {
+            goal,
+            target,
+            results: [],
+            diagnostics: [
+                {
+                    code: 'ambiguous',
+                    message: 'Target resolves to multiple UXML files.',
+                    candidates: uxmlCandidates.map((candidate) => ({ path: candidate, line: 1, snippet: 'target-candidate' })),
+                },
+            ],
+        };
+    }
+    const targetUxmlPath = uxmlCandidates[0];
+    const results = await resolveGoal({
+        repoRoot: input.repoRoot,
+        goal,
+        selectorMode,
+        target,
+        targetKey: key,
+        targetUxmlPath,
+        uiMeta,
+    });
+    if (results.length === 0) {
+        diagnostics.push({
+            code: 'not_found',
+            message: 'No evidence chain found.',
+            candidates: [],
+        });
+        return { goal, target, results: [], diagnostics };
+    }
+    return { goal, target, results, diagnostics };
+}
+async function resolveGoal(input) {
+    if (input.goal === 'asset_refs') {
+        const targetUxmlGuid = findGuidForUxmlPath(input.targetUxmlPath, input.uiMeta.uxmlGuidToPath);
+        if (!targetUxmlGuid)
+            return [];
+        const refs = await scanUiAssetRefs({
+            repoRoot: input.repoRoot,
+            targetGuids: [targetUxmlGuid],
+        });
+        return refs
+            .filter((row) => row.guid === targetUxmlGuid)
+            .map((row, index) => ({
+            key: `${row.sourcePath}:${row.line}:${index}`,
+            evidence_chain: [
+                { path: row.sourcePath, line: row.line, snippet: row.snippet },
+                { path: input.targetUxmlPath, line: 1, snippet: 'resolved-by-guid' },
+            ],
+        }));
+    }
+    if (input.goal === 'template_refs') {
+        const source = await safeRead(path.join(input.repoRoot, input.targetUxmlPath));
+        const parsed = parseUxmlRefs(source);
+        const templates = parsed.templates
+            .map((template) => ({
+            template,
+            resolvedPath: input.uiMeta.uxmlGuidToPath.get(template.guid),
+        }))
+            .filter((row) => Boolean(row.resolvedPath));
+        return templates.map((row, index) => ({
+            key: `${row.resolvedPath}:${row.template.line}:${index}`,
+            evidence_chain: [
+                { path: input.targetUxmlPath, line: row.template.line, snippet: row.template.snippet },
+                { path: row.resolvedPath, line: 1, snippet: 'template-target' },
+            ],
+        }));
+    }
+    const scriptPaths = await resolveScriptPathsForSelectorTarget(input.repoRoot, input.target, input.targetUxmlPath, input.targetKey, input.uiMeta);
+    const csharpBindings = await scanCsharpBindings(input.repoRoot, input.targetKey, scriptPaths);
+    const styles = await resolveStyleSelectorsForUxml(input.repoRoot, input.targetUxmlPath, input.uiMeta);
+    const styleSelectorTokenIndex = buildStyleSelectorTokenIndex(styles, input.selectorMode);
+    const selectorMatches = [];
+    for (const binding of csharpBindings) {
+        const normalizedClass = normalizeClassToken(binding.className);
+        if (!normalizedClass)
+            continue;
+        const styleEvidenceList = styleSelectorTokenIndex.get(normalizedClass) || [];
+        for (const styleEvidence of styleEvidenceList) {
+            const score = scoreSelectorBindingMatch(binding, styleEvidence, input.targetKey);
+            selectorMatches.push({
+                key: `${binding.path}:${binding.line}:${styleEvidence.path}:${styleEvidence.line}:${normalizedClass}`,
+                score,
+                evidence_chain: [
+                    { path: binding.path, line: binding.line, snippet: binding.snippet },
+                    { path: styleEvidence.path, line: styleEvidence.line, snippet: styleEvidence.snippet },
+                ],
+            });
+        }
+    }
+    selectorMatches.sort((left, right) => {
+        const scoreDiff = (right.score || 0) - (left.score || 0);
+        if (scoreDiff !== 0)
+            return scoreDiff;
+        const leftHop = left.evidence_chain[0];
+        const rightHop = right.evidence_chain[0];
+        const pathDiff = leftHop.path.localeCompare(rightHop.path);
+        if (pathDiff !== 0)
+            return pathDiff;
+        return leftHop.line - rightHop.line;
+    });
+    return dedupeTraceResults(selectorMatches);
+}
+function resolveTargetUxmlCandidates(repoRoot, target, targetKey, uxmlGuidToPath) {
+    const normalizedTarget = normalizeUxmlTargetPath(repoRoot, target);
+    if (normalizedTarget) {
+        const exactPath = findExactUxmlPath(normalizedTarget, uxmlGuidToPath);
+        if (exactPath) {
+            return [exactPath];
+        }
+    }
+    const set = new Set();
+    for (const p of uxmlGuidToPath.values()) {
+        if (canonicalKey(path.basename(p, '.uxml')) === targetKey) {
+            set.add(p);
+        }
+    }
+    return [...set];
+}
+function canonicalKey(input) {
+    return String(input || '')
+        .replace(/\\/g, '/')
+        .split('/')
+        .pop()
+        .replace(/\.uxml$/i, '')
+        .replace(/controller$/i, '')
+        .replace(/new$/i, '')
+        .replace(/[^a-z0-9]/gi, '')
+        .toLowerCase();
+}
+async function scanCsharpBindings(repoRoot, targetKey, preferredScriptPaths = []) {
+    const preferredSet = new Set(preferredScriptPaths);
+    const fallbackScriptPaths = (await glob('**/*.cs', { cwd: repoRoot, nodir: true, dot: false }))
+        .filter((scriptPath) => canonicalKey(path.basename(scriptPath, '.cs')) === targetKey);
+    const scriptPaths = [...new Set([...preferredScriptPaths, ...fallbackScriptPaths])]
+        .sort((left, right) => left.localeCompare(right));
+    const out = [];
+    for (const scriptPath of scriptPaths) {
+        const source = await safeRead(path.join(repoRoot, scriptPath));
+        const bindings = extractCsharpSelectorBindings(source);
+        for (const binding of bindings) {
+            out.push({
+                path: scriptPath.replace(/\\/g, '/'),
+                line: binding.line,
+                snippet: binding.snippet,
+                className: binding.className,
+                source: preferredSet.has(scriptPath) ? 'resource_chain' : 'name_fallback',
+            });
+        }
+    }
+    return out;
+}
+async function resolveScriptPathsForSelectorTarget(repoRoot, target, targetUxmlPath, targetKey, uiMeta) {
+    const normalizedTarget = normalizeUxmlTargetPath(repoRoot, target);
+    const isPathTarget = Boolean(normalizedTarget && findExactUxmlPath(normalizedTarget, uiMeta.uxmlGuidToPath));
+    if (!isPathTarget) {
+        return [];
+    }
+    const targetUxmlGuid = findGuidForUxmlPath(targetUxmlPath, uiMeta.uxmlGuidToPath);
+    if (!targetUxmlGuid)
+        return [];
+    const assetRefs = await scanUiAssetRefs({
+        repoRoot,
+        targetGuids: [targetUxmlGuid],
+    });
+    const sourcePaths = [...new Set(assetRefs.map((row) => row.sourcePath))];
+    if (sourcePaths.length === 0)
+        return [];
+    const scopedRefs = await scanUiAssetRefs({
+        repoRoot,
+        scopedPaths: sourcePaths,
+    });
+    const scriptGuids = [...new Set(scopedRefs
+            .filter((row) => row.fieldName === 'm_Script')
+            .map((row) => row.guid.toLowerCase()))];
+    if (scriptGuids.length === 0)
+        return [];
+    const scriptMeta = await buildMetaIndex(repoRoot);
+    if (scriptMeta.size === 0)
+        return [];
+    const lowerToPath = new Map();
+    for (const [guid, scriptPath] of scriptMeta.entries()) {
+        lowerToPath.set(guid.toLowerCase(), scriptPath.replace(/\\/g, '/'));
+    }
+    const scriptPaths = scriptGuids
+        .map((guid) => lowerToPath.get(guid))
+        .filter((value) => Boolean(value))
+        .sort((left, right) => left.localeCompare(right));
+    if (scriptPaths.length > 0) {
+        return [...new Set(scriptPaths)];
+    }
+    return (await glob('**/*.cs', { cwd: repoRoot, nodir: true, dot: false }))
+        .filter((scriptPath) => canonicalKey(path.basename(scriptPath, '.cs')) === targetKey)
+        .sort((left, right) => left.localeCompare(right));
+}
+async function resolveStyleSelectorsForUxml(repoRoot, uxmlPath, uiMeta) {
+    const uxmlSource = await safeRead(path.join(repoRoot, uxmlPath));
+    const parsed = parseUxmlRefs(uxmlSource);
+    const stylePaths = parsed.styles
+        .map((style) => uiMeta.ussGuidToPath.get(style.guid))
+        .filter((value) => Boolean(value));
+    const out = [];
+    for (const ussPath of stylePaths) {
+        const ussSource = await safeRead(path.join(repoRoot, ussPath));
+        for (const selector of parseUssSelectors(ussSource)) {
+            out.push({
+                path: ussPath,
+                line: selector.line,
+                snippet: selector.snippet,
+                selector: selector.selector,
+            });
+        }
+    }
+    return out;
+}
+async function safeRead(filePath) {
+    try {
+        return await fs.readFile(filePath, 'utf-8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return '';
+        throw error;
+    }
+}
+function normalizeUxmlTargetPath(repoRoot, target) {
+    const normalizedTarget = String(target || '').trim().replace(/\\/g, '/');
+    if (!normalizedTarget.toLowerCase().endsWith('.uxml'))
+        return null;
+    const relative = path.isAbsolute(normalizedTarget)
+        ? path.relative(repoRoot, normalizedTarget).replace(/\\/g, '/')
+        : normalizedTarget;
+    if (relative.startsWith('../'))
+        return null;
+    return relative;
+}
+function findExactUxmlPath(targetPath, uxmlGuidToPath) {
+    for (const candidate of uxmlGuidToPath.values()) {
+        if (candidate.toLowerCase() === targetPath.toLowerCase()) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function findGuidForUxmlPath(targetUxmlPath, uxmlGuidToPath) {
+    for (const [guid, assetPath] of uxmlGuidToPath.entries()) {
+        if (assetPath !== targetUxmlPath)
+            continue;
+        if (!/^[0-9a-f]{32}$/i.test(guid))
+            continue;
+        return guid.toLowerCase();
+    }
+    return null;
+}
+function buildStyleSelectorTokenIndex(styles, selectorMode) {
+    const index = new Map();
+    for (const style of styles) {
+        for (const token of extractClassTokens(style.selector, selectorMode)) {
+            const bucket = index.get(token) || [];
+            bucket.push(style);
+            index.set(token, bucket);
+        }
+    }
+    return index;
+}
+function extractClassTokens(selector, selectorMode) {
+    if (selectorMode === 'strict') {
+        const trimmed = selector.trim();
+        if (/^\.[A-Za-z_][A-Za-z0-9_-]*$/.test(trimmed)) {
+            return [trimmed.slice(1)];
+        }
+        return [];
+    }
+    const out = new Set();
+    const pattern = /\.([A-Za-z_][A-Za-z0-9_-]*)/g;
+    let match = pattern.exec(selector);
+    while (match) {
+        const token = normalizeClassToken(match[1]);
+        if (token)
+            out.add(token);
+        match = pattern.exec(selector);
+    }
+    return [...out];
+}
+function normalizeClassToken(value) {
+    return String(value || '').trim();
+}
+function dedupeTraceResults(results) {
+    const seen = new Set();
+    const out = [];
+    for (const result of results) {
+        const signature = result.evidence_chain.map((hop) => `${hop.path}:${hop.line}:${hop.snippet}`).join('|');
+        if (seen.has(signature))
+            continue;
+        seen.add(signature);
+        const score = result.score;
+        out.push({
+            ...result,
+            confidence: toConfidence(score),
+        });
+    }
+    return out;
+}
+function toConfidence(score) {
+    const value = Number(score || 0);
+    if (value >= 7)
+        return 'high';
+    if (value >= 4)
+        return 'medium';
+    return 'low';
+}
+function scoreSelectorBindingMatch(binding, styleEvidence, targetKey) {
+    let score = 0;
+    if (binding.source === 'resource_chain') {
+        score += 6;
+    }
+    const scriptBaseKey = canonicalKey(path.basename(binding.path, '.cs'));
+    if (scriptBaseKey === targetKey) {
+        score += 4;
+    }
+    const normalizedSelector = styleEvidence.selector.trim();
+    const exactSelector = `.${binding.className}`;
+    if (normalizedSelector === exactSelector) {
+        score += 2;
+    }
+    if (normalizedSelector.startsWith(`${exactSelector} `)) {
+        score += 1;
+    }
+    return score;
+}

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

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

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

@@ -0,0 +1,183 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runUnityUiTrace } from './ui-trace.js';
+const here = path.dirname(fileURLToPath(import.meta.url));
+const fixtureRoot = path.resolve(here, '../../../src/core/unity/__fixtures__/mini-unity-ui');
+test('resolves asset_refs with strict path+line evidence chain', async () => {
+    const out = await runUnityUiTrace({
+        repoRoot: fixtureRoot,
+        target: 'EliteBossScreenController',
+        goal: 'asset_refs',
+    });
+    assert.equal(out.goal, 'asset_refs');
+    assert.equal(out.results.length, 1);
+    assert.equal(out.results[0].evidence_chain.every((hop) => Boolean(hop.path) && hop.line > 0), true);
+});
+test('resolves template_refs from target uxml', async () => {
+    const out = await runUnityUiTrace({
+        repoRoot: fixtureRoot,
+        target: 'Assets/UI/Screens/DressUpScreenNew.uxml',
+        goal: 'template_refs',
+    });
+    assert.equal(out.goal, 'template_refs');
+    assert.equal(out.results.length, 1);
+    assert.equal(out.results[0].evidence_chain[1].path, 'Assets/UI/Components/TooltipBox.uxml');
+});
+test('resolves selector_bindings for static csharp selector usage', async () => {
+    const out = await runUnityUiTrace({
+        repoRoot: fixtureRoot,
+        target: 'EliteBossScreenController',
+        goal: 'selector_bindings',
+    });
+    assert.equal(out.goal, 'selector_bindings');
+    assert.equal(out.results.length, 1);
+    assert.equal(out.results[0].evidence_chain.every((hop) => Boolean(hop.path) && hop.line > 0), true);
+});
+test('resolves selector_bindings when target is a UXML path', async () => {
+    const out = await runUnityUiTrace({
+        repoRoot: fixtureRoot,
+        target: 'Assets/UI/Screens/EliteBossScreenNew.uxml',
+        goal: 'selector_bindings',
+    });
+    assert.equal(out.goal, 'selector_bindings');
+    assert.equal(out.results.length, 1);
+    assert.equal(out.results[0].evidence_chain[0].path.endsWith('.cs'), true);
+    assert.equal(out.results[0].evidence_chain[1].path.endsWith('.uss'), true);
+});
+test('selector_bindings path target uses UXML->resource->m_Script chain before filename fallback', async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-ui-trace-selector-chain-'));
+    await fs.mkdir(path.join(tempRoot, 'Assets/UI/Screens'), { recursive: true });
+    await fs.mkdir(path.join(tempRoot, 'Assets/UI/Styles'), { recursive: true });
+    await fs.mkdir(path.join(tempRoot, 'Assets/Prefabs'), { recursive: true });
+    await fs.mkdir(path.join(tempRoot, 'Assets/Scripts'), { recursive: true });
+    await fs.writeFile(path.join(tempRoot, 'Assets/UI/Screens/FeaturePanelNew.uxml'), '<ui:UXML xmlns:ui="UnityEngine.UIElements"><ui:Style src="project://database/Assets/UI/Styles/FeaturePanel.uss?guid=bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb&amp;type=3" /></ui:UXML>\n', 'utf-8');
+    await fs.writeFile(path.join(tempRoot, 'Assets/UI/Screens/FeaturePanelNew.uxml.meta'), 'fileFormatVersion: 2\nguid: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\n', 'utf-8');
+    await fs.writeFile(path.join(tempRoot, 'Assets/UI/Styles/FeaturePanel.uss'), '.feature-panel { color: red; }\n', 'utf-8');
+    await fs.writeFile(path.join(tempRoot, 'Assets/UI/Styles/FeaturePanel.uss.meta'), 'fileFormatVersion: 2\nguid: bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\n', 'utf-8');
+    await fs.writeFile(path.join(tempRoot, 'Assets/Scripts/PanelBinder.cs'), 'public class PanelBinder { void Bind() { root.AddToClassList("feature-panel"); } }\n', 'utf-8');
+    await fs.writeFile(path.join(tempRoot, 'Assets/Scripts/PanelBinder.cs.meta'), 'fileFormatVersion: 2\nguid: cccccccccccccccccccccccccccccccc\n', 'utf-8');
+    await fs.writeFile(path.join(tempRoot, 'Assets/Prefabs/FeaturePanel.prefab'), [
+        '%YAML 1.1',
+        '--- !u!114 &11400000',
+        'MonoBehaviour:',
+        '  m_Script: {fileID: 11500000, guid: cccccccccccccccccccccccccccccccc, type: 3}',
+        '  runtimeViewAsset: {fileID: 9197481963319205126, guid: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa, type: 3}',
+    ].join('\n'), 'utf-8');
+    const out = await runUnityUiTrace({
+        repoRoot: tempRoot,
+        target: 'Assets/UI/Screens/FeaturePanelNew.uxml',
+        goal: 'selector_bindings',
+    });
+    assert.equal(out.results.length, 1);
+    assert.equal(out.results[0].evidence_chain[0].path, 'Assets/Scripts/PanelBinder.cs');
+    assert.equal(out.results[0].evidence_chain[1].path, 'Assets/UI/Styles/FeaturePanel.uss');
+    await fs.rm(tempRoot, { recursive: true, force: true });
+});
+test('selector_bindings matches class token inside composite USS selectors', async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-ui-trace-composite-selector-'));
+    await fs.mkdir(path.join(tempRoot, 'Assets/UI/Screens'), { recursive: true });
+    await fs.mkdir(path.join(tempRoot, 'Assets/UI/Styles'), { recursive: true });
+    await fs.mkdir(path.join(tempRoot, 'Assets/Prefabs'), { recursive: true });
+    await fs.mkdir(path.join(tempRoot, 'Assets/Scripts'), { recursive: true });
+    await fs.writeFile(path.join(tempRoot, 'Assets/UI/Screens/CompositePanelNew.uxml'), '<ui:UXML xmlns:ui="UnityEngine.UIElements"><ui:Style src="project://database/Assets/UI/Styles/CompositePanel.uss?guid=bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb&amp;type=3" /></ui:UXML>\n', 'utf-8');
+    await fs.writeFile(path.join(tempRoot, 'Assets/UI/Screens/CompositePanelNew.uxml.meta'), 'fileFormatVersion: 2\nguid: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\n', 'utf-8');
+    await fs.writeFile(path.join(tempRoot, 'Assets/UI/Styles/CompositePanel.uss'), '.isLock .preview-icon { opacity: 0.4; }\n', 'utf-8');
+    await fs.writeFile(path.join(tempRoot, 'Assets/UI/Styles/CompositePanel.uss.meta'), 'fileFormatVersion: 2\nguid: bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\n', 'utf-8');
+    await fs.writeFile(path.join(tempRoot, 'Assets/Scripts/CompositeBinder.cs'), 'public class CompositeBinder { void Bind() { root.AddToClassList("isLock"); } }\n', 'utf-8');
+    await fs.writeFile(path.join(tempRoot, 'Assets/Scripts/CompositeBinder.cs.meta'), 'fileFormatVersion: 2\nguid: cccccccccccccccccccccccccccccccc\n', 'utf-8');
+    await fs.writeFile(path.join(tempRoot, 'Assets/Prefabs/CompositePanel.prefab'), [
+        '%YAML 1.1',
+        '--- !u!114 &11400000',
+        'MonoBehaviour:',
+        '  m_Script: {fileID: 11500000, guid: cccccccccccccccccccccccccccccccc, type: 3}',
+        '  runtimeViewAsset: {fileID: 9197481963319205126, guid: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa, type: 3}',
+    ].join('\n'), 'utf-8');
+    const out = await runUnityUiTrace({
+        repoRoot: tempRoot,
+        target: 'Assets/UI/Screens/CompositePanelNew.uxml',
+        goal: 'selector_bindings',
+    });
+    assert.equal(out.results.length, 1);
+    assert.equal(out.results[0].evidence_chain[0].path, 'Assets/Scripts/CompositeBinder.cs');
+    assert.equal(out.results[0].evidence_chain[1].path, 'Assets/UI/Styles/CompositePanel.uss');
+    await fs.rm(tempRoot, { recursive: true, force: true });
+});
+test('selector_bindings ranks resource-chain matches ahead of name-fallback matches', async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-ui-trace-ranking-'));
+    await fs.mkdir(path.join(tempRoot, 'Assets/UI/Screens'), { recursive: true });
+    await fs.mkdir(path.join(tempRoot, 'Assets/UI/Styles'), { recursive: true });
+    await fs.mkdir(path.join(tempRoot, 'Assets/Prefabs'), { recursive: true });
+    await fs.mkdir(path.join(tempRoot, 'Assets/Scripts'), { recursive: true });
+    await fs.writeFile(path.join(tempRoot, 'Assets/UI/Screens/RankPanelNew.uxml'), '<ui:UXML xmlns:ui="UnityEngine.UIElements"><ui:Style src="project://database/Assets/UI/Styles/RankPanel.uss?guid=bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb&amp;type=3" /></ui:UXML>\n', 'utf-8');
+    await fs.writeFile(path.join(tempRoot, 'Assets/UI/Screens/RankPanelNew.uxml.meta'), 'fileFormatVersion: 2\nguid: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\n', 'utf-8');
+    await fs.writeFile(path.join(tempRoot, 'Assets/UI/Styles/RankPanel.uss'), '.active .rank-icon { opacity: 1; }\n', 'utf-8');
+    await fs.writeFile(path.join(tempRoot, 'Assets/UI/Styles/RankPanel.uss.meta'), 'fileFormatVersion: 2\nguid: bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\n', 'utf-8');
+    await fs.writeFile(path.join(tempRoot, 'Assets/Scripts/ResourceDriver.cs'), 'public class ResourceDriver { void Bind() { root.AddToClassList("active"); } }\n', 'utf-8');
+    await fs.writeFile(path.join(tempRoot, 'Assets/Scripts/ResourceDriver.cs.meta'), 'fileFormatVersion: 2\nguid: cccccccccccccccccccccccccccccccc\n', 'utf-8');
+    await fs.writeFile(path.join(tempRoot, 'Assets/Scripts/RankPanel.cs'), 'public class RankPanel { void Bind() { root.AddToClassList("active"); } }\n', 'utf-8');
+    await fs.writeFile(path.join(tempRoot, 'Assets/Scripts/RankPanel.cs.meta'), 'fileFormatVersion: 2\nguid: dddddddddddddddddddddddddddddddd\n', 'utf-8');
+    await fs.writeFile(path.join(tempRoot, 'Assets/Prefabs/RankPanel.prefab'), [
+        '%YAML 1.1',
+        '--- !u!114 &11400000',
+        'MonoBehaviour:',
+        '  m_Script: {fileID: 11500000, guid: cccccccccccccccccccccccccccccccc, type: 3}',
+        '  runtimeViewAsset: {fileID: 9197481963319205126, guid: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa, type: 3}',
+    ].join('\n'), 'utf-8');
+    const out = await runUnityUiTrace({
+        repoRoot: tempRoot,
+        target: 'Assets/UI/Screens/RankPanelNew.uxml',
+        goal: 'selector_bindings',
+    });
+    assert.equal(out.results.length, 2);
+    assert.equal(out.results[0].evidence_chain[0].path, 'Assets/Scripts/ResourceDriver.cs');
+    assert.equal(out.results[1].evidence_chain[0].path, 'Assets/Scripts/RankPanel.cs');
+    assert.equal((out.results[0].score || 0) > (out.results[1].score || 0), true);
+    assert.equal(out.results[0].confidence, 'high');
+    assert.equal(out.results[1].confidence, 'medium');
+    await fs.rm(tempRoot, { recursive: true, force: true });
+});
+test('enforces unique-result gate and returns ambiguity diagnostics', async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-ui-trace-ambiguity-'));
+    await fs.cp(fixtureRoot, tempRoot, { recursive: true });
+    await fs.writeFile(path.join(tempRoot, 'Assets/UI/Screens/EliteBossScreen.uxml'), '<ui:UXML xmlns:ui="UnityEngine.UIElements"><ui:VisualElement /></ui:UXML>\n', 'utf-8');
+    await fs.writeFile(path.join(tempRoot, 'Assets/UI/Screens/EliteBossScreen.uxml.meta'), 'fileFormatVersion: 2\nguid: 12121212121212121212121212121212\n', 'utf-8');
+    const out = await runUnityUiTrace({
+        repoRoot: tempRoot,
+        target: 'EliteBossScreenController',
+        goal: 'asset_refs',
+    });
+    assert.deepEqual(out.results, []);
+    assert.equal(out.diagnostics[0].code, 'ambiguous');
+    assert.equal(Boolean(out.diagnostics[0].candidates[0].path), true);
+    assert.equal(out.diagnostics[0].candidates[0].line > 0, true);
+    await fs.rm(tempRoot, { recursive: true, force: true });
+});
+test('treats existing UXML path target as unique even when canonical names collide', async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-ui-trace-path-'));
+    await fs.cp(fixtureRoot, tempRoot, { recursive: true });
+    await fs.mkdir(path.join(tempRoot, 'Assets/UI/Legacy'), { recursive: true });
+    await fs.writeFile(path.join(tempRoot, 'Assets/UI/Legacy/EliteBossScreen.uxml'), '<ui:UXML xmlns:ui="UnityEngine.UIElements"><ui:VisualElement /></ui:UXML>\n', 'utf-8');
+    await fs.writeFile(path.join(tempRoot, 'Assets/UI/Legacy/EliteBossScreen.uxml.meta'), 'fileFormatVersion: 2\nguid: 34343434343434343434343434343434\n', 'utf-8');
+    const out = await runUnityUiTrace({
+        repoRoot: tempRoot,
+        target: 'Assets/UI/Screens/EliteBossScreenNew.uxml',
+        goal: 'asset_refs',
+    });
+    assert.equal(out.diagnostics.length, 0);
+    assert.equal(out.results.length, 1);
+    assert.equal(out.results[0].evidence_chain[1].path, 'Assets/UI/Screens/EliteBossScreenNew.uxml');
+    await fs.rm(tempRoot, { recursive: true, force: true });
+});
+test('ensures no graph mutations occur in query-time engine', async () => {
+    const mockGraphAddRelationship = () => { };
+    await runUnityUiTrace({
+        repoRoot: fixtureRoot,
+        target: 'EliteBossScreenController',
+        goal: 'asset_refs',
+    });
+    assert.equal(typeof mockGraphAddRelationship, 'function');
+});

package/dist/core/unity/uss-selector-parser.d.ts

@@ -0,0 +1,6 @@
+export interface UssSelectorEvidence {
+    selector: string;
+    line: number;
+    snippet: string;
+}
+export declare function parseUssSelectors(content: string): UssSelectorEvidence[];

package/dist/core/unity/uss-selector-parser.js

@@ -0,0 +1,21 @@
+export function parseUssSelectors(content) {
+    const out = [];
+    const lines = content.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        if (!line.includes('{'))
+            continue;
+        const selectorChunk = line.split('{', 1)[0];
+        const rawSelectors = selectorChunk.split(',').map((item) => item.trim()).filter(Boolean);
+        for (const selector of rawSelectors) {
+            if (!selector.startsWith('.'))
+                continue;
+            out.push({
+                selector,
+                line: i + 1,
+                snippet: line.trim(),
+            });
+        }
+    }
+    return out;
+}

package/dist/core/unity/uss-selector-parser.test.d.ts

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

package/dist/core/unity/uss-selector-parser.test.js

@@ -0,0 +1,13 @@
+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 { parseUssSelectors } from './uss-selector-parser.js';
+const here = path.dirname(fileURLToPath(import.meta.url));
+const fixtureRoot = path.resolve(here, '../../../src/core/unity/__fixtures__/mini-unity-ui');
+test('extracts uss selectors with line evidence', async () => {
+    const source = await fs.readFile(path.join(fixtureRoot, 'Assets/UI/Styles/EliteBossScreenNew.uss'), 'utf-8');
+    const selectors = parseUssSelectors(source);
+    assert.equal(selectors.some((entry) => entry.selector === '.tooltip-box' && entry.line > 0), true);
+});

package/dist/core/unity/uxml-ref-parser.d.ts

@@ -0,0 +1,10 @@
+export interface UxmlRefEvidence {
+    guid: string;
+    line: number;
+    snippet: string;
+}
+export interface ParsedUxmlRefs {
+    templates: UxmlRefEvidence[];
+    styles: UxmlRefEvidence[];
+}
+export declare function parseUxmlRefs(content: string): ParsedUxmlRefs;

package/dist/core/unity/uxml-ref-parser.js

@@ -0,0 +1,22 @@
+const GUID_PARAM_PATTERN = /\bguid=([0-9a-f]{32})\b/i;
+export function parseUxmlRefs(content) {
+    const templates = [];
+    const styles = [];
+    const lines = content.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        const guidMatch = line.match(GUID_PARAM_PATTERN);
+        if (!guidMatch)
+            continue;
+        const entry = {
+            guid: guidMatch[1].toLowerCase(),
+            line: i + 1,
+            snippet: line.trim(),
+        };
+        if (/<\s*(?:[A-Za-z_][\w.-]*\s*:\s*)?Template\b/i.test(line))
+            templates.push(entry);
+        if (/<\s*(?:[A-Za-z_][\w.-]*\s*:\s*)?Style\b/i.test(line))
+            styles.push(entry);
+    }
+    return { templates, styles };
+}

package/dist/core/unity/uxml-ref-parser.test.d.ts

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

package/dist/core/unity/uxml-ref-parser.test.js

@@ -0,0 +1,31 @@
+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 { parseUxmlRefs } from './uxml-ref-parser.js';
+const here = path.dirname(fileURLToPath(import.meta.url));
+const fixtureRoot = path.resolve(here, '../../../src/core/unity/__fixtures__/mini-unity-ui');
+test('extracts uxml template/style refs with line evidence', async () => {
+    const source = await fs.readFile(path.join(fixtureRoot, 'Assets/UI/Screens/EliteBossScreenNew.uxml'), 'utf-8');
+    const out = parseUxmlRefs(source);
+    assert.equal(out.templates.length > 0, true);
+    assert.equal(out.styles.length > 0, true);
+    assert.equal(out.templates[0].guid, 'cccccccccccccccccccccccccccccccc');
+    assert.equal(out.styles[0].guid, 'dddddddddddddddddddddddddddddddd');
+    assert.equal(out.templates[0].line > 0, true);
+    assert.equal(out.styles[0].line > 0, true);
+});
+test('supports namespaced ui:Template and ui:Style tags', () => {
+    const source = [
+        '<ui:UXML xmlns:ui="UnityEngine.UIElements">',
+        '  <ui:Style src="project://database/Assets/UI/Styles/A.uss?guid=11111111111111111111111111111111&amp;type=3" />',
+        '  <ui:Template src="project://database/Assets/UI/Components/B.uxml?guid=22222222222222222222222222222222&amp;type=3" />',
+        '</ui:UXML>',
+    ].join('\n');
+    const out = parseUxmlRefs(source);
+    assert.equal(out.styles.length, 1);
+    assert.equal(out.templates.length, 1);
+    assert.equal(out.styles[0].guid, '11111111111111111111111111111111');
+    assert.equal(out.templates[0].guid, '22222222222222222222222222222222');
+});