Add code coverage reporting with gcov/lcov

Currently, our test suite has excellent functional coverage (12 comprehensive unit tests), but we don't have automated coverage reporting to visualize and track this. Adding code coverage will:

• Provide visual confirmation of test coverage
• Help identify untested code paths
• Enable coverage badges in README
• Track coverage trends over time
• Is there a way to test the deployment of github-pages https://onesmoogore.github.io/embedded-motor-pid-controller/index.html and associated pages on branches before merging to main to make sure nothing got broken?

Goals

1. Integrate gcov/lcov into CMake build system

   • Add coverage build option (-DCOVERAGE=ON)
   • Configure compiler flags (--coverage, -fprofile-arcs -ftest-coverage)
   • Create custom CMake target for coverage generation

2. Generate HTML coverage reports

   • Use lcov to collect coverage data
   • Generate HTML reports showing line and branch coverage
   • Include reports for all modules (pid.c, motor.c)

3. Add CI/CD workflow for coverage

   • New GitHub Actions job to run tests with coverage
   • Upload coverage reports as artifacts
   • Integrate with Codecov or Coveralls for tracking

4. Add coverage badge to README

   • Display current coverage percentage
   • Link to detailed coverage report

Functional Requirements

1. CMake Configuration:

   option(ENABLE_COVERAGE "Enable code coverage" OFF)
   
   if(ENABLE_COVERAGE AND CMAKE_C_COMPILER_ID MATCHES "GNU|Clang")
       set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} --coverage")
       set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} --coverage")
   endif()
   
   add_custom_target(coverage
       COMMAND lcov --capture --directory . --output-file coverage.info
       COMMAND lcov --remove coverage.info '/usr/*' --output-file coverage.info
       COMMAND genhtml coverage.info --output-directory coverage_html
       DEPENDS test_pid
   )
   

2. Coverage Report Structure:

   • Overall project coverage percentage
   • Per-file coverage breakdown
   • Line coverage
   • Branch coverage
   • Function coverage

3. CI Integration:

   • Run coverage on Ubuntu (GCC)
   • Generate and upload HTML reports
   • Post coverage summary to PR comments (optional)

Test/Validation Criteria

Must Pass:

1. ✅ Coverage Build Success

   • cmake -DENABLE_COVERAGE=ON .. configures successfully
   • make compiles with coverage flags
   • make test runs all tests successfully

2. ✅ Coverage Report Generation

   • make coverage generates coverage.info
   • HTML reports generated in coverage_html/
   • All source files (pid.c, motor.c) included in report

3. ✅ Coverage Metrics

   • Line coverage ≥ 85%
   • Branch coverage ≥ 80%
   • Function coverage = 100%

4. ✅ CI Workflow

   • Coverage job runs successfully in CI
   • Artifacts uploaded (coverage.info, coverage_html/)
   • No regressions in build time (<1 minute overhead)

5. ✅ Documentation

   • README updated with coverage badge
   • build.md includes coverage instructions
   • Coverage report link in README

Acceptance Criteria

• CMake supports -DENABLE_COVERAGE=ON option
• make coverage target generates HTML reports
• CI workflow runs coverage and uploads artifacts
• Coverage badge visible in README.md
• Line coverage ≥ 85%, branch coverage ≥ 80%
• Documentation updated with coverage instructions
• No warnings or errors in coverage generation

Implementation Notes

Tools Required:

• gcov (bundled with GCC)
• lcov (for HTML generation)
• Optional: Codecov/Coveralls for tracking

Platform Considerations:

• Primarily for GCC/Clang (MSVC has different coverage tools)
• Can be Linux/macOS only (add note for Windows users)

Estimated Effort: 2-4 hours