refactor(src): group the remaining flat files into modules (system, util, api, config, benchmark)

[Chemaclass]

Summary

After #931 and #940, src/ is 11 modules plus 15 loose files. Individually each is small
and well named; as a listing they read as leftovers, and the root stops communicating
structure. Directories convey layering, a flat pile does not.

Group the rest so that src/ holds modules and nothing else (bar main.sh, see below).

Measured on main (8f2a1c3).

Groups

Each is backed by a real dependency cluster, not name similarity.

src/system/ — what this machine has

check_os.sh (107, leaf) · dependencies.sh (42, leaf) · io.sh (31 → dependencies) ·
clock.sh (203 → check_os, dependencies, math) — 383 lines

The true bottom layer. Nothing in it touches test state, config, console or runner.

src/util/ — pure computation

str.sh (156, leaf) · math.sh (104 → dependencies) — 260 lines

One outbound edge (math → dependencies) which just places util above system. Acyclic.

src/api/ — the test-authoring surface

globals.sh (109, leaf) · skip_todo.sh (21) · test_title.sh (5) · bashunit.sh (53) —
188 lines

What a user's test file calls: temp_file/temp_dir/current_dir/data_set, skip/todo,
set_test_title, and the custom-assert facade (assert_that, assert_once,
assertion_failed).

Assertions are the other half of this surface and stay in src/assert/, which at 11 files and
2300 lines has earned its own module. The api/index.sh comment must say so, or the split
looks arbitrary.

src/config/ — run-scoped configuration and persisted state

env.sh (754) · parallel.sh (63) · rerun.sh (124) — 941 lines

Not a junk drawer; there are real internal edges. env → rerun, parallel → env, and
rerun::is_enabled is called from env.sh. parallel::is_enabled is called from 11 files
across runner, coverage, console and main — a cross-cutting mode predicate, the same shape as
env.sh's 33 is_* predicates.

Note src/parallel.sh is a different concern from src/runner/parallel.sh (job-slot waiting
and the spinner, runner-internal). Same basename, different jobs — the collision #923 fixed
the build for.

env.sh is not split here; #931 recorded it as deliberately whole (51 functions but one
concern). It just moves.

src/benchmark/ — the weakest of the set, stated plainly

benchmark.sh (191, 5 functions) → annotations.sh / run.sh / report.sh

It is a distinct feature — runner/bench.sh is the file/function loop, this is the
implementation (annotation parsing, running, result printing). But three files of ~60 lines is
thin, and this is the one group where "everything in modules" costs ceremony to buy
consistency. Accept it or leave benchmark.sh flat; decide deliberately and say which.

main.sh

Stays at the root of src/ for now. Splitting it is #948, and whether it becomes src/main/
or remains a root dispatcher is that issue's call. Renaming it to index.sh is explicitly
out of scope here and should follow this work, not precede it — see the note on #948.

Process

One group per PR, same as #931 and #940:

1. Post the mapping on this issue before moving code.
2. git mv so renames are recorded as renames.
3. index.sh aggregator, entrypoint source line updated.
4. Grep for hardcoded paths before committing.

Suggested order: system → util → api → config → benchmark. System first because
everything sits on it; api third because its naming deserves a second look before it is
cemented.

Constraints

All of ADR-010's, every one of which has drawn blood at least once:

• Aggregator holds only source lines and comments.
• Derive segment boundaries from the next function's start, never a ^}$ brace (refactor(learn): split src/learn.sh into a src/learn/ module #938).
• git check-ignore -v the new directory before committing (refactor(coverage): split src/coverage.sh into a src/coverage/ module #928 hid twelve files).
• CI runs ShellCheck per file without -x; reproduce with
  SHELLCHECK_OPTS="-e SC1091 -e SC2155 -e SC2016".
• A file-wide # shellcheck disable= moves only to files that need it — and check whether it
  is stale first (refactor(coverage): split src/coverage.sh into a src/coverage/ module #928 and refactor(console): split results.sh into six single-purpose files #947 both found dead ones).
• Per-file .editorconfig rules are lost by a move (refactor(console): group the rendering files into a src/console/ module #942 carried one for console_header.sh).
• Grep for hardcoded paths in tests/ before committing. refactor(learn): split src/learn.sh into a src/learn/ module #938 shipped 14 red tests from
  one; refactor(state): split src/state.sh into a src/state/ module #946 found a layering contract that passed while checking nothing because its grep
  target had moved.
• Bash 3.0+ floor; per-test paths stay fork-free.

Verification, per PR

Relocation proof: non-blank line multiset differs only by new shebangs, module headers and
source lines; function count unchanged; the built artifact's sorted code content identical.

Then ./bashunit tests/ · --parallel · --parallel --simple --strict · make sa ·
make lint · CI-mode ShellCheck · bash build.sh bin -v printing ✅ Build verified ✅.

Acceptance criteria (per group PR)

• Mapping posted here before code moves
• git diff shows only relocations — no renamed functions, no changed logic
• Aggregator is src/<group>/index.sh, only source lines and comments
• Hardcoded path references updated (grep tests/ build.sh Makefile .github/ .editorconfig .gitignore)
• git check-ignore -v confirms the directory is not ignored
• All suites green, including bash build.sh bin -v
• .claude/rules/architecture-map.md updated
• No CHANGELOG entry — internal, no user-visible behaviour change

Do not

• Do not rename functions; only file paths change
• Do not split env.sh — refactor(src): finish the module split — 9 large files still flat #931 settled that
• Do not group more than one context per PR
• Do not touch main.sh here
• Do not run shfmt -w; make lint is the format gate

[Chemaclass]

Mapping — src/system/ and src/util/ (correction to the issue body)

The issue put clock.sh in system/. That creates a cross-module cycle:

system/clock.sh -> util/math.sh -> system/dependencies.sh

Harmless at load time — both crossings are inside function bodies, and clock.sh's only
file-scope statements are two variable initialisers — but a module cycle is a smell worth not
shipping. Cutting one file differently removes it:

Module	Files	Lines	Rule
src/system/	check_os.sh · dependencies.sh · io.sh	180	what does this machine have — capability probing
src/util/	str.sh · math.sh · clock.sh	463	compute something — strings, arithmetic, time

util -> system in one direction only (math and clock both probe via dependencies).
Acyclic.

clock.sh reads as a utility — its job is "tell me the time"; it probes the platform the same
way math.sh probes for bc/awk, which is a reason to sit beside it rather than inside the
probing layer.

Callers that move with them

• build.sh:4-5 sources src/check_os.sh and calls check_os::init directly, before it
  sets BASHUNIT_ROOT_DIR — so it must point at the file, not the module index.
• tests/unit/check_os_test.sh:88 sources it relative to the test file.

Proceeding with system/ first.

[Chemaclass]

All five groups merged: system/ #950 · util/ #951 · api/ #952 · config/ #953 · benchmark/ #954.

src/ now holds 16 modules and main.sh — nothing else. Splitting main.sh is #948.