eslint 8.57.0 → 9.2.0

package/lib/rules/no-unused-vars.js

@@ -15,6 +15,11 @@ 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
@@ -23,6 +28,13 @@ const astUtils = require("./utils/ast-utils");
  * @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
 //------------------------------------------------------------------------------
@@ -70,6 +82,12 @@ module.exports = {
                             },
                             destructuredArrayIgnorePattern: {
                                 type: "string"
+                            },
+                            ignoreClassWithStaticInitBlock: {
+                                type: "boolean"
+                            },
+                            reportUsedIgnorePattern: {
+                                type: "boolean"
                             }
                         },
                         additionalProperties: false
@@ -79,7 +97,8 @@ module.exports = {
         ],
 
         messages: {
-            unusedVar: "'{{varName}}' is {{action}} but never used{{additional}}."
+            unusedVar: "'{{varName}}' is {{action}} but never used{{additional}}.",
+            usedIgnoredVar: "'{{varName}}' is marked as ignored but is used{{additional}}."
         }
     },
 
@@ -92,7 +111,9 @@ module.exports = {
             vars: "all",
             args: "after-used",
             ignoreRestSiblings: false,
-            caughtErrors: "none"
+            caughtErrors: "all",
+            ignoreClassWithStaticInitBlock: false,
+            reportUsedIgnorePattern: false
         };
 
         const firstOption = context.options[0];
@@ -105,6 +126,8 @@ module.exports = {
                 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");
@@ -124,6 +147,50 @@ module.exports = {
             }
         }
 
+        /**
+         * 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 = "args";
+                    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.
@@ -131,27 +198,42 @@ module.exports = {
          * @returns {UnusedVarMessageData} The message data to be used with this unused variable.
          */
         function getDefinedMessageData(unusedVar) {
-            const defType = unusedVar.defs && unusedVar.defs[0] && unusedVar.defs[0].type;
-            let type;
-            let pattern;
+            const def = unusedVar.defs && unusedVar.defs[0];
+            let additionalMessageData = "";
 
-            if (defType === "CatchClause" && config.caughtErrorsIgnorePattern) {
-                type = "args";
-                pattern = config.caughtErrorsIgnorePattern.toString();
-            } else if (defType === "Parameter" && config.argsIgnorePattern) {
-                type = "args";
-                pattern = config.argsIgnorePattern.toString();
-            } else if (defType !== "Parameter" && config.varsIgnorePattern) {
-                type = "vars";
-                pattern = config.varsIgnorePattern.toString();
-            }
+            if (def) {
+                let pattern;
+                let variableDescription;
 
-            const additional = type ? `. Allowed unused ${type} must match ${pattern}` : "";
+                switch (def.type) {
+                    case "CatchClause":
+                        if (config.caughtErrorsIgnorePattern) {
+                            [variableDescription, pattern] = getVariableDescription("catch-clause");
+                        }
+                        break;
+
+                    case "Parameter":
+                        if (config.argsIgnorePattern) {
+                            [variableDescription, pattern] = getVariableDescription("parameter");
+                        }
+                        break;
+
+                    default:
+                        if (config.varsIgnorePattern) {
+                            [variableDescription, pattern] = getVariableDescription("variable");
+                        }
+                        break;
+                }
+
+                if (pattern && variableDescription) {
+                    additionalMessageData = `. Allowed unused ${variableDescription} must match ${pattern}`;
+                }
+            }
 
             return {
                 varName: unusedVar.name,
                 action: "defined",
-                additional
+                additional: additionalMessageData
             };
         }
 
@@ -162,19 +244,51 @@ module.exports = {
          * @returns {UnusedVarMessageData} The message data to be used with this unused variable.
          */
         function getAssignedMessageData(unusedVar) {
-            const def = unusedVar.defs[0];
-            let additional = "";
+            const def = unusedVar.defs && unusedVar.defs[0];
+            let additionalMessageData = "";
+
+            if (def) {
+                let pattern;
+                let variableDescription;
 
-            if (config.destructuredArrayIgnorePattern && def && def.name.parent.type === "ArrayPattern") {
-                additional = `. Allowed unused elements of array destructuring patterns must match ${config.destructuredArrayIgnorePattern.toString()}`;
-            } else if (config.varsIgnorePattern) {
-                additional = `. Allowed unused vars must match ${config.varsIgnorePattern.toString()}`;
+                if (def.name.parent.type === "ArrayPattern" && config.destructuredArrayIgnorePattern) {
+                    [variableDescription, pattern] = getVariableDescription("array-destructure");
+                } else if (config.varsIgnorePattern) {
+                    [variableDescription, pattern] = getVariableDescription("variable");
+                }
+
+                if (pattern && variableDescription) {
+                    additionalMessageData = `. Allowed unused ${variableDescription} must match ${pattern}`;
+                }
             }
 
             return {
                 varName: unusedVar.name,
                 action: "assigned a value",
-                additional
+                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
             };
         }
 
@@ -218,7 +332,7 @@ module.exports = {
         function hasRestSibling(node) {
             return node.type === "Property" &&
                 node.parent.type === "ObjectPattern" &&
-                REST_PROPERTY_TYPE.test(node.parent.properties[node.parent.properties.length - 1].type);
+                REST_PROPERTY_TYPE.test(node.parent.properties.at(-1).type);
         }
 
         /**
@@ -323,7 +437,7 @@ module.exports = {
             }
 
             if (parent.type === "SequenceExpression") {
-                const isLastExpression = parent.expressions[parent.expressions.length - 1] === node;
+                const isLastExpression = parent.expressions.at(-1) === node;
 
                 if (!isLastExpression) {
                     return true;
@@ -392,7 +506,7 @@ module.exports = {
             while (parent && isInside(parent, rhsNode)) {
                 switch (parent.type) {
                     case "SequenceExpression":
-                        if (parent.expressions[parent.expressions.length - 1] !== node) {
+                        if (parent.expressions.at(-1) !== node) {
                             return false;
                         }
                         break;
@@ -527,8 +641,13 @@ module.exports = {
          * @private
          */
         function isUsedVariable(variable) {
-            const functionNodes = getFunctionDefinitions(variable),
-                isFunctionDefinition = functionNodes.length > 0;
+            if (variable.eslintUsed) {
+                return true;
+            }
+
+            const functionNodes = getFunctionDefinitions(variable);
+            const isFunctionDefinition = functionNodes.length > 0;
+
             let rhsNode = null;
 
             return variable.references.some(ref => {
@@ -584,8 +703,13 @@ module.exports = {
                         continue;
                     }
 
-                    // skip function expression names and variables marked with markVariableAsUsed()
-                    if (scope.functionExpressionScope || variable.eslintUsed) {
+                    // skip function expression names
+                    if (scope.functionExpressionScope) {
+                        continue;
+                    }
+
+                    // skip variables marked with markVariableAsUsed()
+                    if (!config.reportUsedIgnorePattern && variable.eslintUsed) {
                         continue;
                     }
 
@@ -610,9 +734,25 @@ module.exports = {
                             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") {
@@ -621,11 +761,17 @@ module.exports = {
 
                             // 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;
                             }
-                        }
-
-                        if (type === "Parameter") {
+                        } else if (type === "Parameter") {
 
                             // skip any setter argument
                             if ((def.node.parent.type === "Property" || def.node.parent.type === "MethodDefinition") && def.node.parent.kind === "set") {
@@ -639,6 +785,14 @@ module.exports = {
 
                             // 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;
                             }
 
@@ -650,6 +804,14 @@ module.exports = {
 
                             // 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;
                             }
                         }
@@ -688,7 +850,7 @@ module.exports = {
                         let referenceToReport;
 
                         if (writeReferences.length > 0) {
-                            referenceToReport = writeReferences[writeReferences.length - 1];
+                            referenceToReport = writeReferences.at(-1);
                         }
 
                         context.report({
@@ -713,6 +875,5 @@ module.exports = {
                 }
             }
         };
-
     }
 };