[#50] Update Code Coverage Tools & Documentation

- remove coverage script that relies on nightly builds
- rename script using tarpaulin coverage
- add coverage script using llvm-cov
- add README for tools

Implements [#34]

.gitignore

@@ -17,3 +17,4 @@ tarpaulin-report.html
 .idea/
 .vscode/launch.json
 .vscode/settings.json
+reports/

tools/README.md

@@ -0,0 +1,34 @@
+# Tools
+
+The scripts in this folder help with commands with long arguments
+
+* generate_llvm_coverage.sh **(RECOMMENDED)**
+
+Generate coverage using the llvm coverage tool. The output files are generated to reports/llvm/html/index.html, reports/llvm/lcov.info & reports/llvm/lcov/index.html
+
+``` bash
+$ sh tools/generate_llvm_coverage.sh 
+... 
+Writing directory view page.
+Overall coverage rate:
+  lines......: 78.1% (890 of 1140 lines)
+  functions..: 55.1% (201 of 365 functions)
+llvm-cov report generated to reports/llvm/html/index.html 
+lcov report generated to: reports/llvm/lcov/index.html 
+```
+
+* generate_tarpaulin_coverage.sh
+
+This script generates coverage reports using the tarpaulin interface _and_ lcov. The output files are generated to reports/tarpaulin-report.html, reports/lcov.info & reports/lcov/index.html.
+
+execute the script from the repo root:
+``` bash
+$ sh tools/generate_tarpaulin_coverage.sh
+...
+Overall coverage rate:
+  lines......: 75.1% (431 of 574 lines)
+  functions..: 82.3% (51 of 62 functions)
+tarpaulin report generated to reports/tarpaulin-report.html 
+lcov report generated to: reports/lcov/index.html 
+```
+

tools/generate_llvm_coverage.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+
+################################################################################
+# Copyright (c) 2024 Contributors to the Eclipse Foundation
+#
+# See the NOTICE file(s) distributed with this work for additional
+# information regarding copyright ownership.
+#
+# This program and the accompanying materials are made available under the
+# terms of the Apache License Version 2.0 which is available at
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# SPDX-License-Identifier: Apache-2.0
+################################################################################
+
+BLUE='\033[0;34m'
+NC='\033[0m'
+HAS_LLVMCOV=$(cargo install --list | grep cargo-llvm-cov)
+COVERAGE_OUT=reports/llvm
+
+if [ -z "$HAS_LLVMCOV" ]; then
+    echo "cargo-llvm-cov not found, please install it with 'cargo install cargo-llvm-cov'"
+    exit 1
+fi
+
+mkdir -p $COVERAGE_OUT
+
+# generate coverage using llvm
+# RUST_LOG ensures the debug macros are not flagged by the coverage output
+RUST_LOG=trace cargo llvm-cov --html --output-dir $COVERAGE_OUT --ignore-filename-regex 'utils/.*' 2>&1 | grep -Ev 'TRACE|DEBUG|WARN'
+
+# generate lcov coverage 
+RUST_LOG=trace cargo llvm-cov --lcov --output-path $COVERAGE_OUT/lcov.info --ignore-filename-regex 'utils/.*' 2>&1 | grep -Ev 'TRACE|DEBUG|WARN' 
+genhtml -o $COVERAGE_OUT/lcov/ --show-details --highlight --ignore-errors source --legend $COVERAGE_OUT/lcov.info
+
+printf "${BLUE}"
+printf "llvm-cov report generated to \e]8;;file://%s\a%s\e]8;;\a \n" "$PWD/$COVERAGE_OUT/html/index.html" "$COVERAGE_OUT/html/index.html"
+printf 'lcov report generated to: \e]8;;file://%s\a%s\e]8;;\a \n' "$PWD/$COVERAGE_OUT/lcov/index.html" "$COVERAGE_OUT/lcov/index.html"
+printf "${NC}"

tools/generate_tarpaulin_coverage.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+
+################################################################################
+# Copyright (c) 2024 Contributors to the Eclipse Foundation
+#
+# See the NOTICE file(s) distributed with this work for additional
+# information regarding copyright ownership.
+#
+# This program and the accompanying materials are made available under the
+# terms of the Apache License Version 2.0 which is available at
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# SPDX-License-Identifier: Apache-2.0
+################################################################################
+
+BLUE='\033[0;34m'
+NC='\033[0m'
+HAS_TARPAULIN=$(cargo install --list | grep cargo-tarpaulin)
+HAS_GENHTML=$(which genhtml)
+COVERAGE_OUT=reports
+
+if [ -z "$HAS_TARPAULIN" ]; then
+    echo "cargo-tarpaulin not found, please install it with 'cargo install cargo-tarpaulin'"
+    exit 1
+fi
+
+if [ -z "$HAS_GENHTML" ]; then
+    echo "genhtml not found, please install it with 'sudo apt install lcov'"
+    exit 1
+fi
+
+# we want both html and lcov output formats
+cargo tarpaulin -o lcov -o html --exclude-files 'utils/*' --output-dir $COVERAGE_OUT
+# convert the lcov output to html
+genhtml -o $COVERAGE_OUT/lcov/ --show-details --highlight --ignore-errors source --legend lcov.info
+
+printf "${BLUE}"
+printf "tarpaulin report generated to \e]8;;file://%s\a%s\e]8;;\a \n" "$PWD/$COVERAGE_OUT/tarpaulin-report.html" "$COVERAGE_OUT/tarpaulin-report.html"
+printf 'lcov report generated to: \e]8;;file://%s\a%s\e]8;;\a \n' "$PWD/$COVERAGE_OUT/lcov/index.html" "$COVERAGE_OUT/lcov/index.html"
+printf "${NC}"