Add search functionality to the built-in help command

[dickoff]

As a cli tool grows in capabilities and complexity it becomes harder and hard to find out which command, subcommand, or option might be helpful to accomplish a task. I'm proposing adding a --search | -s <term> option to the built in help command which does a textual search of the tree of commands for relevant subcommands, descriptions, options, arguments, etc. It then outputs the relevant search results, highlighting the relevant results in bold.

I'd love for some feedback on the approach taken and what kind of changes would be welcome. The changes are largely confined to a new CommandSearcher structure which searches the Tree of commands for relevant attributes. I've attempted to have unit tests for the vast majority of the functionality.

Simple Examples

Instructions for using the --search <term> functionality are at the bottom of the help output

math -h         
OVERVIEW: A utility for performing maths.

USAGE: math <subcommand>

OPTIONS:
  --version               Show the version.
  -h, --help              Show help information.

SUBCOMMANDS:
  add (default)           Print the sum of the values.
  multiply, mul           Print the product of the values.
  stats                   Calculate descriptive statistics.

  See 'math help <subcommand>' for detailed help.
  Use 'math help --search <term>' to search commands and options.

Commands that match in name or description are listed at the top:

/math help --search mult
Found 1 match for 'mult':

COMMANDS:
  math multiply
    Print the product of the values.


Use 'math <command> --help' for detailed information.

Options that match are listed below, underneath the command they are associated with:

math help --search float
Found 3 matches for 'float':

OPTIONS:
  math stats average
    <values>: A group of floating-point values to operate on.
  math stats quantiles
    <values>: A group of floating-point values to operate on.
  math stats stdev
    <values>: A group of floating-point values to operate on.

Use 'math <command> --help' for detailed information.

Example of no results:

math help --search foo 
No matches found for 'foo'.
Try 'math --help' for all options.

Large CLI Examples

Here's a couple examples using swift-package-manager and swift-format built against this branch:

$ swift-package help -s depend
Found 39 matches for 'depend':

COMMANDS:
  package add-dependency
    Add a package dependency to the manifest.

  package add-target-dependency
    Add a new target dependency to the manifest.

  package config get-mirror
    ...r the given package dependency.

  package config set-mirror
    Set a mirror for a dependency.

  package resolve
    Resolve package dependencies.

  package show-dependencies
    Print the resolved dependency graph.

  package update
    Update package dependencies.


OPTIONS:
  package
    --enable-dependency-cache: Use a shared cache when fetching dependencies.
    --disable-dependency-cache: Use a shared cache when fetching dependencies.
    --skip-update: Skip updating dependencies from their remote during a resolution.
    --use-registry-identity-for-scm: ...k up source control dependencies in the registry and use their registry identity...
    --replace-scm-with-registry: ...k up source control dependencies in the registry and use the registry to retriev...
    --explicit-target-dependency-import-check: A flag that indicates this build should check whether targets only import their explicitly-declared dependencies.
  package add-dependency
    <dependency>: The URL or directory of the package to add.
    --exact: ... package version to depend on.
    --revision: ...package revision to depend on.
    --branch: ...h of the package to depend on.
    --from: ... package version to depend on (up to the next major version).
    --up-to-next-minor-from: ... package version to depend on (up to the next minor version).
    --type: Specify dependency type.
  package add-target
    --dependencies: A list of target dependency names.
  package add-target-dependency
    <dependency-name>: The name of the new dependency.
    --package: ...ackage in which the dependency resides.
  package completion-tool
    <mode> (possible value: list-dependencies)
  package experimental-install
    --enable-dependency-cache: Use a shared cache when fetching dependencies.
    --disable-dependency-cache: Use a shared cache when fetching dependencies.
    --skip-update: Skip updating dependencies from their remote during a resolution.
    --use-registry-identity-for-scm: ...k up source control dependencies in the registry and use their registry identity...
    --replace-scm-with-registry: ...k up source control dependencies in the registry and use the registry to retriev...
    --explicit-target-dependency-import-check: A flag that indicates this build should check whether targets only import their explicitly-declared dependencies.
  package experimental-uninstall
    --enable-dependency-cache: Use a shared cache when fetching dependencies.
    --disable-dependency-cache: Use a shared cache when fetching dependencies.
    --skip-update: Skip updating dependencies from their remote during a resolution.
    --use-registry-identity-for-scm: ...k up source control dependencies in the registry and use their registry identity...
    --replace-scm-with-registry: ...k up source control dependencies in the registry and use the registry to retriev...
    --explicit-target-dependency-import-check: A flag that indicates this build should check whether targets only import their explicitly-declared dependencies.
  package show-dependencies
    --output-path, -o: ...output the resolved dependency graph.
  package show-traits
    --package-id: ...d in the transitive dependencies.
  package update
    --dry-run, -n: Display the list of dependencies that can be updated.

Use 'swift package <command> --help' for detailed information.

swift-format help --search config
Found 5 matches for 'config':

COMMANDS:
  swift-format dump-configuration
    Dump the configuration in JSON format to standard output


OPTIONS:
  swift-format dump-configuration
    --effective, -e: ...tead of the default configuration.
    --configuration: The path to a JSON file containing the configuration of the linter/formatter or a JSON string containing the configuration directly.
  swift-format format
    --configuration: The path to a JSON file containing the configuration of the linter/formatter or a JSON string containing the configuration directly.
  swift-format lint
    --configuration: The path to a JSON file containing the configuration of the linter/formatter or a JSON string containing the configuration directly.

Use 'swift-format <command> --help' for detailed information.

This is one way of solving #673

Checklist

• [x ] I've added at least one test that validates that my change is working, if appropriate
• [x ] I've followed the code style of the rest of the project
• [x ] I've read the Contribution Guidelines
• [x ] I've updated the documentation if necessary