Add LSP types and server stubs for call hierarchy support (#377)

* Add LSP types and server stubs for call hierarchy support

* Update CMakeLists.txt for new LSP types

* Call hierarchy misc fixes

* Minor PositionRangeArray fixes to simplify codable conformance

* Add CodingTests for PositionRangeArray and CallHierarchy encoding

Author: DavidGoldman

Sources/LanguageServerProtocol/CMakeLists.txt

@@ -22,6 +22,9 @@ add_library(LanguageServerProtocol
   Notifications/TextSynchronizationNotifications.swift
 
   Requests/ApplyEditRequest.swift
+  Requests/CallHierarchyIncomingCallsRequest.swift
+  Requests/CallHierarchyOutgoingCallsRequest.swift
+  Requests/CallHierarchyPrepareRequest.swift
   Requests/CodeActionRequest.swift
   Requests/ColorPresentationRequest.swift
   Requests/CompletionRequest.swift
@@ -45,6 +48,7 @@ add_library(LanguageServerProtocol
   Requests/WorkspaceFoldersRequest.swift
   Requests/WorkspaceSymbolsRequest.swift
 
+  SupportTypes/CallHierarchyItem.swift
   SupportTypes/ClientCapabilities.swift
   SupportTypes/CodeActionKind.swift
   SupportTypes/Command.swift

Sources/LanguageServerProtocol/Messages.swift

@@ -22,6 +22,9 @@ public let builtinRequests: [_RequestType.Type] = [
   CompletionRequest.self,
   HoverRequest.self,
   WorkspaceSymbolsRequest.self,
+  CallHierarchyIncomingCallsRequest.self,
+  CallHierarchyOutgoingCallsRequest.self,
+  CallHierarchyPrepareRequest.self,
   DefinitionRequest.self,
   ImplementationRequest.self,
   ReferencesRequest.self,

Sources/LanguageServerProtocol/PositionRange.swift

@@ -45,6 +45,34 @@ public struct PositionRange: CustomCodableWrapper {
   }
 }
 
+/// An LSP-compatible encoding for `Array<Range<Position>>`, for use with `CustomCodable`.
+public struct PositionRangeArray: CustomCodableWrapper {
+  public var wrappedValue: [Range<Position>]
+
+  public init(wrappedValue: [Range<Position>]) {
+    self.wrappedValue = wrappedValue
+  }
+
+  public init(from decoder: Decoder) throws {
+    var values: [Range<Position>] = []
+    var arrayContainer = try decoder.unkeyedContainer()
+    values.reserveCapacity(arrayContainer.count ?? 1)
+
+    while !arrayContainer.isAtEnd {
+      let range = try arrayContainer.decode(PositionRange.self)
+      values.append(range.wrappedValue)
+    }
+    self.wrappedValue = values
+  }
+
+  public func encode(to encoder: Encoder) throws {
+    var arrayContainer = encoder.unkeyedContainer()
+    for rangeValue in wrappedValue {
+      try arrayContainer.encode(PositionRange(wrappedValue: rangeValue))
+    }
+  }
+}
+
 extension Range: LSPAnyCodable where Bound == Position {
   public init?(fromLSPDictionary dictionary: [String : LSPAny]) {
     guard case .dictionary(let start)? = dictionary[PositionRange.CodingKeys.lowerBound.stringValue],

Sources/LanguageServerProtocol/Requests/CallHierarchyIncomingCallsRequest.swift

@@ -0,0 +1,40 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+/// The request is sent from the client to the server to resolve the callers for
+/// a given call hierarchy item. It is only issued if a server registers for the
+/// `textDocument/prepareCallHierarchy` request.
+public struct CallHierarchyIncomingCallsRequest: RequestType {
+  public static let method: String = "callHierarchy/incomingCalls"
+  public typealias Response = [CallHierarchyIncomingCall]?
+
+  public var item: CallHierarchyItem
+
+  public init(item: CallHierarchyItem) {
+    self.item = item
+  }
+}
+
+/// Represents a caller (an incoming call) - an item that makes a call of the original `item`.
+public struct CallHierarchyIncomingCall: ResponseType, Hashable {
+  /// The item that makes the call.
+  public var from: CallHierarchyItem
+
+  /// The range(s) of calls inside the caller (the item denoted by `from`).
+  @CustomCodable<PositionRangeArray>
+  public var fromRanges: [Range<Position>]
+
+  public init(from: CallHierarchyItem, fromRanges: [Range<Position>]) {
+    self.from = from
+    self.fromRanges = fromRanges
+  }
+}

Sources/LanguageServerProtocol/Requests/CallHierarchyOutgoingCallsRequest.swift

@@ -0,0 +1,40 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+/// The request is sent from the client to the server to resolve callees for a given call hierarchy item.
+/// It is only issued if a server registers for the `textDocument/prepareCallHierarchy` request.
+public struct CallHierarchyOutgoingCallsRequest: RequestType {
+  public static let method: String = "callHierarchy/outgoingCalls"
+  public typealias Response = [CallHierarchyOutgoingCall]?
+
+  public var item: CallHierarchyItem
+
+  public init(item: CallHierarchyItem) {
+    self.item = item
+  }
+}
+
+/// Represents a callee (an outgoing call) - an item that is called by the original `item`.
+public struct CallHierarchyOutgoingCall: ResponseType, Hashable {
+  /// The item that is called.
+  public var to: CallHierarchyItem
+
+  /// The range(s) at which this item is called by the caller (the item inside
+  /// the `callHierarchy/outgoingCalls` request).
+  @CustomCodable<PositionRangeArray>
+  public var fromRanges: [Range<Position>]
+
+  public init(to: CallHierarchyItem, fromRanges: [Range<Position>]) {
+    self.to = to
+    self.fromRanges = fromRanges
+  }
+}

Sources/LanguageServerProtocol/Requests/CallHierarchyPrepareRequest.swift

@@ -0,0 +1,35 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+/// The call hierarchy request is sent from the client to the server to return a call hierarchy for the
+/// language element of the given text document positions.
+///
+/// The call hierarchy requests are executed in two steps:
+/// 1. A call hierarchy item is resolved for the given text document position
+///   (via `textDocument/prepareCallHierarchy`)
+/// 2. The incoming or outgoing call hierarchy items are resolved for a call hierarchy item
+///   (via `callHierarchy/incomingCalls` or `callHierarchy/outgoingCalls`)
+public struct CallHierarchyPrepareRequest: TextDocumentRequest, Hashable {
+  public static let method: String = "textDocument/prepareCallHierarchy"
+  public typealias Response = [CallHierarchyItem]?
+
+  /// The document in which to prepare the call hierarchy items.
+  public var textDocument: TextDocumentIdentifier
+
+  /// The document location at which to prepare the call hierarchy items.
+  public var position: Position
+
+  public init(textDocument: TextDocumentIdentifier, position: Position) {
+    self.textDocument = textDocument
+    self.position = position
+  }
+}

Sources/LanguageServerProtocol/SupportTypes/CallHierarchyItem.swift

@@ -0,0 +1,60 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+/// A single call hierarchy item.
+public struct CallHierarchyItem: ResponseType, Hashable {
+  /// Name of this item.
+  public var name: String
+
+  public var kind: SymbolKind
+  public var tags: [SymbolTag]?
+
+  /// More detail for this item, e.g. the signature of a function.
+  public var detail: String?
+
+  /// The resource identifier of this item.
+  public var uri: DocumentURI
+
+  /// The range enclosing this symbol, excluding leading/trailing whitespace
+  /// but including everything else, e.g. comments and code.
+  @CustomCodable<PositionRange>
+  public var range: Range<Position>
+
+  /// 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 the `range`.
+  @CustomCodable<PositionRange>
+  public var selectionRange: Range<Position>
+
+  /// A data entry field that is preserved between a call hierarchy prepare and
+  /// incoming calls or outgoing calls requests.
+  public var data: LSPAny?
+
+  public init(
+    name: String,
+    kind: SymbolKind,
+    tags: [SymbolTag]?,
+    detail: String? = nil,
+    uri: DocumentURI,
+    range: Range<Position>,
+    selectionRange: Range<Position>,
+    data: LSPAny? = nil
+  ) {
+    self.name = name
+    self.kind = kind
+    self.tags = tags
+    self.detail = detail
+    self.uri = uri
+    self.range = range
+    self.selectionRange = selectionRange
+    self.data = data
+  }
+}

Sources/LanguageServerProtocol/SupportTypes/ClientCapabilities.swift

@@ -438,6 +438,8 @@ public struct TextDocumentClientCapabilities: Hashable, Codable {
 
   public var foldingRange: FoldingRange? = nil
 
+  public var callHierarchy: DynamicRegistrationCapability? = nil
+
   public init(synchronization: Synchronization? = nil,
               completion: Completion? = nil,
               hover: Hover? = nil,
@@ -458,7 +460,8 @@ public struct TextDocumentClientCapabilities: Hashable, Codable {
               colorProvider: DynamicRegistrationCapability? = nil,
               rename: DynamicRegistrationCapability? = nil,
               publishDiagnostics: PublishDiagnostics? = nil,
-              foldingRange: FoldingRange? = nil) {
+              foldingRange: FoldingRange? = nil,
+              callHierarchy: DynamicRegistrationCapability? = nil) {
     self.synchronization = synchronization
     self.completion = completion
     self.hover = hover
@@ -480,5 +483,6 @@ public struct TextDocumentClientCapabilities: Hashable, Codable {
     self.rename = rename
     self.publishDiagnostics = publishDiagnostics
     self.foldingRange = foldingRange
+    self.callHierarchy = callHierarchy
   }
 }

Sources/LanguageServerProtocol/SupportTypes/ServerCapabilities.swift

@@ -81,6 +81,10 @@ public struct ServerCapabilities: Codable, Hashable {
 
   public var workspace: WorkspaceServerCapabilities?
 
+  /// Whether the server provides `textDocument/prepareCallHierarchy` and related
+  /// call hierarchy requests.
+  public var callHierarchyProvider: ValueOrBool<TextDocumentAndStaticRegistrationOptions>?
+
   public var experimental: LSPAny?
 
   public init(
@@ -107,6 +111,7 @@ public struct ServerCapabilities: Codable, Hashable {
     declarationProvider: ValueOrBool<TextDocumentAndStaticRegistrationOptions>? = nil,
     executeCommandProvider: ExecuteCommandOptions? = nil,
     workspace: WorkspaceServerCapabilities? = nil,
+    callHierarchyProvider: ValueOrBool<TextDocumentAndStaticRegistrationOptions>? = nil,
     experimental: LSPAny? = nil
   )
   {
@@ -133,6 +138,7 @@ public struct ServerCapabilities: Codable, Hashable {
     self.declarationProvider = declarationProvider
     self.executeCommandProvider = executeCommandProvider
     self.workspace = workspace
+    self.callHierarchyProvider = callHierarchyProvider
     self.experimental = experimental
   }
 }

Sources/LanguageServerProtocol/SupportTypes/SymbolKind.swift

@@ -53,3 +53,17 @@ public struct SymbolKind: RawRepresentable, Codable, Hashable {
   public static let `operator`: SymbolKind = SymbolKind(rawValue: 25)
   public static let typeParameter: SymbolKind = SymbolKind(rawValue: 26)
 }
+
+/// Symbol tags are extra annotations that tweak the rendering of a symbol.
+///
+/// In LSP, this is an integer, so we don't use a closed set.
+public struct SymbolTag: RawRepresentable, Codable, Hashable {
+  public var rawValue: Int
+
+  public init(rawValue: Int) {
+    self.rawValue = rawValue
+  }
+
+  /// Render a symbol as obsolete, usually using a strike-out.
+  public static let deprecated: SymbolTag = SymbolTag(rawValue: 1)
+}