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 $(git describe $(ls <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}
+            read -ra 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=""
+            for ((_i = COMP_CWORD; _i >= 0; _i--)); do
+                local _w=${COMP_WORDS[_i]}
+                if [[ $_w == *'$('* ]]; then
+                    # Count $( pairs vs ) to detect unclosed subst
+                    local _tmp=${_w//\$\(/}
+                    local _opens=$(((${#_w} - ${#_tmp}) / 2))
+                    _tmp=${_w//)/}
+                    local _closes=$((${#_w} - ${#_tmp}))
+                    if ((_opens > _closes)); then
+                        _nested=$_i
+                        break
+                    fi
+                fi
+            done
+
+            # No unclosed $( found -- we're at the innermost level.
+            [[ $_nested ]] || break
+
+            # Rebuild inner_line from the nested word onward, then
+            # strip its leading $( for the next iteration.
+            inner_line="${COMP_WORDS[*]:_nested}"
+            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,45 @@
+import pytest
+
+from conftest import TestUnitBase
+
+
+@pytest.mark.bashcomp(
+    cmd=None,
+    ignore_env=r"^[+-](COMP(_(WORDS|CWORD|LINE|POINT)|REPLY)|"
+    r"cur|prev|cword|words)=",
+)
+class TestUnitCommandSubstitution(TestUnitBase):
+    def test_command_substitution_completion(self, bash):
+        """Test that command substitution completion works correctly"""
+        # Test basic command substitution: $(echo
+        output = self._test_unit(
+            "_comp_initialize %s; echo $COMP_LINE,$COMP_CWORD,$cur,$prev",
+            bash,
+            "(echo '$(echo')",
+            1,
+            "echo '$(echo'",
+            12,
+        )
+        assert output == "echo,0,echo,"
+
+        # Test command substitution with arguments: $(ls -l
+        output = self._test_unit(
+            "_comp_initialize %s; echo $COMP_LINE,$COMP_CWORD,$cur,$prev",
+            bash,
+            "(echo '$(ls -l')",
+            1,
+            "echo '$(ls -l'",
+            13,
+        )
+        assert output == "ls -l,1,-l,ls"
+
+        # Test that normal completion is not affected
+        output = self._test_unit(
+            "_comp_initialize %s; echo $COMP_LINE,$COMP_CWORD,$cur,$prev",
+            bash,
+            "(echo hello)",
+            1,
+            "echo hello",
+            10,
+        )
+        assert output == "echo hello,1,hello,echo"