diff --git a/protocol/src/main.ts b/protocol/src/main.ts index 7368fa994..2938e13e2 100644 --- a/protocol/src/main.ts +++ b/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 { diff --git a/protocol/src/protocol.callHierarchy.proposed.md b/protocol/src/protocol.callHierarchy.proposed.md new file mode 100644 index 000000000..9b1670b8c --- /dev/null +++ b/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. diff --git a/protocol/src/protocol.callHierarchy.proposed.ts b/protocol/src/protocol.callHierarchy.proposed.ts new file mode 100644 index 000000000..f5deefef0 --- /dev/null +++ b/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('textDocument/callHierarchy'); + export type HandlerSignature = RequestHandler; +} + +/** + * 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('callHierarchy/resolve'); + export type HandlerSignature = RequestHandler; +} + +/** + * 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; +}