///////////////////////////////////////////////////////////////////////////////////////////////
   // checkstyle: Checks Java source code and other text files for adherence to a set of rules.
   // Copyright (C) 2001-2026 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.ArrayList;
  import java.util.Collection;
  import java.util.List;
  import java.util.Set;
  
  import javax.annotation.Nullable;
  
  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;
  import com.puppycrawl.tools.checkstyle.utils.TokenUtil;
  
  /**
   * <div>
   * Checks for assignment of pattern variables.
   * </div>
   *
   * <p>
   * Pattern variable assignment is considered bad programming practice. The pattern variable
   * is meant to be a direct reference to the object being matched. Reassigning it can break this
   * connection and mislead readers.
   * </p>
   *
   * @since 10.26.0
   */
  @StatelessCheck
  public class PatternVariableAssignmentCheck extends AbstractCheck {
  
      /**
       * A key is pointing to the warning message in "messages.properties" file.
       */
      public static final String MSG_KEY = "pattern.variable.assignment";
  
      /**
       * The set of all valid types of ASSIGN token for this check.
       */
      private static final Set<Integer> ASSIGN_TOKEN_TYPES = Set.of(
          TokenTypes.ASSIGN, TokenTypes.PLUS_ASSIGN, TokenTypes.MINUS_ASSIGN, TokenTypes.STAR_ASSIGN,
          TokenTypes.DIV_ASSIGN, TokenTypes.MOD_ASSIGN, TokenTypes.SR_ASSIGN, TokenTypes.BSR_ASSIGN,
          TokenTypes.SL_ASSIGN, TokenTypes.BAND_ASSIGN, TokenTypes.BXOR_ASSIGN,
          TokenTypes.BOR_ASSIGN);
  
      @Override
      public int[] getRequiredTokens() {
          return new int[] {TokenTypes.LITERAL_INSTANCEOF};
      }
  
      @Override
      public int[] getDefaultTokens() {
          return getRequiredTokens();
      }
  
      @Override
      public int[] getAcceptableTokens() {
          return getRequiredTokens();
      }
  
      @Override
      public void visitToken(DetailAST ast) {
  
          final List<DetailAST> patternVariableIdents = getPatternVariableIdents(ast);
          final List<DetailAST> reassignedVariableIdents = getReassignedVariableIdents(ast);
  
          for (DetailAST patternVariableIdent : patternVariableIdents) {
              checkForReassignment(patternVariableIdent, reassignedVariableIdents);
          }
      }
  
      /**
       * Gets the list of all pattern variable idents in instanceof expression.
       *
       * @param ast ast tree of instanceof to get the list from.
       * @return list of pattern variables.
       */
      private static List<DetailAST> getPatternVariableIdents(DetailAST ast) {
  
          final DetailAST outermostPatternVariable =
             ast.findFirstToken(TokenTypes.PATTERN_VARIABLE_DEF);
 
         final DetailAST recordPatternDef;
         if (ast.getType() == TokenTypes.LITERAL_INSTANCEOF) {
             recordPatternDef = ast.findFirstToken(TokenTypes.RECORD_PATTERN_DEF);
         }
         else {
             recordPatternDef = ast;
         }
 
         final List<DetailAST> patternVariableIdentsArray = new ArrayList<>();
 
         if (outermostPatternVariable != null) {
             patternVariableIdentsArray.add(
                 outermostPatternVariable.findFirstToken(TokenTypes.IDENT));
         }
         else if (recordPatternDef != null) {
             final DetailAST recordPatternComponents = recordPatternDef
                 .findFirstToken(TokenTypes.RECORD_PATTERN_COMPONENTS);
 
             if (recordPatternComponents != null) {
                 for (DetailAST innerPatternVariable = recordPatternComponents.getFirstChild();
                      innerPatternVariable != null;
                      innerPatternVariable = innerPatternVariable.getNextSibling()) {
 
                     if (innerPatternVariable.getType() == TokenTypes.PATTERN_VARIABLE_DEF) {
                         patternVariableIdentsArray.add(
                             innerPatternVariable.findFirstToken(TokenTypes.IDENT));
                     }
                     else {
                         patternVariableIdentsArray.addAll(
                             getPatternVariableIdents(innerPatternVariable));
                     }
 
                 }
             }
 
         }
         return patternVariableIdentsArray;
     }
 
     /**
      * Gets the list of AST branches of reassigned variable identifiers.
      *
      * @param ast ast tree of checked instanceof statement
      * @return list of AST identifiers that represent reassigned variables
      */
     private static List<DetailAST> getReassignedVariableIdents(DetailAST ast) {
 
         final List<DetailAST> reassignedVariableIdents = new ArrayList<>();
         final DetailAST scopeRoot = findReassignmentScopeRoot(ast);
 
         if (scopeRoot != null) {
 
             final List<DetailAST> branches =
                     expandReassignmentScopes(scopeRoot);
 
             for (DetailAST branch : branches) {
                 for (DetailAST expressionBranch = branch;
                      expressionBranch != null;
                      expressionBranch = traverseUntilNeededBranchType(
                              expressionBranch, branch, TokenTypes.EXPR)) {
 
                     final DetailAST assignToken =
                             getMatchedAssignToken(expressionBranch);
 
                     if (assignToken != null) {
                         final DetailAST neededAssignIdent =
                                 getNeededAssignIdent(assignToken);
 
                         if (neededAssignIdent.getPreviousSibling() == null) {
                             reassignedVariableIdents.add(neededAssignIdent);
                         }
                     }
                 }
             }
         }
 
         return reassignedVariableIdents;
     }
 
     /**
      * Gets statements that follow the conditional where pattern variable scope extends.
      * Only returns top-level statements that are siblings of the conditional, excluding
      * statements nested in control structures like while loops.
      *
      * @param conditionalStatement The if statement.
      * @return List of statement nodes in the extended scope.
      */
     private static List<DetailAST> getStatementsInExtendedScope(DetailAST conditionalStatement) {
         final List<DetailAST> statements = new ArrayList<>();
 
         DetailAST nextSibling = conditionalStatement.getNextSibling();
 
         while (nextSibling != null) {
             final int type = nextSibling.getType();
             if (type == TokenTypes.EXPR || type == TokenTypes.LITERAL_RETURN
                     || type == TokenTypes.LITERAL_IF) {
                 statements.add(nextSibling);
             }
             else if (type != TokenTypes.SEMI) {
                 break;
             }
             nextSibling = nextSibling.getNextSibling();
         }
 
         return statements;
     }
 
     /**
      * Traverses along the AST tree to locate the first branch of certain token type.
      *
      * @param startingBranch AST branch to start the traverse from, but not check.
      * @param bound AST Branch that the traverse cannot further extend to.
      * @param neededTokenType Token type whose first encountered branch is to look for.
      * @return the AST tree of first encountered branch of needed token type.
      */
     @Nullable
     private static DetailAST traverseUntilNeededBranchType(DetailAST startingBranch,
                               DetailAST bound, int neededTokenType) {
 
         DetailAST match = null;
 
         DetailAST iteratedBranch = shiftToNextTraversedBranch(startingBranch, bound);
 
         while (iteratedBranch != null) {
             if (iteratedBranch.getType() == neededTokenType) {
                 match = iteratedBranch;
                 break;
             }
 
             iteratedBranch = shiftToNextTraversedBranch(iteratedBranch, bound);
         }
 
         return match;
     }
 
     /**
      * Shifts once to the next possible branch within traverse trajectory.
      *
      * @param ast AST branch to shift from.
      * @param boundAst AST Branch that the traverse cannot further extend to.
      * @return the AST tree of next possible branch within traverse trajectory.
      */
     @Nullable
     private static DetailAST shiftToNextTraversedBranch(DetailAST ast, DetailAST boundAst) {
         DetailAST newAst = ast;
 
         if (ast.getFirstChild() != null) {
             newAst = ast.getFirstChild();
         }
         else {
             while (newAst.getNextSibling() == null && !newAst.equals(boundAst)) {
                 newAst = newAst.getParent();
             }
             if (newAst.equals(boundAst)) {
                 newAst = null;
             }
             else {
                 newAst = newAst.getNextSibling();
             }
         }
 
         return newAst;
     }
 
     /**
      * Gets the type of ASSIGN tokens that particularly matches with what follows the preceding
      * branch.
      *
      * @param preAssignBranch branch that precedes the branch of ASSIGN token types.
      * @return type of ASSIGN token.
      */
     @Nullable
     private static DetailAST getMatchedAssignToken(DetailAST preAssignBranch) {
         DetailAST matchedAssignToken = null;
 
         for (int assignType : ASSIGN_TOKEN_TYPES) {
             matchedAssignToken = preAssignBranch.findFirstToken(assignType);
             if (matchedAssignToken != null) {
                 break;
             }
         }
 
         return matchedAssignToken;
     }
 
     /**
      * Gets the needed AST Ident of reassigned variable for check to compare.
      *
      * @param assignToken The AST branch of reassigned variable's ASSIGN token.
      * @return needed AST Ident.
      */
     private static DetailAST getNeededAssignIdent(DetailAST assignToken) {
         DetailAST assignIdent = assignToken;
 
         while (traverseUntilNeededBranchType(
             assignIdent, assignToken.getFirstChild(), TokenTypes.IDENT) != null) {
 
             assignIdent =
                 traverseUntilNeededBranchType(assignIdent, assignToken, TokenTypes.IDENT);
         }
 
         return assignIdent;
     }
 
     /**
      * Checks whether a pattern variable is reassigned and logs a violation if so.
      *
      * @param patternVariableIdent AST ident of the pattern variable
      * @param reassignedVariableIdents list of AST idents that represent reassigned variables
      */
     private void checkForReassignment(
             DetailAST patternVariableIdent,
             Iterable<DetailAST> reassignedVariableIdents) {
 
         for (DetailAST assignTokenIdent : reassignedVariableIdents) {
             if (patternVariableIdent.getText().equals(assignTokenIdent.getText())) {
                 log(assignTokenIdent, MSG_KEY, assignTokenIdent.getText());
             }
         }
     }
 
     /**
      * Finds the nearest AST node that defines the scope in which reassignment
      * of a pattern variable may occur.
      *
      * <p>
      * The scope is determined by locating the closest enclosing conditional
      * structure such as {@code if}, {@code else}, or ternary operator.
      * </p>
      *
      * @param ast the AST node to start searching from
      * @return the AST node representing the reassignment scope root,
      *         or {@code null} if none is found
      */
     @Nullable
     private static DetailAST findReassignmentScopeRoot(DetailAST ast) {
 
         DetailAST result = null;
 
         for (DetailAST node = ast; node != null && result == null;
              node = node.getParent()) {
 
             final int type = node.getType();
 
             if (type == TokenTypes.LITERAL_IF
                     || type == TokenTypes.LITERAL_ELSE
                     || type == TokenTypes.QUESTION) {
                 result = node;
             }
         }
 
         return result;
     }
 
     /**
      * Expands the reassignment scope root into concrete AST branches
      * that may contain reassigned pattern variables.
      *
      * <p>
      * For ternary expressions, the conditional expression itself is
      * treated as the reassignment scope. For {@code if} / {@code else}
      * statements, the method includes the statement list and any
      * subsequent statements where the pattern variable remains in scope.
      * </p>
      *
      * @param scopeRoot the root AST node of the reassignment scope
      * @return list of AST branches that may contain reassignments
      */
     private static List<DetailAST> expandReassignmentScopes(
             DetailAST scopeRoot) {
 
         final List<DetailAST> branches = new ArrayList<>();
 
         addBodyBranch(branches, scopeRoot);
         branches.addAll(getStatementsInExtendedScope(scopeRoot));
 
         return branches;
     }
 
     /**
      * Adds the body branch of a conditional (if/else) to the list.
      * For braced blocks, adds the SLIST. For unbraced statements,
      * adds the single statement directly.
      *
      * @param branches collection to add the body branch to
      * @param scopeRoot the if/else AST node
      */
     private static void addBodyBranch(Collection<DetailAST> branches,
             DetailAST scopeRoot) {
         if (scopeRoot.getType() == TokenTypes.LITERAL_IF) {
             final DetailAST body = TokenUtil.findFirstTokenByPredicate(scopeRoot,
                     node -> node.getType() == TokenTypes.RPAREN)
                     .map(DetailAST::getNextSibling)
                     .orElse(scopeRoot);
             branches.add(body);
         }
         else {
             branches.add(scopeRoot);
         }
     }
 
 }