Introduce DeclGroupHeaderSyntax

This is the base node for the headers we are about to extract.

Unlike other base nodes, DeclGroupHeaderSyntax has children, which are treated as protocol requirements for derived nodes.

Author: beccadax

CodeGeneration/Sources/SyntaxSupport/CommonNodes.swift

@@ -180,13 +180,98 @@ public let COMMON_NODES: [Node] = [
     parserFunction: "parseDeclaration"
   ),
 
+  Node(
+    kind: .declGroupHeader,
+    base: .syntax,
+    nameForDiagnostics: "declaration group header",
+    parserFunction: "parseDeclarationGroupHeader",
+    traits: [
+      "WithAttributes",
+      "WithModifiers",
+    ],
+    children: [
+      Child(
+        name: "attributes",
+        kind: .collection(kind: .attributeList, collectionElementName: "Attribute", defaultsToEmpty: true),
+        nameForDiagnostics: "attributes"
+      ),
+      Child(
+        name: "modifiers",
+        kind: .collection(kind: .declModifierList, collectionElementName: "Modifier", defaultsToEmpty: true),
+        nameForDiagnostics: "modifiers",
+        documentation: "Modifiers like `public` that are attached to the actor declaration."
+      ),
+      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",
+        kind: .node(kind: .genericWhereClause),
+        documentation:
+          "A `where` clause that places additional constraints on generic parameters like `where Element: Hashable`.",
+        isOptional: true
+      ),
+    ]
+  ),
+
   Node(
     kind: .expr,
     base: .syntax,
     nameForDiagnostics: "expression",
     parserFunction: "parseExpression"
   ),
 
+  Node(
+    kind: .missingDeclHeader,
+    base: .declGroupHeader,
+    nameForDiagnostics: "declaration group header",
+    documentation:
+      "In case the source code is missing a declaration group header, this node stands in place of the missing header.",
+    traits: [
+      "MissingNode",
+      "WithAttributes",
+      "WithModifiers",
+    ],
+    children: [
+      Child(
+        name: "attributes",
+        kind: .collection(kind: .attributeList, collectionElementName: "Attribute", defaultsToEmpty: true),
+        documentation:
+          "If there were standalone attributes without a declaration to attach them to, the ``MissingDeclSyntax`` will contain these."
+      ),
+      Child(
+        name: "modifiers",
+        kind: .collection(kind: .declModifierList, collectionElementName: "Modifier", defaultsToEmpty: true),
+        documentation:
+          "If there were standalone modifiers without a declaration to attach them to, the ``MissingDeclSyntax`` will contain these."
+      ),
+      Child(
+        name: "placeholder",
+        kind: .token(choices: [.token(.identifier)], requiresLeadingSpace: false, requiresTrailingSpace: false),
+        documentation: """
+          A placeholder, i.e. `<#decl#>`, that can be inserted into the source code to represent the missing declaration.
+
+          This token should always have `presence = .missing`.
+          """
+      ),
+      Child(name: "inheritanceClause", kind: .node(kind: .inheritanceClause), isOptional: true),
+      Child(
+        name: "genericWhereClause",
+        kind: .node(kind: .genericWhereClause),
+        documentation:
+          "A `where` clause that places additional constraints on generic parameters like `where Element: Hashable`.",
+        isOptional: true
+      ),
+
+    ]
+  ),
+
   Node(
     kind: .missingDecl,
     base: .decl,

CodeGeneration/Sources/SyntaxSupport/CompatibilityLayers.swift

@@ -68,7 +68,7 @@ public struct CompatibilityLayers /*: Sendable*/ {
       typeName: layoutNode.kind.rawValue,
       initialChildren: layoutNode.children,
       history: layoutNode.childHistory,
-      areRequirements: false
+      areRequirements: layoutNode.kind.isBase
     )
 
     deprecatedVarsByNode[node.syntaxNodeKind] = result.vars

CodeGeneration/Sources/SyntaxSupport/Node.swift

@@ -69,11 +69,7 @@ public class Node: NodeChoiceConvertible {
   public var layoutNode: LayoutNode? {
     switch data {
     case .layout:
-      if kind.isBase {
-        return nil
-      } else {
-        return LayoutNode(node: self)
-      }
+      return LayoutNode(node: self)
     default:
       return nil
     }
@@ -136,11 +132,7 @@ public class Node: NodeChoiceConvertible {
     self.documentation = SwiftSyntax.Trivia.docCommentTrivia(from: documentation)
     self.parserFunction = parserFunction
 
-    let liftedChildren = children.lazy.map(Optional.some)
-    let pairedChildren = zip([nil] + liftedChildren, liftedChildren + [nil])
-    let childrenWithUnexpected = pairedChildren.flatMap { earlier, later in
-      [earlier, Child(forUnexpectedBetween: earlier, and: later)].compactMap { $0 }
-    }
+    let childrenWithUnexpected = kind.isBase ? children : interleaveUnexpectedChildren(children)
 
     self.data = .layout(children: childrenWithUnexpected, childHistory: childHistory, traits: traits)
   }
@@ -389,3 +381,12 @@ fileprivate extension Child {
     }
   }
 }
+
+fileprivate func interleaveUnexpectedChildren(_ children: [Child]) -> [Child] {
+  let liftedChildren = children.lazy.map(Optional.some)
+  let pairedChildren = zip([nil] + liftedChildren, liftedChildren + [nil])
+
+  return pairedChildren.flatMap { earlier, later in
+    [earlier, Child(forUnexpectedBetween: earlier, and: later)].compactMap { $0 }
+  }
+}

CodeGeneration/Sources/SyntaxSupport/SyntaxNodeKind.swift

@@ -81,6 +81,7 @@ public enum SyntaxNodeKind: String, CaseIterable, IdentifierConvertible, TypeCon
   case conventionWitnessMethodAttributeArguments
   case copyExpr
   case decl
+  case declGroupHeader
   case declModifier
   case declModifierDetail
   case declModifierList
@@ -197,6 +198,7 @@ public enum SyntaxNodeKind: String, CaseIterable, IdentifierConvertible, TypeCon
   case metatypeType
   case missing
   case missingDecl
+  case missingDeclHeader
   case missingExpr
   case missingPattern
   case missingStmt
@@ -320,7 +322,7 @@ public enum SyntaxNodeKind: String, CaseIterable, IdentifierConvertible, TypeCon
   /// `true` if this is one of the `missing*` cases.
   public var isMissing: Bool {
     switch self {
-    case .missingDecl, .missingExpr, .missingPattern, .missingStmt, .missing, .missingType:
+    case .missingDecl, .missingDeclHeader, .missingExpr, .missingPattern, .missingStmt, .missing, .missingType:
       return true
     default:
       return false
@@ -329,7 +331,7 @@ public enum SyntaxNodeKind: String, CaseIterable, IdentifierConvertible, TypeCon
 
   public var isBase: Bool {
     switch self {
-    case .decl, .expr, .pattern, .stmt, .syntax, .syntaxCollection, .type:
+    case .decl, .declGroupHeader, .expr, .pattern, .stmt, .syntax, .syntaxCollection, .type:
       return true
     default:
       return false
@@ -351,6 +353,15 @@ public enum SyntaxNodeKind: String, CaseIterable, IdentifierConvertible, TypeCon
     }
   }
 
+  public var baseTypeSuffix: String? {
+    switch self {
+    case .declGroupHeader:
+      return "DeclHeaderSyntax"
+    default:
+      return isBase ? syntaxType.description : nil
+    }
+  }
+
   public var isAvailableInDocc: Bool {
     if let node = SYNTAX_NODE_MAP[self], node.isExperimental {
       return false

CodeGeneration/Sources/generate-swift-syntax/templates/swiftsyntax/RawSyntaxNodesFile.swift

@@ -142,7 +142,7 @@ func rawSyntaxNodesFile(nodesStartingWith: [Character]) -> SourceFileSyntax {
           )
         }
 
-        if let node = node.layoutNode {
+        if !node.kind.isBase, let node = node.layoutNode {
           let params = FunctionParameterListSyntax {
             for child in node.children {
               FunctionParameterSyntax(

CodeGeneration/Sources/generate-swift-syntax/templates/swiftsyntax/SyntaxBaseNodesFile.swift

@@ -21,7 +21,7 @@ let syntaxBaseNodesFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
       node.documentation,
       node.subtypes,
     ])
-    DeclSyntax(
+    try! ProtocolDeclSyntax(
       """
       // MARK: - \(node.kind.syntaxType)
 
@@ -31,9 +31,26 @@ let syntaxBaseNodesFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
       ///
       ///  - Warning: Do not conform to this protocol yourself.
       \(node.apiAttributes())\
-      public protocol \(node.kind.protocolType): \(node.base.protocolType) {}
+      public protocol \(node.kind.protocolType): \(node.base.protocolType)
       """
-    )
+    ) {
+      for child in node.layoutNode?.children ?? [] {
+        // ==================================
+        // Children properties (requirements)
+        // ==================================
+
+        let childType: TypeSyntax =
+            child.kind.isNodeChoicesEmpty ? child.syntaxNodeKind.syntaxType : child.syntaxChoicesType
+        let type = child.isOptional ? TypeSyntax("\(childType)?") : TypeSyntax("\(childType)")
+
+        DeclSyntax(
+          """
+          \(child.documentation)\
+          \(child.apiAttributes) var \(child.varDeclName): \(type) { get set }
+          """
+        )
+      }
+    }
 
     DeclSyntax(
       #"""
@@ -285,6 +302,41 @@ let syntaxBaseNodesFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
         StmtSyntax("return .choices(\(choices))")
       }
+
+      for child in node.layoutNode?.children ?? [] {
+        // =================================================
+        // Children properties (type-erased implementations)
+        // =================================================
+
+        let childType: TypeSyntax =
+            child.kind.isNodeChoicesEmpty ? child.syntaxNodeKind.syntaxType : child.syntaxChoicesType
+        let type = child.isOptional ? TypeSyntax("\(childType)?") : TypeSyntax("\(childType)")
+
+        try! VariableDeclSyntax(
+          """
+          \(child.documentation)\
+          \(child.apiAttributes)public var \(child.varDeclName): \(type)
+          """
+        ) {
+          AccessorDeclSyntax(
+            """
+            get {
+              return self.asProtocol(\(node.kind.protocolType).self).\(child.baseCallName)
+            }
+            """
+          )
+
+          AccessorDeclSyntax(
+            """
+            set(value) {
+              var existentialCopy = self.asProtocol(\(node.kind.protocolType).self)
+              existentialCopy.\(child.baseCallName) = value
+              self = \(node.kind.syntaxType)(fromProtocol: existentialCopy)
+            }
+            """
+          )
+        }
+      }
     }
 
     leafProtocolDecl(type: node.kind.leafProtocolType, inheritedType: node.kind.protocolType)

CodeGeneration/Sources/generate-swift-syntax/templates/swiftsyntax/SyntaxNodesFile.swift

@@ -21,7 +21,7 @@ import Utils
 /// It then only emits those syntax nodes whose base kind are that specified kind.
 func syntaxNode(nodesStartingWith: [Character]) -> SourceFileSyntax {
   SourceFileSyntax(leadingTrivia: copyrightHeader) {
-    for node in SYNTAX_NODES.compactMap(\.layoutNode)
+    for node in NON_BASE_SYNTAX_NODES.compactMap(\.layoutNode)
     where nodesStartingWith.contains(node.kind.syntaxType.description.droppingLeadingUnderscores.first!) {
       // We are actually handling this node now
       try! StructDeclSyntax(

CodeGeneration/Sources/generate-swift-syntax/templates/swiftsyntaxbuilder/BuildableNodesFile.swift

@@ -26,7 +26,7 @@ let buildableNodesFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
     """
   )
 
-  for node in SYNTAX_NODES.compactMap(\.layoutNode) {
+  for node in NON_BASE_SYNTAX_NODES.compactMap(\.layoutNode) {
     let type = node.type
 
     if let convenienceInit = try! InitSignature(node).createConvenienceBuilderInitializer() {

CodeGeneration/Sources/generate-swift-syntax/templates/swiftsyntaxbuilder/RenamedChildrenBuilderCompatibilityFile.swift

@@ -26,7 +26,7 @@ let renamedChildrenBuilderCompatibilityFile = try! SourceFileSyntax(leadingTrivi
     """
   )
 
-  for layoutNode in SYNTAX_NODES.compactMap(\.layoutNode).filter({ !$0.childHistory.isEmpty }) {
+  for layoutNode in NON_BASE_SYNTAX_NODES.compactMap(\.layoutNode).filter({ !$0.childHistory.isEmpty }) {
     let initSignatures = SYNTAX_COMPATIBILITY_LAYERS.deprecatedInitSignaturesByNode[layoutNode.syntaxNodeKind] ?? []
 
     for signature in initSignatures {

CodeGeneration/Tests/ValidateSyntaxNodes/ValidateSyntaxNodes.swift

@@ -145,12 +145,12 @@ class ValidateSyntaxNodes: XCTestCase {
   func testBaseKindSuffix() {
     var failures: [ValidationFailure] = []
     for node in SYNTAX_NODES where node.base != .syntaxCollection {
-      if !node.kind.syntaxType.description.hasSuffix(node.base.syntaxType.description) {
+      if !node.kind.syntaxType.description.hasSuffix(node.base.baseTypeSuffix!) {
         failures.append(
           ValidationFailure(
             node: node.kind,
             message:
-              "has base kind '\(node.base.syntaxType)' but type name doesn’t have '\(node.base.syntaxType)' suffix"
+              "has base kind '\(node.base.syntaxType)' but type name doesn’t have '\(node.base.baseTypeSuffix!)' suffix"
           )
         )
       }
@@ -461,6 +461,11 @@ class ValidateSyntaxNodes: XCTestCase {
           node: .declModifier,
           message: "child 'name' only has keywords as its token choices and should thus end with 'Specifier'"
         ),
+        // An extension member for '*DeclSyntax.introducer' already existed; we're just formalizing it
+        ValidationFailure(
+          node: .declGroupHeader,
+          message: "child 'introducer' only has keywords as its token choices and should thus end with 'Specifier'"
+        ),
       ]
     )
   }