refactor(src): group cohesive flat files into modules (assert, console, util)

[Chemaclass]

Summary

#931 splits large files into modules. This is the other half: src/ still holds 36 flat
files, many of them small and clearly belonging to the same concept. Ten of them are
assert_*.sh. Group by context so a directory names a concept, following ADR-010's
index.sh convention.

Measured on main (c8b0b53).

Group 1 — src/assert/ (highest confidence, do first)

Ten files, 2313 lines, already aggregated together by src/assertions.sh. The concept is
established; only the directory is missing.

Now	Becomes
src/assertions.sh	src/assert/index.sh
src/assert.sh (970)	src/assert/core.sh
src/assert_arrays.sh (101)	src/assert/arrays.sh
src/assert_assertions.sh (192)	src/assert/assertions.sh
src/assert_dates.sh (185)	src/assert/dates.sh
src/assert_duration.sh (69)	src/assert/duration.sh
src/assert_files.sh (156)	src/assert/files.sh
src/assert_folders.sh (118)	src/assert/folders.sh
src/assert_json.sh (67)	src/assert/json.sh
src/assert_once.sh (156)	src/assert/once.sh
src/assert_snapshot.sh (299)	src/assert/snapshot.sh

Drop the assert_ prefix inside the directory — it carries the concept, as
learn/lessons/basics.sh does. Function names do not change; only file names.

Two callers hardcode these paths and must move with them:

• tests/unit/completions_test.sh:30 greps src/assert*.sh to derive the public assertion
  list for the completions parity contract → becomes src/assert/*.sh.
• tests/unit/build_test.sh special-cases src/assertions.sh as "the one flat-file
  aggregator" outside the src/*/index.sh glob. That special case disappears — a welcome
  simplification, and the reason ADR-010's original "beside" argument was withdrawn.

src/assertions.sh also sources skip_todo.sh and test_doubles.sh, which are not
assertions (skip/todo markers; spies and mocks). Leave both flat in this group, or handle
them in group 4 — do not sweep them into src/assert/ just because the aggregator lists them.

Group 2 — src/console/ (high confidence)

Output rendering, 1220 lines:

• src/colors.sh (57) → src/console/colors.sh
• src/console_header.sh (335) → src/console/header.sh
• src/console_results.sh (828) → src/console/results.sh

console_results.sh is also on #931's list at 828 lines. Prefer grouping first, splitting
second: move it into src/console/ here, then split it inside the module under #931 if
still warranted.

Group 3 — src/cli/ (high confidence)

The subcommand implementations, ~430 lines. main.sh is the only caller of all four,
and each is literally a bashunit <subcommand> implementation:

• src/upgrade.sh (54) → src/cli/upgrade.sh
• src/watch.sh (112) → src/cli/watch.sh
• src/doc.sh (198) → src/cli/doc.sh
• src/init.sh (66) → src/cli/init.sh

benchmark.sh looks like it belongs but src/runner/bench.sh also calls it, so it is a
shared implementation rather than purely a subcommand — it stays flat. main.sh is the
dispatcher and needs its own split under #931 first; grouping it now would only relocate a
1427-line file.

Zero hardcoded path references to any of the four.

Won't do: src/util/ and src/system/

Considered and declined, recorded here so it is not re-litigated.

The candidates were str (156), math (104), io (31), check_os (107),
dependencies (42), clock (203) — 2 to 10 functions each. These are the most obviously
named files in the repo; nobody has struggled to find math.sh. Wrapping them costs an
index.sh, a source line and a directory hop, and buys navigation for files that were
never hard to navigate. A two-file util/ is not a module, it is ceremony.

ADR-010's rationale is a directory for something with internal structure. A 31-line file
has none.

The effort is better spent on helpers.sh (909 lines, 30 functions, six unrelated concerns:
test-function naming, discovery, data providers, tags, base64 encoding, misc). That is a
cohesion problem, tracked on #931.

Explicitly stays flat

Not everything benefits from a directory. These are single-concept files or cross-cutting
state, and grouping them would invent a concept that does not exist:

bashunit.sh (public custom-assert facade) · globals.sh (public test API) · env.sh ·
state.sh · helpers.sh · clock.sh · parallel.sh · rerun.sh · test_title.sh

main.sh (1427) and the subcommand files (doc, init, upgrade, watch, benchmark)
look like a src/cli/ group, but main.sh needs its own split under #931 first — grouping it
now would just move a 1427-line file. Out of scope here.

Process

Same as #931, and one group per PR:

1. Post the mapping on this issue before moving code.
2. git mv so the rename is recorded as a rename, not add+delete.
3. Update the aggregator to index.sh and the entrypoint's source line.
4. Grep for hardcoded paths before committing — tests/, build.sh, Makefile,
   .github/, .editorconfig, .gitignore. refactor(learn): split src/learn.sh into a src/learn/ module #938 shipped 14 red tests from one hardcoded
   src/learn.sh in a test file.

Constraints (all learned the hard way)

• Aggregators hold only source lines and comments — enforced by
  test_module_aggregators_hold_only_source_lines_and_comments, which globs src/*/index.sh.
• .gitignore can swallow a new module directory. coverage/ was unanchored and hid
  twelve files from git with no ?? in git status. Run
  git check-ignore -v src/<module>/<file>.sh before committing.
• CI runs ShellCheck per file without -x, so a split exposes cross-file symbol use a
  monolith hid. Reproduce locally with SHELLCHECK_OPTS="-e SC1091 -e SC2155 -e SC2016".
• A file-wide # shellcheck disable= moves to the files that need it, not to all of them.
• Per-file .editorconfig rules are lost by a split — check before, decide deliberately.
• Derive segment boundaries from the next function's start, not a ^}$ brace. A brace
  inside a heredoc ends the segment early and silently splits a function across files (refactor(learn): split src/learn.sh into a src/learn/ module #938).
• Bash 3.0+ floor; per-test paths stay fork-free.

Verification, per PR

Prove it is a relocation: the non-blank line multiset differs only by new shebangs, module
headers and source lines, and the function count is unchanged. Then the built artifact —
either byte-identical, or its sorted code content identical when grouping reorders
definitions (safe: everything is sourced before anything is invoked).

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 on this issue before code moves
• git diff shows only relocations — no renamed functions, no changed logic
• Aggregator is src/<group>/index.sh and holds only source lines and comments
• Every new file's first line is #!/usr/bin/env bash
• Hardcoded path references updated (grep tests/ build.sh Makefile .github/)
• git check-ignore -v confirms the new directory is not ignored
• All suites above green, including bash build.sh bin -v
• .claude/rules/architecture-map.md module table updated
• No CHANGELOG entry — internal, no user-visible behaviour change

Do not

• Do not rename functions; only file paths change
• Do not group more than one context per PR
• Do not fold skip_todo.sh / test_doubles.sh into src/assert/
• Do not group main.sh — it needs its own split under refactor(src): finish the module split — 9 large files still flat #931 first
• Do not create tests/unit/<group>/; make test globs one level
• Do not run shfmt -w; make lint is the format gate

[Chemaclass]

Mapping — Group 1 src/assert/

Generated on c8b0b53. Eleven files, 2313 lines, already aggregated together by
src/assertions.sh — the concept exists, only the directory is missing.

Now	Becomes	Lines
src/assertions.sh	src/assert/index.sh	14
src/assert.sh	src/assert/core.sh	970
src/assert_arrays.sh	src/assert/arrays.sh	101
src/assert_assertions.sh	src/assert/assertions.sh	192
src/assert_dates.sh	src/assert/dates.sh	185
src/assert_duration.sh	src/assert/duration.sh	69
src/assert_files.sh	src/assert/files.sh	156
src/assert_folders.sh	src/assert/folders.sh	118
src/assert_json.sh	src/assert/json.sh	67
src/assert_once.sh	src/assert/once.sh	156
src/assert_snapshot.sh	src/assert/snapshot.sh	299

Pure git mv plus the aggregator and entrypoint lines. No function renames — only file
paths change, so the diff is renames only.

skip_todo.sh and test_doubles.sh stay flat: they are sourced by the aggregator but are not
assertions. The index.sh keeps sourcing them from their current location, exactly as
assertions.sh does today.

Callers that move with it

• tests/unit/completions_test.sh:30 derives the public assertion list from src/assert*.sh
  for the completions parity contract → src/assert/*.sh.
• tests/unit/build_test.sh special-cases src/assertions.sh as the one flat-file aggregator
  outside the src/*/index.sh glob. That special case is deleted — the glob now covers it,
  which is the simplification ADR-010 predicted.

Proceeding.

[Chemaclass]

Group 1 (src/assert/) done in #941 (merged). All ten files recorded as pure renames with a zero-line diff; the src/assertions.sh special case in build_test.sh is deleted now that every aggregator is an index.sh.

Next: Group 2 src/console/ (colors + console_header + console_results), then Group 3 src/util/.

[Chemaclass]

All three groups merged:

• Group 1 src/assert/ — refactor(assert): group the assert_*.sh files into a src/assert/ module #941
• Group 2 src/console/ — refactor(console): group the rendering files into a src/console/ module #942
• Group 3 src/cli/ — refactor(cli): group the subcommand files into a src/cli/ module #943

src/util/ and src/system/ were considered and declined; the reasoning is recorded in the issue body so it is not re-litigated. The effort goes to helpers.sh on #931 instead, which is a cohesion problem rather than a size one.

src/ is now 8 modules plus 17 single-concept flat files, down from 40 flat files.