fix: windows drive letters remap to unc paths

[maxnbk]

Closes #2045 and #1438 .
Partial but not complete fix for #1909 (Intentional, I feel that the work that was occurring in the gitbash PR would ultimately resolve this behavior?) .

Explanations:

os.path.realpath on Python 3.8+ Windows silently expands mapped drive letters to their underlying UNC paths. Because canonical_path calls realpath, FileSystemPackageRepository was storing a UNC self.location even when the caller supplied a drive-letter path. This caused make_resource_handle, which does a raw string comparison, to raise ResourceError on every drive-letter handle against a UNC-stored repository.

The fix:

On Windows, canonical_path now uses os.path.abspath instead of os.path.realpath. This preserves path style (drive-letter stays drive-letter, UNC stays UNC) and restores the pre-3.8 normalization behavior without a network-resolution side-effect. A make_resource_handle override is also added to the filesystem plugin to handle residual case or separator mismatches via canonical_path.

Extension of work:

A resolve_links_on_windows config flag (default False) has been added for sites that need some form of symlink/junction resolution on Windows. When enabled, a purpose-built _windows_realpath walks components of the path using os.readlink, resolving real symlinks without actually touching the drive root, in order to avoid the UNC-expansion side-effect entirely. Long-path support (\\?\ prefix handling) is included, with the relevant test skipped on hosts that do not have LongPathsEnabled=1 in the registry. Note: I'm aware that we need to move off of the winreg module, but since we have it for now, might as well use it.

Testing:

This was tested against an actual Drive-letter-map-with-matching-UNC-network-share .

====EDIT====

This PR has been extended with a broader real_path migration.

real_path() helper - A new utility function in filesystem.py that replaces os.path.realpath at all call sites where path-style stability is required.
On Windows, it is delegated to os.path.abspath to preserve the drive-letter style.
On all other platforms, it is delegated to os.path.realpath to preserve symlink resolution.
Importantly, no config-flag is required - the correct behavior is derived from the OS, not user preference. canonical_path from the original PR slice now calls real_path internally.

Call-site migration - All non-test os.path.realpath code that touched stored, serialized, or compared paths have been updated:

• filesystem.py - canonical_path, is_subdirectory
• resolved_context.py - _adjust_variant_for_bundling
• serialise.py - open_file_for_write, load_from_file
• suite.py - Suite.save, Suite.load
• system.py - rez_bin_path
• rezplugins/build_system/cmake.py - also corrects a pre-existing dead-code bug (os.path.abspath used as a truthiness check where os.path.isabs was intended)
• utils/py_dist.py - egg-to-rez file path comparisons and copy destinations

Relationship to prior work - Several earlier attempts addressed this problem class but were either incomplete/partial, lacked tests, or relied on opt-in config flags:

• Fix repo location false mismatch #957 - first fix for the make_resource_handle location mismatch; was reverted. This PR restores the intent of that fix.
• Add new use_canonical_path option in rezconfig.py #1543 - introduced use_canonical_path config flag (default True); only patched FileSystemPackageRepository.init and required users to opt out. Superseded by this work.
• fix: realpath on windows changed behavior in python 3.8 to expand mapped drive letters to their UNC path names #1856 - introduced a real_path helper gated on a windows_unc_path config flag; covered three call sites (canonical_path, _adjust_variant_for_bundling, rez_bin_path). The approach here is the same in spirit but unconditional and covers all remaining call sites. Superseded by this work.

====END EDIT====

Disclosure:

This PR was AI-assisted with Claude Code, Sonnet 4.6, primarily for diagnostics, logic-tracing, documentation and edge-case verification.

[codecov]

Codecov Report

❌ Patch coverage is 79.41176% with 14 lines in your changes missing coverage. Please review.
✅ Project coverage is 61.02%. Comparing base (6f4bc68) to head (92124cf).

Files with missing lines	Patch %	Lines
src/rez/utils/filesystem.py	84.44%	3 Missing and 4 partials ⚠️
src/rez/utils/py_dist.py	0.00%	3 Missing ⚠️
src/rezplugins/build_system/cmake.py	33.33%	1 Missing and 1 partial ⚠️
src/rez/rezconfig.py	0.00%	1 Missing ⚠️
src/rezplugins/package_repository/filesystem.py	85.71%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2104      +/-   ##
==========================================
+ Coverage   60.95%   61.02%   +0.06%     
==========================================
  Files         164      164              
  Lines       20629    20683      +54     
  Branches     3591     3606      +15     
==========================================
+ Hits        12575    12621      +46     
- Misses       7181     7182       +1     
- Partials      873      880       +7     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[JeanChristopheMorinPerso]

@maxnbk What's the relationship to #1856?

During the TSC, @instinct-vfx said that the expected default behavior is that the style should stay consistent based on how the repo was configured?

[cfxegbert]

Can you please look at #1856. There are a few other places that realpath needs to be replaced.

[maxnbk]

I'll take a look and see what else needs resolving. I may have to add some more tests to find all the edge-cases. Goal is to incorporate all solutions from all mismatched PRs, as I think there were approximately 3 all trying to solve the same problem with partial/incomplete solutions, and nobody got all corners.

Evidently that extends to me, so I'll re-evaluate and see what I need to do to extend.
Might be this weekend though. :)

[cfxegbert]

@JeanChristopheMorinPerso Looks like this didn't get merged into the 3.4.0. What can we do to get this out there?

[JeanChristopheMorinPerso]

Hey @cfxegbert, this was intentional. We had a few more questions to answer and decided to push this to a follow up release. We are planning to do a 3.4.1 release soon-ish to get this PR out.

When I reviewed the PR, I noticed that os.path.islink doesn't do what we thought it would on windows. At least I think.