Issue checkstyle#9936: Deprecate 'DetailAST.branchContains`

config/checkstyle_checks.xml

@@ -417,6 +417,13 @@
       <property name="query" value="//ANNOTATION[./IDENT[@text='Issue']]"/>
       <message key="matchxpath.match" value="Avoid using @Issue annotation."/>
     </module>
+    <!-- until https://github.com/checkstyle/checkstyle/issues/5234 -->
+    <module name="MatchXpath">
+      <property name="id" value="MatchXPathBranchContains"/>
+      <property name="query" value="//METHOD_CALL//DOT[.//IDENT[@text = 'branchContains']]"/>
+      <message key="matchxpath.match"
+               value="Avoid using deprecated method 'DetailAst.branchContains()'."/>
+    </module>
     <module name="MissingCtor">
       <!--
         we will not use that fanatic validation, extra code is not good

config/suppressions.xml

@@ -113,4 +113,7 @@
   <!-- Usage of unicode characters to assert the functioning of Xpath on escape character.  -->
   <suppress id="RegexpSinglelineJava" files="[\\/]XpathQueryGeneratorTest.java"/>
 
+  <!-- until https://github.com/checkstyle/checkstyle/issues/5234 -->
+  <suppress id="MatchXPathBranchContains" files="[\\/]DetailAstImplTest.java"/>
+
 </suppressions>

src/main/java/com/puppycrawl/tools/checkstyle/api/DetailAST.java

@@ -90,10 +90,15 @@ public interface DetailAST {
      * Checks if this branch of the parse tree contains a token
      * of the provided type.
      *
+     * @deprecated
+     *      Usage of this method is no longer accepted. We encourage
+     *      traversal of subtrees to be written per the needs of each check
+     *      to avoid unintended side effects.
      * @param type a TokenType
      * @return true if and only if this branch (including this node)
      *     contains a token of type {@code type}.
      */
+    @Deprecated
     boolean branchContains(int type);
 
     /**