From 711815a5c048cd4329a52f5df51bf4d30ce83647 Mon Sep 17 00:00:00 2001 From: Torsten Kilias Date: Mon, 21 Sep 2026 19:34:29 +0200 Subject: [PATCH 1/5] docs: add local v2 coverage guide Document local LCOV and HTML coverage generation plus the CI-compatible SonarQube coverage report. --- doc/developer_guide/v2/v2.md | 1 + doc/developer_guide/v2/v2_coverage.md | 57 +++++++++++++++++++++++++++ 2 files changed, 58 insertions(+) create mode 100644 doc/developer_guide/v2/v2_coverage.md diff --git a/doc/developer_guide/v2/v2.md b/doc/developer_guide/v2/v2.md index 7a51f04..79d408e 100644 --- a/doc/developer_guide/v2/v2.md +++ b/doc/developer_guide/v2/v2.md @@ -4,6 +4,7 @@ The v2 developer documentation is split into focused guides: - [Build and test](v2_build_and_test.md) — Bazel setup and test execution. - [Code quality](v2_code_quality.md) — clang-tidy and clang-format checks. +- [Coverage](v2_coverage.md) — local LCOV and HTML coverage reports. - [Fuzzing](v2_fuzzing.md) — libFuzzer targets, Nox campaigns, and regression runs. - [Dependency policy](v2_dependency_policy.md) — third-party isolation and diff --git a/doc/developer_guide/v2/v2_coverage.md b/doc/developer_guide/v2/v2_coverage.md new file mode 100644 index 0000000..0a155a9 --- /dev/null +++ b/doc/developer_guide/v2/v2_coverage.md @@ -0,0 +1,57 @@ +# v2 Coverage Guide + +## Generate a local coverage report + +Install Bazel, LLVM coverage tooling, and `lcov`/`genhtml` on the local +machine. From the repository root, run the coverage tests from the v2 module: + +```bash +cd udf-runner-cpp/v2 +bazel test --verbose_failures \ + --collect_code_coverage \ + --combined_report=lcov \ + --build_tag_filters=-fuzz-test \ + --test_tag_filters=-fuzz-test \ + //... +``` + +The combined LCOV report is written to: + +```text +bazel-out/_coverage/_coverage_report.dat +``` + +Generate an HTML report from the LCOV data with: + +```bash +genhtml bazel-out/_coverage/_coverage_report.dat \ + --output-directory coverage-html +``` + +Open `coverage-html/index.html` in a browser to inspect line and file +coverage. The `coverage-html` directory is local build output and should not +be committed. + +## Generate the CI-compatible report + +To generate the report format consumed by the SonarQube configuration, add the +same coverage report generator used in CI: + +```bash +cd udf-runner-cpp/v2 +bazel test --verbose_failures \ + --collect_code_coverage \ + --combined_report=lcov \ + --coverage_report_generator=@bazel_sonarqube//:sonarqube_coverage_generator \ + --build_tag_filters=-fuzz-test \ + --test_tag_filters=-fuzz-test \ + //... +``` + +The generated report is consumed from +`bazel-out/_coverage/_coverage_report.dat`, matching +`sonar.coverageReportPaths` in `sonar-project.properties`. + +Fuzz targets are excluded from these commands because they have separate +sanitizer and regression workflows documented in the [v2 fuzzing +guide](v2_fuzzing.md). From 6f9f3cead7ebb47481e9dd8f0b9bba706414f82f Mon Sep 17 00:00:00 2001 From: Torsten Kilias Date: Mon, 21 Sep 2026 19:36:14 +0200 Subject: [PATCH 2/5] docs: add text coverage report commands --- doc/developer_guide/v2/v2_coverage.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/doc/developer_guide/v2/v2_coverage.md b/doc/developer_guide/v2/v2_coverage.md index 0a155a9..b90e41f 100644 --- a/doc/developer_guide/v2/v2_coverage.md +++ b/doc/developer_guide/v2/v2_coverage.md @@ -21,6 +21,18 @@ The combined LCOV report is written to: bazel-out/_coverage/_coverage_report.dat ``` +Print a text summary of the report with: + +```bash +lcov --summary bazel-out/_coverage/_coverage_report.dat +``` + +For a file-by-file text listing, use: + +```bash +lcov --list bazel-out/_coverage/_coverage_report.dat +``` + Generate an HTML report from the LCOV data with: ```bash From 545b79c82ddcef6db6b8d112009b688219e89c03 Mon Sep 17 00:00:00 2001 From: Torsten Kilias Date: Thu, 24 Sep 2026 18:24:16 +0200 Subject: [PATCH 3/5] docs: ignore generated v2 coverage html --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index fa356eb..3db6f52 100644 --- a/.gitignore +++ b/.gitignore @@ -10,4 +10,5 @@ dist *.swp MODULE.bazel.lock bazel-* +/udf-runner-cpp/v2/coverage-html/ .serena From 5d3b843eec1683de7dcda9b20dad3f3916606d91 Mon Sep 17 00:00:00 2001 From: Torsten Kilias Date: Fri, 25 Sep 2026 11:57:42 +0200 Subject: [PATCH 4/5] docs: enforce branch coverage target --- doc/developer_guide/v2/v2_coverage.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/doc/developer_guide/v2/v2_coverage.md b/doc/developer_guide/v2/v2_coverage.md index b90e41f..f98a8ec 100644 --- a/doc/developer_guide/v2/v2_coverage.md +++ b/doc/developer_guide/v2/v2_coverage.md @@ -37,12 +37,15 @@ Generate an HTML report from the LCOV data with: ```bash genhtml bazel-out/_coverage/_coverage_report.dat \ + --branch-coverage \ + --fail-under-branches 80 \ --output-directory coverage-html ``` Open `coverage-html/index.html` in a browser to inspect line and file -coverage. The `coverage-html` directory is local build output and should not -be committed. +coverage, including branch coverage. The command fails if total branch +coverage is below 80%. The `coverage-html` directory is local build output and +should not be committed. ## Generate the CI-compatible report From e106b76275b732b68cbb970795eb9a1aebb65394 Mon Sep 17 00:00:00 2001 From: Torsten Kilias Date: Fri, 25 Sep 2026 12:10:44 +0200 Subject: [PATCH 5/5] docs: document Lima tool fallback --- AGENTS.md | 13 +++++++++++++ ext/lima_vm_templates/docker-udf-client.yaml | 2 +- 2 files changed, 14 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index e5446b5..cb77e1c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -77,3 +77,16 @@ unreleased changelog, so update it before the PR is merged. namespace-sensitive code. - Prefer the existing Poetry, Nox, and Bazel entry points over ad hoc commands. - Keep generated files and build output out of commits. + +## Tool availability and Lima + +- When a required development tool is unavailable on the host, use the + repository's `docker-udf-client` Lima VM instead of installing a host-wide + package. +- Start the VM with + `limactl start ./ext/lima_vm_templates/docker-udf-client.yaml` and run + commands in it with `limactl shell docker-udf-client `. +- If a required tool is missing in the VM, install it there and add its package + to the provisioning list in + [`ext/lima_vm_templates/docker-udf-client.yaml`](ext/lima_vm_templates/docker-udf-client.yaml) + so future VMs provide it automatically. diff --git a/ext/lima_vm_templates/docker-udf-client.yaml b/ext/lima_vm_templates/docker-udf-client.yaml index 20b1679..724f585 100644 --- a/ext/lima_vm_templates/docker-udf-client.yaml +++ b/ext/lima_vm_templates/docker-udf-client.yaml @@ -59,7 +59,7 @@ provision: - mode: system script: | export DEBIAN_FRONTEND=noninteractive - apt update && apt install -y protobuf-compiler libzmq3-dev openjdk-17-jdk build-essential git python3.12-dev python3-pip libpcre3-dev clang-tidy-20 + apt update && apt install -y protobuf-compiler libzmq3-dev openjdk-17-jdk build-essential git python3.12-dev python3-pip libpcre3-dev clang-tidy-20 lcov curl -L https://github.com/bazelbuild/bazelisk/releases/download/v1.27.0/bazelisk-linux-amd64 -o /usr/bin/bazel chmod +x /usr/bin/bazel pip install --break-system-packages numpy