feat: Support for meta.defaultOptions on rules

[JoshuaKGoldberg]

Summary

This RFC proposes recursively defaulting rule options based on the rules schema. The behavior changes are that ESLint will now recursively creates {} objects for rule options. Doing so enhances the core Ajv useDefaults for easier rule options defaults.

Related Issues

• Issue: Change Request: Attach default options as an object to rules eslint#17448
• Reference implementations:
  • [Reference] feat!: factor in schema defaults for rule options eslint#17580
  • feat: add meta.defaultOptions eslint#17656

[ljharb]

this is a lot to page in, but is there a reason the rule schema can't provide the defaults via default, which is part of JSON Schema?

[mdjermanovic]

this is a lot to page in, but is there a reason the rule schema can't provide the defaults via default, which is part of JSON Schema?

Rule schemas can already provide defaults via default. This already works everywhere except at the top level but we could fix that.

The concern with using default is that the behavior is specific to Ajv. While the default keyword is indeed part of the JSON Schema, the specification doesn't dictate how it should be used in the validation process. In fact, the recommendation is not to use it in the validation process ("This value is not used to fill in missing values during the validation process"):

https://json-schema.org/understanding-json-schema/reference/generic.html#annotations

[bradzacher]

As I mentioned on the issue the big problem I've found with the default keyword in the schema is that is really not well handled by Ajv.

Additionally from a type-checker point of view its nearly impossible to strictly type the default value beyond trivial cases.

Finally I also find it can lead to really ambiguous schemas. For example what is the result from this schema:

const schema = {
  type: "object",
  properties: {
    prop: {
      oneOf: [
        { type: "string", default: "foo" },
        { type: "string", default: "bar" },
      ],
    }
  }
};

What does this validate to if I pass it {}? I have no idea!

It's a very vague, wishy-washy way to specify defaults - which isn't what you want.

Which is why (as I mentioned in the issue) we chose an entirely separate property in our typed rule utils for ts-eslint. There's nothing ambiguous or unclear about defaultOption: [{prop: "foo"}] and it's a cinch to validate that the default value is of the correct structure (eg does it pass the schema) and its also a cinch to typecheck it to ensure its of the correct structure.

Thats why personally I think that's the direction we would want to head down here.

[nzakas]

In general, I'm not a fan of piggybacking on JSON Schema for this. See my comment for more.

[JoshuaKGoldberg]

I threaded the discussion on meta.defaultOptions vs. recursive schema defaults here: https://github.com/eslint/rfcs/pull/113/files#r1331794511

[bmish]

Heads up that I implemented a basic version of rule option lists in bmish/eslint-doc-generator#481. It currently pulls option defaults from the schema. I imagine we can just switch it to use meta.defaultOptions whenever a rule provides the new property.

[nzakas]

Thanks, I like this proposal a lot better. I left some comments on a few points but overall I think this is looking good.

[nzakas]

I'm happy with the current state of this RFC. 👍

[mdjermanovic]

What if the rule schema has different object schemas in oneOf/anyOf, for example as in prefer-destructuring. The default for this would be an object with VariableDeclarator and AssignmentExpression properties, but when user config provides the other alternative with array and object properties, merging would result in an object with a mix of properties that would fail validation. Is this a case where the rule should not use meta.defaultOptions?

[bradzacher]

In general the advice we give when using the current ts-eslint tooling is that if you've got some complex options schema - eg oneOf where the schemas are truly disjoint like your example, or rules like @typescript-eslint/ban-types - they are just usecases where the standard logic cannot apply and thus you need to write your own options merging logic.

[nzakas]

I think at this point we should be discouraging the use of oneOf and anyOf. We ended up doing this in core rules because we didn't realize just how many exceptions and options people would want on rules, so early rules would often just use a string value as an option. In order to allow more options, we'd also allow an object. In general, I think we should be encouraging folks to always use an object with multiple properties for their rule options and avoid oneOf and anyOf in their schemas.

[JoshuaKGoldberg]

I think we should be encouraging folks to always use an object with multiple properties for their rule options and avoid oneOf and anyOf in their schemas.

Aha! typescript-eslint/typescript-eslint#6040. I would be interested in filing an issue/discussion on ESLint core to discuss establishing this in core development docs.

[ljharb]

Even with that as a constraint, i'd still have many use cases for anyOf/oneOf, because there are often multiple disjoint sets of options that may or may not be mutually exclusive.

[nzakas]

@ljharb you can always ignore recommendations. I just think it's helpful to give people guardrails that cover the 80% case. If you fall into the 20% case, then void the warranty and do what you need to. I think it's fine for the 20% case to not get the 80% case DX.

[JoshuaKGoldberg]

Can you provide some examples?

[ljharb]

@JoshuaKGoldberg for example, https://github.com/jsx-eslint/eslint-plugin-react/blob/9da1bb0f4aa44849b56e8c2064afd582ea8b36f8/lib/rules/jsx-indent-props.js#L64-L71 - that object property takes a number or two enum values.

https://github.com/jsx-eslint/eslint-plugin-react/blob/9da1bb0f4aa44849b56e8c2064afd582ea8b36f8/lib/rules/jsx-max-props-per-line.js#L39-L70 is more complex; you can specify a maximum with single and/or multi, xor you can specify a maximum with "when".

There's a bunch more in this plugin, and I haven't looked at the other two yet, but suffice to say it's pretty much impossible to avoid with a complex rule that evolves over time.

[mdjermanovic]

In the PoC, it's possible to provide the default options that are invalid for the schema because merging happens after the validation of options.

For example, ignoreIMports is invalid property name (typo uppercase M).

[nzakas]

This seems like something that can be worked out during the implementation phase. I'd recommend we move into Final Commenting now. What do you think?

[mdjermanovic]

Works for me, I'd just like to clarify #113 (comment) as that may affect this and I'm not sure whether the intent was to always pass raw or merged options to Ajv validations.

[nzakas]

Yup, that's what the final commenting period is for: small edits and clarifications. Because we're aligned on the overall approach I think we're ready.

[mdjermanovic]

Note that this is different from the current approach with Ajv defaults, where FlatConfigArray applies them directly in the config objects.

For example, currently:

// eslint.config.js
module.exports = [{
    rules: {
        camelcase: ["error", {}]
    }
}];

$ npx eslint --print-config foo.js
{
  "languageOptions": {
    "ecmaVersion": "latest",
    "sourceType": "module",
    "parser": "[email protected]",
    "parserOptions": {},
    "globals": {}
  },
  "plugins": [
    "@"
  ],
  "rules": {
    "camelcase": [
      2,
      {
        "ignoreDestructuring": false,
        "ignoreImports": false,
        "ignoreGlobals": false
      }
    ]
  }
}

After this change, it would be:

$ npx eslint --print-config foo.js
{
  "languageOptions": {
    "ecmaVersion": "latest",
    "sourceType": "module",
    "parser": "[email protected]",
    "parserOptions": {},
    "globals": {}
  },
  "plugins": [
    "@"
  ],
  "rules": {
    "camelcase": [
      2,
      {}
    ]
  }
}

An advantage of applying defaults in FlatConfigArray is performance, as config-array caches config objects so the defaults are not applied again for each file being linted.

Would it make sense to apply meta.defaultOptions in FlatConfigArray rather than when linting each file? Aside from possible performance gains, an observable difference would be in the output of --print-config which would show the final merged options (which seems useful, though it may be confusing as the output wouldn't match what user sees in their config file).

[JoshuaKGoldberg]

This makes a lot of sense to me, thanks. I implemented the logic inside RuleValidator's validate() method in eslint/eslint#17656.

https://github.com/eslint/eslint/actions/runs/6939046423/job/18875742661?pr=17656 shows finding two typos in rule default options (fixed in 629f691c7):

     Error: Key "rules": Key "accessor-pairs": 	Value {"enforceForClassMembers":true,"getWithoutGet":false,"setWithoutGet":true} should NOT have additional properties.

     Error: Key "rules": Key "camelcase": 	Value {"allow":[],"ignoreDestructuring":false,"ignoreGlobals":false,"ignoreIMports":false,"properties":"always"} should NOT have additional properties.

Also updated eslint/eslint#17656 to mostly apply default options through config-validator and rule-validator. There are a few remaining tests I haven't had the time to stamp out just yet, I think it still functions as a general proof of concept.

[nzakas]

Moving to Final Commenting. @JoshuaKGoldberg please take a look at @mdjermanovic's request for clarification.

[nzakas]

It looks like we've got most of the high-levels details nailed down, so merging. We can work through edge cases and implementation concerns on the implementation PR.

[Rec0iL99]

It looks like we've got most of the high-levels details nailed down, so merging.

@nzakas did you intend on merging this?

[nzakas]

Oops yes! My mistake. Thanks for catching this.