@veewo/gitnexus 1.3.8 → 1.3.9

package/dist/core/unity/resource-hit-scanner.js

@@ -0,0 +1,60 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { glob } from 'glob';
+export async function findGuidHits(repoRoot, guid, options = {}) {
+    const resourceFiles = await resolveResourceFiles(repoRoot, options.resourceFiles);
+    const hits = [];
+    for (const resourcePath of resourceFiles) {
+        const absolutePath = path.join(repoRoot, resourcePath);
+        let content = '';
+        try {
+            content = await fs.readFile(absolutePath, 'utf-8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                continue;
+            throw error;
+        }
+        const lines = content.split(/\r?\n/);
+        for (let index = 0; index < lines.length; index += 1) {
+            if (!lines[index].includes(guid))
+                continue;
+            hits.push({
+                resourcePath: resourcePath.replace(/\\/g, '/'),
+                resourceType: inferResourceType(resourcePath),
+                line: index + 1,
+                lineText: lines[index],
+            });
+        }
+    }
+    return hits;
+}
+async function resolveResourceFiles(repoRoot, scopedResourceFiles) {
+    if (!scopedResourceFiles || scopedResourceFiles.length === 0) {
+        return (await glob(['**/*.prefab', '**/*.unity', '**/*.asset'], {
+            cwd: repoRoot,
+            nodir: true,
+            dot: false,
+        })).sort((left, right) => left.localeCompare(right));
+    }
+    const normalized = scopedResourceFiles
+        .filter((value) => value.endsWith('.prefab') || value.endsWith('.unity') || value.endsWith('.asset'))
+        .map((value) => normalizeRelativePath(repoRoot, value))
+        .filter((value) => value !== null)
+        .sort((left, right) => left.localeCompare(right));
+    return [...new Set(normalized)];
+}
+function normalizeRelativePath(repoRoot, filePath) {
+    const relativePath = path.isAbsolute(filePath) ? path.relative(repoRoot, filePath) : filePath;
+    const normalized = relativePath.replace(/\\/g, '/');
+    if (normalized.startsWith('../'))
+        return null;
+    return normalized;
+}
+function inferResourceType(resourcePath) {
+    if (resourcePath.endsWith('.prefab'))
+        return 'prefab';
+    if (resourcePath.endsWith('.asset'))
+        return 'asset';
+    return 'scene';
+}

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

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

package/dist/core/unity/resource-hit-scanner.test.js

@@ -0,0 +1,20 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findGuidHits } from './resource-hit-scanner.js';
+const here = path.dirname(fileURLToPath(import.meta.url));
+const fixtureRoot = path.resolve(here, '../../../src/core/unity/__fixtures__/mini-unity');
+test('findGuidHits returns resource hits for matching MonoBehaviour scripts', async () => {
+    const hits = await findGuidHits(fixtureRoot, 'a6d481d58c0b4f646b7106ceaf633d6e');
+    assert.equal(hits.length, 1);
+    assert.equal(hits[0].resourceType, 'scene');
+    assert.equal(hits[0].resourcePath, 'Assets/Scene/Global.unity');
+    assert.equal(hits[0].line, 9);
+});
+test('findGuidHits includes ScriptableObject .asset resources', async () => {
+    const hits = await findGuidHits(fixtureRoot, 'abababababababababababababababab');
+    assert.equal(hits.length, 1);
+    assert.equal(hits[0].resourceType, 'asset');
+    assert.equal(hits[0].resourcePath, 'Assets/Config/U2ScriptableConfig.asset');
+});

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

@@ -0,0 +1,23 @@
+import type { UnityResourceGuidHit } from './resource-hit-scanner.js';
+import type { UnityObjectBlock } from './yaml-object-graph.js';
+export interface BuildScanContextInput {
+    repoRoot: string;
+    scopedPaths?: string[];
+    symbolDeclarations?: UnitySymbolDeclaration[];
+}
+export interface UnitySymbolDeclaration {
+    symbol: string;
+    scriptPath: string;
+}
+export interface UnityScanContext {
+    symbolToScriptPaths: Map<string, string[]>;
+    symbolToCanonicalScriptPath: Map<string, string>;
+    symbolToScriptPath: Map<string, string>;
+    scriptPathToGuid: Map<string, string>;
+    guidToResourceHits: Map<string, UnityResourceGuidHit[]>;
+    serializableSymbols: Set<string>;
+    hostFieldTypeHints: Map<string, Map<string, string>>;
+    assetGuidToPath?: Map<string, string>;
+    resourceDocCache: Map<string, UnityObjectBlock[]>;
+}
+export declare function buildUnityScanContext(input: BuildScanContextInput): Promise<UnityScanContext>;

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

@@ -0,0 +1,318 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { glob } from 'glob';
+import { buildAssetMetaIndex, buildMetaIndex } from './meta-index.js';
+import { buildSerializableTypeIndexFromSources } from './serialized-type-index.js';
+const DECLARATION_PATTERN = /\b(?:class|struct|interface)\s+([A-Za-z_][A-Za-z0-9_]*)\b/g;
+const GUID_IN_LINE_PATTERN = /\bguid:\s*([0-9a-f]{32})\b/gi;
+const RESOURCE_HIT_SCAN_CONCURRENCY = 16;
+export async function buildUnityScanContext(input) {
+    const scriptFiles = input.symbolDeclarations && input.symbolDeclarations.length > 0
+        ? resolveScriptFilesFromSymbolDeclarations(input.repoRoot, input.symbolDeclarations, input.scopedPaths)
+        : await resolveScriptFiles(input.repoRoot, input.scopedPaths);
+    const symbolToScriptPaths = input.symbolDeclarations && input.symbolDeclarations.length > 0
+        ? buildSymbolScriptPathIndexFromDeclarations(input.repoRoot, input.symbolDeclarations, input.scopedPaths)
+        : await buildSymbolScriptPathIndex(input.repoRoot, scriptFiles);
+    const scriptSources = await loadScriptSources(input.repoRoot, scriptFiles);
+    const serializableTypeIndex = buildSerializableTypeIndexFromSources(scriptSources);
+    const metaFiles = scriptFiles.map((scriptPath) => `${scriptPath}.meta`);
+    const guidToScriptPath = await buildMetaIndex(input.repoRoot, { metaFiles });
+    const scriptPathToGuid = new Map();
+    for (const [guid, scriptPath] of guidToScriptPath.entries()) {
+        scriptPathToGuid.set(normalizeSlashes(scriptPath), guid);
+    }
+    const resourceFiles = await resolveResourceFiles(input.repoRoot, input.scopedPaths);
+    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 symbolToCanonicalScriptPath = buildCanonicalScriptPathIndex(symbolToScriptPaths, scriptPathToGuid, guidToResourceHits);
+    const symbolToScriptPath = new Map(symbolToCanonicalScriptPath);
+    return {
+        symbolToScriptPaths,
+        symbolToCanonicalScriptPath,
+        symbolToScriptPath,
+        scriptPathToGuid,
+        guidToResourceHits,
+        serializableSymbols: serializableTypeIndex.serializableSymbols,
+        hostFieldTypeHints: serializableTypeIndex.hostFieldTypeHints,
+        assetGuidToPath,
+        resourceDocCache: new Map(),
+    };
+}
+async function loadScriptSources(repoRoot, scriptFiles) {
+    const sources = [];
+    for (const scriptPath of scriptFiles) {
+        const normalizedPath = normalizeSlashes(scriptPath);
+        try {
+            const content = await fs.readFile(path.join(repoRoot, normalizedPath), 'utf-8');
+            sources.push({ filePath: normalizedPath, content });
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                continue;
+            throw error;
+        }
+    }
+    return sources;
+}
+async function buildSymbolScriptPathIndex(repoRoot, scriptFiles) {
+    const candidates = new Map();
+    for (const scriptPath of scriptFiles) {
+        const normalizedPath = normalizeSlashes(scriptPath);
+        addSymbolCandidate(candidates, path.basename(normalizedPath, '.cs'), normalizedPath);
+        const absolutePath = path.join(repoRoot, normalizedPath);
+        let content = '';
+        try {
+            content = await fs.readFile(absolutePath, 'utf-8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                continue;
+            throw error;
+        }
+        DECLARATION_PATTERN.lastIndex = 0;
+        let match = DECLARATION_PATTERN.exec(content);
+        while (match) {
+            addSymbolCandidate(candidates, match[1], normalizedPath);
+            match = DECLARATION_PATTERN.exec(content);
+        }
+    }
+    const symbolToScriptPaths = new Map();
+    for (const [symbol, paths] of candidates.entries()) {
+        symbolToScriptPaths.set(symbol, [...paths].sort((left, right) => left.localeCompare(right)));
+    }
+    return symbolToScriptPaths;
+}
+async function buildGuidHitIndex(repoRoot, scriptPathToGuid, resourceFiles) {
+    if (scriptPathToGuid.size === 0 || resourceFiles.length === 0) {
+        return new Map();
+    }
+    const guidLookup = new Map();
+    for (const guid of scriptPathToGuid.values()) {
+        guidLookup.set(guid.toLowerCase(), guid);
+    }
+    const perResourceHits = await mapWithConcurrency(resourceFiles, RESOURCE_HIT_SCAN_CONCURRENCY, async (resourcePathRaw) => {
+        const resourcePath = normalizeSlashes(resourcePathRaw);
+        const absolutePath = path.join(repoRoot, resourcePath);
+        let content = '';
+        try {
+            content = await fs.readFile(absolutePath, 'utf-8');
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === 'ENOENT' || code === 'EISDIR') {
+                return new Map();
+            }
+            throw error;
+        }
+        const resourceType = inferResourceType(resourcePath);
+        const lines = content.split(/\r?\n/);
+        const hits = new Map();
+        for (let index = 0; index < lines.length; index += 1) {
+            const line = lines[index];
+            const seenCanonical = new Set();
+            GUID_IN_LINE_PATTERN.lastIndex = 0;
+            let match = GUID_IN_LINE_PATTERN.exec(line);
+            while (match) {
+                const canonicalGuid = guidLookup.get(match[1].toLowerCase());
+                if (canonicalGuid && !seenCanonical.has(canonicalGuid)) {
+                    seenCanonical.add(canonicalGuid);
+                    const existing = hits.get(canonicalGuid) || [];
+                    existing.push({
+                        resourcePath,
+                        resourceType,
+                        line: index + 1,
+                        lineText: line,
+                    });
+                    hits.set(canonicalGuid, existing);
+                }
+                match = GUID_IN_LINE_PATTERN.exec(line);
+            }
+        }
+        return hits;
+    });
+    const guidToResourceHits = new Map();
+    for (const hitMap of perResourceHits) {
+        for (const [guid, hits] of hitMap.entries()) {
+            const existing = guidToResourceHits.get(guid) || [];
+            existing.push(...hits);
+            guidToResourceHits.set(guid, existing);
+        }
+    }
+    return guidToResourceHits;
+}
+async function resolveScriptFiles(repoRoot, scopedPaths) {
+    if (!scopedPaths || scopedPaths.length === 0) {
+        return (await glob('**/*.cs', {
+            cwd: repoRoot,
+            nodir: true,
+            dot: false,
+        })).sort((left, right) => left.localeCompare(right));
+    }
+    const scopedScripts = scopedPaths
+        .filter((value) => value.endsWith('.cs'))
+        .map((value) => normalizeRelativePath(repoRoot, value))
+        .filter((value) => value !== null)
+        .sort((left, right) => left.localeCompare(right));
+    return [...new Set(scopedScripts)];
+}
+async function resolveResourceFiles(repoRoot, scopedPaths) {
+    if (!scopedPaths || scopedPaths.length === 0) {
+        return (await glob(['**/*.prefab', '**/*.unity', '**/*.asset'], {
+            cwd: repoRoot,
+            nodir: true,
+            dot: false,
+        })).sort((left, right) => left.localeCompare(right));
+    }
+    const scopedResources = scopedPaths
+        .filter((value) => value.endsWith('.prefab') || value.endsWith('.unity') || value.endsWith('.asset'))
+        .map((value) => normalizeRelativePath(repoRoot, value))
+        .filter((value) => value !== null)
+        .sort((left, right) => left.localeCompare(right));
+    return [...new Set(scopedResources)];
+}
+function addSymbolCandidate(candidates, symbol, scriptPath) {
+    const existing = candidates.get(symbol) || new Set();
+    existing.add(scriptPath);
+    candidates.set(symbol, existing);
+}
+function buildSymbolScriptPathIndexFromDeclarations(repoRoot, declarations, scopedPaths) {
+    const candidates = new Map();
+    const allowedScriptPaths = resolveScopedScriptAllowlist(repoRoot, scopedPaths);
+    for (const declaration of declarations) {
+        const symbol = String(declaration.symbol || '').trim();
+        if (!symbol)
+            continue;
+        const scriptPath = normalizeRelativePath(repoRoot, declaration.scriptPath);
+        if (!scriptPath)
+            continue;
+        if (allowedScriptPaths && !allowedScriptPaths.has(scriptPath))
+            continue;
+        addSymbolCandidate(candidates, symbol, scriptPath);
+    }
+    const symbolToScriptPaths = new Map();
+    for (const [symbol, paths] of candidates.entries()) {
+        symbolToScriptPaths.set(symbol, [...paths].sort((left, right) => left.localeCompare(right)));
+    }
+    return symbolToScriptPaths;
+}
+function buildCanonicalScriptPathIndex(symbolToScriptPaths, scriptPathToGuid, guidToResourceHits) {
+    const canonical = new Map();
+    for (const [symbol, scriptPaths] of symbolToScriptPaths.entries()) {
+        if (scriptPaths.length === 0)
+            continue;
+        const selected = selectCanonicalScriptPath(symbol, scriptPaths, scriptPathToGuid, guidToResourceHits);
+        if (selected) {
+            canonical.set(symbol, selected);
+        }
+    }
+    return canonical;
+}
+function selectCanonicalScriptPath(symbol, scriptPaths, scriptPathToGuid, guidToResourceHits) {
+    const uniquePaths = [...new Set(scriptPaths)].sort((left, right) => left.localeCompare(right));
+    if (uniquePaths.length === 0)
+        return null;
+    const symbolBaseName = `${symbol}.cs`.toLowerCase();
+    const symbolPrefix = `${symbol.toLowerCase()}.`;
+    const scored = uniquePaths.map((scriptPath) => {
+        const baseName = path.basename(scriptPath).toLowerCase();
+        const exactScore = baseName === symbolBaseName ? 0 : 1;
+        const generatedScore = baseName.endsWith('.generated.cs') ? 1 : 0;
+        const suffixScore = baseName.startsWith(symbolPrefix) && baseName !== symbolBaseName ? 1 : 0;
+        const guid = scriptPathToGuid.get(scriptPath);
+        const hitCount = guid ? (guidToResourceHits.get(guid)?.length || 0) : 0;
+        return {
+            scriptPath,
+            exactScore,
+            generatedScore,
+            suffixScore,
+            hitCount,
+        };
+    });
+    scored.sort((left, right) => {
+        if (left.exactScore !== right.exactScore)
+            return left.exactScore - right.exactScore;
+        if (left.generatedScore !== right.generatedScore)
+            return left.generatedScore - right.generatedScore;
+        if (left.suffixScore !== right.suffixScore)
+            return left.suffixScore - right.suffixScore;
+        if (left.hitCount !== right.hitCount)
+            return right.hitCount - left.hitCount;
+        return left.scriptPath.localeCompare(right.scriptPath);
+    });
+    return scored[0].scriptPath;
+}
+function resolveScriptFilesFromSymbolDeclarations(repoRoot, declarations, scopedPaths) {
+    const allowedScriptPaths = resolveScopedScriptAllowlist(repoRoot, scopedPaths);
+    const scriptFiles = declarations
+        .map((declaration) => normalizeRelativePath(repoRoot, declaration.scriptPath))
+        .filter((value) => value !== null)
+        .filter((value) => !allowedScriptPaths || allowedScriptPaths.has(value))
+        .sort((left, right) => left.localeCompare(right));
+    return [...new Set(scriptFiles)];
+}
+function resolveScopedScriptAllowlist(repoRoot, scopedPaths) {
+    if (!scopedPaths || scopedPaths.length === 0)
+        return null;
+    const allowlist = new Set(scopedPaths
+        .filter((value) => value.endsWith('.cs'))
+        .map((value) => normalizeRelativePath(repoRoot, value))
+        .filter((value) => value !== null));
+    return allowlist.size > 0 ? allowlist : null;
+}
+function normalizeRelativePath(repoRoot, filePath) {
+    const relativePath = path.isAbsolute(filePath) ? path.relative(repoRoot, filePath) : filePath;
+    const normalized = normalizeSlashes(relativePath);
+    if (normalized.startsWith('../'))
+        return null;
+    return normalized;
+}
+function normalizeSlashes(filePath) {
+    return filePath.replace(/\\/g, '/');
+}
+function inferResourceType(resourcePath) {
+    if (resourcePath.endsWith('.prefab'))
+        return 'prefab';
+    if (resourcePath.endsWith('.asset'))
+        return 'asset';
+    return 'scene';
+}
+function resolveAssetMetaFiles(repoRoot, scopedPaths, scriptFiles, resourceFiles) {
+    if (scopedPaths && scopedPaths.length > 0) {
+        const scopedMeta = new Set();
+        for (const entry of scopedPaths) {
+            const normalized = normalizeRelativePath(repoRoot, entry);
+            if (!normalized)
+                continue;
+            if (normalized.endsWith('.meta')) {
+                scopedMeta.add(normalized);
+            }
+            else {
+                scopedMeta.add(`${normalized}.meta`);
+            }
+        }
+        return [...scopedMeta].sort((left, right) => left.localeCompare(right));
+    }
+    const inferredMeta = new Set();
+    for (const scriptPath of scriptFiles)
+        inferredMeta.add(`${scriptPath}.meta`);
+    for (const resourcePath of resourceFiles)
+        inferredMeta.add(`${resourcePath}.meta`);
+    return [...inferredMeta].sort((left, right) => left.localeCompare(right));
+}
+async function mapWithConcurrency(items, concurrency, mapper) {
+    const safeConcurrency = Math.max(1, Math.min(concurrency, items.length || 1));
+    const results = new Array(items.length);
+    let cursor = 0;
+    const workers = Array.from({ length: safeConcurrency }, async () => {
+        while (true) {
+            const index = cursor;
+            cursor += 1;
+            if (index >= items.length)
+                break;
+            results[index] = await mapper(items[index], index);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}

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

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

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

@@ -0,0 +1,118 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import os from 'node:os';
+import fs from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { buildUnityScanContext } from './scan-context.js';
+import { resolveUnityBindings } from './resolver.js';
+const here = path.dirname(fileURLToPath(import.meta.url));
+const fixtureRoot = path.resolve(here, '../../../src/core/unity/__fixtures__/mini-unity');
+test('buildUnityScanContext builds symbol/guid/hit indexes once from fixture', async () => {
+    const context = await buildUnityScanContext({ repoRoot: fixtureRoot });
+    assert.ok(context.symbolToScriptPath.has('MainUIManager'));
+    assert.ok(context.scriptPathToGuid.size > 0);
+    assert.ok(context.guidToResourceHits.size > 0);
+});
+test('buildUnityScanContext exposes reusable resourceDocCache for repeated resolves', async () => {
+    const context = await buildUnityScanContext({ repoRoot: fixtureRoot });
+    assert.equal(context.resourceDocCache.size, 0);
+    await resolveUnityBindings({ repoRoot: fixtureRoot, symbol: 'MainUIManager', scanContext: context });
+    const cacheSizeAfterFirst = context.resourceDocCache.size;
+    await resolveUnityBindings({ repoRoot: fixtureRoot, symbol: 'MainUIManager', scanContext: context });
+    assert.equal(context.resourceDocCache.size, cacheSizeAfterFirst);
+    assert.ok(cacheSizeAfterFirst > 0);
+});
+test('buildUnityScanContext accepts symbol declarations as hint source', async () => {
+    const context = await buildUnityScanContext({
+        repoRoot: fixtureRoot,
+        scopedPaths: ['Assets/Scene/MainUIManager.unity'],
+        symbolDeclarations: [
+            { symbol: 'HintOnly', scriptPath: 'Assets/Scripts/HintOnly.cs' },
+            { symbol: 'MainUIManager', scriptPath: 'Assets/Scripts/MainUIManager.cs' },
+        ],
+    });
+    assert.equal(context.symbolToScriptPath.get('HintOnly'), 'Assets/Scripts/HintOnly.cs');
+    assert.equal(context.symbolToScriptPath.get('MainUIManager'), 'Assets/Scripts/MainUIManager.cs');
+});
+test('buildUnityScanContext skips resource scanning when there are no script guids', async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-scancontext-'));
+    const badResourceDir = path.join(tempRoot, 'Assets/Scene/Broken.unity');
+    await fs.mkdir(badResourceDir, { recursive: true });
+    try {
+        const context = await buildUnityScanContext({
+            repoRoot: tempRoot,
+            scopedPaths: ['Assets/Scene/Broken.unity'],
+        });
+        assert.equal(context.scriptPathToGuid.size, 0);
+        assert.equal(context.guidToResourceHits.size, 0);
+    }
+    finally {
+        await fs.rm(tempRoot, { recursive: true, force: true });
+    }
+});
+test('buildUnityScanContext indexes scoped asset meta files for guid->path resolution', 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',
+        ],
+    });
+    assert.equal(context.assetGuidToPath?.get('44444444444444444444444444444444'), 'Assets/Config/MainUIDocument.asset');
+});
+test('buildUnityScanContext selects canonical script for duplicated symbol declarations', async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-canonical-'));
+    const scriptsDir = path.join(tempRoot, 'Assets/Scripts');
+    const sceneDir = path.join(tempRoot, 'Assets/Scene');
+    await fs.mkdir(scriptsDir, { recursive: true });
+    await fs.mkdir(sceneDir, { recursive: true });
+    try {
+        await fs.writeFile(path.join(scriptsDir, 'PlayerActor.cs'), 'public partial class PlayerActor {}', 'utf-8');
+        await fs.writeFile(path.join(scriptsDir, 'PlayerActor.Visual.cs'), 'public partial class PlayerActor {}', 'utf-8');
+        await fs.writeFile(path.join(scriptsDir, 'PlayerActor.cs.meta'), 'guid: 11111111111111111111111111111111\n', 'utf-8');
+        await fs.writeFile(path.join(scriptsDir, 'PlayerActor.Visual.cs.meta'), 'guid: 22222222222222222222222222222222\n', 'utf-8');
+        await fs.writeFile(path.join(sceneDir, 'Test.unity'), '--- !u!1 &1\nguid: 11111111111111111111111111111111\n', 'utf-8');
+        const context = await buildUnityScanContext({
+            repoRoot: tempRoot,
+            symbolDeclarations: [
+                { symbol: 'PlayerActor', scriptPath: 'Assets/Scripts/PlayerActor.cs' },
+                { symbol: 'PlayerActor', scriptPath: 'Assets/Scripts/PlayerActor.Visual.cs' },
+            ],
+        });
+        assert.deepEqual(context.symbolToScriptPaths.get('PlayerActor'), [
+            'Assets/Scripts/PlayerActor.cs',
+            'Assets/Scripts/PlayerActor.Visual.cs',
+        ]);
+        assert.equal(context.symbolToCanonicalScriptPath.get('PlayerActor'), 'Assets/Scripts/PlayerActor.cs');
+        assert.equal(context.symbolToScriptPath.get('PlayerActor'), 'Assets/Scripts/PlayerActor.cs');
+    }
+    finally {
+        await fs.rm(tempRoot, { recursive: true, force: true });
+    }
+});
+test('buildUnityScanContext exposes serializable symbol index and host field type hints', async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-serializable-scancontext-'));
+    const scriptsDir = path.join(tempRoot, 'Assets/Scripts');
+    await fs.mkdir(scriptsDir, { recursive: true });
+    try {
+        await fs.writeFile(path.join(scriptsDir, 'AssetRef.cs'), `
+        [System.Serializable]
+        public class AssetRef { public string guid; }
+      `, 'utf-8');
+        await fs.writeFile(path.join(scriptsDir, 'InventoryConfig.cs'), `
+        using UnityEngine;
+        public class InventoryConfig : ScriptableObject {
+          public AssetRef icon;
+        }
+      `, 'utf-8');
+        const context = await buildUnityScanContext({ repoRoot: tempRoot });
+        assert.equal(context.serializableSymbols.has('AssetRef'), true);
+        assert.equal(context.hostFieldTypeHints.get('InventoryConfig')?.get('icon'), 'AssetRef');
+    }
+    finally {
+        await fs.rm(tempRoot, { recursive: true, force: true });
+    }
+});

package/dist/core/unity/serialized-type-index.d.ts

@@ -0,0 +1,10 @@
+export interface SerializableTypeIndex {
+    serializableSymbols: Set<string>;
+    hostFieldTypeHints: Map<string, Map<string, string>>;
+}
+interface SourceFile {
+    filePath: string;
+    content: string;
+}
+export declare function buildSerializableTypeIndexFromSources(sources: SourceFile[]): SerializableTypeIndex;
+export {};

package/dist/core/unity/serialized-type-index.js

@@ -0,0 +1,105 @@
+const SERIALIZABLE_DECLARATION_PATTERN = /(?:\[[^\]]*\bSerializable\b[^\]]*\]\s*)+(?:(?:public|private|protected|internal|static|sealed|abstract|partial)\s+)*(?:class|struct)\s+([A-Za-z_][A-Za-z0-9_]*)/g;
+const CLASS_DECLARATION_PATTERN = /\bclass\s+([A-Za-z_][A-Za-z0-9_]*)[^{]*\{/g;
+const FIELD_DECLARATION_PATTERN = /(?:\[[^\]]+\]\s*)*(?:(?:public|private|protected|internal|static|readonly|volatile|new|sealed|virtual|override|unsafe)\s+)*([A-Za-z_][A-Za-z0-9_<>\[\],\.\?\s]*)\s+([A-Za-z_][A-Za-z0-9_]*)\s*(?:=[^;]*)?;/g;
+export function buildSerializableTypeIndexFromSources(sources) {
+    const serializableSymbols = new Set();
+    for (const source of sources) {
+        SERIALIZABLE_DECLARATION_PATTERN.lastIndex = 0;
+        let match = SERIALIZABLE_DECLARATION_PATTERN.exec(source.content);
+        while (match) {
+            serializableSymbols.add(match[1]);
+            match = SERIALIZABLE_DECLARATION_PATTERN.exec(source.content);
+        }
+    }
+    const hostFieldTypeHints = new Map();
+    for (const source of sources) {
+        const classBodies = extractClassBodies(source.content);
+        for (const classBody of classBodies) {
+            const fieldHints = extractHostFieldHints(classBody.body, serializableSymbols);
+            if (fieldHints.size > 0) {
+                hostFieldTypeHints.set(classBody.name, fieldHints);
+            }
+        }
+    }
+    return { serializableSymbols, hostFieldTypeHints };
+}
+function extractClassBodies(content) {
+    const result = [];
+    CLASS_DECLARATION_PATTERN.lastIndex = 0;
+    let match = CLASS_DECLARATION_PATTERN.exec(content);
+    while (match) {
+        const className = match[1];
+        const openBraceIndex = CLASS_DECLARATION_PATTERN.lastIndex - 1;
+        const closeBraceIndex = findMatchingBrace(content, openBraceIndex);
+        if (closeBraceIndex !== -1) {
+            result.push({
+                name: className,
+                body: content.slice(openBraceIndex + 1, closeBraceIndex),
+            });
+            CLASS_DECLARATION_PATTERN.lastIndex = closeBraceIndex + 1;
+        }
+        match = CLASS_DECLARATION_PATTERN.exec(content);
+    }
+    return result;
+}
+function findMatchingBrace(content, openBraceIndex) {
+    let depth = 0;
+    for (let index = openBraceIndex; index < content.length; index += 1) {
+        const ch = content[index];
+        if (ch === '{') {
+            depth += 1;
+            continue;
+        }
+        if (ch === '}') {
+            depth -= 1;
+            if (depth === 0) {
+                return index;
+            }
+        }
+    }
+    return -1;
+}
+function extractHostFieldHints(classBody, serializableSymbols) {
+    const hints = new Map();
+    FIELD_DECLARATION_PATTERN.lastIndex = 0;
+    let match = FIELD_DECLARATION_PATTERN.exec(classBody);
+    while (match) {
+        const full = match[0] || '';
+        if (full.includes('(')) {
+            match = FIELD_DECLARATION_PATTERN.exec(classBody);
+            continue;
+        }
+        const declaredType = normalizeDeclaredType(match[1]);
+        const fieldName = match[2];
+        if (declaredType && serializableSymbols.has(declaredType)) {
+            hints.set(fieldName, declaredType);
+        }
+        match = FIELD_DECLARATION_PATTERN.exec(classBody);
+    }
+    return hints;
+}
+function normalizeDeclaredType(input) {
+    let compact = String(input || '').replace(/\s+/g, '');
+    compact = compact.replace(/^global::/, '');
+    if (!compact)
+        return null;
+    let typeName = compact;
+    while (true) {
+        const listMatch = typeName.match(/^(?:System\.Collections\.Generic\.)?(?:List|IList|IReadOnlyList|IEnumerable|HashSet)<(.+)>$/);
+        if (!listMatch)
+            break;
+        typeName = listMatch[1];
+    }
+    if (typeName.endsWith('[]')) {
+        typeName = typeName.slice(0, -2);
+    }
+    if (typeName.endsWith('?')) {
+        typeName = typeName.slice(0, -1);
+    }
+    const genericStart = typeName.indexOf('<');
+    if (genericStart !== -1) {
+        typeName = typeName.slice(0, genericStart);
+    }
+    const shortName = typeName.split('.').pop() || '';
+    return shortName || null;
+}

package/dist/core/unity/serialized-type-index.test.d.ts

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