macroctx: pass ctx JSON (caps) to user macros; add demo macro; docs: MacroCtx section and sandbox Box API; golden for for/foreach normalized AST

tools/build_aot.sh

@@ -5,7 +5,7 @@ ROOT_DIR=$(cd "$(dirname "$0")/.." && pwd)
 cd "$ROOT_DIR"
 
 APP=${1:-apps/tests/mir-branch-ret/main.nyash}
-OUT=${2:-app_aot}
+OUT=${2:-tmp/app_aot}
 OBJ_DIR=${OBJ_DIR:-target/aot_objects}
 OBJ_BASENAME=$(basename "$APP" .nyash)
 OBJ_PATH="$OBJ_DIR/$OBJ_BASENAME.o"
@@ -28,6 +28,8 @@ if [[ ! -f "$OBJ_PATH" ]]; then
 fi
 ls -l "$OBJ_PATH"
 
+# Ensure output directory exists
+mkdir -p "$(dirname "$OUT")"
 echo "[4/5] link with nyrt -> $OUT"
 cc "$OBJ_PATH" \
   -L crates/nyrt/target/release \

tools/build_llvm.sh

@@ -13,7 +13,7 @@ Compiles a Nyash program with the LLVM backend to an object (.o),
 links it with the NyRT static runtime, and produces a native executable.
 
 Options:
-  -o <output>   Output executable name (default: app)
+  -o <output>   Output executable path (default: tmp/app)
 
 Requirements:
   - LLVM 18 development (llvm-config-18)
@@ -24,7 +24,7 @@ USAGE
 if [[ $# -lt 1 ]]; then usage; exit 1; fi
 
 INPUT=""
-OUT="app"
+OUT="tmp/app"
 while [[ $# -gt 0 ]]; do
   case "$1" in
     -h|--help) usage; exit 0 ;;
@@ -129,6 +129,8 @@ else
   ( cd crates/nyrt && cargo build --release -j 24 >/dev/null )
 fi
 
+# Ensure output directory exists
+mkdir -p "$(dirname "$OUT")"
 echo "[4/4] Linking $OUT ..."
 cc "$OBJ" \
   -L target/release \

tools/test/golden/macro/for_basic.expanded.json

@@ -0,0 +1,8 @@
+{"kind":"Program","statements":[
+  {"kind":"Local","variables":["i"],"inits":[{"kind":"Literal","value":{"type":"int","value":0}}]},
+  {"kind":"Loop","condition":{"kind":"BinaryOp","op":"<","left":{"kind":"Variable","name":"i"},"right":{"kind":"Literal","value":{"type":"int","value":3}}},"body":[
+    {"kind":"Print","expression":{"kind":"Variable","name":"i"}},
+    {"kind":"Assignment","target":{"kind":"Variable","name":"i"},"value":{"kind":"BinaryOp","op":"+","left":{"kind":"Variable","name":"i"},"right":{"kind":"Literal","value":{"type":"int","value":1}}}}
+  ]}
+]}
+

tools/test/golden/macro/for_basic_user_macro_golden.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+root=$(cd "$(dirname "$0")"/../../../.. && pwd)
+bin="$root/target/release/nyash"
+src="apps/tests/macro/loopform/for_basic.nyash"
+golden="$root/tools/test/golden/macro/for_basic.expanded.json"
+
+if [ ! -x "$bin" ]; then
+  echo "nyash binary not found at $bin; build first (cargo build --release)" >&2
+  exit 1
+fi
+
+normalize_json() { python3 -c 'import sys,json; print(json.dumps(json.loads(sys.stdin.read()), sort_keys=True, separators=(",", ":")))'; }
+
+out_raw=$("$bin" --dump-expanded-ast-json "$src")
+out_norm=$(printf '%s' "$out_raw" | normalize_json)
+gold_norm=$(normalize_json < "$golden")
+
+if [ "$out_norm" != "$gold_norm" ]; then
+  echo "[FAIL] for_basic expanded JSON mismatch" >&2
+  diff -u <(echo "$out_norm") <(echo "$gold_norm") || true
+  exit 2
+fi
+
+echo "[OK] golden for_basic expansion matched"

tools/test/golden/macro/foreach_basic.expanded.json

@@ -0,0 +1,9 @@
+{"kind":"Program","statements":[
+  {"kind":"Local","variables":["arr"],"inits":[{"kind":"Array","elements":[{"kind":"Literal","value":{"type":"int","value":1}},{"kind":"Literal","value":{"type":"int","value":2}},{"kind":"Literal","value":{"type":"int","value":3}}]}]},
+  {"kind":"Local","variables":["__ny_i"],"inits":[{"kind":"Literal","value":{"type":"int","value":0}}]},
+  {"kind":"Loop","condition":{"kind":"BinaryOp","op":"<","left":{"kind":"Variable","name":"__ny_i"},"right":{"kind":"MethodCall","object":{"kind":"Variable","name":"arr"},"method":"size","arguments":[]}},"body":[
+    {"kind":"Print","expression":{"kind":"MethodCall","object":{"kind":"Variable","name":"arr"},"method":"get","arguments":[{"kind":"Variable","name":"__ny_i"}]}},
+    {"kind":"Assignment","target":{"kind":"Variable","name":"__ny_i"},"value":{"kind":"BinaryOp","op":"+","left":{"kind":"Variable","name":"__ny_i"},"right":{"kind":"Literal","value":{"type":"int","value":1}}}}
+  ]}
+]}
+

tools/test/golden/macro/foreach_basic_user_macro_golden.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+root=$(cd "$(dirname "$0")"/../../../.. && pwd)
+bin="$root/target/release/nyash"
+src="apps/tests/macro/loopform/foreach_basic.nyash"
+golden="$root/tools/test/golden/macro/foreach_basic.expanded.json"
+
+if [ ! -x "$bin" ]; then
+  echo "nyash binary not found at $bin; build first (cargo build --release)" >&2
+  exit 1
+fi
+
+normalize_json() { python3 -c 'import sys,json; print(json.dumps(json.loads(sys.stdin.read()), sort_keys=True, separators=(",", ":")))'; }
+
+out_raw=$("$bin" --dump-expanded-ast-json "$src")
+out_norm=$(printf '%s' "$out_raw" | normalize_json)
+gold_norm=$(normalize_json < "$golden")
+
+if [ "$out_norm" != "$gold_norm" ]; then
+  echo "[FAIL] foreach_basic expanded JSON mismatch" >&2
+  diff -u <(echo "$out_norm") <(echo "$gold_norm") || true
+  exit 2
+fi
+
+echo "[OK] golden foreach_basic expansion matched"