feat: support bzlmod usage of jq/yq

.github/workflows/ci.yaml

@@ -16,6 +16,12 @@ jobs:
     # The type of runner that the job will run on
     runs-on: ubuntu-latest
 
+    strategy:
+      matrix:
+        folder:
+          - "."
+          - "e2e/bzlmod"
+
     # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
       # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
@@ -33,7 +39,9 @@ jobs:
         env:
           # Bazelisk will download bazel to here
           XDG_CACHE_HOME: ~/.cache/bazel-repo
-        run: bazel --bazelrc=.github/workflows/ci.bazelrc --bazelrc=.bazelrc test //...
+        working-directory: ${{ matrix.folder }}
+        run: bazel --bazelrc=$GITHUB_WORKSPACE/.github/workflows/ci.bazelrc --bazelrc=.bazelrc test //...
       - name: integration tests
+        if: ${{ matrix.folder == '.' }}
         # Find all shell scripts within e2e, echo the filename, execute, fail on error
         run: find e2e/*.sh -maxdepth 1 -type f -exec sh -c 'echo "\n\n------------------------------- $0 -------------------------------" && "$0" || kill $PPID' \{\} \;

.prettierignore

@@ -1,4 +1,5 @@
 docs/*.md
+e2e/*/docs.md
 lib/tests/jq/*.json
 lib/tests/yq/empty.yaml
 lib/lib/tests/write_source_files/*.js

MODULE.bazel

@@ -0,0 +1,19 @@
+"aspect-build/bazel-lib"
+
+module(
+    name = "aspect_bazel_lib",
+    version = "0.0.0",
+    compatibility_level = 1,
+    toolchains_to_register = [
+        "@jq_toolchains//:all",
+        "@yq_toolchains//:all",
+    ],
+)
+
+bazel_dep(name = "bazel_skylib", version = "1.1.1")
+bazel_dep(name = "platforms", version = "0.0.4")
+bazel_dep(name = "stardoc", version = "0.5.0", repo_name = "io_bazel_stardoc")
+
+ext = use_extension("@aspect_bazel_lib//lib:extensions.bzl", "ext")
+use_repo(ext, "jq_toolchains")
+use_repo(ext, "yq_toolchains")

WORKSPACE

@@ -25,6 +25,12 @@ local_repository(
     path = "./lib/tests/external_test_repo",
 )
 
+# Avoid descending into the e2e workspaces
+local_repository(
+    name = "e2e_bzlmod",
+    path = "./e2e/bzlmod",
+)
+
 ############################################
 # Gazelle, for generating bzl_library targets
 load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies")

e2e/bzlmod/.bazelrc

@@ -0,0 +1 @@
+common --experimental_enable_bzlmod

e2e/bzlmod/BUILD.bazel

@@ -0,0 +1,40 @@
+"""Integration testing that aspect_bazel_lib works when used via bzlmod.
+
+NB: We don't use yq, so we can confirm that Bazel never fetches it.
+You can manually verify this after testing this repo with
+`ls $(bazel info output_base)/external | grep yq`
+You'll see a aspect_bazel_lib.ext.yq_toolchains repo, but no downloaded yq binary.
+"""
+
+load("@aspect_bazel_lib//lib:jq.bzl", "jq")
+load("@aspect_bazel_lib//lib:docs.bzl", "stardoc_with_diff_test")
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
+
+bzl_library(
+    name = "defs",
+    srcs = ["defs.bzl"],
+)
+
+# Validate that stardoc dependency works.
+# Note, stardoc is generally broken under bzlmod, see
+# https://github.com/bazelbuild/stardoc/issues/117
+# This happens to work because we don't reference any external repos
+# from defs.bzl.
+stardoc_with_diff_test(
+    name = "docs",
+    bzl_library_target = "//:defs",
+)
+
+# Validate that JQ works and resolves its toolchain
+jq(
+    name = "case_no_sources",
+    srcs = [],
+    filter = ".",
+)
+
+diff_test(
+    name = "test",
+    file1 = "case_no_sources",
+    file2 = "expected",
+)

e2e/bzlmod/MODULE.bazel

@@ -0,0 +1,13 @@
+module(
+    name = "e2e_bzlmod",
+    version = "0.0.0",
+    compatibility_level = 1,
+)
+
+bazel_dep(name = "aspect_bazel_lib", version = "0.9.8")
+bazel_dep(name = "bazel_skylib", version = "1.1.1")
+
+local_path_override(
+    module_name = "aspect_bazel_lib",
+    path = "../..",
+)

e2e/bzlmod/WORKSPACE

@@ -0,0 +1,2 @@
+# Marker file that this folder is the root of a Bazel workspace.
+# See MODULE.bazel for dependencies and setup.

e2e/bzlmod/defs.bzl

@@ -0,0 +1 @@
+# no rules

e2e/bzlmod/docs.md

@@ -0,0 +1,4 @@
+<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+
+
+

e2e/bzlmod/expected

@@ -0,0 +1 @@
+null

lib/extensions.bzl

@@ -0,0 +1,16 @@
+"Module extensions for use with bzlmod"
+
+load(
+    "@aspect_bazel_lib//lib:repositories.bzl",
+    "register_jq_toolchains",
+    "register_yq_toolchains",
+)
+
+def _toolchain_extension(_):
+    register_yq_toolchains(register = False)
+    register_jq_toolchains(register = False)
+
+# TODO: some way for users to control repo name/version of the tools installed
+ext = module_extension(
+    implementation = _toolchain_extension,
+)

lib/private/docs.bzl

@@ -6,25 +6,17 @@ load("//lib:write_source_files.bzl", "write_source_files")
 def stardoc_with_diff_test(
         name,
         bzl_library_target,
-        aspect_template = "@io_bazel_stardoc//stardoc:templates/markdown_tables/aspect.vm",
-        func_template = "@io_bazel_stardoc//stardoc:templates/markdown_tables/func.vm",
-        header_template = "@io_bazel_stardoc//stardoc:templates/markdown_tables/header.vm",
-        provider_template = "@io_bazel_stardoc//stardoc:templates/markdown_tables/provider.vm",
-        rule_template = "@io_bazel_stardoc//stardoc:templates/markdown_tables/rule.vm",
-        suggested_update_target = "//docs:update"):
+        suggested_update_target = "//docs:update",
+        **kwargs):
     """Creates a stardoc target, diff test, and an executable to rule to write the generated doc to the source tree and test that it's up to date.
 
     This is helpful for minimizing boilerplate in repos wih lots of stardoc targets.
 
     Args:
         name: the name of the stardoc file to be written to the current source directory (.md will be appended to the name). Call bazel run on this target to update the file.
         bzl_library_target: the label of the `bzl_library` target to generate documentation for
-        aspect_template: the label or path to the Velocity aspect template to use with stardoc
-        func_template: the label or path to the Velocity function/macro template to use with stardoc
-        header_template: the label or path to the Velocity header template to use with stardoc
-        provider_template: the label or path to the Velocity provider template to use with stardoc
-        rule_template: the label or path to the Velocity rule template to use with stardoc
         suggested_update_target: the target suggested to be run when a doc is out of date (should be the label for [update_docs](#update_docs))
+        **kwargs: additional attributes passed to the stardoc() rule, such as for overriding the templates
     """
 
     stardoc_label = name + "-docgen"
@@ -36,12 +28,8 @@ def stardoc_with_diff_test(
         out = name + "-docgen.md",
         input = bzl_library_target + ".bzl",
         deps = [bzl_library_target],
-        aspect_template = aspect_template,
-        func_template = func_template,
-        header_template = header_template,
-        provider_template = provider_template,
-        rule_template = rule_template,
         tags = ["package:" + native.package_name()],  # Tag the package name which will help us reconstruct the write_source_files label in update_docs
+        **kwargs
     )
 
     write_source_files(

lib/repositories.bzl

@@ -21,20 +21,23 @@ def aspect_bazel_lib_dependencies():
 DEFAULT_JQ_VERSION = _DEFAULT_JQ_VERSION
 DEFAULT_YQ_VERSION = _DEFAULT_YQ_VERSION
 
-def register_jq_toolchains(name = "jq", version = DEFAULT_JQ_VERSION):
+def register_jq_toolchains(name = "jq", version = DEFAULT_JQ_VERSION, register = True):
     """Registers jq toolchain and repositories
 
     Args:
         name: override the prefix for the generated toolchain repositories
         version: the version of jq to execute (see https://github.com/stedolan/jq/releases)
+        register: whether to call through to native.register_toolchains.
+            Should be True for WORKSPACE users, but false when used under bzlmod extension
     """
     for [platform, meta] in JQ_PLATFORMS.items():
         jq_platform_repo(
             name = "%s_%s" % (name, platform),
             platform = platform,
             version = version,
         )
-        native.register_toolchains("@%s_toolchains//:%s_toolchain" % (name, platform))
+        if register:
+            native.register_toolchains("@%s_toolchains//:%s_toolchain" % (name, platform))
 
     jq_host_alias_repo(
         name = "%s_host" % name,
@@ -46,20 +49,23 @@ def register_jq_toolchains(name = "jq", version = DEFAULT_JQ_VERSION):
         user_repository_name = name,
     )
 
-def register_yq_toolchains(name = "yq", version = DEFAULT_YQ_VERSION):
+def register_yq_toolchains(name = "yq", version = DEFAULT_YQ_VERSION, register = True):
     """Registers yq toolchain and repositories
 
     Args:
         name: override the prefix for the generated toolchain repositories
         version: the version of yq to execute (see https://github.com/mikefarah/yq/releases)
+        register: whether to call through to native.register_toolchains.
+            Should be True for WORKSPACE users, but false when used under bzlmod extension
     """
     for [platform, meta] in YQ_PLATFORMS.items():
         yq_platform_repo(
             name = "%s_%s" % (name, platform),
             platform = platform,
             version = version,
         )
-        native.register_toolchains("@%s_toolchains//:%s_toolchain" % (name, platform))
+        if register:
+            native.register_toolchains("@%s_toolchains//:%s_toolchain" % (name, platform))
 
     yq_host_alias_repo(
         name = "%s_host" % name,