feat(rules): add require-top-level-describe rule

docs/rules/require-top-level-describe.md

@@ -0,0 +1,47 @@
+# Require top-level describe block (require-top-level-describe)
+
+Jest allows you to organise your test files the way you want it. However, the
+more your codebase grows, the more it becomes hard to navigate in your test
+files. This rule makes sure that you provide at least a top-level describe block
+in your test file.
+
+## Rule Details
+
+This rule triggers a warning if a test case (`test` and `it`) or a hook
+(`beforeAll`, `beforeEach`, `afterEach`, `afterAll`) is not located in a
+top-level describe block.
+
+The following patterns are considered warnings:
+
+```js
+// Above a describe block
+test('my test', () => {});
+describe('test suite', () => {
+  it('test', () => {});
+});
+
+// Below a describe block
+describe('test suite', () => {});
+test('my test', () => {});
+```
+
+The following patterns are **not** considered warnings:
+
+```js
+// In a describe block
+describe('test suite', () => {
+  test('my test', () => {});
+});
+
+// In a nested describe block
+describe('test suite', () => {
+  test('my test', () => {});
+  describe('another test suite', () => {
+    test('my other test', () => {});
+  });
+});
+```
+
+## When Not To Use It
+
+Don't use this rule on non-jest test files.

src/__tests__/rules.test.ts

@@ -3,7 +3,7 @@ import { resolve } from 'path';
 import plugin from '../';
 
 const ruleNames = Object.keys(plugin.rules);
-const numberOfRules = 38;
+const numberOfRules = 39;
 
 describe('rules', () => {
   it('should have a corresponding doc for each rule', () => {

src/rules/__tests__/require-top-level-describe.test.ts

@@ -0,0 +1,58 @@
+import { TSESLint } from '@typescript-eslint/experimental-utils';
+import rule from '../require-top-level-describe';
+
+const ruleTester = new TSESLint.RuleTester({
+  parserOptions: {
+    ecmaVersion: 2015,
+  },
+});
+
+ruleTester.run('no-standalone-hook', rule, {
+  valid: [
+    'describe("test suite", () => { test("my test") });',
+    'describe("test suite", () => { it("my test") });',
+    `
+    describe("test suite", () => {
+      beforeEach("a", () => {}); 
+      describe("b", () => {}); 
+      test("c", () => {})
+    });
+    `,
+    'describe("test suite", () => { beforeAll("my beforeAll") });',
+    'describe("test suite", () => { afterEach("my afterEach") });',
+    'describe("test suite", () => { afterAll("my afterAll") });',
+    `
+    describe("test suite", () => {
+      it("my test", () => {})
+      describe("another test suite", () => {
+      });
+      test("my other test", () => {})
+    });
+    `,
+  ],
+  invalid: [
+    {
+      code: `
+      test("my test", () => {})
+      describe("test suite", () => {});
+      `,
+      errors: [{ messageId: 'unexpectedMethod' }],
+    },
+    {
+      code: `
+      test("my test", () => {})
+      describe("test suite", () => {
+        it("test", () => {})
+      });
+      `,
+      errors: [{ messageId: 'unexpectedMethod' }],
+    },
+    {
+      code: `
+      describe("test suite", () => {});
+      afterAll("my test", () => {})
+      `,
+      errors: [{ messageId: 'unexpectedMethod' }],
+    },
+  ],
+});

src/rules/require-top-level-describe.ts

@@ -0,0 +1,37 @@
+import { TSESTree } from '@typescript-eslint/experimental-utils';
+
+import { createRule, isDescribe, isHook, isTestCase } from './utils';
+
+export default createRule({
+  name: __filename,
+  meta: {
+    docs: {
+      category: 'Best Practices',
+      description:
+        'Prevents test cases and hooks to be outside of a describe block',
+      recommended: false,
+    },
+    messages: {
+      unexpectedMethod: 'There must be a top-level describe block.',
+    },
+    type: 'suggestion',
+    schema: [],
+  },
+  defaultOptions: [],
+  create(context) {
+    let numberOfDescribeBlock = 0;
+    return {
+      CallExpression(node) {
+        isDescribe(node) && numberOfDescribeBlock++;
+        if ((isTestCase(node) || isHook(node)) && numberOfDescribeBlock === 0) {
+          context.report({ node, messageId: 'unexpectedMethod' });
+        }
+      },
+      'CallExpression:exit'(node: TSESTree.CallExpression) {
+        if (isDescribe(node)) {
+          numberOfDescribeBlock--;
+        }
+      },
+    };
+  },
+});