eslint 9.25.1 → 9.27.0

package/lib/linter/node-event-generator.js

@@ -9,248 +9,28 @@
 // Requirements
 //------------------------------------------------------------------------------
 
-const esquery = require("esquery");
+const { parse, matches } = require("./esquery");
 
-//------------------------------------------------------------------------------
+//-----------------------------------------------------------------------------
 // Typedefs
-//------------------------------------------------------------------------------
+//-----------------------------------------------------------------------------
 
 /**
- * An object describing an AST selector
- * @typedef {Object} ASTSelector
- * @property {string} rawSelector The string that was parsed into this selector
- * @property {boolean} isExit `true` if this should be emitted when exiting the node rather than when entering
- * @property {Object} parsedSelector An object (from esquery) describing the matching behavior of the selector
- * @property {string[]|null} listenerTypes A list of node types that could possibly cause the selector to match,
- * or `null` if all node types could cause a match
- * @property {number} attributeCount The total number of classes, pseudo-classes, and attribute queries in this selector
- * @property {number} identifierCount The total number of identifier queries in this selector
+ * @import { ESQueryParsedSelector } from "./esquery.js";
  */
 
-//------------------------------------------------------------------------------
+//-----------------------------------------------------------------------------
 // Helpers
-//------------------------------------------------------------------------------
-
-/**
- * Computes the union of one or more arrays
- * @param {...any[]} arrays One or more arrays to union
- * @returns {any[]} The union of the input arrays
- */
-function union(...arrays) {
-	return [...new Set(arrays.flat())];
-}
-
-/**
- * Computes the intersection of one or more arrays
- * @param {...any[]} arrays One or more arrays to intersect
- * @returns {any[]} The intersection of the input arrays
- */
-function intersection(...arrays) {
-	if (arrays.length === 0) {
-		return [];
-	}
-
-	let result = [...new Set(arrays[0])];
-
-	for (const array of arrays.slice(1)) {
-		result = result.filter(x => array.includes(x));
-	}
-	return result;
-}
-
-/**
- * Gets the possible types of a selector
- * @param {Object} parsedSelector An object (from esquery) describing the matching behavior of the selector
- * @returns {string[]|null} The node types that could possibly trigger this selector, or `null` if all node types could trigger it
- */
-function getPossibleTypes(parsedSelector) {
-	switch (parsedSelector.type) {
-		case "identifier":
-			return [parsedSelector.value];
-
-		case "matches": {
-			const typesForComponents =
-				parsedSelector.selectors.map(getPossibleTypes);
-
-			if (typesForComponents.every(Boolean)) {
-				return union(...typesForComponents);
-			}
-			return null;
-		}
-
-		case "compound": {
-			const typesForComponents = parsedSelector.selectors
-				.map(getPossibleTypes)
-				.filter(typesForComponent => typesForComponent);
-
-			// If all of the components could match any type, then the compound could also match any type.
-			if (!typesForComponents.length) {
-				return null;
-			}
-
-			/*
-			 * If at least one of the components could only match a particular type, the compound could only match
-			 * the intersection of those types.
-			 */
-			return intersection(...typesForComponents);
-		}
-
-		case "child":
-		case "descendant":
-		case "sibling":
-		case "adjacent":
-			return getPossibleTypes(parsedSelector.right);
-
-		case "class":
-			if (parsedSelector.name === "function") {
-				return [
-					"FunctionDeclaration",
-					"FunctionExpression",
-					"ArrowFunctionExpression",
-				];
-			}
-
-			return null;
-
-		default:
-			return null;
-	}
-}
-
-/**
- * Counts the number of class, pseudo-class, and attribute queries in this selector
- * @param {Object} parsedSelector An object (from esquery) describing the selector's matching behavior
- * @returns {number} The number of class, pseudo-class, and attribute queries in this selector
- */
-function countClassAttributes(parsedSelector) {
-	switch (parsedSelector.type) {
-		case "child":
-		case "descendant":
-		case "sibling":
-		case "adjacent":
-			return (
-				countClassAttributes(parsedSelector.left) +
-				countClassAttributes(parsedSelector.right)
-			);
-
-		case "compound":
-		case "not":
-		case "matches":
-			return parsedSelector.selectors.reduce(
-				(sum, childSelector) =>
-					sum + countClassAttributes(childSelector),
-				0,
-			);
-
-		case "attribute":
-		case "field":
-		case "nth-child":
-		case "nth-last-child":
-			return 1;
-
-		default:
-			return 0;
-	}
-}
-
-/**
- * Counts the number of identifier queries in this selector
- * @param {Object} parsedSelector An object (from esquery) describing the selector's matching behavior
- * @returns {number} The number of identifier queries
- */
-function countIdentifiers(parsedSelector) {
-	switch (parsedSelector.type) {
-		case "child":
-		case "descendant":
-		case "sibling":
-		case "adjacent":
-			return (
-				countIdentifiers(parsedSelector.left) +
-				countIdentifiers(parsedSelector.right)
-			);
-
-		case "compound":
-		case "not":
-		case "matches":
-			return parsedSelector.selectors.reduce(
-				(sum, childSelector) => sum + countIdentifiers(childSelector),
-				0,
-			);
-
-		case "identifier":
-			return 1;
-
-		default:
-			return 0;
-	}
-}
+//-----------------------------------------------------------------------------
 
 /**
- * Compares the specificity of two selector objects, with CSS-like rules.
- * @param {ASTSelector} selectorA An AST selector descriptor
- * @param {ASTSelector} selectorB Another AST selector descriptor
- * @returns {number}
- * a value less than 0 if selectorA is less specific than selectorB
- * a value greater than 0 if selectorA is more specific than selectorB
- * a value less than 0 if selectorA and selectorB have the same specificity, and selectorA <= selectorB alphabetically
- * a value greater than 0 if selectorA and selectorB have the same specificity, and selectorA > selectorB alphabetically
+ * Compares two ESQuery selectors by specificity.
+ * @param {ESQueryParsedSelector} a The first selector to compare.
+ * @param {ESQueryParsedSelector} b The second selector to compare.
+ * @returns {number} A negative number if `a` is less specific than `b` or they are equally specific and `a` <= `b` alphabetically, a positive number if `a` is more specific than `b`.
  */
-function compareSpecificity(selectorA, selectorB) {
-	return (
-		selectorA.attributeCount - selectorB.attributeCount ||
-		selectorA.identifierCount - selectorB.identifierCount ||
-		(selectorA.rawSelector <= selectorB.rawSelector ? -1 : 1)
-	);
-}
-
-/**
- * Parses a raw selector string, and throws a useful error if parsing fails.
- * @param {string} rawSelector A raw AST selector
- * @returns {Object} An object (from esquery) describing the matching behavior of this selector
- * @throws {Error} An error if the selector is invalid
- */
-function tryParseSelector(rawSelector) {
-	try {
-		return esquery.parse(rawSelector.replace(/:exit$/u, ""));
-	} catch (err) {
-		if (
-			err.location &&
-			err.location.start &&
-			typeof err.location.start.offset === "number"
-		) {
-			throw new SyntaxError(
-				`Syntax error in selector "${rawSelector}" at position ${err.location.start.offset}: ${err.message}`,
-			);
-		}
-		throw err;
-	}
-}
-
-const selectorCache = new Map();
-
-/**
- * Parses a raw selector string, and returns the parsed selector along with specificity and type information.
- * @param {string} rawSelector A raw AST selector
- * @returns {ASTSelector} A selector descriptor
- */
-function parseSelector(rawSelector) {
-	if (selectorCache.has(rawSelector)) {
-		return selectorCache.get(rawSelector);
-	}
-
-	const parsedSelector = tryParseSelector(rawSelector);
-
-	const result = {
-		rawSelector,
-		isExit: rawSelector.endsWith(":exit"),
-		parsedSelector,
-		listenerTypes: getPossibleTypes(parsedSelector),
-		attributeCount: countClassAttributes(parsedSelector),
-		identifierCount: countIdentifiers(parsedSelector),
-	};
-
-	selectorCache.set(rawSelector, result);
-	return result;
+function compareSpecificity(a, b) {
+	return a.compare(b);
 }
 
 //------------------------------------------------------------------------------
@@ -270,6 +50,52 @@ function parseSelector(rawSelector) {
  * ```
  */
 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 = [];
+
 	/**
 	 * @param {SafeEmitter} emitter
 	 * An SafeEmitter which is the destination of events. This emitter must already
@@ -281,21 +107,20 @@ class NodeEventGenerator {
 	constructor(emitter, esqueryOptions) {
 		this.emitter = emitter;
 		this.esqueryOptions = esqueryOptions;
-		this.currentAncestry = [];
-		this.enterSelectorsByNodeType = new Map();
-		this.exitSelectorsByNodeType = new Map();
-		this.anyTypeEnterSelectors = [];
-		this.anyTypeExitSelectors = [];
 
 		emitter.eventNames().forEach(rawSelector => {
-			const selector = parseSelector(rawSelector);
+			const selector = parse(rawSelector);
 
-			if (selector.listenerTypes) {
+			/*
+			 * If this selector has identified specific node types,
+			 * add it to the map for these node types for faster lookup.
+			 */
+			if (selector.nodeTypes) {
 				const typeMap = selector.isExit
 					? this.exitSelectorsByNodeType
 					: this.enterSelectorsByNodeType;
 
-				selector.listenerTypes.forEach(nodeType => {
+				selector.nodeTypes.forEach(nodeType => {
 					if (!typeMap.has(nodeType)) {
 						typeMap.set(nodeType, []);
 					}
@@ -303,6 +128,13 @@ class NodeEventGenerator {
 				});
 				return;
 			}
+
+			/*
+			 * Remaining selectors are added to the "any type" selectors
+			 * list for the appropriate phase of traversal. This ensures
+			 * that all selectors will still be applied even if no
+			 * specific node type is matched.
+			 */
 			const selectors = selector.isExit
 				? this.anyTypeExitSelectors
 				: this.anyTypeEnterSelectors;
@@ -310,6 +142,7 @@ class NodeEventGenerator {
 			selectors.push(selector);
 		});
 
+		// sort all selectors by specificity for prioritizing call order
 		this.anyTypeEnterSelectors.sort(compareSpecificity);
 		this.anyTypeExitSelectors.sort(compareSpecificity);
 		this.enterSelectorsByNodeType.forEach(selectorList =>
@@ -323,19 +156,19 @@ class NodeEventGenerator {
 	/**
 	 * Checks a selector against a node, and emits it if it matches
 	 * @param {ASTNode} node The node to check
-	 * @param {ASTSelector} selector An AST selector descriptor
+	 * @param {ESQueryParsedSelector} selector An AST selector descriptor
 	 * @returns {void}
 	 */
 	applySelector(node, selector) {
 		if (
-			esquery.matches(
+			matches(
 				node,
-				selector.parsedSelector,
+				selector.root,
 				this.currentAncestry,
 				this.esqueryOptions,
 			)
 		) {
-			this.emitter.emit(selector.rawSelector, node);
+			this.emitter.emit(selector.source, node);
 		}
 	}
 
@@ -348,6 +181,11 @@ class NodeEventGenerator {
 	applySelectors(node, isExit) {
 		const nodeTypeKey = this.esqueryOptions?.nodeTypeKey || "type";
 
+		/*
+		 * Get the selectors that may match this node. First, check
+		 * to see if the node type has specific selectors,
+		 * then gather the "any type" selectors.
+		 */
 		const selectorsByNodeType =
 			(isExit
 				? this.exitSelectorsByNodeType
@@ -361,19 +199,23 @@ class NodeEventGenerator {
 		 * selectorsByNodeType and anyTypeSelectors were already sorted by specificity in the constructor.
 		 * Iterate through each of them, applying selectors in the right order.
 		 */
-		let selectorsByTypeIndex = 0;
+		let selectorsByNodeTypeIndex = 0;
 		let anyTypeSelectorsIndex = 0;
 
 		while (
-			selectorsByTypeIndex < selectorsByNodeType.length ||
+			selectorsByNodeTypeIndex < selectorsByNodeType.length ||
 			anyTypeSelectorsIndex < anyTypeSelectors.length
 		) {
+			/*
+			 * If we've already exhausted the selectors for this node type,
+			 * or if the next any type selector is more specific than the
+			 * next selector for this node type, apply the any type selector.
+			 */
 			if (
-				selectorsByTypeIndex >= selectorsByNodeType.length ||
+				selectorsByNodeTypeIndex >= selectorsByNodeType.length ||
 				(anyTypeSelectorsIndex < anyTypeSelectors.length &&
-					compareSpecificity(
-						anyTypeSelectors[anyTypeSelectorsIndex],
-						selectorsByNodeType[selectorsByTypeIndex],
+					anyTypeSelectors[anyTypeSelectorsIndex].compare(
+						selectorsByNodeType[selectorsByNodeTypeIndex],
 					) < 0)
 			) {
 				this.applySelector(
@@ -381,9 +223,10 @@ class NodeEventGenerator {
 					anyTypeSelectors[anyTypeSelectorsIndex++],
 				);
 			} else {
+				// otherwise apply the node type selector
 				this.applySelector(
 					node,
-					selectorsByNodeType[selectorsByTypeIndex++],
+					selectorsByNodeType[selectorsByNodeTypeIndex++],
 				);
 			}
 		}

package/lib/linter/report-translator.js

@@ -17,7 +17,8 @@ const { interpolate } = require("./interpolate");
 // Typedefs
 //------------------------------------------------------------------------------
 
-/** @typedef {import("../shared/types").LintMessage} LintMessage */
+/** @typedef {import("../types").Linter.LintMessage} LintMessage */
+/** @typedef {import("../types").Linter.LintSuggestion} SuggestionResult */
 
 /**
  * An error message description

package/lib/options.js

@@ -213,6 +213,16 @@ module.exports = function (usingFlatConfig) {
 		};
 	}
 
+	let mcpFlag;
+
+	if (usingFlatConfig) {
+		mcpFlag = {
+			option: "mcp",
+			type: "Boolean",
+			description: "Start the ESLint MCP server",
+		};
+	}
+
 	return optionator({
 		prepend: "eslint [options] file.js [file.js] [dir]",
 		defaults: {
@@ -499,6 +509,7 @@ module.exports = function (usingFlatConfig) {
 			},
 			statsFlag,
 			flagFlag,
+			mcpFlag,
 		].filter(value => !!value),
 	});
 };

package/lib/rule-tester/rule-tester.js

@@ -15,7 +15,7 @@ const assert = require("node:assert"),
 	path = require("node:path"),
 	equal = require("fast-deep-equal"),
 	Traverser = require("../shared/traverser"),
-	{ getRuleOptionsSchema } = require("../config/flat-config-helpers"),
+	{ Config } = require("../config/config"),
 	{ Linter, SourceCodeFixer } = require("../linter"),
 	{ interpolate, getPlaceholderMatcher } = require("../linter/interpolate"),
 	stringify = require("json-stable-stringify-without-jsonify");
@@ -39,9 +39,9 @@ const { SourceCode } = require("../languages/js/source-code");
 // Typedefs
 //------------------------------------------------------------------------------
 
-/** @typedef {import("../shared/types").Parser} Parser */
-/** @typedef {import("../shared/types").LanguageOptions} LanguageOptions */
-/** @typedef {import("../types").Rule.RuleModule} Rule */
+/** @import { LanguageOptions, RuleDefinition } from "@eslint/core" */
+
+/** @typedef {import("../types").Linter.Parser} Parser */
 
 /**
  * A test case that is expected to pass lint.
@@ -192,16 +192,24 @@ function cloneDeeplyExcludesParent(x) {
 /**
  * Freezes a given value deeply.
  * @param {any} x A value to freeze.
+ * @param {Set<Object>} seenObjects Objects already seen during the traversal.
  * @returns {void}
  */
-function freezeDeeply(x) {
+function freezeDeeply(x, seenObjects = new Set()) {
 	if (typeof x === "object" && x !== null) {
+		if (seenObjects.has(x)) {
+			return; // skip to avoid infinite recursion
+		}
+		seenObjects.add(x);
+
 		if (Array.isArray(x)) {
-			x.forEach(freezeDeeply);
+			x.forEach(element => {
+				freezeDeeply(element, seenObjects);
+			});
 		} else {
 			for (const key in x) {
 				if (key !== "parent" && hasOwnProperty(x, key)) {
-					freezeDeeply(x[key]);
+					freezeDeeply(x[key], seenObjects);
 				}
 			}
 		}
@@ -545,7 +553,7 @@ class RuleTester {
 	/**
 	 * Adds a new rule test to execute.
 	 * @param {string} ruleName The name of the rule to run.
-	 * @param {Rule} rule The rule to test.
+	 * @param {RuleDefinition} rule The rule to test.
 	 * @param {{
 	 *   valid: (ValidTestCase | string)[],
 	 *   invalid: InvalidTestCase[]
@@ -759,7 +767,7 @@ class RuleTester {
 			let schema;
 
 			try {
-				schema = getRuleOptionsSchema(rule);
+				schema = Config.getRuleOptionsSchema(rule);
 			} catch (err) {
 				err.message += metaSchemaDescription;
 				throw err;

package/lib/rules/eqeqeq.js

@@ -19,6 +19,7 @@ const astUtils = require("./utils/ast-utils");
 module.exports = {
 	meta: {
 		type: "suggestion",
+		hasSuggestions: true,
 
 		docs: {
 			description: "Require the use of `===` and `!==`",
@@ -63,6 +64,8 @@ module.exports = {
 		messages: {
 			unexpected:
 				"Expected '{{expectedOperator}}' and instead saw '{{actualOperator}}'.",
+			replaceOperator:
+				"Use '{{expectedOperator}}' instead of '{{actualOperator}}'.",
 		},
 	},
 
@@ -138,22 +141,42 @@ module.exports = {
 				token => token.value === node.operator,
 			);
 
-			context.report({
+			const commonReportParams = {
 				node,
 				loc: operatorToken.loc,
 				messageId: "unexpected",
 				data: { expectedOperator, actualOperator: node.operator },
-				fix(fixer) {
-					// If the comparison is a `typeof` comparison or both sides are literals with the same type, then it's safe to fix.
-					if (isTypeOfBinary(node) || areLiteralsAndSameType(node)) {
+			};
+
+			if (isTypeOfBinary(node) || areLiteralsAndSameType(node)) {
+				context.report({
+					...commonReportParams,
+					fix(fixer) {
 						return fixer.replaceText(
 							operatorToken,
 							expectedOperator,
 						);
-					}
-					return null;
-				},
-			});
+					},
+				});
+			} else {
+				context.report({
+					...commonReportParams,
+					suggest: [
+						{
+							messageId: "replaceOperator",
+							data: {
+								expectedOperator,
+								actualOperator: node.operator,
+							},
+							fix: fixer =>
+								fixer.replaceText(
+									operatorToken,
+									expectedOperator,
+								),
+						},
+					],
+				});
+			}
 		}
 
 		return {

package/lib/rules/index.js

@@ -10,7 +10,7 @@
 
 const { LazyLoadingRuleMap } = require("./utils/lazy-loading-rule-map");
 
-/** @type {Map<string, import("../shared/types").Rule>} */
+/** @type {Map<string, import("../types").Rule.RuleModule>} */
 module.exports = new LazyLoadingRuleMap(
 	Object.entries({
 		"accessor-pairs": () => require("./accessor-pairs"),
@@ -225,6 +225,7 @@ module.exports = new LazyLoadingRuleMap(
 		"no-this-before-super": () => require("./no-this-before-super"),
 		"no-throw-literal": () => require("./no-throw-literal"),
 		"no-trailing-spaces": () => require("./no-trailing-spaces"),
+		"no-unassigned-vars": () => require("./no-unassigned-vars"),
 		"no-undef": () => require("./no-undef"),
 		"no-undef-init": () => require("./no-undef-init"),
 		"no-undefined": () => require("./no-undefined"),