coverage: emit a markdown job summary from the report generator (#440)

* coverage: emit a markdown job summary from the report generator

Every consumer that wants a human-readable coverage summary on its
workflow run page has been re-parsing the LCOV itself; the report
generator now emits it directly.

- New py_binary coverage_summary (stdlib only): parses the pipeline's
  LCOV (which includes the exact-0% baseline records), aggregates
  line/branch/file totals, and renders markdown — overall table with
  text progress bars, raw-vs-effective when a justification report
  exists, a per-directory rollup (first one/two path segments, worst
  first), and collapsible least-covered / exact-0% file lists, closing
  with a pointer to the HTML artifact.
- generate_coverage_html: new optional --summary-md <path>; when the
  flag is absent and GITHUB_STEP_SUMMARY is set (GitHub Actions), the
  summary is appended there automatically; with neither, behavior is
  unchanged. Emitted BEFORE the threshold gate decides the exit code,
  so a failing gate still leaves the summary on the run page.
- Edge cases covered by unit tests: missing/empty LCOV (note instead of
  crash), records with LF but no BRF (branch cells render as an em
  dash), BRDA fallback counting, zero denominators, non-UTF8 bytes in
  paths, markdown cell escaping.
- Integration workspace: asserts summary content markers, append
  semantics for GITHUB_STEP_SUMMARY (existing content preserved), and
  that the summary survives a failing gate. The test script unsets
  GITHUB_STEP_SUMMARY first so CI runs don't spam the real run page.
- Docs: adoption guide (README) and COVERAGE_GUIDE updated.

* coverage: clarify summary test resets, import-lib pattern and bar docstring

Review follow-up for #440: comment why each summary test section deletes
summary.md before its own run (stale-file false passes; the failing-gate
section must prove re-creation), note that imports=[".."] is confined to
the *_lib unit-test import helpers, and state in the docstring that the
progress bar visualizes the coverage percentage.

Author: dcalavrezo-qorix

.gitignore

@@ -20,3 +20,5 @@ coverage-html/
 coverage/integration_tests/coverage_artifacts.zip
 coverage/integration_tests/lcov.dat
 coverage/integration_tests/coverage_linux/
+coverage/integration_tests/summary.md
+coverage/integration_tests/step_summary.md

coverage/BUILD

@@ -56,6 +56,13 @@ py_binary(
     srcs = ["effective_coverage.py"],
 )
 
+# Markdown job summary (GITHUB_STEP_SUMMARY / --summary-md), invoked by
+# generate_coverage_html.sh. Stdlib only.
+py_binary(
+    name = "coverage_summary",
+    srcs = ["coverage_summary.py"],
+)
+
 sh_binary(
     name = "generate_coverage_html",
     srcs = ["generate_coverage_html.sh"],
@@ -75,6 +82,15 @@ py_library(
     deps = ["@rules_python//python/runfiles"],
 )
 
+# Import-only test helper like merger_lib/reporter_lib above: imports=[".."]
+# makes `from coverage.coverage_summary import ...` resolvable from the unit
+# tests. Only the *_lib targets carry it; the binaries are unaffected.
+py_library(
+    name = "coverage_summary_lib",
+    srcs = ["coverage_summary.py"],
+    imports = [".."],
+)
+
 # These compile time options are required to cover abnormal termination cases
 # (death tests). LLVM provides them in combination with a specific profile
 # setting which is enabled in Bazel via LLVM_PROFILE_CONTINUOUS_MODE.

coverage/COVERAGE_GUIDE.md

@@ -181,6 +181,14 @@ bazel run @score_tooling//coverage:generate_coverage_html -- \
   (exit 1)** when below. The model: every uncovered line must eventually be
   either tested or justified; the threshold is ratcheted up as gaps close.
 
+- Optionally a **markdown job summary** is emitted (`--summary-md <path>`, or
+  appended to `GITHUB_STEP_SUMMARY` automatically inside GitHub Actions when
+  the flag is absent): overall/per-directory tables computed from the LCOV
+  data (which includes the exact-0% baseline records), raw-vs-effective
+  numbers when justifications ran, and collapsible least-covered/0% file
+  lists. It is written before the gate decides the exit code, so a failing
+  gate still leaves the summary on the run page.
+
 ### 2.3 Day-to-day commands
 
 ```bash

coverage/README.md

@@ -43,6 +43,7 @@ is copied from it.
 | `@score_tooling//coverage:generate_coverage_html` | Orchestration: unpacks the report, runs justifications, enforces the threshold, optionally archives. |
 | `@score_tooling//coverage:justify` | Parses the justification YAML + in-code markers into a manifest. |
 | `@score_tooling//coverage:effective_coverage` | Post-processes the HTML: restyles justified lines, computes effective coverage, detects stale justifications. |
+| `@score_tooling//coverage:coverage_summary` | Renders the markdown job summary from the LCOV data (invoked by `generate_coverage_html` for `--summary-md` / `GITHUB_STEP_SUMMARY`). |
 | `@score_tooling//coverage:enable_llvm_coverage_for_death_tests` | `cc_feature` adding `-mllvm -runtime-counter-relocation` (continuous-mode profiling for death tests). |
 
 ## Prerequisites
@@ -207,6 +208,16 @@ COVERAGE_THRESHOLD=95 bazel run @score_tooling//coverage:generate_coverage_html
 a YAML; add one (`version: 1` + `justifications: []`) when you introduce your
 first `COV_JUSTIFIED` marker.
 
+**GitHub job summary:** inside GitHub Actions no extra flags are needed — when
+`GITHUB_STEP_SUMMARY` is set (and `--summary-md` is not given), a markdown
+summary is appended to the workflow run page automatically: overall
+line/branch/file tables with progress bars, raw-vs-effective when a
+justification YAML is in play, a per-directory rollup (worst first), and
+collapsible lists of the least-covered and exact-0% files. Outside Actions,
+pass `--summary-md <path>` to write the same summary to a file. The summary is
+emitted before the threshold gate decides the exit code, so a failing gate
+still leaves it on the run page. No consumer-side LCOV parsing needed.
+
 `--build_tests_only` matters: without it, coverage builds (not runs) every
 target matched by the pattern, including e.g. `manual`-tagged or
 platform-incompatible test binaries.
@@ -219,6 +230,7 @@ platform-incompatible test binaries.
 | Output directory | positional `output-dir` argument (default `coverage_<platform>`) |
 | Platform-specific justifications | `--platform linux\|qnx` (default linux) |
 | JUnit XMLs subtree in the archive | `--testlogs-subdir <dir>` (default: whole `bazel-testlogs`) |
+| Markdown job summary | `--summary-md <path>`; auto-append to `GITHUB_STEP_SUMMARY` when the flag is absent and the variable is set |
 | Different LLVM version | your own `llvm.toolchain(...)`; pass its labels in step 3 |
 | Rust branch coverage | `-Zcoverage-options=branch` (needs a nightly-based/rolling Ferrocene; drop the flag on stable) |