feat(lowercase-name): support ignoreTopLevelDescribe option (#611)

closes #247

Author: G-Rath

docs/rules/lowercase-name.md

@@ -86,3 +86,21 @@ Example of **correct** code for the `{ "allowedPrefixes": ["GET"] }` option:
 
 describe('GET /live');
 ```
+
+### `ignoreTopLevelDescribe`
+
+This option can be set to allow only the top-level `describe` blocks to have a
+title starting with an upper-case letter.
+
+Example of **correct** code for the `{ "ignoreTopLevelDescribe": true }` option:
+
+```js
+/* eslint jest/lowercase-name: ["error", { "ignoreTopLevelDescribe": true }] */
+describe('MyClass', () => {
+  describe('#myMethod', () => {
+    it('does things', () => {
+      //
+    });
+  });
+});
+```

src/rules/__tests__/lowercase-name.test.ts

@@ -1,4 +1,5 @@
 import { TSESLint } from '@typescript-eslint/experimental-utils';
+import dedent from 'dedent';
 import resolveFrom from 'resolve-from';
 import rule from '../lowercase-name';
 import { DescribeAlias, TestCaseName } from '../utils';
@@ -251,3 +252,115 @@ ruleTester.run('lowercase-name with allowedPrefixes', rule, {
   ],
   invalid: [],
 });
+
+ruleTester.run('lowercase-name with ignoreTopLevelDescribe', rule, {
+  valid: [
+    {
+      code: 'describe("MyClass", () => {});',
+      options: [{ ignoreTopLevelDescribe: true }],
+    },
+    {
+      code: dedent`
+        describe('MyClass', () => {
+          describe('#myMethod', () => {
+            it('does things', () => {
+              //
+            });
+          });
+        });
+      `,
+      options: [{ ignoreTopLevelDescribe: true }],
+    },
+  ],
+  invalid: [
+    {
+      code: 'it("Works!", () => {});',
+      options: [{ ignoreTopLevelDescribe: true }],
+      output: 'it("works!", () => {});',
+      errors: [
+        {
+          messageId: 'unexpectedLowercase',
+          data: { method: TestCaseName.it },
+          column: 4,
+          line: 1,
+        },
+      ],
+    },
+    {
+      code: dedent`
+        describe('MyClass', () => {
+          describe('MyMethod', () => {
+            it('Does things', () => {
+              //
+            });
+          });
+        });
+      `,
+      options: [{ ignoreTopLevelDescribe: true }],
+      output: dedent`
+        describe('MyClass', () => {
+          describe('myMethod', () => {
+            it('does things', () => {
+              //
+            });
+          });
+        });
+      `,
+      errors: [
+        {
+          messageId: 'unexpectedLowercase',
+          data: { method: DescribeAlias.describe },
+          column: 12,
+          line: 2,
+        },
+        {
+          messageId: 'unexpectedLowercase',
+          data: { method: TestCaseName.it },
+          column: 8,
+          line: 3,
+        },
+      ],
+    },
+    {
+      code: dedent`
+        describe('MyClass', () => {
+          describe('MyMethod', () => {
+            it('Does things', () => {
+              //
+            });
+          });
+        });
+      `,
+      options: [{ ignoreTopLevelDescribe: false }],
+      output: dedent`
+        describe('myClass', () => {
+          describe('myMethod', () => {
+            it('does things', () => {
+              //
+            });
+          });
+        });
+      `,
+      errors: [
+        {
+          messageId: 'unexpectedLowercase',
+          data: { method: DescribeAlias.describe },
+          column: 10,
+          line: 1,
+        },
+        {
+          messageId: 'unexpectedLowercase',
+          data: { method: DescribeAlias.describe },
+          column: 12,
+          line: 2,
+        },
+        {
+          messageId: 'unexpectedLowercase',
+          data: { method: TestCaseName.it },
+          column: 8,
+          line: 3,
+        },
+      ],
+    },
+  ],
+});

src/rules/lowercase-name.ts

@@ -62,6 +62,7 @@ export default createRule<
     Partial<{
       ignore: readonly IgnorableFunctionExpressions[];
       allowedPrefixes: readonly string[];
+      ignoreTopLevelDescribe: boolean;
     }>,
   ],
   'unexpectedLowercase'
@@ -98,18 +99,38 @@ export default createRule<
             items: { type: 'string' },
             additionalItems: false,
           },
+          ignoreTopLevelDescribe: {
+            type: 'boolean',
+            default: false,
+          },
         },
         additionalProperties: false,
       },
     ],
   } as const,
-  defaultOptions: [{ ignore: [], allowedPrefixes: [] }],
-  create(context, [{ ignore = [], allowedPrefixes = [] }]) {
+  defaultOptions: [
+    { ignore: [], allowedPrefixes: [], ignoreTopLevelDescribe: false },
+  ],
+  create(
+    context,
+    [{ ignore = [], allowedPrefixes = [], ignoreTopLevelDescribe }],
+  ) {
+    let numberOfDescribeBlocks = 0;
+
     return {
       CallExpression(node: TSESTree.CallExpression) {
         if (!isJestFunctionWithLiteralArg(node)) {
           return;
         }
+
+        if (isDescribe(node)) {
+          numberOfDescribeBlocks++;
+
+          if (ignoreTopLevelDescribe && numberOfDescribeBlocks === 1) {
+            return;
+          }
+        }
+
         const erroneousMethod = jestFunctionName(node, allowedPrefixes);
 
         if (erroneousMethod && !ignore.includes(node.callee.name)) {