Proposing a protocol extension for call hierarchy.

Adds the `textDocument/callHierarchy` request sent from the client to the server to request the call hierarchy for a symbol at the given text document position.

LSP issue: language-server-protocol#468

Signed-off-by: Alex Tugarev <alex.tugarev@typefox.io>

protocol/src/main.ts

@@ -35,7 +35,19 @@ export * from './protocol';
 
 export { FoldingRangeParams as FoldingRangeRequestParam } from './protocol'; // for backward compatibility
 
+import * as callHierarchy from './protocol.callHierarchy.proposed';
+
 export namespace Proposed {
+	export type CallHierarchyClientCapabilities = callHierarchy.CallHierarchyClientCapabilities;
+	export type CallHierarchyServerCapabilities = callHierarchy.CallHierarchyServerCapabilities;
+
+	export namespace CallHierarchyRequest {
+		export const type = callHierarchy.CallHierarchyRequest.type;
+		export type HandlerSignature = callHierarchy.CallHierarchyRequest.HandlerSignature;
+	}
+
+	export type CallHierarchyParams = callHierarchy.CallHierarchyParams;
+	export type CallHierarchyCall = callHierarchy.CallHierarchyCall;
 }
 
 export interface ProtocolConnection {

protocol/src/protocol.callHierarchy.proposed.md

@@ -0,0 +1,127 @@
+
+#### Call Hierarchy
+
+The LSP provides retrieving the call hierachy information with the following request.
+
+_Client Capabilities_:
+
+```ts
+CallHierarchyClientCapabilities {
+    /**
+     * The text document client capabilities
+     */
+    textDocument?: {
+        /**
+         * Capabilities specific to the `textDocument/callHierarchy`
+         */
+        callHierarchy?: {
+            /**
+             * Whether implementation supports dynamic registration. If this is set to `true`
+             * the client supports the new `(TextDocumentRegistrationOptions & StaticRegistrationOptions)`
+             * return value for the corresponding server capability as well.
+             */
+            dynamicRegistration?: boolean;
+        };
+    }
+}
+```
+
+_Server Capabilities_:
+
+```ts
+CallHierarchyServerCapabilities {
+    /**
+     * The server provides Call Hierarchy support.
+     */
+    callHierarchyProvider?: boolean | (TextDocumentRegistrationOptions & StaticRegistrationOptions);
+}
+```
+
+##### Call Hierarchy Request
+
+_Request_:
+
+The `textDocument/callHierarchy` request is sent from the client to the server to request the call hierarchy for a symbol defined (or referenced) at the given text document position.
+
+Returns a call hierarchy item for the requested call direction. ERROR
+
+* method: ‘textDocument/callHierarchy'
+* params: `CallHierarchyParams` defined as follows:
+
+```ts
+export interface CallHierarchyParams extends TextDocumentPositionParams {
+    /**
+     * The direction of calls to provide.
+     */
+    direction: CallHierarchyDirection;
+}
+
+export namespace CallHierarchyDirection {
+    export const Incoming: 1 = 1;
+    export const Outgoing: 2 = 2;
+}
+```
+
+_Response_:
+
+The server will send a collection of `CallHierarchyCall` objects, or `null` if no callable symbol is found at the given document position.
+
+Each `CallHierarchyCall` object defines a call from one `CallHierarchySymbol` to another.
+
+* result: `CallHierarchyCall[]` | `null`
+
+```ts
+export interface CallHierarchyCall {
+
+    /**
+     * The source range of the reference. The range is a sub range of the `from` symbol range.
+     */
+    range: Range;
+
+    /**
+    * The symbol that contains the reference.
+     */
+    from: CallHierarchySymbol;
+
+    /**
+     * The symbol that is referenced.
+    */
+    to: CallHierarchySymbol;
+}
+
+export interface CallHierarchySymbol {
+
+    /**
+     * The name of the symbol targeted by the call hierarchy request.
+     */
+    name: string;
+
+    /**
+     * More detail for this symbol, e.g the signature of a function.
+     */
+    detail?: string;
+
+    /**
+     * The kind of this symbol.
+     */
+    kind: SymbolKind;
+
+    /**
+     * URI of the document containing the symbol.
+     */
+    uri: string;
+
+    /**
+     * The range enclosing this symbol not including leading/trailing whitespace but everything else
+     * like comments. This information is typically used to determine if the the clients cursor is
+     * inside the symbol to reveal in the symbol in the UI.
+     */
+    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 the the `range`.
+     */
+    selectionRange: Range;
+}
+```

protocol/src/protocol.callHierarchy.proposed.ts

@@ -0,0 +1,132 @@
+/* --------------------------------------------------------------------------------------------
+ * Copyright (c) TypeFox and others. All rights reserved.
+ * Licensed under the MIT License. See License.txt in the project root for license information.
+ * ------------------------------------------------------------------------------------------ */
+'use strict';
+
+import { RequestType, RequestHandler } from 'vscode-jsonrpc';
+import { SymbolKind, Range } from 'vscode-languageserver-types';
+import { TextDocumentRegistrationOptions, StaticRegistrationOptions, TextDocumentPositionParams } from './protocol';
+
+export interface CallHierarchyClientCapabilities {
+    /**
+     * The text document client capabilities
+     */
+    textDocument?: {
+        /**
+         * Capabilities specific to the `textDocument/callHierarchy`
+         */
+        callHierarchy?: {
+            /**
+             * Whether implementation supports dynamic registration. If this is set to `true`
+             * the client supports the new `(TextDocumentRegistrationOptions & StaticRegistrationOptions)`
+             * return value for the corresponding server capability as well.
+             */
+            dynamicRegistration?: boolean;
+        };
+    }
+}
+
+export interface CallHierarchyServerCapabilities {
+    /**
+     * The server provides Call Hierarchy support.
+     */
+    callHierarchyProvider?: boolean | (TextDocumentRegistrationOptions & StaticRegistrationOptions);
+}
+
+/**
+ * Request to provide the call hierarchy at a given text document position.
+ *
+ * The request's parameter is of type [CallHierarchyParams](#CallHierarchyParams). The response
+ * is of type [CallHierarchyCall[]](#CallHierarchyCall) or a Thenable that resolves to such.
+ *
+ * Evaluates the symbol defined (or referenced) at the given position, and returns all incoming or outgoing calls to the symbol(s).
+ */
+export namespace CallHierarchyRequest {
+    export const type = new RequestType<CallHierarchyParams, CallHierarchyCall[], void, TextDocumentRegistrationOptions>('textDocument/callHierarchy');
+    export type HandlerSignature = RequestHandler<CallHierarchyParams, CallHierarchyCall[] | null, void>;
+}
+
+/**
+ * The parameter of a `textDocument/callHierarchy` request extends the `TextDocumentPositionParams` with the direction of calls to resolve.
+ */
+export interface CallHierarchyParams extends TextDocumentPositionParams {
+    /**
+     * The direction of calls to provide.
+     */
+    direction: CallHierarchyDirection;
+}
+
+/**
+ * The direction of a call hierarchy request.
+ */
+export namespace CallHierarchyDirection {
+    /**
+     * The callers of a symbol.
+     */
+    export const Incoming: 1 = 1;
+
+    /**
+     * The callees of a symbol.
+     */
+    export const Outgoing: 2 = 2;
+}
+
+export type CallHierarchyDirection = 1 | 2;
+
+/**
+ * The result of a `textDocument/callHierarchy` request.
+ */
+export interface CallHierarchyCall {
+
+    /**
+     * The source range of the reference. The range is a sub range of the `from` symbol range.
+     */
+    range: Range;
+
+	/**
+	 * The symbol that contains the reference.
+	 */
+	from: CallHierarchySymbol;
+
+	/**
+	 * The symbol that is referenced.
+	 */
+	to: CallHierarchySymbol;
+}
+
+export interface CallHierarchySymbol {
+
+    /**
+     * The name of the symbol targeted by the call hierarchy request.
+     */
+    name: string;
+
+    /**
+     * More detail for this symbol, e.g the signature of a function.
+     */
+    detail?: string;
+
+    /**
+     * The kind of this symbol.
+     */
+    kind: SymbolKind;
+
+    /**
+     * URI of the document containing the symbol.
+     */
+    uri: string;
+
+    /**
+     * The range enclosing this symbol not including leading/trailing whitespace but everything else
+     * like comments. This information is typically used to determine if the the clients cursor is
+     * inside the symbol to reveal in the symbol in the UI.
+     */
+    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 the the `range`.
+     */
+    selectionRange: Range;
+}