Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history 
List supported tools earlier
  • Loading branch information
@alexeagle
alexeagle authored Jan 20, 2024
1 parent e56c0d8 commit 53362f5
Showing 1 changed file with 32 additions and 59 deletions.
91 changes: 32 additions & 59 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,38 +23,7 @@ It is also inspired by <https://github.com/github/super-linter>.
[tricorder]: https://static.googleusercontent.com/media/research.google.com/en//pubs/archive/43322.pdf
[reviewdog]: https://github.com/reviewdog/reviewdog

## Design

Formatting and Linting work a bit differently.

| 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. |

This leads to some minor differences in how they are used in rules_lint.

We treat 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.
- We think most developers want "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.

## Available tools
## Supported tools

| Language | Formatter | Linter(s) |
| ------------------------- | --------------------- | ---------------- |
Expand Down Expand Up @@ -105,6 +74,37 @@ Thanks!!

> We'll add documentation on adding formatters as well.
## Design

Formatting and Linting work a bit differently.

| 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. |

This leads to some minor differences in how they are used in rules_lint.

We treat 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.
- We think most developers want "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.

## Installation

Follow instructions from the release you wish to use:
Expand Down Expand Up @@ -154,30 +154,3 @@ 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.

### 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",
)
```

0 comments on commit 53362f5

Please sign in to comment.