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.
Installing bash-completion makes it worse than bare readline (which
still does filename completion).

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 $(git describe $(ls <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,67 @@ _comp_initialize()
     local redir='@(?(+([0-9])|{[a-zA-Z_]*([a-zA-Z_0-9])})@(>?([>|&])|<?([>&])|<<?([-<]))|&>?(>))'
     _comp_get_words -n "$exclude<>&" cur prev words cword
 
+    # If the current word is a command substitution $(, rewrite the
+    # completion context to the command line *inside* the substitution
+    # and dispatch to that command's completion function.
+    if [[ $cur == '$('* ]]; then
+        local inner_line=${cur#\$\(}
+
+        # Handle nested substitutions: strip one $( at a time, parse
+        # into words, and check if any word contains an unclosed $(.
+        # If so, take the text from that word onward as a new inner
+        # line and repeat.  This recurses through nesting levels like
+        # echo $(cmd1 arg $(cmd2 <TAB>.
+        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"
+            # A trailing space means the user is starting a new word.
+            if [[ $inner_line == *[[:space:]] ]]; then
+                COMP_WORDS+=("")
+            fi
+            COMP_CWORD=$((${#COMP_WORDS[@]} - 1))
+
+            # Scan backward for the last word containing an unclosed
+            # $( (more $( than ) characters).
+            local i nested_idx=""
+            for ((i = COMP_CWORD; i >= 0; i--)); do
+                local word=${COMP_WORDS[i]}
+                if [[ $word == *'$('* ]]; then
+                    # Count $( pairs vs ) to detect unclosed subst
+                    local stripped=${word//\$\(/}
+                    local open_count=$(((${#word} - ${#stripped}) / 2))
+                    stripped=${word//)/}
+                    local close_count=$((${#word} - ${#stripped}))
+                    if ((open_count > close_count)); then
+                        nested_idx=$i
+                        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
+        )