Background
bashunit doc lists the 71 built-in assertions, and shell completions offer the same set. A project's own custom assertions appear in neither, so the discoverability story stops at the boundary where a team's assertions actually live.
The constraint is that bashunit doc is a static dump, not a registry: bashunit::doc::get_embedded_docs (src/doc.sh:7) cats docs/assertions.md, and build.sh swaps that for a heredoc in the single-file binary. There is nowhere for a user assertion to register itself.
Proposal
Add a runtime scan alongside the embedded docs, rather than trying to bend the embedded docs to hold user content.
- After the bootstrap file has been sourced, collect declared functions matching
assert_* that are not part of the built-in set.
- For each, print its name and its leading comment block, in the same shape
bashunit doc already uses.
- Surface it as
bashunit doc --custom (custom only) with the plain bashunit doc appending a "Custom assertions" section when a bootstrap defines any.
Completions can reuse the same list.
Notes
- Requires
--boot / BASHUNIT_BOOTSTRAP to be set, since that is the only point where user assertions are guaranteed loaded. Worth documenting that link on the custom-asserts page either way.
- Lowest value of the custom-assert items and the one most in need of a design call before implementation. Filed so the idea is not lost, not because it is ready to build.
- Depends on nothing else, but reads better once the custom-asserts docs are refreshed.
Part of a custom-asserts DX set, each sized as its own PR:
Background
bashunit doclists the 71 built-in assertions, and shell completions offer the same set. A project's own custom assertions appear in neither, so the discoverability story stops at the boundary where a team's assertions actually live.The constraint is that
bashunit docis a static dump, not a registry:bashunit::doc::get_embedded_docs(src/doc.sh:7)catsdocs/assertions.md, andbuild.shswaps that for a heredoc in the single-file binary. There is nowhere for a user assertion to register itself.Proposal
Add a runtime scan alongside the embedded docs, rather than trying to bend the embedded docs to hold user content.
assert_*that are not part of the built-in set.bashunit docalready uses.bashunit doc --custom(custom only) with the plainbashunit docappending a "Custom assertions" section when a bootstrap defines any.Completions can reuse the same list.
Notes
--boot/BASHUNIT_BOOTSTRAPto be set, since that is the only point where user assertions are guaranteed loaded. Worth documenting that link on the custom-asserts page either way.Part of a custom-asserts DX set, each sized as its own PR:
bashunit doc#918 listing project assertions inbashunit doc