feat: add prefer-describe-function-title rule (#690)

* feat: add prefer-describe-function-title rule

* chore: fix peer deps

---------

Co-authored-by: Verite Mugabo <[email protected]>

Author: JoshuaKGoldberg

README.md

@@ -187,6 +187,7 @@ export default [
 | [padding-around-expect-groups](docs/rules/padding-around-expect-groups.md)                                                       | enforce padding around `expect` groups                                   |    | 🌐 | 🔧 |    |    |
 | [prefer-called-with](docs/rules/prefer-called-with.md)                                                                   | enforce using `toBeCalledWith()` or `toHaveBeenCalledWith()`          |    | 🌐 | 🔧 |    |    |
 | [prefer-comparison-matcher](docs/rules/prefer-comparison-matcher.md)                                                     | enforce using the built-in comparison matchers                        |    | 🌐 | 🔧 |    |    |
+| [prefer-describe-function-title](docs/rules/prefer-describe-function-title.md)                                             | prefer using a function as a describe name over an equivalent string  |    | 🌐 | 🔧 |    |    |
 | [prefer-each](docs/rules/prefer-each.md)                                                                                 | enforce using `each` rather than manual loops                         |    | 🌐 |    |    |    |
 | [prefer-equality-matcher](docs/rules/prefer-equality-matcher.md)                                                         | enforce using the built-in quality matchers                           |    | 🌐 |    | 💡 |    |
 | [prefer-expect-assertions](docs/rules/prefer-expect-assertions.md)                                                       | enforce using expect assertions instead of callbacks                  |    | 🌐 |    | 💡 |    |

docs/rules/prefer-describe-function-title.md

@@ -0,0 +1,37 @@
+# Enforce using a function as a describe title over an equivalent string (`vitest/prefer-describe-function-title`)
+
+🔧 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 -->
+
+## Rule Details
+
+This rule aims to enforce passing a named function to `describe()` instead of an equivalent hardcoded string.
+
+Passing named functions means the correct title will be used even if the function is renamed.
+This rule will report if a string is passed to a `describe()` block if:
+
+* The string matches a function imported into the file
+* That function's name also matches the test file's name
+
+Examples of **incorrect** code for this rule:
+
+```ts
+// myFunction.test.js
+import { myFunction } from "./myFunction"
+
+describe("myFunction", () => {
+  // ...
+})
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+// myFunction.test.js
+import { myFunction } from "./myFunction"
+
+describe(myFunction, () => {
+  // ...
+})
+```

package.json

@@ -73,16 +73,14 @@
     "vitest": "^3.0.5"
   },
   "peerDependencies": {
+    "@typescript-eslint/utils": ">= 8.24.0",
     "eslint": ">= 8.57.0",
     "typescript": ">= 5.0.0",
     "vitest": "*"
   },
   "peerDependenciesMeta": {
     "typescript": {
       "optional": true
-    },
-    "vitest": {
-      "optional": true
     }
   },
   "packageManager": "[email protected]"

src/index.ts

@@ -52,6 +52,7 @@ import requireLocalTestContextForConcurrentSnapshots, { RULE_NAME as requireLoca
 import preferTodo, { RULE_NAME as preferTodoName } from './rules/prefer-todo'
 import preferSpyOn, { RULE_NAME as preferSpyOnName } from './rules/prefer-spy-on'
 import preferComparisonMatcher, { RULE_NAME as preferComparisonMatcherName } from './rules/prefer-comparison-matcher'
+import preferDescribeFunctionTitle, { RULE_NAME as preferDescribeFunctionTitleName } from './rules/prefer-describe-function-title'
 import preferToContain, { RULE_NAME as preferToContainName } from './rules/prefer-to-contain'
 import preferExpectAssertions, { RULE_NAME as preferExpectAssertionsName } from './rules/prefer-expect-assertions'
 import paddingAroundAfterAllBlocks, { RULE_NAME as paddingAroundAfterAllBlocksName } from './rules/padding-around-after-all-blocks'
@@ -129,6 +130,7 @@ const allRules = {
   [preferTodoName]: 'warn',
   [preferSpyOnName]: 'warn',
   [preferComparisonMatcherName]: 'warn',
+  [preferDescribeFunctionTitleName]: 'warn',
   [preferToContainName]: 'warn',
   [preferExpectAssertionsName]: 'warn',
   [usePreferToBe]: 'warn',
@@ -221,6 +223,7 @@ const plugin = {
     [preferTodoName]: preferTodo,
     [preferSpyOnName]: preferSpyOn,
     [preferComparisonMatcherName]: preferComparisonMatcher,
+    [preferDescribeFunctionTitleName]: preferDescribeFunctionTitle,
     [preferToContainName]: preferToContain,
     [preferExpectAssertionsName]: preferExpectAssertions,
     [paddingAroundAfterAllBlocksName]: paddingAroundAfterAllBlocks,

src/rules/no-disabled-tests.ts

@@ -1,5 +1,6 @@
 import { createEslintRule, getAccessorValue } from '../utils'
 import { parseVitestFnCall, resolveScope } from '../utils/parse-vitest-fn-call'
+import { getScope } from '../utils/scope'
 
 export const RULE_NAME = 'no-disabled-tests'
 export type MESSAGE_ID = 'missingFunction' | 'pending' | 'pendingSuite' | 'pendingTest' | 'disabledSuite' | 'disabledTest'
@@ -69,9 +70,7 @@ export default createEslintRule<Options, MESSAGE_ID>({
           testDepth--
       },
       'CallExpression[callee.name="pending"]'(node) {
-        const scope = context.sourceCode.getScope
-          ? context.sourceCode.getScope(node)
-          : context.getScope()
+        const scope = getScope(context, node)
 
         if (resolveScope(scope, 'pending'))
           return

src/rules/prefer-describe-function-title.ts

@@ -0,0 +1,83 @@
+import {
+  AST_NODE_TYPES,
+  ESLintUtils,
+  TSESLint
+} from '@typescript-eslint/utils'
+import { createEslintRule } from '../utils'
+import { parsePluginSettings } from '../utils/parse-plugin-settings'
+import { parseVitestFnCall } from '../utils/parse-vitest-fn-call'
+import { getModuleScope } from '../utils/scope'
+import { isClassOrFunctionType } from '../utils/types'
+
+export const RULE_NAME = 'prefer-describe-function-title'
+export type MESSAGE_IDS = 'preferFunction'
+export type Options = []
+
+export default createEslintRule<Options, MESSAGE_IDS>({
+  name: RULE_NAME,
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'enforce using a function as a describe title over an equivalent string',
+      recommended: false
+    },
+    fixable: 'code',
+    schema: [],
+    messages: {
+      preferFunction: 'Enforce using a function over an equivalent string'
+    }
+  },
+  defaultOptions: [],
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (node.arguments.length < 2) {
+          return
+        }
+
+        const [argument] = node.arguments
+        if (
+          argument.type !== AST_NODE_TYPES.Literal
+          || typeof argument.value !== 'string'
+        ) {
+          return
+        }
+
+        const describedTitle = argument.value
+        if (!context.filename.includes(`${describedTitle}.`)) {
+          return
+        }
+
+        const vitestFnCall = parseVitestFnCall(node, context)
+        if (vitestFnCall?.type !== 'describe') {
+          return
+        }
+
+        const scope = getModuleScope(context, node)
+        const scopedFunction = scope?.set.get(describedTitle)?.defs[0]
+        if (scopedFunction?.type !== 'ImportBinding') {
+          return
+        }
+
+        const settings = parsePluginSettings(context.settings)
+        if (settings.typecheck) {
+          const services = ESLintUtils.getParserServices(context)
+          const type = services.getTypeAtLocation(scopedFunction.node)
+
+          if (!isClassOrFunctionType(type)) {
+            return
+          }
+        }
+
+        context.report({
+          node: argument,
+          messageId: 'preferFunction',
+          fix(fixer) {
+            return fixer.replaceText(argument, describedTitle)
+          }
+        })
+      }
+    }
+  }
+})

src/rules/valid-title.ts

@@ -1,7 +1,7 @@
 import { AST_NODE_TYPES, ESLintUtils, JSONSchema, TSESTree } from '@typescript-eslint/utils'
 import { createEslintRule, getStringValue, isStringNode, StringNode } from '../utils'
 import { parseVitestFnCall } from '../utils/parse-vitest-fn-call'
-import { DescribeAlias, TestCaseName } from '../utils/types'
+import { DescribeAlias, isClassOrFunctionType, TestCaseName } from '../utils/types'
 import ts from 'typescript'
 import { parsePluginSettings } from '../utils/parse-plugin-settings'
 
@@ -62,30 +62,6 @@ const compileMatcherPattern = (matcherMaybeWithMessage: MatcherAndMessage | stri
   return [new RegExp(matcher, 'u'), message]
 }
 
-function isFunctionType(type: ts.Type): boolean {
-  const symbol = type.getSymbol()
-
-  if (!symbol) {
-    return false
-  }
-
-  return symbol.getDeclarations()?.some(declaration =>
-    ts.isFunctionDeclaration(declaration)
-    || ts.isMethodDeclaration(declaration)
-    || ts.isFunctionExpression(declaration)
-    || ts.isArrowFunction(declaration)) ?? false
-}
-
-function isClassType(type: ts.Type): boolean {
-  const symbol = type.getSymbol()
-
-  if (!symbol) return false
-
-  return symbol.getDeclarations()?.some(declaration =>
-    ts.isClassDeclaration(declaration)
-    || ts.isClassExpression(declaration)) ?? false
-}
-
 function isStringLikeType(type: ts.Type): boolean {
   return !!(type.flags & (ts.TypeFlags.StringLike))
 }
@@ -229,7 +205,7 @@ export default createEslintRule<Options, MESSAGE_IDS>({
 
           const type = services.getTypeAtLocation(argument)
 
-          if (isFunctionType(type) || isClassType(type)) return
+          if (isClassOrFunctionType(type)) return
 
           if (isStringLikeType(type)) {
             if (isStringNode(argument) && !getStringValue(argument)) {

src/utils/parse-vitest-fn-call.ts

@@ -2,6 +2,7 @@ import { AST_NODE_TYPES, TSESLint, TSESTree } from '@typescript-eslint/utils'
 import { DescribeAlias, HookName, ModifierName, TestCaseName } from './types'
 import { ValidVitestFnCallChains } from './valid-vitest-fn-call-chains'
 import { AccessorNode, getAccessorValue, getStringValue, isFunction, isIdentifier, isStringNode, isSupportedAccessor } from '.'
+import { getScope } from './scope'
 
 export type VitestFnType =
   | 'test'
@@ -313,9 +314,7 @@ const resolveVitestFn = (
   node: TSESTree.CallExpression,
   identifier: string
 ): ResolvedVitestFn | null => {
-  const scope = context.sourceCode.getScope
-    ? context.sourceCode.getScope(node)
-    : context.getScope()
+  const scope = getScope(context, node)
   const maybeImport = resolveScope(scope, identifier)
 
   if (maybeImport === 'local')

src/utils/scope.ts

@@ -0,0 +1,27 @@
+import { TSESLint, TSESTree } from '@typescript-eslint/utils'
+import { Scope } from '@typescript-eslint/utils/ts-eslint'
+
+export function getScope(
+  context: TSESLint.RuleContext<string, unknown[]>,
+  node: TSESTree.Node
+): Scope.Scope {
+  return context.sourceCode.getScope
+    ? context.sourceCode.getScope(node)
+    : context.getScope()
+}
+
+export function getModuleScope(
+  context: TSESLint.RuleContext<string, unknown[]>,
+  node: TSESTree.Node
+): Scope.Scope | null {
+  let scope: Scope.Scope | null = getScope(context, node)
+
+  while (scope) {
+    if (scope.type === 'module') {
+      return scope
+    }
+    scope = scope.upper
+  }
+
+  return scope
+}

src/utils/types.ts

@@ -1,4 +1,5 @@
 import { TSESTree } from '@typescript-eslint/utils'
+import ts from 'typescript'
 
 export enum DescribeAlias {
   describe = 'describe',
@@ -73,3 +74,18 @@ interface TypeAssertionChain<
 > extends TSESTree.TSTypeAssertion {
   expression: TypeAssertionChain<Expression> | Expression
 }
+
+export function isClassOrFunctionType(type: ts.Type): boolean {
+  return type
+    .getSymbol()
+    ?.getDeclarations()
+    ?.some(
+      declaration =>
+        ts.isArrowFunction(declaration)
+        || ts.isClassDeclaration(declaration)
+        || ts.isClassExpression(declaration)
+        || ts.isFunctionDeclaration(declaration)
+        || ts.isFunctionExpression(declaration)
+        || ts.isMethodDeclaration(declaration)
+    ) ?? false
+}

tests/fixture/myFunction.test.ts

@@ -0,0 +1 @@
+export function myFunction() {}

tests/fixture/myFunction.ts

@@ -0,0 +1 @@
+export function myFunction() {}

tests/fixture/tsconfig.json

@@ -2,5 +2,5 @@
 	"compilerOptions": {
 		"strict": true
 	},
-	"include": [ "file.ts", "react.tsx" ]
+	"include": [ "*.ts", "*.tsx" ]
 }