From 43fbd92991b32bbfdcc3a9a018518e2ead2212f3 Mon Sep 17 00:00:00 2001
From: Ben Boeckel <ben.boeckel@kitware.com>
Date: Thu, 29 May 2025 00:03:20 +0200
Subject: [PATCH] Utilities/ast-grep: add rules to remove `CM_DBG` usage

An easy way to detect and remove debugging left over from development.
The rules are disabled by default so that LSP usage doesn't interfere
when they are wanted.

To actually use the rules, severity flags are necessary:

    ast-grep scan --error=rm-cmdbg-includes --error=rm-cmdbg-macros

This command will report on instances; passing `-U` as well will update
the source.

Tests are also not run by default; see
https://github.com/ast-grep/ast-grep/issues/2023 to track its progress.
---
 .../rm-cmdbg-includes-snapshot.yml            | 16 ++++++++++
 .../rm-cmdbg-macros-snapshot.yml              | 30 +++++++++++++++++++
 .../ast-grep/rule-tests/rm-cmdbg-includes.yml |  8 +++++
 .../ast-grep/rule-tests/rm-cmdbg-macros.yml   | 10 +++++++
 .../ast-grep/rules/rm-cmdbg-includes.yml      | 13 ++++++++
 Utilities/ast-grep/rules/rm-cmdbg-macros.yml  | 12 ++++++++
 6 files changed, 89 insertions(+)
 create mode 100644 Utilities/ast-grep/rule-tests/__snapshots__/rm-cmdbg-includes-snapshot.yml
 create mode 100644 Utilities/ast-grep/rule-tests/__snapshots__/rm-cmdbg-macros-snapshot.yml
 create mode 100644 Utilities/ast-grep/rule-tests/rm-cmdbg-includes.yml
 create mode 100644 Utilities/ast-grep/rule-tests/rm-cmdbg-macros.yml
 create mode 100644 Utilities/ast-grep/rules/rm-cmdbg-includes.yml
 create mode 100644 Utilities/ast-grep/rules/rm-cmdbg-macros.yml

diff --git a/Utilities/ast-grep/rule-tests/__snapshots__/rm-cmdbg-includes-snapshot.yml b/Utilities/ast-grep/rule-tests/__snapshots__/rm-cmdbg-includes-snapshot.yml
new file mode 100644
index 0000000000..6b06a3e5a5
--- /dev/null
+++ b/Utilities/ast-grep/rule-tests/__snapshots__/rm-cmdbg-includes-snapshot.yml
@@ -0,0 +1,16 @@
+id: rm-cmdbg-includes
+snapshots:
+  '#include "cmDebugTools.h"':
+    fixed: ''
+    labels:
+    - source: '#include "cmDebugTools.h"'
+      style: primary
+      start: 0
+      end: 25
+  '#include <cmDebugTools.h>':
+    fixed: ''
+    labels:
+    - source: '#include <cmDebugTools.h>'
+      style: primary
+      start: 0
+      end: 25
diff --git a/Utilities/ast-grep/rule-tests/__snapshots__/rm-cmdbg-macros-snapshot.yml b/Utilities/ast-grep/rule-tests/__snapshots__/rm-cmdbg-macros-snapshot.yml
new file mode 100644
index 0000000000..47d919999c
--- /dev/null
+++ b/Utilities/ast-grep/rule-tests/__snapshots__/rm-cmdbg-macros-snapshot.yml
@@ -0,0 +1,30 @@
+id: rm-cmdbg-macros
+snapshots:
+  CM_DBG(arg);:
+    fixed: arg;
+    labels:
+    - source: CM_DBG(arg)
+      style: primary
+      start: 0
+      end: 11
+  a = CM_DBG(arg);:
+    fixed: a = arg;
+    labels:
+    - source: CM_DBG(arg)
+      style: primary
+      start: 4
+      end: 15
+  b = a + CM_DBG(arg);:
+    fixed: b = a + arg;
+    labels:
+    - source: CM_DBG(arg)
+      style: primary
+      start: 8
+      end: 19
+  f(CM_DBG(arg));:
+    fixed: f(arg);
+    labels:
+    - source: CM_DBG(arg)
+      style: primary
+      start: 2
+      end: 13
diff --git a/Utilities/ast-grep/rule-tests/rm-cmdbg-includes.yml b/Utilities/ast-grep/rule-tests/rm-cmdbg-includes.yml
new file mode 100644
index 0000000000..306b8d2ff1
--- /dev/null
+++ b/Utilities/ast-grep/rule-tests/rm-cmdbg-includes.yml
@@ -0,0 +1,8 @@
+---
+id: rm-cmdbg-includes
+valid:
+  - '#include "NotcmDebugTools.h"'
+  - '#include <NotcmDebugTools.h>'
+invalid:
+  - '#include "cmDebugTools.h"'
+  - '#include <cmDebugTools.h>'
diff --git a/Utilities/ast-grep/rule-tests/rm-cmdbg-macros.yml b/Utilities/ast-grep/rule-tests/rm-cmdbg-macros.yml
new file mode 100644
index 0000000000..dbbcda66b3
--- /dev/null
+++ b/Utilities/ast-grep/rule-tests/rm-cmdbg-macros.yml
@@ -0,0 +1,10 @@
+---
+id: rm-cmdbg-macros
+valid:
+  - CM_DBG;
+  - macro(expr);
+invalid:
+  - CM_DBG(arg);
+  - f(CM_DBG(arg));
+  - b = a + CM_DBG(arg);
+  - a = CM_DBG(arg);
diff --git a/Utilities/ast-grep/rules/rm-cmdbg-includes.yml b/Utilities/ast-grep/rules/rm-cmdbg-includes.yml
new file mode 100644
index 0000000000..b3ca0c1090
--- /dev/null
+++ b/Utilities/ast-grep/rules/rm-cmdbg-includes.yml
@@ -0,0 +1,13 @@
+---
+id: rm-cmdbg-includes
+language: Cpp
+severity: 'off'
+message: "Remove `cmDebugTools.h` includes before submission"
+ignores:
+  # Unit tests for the header.
+  - Tests/CMakeLib/testDebug.cxx
+rule:
+  any:
+    - pattern: '#include "cmDebugTools.h"'
+    - pattern: '#include <cmDebugTools.h>'
+fix: ''
diff --git a/Utilities/ast-grep/rules/rm-cmdbg-macros.yml b/Utilities/ast-grep/rules/rm-cmdbg-macros.yml
new file mode 100644
index 0000000000..ed06ba6abe
--- /dev/null
+++ b/Utilities/ast-grep/rules/rm-cmdbg-macros.yml
@@ -0,0 +1,12 @@
+---
+id: rm-cmdbg-macros
+language: Cpp
+severity: 'off'
+message: "Remove `CM_DBG` usage before submission"
+ignores:
+  # Unit tests for the header.
+  - Tests/CMakeLib/testDebug.cxx
+rule:
+  pattern: CM_DBG($EXPR)
+  kind: call_expression
+fix: $EXPR