bahlint 28.58.6934

package/lib/rules/prefer-const.js

@@ -0,0 +1,546 @@
+/**
+ * @fileoverview A rule to suggest using of const declaration for variables that are never reassigned after declared.
+ * @author Toru Nagashima
+ */
+
+"use strict";
+
+//------------------------------------------------------------------------------
+// Requirements
+//------------------------------------------------------------------------------
+
+const FixTracker = require("./utils/fix-tracker");
+const astUtils = require("./utils/ast-utils");
+
+//------------------------------------------------------------------------------
+// Helpers
+//------------------------------------------------------------------------------
+
+const PATTERN_TYPE =
+	/^(?:.+?Pattern|RestElement|SpreadProperty|ExperimentalRestProperty|Property)$/u;
+const DECLARATION_HOST_TYPE =
+	/^(?:Program|BlockStatement|StaticBlock|SwitchCase)$/u;
+const DESTRUCTURING_HOST_TYPE =
+	/^(?:VariableDeclarator|AssignmentExpression)$/u;
+
+/**
+ * Checks whether a given node is located at `ForStatement.init` or not.
+ * @param {ASTNode} node A node to check.
+ * @returns {boolean} `true` if the node is located at `ForStatement.init`.
+ */
+function isInitOfForStatement(node) {
+	return node.parent.type === "ForStatement" && node.parent.init === node;
+}
+
+/**
+ * Checks whether a given Identifier node becomes a VariableDeclaration or not.
+ * @param {ASTNode} identifier An Identifier node to check.
+ * @returns {boolean} `true` if the node can become a VariableDeclaration.
+ */
+function canBecomeVariableDeclaration(identifier) {
+	let node = identifier.parent;
+
+	while (PATTERN_TYPE.test(node.type)) {
+		node = node.parent;
+	}
+
+	return (
+		node.type === "VariableDeclarator" ||
+		(node.type === "AssignmentExpression" &&
+			node.parent.type === "ExpressionStatement" &&
+			DECLARATION_HOST_TYPE.test(node.parent.parent.type))
+	);
+}
+
+/**
+ * Checks if an property or element is from outer scope or function parameters
+ * in destructing pattern.
+ * @param {string} name A variable name to be checked.
+ * @param {eslint-scope.Scope} initScope A scope to start find.
+ * @returns {boolean} Indicates if the variable is from outer scope or function parameters.
+ */
+function isOuterVariableInDestructing(name, initScope) {
+	if (
+		initScope.through.some(
+			ref => ref.resolved && ref.resolved.name === name,
+		)
+	) {
+		return true;
+	}
+
+	const variable = astUtils.getVariableByName(initScope, name);
+
+	if (variable !== null) {
+		return variable.defs.some(def => def.type === "Parameter");
+	}
+
+	return false;
+}
+
+/**
+ * Gets the VariableDeclarator/AssignmentExpression node that a given reference
+ * belongs to.
+ * This is used to detect a mix of reassigned and never reassigned in a
+ * destructuring.
+ * @param {eslint-scope.Reference} reference A reference to get.
+ * @returns {ASTNode|null} A VariableDeclarator/AssignmentExpression node or
+ *      null.
+ */
+function getDestructuringHost(reference) {
+	if (!reference.isWrite()) {
+		return null;
+	}
+	let node = reference.identifier.parent;
+
+	while (PATTERN_TYPE.test(node.type)) {
+		node = node.parent;
+	}
+
+	if (!DESTRUCTURING_HOST_TYPE.test(node.type)) {
+		return null;
+	}
+	return node;
+}
+
+/**
+ * Determines if a destructuring assignment node contains
+ * any MemberExpression nodes. This is used to determine if a
+ * variable that is only written once using destructuring can be
+ * safely converted into a const declaration.
+ * @param {ASTNode} node The ObjectPattern or ArrayPattern node to check.
+ * @returns {boolean} True if the destructuring pattern contains
+ *      a MemberExpression, false if not.
+ */
+function hasMemberExpressionAssignment(node) {
+	switch (node.type) {
+		case "ObjectPattern":
+			return node.properties.some(prop => {
+				if (prop) {
+					/*
+					 * Spread elements have an argument property while
+					 * others have a value property. Because different
+					 * parsers use different node types for spread elements,
+					 * we just check if there is an argument property.
+					 */
+					return hasMemberExpressionAssignment(
+						prop.argument || prop.value,
+					);
+				}
+
+				return false;
+			});
+
+		case "ArrayPattern":
+			return node.elements.some(element => {
+				if (element) {
+					return hasMemberExpressionAssignment(element);
+				}
+
+				return false;
+			});
+
+		case "AssignmentPattern":
+			return hasMemberExpressionAssignment(node.left);
+
+		case "MemberExpression":
+			return true;
+
+		// no default
+	}
+
+	return false;
+}
+
+/**
+ * Gets an identifier node of a given variable.
+ *
+ * If the initialization exists or one or more reading references exist before
+ * the first assignment, the identifier node is the node of the declaration.
+ * Otherwise, the identifier node is the node of the first assignment.
+ *
+ * If the variable should not change to const, this function returns null.
+ * - If the variable is reassigned.
+ * - If the variable is never initialized nor assigned.
+ * - If the variable is initialized in a different scope from the declaration.
+ * - If the unique assignment of the variable cannot change to a declaration.
+ *   e.g. `if (a) b = 1` / `return (b = 1)`
+ * - If the variable is declared in the global scope and `eslintUsed` is `true`.
+ *   `/*exported foo` directive comment makes such variables. This rule does not
+ *   warn such variables because this rule cannot distinguish whether the
+ *   exported variables are reassigned or not.
+ * @param {eslint-scope.Variable} variable A variable to get.
+ * @param {boolean} ignoreReadBeforeAssign
+ *      The value of `ignoreReadBeforeAssign` option.
+ * @returns {ASTNode|null}
+ *      An Identifier node if the variable should change to const.
+ *      Otherwise, null.
+ */
+function getIdentifierIfShouldBeConst(variable, ignoreReadBeforeAssign) {
+	if (variable.eslintUsed && variable.scope.type === "global") {
+		return null;
+	}
+
+	// Finds the unique WriteReference.
+	let writer = null;
+	let isReadBeforeInit = false;
+	const references = variable.references;
+
+	for (let i = 0; i < references.length; ++i) {
+		const reference = references[i];
+
+		if (reference.isWrite()) {
+			const isReassigned =
+				writer !== null && writer.identifier !== reference.identifier;
+
+			if (isReassigned) {
+				return null;
+			}
+
+			const destructuringHost = getDestructuringHost(reference);
+
+			if (
+				destructuringHost !== null &&
+				destructuringHost.left !== void 0
+			) {
+				const leftNode = destructuringHost.left;
+				let hasOuterVariables = false,
+					hasNonIdentifiers = false;
+
+				if (leftNode.type === "ObjectPattern") {
+					const properties = leftNode.properties;
+
+					hasOuterVariables = properties
+						.filter(prop => prop.value)
+						.map(prop => prop.value.name)
+						.some(name =>
+							isOuterVariableInDestructing(name, variable.scope),
+						);
+
+					hasNonIdentifiers = hasMemberExpressionAssignment(leftNode);
+				} else if (leftNode.type === "ArrayPattern") {
+					const elements = leftNode.elements;
+
+					hasOuterVariables = elements
+						.map(element => element && element.name)
+						.some(name =>
+							isOuterVariableInDestructing(name, variable.scope),
+						);
+
+					hasNonIdentifiers = hasMemberExpressionAssignment(leftNode);
+				}
+
+				if (hasOuterVariables || hasNonIdentifiers) {
+					return null;
+				}
+			}
+
+			writer = reference;
+		} else if (reference.isRead() && writer === null) {
+			if (ignoreReadBeforeAssign) {
+				return null;
+			}
+			isReadBeforeInit = true;
+		}
+	}
+
+	/*
+	 * If the assignment is from a different scope, ignore it.
+	 * If the assignment cannot change to a declaration, ignore it.
+	 */
+	const shouldBeConst =
+		writer !== null &&
+		writer.from === variable.scope &&
+		canBecomeVariableDeclaration(writer.identifier);
+
+	if (!shouldBeConst) {
+		return null;
+	}
+
+	if (isReadBeforeInit) {
+		return variable.defs[0].name;
+	}
+
+	return writer.identifier;
+}
+
+/**
+ * Groups by the VariableDeclarator/AssignmentExpression node that each
+ * reference of given variables belongs to.
+ * This is used to detect a mix of reassigned and never reassigned in a
+ * destructuring.
+ * @param {eslint-scope.Variable[]} variables Variables to group by destructuring.
+ * @param {boolean} ignoreReadBeforeAssign
+ *      The value of `ignoreReadBeforeAssign` option.
+ * @returns {Map<ASTNode, ASTNode[]>} Grouped identifier nodes.
+ */
+function groupByDestructuring(variables, ignoreReadBeforeAssign) {
+	const identifierMap = new Map();
+
+	for (let i = 0; i < variables.length; ++i) {
+		const variable = variables[i];
+		const references = variable.references;
+		const identifier = getIdentifierIfShouldBeConst(
+			variable,
+			ignoreReadBeforeAssign,
+		);
+		let prevId = null;
+
+		for (let j = 0; j < references.length; ++j) {
+			const reference = references[j];
+			const id = reference.identifier;
+
+			/*
+			 * Avoid counting a reference twice or more for default values of
+			 * destructuring.
+			 */
+			if (id === prevId) {
+				continue;
+			}
+			prevId = id;
+
+			// Add the identifier node into the destructuring group.
+			const group = getDestructuringHost(reference);
+
+			if (group) {
+				if (identifierMap.has(group)) {
+					identifierMap.get(group).push(identifier);
+				} else {
+					identifierMap.set(group, [identifier]);
+				}
+			}
+		}
+	}
+
+	return identifierMap;
+}
+
+/**
+ * Finds the nearest parent of node with a given type.
+ * @param {ASTNode} node The node to search from.
+ * @param {string} type The type field of the parent node.
+ * @param {Function} shouldStop A predicate that returns true if the traversal should stop, and false otherwise.
+ * @returns {ASTNode} The closest ancestor with the specified type; null if no such ancestor exists.
+ */
+function findUp(node, type, shouldStop) {
+	if (!node || shouldStop(node)) {
+		return null;
+	}
+	if (node.type === type) {
+		return node;
+	}
+	return findUp(node.parent, type, shouldStop);
+}
+
+//------------------------------------------------------------------------------
+// Rule Definition
+//------------------------------------------------------------------------------
+
+/** @type {import('../types').Rule.RuleModule} */
+module.exports = {
+	meta: {
+		type: "suggestion",
+
+		defaultOptions: [
+			{
+				destructuring: "any",
+				ignoreReadBeforeAssign: false,
+			},
+		],
+
+		docs: {
+			description:
+				"Require `const` declarations for variables that are never reassigned after declared",
+			recommended: false,
+			url: "https://eslint.org/docs/latest/rules/prefer-const",
+		},
+
+		fixable: "code",
+
+		schema: [
+			{
+				type: "object",
+				properties: {
+					destructuring: { enum: ["any", "all"] },
+					ignoreReadBeforeAssign: { type: "boolean" },
+				},
+				additionalProperties: false,
+			},
+		],
+		messages: {
+			useConst: "'{{name}}' is never reassigned. Use 'const' instead.",
+		},
+	},
+
+	create(context) {
+		const [{ destructuring, ignoreReadBeforeAssign }] = context.options;
+		const shouldMatchAnyDestructuredVariable = destructuring !== "all";
+		const sourceCode = context.sourceCode;
+		const variables = [];
+		let reportCount = 0;
+		let checkedId = null;
+		let checkedName = "";
+
+		/**
+		 * Reports given identifier nodes if all of the nodes should be declared
+		 * as const.
+		 *
+		 * The argument 'nodes' is an array of Identifier nodes.
+		 * This node is the result of 'getIdentifierIfShouldBeConst()', so it's
+		 * nullable. In simple declaration or assignment cases, the length of
+		 * the array is 1. In destructuring cases, the length of the array can
+		 * be 2 or more.
+		 * @param {(eslint-scope.Reference|null)[]} nodes
+		 *      References which are grouped by destructuring to report.
+		 * @returns {void}
+		 */
+		function checkGroup(nodes) {
+			const nodesToReport = nodes.filter(Boolean);
+
+			if (
+				nodes.length &&
+				(shouldMatchAnyDestructuredVariable ||
+					nodesToReport.length === nodes.length)
+			) {
+				const varDeclParent = findUp(
+					nodes[0],
+					"VariableDeclaration",
+					parentNode => parentNode.type.endsWith("Statement"),
+				);
+				const isVarDecParentNull = varDeclParent === null;
+
+				if (
+					!isVarDecParentNull &&
+					varDeclParent.declarations.length > 0
+				) {
+					const firstDeclaration = varDeclParent.declarations[0];
+
+					if (firstDeclaration.init) {
+						const firstDecParent = firstDeclaration.init.parent;
+
+						/*
+						 * First we check the declaration type and then depending on
+						 * if the type is a "VariableDeclarator" or its an "ObjectPattern"
+						 * we compare the name and id from the first identifier, if the names are different
+						 * we assign the new name, id and reset the count of reportCount and nodeCount in
+						 * order to check each block for the number of reported errors and base our fix
+						 * based on comparing nodes.length and nodesToReport.length.
+						 */
+
+						if (firstDecParent.type === "VariableDeclarator") {
+							if (firstDecParent.id.name !== checkedName) {
+								checkedName = firstDecParent.id.name;
+								reportCount = 0;
+							}
+
+							if (firstDecParent.id.type === "ObjectPattern") {
+								if (firstDecParent.init.name !== checkedName) {
+									checkedName = firstDecParent.init.name;
+									reportCount = 0;
+								}
+							}
+
+							if (firstDecParent.id !== checkedId) {
+								checkedId = firstDecParent.id;
+								reportCount = 0;
+							}
+						}
+					}
+				}
+
+				let shouldFix =
+					varDeclParent &&
+					// Don't do a fix unless all variables in the declarations are initialized (or it's in a for-in or for-of loop)
+					(varDeclParent.parent.type === "ForInStatement" ||
+						varDeclParent.parent.type === "ForOfStatement" ||
+						varDeclParent.declarations.every(
+							declaration => declaration.init,
+						)) &&
+					/*
+					 * If options.destructuring is "all", then this warning will not occur unless
+					 * every assignment in the destructuring should be const. In that case, it's safe
+					 * to apply the fix.
+					 */
+					nodesToReport.length === nodes.length;
+
+				if (
+					!isVarDecParentNull &&
+					varDeclParent.declarations &&
+					varDeclParent.declarations.length !== 1
+				) {
+					if (
+						varDeclParent &&
+						varDeclParent.declarations &&
+						varDeclParent.declarations.length >= 1
+					) {
+						/*
+						 * Add nodesToReport.length to a count, then comparing the count to the length
+						 * of the declarations in the current block.
+						 */
+
+						reportCount += nodesToReport.length;
+
+						let totalDeclarationsCount = 0;
+
+						varDeclParent.declarations.forEach(declaration => {
+							if (declaration.id.type === "ObjectPattern") {
+								totalDeclarationsCount +=
+									declaration.id.properties.length;
+							} else if (declaration.id.type === "ArrayPattern") {
+								totalDeclarationsCount +=
+									declaration.id.elements.length;
+							} else {
+								totalDeclarationsCount += 1;
+							}
+						});
+
+						shouldFix =
+							shouldFix && reportCount === totalDeclarationsCount;
+					}
+				}
+
+				nodesToReport.forEach(node => {
+					context.report({
+						node,
+						messageId: "useConst",
+						data: node,
+						fix: shouldFix
+							? fixer => {
+									const letKeywordToken =
+										sourceCode.getFirstToken(
+											varDeclParent,
+											t => t.value === varDeclParent.kind,
+										);
+
+									/**
+									 * Extend the replacement range to the whole declaration,
+									 * in order to prevent other fixes in the same pass
+									 * https://github.com/eslint/eslint/issues/13899
+									 */
+									return new FixTracker(fixer, sourceCode)
+										.retainRange(varDeclParent.range)
+										.replaceTextRange(
+											letKeywordToken.range,
+											"const",
+										);
+								}
+							: null,
+					});
+				});
+			}
+		}
+
+		return {
+			"Program:exit"() {
+				groupByDestructuring(variables, ignoreReadBeforeAssign).forEach(
+					checkGroup,
+				);
+			},
+
+			VariableDeclaration(node) {
+				if (node.kind === "let" && !isInitOfForStatement(node)) {
+					variables.push(...sourceCode.getDeclaredVariables(node));
+				}
+			},
+		};
+	},
+};