refactor: switch to gazelle (#478)

alexeagle · web-flow · commit f853cb010ffa · 2025-10-27T20:33:23.000-07:00
diff --git a/.aspect/cli/config.yaml b/.aspect/cli/config.yaml
@@ -1,12 +1,3 @@
-configure:
-  languages:
-    javascript: true
-    go: true
-    protobuf: true
-    python: true
-  plugins:
-    - .aspect/cli/main.star
-    - .aspect/cli/rules_cc.star
 plugins:
     - name: fix-visibility
       from: github.com/aspect-build/plugin-fix-visibility
diff --git a/.aspect/cli/main.axl b/.aspect/cli/main.axl
diff --git a/.aspect/cli/rules_cc.axl b/.aspect/cli/rules_cc.axl
diff --git a/.aspect/workflows/config.yaml b/.aspect/workflows/config.yaml
@@ -1,6 +1,6 @@
 # See https://docs.aspect.build/workflows/configuration
 tasks:
-  - configure:
+  - gazelle:
   - checkout:
       update_strategy: rebase
   - lint:
diff --git a/.bazeliskrc b/.bazeliskrc
diff --git a/.bazelrc b/.bazelrc
@@ -7,11 +7,14 @@ import %workspace%/tools/preset.bazelrc
 # We have a lot of dependencies and are okay with some of them bringing a newer version via a transitive dep.
 common --check_direct_dependencies=off
 
+# When running locally, warn about unconfigured git hooks.
+common --workspace_status_command=githooks/check-config.sh
+# But not on CI.
+common:ci --workspace_status_command=
 # Placeholder for your actual stamping logic
-build --workspace_status_command='echo BUILD_VERSION v1.2.3'
+build:release --workspace_status_command='echo BUILD_VERSION v1.2.3'
 
-# As an alternative to using Aspect CLI to get the 'bazel lint' command,
-# users could run 'bazel build --config=lint' to produce the linter reports.
+# 'bazel build --config=lint' will produce the linter reports.
 build:lint --aspects=//tools/lint:linters.bzl%buf
 build:lint --aspects=//tools/lint:linters.bzl%clang_tidy
 build:lint --aspects=//tools/lint:linters.bzl%eslint
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -16,10 +16,10 @@ workflows:
         requires:
         - aw-test
         workspace: .
-    - aw-configure:
+    - aw-format:
         context: []
         workspace: .
-    - aw-format:
+    - aw-gazelle:
         context: []
         workspace: .
     - aw-lint:
@@ -102,7 +102,7 @@ jobs:
         name: Delivery
         no_output_timeout: 180m
     working_directory: /mnt/ephemeral/workdir
-  aw-configure:
+  aw-format:
     environment:
       ASPECT_WORKFLOWS_CIRCLE_PIPELINE_NUMBER: << pipeline.number >>
       ASPECT_WORKFLOWS_CIRCLE_PIPELINE_PROJECT_TYPE: << pipeline.project.type >>
@@ -135,8 +135,8 @@ jobs:
         name: Checkout health
         no_output_timeout: 180m
     - run:
-        command: rosetta run configure --workspace << parameters.workspace >>
-        name: Configure
+        command: rosetta run format --workspace << parameters.workspace >>
+        name: Format
         no_output_timeout: 180m
     - store_artifacts:
         path: /workflows/artifacts
@@ -146,7 +146,7 @@ jobs:
         no_output_timeout: 10m
         when: always
     working_directory: /mnt/ephemeral/workdir
-  aw-format:
+  aw-gazelle:
     environment:
       ASPECT_WORKFLOWS_CIRCLE_PIPELINE_NUMBER: << pipeline.number >>
       ASPECT_WORKFLOWS_CIRCLE_PIPELINE_PROJECT_TYPE: << pipeline.project.type >>
@@ -179,8 +179,8 @@ jobs:
         name: Checkout health
         no_output_timeout: 180m
     - run:
-        command: rosetta run format --workspace << parameters.workspace >>
-        name: Format
+        command: rosetta run gazelle --workspace << parameters.workspace >>
+        name: Gazelle
         no_output_timeout: 180m
     - store_artifacts:
         path: /workflows/artifacts
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -6,13 +6,6 @@
 # See https://pre-commit.com for more information
 # See https://pre-commit.com/hooks.html for more hooks
 repos:
-- repo: local
-  hooks:
-  - id: format
-    name: Format
-    entry: bazel run //tools/format:format
-    language: system
-    types: [text]
 # Lint for starlark code.
 # Special case since rules_lint doesn't want to require that BUILD files are
 # listed as the srcs of some *_library target.
diff --git a/BUILD.bazel b/BUILD.bazel
@@ -1,26 +1,54 @@
-# A top-level build file most often contains tooling and convenience aliases.
 load("@aspect_rules_js//js:defs.bzl", "js_library")
+load("@gazelle//:def.bzl", "gazelle")
 load("@npm//:defs.bzl", "npm_link_all_packages")
 
+package(default_visibility = ["//:__subpackages__"])
+
+# gazelle:prefix github.com/aspect-build/bazel-examples
+
 # JS BUILD generation is opt-in per project
-# aspect:js disabled
+# gazelle:js disabled
 
 # Global config shared across monorepo.
-# aspect:js_npm_package_target_name pkg
-# aspect:js_package_rule_kind js_library
-# aspect:js_project_naming_convention tsc
+# gazelle:js_npm_package_target_name pkg
+# gazelle:js_package_rule_kind js_library
+# gazelle:js_project_naming_convention tsc
 
 # TODO(alex): refactor this folder to follow python gazelle conventions
 # gazelle:exclude py_mypy
-package(default_visibility = ["//:__subpackages__"])
-
-npm_link_all_packages(name = "node_modules")
+gazelle(
+    name = "gazelle",
+    env = {
+        "ORION_EXTENSIONS_DIR": ".aspect/cli",
+        "ENABLE_LANGUAGES": ",".join([
+            "js",
+            "go",
+            "proto",
+            "python",
+        ]),
+    },
+    extra_args = ["-index=lazy"],
+    gazelle = "@multitool//tools/gazelle",
+)
 
-alias(
-    name = "format",
-    actual = "//tools/format",
+gazelle(
+    name = "gazelle.check",
+    env = {
+        "ORION_EXTENSIONS_DIR": ".aspect/cli",
+        "ENABLE_LANGUAGES": ",".join([
+            "js",
+            "go",
+            "proto",
+            "python",
+        ]),
+    },
+    extra_args = ["-index=lazy"],
+    gazelle = "@multitool//tools/gazelle",
+    mode = "diff",
 )
 
+npm_link_all_packages(name = "node_modules")
+
 exports_files(
     [
         ".clang-tidy",
@@ -42,3 +70,9 @@ js_library(
         ":node_modules/typescript-eslint",
     ],
 )
+
+alias(
+    name = "format",
+    actual = "//tools/format:format",
+    visibility = ["//visibility:public"],
+)
diff --git a/README.bazel.md b/README.bazel.md
@@ -4,8 +4,8 @@ This repository uses Bazel to provide a monorepo developer experience.
 
 ## Formatting code
 
-- Run `bazel run format` to re-format all files locally.
-- Run `bazel run format path/to/file` to re-format a single file.
+- Run `bazel run //tools/format` to re-format all files locally.
+- Run `bazel run //tools/format path/to/file` to re-format a single file.
 - Run `pre-commit install` to auto-format changed files on `git commit`; see https://pre-commit.com/.
 
 ## Linting code
diff --git a/githooks/check-config.sh b/githooks/check-config.sh
@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+inside_work_tree=$(git rev-parse --is-inside-work-tree 2>/dev/null)
+
+# Encourage developers to setup githooks
+IFS='' read -r -d '' GITHOOKS_MSG <<"EOF"
+    cat <<EOF
+  It looks like the git config option core.hooksPath is not set.
+  This repository uses hooks stored in githooks/ to run tools such as formatters.
+  You can disable this warning by running:
+
+    echo "common --workspace_status_command=" >> ~/.bazelrc
+
+  To set up the hooks, please run:
+
+    git config core.hooksPath githooks
+EOF
+
+if [ "${inside_work_tree}" = "true" ] && [ "$EUID" -ne 0 ] && [ -z "$(git config core.hooksPath)" ]; then
+    echo >&2 "${GITHOOKS_MSG}"
+fi
diff --git a/githooks/pre-commit b/githooks/pre-commit
@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# Get staged files and format them
+git diff --cached --diff-filter=AM --name-only -z | xargs --null --no-run-if-empty bash -c '
+  if [ $# -gt 0 ]; then
+    bazel run //tools/format -- "$@"
+
+    if ! git diff --quiet -- "$@"; then
+      echo "❌ Some staged files were modified by the pre-commit hook."
+      echo "Please stage the changes and try committing again:"
+      git diff --stat -- "$@"
+      exit 1
+    fi
+  fi
+' _
diff --git a/tools/preset.bazelrc b/tools/preset.bazelrc
@@ -20,6 +20,15 @@ common --nobuild_runfile_links
 common:debug --nocache_test_results
 # Docs: https://registry.build/flag/bazel@8.2.0?filter=cache_test_results
 
+# Don’t encourage a rules author to update their deps if not needed.
+# These bazel_dep calls should indicate the minimum version constraint of the ruleset.
+# If the author instead updates to the newest of any of their transitives, as this flag would suggest,
+# then they'll also force their dependents to a newer version.
+# Context:
+# https://bazelbuild.slack.com/archives/C014RARENH0/p1691158021917459?thread_ts=1691156601.420349&cid=C014RARENH0
+common:ruleset --check_direct_dependencies="off"
+# Docs: https://registry.build/flag/bazel@8.2.0?filter=check_direct_dependencies
+
 # On CI, use colors to highlight output on the screen. Set to `no` if your CI does not display colors.
 common:ci --color="yes"
 # Docs: https://registry.build/flag/bazel@8.2.0?filter=color
@@ -40,17 +49,23 @@ common --enable_platform_specific_config
 common --noexperimental_check_external_repository_files
 # Docs: https://registry.build/flag/bazel@8.2.0?filter=experimental_check_external_repository_files
 
+# Always download coverage files for tests from the remote cache. By default, coverage files are not
+# downloaded on test result cache hits when --remote_download_minimal is enabled, making it impossible
+# to generate a full coverage report.
+common --experimental_fetch_all_coverage_outputs
+# Docs: https://registry.build/flag/bazel@8.2.0?filter=experimental_fetch_all_coverage_outputs
+
 # Set this flag to enable re-tries of failed tests on CI.
 # When any test target fails, try one or more times. This applies regardless of whether the "flaky"
 # tag appears on the target definition.
 # This is a tradeoff: legitimately failing tests will take longer to report,
 # but we can "paper over" flaky tests that pass most of the time.
-# 
+#
 # An alternative is to mark every flaky test with the `flaky = True` attribute, but this requires
 # the buildcop to make frequent code edits.
 # This flag is not recommended for local builds: flakiness is more likely to get fixed if it is
 # observed during development.
-# 
+#
 # Note that when passing after the first attempt, Bazel will give a special "FLAKY" status rather than "PASSED".
 test:ci --flaky_test_attempts=2
 # Docs: https://registry.build/flag/bazel@8.2.0?filter=flaky_test_attempts
@@ -66,6 +81,13 @@ common:ci --grpc_keepalive_time="30s"
 common --heap_dump_on_oom
 # Docs: https://registry.build/flag/bazel@8.2.0?filter=heap_dump_on_oom
 
+# Allow the Bazel server to check directory sources for changes. Ensures that the Bazel server
+# notices when a directory changes, if you have a directory listed in the srcs of some target.
+# Recommended when using [copy_directory](https://github.com/bazel-contrib/bazel-lib/blob/main/docs/copy_directory.md)
+# and [rules_js](https://github.com/aspect-build/rules_js) since npm package are source directories inputs to copy_directory actions.
+startup --host_jvm_args="-DBAZEL_TRACK_SOURCE_DIRECTORIES=1"
+# Docs: https://registry.build/flag/bazel@8.2.0?filter=host_jvm_args
+
 # By default, Bazel automatically creates __init__.py files for py_binary and py_test targets.
 # From https://github.com/bazelbuild/bazel/issues/10076:
 # > It is magic at a distance.
@@ -81,9 +103,18 @@ common --incompatible_default_to_explicit_init_py
 common --incompatible_strict_action_env
 # Docs: https://registry.build/flag/bazel@8.2.0?filter=incompatible_strict_action_env
 
-# On CI, only download remote outputs of top level targets to the local machine.
-common:ci --remote_download_toplevel
-# Docs: https://registry.build/flag/bazel@8.2.0?filter=remote_download_toplevel
+# On CI, don't download remote outputs to the local machine.
+# Most CI pipelines don't need to access the files and they can remain at rest on the remote cache.
+# Significant time can be spent on needless downloads, which is especially noticeable on fully-cached builds.
+#
+# If you do need to download files, the fastest options are:
+# - (preferred) Use `remote_download_regex` to specify the files to download.
+# - Use the Remote Output Service (https://blog.bazel.build/2024/07/23/remote-output-service.html)
+# to lazy-materialize specific files after the build completes.
+# - Perform a second bazel command with specific targets and override this flag with the `toplevel` value.
+# - To copy executable targets, you can use `bazel run --run_under=cp //some:binary_target <destination path>`.
+common:ci --remote_download_outputs="minimal"
+# Docs: https://registry.build/flag/bazel@8.2.0?filter=remote_download_outputs
 
 # On CI, fall back to standalone local execution strategy if remote execution fails.
 # Otherwise, when a grpc remote cache connection fails, it would fail the build.
@@ -94,10 +125,23 @@ common:ci --remote_local_fallback
 common:ci --remote_timeout=3600
 # Docs: https://registry.build/flag/bazel@8.2.0?filter=remote_timeout
 
+# Do not upload locally executed action results to the remote cache.
+# This should be the default for local builds so local builds cannot poison the remote cache.
+#
+# Note that this flag is flipped to True under --config=ci, see below.
+common --noremote_upload_local_results
+# Docs: https://registry.build/flag/bazel@8.2.0?filter=remote_upload_local_results
+
 # On CI, upload locally executed action results to the remote cache.
 common:ci --remote_upload_local_results
 # Docs: https://registry.build/flag/bazel@8.2.0?filter=remote_upload_local_results
 
+# Repository rules, such as rules_jvm_external: put Bazel's JDK on the path.
+# Avoids non-hermeticity from dependency on a JAVA_HOME pointing at a system JDK
+# see https://github.com/bazelbuild/rules_jvm_external/issues/445
+common --repo_env="JAVA_HOME=../bazel_tools/jdk"
+# Docs: https://registry.build/flag/bazel@8.2.0?filter=repo_env
+
 # Reuse sandbox directories between invocations.
 # Directories used by sandboxed non-worker execution may be reused to avoid unnecessary setup costs.
 # Saves time on sandbox creation and deletion when many of the same kind of action is spawned during the build.
@@ -139,6 +183,11 @@ common:ci --terminal_columns=143
 common --test_output="errors"
 # Docs: https://registry.build/flag/bazel@8.2.0?filter=test_output
 
+# Stream stdout/stderr output from each test in real-time.
+# This provides immediate feedback during test execution, useful for debugging test failures.
+common:debug --test_output="streamed"
+# Docs: https://registry.build/flag/bazel@8.2.0?filter=test_output
+
 # Run one test at a time in exclusive mode.
 # This prevents test interference and provides clearer output when debugging test issues.
 common:debug --test_strategy="exclusive"
@@ -154,4 +203,3 @@ test:ci --test_summary="terse"
 # Set to a high value to allow tests to complete even if they take longer than expected.
 common:debug --test_timeout=9999
 # Docs: https://registry.build/flag/bazel@8.2.0?filter=test_timeout
-
diff --git a/tools/tools.lock.json b/tools/tools.lock.json
@@ -89,6 +89,31 @@
       }
     ]
   },
+  "gazelle": {
+    "binaries": [
+      {
+        "kind": "file",
+        "url": "https://github.com/aspect-build/aspect-gazelle/releases/download/2025.40.99+1859933/gazelle-darwin_arm64_cgo",
+        "sha256": "70b73d2333d08938ba05222072b31d587b22e1d122837572078cd24dd1d13585",
+        "os": "macos",
+        "cpu": "arm64"
+      },
+      {
+        "kind": "file",
+        "url": "https://github.com/aspect-build/aspect-gazelle/releases/download/2025.40.99+1859933/gazelle-linux_amd64_cgo",
+        "sha256": "5a0dd88684c5467a6e18567bed9ce472cf21bb98af6f3a5666d15a33e58247db",
+        "os": "linux",
+        "cpu": "x86_64"
+      },
+      {
+        "kind": "file",
+        "url": "https://github.com/aspect-build/aspect-gazelle/releases/download/2025.40.99+1859933/gazelle-linux_arm64_cgo",
+        "sha256": "5b5ded1d75a38581a03390662d702636d601ce348a05453c18086fe8351a22c2",
+        "os": "linux",
+        "cpu": "arm64"
+      }
+    ]
+  },
   "ibazel": {
     "binaries": [
       {
