Deprecate placeholder nodes

Author: kimdv

CodeGeneration/Package.swift

@@ -21,8 +21,8 @@ let package = Package(
     // checkout of swift-syntax that is unaffected by the newly generated files.
     // Be sure to revert the change before committing your changes.
     //
-    // .package(url: "https://github.com/apple/swift-syntax", branch: "main")
-    .package(path: "..")
+    .package(url: "https://github.com/apple/swift-syntax", branch: "main")
+    // .package(path: "..")
   ],
   targets: [
     .executableTarget(

CodeGeneration/Sources/SyntaxSupport/DeclNodes.swift

@@ -551,6 +551,7 @@ public let DECL_NODES: [Node] = [
   Node(
     kind: .editorPlaceholderDecl,
     base: .decl,
+    isDeprecated: true,
     nameForDiagnostics: "editor placeholder",
     documentation: """
       An editor placeholder, e.g. `<#declaration#>` that is used in a position that expects a declaration.

CodeGeneration/Sources/SyntaxSupport/ExprNodes.swift

@@ -791,6 +791,7 @@ public let EXPR_NODES: [Node] = [
   Node(
     kind: .editorPlaceholderExpr,
     base: .expr,
+    isDeprecated: true,
     nameForDiagnostics: "editor placeholder",
     children: [
       Child(

CodeGeneration/Sources/SyntaxSupport/Node.swift

@@ -57,6 +57,9 @@ public class Node {
   /// function that should be invoked to create this node.
   public let parserFunction: TokenSyntax?
 
+  /// If `true`, if the node is deprecated and should not be used anymore.
+  public let isDeprecated: Bool
+
   /// If `true`, this is for an experimental language feature, and any public
   /// API generated should be SPI.
   public var isExperimental: Bool { experimentalFeature != nil }
@@ -95,7 +98,7 @@ public class Node {
 
   /// 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 {
+  public func apiAttributes(forRaw: Bool = false, ignoreAvailableAttribute: Bool = false) -> AttributeListSyntax {
     let attrList = AttributeListSyntax {
       if isExperimental {
         // SPI for enum cases currently requires Swift 5.8 to work correctly.
@@ -106,10 +109,16 @@ public class Node {
           """
         experimentalSPI.with(\.trailingTrivia, .newline)
       }
+
       if forRaw {
         "@_spi(RawSyntax)"
       }
+
+      if isDeprecated, !ignoreAvailableAttribute {
+        #"@available(*, deprecated, message: "Will be removed in a future version.")"#
+      }
     }
+
     return attrList.with(\.trailingTrivia, attrList.isEmpty ? [] : .newline)
   }
 
@@ -128,6 +137,7 @@ public class Node {
     kind: SyntaxNodeKind,
     base: SyntaxNodeKind,
     experimentalFeature: ExperimentalFeature? = nil,
+    isDeprecated: Bool = false,
     nameForDiagnostics: String?,
     documentation: String? = nil,
     parserFunction: TokenSyntax? = nil,
@@ -140,6 +150,7 @@ public class Node {
     self.kind = kind
     self.base = base
     self.experimentalFeature = experimentalFeature
+    self.isDeprecated = isDeprecated
     self.nameForDiagnostics = nameForDiagnostics
     self.documentation = SwiftSyntax.Trivia.docCommentTrivia(from: documentation)
     self.parserFunction = parserFunction
@@ -272,6 +283,7 @@ public class Node {
     kind: SyntaxNodeKind,
     base: SyntaxNodeKind,
     experimentalFeature: ExperimentalFeature? = nil,
+    isDeprecated: Bool = false,
     nameForDiagnostics: String?,
     documentation: String? = nil,
     parserFunction: TokenSyntax? = nil,
@@ -281,6 +293,7 @@ public class Node {
     precondition(base == .syntaxCollection)
     self.base = base
     self.experimentalFeature = experimentalFeature
+    self.isDeprecated = isDeprecated
     self.nameForDiagnostics = nameForDiagnostics
     self.documentation = SwiftSyntax.Trivia.docCommentTrivia(from: documentation)
     self.parserFunction = parserFunction

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

@@ -26,7 +26,7 @@ let syntaxKindFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
     for node in NON_BASE_SYNTAX_NODES {
       DeclSyntax(
         """
-        \(node.apiAttributes())\
+        \(node.apiAttributes(ignoreAvailableAttribute: true))\
         case \(node.varOrCaseName)
         """
       )

Sources/SwiftParser/Declarations.swift

@@ -275,9 +275,9 @@ extension Parser {
       }
 
       if self.currentToken.isEditorPlaceholder {
-        let placeholder = self.consumeAnyToken()
+        let placeholder = self.parseAnyIdentifier()
         return RawDeclSyntax(
-          RawEditorPlaceholderDeclSyntax(
+          RawMissingDeclSyntax(
             attributes: attrs.attributes,
             modifiers: attrs.modifiers,
             placeholder: placeholder,

Sources/SwiftParser/Expressions.swift

@@ -1241,14 +1241,6 @@ extension Parser {
   mutating func parseIdentifierExpression() -> RawExprSyntax {
     let declName = self.parseDeclReferenceExpr(.compoundNames)
     guard self.withLookahead({ $0.canParseAsGenericArgumentList() }) else {
-      if declName.baseName.tokenText.isEditorPlaceholder && declName.argumentNames == nil {
-        return RawExprSyntax(
-          RawEditorPlaceholderExprSyntax(
-            placeholder: declName.baseName,
-            arena: self.arena
-          )
-        )
-      }
       return RawExprSyntax(declName)
     }
 

Sources/SwiftParserDiagnostics/MissingNodesError.swift

@@ -381,7 +381,17 @@ extension ParseDiagnosticsGenerator {
 
     // Walk all upcoming sibling to see if they are also missing to handle them in this diagnostic.
     // If this is the case, handle all of them in this diagnostic.
-    var missingNodes = [Syntax(node)]
+    var missingNodes: [Syntax] = [Syntax(node)]
+
+    // If the node is an `MissingDeclSyntax` and the placeholder is an editor placeholder
+    // we should not add a diagnostic that it's missing.
+    if let missing = missingNodes.first?.as(MissingDeclSyntax.self),
+      missing.placeholder.isEditorPlaceholder,
+      !missing.placeholder.isMissing
+    {
+      missingNodes = []
+    }
+
     if let parentWithTokens = ancestorWithMoreTokens, let index {
       let siblings = parentWithTokens.children(viewMode: .all)
       let siblingsAfter = siblings[siblings.index(after: index)...]
@@ -403,6 +413,10 @@ extension ParseDiagnosticsGenerator {
       }
     }
 
+    if missingNodes.isEmpty {
+      return .visitChildren
+    }
+
     let changes = missingNodes.map { node in
       if let missing = node.asProtocol(MissingNodeSyntax.self) {
         // For missing nodes, only make the placeholder present. Don’t make any

Sources/SwiftParserDiagnostics/ParseDiagnosticsGenerator.swift

@@ -678,7 +678,7 @@ public class ParseDiagnosticsGenerator: SyntaxAnyVisitor {
     if shouldSkip(node) {
       return .skipChildren
     }
-    if node.statements.only?.item.is(EditorPlaceholderExprSyntax.self) == true {
+    if let item = node.statements.only?.item.as(DeclReferenceExprSyntax.self), item.baseName.isEditorPlaceholder {
       // Only emit a single diagnostic about the editor placeholder and none for the missing '{' and '}'.
       addDiagnostic(node, .editorPlaceholderInSourceFile, handledNodes: [node.id])
       return .skipChildren

Sources/SwiftRefactor/ExpandEditorPlaceholder.swift

@@ -135,8 +135,7 @@ public struct ExpandEditorPlaceholder: EditRefactoringProvider {
 /// Expansion on `closure1` and `normalArg` is the same as `ExpandEditorPlaceholder`.
 public struct ExpandEditorPlaceholders: EditRefactoringProvider {
   public static func textRefactor(syntax token: TokenSyntax, in context: Void) -> [SourceEdit] {
-    guard let placeholder = token.parent?.as(EditorPlaceholderExprSyntax.self),
-      let arg = placeholder.parent?.as(LabeledExprSyntax.self),
+    guard let arg = token.parent?.as(LabeledExprSyntax.self),
       let argList = arg.parent?.as(LabeledExprListSyntax.self),
       let call = argList.parent?.as(FunctionCallExprSyntax.self)
     else {
@@ -190,8 +189,8 @@ extension FunctionTypeSyntax {
       placeholder = ExpandEditorPlaceholder.wrapInTypePlaceholder(ret, type: ret)
     }
 
-    let statementPlaceholder = EditorPlaceholderExprSyntax(
-      placeholder: .identifier(placeholder)
+    let statementPlaceholder = DeclReferenceExprSyntax(
+      baseName: .identifier(placeholder)
     )
     let closureStatement = CodeBlockItemSyntax(
       item: .expr(ExprSyntax(statementPlaceholder))
@@ -234,8 +233,9 @@ extension FunctionCallExprSyntax {
     var includedArg = false
     var argsToExpand = 0
     for arg in arguments.reversed() {
-      guard let expr = arg.expression.as(EditorPlaceholderExprSyntax.self),
-        let data = EditorPlaceholderData(token: expr.placeholder),
+      guard let expr = arg.expression.as(DeclReferenceExprSyntax.self),
+        expr.baseName.isEditorPlaceholder,
+        let data = EditorPlaceholderData(token: expr.baseName),
         case let .typed(_, type) = data,
         type.is(FunctionTypeSyntax.self)
       else {
@@ -253,7 +253,7 @@ extension FunctionCallExprSyntax {
 
     var expandedArgs = [LabeledExprSyntax]()
     for arg in arguments.suffix(argsToExpand) {
-      let edits = ExpandEditorPlaceholder.textRefactor(syntax: arg.expression.cast(EditorPlaceholderExprSyntax.self).placeholder)
+      let edits = ExpandEditorPlaceholder.textRefactor(syntax: arg.expression.cast(DeclReferenceExprSyntax.self).baseName)
       guard edits.count == 1, let edit = edits.first, !edit.replacement.isEmpty else {
         return nil
       }

Sources/SwiftSyntax/generated/SyntaxAnyVisitor.swift

@@ -774,18 +774,22 @@ open class SyntaxAnyVisitor: SyntaxVisitor {
     visitAnyPost(node._syntaxNode)
   }
 
+  @available(*, deprecated, message: "Will be removed in a future version.")
   override open func visit(_ node: EditorPlaceholderDeclSyntax) -> SyntaxVisitorContinueKind {
     return visitAny(node._syntaxNode)
   }
 
+  @available(*, deprecated, message: "Will be removed in a future version.")
   override open func visitPost(_ node: EditorPlaceholderDeclSyntax) {
     visitAnyPost(node._syntaxNode)
   }
 
+  @available(*, deprecated, message: "Will be removed in a future version.")
   override open func visit(_ node: EditorPlaceholderExprSyntax) -> SyntaxVisitorContinueKind {
     return visitAny(node._syntaxNode)
   }
 
+  @available(*, deprecated, message: "Will be removed in a future version.")
   override open func visitPost(_ node: EditorPlaceholderExprSyntax) {
     visitAnyPost(node._syntaxNode)
   }

Sources/SwiftSyntax/generated/SyntaxEnum.swift

@@ -107,7 +107,9 @@ public enum SyntaxEnum {
   case documentationAttributeArgumentList(DocumentationAttributeArgumentListSyntax)
   case documentationAttributeArgument(DocumentationAttributeArgumentSyntax)
   case dynamicReplacementAttributeArguments(DynamicReplacementAttributeArgumentsSyntax)
+  @available(*, deprecated, message: "Will be removed in a future version.")
   case editorPlaceholderDecl(EditorPlaceholderDeclSyntax)
+  @available(*, deprecated, message: "Will be removed in a future version.")
   case editorPlaceholderExpr(EditorPlaceholderExprSyntax)
   case effectsAttributeArgumentList(EffectsAttributeArgumentListSyntax)
   case enumCaseDecl(EnumCaseDeclSyntax)

Sources/SwiftSyntax/generated/SyntaxRewriter.swift

@@ -709,13 +709,15 @@ open class SyntaxRewriter {
   /// Visit a ``EditorPlaceholderDeclSyntax``.
   ///   - Parameter node: the node that is being visited
   ///   - Returns: the rewritten node
+  @available(*, deprecated, message: "Will be removed in a future version.")
   open func visit(_ node: EditorPlaceholderDeclSyntax) -> DeclSyntax {
     return DeclSyntax(visitChildren(node))
   }
 
   /// Visit a ``EditorPlaceholderExprSyntax``.
   ///   - Parameter node: the node that is being visited
   ///   - Returns: the rewritten node
+  @available(*, deprecated, message: "Will be removed in a future version.")
   open func visit(_ node: EditorPlaceholderExprSyntax) -> ExprSyntax {
     return ExprSyntax(visitChildren(node))
   }

Sources/SwiftSyntax/generated/SyntaxVisitor.swift

@@ -1111,24 +1111,28 @@ open class SyntaxVisitor {
   /// Visiting ``EditorPlaceholderDeclSyntax`` specifically.
   ///   - Parameter node: the node we are visiting.
   ///   - Returns: how should we continue visiting.
+  @available(*, deprecated, message: "Will be removed in a future version.")
   open func visit(_ node: EditorPlaceholderDeclSyntax) -> SyntaxVisitorContinueKind {
     return .visitChildren
   }
 
   /// The function called after visiting ``EditorPlaceholderDeclSyntax`` and its descendants.
   ///   - node: the node we just finished visiting.
+  @available(*, deprecated, message: "Will be removed in a future version.")
   open func visitPost(_ node: EditorPlaceholderDeclSyntax) {
   }
 
   /// Visiting ``EditorPlaceholderExprSyntax`` specifically.
   ///   - Parameter node: the node we are visiting.
   ///   - Returns: how should we continue visiting.
+  @available(*, deprecated, message: "Will be removed in a future version.")
   open func visit(_ node: EditorPlaceholderExprSyntax) -> SyntaxVisitorContinueKind {
     return .visitChildren
   }
 
   /// The function called after visiting ``EditorPlaceholderExprSyntax`` and its descendants.
   ///   - node: the node we just finished visiting.
+  @available(*, deprecated, message: "Will be removed in a future version.")
   open func visitPost(_ node: EditorPlaceholderExprSyntax) {
   }
 

Sources/SwiftSyntax/generated/raw/RawSyntaxNodesEF.swift

@@ -1,7 +1,7 @@
 @_spi(RawSyntax)
 public protocol RawExprSyntaxNodeProtocol: RawSyntaxNodeProtocol {}
 
-@_spi(RawSyntax)
+@_spi(RawSyntax) @available(*, deprecated, message: "Will be removed in a future version.")
 public struct RawEditorPlaceholderDeclSyntax: RawDeclSyntaxNodeProtocol {
   @_spi(RawSyntax)
   public var layoutView: RawSyntaxLayoutView {
@@ -83,7 +83,7 @@ public struct RawEditorPlaceholderDeclSyntax: RawDeclSyntaxNodeProtocol {
   }
 }
 
-@_spi(RawSyntax)
+@_spi(RawSyntax) @available(*, deprecated, message: "Will be removed in a future version.")
 public struct RawEditorPlaceholderExprSyntax: RawExprSyntaxNodeProtocol {
   @_spi(RawSyntax)
   public var layoutView: RawSyntaxLayoutView {

Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesEF.swift

@@ -21,6 +21,7 @@
 ///  - `attributes`: ``AttributeListSyntax``
 ///  - `modifiers`: ``DeclModifierListSyntax``
 ///  - `placeholder`: `<identifier>`
+@available(*, deprecated, message: "Will be removed in a future version.")
 public struct EditorPlaceholderDeclSyntax: DeclSyntaxProtocol, SyntaxHashable, _LeafDeclSyntaxNodeProtocol {
   public let _syntaxNode: Syntax
 
@@ -223,6 +224,7 @@ public struct EditorPlaceholderDeclSyntax: DeclSyntaxProtocol, SyntaxHashable, _
 /// ### Children
 /// 
 ///  - `placeholder`: `<identifier>`
+@available(*, deprecated, message: "Will be removed in a future version.")
 public struct EditorPlaceholderExprSyntax: ExprSyntaxProtocol, SyntaxHashable, _LeafExprSyntaxNodeProtocol {
   public let _syntaxNode: Syntax
 

Tests/SwiftParserTest/DeclarationTests.swift

@@ -2272,7 +2272,7 @@ final class DeclarationTests: ParserTestCase {
         1️⃣<#code#>
       }
       """,
-      substructure: MemberBlockItemSyntax(decl: EditorPlaceholderDeclSyntax(placeholder: .identifier("<#code#>"))),
+      // substructure: MemberBlockItemSyntax(decl: DeclReferenceExprSyntax(baseName: .identifier("<#code#>"))),
       diagnostics: [
         DiagnosticSpec(message: "editor placeholder in source file")
       ]
@@ -2806,8 +2806,8 @@ final class DeclarationTests: ParserTestCase {
             CodeBlockItemSyntax(
               item: .expr(
                 ExprSyntax(
-                  EditorPlaceholderExprSyntax(
-                    placeholder: .identifier("<#function body#>")
+                  DeclReferenceExprSyntax(
+                    baseName: .identifier("<#function body#>")
                   )
                 )
               )
@@ -2851,8 +2851,8 @@ final class DeclarationTests: ParserTestCase {
             CodeBlockItemSyntax(
               item: .expr(
                 ExprSyntax(
-                  EditorPlaceholderExprSyntax(
-                    placeholder: .identifier("<#function body#>")
+                  DeclReferenceExprSyntax(
+                    baseName: .identifier("<#function body#>")
                   )
                 )
               )

Tests/SwiftParserTest/PatternTests.swift

@@ -180,8 +180,8 @@ final class PatternTests: ParserTestCase {
               identifier: .identifier("<#name#>")
             ),
             initializer: InitializerClauseSyntax(
-              value: EditorPlaceholderExprSyntax(
-                placeholder: .identifier("<#value#>")
+              value: DeclReferenceExprSyntax(
+                baseName: .identifier("<#value#>")
               )
             )
           )

Tests/SwiftParserTest/translated/TrailingClosuresTests.swift

@@ -185,14 +185,14 @@ final class TrailingClosuresTests: ParserTestCase {
           leftBrace: .leftBraceToken(presence: .missing),
           statements: CodeBlockItemListSyntax([
             CodeBlockItemSyntax(
-              item: .init(EditorPlaceholderExprSyntax(placeholder: .identifier("<#T##() -> Void#>")))
+              item: .init(DeclReferenceExprSyntax(baseName: .identifier("<#T##() -> Void#>")))
             )
           ]),
           rightBrace: .rightBraceToken(presence: .missing)
         )
       ),
       diagnostics: [
-        DiagnosticSpec(message: "editor placeholder in source file")
+        DiagnosticSpec(locationMarker: "1️⃣", message: "editor placeholder in source file")
       ]
     )
   }