eslint 9.25.1 → 9.27.0

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/file-context.js

@@ -128,6 +128,17 @@ class FileContext {
 	getSourceCode() {
 		return this.sourceCode;
 	}
+
+	/**
+	 * Creates a new object with the current object as the prototype and
+	 * the specified properties as its own properties.
+	 * @param {Object} extension The properties to add to the new object.
+	 * @returns {FileContext} A new object with the current object as the prototype
+	 * and the specified properties as its own properties.
+	 */
+	extend(extension) {
+		return Object.freeze(Object.assign(Object.create(this), extension));
+	}
 }
 
 exports.FileContext = FileContext;

package/lib/linter/linter.js

@@ -34,10 +34,8 @@ const path = require("node:path"),
 	SourceCodeFixer = require("./source-code-fixer"),
 	timing = require("./timing"),
 	ruleReplacements = require("../../conf/replacements.json");
-const { getRuleFromConfig } = require("../config/flat-config-helpers");
 const { FlatConfigArray } = require("../config/flat-config-array");
 const { startTime, endTime } = require("../shared/stats");
-const { RuleValidator } = require("../config/rule-validator");
 const { assertIsRuleSeverity } = require("../config/flat-config-schema");
 const {
 	normalizeSeverityToString,
@@ -66,6 +64,7 @@ const { ParserService } = require("../services/parser-service");
 const { FileContext } = require("./file-context");
 const { ProcessorService } = require("../services/processor-service");
 const { containsDifferentProperty } = require("../shared/option-utils");
+const { Config } = require("../config/config");
 const STEP_KIND_VISIT = 1;
 const STEP_KIND_CALL = 2;
 
@@ -73,20 +72,21 @@ const STEP_KIND_CALL = 2;
 // Typedefs
 //------------------------------------------------------------------------------
 
-/** @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 */
+/** @import { Language, LanguageOptions, RuleConfig, RuleDefinition, RuleSeverity } from "@eslint/core" */
+
+/** @typedef {import("../types").Linter.Config} Config */
+/** @typedef {import("../types").ESLint.ConfigData} ConfigData */
+/** @typedef {import("../types").ESLint.Environment} Environment */
+/** @typedef {import("../types").Linter.GlobalConf} GlobalConf */
+/** @typedef {import("../types").Linter.LanguageOptions} JSLanguageOptions */
+/** @typedef {import("../types").Linter.LintMessage} LintMessage */
+/** @typedef {import("../types").Linter.Parser} Parser */
+/** @typedef {import("../types").Linter.ParserOptions} ParserOptions */
+/** @typedef {import("../types").Linter.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.StringSeverity} StringSeverity */
+/** @typedef {import("../types").Linter.SuppressedLintMessage} SuppressedLintMessage */
+/** @typedef {import("../types").Linter.TimePass} TimePass */
 
 /* eslint-disable jsdoc/valid-types -- https://github.com/jsdoc-type-pratt-parser/jsdoc-type-pratt-parser/issues/4#issuecomment-778805577 */
 /**
@@ -111,7 +111,7 @@ const STEP_KIND_CALL = 2;
  * @property {SourceCode|null} lastSourceCode The `SourceCode` instance that the last `verify()` call used.
  * @property {SuppressedLintMessage[]} lastSuppressedMessages The `SuppressedLintMessage[]` instance that the last `verify()` call produced.
  * @property {Map<string, Parser>} parserMap The loaded parsers.
- * @property {Times} times The times spent on applying a rule to a file (see `stats` option).
+ * @property {{ passes: TimePass[]; }} times The times spent on applying a rule to a file (see `stats` option).
  * @property {Rules} ruleMap The loaded rules.
  */
 
@@ -351,7 +351,7 @@ function asArray(value) {
 
 /**
  * Pushes a problem to inlineConfigProblems if ruleOptions are redundant.
- * @param {ConfigData} config Provided config.
+ * @param {Config} config Provided config.
  * @param {Object} loc A line/column location
  * @param {Array} problems Problems that may be added to.
  * @param {string} ruleId The rule ID.
@@ -902,7 +902,7 @@ function normalizeFilename(filename) {
  * Normalizes the possible options for `linter.verify` and `linter.verifyAndFix` to a
  * consistent shape.
  * @param {VerifyOptions} providedOptions Options
- * @param {ConfigData} config Config.
+ * @param {Config|ConfigData} config Config.
  * @returns {Required<VerifyOptions> & InternalOptions} Normalized options
  */
 function normalizeVerifyOptions(providedOptions, config) {
@@ -1011,7 +1011,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 +1091,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 +1113,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 +1142,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.
@@ -1185,7 +1185,7 @@ function runRules(
 	 * All rule contexts will inherit from this object. This avoids the performance penalty of copying all the
 	 * properties once for each rule.
 	 */
-	const sharedTraversalContext = new FileContext({
+	const fileContext = new FileContext({
 		cwd,
 		filename,
 		physicalFilename: physicalFilename || filename,
@@ -1201,7 +1201,7 @@ function runRules(
 	const lintingProblems = [];
 
 	Object.keys(configuredRules).forEach(ruleId => {
-		const severity = ConfigOps.getRuleSeverity(configuredRules[ruleId]);
+		const severity = Config.getRuleNumericSeverity(configuredRules[ruleId]);
 
 		// not load disabled rules
 		if (severity === 0) {
@@ -1221,63 +1221,61 @@ function runRules(
 
 		const messageIds = rule.meta && rule.meta.messages;
 		let reportTranslator = null;
-		const ruleContext = Object.freeze(
-			Object.assign(Object.create(sharedTraversalContext), {
-				id: ruleId,
-				options: getRuleOptions(
-					configuredRules[ruleId],
-					applyDefaultOptions ? rule.meta?.defaultOptions : void 0,
-				),
-				report(...args) {
-					/*
-					 * Create a report translator lazily.
-					 * In a vast majority of cases, any given rule reports zero errors on a given
-					 * piece of code. Creating a translator lazily avoids the performance cost of
-					 * creating a new translator function for each rule that usually doesn't get
-					 * called.
-					 *
-					 * Using lazy report translators improves end-to-end performance by about 3%
-					 * with Node 8.4.0.
-					 */
-					if (reportTranslator === null) {
-						reportTranslator = createReportTranslator({
-							ruleId,
-							severity,
-							sourceCode,
-							messageIds,
-							disableFixes,
-							language,
-						});
-					}
-					const problem = reportTranslator(...args);
+		const ruleContext = fileContext.extend({
+			id: ruleId,
+			options: getRuleOptions(
+				configuredRules[ruleId],
+				applyDefaultOptions ? rule.meta?.defaultOptions : void 0,
+			),
+			report(...args) {
+				/*
+				 * Create a report translator lazily.
+				 * In a vast majority of cases, any given rule reports zero errors on a given
+				 * piece of code. Creating a translator lazily avoids the performance cost of
+				 * creating a new translator function for each rule that usually doesn't get
+				 * called.
+				 *
+				 * Using lazy report translators improves end-to-end performance by about 3%
+				 * with Node 8.4.0.
+				 */
+				if (reportTranslator === null) {
+					reportTranslator = createReportTranslator({
+						ruleId,
+						severity,
+						sourceCode,
+						messageIds,
+						disableFixes,
+						language,
+					});
+				}
+				const problem = reportTranslator(...args);
 
-					if (problem.fix && !(rule.meta && rule.meta.fixable)) {
-						throw new Error(
-							'Fixable rules must set the `meta.fixable` property to "code" or "whitespace".',
-						);
-					}
+				if (problem.fix && !(rule.meta && rule.meta.fixable)) {
+					throw new Error(
+						'Fixable rules must set the `meta.fixable` property to "code" or "whitespace".',
+					);
+				}
+				if (
+					problem.suggestions &&
+					!(rule.meta && rule.meta.hasSuggestions === true)
+				) {
 					if (
-						problem.suggestions &&
-						!(rule.meta && rule.meta.hasSuggestions === true)
+						rule.meta &&
+						rule.meta.docs &&
+						typeof rule.meta.docs.suggestion !== "undefined"
 					) {
-						if (
-							rule.meta &&
-							rule.meta.docs &&
-							typeof rule.meta.docs.suggestion !== "undefined"
-						) {
-							// Encourage migration from the former property name.
-							throw new Error(
-								"Rules with suggestions must set the `meta.hasSuggestions` property to `true`. `meta.docs.suggestion` is ignored by ESLint.",
-							);
-						}
+						// Encourage migration from the former property name.
 						throw new Error(
-							"Rules with suggestions must set the `meta.hasSuggestions` property to `true`.",
+							"Rules with suggestions must set the `meta.hasSuggestions` property to `true`. `meta.docs.suggestion` is ignored by ESLint.",
 						);
 					}
-					lintingProblems.push(problem);
-				},
-			}),
-		);
+					throw new Error(
+						"Rules with suggestions must set the `meta.hasSuggestions` property to `true`.",
+					);
+				}
+				lintingProblems.push(problem);
+			},
+		});
 
 		const ruleListenersReturn =
 			timing.enabled || stats
@@ -1886,7 +1884,7 @@ class Linter {
 	/**
 	 * Verify with a processor.
 	 * @param {string|SourceCode} textOrSourceCode The source code.
-	 * @param {FlatConfig} config The config array.
+	 * @param {Config} config The config array.
 	 * @param {VerifyOptions&ProcessorOptions} options The options.
 	 * @param {FlatConfigArray} [configForRecursive] The `ConfigArray` object to apply multiple processors recursively.
 	 * @returns {(LintMessage|SuppressedLintMessage)[]} The found problems.
@@ -1987,7 +1985,7 @@ class Linter {
 	/**
 	 * Verify using flat config and without any processors.
 	 * @param {VFile} file The file to lint.
-	 * @param {FlatConfig} providedConfig An ESLintConfig instance to configure everything.
+	 * @param {Config} providedConfig An ESLintConfig instance to configure everything.
 	 * @param {VerifyOptions} [providedOptions] The optional filename of the file being checked.
 	 * @throws {Error} If during rule execution.
 	 * @returns {(LintMessage|SuppressedLintMessage)[]} The results as an array of messages or an empty array if no messages.
@@ -2101,15 +2099,12 @@ class Linter {
 							}),
 					);
 
-					// next we need to verify information about the specified rules
-					const ruleValidator = new RuleValidator();
-
 					for (const {
 						config: inlineConfig,
 						loc,
 					} of inlineConfigResult.configs) {
 						Object.keys(inlineConfig.rules).forEach(ruleId => {
-							const rule = getRuleFromConfig(ruleId, config);
+							const rule = config.getRuleDefinition(ruleId);
 							const ruleValue = inlineConfig.rules[ruleId];
 
 							if (!rule) {
@@ -2219,11 +2214,8 @@ class Linter {
 								}
 
 								if (shouldValidateOptions) {
-									ruleValidator.validate({
-										plugins: config.plugins,
-										rules: {
-											[ruleId]: ruleOptions,
-										},
+									config.validateRulesConfig({
+										[ruleId]: ruleOptions,
 									});
 								}
 
@@ -2271,7 +2263,7 @@ class Linter {
 			options.allowInlineConfig && !options.warnInlineConfig
 				? getDirectiveCommentsForFlatConfig(
 						sourceCode,
-						ruleId => getRuleFromConfig(ruleId, config),
+						ruleId => config.getRuleDefinition(ruleId),
 						config.language,
 					)
 				: { problems: [], disableDirectives: [] };
@@ -2290,7 +2282,7 @@ class Linter {
 			lintingProblems = runRules(
 				sourceCode,
 				configuredRules,
-				ruleId => getRuleFromConfig(ruleId, config),
+				ruleId => config.getRuleDefinition(ruleId),
 				void 0,
 				config.language,
 				languageOptions,
@@ -2349,7 +2341,7 @@ class Linter {
 	/**
 	 * Same as linter.verify, except without support for processors.
 	 * @param {string|SourceCode} textOrSourceCode The text to parse or a SourceCode object.
-	 * @param {FlatConfig} providedConfig An ESLintConfig instance to configure everything.
+	 * @param {Config} providedConfig An ESLintConfig instance to configure everything.
 	 * @param {VerifyOptions} [providedOptions] The optional filename of the file being checked.
 	 * @throws {Error} If during rule execution.
 	 * @returns {(LintMessage|SuppressedLintMessage)[]} The results as an array of messages or an empty array if no messages.
@@ -2620,7 +2612,7 @@ class Linter {
 
 	/**
 	 * Gets the times spent on (parsing, fixing, linting) a file.
-	 * @returns {LintTimes} The times.
+	 * @returns {{ passes: TimePass[]; }} The times.
 	 */
 	getTimes() {
 		return internalSlotsMap.get(this).times ?? { passes: [] };