Match a path-mapped file name against the solution, not the current directory

[xperiandri]

Go To Definition, Find All References and Rename on a symbol from an assembly built with a path map (DeterministicSourcePaths or <PathMap>) opened generated metadata instead of source. The assembly records file names relative to an unrecorded root, and the editor resolved them against the process's current directory. Relative names are now matched against the solution's document paths; builds without a path map are unaffected.

Editor half of the fix; #20518 and #20470 cover the compiler and project options. Stacked on #20470.

🤖 Generated with Claude Code

[github-actions]

✅ Release notes checked

---

✅ Found changes and release notes in following paths:

Change path	Release notes path	Description
`vsintegration/src`	docs/release-notes/.VisualStudio/18.vNext.md

[T-Gro]

🤖🕵️ Please shorten the description using this guidance. Focus on the problem and why the change is needed, in simplified technical English. Leave the implementation inventory to the Files tab and retain necessary caveats.

[Copilot]

Copilot review overview

🟡 Changes recommended

Unresolved moderate issues remain in path handling and Go To Definition/Find All References lookup paths.

Review effort: Lite
Findings: 3 · 1

Open (4)

• Use path-map resolver for declaration references · New
• Resolve relative declaration paths in Find All References · New
• Use path-map-aware lookups before metadata fallback · New
• Remove duplicate path-map navigation release note · New

What changed in this PR

Updates F# editor navigation to resolve path-mapped source filenames against solution documents.

Changes:

• Adds path-aware filename matching for navigation and symbol resolution.
• Removes path-map options from IDE project options.
• Adds multi-project tests, helpers, and release notes.

File	Reviewed changes
vsintegration/​tests/​FSharp.Editor.Tests/​PathMapNavigationTests.fs	Adds path-map navigation coverage; current test does not exercise relative declaration ranges.
vsintegration/​tests/​FSharp.Editor.Tests/​Helpers/​RoslynHelpers.fs	Adds multi-target helpers; the new helpers currently have no test call sites.
vsintegration/​tests/​FSharp.Editor.Tests/​FSharp.Editor.Tests.fsproj	Includes the new test sources.
vsintegration/​src/​FSharp.Editor/​Navigation/​GoToDefinition.fs	Adds path-aware declaration comparison; earlier rooted-path lookups still bypass the new matcher.
vsintegration/​src/​FSharp.Editor/​LanguageService/​Symbols.fs	Uses solution-aware file resolution; Find All References still uses the older declaration lookup.
vsintegration/​src/​FSharp.Editor/​LanguageService/​FSharpProjectOptionsManager.fs	Filters path-map options from IDE project options.
vsintegration/​src/​FSharp.Editor/​Common/​CodeAnalysisExtensions.fs	Adds relative filename matching; deterministic virtual roots and remaining Find All References lookup paths need correction.
docs/​release-notes/​.VisualStudio/​18.vNext.md	Documents the fix; contains a duplicate path-map entry.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

🔍 Tooling Safety Check — Affects-Design-Time
Affects-Design-Time: Changes IDE integration executed during design-time.

Generated by PR Tooling Safety Check · gpt56 1.7M · ◷

[T-Gro]

🤖 🕵️ Re-reviewed all recent changes as of c9f0917; 1 finding

[T-Gro]

🤖🕵️ [P2] F12 now opens Unrelated.other instead of metadata when an unrelated assembly's document matches the mapped suffix.

// C:\package\Library.fs; build from C:\package:
// fsc --target:library --pathmap:C:\package=. -o:ExternalLibrary.dll Library.fs
module ExternalLibrary
let value = 42

// Unrelated\Library.fs in the solution; ExternalLibrary's source is absent.
module Unrelated
let other = 99

// Consumer\App.fs references ExternalLibrary.dll.
module Consumer
let result = ExternalLibrary.value // F12 jumps to Unrelated.other

[xperiandri]

Fixed in e0fa3ea: a mapped name is only a candidate now. It reaches a document only in the projects that compile the symbol's assembly, and only if they hold exactly one file ending that way; otherwise F12 keeps the external result. Tests: goto definition stays external when only an unrelated file ends as the mapped name does, which runs your repro against a DLL built with --pathmap, and a mapped name reaches the one file of the declaring assembly that ends with it.

[abonie]

#20462 adds origin/current-solution fallback, while #20519 adds mapped-name matching within a supplied solution; resolving their overlapping callers by choosing either implementation loses the other behavior.

Could we consolidate resolution so it preserves origin-buffer precedence, falls back to the current solution, and requires evidence that a candidate belongs to the declaring assembly and intended signature/implementation location rather than treating a filename suffix as source identity?

That contract needs to hold through navigation, declaration reporting, and Rename—including compatible snapshot ownership for replacement edits—with metadata fallback retained when source resolution fails; a mapped DLL with .fsi/.fs, an unrelated same-suffix file, and a stale origin snapshot would provide useful combined coverage.

[abonie]

A relative filename such as .\Scratch\..\Lib\Library.fs no longer resolves to the workspace’s Lib\Library.fs: suffix matching retains the literal Scratch\.. segments, whereas the previous full-path normalization resolved this case when the process directory was the repository root.

Could we lexically normalize . and resolvable .. segments before constructing the matching suffix, without introducing dependence on the process directory again?

Unresolved leading .. segments need explicit handling rather than silent removal, with regression coverage for equivalent normalized paths and names that cannot be resolved without a known root.

[abonie]

With a binary reference to a path-mapped ExternalLibrary.dll, no library source loaded, and an unrelated Library.fs in the solution, F12 opens the unrelated file and Find All References reports its declaration where the previous code treated the symbol as external.

Could we treat suffix matches as candidates and validate them against the declaring project/assembly before accepting them for either navigation or declaration reporting, rather than protecting only reference-search scope?

When source identity cannot be established, retain the external/metadata fallback instead of accepting even a sole suffix match; the absent-source case and ambiguous same-suffix candidates should be regression tests.

[abonie]

For a mapped DLL built from Library.fsi and Library.fs, F12 finds the implementation document but checks DeclarationLocation, which points to the signature; the subsequent imported-symbol lookup finds no uses in the independently checked implementation, leaving no definition instead of the previous external result.

Could resolution use the implementation or signature location selected for the request when it matches the validated target document, rather than relying exclusively on DeclarationLocation?

Retain the external fallback when source resolution fails, and cover a mapped binary reference through final navigation while preserving signature-origin preference and declaration-toggle behavior.

[T-Gro]

🤖 🕵️ Re-reviewed all recent changes as of e2ee950; LGTM

[abonie]

Perhaps merge main into this branch now that #20470 has landed the shared helpers and baseline path-map tests. This PR can then reuse them, leaving only its mapped-name resolution changes and additional tests in the diff.

[T-Gro]

🤖 🕵️ Re-reviewed all recent changes as of dd4f107; LGTM

[xperiandri]

@abonie Addressed in e0fa3ea:

• Suffix match with the source absent: a suffix match is only a candidate; it is accepted for navigation and for the declaration Find All References reports only in the projects that compile the declaring assembly, and only if they hold exactly one such file, otherwise the symbol stays external (goto definition stays external when only an unrelated file ends as the mapped name does, find all references reports a mapped declaration only in the source of its own assembly, a mapped name reaches the one file of the declaring assembly that ends with it).
• Normalization: . and resolvable .. segments are resolved in the name itself before the suffix is built, and a name that climbs above where it starts matches nothing (new rows in a relative name denotes the file whose path ends with it).
• .fsi + .fs: F12 from an implementation file takes the symbol's implementation location, and where the mapped source gives no location the result is the external one (goto definition into a mapped assembly with a signature reaches the file of the origin's kind, goto definition falls back to the assembly when the mapped source gives no location).
• main: the branch sits on current main, the shared fixture and the baseline path-map tests come from Ignore --pathmap in the IDE's F# project options #20470, and the diff holds only the mapped-name resolution and its tests.

[T-Gro]

The diff is still way too big - apply the NoBloat instructions and CodeCompaction skill.

Especially the massive code comments would benefit not just with drastic reduction, but ideally with well named functions/arguments/bindings/types making the intention clear.

If a well named piece of code just tells what the comment says - delete the comment.

• This diff adds 76 new code comment lines and 6741 new code comment chars.
• The same path-mapping rationale is repeated across CodeAnalysisExtensions.fs, Symbols.fs, FindUsagesService.fs, and GoToDefinition.fs instead of being expressed once behind a named helper or API.