action.yml

name: C/C++ Linter
description: Linting C/C++ code with clang-tidy or clang-format to give feedback as comments, PR reviews, and more.
author: cpp-linter
branding:
  icon: "check-circle"
  color: "green"
inputs:
  style:
    description: |
      The style rules to use.

      - Set this to `file` to have clang-format use the closest relative .clang-format file.
      - Set this to a blank string (`''`) to disable the use of clang-format entirely.
      - Any code style supported by the specified version of clang-format.
    required: false
    default: "llvm"
  extensions:
    description: The file extensions to run the action against. This is a comma-separated string.
    required: false
    default: "c,h,C,H,cpp,hpp,cc,hh,c++,h++,cxx,hxx"
  tidy-checks:
    description: |
      Comma-separated list of globs with optional `-` prefix.
      Globs are processed in order of appearance in the list.
      Globs without `-` prefix add checks with matching names to the set,
      globs with the `-` prefix remove checks with matching names from the set of enabled checks.
      This option's value is appended to the value of the 'Checks' option in a .clang-tidy file (if any).

      - It is possible to disable clang-tidy entirely by setting this option to `'-*'`.
      - It is also possible to rely solely on a .clang-tidy config file by specifying this option as a blank string (`''`).
    required: false
    default: "boost-*,bugprone-*,performance-*,readability-*,portability-*,modernize-*,clang-analyzer-*,cppcoreguidelines-*"
  repo-root:
    description: >
      The relative path to the repository root directory.
      This path is relative to the path designated as the runner's `GITHUB_WORKSPACE` environment variable.
    required: false
    default: '.'
  version:
    description: |
      The desired version of the [clang-tools](https://github.com/cpp-linter/clang-tools-pip) to use.
      Accepted options are strings which can be 19, 18, 17, 16, 15, 14, 13, 12, 11, 10, 9, 8 or 7.

      - Set this option to a blank string (`''`) to use the platform's default installed version.
      - This value can also be a path to where the clang tools are installed (if using a custom install location).
    required: false
    default: 14
  verbosity:
    description: |
      This controls the action's verbosity in the workflow's logs.
      Supported options are `info` or `debug`.
      This option does not affect the verbosity of resulting thread comments or file annotations.

      The verbosity can also be engaged by enabling debug logs when
      [re-running jobs or workflows](https://docs.github.com/en/actions/managing-workflow-runs/re-running-workflows-and-jobs).
    required: false
    default: info
  lines-changed-only:
    description: |
      This controls what part of the files are analyzed. The following values are accepted:

      - `false`: All lines in a file are analyzed.
      - `true`: Only lines in the diff that contain additions are analyzed.
      - `diff`: All lines in the diff are analyzed (including unchanged lines but not subtractions).

      !!! info "Important"
          This feature requires special permissions to perform successfully.
          See our [documented permissions](permissions.md)
    required: false
    default: false
  files-changed-only:
    description: |
      Set this option to false to analyze any source files in the repo.
      This is automatically enabled if [`lines-changed-only`](#lines-changed-only) is enabled.

      !!! info "Important"
          This feature requires special permissions to perform successfully.
          See our [documented permissions](permissions.md)
    required: false
    default: true
  ignore:
    description: |
      Set this option with string of path(s) to ignore.

      - In the case of multiple paths, you can use a pipe character (`|`)
        to separate the multiple paths. Multiple lines are forbidden as an input to this option;
        it must be a single string.
      - This can also have files, but the file's relative path has to be specified
        as well.
      - There is no need to use `./` for each entry; a blank string (`''`) represents
        the [`repo-root`](#repo-root) path.
      - Submodules are automatically ignored. Hidden directories (beginning with a `.`) are also ignored
        automatically.
      - Prefix a path with a bang (`!`) to make it explicitly _not_ ignored. The order of
        multiple paths does _not_ take precedence. The `!` prefix can be applied to
        a submodule's path (if desired) but not hidden directories.
      - **As of v2.12**, glob patterns are supported here.
        All asterisk characters (`*`) were previously literal.
    required: false
    default: '.github'
  ignore-tidy:
    description: |-
      Use this option to allow clang-tidy to ignore certain paths/files.
      See [`ignore`](#ignore) for more details on possible values.
    required: false
    default: '.github'
  ignore-format:
    description: |-
      Use this option to allow clang-format to ignore certain paths/files.
      See [`ignore`](#ignore) for more details on possible values.
    required: false
    default: '.github'
  thread-comments:
    description: |
      This controls the behavior of posted thread comments as feedback. The following options are supported:

      - `true`: enable the use of thread comments. This will always delete an outdated thread comment and post a new comment (triggering a notification for every comment).
      - `update`: update an existing thread comment if one already exists. This option does not trigger a new notification for every thread comment update.
      - `false`: disable the use of thread comments.

      !!! info "Important"
          This feature requires special permissions to perform successfully.
          See our [documented permissions](permissions.md)

      > [!NOTE]
      > If run on a private repository, then this feature is disabled because the GitHub REST API behaves differently for thread comments on a private repository.
    required: false
    default: 'false'
  no-lgtm:
    description: |
      Set this option to true or false to enable or disable the use of a
      thread comment or pull request review that basically says 'Looks Good To Me' (when all checks pass).
      The default value, `true` means no LGTM comment posted.

      See [`thread-comments`](#thread-comments), [`tidy-review`](#tidy-review),
      and [`format-review`](#format-review) options for further details.
    required: false
    default: true
  step-summary:
    description: |
      Set this option to true to append content as part of workflow's job summary.

      See implementation details in GitHub's documentation about
      [Adding a job summary](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#adding-a-job-summary).
      This option is independent of the [`thread-comments`](#thread-comments) option,
      rather this option uses the same content that the
      [`thread-comments`](#thread-comments) option would use.

      > [!NOTE]
      > The [`no-lgtm`](#no-lgtm) option is _not_ applied to step summaries.
    required: false
    default: false
  file-annotations:
    description: |
      Set this option to false to disable the use of file annotations as feedback.
    required: false
    default: true
  database:
    description: The directory containing compilation database (like compile_commands.json) file.
    required: false
    default: ""
  extra-args:
    description: |
      A string of extra arguments passed to clang-tidy for use as compiler arguments.
      Multiple arguments are separated by spaces so the argument name and value should
      use an `=` sign instead of a space.

      !!! example

          ``` yaml
          extra-args: '-std=c++17 -Wall'
          ```
          This will be passed to clang-tidy as multiple `--extra-arg` options:
          ```
          clang-tidy --extra-arg=-std=c++17 --extra-arg=-Wall
          ```
    required: false
    default: ""
  tidy-review:
    description: |
      Set this option to `true` to enable Pull Request reviews from clang-tidy.

      !!! info "Important"
          This feature requires special permissions to perform successfully.
          See our [documented permissions](permissions.md).

          See also [the PR review feature caveats](pr-review-caveats.md).

      > [!NOTE]
      > The [`no-lgtm`](#no-lgtm) option is applicable to Pull Request reviews.
    required: false
    default: false
  format-review:
    description: |
      Set this option to `true` to enable Pull Request reviews from clang-format.

      !!! info "Important"
          This feature requires special permissions to perform successfully.
          See our [documented permissions](permissions.md).

          See also [the PR review feature caveats](pr-review-caveats.md).

      > [!NOTE]
      > The [`no-lgtm`](#no-lgtm) option is applicable to Pull Request reviews.
    required: false
    default: false
  passive-reviews:
    description: |
      Set this option to `true` to prevent Pull Request reviews from approving or requesting changes.
    default: false
    required: false
  jobs:
    description: |
      The number of jobs to run in parallel.
      If less than or equal to 0, the number of jobs is set to
      use the number of all available CPU cores.
    required: false
    default: 0
outputs:
  checks-failed:
    description: An integer that can be used as a boolean value to indicate if any checks failed by clang-tidy and clang-format.
    value: ${{ steps.cpp-linter-unix.outputs.checks-failed || steps.cpp-linter-windows.outputs.checks-failed }}
  clang-tidy-checks-failed:
    description: An integer that can be used as a boolean value to indicate if any checks failed by clang-tidy only.
    value: ${{ steps.cpp-linter-unix.outputs.clang-tidy-checks-failed || steps.cpp-linter-windows.outputs.clang-tidy-checks-failed }}
  clang-format-checks-failed:
    description: An integer that can be used as a boolean value to indicate if any checks failed by clang-format only.
    value: ${{ steps.cpp-linter-unix.outputs.clang-format-checks-failed || steps.cpp-linter-windows.outputs.clang-format-checks-failed }}
runs:
  using: "composite"
  steps:
    - name: Install python
      uses: actions/setup-python@v5
      id: setup-python
      with:
        # use python version shipped with latest Ubuntu LTS
        python-version: '3.10'
        update-environment: false

    - name: Install Linux clang dependencies
      if: runner.os == 'Linux'
      shell: bash
      run: |
        sudo apt-get update
        # First try installing from default Ubuntu repositories before trying LLVM script
        if ! sudo apt-get install -y clang-format-${{ inputs.version }} clang-tidy-${{ inputs.version }}; then
          # This LLVM script will add the relevant LLVM PPA: https://apt.llvm.org/
          wget https://apt.llvm.org/llvm.sh -O $GITHUB_ACTION_PATH/llvm_install.sh
          chmod +x $GITHUB_ACTION_PATH/llvm_install.sh
          if sudo $GITHUB_ACTION_PATH/llvm_install.sh ${{ inputs.version }}; then
            sudo apt-get install -y clang-format-${{ inputs.version }} clang-tidy-${{ inputs.version }}
          fi
        fi

    - name: Install MacOS clang dependencies
      if: runner.os == 'macOS'
      shell: bash
      continue-on-error: true
      run: |
        brew install llvm@${{ inputs.version }}
        ln -s "$(brew --prefix llvm@${{ inputs.version }})/bin/clang-format" "/usr/local/bin/clang-format-${{ inputs.version }}"
        ln -s "$(brew --prefix llvm@${{ inputs.version }})/bin/clang-tidy" "/usr/local/bin/clang-tidy-${{ inputs.version }}"

    - name: Setup python venv (Unix)
      if: runner.os == 'Linux' || runner.os == 'macOS'
      shell: bash
      run: |
        ${{ steps.setup-python.outputs.python-path }} -m venv "$GITHUB_ACTION_PATH/venv"
        source "$GITHUB_ACTION_PATH/venv/bin/activate"
        pip install -r "$GITHUB_ACTION_PATH/requirements.txt"
        clang-tools -i ${{ inputs.version }} -b

    - name: Run cpp-linter (Unix)
      id: cpp-linter-unix
      if: runner.os == 'Linux' || runner.os == 'macOS'
      shell: bash
      run: |
        source "$GITHUB_ACTION_PATH/venv/bin/activate"

        cpp-linter \
         --style="${{ inputs.style }}" \
         --extensions=${{ inputs.extensions }} \
         --tidy-checks="${{ inputs.tidy-checks }}" \
         --repo-root=${{ inputs.repo-root }} \
         --version=${{ inputs.version }} \
         --verbosity=${{ inputs.verbosity }} \
         --lines-changed-only=${{ inputs.lines-changed-only }} \
         --files-changed-only=${{ inputs.files-changed-only }} \
         --thread-comments=${{ inputs.thread-comments }} \
         --no-lgtm=${{ inputs.no-lgtm }} \
         --step-summary=${{ inputs.step-summary }} \
         --ignore="${{ inputs.ignore }}" \
         --ignore-tidy="${{ inputs.ignore-tidy }}" \
         --ignore-format="${{ inputs.ignore-format }}" \
         --database=${{ inputs.database }} \
         --file-annotations=${{ inputs.file-annotations }} \
         --extra-arg="${{ inputs.extra-args }}" \
         --tidy-review="${{ inputs.tidy-review }}" \
         --format-review="${{ inputs.format-review }}" \
         --passive-reviews="${{ inputs.passive-reviews }}" \
         --jobs=${{ inputs.jobs }}

    - name: Setup python venv (Windows)
      if: runner.os == 'Windows'
      shell: pwsh
      run: |
        ${{ steps.setup-python.outputs.python-path }} -m venv "$env:GITHUB_ACTION_PATH/venv"
        Invoke-Expression -Command "$env:GITHUB_ACTION_PATH/venv/Scripts/Activate.ps1"
        pip install -r "$env:GITHUB_ACTION_PATH/requirements.txt"
        clang-tools -i ${{ inputs.version }} -b

    - name: Run cpp-linter (Windows)
      id: cpp-linter-windows
      if: runner.os == 'Windows'
      shell: pwsh
      run: |
        Invoke-Expression -Command "$env:GITHUB_ACTION_PATH/venv/Scripts/Activate.ps1"

        $app = 'cpp-linter' +
        ' --style="${{ inputs.style }}"' +
        ' --extensions=${{ inputs.extensions }}' +
        ' --tidy-checks="${{ inputs.tidy-checks }}"' +
        ' --repo-root=${{ inputs.repo-root }}' +
        ' --version=${{ inputs.version }}' +
        ' --verbosity=${{ inputs.verbosity }}' +
        ' --lines-changed-only=${{ inputs.lines-changed-only }}' +
        ' --files-changed-only=${{ inputs.files-changed-only }}' +
        ' --thread-comments=${{ inputs.thread-comments }}' +
        ' --no-lgtm=${{ inputs.no-lgtm }}' +
        ' --step-summary=${{ inputs.step-summary }}' +
        ' --ignore="${{ inputs.ignore }}"' +
        ' --ignore-tidy="${{ inputs.ignore-tidy }}"' +
        ' --ignore-format="${{ inputs.ignore-format }}"' +
        ' --database=${{ inputs.database }}' +
        ' --file-annotations=${{ inputs.file-annotations }}' +
        ' --extra-arg="${{ inputs.extra-args }}"' +
        ' --tidy-review="${{ inputs.tidy-review }}"' +
        ' --format-review="${{ inputs.format-review }}"' +
        ' --passive-reviews="${{ inputs.passive-reviews }}"' +
        ' --jobs=${{ inputs.jobs }}'

        Invoke-Expression -Command $app