RenameProvider for variable/function renaming

CHANGELOG.md

@@ -28,6 +28,12 @@ Please update to PowerShell 7.4 LTS going forward.
 This release contains a logging overhaul which purposely removes our
 dependency on Serilog and should lead to improved stability with
 PowerShell 5.1 (by avoiding a major GAC assembly conflict).
+## v3.3.0
+### Friday, November 15, 2024
+
+See more details at the GitHub Release for [v3.3.0](https://github.com/PowerShell/PowerShellEditorServices/releases/tag/v3.3.0).
+
+Logging updates and dropped EOL PowerShell
 
 ## v3.21.0
 ### Wednesday, October 30, 2024

README.md

@@ -8,7 +8,7 @@
 functionality needed to enable a consistent and robust PowerShell development
 experience in almost any editor or integrated development environment (IDE).
 
-## [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) clients using PowerShell Editor Services:
+## [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) clients using PowerShell Editor Services
 
 - [PowerShell for Visual Studio Code](https://github.com/PowerShell/vscode-powershell)
 > [!NOTE]
@@ -143,6 +143,34 @@ The debugging functionality in PowerShell Editor Services is available in the fo
 - [powershell.nvim for Neovim](https://github.com/TheLeoP/powershell.nvim)
 - [intellij-powershell](https://github.com/ant-druha/intellij-powershell)
 
+### Rename Disclaimer
+
+PowerShell is not a statically typed language. As such, the renaming of functions, parameters, and other symbols can only be done on a best effort basis. While this is sufficient for the majority of use cases, it cannot be relied upon to find all instances of a symbol and rename them across an entire code base such as in C# or TypeScript.
+
+There are several edge case scenarios which may exist where rename is difficult or impossible, or unable to be determined due to the dynamic scoping nature of PowerShell.
+
+The focus of the rename support is on quick updates to variables or functions within a self-contained script file. It is not intended for module developers to find and rename a symbol across multiple files, which is very difficult to do as the relationships are primarily only computed at runtime and not possible to be statically analyzed.
+
+#### 👍 [Implemented and Tested Rename Scenarios](https://github.com/PowerShell/PowerShellEditorServices/blob/main/test/PowerShellEditorServices.Test.Shared/Refactoring)
+
+#### 🤚 Unsupported Scenarios
+
+- ❌ Renaming can only be done within a single file. Renaming symbols across multiple files is not supported, even if those are dotsourced from the source file.
+- ❌ Functions or variables must have a corresponding definition within their scope or above to be renamed. If we cannot find the original definition of a variable or function, the rename will not be supported.
+- ❌ Dynamic Parameters are not supported
+- ❌ Dynamically constructed splat parameters will not be renamed/updated (e.g. `$splat = @{};$splat.a = 5;Do-Thing @a`)
+- ❌ Scoped variables (e.g. $SCRIPT:test) are not currently supported
+- ❌ Renaming a variable inside of a scriptblock that is used in unscoped operations like `Foreach-Parallel` or `Start-Job` and the variable is not defined within the scriptblock is not supported and can have unexpected results.
+- ❌ Scriptblocks part of an assignment are considered isolated scopes. For example `$a = 5; $x = {$a}; & $x` does not consider the two $a to be related, even though in execution this reference matches.
+- ❌ Scriptblocks that are part of a parameter are assumed to not be executing in a different runspace. For example, the renaming behavior will treat `ForEach-Object -Parallel {$x}` the same as `Foreach-Object {$x}` for purposes of finding scope definitions. To avoid unexpected renaming, define/redefine all your variables in the scriptblock using a param block.
+- ❌ A lot of the logic relies on the position of items, so for example, defining a variable in a `begin` block and placing it after a `process` block, while technically correct in PowerShell, will not rename as expected. 
+- ❌ Similarly, defining a function, and having the function rely on a variable that is assigned outside the function and after the function definition, will not find the outer variable reference.
+- ❌ `Get-Variable` and `Set-Variable` are not considered and not currently searched for renames
+
+#### 📄 Filing a Rename Issue
+
+If there is a rename scenario you feel can be reasonably supported in PowerShell, please file a bug report in the PowerShellEditorServices repository with the "Expected" and "Actual" being the before and after rename. We will evaluate it and accept or reject it and give reasons why. Items that fall under the Unsupported Scenarios above will be summarily rejected, however that does not mean that they may not be supported in the future if we come up with a reasonably safe way to implement a scenario.
+
 ## API Usage
 
 Please note that we only consider the following as stable APIs that can be relied on:

src/PowerShellEditorServices/Server/PsesLanguageServer.cs

@@ -91,6 +91,8 @@ public async Task StartAsync()
                         .ClearProviders()
                         .AddPsesLanguageServerLogging()
                         .SetMinimumLevel(_minimumLogLevel))
+                    // TODO: Consider replacing all WithHandler with AddSingleton
+                    .WithConfigurationSection("powershell.rename")
                     .WithHandler<PsesWorkspaceSymbolsHandler>()
                     .WithHandler<PsesTextDocumentHandler>()
                     .WithHandler<GetVersionHandler>()
@@ -123,6 +125,8 @@ public async Task StartAsync()
                     .WithHandler<ExpandAliasHandler>()
                     .WithHandler<PsesSemanticTokensHandler>()
                     .WithHandler<DidChangeWatchedFilesHandler>()
+                    .WithHandler<PrepareRenameHandler>()
+                    .WithHandler<RenameHandler>()
                     // NOTE: The OnInitialize delegate gets run when we first receive the
                     // _Initialize_ request:
                     // https://microsoft.github.io/language-server-protocol/specifications/specification-current/#initialize

src/PowerShellEditorServices/Server/PsesServiceCollectionExtensions.cs

@@ -50,7 +50,8 @@ public static IServiceCollection AddPsesLanguageServices(
                         extensionService.InitializeAsync();
                         return extensionService;
                     })
-                .AddSingleton<AnalysisService>();
+                .AddSingleton<AnalysisService>()
+                .AddSingleton<RenameService>();
         }
 
         public static IServiceCollection AddPsesDebugServices(

src/PowerShellEditorServices/Services/PowerShell/Handlers/HandlerErrorException.cs

@@ -0,0 +1,22 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using OmniSharp.Extensions.JsonRpc;
+using OmniSharp.Extensions.LanguageServer.Protocol.Models;
+
+namespace Microsoft.PowerShell.EditorServices.Handlers;
+
+/// <summary>
+/// A convenience exception for handlers to throw when a request fails for a normal reason,
+/// and to communicate that reason to the user without a full internal stacktrace.
+/// </summary>
+/// <param name="message">The message describing the reason for the request failure.</param>
+/// <param name="logDetails">Additional details to be logged regarding the failure. It should be serializable to JSON.</param>
+/// <param name="severity">The severity level of the message. This is only shown in internal logging.</param>
+public class HandlerErrorException
+(
+    string message,
+    object logDetails = null,
+    MessageType severity = MessageType.Error
+) : RpcErrorException((int)severity, logDetails!, message)
+{ }

src/PowerShellEditorServices/Services/PowerShell/Refactoring/Exceptions.cs

@@ -0,0 +1,40 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System;
+namespace Microsoft.PowerShell.EditorServices.Refactoring
+{
+    public class TargetSymbolNotFoundException : Exception
+    {
+        public TargetSymbolNotFoundException()
+        {
+        }
+
+        public TargetSymbolNotFoundException(string message)
+            : base(message)
+        {
+        }
+
+        public TargetSymbolNotFoundException(string message, Exception inner)
+            : base(message, inner)
+        {
+        }
+    }
+
+    public class FunctionDefinitionNotFoundException : Exception
+    {
+        public FunctionDefinitionNotFoundException()
+        {
+        }
+
+        public FunctionDefinitionNotFoundException(string message)
+            : base(message)
+        {
+        }
+
+        public FunctionDefinitionNotFoundException(string message, Exception inner)
+            : base(message, inner)
+        {
+        }
+    }
+}

src/PowerShellEditorServices/Services/TextDocument/Handlers/FormattingHandlers.cs

@@ -90,7 +90,7 @@ public override async Task<TextEditContainer> Handle(DocumentFormattingParams re
                 return s_emptyTextEditContainer;
             }
 
-            return new TextEditContainer(new TextEdit
+            return new TextEditContainer(new OmniSharp.Extensions.LanguageServer.Protocol.Models.TextEdit
             {
                 NewText = formattedScript,
                 Range = editRange
@@ -184,7 +184,7 @@ public override async Task<TextEditContainer> Handle(DocumentRangeFormattingPara
                 return s_emptyTextEditContainer;
             }
 
-            return new TextEditContainer(new TextEdit
+            return new TextEditContainer(new OmniSharp.Extensions.LanguageServer.Protocol.Models.TextEdit
             {
                 NewText = formattedScript,
                 Range = editRange

src/PowerShellEditorServices/Services/TextDocument/Handlers/RenameHandler.cs

@@ -0,0 +1,41 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+#nullable enable
+
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.PowerShell.EditorServices.Services;
+
+using OmniSharp.Extensions.LanguageServer.Protocol.Document;
+using OmniSharp.Extensions.LanguageServer.Protocol.Models;
+using OmniSharp.Extensions.LanguageServer.Protocol.Client.Capabilities;
+
+namespace Microsoft.PowerShell.EditorServices.Handlers;
+
+/// <summary>
+/// A handler for <a href="https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_prepareRename">textDocument/prepareRename</a>
+/// </summary>
+internal class PrepareRenameHandler
+(
+    RenameService renameService
+) : IPrepareRenameHandler
+{
+    public RenameRegistrationOptions GetRegistrationOptions(RenameCapability capability, ClientCapabilities clientCapabilities) => capability.PrepareSupport ? new() { PrepareProvider = true } : new();
+
+    public async Task<RangeOrPlaceholderRange?> Handle(PrepareRenameParams request, CancellationToken cancellationToken)
+        => await renameService.PrepareRenameSymbol(request, cancellationToken).ConfigureAwait(false);
+}
+
+/// <summary>
+/// A handler for <a href="https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_rename">textDocument/rename</a>
+/// </summary>
+internal class RenameHandler(
+    RenameService renameService
+) : IRenameHandler
+{
+    // RenameOptions may only be specified if the client states that it supports prepareSupport in its initial initialize request.
+    public RenameRegistrationOptions GetRegistrationOptions(RenameCapability capability, ClientCapabilities clientCapabilities) => capability.PrepareSupport ? new() { PrepareProvider = true } : new();
+
+    public async Task<WorkspaceEdit?> Handle(RenameParams request, CancellationToken cancellationToken)
+        => await renameService.RenameSymbol(request, cancellationToken).ConfigureAwait(false);
+}