From a33514b33423c94c9fd83f6df43915d6fac44b23 Mon Sep 17 00:00:00 2001
From: Chemaclass <chemaclass@outlook.es>
Date: Wed, 29 Jul 2026 07:26:58 +0200
Subject: [PATCH] feat(doc): list a project's own assertions in bashunit doc

`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
---
 CHANGELOG.md                                  |   1 +
 completions/_bashunit                         |   1 +
 completions/bashunit.bash                     |  12 ++
 docs/command-line.md                          |  16 +-
 docs/custom-asserts.md                        |  36 +++++
 src/console_header.sh                         |   7 +-
 src/doc.sh                                    | 140 ++++++++++++++++++
 src/main.sh                                   |  61 +++++++-
 tests/acceptance/bashunit_doc_custom_test.sh  |  82 ++++++++++
 .../acceptance/fixtures/custom_assert_docs.sh |  23 +++
 tests/unit/completions_test.sh                |  29 +++-
 11 files changed, 398 insertions(+), 10 deletions(-)
 create mode 100644 tests/acceptance/bashunit_doc_custom_test.sh
 create mode 100644 tests/acceptance/fixtures/custom_assert_docs.sh

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 438cb8cf..4d66b960 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,7 @@
 ## Unreleased
 
 ### Added
+- `bashunit doc --custom` lists the assertions your own project defines, rendering the comment block above each one; plain `bashunit doc` appends them as a "Custom assertions" section. Needs `--boot` / `BASHUNIT_BOOTSTRAP`, which `bashunit doc` now accepts (#918)
 - `bashunit::assert_once <label> <actual>` makes a composed custom assertion count and report once instead of once per inner step, with its own label rather than the internal step's message. Opt-in, so existing totals are unchanged (#917)
 - `assert_assertion_passes`, `assert_assertion_fails` and `assert_assertion_fails_with <message>` test a custom assertion for the verdict it reports. The inner assertion runs isolated — its counters, output and stop-on-failure guard are restored — so testing a failing assertion no longer means rebuilding the expected string from `bashunit::console_results::print_failed_test` (#916)
 - `bashunit::assert_that <expected> <actual> <cmd> [args...]` writes a custom assertion in one call: it runs the command and marks the assertion passed or failed, so the two counters can no longer drift apart by a forgotten `return` or a missing `bashunit::assertion_passed` (#915)
diff --git a/completions/_bashunit b/completions/_bashunit
index 31477610..8f8374db 100644
--- a/completions/_bashunit
+++ b/completions/_bashunit
@@ -59,6 +59,7 @@ _bashunit() {
   fi
 
   _arguments \
+    '--custom[Show only the assertions your project defines]' \
     '(-a --assert)'{-a,--assert}'[Run a standalone assert function]:function:' \
     '(-e --env --boot)'{-e,--env,--boot}'[Load a custom env/bootstrap file]:file:_files' \
     '(-f --filter)'{-f,--filter}'[Only run tests matching the name]:name:' \
diff --git a/completions/bashunit.bash b/completions/bashunit.bash
index 353a2d95..2285a328 100644
--- a/completions/bashunit.bash
+++ b/completions/bashunit.bash
@@ -10,6 +10,9 @@
 
 _BASHUNIT_COMPLETIONS_SUBCOMMANDS="test bench doc init learn upgrade assert watch"
 
+# Flags accepted by the doc subcommand.
+_BASHUNIT_COMPLETIONS_DOC_OPTS="--custom -e --env --boot -h --help"
+
 _BASHUNIT_COMPLETIONS_TEST_OPTS="--assert --boot --coverage --coverage-exclude \
 --coverage-min --coverage-paths --coverage-report --coverage-report-html \
 --debug --detailed --env --exclude-tag --fail-on-risky --failures-only \
@@ -82,6 +85,15 @@ _bashunit_completions() {
     return 0
   fi
 
+  # `bashunit doc <filter>` completes assertion names, plus its own flags.
+  if [ "$COMP_CWORD" -ge 2 ] && [ "${COMP_WORDS[1]}" = "doc" ]; then
+    case "$cur" in
+    -*) COMPREPLY=($(compgen -W "$_BASHUNIT_COMPLETIONS_DOC_OPTS" -- "$cur")) ;;
+    *) COMPREPLY=($(compgen -W "$_BASHUNIT_COMPLETIONS_ASSERT_FNS" -- "$cur")) ;;
+    esac
+    return 0
+  fi
+
   # First word: subcommands (plus flags, since `test` is the default command).
   if [ "$COMP_CWORD" -eq 1 ] && [ "${cur#-}" = "$cur" ]; then
     COMPREPLY=($(compgen -W "$_BASHUNIT_COMPLETIONS_SUBCOMMANDS" -- "$cur"))
diff --git a/docs/command-line.md b/docs/command-line.md
index b3c6b527..49766ad5 100644
--- a/docs/command-line.md
+++ b/docs/command-line.md
@@ -13,7 +13,7 @@ bashunit test [path] [options]    # Run tests (default)
 bashunit bench [path] [options]   # Run benchmarks
 bashunit watch [path] [options]   # Watch files, re-run tests on change
 bashunit assert <fn> <args>       # Run standalone assertion
-bashunit doc [filter]             # Show assertion documentation
+bashunit doc [options] [filter]   # Show assertion documentation
 bashunit init [dir]               # Initialize test directory
 bashunit learn                    # Interactive tutorial
 bashunit upgrade                  # Upgrade to latest version
@@ -890,10 +890,19 @@ also uses polling.
 
 ## doc
 
-> `bashunit doc [filter]`
+> `bashunit doc [options] [filter]`
 
 Display documentation for assertion functions.
 
+| Option | Description |
+|--------|-------------|
+| `--custom` | Show only the assertions your project defines |
+| `-e, --env, --boot <file>` | Load a bootstrap file defining custom assertions |
+
+With a bootstrap loaded, `bashunit doc` appends a **Custom assertions** section
+rendering the comment block above each of your own `assert_*` functions. See
+[Custom asserts](/custom-asserts).
+
 ::: code-group
 ```bash [Examples]
 # Show all assertions
@@ -904,6 +913,9 @@ bashunit doc equals
 
 # Show file-related assertions
 bashunit doc file
+
+# Show only your project's assertions
+bashunit doc --custom --boot tests/bootstrap.sh
 ```
 ```[Output]
 ## assert_equals
diff --git a/docs/custom-asserts.md b/docs/custom-asserts.md
index d8c8c7d8..62a24b10 100644
--- a/docs/custom-asserts.md
+++ b/docs/custom-asserts.md
@@ -302,6 +302,42 @@ source "$(dirname "${BASH_SOURCE[0]}")/custom_asserts.sh"
 See [Configuration](/configuration) and [Command line](/command-line) for the
 full bootstrap options.
 
+## Listing your assertions
+
+`bashunit doc` prints the built-in catalogue. Once a bootstrap defines your own
+assertions, it appends them too, rendering the comment block above each one:
+
+```bash
+./bashunit doc --boot tests/bootstrap.sh     # built-ins, then a "Custom assertions" section
+./bashunit doc --custom --boot tests/bootstrap.sh  # only your own
+./bashunit doc --custom http                 # ...narrowed by a filter
+```
+
+```
+## assert_http_success
+--------------
+Asserts that the status code is a 2xx.
+```
+
+With `BASHUNIT_BOOTSTRAP` set, the `--boot` flag can be omitted. A bootstrap is
+required either way: it is the only point at which your assertions are
+guaranteed loaded, which is another reason to prefer it over sourcing from
+`set_up`.
+
+Write the docstring as a plain comment block immediately above the function —
+the same shape the built-ins use:
+
+```bash
+# Asserts that the status code is a 2xx.
+# Arguments: $1 - the status code
+function assert_http_success() {
+  bashunit::assert_once "a 2xx status" "$1"
+
+  assert_greater_or_equal_than "200" "$1"
+  assert_less_than "300" "$1"
+}
+```
+
 ## Best practices
 
 1. **Prefer `bashunit::assert_that`**: one call marks the assertion passed or failed, so you cannot forget the `return` after a failure (which would bump both counters) or forget `bashunit::assertion_passed` (which would leave the test with zero assertions, reported as risky).
diff --git a/src/console_header.sh b/src/console_header.sh
index e8c31382..6050397e 100644
--- a/src/console_header.sh
+++ b/src/console_header.sh
@@ -208,17 +208,22 @@ EOF
 
 function bashunit::console_header::print_doc_help() {
   cat <<EOF
-Usage: bashunit doc [filter]
+Usage: bashunit doc [options] [filter]
 
 Display documentation for assertion functions.
 
 Arguments:
 filter                      Optional filter to show only matching assertions
 
+Options:
+--custom                    Show only the assertions your project defines
+-e, --env, --boot <file>    Load a bootstrap file defining custom assertions
+
 Examples:
 bashunit doc                Show all assertions
 bashunit doc equals         Show assertions containing 'equals'
 bashunit doc file           Show file-related assertions
+bashunit doc --custom       Show only your project's own assertions
 EOF
 }
 
diff --git a/src/doc.sh b/src/doc.sh
index f168af14..21697884 100644
--- a/src/doc.sh
+++ b/src/doc.sh
@@ -56,3 +56,143 @@ function bashunit::doc::print_asserts() {
     }
   '
 }
+
+##
+# Collects the assert_* functions a bootstrap defined, i.e. those declared now
+# that were not declared before it was sourced, into
+# _BASHUNIT_DOC_CUSTOM_FNS_OUT (newline separated, sorted).
+#
+# Diffing against a snapshot rather than a hardcoded list means the built-in set
+# never has to be maintained in two places.
+# Arguments: $1 - newline separated assert_* names known before the bootstrap
+##
+_BASHUNIT_DOC_CUSTOM_FNS_OUT=""
+
+function bashunit::doc::custom_fns_to_slot() {
+  local known="$1"
+  # Declare and assign separately: bash 3.0 does not expand a compound array
+  # assignment attached to `local`.
+  local -a found
+  found=()
+  local count=0
+  local fn
+
+  for fn in $(compgen -A function assert_ 2>/dev/null); do
+    case "
+$known
+" in
+    *"
+$fn
+"*) continue ;;
+    esac
+
+    # Insertion sort. A project's own assertion list is tiny, so this beats a
+    # `sort` fork -- and `LC_ALL=C sort` is banned in src/ because bash 5.3.9 on
+    # macOS segfaults on that prefix inside a command substitution (#912).
+    local i=$count
+    while [ "$i" -gt 0 ] && [ "${found[$((i - 1))]}" \> "$fn" ]; do
+      found[i]=${found[$((i - 1))]}
+      i=$((i - 1))
+    done
+    found[i]=$fn
+    count=$((count + 1))
+  done
+
+  local out=""
+  local j=0
+  while [ "$j" -lt "$count" ]; do
+    out="$out${found[j]}"$'\n'
+    j=$((j + 1))
+  done
+
+  _BASHUNIT_DOC_CUSTOM_FNS_OUT="${out%$'\n'}"
+}
+
+##
+# Prints the leading comment block of a function, with the comment markers
+# stripped. Silent when the function has no comment or was defined somewhere
+# unreadable (e.g. sourced from a process substitution).
+# Arguments: $1 - function name
+##
+function bashunit::doc::print_fn_comment() {
+  local fn="$1"
+
+  # extdebug is toggled inside the subshell only: enabling it in the caller's
+  # shell clobbers caller state (#808).
+  local info
+  info="$(
+    shopt -s extdebug
+    declare -F "$fn"
+  )"
+
+  local rest="${info#* }"
+  local def_line="${rest%% *}"
+  local file="${rest#* }"
+
+  case "$def_line" in
+  '' | *[!0-9]*) return 0 ;;
+  esac
+  [ -n "$file" ] && [ -f "$file" ] || return 0
+
+  # Read the file once into an array; walking backwards needs random access and
+  # a per-line `sed -n Np` loop is exactly the quadratic pattern #807 removed.
+  local -a lines
+  lines=()
+  local count=0
+  local line
+  while IFS= read -r line || [ -n "$line" ]; do
+    lines[count]="$line"
+    count=$((count + 1))
+  done <"$file"
+
+  # Collect the comment run immediately above the definition, then print it in
+  # source order.
+  local first=$((def_line - 1))
+  local i=$((first - 1))
+  while [ "$i" -ge 0 ]; do
+    case "${lines[i]:-}" in
+    '#'*) i=$((i - 1)) ;;
+    *) break ;;
+    esac
+  done
+
+  local j=$((i + 1))
+  while [ "$j" -lt "$first" ]; do
+    line="${lines[j]:-}"
+    # Strip the marker: "## " fences render as blank, "# text" as "text".
+    line="${line#\#}"
+    line="${line#\#}"
+    line="${line# }"
+    printf '%s\n' "$line"
+    j=$((j + 1))
+  done
+}
+
+##
+# Prints the custom assertions defined by a bootstrap, in the shape
+# bashunit::doc::print_asserts already uses.
+# Arguments: $1 - optional filter
+# Returns: 0 when at least one was printed, 1 when there were none
+##
+function bashunit::doc::print_custom_asserts() {
+  local filter="${1:-}"
+  local printed=1
+  local fn
+
+  for fn in $_BASHUNIT_DOC_CUSTOM_FNS_OUT; do
+    if [ -n "$filter" ]; then
+      case "$fn" in
+      *"$filter"*) ;;
+      *) continue ;;
+      esac
+    fi
+
+    printf '## %s\n' "$fn"
+    printf -- '--------------\n'
+    bashunit::doc::print_fn_comment "$fn"
+    printf '\n'
+    printed=0
+  done
+
+  return $printed
+}
diff --git a/src/main.sh b/src/main.sh
index a6cc91b7..fb66c493 100644
--- a/src/main.sh
+++ b/src/main.sh
@@ -733,14 +733,63 @@ function bashunit::main::cmd_bench() {
 # Subcommand: doc
 #############################
 function bashunit::main::cmd_doc() {
-  case "${1:-}" in
-  -h | --help)
-    bashunit::console_header::print_doc_help
+  local filter=""
+  local custom_only=false
+  local boot_file="${BASHUNIT_BOOTSTRAP:-}"
+
+  while [ $# -gt 0 ]; do
+    case "$1" in
+    -h | --help)
+      bashunit::console_header::print_doc_help
+      exit 0
+      ;;
+    --custom)
+      custom_only=true
+      shift
+      ;;
+    -e | --env | --boot)
+      boot_file="${2:-}"
+      shift 2
+      ;;
+    *)
+      filter="$1"
+      shift
+      ;;
+    esac
+  done
+
+  # Snapshot before sourcing: whatever assert_* appears afterwards is the
+  # project's own.
+  local known
+  known="$(compgen -A function assert_ 2>/dev/null)"
+
+  if [ -n "$boot_file" ]; then
+    if [ ! -r "$boot_file" ]; then
+      printf "%sError: cannot read the bootstrap file: '%s'.%s\n" \
+        "$_BASHUNIT_COLOR_FAILED" "$boot_file" "$_BASHUNIT_COLOR_DEFAULT" >&2
+      exit 1
+    fi
+    # shellcheck disable=SC1090,SC2086
+    source "$boot_file" ${BASHUNIT_BOOTSTRAP_ARGS:-}
+  fi
+
+  bashunit::doc::custom_fns_to_slot "$known"
+
+  if [ "$custom_only" = true ]; then
+    if ! bashunit::doc::print_custom_asserts "$filter"; then
+      printf 'No custom assertions found.\n'
+      printf 'Load them with --boot <file> or BASHUNIT_BOOTSTRAP.\n'
+    fi
     exit 0
-    ;;
-  esac
+  fi
+
+  bashunit::doc::print_asserts "$filter"
+
+  if [ -n "$_BASHUNIT_DOC_CUSTOM_FNS_OUT" ]; then
+    printf '\n## Custom assertions\n\n'
+    bashunit::doc::print_custom_asserts "$filter" || true
+  fi
 
-  bashunit::doc::print_asserts "${1:-}"
   exit 0
 }
 
diff --git a/tests/acceptance/bashunit_doc_custom_test.sh b/tests/acceptance/bashunit_doc_custom_test.sh
new file mode 100644
index 00000000..d28127d3
--- /dev/null
+++ b/tests/acceptance/bashunit_doc_custom_test.sh
@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+
+BOOT="tests/acceptance/fixtures/custom_assert_docs.sh"
+
+function test_doc_custom_lists_the_project_assertions() {
+  local output
+  output=$(./bashunit doc --custom --boot "$BOOT" 2>&1) || true
+
+  assert_contains "## assert_positive_number" "$output"
+  assert_contains "## assert_http_success" "$output"
+}
+
+function test_doc_custom_renders_the_leading_comment_block() {
+  local output
+  output=$(./bashunit doc --custom --boot "$BOOT" 2>&1) || true
+
+  assert_contains "Asserts that the value is a number greater than zero." "$output"
+  assert_contains "Arguments: \$1 - the value under test" "$output"
+  assert_contains "Asserts that the status code is a 2xx." "$output"
+}
+
+function test_doc_custom_skips_functions_that_are_not_assertions() {
+  local output
+  output=$(./bashunit doc --custom --boot "$BOOT" 2>&1) || true
+
+  assert_not_contains "helper_not_an_assertion" "$output"
+}
+
+function test_doc_custom_does_not_list_the_built_in_assertions() {
+  local output
+  output=$(./bashunit doc --custom --boot "$BOOT" 2>&1) || true
+
+  assert_not_contains "## assert_same" "$output"
+  assert_not_contains "## assert_line_count" "$output"
+}
+
+function test_doc_custom_without_a_bootstrap_reports_none() {
+  local output
+  output=$(./bashunit doc --custom 2>&1) || true
+
+  assert_contains "No custom assertions" "$output"
+}
+
+function test_doc_custom_without_a_bootstrap_still_exits_zero() {
+  local exit_code=0
+
+  ./bashunit doc --custom >/dev/null 2>&1 || exit_code=$?
+
+  assert_same "0" "$exit_code"
+}
+
+function test_doc_appends_a_custom_section_when_a_bootstrap_defines_any() {
+  local output
+  output=$(./bashunit doc --boot "$BOOT" 2>&1) || true
+
+  # Built-in catalogue still there, custom section appended after it.
+  assert_contains "## assert_same" "$output"
+  assert_contains "Custom assertions" "$output"
+  assert_contains "## assert_positive_number" "$output"
+}
+
+function test_doc_without_a_bootstrap_has_no_custom_section() {
+  local output
+  output=$(./bashunit doc 2>&1) || true
+
+  assert_not_contains "Custom assertions" "$output"
+}
+
+function test_doc_custom_honours_a_filter() {
+  local output
+  output=$(./bashunit doc --custom --boot "$BOOT" http 2>&1) || true
+
+  assert_contains "## assert_http_success" "$output"
+  assert_not_contains "## assert_positive_number" "$output"
+}
+
+function test_doc_custom_reports_an_unreadable_bootstrap() {
+  local output
+  output=$(./bashunit doc --custom --boot "does/not/exist.sh" 2>&1) || true
+
+  assert_contains "cannot read the bootstrap file" "$output"
+}
diff --git a/tests/acceptance/fixtures/custom_assert_docs.sh b/tests/acceptance/fixtures/custom_assert_docs.sh
new file mode 100644
index 00000000..0e58f534
--- /dev/null
+++ b/tests/acceptance/fixtures/custom_assert_docs.sh
@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+
+# A bootstrap defining project assertions, used to check that `bashunit doc`
+# picks them up and renders their leading comment block.
+
+# Asserts that the value is a number greater than zero.
+# Arguments: $1 - the value under test
+function assert_positive_number() {
+  bashunit::assert_that "positive number" "$1" test "$1" -gt 0
+}
+
+# Asserts that the status code is a 2xx.
+function assert_http_success() {
+  bashunit::assert_once "a 2xx status" "$1"
+
+  assert_greater_or_equal_than "200" "$1"
+  assert_less_than "300" "$1"
+}
+
+# Not an assertion, so it must not be listed.
+function helper_not_an_assertion() {
+  return 0
+}
diff --git a/tests/unit/completions_test.sh b/tests/unit/completions_test.sh
index b29c262f..0ad81011 100644
--- a/tests/unit/completions_test.sh
+++ b/tests/unit/completions_test.sh
@@ -16,6 +16,16 @@ function completions_expected_test_flags() {
     LC_ALL=C sort -u
 }
 
+# Flags accepted by cmd_doc, straight from its option-parsing case arms. The
+# zsh script advertises every flag from one _arguments block, so its expected
+# set is the union of the test and doc flags.
+function completions_expected_doc_flags() {
+  awk '/^function bashunit::main::cmd_doc\(\)/,/^}$/' src/main.sh |
+    grep -E '^[[:space:]]+--?[a-zA-Z][a-zA-Z0-9-]*( \| --?[a-zA-Z][a-zA-Z0-9-]*)*\)' |
+    sed 's/)$//' | tr -d ' ' | tr '|' '\n' |
+    LC_ALL=C sort -u
+}
+
 function completions_expected_assert_functions() {
   grep -hoE '^function assert_[a-z_0-9]+' src/assert*.sh |
     sed 's/^function //' | LC_ALL=C sort -u
@@ -64,12 +74,29 @@ function test_bash_completion_flags_match_main_sh() {
 
 function test_zsh_completion_flags_match_main_sh() {
   local expected actual
-  expected=$(completions_expected_test_flags)
+  expected=$(
+    {
+      completions_expected_test_flags
+      completions_expected_doc_flags
+    } | LC_ALL=C sort -u
+  )
   actual=$(completions_zsh_flags)
 
   assert_same "$expected" "$actual"
 }
 
+function test_bash_completion_doc_flags_match_main_sh() {
+  local expected actual
+  expected=$(completions_expected_doc_flags)
+  actual=$(
+    # shellcheck source=/dev/null
+    source "$BASH_COMPLETION_FILE" 2>/dev/null
+    echo "$_BASHUNIT_COMPLETIONS_DOC_OPTS" | tr ' ' '\n' | grep -v '^$' | LC_ALL=C sort -u
+  )
+
+  assert_same "$expected" "$actual"
+}
+
 function test_bash_completion_lists_all_subcommands() {
   local subcommands
   subcommands=$(