ci.yml

name: CI

on:
  push:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read

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

jobs:
  policy-checks:
    name: policy-checks
    runs-on: ubuntu-24.04
    timeout-minutes: 20
    if: github.event_name == 'pull_request'

    steps:
      - name: Checkout
        uses: actions/checkout@v7
        with:
          fetch-depth: 0

      - name: Install policy dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y ruby-full doxygen

      - name: License + tests policy (changed headers)
        run: |
          ruby scripts/ci_policy_checks.rb

      - name: Doxygen warnings gate (changed files)
        run: |
          ruby scripts/ci_doxygen_changed.rb

      - name: Header docstring coverage gate (changed public declarations)
        env:
          HEADER_DOC_COVERAGE_MIN: "80"
        run: |
          ruby scripts/ci_header_doc_coverage.rb \
            --min "${HEADER_DOC_COVERAGE_MIN}"

  build-and-test:
    name: build-and-test (${{ matrix.os }}, ${{ matrix.compiler }}, ${{ matrix.build_type }})
    runs-on: ${{ matrix.os }}
    timeout-minutes: 45

    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-22.04, ubuntu-24.04]
        compiler: [gcc, clang]
        build_type: [Debug, Release]

    env:
      CCACHE_DIR: ${{ github.workspace }}/.ccache

    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Install base system dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            cmake ninja-build pkg-config ccache \
            libgmp-dev libmpfr-dev libgsl-dev \
            libx11-dev libpthread-stubs0-dev \
            libtclap-dev \
            libgtest-dev \
            ruby-full

      - name: Install GCC toolchain
        if: matrix.compiler == 'gcc'
        run: |
          sudo apt-get install -y g++

      - name: Install Clang toolchain and libc++
        if: matrix.compiler == 'clang'
        run: |
          sudo apt-get install -y clang libc++-dev libc++abi-dev
      - name: Configure compiler
        run: |
          if [ "${{ matrix.compiler }}" = "clang" ]; then
            echo "CC=clang" >> "$GITHUB_ENV"
            echo "CXX=clang++" >> "$GITHUB_ENV"
            # Use libc++ with Clang for better C++20 std::ranges support
            # Set flags in separate variable to avoid CMake issues
            echo "CXXFLAGS_STDLIB=-stdlib=libc++" >> "$GITHUB_ENV"
          else
            echo "CC=gcc" >> "$GITHUB_ENV"
            echo "CXX=g++" >> "$GITHUB_ENV"
            echo "CXXFLAGS_STDLIB=" >> "$GITHUB_ENV"
          fi

      - name: Cache ccache
        uses: actions/cache@v6
        with:
          path: ${{ env.CCACHE_DIR }}
          key: ${{ runner.os }}-${{ matrix.os }}-${{ matrix.compiler }}-${{ matrix.build_type }}-ccache-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-${{ matrix.os }}-${{ matrix.compiler }}-${{ matrix.build_type }}-ccache-
            ${{ runner.os }}-${{ matrix.os }}-${{ matrix.compiler }}-ccache-
            ${{ runner.os }}-${{ matrix.os }}-ccache-

      - name: Build and install GoogleTest
        run: |
          set -euo pipefail

          # For Clang with libc++, we MUST build GoogleTest from source
          # because the system GoogleTest is built with libstdc++ (ABI mismatch)
          if [ "${{ matrix.compiler }}" = "clang" ]; then
            echo "Building GoogleTest from source for Clang + libc++"
            GTEST_SRC=""
            if [ -d /usr/src/googletest ]; then
              GTEST_SRC=/usr/src/googletest
            elif [ -d /usr/src/gtest ]; then
              GTEST_SRC=/usr/src/gtest
            else
              echo "No googletest sources found"
              exit 1
            fi
            
            sudo rm -rf "$GTEST_SRC/build" 2>/dev/null || true
            # Use the configured C and C++ compilers to avoid mixing toolchains
            # Pass libc++ flags only to C++ compiler, not C
            sudo cmake -S "$GTEST_SRC" -B "$GTEST_SRC/build" -G Ninja \
              -DCMAKE_C_COMPILER="${CC}" \
              -DCMAKE_CXX_COMPILER="${CXX}" \
              -DCMAKE_CXX_FLAGS="${CXXFLAGS_STDLIB}" \
              -DCMAKE_EXE_LINKER_FLAGS="-lc++abi"
            sudo cmake --build "$GTEST_SRC/build"
            sudo cmake --install "$GTEST_SRC/build"
            exit 0
          fi

          # For GCC, use system GoogleTest if available
          if pkg-config --exists gtest gtest_main; then
            echo "gtest found via pkg-config"
            exit 0
          fi

          if [ -d /usr/src/googletest ]; then
            sudo cmake -S /usr/src/googletest -B /usr/src/googletest/build -G Ninja
            sudo cmake --build /usr/src/googletest/build
            sudo cmake --install /usr/src/googletest/build
            exit 0
          fi

          if [ -d /usr/src/gtest ]; then
            sudo cmake -S /usr/src/gtest -B /usr/src/gtest/build -G Ninja
            sudo cmake --build /usr/src/gtest/build
            sudo cmake --install /usr/src/gtest/build
            exit 0
          fi

          echo "No googletest sources found in /usr/src (expected /usr/src/googletest or /usr/src/gtest)"
          exit 1

      - name: Configure
        run: |
          rm -rf build
          # For Clang, add libc++abi to linker flags and stdlib to CXX flags
          EXTRA_LINKER_FLAGS=""
          EXTRA_CXX_FLAGS=""
          if [ "${{ matrix.compiler }}" = "clang" ]; then
            EXTRA_LINKER_FLAGS="-lc++abi"
            EXTRA_CXX_FLAGS="${CXXFLAGS_STDLIB}"
          fi
          cmake -S . -B build -G Ninja \
            -DCMAKE_C_COMPILER_LAUNCHER=ccache \
            -DCMAKE_CXX_COMPILER_LAUNCHER=ccache \
            -DCMAKE_BUILD_TYPE=${{ matrix.build_type }} \
            -DCMAKE_CXX_FLAGS="$EXTRA_CXX_FLAGS" \
            -DCMAKE_EXE_LINKER_FLAGS="$EXTRA_LINKER_FLAGS" \
            -DBUILD_EXAMPLES=OFF \
            -DBUILD_TESTS=ON

      - name: Build
        run: |
          cmake --build build --parallel

      - name: Test
        run: |
          mkdir -p build/test_artifacts/golden_svg
          export ALEPH_TEST_GOLDEN_DIR="$PWD/build/test_artifacts/golden_svg"
          ctest --test-dir build --output-on-failure --parallel 2 --timeout 600 \
            -E 'hash_statistical_test'

      - name: Upload test logs on failure
        if: failure()
        uses: actions/upload-artifact@v7
        with:
          name: ctest-logs-${{ matrix.os }}-${{ matrix.compiler }}-${{ matrix.build_type }}
          if-no-files-found: ignore
          path: |
            build/Testing/Temporary/LastTest.log
            build/CMakeCache.txt
            build/test_artifacts/golden_svg

  # Guard the C++ standard contract: the library baseline is C++20 (covered by
  # build-and-test above). This job additionally builds and tests the whole
  # library under C++23, so that C++23 consumers stay supported and the
  # std-alias paths of ah-cpp-compat.H (e.g. std::expected) are exercised.
  # ALEPH_SUPPORTED_CXX_STANDARDS is {20, 23}; C++17 is not supported because
  # the library uses concepts throughout.
  cxx23-build:
    name: cxx23-build (ubuntu-24.04, gcc, Release)
    runs-on: ubuntu-24.04
    timeout-minutes: 45
    env:
      CC: gcc
      CXX: g++
      CCACHE_DIR: ${{ github.workspace }}/.ccache

    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Install system dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            cmake ninja-build pkg-config ccache \
            g++ \
            libgmp-dev libmpfr-dev libgsl-dev \
            libx11-dev libpthread-stubs0-dev \
            libtclap-dev \
            libgtest-dev

      - name: Cache ccache
        uses: actions/cache@v6
        with:
          path: ${{ env.CCACHE_DIR }}
          key: ${{ runner.os }}-cxx23-ccache-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-cxx23-ccache-

      - name: Build and install GoogleTest
        run: |
          set -euo pipefail
          if pkg-config --exists gtest gtest_main; then
            echo "gtest found via pkg-config"; exit 0
          fi
          if [ -d /usr/src/googletest ]; then
            sudo cmake -S /usr/src/googletest -B /usr/src/googletest/build -G Ninja
            sudo cmake --build /usr/src/googletest/build
            sudo cmake --install /usr/src/googletest/build
            exit 0
          fi
          echo "No googletest sources found"; exit 1

      - name: Configure (C++23)
        run: |
          rm -rf build
          cmake -S . -B build -G Ninja \
            -DCMAKE_C_COMPILER_LAUNCHER=ccache \
            -DCMAKE_CXX_COMPILER_LAUNCHER=ccache \
            -DCMAKE_BUILD_TYPE=Release \
            -DALEPH_CXX_STANDARD=23 \
            -DBUILD_EXAMPLES=OFF \
            -DBUILD_TESTS=ON

      - name: Build
        run: cmake --build build --parallel

      - name: Test
        run: |
          mkdir -p build/test_artifacts/golden_svg
          export ALEPH_TEST_GOLDEN_DIR="$PWD/build/test_artifacts/golden_svg"
          ctest --test-dir build --output-on-failure --parallel 2 --timeout 600 \
            -E 'hash_statistical_test'

      - name: Upload test logs on failure
        if: failure()
        uses: actions/upload-artifact@v7
        with:
          name: ctest-logs-cxx23
          if-no-files-found: ignore
          path: |
            build/Testing/Temporary/LastTest.log
            build/CMakeCache.txt

  ranges-off:
    name: ranges-off (ubuntu-24.04, gcc, Release)
    runs-on: ubuntu-24.04
    timeout-minutes: 45
    env:
      CC: gcc
      CXX: g++
      CCACHE_DIR: ${{ github.workspace }}/.ccache

    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Install system dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            cmake ninja-build pkg-config ccache \
            g++ \
            libgmp-dev libmpfr-dev libgsl-dev \
            libx11-dev libpthread-stubs0-dev \
            libtclap-dev \
            libgtest-dev

      - name: Cache ccache
        uses: actions/cache@v6
        with:
          path: ${{ env.CCACHE_DIR }}
          key: ${{ runner.os }}-ranges-off-ccache-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-ranges-off-ccache-

      - name: Build and install GoogleTest
        run: |
          set -euo pipefail
          if pkg-config --exists gtest gtest_main; then
            echo "gtest found via pkg-config"; exit 0
          fi
          if [ -d /usr/src/googletest ]; then
            sudo cmake -S /usr/src/googletest -B /usr/src/googletest/build -G Ninja
            sudo cmake --build /usr/src/googletest/build
            sudo cmake --install /usr/src/googletest/build
            exit 0
          fi
          echo "No googletest sources found"; exit 1

      - name: Configure (ranges disabled)
        run: |
          rm -rf build
          cmake -S . -B build -G Ninja \
            -DCMAKE_C_COMPILER_LAUNCHER=ccache \
            -DCMAKE_CXX_COMPILER_LAUNCHER=ccache \
            -DCMAKE_BUILD_TYPE=Release \
            -DALEPH_DISABLE_RANGES=ON \
            -DBUILD_EXAMPLES=OFF \
            -DBUILD_TESTS=ON

      - name: Build
        run: cmake --build build --parallel

      - name: Test
        run: |
          mkdir -p build/test_artifacts/golden_svg
          export ALEPH_TEST_GOLDEN_DIR="$PWD/build/test_artifacts/golden_svg"
          ctest --test-dir build --output-on-failure --parallel 2 --timeout 600 \
            -E 'hash_statistical_test'

      - name: Upload test logs on failure
        if: failure()
        uses: actions/upload-artifact@v7
        with:
          name: ctest-logs-ranges-off
          if-no-files-found: ignore
          path: |
            build/Testing/Temporary/LastTest.log
            build/CMakeCache.txt

  fft-simd-validation:
    name: fft-simd-validation (ubuntu-24.04, gcc, Release)
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    env:
      CC: gcc
      CXX: g++
      CCACHE_DIR: ${{ github.workspace }}/.ccache

    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Install system dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            cmake ninja-build pkg-config ccache \
            g++ \
            libgmp-dev libmpfr-dev libgsl-dev \
            libx11-dev libpthread-stubs0-dev \
            libtclap-dev \
            libgtest-dev \
            ruby-full python3-numpy python3-sympy

      - name: Cache ccache
        uses: actions/cache@v6
        with:
          path: ${{ env.CCACHE_DIR }}
          key: ${{ runner.os }}-fft-simd-ccache-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-fft-simd-ccache-

      - name: Build and install GoogleTest
        run: |
          set -euo pipefail
          if pkg-config --exists gtest gtest_main; then
            echo "gtest found via pkg-config"
            exit 0
          fi
          if [ -d /usr/src/googletest ]; then
            sudo cmake -S /usr/src/googletest -B /usr/src/googletest/build -G Ninja
            sudo cmake --build /usr/src/googletest/build
            sudo cmake --install /usr/src/googletest/build
            exit 0
          fi
          if [ -d /usr/src/gtest ]; then
            sudo cmake -S /usr/src/gtest -B /usr/src/gtest/build -G Ninja
            sudo cmake --build /usr/src/gtest/build
            sudo cmake --install /usr/src/gtest/build
            exit 0
          fi
          echo "No googletest sources found in /usr/src (expected /usr/src/googletest or /usr/src/gtest)"
          exit 1

      - name: Configure
        run: |
          cmake -S . -B build -G Ninja \
            -DCMAKE_C_COMPILER_LAUNCHER=ccache \
            -DCMAKE_CXX_COMPILER_LAUNCHER=ccache \
            -DCMAKE_BUILD_TYPE=Release \
            -DBUILD_EXAMPLES=ON \
            -DBUILD_TESTS=ON

      - name: Build test and audit example targets
        run: |
          # Build fft_test (always tracked). Build fft_benchmark and
          # fft_reference_probe / polynomial audit helpers only if their targets
          # are actually present.
          TARGETS="fft_test"
          if [ -f build/build.ninja ]; then
            TARGET_LIST="$(ninja -C build -t targets all 2>/dev/null)"
          else
            TARGET_LIST="$(cmake --build build --target help 2>/dev/null || true)"
          fi
          for t in fft_benchmark fft_reference_probe polynomial_benchmark polynomial_reference_probe; do
            if printf '%s\n' "$TARGET_LIST" | grep -q "^${t}:"; then
              TARGETS="$TARGETS $t"
            fi
          done
          echo "Building targets: $TARGETS"
          cmake --build build --parallel --target $TARGETS

      - name: FFT tests (default SIMD policy)
        run: |
          ctest --test-dir build \
            -R '^(FFT|FFTPlan|FFTLargeN|FFTSTFT|FFTOverlapAdd|FFTND|FFTIIR|FFTDSPUtilities|FFTOverlapSave|FFTPartitionedConvolver)' \
            --output-on-failure --timeout 120

      - name: FFT tests (forced scalar)
        env:
          ALEPH_FFT_SIMD: scalar
        run: |
          ctest --test-dir build \
            -R '^(FFT|FFTPlan|FFTLargeN|FFTSTFT|FFTOverlapAdd|FFTND|FFTIIR|FFTDSPUtilities|FFTOverlapSave|FFTPartitionedConvolver)' \
            --output-on-failure --timeout 120

      - name: FFT tests (forced AVX2)
        env:
          ALEPH_FFT_SIMD: avx2
        run: |
          ctest --test-dir build \
            -R '^(FFT|FFTPlan|FFTLargeN|FFTSTFT|FFTOverlapAdd|FFTND|FFTIIR|FFTDSPUtilities|FFTOverlapSave|FFTPartitionedConvolver)' \
            --output-on-failure --timeout 120

      - name: Benchmark validate and reference cross-check
        run: |
          if [ -x build/Examples/fft_benchmark ]; then
            echo "--- Benchmark validate (scalar) ---"
            ALEPH_FFT_SIMD=scalar ./build/Examples/fft_benchmark --validate
            echo "--- Benchmark validate (AVX2) ---"
            ALEPH_FFT_SIMD=avx2 ./build/Examples/fft_benchmark --validate
          else
            echo "fft_benchmark not available, skipping benchmark validation"
          fi

          if [ -x build/Examples/fft_reference_probe ]; then
            echo "--- Reference cross-check ---"
            ruby scripts/fft_reference_check.rb --build-dir build
          else
            echo "fft_reference_probe not available, skipping reference cross-check"
          fi

          if [ -x build/Examples/polynomial_benchmark ]; then
            echo "--- Polynomial benchmark validate ---"
            ./build/Examples/polynomial_benchmark --validate
          else
            echo "polynomial_benchmark not available, skipping polynomial benchmark validate"
          fi

          if [ -x build/Examples/polynomial_reference_probe ]; then
            echo "--- Polynomial reference cross-check ---"
            ruby scripts/polynomial_reference_check.rb --build-dir build
          else
            echo "polynomial_reference_probe not available, skipping polynomial reference cross-check"
          fi

      - name: Collect benchmark artifacts
        if: always()
        run: |
          if [ ! -x build/Examples/fft_benchmark ]; then
            echo "fft_benchmark not available, skipping artifact collection"
            exit 0
          fi
          mkdir -p build/fft_artifacts
          ALEPH_FFT_SIMD=scalar ./build/Examples/fft_benchmark \
            --json --warmup 3 --samples 5 --batch-count 8 \
            > build/fft_artifacts/benchmark-scalar.json
          ALEPH_FFT_SIMD=avx2 ./build/Examples/fft_benchmark \
            --json --warmup 3 --samples 5 --batch-count 8 \
            > build/fft_artifacts/benchmark-avx2.json
          ALEPH_FFT_SIMD=auto ./build/Examples/fft_benchmark \
            --json --warmup 3 --samples 5 --batch-count 8 \
            > build/fft_artifacts/benchmark-auto.json

      - name: Collect polynomial audit artifacts
        if: always()
        run: |
          if [ ! -x build/Examples/polynomial_benchmark ]; then
            echo "polynomial_benchmark not available, skipping polynomial artifact collection"
            exit 0
          fi
          mkdir -p build/polynomial_artifacts
          ./build/Examples/polynomial_benchmark \
            --json --repetitions 512 --warmup 3 --samples 9 --sizes 64,256,1024 \
            > build/polynomial_artifacts/benchmark-release.json
          cp scripts/fixtures/polynomial_benchmark_release_baseline.json \
            build/polynomial_artifacts/benchmark-release-baseline.json
          if [ -x build/Examples/polynomial_reference_probe ]; then
            ./build/Examples/polynomial_reference_probe --json \
              > build/polynomial_artifacts/reference-probe.json
          fi

      - name: Upload FFT artifacts
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: fft-simd-benchmarks
          if-no-files-found: ignore
          path: build/fft_artifacts/

      - name: Upload polynomial audit artifacts
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: polynomial-audit-artifacts
          if-no-files-found: ignore
          path: build/polynomial_artifacts/

      - name: Upload test logs on failure
        if: failure()
        uses: actions/upload-artifact@v7
        with:
          name: ctest-logs-fft-simd
          if-no-files-found: ignore
          path: |
            build/Testing/Temporary/LastTest.log

  planarity-visual-golden:
    name: planarity-visual-golden (ubuntu-24.04, gcc, Release)
    runs-on: ubuntu-24.04
    timeout-minutes: 25
    env:
      CC: gcc
      CXX: g++

    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Install system dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            cmake ninja-build \
            ruby-full \
            g++ \
            libgmp-dev libmpfr-dev libgsl-dev \
            libx11-dev libpthread-stubs0-dev \
            libtclap-dev

      - name: Configure
        run: |
          rm -rf build-planarity-visual
          cmake -S . -B build-planarity-visual -G Ninja \
            -DCMAKE_BUILD_TYPE=Release \
            -DBUILD_EXAMPLES=ON \
            -DBUILD_TESTS=OFF

      - name: Build example
        run: |
          cmake --build build-planarity-visual --target planarity_test_example --parallel

      - name: Generate certificate exchange artifacts
        run: |
          PLANARITY_OUT_DIR="$PWD/build-planarity-visual/planarity_artifacts"
          export PLANARITY_OUT_DIR
          mkdir -p "${PLANARITY_OUT_DIR}"
          ./build-planarity-visual/Examples/planarity_test_example \
            > build-planarity-visual/planarity_example_stdout.txt
          test -f "${PLANARITY_OUT_DIR}/planarity_k33_certificate.graphml"
          test -f "${PLANARITY_OUT_DIR}/planarity_k33_certificate.gexf"

      - name: Visual golden diff
        run: |
          PLANARITY_OUT_DIR="$PWD/build-planarity-visual/planarity_artifacts"
          export PLANARITY_OUT_DIR
          mkdir -p build-planarity-visual/planarity_visual/renders
          ruby scripts/planarity_certificate_ci_visual_diff.rb \
            --input "${PLANARITY_OUT_DIR}/planarity_k33_certificate.graphml" \
            --profile portable.ruby-render-svg \
            --profile portable.ruby-render-pdf \
            --render-output-dir "$PWD/build-planarity-visual/planarity_visual/renders" \
            --report "$PWD/build-planarity-visual/planarity_visual/report.json" \
            --print-summary

      - name: Upload visual artifacts on failure
        if: failure()
        uses: actions/upload-artifact@v7
        with:
          name: planarity-visual-golden-failure
          if-no-files-found: ignore
          path: |
            build-planarity-visual/planarity_example_stdout.txt
            build-planarity-visual/planarity_visual/report.json
            build-planarity-visual/planarity_visual/renders

  coverage:
    name: coverage (ubuntu-24.04, gcc, Debug)
    runs-on: ubuntu-24.04
    timeout-minutes: 60
    env:
      CC: gcc
      CXX: g++
      CCACHE_DIR: ${{ github.workspace }}/.ccache

    steps:
      - name: Checkout
        uses: actions/checkout@v7
        with:
          fetch-depth: 0

      - name: Install system dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            cmake ninja-build pkg-config ccache gcovr ruby-full \
            g++ \
            libgmp-dev libmpfr-dev libgsl-dev \
            libx11-dev libpthread-stubs0-dev \
            libtclap-dev \
            libgtest-dev

      - name: Cache ccache
        uses: actions/cache@v6
        with:
          path: ${{ env.CCACHE_DIR }}
          key: ${{ runner.os }}-coverage-ccache-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-coverage-ccache-

      - name: Build and install GoogleTest
        run: |
          set -euo pipefail

          if pkg-config --exists gtest gtest_main; then
            echo "gtest found via pkg-config"
            exit 0
          fi

          if [ -d /usr/src/googletest ]; then
            sudo cmake -S /usr/src/googletest -B /usr/src/googletest/build -G Ninja
            sudo cmake --build /usr/src/googletest/build
            sudo cmake --install /usr/src/googletest/build
            exit 0
          fi

          if [ -d /usr/src/gtest ]; then
            sudo cmake -S /usr/src/gtest -B /usr/src/gtest/build -G Ninja
            sudo cmake --build /usr/src/gtest/build
            sudo cmake --install /usr/src/gtest/build
            exit 0
          fi

          echo "No googletest sources found in /usr/src (expected /usr/src/googletest or /usr/src/gtest)"
          exit 1

      - name: Configure
        run: |
          rm -rf build-coverage
          cmake -S . -B build-coverage -G Ninja \
            -DCMAKE_C_COMPILER_LAUNCHER=ccache \
            -DCMAKE_CXX_COMPILER_LAUNCHER=ccache \
            -DCMAKE_BUILD_TYPE=Debug \
            -DBUILD_EXAMPLES=OFF \
            -DBUILD_TESTS=ON \
            -DCMAKE_C_FLAGS="--coverage -O0 -g" \
            -DCMAKE_CXX_FLAGS="--coverage -O0 -g" \
            -DCMAKE_EXE_LINKER_FLAGS="--coverage" \
            -DCMAKE_SHARED_LINKER_FLAGS="--coverage"

      - name: Build
        run: |
          cmake --build build-coverage --parallel

      - name: Test
        run: |
          mkdir -p build-coverage/test_artifacts/golden_svg
          export ALEPH_TEST_GOLDEN_DIR="$PWD/build-coverage/test_artifacts/golden_svg"
          # Exclude this benchmark from coverage runs because instrumentation
          # changes timing characteristics and can make this test flaky.
          # Also exclude hash_statistical_test as it's computationally intensive.
          ctest --test-dir build-coverage --output-on-failure --parallel 2 --timeout 600 \
            -E 'ParallelTest\.BenchmarkMapSpeedup|hash_statistical_test'

      - name: Generate coverage reports
        run: |
          ROOT_DIR="$GITHUB_WORKSPACE"
          BUILD_DIR="$ROOT_DIR/build-coverage"
          GCOVR_ARGS=(
            --root "$ROOT_DIR"
            --object-directory "$BUILD_DIR"
            --gcov-exclude "(^|.*/)CMakeFiles/[0-9.]+/CompilerId(C|CXX)/.*"
            --gcov-exclude "(^|.*/)CompilerId(C|CXX)/.*"
            --gcov-ignore-errors source_not_found
            --gcov-ignore-errors no_working_dir_found
            --gcov-ignore-errors output_error
            --gcov-ignore-parse-errors all
            --exclude "(^|.*/)Tests/.*"
            --exclude "(^|.*/)Examples/.*"
            --exclude "(^|.*/)build-coverage/.*"
            --exclude "(^|.*/)cmake-build-.*/.*"
            --exclude "(^|.*/)build-.*/.*"
            --exclude "(^|.*/)CMakeFiles/[0-9.]+/CompilerId(C|CXX)/.*"
          )

          gcovr "${GCOVR_ARGS[@]}" \
            --xml-pretty --output build-coverage/coverage.xml

          gcovr "${GCOVR_ARGS[@]}" \
            --html-details --output build-coverage/coverage.html

          gcovr "${GCOVR_ARGS[@]}" \
            --sort uncovered-percent --print-summary > build-coverage/coverage.txt

          # Phase 27 — per-module coverage for the cellular-automata headers.
          # tpl_ca_*.H (templates/engines) reported separately from ca-*.H
          # (utilities: I/O, observers, exporters, checkpoint).
          gcovr "${GCOVR_ARGS[@]}" \
            --filter '(^|.*/)tpl_ca_.*\.H$' \
            --print-summary > build-coverage/coverage_ca_templates.txt || true
          gcovr "${GCOVR_ARGS[@]}" \
            --filter '(^|.*/)ca-.*\.(H|C)$' \
            --print-summary > build-coverage/coverage_ca_utils.txt || true

      - name: Upload coverage to Codecov
        # Tokenless upload works for public repos via GitHub OIDC. The Codecov
        # project + README badge become live after the first upload reaches
        # codecov.io (one-time maintainer onboarding via "Sign in with GitHub").
        uses: codecov/codecov-action@v7
        with:
          files: build-coverage/coverage.xml
          fail_ci_if_error: false
          flags: unittests
          token: ${{ secrets.CODECOV_TOKEN }}

      - name: Diff coverage gate (PR)
        if: github.event_name == 'pull_request'
        env:
          DIFF_COVERAGE_MIN: "20"
        run: |
          git fetch --no-tags --prune --depth=1 origin "${{ github.base_ref }}"
          ruby scripts/ci_diff_coverage.rb \
            --coverage-xml build-coverage/coverage.xml \
            --diff-range "origin/${{ github.base_ref }}...HEAD" \
            --min-line "${DIFF_COVERAGE_MIN}" \
            --summary-file "$GITHUB_STEP_SUMMARY"

      - name: Publish coverage summary
        run: |
          {
            echo "## Test Coverage"
            echo
            echo '```text'
            cat build-coverage/coverage.txt
            echo '```'
            echo
            echo "### Cellular-automata module (per-header)"
            echo
            echo '#### `tpl_ca_*.H` (templates / engines)'
            echo '```text'
            cat build-coverage/coverage_ca_templates.txt 2>/dev/null || echo "(no data)"
            echo '```'
            echo '#### `ca-*.H` (utilities: I/O, observers, exporters, checkpoint)'
            echo '```text'
            cat build-coverage/coverage_ca_utils.txt 2>/dev/null || echo "(no data)"
            echo '```'
          } >> "$GITHUB_STEP_SUMMARY"

      - name: Upload coverage artifacts
        uses: actions/upload-artifact@v7
        with:
          name: coverage-report
          path: |
            build-coverage/coverage.xml
            build-coverage/coverage.html
            build-coverage/coverage.txt
            build-coverage/coverage_ca_templates.txt
            build-coverage/coverage_ca_utils.txt

      - name: Upload test logs on failure
        if: failure()
        uses: actions/upload-artifact@v7
        with:
          name: ctest-logs-coverage
          if-no-files-found: ignore
          path: |
            build-coverage/Testing/Temporary/LastTest.log
            build-coverage/CMakeCache.txt
            build-coverage/test_artifacts/golden_svg

  sanitizers:
    name: sanitizers (ubuntu-24.04, gcc, Debug)
    runs-on: ubuntu-24.04
    timeout-minutes: 45
    env:
      CC: gcc
      CXX: g++
      CCACHE_DIR: ${{ github.workspace }}/.ccache

    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Install system dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            cmake ninja-build pkg-config ccache \
            g++ \
            libgmp-dev libmpfr-dev libgsl-dev \
            libx11-dev libpthread-stubs0-dev \
            libtclap-dev \
            libgtest-dev

      - name: Cache ccache
        uses: actions/cache@v6
        with:
          path: ${{ env.CCACHE_DIR }}
          key: ${{ runner.os }}-sanitizers-ccache-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-sanitizers-ccache-

      - name: Configure
        run: |
          rm -rf build-asan
          cmake -S . -B build-asan -G Ninja \
            -DCMAKE_C_COMPILER_LAUNCHER=ccache \
            -DCMAKE_CXX_COMPILER_LAUNCHER=ccache \
            -DCMAKE_BUILD_TYPE=Debug \
            -DBUILD_EXAMPLES=OFF \
            -DBUILD_TESTS=ON \
            -DALEPH_USE_SANITIZERS=ON

      - name: Build
        run: |
          cmake --build build-asan --parallel

      - name: Test
        env:
          ASAN_OPTIONS: detect_leaks=1
          ALEPH_TEST_GOLDEN_DIR: ${{ github.workspace }}/build-asan/test_artifacts/golden_svg
        run: |
          mkdir -p "$ALEPH_TEST_GOLDEN_DIR"
          ctest --test-dir build-asan --output-on-failure --parallel 2 --timeout 600 \
            -E 'hash_statistical_test'

      - name: Upload test logs on failure
        if: failure()
        uses: actions/upload-artifact@v7
        with:
          name: ctest-logs-sanitizers
          if-no-files-found: ignore
          path: |
            build-asan/Testing/Temporary/LastTest.log
            build-asan/CMakeCache.txt
            build-asan/test_artifacts/golden_svg

  memory-sanitizer:
    name: memory-sanitizer (ubuntu-24.04, clang, Debug)
    runs-on: ubuntu-24.04
    timeout-minutes: 20
    env:
      CC: clang
      CXX: clang++

    steps:
      - name: Checkout
        uses: actions/checkout@v7
        with:
          persist-credentials: false

      - name: Install system dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            cmake ninja-build pkg-config cppcheck \
            clang \
            libgmp-dev libmpfr-dev libgsl-dev \
            libx11-dev libpthread-stubs0-dev \
            libtclap-dev

      - name: Check Regular_Polygon member initialization
        run: |
          cppcheck \
            --enable=warning \
            --std=c++20 \
            --language=c++ \
            --error-exitcode=1 \
            --suppress=missingIncludeSystem \
            --inline-suppr \
            polygon.H

      - name: Configure targeted MemorySanitizer probe
        run: |
          cmake -S . -B build-msan -G Ninja \
            -DCMAKE_BUILD_TYPE=Debug \
            -DBUILD_EXAMPLES=OFF \
            -DBUILD_TESTS=ON \
            -DALEPH_BUILD_X11_VIEWER=OFF \
            -DALEPH_USE_MEMORY_SANITIZER=ON

      - name: Build targeted MemorySanitizer probe
        run: |
          cmake --build build-msan \
            --target regular_polygon_msan_probe \
            --parallel

      - name: Test default Regular_Polygon state
        run: |
          ctest --test-dir build-msan --output-on-failure \
            -R '^MemorySanitizer\.RegularPolygonDefaultState$'

      - name: Upload test logs on failure
        if: failure()
        uses: actions/upload-artifact@v7
        with:
          name: ctest-logs-memory-sanitizer
          if-no-files-found: ignore
          path: |
            build-msan/Testing/Temporary/LastTest.log
            build-msan/CMakeCache.txt

  tsan:
    # Phase 16 — sanitizer matrix expansion.
    # ThreadSanitizer focuses on data races in the CA Parallel_Engine and
    # thread_pool surfaces. Tests intentionally excluded (sanitizer:skip-tsan):
    #   - hash_statistical_test: long-running statistical sweep, not race-prone,
    #     would 10x the runtime under TSan.
    #   - tpl_ca_parallel_engine_test.*Stress*: by design oversubscribes the
    #     thread pool to stress scheduling. The benign races there are
    #     intentional (work-stealing relaxations) and produce noise rather
    #     than signal; see comments in tpl_ca_parallel_engine.H.
    # See docs/ci_sanitizer_policy.md for the full rationale.
    name: tsan (ubuntu-24.04, clang, Debug)
    runs-on: ubuntu-24.04
    timeout-minutes: 45
    env:
      CC: clang
      CXX: clang++
      CCACHE_DIR: ${{ github.workspace }}/.ccache

    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Install system dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            cmake ninja-build pkg-config ccache \
            clang \
            libgmp-dev libmpfr-dev libgsl-dev \
            libx11-dev libpthread-stubs0-dev \
            libtclap-dev \
            libgtest-dev

      - name: Cache ccache
        uses: actions/cache@v6
        with:
          path: ${{ env.CCACHE_DIR }}
          key: ${{ runner.os }}-tsan-ccache-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-tsan-ccache-

      - name: Configure
        run: |
          rm -rf build-tsan
          cmake -S . -B build-tsan -G Ninja \
            -DCMAKE_C_COMPILER_LAUNCHER=ccache \
            -DCMAKE_CXX_COMPILER_LAUNCHER=ccache \
            -DCMAKE_BUILD_TYPE=Debug \
            -DBUILD_EXAMPLES=OFF \
            -DBUILD_TESTS=ON \
            -DCMAKE_C_COMPILER=clang \
            -DCMAKE_CXX_COMPILER=clang++ \
            -DCMAKE_C_FLAGS="-fsanitize=thread -fno-omit-frame-pointer" \
            -DCMAKE_CXX_FLAGS="-fsanitize=thread -fno-omit-frame-pointer" \
            -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=thread" \
            -DCMAKE_SHARED_LINKER_FLAGS="-fsanitize=thread"

      - name: Build
        run: |
          cmake --build build-tsan --parallel

      - name: Test
        env:
          TSAN_OPTIONS: halt_on_error=1
          ALEPH_TEST_GOLDEN_DIR: ${{ github.workspace }}/build-tsan/test_artifacts/golden_svg
        run: |
          mkdir -p "$ALEPH_TEST_GOLDEN_DIR"
          # See sanitizer:skip-tsan comments above for the rationale of each
          # exclusion. Keep this list in sync with docs/ci_sanitizer_policy.md.
          ctest --test-dir build-tsan --output-on-failure --parallel 2 --timeout 600 \
            -E 'hash_statistical_test|tpl_ca_parallel_engine_test.*Stress'

      - name: Upload test logs on failure
        if: failure()
        uses: actions/upload-artifact@v7
        with:
          name: ctest-logs-tsan
          if-no-files-found: ignore
          path: |
            build-tsan/Testing/Temporary/LastTest.log
            build-tsan/CMakeCache.txt
            build-tsan/test_artifacts/golden_svg

  ubsan:
    # Phase 16 — UndefinedBehaviorSanitizer split from the combined
    # ASan+UBSan build so signals are not masked by ASan reports.
    # Excluded tests are documented in docs/ci_sanitizer_policy.md.
    name: ubsan (ubuntu-24.04, clang, Debug)
    runs-on: ubuntu-24.04
    timeout-minutes: 45
    env:
      CC: clang
      CXX: clang++
      CCACHE_DIR: ${{ github.workspace }}/.ccache

    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Install system dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            cmake ninja-build pkg-config ccache \
            clang \
            libgmp-dev libmpfr-dev libgsl-dev \
            libx11-dev libpthread-stubs0-dev \
            libtclap-dev \
            libgtest-dev

      - name: Cache ccache
        uses: actions/cache@v6
        with:
          path: ${{ env.CCACHE_DIR }}
          key: ${{ runner.os }}-ubsan-ccache-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-ubsan-ccache-

      - name: Configure
        run: |
          rm -rf build-ubsan
          # We pin every UBSan check including the noisy ones (vptr requires
          # RTTI; nullability is whole-program). halt_on_error is set in the
          # environment so any signal turns the job red.
          cmake -S . -B build-ubsan -G Ninja \
            -DCMAKE_C_COMPILER_LAUNCHER=ccache \
            -DCMAKE_CXX_COMPILER_LAUNCHER=ccache \
            -DCMAKE_BUILD_TYPE=Debug \
            -DBUILD_EXAMPLES=OFF \
            -DBUILD_TESTS=ON \
            -DCMAKE_C_COMPILER=clang \
            -DCMAKE_CXX_COMPILER=clang++ \
            -DCMAKE_C_FLAGS="-fsanitize=undefined -fno-sanitize-recover=undefined -fno-omit-frame-pointer" \
            -DCMAKE_CXX_FLAGS="-fsanitize=undefined -fno-sanitize-recover=undefined -fno-omit-frame-pointer" \
            -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=undefined" \
            -DCMAKE_SHARED_LINKER_FLAGS="-fsanitize=undefined"

      - name: Build
        run: |
          cmake --build build-ubsan --parallel

      - name: Test
        env:
          UBSAN_OPTIONS: halt_on_error=1:print_stacktrace=1
          ALEPH_TEST_GOLDEN_DIR: ${{ github.workspace }}/build-ubsan/test_artifacts/golden_svg
        run: |
          mkdir -p "$ALEPH_TEST_GOLDEN_DIR"
          # sanitizer:skip-ubsan
          # - hash_statistical_test: runtime cost, not a UB target.
          ctest --test-dir build-ubsan --output-on-failure --parallel 2 --timeout 600 \
            -E 'hash_statistical_test'

      - name: Upload test logs on failure
        if: failure()
        uses: actions/upload-artifact@v7
        with:
          name: ctest-logs-ubsan
          if-no-files-found: ignore
          path: |
            build-ubsan/Testing/Temporary/LastTest.log
            build-ubsan/CMakeCache.txt
            build-ubsan/test_artifacts/golden_svg

  check-examples:
    name: check-examples (ubuntu-24.04, ${{ matrix.compiler }}, Release)
    runs-on: ubuntu-24.04
    timeout-minutes: 60
    strategy:
      fail-fast: false
      matrix:
        compiler: [gcc, clang]

    env:
      CCACHE_DIR: ${{ github.workspace }}/.ccache

    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Install system dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            cmake ninja-build pkg-config ccache \
            libgmp-dev libmpfr-dev libgsl-dev \
            libx11-dev libpthread-stubs0-dev \
            libtclap-dev \
            ruby-full

      - name: Install GCC toolchain
        if: matrix.compiler == 'gcc'
        run: sudo apt-get install -y g++

      - name: Install Clang toolchain
        if: matrix.compiler == 'clang'
        run: sudo apt-get install -y clang libc++-dev libc++abi-dev

      - name: Configure compiler
        run: |
          if [ "${{ matrix.compiler }}" = "clang" ]; then
            echo "CC=clang" >> "$GITHUB_ENV"
            echo "CXX=clang++" >> "$GITHUB_ENV"
            echo "CXXFLAGS_STDLIB=-stdlib=libc++" >> "$GITHUB_ENV"
            echo "LDFLAGS=-lc++abi" >> "$GITHUB_ENV"
          else
            echo "CC=gcc" >> "$GITHUB_ENV"
            echo "CXX=g++" >> "$GITHUB_ENV"
            echo "CXXFLAGS_STDLIB=" >> "$GITHUB_ENV"
            echo "LDFLAGS=" >> "$GITHUB_ENV"
          fi

      - name: Cache ccache
        uses: actions/cache@v6
        with:
          path: ${{ env.CCACHE_DIR }}
          key: ${{ runner.os }}-examples-${{ matrix.compiler }}-ccache-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-examples-${{ matrix.compiler }}-ccache-

      - name: Check examples compilation
        run: |
          ruby scripts/check_examples_compile --verbose --jobs "$(nproc)" \
            --build-dir "build-examples-${{ matrix.compiler }}"

      - name: TSAN smoke pass for concurrency examples
        run: |
          # Build a selected set of concurrency-heavy examples with TSAN
          ruby scripts/check_examples_compile --verbose --jobs "$(nproc)" --tsan \
            --build-dir "build-examples-${{ matrix.compiler }}-tsan"

      - name: Upload examples build log on failure
        if: failure()
        uses: actions/upload-artifact@v7
        with:
          name: examples-build-log-${{ matrix.compiler }}
          path: build-examples-${{ matrix.compiler }}/examples_build.log

      - name: Upload TSAN examples build log on failure
        if: failure()
        uses: actions/upload-artifact@v7
        with:
          name: examples-build-log-${{ matrix.compiler }}-tsan
          path: build-examples-${{ matrix.compiler }}-tsan/examples_build.log

  ci-success-push:
    name: CI Success
    runs-on: ubuntu-24.04
    needs:
      - build-and-test
      - fft-simd-validation
      - planarity-visual-golden
      - coverage
      - sanitizers
      - memory-sanitizer
      - tsan
      - ubsan
      - check-examples
    if: always() && github.event_name == 'push'
    steps:
      - name: Check results
        run: |
          set -euo pipefail
          echo "build-and-test result: ${{ needs.build-and-test.result }}"
          echo "fft-simd-validation result: ${{ needs.fft-simd-validation.result }}"
          echo "planarity-visual-golden result: ${{ needs.planarity-visual-golden.result }}"
          echo "coverage result: ${{ needs.coverage.result }}"
          echo "sanitizers result: ${{ needs.sanitizers.result }}"
          echo "memory-sanitizer result: ${{ needs.memory-sanitizer.result }}"
          echo "tsan result: ${{ needs.tsan.result }}"
          echo "ubsan result: ${{ needs.ubsan.result }}"
          echo "check-examples result: ${{ needs.check-examples.result }}"

          is_ok() {
            [ "$1" = "success" ] || [ "$1" = "skipped" ]
          }

          all_ok=1

          check_job() {
            job_name="$1"
            job_result="$2"

            if ! is_ok "$job_result"; then
              echo "Job '$job_name' did not succeed (result: $job_result)"
              all_ok=0
            fi
          }

          check_job "build-and-test" "${{ needs.build-and-test.result }}"
          check_job "fft-simd-validation" "${{ needs.fft-simd-validation.result }}"
          check_job "planarity-visual-golden" "${{ needs.planarity-visual-golden.result }}"
          check_job "coverage" "${{ needs.coverage.result }}"
          check_job "sanitizers" "${{ needs.sanitizers.result }}"
          check_job "memory-sanitizer" "${{ needs.memory-sanitizer.result }}"
          check_job "tsan" "${{ needs.tsan.result }}"
          check_job "ubsan" "${{ needs.ubsan.result }}"
          check_job "check-examples" "${{ needs.check-examples.result }}"

          if [ "$all_ok" -ne 1 ]; then
            echo "CI failed"
            exit 1
          fi
          echo "CI passed"

  ci-success-pr:
    name: CI Success
    runs-on: ubuntu-24.04
    needs:
      - policy-checks
      - build-and-test
      - fft-simd-validation
      - planarity-visual-golden
      - coverage
      - sanitizers
      - memory-sanitizer
      - tsan
      - ubsan
      - check-examples
    if: always() && github.event_name == 'pull_request'
    steps:
      - name: Check results
        run: |
          set -euo pipefail
          echo "policy-checks result: ${{ needs.policy-checks.result }}"
          echo "build-and-test result: ${{ needs.build-and-test.result }}"
          echo "fft-simd-validation result: ${{ needs.fft-simd-validation.result }}"
          echo "planarity-visual-golden result: ${{ needs.planarity-visual-golden.result }}"
          echo "coverage result: ${{ needs.coverage.result }}"
          echo "sanitizers result: ${{ needs.sanitizers.result }}"
          echo "memory-sanitizer result: ${{ needs.memory-sanitizer.result }}"
          echo "tsan result: ${{ needs.tsan.result }}"
          echo "ubsan result: ${{ needs.ubsan.result }}"
          echo "check-examples result: ${{ needs.check-examples.result }}"

          is_ok() {
            [ "$1" = "success" ] || [ "$1" = "skipped" ]
          }

          all_ok=1

          check_job() {
            job_name="$1"
            job_result="$2"

            if ! is_ok "$job_result"; then
              echo "Job '$job_name' did not succeed (result: $job_result)"
              all_ok=0
            fi
          }

          check_job "policy-checks" "${{ needs.policy-checks.result }}"
          check_job "build-and-test" "${{ needs.build-and-test.result }}"
          check_job "fft-simd-validation" "${{ needs.fft-simd-validation.result }}"
          check_job "planarity-visual-golden" "${{ needs.planarity-visual-golden.result }}"
          check_job "coverage" "${{ needs.coverage.result }}"
          check_job "sanitizers" "${{ needs.sanitizers.result }}"
          check_job "memory-sanitizer" "${{ needs.memory-sanitizer.result }}"
          check_job "tsan" "${{ needs.tsan.result }}"
          check_job "ubsan" "${{ needs.ubsan.result }}"
          check_job "check-examples" "${{ needs.check-examples.result }}"

          if [ "$all_ok" -ne 1 ]; then
            echo "CI failed"
            exit 1
          fi
          echo "CI passed"