feat(doc): list a project's own assertions in `bashunit doc` by Chemaclass · Pull Request #922 · TypedDevs/bashunit

Chemaclass · 2026-07-29T05:27:12Z

🤔 Background

Related #918

bashunit doc lists only the built-in assertions, so the discoverability story stops at the boundary where a team's own assertions actually live.

💡 Changes

bashunit doc --custom lists the assertions your project defines; plain bashunit doc appends them as a Custom assertions section. Both honour a filter.
bashunit doc now accepts -e, --env, --boot <file> and BASHUNIT_BOOTSTRAP — a bootstrap is the only point where user assertions are guaranteed loaded.
The built-in set is never hardcoded: the command snapshots compgen -A function assert_ before sourcing the bootstrap, so the two lists cannot drift apart.
Entries render the comment block above each definition, located via declare -F with extdebug confined to the capture subshell (fix(runner): stop get_function_line_number clobbering caller extdebug #808) and the file read once rather than one sed per line (perf(runner): read failing-test body once for Source: context #807).
The completions anti-drift contract now derives cmd_doc's flags as well, instead of only cmd_test's.

`bashunit doc` listed only the built-in assertions, so discoverability stopped exactly where a team's own assertions live. Add `--custom` to list them, and make plain `bashunit doc` append a "Custom assertions" section when a bootstrap defines any. `bashunit doc` now accepts `-e | --env | --boot <file>` and honours `BASHUNIT_BOOTSTRAP`, since a bootstrap is the only point where user assertions are guaranteed loaded. The built-in set is not hardcoded: cmd_doc snapshots `compgen -A function assert_` before sourcing the bootstrap, and whatever appears afterwards is the project's own, so the two lists can never drift apart. Each entry renders the comment block immediately above the definition, located via `declare -F` with extdebug enabled inside the capture subshell only -- toggling it in the caller's shell clobbers caller state (#808). The file is read once into an array rather than with a `sed -n Np` per line, which is the quadratic pattern removed in #807. The custom list is insertion-sorted in pure bash rather than piped through `LC_ALL=C sort`: that prefix is banned in src/ because bash 5.3.9 on macOS segfaults on it inside a command substitution (#912), and the list is tiny enough that the fork was not worth it either. The completions anti-drift contract only knew about cmd_test's flags, so a doc-only flag had nowhere correct to live. It now derives cmd_doc's flags too: the zsh expectation is the union (that script advertises everything from one _arguments block) and the bash script carries them in their own variable with its own parity test. Closes#918

Chemaclass · 2026-07-29T05:27:12Z

🤔 Background

Related #918

bashunit doc lists only the built-in assertions, so the discoverability story stops at the boundary where a team's own assertions actually live.

💡 Changes

bashunit doc --custom lists the assertions your project defines; plain bashunit doc appends them as a Custom assertions section. Both honour a filter.
bashunit doc now accepts -e, --env, --boot <file> and BASHUNIT_BOOTSTRAP — a bootstrap is the only point where user assertions are guaranteed loaded.
The built-in set is never hardcoded: the command snapshots compgen -A function assert_ before sourcing the bootstrap, so the two lists cannot drift apart.
Entries render the comment block above each definition, located via declare -F with extdebug confined to the capture subshell (fix(runner): stop get_function_line_number clobbering caller extdebug #808) and the file read once rather than one sed per line (perf(runner): read failing-test body once for Source: context #807).
The completions anti-drift contract now derives cmd_doc's flags as well, instead of only cmd_test's.

`bashunit doc` listed only the built-in assertions, so discoverability stopped exactly where a team's own assertions live. Add `--custom` to list them, and make plain `bashunit doc` append a "Custom assertions" section when a bootstrap defines any. `bashunit doc` now accepts `-e | --env | --boot <file>` and honours `BASHUNIT_BOOTSTRAP`, since a bootstrap is the only point where user assertions are guaranteed loaded. The built-in set is not hardcoded: cmd_doc snapshots `compgen -A function assert_` before sourcing the bootstrap, and whatever appears afterwards is the project's own, so the two lists can never drift apart. Each entry renders the comment block immediately above the definition, located via `declare -F` with extdebug enabled inside the capture subshell only -- toggling it in the caller's shell clobbers caller state (#808). The file is read once into an array rather than with a `sed -n Np` per line, which is the quadratic pattern removed in #807. The custom list is insertion-sorted in pure bash rather than piped through `LC_ALL=C sort`: that prefix is banned in src/ because bash 5.3.9 on macOS segfaults on it inside a command substitution (#912), and the list is tiny enough that the fork was not worth it either. The completions anti-drift contract only knew about cmd_test's flags, so a doc-only flag had nowhere correct to live. It now derives cmd_doc's flags too: the zsh expectation is the union (that script advertises everything from one _arguments block) and the bash script carries them in their own variable with its own parity test. Closes#918

Chemaclass · 2026-07-29T05:27:12Z

🤔 Background

Related #918

bashunit doc lists only the built-in assertions, so the discoverability story stops at the boundary where a team's own assertions actually live.

💡 Changes

bashunit doc --custom lists the assertions your project defines; plain bashunit doc appends them as a Custom assertions section. Both honour a filter.
bashunit doc now accepts -e, --env, --boot <file> and BASHUNIT_BOOTSTRAP — a bootstrap is the only point where user assertions are guaranteed loaded.
The built-in set is never hardcoded: the command snapshots compgen -A function assert_ before sourcing the bootstrap, so the two lists cannot drift apart.
Entries render the comment block above each definition, located via declare -F with extdebug confined to the capture subshell (fix(runner): stop get_function_line_number clobbering caller extdebug #808) and the file read once rather than one sed per line (perf(runner): read failing-test body once for Source: context #807).
The completions anti-drift contract now derives cmd_doc's flags as well, instead of only cmd_test's.

`bashunit doc` listed only the built-in assertions, so discoverability stopped exactly where a team's own assertions live. Add `--custom` to list them, and make plain `bashunit doc` append a "Custom assertions" section when a bootstrap defines any. `bashunit doc` now accepts `-e | --env | --boot <file>` and honours `BASHUNIT_BOOTSTRAP`, since a bootstrap is the only point where user assertions are guaranteed loaded. The built-in set is not hardcoded: cmd_doc snapshots `compgen -A function assert_` before sourcing the bootstrap, and whatever appears afterwards is the project's own, so the two lists can never drift apart. Each entry renders the comment block immediately above the definition, located via `declare -F` with extdebug enabled inside the capture subshell only -- toggling it in the caller's shell clobbers caller state (#808). The file is read once into an array rather than with a `sed -n Np` per line, which is the quadratic pattern removed in #807. The custom list is insertion-sorted in pure bash rather than piped through `LC_ALL=C sort`: that prefix is banned in src/ because bash 5.3.9 on macOS segfaults on it inside a command substitution (#912), and the list is tiny enough that the fork was not worth it either. The completions anti-drift contract only knew about cmd_test's flags, so a doc-only flag had nowhere correct to live. It now derives cmd_doc's flags too: the zsh expectation is the union (that script advertises everything from one _arguments block) and the bash script carries them in their own variable with its own parity test. Closes#918

Chemaclass · 2026-07-29T05:27:12Z

🤔 Background

Related #918

bashunit doc lists only the built-in assertions, so the discoverability story stops at the boundary where a team's own assertions actually live.

💡 Changes

bashunit doc --custom lists the assertions your project defines; plain bashunit doc appends them as a Custom assertions section. Both honour a filter.
bashunit doc now accepts -e, --env, --boot <file> and BASHUNIT_BOOTSTRAP — a bootstrap is the only point where user assertions are guaranteed loaded.
The built-in set is never hardcoded: the command snapshots compgen -A function assert_ before sourcing the bootstrap, so the two lists cannot drift apart.
Entries render the comment block above each definition, located via declare -F with extdebug confined to the capture subshell (fix(runner): stop get_function_line_number clobbering caller extdebug #808) and the file read once rather than one sed per line (perf(runner): read failing-test body once for Source: context #807).
The completions anti-drift contract now derives cmd_doc's flags as well, instead of only cmd_test's.

`bashunit doc` listed only the built-in assertions, so discoverability stopped exactly where a team's own assertions live. Add `--custom` to list them, and make plain `bashunit doc` append a "Custom assertions" section when a bootstrap defines any. `bashunit doc` now accepts `-e | --env | --boot <file>` and honours `BASHUNIT_BOOTSTRAP`, since a bootstrap is the only point where user assertions are guaranteed loaded. The built-in set is not hardcoded: cmd_doc snapshots `compgen -A function assert_` before sourcing the bootstrap, and whatever appears afterwards is the project's own, so the two lists can never drift apart. Each entry renders the comment block immediately above the definition, located via `declare -F` with extdebug enabled inside the capture subshell only -- toggling it in the caller's shell clobbers caller state (#808). The file is read once into an array rather than with a `sed -n Np` per line, which is the quadratic pattern removed in #807. The custom list is insertion-sorted in pure bash rather than piped through `LC_ALL=C sort`: that prefix is banned in src/ because bash 5.3.9 on macOS segfaults on it inside a command substitution (#912), and the list is tiny enough that the fork was not worth it either. The completions anti-drift contract only knew about cmd_test's flags, so a doc-only flag had nowhere correct to live. It now derives cmd_doc's flags too: the zsh expectation is the union (that script advertises everything from one _arguments block) and the bash script carries them in their own variable with its own parity test. Closes#918

Chemaclass · 2026-07-29T05:27:12Z

🤔 Background

Related #918

bashunit doc lists only the built-in assertions, so the discoverability story stops at the boundary where a team's own assertions actually live.

💡 Changes

bashunit doc --custom lists the assertions your project defines; plain bashunit doc appends them as a Custom assertions section. Both honour a filter.
bashunit doc now accepts -e, --env, --boot <file> and BASHUNIT_BOOTSTRAP — a bootstrap is the only point where user assertions are guaranteed loaded.
The built-in set is never hardcoded: the command snapshots compgen -A function assert_ before sourcing the bootstrap, so the two lists cannot drift apart.
Entries render the comment block above each definition, located via declare -F with extdebug confined to the capture subshell (fix(runner): stop get_function_line_number clobbering caller extdebug #808) and the file read once rather than one sed per line (perf(runner): read failing-test body once for Source: context #807).
The completions anti-drift contract now derives cmd_doc's flags as well, instead of only cmd_test's.

`bashunit doc` listed only the built-in assertions, so discoverability stopped exactly where a team's own assertions live. Add `--custom` to list them, and make plain `bashunit doc` append a "Custom assertions" section when a bootstrap defines any. `bashunit doc` now accepts `-e | --env | --boot <file>` and honours `BASHUNIT_BOOTSTRAP`, since a bootstrap is the only point where user assertions are guaranteed loaded. The built-in set is not hardcoded: cmd_doc snapshots `compgen -A function assert_` before sourcing the bootstrap, and whatever appears afterwards is the project's own, so the two lists can never drift apart. Each entry renders the comment block immediately above the definition, located via `declare -F` with extdebug enabled inside the capture subshell only -- toggling it in the caller's shell clobbers caller state (#808). The file is read once into an array rather than with a `sed -n Np` per line, which is the quadratic pattern removed in #807. The custom list is insertion-sorted in pure bash rather than piped through `LC_ALL=C sort`: that prefix is banned in src/ because bash 5.3.9 on macOS segfaults on it inside a command substitution (#912), and the list is tiny enough that the fork was not worth it either. The completions anti-drift contract only knew about cmd_test's flags, so a doc-only flag had nowhere correct to live. It now derives cmd_doc's flags too: the zsh expectation is the union (that script advertises everything from one _arguments block) and the bash script carries them in their own variable with its own parity test. Closes#918

Chemaclass · 2026-07-29T05:27:12Z

🤔 Background

Related #918

bashunit doc lists only the built-in assertions, so the discoverability story stops at the boundary where a team's own assertions actually live.

💡 Changes

bashunit doc --custom lists the assertions your project defines; plain bashunit doc appends them as a Custom assertions section. Both honour a filter.
bashunit doc now accepts -e, --env, --boot <file> and BASHUNIT_BOOTSTRAP — a bootstrap is the only point where user assertions are guaranteed loaded.
The built-in set is never hardcoded: the command snapshots compgen -A function assert_ before sourcing the bootstrap, so the two lists cannot drift apart.
Entries render the comment block above each definition, located via declare -F with extdebug confined to the capture subshell (fix(runner): stop get_function_line_number clobbering caller extdebug #808) and the file read once rather than one sed per line (perf(runner): read failing-test body once for Source: context #807).
The completions anti-drift contract now derives cmd_doc's flags as well, instead of only cmd_test's.

`bashunit doc` listed only the built-in assertions, so discoverability stopped exactly where a team's own assertions live. Add `--custom` to list them, and make plain `bashunit doc` append a "Custom assertions" section when a bootstrap defines any. `bashunit doc` now accepts `-e | --env | --boot <file>` and honours `BASHUNIT_BOOTSTRAP`, since a bootstrap is the only point where user assertions are guaranteed loaded. The built-in set is not hardcoded: cmd_doc snapshots `compgen -A function assert_` before sourcing the bootstrap, and whatever appears afterwards is the project's own, so the two lists can never drift apart. Each entry renders the comment block immediately above the definition, located via `declare -F` with extdebug enabled inside the capture subshell only -- toggling it in the caller's shell clobbers caller state (#808). The file is read once into an array rather than with a `sed -n Np` per line, which is the quadratic pattern removed in #807. The custom list is insertion-sorted in pure bash rather than piped through `LC_ALL=C sort`: that prefix is banned in src/ because bash 5.3.9 on macOS segfaults on it inside a command substitution (#912), and the list is tiny enough that the fork was not worth it either. The completions anti-drift contract only knew about cmd_test's flags, so a doc-only flag had nowhere correct to live. It now derives cmd_doc's flags too: the zsh expectation is the union (that script advertises everything from one _arguments block) and the bash script carries them in their own variable with its own parity test. Closes#918

Chemaclass · 2026-07-29T05:27:12Z

🤔 Background

Related #918

bashunit doc lists only the built-in assertions, so the discoverability story stops at the boundary where a team's own assertions actually live.

💡 Changes

bashunit doc --custom lists the assertions your project defines; plain bashunit doc appends them as a Custom assertions section. Both honour a filter.
bashunit doc now accepts -e, --env, --boot <file> and BASHUNIT_BOOTSTRAP — a bootstrap is the only point where user assertions are guaranteed loaded.
The built-in set is never hardcoded: the command snapshots compgen -A function assert_ before sourcing the bootstrap, so the two lists cannot drift apart.
Entries render the comment block above each definition, located via declare -F with extdebug confined to the capture subshell (fix(runner): stop get_function_line_number clobbering caller extdebug #808) and the file read once rather than one sed per line (perf(runner): read failing-test body once for Source: context #807).
The completions anti-drift contract now derives cmd_doc's flags as well, instead of only cmd_test's.

`bashunit doc` listed only the built-in assertions, so discoverability stopped exactly where a team's own assertions live. Add `--custom` to list them, and make plain `bashunit doc` append a "Custom assertions" section when a bootstrap defines any. `bashunit doc` now accepts `-e | --env | --boot <file>` and honours `BASHUNIT_BOOTSTRAP`, since a bootstrap is the only point where user assertions are guaranteed loaded. The built-in set is not hardcoded: cmd_doc snapshots `compgen -A function assert_` before sourcing the bootstrap, and whatever appears afterwards is the project's own, so the two lists can never drift apart. Each entry renders the comment block immediately above the definition, located via `declare -F` with extdebug enabled inside the capture subshell only -- toggling it in the caller's shell clobbers caller state (#808). The file is read once into an array rather than with a `sed -n Np` per line, which is the quadratic pattern removed in #807. The custom list is insertion-sorted in pure bash rather than piped through `LC_ALL=C sort`: that prefix is banned in src/ because bash 5.3.9 on macOS segfaults on it inside a command substitution (#912), and the list is tiny enough that the fork was not worth it either. The completions anti-drift contract only knew about cmd_test's flags, so a doc-only flag had nowhere correct to live. It now derives cmd_doc's flags too: the zsh expectation is the union (that script advertises everything from one _arguments block) and the bash script carries them in their own variable with its own parity test. Closes#918

Chemaclass · 2026-07-29T05:27:12Z

🤔 Background

Related #918

bashunit doc lists only the built-in assertions, so the discoverability story stops at the boundary where a team's own assertions actually live.

💡 Changes

bashunit doc --custom lists the assertions your project defines; plain bashunit doc appends them as a Custom assertions section. Both honour a filter.
bashunit doc now accepts -e, --env, --boot <file> and BASHUNIT_BOOTSTRAP — a bootstrap is the only point where user assertions are guaranteed loaded.
The built-in set is never hardcoded: the command snapshots compgen -A function assert_ before sourcing the bootstrap, so the two lists cannot drift apart.
Entries render the comment block above each definition, located via declare -F with extdebug confined to the capture subshell (fix(runner): stop get_function_line_number clobbering caller extdebug #808) and the file read once rather than one sed per line (perf(runner): read failing-test body once for Source: context #807).
The completions anti-drift contract now derives cmd_doc's flags as well, instead of only cmd_test's.

`bashunit doc` listed only the built-in assertions, so discoverability stopped exactly where a team's own assertions live. Add `--custom` to list them, and make plain `bashunit doc` append a "Custom assertions" section when a bootstrap defines any. `bashunit doc` now accepts `-e | --env | --boot <file>` and honours `BASHUNIT_BOOTSTRAP`, since a bootstrap is the only point where user assertions are guaranteed loaded. The built-in set is not hardcoded: cmd_doc snapshots `compgen -A function assert_` before sourcing the bootstrap, and whatever appears afterwards is the project's own, so the two lists can never drift apart. Each entry renders the comment block immediately above the definition, located via `declare -F` with extdebug enabled inside the capture subshell only -- toggling it in the caller's shell clobbers caller state (#808). The file is read once into an array rather than with a `sed -n Np` per line, which is the quadratic pattern removed in #807. The custom list is insertion-sorted in pure bash rather than piped through `LC_ALL=C sort`: that prefix is banned in src/ because bash 5.3.9 on macOS segfaults on it inside a command substitution (#912), and the list is tiny enough that the fork was not worth it either. The completions anti-drift contract only knew about cmd_test's flags, so a doc-only flag had nowhere correct to live. It now derives cmd_doc's flags too: the zsh expectation is the union (that script advertises everything from one _arguments block) and the bash script carries them in their own variable with its own parity test. Closes#918