[clang-tidy] add new check readability-enum-initial-value (#86129)

Fixes: #85243.

9 files changed, 431 insertions, 0 deletions

diff --git a/clang-tools-extra/clang-tidy/readability/CMakeLists.txt b/clang-tools-extra/clang-tidy/readability/CMakeLists.txt
index 5728c99..dd772d6 100644
--- a/clang-tools-extra/clang-tidy/readability/CMakeLists.txt
+++ b/clang-tools-extra/clang-tidy/readability/CMakeLists.txt
@@ -17,6 +17,7 @@ add_clang_library(clangTidyReadabilityModule
   DeleteNullPointerCheck.cpp
   DuplicateIncludeCheck.cpp
   ElseAfterReturnCheck.cpp
+  EnumInitialValueCheck.cpp
   FunctionCognitiveComplexityCheck.cpp
   FunctionSizeCheck.cpp
   IdentifierLengthCheck.cpp
diff --git a/clang-tools-extra/clang-tidy/readability/EnumInitialValueCheck.cpp b/clang-tools-extra/clang-tidy/readability/EnumInitialValueCheck.cpp
new file mode 100644
index 0000000..8f2841c3
--- /dev/null
+++ b/clang-tools-extra/clang-tidy/readability/EnumInitialValueCheck.cpp
@@ -0,0 +1,200 @@
+//===--- EnumInitialValueCheck.cpp - clang-tidy ---------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "EnumInitialValueCheck.h"
+#include "../utils/LexerUtils.h"
+#include "clang/AST/Decl.h"
+#include "clang/ASTMatchers/ASTMatchFinder.h"
+#include "clang/ASTMatchers/ASTMatchers.h"
+#include "clang/Basic/Diagnostic.h"
+#include "clang/Basic/SourceLocation.h"
+#include "llvm/ADT/STLExtras.h"
+#include "llvm/ADT/SmallString.h"
+
+using namespace clang::ast_matchers;
+
+namespace clang::tidy::readability {
+
+static bool isNoneEnumeratorsInitialized(const EnumDecl &Node) {
+  return llvm::all_of(Node.enumerators(), [](const EnumConstantDecl *ECD) {
+    return ECD->getInitExpr() == nullptr;
+  });
+}
+
+static bool isOnlyFirstEnumeratorInitialized(const EnumDecl &Node) {
+  bool IsFirst = true;
+  for (const EnumConstantDecl *ECD : Node.enumerators()) {
+    if ((IsFirst && ECD->getInitExpr() == nullptr) ||
+        (!IsFirst && ECD->getInitExpr() != nullptr))
+      return false;
+    IsFirst = false;
+  }
+  return !IsFirst;
+}
+
+static bool areAllEnumeratorsInitialized(const EnumDecl &Node) {
+  return llvm::all_of(Node.enumerators(), [](const EnumConstantDecl *ECD) {
+    return ECD->getInitExpr() != nullptr;
+  });
+}
+
+/// Check if \p Enumerator is initialized with a (potentially negated) \c
+/// IntegerLiteral.
+static bool isInitializedByLiteral(const EnumConstantDecl *Enumerator) {
+  const Expr *const Init = Enumerator->getInitExpr();
+  if (!Init)
+    return false;
+  return Init->isIntegerConstantExpr(Enumerator->getASTContext());
+}
+
+static void cleanInitialValue(DiagnosticBuilder &Diag,
+                              const EnumConstantDecl *ECD,
+                              const SourceManager &SM,
+                              const LangOptions &LangOpts) {
+  const SourceRange InitExprRange = ECD->getInitExpr()->getSourceRange();
+  if (InitExprRange.isInvalid() || InitExprRange.getBegin().isMacroID() ||
+      InitExprRange.getEnd().isMacroID())
+    return;
+  std::optional<Token> EqualToken = utils::lexer::findNextTokenSkippingComments(
+      ECD->getLocation(), SM, LangOpts);
+  if (!EqualToken.has_value() ||
+      EqualToken.value().getKind() != tok::TokenKind::equal)
+    return;
+  const SourceLocation EqualLoc{EqualToken->getLocation()};
+  if (EqualLoc.isInvalid() || EqualLoc.isMacroID())
+    return;
+  Diag << FixItHint::CreateRemoval(EqualLoc)
+       << FixItHint::CreateRemoval(InitExprRange);
+  return;
+}
+
+namespace {
+
+AST_MATCHER(EnumDecl, isMacro) {
+  SourceLocation Loc = Node.getBeginLoc();
+  return Loc.isMacroID();
+}
+
+AST_MATCHER(EnumDecl, hasConsistentInitialValues) {
+  return isNoneEnumeratorsInitialized(Node) ||
+         isOnlyFirstEnumeratorInitialized(Node) ||
+         areAllEnumeratorsInitialized(Node);
+}
+
+AST_MATCHER(EnumDecl, hasZeroInitialValueForFirstEnumerator) {
+  const EnumDecl::enumerator_range Enumerators = Node.enumerators();
+  if (Enumerators.empty())
+    return false;
+  const EnumConstantDecl *ECD = *Enumerators.begin();
+  return isOnlyFirstEnumeratorInitialized(Node) &&
+         isInitializedByLiteral(ECD) && ECD->getInitVal().isZero();
+}
+
+/// Excludes bitfields because enumerators initialized with the result of a
+/// bitwise operator on enumeration values or any other expr that is not a
+/// potentially negative integer literal.
+/// Enumerations where it is not directly clear if they are used with
+/// bitmask, evident when enumerators are only initialized with (potentially
+/// negative) integer literals, are ignored. This is also the case when all
+/// enumerators are powers of two (e.g., 0, 1, 2).
+AST_MATCHER(EnumDecl, hasSequentialInitialValues) {
+  const EnumDecl::enumerator_range Enumerators = Node.enumerators();
+  if (Enumerators.empty())
+    return false;
+  const EnumConstantDecl *const FirstEnumerator = *Node.enumerator_begin();
+  llvm::APSInt PrevValue = FirstEnumerator->getInitVal();
+  if (!isInitializedByLiteral(FirstEnumerator))
+    return false;
+  bool AllEnumeratorsArePowersOfTwo = true;
+  for (const EnumConstantDecl *Enumerator : llvm::drop_begin(Enumerators)) {
+    const llvm::APSInt NewValue = Enumerator->getInitVal();
+    if (NewValue != ++PrevValue)
+      return false;
+    if (!isInitializedByLiteral(Enumerator))
+      return false;
+    PrevValue = NewValue;
+    AllEnumeratorsArePowersOfTwo &= NewValue.isPowerOf2();
+  }
+  return !AllEnumeratorsArePowersOfTwo;
+}
+
+} // namespace
+
+EnumInitialValueCheck::EnumInitialValueCheck(StringRef Name,
+                                             ClangTidyContext *Context)
+    : ClangTidyCheck(Name, Context),
+      AllowExplicitZeroFirstInitialValue(
+          Options.get("AllowExplicitZeroFirstInitialValue", true)),
+      AllowExplicitSequentialInitialValues(
+          Options.get("AllowExplicitSequentialInitialValues", true)) {}
+
+void EnumInitialValueCheck::storeOptions(ClangTidyOptions::OptionMap &Opts) {
+  Options.store(Opts, "AllowExplicitZeroFirstInitialValue",
+                AllowExplicitZeroFirstInitialValue);
+  Options.store(Opts, "AllowExplicitSequentialInitialValues",
+                AllowExplicitSequentialInitialValues);
+}
+
+void EnumInitialValueCheck::registerMatchers(MatchFinder *Finder) {
+  Finder->addMatcher(
+      enumDecl(unless(isMacro()), unless(hasConsistentInitialValues()))
+          .bind("inconsistent"),
+      this);
+  if (!AllowExplicitZeroFirstInitialValue)
+    Finder->addMatcher(
+        enumDecl(hasZeroInitialValueForFirstEnumerator()).bind("zero_first"),
+        this);
+  if (!AllowExplicitSequentialInitialValues)
+    Finder->addMatcher(enumDecl(unless(isMacro()), hasSequentialInitialValues())
+                           .bind("sequential"),
+                       this);
+}
+
+void EnumInitialValueCheck::check(const MatchFinder::MatchResult &Result) {
+  if (const auto *Enum = Result.Nodes.getNodeAs<EnumDecl>("inconsistent")) {
+    DiagnosticBuilder Diag =
+        diag(Enum->getBeginLoc(),
+             "inital values in enum %0 are not consistent, consider explicit "
+             "initialization of all, none or only the first enumerator")
+        << Enum;
+    for (const EnumConstantDecl *ECD : Enum->enumerators())
+      if (ECD->getInitExpr() == nullptr) {
+        const SourceLocation EndLoc = Lexer::getLocForEndOfToken(
+            ECD->getLocation(), 0, *Result.SourceManager, getLangOpts());
+        if (EndLoc.isMacroID())
+          continue;
+        llvm::SmallString<8> Str{" = "};
+        ECD->getInitVal().toString(Str);
+        Diag << FixItHint::CreateInsertion(EndLoc, Str);
+      }
+    return;
+  }
+
+  if (const auto *Enum = Result.Nodes.getNodeAs<EnumDecl>("zero_first")) {
+    const EnumConstantDecl *ECD = *Enum->enumerator_begin();
+    const SourceLocation Loc = ECD->getLocation();
+    if (Loc.isInvalid() || Loc.isMacroID())
+      return;
+    DiagnosticBuilder Diag = diag(Loc, "zero initial value for the first "
+                                       "enumerator in %0 can be disregarded")
+                             << Enum;
+    cleanInitialValue(Diag, ECD, *Result.SourceManager, getLangOpts());
+    return;
+  }
+  if (const auto *Enum = Result.Nodes.getNodeAs<EnumDecl>("sequential")) {
+    DiagnosticBuilder Diag =
+        diag(Enum->getBeginLoc(),
+             "sequential initial value in %0 can be ignored")
+        << Enum;
+    for (const EnumConstantDecl *ECD : llvm::drop_begin(Enum->enumerators()))
+      cleanInitialValue(Diag, ECD, *Result.SourceManager, getLangOpts());
+    return;
+  }
+}
+
+} // namespace clang::tidy::readability
diff --git a/clang-tools-extra/clang-tidy/readability/EnumInitialValueCheck.h b/clang-tools-extra/clang-tidy/readability/EnumInitialValueCheck.h
new file mode 100644
index 0000000..66087e4
--- /dev/null
+++ b/clang-tools-extra/clang-tidy/readability/EnumInitialValueCheck.h
@@ -0,0 +1,38 @@
+//===--- EnumInitialValueCheck.h - clang-tidy -------------------*- C++ -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_READABILITY_ENUMINITIALVALUECHECK_H
+#define LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_READABILITY_ENUMINITIALVALUECHECK_H
+
+#include "../ClangTidyCheck.h"
+
+namespace clang::tidy::readability {
+
+/// Enforces consistent style for enumerators' initialization, covering three
+/// styles: none, first only, or all initialized explicitly.
+///
+/// For the user-facing documentation see:
+/// http://clang.llvm.org/extra/clang-tidy/checks/readability/enum-initial-value.html
+class EnumInitialValueCheck : public ClangTidyCheck {
+public:
+  EnumInitialValueCheck(StringRef Name, ClangTidyContext *Context);
+  void storeOptions(ClangTidyOptions::OptionMap &Opts) override;
+  void registerMatchers(ast_matchers::MatchFinder *Finder) override;
+  void check(const ast_matchers::MatchFinder::MatchResult &Result) override;
+  std::optional<TraversalKind> getCheckTraversalKind() const override {
+    return TK_IgnoreUnlessSpelledInSource;
+  }
+
+private:
+  const bool AllowExplicitZeroFirstInitialValue;
+  const bool AllowExplicitSequentialInitialValues;
+};
+
+} // namespace clang::tidy::readability
+
+#endif // LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_READABILITY_ENUMINITIALVALUECHECK_H
diff --git a/clang-tools-extra/clang-tidy/readability/ReadabilityTidyModule.cpp b/clang-tools-extra/clang-tidy/readability/ReadabilityTidyModule.cpp
index bca2c42..376b846 100644
--- a/clang-tools-extra/clang-tidy/readability/ReadabilityTidyModule.cpp
+++ b/clang-tools-extra/clang-tidy/readability/ReadabilityTidyModule.cpp
@@ -22,6 +22,7 @@
 #include "DeleteNullPointerCheck.h"
 #include "DuplicateIncludeCheck.h"
 #include "ElseAfterReturnCheck.h"
+#include "EnumInitialValueCheck.h"
 #include "FunctionCognitiveComplexityCheck.h"
 #include "FunctionSizeCheck.h"
 #include "IdentifierLengthCheck.h"
@@ -92,6 +93,8 @@ public:
         "readability-duplicate-include");
     CheckFactories.registerCheck<ElseAfterReturnCheck>(
         "readability-else-after-return");
+    CheckFactories.registerCheck<EnumInitialValueCheck>(
+        "readability-enum-initial-value");
     CheckFactories.registerCheck<FunctionCognitiveComplexityCheck>(
         "readability-function-cognitive-complexity");
     CheckFactories.registerCheck<FunctionSizeCheck>(
diff --git a/clang-tools-extra/docs/ReleaseNotes.rst b/clang-tools-extra/docs/ReleaseNotes.rst
index 78b09d2..309b844 100644
--- a/clang-tools-extra/docs/ReleaseNotes.rst
+++ b/clang-tools-extra/docs/ReleaseNotes.rst
@@ -123,6 +123,12 @@ New checks
   Finds initializer lists for aggregate types that could be
   written as designated initializers instead.
 
+- New :doc:`readability-enum-initial-value
+  <clang-tidy/checks/readability/enum-initial-value>` check.
+
+  Enforces consistent style for enumerators' initialization, covering three
+  styles: none, first only, or all initialized explicitly.
+
 - New :doc:`readability-use-std-min-max
   <clang-tidy/checks/readability/use-std-min-max>` check.
 
diff --git a/clang-tools-extra/docs/clang-tidy/checks/list.rst b/clang-tools-extra/docs/clang-tidy/checks/list.rst
index 79e81dd..188a42b 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/list.rst
+++ b/clang-tools-extra/docs/clang-tidy/checks/list.rst
@@ -352,6 +352,7 @@ Clang-Tidy Checks
    :doc:`readability-delete-null-pointer <readability/delete-null-pointer>`, "Yes"
    :doc:`readability-duplicate-include <readability/duplicate-include>`, "Yes"
    :doc:`readability-else-after-return <readability/else-after-return>`, "Yes"
+   :doc:`readability-enum-initial-value <readability/enum-initial-value>`, "Yes"
    :doc:`readability-function-cognitive-complexity <readability/function-cognitive-complexity>`,
    :doc:`readability-function-size <readability/function-size>`,
    :doc:`readability-identifier-length <readability/identifier-length>`,
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/enum-initial-value.rst b/clang-tools-extra/docs/clang-tidy/checks/readability/enum-initial-value.rst
new file mode 100644
index 0000000..660efc1
--- /dev/null
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/enum-initial-value.rst
@@ -0,0 +1,75 @@
+.. title:: clang-tidy - readability-enum-initial-value
+
+readability-enum-initial-value
+==============================
+
+Enforces consistent style for enumerators' initialization, covering three
+styles: none, first only, or all initialized explicitly.
+
+When adding new enumerations, inconsistent initial value will cause potential
+enumeration value conflicts.
+
+In an enumeration, the following three cases are accepted. 
+1. none of enumerators are explicit initialized.
+2. the first enumerator is explicit initialized.
+3. all of enumerators are explicit initialized.
+
+.. code-block:: c++
+
+  // valid, none of enumerators are initialized.
+  enum A {
+    e0,
+    e1,
+    e2,
+  };
+
+  // valid, the first enumerator is initialized.
+  enum A {
+    e0 = 0,
+    e1,
+    e2,
+  };
+
+  // valid, all of enumerators are initialized.
+  enum A {
+    e0 = 0,
+    e1 = 1,
+    e2 = 2,
+  };
+
+  // invalid, e1 is not explicit initialized.
+  enum A {
+    e0 = 0,
+    e1,
+    e2 = 2,
+  };
+
+Options
+-------
+
+.. option:: AllowExplicitZeroFirstInitialValue
+
+  If set to `false`, the first enumerator must not be explicitly initialized.
+  See examples below. Default is `true`.
+
+  .. code-block:: c++
+
+    enum A {
+      e0 = 0, // not allowed if AllowExplicitZeroFirstInitialValue is false
+      e1,
+      e2,
+    };
+
+
+.. option:: AllowExplicitSequentialInitialValues
+
+  If set to `false`, sequential initializations are not allowed.
+  See examples below. Default is `true`.
+
+  .. code-block:: c++
+
+    enum A {
+      e0 = 1, // not allowed if AllowExplicitSequentialInitialValues is false
+      e1 = 2,
+      e2 = 3,
+    };
diff --git a/clang-tools-extra/test/clang-tidy/checkers/readability/enum-initial-value.c b/clang-tools-extra/test/clang-tidy/checkers/readability/enum-initial-value.c
new file mode 100644
index 0000000..c66288c
--- /dev/null
+++ b/clang-tools-extra/test/clang-tidy/checkers/readability/enum-initial-value.c
@@ -0,0 +1,80 @@
+// RUN: %check_clang_tidy %s readability-enum-initial-value %t
+// RUN: %check_clang_tidy -check-suffix=ENABLE %s readability-enum-initial-value %t -- \
+// RUN:     -config='{CheckOptions: { \
+// RUN:         readability-enum-initial-value.AllowExplicitZeroFirstInitialValue: false, \
+// RUN:         readability-enum-initial-value.AllowExplicitSequentialInitialValues: false, \
+// RUN:     }}'
+
+enum EError {
+  // CHECK-MESSAGES: :[[@LINE-1]]:1: warning: inital values in enum 'EError' are not consistent
+  // CHECK-MESSAGES-ENABLE: :[[@LINE-2]]:1: warning: inital values in enum 'EError' are not consistent
+  EError_a = 1,
+  EError_b,
+  // CHECK-FIXES: EError_b = 2,
+  EError_c = 3,
+};
+
+enum ENone {
+  ENone_a,
+  ENone_b,
+  EENone_c,
+};
+
+enum EFirst {
+  EFirst_a = 1,
+  EFirst_b,
+  EFirst_c,
+};
+
+enum EAll {
+  EAll_a = 1,
+  EAll_b = 2,
+  EAll_c = 4,
+};
+
+#define ENUMERATOR_1 EMacro1_b
+enum EMacro1 {
+  // CHECK-MESSAGES: :[[@LINE-1]]:1: warning: inital values in enum 'EMacro1' are not consistent
+  // CHECK-MESSAGES-ENABLE: :[[@LINE-2]]:1: warning: inital values in enum 'EMacro1' are not consistent
+  EMacro1_a = 1,
+  ENUMERATOR_1,
+  // CHECK-FIXES: ENUMERATOR_1 = 2,
+  EMacro1_c = 3,
+};
+
+
+#define ENUMERATOR_2 EMacro2_b = 2
+enum EMacro2 {
+  // CHECK-MESSAGES: :[[@LINE-1]]:1: warning: inital values in enum 'EMacro2' are not consistent
+  // CHECK-MESSAGES-ENABLE: :[[@LINE-2]]:1: warning: inital values in enum 'EMacro2' are not consistent
+  EMacro2_a = 1,
+  ENUMERATOR_2,
+  EMacro2_c,
+  // CHECK-FIXES: EMacro2_c = 3,
+};
+
+enum EnumZeroFirstInitialValue {
+  EnumZeroFirstInitialValue_0 = 0,
+  // CHECK-MESSAGES-ENABLE: :[[@LINE-1]]:3: warning: zero initial value for the first enumerator in 'EnumZeroFirstInitialValue' can be disregarded
+  // CHECK-FIXES-ENABLE: EnumZeroFirstInitialValue_0 ,
+  EnumZeroFirstInitialValue_1,
+  EnumZeroFirstInitialValue_2,
+};
+
+enum EnumZeroFirstInitialValueWithComment {
+  EnumZeroFirstInitialValueWithComment_0 = /* == */ 0,
+  // CHECK-MESSAGES-ENABLE: :[[@LINE-1]]:3: warning: zero initial value for the first enumerator in 'EnumZeroFirstInitialValueWithComment' can be disregarded
+  // CHECK-FIXES-ENABLE: EnumZeroFirstInitialValueWithComment_0 /* == */ ,
+  EnumZeroFirstInitialValueWithComment_1,
+  EnumZeroFirstInitialValueWithComment_2,
+};
+
+enum EnumSequentialInitialValue {
+  // CHECK-MESSAGES-ENABLE: :[[@LINE-1]]:1: warning: sequential initial value in 'EnumSequentialInitialValue' can be ignored
+  EnumSequentialInitialValue_0 = 2,
+  // CHECK-FIXES-ENABLE: EnumSequentialInitialValue_0 = 2,
+  EnumSequentialInitialValue_1 = 3,
+  // CHECK-FIXES-ENABLE: EnumSequentialInitialValue_1 ,
+  EnumSequentialInitialValue_2 = 4,
+  // CHECK-FIXES-ENABLE: EnumSequentialInitialValue_2 ,
+};
diff --git a/clang-tools-extra/test/clang-tidy/checkers/readability/enum-initial-value.cpp b/clang-tools-extra/test/clang-tidy/checkers/readability/enum-initial-value.cpp
new file mode 100644
index 0000000..3c4ba97
--- /dev/null
+++ b/clang-tools-extra/test/clang-tidy/checkers/readability/enum-initial-value.cpp
@@ -0,0 +1,27 @@
+// RUN: %check_clang_tidy %s readability-enum-initial-value %t
+
+enum class EError {
+  // CHECK-MESSAGES: :[[@LINE-1]]:1:  warning: inital values in enum 'EError' are not consistent
+  EError_a = 1,
+  EError_b,
+  // CHECK-FIXES: EError_b = 2,
+  EError_c = 3,
+};
+
+enum class ENone {
+  ENone_a,
+  ENone_b,
+  EENone_c,
+};
+
+enum class EFirst {
+  EFirst_a = 1,
+  EFirst_b,
+  EFirst_c,
+};
+
+enum class EAll {
+  EAll_a = 1,
+  EAll_b = 2,
+  EAll_c = 3,
+};