api to support call hierarchy view

[jrieken]

This is for #16110, ideas already exist in microsoft/vscode-languageserver-node#420

[jrieken]

For June we plan to change the API to @aeschli's proposal: #70231 (comment)

[testforstephen]

@jrieken When will the new API be ready? I'd like to try the call hierarchy feature in Java language server.

[testforstephen]

i have tried the api in Java language server, here is the feedback:

• The client api lags behind the protocol.callHierarchy.proposed.md definition.
• Peek Call Hierarchy shows the callee hierarchy by default, but i prefer to show the caller hierarchy by default. Other IDEs, such as Intellij IDEA and Eclipse, show the Caller Method Hierarchy by default.
• For the callee hierarchy, when clicking the callee method at the right panel, the left panel will refresh the code region, but it doesn't select the callee method name. The caller hierarchy works.

[jrieken]

An updated proposal (based on @aeschli's feedback) can be found here: #80112

[jrieken]

Moving to October for finalisation

[jrieken]

The final and revised proposal featuring a prepare function to get started and two provide functions that work on call hierarchy items.

/**
* Represents programming constructs like functions or constructors in the context
* of call hierarchy.
*/
export class CallHierarchyItem {
    /**
    * The name of this item.
    */
    name: string;

    /**
    * The kind of this item.
    */
    kind: SymbolKind;

    /**
    * Tags for this item.
    */
    tags?: ReadonlyArray<SymbolTag>;

    /**
    * More detail for this item, e.g. the signature of a function.
    */
    detail?: string;

    /**
    * The resource identifier of this item.
    */
    uri: 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 the [`range`](#CallHierarchyItem.range).
    */
    selectionRange: Range;

    constructor(kind: SymbolKind, name: string, detail: string, uri: Uri, range: Range, selectionRange: Range);
}

/**
* Represents an incoming call, e.g. a caller of a method or constructor.
*/
export class CallHierarchyIncomingCall {

    /**
    * The item that makes the call.
    */
    from: CallHierarchyItem;

    /**
    * The range at which at which the calls appears. This is relative to the caller
    * denoted by [`this.from`](#CallHierarchyIncomingCall.from).
    */
    fromRanges: Range[];

    /**
    * Create a new call object.
    *
    * @param item The item making the call.
    * @param fromRanges The ranges at which the calls appear.
    */
    constructor(item: CallHierarchyItem, fromRanges: Range[]);
}

/**
* Represents an outgoing call, e.g. calling a getter from a method or a method from a constructor etc.
*/
export class CallHierarchyOutgoingCall {

    /**
    * The item that is called.
    */
    to: CallHierarchyItem;

    /**
    * The range at which this item is called. This is the range relative to the caller, e.g the item
    * passed to [`provideCallHierarchyOutgoingCalls`](#CallHierarchyItemProvider.provideCallHierarchyOutgoingCalls)
    * and not [`this.to`](#CallHierarchyOutgoingCall.to).
    */
    fromRanges: Range[];

    /**
    * Create a new call object.
    *
    * @param item The item being called
    * @param fromRanges The ranges at which the calls appear.
    */
    constructor(item: CallHierarchyItem, fromRanges: Range[]);
}

/**
* The call hierarchy provider interface describes the constract between extensions
* and the call hierarchy feature which allows to browse calls and caller of function,
* methods, constructor etc.
*/
export interface CallHierarchyProvider {

    /**
    * Bootstraps call hierarchy by returning the item that is denoted by the given document
    * and position. This item will be used as entry into the call graph. Providers should
    * return `undefined` or `null` when there is no item at the given location.
    *
    * @param document The document in which the command was invoked.
    * @param position The position at which the command was invoked.
    * @param token A cancellation token.
    * @returns A call hierarchy item or a thenable that resolves to such. The lack of a result can be
    * signaled by returning `undefined` or `null`.
    */
    prepareCallHierarchy(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<CallHierarchyItem>;

    /**
    * Provide all incoming calls for an item, e.g all callers for a method. In graph terms this descibes directed
    * and annotated edges inside the call graph, e.g the given item is the starting node and the result is the nodes
    * that can be reached.
    *
    * @param item The hierarchy item for which incoming calls should be computed.
    * @param token A cancellation token.
    * @returns A set of incoming calls or a thenable that resolves to such. The lack of a result can be
    * signaled by returning `undefined` or `null`.
    */
    provideCallHierarchyIncomingCalls(item: CallHierarchyItem, token: CancellationToken): ProviderResult<CallHierarchyIncomingCall[]>;

    /**
    * Provide all outgoing calls for an item, e.g call calls to functions, methods, or constructors from the given item. In
    * graph terms this descibes directed and annotated edges inside the call graph, e.g the given item is the starting
    * node and the result is the nodes that can be reached.
    *
    * @param item The hierarchy item for which outgoing calls should be computed.
    * @param token A cancellation token.
    * @returns A set of outgoing calls or a thenable that resolves to such. The lack of a result can be
    * signaled by returning `undefined` or `null`.
    */
    provideCallHierarchyOutgoingCalls(item: CallHierarchyItem, token: CancellationToken): ProviderResult<CallHierarchyOutgoingCall[]>;
}

export namespace languages {

    /**
    * Register a call hierarchy provider.
    *
    * @param selector A selector that defines the documents this provider is applicable to.
    * @param provider A call hierarchy provider.
    * @return A [disposable](#Disposable) that unregisters this provider when being disposed.
    */
    export function registerCallHierarchyProvider(selector: DocumentSelector, provider: CallHierarchyProvider): Disposable;
}

[aeschli]

LGTM!
Typo descibes -> describes

[mjbvz]

@rbuckton You were looking into this on the TS side; does this API look ok to you? Also did you determine if we need a new TS server api for this. My current thinking is that while we could implement call hierarchy using the existing TSServer apis such as find all references, that may require a lot of calls. And there would be false positives too, such as cases where functions are passed into other higher order functions

[rbuckton]

If we're not planning to use find-all-references for this, then we'd definitely need a new API in tsserver. In general the API looks good to me.

[jrieken]

@rbuckton I don't that out going calls can be implemented without extra API in ts-server

[testforstephen]

@jrieken As i understand, this api is for the client to register call hierarchy provider. For the Java language, we want to make the jdt language server to provide call hierarchy provider directly. Looks like there is some small difference between protocol.callHierarchy.proposed.md definition and the client api. So are there any changes required for call hierarchy LSP? Any issue to track it? thanks.

[jrieken]

@dbaeumer will follow up with the LSP once we have shipped this version

[jrieken]

I believe it's this issue: microsoft/vscode-languageserver-node#520 (comment)