[clang-tools-extra] [clang-tidy] Show descriptive error message when check_alphabetical_order.py fails (PR #170975)

[Baranov Victor via cfe-commits]

https://github.com/vbvictor created https://github.com/llvm/llvm-project/pull/170975

None

>From 2415732d2512f7fbc026f14036d6a758fa4ec016 Mon Sep 17 00:00:00 2001
From: Victor Baranov <bar.victor.2002 at gmail.com>
Date: Sat, 6 Dec 2025 13:02:35 +0300
Subject: [PATCH] [clang-tidy] Show descriptive error message when
 check_alphabetical_order.py fails

---
 .../tool/check_alphabetical_order.py          | 23 +++++++++++++------
 .../tool/check_alphabetical_order_test.py     | 13 ++++++++---
 2 files changed, 26 insertions(+), 10 deletions(-)

diff --git a/clang-tools-extra/clang-tidy/tool/check_alphabetical_order.py b/clang-tools-extra/clang-tidy/tool/check_alphabetical_order.py
index 3220795433187..66819aba435e8 100644
--- a/clang-tools-extra/clang-tidy/tool/check_alphabetical_order.py
+++ b/clang-tools-extra/clang-tidy/tool/check_alphabetical_order.py
@@ -126,9 +126,9 @@ def _scan_bullet_blocks(lines: Sequence[str], start: int, end: int) -> ScannedBl
     return ScannedBlocks(blocks_with_pos, i)
 
 
-def read_text(path: str) -> List[str]:
+def read_text(path: str) -> str:
     with io.open(path, "r", encoding="utf-8") as f:
-        return f.read().splitlines(True)
+        return f.read()
 
 
 def write_text(path: str, content: str) -> None:
@@ -364,14 +364,16 @@ def _emit_duplicate_report(lines: Sequence[str], title: str) -> Optional[str]:
 
 
 def process_release_notes(out_path: str, rn_doc: str) -> int:
-    lines = read_text(rn_doc)
+    text = read_text(rn_doc)
+    lines = text.splitlines(True)
     normalized = normalize_release_notes(lines)
     write_text(out_path, normalized)
 
     # Prefer reporting ordering issues first; let diff fail the test.
-    if "".join(lines) != normalized:
+    if text != normalized:
         sys.stderr.write(
-            "Note: 'ReleaseNotes.rst' is not normalized; Please fix ordering first.\n"
+            "\nEntries in 'clang-tools-extra/docs/ReleaseNotes.rst' are not alphabetically sorted.\n"
+            "Fix the ordering by applying diff printed below.\n\n"
         )
         return 0
 
@@ -383,8 +385,15 @@ def process_release_notes(out_path: str, rn_doc: str) -> int:
 
 
 def process_checks_list(out_path: str, list_doc: str) -> int:
-    lines = read_text(list_doc)
-    normalized = normalize_list_rst("".join(lines))
+    text = read_text(list_doc)
+    normalized = normalize_list_rst(text)
+
+    if text != normalized:
+        sys.stderr.write(
+            "\nChecks in 'clang-tools-extra/docs/clang-tidy/checks/list.rst' csv-table are not alphabetically sorted.\n"
+            "Fix the ordering by applying diff printed below.\n\n"
+        )
+
     write_text(out_path, normalized)
     return 0
 
diff --git a/clang-tools-extra/clang-tidy/tool/check_alphabetical_order_test.py b/clang-tools-extra/clang-tidy/tool/check_alphabetical_order_test.py
index bbc3dda7d9473..48a3c761c12ce 100644
--- a/clang-tools-extra/clang-tidy/tool/check_alphabetical_order_test.py
+++ b/clang-tools-extra/clang-tidy/tool/check_alphabetical_order_test.py
@@ -164,7 +164,7 @@ def test_process_release_notes_with_unsorted_content(self) -> None:
             )
 
             self.assertEqual(out, expected_out)
-            self.assertIn("not normalized", buf.getvalue())
+            self.assertIn("not alphabetically sorted", buf.getvalue())
 
     def test_process_release_notes_prioritizes_sorting_over_duplicates(self) -> None:
         # Sorting is incorrect and duplicates exist, should report ordering issues first.
@@ -201,7 +201,7 @@ def test_process_release_notes_prioritizes_sorting_over_duplicates(self) -> None
                 rc = _mod.process_release_notes(out_path, rn_doc)
             self.assertEqual(rc, 0)
             self.assertIn(
-                "Note: 'ReleaseNotes.rst' is not normalized; Please fix ordering first.",
+                "Entries in 'clang-tools-extra/docs/ReleaseNotes.rst' are not alphabetically sorted.",
                 buf.getvalue(),
             )
 
@@ -371,7 +371,14 @@ def test_process_checks_list_normalizes_output(self) -> None:
             out_doc = os.path.join(td, "out.rst")
             with open(in_doc, "w", encoding="utf-8") as f:
                 f.write(list_text)
-            rc = _mod.process_checks_list(out_doc, in_doc)
+            buf = io.StringIO()
+            with redirect_stderr(buf):
+                rc = _mod.process_checks_list(out_doc, in_doc)
+            self.assertEqual(rc, 0)
+            self.assertIn(
+                "Checks in 'clang-tools-extra/docs/clang-tidy/checks/list.rst' csv-table are not alphabetically sorted.",
+                buf.getvalue(),
+            )
             self.assertEqual(rc, 0)
             with open(out_doc, "r", encoding="utf-8") as f:
                 out = f.read()