#52: add local v2 coverage guide

.gitignore

@@ -10,4 +10,5 @@ dist
 *.swp
 MODULE.bazel.lock
 bazel-*
+/udf-runner-cpp/v2/coverage-html/
 .serena

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 <command>`.
+- 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.

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.
 - [Coding style](v2_coding_style.md) — public C++ conventions for v2 code.
 - [Fuzzing](v2_fuzzing.md) — libFuzzer targets, Nox campaigns, and regression
   runs.

doc/developer_guide/v2/v2_coverage.md

@@ -0,0 +1,72 @@
+# 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
+```
+
+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
+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, 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
+
+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).

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