Stabilize macOS bindgen deps with pinned llvm@18

Author: ealdent

.github/workflows/ci.yml

@@ -229,20 +229,24 @@ jobs:
         if: ${{ matrix.kind == 'linux' }}
         run: sudo apt-get update && sudo apt-get install -y clang libclang-dev pkg-config
 
+      - name: Install Rust bindgen dependencies (macOS)
+        if: ${{ matrix.kind == 'macos' }}
+        shell: bash
+        run: |
+          if brew install llvm@18; then
+            llvm_prefix="$(brew --prefix llvm@18)"
+          else
+            brew install llvm
+            llvm_prefix="$(brew --prefix llvm)"
+          fi
+          echo "LIBCLANG_PATH=${llvm_prefix}/lib" >> "${GITHUB_ENV}"
+
       - name: Install LLVM (bindgen dependency)
-        if: ${{ matrix.kind == 'windows' || matrix.kind == 'macos' }}
+        if: ${{ matrix.kind == 'windows' }}
         uses: KyleMayes/install-llvm-action@v2
         with:
           version: "18.1.8"
 
-      - name: Export LIBCLANG_PATH (macOS)
-        if: ${{ matrix.kind == 'macos' }}
-        shell: bash
-        run: |
-          llvm_bin="$(dirname "$(command -v llvm-config)")"
-          llvm_root="$(cd "${llvm_bin}/.." && pwd)"
-          echo "LIBCLANG_PATH=${llvm_root}/lib" >> "${GITHUB_ENV}"
-
       - name: Configure bindgen include paths for Windows Ruby headers
         if: ${{ matrix.kind == 'windows' }}
         shell: pwsh

.github/workflows/release.yml

@@ -170,20 +170,24 @@ jobs:
         if: ${{ matrix.kind == 'linux' }}
         run: sudo apt-get update && sudo apt-get install -y clang libclang-dev pkg-config
 
+      - name: Install Rust bindgen dependencies (macOS)
+        if: ${{ matrix.kind == 'macos' }}
+        shell: bash
+        run: |
+          if brew install llvm@18; then
+            llvm_prefix="$(brew --prefix llvm@18)"
+          else
+            brew install llvm
+            llvm_prefix="$(brew --prefix llvm)"
+          fi
+          echo "LIBCLANG_PATH=${llvm_prefix}/lib" >> "${GITHUB_ENV}"
+
       - name: Install LLVM (bindgen dependency)
-        if: ${{ matrix.kind == 'windows' || matrix.kind == 'macos' }}
+        if: ${{ matrix.kind == 'windows' }}
         uses: KyleMayes/install-llvm-action@v2
         with:
           version: "18.1.8"
 
-      - name: Export LIBCLANG_PATH (macOS)
-        if: ${{ matrix.kind == 'macos' }}
-        shell: bash
-        run: |
-          llvm_bin="$(dirname "$(command -v llvm-config)")"
-          llvm_root="$(cd "${llvm_bin}/.." && pwd)"
-          echo "LIBCLANG_PATH=${llvm_root}/lib" >> "${GITHUB_ENV}"
-
       - name: Configure bindgen include paths for Windows Ruby headers
         if: ${{ matrix.kind == 'windows' }}
         shell: pwsh

docs/modernization-handoff.md

@@ -139,7 +139,7 @@ Delivered:
   - dual Rust DLL artifact-name staging support (`lda_ruby_rust.dll` and `liblda_ruby_rust.dll`)
 - CI jobs for packaged-gem fallback, rust-enabled checks, and manifest checks
 - CI precompiled gem build guardrail job (`precompiled-gem-build`) aligned to the full release-blocking precompiled matrix
-- macOS precompiled CI/release lanes now pin LLVM `18.1.8` (`install-llvm-action`) and derive `LIBCLANG_PATH` from `llvm-config` to avoid bindgen breakage from Homebrew LLVM drift
+- macOS precompiled CI/release lanes now pin Homebrew `llvm@18` (with fallback to `llvm`) and export `LIBCLANG_PATH` from the selected prefix to avoid bindgen breakage from Homebrew LLVM drift
 - release workflow matrix for precompiled gems:
   - `x86_64-linux`
   - `x86_64-linux-musl`

docs/porting-strategy.md

@@ -85,7 +85,7 @@ Completed in `codex/experiment-ruby3-modernization`:
 - RubyGems credential preflight helper added (`bin/verify-rubygems-api-key`) for CI-safe publish key validation.
 - Post-publish verification helper added (`bin/verify-release-publish`) to validate RubyGems + GitHub release artifacts by tag.
 - CI precompiled guardrail job added (`precompiled-gem-build`) for full release-blocking platform packaging checks (Linux, Linux musl, macOS Intel, macOS Apple Silicon, Windows).
-- macOS precompiled CI/release lanes now pin LLVM `18.1.8` (`install-llvm-action`) and derive `LIBCLANG_PATH` from `llvm-config` to avoid bindgen breakage from Homebrew LLVM drift.
+- macOS precompiled CI/release lanes now pin Homebrew `llvm@18` (with fallback to `llvm`) and export `LIBCLANG_PATH` from the selected prefix to avoid bindgen breakage from Homebrew LLVM drift.
 - Release workflow post-publish verification job added (`verify_published_artifacts`).
 - Release failure alert workflow added (`.github/workflows/release-failure-alert.yml`) to open issue alerts for failed tag-triggered `release.yml` runs and auto-close matching alerts when reruns succeed.
 - Maintainer release runbook added (`docs/release-runbook.md`) with publish and rollback/yank procedures.

docs/precompiled-platform-policy.md

@@ -56,7 +56,7 @@ Release automation requirements:
 Continuous integration guardrail:
 
 - `.github/workflows/ci.yml` runs `release-precompiled-artifacts` for the full release-blocking precompiled matrix (Linux, Linux musl, macOS Intel, macOS Apple Silicon, Windows) on every branch/PR.
-- macOS precompiled lanes pin LLVM `18.1.8` via `KyleMayes/install-llvm-action` and export `LIBCLANG_PATH` from `llvm-config` to keep bindgen stable across Homebrew formula updates.
+- macOS precompiled lanes pin Homebrew `llvm@18` (falling back to `llvm` if unavailable) and export `LIBCLANG_PATH` from the selected prefix to keep bindgen stable across Homebrew formula updates.
 - `.github/workflows/precompiled-candidate-evaluation.yml` is used for additional platform candidate checks.
 - `.github/workflows/release.yml` dry-run validates the full release-blocking matrix before publish.