ESLINTJS-65 Remove decorated rules from ESLint plugin

[vdiez]

Changes:

• Decorated rules are not part of the ESLint plugin.
• All external eslint plugins are not part of eslint-plugin-sonarjs any longer.
• meta.ts can be modified and will never be overwritten by generate-meta
• generate-meta will now write to generated-meta.ts, which is imported by meta.ts
• A preliminary meta.ts will be autogenerated first time when creating a new rule. Done in JS-421 Fix new-rule script #4917
• The new available metadata will point which rules are original, external, or decorated.
• We generate rule indexes automatically for both the bridge and the ESLint plugin, no need to maintain the indexes manually
• All rules now contain a folder inside the rules folder, as we need the metadata to be visible for all rules.
• README.md lists not only the ESLint plugin rules, but also points to what rules the user should look for if they want to have the full SQ experience

Fixes JS-336 as well

[zglicz]

Added a few comments. It's hard to correctly review such a big PR

I hope I looked at all of the non-automated files. Also, I'd say it's a nice touch to add a bit more comprehensive PR summary, where you give some reasoning why you make certain decisions.

[zglicz]

what does it mean "they are not shipped"? In the end, if you use our plugin, you will have these rules running, no? Perhaps lets be more explicit, what it means in the plugin and in SonarJS.

[vdiez]

no, I have removed all decorated rules from our plugin, so if they use our plugin those rules, listed in the readme file at the very bottom, will not be available and the user needs to install those plugins if they want the same results as in SonarJS

[vdiez]

I changed the wording on the README, pls let me know if it's better now

[zglicz]

do you think this could be extracted into 'external/{library}' files? that way it's extracted a bit in the correct places.

[vdiez]

not sure I understand your point

[zglicz]

Could the modules in external/plugin.ts be exporting this method/constant? So in external/core.js you would have a method like: getExternalURL(key: string) and similarly in the other files like external/a11y.ts. As in, remove the switches and have these declared in the plugin modules themselves. But I'm fine with this as well.

[yassin-kammoun-sonarsource]

Great work!

I did a first pass and left some comments.
I might add more about the plugin's README.

[vdiez]

added a list of changes and goals of this PR

[yassin-kammoun-sonarsource]

Here, I am proposing a new version of the plugin README. You are free to discard my suggestions or adapt them as you wish. Nevertheless, I would like to share my rationale behind this proposition:

1. The section discussing ESLint and Sonar appears too late in the README. I believe this introduction should be moved to the top of the document. I have reformulated it to emphasize what users can expect from the rules offered by this ESLint plugin, such as accessibility and security vulnerabilities.
2. While GitHub README files do include a built-in table of contents, I'm not sure that many people are aware of it. The fact that we only realized that recently highlights that point. Therefore, I recommend including an explicit table of contents, as the GitHub version does not display by default. Additionally, for reference, ESLint also features its own table of contents.
3. I created a specific subsection about the TypeScript ESLint Parser. However, I'm not entirely sure of some details and would appreciate your clarification on this matter. If I understand correctly, the typescript-eslint/parser dependency is mandatory. Without it, users of this plugin may encounter runtime failures with rules that use the type-checker.
4. I added a new section titled "Feedback" to guide users to the Sonar community forum. While there is a link to the forum at the root of the repository, I believe users of this plugin will typically access the plugin's README rather than the root one. As a result, they may not know how to reach us. While handling community last week, I came across a user that was complaining about this.
5. While I really like it, I am starting to have mixed feelings about the "Rules" section of the README. I am not sure we should mix internal documentation intended for us developers with public documentation meant for users. We reference "ESLint rules" and "Improved ESLint rules" that are not part of eslint-plugin-sonarjs, which is irrelevant from the user's perspective. Unless I am mistaken, this README eventually ends up on the landing page of our plugin on npm.

eslint-plugin-sonarjs (new README)

eslint-plugin-sonarjs is an ESLint plugin maintained by Sonar, designed to help developers write Clean Code. It provides a subset of rules from SonarJS, an analyzer for JavaScript and TypeScript within the Sonar ecosystem. This plugin offers general-purpose rules for detecting code smells and bugs, as well as rules for other aspects of code quality, including testing, accessibility, and more. Additionally, it enhances code security by providing rules to report potential security vulnerabilities.

Table of Contents

1. Prerequisites
2. Installation
3. Usage
4. Configuration
5. SonarLint
6. Feedback
7. Rules

Prerequisites

The prerequisites for using this plugin depend on the ESLint version you are using:

• For ESLint 8, you need Node.js version >= 16.
• For ESLint 9, you need Node.js version that complies with (^18.18.0 || ^20.9.0 || >=21).

Installation

First, ensure that your project is configured with ESLint. If it is not, please follow the ESLint instructions to set it up.

To install the eslint-plugin-sonarjs, use the following npm command:

npm install eslint-plugin-sonarjs --save-dev # locally
npm install eslint-plugin-sonarjs -g         # globally

Usage

The usage of the eslint-plugin-sonarjs dependency depends on the ESLint version used by your project.

For ESLint 8

Add sonarjs to your .eslintrc file:

{
  "plugins": [
    "sonarjs"
  ],
  "extends": [
    "plugin:sonarjs/recommended-legacy"
  ]
}

For ESLint 9

Add sonarjs to your eslint.config.js file:

import sonarjs from "eslint-plugin-sonarjs";

export default [
  {
    plugins: {
      sonarjs
    },
    extends: [
      "plugin:sonarjs/recommended"
    ]
  }
];

TypeScript ESLint Parser

Several rules are designed for linting both JavaScript and TypeScript code, and some even rely on type checking through TypeScript. Therefore, you will need to install the @typescript-eslint/parser dependency and instruct ESLint to use this parser through the parserOptions property.

Configuration

This ESLint plugin provides a single configuration named recommended. This configuration enables most of the rules except for a few exceptions, and the rules are enabled with the error severity. If those exceptions make sense for your project, they can be enabled manually as follows:

{
  "rules": {
    "sonarjs/rule-name": "error"
  }
}

There is also another configuration named recommended-legacy that aims to be backward-compatible with ESLint 8, using the same rule configuration:

{
  "extends": ["plugin:sonarjs/recommended-legacy"]
}

SonarLint

As an alternative to using this ESLint plugin, you can use SonarLint. SonarLint is an IDE extension that helps you detect and fix quality issues as you write code. It provides a broader set of rules compared to the ESLint plugin, improved versions of ESLint rules, and additional features that enhance your linting experience.

Feedback

If you have any questions, encounter any bugs, or have feature requests, please reach out to us through the Sonar Community Forum.

Your messages will reach the maintainers of this GitHub repository.

Rules

Depending on what you decide, either the current contents of the "Rules" section or only the rules that are actually provided by our ESLint plugin.

[vdiez]

I think mentioning the rules that are missing is relevant for users looking for an experience equivalent to SonarJS but using ESLint, so they can install and enable the listed rules.

Thanks for the proposal, I'll do that tomorrow

[yassin-kammoun-sonarsource]

I think mentioning the rules that are missing is relevant for users looking for an experience equivalent to SonarJS but using ESLint, so they can install and enable the listed rules.

Ah ok, I think I misunderstood then. So this means that even ESLint rules or decorated rules can manually be enabled, right?

[vdiez]

yes, they can install other plugins and enable as many rules as they want, indeed

[vdiez]

I will handle the README on another PR, I don't want to have this branch for so long

[sonarqube-next]

Quality Gate passed

Issues
0 New issues
0 Fixed issues
0 Accepted issues

Measures
0 Security Hotspots
99.1% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube

[zglicz]

do you need this comment?

[yassin-kammoun-sonarsource]

Looks great!
Thank you for your efforts.