Replace #fileID, #filePath, #line, and #column with a single macro. (#304)

We have a bunch of functions that take separate, defaulted arguments for
file ID, column, etc. We'd like to normalize these functions to always
take a single `SourceLocation` instance, but until now there hasn't been
a way to express such a thing as a default argument without capturing
the wrong source location.

This PR takes advantage of
[SE-0422](https://github.com/apple/swift-evolution/blob/main/proposals/0422-caller-side-default-argument-macro-expression.md)
to create a new `#_sourceLocation` macro (name pending API review) that
does what we want here. We can't use the obvious `#sourceLocation`
because the language already reserves that macro name for an unrelated
use.

Resolves rdar://121883259.

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

---------

Co-authored-by: Stuart Montgomery <[email protected]>

Author: grynspan

Sources/Testing/Expectations/Expectation+Macro.swift

@@ -23,7 +23,7 @@
 @freestanding(expression) public macro expect(
   _ condition: Bool,
   _ comment: @autoclosure () -> Comment? = nil,
-  sourceLocation: SourceLocation = SourceLocation()
+  sourceLocation: SourceLocation = #_sourceLocation
 ) = #externalMacro(module: "TestingMacros", type: "ExpectMacro")
 
 /// Check that an expectation has passed after a condition has been evaluated
@@ -44,7 +44,7 @@
 @freestanding(expression) public macro require(
   _ condition: Bool,
   _ comment: @autoclosure () -> Comment? = nil,
-  sourceLocation: SourceLocation = SourceLocation()
+  sourceLocation: SourceLocation = #_sourceLocation
 ) = #externalMacro(module: "TestingMacros", type: "RequireMacro")
 
 // MARK: - Optional checking
@@ -68,7 +68,7 @@
 @freestanding(expression) public macro require<T>(
   _ optionalValue: T?,
   _ comment: @autoclosure () -> Comment? = nil,
-  sourceLocation: SourceLocation = SourceLocation()
+  sourceLocation: SourceLocation = #_sourceLocation
 ) -> T = #externalMacro(module: "TestingMacros", type: "RequireMacro")
 
 /// Unwrap an optional boolean value or, if it is `nil`, fail and throw an
@@ -98,7 +98,7 @@
 public macro require(
   _ optionalValue: Bool?,
   _ comment: @autoclosure () -> Comment? = nil,
-  sourceLocation: SourceLocation = SourceLocation()
+  sourceLocation: SourceLocation = #_sourceLocation
 ) -> Bool = #externalMacro(module: "TestingMacros", type: "AmbiguousRequireMacro")
 
 // MARK: - Matching errors by type
@@ -136,7 +136,7 @@ public macro require(
 @freestanding(expression) public macro expect<E, R>(
   throws errorType: E.Type,
   _ comment: @autoclosure () -> Comment? = nil,
-  sourceLocation: SourceLocation = SourceLocation(),
+  sourceLocation: SourceLocation = #_sourceLocation,
   performing expression: () async throws -> R
 ) = #externalMacro(module: "TestingMacros", type: "ExpectMacro") where E: Error
 
@@ -175,7 +175,7 @@ public macro require(
 @freestanding(expression) public macro expect<R>(
   throws _: Never.Type,
   _ comment: @autoclosure () -> Comment? = nil,
-  sourceLocation: SourceLocation = SourceLocation(),
+  sourceLocation: SourceLocation = #_sourceLocation,
   performing expression: () async throws -> R
 ) = #externalMacro(module: "TestingMacros", type: "ExpectMacro")
 
@@ -217,7 +217,7 @@ public macro require(
 @freestanding(expression) public macro require<E, R>(
   throws errorType: E.Type,
   _ comment: @autoclosure () -> Comment? = nil,
-  sourceLocation: SourceLocation = SourceLocation(),
+  sourceLocation: SourceLocation = #_sourceLocation,
   performing expression: () async throws -> R
 ) = #externalMacro(module: "TestingMacros", type: "RequireMacro") where E: Error
 
@@ -236,7 +236,7 @@ public macro require(
 @freestanding(expression) public macro require<R>(
   throws _: Never.Type,
   _ comment: @autoclosure () -> Comment? = nil,
-  sourceLocation: SourceLocation = SourceLocation(),
+  sourceLocation: SourceLocation = #_sourceLocation,
   performing expression: () async throws -> R
 ) = #externalMacro(module: "TestingMacros", type: "RequireMacro")
 
@@ -272,7 +272,7 @@ public macro require(
 @freestanding(expression) public macro expect<E, R>(
   throws error: E,
   _ comment: @autoclosure () -> Comment? = nil,
-  sourceLocation: SourceLocation = SourceLocation(),
+  sourceLocation: SourceLocation = #_sourceLocation,
   performing expression: () async throws -> R
 ) = #externalMacro(module: "TestingMacros", type: "ExpectMacro") where E: Error & Equatable
 
@@ -309,7 +309,7 @@ public macro require(
 @freestanding(expression) public macro require<E, R>(
   throws error: E,
   _ comment: @autoclosure () -> Comment? = nil,
-  sourceLocation: SourceLocation = SourceLocation(),
+  sourceLocation: SourceLocation = #_sourceLocation,
   performing expression: () async throws -> R
 ) = #externalMacro(module: "TestingMacros", type: "RequireMacro") where E: Error & Equatable
 
@@ -352,7 +352,7 @@ public macro require(
 /// ``expect(throws:_:sourceLocation:performing:)-5lzjz`` instead.
 @freestanding(expression) public macro expect<R>(
   _ comment: @autoclosure () -> Comment? = nil,
-  sourceLocation: SourceLocation = SourceLocation(),
+  sourceLocation: SourceLocation = #_sourceLocation,
   performing expression: () async throws -> R,
   throws errorMatcher: (any Error) async throws -> Bool
 ) = #externalMacro(module: "TestingMacros", type: "ExpectMacro")
@@ -400,7 +400,7 @@ public macro require(
 /// this macro. The test will then fail if an error is thrown.
 @freestanding(expression) public macro require<R>(
   _ comment: @autoclosure () -> Comment? = nil,
-  sourceLocation: SourceLocation = SourceLocation(),
+  sourceLocation: SourceLocation = #_sourceLocation,
   performing expression: () async throws -> R,
   throws errorMatcher: (any Error) async throws -> Bool
 ) = #externalMacro(module: "TestingMacros", type: "RequireMacro")
@@ -474,7 +474,7 @@ public macro require(
 @freestanding(expression) public macro expect(
   exitsWith expectedExitCondition: ExitCondition,
   _ comment: @autoclosure () -> Comment? = nil,
-  sourceLocation: SourceLocation = SourceLocation(),
+  sourceLocation: SourceLocation = #_sourceLocation,
   performing expression: @convention(thin) () async throws -> Void
 ) = #externalMacro(module: "TestingMacros", type: "ExitTestExpectMacro")
 
@@ -549,6 +549,6 @@ public macro require(
 @freestanding(expression) public macro require(
   exitsWith expectedExitCondition: ExitCondition,
   _ comment: @autoclosure () -> Comment? = nil,
-  sourceLocation: SourceLocation = SourceLocation(),
+  sourceLocation: SourceLocation = #_sourceLocation,
   performing expression: @convention(thin) () async -> Void
 ) = #externalMacro(module: "TestingMacros", type: "ExitTestRequireMacro")

Sources/Testing/Issues/Confirmation.swift

@@ -55,6 +55,8 @@ extension Confirmation {
 ///     `body` is invoked. The default value of this argument is `1`, indicating
 ///     that the event should occur exactly once. Pass `0` if the event should
 ///     _never_ occur when `body` is invoked.
+///   - sourceLocation: The source location to which any recorded issues should
+///     be attributed.
 ///   - body: The function to invoke.
 ///
 /// - Returns: Whatever is returned by `body`.
@@ -92,10 +94,7 @@ extension Confirmation {
 public func confirmation<R>(
   _ comment: Comment? = nil,
   expectedCount: Int = 1,
-  fileID: String = #fileID,
-  filePath: String = #filePath,
-  line: Int = #line,
-  column: Int = #column,
+  sourceLocation: SourceLocation = #_sourceLocation,
   _ body: (Confirmation) async throws -> R
 ) async rethrows -> R {
   let confirmation = Confirmation()
@@ -106,7 +105,7 @@ public func confirmation<R>(
         .confirmationMiscounted(actual: actualCount, expected: expectedCount),
         comments: Array(comment),
         backtrace: .current(),
-        sourceLocation: SourceLocation(fileID: fileID, filePath: filePath, line: line, column: column)
+        sourceLocation: sourceLocation
       )
     }
   }

Sources/Testing/Issues/Issue+Recording.swift

@@ -99,6 +99,8 @@ extension Issue {
   ///
   /// - Parameters:
   ///   - comment: A comment describing the expectation.
+  ///   - sourceLocation: The source location to which the issue should be
+  ///     attributed.
   ///
   /// - Returns: The issue that was recorded.
   ///
@@ -107,12 +109,8 @@ extension Issue {
   /// or ``require(_:_:sourceLocation:)-5l63q`` macros.)
   @discardableResult public static func record(
     _ comment: Comment? = nil,
-    fileID: String = #fileID,
-    filePath: String = #filePath,
-    line: Int = #line,
-    column: Int = #column
+    sourceLocation: SourceLocation = #_sourceLocation
   ) -> Self {
-    let sourceLocation = SourceLocation(fileID: fileID, filePath: filePath, line: line, column: column)
     let sourceContext = SourceContext(backtrace: .current(), sourceLocation: sourceLocation)
     let issue = Issue(kind: .unconditional, comments: Array(comment), sourceContext: sourceContext)
     return issue.record()
@@ -127,6 +125,8 @@ extension Issue {
   /// - Parameters:
   ///   - error: The error that caused the issue.
   ///   - comment: A comment describing the expectation.
+  ///   - sourceLocation: The source location to which the issue should be
+  ///     attributed.
   ///
   /// - Returns: The issue that was recorded.
   ///
@@ -137,12 +137,8 @@ extension Issue {
   @discardableResult public static func record(
     _ error: any Error,
     _ comment: Comment? = nil,
-    fileID: String = #fileID,
-    filePath: String = #filePath,
-    line: Int = #line,
-    column: Int = #column
+    sourceLocation: SourceLocation = #_sourceLocation
   ) -> Self {
-    let sourceLocation = SourceLocation(fileID: fileID, filePath: filePath, line: line, column: column)
     let backtrace = Backtrace(forFirstThrowOf: error) ?? Backtrace.current()
     let sourceContext = SourceContext(backtrace: backtrace, sourceLocation: sourceLocation)
     let issue = Issue(kind: .errorCaught(error), comments: Array(comment), sourceContext: sourceContext)

Sources/Testing/Issues/Issue.swift

@@ -13,7 +13,7 @@ public struct Issue: Sendable {
   /// Kinds of issues which may be recorded.
   public enum Kind: Sendable {
     /// An issue which occurred unconditionally, for example by using
-    /// ``Issue/record(_:fileID:filePath:line:column:)``.
+    /// ``Issue/record(_:sourceLocation:)``.
     case unconditional
 
     /// An issue due to a failed expectation, such as those produced by
@@ -33,9 +33,9 @@ public struct Issue: Sendable {
     ///     ``Confirmation/confirm(count:)`` should have been called.
     ///
     /// This issue can occur when calling
-    /// ``confirmation(_:expectedCount:fileID:filePath:line:column:_:)`` when
-    /// the confirmation passed to these functions' `body` closures is confirmed
-    /// too few or too many times.
+    /// ``confirmation(_:expectedCount:sourceLocation:_:)`` when the
+    /// confirmation passed to these functions' `body` closures is confirmed too
+    /// few or too many times.
     indirect case confirmationMiscounted(actual: Int, expected: Int)
 
     /// An issue due to an `Error` being thrown by a test function and caught by
@@ -235,7 +235,7 @@ extension Issue.Kind {
   @_spi(ForToolsIntegrationOnly)
   public enum Snapshot: Sendable, Codable {
     /// An issue which occurred unconditionally, for example by using
-    /// ``Issue/record(_:fileID:filePath:line:column:)``.
+    /// ``Issue/record(_:sourceLocation:)``.
     case unconditional
 
     /// An issue due to a failed expectation, such as those produced by
@@ -255,9 +255,9 @@ extension Issue.Kind {
     ///     ``Confirmation/confirm(count:)`` should have been called.
     ///
     /// This issue can occur when calling
-    /// ``confirmation(_:expectedCount:fileID:filePath:line:column:_:)`` when
-    /// the confirmation passed to these functions' `body` closures is confirmed
-    /// too few or too many times.
+    /// ``confirmation(_:expectedCount:sourceLocation:_:)`` when the
+    /// confirmation passed to these functions' `body` closures is confirmed too
+    /// few or too many times.
     indirect case confirmationMiscounted(actual: Int, expected: Int)
 
     /// An issue due to an `Error` being thrown by a test function and caught by