Create Gazelle language for Starlark

BUILD

@@ -4,6 +4,11 @@ licenses(["notice"])
 
 package(default_visibility = ["//visibility:public"])
 
+# gazelle:exclude internal_deps.bzl
+# gazelle:exclude internal_setup.bzl
+# buildifier: disable=skylark-comment
+# gazelle:exclude skylark_library.bzl
+
 exports_files(["LICENSE"])
 
 filegroup(
@@ -45,6 +50,16 @@ bzl_library(
     srcs = ["bzl_library.bzl"],
 )
 
+bzl_library(
+    name = "version",
+    srcs = ["version.bzl"],
+)
+
+bzl_library(
+    name = "workspace",
+    srcs = ["workspace.bzl"],
+)
+
 # The files needed for distribution.
 # TODO(aiuto): We should strip this from the release, but there is no
 # capability now to generate BUILD.foo from BUILD and have it appear in the

CODEOWNERS

@@ -1,3 +1,4 @@
 * @c-parsons @laurentlb @jin @aiuto
 distribution/ @aiuto @fwe
 rules/ @juliexxia
+gazelle/ @achew22 @jayconrod

WORKSPACE

@@ -10,14 +10,20 @@ maybe(
     url = "https://github.com/bazelbuild/bazel-federation/releases/download/0.0.1/bazel_federation-0.0.1.tar.gz",
 )
 
-load("@bazel_federation//:repositories.bzl", "bazel_skylib_deps")
+load("@bazel_federation//:repositories.bzl", "bazel_skylib_deps", "rules_go")
 
 bazel_skylib_deps()
 
+rules_go()
+
 load("@bazel_federation//setup:bazel_skylib.bzl", "bazel_skylib_setup")
 
 bazel_skylib_setup()
 
+load("@bazel_federation//setup:rules_go.bzl", "rules_go_setup")
+
+rules_go_setup()
+
 # Below this line is for documentation generation only,
 # and should thus not be included by dependencies on
 # bazel-skylib.
@@ -40,3 +46,22 @@ maybe(
         "https://github.com/bazelbuild/rules_cc/archive/cb2dfba6746bfa3c3705185981f3109f0ae1b893.zip",
     ],
 )
+
+# Provide a repository hint for Gazelle to inform it that the go package
+# github.com/bazelbuild/rules_go is available from io_bazel_rules_go and it
+# doesn't need to duplicatively fetch it.
+# gazelle:repository go_repository name=io_bazel_rules_go importpath=github.com/bazelbuild/rules_go
+http_archive(
+    name = "bazel_gazelle",
+    sha256 = "bfd86b3cbe855d6c16c6fce60d76bd51f5c8dbc9cfcaef7a2bb5c1aafd0710e8",
+    urls = [
+        "https://mirror.bazel.build/github.com/bazelbuild/bazel-gazelle/releases/download/v0.21.0/bazel-gazelle-v0.21.0.tar.gz",
+        "https://github.com/bazelbuild/bazel-gazelle/releases/download/v0.21.0/bazel-gazelle-v0.21.0.tar.gz",
+    ],
+)
+# Another Gazelle repository hint.
+# gazelle:repository go_repository name=bazel_gazelle importpath=github.com/bazelbuild/bazel-gazelle/testtools
+
+load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies")
+
+gazelle_dependencies()

gazelle/BUILD

@@ -0,0 +1,53 @@
+load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test")
+load("@bazel_gazelle//:def.bzl", "gazelle", "gazelle_binary")
+
+# gazelle:exclude testdata
+
+go_library(
+    name = "go_default_library",
+    srcs = ["gazelle.go"],
+    importpath = "github.com/bazelbuild/bazel-skylib/gazelle",
+    visibility = ["//visibility:public"],
+    deps = [
+        "@bazel_gazelle//config:go_default_library",
+        "@bazel_gazelle//label:go_default_library",
+        "@bazel_gazelle//language:go_default_library",
+        "@bazel_gazelle//pathtools:go_default_library",
+        "@bazel_gazelle//repo:go_default_library",
+        "@bazel_gazelle//resolve:go_default_library",
+        "@bazel_gazelle//rule:go_default_library",
+        "@com_github_bazelbuild_buildtools//build:go_default_library",
+    ],
+)
+
+go_test(
+    name = "go_default_test",
+    srcs = ["gazelle_test.go"],
+    data = [
+        ":gazelle-skylib",
+    ] + glob([
+        "testdata/**",
+    ]),
+    embed = [":go_default_library"],
+    deps = [
+        "@bazel_gazelle//testtools:go_default_library",
+        "@io_bazel_rules_go//go/tools/bazel:go_default_library",
+    ],
+)
+
+# This gazelle binary is used exclusively for testing the gazelle language
+# extension and thus only has the skylib language installed.
+gazelle_binary(
+    name = "gazelle-skylib",
+    languages = [":go_default_library"],
+    visibility = [
+        # Also make the binary available in the root of the repo for use, but
+        # not externally.
+        "//:__pkg__",
+    ],
+)
+
+gazelle(
+    name = "gazelle",
+    gazelle = "//gazelle:gazelle-skylib",
+)

gazelle/README.md

@@ -0,0 +1,13 @@
+# Gazelle
+
+Gazelle is a `BUILD` file generator for Bazel. This directory contains a
+language extension for the Gazelle generator that allows it to automatically
+parse valid `bzl_library` targets for all `.bzl` files in a repo in which it
+runs. It will additionally include a `deps` entry tracking every `.bzl` that is
+`load`ed into the primary file.
+
+This can be used, for example, to generate
+[`stardoc`](https://github.com/bazelbuild/stardoc) documentation for your
+`.bzl` files, both simplify the task of and improve the quality of
+documentation.
+