fix(_comp_initialize): complete inside $() command substitutions

Since bash 4.3, $(cmd args is treated as a single opaque word in
COMP_WORDS, so the outer command's completion function produces nothing.

Detect when cur starts with $( in _comp_initialize, rewrite COMP_LINE /
COMP_POINT / COMP_WORDS / COMP_CWORD to describe the command line
inside the substitution, and dispatch to the inner command's completion
function via _comp_command_offset 0.

Handle nested substitutions (e.g. echo $(cmd1 arg $(cmd2 <TAB>) by
looping: after parsing inner_line into words, scan for any word with an
unclosed $( (more $( than ) counts) and re-enter the loop from that
word onward, stripping one $( per iteration until the innermost level
is reached.

Integration tests register a simple completion function (csub_cmd) and
use assert_complete to send real keystrokes through the full pipeline:
- Single-level: echo $(csub_cmd <TAB> matches bare csub_cmd <TAB>
- Single-level partial: echo $(csub_cmd a<TAB> filters by prefix
- Nested: echo $(echo foo $(csub_cmd <TAB> dispatches through nesting
- Nested partial: echo $(echo foo $(csub_cmd b<TAB> filters in nesting
- Closed-then-open: echo $(echo hi) $(csub_cmd <TAB> skips closed $()
- Regression: csub_cmd <TAB> without $( still works

Closes #630

Author: richardkmichael

bash_completion

@@ -1626,6 +1626,83 @@ _comp_initialize()
     local redir='@(?(+([0-9])|{[a-zA-Z_]*([a-zA-Z_0-9])})@(>?([>|&])|<?([>&])|<<?([-<]))|&>?(>))'
     _comp_get_words -n "$exclude<>&" cur prev words cword
 
+    # Since bash 4.3, find_cmd_start() skips over unclosed $(,
+    # causing the entire $( content to appear as one token in
+    # COMP_WORDS.  For example, in "echo $(cmd1 arg $(cmd2 ",
+    # cur is the single blob "$(cmd1 arg $(cmd2 ".
+    #
+    # The loop below strips $( layers one at a time: split
+    # into words, find a word with unclosed $(, rebuild
+    # inner_line from that word onward, and repeat.  When no
+    # unclosed $( remains, COMP_* describes the innermost
+    # command and _comp_command_offset dispatches to it.
+    if [[ $cur == '$('* ]]; then
+        local inner_line=$cur
+        local i nested_idx
+
+        while true; do
+            # Empty or whitespace-only -- nothing to complete,
+            # matching bare-prompt behavior.
+            [[ ${inner_line//[[:space:]]/} ]] || return 1
+
+            COMP_LINE=$inner_line
+            COMP_POINT=${#inner_line}
+            _comp_split COMP_WORDS "$inner_line"
+
+            # _comp_split discarded trailing whitespace, but if a trailing
+            # space was present, then the cursor is past the last word.
+            # Append an empty word so COMP_CWORD points to the empty position
+            # to correctly perform the completion there.
+            if [[ $inner_line == *[[:space:]] ]]; then
+                COMP_WORDS+=("")
+            fi
+
+            # COMP_CWORD is the index of the word at the cursor.  Bash provides
+            # the entire unclosed $( as one opaque token, so the cursor
+            # position within it is lost; we set COMP_POINT to end-of-line
+            # above and COMP_CWORD to the last word to match.
+            COMP_CWORD=$((${#COMP_WORDS[@]} - 1))
+
+            # Scan backward for a word with more $( than ),
+            # indicating an unclosed substitution.
+            nested_idx=""
+            for ((i = COMP_CWORD; i >= 0; i--)); do
+                local word=${COMP_WORDS[i]}
+                if [[ $word == *'$('* ]]; then
+                    # To detect unclosed substitutions, count
+                    # occurrences of $( and ) by removing them
+                    # and comparing lengths.
+                    local without_opens=${word//\$\(/}
+                    local open_count=$(((${#word} - ${#without_opens}) / 2))
+                    local without_closes=${word//)/}
+                    local close_count=$((${#word} - ${#without_closes}))
+                    if ((open_count > close_count)); then
+                        nested_idx=$i
+                        # re-parse from this word onward; inner_line is
+                        # assembled below for the next iteration
+                        break
+                    fi
+                fi
+            done
+
+            # No unclosed $( found -- we're at the innermost level.
+            [[ $nested_idx ]] || break
+
+            # Rebuild inner_line from the nested word onward, then
+            # strip its leading $( for the next iteration.
+            inner_line="${COMP_WORDS[*]:nested_idx}"
+            inner_line=${inner_line#\$\(}
+        done
+
+        # Unset words so _comp_command_offset uses COMP_WORDS directly
+        # (same pattern as _comp_command).
+        local words
+        unset -v words
+
+        _comp_command_offset 0
+        return 1
+    fi
+
     # Complete variable names.
     _comp_compgen_variables && return 1
 

test/t/unit/test_unit_command_substitution.py

@@ -0,0 +1,62 @@
+import pytest
+
+from conftest import assert_bash_exec, assert_complete
+
+
+@pytest.mark.bashcomp(
+    cmd=None,
+    ignore_env=r"^[+-](COMPREPLY|REPLY)=",
+)
+class TestUnitCommandSubstitution:
+    """Test completion inside $() command substitutions.
+
+    Each test sends real keystrokes via assert_complete, comparing
+    completions at the bare prompt with completions inside $().
+    """
+
+    wordlist = sorted(["alpha", "bravo"])
+
+    @pytest.fixture(scope="class")
+    def functions(self, bash):
+        assert_bash_exec(
+            bash,
+            # csub_cmd: a test command whose completion function returns
+            # a fixed word list, filtered by the current word prefix.
+            "_csub_compfunc() {"
+            '  COMPREPLY=($(compgen -W "%s"'
+            ' -- "${COMP_WORDS[COMP_CWORD]}"));'
+            "}; "
+            "complete -F _csub_compfunc csub_cmd" % " ".join(self.wordlist),
+        )
+
+    def test_normal_not_affected(self, bash, functions):
+        """Completion without $( still works."""
+        assert assert_complete(bash, "csub_cmd ") == self.wordlist
+
+    def test_single_level(self, bash, functions):
+        """echo $(csub_cmd <TAB> produces same completions."""
+        assert assert_complete(bash, "echo $(csub_cmd ") == self.wordlist
+
+    def test_single_level_partial(self, bash, functions):
+        """echo $(csub_cmd a<TAB> completes the matching word."""
+        assert assert_complete(bash, "echo $(csub_cmd a") == ["lpha"]
+
+    def test_nested(self, bash, functions):
+        """echo $(echo foo $(csub_cmd <TAB> works through nesting."""
+        assert (
+            assert_complete(bash, "echo $(echo foo $(csub_cmd ")
+            == self.wordlist
+        )
+
+    def test_nested_partial(self, bash, functions):
+        """echo $(echo foo $(csub_cmd b<TAB> completes inside nesting."""
+        assert assert_complete(bash, "echo $(echo foo $(csub_cmd b") == [
+            "ravo"
+        ]
+
+    def test_closed_then_open(self, bash, functions):
+        """echo $(echo hi) $(csub_cmd <TAB> -- closed $() before open one."""
+        assert (
+            assert_complete(bash, "echo $(echo hi) $(csub_cmd ")
+            == self.wordlist
+        )