JS-1452 Document ProfileRegistrar for default Sonar way activation (#6592)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: vdiez

docs/custom-rules/CUSTOM_RULES_API_CHANGELOG.md

@@ -25,6 +25,7 @@ git show <commit-hash> --stat
 - `sonar-plugin/api/src/main/java/org/sonar/plugins/javascript/api/`
   - `EslintHook.java` - New hook interface (10.23.0+)
   - `EslintHookRegistrar.java` - Hook registration (10.23.0+)
+  - `ProfileRegistrar.java` - Default profile activation SPI (10.22.0+)
   - `EslintBasedCheck.java` - Check interface (deprecated 11.6.0)
   - `JavaScriptCheck.java` - Marker interface (deprecated 11.6.0)
   - `CustomRuleRepository.java` - Rule repository interface
@@ -107,12 +108,13 @@ public Set<org.sonar.plugins.javascript.api.Language> compatibleLanguages() {
 
 ### SonarJS 10.22.0 (March 2025)
 
-| Change                                  | Details                                     | Commit        |
-| --------------------------------------- | ------------------------------------------- | ------------- |
-| ✅ `Language` enum added (standalone)   | `org.sonar.plugins.javascript.api.Language` | `2f9168ca008` |
-| ✅ `compatibleLanguages()` method added | New method in `CustomRuleRepository`        | `2f9168ca008` |
-| ⚠️ `languages()` method deprecated      | Use `compatibleLanguages()` instead         | `2f9168ca008` |
-| 🔄 `CustomRuleRepository` undeprecated  | Interface itself is no longer deprecated    | `2f9168ca008` |
+| Change                                  | Details                                                            | Commit        |
+| --------------------------------------- | ------------------------------------------------------------------ | ------------- |
+| ✅ `Language` enum added (standalone)   | `org.sonar.plugins.javascript.api.Language`                        | `2f9168ca008` |
+| ✅ `compatibleLanguages()` method added | New method in `CustomRuleRepository`                               | `2f9168ca008` |
+| ✅ `ProfileRegistrar` interface added   | Register extra rule keys in built-in default profile (`Sonar way`) | `27e268aad12` |
+| ⚠️ `languages()` method deprecated      | Use `compatibleLanguages()` instead                                | `2f9168ca008` |
+| 🔄 `CustomRuleRepository` undeprecated  | Interface itself is no longer deprecated                           | `2f9168ca008` |
 
 **Migration**: Start using `compatibleLanguages()` to prepare for 11.x.
 
@@ -250,6 +252,7 @@ JavaScriptCheck (deprecated, marker only)
 | `RulesBundle`                        | 6.x         | -             |
 | Separate API module                  | 10.15.0     | -             |
 | `compatibleLanguages()`              | 10.22.0     | 25.5.0        |
+| `ProfileRegistrar`                   | 10.22.0     | 25.5.0        |
 | `EslintHook` / `EslintHookRegistrar` | 10.23.0     | 25.6.0        |
 | `languages()` removed                | 11.1.0      | 25.9.0        |
 | `EslintBasedCheck` deprecated        | 11.6.0      | 25.12.0       |

docs/custom-rules/ESLINT_HOOKS.md

@@ -9,7 +9,7 @@ This document describes the recommended approach for creating custom rules that
 The `EslintHook` interface is the modern way to define custom rules in SonarJS. Rules implementing this interface:
 
 - **Can raise Sonar issues** when registered via `CustomRuleRepository`
-- **Are activated through quality profiles** - only run when enabled by users
+- **Are activated through quality profiles** - by default, run only when enabled in the active quality profile
 - **Provide full control** over analysis modes, file types, and configurations
 
 ## Components
@@ -21,6 +21,7 @@ A complete custom rules integration requires:
 3. **Rules Bundle** - packages the ESLint-side JavaScript code
 4. **Rules Definition** - defines rule metadata for SonarQube
 5. **Plugin Class** - registers all components
+6. **Default Profile Registrar (optional)** - implements `ProfileRegistrar` to activate rules in built-in default profile (`Sonar way`)
 
 ## Implementation Guide
 
@@ -284,6 +285,51 @@ Add the SonarJS API dependency to your `pom.xml`:
 </dependency>
 ```
 
+### 9. Optional: Activate Rules in the Default Built-In Profile
+
+If you want your rules to be active by default in the built-in default quality profile (`Sonar way`), implement `ProfileRegistrar`:
+
+```java
+package com.example.plugin;
+
+import java.util.List;
+import org.sonar.api.rule.RuleKey;
+import org.sonar.plugins.javascript.api.Language;
+import org.sonar.plugins.javascript.api.ProfileRegistrar;
+
+public class MyProfileRegistrar implements ProfileRegistrar {
+
+  @Override
+  public void register(RegistrarContext registrarContext) {
+    registrarContext.registerDefaultQualityProfileRules(
+      Language.JAVASCRIPT,
+      List.of(RuleKey.of(MyRuleRepository.REPOSITORY_KEY, "S1234"))
+    );
+    registrarContext.registerDefaultQualityProfileRules(
+      Language.TYPESCRIPT,
+      List.of(RuleKey.of(MyRuleRepository.REPOSITORY_KEY, "S1234"))
+    );
+  }
+}
+```
+
+Register it in your plugin:
+
+```java
+context.addExtensions(
+  MyRulesBundle.class,
+  MyRuleRepository.class,
+  MyRulesDefinition.class,
+  MyProfileRegistrar.class
+);
+```
+
+Notes:
+
+- This is `@ServerSide` API and is not used in SonarLint.
+- It contributes to the built-in default profile (`Sonar way`) only.
+- Users can still activate/deactivate your rules in any quality profile.
+
 ## API Reference
 
 ### EslintHook Interface
@@ -305,6 +351,13 @@ Add the SonarJS API dependency to your `pom.xml`:
 | `checkClasses()`        | List of check classes implementing EslintHook |
 | `compatibleLanguages()` | Languages this repository supports (JS/TS)    |
 
+### ProfileRegistrar Interface (Optional)
+
+| Method                                    | Description                                                                |
+| ----------------------------------------- | -------------------------------------------------------------------------- |
+| `register(RegistrarContext)`              | Called on server side to contribute additional default-profile activations |
+| `registerDefaultQualityProfileRules(...)` | Adds rule keys to the built-in default profile (`Sonar way`) for JS or TS  |
+
 ## Best Practices
 
 1. **Use `@JavaScriptRule` and `@TypeScriptRule` annotations** - These control which languages your rule applies to.
@@ -658,12 +711,14 @@ This is why `CustomRuleRepository` rules can raise issues: their `eslintKey` is
 
 ### Key Integration Points
 
-| Component                      | File                                                       | Purpose                              |
-| ------------------------------ | ---------------------------------------------------------- | ------------------------------------ |
-| `EslintHook`                   | `sonar-plugin/api/.../EslintHook.java`                     | Rule interface                       |
-| `CustomRuleRepository`         | `sonar-plugin/api/.../CustomRuleRepository.java`           | Interface for rule repositories      |
-| `RulesBundle`                  | `sonar-plugin/api/.../RulesBundle.java`                    | Interface for JS bundle location     |
-| `JsTsChecks.addCustomChecks()` | `sonar-plugin/sonar-javascript-plugin/.../JsTsChecks.java` | Processes custom repositories        |
-| `JsTsChecks.doAddChecks()`     | `sonar-plugin/sonar-javascript-plugin/.../JsTsChecks.java` | Instantiates checks via CheckFactory |
-| `RulesBundles`                 | `sonar-plugin/bridge/.../RulesBundles.java`                | Deploys JS bundles                   |
-| `Linter`                       | `packages/jsts/src/linter/linter.ts`                       | Loads and executes rules             |
+| Component                      | File                                                                         | Purpose                               |
+| ------------------------------ | ---------------------------------------------------------------------------- | ------------------------------------- |
+| `EslintHook`                   | `sonar-plugin/api/.../EslintHook.java`                                       | Rule interface                        |
+| `CustomRuleRepository`         | `sonar-plugin/api/.../CustomRuleRepository.java`                             | Interface for rule repositories       |
+| `ProfileRegistrar`             | `sonar-plugin/api/.../ProfileRegistrar.java`                                 | Optional default-profile activations  |
+| `RulesBundle`                  | `sonar-plugin/api/.../RulesBundle.java`                                      | Interface for JS bundle location      |
+| `JsTsChecks.addCustomChecks()` | `sonar-plugin/sonar-javascript-plugin/.../JsTsChecks.java`                   | Processes custom repositories         |
+| `JsTsChecks.doAddChecks()`     | `sonar-plugin/sonar-javascript-plugin/.../JsTsChecks.java`                   | Instantiates checks via CheckFactory  |
+| `JavaScriptProfilesDefinition` | `sonar-plugin/sonar-javascript-plugin/.../JavaScriptProfilesDefinition.java` | Applies default-profile contributions |
+| `RulesBundles`                 | `sonar-plugin/bridge/.../RulesBundles.java`                                  | Deploys JS bundles                    |
+| `Linter`                       | `packages/jsts/src/linter/linter.ts`                                         | Loads and executes rules              |