[Advanced]: Integrate Code Coverage for C++ SDK

## 🧠 Advanced Issue

This issue is designed for experienced contributors who are comfortable navigating unfamiliar systems, working with incomplete specifications, and making thoughtful design tradeoffs with long-term implications.

Advanced Issues may involve:
- Major architectural decisions or infrastructure changes
- Cross-cutting concerns that span multiple modules
- Creating new systems or frameworks
- Defining patterns others will follow

The best solutions will reflect care, clarity, and a deep understanding of the problem space.

---

## 🐞 Problem Description

The C++ SDK currently has no code coverage statistics during PR checks or CI execution. This makes it difficult to:
- Identify untested code paths
- Track test coverage trends over time
- Ensure new code is adequately tested
- Maintain code quality standards

**Current state:**
- Tests run via CTest in CI
- No coverage instrumentation
- No coverage reporting
- No visibility into test coverage metrics

---

## 💡 Expected Outcome

Integrate code coverage tooling into the C++ SDK build and CI pipeline.

**Goals:**
1. Generate code coverage data during test execution
2. Upload coverage reports to a reporting service (e.g., Codecov, Coveralls)
3. Display coverage metrics in PR checks
4. Track coverage trends over time

**Non-goals:**
- Enforcing minimum coverage thresholds (can be added later)
- Coverage for all platforms (Linux is sufficient initially)

---

## 🧠 Design Considerations

Several architectural decisions need to be made:

### 1. Coverage Tool Selection
Options for C++ coverage:
- **gcov + lcov** - GCC's native coverage tool + HTML report generator
- **llvm-cov** - LLVM/Clang's coverage tool
- **gcovr** - Python-based gcov report generator

Recommendation: gcov + lcov is most common for GCC-based builds.

### 2. CMake Integration
Add a coverage build option to `CMakeLists.txt`:

```cmake
option(CODE_COVERAGE "Enable code coverage instrumentation" OFF)

if(CODE_COVERAGE AND CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
add_compile_options(--coverage -O0 -g)
add_link_options(--coverage)
endif()
```

Considerations:
- Coverage should only be enabled for Debug builds
- Coverage instrumentation impacts performance
- May need a separate CMake preset for coverage builds

### 3. CI Integration Strategy
Options:
- **Separate coverage job** - dedicated workflow for coverage
- **Extend existing build** - add coverage step to current CI
- **Coverage-only on merge** - reduce PR overhead

Current CI (`zxc-build-library.yaml`) runs:
1. CMake configure/build
2. Solo network setup
3. CTest execution

Coverage steps would add:
1. Build with coverage flags
2. Run tests (generates `.gcda` files)
3. Process with lcov
4. Upload to Codecov/Coveralls

### 4. Reporting Service
Options:
- **Codecov** - widely used, free for open source, GitHub integration
- **Coveralls** - similar features, alternative option
- **SonarCloud** - more comprehensive analysis

### 5. What to Cover
Decisions:
- Unit tests only, or include integration tests?
- Exclude third-party code (vcpkg dependencies)?
- Exclude generated protobuf code?

---

## 📂 Relevant Files

**Build configuration:**
- `CMakeLists.txt` - main CMake configuration
- `CMakePresets.json` - build presets

**CI configuration:**
- `.github/workflows/flow-pull-request-checks.yaml` - PR checks
- `.github/workflows/zxc-build-library.yaml` - build/test pipeline

**Test locations:**
- `src/sdk/tests/unit/` - unit tests
- `src/sdk/tests/integration/` - integration tests

---

## ✅ Acceptance Criteria

- [ ] CMake option added to enable coverage instrumentation
- [ ] Coverage data generated during test execution
- [ ] Coverage reports uploaded to reporting service
- [ ] Coverage badge/metrics visible in PRs
- [ ] Generated/third-party code excluded from coverage
- [ ] Documentation updated with coverage information
- [ ] CI execution time remains reasonable

---

## 📋 Contribution Guide

To help your contribution go as smoothly as possible:

- [ ] Comment `/assign` to request the issue
- [ ] Wait for assignment
- [ ] Fork the repository and create a branch
- [ ] Propose a design in the PR description before implementing
- [ ] Implement CMake changes and CI workflow updates
- [ ] Test coverage generation locally
- [ ] Sign each commit using `-s -S`
- [ ] Push your branch and open a pull request

Read [Workflow Guide](docs/training/workflow.md) for step-by-step workflow guidance.
Read [README.md](README.md) for setup instructions.

**Pull requests cannot be merged without `S` and `s` signed commits.**
See the [Signing Guide](docs/training/signing.md).

---

## 📚 Additional Context or Resources

**Reference article:**
- [Code Coverage Testing for C++](https://www.danielsieger.com/blog/2022/03/06/code-coverage-for-cpp.html)

**Tools:**
- [gcov documentation](https://gcc.gnu.org/onlinedocs/gcc/Gcov.html)
- [lcov](https://github.com/linux-test-project/lcov)
- [Codecov](https://codecov.io/)
- [codecov-action](https://github.com/codecov/codecov-action) - GitHub Action

**Example CMake coverage setup:**

```cmake
# Coverage configuration
option(CODE_COVERAGE "Enable code coverage" OFF)

if(CODE_COVERAGE)
if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
message(STATUS "Code coverage enabled")
add_compile_options(--coverage -O0 -g -fprofile-arcs -ftest-coverage)
add_link_options(--coverage)
else()
message(WARNING "Code coverage requires GCC or Clang")
endif()
endif()
```

**Example CI step:**

```yaml
- name: Generate Coverage Report
run: |
lcov --capture --directory . --output-file coverage.info
lcov --remove coverage.info '/usr/*' '*/vcpkg/*' '*.pb.*' --output-file coverage.info

- name: Upload to Codecov
uses: codecov/codecov-action@v4
with:
files: coverage.info
fail_ci_if_error: true
```

If you have questions, the community is happy to help:

https://discord.com/channels/905194001349627914/1337424839761465364