x/tools/gopls: provide a way to run ExecuteCommand features in one step

[leitzler]

What version of Go are you using (go version)?

golang.org/x/tools v0.0.0-20200721032237-77f530d86f9a
golang.org/x/tools/gopls v0.0.0-20200721032237-77f530d86f9a

I was adding fillstruct support to govim and they way gopls currently works is that it require a CodeAction/ExecuteCommand/ApplyEdit dance.

From a user point of view I see fillstruct as a direct request, initiated when the user already have the cursor placed on a non-filled struct identifier and the sole intention is to fill it.

It would be nice to be able to call ExecuteCommand from the client w/o a CodeAction request in before, but as discussed on Slack the different commands (and their arguments) aren't stable enough to be made public.
Example of a fillstruct command as returned by CodeAction:

Command:     &protocol.Command{
    Title:     "Fill foo with default values",
    Command:   "fill_struct",
    Arguments: {
        "{\"uri\":\"file:///private/var/folders/xm/ls208xd174v95pgd20rn_qbh0000gn/T/tmp.lmXRD9mP/main.go\",\"range\":{\"start\":{\"line\":7,\"character\":6},\"end\":{\"line\":7,\"character\":6}}}",
    },
},

As long as there is only one single (fillstruct) Command in the response, govim can automatically do another roundtrip and call ExecuteCommand with that Command. But if there are more than one Command in the CodaAction response (or the command isn't a fillstruct) there is currently no good way for the client to tell them apart.

Neither Command name (e.g. "fill_struct") or Arguments are specified anywhere so the client cannot know if/which command that belong to the request. Title is a dynamic string that contain the struct identifier. Using that field would require string matching (and unique struct identifiers on each line).

AFAIK other commands, such as "Extract variable" or "Extract function", are falls into the same category of user-invoked commands with a clear intent.

From my point of view gopls needs the following to be able to provide one step commands (I could obviously have missed other/better ways).

• Use explicit kinds for all CodeActions with Commands, like refactor.rewrite.fillstruct instead of just the base kind refactor.rewrite so that it is possible to request a single kind of code action commands.
• Allow a more narrow range as part of the CodeAction request (see CL244519). fillstruct operates on the whole line regardless of range specified in the CodeAction parameters.

[gopherbot]

Change https://golang.org/cl/244519 mentions this issue: internal/lsp: allow narrower scope for convenience CodeActions

[stamblerre]

Use explicit kinds for all CodeActions with Commands, like refactor.rewrite.fillstruct instead of just the base kind refactor.rewrite so that it is possible to request a single kind of code action commands.

We do still need to look into how these code action kinds work, and maybe we will use them. Still, I think that a client executing commands directly will always be prone to errors and incompatibilities, at least until the protocol has a way to tell the client which arguments should be provided to which commands.

I'm not sure if this is something that the protocol will support, but microsoft/language-server-protocol#642 and microsoft/language-server-protocol#430 are relevant. It may be worth filing an issue for this specifically, as I'm sure that every language has to deal with this issue.

Unless something changes, the only "correct" way to call fillstruct will be to first call codeAction, as that's the only correct way of getting the command and checking if it's available to call.

[leitzler]

We do still need to look into how these code action kinds work, and maybe we will use them. Still, I think that a client executing commands directly will always be prone to errors and incompatibilities, at least until the protocol has a way to tell the client which arguments should be provided to which commands.

Yes, the purpose here would be to provide a way for the client to ask for fillstruct (or any of the others) explicitly in the CodeAction request.

I think that would be needed in the case of refactor.extract already, and refactor.rewrite if/when other rewrites than fillstruct is added.

If the user want to extract to function they call CodeAction with only set to refactor.extract today and gets two CodeAction responses, one for "Extract to variable" and one for "Extract to function". They can't be told apart w/o looking at the Title.

That's why I suggest adding refactor.extract.function in the CodeAction request so the response can be used to call ExecuteCommand.

[leitzler]

To clarify the intent here; It doesn't have to be client crafted calls to ExecuteCommand. Requiring another LSP roundtrip (like CodeLens or CodeAction) is also a way to implement it in a way so it acts as one step for the user.

Heschi had a suggestion on the latest tools call, for a potential way forward. That would be to add existing CodeLenses as CodeActions as well (opt-in, disabled by default). It would require each command to have a unique kind that can be sent from the client asOnly: field, e.g. refactor.rewrite.fillstruct instead of just the base kind refactor.rewrite.

Adding unique kinds to gopls might not be as intrusive as it can seem:

• The LSP specification about how the server announce the capabilities has a comment about it. All individual kinds don't have to be announced separately, it can continue to just announce base kinds:

/**
* CodeActionKinds that this server may return.
*
* The list of kinds may be generic, such as CodeActionKind.Refactor, or the server
* may list out every specific kind they provide.
*/
codeActionKinds?: CodeActionKind[];

• The server should return all code actions that is included in a certain base kind, existing clients do not have to ask for explicit code actions (even if they may) - CodeActionKind filtering microsoft/language-server-protocol#970 (comment)

It could be tricky to fit some of the existing CodeLenses into a CodeAction basekind. I read somewhere (but lost the link) that the source base kind doesn't show up as a lightbulb in VSCode (since it "applies to the entire file") for example, but things like "go generate" isn't a perfect fit for that description.

According to LSP specification the entire set of kinds ".. is open and client needs to announce the kinds it support..." so it doesn't really prevent gopls from using a new base kind.

Thoughts?

[stamblerre]

That sounds reasonable enough to me, but it's definitely not a priority for us, so this would have to be contributor-driven. We're certainly open to adding more granular code action kinds.

[gopherbot]

Change https://golang.org/cl/259377 mentions this issue: gopls: add "go test" code action

[gopherbot]

Change https://golang.org/cl/290111 mentions this issue: internal/lsp: switch to the new command API

[gopherbot]

Change https://golang.org/cl/290190 mentions this issue: gopls/doc: add argument documentation for commands

[gopherbot]

Change https://golang.org/cl/289489 mentions this issue: internal/lsp/command: add an interface for workspace/executeCommand

[gopherbot]

Change https://go.dev/cl/587555 mentions this issue: gopls/internal/server: avoid VS Code lightbulb

[gopherbot]

Change https://go.dev/cl/604818 mentions this issue: gopls/internal/settings: use CodeActionKind hierarchy