|
| 1 | +// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license. |
| 2 | + |
| 3 | +/** |
| 4 | + * Nested control-flow composition (ADR-0031) — interactions the single-construct |
| 5 | + * tests don't exercise: a `parallel` block inside a `loop` body, a `loop` inside |
| 6 | + * a `try_catch` try region. Asserts the three things that only break when |
| 7 | + * constructs are nested: |
| 8 | + * 1. variable scope flows INTO nested regions (the loop iterator is visible to |
| 9 | + * a node inside a nested parallel branch); |
| 10 | + * 2. mutations inside a nested region propagate OUT to the enclosing scope; |
| 11 | + * 3. step-log folding tags each step with its INNERMOST container |
| 12 | + * (parentNodeId / regionKind), and the after-block continuation runs once. |
| 13 | + */ |
| 14 | + |
| 15 | +import { describe, it, expect, beforeEach } from 'vitest'; |
| 16 | +import { AutomationEngine } from '../engine.js'; |
| 17 | +import type { NodeExecutor } from '../engine.js'; |
| 18 | +import { registerLoopNode } from './loop-node.js'; |
| 19 | +import { registerParallelNode } from './parallel-node.js'; |
| 20 | +import { registerTryCatchNode } from './try-catch-node.js'; |
| 21 | + |
| 22 | +function silentLogger() { |
| 23 | + return { info() {}, warn() {}, error() {}, debug() {}, child() { return silentLogger(); } } as any; |
| 24 | +} |
| 25 | +function ctx() { |
| 26 | + return { logger: silentLogger(), getService() { throw new Error('none'); } } as any; |
| 27 | +} |
| 28 | + |
| 29 | +describe('nested control-flow composition (ADR-0031)', () => { |
| 30 | + let engine: AutomationEngine; |
| 31 | + let collected: Array<{ tag: string; cur: unknown }>; |
| 32 | + |
| 33 | + beforeEach(() => { |
| 34 | + engine = new AutomationEngine(silentLogger()); |
| 35 | + collected = []; |
| 36 | + registerLoopNode(engine, ctx()); |
| 37 | + registerParallelNode(engine, ctx()); |
| 38 | + registerTryCatchNode(engine, ctx()); |
| 39 | + |
| 40 | + // Leaf: records the tag + the loop iterator value it can see (proves scope |
| 41 | + // flows into the nested region), and mutates an enclosing-scope variable. |
| 42 | + engine.registerNodeExecutor({ |
| 43 | + type: 'collect', |
| 44 | + async execute(node, variables) { |
| 45 | + const tag = String((node.config as any)?.tag ?? 'leaf'); |
| 46 | + const cur = variables.get('cur'); |
| 47 | + collected.push({ tag, cur }); |
| 48 | + variables.set('lastSeen', `${cur}:${tag}`); |
| 49 | + return { success: true }; |
| 50 | + }, |
| 51 | + } as NodeExecutor); |
| 52 | + // A node after the outer container, to prove the after-block continuation. |
| 53 | + engine.registerNodeExecutor({ |
| 54 | + type: 'after', |
| 55 | + async execute(_n, variables) { |
| 56 | + variables.set('afterRan', true); |
| 57 | + return { success: true }; |
| 58 | + }, |
| 59 | + } as NodeExecutor); |
| 60 | + }); |
| 61 | + |
| 62 | + it('parallel INSIDE loop: iterator visible in branches, mutations propagate, steps fold to innermost', async () => { |
| 63 | + engine.registerFlow('nested', { |
| 64 | + name: 'nested', label: 'Nested', type: 'autolaunched', |
| 65 | + variables: [{ name: 'items', type: 'list', isInput: true }], |
| 66 | + nodes: [ |
| 67 | + { id: 's', type: 'start', label: 'Start' }, |
| 68 | + { |
| 69 | + id: 'outer_loop', type: 'loop', label: 'For each', |
| 70 | + config: { |
| 71 | + collection: '{items}', iteratorVariable: 'cur', |
| 72 | + body: { |
| 73 | + nodes: [{ |
| 74 | + id: 'inner_par', type: 'parallel', label: 'Fan', |
| 75 | + config: { |
| 76 | + branches: [ |
| 77 | + { name: 'A', nodes: [{ id: 'leafA', type: 'collect', label: 'A', config: { tag: 'A' } }], edges: [] }, |
| 78 | + { name: 'B', nodes: [{ id: 'leafB', type: 'collect', label: 'B', config: { tag: 'B' } }], edges: [] }, |
| 79 | + ], |
| 80 | + }, |
| 81 | + }], |
| 82 | + edges: [], |
| 83 | + }, |
| 84 | + }, |
| 85 | + }, |
| 86 | + { id: 'aft', type: 'after', label: 'After' }, |
| 87 | + { id: 'e', type: 'end', label: 'End' }, |
| 88 | + ], |
| 89 | + edges: [ |
| 90 | + { id: 'e1', source: 's', target: 'outer_loop' }, |
| 91 | + { id: 'e2', source: 'outer_loop', target: 'aft' }, |
| 92 | + { id: 'e3', source: 'aft', target: 'e' }, |
| 93 | + ], |
| 94 | + } as never); |
| 95 | + |
| 96 | + const result = await engine.execute('nested', { params: { items: ['x', 'y'] } }); |
| 97 | + expect(result.success).toBe(true); |
| 98 | + |
| 99 | + // 1. Scope flows in: every leaf saw the right loop iterator value. |
| 100 | + const seen = collected.map(c => `${c.cur}:${c.tag}`).sort(); |
| 101 | + expect(seen).toEqual(['x:A', 'x:B', 'y:A', 'y:B']); |
| 102 | + |
| 103 | + // 3. Step folding: a leaf's INNERMOST container is the parallel block; the |
| 104 | + // parallel block's own container is the loop body. |
| 105 | + const steps = (await engine.listRuns('nested'))[0].steps; |
| 106 | + const leafStep = steps.find(s => s.nodeId === 'leafA'); |
| 107 | + expect(leafStep?.parentNodeId).toBe('inner_par'); |
| 108 | + expect(leafStep?.regionKind).toBe('parallel-branch'); |
| 109 | + const parStep = steps.find(s => s.nodeId === 'inner_par'); |
| 110 | + expect(parStep?.parentNodeId).toBe('outer_loop'); |
| 111 | + expect(parStep?.regionKind).toBe('loop-body'); |
| 112 | + |
| 113 | + // after-block continuation ran exactly once. |
| 114 | + expect(steps.filter(s => s.nodeId === 'aft')).toHaveLength(1); |
| 115 | + }); |
| 116 | + |
| 117 | + it('loop INSIDE try_catch: deepest step folds to the loop, loop folds to the try region', async () => { |
| 118 | + engine.registerFlow('tc_nested', { |
| 119 | + name: 'tc_nested', label: 'TC Nested', type: 'autolaunched', |
| 120 | + variables: [{ name: 'items', type: 'list', isInput: true }], |
| 121 | + nodes: [ |
| 122 | + { id: 's', type: 'start', label: 'Start' }, |
| 123 | + { |
| 124 | + id: 'guard', type: 'try_catch', label: 'Guard', |
| 125 | + config: { |
| 126 | + try: { |
| 127 | + nodes: [{ |
| 128 | + id: 'tc_loop', type: 'loop', label: 'Loop', |
| 129 | + config: { |
| 130 | + collection: '{items}', iteratorVariable: 'cur', |
| 131 | + body: { nodes: [{ id: 'leaf', type: 'collect', label: 'L', config: { tag: 'L' } }], edges: [] }, |
| 132 | + }, |
| 133 | + }], |
| 134 | + edges: [], |
| 135 | + }, |
| 136 | + }, |
| 137 | + }, |
| 138 | + { id: 'aft', type: 'after', label: 'After' }, |
| 139 | + { id: 'e', type: 'end', label: 'End' }, |
| 140 | + ], |
| 141 | + edges: [ |
| 142 | + { id: 'e1', source: 's', target: 'guard' }, |
| 143 | + { id: 'e2', source: 'guard', target: 'aft' }, |
| 144 | + { id: 'e3', source: 'aft', target: 'e' }, |
| 145 | + ], |
| 146 | + } as never); |
| 147 | + |
| 148 | + const result = await engine.execute('tc_nested', { params: { items: ['p', 'q'] } }); |
| 149 | + expect(result.success).toBe(true); |
| 150 | + expect(collected.map(c => `${c.cur}:${c.tag}`).sort()).toEqual(['p:L', 'q:L']); |
| 151 | + |
| 152 | + const steps = (await engine.listRuns('tc_nested'))[0].steps; |
| 153 | + const leafStep = steps.find(s => s.nodeId === 'leaf'); |
| 154 | + expect(leafStep?.parentNodeId).toBe('tc_loop'); // innermost = the loop body |
| 155 | + expect(leafStep?.regionKind).toBe('loop-body'); |
| 156 | + const loopStep = steps.find(s => s.nodeId === 'tc_loop'); |
| 157 | + expect(loopStep?.parentNodeId).toBe('guard'); // loop sits in the try region |
| 158 | + expect(loopStep?.regionKind).toBe('try'); |
| 159 | + }); |
| 160 | + |
| 161 | + it('a mutation made deep inside nested regions is visible to the after-block (enclosing scope)', async () => { |
| 162 | + engine.registerFlow('scope', { |
| 163 | + name: 'scope', label: 'Scope', type: 'autolaunched', |
| 164 | + variables: [{ name: 'items', type: 'list', isInput: true }, { name: 'lastSeen', type: 'text', isOutput: true }], |
| 165 | + nodes: [ |
| 166 | + { id: 's', type: 'start', label: 'Start' }, |
| 167 | + { |
| 168 | + id: 'outer_loop', type: 'loop', label: 'For each', |
| 169 | + config: { |
| 170 | + collection: '{items}', iteratorVariable: 'cur', |
| 171 | + body: { nodes: [{ id: 'leaf', type: 'collect', label: 'Z', config: { tag: 'Z' } }], edges: [] }, |
| 172 | + }, |
| 173 | + }, |
| 174 | + { id: 'e', type: 'end', label: 'End' }, |
| 175 | + ], |
| 176 | + edges: [ |
| 177 | + { id: 'e1', source: 's', target: 'outer_loop' }, |
| 178 | + { id: 'e2', source: 'outer_loop', target: 'e' }, |
| 179 | + ], |
| 180 | + } as never); |
| 181 | + |
| 182 | + const result = await engine.execute('scope', { params: { items: ['m', 'n'] } }); |
| 183 | + expect(result.success).toBe(true); |
| 184 | + // The loop body's mutation of `lastSeen` survived to the flow output — the |
| 185 | + // region ran in the enclosing scope, last iteration wins. |
| 186 | + expect(result.output?.lastSeen).toBe('n:Z'); |
| 187 | + }); |
| 188 | +}); |
0 commit comments