Code actions contribution point

[mjbvz]

Problem

For feature requests such as #52846 or any improved refactoring UX, VS Code needs to know all the code actions that are available for a language. Some information about available code actions is provided by CodeActionProviderMetadata but only if an extension has been activated and the provider has been registered

Proposal

To support this, we likely want a new contribution point that lets extensions statically tell us about the general classes of the code actions that they provide:

{
  "contributions": {
    "codeActions": [
      {
        "languages": [
          "javascript",
          "javascriptreact",
          "typescript",
          "typescriptreact"
        ],
        "actions": [
          {
            "kind": "refactor.extract.constant",
            "title": "Extract constant",
            "description": "Extract expression to a constant."
          }
        ]
      }
    ]
  }
}

Potential use cases for this info

• Show on the extension's contribution page Show contributed code actions in extensions view #84091
• IntelliSense for codeActionsOnSave (c8d64b1)
• IntelliSense for configuring refactors in the keybinding json editor Code action intellisense in the keybindings JSON editor #84033
• IntelliSense for configuring refactors in UI keybinding editor Allow viewing and editing commands with 'args' in the keybindings editor #84072
• Improving the refactor context menu in VS Code

/cc @kieferrm

[mjbvz]

I have checked in a prototype of the static codeActions contribution point and have hooked up a few examples of how this information could be used by us, such as providing intellisense for editor.codeActionsOnSave and when configuring code action keybindings. I think that a static contribution point makes sense for use cases like these, although it means that extensions need to generate those static lists for us, see: microsoft/TypeScript#34859

@jrieken brought up that not all extensions may be able to generate these lists ahead of time, such as those using Rosyln. For some use cases, we may also want to dynamically enabled/disable which code actions are shown to the user. If you are using an old TypeScript version for example, refactoring is not supported. An example of where code actions would be enabled/disabled would a improved refactor context menu in the editor

My current thinking on static vs dynamic contribution points is that we likely want both:

• The static info would document all possible code actions that may be available. Having this makes sense IMO when you are configuring keybindings. It also does not require activating extensions.

• The dynamic info about what code actions are really available in the current file would be useful for the refactoring menu in the editor. The CodeActionProviderMetadata api already lets extensions provide this info to us

[mjbvz]

Copying a few extension authors for feedback on contribution point and possible use cases

@DanTup for Dart
@DonJayamanne for Python
@DustinCampbell for C#

[mjbvz]

Based on trying this for JS/TS, I've added a description field and changed the schema to the following:

 "codeActions": [
      {
        "languages": [
          "javascript",
          "javascriptreact",
          "typescript",
          "typescriptreact"
        ],
        "actions": [
          {
            "kind": "refactor.extract.constant",
            "title": "%codeActions.refactor.extract.constant.title%",
            "description": "%codeActions.refactor.extract.constant.description%"
          },
          ....
        ]
      }
    ]

[DonJayamanne]

Are these code actions context aware (visa a callback)?
I.e. can I have them show up in one file and not the other. Or one line and not the other?

[mjbvz]

This proposal does not effect the existing CodeActionProvider api (which lets your extension control which actual code actions are shown to the user in the editor). The static contribution point proposed here aims to supports some of the use cases outlined above without needing to activate any extensions

[DonJayamanne]

The static info would document all possible code actions that may be available. Having this makes sense IMO when you are configuring keybindings. It also does not require activating extensions.

Missed this.

[DanTup]

The code actions in Dart are all defined in the language server, so we can't really provide this ahead-of-time either. This is similar to a request I made a while ago for keybinds:

#45383

I expected them to only show up when the extension is activated though - not ideal, but supports the case where they might change across different versions of SDKs that you can't possibly know ahead-of-time.

[jrieken]

@mjbvz Maybe something more pragmatic. Once a code action provider registered (dynamically) we store its code action kinds (for configurations) and revalidate them whenever registration happens again or when an extension cannot be found anymore. That would work better with dynamic code action lists and still yield in a better user experience - except the first time before the first activation.

[mjbvz]

@DanTup This is the case for TS as well. There should be some way for you to extract this list, either manually or with automation. Again the idea is that the extension provides the complete set of all possible refactorings that users can configure—regardless of what specific language version a user is on—and that this does not any impact on what actions are actually shown in the editor

I'm not opposed to allowing the same metadata to be contributed dynamically as well, but this would also be new information that extensions would have to provide to VS Code (i.e. through a new api). The current CodeActionProviderMetadata is not sufficient

@jrieken Managing a cache of metadata about code actions will get very complicated. TS for example only contributes a refactor provider if you are using TS 2.8, and user can explicitly disable some code actions like organize imports through settings

[DanTup]

@DanTup This is the case for TS as well. There should be some way for you to extract this list, either manually or with automation.

Sure, it just means having some script to update/maintain it I was hoping to avoid :-)

and user can explicitly disable some code actions like organize imports through settings

Doesn't that affect a static list in the same way (there may be things in the static list that have been disabled)?

[orta]

I made a script which generates all of TypeScripts microsoft/TypeScript#34859 (comment) , but the tricky thing here is that it won't account for a workspace's version of typescript (only vscode's) - which could end up asking for refactors that don't exist. That could end up being a tricky mismatch.

We wondered about making it something the TSServer could provide? but that kinda undermines the point of having it beforehand.

[akaroml]

While we do Java language support in VS Code, we always hoped there could be some way to fully expose all the capabilities. The problem with the dynamic way is that the options are contextual. So we constantly hear from the users asking for some refactoring features that are actually there. They just couldn't find them or figure out how to trigger them.

That's why I really like this idea of having this new contribution point, which introduces the static way of exposing all possible code actions. The extension's contribution will make it even better by showing all the options in one place. Power users would want to set hot keys to specific actions, and this will also be possible and convenient.

One feedback is still regarding discoverability. IntelliJ has this top menu entry to expose all refactoring options. It shows the full picture even when some options are not available at the moment. It would be great to have some equivalent in VS Code because refactoring is especially important for languages like Java, C#.

[jrieken]

Managing a cache of metadata about code actions will get very complicated. TS for example only contributes a refactor provider if you are using TS 2.8, and user can explicitly disable some code actions like organize imports through settings

Yes, but applying the same logic how it is then better to "cache" them at compile time, e.g writing them upfront into package.json without knowing anything about the user or her/his settings nor being able to change that list? What I am suggesting is to cache them only between the time of deactivation and activation.

[mjbvz]

In our existing keybindings UX, we let users configure keybindings for any command. Many of these commands are only actually enabled when the user has enabled a setting or switched their language run time, but that does not prevent users from setting up the keybinding.

I believe that is also the behavior we want when configure keybindings for code actions or refactors: I should always be able to configure a keybinding for extract constant if we know some extension provides it. A static contribution point enables that

[DanTup]

@mjbvz what's the status of this? If I want my code actions to show up in the keybinding list, should I be statically contributing them in package.json like this, or just providing them via documentation (like #89388)? It's not clear if documentation also includes this?

[DanTup]

Strangely, although some code actions show up in the keybinding list, if I try to add my own based on the info above, I get this warning:

If I remove the array (?!), then it breaks the intellisense for the existing ones, because it throws an error trying to call slice on the actions object.

[DanTup]

(oh, ignoring the warning seems like the right thing - my code action then shows up! 🤨)

[heejaechang]

Pylance team wants to expose all individuals fix all code actions to users so they can configure which fix all code actions run on file save. currently there seems no way to add those individual action names in editor.codeActionsOnSave schema. and no way to provide default value for code actions on save for each fix all code actions.

I think that makes it very hard for users to discover each fix all actions and make default such as source.fixAll: true very intrusive since updating extension without knowing that it just added new fix all code action can change users code unexpectedly. furthermore, in current design, it will be very hard to find out which extension actually did it.

Please, provide a way to configure this by each fix all code action provider

[vs-code-engineering]

We closed this issue because we don't plan to address it in the foreseeable future. If you disagree and feel that this issue is crucial: we are happy to listen and to reconsider.

If you wonder what we are up to, please see our roadmap and issue reporting guidelines.

Thanks for your understanding, and happy coding!