Document machine/rules.json

[oaahmad]

Please document this generated file: https://github.com/dart-lang/sdk/blob/main/pkg/linter/tool/machine/rules.json

Preferably in one (or both) of these pages:

• https://dart.dev/tools/linter-rules
• https://dart.dev/tools/analysis

I'm thinking just something like "you can view all the rules as JSON here" where "here" is a link to the raw file (so people can curl the linked page and get a JSON file). No need for documentation beyond that (people will either have a need for that file or not).

I've been wanting a file like this to work with, but I didn't know it existed.

My use case: as part of a side project I'm working on, I'm trying to create a command-line tool that generates an analysis_options.yaml file that has include package:flutter_lints/flutter.yaml and also adds a rule under rules for every existing rule that meets the following criteria:

• Not already included in flutter_lints
• Does not conflict with any rule in flutter_lints
• Has not been removed (in newer versions of Dart)
• Has been released in a stable version of Dart
• Is not experimental

The goal is to make it easy for me to create a new Dart/Flutter project with a strict set of lints that is a superset of flutter_lints. I can then go through the lints listed in the generated file and remove the few that I don't want or conflict. This would be easier than going through the entire list of lints that Dart supports.

Here is another use case I found that might benefit from machine/rules.json: VeryGoodOpenSource/very_good_analysis#100

Now that I know the file exists, this issue is:

• To benefit anyone else that could use this file (so they don't waste time like me)
• In case I forget this file exists or where to find it because I haven't thought about it for a long time

[lrhn]

If we intend the file to be public, I'll recommend adding a version number to the format, so that we can change the format in the future, and tools depending on the file can tell that they're not compatible with the new format.

If the file is not intended to be public, consider adding a notice, maybe:

{
  "_NOTICE:_": "This file is for internal use by the SDK. Format may change without notice.",
  "lints": ... current content ...
}

(Oh why does JSON not have comments!)

[pq]

/fyi @parlough

[srawlins]

I don't think we intend for it to be public, or to have to consider versioning or consider any change to it a "breaking" change.

[pq]

@parlough: do we have a copy of rules.json somewhere on dart.dev or am I mis-remembering?

I don't think we intend for it to be public

Originally it was. The impetus was a tool @csells built. I expect it's no longer being maintained but it's possible there are others. Parker may know more...

[srawlins]

Oh very cool! In that case I like the versioning suggestion.

[csells]

I believe this rules.json file is being used by @gaetschwartz to produce the all_lint_rules_community package. Does the Dart team produce an alternative? I absolutely love having all of the lint rules turned on by default, with some that I turn off. I catch so many problems in my code doing that.

[parlough]

@parlough: do we have a copy of rules.json somewhere on dart.dev or am I mis-remembering?

Not directly hosted on the site, but it's mirrored at https://github.com/dart-lang/site-www/blob/main/src/_data/linter_rules.json and used to generate the the linter rule docs that are indexed at https://dart.dev/tools/linter-rules#rules.

I don't think we intend for it to be public

Originally it was. The impetus was a tool csells built. I expect it's no longer being maintained but it's possible there are others. Parker may know more...

Currently the machine/rules.json file has no versioning strategy and its current form will likely be retired soon as we introduce new documentation for choosing lints (dart-lang/site-www#4499, dart-lang/site-www#4498). So keeping that in mind, I'd say it's best to consider the current file as not public.

The final form of its replacement hasn't been decided yet, but I'll update here when it is ready and will keep in mind the use cases outlined here as well as any potential versioning concerns.

[pq]

Thanks @parlough!

[csells]

@pq @srawlins @parlough does the team have a place that lists all of the lint rules? I love turning them all on (and then turning off the annoying and conflicting ones) -- it feels like a whole new compiler when I do!

[srawlins]

@csells I would use https://github.com/dart-lang/linter/blob/main/example/all.yaml

[csells]

Cool, @srawlins. Thanks. Is that kept up to date with every new lint as they're created?

[pq]

Slight correction. I'd actually use:

https://github.com/dart-lang/sdk/blob/main/pkg/linter/example/all.yaml

(The linter repo is stale.)

It should be kept up to date. (There used to be tests but I'll double-check.)

PS: Hi Chris!

[csells]

hey Phil (@pq)! long time! we should grab some lunch sometime soon!

[parlough]

I'll also add that https://dart.dev/lints/all has a list of all lints available on stable in the analysis_options.yaml format and https://dart.dev/lints has a list of all lints with their details :)

[csells]

thanks, @parlough. the online lint docs are super useful for sure. what I'm looking for is a stable place to pull all of the dart lint rules in an automated way into a tool. I think this is actually what I'm looking for. thanks, all!