feat(doc): list a project's own assertions in bashunit doc - #922
Merged
Conversation
`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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🤔 Background
Related #918
bashunit doclists only the built-in assertions, so the discoverability story stops at the boundary where a team's own assertions actually live.💡 Changes
bashunit doc --customlists the assertions your project defines; plainbashunit docappends them as a Custom assertions section. Both honour a filter.bashunit docnow accepts-e, --env, --boot <file>andBASHUNIT_BOOTSTRAP— a bootstrap is the only point where user assertions are guaranteed loaded.compgen -A function assert_before sourcing the bootstrap, so the two lists cannot drift apart.declare -Fwithextdebugconfined to the capture subshell (fix(runner): stop get_function_line_number clobbering caller extdebug #808) and the file read once rather than onesedper line (perf(runner): read failing-test body once for Source: context #807).cmd_doc's flags as well, instead of onlycmd_test's.