eslint-index

[wagerfield]

I have created a ESLint utility module inspired by eslint-find-rules that I thought you might find useful for eslint-config-airbnb-base and eslint-config-airbnb.

The module is called eslint-index and you can read the full documentation on npm.

eslint-index provides a great deal of functionality including:

• List all available rules declared by ESLint and any plugins you have included
• Colour code rules depending on their status:
  • omitted (not declared anywhere in you ESLint config file)
  • 0|off (declared, but set to 0|off)
  • 1|warn
  • 2|error
• Display links to the rule documentation page next to each rule
• Filter/reject rules by their status and/or their group
  • status is as described above (omitted|off|warn|error)
  • group is eslint for the core ESLint rules or the name of any of your plugins like react|import|flowtype
• Format the output as a number or a table to get an overview of your rule settings
• Rules that have been marked as deprecated are removed from all outputs
• All of the above filters and formatting can be combined, for example:
  • filter omitted and off rules, output them as a list and display the rule doc links alongside
  • filter eslint rules and display the rule setting counters in a table

I wrote this plugin to aid the development of my own ESLint config settings and found it incredibly useful for keeping track of everything. I hope you find this module useful and please do let me know if you have any ideas on how to improve it.

[ljharb]

@wagerfield how does this work in a repo with multiple nested eslintrc files?

Is there any chance your tool could be used to report when a non-top-level config override isn't needed? (ie, when if removed, additional warnings wouldn't appear)

[wagerfield]

@ljharb right now eslint-index only parses the .eslintrc file that is provided as the first argument to the CLI—there is no support for multiple config files (you have to parse them independently):

eslint-index .eslintrc
eslint-index ./nested/path/to/.eslintrc

If I understand correctly, you would like an interface for flagging when override rules within nested .eslintrc files are not needed—due to parent .eslintrc files specifying the same rule settings.

Example:

some-project
- .eslintrc // root config file
  > semi: [ 'error', 'never' ]
  > no-console: 'error'
- some-nested-folder
  - .eslintrc // nested config file
    > semi: [ 'error', 'never' ] // identical to a parent config rule setting » redundant
    > no-console: 'off' // overrides parent config rule setting

Implementing an interface for this is certainly possible, though it would be helpful to know how you might want to use such a feature and what effect it would have on the rest of the tool.

One option would be to specify a project directory rather than a specific .eslintrc file and then have the tool search for all .eslintrc files within that directory and any nested directories. With this directory map of .eslintrc files, the tool could recursively loop downwards through the tree and identify which rule overrides are identical to those already in scope and flag these to the console.

eslint-index . // search and build a dir map of all .eslintrc files and parse them accordingly

Alternatively a more manual approach (that could work in conjunction with the above) would allow for a number of .eslintrc files to be passed as arguments to the CLI and have the tool perform the same logic as above.

eslint-index .eslintrc path/to/nested/.eslintrc

If I add the ability to specify both .eslintrc files and directories, a combination of the above could be achieved via the CLI:

eslint-index .eslintrc nested/dir/to/search

A side effect of this would mean that the output would need to branch for each .eslintrc file. So if you're wanting to output the rules in a list, table or number—a list, table or number would need to be generated for each file. This presents a number of problems or options depending on how you look at it—which could start to make the tool a little cumbersome and complex.

With multiple .eslintrc files now in play, would you expect the output for each of the config files (be it a list, table or number) to reflect the rules specified in each .eslintrc file—irrespective of parent config files or would you want the outputs to inherit the settings—applying the overrides? I could introduce a flag for this to allow for both behaviours—and perhaps this is the best option.

Please do let me know what your thoughts are on all this and I can go about implementing this functionality.

[ljharb]

I'm not looking for duplicated rule overrides - I'm looking for unnecessary ones. In other words, given s project dir, which non-top-level rule overrides could I remove without making the linter fail?

[wagerfield]

When you refer to non-top-level rule overrides, do you mean those that are specified in .eslintrc files that are not at the root of your project?

This tool does not run your config[s] against your source code. All eslint-index does is parse an .eslintrc file and compare it against all available rules for both ESLint and any plugins you have added and specified in your config's extends value.

In order to achieve what you are suggesting, the tool would need to:

1. Gather (or be provided with) a config file
2. Parse the config file to gather all the rules you have specified
3. Run the config file against your source code (through ESLint)
4. Incrementally disable rules (setting them to off|0) and running the modified config against your code again and again
5. Gather any rules that triggered a linting error

Is that correct?

[ljharb]

Correct - that's what i'm hoping for :-)

Absent that, this tool might still be very useful, but I haven't yet grasped what specific problem it solves for me.

[wagerfield]

I developed the tool to assist me in writing a config for my company (eslint-config-supermind). With so many rules available in ESLint itself plus all the rules provided by plugins, I found it difficult to keep track of which rules I had used and which ones I hadn't. This became all the more difficult when upgrading eslint and any plugins—I wouldn't know what new rules had been added.

eslint-find-rules went a long way in helping with this, but I felt it lacked the granular functionality I desired—so I developed eslint-index. Being able to filter rules by status (omitted|off|warn|error), by plugin (react|jsx-a11y) or the core eslint rules and having doc urls outputted alongside rules in the console has been very useful to me.

For example, if I upgrade eslint or any plugins and want to see which rules I haven't specified (because they are new) and for these omitted rules, display links to the docs alongside, I can do:

eslint-index .eslintrc.js --status omitted --docs