# Macro Enhancements — Test Requirements

Maps each enhancement from `docs/macro-enhancements.md` to specific automated test cases.

Slug: `macro-enh`

---

## Enhancement 1: Opcode Parameters

### macro-enh.E1.1: Grammar accepts `param_ref` in opcode position

- **E1.1a Success:** `&r <| ${op}` parses without error inside a macro body
- **E1.1b Success:** `${op} &src |> &dst` (strong_edge with param opcode) parses
- **E1.1c Success:** `&dst ${op} <| &src` (weak_edge with param opcode) parses
- **Test type:** Unit (parse + lower)
- **File:** `tests/test_opcode_params.py`

### macro-enh.E1.2: Lower pass stores ParamRef in IRNode.opcode

- **E1.2a Success:** After lowering a macro body with `${op}`, the IRNode has `opcode` as `ParamRef(param="op")`
- **E1.2b Success:** Anonymous nodes from strong/weak edges with `${op}` also have ParamRef opcode
- **Test type:** Unit (lower)
- **File:** `tests/test_opcode_params.py`

### macro-enh.E1.3: OPCODE accepted as positional macro argument

- **E1.3a Success:** `#reduce_2 add` parses — bare `add` in macro call argument position is accepted
- **E1.3b Success:** Lower pass wraps the OPCODE token as a string `"add"` in `IRMacroCall.positional_args`
- **Test type:** Unit (parse + lower)
- **File:** `tests/test_opcode_params.py`

### macro-enh.E1.4: Expand pass resolves opcode ParamRef

- **E1.4a Success:** Macro `#wrap op |> { &n <| ${op} }` invoked as `#wrap add` produces node with `opcode=ArithOp.ADD`
- **E1.4b Success:** Macro invoked with `sub`, `gate`, `read` (different op types) all resolve correctly
- **E1.4c Failure:** Macro invoked with `#wrap banana` produces MACRO error — invalid opcode mnemonic
- **E1.4d Failure:** Macro invoked with `#wrap 42` (numeric, not opcode) produces MACRO error
- **Test type:** Unit (expand)
- **File:** `tests/test_opcode_params.py`

### macro-enh.E1.5: Full pipeline with opcode params

- **E1.5a Success:** `#reduce_2 op |> { &r <| ${op} }` + `#reduce_2 add` assembles through full pipeline (parse → lower → expand → resolve → place → allocate → codegen)
- **E1.5b Success:** Output PEConfig has correct ALUInst with ArithOp.ADD
- **Test type:** Integration (full pipeline via `assemble()`)
- **File:** `tests/test_opcode_params.py`

---

## Enhancement 2: Parameterized Placement and Port Qualifiers

### macro-enh.E2.1: Grammar accepts `param_ref` in placement position

- **E2.1a Success:** `&n <| add |${pe}` parses inside macro body
- **E2.1b Success:** Lower pass returns `ParamRef` (wrapped as `PlacementRef`) from placement handler
- **Test type:** Unit (parse + lower)
- **File:** `tests/test_qualified_ref_params.py`

### macro-enh.E2.2: Grammar accepts `param_ref` in port position

- **E2.2a Success:** `&src |> &dst:${port}` parses inside macro body
- **E2.2b Success:** Lower pass returns `ParamRef` (wrapped as `PortRef`) from port handler
- **Test type:** Unit (parse + lower)
- **File:** `tests/test_qualified_ref_params.py`

### macro-enh.E2.3: Context slot bracket syntax parses

- **E2.3a Success:** `&node[2]` parses (literal context slot)
- **E2.3b Success:** `&node|pe0[2]:L` parses (full qualifier chain)
- **E2.3c Success:** `&node[${ctx}]` parses (parameterized context slot)
- **E2.3d Success:** `&node[0..4]` parses (range reservation)
- **Test type:** Unit (parse + lower)
- **File:** `tests/test_qualified_ref_params.py`

### macro-enh.E2.4: Expand pass resolves placement ParamRef

- **E2.4a Success:** Macro with `|${pe}` invoked with `pe0` places node on PE 0
- **E2.4b Success:** Macro with `|${pe}` invoked with `pe1` places node on PE 1
- **E2.4c Failure:** Macro invoked with `|${pe}` where arg is `"banana"` produces MACRO error
- **Test type:** Unit (expand)
- **File:** `tests/test_qualified_ref_params.py`

### macro-enh.E2.5: Expand pass resolves port ParamRef

- **E2.5a Success:** Macro with `:${port}` invoked with `L` resolves to `Port.L`
- **E2.5b Success:** Macro with `:${port}` invoked with `R` resolves to `Port.R`
- **E2.5c Failure:** Macro invoked with invalid port value produces MACRO error
- **Test type:** Unit (expand)
- **File:** `tests/test_qualified_ref_params.py`

### macro-enh.E2.6: Expand pass resolves context slot ParamRef

- **E2.6a Success:** Macro with `[${ctx}]` invoked with `2` resolves to ctx slot 2
- **E2.6b Failure:** Non-numeric ctx slot value produces MACRO error
- **Test type:** Unit (expand)
- **File:** `tests/test_qualified_ref_params.py`

### macro-enh.E2.7: Full pipeline with placement/port params

- **E2.7a Success:** Macro parameterizing PE placement assembles through full pipeline; node placed on correct PE
- **E2.7b Success:** Macro parameterizing port assembles through full pipeline; edge targets correct port
- **Test type:** Integration (full pipeline)
- **File:** `tests/test_qualified_ref_params.py`

---

## Enhancement 3: @ret Wiring for Macros

### macro-enh.E3.1: Grammar accepts output list on macro_call_stmt

- **E3.1a Success:** `#macro args |> &dest` parses
- **E3.1b Success:** `#macro args |> name=&dest` parses (named output)
- **E3.1c Success:** `#macro args |> &a, &b` parses (multiple outputs)
- **E3.1d Success:** `#macro args |> name1=&a, name2=&b` parses (multiple named outputs)
- **Test type:** Unit (parse + lower)
- **File:** `tests/test_macro_ret_wiring.py`

### macro-enh.E3.2: Lower pass stores output_dests on IRMacroCall

- **E3.2a Success:** `IRMacroCall.output_dests` contains positional output refs
- **E3.2b Success:** `IRMacroCall.output_dests` contains named output refs (name, ref) tuples
- **Test type:** Unit (lower)
- **File:** `tests/test_macro_ret_wiring.py`

### macro-enh.E3.3: Expand pass rewrites @ret edges

- **E3.3a Success:** Macro body edge `&src |> @ret` becomes `&src |> &actual_dest` after expansion
- **E3.3b Success:** Named `@ret_body` maps to `body=&dest` in call site output
- **E3.3c Success:** Multiple @ret variants (e.g., `@ret_body` + `@ret_exit`) each map to their named outputs
- **E3.3d Failure:** `@ret_body` in macro body but call site has no `body=` output → MACRO error
- **E3.3e Failure:** Macro body has `@ret` but call site provides zero outputs → MACRO error
- **E3.3f Success:** Positional @ret maps to first positional output
- **Test type:** Unit (expand)
- **File:** `tests/test_macro_ret_wiring.py`

### macro-enh.E3.4: @ret port preservation

- **E3.4a Success:** `&src |> @ret:R` rewrites to `&src |> &dest:R` — port on @ret is preserved
- **E3.4b Success:** `&src |> @ret_exit:R` also preserves port
- **Test type:** Unit (expand)
- **File:** `tests/test_macro_ret_wiring.py`

### macro-enh.E3.5: Nested macro @ret scoping

- **E3.5a Success:** Macro A calls macro B which has @ret; B's @ret resolves at B's call site (inside A's body), A's @ret resolves at A's call site
- **Test type:** Unit (expand)
- **File:** `tests/test_macro_ret_wiring.py`

### macro-enh.E3.6: Full pipeline with @ret macros

- **E3.6a Success:** Macro with @ret + call site output list assembles through full pipeline
- **E3.6b Success:** Generated edges connect expanded macro internals to call-site-specified destinations
- **Test type:** Integration (full pipeline)
- **File:** `tests/test_macro_ret_wiring.py`

---

## Enhancement 4: Built-in Macro Rewrite

### macro-enh.E4.1: New builtins use opcode params

- **E4.1a Success:** `#reduce_2 add` expands correctly (single node with ArithOp.ADD)
- **E4.1b Success:** `#reduce_3 sub` expands correctly (two nodes with ArithOp.SUB, wired)
- **E4.1c Success:** `#reduce_4 add` expands correctly (three nodes, tree structure)
- **Test type:** Unit (expand)
- **File:** `tests/test_builtins.py`

### macro-enh.E4.2: New builtins use @ret wiring

- **E4.2a Success:** `#loop_counted |> body=&proc, exit=&done` wires @ret_body → &proc, @ret_exit → &done
- **E4.2b Success:** `#loop_while |> body=&proc, exit=&done` wires similarly
- **Test type:** Unit (expand)
- **File:** `tests/test_builtins.py`

### macro-enh.E4.3: Backwards compatibility

- **E4.3a:** Old macro names that are removed are documented in CHANGELOG or similar
- **Test type:** Manual verification (pre-1.0, acceptable breakage)

### macro-enh.E4.4: Full pipeline with new builtins

- **E4.4a Success:** Program using `#loop_counted |> body=&body, exit=&done` + `#reduce_2 add` assembles through full pipeline
- **Test type:** Integration (full pipeline)
- **File:** `tests/test_builtins.py`

---

## Human Verification

### macro-enh.HV1: dfgraph renders programs using new macros
- Verify that dfgraph correctly visualises programs using opcode params, @ret wiring
- **Justification:** Graph rendering depends on pipeline output; visual verification needed

### macro-enh.HV2: Error messages are useful
- Verify that error messages for invalid opcode params, mismatched @ret, etc. include actionable context (macro name, line, suggestions)
- **Justification:** Error message quality is subjective; automated tests check presence but not clarity