build.yml

on:
  push:
    branches:
      - main
  pull_request:
    types: [opened, synchronize, reopened]

name: Build

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

env:
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
  BUILD_TYPE: Release
  BUILD_WRAPPER_OUT_DIR: build_wrapper_output_directory # Directory where build-wrapper output will be placed

jobs:
  # Build the engine + Catch2 unit tests with CMake/Ninja + Clang/libc++ and run
  # them through ctest on both macOS (Homebrew LLVM) and Ubuntu (apt.llvm.org
  # Clang + libc++) — the multi-platform proof. The macOS leg also produces the
  # SonarCloud coverage report from Clang source-based coverage.
  build-and-test:
    name: Build & Test (${{ matrix.os }})
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [macos-26, ubuntu-latest]

    steps:
    - name: Checkout repository
      uses: actions/checkout@v5
      with:
        submodules: recursive

    - name: Set up Homebrew
      if: runner.os == 'macOS'
      uses: Homebrew/actions/setup-homebrew@main

    - name: Install dependencies (macOS)
      if: runner.os == 'macOS'
      run: bash ./.github/workflows/scripts/brew.sh

    - name: Install dependencies (Ubuntu)
      if: runner.os == 'Linux'
      run: bash ./.github/workflows/scripts/ubuntu_deps.sh

    # Pin CMake (and a matching Ninja) to 4.3.3 so CI matches local dev and
    # lands in the [4.3, 4.4) CMAKE_EXPERIMENTAL_CXX_IMPORT_STD UUID branch in
    # CMakeLists.txt. The runner's default CMake (3.31.x) has no pinned UUID and
    # fails configuration. Runs before build_dep.sh since that also calls cmake.
    - name: Setup CMake & Ninja
      uses: lukka/get-cmake@v4.3.3

    - name: Build C++ Libraries
      run: bash ./scripts/build_dep.sh

    # scripts/build.sh selects the toolchain per platform (Homebrew LLVM on
    # macOS, clang/clang++ on Linux), configures with Ninja, and builds the
    # library, executable, and unit_tests. ENABLE_COVERAGE instruments the
    # macOS build for the coverage report below.
    - name: Configure & build
      run: ENABLE_COVERAGE=${{ runner.os == 'macOS' && 'ON' || 'OFF' }} bash ./scripts/build.sh

    - name: Run tests
      run: ctest --test-dir build --output-on-failure

    - name: Generate coverage report
      if: runner.os == 'macOS'
      run: >
          bash ./.github/workflows/scripts/llvmcov-to-sonarqube-generic.sh build
          > sonarqube-generic-coverage.xml

    - name: Upload coverage report
      if: runner.os == 'macOS'
      uses: actions/upload-artifact@v7
      with:
        name: sonarqube-coverage
        path: sonarqube-generic-coverage.xml
        retention-days: 1

  sonar-scan:
    name: SonarCloud Scan
    needs: build-and-test
    runs-on: ubuntu-latest

    steps:
      # fetch-depth: 0 gives Sonar full git history for blame-based new-code analysis.
      - name: Checkout repository
        uses: actions/checkout@v5
        with:
          fetch-depth: 0
          submodules: recursive

      # Same Clang + libc++ + Boost toolchain as the Ubuntu test leg, so the
      # build-wrapper captures a build identical to the one that is tested.
      - name: Install dependencies
        run: bash ./.github/workflows/scripts/ubuntu_deps.sh

      # Match local dev / the [4.3, 4.4) import-std UUID branch in CMakeLists.txt;
      # the runner's default CMake (3.31.x) has no pinned UUID. See the build job.
      - name: Setup CMake & Ninja
        uses: lukka/get-cmake@v4.3.3

      - name: Build C++ Libraries
        run: bash ./scripts/build_dep.sh

      # SonarQube Server and Cloud is a widely used static analysis solution for
      # continuous code quality and security inspection, and the official
      # entrypoint for scanning C++ projects via GitHub actions.
      # https://github.com/SonarSource/sonarqube-scan-action
      - name: Install Build Wrapper
        uses: SonarSource/sonarqube-scan-action/install-build-wrapper@v4.2.1

      # Lands at ./artifact/sonarqube-generic-coverage.xml so the existing
      # sonar.coverageReportPaths argument keeps working unchanged.
      - name: Download coverage artifact from build job
        uses: actions/download-artifact@v5
        with:
          name: sonarqube-coverage
          path: artifact

      # Build through scripts/build.sh under the build-wrapper so the analyzed
      # build uses the exact same toolchain as the tested build (apt.llvm.org
      # Clang + libc++ + OpenMP). A bare `cmake -DCMAKE_CXX_COMPILER=clang++`
      # picked up the runner's system Clang 18 — which has no libc++ `std` module
      # and no matching libomp, so find_package(OpenMP REQUIRED) failed. The
      # build-wrapper intercepts the Ninja compile commands for the scan; deps
      # were already built above so build.sh skips them and only our TUs are
      # captured.
      - name: Build under build-wrapper
        run: >
          build-wrapper-linux-x86-64 --out-dir ${{ env.BUILD_WRAPPER_OUT_DIR }}
          bash ./scripts/build.sh

      # Performs the SonarQube scan using the captured build commands and the
      # downloaded coverage report. Requires GitHub and SonarQube tokens.
      # sonar.cfamily.enableModules turns on the analyzer's (experimental) C++20
      # named-modules support; this project is module-heavy (`import std;` plus
      # .cppm interface units), so without it the analyzer can't parse those TUs.
      # NB: keep these as --define args, not a `#` comment inside the folded
      # `args: >` block — a `#` there would be passed to the scanner literally.
      - name: SonarQube Scan
        uses: SonarSource/sonarqube-scan-action@v4.2.1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN  }}
        with:
          args: >
            --define sonar.cfamily.compile-commands="${{ env.BUILD_WRAPPER_OUT_DIR }}/compile_commands.json"
            --define sonar.cfamily.enableModules=true
            --define sonar.coverageReportPaths=artifact/sonarqube-generic-coverage.xml