I’m currently looking at adding a little feature involving lockfiles/resolves and trying to grok the overall design, this helps a lot:

╭─ zsh  ~/src/github/kaos/pants   main ?1 ~1                                                                                                     20:42:44 
╰─❯ ./pants GenerateToolLockfileSentinel --help

`pants.core.goals.generate_lockfiles.GenerateToolLockfileSentinel` api type
---------------------------------------------------------------------------

Tools use this as an entry point to say how to generate their tool lockfile.

Each language ecosystem should set up a union member of `GenerateLockfile`, like
`GeneratePythonLockfile`, as explained in that class's docstring.

Each language ecosystem should also subclass `GenerateToolLockfileSentinel`, e.g.
`GeneratePythonToolLockfileSentinel`. The subclass does not need to do anything - it is only used to know which language ecosystems tools correspond to.

Then, each tool should subclass their language ecosystem's subclass of `GenerateToolLockfileSentinel` and set up a rule that goes from the
subclass -> the language's lockfile request, e.g. BlackLockfileSentinel ->
GeneratePythonLockfile. Register `UnionRule(GenerateToolLockfileSentinel, MySubclass)`.

activated by : pants.core
union members: AutoflakeLockfileSentinel
               BlackLockfileSentinel
               CoveragePyLockfileSentinel
               DebugPyLockfileSentinel
               DocformatterLockfileSentinel
               DockerfileParserLockfileSentinel
               Flake8LockfileSentinel
               GoogleJavaFormatToolLockfileSentinel
               IPythonLockfileSentinel
               IsortLockfileSentinel
               JavaParserToolLockfileSentinel
               JunitToolLockfileSentinel
               MyPyExtraTypeStubsLockfileSentinel
               MyPyLockfileSentinel
               PyoxidizerLockfileSentinel
               PytestLockfileSentinel
               ScalaParserToolLockfileSentinel
               ScalafmtToolLockfileSentinel
               ScalatestToolLockfileSentinel
               SetuptoolsLockfileSentinel
               SetuptoolsSCMLockfileSentinel
               StripJarToolLockfileSentinel
               TwineLockfileSentinel

Include API types and rules dependency information by running `./pants help-advanced pants.core.goals.generate_lockfiles.GenerateToolLockfileSentinel`.

the list of union members in particular in this case, as hunting them down would have been… well a well-formed shell command but still.. this is more easily comprehensible 🙂