Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/aspect-build/bazel-super-formatter
Hermetic meta-formatter to format code in most languages
https://github.com/aspect-build/bazel-super-formatter
Last synced: 11 days ago
JSON representation
Hermetic meta-formatter to format code in most languages
- Host: GitHub
- URL: https://github.com/aspect-build/bazel-super-formatter
- Owner: aspect-build
- License: apache-2.0
- Archived: true
- Created: 2022-08-25T18:59:48.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-02-20T11:53:08.000Z (9 months ago)
- Last Synced: 2024-05-29T01:40:34.527Z (5 months ago)
- Language: Starlark
- Homepage:
- Size: 118 KB
- Stars: 53
- Watchers: 7
- Forks: 10
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-bazel - bazel-super-formatter - Hermetic aggregation formatter to format code in most languages (Tooling / General)
README
# 📣 DEPRECATED
https://github.com/aspect-build/rules_lint has replaced this repo.
It has a more scalable and maintainable approach for aggregating the formatter tools.
We're sorry for the churn! Chat with us in `#aspect-dev` on https://slack.bazel.build if you're stuck migrating.
# A tool for formatting source code
Easily ensure your code is always formatted, with consistent tooling across everyone's machines.
bazel-super-formatter is an aggregator tool that runs many formatters, in the spirit of .
Features:
- Don't need to add Bazel targets to include the source files, or even adopt Bazel at all.
- Managed, fully hermetic tools and runtimes (except as noted below).
- Honors formatter configuration files.
Supported languages:
| Supported | Language | Tool |
| --------- | ------------------------- | -------------------------------------------------------------- |
| ✓ | Python | [Black](https://pypi.org/project/black/) |
| ✓ | Java | [google-java-format] |
| ✓ | Kotlin | [ktfmt](https://github.com/facebook/ktfmt) |
| ✓ | JavaScript/TypeScript/TSX | [Prettier] |
| ✓ | CSS/HTML | [Prettier] |
| ✓ | JSON | [Prettier] |
| ✓ | Markdown | [Prettier] |
| ✓ | Bash | [prettier-plugin-sh](https://github.com/un-ts/prettier) |
| ✓ | SQL | [prettier-plugin-sql](https://github.com/un-ts/prettier) |
| ✓ | Starlark (Bazel) | [Buildifier](https://github.com/keith/buildifier-prebuilt) |
| ✓ | Swift | [SwiftFormat](https://github.com/nicklockwood/SwiftFormat) (1) |
| ✓ | Go | [gofmt](https://pkg.go.dev/cmd/gofmt) |
| ✓ | Protobuf | [buf](https://docs.buf.build/format/usage) |
| ✓ | Terraform | [terraform](https://github.com/hashicorp/terraform) fmt |
| ✓ | Jsonnet | [jsonnetfmt](https://github.com/google/go-jsonnet) |
| ✓ | Scala | [scalafmt](https://scalameta.org/scalafmt) |
| | C/C++/C# | clang-format |
| | Rust | [rustfmt](https://github.com/rust-lang/rustfmt) |
| | YAML | [yamlfmt](https://github.com/google/yamlfmt) |
More languages TODO: https://github.com/aspect-build/bazel-super-formatter/issues/6
[prettier]: https://prettier.io
[google-java-format]: https://github.com/google/google-java-format
1. Non-hermetic: requires that a swift toolchain is installed on the machine.
See https://github.com/bazelbuild/rules_swift#1-install-swift
## Installation
Install Bazel:
From the release you wish to use:
copy the WORKSPACE snippet into your `WORKSPACE` file.
## Usage
### One-time re-format all files
`bazel run @aspect_rules_format//format`
> Note that mass-reformatting can be disruptive in an active repo.
> You may want to instruct developers with in-flight changes to reformat their branches as well, to avoid merge conflicts.
> Also consider adding your re-format commit to the [`.git-blame-ignore-revs` file](https://docs.github.com/en/repositories/working-with-files/using-files/viewing-a-file#ignore-commits-in-the-blame-view) to avoid polluting the blame layer.
### Re-format specific file(s)
`bazel run @aspect_rules_format//format some/file.md other/file.json`
### Install as a pre-commit hook
If you use [pre-commit.com](https://pre-commit.com/), add this in your `.pre-commit-config.yaml`:
```yaml
- repo: local
hooks:
- id: bazel-super-formatter
name: Format
language: system
entry: bazel run @aspect_rules_format//format
files: .*
```
> Note that pre-commit is silent while Bazel is fetching the tooling, which can make it appear hung on the first run.
> There is no way to avoid this; see https://github.com/pre-commit/pre-commit/issues/1003
If you don't use pre-commit, you can just wire directly into the git hook, however
this option will always run the formatter over all files, not just changed files.
```bash
$ echo "bazel run @aspect_rules_format//format" >> .git/hooks/pre-commit
$ chmod u+x .git/hooks/pre-commit
```
### Check that files are already formatted
This will exit non-zero if formatting is needed. You would typically run the check mode on CI.
`bazel run @aspect_rules_format//format -- --mode check`
## Configuration
### Enable the formatters for your languages
When you enable a language, it causes the super-formatter to fetch additional tooling as a
runtime dependency of the format binary.
Add some of these lines to `.bazelrc`:
```
# Enable fetching formatter toolchains
run --@aspect_rules_format//format:go_enabled
run --@aspect_rules_format//format:java_enabled
run --@aspect_rules_format//format:jsonnet_enabled
run --@aspect_rules_format//format:kotlin_enabled
run --@aspect_rules_format//format:proto_enabled
run --@aspect_rules_format//format:python_enabled
run --@aspect_rules_format//format:scala_enabled
run --@aspect_rules_format//format:swift_enabled
run --@aspect_rules_format//format:terraform_enabled
```
### Changing the version of a formatter tool
Look in our `format/repositories.bzl` file and copy the `http_*` rule you want to modify into your WORKSPACE, above the `rules_format_dependencies()` call.
### Replacing a tool, to add plugins
You can specify your own local binary, for example you might use `black` for Python with a custom `requirements.txt` file that adds plugins such as `typing_extensions`.
You can do this in `WORKSPACE` before installing aspect_rules_format:
```starlark
pip_parse(
name = "aspect_rules_format_pypi",
requirements_lock = "//tools/black:requirements.txt",
)
load("@aspect_rules_format_pypi//:requirements.bzl", _aspect_rules_format_pypi_install_deps = "install_deps")
_aspect_rules_format_pypi_install_deps()
```
See https://github.com/aspect-build/bazel-super-formatter/issues/13
### Ignoring files
We honor the `.gitignore` file. Otherwise use the affordance provided by the formatter 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 from an editor
Some engineers are used to setting up a formatter tool in their editor/IDE. Typically there is an editor extension, for example Prettier documents a number of them on .
The authors of bazel-super-formatter believe that it's a waste of time for developers to setup their workflow this way.
It's redundant. Since not all engineers will configure their editor, you need to have a pre-commit CI check anyway.
At best, the users are instructed how to carefully reproduce the versions of the tools and their configuration files, so that the format operation
they perform matches what will happen automatically as they send their change off for review.
Not everyone will agree, and it may not be beneficial to convince developers to change their behavior.
Since this tool uses the same configuration files as the tool expects, you can always setup the editor extensions for all the underlying formatters yourself.
Or you could probably configure the editor to always run one of the commands above in the Usage section, any time a file is changed.
The instructions to do this are out-of-scope for this repo, particularly since they have to be formulated and updated for so many editors.
### Using a formatter from a BUILD rule
Generally, you should just allow code generators to make messy files.
You can exclude them from formatting by changing the file extension, adding a suppression comment at the top (following the formatter's docs) or adding to the formatter's ignore file (e.g. `.prettierignore`).
However there are some valid cases where you really want to run a formatter as a build step. You can just reach into the external repository where we've installed them. For example, to run Prettier:
```starlark
load("@aspect_rules_format_npm//:prettier/package_json.bzl", prettier = "bin")
prettier.prettier_binary(name = "prettier")
js_run_binary(
name = "fmt",
srcs = ["raw_file.md"],
args = ["raw_file.md"],
chdir = package_name(),
stdout = "formatted_file.md",
tool = "prettier",
)
```
## Design
See https://hackmd.io/0UgIb6gyTvSVX9N2vTPGug
### What about linting?
This project just covers the "formatting" use case. Linting is a totally different developer experience as explained in the design doc above:
| 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. |
See for running linters.