refactor(src): finish the module split — 9 large files still flat

[Chemaclass]

Summary

src/ is half-migrated. runner and coverage are module directories (#924, #925); the
other 37 files are still flat, and nine of them are large enough to deserve the same
treatment. Finish the migration, one module per PR.

Measured on main (7eecc45): 40 flat .sh files + 3 module directories, 15,614 lines total.

Convention: settled

The aggregator lives inside the module directory as index.sh:

src/runner/index.sh <- entry point
src/runner/exec.sh
src/coverage/index.sh
src/coverage/engine.sh

Decided and applied to both existing modules in #934; ADR-010 amended with the reasoning.
The original "beside" choice (src/runner.sh + src/runner/*.sh) rested on matching the
src/assertions.sh precedent, which does not apply — assertions.sh aggregates flat files
and has no directory. What settled it: the "aggregators hold only source lines" rule was
enforced against a hand-maintained list that had already drifted (#928 added src/coverage.sh
and never appended it), and a predictable src/*/index.sh lets that test discover modules by
glob instead.

Every new module in this issue uses index.sh. Do not mix placements.

What is left to split

File	Lines	Fns	Note
src/main.sh	1422	24	flag parsing + every subcommand's cmd_* in one file
src/learn.sh	1213	82	the interactive tutorial; self-contained, lowest risk
src/assert.sh	970	42	the core assertion catalogue — cohesive, may not want splitting
src/helpers.sh	909	30	discovery, fn filtering, provider map, duplicate check, ids
src/console_results.sh	828	27	totals rendering + deferred failure/skip blocks
src/env.sh	754	51	BASHUNIT_* defaults, config files, scratch dirs
src/test_doubles.sh	470	17	spies + mocks
src/reports.sh	434	18	JUnit/HTML/TAP/JSON writers — one per format is the obvious seam
src/state.sh	404	42	counters + payload encode/decode + TAP conversion

Separately, ~20 files under 120 lines (colors, str, math, io, globals,
check_os, dependencies, …) could group into a src/util/ module. Lower value than the
big files — grouping small cohesive files buys navigation, not comprehension. Treat as
optional and last.

Do not split all nine in one PR. One module per PR, same as #924 and #925, so each stays
reviewable as a pure relocation.

Per-module process (proven by #924 and #925)

1. Post a responsibility map on the issue and get it agreed before moving code: one-line
   summary per function, the internal call graph, every _BASHUNIT_* global with who assigns
   and who reads it, and a proposed acyclic layering. Generate it from the file, do not
   eyeball it.
2. Split. git diff must show only relocations — no renamed functions, no changed logic.
3. Verify (below), then open the PR.

Constraints — all of these have already drawn blood

• Aggregators may contain only source lines and comments. build::process_file emits a
  file's body and then recurses into its sources, so any statement in an aggregator runs
  before its dependencies in the built binary but after them in dev mode. Enforced by
  test_module_aggregators_hold_only_source_lines_and_comments.
• File-scope initialisers must move with their module, and order-dependent ones must stay
  contiguous. In refactor(coverage): split src/coverage.sh into a src/coverage/ module #928, _BASHUNIT_COVERAGE_XTRACE_PS4 expands $_BASHUNIT_COVERAGE_XTRACE_FS
  at file scope, and _NONEXEC_PATTERN is built across 7 successive lines. Grep for
  file-scope assignments that read another file-scope variable before splitting.
• .gitignore can silently swallow a new module directory. coverage/ was unanchored, so
  it matched src/coverage/ and excluded all twelve new files from git — git status showed
  no ?? entries at all. Fixed in refactor(coverage): split src/coverage.sh into a src/coverage/ module #928 by anchoring to /coverage/, but check
  git check-ignore -v src/<newmodule>/<file>.sh before committing any new module.
• CI runs ShellCheck per file without -x, so it cannot follow source. A monolith hides
  cross-file variable use; splitting exposes it as SC2034. In refactor(coverage): split src/coverage.sh into a src/coverage/ module #928 this surfaced a genuinely
  dead local. Reproduce CI's mode locally before pushing:
  for f in $(git ls-files '*.sh') bashunit; do shellcheck --format=gcc "$f"; done
  with SHELLCHECK_OPTS="-e SC1091 -e SC2155 -e SC2016".
• Check .editorconfig for per-file rules on the file being split. [src/coverage.sh] max_line_length = unset would have been lost by the split; refactor(coverage): split src/coverage.sh into a src/coverage/ module #928 rescoped it to the two
  files that actually needed it and reflowed the rest. Decide deliberately and state the
  decision in the PR.
• Dynamic-scope helper groups cannot be separated. Functions that mutate a caller's locals
  must land in the same file as their caller, with the justification comment
  (.claude/rules/bash-style.md). src/coverage/branches.sh is the precedent.
• Tests stay flat. make test globs exactly one level — never create tests/unit/<module>/.
• Bash 3.0+ floor; per-test paths stay fork-free (.claude/rules/perf-fork-budget.md).

Verification, per PR

Prove the change is a relocation by comparing the non-blank line multiset before and after —
it must differ only by the new shebangs and module header comments — plus an unchanged
function count:

git show main:src/<file>.sh | grep -vE '^[[:space:]]*$' | sort > /tmp/before.txt
cat src/<module>/*.sh | grep -vE '^[[:space:]]*$' | sort > /tmp/after.txt
comm -3 /tmp/before.txt /tmp/after.txt

Then: ./bashunit tests/ · ./bashunit --parallel tests/ ·
./bashunit --parallel --simple --strict tests/ · make sa · make lint ·
fork-budget acceptance tests · bash build.sh bin -v printing ✅ Build verified ✅.
Add ./bashunit --coverage --parallel tests/ when the module touches coverage.

Acceptance criteria (per module PR)

• Responsibility map posted and agreed before code moves
• git diff shows only relocations — no renamed functions, no changed logic
• Aggregator contains only source lines and comments
• Every new file's first line is #!/usr/bin/env bash
• git check-ignore -v confirms the new directory is not ignored
• CI-mode ShellCheck (per file, no -x) clean
• .editorconfig per-file rules reviewed; decision stated in the PR
• 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 start moving code before the responsibility map is posted
• Do not rename functions or change behaviour
• Do not split more than one module per PR
• Do not create tests/unit/<module>/
• Do not run shfmt -w; make lint is the format gate

Note on build.sh — no work needed

build.sh already handles arbitrary nesting. build::process_file is a depth-first walk of
source statements, not a directory walk: it emits a file's body, recurses into every
^source line, dedupes on repo-relative path (#923), and strips all source lines from the
artifact. Verified on main with a throwaway three-level module
(src/x.sh → src/x/mid.sh → src/x/deep/leaf.sh): all three bodies embedded in DFS order,
zero source lines left in the output. Depth is pinned by a regression test in a separate
issue.

[Chemaclass]

Responsibility map — src/reports.sh (first module)

Generated from the file on be37b72: 434 lines, 18 functions, 7 file-scope globals, 13 of
those functions called from outside.

Proposed layout — 6 files

File	Functions	~Lines
reports/index.sh	—	aggregator, source lines only
reports/collect.sh	the 7 _BASHUNIT_REPORTS_TEST_* arrays · is_enabled · add_test · add_test_{snapshot,incomplete,skipped,passed,risky,failed}	72
reports/junit.sh	__xml_escape · generate_junit_xml	72
reports/tap.sh	__tap_message · generate_report_tap	52
reports/json.sh	__json_escape · generate_report_json	56
reports/gha.sh	__gha_encode · print_gha_annotations · generate_gha_log	66
reports/html.sh	generate_report_html	116

Layering is acyclic

All 12 internal call edges:

collect.sh add_test_* -> add_test -> is_enabled (self-contained)
junit.sh generate_junit_xml -> __xml_escape
tap.sh generate_report_tap -> __tap_message
json.sh generate_report_json -> __json_escape
gha.sh generate_gha_log -> print_gha_annotations -> __gha_encode
html.sh (no internal calls)

No writer calls another writer. Every writer reads the collect.sh arrays and nothing else,
so the layering is collect -> {junit, tap, json, gha, html}, one level deep.

Each escaper is used by exactly one format (__xml_escape only by junit, __json_escape only
by json, __gha_encode only by gha, __tap_message only by tap), so each travels with its
format rather than into a shared helpers file.

Globals

All 7 are the parallel arrays backing the collected results, written by add_test and read by
every writer. They go to collect.sh together; none is order-dependent at file scope.

External surface (unchanged)

add_test* and is_enabled are called from src/runner/{exec,hooks,context}.sh; the five
generate_* entry points from src/main.sh. No renames.

Proceeding with the split.

[Chemaclass]

src/reports.sh done in #937 (merged) — 6 files under src/reports/ with an index.sh entry point. First module built to the amended convention from the start.

Remaining: main.sh (1422) · learn.sh (1213) · assert.sh (970, may not want splitting) · helpers.sh (909) · console_results.sh (828) · env.sh (754) · test_doubles.sh (470) · state.sh (404).

[Chemaclass]

Responsibility map — src/learn.sh (second module)

Generated from the file on 1878f1b.

Correction to the issue's own table: it lists learn.sh as 1213 lines, 82 fns. Only 20
are real functions — the other 62 are sample code inside heredocs (the tutorial's example
tests: set_up, test_valid_emails, data_provider_*, …), counted because they sit at
line-start inside heredoc bodies. Every heredoc is contained within a function body, so
splitting at function boundaries never cuts one.

Proposed layout — 15 files

File	Contents	~Lines
learn/index.sh	aggregator, source lines only	20
learn/progress.sh	LEARN_PROGRESS_FILE · mark_completed · is_completed · show_progress · reset_progress	65
learn/session.sh	LEARN_TEMP_DIR · init · cleanup · create_example_file · run_lesson_test	65
learn/menu.sh	print_menu · start	70
learn/lessons/basics.sh … challenge.sh	one file per lesson (10 files, 64–139 lines each)	1008

Layering is acyclic

All 37 internal call edges reduce to four levels:

progress <- session <- lessons (x10) <- menu

• every lesson calls exactly create_example_file and run_lesson_test, nothing else
• run_lesson_test -> mark_completed is the only session→progress edge
• show_progress -> is_completed is internal to progress
• start is the sole dispatcher (a case on the menu choice) and the only external entry
  point — src/main.sh calls bashunit::learn::start and nothing else

No lesson calls another lesson, so the ten are mutually independent and each is one file.

Why lessons/ as a subdirectory

Keeps the three plumbing files visible in src/learn/ instead of buried among ten curriculum
files, and makes adding a lesson a new file plus one source line and one case arm. This is
depth-3 (src/learn/lessons/basics.sh), which the build already supports and which #932 pinned
with a regression test — this is its first real use.

File-scope state

Two globals only: LEARN_TEMP_DIR (session) and declare -r LEARN_PROGRESS_FILE (progress).
Neither is order-dependent. The file-wide # shellcheck disable=SC2016 will be placed on the
files that actually need it, as in #937.

Proceeding with the split.

[Chemaclass]

src/learn.sh done in #938 (merged) — 15 files under src/learn/, including the first depth-3 use (src/learn/lessons/).

Note for whoever takes the next module: the function counts in the table above are grep -c '^function ', which over-counts any file containing heredocs with sample code. learn.sh was listed as 82 functions and had 20. Check before planning, and derive segment boundaries from the next function's start rather than a ^}$ closing brace — a brace inside a heredoc terminates the segment early and silently splits a function across files.

Remaining: main.sh (1422) · assert.sh (970, may not want splitting) · helpers.sh (909) · console_results.sh (828) · env.sh (754) · test_doubles.sh (470) · state.sh (404).