feat: merge lcov reports from sharded test runs #1754

Description

#1707 adds --shard-index and --total-shards to very_good test and very_good dart test, so a suite can be split across CI runners with a strategy.matrix. Sharding and --min-coverage don't mix well yet. Each shard runs only part of the suite, so its coverage/lcov.info reflects only the code that slice touches. With --collect-coverage-from all, _enhanceLcovWithUntestedFiles also adds every file the shard never loaded at 0%. A shard's percentage is always well below the real number, and a threshold check on it fails healthy builds.

#1707 handles this by rejecting an explicit --min-coverage when sharding. The error tells users to collect coverage per shard with --coverage, merge the lcov reports, and enforce the threshold once in a separate job. The CLI has no way to do those last two steps today, so teams have to reach for lcov or a custom script. A threshold set in very_good.yaml is also ignored silently when sharding, so teams that rely on it lose enforcement without being told.

This issue proposes that the CLI merge the shard reports and run the coverage checks on the merged result.

A possible shape:

jobs:
  test:
    strategy:
      matrix:
        shard: [1, 2, 3]
    steps:
      - run: very_good test --coverage --shard-index ${{ matrix.shard }} --total-shards 3
      - uses: actions/upload-artifact@v4
        with:
          name: coverage-${{ matrix.shard }}
          path: coverage/lcov.info

  coverage:
    needs: test
    steps:
      - uses: actions/download-artifact@v4
      - run: very_good test coverage merge coverage-*/lcov.info --min-coverage 100

The command name and placement are open for discussion. It could live under very_good test or as a new top-level command.

Things the merge has to get right:

• Union hits, don't average percentages. A line counts as covered when any shard hit it. For each source file, sum the per-line hit counts across reports and recompute totals from the merged lines.
• 0% records from --collect-coverage-from all must merge cleanly. A file one shard added at 0% and another shard actually covered should end up covered.
• Path consistency. Reports from different runners have to agree on each file's path. If SF: entries can be absolute and runners check out to different directories, paths need normalizing relative to the project root.
• Reuse the existing checks. --min-coverage, --exclude-coverage and --show-uncovered should behave exactly as they do in a normal run. CoverageMetrics.fromLcovRecords and MinCoverageNotMet in lib/src/cli/test_cli_runner.dart already do the parsing and reporting, so the merge only needs to feed them a combined set of records.
• Fall back to very_good.yaml. The merge step should pick up the threshold from very_good.yaml the same way very_good test does, which closes the silent-skip gap for sharded runs.
• Write the merged report to disk so it can still go to Codecov or be rendered with genhtml.

#804 asked for something close to this for multi-package apps run with -r, where each package writes its own lcov file. It was closed without a merge feature. The same merge logic would serve both cases, so it's worth designing with both in mind.

Requirements

• A command merges two or more lcov files into a single report.
• Hit counts are combined per file and per line, so a line covered in any input counts as covered.
• --min-coverage, --exclude-coverage and --show-uncovered work on the merged report and match the output of a normal very_good test run.
• The minimum coverage threshold falls back to very_good.yaml when the flag is not passed.
• The merged report is written to a configurable output path.
• The --min-coverage usage error added in feat(test): support sharding tests across CI runners #1707 points to the new command.
• Docs describe the sharded CI workflow from start to finish.
• All CI/CD checks are passing.
• There is no drop in the test coverage percentage.

Additional Context

• feat(test): support sharding tests across CI runners #1707: sharding PR that rejects --min-coverage and suggests merging reports
• feat: Support test sharding for CI parallelization with test_optimizer #1538: original sharding request
• feat: Include a command to generate a single coverage report for multi-package apps #804: earlier request for a single coverage report across multi-package runs