Skip to content

Add pathMappings option to debugger#2251

Merged
andyleejordan merged 3 commits into
PowerShell:mainfrom
jborean93:path-mapping
Sep 4, 2025
Merged

Add pathMappings option to debugger#2251
andyleejordan merged 3 commits into
PowerShell:mainfrom
jborean93:path-mapping

Conversation

@jborean93

Copy link
Copy Markdown
Contributor

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 AI review requested due to automatic review settings July 31, 2025 06:00

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment thread src/PowerShellEditorServices/Services/DebugAdapter/PathMapping.cs Outdated
Comment thread test/PowerShellEditorServices.Test.E2E/DebugAdapterProtocolMessageTests.cs Outdated
Comment thread test/PowerShellEditorServices.Test.E2E/DebugAdapterProtocolMessageTests.cs Outdated
Comment thread src/PowerShellEditorServices/Services/DebugAdapter/DebugService.cs Outdated
Comment thread src/PowerShellEditorServices/Services/DebugAdapter/DebugService.cs Outdated
@jborean93

Copy link
Copy Markdown
Contributor Author

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\\"
    }
  ]
},
image

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.

Comment thread src/PowerShellEditorServices/Services/DebugAdapter/DebugService.cs Outdated
Comment thread src/PowerShellEditorServices/Services/DebugAdapter/DebugService.cs Outdated
Comment thread src/PowerShellEditorServices/Services/DebugAdapter/DebugService.cs Outdated
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.

@andyleejordan andyleejordan left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this!

@andyleejordan andyleejordan enabled auto-merge (squash) September 4, 2025 20:28
@andyleejordan andyleejordan changed the title Add pathMappings option to debugger Add pathMappings option to debugger Sep 4, 2025
@andyleejordan andyleejordan enabled auto-merge (squash) September 4, 2025 20:29
andyleejordan pushed a commit to PowerShell/vscode-powershell that referenced this pull request Sep 4, 2025
@andyleejordan andyleejordan merged commit 8d7e88f into PowerShell:main Sep 4, 2025
6 checks passed
@jborean93 jborean93 deleted the path-mapping branch September 4, 2025 21:01
@jborean93

Copy link
Copy Markdown
Contributor Author

Thanks for the review and merge!

@andyleejordan andyleejordan added the Issue-Enhancement A feature request (enhancement). label Sep 5, 2025
andyleejordan added a commit that referenced this pull request Jun 22, 2026
…ression); cap CI job (#2318)

* Reduce CI test timeout and fix busy-spin in `ReadScriptLogLineAsync`

The `CanAttachScriptWithPathMappings` E2E test intermittently hung
`windows-latest` CI for the full six-hour default — three of the last
eleven `main` runs died this way, all the same test, interspersed with
green runs (a classic flaky race, not a regression). None of the commits
whose runs hung touched the debugger attach path.

The hang mechanism lived in `ReadScriptLogLineAsync`: at EOF
`StreamReader.ReadLineAsync()` completes *synchronously* with `null`, so
the `while`/`await` polling loop never actually yielded. It busy-spun one
CPU at 100%, which starved the scheduler so none of the existing
cooperative safety nets — xUnit's `[SkippableFact(Timeout = 15000)]`, the
30s `debugTaskCts`, or `WaitForExitAsync` — could ever schedule their
continuations. A flaky few-second race thus escalated into a six-hour
wedge. Ironically the busy-loop landed in #2208, a PR meant to reduce
flakiness, and lay dormant until #2251 added a Windows-racy attach test
that actually hits the EOF spin.

- Back off with `await Task.Delay(100, token)` on EOF so we yield instead
  of busy-spinning, and cap the whole read with a 15s linked CTS that
  throws a clear `TimeoutException` naming the log path.
- Add `timeout-minutes: 15` to the `ci` job as a backstop so any future
  hang fails in 15 minutes instead of riding GitHub's 6-hour default. A
  normal run finishes well under that (Windows, the slowest, is ~12-14m).

The underlying attach race (reflection-based wait for `Debug-Runspace` to
subscribe) is still worth hardening, but it now fails fast instead of
hanging.

Drafted by Copilot (Claude Opus 4.8).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Revert "Match strong-name identity when resolving PSES dependencies (#2303)"

This reverts commit b9fd1b3.

#2303 is what broke `CanAttachScriptWithPathMappings` on Windows. A clean
bisection shows its parent (#2304, 6ad4f46) passed Windows E2E in ~12
minutes, while #2303 itself hung for 5h51m on that exact test -- and every
commit built on top of it inherited the hang. Months of green Windows runs
precede #2303.

The mechanism is in `PsesLoadContext.Load`. #2303 tightened
`IsSatisfyingAssembly` to also require a matching public key token and
culture. When a `$PSHOME` assembly previously satisfied a dependency by
name+version, `Load` returned `null` and PSES *shared* PowerShell's single
copy. Under the stricter check a token mismatch now fails that first test,
so `Load` falls through and loads our *own* bundled copy into the isolated
`PsesLoadContext` instead -- producing two copies of the same assembly in
two load contexts and a split type identity. The debugger-attach handshake
(`Debug-Runspace` subscribing to `RunspaceBase.AvailabilityChanged`, plus
the stopped-event plumbing in SMA) relies on cross-context event wiring
that silently breaks under such a split, so the attach never completes and
the test waits forever. It only trips on Windows because that is where the
`$PSHOME`-versus-bundled token divergence occurs. #2303's "no bundled
dependency changes resolution" check was static and missed an assembly
loaded dynamically during attach.

#2303 was self-described as "a focused trial of tightening" the matching,
so reverting it restores the long-standing, known-good behavior. We can
re-attempt the hardening later with this attach test as a guard.

Drafted by Copilot (Claude Opus 4.8).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Bump CI timeout backstop to 30 minutes

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Lower `ReadScriptLogLineAsync` cap below per-test xUnit timeout

The internal `CancelAfter` cap was 15s, exactly equal to the
`[SkippableFact(Timeout = 15000)]` on `CanAttachScriptWithPathMappings`.
Because xUnit's per-test timer covers the whole test -- attach,
setBreakpoints, configurationDone and waiting for stopped events all run
before `ReadScriptLogLineAsync` is even entered -- xUnit's generic
timeout would almost always fire first, so the descriptive
`TimeoutException` naming the log path would never surface for the very
test that motivated it.

Drop the cap to 10s so the clearer message can win for that test, while
still bounding the untimed `[Fact]` callers. Per review feedback from
copilot-pull-request-reviewer on #2318.

Drafted by Copilot (Claude Opus 4.8).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Restore #2303 and test helper, keeping only the CI timeout backstop

Reduce this branch to its one honest, effective change: a 30-minute
`timeout-minutes` on the CI test job. A normal run finishes well under
that (Windows, the slowest, is ~12-14 minutes), so the cap only bounds a
hung test instead of letting it ride GitHub's 6-hour default.

This un-reverts #2303 and drops the earlier `ReadScriptLogLineAsync`
change, both of which were based on a per-commit bisection that has since
been disproven. The Windows debugger-attach test
`CanAttachScriptWithPathMappings` intermittently wedges on the attach
handshake and rides the default timeout; the same hang reproduces on
`main` (which contains #2303) and reproduced here with #2303 reverted, so
#2303 is not the cause and is restored. The attach test wedges before it
ever reaches `ReadScriptLogLineAsync`, so that change could not affect the
hang and its short internal cap risked introducing new flakiness on a
slow-but-healthy attach; it is reverted too. The intermittent attach hang
is tracked separately.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix thread-pool starvation that wedged attach E2E test

CanAttachScriptWithPathMappings intermittently hung Windows CI for hours
instead of failing fast. Its ReadScriptLogLineAsync tailed the script log
with `while (...) await ReadLineAsync()`, but at EOF ReadLineAsync
completes synchronously with null, so the loop never released its
thread-pool thread. On constrained CI runners that starved the pool,
which both wedged the DAP client's background I/O and prevented the xUnit
(15s) and harness (30s) timeout continuations from ever running -- so a
transient stall rode the job timeout for hours.

Await a short delay between reads so the tail loop yields, and add a
matching sleep to the child process's Debug-Runspace readiness poll so it
cannot peg a core during the attach handshake. Combined with the
30-minute CI job cap, a genuine stall now fails fast via the test's own
timeout instead of hanging.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Skip attach E2E test on in-box Windows PowerShell

CanAttachScriptWithPathMappings hangs on in-box Windows PowerShell 5.1
since the windows-2025-vs2026 runner image refreshed from 20260608 to
20260614. The cross-process Debug-Runspace attach wedges and the test
rides the job timeout; the windows-latest leg cannot complete.

Scope the skip to IsWindowsPowerShell so the in-box WinPS suites
(including CLM) are exempt while PowerShell Core, the preview, macOS, and
Linux keep full coverage of the attach path. This is a stopgap pending a
real fix for the in-box attach deadlock, tracked by #2323; the 30-minute
timeout-minutes backstop in ci-test.yml stays as a guard.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Soften ReadScriptLogLineAsync comment to match root cause

The earlier comment asserted the EOF tight-loop was the cause of the
multi-hour Windows hang. Deconfounding analysis disproved that: the hang
is the in-box Windows PowerShell attach regression from the 20260614
runner image, not thread-pool starvation here. Keep the yield as genuine
harness hardening but describe it as such rather than claiming it as the
fix.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Skip attach E2E test at discovery time on Windows PowerShell

CanAttachScriptWithPathMappings wedges during the per-test InitializeAsync
(PSES debug-adapter server startup) on in-box Windows PowerShell since the
windows-2025-vs2026 runner image refresh, riding the job timeout in CI.

The prior in-body Skip.If(IsWindowsPowerShell) never fired because xUnit runs
IAsyncLifetime.InitializeAsync before the test body, and that setup is where
the hang occurs. Add a SkippableFact subclass that sets Skip in its
constructor so xUnit skips the test at discovery time, before it instantiates
the class or runs InitializeAsync. The SkippableFact discoverer is retained so
the runtime Constrained Language Mode skip still works off-Windows.

See #2323.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* ci: raise test job timeout to 60 minutes

The 30-minute cap was too aggressive as a backstop; bump it to 60 so a
genuinely slow (but not hung) run is not killed prematurely, while still
capping a wedged test well short of GitHub's 6-hour default.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Skip all debug adapter E2E tests on Windows PowerShell

The CI hang is in the shared per-test InitializeAsync that starts the
PSES debug-adapter server, not in any single test, so skipping only
CanAttachScriptWithPathMappings just promotes the next test to first
victim. Each test pays a fresh cold-start, and intermittently any one of
them can be the test that wedges on the 20260614 runner image.

Broaden the discovery-time Windows PowerShell skip to the entire
DebugAdapterProtocolMessageTests class: add a SkippableTheory companion
to the existing SkippableFact variant, share the skip reason, and apply
the attributes to all test methods. The pwsh (.NET 8) E2E suite still
runs the full set, so only in-box Windows PowerShell debug-adapter
coverage is paused, pending a real fix tracked in #2323.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Skip all language server E2E tests on Windows PowerShell

The in-box Windows PowerShell server wedges during startup on the current
windows-latest runner image, riding the job timeout. This is a runner-image
regression, not our code: re-running an old commit that predates all of our
recent PRs (and previously passed) now hangs the same way, while macOS and
Linux stay green. Because both E2E suites spawn the same WinPS-hosted server,
skipping only the debug adapter tests just relocated the hang to the language
server fixture's `LSPTestsFixture.InitializeAsync`, where `_psesHost.Start()`
launches the server.

- Apply the discovery-time `[SkippableFactOnWindowsPowerShell]` skip to every
  test method in `LanguageServerProtocolMessageTests`.
- Guard `LSPTestsFixture` so it does not start the server under Windows
  PowerShell, and dispose safely when it wasn't started. xUnit still creates an
  `IClassFixture<>` even when every method in the class is skipped at discovery
  time, so the discovery-time skip alone does not stop the fixture's own startup
  from hanging.
- Generalize the shared skip reason from `WindowsPowerShellDebugAdapterSkip` to
  `WindowsPowerShellServerStartupSkip`, since it now covers both protocols.

Windows PowerShell unit coverage (`TestPS51`) still runs; this only skips the
WinPS-hosted E2E server tests as a stopgap pending a real fix. See #2323.

Drafted by Copilot (Claude Opus 4.8).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Issue-Enhancement A feature request (enhancement).

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Path Mapping on Attach request

4 participants