eslint 9.33.0 → 9.35.0

package/lib/eslint/eslint-helpers.js

@@ -11,11 +11,17 @@
 
 const path = require("node:path");
 const fs = require("node:fs");
+const { isMainThread, threadId } = require("node:worker_threads");
 const fsp = fs.promises;
 const isGlob = require("is-glob");
 const hash = require("../cli-engine/hash");
 const minimatch = require("minimatch");
 const globParent = require("glob-parent");
+const { Linter } = require("../linter");
+const { getShorthandName } = require("../shared/naming");
+const LintResultCache = require("../cli-engine/lint-result-cache");
+const { ConfigLoader, LegacyConfigLoader } = require("../config/config-loader");
+const createDebug = require("debug");
 
 //-----------------------------------------------------------------------------
 // Fixup references
@@ -30,11 +36,16 @@ const MINIMATCH_OPTIONS = { dot: true };
 
 /**
  * @import { ESLintOptions } from "./eslint.js";
- * @import { ConfigLoader, LegacyConfigLoader } from "../config/config-loader.js";
+ * @import { Config as CalculatedConfig } from "../config/config.js";
+ * @import { FlatConfigArray } from "../config/flat-config-array.js";
+ * @import { WarningService } from "../services/warning-service.js";
+ * @import { Retrier } from "@humanwhocodes/retry";
  */
 
+/** @typedef {import("../types").Linter.Config} Config */
 /** @typedef {import("../types").Linter.LintMessage} LintMessage */
 /** @typedef {import("../types").ESLint.LintResult} LintResult */
+/** @typedef {import("../types").ESLint.Plugin} Plugin */
 
 /**
  * @typedef {Object} GlobSearch
@@ -43,6 +54,18 @@ const MINIMATCH_OPTIONS = { dot: true };
  *      before doing any normalization.
  */
 
+//------------------------------------------------------------------------------
+// Internal Helpers
+//------------------------------------------------------------------------------
+
+const hrtimeBigint = process.hrtime.bigint;
+
+createDebug.formatters.t = timeDiff =>
+	`${(timeDiff + 500_000n) / 1_000_000n} ms`;
+const debug = createDebug(
+	`eslint:eslint-helpers${isMainThread ? "" : `:thread-${threadId}`}`,
+);
+
 //-----------------------------------------------------------------------------
 // Errors
 //-----------------------------------------------------------------------------
@@ -137,6 +160,15 @@ function isEmptyArrayOrArrayOfNonEmptyString(value) {
 	return Array.isArray(value) && value.every(isNonEmptyString);
 }
 
+/**
+ * Check if a given value is a positive integer.
+ * @param {unknown} value The value to check.
+ * @returns {boolean} `true` if `value` is a positive integer.
+ */
+function isPositiveInteger(value) {
+	return Number.isInteger(value) && value > 0;
+}
+
 //-----------------------------------------------------------------------------
 // File-related Helpers
 //-----------------------------------------------------------------------------
@@ -537,6 +569,7 @@ async function findFiles({
 		filePaths.map(filePath => fsp.stat(filePath).catch(() => {})),
 	);
 
+	const promises = [];
 	stats.forEach((stat, index) => {
 		const filePath = filePaths[index];
 		const pattern = normalizeToPosix(patterns[index]);
@@ -545,6 +578,7 @@ async function findFiles({
 			// files are added directly to the list
 			if (stat.isFile()) {
 				results.push(filePath);
+				promises.push(configLoader.loadConfigArrayForFile(filePath));
 			}
 
 			// directories need extensions attached
@@ -590,15 +624,28 @@ async function findFiles({
 	}
 
 	// now we are safe to do the search
-	const globbyResults = await globMultiSearch({
-		searches,
-		configLoader,
-		errorOnUnmatchedPattern,
-	});
+	promises.push(
+		globMultiSearch({
+			searches,
+			configLoader,
+			errorOnUnmatchedPattern,
+		}),
+	);
+	const globbyResults = (await Promise.all(promises)).at(-1);
 
 	return [...new Set([...results, ...globbyResults])];
 }
 
+/**
+ * Return the absolute path of a file named `"__placeholder__.js"` in a given directory.
+ * This is used as a replacement for a missing file path.
+ * @param {string} cwd An absolute directory path.
+ * @returns {string} The absolute path of a file named `"__placeholder__.js"` in the given directory.
+ */
+function getPlaceholderPath(cwd) {
+	return path.join(cwd, "__placeholder__.js");
+}
+
 //-----------------------------------------------------------------------------
 // Results-related Helpers
 //-----------------------------------------------------------------------------
@@ -758,6 +805,7 @@ function processOptions({
 	cache = false,
 	cacheLocation = ".eslintcache",
 	cacheStrategy = "metadata",
+	concurrency = "off",
 	cwd = process.cwd(),
 	errorOnUnmatchedPattern = true,
 	fix = false,
@@ -853,6 +901,15 @@ function processOptions({
 	if (cacheStrategy !== "metadata" && cacheStrategy !== "content") {
 		errors.push('\'cacheStrategy\' must be any of "metadata", "content".');
 	}
+	if (
+		concurrency !== "off" &&
+		concurrency !== "auto" &&
+		!isPositiveInteger(concurrency)
+	) {
+		errors.push(
+			'\'concurrency\' must be a positive integer, "auto", or "off".',
+		);
+	}
 	if (!isNonEmptyString(cwd) || !path.isAbsolute(cwd)) {
 		errors.push("'cwd' must be an absolute path.");
 	}
@@ -928,6 +985,7 @@ function processOptions({
 		cache,
 		cacheLocation,
 		cacheStrategy,
+		concurrency,
 
 		// when overrideConfigFile is true that means don't do config file lookup
 		configFile: overrideConfigFile === true ? false : overrideConfigFile,
@@ -947,6 +1005,15 @@ function processOptions({
 	};
 }
 
+/**
+ * Loads ESLint constructor options from an options module.
+ * @param {string} optionsURL The URL string of the options module to load.
+ * @returns {Promise<ESLintOptions>} ESLint constructor options.
+ */
+async function loadOptionsFromModule(optionsURL) {
+	return (await import(optionsURL)).default;
+}
+
 //-----------------------------------------------------------------------------
 // Cache-related helpers
 //-----------------------------------------------------------------------------
@@ -1022,6 +1089,349 @@ function getCacheFile(cacheFile, cwd, { prefix = ".cache_" } = {}) {
 	return resolvedCacheFile;
 }
 
+/**
+ * Creates a new lint result cache.
+ * @param {ESLintOptions} eslintOptions The processed ESLint options.
+ * @param {string} cacheFilePath The path to the cache file.
+ * @returns {?LintResultCache} A new lint result cache or `null`.
+ */
+function createLintResultCache({ cache, cacheStrategy }, cacheFilePath) {
+	return cache ? new LintResultCache(cacheFilePath, cacheStrategy) : null;
+}
+
+//-----------------------------------------------------------------------------
+// Lint helpers
+//-----------------------------------------------------------------------------
+
+/**
+ * Checks whether a message's rule type should be fixed.
+ * @param {LintMessage} message The message to check.
+ * @param {CalculatedConfig} config The config for the file that generated the message.
+ * @param {string[]} fixTypes An array of fix types to check.
+ * @returns {boolean} Whether the message should be fixed.
+ */
+function shouldMessageBeFixed(message, config, fixTypes) {
+	if (!message.ruleId) {
+		return fixTypes.has("directive");
+	}
+
+	const rule = message.ruleId && config.getRuleDefinition(message.ruleId);
+
+	return Boolean(rule && rule.meta && fixTypes.has(rule.meta.type));
+}
+
+/**
+ * Creates a fixer function based on the provided fix, fixTypesSet, and config.
+ * @param {Function|boolean} fix The original fix option.
+ * @param {Set<string>} fixTypesSet A set of fix types to filter messages for fixing.
+ * @param {CalculatedConfig} config The config for the file that generated the message.
+ * @returns {Function|boolean} The fixer function or the original fix value.
+ */
+function getFixerForFixTypes(fix, fixTypesSet, config) {
+	if (!fix || !fixTypesSet) {
+		return fix;
+	}
+
+	const originalFix = typeof fix === "function" ? fix : () => true;
+
+	return message =>
+		shouldMessageBeFixed(message, config, fixTypesSet) &&
+		originalFix(message);
+}
+
+/**
+ * Processes a source code using ESLint.
+ * @param {Object} config The config object.
+ * @param {string} config.text The source code to verify.
+ * @param {string} config.cwd The path to the current working directory.
+ * @param {string|undefined} config.filePath The path to the file of `text`. If this is undefined, it uses `<text>`.
+ * @param {FlatConfigArray} config.configs The config.
+ * @param {boolean} config.fix If `true` then it does fix.
+ * @param {boolean} config.allowInlineConfig If `true` then it uses directive comments.
+ * @param {Function} config.ruleFilter A predicate function to filter which rules should be run.
+ * @param {boolean} config.stats If `true`, then if reports extra statistics with the lint results.
+ * @param {Linter} config.linter The linter instance to verify.
+ * @returns {LintResult} The result of linting.
+ * @private
+ */
+function verifyText({
+	text,
+	cwd,
+	filePath: providedFilePath,
+	configs,
+	fix,
+	allowInlineConfig,
+	ruleFilter,
+	stats,
+	linter,
+}) {
+	const startTime = hrtimeBigint();
+
+	const filePath = providedFilePath || "<text>";
+
+	/*
+	 * Verify.
+	 * `config.extractConfig(filePath)` requires an absolute path, but `linter`
+	 * doesn't know CWD, so it gives `linter` an absolute path always.
+	 */
+	const filePathToVerify =
+		filePath === "<text>" ? getPlaceholderPath(cwd) : filePath;
+	const { fixed, messages, output } = linter.verifyAndFix(text, configs, {
+		allowInlineConfig,
+		filename: filePathToVerify,
+		fix,
+		ruleFilter,
+		stats,
+
+		/**
+		 * Check if the linter should adopt a given code block or not.
+		 * @param {string} blockFilename The virtual filename of a code block.
+		 * @returns {boolean} `true` if the linter should adopt the code block.
+		 */
+		filterCodeBlock(blockFilename) {
+			return configs.getConfig(blockFilename) !== void 0;
+		},
+	});
+
+	// Tweak and return.
+	const result = {
+		filePath: filePath === "<text>" ? filePath : path.resolve(filePath),
+		messages,
+		suppressedMessages: linter.getSuppressedMessages(),
+		...calculateStatsPerFile(messages),
+	};
+
+	if (fixed) {
+		result.output = output;
+	}
+
+	if (
+		result.errorCount + result.warningCount > 0 &&
+		typeof result.output === "undefined"
+	) {
+		result.source = text;
+	}
+
+	if (stats) {
+		result.stats = {
+			times: linter.getTimes(),
+			fixPasses: linter.getFixPassCount(),
+		};
+	}
+
+	const endTime = hrtimeBigint();
+	debug('File "%s" linted in %t', filePath, endTime - startTime);
+
+	return result;
+}
+
+/**
+ * Lints a single file.
+ * @param {string} filePath File path to lint.
+ * @param {FlatConfigArray} configs The config array for the file.
+ * @param {ESLintOptions} eslintOptions The processed ESLint options.
+ * @param {Linter} linter The linter instance to use.
+ * @param {?LintResultCache} lintResultCache The result cache or `null`.
+ * @param {?{ duration: bigint; }} readFileCounter Used to keep track of the time spent reading files.
+ * @param {Retrier} [retrier] Used to retry linting on certain errors.
+ * @param {AbortController} [controller] Used to stop linting when an error occurs.
+ * @returns {Promise<LintResult>} The lint result.
+ */
+async function lintFile(
+	filePath,
+	configs,
+	eslintOptions,
+	linter,
+	lintResultCache,
+	readFileCounter,
+	retrier,
+	controller,
+) {
+	const config = configs.getConfig(filePath);
+	const {
+		allowInlineConfig,
+		cwd,
+		fix,
+		fixTypes,
+		ruleFilter,
+		stats,
+		warnIgnored,
+	} = eslintOptions;
+	const fixTypesSet = fixTypes ? new Set(fixTypes) : null;
+
+	/*
+	 * If a filename was entered that cannot be matched
+	 * to a config, then notify the user.
+	 */
+	if (!config) {
+		if (warnIgnored) {
+			const configStatus = configs.getConfigStatus(filePath);
+
+			return createIgnoreResult(filePath, cwd, configStatus);
+		}
+
+		return void 0;
+	}
+
+	// Skip if there is cached result.
+	if (lintResultCache) {
+		const cachedResult = lintResultCache.getCachedLintResults(
+			filePath,
+			config,
+		);
+
+		if (cachedResult) {
+			const hadMessages =
+				cachedResult.messages && cachedResult.messages.length > 0;
+
+			if (hadMessages && fix) {
+				debug(`Reprocessing cached file to allow autofix: ${filePath}`);
+			} else {
+				debug(`Skipping file since it hasn't changed: ${filePath}`);
+				return cachedResult;
+			}
+		}
+	}
+
+	// set up fixer for fixTypes if necessary
+	const fixer = getFixerForFixTypes(fix, fixTypesSet, config);
+
+	/**
+	 * Reads the file and lints its content.
+	 * @returns {Promise<LintResult>} A lint result.
+	 */
+	async function readAndVerifyFile() {
+		const readFileEnterTime = hrtimeBigint();
+		const text = await fsp.readFile(filePath, {
+			encoding: "utf8",
+			signal: controller?.signal,
+		});
+		const readFileExitTime = hrtimeBigint();
+		const readFileDuration = readFileExitTime - readFileEnterTime;
+		debug('File "%s" read in %t', filePath, readFileDuration);
+		if (readFileCounter) {
+			readFileCounter.duration += readFileDuration;
+		}
+
+		// fail immediately if an error occurred in another file
+		controller?.signal.throwIfAborted();
+
+		// do the linting
+		return verifyText({
+			text,
+			filePath,
+			configs,
+			cwd,
+			fix: fixer,
+			allowInlineConfig,
+			ruleFilter,
+			stats,
+			linter,
+		});
+	}
+
+	// Use the retrier if provided, otherwise just call the function.
+	const readAndVerifyFilePromise = retrier
+		? retrier.retry(readAndVerifyFile, { signal: controller?.signal })
+		: readAndVerifyFile();
+
+	return readAndVerifyFilePromise.catch(error => {
+		controller?.abort(error);
+		throw error;
+	});
+}
+
+/**
+ * Retrieves flags from the environment variable ESLINT_FLAGS.
+ * @param {string[]} flags The flags defined via the API.
+ * @returns {string[]} The merged flags to use.
+ */
+function mergeEnvironmentFlags(flags) {
+	if (!process.env.ESLINT_FLAGS) {
+		return flags;
+	}
+
+	const envFlags = process.env.ESLINT_FLAGS.trim().split(/\s*,\s*/gu);
+	return Array.from(new Set([...envFlags, ...flags]));
+}
+
+/**
+ * Creates a new linter instance.
+ * @param {ESLintOptions} eslintOptions The processed ESLint options.
+ * @param {WarningService} warningService The warning service to use.
+ * @returns {Linter} The linter instance.
+ */
+function createLinter({ cwd, flags }, warningService) {
+	return new Linter({
+		configType: "flat",
+		cwd,
+		flags: mergeEnvironmentFlags(flags),
+		warningService,
+	});
+}
+
+/**
+ * Creates default configs with the specified plugins.
+ * @param {Record<string, Plugin> | undefined} optionPlugins The plugins specified in the ESLint options.
+ * @returns {Config[]} The default configs.
+ */
+function createDefaultConfigs(optionPlugins) {
+	const defaultConfigs = [];
+
+	// Add plugins
+	if (optionPlugins) {
+		const plugins = {};
+
+		for (const [pluginName, plugin] of Object.entries(optionPlugins)) {
+			plugins[getShorthandName(pluginName, "eslint-plugin")] = plugin;
+		}
+
+		defaultConfigs.push({ plugins });
+	}
+
+	return defaultConfigs;
+}
+
+/**
+ * Creates a config loader.
+ * @param {ESLintOptions} eslintOptions The processed ESLint options.
+ * @param {Config[]} defaultConfigs The default configs.
+ * @param {Linter} linter The linter instance.
+ * @param {WarningService} warningService The warning service to use.
+ * @returns {ConfigLoader} The config loader.
+ */
+function createConfigLoader(
+	{
+		cwd,
+		baseConfig,
+		overrideConfig,
+		configFile,
+		ignore: ignoreEnabled,
+		ignorePatterns,
+	},
+	defaultConfigs,
+	linter,
+	warningService,
+) {
+	const configLoaderOptions = {
+		cwd,
+		baseConfig,
+		overrideConfig,
+		configFile,
+		ignoreEnabled,
+		ignorePatterns,
+		defaultConfigs,
+		hasUnstableNativeNodeJsTSConfigFlag: linter.hasFlag(
+			"unstable_native_nodejs_ts_config",
+		),
+		warningService,
+	};
+
+	return linter.hasFlag("v10_config_lookup_from_file")
+		? new ConfigLoader(configLoaderOptions)
+		: new LegacyConfigLoader(configLoaderOptions);
+}
+
 //-----------------------------------------------------------------------------
 // Exports
 //-----------------------------------------------------------------------------
@@ -1035,8 +1445,18 @@ module.exports = {
 	createIgnoreResult,
 	isErrorMessage,
 	calculateStatsPerFile,
+	getPlaceholderPath,
 
 	processOptions,
+	loadOptionsFromModule,
 
 	getCacheFile,
+	createLintResultCache,
+
+	getFixerForFixTypes,
+	verifyText,
+	lintFile,
+	createLinter,
+	createDefaultConfigs,
+	createConfigLoader,
 };