Rename no-top-level-hooks to no-root-hooks

Mocha calls hooks declared outside a suite root hooks. Rename the rule so the public rule id and documentation use Mocha's terminology.

BREAKING CHANGE: Users must replace mocha/no-top-level-hooks with mocha/no-root-hooks in ESLint configs.

Author: lo1tuma

README.md

@@ -135,10 +135,10 @@ For maintainers: the rules table below is generated, and the headers in `documen
 | [no-pending-tests](documentation/rules/no-pending-tests.md)                                   | Disallow pending tests                                                  |    | ✅  |    |    | 💡 |
 | [no-return-and-callback](documentation/rules/no-return-and-callback.md)                       | Disallow returning in a test or hook function that uses a callback      | ✅  |    |    |    |    |
 | [no-return-from-async](documentation/rules/no-return-from-async.md)                           | Disallow returning from an async test or hook                           |    |    | ✅  |    |    |
+| [no-root-hooks](documentation/rules/no-root-hooks.md)                                         | Disallow root hooks                                                     |    | ✅  |    |    |    |
 | [no-setup-in-describe](documentation/rules/no-setup-in-describe.md)                           | Disallow setup in describe blocks                                       | ✅  |    |    |    |    |
 | [no-sibling-hooks](documentation/rules/no-sibling-hooks.md)                                   | Disallow duplicate uses of a hook at the same level inside a suite      | ✅  |    |    |    |    |
 | [no-synchronous-tests](documentation/rules/no-synchronous-tests.md)                           | Disallow synchronous tests                                              |    |    | ✅  |    |    |
-| [no-top-level-hooks](documentation/rules/no-top-level-hooks.md)                               | Disallow top-level hooks                                                |    | ✅  |    |    |    |
 | [prefer-arrow-callback](documentation/rules/prefer-arrow-callback.md)                         | Require using arrow functions for callbacks                             |    |    | ✅  | 🔧 |    |
 | [valid-suite-title](documentation/rules/valid-suite-title.md)                                 | Require suite descriptions to match a pre-configured regular expression |    |    | ✅  |    |    |
 | [valid-test-title](documentation/rules/valid-test-title.md)                                   | Require test descriptions to match a pre-configured regular expression  |    |    | ✅  |    |    |

documentation/rules/no-top-level-hooks.md documentation/rules/no-root-hooks.mddocumentation/rules/no-top-level-hooks.md renamed to documentation/rules/no-root-hooks.md

@@ -1,15 +1,16 @@
-# Disallow top-level hooks (`mocha/no-top-level-hooks`)
+# Disallow root hooks (`mocha/no-root-hooks`)
 
 ⚠️ This rule _warns_ in the ✅ `recommended` [config](https://github.com/lo1tuma/eslint-plugin-mocha#configs).
 
 <!-- end auto-generated rule header -->
 
-Mocha proposes hooks that allow code to be run before or after every or all tests. This helps define a common setup or teardown process for every test.
-These hooks should only be declared inside test suites, as they would otherwise be run before or after every test or test suite of the project, even if the test suite of the file they were declared in was skipped. This can lead to very confusing and unwanted effects.
+Mocha calls hooks declared outside a suite [root hooks](https://mochajs.org/features/hooks/#root-level-hooks). They run before or after tests in the root suite, which can be surprising when a file's own suites are skipped.
+
+This rule disallows root hooks and requires hooks to be declared inside a suite.
 
 ## Rule Details
 
-This rule looks for every call to `before`, `after`, `beforeEach` and `afterEach` that are not in a test suite.
+This rule looks for every call to `before`, `after`, `beforeEach` and `afterEach` that is not in a test suite.
 
 The following patterns are considered warnings:
 

source/plugin.ts

@@ -18,10 +18,10 @@ import { noNestedTestsRule } from './rules/no-nested-tests.js';
 import { noPendingTestsRule } from './rules/no-pending-tests.js';
 import { noReturnAndCallbackRule } from './rules/no-return-and-callback.js';
 import { noReturnFromAsyncRule } from './rules/no-return-from-async.js';
+import { noRootHooksRule } from './rules/no-root-hooks.js';
 import { noSetupInDescribeRule } from './rules/no-setup-in-describe.js';
 import { noSiblingHooksRule } from './rules/no-sibling-hooks.js';
 import { noSynchronousTestsRule } from './rules/no-synchronous-tests.js';
-import { noTopLevelHooksRule } from './rules/no-top-level-hooks.js';
 import { preferArrowCallbackRule } from './rules/prefer-arrow-callback.js';
 import { validSuiteTitleRule } from './rules/valid-suite-title.js';
 import { validTestTitleRule } from './rules/valid-test-title.js';
@@ -46,7 +46,7 @@ const allRules: Linter.RulesRecord = {
     'mocha/no-setup-in-describe': 'error',
     'mocha/no-sibling-hooks': 'error',
     'mocha/no-synchronous-tests': 'error',
-    'mocha/no-top-level-hooks': 'error',
+    'mocha/no-root-hooks': 'error',
     'mocha/prefer-arrow-callback': 'error',
     'mocha/consistent-spacing-between-blocks': 'error',
     'mocha/consistent-interface': ['error', { interface: 'BDD' }],
@@ -73,7 +73,7 @@ const recommendedRules: Linter.RulesRecord = {
     'mocha/no-setup-in-describe': 'error',
     'mocha/no-sibling-hooks': 'error',
     'mocha/no-synchronous-tests': 'off',
-    'mocha/no-top-level-hooks': 'warn',
+    'mocha/no-root-hooks': 'warn',
     'mocha/prefer-arrow-callback': 'off',
     'mocha/valid-suite-title': 'off',
     'mocha/valid-test-title': 'off',
@@ -100,7 +100,7 @@ const rules = {
     'no-setup-in-describe': noSetupInDescribeRule,
     'no-sibling-hooks': noSiblingHooksRule,
     'no-synchronous-tests': noSynchronousTestsRule,
-    'no-top-level-hooks': noTopLevelHooksRule,
+    'no-root-hooks': noRootHooksRule,
     'prefer-arrow-callback': preferArrowCallbackRule,
     'consistent-spacing-between-blocks': consistentSpacingBetweenBlocksRule,
     'consistent-interface': consistentInterfaceRule,

source/rules/no-top-level-hooks.test.ts source/rules/no-root-hooks.test.tssource/rules/no-top-level-hooks.test.ts renamed to source/rules/no-root-hooks.test.ts

@@ -1,9 +1,9 @@
 import { RuleTester } from 'eslint';
-import { noTopLevelHooksRule } from './no-top-level-hooks.js';
+import { noRootHooksRule } from './no-root-hooks.js';
 
 const ruleTester = new RuleTester({ languageOptions: { sourceType: 'script' } });
 
-ruleTester.run('no-top-level-hooks', noTopLevelHooksRule, {
+ruleTester.run('no-root-hooks', noRootHooksRule, {
     valid: [
         'describe(function() { before(function() {}); });',
         'describe(function() { after(function() {}); });',

source/rules/no-top-level-hooks.ts source/rules/no-root-hooks.tssource/rules/no-top-level-hooks.ts renamed to source/rules/no-root-hooks.ts

@@ -1,16 +1,16 @@
 import type { Rule } from 'eslint';
 import { createMochaVisitors } from '../ast/mocha-visitors.js';
 
-export const noTopLevelHooksRule: Readonly<Rule.RuleModule> = {
+export const noRootHooksRule: Readonly<Rule.RuleModule> = {
     meta: {
         type: 'problem',
         languages: ['js/js'],
         docs: {
-            description: 'Disallow top-level hooks',
-            url: 'https://github.com/lo1tuma/eslint-plugin-mocha/blob/main/documentation/rules/no-top-level-hooks.md'
+            description: 'Disallow root hooks',
+            url: 'https://github.com/lo1tuma/eslint-plugin-mocha/blob/main/documentation/rules/no-root-hooks.md'
         },
         messages: {
-            unexpectedTopLevelHook: 'Unexpected use of Mocha `{{name}}` hook outside of a test suite'
+            unexpectedRootHook: 'Unexpected use of Mocha `{{name}}` hook outside of a test suite'
         },
         schema: []
     },
@@ -24,7 +24,7 @@ export const noTopLevelHooksRule: Readonly<Rule.RuleModule> = {
 
                     context.report({
                         node,
-                        messageId: 'unexpectedTopLevelHook',
+                        messageId: 'unexpectedRootHook',
                         data: { name: visitorContext.name }
                     });
                 }