Refine coverage collection for C++ files

[matteoacrossi]

We decided to leave the points raised by @robertodr's review of #135 for a later PR:

• Remove the narrative comments from the code, because they make me sick
• Add -fcondition-coverage and -fpath-coverage to the compile flags for the coverage build (they give more information)
• Invoke gcovr with --conditions
• Figure out if you can use these options for gcov --prime-paths --prime-paths-lines --prime-paths-source when calling it through gcovr

Originally posted by @robertodr in #135 (review)

[robertodr]

Attaching a Claude report @diagonal-hamiltonian got:

  Context
                                                                                                                                                      PR #33's SonarCloud gate fails on new_coverage (77.9% merged, below the 80% threshold) even though
  line coverage is 95.7%. The drag is condition coverage: 63.2%. This is not a real test gap
  — it's a measurement artifact of how the Python extension is instantiated for coverage.                                                                                                                                                                                                             The engine MonomialPropagator<NumModes> is compiled at 8 storage-width blocks
  [32,64,96,128,160,192,224,256] in the Python extension (driven by monoprop_MAX_NUM_MODES=250 →
  tools/generate-binders.py). gcov counts each instantiation's conditions separately. The
  authoritative asymmetry:
 
 gcovr --merge-lines unions duplicate lines across instantiations → a line covered in any
 ock counts as covered → line coverage 95.7%.
  - It only sums conditions across instantiations (gcovr 8.6 has no flag to union
  conditions — --merge-mode-* is functions-only). So the condition denominator is multiplied.
 
  Crucially, pytest's largest operator is 16 modes (the S0_8e8o fixture,
 sts/test_only_rotate_k.py:105), so dispatch only ever runs the width-32 block. The other 7                                                       ↓
  blocks are compiled but never executed → their conditions are ~0%-covered pure denominator. That                                                   ↓
 ad weight is the whole gap. Native C++ tests are independent of this (they hard-code fixed widths                                                ↓
  {2,3,4,6,8,12} in each TU and clear 80% on their own), so the problem is Python-extension-only.
                                                                                                                                                     ↓
  Goal: make the coverage build compile only the instantiation the tests actually exercise, so the
  condition denominator reflects real code, not dead template copies.
                                                                                                                                                     ↓
  Root-cause fix (primary)                                                                                                                           ↓
 
  Build the coverage Python extension with monoprop_MAX_NUM_MODES=32 → a single width-32 block                                                       ↓
  (the only one pytest executes; 16 ≤ 32 with margin). This removes the 7 never-run 0%-covered                                                       ↓
  instantiations at the source. Line coverage is unaffected (already unioned); condition coverage                                                    ↓
  rises because the inflated 7× denominator is gone. No custom tooling, no product change (production
  ships the default 250), no test changes.                                                                                                           ↓
 
  Edit — .github/workflows/test.yml, python-bindings-coverage job (env block ~lines 258-264)
                                                                                                                                                     ↓
  Add a scikit-build-core CMake override alongside the existing coverage env vars:                                                                   ↓
                                                                                                                                                     ↓
      env:
        SKBUILD_CMAKE_BUILD_TYPE: Coverage                                                                                                           ↓
        SKBUILD_BUILD_DIR: ${{ github.workspace }}/build-python-coverage
        # Coverage-only: compile a single engine instantiation (the width-32 block is the only
        # one the tests dispatch to; the operator max is 16 modes). This avoids gcov counting                                                        ↓
        # conditions across 8 template widths, 7 of which are never executed — an inflation that                                                     ↓
        # gcovr --merge-lines does not dedup for conditions (only for lines). Production keeps 250.
        SKBUILD_CMAKE_ARGS: "-Dmonoprop_MAX_NUM_MODES=32"
 
  (Exact env var name to confirm during measurement — scikit-build-core honours SKBUILD_CMAKE_ARGS;                                                  ↓
  verify the generated build-python-coverage/.../generated/bind_up_to_*.cpp count drops from 8 to 1.)                                                ↓
                                                                                                                                                     ↓
  Keep PR #135's --exclude-throw-branches --exclude-unreachable-branches on both collection
  steps (they compose — throw-noise removal + dead-instantiation removal). No change to the merge step
  (gcovr --root . --merge-lines --add-tracefile 'cpp-coverage-*.json' --sonarqube coverage_cpp.xml).                                                 ↓
                                                                                                                                                     ↓
  Where it lands                                                                                                                                     ↓
                                                                                                                                                     ↓
 is is a coverage-measurement fix → it belongs on the main-based PR #135                                                                          ↓
  (fix/sonar-exclude-throw-branches), extending its existing story ("make the coverage number                                                        ↓
  honest"). PR #33 then merges/rebases main and inherits it, on top of the 3 test files already                                                      ↓
  written there (the test top-up). No coverage-config change goes on PR #33 itself.                                                                  ↓
                                                                                                                                                     ↓
  Verification (measure before touching CI)
                                                                                                                                                     ↓
  Use the scratchpad harness (env.sh, py_cov.sh, newcov_full.py, cov_native.json). One caveat:
  the install-time generate-dispatch.py overwrites the working-tree src/monoprop/_dispatch.py,
  so a MAX=32 build rewrites it locally — restore afterward.                                                                                         ↓
 
  1. rm -rf build-python-coverage (the existing tree is cached at 250).
  2. Re-run the python-coverage build with SKBUILD_CMAKE_ARGS="-Dmonoprop_MAX_NUM_MODES=32" added to                                                 ↓
  py_cov.sh; confirm exactly one bind_up_to_*.cpp is generated and pytest is green (477).
  3. Re-merge the new cov_python.json with the existing throw-excluded cov_native.json and
  recompute: newcov_full.py sonar_merged.xml. Decision gate: expect new_coverage ≥ 80% with a
  comfortable margin (native alone is ≥80% throw-excluded; adding the well-executed width-32                                                         ↓
  Python block should keep it there). Record the exact merged line/condition/overall numbers.                                                        ↓
  4. Restore dev env: git checkout src/monoprop/_dispatch.py, then reinstall the Release                                                             ↓
  extension (uv pip install -e . --reinstall) — the venv currently holds the Coverage build.                                                         ↓
 
  Then apply to CI: edit test.yml on fix/sonar-exclude-throw-branches, push, and confirm the
  SonarCloud gate on the PR reports new_coverage ≥ 80%.                                                                                              ↓
 
  Fallback ladder (only if the measured margin is thin)
                                                                                                                                                     ↓
  Condition-union post-processor (most correct, build-agnostic): a small script that reads the                                                    ↓
  per-instantiation gcovr JSON and logical-ORs conditions per (file,line) before emitting the
  SonarQube XML — does for conditions what --merge-lines does for lines, covering native
  multiplicity too. Adds one maintained CI script.                                                                                                   ↓
  2. sonar.coverage.exclusions on the two template-heaviest headers                                                                                  ↓
 etail/evolution/layer_build/Scan.h, detail/monomial_propagator/MonomialPropagatorImpl.h) —                                                       ↓
  pragmatic, but hides some real signal.
  3. gcovr --sonarqube-metric line on the merge step — reports line coverage only (~95.7%);                                                          ↓
  abandons branch signal project-wide. Last resort.
 
 t of scope / carried forward                                                                                                                     ↓
                                                                                                                                                     ↓
 The 3 new C++ test files on perf/align-with-paper (env_config_tests.cpp,                                                                         ↓
  profiling_coverage_tests.cpp, cpu_topology_tests.cpp) are done and green — commit them to
  PR #33 as the test top-up when the user approves (they add genuine coverage of otherwise
  unswept seams; independent of this measurement fix).
  - Rotate the SonarCloud token e5b8a643… (in shell history + scratchpad .sonar_token).

[robertodr]

It seems #152 addresses this. Additional compilation flags cannot be used, if the information is then aggregated with gcovr though.