Promote SourceLocation._filePath to proper, non-underscored SPI.

This PR introduces an `@_spi var filePath` property on `SourceLocation` with the
intent of replacing the existing underscored/unsupported `_filePath` property.

Because Xcode 16 through 26 directly encodes and decodes instances of
`SourceLocation`, we can't just stop encoding/decoding the `_filePath` key and
need to keep it there for at least a Swift release or two, until Apple's fork of
Swift Testing has been updated to include the new encoding key. At that point we
can remove the old one.

Author: grynspan

Sources/Testing/SourceAttribution/SourceLocation.swift

@@ -71,11 +71,8 @@ public struct SourceLocation: Sendable {
   }
 
   /// The path to the source file.
-  ///
-  /// - Warning: This property is provided temporarily to aid in integrating the
-  ///   testing library with existing tools such as Swift Package Manager. It
-  ///   will be removed in a future release.
-  public var _filePath: String
+  @_spi(Experimental)
+  public var filePath: String
 
   /// The line in the source file.
   ///
@@ -118,7 +115,7 @@ public struct SourceLocation: Sendable {
     precondition(column > 0, "SourceLocation.column must be greater than 0 (was \(column))")
 
     self.fileID = fileID
-    self._filePath = filePath
+    self.filePath = filePath
     self.line = line
     self.column = column
   }
@@ -167,4 +164,54 @@ extension SourceLocation: CustomStringConvertible, CustomDebugStringConvertible
 
 // MARK: - Codable
 
-extension SourceLocation: Codable {}
+extension SourceLocation: Codable {
+  private enum CodingKeys: String, CodingKey {
+    case fileID
+    case filePath
+    case _filePath
+    case line
+    case column
+  }
+
+  func encode(to encoder: any Encoder) throws {
+    var container = encoder.container(keyedBy: CodingKeys.self)
+    try container.encode(fileID, forKey: .fileID)
+    try container.encode(line, forKey: .line)
+    try container.encode(column, forKey: .column)
+
+    // For backwards-compatibility, we must always encode "_filePath".
+    try container.encode(filePath, forKey: ._filePath)
+    try container.encode(filePath, forKey: .filePath)
+  }
+
+  init(from decoder: any Decoder) throws {
+    let container = try decoder.container(keyedBy: CodingKeys.self)
+    fileID = try container.decode(String.self, forKey: .fileID)
+    line = try container.decode(Int.self, forKey: .line)
+    column = try container.decode(Int.self, forKey: .column)
+
+    // For simplicity's sake, we won't be picky about which key contains the
+    // file path.
+    filePath = try container.decodeIfPresent(String.self, forKey: ._filePath)
+      ?? try container.decode(String.self, forKey: .filePath)
+  }
+}
+
+// MARK: - Deprecated
+
+extension SourceLocation {
+  /// The path to the source file.
+  ///
+  /// - Warning: This property is provided temporarily to aid in integrating the
+  ///   testing library with existing tools such as Swift Package Manager. It
+  ///   will be removed in a future release.
+  @available(swift, deprecated: 100000.0, renamed: "filePath")
+  public var _filePath: String {
+    get {
+      filePath
+    }
+    set {
+      filePath = newValue
+    }
+  }
+}

Tests/TestingTests/SourceLocationTests.swift

@@ -121,6 +121,16 @@ struct SourceLocationTests {
   }
 #endif
 
+  @Test("SourceLocation.filePath property")
+  func sourceLocationFilePath() {
+    var sourceLocation = #_sourceLocation
+    #expect(sourceLocation.filePath == #filePath)
+
+    sourceLocation.filePath = "A"
+    #expect(sourceLocation.filePath == "A")
+  }
+
+  @available(swift, deprecated: 100000.0)
   @Test("SourceLocation._filePath property")
   func sourceLocationFilePath() {
     var sourceLocation = #_sourceLocation