eslint 9.25.0 → 9.26.0

package/README.md

@@ -20,9 +20,9 @@
 
 ESLint is a tool for identifying and reporting on patterns found in ECMAScript/JavaScript code. In many ways, it is similar to JSLint and JSHint with a few exceptions:
 
--   ESLint uses [Espree](https://github.com/eslint/js/tree/main/packages/espree) for JavaScript parsing.
--   ESLint uses an AST to evaluate patterns in code.
--   ESLint is completely pluggable, every single rule is a plugin and you can add more at runtime.
+- ESLint uses [Espree](https://github.com/eslint/js/tree/main/packages/espree) for JavaScript parsing.
+- ESLint uses an AST to evaluate patterns in code.
+- ESLint is completely pluggable, every single rule is a plugin and you can add more at runtime.
 
 ## Table of Contents
 
@@ -87,9 +87,9 @@ export default defineConfig([
 
 The names `"prefer-const"` and `"no-constant-binary-expression"` are the names of [rules](https://eslint.org/docs/rules) in ESLint. The first value is the error level of the rule and can be one of these values:
 
--   `"off"` or `0` - turn the rule off
--   `"warn"` or `1` - turn the rule on as a warning (doesn't affect exit code)
--   `"error"` or `2` - turn the rule on as an error (exit code will be 1)
+- `"off"` or `0` - turn the rule off
+- `"warn"` or `1` - turn the rule on as a warning (doesn't affect exit code)
+- `"error"` or `2` - turn the rule on as an error (exit code will be 1)
 
 The three error levels allow you fine-grained control over how ESLint applies rules (for more configuration options and details, see the [configuration docs](https://eslint.org/docs/latest/use/configure)).
 
@@ -109,10 +109,10 @@ ESLint adheres to the [OpenJS Foundation Code of Conduct](https://eslint.org/con
 
 Before filing an issue, please be sure to read the guidelines for what you're reporting:
 
--   [Bug Report](https://eslint.org/docs/latest/contribute/report-bugs)
--   [Propose a New Rule](https://eslint.org/docs/latest/contribute/propose-new-rule)
--   [Proposing a Rule Change](https://eslint.org/docs/latest/contribute/propose-rule-change)
--   [Request a Change](https://eslint.org/docs/latest/contribute/request-change)
+- [Bug Report](https://eslint.org/docs/latest/contribute/report-bugs)
+- [Propose a New Rule](https://eslint.org/docs/latest/contribute/propose-new-rule)
+- [Proposing a Rule Change](https://eslint.org/docs/latest/contribute/propose-rule-change)
+- [Request a Change](https://eslint.org/docs/latest/contribute/request-change)
 
 ## Frequently Asked Questions
 
@@ -174,32 +174,32 @@ ESLint takes security seriously. We work hard to ensure that ESLint is safe for
 
 ESLint follows [semantic versioning](https://semver.org). However, due to the nature of ESLint as a code quality tool, it's not always clear when a minor or major version bump occurs. To help clarify this for everyone, we've defined the following semantic versioning policy for ESLint:
 
--   Patch release (intended to not break your lint build)
-    -   A bug fix in a rule that results in ESLint reporting fewer linting errors.
-    -   A bug fix to the CLI or core (including formatters).
-    -   Improvements to documentation.
-    -   Non-user-facing changes such as refactoring code, adding, deleting, or modifying tests, and increasing test coverage.
-    -   Re-releasing after a failed release (i.e., publishing a release that doesn't work for anyone).
--   Minor release (might break your lint build)
-    -   A bug fix in a rule that results in ESLint reporting more linting errors.
-    -   A new rule is created.
-    -   A new option to an existing rule that does not result in ESLint reporting more linting errors by default.
-    -   A new addition to an existing rule to support a newly-added language feature (within the last 12 months) that will result in ESLint reporting more linting errors by default.
-    -   An existing rule is deprecated.
-    -   A new CLI capability is created.
-    -   New capabilities to the public API are added (new classes, new methods, new arguments to existing methods, etc.).
-    -   A new formatter is created.
-    -   `eslint:recommended` is updated and will result in strictly fewer linting errors (e.g., rule removals).
--   Major release (likely to break your lint build)
-    -   `eslint:recommended` is updated and may result in new linting errors (e.g., rule additions, most rule option updates).
-    -   A new option to an existing rule that results in ESLint reporting more linting errors by default.
-    -   An existing formatter is removed.
-    -   Part of the public API is removed or changed in an incompatible way. The public API includes:
-        -   Rule schemas
-        -   Configuration schema
-        -   Command-line options
-        -   Node.js API
-        -   Rule, formatter, parser, plugin APIs
+- Patch release (intended to not break your lint build)
+    - A bug fix in a rule that results in ESLint reporting fewer linting errors.
+    - A bug fix to the CLI or core (including formatters).
+    - Improvements to documentation.
+    - Non-user-facing changes such as refactoring code, adding, deleting, or modifying tests, and increasing test coverage.
+    - Re-releasing after a failed release (i.e., publishing a release that doesn't work for anyone).
+- Minor release (might break your lint build)
+    - A bug fix in a rule that results in ESLint reporting more linting errors.
+    - A new rule is created.
+    - A new option to an existing rule that does not result in ESLint reporting more linting errors by default.
+    - A new addition to an existing rule to support a newly-added language feature (within the last 12 months) that will result in ESLint reporting more linting errors by default.
+    - An existing rule is deprecated.
+    - A new CLI capability is created.
+    - New capabilities to the public API are added (new classes, new methods, new arguments to existing methods, etc.).
+    - A new formatter is created.
+    - `eslint:recommended` is updated and will result in strictly fewer linting errors (e.g., rule removals).
+- Major release (likely to break your lint build)
+    - `eslint:recommended` is updated and may result in new linting errors (e.g., rule additions, most rule option updates).
+    - A new option to an existing rule that results in ESLint reporting more linting errors by default.
+    - An existing formatter is removed.
+    - Part of the public API is removed or changed in an incompatible way. The public API includes:
+        - Rule schemas
+        - Configuration schema
+        - Command-line options
+        - Node.js API
+        - Rule, formatter, parser, plugin APIs
 
 According to our policy, any minor update may report more linting errors than the previous release (ex: from a bug fix). As such, we recommend using the tilde (`~`) in `package.json` e.g. `"eslint": "~3.1.0"` to guarantee the results of your builds.
 
@@ -299,8 +299,8 @@ Amaresh  S M
 </a>
 </td><td align="center" valign="top" width="11%">
 <a href="https://github.com/harish-sethuraman">
-<img src="https://github.com/harish-sethuraman.png?s=75" width="75" height="75" alt="Strek's Avatar"><br />
-Strek
+<img src="https://github.com/harish-sethuraman.png?s=75" width="75" height="75" alt="Harish's Avatar"><br />
+Harish
 </a>
 </td><td align="center" valign="top" width="11%">
 <a href="https://github.com/kecrily">
@@ -324,7 +324,7 @@ to get your logo on our READMEs and [website](https://eslint.org/sponsors).
 <p><a href="https://automattic.com"><img src="https://images.opencollective.com/automattic/d0ef3e1/logo.png" alt="Automattic" height="128"></a> <a href="https://www.airbnb.com/"><img src="https://images.opencollective.com/airbnb/d327d66/logo.png" alt="Airbnb" height="128"></a></p><h3>Gold Sponsors</h3>
 <p><a href="https://qlty.sh/"><img src="https://images.opencollective.com/qltysh/33d157d/logo.png" alt="Qlty Software" height="96"></a> <a href="https://trunk.io/"><img src="https://images.opencollective.com/trunkio/fb92d60/avatar.png" alt="trunk.io" height="96"></a> <a href="https://shopify.engineering/"><img src="https://avatars.githubusercontent.com/u/8085" alt="Shopify" height="96"></a></p><h3>Silver Sponsors</h3>
 <p><a href="https://vite.dev/"><img src="https://images.opencollective.com/vite/e6d15e1/logo.png" alt="Vite" height="64"></a> <a href="https://liftoff.io/"><img src="https://images.opencollective.com/liftoff/5c4fa84/logo.png" alt="Liftoff" height="64"></a> <a href="https://americanexpress.io"><img src="https://avatars.githubusercontent.com/u/3853301" alt="American Express" height="64"></a> <a href="https://stackblitz.com"><img src="https://avatars.githubusercontent.com/u/28635252" alt="StackBlitz" height="64"></a></p><h3>Bronze Sponsors</h3>
-<p><a href="https://cybozu.co.jp/"><img src="https://images.opencollective.com/cybozu/933e46d/logo.png" alt="Cybozu" height="32"></a> <a href="https://www.crosswordsolver.org/anagram-solver/"><img src="https://images.opencollective.com/anagram-solver/2666271/logo.png" alt="Anagram Solver" height="32"></a> <a href="https://icons8.com/"><img src="https://images.opencollective.com/icons8/7fa1641/logo.png" alt="Icons8" height="32"></a> <a href="https://discord.com"><img src="https://images.opencollective.com/discordapp/f9645d9/logo.png" alt="Discord" height="32"></a> <a href="https://www.gitbook.com"><img src="https://avatars.githubusercontent.com/u/7111340" alt="GitBook" height="32"></a> <a href="https://nolebase.ayaka.io"><img src="https://avatars.githubusercontent.com/u/11081491" alt="Neko" height="32"></a> <a href="https://nx.dev"><img src="https://avatars.githubusercontent.com/u/23692104" alt="Nx" height="32"></a> <a href="https://opensource.mercedes-benz.com/"><img src="https://avatars.githubusercontent.com/u/34240465" alt="Mercedes-Benz Group" height="32"></a> <a href="https://herocoders.com"><img src="https://avatars.githubusercontent.com/u/37549774" alt="HeroCoders" height="32"></a> <a href="https://www.lambdatest.com"><img src="https://avatars.githubusercontent.com/u/171592363" alt="LambdaTest" height="32"></a></p>
+<p><a href="https://icons8.com/"><img src="https://images.opencollective.com/icons8/7fa1641/logo.png" alt="Icons8" height="32"></a> <a href="https://discord.com"><img src="https://images.opencollective.com/discordapp/f9645d9/logo.png" alt="Discord" height="32"></a> <a href="https://www.gitbook.com"><img src="https://avatars.githubusercontent.com/u/7111340" alt="GitBook" height="32"></a> <a href="https://nolebase.ayaka.io"><img src="https://avatars.githubusercontent.com/u/11081491" alt="Neko" height="32"></a> <a href="https://nx.dev"><img src="https://avatars.githubusercontent.com/u/23692104" alt="Nx" height="32"></a> <a href="https://opensource.mercedes-benz.com/"><img src="https://avatars.githubusercontent.com/u/34240465" alt="Mercedes-Benz Group" height="32"></a> <a href="https://herocoders.com"><img src="https://avatars.githubusercontent.com/u/37549774" alt="HeroCoders" height="32"></a> <a href="https://www.lambdatest.com"><img src="https://avatars.githubusercontent.com/u/171592363" alt="LambdaTest" height="32"></a></p>
 <h3>Technology Sponsors</h3>
 Technology sponsors allow us to use their products and services for free as part of a contribution to the open source ecosystem and our work.
 <p><a href="https://netlify.com"><img src="https://raw.githubusercontent.com/eslint/eslint.org/main/src/assets/images/techsponsors/netlify-icon.svg" alt="Netlify" height="32"></a> <a href="https://algolia.com"><img src="https://raw.githubusercontent.com/eslint/eslint.org/main/src/assets/images/techsponsors/algolia-icon.svg" alt="Algolia" height="32"></a> <a href="https://1password.com"><img src="https://raw.githubusercontent.com/eslint/eslint.org/main/src/assets/images/techsponsors/1password-icon.svg" alt="1Password" height="32"></a></p>

package/bin/eslint.js

@@ -155,6 +155,25 @@ ${getErrorMessage(error)}`;
 		return;
 	}
 
+	// start the MCP server if `--mcp` is present
+	if (process.argv.includes("--mcp")) {
+		const { mcpServer } = require("../lib/mcp/mcp-server");
+		const {
+			StdioServerTransport,
+		} = require("@modelcontextprotocol/sdk/server/stdio.js");
+
+		await mcpServer.connect(new StdioServerTransport());
+
+		// Note: do not use console.log() because stdout is part of the server transport
+		console.error(`ESLint MCP server is running. cwd: ${process.cwd()}`);
+
+		process.on("SIGINT", () => {
+			mcpServer.close();
+			process.exitCode = 0;
+		});
+		return;
+	}
+
 	// Otherwise, call the CLI.
 	const cli = require("../lib/cli");
 	const exitCode = await cli.execute(

package/lib/cli-engine/cli-engine.js

@@ -63,10 +63,10 @@ const validFixTypes = new Set(["directive", "problem", "suggestion", "layout"]);
 /** @typedef {import("../shared/types").LintMessage} LintMessage */
 /** @typedef {import("../shared/types").SuppressedLintMessage} SuppressedLintMessage */
 /** @typedef {import("../shared/types").ParserOptions} ParserOptions */
-/** @typedef {import("../shared/types").Plugin} Plugin */
 /** @typedef {import("../shared/types").RuleConf} RuleConf */
 /** @typedef {import("../types").Rule.RuleModule} Rule */
 /** @typedef {import("../types").ESLint.FormatterFunction} FormatterFunction */
+/** @typedef {import("../types").ESLint.Plugin} Plugin */
 /** @typedef {ReturnType<CascadingConfigArrayFactory.getConfigArrayForFile>} ConfigArray */
 /** @typedef {ReturnType<ConfigArray.extractConfig>} ExtractedConfig */
 

package/lib/cli.js

@@ -44,8 +44,8 @@ const debug = require("debug")("eslint:cli");
 /** @typedef {import("./eslint/eslint").LintMessage} LintMessage */
 /** @typedef {import("./eslint/eslint").LintResult} LintResult */
 /** @typedef {import("./options").ParsedCLIOptions} ParsedCLIOptions */
-/** @typedef {import("./shared/types").Plugin} Plugin */
 /** @typedef {import("./shared/types").ResultsMeta} ResultsMeta */
+/** @typedef {import("./types").ESLint.Plugin} Plugin */
 
 //------------------------------------------------------------------------------
 // Helpers

package/lib/eslint/eslint.js

@@ -57,10 +57,11 @@ const { ConfigLoader, LegacyConfigLoader } = require("../config/config-loader");
  * @import { CLIEngineLintReport } from "./legacy-eslint.js";
  * @import { FlatConfigArray } from "../config/flat-config-array.js";
  * @import { RuleDefinition } from "@eslint/core";
- * @import { ConfigData, DeprecatedRuleInfo, LintMessage, LintResult, Plugin, ResultsMeta } from "../shared/types.js";
+ * @import { ConfigData, DeprecatedRuleInfo, LintMessage, LintResult, ResultsMeta } from "../shared/types.js";
  */
 
 /** @typedef {ReturnType<ConfigArray.extractConfig>} ExtractedConfig */
+/** @typedef {import("../types").ESLint.Plugin} Plugin */
 
 /**
  * The options with which to configure the ESLint instance.
@@ -703,15 +704,11 @@ class ESLint {
 			debug(`Deleting cache file at ${cacheFilePath}`);
 
 			try {
-				await fs.unlink(cacheFilePath);
+				if (existsSync(cacheFilePath)) {
+					await fs.unlink(cacheFilePath);
+				}
 			} catch (error) {
-				const errorCode = error && error.code;
-
-				// Ignore errors when no such file exists or file system is read only (and cache file does not exist)
-				if (
-					errorCode !== "ENOENT" &&
-					!(errorCode === "EROFS" && !existsSync(cacheFilePath))
-				) {
+				if (existsSync(cacheFilePath)) {
 					throw error;
 				}
 			}

package/lib/eslint/legacy-eslint.js

@@ -34,10 +34,10 @@ const { version } = require("../../package.json");
 /** @typedef {import("../shared/types").ConfigData} ConfigData */
 /** @typedef {import("../shared/types").LintMessage} LintMessage */
 /** @typedef {import("../shared/types").SuppressedLintMessage} SuppressedLintMessage */
-/** @typedef {import("../shared/types").Plugin} Plugin */
-/** @typedef {import("../types").Rule.RuleModule} Rule */
 /** @typedef {import("../shared/types").LintResult} LintResult */
 /** @typedef {import("../shared/types").ResultsMeta} ResultsMeta */
+/** @typedef {import("../types").ESLint.Plugin} Plugin */
+/** @typedef {import("../types").Rule.RuleModule} Rule */
 
 /**
  * The main formatter object.

package/lib/languages/js/index.js

@@ -25,6 +25,7 @@ const { LATEST_ECMA_VERSION } = require("../../../conf/ecma-version");
 /** @typedef {import("@eslint/core").File} File */
 /** @typedef {import("@eslint/core").Language} Language */
 /** @typedef {import("@eslint/core").OkParseResult} OkParseResult */
+/** @typedef {import("../../types").Linter.LanguageOptions} JSLanguageOptions */
 
 //-----------------------------------------------------------------------------
 // Helpers
@@ -37,7 +38,7 @@ const parserSymbol = Symbol.for("eslint.RuleTester.parser");
 /**
  * Analyze scope of the given AST.
  * @param {ASTNode} ast The `Program` node to analyze.
- * @param {LanguageOptions} languageOptions The parser options.
+ * @param {JSLanguageOptions} languageOptions The parser options.
  * @param {Record<string, string[]>} visitorKeys The visitor keys.
  * @returns {ScopeManager} The analysis result.
  */
@@ -230,7 +231,7 @@ module.exports = {
 	 * Parses the given file into an AST.
 	 * @param {File} file The virtual file to parse.
 	 * @param {Object} options Additional options passed from ESLint.
-	 * @param {LanguageOptions} options.languageOptions The language options.
+	 * @param {JSLanguageOptions} options.languageOptions The language options.
 	 * @returns {Object} The result of parsing.
 	 */
 	parse(file, { languageOptions }) {
@@ -309,7 +310,7 @@ module.exports = {
 	 * @param {File} file The virtual file to create a `SourceCode` object from.
 	 * @param {OkParseResult} parseResult The result returned from `parse()`.
 	 * @param {Object} options Additional options passed from ESLint.
-	 * @param {LanguageOptions} options.languageOptions The language options.
+	 * @param {JSLanguageOptions} options.languageOptions The language options.
 	 * @returns {SourceCode} The new `SourceCode` object.
 	 */
 	createSourceCode(file, parseResult, { languageOptions }) {

package/lib/linter/esquery.js

@@ -0,0 +1,329 @@
+/**
+ * @fileoverview ESQuery wrapper for ESLint.
+ * @author Nicholas C. Zakas
+ */
+
+"use strict";
+
+//------------------------------------------------------------------------------
+// Requirements
+//------------------------------------------------------------------------------
+
+const esquery = require("esquery");
+
+//-----------------------------------------------------------------------------
+// Typedefs
+//-----------------------------------------------------------------------------
+
+/**
+ * @typedef {import("esquery").Selector} ESQuerySelector
+ * @typedef {import("esquery").ESQueryOptions} ESQueryOptions
+ */
+
+//------------------------------------------------------------------------------
+// Classes
+//------------------------------------------------------------------------------
+
+/**
+ * The result of parsing and analyzing an ESQuery selector.
+ */
+class ESQueryParsedSelector {
+	/**
+	 * The raw selector string that was parsed
+	 * @type {string}
+	 */
+	source;
+
+	/**
+	 * Whether this selector is an exit selector
+	 * @type {boolean}
+	 */
+	isExit;
+
+	/**
+	 * An object (from esquery) describing the matching behavior of the selector
+	 * @type {ESQuerySelector}
+	 */
+	root;
+
+	/**
+	 * The node types that could possibly trigger this selector, or `null` if all node types could trigger it
+	 * @type {string[]|null}
+	 */
+	nodeTypes;
+
+	/**
+	 * The number of class, pseudo-class, and attribute queries in this selector
+	 * @type {number}
+	 */
+	attributeCount;
+
+	/**
+	 * The number of identifier queries in this selector
+	 * @type {number}
+	 */
+	identifierCount;
+
+	/**
+	 * Creates a new parsed selector.
+	 * @param {string} source The raw selector string that was parsed
+	 * @param {boolean} isExit Whether this selector is an exit selector
+	 * @param {ESQuerySelector} root An object (from esquery) describing the matching behavior of the selector
+	 * @param {string[]|null} nodeTypes The node types that could possibly trigger this selector, or `null` if all node types could trigger it
+	 * @param {number} attributeCount The number of class, pseudo-class, and attribute queries in this selector
+	 * @param {number} identifierCount The number of identifier queries in this selector
+	 */
+	constructor(
+		source,
+		isExit,
+		root,
+		nodeTypes,
+		attributeCount,
+		identifierCount,
+	) {
+		this.source = source;
+		this.isExit = isExit;
+		this.root = root;
+		this.nodeTypes = nodeTypes;
+		this.attributeCount = attributeCount;
+		this.identifierCount = identifierCount;
+	}
+
+	/**
+	 * Compares this selector's specifity to another selector for sorting purposes.
+	 * @param {ESQueryParsedSelector} otherSelector The selector to compare against
+	 * @returns {number}
+	 * a value less than 0 if this selector is less specific than otherSelector
+	 * a value greater than 0 if this selector is more specific than otherSelector
+	 * a value less than 0 if this selector and otherSelector have the same specificity, and this selector <= otherSelector alphabetically
+	 * a value greater than 0 if this selector and otherSelector have the same specificity, and this selector > otherSelector alphabetically
+	 */
+	compare(otherSelector) {
+		return (
+			this.attributeCount - otherSelector.attributeCount ||
+			this.identifierCount - otherSelector.identifierCount ||
+			(this.source <= otherSelector.source ? -1 : 1)
+		);
+	}
+}
+
+//------------------------------------------------------------------------------
+// Helpers
+//------------------------------------------------------------------------------
+
+const selectorCache = new Map();
+
+/**
+ * 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;
+}
+
+/**
+ * Analyzes a parsed selector and returns combined data about it
+ * @param {ESQuerySelector} parsedSelector An object (from esquery) describing the matching behavior of the selector
+ * @returns {{nodeTypes:string[]|null, attributeCount:number, identifierCount:number}} Object containing selector data.
+ */
+function analyzeParsedSelector(parsedSelector) {
+	let attributeCount = 0;
+	let identifierCount = 0;
+
+	/**
+	 * Analyzes a selector and returns the node types that could possibly trigger it.
+	 * @param {ESQuerySelector} selector The selector to analyze.
+	 * @returns {string[]|null} The node types that could possibly trigger this selector, or `null` if all node types could trigger it
+	 */
+	function analyzeSelector(selector) {
+		switch (selector.type) {
+			case "identifier":
+				identifierCount++;
+				return [selector.value];
+
+			case "not":
+				selector.selectors.map(analyzeSelector);
+				return null;
+
+			case "matches": {
+				const typesForComponents =
+					selector.selectors.map(analyzeSelector);
+
+				if (typesForComponents.every(Boolean)) {
+					return union(...typesForComponents);
+				}
+				return null;
+			}
+
+			case "compound": {
+				const typesForComponents = selector.selectors
+					.map(analyzeSelector)
+					.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 "attribute":
+			case "field":
+			case "nth-child":
+			case "nth-last-child":
+				attributeCount++;
+				return null;
+
+			case "child":
+			case "descendant":
+			case "sibling":
+			case "adjacent":
+				analyzeSelector(selector.left);
+				return analyzeSelector(selector.right);
+
+			case "class":
+				// TODO: abstract into JSLanguage somehow
+				if (selector.name === "function") {
+					return [
+						"FunctionDeclaration",
+						"FunctionExpression",
+						"ArrowFunctionExpression",
+					];
+				}
+				return null;
+
+			default:
+				return null;
+		}
+	}
+
+	const nodeTypes = analyzeSelector(parsedSelector);
+
+	return {
+		nodeTypes,
+		attributeCount,
+		identifierCount,
+	};
+}
+
+/**
+ * Tries to parse a simple selector string, such as a single identifier or wildcard.
+ * This saves time by avoiding the overhead of esquery parsing for simple cases.
+ * @param {string} selector The selector string to parse.
+ * @returns {Object|null} An object describing the selector if it is simple, or `null` if it is not.
+ */
+function trySimpleParseSelector(selector) {
+	if (selector === "*") {
+		return {
+			type: "wildcard",
+			value: "*",
+		};
+	}
+
+	if (/^[a-z]+$/iu.test(selector)) {
+		return {
+			type: "identifier",
+			value: selector,
+		};
+	}
+
+	return null;
+}
+
+/**
+ * Parses a raw selector string, and throws a useful error if parsing fails.
+ * @param {string} selector The selector string to parse.
+ * @returns {Object} An object (from esquery) describing the matching behavior of this selector
+ * @throws {Error} An error if the selector is invalid
+ */
+function tryParseSelector(selector) {
+	try {
+		return esquery.parse(selector);
+	} catch (err) {
+		if (
+			err.location &&
+			err.location.start &&
+			typeof err.location.start.offset === "number"
+		) {
+			throw new SyntaxError(
+				`Syntax error in selector "${selector}" at position ${err.location.start.offset}: ${err.message}`,
+			);
+		}
+		throw err;
+	}
+}
+
+/**
+ * Parses a raw selector string, and returns the parsed selector along with specificity and type information.
+ * @param {string} source A raw AST selector
+ * @returns {ESQueryParsedSelector} A selector descriptor
+ */
+function parse(source) {
+	if (selectorCache.has(source)) {
+		return selectorCache.get(source);
+	}
+
+	const cleanSource = source.replace(/:exit$/u, "");
+	const parsedSelector =
+		trySimpleParseSelector(cleanSource) ?? tryParseSelector(cleanSource);
+	const { nodeTypes, attributeCount, identifierCount } =
+		analyzeParsedSelector(parsedSelector);
+
+	const result = new ESQueryParsedSelector(
+		source,
+		source.endsWith(":exit"),
+		parsedSelector,
+		nodeTypes,
+		attributeCount,
+		identifierCount,
+	);
+
+	selectorCache.set(source, result);
+	return result;
+}
+
+/**
+ * Checks if a node matches a given selector.
+ * @param {Object} node The node to check against the selector.
+ * @param {ESQuerySelector} root The root of the selector to match against.
+ * @param {Object[]} ancestry The ancestry of the node being checked, which is an array of nodes from the current node to the root.
+ * @param {ESQueryOptions} options The options to use for matching.
+ * @returns {boolean} `true` if the node matches the selector, `false` otherwise.
+ */
+function matches(node, root, ancestry, options) {
+	return esquery.matches(node, root, ancestry, options);
+}
+
+//-----------------------------------------------------------------------------
+// Exports
+//-----------------------------------------------------------------------------
+
+module.exports = {
+	parse,
+	matches,
+	ESQueryParsedSelector,
+};

package/lib/linter/linter.js

@@ -73,20 +73,19 @@ const STEP_KIND_CALL = 2;
 // Typedefs
 //------------------------------------------------------------------------------
 
+/** @import { Language, LanguageOptions, RuleConfig, RuleDefinition, RuleSeverity } from "@eslint/core" */
+
 /** @typedef {import("../shared/types").ConfigData} ConfigData */
 /** @typedef {import("../shared/types").Environment} Environment */
 /** @typedef {import("../shared/types").GlobalConf} GlobalConf */
 /** @typedef {import("../shared/types").LintMessage} LintMessage */
 /** @typedef {import("../shared/types").SuppressedLintMessage} SuppressedLintMessage */
 /** @typedef {import("../shared/types").ParserOptions} ParserOptions */
-/** @typedef {import("../shared/types").LanguageOptions} LanguageOptions */
 /** @typedef {import("../shared/types").Processor} Processor */
-/** @typedef {import("../types").Rule.RuleModule} Rule */
 /** @typedef {import("../shared/types").Times} Times */
-/** @typedef {import("@eslint/core").Language} Language */
-/** @typedef {import("@eslint/core").RuleSeverity} RuleSeverity */
-/** @typedef {import("@eslint/core").RuleConfig} RuleConfig */
+/** @typedef {import("../types").Linter.LanguageOptions} JSLanguageOptions */
 /** @typedef {import("../types").Linter.StringSeverity} StringSeverity */
+/** @typedef {import("../types").Rule.RuleModule} Rule */
 
 /* eslint-disable jsdoc/valid-types -- https://github.com/jsdoc-type-pratt-parser/jsdoc-type-pratt-parser/issues/4#issuecomment-778805577 */
 /**
@@ -1011,7 +1010,7 @@ function resolveParserOptions(parser, providedOptions, enabledEnvironments) {
  * @param {Object} config.globals Global variable definitions.
  * @param {Parser} config.parser The parser to use.
  * @param {ParserOptions} config.parserOptions The parserOptions to use.
- * @returns {LanguageOptions} The languageOptions equivalent.
+ * @returns {JSLanguageOptions} The languageOptions equivalent.
  */
 function createLanguageOptions({
 	globals: configuredGlobals,
@@ -1091,7 +1090,7 @@ function getRuleOptions(ruleConfig, defaultOptions) {
 /**
  * Analyze scope of the given AST.
  * @param {ASTNode} ast The `Program` node to analyze.
- * @param {LanguageOptions} languageOptions The parser options.
+ * @param {JSLanguageOptions} languageOptions The language options.
  * @param {Record<string, string[]>} visitorKeys The visitor keys.
  * @returns {ScopeManager} The analysis result.
  */
@@ -1113,7 +1112,7 @@ function analyzeScope(ast, languageOptions, visitorKeys) {
 
 /**
  * Runs a rule, and gets its listeners
- * @param {Rule} rule A rule object
+ * @param {RuleDefinition} rule A rule object
  * @param {Context} ruleContext The context that should be passed to the rule
  * @throws {TypeError} If `rule` is not an object with a `create` method
  * @throws {any} Any error during the rule's `create`
@@ -1142,7 +1141,7 @@ function createRuleListeners(rule, ruleContext) {
  * Runs the given rules on the given SourceCode object
  * @param {SourceCode} sourceCode A SourceCode object for the given text
  * @param {Object} configuredRules The rules configuration
- * @param {function(string): Rule} ruleMapper A mapper function from rule names to rules
+ * @param {function(string): RuleDefinition} ruleMapper A mapper function from rule names to rules
  * @param {string | undefined} parserName The name of the parser in the config
  * @param {Language} language The language object used for parsing.
  * @param {LanguageOptions} languageOptions The options for parsing the code.