eslint 9.25.1 → 9.26.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/mcp/mcp-server.js

@@ -0,0 +1,66 @@
+/**
+ * @fileoverview MCP Server for handling requests and responses to ESLint.
+ * @author Nicholas C. Zakas
+ */
+
+"use strict";
+
+//-----------------------------------------------------------------------------
+// Requirements
+//-----------------------------------------------------------------------------
+
+const { McpServer } = require("@modelcontextprotocol/sdk/server/mcp.js");
+const { z } = require("zod");
+const { ESLint } = require("../eslint");
+const pkg = require("../../package.json");
+
+//-----------------------------------------------------------------------------
+// Server
+//-----------------------------------------------------------------------------
+
+const mcpServer = new McpServer({
+	name: "ESLint",
+	version: pkg.version,
+});
+
+// Important: Cursor throws an error when `describe()` is used in the schema.
+const filePathsSchema = {
+	filePaths: z.array(z.string().min(1)).nonempty(),
+};
+
+//-----------------------------------------------------------------------------
+// Tools
+//-----------------------------------------------------------------------------
+
+mcpServer.tool(
+	"lint-files",
+	"Lint files using ESLint. You must provide a list of absolute file paths to the files you want to lint. The absolute file paths should be in the correct format for your operating system (e.g., forward slashes on Unix-like systems, backslashes on Windows).",
+	filePathsSchema,
+	async ({ filePaths }) => {
+		const eslint = new ESLint({
+			// enable lookup from file rather than from cwd
+			flags: ["unstable_config_lookup_from_file"],
+		});
+
+		const results = await eslint.lintFiles(filePaths);
+		const content = results.map(result => ({
+			type: "text",
+			text: JSON.stringify(result),
+		}));
+
+		content.unshift({
+			type: "text",
+			text: "Here are the results of running ESLint on the provided files:",
+		});
+		content.push({
+			type: "text",
+			text: "Do not automatically fix these issues. You must ask the user for confirmation before attempting to fix the issues found.",
+		});
+
+		return {
+			content,
+		};
+	},
+);
+
+module.exports = { mcpServer };

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

@@ -39,9 +39,9 @@ const { SourceCode } = require("../languages/js/source-code");
 // Typedefs
 //------------------------------------------------------------------------------
 
+/** @import { LanguageOptions, RuleDefinition } from "@eslint/core" */
+
 /** @typedef {import("../shared/types").Parser} Parser */
-/** @typedef {import("../shared/types").LanguageOptions} LanguageOptions */
-/** @typedef {import("../types").Rule.RuleModule} Rule */
 
 /**
  * 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[]

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"),