@renault-digital/bash-base 2.4.1 → 2.5.1

package/scripts/test-shell-compat.sh

@@ -0,0 +1,391 @@
+#!/usr/bin/env bash
+set -u
+
+ROOT="${BASH_BASE_ROOT:-$(cd "$(dirname "$0")/.." && pwd)}"
+ALLOW_NO_ZSH="${ALLOW_NO_ZSH:-0}"
+
+pass=0
+fail=0
+
+ok() {
+	printf 'PASS  %s\n' "$1"
+	pass=$((pass + 1))
+}
+bad() {
+	printf 'FAIL  %s\n' "$1" >&2
+	fail=$((fail + 1))
+}
+
+printf 'Bash/zsh bash-base compatibility tests\n'
+printf 'Root: %s\n\n' "$ROOT"
+
+src_files=(
+	alias.sh argument.sh array.sh constant.sh document.sh
+	out.sh process.sh reflection.sh string.sh tool.sh
+)
+
+for f in "${src_files[@]}"; do
+	if bash -n "$ROOT/src/$f"; then
+		ok "bash syntax: $f"
+	else
+		bad "bash syntax: $f"
+	fi
+done
+
+if command -v zsh >/dev/null 2>&1; then
+	for f in "${src_files[@]}"; do
+		if zsh -n "$ROOT/src/$f"; then
+			ok "zsh syntax: $f"
+		else
+			bad "zsh syntax: $f"
+		fi
+	done
+else
+	if [[ "$ALLOW_NO_ZSH" == 1 ]]; then
+		printf 'SKIP  zsh syntax/runtime checks (zsh unavailable)\n'
+	else
+		bad "zsh is required for shared-shell verification"
+	fi
+fi
+
+# Source-level guards for constructs intentionally removed from the shared code.
+# Comments are stripped before matching so explanatory text does not trigger.
+active="$({
+	for f in "${src_files[@]}"; do
+		sed -E '/^[[:space:]]*#/d' "$ROOT/src/$f"
+	done
+} 2>/dev/null)"
+
+static_bad=0
+for pattern in \
+	'read[[:space:]].*-p' \
+	'\$\{[^}]*\^\^\}' \
+	'\$\{[^}]*,,\}' \
+	'\$\{[^}]*\^\}' \
+	'\$\{![^}]+\}' \
+	'(^|[[:space:]])declare[[:space:]]+-' \
+	'export[[:space:]]+-f' \
+	'(^|[[:space:]])shopt([[:space:]]|$)' \
+	'(^|[[:space:]])setopt([[:space:]]|$)' \
+	'(^|[[:space:]])\[[[:space:]].*[[:space:]]==[[:space:]]'
+do
+	if printf '%s\n' "$active" | grep -Eq "$pattern"; then
+		printf 'Static forbidden pattern matched: %s\n' "$pattern" >&2
+		static_bad=1
+	fi
+done
+
+if ((static_bad == 0)); then
+	ok "no known Bash-only/zsh-only constructs in active library code"
+else
+	bad "shared-syntax static scan"
+fi
+
+# Function declarations should use the common name() form.
+if grep -RInE '^[[:space:]]*function[[:space:]]+' "$ROOT/src" >/dev/null 2>&1; then
+	bad "function keyword remains in active source declarations"
+else
+	ok "common function declaration syntax"
+fi
+
+runtime_payload="$(mktemp "${TMPDIR:-/tmp}/bash-base-runtime.XXXXXX")" || exit 1
+trap 'rm -f "$runtime_payload"' EXIT INT TERM HUP
+cat >"$runtime_payload" <<'PAYLOAD'
+set -u
+root="$1"
+cd "$root"
+
+source src/constant.sh
+source src/out.sh
+source src/tool.sh
+source src/string.sh
+source src/array.sh
+source src/reflection.sh
+source src/argument.sh
+source src/process.sh
+source src/document.sh
+source src/alias.sh
+
+expected_script_name="${0##*/}"
+
+runtime_failures=0
+assert_eq() {
+    local name="$1" expected="$2" actual="$3"
+    if [[ "$actual" != "$expected" ]]; then
+        printf 'ASSERT FAIL [%s]\nexpected: <%s>\nactual:   <%s>\n' "$name" "$expected" "$actual" >&2
+        runtime_failures=$((runtime_failures + 1))
+        return 1
+    fi
+}
+
+assert_status() {
+    local name="$1" expected="$2" actual="$3"
+    if [[ "$actual" != "$expected" ]]; then
+        printf 'ASSERT FAIL [%s] expected status %s got %s\n' "$name" "$expected" "$actual" >&2
+        runtime_failures=$((runtime_failures + 1))
+        return 1
+    fi
+}
+
+assert_eq script_name "$expected_script_name" "$THIS_SCRIPT_NAME"
+assert_eq upper ABC "$(string_upper aBc)"
+assert_eq lower abc "$(string_lower aBc)"
+assert_eq upper_first Abc "$(string_upper_first aBc)"
+assert_eq substring 's fd' "$(string_sub 2 -1 ' as fd ')"
+assert_eq substring_negative_start 'fd' "$(string_sub -3 -1 ' as fd ')"
+assert_eq substring_empty '' "$(string_sub 0 0 'abc')"
+assert_eq substring_out_of_range '' "$(string_sub -99 -1 'abc')"
+
+# The heredoc may contain shell quotes and command syntax as plain text.
+declare_heredoc literal_heredoc <<'LITERAL_HEREDOC'
+It's text: $(printf NEVER_EXECUTE); "quoted".
+LITERAL_HEREDOC
+assert_eq literal_heredoc 'It'"'"'s text: $(printf NEVER_EXECUTE); "quoted".' "$literal_heredoc"
+
+arr=(' a ' ' b c ')
+assert_eq array_join ' a | b c ' "$(array_join '|' arr)"
+array_contains arr ' b c '
+assert_status array_contains 0 "$?"
+
+arr_sort=('bb' 'aa' 'aa')
+array_sort arr_sort
+assert_eq array_sort 'aa|aa|bb' "$(array_join '|' arr_sort)"
+
+array_equal_a=('bb' 'aa')
+array_equal_b=('aa' 'bb')
+array_equals array_equal_a array_equal_b true
+assert_status array_equals 0 "$?"
+
+left=('aa' 'bb' 'aa' 'cc')
+right=('aa' 'aa' 'dd' 'bb')
+array_union left right union_result
+assert_eq array_union 'aa|bb|cc|dd' "$(array_join '|' union_result)"
+
+remove_arr=('a' ' b' 'c' 'a b' 'f' 'g')
+array_remove remove_arr 'a b'
+assert_eq array_remove 'a| b|c|f|g' "$(array_join '|' remove_arr)"
+
+map_arr=(' a ' " b '(c ")
+array_map map_arr 'string_trim | wc -m | string_trim' mapped
+assert_eq array_map '2|6' "$(array_join '|' mapped)"
+
+filter_arr=('NAME' 'NAME B' 'OTHER')
+array_filter filter_arr 'NAME' filtered
+assert_eq array_filter 'NAME|NAME B' "$(array_join '|' filtered)"
+
+# array_describe/array_from_describe use each shell's own declaration format;
+# round-trip behavior, not declaration spelling, is the cross-shell contract.
+desc="$(array_describe arr)"
+array_from_describe roundtrip "$desc"
+assert_eq array_roundtrip ' a | b c ' "$(array_join '|' roundtrip)"
+
+# Bash regression: public array-by-name APIs must not shadow legitimate names.
+values=('a' 'b')
+assert_eq name_values_join 'a|b' "$(array_join '|' values)"
+array_contains values b
+assert_status name_values_contains 0 "$?"
+array_map values string_upper mapped_values
+assert_eq name_values_map 'A|B' "$(array_join '|' mapped_values)"
+array_filter values a filtered_values
+assert_eq name_values_filter 'a' "$(array_join '|' filtered_values)"
+source=('a' 'b')
+other=('b')
+array_intersection source other inter false
+assert_eq name_source_intersection 'b' "$(array_join '|' inter)"
+array_subtract source other subtracted false
+assert_eq name_source_subtract 'a' "$(array_join '|' subtracted)"
+source1=('a')
+array_union source1 other combined false
+assert_eq name_source1_union 'a|b' "$(array_join '|' combined)"
+source2=('b')
+left_also=('a')
+array_union left_also source2 combined false
+assert_eq name_source2_union 'a|b' "$(array_join '|' combined)"
+kept=(a b c)
+array_remove kept b
+assert_eq name_kept_remove 'a|c' "$(array_join '|' kept)"
+
+# Exercise the historical Bash 3.2 `typeset -p` format even on newer
+# Bash runners. Only the mocked builtin call is scoped to this subshell.
+if [[ -n "${BASH_VERSION:-}" ]]; then
+    legacy_roundtrip="$(
+        typeset() {
+            if [[ "${1-}" == -p && "${2-}" == arr ]]; then
+                printf '%s\n' "declare -a arr='([0]=\" a \" [1]=\" b c \")'"
+            else
+                builtin typeset "$@"
+            fi
+        }
+        legacy_desc="$(array_describe arr)"
+        array_from_describe legacy_restored "$legacy_desc" || exit 1
+        array_join '|' legacy_restored
+    )"
+    assert_eq array_legacy_bash32_roundtrip ' a | b c ' "$legacy_roundtrip"
+fi
+
+assert_eq reflect_nth_arg 'ha ho' "$(reflect_nth_arg 3 'ab cdv "ha ho"')"
+assert_eq reflect_nth_arg_complex 'SIA (lowercase, 3 chars)' "$(reflect_nth_arg 4 'args_valid_or_read myVar '\''^[0-9a-z]{3,3}$'\'' "SIA (lowercase, 3 chars)"')"
+reflect_get_function_definition reflect_nth_arg >/dev/null
+reflect_search_function '^reflect_nth_arg$' | grep -qx 'reflect_nth_arg'
+reflect_search_variable '^COLOR_BLUE$' | grep -qx 'COLOR_BLUE'
+
+set -- "param 1" "param 2"
+args_parse $# "$@" var1 var2
+assert_eq args_parse_var1 'param 1' "$var1"
+assert_eq args_parse_var2 'param 2' "$var2"
+
+positionalValue='OLD'
+args_parse 1 X positionalValue
+assert_eq args_parse_shadow_positionalValue X "$positionalValue"
+prompt='OLD'
+args_parse 1 Y prompt
+assert_eq args_parse_shadow_prompt Y "$prompt"
+
+if [[ -n "${BASH_VERSION:-}" ]]; then
+    # Legacy Bash output and implicit shell-state behavior; zsh uses its own semantics.
+    assert_eq reflect_zero 0 "$(reflect_nth_arg 0 'a b c')"
+    assert_eq reflect_oob '' "$(set +u; reflect_nth_arg 99 'a b c')"
+    mapped_input=('-n' 'b')
+    array_map mapped_input cat mapped_output
+    assert_eq map_legacy_echo '|'"b" "$(array_join '|' mapped_output)"
+    display_name='  abc  '
+    expected_display="$(printf '%-30.30s%s' 'display_name:' "${COLOR_BLUE}abc${COLOR_END}")"
+    assert_eq print_args_legacy_spaces "$expected_display" "$(print_args display_name)"
+    default_name='  abc  '
+    args_valid_or_default default_name '^.*abc.*$' desc >/dev/null
+    assert_eq args_default_legacy_spaces abc "$default_name"
+    read_out="$(printf '  abc  \n' | args_valid_or_read read_name '^.+$' 'enter')"
+    assert_eq args_read_legacy_spaces "Inputted value: ${COLOR_BLUE}'abc'${COLOR_END}" "$read_out"
+    proposed_out="$(args_valid_or_read proposed_name '^.+$' 'enter' '  foo  ' <<<'')"
+    assert_eq args_read_legacy_proposed "Inputted value: ${COLOR_BLUE}'foo'${COLOR_END}" "$proposed_out"
+    default_name=''
+    fallback_out="$(args_valid_or_default default_name '^.+$' desc 'a   b')"
+    if [[ "$fallback_out" != *"Inputted value: ${COLOR_BLUE}'a b'${COLOR_END}"* ]]; then
+        printf 'ASSERT FAIL [args_default_legacy_fallback] %s\n' "$fallback_out" >&2
+        runtime_failures=$((runtime_failures + 1))
+    fi
+    # Bash 4+/5+ case conversion must use native locale-sensitive rules.
+    if ((BASH_VERSINFO[0] >= 4)); then
+        utf8_locale="$(locale -a 2>/dev/null | grep -Ei -m1 '^(en_US\.UTF-8|C\.utf-?8|fr_FR\.UTF-8)$' || :)"
+        if [[ -n "$utf8_locale" ]]; then
+            original_upper="$(LC_ALL="$utf8_locale" bash -c 'v=école; echo "${v^^}"')"
+            if [[ "$original_upper" == 'ÉCOLE' ]]; then
+                assert_eq upper_legacy_unicode ÉCOLE "$(LC_ALL="$utf8_locale" string_upper école)"
+                assert_eq lower_legacy_unicode école "$(LC_ALL="$utf8_locale" string_lower ÉCOLE)"
+                assert_eq first_legacy_unicode École "$(LC_ALL="$utf8_locale" string_upper_first éCOLE)"
+            fi
+        fi
+    fi
+fi
+
+# read -r must use default IFS so Bash continues to accept spaced confirmations.
+modeQuiet=false
+spaced_yes="$(printf '  y  \n' | confirm_to_continue)"
+assert_eq confirm_spaced_yes 'Continue...' "$spaced_yes"
+
+sel='abc'
+select_out="$(printf '%s\n' 2 | args_valid_or_select_args sel 'which value' a ab d | grep 'Selected value')"
+assert_eq args_select "Selected value: ${COLOR_BLUE}'ab'${COLOR_END}" "$select_out"
+
+modeQuiet=false
+read_out="$(printf '%s\n' 70022 | args_valid_or_read irn '^[0-9]{5,5}$' 'IRN')"
+assert_eq args_valid_or_read "Inputted value: ${COLOR_BLUE}'70022'${COLOR_END}" "$read_out"
+
+irn=70033
+default_out="$(args_valid_or_default irn '^[0-9]{5,5}$' 'IRN' 70088)"
+assert_eq args_valid_or_default "Inputted value: ${COLOR_BLUE}'70033'${COLOR_END}" "$default_out"
+assert_eq args_valid_or_default_value 70033 "$irn"
+
+modeQuiet=true
+quiet_out="$(confirm_to_continue)"
+assert_eq confirm_quiet '' "$quiet_out"
+
+modeQuiet=false
+yes_out="$(printf '%s\n' y | confirm_to_continue)"
+assert_eq confirm_yes 'Continue...' "$yes_out"
+
+# Legacy names intentionally remain callable, but are wrapper functions rather
+# than shell aliases so non-interactive Bash/zsh behavior is deterministic.
+modeQuiet=true
+assert_eq args_confirm '' "$(args_confirm)"
+var1='value 1'
+assert_eq args_print "var1:                         ${COLOR_BLUE}value 1${COLOR_END}" "$(args_print var1)"
+
+# Both old and new function declaration styles must remain discoverable.
+cat > "${TMPDIR:-/tmp}/bash-base-reflect-test.$$" <<'EOS'
+old_style() { :; }
+function legacy_style() { :; }
+EOS
+names="$(reflect_function_names_of_file "${TMPDIR:-/tmp}/bash-base-reflect-test.$$")"
+rm -f "${TMPDIR:-/tmp}/bash-base-reflect-test.$$"
+printf '%s\n' "$names" | grep -qx old_style
+printf '%s\n' "$names" | grep -qx legacy_style
+
+if ((runtime_failures > 0)); then
+    printf 'RUNTIME ASSERTIONS FAILED: %s\n' "$runtime_failures" >&2
+    exit 1
+fi
+printf 'RUNTIME PASS\n'
+PAYLOAD
+
+run_runtime() {
+	local shell_name="$1" shell_bin="$2"
+	local output rc
+	output="$($shell_bin "$runtime_payload" "$ROOT" 2>&1)"
+	rc=$?
+	if [[ $rc -eq 0 && "$output" == *'RUNTIME PASS'* ]]; then
+		ok "$shell_name runtime behavior"
+	else
+		bad "$shell_name runtime behavior"
+		printf '%s\n' "$output" >&2
+	fi
+}
+
+run_runtime Bash bash
+if command -v zsh >/dev/null 2>&1; then
+	run_runtime zsh zsh
+fi
+
+# args_parse scans the caller script for args_valid_* rules. In zsh, function
+# execution can change $0, so exercise this through a real script rather than
+# only calling args_parse from the smoke-test function body.
+metadata_script="$(mktemp "${TMPDIR:-/tmp}/bash-base-args-metadata.XXXXXX")" || exit 1
+cat >"$metadata_script" <<'META'
+root="$1"
+shift
+cd "$root" || exit 1
+source src/constant.sh
+source src/out.sh
+source src/tool.sh
+source src/string.sh
+source src/array.sh
+source src/reflection.sh
+source src/argument.sh
+args_parse $# "$@" destination region
+args_valid_or_read destination '^ok$' 'validated destination'
+META
+
+run_metadata_test() {
+	local shell_name="$1" shell_bin="$2"
+	local output rc
+	output="$($shell_bin "$metadata_script" "$ROOT" -h 2>&1)"
+	rc=$?
+	if [[ $rc -eq 0 &&
+		"$output" == *'validated destination'* &&
+		"$output" == *'"destinationValue" "regionValue"'* &&
+		"$output" != *'destinationValue\" \"regionValue'* ]]; then
+		ok "$shell_name args_parse caller-script metadata/help rendering"
+	else
+		bad "$shell_name args_parse caller-script metadata/help rendering"
+		printf '%s\n' "$output" >&2
+	fi
+}
+
+run_metadata_test Bash bash
+if command -v zsh >/dev/null 2>&1; then
+	run_metadata_test zsh zsh
+fi
+rm -f "$metadata_script"
+
+printf '\n%d passed, %d failed\n' "$pass" "$fail"
+((fail == 0))

package/scripts/test.sh

@@ -1,21 +1,89 @@
 #!/usr/bin/env bash
 
-# use this script to check if bash-base is compatible with your bash and environment
+# Verify Bash/zsh compatibility first, then run the historical Bash ShellSpec
+# suite. Pin the test framework version across macOS and GitHub Actions.
 
-# Mac OSX
-if ! [ -f "$HOME"/.local/lib/shellspec/shellspec ]; then
-	brew install kcov
-	curl -fsSL https://git.io/shellspec | sh -s 0.27.2 --yes
+set -u
+set -o pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT" || exit 1
+
+bash scripts/test-shell-compat.sh || exit $?
+
+shellspec_version=0.28.1
+shellspec_dir="$HOME/.local/lib/shellspec"
+shellspec_bin="$shellspec_dir/shellspec"
+
+installed_version=''
+if [[ -f "$shellspec_bin" ]]; then
+	installed_version="$(bash "$shellspec_bin" --version 2>/dev/null || true)"
+fi
+
+if [[ "$installed_version" != "$shellspec_version" ]]; then
+	# Existing git installations can switch versions without deleting the
+	# installation directory or breaking the ~/.local/bin/shellspec link.
+	if [[ -d "$shellspec_dir/.git" ]]; then
+		curl -fsSL https://git.io/shellspec |
+			sh -s "$shellspec_version" --switch --yes || exit $?
+	elif [[ ! -e "$shellspec_dir" ]]; then
+		curl -fsSL https://git.io/shellspec |
+			sh -s "$shellspec_version" --yes || exit $?
+	else
+		printf '%s\n' \
+			"ERROR: $shellspec_dir exists but is not a ShellSpec git installation." \
+			'Cannot safely switch its version automatically.' >&2
+		exit 1
+	fi
+fi
+
+# Fail closed if installation/switching did not select the pinned version.
+installed_version="$(bash "$shellspec_bin" --version 2>/dev/null || true)"
+if [[ "$installed_version" != "$shellspec_version" ]]; then
+	printf 'ERROR: expected ShellSpec %s, got %s\n' \
+		"$shellspec_version" "${installed_version:-<not installed>}" >&2
+	exit 1
 fi
-bash -c 'echo BASH_VERSION: $BASH_VERSION'
-bash "$HOME"/.local/lib/shellspec/shellspec "$@" spec/*.spec.sh
 
-# Uninstall shellspec:
-# rm -fr $HOME/.local/bin/shellspec
-# rm -fr $HOME/.local/lib/shellspec
+# Preserve the original optional Homebrew kcov setup for local macOS coverage.
+# Normal `npm test` does not require kcov.
+for arg in "$@"; do
+	if [[ "$arg" == --kcov ]] && ! command -v kcov >/dev/null 2>&1; then
+		if [[ "$(uname -s)" == Darwin ]]; then
+			if ! command -v brew >/dev/null 2>&1; then
+				printf '%s\n' 'ERROR: Homebrew is required to install kcov on macOS.' >&2
+				exit 1
+			fi
+			brew install kcov || exit $?
+		else
+			printf '%s\n' 'ERROR: kcov is required for --kcov.' >&2
+			exit 1
+		fi
+	fi
+done
+
+# On macOS, kcov 43 can fail to attach to ShellSpec's test executor when
+# RLIMIT_NOFILE is exceptionally high (observed soft limit: 1048576). A
+# temporary 256-descriptor soft limit allowed ShellSpec --kcov to complete.
+# This script is executed as a child process, so the caller's limit is intact.
+# Apply only when coverage is explicitly requested; normal tests are unchanged.
+if [[ "$(uname -s)" == Darwin ]]; then
+	for arg in "$@"; do
+		if [[ "$arg" == --kcov ]]; then
+			if ! ulimit -Sn 256; then
+				printf '%s\n' 'ERROR: unable to set macOS kcov soft FD limit to 256.' >&2
+				exit 1
+			fi
+			printf 'macOS kcov soft FD limit: %s\n' "$(ulimit -Sn)"
+			break
+		fi
+	done
+fi
 
-# Debian
-#docker run --rm -v "$(pwd)":/bash-base -w /bash-base shellspec/shellspec-debian:0.27-kcov "$@" spec/*.spec.sh
+printf 'ShellSpec version: %s\n' "$installed_version"
+printf 'BASH_VERSION: %s\n' "$BASH_VERSION"
 
-# Alpine
-#docker run --rm -v "$(pwd)":/bash-base -w /bash-base shellspec/shellspec:0.27-kcov "$@" spec/*.spec.sh
+# Since ShellSpec 0.28.0, explicitly named specfiles are still filtered by
+# --pattern. Our historical files are named *.spec.sh (not *_spec.sh).
+# --fail-no-examples prevents an empty test run from reporting success.
+bash "$shellspec_bin" --pattern '*.spec.sh' --fail-no-examples "$@" spec/*.spec.sh

package/spec/array.spec.sh

@@ -278,13 +278,19 @@ Describe 'array_from_describe'
     strDescribe="([1]=' as' [5]='fd ')"
     It 'with value'
         When call array_from_describe actual "${strDescribe}"
-        The value "$(declare -p actual)" should eq "declare -a actual=([1]=\" as\" [5]=\"fd \")"
+        The status should be success
+        The value "${#actual[@]}" should eq "2"
+        The value "${actual[1]}" should eq " as"
+        The value "${actual[5]}" should eq "fd "
     End
 
     It 'with file'
         echo "${strDescribe}" > temp_file.txt
         When call eval "array_from_describe actual < temp_file.txt"
-        The value "$(declare -p actual)" should eq "declare -a actual=([1]=\" as\" [5]=\"fd \")"
+        The status should be success
+        The value "${#actual[@]}" should eq "2"
+        The value "${actual[1]}" should eq " as"
+        The value "${actual[5]}" should eq "fd "
         rm -fr temp_file.txt
     End
 End

package/spec/coverage_edges.spec.sh

@@ -0,0 +1,88 @@
+#shellcheck shell=bash
+# Targeted coverage/regression tests for reachable Bash/zsh edge cases.
+# Keep the Bash legacy behavior for reflect_nth_arg unchanged.
+
+Include src/string.sh
+Include src/reflection.sh
+Include src/argument.sh
+
+coverage_not_zsh() {
+    [[ -z "${ZSH_VERSION:-}" ]]
+}
+
+coverage_bash_4_or_later() {
+    [[ -n "${BASH_VERSION:-}" ]] && (( BASH_VERSINFO[0] >= 4 ))
+}
+
+coverage_source_argument() {
+    . src/argument.sh
+    [[ -n "${THIS_SCRIPT_PATH:-}" && -n "${THIS_SCRIPT_NAME:-}" ]]
+}
+
+Describe 'coverage edge branches with observable behavior'
+    It 'zsh rejects a nonnumeric reflect_nth_arg index'
+        Skip if 'zsh-specific return status' coverage_not_zsh
+        When call reflect_nth_arg invalid alpha beta
+        The status should eq 1
+        The output should eq ''
+    End
+
+    It 'zsh rejects an out-of-range reflect_nth_arg index'
+        Skip if 'zsh-specific return status' coverage_not_zsh
+        When call reflect_nth_arg 99 alpha beta
+        The status should eq 1
+        The output should eq ''
+    End
+
+    It 'returns empty output for an out-of-range substring start'
+        When call string_sub 99 1 abc
+        The status should eq 0
+        The output should eq ''
+    End
+
+    It 'rejects an invalid negative substring length on the portable path'
+        # Bash 4+ follows native substring expansion semantics and can abort
+        # the calling shell on an invalid negative length. This test targets
+        # only the Bash 3.2 / zsh portable fallback, and must not change Bash 4+.
+        Skip if 'Bash 4+ uses native substring expansion' coverage_bash_4_or_later
+        When call string_sub 2 -20 abc
+        The status should eq 1
+        The output should eq ''
+    End
+
+    It 'reports a valid value without an eval or pipe test wrapper'
+        coverage_read_value='12345'
+        When call args_valid_or_read coverage_read_value '^12345$' 'IRN'
+        The status should eq 0
+        The variable coverage_read_value should eq '12345'
+        The output should include 'Inputted value:'
+    End
+
+    It 'reports a defaulted value without an eval or pipe test wrapper'
+        coverage_default_value=''
+        When call args_valid_or_default coverage_default_value '^valid$' 'Value' valid
+        The status should eq 0
+        The variable coverage_default_value should eq 'valid'
+        The output should include 'Inputted value:'
+    End
+
+    It 'prints an explicit placeholder for an empty variable'
+        LOG_LEVEL=$LOG_LEVEL_WARN
+        empty_for_coverage=''
+        When call print_args empty_for_coverage
+        The status should eq 0
+        The output should include '<EMPTY>'
+    End
+
+    It 'rejects a heredoc target that is not a shell identifier'
+        When call declare_heredoc 'invalid-name'
+        The status should eq 2
+        The output should eq ''
+    End
+
+    It 'uses the zsh-specific entry path when argument.sh is sourced'
+        Skip if 'zsh-only source branch' coverage_not_zsh
+        When call coverage_source_argument
+        The status should eq 0
+    End
+End

package/spec/coverage_zsh_array_map.spec.sh

@@ -0,0 +1,24 @@
+#shellcheck shell=bash
+# Target the zsh-specific array_map branch (src/array.sh:449).
+# Does not change Bash semantics or existing tests.
+Include src/array.sh
+
+coverage_not_zsh_array() {
+    [[ -z "${ZSH_VERSION:-}" ]]
+}
+
+coverage_map_zsh_values() {
+    local -a original_values=(alpha beta)
+    local -a mapped_values=()
+    array_map original_values cat mapped_values || return $?
+    printf '<%s>\n' "${mapped_values[@]}"
+}
+
+Describe 'zsh array_map portable input branch'
+    It 'maps two elements through the zsh-specific pipeline'
+        Skip if 'requires zsh' coverage_not_zsh_array
+        When call coverage_map_zsh_values
+        The status should eq 0
+        The output should eq $'<alpha>\n<beta>'
+    End
+End