From 2a85f0483fb6d17e4c54bde60bbd7f03028b6161 Mon Sep 17 00:00:00 2001 From: Alisdair McDiarmid Date: Fri, 12 Mar 2021 14:25:11 -0500 Subject: [PATCH] website: Update validate -json diags documentation Updated to include details about the new "snippet" object in JSON diagnostics. --- website/docs/cli/commands/validate.html.md | 51 +++++++++++++++++++++- 1 file changed, 50 insertions(+), 1 deletion(-) diff --git a/website/docs/cli/commands/validate.html.md b/website/docs/cli/commands/validate.html.md index 62bcb7e9f..687e83789 100644 --- a/website/docs/cli/commands/validate.html.md +++ b/website/docs/cli/commands/validate.html.md @@ -123,7 +123,7 @@ The nested objects in `diagnostics` have the following properties: additional rules for processing other text conventions, but will do so within the bounds of the rules above to achieve backward-compatibility. -* `range` (object): An optional object describing a portion of the configuration +* `range` (object): An optional object referencing a portion of the configuration source code that the diagnostic message relates to. For errors, this will typically indicate the bounds of the specific block header, attribute, or expression which was detected as invalid. @@ -137,6 +137,41 @@ The nested objects in `diagnostics` have the following properties: configuration, so `range` will be omitted or `null` for diagnostic messages where it isn't relevant. +* `snippet` (object): An optional object including an excerpt of the + configuration source code that the diagnostic message relates to. + + The snippet information includes: + + * `context` (string): An optional summary of the root context of the + diagnostic. For example, this might be the resource block containing the + expression which triggered the diagnostic. For some diagnostics this + information is not available, and then this property will be `null`. + + * `code` (string): A snippet of Terraform configuration including the + source of the diagnostic. This can be multiple lines and may include + additional configuration source code around the expression which + triggered the diagnostic. + + * `start_line` (number): A one-based line count representing the position + in the source file at which the `code` excerpt begins. This is not + necessarily the same value as `range.start.line`, as it is possible for + `code` to include one or more lines of context before the source of the + diagnostic. + + * `highlight_start_offset` (number): A zero-based character offset into the + `code` string, pointing at the start of the expression which triggered + the diagnostic. + + * `highlight_end_offset` (number): A zero-based character offset into the + `code` string, pointing at the end of the expression which triggered the + diagnostic. + + * `values` (array of objects): Contains zero or more expression values + which may be useful in understanding the source of a diagnostic in a + complex expression. These expression value objects are described below. + +### Source Position + A source position object, as used in the `range` property of a diagnostic object, has the following properties: @@ -153,3 +188,17 @@ exact positions used for particular error messages are intended for human interpretation only and subject to change in future versions of Terraform due either to improvements to the error reporting or changes in implementation details of the language parser/evaluator. + +### Expression Value + +An expression value object gives additional information about a value which is +part of the expression which triggered the diagnostic. This is especially +useful when using `for_each` or similar constructs, in order to identify +exactly which values are responsible for an error. The object has two properties: + +* `traversal` (string): An HCL traversal string, such as `var.instance_count`. + +* `statement` (string): A short English-language fragment describing the value + of the expression when the diagnostic was triggered. The contents of this + string are intended to be human-readable and are subject to change in future + versions of Terraform.