eslint-plugin-jest-formatting 1.0.0 → 2.0.0

package/src/rules/padding.ts

@@ -1,115 +1,144 @@
 /**
- * @fileoverview Rule to require or disallow newlines between jest functions
- *   Based on eslint/padding-line-between-statements by Toru Nagashima
- *   See: https://github.com/eslint/eslint/blob/master/lib/rules/padding-line-between-statements.js
+ * Require/fix newlines around jest functions
  *
- *   STATEMENT_LIST_PARENTS, isTokenOnSameLine and isSemiColonToken borrowed from
- *   eslint ast-utils by Gyandeep Singh
- *   See: https://github.com/eslint/eslint/blob/master/lib/rules/utils/ast-utils.js
+ * Based on eslint/padding-line-between-statements by Toru Nagashima
+ * See: https://github.com/eslint/eslint/blob/master/lib/rules/padding-line-between-statements.js
+ *
+ * Some helpers borrowed from eslint ast-utils by Gyandeep Singh
+ * See: https://github.com/eslint/eslint/blob/master/lib/rules/utils/ast-utils.js
  */
+
 import { AST, Rule, SourceCode } from 'eslint';
+// This is because we are using @types/estree that are brought in with eslint
+// eslint-disable-next-line import/no-extraneous-dependencies
 import { Node } from 'estree';
+import * as astUtils from '../ast-utils';
+
+// Statement types we'll respond to
+export const enum StatementType {
+  Any,
+  AfterAllToken,
+  AfterEachToken,
+  BeforeAllToken,
+  BeforeEachToken,
+  DescribeToken,
+  ExpectToken,
+  FdescribeToken,
+  FitToken,
+  ItToken,
+  TestToken,
+  XdescribeToken,
+  XitToken,
+  XtestToken,
+}
 
-type StatementTypeTester = {
-  [test: string]: (node: Node, sourceCode: SourceCode) => boolean;
-};
+type StatementTypes = StatementType | StatementType[];
 
-type PaddingTypeTester = {
-  [verify: string]: (
-    context: Rule.RuleContext,
-    prevNode: Node,
-    nextNode: Node,
-    paddingLines: AST.Token[][],
-  ) => void;
-};
+type StatementTester = (node: Node, sourceCode: SourceCode) => boolean;
 
-const STATEMENT_LIST_PARENTS = new Set([
-  'Program',
-  'BlockStatement',
-  'SwitchCase',
-  'SwitchStatement',
-]);
+// Padding type to apply between statements
+export const enum PaddingType {
+  Any,
+  Always,
+}
 
-const isTokenOnSameLine = (
-  left: Node | AST.Token,
-  right: Node | AST.Token,
-): boolean => left.loc.end.line === right.loc.start.line;
+type PaddingTester = (
+  prevNode: Node,
+  nextNode: Node,
+  paddingContext: PaddingContext,
+) => void;
+
+// A configuration object for padding type and the two statement types
+export interface Config {
+  paddingType: PaddingType;
+  prevStatementType: StatementTypes;
+  nextStatementType: StatementTypes;
+}
 
-const isSemicolonToken = (token: AST.Token): boolean =>
-  token.value === ';' && token.type === 'Punctuator';
+// Tracks position in scope and prevNode. Used to compare current and prev node
+// and then to walk back up to the parent scope or down into the next one.
+// And so on...
+interface Scope {
+  upper: Scope | null;
+  prevNode: Node | null;
+}
 
-// NOTE: Should probably be configurable
-const isTestFile = (filename: string): boolean =>
-  filename.includes('test') || filename.includes('spec');
+interface ScopeInfo {
+  prevNode: Node | null;
+  enter: () => void;
+  exit: () => void;
+}
 
-/**
- * Creates tester which check if an expression node has a certain name
- */
-function newJestTokenTester(name: string): StatementTypeTester {
-  return {
-    test: (node: Node, sourceCode: SourceCode): boolean => {
-      const token = sourceCode.getFirstToken(node);
-
-      return (
-        node.type === 'ExpressionStatement' &&
-        token.type === 'Identifier' &&
-        token.value === name
-      );
-    },
-  };
+interface PaddingContext {
+  ruleContext: Rule.RuleContext;
+  sourceCode: SourceCode;
+  scopeInfo: ScopeInfo;
+  configs: Config[];
 }
 
-/**
- * Gets the actual last token.
- *
- * If a semicolon is semicolon-less style's semicolon, this ignores it.
- * For example:
- *
- *     foo()
- *     ;[1, 2, 3].forEach(bar)
- */
-function getActualLastToken(sourceCode: SourceCode, node: Node): AST.Token {
-  const semiToken = sourceCode.getLastToken(node);
-  const prevToken = sourceCode.getTokenBefore(semiToken);
-  const nextToken = sourceCode.getTokenAfter(semiToken);
-  const isSemicolonLessStyle = Boolean(
-    prevToken &&
-      nextToken &&
-      prevToken.range[0] >= node.range[0] &&
-      isSemicolonToken(semiToken) &&
-      semiToken.loc.start.line !== prevToken.loc.end.line &&
-      semiToken.loc.end.line === nextToken.loc.start.line,
-  );
+// Creates a StatementTester to test an ExpressionStatement's first token name
+const createTokenTester = (tokenName: string): StatementTester => {
+  return (node: Node, sourceCode: SourceCode): boolean => {
+    const token = sourceCode.getFirstToken(node);
 
-  return isSemicolonLessStyle ? prevToken : semiToken;
-}
+    return (
+      node.type === 'ExpressionStatement' &&
+      token.type === 'Identifier' &&
+      token.value === tokenName
+    );
+  };
+};
+
+// A mapping of StatementType to StatementTester for... testing statements
+const statementTesters: { [T in StatementType]: StatementTester } = {
+  [StatementType.Any]: () => true,
+  [StatementType.AfterAllToken]: createTokenTester('afterAll'),
+  [StatementType.AfterEachToken]: createTokenTester('afterEach'),
+  [StatementType.BeforeAllToken]: createTokenTester('beforeAll'),
+  [StatementType.BeforeEachToken]: createTokenTester('beforeEach'),
+  [StatementType.DescribeToken]: createTokenTester('describe'),
+  [StatementType.ExpectToken]: createTokenTester('expect'),
+  [StatementType.FdescribeToken]: createTokenTester('fdescribe'),
+  [StatementType.FitToken]: createTokenTester('fit'),
+  [StatementType.ItToken]: createTokenTester('it'),
+  [StatementType.TestToken]: createTokenTester('test'),
+  [StatementType.XdescribeToken]: createTokenTester('xdescribe'),
+  [StatementType.XitToken]: createTokenTester('xit'),
+  [StatementType.XtestToken]: createTokenTester('xtest'),
+};
 
 /**
- * Check and report statements for `always` configuration.
+ * Check and report statements for `PaddingType.Always` configuration.
  * This autofix inserts a blank line between the given 2 statements.
  * If the `prevNode` has trailing comments, it inserts a blank line after the
  * trailing comments.
  */
-function verifyForAlways(
-  context: Rule.RuleContext,
+const paddingAlwaysTester = (
   prevNode: Node,
   nextNode: Node,
-  paddingLines: AST.Token[],
-): void {
+  paddingContext: PaddingContext,
+): void => {
+  const { sourceCode, ruleContext } = paddingContext;
+  const paddingLines = astUtils.getPaddingLineSequences(
+    prevNode,
+    nextNode,
+    sourceCode,
+  );
+
+  // We've got some padding lines. Great.
   if (paddingLines.length > 0) {
     return;
   }
 
-  context.report({
+  // Missing padding line
+  ruleContext.report({
     node: nextNode,
     message: 'Expected blank line before this statement.',
     fix(fixer: Rule.RuleFixer): Rule.Fix {
-      const sourceCode = context.getSourceCode();
-      let prevToken = getActualLastToken(sourceCode, prevNode);
+      let prevToken = astUtils.getActualLastToken(sourceCode, prevNode);
       const nextToken =
         sourceCode.getFirstTokenBetween(prevToken, nextNode, {
           includeComments: true,
-
           /**
            * Skip the trailing comments of the previous node.
            * This inserts a blank line after the last trailing comment.
@@ -128,7 +157,7 @@ function verifyForAlways(
            *     bar();
            */
           filter(token: AST.Token): boolean {
-            if (isTokenOnSameLine(prevToken, token)) {
+            if (astUtils.areTokensOnSameLine(prevToken, token)) {
               prevToken = token;
               return false;
             }
@@ -137,203 +166,185 @@ function verifyForAlways(
           },
         }) || nextNode;
 
-      const insertText = isTokenOnSameLine(prevToken, nextToken)
+      const insertText = astUtils.areTokensOnSameLine(prevToken, nextToken)
         ? '\n\n'
         : '\n';
 
       return fixer.insertTextAfter(prevToken, insertText);
     },
   });
-}
-
-/**
- * Types of blank lines.
- * `any`  and `always` are defined.
- * Those have `verify` method to check and report statements.
- */
-const PaddingTypes = {
-  any: { verify: () => {} },
-  always: { verify: verifyForAlways },
 };
 
-/**
- * Types of statements.
- * Those have `test` method to check it matches to the given statement.
- */
-const StatementTypes = {
-  '*': { test: () => true },
-  afterAll: newJestTokenTester('afterAll'),
-  afterEach: newJestTokenTester('afterEach'),
-  beforeAll: newJestTokenTester('beforeAll'),
-  beforeEach: newJestTokenTester('beforeEach'),
-  describe: newJestTokenTester('describe'),
-  expect: newJestTokenTester('expect'),
-  it: newJestTokenTester('it'),
-  test: newJestTokenTester('test'),
+// A mapping of PaddingType to PaddingTester
+const paddingTesters: { [T in PaddingType]: PaddingTester } = {
+  [PaddingType.Any]: () => true,
+  [PaddingType.Always]: paddingAlwaysTester,
 };
 
-//------------------------------------------------------------------------------
-// Rule Definition
-//------------------------------------------------------------------------------
+const createScopeInfo = (): ScopeInfo => {
+  return (() => {
+    let scope: Scope = null;
 
-export default <Rule.RuleModule>{
-  meta: {
-    fixable: 'whitespace',
-    schema: {
-      definitions: {
-        paddingType: {
-          enum: Object.keys(PaddingTypes),
-        },
-        statementType: {
-          anyOf: [
-            { enum: Object.keys(StatementTypes) },
-            {
-              type: 'array',
-              items: { enum: Object.keys(StatementTypes) },
-              minItems: 1,
-              uniqueItems: true,
-              additionalItems: false,
-            },
-          ],
-        },
+    return {
+      get prevNode() {
+        return scope.prevNode;
       },
-      type: 'array',
-      items: {
-        type: 'object',
-        properties: {
-          blankLine: { $ref: '#/definitions/paddingType' },
-          prev: { $ref: '#/definitions/statementType' },
-          next: { $ref: '#/definitions/statementType' },
-        },
-        additionalProperties: false,
-        required: ['blankLine', 'prev', 'next'],
+      set prevNode(node) {
+        scope.prevNode = node;
       },
-      additionalItems: false,
-    },
-  },
-  create(context: Rule.RuleContext): Rule.RuleListener {
-    const filename = context.getFilename();
-
-    if (!isTestFile(filename)) {
-      return {};
-    }
-
-    const sourceCode = context.getSourceCode();
-    const configureList = context.options || [];
-    let scopeInfo = null;
-
-    function enterScope(): void {
-      scopeInfo = { upper: scopeInfo, prevNode: null };
-    }
-
-    function exitScope(): void {
-      scopeInfo = scopeInfo.upper;
-    }
-
-    /**
-     * Checks whether the given node matches the given type.
-     */
-    function match(node: Node, type: string | string[]): boolean {
-      let innerStatementNode = node;
-
-      while (innerStatementNode.type === 'LabeledStatement') {
-        innerStatementNode = innerStatementNode.body;
-      }
-
-      if (Array.isArray(type)) {
-        return type.some(match.bind(null, innerStatementNode));
-      }
-
-      return StatementTypes[type].test(innerStatementNode, sourceCode);
-    }
+      enter() {
+        scope = { upper: scope, prevNode: null };
+      },
+      exit() {
+        scope = scope.upper;
+      },
+    };
+  })();
+};
 
-    /**
-     * Finds the last matched configure from configureList.
-     */
-    function getPaddingType(prevNode: Node, nextNode: Node): PaddingTypeTester {
-      for (let i = configureList.length - 1; i >= 0; --i) {
-        const { prev, next, blankLine } = configureList[i];
+/**
+ * Check whether the given node matches the statement type
+ */
+const nodeMatchesType = (
+  node: Node,
+  statementType: StatementTypes,
+  paddingContext: PaddingContext,
+): boolean => {
+  let innerStatementNode = node;
+  const { sourceCode } = paddingContext;
+
+  // Dig into LabeledStatement body until it's not that anymore
+  while (innerStatementNode.type === 'LabeledStatement') {
+    innerStatementNode = innerStatementNode.body;
+  }
 
-        if (match(prevNode, prev) && match(nextNode, next)) {
-          return PaddingTypes[blankLine];
-        }
-      }
+  // If it's an array recursively check if any of the statement types match
+  // the node
+  if (Array.isArray(statementType)) {
+    return statementType.some((type) =>
+      nodeMatchesType(innerStatementNode, type, paddingContext),
+    );
+  }
 
-      return PaddingTypes.any;
-    }
+  return statementTesters[statementType](innerStatementNode, sourceCode);
+};
 
-    /**
-     * Gets padding line sequences between the given 2 statements.
-     * Comments are separators of the padding line sequences.
-     */
-    function getPaddingLineSequences(
-      prevNode: Node,
-      nextNode: Node,
-    ): AST.Token[][] {
-      const pairs: AST.Token[][] = [];
-      let prevToken = getActualLastToken(sourceCode, prevNode);
-
-      if (nextNode.loc.start.line - prevToken.loc.end.line >= 2) {
-        do {
-          const token = sourceCode.getTokenAfter(prevToken, {
-            includeComments: true,
-          });
-
-          if (token.loc.start.line - prevToken.loc.end.line >= 2) {
-            pairs.push([prevToken, token]);
-          }
-
-          prevToken = token;
-        } while (prevToken.range[0] < nextNode.range[0]);
-      }
-
-      return pairs;
+/**
+ * Executes matching padding tester for last matched padding config for given
+ * nodes
+ */
+const testPadding = (
+  prevNode: Node,
+  nextNode: Node,
+  paddingContext: PaddingContext,
+): void => {
+  const { configs } = paddingContext;
+
+  const testType = (type: PaddingType) =>
+    paddingTesters[type](prevNode, nextNode, paddingContext);
+
+  for (let i = configs.length - 1; i >= 0; --i) {
+    const {
+      prevStatementType: prevType,
+      nextStatementType: nextType,
+      paddingType,
+    } = configs[i];
+
+    if (
+      nodeMatchesType(prevNode, prevType, paddingContext) &&
+      nodeMatchesType(nextNode, nextType, paddingContext)
+    ) {
+      return testType(paddingType);
     }
+  }
 
-    /**
-     * Verify padding lines between the given node and the previous node.
-     */
-    function verify(node): void {
-      const parentType = node.parent.type;
-      const validParent = STATEMENT_LIST_PARENTS.has(parentType);
-
-      if (!validParent) {
-        return;
-      }
+  // There were no matching padding rules for the prevNode, nextNode,
+  // paddingType combination... so we'll use PaddingType.Any which is always ok
+  return testType(PaddingType.Any);
+};
 
-      // Save this node as the current previous statement.
-      const { prevNode } = scopeInfo;
+/**
+ * Verify padding lines between the given node and the previous node.
+ */
+const verifyNode = (node: Node, paddingContext: PaddingContext): void => {
+  const { scopeInfo } = paddingContext;
+
+  // NOTE: ESLint types use ESTree which provides a Node type, however
+  //  ESTree.Node doesn't support the parent property which is added by
+  //  ESLint during traversal. Our best bet is to ignore the property access
+  //  here as it's the only place that it's checked.
+  //  eslint-disable-next-line @typescript-eslint/no-explicit-any
+  if (!astUtils.isValidParent((node as any).parent.type)) {
+    return;
+  }
 
-      // Verify.
-      if (prevNode) {
-        const type = getPaddingType(prevNode, node);
-        const paddingLines = getPaddingLineSequences(prevNode, node);
+  if (scopeInfo.prevNode) {
+    testPadding(scopeInfo.prevNode, node, paddingContext);
+  }
 
-        type.verify(context, prevNode, node, paddingLines);
-      }
+  scopeInfo.prevNode = node;
+};
 
-      scopeInfo.prevNode = node;
-    }
+/**
+ * Creates an ESLint rule for a given set of padding Config objects.
+ *
+ * The algorithm is approximately this:
+ *
+ * For each 'scope' in the program
+ * - Enter the scope (store the parent scope and previous node)
+ * - For each statement in the scope
+ *   - Check the current node and previous node against the Config objects
+ *   - If the current node and previous node match a Config, check the padding.
+ *     Otherwise, ignore it.
+ *   - If the padding is missing (and required), report and fix
+ *   - Store the current node as the previous
+ *   - Repeat
+ * - Exit scope (return to parent scope and clear previous node)
+ *
+ * The items we're looking for with this rule are ExpressionStatement nodes
+ * where the first token is an Identifier with a name matching one of the Jest
+ * functions. It's not foolproof, of course, but it's probably good enough for
+ * almost all cases.
+ *
+ * The Config objects specify a padding type, a previous statement type, and a
+ * next statement type. Wildcard statement types and padding types are
+ * supported. The current node and previous node are checked against the
+ * statement types. If they match then the specified padding type is
+ * tested/enforced.
+ *
+ * See src/index.ts for examples of Config usage.
+ */
+export const createRule = (
+  configs: Config[],
+  deprecated = false,
+): Rule.RuleModule => ({
+  meta: {
+    fixable: 'whitespace',
+    deprecated,
+  },
+  create(context: Rule.RuleContext) {
+    const paddingContext = {
+      ruleContext: context,
+      sourceCode: context.getSourceCode(),
+      scopeInfo: createScopeInfo(),
+      configs,
+    };
 
-    /**
-     * Verify padding lines between the given node and the previous node.
-     * Then process to enter to new scope.
-     */
-    function verifyThenEnterScope(node: Node): void {
-      verify(node);
-      enterScope();
-    }
+    const { scopeInfo } = paddingContext;
 
     return {
-      Program: enterScope,
-      BlockStatement: enterScope,
-      SwitchStatement: enterScope,
-      'Program:exit': exitScope,
-      'BlockStatement:exit': exitScope,
-      'SwitchStatement:exit': exitScope,
-      ':statement': verify,
-      SwitchCase: verifyThenEnterScope,
-      'SwitchCase:exit': exitScope,
+      Program: scopeInfo.enter,
+      'Program:exit': scopeInfo.enter,
+      BlockStatement: scopeInfo.enter,
+      'BlockStatement:exit': scopeInfo.exit,
+      SwitchStatement: scopeInfo.enter,
+      'SwitchStatement:exit': scopeInfo.exit,
+      ':statement': (node: Node) => verifyNode(node, paddingContext),
+      SwitchCase: (node: Node) => {
+        verifyNode(node, paddingContext);
+        scopeInfo.enter();
+      },
+      'SwitchCase:exit': scopeInfo.exit,
     };
   },
-};
+});

package/tests/catfood.js

@@ -0,0 +1,41 @@
+/**
+ * This file should be IGNORED by jest-formatting due to the `overrides.files`
+ * value in `recommended` and `strict` config. This file does not match the
+ * globs.
+ */
+
+/* eslint-disable @typescript-eslint/no-empty-function */
+
+beforeAll(() => {});
+beforeEach(() => {});
+afterAll(() => {});
+afterEach(() => {});
+describe('no padding on top', () => {
+  it('has no padding above', () => {
+    expect(true);
+  });
+  expect(true);
+  expect(1);
+  xit('has padding above', () => {
+    expect(true);
+  });
+  it('also has padding above but not below', () => {
+    expect(true);
+  });
+});
+xdescribe('padding above', () => {
+  it('has no padding above or below', () => {
+    expect(true);
+  });
+  it('has no padding above or below', () => {
+    expect(true);
+  });
+});
+describe('padding above', () => {
+  it('has no padding above or below', () => {
+    expect(true);
+  });
+  it('has no padding above or below', () => {
+    expect(true);
+  });
+});

package/tests/dogfood.spec.js

@@ -1,3 +1,5 @@
+/* eslint-disable @typescript-eslint/no-empty-function */
+
 beforeAll(() => {});
 
 beforeEach(() => {});