Merge remote-tracking branch 'upstream/main' into rfc-upstream-sync

Author: MAJKFL

CodeGeneration/Sources/SyntaxSupport/AvailabilityNodes.swift

@@ -182,4 +182,29 @@ public let AVAILABILITY_NODES: [Node] = [
     ]
   ),
 
+  Node(
+    kind: .availabilityMacroDefinition,
+    base: .syntax,
+    spi: "Compiler",
+    nameForDiagnostics: "availability macro definition",
+    documentation: "Syntax for '-define-availability' compiler arguments, never appear in Swift source code",
+    parserFunction: "parseAvailabilityMacroDefinition",
+    children: [
+      Child(
+        name: "platformVersion",
+        kind: .node(kind: .platformVersion)
+      ),
+      Child(
+        name: "colon",
+        kind: .token(choices: [.token(.colon)])
+      ),
+      Child(
+        name: "specs",
+        kind: .collection(
+          kind: .availabilityArgumentList,
+          collectionElementName: "AvailabilityArgument"
+        )
+      ),
+    ]
+  ),
 ]

CodeGeneration/Sources/SyntaxSupport/KeywordSpec.swift

@@ -38,17 +38,12 @@ public struct KeywordSpec: IdentifierConvertible {
   ///
   /// This is typically used to mark APIs as SPI when the keyword is part of an experimental language feature.
   public var apiAttributes: AttributeListSyntax {
-    let attrList = AttributeListSyntax {
+    AttributeListSyntax {
       if isExperimental {
-        let experimentalSPI: AttributeListSyntax = """
-          #if compiler(>=5.8)
-          @_spi(ExperimentalLanguageFeatures)
-          #endif
-          """
-        experimentalSPI.with(\.trailingTrivia, .newline)
+        AttributeSyntax("@_spi(ExperimentalLanguageFeatures)")
+          .with(\.trailingTrivia, .newline)
       }
     }
-    return attrList.with(\.trailingTrivia, attrList.isEmpty ? [] : .newline)
   }
 
   /// Initializes a new `KeywordSpec` instance.

CodeGeneration/Sources/SyntaxSupport/Node.swift

@@ -42,6 +42,9 @@ public class Node: NodeChoiceConvertible {
 
   public let experimentalFeature: ExperimentalFeature?
 
+  /// SPI name if this node is only available for the SPI.
+  public let spi: TokenSyntax?
+
   /// When the node name is printed for diagnostics, this name is used.
   /// If `nil`, `nameForDiagnostics` will print the parent node’s name.
   public let nameForDiagnostics: String?
@@ -93,21 +96,20 @@ public class Node: NodeChoiceConvertible {
   /// Retrieve the attributes that should be printed on any API for the
   /// generated node. If `forRaw` is true, this is for the raw syntax node.
   public func apiAttributes(forRaw: Bool = false) -> AttributeListSyntax {
-    let attrList = AttributeListSyntax {
+    AttributeListSyntax {
       if isExperimental {
-        // SPI for enum cases currently requires Swift 5.8 to work correctly.
-        let experimentalSPI: AttributeListSyntax = """
-          #if compiler(>=5.8)
-          @_spi(ExperimentalLanguageFeatures)
-          #endif
-          """
-        experimentalSPI.with(\.trailingTrivia, .newline)
+        AttributeSyntax("@_spi(ExperimentalLanguageFeatures)")
+          .with(\.trailingTrivia, .newline)
+      }
+      if let spi = self.spi {
+        AttributeSyntax("@_spi(\(spi))")
+          .with(\.trailingTrivia, .newline)
       }
       if forRaw {
-        "@_spi(RawSyntax)"
+        AttributeSyntax("@_spi(RawSyntax)")
+          .with(\.trailingTrivia, .newline)
       }
     }
-    return attrList.with(\.trailingTrivia, attrList.isEmpty ? [] : .newline)
   }
 
   public var apiAttributes: AttributeListSyntax {
@@ -119,6 +121,7 @@ public class Node: NodeChoiceConvertible {
     kind: SyntaxNodeKind,
     base: SyntaxNodeKind,
     experimentalFeature: ExperimentalFeature? = nil,
+    spi: TokenSyntax? = nil,
     nameForDiagnostics: String?,
     documentation: String? = nil,
     parserFunction: TokenSyntax? = nil,
@@ -132,6 +135,7 @@ public class Node: NodeChoiceConvertible {
     self.kind = kind
     self.base = base
     self.experimentalFeature = experimentalFeature
+    self.spi = spi
     self.nameForDiagnostics = nameForDiagnostics
     self.documentation = SwiftSyntax.Trivia.docCommentTrivia(from: documentation)
     self.parserFunction = parserFunction
@@ -141,6 +145,10 @@ public class Node: NodeChoiceConvertible {
     self.data = .layout(children: childrenWithUnexpected, childHistory: childHistory, traits: traits)
   }
 
+  public var hiddenInDocumentation: Bool {
+    self.isExperimental || self.spi != nil || self.kind.isDeprecated
+  }
+
   /// A doc comment that lists all the nodes in which this node occurs as a child in.
   public var containedIn: SwiftSyntax.Trivia {
     if kind == .unexpectedNodes {
@@ -149,7 +157,10 @@ public class Node: NodeChoiceConvertible {
       return []
     }
     var childIn: [(node: SyntaxNodeKind, child: Child?)] = []
-    for node in SYNTAX_NODES where !node.isExperimental {
+    for node in SYNTAX_NODES {
+      if !self.hiddenInDocumentation && node.hiddenInDocumentation {
+        continue
+      }
       if let layout = node.layoutNode {
         for child in layout.children {
           if child.kinds.contains(self.kind) {
@@ -202,7 +213,7 @@ public class Node: NodeChoiceConvertible {
 
     let list =
       SYNTAX_NODES
-      .filter { $0.base == self.kind && !$0.isExperimental && !$0.kind.isDeprecated }
+      .filter { $0.base == self.kind && (!$0.hiddenInDocumentation || self.hiddenInDocumentation) }
       .map { "- \($0.kind.doccLink)" }
       .joined(separator: "\n")
 
@@ -226,6 +237,7 @@ public class Node: NodeChoiceConvertible {
     kind: SyntaxNodeKind,
     base: SyntaxNodeKind,
     experimentalFeature: ExperimentalFeature? = nil,
+    spi: TokenSyntax? = nil,
     nameForDiagnostics: String?,
     documentation: String? = nil,
     parserFunction: TokenSyntax? = nil,
@@ -235,6 +247,7 @@ public class Node: NodeChoiceConvertible {
     precondition(base == .syntaxCollection)
     self.base = base
     self.experimentalFeature = experimentalFeature
+    self.spi = spi
     self.nameForDiagnostics = nameForDiagnostics
     self.documentation = SwiftSyntax.Trivia.docCommentTrivia(from: documentation)
     self.parserFunction = parserFunction

CodeGeneration/Sources/SyntaxSupport/SyntaxNodeKind.swift

@@ -44,6 +44,7 @@ public enum SyntaxNodeKind: String, CaseIterable, IdentifierConvertible, TypeCon
   case availabilityArgumentList
   case availabilityCondition
   case availabilityLabeledArgument
+  case availabilityMacroDefinition
   case awaitExpr
   case backDeployedAttributeArguments
   case binaryOperatorExpr

CodeGeneration/Sources/generate-swift-syntax/ImportSwiftSyntax.swift

@@ -0,0 +1,51 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2025 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
+//
+//===----------------------------------------------------------------------===//
+
+import SwiftSyntax
+import SwiftSyntaxBuilder
+import SyntaxSupport
+
+enum ImportAccessLevel {
+  case `public`
+  case `internal`
+}
+
+func importSwiftSyntax(accessLevel: ImportAccessLevel = .internal) -> DeclSyntax {
+  // Import all '@_spi'.
+  let importingAttrs = AttributeListSyntax {
+    var seen: Set<String> = []
+    AttributeSyntax("@_spi(RawSyntax)").with(\.trailingTrivia, .space)
+    AttributeSyntax("@_spi(ExperimentalLanguageFeatures)").with(\.trailingTrivia, .space)
+    for node in NON_BASE_SYNTAX_NODES {
+      if let spi = node.spi, seen.insert(spi.text).inserted {
+        AttributeSyntax("@_spi(\(spi))").with(\.trailingTrivia, .space)
+      }
+    }
+  }
+  let visibilityKeyword: TokenSyntax
+  switch accessLevel {
+  case .internal:
+    visibilityKeyword = "internal"
+  case .public:
+    visibilityKeyword = "public"
+  }
+
+  return DeclSyntax(
+    """
+    #if compiler(>=6)
+    \(importingAttrs)\(visibilityKeyword) import SwiftSyntax
+    #else
+    \(importingAttrs)import SwiftSyntax
+    #endif
+    """
+  )
+}

CodeGeneration/Sources/generate-swift-syntax/templates/swiftparser/IsLexerClassifiedFile.swift

@@ -16,15 +16,7 @@ import SyntaxSupport
 import Utils
 
 let isLexerClassifiedFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
-  DeclSyntax(
-    """
-    #if compiler(>=6)
-    public import SwiftSyntax
-    #else
-    import SwiftSyntax
-    #endif
-    """
-  )
+  importSwiftSyntax(accessLevel: .public)
 
   try! ExtensionDeclSyntax(
     """

CodeGeneration/Sources/generate-swift-syntax/templates/swiftparser/LayoutNodesParsableFile.swift

@@ -16,15 +16,7 @@ import SyntaxSupport
 import Utils
 
 let layoutNodesParsableFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
-  DeclSyntax(
-    """
-    #if compiler(>=6)
-    @_spi(RawSyntax) public import SwiftSyntax
-    #else
-    @_spi(RawSyntax) import SwiftSyntax
-    #endif
-    """
-  )
+  importSwiftSyntax(accessLevel: .public)
 
   DeclSyntax(
     """
@@ -49,7 +41,7 @@ let layoutNodesParsableFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
             defer { withExtendedLifetime(parser) {} }
             let node = parser.\(parserFunction)()
             let raw = RawSyntax(parser.parseRemainder(into: node))
-            return Syntax(raw: raw, rawNodeArena: parser.arena).cast(Self.self)
+            return Syntax(raw: raw, rawNodeArena: raw.arena).cast(Self.self)
           }
         }
         """

CodeGeneration/Sources/generate-swift-syntax/templates/swiftparser/ParserTokenSpecSetFile.swift

@@ -27,15 +27,7 @@ func tokenCaseMatch(
 }
 
 let parserTokenSpecSetFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
-  DeclSyntax(
-    """
-    #if compiler(>=6)
-    @_spi(RawSyntax) @_spi(ExperimentalLanguageFeatures) public import SwiftSyntax
-    #else
-    @_spi(RawSyntax) @_spi(ExperimentalLanguageFeatures) import SwiftSyntax
-    #endif
-    """
-  )
+  importSwiftSyntax(accessLevel: .public)
 
   for layoutNode in SYNTAX_NODES.compactMap(\.layoutNode) {
     for child in layoutNode.children {

CodeGeneration/Sources/generate-swift-syntax/templates/swiftparser/TokenSpecStaticMembersFile.swift

@@ -16,15 +16,7 @@ import SyntaxSupport
 import Utils
 
 let tokenSpecStaticMembersFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
-  DeclSyntax(
-    """
-    #if compiler(>=6)
-    @_spi(RawSyntax) internal import SwiftSyntax
-    #else
-    @_spi(RawSyntax) import SwiftSyntax
-    #endif
-    """
-  )
+  importSwiftSyntax()
 
   try! ExtensionDeclSyntax("extension TokenSpec") {
     for tokenSpec in Token.allCases.map(\.spec) where tokenSpec.kind != .keyword {

CodeGeneration/Sources/generate-swift-syntax/templates/swiftparserdiagnostics/ChildNameForDiagnosticsFile.swift

@@ -16,15 +16,7 @@ import SyntaxSupport
 import Utils
 
 let childNameForDiagnosticFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
-  DeclSyntax(
-    """
-    #if compiler(>=6)
-    @_spi(ExperimentalLanguageFeatures) internal import SwiftSyntax
-    #else
-    @_spi(ExperimentalLanguageFeatures) import SwiftSyntax
-    #endif
-    """
-  )
+  importSwiftSyntax(accessLevel: .internal)
 
   try! FunctionDeclSyntax(
     "private func childNameForDiagnostics(_ keyPath: AnyKeyPath) -> String?"