hclsyntax: Special error messages for EOF in certain contexts

For parts of the input that are delimited by start and end tokens, our
typical pattern is to keep scanning for items until we reach the end token,
or to generate an error if we encounter a token that isn't valid.

In some common examples of that we'll now treat TokenEOF as special and
report a different message about the element being unclosed, because it
seems common in practice for folks to leave off closing delimiters and
then be confused about HCL reporting a parse error at the end of the
file. Instead, we'll now report the error from the perspective of the
opening token(s) and describe that construct as "unclosed", because the
EOF range is generally less useful than any range that actually contains
some relevant characters.

This is not totally comprehensive for all cases, but covers some
situations that I've seen folks ask about, and some others that were
similar enough to those that it was easy to modify them in the same ways.

This does actually change one of the error ranges constrained by the
specification test suite, but in practice we're not actually using that
test suite to represent the "specification" for HCL, so it's better to
change the hypothetical specification to call for a better error reporting
behavior than to retain the old behavior just because we happened to
encoded in the (unfinished) test suite.

Author: apparentlymart

hclsyntax/parser.go

@@ -76,14 +76,37 @@ Token:
 		default:
 			bad := p.Read()
 			if !p.recovery {
-				if bad.Type == TokenOQuote {
+				switch bad.Type {
+				case TokenOQuote:
 					diags = append(diags, &hcl.Diagnostic{
 						Severity: hcl.DiagError,
 						Summary:  "Invalid argument name",
 						Detail:   "Argument names must not be quoted.",
 						Subject:  &bad.Range,
 					})
-				} else {
+				case TokenEOF:
+					switch end {
+					case TokenCBrace:
+						// If we're looking for a closing brace then we're parsing a block
+						diags = append(diags, &hcl.Diagnostic{
+							Severity: hcl.DiagError,
+							Summary:  "Unclosed configuration block",
+							Detail:   "There is no closing brace for this block before the end of the file. This may be caused by incorrect brace nesting elsewhere in this file.",
+							Subject:  &startRange,
+						})
+					default:
+						// The only other "end" should itself be TokenEOF (for
+						// the top-level body) and so we shouldn't get here,
+						// but we'll return a generic error message anyway to
+						// be resilient.
+						diags = append(diags, &hcl.Diagnostic{
+							Severity: hcl.DiagError,
+							Summary:  "Unclosed configuration body",
+							Detail:   "Found end of file before the end of this configuration body.",
+							Subject:  &startRange,
+						})
+					}
+				default:
 					diags = append(diags, &hcl.Diagnostic{
 						Severity: hcl.DiagError,
 						Summary:  "Argument or block definition required",
@@ -388,12 +411,23 @@ Token:
 			// user intent for this one, we'll skip it if we're already in
 			// recovery mode.
 			if !p.recovery {
-				diags = append(diags, &hcl.Diagnostic{
-					Severity: hcl.DiagError,
-					Summary:  "Invalid single-argument block definition",
-					Detail:   "A single-line block definition must end with a closing brace immediately after its single argument definition.",
-					Subject:  p.Peek().Range.Ptr(),
-				})
+				switch p.Peek().Type {
+				case TokenEOF:
+					diags = append(diags, &hcl.Diagnostic{
+						Severity: hcl.DiagError,
+						Summary:  "Unclosed configuration block",
+						Detail:   "There is no closing brace for this block before the end of the file. This may be caused by incorrect brace nesting elsewhere in this file.",
+						Subject:  oBrace.Range.Ptr(),
+						Context:  hcl.RangeBetween(ident.Range, oBrace.Range).Ptr(),
+					})
+				default:
+					diags = append(diags, &hcl.Diagnostic{
+						Severity: hcl.DiagError,
+						Summary:  "Invalid single-argument block definition",
+						Detail:   "A single-line block definition must end with a closing brace immediately after its single argument definition.",
+						Subject:  p.Peek().Range.Ptr(),
+					})
+				}
 			}
 			p.recover(TokenCBrace)
 		}
@@ -1059,12 +1093,22 @@ func (p *parser) parseExpressionTerm() (Expression, hcl.Diagnostics) {
 	default:
 		var diags hcl.Diagnostics
 		if !p.recovery {
-			diags = append(diags, &hcl.Diagnostic{
-				Severity: hcl.DiagError,
-				Summary:  "Invalid expression",
-				Detail:   "Expected the start of an expression, but found an invalid expression token.",
-				Subject:  &start.Range,
-			})
+			switch start.Type {
+			case TokenEOF:
+				diags = append(diags, &hcl.Diagnostic{
+					Severity: hcl.DiagError,
+					Summary:  "Missing expression",
+					Detail:   "Expected the start of an expression, but found the end of the file.",
+					Subject:  &start.Range,
+				})
+			default:
+				diags = append(diags, &hcl.Diagnostic{
+					Severity: hcl.DiagError,
+					Summary:  "Invalid expression",
+					Detail:   "Expected the start of an expression, but found an invalid expression token.",
+					Subject:  &start.Range,
+				})
+			}
 		}
 		p.setRecovery()
 
@@ -1163,13 +1207,23 @@ Token:
 		}
 
 		if sep.Type != TokenComma {
-			diags = append(diags, &hcl.Diagnostic{
-				Severity: hcl.DiagError,
-				Summary:  "Missing argument separator",
-				Detail:   "A comma is required to separate each function argument from the next.",
-				Subject:  &sep.Range,
-				Context:  hcl.RangeBetween(name.Range, sep.Range).Ptr(),
-			})
+			switch sep.Type {
+			case TokenEOF:
+				diags = append(diags, &hcl.Diagnostic{
+					Severity: hcl.DiagError,
+					Summary:  "Unterminated function call",
+					Detail:   "There is no closing parenthesis for this function call before the end of the file. This may be caused by incorrect parethesis nesting elsewhere in this file.",
+					Subject:  hcl.RangeBetween(name.Range, openTok.Range).Ptr(),
+				})
+			default:
+				diags = append(diags, &hcl.Diagnostic{
+					Severity: hcl.DiagError,
+					Summary:  "Missing argument separator",
+					Detail:   "A comma is required to separate each function argument from the next.",
+					Subject:  &sep.Range,
+					Context:  hcl.RangeBetween(name.Range, sep.Range).Ptr(),
+				})
+			}
 			closeTok = p.recover(TokenCParen)
 			break Token
 		}
@@ -1242,13 +1296,23 @@ func (p *parser) parseTupleCons() (Expression, hcl.Diagnostics) {
 
 		if next.Type != TokenComma {
 			if !p.recovery {
-				diags = append(diags, &hcl.Diagnostic{
-					Severity: hcl.DiagError,
-					Summary:  "Missing item separator",
-					Detail:   "Expected a comma to mark the beginning of the next item.",
-					Subject:  &next.Range,
-					Context:  hcl.RangeBetween(open.Range, next.Range).Ptr(),
-				})
+				switch next.Type {
+				case TokenEOF:
+					diags = append(diags, &hcl.Diagnostic{
+						Severity: hcl.DiagError,
+						Summary:  "Unterminated tuple constructor expression",
+						Detail:   "There is no corresponding closing bracket before the end of the file. This may be caused by incorrect bracket nesting elsewhere in this file.",
+						Subject:  open.Range.Ptr(),
+					})
+				default:
+					diags = append(diags, &hcl.Diagnostic{
+						Severity: hcl.DiagError,
+						Summary:  "Missing item separator",
+						Detail:   "Expected a comma to mark the beginning of the next item.",
+						Subject:  &next.Range,
+						Context:  hcl.RangeBetween(open.Range, next.Range).Ptr(),
+					})
+				}
 			}
 			close = p.recover(TokenCBrack)
 			break
@@ -1359,6 +1423,13 @@ func (p *parser) parseObjectCons() (Expression, hcl.Diagnostics) {
 						Subject:  &next.Range,
 						Context:  hcl.RangeBetween(open.Range, next.Range).Ptr(),
 					})
+				case TokenEOF:
+					diags = append(diags, &hcl.Diagnostic{
+						Severity: hcl.DiagError,
+						Summary:  "Unterminated object constructor expression",
+						Detail:   "There is no corresponding closing brace before the end of the file. This may be caused by incorrect brace nesting elsewhere in this file.",
+						Subject:  open.Range.Ptr(),
+					})
 				default:
 					diags = append(diags, &hcl.Diagnostic{
 						Severity: hcl.DiagError,
@@ -1399,13 +1470,23 @@ func (p *parser) parseObjectCons() (Expression, hcl.Diagnostics) {
 
 		if next.Type != TokenComma && next.Type != TokenNewline {
 			if !p.recovery {
-				diags = append(diags, &hcl.Diagnostic{
-					Severity: hcl.DiagError,
-					Summary:  "Missing attribute separator",
-					Detail:   "Expected a newline or comma to mark the beginning of the next attribute.",
-					Subject:  &next.Range,
-					Context:  hcl.RangeBetween(open.Range, next.Range).Ptr(),
-				})
+				switch next.Type {
+				case TokenEOF:
+					diags = append(diags, &hcl.Diagnostic{
+						Severity: hcl.DiagError,
+						Summary:  "Unterminated object constructor expression",
+						Detail:   "There is no corresponding closing brace before the end of the file. This may be caused by incorrect brace nesting elsewhere in this file.",
+						Subject:  open.Range.Ptr(),
+					})
+				default:
+					diags = append(diags, &hcl.Diagnostic{
+						Severity: hcl.DiagError,
+						Summary:  "Missing attribute separator",
+						Detail:   "Expected a newline or comma to mark the beginning of the next attribute.",
+						Subject:  &next.Range,
+						Context:  hcl.RangeBetween(open.Range, next.Range).Ptr(),
+					})
+				}
 			}
 			close = p.recover(TokenCBrace)
 			break

hclsyntax/parser_template.go

@@ -414,22 +414,42 @@ Token:
 			if close.Type != TokenTemplateSeqEnd {
 				if !p.recovery {
 					switch close.Type {
-					case TokenColon:
+					case TokenEOF:
 						diags = append(diags, &hcl.Diagnostic{
 							Severity: hcl.DiagError,
-							Summary:  "Extra characters after interpolation expression",
-							Detail:   "Template interpolation doesn't expect a colon at this location. Did you intend this to be a literal sequence to be processed as part of another language? If so, you can escape it by starting with \"$${\" instead of just \"${\".",
-							Subject:  &close.Range,
-							Context:  hcl.RangeBetween(startRange, close.Range).Ptr(),
+							Summary:  "Unclosed template interpolation sequence",
+							Detail:   "There is no closing brace for this interpolation sequence before the end of the file. This might be caused by incorrect nesting inside the given expression.",
+							Subject:  &startRange,
 						})
-					default:
+					case TokenColon:
 						diags = append(diags, &hcl.Diagnostic{
 							Severity: hcl.DiagError,
 							Summary:  "Extra characters after interpolation expression",
-							Detail:   "Expected a closing brace to end the interpolation expression, but found extra characters.\n\nThis can happen when you include interpolation syntax for another language, such as shell scripting, but forget to escape the interpolation start token. If this is an embedded sequence for another language, escape it by starting with \"$${\" instead of just \"${\".",
+							Detail:   "Template interpolation doesn't expect a colon at this location. Did you intend this to be a literal sequence to be processed as part of another language? If so, you can escape it by starting with \"$${\" instead of just \"${\".",
 							Subject:  &close.Range,
 							Context:  hcl.RangeBetween(startRange, close.Range).Ptr(),
 						})
+					default:
+						if (close.Type == TokenCQuote || close.Type == TokenOQuote) && end == TokenCQuote {
+							// We'll get here if we're processing a _quoted_
+							// template and we find an errant quote inside an
+							// interpolation sequence, which suggests that
+							// the interpolation sequence is missing its terminator.
+							diags = append(diags, &hcl.Diagnostic{
+								Severity: hcl.DiagError,
+								Summary:  "Unclosed template interpolation sequence",
+								Detail:   "There is no closing brace for this interpolation sequence before the end of the quoted template. This might be caused by incorrect nesting inside the given expression.",
+								Subject:  &startRange,
+							})
+						} else {
+							diags = append(diags, &hcl.Diagnostic{
+								Severity: hcl.DiagError,
+								Summary:  "Extra characters after interpolation expression",
+								Detail:   "Expected a closing brace to end the interpolation expression, but found extra characters.\n\nThis can happen when you include interpolation syntax for another language, such as shell scripting, but forget to escape the interpolation start token. If this is an embedded sequence for another language, escape it by starting with \"$${\" instead of just \"${\".",
+								Subject:  &close.Range,
+								Context:  hcl.RangeBetween(startRange, close.Range).Ptr(),
+							})
+						}
 					}
 				}
 				p.recover(TokenTemplateSeqEnd)