From 9f706d1dbfbb13d75b858aae6af6f2087e7041b7 Mon Sep 17 00:00:00 2001
From: Jonathan Grynspan <jgrynspan@apple.com>
Date: Fri, 24 Oct 2025 11:20:36 -0400
Subject: [PATCH] Add an SPI `Attachment.uncheckedPreferredName` property.

This PR adds a for-tools SPI property `uncheckedPreferredName` to `Attachment`.
We can then use this property to distinguish when the developer provided or did
not provide a name for an attachment.

Tools can then use this property and apply their own naming rules when consuming
attachments from the event stream.

Naming is hard; I'm open to other/better names.
---
 .../ABI/Encoded/ABI.EncodedAttachment.swift   |  2 +-
 Sources/Testing/Attachments/Attachment.swift  | 20 +++++++++++++------
 2 files changed, 15 insertions(+), 7 deletions(-)

diff --git a/Sources/Testing/ABI/Encoded/ABI.EncodedAttachment.swift b/Sources/Testing/ABI/Encoded/ABI.EncodedAttachment.swift
index 013e129f6..5f8096c4d 100644
--- a/Sources/Testing/ABI/Encoded/ABI.EncodedAttachment.swift
+++ b/Sources/Testing/ABI/Encoded/ABI.EncodedAttachment.swift
@@ -42,7 +42,7 @@ extension ABI {
       path = attachment.fileSystemPath
 
       if V.includesExperimentalFields {
-        _preferredName = attachment.preferredName
+        _preferredName = attachment.uncheckedPreferredName
 
         if path == nil {
           _bytes = try? attachment.withUnsafeBytes { bytes in
diff --git a/Sources/Testing/Attachments/Attachment.swift b/Sources/Testing/Attachments/Attachment.swift
index 1313b0d41..932666ac5 100644
--- a/Sources/Testing/Attachments/Attachment.swift
+++ b/Sources/Testing/Attachments/Attachment.swift
@@ -76,6 +76,19 @@ public struct Attachment<AttachableValue> where AttachableValue: Attachable & ~C
   /// Storage for ``preferredName``.
   fileprivate var _preferredName: String?
 
+  /// A filename to use when saving this attachment.
+  ///
+  /// The value of this property is equal to ``preferredName`` if the test
+  /// author specified a preferred name when creating the attachment. Otherwise,
+  /// the value of this property is `nil`.
+  @_spi(ForToolsIntegrationOnly)
+  public var uncheckedPreferredName: String? {
+    if let _preferredName, !_preferredName.isEmpty {
+      return attachableValue.preferredName(for: self, basedOn: _preferredName)
+    }
+    return nil
+  }
+
   /// A filename to use when saving this attachment.
   ///
   /// The value of this property is used as a hint to the testing library. The
@@ -88,12 +101,7 @@ public struct Attachment<AttachableValue> where AttachableValue: Attachable & ~C
   ///   @Available(Xcode, introduced: 26.0)
   /// }
   public var preferredName: String {
-    let suggestedName = if let _preferredName, !_preferredName.isEmpty {
-      _preferredName
-    } else {
-      Self.defaultPreferredName
-    }
-    return attachableValue.preferredName(for: self, basedOn: suggestedName)
+    uncheckedPreferredName ?? attachableValue.preferredName(for: self, basedOn: Self.defaultPreferredName)
   }
 
   /// The source location of this instance.