From b0e5665aaa09ad8dcc2cb7fd7f351ebb80c3ff4c Mon Sep 17 00:00:00 2001
From: Martin Atkins <mart@degeneration.co.uk>
Date: Thu, 15 Apr 2021 14:34:02 -0700
Subject: [PATCH] hclsyntax: Hint about possible unescaped ${ for other
 languages

It's a common error to accidentally include a ${ intended to be processed
as part of another language after HCL processing, such as a shell script
or an AWS IAM policy document.

Exactly what sort of error will appear in that case unfortunately depends
on the syntax for that other language, but a lot of them happen to end up
in the codepath where we report the "Extra characters after interpolation
expression" diagnostic message. For that reason, this extends that error
message with an additional hint about escaping, and I've also included
a special case for colons because they happen to arise in both Bash and
AWS IAM interpolation syntax, albeit with different meanings.

Because this message is coming from HCL and HCL doesn't typically assume
anything about the application where it's being used, the hint message
is pretty generic and focuses only on the hint about the escaping syntax,
in the hope that this will be hint enough to prompt the user to think
about what they are currently working on and realize how to respond to
this error.
---
 hclsyntax/parser_template.go | 25 ++++++++++++++++++-------
 1 file changed, 18 insertions(+), 7 deletions(-)

diff --git a/hclsyntax/parser_template.go b/hclsyntax/parser_template.go
index 6b7e6ca4..02181fc7 100644
--- a/hclsyntax/parser_template.go
+++ b/hclsyntax/parser_template.go
@@ -413,13 +413,24 @@ Token:
 			close := p.Peek()
 			if close.Type != TokenTemplateSeqEnd {
 				if !p.recovery {
-					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.",
-						Subject:  &close.Range,
-						Context:  hcl.RangeBetween(startRange, close.Range).Ptr(),
-					})
+					switch close.Type {
+					case TokenColon:
+						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(),
+						})
+					default:
+						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)
 			} else {