Reevaluate the meta.docs.suggestion property

[bmish]

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: Docs: Add missing meta.docs.suggestion property in some examples #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: Fix: Throw error when rule is missing meta.docs.suggestion property #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 Fix: Throw error when rule is missing meta.docs.suggestion property #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

[nzakas]

Thanks for writing all of this up! I do think the fourth option is probably closest to what we want, though perhaps suggestions may be a better choice than suggestable, as the latter isn't a word. :) (Suggestible is a word, but I still think suggestions is clearer for most people.)

[nzakas]

TSC Summary: This issue outlines that we have documented a meta.docs.suggestions property in rules that appears to originally have been created to indicate when a rule has suggestions much like the meta.fixable property indicates if a rule is fixable. However, we don't rely on meta.docs.suggestions in any way, and do not enforce its usage to provide suggestions from rules. Additionally, all other current meta.docs.* properties are all optional, so this one seems out of place. There are several options but the most straightforward seems to be to create a new meta.suggestions property that, when set to true, enables rules to provide suggestions in the same way meta.fixable allows rules to provide fixes. This would be a breaking change but would ensure that both humans and tooling can easily tell when a rule provides suggestions.

TSC Question: How do we want to proceed here? And do we want to include this in v8.0.0 (somewhat related to #13349)?

[bmish]

Thanks for writing all of this up! I do think the fourth option is probably closest to what we want, though perhaps suggestions may be a better choice than suggestable, as the latter isn't a word. :) (Suggestible is a word, but I still think suggestions is clearer for most people.)

Perhaps we could call it hasSuggestions? That would make it more clear that this is a boolean property. I'm worried that suggestions sounds too much like the actual array of suggestion objects. In fact, suggestions is the same name used in unit tests to assert that the proper list of suggestions is reported, and I wouldn't want to create confusion with that.

[nzakas]

That’s fine with me. We can always finalize the wording on the implementation PR.

[bmish]

Shall I prepare an RFC and/or implementation PR with Option 4?

[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!

[bmish]

The implementation will be very similar to #14292 which I closed. It will contain:

• docs/developer-guide/working-with-rules.md
  • Rule Basics: Rename the meta.docs.suggestion property to meta.hasSuggestions and mention that this is required for suggetable rules
  • Update examples to show this new property
• lib/linter.js
  • Throw an error when the property is missing for suggestable rules
• fixtures/testers/rule-tester/suggestions.js
  • Add property to test fixtures
• tests/lib/linter/linter.js
  • Tests that exception is thrown properly
• tests/lib/rule-tester/rule-tester.js
  • Tests that exception is thrown properly
• Update property in core rules that provide suggestions

Does that sound good? If so, I'll open the implementation PR.

[nzakas]

@bmish that looks good to me. Thanks for offering!

[bmish]

Another addition to the implementation: I'd like to disallow / throw an exception when the old property meta.docs.suggestion is included in a rule in order to ensure that that property gets cleaned up (it would be confusing if a rule specified both the old property and the new replacement property).

[bmish]

I have opened #14573 with the implementation.