[clangd] Call hierarchy (Protocol layer)

[nridge]

Summary

The protocol is based on the spec found here:
https://microsoft.github.io/language-server-protocol/specifications/specification-3-16/#textDocument_prepareCallHierarchy

[nridge]

• Rebased on top of upstream changes
• Rebased on top of TestWorkspace changes
• Merged D89298 into this patch
• Split index changes out to D89670
• Added more tests

[nridge]

Keeping in the draft state for now, as I still need to address this comment from the issue discussion:

The request still has a progressToken attached to it, I presume(it is unclear from the spec) it is preserved between prepare and subsequent requests. So we can keep a mapping in ClangdServer and stash symbolIDs.

[nridge]

Add and use CallHierarchyItem.data

[nridge]

In D89296#2337788, @nridge wrote:

Keeping in the draft state for now, as I still need to address this comment from the issue discussion:

The request still has a progressToken attached to it, I presume(it is unclear from the spec) it is preserved between prepare and subsequent requests. So we can keep a mapping in ClangdServer and stash symbolIDs.

The protocol has since been amended to introduce a data field to CallHierarchyItem in which we can stash the SymbolID, making this workaround unnecessary.

The updated patch uses the data field, and should be ready for review.

[nridge]

Note, testing this with vscode requires this vscode-clangd patch applied (to use a newer version of the client libraries that support the data field).

[nridge]

Kadir, would you like to take a look at this, as you're already familiar with the index changes? :)

[kadircet]

Thanks, I skimmed over it (again) and I think this looks pretty great in general. I couldn't take a look at the details yet, I would really appreciate it if you could chop this one into smaller pieces (i know, i asked it before, but this is still too big). I suppose something like:

• Changes in the XRefs side, introducing {prepare,incoming,outgoing} CallHierarchy bits, relevant Protocol.h additions and unittests for those.
• Surfacing this in ClangdServer and ClangdLSPServer layer, with relevant unit/lit tests. (I would be even more happier if you could split this in two again one for each layer :) )

would be great.

If you can't split it up, that's also fine. I'll go over it eventually, it will just take longer and probably be harder to remember where we left off after each iteration :D

[nridge]

Split patch as requested

[kadircet]

clang-tools-extra/clangd/Protocol.cpp

1216

we should also populate tags and detail conditionally. rather than providing empty strings/vectors.

1245

s/"from"/"to"

clang-tools-extra/clangd/Protocol.h

1407

we use exactly the same names in protocol here, even if they don't adhere to the style guide. i.e. s/Name/name. same for others.

1423

s/Rng/range

1432

i would drop the optional, as there's no difference between empty vs none.

1461

could you put this before CallHierarchyItem ?

1464

could you put this before CallHierarchyIncomingCall, same for outgoing

[nridge]

Address review comments

[nridge]

Forgot to rename a few fields

[kadircet]

thanks, LGTM

clang-tools-extra/clangd/Protocol.h

struct TypeHierarchyItem {
   /// the parents have not been resolved yet.
   llvm::Optional<std::vector<TypeHierarchyItem>> parents;
 
   /// If this type hierarchy item is resolved, it contains the direct children
   /// of the current item. Could be empty if the item does not have any
   /// descendants. If not defined, the children have not been resolved.
   llvm::Optional<std::vector<TypeHierarchyItem>> children;
 
-  /// An optional 'data' filed, which can be used to identify a type hierarchy
+  /// An optional 'data' field, which can be used to identify a type hierarchy
   /// item in a resolve request.
   llvm::Optional<std::string> data;
 };
 llvm::json::Value toJSON(const TypeHierarchyItem &);
 llvm::raw_ostream &operator<<(llvm::raw_ostream &, const TypeHierarchyItem &);
 bool fromJSON(const llvm::json::Value &, TypeHierarchyItem &, llvm::json::Path);
 
 /// Parameters for the `typeHierarchy/resolve` request.
 struct ResolveTypeHierarchyItemParams {
   /// The item to resolve.
   TypeHierarchyItem item;
 
   /// The hierarchy levels to resolve. `0` indicates no level.
   int resolve;
 
   /// The direction of the hierarchy levels to resolve.
   TypeHierarchyDirection direction;
 };
 bool fromJSON(const llvm::json::Value &, ResolveTypeHierarchyItemParams &,
               llvm::json::Path);
 
+enum class SymbolTag { Deprecated = 1 };
+llvm::json::Value toJSON(SymbolTag);
+
+/// The parameter of a `textDocument/prepareCallHierarchy` request.
+struct CallHierarchyPrepareParams : public TextDocumentPositionParams {};
+
+/// Represents programming constructs like functions or constructors
+/// in the context of call hierarchy.
+struct CallHierarchyItem {
+  /// The name of this item.
+  std::string name;
+
+  /// The kind of this item.
+  SymbolKind kind;
+
+  /// Tags for this item.
+  std::vector<SymbolTag> tags;
+
+  /// More detaill for this item, e.g. the signature of a function.
+  std::string detail;
+
+  /// The resource identifier of this item.
+  URIForFile uri;
+
+  /// The range enclosing this symbol not including leading / trailing
+  /// whitespace but everything else, e.g. comments and code.
+  Range range;
+
+  /// The range that should be selected and revealed when this symbol
+  /// is being picked, e.g. the name of a function.
+  /// Must be contained by `Rng`.
+  Range selectionRange;
+
+  /// An optional 'data' field, which can be used to identify a call
+  /// hierarchy item in an incomingCalls or outgoingCalls request.
+  std::string data;
+};
+llvm::json::Value toJSON(const CallHierarchyItem &);
+bool fromJSON(const llvm::json::Value &, CallHierarchyItem &, llvm::json::Path);
+
+/// The parameter of a `callHierarchy/incomingCalls` request.
+struct CallHierarchyIncomingCallsParams {
+  CallHierarchyItem item;
+};
+bool fromJSON(const llvm::json::Value &, CallHierarchyIncomingCallsParams &,
+              llvm::json::Path);
+
+/// Represents an incoming call, e.g. a caller of a method or constructor.
+struct CallHierarchyIncomingCall {
+  /// The item that makes the call.
+  CallHierarchyItem from;
+
+  /// The range at which the calls appear.
+  /// This is relative to the caller denoted by `From`.
+  std::vector<Range> fromRanges;
+};
+llvm::json::Value toJSON(const CallHierarchyIncomingCall &);
+
+/// The parameter of a `callHierarchy/outgoingCalls` request.
+struct CallHierarchyOutgoingCallsParams {
+  CallHierarchyItem item;
+};
+bool fromJSON(const llvm::json::Value &, CallHierarchyOutgoingCallsParams &,
+              llvm::json::Path);
+
+/// Represents an outgoing call, e.g. calling a getter from a method or
+/// a method from a constructor etc.
+struct CallHierarchyOutgoingCall {
+  /// The item that is called.
+  CallHierarchyItem to;
+
+  /// The range at which this item is called.
+  /// This is the range relative to the caller, and not `To`.
+  std::vector<Range> fromRanges;
+};
+llvm::json::Value toJSON(const CallHierarchyOutgoingCall &);
+
 struct ReferenceParams : public TextDocumentPositionParams {
   // For now, no options like context.includeDeclaration are supported.
 };
 bool fromJSON(const llvm::json::Value &, ReferenceParams &, llvm::json::Path);
 
 /// Clangd extension: indicates the current state of the file in clangd,
 /// sent from server via the `textDocument/clangd.fileStatus` notification.
 struct FileStatus {

clang-tools-extra/clangd/Protocol.cpp

 }
 
 bool fromJSON(const llvm::json::Value &Params, ReferenceParams &R,
               llvm::json::Path P) {
   TextDocumentPositionParams &Base = R;
   return fromJSON(Params, Base, P);
 }
 
+llvm::json::Value toJSON(SymbolTag Tag) {
+  return llvm::json::Value{static_cast<int>(Tag)};
+}
+
+llvm::json::Value toJSON(const CallHierarchyItem &I) {
+  llvm::json::Object Result{{"name", I.name},
+                            {"kind", static_cast<int>(I.kind)},
+                            {"range", I.range},
+                            {"selectionRange", I.selectionRange},
+                            {"uri", I.uri}};
+  if (!I.tags.empty())
+    Result["tags"] = I.tags;
+  if (!I.detail.empty())
+    Result["detail"] = I.detail;
+  if (!I.data.empty())
+    Result["data"] = I.data;
+  return std::move(Result);
+}
+
+bool fromJSON(const llvm::json::Value &Params, CallHierarchyItem &I,
+              llvm::json::Path P) {
+  llvm::json::ObjectMapper O(Params, P);
+
+  // Populate the required fields only. We don't care about the
+  // optional fields `Tags` and `Detail` for the purpose of
+  // client --> server communication.
+  return O && O.map("name", I.name) && O.map("kind", I.kind) &&
+         O.map("uri", I.uri) && O.map("range", I.range) &&
+         O.map("selectionRange", I.selectionRange) &&
+         O.mapOptional("data", I.data);
+}
+
+bool fromJSON(const llvm::json::Value &Params,
+              CallHierarchyIncomingCallsParams &C, llvm::json::Path P) {
+  llvm::json::ObjectMapper O(Params, P);
+  return O.map("item", C.item);
+}
+
+llvm::json::Value toJSON(const CallHierarchyIncomingCall &C) {
+  return llvm::json::Object{{"from", C.from}, {"fromRanges", C.fromRanges}};
+}
+
+bool fromJSON(const llvm::json::Value &Params,
+              CallHierarchyOutgoingCallsParams &C, llvm::json::Path P) {
+  llvm::json::ObjectMapper O(Params, P);
+  return O.map("item", C.item);
+}
+
+llvm::json::Value toJSON(const CallHierarchyOutgoingCall &C) {
+  return llvm::json::Object{{"to", C.to}, {"fromRanges", C.fromRanges}};
+}
+
 static const char *toString(OffsetEncoding OE) {
   switch (OE) {
   case OffsetEncoding::UTF8:
     return "utf-8";
   case OffsetEncoding::UTF16:
     return "utf-16";
   case OffsetEncoding::UTF32:
     return "utf-32";