///////////////////////////////////////////////////////////////////////////////////////////////
// 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);
        }
    }

}