Setting up MacOS CI + CI overhaul

.github/actions/_generate_llvm_html_coverage/action.yaml

@@ -0,0 +1,36 @@
+name: Generate LLVM HTML Coverage
+description: Builds the HTML coverage report for a coverage-enabled LLVM preset
+
+inputs:
+  build-preset:
+    description: CMake build preset used to generate HTML coverage artifacts
+    required: true
+  test-preset:
+    description: CTest preset whose recorded coverage data should be reported
+    required: true
+
+outputs:
+  html-cov-dir:
+    description: Directory containing the generated HTML coverage report
+    value: ${{ steps.htmlcov.outputs.html_cov_dir }}
+
+runs:
+  using: composite
+  steps:
+    - id: htmlcov
+      shell: bash
+      run: |
+        set +e
+        cmake --build --preset ${{ matrix.build_preset }} --target coverage-html 2>&1 | tee coverage_html_summary.txt
+        COV_EXIT_CODE=${PIPESTATUS[0]}  # Capture CMake exit code, not tee
+        set -e
+
+        HTML_COV_DIR=$(grep -Po "HTML coverage directory: \K.*" coverage_html_summary.txt)
+        # -P: Uses Perl-style regex.
+        # -o: Only outputs the matched part (not the whole line).
+        # \K: Tells the engine to match the string but ignore it in the final output.
+        # .*: Matches the rest of the line (the path)
+
+        echo "html_cov_dir=$HTML_COV_DIR" >> "$GITHUB_OUTPUT"
+
+        exit $COV_EXIT_CODE

.github/actions/_log_to_gh_summary_bash/action.yaml

@@ -0,0 +1,46 @@
+name: CMake Bash Step With Summary
+description: Runs a CMake command and logs output to GitHub Step Summary (Linux, MacOS)
+
+inputs:
+  step-name:
+    description: Display name (e.g. Build, Configure)
+    required: true
+  command:
+    description: The full cmake command to run
+    required: true
+  output-file:
+    description: Temporary text file to store command output
+    required: false
+    default: tmp_step_output.txt
+
+runs:
+  using: composite
+  steps:
+    - shell: bash
+      run: |
+        set +e
+        eval "${{ inputs.command }} 2>&1 | tee ${{ inputs.output-file }}"
+        EXIT_CODE=${PIPESTATUS[0]}
+        set -e
+
+        LOG_SIZE=$(wc -c < ${{ inputs.output-file }})
+
+        if [ $EXIT_CODE -eq 0 ]; then
+          echo "<details><summary>🟢 ${{ inputs.step-name }} Successful</summary>" >> $GITHUB_STEP_SUMMARY
+        else
+          echo "## 🔴 ${{ inputs.step-name }} Failed" >> $GITHUB_STEP_SUMMARY
+        fi
+
+        echo '' >> $GITHUB_STEP_SUMMARY
+        echo '```text' >> $GITHUB_STEP_SUMMARY
+
+        # Guard against 1MB GitHub Step Summary limit: only show the last 500 lines if it's huge
+        tail -n 500 ${{ inputs.output-file }} >> $GITHUB_STEP_SUMMARY
+
+        echo '```' >> $GITHUB_STEP_SUMMARY
+
+        if [ $EXIT_CODE -eq 0 ]; then
+          echo "</details>" >> $GITHUB_STEP_SUMMARY
+        fi
+
+        exit $EXIT_CODE

.github/actions/_log_to_gh_summary_pwsh/action.yaml

@@ -0,0 +1,43 @@
+name: CMake PowerShell Step With Summary
+description: Runs a command and logs output to GitHub Step Summary on Windows runners
+
+inputs:
+  step-name:
+    description: Display name (e.g. Build, Configure)
+    required: true
+  command:
+    description: The full command to run
+    required: true
+  output-file:
+    description: Temporary text file to store command output
+    required: false
+    default: tmp_step_output.txt
+
+runs:
+  using: composite
+  steps:
+    - shell: pwsh
+      run: |
+        $command = "${{ inputs.command }}"
+        $outputFile = "${{ inputs.output-file }}"
+
+        $global:LASTEXITCODE = 0
+        Invoke-Expression "$command 2>&1" | Tee-Object -FilePath $outputFile
+        $exitCode = if ($null -ne $LASTEXITCODE) { $LASTEXITCODE } else { 0 }
+
+        if ($exitCode -eq 0) {
+          Add-Content $env:GITHUB_STEP_SUMMARY "<details><summary>🟢 ${{ inputs.step-name }} Successful</summary>"
+        } else {
+          Add-Content $env:GITHUB_STEP_SUMMARY "## 🔴 ${{ inputs.step-name }} Failed"
+        }
+
+        Add-Content $env:GITHUB_STEP_SUMMARY ""
+        Add-Content $env:GITHUB_STEP_SUMMARY '```text'
+        Get-Content $outputFile -Tail 500 | Add-Content $env:GITHUB_STEP_SUMMARY
+        Add-Content $env:GITHUB_STEP_SUMMARY '```'
+
+        if ($exitCode -eq 0) {
+          Add-Content $env:GITHUB_STEP_SUMMARY "</details>"
+        }
+
+        exit $exitCode

.github/actions/_publish_llvm_coverage/action.yaml

@@ -0,0 +1,70 @@
+name: Publish LLVM Coverage
+description: Publishes the HTML coverage report and shields badges to GitHub Pages
+
+inputs:
+  build-preset:
+    description: CMake build preset used to generate coverage artifacts
+    required: true
+  test-preset:
+    description: CTest preset whose recorded coverage data should be reported
+    required: true
+  github-token:
+    description: GitHub token used to publish the generated site
+    required: true
+  publish-branch:
+    description: Git branch used by GitHub Pages
+    required: false
+    default: gh-pages
+  publish-dir:
+    description: Directory prepared locally before publication
+    required: false
+    default: out
+
+runs:
+  using: composite
+  steps:
+    - name: Generate html coverage report
+      id: htmlcov
+      uses: ./.github/actions/_generate_llvm_html_coverage
+      with:
+        build-preset: ${{ inputs.build-preset }}
+        test-preset: ${{ inputs.test-preset }}
+
+    - name: Generate shields.io badge
+      id: shieldsio
+      shell: bash
+      run: |
+        set +e
+        cmake --build --preset ${{ matrix.build_preset }} --target coverage-shieldsio 2>&1 | tee coverage_shieldsio_summary.txt
+        COV_EXIT_CODE=${PIPESTATUS[0]}  # Capture CMake exit code, not tee
+        set -e
+
+        SHIELDSIO_REGION_COV_BADGE_FILE=$(grep -Po "Shields.io Region Coverage badge written to: \K.*" coverage_shieldsio_summary.txt)
+        SHIELDSIO_FUNCTION_COV_BADGE_FILE=$(grep -Po "Shields.io Function Coverage badge written to: \K.*" coverage_shieldsio_summary.txt)
+        SHIELDSIO_LINE_COV_BADGE_FILE=$(grep -Po "Shields.io Line Coverage badge written to: \K.*" coverage_shieldsio_summary.txt)
+        SHIELDSIO_BRANCH_COV_BADGE_FILE=$(grep -Po "Shields.io Branch Coverage badge written to: \K.*" coverage_shieldsio_summary.txt)
+
+        echo "SHIELDSIO_REGION_COV_BADGE_FILE=$SHIELDSIO_REGION_COV_BADGE_FILE" >> "$GITHUB_OUTPUT"
+        echo "SHIELDSIO_FUNCTION_COV_BADGE_FILE=$SHIELDSIO_FUNCTION_COV_BADGE_FILE" >> "$GITHUB_OUTPUT"
+        echo "SHIELDSIO_LINE_COV_BADGE_FILE=$SHIELDSIO_LINE_COV_BADGE_FILE" >> "$GITHUB_OUTPUT"
+        echo "SHIELDSIO_BRANCH_COV_BADGE_FILE=$SHIELDSIO_BRANCH_COV_BADGE_FILE" >> "$GITHUB_OUTPUT"
+
+        exit $COV_EXIT_CODE
+
+    - name: Prepare files
+      shell: bash
+      run: |
+        mkdir -p "${{ inputs.publish-dir }}/coverage/badges"
+        cp -r "${{ steps.htmlcov.outputs.html-cov-dir }}" "${{ inputs.publish-dir }}/coverage/"
+        cp "${{ steps.shieldsio.outputs.SHIELDSIO_REGION_COV_BADGE_FILE }}" "${{ inputs.publish-dir }}/coverage/badges"
+        cp "${{ steps.shieldsio.outputs.SHIELDSIO_FUNCTION_COV_BADGE_FILE }}" "${{ inputs.publish-dir }}/coverage/badges"
+        cp "${{ steps.shieldsio.outputs.SHIELDSIO_LINE_COV_BADGE_FILE }}" "${{ inputs.publish-dir }}/coverage/badges"
+        cp "${{ steps.shieldsio.outputs.SHIELDSIO_BRANCH_COV_BADGE_FILE }}" "${{ inputs.publish-dir }}/coverage/badges"
+
+    - name: Publish coverage badge and report to gh-pages
+      uses: peaceiris/actions-gh-pages@v4
+      with:
+        github_token: ${{ inputs.github-token }}
+        publish_branch: ${{ inputs.publish-branch }}
+        publish_dir: ${{ inputs.publish-dir }}
+        keep_files: true

.github/actions/_setup_configure_build_linux/action.yaml

@@ -0,0 +1,115 @@
+name: Setup, Configure, and Build Linux CI
+description: Configures the Linux CI environment, restores caches, and runs CMake configure/build
+
+inputs:
+  arch:
+    description: Architecture label used in cache keys
+    required: true
+  configure-preset:
+    description: CMake configure preset to use
+    required: true
+  build-preset:
+    description: CMake build preset to use
+    required: true
+  build-target:
+    description: Optional CMake build target
+    required: false
+    default: ""
+  build-step-name:
+    description: Display label used in the GitHub summary for the build step
+    required: false
+    default: Build
+
+runs:
+  using: composite
+  steps:
+    - name: Setup VCPKG environment
+      shell: bash
+      run: |
+        set -euo pipefail
+
+        if [[ -z "${VCPKG_INSTALLATION_ROOT:-}" ]]; then
+          echo "::error::No pre-installed vcpkg root was found on this runner."
+          exit 1
+        fi
+
+        mkdir -p \
+          "$GITHUB_WORKSPACE/.cache/vcpkg/downloads" \
+          "$GITHUB_WORKSPACE/.cache/vcpkg/archives"
+
+        {
+          echo "VCPKG_ROOT=$VCPKG_INSTALLATION_ROOT"
+          echo "VCPKG_DOWNLOADS=$GITHUB_WORKSPACE/.cache/vcpkg/downloads"
+          echo "VCPKG_DEFAULT_BINARY_CACHE=$GITHUB_WORKSPACE/.cache/vcpkg/archives"
+        } >> "$GITHUB_ENV"
+
+    - name: Cache VCPKG assets
+      uses: actions/cache@v4
+      with:
+        path: |
+          .cache/vcpkg/downloads
+          .cache/vcpkg/archives
+        key: ${{ runner.os }}-${{ inputs.arch }}-vcpkg-${{ inputs.build-preset }}-${{ hashFiles('vcpkg.json') }}
+        restore-keys: ${{ runner.os }}-${{ inputs.arch }}-vcpkg-
+
+    - name: Cache build
+      uses: actions/cache@v4
+      with:
+        path: build/${{ inputs.build-preset }}
+        key: ${{ runner.os }}-${{ inputs.arch }}-cmake-${{ inputs.build-preset }}-${{ hashFiles('CMakeLists.txt', 'CMakePresets.json', 'vcpkg.json', '**/*.cmake', '.github/actions/_setup_configure_build_linux/action.yaml') }}
+
+    - name: Setup LLVM tool aliases
+      shell: bash
+      run: |
+        set -euo pipefail
+
+        # GitHub's Ubuntu runners sometimes expose versioned LLVM binaries
+        # (for example `llvm-cov-18`) without the unversioned names that our
+        # existing CMake lookup expects. Adding a lightweight workspace-local
+        # aliases here instead of reinstalling LLVM packages on every run.
+
+        TOOL_BIN_DIR="$GITHUB_WORKSPACE/.local/bin"
+        mkdir -p "$TOOL_BIN_DIR"
+
+        ensure_llvm_tool() {
+          local tool="$1"
+
+          if command -v "$tool" >/dev/null 2>&1; then
+            return 0
+          fi
+
+          for suffix in 20 19 18 17 16; do
+            if candidate=$(command -v "${tool}-${suffix}" 2>/dev/null); then
+              ln -sf "$candidate" "$TOOL_BIN_DIR/$tool"
+              return 0
+            fi
+          done
+
+          echo "::warning::Could not find $tool or a versioned variant in PATH."
+          return 0
+        }
+
+        ensure_llvm_tool llvm-cov
+        ensure_llvm_tool llvm-profdata
+
+        echo "$TOOL_BIN_DIR" >> "$GITHUB_PATH"
+
+    - name: Configure (${{ inputs.configure-preset }})
+      uses: ./.github/actions/_log_to_gh_summary_bash
+      with:
+        step-name: Configure (${{ inputs.configure-preset }})
+        command: "cmake --preset ${{ inputs.configure-preset }}"
+
+    - name: Build (${{ inputs.build-preset }})
+      if: ${{ inputs.build-target == '' }}
+      uses: ./.github/actions/_log_to_gh_summary_bash
+      with:
+        step-name: ${{ inputs.build-step-name }} (${{ inputs.build-preset }})
+        command: "cmake --build --preset ${{ inputs.build-preset }}"
+
+    - name: Build target (${{ inputs.build-target }})
+      if: ${{ inputs.build-target != '' }}
+      uses: ./.github/actions/_log_to_gh_summary_bash
+      with:
+        step-name: ${{ inputs.build-step-name }} (${{ inputs.build-preset }})
+        command: "cmake --build --preset ${{ inputs.build-preset }} --target ${{ inputs.build-target }}"

.github/actions/_setup_configure_build_macos/action.yaml

@@ -0,0 +1,79 @@
+name: Setup, Configure, and Build macOS CI
+description: Configures the macOS CI environment, restores caches, and runs CMake configure/build
+
+inputs:
+  arch:
+    description: Architecture label used in cache keys
+    required: true
+  configure-preset:
+    description: CMake configure preset to use
+    required: true
+  build-preset:
+    description: CMake build preset to use
+    required: true
+  build-target:
+    description: Optional CMake build target
+    required: false
+    default: ""
+  build-step-name:
+    description: Display label used in the GitHub summary for the build step
+    required: false
+    default: Build
+
+runs:
+  using: composite
+  steps:
+    - name: Setup VCPKG environment
+      shell: bash
+      run: |
+        set -euo pipefail
+
+        if [[ -z "${VCPKG_INSTALLATION_ROOT:-}" ]]; then
+          echo "::error::No pre-installed vcpkg root was found on this runner."
+          exit 1
+        fi
+
+        mkdir -p \
+          "$GITHUB_WORKSPACE/.cache/vcpkg/downloads" \
+          "$GITHUB_WORKSPACE/.cache/vcpkg/archives"
+
+        {
+          echo "VCPKG_ROOT=$VCPKG_INSTALLATION_ROOT"
+          echo "VCPKG_DOWNLOADS=$GITHUB_WORKSPACE/.cache/vcpkg/downloads"
+          echo "VCPKG_DEFAULT_BINARY_CACHE=$GITHUB_WORKSPACE/.cache/vcpkg/archives"
+        } >> "$GITHUB_ENV"
+
+    - name: Cache VCPKG assets
+      uses: actions/cache@v4
+      with:
+        path: |
+          .cache/vcpkg/downloads
+          .cache/vcpkg/archives
+        key: ${{ runner.os }}-${{ inputs.arch }}-vcpkg-${{ inputs.build-preset }}-${{ hashFiles('vcpkg.json') }}
+        restore-keys: ${{ runner.os }}-${{ inputs.arch }}-vcpkg-
+
+    - name: Cache build
+      uses: actions/cache@v4
+      with:
+        path: build/${{ inputs.build-preset }}
+        key: ${{ runner.os }}-${{ inputs.arch }}-cmake-${{ inputs.build-preset }}-${{ hashFiles('CMakeLists.txt', 'CMakePresets.json', 'vcpkg.json', '**/*.cmake', '.github/actions/_setup_configure_build_macos/action.yaml') }}
+
+    - name: Configure (${{ inputs.configure-preset }})
+      uses: ./.github/actions/_log_to_gh_summary_bash
+      with:
+        step-name: Configure (${{ inputs.configure-preset }})
+        command: "cmake --preset ${{ inputs.configure-preset }}"
+
+    - name: Build (${{ inputs.build-preset }})
+      if: ${{ inputs.build-target == '' }}
+      uses: ./.github/actions/_log_to_gh_summary_bash
+      with:
+        step-name: ${{ inputs.build-step-name }} (${{ inputs.build-preset }})
+        command: "cmake --build --preset ${{ inputs.build-preset }}"
+
+    - name: Build target (${{ inputs.build-target }})
+      if: ${{ inputs.build-target != '' }}
+      uses: ./.github/actions/_log_to_gh_summary_bash
+      with:
+        step-name: ${{ inputs.build-step-name }} (${{ inputs.build-preset }})
+        command: "cmake --build --preset ${{ inputs.build-preset }} --target ${{ inputs.build-target }}"