ci: optimize clang-format in GitHub Actions (#21715)

## Summary
- Replace cmake-based clang-format with dedicated bash script that
directly processes source files
- Optimize CI to only install clang-format-19 instead of entire LLVM
toolchain
- Script enforces specific clang-format version with no fallbacks

## Changes
1. **New bash script** (`scripts/run-clang-format.sh`):
   - Directly reads C++ files from `CxxSources.txt`
   - Finds all header files in `src/` and `packages/` directories
   - Respects existing `.clang-format` configuration files
   - Requires specific clang-format version (no fallbacks)
   - Defaults to format mode (modifies files in place)

2. **Optimized GitHub Action**:
- Only installs `clang-format-19` package with `--no-install-recommends`
   - Avoids installing unnecessary components like manpages
   - Uses new bash script instead of cmake targets

3. **Updated package.json scripts**:
- `clang-format`, `clang-format:check`, and `clang-format:diff` now use
the bash script

## Test plan
- [x] Verified script finds and processes all C++ source and header
files
- [x] Tested formatting works correctly by adding formatting issues and
running the script
- [x] Confirmed script respects `.clang-format` configuration files
- [x] Script correctly requires specific clang-format version

🤖 Generated with [Claude Code](https://claude.ai/code)

---------

Co-authored-by: Claude <claude@anthropic.ai>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

.github/workflows/CLAUDE.md

@@ -0,0 +1,103 @@
+# GitHub Actions Workflow Maintenance Guide
+
+This document provides guidance for maintaining the GitHub Actions workflows in this repository.
+
+## format.yml Workflow
+
+### Overview
+The `format.yml` workflow runs code formatters (Prettier, clang-format, and Zig fmt) on pull requests and pushes to main. It's optimized for speed by running all formatters in parallel.
+
+### Key Components
+
+#### 1. Clang-format Script (`scripts/run-clang-format.sh`)
+- **Purpose**: Formats C++ source and header files
+- **What it does**:
+  - Reads C++ files from `cmake/sources/CxxSources.txt`
+  - Finds all header files in `src/` and `packages/`
+  - Excludes third-party directories (libuv, napi, deps, vendor, sqlite, etc.)
+  - Requires specific clang-format version (no fallbacks)
+
+**Important exclusions**:
+- `src/napi/` - Node API headers (third-party)
+- `src/bun.js/bindings/libuv/` - libuv headers (third-party)
+- `src/bun.js/bindings/sqlite/` - SQLite headers (third-party)
+- `src/bun.js/api/ffi-*.h` - FFI headers (generated/third-party)
+- `src/deps/` - Dependencies (third-party)
+- Files in `vendor/`, `third_party/`, `generated/` directories
+
+#### 2. Parallel Execution
+The workflow runs all three formatters simultaneously:
+- Each formatter outputs with a prefix (`[prettier]`, `[clang-format]`, `[zig]`)
+- Output is streamed in real-time without blocking
+- Uses GitHub Actions groups (`::group::`) for collapsible sections
+
+#### 3. Tool Installation
+
+##### Clang-format-19
+- Installs ONLY `clang-format-19` package (not the entire LLVM toolchain)
+- Uses `--no-install-recommends --no-install-suggests` to skip unnecessary packages
+- Quiet installation with `-qq` and `-o=Dpkg::Use-Pty=0`
+
+##### Zig
+- Downloads from `oven-sh/zig` releases (musl build for static linking)
+- URL: `https://github.com/oven-sh/zig/releases/download/autobuild-{COMMIT}/bootstrap-x86_64-linux-musl.zip`
+- Extracts to temp directory to avoid polluting the repository
+- Directory structure: `bootstrap-x86_64-linux-musl/zig`
+
+### Updating the Workflow
+
+#### To update Zig version:
+1. Find the new commit hash from https://github.com/oven-sh/zig/releases
+2. Replace the hash in the wget URL (line 65 of format.yml)
+3. Test that the URL is valid and the binary works
+
+#### To update clang-format version:
+1. Update `LLVM_VERSION_MAJOR` environment variable at the top of format.yml
+2. Update the version check in `scripts/run-clang-format.sh`
+
+#### To add/remove file exclusions:
+1. Edit the exclusion patterns in `scripts/run-clang-format.sh` (lines 34-39)
+2. Test locally to ensure the right files are being formatted
+
+### Performance Optimizations
+1. **Parallel execution**: All formatters run simultaneously
+2. **Minimal installations**: Only required packages, no extras
+3. **Temp directories**: Tools downloaded to temp dirs, cleaned up after use
+4. **Streaming output**: Real-time feedback without buffering
+5. **Early start**: Formatting begins immediately after each tool is ready
+
+### Troubleshooting
+
+**If formatters appear to run sequentially:**
+- Check if output is being buffered (should use `sed` for line prefixing)
+- Ensure background processes use `&` and proper wait commands
+
+**If third-party files are being formatted:**
+- Review exclusion patterns in `scripts/run-clang-format.sh`
+- Check if new third-party directories were added that need exclusion
+
+**If clang-format installation is slow:**
+- Ensure using minimal package installation flags
+- Check if apt cache needs updating
+- Consider caching the clang-format binary between runs
+
+### Testing Changes Locally
+
+```bash
+# Test the clang-format script
+export LLVM_VERSION_MAJOR=19
+./scripts/run-clang-format.sh format
+
+# Test with check mode (no modifications)
+./scripts/run-clang-format.sh check
+
+# Test specific file exclusions
+./scripts/run-clang-format.sh format 2>&1 | grep -E "(libuv|napi|deps)"
+# Should return nothing if exclusions work correctly
+```
+
+### Important Notes
+- The script defaults to **format** mode (modifies files)
+- Always test locally before pushing workflow changes
+- The musl Zig build works on glibc systems due to static linking
+- Keep the exclusion list updated as new third-party code is added

.github/workflows/format.yml

@@ -37,24 +37,72 @@ jobs:
       - name: Setup Dependencies
         run: |
           bun install
-      - name: Install LLVM
+      - name: Format Code
         run: |
-          curl -fsSL https://apt.llvm.org/llvm.sh | sudo bash -s -- ${{ env.LLVM_VERSION_MAJOR }} all
-      - name: Setup Zig
-        uses: mlugg/setup-zig@v1
-        with:
-          version: 0.14.0
-      - name: Zig Format
-        run: |
-          zig fmt src
-          ./scripts/sort-imports.ts src
-          zig fmt src
-      - name: Prettier Format
-        run: |
-          bun run prettier
-      - name: Clang Format
-        run: |
-          bun run clang-format
+          # Start prettier in background with prefixed output
+          echo "::group::Prettier"
+          (bun run prettier 2>&1 | sed 's/^/[prettier] /' || echo "[prettier] Failed with exit code $?") &
+          PRETTIER_PID=$!
+          
+          # Start clang-format installation and formatting in background with prefixed output
+          echo "::group::Clang-format"
+          (
+            echo "[clang-format] Installing clang-format-${{ env.LLVM_VERSION_MAJOR }}..."
+            wget -qO- https://apt.llvm.org/llvm-snapshot.gpg.key | sudo tee /etc/apt/trusted.gpg.d/apt.llvm.org.asc > /dev/null
+            echo "deb http://apt.llvm.org/$(lsb_release -cs)/ llvm-toolchain-$(lsb_release -cs)-${{ env.LLVM_VERSION_MAJOR }} main" | sudo tee /etc/apt/sources.list.d/llvm.list > /dev/null
+            sudo apt-get update -qq
+            sudo apt-get install -y -qq --no-install-recommends --no-install-suggests -o=Dpkg::Use-Pty=0 clang-format-${{ env.LLVM_VERSION_MAJOR }}
+            echo "[clang-format] Running clang-format..."
+            LLVM_VERSION_MAJOR=${{ env.LLVM_VERSION_MAJOR }} ./scripts/run-clang-format.sh format 2>&1 | sed 's/^/[clang-format] /'
+          ) &
+          CLANG_PID=$!
+          
+          # Setup Zig in temp directory and run zig fmt in background with prefixed output
+          echo "::group::Zig fmt"
+          (
+            ZIG_TEMP=$(mktemp -d)
+            echo "[zig] Downloading Zig (musl build)..."
+            wget -q -O "$ZIG_TEMP/zig.zip" https://github.com/oven-sh/zig/releases/download/autobuild-d1a4e0b0ddc75f37c6a090b97eef0cbb6335556e/bootstrap-x86_64-linux-musl.zip
+            unzip -q -d "$ZIG_TEMP" "$ZIG_TEMP/zig.zip"
+            export PATH="$ZIG_TEMP/bootstrap-x86_64-linux-musl:$PATH"
+            echo "[zig] Running zig fmt..."
+            zig fmt src 2>&1 | sed 's/^/[zig] /'
+            ./scripts/sort-imports.ts src 2>&1 | sed 's/^/[zig] /'
+            zig fmt src 2>&1 | sed 's/^/[zig] /'
+            rm -rf "$ZIG_TEMP"
+          ) &
+          ZIG_PID=$!
+          
+          # Wait for all formatting tasks to complete
+          echo ""
+          echo "Running formatters in parallel..."
+          FAILED=0
+          
+          if ! wait $PRETTIER_PID; then
+            echo "::error::Prettier failed"
+            FAILED=1
+          fi
+          echo "::endgroup::"
+          
+          if ! wait $CLANG_PID; then
+            echo "::error::Clang-format failed"
+            FAILED=1
+          fi
+          echo "::endgroup::"
+          
+          if ! wait $ZIG_PID; then
+            echo "::error::Zig fmt failed"
+            FAILED=1
+          fi
+          echo "::endgroup::"
+          
+          # Exit with error if any formatter failed
+          if [ $FAILED -eq 1 ]; then
+            echo "::error::One or more formatters failed"
+            exit 1
+          fi
+          
+          echo "✅ All formatters completed successfully"
       - name: Ban Words
         run: |
           bun ./test/internal/ban-words.test.ts

package.json

@@ -68,9 +68,9 @@
     "zig:check-windows": "bun run zig build check-windows --summary new",
     "analysis": "bun ./scripts/build.mjs -DCMAKE_BUILD_TYPE=Debug -DENABLE_ANALYSIS=ON -DENABLE_CCACHE=OFF -B build/analysis",
     "analysis:no-llvm": "bun run analysis -DENABLE_LLVM=OFF",
-    "clang-format": "bun run analysis --target clang-format",
-    "clang-format:check": "bun run analysis --target clang-format-check",
-    "clang-format:diff": "bun run analysis --target clang-format-diff",
+    "clang-format": "./scripts/run-clang-format.sh format",
+    "clang-format:check": "./scripts/run-clang-format.sh check",
+    "clang-format:diff": "./scripts/run-clang-format.sh diff",
     "clang-tidy": "bun run analysis --target clang-tidy",
     "clang-tidy:check": "bun run analysis --target clang-tidy-check",
     "clang-tidy:diff": "bun run analysis --target clang-tidy-diff",

scripts/run-clang-format.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Run clang-format on all C++ source and header files in the Bun project
+
+# Get the directory where this script is located
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# Get the project root directory (parent of scripts/)
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# Default to format mode (modify files)
+MODE="${1:-format}"
+
+# Use LLVM_VERSION_MAJOR from environment or default to 19
+LLVM_VERSION="${LLVM_VERSION_MAJOR:-19}"
+
+# Ensure we have the specific clang-format version
+CLANG_FORMAT="clang-format-${LLVM_VERSION}"
+if ! command -v "$CLANG_FORMAT" &> /dev/null; then
+    echo "Error: $CLANG_FORMAT not found" >&2
+    echo "Please install clang-format version $LLVM_VERSION" >&2
+    exit 1
+fi
+
+cd "$PROJECT_ROOT"
+
+# Array to hold all files to format
+declare -a FILES_TO_FORMAT
+
+# Find all header files in src/ and packages/, excluding third-party and generated code
+echo "Finding header files..."
+while IFS= read -r -d '' file; do
+    # Additional filtering for specific files and patterns
+    if [[ "$file" =~ src/bun\.js/api/ffi- ]] || \
+       [[ "$file" =~ src/napi/ ]] || \
+       [[ "$file" =~ src/bun\.js/bindings/libuv/ ]] || \
+       [[ "$file" =~ src/bun\.js/bindings/sqlite/ ]] || \
+       [[ "$file" =~ packages/bun-usockets/.*libuv ]] || \
+       [[ "$file" =~ src/deps/ ]]; then
+        continue
+    fi
+    FILES_TO_FORMAT+=("$file")
+done < <(find src packages -type f \( -name "*.h" -o -name "*.hpp" \) \
+    -not -path "*/vendor/*" \
+    -not -path "*/third_party/*" \
+    -not -path "*/thirdparty/*" \
+    -not -path "*/generated/*" \
+    -print0 2>/dev/null || true)
+
+# Read C++ source files from CxxSources.txt
+echo "Reading C++ source files from CxxSources.txt..."
+if [ -f "cmake/sources/CxxSources.txt" ]; then
+    while IFS= read -r file; do
+        # Skip empty lines and comments
+        if [[ -n "$file" && ! "$file" =~ ^[[:space:]]*# ]]; then
+            # Check if file exists
+            if [ -f "$file" ]; then
+                FILES_TO_FORMAT+=("$file")
+            fi
+        fi
+    done < "cmake/sources/CxxSources.txt"
+else
+    echo "Warning: cmake/sources/CxxSources.txt not found" >&2
+fi
+
+# Remove duplicates while preserving order
+declare -a UNIQUE_FILES
+declare -A seen
+for file in "${FILES_TO_FORMAT[@]}"; do
+    if [[ ! -v "seen[$file]" ]]; then
+        seen["$file"]=1
+        UNIQUE_FILES+=("$file")
+    fi
+done
+
+echo "Processing ${#UNIQUE_FILES[@]} files..."
+
+# Run clang-format based on mode
+if [ "$MODE" = "check" ]; then
+    # Check mode - verify formatting without modifying files
+    FAILED=0
+    for file in "${UNIQUE_FILES[@]}"; do
+        # Find the nearest .clang-format file for this source file
+        dir=$(dirname "$file")
+        while [ "$dir" != "." ] && [ "$dir" != "/" ]; do
+            if [ -f "$dir/.clang-format" ]; then
+                break
+            fi
+            dir=$(dirname "$dir")
+        done
+        
+        if ! $CLANG_FORMAT --dry-run --Werror "$file" 2>/dev/null; then
+            echo "Format check failed: $file"
+            FAILED=1
+        fi
+    done
+    
+    if [ $FAILED -eq 1 ]; then
+        echo "Some files need formatting. Run 'bun run clang-format' to fix."
+        exit 1
+    else
+        echo "All files are properly formatted."
+    fi
+elif [ "$MODE" = "format" ] || [ "$MODE" = "fix" ]; then
+    # Format mode - modify files in place
+    for file in "${UNIQUE_FILES[@]}"; do
+        echo "Formatting: $file"
+        $CLANG_FORMAT -i "$file"
+    done
+    echo "Formatting complete."
+elif [ "$MODE" = "diff" ]; then
+    # Diff mode - show what would change
+    for file in "${UNIQUE_FILES[@]}"; do
+        if ! $CLANG_FORMAT --dry-run --Werror "$file" 2>/dev/null; then
+            echo "=== $file ==="
+            diff -u "$file" <($CLANG_FORMAT "$file") || true
+        fi
+    done
+else
+    echo "Usage: $0 [check|format|fix|diff]" >&2
+    echo "  check  - Check if files are formatted (default)" >&2
+    echo "  format - Format files in place" >&2
+    echo "  fix    - Same as format" >&2
+    echo "  diff   - Show formatting differences" >&2
+    exit 1
+fi

src/bake/BakeProduction.h

@@ -2,4 +2,4 @@
 #include "headers-handwritten.h"
 
 namespace Bake {
-} // namespace Bake
+} // namespace Bake

src/bun.js/bindings/v8/V8Array.h

@@ -30,7 +30,8 @@ public:
         std::function<MaybeLocal<v8::Value>()> next_value_callback);
 
     // Cast a Value to Array (with optional type checking)
-    inline static Array* Cast(Value* value) {
+    inline static Array* Cast(Value* value)
+    {
 #ifdef V8_ENABLE_CHECKS
         CheckCast(value);
 #endif
@@ -43,12 +44,12 @@ public:
         kContinue,
     };
     using IterationCallback = CallbackResult (*)(uint32_t index,
-                                                 Local<Value> element,
-                                                 void* data);
+        Local<Value> element,
+        void* data);
 
     // Iterates over array elements efficiently
     BUN_EXPORT Maybe<void> Iterate(Local<Context> context, IterationCallback callback,
-                      void* callback_data);
+        void* callback_data);
 
 private:
     Array();

src/bun.js/bindings/v8/V8Object.h

@@ -16,13 +16,13 @@ public:
     BUN_EXPORT static Local<Object> New(Isolate* isolate);
     BUN_EXPORT Maybe<bool> Set(Local<Context> context, Local<Value> key, Local<Value> value);
     BUN_EXPORT Maybe<bool> Set(Local<Context> context, uint32_t index, Local<Value> value);
-    
+
     // Get property by key
     BUN_EXPORT MaybeLocal<Value> Get(Local<Context> context, Local<Value> key);
-    
+
     // Get property by index (for arrays)
     BUN_EXPORT MaybeLocal<Value> Get(Local<Context> context, uint32_t index);
-    
+
     BUN_EXPORT void SetInternalField(int index, Local<Data> data);
     // usually inlined
     BUN_EXPORT Local<Data> GetInternalField(int index);

src/bun.js/bindings/v8/V8Value.h

@@ -15,7 +15,7 @@ public:
     BUN_EXPORT bool IsUint32() const;
     BUN_EXPORT bool IsFunction() const;
     BUN_EXPORT Maybe<uint32_t> Uint32Value(Local<Context> context) const;
-    
+
     // Comparison methods
     BUN_EXPORT bool StrictEquals(Local<Value> that) const;
 

src/bun.js/bindings/webcore/ExtendedDOMClientIsoSubspaces.h

@@ -38,4 +38,4 @@ public:
 
 namespace WebCore {
 using ExtendedDOMClientIsoSubspaces = WebCore::ExtendedDOMClientIsoSubspaces;
-}
+}

src/bun.js/bindings/webcore/JSDOMConvert.h

@@ -46,4 +46,4 @@
 #include "JSDOMConvertUnion.h"
 #include "JSDOMConvertWebGL.h"
 
-#include "JSDOMConvertBufferSource+JSBuffer.h"
+#include "JSDOMConvertBufferSource+JSBuffer.h"

src/bun.js/bindings/webcore/JSDOMWindow.h

@@ -1 +1 @@
-// this is a stub header file
+// this is a stub header file

src/bun.js/bindings/webcore/JSEventTargetNode.h

@@ -4,4 +4,4 @@ namespace Bun {
 
 JSC_DECLARE_HOST_FUNCTION(jsFunctionNodeEventsGetEventListeners);
 
-}
+}

src/bun.js/bindings/webcore/JSMIMEType.h

@@ -97,4 +97,4 @@ private:
 // Function to setup the structures lazily
 void setupJSMIMETypeClassStructure(JSC::LazyClassStructure::Initializer&);
 
-} // namespace WebCore
+} // namespace WebCore

src/bun.js/bindings/webcore/JSServiceWorker.h

@@ -1 +1 @@
-// stub
+// stub

src/bun.js/bindings/webcore/JSWindowProxy.h

@@ -1 +1 @@
-// stub
+// stub

src/bun.js/bindings/webcore/WebCoreJSClientData.h

@@ -1,3 +1,3 @@
 #pragma once
 
-#include "BunClientData.h"
+#include "BunClientData.h"

src/bun.js/bindings/webcore/WebCoreTypedArrayController.h

@@ -52,4 +52,4 @@ private:
     bool m_allowAtomicsWait;
 };
 
-} // namespace WebCore
+} // namespace WebCore

src/bun.js/bindings/webcore/config.h

@@ -3,4 +3,4 @@
 #ifndef WEBCORE_CONFIG
 #define WEBCORE_CONFIG
 #include "root.h"
-#endif
+#endif

src/bun.js/bindings/webcrypto/CryptoAlgorithmX25519.h

@@ -37,7 +37,7 @@ private:
     CryptoAlgorithmX25519() = default;
     CryptoAlgorithmIdentifier identifier() const final;
 
-    void generateKey(const CryptoAlgorithmParameters& , bool extractable, CryptoKeyUsageBitmap usages, KeyOrKeyPairCallback&& , ExceptionCallback&& , ScriptExecutionContext&);
+    void generateKey(const CryptoAlgorithmParameters&, bool extractable, CryptoKeyUsageBitmap usages, KeyOrKeyPairCallback&&, ExceptionCallback&&, ScriptExecutionContext&);
     void deriveBits(const CryptoAlgorithmParameters&, Ref<CryptoKey>&&, std::optional<size_t> length, VectorCallback&&, ExceptionCallback&&, ScriptExecutionContext&, WorkQueue&);
     void importKey(CryptoKeyFormat, KeyData&&, const CryptoAlgorithmParameters&, bool extractable, CryptoKeyUsageBitmap, KeyCallback&&, ExceptionCallback&&) final;
     void exportKey(CryptoKeyFormat, Ref<CryptoKey>&&, KeyDataCallback&&, ExceptionCallback&&) final;

src/bun.js/bindings/webcrypto/CryptoAlgorithmX25519Params.h

@@ -31,6 +31,7 @@ namespace WebCore {
 
 class CryptoAlgorithmX25519Params final : public CryptoAlgorithmParameters {
     WTF_MAKE_TZONE_ALLOCATED(CryptoAlgorithmX25519Params);
+
 public:
     RefPtr<CryptoKey> publicKey;
     Class parametersClass() const final { return Class::X25519Params; }

src/bun.js/bindings/webcrypto/JSX25519Params.h

@@ -20,7 +20,6 @@
 
 #pragma once
 
-
 #if ENABLE(WEB_CRYPTO)
 
 #include "CryptoAlgorithmX25519Params.h"