[ST-0020] Promote SourceLocation.filePath to API. (#1472)

This PR formally implements the changes proposed in
[ST-0020](https://github.com/swiftlang/swift-evolution/blob/main/proposals/testing/0020-sourcelocation-filepath.md).

Resolves rdar://152999195.

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

@@ -39,7 +39,9 @@ array (also defined as in JSON) whose elements all follow rule `<T>`.
 <bool> ::= true | false ; as in JSON
 
 <source-location> ::= {
-  "fileID": <string>, ; the Swift file ID of the file
+  ["fileID": <string>,] ; the Swift file ID of the file if available, as per
+                        ; SE-0274 § "Specification of the #file string format"
+  "filePath": <string>, ; the compile-time path to the file
   "line": <number>,
   "column": <number>,
 }
@@ -49,7 +51,8 @@ array (also defined as in JSON) whose elements all follow rule `<T>`.
   "since1970": <number>, ; floating-point seconds since 1970-01-01 00:00:00 UT
 }
 
-<version> ::= "version": 0 ; will be incremented as the format changes
+<version> ::= "version": <version-number>
+<version-number> ::= 0 | "<version core>" ; as per https://semver.org
 ```
 
 <!--
@@ -230,3 +233,4 @@ sufficient information to display the event in a human-readable format.
 | [ST-0009](https://github.com/swiftlang/swift-evolution/blob/main/proposals/testing/0009-attachments.md#integration-with-supporting-tools) | Added attachments. | 6.2 | `0` |
 | [ST-0013](https://github.com/swiftlang/swift-evolution/blob/main/proposals/testing/0013-issue-severity-warning.md#event-stream) | Added test issue severity. | 6.3 | `"6.3"` |
 | [ST-0016](https://github.com/swiftlang/swift-evolution/blob/main/proposals/testing/0016-test-cancellation.md#integration-with-supporting-tools) | Added test cancellation. | 6.3 | `"6.3"` |
+| [ST-0020](https://github.com/swiftlang/swift-evolution/blob/main/proposals/testing/0020-sourcelocation-filepath.md#detailed-design) | Added `filePath`. | 6.3 | `"6.3"` |

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

@@ -96,7 +96,7 @@ extension ABI {
     ///
     /// - Warning: Source locations at this level of the JSON schema are not yet
     ///   part of said JSON schema.
-    var _sourceLocation: SourceLocation?
+    var _sourceLocation: EncodedSourceLocation<V>?
 
     init?(encoding event: borrowing Event, in eventContext: borrowing Event.Context, messages: borrowing [Event.HumanReadableOutputRecorder.Message]) {
       switch event.kind {
@@ -142,14 +142,14 @@ extension ABI {
         switch event.kind {
         case let .issueRecorded(recordedIssue):
           _comments = recordedIssue.comments.map(\.rawValue)
-          _sourceLocation = recordedIssue.sourceLocation
+          _sourceLocation = recordedIssue.sourceLocation.map { EncodedSourceLocation(encoding: $0) }
         case let .valueAttached(attachment):
-          _sourceLocation = attachment.sourceLocation
+          _sourceLocation = EncodedSourceLocation<V>(encoding: attachment.sourceLocation)
         case let .testCaseCancelled(skipInfo),
           let .testSkipped(skipInfo),
           let .testCancelled(skipInfo):
           _comments = Array(skipInfo.comment).map(\.rawValue)
-          _sourceLocation = skipInfo.sourceLocation
+          _sourceLocation = skipInfo.sourceLocation.map { EncodedSourceLocation(encoding: $0) }
         default:
           break
         }

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

@@ -46,7 +46,7 @@ extension ABI {
     var isKnown: Bool
 
     /// The location in source where this issue occurred, if available.
-    var sourceLocation: SourceLocation?
+    var sourceLocation: EncodedSourceLocation<V>?
 
     /// The backtrace where this issue occurred, if available.
     ///
@@ -61,7 +61,7 @@ extension ABI {
     init(encoding issue: borrowing Issue, in eventContext: borrowing Event.Context) {
       // >= v0
       isKnown = issue.isKnown
-      sourceLocation = issue.sourceLocation
+      sourceLocation = issue.sourceLocation.map { EncodedSourceLocation(encoding: $0) }
 
       // >= v6.3
       if V.versionNumber >= ABI.v6_3.versionNumber {

Sources/Testing/ABI/Encoded/ABI.EncodedSourceLocation.swift

@@ -0,0 +1,67 @@
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2026 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
+//
+
+extension ABI {
+  /// A type implementing the JSON encoding of ``SourceLocation`` for the ABI
+  /// entry point and event stream output.
+  ///
+  /// This type is not part of the public interface of the testing library. It
+  /// assists in converting values to JSON; clients that consume this JSON are
+  /// expected to write their own decoders.
+  struct EncodedSourceLocation<V>: Sendable where V: ABI.Version {
+    /// See ``SourceLocation`` for a discussion of these properties.
+    var fileID: String?
+    var filePath: String?
+    var _filePath: String?
+    var line: Int
+    var column: Int
+
+    init(encoding sourceLocation: borrowing SourceLocation) {
+      fileID = sourceLocation.fileID
+
+      // When using the 6.3 schema, don't encode synthesized file IDs.
+      if V.versionNumber >= ABI.v6_3.versionNumber,
+         sourceLocation.moduleName == SourceLocation.synthesizedModuleName {
+        fileID = nil
+      }
+
+      // When using the 6.3 schema, we encode both "filePath" and "_filePath" to
+      // ease migration for existing tools.
+      if V.versionNumber >= ABI.v6_3.versionNumber {
+        filePath = sourceLocation.filePath
+      }
+      if V.versionNumber <= ABI.v6_3.versionNumber {
+        _filePath = sourceLocation.filePath
+      }
+
+      line = sourceLocation.line
+      column = sourceLocation.column
+    }
+  }
+}
+
+// MARK: - Codable
+
+extension ABI.EncodedSourceLocation: Codable {}
+
+// MARK: -
+
+extension SourceLocation {
+  init?<V>(_ sourceLocation: ABI.EncodedSourceLocation<V>) {
+    let fileID = sourceLocation.fileID
+    guard let filePath = sourceLocation.filePath ?? sourceLocation._filePath else {
+      return nil
+    }
+    let line = max(1, sourceLocation.line)
+    let column = max(1, sourceLocation.column)
+
+    self.init(fileIDSynthesizingIfNeeded: fileID, filePath: filePath, line: line, column: column)
+  }
+}

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

@@ -38,7 +38,7 @@ extension ABI {
     var displayName: String?
 
     /// The source location of this test.
-    var sourceLocation: SourceLocation
+    var sourceLocation: EncodedSourceLocation<V>
 
     /// A type implementing the JSON encoding of ``Test/ID`` for the ABI entry
     /// point and event stream output.
@@ -87,7 +87,7 @@ extension ABI {
       }
       name = test.name
       displayName = test.displayName
-      sourceLocation = test.sourceLocation
+      sourceLocation = EncodedSourceLocation(encoding: test.sourceLocation)
       id = ID(encoding: test.id)
 
       // Experimental fields

Sources/Testing/CMakeLists.txt

@@ -21,6 +21,7 @@ add_library(Testing
   ABI/Encoded/ABI.EncodedInstant.swift
   ABI/Encoded/ABI.EncodedIssue.swift
   ABI/Encoded/ABI.EncodedMessage.swift
+  ABI/Encoded/ABI.EncodedSourceLocation.swift
   ABI/Encoded/ABI.EncodedTest.swift
   Attachments/Images/AttachableAsImage.swift
   Attachments/Images/_AttachableImageWrapper.swift

Sources/Testing/Events/Recorder/Event.AdvancedConsoleOutputRecorder.swift

@@ -610,7 +610,7 @@ extension Event.AdvancedConsoleOutputRecorder {
             }
 
             // 2. Location
-            if let sourceLocation = issue.sourceLocation {
+            if let sourceLocation = issue.sourceLocation.flatMap(SourceLocation.init) {
               output += "\n"
               output += "  Location: \(sourceLocation.fileName):\(sourceLocation.line):\(sourceLocation.column)\n"
             }
@@ -731,7 +731,7 @@ extension Event.AdvancedConsoleOutputRecorder {
           output += "\(issuePrefix)\(issueTreePrefix)Expectation failed: \(conciseDescription)\n"
 
           // Add concise source location
-          if let sourceLocation = issue.sourceLocation {
+          if let sourceLocation = issue.sourceLocation.flatMap(SourceLocation.init) {
             let locationPrefix = issuePrefix + (isLastIssue ? "   " : "\(_treeVertical)  ")
             output += "\(locationPrefix)at \(sourceLocation.fileName):\(sourceLocation.line)\n"
           }
@@ -952,7 +952,7 @@ extension Event.AdvancedConsoleOutputRecorder {
     var fileName = ""
     if let issues = context.testData[testID]?.issues, 
        let firstIssue = issues.first,
-       let sourceLocation = firstIssue.sourceLocation {
+       let sourceLocation = firstIssue.sourceLocation.flatMap(SourceLocation.init) {
       fileName = sourceLocation.fileName
     }
 

Sources/Testing/ExitTests/ExitTest.swift

@@ -1031,7 +1031,7 @@ extension ExitTest {
     lazy var comments: [Comment] = event._comments?.map(Comment.init(rawValue:)) ?? []
     lazy var sourceContext = SourceContext(
       backtrace: nil, // A backtrace from the child process will have the wrong address space.
-      sourceLocation: event._sourceLocation
+      sourceLocation: event._sourceLocation.flatMap(SourceLocation.init)
     )
     lazy var skipInfo = SkipInfo(comment: comments.first, sourceContext: sourceContext)
     if let issue = event.issue {
@@ -1059,7 +1059,7 @@ extension ExitTest {
       }
       issueCopy.record()
     } else if let attachment = event.attachment {
-      Attachment.record(attachment, sourceLocation: event._sourceLocation!)
+      Attachment.record(attachment, sourceLocation: event._sourceLocation.flatMap(SourceLocation.init)!)
     } else if case .testCancelled = event.kind {
       _ = try? Test.cancel(with: skipInfo)
     }

Sources/Testing/SourceAttribution/SourceLocation+Macro.swift

@@ -12,11 +12,11 @@
 ///
 /// - Returns: The source location at which this macro is applied.
 ///
-/// This macro can be used in place of `#fileID`, `#line`, and `#column` as a
-/// default argument to a function. It expands to an instance of
+/// You can use this macro in place of `#fileID`, `#filePath`, `#line`, and
+/// `#column` as a default argument to a function. It expands to an instance of
 /// ``SourceLocation`` referring to the location of the macro invocation itself
 /// (similar to how `#fileID` expands to the ID of the file containing the
-/// `#fileID` invocation.)
+/// `#fileID` invocation).
 @freestanding(expression) public macro _sourceLocation() -> SourceLocation = #externalMacro(module: "TestingMacros", type: "SourceLocationMacro")
 
 extension SourceLocation {

Sources/Testing/SourceAttribution/SourceLocation.swift

@@ -71,7 +71,6 @@ public struct SourceLocation: Sendable {
   }
 
   /// The path to the source file.
-  @_spi(Experimental)
   public var filePath: String
 
   /// The line in the source file.
@@ -212,14 +211,61 @@ extension SourceLocation: Codable {
 
   public 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)
+    let fileID = try container.decode(String.self, forKey: .fileID)
+    let line = try container.decode(Int.self, forKey: .line)
+    let 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)
+    let filePath = try container.decodeIfPresent(String.self, forKey: .filePath)
       ?? container.decode(String.self, forKey: ._filePath)
+
+    self.init(fileID: fileID, filePath: filePath, line: line, column: column)
+  }
+
+  init(fileIDSynthesizingIfNeeded fileID: String?, filePath: String, line: Int, column: Int) {
+    // Synthesize the file ID if needed.
+    let fileID = fileID ?? Self._synthesizeFileID(fromFilePath: filePath)
+    self.init(fileID: fileID, filePath: filePath, line: line, column: column)
+  }
+
+  /// The name of the ersatz Swift module used for synthesized file IDs.
+  static var synthesizedModuleName: String {
+    "__C"
+  }
+
+  /// Synthesize a file ID from the given file path and module name.
+  ///
+  /// - Parameters:
+  ///   - filePath: The file path.
+  ///   - moduleName: The module name.
+  ///
+  /// - Returns: A file path constructed from `filePath` and `moduleName`.
+  private static func _synthesizeFileID(fromFilePath filePath: String, inModuleNamed moduleName: String = synthesizedModuleName) -> String {
+    let fileName: String? = {
+      var filePath = filePath[...]
+
+#if os(Windows)
+      // On Windows, replace backslashes in the path with slashes. (This is an
+      // admittedly naïve approach, but this function is not a hot path.)
+      do {
+        let characters = filePath.map { $0 == #"\"# ? "/" : $0 }
+        filePath = String(characters)[...]
+      }
+#endif
+
+      // Trim any trailing slashes, then take the substring following the last
+      // (remaining) slash, if any.
+      if let lastNonSlashCharacter = filePath.lastIndex(where: { $0 != "/" }) {
+        filePath = filePath[...lastNonSlashCharacter]
+        if let lastSlashCharacter = filePath.lastIndex(of: "/") {
+          filePath = filePath[lastSlashCharacter...].dropFirst()
+        }
+        return String(filePath)
+      }
+      return nil
+    }()
+    return "\(moduleName)/\(fileName ?? filePath)"
   }
 }
 
@@ -231,7 +277,7 @@ extension SourceLocation {
   /// - 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")
+  @available(swift, deprecated: 6.3, renamed: "filePath")
   public var _filePath: String {
     get {
       filePath