pando-ai 0.1.4 → 0.1.9

package/tools/csharp-indexer/src/Program.cs

@@ -0,0 +1,1860 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using System.Reflection;
+using System.Threading;
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.CSharp;
+using Microsoft.CodeAnalysis.CSharp.Syntax;
+
+namespace Pando.CSharpIndexer
+{
+    public class CliNode
+    {
+        [JsonPropertyName("name")] public string? Name { get; set; }
+        [JsonPropertyName("kind")] public string Kind { get; set; } = "";
+        [JsonPropertyName("rawKind")] public string? RawKind { get; set; }
+        [JsonPropertyName("rawKindSource")] public string? RawKindSource { get; set; }
+        [JsonPropertyName("containerRawKind")] public string? ContainerRawKind { get; set; }
+        [JsonPropertyName("containerRawKindSource")] public string? ContainerRawKindSource { get; set; }
+        [JsonPropertyName("semanticKind")] public string? SemanticKind { get; set; }
+        [JsonPropertyName("start")] public int Start { get; set; }
+        [JsonPropertyName("end")] public int End { get; set; }
+        [JsonPropertyName("isExported")] public int IsExported { get; set; }
+        [JsonPropertyName("containerKind")] public string? ContainerKind { get; set; }
+        [JsonPropertyName("paramCount")] public int? ParamCount { get; set; }
+        [JsonPropertyName("qualifiedName")] public string? QualifiedName { get; set; }
+        [JsonPropertyName("scopeChain")] public List<string>? ScopeChain { get; set; }
+        [JsonPropertyName("symbolKey")] public string? SymbolKey { get; set; }
+        [JsonPropertyName("metadata")] public Dictionary<string, object?>? Metadata { get; set; }
+    }
+
+    public class CliImport
+    {
+        [JsonPropertyName("module")] public string? Module { get; set; }
+        [JsonPropertyName("isTypeOnly")] public int IsTypeOnly { get; set; }
+    }
+
+    public class CliImportBinding
+    {
+        [JsonPropertyName("module")] public string? Module { get; set; }
+        [JsonPropertyName("localName")] public string LocalName { get; set; } = "";
+        [JsonPropertyName("importedName")] public string ImportedName { get; set; } = "";
+        [JsonPropertyName("kind")] public string Kind { get; set; } = "named";
+        [JsonPropertyName("isTypeOnly")] public int IsTypeOnly { get; set; }
+    }
+
+    public class CliReference
+    {
+        [JsonPropertyName("sourceStart")] public int SourceStart { get; set; }
+        [JsonPropertyName("sourceEnd")] public int SourceEnd { get; set; }
+        [JsonPropertyName("refKind")] public string RefKind { get; set; } = "call";
+        [JsonPropertyName("refName")] public string? RefName { get; set; }
+        [JsonPropertyName("receiverName")] public string? ReceiverName { get; set; }
+        [JsonPropertyName("arity")] public int? Arity { get; set; }
+        [JsonPropertyName("containerQualifiedName")] public string? ContainerQualifiedName { get; set; }
+        [JsonPropertyName("targetSymbolKey")] public string? TargetSymbolKey { get; set; }
+        [JsonPropertyName("metadata")] public Dictionary<string, object?>? Metadata { get; set; }
+    }
+
+    public class CliSymbolMention
+    {
+        [JsonPropertyName("name")] public string? Name { get; set; }
+        [JsonPropertyName("mentionKind")] public string MentionKind { get; set; } = "reference";
+        [JsonPropertyName("targetSymbolKey")] public string? TargetSymbolKey { get; set; }
+        [JsonPropertyName("containerQualifiedName")] public string? ContainerQualifiedName { get; set; }
+        [JsonPropertyName("count")] public int Count { get; set; } = 1;
+    }
+
+    public class CliReferenceSpan
+    {
+        [JsonPropertyName("file")] public string File { get; set; } = "";
+        [JsonPropertyName("start")] public int Start { get; set; }
+        [JsonPropertyName("end")] public int End { get; set; }
+        [JsonPropertyName("refKind")] public string RefKind { get; set; } = "reference";
+        [JsonPropertyName("callerStart")] public int? CallerStart { get; set; }
+        [JsonPropertyName("callerEnd")] public int? CallerEnd { get; set; }
+        [JsonPropertyName("callerKind")] public string? CallerKind { get; set; }
+        // "statement" — the reference is the callee of an InvocationExpression that
+        // forms a complete ExpressionStatement; safe to delete the whole statement.
+        // "expression" — the reference participates in a larger expression; deletion
+        // would corrupt syntax. Callers should refuse and surface manual-review.
+        [JsonPropertyName("enclosingKind")] public string? EnclosingKind { get; set; }
+        [JsonPropertyName("enclosingStart")] public int? EnclosingStart { get; set; }
+        [JsonPropertyName("enclosingEnd")] public int? EnclosingEnd { get; set; }
+    }
+
+    public class CliParseResult
+    {
+        [JsonPropertyName("nodes")] public List<CliNode> Nodes { get; set; } = new();
+        [JsonPropertyName("imports")] public List<CliImport> Imports { get; set; } = new();
+        [JsonPropertyName("importBindings")] public List<CliImportBinding> ImportBindings { get; set; } = new();
+        [JsonPropertyName("references")] public List<CliReference> References { get; set; } = new();
+        [JsonPropertyName("symbolMentions")] public List<CliSymbolMention> SymbolMentions { get; set; } = new();
+        [JsonPropertyName("modulePublic")] public List<string> ModulePublic { get; set; } = new();
+        [JsonPropertyName("explicitExports")] public List<string>? ExplicitExports { get; set; }
+        [JsonPropertyName("error")] public string? Error { get; set; }
+        [JsonIgnore] internal Dictionary<string, CliSymbolMention>? SymbolMentionIndex { get; set; }
+    }
+
+    public class CliValidationResult
+    {
+        [JsonPropertyName("ok")] public bool Ok { get; set; } = true;
+        [JsonPropertyName("error")] public string? Error { get; set; }
+    }
+
+    public class CliResolvedSpan
+    {
+        [JsonPropertyName("start")] public int Start { get; set; }
+        [JsonPropertyName("end")] public int End { get; set; }
+        [JsonPropertyName("bodyStart")] public int? BodyStart { get; set; }
+        [JsonPropertyName("bodyEnd")] public int? BodyEnd { get; set; }
+        [JsonPropertyName("text")] public string? Text { get; set; }
+        [JsonPropertyName("error")] public string? Error { get; set; }
+    }
+
+    internal static class Program
+    {
+        private static int Main(string[] args)
+        {
+            try
+            {
+                var parsed = ParseArgs(args);
+                if (parsed.ContainsKey("server"))
+                {
+                    return RunServer();
+                }
+                if (!parsed.TryGetValue("file", out var file) || string.IsNullOrWhiteSpace(file))
+                {
+                    WriteError("missing --file");
+                    return 2;
+                }
+
+                var content = File.ReadAllText(file!);
+                var tree = CSharpSyntaxTree.ParseText(content);
+                var root = tree.GetCompilationUnitRoot();
+
+                if (parsed.ContainsKey("validate"))
+                {
+                    var validation = ValidateSyntax(tree);
+                    WriteOutput(parsed, validation);
+                    return validation.Error == null ? 0 : 2;
+                }
+
+                if (parsed.ContainsKey("resolve"))
+                {
+                    if (!parsed.TryGetValue("nodePath", out var nodePath))
+                    {
+                        WriteError("missing --nodePath");
+                        return 2;
+                    }
+                    var resolved = ResolveSpan(nodePath!, root, content);
+                    WriteOutput(parsed, resolved);
+                    return resolved.Error == null ? 0 : 2;
+                }
+
+                var result = BuildParseResult(root, content);
+                WriteOutput(parsed, result);
+                return 0;
+            }
+            catch (Exception ex)
+            {
+                WriteError(ex.Message);
+                return 2;
+            }
+        }
+
+        private static Dictionary<string, string?> ParseArgs(string[] args)
+        {
+            var map = new Dictionary<string, string?>(StringComparer.OrdinalIgnoreCase);
+            for (int i = 0; i < args.Length; i++)
+            {
+                var arg = args[i];
+                if (!arg.StartsWith("--", StringComparison.Ordinal)) { continue; }
+                var key = arg.Substring(2);
+                string? value = null;
+                if (i + 1 < args.Length && !args[i + 1].StartsWith("--", StringComparison.Ordinal))
+                {
+                    value = args[i + 1];
+                    i++;
+                }
+                map[key] = value;
+            }
+            return map;
+        }
+
+        private static int RunServer()
+        {
+            var options = new JsonSerializerOptions
+            {
+                DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
+                PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
+            };
+            string? line;
+            while ((line = Console.ReadLine()) != null)
+            {
+                if (string.IsNullOrWhiteSpace(line)) { continue; }
+                try
+                {
+                    using var doc = JsonDocument.Parse(line);
+                    var root = doc.RootElement;
+                    var id = root.TryGetProperty("id", out var idEl) && idEl.TryGetInt64(out var idVal) ? idVal : 0;
+                    var op = root.TryGetProperty("op", out var opEl) ? opEl.GetString() ?? "" : "";
+                    if (string.Equals(op, "parse", StringComparison.OrdinalIgnoreCase))
+                    {
+                        if (root.TryGetProperty("files", out var filesEl) && filesEl.ValueKind == JsonValueKind.Array)
+                        {
+                            var results = new List<object>();
+                            foreach (var item in filesEl.EnumerateArray())
+                            {
+                                var file = GetString(item, "file");
+                                if (string.IsNullOrWhiteSpace(file))
+                                {
+                                    results.Add(new { file, ok = false, error = "missing file" });
+                                    continue;
+                                }
+                                try
+                                {
+                                    var result = ParseFile(file!);
+                                    results.Add(new { file, ok = true, result });
+                                }
+                                catch (Exception ex)
+                                {
+                                    results.Add(new { file, ok = false, error = ex.Message });
+                                }
+                            }
+                            WriteServerResponse(new { id, ok = true, results }, options);
+                            continue;
+                        }
+                        var singleFile = GetString(root, "file");
+                        if (string.IsNullOrWhiteSpace(singleFile))
+                        {
+                            WriteServerResponse(new { id, ok = false, error = "missing file" }, options);
+                            continue;
+                        }
+                        try
+                        {
+                            var result = ParseFile(singleFile!);
+                            WriteServerResponse(new { id, ok = true, result }, options);
+                        }
+                        catch (Exception ex)
+                        {
+                            WriteServerResponse(new { id, ok = false, error = ex.Message }, options);
+                        }
+                        continue;
+                    }
+                    if (string.Equals(op, "resolve", StringComparison.OrdinalIgnoreCase))
+                    {
+                        var file = GetString(root, "file");
+                        var nodePath = GetString(root, "nodePath");
+                        if (string.IsNullOrWhiteSpace(file) || string.IsNullOrWhiteSpace(nodePath))
+                        {
+                            WriteServerResponse(new { id, ok = false, error = "missing file or nodePath" }, options);
+                            continue;
+                        }
+                        try
+                        {
+                            var resolved = ResolveFile(file!, nodePath!);
+                            WriteServerResponse(new { id, ok = true, result = resolved }, options);
+                        }
+                        catch (Exception ex)
+                        {
+                            WriteServerResponse(new { id, ok = false, error = ex.Message }, options);
+                        }
+                        continue;
+                    }
+                    if (string.Equals(op, "resolve-references", StringComparison.OrdinalIgnoreCase))
+                    {
+                        var file = GetString(root, "file");
+                        var nodePath = GetString(root, "nodePath");
+                        var files = GetStringArray(root, "files");
+                        var relTypes = GetStringArray(root, "relTypes");
+                        var maxResults = GetInt(root, "maxResults");
+                        var includeTargetFileReferences = GetBool(root, "includeTargetFileReferences") ?? true;
+                        var aggregateByCaller = GetBool(root, "aggregateByCaller") ?? false;
+                        if (string.IsNullOrWhiteSpace(file) || string.IsNullOrWhiteSpace(nodePath) || files == null || files.Count == 0)
+                        {
+                            WriteServerResponse(new { id, ok = false, error = "missing file, nodePath, or files" }, options);
+                            continue;
+                        }
+                        try
+                        {
+                            var resolved = ResolveReferencesInFiles(file!, nodePath!, files, relTypes, maxResults, includeTargetFileReferences, aggregateByCaller);
+                            WriteServerResponse(new { id, ok = true, result = resolved }, options);
+                        }
+                        catch (Exception ex)
+                        {
+                            WriteServerResponse(new { id, ok = false, error = ex.Message }, options);
+                        }
+                        continue;
+                    }
+                    WriteServerResponse(new { id, ok = false, error = "unknown op" }, options);
+                }
+                catch (Exception ex)
+                {
+                    try
+                    {
+                        WriteServerResponse(new { id = 0, ok = false, error = ex.Message }, options);
+                    }
+                    catch { }
+                }
+            }
+            return 0;
+        }
+
+        private static string? GetString(JsonElement element, string name)
+        {
+            if (element.ValueKind == JsonValueKind.Object && element.TryGetProperty(name, out var prop))
+            {
+                if (prop.ValueKind == JsonValueKind.String) { return prop.GetString(); }
+            }
+            return null;
+        }
+
+        private static List<string>? GetStringArray(JsonElement element, string name)
+        {
+            if (element.ValueKind != JsonValueKind.Object) { return null; }
+            if (!element.TryGetProperty(name, out var prop) || prop.ValueKind != JsonValueKind.Array) { return null; }
+            var list = new List<string>();
+            foreach (var item in prop.EnumerateArray())
+            {
+                if (item.ValueKind == JsonValueKind.String)
+                {
+                    var val = item.GetString();
+                    if (!string.IsNullOrWhiteSpace(val)) { list.Add(val!); }
+                }
+            }
+            return list;
+        }
+
+        private static int? GetInt(JsonElement element, string name)
+        {
+            if (element.ValueKind != JsonValueKind.Object) { return null; }
+            if (!element.TryGetProperty(name, out var prop)) { return null; }
+            if (prop.ValueKind == JsonValueKind.Number && prop.TryGetInt32(out var value)) { return value; }
+            return null;
+        }
+
+        private static bool? GetBool(JsonElement element, string name)
+        {
+            if (element.ValueKind != JsonValueKind.Object) { return null; }
+            if (!element.TryGetProperty(name, out var prop)) { return null; }
+            if (prop.ValueKind == JsonValueKind.True) { return true; }
+            if (prop.ValueKind == JsonValueKind.False) { return false; }
+            return null;
+        }
+
+        private static CliParseResult ParseFile(string file)
+        {
+            var content = File.ReadAllText(file);
+            var tree = CSharpSyntaxTree.ParseText(content, path: file);
+            var root = tree.GetCompilationUnitRoot();
+            return BuildParseResult(root, content);
+        }
+
+        private static CliResolvedSpan ResolveFile(string file, string nodePath)
+        {
+            var content = File.ReadAllText(file);
+            var tree = CSharpSyntaxTree.ParseText(content, path: file);
+            var root = tree.GetCompilationUnitRoot();
+            return ResolveSpan(nodePath, root, content);
+        }
+
+        private static CliValidationResult ValidateSyntax(SyntaxTree tree)
+        {
+            var errors = tree.GetDiagnostics().Where(d => d.Severity == DiagnosticSeverity.Error).ToList();
+            if (errors.Count == 0)
+            {
+                return new CliValidationResult { Ok = true };
+            }
+            var msg = string.Join("; ", errors.Take(5).Select(e => e.GetMessage()));
+            return new CliValidationResult { Ok = false, Error = $"{errors.Count} error(s): {msg}" };
+        }
+
+        private static void WriteServerResponse(object payload, JsonSerializerOptions options)
+        {
+            Console.WriteLine(JsonSerializer.Serialize(payload, options));
+        }
+
+        private static void WriteOutput(Dictionary<string, string?> args, object payload)
+        {
+            var json = JsonSerializer.Serialize(payload, new JsonSerializerOptions
+            {
+                DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
+                PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
+            });
+            if (args.TryGetValue("output", out var output) && !string.IsNullOrWhiteSpace(output))
+            {
+                File.WriteAllText(output!, json);
+            }
+            else
+            {
+                Console.WriteLine(json);
+            }
+        }
+
+        private static void WriteError(string message)
+        {
+            Console.WriteLine(JsonSerializer.Serialize(new CliParseResult { Error = message }));
+        }
+
+        private static SemanticModel? TryCreateSemanticModel(CompilationUnitSyntax root)
+        {
+            try
+            {
+                var compilation = CreateCompilation(new[] { root.SyntaxTree });
+                return compilation.GetSemanticModel(root.SyntaxTree, ignoreAccessibility: true);
+            }
+            catch
+            {
+                return null;
+            }
+        }
+
+        private static CliParseResult BuildParseResult(CompilationUnitSyntax root, string content)
+        {
+            var result = new CliParseResult();
+            var semanticModel = TryCreateSemanticModel(root);
+
+            foreach (var u in root.Usings)
+            {
+                if (u.Name == null) { continue; }
+                var module = u.Name.ToString();
+                result.Imports.Add(new CliImport { Module = module, IsTypeOnly = 0 });
+                if (u.Alias != null)
+                {
+                    result.ImportBindings.Add(new CliImportBinding
+                    {
+                        Module = module,
+                        LocalName = u.Alias.Name.ToString(),
+                        ImportedName = module,
+                        Kind = "named",
+                        IsTypeOnly = 0,
+                    });
+                }
+            }
+
+            var publicNames = new HashSet<string>(StringComparer.Ordinal);
+
+            foreach (var node in root.DescendantNodes())
+            {
+                switch (node)
+                {
+                    case EnumDeclarationSyntax enumDecl:
+                        AddEnumNode(result, enumDecl, content, publicNames, semanticModel);
+                        break;
+                    case BaseTypeDeclarationSyntax typeDecl:
+                        AddTypeNode(result, typeDecl, content, publicNames, semanticModel);
+                        break;
+                    case MethodDeclarationSyntax method:
+                        AddMethodNode(result, method, content, semanticModel);
+                        break;
+                    case ConstructorDeclarationSyntax ctor:
+                        AddConstructorNode(result, ctor, content, semanticModel);
+                        break;
+                    case PropertyDeclarationSyntax prop:
+                        AddPropertyNode(result, prop, content, semanticModel);
+                        break;
+                    case IndexerDeclarationSyntax indexer:
+                        AddIndexerNode(result, indexer, content, semanticModel);
+                        break;
+                    case FieldDeclarationSyntax field:
+                        AddFieldNodes(result, field, content, semanticModel);
+                        break;
+                    case EventDeclarationSyntax ev:
+                        AddEventNode(result, ev, content, semanticModel);
+                        break;
+                    case EventFieldDeclarationSyntax evField:
+                        AddEventFieldNodes(result, evField, content, semanticModel);
+                        break;
+                    case DelegateDeclarationSyntax del:
+                        AddDelegateNode(result, del, content, publicNames, semanticModel);
+                        break;
+                    case EnumMemberDeclarationSyntax enumMember:
+                        AddEnumMemberNode(result, enumMember, semanticModel);
+                        break;
+                    case IfStatementSyntax ifStmt:
+                        AddStructuralNode(result, ifStmt, semanticModel);
+                        break;
+                    case ForStatementSyntax forStmt:
+                        AddStructuralNode(result, forStmt, semanticModel);
+                        break;
+                    case ForEachStatementSyntax forEachStmt:
+                        AddStructuralNode(result, forEachStmt, semanticModel);
+                        break;
+                    case ForEachVariableStatementSyntax forEachVarStmt:
+                        AddStructuralNode(result, forEachVarStmt, semanticModel);
+                        break;
+                    case SwitchStatementSyntax switchStmt:
+                        AddStructuralNode(result, switchStmt, semanticModel);
+                        break;
+                    case ReturnStatementSyntax returnStmt:
+                        AddStructuralNode(result, returnStmt, semanticModel);
+                        break;
+                    case ExpressionStatementSyntax exprStmt:
+                        AddStructuralNode(result, exprStmt, semanticModel);
+                        break;
+                    case InvocationExpressionSyntax call:
+                        AddStructuralNode(result, call, semanticModel);
+                        AddCallReference(result, call, content, semanticModel);
+                        break;
+                    case ObjectCreationExpressionSyntax created:
+                        AddStructuralNode(result, created, semanticModel);
+                        AddNewReference(result, created, content, semanticModel);
+                        break;
+                    case IdentifierNameSyntax idName:
+                        AddIdentifierReference(result, idName, content, semanticModel);
+                        break;
+                    case GenericNameSyntax genName:
+                        AddIdentifierReference(result, genName, content, semanticModel);
+                        break;
+                    case VariableDeclaratorSyntax localVar when ShouldIndexLocalVariable(localVar):
+                        AddStructuralNode(result, localVar, semanticModel);
+                        break;
+                    case OperatorDeclarationSyntax op:
+                        AddOperatorNode(result, op, content, semanticModel);
+                        break;
+                    case ConversionOperatorDeclarationSyntax conv:
+                        AddConversionOperatorNode(result, conv, content, semanticModel);
+                        break;
+                    case DestructorDeclarationSyntax dtor:
+                        AddDestructorNode(result, dtor, content, semanticModel);
+                        break;
+                    case LocalFunctionStatementSyntax localFn:
+                        AddLocalFunctionNode(result, localFn, content, semanticModel);
+                        break;
+                }
+            }
+
+            EnrichNodeHierarchy(result.Nodes, root);
+
+            result.ModulePublic = publicNames.ToList();
+            return result;
+        }
+
+        private static string NormalizeQualifiedName(string? qualifiedName)
+        {
+            if (string.IsNullOrWhiteSpace(qualifiedName)) { return string.Empty; }
+            return qualifiedName.StartsWith("global::", StringComparison.Ordinal)
+                ? qualifiedName.Substring("global::".Length)
+                : qualifiedName;
+        }
+
+        private static List<string> BuildScopeChain(ISymbol symbol)
+        {
+            var chain = new List<string>();
+            ISymbol? current = symbol;
+            while (current != null)
+            {
+                if (current is INamespaceSymbol ns)
+                {
+                    if (!ns.IsGlobalNamespace && !string.IsNullOrWhiteSpace(ns.Name))
+                    {
+                        chain.Add(ns.Name);
+                    }
+                }
+                else if (!string.IsNullOrWhiteSpace(current.Name))
+                {
+                    chain.Add(current.Name);
+                }
+                current = current.ContainingSymbol;
+            }
+            chain.Reverse();
+            return chain;
+        }
+
+        private static ISymbol? TryGetSymbol(SemanticModel? model, SyntaxNode node, bool declared = true)
+        {
+            if (model == null) { return null; }
+            try
+            {
+                ISymbol? symbol = declared ? model.GetDeclaredSymbol(node) : null;
+                if (symbol == null)
+                {
+                    var info = model.GetSymbolInfo(node);
+                    symbol = info.Symbol ?? info.CandidateSymbols.FirstOrDefault();
+                }
+                if (symbol == null && !declared)
+                {
+                    switch (node)
+                    {
+                        case InvocationExpressionSyntax invocation:
+                        {
+                            var info = model.GetSymbolInfo(invocation.Expression);
+                            symbol = info.Symbol ?? info.CandidateSymbols.FirstOrDefault();
+                            break;
+                        }
+                        case ObjectCreationExpressionSyntax creation:
+                        {
+                            var info = model.GetSymbolInfo(creation.Type);
+                            symbol = info.Symbol ?? info.CandidateSymbols.FirstOrDefault();
+                            break;
+                        }
+                    }
+                }
+                return symbol;
+            }
+            catch
+            {
+                return null;
+            }
+        }
+
+        private static void PopulateNodeSymbolInfo(CliNode node, SemanticModel? model, SyntaxNode syntaxNode)
+        {
+            var symbol = TryGetSymbol(model, syntaxNode, declared: true);
+            if (symbol == null) { return; }
+
+            var qualified = NormalizeQualifiedName(symbol.ToDisplayString(SymbolDisplayFormat.FullyQualifiedFormat));
+            if (!string.IsNullOrWhiteSpace(qualified))
+            {
+                node.QualifiedName = qualified;
+            }
+            var chain = BuildScopeChain(symbol);
+            if (chain.Count > 0)
+            {
+                node.ScopeChain = chain;
+            }
+            var key = TryGetSymbolKey(symbol);
+            if (!string.IsNullOrWhiteSpace(key))
+            {
+                node.SymbolKey = key;
+            }
+        }
+
+        private static void AddSymbolMention(
+            CliParseResult result,
+            string? name,
+            string mentionKind,
+            string? targetSymbolKey,
+            string? containerQualifiedName)
+        {
+            var cleanedName = string.IsNullOrWhiteSpace(name) ? null : name.Trim();
+            if (string.IsNullOrWhiteSpace(cleanedName)) { return; }
+            var cleanedKind = string.IsNullOrWhiteSpace(mentionKind) ? "reference" : mentionKind.Trim().ToLowerInvariant();
+            var cleanedTargetKey = string.IsNullOrWhiteSpace(targetSymbolKey) ? string.Empty : targetSymbolKey.Trim();
+            var cleanedContainer = string.IsNullOrWhiteSpace(containerQualifiedName) ? string.Empty : containerQualifiedName.Trim();
+            result.SymbolMentionIndex ??= new Dictionary<string, CliSymbolMention>(StringComparer.Ordinal);
+            var dedupeKey = $"{cleanedName}\u0000{cleanedKind}\u0000{cleanedTargetKey}\u0000{cleanedContainer}";
+            if (result.SymbolMentionIndex.TryGetValue(dedupeKey, out var existing))
+            {
+                existing.Count += 1;
+                return;
+            }
+            var mention = new CliSymbolMention
+            {
+                Name = cleanedName,
+                MentionKind = cleanedKind,
+                TargetSymbolKey = string.IsNullOrWhiteSpace(cleanedTargetKey) ? null : cleanedTargetKey,
+                ContainerQualifiedName = string.IsNullOrWhiteSpace(cleanedContainer) ? null : cleanedContainer,
+                Count = 1,
+            };
+            result.SymbolMentionIndex[dedupeKey] = mention;
+            result.SymbolMentions.Add(mention);
+        }
+
+        // Stable, cross-file identifier for a Roslyn symbol. Uses the public
+        // documentation comment ID (e.g. "T:Newtonsoft.Json.Linq.JValue" or
+        // "M:Foo.Bar(System.Int32)"), which is unique and reproducible across
+        // independent compilations as long as the fully qualified name matches.
+        // Falls back to fully qualified display string when no doc comment id
+        // is produced (e.g. anonymous/local symbols).
+        private static string? TryGetSymbolKey(ISymbol symbol)
+        {
+            try
+            {
+                var docId = symbol.GetDocumentationCommentId();
+                if (!string.IsNullOrWhiteSpace(docId) && docId != "!:") { return docId; }
+                var fq = symbol.ToDisplayString(SymbolDisplayFormat.FullyQualifiedFormat);
+                if (string.IsNullOrWhiteSpace(fq)) { return null; }
+                return $"FQ:{fq}";
+            }
+            catch
+            {
+                return null;
+            }
+        }
+
+        private static CSharpCompilation CreateCompilation(IEnumerable<SyntaxTree> trees)
+        {
+            var refs = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+            void AddRef(Type t)
+            {
+                try
+                {
+                    var loc = t.Assembly.Location;
+                    if (!string.IsNullOrWhiteSpace(loc))
+                    {
+                        refs.Add(loc);
+                    }
+                }
+                catch { }
+            }
+
+            AddRef(typeof(object));
+            AddRef(typeof(Enumerable));
+            AddRef(typeof(Console));
+            AddRef(typeof(System.Runtime.GCSettings));
+
+            var metadata = refs.Select(r => MetadataReference.CreateFromFile(r)).ToList();
+            return CSharpCompilation.Create(
+                "PandoIndex",
+                trees,
+                metadata,
+                new CSharpCompilationOptions(OutputKind.DynamicallyLinkedLibrary));
+        }
+
+        private static object ResolveReferencesInFiles(string targetFile, string nodePath, List<string> files, List<string>? relTypes = null, int? maxResults = null, bool includeTargetFileReferences = true, bool aggregateByCaller = false)
+        {
+            var targetRef = ParseNodePathRef(nodePath);
+            if (targetRef == null) { return new { error = "invalid nodePath" }; }
+
+            var targetContent = File.ReadAllText(targetFile);
+            var targetTree = CSharpSyntaxTree.ParseText(targetContent, path: targetFile);
+            var targetRoot = targetTree.GetCompilationUnitRoot();
+            var targetNode = FindNodeByRef(targetRoot, targetRef.Value.start, targetRef.Value.end, targetRef.Value.kind);
+            if (targetNode == null) { return new { error = "target node not found" }; }
+
+            var trees = new List<SyntaxTree> { targetTree };
+            var seen = new HashSet<string>(StringComparer.OrdinalIgnoreCase) { targetFile };
+            foreach (var file in files.OrderBy(static f => f, StringComparer.OrdinalIgnoreCase))
+            {
+                if (string.IsNullOrWhiteSpace(file)) { continue; }
+                var normalized = file;
+                if (seen.Contains(normalized)) { continue; }
+                seen.Add(normalized);
+                try
+                {
+                    var text = File.ReadAllText(normalized);
+                    trees.Add(CSharpSyntaxTree.ParseText(text, path: normalized));
+                }
+                catch { }
+            }
+
+            var compilation = CreateCompilation(trees);
+            var targetModel = compilation.GetSemanticModel(targetTree, ignoreAccessibility: true);
+            var targetSymbol = TryGetSymbol(targetModel, targetNode, declared: true) ?? TryGetSymbol(targetModel, targetNode, declared: false);
+            if (targetSymbol == null) { return new { error = "target symbol not found" }; }
+            var targetKey = TryGetSymbolKey(targetSymbol);
+            if (string.IsNullOrWhiteSpace(targetKey)) { return new { error = "target symbol key missing" }; }
+
+            var references = new List<CliReferenceSpan>();
+            var allowedRelTypes = relTypes != null && relTypes.Count > 0
+                ? new HashSet<string>(relTypes.Where(static value => !string.IsNullOrWhiteSpace(value)), StringComparer.OrdinalIgnoreCase)
+                : null;
+            var cappedResults = maxResults.HasValue && maxResults.Value > 0 ? maxResults.Value : int.MaxValue;
+            var truncated = false;
+            var seenCallerGroups = aggregateByCaller ? new HashSet<string>(StringComparer.Ordinal) : null;
+            foreach (var tree in trees)
+            {
+                var root = tree.GetCompilationUnitRoot();
+                var model = compilation.GetSemanticModel(tree, ignoreAccessibility: true);
+                var filePath = tree.FilePath;
+                if (string.IsNullOrWhiteSpace(filePath)) { continue; }
+                if (!includeTargetFileReferences && string.Equals(filePath, targetFile, StringComparison.OrdinalIgnoreCase)) { continue; }
+
+                var seenSpans = new HashSet<(int, int)>();
+                foreach (var node in root.DescendantNodes())
+                {
+                    ISymbol? sym = null;
+                    int spanStart = node.Span.Start;
+                    int spanEnd = node.Span.End;
+                    if (node is InvocationExpressionSyntax || node is ObjectCreationExpressionSyntax)
+                    {
+                        sym = TryGetSymbol(model, node, declared: false);
+                    }
+                    else if (node is SimpleNameSyntax simpleName)
+                    {
+                        // Skip identifiers that are the immediate callee of an
+                        // InvocationExpression or the type of an ObjectCreation —
+                        // those nodes are already emitted with a wider span and
+                        // would otherwise produce duplicate references.
+                        if (IsRedundantWithCallOrNew(simpleName)) { continue; }
+                        sym = TryGetSymbol(model, node, declared: false);
+                        spanStart = simpleName.Identifier.Span.Start;
+                        spanEnd = simpleName.Identifier.Span.End;
+                    }
+                    if (sym == null) { continue; }
+                    var key = TryGetSymbolKey(sym);
+                    if (string.IsNullOrWhiteSpace(key) || key != targetKey) { continue; }
+                    if (!seenSpans.Add((spanStart, spanEnd))) { continue; }
+                    var refKind = ClassifyResolvedReferenceKind(node, sym);
+                    if (allowedRelTypes != null && !allowedRelTypes.Contains(refKind)) { continue; }
+                    var caller = FindEnclosingCallerDeclaration(node);
+                    var (enclosingKind, enclosingStart, enclosingEnd) = ClassifyReferenceContext(node);
+                    references.Add(new CliReferenceSpan
+                    {
+                        File = filePath,
+                        Start = spanStart,
+                        End = spanEnd,
+                        RefKind = refKind,
+                        CallerStart = caller.HasValue ? caller.Value.start : null,
+                        CallerEnd = caller.HasValue ? caller.Value.end : null,
+                        CallerKind = caller.HasValue ? caller.Value.kind : null,
+                        EnclosingKind = enclosingKind,
+                        EnclosingStart = enclosingStart,
+                        EnclosingEnd = enclosingEnd,
+                    });
+                    if (aggregateByCaller)
+                    {
+                        var callerKey = caller != null
+                            ? $"{filePath}\0{caller.Value.start}\0{caller.Value.end}\0{caller.Value.kind}"
+                            : $"{filePath}\0{spanStart}\0{spanEnd}\0REF";
+                        seenCallerGroups!.Add(callerKey);
+                        if (seenCallerGroups.Count >= cappedResults)
+                        {
+                            truncated = true;
+                            return new { symbolKey = targetKey, references, truncated };
+                        }
+                    }
+                    else if (references.Count >= cappedResults)
+                    {
+                        truncated = true;
+                        return new { symbolKey = targetKey, references, truncated };
+                    }
+                }
+            }
+
+            return new { symbolKey = targetKey, references, truncated };
+        }
+
+        private static string ClassifyResolvedReferenceKind(SyntaxNode node, ISymbol symbol)
+        {
+            if (node is InvocationExpressionSyntax) { return "call"; }
+            if (node is ObjectCreationExpressionSyntax) { return "new"; }
+            return symbol.Kind switch
+            {
+                SymbolKind.NamedType => "type",
+                SymbolKind.Namespace => "type",
+                _ => "reference",
+            };
+        }
+
+        private static (int start, int end, string kind)? FindEnclosingCallerDeclaration(SyntaxNode node)
+        {
+            for (SyntaxNode? current = node; current != null; current = current.Parent)
+            {
+                switch (current)
+                {
+                    case MethodDeclarationSyntax method:
+                        return (method.Span.Start, method.Span.End, method.Kind().ToString());
+                    case ConstructorDeclarationSyntax ctor:
+                        return (ctor.Span.Start, ctor.Span.End, ctor.Kind().ToString());
+                    case LocalFunctionStatementSyntax localFunction:
+                        return (localFunction.Span.Start, localFunction.Span.End, localFunction.Kind().ToString());
+                    case AccessorDeclarationSyntax accessor:
+                        return (accessor.Span.Start, accessor.Span.End, accessor.Kind().ToString());
+                    case ParenthesizedLambdaExpressionSyntax lambda:
+                        return (lambda.Span.Start, lambda.Span.End, lambda.Kind().ToString());
+                    case SimpleLambdaExpressionSyntax simpleLambda:
+                        return (simpleLambda.Span.Start, simpleLambda.Span.End, simpleLambda.Kind().ToString());
+                    case AnonymousMethodExpressionSyntax anonymousMethod:
+                        return (anonymousMethod.Span.Start, anonymousMethod.Span.End, anonymousMethod.Kind().ToString());
+                }
+            }
+            return null;
+        }
+
+        // Walk up from a matched reference node to determine whether deleting it is
+        // syntactically safe. A reference whose enclosing chain ends at an
+        // ExpressionStatementSyntax can be removed by replacing the whole statement.
+        // Anything else (assignments, arguments, member-access chains, conditionals,
+        // string interpolation, etc.) is reported as "expression" so the caller can
+        // refuse and surface manual review instead of writing a corrupting marker.
+        private static (string kind, int? start, int? end) ClassifyReferenceContext(SyntaxNode refNode)
+        {
+            // Walk up through the chain that "wraps" this reference. Stop when we
+            // reach the outermost expression that *contains* the ref; if its parent
+            // is an ExpressionStatement, deletion is safe.
+            SyntaxNode current = refNode;
+            while (current.Parent is ExpressionSyntax parentExpr)
+            {
+                // Stop walking if the parent is unrelated (e.g., a sibling of an
+                // argument list). The chain we care about: identifier → member access
+                // → invocation. Anything beyond that (e.g., parent of an invocation
+                // that is itself the operand of a binary expression) is an expression
+                // context and not safe to delete wholesale.
+                if (parentExpr is MemberAccessExpressionSyntax memberAccess && memberAccess.Name == current)
+                {
+                    current = parentExpr;
+                    continue;
+                }
+                if (parentExpr is InvocationExpressionSyntax invocation && invocation.Expression == current)
+                {
+                    current = parentExpr;
+                    continue;
+                }
+                if (parentExpr is ObjectCreationExpressionSyntax objectCreation && objectCreation.Type == current)
+                {
+                    current = parentExpr;
+                    continue;
+                }
+                break;
+            }
+            if (current.Parent is ExpressionStatementSyntax stmt)
+            {
+                return ("statement", stmt.Span.Start, stmt.Span.End);
+            }
+            return ("expression", null, null);
+        }
+
+        private static string? GetContainerQualifiedName(SemanticModel? model, SyntaxNode syntaxNode)
+        {
+            if (model == null) { return null; }
+            try
+            {
+                var symbol = model.GetEnclosingSymbol(syntaxNode.SpanStart);
+                if (symbol == null) { return null; }
+                var qualified = NormalizeQualifiedName(symbol.ToDisplayString(SymbolDisplayFormat.FullyQualifiedFormat));
+                return string.IsNullOrWhiteSpace(qualified) ? null : qualified;
+            }
+            catch
+            {
+                return null;
+            }
+        }
+
+        private static void AddTypeNode(CliParseResult result, BaseTypeDeclarationSyntax node, string content, HashSet<string> publicNames, SemanticModel? model)
+        {
+            var kind = node switch
+            {
+                ClassDeclarationSyntax => "Class",
+                StructDeclarationSyntax => "Struct",
+                InterfaceDeclarationSyntax => "Interface",
+                RecordDeclarationSyntax record => record.ClassOrStructKeyword.IsKind(SyntaxKind.StructKeyword) ? "Struct" : "Class",
+                _ => "Class",
+            };
+            var semanticKind = kind switch
+            {
+                "Class" => "class",
+                "Struct" => "struct",
+                "Interface" => "interface",
+                _ => "class",
+            };
+            var modifiers = node.Modifiers;
+            var isPublic = modifiers.Any(SyntaxKind.PublicKeyword);
+            if (isPublic) { publicNames.Add(node.Identifier.Text); }
+
+            var metadata = BuildVisibilityMetadata(modifiers);
+            if (node is RecordDeclarationSyntax)
+            {
+                metadata["isRecord"] = true;
+            }
+            if (node is TypeDeclarationSyntax t && t.BaseList != null)
+            {
+                var bases = t.BaseList.Types.Select(tn => tn.Type.ToString()).ToList();
+                if (bases.Count > 0)
+                {
+                    metadata["extends"] = bases.First();
+                    if (bases.Count > 1)
+                    {
+                        metadata["implements"] = bases.Skip(1).ToList();
+                    }
+                }
+            }
+
+            result.Nodes.Add(new CliNode
+            {
+                Name = node.Identifier.Text,
+                Kind = kind,
+                RawKind = node.Kind().ToString(),
+                RawKindSource = "roslyn",
+                SemanticKind = semanticKind,
+                Start = node.Span.Start,
+                End = node.Span.End,
+                IsExported = isPublic ? 1 : 0,
+                ContainerKind = null,
+                ContainerRawKind = null,
+                ContainerRawKindSource = null,
+                ParamCount = null,
+                Metadata = metadata,
+            });
+            PopulateNodeSymbolInfo(result.Nodes[^1], model, node);
+        }
+
+        private static void AddEnumNode(CliParseResult result, EnumDeclarationSyntax node, string content, HashSet<string> publicNames, SemanticModel? model)
+        {
+            var modifiers = node.Modifiers;
+            var isPublic = modifiers.Any(SyntaxKind.PublicKeyword);
+            if (isPublic) { publicNames.Add(node.Identifier.Text); }
+            var metadata = BuildVisibilityMetadata(modifiers);
+            result.Nodes.Add(new CliNode
+            {
+                Name = node.Identifier.Text,
+                Kind = "Enum",
+                RawKind = node.Kind().ToString(),
+                RawKindSource = "roslyn",
+                SemanticKind = "enum",
+                Start = node.Span.Start,
+                End = node.Span.End,
+                IsExported = isPublic ? 1 : 0,
+                ContainerKind = null,
+                ContainerRawKind = null,
+                ContainerRawKindSource = null,
+                ParamCount = null,
+                Metadata = metadata,
+            });
+            PopulateNodeSymbolInfo(result.Nodes[^1], model, node);
+        }
+
+        private static void AddDelegateNode(CliParseResult result, DelegateDeclarationSyntax node, string content, HashSet<string> publicNames, SemanticModel? model)
+        {
+            var modifiers = node.Modifiers;
+            var isPublic = modifiers.Any(SyntaxKind.PublicKeyword);
+            if (isPublic) { publicNames.Add(node.Identifier.Text); }
+            var metadata = BuildVisibilityMetadata(modifiers);
+            result.Nodes.Add(new CliNode
+            {
+                Name = node.Identifier.Text,
+                Kind = "Delegate",
+                RawKind = node.Kind().ToString(),
+                RawKindSource = "roslyn",
+                SemanticKind = "type",
+                Start = node.Span.Start,
+                End = node.Span.End,
+                IsExported = isPublic ? 1 : 0,
+                ContainerKind = null,
+                ContainerRawKind = null,
+                ContainerRawKindSource = null,
+                ParamCount = node.ParameterList.Parameters.Count,
+                Metadata = metadata,
+            });
+            PopulateNodeSymbolInfo(result.Nodes[^1], model, node);
+        }
+
+        private static void AddMethodNode(CliParseResult result, MethodDeclarationSyntax node, string content, SemanticModel? model)
+        {
+            var container = node.Ancestors().OfType<BaseTypeDeclarationSyntax>().FirstOrDefault();
+            var metadata = BuildVisibilityMetadata(node.Modifiers, container?.Identifier.Text, container?.Kind().ToString());
+            metadata["isAsync"] = node.Modifiers.Any(SyntaxKind.AsyncKeyword);
+            metadata["isStatic"] = node.Modifiers.Any(SyntaxKind.StaticKeyword);
+            metadata["isAbstract"] = node.Modifiers.Any(SyntaxKind.AbstractKeyword);
+            metadata["returnType"] = node.ReturnType.ToString();
+
+            result.Nodes.Add(new CliNode
+            {
+                Name = node.Identifier.Text,
+                Kind = "Method",
+                RawKind = node.Kind().ToString(),
+                RawKindSource = "roslyn",
+                ContainerRawKind = container?.Kind().ToString(),
+                ContainerRawKindSource = container == null ? null : "roslyn",
+                SemanticKind = "method",
+                Start = node.Span.Start,
+                End = node.Span.End,
+                IsExported = 0,
+                ContainerKind = container == null ? null : "Class",
+                ParamCount = node.ParameterList.Parameters.Count,
+                Metadata = metadata,
+            });
+            PopulateNodeSymbolInfo(result.Nodes[^1], model, node);
+        }
+
+        private static void AddConstructorNode(CliParseResult result, ConstructorDeclarationSyntax node, string content, SemanticModel? model)
+        {
+            var container = node.Ancestors().OfType<BaseTypeDeclarationSyntax>().FirstOrDefault();
+            var metadata = BuildVisibilityMetadata(node.Modifiers, container?.Identifier.Text, container?.Kind().ToString());
+            metadata["isStatic"] = node.Modifiers.Any(SyntaxKind.StaticKeyword);
+            metadata["isAbstract"] = node.Modifiers.Any(SyntaxKind.AbstractKeyword);
+
+            result.Nodes.Add(new CliNode
+            {
+                Name = node.Identifier.Text,
+                Kind = "Method",
+                RawKind = node.Kind().ToString(),
+                RawKindSource = "roslyn",
+                ContainerRawKind = container?.Kind().ToString(),
+                ContainerRawKindSource = container == null ? null : "roslyn",
+                SemanticKind = "method",
+                Start = node.Span.Start,
+                End = node.Span.End,
+                IsExported = 0,
+                ContainerKind = container == null ? null : "Class",
+                ParamCount = node.ParameterList.Parameters.Count,
+                Metadata = metadata,
+            });
+            PopulateNodeSymbolInfo(result.Nodes[^1], model, node);
+        }
+
+        private static void AddPropertyNode(CliParseResult result, PropertyDeclarationSyntax node, string content, SemanticModel? model)
+        {
+            var container = node.Ancestors().OfType<BaseTypeDeclarationSyntax>().FirstOrDefault();
+            var metadata = BuildVisibilityMetadata(node.Modifiers, container?.Identifier.Text, container?.Kind().ToString());
+            metadata["isStatic"] = node.Modifiers.Any(SyntaxKind.StaticKeyword);
+            metadata["isReadonly"] = node.AccessorList?.Accessors.All(a => a.Kind() == SyntaxKind.GetAccessorDeclaration) == true;
+
+            result.Nodes.Add(new CliNode
+            {
+                Name = node.Identifier.Text,
+                Kind = "Property",
+                RawKind = node.Kind().ToString(),
+                RawKindSource = "roslyn",
+                ContainerRawKind = container?.Kind().ToString(),
+                ContainerRawKindSource = container == null ? null : "roslyn",
+                SemanticKind = "property",
+                Start = node.Span.Start,
+                End = node.Span.End,
+                IsExported = 0,
+                ContainerKind = container == null ? null : "Class",
+                ParamCount = null,
+                Metadata = metadata,
+            });
+            PopulateNodeSymbolInfo(result.Nodes[^1], model, node);
+        }
+
+        private static void AddFieldNodes(CliParseResult result, FieldDeclarationSyntax node, string content, SemanticModel? model)
+        {
+            var container = node.Ancestors().OfType<BaseTypeDeclarationSyntax>().FirstOrDefault();
+            var metadata = BuildVisibilityMetadata(node.Modifiers, container?.Identifier.Text, container?.Kind().ToString());
+            metadata["isStatic"] = node.Modifiers.Any(SyntaxKind.StaticKeyword);
+            metadata["isReadonly"] = node.Modifiers.Any(SyntaxKind.ReadOnlyKeyword);
+
+            foreach (var v in node.Declaration.Variables)
+            {
+                result.Nodes.Add(new CliNode
+                {
+                    Name = v.Identifier.Text,
+                    Kind = "Field",
+                    RawKind = v.Kind().ToString(),
+                    RawKindSource = "roslyn",
+                    ContainerRawKind = container?.Kind().ToString(),
+                    ContainerRawKindSource = container == null ? null : "roslyn",
+                    SemanticKind = "field",
+                    Start = v.Span.Start,
+                    End = v.Span.End,
+                    IsExported = 0,
+                    ContainerKind = container == null ? null : "Class",
+                    ParamCount = null,
+                    Metadata = metadata,
+                });
+                PopulateNodeSymbolInfo(result.Nodes[^1], model, v);
+            }
+        }
+
+        private static bool ShouldIndexLocalVariable(VariableDeclaratorSyntax node)
+        {
+            return node.Ancestors().Any(a =>
+                    a is BaseMethodDeclarationSyntax
+                    || a is LocalFunctionStatementSyntax
+                    || a is AccessorDeclarationSyntax
+                    || a is AnonymousFunctionExpressionSyntax)
+                && !node.Ancestors().Any(a => a is FieldDeclarationSyntax || a is EventFieldDeclarationSyntax);
+        }
+
+        private static void AddStructuralNode(CliParseResult result, SyntaxNode node, SemanticModel? model)
+        {
+            var container = node.Ancestors().FirstOrDefault(a =>
+                a is BaseMethodDeclarationSyntax
+                || a is LocalFunctionStatementSyntax
+                || a is AccessorDeclarationSyntax
+                || a is BaseTypeDeclarationSyntax);
+            var containerKind = container switch
+            {
+                MethodDeclarationSyntax => "Method",
+                ConstructorDeclarationSyntax => "Method",
+                DestructorDeclarationSyntax => "Method",
+                OperatorDeclarationSyntax => "Method",
+                ConversionOperatorDeclarationSyntax => "Method",
+                LocalFunctionStatementSyntax => "Function",
+                AccessorDeclarationSyntax => "Property",
+                BaseTypeDeclarationSyntax => "Class",
+                _ => null,
+            };
+            var name = node switch
+            {
+                VariableDeclaratorSyntax v => v.Identifier.Text,
+                ForEachStatementSyntax f => f.Identifier.Text,
+                InvocationExpressionSyntax i => ExtractName(i.Expression),
+                ObjectCreationExpressionSyntax o => ExtractName(o.Type),
+                _ => null,
+            };
+
+            result.Nodes.Add(new CliNode
+            {
+                Name = name,
+                Kind = node.Kind().ToString(),
+                RawKind = node.Kind().ToString(),
+                RawKindSource = "roslyn",
+                SemanticKind = null,
+                Start = node.Span.Start,
+                End = node.Span.End,
+                IsExported = 0,
+                ContainerKind = containerKind,
+                ContainerRawKind = container?.Kind().ToString(),
+                ContainerRawKindSource = container == null ? null : "roslyn",
+                ParamCount = null,
+                Metadata = null,
+            });
+            PopulateNodeSymbolInfo(result.Nodes[^1], model, node);
+        }
+
+        private static void AddIndexerNode(CliParseResult result, IndexerDeclarationSyntax node, string content, SemanticModel? model)
+        {
+            var container = node.Ancestors().OfType<BaseTypeDeclarationSyntax>().FirstOrDefault();
+            var metadata = BuildVisibilityMetadata(node.Modifiers, container?.Identifier.Text, container?.Kind().ToString());
+            metadata["isStatic"] = node.Modifiers.Any(SyntaxKind.StaticKeyword);
+            metadata["isReadonly"] = node.AccessorList?.Accessors.All(a => a.Kind() == SyntaxKind.GetAccessorDeclaration) == true;
+
+            result.Nodes.Add(new CliNode
+            {
+                Name = "this",
+                Kind = "Property",
+                RawKind = node.Kind().ToString(),
+                RawKindSource = "roslyn",
+                ContainerRawKind = container?.Kind().ToString(),
+                ContainerRawKindSource = container == null ? null : "roslyn",
+                SemanticKind = "property",
+                Start = node.Span.Start,
+                End = node.Span.End,
+                IsExported = 0,
+                ContainerKind = container == null ? null : "Class",
+                ParamCount = node.ParameterList?.Parameters.Count ?? 0,
+                Metadata = metadata,
+            });
+            PopulateNodeSymbolInfo(result.Nodes[^1], model, node);
+        }
+
+        private static void AddEventNode(CliParseResult result, EventDeclarationSyntax node, string content, SemanticModel? model)
+        {
+            var container = node.Ancestors().OfType<BaseTypeDeclarationSyntax>().FirstOrDefault();
+            var metadata = BuildVisibilityMetadata(node.Modifiers, container?.Identifier.Text, container?.Kind().ToString());
+            metadata["isStatic"] = node.Modifiers.Any(SyntaxKind.StaticKeyword);
+            metadata["isEvent"] = true;
+
+            result.Nodes.Add(new CliNode
+            {
+                Name = node.Identifier.Text,
+                Kind = "Event",
+                RawKind = node.Kind().ToString(),
+                RawKindSource = "roslyn",
+                ContainerRawKind = container?.Kind().ToString(),
+                ContainerRawKindSource = container == null ? null : "roslyn",
+                SemanticKind = "field",
+                Start = node.Span.Start,
+                End = node.Span.End,
+                IsExported = 0,
+                ContainerKind = container == null ? null : "Class",
+                ParamCount = null,
+                Metadata = metadata,
+            });
+            PopulateNodeSymbolInfo(result.Nodes[^1], model, node);
+        }
+
+        private static void AddEventFieldNodes(CliParseResult result, EventFieldDeclarationSyntax node, string content, SemanticModel? model)
+        {
+            var container = node.Ancestors().OfType<BaseTypeDeclarationSyntax>().FirstOrDefault();
+            var metadata = BuildVisibilityMetadata(node.Modifiers, container?.Identifier.Text, container?.Kind().ToString());
+            metadata["isStatic"] = node.Modifiers.Any(SyntaxKind.StaticKeyword);
+            metadata["isEvent"] = true;
+
+            foreach (var v in node.Declaration.Variables)
+            {
+                result.Nodes.Add(new CliNode
+                {
+                    Name = v.Identifier.Text,
+                    Kind = "Event",
+                    RawKind = v.Kind().ToString(),
+                    RawKindSource = "roslyn",
+                    ContainerRawKind = container?.Kind().ToString(),
+                    ContainerRawKindSource = container == null ? null : "roslyn",
+                    SemanticKind = "field",
+                    Start = v.Span.Start,
+                    End = v.Span.End,
+                    IsExported = 0,
+                    ContainerKind = container == null ? null : "Class",
+                    ParamCount = null,
+                    Metadata = metadata,
+                });
+                PopulateNodeSymbolInfo(result.Nodes[^1], model, v);
+            }
+        }
+
+        private static void AddEnumMemberNode(CliParseResult result, EnumMemberDeclarationSyntax node, SemanticModel? model)
+        {
+            var container = node.Ancestors().OfType<EnumDeclarationSyntax>().FirstOrDefault();
+            result.Nodes.Add(new CliNode
+            {
+                Name = node.Identifier.Text,
+                Kind = "EnumMember",
+                RawKind = node.Kind().ToString(),
+                RawKindSource = "roslyn",
+                SemanticKind = "enum",
+                Start = node.Span.Start,
+                End = node.Span.End,
+                IsExported = 0,
+                ContainerKind = container == null ? null : "Enum",
+                ContainerRawKind = container?.Kind().ToString(),
+                ContainerRawKindSource = container == null ? null : "roslyn",
+                ParamCount = null,
+                Metadata = null,
+            });
+            PopulateNodeSymbolInfo(result.Nodes[^1], model, node);
+        }
+
+        private static void AddOperatorNode(CliParseResult result, OperatorDeclarationSyntax node, string content, SemanticModel? model)
+        {
+            var container = node.Ancestors().OfType<BaseTypeDeclarationSyntax>().FirstOrDefault();
+            var metadata = BuildVisibilityMetadata(node.Modifiers, container?.Identifier.Text, container?.Kind().ToString());
+            metadata["isStatic"] = node.Modifiers.Any(SyntaxKind.StaticKeyword);
+            metadata["returnType"] = node.ReturnType.ToString();
+
+            result.Nodes.Add(new CliNode
+            {
+                Name = $"operator {node.OperatorToken.Text}",
+                Kind = "Method",
+                RawKind = node.Kind().ToString(),
+                RawKindSource = "roslyn",
+                ContainerRawKind = container?.Kind().ToString(),
+                ContainerRawKindSource = container == null ? null : "roslyn",
+                SemanticKind = "method",
+                Start = node.Span.Start,
+                End = node.Span.End,
+                IsExported = 0,
+                ContainerKind = container == null ? null : "Class",
+                ParamCount = node.ParameterList.Parameters.Count,
+                Metadata = metadata,
+            });
+            PopulateNodeSymbolInfo(result.Nodes[^1], model, node);
+        }
+
+        private static void AddConversionOperatorNode(CliParseResult result, ConversionOperatorDeclarationSyntax node, string content, SemanticModel? model)
+        {
+            var container = node.Ancestors().OfType<BaseTypeDeclarationSyntax>().FirstOrDefault();
+            var metadata = BuildVisibilityMetadata(node.Modifiers, container?.Identifier.Text, container?.Kind().ToString());
+            metadata["isStatic"] = node.Modifiers.Any(SyntaxKind.StaticKeyword);
+            metadata["returnType"] = node.Type.ToString();
+
+            var kind = node.ImplicitOrExplicitKeyword.Kind() == SyntaxKind.ImplicitKeyword ? "implicit" : "explicit";
+            result.Nodes.Add(new CliNode
+            {
+                Name = $"{kind} operator {node.Type}",
+                Kind = "Method",
+                RawKind = node.Kind().ToString(),
+                RawKindSource = "roslyn",
+                ContainerRawKind = container?.Kind().ToString(),
+                ContainerRawKindSource = container == null ? null : "roslyn",
+                SemanticKind = "method",
+                Start = node.Span.Start,
+                End = node.Span.End,
+                IsExported = 0,
+                ContainerKind = container == null ? null : "Class",
+                ParamCount = node.ParameterList.Parameters.Count,
+                Metadata = metadata,
+            });
+            PopulateNodeSymbolInfo(result.Nodes[^1], model, node);
+        }
+
+        private static void AddDestructorNode(CliParseResult result, DestructorDeclarationSyntax node, string content, SemanticModel? model)
+        {
+            var container = node.Ancestors().OfType<BaseTypeDeclarationSyntax>().FirstOrDefault();
+            var metadata = BuildVisibilityMetadata(node.Modifiers, container?.Identifier.Text, container?.Kind().ToString());
+
+            result.Nodes.Add(new CliNode
+            {
+                Name = $"~{node.Identifier.Text}",
+                Kind = "Method",
+                RawKind = node.Kind().ToString(),
+                RawKindSource = "roslyn",
+                ContainerRawKind = container?.Kind().ToString(),
+                ContainerRawKindSource = container == null ? null : "roslyn",
+                SemanticKind = "method",
+                Start = node.Span.Start,
+                End = node.Span.End,
+                IsExported = 0,
+                ContainerKind = container == null ? null : "Class",
+                ParamCount = 0,
+                Metadata = metadata,
+            });
+            PopulateNodeSymbolInfo(result.Nodes[^1], model, node);
+        }
+
+        private static void AddLocalFunctionNode(CliParseResult result, LocalFunctionStatementSyntax node, string content, SemanticModel? model)
+        {
+            var container = node.Ancestors().OfType<BaseTypeDeclarationSyntax>().FirstOrDefault();
+            var metadata = BuildVisibilityMetadata(node.Modifiers, container?.Identifier.Text, container?.Kind().ToString());
+            metadata["isLocal"] = true;
+            metadata["returnType"] = node.ReturnType.ToString();
+
+            result.Nodes.Add(new CliNode
+            {
+                Name = node.Identifier.Text,
+                Kind = "Function",
+                RawKind = node.Kind().ToString(),
+                RawKindSource = "roslyn",
+                ContainerRawKind = container?.Kind().ToString(),
+                ContainerRawKindSource = container == null ? null : "roslyn",
+                SemanticKind = "function",
+                Start = node.Span.Start,
+                End = node.Span.End,
+                IsExported = 0,
+                ContainerKind = container == null ? null : "Class",
+                ParamCount = node.ParameterList.Parameters.Count,
+                Metadata = metadata,
+            });
+            PopulateNodeSymbolInfo(result.Nodes[^1], model, node);
+        }
+
+        private static void AddStructuralNode(CliParseResult result, SyntaxNode node, string? name = null)
+        {
+            var metadata = new Dictionary<string, object?>();
+            if (node is VariableDeclaratorSyntax variable)
+            {
+                metadata["hasInitializer"] = variable.Initializer != null;
+            }
+            var kind = node.Kind().ToString();
+            result.Nodes.Add(new CliNode
+            {
+                Name = string.IsNullOrWhiteSpace(name) ? null : name,
+                Kind = kind,
+                RawKind = kind,
+                RawKindSource = "roslyn",
+                SemanticKind = InferSemanticKind(node),
+                Start = node.Span.Start,
+                End = node.Span.End,
+                IsExported = 0,
+                ContainerKind = null,
+                ContainerRawKind = null,
+                ContainerRawKindSource = null,
+                ParamCount = null,
+                Metadata = metadata,
+            });
+        }
+
+        private static string? InferSemanticKind(SyntaxNode node)
+        {
+            return node switch
+            {
+                StatementSyntax => "statement",
+                ExpressionSyntax => "expression",
+                VariableDeclaratorSyntax => "variable",
+                _ => null,
+            };
+        }
+
+        private static void EnrichNodeHierarchy(List<CliNode> nodes, CompilationUnitSyntax root)
+        {
+            var syntaxByKey = root.DescendantNodes()
+                .GroupBy(n => NodeKey(n.Span.Start, n.Span.End, n.Kind().ToString()))
+                .ToDictionary(g => g.Key, g => g.First(), StringComparer.Ordinal);
+            var nodeByKey = nodes
+                .GroupBy(n => NodeKey(n.Start, n.End, n.RawKind ?? n.Kind), StringComparer.Ordinal)
+                .ToDictionary(g => g.Key, g => g.First(), StringComparer.Ordinal);
+            var emittedKeys = new HashSet<string>(nodeByKey.Keys, StringComparer.Ordinal);
+            var childrenByParent = new Dictionary<string, List<CliNode>>(StringComparer.Ordinal);
+
+            foreach (var cliNode in nodes)
+            {
+                var key = NodeKey(cliNode.Start, cliNode.End, cliNode.RawKind ?? cliNode.Kind);
+                if (!syntaxByKey.TryGetValue(key, out var syntax)) { continue; }
+                var metadata = cliNode.Metadata ??= new Dictionary<string, object?>();
+                var body = GetBodySpan(syntax);
+                if (body != null)
+                {
+                    metadata["bodyStart"] = body.Value.start;
+                    metadata["bodyEnd"] = body.Value.end;
+                }
+                metadata["role"] = InferNodeRole(syntax);
+
+                var parent = syntax.Parent;
+                while (parent != null)
+                {
+                    var parentKey = NodeKey(parent.Span.Start, parent.Span.End, parent.Kind().ToString());
+                    if (emittedKeys.Contains(parentKey))
+                    {
+                        metadata["parentStart"] = parent.Span.Start;
+                        metadata["parentEnd"] = parent.Span.End;
+                        metadata["parentKind"] = parent.Kind().ToString();
+                        if (!childrenByParent.TryGetValue(parentKey, out var list))
+                        {
+                            list = new List<CliNode>();
+                            childrenByParent[parentKey] = list;
+                        }
+                        list.Add(cliNode);
+                        break;
+                    }
+                    parent = parent.Parent;
+                }
+            }
+
+            foreach (var entry in childrenByParent)
+            {
+                var ordered = entry.Value
+                    .OrderBy(n => n.Start)
+                    .ThenBy(n => n.End)
+                    .ThenBy(n => n.RawKind ?? n.Kind)
+                    .ToList();
+                if (nodeByKey.TryGetValue(entry.Key, out var parent))
+                {
+                    var metadata = parent.Metadata ??= new Dictionary<string, object?>();
+                    metadata["children"] = ordered
+                        .Select(n => new Dictionary<string, object?>
+                        {
+                            ["start"] = n.Start,
+                            ["end"] = n.End,
+                            ["kind"] = n.RawKind ?? n.Kind,
+                        })
+                        .ToList();
+                }
+                for (var i = 0; i < ordered.Count; i++)
+                {
+                    var metadata = ordered[i].Metadata ??= new Dictionary<string, object?>();
+                    metadata["indexInParent"] = i;
+                }
+            }
+
+            foreach (var cliNode in nodes)
+            {
+                var depth = 0;
+                var metadata = cliNode.Metadata;
+                while (metadata != null
+                    && metadata.TryGetValue("parentStart", out var start)
+                    && metadata.TryGetValue("parentEnd", out var end)
+                    && metadata.TryGetValue("parentKind", out var kind))
+                {
+                    var parentKey = NodeKey(Convert.ToInt32(start), Convert.ToInt32(end), Convert.ToString(kind) ?? "");
+                    if (!nodeByKey.TryGetValue(parentKey, out var parent)) { break; }
+                    depth++;
+                    metadata = parent.Metadata;
+                }
+                cliNode.Metadata ??= new Dictionary<string, object?>();
+                cliNode.Metadata["depth"] = depth;
+            }
+        }
+
+        private static string NodeKey(int start, int end, string kind) => $"{start}:{end}:{kind}";
+
+        private static (int start, int end)? GetBodySpan(SyntaxNode node)
+        {
+            return node switch
+            {
+                BaseTypeDeclarationSyntax typeDecl when typeDecl.OpenBraceToken.Span.End <= typeDecl.CloseBraceToken.SpanStart
+                    => (typeDecl.OpenBraceToken.Span.End, typeDecl.CloseBraceToken.SpanStart),
+                BaseMethodDeclarationSyntax method when method.Body != null
+                    => (method.Body.OpenBraceToken.Span.End, method.Body.CloseBraceToken.SpanStart),
+                AccessorDeclarationSyntax accessor when accessor.Body != null
+                    => (accessor.Body.OpenBraceToken.Span.End, accessor.Body.CloseBraceToken.SpanStart),
+                AnonymousFunctionExpressionSyntax anon when anon.Body is BlockSyntax block
+                    => (block.OpenBraceToken.Span.End, block.CloseBraceToken.SpanStart),
+                _ => null,
+            };
+        }
+
+        private static string InferNodeRole(SyntaxNode node)
+        {
+            var parent = node.Parent;
+            if (parent == null) { return "root"; }
+            if (parent is BaseTypeDeclarationSyntax) { return "member"; }
+            if (parent is BlockSyntax) { return "statement"; }
+            if (parent is IfStatementSyntax ifStatement)
+            {
+                if (ifStatement.Condition == node) { return "condition"; }
+                if (ifStatement.Statement == node) { return "then"; }
+                if (ifStatement.Else?.Statement == node) { return "else"; }
+            }
+            if (parent is ForStatementSyntax forStatement)
+            {
+                if (forStatement.Condition == node) { return "condition"; }
+                if (forStatement.Statement == node) { return "body"; }
+                if (forStatement.Declaration == node) { return "initializer"; }
+            }
+            if (parent is ForEachStatementSyntax forEachStatement && forEachStatement.Statement == node) { return "body"; }
+            if (parent is ForEachVariableStatementSyntax forEachVariableStatement && forEachVariableStatement.Statement == node) { return "body"; }
+            if (parent is SwitchStatementSyntax switchStatement)
+            {
+                if (switchStatement.Expression == node) { return "expression"; }
+                if (switchStatement.Sections.Contains(node)) { return "section"; }
+            }
+            if (parent is ReturnStatementSyntax returnStatement && returnStatement.Expression == node) { return "value"; }
+            if (parent is InvocationExpressionSyntax invocation)
+            {
+                if (invocation.Expression == node) { return "callee"; }
+                if (invocation.ArgumentList.Arguments.Contains(node)) { return "argument"; }
+            }
+            if (parent is ObjectCreationExpressionSyntax creation)
+            {
+                if (creation.Type == node) { return "type"; }
+                if (creation.ArgumentList?.Arguments.Contains(node) == true) { return "argument"; }
+            }
+            if (parent is VariableDeclarationSyntax) { return "variable"; }
+            if (parent is EqualsValueClauseSyntax) { return "initializer"; }
+            if (parent is ExpressionStatementSyntax) { return "expression"; }
+            if (node is StatementSyntax) { return "statement"; }
+            if (node is ExpressionSyntax) { return "expression"; }
+            return "child";
+        }
+
+        private static void AddCallReference(CliParseResult result, InvocationExpressionSyntax node, string content, SemanticModel? model)
+        {
+            var name = ExtractName(node.Expression);
+            var containerQualifiedName = GetContainerQualifiedName(model, node);
+            var symbol = TryGetSymbol(model, node, declared: false);
+            var targetSymbolKey = symbol == null ? null : TryGetSymbolKey(symbol);
+            AddSymbolMention(result, name, "call", targetSymbolKey, containerQualifiedName);
+        }
+
+        private static void AddNewReference(CliParseResult result, ObjectCreationExpressionSyntax node, string content, SemanticModel? model)
+        {
+            var containerQualifiedName = GetContainerQualifiedName(model, node);
+            var symbol = TryGetSymbol(model, node, declared: false);
+            var name = symbol?.Name ?? node.Type.ToString();
+            var targetSymbolKey = symbol == null ? null : TryGetSymbolKey(symbol);
+            AddSymbolMention(result, name, "new", targetSymbolKey, containerQualifiedName);
+        }
+
+        // Emit a reference row for type/namespace/field/property/event identifier
+        // usages so find-references covers more than just call/new sites.
+        // Skips: declarations, locals, parameters, type parameters, labels;
+        // also skips identifiers that are already covered by AddCallReference
+        // (the callee of an invocation) or AddNewReference (the type of a new
+        // expression), so we don't emit duplicate spans.
+        private static void AddIdentifierReference(CliParseResult result, SimpleNameSyntax node, string content, SemanticModel? model)
+        {
+            if (model == null) { return; }
+            if (IsRedundantWithCallOrNew(node)) { return; }
+            if (IsDeclarationName(node)) { return; }
+
+            ISymbol? symbol;
+            try
+            {
+                var info = model.GetSymbolInfo(node);
+                symbol = info.Symbol ?? info.CandidateSymbols.FirstOrDefault();
+            }
+            catch
+            {
+                return;
+            }
+            if (symbol == null) { return; }
+
+            // Filter to symbol kinds where find-references is meaningful.
+            // Methods are still emitted so method-group references (delegates,
+            // nameof, etc.) are captured; the call sites themselves are also
+            // covered by AddCallReference but with a different (full-call) span.
+            switch (symbol.Kind)
+            {
+                case SymbolKind.NamedType:
+                case SymbolKind.Namespace:
+                case SymbolKind.Field:
+                case SymbolKind.Property:
+                case SymbolKind.Event:
+                case SymbolKind.Method:
+                    break;
+                default:
+                    return;
+            }
+
+            // For methods, skip the redundant case where this identifier is the
+            // immediate callee of an InvocationExpression. AddCallReference has
+            // already emitted a row for the whole invocation.
+            if (symbol.Kind == SymbolKind.Method && IsImmediateInvocationTarget(node))
+            {
+                return;
+            }
+
+            var refKind = symbol.Kind switch
+            {
+                SymbolKind.NamedType => "type",
+                SymbolKind.Namespace => "type",
+                _ => "reference",
+            };
+
+            var key = TryGetSymbolKey(symbol);
+            var containerQualifiedName = GetContainerQualifiedName(model, node);
+            AddSymbolMention(result, node.Identifier.Text, refKind, key, containerQualifiedName);
+        }
+
+        private static bool IsRedundantWithCallOrNew(SimpleNameSyntax node)
+        {
+            // Walk up the "name chain" so that for `A.B.C` we still consider the
+            // outermost access when classifying redundancy.
+            SyntaxNode current = node;
+            while (current.Parent is MemberAccessExpressionSyntax memberAccess && memberAccess.Name == current)
+            {
+                current = memberAccess;
+            }
+            while (current.Parent is QualifiedNameSyntax qualified && qualified.Right == current)
+            {
+                current = qualified;
+            }
+            // Whole-callee of an invocation is already covered by AddCallReference.
+            if (current.Parent is InvocationExpressionSyntax invocation && invocation.Expression == current)
+            {
+                return true;
+            }
+            // Whole-type of an object creation is already covered by AddNewReference.
+            if (current.Parent is ObjectCreationExpressionSyntax creation && creation.Type == current)
+            {
+                return true;
+            }
+            return false;
+        }
+
+        private static bool IsImmediateInvocationTarget(SimpleNameSyntax node)
+        {
+            SyntaxNode current = node;
+            while (current.Parent is MemberAccessExpressionSyntax memberAccess && memberAccess.Name == current)
+            {
+                current = memberAccess;
+            }
+            return current.Parent is InvocationExpressionSyntax invocation && invocation.Expression == current;
+        }
+
+        private static bool IsDeclarationName(SimpleNameSyntax node)
+        {
+            // SimpleName doesn't itself carry a Declarator, but it can appear as
+            // the explicit-interface qualifier of one. The actual declared name
+            // of a class/method is a regular SyntaxToken on the parent node, so
+            // it never reaches this dispatch.
+            var parent = node.Parent;
+            if (parent is NameEqualsSyntax) { return true; }       // `using X = ...;` (left side)
+            if (parent is NameColonSyntax) { return true; }        // `Method(name: value)`
+            return false;
+        }
+
+        private static string? ExtractName(ExpressionSyntax expr)
+        {
+            return expr switch
+            {
+                IdentifierNameSyntax id => id.Identifier.Text,
+                MemberAccessExpressionSyntax mem => mem.Name.Identifier.Text,
+                GenericNameSyntax gen => gen.Identifier.Text,
+                _ => expr.ToString(),
+            };
+        }
+
+        private static string? ExtractReceiverName(ExpressionSyntax expr)
+        {
+            if (expr is MemberAccessExpressionSyntax mem)
+            {
+                if (mem.Expression is IdentifierNameSyntax id)
+                {
+                    return id.Identifier.Text;
+                }
+            }
+            return null;
+        }
+
+        private static Dictionary<string, object?> BuildReferenceMetadata(SyntaxNode node, string content)
+        {
+            var metadata = new Dictionary<string, object?>();
+            var text = content.Substring(node.Span.Start, node.Span.Length);
+            metadata["expression"] = text;
+
+            var containerType = node.Ancestors().OfType<BaseTypeDeclarationSyntax>().FirstOrDefault();
+            if (containerType != null)
+            {
+                metadata["containerName"] = containerType.Identifier.Text;
+                metadata["containerKind"] = "Class";
+            }
+            return metadata;
+        }
+
+        private static Dictionary<string, object?> BuildVisibilityMetadata(SyntaxTokenList modifiers, string? containerName = null, string? containerKind = null)
+        {
+            var metadata = new Dictionary<string, object?>();
+            var visibility = "private";
+            if (modifiers.Any(SyntaxKind.PublicKeyword)) { visibility = "public"; }
+            else if (modifiers.Any(SyntaxKind.ProtectedKeyword) && modifiers.Any(SyntaxKind.InternalKeyword)) { visibility = "protected internal"; }
+            else if (modifiers.Any(SyntaxKind.ProtectedKeyword)) { visibility = "protected"; }
+            else if (modifiers.Any(SyntaxKind.InternalKeyword)) { visibility = "internal"; }
+
+            metadata["visibility"] = visibility;
+            if (!string.IsNullOrWhiteSpace(containerName)) { metadata["containerName"] = containerName; }
+            if (!string.IsNullOrWhiteSpace(containerKind)) { metadata["containerKind"] = "Class"; }
+            return metadata;
+        }
+
+        private static CliResolvedSpan ResolveSpan(string nodePath, CompilationUnitSyntax root, string content)
+        {
+            var targetRef = ParseNodePathRef(nodePath);
+            if (targetRef == null)
+            {
+                return new CliResolvedSpan { Error = "invalid nodePath" };
+            }
+
+            var target = FindNodeByRef(root, targetRef.Value.start, targetRef.Value.end, targetRef.Value.kind);
+            if (target == null)
+            {
+                return new CliResolvedSpan { Error = "node not found" };
+            }
+
+            int? bodyStart = null;
+            int? bodyEnd = null;
+
+            switch (target)
+            {
+                case BaseTypeDeclarationSyntax typeDecl:
+                    bodyStart = typeDecl.OpenBraceToken.Span.End;
+                    bodyEnd = typeDecl.CloseBraceToken.SpanStart;
+                    break;
+                case BaseMethodDeclarationSyntax method:
+                    if (method.Body != null)
+                    {
+                        bodyStart = method.Body.OpenBraceToken.Span.End;
+                        bodyEnd = method.Body.CloseBraceToken.SpanStart;
+                    }
+                    break;
+                case AccessorDeclarationSyntax accessor:
+                    if (accessor.Body != null)
+                    {
+                        bodyStart = accessor.Body.OpenBraceToken.Span.End;
+                        bodyEnd = accessor.Body.CloseBraceToken.SpanStart;
+                    }
+                    break;
+            }
+
+            return new CliResolvedSpan
+            {
+                Start = target.Span.Start,
+                End = target.Span.End,
+                BodyStart = bodyStart,
+                BodyEnd = bodyEnd,
+                Text = content.Substring(target.Span.Start, target.Span.Length),
+            };
+        }
+
+        private static SyntaxNode? FindNodeByRef(CompilationUnitSyntax root, int start, int end, string? kind)
+        {
+            SyntaxNode? firstSpanMatch = null;
+            foreach (var node in root.DescendantNodes())
+            {
+                if (node.Span.Start != start || node.Span.End != end) { continue; }
+                firstSpanMatch ??= node;
+                if (!string.IsNullOrWhiteSpace(kind) && string.Equals(node.Kind().ToString(), kind, StringComparison.Ordinal))
+                {
+                    return node;
+                }
+            }
+            return firstSpanMatch;
+        }
+
+        private static (int start, int end, string? kind)? ParseNodePathRef(string nodePath)
+        {
+            var clean = nodePath;
+            if (clean.StartsWith("SyntaxError:") || clean.StartsWith("CompileError:"))
+            {
+                var idx = clean.IndexOf(':');
+                if (idx >= 0) { clean = clean.Substring(idx + 1); }
+            }
+            string? kind = null;
+            if (clean.Contains('#'))
+            {
+                clean = clean.Split('#')[1];
+            }
+            if (clean.Contains(':'))
+            {
+                kind = clean.Substring(clean.LastIndexOf(':') + 1);
+                clean = clean.Substring(0, clean.LastIndexOf(':'));
+            }
+            var parts = clean.Split('-');
+            if (parts.Length != 2) { return null; }
+            if (int.TryParse(parts[0], out var start) && int.TryParse(parts[1], out var end) && end >= start)
+            {
+                return (start, end, string.IsNullOrWhiteSpace(kind) ? null : kind);
+            }
+            return null;
+        }
+    }
+}