Promote attachments to API (swiftlang#973)

This PR promotes attachments to API and makes the appropriate changes to
match what was approved in the review of
[ST-0009](https://github.com/swiftlang/swift-evolution/blob/main/proposals/testing/0009-attachments.md).

### 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

Documentation/ABI/JSON.md

@@ -188,19 +188,24 @@ sufficient information to display the event in a human-readable format.
   "kind": <event-kind>,
   "instant": <instant>, ; when the event occurred
   ["issue": <issue>,] ; the recorded issue (if "kind" is "issueRecorded")
+  ["attachment": <attachment>,] ; the attachment (if kind is "valueAttached")
   "messages": <array:message>,
   ["testID": <test-id>,]
 }
 
 <event-kind> ::= "runStarted" | "testStarted" | "testCaseStarted" |
   "issueRecorded" | "testCaseEnded" | "testEnded" | "testSkipped" |
-  "runEnded" ; additional event kinds may be added in the future
+  "runEnded" | "valueAttached"; additional event kinds may be added in the future
 
 <issue> ::= {
   "isKnown": <bool>, ; is this a known issue or not?
   ["sourceLocation": <source-location>,] ; where the issue occurred, if known
 }
 
+<attachment> ::= {
+  "path": <string>, ; the absolute path to the attachment on disk
+}
+
 <message> ::= {
   "symbol": <message-symbol>,
   "text": <string>, ; the human-readable text of this message

Sources/Overlays/_Testing_CoreGraphics/Attachments/Attachment+AttachableAsCGImage.swift

@@ -42,9 +42,9 @@ extension Attachment {
     contentType: (any Sendable)?,
     encodingQuality: Float,
     sourceLocation: SourceLocation
-  ) where AttachableValue == _AttachableImageContainer<T> {
-    let imageContainer = _AttachableImageContainer(image: attachableValue, encodingQuality: encodingQuality, contentType: contentType)
-    self.init(imageContainer, named: preferredName, sourceLocation: sourceLocation)
+  ) where AttachableValue == _AttachableImageWrapper<T> {
+    let imageWrapper = _AttachableImageWrapper(image: attachableValue, encodingQuality: encodingQuality, contentType: contentType)
+    self.init(imageWrapper, named: preferredName, sourceLocation: sourceLocation)
   }
 
   /// Initialize an instance of this type that encloses the given image.
@@ -79,7 +79,7 @@ extension Attachment {
     as contentType: UTType?,
     encodingQuality: Float = 1.0,
     sourceLocation: SourceLocation = #_sourceLocation
-  ) where AttachableValue == _AttachableImageContainer<T> {
+  ) where AttachableValue == _AttachableImageWrapper<T> {
     self.init(attachableValue: attachableValue, named: preferredName, contentType: contentType, encodingQuality: encodingQuality, sourceLocation: sourceLocation)
   }
 
@@ -109,7 +109,7 @@ extension Attachment {
     named preferredName: String? = nil,
     encodingQuality: Float = 1.0,
     sourceLocation: SourceLocation = #_sourceLocation
-  ) where AttachableValue == _AttachableImageContainer<T> {
+  ) where AttachableValue == _AttachableImageWrapper<T> {
     self.init(attachableValue: attachableValue, named: preferredName, contentType: nil, encodingQuality: encodingQuality, sourceLocation: sourceLocation)
   }
 }

Sources/Overlays/_Testing_CoreGraphics/Attachments/_AttachableImageContainer.swift renamed to Sources/Overlays/_Testing_CoreGraphics/Attachments/_AttachableImageWrapper.swift

@@ -9,7 +9,7 @@
 //
 
 #if SWT_TARGET_OS_APPLE && canImport(CoreGraphics)
-@_spi(Experimental) public import Testing
+public import Testing
 private import CoreGraphics
 
 private import ImageIO
@@ -48,7 +48,7 @@ import UniformTypeIdentifiers
 ///
 /// - [`CGImage`](https://developer.apple.com/documentation/coregraphics/cgimage)
 @_spi(Experimental)
-public struct _AttachableImageContainer<Image>: Sendable where Image: AttachableAsCGImage {
+public struct _AttachableImageWrapper<Image>: Sendable where Image: AttachableAsCGImage {
   /// The underlying image.
   ///
   /// `CGImage` and `UIImage` are sendable, but `NSImage` is not. `NSImage`
@@ -127,8 +127,8 @@ public struct _AttachableImageContainer<Image>: Sendable where Image: Attachable
 
 // MARK: -
 
-extension _AttachableImageContainer: AttachableContainer {
-  public var attachableValue: Image {
+extension _AttachableImageWrapper: AttachableWrapper {
+  public var wrappedValue: Image {
     image
   }
 

Sources/Overlays/_Testing_Foundation/Attachments/Attachable+Encodable+NSSecureCoding.swift

@@ -9,7 +9,7 @@
 //
 
 #if canImport(Foundation)
-@_spi(Experimental) public import Testing
+public import Testing
 public import Foundation
 
 // This implementation is necessary to let the compiler disambiguate when a type
@@ -18,7 +18,9 @@ public import Foundation
 // (which explicitly document what happens when a type conforms to both
 // protocols.)
 
-@_spi(Experimental)
+/// @Metadata {
+///   @Available(Swift, introduced: 6.2)
+/// }
 extension Attachable where Self: Encodable & NSSecureCoding {
   @_documentation(visibility: private)
   public func withUnsafeBytes<R>(for attachment: borrowing Attachment<Self>, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {

Sources/Overlays/_Testing_Foundation/Attachments/Attachable+Encodable.swift

@@ -9,7 +9,7 @@
 //
 
 #if canImport(Foundation)
-@_spi(Experimental) public import Testing
+public import Testing
 private import Foundation
 
 /// A common implementation of ``withUnsafeBytes(for:_:)`` that is used when a
@@ -53,7 +53,10 @@ func withUnsafeBytes<E, R>(encoding attachableValue: borrowing E, for attachment
 // Implement the protocol requirements generically for any encodable value by
 // encoding to JSON. This lets developers provide trivial conformance to the
 // protocol for types that already support Codable.
-@_spi(Experimental)
+
+/// @Metadata {
+///   @Available(Swift, introduced: 6.2)
+/// }
 extension Attachable where Self: Encodable {
   /// Encode this value into a buffer using either [`PropertyListEncoder`](https://developer.apple.com/documentation/foundation/propertylistencoder)
   /// or [`JSONEncoder`](https://developer.apple.com/documentation/foundation/jsonencoder),
@@ -86,6 +89,10 @@ extension Attachable where Self: Encodable {
   /// _and_ [`NSSecureCoding`](https://developer.apple.com/documentation/foundation/nssecurecoding),
   /// the default implementation of this function uses the value's conformance
   /// to `Encodable`.
+  ///
+  /// @Metadata {
+  ///   @Available(Swift, introduced: 6.2)
+  /// }
   public func withUnsafeBytes<R>(for attachment: borrowing Attachment<Self>, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
     try _Testing_Foundation.withUnsafeBytes(encoding: self, for: attachment, body)
   }

Sources/Overlays/_Testing_Foundation/Attachments/Attachable+NSSecureCoding.swift

@@ -9,13 +9,16 @@
 //
 
 #if canImport(Foundation)
-@_spi(Experimental) public import Testing
+public import Testing
 public import Foundation
 
 // As with Encodable, implement the protocol requirements for
 // NSSecureCoding-conformant classes by default. The implementation uses
 // NSKeyedArchiver for encoding.
-@_spi(Experimental)
+
+/// @Metadata {
+///   @Available(Swift, introduced: 6.2)
+/// }
 extension Attachable where Self: NSSecureCoding {
   /// Encode this object using [`NSKeyedArchiver`](https://developer.apple.com/documentation/foundation/nskeyedarchiver)
   /// into a buffer, then call a function and pass that buffer to it.
@@ -46,6 +49,10 @@ extension Attachable where Self: NSSecureCoding {
   /// _and_ [`NSSecureCoding`](https://developer.apple.com/documentation/foundation/nssecurecoding),
   /// the default implementation of this function uses the value's conformance
   /// to `Encodable`.
+  ///
+  /// @Metadata {
+  ///   @Available(Swift, introduced: 6.2)
+  /// }
   public func withUnsafeBytes<R>(for attachment: borrowing Attachment<Self>, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
     let format = try EncodingFormat(for: attachment)
 

Sources/Overlays/_Testing_Foundation/Attachments/Attachment+URL.swift

@@ -9,7 +9,7 @@
 //
 
 #if canImport(Foundation)
-@_spi(Experimental) public import Testing
+public import Testing
 public import Foundation
 
 #if !SWT_NO_PROCESS_SPAWNING && os(Windows)
@@ -32,8 +32,7 @@ extension URL {
   }
 }
 
-@_spi(Experimental)
-extension Attachment where AttachableValue == _AttachableURLContainer {
+extension Attachment where AttachableValue == _AttachableURLWrapper {
 #if SWT_TARGET_OS_APPLE
   /// An operation queue to use for asynchronously reading data from disk.
   private static let _operationQueue = OperationQueue()
@@ -51,6 +50,10 @@ extension Attachment where AttachableValue == _AttachableURLContainer {
   ///     attachment.
   ///
   /// - Throws: Any error that occurs attempting to read from `url`.
+  ///
+  /// @Metadata {
+  ///   @Available(Swift, introduced: 6.2)
+  /// }
   public init(
     contentsOf url: URL,
     named preferredName: String? = nil,
@@ -91,8 +94,8 @@ extension Attachment where AttachableValue == _AttachableURLContainer {
     }
 #endif
 
-    let urlContainer = _AttachableURLContainer(url: url, data: data, isCompressedDirectory: isDirectory)
-    self.init(urlContainer, named: preferredName, sourceLocation: sourceLocation)
+    let urlWrapper = _AttachableURLWrapper(url: url, data: data, isCompressedDirectory: isDirectory)
+    self.init(urlWrapper, named: preferredName, sourceLocation: sourceLocation)
   }
 }
 

Sources/Overlays/_Testing_Foundation/Attachments/Data+Attachable.swift

@@ -9,11 +9,16 @@
 //
 
 #if canImport(Foundation)
-@_spi(Experimental) public import Testing
+public import Testing
 public import Foundation
 
-@_spi(Experimental)
+/// @Metadata {
+///   @Available(Swift, introduced: 6.2)
+/// }
 extension Data: Attachable {
+  /// @Metadata {
+  ///   @Available(Swift, introduced: 6.2)
+  /// }
   public func withUnsafeBytes<R>(for attachment: borrowing Attachment<Self>, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
     try withUnsafeBytes(body)
   }

Sources/Overlays/_Testing_Foundation/Attachments/EncodingFormat.swift

@@ -9,7 +9,7 @@
 //
 
 #if canImport(Foundation)
-@_spi(Experimental) import Testing
+import Testing
 import Foundation
 
 /// An enumeration describing the encoding formats we support for `Encodable`

Sources/Overlays/_Testing_Foundation/Attachments/_AttachableURLContainer.swift renamed to Sources/Overlays/_Testing_Foundation/Attachments/_AttachableURLWrapper.swift

@@ -9,16 +9,15 @@
 //
 
 #if canImport(Foundation)
-@_spi(Experimental) public import Testing
+public import Testing
 public import Foundation
 
 /// A wrapper type representing file system objects and URLs that can be
 /// attached indirectly.
 ///
 /// You do not need to use this type directly. Instead, initialize an instance
 /// of ``Attachment`` using a file URL.
-@_spi(Experimental)
-public struct _AttachableURLContainer: Sendable {
+public struct _AttachableURLWrapper: Sendable {
   /// The underlying URL.
   var url: URL
 
@@ -31,8 +30,8 @@ public struct _AttachableURLContainer: Sendable {
 
 // MARK: -
 
-extension _AttachableURLContainer: AttachableContainer {
-  public var attachableValue: URL {
+extension _AttachableURLWrapper: AttachableWrapper {
+  public var wrappedValue: URL {
     url
   }