Allow ListRepositories to load macros not in Workspace

[tyler-french]

What type of PR is this?

Feature

What package or component does this PR mostly affect?

repo

What does this PR do? Why is it needed?

The PR allows a user to load other repository macros from within a top-level repository macro, so that it does not have to be added to the Workspace file. These macros with a second layer are identified by prepending a "+" to the beginning of the path in the repository_macro directive:

e.g. # gazelle:repository_macro +repos.bzl%go_repositories would load repos.bzl%go_repositories and any other files loaded from within the macro.

This is needed because the functionality already exists and is legal in bazel: A go_repository( ... ) rule can be added to a macro, loaded by another macro, and loaded by the workspace. However, gazelle will not resolve this repository, and create a duplicate rule, thereby creating incorrect/duplicate Starlark content.

In very large repositories, this is important when dependency management needs to happen in many different file spaces.
This change uses a highly conservative opt-in approach, although since it is legal in Bazel, perhaps this "opt-in" requirement can be removed in the future. With this implementation, ListRepositories will correctly list all of the go_repository( imports in that file, whether directly or loaded from another macro, as Bazel would similarly load.

For all existing uses (macro files existing as references only from Workspace file), no changes would be made. Only in cases where a user specifically decides to load another macro, and identify this desire in the gazelle directive.

Which issues(s) does this PR fix?

Fixes #1049

[linzhp]

Is it safe to assume all repository_macros only contains repository definitions or other repository_macros? In that case, we don't need to specify # gazelle:repository_macro in a repository macro: if a statement is not a Rule, then we recursively load it as a repository macro

[tyler-french]

Is it safe to assume all repository_macros only contains repository definitions or other repository_macros? In that case, we don't need to specify # gazelle:repository_macro in a repository macro: if a statement is not a Rule, then we recursively load it as a repository macro

In my personal opinion, I feel that it would be not safe to do this because it opens the potential for more unnecessary recursive calls. Firstly, this function finds all the Rule direct loads of repositories (which are Bazel lingo not gazelle). Next it checks for the gazelle directives only of the type go_repository. I think the best approach is: the more conservative possible, the better. Since rules could be of other types, and directives could be unrelated. With this approach, the user has to specify, the same way that they are already required to do from the Workspace file, that this other file is a repository_macro, only for loading go repositories (since directives are supposed to be primarily handwritten).

[linzhp]

@jayconrod We are adding a new syntax

# gazelle:repository_macro +some/file.bzl%go_repositories

The + sign tells Gazelle to look for other repository macros called by this repository macro. It's to avoid unnecessary recursion into non-repository macros. Do you think it a good idea? Would you prefer a simpler assumption that all repository macros should only contain either repository rules or other repository macros?

[linzhp]

This PR keeps failing on Windows. Please fix the test on Windows.

[linzhp]

@jayconrod @blico I don't see further issues. Do you want to take another look?

[blico]

Please also modify the repository_macro doc in readme.rst to describe the added functionality

[blico]

Looks good! Just a few more minor comments.