Feature proposal: Indicate when a rule option in the user's config matches the default value for the rule option

[scottohara]

(Elaborates further on eslint/eslint#19182)

As of eslint v9.15.0, many (most? all?) rules now come with meta.defaultOptions, providing the ability to programatically determine the default option values for a given rule (see eslint/eslint#17656).

To assist users in keeping minimal, maintainable eslint configs, I would like to propose an enhancement to the config inspector that leverages this newly available rule metadata.

Specifically: have the config inspector indicate when a rule option in a user config matches the default value for that rule.
The user may choose to remove the redundant option from their config.

Below is a straw man on how such a feature might be implemented.

Rule item 'has options' indicator

The first potential change would be to the dot that appears in the upper-right hand corner of a rule item.

This dot (which takes on the color of the rule level: red for Error level, orange for Warn, grey for Off) is conditionally displayed by RuleLevelIcon.vue based on the hasOptions prop (which is set by ruleStates[idx].options?.length; that is: if the rule state has any options).

If it is determined that the rule state not only has options, but some of those options are redundant because they match the rule option’s default value, show a slightly different indicator.

I’ll leave it to the UI designers to consider what would be appropriate here, but it could be something as simple as changing the dot color (for example: to a blue dot):

This may require passing a new prop to the RuleLevelIcon.vue component, such as hasRedundantOptions?: boolean.

Shiki highlighted options

The next potential change is arguably the core feature of this proposal, which concerns the popover that displays the rule state options.

The goal here is to somehow visually indicate when a given rule option matches the default for the rule.

Shiki has support for decorations, so the first step would be to determine which option value(s) need to be decorated.

If the user’s version of eslint is v9.15.0 or higher, the assumption is that payload.rules[name].meta.defaultOptions should be present if the rule has default options.

Calculate the intersection of ruleStates[idx].options ∩ rules[name].meta.defaultOptions (where the both the key & value matches), and use this information to apply a Shiki decoration such as:

Note the option values have text-decoration: line-through , and the message below the Shiki block explains why.

Again, I would defer to the UI designers to decide on the most appropriate way of conveying this; the above is just a straw man.

Bonus change

One further (optional) change might be to provide some way of filtering rules that contain redundant options, similar to filtering recommended/fixable/deprecated rules.

This is more of a quality-of-life change, so I could understand if it’s a step too far.

For completeness, here’s an example of what it could look like:

Note the blue “13 rules have redundant options” button, and the “Redundant options” radio button.

I'd love to hear any feedback on whether this would be a useful addition to the inspector. If so, I would be willing to have a stab at implementing it.

[scottohara]

I was keen to see whether the above proposal would be achievable, and I ended up creating a working version here:
scottohara@ca6463d

I've opted not to create a pull request at this stage without some sort of indication from the maintainers that they would be receptive of such a change. Happy to do so if advised.

(Note: I'm not a Vue.js developer, and this potentially being my first contribution to the project, it is highly likely that some things will need to be modified)

The changes themselves are fairly minimal.

Detecting rule options that are redundant

The main addition is a new /app/composables/options.ts file, that exports a deepCompareOptions(option, defaultOptions) function. As the name suggests, this function deeply compares the rule options from the user's config against the default options for that rule.
If it finds any where the user-supplied value matches the rule's default value, it alters the user's value in a very specific (albeit, a bit hacky) way: it wraps the user-supplied value in 3-part array.

e.g.

// Original value
{
  enforceForClassMembers: true
}

// Wrapped value
{
  enforceForClassMembers: ["--", true, "--"]
}

The reason for this is that we need some way to indicate that the value matches the default, while preserving the original type & value of the option. The "--" boundary markers give me something to later match on with a regex (see below).

Highlighting those redundant options in the Shiki component

It turns out that Shiki provides a number of common transformers, one of which enables marking lines added or removed using a // [!code ] common at the end of the line:

- this line is removed  // [!code --]
+ this line is added    // [!code ++]

However, the rule options are a JS object that is stringified and the quotes stripped before geing passed to shiki's codeToHtml() function. There's no easy way to append a code comment to properties of an object, so we need to add these transformer hints after the object is converted to a string, but before it is passed to Shiki.

Hence the weird wrapping of values in the 3-part array above. This gives me something that a regex can find & replace in the string.

In /app/composable/strings.ts, there is a new transformDiff(code) function that searches for the pattern ["--", value, "--"] and replaces it with value, // [!code --].

If there's a better approach to this, I'd love to hear it, as it does feel a bit hacky.

Finally, the <RuleStateItem> component calls this function with the result from stringifyUnquoted(options) when rendering the <Shiki> component.

I also had to add a style to global.css for how to style this (opting for text-decoration: line-through), as the Shiki transformers themselves don't apply any styles.

Blue dot to indicate rules that have redundant options

The final change was to the <RuleLevelIcon> component to make the has-options dot in the upper-right corner blue when the rule has options that are potentially redundant.

And that's pretty much it. The only other change was to upgrade to [email protected] so that the meta.defaultOptions is available to use.

I hope this is useful, and I hope I haven't overstepped here by working on this before getting the nod from a maintainer.

I would be happy to convert this discussion idea to an issue, and submit the associated pull request as a next step.

[nzakas]

Ping @antfu for thoughts.

[scottohara]

Thanks for the initial positive signs on this.

For what it's worth, I've already used the new feature in my fork to successfully identify & assist in trimming redundant options from my own configs and it was a great help (but I would say that, wouldn't I? 😉 ).

The only minor issue that still needs some further work is a false-positive when a rule takes multiple options, and the first option is redundant, but later options are not.

In this case, the first option shouldn't be suggested for removal as it would break the positional nature of the options.

An example from my own config is:

"arrow-body-style": ["error", "as-needed", { requireReturnForObjectLiteral: false }]

The string option "as-needed" is the default for the rule, but the requireReturnForObjectLiteral has a default of true and I've set it to false.

The config inspector erroneously suggests removing the "as-needed" string:

So that is something I'll need to address.

[antfu]

I love this idea, and thanks for those great proposal UI screenshots, that helps a lot on understanding your idea!

From the high level, I'd raise the question of how much users want to remove the options if they are the same as the default. While they would behave exactly the same by removing the options, the difference is that it would lose a bit of the explicitness and hand the control to the rule's default (which might be changed). So I am more wondering our stand here, if it's We just let you know your options are the same as the default or They are the same, and you should remove your options (as a net-negative thing).

That would affect how strong we want to show it in the UI, like using ⚠️ or ℹ️, having an option to ignore them or not.

About the UI of line-through options, it looks to me more like "Invalid Options" than "The same as default". I think maybe decrease the opacity would be a better presentation.

I am also not sure about partially marking for some properties in an object, as it deps on the rule implementation, some might use "override" some might use "merge" to handle the object options. I think for those cases, it might be better to just have a tab to show the default options than doing too fine-grain comparison (better leaving that to users)

[scottohara]

That’s great insight, and on reflection I think you’re absolutely right that striking through the options and suggesting their removal may be too strong.

I do like the idea of a more subtle indicator, or lowering the opacity.

[nzakas]

Just keep in mind that lower opacity might not be apparent to people with any kind of visual disability. I'd be more in favor of an icon for that reason.

[scottohara]

In light of the feedback (thank you!), I have made two changes below.

Note

Please let me know if, at this point, it would be preferable to create a draft PR for this so that further discussion & iteration on the feature happens there.

Feedback

@antfu it might be better to just have a tab to show the default options than doing too fine-grain comparison (better leaving that to users)

Response

Not sure if this is exactly what you had in mind, but here is a version that includes buttons in the rule state popover for toggling between showing the configured options (as before) and default options.

Example showing default options:

Feedback

@antfu About the UI of line-through options, it looks to me more like "Invalid Options" than "The same as default". I think maybe decrease the opacity would be a better presentation.

@nzakas Just keep in mind that lower opacity might not be apparent to people with any kind of visual disability. I'd be more in favor of an icon for that reason.

Response

I too think an icon would work best here, but for expediency, for now I simply replaced the line-through style with italics and a mild reduction in opacity (to 75%). Happy to explore further the idea of an appropriate icon if preferred.

I also changed the text below the options from

Values crossed-out may be removed as they match the default for the rule

to simply

Options italicized match the default for the rule

[antfu]

Looks great! Feel free to drop a PR so we could iterate the details. Thanks!

[scottohara]

Merged in #110

🎉