Skip to content

Allow clients to pass experimental capabilities they want to enable as a dictionary #2204

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

ahoppen
Copy link
Member

@ahoppen ahoppen commented Jul 14, 2025

The motivation for this is that I noticed that the workspace/peekDocuments request only allows the specification of a document to peek but not the location to peek within it. The fix is to change the location parameter from DocumentUri to Location, but this is a protocol-breaking change, so the client needs to communicate that it can support locations in the workspace/peekDocuments request.

The client currently communicates that it supports peeking documents by passing workspace/peekDocuments: true in the experimental client capabilities. We could just add another option to the experimental client capabilities like workspace/peekDocuments.supportsLocations but this seems a little hacky. Instead, what I propose is that we

  1. Allow enabling experimental capabilities as "<capability name>": { "supported": true }
  2. Switch the VS Code Swift extension to enable client capabilities using a dictionary if it discovers that it uses SourceKit-LSP ≥6.3 (older SourceKit-LSP don’t recogize a dictionary as enabling a capability)
  3. Expanding the options to "workspace/peekDocuments": { "supported" true, "supportsLocation": true } to communicate that location-based peeking is supported

This pattern will also support experimental capability changes like this in the future.

Use cases that might lack because of this are:

  1. Using an old Swift 6.3 toolchain that doesn’t support dictionary-based capabilities with the VS Code Swift extension. In that case macro expansion will work in the fallback mode that we have for other editors and active editor tracking (which cancels target preparation when a file is switched) is disabled. I think this is acceptable.
  2. If there are other editors that support these experimental capabilities, they will continue to work just fine by passing the boolen value to enable the option. If they want to support one of the options (eg. location-based peeking), they will need to switch to dictinary-based enabling and thus check the SourceKit-LSP version prior to startup. This might be mildly annoying on their side but since the number of client that support these capabilities should be very small (I am not aware of any) and they need to explicitly opt-in to the new behavior, I think this is also acceptable.

…s a dictionary

The motivation for this is that I noticed that the `workspace/peekDocuments` request only allows the specification of a document to peek but not the location to peek within it. The fix is to change the `location` parameter from `DocumentUri` to `Location`, but this is a protocol-breaking change, so the client needs to communicate that it can support locations in the `workspace/peekDocuments` request.

The client currently communicates that it supports peeking documents by passing `workspace/peekDocuments: true` in the experimental client capabilities. We could just add another option to the experimental client capabilities like `workspace/peekDocuments.supportsLocations` but this seems a little hacky. Instead, what I propose is that we
1. Allow enabling experimental capabilities as `"<capability name>": { "supported": true }`
2. Switch the VS Code Swift extension to enable client capabilities using a dictionary if it discovers that it uses SourceKit-LSP ≥6.3 (older SourceKit-LSP don’t recogize a dictionary as enabling a capability)
3. Expanding the options to `"workspace/peekDocuments": { "supported" true, "supportsLocation": true }` to communicate that location-based peeking is supported

This pattern will also support experimental capability changes like this in the future.

Use cases that might lack because of this are:
1. Using an old Swift 6.3 toolchain that doesn’t support dictionary-based capabilities with the VS Code Swift extension. In that case macro expansion will work in the fallback mode that we have for other editors and active editor tracking (which cancels target preparation when a file is switched) is disabled. I think this is acceptable.
2. If there are other editors that support these experimental capabilities, they will continue to work just fine by passing the boolen value to enable the option. If they want to support one of the options (eg. location-based peeking), they will need to switch to dictinary-based enabling and thus check the SourceKit-LSP version prior to startup. This might be mildly annoying on their side but since the number of client that support these capabilities should be very small (I am not aware of any) and they need to explicitly opt-in to the new behavior, I think this is also acceptable.
@ahoppen
Copy link
Member Author

ahoppen commented Jul 14, 2025

@swift-ci Please test

ahoppen added a commit to ahoppen/vscode-swift that referenced this pull request Jul 14, 2025
ahoppen added a commit to ahoppen/vscode-swift that referenced this pull request Jul 14, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant