eslint 7.27.0 → 7.31.0

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

@@ -0,0 +1,452 @@
+/**
+ * @fileoverview Flat config schema
+ * @author Nicholas C. Zakas
+ */
+
+"use strict";
+
+//-----------------------------------------------------------------------------
+// Type Definitions
+//-----------------------------------------------------------------------------
+
+/**
+ * @typedef ObjectPropertySchema
+ * @property {Function|string} merge The function or name of the function to call
+ *      to merge multiple objects with this property.
+ * @property {Function|string} validate The function or name of the function to call
+ *      to validate the value of this property.
+ */
+
+//-----------------------------------------------------------------------------
+// Helpers
+//-----------------------------------------------------------------------------
+
+const ruleSeverities = new Map([
+    [0, 0], ["off", 0],
+    [1, 1], ["warn", 1],
+    [2, 2], ["error", 2]
+]);
+
+const globalVariablesValues = new Set([
+    true, "true", "writable", "writeable",
+    false, "false", "readonly", "readable", null,
+    "off"
+]);
+
+/**
+ * Check if a value is a non-null object.
+ * @param {any} value The value to check.
+ * @returns {boolean} `true` if the value is a non-null object.
+ */
+function isNonNullObject(value) {
+    return typeof value === "object" && value !== null;
+}
+
+/**
+ * Check if a value is undefined.
+ * @param {any} value The value to check.
+ * @returns {boolean} `true` if the value is undefined.
+ */
+function isUndefined(value) {
+    return typeof value === "undefined";
+}
+
+/**
+ * Deeply merges two objects.
+ * @param {Object} first The base object.
+ * @param {Object} second The overrides object.
+ * @returns {Object} An object with properties from both first and second.
+ */
+function deepMerge(first = {}, second = {}) {
+
+    /*
+     * If the second value is an array, just return it. We don't merge
+     * arrays because order matters and we can't know the correct order.
+     */
+    if (Array.isArray(second)) {
+        return second;
+    }
+
+    /*
+     * First create a result object where properties from the second object
+     * overwrite properties from the first. This sets up a baseline to use
+     * later rather than needing to inspect and change every property
+     * individually.
+     */
+    const result = {
+        ...first,
+        ...second
+    };
+
+    for (const key of Object.keys(second)) {
+
+        // avoid hairy edge case
+        if (key === "__proto__") {
+            continue;
+        }
+
+        const firstValue = first[key];
+        const secondValue = second[key];
+
+        if (isNonNullObject(firstValue)) {
+            result[key] = deepMerge(firstValue, secondValue);
+        } else if (isUndefined(firstValue)) {
+            if (isNonNullObject(secondValue)) {
+                result[key] = deepMerge(
+                    Array.isArray(secondValue) ? [] : {},
+                    secondValue
+                );
+            } else if (!isUndefined(secondValue)) {
+                result[key] = secondValue;
+            }
+        }
+    }
+
+    return result;
+
+}
+
+/**
+ * Normalizes the rule options config for a given rule by ensuring that
+ * it is an array and that the first item is 0, 1, or 2.
+ * @param {Array|string|number} ruleOptions The rule options config.
+ * @returns {Array} An array of rule options.
+ */
+function normalizeRuleOptions(ruleOptions) {
+
+    const finalOptions = Array.isArray(ruleOptions)
+        ? ruleOptions.slice(0)
+        : [ruleOptions];
+
+    finalOptions[0] = ruleSeverities.get(finalOptions[0]);
+    return finalOptions;
+}
+
+//-----------------------------------------------------------------------------
+// Assertions
+//-----------------------------------------------------------------------------
+
+/**
+ * Validates that a value is a valid rule options entry.
+ * @param {any} value The value to check.
+ * @returns {void}
+ * @throws {TypeError} If the value isn't a valid rule options.
+ */
+function assertIsRuleOptions(value) {
+
+    if (typeof value !== "string" && typeof value !== "number" && !Array.isArray(value)) {
+        throw new TypeError("Expected a string, number, or array.");
+    }
+}
+
+/**
+ * Validates that a value is valid rule severity.
+ * @param {any} value The value to check.
+ * @returns {void}
+ * @throws {TypeError} If the value isn't a valid rule severity.
+ */
+function assertIsRuleSeverity(value) {
+    const severity = typeof value === "string"
+        ? ruleSeverities.get(value.toLowerCase())
+        : ruleSeverities.get(value);
+
+    if (typeof severity === "undefined") {
+        throw new TypeError("Expected severity of \"off\", 0, \"warn\", 1, \"error\", or 2.");
+    }
+}
+
+/**
+ * Validates that a given string is the form pluginName/objectName.
+ * @param {string} value The string to check.
+ * @returns {void}
+ * @throws {TypeError} If the string isn't in the correct format.
+ */
+function assertIsPluginMemberName(value) {
+    if (!/[@a-z0-9-_$]+(?:\/(?:[a-z0-9-_$]+))+$/iu.test(value)) {
+        throw new TypeError(`Expected string in the form "pluginName/objectName" but found "${value}".`);
+    }
+}
+
+/**
+ * Validates that a value is an object.
+ * @param {any} value The value to check.
+ * @returns {void}
+ * @throws {TypeError} If the value isn't an object.
+ */
+function assertIsObject(value) {
+    if (!isNonNullObject(value)) {
+        throw new TypeError("Expected an object.");
+    }
+}
+
+/**
+ * Validates that a value is an object or a string.
+ * @param {any} value The value to check.
+ * @returns {void}
+ * @throws {TypeError} If the value isn't an object or a string.
+ */
+function assertIsObjectOrString(value) {
+    if ((!value || typeof value !== "object") && typeof value !== "string") {
+        throw new TypeError("Expected an object or string.");
+    }
+}
+
+//-----------------------------------------------------------------------------
+// Low-Level Schemas
+//-----------------------------------------------------------------------------
+
+
+/** @type {ObjectPropertySchema} */
+const numberSchema = {
+    merge: "replace",
+    validate: "number"
+};
+
+/** @type {ObjectPropertySchema} */
+const booleanSchema = {
+    merge: "replace",
+    validate: "boolean"
+};
+
+/** @type {ObjectPropertySchema} */
+const deepObjectAssignSchema = {
+    merge(first = {}, second = {}) {
+        return deepMerge(first, second);
+    },
+    validate: "object"
+};
+
+//-----------------------------------------------------------------------------
+// High-Level Schemas
+//-----------------------------------------------------------------------------
+
+/** @type {ObjectPropertySchema} */
+const globalsSchema = {
+    merge: "assign",
+    validate(value) {
+
+        assertIsObject(value);
+
+        for (const key of Object.keys(value)) {
+
+            // avoid hairy edge case
+            if (key === "__proto__") {
+                continue;
+            }
+
+            if (key !== key.trim()) {
+                throw new TypeError(`Global "${key}" has leading or trailing whitespace.`);
+            }
+
+            if (!globalVariablesValues.has(value[key])) {
+                throw new TypeError(`Key "${key}": Expected "readonly", "writable", or "off".`);
+            }
+        }
+    }
+};
+
+/** @type {ObjectPropertySchema} */
+const parserSchema = {
+    merge: "replace",
+    validate(value) {
+        assertIsObjectOrString(value);
+
+        if (typeof value === "object" && typeof value.parse !== "function" && typeof value.parseForESLint !== "function") {
+            throw new TypeError("Expected object to have a parse() or parseForESLint() method.");
+        }
+
+        if (typeof value === "string") {
+            assertIsPluginMemberName(value);
+        }
+    }
+};
+
+/** @type {ObjectPropertySchema} */
+const pluginsSchema = {
+    merge(first = {}, second = {}) {
+        const keys = new Set([...Object.keys(first), ...Object.keys(second)]);
+        const result = {};
+
+        // manually validate that plugins are not redefined
+        for (const key of keys) {
+
+            // avoid hairy edge case
+            if (key === "__proto__") {
+                continue;
+            }
+
+            if (key in first && key in second && first[key] !== second[key]) {
+                throw new TypeError(`Cannot redefine plugin "${key}".`);
+            }
+
+            result[key] = second[key] || first[key];
+        }
+
+        return result;
+    },
+    validate(value) {
+
+        // first check the value to be sure it's an object
+        if (value === null || typeof value !== "object") {
+            throw new TypeError("Expected an object.");
+        }
+
+        // second check the keys to make sure they are objects
+        for (const key of Object.keys(value)) {
+
+            // avoid hairy edge case
+            if (key === "__proto__") {
+                continue;
+            }
+
+            if (value[key] === null || typeof value[key] !== "object") {
+                throw new TypeError(`Key "${key}": Expected an object.`);
+            }
+        }
+    }
+};
+
+/** @type {ObjectPropertySchema} */
+const processorSchema = {
+    merge: "replace",
+    validate(value) {
+        if (typeof value === "string") {
+            assertIsPluginMemberName(value);
+        } else if (value && typeof value === "object") {
+            if (typeof value.preprocess !== "function" || typeof value.postprocess !== "function") {
+                throw new TypeError("Object must have a preprocess() and a postprocess() method.");
+            }
+        } else {
+            throw new TypeError("Expected an object or a string.");
+        }
+    }
+};
+
+/** @type {ObjectPropertySchema} */
+const rulesSchema = {
+    merge(first = {}, second = {}) {
+
+        const result = {
+            ...first,
+            ...second
+        };
+
+        for (const ruleId of Object.keys(result)) {
+
+            // avoid hairy edge case
+            if (ruleId === "__proto__") {
+
+                /* eslint-disable-next-line no-proto */
+                delete result.__proto__;
+                continue;
+            }
+
+            result[ruleId] = normalizeRuleOptions(result[ruleId]);
+
+            /*
+             * If either rule config is missing, then the correct
+             * config is already present and we just need to normalize
+             * the severity.
+             */
+            if (!(ruleId in first) || !(ruleId in second)) {
+                continue;
+            }
+
+            const firstRuleOptions = normalizeRuleOptions(first[ruleId]);
+            const secondRuleOptions = normalizeRuleOptions(second[ruleId]);
+
+            /*
+             * If the second rule config only has a severity (length of 1),
+             * then use that severity and keep the rest of the options from
+             * the first rule config.
+             */
+            if (secondRuleOptions.length === 1) {
+                result[ruleId] = [secondRuleOptions[0], ...firstRuleOptions.slice(1)];
+                continue;
+            }
+
+            /*
+             * In any other situation, then the second rule config takes
+             * precedence. That means the value at `result[ruleId]` is
+             * already correct and no further work is necessary.
+             */
+        }
+
+        return result;
+    },
+
+    validate(value) {
+        assertIsObject(value);
+
+        let lastRuleId;
+
+        // Performance: One try-catch has less overhead than one per loop iteration
+        try {
+
+            /*
+             * We are not checking the rule schema here because there is no
+             * guarantee that the rule definition is present at this point. Instead
+             * we wait and check the rule schema during the finalization step
+             * of calculating a config.
+             */
+            for (const ruleId of Object.keys(value)) {
+
+                // avoid hairy edge case
+                if (ruleId === "__proto__") {
+                    continue;
+                }
+
+                lastRuleId = ruleId;
+
+                const ruleOptions = value[ruleId];
+
+                assertIsRuleOptions(ruleOptions);
+
+                if (Array.isArray(ruleOptions)) {
+                    assertIsRuleSeverity(ruleOptions[0]);
+                } else {
+                    assertIsRuleSeverity(ruleOptions);
+                }
+            }
+        } catch (error) {
+            error.message = `Key "${lastRuleId}": ${error.message}`;
+            throw error;
+        }
+    }
+};
+
+/** @type {ObjectPropertySchema} */
+const sourceTypeSchema = {
+    merge: "replace",
+    validate(value) {
+        if (typeof value !== "string" || !/^(?:script|module|commonjs)$/u.test(value)) {
+            throw new TypeError("Expected \"script\", \"module\", or \"commonjs\".");
+        }
+    }
+};
+
+//-----------------------------------------------------------------------------
+// Full schema
+//-----------------------------------------------------------------------------
+
+exports.flatConfigSchema = {
+    settings: deepObjectAssignSchema,
+    linterOptions: {
+        schema: {
+            noInlineConfig: booleanSchema,
+            reportUnusedDisableDirectives: booleanSchema
+        }
+    },
+    languageOptions: {
+        schema: {
+            ecmaVersion: numberSchema,
+            sourceType: sourceTypeSchema,
+            globals: globalsSchema,
+            parser: parserSchema,
+            parserOptions: deepObjectAssignSchema
+        }
+    },
+    processor: processorSchema,
+    plugins: pluginsSchema,
+    rules: rulesSchema
+};

package/lib/config/rule-validator.js

@@ -0,0 +1,169 @@
+/**
+ * @fileoverview Rule Validator
+ * @author Nicholas C. Zakas
+ */
+
+"use strict";
+
+//-----------------------------------------------------------------------------
+// Requirements
+//-----------------------------------------------------------------------------
+
+const ajv = require("../shared/ajv")();
+
+//-----------------------------------------------------------------------------
+// Helpers
+//-----------------------------------------------------------------------------
+
+/**
+ * Finds a rule with the given ID in the given config.
+ * @param {string} ruleId The ID of the rule to find.
+ * @param {Object} config The config to search in.
+ * @returns {{create: Function, schema: (Array|null)}} THe rule object.
+ */
+function findRuleDefinition(ruleId, config) {
+    const ruleIdParts = ruleId.split("/");
+    let pluginName, ruleName;
+
+    // built-in rule
+    if (ruleIdParts.length === 1) {
+        pluginName = "@";
+        ruleName = ruleIdParts[0];
+    } else {
+        ruleName = ruleIdParts.pop();
+        pluginName = ruleIdParts.join("/");
+    }
+
+    if (!config.plugins || !config.plugins[pluginName]) {
+        throw new TypeError(`Key "rules": Key "${ruleId}": Could not find plugin "${pluginName}".`);
+    }
+
+    if (!config.plugins[pluginName].rules || !config.plugins[pluginName].rules[ruleName]) {
+        throw new TypeError(`Key "rules": Key "${ruleId}": Could not find "${ruleName}" in plugin "${pluginName}".`);
+    }
+
+    return config.plugins[pluginName].rules[ruleName];
+
+}
+
+/**
+ * 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.
+ */
+function getRuleOptionsSchema(rule) {
+
+    if (!rule) {
+        return null;
+    }
+
+    const schema = rule.schema || rule.meta && rule.meta.schema;
+
+    if (Array.isArray(schema)) {
+        if (schema.length) {
+            return {
+                type: "array",
+                items: schema,
+                minItems: 0,
+                maxItems: schema.length
+            };
+        }
+        return {
+            type: "array",
+            minItems: 0,
+            maxItems: 0
+        };
+
+    }
+
+    // Given a full schema, leave it alone
+    return schema || null;
+}
+
+//-----------------------------------------------------------------------------
+// Exports
+//-----------------------------------------------------------------------------
+
+/**
+ * Implements validation functionality for the rules portion of a config.
+ */
+class RuleValidator {
+
+    /**
+     * Creates a new instance.
+     */
+    constructor() {
+
+        /**
+         * A collection of compiled validators for rules that have already
+         * been validated.
+         * @type {WeakMap}
+         * @property validators
+         */
+        this.validators = new WeakMap();
+    }
+
+    /**
+     * Validates all of the rule configurations in a config against each
+     * rule's schema.
+     * @param {Object} config The full config to validate. This object must
+     *      contain both the rules section and the plugins section.
+     * @returns {void}
+     * @throws {Error} If a rule's configuration does not match its schema.
+     */
+    validate(config) {
+
+        if (!config.rules) {
+            return;
+        }
+
+        for (const [ruleId, ruleOptions] of Object.entries(config.rules)) {
+
+            // check for edge case
+            if (ruleId === "__proto__") {
+                continue;
+            }
+
+            /*
+             * If a rule is disabled, we don't do any validation. This allows
+             * users to safely set any value to 0 or "off" without worrying
+             * that it will cause a validation error.
+             *
+             * Note: ruleOptions is always an array at this point because
+             * this validation occurs after FlatConfigArray has merged and
+             * normalized values.
+             */
+            if (ruleOptions[0] === 0) {
+                continue;
+            }
+
+            const rule = findRuleDefinition(ruleId, config);
+
+            // 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));
+                }
+            }
+
+            const validateRule = this.validators.get(rule);
+
+            if (validateRule) {
+
+                validateRule(ruleOptions.slice(1));
+
+                if (validateRule.errors) {
+                    throw new Error(`Key "rules": Key "${ruleId}": ${
+                        validateRule.errors.map(
+                            error => `\tValue ${JSON.stringify(error.data)} ${error.message}.\n`
+                        ).join("")
+                    }`);
+                }
+            }
+        }
+    }
+}
+
+exports.RuleValidator = RuleValidator;

package/lib/eslint/eslint.js

@@ -514,6 +514,39 @@ class ESLint {
         return CLIEngine.getErrorResults(results);
     }
 
+    /**
+     * Returns meta objects for each rule represented in the lint results.
+     * @param {LintResult[]} results The results to fetch rules meta for.
+     * @returns {Object} A mapping of ruleIds to rule meta objects.
+     */
+    getRulesMetaForResults(results) {
+
+        const resultRuleIds = new Set();
+
+        // first gather all ruleIds from all results
+
+        for (const result of results) {
+            for (const { ruleId } of result.messages) {
+                resultRuleIds.add(ruleId);
+            }
+        }
+
+        // create a map of all rules in the results
+
+        const { cliEngine } = privateMembersMap.get(this);
+        const rules = cliEngine.getRules();
+        const resultRules = new Map();
+
+        for (const [ruleId, rule] of rules) {
+            if (resultRuleIds.has(ruleId)) {
+                resultRules.set(ruleId, rule);
+            }
+        }
+
+        return createRulesMeta(resultRules);
+
+    }
+
     /**
      * Executes the current configuration on an array of file and directory names.
      * @param {string[]} patterns An array of file and directory names.
@@ -552,9 +585,12 @@ class ESLint {
             ...unknownOptions
         } = options || {};
 
-        for (const key of Object.keys(unknownOptions)) {
-            throw new Error(`'options' must not include the unknown option '${key}'`);
+        const unknownOptionKeys = Object.keys(unknownOptions);
+
+        if (unknownOptionKeys.length > 0) {
+            throw new Error(`'options' must not include the unknown option(s): ${unknownOptionKeys.join(", ")}`);
         }
+
         if (filePath !== void 0 && !isNonEmptyString(filePath)) {
             throw new Error("'options.filePath' must be a non-empty string or undefined");
         }

package/lib/init/npm-utils.js

@@ -50,8 +50,7 @@ function findPackageJson(startDir) {
  */
 function installSyncSaveDev(packages) {
     const packageList = Array.isArray(packages) ? packages : [packages];
-    const npmProcess = spawn.sync("npm", ["i", "--save-dev"].concat(packageList),
-        { stdio: "inherit" });
+    const npmProcess = spawn.sync("npm", ["i", "--save-dev"].concat(packageList), { stdio: "inherit" });
     const error = npmProcess.error;
 
     if (error && error.code === "ENOENT") {