Gazelle should resolve labels using declared import paths

[jayconrod]

Currently, Gazelle converts import paths into Bazel labels by following a few simple conventions. This requires go_library to be in specific packages with specific names (go_default_library) in order to work. This is causing an increasing amount of difficulty for several reasons.

• There is no warning when referencing a library that doesn't exist. (Gazelle: warn when an import path can't be resolved #388)
• There are multiple ways to structure a repository. Gazelle itself supports hierarchical mode and flat mode. We'd like to be able to mix these. (Gazelle flat mode #608)
• We don't want to force a repository to have a single prefix (or any prefix at all). (Allow gazelle to be aware of go_prefix mappings defined in the workspace. #313, Gazelle monorepo support (importpath) #597, Deprecate and remove go_prefix #721)
• We don't want to force external repositories that have particular names. (gazelle infers wrong external from import path  #606)
• We should allow multiple vendor directories. (Support vendor dirs not in root of the repo #486, Make gazelle play well with vendor directories from dep #725)
• We should allow vendor directories and external repositories at the same time. (Gazelle should default to vendoring if the vendor directory exists #404)
• We should respect importpath attributes in rules.
• With go_proto_library, there are multiple kinds of libraries with different naming conventions. (Generate new proto rules with gazelle #808)
• We'd like to drop the go_default_library name at some point. (Use package name instead of go_default_library to define a default library #265)

Smarter label resolution is a prerequisite for all of this.

---

Proposal

When Gazelle starts, it will build a table that maps import paths to labels and directories. This table will be populated by several mechanisms:

• For external repositories that use flat build files generated by Gazelle stored in a third_party directory, Gazelle will scan these files.
• For packages in the current repository that Gazelle won't update, Gazelle will scan existing build files.
• For packages in the current repository that Gazelle will update, Gazelle will scan source files.

After build files and directories are scanned, Gazelle will generate rules for the packages it needs to update. Dependencies will be resolved using the table described above.

• If an import path corresponds to one or more labels, Gazelle will choose one using vendoring logic and visibility. If there are multiple valid labels, Gazelle will emit an error.
• If an import path points to a repository that could not be scanned for some reason, Gazelle will fall back to current conventions.
• If an import path can't be resolved (it points to a known prefix, and there's no visible label), Gazelle will emit an error.

[ianthehat]

"If there are multiple valid labels, Gazelle will emit an error"
Will it write out the files anyway (using the first match with a comment) so you can resolve by hand?

[jayconrod]

Yes. Gazelle errors are almost never fatal. When it fails to find a label for an import path, it won't emit a label for that import. So you'll need to manually add one with a # keep comment.

[guoshimin]

Has this proposal been accepted? Has work started? If not, what's it blocked on?

[jayconrod]

I'm actively working on this on a dev branch. I'm hoping to cut the first changes this week.

[jayconrod]

Closing old Gazelle issues. This is mostly done. A few remaining open issues have been migrated to bazelbuild/bazel-gazelle.