generate-coverage: support crate exclusions / extra cargo args (workspace subsets cannot adopt the ratchet)

[leynos]

Problem

generate-coverage hard-codes cargo llvm-cov --workspace (see
get_cargo_coverage_cmd in run_rust.py) with no way to exclude
crates or pass extra cargo arguments. Workspaces whose test suite
cannot run as a bare --workspace build cannot adopt the action —
and therefore cannot use with-ratchet, which lives inside it.

Observed live during the CodeScene coverage rollout on
leynos/whitaker (whitaker#274): make test excludes eleven crates
(seven rustc_* proxy shims, the root crate, and three lint crates
whose dylint UI tests need per-target
-C prefer-dynamic -Z force-unstable-if-unmarked RUSTFLAGS). The
workaround is a Makefile coverage target that reuses the test
recipe with a TEST_RUNNER swap to llvm-cov nextest --lcov, plus
the standalone upload-codescene-coverage action — with the ratchet
left off.

Proposal

Add an extra-cargo-args (or exclude) input to generate-coverage
that is appended to the cargo llvm-cov invocation, so
exclusion-heavy workspaces can adopt the action and its ratchet.
Default behaviour unchanged.

Affected consumers

• leynos/whitaker (confirmed; see whitaker#274 for the workaround)
• any workspace whose CI-tested crate subset differs from
  --workspace (the mutation-testing rollout catalogued several:
  CI-excluded crates, path-dep fixtures, vendored patch crates).

Related: #335 (language-detection override) — same theme of
detect/command inflexibility blocking adoption.

[coderabbitai]

🔗 Related PRs

leynos/netsuke#410 - Adopt the Whitaker Dylint suite in the lint gate and CI [merged]
leynos/ddlint#287 - Wire the CodeScene coverage gate into CI [merged]
leynos/lag-complexity#72 - Wire CodeScene coverage upload on main and prepare the PR gate [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Summary

• Add a single free-form extra-cargo-args string input, reusing the cucumber-rs-args shlex.split precedent, that appends caller-supplied flags (including --exclude <crate>) to cargo llvm-cov.
• Thread the parsed tokens through the shared get_cargo_coverage_cmd, so both the primary and cucumber-rs invocations gain the flags from one change, with the default path a strict no-op.
• Validate the raw string at the main() boundary and convert malformed quoting into a clean typer.Exit(2), matching the pytest-workers pattern.
• Cover the addition with argv and end-to-end tests, and document it in the action's README and CHANGELOG as a minor, backward-compatible input.

Follow-up agent prompt:

Implement extra-cargo-args for the generate-coverage action. Add an optional
extra-cargo-args input to action.yml wired to INPUT_EXTRA_CARGO_ARGS; parse it in
run_rust.py's main() via a shlex.split helper that raises ValueError on bad
quoting (caught and converted to typer.Exit(2)); thread the token list through
get_cargo_coverage_cmd (inserted after --workspace/--features, before the
--<fmt> --output-path tail) so both the primary run and run_cucumber_rs_coverage
receive it. Keep the argv identical when the input is empty. Extend
tests/test_scripts.py with happy-path, no-op, and malformed-quote cases, and
update the action's README.md (Inputs table + example) and CHANGELOG.md
(Unreleased bullet). Use en-GB-oxendict spelling.

Design Choices

Design Choice 1: Which input shape to add: a single free-form `extra-cargo-args` string, or a dedicated `exclude` list input?

Options Considered:

1. A single extra-cargo-args free-form string, shlex.split and appended to the cargo llvm-cov argv (mirrors cucumber-rs-args). Covers --exclude, --exclude-from-report, --exclude-from-test, and any future flag.
2. A dedicated exclude input (comma/space/newline-separated crate list) expanded into repeated --exclude <crate> pairs (mirrors validate-linux-packages normalisation).

Chosen Option: 1

Rationale: The ticket offers both ("extra-cargo-args (or exclude)"). The distinction matters: whitaker#274 needs to exclude eleven crates, but the broader consumer catalogue also mentions vendored patch crates and path-dep fixtures that may need other cargo llvm-cov flags. A single extra-cargo-args string subsumes crate exclusion plus every other flag the affected consumers require, reuses the established cucumber-rs-args precedent with the least new surface area, and keeps the action flexible without a bespoke normaliser.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Thread extra-cargo-args through the Rust coverage command

Extend the single command-building path so the new flags reach both the primary and cucumber-rs cargo invocations, and validate the input at the CLI boundary. Because get_cargo_coverage_cmd is the sole builder shared by both call sites, extending it once covers every invocation.

Task 1: Add a validated parse helper for extra cargo args

Provide a pure helper that turns the raw string into a token list and fails cleanly on malformed quoting.

• Add a small parse helper in .github/actions/generate-coverage/scripts/run_rust.py that runs shlex.split on the raw extra-cargo-args string and raises ValueError on unterminated quotes, mirroring run_python.py's _parse_pytest_workers shape.
• Return an empty list for empty/whitespace-only input so the default path is a strict no-op.

Task 2: Splice extra args into `get_cargo_coverage_cmd`

Let the shared builder append the caller-supplied tokens without disturbing existing ordering.

• Extend get_cargo_coverage_cmd in run_rust.py with a new keyword-only parameter carrying the pre-parsed token list (default empty).
• Insert the tokens after the --workspace/--features block and before the --<fmt> --output-path tail, so --exclude <crate> and similar flags bind to cargo llvm-cov proper rather than the test binary.
• Keep the existing argv byte-for-byte identical when the token list is empty.

Task 3: Backfill and forward the input in `main()` and the cucumber path

Read the new input following existing conventions and forward it to every invocation.

• Add an extra_cargo_args typer.Option() parameter to main() in run_rust.py, backfilled via extra_cargo_args or os.getenv("INPUT_EXTRA_CARGO_ARGS", ""), matching the cucumber_rs_args idiom.
• Parse the raw string once via the Task 1.1 helper at the main() boundary, catching ValueError and emitting typer.echo(..., err=True) + raise typer.Exit(2) (consistent with pytest-workers and common._env_bool).
• Pass the parsed tokens into the primary get_cargo_coverage_cmd call and forward them into run_cucumber_rs_coverage, which threads them into its own internal get_cargo_coverage_cmd call so the cucumber sub-run receives identical scoping.

🤖 Prompt for AI agents

Implement the shared cargo command extension in
`.github/actions/generate-coverage/scripts/run_rust.py` so `extra-cargo-args`
flows into every `cargo llvm-cov` invocation. Goal: a single change to
`get_cargo_coverage_cmd` covers both the primary run and the cucumber-rs
sub-invocation.

- Add a parse helper that runs `shlex.split` on the raw `extra-cargo-args`
string, raises `ValueError` on unterminated quotes, and returns an empty list
for empty/whitespace-only input (mirror `run_python.py`'s
`_parse_pytest_workers` shape).
- Extend `get_cargo_coverage_cmd` with a new keyword-only parameter carrying the
pre-parsed token list (default empty). Insert the tokens after the
`--workspace`/`--features` block and before the `--<fmt> --output-path` tail.
Keep argv byte-for-byte identical when the token list is empty.
- Add an `extra_cargo_args` `typer.Option()` parameter to `main()`, backfilled
via `extra_cargo_args or os.getenv("INPUT_EXTRA_CARGO_ARGS", "")` (matching the
`cucumber_rs_args` idiom).
- Parse the raw string once at the `main()` boundary using the new helper; catch
`ValueError`, emit `typer.echo(..., err=True)`, then `raise typer.Exit(2)`
(consistent with `pytest-workers` and `common._env_bool`).
- Pass the parsed tokens into the primary `get_cargo_coverage_cmd` call and
forward them into `run_cucumber_rs_coverage`, threading them into its own
internal `get_cargo_coverage_cmd` call so the cucumber sub-run receives
identical scoping.

Phase 2: Expose the input on the action interface

Surface the new input at the composite-action boundary so callers can set it.

Declare and wire the `extra-cargo-args` input

Register the input and map it to the environment variable the script reads.

• Add an extra-cargo-args input (optional, no default) to the inputs: block of .github/actions/generate-coverage/action.yml, with a description noting it is appended verbatim to cargo llvm-cov (e.g. --exclude <crate>).
• Add INPUT_EXTRA_CARGO_ARGS: ${{ inputs.extra-cargo-args }} to the env: block of the id: rust step, mirroring the INPUT_CUCUMBER_RS_ARGS wiring.

🤖 Prompt for AI agents

Wire the new input onto the composite action interface in
`.github/actions/generate-coverage/action.yml`. Goal: make `extra-cargo-args`
settable by callers and route it to the script.

- Add an `extra-cargo-args` input (optional, no default) to the `inputs:` block,
with a description noting it is appended verbatim to `cargo llvm-cov` (e.g.
`--exclude <crate>`).
- Add `INPUT_EXTRA_CARGO_ARGS: ${{ inputs.extra-cargo-args }}` to the `env:`
block of the `id: rust` step, mirroring the existing `INPUT_CUCUMBER_RS_ARGS`
wiring.

Phase 3: Tests and documentation

Lock in the pass-through behaviour and record the addition per the action's conventions.

Task 1: Extend command-construction and end-to-end tests

Cover the happy path, the no-op default, and malformed input.

• Extend test_get_cargo_coverage_cmd_variants (or add a dedicated test) in .github/actions/generate-coverage/tests/test_scripts.py to assert the parsed tokens land in the correct argv position for a representative --exclude <crate> value, and that empty input leaves the argv unchanged.
• Add an end-to-end shell_stubs-based test (following test_run_rust_success) asserting the full argv includes the exclusion flags, and a cucumber variant confirming the second invocation also carries them.
• Add a malformed-input case (e.g. unterminated quote) asserting a clean typer.Exit(2) rather than a raw traceback.

Task 2: Update action documentation and changelog

Keep the action's own docs authoritative and record the minor bump.

• Add an extra-cargo-args row to the Inputs table in .github/actions/generate-coverage/README.md, plus a short example snippet demonstrating crate exclusion.
• Add a bullet under ## Unreleased in .github/actions/generate-coverage/CHANGELOG.md describing the new optional input and its unchanged default behaviour (a backward-compatible, additive change → minor bump).
• Leave the root README.md "Latest major" column untouched; an additive optional input does not change the major version.

🤖 Prompt for AI agents

Add test coverage and documentation for the `extra-cargo-args` addition. Goal:
lock in the pass-through behaviour and record it per the action's own
documentation conventions.

- Extend `test_get_cargo_coverage_cmd_variants` (or add a dedicated test) in
`.github/actions/generate-coverage/tests/test_scripts.py` to assert parsed
tokens land in the correct argv position for a representative `--exclude
<crate>` value, and that empty input leaves the argv unchanged.
- Add an end-to-end `shell_stubs`-based test (following `test_run_rust_success`)
asserting the full argv includes the exclusion flags, plus a cucumber variant
confirming the second invocation also carries them.
- Add a malformed-input case (e.g. unterminated quote) asserting a clean
`typer.Exit(2)` rather than a raw traceback.
- Add an `extra-cargo-args` row to the Inputs table in
`.github/actions/generate-coverage/README.md`, plus a short example snippet
demonstrating crate exclusion.
- Add a bullet under `## Unreleased` in
`.github/actions/generate-coverage/CHANGELOG.md` describing the new optional
input and its unchanged default behaviour (additive, backward-compatible → minor
bump).
- Leave the root `README.md` "Latest major" column untouched, since an additive
optional input does not change the major version.

Research

The generate-coverage composite action wires GitHub inputs into Python scripts via INPUT_<UPPER_SNAKE> environment variables. run_rust.py builds the coverage command in get_cargo_coverage_cmd, which unconditionally appends --workspace and is shared by both the primary main() run and the run_cucumber_rs_coverage sub-invocation. The cucumber-rs-args input already establishes the free-form "extra args" precedent (shlex.split, verbatim append), and run_python.py's pytest-workers handling establishes the CLI-boundary validation pattern (parse helper raising ValueError, caught in main() and converted to typer.Exit(2)). Tests in tests/test_scripts.py assert the cargo argv via plain list equality; documentation lives in the action's README.md and CHANGELOG.md.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the shared cargo command extension in
`.github/actions/generate-coverage/scripts/run_rust.py` so `extra-cargo-args`
flows into every `cargo llvm-cov` invocation. Goal: a single change to
`get_cargo_coverage_cmd` covers both the primary run and the cucumber-rs
sub-invocation.

- Add a parse helper that runs `shlex.split` on the raw `extra-cargo-args`
string, raises `ValueError` on unterminated quotes, and returns an empty list
for empty/whitespace-only input (mirror `run_python.py`'s
`_parse_pytest_workers` shape).
- Extend `get_cargo_coverage_cmd` with a new keyword-only parameter carrying the
pre-parsed token list (default empty). Insert the tokens after the
`--workspace`/`--features` block and before the `--<fmt> --output-path` tail.
Keep argv byte-for-byte identical when the token list is empty.
- Add an `extra_cargo_args` `typer.Option()` parameter to `main()`, backfilled
via `extra_cargo_args or os.getenv("INPUT_EXTRA_CARGO_ARGS", "")` (matching the
`cucumber_rs_args` idiom).
- Parse the raw string once at the `main()` boundary using the new helper; catch
`ValueError`, emit `typer.echo(..., err=True)`, then `raise typer.Exit(2)`
(consistent with `pytest-workers` and `common._env_bool`).
- Pass the parsed tokens into the primary `get_cargo_coverage_cmd` call and
forward them into `run_cucumber_rs_coverage`, threading them into its own
internal `get_cargo_coverage_cmd` call so the cucumber sub-run receives
identical scoping.
===============================================================================

Task: 2

Wire the new input onto the composite action interface in
`.github/actions/generate-coverage/action.yml`. Goal: make `extra-cargo-args`
settable by callers and route it to the script.

- Add an `extra-cargo-args` input (optional, no default) to the `inputs:` block,
with a description noting it is appended verbatim to `cargo llvm-cov` (e.g.
`--exclude <crate>`).
- Add `INPUT_EXTRA_CARGO_ARGS: ${{ inputs.extra-cargo-args }}` to the `env:`
block of the `id: rust` step, mirroring the existing `INPUT_CUCUMBER_RS_ARGS`
wiring.
===============================================================================

Task: 3

Add test coverage and documentation for the `extra-cargo-args` addition. Goal:
lock in the pass-through behaviour and record it per the action's own
documentation conventions.

- Extend `test_get_cargo_coverage_cmd_variants` (or add a dedicated test) in
`.github/actions/generate-coverage/tests/test_scripts.py` to assert parsed
tokens land in the correct argv position for a representative `--exclude
<crate>` value, and that empty input leaves the argv unchanged.
- Add an end-to-end `shell_stubs`-based test (following `test_run_rust_success`)
asserting the full argv includes the exclusion flags, plus a cucumber variant
confirming the second invocation also carries them.
- Add a malformed-input case (e.g. unterminated quote) asserting a clean
`typer.Exit(2)` rather than a raw traceback.
- Add an `extra-cargo-args` row to the Inputs table in
`.github/actions/generate-coverage/README.md`, plus a short example snippet
demonstrating crate exclusion.
- Add a bullet under `## Unreleased` in
`.github/actions/generate-coverage/CHANGELOG.md` describing the new optional
input and its unchanged default behaviour (additive, backward-compatible → minor
bump).
- Leave the root `README.md` "Latest major" column untouched, since an additive
optional input does not change the major version.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!