Add LSP extension to show Macro Expansions (or any document) in a "peeked" editor (and some minor quality improvements)

lokesh-tr commented 3 weeks ago

Intro:

Note: This Feature is Experimental 🧪. You have to first enable this feature by passing --experimental-feature show-macro-expansions to sourcekit-lsp

The previous PR (https://github.com/apple/sourcekit-lsp/pull/1436) lays the foundation for adding LSP support to show Macro Expansions of any kind. This PR brings better macro expansion functionality to all editors and some custom functionality through LSP extension for VS Code (, which other editors can also utilise by custom request handling.)

If you are interested in bringing the custom functionality to your own editor, I highly recommend going through the PR below: Accompanying PR in "Swift for VS Code" Extension": https://github.com/swiftlang/vscode-swift/pull/945

About this pull request:

This implements an LSP Extension PeekDocumentsRequest to let ExpandMacroCommand to open the macro expansions in a "peeked" editor window. For this to work, the client has to pass "workspace/peekDocuments" enabled to ClientCapabilities.experimental and the client should handle the PeekDocumentsRequest and show the expansions in a "peeked" editor window.

PR to support the above capability in the "Swift for VS Code" Extension: https://github.com/swiftlang/vscode-swift/pull/945 The "Swift for VS Code" extension cannot send the client capability, so it instead passes the same through initializationOptions in the InitializeRequest.

For editors which doesn't support this capability, sourcekit-lsp sends a ShowDocumentRequest. The ShowDocumentRequest is updated to show all the macro expansions in a single generated file. Moreover, its folder structure is updated to use hex string of MD5 hash of concatenation of buffer names of expansions.

This PR also does a lot of quality improvements.

List of all changes:

changes the shown Line and Column numbers to be One-based indexing instead of Zero-based indexing, so that users can match the macro expansions' line and column numbers with their editor's line and column numbers.
adds a test case for @attached Macro Expansion, thereby assures LSP support for @attached Macro Expansions.
fixes a bug where ShowDocumentRequest fails due to invalid selection
makes ShowDocumentRequest to use only a single file to display all the expansions
implements a general PeekDocumentsRequest that can be used to make the editor to open files in a peeked editor
if the client sets the experimental client capability peekDocuments (or alternatively, in the initializationOptions), then the ExpandMacroCommand sends a PeekDocumentsRequest instead of a ShowDocumentRequest. (Accompanying PR in vscode-swift extension: https://github.com/swiftlang/vscode-swift/pull/945)
Fixes https://github.com/swiftlang/vscode-swift/issues/564
updated all ExecuteCommandTests appropriately
Fixes https://github.com/swiftlang/sourcekit-lsp/issues/1498 (rdar://130207754)
Added Documentation wherever necessary
updates folder structure to utilise MD5 hash for ShowDocumentRequest generated macro expansions

References:

Previous PR which laid the foundation: https://github.com/apple/sourcekit-lsp/pull/1436 Accompanying PR in the Swift Extension for VS Code repository: https://github.com/swiftlang/vscode-swift/pull/945

Expansion of Swift Macros in Visual Studio Code - Google Summer Of Code 2024 @lokesh-tr @ahoppen @adam-fowler

lokesh-tr commented 2 weeks ago

@ahoppen I have also updated the PR to fix the bug where it fails to perform ShowDocumentRequest due to invalid selection, and I believe that the current implementation of DictionaryStorageMacro is the simplest form that works.

lokesh-tr commented 1 week ago

The last commit which I made breaks the test cases and is also a proof-of-concept implementation of the feature which will be implemented in a full-fledged manner.

Edit: Now, the test cases all pass and it's implemented in a full-fledged manner

Here's the accompanying PR https://github.com/swiftlang/vscode-swift/pull/945 in the VS Code Swift Extension Repository.

lokesh-tr commented 5 days ago

@ahoppen I have updated everything as per last call, I will squash the commits as soon as this passes the review stage.

lokesh-tr commented 5 days ago

@ahoppen Let me know if there's anything else needed to be fixed, I shall proceed to squash the commits if they are all good. I have also updated the vscode-swift PR to incorporate the new changes.

lokesh-tr commented 4 days ago

@ahoppen I have addressed your comments, let me know if there are any other concerns. I have also squashed the commits. I guess its ready to 🚢

ahoppen commented 4 days ago

@swift-ci Please test

lokesh-tr commented 3 days ago

@ahoppen trigger Test windows ?

ahoppen commented 3 days ago

@swift-ci Please test Windows

lokesh-tr commented 3 days ago

@ahoppen All the test cases pass. But, seems like a merge conflict happened in between. But the conflicting file Sources/SourceKitLSP/Swift/Refactoring.swift is already deleted / renamed to RefactoringResponse.swift. Do you want me to rebase once again and go through the tests once again? I guess it would be fine if you merge it directly by removing this file. 🤔

Edit: I rebased it anyways

ahoppen commented 3 days ago

@swift-ci Please test

ahoppen commented 3 days ago

@swift-ci Please test Windows

swiftlang / sourcekit-lsp