Abstract away our dependency on Foundation for JSON encoding/decoding (#355)

This PR moves all our uses of `JSONEncoder` and `JSONDecoder` to a new
namespace enum, `JSON`, and provides interfaces that don't use
Foundation.

This change does _not_ remove our dependency on Foundation's JSON
functionality, but it should allow us to replace that functionality in
the future with JSON encoding/decoding logic from another library (or
home-grown, if necessary.)

### Checklist:

- [x] Code and documentation should follow the style of the [Style
Guide](https://github.com/apple/swift-testing/blob/main/Documentation/StyleGuide.md).
- [x] If public symbols are renamed or modified, DocC references should
be updated.

Author: grynspan

Sources/Testing/ExitTests/ExitTest.swift

@@ -9,9 +9,6 @@
 //
 
 private import TestingInternals
-#if canImport(Foundation)
-private import Foundation
-#endif
 
 #if !SWT_NO_EXIT_TESTS
 /// A type describing an exit test.
@@ -223,10 +220,12 @@ extension ExitTest {
   /// `__swiftPMEntryPoint()` function. The effect of using it under other
   /// configurations is undefined.
   static func findInEnvironmentForSwiftPM() -> Self? {
-    let sourceLocationString = Environment.variable(named: "SWT_EXPERIMENTAL_EXIT_TEST_SOURCE_LOCATION")
-    if let sourceLocationData = sourceLocationString?.data(using: .utf8),
-       let sourceLocation = try? JSONDecoder().decode(SourceLocation.self, from: sourceLocationData) {
-      return find(at: sourceLocation)
+    if var sourceLocationString = Environment.variable(named: "SWT_EXPERIMENTAL_EXIT_TEST_SOURCE_LOCATION") {
+      return try? sourceLocationString.withUTF8 { sourceLocationBuffer in
+        let sourceLocationBuffer = UnsafeRawBufferPointer(sourceLocationBuffer)
+        let sourceLocation = try JSON.decode(SourceLocation.self, from: sourceLocationBuffer)
+        return find(at: sourceLocation)
+      }
     }
     return nil
   }
@@ -286,10 +285,12 @@ extension ExitTest {
 #endif
       // Insert a specific variable that tells the child process which exit test
       // to run.
-      childEnvironment["SWT_EXPERIMENTAL_EXIT_TEST_SOURCE_LOCATION"] = try String(data: JSONEncoder().encode(exitTest.sourceLocation), encoding: .utf8)!
+      try JSON.withEncoding(of: exitTest.sourceLocation) { json in
+        childEnvironment["SWT_EXPERIMENTAL_EXIT_TEST_SOURCE_LOCATION"] = String(decoding: json, as: UTF8.self)
+      }
 
       return try await _spawnAndWait(
-        forExecutableAtPath: childProcessExecutablePath, 
+        forExecutableAtPath: childProcessExecutablePath,
         arguments: childArguments,
         environment: childEnvironment
       )

Sources/Testing/Parameterization/CustomTestArgumentEncodable.swift

@@ -8,10 +8,6 @@
 // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 //
 
-#if canImport(Foundation)
-private import Foundation
-#endif
-
 /// A protocol for customizing how arguments passed to parameterized tests are
 /// encoded, which is used to match against when running specific arguments.
 ///
@@ -107,15 +103,7 @@ extension Test.Case.Argument.ID {
   ///
   /// - Throws: Any error encountered during encoding.
   private static func _encode(_ value: some Encodable, parameter: Test.Parameter) throws -> [UInt8] {
-    let encoder = JSONEncoder()
-
-    // Keys must be sorted to ensure deterministic matching of encoded data.
-    encoder.outputFormatting.insert(.sortedKeys)
-
-    // Set user info keys which clients may wish to use during encoding.
-    encoder.userInfo[._testParameterUserInfoKey] = parameter
-
-    return .init(try encoder.encode(value))
+    try JSON.withEncoding(of: value, userInfo: [._testParameterUserInfoKey: parameter], Array.init)
   }
 #endif
 }

Sources/Testing/Running/EntryPoint.swift

@@ -9,9 +9,6 @@
 //
 
 private import TestingInternals
-#if canImport(Foundation)
-private import Foundation
-#endif
 
 /// The entry point to the testing library used by Swift Package Manager.
 ///
@@ -321,17 +318,17 @@ private func _eventHandlerForStreamingEvents(toFileAtPath path: String) throws -
       event: Event.Snapshot(snapshotting: event),
       eventContext: Event.Context.Snapshot(snapshotting: context)
     )
-    if var snapshotJSON = try? JSONEncoder().encode(snapshot) {
+    try? JSON.withEncoding(of: snapshot) { snapshotJSON in
       func isASCIINewline(_ byte: UInt8) -> Bool {
         byte == 10 || byte == 13
       }
 
 #if DEBUG
-      // We don't actually expect JSONEncoder() to produce output containing
+      // We don't actually expect the JSON encoder to produce output containing
       // newline characters, so in debug builds we'll log a diagnostic message.
       if snapshotJSON.contains(where: isASCIINewline) {
         let message = Event.ConsoleOutputRecorder.warning(
-          "JSONEncoder() produced one or more newline characters while encoding an event snapshot with kind '\(event.kind)'. Please file a bug report at https://github.com/apple/swift-testing/issues/new",
+          "JSON encoder produced one or more newline characters while encoding an event snapshot with kind '\(event.kind)'. Please file a bug report at https://github.com/apple/swift-testing/issues/new",
           options: .for(.stderr)
         )
 #if SWT_TARGET_OS_APPLE
@@ -343,6 +340,7 @@ private func _eventHandlerForStreamingEvents(toFileAtPath path: String) throws -
 #endif
 
       // Remove newline characters to conform to JSON lines specification.
+      var snapshotJSON = Array(snapshotJSON)
       snapshotJSON.removeAll(where: isASCIINewline)
       if !snapshotJSON.isEmpty {
         try? file.withLock {

Sources/Testing/Support/JSON.swift

@@ -0,0 +1,66 @@
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2024 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+//
+
+#if canImport(Foundation)
+private import Foundation
+#endif
+
+enum JSON {
+  /// Encode a value as JSON.
+  ///
+  /// - Parameters:
+  ///   - value: The value to encode.
+  ///   - userInfo: Any user info to pass into the encoder during encoding.
+  ///   - body: A function to call.
+  ///
+  /// - Returns: Whatever is returned by `body`.
+  ///
+  /// - Throws: Whatever is thrown by `body` or by the encoding process.
+  static func withEncoding<R>(of value: some Encodable, userInfo: [CodingUserInfoKey: Any] = [:], _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
+#if canImport(Foundation)
+    let encoder = JSONEncoder()
+
+    // Keys must be sorted to ensure deterministic matching of encoded data.
+    encoder.outputFormatting.insert(.sortedKeys)
+
+    // Set user info keys that clients want to use during encoding.
+    encoder.userInfo.merge(userInfo, uniquingKeysWith: { _, rhs in rhs})
+
+    let data = try encoder.encode(value)
+    return try data.withUnsafeBytes(body)
+#else
+    throw SystemError(description: "JSON encoding requires Foundation which is not available in this environment.")
+#endif
+  }
+
+  /// Decode a value from JSON data.
+  ///
+  /// - Parameters:
+  ///   - type: The type of value to decode.
+  ///   - jsonRepresentation: The JSON encoding of the value to decode.
+  ///
+  /// - Returns: An instance of `T` decoded from `jsonRepresentation`.
+  ///
+  /// - Throws: Whatever is thrown by the decoding process.
+  static func decode<T>(_ type: T.Type, from jsonRepresentation: UnsafeRawBufferPointer) throws -> T where T: Decodable {
+#if canImport(Foundation)
+    try withExtendedLifetime(jsonRepresentation) {
+      let data = Data(
+        bytesNoCopy: .init(mutating: jsonRepresentation.baseAddress!),
+        count: jsonRepresentation.count,
+        deallocator: .none
+      )
+      return try JSONDecoder().decode(type, from: data)
+    }
+#else
+    throw SystemError(description: "JSON decoding requires Foundation which is not available in this environment.")
+#endif
+  }
+}

Sources/Testing/Traits/Tags/Tag.Color+Loading.swift

@@ -99,7 +99,9 @@ func loadTagColors(fromFileInDirectoryAtPath swiftTestingDirectoryPath: String =
   // nil is a valid decoded color value (representing "no color") that we can
   // use for merging tag color data from multiple sources, but it is not valid
   // as an actual tag color, so we have a step here that filters it.
-  return try JSONDecoder().decode([Tag: Tag.Color?].self, from: tagColorsData)
-    .compactMapValues { $0 }
+  return try tagColorsData.withUnsafeBytes { tagColorsData in
+    try JSON.decode([Tag: Tag.Color?].self, from: tagColorsData)
+      .compactMapValues { $0 }
+  }
 }
 #endif

Sources/TestingInternals/include/Includes.h

@@ -43,6 +43,10 @@
 #include <unistd.h>
 #endif
 
+#if __has_include(<sys/fcntl.h>)
+#include <sys/fcntl.h>
+#endif
+
 #if __has_include(<sys/stat.h>)
 #include <sys/stat.h>
 #endif
@@ -75,6 +79,10 @@
 #include <limits.h>
 #endif
 
+#if __has_include(<spawn.h>)
+#include <spawn.h>
+#endif
+
 #if __has_include(<crt_externs.h>)
 #include <crt_externs.h>
 #endif

Tests/TestingTests/BacktraceTests.swift

@@ -9,9 +9,6 @@
 //
 
 @testable @_spi(ForToolsIntegrationOnly) import Testing
-#if canImport(Foundation)
-import Foundation
-#endif
 
 struct BacktracedError: Error {}
 
@@ -51,8 +48,7 @@ struct BacktraceTests {
   @Test("Encoding/decoding")
   func encodingAndDecoding() throws {
     let original = Backtrace.current()
-    let data = try JSONEncoder().encode(original)
-    let copy = try JSONDecoder().decode(Backtrace.self, from: data)
+    let copy = try JSON.encodeAndDecode(original)
     #expect(original == copy)
   }
 #endif

Tests/TestingTests/ClockTests.swift

@@ -8,9 +8,6 @@
 // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 //
 
-#if canImport(Foundation)
-import Foundation
-#endif
 @testable @_spi(Experimental) @_spi(ForToolsIntegrationOnly) import Testing
 private import TestingInternals
 
@@ -129,9 +126,7 @@ struct ClockTests {
   func codable() async throws {
     let now = Test.Clock.Instant()
     let instant = now.advanced(by: .nanoseconds(100))
-    let decoded = try JSONDecoder().decode(Test.Clock.Instant.self,
-                                           from: JSONEncoder().encode(instant))
-
+    let decoded = try JSON.encodeAndDecode(instant)
     #expect(instant == decoded)
     #expect(instant != now)
   }

Tests/TestingTests/EventTests.swift

@@ -8,9 +8,6 @@
 // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 //
 
-#if canImport(Foundation)
-import Foundation
-#endif
 @testable @_spi(Experimental) @_spi(ForToolsIntegrationOnly) import Testing
 private import TestingInternals
 
@@ -62,8 +59,7 @@ struct EventTests {
     let testCaseID = Test.Case.ID(argumentIDs: nil)
     let event = Event(kind, testID: testID, testCaseID: testCaseID, instant: .now)
     let eventSnapshot = Event.Snapshot(snapshotting: event)
-    let encoded = try JSONEncoder().encode(eventSnapshot)
-    let decoded = try JSONDecoder().decode(Event.Snapshot.self, from: encoded)
+    let decoded = try JSON.encodeAndDecode(eventSnapshot)
 
     #expect(String(describing: decoded) == String(describing: eventSnapshot))
   }
@@ -73,8 +69,7 @@ struct EventTests {
     let eventContext = Event.Context()
     let snapshot = Event.Context.Snapshot(snapshotting: eventContext)
 
-    let encoded = try JSONEncoder().encode(snapshot)
-    let decoded = try JSONDecoder().decode(Event.Context.Snapshot.self, from: encoded)
+    let decoded = try JSON.encodeAndDecode(snapshot)
 
     #expect(String(describing: decoded.test) == String(describing: eventContext.test.map(Test.Snapshot.init(snapshotting:))))
     #expect(String(describing: decoded.testCase) == String(describing: eventContext.testCase.map(Test.Case.Snapshot.init(snapshotting:))))

Tests/TestingTests/IssueTests.swift

@@ -10,7 +10,6 @@
 
 @testable @_spi(Experimental) @_spi(ForToolsIntegrationOnly) import Testing
 private import TestingInternals
-import Foundation
 
 #if canImport(XCTest)
 import XCTest
@@ -1408,8 +1407,7 @@ struct IssueCodingTests {
                       comments: ["Comment"],
                       sourceContext: SourceContext(backtrace: Backtrace.current(), sourceLocation: SourceLocation()))
     let issueSnapshot = Issue.Snapshot(snapshotting: issue)
-    let encoded = try JSONEncoder().encode(issueSnapshot)
-    let decoded = try JSONDecoder().decode(Issue.Snapshot.self, from: encoded)
+    let decoded = try JSON.encodeAndDecode(issueSnapshot)
 
     #expect(String(describing: decoded) == String(describing: issueSnapshot))
   }