Move JSON ABI source files to prepare for v1. (#953)

grynspan · web-flow · commit 7493d6e3600c · 2025-02-12T16:30:34.000-05:00
At this time, we expect most of the "ABIv1" JSON schema will be the same as the current "ABIv0" one, so this PR reshuffles the source files supporting it so they can be more readily reused between the two. Future PRs will start adding actual "ABIv1" functionality—this is just a bookkeeping PR. ### 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.
diff --git a/Documentation/ABI/JSON.md b/Documentation/ABI/JSON.md
@@ -13,7 +13,7 @@ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 This document outlines the JSON schemas used by the testing library for its ABI
 entry point and for the `--event-stream-output-path` command-line argument. For
 more information about the ABI entry point, see the documentation for
-[ABIv0.EntryPoint](https://github.com/search?q=repo%3Aapple%2Fswift-testing%EntryPoint&type=code).
+[ABI.v0.EntryPoint](https://github.com/search?q=repo%3Aapple%2Fswift-testing%EntryPoint&type=code).
 
 ## Modified Backus-Naur form
 
diff --git a/Sources/Testing/ABI/ABI.Record+Streaming.swift b/Sources/Testing/ABI/ABI.Record+Streaming.swift
@@ -9,7 +9,7 @@
 //
 
 #if canImport(Foundation) && (!SWT_NO_FILE_IO || !SWT_NO_ABI_ENTRY_POINT)
-extension ABIv0.Record {
+extension ABI.Record {
   /// Post-process encoded JSON and write it to a file.
   ///
   /// - Parameters:
diff --git a/Sources/Testing/ABI/ABI.Record.swift b/Sources/Testing/ABI/ABI.Record.swift
@@ -8,7 +8,7 @@
 // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 //
 
-extension ABIv0 {
+extension ABI {
   /// A type implementing the JSON encoding of records for the ABI entry point
   /// and event stream output.
   ///
@@ -48,7 +48,7 @@ extension ABIv0 {
 
 // MARK: - Codable
 
-extension ABIv0.Record: Codable {
+extension ABI.Record: Codable {
   private enum CodingKeys: String, CodingKey {
     case version
     case kind
@@ -73,10 +73,10 @@ extension ABIv0.Record: Codable {
     version = try container.decode(Int.self, forKey: .version)
     switch try container.decode(String.self, forKey: .kind) {
     case "test":
-      let test = try container.decode(ABIv0.EncodedTest.self, forKey: .payload)
+      let test = try container.decode(ABI.EncodedTest.self, forKey: .payload)
       kind = .test(test)
     case "event":
-      let event = try container.decode(ABIv0.EncodedEvent.self, forKey: .payload)
+      let event = try container.decode(ABI.EncodedEvent.self, forKey: .payload)
       kind = .event(event)
     case let kind:
       throw DecodingError.dataCorrupted(.init(codingPath: decoder.codingPath, debugDescription: "Unrecognized record kind '\(kind)'"))
diff --git a/Sources/Testing/ABI/ABI.swift b/Sources/Testing/ABI/ABI.swift
@@ -0,0 +1,30 @@
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2024–2025 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
+//
+
+/// A namespace for ABI symbols.
+@_spi(ForToolsIntegrationOnly)
+public enum ABI: Sendable {}
+
+// MARK: -
+
+@_spi(ForToolsIntegrationOnly)
+extension ABI {
+  /// A namespace for ABI version 0 symbols.
+  public enum v0: Sendable {}
+
+  /// A namespace for ABI version 1 symbols.
+  @_spi(Experimental)
+  public enum v1: Sendable {}
+}
+
+/// A namespace for ABI version 0 symbols.
+@_spi(ForToolsIntegrationOnly)
+@available(*, deprecated, renamed: "ABI.v0")
+public typealias ABIv0 = ABI.v0
diff --git a/Sources/Testing/ABI/Encoded/ABI.EncodedAttachment.swift b/Sources/Testing/ABI/Encoded/ABI.EncodedAttachment.swift
@@ -8,7 +8,7 @@
 // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 //
 
-extension ABIv0 {
+extension ABI {
   /// A type implementing the JSON encoding of ``Attachment`` for the ABI entry
   /// point and event stream output.
   ///
@@ -29,4 +29,4 @@ extension ABIv0 {
 
 // MARK: - Codable
 
-extension ABIv0.EncodedAttachment: Codable {}
+extension ABI.EncodedAttachment: Codable {}
diff --git a/Sources/Testing/ABI/Encoded/ABI.EncodedBacktrace.swift b/Sources/Testing/ABI/Encoded/ABI.EncodedBacktrace.swift
@@ -8,7 +8,7 @@
 // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 //
 
-extension ABIv0 {
+extension ABI {
   /// A type implementing the JSON encoding of ``Backtrace`` for the ABI entry
   /// point and event stream output.
   ///
@@ -33,7 +33,7 @@ extension ABIv0 {
 
 // MARK: - Codable
 
-extension ABIv0.EncodedBacktrace: Codable {
+extension ABI.EncodedBacktrace: Codable {
   func encode(to encoder: any Encoder) throws {
     try symbolicatedAddresses.encode(to: encoder)
   }
diff --git a/Sources/Testing/ABI/Encoded/ABI.EncodedError.swift b/Sources/Testing/ABI/Encoded/ABI.EncodedError.swift
@@ -8,7 +8,7 @@
 // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 //
 
-extension ABIv0 {
+extension ABI {
   /// A type implementing the JSON encoding of ``Error`` for the ABI entry point
   /// and event stream output.
   ///
@@ -39,7 +39,7 @@ extension ABIv0 {
 
 // MARK: - Error
 
-extension ABIv0.EncodedError: Error {
+extension ABI.EncodedError: Error {
   var _domain: String {
     domain
   }
@@ -56,11 +56,11 @@ extension ABIv0.EncodedError: Error {
 
 // MARK: - Codable
 
-extension ABIv0.EncodedError: Codable {}
+extension ABI.EncodedError: Codable {}
 
 // MARK: - CustomTestStringConvertible
 
-extension ABIv0.EncodedError: CustomTestStringConvertible {
+extension ABI.EncodedError: CustomTestStringConvertible {
   var testDescription: String {
     description
   }
diff --git a/Sources/Testing/ABI/Encoded/ABI.EncodedEvent.swift b/Sources/Testing/ABI/Encoded/ABI.EncodedEvent.swift
@@ -8,7 +8,7 @@
 // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 //
 
-extension ABIv0 {
+extension ABI {
   /// A type implementing the JSON encoding of ``Event`` for the ABI entry point
   /// and event stream output.
   ///
@@ -109,5 +109,5 @@ extension ABIv0 {
 
 // MARK: - Codable
 
-extension ABIv0.EncodedEvent: Codable {}
-extension ABIv0.EncodedEvent.Kind: Codable {}
+extension ABI.EncodedEvent: Codable {}
+extension ABI.EncodedEvent.Kind: Codable {}
diff --git a/Sources/Testing/ABI/Encoded/ABI.EncodedInstant.swift b/Sources/Testing/ABI/Encoded/ABI.EncodedInstant.swift
@@ -8,7 +8,7 @@
 // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 //
 
-extension ABIv0 {
+extension ABI {
   /// A type implementing the JSON encoding of ``Test/Clock/Instant`` for the
   /// ABI entry point and event stream output.
   ///
@@ -37,4 +37,4 @@ extension ABIv0 {
 
 // MARK: - Codable
 
-extension ABIv0.EncodedInstant: Codable {}
+extension ABI.EncodedInstant: Codable {}
diff --git a/Sources/Testing/ABI/Encoded/ABI.EncodedIssue.swift b/Sources/Testing/ABI/Encoded/ABI.EncodedIssue.swift
@@ -8,7 +8,7 @@
 // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 //
 
-extension ABIv0 {
+extension ABI {
   /// A type implementing the JSON encoding of ``Issue`` for the ABI entry point
   /// and event stream output.
   ///
@@ -65,5 +65,5 @@ extension ABIv0 {
 
 // MARK: - Codable
 
-extension ABIv0.EncodedIssue: Codable {}
-extension ABIv0.EncodedIssue.Severity: Codable {}
+extension ABI.EncodedIssue: Codable {}
+extension ABI.EncodedIssue.Severity: Codable {}
diff --git a/Sources/Testing/ABI/Encoded/ABI.EncodedMessage.swift b/Sources/Testing/ABI/Encoded/ABI.EncodedMessage.swift
@@ -8,7 +8,7 @@
 // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 //
 
-extension ABIv0 {
+extension ABI {
   /// A type implementing the JSON encoding of
   /// ``Event/HumanReadableOutputRecorder/Message`` for the ABI entry point and
   /// event stream output.
@@ -76,5 +76,5 @@ extension ABIv0 {
 
 // MARK: - Codable
 
-extension ABIv0.EncodedMessage: Codable {}
-extension ABIv0.EncodedMessage.Symbol: Codable {}
+extension ABI.EncodedMessage: Codable {}
+extension ABI.EncodedMessage.Symbol: Codable {}
diff --git a/Sources/Testing/ABI/Encoded/ABI.EncodedTest.swift b/Sources/Testing/ABI/Encoded/ABI.EncodedTest.swift
@@ -8,7 +8,7 @@
 // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 //
 
-extension ABIv0 {
+extension ABI {
   /// A type implementing the JSON encoding of ``Test`` for the ABI entry point
   /// and event stream output.
   ///
@@ -92,7 +92,7 @@ extension ABIv0 {
   }
 }
 
-extension ABIv0 {
+extension ABI {
   /// A type implementing the JSON encoding of ``Test/Case`` for the ABI entry
   /// point and event stream output.
   ///
@@ -120,6 +120,6 @@ extension ABIv0 {
 
 // MARK: - Codable
 
-extension ABIv0.EncodedTest: Codable {}
-extension ABIv0.EncodedTest.Kind: Codable {}
-extension ABIv0.EncodedTestCase: Codable {}
+extension ABI.EncodedTest: Codable {}
+extension ABI.EncodedTest.Kind: Codable {}
+extension ABI.EncodedTestCase: Codable {}
diff --git a/Sources/Testing/ABI/EntryPoints/ABIEntryPoint.swift b/Sources/Testing/ABI/EntryPoints/ABIEntryPoint.swift
@@ -11,7 +11,7 @@
 #if canImport(Foundation) && !SWT_NO_ABI_ENTRY_POINT
 private import _TestingInternals
 
-extension ABIv0 {
+extension ABI.v0 {
   /// The type of the entry point to the testing library used by tools that want
   /// to remain version-agnostic regarding the testing library.
   ///
@@ -62,7 +62,7 @@ extension ABIv0 {
 ///   untyped pointer.
 @_cdecl("swt_abiv0_getEntryPoint")
 @usableFromInline func abiv0_getEntryPoint() -> UnsafeRawPointer {
-  unsafeBitCast(ABIv0.entryPoint, to: UnsafeRawPointer.self)
+  unsafeBitCast(ABI.v0.entryPoint, to: UnsafeRawPointer.self)
 }
 
 #if !SWT_NO_SNAPSHOT_TYPES
@@ -72,7 +72,7 @@ extension ABIv0 {
 /// Beta 1.
 ///
 /// This type will be removed in a future update.
-@available(*, deprecated, message: "Use ABIv0.EntryPoint instead.")
+@available(*, deprecated, message: "Use ABI.v0.EntryPoint instead.")
 typealias ABIEntryPoint_v0 = @Sendable (
   _ argumentsJSON: UnsafeRawBufferPointer?,
   _ recordHandler: @escaping @Sendable (_ recordJSON: UnsafeRawBufferPointer) -> Void
@@ -82,7 +82,7 @@ typealias ABIEntryPoint_v0 = @Sendable (
 /// Xcode 16 Beta 1.
 ///
 /// This function will be removed in a future update.
-@available(*, deprecated, message: "Use ABIv0.entryPoint (swt_abiv0_getEntryPoint()) instead.")
+@available(*, deprecated, message: "Use ABI.v0.entryPoint (swt_abiv0_getEntryPoint()) instead.")
 @_cdecl("swt_copyABIEntryPoint_v0")
 @usableFromInline func copyABIEntryPoint_v0() -> UnsafeMutableRawPointer {
   let result = UnsafeMutablePointer<ABIEntryPoint_v0>.allocate(capacity: 1)
@@ -124,8 +124,8 @@ private func _entryPoint(
   let exitCode = await entryPoint(passing: args, eventHandler: eventHandler)
 
   // To maintain compatibility with Xcode 16 Beta 1, suppress custom exit codes.
-  // (This is also needed by ABIv0.entryPoint to correctly treat the no-tests as
-  // a successful run.)
+  // (This is also needed by ABI.v0.entryPoint to correctly treat the no-tests
+  // as a successful run.)
   if exitCode == EXIT_NO_TESTS_FOUND {
     return EXIT_SUCCESS
   }
diff --git a/Sources/Testing/ABI/EntryPoints/EntryPoint.swift b/Sources/Testing/ABI/EntryPoints/EntryPoint.swift
@@ -612,8 +612,8 @@ func eventHandlerForStreamingEvents(
     // will be removed in a future update. Do not use it.
     eventHandlerForStreamingEventSnapshots(to: eventHandler)
 #endif
-  case nil, 0:
-    ABIv0.Record.eventHandler(encodeAsJSONLines: encodeAsJSONLines, forwardingTo: eventHandler)
+  case nil, 0, 1:
+    ABI.Record.eventHandler(encodeAsJSONLines: encodeAsJSONLines, forwardingTo: eventHandler)
   case let .some(unsupportedVersion):
     throw _EntryPointError.invalidArgument("--event-stream-version", value: "\(unsupportedVersion)")
   }
diff --git a/Sources/Testing/ABI/v0/ABIv0.swift b/Sources/Testing/ABI/v0/ABIv0.swift
diff --git a/Sources/Testing/CMakeLists.txt b/Sources/Testing/CMakeLists.txt
@@ -10,17 +10,17 @@ add_library(Testing
   ABI/EntryPoints/ABIEntryPoint.swift
   ABI/EntryPoints/EntryPoint.swift
   ABI/EntryPoints/SwiftPMEntryPoint.swift
-  ABI/v0/ABIv0.Record.swift
-  ABI/v0/ABIv0.Record+Streaming.swift
-  ABI/v0/ABIv0.swift
-  ABI/v0/Encoded/ABIv0.EncodedAttachment.swift
-  ABI/v0/Encoded/ABIv0.EncodedBacktrace.swift
-  ABI/v0/Encoded/ABIv0.EncodedError.swift
-  ABI/v0/Encoded/ABIv0.EncodedEvent.swift
-  ABI/v0/Encoded/ABIv0.EncodedInstant.swift
-  ABI/v0/Encoded/ABIv0.EncodedIssue.swift
-  ABI/v0/Encoded/ABIv0.EncodedMessage.swift
-  ABI/v0/Encoded/ABIv0.EncodedTest.swift
+  ABI/ABI.Record.swift
+  ABI/ABI.Record+Streaming.swift
+  ABI/ABI.swift
+  ABI/Encoded/ABI.EncodedAttachment.swift
+  ABI/Encoded/ABI.EncodedBacktrace.swift
+  ABI/Encoded/ABI.EncodedError.swift
+  ABI/Encoded/ABI.EncodedEvent.swift
+  ABI/Encoded/ABI.EncodedInstant.swift
+  ABI/Encoded/ABI.EncodedIssue.swift
+  ABI/Encoded/ABI.EncodedMessage.swift
+  ABI/Encoded/ABI.EncodedTest.swift
   Attachments/Attachable.swift
   Attachments/AttachableContainer.swift
   Attachments/Attachment.swift
diff --git a/Sources/Testing/ExitTests/ExitTest.swift b/Sources/Testing/ExitTests/ExitTest.swift
@@ -444,7 +444,7 @@ extension ExitTest {
     // Encode events as JSON and write them to the back channel file handle.
     // Only forward issue-recorded events. (If we start handling other kinds of
     // events in the future, we can forward them too.)
-    let eventHandler = ABIv0.Record.eventHandler(encodeAsJSONLines: true) { json in
+    let eventHandler = ABI.Record.eventHandler(encodeAsJSONLines: true) { json in
       _ = try? _backChannelForEntryPoint?.withLock {
         try _backChannelForEntryPoint?.write(json)
         try _backChannelForEntryPoint?.write("\n")
@@ -692,7 +692,7 @@ extension ExitTest {
   ///
   /// - Throws: Any error encountered attempting to decode or process the JSON.
   private static func _processRecord(_ recordJSON: UnsafeRawBufferPointer, fromBackChannel backChannel: borrowing FileHandle) throws {
-    let record = try JSON.decode(ABIv0.Record.self, from: recordJSON)
+    let record = try JSON.decode(ABI.Record.self, from: recordJSON)
 
     if case let .event(event) = record.kind, let issue = event.issue {
       // Translate the issue back into a "real" issue and record it
diff --git a/Tests/TestingTests/ABIEntryPointTests.swift b/Tests/TestingTests/ABIEntryPointTests.swift
diff --git a/Tests/TestingTests/SwiftPMTests.swift b/Tests/TestingTests/SwiftPMTests.swift
