feat: add rule consistent-each-for (#826)

* feat: add rule consistent-each-for

* refactor: remove unnecessary type assertions in consistent-each-for tests

* update

* remove unnecessary comments

---------

Co-authored-by: Verite Mugabo <mugaboverite@gmail.com>

Author: figueiredoluiz

README.md

@@ -187,6 +187,7 @@ export default defineConfig({
 
 | Name                                                                                                                     | Description                                                                                     | 💼  | ⚠️  | 🚫  | 🔧  | 💡  | 💭  | ❌  |
 | :----------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------- | :-- | :-- | :-- | :-- | :-- | :-- | :-- |
+| [consistent-each-for](docs/rules/consistent-each-for.md)                                                                 | enforce using `.each` or `.for` consistently                                                    |     | 🌐  |     |     |     |     |     |
 | [consistent-test-filename](docs/rules/consistent-test-filename.md)                                                       | require test file pattern                                                                       |     | 🌐  |     |     |     |     |     |
 | [consistent-test-it](docs/rules/consistent-test-it.md)                                                                   | enforce using test or it but not both                                                           |     | 🌐  |     | 🔧  |     |     |     |
 | [consistent-vitest-vi](docs/rules/consistent-vitest-vi.md)                                                               | enforce using vitest or vi but not both                                                         |     | 🌐  |     | 🔧  |     |     |     |

docs/rules/consistent-each-for.md

@@ -0,0 +1,111 @@
+# Enforce using `.each` or `.for` consistently (`vitest/consistent-each-for`)
+
+⚠️ This rule _warns_ in the 🌐 `all` config.
+
+<!-- end auto-generated rule header -->
+
+## Rule Details
+
+Vitest provides two ways to run parameterized tests: `.each` and `.for`. This rule enforces consistency in the usage of these methods.
+
+**Key Differences:**
+
+- **`.each`**: Spreads array arguments to individual parameters
+- **`.for`**: Keeps arrays intact, provides better TestContext support
+
+This rule allows you to configure which method to prefer for different test function types (`test`, `it`, `describe`, `suite`).
+
+Examples of **incorrect** code when configured to prefer `.for`:
+
+```js
+// { test: 'for' }
+test.each([[1, 1, 2]])('test', (a, b, expected) => {
+  expect(a + b).toBe(expected)
+})
+```
+
+```js
+// { describe: 'for' }
+describe.each([[1], [2]])('suite %s', (n) => {
+  test('test', () => {})
+})
+```
+
+Examples of **correct** code when configured to prefer `.for`:
+
+```js
+// { test: 'for' }
+test.for([[1, 1, 2]])('test', ([a, b, expected]) => {
+  expect(a + b).toBe(expected)
+})
+```
+
+```js
+// { describe: 'for' }
+describe.for([[1], [2]])('suite %s', ([n]) => {
+  test('test', () => {})
+})
+```
+
+Examples of **incorrect** code when configured to prefer `.each`:
+
+```js
+// { test: 'each' }
+test.for([[1, 1, 2]])('test', ([a, b, expected]) => {
+  expect(a + b).toBe(expected)
+})
+```
+
+Examples of **correct** code when configured to prefer `.each`:
+
+```js
+// { test: 'each' }
+test.each([[1, 1, 2]])('test', (a, b, expected) => {
+  expect(a + b).toBe(expected)
+})
+```
+
+```js
+// { test: 'each' }
+test.skip.each([[1, 2]])('test', (a, b) => {
+  expect(a).toBeLessThan(b)
+})
+```
+
+## Options
+
+<!-- begin auto-generated rule options list -->
+
+| Name       | Type   | Choices       |
+| :--------- | :----- | :------------ |
+| `describe` | String | `each`, `for` |
+| `it`       | String | `each`, `for` |
+| `suite`    | String | `each`, `for` |
+| `test`     | String | `each`, `for` |
+
+<!-- end auto-generated rule options list -->
+
+## Configuration
+
+Typical configuration to enforce `.for` for tests and `.each` for describe blocks:
+
+```js
+// eslint.config.js
+export default [
+  {
+    rules: {
+      'vitest/consistent-each-for': [
+        'warn',
+        {
+          test: 'for',
+          it: 'for',
+          describe: 'each',
+          suite: 'each',
+        },
+      ],
+    },
+  },
+]
+```
+
+You can configure each function type independently. If a function type is not configured, the rule won't enforce any preference for it.

src/index.ts

@@ -25,6 +25,7 @@ const createConfigLegacy = (rules: Record<string, string>) => ({
 const allRules = {
   'consistent-test-filename': 'warn',
   'consistent-test-it': 'warn',
+  'consistent-each-for': 'warn',
   'consistent-vitest-vi': 'warn',
   'expect-expect': 'warn',
   'hoisted-apis-on-top': 'warn',

src/rules/consistent-each-for.ts

@@ -0,0 +1,99 @@
+import { TSESTree } from '@typescript-eslint/utils'
+import { createEslintRule, getAccessorValue } from '../utils'
+import { parseVitestFnCall } from '../utils/parse-vitest-fn-call'
+
+export const RULE_NAME = 'consistent-each-for'
+export type MessageIds = 'consistentMethod'
+
+type EachOrFor = 'each' | 'for'
+
+const BASE_FN_NAMES = ['test', 'it', 'describe', 'suite']
+
+type Options = {
+  test?: EachOrFor
+  it?: EachOrFor
+  describe?: EachOrFor
+  suite?: EachOrFor
+}
+
+export default createEslintRule<[Partial<Options>], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'enforce using `.each` or `.for` consistently',
+      recommended: false,
+    },
+    messages: {
+      consistentMethod:
+        'Prefer using `{{ functionName }}.{{ preferred }}` over `{{ functionName }}.{{ actual }}`',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          test: {
+            type: 'string',
+            enum: ['each', 'for'],
+          },
+          it: {
+            type: 'string',
+            enum: ['each', 'for'],
+          },
+          describe: {
+            type: 'string',
+            enum: ['each', 'for'],
+          },
+          suite: {
+            type: 'string',
+            enum: ['each', 'for'],
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+    defaultOptions: [{}],
+  },
+  defaultOptions: [{}],
+  create(context, [options]) {
+    return {
+      CallExpression(node: TSESTree.CallExpression) {
+        const vitestFnCall = parseVitestFnCall(node, context)
+
+        if (!vitestFnCall) return
+
+        const baseFunctionName = vitestFnCall.name.replace(/^[fx]/, '')
+
+        if (!BASE_FN_NAMES.includes(baseFunctionName)) return
+
+        const eachMember = vitestFnCall.members.find(
+          (member) => getAccessorValue(member) === 'each',
+        )
+
+        const forMember = vitestFnCall.members.find(
+          (member) => getAccessorValue(member) === 'for',
+        )
+
+        if (!eachMember && !forMember) return
+
+        const preference = options[baseFunctionName as keyof Options]
+
+        if (!preference) return
+
+        const actual: EachOrFor = eachMember ? 'each' : 'for'
+
+        if (actual !== preference) {
+          context.report({
+            node: (eachMember || forMember)!,
+            messageId: 'consistentMethod',
+            data: {
+              functionName: vitestFnCall.name,
+              preferred: preference,
+              actual,
+            },
+          })
+        }
+      },
+    }
+  },
+})

src/rules/index.ts

@@ -1,4 +1,5 @@
 import { Linter } from 'eslint'
+import consistentEachFor from './consistent-each-for'
 import consistentTestFilename from './consistent-test-filename'
 import consistentTestIt from './consistent-test-it'
 import consistentVitestVi from './consistent-vitest-vi'
@@ -78,6 +79,7 @@ import validTitle from './valid-title'
 import warnTodo from './warn-todo'
 
 export const rules = {
+  'consistent-each-for': consistentEachFor,
   'consistent-test-filename': consistentTestFilename,
   'consistent-test-it': consistentTestIt,
   'consistent-vitest-vi': consistentVitestVi,