feat!: redesign for-loop syntax with explicit context access

BREAKING CHANGE: The for-loop syntax no longer implicitly treats
the first variable as an index when two variables are present.

Old syntax (no longer works):
  for idx, item in items:
      print(idx, item)

New syntax:
  for item in items with loop:
      print(loop.idx, item)

The `with <identifier>` clause is optional and provides a context
object containing:
  - loop.idx: current iteration index (0-based)
  - loop.src: the original collection being iterated

The recommended convention for for-loops is `loop` (e.g., `with loop`),
making the syntax self-documenting: `loop.idx` clearly indicates
"the loop's current index".

This change unifies the mental model: all variables on the left
side of `in` now correspond to values being unpacked from each
element. Two variables means unpacking pairs, not index + item.

Benefits:
- Clearer semantics: variables always map to values
- Explicit over implicit: context access is opt-in
- Consistent: same pattern for lists, maps, strings, comprehensions
- Flexible: context variable name is user-chosen

A migration hint appears when the interpreter detects the old
pattern (first variable named 'idx', 'index', or 'i' with a
non-unpackable collection). This hint triggers for 2 or more
left-hand variables, not just exactly 2.

Note: The migration hint can be removed from 2027 onwards, once
users have had sufficient time to update their scripts.

Bug fix: `break` now works correctly in map iteration. Previously,
`break` inside a `for key in map:` loop would only exit the switch
statement, not the for loop itself. Fixed by adding a labeled loop
(`Loop:`) and using `break Loop`. A regression test with switch
inside a map loop ensures this won't recur.

Implementation notes:
- Context creation extracted to `setLoopContext()` helper to avoid
  duplication between list and map iteration
- go.mod contains a temporary replace directive pointing to a local
  tree-sitter-rad with the grammar changes. This will be removed
  once tree-sitter-rad publishes a new release.

Author: amterp

core/interpreter.go

@@ -963,18 +963,32 @@ func (i *Interpreter) doVarPathAssign(varPathNode *ts.Node, rightValue RadValue,
 	val.ModifyIdx(i, &lastIndex, rightValue)
 }
 
+// setLoopContext creates and sets the loop context variable if the user specified 'with <name>'.
+// The context is a map containing 'idx' (current iteration index) and 'src' (original collection).
+func (i *Interpreter) setLoopContext(contextNode *ts.Node, idx int64, srcValue RadValue) {
+	if contextNode == nil {
+		return
+	}
+	ctxName := i.GetSrcForNode(contextNode)
+	ctx := NewRadMap()
+	ctx.Set(newRadValue(i, contextNode, "idx"), newRadValue(i, contextNode, idx))
+	ctx.Set(newRadValue(i, contextNode, "src"), srcValue)
+	i.env.SetVar(ctxName, newRadValue(i, contextNode, ctx))
+}
+
 func (i *Interpreter) executeForLoop(node *ts.Node, doOneLoop func() EvalResult) EvalResult {
 	leftsNode := rl.GetChild(node, rl.F_LEFTS)
 	rightNode := rl.GetChild(node, rl.F_RIGHT)
+	contextNode := rl.GetChild(node, rl.F_CONTEXT)
 
 	res := i.eval(rightNode)
 	switch coercedRight := res.Val.Val.(type) {
 	case RadString:
-		return runForLoopList(i, leftsNode, rightNode, coercedRight.ToRuneList(), doOneLoop)
+		return runForLoopList(i, leftsNode, rightNode, contextNode, coercedRight.ToRuneList(), res.Val, doOneLoop)
 	case *RadList:
-		return runForLoopList(i, leftsNode, rightNode, coercedRight, doOneLoop)
+		return runForLoopList(i, leftsNode, rightNode, contextNode, coercedRight, res.Val, doOneLoop)
 	case *RadMap:
-		return runForLoopMap(i, leftsNode, coercedRight, doOneLoop)
+		return runForLoopMap(i, leftsNode, contextNode, coercedRight, res.Val, doOneLoop)
 	default:
 		i.errorf(rightNode, "Cannot iterate through a %s", TypeAsString(res.Val))
 		panic(UNREACHABLE)
@@ -983,52 +997,50 @@ func (i *Interpreter) executeForLoop(node *ts.Node, doOneLoop func() EvalResult)
 
 func runForLoopList(
 	i *Interpreter,
-	leftsNode, rightNode *ts.Node,
+	leftsNode, rightNode, contextNode *ts.Node,
 	list *RadList,
+	srcValue RadValue,
 	doOneLoop func() EvalResult,
 ) EvalResult {
-	var idxNode *ts.Node
-	itemNodes := make([]*ts.Node, 0)
-
 	leftNodes := rl.GetChildren(leftsNode, rl.F_LEFT)
 
 	if len(leftNodes) == 0 {
 		i.errorf(leftsNode, "Expected at least one variable on the left side of for loop")
-	} else if len(leftNodes) == 1 {
-		itemNodes = append(itemNodes, &leftNodes[0])
-	} else {
-		idxNode = &leftNodes[0]
-		for idx := 1; idx < len(leftNodes); idx++ {
-			itemNodes = append(itemNodes, &leftNodes[idx])
-		}
 	}
 
 Loop:
 	for idx, val := range list.Values {
-		if idxNode != nil {
-			idxName := i.GetSrcForNode(idxNode)
-			i.env.SetVar(idxName, newRadValue(i, idxNode, int64(idx)))
-		}
+		i.setLoopContext(contextNode, int64(idx), srcValue)
 
-		if len(itemNodes) == 1 {
-			itemNode := itemNodes[0]
+		if len(leftNodes) == 1 {
+			itemNode := &leftNodes[0]
 			itemName := i.GetSrcForNode(itemNode)
 			i.env.SetVar(itemName, val)
-		} else if len(itemNodes) > 1 {
-			// expecting list of lists, unpacking by idx
+		} else {
+			// Multiple variables = unpacking (expecting list of lists)
 			listInList, ok := val.TryGetList()
 			if !ok {
-				i.errorf(rightNode, "Expected list of lists, got element type %q", TypeAsString(val))
+				// Migration hint for old syntax
+				firstName := i.GetSrcForNode(&leftNodes[0])
+				if firstName == "idx" || firstName == "index" || firstName == "i" {
+					i.errorf(rightNode, "Cannot unpack %q into %d values\n\n"+
+						"Note: The for-loop syntax changed. It looks like you may be using the old syntax.\n"+
+						"Old: for idx, item in items:\n"+
+						"New: for item in items with loop:\n"+
+						"         print(loop.idx, item)",
+						TypeAsString(val), len(leftNodes))
+				}
+				i.errorf(rightNode, "Cannot unpack %q into %d values", TypeAsString(val), len(leftNodes))
 			}
 
-			if listInList.LenInt() < len(itemNodes) {
+			if listInList.LenInt() < len(leftNodes) {
 				i.errorf(rightNode, "Expected at least %s in inner list, got %d",
-					com.Pluralize(len(itemNodes), "value"), listInList.LenInt())
+					com.Pluralize(len(leftNodes), "value"), listInList.LenInt())
 			}
 
-			for idx, itemNode := range itemNodes {
-				itemName := i.GetSrcForNode(itemNode)
-				i.env.SetVar(itemName, listInList.Values[idx])
+			for j, itemNode := range leftNodes {
+				itemName := i.GetSrcForNode(&itemNode)
+				i.env.SetVar(itemName, listInList.Values[j])
 			}
 		}
 
@@ -1043,7 +1055,13 @@ Loop:
 	return VoidNormal
 }
 
-func runForLoopMap(i *Interpreter, leftsNode *ts.Node, radMap *RadMap, doOneLoop func() EvalResult) EvalResult {
+func runForLoopMap(
+	i *Interpreter,
+	leftsNode, contextNode *ts.Node,
+	radMap *RadMap,
+	srcValue RadValue,
+	doOneLoop func() EvalResult,
+) EvalResult {
 	var keyNode *ts.Node
 	var valueNode *ts.Node
 
@@ -1059,7 +1077,11 @@ func runForLoopMap(i *Interpreter, leftsNode *ts.Node, radMap *RadMap, doOneLoop
 		valueNode = &leftNodes[1]
 	}
 
+	idx := int64(0)
+Loop:
 	for _, key := range radMap.Keys() {
+		i.setLoopContext(contextNode, idx, srcValue)
+
 		keyName := i.GetSrcForNode(keyNode)
 		i.env.SetVar(keyName, key)
 
@@ -1072,10 +1094,11 @@ func runForLoopMap(i *Interpreter, leftsNode *ts.Node, radMap *RadMap, doOneLoop
 		res := doOneLoop()
 		switch res.Ctrl {
 		case CtrlBreak:
-			break
+			break Loop
 		case CtrlReturn, CtrlYield:
 			return res
 		}
+		idx++
 	}
 	return VoidNormal
 }

core/testing/for_context_test.go

@@ -0,0 +1,121 @@
+package testing
+
+import "testing"
+
+func Test_For_WithContext_PrintFullContext(t *testing.T) {
+	// Print the full context object to verify structure
+	script := `
+items = ["a", "b", "c"]
+for item in items with loop:
+	print(loop)
+`
+	setupAndRunCode(t, script, "--color=never")
+	expected := `{ "idx": 0, "src": [ "a", "b", "c" ] }
+{ "idx": 1, "src": [ "a", "b", "c" ] }
+{ "idx": 2, "src": [ "a", "b", "c" ] }
+`
+	assertOnlyOutput(t, stdOutBuffer, expected)
+	assertNoErrors(t)
+}
+
+func Test_For_WithContext_IdxAndItem(t *testing.T) {
+	script := `
+items = ["a", "b", "c"]
+for item in items with loop:
+	print(loop.idx, item)
+`
+	setupAndRunCode(t, script, "--color=never")
+	assertOnlyOutput(t, stdOutBuffer, "0 a\n1 b\n2 c\n")
+	assertNoErrors(t)
+}
+
+func Test_For_WithContext_AccessSrc(t *testing.T) {
+	// Use loop.src to access original collection for lookahead
+	script := `
+items = ["a", "b", "c"]
+for item in items with loop:
+	if loop.idx < loop.src.len() - 1:
+		print(loop.src[loop.idx + 1])
+`
+	setupAndRunCode(t, script, "--color=never")
+	assertOnlyOutput(t, stdOutBuffer, "b\nc\n")
+	assertNoErrors(t)
+}
+
+func Test_For_WithContext_Map(t *testing.T) {
+	script := `
+m = {"a": 1, "b": 2, "c": 3}
+for key in m with loop:
+	print(loop.idx, key)
+`
+	setupAndRunCode(t, script, "--color=never")
+	assertOnlyOutput(t, stdOutBuffer, "0 a\n1 b\n2 c\n")
+	assertNoErrors(t)
+}
+
+func Test_For_WithContext_MapKeyValue(t *testing.T) {
+	script := `
+m = {"a": 1, "b": 2}
+for key, value in m with loop:
+	print(loop.idx, key, value)
+`
+	setupAndRunCode(t, script, "--color=never")
+	assertOnlyOutput(t, stdOutBuffer, "0 a 1\n1 b 2\n")
+	assertNoErrors(t)
+}
+
+func Test_For_WithContext_ListComprehension(t *testing.T) {
+	script := `
+items = ["a", "b", "c"]
+result = ["{loop.idx}:{item}" for item in items with loop]
+print(result)
+`
+	setupAndRunCode(t, script, "--color=never")
+	assertOnlyOutput(t, stdOutBuffer, "[ \"0:a\", \"1:b\", \"2:c\" ]\n")
+	assertNoErrors(t)
+}
+
+func Test_For_WithContext_String(t *testing.T) {
+	script := `
+s = "abc"
+for char in s with loop:
+	print(loop.idx, char)
+`
+	setupAndRunCode(t, script, "--color=never")
+	assertOnlyOutput(t, stdOutBuffer, "0 a\n1 b\n2 c\n")
+	assertNoErrors(t)
+}
+
+func Test_For_WithContext_CustomName(t *testing.T) {
+	// User can use any name for context variable
+	script := `
+items = [1, 2, 3]
+for item in items with meta:
+	print(meta.idx)
+`
+	setupAndRunCode(t, script, "--color=never")
+	assertOnlyOutput(t, stdOutBuffer, "0\n1\n2\n")
+	assertNoErrors(t)
+}
+
+func Test_For_Unpacking_NoAutoIndex(t *testing.T) {
+	script := `
+pairs = [["a", 1], ["b", 2]]
+for name, val in pairs:
+	print(name, val)
+`
+	setupAndRunCode(t, script, "--color=never")
+	assertOnlyOutput(t, stdOutBuffer, "a 1\nb 2\n")
+	assertNoErrors(t)
+}
+
+func Test_For_Unpacking_WithContext(t *testing.T) {
+	script := `
+pairs = [["a", 1], ["b", 2]]
+for name, val in pairs with loop:
+	print(loop.idx, name, val)
+`
+	setupAndRunCode(t, script, "--color=never")
+	assertOnlyOutput(t, stdOutBuffer, "0 a 1\n1 b 2\n")
+	assertNoErrors(t)
+}

core/testing/for_test.go

@@ -16,8 +16,8 @@ for item in a:
 func Test_For_ILoop(t *testing.T) {
 	script := `
 a = ["a", "b", "c"]
-for idx, item in a:
-	print(idx, item)
+for item in a with loop:
+	print(loop.idx, item)
 `
 	setupAndRunCode(t, script, "--color=never")
 	assertOnlyOutput(t, stdOutBuffer, "0 a\n1 b\n2 c\n")
@@ -28,8 +28,8 @@ func Test_For_ChangesInsideAreRemembered(t *testing.T) {
 	script := `
 num = 0
 a = ["a", "b", "c"]
-for idx, item in a:
-	num += idx
+for item in a with loop:
+	num += loop.idx
 print(num)
 `
 	setupAndRunCode(t, script, "--color=never")
@@ -112,3 +112,36 @@ for i in range(5):
 	assertOnlyOutput(t, stdOutBuffer, expected)
 	assertNoErrors(t)
 }
+
+func Test_For_MapCanBreak(t *testing.T) {
+	script := `
+m = {"a": 1, "b": 2, "c": 3}
+for key in m:
+	print(key)
+	break
+`
+	setupAndRunCode(t, script, "--color=never")
+	assertOnlyOutput(t, stdOutBuffer, "a\n")
+	assertNoErrors(t)
+}
+
+func Test_For_MapCanBreakFromSwitch(t *testing.T) {
+	// Regression test: break inside switch should exit the for loop, not just the switch.
+	// The original bug was that the switch statement used 'break' internally, so a user's
+	// 'break' would only exit the switch, causing an infinite loop.
+	script := `
+m = {"a": 1, "b": 2, "c": 3}
+for key, val in m:
+	switch val:
+		case 1:
+			print("found one")
+			break
+		case 2:
+			print("found two")
+		default:
+			print("other")
+`
+	setupAndRunCode(t, script, "--color=never")
+	assertOnlyOutput(t, stdOutBuffer, "found one\n")
+	assertNoErrors(t)
+}