Introduce autofix API

[wata727]

See also terraform-linters/tflint#266

This PR adds a new Runner API for autofix. The newly added EmitIssueWithFix API allows plugins to not only emit issues but also automatically apply fixes for the issues.

Below is an example of autofixing the instance type "t2.micro" to "t3.micro".

runner.EmitIssueWithFix(
	rule,
	"Use t3 family instead of t2 family",
	expr.Range(),
	func (f tflint.Fixer) error {
		return f.ReplaceText(expr.Range(), `"t3.micro"`)
	}
)

Unlike EmitIssue API, this function allows you to pass a function callback for autofix in the 4th argument. Plugin developers can use the tflint.Fixer in the function callback to change their source code.

The following APIs are available in tflint.Fixer:

• ReplaceText(hcl.Range, ...(string|tflint.TextNode))
• InsertTextBefore(hcl.Range, string)
• InsertTextAfter(hcl.Range, string)
• Remove(hcl.Range)
• RemoveAttribute(*hcl.Attribute)
• RemoveBlock(*hcl.Block)
• RemoveExtBlock(*hclext.Block)

They are inspired by ESLint's autofix APIs. See the GoDoc for these details.

Also, it doesn't change the source code directly, but there are some APIs available to help with that:

• TextAt(hcl.Range) tflint.TextNode
• ValueText(cty.Value) string
• RangeTo(to string, filename string, start hcl.Pos) hcl.Range

Please refer to terraform-linters/tflint#266 for how to use the autofix implemented by plugins from TFLint.

---

Next, describe the internal design. The sequence diagram for communication between the host and plugins is shown below:

sequenceDiagram
  participant RuleSet as RuleSet (plugin)
  participant Rule as Rule (plugin)
  participant TFLint as TFLint (host)
  RuleSet->>Rule: Start rule.Check()
  Rule->>TFLint: EmitIssue()
  TFLint->>Rule: applied?
  Rule->>Rule: fixer.ReplaceText()
  Rule->>RuleSet: End rule.Check()
  RuleSet->>TFLint: ApplyChanges()

Loading

This PR adds the ApplyChanges API and changes the EmitIssue API to return whether the issue has been applied (e.g. it may be ignored by tflint-ignore annotations).

After emitting an issue with EmitIssue API, if it is not ignored by an annotation, invoke the given fix function. tflint.Fixer has all the source code internally and the fix function rewrites that as a byte sequence.

After the rule inspection is finished, the rewritten source code is applied to the host server by the ApplyChanges API. From now on, the body obtained by APIs such as GetModuleContent will be the fixed source code.

There are two implementation considerations worth mentioning here. One is not to use hclwrite to rewrite the source code. The hclwrite provides APIs for rewriting HCL, but since it handles AST with a different abstraction level than hclsyntax, it is not possible to rewrite the corresponding expression from hcl.Expression. In order to realize easy rewriting using hcl.Expression or hcl.Range, I thought that it was necessary to implement the rewriting operation as a byte string instead of hclwrite. This implementation is in internal.Fixer.

The other is byte shift by rewriting. The source code is rewritten using the byte index pointed to by Byte field in hcl.Pos. However, if multiple rewrite operations occur, the original hcl.Pos may have a byte index that does not reflect the result of the previous rewrite operation. To solve this problem, the internal.Fixer tracks byte index shifts that occur during rewriting. The shift is reflected in the byte indices of subsequent operations, allowing the original range to be rewritten appropriately.

The discussion on which these designs were based can be found in terraform-linters/tflint#266 (comment).