refactor(runner): split src/runner.sh into a src/runner/ module#927

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Chemaclass merged 2 commits into from
Jul 30, 2026
Merged

refactor(runner): split src/runner.sh into a src/runner/ module #927

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0567a48
refactor(runner): split src/runner.sh into a src/runner/ module
Chemaclass Jul 30, 2026
56ab0c6
docs: update changelog
Chemaclass Jul 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 12 additions & 2 deletions .claude/rules/architecture-map.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -14,7 +14,7 @@ flow of a test run. Line numbers drift; function names are the stable anchors.
```
bashunit (entry) sources all src/*.sh; version gate; early flag scan
└─ bashunit::main::cmd_test (main.sh: flag parsing, env exports)
└─ bashunit::runner::load_test_files (runner.sh: the per-file loop)
└─ bashunit::runner::load_test_files (runner/discovery.sh: the per-file loop)
├─ console_header::print_header "Running N tests" — captures
│ └─ helper::find_total_tests $() SUBSHELL: sources each file in a
│ nested subshell just to count tests
Expand DownExpand Up@@ -48,7 +48,17 @@ shell (or, in parallel, in per-test `.result` files aggregated at the end).
| Module | Owns |
|--------|------|
| `bashunit` + `main.sh` | entry, subcommand routing, flag parsing, run lifecycle, exit codes, cleanup calls |
| `runner.sh` | file loop, per-test execution, retry/timeout, result parsing, failure context |
| `runner.sh` | aggregator only — sources the `src/runner/` module below |
| `runner/context.sh` | workdir restore, test identity/location exports, title interpolation, capability probes |
| `runner/payload.sh` | the `_BASHUNIT_RUNNER_*_OUT` return slots; encode/decode of the per-test result payload |
| `runner/diagnostics.sh` | runtime-error detection, kill-signal classification, profiling, verbose/file headers |
| `runner/result.sh` | `parse_result{,_sync,_parallel}`, failure source context, failed/skipped/incomplete/risky writers |
| `runner/parallel.sh` | job-slot waiting (`wait -n` or poll), running-job count, spinner |
| `runner/hooks.sh` | set_up/tear_down (test + script scope), hook failure records, mock clearing, EXIT cleanup |
| `runner/provider.sh` | `@data_provider` argument parsing |
| `runner/exec.sh` | `run_test`, the capture-subshell body, retry, timeout watchdog, per-file dispatch |
| `runner/discovery.sh` | `load_test_files` (the per-file loop), `functions_for_script` |
| `runner/bench.sh` | benchmark file loop and bench function dispatch |
| `helpers.sh` | discovery (`find_files_recursive`), fn filtering, provider map, duplicate check, ids |
| `state.sh` | counters, per-test payload encode/decode, TAP conversion |
| `env.sh` | all `BASHUNIT_*` defaults/config files, scratch dirs (`_BASHUNIT_RUN_OUTPUT_DIR` + EXIT-trap cleanup) |
Expand Down
2 changes: 1 addition & 1 deletion .claude/rules/bash-style.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -118,7 +118,7 @@ local thing=$_BASHUNIT_PKG_THING_OUT
- A dedicated slot per helper (rather than one shared `_BASHUNIT_OUT`) means
adjacent or nested calls can't clobber each other. Cheap: globals are free.

Examples in tree: `src/runner.sh` (`_BASHUNIT_RUNNER_FIELD_OUT`,
Examples in tree: `src/runner/payload.sh` (`_BASHUNIT_RUNNER_FIELD_OUT`,
`_BASHUNIT_RUNNER_TOTAL_OUT`, `_BASHUNIT_RUNNER_TYPE_OUT`, `_BASHUNIT_RUNNER_OUTPUT_OUT`),
`src/coverage.sh` (`_BASHUNIT_BRANCH_ARMS_OUT`).

Expand Down
3 changes: 3 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -2,6 +2,9 @@

## Unreleased

### Changed
- Internal: `src/runner.sh` is split into a `src/runner/` module of ten single-responsibility files behind a `source`-only aggregator. A pure relocation, no behavior change; see [ADR-010](adrs/adr-010-src-module-directories.md) (#924)

### Fixed
- `build.sh` dedupes embedded files by repo-relative path. The previous basename key compared the top-level loop's relative paths against the recursion's absolute ones, so a file reached from two places could be bundled twice in the released binary; it also collided for same-named files in different directories (#923)

Expand Down
108 changes: 108 additions & 0 deletions adrs/adr-010-src-module-directories.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
# Splitting large `src/` files into module directories

* Status: accepted
* Deciders: Chemaclass
* Date: 2026-07-30

Technical Story: https://github.com/TypedDevs/bashunit/issues/924

## Context and Problem Statement

`src/runner.sh` had grown to 2145 lines and 57 functions covering five unrelated
responsibilities: the per-file loop, per-test execution, retry/timeout, result
parsing and failure context. Navigating it meant scrolling, and every change
touched the same file no matter which concern it belonged to.

`src/` was flat, so the obvious fix — one file per responsibility — would have
added ten more entries to an already-40-file directory. Can we group them into a
directory without changing what the released single-file binary does?

## Decision Drivers

* The distributable is a single concatenated bash script; its execution order
must not change.
* Bash 3.0+ floor, so no clever loading tricks.
* Per-test paths are fork-free and budgeted (`.claude/rules/perf-fork-budget.md`).
* `make test` globs `tests/*/*[tT]est.sh` — exactly one level deep.

## Considered Options

* Leave `src/runner.sh` as one file
* Split into flat `src/runner_*.sh` files
* Split into a `src/runner/` directory behind a thin aggregator

## Decision Outcome

Chosen option: **`src/runner/` directory behind a thin aggregator**.

`src/runner.sh` keeps its single `source` line in the `bashunit` entrypoint and
becomes ten `source` lines plus comments. `build.sh` needs no per-module
knowledge: it already recurses into `source` lines, so the module children are
discovered through the aggregator.

This required fixing `build.sh` first (#923). Its embed dedupe was keyed on a
file's *basename*, which both hid a genuine double-embed (the top-level loop
passes repo-relative paths, the recursion absolute ones, so the two spellings
never matched) and would have collided `src/parallel.sh` with
`src/runner/parallel.sh`. The key is now the repo-relative path.

**The constraint this buys is worth stating explicitly: an aggregator 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 would run
before its dependencies in the built binary but after them in dev mode. This is
enforced by `test_module_aggregators_hold_only_source_lines_and_comments`.

Sourcing follows the dependency layering, leaves first:

```
context · payload · diagnostics → parallel · hooks · result → provider · exec → discovery · bench
```

53 of the 57 functions are leaves; only `load_test_files`, `load_bench_files`,
`run_test` and `parse_result` have callees, so the layering is acyclic.

### Positive Consequences

* Each file is 90-540 lines with one responsibility; `src/` root gains a
directory instead of ten files.
* No runtime cost. Cold start is dominated by parse time, not file opens
(measured in #798), and a file split adds no forks — the fork-budget
acceptance tests pass unchanged.
* The pattern generalises: `src/coverage.sh` (2548 lines) is the next candidate.

### Negative Consequences

* Return-slot globals now cross file boundaries — `runner/payload.sh` declares
the 13 `_BASHUNIT_RUNNER_*_OUT` slots that `runner/exec.sh` reads. ShellCheck
can no longer see both ends, so `runner/exec.sh` needs one scoped `SC2154`
disable for the `exit_code` assigned inside an EXIT trap body and read by
`cleanup_on_exit` in `runner/hooks.sh`.
* One more indirection when grepping: `bashunit::runner::*` now spans ten files.

## Pros and Cons of the Options

### Leave `src/runner.sh` as one file

* Good, because zero risk and zero churn.
* Bad, because the file had five responsibilities and no seam to test them apart.

### Flat `src/runner_*.sh` files

* Good, because it needs no `build.sh` change at all.
* Bad, because it grows the flat `src/` root by ten entries and encodes the
grouping in a filename prefix rather than in the directory structure.
* Bad, because it does not generalise — `src/coverage.sh` would add nine more.

### `src/runner/` directory behind an aggregator

* Good, because it mirrors the existing `src/assertions.sh` → `src/assert_*.sh`
aggregator precedent, and `src/dev/debug.sh` already proved `src/` can nest.
* Good, because `build.sh` discovers children through recursion, so adding a
module file needs no build change.
* Bad, because it required fixing the build's dedupe key first (#923).

## Links

* Enabled by [#923](https://github.com/TypedDevs/bashunit/issues/923) — repo-relative embed markers
* Tests stay flat: `make test` globs one level, so `tests/unit/runner_*_test.sh`,
never `tests/unit/runner/`
4 changes: 2 additions & 2 deletions src/coverage.sh
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -170,8 +170,8 @@ function bashunit::coverage::resolve_engine() {
esac
}

# Name kept from the trap-only era: this is the seam runner.sh already calls
# around every test body and lifecycle hook.
# Name kept from the trap-only era: this is the seam runner/exec.sh and
# runner/hooks.sh already call around every test body and lifecycle hook.
function bashunit::coverage::enable_trap() {
if ! bashunit::env::is_coverage_enabled; then
return 0
Expand Down
Loading
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { // Add copy buttons to all 
 blocks
(function() {
function addCopyButtons() {
document.querySelectorAll('pre code').forEach(function(codeBlock) {
if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;
codeBlock.parentElement.setAttribute('data-copy-added', 'true');
var btn = document.createElement('button');
btn.textContent = 'Copy';
btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';
btn.onmouseover = function() { this.style.opacity = '1'; };
btn.onmouseout = function() { this.style.opacity = '0.7'; };
btn.onclick = function() {
navigator.clipboard.writeText(codeBlock.textContent).then(function() {
btn.textContent = 'Copied!';
setTimeout(function() { btn.textContent = 'Copy'; }, 1500);
});
};
codeBlock.parentElement.style.position = 'relative';
codeBlock.parentElement.appendChild(btn);
});
}
addCopyButtons();
// Re-run on dynamic content
var observer = new MutationObserver(addCopyButtons);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
refactor(runner): split src/runner.sh into a src/runner/ module#927

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Chemaclass
merged 2 commits into

from

Jul 30, 2026
 Merged


refactor(runner): split src/runner.sh into a src/runner/ module
#927
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
0567a48

refactor(runner): split src/runner.sh into a src/runner/ module


Chemaclass Jul 30, 2026
56ab0c6

docs: update changelog


Chemaclass Jul 30, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


14 changes: 12 additions & 2 deletions
.claude/rules/architecture-map.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -14,7 +14,7 @@ flow of a test run. Line numbers drift; function names are the stable anchors.
```
bashunit (entry) sources all src/*.sh; version gate; early flag scan
└─ bashunit::main::cmd_test (main.sh: flag parsing, env exports)
 └─ bashunit::runner::load_test_files (runner.sh: the per-file loop)
 └─ bashunit::runner::load_test_files (runner/discovery.sh: the per-file loop)
 ├─ console_header::print_header "Running N tests" — captures
 │ └─ helper::find_total_tests $() SUBSHELL: sources each file in a
 │ nested subshell just to count tests
Expand DownExpand Up@@ -48,7 +48,17 @@ shell (or, in parallel, in per-test `.result` files aggregated at the end).
| Module | Owns |
|--------|------|
| `bashunit` + `main.sh` | entry, subcommand routing, flag parsing, run lifecycle, exit codes, cleanup calls |
| `runner.sh` | file loop, per-test execution, retry/timeout, result parsing, failure context |
| `runner.sh` | aggregator only — sources the `src/runner/` module below |
| `runner/context.sh` | workdir restore, test identity/location exports, title interpolation, capability probes |
| `runner/payload.sh` | the `_BASHUNIT_RUNNER_*_OUT` return slots; encode/decode of the per-test result payload |
| `runner/diagnostics.sh` | runtime-error detection, kill-signal classification, profiling, verbose/file headers |
| `runner/result.sh` | `parse_result{,_sync,_parallel}`, failure source context, failed/skipped/incomplete/risky writers |
| `runner/parallel.sh` | job-slot waiting (`wait -n` or poll), running-job count, spinner |
| `runner/hooks.sh` | set_up/tear_down (test + script scope), hook failure records, mock clearing, EXIT cleanup |
| `runner/provider.sh` | `@data_provider` argument parsing |
| `runner/exec.sh` | `run_test`, the capture-subshell body, retry, timeout watchdog, per-file dispatch |
| `runner/discovery.sh` | `load_test_files` (the per-file loop), `functions_for_script` |
| `runner/bench.sh` | benchmark file loop and bench function dispatch |
| `helpers.sh` | discovery (`find_files_recursive`), fn filtering, provider map, duplicate check, ids |
| `state.sh` | counters, per-test payload encode/decode, TAP conversion |
| `env.sh` | all `BASHUNIT_*` defaults/config files, scratch dirs (`_BASHUNIT_RUN_OUTPUT_DIR` + EXIT-trap cleanup) |
Expand Down

2 changes: 1 addition & 1 deletion
.claude/rules/bash-style.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -118,7 +118,7 @@ local thing=$_BASHUNIT_PKG_THING_OUT
- A dedicated slot per helper (rather than one shared `_BASHUNIT_OUT`) means
 adjacent or nested calls can't clobber each other. Cheap: globals are free.

Examples in tree: `src/runner.sh` (`_BASHUNIT_RUNNER_FIELD_OUT`,
Examples in tree: `src/runner/payload.sh` (`_BASHUNIT_RUNNER_FIELD_OUT`,
`_BASHUNIT_RUNNER_TOTAL_OUT`, `_BASHUNIT_RUNNER_TYPE_OUT`, `_BASHUNIT_RUNNER_OUTPUT_OUT`),
`src/coverage.sh` (`_BASHUNIT_BRANCH_ARMS_OUT`).

Expand Down

3 changes: 3 additions & 0 deletions
CHANGELOG.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,6 +2,9 @@

## Unreleased

### Changed
- Internal: `src/runner.sh` is split into a `src/runner/` module of ten single-responsibility files behind a `source`-only aggregator. A pure relocation, no behavior change; see [ADR-010](adrs/adr-010-src-module-directories.md) (#924)

### Fixed
- `build.sh` dedupes embedded files by repo-relative path. The previous basename key compared the top-level loop's relative paths against the recursion's absolute ones, so a file reached from two places could be bundled twice in the released binary; it also collided for same-named files in different directories (#923)

Expand Down

108 changes: 108 additions & 0 deletions
adrs/adr-010-src-module-directories.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
# Splitting large `src/` files into module directories

* Status: accepted
* Deciders: Chemaclass
* Date: 2026-07-30

Technical Story: https://github.com/TypedDevs/bashunit/issues/924

## Context and Problem Statement

`src/runner.sh` had grown to 2145 lines and 57 functions covering five unrelated
responsibilities: the per-file loop, per-test execution, retry/timeout, result
parsing and failure context. Navigating it meant scrolling, and every change
touched the same file no matter which concern it belonged to.

`src/` was flat, so the obvious fix — one file per responsibility — would have
added ten more entries to an already-40-file directory. Can we group them into a
directory without changing what the released single-file binary does?

## Decision Drivers

* The distributable is a single concatenated bash script; its execution order
 must not change.
* Bash 3.0+ floor, so no clever loading tricks.
* Per-test paths are fork-free and budgeted (`.claude/rules/perf-fork-budget.md`).
* `make test` globs `tests/*/*[tT]est.sh` — exactly one level deep.

## Considered Options

* Leave `src/runner.sh` as one file
* Split into flat `src/runner_*.sh` files
* Split into a `src/runner/` directory behind a thin aggregator

## Decision Outcome

Chosen option: **`src/runner/` directory behind a thin aggregator**.

`src/runner.sh` keeps its single `source` line in the `bashunit` entrypoint and
becomes ten `source` lines plus comments. `build.sh` needs no per-module
knowledge: it already recurses into `source` lines, so the module children are
discovered through the aggregator.

This required fixing `build.sh` first (#923). Its embed dedupe was keyed on a
file's *basename*, which both hid a genuine double-embed (the top-level loop
passes repo-relative paths, the recursion absolute ones, so the two spellings
never matched) and would have collided `src/parallel.sh` with
`src/runner/parallel.sh`. The key is now the repo-relative path.

**The constraint this buys is worth stating explicitly: an aggregator 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 would run
before its dependencies in the built binary but after them in dev mode. This is
enforced by `test_module_aggregators_hold_only_source_lines_and_comments`.

Sourcing follows the dependency layering, leaves first:

```
context · payload · diagnostics → parallel · hooks · result → provider · exec → discovery · bench
```

53 of the 57 functions are leaves; only `load_test_files`, `load_bench_files`,
`run_test` and `parse_result` have callees, so the layering is acyclic.

### Positive Consequences

* Each file is 90-540 lines with one responsibility; `src/` root gains a
 directory instead of ten files.
* No runtime cost. Cold start is dominated by parse time, not file opens
 (measured in #798), and a file split adds no forks — the fork-budget
 acceptance tests pass unchanged.
* The pattern generalises: `src/coverage.sh` (2548 lines) is the next candidate.

### Negative Consequences

* Return-slot globals now cross file boundaries — `runner/payload.sh` declares
 the 13 `_BASHUNIT_RUNNER_*_OUT` slots that `runner/exec.sh` reads. ShellCheck
 can no longer see both ends, so `runner/exec.sh` needs one scoped `SC2154`
 disable for the `exit_code` assigned inside an EXIT trap body and read by
 `cleanup_on_exit` in `runner/hooks.sh`.
* One more indirection when grepping: `bashunit::runner::*` now spans ten files.

## Pros and Cons of the Options

### Leave `src/runner.sh` as one file

* Good, because zero risk and zero churn.
* Bad, because the file had five responsibilities and no seam to test them apart.

### Flat `src/runner_*.sh` files

* Good, because it needs no `build.sh` change at all.
* Bad, because it grows the flat `src/` root by ten entries and encodes the
 grouping in a filename prefix rather than in the directory structure.
* Bad, because it does not generalise — `src/coverage.sh` would add nine more.

### `src/runner/` directory behind an aggregator

* Good, because it mirrors the existing `src/assertions.sh` → `src/assert_*.sh`
 aggregator precedent, and `src/dev/debug.sh` already proved `src/` can nest.
* Good, because `build.sh` discovers children through recursion, so adding a
 module file needs no build change.
* Bad, because it required fixing the build's dedupe key first (#923).

## Links

* Enabled by [#923](https://github.com/TypedDevs/bashunit/issues/923) — repo-relative embed markers
* Tests stay flat: `make test` globs one level, so `tests/unit/runner_*_test.sh`,
 never `tests/unit/runner/`

4 changes: 2 additions & 2 deletions
src/coverage.sh

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -170,8 +170,8 @@ function bashunit::coverage::resolve_engine() {
 esac
}

# Name kept from the trap-only era: this is the seam runner.sh already calls
# around every test body and lifecycle hook.
# Name kept from the trap-only era: this is the seam runner/exec.sh and
# runner/hooks.sh already call around every test body and lifecycle hook.
function bashunit::coverage::enable_trap() {
 if ! bashunit::env::is_coverage_enabled; then
 return 0
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Force GitHub README to respect dark mode
(function() {
var style = document.createElement('style');
style.textContent = '
.markdown-body {
color-scheme: dark light;
}
.markdown-body pre { background: #161b22 !important; }
.markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }
.markdown-body table th, .markdown-body table td { border-color: #30363d !important; }
.markdown-body img { background: #0d1117; }
.markdown-body blockquote { border-left-color: #8b949e; }
.markdown-body hr { border-color: #30363d; }
';
document.head.appendChild(style);
})();
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
refactor(runner): split src/runner.sh into a src/runner/ module#927

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Chemaclass
merged 2 commits into

from

Jul 30, 2026
 Merged


refactor(runner): split src/runner.sh into a src/runner/ module
#927
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
0567a48

refactor(runner): split src/runner.sh into a src/runner/ module


Chemaclass Jul 30, 2026
56ab0c6

docs: update changelog


Chemaclass Jul 30, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


14 changes: 12 additions & 2 deletions
.claude/rules/architecture-map.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -14,7 +14,7 @@ flow of a test run. Line numbers drift; function names are the stable anchors.
```
bashunit (entry) sources all src/*.sh; version gate; early flag scan
└─ bashunit::main::cmd_test (main.sh: flag parsing, env exports)
 └─ bashunit::runner::load_test_files (runner.sh: the per-file loop)
 └─ bashunit::runner::load_test_files (runner/discovery.sh: the per-file loop)
 ├─ console_header::print_header "Running N tests" — captures
 │ └─ helper::find_total_tests $() SUBSHELL: sources each file in a
 │ nested subshell just to count tests
Expand DownExpand Up@@ -48,7 +48,17 @@ shell (or, in parallel, in per-test `.result` files aggregated at the end).
| Module | Owns |
|--------|------|
| `bashunit` + `main.sh` | entry, subcommand routing, flag parsing, run lifecycle, exit codes, cleanup calls |
| `runner.sh` | file loop, per-test execution, retry/timeout, result parsing, failure context |
| `runner.sh` | aggregator only — sources the `src/runner/` module below |
| `runner/context.sh` | workdir restore, test identity/location exports, title interpolation, capability probes |
| `runner/payload.sh` | the `_BASHUNIT_RUNNER_*_OUT` return slots; encode/decode of the per-test result payload |
| `runner/diagnostics.sh` | runtime-error detection, kill-signal classification, profiling, verbose/file headers |
| `runner/result.sh` | `parse_result{,_sync,_parallel}`, failure source context, failed/skipped/incomplete/risky writers |
| `runner/parallel.sh` | job-slot waiting (`wait -n` or poll), running-job count, spinner |
| `runner/hooks.sh` | set_up/tear_down (test + script scope), hook failure records, mock clearing, EXIT cleanup |
| `runner/provider.sh` | `@data_provider` argument parsing |
| `runner/exec.sh` | `run_test`, the capture-subshell body, retry, timeout watchdog, per-file dispatch |
| `runner/discovery.sh` | `load_test_files` (the per-file loop), `functions_for_script` |
| `runner/bench.sh` | benchmark file loop and bench function dispatch |
| `helpers.sh` | discovery (`find_files_recursive`), fn filtering, provider map, duplicate check, ids |
| `state.sh` | counters, per-test payload encode/decode, TAP conversion |
| `env.sh` | all `BASHUNIT_*` defaults/config files, scratch dirs (`_BASHUNIT_RUN_OUTPUT_DIR` + EXIT-trap cleanup) |
Expand Down

2 changes: 1 addition & 1 deletion
.claude/rules/bash-style.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -118,7 +118,7 @@ local thing=$_BASHUNIT_PKG_THING_OUT
- A dedicated slot per helper (rather than one shared `_BASHUNIT_OUT`) means
 adjacent or nested calls can't clobber each other. Cheap: globals are free.

Examples in tree: `src/runner.sh` (`_BASHUNIT_RUNNER_FIELD_OUT`,
Examples in tree: `src/runner/payload.sh` (`_BASHUNIT_RUNNER_FIELD_OUT`,
`_BASHUNIT_RUNNER_TOTAL_OUT`, `_BASHUNIT_RUNNER_TYPE_OUT`, `_BASHUNIT_RUNNER_OUTPUT_OUT`),
`src/coverage.sh` (`_BASHUNIT_BRANCH_ARMS_OUT`).

Expand Down

3 changes: 3 additions & 0 deletions
CHANGELOG.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,6 +2,9 @@

## Unreleased

### Changed
- Internal: `src/runner.sh` is split into a `src/runner/` module of ten single-responsibility files behind a `source`-only aggregator. A pure relocation, no behavior change; see [ADR-010](adrs/adr-010-src-module-directories.md) (#924)

### Fixed
- `build.sh` dedupes embedded files by repo-relative path. The previous basename key compared the top-level loop's relative paths against the recursion's absolute ones, so a file reached from two places could be bundled twice in the released binary; it also collided for same-named files in different directories (#923)

Expand Down

108 changes: 108 additions & 0 deletions
adrs/adr-010-src-module-directories.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
# Splitting large `src/` files into module directories

* Status: accepted
* Deciders: Chemaclass
* Date: 2026-07-30

Technical Story: https://github.com/TypedDevs/bashunit/issues/924

## Context and Problem Statement

`src/runner.sh` had grown to 2145 lines and 57 functions covering five unrelated
responsibilities: the per-file loop, per-test execution, retry/timeout, result
parsing and failure context. Navigating it meant scrolling, and every change
touched the same file no matter which concern it belonged to.

`src/` was flat, so the obvious fix — one file per responsibility — would have
added ten more entries to an already-40-file directory. Can we group them into a
directory without changing what the released single-file binary does?

## Decision Drivers

* The distributable is a single concatenated bash script; its execution order
 must not change.
* Bash 3.0+ floor, so no clever loading tricks.
* Per-test paths are fork-free and budgeted (`.claude/rules/perf-fork-budget.md`).
* `make test` globs `tests/*/*[tT]est.sh` — exactly one level deep.

## Considered Options

* Leave `src/runner.sh` as one file
* Split into flat `src/runner_*.sh` files
* Split into a `src/runner/` directory behind a thin aggregator

## Decision Outcome

Chosen option: **`src/runner/` directory behind a thin aggregator**.

`src/runner.sh` keeps its single `source` line in the `bashunit` entrypoint and
becomes ten `source` lines plus comments. `build.sh` needs no per-module
knowledge: it already recurses into `source` lines, so the module children are
discovered through the aggregator.

This required fixing `build.sh` first (#923). Its embed dedupe was keyed on a
file's *basename*, which both hid a genuine double-embed (the top-level loop
passes repo-relative paths, the recursion absolute ones, so the two spellings
never matched) and would have collided `src/parallel.sh` with
`src/runner/parallel.sh`. The key is now the repo-relative path.

**The constraint this buys is worth stating explicitly: an aggregator 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 would run
before its dependencies in the built binary but after them in dev mode. This is
enforced by `test_module_aggregators_hold_only_source_lines_and_comments`.

Sourcing follows the dependency layering, leaves first:

```
context · payload · diagnostics → parallel · hooks · result → provider · exec → discovery · bench
```

53 of the 57 functions are leaves; only `load_test_files`, `load_bench_files`,
`run_test` and `parse_result` have callees, so the layering is acyclic.

### Positive Consequences

* Each file is 90-540 lines with one responsibility; `src/` root gains a
 directory instead of ten files.
* No runtime cost. Cold start is dominated by parse time, not file opens
 (measured in #798), and a file split adds no forks — the fork-budget
 acceptance tests pass unchanged.
* The pattern generalises: `src/coverage.sh` (2548 lines) is the next candidate.

### Negative Consequences

* Return-slot globals now cross file boundaries — `runner/payload.sh` declares
 the 13 `_BASHUNIT_RUNNER_*_OUT` slots that `runner/exec.sh` reads. ShellCheck
 can no longer see both ends, so `runner/exec.sh` needs one scoped `SC2154`
 disable for the `exit_code` assigned inside an EXIT trap body and read by
 `cleanup_on_exit` in `runner/hooks.sh`.
* One more indirection when grepping: `bashunit::runner::*` now spans ten files.

## Pros and Cons of the Options

### Leave `src/runner.sh` as one file

* Good, because zero risk and zero churn.
* Bad, because the file had five responsibilities and no seam to test them apart.

### Flat `src/runner_*.sh` files

* Good, because it needs no `build.sh` change at all.
* Bad, because it grows the flat `src/` root by ten entries and encodes the
 grouping in a filename prefix rather than in the directory structure.
* Bad, because it does not generalise — `src/coverage.sh` would add nine more.

### `src/runner/` directory behind an aggregator

* Good, because it mirrors the existing `src/assertions.sh` → `src/assert_*.sh`
 aggregator precedent, and `src/dev/debug.sh` already proved `src/` can nest.
* Good, because `build.sh` discovers children through recursion, so adding a
 module file needs no build change.
* Bad, because it required fixing the build's dedupe key first (#923).

## Links

* Enabled by [#923](https://github.com/TypedDevs/bashunit/issues/923) — repo-relative embed markers
* Tests stay flat: `make test` globs one level, so `tests/unit/runner_*_test.sh`,
 never `tests/unit/runner/`

4 changes: 2 additions & 2 deletions
src/coverage.sh

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -170,8 +170,8 @@ function bashunit::coverage::resolve_engine() {
 esac
}

# Name kept from the trap-only era: this is the seam runner.sh already calls
# around every test body and lifecycle hook.
# Name kept from the trap-only era: this is the seam runner/exec.sh and
# runner/hooks.sh already call around every test body and lifecycle hook.
function bashunit::coverage::enable_trap() {
 if ! bashunit::env::is_coverage_enabled; then
 return 0
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Highlight search terms from Google/DuckDuckGo/Bing referrer
(function() {
var ref = document.referrer;
var terms = [];
if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {
var url = new URL(ref);
var q = url.searchParams.get('q') || url.searchParams.get('p');
if (q) {
terms = q.split(/\s+/).filter(function(t) { return t.length > 2; });
}
}
if (terms.length === 0) return;
var style = document.createElement('style');
style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';
document.head.appendChild(style);
function highlight(node) {
if (node.nodeType === 3) { // text node
var text = node.textContent;
var found = false;
terms.forEach(function(term) {
var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\]\\]/g, '\\') + ')', 'gi');
if (regex.test(text)) {
found = true;
var frag = document.createDocumentFragment();
var parts = text.split(regex);
parts.forEach(function(part, i) {
if (i % 2 === 0) {
frag.appendChild(document.createTextNode(part));
} else {
var span = document.createElement('span');
span.className = 'userscript-highlight';
span.textContent = part;
frag.appendChild(span);
}
});
node.parentNode.replaceChild(frag, node);
}
});
} else if (node.nodeType === 1 && node.childNodes) { // element
var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];
if (!skipTags.includes(node.tagName)) {
Array.from(node.childNodes).forEach(highlight);
}
}
}
highlight(document.body);
// Re-highlight on dynamic content
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1 || node.nodeType === 3) highlight(node);
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
refactor(runner): split src/runner.sh into a src/runner/ module#927

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Chemaclass
merged 2 commits into

from

Jul 30, 2026
 Merged


refactor(runner): split src/runner.sh into a src/runner/ module
#927
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
0567a48

refactor(runner): split src/runner.sh into a src/runner/ module


Chemaclass Jul 30, 2026
56ab0c6

docs: update changelog


Chemaclass Jul 30, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


14 changes: 12 additions & 2 deletions
.claude/rules/architecture-map.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -14,7 +14,7 @@ flow of a test run. Line numbers drift; function names are the stable anchors.
```
bashunit (entry) sources all src/*.sh; version gate; early flag scan
└─ bashunit::main::cmd_test (main.sh: flag parsing, env exports)
 └─ bashunit::runner::load_test_files (runner.sh: the per-file loop)
 └─ bashunit::runner::load_test_files (runner/discovery.sh: the per-file loop)
 ├─ console_header::print_header "Running N tests" — captures
 │ └─ helper::find_total_tests $() SUBSHELL: sources each file in a
 │ nested subshell just to count tests
Expand DownExpand Up@@ -48,7 +48,17 @@ shell (or, in parallel, in per-test `.result` files aggregated at the end).
| Module | Owns |
|--------|------|
| `bashunit` + `main.sh` | entry, subcommand routing, flag parsing, run lifecycle, exit codes, cleanup calls |
| `runner.sh` | file loop, per-test execution, retry/timeout, result parsing, failure context |
| `runner.sh` | aggregator only — sources the `src/runner/` module below |
| `runner/context.sh` | workdir restore, test identity/location exports, title interpolation, capability probes |
| `runner/payload.sh` | the `_BASHUNIT_RUNNER_*_OUT` return slots; encode/decode of the per-test result payload |
| `runner/diagnostics.sh` | runtime-error detection, kill-signal classification, profiling, verbose/file headers |
| `runner/result.sh` | `parse_result{,_sync,_parallel}`, failure source context, failed/skipped/incomplete/risky writers |
| `runner/parallel.sh` | job-slot waiting (`wait -n` or poll), running-job count, spinner |
| `runner/hooks.sh` | set_up/tear_down (test + script scope), hook failure records, mock clearing, EXIT cleanup |
| `runner/provider.sh` | `@data_provider` argument parsing |
| `runner/exec.sh` | `run_test`, the capture-subshell body, retry, timeout watchdog, per-file dispatch |
| `runner/discovery.sh` | `load_test_files` (the per-file loop), `functions_for_script` |
| `runner/bench.sh` | benchmark file loop and bench function dispatch |
| `helpers.sh` | discovery (`find_files_recursive`), fn filtering, provider map, duplicate check, ids |
| `state.sh` | counters, per-test payload encode/decode, TAP conversion |
| `env.sh` | all `BASHUNIT_*` defaults/config files, scratch dirs (`_BASHUNIT_RUN_OUTPUT_DIR` + EXIT-trap cleanup) |
Expand Down

2 changes: 1 addition & 1 deletion
.claude/rules/bash-style.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -118,7 +118,7 @@ local thing=$_BASHUNIT_PKG_THING_OUT
- A dedicated slot per helper (rather than one shared `_BASHUNIT_OUT`) means
 adjacent or nested calls can't clobber each other. Cheap: globals are free.

Examples in tree: `src/runner.sh` (`_BASHUNIT_RUNNER_FIELD_OUT`,
Examples in tree: `src/runner/payload.sh` (`_BASHUNIT_RUNNER_FIELD_OUT`,
`_BASHUNIT_RUNNER_TOTAL_OUT`, `_BASHUNIT_RUNNER_TYPE_OUT`, `_BASHUNIT_RUNNER_OUTPUT_OUT`),
`src/coverage.sh` (`_BASHUNIT_BRANCH_ARMS_OUT`).

Expand Down

3 changes: 3 additions & 0 deletions
CHANGELOG.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,6 +2,9 @@

## Unreleased

### Changed
- Internal: `src/runner.sh` is split into a `src/runner/` module of ten single-responsibility files behind a `source`-only aggregator. A pure relocation, no behavior change; see [ADR-010](adrs/adr-010-src-module-directories.md) (#924)

### Fixed
- `build.sh` dedupes embedded files by repo-relative path. The previous basename key compared the top-level loop's relative paths against the recursion's absolute ones, so a file reached from two places could be bundled twice in the released binary; it also collided for same-named files in different directories (#923)

Expand Down

108 changes: 108 additions & 0 deletions
adrs/adr-010-src-module-directories.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
# Splitting large `src/` files into module directories

* Status: accepted
* Deciders: Chemaclass
* Date: 2026-07-30

Technical Story: https://github.com/TypedDevs/bashunit/issues/924

## Context and Problem Statement

`src/runner.sh` had grown to 2145 lines and 57 functions covering five unrelated
responsibilities: the per-file loop, per-test execution, retry/timeout, result
parsing and failure context. Navigating it meant scrolling, and every change
touched the same file no matter which concern it belonged to.

`src/` was flat, so the obvious fix — one file per responsibility — would have
added ten more entries to an already-40-file directory. Can we group them into a
directory without changing what the released single-file binary does?

## Decision Drivers

* The distributable is a single concatenated bash script; its execution order
 must not change.
* Bash 3.0+ floor, so no clever loading tricks.
* Per-test paths are fork-free and budgeted (`.claude/rules/perf-fork-budget.md`).
* `make test` globs `tests/*/*[tT]est.sh` — exactly one level deep.

## Considered Options

* Leave `src/runner.sh` as one file
* Split into flat `src/runner_*.sh` files
* Split into a `src/runner/` directory behind a thin aggregator

## Decision Outcome

Chosen option: **`src/runner/` directory behind a thin aggregator**.

`src/runner.sh` keeps its single `source` line in the `bashunit` entrypoint and
becomes ten `source` lines plus comments. `build.sh` needs no per-module
knowledge: it already recurses into `source` lines, so the module children are
discovered through the aggregator.

This required fixing `build.sh` first (#923). Its embed dedupe was keyed on a
file's *basename*, which both hid a genuine double-embed (the top-level loop
passes repo-relative paths, the recursion absolute ones, so the two spellings
never matched) and would have collided `src/parallel.sh` with
`src/runner/parallel.sh`. The key is now the repo-relative path.

**The constraint this buys is worth stating explicitly: an aggregator 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 would run
before its dependencies in the built binary but after them in dev mode. This is
enforced by `test_module_aggregators_hold_only_source_lines_and_comments`.

Sourcing follows the dependency layering, leaves first:

```
context · payload · diagnostics → parallel · hooks · result → provider · exec → discovery · bench
```

53 of the 57 functions are leaves; only `load_test_files`, `load_bench_files`,
`run_test` and `parse_result` have callees, so the layering is acyclic.

### Positive Consequences

* Each file is 90-540 lines with one responsibility; `src/` root gains a
 directory instead of ten files.
* No runtime cost. Cold start is dominated by parse time, not file opens
 (measured in #798), and a file split adds no forks — the fork-budget
 acceptance tests pass unchanged.
* The pattern generalises: `src/coverage.sh` (2548 lines) is the next candidate.

### Negative Consequences

* Return-slot globals now cross file boundaries — `runner/payload.sh` declares
 the 13 `_BASHUNIT_RUNNER_*_OUT` slots that `runner/exec.sh` reads. ShellCheck
 can no longer see both ends, so `runner/exec.sh` needs one scoped `SC2154`
 disable for the `exit_code` assigned inside an EXIT trap body and read by
 `cleanup_on_exit` in `runner/hooks.sh`.
* One more indirection when grepping: `bashunit::runner::*` now spans ten files.

## Pros and Cons of the Options

### Leave `src/runner.sh` as one file

* Good, because zero risk and zero churn.
* Bad, because the file had five responsibilities and no seam to test them apart.

### Flat `src/runner_*.sh` files

* Good, because it needs no `build.sh` change at all.
* Bad, because it grows the flat `src/` root by ten entries and encodes the
 grouping in a filename prefix rather than in the directory structure.
* Bad, because it does not generalise — `src/coverage.sh` would add nine more.

### `src/runner/` directory behind an aggregator

* Good, because it mirrors the existing `src/assertions.sh` → `src/assert_*.sh`
 aggregator precedent, and `src/dev/debug.sh` already proved `src/` can nest.
* Good, because `build.sh` discovers children through recursion, so adding a
 module file needs no build change.
* Bad, because it required fixing the build's dedupe key first (#923).

## Links

* Enabled by [#923](https://github.com/TypedDevs/bashunit/issues/923) — repo-relative embed markers
* Tests stay flat: `make test` globs one level, so `tests/unit/runner_*_test.sh`,
 never `tests/unit/runner/`

4 changes: 2 additions & 2 deletions
src/coverage.sh

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -170,8 +170,8 @@ function bashunit::coverage::resolve_engine() {
 esac
}

# Name kept from the trap-only era: this is the seam runner.sh already calls
# around every test body and lifecycle hook.
# Name kept from the trap-only era: this is the seam runner/exec.sh and
# runner/hooks.sh already call around every test body and lifecycle hook.
function bashunit::coverage::enable_trap() {
 if ! bashunit::env::is_coverage_enabled; then
 return 0
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Strip utm_, fbclid, gclid, etc. from all links on page
(function() {
var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',
'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',
'ref', 'ref_src', 'source', 'medium', 'campaign'];
function cleanUrl(url) {
try {
var u = new URL(url, window.location.origin);
var changed = false;
trackingParams.forEach(function(p) {
if (u.searchParams.has(p)) {
u.searchParams.delete(p);
changed = true;
}
});
return changed ? u.toString() : url;
} catch (e) {
return url;
}
}
function cleanLinks() {
document.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
cleanLinks();
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1) {
if (node.tagName === 'A') cleanLinks();
node.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
refactor(runner): split src/runner.sh into a src/runner/ module#927

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Chemaclass
merged 2 commits into

from

Jul 30, 2026
 Merged


refactor(runner): split src/runner.sh into a src/runner/ module
#927
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
0567a48

refactor(runner): split src/runner.sh into a src/runner/ module


Chemaclass Jul 30, 2026
56ab0c6

docs: update changelog


Chemaclass Jul 30, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


14 changes: 12 additions & 2 deletions
.claude/rules/architecture-map.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -14,7 +14,7 @@ flow of a test run. Line numbers drift; function names are the stable anchors.
```
bashunit (entry) sources all src/*.sh; version gate; early flag scan
└─ bashunit::main::cmd_test (main.sh: flag parsing, env exports)
 └─ bashunit::runner::load_test_files (runner.sh: the per-file loop)
 └─ bashunit::runner::load_test_files (runner/discovery.sh: the per-file loop)
 ├─ console_header::print_header "Running N tests" — captures
 │ └─ helper::find_total_tests $() SUBSHELL: sources each file in a
 │ nested subshell just to count tests
Expand DownExpand Up@@ -48,7 +48,17 @@ shell (or, in parallel, in per-test `.result` files aggregated at the end).
| Module | Owns |
|--------|------|
| `bashunit` + `main.sh` | entry, subcommand routing, flag parsing, run lifecycle, exit codes, cleanup calls |
| `runner.sh` | file loop, per-test execution, retry/timeout, result parsing, failure context |
| `runner.sh` | aggregator only — sources the `src/runner/` module below |
| `runner/context.sh` | workdir restore, test identity/location exports, title interpolation, capability probes |
| `runner/payload.sh` | the `_BASHUNIT_RUNNER_*_OUT` return slots; encode/decode of the per-test result payload |
| `runner/diagnostics.sh` | runtime-error detection, kill-signal classification, profiling, verbose/file headers |
| `runner/result.sh` | `parse_result{,_sync,_parallel}`, failure source context, failed/skipped/incomplete/risky writers |
| `runner/parallel.sh` | job-slot waiting (`wait -n` or poll), running-job count, spinner |
| `runner/hooks.sh` | set_up/tear_down (test + script scope), hook failure records, mock clearing, EXIT cleanup |
| `runner/provider.sh` | `@data_provider` argument parsing |
| `runner/exec.sh` | `run_test`, the capture-subshell body, retry, timeout watchdog, per-file dispatch |
| `runner/discovery.sh` | `load_test_files` (the per-file loop), `functions_for_script` |
| `runner/bench.sh` | benchmark file loop and bench function dispatch |
| `helpers.sh` | discovery (`find_files_recursive`), fn filtering, provider map, duplicate check, ids |
| `state.sh` | counters, per-test payload encode/decode, TAP conversion |
| `env.sh` | all `BASHUNIT_*` defaults/config files, scratch dirs (`_BASHUNIT_RUN_OUTPUT_DIR` + EXIT-trap cleanup) |
Expand Down

2 changes: 1 addition & 1 deletion
.claude/rules/bash-style.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -118,7 +118,7 @@ local thing=$_BASHUNIT_PKG_THING_OUT
- A dedicated slot per helper (rather than one shared `_BASHUNIT_OUT`) means
 adjacent or nested calls can't clobber each other. Cheap: globals are free.

Examples in tree: `src/runner.sh` (`_BASHUNIT_RUNNER_FIELD_OUT`,
Examples in tree: `src/runner/payload.sh` (`_BASHUNIT_RUNNER_FIELD_OUT`,
`_BASHUNIT_RUNNER_TOTAL_OUT`, `_BASHUNIT_RUNNER_TYPE_OUT`, `_BASHUNIT_RUNNER_OUTPUT_OUT`),
`src/coverage.sh` (`_BASHUNIT_BRANCH_ARMS_OUT`).

Expand Down

3 changes: 3 additions & 0 deletions
CHANGELOG.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,6 +2,9 @@

## Unreleased

### Changed
- Internal: `src/runner.sh` is split into a `src/runner/` module of ten single-responsibility files behind a `source`-only aggregator. A pure relocation, no behavior change; see [ADR-010](adrs/adr-010-src-module-directories.md) (#924)

### Fixed
- `build.sh` dedupes embedded files by repo-relative path. The previous basename key compared the top-level loop's relative paths against the recursion's absolute ones, so a file reached from two places could be bundled twice in the released binary; it also collided for same-named files in different directories (#923)

Expand Down

108 changes: 108 additions & 0 deletions
adrs/adr-010-src-module-directories.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
# Splitting large `src/` files into module directories

* Status: accepted
* Deciders: Chemaclass
* Date: 2026-07-30

Technical Story: https://github.com/TypedDevs/bashunit/issues/924

## Context and Problem Statement

`src/runner.sh` had grown to 2145 lines and 57 functions covering five unrelated
responsibilities: the per-file loop, per-test execution, retry/timeout, result
parsing and failure context. Navigating it meant scrolling, and every change
touched the same file no matter which concern it belonged to.

`src/` was flat, so the obvious fix — one file per responsibility — would have
added ten more entries to an already-40-file directory. Can we group them into a
directory without changing what the released single-file binary does?

## Decision Drivers

* The distributable is a single concatenated bash script; its execution order
 must not change.
* Bash 3.0+ floor, so no clever loading tricks.
* Per-test paths are fork-free and budgeted (`.claude/rules/perf-fork-budget.md`).
* `make test` globs `tests/*/*[tT]est.sh` — exactly one level deep.

## Considered Options

* Leave `src/runner.sh` as one file
* Split into flat `src/runner_*.sh` files
* Split into a `src/runner/` directory behind a thin aggregator

## Decision Outcome

Chosen option: **`src/runner/` directory behind a thin aggregator**.

`src/runner.sh` keeps its single `source` line in the `bashunit` entrypoint and
becomes ten `source` lines plus comments. `build.sh` needs no per-module
knowledge: it already recurses into `source` lines, so the module children are
discovered through the aggregator.

This required fixing `build.sh` first (#923). Its embed dedupe was keyed on a
file's *basename*, which both hid a genuine double-embed (the top-level loop
passes repo-relative paths, the recursion absolute ones, so the two spellings
never matched) and would have collided `src/parallel.sh` with
`src/runner/parallel.sh`. The key is now the repo-relative path.

**The constraint this buys is worth stating explicitly: an aggregator 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 would run
before its dependencies in the built binary but after them in dev mode. This is
enforced by `test_module_aggregators_hold_only_source_lines_and_comments`.

Sourcing follows the dependency layering, leaves first:

```
context · payload · diagnostics → parallel · hooks · result → provider · exec → discovery · bench
```

53 of the 57 functions are leaves; only `load_test_files`, `load_bench_files`,
`run_test` and `parse_result` have callees, so the layering is acyclic.

### Positive Consequences

* Each file is 90-540 lines with one responsibility; `src/` root gains a
 directory instead of ten files.
* No runtime cost. Cold start is dominated by parse time, not file opens
 (measured in #798), and a file split adds no forks — the fork-budget
 acceptance tests pass unchanged.
* The pattern generalises: `src/coverage.sh` (2548 lines) is the next candidate.

### Negative Consequences

* Return-slot globals now cross file boundaries — `runner/payload.sh` declares
 the 13 `_BASHUNIT_RUNNER_*_OUT` slots that `runner/exec.sh` reads. ShellCheck
 can no longer see both ends, so `runner/exec.sh` needs one scoped `SC2154`
 disable for the `exit_code` assigned inside an EXIT trap body and read by
 `cleanup_on_exit` in `runner/hooks.sh`.
* One more indirection when grepping: `bashunit::runner::*` now spans ten files.

## Pros and Cons of the Options

### Leave `src/runner.sh` as one file

* Good, because zero risk and zero churn.
* Bad, because the file had five responsibilities and no seam to test them apart.

### Flat `src/runner_*.sh` files

* Good, because it needs no `build.sh` change at all.
* Bad, because it grows the flat `src/` root by ten entries and encodes the
 grouping in a filename prefix rather than in the directory structure.
* Bad, because it does not generalise — `src/coverage.sh` would add nine more.

### `src/runner/` directory behind an aggregator

* Good, because it mirrors the existing `src/assertions.sh` → `src/assert_*.sh`
 aggregator precedent, and `src/dev/debug.sh` already proved `src/` can nest.
* Good, because `build.sh` discovers children through recursion, so adding a
 module file needs no build change.
* Bad, because it required fixing the build's dedupe key first (#923).

## Links

* Enabled by [#923](https://github.com/TypedDevs/bashunit/issues/923) — repo-relative embed markers
* Tests stay flat: `make test` globs one level, so `tests/unit/runner_*_test.sh`,
 never `tests/unit/runner/`

4 changes: 2 additions & 2 deletions
src/coverage.sh

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -170,8 +170,8 @@ function bashunit::coverage::resolve_engine() {
 esac
}

# Name kept from the trap-only era: this is the seam runner.sh already calls
# around every test body and lifecycle hook.
# Name kept from the trap-only era: this is the seam runner/exec.sh and
# runner/hooks.sh already call around every test body and lifecycle hook.
function bashunit::coverage::enable_trap() {
 if ! bashunit::env::is_coverage_enabled; then
 return 0
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Auto-enable theater mode on YouTube
(function() {
function tryTheater() {
var btn = document.querySelector('button[aria-label="Theater mode"], ytd-player #player button[title="Theater mode"]');
if (btn && !btn.classList.contains('activated')) {
btn.click();
}
}
// Try immediately
tryTheater();
// Try after navigation (SPA)
var lastUrl = location.href;
setInterval(function() {
if (location.href !== lastUrl) {
lastUrl = location.href;
setTimeout(tryTheater, 500);
}
}, 1000);
// Also try on player load
var observer = new MutationObserver(tryTheater);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
refactor(runner): split src/runner.sh into a src/runner/ module#927

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Chemaclass
merged 2 commits into

from

Jul 30, 2026
 Merged


refactor(runner): split src/runner.sh into a src/runner/ module
#927
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
0567a48

refactor(runner): split src/runner.sh into a src/runner/ module


Chemaclass Jul 30, 2026
56ab0c6

docs: update changelog


Chemaclass Jul 30, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


14 changes: 12 additions & 2 deletions
.claude/rules/architecture-map.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -14,7 +14,7 @@ flow of a test run. Line numbers drift; function names are the stable anchors.
```
bashunit (entry) sources all src/*.sh; version gate; early flag scan
└─ bashunit::main::cmd_test (main.sh: flag parsing, env exports)
 └─ bashunit::runner::load_test_files (runner.sh: the per-file loop)
 └─ bashunit::runner::load_test_files (runner/discovery.sh: the per-file loop)
 ├─ console_header::print_header "Running N tests" — captures
 │ └─ helper::find_total_tests $() SUBSHELL: sources each file in a
 │ nested subshell just to count tests
Expand DownExpand Up@@ -48,7 +48,17 @@ shell (or, in parallel, in per-test `.result` files aggregated at the end).
| Module | Owns |
|--------|------|
| `bashunit` + `main.sh` | entry, subcommand routing, flag parsing, run lifecycle, exit codes, cleanup calls |
| `runner.sh` | file loop, per-test execution, retry/timeout, result parsing, failure context |
| `runner.sh` | aggregator only — sources the `src/runner/` module below |
| `runner/context.sh` | workdir restore, test identity/location exports, title interpolation, capability probes |
| `runner/payload.sh` | the `_BASHUNIT_RUNNER_*_OUT` return slots; encode/decode of the per-test result payload |
| `runner/diagnostics.sh` | runtime-error detection, kill-signal classification, profiling, verbose/file headers |
| `runner/result.sh` | `parse_result{,_sync,_parallel}`, failure source context, failed/skipped/incomplete/risky writers |
| `runner/parallel.sh` | job-slot waiting (`wait -n` or poll), running-job count, spinner |
| `runner/hooks.sh` | set_up/tear_down (test + script scope), hook failure records, mock clearing, EXIT cleanup |
| `runner/provider.sh` | `@data_provider` argument parsing |
| `runner/exec.sh` | `run_test`, the capture-subshell body, retry, timeout watchdog, per-file dispatch |
| `runner/discovery.sh` | `load_test_files` (the per-file loop), `functions_for_script` |
| `runner/bench.sh` | benchmark file loop and bench function dispatch |
| `helpers.sh` | discovery (`find_files_recursive`), fn filtering, provider map, duplicate check, ids |
| `state.sh` | counters, per-test payload encode/decode, TAP conversion |
| `env.sh` | all `BASHUNIT_*` defaults/config files, scratch dirs (`_BASHUNIT_RUN_OUTPUT_DIR` + EXIT-trap cleanup) |
Expand Down

2 changes: 1 addition & 1 deletion
.claude/rules/bash-style.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -118,7 +118,7 @@ local thing=$_BASHUNIT_PKG_THING_OUT
- A dedicated slot per helper (rather than one shared `_BASHUNIT_OUT`) means
 adjacent or nested calls can't clobber each other. Cheap: globals are free.

Examples in tree: `src/runner.sh` (`_BASHUNIT_RUNNER_FIELD_OUT`,
Examples in tree: `src/runner/payload.sh` (`_BASHUNIT_RUNNER_FIELD_OUT`,
`_BASHUNIT_RUNNER_TOTAL_OUT`, `_BASHUNIT_RUNNER_TYPE_OUT`, `_BASHUNIT_RUNNER_OUTPUT_OUT`),
`src/coverage.sh` (`_BASHUNIT_BRANCH_ARMS_OUT`).

Expand Down

3 changes: 3 additions & 0 deletions
CHANGELOG.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,6 +2,9 @@

## Unreleased

### Changed
- Internal: `src/runner.sh` is split into a `src/runner/` module of ten single-responsibility files behind a `source`-only aggregator. A pure relocation, no behavior change; see [ADR-010](adrs/adr-010-src-module-directories.md) (#924)

### Fixed
- `build.sh` dedupes embedded files by repo-relative path. The previous basename key compared the top-level loop's relative paths against the recursion's absolute ones, so a file reached from two places could be bundled twice in the released binary; it also collided for same-named files in different directories (#923)

Expand Down

108 changes: 108 additions & 0 deletions
adrs/adr-010-src-module-directories.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
# Splitting large `src/` files into module directories

* Status: accepted
* Deciders: Chemaclass
* Date: 2026-07-30

Technical Story: https://github.com/TypedDevs/bashunit/issues/924

## Context and Problem Statement

`src/runner.sh` had grown to 2145 lines and 57 functions covering five unrelated
responsibilities: the per-file loop, per-test execution, retry/timeout, result
parsing and failure context. Navigating it meant scrolling, and every change
touched the same file no matter which concern it belonged to.

`src/` was flat, so the obvious fix — one file per responsibility — would have
added ten more entries to an already-40-file directory. Can we group them into a
directory without changing what the released single-file binary does?

## Decision Drivers

* The distributable is a single concatenated bash script; its execution order
 must not change.
* Bash 3.0+ floor, so no clever loading tricks.
* Per-test paths are fork-free and budgeted (`.claude/rules/perf-fork-budget.md`).
* `make test` globs `tests/*/*[tT]est.sh` — exactly one level deep.

## Considered Options

* Leave `src/runner.sh` as one file
* Split into flat `src/runner_*.sh` files
* Split into a `src/runner/` directory behind a thin aggregator

## Decision Outcome

Chosen option: **`src/runner/` directory behind a thin aggregator**.

`src/runner.sh` keeps its single `source` line in the `bashunit` entrypoint and
becomes ten `source` lines plus comments. `build.sh` needs no per-module
knowledge: it already recurses into `source` lines, so the module children are
discovered through the aggregator.

This required fixing `build.sh` first (#923). Its embed dedupe was keyed on a
file's *basename*, which both hid a genuine double-embed (the top-level loop
passes repo-relative paths, the recursion absolute ones, so the two spellings
never matched) and would have collided `src/parallel.sh` with
`src/runner/parallel.sh`. The key is now the repo-relative path.

**The constraint this buys is worth stating explicitly: an aggregator 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 would run
before its dependencies in the built binary but after them in dev mode. This is
enforced by `test_module_aggregators_hold_only_source_lines_and_comments`.

Sourcing follows the dependency layering, leaves first:

```
context · payload · diagnostics → parallel · hooks · result → provider · exec → discovery · bench
```

53 of the 57 functions are leaves; only `load_test_files`, `load_bench_files`,
`run_test` and `parse_result` have callees, so the layering is acyclic.

### Positive Consequences

* Each file is 90-540 lines with one responsibility; `src/` root gains a
 directory instead of ten files.
* No runtime cost. Cold start is dominated by parse time, not file opens
 (measured in #798), and a file split adds no forks — the fork-budget
 acceptance tests pass unchanged.
* The pattern generalises: `src/coverage.sh` (2548 lines) is the next candidate.

### Negative Consequences

* Return-slot globals now cross file boundaries — `runner/payload.sh` declares
 the 13 `_BASHUNIT_RUNNER_*_OUT` slots that `runner/exec.sh` reads. ShellCheck
 can no longer see both ends, so `runner/exec.sh` needs one scoped `SC2154`
 disable for the `exit_code` assigned inside an EXIT trap body and read by
 `cleanup_on_exit` in `runner/hooks.sh`.
* One more indirection when grepping: `bashunit::runner::*` now spans ten files.

## Pros and Cons of the Options

### Leave `src/runner.sh` as one file

* Good, because zero risk and zero churn.
* Bad, because the file had five responsibilities and no seam to test them apart.

### Flat `src/runner_*.sh` files

* Good, because it needs no `build.sh` change at all.
* Bad, because it grows the flat `src/` root by ten entries and encodes the
 grouping in a filename prefix rather than in the directory structure.
* Bad, because it does not generalise — `src/coverage.sh` would add nine more.

### `src/runner/` directory behind an aggregator

* Good, because it mirrors the existing `src/assertions.sh` → `src/assert_*.sh`
 aggregator precedent, and `src/dev/debug.sh` already proved `src/` can nest.
* Good, because `build.sh` discovers children through recursion, so adding a
 module file needs no build change.
* Bad, because it required fixing the build's dedupe key first (#923).

## Links

* Enabled by [#923](https://github.com/TypedDevs/bashunit/issues/923) — repo-relative embed markers
* Tests stay flat: `make test` globs one level, so `tests/unit/runner_*_test.sh`,
 never `tests/unit/runner/`

4 changes: 2 additions & 2 deletions
src/coverage.sh

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -170,8 +170,8 @@ function bashunit::coverage::resolve_engine() {
 esac
}

# Name kept from the trap-only era: this is the seam runner.sh already calls
# around every test body and lifecycle hook.
# Name kept from the trap-only era: this is the seam runner/exec.sh and
# runner/hooks.sh already call around every test body and lifecycle hook.
function bashunit::coverage::enable_trap() {
 if ! bashunit::env::is_coverage_enabled; then
 return 0
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Remove or un-stick sticky/fixed headers that block content
(function() {
function unstick() {
document.querySelectorAll('header, nav, [role="banner"], .header, .navbar, .sticky, .fixed-top, [style*="position: fixed"], [style*="position:sticky"]').forEach(function(el) {
if (el.style.position === 'fixed' || el.style.position === 'sticky' || getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {
el.style.position = 'static';
el.style.top = 'auto';
el.style.zIndex = 'auto';
}
});
}
unstick();
var observer = new MutationObserver(unstick);
observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });
})();
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
refactor(runner): split src/runner.sh into a src/runner/ module#927

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Chemaclass
merged 2 commits into

from

Jul 30, 2026
 Merged


refactor(runner): split src/runner.sh into a src/runner/ module
#927
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
0567a48

refactor(runner): split src/runner.sh into a src/runner/ module


Chemaclass Jul 30, 2026
56ab0c6

docs: update changelog


Chemaclass Jul 30, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


14 changes: 12 additions & 2 deletions
.claude/rules/architecture-map.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -14,7 +14,7 @@ flow of a test run. Line numbers drift; function names are the stable anchors.
```
bashunit (entry) sources all src/*.sh; version gate; early flag scan
└─ bashunit::main::cmd_test (main.sh: flag parsing, env exports)
 └─ bashunit::runner::load_test_files (runner.sh: the per-file loop)
 └─ bashunit::runner::load_test_files (runner/discovery.sh: the per-file loop)
 ├─ console_header::print_header "Running N tests" — captures
 │ └─ helper::find_total_tests $() SUBSHELL: sources each file in a
 │ nested subshell just to count tests
Expand DownExpand Up@@ -48,7 +48,17 @@ shell (or, in parallel, in per-test `.result` files aggregated at the end).
| Module | Owns |
|--------|------|
| `bashunit` + `main.sh` | entry, subcommand routing, flag parsing, run lifecycle, exit codes, cleanup calls |
| `runner.sh` | file loop, per-test execution, retry/timeout, result parsing, failure context |
| `runner.sh` | aggregator only — sources the `src/runner/` module below |
| `runner/context.sh` | workdir restore, test identity/location exports, title interpolation, capability probes |
| `runner/payload.sh` | the `_BASHUNIT_RUNNER_*_OUT` return slots; encode/decode of the per-test result payload |
| `runner/diagnostics.sh` | runtime-error detection, kill-signal classification, profiling, verbose/file headers |
| `runner/result.sh` | `parse_result{,_sync,_parallel}`, failure source context, failed/skipped/incomplete/risky writers |
| `runner/parallel.sh` | job-slot waiting (`wait -n` or poll), running-job count, spinner |
| `runner/hooks.sh` | set_up/tear_down (test + script scope), hook failure records, mock clearing, EXIT cleanup |
| `runner/provider.sh` | `@data_provider` argument parsing |
| `runner/exec.sh` | `run_test`, the capture-subshell body, retry, timeout watchdog, per-file dispatch |
| `runner/discovery.sh` | `load_test_files` (the per-file loop), `functions_for_script` |
| `runner/bench.sh` | benchmark file loop and bench function dispatch |
| `helpers.sh` | discovery (`find_files_recursive`), fn filtering, provider map, duplicate check, ids |
| `state.sh` | counters, per-test payload encode/decode, TAP conversion |
| `env.sh` | all `BASHUNIT_*` defaults/config files, scratch dirs (`_BASHUNIT_RUN_OUTPUT_DIR` + EXIT-trap cleanup) |
Expand Down

2 changes: 1 addition & 1 deletion
.claude/rules/bash-style.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -118,7 +118,7 @@ local thing=$_BASHUNIT_PKG_THING_OUT
- A dedicated slot per helper (rather than one shared `_BASHUNIT_OUT`) means
 adjacent or nested calls can't clobber each other. Cheap: globals are free.

Examples in tree: `src/runner.sh` (`_BASHUNIT_RUNNER_FIELD_OUT`,
Examples in tree: `src/runner/payload.sh` (`_BASHUNIT_RUNNER_FIELD_OUT`,
`_BASHUNIT_RUNNER_TOTAL_OUT`, `_BASHUNIT_RUNNER_TYPE_OUT`, `_BASHUNIT_RUNNER_OUTPUT_OUT`),
`src/coverage.sh` (`_BASHUNIT_BRANCH_ARMS_OUT`).

Expand Down

3 changes: 3 additions & 0 deletions
CHANGELOG.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,6 +2,9 @@

## Unreleased

### Changed
- Internal: `src/runner.sh` is split into a `src/runner/` module of ten single-responsibility files behind a `source`-only aggregator. A pure relocation, no behavior change; see [ADR-010](adrs/adr-010-src-module-directories.md) (#924)

### Fixed
- `build.sh` dedupes embedded files by repo-relative path. The previous basename key compared the top-level loop's relative paths against the recursion's absolute ones, so a file reached from two places could be bundled twice in the released binary; it also collided for same-named files in different directories (#923)

Expand Down

108 changes: 108 additions & 0 deletions
adrs/adr-010-src-module-directories.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
# Splitting large `src/` files into module directories

* Status: accepted
* Deciders: Chemaclass
* Date: 2026-07-30

Technical Story: https://github.com/TypedDevs/bashunit/issues/924

## Context and Problem Statement

`src/runner.sh` had grown to 2145 lines and 57 functions covering five unrelated
responsibilities: the per-file loop, per-test execution, retry/timeout, result
parsing and failure context. Navigating it meant scrolling, and every change
touched the same file no matter which concern it belonged to.

`src/` was flat, so the obvious fix — one file per responsibility — would have
added ten more entries to an already-40-file directory. Can we group them into a
directory without changing what the released single-file binary does?

## Decision Drivers

* The distributable is a single concatenated bash script; its execution order
 must not change.
* Bash 3.0+ floor, so no clever loading tricks.
* Per-test paths are fork-free and budgeted (`.claude/rules/perf-fork-budget.md`).
* `make test` globs `tests/*/*[tT]est.sh` — exactly one level deep.

## Considered Options

* Leave `src/runner.sh` as one file
* Split into flat `src/runner_*.sh` files
* Split into a `src/runner/` directory behind a thin aggregator

## Decision Outcome

Chosen option: **`src/runner/` directory behind a thin aggregator**.

`src/runner.sh` keeps its single `source` line in the `bashunit` entrypoint and
becomes ten `source` lines plus comments. `build.sh` needs no per-module
knowledge: it already recurses into `source` lines, so the module children are
discovered through the aggregator.

This required fixing `build.sh` first (#923). Its embed dedupe was keyed on a
file's *basename*, which both hid a genuine double-embed (the top-level loop
passes repo-relative paths, the recursion absolute ones, so the two spellings
never matched) and would have collided `src/parallel.sh` with
`src/runner/parallel.sh`. The key is now the repo-relative path.

**The constraint this buys is worth stating explicitly: an aggregator 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 would run
before its dependencies in the built binary but after them in dev mode. This is
enforced by `test_module_aggregators_hold_only_source_lines_and_comments`.

Sourcing follows the dependency layering, leaves first:

```
context · payload · diagnostics → parallel · hooks · result → provider · exec → discovery · bench
```

53 of the 57 functions are leaves; only `load_test_files`, `load_bench_files`,
`run_test` and `parse_result` have callees, so the layering is acyclic.

### Positive Consequences

* Each file is 90-540 lines with one responsibility; `src/` root gains a
 directory instead of ten files.
* No runtime cost. Cold start is dominated by parse time, not file opens
 (measured in #798), and a file split adds no forks — the fork-budget
 acceptance tests pass unchanged.
* The pattern generalises: `src/coverage.sh` (2548 lines) is the next candidate.

### Negative Consequences

* Return-slot globals now cross file boundaries — `runner/payload.sh` declares
 the 13 `_BASHUNIT_RUNNER_*_OUT` slots that `runner/exec.sh` reads. ShellCheck
 can no longer see both ends, so `runner/exec.sh` needs one scoped `SC2154`
 disable for the `exit_code` assigned inside an EXIT trap body and read by
 `cleanup_on_exit` in `runner/hooks.sh`.
* One more indirection when grepping: `bashunit::runner::*` now spans ten files.

## Pros and Cons of the Options

### Leave `src/runner.sh` as one file

* Good, because zero risk and zero churn.
* Bad, because the file had five responsibilities and no seam to test them apart.

### Flat `src/runner_*.sh` files

* Good, because it needs no `build.sh` change at all.
* Bad, because it grows the flat `src/` root by ten entries and encodes the
 grouping in a filename prefix rather than in the directory structure.
* Bad, because it does not generalise — `src/coverage.sh` would add nine more.

### `src/runner/` directory behind an aggregator

* Good, because it mirrors the existing `src/assertions.sh` → `src/assert_*.sh`
 aggregator precedent, and `src/dev/debug.sh` already proved `src/` can nest.
* Good, because `build.sh` discovers children through recursion, so adding a
 module file needs no build change.
* Bad, because it required fixing the build's dedupe key first (#923).

## Links

* Enabled by [#923](https://github.com/TypedDevs/bashunit/issues/923) — repo-relative embed markers
* Tests stay flat: `make test` globs one level, so `tests/unit/runner_*_test.sh`,
 never `tests/unit/runner/`

4 changes: 2 additions & 2 deletions
src/coverage.sh

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -170,8 +170,8 @@ function bashunit::coverage::resolve_engine() {
 esac
}

# Name kept from the trap-only era: this is the seam runner.sh already calls
# around every test body and lifecycle hook.
# Name kept from the trap-only era: this is the seam runner/exec.sh and
# runner/hooks.sh already call around every test body and lifecycle hook.
function bashunit::coverage::enable_trap() {
 if ! bashunit::env::is_coverage_enabled; then
 return 0
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Universal Dark Mode - works on any site
(function() {
var enabled = true;
function applyDarkMode() {
if (!enabled) return;
// Create style element if it doesn't exist
var style = document.getElementById('universal-dark-mode-style');
if (!style) {
style = document.createElement('style');
style.id = 'universal-dark-mode-style';
document.head.appendChild(style);
}
// Dark mode CSS - inverts colors but preserves images/video
style.textContent = '
/* Invert everything except media */
html {
filter: invert(1) hue-rotate(180deg) !important;
background: #1a1a2e !important;
}
/* Restore images, videos, iframes, canvas */
img, video, iframe, canvas, svg, picture, [style*="background-image"] {
filter: invert(1) hue-rotate(180deg) !important;
}
/* Preserve specific elements that should not be inverted */
.no-dark-mode, .no-dark-mode *,
[data-theme="light"], [data-theme="light"],
.ace_editor, .ace_editor *,
.CodeMirror, .CodeMirror *,
.monaco-editor, .monaco-editor *,
.markdown-body pre, .markdown-body pre *,
.highlight, .highlight *,
pre code, pre code * {
filter: none !important;
}
/* Fix common UI elements */
.modal, .popup, .dropdown-menu, .tooltip, .popover {
filter: invert(1) hue-rotate(180deg) !important;
background: #2d2d44 !important;
border-color: #444 !important;
}
/* Scrollbars */
::-webkit-scrollbar { background: #1a1a2e !important; }
::-webkit-scrollbar-thumb { background: #444 !important; }
::-webkit-scrollbar-thumb:hover { background: #555 !important; }
/* Selection */
::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
';
}
function removeDarkMode() {
var style = document.getElementById('universal-dark-mode-style');
if (style) style.remove();
}
// Toggle with Alt+Shift+D
document.addEventListener('keydown', function(e) {
if (e.altKey && e.shiftKey && e.key === 'D') {
e.preventDefault();
enabled = !enabled;
if (enabled) {
applyDarkMode();
console.log('[Universal Dark Mode] Enabled');
} else {
removeDarkMode();
console.log('[Universal Dark Mode] Disabled');
}
}
});
// Apply on load
applyDarkMode();
// Re-apply on dynamic content
var observer = new MutationObserver(function(mutations) {
if (enabled && !document.getElementById('universal-dark-mode-style')) {
applyDarkMode();
}
});
observer.observe(document.head, { childList: true });
console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');
})();
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
refactor(runner): split src/runner.sh into a src/runner/ module#927

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Chemaclass
merged 2 commits into

from

Jul 30, 2026
 Merged


refactor(runner): split src/runner.sh into a src/runner/ module
#927
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
0567a48

refactor(runner): split src/runner.sh into a src/runner/ module


Chemaclass Jul 30, 2026
56ab0c6

docs: update changelog


Chemaclass Jul 30, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


14 changes: 12 additions & 2 deletions
.claude/rules/architecture-map.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -14,7 +14,7 @@ flow of a test run. Line numbers drift; function names are the stable anchors.
```
bashunit (entry) sources all src/*.sh; version gate; early flag scan
└─ bashunit::main::cmd_test (main.sh: flag parsing, env exports)
 └─ bashunit::runner::load_test_files (runner.sh: the per-file loop)
 └─ bashunit::runner::load_test_files (runner/discovery.sh: the per-file loop)
 ├─ console_header::print_header "Running N tests" — captures
 │ └─ helper::find_total_tests $() SUBSHELL: sources each file in a
 │ nested subshell just to count tests
Expand DownExpand Up@@ -48,7 +48,17 @@ shell (or, in parallel, in per-test `.result` files aggregated at the end).
| Module | Owns |
|--------|------|
| `bashunit` + `main.sh` | entry, subcommand routing, flag parsing, run lifecycle, exit codes, cleanup calls |
| `runner.sh` | file loop, per-test execution, retry/timeout, result parsing, failure context |
| `runner.sh` | aggregator only — sources the `src/runner/` module below |
| `runner/context.sh` | workdir restore, test identity/location exports, title interpolation, capability probes |
| `runner/payload.sh` | the `_BASHUNIT_RUNNER_*_OUT` return slots; encode/decode of the per-test result payload |
| `runner/diagnostics.sh` | runtime-error detection, kill-signal classification, profiling, verbose/file headers |
| `runner/result.sh` | `parse_result{,_sync,_parallel}`, failure source context, failed/skipped/incomplete/risky writers |
| `runner/parallel.sh` | job-slot waiting (`wait -n` or poll), running-job count, spinner |
| `runner/hooks.sh` | set_up/tear_down (test + script scope), hook failure records, mock clearing, EXIT cleanup |
| `runner/provider.sh` | `@data_provider` argument parsing |
| `runner/exec.sh` | `run_test`, the capture-subshell body, retry, timeout watchdog, per-file dispatch |
| `runner/discovery.sh` | `load_test_files` (the per-file loop), `functions_for_script` |
| `runner/bench.sh` | benchmark file loop and bench function dispatch |
| `helpers.sh` | discovery (`find_files_recursive`), fn filtering, provider map, duplicate check, ids |
| `state.sh` | counters, per-test payload encode/decode, TAP conversion |
| `env.sh` | all `BASHUNIT_*` defaults/config files, scratch dirs (`_BASHUNIT_RUN_OUTPUT_DIR` + EXIT-trap cleanup) |
Expand Down

2 changes: 1 addition & 1 deletion
.claude/rules/bash-style.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -118,7 +118,7 @@ local thing=$_BASHUNIT_PKG_THING_OUT
- A dedicated slot per helper (rather than one shared `_BASHUNIT_OUT`) means
 adjacent or nested calls can't clobber each other. Cheap: globals are free.

Examples in tree: `src/runner.sh` (`_BASHUNIT_RUNNER_FIELD_OUT`,
Examples in tree: `src/runner/payload.sh` (`_BASHUNIT_RUNNER_FIELD_OUT`,
`_BASHUNIT_RUNNER_TOTAL_OUT`, `_BASHUNIT_RUNNER_TYPE_OUT`, `_BASHUNIT_RUNNER_OUTPUT_OUT`),
`src/coverage.sh` (`_BASHUNIT_BRANCH_ARMS_OUT`).

Expand Down

3 changes: 3 additions & 0 deletions
CHANGELOG.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,6 +2,9 @@

## Unreleased

### Changed
- Internal: `src/runner.sh` is split into a `src/runner/` module of ten single-responsibility files behind a `source`-only aggregator. A pure relocation, no behavior change; see [ADR-010](adrs/adr-010-src-module-directories.md) (#924)

### Fixed
- `build.sh` dedupes embedded files by repo-relative path. The previous basename key compared the top-level loop's relative paths against the recursion's absolute ones, so a file reached from two places could be bundled twice in the released binary; it also collided for same-named files in different directories (#923)

Expand Down

108 changes: 108 additions & 0 deletions
adrs/adr-010-src-module-directories.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
# Splitting large `src/` files into module directories

* Status: accepted
* Deciders: Chemaclass
* Date: 2026-07-30

Technical Story: https://github.com/TypedDevs/bashunit/issues/924

## Context and Problem Statement

`src/runner.sh` had grown to 2145 lines and 57 functions covering five unrelated
responsibilities: the per-file loop, per-test execution, retry/timeout, result
parsing and failure context. Navigating it meant scrolling, and every change
touched the same file no matter which concern it belonged to.

`src/` was flat, so the obvious fix — one file per responsibility — would have
added ten more entries to an already-40-file directory. Can we group them into a
directory without changing what the released single-file binary does?

## Decision Drivers

* The distributable is a single concatenated bash script; its execution order
 must not change.
* Bash 3.0+ floor, so no clever loading tricks.
* Per-test paths are fork-free and budgeted (`.claude/rules/perf-fork-budget.md`).
* `make test` globs `tests/*/*[tT]est.sh` — exactly one level deep.

## Considered Options

* Leave `src/runner.sh` as one file
* Split into flat `src/runner_*.sh` files
* Split into a `src/runner/` directory behind a thin aggregator

## Decision Outcome

Chosen option: **`src/runner/` directory behind a thin aggregator**.

`src/runner.sh` keeps its single `source` line in the `bashunit` entrypoint and
becomes ten `source` lines plus comments. `build.sh` needs no per-module
knowledge: it already recurses into `source` lines, so the module children are
discovered through the aggregator.

This required fixing `build.sh` first (#923). Its embed dedupe was keyed on a
file's *basename*, which both hid a genuine double-embed (the top-level loop
passes repo-relative paths, the recursion absolute ones, so the two spellings
never matched) and would have collided `src/parallel.sh` with
`src/runner/parallel.sh`. The key is now the repo-relative path.

**The constraint this buys is worth stating explicitly: an aggregator 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 would run
before its dependencies in the built binary but after them in dev mode. This is
enforced by `test_module_aggregators_hold_only_source_lines_and_comments`.

Sourcing follows the dependency layering, leaves first:

```
context · payload · diagnostics → parallel · hooks · result → provider · exec → discovery · bench
```

53 of the 57 functions are leaves; only `load_test_files`, `load_bench_files`,
`run_test` and `parse_result` have callees, so the layering is acyclic.

### Positive Consequences

* Each file is 90-540 lines with one responsibility; `src/` root gains a
 directory instead of ten files.
* No runtime cost. Cold start is dominated by parse time, not file opens
 (measured in #798), and a file split adds no forks — the fork-budget
 acceptance tests pass unchanged.
* The pattern generalises: `src/coverage.sh` (2548 lines) is the next candidate.

### Negative Consequences

* Return-slot globals now cross file boundaries — `runner/payload.sh` declares
 the 13 `_BASHUNIT_RUNNER_*_OUT` slots that `runner/exec.sh` reads. ShellCheck
 can no longer see both ends, so `runner/exec.sh` needs one scoped `SC2154`
 disable for the `exit_code` assigned inside an EXIT trap body and read by
 `cleanup_on_exit` in `runner/hooks.sh`.
* One more indirection when grepping: `bashunit::runner::*` now spans ten files.

## Pros and Cons of the Options

### Leave `src/runner.sh` as one file

* Good, because zero risk and zero churn.
* Bad, because the file had five responsibilities and no seam to test them apart.

### Flat `src/runner_*.sh` files

* Good, because it needs no `build.sh` change at all.
* Bad, because it grows the flat `src/` root by ten entries and encodes the
 grouping in a filename prefix rather than in the directory structure.
* Bad, because it does not generalise — `src/coverage.sh` would add nine more.

### `src/runner/` directory behind an aggregator

* Good, because it mirrors the existing `src/assertions.sh` → `src/assert_*.sh`
 aggregator precedent, and `src/dev/debug.sh` already proved `src/` can nest.
* Good, because `build.sh` discovers children through recursion, so adding a
 module file needs no build change.
* Bad, because it required fixing the build's dedupe key first (#923).

## Links

* Enabled by [#923](https://github.com/TypedDevs/bashunit/issues/923) — repo-relative embed markers
* Tests stay flat: `make test` globs one level, so `tests/unit/runner_*_test.sh`,
 never `tests/unit/runner/`

4 changes: 2 additions & 2 deletions
src/coverage.sh

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -170,8 +170,8 @@ function bashunit::coverage::resolve_engine() {
 esac
}

# Name kept from the trap-only era: this is the seam runner.sh already calls
# around every test body and lifecycle hook.
# Name kept from the trap-only era: this is the seam runner/exec.sh and
# runner/hooks.sh already call around every test body and lifecycle hook.
function bashunit::coverage::enable_trap() {
 if ! bashunit::env::is_coverage_enabled; then
 return 0
Expand Down
Loading
Loading