eslint 8.57.0 → 9.2.0

package/lib/config/flat-config-array.js

@@ -13,12 +13,16 @@ const { ConfigArray, ConfigArraySymbol } = require("@humanwhocodes/config-array"
 const { flatConfigSchema } = require("./flat-config-schema");
 const { RuleValidator } = require("./rule-validator");
 const { defaultConfig } = require("./default-config");
-const jsPlugin = require("@eslint/js");
 
 //-----------------------------------------------------------------------------
 // Helpers
 //-----------------------------------------------------------------------------
 
+/**
+ * Fields that are considered metadata and not part of the config object.
+ */
+const META_FIELDS = new Set(["name"]);
+
 const ruleValidator = new RuleValidator();
 
 /**
@@ -75,7 +79,53 @@ function getObjectId(object) {
     return name;
 }
 
+/**
+ * Wraps a config error with details about where the error occurred.
+ * @param {Error} error The original error.
+ * @param {number} originalLength The original length of the config array.
+ * @param {number} baseLength The length of the base config.
+ * @returns {TypeError} The new error with details.
+ */
+function wrapConfigErrorWithDetails(error, originalLength, baseLength) {
+
+    let location = "user-defined";
+    let configIndex = error.index;
+
+    /*
+     * A config array is set up in this order:
+     * 1. Base config
+     * 2. Original configs
+     * 3. User-defined configs
+     * 4. CLI-defined configs
+     *
+     * So we need to adjust the index to account for the base config.
+     *
+     * - If the index is less than the base length, it's in the base config
+     *   (as specified by `baseConfig` argument to `FlatConfigArray` constructor).
+     * - If the index is greater than the base length but less than the original
+     *   length + base length, it's in the original config. The original config
+     *   is passed to the `FlatConfigArray` constructor as the first argument.
+     * - Otherwise, it's in the user-defined config, which is loaded from the
+     *   config file and merged with any command-line options.
+     */
+    if (error.index < baseLength) {
+        location = "base";
+    } else if (error.index < originalLength + baseLength) {
+        location = "original";
+        configIndex = error.index - baseLength;
+    } else {
+        configIndex = error.index - originalLength - baseLength;
+    }
+
+    return new TypeError(
+        `${error.message.slice(0, -1)} at ${location} index ${configIndex}.`,
+        { cause: error }
+    );
+}
+
 const originalBaseConfig = Symbol("originalBaseConfig");
+const originalLength = Symbol("originalLength");
+const baseLength = Symbol("baseLength");
 
 //-----------------------------------------------------------------------------
 // Exports
@@ -102,12 +152,24 @@ class FlatConfigArray extends ConfigArray {
             schema: flatConfigSchema
         });
 
+        /**
+         * The original length of the array before any modifications.
+         * @type {number}
+         */
+        this[originalLength] = this.length;
+
         if (baseConfig[Symbol.iterator]) {
             this.unshift(...baseConfig);
         } else {
             this.unshift(baseConfig);
         }
 
+        /**
+         * The length of the array after applying the base config.
+         * @type {number}
+         */
+        this[baseLength] = this.length - this[originalLength];
+
         /**
          * The base config used to build the config array.
          * @type {Array<FlatConfig>}
@@ -125,45 +187,69 @@ class FlatConfigArray extends ConfigArray {
         Object.defineProperty(this, "shouldIgnore", { writable: false });
     }
 
-    /* eslint-disable class-methods-use-this -- Desired as instance method */
     /**
-     * Replaces a config with another config to allow us to put strings
-     * in the config array that will be replaced by objects before
-     * normalization.
-     * @param {Object} config The config to preprocess.
-     * @returns {Object} The preprocessed config.
+     * Normalizes the array by calling the superclass method and catching/rethrowing
+     * any ConfigError exceptions with additional details.
+     * @param {any} [context] The context to use to normalize the array.
+     * @returns {Promise<FlatConfigArray>} A promise that resolves when the array is normalized.
      */
-    [ConfigArraySymbol.preprocessConfig](config) {
-        if (config === "eslint:recommended") {
+    normalize(context) {
+        return super.normalize(context)
+            .catch(error => {
+                if (error.name === "ConfigError") {
+                    throw wrapConfigErrorWithDetails(error, this[originalLength], this[baseLength]);
+                }
 
-            // if we are in a Node.js environment warn the user
-            if (typeof process !== "undefined" && process.emitWarning) {
-                process.emitWarning("The 'eslint:recommended' string configuration is deprecated and will be replaced by the @eslint/js package's 'recommended' config.");
-            }
+                throw error;
 
-            return jsPlugin.configs.recommended;
-        }
+            });
+    }
+
+    /**
+     * Normalizes the array by calling the superclass method and catching/rethrowing
+     * any ConfigError exceptions with additional details.
+     * @param {any} [context] The context to use to normalize the array.
+     * @returns {FlatConfigArray} The current instance.
+     * @throws {TypeError} If the config is invalid.
+     */
+    normalizeSync(context) {
+
+        try {
 
-        if (config === "eslint:all") {
+            return super.normalizeSync(context);
 
-            // if we are in a Node.js environment warn the user
-            if (typeof process !== "undefined" && process.emitWarning) {
-                process.emitWarning("The 'eslint:all' string configuration is deprecated and will be replaced by the @eslint/js package's 'all' config.");
+        } catch (error) {
+
+            if (error.name === "ConfigError") {
+                throw wrapConfigErrorWithDetails(error, this[originalLength], this[baseLength]);
             }
 
-            return jsPlugin.configs.all;
+            throw error;
+
         }
 
+    }
+
+    /* eslint-disable class-methods-use-this -- Desired as instance method */
+    /**
+     * Replaces a config with another config to allow us to put strings
+     * in the config array that will be replaced by objects before
+     * normalization.
+     * @param {Object} config The config to preprocess.
+     * @returns {Object} The preprocessed config.
+     */
+    [ConfigArraySymbol.preprocessConfig](config) {
+
         /*
-         * If `shouldIgnore` is false, we remove any ignore patterns specified
-         * in the config so long as it's not a default config and it doesn't
-         * have a `files` entry.
+         * If a config object has `ignores` and no other non-meta fields, then it's an object
+         * for global ignores. If `shouldIgnore` is false, that object shouldn't apply,
+         * so we'll remove its `ignores`.
          */
         if (
             !this.shouldIgnore &&
             !this[originalBaseConfig].includes(config) &&
             config.ignores &&
-            !config.files
+            Object.keys(config).filter(key => !META_FIELDS.has(key)).length === 1
         ) {
             /* eslint-disable-next-line no-unused-vars -- need to strip off other keys */
             const { ignores, ...otherKeys } = config;

package/lib/config/flat-config-helpers.js

@@ -5,6 +5,23 @@
 
 "use strict";
 
+//------------------------------------------------------------------------------
+// Typedefs
+//------------------------------------------------------------------------------
+
+/** @typedef {import("../shared/types").Rule} Rule */
+
+//------------------------------------------------------------------------------
+// Private Members
+//------------------------------------------------------------------------------
+
+// JSON schema that disallows passing any options
+const noOptionsSchema = Object.freeze({
+    type: "array",
+    minItems: 0,
+    maxItems: 0
+});
+
 //-----------------------------------------------------------------------------
 // Functions
 //-----------------------------------------------------------------------------
@@ -52,32 +69,39 @@ function getRuleFromConfig(ruleId, config) {
     const { pluginName, ruleName } = parseRuleId(ruleId);
 
     const plugin = config.plugins && config.plugins[pluginName];
-    let rule = plugin && plugin.rules && plugin.rules[ruleName];
-
-
-    // normalize function rules into objects
-    if (rule && typeof rule === "function") {
-        rule = {
-            create: rule
-        };
-    }
+    const rule = plugin && plugin.rules && plugin.rules[ruleName];
 
     return rule;
 }
 
 /**
  * Gets a complete options schema for a rule.
- * @param {{create: Function, schema: (Array|null)}} rule A new-style rule object
- * @returns {Object} JSON Schema for the rule's options.
+ * @param {Rule} rule A rule object
+ * @throws {TypeError} If `meta.schema` is specified but is not an array, object or `false`.
+ * @returns {Object|null} JSON Schema for the rule's options. `null` if `meta.schema` is `false`.
  */
 function getRuleOptionsSchema(rule) {
 
-    if (!rule) {
+    if (!rule.meta) {
+        return { ...noOptionsSchema }; // default if `meta.schema` is not specified
+    }
+
+    const schema = rule.meta.schema;
+
+    if (typeof schema === "undefined") {
+        return { ...noOptionsSchema }; // default if `meta.schema` is not specified
+    }
+
+    // `schema:false` is an allowed explicit opt-out of options validation for the rule
+    if (schema === false) {
         return null;
     }
 
-    const schema = rule.schema || rule.meta && rule.meta.schema;
+    if (typeof schema !== "object" || schema === null) {
+        throw new TypeError("Rule's `meta.schema` must be an array or object");
+    }
 
+    // ESLint-specific array form needs to be converted into a valid JSON Schema definition
     if (Array.isArray(schema)) {
         if (schema.length) {
             return {
@@ -87,16 +111,13 @@ function getRuleOptionsSchema(rule) {
                 maxItems: schema.length
             };
         }
-        return {
-            type: "array",
-            minItems: 0,
-            maxItems: 0
-        };
 
+        // `schema:[]` is an explicit way to specify that the rule does not accept any options
+        return { ...noOptionsSchema };
     }
 
-    // Given a full schema, leave it alone
-    return schema || null;
+    // `schema:<object>` is assumed to be a valid JSON Schema definition
+    return schema;
 }
 
 

package/lib/config/flat-config-schema.js

@@ -9,11 +9,6 @@
 // Requirements
 //-----------------------------------------------------------------------------
 
-/*
- * Note: This can be removed in ESLint v9 because structuredClone is available globally
- * starting in Node.js v17.
- */
-const structuredClone = require("@ungap/structured-clone").default;
 const { normalizeSeverityToNumber } = require("../shared/severity");
 
 //-----------------------------------------------------------------------------
@@ -593,6 +588,5 @@ const flatConfigSchema = {
 
 module.exports = {
     flatConfigSchema,
-    assertIsRuleSeverity,
-    assertIsRuleOptions
+    assertIsRuleSeverity
 };

package/lib/config/rule-validator.js

@@ -66,6 +66,25 @@ function throwRuleNotFoundError({ pluginName, ruleName }, config) {
     throw new TypeError(errorMessage);
 }
 
+/**
+ * The error type when a rule has an invalid `meta.schema`.
+ */
+class InvalidRuleOptionsSchemaError extends Error {
+
+    /**
+     * Creates a new instance.
+     * @param {string} ruleId Id of the rule that has an invalid `meta.schema`.
+     * @param {Error} processingError Error caught while processing the `meta.schema`.
+     */
+    constructor(ruleId, processingError) {
+        super(
+            `Error while processing options validation schema of rule '${ruleId}': ${processingError.message}`,
+            { cause: processingError }
+        );
+        this.code = "ESLINT_INVALID_RULE_OPTIONS_SCHEMA";
+    }
+}
+
 //-----------------------------------------------------------------------------
 // Exports
 //-----------------------------------------------------------------------------
@@ -130,10 +149,14 @@ class RuleValidator {
 
             // Precompile and cache validator the first time
             if (!this.validators.has(rule)) {
-                const schema = getRuleOptionsSchema(rule);
-
-                if (schema) {
-                    this.validators.set(rule, ajv.compile(schema));
+                try {
+                    const schema = getRuleOptionsSchema(rule);
+
+                    if (schema) {
+                        this.validators.set(rule, ajv.compile(schema));
+                    }
+                } catch (err) {
+                    throw new InvalidRuleOptionsSchemaError(ruleId, err);
                 }
             }
 
@@ -144,9 +167,22 @@ class RuleValidator {
                 validateRule(ruleOptions.slice(1));
 
                 if (validateRule.errors) {
-                    throw new Error(`Key "rules": Key "${ruleId}": ${
+                    throw new Error(`Key "rules": Key "${ruleId}":\n${
                         validateRule.errors.map(
-                            error => `\tValue ${JSON.stringify(error.data)} ${error.message}.\n`
+                            error => {
+                                if (
+                                    error.keyword === "additionalProperties" &&
+                                    error.schema === false &&
+                                    typeof error.parentSchema?.properties === "object" &&
+                                    typeof error.params?.additionalProperty === "string"
+                                ) {
+                                    const expectedProperties = Object.keys(error.parentSchema.properties).map(property => `"${property}"`);
+
+                                    return `\tValue ${JSON.stringify(error.data)} ${error.message}.\n\t\tUnexpected property "${error.params.additionalProperty}". Expected properties: ${expectedProperties.join(", ")}.\n`;
+                                }
+
+                                return `\tValue ${JSON.stringify(error.data)} ${error.message}.\n`;
+                            }
                         ).join("")
                     }`);
                 }

package/lib/eslint/eslint-helpers.js

@@ -15,7 +15,6 @@ const fsp = fs.promises;
 const isGlob = require("is-glob");
 const hash = require("../cli-engine/hash");
 const minimatch = require("minimatch");
-const util = require("util");
 const fswalk = require("@nodelib/fs.walk");
 const globParent = require("glob-parent");
 const isPathInside = require("is-path-inside");
@@ -24,7 +23,6 @@ const isPathInside = require("is-path-inside");
 // Fixup references
 //-----------------------------------------------------------------------------
 
-const doFsWalk = util.promisify(fswalk.walk);
 const Minimatch = minimatch.Minimatch;
 const MINIMATCH_OPTIONS = { dot: true };
 
@@ -105,20 +103,30 @@ class AllFilesIgnoredError extends Error {
 
 /**
  * Check if a given value is a non-empty string or not.
- * @param {any} x The value to check.
- * @returns {boolean} `true` if `x` is a non-empty string.
+ * @param {any} value The value to check.
+ * @returns {boolean} `true` if `value` is a non-empty string.
  */
-function isNonEmptyString(x) {
-    return typeof x === "string" && x.trim() !== "";
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim() !== "";
 }
 
 /**
  * Check if a given value is an array of non-empty strings or not.
- * @param {any} x The value to check.
- * @returns {boolean} `true` if `x` is an array of non-empty strings.
+ * @param {any} value The value to check.
+ * @returns {boolean} `true` if `value` is an array of non-empty strings.
+ */
+function isArrayOfNonEmptyString(value) {
+    return Array.isArray(value) && value.length && value.every(isNonEmptyString);
+}
+
+/**
+ * Check if a given value is an empty array or an array of non-empty strings.
+ * @param {any} value The value to check.
+ * @returns {boolean} `true` if `value` is an empty array or an array of non-empty
+ *      strings.
  */
-function isArrayOfNonEmptyString(x) {
-    return Array.isArray(x) && x.every(isNonEmptyString);
+function isEmptyArrayOrArrayOfNonEmptyString(value) {
+    return Array.isArray(value) && value.every(isNonEmptyString);
 }
 
 //-----------------------------------------------------------------------------
@@ -270,56 +278,92 @@ async function globSearch({
      */
     const unmatchedPatterns = new Set([...relativeToPatterns.keys()]);
 
-    const filePaths = (await doFsWalk(basePath, {
-
-        deepFilter(entry) {
-            const relativePath = normalizeToPosix(path.relative(basePath, entry.path));
-            const matchesPattern = matchers.some(matcher => matcher.match(relativePath, true));
+    const filePaths = (await new Promise((resolve, reject) => {
 
-            return matchesPattern && !configs.isDirectoryIgnored(entry.path);
-        },
-        entryFilter(entry) {
-            const relativePath = normalizeToPosix(path.relative(basePath, entry.path));
+        let promiseRejected = false;
 
-            // entries may be directories or files so filter out directories
-            if (entry.dirent.isDirectory()) {
+        /**
+         * Wraps a boolean-returning filter function. The wrapped function will reject the promise if an error occurs.
+         * @param {Function} filter A filter function to wrap.
+         * @returns {Function} A function similar to the wrapped filter that rejects the promise if an error occurs.
+         */
+        function wrapFilter(filter) {
+            return (...args) => {
+
+                // No need to run the filter if an error has been thrown.
+                if (!promiseRejected) {
+                    try {
+                        return filter(...args);
+                    } catch (error) {
+                        promiseRejected = true;
+                        reject(error);
+                    }
+                }
                 return false;
-            }
+            };
+        }
 
-            /*
-             * Optimization: We need to track when patterns are left unmatched
-             * and so we use `unmatchedPatterns` to do that. There is a bit of
-             * complexity here because the same file can be matched by more than
-             * one pattern. So, when we start, we actually need to test every
-             * pattern against every file. Once we know there are no remaining
-             * unmatched patterns, then we can switch to just looking for the
-             * first matching pattern for improved speed.
-             */
-            const matchesPattern = unmatchedPatterns.size > 0
-                ? matchers.reduce((previousValue, matcher) => {
-                    const pathMatches = matcher.match(relativePath);
+        fswalk.walk(
+            basePath,
+            {
+                deepFilter: wrapFilter(entry => {
+                    const relativePath = normalizeToPosix(path.relative(basePath, entry.path));
+                    const matchesPattern = matchers.some(matcher => matcher.match(relativePath, true));
+
+                    return matchesPattern && !configs.isDirectoryIgnored(entry.path);
+                }),
+                entryFilter: wrapFilter(entry => {
+                    const relativePath = normalizeToPosix(path.relative(basePath, entry.path));
+
+                    // entries may be directories or files so filter out directories
+                    if (entry.dirent.isDirectory()) {
+                        return false;
+                    }
 
                     /*
-                     * We updated the unmatched patterns set only if the path
-                     * matches and the file isn't ignored. If the file is
-                     * ignored, that means there wasn't a match for the
-                     * pattern so it should not be removed.
-                     *
-                     * Performance note: isFileIgnored() aggressively caches
-                     * results so there is no performance penalty for calling
-                     * it twice with the same argument.
+                     * Optimization: We need to track when patterns are left unmatched
+                     * and so we use `unmatchedPatterns` to do that. There is a bit of
+                     * complexity here because the same file can be matched by more than
+                     * one pattern. So, when we start, we actually need to test every
+                     * pattern against every file. Once we know there are no remaining
+                     * unmatched patterns, then we can switch to just looking for the
+                     * first matching pattern for improved speed.
                      */
-                    if (pathMatches && !configs.isFileIgnored(entry.path)) {
-                        unmatchedPatterns.delete(matcher.pattern);
-                    }
-
-                    return pathMatches || previousValue;
-                }, false)
-                : matchers.some(matcher => matcher.match(relativePath));
-
-            return matchesPattern && !configs.isFileIgnored(entry.path);
-        }
-
+                    const matchesPattern = unmatchedPatterns.size > 0
+                        ? matchers.reduce((previousValue, matcher) => {
+                            const pathMatches = matcher.match(relativePath);
+
+                            /*
+                             * We updated the unmatched patterns set only if the path
+                             * matches and the file isn't ignored. If the file is
+                             * ignored, that means there wasn't a match for the
+                             * pattern so it should not be removed.
+                             *
+                             * Performance note: isFileIgnored() aggressively caches
+                             * results so there is no performance penalty for calling
+                             * it twice with the same argument.
+                             */
+                            if (pathMatches && !configs.isFileIgnored(entry.path)) {
+                                unmatchedPatterns.delete(matcher.pattern);
+                            }
+
+                            return pathMatches || previousValue;
+                        }, false)
+                        : matchers.some(matcher => matcher.match(relativePath));
+
+                    return matchesPattern && !configs.isFileIgnored(entry.path);
+                })
+            },
+            (error, entries) => {
+
+                // If the promise is already rejected, calling `resolve` or `reject` will do nothing.
+                if (error) {
+                    reject(error);
+                } else {
+                    resolve(entries);
+                }
+            }
+        );
     })).map(entry => entry.path);
 
     // now check to see if we have any unmatched patterns
@@ -655,9 +699,9 @@ class ESLintInvalidOptionsError extends Error {
 
 /**
  * Validates and normalizes options for the wrapped CLIEngine instance.
- * @param {FlatESLintOptions} options The options to process.
+ * @param {ESLintOptions} options The options to process.
  * @throws {ESLintInvalidOptionsError} If of any of a variety of type errors.
- * @returns {FlatESLintOptions} The normalized options.
+ * @returns {ESLintOptions} The normalized options.
  */
 function processOptions({
     allowInlineConfig = true, // ← we cannot use `overrideConfig.noInlineConfig` instead because `allowInlineConfig` has side-effect that suppress warnings that show inline configs are ignored.
@@ -675,7 +719,10 @@ function processOptions({
     overrideConfig = null,
     overrideConfigFile = null,
     plugins = {},
+    stats = false,
     warnIgnored = true,
+    passOnNoPatterns = false,
+    ruleFilter = () => true,
     ...unknownOptions
 }) {
     const errors = [];
@@ -759,7 +806,7 @@ function processOptions({
     if (typeof ignore !== "boolean") {
         errors.push("'ignore' must be a boolean.");
     }
-    if (!isArrayOfNonEmptyString(ignorePatterns) && ignorePatterns !== null) {
+    if (!isEmptyArrayOrArrayOfNonEmptyString(ignorePatterns) && ignorePatterns !== null) {
         errors.push("'ignorePatterns' must be an array of non-empty strings or null.");
     }
     if (typeof overrideConfig !== "object") {
@@ -768,6 +815,9 @@ function processOptions({
     if (!isNonEmptyString(overrideConfigFile) && overrideConfigFile !== null && overrideConfigFile !== true) {
         errors.push("'overrideConfigFile' must be a non-empty string, null, or true.");
     }
+    if (typeof passOnNoPatterns !== "boolean") {
+        errors.push("'passOnNoPatterns' must be a boolean.");
+    }
     if (typeof plugins !== "object") {
         errors.push("'plugins' must be an object or null.");
     } else if (plugins !== null && Object.keys(plugins).includes("")) {
@@ -776,9 +826,15 @@ function processOptions({
     if (Array.isArray(plugins)) {
         errors.push("'plugins' doesn't add plugins to configuration to load. Please use the 'overrideConfig.plugins' option instead.");
     }
+    if (typeof stats !== "boolean") {
+        errors.push("'stats' must be a boolean.");
+    }
     if (typeof warnIgnored !== "boolean") {
         errors.push("'warnIgnored' must be a boolean.");
     }
+    if (typeof ruleFilter !== "function") {
+        errors.push("'ruleFilter' must be a function.");
+    }
     if (errors.length > 0) {
         throw new ESLintInvalidOptionsError(errors);
     }
@@ -800,7 +856,10 @@ function processOptions({
         globInputPaths,
         ignore,
         ignorePatterns,
-        warnIgnored
+        stats,
+        passOnNoPatterns,
+        warnIgnored,
+        ruleFilter
     };
 }
 
@@ -887,7 +946,6 @@ function getCacheFile(cacheFile, cwd) {
 //-----------------------------------------------------------------------------
 
 module.exports = {
-    isGlobPattern,
     findFiles,
 
     isNonEmptyString,