Literal ${ in strings, one interpolation splitter, errors that teach

[b-macker]

Summary

An LLM building a real NAAb project put a JavaScript template literal inside a NAAb string and got Parse error at line 1, column 11: ... Got: '/'. The error named no file. The "line 1" was a position inside the extracted ${...}, not in the source file. The attached hint was about multi-line operators and had nothing to do with the problem, so it took a long bisection to find.

The cause: every NAAb string evaluates ${...}, and there was no way to write a literal one. \${ and \x24{ both still interpolated.

This PR adds that escape, gives the whole class of mistake errors that point at the source and suggest the fix, and fixes a VM/tree-walker divergence found along the way.

Changes

• Escape:
  • \${ is now a literal ${.
  • In f-strings, \{ and \} are literal braces.
  • A \$ not followed by { keeps its backslash, so shell text like "echo \$HOME" is unchanged.
  • \{ outside f-strings also keeps its backslash, so regex text like a\{2\} is unchanged.
  • Both compatibility claims are measured on the old build as well as the new one.
• One splitter: the new header include/naab/string_interpolation.h is now used by the tree-walker, the VM compiler and both taint scanners. There were four hand-written copies, and if the evaluator and a taint scanner ever disagreed about what counts as interpolation, taint tracking could be bypassed.
• VM/tree-walker divergence fixed (existed before this PR):
  • "n=${n}" + "!" printed n=${n}! on the VM but n=5! on the tree-walker.
  • Cause: the VM combined the two literals into one constant from their raw source text, before interpolation.
  • It now only combines literals that contain no ${.
• Errors that teach:
  • A parse error inside ${...} now gives the file, line and column of the enclosing string, shows the expression, and recognises JavaScript or shell text. It suggests the \${ escape, or a <<javascript>> block instead.
  • String literals now carry their source location, and tokens inside ${...} are shifted to that line. Runtime errors inside ${...} therefore report the real line instead of line 1.
  • An undefined ALL_CAPS name (as in "echo ${HOME}") now explains that the string was interpolated and offers \${HOME} or env.get("HOME"), in both engines.
  • === and !== now point to == and !=. I checked first that == does not coerce types: 1 == "1" is false in both engines.
• Formatter: it now writes the escape back out as \${. Writing the lexer's internal marker instead would have turned a literal ${ back into live interpolation the next time the file ran.
• Docs:
  • Book chapter 2 now documents string interpolation and its escapes; the book didn't cover interpolation before.
  • CLAUDE.md gets a new gotcha entry.
  • Corrections to the regex suite's header comment and to docs/unit-test-findings.md: both still described my Windows-stall theory, which the next Windows run disproved.
  • The findings doc also records a use-after-free race in AsyncCallbackPool. That code is only used by tests and isn't changed here.

Test Plan

• tests/parser/test_string_interp_escape.sh: 25 checks across both engines. On master, only its 4 "behaviour unchanged" checks pass. Those 4 run as a separate program, so a crash elsewhere in the file can't make them fail falsely.
• test_taint_engine_parity.sh passes 14/14, including a new PARITY-interp_escaped check: an escaped \${t} is not treated as a use of t, while the existing PARITY-interp check still requires an unescaped ${t} to be flagged.
• Differential VM vs tree-walker 56/0, error-message leak check 874/0, formatter idempotence passes.
• Full suite: running locally, result to follow.

🤖 Generated with Claude Code

https://claude.ai/code/session_01ELUfjXZvx8kzXo1UJjrAhC

---

Generated by Claude Code

[github-actions]

NAAb Governance Report

Metric	Count
Files checked	16
Passed	16
Failed	0

All governance checks passed!

_{Generated by NAAb Governance Engine v4.0}