clang-format: Add IncludeSortKey option

Sorting by stem gives nicer results when various header file names
are substrings of other header file names, for example, a CLI application
with a main header named analyze.h and a analyze-xxx.h header for each
subcommand currently will always put analyze.h last after all the
analyze-xxx.h headers, but putting analyze.h first instead of last is arguable
nicer to read.

TLDR; Instead of

"""
/#include "analyze-blame.h"
/#include "analyze.h"
"""

You'd get

"""
/#include "analyze.h"
/#include "analyze-blame.h"
"""

Let's allow sorting by stem instead of full path by introducing a new
option IncludeSortKey with two values "Path" and "Stem".

Author: DaanDeMeyer

clang/docs/ClangFormatStyleOptions.rst

@@ -4226,6 +4226,22 @@ the configuration (without a prefix: ``Auto``).
   ``ClassImpl.hpp`` would not have the main include file put on top
   before any other include.
 
+.. _IncludeSortKey:
+
+**IncludeSortKey** (``IncludeSortKeyDiscriminator``) :versionbadge:`clang-format 21` :ref:`¶ <IncludeSortKey>`
+  When sorting includes in each block, sort by the specified sort key.
+
+  Possible values:
+
+  * ``ISK_Path`` (in configuration: ``Path``)
+    Includes are sorted alphabetically by their full path.
+
+  * ``ISK_Stem`` (in configuration: ``Stem``)
+    Includes are sorted alphabetically by their full path without the
+    file extension.
+
+
+
 .. _IndentAccessModifiers:
 
 **IndentAccessModifiers** (``Boolean``) :versionbadge:`clang-format 13` :ref:`¶ <IndentAccessModifiers>`

clang/include/clang/Format/Format.h

@@ -5368,6 +5368,7 @@ struct FormatStyle {
            IncludeStyle.IncludeIsMainSourceRegex ==
                R.IncludeStyle.IncludeIsMainSourceRegex &&
            IncludeStyle.MainIncludeChar == R.IncludeStyle.MainIncludeChar &&
+           IncludeStyle.IncludeSortKey == R.IncludeStyle.IncludeSortKey &&
            IndentAccessModifiers == R.IndentAccessModifiers &&
            IndentCaseBlocks == R.IndentCaseBlocks &&
            IndentCaseLabels == R.IndentCaseLabels &&

clang/include/clang/Tooling/Inclusions/IncludeStyle.h

@@ -152,6 +152,19 @@ struct IncludeStyle {
   /// \version 10
   std::string IncludeIsMainSourceRegex;
 
+  /// Available sort keys that can be used to sort includes in each block.
+  enum IncludeSortKeyDiscriminator : int8_t {
+    /// Includes are sorted alphabetically by their full path.
+    ISK_Path,
+    /// Includes are sorted alphabetically by their full path without the
+    /// file extension.
+    ISK_Stem,
+  };
+
+  /// When sorting includes in each block, sort by the specified sort key.
+  /// \version 21
+  IncludeSortKeyDiscriminator IncludeSortKey;
+
   /// Character to consider in the include directives for the main header.
   enum MainIncludeCharDiscriminator : int8_t {
     /// Main include uses quotes: ``#include "foo.hpp"`` (the default).
@@ -197,6 +210,14 @@ struct ScalarEnumerationTraits<
       clang::tooling::IncludeStyle::MainIncludeCharDiscriminator &Value);
 };
 
+template <>
+struct ScalarEnumerationTraits<
+    clang::tooling::IncludeStyle::IncludeSortKeyDiscriminator> {
+  static void
+  enumeration(IO &IO,
+              clang::tooling::IncludeStyle::IncludeSortKeyDiscriminator &Value);
+};
+
 } // namespace yaml
 } // namespace llvm
 

clang/lib/Format/Format.cpp

@@ -1062,6 +1062,7 @@ template <> struct MappingTraits<FormatStyle> {
     IO.mapOptional("IncludeIsMainRegex", Style.IncludeStyle.IncludeIsMainRegex);
     IO.mapOptional("IncludeIsMainSourceRegex",
                    Style.IncludeStyle.IncludeIsMainSourceRegex);
+    IO.mapOptional("IncludeSortKey", Style.IncludeStyle.IncludeSortKey);
     IO.mapOptional("IndentAccessModifiers", Style.IndentAccessModifiers);
     IO.mapOptional("IndentCaseBlocks", Style.IndentCaseBlocks);
     IO.mapOptional("IndentCaseLabels", Style.IndentCaseLabels);
@@ -1581,6 +1582,7 @@ FormatStyle getLLVMStyle(FormatStyle::LanguageKind Language) {
       {"^(<|\"(gtest|gmock|isl|json)/)", 3, 0, false},
       {".*", 1, 0, false}};
   LLVMStyle.IncludeStyle.IncludeIsMainRegex = "(Test)?$";
+  LLVMStyle.IncludeStyle.IncludeSortKey = tooling::IncludeStyle::ISK_Path;
   LLVMStyle.IncludeStyle.MainIncludeChar = tooling::IncludeStyle::MICD_Quote;
   LLVMStyle.IndentAccessModifiers = false;
   LLVMStyle.IndentCaseBlocks = false;
@@ -3221,15 +3223,33 @@ static void sortCppIncludes(const FormatStyle &Style,
     stable_sort(Indices, [&](unsigned LHSI, unsigned RHSI) {
       const auto LHSFilenameLower = Includes[LHSI].Filename.lower();
       const auto RHSFilenameLower = Includes[RHSI].Filename.lower();
-      return std::tie(Includes[LHSI].Priority, LHSFilenameLower,
-                      Includes[LHSI].Filename) <
-             std::tie(Includes[RHSI].Priority, RHSFilenameLower,
-                      Includes[RHSI].Filename);
+      SmallString<128> LHSStem = Includes[LHSI].Filename;
+      SmallString<128> RHSStem = Includes[RHSI].Filename;
+      if (Style.IncludeStyle.IncludeSortKey ==
+          tooling::IncludeStyle::ISK_Stem) {
+        llvm::sys::path::replace_extension(LHSStem, "");
+        llvm::sys::path::replace_extension(RHSStem, "");
+      }
+      const auto LHSStemLower = LHSStem.str().lower();
+      const auto RHSStemLower = RHSStem.str().lower();
+      return std::tie(Includes[LHSI].Priority, LHSStemLower, LHSStem,
+                      LHSFilenameLower, Includes[LHSI].Filename) <
+             std::tie(Includes[RHSI].Priority, RHSStemLower, RHSStem,
+                      RHSFilenameLower, Includes[RHSI].Filename);
     });
   } else {
     stable_sort(Indices, [&](unsigned LHSI, unsigned RHSI) {
-      return std::tie(Includes[LHSI].Priority, Includes[LHSI].Filename) <
-             std::tie(Includes[RHSI].Priority, Includes[RHSI].Filename);
+      SmallString<128> LHSStem = Includes[LHSI].Filename;
+      SmallString<128> RHSStem = Includes[RHSI].Filename;
+      if (Style.IncludeStyle.IncludeSortKey ==
+          tooling::IncludeStyle::ISK_Stem) {
+        llvm::sys::path::replace_extension(LHSStem, "");
+        llvm::sys::path::replace_extension(RHSStem, "");
+      }
+      return std::tie(Includes[LHSI].Priority, LHSStem,
+                      Includes[LHSI].Filename) <
+             std::tie(Includes[RHSI].Priority, RHSStem,
+                      Includes[RHSI].Filename);
     });
   }
 

clang/lib/Tooling/Inclusions/IncludeStyle.cpp

@@ -35,5 +35,11 @@ void ScalarEnumerationTraits<IncludeStyle::MainIncludeCharDiscriminator>::
   IO.enumCase(Value, "Any", IncludeStyle::MICD_Any);
 }
 
+void ScalarEnumerationTraits<IncludeStyle::IncludeSortKeyDiscriminator>::
+    enumeration(IO &IO, IncludeStyle::IncludeSortKeyDiscriminator &Value) {
+  IO.enumCase(Value, "Path", IncludeStyle::ISK_Path);
+  IO.enumCase(Value, "Stem", IncludeStyle::ISK_Stem);
+}
+
 } // namespace yaml
 } // namespace llvm

clang/unittests/Format/SortIncludesTest.cpp

@@ -1485,6 +1485,26 @@ TEST_F(SortIncludesTest, BlockCommentedOutIncludes) {
   verifyFormat(Code, sort(Code, "input.cpp", 0));
 }
 
+TEST_F(SortIncludesTest, IncludeSortKey) {
+  verifyFormat("#include <a-util.h>\n"
+               "#include <a.h>\n"
+               "#include <a.inc>",
+               sort("#include <a.inc>\n"
+                    "#include <a-util.h>\n"
+                    "#include <a.h>",
+                    "input.h", 1));
+
+  Style.IncludeSortKey = tooling::IncludeStyle::ISK_Stem;
+
+  verifyFormat("#include <a.h>\n"
+               "#include <a.inc>\n"
+               "#include <a-util.h>",
+               sort("#include <a.inc>\n"
+                    "#include <a-util.h>\n"
+                    "#include <a.h>",
+                    "input.h", 1));
+}
+
 } // end namespace
 } // end namespace format
 } // end namespace clang