/**
 * @fileoverview Rule to flag declared but unused variables
 * @author Ilya Volodin
 */

"use strict";

//------------------------------------------------------------------------------
// Requirements
//------------------------------------------------------------------------------

const astUtils = require("./utils/ast-utils");

//------------------------------------------------------------------------------
// Typedefs
//------------------------------------------------------------------------------

/**
 * A simple name for the types of variables that this rule supports
 * @typedef {'array-destructure'|'catch-clause'|'parameter'|'variable'} VariableType
 */

/**
 * Bag of data used for formatting the `unusedVar` lint message.
 * @typedef {Object} UnusedVarMessageData
 * @property {string} varName The name of the unused var.
 * @property {'defined'|'assigned a value'} action Description of the vars state.
 * @property {string} additional Any additional info to be appended at the end.
 */

/**
 * Bag of data used for formatting the `usedIgnoredVar` lint message.
 * @typedef {Object} UsedIgnoredVarMessageData
 * @property {string} varName The name of the unused var.
 * @property {string} additional Any additional info to be appended at the end.
 */

//------------------------------------------------------------------------------
// Rule Definition
//------------------------------------------------------------------------------

/** @type {import('../shared/types').Rule} */
module.exports = {
    meta: {
        type: "problem",

        docs: {
            description: "Disallow unused variables",
            recommended: true,
            url: "https://eslint.org/docs/latest/rules/no-unused-vars"
        },

        hasSuggestions: true,

        schema: [
            {
                oneOf: [
                    {
                        enum: ["all", "local"]
                    },
                    {
                        type: "object",
                        properties: {
                            vars: {
                                enum: ["all", "local"]
                            },
                            varsIgnorePattern: {
                                type: "string"
                            },
                            args: {
                                enum: ["all", "after-used", "none"]
                            },
                            ignoreRestSiblings: {
                                type: "boolean"
                            },
                            argsIgnorePattern: {
                                type: "string"
                            },
                            caughtErrors: {
                                enum: ["all", "none"]
                            },
                            caughtErrorsIgnorePattern: {
                                type: "string"
                            },
                            destructuredArrayIgnorePattern: {
                                type: "string"
                            },
                            ignoreClassWithStaticInitBlock: {
                                type: "boolean"
                            },
                            reportUsedIgnorePattern: {
                                type: "boolean"
                            }
                        },
                        additionalProperties: false
                    }
                ]
            }
        ],

        messages: {
            unusedVar: "'{{varName}}' is {{action}} but never used{{additional}}.",
            usedIgnoredVar: "'{{varName}}' is marked as ignored but is used{{additional}}.",
            removeVar: "Remove unused variable '{{varName}}'."
        }
    },

    create(context) {
        const sourceCode = context.sourceCode;

        const REST_PROPERTY_TYPE = /^(?:RestElement|(?:Experimental)?RestProperty)$/u;

        const config = {
            vars: "all",
            args: "after-used",
            ignoreRestSiblings: false,
            caughtErrors: "all",
            ignoreClassWithStaticInitBlock: false,
            reportUsedIgnorePattern: false
        };

        const firstOption = context.options[0];

        if (firstOption) {
            if (typeof firstOption === "string") {
                config.vars = firstOption;
            } else {
                config.vars = firstOption.vars || config.vars;
                config.args = firstOption.args || config.args;
                config.ignoreRestSiblings = firstOption.ignoreRestSiblings || config.ignoreRestSiblings;
                config.caughtErrors = firstOption.caughtErrors || config.caughtErrors;
                config.ignoreClassWithStaticInitBlock = firstOption.ignoreClassWithStaticInitBlock || config.ignoreClassWithStaticInitBlock;
                config.reportUsedIgnorePattern = firstOption.reportUsedIgnorePattern || config.reportUsedIgnorePattern;

                if (firstOption.varsIgnorePattern) {
                    config.varsIgnorePattern = new RegExp(firstOption.varsIgnorePattern, "u");
                }

                if (firstOption.argsIgnorePattern) {
                    config.argsIgnorePattern = new RegExp(firstOption.argsIgnorePattern, "u");
                }

                if (firstOption.caughtErrorsIgnorePattern) {
                    config.caughtErrorsIgnorePattern = new RegExp(firstOption.caughtErrorsIgnorePattern, "u");
                }

                if (firstOption.destructuredArrayIgnorePattern) {
                    config.destructuredArrayIgnorePattern = new RegExp(firstOption.destructuredArrayIgnorePattern, "u");
                }
            }
        }

        /**
         * Determines what variable type a def is.
         * @param  {Object} def the declaration to check
         * @returns {VariableType} a simple name for the types of variables that this rule supports
         */
        function defToVariableType(def) {

            /*
             * This `destructuredArrayIgnorePattern` error report works differently from the catch
             * clause and parameter error reports. _Both_ the `varsIgnorePattern` and the
             * `destructuredArrayIgnorePattern` will be checked for array destructuring. However,
             * for the purposes of the report, the currently defined behavior is to only inform the
             * user of the `destructuredArrayIgnorePattern` if it's present (regardless of the fact
             * that the `varsIgnorePattern` would also apply). If it's not present, the user will be
             * informed of the `varsIgnorePattern`, assuming that's present.
             */
            if (config.destructuredArrayIgnorePattern && def.name.parent.type === "ArrayPattern") {
                return "array-destructure";
            }

            switch (def.type) {
                case "CatchClause":
                    return "catch-clause";
                case "Parameter":
                    return "parameter";

                default:
                    return "variable";
            }
        }

        /**
         * Gets a given variable's description and configured ignore pattern
         * based on the provided variableType
         * @param {VariableType} variableType a simple name for the types of variables that this rule supports
         * @throws {Error} (Unreachable)
         * @returns {[string | undefined, string | undefined]} the given variable's description and
         * ignore pattern
         */
        function getVariableDescription(variableType) {
            let pattern;
            let variableDescription;

            switch (variableType) {
                case "array-destructure":
                    pattern = config.destructuredArrayIgnorePattern;
                    variableDescription = "elements of array destructuring";
                    break;

                case "catch-clause":
                    pattern = config.caughtErrorsIgnorePattern;
                    variableDescription = "caught errors";
                    break;

                case "parameter":
                    pattern = config.argsIgnorePattern;
                    variableDescription = "args";
                    break;

                case "variable":
                    pattern = config.varsIgnorePattern;
                    variableDescription = "vars";
                    break;

                default:
                    throw new Error(`Unexpected variable type: ${variableType}`);
            }

            if (pattern) {
                pattern = pattern.toString();
            }

            return [variableDescription, pattern];
        }

        /**
         * Generates the message data about the variable being defined and unused,
         * including the ignore pattern if configured.
         * @param {Variable} unusedVar eslint-scope variable object.
         * @returns {UnusedVarMessageData} The message data to be used with this unused variable.
         */
        function getDefinedMessageData(unusedVar) {
            const def = unusedVar.defs && unusedVar.defs[0];
            let additionalMessageData = "";

            if (def) {
                const [variableDescription, pattern] = getVariableDescription(defToVariableType(def));

                if (pattern && variableDescription) {
                    additionalMessageData = `. Allowed unused ${variableDescription} must match ${pattern}`;
                }
            }

            return {
                varName: unusedVar.name,
                action: "defined",
                additional: additionalMessageData
            };
        }

        /**
         * Generate the warning message about the variable being
         * assigned and unused, including the ignore pattern if configured.
         * @param {Variable} unusedVar eslint-scope variable object.
         * @returns {UnusedVarMessageData} The message data to be used with this unused variable.
         */
        function getAssignedMessageData(unusedVar) {
            const def = unusedVar.defs && unusedVar.defs[0];
            let additionalMessageData = "";

            if (def) {
                const [variableDescription, pattern] = getVariableDescription(defToVariableType(def));

                if (pattern && variableDescription) {
                    additionalMessageData = `. Allowed unused ${variableDescription} must match ${pattern}`;
                }
            }

            return {
                varName: unusedVar.name,
                action: "assigned a value",
                additional: additionalMessageData
            };
        }

        /**
         * Generate the warning message about a variable being used even though
         * it is marked as being ignored.
         * @param {Variable} variable eslint-scope variable object
         * @param {VariableType} variableType a simple name for the types of variables that this rule supports
         * @returns {UsedIgnoredVarMessageData} The message data to be used with
         * this used ignored variable.
         */
        function getUsedIgnoredMessageData(variable, variableType) {
            const [variableDescription, pattern] = getVariableDescription(variableType);

            let additionalMessageData = "";

            if (pattern && variableDescription) {
                additionalMessageData = `. Used ${variableDescription} must not match ${pattern}`;
            }

            return {
                varName: variable.name,
                additional: additionalMessageData
            };
        }

        //--------------------------------------------------------------------------
        // Helpers
        //--------------------------------------------------------------------------

        const STATEMENT_TYPE = /(?:Statement|Declaration)$/u;

        /**
         * Determines if a given variable is being exported from a module.
         * @param {Variable} variable eslint-scope variable object.
         * @returns {boolean} True if the variable is exported, false if not.
         * @private
         */
        function isExported(variable) {

            const definition = variable.defs[0];

            if (definition) {

                let node = definition.node;

                if (node.type === "VariableDeclarator") {
                    node = node.parent;
                } else if (definition.type === "Parameter") {
                    return false;
                }

                return node.parent.type.indexOf("Export") === 0;
            }
            return false;

        }

        /**
         * Checks whether a node is a sibling of the rest property or not.
         * @param {ASTNode} node a node to check
         * @returns {boolean} True if the node is a sibling of the rest property, otherwise false.
         */
        function hasRestSibling(node) {
            return node.type === "Property" &&
                node.parent.type === "ObjectPattern" &&
                REST_PROPERTY_TYPE.test(node.parent.properties.at(-1).type);
        }

        /**
         * Determines if a variable has a sibling rest property
         * @param {Variable} variable eslint-scope variable object.
         * @returns {boolean} True if the variable has a sibling rest property, false if not.
         * @private
         */
        function hasRestSpreadSibling(variable) {
            if (config.ignoreRestSiblings) {
                const hasRestSiblingDefinition = variable.defs.some(def => hasRestSibling(def.name.parent));
                const hasRestSiblingReference = variable.references.some(ref => hasRestSibling(ref.identifier.parent));

                return hasRestSiblingDefinition || hasRestSiblingReference;
            }

            return false;
        }

        /**
         * Determines if a reference is a read operation.
         * @param {Reference} ref An eslint-scope Reference
         * @returns {boolean} whether the given reference represents a read operation
         * @private
         */
        function isReadRef(ref) {
            return ref.isRead();
        }

        /**
         * Determine if an identifier is referencing an enclosing function name.
         * @param {Reference} ref The reference to check.
         * @param {ASTNode[]} nodes The candidate function nodes.
         * @returns {boolean} True if it's a self-reference, false if not.
         * @private
         */
        function isSelfReference(ref, nodes) {
            let scope = ref.from;

            while (scope) {
                if (nodes.includes(scope.block)) {
                    return true;
                }

                scope = scope.upper;
            }

            return false;
        }

        /**
         * Gets a list of function definitions for a specified variable.
         * @param {Variable} variable eslint-scope variable object.
         * @returns {ASTNode[]} Function nodes.
         * @private
         */
        function getFunctionDefinitions(variable) {
            const functionDefinitions = [];

            variable.defs.forEach(def => {
                const { type, node } = def;

                // FunctionDeclarations
                if (type === "FunctionName") {
                    functionDefinitions.push(node);
                }

                // FunctionExpressions
                if (type === "Variable" && node.init &&
                    (node.init.type === "FunctionExpression" || node.init.type === "ArrowFunctionExpression")) {
                    functionDefinitions.push(node.init);
                }
            });
            return functionDefinitions;
        }

        /**
         * Checks the position of given nodes.
         * @param {ASTNode} inner A node which is expected as inside.
         * @param {ASTNode} outer A node which is expected as outside.
         * @returns {boolean} `true` if the `inner` node exists in the `outer` node.
         * @private
         */
        function isInside(inner, outer) {
            return (
                inner.range[0] >= outer.range[0] &&
                inner.range[1] <= outer.range[1]
            );
        }

        /**
         * Checks whether a given node is unused expression or not.
         * @param {ASTNode} node The node itself
         * @returns {boolean} The node is an unused expression.
         * @private
         */
        function isUnusedExpression(node) {
            const parent = node.parent;

            if (parent.type === "ExpressionStatement") {
                return true;
            }

            if (parent.type === "SequenceExpression") {
                const isLastExpression = parent.expressions.at(-1) === node;

                if (!isLastExpression) {
                    return true;
                }
                return isUnusedExpression(parent);
            }

            return false;
        }

        /**
         * If a given reference is left-hand side of an assignment, this gets
         * the right-hand side node of the assignment.
         *
         * In the following cases, this returns null.
         *
         * - The reference is not the LHS of an assignment expression.
         * - The reference is inside of a loop.
         * - The reference is inside of a function scope which is different from
         *   the declaration.
         * @param {eslint-scope.Reference} ref A reference to check.
         * @param {ASTNode} prevRhsNode The previous RHS node.
         * @returns {ASTNode|null} The RHS node or null.
         * @private
         */
        function getRhsNode(ref, prevRhsNode) {
            const id = ref.identifier;
            const parent = id.parent;
            const refScope = ref.from.variableScope;
            const varScope = ref.resolved.scope.variableScope;
            const canBeUsedLater = refScope !== varScope || astUtils.isInLoop(id);

            /*
             * Inherits the previous node if this reference is in the node.
             * This is for `a = a + a`-like code.
             */
            if (prevRhsNode && isInside(id, prevRhsNode)) {
                return prevRhsNode;
            }

            if (parent.type === "AssignmentExpression" &&
                isUnusedExpression(parent) &&
                id === parent.left &&
                !canBeUsedLater
            ) {
                return parent.right;
            }
            return null;
        }

        /**
         * Checks whether a given function node is stored to somewhere or not.
         * If the function node is stored, the function can be used later.
         * @param {ASTNode} funcNode A function node to check.
         * @param {ASTNode} rhsNode The RHS node of the previous assignment.
         * @returns {boolean} `true` if under the following conditions:
         *      - the funcNode is assigned to a variable.
         *      - the funcNode is bound as an argument of a function call.
         *      - the function is bound to a property and the object satisfies above conditions.
         * @private
         */
        function isStorableFunction(funcNode, rhsNode) {
            let node = funcNode;
            let parent = funcNode.parent;

            while (parent && isInside(parent, rhsNode)) {
                switch (parent.type) {
                    case "SequenceExpression":
                        if (parent.expressions.at(-1) !== node) {
                            return false;
                        }
                        break;

                    case "CallExpression":
                    case "NewExpression":
                        return parent.callee !== node;

                    case "AssignmentExpression":
                    case "TaggedTemplateExpression":
                    case "YieldExpression":
                        return true;

                    default:
                        if (STATEMENT_TYPE.test(parent.type)) {

                            /*
                             * If it encountered statements, this is a complex pattern.
                             * Since analyzing complex patterns is hard, this returns `true` to avoid false positive.
                             */
                            return true;
                        }
                }

                node = parent;
                parent = parent.parent;
            }

            return false;
        }

        /**
         * Checks whether a given Identifier node exists inside of a function node which can be used later.
         *
         * "can be used later" means:
         * - the function is assigned to a variable.
         * - the function is bound to a property and the object can be used later.
         * - the function is bound as an argument of a function call.
         *
         * If a reference exists in a function which can be used later, the reference is read when the function is called.
         * @param {ASTNode} id An Identifier node to check.
         * @param {ASTNode} rhsNode The RHS node of the previous assignment.
         * @returns {boolean} `true` if the `id` node exists inside of a function node which can be used later.
         * @private
         */
        function isInsideOfStorableFunction(id, rhsNode) {
            const funcNode = astUtils.getUpperFunction(id);

            return (
                funcNode &&
                isInside(funcNode, rhsNode) &&
                isStorableFunction(funcNode, rhsNode)
            );
        }

        /**
         * Checks whether a given reference is a read to update itself or not.
         * @param {eslint-scope.Reference} ref A reference to check.
         * @param {ASTNode} rhsNode The RHS node of the previous assignment.
         * @returns {boolean} The reference is a read to update itself.
         * @private
         */
        function isReadForItself(ref, rhsNode) {
            const id = ref.identifier;
            const parent = id.parent;

            return ref.isRead() && (

                // self update. e.g. `a += 1`, `a++`
                (
                    (
                        parent.type === "AssignmentExpression" &&
                        parent.left === id &&
                        isUnusedExpression(parent) &&
                        !astUtils.isLogicalAssignmentOperator(parent.operator)
                    ) ||
                    (
                        parent.type === "UpdateExpression" &&
                        isUnusedExpression(parent)
                    )
                ) ||

                // in RHS of an assignment for itself. e.g. `a = a + 1`
                (
                    rhsNode &&
                    isInside(id, rhsNode) &&
                    !isInsideOfStorableFunction(id, rhsNode)
                )
            );
        }

        /**
         * Determine if an identifier is used either in for-in or for-of loops.
         * @param {Reference} ref The reference to check.
         * @returns {boolean} whether reference is used in the for-in loops
         * @private
         */
        function isForInOfRef(ref) {
            let target = ref.identifier.parent;


            // "for (var ...) { return; }"
            if (target.type === "VariableDeclarator") {
                target = target.parent.parent;
            }

            if (target.type !== "ForInStatement" && target.type !== "ForOfStatement") {
                return false;
            }

            // "for (...) { return; }"
            if (target.body.type === "BlockStatement") {
                target = target.body.body[0];

            // "for (...) return;"
            } else {
                target = target.body;
            }

            // For empty loop body
            if (!target) {
                return false;
            }

            return target.type === "ReturnStatement";
        }

        /**
         * Determines if the variable is used.
         * @param {Variable} variable The variable to check.
         * @returns {boolean} True if the variable is used
         * @private
         */
        function isUsedVariable(variable) {
            if (variable.eslintUsed) {
                return true;
            }

            const functionNodes = getFunctionDefinitions(variable);
            const isFunctionDefinition = functionNodes.length > 0;

            let rhsNode = null;

            return variable.references.some(ref => {
                if (isForInOfRef(ref)) {
                    return true;
                }

                const forItself = isReadForItself(ref, rhsNode);

                rhsNode = getRhsNode(ref, rhsNode);

                return (
                    isReadRef(ref) &&
                    !forItself &&
                    !(isFunctionDefinition && isSelfReference(ref, functionNodes))
                );
            });
        }

        /**
         * Checks whether the given variable is after the last used parameter.
         * @param {eslint-scope.Variable} variable The variable to check.
         * @returns {boolean} `true` if the variable is defined after the last
         * used parameter.
         */
        function isAfterLastUsedArg(variable) {
            const def = variable.defs[0];
            const params = sourceCode.getDeclaredVariables(def.node);
            const posteriorParams = params.slice(params.indexOf(variable) + 1);

            // If any used parameters occur after this parameter, do not report.
            return !posteriorParams.some(v => v.references.length > 0 || v.eslintUsed);
        }

        /**
         * Gets an array of variables without read references.
         * @param {Scope} scope an eslint-scope Scope object.
         * @param {Variable[]} unusedVars an array that saving result.
         * @returns {Variable[]} unused variables of the scope and descendant scopes.
         * @private
         */
        function collectUnusedVariables(scope, unusedVars) {
            const variables = scope.variables;
            const childScopes = scope.childScopes;
            let i, l;

            if (scope.type !== "global" || config.vars === "all") {
                for (i = 0, l = variables.length; i < l; ++i) {
                    const variable = variables[i];

                    // skip a variable of class itself name in the class scope
                    if (scope.type === "class" && scope.block.id === variable.identifiers[0]) {
                        continue;
                    }

                    // skip function expression names
                    if (scope.functionExpressionScope) {
                        continue;
                    }

                    // skip variables marked with markVariableAsUsed()
                    if (!config.reportUsedIgnorePattern && variable.eslintUsed) {
                        continue;
                    }

                    // skip implicit "arguments" variable
                    if (scope.type === "function" && variable.name === "arguments" && variable.identifiers.length === 0) {
                        continue;
                    }

                    // explicit global variables don't have definitions.
                    const def = variable.defs[0];

                    if (def) {
                        const type = def.type;
                        const refUsedInArrayPatterns = variable.references.some(ref => ref.identifier.parent.type === "ArrayPattern");

                        // skip elements of array destructuring patterns
                        if (
                            (
                                def.name.parent.type === "ArrayPattern" ||
                                refUsedInArrayPatterns
                            ) &&
                            config.destructuredArrayIgnorePattern &&
                            config.destructuredArrayIgnorePattern.test(def.name.name)
                        ) {
                            if (config.reportUsedIgnorePattern && isUsedVariable(variable)) {
                                context.report({
                                    node: def.name,
                                    messageId: "usedIgnoredVar",
                                    data: getUsedIgnoredMessageData(variable, "array-destructure")
                                });
                            }

                            continue;
                        }

                        if (type === "ClassName") {
                            const hasStaticBlock = def.node.body.body.some(node => node.type === "StaticBlock");

                            if (config.ignoreClassWithStaticInitBlock && hasStaticBlock) {
                                continue;
                            }
                        }

                        // skip catch variables
                        if (type === "CatchClause") {
                            if (config.caughtErrors === "none") {
                                continue;
                            }

                            // skip ignored parameters
                            if (config.caughtErrorsIgnorePattern && config.caughtErrorsIgnorePattern.test(def.name.name)) {
                                if (config.reportUsedIgnorePattern && isUsedVariable(variable)) {
                                    context.report({
                                        node: def.name,
                                        messageId: "usedIgnoredVar",
                                        data: getUsedIgnoredMessageData(variable, "catch-clause")
                                    });
                                }

                                continue;
                            }
                        } else if (type === "Parameter") {

                            // skip any setter argument
                            if ((def.node.parent.type === "Property" || def.node.parent.type === "MethodDefinition") && def.node.parent.kind === "set") {
                                continue;
                            }

                            // if "args" option is "none", skip any parameter
                            if (config.args === "none") {
                                continue;
                            }

                            // skip ignored parameters
                            if (config.argsIgnorePattern && config.argsIgnorePattern.test(def.name.name)) {
                                if (config.reportUsedIgnorePattern && isUsedVariable(variable)) {
                                    context.report({
                                        node: def.name,
                                        messageId: "usedIgnoredVar",
                                        data: getUsedIgnoredMessageData(variable, "parameter")
                                    });
                                }

                                continue;
                            }

                            // if "args" option is "after-used", skip used variables
                            if (config.args === "after-used" && astUtils.isFunction(def.name.parent) && !isAfterLastUsedArg(variable)) {
                                continue;
                            }
                        } else {

                            // skip ignored variables
                            if (config.varsIgnorePattern && config.varsIgnorePattern.test(def.name.name)) {
                                if (config.reportUsedIgnorePattern && isUsedVariable(variable)) {
                                    context.report({
                                        node: def.name,
                                        messageId: "usedIgnoredVar",
                                        data: getUsedIgnoredMessageData(variable, "variable")
                                    });
                                }

                                continue;
                            }
                        }
                    }

                    if (!isUsedVariable(variable) && !isExported(variable) && !hasRestSpreadSibling(variable)) {
                        unusedVars.push(variable);
                    }
                }
            }

            for (i = 0, l = childScopes.length; i < l; ++i) {
                collectUnusedVariables(childScopes[i], unusedVars);
            }

            return unusedVars;
        }

        /**
         * fixes unused variables
         * @param {Object} fixer fixer object
         * @param {Object} unusedVar unused variable to fix
         * @returns {Object} fixer object
         */
        function handleFixes(fixer, unusedVar) {
            const id = unusedVar.identifiers[0];
            const parent = id.parent;
            const parentType = parent.type;
            const tokenBefore = sourceCode.getTokenBefore(id);
            const tokenAfter = sourceCode.getTokenAfter(id);
            const isFunction = astUtils.isFunction;
            const isLoop = astUtils.isLoop;
            const allWriteReferences = unusedVar.references.filter(ref => ref.isWrite());

            /**
             * get range from token before of a given node
             * @param {ASTNode} node node of identifier
             * @param {number} skips number of token to skip
             * @returns {number} start range of token before the identifier
             */
            function getPreviousTokenStart(node, skips) {
                return sourceCode.getTokenBefore(node, skips).range[0];
            }

            /**
             * get range to token after of a given node
             * @param {ASTNode} node node of identifier
             * @param {number} skips number of token to skip
             * @returns {number} end range of token after the identifier
             */
            function getNextTokenEnd(node, skips) {
                return sourceCode.getTokenAfter(node, skips).range[1];
            }

            /**
             * get the value of token before of a given node
             * @param {ASTNode} node node of identifier
             * @returns {string} value of token before the identifier
             */
            function getTokenBeforeValue(node) {
                return sourceCode.getTokenBefore(node).value;
            }

            /**
             * get the value of token after of a given node
             * @param {ASTNode} node node of identifier
             * @returns {string} value of token after the identifier
             */
            function getTokenAfterValue(node) {
                return sourceCode.getTokenAfter(node).value;
            }

            /**
             * Check if an array has a single element with null as other element.
             * @param {ASTNode} node ArrayPattern node
             * @returns {boolean} true if array has single element with other null elements
             */
            function hasSingleElement(node) {
                return node.elements.filter(e => e !== null).length === 1;
            }

            /**
             * check whether import specifier has an import of particular type
             * @param {ASTNode} node ImportDeclaration node
             * @param {string} type type of import to check
             * @returns {boolean} true if import specifier has import of specified type
             */
            function hasImportOfCertainType(node, type) {
                return node.specifiers.some(e => e.type === type);
            }

            /**
             * Check whether declaration is safe to remove or not
             * @param {ASTNode} nextToken next token of unused variable
             * @param {ASTNode} prevToken previous token of unused variable
             * @returns {boolean} true if declaration is not safe to remove
             */
            function isDeclarationNotSafeToRemove(nextToken, prevToken) {
                return (
                    (nextToken.type === "String") ||
                    (
                        prevToken &&
                        !astUtils.isSemicolonToken(prevToken) &&
                        !astUtils.isOpeningBraceToken(prevToken)
                    )
                );
            }

            /**
             * give fixes for unused variables in function parameters
             * @param {ASTNode} node node to check
             * @returns {Object} fixer object
             */
            function fixFunctionParameters(node) {
                const parentNode = node.parent;

                if (isFunction(parentNode)) {

                    // remove unused function parameter if there is only a single parameter
                    if (parentNode.params.length === 1) {
                        return fixer.removeRange(node.range);
                    }

                    // remove first unused function parameter when there are multiple parameters
                    if (getTokenBeforeValue(node) === "(" && getTokenAfterValue(node) === ",") {
                        return fixer.removeRange([node.range[0], getNextTokenEnd(node)]);
                    }

                    // remove unused function parameters except first one when there are multiple parameters
                    return fixer.removeRange([getPreviousTokenStart(node), node.range[1]]);
                }

                return null;
            }

            /**
             * fix unused variable declarations and function parameters
             * @param {ASTNode} node parent node to identifier
             * @returns {Object} fixer object
             */
            function fixVariables(node) {
                const parentNode = node.parent;

                // remove unused declared variables such as var a = b; or var a = b, c;
                if (parentNode.type === "VariableDeclarator") {

                    // skip variable in for (const [ foo ] of bar);
                    if (isLoop(parentNode.parent.parent)) {
                        return null;
                    }

                    /*
                     * remove unused declared variable with single declaration such as 'var a = b;'
                     * remove complete declaration when there is an unused variable in 'const { a } = foo;', same for arrays.
                     */
                    if (parentNode.parent.declarations.length === 1) {

                        // if next token is a string it could become a directive if node is removed -> no suggestion.
                        const nextToken = sourceCode.getTokenAfter(parentNode.parent);

                        // if previous token exists and is not ";" or "{" not sure about ASI rules -> no suggestion.
                        const prevToken = sourceCode.getTokenBefore(parentNode.parent);

                        if (nextToken && isDeclarationNotSafeToRemove(nextToken, prevToken)) {
                            return null;
                        }

                        return fixer.removeRange(parentNode.parent.range);
                    }

                    /*
                     * remove unused declared variable with multiple declaration except first one such as 'var a = b, c = d;'
                     * fix 'let bar = "hello", { a } = foo;' to 'let bar = "hello";' if 'a' is unused, same for arrays.
                     */
                    if (getTokenBeforeValue(parentNode) === ",") {
                        return fixer.removeRange([getPreviousTokenStart(parentNode), parentNode.range[1]]);
                    }

                    /*
                     * remove first unused declared variable when there are multiple declarations
                     * fix 'let { a } = foo, bar = "hello";' to 'let  bar = "hello";' if 'a' is unused, same for arrays.
                     */
                    return fixer.removeRange([parentNode.range[0], getNextTokenEnd(parentNode)]);
                }

                // fixes [{a: {k}}], [{a: [k]}]
                if (getTokenBeforeValue(node) === ":") {
                    if (parentNode.parent.type === "ObjectPattern") {
                        // eslint-disable-next-line no-use-before-define -- due to interdependency of functions
                        return fixObjectWithValueSeparator(node);
                    }
                }

                // fix unused function parameters
                return fixFunctionParameters(node);
            }

            /**
             * fix nested object like { a: { b } }
             * @param {ASTNode} node parent node to check
             * @returns {Object} fixer object
             */
            function fixNestedObjectVariable(node) {
                const parentNode = node.parent;

                // fix for { a: { b: { c: { d } } } }
                if (
                    parentNode.parent.parent.parent.type === "ObjectPattern" &&
                        parentNode.parent.properties.length === 1
                ) {
                    return fixNestedObjectVariable(parentNode.parent);
                }

                // fix for { a: { b } }
                if (parentNode.parent.type === "ObjectPattern") {

                    // fix for unused variables in dectructured object with single property in variable decalartion and function parameter
                    if (parentNode.parent.properties.length === 1) {
                        return fixVariables(parentNode.parent);
                    }

                    // fix for first unused property when there are multiple properties such as '{ a: { b }, c }'
                    if (getTokenBeforeValue(parentNode) === "{") {
                        return fixer.removeRange(
                            [parentNode.range[0], getNextTokenEnd(parentNode)]
                        );
                    }

                    // fix for unused property except first one when there are multiple properties such as '{ k, a: { b } }'
                    return fixer.removeRange([getPreviousTokenStart(parentNode), parentNode.range[1]]);
                }

                return null;
            }

            /**
             * fix unused variables in array and nested array
             * @param {ASTNode} node parent node to check
             * @returns {Object} fixer object
             */
            function fixNestedArrayVariable(node) {
                const parentNode = node.parent;

                // fix for nested arrays [[ a ]]
                if (parentNode.parent.type === "ArrayPattern" && hasSingleElement(parentNode)) {
                    return fixNestedArrayVariable(parentNode);
                }

                if (hasSingleElement(parentNode)) {

                    // fixes { a: [{ b }] } or { a: [[ b ]] }
                    if (getTokenBeforeValue(parentNode) === ":") {
                        return fixVariables(parentNode);
                    }

                    // fixes [a, ...[[ b ]]] or [a, ...[{ b }]]
                    if (parentNode.parent.type === "RestElement") {
                        // eslint-disable-next-line no-use-before-define -- due to interdependency of functions
                        return fixRestInPattern(parentNode.parent);
                    }

                    // fix unused variables in destructured array in variable declaration or function parameter
                    return fixVariables(parentNode);
                }

                // remove last unused array element
                if (
                    getTokenBeforeValue(node) === "," &&
                        getTokenAfterValue(node) === "]"
                ) {
                    return fixer.removeRange([getPreviousTokenStart(node), node.range[1]]);
                }

                // remove unused array element
                return fixer.removeRange(node.range);
            }

            /**
             * fix cases like {a: {k}} or {a: [k]}
             * @param {ASTNode} node parent node to check
             * @returns {Object} fixer object
             */
            function fixObjectWithValueSeparator(node) {
                const parentNode = node.parent.parent;

                // fix cases like [{a : { b }}] or [{a : [ b ]}]
                if (
                    parentNode.parent.type === "ArrayPattern" &&
                        parentNode.properties.length === 1
                ) {
                    return fixNestedArrayVariable(parentNode);
                }

                // fix cases like {a: {k}} or {a: [k]}
                return fixNestedObjectVariable(node);
            }

            /**
             * fix ...[[a]] or ...[{a}] like patterns
             * @param {ASTNode} node parent node to check
             * @returns {Object} fixer object
             */
            function fixRestInPattern(node) {
                const parentNode = node.parent;

                // fix ...[[a]] or ...[{a}] in function parameters
                if (isFunction(parentNode)) {
                    if (parentNode.params.length === 1) {
                        return fixer.removeRange(node.range);
                    }

                    return fixer.removeRange([getPreviousTokenStart(node), node.range[1]]);
                }

                // fix rest in nested array pattern like [[a, ...[b]]]
                if (parentNode.type === "ArrayPattern") {

                    // fix [[...[b]]]
                    if (hasSingleElement(parentNode)) {
                        if (parentNode.parent.type === "ArrayPattern") {
                            return fixNestedArrayVariable(parentNode);
                        }

                        // fix 'const [...[b]] = foo; and function foo([...[b]]) {}
                        return fixVariables(parentNode);
                    }

                    // fix [[a, ...[b]]]
                    return fixer.removeRange([getPreviousTokenStart(node), node.range[1]]);
                }

                return null;
            }

            // skip fix when variable has references that would be left behind
            if (allWriteReferences.some(ref => ref.identifier.range[0] !== id.range[0])) {
                return null;
            }

            // remove declared variables such as var a; or var a, b;
            if (parentType === "VariableDeclarator") {
                if (parent.parent.declarations.length === 1) {

                    // prevent fix of variable in forOf and forIn loops.
                    if (isLoop(parent.parent.parent) && parent.parent.parent.body !== parent.parent) {
                        return null;
                    }

                    // removes only variable not semicolon in 'if (foo()) var bar;' or in 'loops' or in 'with' statement.
                    if (
                        parent.parent.parent.type === "IfStatement" ||
                        isLoop(parent.parent.parent) ||
                        (parent.parent.parent.type === "WithStatement" && parent.parent.parent.body === parent.parent)
                    ) {
                        return fixer.replaceText(parent.parent, ";");
                    }

                    // if next token is a string it could become a directive if node is removed -> no suggestion.
                    const nextToken = sourceCode.getTokenAfter(parent.parent);

                    // if previous token exists and is not ";" or "{" not sure about ASI rules -> no suggestion.
                    const prevToken = sourceCode.getTokenBefore(parent.parent);

                    if (nextToken && isDeclarationNotSafeToRemove(nextToken, prevToken)) {
                        return null;
                    }

                    // remove unused declared variable with single declaration like 'var a = b;'
                    return fixer.removeRange(parent.parent.range);
                }

                // remove unused declared variable with multiple declaration except first one like 'var a = b, c = d;'
                if (tokenBefore.value === ",") {
                    return fixer.removeRange([tokenBefore.range[0], parent.range[1]]);
                }

                // remove first unused declared variable when there are multiple declarations
                return fixer.removeRange([parent.range[0], getNextTokenEnd(parent)]);
            }

            // remove variables in object patterns
            if (parent.parent.type === "ObjectPattern") {
                if (parent.parent.properties.length === 1) {

                    // fix [a, ...{b}]
                    if (parent.parent.parent.type === "RestElement") {
                        return fixRestInPattern(parent.parent.parent);
                    }

                    // fix [{ a }]
                    if (parent.parent.parent.type === "ArrayPattern") {
                        return fixNestedArrayVariable(parent.parent);
                    }

                    /*
                     * var {a} = foo;
                     * function a({a}) {}
                     * fix const { a: { b } } = foo;
                     */
                    return fixVariables(parent.parent);
                }

                // fix const { a:b } = foo;
                if (tokenBefore.value === ":") {

                    // remove first unused variable in const { a:b } = foo;
                    if (getTokenBeforeValue(parent) === "{" && getTokenAfterValue(parent) === ",") {
                        return fixer.removeRange([parent.range[0], getNextTokenEnd(parent)]);
                    }

                    // remove unused variables in const { a: b, c: d } = foo; except first one
                    return fixer.removeRange([getPreviousTokenStart(parent), id.range[1]]);
                }
            }

            // remove unused variables inside an array
            if (parentType === "ArrayPattern") {
                if (hasSingleElement(parent)) {

                    // fix [a, ...[b]]
                    if (parent.parent.type === "RestElement") {
                        return fixRestInPattern(parent.parent);
                    }

                    // fix [ [a] ]
                    if (parent.parent.type === "ArrayPattern") {
                        return fixNestedArrayVariable(parent);
                    }

                    /*
                     * fix var [a] = foo;
                     * fix function foo([a]) {}
                     * fix const { a: [b] } = foo;
                     */
                    return fixVariables(parent);
                }

                // if "a" is unused in [a, b ,c] fixes to [, b, c]
                if (tokenBefore.value === "," && tokenAfter.value === ",") {
                    return fixer.removeRange(id.range);
                }
            }

            // remove unused rest elements
            if (parentType === "RestElement") {

                // fix [a, ...rest]
                if (parent.parent.type === "ArrayPattern") {
                    if (hasSingleElement(parent.parent)) {

                        // fix [[...rest]] when there is only rest element
                        if (
                            parent.parent.parent.type === "ArrayPattern"
                        ) {
                            return fixNestedArrayVariable(parent.parent);
                        }

                        // fix 'const [...rest] = foo;' and 'function foo([...rest]) {}'
                        return fixVariables(parent.parent);
                    }

                    // fix [a, ...rest]
                    return fixer.removeRange([getPreviousTokenStart(id, 1), id.range[1]]);
                }

                // fix { a, ...rest}
                if (parent.parent.type === "ObjectPattern") {

                    // fix 'const {...rest} = foo;' and 'function foo({...rest}) {}'
                    if (parent.parent.properties.length === 1) {
                        return fixVariables(parent.parent);
                    }

                    // fix { a, ...rest} when there are multiple properties
                    return fixer.removeRange([getPreviousTokenStart(id, 1), id.range[1]]);
                }

                // fix function foo(...rest) {}
                if (isFunction(parent.parent)) {

                    // remove unused rest in function parameter if there is only single parameter
                    if (parent.parent.params.length === 1) {
                        return fixer.removeRange(parent.range);
                    }

                    // remove unused rest in function parameter if there multiple parameter
                    return fixer.removeRange([getPreviousTokenStart(parent), parent.range[1]]);
                }
            }

            if (parentType === "AssignmentPattern") {

                // fix [a = aDefault]
                if (parent.parent.type === "ArrayPattern") {
                    return fixNestedArrayVariable(parent);
                }

                // fix {a = aDefault}
                if (parent.parent.parent.type === "ObjectPattern") {
                    if (parent.parent.parent.properties.length === 1) {

                        // fixes [{a = aDefault}]
                        if (parent.parent.parent.parent.type === "ArrayPattern") {
                            return fixNestedArrayVariable(parent.parent.parent);
                        }

                        // fix 'const {a = aDefault} = foo;' and 'function foo({a = aDefault}) {}'
                        return fixVariables(parent.parent.parent);
                    }

                    // fix unused 'a' in {a = aDefault} if it is the first property
                    if (
                        getTokenBeforeValue(parent.parent) === "{" &&
                            getTokenAfterValue(parent.parent) === ","
                    ) {
                        return fixer.removeRange([parent.parent.range[0], getNextTokenEnd(parent.parent)]);
                    }

                    // fix unused 'b' in {a, b = aDefault} if it is not the first property
                    return fixer.removeRange([getPreviousTokenStart(parent.parent), parent.parent.range[1]]);
                }

                // fix unused assignment patterns in function parameters
                if (isFunction(parent.parent)) {
                    return fixFunctionParameters(parent);
                }
            }

            // remove unused functions
            if (parentType === "FunctionDeclaration" && parent.id === id) {
                return fixer.removeRange(parent.range);
            }

            // remove unused default import
            if (parentType === "ImportDefaultSpecifier") {

                // remove unused default import when there are not other imports
                if (
                    !hasImportOfCertainType(parent.parent, "ImportSpecifier") &&
                    !hasImportOfCertainType(parent.parent, "ImportNamespaceSpecifier")
                ) {
                    return fixer.removeRange([parent.range[0], parent.parent.source.range[0]]);
                }

                // remove unused default import when there are other imports also
                return fixer.removeRange([id.range[0], tokenAfter.range[1]]);
            }

            if (parentType === "ImportSpecifier") {

                // remove unused imports when there is a single import
                if (parent.parent.specifiers.filter(e => e.type === "ImportSpecifier").length === 1) {

                    // remove unused import when there is no default import
                    if (!hasImportOfCertainType(parent.parent, "ImportDefaultSpecifier")) {
                        return fixer.removeRange(parent.parent.range);
                    }

                    // fixes "import foo from 'module';" to "import 'module';"
                    return fixer.removeRange([getPreviousTokenStart(parent, 1), tokenAfter.range[1]]);
                }

                if (getTokenBeforeValue(parent) === "{") {
                    return fixer.removeRange([parent.range[0], getNextTokenEnd(parent)]);
                }

                return fixer.removeRange([getPreviousTokenStart(parent), parent.range[1]]);
            }

            if (parentType === "ImportNamespaceSpecifier") {
                if (hasImportOfCertainType(parent.parent, "ImportDefaultSpecifier")) {
                    return fixer.removeRange([getPreviousTokenStart(parent), parent.range[1]]);
                }

                // fixes "import * as foo from 'module';" to "import 'module';"
                return fixer.removeRange([parent.range[0], parent.parent.source.range[0]]);
            }

            // skip error in catch(error) variable
            if (parentType === "CatchClause") {
                return null;
            }

            // remove unused declared classes
            if (parentType === "ClassDeclaration") {
                return fixer.removeRange(parent.range);
            }

            // remove unused varible that is in a sequence [a,b] fixes to [a]
            if (tokenBefore?.value === ",") {
                return fixer.removeRange([tokenBefore.range[0], id.range[1]]);
            }

            // remove unused varible that is in a sequence inside function arguments and object pattern
            if (tokenAfter.value === ",") {

                // fix function foo(a, b) {}
                if (tokenBefore.value === "(") {
                    return fixer.removeRange([id.range[0], tokenAfter.range[1]]);
                }

                // fix const {a, b} = foo;
                if (tokenBefore.value === "{") {
                    return fixer.removeRange([id.range[0], tokenAfter.range[1]]);
                }
            }

            if (parentType === "ArrowFunctionExpression" && parent.params.length === 1 && tokenAfter?.value !== ")") {
                return fixer.replaceText(id, "()");
            }

            return fixer.removeRange(id.range);
        }

        //--------------------------------------------------------------------------
        // Public
        //--------------------------------------------------------------------------

        return {
            "Program:exit"(programNode) {
                const unusedVars = collectUnusedVariables(sourceCode.getScope(programNode), []);

                for (let i = 0, l = unusedVars.length; i < l; ++i) {
                    const unusedVar = unusedVars[i];

                    // Report the first declaration.
                    if (unusedVar.defs.length > 0) {

                        // report last write reference, https://github.com/eslint/eslint/issues/14324
                        const writeReferences = unusedVar.references.filter(ref => ref.isWrite() && ref.from.variableScope === unusedVar.scope.variableScope);

                        let referenceToReport;

                        if (writeReferences.length > 0) {
                            referenceToReport = writeReferences.at(-1);
                        }

                        context.report({
                            node: referenceToReport ? referenceToReport.identifier : unusedVar.identifiers[0],
                            messageId: "unusedVar",
                            data: unusedVar.references.some(ref => ref.isWrite())
                                ? getAssignedMessageData(unusedVar)
                                : getDefinedMessageData(unusedVar),
                            suggest: [
                                {
                                    messageId: "removeVar",
                                    data: {
                                        varName: unusedVar.name
                                    },
                                    fix(fixer) {
                                        return handleFixes(fixer, unusedVar);
                                    }
                                }
                            ]
                        });

                    // If there are no regular declaration, report the first `/*globals*/` comment directive.
                    } else if (unusedVar.eslintExplicitGlobalComments) {
                        const directiveComment = unusedVar.eslintExplicitGlobalComments[0];

                        context.report({
                            node: programNode,
                            loc: astUtils.getNameLocationInGlobalDirectiveComment(sourceCode, directiveComment, unusedVar.name),
                            messageId: "unusedVar",
                            data: getDefinedMessageData(unusedVar)
                        });
                    }
                }
            }
        };
    }
};