eslint 9.27.0 → 9.28.0

package/lib/linter/{node-event-generator.js → source-code-traverser.js}

@@ -1,6 +1,6 @@
 /**
- * @fileoverview The event generator for AST nodes.
- * @author Toru Nagashima
+ * @fileoverview Traverser for SourceCode objects.
+ * @author Nicholas C. Zakas
  */
 
 "use strict";
@@ -10,6 +10,7 @@
 //------------------------------------------------------------------------------
 
 const { parse, matches } = require("./esquery");
+const vk = require("eslint-visitor-keys");
 
 //-----------------------------------------------------------------------------
 // Typedefs
@@ -17,12 +18,16 @@ const { parse, matches } = require("./esquery");
 
 /**
  * @import { ESQueryParsedSelector } from "./esquery.js";
+ * @import { Language, SourceCode } from "@eslint/core";
  */
 
 //-----------------------------------------------------------------------------
 // Helpers
 //-----------------------------------------------------------------------------
 
+const STEP_KIND_VISIT = 1;
+const STEP_KIND_CALL = 2;
+
 /**
  * Compares two ESQuery selectors by specificity.
  * @param {ESQueryParsedSelector} a The first selector to compare.
@@ -33,69 +38,10 @@ function compareSpecificity(a, b) {
 	return a.compare(b);
 }
 
-//------------------------------------------------------------------------------
-// Public Interface
-//------------------------------------------------------------------------------
-
 /**
- * The event generator for AST nodes.
- * This implements below interface.
- *
- * ```ts
- * interface EventGenerator {
- *     emitter: SafeEmitter;
- *     enterNode(node: ASTNode): void;
- *     leaveNode(node: ASTNode): void;
- * }
- * ```
+ * Helper to wrap ESQuery operations.
  */
-class NodeEventGenerator {
-	/**
-	 * The emitter to use during traversal.
-	 * @type {SafeEmitter}
-	 */
-	emitter;
-
-	/**
-	 * The options for `esquery` to use during matching.
-	 * @type {ESQueryOptions}
-	 */
-	esqueryOptions;
-
-	/**
-	 * The ancestry of the currently visited node.
-	 * @type {ASTNode[]}
-	 */
-	currentAncestry = [];
-
-	/**
-	 * A map of node type to selectors targeting that node type on the
-	 * enter phase of traversal.
-	 * @type {Map<string, ESQueryParsedSelector[]>}
-	 */
-	enterSelectorsByNodeType = new Map();
-
-	/**
-	 * A map of node type to selectors targeting that node type on the
-	 * exit phase of traversal.
-	 * @type {Map<string, ESQueryParsedSelector[]>}
-	 */
-	exitSelectorsByNodeType = new Map();
-
-	/**
-	 * An array of selectors that match any node type on the
-	 * enter phase of traversal.
-	 * @type {ESQueryParsedSelector[]}
-	 */
-	anyTypeEnterSelectors = [];
-
-	/**
-	 * An array of selectors that match any node type on the
-	 * exit phase of traversal.
-	 * @type {ESQueryParsedSelector[]}
-	 */
-	anyTypeExitSelectors = [];
-
+class ESQueryHelper {
 	/**
 	 * @param {SafeEmitter} emitter
 	 * An SafeEmitter which is the destination of events. This emitter must already
@@ -105,9 +51,46 @@ class NodeEventGenerator {
 	 * @returns {NodeEventGenerator} new instance
 	 */
 	constructor(emitter, esqueryOptions) {
+		/**
+		 * The emitter to use during traversal.
+		 * @type {SafeEmitter}
+		 */
 		this.emitter = emitter;
+
+		/**
+		 * The options for `esquery` to use during matching.
+		 * @type {ESQueryOptions}
+		 */
 		this.esqueryOptions = esqueryOptions;
 
+		/**
+		 * A map of node type to selectors targeting that node type on the
+		 * enter phase of traversal.
+		 * @type {Map<string, ESQueryParsedSelector[]>}
+		 */
+		this.enterSelectorsByNodeType = new Map();
+
+		/**
+		 * A map of node type to selectors targeting that node type on the
+		 * exit phase of traversal.
+		 * @type {Map<string, ESQueryParsedSelector[]>}
+		 */
+		this.exitSelectorsByNodeType = new Map();
+
+		/**
+		 * An array of selectors that match any node type on the
+		 * enter phase of traversal.
+		 * @type {ESQueryParsedSelector[]}
+		 */
+		this.anyTypeEnterSelectors = [];
+
+		/**
+		 * An array of selectors that match any node type on the
+		 * exit phase of traversal.
+		 * @type {ESQueryParsedSelector[]}
+		 */
+		this.anyTypeExitSelectors = [];
+
 		emitter.eventNames().forEach(rawSelector => {
 			const selector = parse(rawSelector);
 
@@ -156,18 +139,12 @@ class NodeEventGenerator {
 	/**
 	 * Checks a selector against a node, and emits it if it matches
 	 * @param {ASTNode} node The node to check
+	 * @param {ASTNode[]} ancestry The ancestry of the node being checked.
 	 * @param {ESQueryParsedSelector} selector An AST selector descriptor
 	 * @returns {void}
 	 */
-	applySelector(node, selector) {
-		if (
-			matches(
-				node,
-				selector.root,
-				this.currentAncestry,
-				this.esqueryOptions,
-			)
-		) {
+	#applySelector(node, ancestry, selector) {
+		if (matches(node, selector.root, ancestry, this.esqueryOptions)) {
 			this.emitter.emit(selector.source, node);
 		}
 	}
@@ -175,10 +152,11 @@ class NodeEventGenerator {
 	/**
 	 * Applies all appropriate selectors to a node, in specificity order
 	 * @param {ASTNode} node The node to check
+	 * @param {ASTNode[]} ancestry The ancestry of the node being checked.
 	 * @param {boolean} isExit `false` if the node is currently being entered, `true` if it's currently being exited
 	 * @returns {void}
 	 */
-	applySelectors(node, isExit) {
+	applySelectors(node, ancestry, isExit) {
 		const nodeTypeKey = this.esqueryOptions?.nodeTypeKey || "type";
 
 		/*
@@ -218,39 +196,117 @@ class NodeEventGenerator {
 						selectorsByNodeType[selectorsByNodeTypeIndex],
 					) < 0)
 			) {
-				this.applySelector(
+				this.#applySelector(
 					node,
+					ancestry,
 					anyTypeSelectors[anyTypeSelectorsIndex++],
 				);
 			} else {
 				// otherwise apply the node type selector
-				this.applySelector(
+				this.#applySelector(
 					node,
+					ancestry,
 					selectorsByNodeType[selectorsByNodeTypeIndex++],
 				);
 			}
 		}
 	}
+}
+
+//------------------------------------------------------------------------------
+// Public Interface
+//------------------------------------------------------------------------------
 
+/**
+ * Traverses source code and ensures that visitor methods are called when
+ * entering and leaving each node.
+ */
+class SourceCodeTraverser {
 	/**
-	 * Emits an event of entering AST node.
-	 * @param {ASTNode} node A node which was entered.
-	 * @returns {void}
+	 * The language of the source code being traversed.
+	 * @type {Language}
+	 */
+	#language;
+
+	/**
+	 * Map of languages to instances of this class.
+	 * @type {WeakMap<Language, SourceCodeTraverser>}
+	 */
+	static instances = new WeakMap();
+
+	/**
+	 * Creates a new instance.
+	 * @param {Language} language The language of the source code being traversed.
 	 */
-	enterNode(node) {
-		this.applySelectors(node, false);
-		this.currentAncestry.unshift(node);
+	constructor(language) {
+		this.#language = language;
+	}
+
+	static getInstance(language) {
+		if (!this.instances.has(language)) {
+			this.instances.set(language, new this(language));
+		}
+
+		return this.instances.get(language);
 	}
 
 	/**
-	 * Emits an event of leaving AST node.
-	 * @param {ASTNode} node A node which was left.
+	 * Traverses the given source code synchronously.
+	 * @param {SourceCode} sourceCode The source code to traverse.
+	 * @param {SafeEmitter} emitter The emitter to use for events.
+	 * @param {Object} options Options for traversal.
+	 * @param {ReturnType<SourceCode["traverse"]>} options.steps The steps to take during traversal.
 	 * @returns {void}
+	 * @throws {Error} If an error occurs during traversal.
 	 */
-	leaveNode(node) {
-		this.currentAncestry.shift();
-		this.applySelectors(node, true);
+	traverseSync(sourceCode, emitter, { steps } = {}) {
+		const esquery = new ESQueryHelper(emitter, {
+			visitorKeys: sourceCode.visitorKeys ?? this.#language.visitorKeys,
+			fallback: vk.getKeys,
+			matchClass: this.#language.matchesSelectorClass ?? (() => false),
+			nodeTypeKey: this.#language.nodeTypeKey,
+		});
+
+		const currentAncestry = [];
+
+		for (const step of steps ?? sourceCode.traverse()) {
+			switch (step.kind) {
+				case STEP_KIND_VISIT: {
+					try {
+						if (step.phase === 1) {
+							esquery.applySelectors(
+								step.target,
+								currentAncestry,
+								false,
+							);
+							currentAncestry.unshift(step.target);
+						} else {
+							currentAncestry.shift();
+							esquery.applySelectors(
+								step.target,
+								currentAncestry,
+								true,
+							);
+						}
+					} catch (err) {
+						err.currentNode = step.target;
+						throw err;
+					}
+					break;
+				}
+
+				case STEP_KIND_CALL: {
+					emitter.emit(step.target, ...step.args);
+					break;
+				}
+
+				default:
+					throw new Error(
+						`Invalid traversal step found: "${step.kind}".`,
+					);
+			}
+		}
 	}
 }
 
-module.exports = NodeEventGenerator;
+module.exports = { SourceCodeTraverser };

package/lib/options.js

@@ -66,6 +66,7 @@ const optionator = require("optionator");
  * @property {string[]} [suppressRule] Suppress specific rules
  * @property {string} [suppressionsLocation] Path to the suppressions file or directory
  * @property {boolean} [pruneSuppressions] Prune unused suppressions
+ * @property {boolean} [passOnUnprunedSuppressions] Ignore unused suppressions
  */
 
 //------------------------------------------------------------------------------
@@ -449,6 +450,12 @@ module.exports = function (usingFlatConfig) {
 				default: "false",
 				description: "Prune unused suppressions",
 			},
+			{
+				option: "pass-on-unpruned-suppressions",
+				type: "Boolean",
+				default: "false",
+				description: "Ignore unused suppressions",
+			},
 			{
 				heading: "Miscellaneous",
 			},

package/lib/rules/func-style.js

@@ -11,12 +11,15 @@
 /** @type {import('../types').Rule.RuleModule} */
 module.exports = {
 	meta: {
+		dialects: ["javascript", "typescript"],
+		language: "javascript",
 		type: "suggestion",
 
 		defaultOptions: [
 			"expression",
 			{
 				allowArrowFunctions: false,
+				allowTypeAnnotation: false,
 				overrides: {},
 			},
 		],
@@ -39,6 +42,9 @@ module.exports = {
 					allowArrowFunctions: {
 						type: "boolean",
 					},
+					allowTypeAnnotation: {
+						type: "boolean",
+					},
 					overrides: {
 						type: "object",
 						properties: {
@@ -60,11 +66,49 @@ module.exports = {
 	},
 
 	create(context) {
-		const [style, { allowArrowFunctions, overrides }] = context.options;
+		const [style, { allowArrowFunctions, allowTypeAnnotation, overrides }] =
+			context.options;
 		const enforceDeclarations = style === "declaration";
 		const { namedExports: exportFunctionStyle } = overrides;
 		const stack = [];
 
+		/**
+		 * Checks if a function declaration is part of an overloaded function
+		 * @param {ASTNode} node The function declaration node to check
+		 * @returns {boolean} True if the function is overloaded
+		 */
+		function isOverloadedFunction(node) {
+			const functionName = node.id.name;
+
+			if (node.parent.type === "ExportNamedDeclaration") {
+				return node.parent.parent.body.some(
+					member =>
+						member.type === "ExportNamedDeclaration" &&
+						member.declaration?.type === "TSDeclareFunction" &&
+						member.declaration.id.name === functionName,
+				);
+			}
+
+			if (node.parent.type === "SwitchCase") {
+				return node.parent.parent.cases.some(switchCase =>
+					switchCase.consequent.some(
+						member =>
+							member.type === "TSDeclareFunction" &&
+							member.id.name === functionName,
+					),
+				);
+			}
+
+			return (
+				Array.isArray(node.parent.body) &&
+				node.parent.body.some(
+					member =>
+						member.type === "TSDeclareFunction" &&
+						member.id.name === functionName,
+				)
+			);
+		}
+
 		const nodesToCheck = {
 			FunctionDeclaration(node) {
 				stack.push(false);
@@ -73,14 +117,16 @@ module.exports = {
 					!enforceDeclarations &&
 					node.parent.type !== "ExportDefaultDeclaration" &&
 					(typeof exportFunctionStyle === "undefined" ||
-						node.parent.type !== "ExportNamedDeclaration")
+						node.parent.type !== "ExportNamedDeclaration") &&
+					!isOverloadedFunction(node)
 				) {
 					context.report({ node, messageId: "expression" });
 				}
 
 				if (
 					node.parent.type === "ExportNamedDeclaration" &&
-					exportFunctionStyle === "expression"
+					exportFunctionStyle === "expression" &&
+					!isOverloadedFunction(node)
 				) {
 					context.report({ node, messageId: "expression" });
 				}
@@ -97,7 +143,8 @@ module.exports = {
 					node.parent.type === "VariableDeclarator" &&
 					(typeof exportFunctionStyle === "undefined" ||
 						node.parent.parent.parent.type !==
-							"ExportNamedDeclaration")
+							"ExportNamedDeclaration") &&
+					!(allowTypeAnnotation && node.parent.id.typeAnnotation)
 				) {
 					context.report({
 						node: node.parent,
@@ -109,7 +156,8 @@ module.exports = {
 					node.parent.type === "VariableDeclarator" &&
 					node.parent.parent.parent.type ===
 						"ExportNamedDeclaration" &&
-					exportFunctionStyle === "declaration"
+					exportFunctionStyle === "declaration" &&
+					!(allowTypeAnnotation && node.parent.id.typeAnnotation)
 				) {
 					context.report({
 						node: node.parent,
@@ -144,7 +192,8 @@ module.exports = {
 						enforceDeclarations &&
 						(typeof exportFunctionStyle === "undefined" ||
 							node.parent.parent.parent.type !==
-								"ExportNamedDeclaration")
+								"ExportNamedDeclaration") &&
+						!(allowTypeAnnotation && node.parent.id.typeAnnotation)
 					) {
 						context.report({
 							node: node.parent,
@@ -155,7 +204,8 @@ module.exports = {
 					if (
 						node.parent.parent.parent.type ===
 							"ExportNamedDeclaration" &&
-						exportFunctionStyle === "declaration"
+						exportFunctionStyle === "declaration" &&
+						!(allowTypeAnnotation && node.parent.id.typeAnnotation)
 					) {
 						context.report({
 							node: node.parent,

package/lib/rules/no-implicit-globals.js

@@ -5,6 +5,12 @@
 
 "use strict";
 
+const ASSIGNMENT_NODES = new Set([
+	"AssignmentExpression",
+	"ForInStatement",
+	"ForOfStatement",
+]);
+
 //------------------------------------------------------------------------------
 // Rule Definition
 //------------------------------------------------------------------------------
@@ -142,27 +148,37 @@ module.exports = {
 							}
 						}
 					});
-				});
 
-				// Undeclared assigned variables.
-				scope.implicit.variables.forEach(variable => {
-					const scopeVariable = scope.set.get(variable.name);
-					let messageId;
+					if (
+						isReadonlyEslintGlobalVariable &&
+						variable.defs.length === 0
+					) {
+						variable.references.forEach(reference => {
+							if (reference.isWrite() && !reference.isRead()) {
+								let assignmentParent =
+									reference.identifier.parent;
+
+								while (
+									assignmentParent &&
+									!ASSIGNMENT_NODES.has(assignmentParent.type)
+								) {
+									assignmentParent = assignmentParent.parent;
+								}
 
-					if (scopeVariable) {
-						// ESLint global variable
-						if (scopeVariable.writeable) {
-							return;
-						}
-						messageId = "assignmentToReadonlyGlobal";
-					} else {
-						// Reference to an unknown variable, possible global leak.
-						messageId = "globalVariableLeak";
+								report(
+									assignmentParent ?? reference.identifier,
+									"assignmentToReadonlyGlobal",
+								);
+							}
+						});
 					}
+				});
 
+				// Undeclared assigned variables.
+				scope.implicit.variables.forEach(variable => {
 					// def.node is an AssignmentExpression, ForInStatement or ForOfStatement.
 					variable.defs.forEach(def => {
-						report(def.node, messageId);
+						report(def.node, "globalVariableLeak");
 					});
 				});
 			},

package/lib/rules/no-magic-numbers.js

@@ -26,10 +26,73 @@ function normalizeIgnoreValue(x) {
 	return x;
 }
 
+/**
+ * Checks if the node parent is a TypeScript enum member
+ * @param {ASTNode} node The node to be validated
+ * @returns {boolean} True if the node parent is a TypeScript enum member
+ */
+function isParentTSEnumDeclaration(node) {
+	return node.parent.type === "TSEnumMember";
+}
+
+/**
+ * Checks if the node is a valid TypeScript numeric literal type.
+ * @param {ASTNode} node The node to be validated
+ * @returns {boolean} True if the node is a TypeScript numeric literal type
+ */
+function isTSNumericLiteralType(node) {
+	let ancestor = node.parent;
+
+	// Go up while we're part of a type union
+	while (ancestor.parent.type === "TSUnionType") {
+		ancestor = ancestor.parent;
+	}
+
+	// Check if the final ancestor is in a type alias declaration
+	return ancestor.parent.type === "TSTypeAliasDeclaration";
+}
+
+/**
+ * Checks if the node parent is a readonly class property
+ * @param {ASTNode} node The node to be validated
+ * @returns {boolean} True if the node parent is a readonly class property
+ */
+function isParentTSReadonlyPropertyDefinition(node) {
+	if (node.parent?.type === "PropertyDefinition" && node.parent.readonly) {
+		return true;
+	}
+
+	return false;
+}
+
+/**
+ * Checks if the node is part of a type indexed access (eg. Foo[4])
+ * @param {ASTNode} node The node to be validated
+ * @returns {boolean} True if the node is part of an indexed access
+ */
+function isAncestorTSIndexedAccessType(node) {
+	let ancestor = node.parent;
+
+	/*
+	 * Go up another level while we're part of a type union (eg. 1 | 2) or
+	 * intersection (eg. 1 & 2)
+	 */
+	while (
+		ancestor.parent.type === "TSUnionType" ||
+		ancestor.parent.type === "TSIntersectionType"
+	) {
+		ancestor = ancestor.parent;
+	}
+
+	return ancestor.parent.type === "TSIndexedAccessType";
+}
+
 /** @type {import('../types').Rule.RuleModule} */
 module.exports = {
 	meta: {
 		type: "suggestion",
+		dialects: ["typescript", "javascript"],
+		language: "javascript",
 
 		docs: {
 			description: "Disallow magic numbers",
@@ -75,6 +138,22 @@ module.exports = {
 						type: "boolean",
 						default: false,
 					},
+					ignoreEnums: {
+						type: "boolean",
+						default: false,
+					},
+					ignoreNumericLiteralTypes: {
+						type: "boolean",
+						default: false,
+					},
+					ignoreReadonlyClassProperties: {
+						type: "boolean",
+						default: false,
+					},
+					ignoreTypeIndexes: {
+						type: "boolean",
+						default: false,
+					},
 				},
 				additionalProperties: false,
 			},
@@ -94,7 +173,12 @@ module.exports = {
 			ignoreArrayIndexes = !!config.ignoreArrayIndexes,
 			ignoreDefaultValues = !!config.ignoreDefaultValues,
 			ignoreClassFieldInitialValues =
-				!!config.ignoreClassFieldInitialValues;
+				!!config.ignoreClassFieldInitialValues,
+			ignoreEnums = !!config.ignoreEnums,
+			ignoreNumericLiteralTypes = !!config.ignoreNumericLiteralTypes,
+			ignoreReadonlyClassProperties =
+				!!config.ignoreReadonlyClassProperties,
+			ignoreTypeIndexes = !!config.ignoreTypeIndexes;
 
 		const okTypes = detectObjects
 			? []
@@ -217,14 +301,15 @@ module.exports = {
 				let value;
 				let raw;
 
-				// Treat unary minus as a part of the number
+				// Treat unary minus/plus as a part of the number
 				if (
 					node.parent.type === "UnaryExpression" &&
-					node.parent.operator === "-"
+					["-", "+"].includes(node.parent.operator)
 				) {
 					fullNumberNode = node.parent;
-					value = -node.value;
-					raw = `-${node.raw}`;
+					value =
+						node.parent.operator === "-" ? -node.value : node.value;
+					raw = `${node.parent.operator}${node.raw}`;
 				} else {
 					fullNumberNode = node;
 					value = node.value;
@@ -239,6 +324,14 @@ module.exports = {
 					(ignoreDefaultValues && isDefaultValue(fullNumberNode)) ||
 					(ignoreClassFieldInitialValues &&
 						isClassFieldInitialValue(fullNumberNode)) ||
+					(ignoreEnums &&
+						isParentTSEnumDeclaration(fullNumberNode)) ||
+					(ignoreNumericLiteralTypes &&
+						isTSNumericLiteralType(fullNumberNode)) ||
+					(ignoreTypeIndexes &&
+						isAncestorTSIndexedAccessType(fullNumberNode)) ||
+					(ignoreReadonlyClassProperties &&
+						isParentTSReadonlyPropertyDefinition(fullNumberNode)) ||
 					isParseIntRadix(fullNumberNode) ||
 					isJSXNumber(fullNumberNode) ||
 					(ignoreArrayIndexes && isArrayIndex(fullNumberNode, value))