Define an experimental event stream version and use it to conditionalize relevant content (#1287)

This PR formally defines an "experimental" event stream version (named
`ABI.ExperimentalVersion`) which represents content that is considered
experimental. It then adopts the new experimental version in several
places to conditionalize the inclusion of fields on event stream models
which are not yet officially included in any defined, supported version.
Finally, it uses this new version everywhere that intentionally always
uses the _highest experimental_ version, such as the exit test back
channel and the [recently-added](#1253) experimental console output
recorder.

### Motivation:

The event stream now has an established versioning system (as of #956)
and can easily conditionalize content based on version. As a general
rule, we prefer to exclude content which has not gone through Swift
Evolution review when delivering data to event stream consumers which
expect to receive content from a supported version. The fields this PR
conditionalizes have underscore prefixes and have code-level
documentation indicating their unofficial-ness, but the fact that they
are included at all in supported/non-experimental version streams could
lead to misuse or unintentional breakages in the future if the names or
semantics of these fields change.

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

Sources/Testing/ABI/ABI.swift

@@ -45,7 +45,8 @@ extension ABI {
   /// The current supported ABI version (ignoring any experimental versions.)
   typealias CurrentVersion = v0
 
-  /// The highest supported ABI version (including any experimental versions.)
+  /// The highest defined and supported ABI version (including any experimental
+  /// versions.)
   typealias HighestVersion = v6_3
 
 #if !hasFeature(Embedded)
@@ -93,6 +94,39 @@ extension ABI {
 #endif
 }
 
+/// The value of the environment variable flag which enables experimental event
+/// stream fields, if any.
+private let _shouldIncludeExperimentalFlags = Environment.flag(named: "SWT_EXPERIMENTAL_EVENT_STREAM_FIELDS_ENABLED")
+
+extension ABI.Version {
+  /// Whether or not experimental fields should be included when using this
+  /// ABI version.
+  ///
+  /// The value of this property is `true` if any of the following conditions
+  /// are satisfied:
+  ///
+  /// - The version number is less than 6.3. This is to preserve compatibility
+  ///   with existing clients before the inclusion of experimental fields became
+  ///   opt-in starting in 6.3.
+  /// - The version number is greater than or equal to 6.3 and the environment
+  ///   variable flag `SWT_EXPERIMENTAL_EVENT_STREAM_FIELDS_ENABLED` is set to a
+  ///   true value.
+  /// - The version number is greater than or equal to that of ``ABI/ExperimentalVersion``.
+  ///
+  /// Otherwise, the value of this property is `false`.
+  static var includesExperimentalFields: Bool {
+    switch versionNumber {
+    case ABI.ExperimentalVersion.versionNumber...:
+      true
+    case ABI.v6_3.versionNumber...:
+      _shouldIncludeExperimentalFlags == true
+    default:
+      // Maintain behavior for pre-6.3 versions.
+      true
+    }
+  }
+}
+
 // MARK: - Concrete ABI versions
 
 extension ABI {
@@ -125,6 +159,14 @@ extension ABI {
       VersionNumber(6, 3)
     }
   }
+
+  /// A namespace and type representing the ABI version whose symbols are
+  /// considered experimental.
+  enum ExperimentalVersion: Sendable, Version {
+    static var versionNumber: VersionNumber {
+      VersionNumber(99, 0)
+    }
+  }
 }
 
 /// A namespace for ABI version 0 symbols.

Sources/Testing/ABI/Encoded/ABI.EncodedEvent.swift

@@ -145,8 +145,12 @@ extension ABI {
       instant = EncodedInstant(encoding: event.instant)
       self.messages = messages.map(EncodedMessage.init)
       testID = event.testID.map(EncodedTest.ID.init)
-      if eventContext.test?.isParameterized == true {
-        _testCase = eventContext.testCase.map(EncodedTestCase.init)
+
+      // Experimental fields
+      if V.includesExperimentalFields {
+        if eventContext.test?.isParameterized == true {
+          _testCase = eventContext.testCase.map(EncodedTestCase.init)
+        }
       }
     }
   }

Sources/Testing/ABI/Encoded/ABI.EncodedIssue.swift

@@ -72,12 +72,14 @@ extension ABI {
         isFailure = issue.isFailure
       }
 
-      // Experimental
-      if let backtrace = issue.sourceContext.backtrace {
-        _backtrace = EncodedBacktrace(encoding: backtrace, in: eventContext)
-      }
-      if let error = issue.error {
-        _error = EncodedError(encoding: error, in: eventContext)
+      // Experimental fields
+      if V.includesExperimentalFields {
+        if let backtrace = issue.sourceContext.backtrace {
+          _backtrace = EncodedBacktrace(encoding: backtrace, in: eventContext)
+        }
+        if let error = issue.error {
+          _error = EncodedError(encoding: error, in: eventContext)
+        }
       }
     }
   }

Sources/Testing/ABI/Encoded/ABI.EncodedTest.swift

@@ -76,29 +76,26 @@ extension ABI {
     /// The tags associated with the test.
     ///
     /// - Warning: Tags are not yet part of the JSON schema.
-    ///
-    /// @Metadata {
-    ///   @Available("Swift Testing ABI", introduced: 6.3)
-    /// }
     var _tags: [String]?
 
     init(encoding test: borrowing Test) {
       if test.isSuite {
         kind = .suite
       } else {
         kind = .function
-        let testIsParameterized = test.isParameterized
-        isParameterized = testIsParameterized
-        if testIsParameterized {
-          _testCases = test.uncheckedTestCases?.map(EncodedTestCase.init(encoding:))
-        }
+        isParameterized = test.isParameterized
       }
       name = test.name
       displayName = test.displayName
       sourceLocation = test.sourceLocation
       id = ID(encoding: test.id)
 
-      if V.versionNumber >= ABI.v6_3.versionNumber {
+      // Experimental fields
+      if V.includesExperimentalFields {
+        if isParameterized == true {
+          _testCases = test.uncheckedTestCases?.map(EncodedTestCase.init(encoding:))
+        }
+
         let tags = test.tags
         if !tags.isEmpty {
           _tags = tags.map(String.init(describing:))

Sources/Testing/ABI/EntryPoints/EntryPoint.swift

@@ -57,10 +57,10 @@ func entryPoint(passing args: __CommandLineArguments_v0?, eventHandler: Event.Ha
       // Check for experimental console output flag
       if Environment.flag(named: "SWT_ENABLE_EXPERIMENTAL_CONSOLE_OUTPUT") == true {
         // Use experimental AdvancedConsoleOutputRecorder
-        var advancedOptions = Event.AdvancedConsoleOutputRecorder<ABI.HighestVersion>.Options()
+        var advancedOptions = Event.AdvancedConsoleOutputRecorder<ABI.ExperimentalVersion>.Options()
         advancedOptions.base = .for(.stderr)
 
-        let eventRecorder = Event.AdvancedConsoleOutputRecorder<ABI.HighestVersion>(options: advancedOptions) { string in
+        let eventRecorder = Event.AdvancedConsoleOutputRecorder<ABI.ExperimentalVersion>(options: advancedOptions) { string in
           try? FileHandle.stderr.write(string)
         }
 

Sources/Testing/ExitTests/ExitTest.swift

@@ -542,10 +542,9 @@ extension ABI {
   /// The ABI version to use for encoding and decoding events sent over the back
   /// channel.
   ///
-  /// The back channel always uses the latest ABI version (even if experimental)
-  /// since both the producer and consumer use this exact version of the testing
-  /// library.
-  fileprivate typealias BackChannelVersion = v6_3
+  /// The back channel always uses the experimental ABI version since both the
+  /// producer and consumer use this exact version of the testing library.
+  fileprivate typealias BackChannelVersion = ExperimentalVersion
 }
 
 @_spi(ForToolsIntegrationOnly)

Tests/TestingTests/SwiftPMTests.swift

@@ -376,7 +376,7 @@ struct SwiftPMTests {
     }
     #expect(testRecords.count == 1)
     for testRecord in testRecords {
-      if version.versionNumber >= ABI.v6_3.versionNumber {
+      if version.includesExperimentalFields {
         #expect(testRecord._tags != nil)
       } else {
         #expect(testRecord._tags == nil)