@aigne/ash 0.0.1

package/src/parser.test.ts

@@ -0,0 +1,1024 @@
+import { describe, it, expect } from "vitest";
+import { AshLexer } from "./lexer.js";
+import { AshParser } from "./parser.js";
+import type { Program } from "./ast.js";
+
+const lexer = new AshLexer();
+const parser = new AshParser();
+
+function parse(source: string): Program {
+  return parser.parse(lexer.tokenize(source));
+}
+
+describe("Phase 1: ASH Parser", () => {
+  // ── Happy ──
+
+  it("parse minimal job: `job cleanup { find /world/tmp }`", () => {
+    const prog = parse("job cleanup { find /world/tmp }");
+    expect(prog.jobs).toHaveLength(1);
+    expect(prog.jobs[0].name).toBe("cleanup");
+    expect(prog.jobs[0].pipeline).toHaveLength(1);
+    expect(prog.jobs[0].pipeline[0]).toMatchObject({ kind: "find", path: "/world/tmp" });
+  });
+
+  it("parse pipeline with where", () => {
+    const prog = parse('job q { find /world/users | where status == "active" | map name }');
+    const stages = prog.jobs[0].pipeline;
+    expect(stages).toHaveLength(3);
+    expect(stages[0]).toMatchObject({ kind: "find" });
+    expect(stages[1]).toMatchObject({ kind: "where", left: "status", op: "==", right: "active" });
+    expect(stages[2]).toMatchObject({ kind: "map", field: "name" });
+  });
+
+  it("parse save expression", () => {
+    const prog = parse("job s { save /world/output }");
+    expect(prog.jobs[0].pipeline[0]).toMatchObject({ kind: "save", path: "/world/output" });
+  });
+
+  it("parse publish expression", () => {
+    const prog = parse("job p { publish /topic/results }");
+    expect(prog.jobs[0].pipeline[0]).toMatchObject({ kind: "publish", path: "/topic/results" });
+  });
+
+  it("parse tee in pipeline", () => {
+    const prog = parse("job t { find /world/data | tee /world/backup | save /world/main }");
+    expect(prog.jobs[0].pipeline).toHaveLength(3);
+    expect(prog.jobs[0].pipeline[1]).toMatchObject({ kind: "tee", path: "/world/backup" });
+  });
+
+  it("parse fanout with multiple branches", () => {
+    const prog = parse("job f { fanout { save /world/a, save /world/b } }");
+    const fanout = prog.jobs[0].pipeline[0];
+    expect(fanout.kind).toBe("fanout");
+    if (fanout.kind === "fanout") {
+      expect(fanout.branches).toHaveLength(2);
+    }
+  });
+
+  it("parse annotation @approval(human) on job", () => {
+    const prog = parse("@approval(human)\njob secured { find /world/data }");
+    expect(prog.jobs[0].annotations).toHaveLength(1);
+    expect(prog.jobs[0].annotations[0]).toMatchObject({ name: "approval", args: ["human"] });
+  });
+
+  it("parse multiple jobs", () => {
+    const prog = parse("job a { find /world/x }\njob b { find /world/y }");
+    expect(prog.jobs).toHaveLength(2);
+    expect(prog.jobs[0].name).toBe("a");
+    expect(prog.jobs[1].name).toBe("b");
+  });
+
+  it("parse where comparison operators: ==, !=, >, <, >=, <=", () => {
+    const ops = ["==", "!=", ">", "<", ">=", "<="];
+    for (const op of ops) {
+      const prog = parse(`job q { where x ${op} 5 }`);
+      expect(prog.jobs[0].pipeline[0]).toMatchObject({ kind: "where", op });
+    }
+  });
+
+  it("parse map dot field access `map user.name`", () => {
+    const prog = parse("job m { map user.name }");
+    expect(prog.jobs[0].pipeline[0]).toMatchObject({ kind: "map", field: "user.name" });
+  });
+
+  it("parse find nested path", () => {
+    const prog = parse("job f { find /world/org/team/members }");
+    expect(prog.jobs[0].pipeline[0]).toMatchObject({ kind: "find", path: "/world/org/team/members" });
+  });
+
+  // ── Output / Input ──
+
+  it("parse output as top-level statement", () => {
+    const prog = parse('output "hello world"');
+    expect(prog.statements).toHaveLength(1);
+    expect(prog.statements[0]).toMatchObject({ kind: "output", message: "hello world" });
+  });
+
+  it("parse output inside job pipeline", () => {
+    const prog = parse('job q { output "starting" | find /world/x | save /world/out }');
+    expect(prog.statements).toHaveLength(1);
+    const job = prog.statements[0];
+    expect(job.kind).toBe("job");
+    if (job.kind === "job") {
+      expect(job.pipeline[0]).toMatchObject({ kind: "output", message: "starting" });
+    }
+  });
+
+  it("parse input as pipeline source", () => {
+    const prog = parse('job q { input "Enter name:" | save /world/out }');
+    expect(prog.statements).toHaveLength(1);
+    const job = prog.statements[0];
+    if (job.kind === "job") {
+      expect(job.pipeline[0]).toMatchObject({ kind: "input", prompt: "Enter name:" });
+    }
+  });
+
+  it("parse mixed top-level: output + job + output", () => {
+    const prog = parse(`
+output "=== Start ==="
+job etl { find /world/data | save /world/out }
+output "Done."
+    `);
+    expect(prog.statements).toHaveLength(3);
+    expect(prog.statements[0]).toMatchObject({ kind: "output" });
+    expect(prog.statements[1]).toMatchObject({ kind: "job" });
+    expect(prog.statements[2]).toMatchObject({ kind: "output" });
+  });
+
+  it("backward compat: Program.jobs still works for job-only programs", () => {
+    const prog = parse("job a { find /world/x }");
+    expect(prog.jobs).toHaveLength(1);
+    expect(prog.jobs[0].name).toBe("a");
+  });
+
+  // ── Bad ──
+
+  it("job missing body braces → syntax error", () => {
+    expect(() => parse("job x find /world/a")).toThrow();
+  });
+
+  it("pipe right side empty → unexpected EOF", () => {
+    expect(() => parse("job x { find /world/a | }")).toThrow();
+  });
+
+  it("pipe left side empty → unexpected PIPE", () => {
+    expect(() => parse("job x { | where x > 1 }")).toThrow();
+  });
+
+  it("annotation parenthesis unclosed → error", () => {
+    expect(() => parse("@approval(human\njob x { find /world/a }")).toThrow();
+  });
+
+  it("top-level statement without job → error", () => {
+    expect(() => parse("find /world/a")).toThrow();
+  });
+
+  // ── Edge ──
+
+  it("empty body job `job empty { }` → zero pipeline stages", () => {
+    const prog = parse("job empty { }");
+    expect(prog.jobs[0].pipeline).toHaveLength(0);
+  });
+
+  it("10+ stage pipeline → correctly parsed", () => {
+    const stages = Array(10).fill("map x").join(" | ");
+    const prog = parse(`job deep { ${stages} }`);
+    expect(prog.jobs[0].pipeline).toHaveLength(10);
+  });
+
+  it("annotation without args `@readonly` → parsed correctly", () => {
+    const prog = parse("@readonly\njob r { find /world/x }");
+    expect(prog.jobs[0].annotations[0]).toMatchObject({ name: "readonly", args: [] });
+  });
+
+  it("where comparing two fields `where a.x == b.y`", () => {
+    const prog = parse("job q { where a.x == b.y }");
+    const w = prog.jobs[0].pipeline[0];
+    expect(w).toMatchObject({ kind: "where", left: "a.x", right: "b.y" });
+  });
+
+  // ── Security ──
+
+  it("job name is reserved word `job find { }` → rejected", () => {
+    expect(() => parse("job find { }")).toThrow(/reserved keyword/);
+  });
+
+  // ── Data Loss ──
+
+  it("parser error includes line/column", () => {
+    try {
+      parse("job x find");
+      expect.unreachable();
+    } catch (e: any) {
+      expect(e.message).toMatch(/line|column/i);
+    }
+  });
+});
+
+describe("Phase 6: find...where inline + QueryAST", () => {
+  // ── Happy ──
+
+  it("find /path where condition → FindExpression with inline query", () => {
+    const prog = parse("job q { find /world/users where active == true }");
+    const find = prog.jobs[0].pipeline[0];
+    expect(find.kind).toBe("find");
+    if (find.kind === "find") {
+      expect(find.path).toBe("/world/users");
+      expect(find.query).toBeDefined();
+      expect(find.query).toMatchObject({ field: "active", op: "==", value: "true" });
+    }
+  });
+
+  it("find without inline where → no query (backward compat)", () => {
+    const prog = parse("job q { find /world/users }");
+    const find = prog.jobs[0].pipeline[0];
+    if (find.kind === "find") {
+      expect(find.query).toBeUndefined();
+    }
+  });
+
+  it("find /path where condition | more stages → inline query + pipeline continues", () => {
+    const prog = parse("job q { find /world/users where active == true | map name | save /world/out }");
+    const stages = prog.jobs[0].pipeline;
+    expect(stages).toHaveLength(3);
+    expect(stages[0].kind).toBe("find");
+    if (stages[0].kind === "find") {
+      expect(stages[0].query).toBeDefined();
+    }
+    expect(stages[1].kind).toBe("map");
+    expect(stages[2].kind).toBe("save");
+  });
+
+  it("QueryAST from where clause can be serialized to JSON", () => {
+    const prog = parse("job q { find /world/x where score > 80 }");
+    const find = prog.jobs[0].pipeline[0];
+    if (find.kind === "find" && find.query) {
+      const json = JSON.stringify(find.query);
+      expect(json).toBeTruthy();
+      const parsed = JSON.parse(json);
+      expect(parsed.field).toBe("score");
+      expect(parsed.op).toBe(">");
+    }
+  });
+
+  // ── Bad ──
+
+  it("find /path where (missing condition) → syntax error", () => {
+    expect(() => parse("job q { find /world/x where }")).toThrow();
+  });
+
+  // ── Edge ──
+
+  it("find...where inline + pipe where → both parsed", () => {
+    const prog = parse("job q { find /world/x where active == true | where score > 80 }");
+    const stages = prog.jobs[0].pipeline;
+    expect(stages).toHaveLength(2);
+    if (stages[0].kind === "find") {
+      expect(stages[0].query).toBeDefined();
+    }
+    expect(stages[1].kind).toBe("where");
+  });
+
+  it("where with dotted field find /path where user.name == Alice", () => {
+    const prog = parse('job q { find /world/x where user.name == "Alice" }');
+    const find = prog.jobs[0].pipeline[0];
+    if (find.kind === "find" && find.query) {
+      expect(find.query.field).toBe("user.name");
+    }
+  });
+
+  // ── Data Loss ──
+
+  it("v0 find | where syntax still works (regression 0)", () => {
+    const prog = parse("job q { find /world/x | where active == true }");
+    const stages = prog.jobs[0].pipeline;
+    expect(stages).toHaveLength(2);
+    expect(stages[0].kind).toBe("find");
+    expect(stages[1].kind).toBe("where");
+    if (stages[0].kind === "find") {
+      expect(stages[0].query).toBeUndefined();
+    }
+  });
+});
+
+describe("Phase 7: Variables + Map Transformers", () => {
+  it("let x = 42 → LetStatement in top-level", () => {
+    const prog = parse('let x = 42\njob q { find /world/d | save /world/out }');
+    expect(prog.statements.length).toBeGreaterThanOrEqual(2);
+    expect(prog.statements[0]).toMatchObject({ kind: "let", name: "x" });
+  });
+
+  it("let with string value", () => {
+    const prog = parse('let path = "/world/test"\njob q { find /world/d }');
+    const letStmt = prog.statements[0];
+    if (letStmt.kind === "let") {
+      expect(letStmt.value).toBe("/world/test");
+    }
+  });
+
+  it("$variable in where clause", () => {
+    const prog = parse('let threshold = 80\njob q { find /world/d | where score > $threshold | save /world/out }');
+    const where = prog.jobs[0].pipeline[1];
+    if (where.kind === "where") {
+      expect(where.right).toBe("$threshold");
+    }
+  });
+
+  it("map single field still works (backward compat)", () => {
+    const prog = parse("job q { map name }");
+    expect(prog.jobs[0].pipeline[0]).toMatchObject({ kind: "map", field: "name" });
+  });
+
+  it("map { key field } → object mapping", () => {
+    const prog = parse('job q { map { fullName name, dept department } }');
+    const m = prog.jobs[0].pipeline[0];
+    expect(m.kind).toBe("map");
+    if (m.kind === "map") {
+      expect(m.mappings).toBeDefined();
+      expect(m.mappings).toEqual({ fullName: "name", dept: "department" });
+    }
+  });
+
+  // Bad
+  it("let missing = → syntax error", () => {
+    expect(() => parse("let x 42")).toThrow();
+  });
+
+  it("let duplicate name → error", () => {
+    expect(() => parse("let x = 1\nlet x = 2\njob q { find /world/d }")).toThrow();
+  });
+
+  // Edge
+  it("let keyword conflict → error", () => {
+    expect(() => parse("let find = 1\njob q { find /world/d }")).toThrow();
+  });
+});
+
+describe("Phase v3-0: action parsing", () => {
+  it("parse `action /path` → ActionExpression with no params", () => {
+    const prog = parse("job q { action /tools/classify }");
+    const stage = prog.jobs[0].pipeline[0];
+    expect(stage).toMatchObject({ kind: "action", path: "/tools/classify" });
+    if (stage.kind === "action") {
+      expect(stage.params).toBeUndefined();
+    }
+  });
+
+  it("parse `action /path { key: \"value\" }` → ActionExpression with string param", () => {
+    const prog = parse('job q { action /tools/email { template: "welcome" } }');
+    const stage = prog.jobs[0].pipeline[0];
+    expect(stage).toMatchObject({ kind: "action", path: "/tools/email" });
+    if (stage.kind === "action") {
+      expect(stage.params).toEqual({ template: "welcome" });
+    }
+  });
+
+  it("parse `action /path { key: 42 }` → ActionExpression with number param", () => {
+    const prog = parse("job q { action /tools/score { threshold: 42 } }");
+    const stage = prog.jobs[0].pipeline[0];
+    if (stage.kind === "action") {
+      expect(stage.params).toEqual({ threshold: 42 });
+    }
+  });
+
+  it("parse `action /path { a: \"x\", b: 2 }` → ActionExpression with multiple params", () => {
+    const prog = parse('job q { action /tools/x { a: "x", b: 2 } }');
+    const stage = prog.jobs[0].pipeline[0];
+    if (stage.kind === "action") {
+      expect(stage.params).toEqual({ a: "x", b: 2 });
+    }
+  });
+
+  it("parse action in pipeline: find | action | save", () => {
+    const prog = parse("job q { find /data | action /tools/transform | save /out }");
+    const stages = prog.jobs[0].pipeline;
+    expect(stages).toHaveLength(3);
+    expect(stages[0].kind).toBe("find");
+    expect(stages[1]).toMatchObject({ kind: "action", path: "/tools/transform" });
+    expect(stages[2].kind).toBe("save");
+  });
+
+  it("parse action with deep path `/a/b/c/d/e`", () => {
+    const prog = parse("job q { action /a/b/c/d/e }");
+    const stage = prog.jobs[0].pipeline[0];
+    expect(stage).toMatchObject({ kind: "action", path: "/a/b/c/d/e" });
+  });
+
+  // Bad
+  it("`action` without path → syntax error", () => {
+    expect(() => parse("job q { action }")).toThrow();
+  });
+
+  it("`action { }` (missing path) → syntax error", () => {
+    expect(() => parse("job q { action { } }")).toThrow();
+  });
+
+  it("`action /path { key }` (missing colon/value) → syntax error", () => {
+    expect(() => parse("job q { action /path { key } }")).toThrow();
+  });
+
+  it("`action /path { key: }` (missing value) → syntax error", () => {
+    expect(() => parse("job q { action /path { key: } }")).toThrow();
+  });
+
+  // ── Relative actions ──
+
+  it("parse `action turn_off` → relative ActionExpression", () => {
+    const prog = parse("job q { find /ha/lights | action turn_off }");
+    const action = prog.jobs[0].pipeline[1];
+    expect(action).toMatchObject({ kind: "action", path: "turn_off", relative: true });
+  });
+
+  it("parse `action /tesla/.actions/honk` → absolute (no relative flag)", () => {
+    const prog = parse("job q { action /tesla/.actions/honk }");
+    const action = prog.jobs[0].pipeline[0];
+    expect(action).toMatchObject({ kind: "action", path: "/tesla/.actions/honk" });
+    expect((action as any).relative).toBeUndefined();
+  });
+
+  it("parse `action turn_off { brightness: 0 }` → relative with params", () => {
+    const prog = parse("job q { find /ha/lights | action turn_off { brightness: 0 } }");
+    const action = prog.jobs[0].pipeline[1];
+    expect(action).toMatchObject({
+      kind: "action",
+      path: "turn_off",
+      relative: true,
+      params: { brightness: 0 },
+    });
+  });
+
+  // ── json() wrapper for complex params ──
+
+  it("json([...]) array → parsed JS array", () => {
+    const prog = parse('job q { action /tools/run { tools: json([{"path": "/a", "ops": ["read"]}]) } }');
+    const stage = prog.jobs[0].pipeline[0];
+    if (stage.kind === "action") {
+      expect(stage.params).toEqual({ tools: [{ path: "/a", ops: ["read"] }] });
+    }
+  });
+
+  it("json({...}) object → parsed JS object", () => {
+    const prog = parse('job q { action /tools/run { budget: json({"max_rounds": 4}) } }');
+    const stage = prog.jobs[0].pipeline[0];
+    if (stage.kind === "action") {
+      expect(stage.params).toEqual({ budget: { max_rounds: 4 } });
+    }
+  });
+
+  it("json() nested structures → deep structure", () => {
+    const prog = parse('job q { action /tools/run { cfg: json({"a": [1, 2], "b": {"c": true}}) } }');
+    const stage = prog.jobs[0].pipeline[0];
+    if (stage.kind === "action") {
+      expect(stage.params).toEqual({ cfg: { a: [1, 2], b: { c: true } } });
+    }
+  });
+
+  it("mixed primitives + json() → both present", () => {
+    const prog = parse('job q { action /tools/run { a: "str", b: 42, c: json([1, 2]) } }');
+    const stage = prog.jobs[0].pipeline[0];
+    if (stage.kind === "action") {
+      expect(stage.params).toEqual({ a: "str", b: 42, c: [1, 2] });
+    }
+  });
+
+  it("json({}) and json([]) → empty structures", () => {
+    const prog = parse("job q { action /tools/run { a: json({}), b: json([]) } }");
+    const stage = prog.jobs[0].pipeline[0];
+    if (stage.kind === "action") {
+      expect(stage.params).toEqual({ a: {}, b: [] });
+    }
+  });
+
+  it("json() with null and boolean values", () => {
+    const prog = parse('job q { action /tools/run { x: json({"a": null, "b": true, "c": false}) } }');
+    const stage = prog.jobs[0].pipeline[0];
+    if (stage.kind === "action") {
+      expect(stage.params).toEqual({ x: { a: null, b: true, c: false } });
+    }
+  });
+
+  it("unterminated json( → parse error", () => {
+    expect(() => parse('job q { action /tools/run { x: json({"a": 1} } }')).toThrow();
+  });
+
+  it("json() with string values", () => {
+    const prog = parse('job q { action /tools/run { x: json({"name": "hello"}) } }');
+    const stage = prog.jobs[0].pipeline[0];
+    if (stage.kind === "action") {
+      expect(stage.params).toEqual({ x: { name: "hello" } });
+    }
+  });
+});
+
+describe("Phase v3-1: expression parsing", () => {
+  // ── Happy Path ──
+
+  it("parse `map { score: age * 2 }` → MapExpression with BinaryExpr", () => {
+    const prog = parse("job q { map { score: age * 2 } }");
+    const m = prog.jobs[0].pipeline[0];
+    expect(m.kind).toBe("map");
+    if (m.kind === "map") {
+      expect(m.exprMappings).toBeDefined();
+      expect(m.exprMappings!.score).toMatchObject({
+        kind: "binary", op: "*",
+        left: { kind: "field_access", path: "age" },
+        right: { kind: "literal", value: 2 },
+      });
+    }
+  });
+
+  it('parse `map { label: name + " suffix" }` → string concat', () => {
+    const prog = parse('job q { map { label: name + " suffix" } }');
+    const m = prog.jobs[0].pipeline[0];
+    if (m.kind === "map" && m.exprMappings) {
+      expect(m.exprMappings.label).toMatchObject({
+        kind: "binary", op: "+",
+        left: { kind: "field_access", path: "name" },
+        right: { kind: "literal", value: " suffix" },
+      });
+    }
+  });
+
+  it("parse `map { x: a + b * c }` → correct precedence (* before +)", () => {
+    const prog = parse("job q { map { x: a + b * c } }");
+    const m = prog.jobs[0].pipeline[0];
+    if (m.kind === "map" && m.exprMappings) {
+      const expr = m.exprMappings.x;
+      // Should be: a + (b * c)
+      expect(expr.kind).toBe("binary");
+      if (expr.kind === "binary") {
+        expect(expr.op).toBe("+");
+        expect(expr.left).toMatchObject({ kind: "field_access", path: "a" });
+        expect(expr.right).toMatchObject({
+          kind: "binary", op: "*",
+          left: { kind: "field_access", path: "b" },
+          right: { kind: "field_access", path: "c" },
+        });
+      }
+    }
+  });
+
+  it("parse `map { x: (a + b) * c }` → parenthesized override", () => {
+    const prog = parse("job q { map { x: (a + b) * c } }");
+    const m = prog.jobs[0].pipeline[0];
+    if (m.kind === "map" && m.exprMappings) {
+      const expr = m.exprMappings.x;
+      expect(expr.kind).toBe("binary");
+      if (expr.kind === "binary") {
+        expect(expr.op).toBe("*");
+        expect(expr.left).toMatchObject({
+          kind: "binary", op: "+",
+          left: { kind: "field_access", path: "a" },
+          right: { kind: "field_access", path: "b" },
+        });
+        expect(expr.right).toMatchObject({ kind: "field_access", path: "c" });
+      }
+    }
+  });
+
+  it("parse `map { x: $var + 1 }` → variable reference in expression", () => {
+    const prog = parse("let v = 10\njob q { map { x: $v + 1 } }");
+    const m = prog.jobs[0].pipeline[0];
+    if (m.kind === "map" && m.exprMappings) {
+      expect(m.exprMappings.x).toMatchObject({
+        kind: "binary", op: "+",
+        left: { kind: "var_ref", name: "v" },
+        right: { kind: "literal", value: 1 },
+      });
+    }
+  });
+
+  it("parse `map { x: obj.nested.field * 2 }` → dot-notation field", () => {
+    const prog = parse("job q { map { x: obj.nested.field * 2 } }");
+    const m = prog.jobs[0].pipeline[0];
+    if (m.kind === "map" && m.exprMappings) {
+      expect(m.exprMappings.x).toMatchObject({
+        kind: "binary", op: "*",
+        left: { kind: "field_access", path: "obj.nested.field" },
+        right: { kind: "literal", value: 2 },
+      });
+    }
+  });
+
+  it('parse `map name + " " + surname` → single-expression map (no braces)', () => {
+    const prog = parse('job q { map name + " " + surname }');
+    const m = prog.jobs[0].pipeline[0];
+    if (m.kind === "map") {
+      expect(m.expression).toBeDefined();
+      expect(m.expression!.kind).toBe("binary");
+    }
+  });
+
+  it("parse `map { score: raw * 0.8 + bonus, label: name }` → multi-key expression", () => {
+    const prog = parse("job q { map { score: raw * 0.8 + bonus, label: name } }");
+    const m = prog.jobs[0].pipeline[0];
+    if (m.kind === "map" && m.exprMappings) {
+      expect(Object.keys(m.exprMappings)).toEqual(["score", "label"]);
+      expect(m.exprMappings.label).toMatchObject({ kind: "field_access", path: "name" });
+    }
+  });
+
+  // ── Bad Path ──
+
+  it("parse `map { x: foo() }` → function call rejected (LPAREN after field)", () => {
+    // foo() would parse foo as field_access, then ( would be unexpected in map context
+    // The parser would stop at ( and the } check would fail
+    expect(() => parse("job q { map { x: foo() } }")).toThrow();
+  });
+
+  it("parse `map { x: a ? b : c }` → ternary rejected", () => {
+    expect(() => parse("job q { map { x: a ? b : c } }")).toThrow();
+  });
+
+  // ── Edge Cases / Backward Compat ──
+
+  it("backward compat: `map field` still works", () => {
+    const prog = parse("job q { map name }");
+    expect(prog.jobs[0].pipeline[0]).toMatchObject({ kind: "map", field: "name" });
+  });
+
+  it("backward compat: `map { out input }` (no colon) still works", () => {
+    const prog = parse("job q { map { fullName name, dept department } }");
+    const m = prog.jobs[0].pipeline[0];
+    if (m.kind === "map") {
+      expect(m.mappings).toEqual({ fullName: "name", dept: "department" });
+    }
+  });
+
+  it("backward compat: `map user.name` dotted field still works", () => {
+    const prog = parse("job q { map user.name }");
+    expect(prog.jobs[0].pipeline[0]).toMatchObject({ kind: "map", field: "user.name" });
+  });
+
+  it("parse `map { x: 0 }` → literal number expression", () => {
+    const prog = parse("job q { map { x: 0 } }");
+    const m = prog.jobs[0].pipeline[0];
+    if (m.kind === "map" && m.exprMappings) {
+      expect(m.exprMappings.x).toMatchObject({ kind: "literal", value: 0 });
+    }
+  });
+
+  it('parse `map { x: "hello" }` → literal string expression', () => {
+    const prog = parse('job q { map { x: "hello" } }');
+    const m = prog.jobs[0].pipeline[0];
+    if (m.kind === "map" && m.exprMappings) {
+      expect(m.exprMappings.x).toMatchObject({ kind: "literal", value: "hello" });
+    }
+  });
+
+  it("parse `map { x: ((a + b)) }` → nested parens", () => {
+    const prog = parse("job q { map { x: ((a + b)) } }");
+    const m = prog.jobs[0].pipeline[0];
+    if (m.kind === "map" && m.exprMappings) {
+      expect(m.exprMappings.x).toMatchObject({
+        kind: "binary", op: "+",
+        left: { kind: "field_access", path: "a" },
+        right: { kind: "field_access", path: "b" },
+      });
+    }
+  });
+});
+
+describe("Phase v3-2: route parsing", () => {
+  it('parse `route field { "val" -> job target }` basic route', () => {
+    const prog = parse('job main { find /data | route category { "urgent" -> job urgent_handler } }\njob urgent_handler { save /world/urgent }');
+    const stage = prog.jobs[0].pipeline[1];
+    expect(stage.kind).toBe("route");
+    if (stage.kind === "route") {
+      expect(stage.field).toBe("category");
+      expect(stage.branches).toHaveLength(1);
+      expect(stage.branches[0]).toEqual({ value: "urgent", targetJob: "urgent_handler" });
+    }
+  });
+
+  it('parse route with fallback `_ -> job default`', () => {
+    const prog = parse('job main { find /data | route type { "a" -> job handle_a, _ -> job fallback } }\njob handle_a { save /out/a }\njob fallback { save /out/default }');
+    const stage = prog.jobs[0].pipeline[1];
+    if (stage.kind === "route") {
+      expect(stage.branches).toHaveLength(1);
+      expect(stage.fallback).toBe("fallback");
+    }
+  });
+
+  it('parse route with multiple branches', () => {
+    const prog = parse('job main { find /data | route status { "open" -> job handle_open, "closed" -> job handle_closed, _ -> job handle_other } }\njob handle_open { save /out/open }\njob handle_closed { save /out/closed }\njob handle_other { save /out/other }');
+    const stage = prog.jobs[0].pipeline[1];
+    if (stage.kind === "route") {
+      expect(stage.branches).toHaveLength(2);
+      expect(stage.fallback).toBe("handle_other");
+    }
+  });
+
+  it('parse route with nested field `route result.category { ... }`', () => {
+    const prog = parse('job main { find /data | route result.category { "x" -> job handle_x } }\njob handle_x { save /out/x }');
+    const stage = prog.jobs[0].pipeline[1];
+    if (stage.kind === "route") {
+      expect(stage.field).toBe("result.category");
+    }
+  });
+
+  // Bad
+  it("route without field → error", () => {
+    expect(() => parse("job main { route { } }")).toThrow();
+  });
+
+  it("route with empty branches → error", () => {
+    expect(() => parse("job main { route field { } }")).toThrow();
+  });
+
+  it("route branch missing -> → error", () => {
+    expect(() => parse('job main { route field { "val" job target } }')).toThrow();
+  });
+});
+
+describe("Phase 8: count/group-by parsing", () => {
+  it("parse `count` in pipeline", () => {
+    const prog = parse("job q { find /world/x | count }");
+    expect(prog.jobs[0].pipeline[1]).toMatchObject({ kind: "count" });
+  });
+
+  it("parse `group-by field` in pipeline", () => {
+    const prog = parse("job q { find /world/x | group-by dept }");
+    expect(prog.jobs[0].pipeline[1]).toMatchObject({ kind: "group-by", field: "dept" });
+  });
+
+  it("parse `group-by` with dotted field", () => {
+    const prog = parse("job q { find /world/x | group-by user.dept }");
+    const gb = prog.jobs[0].pipeline[1];
+    if (gb.kind === "group-by") {
+      expect(gb.field).toBe("user.dept");
+    }
+  });
+
+  it("count | save pipeline", () => {
+    const prog = parse("job q { find /world/x | count | save /world/out }");
+    expect(prog.jobs[0].pipeline).toHaveLength(3);
+    expect(prog.jobs[0].pipeline[1]).toMatchObject({ kind: "count" });
+    expect(prog.jobs[0].pipeline[2]).toMatchObject({ kind: "save" });
+  });
+
+  it("group-by missing field → error", () => {
+    expect(() => parse("job q { group-by }")).toThrow();
+  });
+
+  it("where | count | save full chain", () => {
+    const prog = parse("job q { find /world/x | where active == true | count | save /world/out }");
+    expect(prog.jobs[0].pipeline).toHaveLength(4);
+  });
+});
+
+describe("Phase v3-2: lookup parsing", () => {
+  it("parses `lookup /data/customers on customer_id`", () => {
+    const prog = parse("job q { find /data/orders | lookup /data/customers on customer_id | save /data/out }");
+    const lookup = prog.jobs[0].pipeline[1];
+    expect(lookup).toMatchObject({ kind: "lookup", path: "/data/customers", joinKey: "customer_id" });
+  });
+
+  it("parses lookup with dotted join key", () => {
+    const prog = parse("job q { find /data/orders | lookup /data/users on meta.user_id | save /out }");
+    const lookup = prog.jobs[0].pipeline[1];
+    expect(lookup).toMatchObject({ kind: "lookup", joinKey: "meta.user_id" });
+  });
+
+  it("lookup without path → syntax error", () => {
+    expect(() => parse("job q { lookup }")).toThrow(/path/i);
+  });
+
+  it("lookup /path without 'on' → syntax error", () => {
+    expect(() => parse("job q { lookup /data/x | save /out }")).toThrow(/on/i);
+  });
+
+  it("lookup in full pipeline: find | lookup | map | save", () => {
+    const prog = parse("job q { find /orders | lookup /customers on cust_id | map name | save /out }");
+    expect(prog.jobs[0].pipeline).toHaveLength(4);
+    expect(prog.jobs[0].pipeline[1]).toMatchObject({ kind: "lookup" });
+  });
+});
+
+describe("Phase v3-2: runtime let parsing", () => {
+  it("parses `let total = find /data | count`", () => {
+    const prog = parse("let total = find /data | count\njob q { find /world/x | save /out }");
+    const letStmt = prog.statements[0];
+    expect(letStmt.kind).toBe("let");
+    expect((letStmt as any).name).toBe("total");
+    expect((letStmt as any).pipeline).toBeDefined();
+    expect((letStmt as any).pipeline).toHaveLength(2);
+    expect((letStmt as any).pipeline[0]).toMatchObject({ kind: "find" });
+    expect((letStmt as any).pipeline[1]).toMatchObject({ kind: "count" });
+  });
+
+  it("static let still works: let x = 42", () => {
+    const prog = parse("let x = 42\njob q { find /data | save /out }");
+    const letStmt = prog.statements[0];
+    expect(letStmt.kind).toBe("let");
+    expect((letStmt as any).pipeline).toBeUndefined();
+    expect((letStmt as any).value).toBe(42);
+  });
+
+  it("runtime let: let count_result = find /data/items | where active == true | count", () => {
+    const prog = parse("let count_result = find /data/items | where active == true | count\njob q { find /data | save /out }");
+    const letStmt = prog.statements[0] as any;
+    expect(letStmt.pipeline).toHaveLength(3);
+  });
+});
+
+describe("Phase v3-3: param parsing", () => {
+  it("parses `param source = /data/users`", () => {
+    const prog = parse("param source = /data/users\njob q { find /data | save /out }");
+    const param = prog.statements[0] as any;
+    expect(param.kind).toBe("param");
+    expect(param.name).toBe("source");
+    expect(param.defaultValue).toBe("/data/users");
+  });
+
+  it("parses `param threshold = 80` numeric default", () => {
+    const prog = parse("param threshold = 80\njob q { find /data | save /out }");
+    expect((prog.statements[0] as any).defaultValue).toBe(80);
+  });
+
+  it('parses `param label = "default"` string default', () => {
+    const prog = parse('param label = "default"\njob q { find /data | save /out }');
+    expect((prog.statements[0] as any).defaultValue).toBe("default");
+  });
+
+  it("multiple params in sequence", () => {
+    const prog = parse('param source = /data/users\nparam threshold = 80\nparam label = "test"\njob q { find /data | save /out }');
+    expect(prog.statements.filter((s: any) => s.kind === "param")).toHaveLength(3);
+  });
+
+  it("param without name → syntax error", () => {
+    expect(() => parse("param = 42")).toThrow(/name/i);
+  });
+
+  it("param without = → syntax error", () => {
+    expect(() => parse("param source 42")).toThrow();
+  });
+
+  it("param with reserved keyword name → syntax error", () => {
+    expect(() => parse("param job = 42")).toThrow(/reserved/i);
+  });
+
+  it("duplicate param name → syntax error", () => {
+    expect(() => parse("param x = 1\nparam x = 2\njob q { find /data }")).toThrow(/[Dd]uplicate param/);
+  });
+
+  it("param name conflicts with prior let → syntax error", () => {
+    expect(() => parse("let x = 1\nparam x = 2\njob q { find /data }")).toThrow(/conflicts/i);
+  });
+
+  it("let name conflicts with prior param → syntax error", () => {
+    expect(() => parse("param x = 1\nlet x = 2\njob q { find /data }")).toThrow(/conflicts/i);
+  });
+
+  it("different param and let names → ok", () => {
+    const prog = parse("param a = 1\nlet b = 2\njob q { find /data }");
+    expect(prog.statements.filter((s: any) => s.kind === "param")).toHaveLength(1);
+    expect(prog.statements.filter((s: any) => s.kind === "let")).toHaveLength(1);
+  });
+});
+
+describe("Phase v3-3: on trigger parsing", () => {
+  it("parses `job handle on /data/inbox:created { find /data/inbox }`", () => {
+    const p = parse("job handle on /data/inbox:created { find /data/inbox }");
+    const job = p.jobs[0];
+    expect(job.name).toBe("handle");
+    expect(job.trigger).toEqual({ kind: "event", path: "/data/inbox", event: "created" });
+    expect(job.pipeline.length).toBe(1);
+    expect(job.pipeline[0].kind).toBe("find");
+  });
+
+  it("parses trigger with deep path: `job sync on /a/b/c/d:updated { find /a/b/c/d }`", () => {
+    const p = parse("job sync on /a/b/c/d:updated { find /a/b/c/d }");
+    const job = p.jobs[0];
+    expect(job.trigger).toEqual({ kind: "event", path: "/a/b/c/d", event: "updated" });
+  });
+
+  it("job without trigger has no trigger field", () => {
+    const p = parse("job plain { find /data }");
+    expect(p.jobs[0].trigger).toBeUndefined();
+  });
+
+  it("multiple jobs with different triggers", () => {
+    const p = parse(`
+      job a on /inbox:created { find /inbox }
+      job b on /outbox:sent { find /outbox }
+    `);
+    expect(p.jobs[0].trigger).toEqual({ kind: "event", path: "/inbox", event: "created" });
+    expect(p.jobs[1].trigger).toEqual({ kind: "event", path: "/outbox", event: "sent" });
+  });
+
+  it("trigger + annotations work together", () => {
+    const p = parse(`
+      @retry(3)
+      job handler on /data:updated { find /data }
+    `);
+    const job = p.jobs[0];
+    expect(job.annotations[0].name).toBe("retry");
+    expect(job.trigger).toEqual({ kind: "event", path: "/data", event: "updated" });
+  });
+
+  it("`job name on` without path → syntax error", () => {
+    expect(() => parse("job handler on { find /data }")).toThrow(/path/i);
+  });
+
+  it("`job name on /path` without :event → syntax error", () => {
+    expect(() => parse("job handler on /data { find /data }")).toThrow(/':event'/i);
+  });
+
+  it("`job name on /path:` without event name → syntax error", () => {
+    expect(() => parse("job handler on /data: { find /data }")).toThrow(/event name/i);
+  });
+
+  it("parses cron trigger: `job ticker on cron(\"*/5 * * * *\") { ... }`", () => {
+    const p = parse('job ticker on cron("*/5 * * * *") { find /metrics | save /snapshots }');
+    const job = p.jobs[0];
+    expect(job.name).toBe("ticker");
+    expect(job.trigger).toEqual({ kind: "cron", expression: "*/5 * * * *" });
+    expect(job.pipeline.length).toBe(2);
+  });
+
+  it("cron trigger with annotations", () => {
+    const p = parse('@caps(read /data/*)\njob poller on cron("0 * * * *") { find /data/status }');
+    const job = p.jobs[0];
+    expect(job.annotations[0].name).toBe("caps");
+    expect(job.trigger).toEqual({ kind: "cron", expression: "0 * * * *" });
+  });
+
+  it("cron trigger missing parens → syntax error", () => {
+    expect(() => parse('job ticker on cron "*/5 * * * *" { find /data }')).toThrow(/'\('/i);
+  });
+
+  it("cron trigger missing expression → syntax error", () => {
+    expect(() => parse("job ticker on cron() { find /data }")).toThrow(/cron expression/i);
+  });
+
+  it("cron trigger missing closing paren → syntax error", () => {
+    expect(() => parse('job ticker on cron("*/5 * * * *" { find /data }')).toThrow(/'\)'/i);
+  });
+
+  it("mixed event and cron triggers in same script", () => {
+    const p = parse(`
+      job handler on /data/inbox:created { find /data/inbox }
+      job ticker on cron("0 */6 * * *") { find /metrics }
+    `);
+    expect(p.jobs[0].trigger).toEqual({ kind: "event", path: "/data/inbox", event: "created" });
+    expect(p.jobs[1].trigger).toEqual({ kind: "cron", expression: "0 */6 * * *" });
+  });
+});
+
+// ── Script-level annotation propagation ──
+
+describe("Script-level annotations propagate to all jobs", () => {
+  it("single-job script — no behavior change", () => {
+    const ast = parse('@caps(exec /api/*)\njob a { action /api/send }');
+    expect(ast.jobs).toHaveLength(1);
+    expect(ast.jobs[0].annotations.some(a => a.name === "caps")).toBe(true);
+  });
+
+  it("multi-job with script-level @caps → both jobs get @caps", () => {
+    const ast = parse('@caps(exec /api/*)\njob a { action /api/send }\njob b { action /api/recv }');
+    expect(ast.jobs).toHaveLength(2);
+    expect(ast.jobs[0].annotations.some(a => a.name === "caps")).toBe(true);
+    expect(ast.jobs[1].annotations.some(a => a.name === "caps")).toBe(true);
+    // Both should have the same args
+    const capsA = ast.jobs[0].annotations.find(a => a.name === "caps")!;
+    const capsB = ast.jobs[1].annotations.find(a => a.name === "caps")!;
+    expect(capsA.args).toEqual(["exec", "/api/*"]);
+    expect(capsB.args).toEqual(["exec", "/api/*"]);
+  });
+
+  it("multi-job with script-level @caps + @budget → both jobs get both", () => {
+    const ast = parse('@caps(exec /api/*)\n@budget(actions 10)\njob a { action /api/x }\njob b { action /api/y }');
+    expect(ast.jobs).toHaveLength(2);
+    for (const job of ast.jobs) {
+      expect(job.annotations.some(a => a.name === "caps")).toBe(true);
+      expect(job.annotations.some(a => a.name === "budget")).toBe(true);
+    }
+  });
+
+  it("second job with own @caps → overrides script-level", () => {
+    const ast = parse('@caps(exec /api/*)\njob a { action /api/x }\n@caps(exec /ha/*)\njob b { action /ha/y }');
+    expect(ast.jobs).toHaveLength(2);
+    const capsA = ast.jobs[0].annotations.find(a => a.name === "caps")!;
+    const capsB = ast.jobs[1].annotations.find(a => a.name === "caps")!;
+    expect(capsA.args).toEqual(["exec", "/api/*"]);
+    expect(capsB.args).toEqual(["exec", "/ha/*"]);
+  });
+
+  it("script-level @caps + job-specific @retry → job gets both", () => {
+    const ast = parse('@caps(exec /api/*)\njob a { action /api/x }\n@retry(3)\njob b { action /api/y }');
+    expect(ast.jobs).toHaveLength(2);
+    // Job b should have inherited @caps + its own @retry
+    const jobB = ast.jobs[1];
+    expect(jobB.annotations.some(a => a.name === "caps")).toBe(true);
+    expect(jobB.annotations.some(a => a.name === "retry")).toBe(true);
+  });
+
+  it("annotations between jobs do NOT become script-level", () => {
+    const ast = parse('job a { output "hi" }\n@caps(exec /api/*)\njob b { action /api/x }');
+    expect(ast.jobs).toHaveLength(2);
+    // Job a has no annotations (no script-level, no job-specific)
+    expect(ast.jobs[0].annotations).toHaveLength(0);
+    // Job b has its own @caps
+    expect(ast.jobs[1].annotations.some(a => a.name === "caps")).toBe(true);
+  });
+
+  it("@readonly before first job stays job-specific (not script-level)", () => {
+    const ast = parse('@readonly\njob safe { find /data }\njob writer { action /api/send }');
+    expect(ast.jobs).toHaveLength(2);
+    // @readonly only on first job
+    expect(ast.jobs[0].annotations.some(a => a.name === "readonly")).toBe(true);
+    expect(ast.jobs[1].annotations.some(a => a.name === "readonly")).toBe(false);
+  });
+
+  it("@readonly + script-level @caps → @readonly on first job, @caps on both", () => {
+    const ast = parse('@caps(exec /api/*)\n@readonly\njob safe { find /data }\njob writer { action /api/send }');
+    expect(ast.jobs).toHaveLength(2);
+    // @caps on both (script-level)
+    expect(ast.jobs[0].annotations.some(a => a.name === "caps")).toBe(true);
+    expect(ast.jobs[1].annotations.some(a => a.name === "caps")).toBe(true);
+    // @readonly only on first job
+    expect(ast.jobs[0].annotations.some(a => a.name === "readonly")).toBe(true);
+    expect(ast.jobs[1].annotations.some(a => a.name === "readonly")).toBe(false);
+  });
+});