Run linters and formatters under Bazel

[!NOTE] This repository uses the Aspect CLI for CI and local development. See the docs and install instructions to get started.

This ruleset integrates linting and formatting as first-class concepts under Bazel.

Features:

• No changes needed to rulesets. Works with the Bazel rules you already use.
• No changes needed to BUILD files. You don't need to add lint wrapper macros, and lint doesn't appear in bazel query output. Instead, users simply lint their existing *_library targets.
• Incremental. Lint checks (including producing fixes) are run as normal Bazel actions, which means they support Remote Execution and the outputs are stored in the Remote Cache.
• Lint results can be presented in various ways, such as Code Review comments or failing tests. See Usage.
• Can lint changes only. It's fine if your repository has a lot of existing issues. It's not necessary to fix or suppress all of them to start linting new changes. This is sometimes called the "Water Leak Principle": you should always fix a leak before mopping the spill.
• Can format files not known to Bazel. Formatting just runs directly on the file tree. No need to create sh_library targets for your shell scripts, for example.
• Honors the same configuration files you use for these tools outside Bazel (e.g. in the editor)

Watch Alex's talk at BazelCon 2024:

Better DX with the Aspect CLI

You can drive linting straight from Bazel, but the experience is rough: you run a verbose build to produce report files, then hunt them down under bazel-out/ and cat them yourself.

$ bazel build --config=lint --output_groups=rules_lint_human //...
INFO: Build completed successfully, 8 total actions
# ...no findings printed. Now go find and cat the reports:
$ cat bazel-out/*/bin/src/hello.AspectRulesLintShellCheck.out
In src/hello.sh line 10:
grep '*foo*' file
     ^-----^ SC2063 (warning): Grep uses regex, but this looks like a glob.

The Aspect CLI adds a first-class aspect lint command that runs the same Bazel aspects, then collects and prints every finding for you — grouped by linter, tagged by severity, with file:line and rule, and one-key interactive fixes:

$ aspect lint //...

🧹 Linters (1): ShellCheck

Lint findings
  ℹ️ src/hello.sh:4 · ShellCheck — Double quote to prevent globbing and word splitting.
  ⚠️ src/hello.sh:10 · ShellCheck — Grep uses regex, but this looks like a glob.

It also scopes findings to your changed lines by default (the "Water Leak Principle") and applies fixes with aspect lint --fix.

On CI, the free Aspect Workflows GitHub App makes this shine: every aspect lint task posts a rich GitHub status check — findings grouped by linter and severity with file:line and rule, a per-linter summary table, and a copy-paste reproduce command — and surfaces the same findings as inline PR review comments. Install and authenticate it in a few minutes; no server to run.

The screenshot above is a live status check from this repo's examples/python lint task — open the real thing.

Configure it once in .aspect/config.axl by pointing the lint task at your aspects — no --config=lint or output-group flags to remember:

def config(ctx: ConfigContext):
    ctx.tasks["lint"].args.aspects = ["//tools/lint:linters.bzl%shellcheck"]

Try it in this repo: every linter under examples/ is wired up for aspect lint. After installing the CLI:

$ cd examples/shell && aspect lint //...

Formatting

The same applies to formatting. Instead of bazel run //tools/format, the aspect format command runs your //tools/format target, formats only your changed files by default (or --scope=all for the whole tree), and reports exactly what it touched — with a ready-to-run fix command:

$ aspect format

→ ✨ Format · Formatting changed files
→ 📋 Diff · Computing format diff
2 files were modified:
  - src/hello.sh
  - src/sourced_dep.sh

On CI it posts a format status check via the same GitHub App, and --severity chooses whether an unformatted file warns or fails the build. It works out of the box — aspect format already targets //tools/format, so no extra config is needed:

$ cd examples/shell && aspect format

See the Aspect CLI overview and the lint and format task docs.

Supported tools

New tools are being added frequently, so check this page again!

Linters which are not language-specific:

• keep-sorted

Language	Formatter	Linter(s)
C / C++	clang-format	clang-tidy or cppcheck
CUE	cue fmt
Cuda	clang-format
CSS, Less, Sass	Prettier	Stylelint
F#	Fantomas
Go	gofmt or gofumpt
Go Module	modfmt
Gherkin	prettier-plugin-gherkin
GraphQL	Prettier
HCL (Hashicorp Config)	terraform fmt
HTML	Prettier
JSON	Prettier
Java	google-java-format	pmd , Checkstyle, Spotbugs
JavaScript	Prettier	ESLint
HTML templates	djlint
Jsonnet	jsonnetfmt
Kotlin	ktfmt	ktlint
Markdown	Prettier	Vale
Pkl	pkl
Protocol Buffer	buf	buf lint
Python	ruff	bandit, flake8, pydoclint, pylint, ruff, ty
QML	qmlformat	qmllint
Ruby		RuboCop, Standard
Rust	rustfmt	clippy
SQL	prettier-plugin-sql
Scala	scalafmt	scalafix
Shell	shfmt	shellcheck
Starlark	Buildifier	Buildifier
Swift	SwiftFormat (1)
TOML	taplo
TSX	Prettier	ESLint
TypeScript	Prettier	ESLint
YAML	yamlfmt	yamllint
XML	prettier/plugin-xml

1. Non-hermetic: requires that a swift toolchain is installed on the machine. See https://github.com/bazelbuild/rules_swift#1-install-swift

To add a tool, please follow the steps in lint/README.md or format/README.md and then send us a PR. Thanks!!

Installation

Follow instructions from the release you wish to use: https://github.com/aspect-build/rules_lint/releases

Usage

Formatting and Linting are inherently different, which leads to differences in how they are used in rules_lint. It is best conceived as two rulesets in one.

Formatter	Linter
Only one per language, since they could conflict with each other.	Many per language is fine; results compose.
Invariant: program's behavior is never changed.	Suggested fixes may change behavior.
Developer has no choices. Always blindly accept result.	Fix may be manual, or select from multiple auto-fixes.
Changes must be applied.	Violations can be suppressed.
Operates on a single file at a time.	Can require the dependency graph.
Can always format just changed files / regions	New violations might be introduced in unchanged files.
Fast enough to put in a pre-commit workflow.	Some are slow.

Format

To format files, run the target you create when you install rules_lint.

We recommend using a Git pre-commit hook to format changed files, and Aspect Workflows to provide the check on CI.

See Formatting for more ways to use the formatter.

Also see API Documentation

Demo:

Lint

To lint code, we recommend using the Aspect CLI to get the missing lint command, and Aspect Workflows to provide first-class support for "linters as code reviewers".

For example, running bazel lint //src:all prints lint warnings to the terminal for all targets in the //src package. Suggested fixes from the linter tools are presented interactively.

See Linting for more ways to use the linter.

Also see API Documentation

Demo:

Ignoring files

The linters only visit files that are part of the Bazel dependency graph (listed as srcs to some library target).

The formatter honors the .gitignore and .gitattributes files. Otherwise use the affordance provided by the tool, for example .prettierignore for files to be ignored by Prettier.

Sometimes engineers want to ignore a file with a certain extension because the content isn't actually valid syntax for the corresponding language. For example, you might write a template for YAML and name it my-template.yaml even though it needs to have some interpolated values inserted before it's syntactically valid. We recommend instead fixing the file extension. In this example, my.yaml.tmpl or my-template.yaml_ might be better.

Using with your editor

We believe that existing editor plugins should just work as-is. They may download or bundle their own copy of the tools, which can lead to some version skew in lint/format rules.

For formatting, we believe it's a waste of time to configure these in the editor, because developers should just rely on formatting happening when they commit and not care what the code looks like before that point. But we're not trying to stop anyone, either!

You could probably configure the editor to always run the same Bazel command, any time a file is changed. Instructions to do this are out-of-scope for this repo, particularly since they have to be formulated and updated for so many editors.

Telemetry & privacy policy

This ruleset collects limited usage data via tools_telemetry, which is reported to Aspect Build Inc and governed by our privacy policy.