feat: Add ignoreOnInitialization option to no-shadow rule

docs/rules/no-shadow.md

@@ -42,11 +42,11 @@ if (true) {
 
 ## Options
 
-This rule takes one option, an object, with properties `"builtinGlobals"`, `"hoist"` and `"allow"`.
+This rule takes one option, an object, with properties `"builtinGlobals"`, `"hoist"`, `"allow"` and `"ignoreOnInitialization"`.
 
 ```json
 {
-    "no-shadow": ["error", { "builtinGlobals": false, "hoist": "functions", "allow": [] }]
+    "no-shadow": ["error", { "builtinGlobals": false, "hoist": "functions", "allow": [], "ignoreOnInitialization": false }]
 }
 ```
 
@@ -164,6 +164,31 @@ foo(function (err, result) {
 });
 ```
 
+### ignoreOnInitialization
+
+The `ignoreOnInitialization` option is `false` by default.
+If it is `true`, the rule prevents reporting variables on initialization statements, the shadowed variable must be on the left side and the shadowing variable must be on the right side.
+
+Examples of **incorrect** code for the default `{ "ignoreOnInitialization": "true" }` option:
+
+```js
+/*eslint no-shadow: ["error", { "ignoreOnInitialization": true }]*/
+
+var x = x => x;
+```
+
+Because the shadowing variable x will shadow an initialized shadowed variable x.
+
+Examples of **correct** code for the `{ "ignoreOnInitialization": true }` option:
+
+```js
+/*eslint no-shadow: ["error", { "ignoreOnInitialization": true }]*/
+
+var x = foo(x => x)
+```
+
+Because the shadowing variable x will shadow an uninitialized shadowed variable x.
+
 ## Related Rules
 
 * [no-shadow-restricted-names](no-shadow-restricted-names.md)

lib/rules/no-shadow.js

@@ -11,6 +11,15 @@
 
 const astUtils = require("./utils/ast-utils");
 
+//------------------------------------------------------------------------------
+// Helpers
+//------------------------------------------------------------------------------
+
+const FUN_NODES_TYPES = ["ArrowFunctionExpression", "FunctionExpression"];
+const CALL_EXP_NODE_TYPE = ["CallExpression"];
+const SENTINEL_TYPE = /^(?:(?:Function|Class)(?:Declaration|Expression)|ArrowFunctionExpression|CatchClause|ImportDeclaration|ExportNamedDeclaration)$/u;
+const FOR_IN_OF_TYPE = /^For(?:In|Of)Statement$/u;
+
 //------------------------------------------------------------------------------
 // Rule Definition
 //------------------------------------------------------------------------------
@@ -37,7 +46,8 @@ module.exports = {
                         items: {
                             type: "string"
                         }
-                    }
+                    },
+                    ignoreOnInitialization: { type: "boolean", default: false }
                 },
                 additionalProperties: false
             }
@@ -54,9 +64,120 @@ module.exports = {
         const options = {
             builtinGlobals: context.options[0] && context.options[0].builtinGlobals,
             hoist: (context.options[0] && context.options[0].hoist) || "functions",
-            allow: (context.options[0] && context.options[0].allow) || []
+            allow: (context.options[0] && context.options[0].allow) || [],
+            ignoreOnInitialization: context.options[0] && context.options[0].ignoreOnInitialization
         };
 
+        /**
+         * Checks whether or not a given location is inside of the range of a given node.
+         * @param {ASTNode} node An node to check.
+         * @param {number} location A location to check.
+         * @returns {boolean} `true` if the location is inside of the range of the node.
+         */
+        function isInRange(node, location) {
+            return node && node.range[0] <= location && location <= node.range[1];
+        }
+
+        /**
+         * Checks whether or not the nodes types include the node type.
+         * @param {ASTNode} node a node to get.
+         * @param {[string]} types an array of nodes types.
+         * @returns {boolean} True if nodes types include the node type.
+         */
+        function isNodeMatchesTypes(node, types) {
+            return types.includes(node.type);
+        }
+
+        /**
+         * Searches from the current node through its ancestry to find a matching node.
+         * @param {ASTNode} node a node to get.
+         * @param {MatchCallback} match a callback that checks whether or not the node verifies its condition or not.
+         * @param {StopSearchingCallback} stopSearching a callback that checks whether or not the searching should be stopped or not.
+         * @returns {ASTNode} the matching node.
+         */
+        function findSelfOrAncestor(node, match, stopSearching) {
+            let currentNode = node;
+
+            while (currentNode && !match(currentNode)) {
+                if (stopSearching && stopSearching(currentNode)) {
+                    return null;
+                }
+                currentNode = currentNode.parent;
+            }
+            return currentNode;
+        }
+
+        /**
+         * Finds function's outer scope.
+         * @param {Scope} scope Function's own scope.
+         * @returns {Scope} Function's outer scope.
+         */
+        function getOuterScope(scope) {
+            const upper = scope.upper;
+
+            if (upper.type === "function-expression-name") {
+                return upper.upper;
+            }
+            return upper;
+        }
+
+        /**
+         * Checks if a variable and a shadowedVariable have the same init pattern ancestor.
+         * @param {Object} variable a variable to check.
+         * @param {Object} shadowedVariable a shadowedVariable to check.
+         * @returns {boolean} Whether or not the variable and the shadowedVariable have the same init pattern ancestor.
+         */
+        function isInitPatternNode(variable, shadowedVariable) {
+            const outerDef = shadowedVariable.defs[0];
+            const { variableScope } = variable.scope;
+
+
+            if (!(FUN_NODES_TYPES.includes(variableScope.block.type) && getOuterScope(variableScope) === shadowedVariable.scope)) {
+                return false;
+            }
+
+            const fun = variableScope.block;
+            const { parent } = fun;
+
+            const callExpression = findSelfOrAncestor(
+                parent,
+                node => isNodeMatchesTypes(node, CALL_EXP_NODE_TYPE),
+                node => isNodeMatchesTypes(node, FUN_NODES_TYPES)
+            );
+
+            if (!callExpression) {
+                return false;
+            }
+
+            let node = outerDef && outerDef.name;
+            const innerDef = variable.defs[0];
+            const location = innerDef && innerDef.name.range[1];
+
+            while (node) {
+                if (node.type === "VariableDeclarator") {
+                    if (isInRange(node.init, location)) {
+                        return true;
+                    }
+                    if (FOR_IN_OF_TYPE.test(node.parent.parent.type) &&
+                        isInRange(node.parent.parent.right, location)
+                    ) {
+                        return true;
+                    }
+                    break;
+                } else if (node.type === "AssignmentPattern") {
+                    if (isInRange(node.right, location)) {
+                        return true;
+                    }
+                } else if (SENTINEL_TYPE.test(node.type)) {
+                    break;
+                }
+
+                node = node.parent;
+            }
+
+            return false;
+        }
+
         /**
          * Check if variable name is allowed.
          * @param {ASTNode} variable The variable to check.
@@ -99,11 +220,11 @@ module.exports = {
 
             return (
                 outer &&
-                inner &&
-                outer[0] < inner[0] &&
-                inner[1] < outer[1] &&
-                ((innerDef.type === "FunctionName" && innerDef.node.type === "FunctionExpression") || innerDef.node.type === "ClassExpression") &&
-                outerScope === innerScope.upper
+                 inner &&
+                 outer[0] < inner[0] &&
+                 inner[1] < outer[1] &&
+                 ((innerDef.type === "FunctionName" && innerDef.node.type === "FunctionExpression") || innerDef.node.type === "ClassExpression") &&
+                 outerScope === innerScope.upper
             );
         }
 
@@ -154,11 +275,11 @@ module.exports = {
 
             return (
                 inner &&
-                outer &&
-                inner[1] < outer[0] &&
+                 outer &&
+                 inner[1] < outer[0] &&
 
-                // Excepts FunctionDeclaration if is {"hoist":"function"}.
-                (options.hoist !== "functions" || !outerDef || outerDef.node.type !== "FunctionDeclaration")
+                 // Excepts FunctionDeclaration if is {"hoist":"function"}.
+                 (options.hoist !== "functions" || !outerDef || outerDef.node.type !== "FunctionDeclaration")
             );
         }
 
@@ -175,8 +296,8 @@ module.exports = {
 
                 // Skips "arguments" or variables of a class name in the class scope of ClassDeclaration.
                 if (variable.identifiers.length === 0 ||
-                    isDuplicatedClassNameVariable(variable) ||
-                    isAllowed(variable)
+                     isDuplicatedClassNameVariable(variable) ||
+                     isAllowed(variable)
                 ) {
                     continue;
                 }
@@ -185,9 +306,10 @@ module.exports = {
                 const shadowed = astUtils.getVariableByName(scope.upper, variable.name);
 
                 if (shadowed &&
-                    (shadowed.identifiers.length > 0 || (options.builtinGlobals && "writeable" in shadowed)) &&
-                    !isOnInitializer(variable, shadowed) &&
-                    !(options.hoist !== "all" && isInTdz(variable, shadowed))
+                      (shadowed.identifiers.length > 0 || (options.builtinGlobals && "writeable" in shadowed)) &&
+                      !isOnInitializer(variable, shadowed) &&
+                      (!(options.ignoreOnInitialization && isInitPatternNode(variable, shadowed)) || options.hoist === "all") &&
+                      !(options.hoist !== "all" && isInTdz(variable, shadowed))
                 ) {
                     const location = getDeclaredLocation(shadowed);
                     const messageId = location.global ? "noShadowGlobal" : "noShadow";