Add pathMappings option to debugger

[jborean93]

PR Summary

Adds the pathMappings option to the debugger that can be used to map a local to remote path and vice versa. This is useful if the local environment has a checkout of the files being run on a remote target but at a different path. The mappings are used to translate the paths that will the breakpoint will be set to in the target PowerShell instance. It is also used to update the stack trace paths received from the remote.

For a launch scenario, the path mappings are also used when launching a script if the integrated terminal has entered a remote runspace.

PR Context

Fixes: #2242

[Copilot]

Pull Request Overview

This PR adds a pathMappings option to the PowerShell debugger that enables mapping between local and remote file paths during debugging sessions. This is particularly useful when debugging remote PowerShell instances where the local development environment has the same files but at different paths.

Key changes:

• Adds PathMapping record to define local-to-remote path mappings
• Integrates path mapping logic into breakpoint setting, stack trace handling, and script launching
• Adds comprehensive end-to-end test for attach scenarios with path mappings

Reviewed Changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
PathMapping.cs	New record defining the structure for local/remote path mappings
DebugService.cs	Core path mapping logic with methods to translate between local and remote paths
LaunchAndAttachHandler.cs	Integration of path mappings into launch and attach request handling
StackTraceHandler.cs	Updates stack trace paths using path mappings for remote debugging
BreakpointService.cs	Modified to use mapped paths when setting breakpoints
BreakpointApiUtils.cs	Added script path override parameter for breakpoint setting
DisconnectHandler.cs	Cleanup of path mappings on disconnect
DscBreakpointCapability.cs	Minor refactor to extract module name instead of full module info
DebugAdapterProtocolMessageTests.cs	Comprehensive E2E test for path mapping functionality

Comments suppressed due to low confidence (1)

test/PowerShellEditorServices.Test.E2E/DebugAdapterProtocolMessageTests.cs:580

• Spelling error: 'cotinue' should be 'continue'.

                // background and requesting the st is the only wait to ensure

[Copilot]

Path comparison using StartsWith without ensuring proper path separators could lead to incorrect matches. For example, '/home/user' would incorrectly match '/home/username/file.ps1'. Consider using proper path comparison logic that respects directory boundaries.

Suggested change

	if (remotePath.StartsWith(mapping.RemoteRoot, StringComparison.OrdinalIgnoreCase))
	{
	localPath = mapping.LocalRoot + remotePath.Substring(mapping.RemoteRoot.Length);
	string normalizedRemotePath = Path.GetFullPath(remotePath);
	string normalizedRemoteRoot = Path.GetFullPath(mapping.RemoteRoot);
	if (normalizedRemotePath.StartsWith(normalizedRemoteRoot, StringComparison.OrdinalIgnoreCase) &&
	Path.GetRelativePath(normalizedRemoteRoot, normalizedRemotePath).IndexOf("..", StringComparison.Ordinal) != 0)
	{
	localPath = Path.Combine(mapping.LocalRoot, Path.GetRelativePath(normalizedRemoteRoot, normalizedRemotePath));

[jborean93]

In this case it is use supplied values. if they wish to not use a directory separator at the end of the localRoot or remoteRoot then that's their decision. The path mappings is designed to replace the root substring with the specified equivalent.

[Copilot]

Same path comparison issue as with TryGetMappedLocalPath. Using StartsWith without proper path boundary checking could lead to incorrect path mappings.

Suggested change

	if (localPath.StartsWith(mapping.LocalRoot, StringComparison.OrdinalIgnoreCase))
	if (localPath.StartsWith(mapping.LocalRoot, StringComparison.OrdinalIgnoreCase) &&
	(localPath.Length == mapping.LocalRoot.Length ||
	localPath[mapping.LocalRoot.Length] == System.IO.Path.DirectorySeparatorChar ||
	localPath[mapping.LocalRoot.Length] == System.IO.Path.AltDirectorySeparatorChar))

[jborean93]

See #2251 (comment)

[jborean93]

An example of how the pathMappings can be used for launching when the interactive terminal has entered a remote runspace. The editor sees the file under /home/jborean/dev/vscode-powershell/examples/test.ps1 but the pathMappings will map it to C:\temp\test.ps1 where that same script is located on the remote host.

{
  "name": "PowerShell Launch Script",
  "type": "PowerShell",
  "request": "launch",
  "script": "${workspaceFolder}/test.ps1",
  "cwd": "${cwd}",
  "pathMappings": [
    {
      "localRoot": "${workspaceFolder}/",
      "remoteRoot": "C:\\temp\\"
    }
  ]
},

It looks like I need to update the logic for the client breakpoint to contain the original workspace path and not the mapped remote file so I will fix that.