fix: CI infrastructure, clang-tidy + Conan, and platform fixes

- Fix clang-tidy + Conan: remove -p flag from StaticAnalyzers.cmake
  so CMake passes full compile command (including -isystem paths)
  directly to clang-tidy
- Disable misc-include-cleaner in .clang-tidy (noisy false positives)
- Disable clang-tidy on test targets (Catch2 macro false positives)
- Fix macOS GCC: pre-install Conan deps with libstdc++11 profile
- Skip GCC --coverage on macOS ARM (Apple linker can't find libgcov)
- Install lizard in CI and WASM workflows
- Disable Bloaty/IWYU in CI (not available on runners)
- Pin Emscripten to 3.1.74 (Conan doesn't support emcc 23+)
- Fix auto-clang-format PR checkout (github.head_ref)
- Add myproject_SKIP_CONAN_PROVIDER option to cmake/Conan.cmake
- Add CI_KNOWN_ISSUES.md

Signed-off-by: Helder Ferreira <helder@versatushpc.com.br>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: viniciusferrao

.clang-tidy

@@ -15,7 +15,8 @@ Checks: "*,
         -misc-non-private-member-variables-in-classes,
         -misc-no-recursion,
         -misc-use-anonymous-namespace,
-        -misc-use-internal-linkage
+        -misc-use-internal-linkage,
+        -misc-include-cleaner
 "
 WarningsAsErrors: ''
 HeaderFilterRegex: '(include|src)/'

.github/workflows/auto-clang-format.yml

@@ -7,6 +7,8 @@ jobs:
 
     steps:
     - uses: actions/checkout@v6
+      with:
+        ref: ${{ github.head_ref }}
     - uses: DoozyX/clang-format-lint-action@v0.20
       with:
         source: '.'

.github/workflows/ci.yml

@@ -161,12 +161,43 @@ jobs:
           gcovr: true
           opencppcoverage: true
 
-      - name: Install Conan
-        run: pip install conan
+      - name: Install Conan and Lizard
+        run: pip install conan lizard
+
+      - name: Pre-install Conan deps for macOS GCC
+        if: ${{ runner.os == 'macOS' && contains(matrix.compiler, 'gcc') }}
+        run: |
+          # GCC on macOS uses libstdc++, but the cmake-conan provider
+          # auto-detects Apple Clang and builds packages with libc++.
+          # Pre-install deps with a GCC profile and skip the provider.
+          conan profile detect --force
+          GCC_VER=$(echo "${{ matrix.compiler }}" | grep -o '[0-9]*')
+          cat > ~/.conan2/profiles/default << PROFILE
+          [settings]
+          arch=armv8
+          build_type=Release
+          compiler=gcc
+          compiler.cppstd=23
+          compiler.libcxx=libstdc++11
+          compiler.version=$GCC_VER
+          os=Macos
+          [conf]
+          tools.build:compiler_executables={"c": "gcc-$GCC_VER", "cpp": "g++-$GCC_VER"}
+          PROFILE
+          cat ~/.conan2/profiles/default
+          conan install . --output-folder=build --build=missing -s build_type=Debug
+          conan install . --output-folder=build --build=missing -s build_type=Release
+          conan install . --output-folder=build --build=missing -s build_type=RelWithDebInfo
 
       - name: Configure CMake
+        shell: bash
         run: |
-          cmake -S . -B ./build -G "${{matrix.generator}}" -D${{ env.PROJECT_NAME }}_ENABLE_IPO=${{matrix.enable_ipo }} -DCMAKE_BUILD_TYPE:STRING=${{matrix.build_type}} -D${{ env.PROJECT_NAME }}_PACKAGING_MAINTAINER_MODE:BOOL=${{matrix.packaging_maintainer_mode}} -D${{ env.PROJECT_NAME }}_ENABLE_COVERAGE:BOOL=${{ matrix.build_type == 'Debug' }} -DGIT_SHA:STRING=${{ github.sha }}
+          EXTRA_CMAKE_ARGS=""
+          # macOS GCC: deps pre-installed with libstdc++11 profile
+          if [[ "${{ runner.os }}" == "macOS" && "${{ matrix.compiler }}" =~ gcc ]]; then
+            EXTRA_CMAKE_ARGS="-Dmyproject_SKIP_CONAN_PROVIDER=ON -DCMAKE_PREFIX_PATH=$PWD/build"
+          fi
+          cmake -S . -B ./build -G "${{matrix.generator}}" $EXTRA_CMAKE_ARGS -D${{ env.PROJECT_NAME }}_ENABLE_IPO=${{matrix.enable_ipo }} -DCMAKE_BUILD_TYPE:STRING=${{matrix.build_type}} -D${{ env.PROJECT_NAME }}_PACKAGING_MAINTAINER_MODE:BOOL=${{matrix.packaging_maintainer_mode}} -D${{ env.PROJECT_NAME }}_ENABLE_COVERAGE:BOOL=${{ matrix.build_type == 'Debug' }} -D${{ env.PROJECT_NAME }}_ENABLE_BLOATY:BOOL=OFF -D${{ env.PROJECT_NAME }}_ENABLE_INCLUDE_WHAT_YOU_USE:BOOL=OFF -DGIT_SHA:STRING=${{ github.sha }}
 
       - name: Build
         # Execute the build.  You can specify a specific target with "--target <NAME>"
@@ -205,7 +236,7 @@ jobs:
       - name: Publish to codecov
         uses: codecov/codecov-action@v5
         with:
-          fail_ci_if_error: true # we weren't posting previously
+          fail_ci_if_error: true
           flags: ${{ runner.os }}
           name: ${{ runner.os }}-coverage
           token: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/wasm.yml

@@ -20,15 +20,20 @@ jobs:
       - name: Setup Emscripten
         uses: mymindstorm/setup-emsdk@v14
         with:
-          version: 'latest'
+          # Pin to 3.1.x — Conan's settings.yml doesn't support emcc 23+ yet
+          version: '3.1.74'
 
-      - name: Install Ninja and Conan
+      - name: Install Ninja, Conan, and Lizard
         run: |
           sudo apt-get install -y ninja-build
-          pip install conan
+          pip install conan lizard
 
       - name: Configure CMake
-        run: emcmake cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
+        run: |
+          emcmake cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release \
+            -Dmyproject_ENABLE_BLOATY=OFF \
+            -Dmyproject_ENABLE_INCLUDE_WHAT_YOU_USE=OFF \
+            -Dmyproject_ENABLE_CLANG_TIDY=OFF
 
       - name: Build all WASM targets
         run: emmake cmake --build build --target web-dist

CI_KNOWN_ISSUES.md

@@ -0,0 +1,51 @@
+# CI Known Issues
+
+This document tracks CI limitations and their resolutions. Most issues
+stemmed from the migration from CPM/FetchContent to Conan 2.0.
+
+## clang-tidy and Conan include paths (RESOLVED)
+
+**Status:** Fixed by removing the `-p` flag from `StaticAnalyzers.cmake`.
+
+**Root cause:** The `-p` flag in `CMAKE_CXX_CLANG_TIDY` options told CMake
+to have clang-tidy use `compile_commands.json` instead of passing the full
+compile command directly. This broke include resolution for Conan packages
+whose headers live in external `-isystem` paths (`~/.conan2/p/...`). Without
+`-p`, CMake appends `-- <full compile command>` to clang-tidy, which includes
+all `-isystem` paths and works reliably with Conan.
+
+## macOS + GCC Conan ABI (RESOLVED)
+
+**Status:** Fixed by overriding the Conan profile for macOS GCC in CI.
+
+**Root cause:** Conan's default macOS profile detects Apple Clang and sets
+`compiler.libcxx=libc++`. When building with GCC 14 (which uses `libstdc++`),
+this causes ABI mismatches at link time. Fixed by creating a GCC-specific
+Conan profile with `compiler=gcc` and `compiler.libcxx=libstdc++11`.
+
+## codecov fail_ci_if_error (RESOLVED)
+
+**Status:** Set to `true`. Requires `CODECOV_TOKEN` repository secret.
+
+**Setup:** Add `CODECOV_TOKEN` to the repository secrets at
+`Settings > Secrets and variables > Actions`. The token is obtained from
+[codecov.io](https://codecov.io) after linking the repository. Derived repos
+must configure their own token.
+
+## GCC coverage on macOS ARM
+
+**Status:** Skipped in `cmake/Tests.cmake` when `APPLE AND GNU`.
+
+**Root cause:** GCC's `--coverage` flag links against `libgcov`, which
+Apple's ARM linker can't find. Tests still run and pass; only coverage
+instrumentation is skipped. GCC coverage works on Linux.
+
+## Intel ICX coverage
+
+**Status:** gcovr skipped when `matrix.compiler == intel` in `ci.yml`.
+
+**Root cause:** Intel ICX produces coverage data in a format incompatible
+with `gcov`. Tests still run and pass; only the coverage report is skipped.
+
+**Possible fix:** Use `llvm-cov` from the oneAPI toolkit to process ICX
+coverage data. Nice-to-have, not a blocker.

cmake/Conan.cmake

@@ -6,6 +6,11 @@
 #
 # This file must be included BEFORE the project() call.
 
+option(myproject_SKIP_CONAN_PROVIDER "Skip the Conan CMake provider (use pre-installed deps)" OFF)
+if(myproject_SKIP_CONAN_PROVIDER)
+  return()
+endif()
+
 set(CONAN_PROVIDER_LOCATION "${CMAKE_BINARY_DIR}/cmake/conan_provider.cmake")
 
 if(NOT EXISTS "${CONAN_PROVIDER_LOCATION}")

cmake/StaticAnalyzers.cmake

@@ -74,12 +74,17 @@ macro(myproject_enable_clang_tidy target WARNINGS_AS_ERRORS)
     endif()
 
     # construct the clang-tidy command line
+    # NOTE: Do not add -p here. With -p, CMake tells clang-tidy to use
+    # compile_commands.json instead of passing the full compile command
+    # directly. This breaks include resolution for Conan packages whose
+    # headers live in external -isystem paths outside the build tree.
+    # Without -p, CMake appends "-- <full compile command>" to clang-tidy,
+    # which includes all -isystem paths and works reliably.
     set(CLANG_TIDY_OPTIONS
         ${CLANGTIDY}
         -extra-arg=-Wno-unknown-warning-option
         -extra-arg=-Wno-ignored-optimization-argument
-        -extra-arg=-Wno-unused-command-line-argument
-        -p)
+        -extra-arg=-Wno-unused-command-line-argument)
     # set standard
     if(NOT
        "${CMAKE_CXX_STANDARD}"

cmake/Tests.cmake

@@ -1,5 +1,11 @@
 function(myproject_enable_coverage project_name)
   if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU" OR CMAKE_CXX_COMPILER_ID MATCHES ".*Clang")
+    # GCC's --coverage flag doesn't work on macOS ARM (Apple linker
+    # can't find libgcov). Skip coverage for GCC on Apple platforms.
+    if(APPLE AND CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
+      message(WARNING "Coverage disabled: GCC --coverage is not supported on macOS ARM")
+      return()
+    endif()
     target_compile_options(${project_name} INTERFACE --coverage -g)
     target_link_libraries(${project_name} INTERFACE --coverage)
   endif()

include/myproject/sample_library.hpp

@@ -3,7 +3,7 @@
 
 #include <myproject/sample_library_export.hpp>
 
-[[nodiscard]] SAMPLE_LIBRARY_EXPORT int factorial(int) noexcept;
+[[nodiscard]] SAMPLE_LIBRARY_EXPORT int factorial(int input) noexcept;
 
 [[nodiscard]] constexpr int factorial_constexpr(int input) noexcept {
   if (input == 0) {

src/ftxui_sample/main.cpp

@@ -207,11 +207,9 @@ struct Color {
 
 // A simple way of representing a bitmap on screen using only characters
 struct Bitmap : ftxui::Node {
-  Bitmap(std::size_t width,
-         std::size_t
-             height)  // NOLINT same typed parameters adjacent to each other
-      : width_(width)
-      , height_(height) {}
+  // NOLINTNEXTLINE(bugprone-easily-swappable-parameters)
+  Bitmap(std::size_t width, std::size_t height)
+      : width_(width), height_(height) {}
 
   Color& at(std::size_t cur_x, std::size_t cur_y) {
     return pixels.at((width_ * cur_y) + cur_x);