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,24 @@ 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 namespace CallHierarchyResolveRequest {
+		export const type = callHierarchy.CallHierarchyResolveRequest.type;
+		export type HandlerSignature = callHierarchy.CallHierarchyResolveRequest.HandlerSignature;
+	}
+
+	export type CallHierarchyParams = callHierarchy.CallHierarchyParams;
+	export type ResolveCallHierarchyItemParams = callHierarchy.ResolveCallHierarchyItemParams;
+	export type CallHierarchyItem = callHierarchy.CallHierarchyItem;
 }
 
 export interface ProtocolConnection {

protocol/src/protocol.callHierarchy.proposed.md

@@ -0,0 +1,148 @@
+
+#### 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 at the given text document position.
+
+Returns a call hierarchy item for the requested call direction.
+
+* method: ‘textDocument/callHierarchy'
+* params: `CallHierarchyParams` defined as follows:
+
+```ts
+export interface CallHierarchyParams extends TextDocumentPositionParams {
+    resolve?: number;
+    direction?: CallHierarchyDirection;
+}
+```
+
+_Response_:
+
+The server will send a `CallHierarchyItem` object containing the information about the targeted symbol. The item will be undefined, if no such symbol is found.
+
+The item is _unresolved_ if the lists of callers and callees are undefined. Unresolved items can be resolved via `callHierarchy/resolve` requests.
+
+The resolved item includes callers or callees again of type `CallHierarchyItem`. The caller/callee object provide the actual location of the call (`CallHierarchyItem.callLocation`).
+
+* result: `CallHierarchyItem` | `null` defined as follows:
+
+```ts
+export interface CallHierarchyItem {
+
+    /**
+     * 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;
+
+    /**
+     * `true` if the hierarchy item is deprecated. Otherwise, `false`. It is `false` by default.
+     */
+    deprecated?: boolean;
+
+    /**
+     * 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;
+
+    /**
+     * The actual locations of incoming (or outgoing) calls to (or from) a callable identified by this item.
+     *
+     * *Note*: undefined in root item.
+     */
+    callLocations?: Location[];
+
+    /**
+     * List of incoming (or outgoing) calls to (or from) a callable identified by this item.
+     *
+     * *Note*: if undefined, this item is unresolved.
+     */
+    calls?: CallHierarchyItem[];
+
+    /**
+     * Optional data to identify an item in a resolve request.
+     */
+    data?: any;
+}
+```
+
+_Request_:
+
+The `callHierarchy/resolve` request is sent from the client to the server to resolve a call hierarchy item.
+
+Returns a resolved call hierarchy item for the requested call direction.
+
+* method: callHierarchy/resolve'
+* params: `CallHierarchyParams` defined as follows:
+
+```ts
+export interface ResolveCallHierarchyItemParams {
+    item: CallHierarchyItem;
+    resolve: number;
+    direction: CallHierarchyDirection;
+}
+```
+
+_Response_:
+
+The server will send a resolved `CallHierarchyItem` object.

protocol/src/protocol.callHierarchy.proposed.ts

@@ -0,0 +1,172 @@
+/* --------------------------------------------------------------------------------------------
+ * 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 { Location, 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 request the call hierarchy at a given text document position.
+ *
+ * The request's parameter is of type [CallHierarchyParams](#CallHierarchyParams). The response
+ * is of type [CallHierarchyItem](#CallHierarchyItem) or a Thenable that resolves to such.
+ *
+ * The optional request's parameter defines the maximum number of levels to [resolve](#CallHierarchyParams.resolve) by this request.
+ * Unresolved items can be resolved in subsequent `callHierarchy/resolve` requests.
+ */
+export namespace CallHierarchyRequest {
+    export const type = new RequestType<CallHierarchyParams, CallHierarchyItem, void, TextDocumentRegistrationOptions>('textDocument/callHierarchy');
+    export type HandlerSignature = RequestHandler<CallHierarchyParams, CallHierarchyItem | null, void>;
+}
+
+/**
+ * Request to resolve a call hierarchy item.
+ *
+ * The request's parameter is of type [ResolveCallHierarchyItemParams](#ResolveCallHierarchyItemParams). The response
+ * is of type [CallHierarchyItem](#CallHierarchyItem) or a Thenable that resolves to such.
+ */
+export namespace CallHierarchyResolveRequest {
+    export const type = new RequestType<ResolveCallHierarchyItemParams, CallHierarchyItem, void, void>('callHierarchy/resolve');
+    export type HandlerSignature = RequestHandler<ResolveCallHierarchyItemParams, CallHierarchyItem | null, void>;
+}
+
+/**
+ * The parameters of a `textDocument/callHierarchy` request.
+ */
+export interface CallHierarchyParams extends TextDocumentPositionParams {
+    /**
+     * The number of levels to resolve.
+     */
+    resolve?: number;
+    /**
+     * The direction of calls to resolve.
+     */
+    direction?: CallHierarchyDirection;
+}
+
+/**
+ * The parameters of a `callHierarchy/resolve` request.
+ */
+export interface ResolveCallHierarchyItemParams {
+    /**
+     * Unresolved item.
+     */
+    item: CallHierarchyItem;
+    /**
+     * The number of levels to resolve.
+     */
+    resolve: number;
+    /**
+     * The direction of calls to resolve.
+     */
+    direction: CallHierarchyDirection;
+}
+
+/**
+ * The direction of a call hierarchy.
+ */
+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 CallHierarchyItem {
+
+    /**
+     * 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;
+
+    /**
+     * `true` if the hierarchy item is deprecated. Otherwise, `false`. It is `false` by default.
+     */
+    deprecated?: boolean;
+
+    /**
+     * 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;
+
+    /**
+     * The actual locations of incoming (or outgoing) calls to (or from) a callable identified by this item.
+     *
+     * *Note*: undefined in root item.
+     */
+    callLocations?: Location[];
+
+    /**
+     * List of incoming (or outgoing) calls to (or from) a callable identified by this item.
+     *
+     * *Note*: if undefined, this item is unresolved.
+     */
+    calls?: CallHierarchyItem[];
+
+    /**
+     * Optional data to identify an item in a resolve request.
+     */
+    data?: any;
+}