feat: add meta.defaultOptions

docs/src/extend/custom-rules.md

@@ -60,6 +60,8 @@ The source file for a rule exports an object with the following properties. Both
 
 * `schema`: (`object | array | false`) Specifies the [options](#options-schemas) so ESLint can prevent invalid [rule configurations](../use/configure/rules). Mandatory when the rule has options.
 
+* `defaultOptions`: (`array`) Specifies [default options](#option-defaults) for the rule. If present, any user-provided options in their config will be merged on top of them recursively.
+
 * `deprecated`: (`boolean`) Indicates whether the rule has been deprecated. You may omit the `deprecated` property if the rule has not been deprecated.
 
 * `replacedBy`: (`array`) In the case of a deprecated rule, specify replacement rule(s).
@@ -796,6 +798,51 @@ module.exports = {
 
 To learn more about JSON Schema, we recommend looking at some examples on the [JSON Schema website](https://json-schema.org/learn/miscellaneous-examples), or reading the free [Understanding JSON Schema](https://json-schema.org/understanding-json-schema/) ebook.
 
+#### Option Defaults
+
+Rules may specify a `meta.defaultOptions` array of default values for any options.
+When the rule is enabled in a user configuration, ESLint will recursively merge any user-provided option elements on top of the default elements.
+
+For example, given the following defaults:
+
+```js
+export default {
+ meta: {
+ defaultOptions: [{
+ alias: "basic",
+ }],
+ schema: {
+ type: "object",
+ properties: {
+ alias: {
+ type: "string"
+ }
+ },
+ additionalProperties: false
+ }
+ },
+ create(context) {
+ const [{ alias }] = context.options;
+
+ return { /* ... */ };
+ }
+}
+```
+
+The rule would have a runtime `alias` value of `"basic"` unless the user configuration specifies a different value, such as with `["error", { alias: "complex" }]`.
+
+Each element of the options array is merged according to the following rules:
+
+* Any missing value or explicit user-provided `undefined` will fall back to a default option
+* User-provided arrays and primitive values other than `undefined` override a default option
+* User-provided objects will merge into a default option object and replace a non-object default otherwise
+
+Option defaults will also be validated against the rule's `meta.schema`.
+
+**Note:** ESLint internally uses [Ajv](https://ajv.js.org) for schema validation with its [`useDefaults` option](https://ajv.js.org/guide/modifying-data.html#assigning-defaults) enabled.
+Both user-provided and `meta.defaultOptions` options will override any defaults specified in a rule's schema.
+ESLint may disable Ajv's `useDefaults` in a future major version.
+
 ### Accessing Shebangs
 
 [Shebangs (#!)](https://en.wikipedia.org/wiki/Shebang_(Unix)) are represented by the unique tokens of type `"Shebang"`. They are treated as comments and can be accessed by the methods outlined in the [Accessing Comments](#accessing-comments) section, such as `sourceCode.getAllComments()`.

lib/config/flat-config-schema.js

@@ -588,5 +588,6 @@ const flatConfigSchema = {
 
 module.exports = {
  flatConfigSchema,
+ assertIsRuleOptions,
  assertIsRuleSeverity
 };

lib/config/rule-validator.js

@@ -10,6 +10,7 @@
 //-----------------------------------------------------------------------------
 
 const ajvImport = require("../shared/ajv");
+const { deepMergeArrays } = require("../shared/deep-merge-arrays");
 const ajv = ajvImport();
 const {
  parseRuleId,
@@ -164,7 +165,10 @@ class RuleValidator {
 
  if (validateRule) {
 
- validateRule(ruleOptions.slice(1));
+ const slicedOptions = ruleOptions.slice(1);
+ const mergedOptions = deepMergeArrays(rule.meta?.defaultOptions, slicedOptions);
+
+ validateRule(mergedOptions);
 
  if (validateRule.errors) {
  throw new Error(`Key "rules": Key "${ruleId}":\n${
@@ -186,6 +190,10 @@ class RuleValidator {
  ).join("")
  }`);
  }
+
+ if (mergedOptions.length) {
+ config.rules[ruleId] = [ruleOptions[0], ...mergedOptions];
+ }
  }
  }
  }

lib/linter/linter.js

@@ -42,8 +42,9 @@ const
 const { getRuleFromConfig } = require("../config/flat-config-helpers");
 const { FlatConfigArray } = require("../config/flat-config-array");
 const { RuleValidator } = require("../config/rule-validator");
-const { assertIsRuleSeverity } = require("../config/flat-config-schema");
+const { assertIsRuleOptions, assertIsRuleSeverity } = require("../config/flat-config-schema");
 const { normalizeSeverityToString } = require("../shared/severity");
+const { deepMergeArrays } = require("../shared/deep-merge-arrays");
 const debug = require("debug")("eslint:linter");
 const MAX_AUTOFIX_PASSES = 10;
 const DEFAULT_PARSER_NAME = "espree";
@@ -828,14 +829,31 @@ function stripUnicodeBOM(text) {
 /**
  * Get the options for a rule (not including severity), if any
  * @param {Array|number} ruleConfig rule configuration
+ * @param {Object|undefined} defaultOptions rule.meta.defaultOptions
  * @returns {Array} of rule options, empty Array if none
  */
-function getRuleOptions(ruleConfig) {
+function getRuleOptions(ruleConfig, defaultOptions) {
  if (Array.isArray(ruleConfig)) {
- return ruleConfig.slice(1);
+ return deepMergeArrays(defaultOptions, ruleConfig.slice(1));
  }
- return [];
+ return defaultOptions ?? [];
+}
+
+/**
+ * Get the options for a rule's inline comment, including severity
+ * @param {string} ruleId Rule name being configured.
+ * @param {Array|number} ruleValue rule severity and options, if any
+ * @param {Object|undefined} defaultOptions rule.meta.defaultOptions
+ * @returns {Array} of rule options, empty Array if none
+ */
+function getRuleOptionsInline(ruleId, ruleValue, defaultOptions) {
+ assertIsRuleOptions(ruleId, ruleValue);
+
+ const [ruleSeverity, ...ruleConfig] = Array.isArray(ruleValue) ? ruleValue : [ruleValue];
 
+ assertIsRuleSeverity(ruleId, ruleSeverity);
+
+ return [ruleSeverity, ...deepMergeArrays(defaultOptions, ruleConfig)];
 }
 
 /**
@@ -982,14 +1000,28 @@ function createRuleListeners(rule, ruleContext) {
  * @param {LanguageOptions} languageOptions The options for parsing the code.
  * @param {Object} settings The settings that were enabled in the config
  * @param {string} filename The reported filename of the code
+ * @param {boolean} applyDefaultOptions If true, apply rules' meta.defaultOptions in computing their config options.
  * @param {boolean} disableFixes If true, it doesn't make `fix` properties.
  * @param {string | undefined} cwd cwd of the cli
  * @param {string} physicalFilename The full path of the file on disk without any code block information
  * @param {Function} ruleFilter A predicate function to filter which rules should be executed.
  * @returns {LintMessage[]} An array of reported problems
  * @throws {Error} If traversal into a node fails.
  */
-function runRules(sourceCode, configuredRules, ruleMapper, parserName, languageOptions, settings, filename, disableFixes, cwd, physicalFilename, ruleFilter) {
+function runRules(
+ sourceCode,
+ configuredRules,
+ ruleMapper,
+ parserName,
+ languageOptions,
+ settings,
+ filename,
+ applyDefaultOptions,
+ disableFixes,
+ cwd,
+ physicalFilename,
+ ruleFilter
+) {
  const emitter = createEmitter();
 
  // must happen first to assign all node.parent properties
@@ -1047,7 +1079,7 @@ function runRules(sourceCode, configuredRules, ruleMapper, parserName, languageO
  Object.create(sharedTraversalContext),
  {
  id: ruleId,
- options: getRuleOptions(configuredRules[ruleId]),
+ options: getRuleOptions(configuredRules[ruleId], applyDefaultOptions && rule.meta?.defaultOptions),
  report(...args) {
 
  /*
@@ -1395,6 +1427,7 @@ class Linter {
  languageOptions,
  settings,
  options.filename,
+ true,
  options.disableFixes,
  slots.cwd,
  providedOptions.physicalFilename,
@@ -1723,9 +1756,7 @@ class Linter {
 
  try {
 
- let ruleOptions = Array.isArray(ruleValue) ? ruleValue : [ruleValue];
-
- assertIsRuleSeverity(ruleId, ruleOptions[0]);
+ let ruleOptions = getRuleOptionsInline(ruleId, ruleValue, rule.meta?.defaultOptions);
 
  /*
  * If the rule was already configured, inline rule configuration that
@@ -1838,6 +1869,7 @@ class Linter {
  languageOptions,
  settings,
  options.filename,
+ false,
  options.disableFixes,
  slots.cwd,
  providedOptions.physicalFilename,

lib/rules/accessor-pairs.js

@@ -139,6 +139,12 @@ module.exports = {
  meta: {
  type: "suggestion",
 
+ defaultOptions: [{
+ enforceForClassMembers: true,
+ getWithoutSet: false,
+ setWithoutGet: true
+ }],
+
  docs: {
  description: "Enforce getter and setter pairs in objects and classes",
  recommended: false,
@@ -149,16 +155,13 @@ module.exports = {
  type: "object",
  properties: {
  getWithoutSet: {
- type: "boolean",
- default: false
+ type: "boolean"
  },
  setWithoutGet: {
- type: "boolean",
- default: true
+ type: "boolean"
  },
  enforceForClassMembers: {
- type: "boolean",
- default: true
+ type: "boolean"
  }
  },
  additionalProperties: false
@@ -174,7 +177,7 @@ module.exports = {
  }
  },
  create(context) {
- const config = context.options[0] || {};
+ const [config] = context.options;
  const checkGetWithoutSet = config.getWithoutSet === true;
  const checkSetWithoutGet = config.setWithoutGet !== false;
  const enforceForClassMembers = config.enforceForClassMembers !== false;

lib/rules/array-bracket-spacing.js

@@ -18,6 +18,8 @@ module.exports = {
  replacedBy: [],
  type: "layout",
 
+ defaultOptions: ["never"],
+
  docs: {
  description: "Enforce consistent spacing inside array brackets",
  recommended: false,

lib/rules/array-callback-return.js

@@ -215,6 +215,12 @@ module.exports = {
  meta: {
  type: "problem",
 
+ defaultOptions: [{
+ allowImplicit: false,
+ checkForEach: false,
+ allowVoid: false
+ }],
+
  docs: {
  description: "Enforce `return` statements in callbacks of array methods",
  recommended: false,
@@ -229,16 +235,13 @@ module.exports = {
  type: "object",
  properties: {
  allowImplicit: {
- type: "boolean",
- default: false
+ type: "boolean"
  },
  checkForEach: {
- type: "boolean",
- default: false
+ type: "boolean"
  },
  allowVoid: {
- type: "boolean",
- default: false
+ type: "boolean"
  }
  },
  additionalProperties: false
@@ -256,8 +259,7 @@ module.exports = {
  },
 
  create(context) {
-
- const options = context.options[0] || { allowImplicit: false, checkForEach: false, allowVoid: false };
+ const [options] = context.options;
  const sourceCode = context.sourceCode;
 
  let funcInfo = {

lib/rules/array-element-newline.js

@@ -19,6 +19,8 @@ module.exports = {
  replacedBy: [],
  type: "layout",
 
+ defaultOptions: ["always"],
+
  docs: {
  description: "Enforce line breaks after each array element",
  recommended: false,

lib/rules/arrow-body-style.js

@@ -19,6 +19,8 @@ module.exports = {
  meta: {
  type: "suggestion",
 
+ defaultOptions: ["as-needed"],
+
  docs: {
  description: "Require braces around arrow function bodies",
  recommended: false,
@@ -71,7 +73,7 @@ module.exports = {
  create(context) {
  const options = context.options;
  const always = options[0] === "always";
- const asNeeded = !options[0] || options[0] === "as-needed";
+ const asNeeded = options[0] === "as-needed";
  const never = options[0] === "never";
  const requireReturnForObjectLiteral = options[1] && options[1].requireReturnForObjectLiteral;
  const sourceCode = context.sourceCode;

lib/rules/arrow-parens.js

@@ -35,6 +35,8 @@ module.exports = {
  replacedBy: [],
  type: "layout",
 
+ defaultOptions: ["always"],
+
  docs: {
  description: "Require parentheses around arrow function arguments",
  recommended: false,
@@ -51,8 +53,7 @@ module.exports = {
  type: "object",
  properties: {
  requireForBlockBody: {
- type: "boolean",
- default: false
+ type: "boolean"
  }
  },
  additionalProperties: false