ci.yml

# =========================================================================
#   Ceedling - Test-Centered Build System for C
#   ThrowTheSwitch.org
#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
#   SPDX-License-Identifier: MIT
# =========================================================================

# -----------------------------------------------------------------------
# Continuous Integration Workflow
#
# Purpose:
#   Run the full test suite and verify a clean gem build on every push.
#   No releases are created here — publishing is handled by prerelease.yml
#   and release.yml, which trigger only on intentional Git tags.
#
# Triggers:
#   - Push to any branch
#   - Pull request targeting master
#   - Manual dispatch (workflow_dispatch)
#
# Skip-CI:
#   Add any of the following to your commit message to skip this workflow:
#     [skip ci]  [ci skip]  [no ci]  [skip actions]  [actions skip]
#   Note: skip keywords have no effect on workflow_dispatch runs.
#
# Branch exclusions:
#   To permanently exclude a branch pattern from CI, add a branches-ignore
#   list under the push: trigger below (e.g. docs/**, wip/**).
# -----------------------------------------------------------------------

---
name: CI

# Triggers the workflow on push to any branch (tag pushes excluded — handled by
# prerelease.yml and release.yml), pull requests targeting master, or manual dispatch
on:
  push:
    branches:
      - '**'             # All branches; branches: ['**'] scopes push to refs/heads/ only,
                         # excluding refs/tags/ pushes — see Skip-CI above
  pull_request:
    branches: [master]
  workflow_dispatch:


# Cancel any in-progress run on the same ref when a new push arrives,
# preventing stale run pile-up on active branches
concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true


permissions:
  contents: read


jobs:
  # Job: Build MkDocs HTML documentation bundle for gem inclusion
  generate-docs:
    name: "Generate Local Docs Bundle for Gem Inclusion"
    uses: ./.github/workflows/_generate-docs.yml


  # Job: Linux test suite
  tests-linux:
    name: "Linux Test Suite"
    needs: generate-docs
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        ruby: ['3.0', '3.1', '3.2', '3.3', '3.4', '3.5']
    steps:
      # Checks out repository under $GITHUB_WORKSPACE — must come first to enable local action access
      - name: Checkout Latest Repo
        uses: actions/checkout@v4
        with:
          submodules: recursive

      # Common set up steps
      - name: Set Up Ruby Test Environment
        uses: ./.github/actions/setup
        with:
          ruby: ${{ matrix.ruby }}

      # Workaround: Fix Ruby toolcache Gem directory permissions (Bundler exit 38)
      # This is an environmental Ruby/toolcache issue, not a Bundler issue; the fix must
      # run after setup-ruby (which populates the toolcache) but before bundle install.
      # Issue: https://github.com/rubygems/rubygems/issues/7983
      - name: Apply Workaround for Ruby toolcache Gem Directory Permissions
        run: |
          sudo chmod -R go-w /opt/hostedtoolcache/Ruby/**/**/lib/ruby/gems/**/gems || true

      # Install Gem Dependencies
      - name: Install Gem Dependencies
        # Ensure local installation to prevent system directory permission problems
        run: |
          bundle install

      # Run unit tests immediately after gem install — before the slower external tool
      # installation steps — so unit failures surface as quickly as possible.
      # Unit tests have no dependency on gdb, valgrind, cppcheck, gcovr, or ReportGenerator.
      - name: Run Unit Tests
        env:
          CI_RSPEC_PROGRESS_FORMAT: true
        run: rake specs:units

      # Install gdb for backtrace feature testing
      - name: Install gdb for Backtrace Feature Testing
        run: |
          sudo apt-get update -qq
          sudo apt-get install --assume-yes --quiet gdb

      # Install valgrind for Valgrind plugin testing
      - name: Install valgrind for Valgrind Feature Testing
        run: |
          sudo apt-get update -qq
          sudo apt-get install --assume-yes --quiet valgrind

      # Build cppcheck from source at a pinned version so all plugin options
      # (including SARIF, which requires 2.16+) are available for testing.
      # The installed binary is cached by version to avoid rebuilding on every run.
      - name: Cache cppcheck binary and data files
        id: cache-cppcheck
        uses: actions/cache@v4
        with:
          path: |
            /usr/local/bin/cppcheck
            /usr/local/share/cppcheck
          key: cppcheck-${{ env.CPPCHECK_VERSION }}-linux
        env:
          CPPCHECK_VERSION: '2.16.0'

      - name: "Build and Install cppcheck for Tests of Ceedling Plugin: Cppcheck"
        if: steps.cache-cppcheck.outputs.cache-hit != 'true'
        env:
          CPPCHECK_VERSION: '2.16.0'
        run: |
          sudo apt-get install --assume-yes --quiet cmake
          wget -q https://github.com/danmar/cppcheck/archive/refs/tags/${CPPCHECK_VERSION}.tar.gz -O cppcheck.tar.gz
          tar xzf cppcheck.tar.gz
          cmake -S cppcheck-${CPPCHECK_VERSION} -B cppcheck-build -DCMAKE_BUILD_TYPE=Release -DUSE_MATCHCOMPILER=ON -DFILESDIR=/usr/local/share/cppcheck
          cmake --build cppcheck-build --parallel $(nproc)
          sudo cmake --install cppcheck-build

      # --break-system-packages is required on Ubuntu 24.04+
      # (PEP 668 prevents pip from installing to the system Python environment without explicit opt-in)
      - name: "Install GCovr for Tests of Ceedling Plugin: Gcov"
        run: |
          pip install --break-system-packages gcovr

      # Install ReportGenerator for Gcov plugin
      # Fix PATH before tool installation
      # https://stackoverflow.com/questions/59010890/github-action-how-to-restart-the-session
      - name: "Install ReportGenerator for Tests of Ceedling Plugin: Gcov"
        run: |
          mkdir --parents $HOME/.dotnet/tools
          echo "$HOME/.dotnet/tools" >> $GITHUB_PATH
          dotnet tool install --global dotnet-reportgenerator-globaltool

      # Run system tests via the run-system-tests action (CI batch debug mode: failures only preserved)
      - name: Run System Tests
        uses: ./.github/actions/run-system-tests
        with:
          ruby: ${{ matrix.ruby }}

      # Common plugin test steps
      - name: Run Plugin Tests
        uses: ./.github/actions/run-plugin-tests


  # Job: Windows test suite
  tests-windows:
    name: "Windows Test Suite"
    needs: generate-docs
    runs-on: windows-latest
    strategy:
      fail-fast: false
      matrix:
        # Ruby 3.5 not available on Windows runners [July 2026]
        ruby: ['3.0', '3.1', '3.2', '3.3', '3.4']
    steps:
      # Checks out repository under $GITHUB_WORKSPACE — must come first to enable local action access
      - name: Checkout Latest Repo
        uses: actions/checkout@v4
        with:
          submodules: recursive

      # Windows Defender real-time monitoring scans every file touched during gem installation
      # and C compilation, adding 5–15 minutes of overhead per run. Disable it for CI performance.
      - name: Disable Windows Defender real-time monitoring
        shell: powershell
        run: Set-MpPreference -DisableRealtimeMonitoring $true

      # Common set up steps
      - name: Set Up Ruby Test Environment
        uses: ./.github/actions/setup
        with:
          ruby: ${{ matrix.ruby }}

      # Install Gem Dependencies
      - name: Install Gem Dependencies
        # Ensure local installation to prevent system directory permission problems
        run: |
          bundle install

      # Run unit tests immediately after gem install — before the slower external tool
      # installation steps — so unit failures surface as quickly as possible.
      # Unit tests have no dependency on gcovr, ReportGenerator, or cppcheck.
      - name: Run Unit Tests
        env:
          CI_RSPEC_PROGRESS_FORMAT: true
        run: rake specs:units

      # Install GCovr for Gcov plugin test
      - name: "Install GCovr for Tests of Ceedling Plugin: Gcov"
        run: |
          pip install gcovr

      # Install ReportGenerator for Gcov plugin test
      - name: "Install ReportGenerator for Tests of Ceedling Plugin: Gcov"
        run: |
          dotnet tool install --global dotnet-reportgenerator-globaltool

      # Install cppcheck via Chocolatey (installs the MSI to C:\Program Files\Cppcheck\).
      # Add the real install directory to PATH ahead of the Chocolatey shim so that
      # cppcheck can locate its cfg/ directory (needed for std.cfg library lookups).
      - name: "Install cppcheck for Tests of Ceedling Plugin: Cppcheck"
        run: |
          choco upgrade cppcheck -y
          echo "C:\Program Files\Cppcheck" >> $env:GITHUB_PATH

      # Run system tests via the run-system-tests action (CI batch debug mode: failures only preserved)
      - name: Run System Tests
        uses: ./.github/actions/run-system-tests
        with:
          ruby: ${{ matrix.ruby }}

      # Common plugin test steps
      - name: Run Plugin Tests
        uses: ./.github/actions/run-plugin-tests


  # Job: macOS test suite
  # Targets Apple Clang (the gcc alias on macOS resolves to Xcode's LLVM-based Clang).
  # Homebrew GCC is effectively covered by the Linux job, so no compiler matrix is needed.
  # Ruby matrix starts at 3.1: macos-latest runs on Apple Silicon (ARM64), and ruby/setup-ruby
  # has no pre-built binary for Ruby 3.0 on ARM64.
  # Note for the future: Ruby 3.1 will itself be dropped starting with macOS 26.
  tests-macos:
    name: "macOS Test Suite"
    needs: generate-docs
    runs-on: macos-latest
    strategy:
      fail-fast: false
      matrix:
        ruby: ['3.1', '3.2', '3.3', '3.4', '3.5']
    steps:
      # Checks out repository under $GITHUB_WORKSPACE — must come first to enable local action access
      - name: Checkout Latest Repo
        uses: actions/checkout@v4
        with:
          submodules: recursive

      # Common set up steps
      - name: Set Up Ruby Test Environment
        uses: ./.github/actions/setup
        with:
          ruby: ${{ matrix.ruby }}

      # No toolcache permissions workaround — that step targets /opt/hostedtoolcache (Linux-specific path)

      # Install Gem Dependencies
      # force_ruby_platform bypasses Bundler's multi-platform gem resolution, which fails on
      # macOS ARM64 due to mixed versioned/generic platform strings in the lockfile.
      # All Ceedling gem dependencies are pure Ruby, so this has no functional effect.
      - name: Install Gem Dependencies
        run: |
          bundle config set --local force_ruby_platform true
          bundle install

      # Run unit tests immediately after gem install — before the slower external tool
      # installation steps — so unit failures surface as quickly as possible.
      # Unit tests have no dependency on cppcheck, gcovr, or ReportGenerator.
      - name: Run Unit Tests
        env:
          CI_RSPEC_PROGRESS_FORMAT: true
        run: rake specs:units

      # gdb is not installed on macOS runners — backtrace specs detect absence and skip
      # valgrind is unavailable on macOS — valgrind specs already skip via @valgrind_available guard

      # Install cppcheck via Homebrew
      - name: "Install cppcheck for Tests of Ceedling Plugin: Cppcheck"
        run: |
          brew install cppcheck

      # --break-system-packages required on macOS 14+ (PEP 668 prevents pip from installing
      # to the system Python environment without explicit opt-in, same as Ubuntu 24.04+)
      - name: "Install GCovr for Tests of Ceedling Plugin: Gcov"
        run: |
          pip install --break-system-packages gcovr

      # Install ReportGenerator for Gcov plugin
      # Fix PATH before tool installation
      # https://stackoverflow.com/questions/59010890/github-action-how-to-restart-the-session
      - name: "Install ReportGenerator for Tests of Ceedling Plugin: Gcov"
        run: |
          mkdir -p $HOME/.dotnet/tools
          echo "$HOME/.dotnet/tools" >> $GITHUB_PATH
          dotnet tool install --global dotnet-reportgenerator-globaltool

      # Run system tests via the run-system-tests action (CI batch debug mode: failures only preserved)
      - name: Run System Tests
        uses: ./.github/actions/run-system-tests
        with:
          ruby: ${{ matrix.ruby }}

      # Common plugin test steps
      - name: Run Plugin Tests
        uses: ./.github/actions/run-plugin-tests


  # Job: Preprocessing locale encoding regression test
  # Installs ja_JP.UTF-8 locale and runs the locale encoding spec under it.
  # This replicates issue #1160's root cause: GCC under a non-C locale outputs
  # localized preprocessor markers (e.g. <組み込み> for <built-in>) that Ceedling
  # must handle without raising encoding errors.
  # Note: No generate-docs dependency or docs download needed — system tests use
  # a path-based Bundler deployment (deploy_gem) that does not require a gem build.
  tests-linux-locale:
    name: "Linux Test Suite (ja_JP.UTF-8 Locale)"
    runs-on: ubuntu-latest
    steps:
      - uses: actions/cache@v4
        with:
          path: vendor/bundle
          key: bundle-use-ruby-${{ runner.os }}-3.3-${{ hashFiles('**/Gemfile.lock') }}
          restore-keys: |
            bundle-use-ruby-${{ runner.os }}-3.3-

      - name: Checkout Latest Repo
        uses: actions/checkout@v4
        with:
          submodules: recursive

      - name: Set Up Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.3'

      - name: Apply Workaround for Ruby toolcache Gem Directory Permissions
        run: |
          sudo chmod -R go-w /opt/hostedtoolcache/Ruby/**/**/lib/ruby/gems/**/gems || true

      - name: Install Gem Dependencies
        run: |
          bundle install

      - name: Install ja_JP.UTF-8 Locale
        run: |
          sudo locale-gen ja_JP.UTF-8
          sudo update-locale
          locale -a

      - name: Run Preprocessing Locale Spec under ja_JP.UTF-8
        env:
          LC_ALL: ja_JP.UTF-8
          LANG: ja_JP.UTF-8
          CI_RSPEC_PROGRESS_FORMAT: true
        run: |
          rake spec:system:debug:preprocessing_locale

      # Passing project directories are deleted immediately by done!; passing logs are never written.
      # This step is retained as a safety net in case of any leftover pass artifacts.
      - name: Remove passing system test artifacts before upload
        if: failure()
        shell: bash
        run: |
          rm -rf systests/proj/pass || true
          rm -f systests/systest.pass.*.log || true

      # Upload system test failure logs and temp project directories on test job failure
      - name: Upload system test failure artifacts
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: systest-failures-locale-ruby-3.3
          path: systests/
          if-no-files-found: ignore


  # Job: Default-encoding stress test against example projects
  # Forces Ruby's default external encoding to US-ASCII (via LC_ALL=C) and exports +
  # fully tests example projects with differing preprocessing configurations, catching
  # regressions in Ceedling's handling of non-ASCII source content under a non-UTF-8
  # platform default encoding.
  # Note: No generate-docs dependency needed — system tests use a path-based Bundler
  # deployment (deploy_gem) that does not require a gem build.
  tests-linux-encoding-stress:
    name: "Linux Encoding Stress Test (C/POSIX)"
    runs-on: ubuntu-latest
    steps:
      - uses: actions/cache@v4
        with:
          path: vendor/bundle
          key: bundle-use-ruby-${{ runner.os }}-3.3-${{ hashFiles('**/Gemfile.lock') }}
          restore-keys: |
            bundle-use-ruby-${{ runner.os }}-3.3-

      - name: Checkout Latest Repo
        uses: actions/checkout@v4
        with:
          submodules: recursive

      - name: Set Up Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.3'

      - name: Apply Workaround for Ruby toolcache Gem Directory Permissions
        run: |
          sudo chmod -R go-w /opt/hostedtoolcache/Ruby/**/**/lib/ruby/gems/**/gems || true

      - name: Install Gem Dependencies
        run: |
          bundle install

      # LC_ALL/LANG=C (POSIX) is the stress pick: it's always available (no locale-gen
      # needed, unlike the ja_JP.UTF-8 job above) and it's the locale under which Ruby's
      # Encoding.default_external resolves to US-ASCII rather than UTF-8 on Linux. That's
      # the actual condition under test — source files here are UTF-8, but the platform
      # default encoding is 7-bit ASCII, which is what surfaces bugs in code that reads
      # or scans file content without accounting for the platform's default encoding.
      # These env vars set the job-level default before RSpec boots; the spec itself
      # additionally re-asserts them per-invocation since SystemContext#with_context
      # otherwise forces en_US.UTF-8 ahead of each nested Ceedling call.
      - name: Run Example Projects Under C/POSIX Default Encoding Stress
        env:
          LC_ALL: C
          LANG: C
          CI_RSPEC_PROGRESS_FORMAT: true
        run: |
          rake spec:system:debug:encoding_stress

      # Passing project directories are deleted immediately by done!; passing logs are never written.
      # This step is retained as a safety net in case of any leftover pass artifacts.
      - name: Remove passing system test artifacts before upload
        if: failure()
        shell: bash
        run: |
          rm -rf systests/proj/pass || true
          rm -f systests/systest.pass.*.log || true

      # Upload system test failure logs and temp project directories on test job failure
      - name: Upload system test failure artifacts
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: systest-failures-encoding-stress-ruby-3.3
          path: systests/
          if-no-files-found: ignore


  # Job: Build the Ceedling gem once all tests pass
  # Verifies a clean gem build is possible; the built gem is uploaded as a
  # downloadable workflow artifact. No release is created here.
  build-gem:
    name: "Validate Ceedling Gem Build"
    needs:
      - tests-linux
      - tests-windows
      - tests-macos
      - tests-linux-locale
      - tests-linux-encoding-stress
    runs-on: ubuntu-latest

    steps:
      # Use a cache for our tools to speed up builds
      # No matrix here; Ruby version is hardcoded to match the cache key format used by test jobs
      - uses: actions/cache@v4
        with:
          path: vendor/bundle
          key: bundle-use-ruby-${{ runner.os }}-3.3-${{ hashFiles('**/Gemfile.lock') }}
          restore-keys: |
            bundle-use-ruby-${{ runner.os }}-3.3-

      - name: Checkout Latest Repo
        uses: actions/checkout@v4
        with:
          submodules: recursive

      - name: Set Up Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.3'

      - name: Install Gem Dependencies
        run: |
          bundle install

      # Download HTML docs bundle built by generate-docs job to validate docs ingestion in gem build
      - name: Download HTML Documentation Bundle
        uses: actions/download-artifact@v4
        with:
          name: gem-docs-site-local
          path: site-local/

      - name: Build Ceedling Gem
        run: |
          gem build ceedling.gemspec

      # Upload the built gem as a workflow artifact (downloadable from the Actions UI)
      - name: Upload Built Gem Artifact
        uses: actions/upload-artifact@v4
        with:
          name: ceedling-gem
          path: ceedling-*.gem
          if-no-files-found: error