feat(tags): tag expressions (AND / NOT) and file-level @tags

[Chemaclass]

Problem

Tag selection is weaker than the systems people migrate from.

• --tag is repeatable but OR-only (bashunit test --help: "repeatable, OR logic"). There is no way to say "slow and db".
• There is no negation inside an expression; --exclude-tag is a separate flag that always wins.
• Tags are per function only. src/helper/tags.sh:10 build_tags_map scans the contiguous comment block directly above each function definition, so tagging a whole file means repeating # @tag integration above every test in it.

bats-core supports --filter-tags 'a,!b' with AND semantics and has both # bats test_tags= and # bats file_tags=.

Proposal

File-level tags — a # @tags <list> comment before the first function definition (or anywhere at top level) applies to every test in that file, unioned with per-function # @tag.

Tag expressions in --tag:

--tag slow              # has slow                     (unchanged)
--tag slow --tag db     # slow OR db                   (unchanged, back-compat)
--tag 'slow&&db'        # slow AND db
--tag '!slow'           # NOT slow
--tag 'db&&!slow'       # db AND NOT slow

Precedence stays as documented: --exclude-tag still wins over any --tag match.

Where to change

• src/helper/tags.sh:10 build_tags_map — single awk pass; extend it to also collect file-level tags and union them in.
• src/helper/tags.sh:99 function_matches_tags — the expression evaluator lives here.
• src/helper/tags.sh:74 tags_for_function.

Acceptance criteria

• # @tags a b above the first function applies both tags to every test in the file
• File-level and function-level tags union (no override, no duplicate match)
• --tag 'a&&b' selects only tests carrying both
• --tag '!a' selects only tests without a
• --tag 'a&&!b' works
• Repeated --tag flags keep OR semantics between them (no behaviour change for existing users)
• --exclude-tag still wins over an expression match
• A malformed expression ('a&&', '&&', '!') exits non-zero with a usage error, not a silent full-suite run (Unknown options are silently ignored: a typo'd flag runs a different suite and exits 0 #871 class of bug)
• The memoization in build_tags_map still holds — no per-function rescan (perf(tags): build per-file function-to-tags map in one pass instead of per-function grep/sed walk #773)
• Unit tests in tests/unit/helper/tags_test.sh, acceptance coverage for the CLI surface

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

All acceptance criteria met, on the Bash 3.2 floor.

Two things worth recording:

--tag 'slow&&' was accepted and silently evaluated as plain slow. Consuming the && emptied the remainder, so a while [ -n "$rest" ] loop ended before the empty trailing term was ever checked — exactly the #871 failure shape the criteria asked about, but narrowing the selection rather than widening it. Both the evaluator and the validator now consume one term per iteration and stop only after the last, so the empty term surfaces. My first acceptance test only covered '&&', which was caught; the trailing form needed its own case.

File tags are buffered to awk's END rather than printed at each function, so # @tags applies regardless of where it sits in the file. That surfaced an unrelated trap: an uninitialised awk variable used as a subscript is the empty string, not 0, so order[n] with n unset put the first function in an unreachable slot and dropped its tags. Two previously-passing tests caught it.

Mutation-tested: ignoring negation fails 7 tests, turning AND into OR fails 16, dropping file tags fails 6.