Proposal: textDocument/prepareCodeAction

[AmadeusW]

Problem:

LSP server may be under heavy load when a client makes excessive calls to textDocument/codeActions in order to display a code action icon in the margin. The icon depends solely on a single CodeActionKind, yet the textDocument/codeActions requires server to compute all actions that are available at a given location. This request is made frequently: whenever caret moves and lightbulb is not yet present in the margin. This places heavy computational burden on the server.

Client chooses an icon based on CodeActionKind available at a line of code.

Goal:

The goal of the following proposal is to expose a request which allows a client to query for available CodeActionKinds without requiring the server to perform expensive computation of all code actions. This request is expected to be lightweight, as a client may make it frequently: for example, whenever caret moves and lightbulb is not yet present in the margin.

Proposed solution:

The prepare code action request is sent from the client to the server to display the appropriate lightbulb icon in the margin at a given caret location or selected range.

Request:

• method: textDocument/prepareCodeAction
• params: prepareCodeActionsParams defined as follows:

export interface PrepareCodeActionParams {
	/**
	 * The document in which the command was invoked.
	 */
	textDocument: TextDocumentIdentifier;

	/**
	 * The range for which the command was invoked.
	 */
	range: Range;
}

Note: This matches textDocument/codeAction request which does not extend TextDocumentPositionParams but passes in Range instead of Position

Response:

• result: CodeActionKind[] | null describing all or single CodeActionKind available at requested position. Client will display lightbulb icon based on its own understanding of precedence of CodeActionKinds. If null is returned then it is deemed that textDocument/codeAction request is not valid at the given range, and textDocument/prepareCodeActions will be queried as soon as the caret moves.

Server capability:

export interface CodeActionOptions extends WorkDoneProgressOptions {
	/**
	 * Server supports testing for available code action kinds.
	 */
	prepareSupport?: boolean;
}

Behavior for servers which don't support this capability:

Visual Studio will continue to query textDocument/codeAction on caret move to obtain CodeActionKind. Remaining information will be discarded.

Difference from codeAction/resolve

codeAction/resolve allows a server to lazily compute TextEdits and other properties of a previously known code action which was selected by the developer. The proposed request doesn't require the server to discover and name all available actions. It only requires the server to determine whether a single action exists, and what is its kind.

Other considerations:

It looks like CodeActionOptions is tied to supporting code action literals. I don't fully understand these, and am curious whether there are clients or servers which would like to support textDocument/prepareCodeAction but don't support the literals.

[NTaylorMullen]

Looks great, one modification I'd do is update the beginning problem statement to be platform agnostic (no VS, no VSCode etc.)

[rwols]

Don't we already have codeAction/resolve for this? Just don't put key in textDocument.codeAction.resolveSupport.properties and servers are forced to provide the kind.

[AmadeusW]

Thanks for bringing this up @rwols, I added a note which compares this request with codeAction/resolve.

The main difference is that codeAction/resolve requires server to initially discover all actions, so that they can appear in the code actions menu. Once developer selects one item, client calls codeAction/resolve to get its text edits.

The proposed textDocument/prepareCodeAction doesn't require the server to discover and name all available actions; It only requires the server to declare whether a single action exists, and what is its kind. Many servers can answer this query cheaply, particularly the servers evolved from Visual Studio language services.

[dbaeumer]

@mjbvz I already discussed this with @jrieken and we came to the conclusion that such a request makes sense. Do you have any feedback on this or may be ideas how to improve.

[mjbvz]

I think the idea make sense. I don't love the name since this only talks about code action kinds, but we already have prepareRename which is similar

[dbaeumer]

Yes, the naming got influenced by prepareRename

[dbaeumer]

@AmadeusW can you prepare a PR that adds this?