feat: prefer importing jest globals [new rule]

- Fix jest-community#1101

Issue: jest-community#1101

Author: MadeinFrance

README.md

@@ -248,6 +248,7 @@ set to warn in.\
 | [prefer-expect-resolves](docs/rules/prefer-expect-resolves.md)               | Prefer `await expect(...).resolves` over `expect(await ...)` syntax       |     |     | 🔧  |     |     |
 | [prefer-hooks-in-order](docs/rules/prefer-hooks-in-order.md)                 | Prefer having hooks in a consistent order                                 |     |     |     |     |     |
 | [prefer-hooks-on-top](docs/rules/prefer-hooks-on-top.md)                     | Suggest having hooks before any test cases                                |     |     |     |     |     |
+| [prefer-jest-globals](docs/rules/prefer-jest-globals.md)                     | Prefer importing Jest globals                                             |     |     | 🔧  |     |     |
 | [prefer-lowercase-title](docs/rules/prefer-lowercase-title.md)               | Enforce lowercase test names                                              |     |     | 🔧  |     |     |
 | [prefer-mock-promise-shorthand](docs/rules/prefer-mock-promise-shorthand.md) | Prefer mock resolved/rejected shorthands for promises                     |     |     | 🔧  |     |     |
 | [prefer-snapshot-hint](docs/rules/prefer-snapshot-hint.md)                   | Prefer including a hint with external snapshots                           |     |     |     |     |     |

docs/rules/prefer-jest-globals.md

@@ -0,0 +1,47 @@
+# Prefer importing Jest globals (`prefer-jest-globals`)
+
+🔧 This rule is automatically fixable by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->
+
+This rule aims to enforce explicit imports from `@jest/globals`.
+
+1. This is useful for ensuring that the Jest APIs are imported the same way in
+   the codebase.
+2. When you can't modify Jest's
+   [`injectGlobals`](https://jestjs.io/docs/configuration#injectglobals-boolean)
+   configuration property, this rule can help to ensure that the Jest globals
+   are imported explicitly and facilitate a migration to `@jest/globals`.
+
+## Rule details
+
+Examples of **incorrect** code for this rule
+
+```js
+/* eslint jest/prefer-jest-globals: "error" */
+
+describe('foo', () => {
+  it('accepts this input', () => {
+    // ...
+  });
+});
+```
+
+Examples of **correct** code for this rule
+
+```js
+/* eslint jest/prefer-jest-globals: "error" */
+
+import { describe, it } from '@jest/globals';
+
+describe('foo', () => {
+  it('accepts this input', () => {
+    // ...
+  });
+});
+```
+
+## Further Reading
+
+- [Documentation](https://jestjs.io/docs/api)

src/__tests__/__snapshots__/rules.test.ts.snap

@@ -45,6 +45,7 @@ exports[`rules should export configs that refer to actual rules 1`] = `
       "jest/prefer-expect-resolves": "error",
       "jest/prefer-hooks-in-order": "error",
       "jest/prefer-hooks-on-top": "error",
+      "jest/prefer-jest-globals": "error",
       "jest/prefer-lowercase-title": "error",
       "jest/prefer-mock-promise-shorthand": "error",
       "jest/prefer-snapshot-hint": "error",

src/__tests__/rules.test.ts

@@ -2,7 +2,7 @@ import { existsSync } from 'fs';
 import { resolve } from 'path';
 import plugin from '../';
 
-const numberOfRules = 53;
+const numberOfRules = 54;
 const ruleNames = Object.keys(plugin.rules);
 const deprecatedRules = Object.entries(plugin.rules)
   .filter(([, rule]) => rule.meta.deprecated)

src/rules/__tests__/prefer-jest-globals.test.ts

@@ -0,0 +1,36 @@
+import { TSESLint } from '@typescript-eslint/utils';
+import dedent from 'dedent';
+import rule from '../prefer-jest-globals';
+import { espreeParser } from './test-utils';
+
+const ruleTester = new TSESLint.RuleTester({
+  parser: espreeParser,
+  parserOptions: {
+    ecmaVersion: 2015,
+    sourceType: 'module',
+  },
+});
+
+ruleTester.run('prefer-jest-globals.test', rule, {
+  valid: [
+    {
+      code: dedent`
+        import { test, expect } from '@jest/globals';
+
+        test('should pass', () => {
+            expect(true).toBeDefined();
+        });
+        `,
+      parserOptions: { sourceType: 'module' },
+    },
+  ],
+  invalid: [
+    {
+      code: dedent`
+        it("foo");
+      `,
+      parserOptions: { sourceType: 'module' },
+      errors: [{ endColumn: 11, column: 1, messageId: 'preferJestGlobal' }],
+    },
+  ],
+});

src/rules/prefer-jest-globals.ts

@@ -0,0 +1,58 @@
+import globalsJson from '../globals.json';
+import { createRule } from './utils';
+
+export default createRule({
+  name: __filename,
+  meta: {
+    docs: {
+      category: 'Best Practices',
+      description: 'Prefer importing Jest globals',
+      recommended: false,
+    },
+    messages: {
+      preferJestGlobal:
+        "Jest function \"{{ jestFunction }} is used but not imported from '@jest/globals'",
+    },
+    fixable: 'code',
+    type: 'suggestion',
+    schema: [],
+  },
+  defaultOptions: [],
+  create(context) {
+    const jestFunctions = Object.keys(globalsJson);
+    const importedJestFunctions: any[] = [];
+    const usedJestFunctions = new Set();
+
+    return {
+      ImportDeclaration(node) {
+        // Check if the import source is '@jest/globals'
+        if (node.source.value === '@jest/globals') {
+          node.specifiers.forEach(specifier => {
+            if (
+              specifier.type === 'ImportSpecifier' &&
+              jestFunctions.includes(specifier.imported.name)
+            ) {
+              importedJestFunctions.push(specifier.imported.name);
+            }
+          });
+        }
+      },
+      Identifier(node) {
+        if (jestFunctions.includes(node.name)) {
+          usedJestFunctions.add(node.name);
+        }
+      },
+      'Program:exit'() {
+        usedJestFunctions.forEach(jestFunction => {
+          if (!importedJestFunctions.includes(jestFunction)) {
+            context.report({
+              node: context.getSourceCode().ast,
+              messageId: 'preferJestGlobal',
+              data: { jestFunction },
+            });
+          }
+        });
+      },
+    };
+  },
+});

yarn.lock

@@ -2846,11 +2846,11 @@ __metadata:
   linkType: hard
 
 "@types/node@npm:*":
-  version: 20.11.0
-  resolution: "@types/node@npm:20.11.0"
+  version: 20.10.8
+  resolution: "@types/node@npm:20.10.8"
   dependencies:
     undici-types: ~5.26.4
-  checksum: 1bd6890db7e0404d11c33d28f46f19f73256f0ba35d19f0ef2a0faba09f366f188915fb9338eebebcc472075c1c4941e17c7002786aa69afa44980737846b200
+  checksum: ce9b7ee545b3605f667be2ea900e38ab58d7b561192a7342443e5d7f61c44fd9d016eac48e95d3011f090ceea65a727e83a31d51fabdd9fc20ff9992edcbc682
   languageName: node
   linkType: hard
 
@@ -3086,7 +3086,7 @@ __metadata:
   version: 8.11.3
   resolution: "acorn@npm:8.11.3"
   bin:
-    acorn: bin/acorn
+    acorn: ./bin/acorn
   checksum: 76d8e7d559512566b43ab4aadc374f11f563f0a9e21626dd59cb2888444e9445923ae9f3699972767f18af61df89cd89f5eaaf772d1327b055b45cb829b4a88c
   languageName: node
   linkType: hard
@@ -4293,7 +4293,7 @@ __metadata:
     jest-util: ^29.7.0
     prompts: ^2.0.1
   bin:
-    create-jest: bin/create-jest.js
+    create-jest: ./bin/create-jest.js
   checksum: 1427d49458adcd88547ef6fa39041e1fe9033a661293aa8d2c3aa1b4967cb5bf4f0c00436c7a61816558f28ba2ba81a94d5c962e8022ea9a883978fc8e1f2945
   languageName: node
   linkType: hard
@@ -5155,7 +5155,7 @@ __metadata:
     strip-ansi: ^6.0.1
     text-table: ^0.2.0
   bin:
-    eslint: bin/eslint.js
+    eslint: ./bin/eslint.js
   checksum: 883436d1e809b4a25d9eb03d42f584b84c408dbac28b0019f6ea07b5177940bf3cca86208f749a6a1e0039b63e085ee47aca1236c30721e91f0deef5cc5a5136
   languageName: node
   linkType: hard
@@ -5724,7 +5724,7 @@ __metadata:
     minipass: ^5.0.0 || ^6.0.2 || ^7.0.0
     path-scurry: ^1.10.1
   bin:
-    glob: dist/esm/bin.mjs
+    glob: ./dist/esm/bin.mjs
   checksum: 4f2fe2511e157b5a3f525a54092169a5f92405f24d2aed3142f4411df328baca13059f4182f1db1bf933e2c69c0bd89e57ae87edd8950cba8c7ccbe84f721cf3
   languageName: node
   linkType: hard
@@ -6751,7 +6751,7 @@ __metadata:
     node-notifier:
       optional: true
   bin:
-    jest: bin/jest.js
+    jest: ./bin/jest.js
   checksum: 664901277a3f5007ea4870632ed6e7889db9da35b2434e7cb488443e6bf5513889b344b7fddf15112135495b9875892b156faeb2d7391ddb9e2a849dcb7b6c36
   languageName: node
   linkType: hard
@@ -7151,7 +7151,7 @@ __metadata:
     node-notifier:
       optional: true
   bin:
-    jest: bin/jest.js
+    jest: ./bin/jest.js
   checksum: 17ca8d67504a7dbb1998cf3c3077ec9031ba3eb512da8d71cb91bcabb2b8995c4e4b292b740cb9bf1cbff5ce3e110b3f7c777b0cefb6f41ab05445f248d0ee0b
   languageName: node
   linkType: hard
@@ -8134,14 +8134,14 @@ __metadata:
   languageName: node
   linkType: hard
 
-"ms@npm:2.1.2":
+"ms@npm:2.1.2, ms@npm:^2.1.1":
   version: 2.1.2
   resolution: "ms@npm:2.1.2"
   checksum: 673cdb2c3133eb050c745908d8ce632ed2c02d85640e2edb3ace856a2266a813b30c613569bf3354fdf4ea7d1a1494add3bfa95e2713baa27d0c2c71fc44f58f
   languageName: node
   linkType: hard
 
-"ms@npm:^2.1.1, ms@npm:^2.1.2, ms@npm:^2.1.3":
+"ms@npm:^2.1.2, ms@npm:^2.1.3":
   version: 2.1.3
   resolution: "ms@npm:2.1.3"
   checksum: aa92de608021b242401676e35cfa5aa42dd70cbdc082b916da7fb925c542173e36bce97ea3e804923fe92c0ad991434e4a38327e15a1b5b5f945d66df615ae6d
@@ -8239,7 +8239,7 @@ __metadata:
     tar: ^6.1.2
     which: ^4.0.0
   bin:
-    node-gyp: bin/node-gyp.js
+    node-gyp: ./bin/node-gyp.js
   checksum: 60a74e66d364903ce02049966303a57f898521d139860ac82744a5fdd9f7b7b3b61f75f284f3bfe6e6add3b8f1871ce305a1d41f775c7482de837b50c792223f
   languageName: node
   linkType: hard
@@ -9517,7 +9517,7 @@ __metadata:
     path-parse: ^1.0.7
     supports-preserve-symlinks-flag: ^1.0.0
   bin:
-    resolve: bin/resolve
+    resolve: ./bin/resolve
   checksum: f8a26958aa572c9b064562750b52131a37c29d072478ea32e129063e2da7f83e31f7f11e7087a18225a8561cfe8d2f0df9dbea7c9d331a897571c0a2527dbb4c
   languageName: node
   linkType: hard
@@ -9530,7 +9530,7 @@ __metadata:
     path-parse: ^1.0.7
     supports-preserve-symlinks-flag: ^1.0.0
   bin:
-    resolve: bin/resolve
+    resolve: ./bin/resolve
   checksum: 5479b7d431cacd5185f8db64bfcb7286ae5e31eb299f4c4f404ad8aa6098b77599563ac4257cb2c37a42f59dfc06a1bec2bcf283bb448f319e37f0feb9a09847
   languageName: node
   linkType: hard
@@ -9582,7 +9582,7 @@ __metadata:
   dependencies:
     glob: ^7.1.3
   bin:
-    rimraf: bin.js
+    rimraf: ./bin.js
   checksum: 87f4164e396f0171b0a3386cc1877a817f572148ee13a7e113b238e48e8a9f2f31d009a92ec38a591ff1567d9662c6b67fd8818a2dbbaed74bc26a87a2a4a9a0
   languageName: node
   linkType: hard
@@ -9626,13 +9626,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"safe-buffer@npm:~5.2.0":
-  version: 5.2.1
-  resolution: "safe-buffer@npm:5.2.1"
-  checksum: b99c4b41fdd67a6aaf280fcd05e9ffb0813654894223afb78a31f14a19ad220bba8aba1cb14eddce1fcfb037155fe6de4e861784eb434f7d11ed58d1e70dd491
-  languageName: node
-  linkType: hard
-
 "safe-regex-test@npm:^1.0.0":
   version: 1.0.2
   resolution: "safe-regex-test@npm:1.0.2"
@@ -9727,7 +9720,7 @@ __metadata:
   version: 5.7.2
   resolution: "semver@npm:5.7.2"
   bin:
-    semver: bin/semver
+    semver: ./bin/semver
   checksum: fb4ab5e0dd1c22ce0c937ea390b4a822147a9c53dbd2a9a0132f12fe382902beef4fbf12cf51bb955248d8d15874ce8cd89532569756384f994309825f10b686
   languageName: node
   linkType: hard
@@ -9747,7 +9740,7 @@ __metadata:
   version: 6.3.1
   resolution: "semver@npm:6.3.1"
   bin:
-    semver: bin/semver.js
+    semver: ./bin/semver.js
   checksum: ae47d06de28836adb9d3e25f22a92943477371292d9b665fb023fae278d345d508ca1958232af086d85e0155aee22e313e100971898bbb8d5d89b8b1d4054ca2
   languageName: node
   linkType: hard
@@ -10143,16 +10136,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"string_decoder@npm:^1.1.1":
-  version: 1.3.0
-  resolution: "string_decoder@npm:1.3.0"
-  dependencies:
-    safe-buffer: ~5.2.0
-  checksum: 8417646695a66e73aefc4420eb3b84cc9ffd89572861fe004e6aeb13c7bc00e2f616247505d2dbbef24247c372f70268f594af7126f43548565c68c117bdeb56
-  languageName: node
-  linkType: hard
-
-"string_decoder@npm:~1.1.1":
+"string_decoder@npm:^1.1.1, string_decoder@npm:~1.1.1":
   version: 1.1.1
   resolution: "string_decoder@npm:1.1.1"
   dependencies:
@@ -10663,8 +10647,8 @@ __metadata:
   version: 5.2.2
   resolution: "typescript@npm:5.2.2"
   bin:
-    tsc: bin/tsc
-    tsserver: bin/tsserver
+    tsc: ./bin/tsc
+    tsserver: ./bin/tsserver
   checksum: 7912821dac4d962d315c36800fe387cdc0a6298dba7ec171b350b4a6e988b51d7b8f051317786db1094bd7431d526b648aba7da8236607febb26cf5b871d2d3c
   languageName: node
   linkType: hard
@@ -10673,8 +10657,8 @@ __metadata:
   version: 5.2.2
   resolution: "typescript@patch:typescript@npm%3A5.2.2#~builtin<compat/typescript>::version=5.2.2&hash=f3b441"
   bin:
-    tsc: bin/tsc
-    tsserver: bin/tsserver
+    tsc: ./bin/tsc
+    tsserver: ./bin/tsserver
   checksum: 0f4da2f15e6f1245e49db15801dbee52f2bbfb267e1c39225afdab5afee1a72839cd86000e65ee9d7e4dfaff12239d28beaf5ee431357fcced15fb08583d72ca
   languageName: node
   linkType: hard
@@ -10935,7 +10919,7 @@ __metadata:
   dependencies:
     isexe: ^3.1.1
   bin:
-    node-which: bin/which.js
+    node-which: ./bin/which.js
   checksum: f17e84c042592c21e23c8195108cff18c64050b9efb8459589116999ea9da6dd1509e6a1bac3aeebefd137be00fabbb61b5c2bc0aa0f8526f32b58ee2f545651
   languageName: node
   linkType: hard