rules_lint
v1.0.3
published 1 month ago
89 stars
47 forks
4 watchers
aspect-build/rules_lint
Apache License 2.0
public
1 assets
646,498 downloads
333 KB
Bazel central registry
Compatability level 1
mYU1y1+PvVluFx+ozytM1vp9ZCI/pU14QK8iGjbLENY=
Maintained byAlex Eagle
Run static analysis tools with Bazel
v1.0.3
October 25, 2024

Using Bzlmod with Bazel 6

  1. Enable with common --enable_bzlmod in .bazelrc.
  2. Add to your MODULE.bazel file:
bazel_dep(name = "aspect_rules_lint", version = "1.0.3")

# Next, follow the install instructions for
# - linting: https://github.com/aspect-build/rules_lint/blob/v1.0.3/docs/linting.md
# - formatting: https://github.com/aspect-build/rules_lint/blob/v1.0.3/docs/formatting.md

Using WORKSPACE

Paste this snippet into your file:

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
    name = "aspect_rules_lint",
    sha256 = "998535cb5f8fbd596e171fa8cf2b4cd6fa7d64223fa54d7840af221a36cb10d6",
    strip_prefix = "rules_lint-1.0.3",
    url = "https://github.com/aspect-build/rules_lint/releases/download/v1.0.3/rules_lint-v1.0.3.tar.gz",
)

# aspect_rules_lint depends on aspect_bazel_lib.
http_archive(
    name = "aspect_bazel_lib",
    sha256 = "6d758a8f646ecee7a3e294fbe4386daafbe0e5966723009c290d493f227c390b",
    strip_prefix = "bazel-lib-2.7.7",
    url = "https://github.com/aspect-build/bazel-lib/releases/download/v2.7.7/bazel-lib-v2.7.7.tar.gz",
)

load("@aspect_bazel_lib//lib:repositories.bzl", "aspect_bazel_lib_dependencies")

# aspect_bazel_lib depends on bazel_skylib
aspect_bazel_lib_dependencies()

load(
    "@aspect_rules_lint//format:repositories.bzl",
    # Fetch additional formatter binaries you need:
    "fetch_java_format",
    "fetch_ktfmt",
    "fetch_swiftformat",
    "rules_lint_dependencies",
)

rules_lint_dependencies()

fetch_java_format()

fetch_ktfmt()

fetch_swiftformat()

load("@aspect_rules_lint//lint:checkstyle.bzl", "fetch_checkstyle")

fetch_checkstyle()

load("@aspect_rules_lint//lint:pmd.bzl", "fetch_pmd")

fetch_pmd()

load("@aspect_rules_lint//lint:vale.bzl", "fetch_vale")

fetch_vale()

load("@aspect_rules_lint//lint:ktlint.bzl", "fetch_ktlint")

fetch_ktlint()

########################
# Optional: multitool provides defaults for some tools such as yamlfmt
# If you do not set up multitool, you must provide these tools yourself
load("@rules_multitool//multitool:multitool.bzl", "multitool")

multitool(
    name = "multitool",
    lockfiles = [
        "@aspect_rules_lint//format:multitool.lock.json",
        "@aspect_rules_lint//lint:multitool.lock.json",
    ],
)

What's Changed

Full Changelog: https://github.com/aspect-build/rules_lint/compare/v1.0.2...v1.0.3

Deps:
Assets:

Run linters and formatters under Bazel

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)

Supported tools

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

Language Formatter Linter(s)
C / C++ clang-format clang-tidy
Cuda clang-format
CSS, Less, Sass Prettier Stylelint
Go gofmt or gofumpt
GraphQL Prettier
HCL (Hashicorp Config) terraform fmt
HTML Prettier
JSON Prettier
Java google-java-format pmd , Checkstyle
JavaScript Prettier ESLint
Jsonnet jsonnetfmt
Kotlin ktfmt ktlint
Markdown Prettier Vale
Protocol Buffer buf buf lint
Python ruff flake8, ruff
Rust rustfmt
SQL prettier-plugin-sql
Scala scalafmt
Shell shfmt shellcheck
Starlark Buildifier
Swift SwiftFormat (1)
TSX Prettier ESLint
TypeScript Prettier ESLint
YAML yamlfmt
  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.

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.

Demo: pre-commit format

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.

Demo: bazel lint 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.

FAQ

What about type-checking?

We consider type-checkers as a build tool, not as a linter. This is for a few reasons:

  • They are commonly distributed along with compilers. In compiled languages like Java, types are required in order for the compiler to emit executable bytecode at all. In interpreted languages they're still often linked, e.g. TypeScript does both "compiling" to JavaScript and also type-checking. This suggests that rules for a language should include the type-checker, e.g. we expect Sorbet to be integrated with rules_ruby and mypy/pyright to be integrated with rules_python or Aspect's rules_py.
  • We think most developers want "build error" semantics for type-checks: the whole repository should successfully type-check or you cannot commit the change. rules_lint is optimized for "warning" semantics, where we produce report files and it's up to the Dev Infra team how to present those, for example only on changed files.
  • You can only type-check a library if its dependencies were checkable, which means short-circuiting execution. rules_lint currently runs linters on every node in the dependency graph, including any whose dependencies have lint warnings.