Include code comments before expectations which are preceded by try/await in recorded issues (#1092)

This fixes an issue where code comments placed before an expectation
like `#expect()` which has effect introducer keywords like `try` or
`await` are ignored, and ensures they are included in the recorded issue
if the expectation fails.

Consider this example of two failing expectations:

```swift
// Uh oh!
#expect(try x() == 2)

// Uh oh!
try #expect(x() == 2)
```

Prior to this PR, if `x()` returned a value other than `2`, there would
be two issues recorded, but the second one would not have the comment
`“Uh oh!”` because from the macro’s perspective, that code comment was
on the `try` keyword and it could only see trivia associated with
`#expect()`.

Now, with the recent swift-syntax fix from
swiftlang/swift-syntax#3037, the `try` keyword
and its associated trivia can be included and this bug can be fixed. We
recently adopted a new-enough swift-syntax in #1069, so the only fix
needed is to adopt `lexicalContext` for this new purpose in our macro.

### 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/TestingMacros/ConditionMacro.swift

@@ -157,8 +157,17 @@ extension ConditionMacro {
         expandedFunctionName = conditionArgument.expandedFunctionName
       }
 
-      // Capture any comments as well (either in source or as a macro argument.)
+      // Capture any comments as well -- either in source, preceding the
+      // expression macro or one of its lexical context nodes, or as an argument
+      // to the macro.
       let commentsArrayExpr = ArrayExprSyntax {
+        // Lexical context is ordered innermost-to-outermost, so reverse it to
+        // maintain the expected order.
+        for lexicalSyntaxNode in context.lexicalContext.trailingEffectExpressions.reversed() {
+          for commentTraitExpr in createCommentTraitExprs(for: lexicalSyntaxNode) {
+            ArrayElementSyntax(expression: commentTraitExpr)
+          }
+        }
         for commentTraitExpr in createCommentTraitExprs(for: macro) {
           ArrayElementSyntax(expression: commentTraitExpr)
         }

Sources/TestingMacros/Support/EffectfulExpressionHandling.swift

@@ -12,7 +12,7 @@ import SwiftSyntax
 import SwiftSyntaxBuilder
 import SwiftSyntaxMacros
 
-// MARK: - Finding effect keywords
+// MARK: - Finding effect keywords and expressions
 
 /// A syntax visitor class that looks for effectful keywords in a given
 /// expression.
@@ -69,6 +69,21 @@ func findEffectKeywords(in node: some SyntaxProtocol, context: some MacroExpansi
   return effectFinder.effectKeywords
 }
 
+extension BidirectionalCollection<Syntax> {
+  /// The suffix of syntax nodes in this collection which are effectful
+  /// expressions, such as those for `try` or `await`.
+  var trailingEffectExpressions: some Collection<Syntax> {
+    reversed()
+      .prefix { node in
+        // This could be simplified if/when swift-syntax introduces a protocol
+        // which all effectful expression syntax node types conform to.
+        // See https://github.com/swiftlang/swift-syntax/issues/3040
+        node.is(TryExprSyntax.self) || node.is(AwaitExprSyntax.self) || node.is(UnsafeExprSyntax.self)
+      }
+      .reversed()
+  }
+}
+
 // MARK: - Inserting effect keywords/thunks
 
 /// Make a function call expression to an effectful thunk function provided by

Tests/TestingMacrosTests/ConditionMacroTests.swift

@@ -240,6 +240,59 @@ struct ConditionMacroTests {
       // Capture me
       Testing.__checkValue(try x(), expression: .__fromSyntaxNode("try x()"), comments: [.__line("// Capture me")], isRequired: false, sourceLocation: Testing.SourceLocation.__here()).__expected()
       """,
+
+      """
+      // Capture me
+      try #expect(x)
+      """:
+      """
+      // Capture me
+      try Testing.__checkValue(x, expression: .__fromSyntaxNode("x"), comments: [.__line("// Capture me")], isRequired: false, sourceLocation: Testing.SourceLocation.__here()).__expected()
+      """,
+
+      """
+      // Capture me
+      await #expect(x)
+      """:
+      """
+      // Capture me
+      await Testing.__checkValue(x, expression: .__fromSyntaxNode("x"), comments: [.__line("// Capture me")], isRequired: false, sourceLocation: Testing.SourceLocation.__here()).__expected()
+      """,
+
+      """
+      // Ignore me
+
+      // Comment for try
+      try
+      // Comment for await
+      await
+      // Comment for expect
+      #expect(x)
+      """:
+      """
+      // Comment for try
+      try
+      // Comment for await
+      await
+      // Comment for expect
+      Testing.__checkValue(x, expression: .__fromSyntaxNode("x"), comments: [.__line("// Comment for try"), .__line("// Comment for await"), .__line("// Comment for expect")], isRequired: false, sourceLocation: Testing.SourceLocation.__here()).__expected()
+      """,
+
+      """
+      // Ignore me
+      func example() {
+        // Capture me
+        #expect(x())
+      }
+      """:
+      """
+      func example() {
+        // Capture me
+        Testing.__checkFunctionCall((), calling: { _ in
+          x()
+        }, expression: .__fromFunctionCall(nil, "x"), comments: [.__line("// Capture me")], isRequired: false, sourceLocation: Testing.SourceLocation.__here()).__expected()
+      }
+      """,
     ]
   )
   func commentCapture(input: String, expectedOutput: String) throws {