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>
2026-02-02 15:08:46 +00:00 · 2025-08-08 22:36:49 -07:00
parent 05cff5cfde
commit 0827add9a3
21 changed files with 319 additions and 41 deletions
--- a/.github/workflows/CLAUDE.md
+++ b/.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
--- a/.github/workflows/format.yml
+++ b/.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