///////////////////////////////////////////////////////////////////////////////////////////////
   // checkstyle: Checks Java source code and other text files for adherence to a set of rules.
   // Copyright (C) 2001-2025 the original author or authors.
   //
   // This library is free software; you can redistribute it and/or
   // modify it under the terms of the GNU Lesser General Public
   // License as published by the Free Software Foundation; either
   // version 2.1 of the License, or (at your option) any later version.
   //
  // This library is distributed in the hope that it will be useful,
  // but WITHOUT ANY WARRANTY; without even the implied warranty of
  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  // Lesser General Public License for more details.
  //
  // You should have received a copy of the GNU Lesser General Public
  // License along with this library; if not, write to the Free Software
  // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  ///////////////////////////////////////////////////////////////////////////////////////////////
  
  package com.puppycrawl.tools.checkstyle.checks.coding;
  
  import java.util.Optional;
  
  import com.puppycrawl.tools.checkstyle.StatelessCheck;
  import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
  import com.puppycrawl.tools.checkstyle.api.DetailAST;
  import com.puppycrawl.tools.checkstyle.api.TokenTypes;
  
  /**
   * <div>
   * Checks for redundant null checks with the instanceof operator.
   * </div>
   *
   * <p>
   * The instanceof operator inherently returns false when the left operand is null,
   * making explicit null checks redundant in boolean expressions with instanceof.
   * </p>
   *
   * <p>
   * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker}
   * </p>
   *
   * <p>
   * Violation Message Keys:
   * </p>
   *
   * <ul>
   *   <li>
   *     {@code unnecessary.nullcheck.with.instanceof}
   *   </li>
   * </ul>
   *
   * @since 10.25.0
   */
  @StatelessCheck
  public class UnnecessaryNullCheckWithInstanceOfCheck extends AbstractCheck {
  
      /**
       * The error message key for reporting unnecessary null checks.
       */
      public static final String MSG_UNNECESSARY_NULLCHECK = "unnecessary.nullcheck.with.instanceof";
  
      @Override
      public int[] getDefaultTokens() {
          return getRequiredTokens();
      }
  
      @Override
      public int[] getAcceptableTokens() {
          return getRequiredTokens();
      }
  
      @Override
      public int[] getRequiredTokens() {
          return new int[] {TokenTypes.LITERAL_INSTANCEOF};
      }
  
      @Override
      public void visitToken(DetailAST instanceofNode) {
          findUnnecessaryNullCheck(instanceofNode)
                  .ifPresent(violationNode -> log(violationNode, MSG_UNNECESSARY_NULLCHECK));
      }
  
      /**
       * Checks for an unnecessary null check within a logical AND expression.
       *
       * @param instanceOfNode the AST node representing the instanceof expression
       * @return the identifier if the check is redundant, otherwise {@code null}
       */
      private static Optional<DetailAST> findUnnecessaryNullCheck(DetailAST instanceOfNode) {
          DetailAST currentParent = instanceOfNode;
  
          while (currentParent.getParent().getType() == TokenTypes.LAND) {
              currentParent = currentParent.getParent();
          }
          return findRedundantNullCheck(currentParent, instanceOfNode)
              .map(DetailAST::getFirstChild);
      }
  
     /**
      * Finds a redundant null check in a logical AND expression combined with an instanceof check.
      *
      * @param logicalAndNode the root node of the logical AND expression
      * @param instanceOfNode the instanceof expression node
      * @return the AST node representing the redundant null check, or null if not found
      */
     private static Optional<DetailAST> findRedundantNullCheck(DetailAST logicalAndNode,
         DetailAST instanceOfNode) {
 
         DetailAST nullCheckNode = null;
         final DetailAST instanceOfIdent = instanceOfNode.findFirstToken(TokenTypes.IDENT);
 
         if (instanceOfIdent != null
             && !containsVariableDereference(logicalAndNode, instanceOfIdent.getText())) {
 
             DetailAST currentChild = logicalAndNode.getFirstChild();
             while (currentChild != null) {
                 if (isNotEqual(currentChild)
                         && isNullCheckRedundant(instanceOfIdent, currentChild)) {
                     nullCheckNode = currentChild;
                 }
                 else if (nullCheckNode == null && currentChild.getType() == TokenTypes.LAND) {
                     nullCheckNode = findRedundantNullCheck(currentChild, instanceOfNode)
                             .orElse(null);
                 }
                 currentChild = currentChild.getNextSibling();
             }
         }
         return Optional.ofNullable(nullCheckNode);
     }
 
     /**
      * Checks if the given AST node contains a method call or field access
      * on the specified variable.
      *
      * @param node the AST node to check
      * @param variableName the name of the variable
      * @return true if the variable is dereferenced, false otherwise
      */
     private static boolean containsVariableDereference(DetailAST node, String variableName) {
 
         boolean found = false;
 
         if (node.getType() == TokenTypes.DOT
             || node.getType() == TokenTypes.METHOD_CALL || node.getType() == TokenTypes.LAND) {
 
             DetailAST firstChild = node.getFirstChild();
 
             while (firstChild != null) {
                 if (variableName.equals(firstChild.getText())
                         && firstChild.getNextSibling().getType() != TokenTypes.ELIST
                             || containsVariableDereference(firstChild, variableName)) {
                     found = true;
                     break;
                 }
                 firstChild = firstChild.getNextSibling();
             }
         }
         return found;
     }
 
     /**
      * Checks if the given AST node represents a {@code !=} (not equal) operator.
      *
      * @param node the AST node to check
      * @return {@code true} if the node is a not equal operator, otherwise {@code false}
      */
     private static boolean isNotEqual(DetailAST node) {
         return node.getType() == TokenTypes.NOT_EQUAL;
     }
 
     /**
      * Checks if the given AST node is a null literal.
      *
      * @param node AST node to check
      * @return true if the node is a null literal, false otherwise
      */
     private static boolean isNullLiteral(DetailAST node) {
         return node.getType() == TokenTypes.LITERAL_NULL;
     }
 
     /**
      * Determines if the null check is redundant with the instanceof check.
      *
      * @param instanceOfIdent the identifier from the instanceof check
      * @param nullCheckNode the node representing the null check
      * @return true if the null check is unnecessary, false otherwise
      */
     private static boolean isNullCheckRedundant(DetailAST instanceOfIdent,
         final DetailAST nullCheckNode) {
 
         final DetailAST nullCheckIdent = nullCheckNode.findFirstToken(TokenTypes.IDENT);
         return nullCheckIdent != null
                 && (isNullLiteral(nullCheckNode.getFirstChild().getNextSibling())
                     || isNullLiteral(nullCheckNode.getFirstChild()))
                 && instanceOfIdent.getText().equals(nullCheckIdent.getText());
     }
 }