refactor(tests): mirror the src/ module layout in tests/unit/

[Chemaclass]

Summary

src/ is now 17 modules with no loose files (#931, #940, #948, #949, ADR-011). tests/unit/
is still 71 flat files — assert_advanced_test.sh, coverage_engine_test.sh,
runner_exec_test.sh, … — with the module encoded in a filename prefix rather than in the
tree.

Mirror the source layout, the way PHPUnit projects mirror src/ into tests/:

src/coverage/engine.sh -> tests/unit/coverage/engine_test.sh
src/runner/exec.sh -> tests/unit/runner/exec_test.sh

Finding the tests for a module becomes ls tests/unit/<module>/ instead of remembering a
prefix convention.

Blocker: make test only globs one level

This must be fixed first, in its own PR, or tests silently stop running.

Makefile:67:

TEST_SCRIPTS = $(wildcard $(TEST_SCRIPTS_DIR)/*/*[tT]est.sh)

That matches tests/<dir>/<name>_test.sh and nothing deeper. Nest a test and make test
skips it and stays green — and make test is its own CI matrix entry plus the Linux and
macOS jobs.

./bashunit tests/ already recurses (verified: it finds unit/sub/deep_test.sh), so the other
three matrix entries would keep running everything. The two would silently disagree.

The fix is not simply "make the glob recursive"

A naive recursive glob sweeps in four fixture files that are inputs to other tests, not
tests:

tests/acceptance/fixtures/tests_path/a_test.sh
tests/acceptance/fixtures/tests_path/other_test.sh
tests/unit/fixtures/tests/example1_test.sh
tests/unit/fixtures/tests/example2_test.sh

(156 files today, 160 with a naive recursive glob.)

So:

TEST_SCRIPTS = $(shell find $(TEST_SCRIPTS_DIR) -name '*[tT]est.sh' -not -path '*/fixtures/*')

and a guard test asserting make test's collected list equals the set of real test files —
otherwise this regresses silently the next time someone nests a directory.

Proposed layout

One directory per source module, same names:

tests/unit/<dir>/	Files today	From
assert/	12	assert_* (10), directory_test, file_test
coverage/	9	coverage_*
runner/	6	runner_* (5), setup_teardown_test
cli/	5	watch* (3), doc_test, upgrade_test
config/	4	env_test, env_deprecated_aliases_test, parallel_test, rerun_test
api/	4	globals_test, skip_todo_test, test_title_test, custom_assertions_test
console/	4	console_* (3), colors_test
helper/	3	helpers*
system/	3	check_os_test, dependencies_test, io_test
util/	3	clock_test, math_test, str_test
reports/	2	reports_test, reports_json_test
doubles/	1	test_doubles_test
state/	1	state_test
main/	2	main_test, completions_test
learn/	1	learn_test
benchmark/	1	benchmark_test

The remainder does not mirror src/, and should not pretend to

Ten files test the project's own tooling and invariants, not a source module:

• release_generation · release_sandbox · release_update · release_utilities ·
  release_validation — cover tools/release.sh; zero src/ references
• package_json_test — covers package.json
• build_test — covers build.sh
• bash_version_test — covers the entrypoint's version gate
• bash_compatibility_test — greps all of src/, belongs to no single module
• redirect_error_test — behavioural, no single owner

Proposal: tests/unit/project/. Naming it something honest beats forcing it under a module
name that would be a lie.

Phasing

1. Makefile + guard test. Recursive collection excluding fixtures/, plus the test that
   keeps it honest. No files move. This PR is a prerequisite for every one below.
2. One PR per module directory, largest first (assert/, coverage/, runner/, …).
3. tests/unit/project/ last, once only the remainder is left flat.

tests/functional/ and tests/acceptance/ stay flat for now — they are organised by scenario
rather than by source module, so the mirror argument does not apply. Revisit separately if it
ever does.

The verification that matters

The reported test total must not change. Before and after each PR:

./bashunit tests/ # Tests: N passed ... T total
make test # must collect the same set

If a file stops being collected, T drops. That single number is the safety net against the
silent-skip failure this whole issue is designed around — check it on every PR, not just the
first.

Also per PR: make sa · make lint · ./bashunit --parallel --simple --strict tests/ ·
bash build.sh bin -v.

Constraints

• Fixtures must never be collected as tests. They live under fixtures/ and are excluded
  by path. Fixture files are also named test_*.sh (prefix) rather than *_test.sh (suffix)
  precisely so the old glob missed them — keep both guards.
• Tests reference fixtures by relative path ($(bashunit::current_dir)/fixtures/...). Moving a
  test one directory deeper breaks those paths. Grep each file for current_dir,
  BASH_SOURCE and fixtures/ before moving it.
• Several tests reach into src/ by path — tests/unit/build_test.sh,
  tests/unit/state_test.sh, tests/unit/completions_test.sh,
  tests/unit/env_deprecated_aliases_test.sh, tests/unit/helpers_test.sh,
  tests/unit/check_os_test.sh. Those paths are repo-relative, so moving the test does not
  break them — but confirm rather than assume.
• Do not rename test functions; only file paths change.

Acceptance criteria (per PR)

• ./bashunit tests/ reports the same total as before the change
• make test collects the same set as ./bashunit tests/
• No fixture is collected as a test
• Fixture-relative paths inside moved tests still resolve
• make sa && make lint green
• ./bashunit --parallel --simple --strict tests/ green
• bash build.sh bin -v prints ✅ Build verified ✅
• No CHANGELOG entry — internal, no user-visible behaviour change

Do not

• Do not move any test before the Makefile PR lands
• Do not make the glob recursive without excluding fixtures/
• Do not create tests/unit/<module>/<submodule>/ — one level of mirroring is the goal
• Do not rename test functions

[Chemaclass]

Phase 1 done in #958 (merged). make test now collects recursively, excluding fixtures/, guarded by tests/unit/project/collection_test.sh — itself nested, so the old glob would not have found it.

Worth recording for the phases that follow: the guard failed CI on its first run in a way that is easy to hit again. Running from inside make test, its sub-make inherited MAKEFLAGS and wrapped the output in make[1]: Entering/Leaving directory, so a positional tail -n +2 stripped the wrong line. Exactly the four make-driven jobs failed while every ./bashunit tests/ job passed. Parse make output by content (grep '^tests/'), never by line position, and clear MAKEFLAGS.

Moving files is now unblocked.