Address code review and update release notes

Author: DougGregor

Release Notes/511.md

@@ -36,6 +36,10 @@
   - Description: `SwiftParser` adds an extension on `String` to check if it can be used as an identifier in a given context.
   - Pull Request: https://github.com/apple/swift-syntax/pull/2434
 
+- `SyntaxProtocol.asMacroLexicalContext()` and `allMacroLexicalContexts(enclosingSyntax:)`
+  - Description: Produce the lexical context for a given syntax node (if it has one), or the entire stack of lexical contexts enclosing a syntax node, for use in macro expansion.
+  - Pull request: https://github.com/apple/swift-syntax/pull/1554
+
 ## API Behavior Changes
 
 ## Deprecations
@@ -93,6 +97,11 @@
   - The new cases cover the newly introduced `ThrowsClauseSyntax`
   - Pull request: https://github.com/apple/swift-syntax/pull/2379
   - Migration steps: In exhaustive switches over `SyntaxEnum` and `SyntaxKind`, cover the new case.
+
+- `MacroExpansionContext` now requires a property `lexicalContext`:
+  - Description: The new property provides the lexical context in which the macro is expanded, and has several paired API changes. Types that conform to `MacroExpansionContext` will need to implement this property. Additionally, the `HostToPluginMessage` cases `expandFreestandingMacro` and `expandAttachedMacro` now include an optional `lexicalContext`. Finally, the `SyntaxProtocol.expand(macros:in:indentationWidth:)` syntactic expansion operation has been deprecated in favor of a new version `expand(macros:contextGenerator:indentationWidth:)` that takes a function produces a new macro expansion context for each expansion.
+  - Pull request: https://github.com/apple/swift-syntax/pull/1554
+  - Migration steps: Add the new property `lexicalContext` to any `MacroExpansionContext`-conforming types. If implementing the host-to-plugin message protocol, add support for `lexicalContext`. For macro expansion operations going through `SyntaxProtocol.expand`, provide a context generator that creates a fresh context including the lexical context.
 
 
 ## Template

Sources/SwiftCompilerPluginMessageHandling/PluginMessages.swift

@@ -24,7 +24,7 @@ public enum HostToPluginMessage: Codable {
     macroRole: PluginMessage.MacroRole? = nil,
     discriminator: String,
     syntax: PluginMessage.Syntax,
-    lexicalContext: [PluginMessage.Syntax]?
+    lexicalContext: [PluginMessage.Syntax]? = nil
   )
 
   /// Expand an '@attached' macro.
@@ -37,7 +37,7 @@ public enum HostToPluginMessage: Codable {
     parentDeclSyntax: PluginMessage.Syntax?,
     extendedTypeSyntax: PluginMessage.Syntax?,
     conformanceListSyntax: PluginMessage.Syntax?,
-    lexicalContext: [PluginMessage.Syntax]?
+    lexicalContext: [PluginMessage.Syntax]? = nil
   )
 
   /// Optionally implemented message to load a dynamic link library.

Sources/SwiftSyntaxMacroExpansion/BasicMacroExpansionContext.swift

@@ -73,7 +73,7 @@ public class BasicMacroExpansionContext {
 
   /// Create a new macro evaluation context.
   public init(
-    lexicalContext: [Syntax],
+    lexicalContext: [Syntax] = [],
     expansionDiscriminator: String = "__macro_local_",
     sourceFiles: [SourceFileSyntax: KnownSourceFile] = [:]
   ) {

Sources/SwiftSyntaxMacros/MacroExpansionContext.swift

@@ -59,8 +59,10 @@ public protocol MacroExpansionContext: AnyObject {
   /// member lists emptied, and properties and subscripts have their accessor
   /// blocks removed.
   ///
-  /// The first entry in the array is the innermost context, which could be
-  /// the syntax node to which
+  /// The first entry in the array is the innermost context. For attached
+  /// macros, this is often the declaration to which the macro is attached.
+  /// This array can be empty if there is no context, for example when a
+  /// freestanding macro is used at file scope.
   var lexicalContext: [Syntax] { get }
 }
 

Sources/SwiftSyntaxMacrosTestSupport/Assertions.swift

@@ -322,7 +322,6 @@ public func assertMacroExpansion(
 
   // Expand all macros in the source.
   let context = BasicMacroExpansionContext(
-    lexicalContext: /*FIXME:*/ [],
     sourceFiles: [origSourceFile: .init(moduleName: testModuleName, fullFilePath: testFileName)]
   )
 

Tests/SwiftSyntaxMacroExpansionTest/LexicalContextTests.swift

@@ -65,8 +65,7 @@ extension SyntaxProtocol {
   /// Form a function name.
   private func formFunctionName(
     _ baseName: String,
-    _ parameters: FunctionParameterClauseSyntax?,
-    isSubscript: Bool = false
+    _ parameters: FunctionParameterClauseSyntax?
   ) -> String {
     let argumentNames: [String] =
       parameters?.parameters.map { param in
@@ -97,8 +96,7 @@ extension SyntaxProtocol {
     if let subscriptDecl = self.as(SubscriptDeclSyntax.self) {
       return formFunctionName(
         "subscript",
-        subscriptDecl.parameterClause,
-        isSubscript: true
+        subscriptDecl.parameterClause
       )
     }
 
@@ -193,14 +191,19 @@ final class LexicalContextTests: XCTestCase {
       func f(a: Int, _: Double, c: Int) {
         print(#function)
       }
-
-      struct X {
-        var computed: String {
-          get {
-            #function
-          }
+      """,
+      expandedSource: """
+        func f(a: Int, _: Double, c: Int) {
+          print(  "f(a:_:c:)")
         }
+        """,
+      macros: ["function": FunctionMacro.self],
+      indentationWidth: indentationWidth
+    )
 
+    assertMacroExpansion(
+      """
+      struct X {
         init(from: String) {
           #function
         }
@@ -213,23 +216,9 @@ final class LexicalContextTests: XCTestCase {
           #function
         }
       }
-
-      extension A {
-        static var staticProp: String = #function
-      }
       """,
       expandedSource: """
-        func f(a: Int, _: Double, c: Int) {
-          print(  "f(a:_:c:)")
-        }
-
         struct X {
-          var computed: String {
-            get {
-              "computed"
-            }
-          }
-
           init(from: String) {
             "init(from:)"
           }
@@ -242,7 +231,37 @@ final class LexicalContextTests: XCTestCase {
             "subscript(a:)"
           }
         }
+        """,
+      macros: ["function": FunctionMacro.self],
+      indentationWidth: indentationWidth
+    )
 
+    assertMacroExpansion(
+      """
+      var computed: String {
+        get {
+          #function
+        }
+      }
+      """,
+      expandedSource: """
+        var computed: String {
+          get {
+            "computed"
+          }
+        }
+        """,
+      macros: ["function": FunctionMacro.self],
+      indentationWidth: indentationWidth
+    )
+
+    assertMacroExpansion(
+      """
+      extension A {
+        static var staticProp: String = #function
+      }
+      """,
+      expandedSource: """
         extension A {
           static var staticProp: String =   "staticProp"
         }
@@ -294,5 +313,9 @@ final class LexicalContextTests: XCTestCase {
         """,
       macros: ["allLexicalContexts": AllLexicalContextsMacro.self]
     )
+
+    // Test closures separately, because they don't fit as declaration macros.
+    let closure: ExprSyntax = "{ (a, b) in print(a + b) }"
+    XCTAssertEqual(closure.asMacroLexicalContext()!.description, "{ (a, b) in }")
   }
 }