callman-core 1.17.0 → 1.18.0

package/dist/scenario-runner/runScenario.js

@@ -1,7 +1,7 @@
 import { buildConditionOutputPayload, evaluateConditionConfig, evaluateConditionRule, resolveConditionRuntimeValue, validateConditionConfig, } from "./condition.js";
 import { applyExtract } from "./extraction.js";
 import { evaluateAssertionConfig, validateAssertionConfig, } from "./assertion.js";
-import { createSubScenarioStepId, buildRuntimeStepDescriptors, DEFAULT_END_LOOP_DELAY_MS, DEFAULT_END_LOOP_ITERATIONS, flattenScenarioNodesForContext, MAX_END_LOOP_ITERATIONS, DEFAULT_POLL_INTERVAL_MS, DEFAULT_POLL_MAX_ATTEMPTS, MAX_POLL_ATTEMPTS, } from "./graphTraversal.js";
+import { createSubScenarioStepId, buildRuntimeStepDescriptors, DEFAULT_END_LOOP_DELAY_MS, DEFAULT_END_LOOP_ITERATIONS, flattenScenarioNodesForContext, MAX_END_LOOP_ITERATIONS, DEFAULT_POLL_INTERVAL_MS, DEFAULT_POLL_MAX_ATTEMPTS, MAX_POLL_ATTEMPTS, DEFAULT_FOREACH_MAX_ITERATIONS, MAX_FOREACH_ITERATIONS, } from "./graphTraversal.js";
 import { executeWithScenarioNodePolicy } from "./executionPolicyRunner.js";
 import { getLegacyScenarioNodeExecutionPolicy, getScenarioNodeExecutionPolicy, supportsScenarioNodeExecutionPolicy, } from "./nodePolicy.js";
 import { buildScenarioExecutionGraph, buildScenarioTemplateValues, collectExclusiveBranchNodeIds, evaluateScenarioExpression, resolveScenarioJsonTemplateString, resolveScenarioTemplateString, } from "./templateResolver.js";
@@ -33,9 +33,18 @@ const buildTitle = (node) => {
     return `${node.type[0]?.toUpperCase() ?? ""}${node.type.slice(1)}`;
 };
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-// `loop`/`loops` are the loop-iteration template roots (see the loop-frame
+// `loop`/`loops` are the loop-iteration template roots and `item`/`each`/
+// `eaches` the foreach-iteration ones (see the loop-frame and foreach
 // machinery in runScenario) — node labels must not shadow them.
-const RESERVED_WORKFLOW_ROOT_LABELS = new Set(["workflow", "__meta", "loop", "loops"]);
+const RESERVED_WORKFLOW_ROOT_LABELS = new Set([
+    "workflow",
+    "__meta",
+    "loop",
+    "loops",
+    "item",
+    "each",
+    "eaches",
+]);
 const cloneNodeExecutionMeta = (meta) => ({
     ...meta,
     ...(meta.error ? { error: { ...meta.error } } : {}),
@@ -413,6 +422,18 @@ const updateRecordFromEvent = (records, event) => {
         });
         return;
     }
+    if (event.type === "step:iteration") {
+        // Iteration progress marker only — the terminal success/fail event owns
+        // the record. Without this early return the generic fallback below would
+        // stamp status:"failed" on the foreach step.
+        records.set(event.stepId, {
+            ...current,
+            stepType: event.stepType,
+            title: event.title,
+            startedAt: current.startedAt ?? event.at,
+        });
+        return;
+    }
     if (event.type === "step:condition") {
         records.set(event.stepId, {
             ...current,
@@ -508,6 +529,9 @@ const callHandler = async (handlers, event) => {
         case "step:poll":
             await handlers?.onPollTick?.(event);
             return;
+        case "step:iteration":
+            await handlers?.onForeachIteration?.(event);
+            return;
         case "step:success":
             await handlers?.onNodeSuccess?.(event);
             return;
@@ -821,10 +845,10 @@ export const runScenario = async ({ scenario, environment = {}, globals = {}, ru
         let executionPolicy = supportsScenarioNodeExecutionPolicy(node)
             ? withNotificationFailurePolicyOverride(node, getScenarioNodeExecutionPolicy(node))
             : getLegacyScenarioNodeExecutionPolicy();
-        if (node.type === "poll") {
-            // The poll loop REPLACES per-node retry (nested retry loops would be
-            // unexplainable). onFailure — incl. error edges — still governs the
-            // timeout outcome.
+        if (node.type === "poll" || node.type === "foreach") {
+            // The poll/item loop REPLACES per-node retry (nested retry loops would
+            // be unexplainable). onFailure — incl. error edges — still governs the
+            // final outcome.
             executionPolicy = {
                 ...executionPolicy,
                 retry: { enabled: false, maxAttempts: 0, delayMs: 0 },
@@ -1533,6 +1557,228 @@ export const runScenario = async ({ scenario, environment = {}, globals = {}, ru
                     shouldMarkPartialSuccess = degradedStepIds.size > degradedCountBefore;
                     outputData = groupedOutput;
                 }
+                if (node.type === "foreach") {
+                    const foreachConfig = node.data.config;
+                    // ── Resolve the items array ──────────────────────────────────────
+                    let items;
+                    if (foreachConfig.sourceMode === "inline") {
+                        const rawInline = (foreachConfig.itemsInline ?? "").trim();
+                        if (!rawInline) {
+                            throw new ScenarioNodeFailureError("Foreach inline items are empty.");
+                        }
+                        const resolvedInline = resolveScenarioJsonTemplateString(rawInline, templateValues);
+                        let parsedInline;
+                        try {
+                            parsedInline = JSON.parse(resolvedInline);
+                        }
+                        catch {
+                            throw new ScenarioNodeFailureError("Foreach inline items are not valid JSON after template resolution.");
+                        }
+                        if (!Array.isArray(parsedInline)) {
+                            throw new ScenarioNodeFailureError("Foreach inline items must be a JSON array.");
+                        }
+                        items = parsedInline;
+                    }
+                    else {
+                        const itemsPath = (foreachConfig.itemsPath ?? "").trim();
+                        if (!itemsPath) {
+                            throw new ScenarioNodeFailureError("Foreach items path is required.");
+                        }
+                        const resolved = resolveConditionRuntimeValue({
+                            environment: runtimeContext.environment,
+                            globals: runtimeContext.globals,
+                            workflowContext: runtimeContext.workflowContext,
+                            nodeMetaByLabel: runtimeContext.nodeMetaByLabel,
+                            responseRoot: runtimeContext.responseRoot,
+                            dbResult: runtimeContext.dbResult,
+                            kafkaEvent: runtimeContext.kafkaEvent,
+                            redisResult: runtimeContext.redisResult,
+                        }, itemsPath);
+                        if (!resolved.exists || typeof resolved.value === "undefined") {
+                            throw new ScenarioNodeFailureError(`Foreach items path "${itemsPath}" resolved to nothing.`);
+                        }
+                        if (!Array.isArray(resolved.value)) {
+                            throw new ScenarioNodeFailureError(`Foreach items path "${itemsPath}" must resolve to an array (got ${typeof resolved.value}).`);
+                        }
+                        items = resolved.value;
+                    }
+                    const itemAlias = (foreachConfig.itemAlias ?? "").trim();
+                    if (itemAlias && RESERVED_WORKFLOW_ROOT_LABELS.has(itemAlias)) {
+                        throw new ScenarioNodeFailureError(`Foreach item alias "${itemAlias}" is a reserved name.`);
+                    }
+                    const maxIterations = Math.min(MAX_FOREACH_ITERATIONS, Math.max(1, Math.round(foreachConfig.maxIterations ?? DEFAULT_FOREACH_MAX_ITERATIONS)));
+                    const processLimit = Math.min(items.length, maxIterations);
+                    const iterationDelayMs = Math.max(0, Math.round(foreachConfig.delayMs ?? 0));
+                    const onItemFailure = foreachConfig.onItemFailure ?? "stop";
+                    const collectResults = foreachConfig.collectResults !== false;
+                    // Thinned emission keeps stored events bounded (~100 iteration markers).
+                    const iterationEmitStride = Math.max(1, Math.ceil(processLimit / 100));
+                    const internalGraph = buildScenarioExecutionGraph(foreachConfig.nodes, foreachConfig.edges);
+                    const internalScope = {
+                        graph: internalGraph,
+                        stepIdForNode: (childNodeId) => createSubScenarioStepId(stepId, childNodeId),
+                        stepIdForEdge: (edgeId) => createSubScenarioStepId(stepId, edgeId),
+                    };
+                    // ALL descendant step ids (nested containers included) — reset
+                    // targets between iterations.
+                    const internalStepIds = buildRuntimeStepDescriptors(foreachConfig.nodes, stepId).map((descriptor) => descriptor.stepId);
+                    const childLabels = flattenScenarioNodesForContext(foreachConfig.nodes)
+                        .map((childNode) => childNode.data.label.trim())
+                        .filter((childLabel) => childLabel.length > 0);
+                    const workflowRoots = runtimeContext.workflowContext;
+                    // Save the enclosing iteration roots so a NESTED foreach restores
+                    // its parent's {{item}}/{{each}} when it finishes mid-iteration.
+                    const hadItemRoot = Object.prototype.hasOwnProperty.call(workflowRoots, "item");
+                    const previousItemRoot = workflowRoots.item;
+                    const hadEachRoot = Object.prototype.hasOwnProperty.call(workflowRoots, "each");
+                    const previousEachRoot = workflowRoots.each;
+                    const hadAliasRoot = itemAlias
+                        ? Object.prototype.hasOwnProperty.call(workflowRoots, itemAlias)
+                        : false;
+                    const previousAliasRoot = itemAlias ? workflowRoots[itemAlias] : undefined;
+                    const nodeLabelKey = nodeLabel;
+                    const previousEaches = workflowRoots.eaches;
+                    const degradedCountBefore = degradedStepIds.size;
+                    const results = [];
+                    let failedItems = 0;
+                    try {
+                        for (let index = 0; index < processLimit; index += 1) {
+                            throwIfStopped(signal);
+                            if (index > 0) {
+                                // Fresh pass: every internal step back to idle (including the
+                                // "skipped" stamped on unreached nodes last pass), degraded
+                                // marks cleared, records reset via the bulk step:reset event.
+                                for (const internalStepId of internalStepIds) {
+                                    localStatuses.set(internalStepId, "idle");
+                                    degradedStepIds.delete(internalStepId);
+                                }
+                                await emit({
+                                    type: "step:reset",
+                                    runId,
+                                    scenarioId: scenario.id,
+                                    stepIds: internalStepIds,
+                                    at: new Date().toISOString(),
+                                    reason: `Item ${index + 1}/${processLimit}: reset foreach body`,
+                                });
+                                if (iterationDelayMs > 0) {
+                                    await waitForDuration(iterationDelayMs);
+                                }
+                            }
+                            // Fresh-pass isolation: a failed/short-circuited item must not
+                            // inherit the previous iteration's child outputs in its results
+                            // snapshot. The final iteration's children stay published after
+                            // the loop (last-iteration-wins for downstream reads).
+                            for (const childLabel of childLabels) {
+                                delete workflowRoots[childLabel];
+                            }
+                            const item = items[index];
+                            const frame = {
+                                index,
+                                iteration: index + 1,
+                                total: processLimit,
+                                remaining: processLimit - (index + 1),
+                            };
+                            workflowRoots.item = item;
+                            if (itemAlias) {
+                                workflowRoots[itemAlias] = item;
+                            }
+                            workflowRoots.each = frame;
+                            if (nodeLabelKey) {
+                                const eachesRoot = workflowRoots.eaches && typeof workflowRoots.eaches === "object"
+                                    ? workflowRoots.eaches
+                                    : {};
+                                workflowRoots.eaches = { ...eachesRoot, [nodeLabelKey]: frame };
+                            }
+                            if (index === 0 ||
+                                index === processLimit - 1 ||
+                                (index + 1) % iterationEmitStride === 0) {
+                                const itemPreview = (() => {
+                                    try {
+                                        const serialized = JSON.stringify(item);
+                                        if (typeof serialized !== "string")
+                                            return String(item);
+                                        return serialized.length > 2048 ? `${serialized.slice(0, 2048)}…` : serialized;
+                                    }
+                                    catch {
+                                        return null;
+                                    }
+                                })();
+                                await emit({
+                                    type: "step:iteration",
+                                    runId,
+                                    scenarioId: scenario.id,
+                                    stepId,
+                                    stepType: node.type,
+                                    title,
+                                    at: new Date().toISOString(),
+                                    index,
+                                    iteration: index + 1,
+                                    total: processLimit,
+                                    itemPreview,
+                                });
+                            }
+                            try {
+                                for (const startNodeId of internalGraph.startNodeIds) {
+                                    throwIfStopped(signal);
+                                    await executeNode(startNodeId, null, {}, internalScope);
+                                }
+                                await markScopeRemainingNodesSkipped(internalScope, `Internal node was not reached inside ${title} (item ${index + 1}).`);
+                            }
+                            catch (error) {
+                                if (error instanceof ScenarioStopError) {
+                                    throw error;
+                                }
+                                failedItems += 1;
+                                if (onItemFailure === "stop") {
+                                    const message = error instanceof Error ? error.message : String(error);
+                                    throw new ScenarioNodeFailureError(`Foreach item ${index + 1}/${processLimit} failed: ${message}`);
+                                }
+                                // continue: unreached internal nodes stay consistent for the
+                                // report, the run degrades to partial success below.
+                                await markScopeRemainingNodesSkipped(internalScope, `Internal node was not reached inside ${title} (item ${index + 1} failed).`);
+                            }
+                            if (collectResults) {
+                                const iterationOutput = {};
+                                for (const childLabel of childLabels) {
+                                    if (Object.prototype.hasOwnProperty.call(workflowRoots, childLabel)) {
+                                        iterationOutput[childLabel] = workflowRoots[childLabel];
+                                    }
+                                }
+                                results.push(iterationOutput);
+                            }
+                        }
+                    }
+                    finally {
+                        // Restore the enclosing iteration roots (or clear ours).
+                        if (hadItemRoot)
+                            workflowRoots.item = previousItemRoot;
+                        else
+                            delete workflowRoots.item;
+                        if (hadEachRoot)
+                            workflowRoots.each = previousEachRoot;
+                        else
+                            delete workflowRoots.each;
+                        if (itemAlias) {
+                            if (hadAliasRoot)
+                                workflowRoots[itemAlias] = previousAliasRoot;
+                            else
+                                delete workflowRoots[itemAlias];
+                        }
+                        if (typeof previousEaches === "undefined")
+                            delete workflowRoots.eaches;
+                        else
+                            workflowRoots.eaches = previousEaches;
+                    }
+                    shouldMarkPartialSuccess =
+                        degradedStepIds.size > degradedCountBefore || failedItems > 0;
+                    outputData = {
+                        ...(collectResults ? { results } : {}),
+                        itemCount: items.length,
+                        processedCount: processLimit,
+                        truncated: items.length > processLimit,
+                        failedItems,
+                    };
+                }
                 if (node.type === "end") {
                     if (node.data.config.loop && node.data.config.loopTargetNodeId) {
                         const loopTargetNode = scope.graph.nodeMap.get(node.data.config.loopTargetNodeId);