elm-review/docs.json

[{"name":"Review.Fix","comment":" Tools to write automatic error fixes.\n\nWhen creating a [`Review.Rule.Error`](./Review-Rule#Error), you can provide an automatic\nfix for the error using [`Review.Rule.errorWithFix`](./Review-Rule#errorWithFix)\nor other functions that end with \"withFix\" so that the user doesn't need to fix\nthe problem themselves.\n\nIn the [CLI], the user can ask to fix the errors automatically, and in doing so,\nthey will be presented by a fix which they can accept or refuse. If the fix gets\nrefused, then the next fixable error will be presented. Otherwise, if the fix\ngets accepted, the file will be applied and the fixed file content get analyzed\nagain by the different rules in the user's configuration, and then another fix\nwill be presented. When there are no more fixable errors, the remaining errors\nwill be reported, just like when the user doesn't request errors to be automatically\nfixed.\n\nIn summary, errors will be presented one by one and the user will validate them.\nThe [CLI] also proposes an option to fix all the errors, which applies each fix\none by one and then asks the user to confirm the cumulated fix.\n\n\n# Guidelines\n\nAn automatic fix, when applied, should resolve the reported error completely.\nThis means that when the automatic fix is applied, the user should not have to\nthink about the error anymore or have to do additional work.\n\nImagine if the user applies a lot of automatic fixes all at once. We don't want them to have to\nremember having to do something, otherwise we may have just offloaded a lot of\nwork that they may forget to do. In that case, it is better not to provide a fix\nat all, so that they keep a reminder and the details of how to fix the problem.\n\nAn automatic fix should resolve only the reported error, not try to fix other\npotential errors. By only fixing one error at a time, the fix will be easier for\nthe user to digest and understand. The file will be re-reviewed when the fix is\napplied, and then another error can fix that one.\n\n\n# When (not) to provide an automatic fix?\n\nFor users, having an automatic fix always feels like a nice-to-have and they may\nrequest you to provide some, but they are not mandatory, and in some cases, it\nis better not to have any.\n\n\n## Reasons not to provide an automatic fix\n\n\n### A complete automatic fix is not possible\n\nSometimes, just by going through the whole file, you are missing some of the\ninformation needed to generate the right fix. Instead of providing a partial or\npotentially incorrect fix, it would be better to provide more details, hints or\nsuggestions.\n\n\n### The fix would result in a compiler error\n\nAn automatic fix should not cause changes that would break the file or the\nproject. In some cases, we can detect that the [fix will break things](#Problem),\nlike if the result of the fix is invalid Elm code (as in resulting in a parsing\nerror), but ultimately we can't detect that the project will still compile after\nthe fix is applied.\n\nUsers are notified that an automatic fix is available. For performance reasons,\nwe only check that a fix is valid before presenting it to the user and ignore it\nif it turns out to be invalid. This means that the user will be disappointed or\nconfused when the error ends up not being enforced. The only way we have to\nprevent this is to write tests, as fixes are applied in tests.\n\n\n### The user should learn about problem and how to solve it\n\nSometimes problems are learning opportunities, and it is worth having the user\nspend some time reading through the details of the error and trying several\nalternatives in order to understand the problem and the tradeoffs of the\nsolutions. You can guide them by using great error details!\n\n\n## Reasons to provide an automatic fix\n\nThe reasons to provide an automatic fix are basically the opposite of the\nreasons not to provide an automatic fix:\n\n  - We know how to fix the problem completely and accurately\n  - The task is menial and the user will not learn anything by fixing the error\n    themse