GeezerVison

Fixes #45670.

Overview

Currently, when we offer completions for methods inside a class-like declaration, we only offer method names:

abstract class Base {
    abstract foo(param1: string, param2: boolean): Promise<void>;
}

class Sub extends Base {
    | /* completions offered: "foo" */
}

but in many cases, we have enough information to offer the whole method signature/declaration, like so:

class Sub extends Base {
    foo(param1: string, param2: boolean): Promise<void> {
        | // cursor ends up here
    }
}

This PR makes it so that we offer method and property declarations inside class declarations whenever possible.
The rough outline of how it works is:

• At some point in completions.ts, when answering a completions request, we gather symbols to be offered as completions, and then we call createCompletionEntry for each of those symbols. createCompletionEntry then converts a symbol into a proper CompletionEntry, which is what we will send back in response to a completion request.
• Ultimately, this PR changes how a CompletionEntry is created for a symbol, in the cases mentioned above.
  The main thing is the insertText property of a CompletionEntry: insertTextis the text that is inserted when a user accepts a completion, so for this new feature we want theinsertText` to be a whole signature/declaration, instead of just a name/identifier.
• To achieve that, there are two new functions used inside createCompletionEntry:
  • isClassLikeMemberCompletion(symbol): this decides whether or not a completion symbol is a class member and we should offer whole signature completions for it;
  • if the above function returns true, we call getEntryForMemberCompletion(symbol) for that completion symbol. This function will define what the insertText should be for that completion.

Core functionality

The main functionality of converting a symbol into a member node is provided by codefix.addNewNodeForMemberSymbol, called inside getEntryForMemberCompletion. This function already existed and is used by multiple codefixes, like classIncorrectlyImplementsInterface, to generate the member nodes that are missing in a class-like declaration.

Since codefix.addNewNodeForMemberSymbol was implemented for this missing member node scenario, there are some things we need to add on top of it to make everything work for a completions scenario, e.g. checking whether we should add an override modifier. Those additional constraints are mostly dealt with in the callback function passed to codefix.addNewNodeForMemberSymbol.

Snippets

Completions can use snippets to control where the cursor should go to when the completion is inserted (i.e. tab stops), to indicate the user should fill in some part of the completion, and to make it easier for the user to change parts of the completion-inserted text (i.e. placeholders). Snippet syntax reference can be found here: https://code.visualstudio.com/docs/editor/userdefinedsnippets#_snippet-syntax.

This new completion, so far, inserts method signatures or declarations. With that in mind, there are many places in such a signature/declaration where we could add snippet placeholders, to make it easy for the user to modify parts of the completion.

First, a final tabstop (i.e. $0) is always placed in the completion declaration's implementation body, if there is one. This means that the cursor will be at the empty body as its final position, once the completion is inserted.
Other than that, several parts of the declaration can be modified in ways that make sense (i.e. the code will type check). For example, the parameter and return types can be modified, as long as they conform to the type of the declaration being overridden/implemented.

The question of where to add placeholders/tabstops was discussed in a meeting. One of the initial points was that there were some cases when it was very likely that the user would want to change parts of the declaration, e.g. when changing the parameter types of an overload implementation, and in the rest of the cases it was less likely that the user would want to do so.

However, it was pointed out that snippets rely on "muscle memory" and predictability about where there will be tabstops/placeholders. So even though for the same declaration position (e.g. parameter type), we sometimes want to have a placeholder and sometimes not, it is better to favor uniformity and have the same tabstops/placeholders in the same declaration parts.

• Open question: what parts of a member declaration should be snippet placeholders? e.g. parameter names, parameter types, return type...

Emitter changes

The main concern implementation-wise with snippet support is emitting an AST into a string properly.
Some completions already use snippets (e.g. import completions), but these completion snippets are manipulated as strings. The completion feature in this PR requires a more complex completion text (e.g. a method signature), which becomes very tricky to manipulate as string, and is better to handle as an AST. So I decided to add support for snippets in our AST and emitter directly.

There is a new property, SnippetElement, added to EmitNode. An EmitNode is an optional property of nodes that gathers information pertinent to the emitter. The new SnippetElement property, when present in the emit node of a node, indicates that that node should be interpreted as some type of snippet element, e.g. a placeholder or a tabstop. The emitter will then handle printing that node into an appropriate string.

Example:
In the code

interface I {
    fun(a: string | number): number;
}

class C {
    fun(a: string | number): number {
           ^^^^^^^^^^^^^^^ // placeholder
    }
}

the string | number type node will have a SnippetElement of kind SnippetKind.Placeholder attached to its emit node.
Then, when the emitter is printing this type node, it will first print ${n:, then it will recursively print the (escaped) actual node, i.e. string | number, and then it will print }. In the end, the node will be printed as ${n:string | number}, which is the syntax for a placeholder whose text is string | number. (Note: n refers to a natural number here, corresponding to the order in which this placeholder/tabstop will be visited when the user presses tab sequentially).

Another thing added to the emitter is support for escaping text that would make the editor incorrectly understand a node as a snippet element.
For instance, if we have a method declaration like "$usd"(a: number): number, if we don't escape the $, the editor will think that $usd is a snippet variable instead of an identifier name.

Future work

• Support some edge cases pointed out in this PR's comments
• Support this feature in JS files (including support for JSDoc)
• Support offering those declaration completions for class properties?
• Support offering those declaration completions in objects/interfaces/object types and not only class-like declarations?
• Improve overloads support:
  • heuristics for determining default types in implementation signature
  • snippet placeholder sync?