feat: support verbose option

shenxianpeng · shenxianpeng · commit 8faac34f049c · 2025-07-04T00:08:25.000+03:00
diff --git a/README.md b/README.md
@@ -81,6 +81,44 @@ pre-commit run --files $(git diff --name-only)
 
 This approach ensures that only modified files are checked, further speeding up the linting process during development.
 
+### Verbose Output and Debugging
+
+For debugging issues or getting more detailed information about what the hooks are doing, you can enable verbose output:
+
+```yaml
+repos:
+  - repo: https://github.com/cpp-linter/cpp-linter-hooks
+    rev: v0.8.1
+    hooks:
+      - id: clang-format
+        args: [--style=file, --version=18, --verbose]  # Enable verbose output
+      - id: clang-tidy
+        args: [--checks=.clang-tidy, --version=18, --verbose]  # Enable verbose output
+```
+
+When you run pre-commit with verbose mode, you'll get detailed debug information:
+
+```bash
+# Run pre-commit with verbose output
+pre-commit run --verbose --all-files
+
+# Run specific hook with verbose output
+pre-commit run clang-format --verbose
+```
+
+The verbose output includes:
+- The exact command being executed
+- The path to the clang tool executable
+- The tool version being used
+- Exit codes and detailed error messages
+- Both stdout and stderr output from the tools
+
+This is particularly useful when debugging issues like:
+- Exit code 247 (tool execution errors)
+- Missing compilation databases for clang-tidy
+- Configuration file loading issues
+- Tool installation problems
+
 ## Output
 
 ### clang-format Example
@@ -148,7 +186,6 @@ Use -header-filter=.* to display errors from all non-system headers. Use -system
     for (;;)
             ^
              {
-
 ```
 
 ## Contributing
diff --git a/cpp_linter_hooks/clang_format.py b/cpp_linter_hooks/clang_format.py
@@ -1,4 +1,5 @@
 import subprocess
+import sys
 from argparse import ArgumentParser
 from typing import Tuple
 
@@ -7,6 +8,9 @@
 
 parser = ArgumentParser()
 parser.add_argument("--version", default=DEFAULT_CLANG_VERSION)
+parser.add_argument(
+    "-v", "--verbose", action="store_true", help="Enable verbose output"
+)
 
 
 def run_clang_format(args=None) -> Tuple[int, str]:
@@ -15,27 +19,81 @@ def run_clang_format(args=None) -> Tuple[int, str]:
     command = [str(path), "-i"]
     command.extend(other_args)
 
+    verbose = hook_args.verbose
+
+    if verbose:
+        print(f"[DEBUG] clang-format command: {' '.join(command)}", file=sys.stderr)
+        print(f"[DEBUG] clang-format version: {hook_args.version}", file=sys.stderr)
+        print(f"[DEBUG] clang-format executable: {path}", file=sys.stderr)
+
     retval = 0
     output = ""
+    stderr_output = ""
+
     try:
         if "--dry-run" in command:
-            sp = subprocess.run(command, stdout=subprocess.PIPE, encoding="utf-8")
+            sp = subprocess.run(
+                command,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                encoding="utf-8",
+            )
             retval = -1  # Not a fail just identify it's a dry-run.
             output = sp.stdout
+            stderr_output = sp.stderr
+
+            if verbose:
+                print("[DEBUG] Dry-run mode detected", file=sys.stderr)
+                print(
+                    f"[DEBUG] Exit code: {sp.returncode} (converted to -1 for dry-run)",
+                    file=sys.stderr,
+                )
         else:
-            retval = subprocess.run(command, stdout=subprocess.PIPE).returncode
-        return retval, output
-    except FileNotFoundError as stderr:
+            sp = subprocess.run(
+                command,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                encoding="utf-8",
+            )
+            retval = sp.returncode
+            output = sp.stdout
+            stderr_output = sp.stderr
+
+            if verbose:
+                print(f"[DEBUG] Exit code: {retval}", file=sys.stderr)
+
+        # Combine stdout and stderr for comprehensive output
+        combined_output = ""
+        if output:
+            combined_output += output
+        if stderr_output:
+            if combined_output:
+                combined_output += "\n"
+            combined_output += stderr_output
+
+        if verbose and (output or stderr_output):
+            print(f"[DEBUG] stdout: {repr(output)}", file=sys.stderr)
+            print(f"[DEBUG] stderr: {repr(stderr_output)}", file=sys.stderr)
+
+        return retval, combined_output
+
+    except FileNotFoundError as error:
         retval = 1
-        return retval, str(stderr)
+        error_msg = f"clang-format executable not found: {error}"
+
+        if verbose:
+            print(f"[DEBUG] FileNotFoundError: {error}", file=sys.stderr)
+            print(f"[DEBUG] Command attempted: {' '.join(command)}", file=sys.stderr)
+
+        return retval, error_msg
 
 
 def main() -> int:
     retval, output = run_clang_format()
-    if retval != 0:
-        print(output)
+    if retval != 0:  # pragma: no cover
+        print(output)  # pragma: no cover
     return retval
 
 
-if __name__ == "__main__":
+if __name__ == "__main__":  # pragma: no cover
     raise SystemExit(main())
diff --git a/cpp_linter_hooks/clang_tidy.py b/cpp_linter_hooks/clang_tidy.py
@@ -1,4 +1,5 @@
 import subprocess
+import sys
 from argparse import ArgumentParser
 from typing import Tuple
 
@@ -7,6 +8,9 @@
 
 parser = ArgumentParser()
 parser.add_argument("--version", default=DEFAULT_CLANG_VERSION)
+parser.add_argument(
+    "-v", "--verbose", action="store_true", help="Enable verbose output"
+)
 
 
 def run_clang_tidy(args=None) -> Tuple[int, str]:
@@ -15,26 +19,67 @@ def run_clang_tidy(args=None) -> Tuple[int, str]:
     command = [str(path)]
     command.extend(other_args)
 
+    verbose = hook_args.verbose
+
+    if verbose:
+        print(f"[DEBUG] clang-tidy command: {' '.join(command)}", file=sys.stderr)
+        print(f"[DEBUG] clang-tidy version: {hook_args.version}", file=sys.stderr)
+        print(f"[DEBUG] clang-tidy executable: {path}", file=sys.stderr)
+
     retval = 0
     output = ""
+    stderr_output = ""
+
     try:
-        sp = subprocess.run(command, stdout=subprocess.PIPE, encoding="utf-8")
+        sp = subprocess.run(
+            command, stdout=subprocess.PIPE, stderr=subprocess.PIPE, encoding="utf-8"
+        )
         retval = sp.returncode
         output = sp.stdout
-        if "warning:" in output or "error:" in output:
+        stderr_output = sp.stderr
+
+        if verbose:
+            print(f"[DEBUG] Exit code: {retval}", file=sys.stderr)
+            print(f"[DEBUG] stdout: {repr(output)}", file=sys.stderr)
+            print(f"[DEBUG] stderr: {repr(stderr_output)}", file=sys.stderr)
+
+        # Combine stdout and stderr for comprehensive output
+        combined_output = ""
+        if output:
+            combined_output += output
+        if stderr_output:
+            if combined_output:
+                combined_output += "\n"
+            combined_output += stderr_output
+
+        # Check for warnings or errors in the combined output
+        if "warning:" in combined_output or "error:" in combined_output:
             retval = 1
-        return retval, output
-    except FileNotFoundError as stderr:
+            if verbose:
+                print(
+                    "[DEBUG] Found warnings/errors, setting exit code to 1",
+                    file=sys.stderr,
+                )
+
+        return retval, combined_output
+
+    except FileNotFoundError as error:
         retval = 1
-        return retval, str(stderr)
+        error_msg = f"clang-tidy executable not found: {error}"
+
+        if verbose:
+            print(f"[DEBUG] FileNotFoundError: {error}", file=sys.stderr)
+            print(f"[DEBUG] Command attempted: {' '.join(command)}", file=sys.stderr)
+
+        return retval, error_msg
 
 
 def main() -> int:
     retval, output = run_clang_tidy()
-    if retval != 0:
-        print(output)
+    if retval != 0:  # pragma: no cover
+        print(output)  # pragma: no cover
     return retval
 
 
-if __name__ == "__main__":
+if __name__ == "__main__":  # pragma: no cover
     raise SystemExit(main())
diff --git a/example-pre-commit-config-verbose.yaml b/example-pre-commit-config-verbose.yaml
@@ -0,0 +1,25 @@
+# Example .pre-commit-config.yaml with verbose debugging enabled
+
+repos:
+  - repo: https://github.com/cpp-linter/cpp-linter-hooks
+    rev: v0.8.1  # Use the tag or commit you want
+    hooks:
+      - id: clang-format
+        args: [--style=file, --version=18, --verbose]   # Added --verbose
+        files: ^(src|include)/.*\.(cpp|cc|cxx|h|hpp)$
+      - id: clang-tidy
+        args: [--checks=.clang-tidy, --version=18, --verbose]  # Added --verbose
+        files: ^(src|include)/.*\.(cpp|cc|cxx|h|hpp)$
+
+# To use this configuration:
+# 1. Save this as .pre-commit-config.yaml in your project root
+# 2. Run: pre-commit run --verbose --all-files
+# 3. The --verbose flag to pre-commit combined with --verbose in args
+#    will give you maximum debugging information
+
+# For your specific exit code 247 issue, you'll now see:
+# - The exact clang-format command being executed
+# - The path to the clang-format executable
+# - The version being used
+# - Both stdout and stderr output
+# - The actual exit code from clang-format
diff --git a/tests/test_clang_format.py b/tests/test_clang_format.py
@@ -1,7 +1,8 @@
 import pytest
 from pathlib import Path
+from unittest.mock import patch, MagicMock
 
-from cpp_linter_hooks.clang_format import run_clang_format
+from cpp_linter_hooks.clang_format import run_clang_format, main
 
 
 @pytest.mark.parametrize(
@@ -64,3 +65,97 @@ def test_run_clang_format_dry_run(args, expected_retval, tmp_path):
     test_file = tmp_path / "main.c"
     ret, _ = run_clang_format(["--dry-run", str(test_file)])
     assert ret == -1  # Dry run should not fail
+
+
+def test_main_empty_output():
+    """Test main() function when clang-format returns error with empty output"""
+    with patch(
+        "cpp_linter_hooks.clang_format.run_clang_format"
+    ) as mock_run_clang_format:
+        # Mock failed run with empty output
+        mock_run_clang_format.return_value = (1, "")
+
+        with patch("builtins.print") as mock_print:
+            result = main()
+
+            # Should return 1 and print empty string
+            assert result == 1
+            mock_print.assert_called_once_with("")
+
+
+def test_verbose_output(tmp_path, capsys):
+    """Test that verbose mode produces debug output to stderr"""
+    test_file = tmp_path / "test.c"
+    test_file.write_text("#include <stdio.h>\nint main(){return 0;}")
+
+    with patch("cpp_linter_hooks.clang_format.ensure_installed") as mock_ensure:
+        mock_ensure.return_value = "/fake/clang-format"
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")
+
+            # Test verbose mode
+            retval, output = run_clang_format(
+                ["--verbose", "--style=Google", str(test_file)]
+            )
+
+            # Check that debug messages were printed to stderr
+            captured = capsys.readouterr()
+            assert "[DEBUG] clang-format command:" in captured.err
+            assert "[DEBUG] clang-format version:" in captured.err
+            assert "[DEBUG] clang-format executable:" in captured.err
+            assert "[DEBUG] Exit code:" in captured.err
+
+
+def test_verbose_with_error(tmp_path, capsys):
+    """Test verbose output when there's an error"""
+    test_file = tmp_path / "test.c"
+
+    with patch("cpp_linter_hooks.clang_format.ensure_installed") as mock_ensure:
+        mock_ensure.return_value = "/fake/clang-format"
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(
+                returncode=1, stdout="error output", stderr="error in stderr"
+            )
+
+            # Test verbose mode with error
+            retval, output = run_clang_format(
+                ["--verbose", "--style=Google", str(test_file)]
+            )
+
+            # Check return values
+            assert retval == 1
+            assert "error output" in output
+            assert "error in stderr" in output
+
+            # Check debug output
+            captured = capsys.readouterr()
+            assert "[DEBUG] Exit code: 1" in captured.err
+            assert "[DEBUG] stdout:" in captured.err
+            assert "[DEBUG] stderr:" in captured.err
+
+
+def test_verbose_dry_run(tmp_path, capsys):
+    """Test verbose output in dry-run mode"""
+    test_file = tmp_path / "test.c"
+    test_file.write_text("#include <stdio.h>\nint main(){return 0;}")
+
+    with patch("cpp_linter_hooks.clang_format.ensure_installed") as mock_ensure:
+        mock_ensure.return_value = "/fake/clang-format"
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(
+                returncode=0, stdout="dry run output", stderr=""
+            )
+
+            # Test verbose dry-run mode
+            retval, output = run_clang_format(
+                ["--verbose", "--dry-run", str(test_file)]
+            )
+
+            # Check return values (dry-run should return -1)
+            assert retval == -1
+            assert "dry run output" in output
+
+            # Check debug output
+            captured = capsys.readouterr()
+            assert "[DEBUG] Dry-run mode detected" in captured.err
+            assert "[DEBUG] Exit code: 0 (converted to -1 for dry-run)" in captured.err
diff --git a/tests/test_clang_tidy.py b/tests/test_clang_tidy.py
