feat(api): conditional skip helpers (skip_if, skip_unless_command, skip_on)

[Chemaclass]

Problem

Conditional skipping is manual and easy to get wrong. bashunit::skip (src/api/skip_todo.sh:3) marks the test skipped but does not stop the test body — the author has to remember && return.

bashunit's own suite shows the cost: 32 test files repeat this shape.

# tests/unit/assert/files_test.sh:197
if bashunit::check_os::is_windows; then
  bashunit::skip && return
fi

# tests/unit/util/math_test.sh:42
bashunit::skip "bc not available"

Two failure modes: forget return and the test keeps running (on a platform where it cannot pass), or forget the guard entirely and the suite is red on someone else's machine. Neither is caught by any linter.

Proposal

Three helpers, each of which marks the test skipped and returns from the caller:

bashunit::skip_if <condition-command> [reason]   # skips when the command succeeds
bashunit::skip_unless <condition-command> [reason]
bashunit::skip_unless_command <cmd> [<cmd>…]     # reason defaults to "requires <cmd>"
bashunit::skip_on <os> [reason]                  # windows | macos | linux

Usage:

function test_permissions() {
  bashunit::skip_on windows "Git Bash fakes file permissions"
  assert_file_permissions 644 "$file"
}

function test_math() {
  bashunit::skip_unless_command bc
  assert_equals 4 "$(calc 2+2)"
}

The "returns from the caller" part is the whole point and is the tricky bit in Bash 3.0 — a function cannot return on behalf of its caller. Look at how bashunit::runner::execute_test_hook (src/runner/hooks.sh:200) already solves early-exit with a FUNCNAME-guarded trap; reuse that mechanism rather than inventing a second one. If a trap-based approach is rejected, the fallback is to keep && return at the call site but have the helpers return a status that makes the idiom unambiguous — document whichever is chosen.

src/system/check_os.sh already provides is_windows / is_macos / is_linux for skip_on.

Acceptance criteria

• bashunit::skip_if true "reason" marks the test skipped and the rest of the body does not run
• bashunit::skip_if false does not skip and the body runs to completion
• bashunit::skip_unless_command definitely_not_a_command skips with reason requires definitely_not_a_command
• bashunit::skip_unless_command bash does not skip
• bashunit::skip_on windows skips only on Windows; macos, linux likewise
• An unknown OS name is a usage error, not a silent no-skip
• The reason appears in the console output and in the reports, like today's bashunit::skip
• Skipped counters increment exactly once
• Works inside a data-provider test and under --parallel
• Existing bashunit::skip / bashunit::todo behaviour is unchanged
• At least a few of the 32 boilerplate sites in tests/ are migrated in the same PR to prove the ergonomics
• Documented in docs/skipping-incomplete.md and docs/globals.md

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 #1065 (merged).