fix: markdown/tools:update_markdown_toc (#162)

- Reworked how `ekalinin/github-markdown-toc.go` is referenced and the
dependencies are managed. Let Gazelle do the heavy lifting.
- Update `//:update_all` to execute `//:gazelle_update_repos` and
`//:gazelle`.

Author: cgrindel

BUILD.bazel

@@ -1,3 +1,4 @@
+load("@bazel_gazelle//:def.bzl", "gazelle")
 load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 load(
     "//bzlformat:defs.bzl",
@@ -7,6 +8,18 @@ load(
 load("//tests:integration_test_common.bzl", "INTEGRATION_TEST_TAGS")
 load("//updatesrc:defs.bzl", "updatesrc_update_all")
 
+# gazelle:prefix github.com/cgrindel/bazel-starlib
+gazelle(name = "gazelle")
+
+gazelle(
+    name = "gazelle_update_repos",
+    args = [
+        "-from_file=go.mod",
+        "-to_macro=go_deps.bzl%bazel_starlib_go_dependencies",
+    ],
+    command = "update-repos",
+)
+
 # MARK: - Bazel Starlark Lint and Formatting
 
 bzlformat_pkg(name = "bzlformat")
@@ -22,9 +35,16 @@ updatesrc_update_all(
     targets_to_run = [
         "@contrib_rules_bazel_integration_test//tools:update_deleted_packages",
         ":bzlformat_missing_pkgs_fix",
+        ":gazelle_update_repos",
+        ":gazelle",
     ],
 )
 
+alias(
+    name = "tidy",
+    actual = ":update_all",
+)
+
 # MARK: - Markdown Files
 
 package_group(

WORKSPACE

@@ -4,6 +4,20 @@ load("//:deps.bzl", "bazel_starlib_dependencies")
 
 bazel_starlib_dependencies()
 
+# gazelle:repo bazel_gazelle
+load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies")
+load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies")
+load("//:go_deps.bzl", "bazel_starlib_go_dependencies")
+
+# gazelle:repository_macro go_deps.bzl%bazel_starlib_go_dependencies
+bazel_starlib_go_dependencies()
+
+go_rules_dependencies()
+
+go_register_toolchains(version = "1.19.1")
+
+gazelle_dependencies()
+
 load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
 
 bazel_skylib_workspace()
@@ -35,20 +49,6 @@ buildifier_prebuilt_register_toolchains()
 
 # markdown_register_node_deps()
 
-# MARK: - Golang Deps (gh-md-toc)
-
-load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies")
-load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies")
-load("//markdown:deps.bzl", "bazel_starlib_markdown_dependencies")
-
-bazel_starlib_markdown_dependencies()
-
-go_rules_dependencies()
-
-go_register_toolchains(version = "1.17.6")
-
-gazelle_dependencies()
-
 # MARK: - Integration Testing
 
 load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

bazel_versions.bzl

@@ -1,6 +1,6 @@
 """Bazel Version Declarations"""
 
-CURRENT_BAZEL_VERSION = "5.1.1"
+CURRENT_BAZEL_VERSION = "//:.bazelversion"
 
 OTHER_BAZEL_VERSIONS = [
     "4.2.2",

cmd/go_deps/BUILD.bazel

@@ -0,0 +1,18 @@
+load("@cgrindel_bazel_starlib//bzlformat:defs.bzl", "bzlformat_pkg")
+load("@io_bazel_rules_go//go:def.bzl", "go_binary", "go_library")
+
+go_library(
+    name = "go_deps_lib",
+    srcs = ["main.go"],
+    importpath = "github.com/cgrindel/bazel-starlib/cmd/go_deps",
+    visibility = ["//visibility:private"],
+    deps = ["@com_github_ekalinin_github_markdown_toc_go//:github-markdown-toc_go"],
+)
+
+go_binary(
+    name = "go_deps",
+    embed = [":go_deps_lib"],
+    visibility = ["//visibility:public"],
+)
+
+bzlformat_pkg(name = "bzlformat")

cmd/go_deps/README.md

@@ -0,0 +1,22 @@
+# Golang Dependencies
+
+The `bazel-starlib` repository uses Golang modules that contain exeutable packages (e.g., binaries).
+To ensure that these binary targets are downloaded and built properly, a simple Golang program
+exists to reference the required packages. [Gazelle](https://github.com/bazelbuild/bazel-gazelle) is
+then used to identify the transitive dependencies and saves them to `go_deps.bzl`.
+
+## To Add a Golang Dependency
+
+Update the `main.go` in this directory to depend upon the desired Golang package. Be sure to use the
+package in some way. Otherwise, `go mod tidy` will remove it.
+
+Execute the following to update the go module files, resolve the Golang dependencies and update the
+Bazel build files.
+
+```sh
+# bazel run @go_sdk//:bin/go -- mod tidy
+$ bazel run //:gazelle_update_repos
+$ bazel run //:gazelle
+```
+
+Reference the Golang binary target.

cmd/go_deps/main.go

@@ -0,0 +1,22 @@
+package main
+
+import (
+	"fmt"
+	"strings"
+
+	gmt "github.com/ekalinin/github-markdown-toc.go"
+)
+
+func main() {
+	fmt.Println("Hello, world.")
+
+	ghtoc := generateToc()
+	fmt.Printf("TOC:\n%s", ghtoc)
+}
+
+// Use the markdown package so that it is a dependency.
+func generateToc() string {
+	doc := gmt.NewGHDoc("", false, 0, 0, true, "", 2, false)
+	toc := *doc.GrabToc()
+	return strings.Join(toc, "\n")
+}

deps.bzl

@@ -15,57 +15,6 @@ def _bazeldoc_dependencies():
         ],
     )
 
-def _markdown_dependencies():
-    # GH140: Temporarily disable markdown while adding support for
-    # --incompatible_disallow_empty_glob.
-
-    # maybe(
-    #     http_archive,
-    #     name = "build_bazel_rules_nodejs",
-    #     sha256 = "e328cb2c9401be495fa7d79c306f5ee3040e8a03b2ebb79b022e15ca03770096",
-    #     urls = ["https://github.com/bazelbuild/rules_nodejs/releases/download/5.4.2/rules_nodejs-5.4.2.tar.gz"],
-    # )
-
-    maybe(
-        http_archive,
-        name = "io_bazel_rules_go",
-        sha256 = "099a9fb96a376ccbbb7d291ed4ecbdfd42f6bc822ab77ae6f1b5cb9e914e94fa",
-        urls = [
-            "https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.35.0/rules_go-v0.35.0.zip",
-            "https://github.com/bazelbuild/rules_go/releases/download/v0.35.0/rules_go-v0.35.0.zip",
-        ],
-    )
-
-    maybe(
-        http_archive,
-        name = "bazel_gazelle",
-        sha256 = "de69a09dc70417580aabf20a28619bb3ef60d038470c7cf8442fafcf627c21cb",
-        urls = [
-            "https://mirror.bazel.build/github.com/bazelbuild/bazel-gazelle/releases/download/v0.24.0/bazel-gazelle-v0.24.0.tar.gz",
-            "https://github.com/bazelbuild/bazel-gazelle/releases/download/v0.24.0/bazel-gazelle-v0.24.0.tar.gz",
-        ],
-    )
-
-    maybe(
-        http_archive,
-        name = "ekalinin_github_markdown_toc",
-        sha256 = "6bfeab2b28e5c7ad1d5bee9aa6923882a01f56a7f2d0f260f01acde2111f65af",
-        strip_prefix = "github-markdown-toc.go-1.2.0",
-        urls = ["https://github.com/ekalinin/github-markdown-toc.go/archive/refs/tags/1.2.0.tar.gz"],
-        build_file_content = """\
-load("@io_bazel_rules_go//go:def.bzl", "go_binary", "go_library")
-
-go_binary(
-    name = "gh_md_toc",
-    srcs = glob(["*.go"], exclude = ["*_test.go"]),
-    deps = [
-        "@in_gopkg_alecthomas_kingpin_v2//:go_default_library",
-    ],
-    visibility = ["//visibility:public"],
-)
-""",
-    )
-
 def _prebuilt_buildtools_dependencies():
     maybe(
         http_archive,
@@ -86,26 +35,6 @@ def _prebuilt_buildtools_dependencies():
     )
 
 def _compile_from_source_buildtools_dependencies():
-    maybe(
-        http_archive,
-        name = "io_bazel_rules_go",
-        sha256 = "099a9fb96a376ccbbb7d291ed4ecbdfd42f6bc822ab77ae6f1b5cb9e914e94fa",
-        urls = [
-            "https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.35.0/rules_go-v0.35.0.zip",
-            "https://github.com/bazelbuild/rules_go/releases/download/v0.35.0/rules_go-v0.35.0.zip",
-        ],
-    )
-
-    maybe(
-        http_archive,
-        name = "bazel_gazelle",
-        sha256 = "de69a09dc70417580aabf20a28619bb3ef60d038470c7cf8442fafcf627c21cb",
-        urls = [
-            "https://mirror.bazel.build/github.com/bazelbuild/bazel-gazelle/releases/download/v0.24.0/bazel-gazelle-v0.24.0.tar.gz",
-            "https://github.com/bazelbuild/bazel-gazelle/releases/download/v0.24.0/bazel-gazelle-v0.24.0.tar.gz",
-        ],
-    )
-
     maybe(
         http_archive,
         name = "com_google_protobuf",
@@ -136,17 +65,14 @@ def _compile_from_source_buildtools_dependencies():
 
 def bazel_starlib_dependencies(
         use_prebuilt_buildtools = True,
-        use_bazeldoc = True,
-        use_markdown = True):
+        use_bazeldoc = True):
     """Declares the dependencies for bazel-starlib.
 
     Args:
         use_prebuilt_buildtools: A `bool` specifying whether to use a prebuilt
                                  version of `bazelbuild/buildtools`.
         use_bazeldoc: A `bool` specifying whether the `bazeldoc` dependencies
                       should be loaded.
-        use_markdown: A `bool` specifying whether the `markdown` depdendencies
-                      should be loaded.
     """
     maybe(
         http_archive,
@@ -158,12 +84,29 @@ def bazel_starlib_dependencies(
         sha256 = "74d544d96f4a5bb630d465ca8bbcfe231e3594e5aae57e1edbf17a6eb3ca2506",
     )
 
+    maybe(
+        http_archive,
+        name = "io_bazel_rules_go",
+        sha256 = "099a9fb96a376ccbbb7d291ed4ecbdfd42f6bc822ab77ae6f1b5cb9e914e94fa",
+        urls = [
+            "https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.35.0/rules_go-v0.35.0.zip",
+            "https://github.com/bazelbuild/rules_go/releases/download/v0.35.0/rules_go-v0.35.0.zip",
+        ],
+    )
+
+    maybe(
+        http_archive,
+        name = "bazel_gazelle",
+        sha256 = "efbbba6ac1a4fd342d5122cbdfdb82aeb2cf2862e35022c752eaddffada7c3f3",
+        urls = [
+            "https://mirror.bazel.build/github.com/bazelbuild/bazel-gazelle/releases/download/v0.27.0/bazel-gazelle-v0.27.0.tar.gz",
+            "https://github.com/bazelbuild/bazel-gazelle/releases/download/v0.27.0/bazel-gazelle-v0.27.0.tar.gz",
+        ],
+    )
+
     if use_bazeldoc:
         _bazeldoc_dependencies()
 
-    if use_markdown:
-        _markdown_dependencies()
-
     if use_prebuilt_buildtools:
         _prebuilt_buildtools_dependencies()
     else:

examples/bzlformat/build_buildtools/WORKSPACE

@@ -10,7 +10,6 @@ load("@cgrindel_bazel_starlib//:deps.bzl", "bazel_starlib_dependencies")
 # Be sure to specify that you do not want to use the prebuilt tools
 bazel_starlib_dependencies(
     use_bazeldoc = False,
-    use_markdown = False,
     use_prebuilt_buildtools = False,
 )
 

examples/bzlformat/simple/WORKSPACE

@@ -7,10 +7,7 @@ local_repository(
 
 load("@cgrindel_bazel_starlib//:deps.bzl", "bazel_starlib_dependencies")
 
-bazel_starlib_dependencies(
-    use_bazeldoc = False,
-    use_markdown = False,
-)
+bazel_starlib_dependencies(use_bazeldoc = False)
 
 load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
 

examples/markdown/simple/WORKSPACE

@@ -7,10 +7,7 @@ local_repository(
 
 load("@cgrindel_bazel_starlib//:deps.bzl", "bazel_starlib_dependencies")
 
-bazel_starlib_dependencies(
-    use_bazeldoc = False,
-    use_markdown = True,
-)
+bazel_starlib_dependencies(use_bazeldoc = False)
 
 load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")