Resolves #505 - Fix handling for Windows long paths (#506)

* Resolves #505 - Fix handling for Windows long paths

PR#369 - #369
Caused the majority of tests on Windows to fail, as normalization of
RelativePath was removed. This change  also removed the call to
'PathAllocCanonicalize' for AbsolutePath which had the long file
flag 'PATHCCH_ALLOW_LONG_PATHS'.

Reintroducing canonicalization of AbsolutePath path representation
to handle long paths.

* Update tests dealing with RelativePath to match implementation.
* Canonicalize the path representation for AbsolutePath which also allows
  for long path '\\?\' prefix addition when path > 260 in length.
* Strip trailing backslash on string representation of AbsolutePath to match
  definition. Only strips for non root paths.
* Add helper functions:
  - removeTrailingBackslash
  - stripPrefix
  - canonicalPathRepresentation
* Add Windows API Error helpers
* Add long path tests into each test case
* Fix up .suffix. '.' has no suffix
* Update copyright dates

* Make PathCchStripPrefix and PathCchRemoveBackslash use temporary buffer.

- Move PathCchStripPrefix and PathCchRemoveBackslash to use a
mutable temporary buffer.
    - Could not use buffer.withMemoryRebound and getCstring() as
      on Windows this seem to produce corrupt data.
- Add more tests for unParsed '\\?\' and device '\\.\' paths
- Remove the PATHCCH_CANONICALIZE_SLASHES flag as it is not
  needed.
- Add Win32Error.swift to CMakeLists

Author: kcieplak

Sources/TSCBasic/CMakeLists.txt

@@ -49,7 +49,8 @@ add_library(TSCBasic
   TerminalController.swift
   Thread.swift
   Tuple.swift
-  misc.swift)
+  misc.swift
+  Win32Error.swift)
 
 target_compile_options(TSCBasic PUBLIC
   # Ignore secure function warnings on Windows.

Sources/TSCBasic/Path.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2014 - 2018 Apple Inc. and the Swift project authors
+ Copyright (c) 2014 - 2025 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See http://swift.org/LICENSE.txt for license information
@@ -32,6 +32,7 @@ import var Foundation.NSLocalizedDescriptionKey
 /// - Removing `.` path components
 /// - Removing any trailing path separator
 /// - Removing any redundant path separators
+/// - Converting the disk designator to uppercase (Windows) i.e. c:\ to C:\
 ///
 /// This string manipulation may change the meaning of a path if any of the
 /// path components are symbolic links on disk.  However, the file system is
@@ -506,21 +507,30 @@ private struct WindowsPath: Path, Sendable {
     var components: [String] {
         let normalized: UnsafePointer<Int8> = string.fileSystemRepresentation
         defer { normalized.deallocate() }
-
-        return String(cString: normalized).components(separatedBy: "\\").filter { !$0.isEmpty }
+        // Remove prefix from the components, allowing for comparison across normalized paths.
+        var prefixStrippedPath = PathCchStripPrefix(String(cString: normalized))
+        // The '\\.\'' prefix is not removed by PathCchStripPrefix do this manually.
+        if prefixStrippedPath.starts(with: #"\\.\"#) {
+            prefixStrippedPath = String(prefixStrippedPath.dropFirst(4))
+        }
+        return prefixStrippedPath.components(separatedBy: #"\"#).filter { !$0.isEmpty }
     }
 
     var parentDirectory: Self {
         return self == .root ? self : Self(string: dirname)
     }
 
     init(string: String) {
-        if string.first?.isASCII ?? false, string.first?.isLetter ?? false, string.first?.isLowercase ?? false,
-           string.count > 1, string[string.index(string.startIndex, offsetBy: 1)] == ":"
+        let noPrefixPath = PathCchStripPrefix(string)
+        let prefix = string.replacingOccurrences(of: noPrefixPath, with: "") // Just the prefix or empty
+
+        // Perform drive designator normalization i.e. 'c:\' to 'C:\' on string.
+        if noPrefixPath.first?.isASCII ?? false, noPrefixPath.first?.isLetter ?? false, noPrefixPath.first?.isLowercase ?? false,
+           noPrefixPath.count > 1, noPrefixPath[noPrefixPath.index(noPrefixPath.startIndex, offsetBy: 1)] == ":"
         {
-            self.string = "\(string.first!.uppercased())\(string.dropFirst(1))"
+            self.string = "\(prefix)\(noPrefixPath.first!.uppercased())\(noPrefixPath.dropFirst(1))"
         } else {
-            self.string = string
+            self.string = prefix + noPrefixPath
         }
     }
 
@@ -536,7 +546,13 @@ private struct WindowsPath: Path, Sendable {
         if !Self.isAbsolutePath(realpath) {
             throw PathValidationError.invalidAbsolutePath(path)
         }
-        self.init(string: realpath)
+        do {
+            let canonicalizedPath = try canonicalPathRepresentation(realpath)
+            let normalizedPath = PathCchRemoveBackslash(canonicalizedPath) // AbsolutePath states paths have no trailing separator.
+            self.init(string: normalizedPath)
+        } catch {
+            throw PathValidationError.invalidAbsolutePath("\(path): \(error)")
+        }
     }
 
     init(validatingRelativePath path: String) throws {
@@ -554,12 +570,20 @@ private struct WindowsPath: Path, Sendable {
 
     func suffix(withDot: Bool) -> String? {
         return self.string.withCString(encodedAs: UTF16.self) {
-          if let pointer = PathFindExtensionW($0) {
-            let substring = String(decodingCString: pointer, as: UTF16.self)
-            guard substring.length > 0 else { return nil }
-            return withDot ? substring : String(substring.dropFirst(1))
-          }
-          return nil
+            if let dotPointer = PathFindExtensionW($0) {
+                // If the dotPointer is the same as the full path, there are no components before
+                // the suffix and therefore there is no suffix.
+                if dotPointer == $0 {
+                    return nil
+                }
+                let substring = String(decodingCString: dotPointer, as: UTF16.self)
+                // Substring must have a dot and one more character to be considered a suffix
+                guard substring.length > 1 else {
+                    return nil
+                }
+                return withDot ? substring : String(substring.dropFirst(1))
+            }
+            return nil
         }
     }
 
@@ -585,6 +609,111 @@ private struct WindowsPath: Path, Sendable {
         return Self(string: String(decodingCString: result!, as: UTF16.self))
     }
 }
+
+fileprivate func HRESULT_CODE(_ hr: HRESULT) -> DWORD {
+    DWORD(hr) & 0xFFFF
+}
+
+@inline(__always)
+fileprivate func HRESULT_FACILITY(_ hr: HRESULT) -> DWORD {
+    DWORD(hr << 16) & 0x1FFF
+}
+
+@inline(__always)
+fileprivate func SUCCEEDED(_ hr: HRESULT) -> Bool {
+    hr >= 0
+}
+
+// This is a non-standard extension to the Windows SDK that allows us to convert
+// an HRESULT to a Win32 error code.
+@inline(__always)
+fileprivate func WIN32_FROM_HRESULT(_ hr: HRESULT) -> DWORD {
+    if SUCCEEDED(hr) { return DWORD(ERROR_SUCCESS) }
+    if HRESULT_FACILITY(hr) == FACILITY_WIN32 {
+        return HRESULT_CODE(hr)
+    }
+    return DWORD(hr)
+}
+
+/// Create a canonicalized path representation for Windows.
+/// Returns a potentially `\\?\`-prefixed version of the path,
+/// to ensure long paths greater than MAX_PATH (260) characters are handled correctly.
+///
+/// - seealso: https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation
+fileprivate func canonicalPathRepresentation(_ path: String) throws -> String {
+    return try path.withCString(encodedAs: UTF16.self) { pwszPlatformPath in
+        // 1. Normalize the path first.
+        // Contrary to the documentation, this works on long paths independently
+        // of the registry or process setting to enable long paths (but it will also
+        // not add the \\?\ prefix required by other functions under these conditions).
+        let dwLength: DWORD = GetFullPathNameW(pwszPlatformPath, 0, nil, nil)
+
+        return try withUnsafeTemporaryAllocation(of: WCHAR.self, capacity: Int(dwLength)) { pwszFullPath in
+            guard (1 ..< dwLength).contains(GetFullPathNameW(pwszPlatformPath, DWORD(pwszFullPath.count), pwszFullPath.baseAddress, nil)) else {
+                throw Win32Error(GetLastError())
+            }
+            // 1.5 Leave \\.\ prefixed paths alone since device paths are already an exact representation and PathCchCanonicalizeEx will mangle these.
+            if pwszFullPath.count >= 4 {
+                if let base = pwszFullPath.baseAddress,
+                   base[0] == UInt8(ascii: "\\"),
+                   base[1] == UInt8(ascii: "\\"),
+                   base[2] == UInt8(ascii: "."),
+                   base[3] == UInt8(ascii: "\\")
+                {
+                    return String(decodingCString: base, as: UTF16.self)
+                }
+            }
+            // 2. Canonicalize the path.
+            // This will add the \\?\ prefix if needed based on the path's length.
+            var pwszCanonicalPath: LPWSTR?
+            let flags: ULONG = numericCast(PATHCCH_ALLOW_LONG_PATHS.rawValue)
+            let result = PathAllocCanonicalize(pwszFullPath.baseAddress, flags, &pwszCanonicalPath)
+            if let pwszCanonicalPath {
+                defer { LocalFree(pwszCanonicalPath) }
+                if result == S_OK {
+                    // 3. Perform the operation on the normalized path.
+                    return String(decodingCString: pwszCanonicalPath, as: UTF16.self)
+                }
+            }
+            throw Win32Error(WIN32_FROM_HRESULT(result))
+        }
+    }
+}
+
+/// Removes the "\\?\" prefix, if present, from a file path. When this function returns successfully,
+/// the same path string will have the prefix removed,if the prefix was present.
+/// If no prefix was present,the string will be unchanged.
+fileprivate func PathCchStripPrefix(_ path: String) -> String {
+    return path.withCString(encodedAs: UTF16.self) { cStringPtr in
+        withUnsafeTemporaryAllocation(of: WCHAR.self, capacity: path.utf16.count + 1) { buffer in
+            buffer.initialize(from: UnsafeBufferPointer(start: cStringPtr, count: path.utf16.count + 1))
+            let result = PathCchStripPrefix(buffer.baseAddress!, buffer.count)
+            if result == S_OK {
+                return String(decodingCString: buffer.baseAddress!, as: UTF16.self)
+            }
+            return path
+        }
+    }
+}
+
+/// Remove a trailing backslash from a path if the following conditions
+/// are true:
+///   * Path is not a root path
+///   * Pash has a trailing backslash
+/// If conditions are not met then the string is returned unchanged.
+fileprivate func PathCchRemoveBackslash(_ path: String) -> String {
+    return path.withCString(encodedAs: UTF16.self) { cStringPtr in
+        return withUnsafeTemporaryAllocation(of: WCHAR.self, capacity: path.utf16.count + 1) { buffer in
+            buffer.initialize(from: UnsafeBufferPointer(start: cStringPtr, count: path.utf16.count + 1))
+            let result = PathCchRemoveBackslash(buffer.baseAddress!, path.utf16.count + 1)
+            if result == S_OK {
+                return String(decodingCString: buffer.baseAddress!, as: UTF16.self)
+            }
+            return path
+        }
+        return path
+    }
+}
 #else
 private struct UNIXPath: Path, Sendable {
     let string: String
@@ -966,7 +1095,8 @@ extension AbsolutePath {
             }
         }
 
-        assert(AbsolutePath(base, result) == self)
+        assert(AbsolutePath(base, result) == self, "base:\(base) result:\(result) self: \(self)")
+
         return result
     }
 

Sources/TSCBasic/Win32Error.swift

@@ -0,0 +1,37 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2014 - 2025 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See http://swift.org/LICENSE.txt for license information
+ See http://swift.org/CONTRIBUTORS.txt for Swift project authors
+ */
+
+#if os(Windows)
+public import WinSDK
+import Foundation
+
+public struct Win32Error: Error, CustomStringConvertible {
+    public let error: DWORD
+
+    public init(_ error: DWORD) {
+        self.error = error
+    }
+
+    public var description: String {
+        let flags: DWORD = DWORD(FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS)
+        var buffer: UnsafeMutablePointer<WCHAR>?
+        let length: DWORD = withUnsafeMutablePointer(to: &buffer) {
+            $0.withMemoryRebound(to: WCHAR.self, capacity: 2) {
+                FormatMessageW(flags, nil, error, 0, $0, 0, nil)
+            }
+        }
+        guard let buffer, length > 0 else {
+            return "Win32 Error Code \(error)"
+        }
+        defer { LocalFree(buffer) }
+        return String(decodingCString: buffer, as: UTF16.self).trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+}
+#endif