@tai-kun/vp-lint-plugins 0.0.4 → 0.0.5

package/src/rules/blank-line.ts

@@ -1,143 +1,601 @@
-import type { Fix, Fixer, ESTree, Comment, SourceCode } from "vite-plus/lint/plugins";
+import { defineRule } from "vite-plus/lint/plugins";
+import type { ESTree, Variable } from "vite-plus/lint/plugins";
 
-/**
- * 文の配列を持つ親から、その文が属する配列を取得します。
- */
-function getStatementBody(node: ESTree.Node): readonly ESTree.Node[] | null {
-  const { parent } = node;
+import {
+  isComment,
+  hasBlankLine,
+  isDocComment,
+  getBlankLineFix,
+  getInsertionTarget,
+  getRemoveBlankLineFix,
+} from "./blank-line-utils.js";
 
-  if (parent === null) {
-    return null;
+type ControlStatement =
+  | ESTree.DoWhileStatement
+  | ESTree.ForInStatement
+  | ESTree.ForOfStatement
+  | ESTree.ForStatement
+  | ESTree.IfStatement
+  | ESTree.SwitchStatement
+  | ESTree.TryStatement
+  | ESTree.WhileStatement;
+
+const CONTROL_STATEMENT_TYPES: ReadonlySet<ControlStatement["type"]> = new Set([
+  "DoWhileStatement",
+  "ForInStatement",
+  "ForOfStatement",
+  "ForStatement",
+  "IfStatement",
+  "SwitchStatement",
+  "TryStatement",
+  "WhileStatement",
+]);
+
+const DECLARATION_TYPES: ReadonlySet<string> = new Set([
+  "ClassDeclaration",
+  "FunctionDeclaration",
+  "TSDeclareFunction",
+  "TSEnumDeclaration",
+  "TSInterfaceDeclaration",
+  "TSModuleDeclaration",
+  "TSTypeAliasDeclaration",
+]);
+
+const SKIP_RETURN_PREVIOUS_TYPES: ReadonlySet<string> = new Set([
+  // 制御ブロックの後は afterControlBlock が担当するため、ここでは判定しません。
+  "DoWhileStatement",
+  "ForInStatement",
+  "ForOfStatement",
+  "ForStatement",
+  "IfStatement",
+  "SwitchStatement",
+  "TryStatement",
+  "WhileStatement",
+  // 宣言の後は afterDeclaration が担当するため、ここでは判定しません。
+  "ClassDeclaration",
+  "ExportAllDeclaration",
+  "ExportDefaultDeclaration",
+  "ExportNamedDeclaration",
+  "FunctionDeclaration",
+  "ImportDeclaration",
+  "TSDeclareFunction",
+  "TSEnumDeclaration",
+  "TSInterfaceDeclaration",
+  "TSModuleDeclaration",
+  "TSTypeAliasDeclaration",
+  // 途中で終わる文や空文の後は対象外にします。
+  "BlockStatement",
+  "BreakStatement",
+  "ContinueStatement",
+  "DebuggerStatement",
+  "EmptyStatement",
+  "LabeledStatement",
+  "ReturnStatement",
+  "ThrowStatement",
+  "WithStatement",
+]);
+
+interface BlankLineOptions {
+  afterControlBlock: boolean;
+  afterDeclaration: boolean;
+  afterVariableDeclaration: boolean;
+  beforeReturn: boolean;
+  betweenClassMembers: boolean;
+  betweenSwitchCases: boolean;
+  betweenTypeMembers: boolean;
+}
+
+const DEFAULT_OPTIONS: BlankLineOptions = {
+  beforeReturn: true,
+  afterDeclaration: true,
+  afterControlBlock: true,
+  betweenSwitchCases: true,
+  betweenTypeMembers: true,
+  betweenClassMembers: true,
+  afterVariableDeclaration: true,
+};
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function getFlag(option: Record<string, unknown>, key: keyof BlankLineOptions): boolean {
+  const value = option[key];
+
+  return value === undefined ? DEFAULT_OPTIONS[key] : value === true;
+}
+
+function getOptions(options: readonly unknown[]): BlankLineOptions {
+  const option = options[0];
+
+  if (!isObject(option)) {
+    return { ...DEFAULT_OPTIONS };
   }
 
-  if (
-    parent.type === "Program" ||
-    parent.type === "BlockStatement" ||
-    parent.type === "StaticBlock" ||
-    parent.type === "TSModuleBlock"
-  ) {
-    return parent.body;
+  return {
+    beforeReturn: getFlag(option, "beforeReturn"),
+    afterDeclaration: getFlag(option, "afterDeclaration"),
+    afterControlBlock: getFlag(option, "afterControlBlock"),
+    betweenSwitchCases: getFlag(option, "betweenSwitchCases"),
+    betweenTypeMembers: getFlag(option, "betweenTypeMembers"),
+    betweenClassMembers: getFlag(option, "betweenClassMembers"),
+    afterVariableDeclaration: getFlag(option, "afterVariableDeclaration"),
+  };
+}
+
+function isControlStatement(node: ESTree.Node): node is ControlStatement {
+  return CONTROL_STATEMENT_TYPES.has(node.type as ControlStatement["type"]);
+}
+
+function getDeclaration(node: ESTree.Node): ESTree.Node | null {
+  if (DECLARATION_TYPES.has(node.type)) {
+    return node;
   }
 
-  if (parent.type === "SwitchCase") {
-    return parent.consequent;
+  if (
+    (node.type === "ExportNamedDeclaration" || node.type === "ExportDefaultDeclaration") &&
+    node.declaration !== null &&
+    DECLARATION_TYPES.has(node.declaration.type)
+  ) {
+    return node.declaration;
   }
 
   return null;
 }
 
-function getNextStatement(node: ESTree.Node): ESTree.Node | null {
-  const body = getStatementBody(node);
+function isOverload(declaration: ESTree.Node): boolean {
+  return (
+    (declaration.type === "FunctionDeclaration" || declaration.type === "TSDeclareFunction") &&
+    declaration.body === null
+  );
+}
+
+function getVariableDeclaration(node: ESTree.Node): ESTree.VariableDeclaration | null {
+  if (node.type === "VariableDeclaration") {
+    return node;
+  }
 
-  if (body === null) {
-    return null;
+  if (node.type === "ExportNamedDeclaration" && node.declaration?.type === "VariableDeclaration") {
+    return node.declaration;
   }
 
-  const index = body.indexOf(node);
+  return null;
+}
+
+function isRelatedExpression(
+  statement: ESTree.Statement,
+  variables: ReadonlySet<Variable>,
+): boolean {
+  if (statement.type !== "ExpressionStatement") {
+    return false;
+  }
 
-  if (index === -1 || index === body.length - 1) {
-    return null;
+  for (const variable of variables) {
+    for (const reference of variable.references) {
+      if (
+        reference.identifier.range[0] >= statement.range[0] &&
+        reference.identifier.range[1] <= statement.range[1]
+      ) {
+        return true;
+      }
+    }
   }
 
-  return body[index + 1] ?? null;
+  return false;
 }
 
-function getPreviousStatement(node: ESTree.Node): ESTree.Node | null {
-  const body = getStatementBody(node);
+function isDirective(node: ESTree.Node): boolean {
+  return node.type === "ExpressionStatement" && typeof node.directive === "string";
+}
 
-  if (body === null) {
+function getKeyName(member: ESTree.ClassElement): string | null {
+  if (member.type === "TSIndexSignature" || member.type === "StaticBlock") {
     return null;
   }
 
-  const index = body.indexOf(node);
-
-  if (index <= 0) {
+  if (member.computed) {
     return null;
   }
 
-  return body[index - 1] ?? null;
-}
+  const key = member.key;
 
-/**
- * 空行の挿入位置を返します。
- *
- * 次の文に付くコメントがある場合は、そのコメントの前を挿入位置にします。
- * 同じ行の末尾コメントは対象外です。
- */
-function getInsertionTarget(
-  node: ESTree.Node,
-  nextStatement: ESTree.Node,
-  sourceCode: SourceCode,
-): ESTree.Node | Comment {
-  return (
-    sourceCode
-      .getAllComments()
-      .find(
-        (comment) =>
-          comment.range[0] >= node.range[1] &&
-          comment.range[1] <= nextStatement.range[0] &&
-          comment.loc.start.line > node.loc.end.line,
-      ) ?? nextStatement
-  );
+  if (key.type === "Identifier") {
+    return key.name;
+  }
+
+  if (key.type === "Literal" && (typeof key.value === "string" || typeof key.value === "number")) {
+    return String(key.value);
+  }
+
+  return null;
 }
 
-function hasBlankLine(node: ESTree.Node, target: ESTree.Node | Comment): boolean {
-  return target.loc.start.line > node.loc.end.line + 1;
+function isOverloadMember(member: ESTree.ClassElement): boolean {
+  return member.type === "MethodDefinition" && member.value.body === null;
 }
 
-function getBlankLineFix(
-  fixer: Fixer,
-  sourceCode: SourceCode,
-  node: ESTree.Node,
-  target: ESTree.Node | Comment,
-): Fix | null {
-  if (target.loc.start.line === node.loc.end.line) {
-    return fixer.insertTextAfterRange([node.range[1], node.range[1]], "\n\n");
+function isGetterSetterPair(previous: ESTree.ClassElement, next: ESTree.ClassElement): boolean {
+  if (previous.type !== "MethodDefinition" || next.type !== "MethodDefinition") {
+    return false;
+  }
+
+  if (
+    !(
+      (previous.kind === "get" && next.kind === "set") ||
+      (previous.kind === "set" && next.kind === "get")
+    )
+  ) {
+    return false;
   }
 
-  const lineEnd = sourceCode.text.indexOf("\n", node.range[1]);
+  const previousName = getKeyName(previous);
+  const nextName = getKeyName(next);
 
-  if (lineEnd === -1) {
-    return null;
+  return previousName !== null && previousName === nextName;
+}
+
+function getMemberStart(member: ESTree.ClassElement): ESTree.ClassElement | ESTree.Decorator {
+  if (member.type === "TSIndexSignature" || member.type === "StaticBlock") {
+    return member;
   }
 
-  return fixer.insertTextBeforeRange([lineEnd, lineEnd + 1], "\n");
+  return member.decorators[0] ?? member;
 }
 
 /**
- * 指定したノードと対象の間の空行を削除します。
+ * 宣言・制御ブロック・変数宣言グループ・return・クラスや型のメンバー・switch の case における空行を、1 つのルールでまとめて扱います。
+ *
+ * 文の境界ごとに該当する項目を 1 つだけ判定するため、複数の診断が同じ箇所で矛盾しません。
+ * 行コメントや通常のブロックコメントを挟む場合、前後の空行は任意とします。
  */
-function getRemoveBlankLineFix(
-  fixer: Fixer,
-  sourceCode: SourceCode,
-  node: ESTree.Node,
-  target: ESTree.Node | Comment,
-): Fix | null {
-  if (target.loc.start.line <= node.loc.end.line + 1) {
-    return null;
-  }
+const blankLine = defineRule({
+  meta: {
+    docs: {
+      description:
+        "Require blank lines between statements, class members, and switch cases, and above JSDoc-style block comments.",
+    },
+    type: "layout",
+    schema: [
+      {
+        type: "object",
+        properties: {
+          beforeReturn: { type: "boolean" },
+          afterDeclaration: { type: "boolean" },
+          afterControlBlock: { type: "boolean" },
+          betweenSwitchCases: { type: "boolean" },
+          betweenTypeMembers: { type: "boolean" },
+          betweenClassMembers: { type: "boolean" },
+          afterVariableDeclaration: { type: "boolean" },
+        },
+        additionalProperties: false,
+      },
+    ],
+    fixable: "whitespace",
+    messages: {
+      blankLine: "Expected a blank line here.",
+      unexpectedBlankLine:
+        "Expected no blank line between a variable declaration and its related statement.",
+    },
+  },
+  create(context) {
+    const sourceCode = context.sourceCode;
+    const options = getOptions(context.options);
 
-  const fromLineEnd = sourceCode.text.indexOf("\n", node.range[1]);
+    function requireBlankLine(
+      previous: ESTree.Node,
+      next: ESTree.Node,
+      reportNode: ESTree.Node,
+    ): void {
+      const target = getInsertionTarget(previous, next, sourceCode);
 
-  if (fromLineEnd === -1) {
-    return null;
-  }
+      // JSDoc 形式のブロックコメントの 1 行上は空行にします。
+      // それ以外のコメントを挟む場合、前後の空行は任意とします。
+      if (isComment(target) && !isDocComment(target)) {
+        return;
+      }
 
-  const targetLineStart = sourceCode.text.lastIndexOf("\n", target.range[0]) + 1;
-  const indent = sourceCode.text.slice(targetLineStart, target.range[0]);
+      if (hasBlankLine(previous, target)) {
+        return;
+      }
 
-  if (indent.trim() !== "") {
-    return null;
-  }
+      context.report({
+        fix(fixer) {
+          return getBlankLineFix(fixer, sourceCode, previous, target);
+        },
+        node: reportNode,
+        messageId: "blankLine",
+      });
+    }
 
-  return fixer.replaceTextRange([fromLineEnd, target.range[0]], `\n${indent}`);
-}
+    /**
+     * 変数宣言グループを収集します。
+     *
+     * 連続する変数宣言と、宣言した変数を使う式文を同じグループとして扱います。
+     * グループ開始でない場合は null を返します。
+     */
+    function collectVariableGroup(
+      body: readonly ESTree.Node[],
+      start: number,
+    ): {
+      variables: Set<Variable>;
+      statements: ESTree.Node[];
+    } | null {
+      const first = body[start];
 
-export {
-  hasBlankLine,
-  getBlankLineFix,
-  getNextStatement,
-  getInsertionTarget,
-  getPreviousStatement,
-  getRemoveBlankLineFix,
-};
+      if (first === undefined) {
+        return null;
+      }
+
+      const firstDeclaration = getVariableDeclaration(first);
+
+      if (firstDeclaration === null) {
+        return null;
+      }
+
+      const variables = new Set<Variable>(sourceCode.getDeclaredVariables(firstDeclaration));
+      const statements: ESTree.Node[] = [first];
+      let index = start + 1;
+
+      while (index < body.length) {
+        const next = body[index];
+
+        if (next === undefined) {
+          break;
+        }
+
+        const nextDeclaration = getVariableDeclaration(next);
+        const lastStatement = statements.at(-1);
+
+        if (
+          nextDeclaration !== null &&
+          lastStatement !== undefined &&
+          getVariableDeclaration(lastStatement) !== null
+        ) {
+          for (const variable of sourceCode.getDeclaredVariables(nextDeclaration)) {
+            variables.add(variable);
+          }
+
+          statements.push(next);
+          index += 1;
+          continue;
+        }
+
+        if (next.type === "ExpressionStatement" && isRelatedExpression(next, variables)) {
+          statements.push(next);
+          index += 1;
+          continue;
+        }
+
+        break;
+      }
+
+      return {
+        variables,
+        statements,
+      };
+    }
+
+    function checkVariableGroupBoundary(last: ESTree.Node, next: ESTree.Node | undefined): void {
+      if (next === undefined || next.type === "EmptyStatement") {
+        return;
+      }
+
+      if (next.type === "ReturnStatement") {
+        if (options.beforeReturn) {
+          requireBlankLine(last, next, next);
+        }
+
+        return;
+      }
+
+      if (options.afterVariableDeclaration) {
+        requireBlankLine(last, next, next);
+      }
+    }
+
+    function checkStatementBody(body: readonly ESTree.Node[]): void {
+      let index = 0;
+
+      while (index < body.length) {
+        const group =
+          options.afterVariableDeclaration || options.beforeReturn
+            ? collectVariableGroup(body, index)
+            : null;
+
+        if (group !== null) {
+          if (options.afterVariableDeclaration) {
+            for (let offset = 0; offset < group.statements.length - 1; offset += 1) {
+              const previous = group.statements[offset];
+              const next = group.statements[offset + 1];
+
+              if (previous === undefined || next === undefined) {
+                continue;
+              }
+
+              const target = getInsertionTarget(previous, next, sourceCode);
+
+              // JSDoc 形式のブロックコメントの 1 行上は空行にします。
+              if (isDocComment(target)) {
+                requireBlankLine(previous, next, next);
+                continue;
+              }
+
+              // 変数同士の境界は空行の有無を問いません。
+              if (next.type !== "ExpressionStatement") {
+                continue;
+              }
+
+              if (isComment(target) || !hasBlankLine(previous, target)) {
+                continue;
+              }
+
+              context.report({
+                fix(fixer) {
+                  return getRemoveBlankLineFix(fixer, sourceCode, previous, target);
+                },
+                node: next,
+                messageId: "unexpectedBlankLine",
+              });
+            }
+          }
+
+          const last = group.statements.at(-1);
+          const next = body[index + group.statements.length];
+
+          if (last === undefined) {
+            index += group.statements.length;
+            continue;
+          }
+
+          checkVariableGroupBoundary(last, next);
+
+          index += group.statements.length;
+          continue;
+        }
+
+        const previous = body[index];
+        const next = body[index + 1];
+
+        if (previous === undefined || next === undefined || next.type === "EmptyStatement") {
+          index += 1;
+          continue;
+        }
+
+        if (isControlStatement(previous)) {
+          if (options.afterControlBlock) {
+            requireBlankLine(previous, next, previous);
+          }
+
+          index += 1;
+          continue;
+        }
+
+        const declaration = getDeclaration(previous);
+
+        if (declaration !== null) {
+          if (!isOverload(declaration) && options.afterDeclaration) {
+            requireBlankLine(previous, next, previous);
+          }
+
+          index += 1;
+          continue;
+        }
+
+        if (next.type === "ReturnStatement") {
+          if (
+            options.beforeReturn &&
+            !SKIP_RETURN_PREVIOUS_TYPES.has(previous.type) &&
+            !isDirective(previous)
+          ) {
+            requireBlankLine(previous, next, next);
+          }
+
+          index += 1;
+          continue;
+        }
+
+        index += 1;
+      }
+    }
+
+    /**
+     * 型や interface のメンバー境界を確認します。
+     *
+     * メンバー間の空行は要求せず、JSDoc 形式のブロックコメントの 1 行上だけ空行を要求します。
+     */
+    function checkTypeMembers(members: readonly ESTree.TSSignature[]): void {
+      for (let index = 1; index < members.length; index += 1) {
+        const previous = members[index - 1];
+        const next = members[index];
+
+        if (previous === undefined || next === undefined) {
+          continue;
+        }
+
+        const target = getInsertionTarget(previous, next, sourceCode);
+
+        if (!isDocComment(target) || hasBlankLine(previous, target)) {
+          continue;
+        }
+
+        context.report({
+          fix(fixer) {
+            return getBlankLineFix(fixer, sourceCode, previous, target);
+          },
+          node: next,
+          messageId: "blankLine",
+        });
+      }
+    }
+
+    return {
+      Program(node): void {
+        checkStatementBody(node.body);
+      },
+      ClassBody(node): void {
+        if (!options.betweenClassMembers) {
+          return;
+        }
+
+        for (let index = 1; index < node.body.length; index += 1) {
+          const previous = node.body[index - 1];
+          const next = node.body[index];
+
+          if (previous === undefined || next === undefined) {
+            continue;
+          }
+
+          if (isOverloadMember(previous) || isGetterSetterPair(previous, next)) {
+            continue;
+          }
+
+          requireBlankLine(previous, getMemberStart(next), next);
+        }
+      },
+      SwitchCase(node): void {
+        checkStatementBody(node.consequent);
+      },
+      StaticBlock(node): void {
+        checkStatementBody(node.body);
+      },
+      TSModuleBlock(node): void {
+        checkStatementBody(node.body);
+      },
+      TSTypeLiteral(node): void {
+        if (!options.betweenTypeMembers) {
+          return;
+        }
+
+        checkTypeMembers(node.members);
+      },
+      BlockStatement(node): void {
+        checkStatementBody(node.body);
+      },
+      SwitchStatement(node): void {
+        if (!options.betweenSwitchCases) {
+          return;
+        }
+
+        for (let index = 1; index < node.cases.length; index += 1) {
+          const previous = node.cases[index - 1];
+          const next = node.cases[index];
+
+          if (previous === undefined || next === undefined || previous.consequent.length === 0) {
+            continue;
+          }
+
+          requireBlankLine(previous, next, next);
+        }
+      },
+      TSInterfaceBody(node): void {
+        if (!options.betweenTypeMembers) {
+          return;
+        }
+
+        checkTypeMembers(node.body);
+      },
+    };
+  },
+});
+
+export default blankLine;