Add "expr" type as a schema type (#164)

Author: wata727

docs/functions.md

@@ -795,6 +795,170 @@ Returns:
 
 - `range` (range): a range for [DIR]/main.tf:1:1
 
+## `hcl.expr_list`
+
+```rego
+exprs := hcl.expr_list(expr)
+```
+
+Extract a list of expressions from the given static list expression.
+This is equivalent to [`hcl.ExprList`](https://github.com/hashicorp/hcl/blob/v2.24.0/expr_list.go#L17).
+
+- `expr` (raw_expr): static list expression which is retrieved as an [`expr` type](./schema.md#expr-type).
+
+Returns:
+
+- `exprs` (array[raw_expr]): expressions as elements of the list.
+
+Types:
+
+|Name|Type|
+|---|---|
+|`raw_expr`|`object<value: string, range: range>`|
+
+Examples:
+
+```hcl
+resource "aws_instance" "main" {
+  lifecycle {
+    ignore_changes = [key_name, tags]
+  }
+}
+```
+
+```rego
+instances := terraform.resources("*", {"lifecycle": {"ignore_changes": "expr"}}, {"expand_mode": "none"})
+hcl.expr_list(instances[i].config.lifecycle[j].config.ignore_changes)
+```
+
+```json
+[
+  {
+    "value": "key_name",
+    "range": {...}
+  },
+  {
+    "value": "tags",
+    "range": {...}
+  }
+]
+```
+
+## `hcl.expr_map`
+
+```rego
+pairs := hcl.expr_map(expr)
+```
+
+Extract a list of key value pairs from the given static map expression.
+This is equivalent to [hcl.ExprMap](https://github.com/hashicorp/hcl/blob/v2.24.0/expr_map.go#L17).
+
+- `expr` (raw_expr): static map expression which is retrieved as an [`expr` type](./schema.md#expr-type).
+
+Returns:
+
+- `pairs` (array[key_value]): key value pairs of the map as expressions.
+
+Types:
+
+|Name|Type|
+|---|---|
+|`key_value`|`object<key: raw_expr, value: raw_expr>`|
+
+Examples:
+
+```hcl
+module "tunnel" {
+  source    = "./tunnel"
+  providers = {
+    aws.src = aws.usw1
+    aws.dst = aws.usw2
+  }
+}
+```
+
+```rego
+calls := terraform.module_calls({"providers": "expr"})
+hcl.expr_map(calls[i].config.providers)
+```
+
+```json
+[
+  {
+    "key": {
+      "value": "aws.src",
+      "range": {...}
+    },
+    "value": {
+      "value": "aws.usw1",
+      "range": {...}
+    }
+  },
+  {
+    "key": {
+      "value": "aws.dst",
+      "range": {...}
+    },
+    "value": {
+      "value": "aws.usw2",
+      "range": {...}
+    }
+  }
+]
+```
+
+## `hcl.expr_call`
+
+```rego
+call := hcl.expr_call(expr)
+```
+
+Extract the function name and arguments from the given function call expression.
+This is equivalent to [hcl.ExprCall](https://github.com/hashicorp/hcl/blob/v2.24.0/expr_call.go#L17).
+
+- `expr` (raw_expr): function call expression which is retrieved as an [`expr` type](./schema.md#expr-type).
+
+Returns:
+
+- `call` (call): function call object.
+
+Types:
+
+|Name|Type|
+|---|---|
+|`call`|`object<name: string, name_range: range, arguments: array[raw_expr], args_range: range>`|
+
+Examples:
+
+```hcl
+resource "aws_instance" "main" {
+  ami = provider::custom::get_ami_id("web", "v0.9")
+}
+```
+
+```rego
+instances := terraform.resources("aws_instance", {"ami": "expr"})
+hcl.expr_call(instances[i].config.ami)
+```
+
+```json
+{
+  "name": "provider::custom::get_ami_id",
+  "name_range": {...},
+  "arguments": [
+    {
+      "value": "\"web\"",
+      "range": {...}
+    },
+    {
+      "value": "\"v0.9\"",
+      "range": {...}
+    }
+  ],
+  "args_range": {...}
+}
+```
+
 ## `tflint.issue`
 
 ```rego

docs/schema.md

@@ -10,25 +10,33 @@ For example, a schema required to decode the top-level `instance_type` is:
 {"instance_type": "string"}
 ```
 
-The object's key is the attribute name and the value represents the type. The type syntax is the same as [Terraform's type constraints](https://developer.hashicorp.com/terraform/language/expressions/type-constraints).
+The object's key is the attribute name and the value represents the type. The type syntax is essentially the same as [Terraform's type constraints](https://developer.hashicorp.com/terraform/language/expressions/type-constraints).
+
+## `any` Type
 
 TFLint implicitly converts values according to their type, which is useful when working with numbers.
 
+```rego
+{"size": "number"}
+```
+
 ```hcl
-resource "aws_instance" "number" {
-  ebs_block_device {
-    volume_size = 50
-  }
+resource "aws_ebs_volume" "number" {
+  size = 50
 }
 
-resource "aws_instance" "string" {
-  ebs_block_device {
-    volume_size = "50" # => convert to number in JSON
-  }
+resource "aws_ebs_volume" "string" {
+  size = "50" # => convert to number in JSON
 }
 ```
 
-If you don't know the attribute type, you can use `any`. In this case no conversion is done, but the raw value from the config file is available.
+If you don't know the attribute type, you can use `any`. In this case no conversion is done, but the raw value from the config file is available. In the above example, the JSON will contain 50 and "50".
+
+```rego
+{"size": "any"}
+```
+
+## Nested Blocks
 
 A schema for decoding nested blocks is:
 
@@ -53,3 +61,46 @@ resource "aws_instance" "main" {
 ```
 
 The `__labels` is a special key that sets labels. The value defines the label name in an array, not the type. Label names are basically meaningless.
+
+## `expr` Type
+
+The `expr` type can be used as a special type. Attributes specified as `expr` type are not evaluated immediately, but the structure of the expression is included in the value.
+
+```hcl
+variable "instance_type" {
+  default = "t2.micro"
+}
+
+resource "aws_instance" "main" {
+  instance_type = var.instance_type
+}
+```
+
+```rego
+{"instance_type": "string"}
+```
+
+```json
+{
+  "value": "t2.micro",
+  "unknown": false,
+  "sensitive": false,
+  "ephemeral": false,
+  "range": {...}
+}
+```
+
+```rego
+{"instance_type": "expr"}
+```
+
+```json
+{
+  "value": "var.instance_type",
+  "range": {...}
+}
+```
+
+This is useful for writing policies over expression structures. For example, the `expr` type is the only way to handle meta-arguments such as `ignore_changes` that cannot be evaluated in the normal way.
+
+The value obtained with the `expr` type is called `raw_expr` type and can be passed to HCL static analysis functions such as [`hcl.expr_list`](./functions.md#hclexpr_list), [`hcl.expr_map`](./functions.md#hclexpr_map), and [`hcl.expr_call`](./functions.md#hclexpr_call).

examples/enforce_tags_ignore/.tflint.d/policies/tags.rego

@@ -0,0 +1,41 @@
+package tflint
+
+import rego.v1
+
+aws_instances := terraform.resources("aws_instance", {"lifecycle": {"ignore_changes": "expr"}}, {"expand_mode": "none"})
+
+# ignore_changes = [tags]
+has_tags_ignore(instance) if {
+	ignore_changes := instance.config.lifecycle[_].config.ignore_changes
+
+    startswith(ignore_changes.value, "[")
+	some i
+	hcl.expr_list(ignore_changes)[i].value == "tags"
+}
+
+# ignore_changes = ["tags"]
+has_tags_ignore(instance) if {
+	ignore_changes := instance.config.lifecycle[_].config.ignore_changes
+
+    startswith(ignore_changes.value, "[")
+	some i
+	hcl.expr_list(ignore_changes)[i].value == `"tags"`
+}
+
+# ignore_changes = all
+has_tags_ignore(instance) if {
+	ignore_changes := instance.config.lifecycle[_].config.ignore_changes
+    ignore_changes.value == "all"
+}
+
+# ignore_changes = "all"
+has_tags_ignore(instance) if {
+	ignore_changes := instance.config.lifecycle[_].config.ignore_changes
+    ignore_changes.value == `"all"`
+}
+
+deny_instance_without_tags_ignore contains issue if {
+	not has_tags_ignore(aws_instances[i])
+
+	issue := tflint.issue(`instance must have "ignore_changes = [tags]"`, aws_instances[i].decl_range)
+}