Merge pull request swiftlang#2539 from bnbarham/add-introducer

Add an introducer property to DeclGroupSyntax

Author: bnbarham

CodeGeneration/Sources/SyntaxSupport/Traits.swift

@@ -47,6 +47,11 @@ public let TRAITS: [Trait] = [
     children: [
       Child(name: "attributes", kind: .node(kind: .attributeList)),
       Child(name: "modifiers", kind: .node(kind: .declModifierList)),
+      Child(
+        name: "introducer",
+        kind: .token(choices: [.keyword(.actor), .keyword(.class), .keyword(.enum), .keyword(.extension), .keyword(.protocol), .keyword(.struct)]),
+        documentation: "The token that introduces this declaration, eg. `class` for a class declaration."
+      ),
       Child(name: "inheritanceClause", kind: .node(kind: .inheritanceClause), isOptional: true),
       Child(
         name: "genericWhereClause",

Release Notes/600.md

@@ -35,7 +35,7 @@
 - `String.isValidIdentifier(for:)`
   - 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
-    
+
 - `MacroDeclSyntax.expand`
   - the `expand(argumentList:definition:replacements:)` method gains a new parameter 'genericReplacements:' that is defaulted to an empty array.
   - The method's signature is now `expand(argumentList:definition:replacements:genericReplacements:)`
@@ -65,11 +65,16 @@
 - Type specifiers
   - Description: `AttributedTypeSyntax` can now contain multiple specifiers and these types are used to model the list of specifiers. Additionally, type specifiers can now contain arguments, like `borrow(data)`. To facilitate this, the following new types were introduces: `LifetimeSpecifierArgumentListSyntax`, `LifetimeSpecifierArgumentSyntax`, `LifetimeSpecifierArgumentsSyntax`, `LifetimeTypeSpecifierSyntax`, `SimpleTypeSpecifierSyntax`, `TypeSpecifierListSyntax`
   - Pull request: https://github.com/apple/swift-syntax/pull/2433
-  
+
+- `DeclGroupSyntax.introducer`
+  - Description: The `DeclGroupSyntax` trait has an extra `introducer` property, ie. the keyword that introduces the declaration.
+  - Issue: https://github.com/apple/sourcekit-lsp/issues/2535
+  - Pull Request: https://github.com/apple/swift-syntax/pull/2539
+
 ## API Behavior Changes
 
 ## Deprecations
-  
+
 - Child Choice Node Casts
   - Description: `is`, `as`, and `cast` methods for types not contained in the choice node are marked as deprecated. The deprecated methods will emit a warning, indicating that the cast will always fail.
   - Issue: https://github.com/apple/swift-syntax/issues/2092
@@ -85,7 +90,7 @@
 - `MacroExpansion{Error|Warning|FixIt}Message` moved to the `SwiftSyntaxMacros` module
   - Description: Move the `MacroExpansion{Error|Warning|FixIt}Message` types from the `SwiftSyntaxMacroExpansion` module to `SwiftSyntaxMacros`. Deprecated typealiases in `SwiftSyntaxMacroExpansion` forward to `SwiftSyntaxMacros`.
   - Pull request: https://github.com/apple/swift-syntax/pull/2338
-  - Notes: The expansion diagnostic messages were defined in `SwiftSyntaxMacroExpansion`, which is intended as an implementation detail of the plugin server and should not need to be imported by macros.  
+  - Notes: The expansion diagnostic messages were defined in `SwiftSyntaxMacroExpansion`, which is intended as an implementation detail of the plugin server and should not need to be imported by macros.
 
 - `EditorPlaceholderDeclSyntax` and `EditorPlaceholderExprSyntax`:
   - Description: `EditorPlaceholderDeclSyntax` and `EditorPlaceholderExprSyntax` are now deprecated and placeholders are instead parsed as identifiers within a `MissingDeclSyntax` or `DeclReferenceExprSyntax`.
@@ -105,15 +110,15 @@
 - Effect specifiers:
   - Description: The `unexpectedAfterThrowsSpecifier` node of the various effect specifiers has been removed.
   - Pull request: https://github.com/apple/swift-syntax/pull/2219
-  - Migration steps: Check `unexpectedBetweenThrowsSpecifierAndThrownError` and `unexpectedAfterThrownError` instead. 
+  - Migration steps: Check `unexpectedBetweenThrowsSpecifierAndThrownError` and `unexpectedAfterThrownError` instead.
 
 - `SyntaxKind` removed conformance to `CaseIterable`
-  - Description: `SyntaxKind` no longer conforms to `CaseIterable` since there is no good use case to iterate over all syntax kinds. 
-  - Pull request: https://github.com/apple/swift-syntax/pull/2292 
+  - Description: `SyntaxKind` no longer conforms to `CaseIterable` since there is no good use case to iterate over all syntax kinds.
+  - Pull request: https://github.com/apple/swift-syntax/pull/2292
   - Migration steps: Exhaustively check all the syntax nodes that your program supports. There should be no use case to iterate over all cases in `SyntaxKind`.
 
 - `IntegerLiteralExprSyntax.Radix` removed conformance to `CaseIterable`
-  - Description: `IntegerLiteralExprSyntax.Radix` no longer conforms to `CaseIterable` since there is no good use case to iterate over all radix kinds. 
+  - Description: `IntegerLiteralExprSyntax.Radix` no longer conforms to `CaseIterable` since there is no good use case to iterate over all radix kinds.
   - Pull request: https://github.com/apple/swift-syntax/pull/2292
   - Migration steps: There should be no use case to iterate over all cases in `IntegerLiteralExprSyntax.Radix`.
 
@@ -127,7 +132,7 @@
   - The new classification case covers the first names of parameters in function-like declarations and the label of arguments in function-like calls.
   - Pull request: https://github.com/apple/swift-syntax/pull/2375
   - Migration steps: In exhaustive switches over `SyntaxClassification`, cover the new case.
-  
+
 - `SyntaxEnum` and `SyntaxKind` gained new cases: `throwsClause`
   - The new cases cover the newly introduced `ThrowsClauseSyntax`
   - Pull request: https://github.com/apple/swift-syntax/pull/2379
@@ -137,10 +142,10 @@
   - 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.
-  
+
 - `TriviaPiece.isBackslash` in `SwiftParserDiagnostics` removed
   - Description: `TriviaPiece.isBackslash` was not intended to be public API.
-  - Pull request: xxx
+  - Pull request: https://github.com/apple/swift-syntax/pull/2531
   - Migration steps: Use `if case .backslash = triviaPiece` instead
 
 ## Template

Sources/SwiftSyntax/CMakeLists.txt

@@ -14,6 +14,7 @@ add_swift_syntax_library(SwiftSyntax
   BumpPtrAllocator.swift
   CommonAncestor.swift
   Convenience.swift
+  CustomTraits.swift
   MemoryLayout.swift
   MissingNodeInitializers.swift
   SourceEdit.swift

Sources/SwiftSyntax/CustomTraits.swift

@@ -0,0 +1,82 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2024 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 the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+extension ActorDeclSyntax {
+  public var introducer: TokenSyntax {
+    get {
+      return actorKeyword
+    }
+    set {
+      actorKeyword = newValue
+    }
+  }
+}
+
+extension ClassDeclSyntax {
+  public var introducer: TokenSyntax {
+    get {
+      return classKeyword
+    }
+    set {
+      classKeyword = newValue
+    }
+  }
+}
+
+extension EnumDeclSyntax {
+  public var introducer: TokenSyntax {
+    get {
+      return enumKeyword
+    }
+    set {
+      enumKeyword = newValue
+    }
+  }
+}
+
+extension ExtensionDeclSyntax {
+  public var introducer: TokenSyntax {
+    get {
+      return extensionKeyword
+    }
+    set {
+      extensionKeyword = newValue
+    }
+  }
+}
+
+extension ProtocolDeclSyntax {
+  public var introducer: TokenSyntax {
+    get {
+      return protocolKeyword
+    }
+    set {
+      protocolKeyword = newValue
+    }
+  }
+}
+
+extension StructDeclSyntax {
+  public var introducer: TokenSyntax {
+    get {
+      return structKeyword
+    }
+    set {
+      structKeyword = newValue
+    }
+  }
+}
+
+//==========================================================================//
+// IMPORTANT: If you are tempted to add an extension here, please insert    //
+// it in alphabetical order above                                           //
+//==========================================================================//

Sources/SwiftSyntax/generated/SyntaxTraits.swift

@@ -72,6 +72,22 @@ public protocol DeclGroupSyntax: SyntaxProtocol, DeclSyntaxProtocol {
     set
   }
 
+  /// The token that introduces this declaration, eg. `class` for a class declaration.
+  ///
+  /// ### Tokens
+  /// 
+  /// For syntax trees generated by the parser, this is guaranteed to be one of the following kinds:
+  ///  - `actor`
+  ///  - `class`
+  ///  - `enum`
+  ///  - `extension`
+  ///  - `protocol`
+  ///  - `struct`
+  var introducer: TokenSyntax {
+    get
+    set
+  }
+  
   var inheritanceClause: InheritanceClauseSyntax? {
     get
     set