Support for cli subgoals

[kaos]

Is your feature request related to a problem? Please describe.

In order to support a growing number of features, there is a risk of overcrowding the top level list goals.

Describe the solution you'd like

Support grouping related functionality (sub goals) under a common parent goal.

So you can have commands like (from slack thread):

$  ./pants caches "<subgoal>" 

# e.g.
$ ./pants caches report 
$ ./pants caches clean

# and help
$ ./pants help caches
$ ./pants help caches clean

Describe alternatives you've considered

Namespacing goals using a naming standard, such as group-subgoal. I think that is sub optimal and not very user friendly solution. It would make it harder to present in help listings, and to request help for a group etc (if any grouping logic is to be applied, or it won't help reduce the overcrowding situation).

Additional context

The need for this feature has been suggested in slack here for #13494 and I also envision it could ease the introduction of new features without adding too much noise to the overall list of top level goals (such as managing your list 3rd party requirements for one, #12880).

[stuhood]

Prior art is that we used to have "nested" scopes, which were dot-separated. So group.subgoal. They had very different CLI semantics than this, but these semantics are pretty clearly better that those.

I do wonder whether this is actually justified though: the caches example from the body is presumably spawned out of discussion of #11167, and "builtin" goals (like help) can already have their own semantics... as demonstrated by help already supporting subcommands.

So cleaning up the support that builtin goals have for subcommands would definitely be welcome. But justifying adding support for subcommands for all user goals would probably require a different motivating usecase.

[kaos]

Due to the complexity or effort to develop? (I'm halfway through with a POC for this ;) ) Wasn't too difficult (unless there's some unforeseen hurdles ahead)

[kaos]

Wouldn't mind cleaning up the support for builtin goals first though :)

[stuhood]

Wasn't too difficult (unless there's some unforeseen hurdles ahead)

The primary concern for me is that combining subcommands with multiple goals (e.g. ./pants check fmt caches report lint) is confusing, and we're going to want to lean in even further for multiple goals via #10542 (which is mostly unblocked). It would also never make sense for a cache cleanup goal to run concurrently with builtin goals using the @goal_rule API (although maybe caches isn't the best example of how this would be used).

Meanwhile, builtin commands don't support running multiple goals (so ./pants check fmt help lint isn't possible... which is good, because it would be ambiguous).

[kaos]

Thanks, that makes sense.

[kaos]

Closing this, as with the BuiltinGoal the way arguments may be parsed are much more flexible.