feat(config): named suites in .bashunitrc and --suite <name>

[Chemaclass]

Problem

A project with more than one tier of tests has no way to name those tiers. bashunit's own repo is the example: tests/unit, tests/functional, tests/acceptance, tests/benchmark, each wanting different options — and the way you select between them is a Makefile plus remembered flags.

.bashunitrc already exists (src/config/env.sh:82 load_config_file), but it only sets global defaults. There is no way to express "the unit suite is this path with these options".

Proposal

Named suites in .bashunitrc, plus a flag to select one:

[suite:unit]
paths = tests/unit
parallel = true

[suite:acceptance]
paths = tests/acceptance
parallel = false
test_timeout = 60

[suite:ci]
paths = tests/unit tests/functional
tags = !slow

--suite <name> Run a named suite from .bashunitrc (repeatable)
--list-suites Print the defined suite names and exit

Precedence, to be documented and tested: CLI flags > suite settings > global .bashunitrc settings > .env > built-in defaults.

The exact file syntax is open — pick whatever parses cleanly in Bash 3.0 without declare -A and stays consistent with how .bashunitrc reads today. INI-style sections are the suggestion, not a requirement.

Where to change

• src/config/env.sh:82 load_config_file and the surrounding precedence chain.
• src/main/test.sh, src/main/validate.sh:60.

Acceptance criteria

• --suite unit runs only that suite's paths with its options
• Repeated --suite a --suite b runs the union of their paths
• An explicit CLI flag beats the suite setting for the same option
• An unknown suite name exits non-zero listing the defined suites
• --list-suites prints the names and exits 0
• A path argument together with --suite is either an error or documented precedence — decide, document, test
• .bashunitrc with no suite sections behaves exactly as today
• A malformed suite section exits non-zero with the offending line quoted
• Bash 3.0 compatible parsing (no declare -A)
• bashunit's own Makefile targets are migrated to --suite in the same PR as the dogfood proof
• Documented in docs/configuration.md; acceptance coverage alongside tests/acceptance/bashunit_bashunitrc_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 #1067 (merged).