vscode-extension--copy-words-to-clipboard/hover-words-to-copy/node_modules/eslint/lib/rules/prefer-const.js

/**
 * @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));
				}
			},
		};
	},
};