Show in the documentation when a rule is autofixable

[jfmengels]

I see that a few static analysis tools indicate that a rule is fixable or not.

I don't think a rule should always provide fixes, but when it does, I think it's nice to highlight it, as that would make the user quite happy.

Some Prior art

ESLint

On the rule listing:

On the rule page:

The --fix option on the command line can automatically fix some of the problems reported by this rule.

(again with the wrench symbol)

The docs do not indicate what the fix will do or in which situations it will (not) be enabled.

Textlint

(I had never heard of textlint before today by the way, but it's probably worth looking into).

Rules seem to indicate that they are fixable, and there is a check mark next to the rule name in the rule list

HLint

HLint's rule list indicate when they are NOT fixable. It looks like there is a lot of work on making most rules fixable, so that makes sense. Even the unfixable rules indicate a "suggestion" of what the code should look like instead of what was detected. I guess it's more of a "we can't autofix" situation here.

Rome frontend

Rome generates documentation and includes a real report by running the rules on example files (this is pretty cool by the way, though it's worth noting that there are no custom rules, which simplifies the task).

The generated report shows the suggested fix by default.

Exploration

I'd like to explore nice ways to show that a fix is available, and if possible to enforce this convention.

I think we could detect whether there the rule proposes a fix by checking whether the file imports Review.Fix. If it does, then we can enforce/autofix adding that information in the README and in the rule's documentation.

The question is then, should

I imagine that for some rules it's easiest and best to show the fixed results in the examples directly. Something like

List.map (\v -> v.foo)
-- would be fixed to
List.map .foo

For others, fixes might be a more difficult, and therefore a simple mention somewhere that the rule provides automatic fixes is enough. On my end, I think I'll try to add such examples on my repos and see what comes out of that.