Reevaluate the `meta.docs.suggestion` property
See original GitHub issueThe 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:
- 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).
- Its name and location are inconsistent with a related property
meta.fixable
. - 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.
- 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
- 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
- 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
- Rename the property to
meta.suggestable
for consistency withmeta.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
Issue Analytics
- State:
- Created 2 years ago
- Comments:10 (10 by maintainers)
Top GitHub Comments
I have opened #14573 with the implementation.
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 withhasSuggestions
, 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!