Add deprecated warnings for base node casts in base node protocols

Author: Matejkob

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

@@ -72,6 +72,39 @@ let syntaxBaseNodesFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
           return self.as(S.self)!
         }
 
+        /// Checks if the current syntax node can be upcast to its base node type (``\#(node.kind.syntaxType)``).
+        ///
+        /// - Returns: `true` since the node can always be upcast to its base node.
+        ///
+        /// - Note: This method overloads the general `is` method and is marked deprecated to produce a warning
+        ///         informing the user that the upcast will always succeed.
+        @available(*, deprecated, message: "This cast will always succeed")
+        public func `is`(_ syntaxType: \#(node.kind.syntaxType).Type) -> Bool {
+          return true
+        }
+
+        /// Attempts to upcast the current syntax node to its base node type (``\#(node.kind.syntaxType)``).
+        ///
+        /// - Returns: The base node created from the current syntax node, as the node can always be upcast to its base type.
+        ///
+        /// - Note: This method overloads the general `as` method and is marked deprecated to produce a warning
+        ///         informing the user the upcast should be performed using the target base node's initializer.
+        @available(*, deprecated, message: "Use `\#(node.kind.syntaxType).init` for upcasting")
+        public func `as`(_ syntaxType: \#(node.kind.syntaxType).Type) -> \#(node.kind.syntaxType)? {
+          return \#(node.kind.syntaxType)(self)
+        }
+
+        /// Force-upcast the current syntax node to its base node type (``\#(node.kind.syntaxType)``).
+        ///
+        /// - Returns: The base node created from the current syntax node, as the node can always be upcast to its base type.
+        ///
+        /// - Note: This method overloads the general `as` method and is marked deprecated to produce a warning
+        ///         informing the user the upcast should be performed using the target base node's initializer.
+        @available(*, deprecated, message: "Use `\#(node.kind.syntaxType).init` for upcasting")
+        public func cast(_ syntaxType: \#(node.kind.syntaxType).Type) -> \#(node.kind.syntaxType) {
+          return \#(node.kind.syntaxType)(self)
+        }
+
         /// Checks if the current syntax node can be cast to a given node type from the different base node protocol hierarchy than ``\#(node.kind.protocolType)``.
         ///
         /// - Returns: `false` since the node can not be cast to the node type from different base node protocol hierarchy than ``\#(node.kind.protocolType)``.

Release Notes/510.md

@@ -29,12 +29,17 @@
   - Description: Syntax nodes that do not act as base nodes for other syntax types have the casting methods marked as deprecated. This prevents unsafe type-casting by issuing deprecation warnings for methods that will always result in failed casts.
   - Issue: https://github.com/apple/swift-syntax/issues/2092
   - Pull Request: https://github.com/apple/swift-syntax/pull/2108
-  
+
 - Same-Type Casts 
   - Description: `is`, `as`, and `cast` overloads on `SyntaxProtocol` with same-type conversions are marked as deprecated. The deprecated methods emit a warning indicating the cast will always succeed.
   - Issue: https://github.com/apple/swift-syntax/issues/2092
   - Pull Request: https://github.com/apple/swift-syntax/pull/2108
-  
+
+- Base Node Casts
+  - Description: `is`, `as`, and `cast` methods on base node protocols with base-type conversions are marked as deprecated. The deprecated methods emit a warning that informs the developer that the cast will always succeed and should be done using the base node's initializer.
+  - Issue: https://github.com/apple/swift-syntax/issues/2092
+  - Pull Request: https://github.com/apple/swift-syntax/pull/2108
+
 ## API-Incompatible Changes
 
 

Sources/SwiftSyntax/Syntax.swift

@@ -213,6 +213,17 @@ public extension SyntaxProtocol {
     return self.as(syntaxType) != nil
   }
 
+  /// Checks if the current syntax node can be upcast to ``Syntax`` node.
+  ///
+  /// - Returns: `true` since the node can always be upcast to ``Syntax`` node.
+  ///
+  /// - Note: This method overloads the general `is` method and is marked deprecated to produce a warning
+  ///         informing the user that the upcast will always succeed.
+  @available(*, deprecated, message: "This cast will always succeed")
+  func `is`(_ syntaxType: Syntax.Type) -> Bool {
+    return true
+  }
+
   /// Checks if the current syntax node can be cast to its own type.
   ///
   /// - Returns: `true` since the node is already of its own type.
@@ -231,6 +242,17 @@ public extension SyntaxProtocol {
     return S.init(self)
   }
 
+  /// Attempts to upcast the current syntax node to ``Syntax`` node..
+  ///
+  /// - Returns: The ``Syntax`` node created from the current syntax node, as the node can always be upcast to ``Syntax`` node.
+  ///
+  /// - Note: This method overloads the general `as` method and is marked deprecated to produce a warning
+  ///         informing the user the upcast should be performed using the base node's initializer.
+  @available(*, deprecated, message: "Use `Syntax.init` for upcasting.")
+  func `as`(_ syntaxType: Syntax.Type) -> Syntax? {
+    return Syntax(self)
+  }
+
   /// Casts the current syntax node to its own type.
   ///
   /// - Returns: The current syntax node.
@@ -250,6 +272,17 @@ public extension SyntaxProtocol {
     return self.as(S.self)!
   }
 
+  /// Force-cast the current syntax node to ``Syntax`` node..
+  ///
+  /// - Returns: The ``Syntax`` node created from the current syntax node, as the node can always be upcast to ``Syntax`` node.
+  ///
+  /// - Note: This method overloads the general `as` method and is marked deprecated to produce a warning
+  ///         informing the user the upcast should be performed using the base node's initializer.
+  @available(*, deprecated, message: "Use `Syntax.init` for upcasting.")
+  func cast(_ syntaxType: Syntax.Type) -> Syntax {
+    return Syntax(self)
+  }
+
   /// Force-casts the current syntax node to its own type.
   ///
   /// - Returns: The current syntax node.

Sources/SwiftSyntax/generated/SyntaxBaseNodes.swift

@@ -63,6 +63,42 @@ extension DeclSyntaxProtocol {
   }
 
 
+  /// Checks if the current syntax node can be upcast to its base node type (``DeclSyntax``).
+  ///
+  /// - Returns: `true` since the node can always be upcast to its base node.
+  ///
+  /// - Note: This method overloads the general `is` method and is marked deprecated to produce a warning
+  ///         informing the user that the upcast will always succeed.
+  @available(*, deprecated, message: "This cast will always succeed")
+  public func `is`(_ syntaxType: DeclSyntax.Type) -> Bool {
+    return true
+  }
+  
+
+  /// Attempts to upcast the current syntax node to its base node type (``DeclSyntax``).
+  ///
+  /// - Returns: The base node created from the current syntax node, as the node can always be upcast to its base type.
+  ///
+  /// - Note: This method overloads the general `as` method and is marked deprecated to produce a warning
+  ///         informing the user the upcast should be performed using the target base node's initializer.
+  @available(*, deprecated, message: "Use `DeclSyntax.init` for upcasting")
+  public func `as`(_ syntaxType: DeclSyntax.Type) -> DeclSyntax? {
+    return DeclSyntax(self)
+  }
+  
+
+  /// Force-upcast the current syntax node to its base node type (``DeclSyntax``).
+  ///
+  /// - Returns: The base node created from the current syntax node, as the node can always be upcast to its base type.
+  ///
+  /// - Note: This method overloads the general `as` method and is marked deprecated to produce a warning
+  ///         informing the user the upcast should be performed using the target base node's initializer.
+  @available(*, deprecated, message: "Use `DeclSyntax.init` for upcasting")
+  public func cast(_ syntaxType: DeclSyntax.Type) -> DeclSyntax {
+    return DeclSyntax(self)
+  }
+  
+
   /// Checks if the current syntax node can be cast to a given node type from the different base node protocol hierarchy than ``DeclSyntaxProtocol``.
   ///
   /// - Returns: `false` since the node can not be cast to the node type from different base node protocol hierarchy than ``DeclSyntaxProtocol``.
@@ -315,6 +351,42 @@ extension ExprSyntaxProtocol {
   }
 
 
+  /// Checks if the current syntax node can be upcast to its base node type (``ExprSyntax``).
+  ///
+  /// - Returns: `true` since the node can always be upcast to its base node.
+  ///
+  /// - Note: This method overloads the general `is` method and is marked deprecated to produce a warning
+  ///         informing the user that the upcast will always succeed.
+  @available(*, deprecated, message: "This cast will always succeed")
+  public func `is`(_ syntaxType: ExprSyntax.Type) -> Bool {
+    return true
+  }
+  
+
+  /// Attempts to upcast the current syntax node to its base node type (``ExprSyntax``).
+  ///
+  /// - Returns: The base node created from the current syntax node, as the node can always be upcast to its base type.
+  ///
+  /// - Note: This method overloads the general `as` method and is marked deprecated to produce a warning
+  ///         informing the user the upcast should be performed using the target base node's initializer.
+  @available(*, deprecated, message: "Use `ExprSyntax.init` for upcasting")
+  public func `as`(_ syntaxType: ExprSyntax.Type) -> ExprSyntax? {
+    return ExprSyntax(self)
+  }
+  
+
+  /// Force-upcast the current syntax node to its base node type (``ExprSyntax``).
+  ///
+  /// - Returns: The base node created from the current syntax node, as the node can always be upcast to its base type.
+  ///
+  /// - Note: This method overloads the general `as` method and is marked deprecated to produce a warning
+  ///         informing the user the upcast should be performed using the target base node's initializer.
+  @available(*, deprecated, message: "Use `ExprSyntax.init` for upcasting")
+  public func cast(_ syntaxType: ExprSyntax.Type) -> ExprSyntax {
+    return ExprSyntax(self)
+  }
+  
+
   /// Checks if the current syntax node can be cast to a given node type from the different base node protocol hierarchy than ``ExprSyntaxProtocol``.
   ///
   /// - Returns: `false` since the node can not be cast to the node type from different base node protocol hierarchy than ``ExprSyntaxProtocol``.
@@ -595,6 +667,42 @@ extension PatternSyntaxProtocol {
   }
 
 
+  /// Checks if the current syntax node can be upcast to its base node type (``PatternSyntax``).
+  ///
+  /// - Returns: `true` since the node can always be upcast to its base node.
+  ///
+  /// - Note: This method overloads the general `is` method and is marked deprecated to produce a warning
+  ///         informing the user that the upcast will always succeed.
+  @available(*, deprecated, message: "This cast will always succeed")
+  public func `is`(_ syntaxType: PatternSyntax.Type) -> Bool {
+    return true
+  }
+  
+
+  /// Attempts to upcast the current syntax node to its base node type (``PatternSyntax``).
+  ///
+  /// - Returns: The base node created from the current syntax node, as the node can always be upcast to its base type.
+  ///
+  /// - Note: This method overloads the general `as` method and is marked deprecated to produce a warning
+  ///         informing the user the upcast should be performed using the target base node's initializer.
+  @available(*, deprecated, message: "Use `PatternSyntax.init` for upcasting")
+  public func `as`(_ syntaxType: PatternSyntax.Type) -> PatternSyntax? {
+    return PatternSyntax(self)
+  }
+  
+
+  /// Force-upcast the current syntax node to its base node type (``PatternSyntax``).
+  ///
+  /// - Returns: The base node created from the current syntax node, as the node can always be upcast to its base type.
+  ///
+  /// - Note: This method overloads the general `as` method and is marked deprecated to produce a warning
+  ///         informing the user the upcast should be performed using the target base node's initializer.
+  @available(*, deprecated, message: "Use `PatternSyntax.init` for upcasting")
+  public func cast(_ syntaxType: PatternSyntax.Type) -> PatternSyntax {
+    return PatternSyntax(self)
+  }
+  
+
   /// Checks if the current syntax node can be cast to a given node type from the different base node protocol hierarchy than ``PatternSyntaxProtocol``.
   ///
   /// - Returns: `false` since the node can not be cast to the node type from different base node protocol hierarchy than ``PatternSyntaxProtocol``.
@@ -830,6 +938,42 @@ extension StmtSyntaxProtocol {
   }
 
 
+  /// Checks if the current syntax node can be upcast to its base node type (``StmtSyntax``).
+  ///
+  /// - Returns: `true` since the node can always be upcast to its base node.
+  ///
+  /// - Note: This method overloads the general `is` method and is marked deprecated to produce a warning
+  ///         informing the user that the upcast will always succeed.
+  @available(*, deprecated, message: "This cast will always succeed")
+  public func `is`(_ syntaxType: StmtSyntax.Type) -> Bool {
+    return true
+  }
+  
+
+  /// Attempts to upcast the current syntax node to its base node type (``StmtSyntax``).
+  ///
+  /// - Returns: The base node created from the current syntax node, as the node can always be upcast to its base type.
+  ///
+  /// - Note: This method overloads the general `as` method and is marked deprecated to produce a warning
+  ///         informing the user the upcast should be performed using the target base node's initializer.
+  @available(*, deprecated, message: "Use `StmtSyntax.init` for upcasting")
+  public func `as`(_ syntaxType: StmtSyntax.Type) -> StmtSyntax? {
+    return StmtSyntax(self)
+  }
+  
+
+  /// Force-upcast the current syntax node to its base node type (``StmtSyntax``).
+  ///
+  /// - Returns: The base node created from the current syntax node, as the node can always be upcast to its base type.
+  ///
+  /// - Note: This method overloads the general `as` method and is marked deprecated to produce a warning
+  ///         informing the user the upcast should be performed using the target base node's initializer.
+  @available(*, deprecated, message: "Use `StmtSyntax.init` for upcasting")
+  public func cast(_ syntaxType: StmtSyntax.Type) -> StmtSyntax {
+    return StmtSyntax(self)
+  }
+  
+
   /// Checks if the current syntax node can be cast to a given node type from the different base node protocol hierarchy than ``StmtSyntaxProtocol``.
   ///
   /// - Returns: `false` since the node can not be cast to the node type from different base node protocol hierarchy than ``StmtSyntaxProtocol``.
@@ -1075,6 +1219,42 @@ extension TypeSyntaxProtocol {
   }
 
 
+  /// Checks if the current syntax node can be upcast to its base node type (``TypeSyntax``).
+  ///
+  /// - Returns: `true` since the node can always be upcast to its base node.
+  ///
+  /// - Note: This method overloads the general `is` method and is marked deprecated to produce a warning
+  ///         informing the user that the upcast will always succeed.
+  @available(*, deprecated, message: "This cast will always succeed")
+  public func `is`(_ syntaxType: TypeSyntax.Type) -> Bool {
+    return true
+  }
+  
+
+  /// Attempts to upcast the current syntax node to its base node type (``TypeSyntax``).
+  ///
+  /// - Returns: The base node created from the current syntax node, as the node can always be upcast to its base type.
+  ///
+  /// - Note: This method overloads the general `as` method and is marked deprecated to produce a warning
+  ///         informing the user the upcast should be performed using the target base node's initializer.
+  @available(*, deprecated, message: "Use `TypeSyntax.init` for upcasting")
+  public func `as`(_ syntaxType: TypeSyntax.Type) -> TypeSyntax? {
+    return TypeSyntax(self)
+  }
+  
+
+  /// Force-upcast the current syntax node to its base node type (``TypeSyntax``).
+  ///
+  /// - Returns: The base node created from the current syntax node, as the node can always be upcast to its base type.
+  ///
+  /// - Note: This method overloads the general `as` method and is marked deprecated to produce a warning
+  ///         informing the user the upcast should be performed using the target base node's initializer.
+  @available(*, deprecated, message: "Use `TypeSyntax.init` for upcasting")
+  public func cast(_ syntaxType: TypeSyntax.Type) -> TypeSyntax {
+    return TypeSyntax(self)
+  }
+  
+
   /// Checks if the current syntax node can be cast to a given node type from the different base node protocol hierarchy than ``TypeSyntaxProtocol``.
   ///
   /// - Returns: `false` since the node can not be cast to the node type from different base node protocol hierarchy than ``TypeSyntaxProtocol``.