c++-code-formatting.yml

---
name: C++ code formatting reusable workflow

'on':
  workflow_call:
    secrets:
      alibuild_github_token:
        required: true
        description: >-
          The GitHub token to use to push commits to alibuild's repo. This is
          used for automatic cleanup PRs containing fixes from clang-format.

# For sensitive actions (e.g. pushing to cleanup branches), we use a
# manually-specified token (secrets.alibuild_github_token).
permissions: {}

env:
  # GitHub also provides github.event.pull_request.base.sha, but that isn't
  # always the latest commit on the base branch (e.g. see
  # https://github.com/AliceO2Group/AliceO2/pull/12499). Using it might lead
  # to false positives in the errors we show.
  BASE_BRANCH: ${{ github.event.pull_request.base.ref }}
  PR_BRANCH: ${{ github.event.pull_request.head.ref }}
  PR_NUMBER: ${{ github.event.pull_request.number }}

jobs:
  clang-format:
    name: clang-format
    # Keep the clang-format version synced with the one installed by aliBuild,
    # (see https://github.com/alisw/alidist/blob/master/clang.sh).
    runs-on: ubuntu-24.04

    steps:
      - name: Checkout code
        uses: actions/checkout@v6
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          persist-credentials: false
          # We need the history of the dev branch all the way back to where the
          # PR diverged. We're fetching everything here, as we don't know how
          # many commits back that point is.
          fetch-depth: 0

      - name: Install prerequisites
        env:
          DEBIAN_FRONTEND: noninteractive
        run: |
          sudo apt update
          sudo apt install -y clang-format-20
          sudo update-alternatives --install /usr/bin/clang-format \
            clang-format /usr/bin/clang-format-20 100
          sudo update-alternatives --install /usr/bin/git-clang-format \
            git-clang-format /usr/bin/git-clang-format-20 100
          sudo update-alternatives --set clang-format /usr/bin/clang-format-20
          sudo update-alternatives --set git-clang-format /usr/bin/git-clang-format-20

      # We need to fetch the PR's head commit to base our cleanup commit on.
      - name: Fetch PR branch
        run: |
          git config --global user.email 'alibuild@cern.ch'
          git config --global user.name 'ALICE Action Bot'
          git fetch origin "$BASE_BRANCH"

      - name: Run clang format
        id: clang_format
        run: |
          set -x
          # $BASE_BRANCH is the branch the PR will be merged into, NOT the
          # commit this PR derives from! For that, we need to find the latest
          # common ancestor between the PR and the branch we are merging into.
          base_commit=$(git merge-base HEAD "origin/$BASE_BRANCH")
          # Find changed files, ignoring binary files.
          readarray -d '' commit_files < \
            <(git diff -z --diff-filter d --name-only "$base_commit")
          [ ${#commit_files[@]} -gt 0 ] || { echo "No files to check"; exit 0; }

          # Check for invalid file extensions for C++ code.
          have_invalid_extension=
          for file in "${commit_files[@]}"; do
            case $file in
              */3rdparty/*) ;;   # ignore vendored files
              *.hxx|*.cc|*.hpp)
                echo "The following error is for file $file:"
                echo "::error file=$file::$file uses non-allowed extension"
                have_invalid_extension=true ;;
            esac
          done
          # Abort now if invalid file extensions found.
          [ -z "$have_invalid_extension" ]

          if patch=$(git-clang-format --commit "$base_commit" --diff \
                                      --style file "${commit_files[@]}")
          then
            echo cleanup_commit= >> "$GITHUB_OUTPUT"
            exit 0
          fi

          echo "$patch" | patch -p1
          git commit -am 'Please consider the following formatting changes'
          cat << EOF >> "$GITHUB_STEP_SUMMARY"
          # clang-format failed

          To reproduce it locally please run

          \`\`\`sh
          git checkout $PR_BRANCH
          git-clang-format --commit $base_commit --diff --style file
          \`\`\`

          Note: using clang-format version $(clang-format --version).

          Opening a PR to your branch with the fixes.
          EOF
          echo cleanup_commit=HEAD >> "$GITHUB_OUTPUT"
          exit 1

      - name: Update cleanup branch
        # Run this even if clang-format fails (i.e. finds formatting issues).
        if: ${{ (success() || failure()) && github.event.repository.owner.login == 'AliceO2Group' }}
        env:
          REMOTE_URL: "https://alibuild:${{ secrets.alibuild_github_token }}@\
            github.com/alibuild/${{ github.event.repository.name }}"
          # An empty CLEANUP_COMMIT means delete the branch.
          CLEANUP_COMMIT: ${{ steps.clang_format.outputs.cleanup_commit }}
        run: |
          git push -f "$REMOTE_URL" "$CLEANUP_COMMIT:refs/heads/alibot-cleanup-$PR_NUMBER"

      - name: Create pull request with formatting changes
        uses: alisw/pull-request@v2
        # Run this even if clang-format fails (i.e. finds formatting issues).
        if: ${{ (success() || failure()) && github.event.repository.owner.login == 'AliceO2Group' }}
        with:
          source_branch: 'alibuild:alibot-cleanup-${{ github.event.pull_request.number }}'
          destination_branch: '${{ github.event.pull_request.head.label }}'
          github_token: ${{ secrets.alibuild_github_token }}
          pr_title: >-
            Please consider the following formatting changes to
            #${{ github.event.pull_request.number }}
          pr_body: >-
            Your PR ${{ github.event.pull_request.html_url }} cannot be merged as is. You should either run `clang-format`
            yourself and update the pull request, or merge this PR in yours.

            You can find the AliceO2 coding conventions at
            <https://github.com/AliceO2Group/CodingGuidelines>.
        continue-on-error: true  # We do not create PRs if the branch is not there.

  copyright:
    name: copyright headers
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v6
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          persist-credentials: false
          # We need the history of the dev branch all the way back to where the
          # PR diverged. We're fetching everything here, as we don't know how
          # many commits back that point is.
          fetch-depth: 0

      # Fetch the PR's base branch to find the common ancestor.
      - name: Update PR branch
        run: git fetch origin "$BASE_BRANCH"

      - name: Check copyright headers
        env:
          # The expected copyright notice. Comment markers ("//" or "#") are
          # added automatically and should NOT appear in this variable.
          # We want to ignore the year, so treat the first line as a regex.
          COPYRIGHT_FIRST_LINE: |-
            Copyright [0-9]{4}-[0-9]{4} CERN and copyright holders of ALICE O2\.
          COPYRIGHT_REST: |-
            See https://alice-o2.web.cern.ch/copyright for details of the copyright holders.
            All rights not expressly granted are reserved.

            This software is distributed under the terms of the GNU General Public
            License v3 (GPL Version 3), copied verbatim in the file "COPYING".

            In applying this license CERN does not waive the privileges and immunities
            granted to it by virtue of its status as an Intergovernmental Organization
            or submit itself to any jurisdiction.
        run: |
          # Find changed C++ and CMake files. Keep the file extensions in sync
          # with the ones in the "case" statement below!
          readarray -d '' files < \
            <(git diff -z --diff-filter d --name-only --merge-base "origin/$BASE_BRANCH" \
                       -- '*.cxx' '*.h' '*.C' '*.cmake' '*/CMakeLists.txt' CMakeLists.txt)
          # Run copyright notice check. Comment lines start with "//" for C++
          # files and "#" for CMake files.
          cpp_first="// $COPYRIGHT_FIRST_LINE"
          hash_first="# $COPYRIGHT_FIRST_LINE"
          cpp_rest=$(echo "$COPYRIGHT_REST" | sed -r 's,^.+,// \0,; s,^$,//,')
          hash_rest=$(echo "$COPYRIGHT_REST" | sed -r 's,^.+,# \0,; s,^$,#,')
          total_lines=$(($(echo "$COPYRIGHT_REST" | wc -l) + 1))
          incorrect_files=()
          for file in "${files[@]}"; do
            case $file in
              */3rdparty/*) continue ;;  # ignore vendored files
              *.cxx|*.h|*.C) first=$cpp_first rest=$cpp_rest ;;
              *.cmake|*CMakeLists.txt) first=$hash_first rest=$hash_rest ;;
              *) echo "error: unknown file type for $file" >&2; exit 1 ;;
            esac
            if head -1 "$file" | grep -qvEx "$first" ||
               [ "$(head -n "$total_lines" "$file" | tail -n +2)" != "$rest" ]
            then
              incorrect_files+=("$file")
              echo "The following error is for file $file:"
              echo -n "::error file=$file,line=1,endLine=$total_lines,"
              echo -n "title=Missing or malformed copyright notice::"
              echo "This source file is missing the correct copyright notice."
            fi
          done

          # Tell user what to do in case of copyright notice error
          [ ${#incorrect_files[@]} -gt 0 ] || exit 0
          cat << EOF >> "$GITHUB_STEP_SUMMARY"
          The following files are missing the correct copyright notice:

          EOF
          for file in "${incorrect_files[@]}"; do
            echo "- \`$file\`" >> "$GITHUB_STEP_SUMMARY"
          done
          cat << EOF >> "$GITHUB_STEP_SUMMARY"

          Make sure all of your C++ and CMake source files begin with the
          following exact lines (but replace the \`//\` at the beginning of each
          line with a \`#\` for CMake files):

          \`\`\`
          $(echo "$cpp_first" |
              sed -r 's/\[0-9\]\{4\}/2020/; s/\[0-9\]\{4\}/2022/; s/\\\././')
          $cpp_rest
          \`\`\`

          (The year numbers on the first line aren't checked.)
          EOF
          exit 1

  line-endings:
    name: line endings
    runs-on: ubuntu-latest

    steps:
      - name: Install prerequisites
        run: |
          sudo -n apt update
          sudo -n apt install dos2unix

      - name: Checkout code
        uses: actions/checkout@v6
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          persist-credentials: false

      - name: Check for incorrect line endings
        run: |
          # shellcheck disable=SC1004
          if find . \( -path ./.git -prune -false \) -o -type f \( \
               -name '*.c' -o -name '*.C' -o -name '*.cpp' -o -name '*.cxx' -o \
               -name '*.cl' -o -name '*.h' -o -name '*.hpp' -o -name '*.py' -o \
               -name '*.sh' -o -name '*.xml' -o -name '*.yml' \) -print0 |
             xargs -0 dos2unix -i |
             awk '
               function error(title, message) {
                 printf "The following error is for file %s:\n", $6
                 printf "::error file=%s,title=%s::%s\n", $6, title, message
                 exit_code = 0
               }
               BEGIN { exit_code = 1 }
               END { exit exit_code }
               ($5 != "text") { next }
               ($4 != "no_bom") {
                 error("BOM or wrong encoding",
                       "All files must be UTF-8 without a byte order mark. " \
                       "Found a byte order mark for the " $4 " encoding.")
               }
               ($1 > 0) {
                 error("DOS line endings",
                       "Files must have UNIX-style (LF only) line endings. " \
                       "Found " $1 " DOS-style (CR+LF) line endings.")
               }
               ($3 > 0) {
                 error("Mac line endings",
                       "Files must have UNIX-style (LF only) line endings. " \
                       "Found " $3 " Mac-style (CR only) line endings.")
               }
             '
          then
            cat << EOF >> "$GITHUB_STEP_SUMMARY"
          # Line ending and/or encoding errors found

          To avoid these errors, configure your editor to:

          - Write files with UNIX-style line endings (linefeeds only).
          - Write files as UTF-8 without a byte order mark (BOM).
          EOF
            exit 1
          fi

  whitespace:
    name: whitespace
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v6
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          persist-credentials: false
          # We need the history of the dev branch all the way back to where the
          # PR diverged. We're fetching everything here, as we don't know how
          # many commits back that point is.
          fetch-depth: 0

      # Fetch the PR's base branch to find the common ancestor.
      - name: Update PR branch
        run: git fetch origin "$BASE_BRANCH"

      - name: Find bad spacing
        run: |
          # Find changed files, ignoring binary files.
          readarray -d '' files < \
            <(git diff -z --diff-filter d --name-only --merge-base "origin/$BASE_BRANCH" |
                while read -rd '' filename; do
                  # Skip 3rdparty files
                  [[ "$filename" == */3rdparty/* ]] && continue
                  file -bi "$filename" | grep -q charset=binary ||
                    printf "%s\\0" "$filename"
                done)
          echo 'Changed text files are:'
          printf '%s\n' "${files[@]}"
          # Find tabs and trailing whitespaces in modified text files and show
          # where they are.
          if awk '
            BEGIN { exit_code = 1 }
            function error(title, message) {
              printf "The following error is for file %s, line %i, column %i:\n",
                     FILENAME, FNR, RSTART
              printf "::error file=%s,line=%i,col=%i,endColumn=%i,title=%s::%s\n",
                     FILENAME, FNR, RSTART, RSTART + RLENGTH, title, message
              exit_code = 0
            }
            match($0, / +$/) {
              error("Trailing spaces",
                    "Remove the trailing spaces at the end of the line.")
            }
            match($0, /\t+/) {
              # Only check for tabs in C/C++ source files and Python/Shell scripts
              if (FILENAME ~ /\.[ch](xx|pp)?$/ || FILENAME ~ /\.(py|sh)$/) {
                error("Tab characters found",
                      "Indent code using spaces instead of tabs.")
              }
            }
            END {
              exit exit_code
            }
          ' "${files[@]}"
          then
            cat << EOF >> "$GITHUB_STEP_SUMMARY"
          # Whitespace errors found.

          Fix the errors in your editor (or with a command).

          ## Command tips

          - Get list of files you changed:
            \`\`\`sh
            git diff --diff-filter d --name-only --merge-base upstream/$BASE_BRANCH
            \`\`\`
          - Replace each tab with two spaces:
            \`\`\`sh
            sed -i 's/\t/  /g' <files>
            \`\`\`
          - Remove trailing whitespaces:
            \`\`\`sh
            sed -i 's/[[:space:]]*$//' <files>
            \`\`\`

          To avoid these errors, configure your editor to:

          - Emit spaces when the Tab key is pressed.
          - Display whitespace characters.
          - Replace tabs with spaces and remove trailing whitespaces when a file is saved.
          EOF
            exit 1
          fi

  pragma-once:
    name: pragma-once
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          persist-credentials: false

      - name: Run pragma check
        run: |
          git --no-pager grep -q '#pragma once' -- '*.h' || exit 0
          # Some files have #pragma once.
          cat << EOF >> "$GITHUB_STEP_SUMMARY"
          The following files use \`#pragma once\`. Please change them.

          EOF
          git --no-pager grep --line-number --column '#pragma once' -- '*.h' |
            while IFS=: read -r file line column _; do
              echo "The following error is for file $file, line $line:"
              echo -n "::error file=$file,line=$line,column=$column,"
              echo 'title=#pragma once::Do not use #pragma once.'
              echo "- \`$file\`" >> "$GITHUB_STEP_SUMMARY"
            done
          exit 1