fix: return heredoc bodies as real multi-line values when unquoting (#303)

[kkozik-amplify]

caused by #303

Problem

preserve_heredocs=False strips the <<-EOT markers as documented, but converts every real newline in the body into a literal \n (backslash + n). Reported from production: a heredoc-defined PGP private key came out as a single line and was silently unusable.

I verified the reporter's strongest claim rather than taking it on trust — brute-forcing all sixteen combinations of strip_string_quotes, preserve_heredocs, wrap_objects and explicit_blocks:

combinations yielding v7 semantics: 0

There was genuinely no way to get a plain multi-line string out of 8.x.

Root cause

hcl2/rules/strings.py. The flatten path escapes the body to build a quoted-string source form, and that escaping ran before the strip_string_quotes early return:

heredoc = _strip_closing_marker_line(match.group(2))
heredoc = heredoc.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n")
if options.strip_string_quotes:
    return heredoc        # ← escaped SOURCE, where the caller asked for a VALUE
return f'"{heredoc}"'

HeredocTrimTemplateRule has the same shape via its sep = "\\n".

This is the same defect #313 fixed for quoted strings — strip_string_quotes should yield values, not source. That change touched StringRule and left both heredoc rules behind.

Fix

Move the escaping after the early return, in both rules. The quoted form is unchanged.

Options	Before	After
strip_string_quotes + preserve_heredocs=False	'line1\\nline2'	'line1\nline2'
preserve_heredocs=False alone	'"line1\\nline2"'	unchanged

What the tests said

The only two failures across the whole suite were the tests asserting the reported behaviour:

self.assertEqual(rule.serialize(opts), "line1\\nline2")

No golden or integration file moved. Both now assert real newlines, and each gained a sibling pinning that the quoted form still escapes — so the value path and the source path cannot drift apart again.

Added TestHeredocFlattenedToValue covering the plain and trimmed forms, the reported multi-line-secret shape, and that embedded quotes and backslashes are escaped in the source form but not the value form.

Docs

The issue notes the migration guide never mentions this, which is how the reporter ended up with no working combination. Fixed both:

• docs/01_getting_started.md — the option table said only "Keep heredocs in their original form"; it now describes what False actually produces and how to get the value.
• docs/06_migrating_to_v8.md — preserve_heredocs=False added to the V7_COMPAT recipe, with a worked example and a note that it needs strip_string_quotes alongside it.

Both documented outputs were executed against the code, not written from memory.

Related

• fix: make strip_string_quotes yield values, not broken source (#308, #310) #313 — same defect class, fixed for quoted strings; this is the heredoc half
• strip_string_quotes should be enabled by default #289 — proposes strip_string_quotes as the default; this should land first, or that change ships the corruption to everyone

Test plan

• Full suite: 1511 passing
• pre-commit run: clean (ruff check, ruff format, mypy)
• The issue's exact reproduction now yields real newlines: 3 | literal backslash-n: 0