feat(gazelle): Add "include_dep" Python comment annotation

[dougthor42]

Add a new Python comment annotation for Gazelle: include_dep. This annotation accepts a comma-separated string of values. Values should be targets names, but no validation is done.

The annotation can be added multiple times, and all values are combined and de-duplicated.

For python_generation_mode = "package", the include_dep annotations found across all files included in the generated target.

The parser.annotations struct is updated to include a new includeDep field, and parser.parse is updated to return the annotations struct. All target builders then add the resolved dependencies.

Fixes #1862.

Example:

# gazelle:include_dep //foo:bar,:hello_world,//:abc
# gazelle:include_dep //:def,//foo:bar

will cause gazelle to generate:

deps = [
    ":hello_world",
    "//:abc",
    "//:def",
    "//foo:bar",
]

[dougthor42]

Still TODO:

• [x] Udpate CHANGELOG
• [x] Update documentation

[dougthor42]

I think this is ready for review.

Note that this might be a bit of a footgun. Users can add non-python targets to deps and then things will fail during bazel build with <target> does not have mandatory providers: 'PyInfo' or 'CcInfo' or 'PyInfo'. The docs I've added try to address this.

If that's deemed too big of risk, I'd be happy to discuss alternative solutions.

[aignas]

Don't have time to look into this right now, but after reading your last comment, I am wondering if the right way to avoid the footgun would be to use the import path as an argument to the gazelle comment, but that is almost as a noop import statement using just python? Which puts us back to square 1.

I'll think about this a little more.

[f0rmiga]

Don't have time to look into this right now, but after reading your last comment, I am wondering if the right way to avoid the footgun would be to use the import path as an argument to the gazelle comment, but that is almost as a noop import statement using just python? Which puts us back to square 1.

I'll think about this a little more.

We are overthinking here. If the user gets to this point, the entire implementation will look wrong (the user code).

[f0rmiga]

Thank you, @dougthor42!