///////////////////////////////////////////////////////////////////////////////////////////////
// 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.Arrays;
import java.util.BitSet;

import com.puppycrawl.tools.checkstyle.PropertyType;
import com.puppycrawl.tools.checkstyle.StatelessCheck;
import com.puppycrawl.tools.checkstyle.XdocsPropertyType;
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.CheckUtil;
import com.puppycrawl.tools.checkstyle.utils.CommonUtil;
import com.puppycrawl.tools.checkstyle.utils.ScopeUtil;
import com.puppycrawl.tools.checkstyle.utils.TokenUtil;

/**
 * <div>
 * Checks that there are no
 * <a href="https://en.wikipedia.org/wiki/Magic_number_%28programming%29">
 * {@code "magic number"}</a> where a magic
 * number is a numeric literal that is not defined as a constant.
 * By default, -1, 0, 1, and 2 are not considered to be magic numbers.
 * </div>
 *
 * <p>Constant definition is any variable/field that has 'final' modifier.
 * It is fine to have one constant defining multiple numeric literals within one expression:
 * </p>
 * {@snippet lang="text" :
 * static final int SECONDS_PER_DAY = 24 * 60 * 60;
 * static final double SPECIAL_RATIO = 4.0 / 3.0;
 * static final double SPECIAL_SUM = 1 + Math.E;
 * static final double SPECIAL_DIFFERENCE = 4 - Math.PI;
 * static final Border STANDARD_BORDER = BorderFactory.createEmptyBorder(3, 3, 3, 3);
 * static final Integer ANSWER_TO_THE_ULTIMATE_QUESTION_OF_LIFE = new Integer(42);
 * }
 *
 * @since 3.1
 */
@StatelessCheck
public class MagicNumberCheck extends AbstractCheck {

    /**
     * A key is pointing to the warning message text in "messages.properties" file.
     */
    public static final String MSG_KEY = "magic.number";

    /**
     * Specify tokens that are allowed in the AST path from the
     * number literal to the enclosing constant definition.
     */
    @XdocsPropertyType(PropertyType.TOKEN_ARRAY)
    private BitSet constantWaiverParentToken = TokenUtil.asBitSet(
        TokenTypes.ASSIGN,
        TokenTypes.ARRAY_INIT,
        TokenTypes.EXPR,
        TokenTypes.UNARY_PLUS,
        TokenTypes.UNARY_MINUS,
        TokenTypes.TYPECAST,
        TokenTypes.ELIST,
        TokenTypes.LITERAL_NEW,
        TokenTypes.METHOD_CALL,
        TokenTypes.STAR,
        TokenTypes.DIV,
        TokenTypes.PLUS,
        TokenTypes.MINUS,
        TokenTypes.QUESTION,
        TokenTypes.COLON,
        TokenTypes.EQUAL,
        TokenTypes.NOT_EQUAL,
        TokenTypes.MOD,
        TokenTypes.SR,
        TokenTypes.BSR,
        TokenTypes.GE,
        TokenTypes.GT,
        TokenTypes.SL,
        TokenTypes.LE,
        TokenTypes.LT,
        TokenTypes.BXOR,
        TokenTypes.BOR,
        TokenTypes.BNOT,
        TokenTypes.BAND
    );

    /** Specify non-magic numbers. */
    private double[] ignoreNumbers = {-1, 0, 1, 2};

    /** Ignore magic numbers in hashCode methods. */
    private boolean ignoreHashCodeMethod;

    /** Ignore magic numbers in annotation declarations. */
    private boolean ignoreAnnotation;

    /** Ignore magic numbers in field declarations. */
    private boolean ignoreFieldDeclaration;

    /** Ignore magic numbers in annotation elements defaults. */
    private boolean ignoreAnnotationElementDefaults = true;

    /**
     * Creates a new {@code MagicNumberCheck} instance.
     */
    public MagicNumberCheck() {
        // no code by default
    }

    @Override
    public int[] getDefaultTokens() {
        return getAcceptableTokens();
    }

    @Override
    public int[] getAcceptableTokens() {
        return new int[] {
            TokenTypes.NUM_DOUBLE,
            TokenTypes.NUM_FLOAT,
            TokenTypes.NUM_INT,
            TokenTypes.NUM_LONG,
        };
    }

    @Override
    public int[] getRequiredTokens() {
        return CommonUtil.EMPTY_INT_ARRAY;
    }

    @Override
    public void visitToken(DetailAST ast) {
        if (shouldTestAnnotationArgs(ast)
                && shouldTestAnnotationDefaults(ast)
                && !isInIgnoreList(ast)
                && shouldCheckHashCodeMethod(ast)
                && shouldCheckFieldDeclaration(ast)) {
            final DetailAST constantDefAST = findContainingConstantDef(ast);
            if (isMagicNumberExists(ast, constantDefAST)) {
                reportMagicNumber(ast);
            }
        }
    }

    /**
     * Checks if ast is annotation argument and should be checked.
     *
     * @param ast token to check
     * @return true if element is skipped, false otherwise
     */
    private boolean shouldTestAnnotationArgs(DetailAST ast) {
        return !ignoreAnnotation || !isChildOf(ast, TokenTypes.ANNOTATION);
    }

    /**
     * Checks if ast is annotation element default value and should be checked.
     *
     * @param ast token to check
     * @return true if element is skipped, false otherwise
     */
    private boolean shouldTestAnnotationDefaults(DetailAST ast) {
        return !ignoreAnnotationElementDefaults || !isChildOf(ast, TokenTypes.LITERAL_DEFAULT);
    }

    /**
     * Checks if the given AST node is a HashCode Method and should be checked.
     *
     * @param ast the AST node to check
     * @return true if element should be checked, false otherwise
     */
    private boolean shouldCheckHashCodeMethod(DetailAST ast) {
        return !ignoreHashCodeMethod || !isInHashCodeMethod(ast);
    }

    /**
     * Checks if the given AST node is a field declaration and should be checked.
     *
     * @param ast the AST node to check
     * @return true if element should be checked, false otherwise
     */
    private boolean shouldCheckFieldDeclaration(DetailAST ast) {
        return !ignoreFieldDeclaration || !isFieldDeclaration(ast);
    }

    /**
     * Is magic number somewhere at ast tree.
     *
     * @param ast ast token
     * @param constantDefAST constant ast
     * @return true if magic number is present
     */
    private boolean isMagicNumberExists(DetailAST ast, DetailAST constantDefAST) {
        boolean found = false;
        DetailAST astNode = ast.getParent();
        while (astNode != constantDefAST) {
            final int type = astNode.getType();

            if (!constantWaiverParentToken.get(type)) {
                found = true;
                break;
            }

            astNode = astNode.getParent();
        }
        return found;
    }

    /**
     * Finds the constant definition that contains aAST.
     *
     * @param ast the AST
     * @return the constant def or null if ast is not contained in a constant definition.
     */
    private static DetailAST findContainingConstantDef(DetailAST ast) {
        DetailAST varDefAST = ast;
        while (varDefAST != null
                && varDefAST.getType() != TokenTypes.VARIABLE_DEF
                && varDefAST.getType() != TokenTypes.ENUM_CONSTANT_DEF) {
            varDefAST = varDefAST.getParent();
        }
        DetailAST constantDef = null;

        // no containing variable definition?
        if (varDefAST != null) {
            // implicit constant?
            if (ScopeUtil.isInInterfaceOrAnnotationBlock(varDefAST)
                    || varDefAST.getType() == TokenTypes.ENUM_CONSTANT_DEF) {
                constantDef = varDefAST;
            }
            else {
                // explicit constant
                final DetailAST modifiersAST = varDefAST.findFirstToken(TokenTypes.MODIFIERS);

                if (modifiersAST.findFirstToken(TokenTypes.FINAL) != null) {
                    constantDef = varDefAST;
                }
            }
        }
        return constantDef;
    }

    /**
     * Reports aAST as a magic number, includes unary operators as needed.
     *
     * @param ast the AST node that contains the number to report
     */
    private void reportMagicNumber(DetailAST ast) {
        String text = ast.getText();
        final DetailAST parent = ast.getParent();
        DetailAST reportAST = ast;
        if (parent.getType() == TokenTypes.UNARY_MINUS) {
            reportAST = parent;
            text = "-" + text;
        }
        else if (parent.getType() == TokenTypes.UNARY_PLUS) {
            reportAST = parent;
            text = "+" + text;
        }
        log(reportAST,
                MSG_KEY,
                text);
    }

    /**
     * Determines whether or not the given AST is in a valid hash code method.
     * A valid hash code method is considered to be a method of the signature
     * {@code public int hashCode()}.
     *
     * @param ast the AST from which to search for an enclosing hash code method definition
     *
     * @return {@code true} if {@code ast} is in the scope of a valid hash code method.
     */
    private static boolean isInHashCodeMethod(DetailAST ast) {
        // find the method definition AST
        DetailAST currentAST = ast;
        while (currentAST != null
                && currentAST.getType() != TokenTypes.METHOD_DEF) {
            currentAST = currentAST.getParent();
        }
        final DetailAST methodDefAST = currentAST;
        boolean inHashCodeMethod = false;

        if (methodDefAST != null) {
            // Check for 'hashCode' name.
            final DetailAST identAST = methodDefAST.findFirstToken(TokenTypes.IDENT);

            if ("hashCode".equals(identAST.getText())) {
                // Check for no arguments.
                final DetailAST paramAST = methodDefAST.findFirstToken(TokenTypes.PARAMETERS);
                // we are in a 'public int hashCode()' method! The compiler will ensure
                // the method returns an 'int' and is public.
                inHashCodeMethod = !paramAST.hasChildren();
            }
        }
        return inHashCodeMethod;
    }

    /**
     * Decides whether the number of an AST is in the ignore list of this check.
     *
     * @param ast the AST to check
     * @return true if the number of ast is in the ignore list of this check.
     */
    private boolean isInIgnoreList(DetailAST ast) {
        double value = CheckUtil.parseDouble(ast.getText(), ast.getType());
        final DetailAST parent = ast.getParent();
        if (parent.getType() == TokenTypes.UNARY_MINUS) {
            value = -1 * value;
        }
        return Arrays.binarySearch(ignoreNumbers, value) >= 0;
    }

    /**
     * Determines whether or not the given AST is field declaration.
     *
     * @param ast AST from which to search for an enclosing field declaration
     *
     * @return {@code true} if {@code ast} is in the scope of field declaration
     */
    private static boolean isFieldDeclaration(DetailAST ast) {
        DetailAST varDefAST = null;
        DetailAST node = ast;
        while (node != null && node.getType() != TokenTypes.OBJBLOCK) {
            if (node.getType() == TokenTypes.VARIABLE_DEF) {
                varDefAST = node;
                break;
            }
            node = node.getParent();
        }

        boolean result = false;

        if (varDefAST != null) {
            final DetailAST parent = varDefAST.getParent();

            if (parent.getType() == TokenTypes.COMPACT_COMPILATION_UNIT) {
                result = true;
            }
            else {
                final DetailAST grandParent = parent.getParent();

                result = grandParent.getType() == TokenTypes.CLASS_DEF
                    || grandParent.getType() == TokenTypes.RECORD_DEF
                    || grandParent.getType() == TokenTypes.LITERAL_NEW;
            }
        }

        return result;
    }

    /**
     * Setter to specify tokens that are allowed in the AST path from the
     * number literal to the enclosing constant definition.
     *
     * @param tokens The string representation of the tokens interested in
     * @since 6.11
     */
    public void setConstantWaiverParentToken(String... tokens) {
        constantWaiverParentToken = TokenUtil.asBitSet(tokens);
    }

    /**
     * Setter to specify non-magic numbers.
     *
     * @param list numbers to ignore.
     * @since 3.1
     */
    public void setIgnoreNumbers(double... list) {
        ignoreNumbers = new double[list.length];
        System.arraycopy(list, 0, ignoreNumbers, 0, list.length);
        Arrays.sort(ignoreNumbers);
    }

    /**
     * Setter to ignore magic numbers in hashCode methods.
     *
     * @param ignoreHashCodeMethod decide whether to ignore hash code methods
     * @since 5.3
     */
    public void setIgnoreHashCodeMethod(boolean ignoreHashCodeMethod) {
        this.ignoreHashCodeMethod = ignoreHashCodeMethod;
    }

    /**
     * Setter to ignore magic numbers in annotation declarations.
     *
     * @param ignoreAnnotation decide whether to ignore annotations
     * @since 5.4
     */
    public void setIgnoreAnnotation(boolean ignoreAnnotation) {
        this.ignoreAnnotation = ignoreAnnotation;
    }

    /**
     * Setter to ignore magic numbers in field declarations.
     *
     * @param ignoreFieldDeclaration decide whether to ignore magic numbers in field declaration
     * @since 6.6
     */
    public void setIgnoreFieldDeclaration(boolean ignoreFieldDeclaration) {
        this.ignoreFieldDeclaration = ignoreFieldDeclaration;
    }

    /**
     * Setter to ignore magic numbers in annotation elements defaults.
     *
     * @param ignoreAnnotationElementDefaults decide whether to ignore annotation elements defaults
     * @since 8.23
     */
    public void setIgnoreAnnotationElementDefaults(boolean ignoreAnnotationElementDefaults) {
        this.ignoreAnnotationElementDefaults = ignoreAnnotationElementDefaults;
    }

    /**
     * Determines if the given AST node has a parent node with given token type code.
     *
     * @param ast the AST from which to search for annotations
     * @param type the type code of parent token
     *
     * @return {@code true} if the AST node has a parent with given token type.
     */
    private static boolean isChildOf(DetailAST ast, int type) {
        boolean result = false;
        DetailAST node = ast;
        do {
            if (node.getType() == type) {
                result = true;
                break;
            }
            node = node.getParent();
        } while (node != null);

        return result;
    }

}