Bash completion for the build examples helper script (project-chip#39915)

* Bash completion for the build examples helper script

* Target completion support in build_examples script

* Do not match path when setting up completion

* Restyled by shfmt

* Suggest modifiers only on demand

* Unit test for target completion strings generator

---------

Co-authored-by: Restyled.io <[email protected]>

Author: arkq

scripts/build/build/target.py

@@ -251,15 +251,15 @@ def AppendFixedTargets(self, parts: List[TargetPart]):
         """
         self.fixed_targets.append(parts)
 
-    def AppendModifier(self, name: str, **kargs):
+    def AppendModifier(self, name: str, **kwargs):
         """Appends a specific modifier to a build target. For example:
 
         target.AppendModifier(name='release', release=True)
         target.AppendModifier(name='clang', use_clang=True)
         target.AppendModifier(name='coverage', coverage=True).OnlyIfRe('-clang')
 
         """
-        part = TargetPart(name, **kargs)
+        part = TargetPart(name, **kwargs)
 
         self.modifiers.append(part)
 
@@ -285,8 +285,63 @@ def HumanString(self):
 
         return result
 
+    def CompletionStrings(self, value: str) -> List[str]:
+        """Get a list of completion strings for this target."""
+
+        if self.name.startswith(value):
+            return [self.name + "-"]
+        if not value.startswith(self.name + "-"):
+            return []
+
+        completions = []
+        prefix = self.name
+        suffix = value[len(self.name) + 1:]
+
+        for i, targets in enumerate(self.fixed_targets, 1):
+            # If we are not processing the last fixed target,
+            # append hyphen to the generated completions.
+            hyphen = '-' if i != len(self.fixed_targets) else ''
+            for target in targets:
+                if suffix.startswith(target.name + hyphen):
+                    # Strip the prefix and continue processing.
+                    prefix += f"-{target.name}"
+                    suffix = suffix[len(target.name) + 1:]
+                    break
+            else:
+                for target in targets:
+                    # NOTE: We are not validating whether the target is acceptable
+                    #       for the given value. Some validation rules require the
+                    #       full target name to be known, so in case of completions
+                    #       we just assume that the target is acceptable.
+                    completions.append(f"{prefix}-{target.name}{hyphen}")
+                # Return validated completions.
+                return [c for c in completions if c.startswith(value)]
+
+        modifiers = []
+        while True:
+            # Get modifiers which are already part of the value.
+            for modifier in self.modifiers:
+                if suffix.startswith(modifier.name):
+                    modifiers.append(modifier)
+                    # Strip the prefix and continue processing.
+                    prefix += f"-{modifier.name}"
+                    suffix = suffix[len(modifier.name) + 1:]
+                    break
+            else:
+                # No more modifiers in the suffix, break the loop.
+                break
+
+        completions.append(prefix)
+        # Return all valid modifiers that are not already part of the value.
+        for modifier in self.modifiers:
+            if modifier not in modifiers and modifier.Accept(prefix):
+                completions.append(f"{prefix}-{modifier.name}")
+
+        # Return validated completions.
+        return [c for c in completions if c.startswith(value)]
+
     def ToDict(self):
-        """Outputs a parseable description of the available variants
+        """Outputs a parsable description of the available variants
         and modifiers:
 
             like:

scripts/build/build/test_target.py

@@ -26,7 +26,7 @@ def __init__(self, **kargs):
         self.kargs = kargs
 
 
-class TestGlobMatcher(unittest.TestCase):
+class TestBuildTarget(unittest.TestCase):
 
     def test_one_fixed_target(self):
         t = BuildTarget('fake', FakeBuilder)
@@ -150,6 +150,51 @@ def test_modifiers(self):
         self.assertIsNone(t.StringIntoTargetParts('fake-bar-m1'))
         self.assertIsNone(t.StringIntoTargetParts('fake-foo-x1-y1'))
 
+    def test_completion_strings(self):
+        t = BuildTarget('fake', FakeBuilder)
+
+        t.AppendFixedTargets([
+            TargetPart('foo', foo=1),
+            TargetPart('bar', bar=2),
+        ])
+
+        t.AppendFixedTargets([
+            TargetPart('one', value=1),
+            TargetPart('two', value=2),
+        ])
+
+        t.AppendModifier('m1', m=1).ExceptIfRe('-m2')
+        t.AppendModifier('m2', m=2).ExceptIfRe('-m1')
+        t.AppendModifier('extra', extra=1).OnlyIfRe('-foo-')
+
+        # Non-existing target should return an empty list.
+        self.assertEqual(t.CompletionStrings('non-existing-'),
+                         [])
+
+        # Not the last fixed target - completions should be suffixed with "-".
+        self.assertEqual(t.CompletionStrings(''),
+                         ['fake-'])
+        self.assertEqual(t.CompletionStrings('fake-'),
+                         ['fake-foo-', 'fake-bar-'])
+        self.assertEqual(t.CompletionStrings('fake-f'),
+                         ['fake-foo-'])
+
+        # The last fixed target - completions should not be suffixed with "-".
+        self.assertEqual(t.CompletionStrings('fake-foo-'),
+                         ['fake-foo-one', 'fake-foo-two'])
+
+        # Modifiers should be added to the last fixed target.
+        self.assertEqual(t.CompletionStrings('fake-foo-two'),
+                         ['fake-foo-two', 'fake-foo-two-m1', 'fake-foo-two-m2', 'fake-foo-two-extra'])
+        self.assertEqual(t.CompletionStrings('fake-foo-two-m'),
+                         ['fake-foo-two-m1', 'fake-foo-two-m2'])
+
+        # After adding a modifier, completions should respect exclusion rules.
+        self.assertEqual(t.CompletionStrings('fake-foo-one-m1'),
+                         ['fake-foo-one-m1', 'fake-foo-one-m1-extra'])
+        self.assertEqual(t.CompletionStrings('fake-bar-one-m1'),
+                         ['fake-bar-one-m1'])
+
 
 if __name__ == '__main__':
     unittest.main()

scripts/build/build_examples.py

@@ -169,13 +169,12 @@ def main(context, log_level, verbose, target, enable_link_map_file, repo,
     else:
         runner = ShellRunner(root=repo)
 
-    requested_targets = set([t.lower() for t in target])
-    logging.info('Building targets: %s', CommaSeparate(requested_targets))
-
     context.obj = build.Context(
         repository_path=repo, output_prefix=out_prefix, verbose=verbose,
         ninja_jobs=ninja_jobs, runner=runner
     )
+
+    requested_targets = set([t.lower() for t in target])
     context.obj.SetupBuilders(targets=requested_targets, options=BuilderOptions(
         enable_link_map_file=enable_link_map_file,
         enable_flashbundle=enable_flashbundle,
@@ -200,23 +199,31 @@ def cmd_generate(context):
 @click.option(
     '--format',
     default='summary',
-    type=click.Choice(['summary', 'expanded', 'json'], case_sensitive=False),
+    type=click.Choice(['summary', 'expanded', 'json', 'completion'], case_sensitive=False),
     help="""
-        summary - list of shorthand strings summarzing the available targets;
+        summary - list of shorthand strings summarizing the available targets;
 
         expanded - list all possible targets rather than the shorthand string;
 
-        json - a JSON representation of the available targets
+        json - a JSON representation of the available targets;
+
+        completion - a list of strings suitable for bash completion;
         """)
+@click.argument('COMPLETION-PREFIX', default='')
 @click.pass_context
-def cmd_targets(context, format):
+def cmd_targets(context, format, completion_prefix):
     if format == 'expanded':
+        build.target.report_rejected_parts = False
         for target in build.targets.BUILD_TARGETS:
-            build.target.report_rejected_parts = False
             for s in target.AllVariants():
                 print(s)
     elif format == 'json':
         print(json.dumps([target.ToDict() for target in build.targets.BUILD_TARGETS], indent=4))
+    elif format == 'completion':
+        build.target.report_rejected_parts = False
+        for target in build.targets.BUILD_TARGETS:
+            for s in target.CompletionStrings(completion_prefix):
+                print(s)
     else:
         for target in build.targets.BUILD_TARGETS:
             print(target.HumanString())

scripts/helpers/bash-completion.sh

@@ -16,6 +16,88 @@
 # limitations under the License.
 #
 
+_chip_build_example() {
+
+    local cur prev words cword split
+    _init_completion -s || return
+
+    # The command names supported by the script.
+    local commands="build gen targets"
+
+    local i
+    local command command_comp_cword
+    # Get the first non-option argument taking into account the options with their arguments.
+    for ((i = 1; i <= COMP_CWORD; i++)); do
+        case "${COMP_WORDS[i]}" in
+            --log-level | --target | --repo | --out-prefix | --ninja-jobs | --pregen-dir | --dry-run-output | --pw-command-launcher)
+                ((i == COMP_CWORD)) && break
+                ((i == COMP_CWORD - 1)) && [[ "${COMP_WORDS[i + 1]}" = "=" ]] && break
+                [[ "${COMP_WORDS[i + 1]}" = "=" ]] && ((i++))
+                [[ "${COMP_WORDS[i + 1]}" ]] && ((i++))
+                continue
+                ;;
+            -* | =)
+                continue
+                ;;
+        esac
+        command="${COMP_WORDS[i]}"
+        command_comp_cword=$i
+        break
+    done
+
+    # Compete the global options if the command is not specified yet.
+    if [[ -z "$command" ]]; then
+        case "$prev" in
+            --target)
+                readarray -t COMPREPLY < <(compgen -W "$("$1" targets --format=completion "$cur")" -- "$cur")
+                compopt -o nospace
+                return
+                ;;
+            --repo | --out-prefix | --pregen-dir)
+                _filedir -d
+                return
+                ;;
+            --dry-run-output)
+                _filedir
+                return
+                ;;
+        esac
+        case "$cur" in
+            -*)
+                readarray -t COMPREPLY < <(compgen -W "$(_parse_help "$1")" -- "$cur")
+                return
+                ;;
+        esac
+    fi
+
+    # Complete the command name.
+    if [[ "$command_comp_cword" -eq "$COMP_CWORD" ]]; then
+        readarray -t COMPREPLY < <(compgen -W "$commands" -- "$cur")
+        return
+    fi
+
+    # Check if the command is valid.
+    [[ "$commands" =~ $command ]] || return
+
+    # Command-specific completion.
+    case "$prev" in
+        --format)
+            readarray -t COMPREPLY < <(compgen -W "summary expanded json" -- "$cur")
+            return
+            ;;
+        --copy-artifacts-to | --create-archives)
+            _filedir -d
+            return
+            ;;
+    esac
+    case "$cur" in
+        -*)
+            readarray -t COMPREPLY < <(compgen -W "$("$1" "$command" --help | _parse_help -)" -- "$cur")
+            ;;
+    esac
+
+}
+
 # Get the list of commands from the output of the chip-tool,
 # where each command is prefixed with the ' | * ' string.
 _chip_tool_get_commands() {
@@ -124,6 +206,9 @@ _chip_tool() {
 
 }
 
+complete -F _chip_build_example scripts/build/build_examples.py
+complete -F _chip_build_example build_examples.py
+
 complete -F _chip_app chip-air-purifier-app
 complete -F _chip_app chip-all-clusters-app
 complete -F _chip_app chip-bridge-app