chore: document that we don't support WORKSPACE

.github/workflows/release_prep.sh

@@ -19,21 +19,9 @@ cat << EOF
 
 \`\`\`starlark
 bazel_dep(name = "aspect_rules_eslint", version = "${TAG:1}")
-\`\`\`
-
-## Using WORKSPACE
-
-Paste this snippet into your `WORKSPACE.bazel` file:
 
-\`\`\`starlark
-load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
-http_archive(
-    name = "aspect_rules_eslint",
-    sha256 = "${SHA}",
-    strip_prefix = "${PREFIX}",
-    url = "https://github.com/aspect-build/rules_eslint/releases/download/${TAG}/${ARCHIVE}",
-)
+# Depending on which linters you setup, you may need more dependencies.
+# See example/MODULE.bazel in the rules_lint repository.
+\`\`\`
 EOF
 
-awk 'f;/--SNIP--/{f=1}' e2e/smoke/WORKSPACE.bazel
-echo "\`\`\`" 

MODULE.bazel

@@ -5,8 +5,8 @@ module(
     compatibility_level = 1,
 )
 
-bazel_dep(name = "aspect_bazel_lib", version = "1.31.2")
-bazel_dep(name = "aspect_rules_js", version = "1.32.2")
+bazel_dep(name = "aspect_bazel_lib", version = "1.36.0")
+bazel_dep(name = "aspect_rules_js", version = "1.32.6")
 bazel_dep(name = "bazel_skylib", version = "1.4.1")
 bazel_dep(name = "platforms", version = "0.0.7")
 

README.md

@@ -18,7 +18,7 @@ Features:
 How developers use it:
 
 1. (preferred) This ruleset provides an Aspect CLI plugin,
-  so it can register the missing 'lint' command and users just type `bazel lint //path/to:targets`.
+   so it can register the missing 'lint' command and users just type `bazel lint //path/to:targets`.
 2. Run with vanilla Bazel, by placing a couple commands in a shell script, Makefile, or similar wrapper.
 
 This project is inspired by the design for [Tricorder].
@@ -38,5 +38,40 @@ TODO: step-by-step instructions to add a linter in this repo, and maybe how to a
 
 ## Installation
 
+rules_lint currently only works with bzlmod under Bazel 6+.
+This is because we accumulate dependencies which are difficult to express
+in a WORKSPACE file.
+We might add support for WORKSPACE in the future.
+
 Follow instructions from the release you wish to use:
 <https://github.com/aspect-build/rules_lint/releases>
+
+Next, you must declare your linters as Bazel aspects.
+
+> This is needed because Bazel only allows aspect attributes of type
+> `bool`, `int` or `string`.
+> We want to follow the documentation from
+> https://bazel.build/extending/aspects#aspect_definition_2:
+> Aspects are also allowed to have private attributes of types label or label_list. Private label attributes can be used to specify dependencies on tools or libraries that are needed for actions generated by aspects.
+
+We suggest creating a `lint.bzl` file in whatever package contains most of your
+custom Bazel configuration.
+This `lint.bzl` should contain linter aspect declarations.
+See the `docs/` folder for "aspect factory functions" that declare your linters.
+
+Finally, reference those linters as `//path/to:lint.bzl%mylinter`
+in the lint runner.
+
+If you use the Aspect CLI, then include a block like the following in `.aspect/cli/config.yaml`:
+
+```
+plugins:
+  - name: lint-plugin
+    properties:
+      lint_aspects:
+        - //:lint.bzl%eslint
+        - //:lint.bzl%buf
+```
+
+If you don't use Aspect CLI, you can put these in some other wrapper like a shell script that runs the linter aspects over the requested targets.
+See the `lint.sh` script in the `example/` folder.

docs/BUILD.bazel

@@ -0,0 +1,15 @@
+# This load statement must be in the docs/ package rather than anything users depend on
+# so that the dependency on stardoc doesn't leak to them.
+load("@aspect_bazel_lib//lib:docs.bzl", "stardoc_with_diff_test", "update_docs")
+
+stardoc_with_diff_test(
+    name = "buf",
+    bzl_library_target = "//lint:buf",
+)
+
+stardoc_with_diff_test(
+    name = "eslint",
+    bzl_library_target = "//lint:eslint",
+)
+
+update_docs(name = "update")

lint/BUILD.bazel

@@ -1,5 +1,7 @@
 load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 
+exports_files(glob(["*.bzl"]))
+
 bzl_library(
     name = "buf",
     srcs = ["buf.bzl"],
@@ -11,5 +13,8 @@ bzl_library(
     name = "eslint",
     srcs = ["eslint.bzl"],
     visibility = ["//visibility:public"],
-    deps = ["@aspect_bazel_lib//lib:copy_to_bin"],
+    deps = [
+        "@aspect_bazel_lib//lib:copy_to_bin",
+        "@aspect_rules_js//js:libs",
+    ],
 )

lint/buf.bzl

@@ -1,6 +1,17 @@
-"API for calling buf lint as an aspect"
+"""API for calling declaring a buf lint aspect.
+
+Typical usage:
+
+```
+load("@aspect_rules_lint//lint:buf.bzl", "buf_lint_aspect")
+
+buf = buf_lint_aspect(
+    config = "@@//path/to:buf.yaml",
+)
+```
+"""
+
 load("@rules_proto//proto:defs.bzl", "ProtoInfo")
-load("@aspect_bazel_lib//lib:paths.bzl", "to_output_relative_path")
 
 def _short_path(file, dir_exp):
     return file.path
@@ -9,11 +20,6 @@ def _buf_action(ctx, toolchain, target, report):
     config = json.encode({
         "input_config": "" if ctx.file._config == None else ctx.file._config.short_path,
     })
-    # files_to_include = []
-    # if ctx.file.config != None:
-    #     files_to_include.append(ctx.file.config)
-    # return protoc_plugin_test(ctx, proto_infos, ctx.executable._protoc, ctx.toolchains[_TOOLCHAIN].cli, config, files_to_include)
-    # def protoc_plugin_test(ctx, proto_infos, protoc, plugin, config, files_to_include = []):
 
     deps = depset(
         [target[ProtoInfo].direct_descriptor_set],
@@ -23,7 +29,6 @@ def _buf_action(ctx, toolchain, target, report):
     sources = []
     source_files = []
 
-
     for f in target[ProtoInfo].direct_sources:
         source_files.append(f)
 
@@ -44,7 +49,7 @@ def _buf_action(ctx, toolchain, target, report):
         inputs = depset([
             ctx.file._config,
             ctx.executable._protoc,
-            ctx.toolchains["@rules_buf//tools/protoc-gen-buf-lint:toolchain_type"].cli
+            ctx.toolchains["@rules_buf//tools/protoc-gen-buf-lint:toolchain_type"].cli,
         ], transitive = [deps]),
         outputs = [report],
         command = """\
@@ -53,7 +58,6 @@ def _buf_action(ctx, toolchain, target, report):
         arguments = [args],
     )
 
-
 def _buf_lint_aspect_impl(target, ctx):
     if ctx.rule.kind in ["proto_library"]:
         report = ctx.actions.declare_file(target.label.name + ".buf-report.txt")
@@ -66,11 +70,14 @@ def _buf_lint_aspect_impl(target, ctx):
         OutputGroupInfo(report = results),
     ]
 
-
 def buf_lint_aspect(config, toolchain = "@rules_buf//tools/protoc-gen-buf-lint:toolchain_type"):
     """A factory function to create a linter aspect.
+
+    Args:
+        config: label of the the buf.yaml file
+        toolchain: override the default toolchain of the protoc-gen-buf-lint tool
     """
-    return aspect( 
+    return aspect(
         implementation = _buf_lint_aspect_impl,
         attr_aspects = ["deps"],
         attrs = {

lint/eslint.bzl

@@ -1,4 +1,16 @@
-"Public API re-exports"
+"""API for calling declaring an ESLint lint aspect.
+
+Typical usage:
+
+```
+load("@aspect_rules_lint//lint:eslint.bzl", "eslint_aspect")
+
+eslint = eslint_aspect(
+    binary = "@@//path/to:eslint",
+    config = "@@//path/to:eslintrc",
+)
+```
+"""
 
 load("@aspect_bazel_lib//lib:copy_to_bin.bzl", "copy_files_to_bin_actions")
 load("@aspect_rules_js//js:libs.bzl", "js_lib_helpers")
@@ -32,6 +44,7 @@ def _eslint_action(ctx, executable, srcs, report, use_exit_code = False):
     env = {"BAZEL_BINDIR": ctx.bin_dir.path}
 
     inputs = copy_files_to_bin_actions(ctx, srcs)
+
     # Add the config file along with any deps it has on npm packages
     inputs.extend(js_lib_helpers.gather_files_from_js_providers(
         [ctx.attr._config_file],
@@ -71,10 +84,18 @@ def _eslint_aspect_impl(target, ctx):
 
 def eslint_aspect(binary, config):
     """A factory function to create a linter aspect.
+
+    Args:
+        binary: the eslint binary, typically a rule like
+
+            ```
+            load("@npm//:eslint/package_json.bzl", eslint_bin = "bin")
+            eslint_bin.eslint_binary(name = "eslint")
+            ```
+        config: label of the eslint config file
     """
     return aspect(
         implementation = _eslint_aspect_impl,
-        # attr_aspects = ["deps"],
         attrs = {
             "_eslint": attr.label(
                 default = binary,