feat: Add parallel execution support for clang-tidy (#203)

Author: shenxianpeng

README.md

@@ -211,6 +211,22 @@ Use -header-filter=.* to display errors from all non-system headers. Use -system
       files: ^(src|include)/.*\.(cpp|cc|cxx|h|hpp)$
 ```
 
+For `clang-tidy`, you can also process multiple files in parallel by adding `--jobs`
+or `-j`:
+
+```yaml
+- repo: https://github.com/cpp-linter/cpp-linter-hooks
+  rev: v1.2.0
+  hooks:
+    - id: clang-tidy
+      args: [--checks=.clang-tidy, --version=21, --jobs=4]
+```
+
+> [!WARNING]
+> When using `--jobs`/`-j`, avoid sharing options that write to a single output file
+> (for example `--export-fixes=fixes.yaml`) across parallel `clang-tidy` invocations.
+> If you need `--export-fixes`, ensure each job writes to a unique file path to avoid
+> corrupted or overwritten outputs.
 Alternatively, if you want to run the hooks manually on only the changed files, you can use the following command:
 
 ```bash

cpp_linter_hooks/clang_tidy.py

@@ -1,19 +1,49 @@
+from concurrent.futures import ThreadPoolExecutor
 import subprocess
 import sys
-from argparse import ArgumentParser
+from argparse import ArgumentParser, ArgumentTypeError
 from pathlib import Path
-from typing import Optional, Tuple
+from typing import List, Optional, Tuple
 
 from cpp_linter_hooks.util import resolve_install, DEFAULT_CLANG_TIDY_VERSION
 
 COMPILE_DB_SEARCH_DIRS = ["build", "out", "cmake-build-debug", "_build"]
+SOURCE_FILE_SUFFIXES = {
+    ".c",
+    ".cc",
+    ".cp",
+    ".cpp",
+    ".cxx",
+    ".c++",
+    ".cu",
+    ".cuh",
+    ".h",
+    ".hh",
+    ".hpp",
+    ".hxx",
+    ".h++",
+    ".ipp",
+    ".inl",
+    ".ixx",
+    ".tpp",
+    ".txx",
+}
+
+
+def _positive_int(value: str) -> int:
+    jobs = int(value)
+    if jobs < 1:
+        raise ArgumentTypeError("--jobs must be greater than 0")
+    return jobs
+
 
 parser = ArgumentParser()
 parser.add_argument("--version", default=DEFAULT_CLANG_TIDY_VERSION)
 parser.add_argument("--compile-commands", default=None, dest="compile_commands")
 parser.add_argument(
     "--no-compile-commands", action="store_true", dest="no_compile_commands"
 )
+parser.add_argument("-j", "--jobs", type=_positive_int, default=1)
 parser.add_argument("-v", "--verbose", action="store_true")
 
 
@@ -74,6 +104,38 @@ def _exec_clang_tidy(command) -> Tuple[int, str]:
         return 1, str(e)
 
 
+def _looks_like_source_file(path: str) -> bool:
+    return Path(path).suffix.lower() in SOURCE_FILE_SUFFIXES
+
+
+def _split_source_files(args: List[str]) -> Tuple[List[str], List[str]]:
+    split_idx = len(args)
+    source_files: List[str] = []
+    for idx in range(len(args) - 1, -1, -1):
+        if not _looks_like_source_file(args[idx]):
+            break
+        source_files.append(args[idx])
+        split_idx = idx
+    return args[:split_idx], list(reversed(source_files))
+
+
+def _combine_outputs(results: List[Tuple[int, str]]) -> str:
+    return "\n".join(output.rstrip("\n") for _, output in results if output)
+
+
+def _exec_parallel_clang_tidy(
+    command_prefix: List[str], source_files: List[str], jobs: int
+) -> Tuple[int, str]:
+    def run_file(source_file: str) -> Tuple[int, str]:
+        return _exec_clang_tidy(command_prefix + [source_file])
+
+    with ThreadPoolExecutor(max_workers=min(jobs, len(source_files))) as executor:
+        results = list(executor.map(run_file, source_files))
+
+    retval = 1 if any(retval != 0 for retval, _ in results) else 0
+    return retval, _combine_outputs(results)
+
+
 def run_clang_tidy(args=None) -> Tuple[int, str]:
     hook_args, other_args = parser.parse_known_args(args)
     if hook_args.version:
@@ -90,6 +152,21 @@ def run_clang_tidy(args=None) -> Tuple[int, str]:
             )
         other_args = ["-p", compile_db_path] + other_args
 
+    clang_tidy_args, source_files = _split_source_files(other_args)
+
+    # Parallel execution is unsafe when arguments include flags that write to a
+    # shared output path (e.g., --export-fixes fixes.yaml). In that case, force
+    # serial execution to avoid concurrent writes/overwrites.
+    unsafe_parallel = any(
+        arg == "--export-fixes" or arg.startswith("--export-fixes=")
+        for arg in clang_tidy_args
+    )
+
+    if hook_args.jobs > 1 and len(source_files) > 1 and not unsafe_parallel:
+        return _exec_parallel_clang_tidy(
+            ["clang-tidy"] + clang_tidy_args, source_files, hook_args.jobs
+        )
+
     return _exec_clang_tidy(["clang-tidy"] + other_args)
 
 

testing/pre-commit-config-parallel.yaml

@@ -0,0 +1,6 @@
+repos:
+  - repo: .
+    rev: HEAD
+    hooks:
+      - id: clang-tidy
+        args: [--checks=.clang-tidy, --jobs=2]

testing/run.sh

@@ -40,6 +40,32 @@ else
     exit_code=1
 fi
 
+# Test parallel execution with multiple source files
+echo "===================================="
+echo "Test pre-commit-config-parallel.yaml"
+echo "===================================="
+uvx pre-commit clean
+uvx pre-commit run -c testing/pre-commit-config-parallel.yaml \
+    --files testing/main.c testing/good.c | tee -a parallel_result.txt || true
+git restore testing/main.c
+
+parallel_failed=$(grep -c "Failed" parallel_result.txt 2>/dev/null || echo "0")
+echo "$parallel_failed parallel cases failed."
+
+if [[ $parallel_failed -ge 1 ]]; then
+    echo "========================================================"
+    echo "Parallel test passed (expected failures detected: $parallel_failed)."
+    echo "========================================================"
+    parallel_result="success"
+    rm parallel_result.txt
+else
+    echo "==========================================="
+    echo "Parallel test failed (no failures detected)."
+    echo "==========================================="
+    parallel_result="failure"
+    exit_code=1
+fi
+
 # Add result to GitHub summary if running in GitHub Actions
 if [[ -n "$GITHUB_STEP_SUMMARY" ]]; then
     {
@@ -48,6 +74,8 @@ if [[ -n "$GITHUB_STEP_SUMMARY" ]]; then
         echo "**Result:** $result"
         echo ""
         echo "**Failed cases:** $failed_cases"
+        echo ""
+        echo "**Parallel test:** $parallel_result"
     } >> "$GITHUB_STEP_SUMMARY"
 fi
 

tests/test_clang_tidy.py

@@ -1,5 +1,6 @@
 import pytest
 import subprocess
+import time
 from pathlib import Path
 from unittest.mock import patch, MagicMock
 
@@ -227,3 +228,99 @@ def test_no_verbose_no_extra_stderr(tmp_path, monkeypatch, capsys):
     ):
         run_clang_tidy(["dummy.cpp"])
     assert capsys.readouterr().err == ""
+
+
+def test_jobs_one_keeps_single_invocation():
+    with (
+        patch(
+            "cpp_linter_hooks.clang_tidy._exec_clang_tidy", return_value=(0, "")
+        ) as mock_exec,
+        patch("cpp_linter_hooks.clang_tidy.resolve_install"),
+    ):
+        run_clang_tidy(["--jobs=1", "-p", "./build", "a.cpp", "b.cpp"])
+
+    mock_exec.assert_called_once_with(["clang-tidy", "-p", "./build", "a.cpp", "b.cpp"])
+
+
+def test_jobs_parallelizes_source_files_and_preserves_output_order():
+    def fake_exec(command):
+        source_file = command[-1]
+        if source_file == "a.cpp":
+            time.sleep(0.05)
+            return 0, "a.cpp output"
+        return 1, "b.cpp output"
+
+    with (
+        patch("cpp_linter_hooks.clang_tidy._exec_clang_tidy", side_effect=fake_exec),
+        patch("cpp_linter_hooks.clang_tidy.resolve_install"),
+    ):
+        ret, output = run_clang_tidy(
+            [
+                "--jobs=4",
+                "-p",
+                "./build",
+                "--header-filter=.*",
+                "a.cpp",
+                "b.cpp",
+            ]
+        )
+
+    assert ret == 1
+    assert output == "a.cpp output\nb.cpp output"
+
+
+def test_jobs_parallelizes_only_trailing_source_files():
+    with (
+        patch(
+            "cpp_linter_hooks.clang_tidy._exec_clang_tidy", return_value=(0, "")
+        ) as mock_exec,
+        patch("cpp_linter_hooks.clang_tidy.resolve_install"),
+    ):
+        run_clang_tidy(
+            [
+                "--jobs=2",
+                "-p",
+                "./build",
+                "--header-filter=.*",
+                "a.cpp",
+                "b.hpp",
+            ]
+        )
+
+    commands = {tuple(call.args[0]) for call in mock_exec.call_args_list}
+    assert commands == {
+        ("clang-tidy", "-p", "./build", "--header-filter=.*", "a.cpp"),
+        ("clang-tidy", "-p", "./build", "--header-filter=.*", "b.hpp"),
+    }
+
+
+def test_jobs_with_export_fixes_forces_serial_execution():
+    with (
+        patch(
+            "cpp_linter_hooks.clang_tidy._exec_clang_tidy", return_value=(0, "")
+        ) as mock_exec,
+        patch("cpp_linter_hooks.clang_tidy.resolve_install"),
+    ):
+        run_clang_tidy(
+            [
+                "--jobs=4",
+                "-p",
+                "./build",
+                "--export-fixes",
+                "fixes.yaml",
+                "a.cpp",
+                "b.cpp",
+            ]
+        )
+
+    mock_exec.assert_called_once_with(
+        [
+            "clang-tidy",
+            "-p",
+            "./build",
+            "--export-fixes",
+            "fixes.yaml",
+            "a.cpp",
+            "b.cpp",
+        ]
+    )