feat: introduce a config defaulted-False config-flag and link-resolution-behavior intended to produce realpath-like behavior

Signed-off-by: Stephen Mackenzie <maxnbk@users.noreply.github.com>

Author: maxnbk

src/rez/config.py

@@ -415,6 +415,7 @@ def _parse_env_var(self, value):
     "suite_alias_prefix_char":                      Char,
     "cache_packages_path":                          OptionalStr,
     "package_definition_python_path":               OptionalStr,
+    "resolve_links_on_windows":                     Bool,
     "tmpdir":                                       OptionalStr,
     "context_tmpdir":                               OptionalStr,
     "default_shell":                                OptionalStr,

src/rez/rezconfig.py

@@ -125,6 +125,26 @@
 # For further information, see :ref:`package-definition-sharing-code`.
 package_definition_python_path = None
 
+# On Windows, whether to resolve symbolic links and junction points when
+# normalising filesystem paths (primarily inside ``canonical_path``).
+#
+# When ``False`` (default), rez uses ``os.path.abspath``, which normalises
+# separators and ``.``/``..`` components without following symlinks and without
+# expanding mapped drive letters to their UNC equivalents.  This preserves the
+# path style supplied by the caller (drive-letter input, drive-letter output,
+# UNC input, UNC output), effectively defaulting to pre-Python-3.8 behaviour of
+# ``os.path.realpath`` on Windows.
+#
+# When ``True``, rez performs a component-by-component walk using
+# ``os.path.islink`` / ``os.readlink``.  This resolves actual symlinks and
+# junction points without the drive-letter-to-UNC side-effect that
+# ``os.path.realpath`` introduced in Python 3.8.  Useful when package
+# repositories are accessed through directory symlinks or junctions.
+#
+# This setting is a no-op on non-Windows platforms, which always resolve
+# symlinks via ``os.path.realpath``.
+resolve_links_on_windows = False
+
 
 ###############################################################################
 # Extensions

src/rez/utils/filesystem.py

@@ -490,6 +490,42 @@ def to_posixpath(path: str):
     return posixpath.sep.join(path.split(ntpath.sep))
 
 
+def _windows_realpath(path: str) -> str:
+    """Resolve symlinks and junctions on Windows without expanding mapped drives.
+
+    ``os.path.realpath`` on Python 3.8+ Windows uses ``GetFinalPathNameByHandle``
+    which expands mapped drive letters (e.g. ``N:\\``) to their underlying UNC
+    server paths.  This function resolves only actual filesystem symlinks and
+    junction points, walking the path component-by-component so that the drive
+    root (drive-letter or UNC prefix) is never touched.
+    """
+    path = os.path.normpath(os.path.abspath(path))
+    drive, rest = os.path.splitdrive(path)
+    # Preserve the root separator so UNC paths keep their leading "\\" and
+    # drive-letter paths keep their "\".
+    result = drive + (os.sep if rest.startswith(os.sep) else "")
+    for part in rest.lstrip(os.sep).split(os.sep):
+        if not part:
+            continue
+        candidate = os.path.join(result, part)
+        depth = 0
+        while os.path.islink(candidate) and depth < 40:
+            target = os.readlink(candidate)
+            # os.readlink on Windows may return an extended-length path
+            # (\\?\C:\... or \\?\UNC\server\share\...). Strip the prefix so
+            # subsequent abspath/normpath calls produce ordinary paths.
+            if target.startswith("\\\\?\\UNC\\"):
+                target = "\\\\" + target[8:]
+            elif target.startswith("\\\\?\\"):
+                target = target[4:]
+            if not os.path.isabs(target):
+                target = os.path.join(os.path.dirname(candidate), target)
+            candidate = os.path.normpath(os.path.abspath(target))
+            depth += 1
+        result = candidate
+    return result
+
+
 def canonical_path(path: str, platform=None):
     r""" Resolves symlinks, and formats filepath.
 
@@ -508,12 +544,19 @@ def canonical_path(path: str, platform=None):
         platform = platform_
 
     # On Windows, os.path.realpath from py3.8 onwards silently converts drive
-    # lettered paths to their UNC equivalents (N:\ → \\server\share\). By default,
-    # use abspath instead to preserve the caller's form.
+    # lettered paths to their UNC equivalents (N:\ → \\server\share\).
     # We check sys.platform rather than the platform argument because this is
     # an OS-level behaviour of os.path.realpath, not a user-configurable choice.
     if sys.platform == "win32":
-        path = os.path.normpath(os.path.abspath(path))
+        # Lazy import avoids a circular dependency (config imports filesystem).
+        from rez.config import config  # noqa: PLC0415
+        if config.resolve_links_on_windows:
+            path = _windows_realpath(path)
+        else:
+            # Default: abspath preserves the caller's path form (drive-letter
+            # stays drive-letter, UNC stays UNC) and restores the pre-3.8
+            # behaviour where realpath on Windows was equivalent to abspath.
+            path = os.path.normpath(os.path.abspath(path))
     else:
         path = os.path.normpath(os.path.realpath(path))