nonbinary.computer
OR-1 dataflow CPU sketch
1# Macro Enhancements — Test Requirements
2
3Maps each enhancement from `docs/macro-enhancements.md` to specific automated test cases.
4
5Slug: `macro-enh`
6
7---
8
9## Enhancement 1: Opcode Parameters
10
11### macro-enh.E1.1: Grammar accepts `param_ref` in opcode position
12
13- **E1.1a Success:** `&r <| ${op}` parses without error inside a macro body
14- **E1.1b Success:** `${op} &src |> &dst` (strong_edge with param opcode) parses
15- **E1.1c Success:** `&dst ${op} <| &src` (weak_edge with param opcode) parses
16- **Test type:** Unit (parse + lower)
17- **File:** `tests/test_opcode_params.py`
18
19### macro-enh.E1.2: Lower pass stores ParamRef in IRNode.opcode
20
21- **E1.2a Success:** After lowering a macro body with `${op}`, the IRNode has `opcode` as `ParamRef(param="op")`
22- **E1.2b Success:** Anonymous nodes from strong/weak edges with `${op}` also have ParamRef opcode
23- **Test type:** Unit (lower)
24- **File:** `tests/test_opcode_params.py`
25
26### macro-enh.E1.3: OPCODE accepted as positional macro argument
27
28- **E1.3a Success:** `#reduce_2 add` parses — bare `add` in macro call argument position is accepted
29- **E1.3b Success:** Lower pass wraps the OPCODE token as a string `"add"` in `IRMacroCall.positional_args`
30- **Test type:** Unit (parse + lower)
31- **File:** `tests/test_opcode_params.py`
32
33### macro-enh.E1.4: Expand pass resolves opcode ParamRef
34
35- **E1.4a Success:** Macro `#wrap op |> { &n <| ${op} }` invoked as `#wrap add` produces node with `opcode=ArithOp.ADD`
36- **E1.4b Success:** Macro invoked with `sub`, `gate`, `read` (different op types) all resolve correctly
37- **E1.4c Failure:** Macro invoked with `#wrap banana` produces MACRO error — invalid opcode mnemonic
38- **E1.4d Failure:** Macro invoked with `#wrap 42` (numeric, not opcode) produces MACRO error
39- **Test type:** Unit (expand)
40- **File:** `tests/test_opcode_params.py`
41
42### macro-enh.E1.5: Full pipeline with opcode params
43
44- **E1.5a Success:** `#reduce_2 op |> { &r <| ${op} }` + `#reduce_2 add` assembles through full pipeline (parse → lower → expand → resolve → place → allocate → codegen)
45- **E1.5b Success:** Output PEConfig has correct ALUInst with ArithOp.ADD
46- **Test type:** Integration (full pipeline via `assemble()`)
47- **File:** `tests/test_opcode_params.py`
48
49---
50
51## Enhancement 2: Parameterized Placement and Port Qualifiers
52
53### macro-enh.E2.1: Grammar accepts `param_ref` in placement position
54
55- **E2.1a Success:** `&n <| add |${pe}` parses inside macro body
56- **E2.1b Success:** Lower pass returns `ParamRef` (wrapped as `PlacementRef`) from placement handler
57- **Test type:** Unit (parse + lower)
58- **File:** `tests/test_qualified_ref_params.py`
59
60### macro-enh.E2.2: Grammar accepts `param_ref` in port position
61
62- **E2.2a Success:** `&src |> &dst:${port}` parses inside macro body
63- **E2.2b Success:** Lower pass returns `ParamRef` (wrapped as `PortRef`) from port handler
64- **Test type:** Unit (parse + lower)
65- **File:** `tests/test_qualified_ref_params.py`
66
67### macro-enh.E2.3: Context slot bracket syntax parses
68
69- **E2.3a Success:** `&node[2]` parses (literal context slot)
70- **E2.3b Success:** `&node|pe0[2]:L` parses (full qualifier chain)
71- **E2.3c Success:** `&node[${ctx}]` parses (parameterized context slot)
72- **E2.3d Success:** `&node[0..4]` parses (range reservation)
73- **Test type:** Unit (parse + lower)
74- **File:** `tests/test_qualified_ref_params.py`
75
76### macro-enh.E2.4: Expand pass resolves placement ParamRef
77
78- **E2.4a Success:** Macro with `|${pe}` invoked with `pe0` places node on PE 0
79- **E2.4b Success:** Macro with `|${pe}` invoked with `pe1` places node on PE 1
80- **E2.4c Failure:** Macro invoked with `|${pe}` where arg is `"banana"` produces MACRO error
81- **Test type:** Unit (expand)
82- **File:** `tests/test_qualified_ref_params.py`
83
84### macro-enh.E2.5: Expand pass resolves port ParamRef
85
86- **E2.5a Success:** Macro with `:${port}` invoked with `L` resolves to `Port.L`
87- **E2.5b Success:** Macro with `:${port}` invoked with `R` resolves to `Port.R`
88- **E2.5c Failure:** Macro invoked with invalid port value produces MACRO error
89- **Test type:** Unit (expand)
90- **File:** `tests/test_qualified_ref_params.py`
91
92### macro-enh.E2.6: Expand pass resolves context slot ParamRef
93
94- **E2.6a Success:** Macro with `[${ctx}]` invoked with `2` resolves to ctx slot 2
95- **E2.6b Failure:** Non-numeric ctx slot value produces MACRO error
96- **Test type:** Unit (expand)
97- **File:** `tests/test_qualified_ref_params.py`
98
99### macro-enh.E2.7: Full pipeline with placement/port params
100
101- **E2.7a Success:** Macro parameterizing PE placement assembles through full pipeline; node placed on correct PE
102- **E2.7b Success:** Macro parameterizing port assembles through full pipeline; edge targets correct port
103- **Test type:** Integration (full pipeline)
104- **File:** `tests/test_qualified_ref_params.py`
105
106---
107
108## Enhancement 3: @ret Wiring for Macros
109
110### macro-enh.E3.1: Grammar accepts output list on macro_call_stmt
111
112- **E3.1a Success:** `#macro args |> &dest` parses
113- **E3.1b Success:** `#macro args |> name=&dest` parses (named output)
114- **E3.1c Success:** `#macro args |> &a, &b` parses (multiple outputs)
115- **E3.1d Success:** `#macro args |> name1=&a, name2=&b` parses (multiple named outputs)
116- **Test type:** Unit (parse + lower)
117- **File:** `tests/test_macro_ret_wiring.py`
118
119### macro-enh.E3.2: Lower pass stores output_dests on IRMacroCall
120
121- **E3.2a Success:** `IRMacroCall.output_dests` contains positional output refs
122- **E3.2b Success:** `IRMacroCall.output_dests` contains named output refs (name, ref) tuples
123- **Test type:** Unit (lower)
124- **File:** `tests/test_macro_ret_wiring.py`
125
126### macro-enh.E3.3: Expand pass rewrites @ret edges
127
128- **E3.3a Success:** Macro body edge `&src |> @ret` becomes `&src |> &actual_dest` after expansion
129- **E3.3b Success:** Named `@ret_body` maps to `body=&dest` in call site output
130- **E3.3c Success:** Multiple @ret variants (e.g., `@ret_body` + `@ret_exit`) each map to their named outputs
131- **E3.3d Failure:** `@ret_body` in macro body but call site has no `body=` output → MACRO error
132- **E3.3e Failure:** Macro body has `@ret` but call site provides zero outputs → MACRO error
133- **E3.3f Success:** Positional @ret maps to first positional output
134- **Test type:** Unit (expand)
135- **File:** `tests/test_macro_ret_wiring.py`
136
137### macro-enh.E3.4: @ret port preservation
138
139- **E3.4a Success:** `&src |> @ret:R` rewrites to `&src |> &dest:R` — port on @ret is preserved
140- **E3.4b Success:** `&src |> @ret_exit:R` also preserves port
141- **Test type:** Unit (expand)
142- **File:** `tests/test_macro_ret_wiring.py`
143
144### macro-enh.E3.5: Nested macro @ret scoping
145
146- **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
147- **Test type:** Unit (expand)
148- **File:** `tests/test_macro_ret_wiring.py`
149
150### macro-enh.E3.6: Full pipeline with @ret macros
151
152- **E3.6a Success:** Macro with @ret + call site output list assembles through full pipeline
153- **E3.6b Success:** Generated edges connect expanded macro internals to call-site-specified destinations
154- **Test type:** Integration (full pipeline)
155- **File:** `tests/test_macro_ret_wiring.py`
156
157---
158
159## Enhancement 4: Built-in Macro Rewrite
160
161### macro-enh.E4.1: New builtins use opcode params
162
163- **E4.1a Success:** `#reduce_2 add` expands correctly (single node with ArithOp.ADD)
164- **E4.1b Success:** `#reduce_3 sub` expands correctly (two nodes with ArithOp.SUB, wired)
165- **E4.1c Success:** `#reduce_4 add` expands correctly (three nodes, tree structure)
166- **Test type:** Unit (expand)
167- **File:** `tests/test_builtins.py`
168
169### macro-enh.E4.2: New builtins use @ret wiring
170
171- **E4.2a Success:** `#loop_counted |> body=&proc, exit=&done` wires @ret_body → &proc, @ret_exit → &done
172- **E4.2b Success:** `#loop_while |> body=&proc, exit=&done` wires similarly
173- **Test type:** Unit (expand)
174- **File:** `tests/test_builtins.py`
175
176### macro-enh.E4.3: Backwards compatibility
177
178- **E4.3a:** Old macro names that are removed are documented in CHANGELOG or similar
179- **Test type:** Manual verification (pre-1.0, acceptable breakage)
180
181### macro-enh.E4.4: Full pipeline with new builtins
182
183- **E4.4a Success:** Program using `#loop_counted |> body=&body, exit=&done` + `#reduce_2 add` assembles through full pipeline
184- **Test type:** Integration (full pipeline)
185- **File:** `tests/test_builtins.py`
186
187---
188
189## Human Verification
190
191### macro-enh.HV1: dfgraph renders programs using new macros
192- Verify that dfgraph correctly visualises programs using opcode params, @ret wiring
193- **Justification:** Graph rendering depends on pipeline output; visual verification needed
194
195### macro-enh.HV2: Error messages are useful
196- Verify that error messages for invalid opcode params, mismatched @ret, etc. include actionable context (macro name, line, suggestions)
197- **Justification:** Error message quality is subjective; automated tests check presence but not clarity