feat(cli): --list / --dry-run to show which tests would run

[Chemaclass]

Problem

There is no way to ask bashunit which tests it would run. Every selection mechanism — --filter, --tag, --exclude-tag, --shard i/n, --random-order --seed, --rerun-failed, file::fn, file:LINE — is only observable by actually running the suite.

Consequences today:

• --shard 1/4 cannot be checked for balance without four full runs.
• A typo'd --filter silently runs 0 tests and exits 1 with "No tests found" (src/console/summary.sh:128), indistinguishable from a genuinely empty suite.
• Editor/CI tooling has no machine-readable list of test ids.

bats-core has -c/--count, shellspec has --dry-run and --list examples.

Proposal

--list                    Print the tests that would run, then exit 0
--list-format <fmt>       text (default) | json
--dry-run                 Alias of --list (shellspec-compatible spelling)

• Honours every selection flag, applied in the same order as a real run, including shard slicing and --random-order --seed ordering.
• text output: one path/to/file_test.sh::test_function_name per line, followed by N tests on stderr.
• json output: {"count": N, "tests": [{"file": "...", "function": "...", "name": "human readable", "line": 12, "tags": ["slow"]}]}.
• No test body is executed, no bootstrap side effects beyond sourcing, no reports are written.
• Exit code 0 even when the list is empty (this is a query, not a run).

Where to change

• src/helper/discovery.sh:62 get_functions_to_run and :134 find_total_tests already do the selection work — the list command should reuse them rather than re-implement filtering.
• src/helper/tags.sh:99 function_matches_tags for the tag column.
• src/helper/discovery.sh:243 get_function_line_number for the line column.
• src/main/run.sh — branch before the runner loop.
• src/helper/naming.sh normalize_test_function_name for the human-readable name.

Acceptance criteria

• bashunit --list tests/ lists every test, one per line, and exits 0
• --list respects --filter, --tag, --exclude-tag, --shard, --rerun-failed, file::fn and file:LINE
• --list --random-order --seed 42 prints the same order that --random-order --seed 42 would execute
• --list-format json emits valid JSON (verify with jq) including file, function, name, line, tags
• Data-provider tests are listed once per test function (document the choice in the docs if a provider expands to N cases)
• No test body runs: a fixture whose test writes a marker file leaves no marker after --list
• Empty selection prints nothing and exits 0
• Acceptance test in tests/acceptance/bashunit_list_test.sh

Repo checklist (agent)

• TDD: RED → GREEN → REFACTOR. Write the failing test first.
• Bash 3.0+ only: no printf -v, no += append, no declare -A, no [[ ]], no ${var,,}, no &>>, no ${arr[-1]}. Expanding a possibly-empty array under set -u needs ${arr[@]+"${arr[@]}"}.
• A new CLI flag must be wired in all of these or a parity test fails:
  • parse in src/main/test.sh (report-style flags need export -n, see src/main/test.sh:188-196 for why)
  • validate the value in bashunit::main::validate_config_or_exit (src/main/validate.sh:60) — unvalidated input used to run the wrong thing and exit 0 (Unknown options are silently ignored: a typo'd flag runs a different suite and exits 0 #871, --jobs with a non-integer value hangs on Bash 3.x and is silently ignored on Bash 4.3+ #873)
  • default + env var in src/config/env.sh and a documented line in .env.example
  • --help text in the same block it belongs to
  • both completions/bashunit.bash and completions/_bashunit (anti-drift test feat(cli): bash and zsh completion scripts with an anti-drift test #778 fails otherwise)
• Gates: make sa, make lint, ./bashunit tests/, ./bashunit --parallel tests/. Never run shfmt -w.
• Docs: update docs/command-line.md. Editing docs/assertions.md invalidates the bashunit doc acceptance snapshot — regenerate it.
• CHANGELOG.md: add one line under ## Unreleased.
• Fixtures under tests/acceptance/fixtures/ must not end in *test.sh.
• One issue = one PR.

[Chemaclass]

Done in #1034 (merged).

--list / --dry-run print path::function per line on stdout with the count on stderr; --list-format json adds name, line and tags.

All acceptance criteria met. Two notes on how the guarantees are held rather than merely claimed:

• Order cannot drift. The per-file shuffle was extracted into runner::order_functions_for_script, which both the runner and the listing call. Making the listing re-derive its own order fails the seed-order test.
• No side effects. The interception sits after every selection step and before render_running_file_header and set_up_before_script. The fixture's script hook and test body both write the same marker, so its absence proves neither ran; moving the interception below the hooks fails 11 tests.

One thing worth recording: the first version of the seed-order test parsed rendered result lines (sed 's/\x1b...' plus grep -oE '^. Passed:'). That passed on macOS and failed on 17 CI jobs — \x1b is a GNU sed extension and the status glyph is multi-byte, so . matches a different amount under a non-UTF-8 locale. The fixture now records its own execution order to a file and the test compares orders directly, with a paired test asserting the seed actually reorders so the comparison cannot hold trivially.