@veewo/gitnexus 1.3.8 → 1.3.10

package/dist/core/unity/resolver.js

@@ -0,0 +1,384 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { glob } from 'glob';
+import { buildMetaIndex } from './meta-index.js';
+import { mergeOverrideChain } from './override-merger.js';
+import { findGuidHits } from './resource-hit-scanner.js';
+import { parseUnityYamlObjects } from './yaml-object-graph.js';
+export async function resolveUnityBindings(input) {
+    const scriptPath = await resolveSymbolScriptPath(input.repoRoot, input.symbol, input.scanContext);
+    const scriptGuid = await resolveScriptGuid(input.repoRoot, scriptPath, input.scanContext);
+    const hits = input.scanContext
+        ? (input.scanContext.guidToResourceHits.get(scriptGuid) ?? [])
+        : await findGuidHits(input.repoRoot, scriptGuid);
+    const resourceBindings = [];
+    const unityDiagnostics = [];
+    for (const hit of hits) {
+        const blocks = await getResourceBlocks(input.repoRoot, hit.resourcePath, input.scanContext);
+        const matchedComponents = blocks.filter((block) => block.objectType === 'MonoBehaviour' && block.fields.m_Script?.includes(scriptGuid));
+        if (matchedComponents.length === 0) {
+            unityDiagnostics.push(`No MonoBehaviour block matched script guid ${scriptGuid} in ${hit.resourcePath}.`);
+            continue;
+        }
+        for (const block of matchedComponents) {
+            const resolved = resolveBindingForComponent(block, blocks, hit, input.scanContext);
+            resourceBindings.push({
+                resourcePath: hit.resourcePath,
+                resourceType: hit.resourceType,
+                bindingKind: resolved.bindingKind,
+                componentObjectId: block.objectId,
+                evidence: {
+                    line: hit.line,
+                    lineText: hit.lineText,
+                },
+                serializedFields: resolved.serializedFields,
+                resolvedReferences: resolved.resolvedReferences,
+                assetRefPaths: extractAssetRefPathReferences(resolved.serializedFields),
+            });
+        }
+    }
+    return {
+        symbol: input.symbol,
+        scriptPath,
+        scriptGuid,
+        resourceBindings,
+        serializedFields: aggregateSerializedFields(resourceBindings),
+        unityDiagnostics,
+    };
+}
+export function hasCoverage(resultSet) {
+    return {
+        hasScalar: resultSet.some((result) => result.serializedFields.scalarFields.length > 0),
+        hasReference: resultSet.some((result) => result.serializedFields.referenceFields.length > 0),
+    };
+}
+async function resolveSymbolScriptPath(repoRoot, symbol, scanContext) {
+    const contextHit = scanContext?.symbolToScriptPath.get(symbol);
+    if (contextHit) {
+        return normalizePath(contextHit);
+    }
+    const scriptFiles = (await glob('**/*.cs', {
+        cwd: repoRoot,
+        nodir: true,
+        dot: false,
+    })).sort((left, right) => left.localeCompare(right));
+    const basenameMatches = scriptFiles.filter((filePath) => path.basename(filePath, '.cs') === symbol);
+    if (basenameMatches.length === 1) {
+        return normalizePath(basenameMatches[0]);
+    }
+    const symbolRegex = new RegExp(`\\b(class|struct|interface)\\s+${escapeRegex(symbol)}\\b`);
+    const contentMatches = [];
+    for (const filePath of scriptFiles) {
+        const content = await fs.readFile(path.join(repoRoot, filePath), 'utf-8');
+        if (symbolRegex.test(content)) {
+            contentMatches.push(normalizePath(filePath));
+        }
+    }
+    if (contentMatches.length === 1) {
+        return contentMatches[0];
+    }
+    if (contentMatches.length > 1 || basenameMatches.length > 1) {
+        throw new Error(`Unity symbol "${symbol}" is ambiguous.`);
+    }
+    throw new Error(`Unity symbol "${symbol}" was not found under ${repoRoot}.`);
+}
+async function resolveScriptGuid(repoRoot, scriptPath, scanContext) {
+    const contextGuid = scanContext?.scriptPathToGuid.get(normalizePath(scriptPath));
+    if (contextGuid) {
+        return contextGuid;
+    }
+    const metaIndex = await buildMetaIndex(repoRoot);
+    for (const [guid, indexedScriptPath] of metaIndex.entries()) {
+        if (normalizePath(indexedScriptPath) === normalizePath(scriptPath)) {
+            return guid;
+        }
+    }
+    throw new Error(`No .meta guid found for ${scriptPath}.`);
+}
+async function getResourceBlocks(repoRoot, resourcePath, scanContext) {
+    const normalizedResourcePath = normalizePath(resourcePath);
+    const cached = scanContext?.resourceDocCache.get(normalizedResourcePath);
+    if (cached) {
+        return cached;
+    }
+    const absoluteResourcePath = path.join(repoRoot, normalizedResourcePath);
+    const raw = await fs.readFile(absoluteResourcePath, 'utf-8');
+    const blocks = parseUnityYamlObjects(raw);
+    scanContext?.resourceDocCache.set(normalizedResourcePath, blocks);
+    return blocks;
+}
+function resolveBindingForComponent(componentBlock, blocks, hit, scanContext) {
+    const directLayer = createLayerFromFields(componentBlock.fields, baseLayerName(hit.resourceType));
+    const layers = [directLayer];
+    let bindingKind = inferBindingKind(componentBlock, hit.resourceType);
+    const prefabInstanceId = extractFileId(componentBlock.fields.m_PrefabInstance);
+    if (prefabInstanceId) {
+        const prefabInstanceBlock = blocks.find((block) => block.objectType === 'PrefabInstance' && block.objectId === prefabInstanceId);
+        if (prefabInstanceBlock?.fields.m_Modification) {
+            const modificationLayer = createLayerFromModification(prefabInstanceBlock.fields.m_Modification, componentBlock.objectId, hit.resourceType === 'scene' ? 'scene' : 'prefab-instance');
+            if (modificationLayer) {
+                layers.push(modificationLayer);
+                if (hit.resourceType === 'scene') {
+                    bindingKind = 'scene-override';
+                }
+            }
+        }
+    }
+    const merged = mergeOverrideChain(layers);
+    return {
+        bindingKind,
+        serializedFields: toSerializedFields(merged),
+        resolvedReferences: toResolvedReferences(merged, blocks, hit.resourcePath, scanContext?.assetGuidToPath),
+    };
+}
+function createLayerFromFields(fields, sourceLayer) {
+    const scalarFields = {};
+    const referenceFields = {};
+    for (const [name, rawValue] of Object.entries(fields)) {
+        if (name.startsWith('m_'))
+            continue;
+        const reference = parseObjectReference(rawValue);
+        if (reference) {
+            referenceFields[name] = reference;
+            continue;
+        }
+        scalarFields[name] = {
+            value: rawValue.trim(),
+            valueType: inferValueType(rawValue),
+        };
+    }
+    return { sourceLayer, scalarFields, referenceFields };
+}
+function createLayerFromModification(modificationBody, targetObjectId, sourceLayer) {
+    const scalarFields = {};
+    const referenceFields = {};
+    const entryPattern = /-\s*target:\s*\{fileID:\s*(\d+)[^}]*\}\s*\n\s*propertyPath:\s*([^\n]+)\s*\n\s*value:\s*([^\n]*)\s*\n\s*objectReference:\s*(\{[^\n]*\})/g;
+    let match = entryPattern.exec(modificationBody);
+    while (match) {
+        const [, fileId, propertyPath, rawValue, rawObjectReference] = match;
+        if (fileId === targetObjectId && !propertyPath.startsWith('m_')) {
+            const normalizedValue = rawValue.trim();
+            if (normalizedValue.length > 0) {
+                scalarFields[propertyPath] = {
+                    value: normalizedValue,
+                    valueType: inferValueType(normalizedValue),
+                };
+            }
+            else {
+                const reference = parseObjectReference(rawObjectReference);
+                if (reference) {
+                    referenceFields[propertyPath] = reference;
+                }
+            }
+        }
+        match = entryPattern.exec(modificationBody);
+    }
+    if (Object.keys(scalarFields).length === 0 && Object.keys(referenceFields).length === 0) {
+        return null;
+    }
+    return { sourceLayer, scalarFields, referenceFields };
+}
+function toSerializedFields(merged) {
+    return {
+        scalarFields: Object.values(merged.scalarFields).sort((left, right) => left.name.localeCompare(right.name)),
+        referenceFields: Object.values(merged.referenceFields).sort((left, right) => left.name.localeCompare(right.name)),
+    };
+}
+const ASSET_REF_FIELD_RE = /^\s*([A-Za-z0-9_]*Ref):\s*$/;
+const RELATIVE_PATH_RE = /^\s*_relativePath:\s*(.*)$/;
+function unquote(value) {
+    return value.replace(/^"|"$/g, '');
+}
+function isSpriteRelativePath(value) {
+    const normalized = value.trim().toLowerCase();
+    if (!normalized)
+        return false;
+    if (normalized.includes('/sprites/'))
+        return true;
+    return /\.(png|jpg|jpeg|tga|psd|webp|spriteatlas|spriteatlasv2)$/.test(normalized);
+}
+export function extractAssetRefPathReferences(serializedFields) {
+    const refs = [];
+    for (const scalarField of serializedFields.scalarFields) {
+        const text = String(scalarField.value || '');
+        if (!text)
+            continue;
+        let currentFieldName = scalarField.name;
+        const lines = text.split(/\r?\n/);
+        for (const line of lines) {
+            const fieldMatch = line.match(ASSET_REF_FIELD_RE);
+            if (fieldMatch) {
+                currentFieldName = fieldMatch[1];
+                continue;
+            }
+            const relativeMatch = line.match(RELATIVE_PATH_RE);
+            if (!relativeMatch) {
+                continue;
+            }
+            const relativePath = unquote((relativeMatch[1] || '').trim());
+            refs.push({
+                parentFieldName: scalarField.name,
+                fieldName: currentFieldName,
+                relativePath,
+                sourceLayer: scalarField.sourceLayer || 'unknown',
+                isEmpty: relativePath.length === 0,
+                isSprite: isSpriteRelativePath(relativePath),
+            });
+        }
+    }
+    return refs;
+}
+function aggregateSerializedFields(resourceBindings) {
+    return {
+        scalarFields: resourceBindings.flatMap((binding) => binding.serializedFields.scalarFields),
+        referenceFields: resourceBindings.flatMap((binding) => binding.serializedFields.referenceFields),
+    };
+}
+function toResolvedReferences(merged, blocks, resourcePath, assetGuidToPath) {
+    const references = [];
+    const blocksById = new Map();
+    for (const block of blocks) {
+        blocksById.set(block.objectId, block);
+    }
+    for (const reference of Object.values(merged.referenceFields)) {
+        references.push(resolveReferenceCandidate({
+            fieldName: reference.name,
+            sourceLayer: reference.sourceLayer,
+            fileId: reference.fileId,
+            guid: reference.guid,
+            fromList: false,
+        }, blocksById, resourcePath, assetGuidToPath));
+    }
+    for (const scalar of Object.values(merged.scalarFields)) {
+        const candidates = parseListReferenceCandidates(scalar.name, scalar.sourceLayer, scalar.value);
+        references.push(...candidates.map((candidate) => resolveReferenceCandidate(candidate, blocksById, resourcePath, assetGuidToPath)));
+    }
+    return references;
+}
+function parseListReferenceCandidates(fieldName, sourceLayer, rawValue) {
+    const trimmed = rawValue.trim();
+    if (!trimmed.startsWith('-'))
+        return [];
+    const candidates = [];
+    const lines = trimmed.split(/\r?\n/);
+    let listIndex = 0;
+    for (const line of lines) {
+        const lineTrimmed = line.trim();
+        if (!lineTrimmed.startsWith('-'))
+            continue;
+        const entryMatch = lineTrimmed.match(/^-\s*(\{.*\})\s*$/);
+        if (!entryMatch)
+            continue;
+        const parsed = parseObjectReference(entryMatch[1]);
+        if (!parsed)
+            continue;
+        candidates.push({
+            fieldName,
+            sourceLayer,
+            fileId: parsed.fileId,
+            guid: parsed.guid,
+            fromList: true,
+            listIndex,
+        });
+        listIndex += 1;
+    }
+    return candidates;
+}
+function resolveReferenceCandidate(candidate, blocksById, resourcePath, assetGuidToPath) {
+    const fileId = candidate.fileId;
+    const guid = candidate.guid;
+    const normalizedGuid = guid ? guid.toLowerCase() : undefined;
+    if (fileId === '0') {
+        return {
+            ...candidate,
+            resolution: 'null',
+        };
+    }
+    if (normalizedGuid && !isBuiltInGuid(normalizedGuid)) {
+        const assetPath = assetGuidToPath?.get(normalizedGuid) || assetGuidToPath?.get(guid);
+        return {
+            ...candidate,
+            resolution: assetPath ? 'external-asset' : 'unresolved',
+            target: assetPath ? { assetPath } : undefined,
+        };
+    }
+    if (fileId) {
+        const targetBlock = blocksById.get(fileId);
+        if (targetBlock) {
+            return {
+                ...candidate,
+                resolution: 'local-object',
+                target: {
+                    resourcePath,
+                    objectId: targetBlock.objectId,
+                    objectType: targetBlock.objectType,
+                    gameObjectName: resolveGameObjectName(targetBlock, blocksById),
+                },
+            };
+        }
+    }
+    return {
+        ...candidate,
+        resolution: 'unresolved',
+    };
+}
+function resolveGameObjectName(block, blocksById) {
+    if (block.objectType === 'GameObject') {
+        return block.fields.m_Name?.trim() || undefined;
+    }
+    const gameObjectRef = parseObjectReference(block.fields.m_GameObject || '');
+    const gameObjectId = gameObjectRef?.fileId;
+    if (!gameObjectId)
+        return undefined;
+    const gameObjectBlock = blocksById.get(gameObjectId);
+    if (!gameObjectBlock || gameObjectBlock.objectType !== 'GameObject')
+        return undefined;
+    return gameObjectBlock.fields.m_Name?.trim() || undefined;
+}
+function isBuiltInGuid(guid) {
+    return /^0+$/.test(guid);
+}
+function inferBindingKind(componentBlock, resourceType) {
+    if (componentBlock.stripped && resourceType === 'scene')
+        return 'scene-override';
+    if (componentBlock.stripped)
+        return 'nested';
+    if (componentBlock.fields.m_PrefabInstance)
+        return 'prefab-instance';
+    return 'direct';
+}
+function baseLayerName(resourceType) {
+    if (resourceType === 'scene')
+        return 'scene';
+    if (resourceType === 'asset')
+        return 'asset';
+    return 'prefab';
+}
+function extractFileId(rawValue) {
+    if (!rawValue)
+        return undefined;
+    return rawValue.match(/fileID:\s*(\d+)/)?.[1];
+}
+function parseObjectReference(rawValue) {
+    const trimmed = rawValue.trim();
+    if (!trimmed.startsWith('{') || !trimmed.includes('fileID:')) {
+        return null;
+    }
+    const fileId = trimmed.match(/fileID:\s*(-?\d+)/)?.[1];
+    const guid = trimmed.match(/guid:\s*([0-9a-f]{32})/i)?.[1];
+    return { fileId, guid };
+}
+function inferValueType(rawValue) {
+    const trimmed = rawValue.trim();
+    if (/^-?\d+(\.\d+)?$/.test(trimmed))
+        return 'number';
+    if (/^(true|false)$/i.test(trimmed))
+        return 'boolean';
+    return 'string';
+}
+function normalizePath(filePath) {
+    return filePath.replace(/\\/g, '/');
+}
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/core/unity/resolver.test.d.ts

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

package/dist/core/unity/resolver.test.js

@@ -0,0 +1,244 @@
+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 { buildUnityScanContext } from './scan-context.js';
+import { extractAssetRefPathReferences, hasCoverage, resolveUnityBindings } from './resolver.js';
+const here = path.dirname(fileURLToPath(import.meta.url));
+const fixtureRoot = path.resolve(here, '../../../src/core/unity/__fixtures__/mini-unity');
+const requiredSamples = ['Global', 'BattleMode', 'PlayerActor', 'MainUIManager'];
+const acceptanceBaseline = {
+    Global: {
+        expectedBindingKinds: ['direct'],
+        minScalarFields: 1,
+        minReferenceFields: 0,
+        requiredScalarFields: ['needPause'],
+        requiredReferenceFields: [],
+    },
+    BattleMode: {
+        expectedBindingKinds: ['direct'],
+        minScalarFields: 1,
+        minReferenceFields: 1,
+        requiredScalarFields: ['battleState'],
+        requiredReferenceFields: ['uiDocument'],
+    },
+    PlayerActor: {
+        expectedBindingKinds: ['direct'],
+        minScalarFields: 1,
+        minReferenceFields: 1,
+        requiredScalarFields: ['walkSpeed'],
+        requiredReferenceFields: ['animatorController'],
+    },
+    MainUIManager: {
+        expectedBindingKinds: ['scene-override'],
+        minScalarFields: 1,
+        minReferenceFields: 1,
+        requiredScalarFields: ['needPause'],
+        requiredReferenceFields: ['mainUIDocument'],
+    },
+};
+test('resolveUnityBindings matches frozen acceptance baseline for required Unity samples', async () => {
+    const results = await Promise.all(requiredSamples.map((symbol) => resolveUnityBindings({ repoRoot: fixtureRoot, symbol })));
+    for (const result of results) {
+        const baseline = acceptanceBaseline[result.symbol];
+        assert.ok(baseline, `Missing acceptance baseline for ${result.symbol}`);
+        const bindingKinds = Array.from(new Set(result.resourceBindings.map((binding) => binding.bindingKind))).sort();
+        assert.ok(result.resourceBindings.length >= 1, `${result.symbol} should have at least one resource binding`);
+        assert.deepEqual(bindingKinds, [...baseline.expectedBindingKinds].sort(), `${result.symbol} binding kinds changed`);
+        assert.ok(result.serializedFields.scalarFields.length >= baseline.minScalarFields, `${result.symbol} scalar field count below baseline`);
+        assert.ok(result.serializedFields.referenceFields.length >= baseline.minReferenceFields, `${result.symbol} reference field count below baseline`);
+        const scalarNames = new Set(result.serializedFields.scalarFields.map((field) => field.name));
+        const referenceNames = new Set(result.serializedFields.referenceFields.map((field) => field.name));
+        for (const fieldName of baseline.requiredScalarFields) {
+            assert.ok(scalarNames.has(fieldName), `${result.symbol} missing scalar field ${fieldName}`);
+        }
+        for (const fieldName of baseline.requiredReferenceFields) {
+            assert.ok(referenceNames.has(fieldName), `${result.symbol} missing reference field ${fieldName}`);
+        }
+    }
+    assert.deepEqual(hasCoverage(results), { hasScalar: true, hasReference: true });
+});
+test('resolveUnityBindings applies PrefabInstance modifications for stripped scene components', async () => {
+    const result = await resolveUnityBindings({ repoRoot: fixtureRoot, symbol: 'MainUIManager' });
+    const needPause = result.serializedFields.scalarFields.find((field) => field.name === 'needPause');
+    const uiDocument = result.serializedFields.referenceFields.find((field) => field.name === 'mainUIDocument');
+    assert.equal(result.resourceBindings[0]?.bindingKind, 'scene-override');
+    assert.equal(needPause?.value, '1');
+    assert.equal(needPause?.sourceLayer, 'scene');
+    assert.equal(uiDocument?.guid, '44444444444444444444444444444444');
+    assert.equal(uiDocument?.sourceLayer, 'scene');
+});
+test('resolveUnityBindings uses provided scan context without repo re-scan', async () => {
+    const context = await buildUnityScanContext({ repoRoot: fixtureRoot });
+    const result = await resolveUnityBindings({ repoRoot: fixtureRoot, symbol: 'MainUIManager', scanContext: context });
+    assert.ok(result.resourceBindings.length > 0);
+});
+test('resource YAML parse is reused across symbols sharing same resource file', async (t) => {
+    const context = await buildUnityScanContext({ repoRoot: fixtureRoot });
+    const scriptPath = context.symbolToScriptPath.get('Global');
+    assert.ok(scriptPath);
+    context.symbolToScriptPath.set('GlobalAlias', scriptPath);
+    const scriptGuid = context.scriptPathToGuid.get(scriptPath);
+    assert.ok(scriptGuid);
+    const targetResourcePath = context.guidToResourceHits.get(scriptGuid)?.[0]?.resourcePath;
+    assert.ok(targetResourcePath);
+    const originalReadFile = fs.readFile.bind(fs);
+    let targetResourceReadCount = 0;
+    t.mock.method(fs, 'readFile', async (...args) => {
+        const fileArg = args[0];
+        const rawPath = typeof fileArg === 'string' ? fileArg : fileArg instanceof URL ? fileArg.pathname : String(fileArg);
+        const normalizedPath = rawPath.replace(/\\/g, '/');
+        if (normalizedPath.endsWith(targetResourcePath)) {
+            targetResourceReadCount += 1;
+        }
+        return originalReadFile(...args);
+    });
+    const first = await resolveUnityBindings({ repoRoot: fixtureRoot, symbol: 'Global', scanContext: context });
+    const second = await resolveUnityBindings({ repoRoot: fixtureRoot, symbol: 'GlobalAlias', scanContext: context });
+    assert.ok(first.resourceBindings.length > 0);
+    assert.ok(second.resourceBindings.length > 0);
+    assert.equal(targetResourceReadCount, 1);
+});
+test('resolveUnityBindings emits structured local/list reference targets for agent consumption', async () => {
+    const result = await resolveUnityBindings({ repoRoot: fixtureRoot, symbol: 'MenuScreenCarrier' });
+    const binding = result.resourceBindings[0];
+    assert.ok(binding);
+    const defaultRef = binding.resolvedReferences.find((ref) => ref.fieldName === 'defaultScreen' && !ref.fromList);
+    assert.equal(defaultRef?.resolution, 'local-object');
+    assert.equal(defaultRef?.target?.objectType, 'GameObject');
+    assert.equal(defaultRef?.target?.gameObjectName, 'ScreenA');
+    const listRefs = binding.resolvedReferences
+        .filter((ref) => ref.fieldName === 'menuScreenList' && ref.fromList)
+        .sort((left, right) => (left.listIndex || 0) - (right.listIndex || 0));
+    assert.equal(listRefs.length, 3);
+    assert.equal(listRefs[0].resolution, 'local-object');
+    assert.equal(listRefs[0].target?.gameObjectName, 'ScreenA');
+    assert.equal(listRefs[1].resolution, 'local-object');
+    assert.equal(listRefs[1].target?.gameObjectName, 'ScreenB');
+    assert.equal(listRefs[2].resolution, 'null');
+});
+test('resolveUnityBindings resolves external guid to asset path when scan context includes asset meta', async () => {
+    const context = await buildUnityScanContext({
+        repoRoot: fixtureRoot,
+        scopedPaths: [
+            'Assets/Scripts/MainUIManager.cs',
+            'Assets/Scripts/MainUIManager.cs.meta',
+            'Assets/Scene/MainUIManager.unity',
+            'Assets/Config/MainUIDocument.asset.meta',
+        ],
+    });
+    const result = await resolveUnityBindings({ repoRoot: fixtureRoot, symbol: 'MainUIManager', scanContext: context });
+    const mainBinding = result.resourceBindings[0];
+    assert.ok(mainBinding);
+    const externalRef = mainBinding.resolvedReferences.find((ref) => ref.fieldName === 'mainUIDocument' && ref.guid === '44444444444444444444444444444444');
+    assert.equal(externalRef?.resolution, 'external-asset');
+    assert.equal(externalRef?.target?.assetPath, 'Assets/Config/MainUIDocument.asset');
+});
+test('resolveUnityBindings supports ScriptableObject .asset resource bindings', async () => {
+    const context = await buildUnityScanContext({
+        repoRoot: fixtureRoot,
+        scopedPaths: [
+            'Assets/Scripts/U2ScriptableConfig.cs',
+            'Assets/Scripts/U2ScriptableConfig.cs.meta',
+            'Assets/Config/U2ScriptableConfig.asset',
+            'Assets/Config/U2ScriptableConfig.asset.meta',
+            'Assets/Config/MainUIDocument.asset.meta',
+        ],
+    });
+    const result = await resolveUnityBindings({ repoRoot: fixtureRoot, symbol: 'U2ScriptableConfig', scanContext: context });
+    const binding = result.resourceBindings[0];
+    assert.ok(binding);
+    assert.equal(binding.resourceType, 'asset');
+    assert.equal(binding.resourcePath, 'Assets/Config/U2ScriptableConfig.asset');
+    assert.deepEqual(binding.serializedFields, result.serializedFields);
+    assert.deepEqual(binding.serializedFields.scalarFields.map((field) => field.name), ['menuScreenList']);
+    assert.deepEqual(binding.serializedFields.referenceFields.map((field) => field.name), ['mainUIDocument']);
+    assert.equal(binding.serializedFields.referenceFields[0]?.sourceLayer, 'asset');
+    const directExternal = binding.resolvedReferences.find((ref) => ref.fieldName === 'mainUIDocument' && !ref.fromList);
+    assert.equal(directExternal?.resolution, 'external-asset');
+    assert.equal(directExternal?.target?.assetPath, 'Assets/Config/MainUIDocument.asset');
+    const listRefs = binding.resolvedReferences
+        .filter((ref) => ref.fieldName === 'menuScreenList' && ref.fromList)
+        .sort((left, right) => (left.listIndex || 0) - (right.listIndex || 0));
+    assert.equal(listRefs.length, 2);
+    assert.equal(listRefs[0]?.resolution, 'null');
+    assert.equal(listRefs[1]?.resolution, 'external-asset');
+});
+test('resolveUnityBindings keeps existing scene serializedFields stable when .asset support is enabled', async () => {
+    const context = await buildUnityScanContext({
+        repoRoot: fixtureRoot,
+        scopedPaths: [
+            'Assets/Scripts/MainUIManager.cs',
+            'Assets/Scripts/MainUIManager.cs.meta',
+            'Assets/Scene/MainUIManager.unity',
+            'Assets/Scripts/U2ScriptableConfig.cs',
+            'Assets/Scripts/U2ScriptableConfig.cs.meta',
+            'Assets/Config/U2ScriptableConfig.asset',
+            'Assets/Config/U2ScriptableConfig.asset.meta',
+            'Assets/Config/MainUIDocument.asset.meta',
+        ],
+    });
+    const result = await resolveUnityBindings({ repoRoot: fixtureRoot, symbol: 'MainUIManager', scanContext: context });
+    const needPause = result.serializedFields.scalarFields.find((field) => field.name === 'needPause');
+    const mainUIDocument = result.serializedFields.referenceFields.find((field) => field.name === 'mainUIDocument');
+    assert.ok(result.resourceBindings.length > 0);
+    assert.equal(needPause?.sourceLayer, 'scene');
+    assert.equal(needPause?.value, '1');
+    assert.equal(mainUIDocument?.sourceLayer, 'scene');
+    assert.equal(mainUIDocument?.guid, '44444444444444444444444444444444');
+});
+test('extractAssetRefPathReferences parses nested _relativePath rows and marks sprite assets', () => {
+    const refs = extractAssetRefPathReferences({
+        scalarFields: [
+            {
+                name: 'Values',
+                sourceLayer: 'asset',
+                value: `
+_Head_Ref:
+  _relativePath: Assets/NEON/Art/Sprites/UI/0_pixle/ui_character_head/hero_head_Nik.png
+_actorPrefabRef:
+  _relativePath: Assets/ActorPrefab/Actor_Nik/V_Actor_Nik.prefab
+`,
+            },
+        ],
+        referenceFields: [],
+    });
+    assert.equal(refs.length, 2);
+    assert.equal(refs[0]?.fieldName, '_Head_Ref');
+    assert.equal(refs[0]?.isSprite, true);
+    assert.equal(refs[1]?.fieldName, '_actorPrefabRef');
+    assert.equal(refs[1]?.isSprite, false);
+});
+test('extractAssetRefPathReferences handles Unity Ref naming variants and stable sprite classification', () => {
+    const refs = extractAssetRefPathReferences({
+        scalarFields: [
+            {
+                name: 'Values',
+                sourceLayer: 'asset',
+                value: `
+_icon_Ref:
+  _relativePath: "Assets/NEON/Art/Sprites/UI/icon_main.PNG"
+actorPrefabRef:
+  _relativePath: Assets/ActorPrefab/Actor_Nik/V_Actor_Nik.prefab
+_atlas_Ref:
+  _relativePath: Assets/Atlas/UI.spriteatlasv2
+_empty_Ref:
+  _relativePath:
+`,
+            },
+        ],
+        referenceFields: [],
+    });
+    assert.equal(refs.length, 4);
+    assert.equal(refs[0]?.fieldName, '_icon_Ref');
+    assert.equal(refs[0]?.relativePath, 'Assets/NEON/Art/Sprites/UI/icon_main.PNG');
+    assert.equal(refs[0]?.isSprite, true);
+    assert.equal(refs[1]?.fieldName, 'actorPrefabRef');
+    assert.equal(refs[1]?.isSprite, false);
+    assert.equal(refs[2]?.fieldName, '_atlas_Ref');
+    assert.equal(refs[2]?.isSprite, true);
+    assert.equal(refs[3]?.fieldName, '_empty_Ref');
+    assert.equal(refs[3]?.isEmpty, true);
+    assert.equal(refs.every((row) => row.parentFieldName === 'Values'), true);
+});

package/dist/core/unity/resource-hit-scanner.d.ts

@@ -0,0 +1,10 @@
+export interface UnityResourceGuidHit {
+    resourcePath: string;
+    resourceType: 'prefab' | 'scene' | 'asset';
+    line: number;
+    lineText: string;
+}
+export interface FindGuidHitsOptions {
+    resourceFiles?: string[];
+}
+export declare function findGuidHits(repoRoot: string, guid: string, options?: FindGuidHitsOptions): Promise<UnityResourceGuidHit[]>;