api to support call hierarchy view

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

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;
}

LGTM!
Typo descibes -> describes

more typos #70231

Ron Buckton (@rbuckton)

Ron Buckton (@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

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.

move call hierarchy API to stable, #70231

Ron Buckton (@rbuckton)

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

Johannes Rieken (@jrieken)

Johannes Rieken (@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.

Dirk Bäumer (@dbaeumer)

Dirk Bäumer (@dbaeumer) will follow up with the LSP once we have shipped this version

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

Navigation Menu

Repository navigation

api to support call hierarchy view #70231

21 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

api to support call hierarchy view #70231

Description

Activity

jrieken commented on Mar 14, 2019

aeschli commented on Mar 27, 2019

21 remaining items

jrieken commented on Oct 25, 2019

aeschli commented on Oct 25, 2019

mjbvz commented on Oct 26, 2019

rbuckton commented on Oct 26, 2019

jrieken commented on Oct 28, 2019

testforstephen commented on Oct 29, 2019

jrieken commented on Oct 29, 2019

jrieken commented on Oct 29, 2019

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions