2 * @fileoverview Rule to flag declared but unused variables
8 //------------------------------------------------------------------------------
10 //------------------------------------------------------------------------------
12 const astUtils = require("./utils/ast-utils");
14 //------------------------------------------------------------------------------
16 //------------------------------------------------------------------------------
19 * Bag of data used for formatting the `unusedVar` lint message.
20 * @typedef {Object} UnusedVarMessageData
21 * @property {string} varName The name of the unused var.
22 * @property {'defined'|'assigned a value'} action Description of the vars state.
23 * @property {string} additional Any additional info to be appended at the end.
26 //------------------------------------------------------------------------------
28 //------------------------------------------------------------------------------
35 description: "disallow unused variables",
36 category: "Variables",
38 url: "https://eslint.org/docs/rules/no-unused-vars"
45 enum: ["all", "local"]
51 enum: ["all", "local"]
57 enum: ["all", "after-used", "none"]
68 caughtErrorsIgnorePattern: {
72 additionalProperties: false
79 unusedVar: "'{{varName}}' is {{action}} but never used{{additional}}."
84 const sourceCode = context.getSourceCode();
86 const REST_PROPERTY_TYPE = /^(?:RestElement|(?:Experimental)?RestProperty)$/u;
91 ignoreRestSiblings: false,
95 const firstOption = context.options[0];
98 if (typeof firstOption === "string") {
99 config.vars = firstOption;
101 config.vars = firstOption.vars || config.vars;
102 config.args = firstOption.args || config.args;
103 config.ignoreRestSiblings = firstOption.ignoreRestSiblings || config.ignoreRestSiblings;
104 config.caughtErrors = firstOption.caughtErrors || config.caughtErrors;
106 if (firstOption.varsIgnorePattern) {
107 config.varsIgnorePattern = new RegExp(firstOption.varsIgnorePattern, "u");
110 if (firstOption.argsIgnorePattern) {
111 config.argsIgnorePattern = new RegExp(firstOption.argsIgnorePattern, "u");
114 if (firstOption.caughtErrorsIgnorePattern) {
115 config.caughtErrorsIgnorePattern = new RegExp(firstOption.caughtErrorsIgnorePattern, "u");
121 * Generates the message data about the variable being defined and unused,
122 * including the ignore pattern if configured.
123 * @param {Variable} unusedVar eslint-scope variable object.
124 * @returns {UnusedVarMessageData} The message data to be used with this unused variable.
126 function getDefinedMessageData(unusedVar) {
127 const defType = unusedVar.defs && unusedVar.defs[0] && unusedVar.defs[0].type;
131 if (defType === "CatchClause" && config.caughtErrorsIgnorePattern) {
133 pattern = config.caughtErrorsIgnorePattern.toString();
134 } else if (defType === "Parameter" && config.argsIgnorePattern) {
136 pattern = config.argsIgnorePattern.toString();
137 } else if (defType !== "Parameter" && config.varsIgnorePattern) {
139 pattern = config.varsIgnorePattern.toString();
142 const additional = type ? `. Allowed unused ${type} must match ${pattern}` : "";
145 varName: unusedVar.name,
152 * Generate the warning message about the variable being
153 * assigned and unused, including the ignore pattern if configured.
154 * @param {Variable} unusedVar eslint-scope variable object.
155 * @returns {UnusedVarMessageData} The message data to be used with this unused variable.
157 function getAssignedMessageData(unusedVar) {
158 const additional = config.varsIgnorePattern ? `. Allowed unused vars must match ${config.varsIgnorePattern.toString()}` : "";
161 varName: unusedVar.name,
162 action: "assigned a value",
167 //--------------------------------------------------------------------------
169 //--------------------------------------------------------------------------
171 const STATEMENT_TYPE = /(?:Statement|Declaration)$/u;
174 * Determines if a given variable is being exported from a module.
175 * @param {Variable} variable eslint-scope variable object.
176 * @returns {boolean} True if the variable is exported, false if not.
179 function isExported(variable) {
181 const definition = variable.defs[0];
185 let node = definition.node;
187 if (node.type === "VariableDeclarator") {
189 } else if (definition.type === "Parameter") {
193 return node.parent.type.indexOf("Export") === 0;
200 * Determines if a variable has a sibling rest property
201 * @param {Variable} variable eslint-scope variable object.
202 * @returns {boolean} True if the variable is exported, false if not.
205 function hasRestSpreadSibling(variable) {
206 if (config.ignoreRestSiblings) {
207 return variable.defs.some(def => {
208 const propertyNode = def.name.parent;
209 const patternNode = propertyNode.parent;
212 propertyNode.type === "Property" &&
213 patternNode.type === "ObjectPattern" &&
214 REST_PROPERTY_TYPE.test(patternNode.properties[patternNode.properties.length - 1].type)
223 * Determines if a reference is a read operation.
224 * @param {Reference} ref An eslint-scope Reference
225 * @returns {boolean} whether the given reference represents a read operation
228 function isReadRef(ref) {
233 * Determine if an identifier is referencing an enclosing function name.
234 * @param {Reference} ref The reference to check.
235 * @param {ASTNode[]} nodes The candidate function nodes.
236 * @returns {boolean} True if it's a self-reference, false if not.
239 function isSelfReference(ref, nodes) {
240 let scope = ref.from;
243 if (nodes.indexOf(scope.block) >= 0) {
254 * Gets a list of function definitions for a specified variable.
255 * @param {Variable} variable eslint-scope variable object.
256 * @returns {ASTNode[]} Function nodes.
259 function getFunctionDefinitions(variable) {
260 const functionDefinitions = [];
262 variable.defs.forEach(def => {
263 const { type, node } = def;
265 // FunctionDeclarations
266 if (type === "FunctionName") {
267 functionDefinitions.push(node);
270 // FunctionExpressions
271 if (type === "Variable" && node.init &&
272 (node.init.type === "FunctionExpression" || node.init.type === "ArrowFunctionExpression")) {
273 functionDefinitions.push(node.init);
276 return functionDefinitions;
280 * Checks the position of given nodes.
281 * @param {ASTNode} inner A node which is expected as inside.
282 * @param {ASTNode} outer A node which is expected as outside.
283 * @returns {boolean} `true` if the `inner` node exists in the `outer` node.
286 function isInside(inner, outer) {
288 inner.range[0] >= outer.range[0] &&
289 inner.range[1] <= outer.range[1]
294 * If a given reference is left-hand side of an assignment, this gets
295 * the right-hand side node of the assignment.
297 * In the following cases, this returns null.
299 * - The reference is not the LHS of an assignment expression.
300 * - The reference is inside of a loop.
301 * - The reference is inside of a function scope which is different from
303 * @param {eslint-scope.Reference} ref A reference to check.
304 * @param {ASTNode} prevRhsNode The previous RHS node.
305 * @returns {ASTNode|null} The RHS node or null.
308 function getRhsNode(ref, prevRhsNode) {
309 const id = ref.identifier;
310 const parent = id.parent;
311 const grandparent = parent.parent;
312 const refScope = ref.from.variableScope;
313 const varScope = ref.resolved.scope.variableScope;
314 const canBeUsedLater = refScope !== varScope || astUtils.isInLoop(id);
317 * Inherits the previous node if this reference is in the node.
318 * This is for `a = a + a`-like code.
320 if (prevRhsNode && isInside(id, prevRhsNode)) {
324 if (parent.type === "AssignmentExpression" &&
325 grandparent.type === "ExpressionStatement" &&
326 id === parent.left &&
335 * Checks whether a given function node is stored to somewhere or not.
336 * If the function node is stored, the function can be used later.
337 * @param {ASTNode} funcNode A function node to check.
338 * @param {ASTNode} rhsNode The RHS node of the previous assignment.
339 * @returns {boolean} `true` if under the following conditions:
340 * - the funcNode is assigned to a variable.
341 * - the funcNode is bound as an argument of a function call.
342 * - the function is bound to a property and the object satisfies above conditions.
345 function isStorableFunction(funcNode, rhsNode) {
347 let parent = funcNode.parent;
349 while (parent && isInside(parent, rhsNode)) {
350 switch (parent.type) {
351 case "SequenceExpression":
352 if (parent.expressions[parent.expressions.length - 1] !== node) {
357 case "CallExpression":
358 case "NewExpression":
359 return parent.callee !== node;
361 case "AssignmentExpression":
362 case "TaggedTemplateExpression":
363 case "YieldExpression":
367 if (STATEMENT_TYPE.test(parent.type)) {
370 * If it encountered statements, this is a complex pattern.
371 * Since analyzing complex patterns is hard, this returns `true` to avoid false positive.
378 parent = parent.parent;
385 * Checks whether a given Identifier node exists inside of a function node which can be used later.
387 * "can be used later" means:
388 * - the function is assigned to a variable.
389 * - the function is bound to a property and the object can be used later.
390 * - the function is bound as an argument of a function call.
392 * If a reference exists in a function which can be used later, the reference is read when the function is called.
393 * @param {ASTNode} id An Identifier node to check.
394 * @param {ASTNode} rhsNode The RHS node of the previous assignment.
395 * @returns {boolean} `true` if the `id` node exists inside of a function node which can be used later.
398 function isInsideOfStorableFunction(id, rhsNode) {
399 const funcNode = astUtils.getUpperFunction(id);
403 isInside(funcNode, rhsNode) &&
404 isStorableFunction(funcNode, rhsNode)
409 * Checks whether a given reference is a read to update itself or not.
410 * @param {eslint-scope.Reference} ref A reference to check.
411 * @param {ASTNode} rhsNode The RHS node of the previous assignment.
412 * @returns {boolean} The reference is a read to update itself.
415 function isReadForItself(ref, rhsNode) {
416 const id = ref.identifier;
417 const parent = id.parent;
418 const grandparent = parent.parent;
420 return ref.isRead() && (
422 // self update. e.g. `a += 1`, `a++`
423 (// in RHS of an assignment for itself. e.g. `a = a + 1`
425 parent.type === "AssignmentExpression" &&
426 grandparent.type === "ExpressionStatement" &&
430 parent.type === "UpdateExpression" &&
431 grandparent.type === "ExpressionStatement"
433 isInside(id, rhsNode) &&
434 !isInsideOfStorableFunction(id, rhsNode)))
439 * Determine if an identifier is used either in for-in loops.
440 * @param {Reference} ref The reference to check.
441 * @returns {boolean} whether reference is used in the for-in loops
444 function isForInRef(ref) {
445 let target = ref.identifier.parent;
448 // "for (var ...) { return; }"
449 if (target.type === "VariableDeclarator") {
450 target = target.parent.parent;
453 if (target.type !== "ForInStatement") {
457 // "for (...) { return; }"
458 if (target.body.type === "BlockStatement") {
459 target = target.body.body[0];
461 // "for (...) return;"
463 target = target.body;
466 // For empty loop body
471 return target.type === "ReturnStatement";
475 * Determines if the variable is used.
476 * @param {Variable} variable The variable to check.
477 * @returns {boolean} True if the variable is used
480 function isUsedVariable(variable) {
481 const functionNodes = getFunctionDefinitions(variable),
482 isFunctionDefinition = functionNodes.length > 0;
485 return variable.references.some(ref => {
486 if (isForInRef(ref)) {
490 const forItself = isReadForItself(ref, rhsNode);
492 rhsNode = getRhsNode(ref, rhsNode);
497 !(isFunctionDefinition && isSelfReference(ref, functionNodes))
503 * Checks whether the given variable is after the last used parameter.
504 * @param {eslint-scope.Variable} variable The variable to check.
505 * @returns {boolean} `true` if the variable is defined after the last
508 function isAfterLastUsedArg(variable) {
509 const def = variable.defs[0];
510 const params = context.getDeclaredVariables(def.node);
511 const posteriorParams = params.slice(params.indexOf(variable) + 1);
513 // If any used parameters occur after this parameter, do not report.
514 return !posteriorParams.some(v => v.references.length > 0 || v.eslintUsed);
518 * Gets an array of variables without read references.
519 * @param {Scope} scope an eslint-scope Scope object.
520 * @param {Variable[]} unusedVars an array that saving result.
521 * @returns {Variable[]} unused variables of the scope and descendant scopes.
524 function collectUnusedVariables(scope, unusedVars) {
525 const variables = scope.variables;
526 const childScopes = scope.childScopes;
529 if (scope.type !== "global" || config.vars === "all") {
530 for (i = 0, l = variables.length; i < l; ++i) {
531 const variable = variables[i];
533 // skip a variable of class itself name in the class scope
534 if (scope.type === "class" && scope.block.id === variable.identifiers[0]) {
538 // skip function expression names and variables marked with markVariableAsUsed()
539 if (scope.functionExpressionScope || variable.eslintUsed) {
543 // skip implicit "arguments" variable
544 if (scope.type === "function" && variable.name === "arguments" && variable.identifiers.length === 0) {
548 // explicit global variables don't have definitions.
549 const def = variable.defs[0];
552 const type = def.type;
554 // skip catch variables
555 if (type === "CatchClause") {
556 if (config.caughtErrors === "none") {
560 // skip ignored parameters
561 if (config.caughtErrorsIgnorePattern && config.caughtErrorsIgnorePattern.test(def.name.name)) {
566 if (type === "Parameter") {
568 // skip any setter argument
569 if ((def.node.parent.type === "Property" || def.node.parent.type === "MethodDefinition") && def.node.parent.kind === "set") {
573 // if "args" option is "none", skip any parameter
574 if (config.args === "none") {
578 // skip ignored parameters
579 if (config.argsIgnorePattern && config.argsIgnorePattern.test(def.name.name)) {
583 // if "args" option is "after-used", skip used variables
584 if (config.args === "after-used" && astUtils.isFunction(def.name.parent) && !isAfterLastUsedArg(variable)) {
589 // skip ignored variables
590 if (config.varsIgnorePattern && config.varsIgnorePattern.test(def.name.name)) {
596 if (!isUsedVariable(variable) && !isExported(variable) && !hasRestSpreadSibling(variable)) {
597 unusedVars.push(variable);
602 for (i = 0, l = childScopes.length; i < l; ++i) {
603 collectUnusedVariables(childScopes[i], unusedVars);
609 //--------------------------------------------------------------------------
611 //--------------------------------------------------------------------------
614 "Program:exit"(programNode) {
615 const unusedVars = collectUnusedVariables(context.getScope(), []);
617 for (let i = 0, l = unusedVars.length; i < l; ++i) {
618 const unusedVar = unusedVars[i];
620 // Report the first declaration.
621 if (unusedVar.defs.length > 0) {
623 node: unusedVar.references.length ? unusedVar.references[
624 unusedVar.references.length - 1
625 ].identifier : unusedVar.identifiers[0],
626 messageId: "unusedVar",
627 data: unusedVar.references.some(ref => ref.isWrite())
628 ? getAssignedMessageData(unusedVar)
629 : getDefinedMessageData(unusedVar)
632 // If there are no regular declaration, report the first `/*globals*/` comment directive.
633 } else if (unusedVar.eslintExplicitGlobalComments) {
634 const directiveComment = unusedVar.eslintExplicitGlobalComments[0];
638 loc: astUtils.getNameLocationInGlobalDirectiveComment(sourceCode, directiveComment, unusedVar.name),
639 messageId: "unusedVar",
640 data: getDefinedMessageData(unusedVar)