maint/CI ~ convert to instrumented/source-based coverage calculation

## [why]

Coverage calculations using the past `grcov` method has become increasingly ... odd, with
strange lapses not obviously related to code changes. More recently, Rust (and `grcov`)
have been promoting a new method for code coverage calculation, called instrumented (or
source-based). Discussion about instrumented coverage has now been stabilized and included
in [_The rustc book_][^1].

Unfortunately, the current incarnation of instrumented coverage does not support branch
coverage calculation. It's, at best, a work-in-progress, possibly a works-as-designed,
with, currently, a lack of strong support for adding branch support. "Region" coverage
calculation is instead being discussed as a substitute for branch calculations.

Ultimately, given increasing flakiness with the current method, a more robust and accurate
method of line coverage is worth the loss of information arising from lack of branch
coverage, which is of lower importance for most development.

### refs

[^1]: https://doc.rust-lang.org/rustc/instrument-coverage.html

- [Rust ~ Instrumentation-based coverage](https://doc.rust-lang.org/rustc/instrument-coverage.html) @@ <https://archive.is/ERWrk>
- [HowTo collect Rust source-based coverage](https://marco-c.github.io/2020/11/24/rust-source-based-code-coverage.html) @@ <https://archive.is/X9R14>
- [`grcov` issue ~ missing branch coverage](mozilla/grcov#520)
- [Rust issue ~ add support for branch coverage](rust-lang/rust#79649)

.github/workflows/ci.yml

@@ -1,5 +1,5 @@
-# spell-checker:ignore (rust) clippy rustfmt rustup RUSTC RUSTFLAGS Zpanic Cpanic RUSTDOCFLAGS Ccodegen Coverflow
-# spell-checker:ignore (bash) alnum esac (jargon) maint (utils) codecov grcov lcov (vars) tempfile () ntempfile
+# spell-checker:ignore (rust) clippy rustfmt rustup RUSTC RUSTFLAGS Zpanic Cpanic RUSTDOCFLAGS Ccodegen Coverflow profraw
+# spell-checker:ignore (abbrevs/acronyms) MSVC (bash) alnum esac (jargon) maint (utils) codecov grcov lcov (vars) tempfile () ntempfile
 
 on: [push, pull_request]
 
@@ -97,16 +97,16 @@ jobs:
  - { os: windows-latest, features: windows }
  steps:
  - uses: actions/checkout@v3
- - name: Initialize workflow variables
+ - name: Initialize/setup workflow
  id: vars
  shell: bash
  run: |
- ## VARs setup
+ ## VARs and paths setup
  outputs() { step_id="${{ github.action }}"; for var in "$@" ; do echo steps.${step_id}.outputs.${var}="${!var}"; echo "${var}=${!var}" >> $GITHUB_OUTPUT; done; }
  # toolchain
  TOOLCHAIN="nightly" ## default to "nightly" toolchain (required for certain required unstable compiler flags) ## !maint: refactor when stable channel has needed support
  # * specify gnu-type TOOLCHAIN for windows; `grcov` requires gnu-style code coverage data files
- case ${{ matrix.job.os }} in windows-*) TOOLCHAIN="$TOOLCHAIN-x86_64-pc-windows-gnu" ;; esac;
+ case ${{ matrix.job.os }} in windows-*) TOOLCHAIN="$TOOLCHAIN-x86_64-pc-windows-msvc" ;; esac;
  # * use requested TOOLCHAIN if specified
  if [ -n "${{ matrix.job.toolchain }}" ]; then TOOLCHAIN="${{ matrix.job.toolchain }}" ; fi
  outputs TOOLCHAIN
@@ -116,6 +116,13 @@ jobs:
  # * CODECOV_FLAGS
  CODECOV_FLAGS=$( echo "${{ matrix.job.os }}" | sed 's/[^[:alnum:]]/_/g' )
  outputs CODECOV_FLAGS
+ # * code coverage
+ COVERAGE_REPORT_DIR="target/debug/coverage"
+ PROFILES_DIR="${COVERAGE_REPORT_DIR}/profiles"
+ mkdir -p "${COVERAGE_REPORT_DIR}" "${PROFILES_DIR}"
+ outputs COVERAGE_REPORT_DIR PROFILES_DIR
+ LLVM_PROFILE_FILE="${PROFILES_DIR}/profile-%p-%m.profraw"
+ outputs LLVM_PROFILE_FILE
  - name: Install `rust` toolchain
  shell: bash
  env:
@@ -124,31 +131,49 @@ jobs:
  ## Install `rust` toolchain
  rm -f "${HOME}/.cargo/bin/"{rustfmt,cargo-fmt}
  rustup toolchain install ${TOOLCHAIN} -c rustfmt --profile minimal
+ rustup component add --toolchain ${TOOLCHAIN} llvm-tools
  rustup default ${TOOLCHAIN}
  - run: cargo install grcov
  - name: Test
  shell: bash
  env:
  CARGO_INCREMENTAL: '0'
+ LLVM_PROFILE_FILE: ${{ steps.vars.outputs.LLVM_PROFILE_FILE }}
  RUSTC_WRAPPER: ''
- RUSTFLAGS: '-Zprofile -Ccodegen-units=1 -Copt-level=0 -Clink-dead-code -Coverflow-checks=off -Zpanic_abort_tests -Cpanic=abort'
- RUSTDOCFLAGS: '-Cpanic=abort'
+ RUSTFLAGS: '-C instrument-coverage'
+ RUSTDOCFLAGS: ''
  run: |
  ## Test
  cargo test ${{ steps.vars.outputs.CARGO_FEATURES_OPTION }} --no-fail-fast
+ - name: Test examples
+ shell: bash
+ env:
+ CARGO_INCREMENTAL: '0'
+ LLVM_PROFILE_FILE: ${{ steps.vars.outputs.LLVM_PROFILE_FILE }}
+ RUSTC_WRAPPER: ''
+ RUSTFLAGS: '-C instrument-coverage'
+ RUSTDOCFLAGS: ''
+ run: |
+ ## Test
+ cargo test ${{ steps.vars.outputs.CARGO_FEATURES_OPTION }} --examples --no-fail-fast
  - name: Generate coverage data (via `grcov`)
  id: coverage
  shell: bash
  run: |
  ## Generate coverage data
- COVERAGE_REPORT_DIR="target/debug"
+ outputs() { step_id="${{ github.action }}"; for var in "$@" ; do echo steps.${step_id}.outputs.${var}="${!var}"; echo "${var}=${!var}" >> $GITHUB_OUTPUT; done; }
+ #
+ COVERAGE_REPORT_DIR='${{ steps.vars.outputs.COVERAGE_REPORT_DIR }}'
+ LLVM_PROFILE_FILE='${{ steps.vars.outputs.LLVM_PROFILE_FILE }}'
+ PROFILES_DIR='${{ steps.vars.outputs.PROFILES_DIR }}'
+ BINARY_PATH='target/debug'
  COVERAGE_REPORT_FILE="${COVERAGE_REPORT_DIR}/lcov.info"
- mkdir -p "${COVERAGE_REPORT_DIR}"
  # display coverage files
- grcov . --output-type files --ignore build.rs --ignore "vendor/*" --ignore "/*" --ignore "[a-zA-Z]:/*" --excl-br-line "^\s*((debug_)?assert(_eq|_ne)?!|#\[derive\()" | sort --unique
+ grcov . --binary-path "${BINARY_PATH}" --source-dir . --output-type files --ignore build.rs --ignore "examples/*" --ignore "vendor/*" --ignore "/*" --ignore "[a-zA-Z]:/*" --excl-br-line "^\s*((debug_)?assert(_eq|_ne)?!|#\[derive\()" | sort --unique
  # generate coverage report
- grcov . --output-type lcov --output-path "${COVERAGE_REPORT_FILE}" --branch --ignore build.rs --ignore "vendor/*" --ignore "/*" --ignore "[a-zA-Z]:/*" --excl-br-line "^\s*((debug_)?assert(_eq|_ne)?!|#\[derive\()"
- echo "report=${COVERAGE_REPORT_FILE}" >> $GITHUB_OUTPUT
+ grcov . --binary-path "${BINARY_PATH}" --source-dir . --output-type lcov --output-path "${COVERAGE_REPORT_FILE}" --ignore build.rs --ignore "examples/*" --ignore "vendor/*" --ignore "/*" --ignore "[a-zA-Z]:/*" --excl-br-line "^\s*((debug_)?assert(_eq|_ne)?!|#\[derive\()"
+ report=${COVERAGE_REPORT_FILE}
+ outputs report
  - name: Upload coverage results (to Codecov.io)
  uses: codecov/codecov-action@v3
  # if: steps.vars.outputs.HAS_CODECOV_TOKEN