Reevaluate the `meta.docs.suggestion` property

The problem you want to solve.

There is a rule property meta.docs.suggestion mentioned in the Rule Basics documentation that was added along with the Suggestions API / Suggestions RFC:

suggestion (boolean) specifies whether rules can return suggestions (defaults to false if omitted)

There are a few potential problems with this property:

1. It is missing from some of ESLint’s examples / test cases depicting usage of the suggestions API (more discussion in: https://github.com/eslint/eslint/pull/14298).
2. Its name and location are inconsistent with a related property meta.fixable.
3. Its presence is not enforced, so humans and tooling cannot reliably use it for determining whether a rule provides suggestions (as opposed to meta.fixable whose presence is enforced for autofixable rules) (more discussion in: https://github.com/eslint/eslint/pull/14292).

Use cases for having a convenient static property to determine which rules are suggestable:

• Ability to quickly compile a list of suggestable rules
• Ability to write tests that suggestable rules specify that they are suggestable in their documentation
• TODO: add any other ideas here

Note that ESLint itself doesn’t currently need to know which rules are suggestable (provide suggestions), whereas it does need to know which rules are fixable, so differences between meta.docs.suggestion and meta.fixable could be justified if we wanted to keep meta.docs.suggestion as an optional property (as opposed to meta.fixable which is a required property).

Your take on the correct solution to the problem.

There are several potential solutions here of varying size.

1. Keep meta.docs.suggestion as an optional property, fully document it, and add a lint rule eslint-plugin/require-meta-docs-suggestion for those wishing to enforce its presence.
   • Maintains the status quo, no disruption to anyone
   • The property would still be of limited usefulness as we can’t assume plugin rules would provide it
2. Keep meta.docs.suggestion, and begin to enforce its presence as a required property for suggestable rules. Implementation in https://github.com/eslint/eslint/pull/14292.
   • Ensures that humans and tooling have a reliable means of determining which rules are suggestable
   • But now there would be a noticeable naming/location inconsistency between this property and meta.fixable which would both be required properties
   • This is a breaking change that requires a one-line change in all rules that forgot to specify this property
3. Remove the meta.docs.suggestion property entirely and do not add a replacement for it.
   • Simplifies the API by removing a potentially unnecessary property
   • But now there’s no recommended way to determine what rules provide suggestions
4. Rename the property to meta.suggestable for consistency with meta.fixable, and enforce its presence for suggestable rules.
   • Ensures that humans and tooling have a reliable means of determining which rules are suggestable
   • Cleans up the API by addressing the naming/location inconsistency with meta.fixable
   • This is a breaking change that requires a one-line change in all suggestable rules

My preferred solution is 4 because it yields the most useful and consistent end-result, although this is also the most disruptive change, so I’m interested to hear what others prefer.

Are you willing to submit a pull request to implement this change?

Yes

CC the original RFC/PR author: @ilyavolodin @wdoug

[bmish]

I have opened #14573 with the implementation.

[btmills]

Coming out of Thursday’s TSC meeting, we’re all aligned around option 4. We discussed suggestions in the meeting since that was the latest idea at the time, but I’d also be fine with hasSuggestions, and like nzakas said, the name is easy to change in the PR.

Since this will be a breaking change, we’ll want to include this in a blog post prior to the v8.0.0 release to give everyone a heads up, and the PR should be included in at least one beta release to give plugin authors time to change the property and ship a new release before v8.0.0 final.

Normally we do RFCs for breaking changes, but hopefully we can use fixable as precedent for the implementation of this property so we don’t have to do a full RFC here. Before you submit an implementation PR, can you leave a comment here outlining what the PR will need to include? That’ll give everyone a chance to look the plan over and make sure we’ve thought of everything before you dive in on the implementation. Thanks for working on this @bmish!