Diagnose when we incorrectly infer the type of a capture list item in an exit test. (#1152)

Follow-up to #1130, split out for clarity.

This PR adds a custom diagnostic at compile time if we incorrectly infer
the type of a captured function argument or `self` in an exit test. For
example:

```swift
func f(_ x: Int) async {
  let x = String(x) // local type of 'x' is String, not Int
  await #expect(processExitsWith: ...) { [x] in
    ...
  }
}
```

This improves our feedback to the developer when we encounter a pattern
like that. The developer will now see:

> 🛑 Type of captured value 'x' is ambiguous

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

Sources/Testing/Expectations/Expectation+Macro.swift

@@ -580,6 +580,7 @@ public macro require(
 /// - Parameters:
 ///   - value: The captured value.
 ///   - name: The name of the capture list item corresponding to `value`.
+///   - expectedType: The type of `value`.
 ///
 /// - Returns: `value` verbatim.
 ///
@@ -588,7 +589,8 @@ public macro require(
 @freestanding(expression)
 public macro __capturedValue<T>(
   _ value: T,
-  _ name: String
+  _ name: String,
+  _ expectedType: T.Type
 ) -> T = #externalMacro(module: "TestingMacros", type: "ExitTestCapturedValueMacro") where T: Sendable & Codable
 
 /// Emit a compile-time diagnostic when an unsupported value is captured by an
@@ -597,6 +599,7 @@ public macro __capturedValue<T>(
 /// - Parameters:
 ///   - value: The captured value.
 ///   - name: The name of the capture list item corresponding to `value`.
+///   - expectedType: The type of `value`.
 ///
 /// - Returns: The result of a call to `fatalError()`. `value` is discarded at
 ///   compile time.
@@ -606,5 +609,27 @@ public macro __capturedValue<T>(
 @freestanding(expression)
 public macro __capturedValue<T>(
   _ value: borrowing T,
-  _ name: String
+  _ name: String,
+  _ expectedType: T.Type
 ) -> Never = #externalMacro(module: "TestingMacros", type: "ExitTestBadCapturedValueMacro") where T: ~Copyable & ~Escapable
+
+/// Emit a compile-time diagnostic when a value is captured by an exit test but
+/// we inferred the wrong type.
+///
+/// - Parameters:
+///   - value: The captured value.
+///   - name: The name of the capture list item corresponding to `value`.
+///   - expectedType: The _expected_ type of `value`, which will differ from the
+///     _actual_ type of `value`.
+///
+/// - Returns: The result of a call to `fatalError()`. `value` is discarded at
+///   compile time.
+///
+/// - Warning: This macro is used to implement the `#expect(processExitsWith:)`
+///   macro. Do not use it directly.
+@freestanding(expression)
+public macro __capturedValue<T, U>(
+  _ value: borrowing T,
+  _ name: String,
+  _ expectedType: U.Type
+) -> T = #externalMacro(module: "TestingMacros", type: "ExitTestIncorrectlyCapturedValueMacro") where T: ~Copyable & ~Escapable, U: ~Copyable & ~Escapable

Sources/TestingMacros/ExitTestCapturedValueMacro.swift

@@ -8,6 +8,7 @@
 // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 //
 
+import SwiftParser
 public import SwiftSyntax
 import SwiftSyntaxBuilder
 public import SwiftSyntaxMacros
@@ -52,3 +53,26 @@ public struct ExitTestBadCapturedValueMacro: ExpressionMacro, Sendable {
     return #"Swift.fatalError("Unsupported")"#
   }
 }
+
+/// The implementation of the `#__capturedValue()` macro when the type we
+/// inferred for the value was incorrect.
+///
+/// This type is used to implement the `#__capturedValue()` macro. Do not use it
+/// directly.
+public struct ExitTestIncorrectlyCapturedValueMacro: ExpressionMacro, Sendable {
+  public static func expansion(
+    of macro: some FreestandingMacroExpansionSyntax,
+    in context: some MacroExpansionContext
+  ) throws -> ExprSyntax {
+    let arguments = Array(macro.arguments)
+    let expr = arguments[0].expression
+    let nameExpr = arguments[1].expression.cast(StringLiteralExprSyntax.self)
+
+    // Diagnose that the type of 'expr' is invalid.
+    let name = nameExpr.representedLiteralValue ?? expr.trimmedDescription
+    let capture = ClosureCaptureSyntax(name: .identifier(name))
+    context.diagnose(.typeOfCaptureIsAmbiguous(capture))
+
+    return expr
+  }
+}

Sources/TestingMacros/Support/ClosureCaptureListParsing.swift

@@ -36,7 +36,7 @@ struct CapturedValueInfo {
 
   /// The expression to assign to the captured value with type-checking applied.
   var typeCheckedExpression: ExprSyntax {
-    #"#__capturedValue(\#(expression.trimmed), \#(literal: name.trimmedDescription))"#
+    #"#__capturedValue(\#(expression.trimmed), \#(literal: name.trimmedDescription), (\#(type.trimmed)).self)"#
   }
 
   init(_ capture: ClosureCaptureSyntax, in context: some MacroExpansionContext) {

Sources/TestingMacros/TestingMacrosMain.swift

@@ -30,6 +30,7 @@ struct TestingMacrosMain: CompilerPlugin {
       ExitTestRequireMacro.self,
       ExitTestCapturedValueMacro.self,
       ExitTestBadCapturedValueMacro.self,
+      ExitTestIncorrectlyCapturedValueMacro.self,
       TagMacro.self,
       SourceLocationMacro.self,
       PragmaMacro.self,

Tests/TestingTests/ExitTestTests.swift

@@ -479,12 +479,16 @@ private import _TestingInternals
       }
     }(i)
 
+#if false // intentionally fails to compile
     // FAILS TO COMPILE: shadowing `i` with a variable of a different type will
     // prevent correct expansion (we need an equivalent of decltype() for that.)
-//    let i = String(i)
-//    await #expect(processExitsWith: .success) { [i] in
-//      #expect(!i.isEmpty)
-//    }
+    func g(i: Int) async {
+      let i = String(i)
+      await #expect(processExitsWith: .success) { [i] in
+        #expect(!i.isEmpty)
+      }
+    }
+#endif
   }
 
   @Test("Capturing a literal expression")