Add SerializedJSON type as string literal escaping helper (#6730)

Currently we have to call `_nativePathString` manually in a lot of places where `AbsolutePath` is interpolated into strings. We also need to take into account whether `_nativePathString` should be called with `escaped: true` or `escaped: false` arguments, which is prone to errors. The serialization format should carry the knowledge of its correct escaping algorithm, not the path representation itself.

We can make this much cleaner if string interpolations call `_nativePathString` automatically where needed, and serialization formats add proper escaping on top of that.

Let's mplements this for JSON, specifically where it is used in Swift SDKs.

### Modifications:

Added `SerializedJSON` type as string literal escaping helper.

Also added a custom `AbsolutePath` interpolation to the new type, which removes the need to call `_nativePathString` when paths are interpolated in JSON strings.

### Result:

We don't have to call `_nativePathString` manually in as many places. In future PRs `_nativePathString` should be declared `private` or at least `internal` so that it's hidden as an implementation detail of appropriate string interpolations.

Author: MaxDesiatov

Sources/Basics/ByteString+Extensions.swift

@@ -23,4 +23,8 @@ extension ByteString {
     public var sha256Checksum: String {
         SHA256().hash(self).hexadecimalRepresentation
     }
+
+    public init(json: SerializedJSON) {
+        self.init(json.underlying.utf8)
+    }
 }

Sources/Basics/CMakeLists.txt

@@ -27,6 +27,7 @@ add_library(Basics
   Errors.swift
   FileSystem/AbsolutePath.swift
   FileSystem/FileSystem+Extensions.swift
+  FileSystem/NativePathExtensions.swift
   FileSystem/RelativePath.swift
   FileSystem/TemporaryFile.swift
   FileSystem/TSCAdapters.swift
@@ -45,12 +46,12 @@ add_library(Basics
   ImportScanning.swift
   JSON+Extensions.swift
   JSONDecoder+Extensions.swift
-  NativePathExtensions.swift
   Netrc.swift
   Observability.swift
   SQLite.swift
   Sandbox.swift
   SendableTimeInterval.swift
+  Serialization/SerializedJSON.swift
   String+Extensions.swift
   SwiftVersion.swift
   SQLiteBackedCache.swift

Sources/Basics/NativePathExtensions.swift renamed to Sources/Basics/FileSystem/NativePathExtensions.swift

@@ -24,3 +24,15 @@ extension AbsolutePath {
         }
     }
 }
+
+extension DefaultStringInterpolation {
+    public mutating func appendInterpolation(_ value: AbsolutePath) {
+        self.appendInterpolation(value._nativePathString(escaped: false))
+    }
+}
+
+extension SerializedJSON.StringInterpolation {
+    public mutating func appendInterpolation(_ value: AbsolutePath) {
+        self.appendInterpolation(value._nativePathString(escaped: false))
+    }
+}

Sources/Basics/Serialization/SerializedJSON.swift

@@ -0,0 +1,49 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift open source project
+//
+// Copyright (c) 2023 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 the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+/// Wrapper type representing serialized escaped JSON strings providing helpers
+/// for escaped string interpolations for common types such as `AbsolutePath`.
+public struct SerializedJSON {
+    let underlying: String
+}
+
+extension SerializedJSON: ExpressibleByStringLiteral {
+    public init(stringLiteral: String) {
+        self.underlying = stringLiteral
+    }
+}
+
+extension SerializedJSON: ExpressibleByStringInterpolation {
+    public init(stringInterpolation: StringInterpolation) {
+        self.init(underlying: stringInterpolation.value)
+    }
+
+    public struct StringInterpolation: StringInterpolationProtocol {
+        fileprivate var value: String = ""
+
+        private func escape(_ string: String) -> String {
+            string.replacingOccurrences(of: #"\"#, with: #"\\"#)
+        }
+
+        public init(literalCapacity: Int, interpolationCount: Int) {
+            self.value.reserveCapacity(literalCapacity)
+        }
+
+        public mutating func appendLiteral(_ literal: String) {
+            self.value.append(self.escape(literal))
+        }
+
+        public mutating func appendInterpolation(_ value: some CustomStringConvertible) {
+            self.value.append(self.escape(value.description))
+        }
+    }
+}

Tests/BasicsTests/Serialization/SerializedJSONTests.swift

@@ -0,0 +1,40 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift open source project
+//
+// Copyright (c) 2023 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 the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+@testable import Basics
+import XCTest
+
+final class SerializedJSONTests: XCTestCase {
+    func testPathInterpolation() throws {
+        var path = try AbsolutePath(validating: #"/test\backslashes"#)
+        var json: SerializedJSON = "\(path)"
+
+        XCTAssertEqual(json.underlying, #"/test\\backslashes"#)
+
+        #if os(Windows)
+        path = try AbsolutePath(validating: #"\\?\C:\Users"#)
+        json = "\(path)"
+
+        XCTAssertEqual(json.underlying, #"\\\\?\\C:\\Users"#)
+
+        path = try AbsolutePath(validating: #"\\.\UNC\server\share\n\"#)
+        json = "\(path)"
+
+        XCTAssertEqual(json.underlying, #"\\\\.\\UNC\\server\\share\\"#)
+
+        path = try AbsolutePath(validating: #"\??\Volumes{b79de17a-a1ed-4c58-a353-731b7c4885a6}\\"#)
+        json = "\(path)"
+
+        XCTAssertEqual(json.underlying, #"\\??\\Volumes{b79de17a-a1ed-4c58-a353-731b7c4885a6}\\"#)
+        #endif
+    }
+}

Tests/PackageModelTests/SwiftSDKBundleTests.swift

@@ -21,7 +21,7 @@ import class TSCBasic.InMemoryFileSystem
 
 private let testArtifactID = "test-artifact"
 
-private func generateInfoJSON(artifacts: [MockArtifact]) -> String {
+private func generateInfoJSON(artifacts: [MockArtifact]) -> SerializedJSON {
     """
     {
         "artifacts" : {
@@ -68,7 +68,7 @@ private func generateTestFileSystem(bundleArtifacts: [MockArtifact]) throws -> (
             (
                 "\($0.path)/info.json",
                 ByteString(
-                    encodingAsUTF8: generateInfoJSON(artifacts: $0.artifacts)
+                    json: generateInfoJSON(artifacts: $0.artifacts)
                 )
             )
         })