@xdelivered/emberflow 0.2.0

package/dist/src/engine/diagnostics.js

@@ -0,0 +1,148 @@
+import { parsePathParams } from '../lib/pathParams.js';
+function paramDefaultsOf(inputNode) {
+    const defaults = inputNode.config?.defaults;
+    const params = defaults && typeof defaults === 'object' && !Array.isArray(defaults)
+        ? defaults.params
+        : undefined;
+    return params && typeof params === 'object' && !Array.isArray(params) ? params : undefined;
+}
+/** Diagnose an operation (a flow with an `http` trigger, plus its scenarios)
+ *  for issues a studio user or the `emberflow doctor` CLI should surface
+ *  before relying on the operation. Deterministic order: all
+ *  `missing-param-default` (path order), then all `param-no-real-scenario`
+ *  (path order), then `no-expects`, then `missing-node-mock` (extras order),
+ *  then `inputmap-schema-mismatch` (node order), then `simulated-commit`
+ *  (node order), then `language-drift` (at most one, project-level). */
+export function diagnoseOperation(flow, scenarios, extras) {
+    const diagnostics = [];
+    const scenarioList = scenarios ?? [];
+    const path = flow.http?.path;
+    const params = path ? parsePathParams(path) : [];
+    // No Input node means nothing can map `params` into a node — there is
+    // nothing to guard and nowhere to put a default, so skip entirely (mirrors
+    // missingPathParams' guard semantics).
+    const inputNode = params.length > 0 ? flow.nodes.find((n) => n.type === 'Input') : undefined;
+    if (inputNode) {
+        const paramDefaults = paramDefaultsOf(inputNode);
+        for (const name of params) {
+            const hasDefault = paramDefaults ? paramDefaults[name] !== undefined : false;
+            if (!hasDefault) {
+                diagnostics.push({
+                    severity: 'warning',
+                    code: 'missing-param-default',
+                    message: `Path param ":${name}" has no default — plain Run would reach nodes with params.${name} undefined. Add a value (even "") under the Input node's defaults.params, or run a scenario.`,
+                    nodeId: inputNode.id,
+                    param: name,
+                });
+            }
+        }
+        for (const name of params) {
+            const suppliesRealValue = scenarioList.some((s) => {
+                const scenarioParams = s.input?.params;
+                const value = scenarioParams?.[name];
+                return typeof value === 'string' ? value !== '' : value !== undefined;
+            });
+            if (!suppliesRealValue) {
+                diagnostics.push({
+                    severity: 'info',
+                    code: 'param-no-real-scenario',
+                    message: `No scenario supplies a real value for path param ":${name}" — add a scenario with input.params.${name} set to exercise this path.`,
+                    nodeId: inputNode.id,
+                    param: name,
+                });
+            }
+        }
+    }
+    const hasExpect = scenarioList.some((s) => s.expect !== undefined);
+    if (!hasExpect) {
+        diagnostics.push({
+            severity: 'info',
+            code: 'no-expects',
+            message: 'This operation has no scenario with an expect — nothing verifies its behavior automatically. Add expect to at least one scenario.',
+        });
+    }
+    const infraNodes = extras?.infraNodes ?? [];
+    const opMocks = extras?.opMocks ?? flow.mocks ?? {};
+    for (const { id, traceKind } of infraNodes) {
+        if (Object.prototype.hasOwnProperty.call(opMocks, id))
+            continue;
+        const node = flow.nodes.find((n) => n.id === id);
+        diagnostics.push({
+            severity: 'info',
+            code: 'missing-node-mock',
+            message: `"${node?.label ?? id}" touches infrastructure (${traceKind}) but has no mock — plain (no-scenario) Mock runs will fail at it. Cover with AI writes mocks, or add one under "mocks" in the scenarios file.`,
+            nodeId: id,
+        });
+    }
+    // inputmap-schema-mismatch: an inputMap entry reads a field the source node
+    // never declares. Catches wiring that only breaks in a REAL run — a mocked
+    // source node hides it, but the live node returns a differently-shaped output.
+    // Only fires when the source node's type is registered AND its outputSchema
+    // declares fields (present in extras.outputFieldsByNode).
+    const outputFieldsByNode = extras?.outputFieldsByNode;
+    if (outputFieldsByNode) {
+        for (const node of flow.nodes) {
+            if (!node.inputMap)
+                continue;
+            for (const [field, mapping] of Object.entries(node.inputMap)) {
+                const declared = outputFieldsByNode[mapping.sourceNodeId];
+                if (!declared)
+                    continue; // source unregistered or has no declared output fields
+                // '$' means the whole output — nothing to check. Ignore a leading '$'.
+                const raw = mapping.sourceField;
+                if (raw === '$' || raw === '')
+                    continue;
+                const firstSegment = raw.replace(/^\$\.?/, '').split('.')[0];
+                if (firstSegment === '' || firstSegment === '$')
+                    continue;
+                if (!declared.includes(firstSegment)) {
+                    diagnostics.push({
+                        severity: 'warning',
+                        code: 'inputmap-schema-mismatch',
+                        message: `"${node.label ?? node.id}".${field} reads "${raw}" from ${mapping.sourceNodeId}, but "${firstSegment}" is not a declared output field of that node (declares: ${declared.join(', ') || 'none'}). A real run may return undefined here even if a mock hides it.`,
+                        nodeId: node.id,
+                        param: field,
+                    });
+                }
+            }
+        }
+    }
+    // simulated-commit: a mutation node whose implementation source still
+    // contains the `[SIMULATED]` marker — the forbidden anti-pattern of a
+    // commit branch that logs and returns success instead of performing (or
+    // throwing on) the real side effect. Each flagged node instance gets its
+    // own warning; a node type used twice is not deduped, since each instance
+    // is an independent op-level risk. Only fires for nodes present in
+    // extras.mutationSourcesByNode — see that field's doc comment for the
+    // registered/mutation/function-source gating the caller performs.
+    const mutationSourcesByNode = extras?.mutationSourcesByNode;
+    if (mutationSourcesByNode) {
+        for (const node of flow.nodes) {
+            const source = mutationSourcesByNode[node.id];
+            if (source === undefined || !source.includes('[SIMULATED]'))
+                continue;
+            diagnostics.push({
+                severity: 'warning',
+                code: 'simulated-commit',
+                message: `mutation node "${node.id}" (${node.type}) has a simulated commit path — the commit branch must perform the real side effect or throw naming the missing secretRef`,
+                nodeId: node.id,
+            });
+        }
+    }
+    // language-drift: the project's declared `language:` field disagrees with
+    // its own config file's extension. Only fires when the caller passed
+    // extras.languageDrift — which callers only do when the field was EXPLICIT
+    // and contradicts the extension (see that field's doc comment); an
+    // inferred language always agrees with the extension by construction, so
+    // there's nothing to detect in that case.
+    const languageDrift = extras?.languageDrift;
+    if (languageDrift) {
+        const { projectLanguage, configPathExtension } = languageDrift;
+        diagnostics.push({
+            severity: 'info',
+            code: 'language-drift',
+            message: `Project config declares language: "${projectLanguage}" but the config file itself is "${configPathExtension}" — align the "language" field with the config file's extension, or rename the file, so agents and tooling author in the right language.`,
+        });
+    }
+    return diagnostics;
+}

package/dist/src/engine/executor.d.ts

@@ -0,0 +1,151 @@
+import type { LogLine, NodeRunState, SubflowResult, WorkflowDefinition, WorkflowRun } from './types.js';
+import type { NodeRegistry } from './registry.js';
+import type { TraceSink } from './trace.js';
+export declare function getByPath(obj: unknown, path: string): unknown;
+/**
+ * Enriches a "reading property of undefined/null" TypeError message with the
+ * node's resolved input keys, so the recorded error points at what the node
+ * actually received instead of just the raw JS engine message. Every other
+ * message passes through byte-identical.
+ */
+export declare function explainUndefinedRead(message: string, input: Record<string, unknown>): string;
+export interface ExecutorEvents {
+    onNodeStateChange?: (nodeId: string, state: NodeRunState) => void;
+    onLog?: (line: LogLine) => void;
+    onRunFinished?: (run: WorkflowRun) => void;
+}
+export interface StartRunOptions {
+    flow: WorkflowDefinition;
+    registry: NodeRegistry;
+    trace?: TraceSink;
+    events?: ExecutorEvents;
+    now?: () => string;
+    newId?: () => string;
+    secrets?: Record<string, string>;
+    /** Non-secret environment values, exposed as ctx.vars and used to resolve {"$env": NAME}. */
+    vars?: Record<string, string>;
+    /** When true, mutation nodes dry-run their side effects; recorded on the run. */
+    safeMode?: boolean;
+    /** The environment name this run points at; recorded on the run. */
+    environment?: string;
+    /** nodeId -> pinned output. Pinned nodes skip execution and tracing. */
+    pins?: Record<string, unknown>;
+    /**
+     * When true, runs in Mock mode: nodes with a canned output in `mocks` return
+     * it verbatim without invoking their implementation or the retry loop; nodes
+     * that would touch infrastructure (`traceKind` 'db'/'http'/'llm') and have no
+     * mock fail loud (a normal node failure — respects `optional`, halts like any
+     * error). Pure/compute nodes (`traceKind` 'compute' or absent) always execute
+     * their real implementation, mocked or not. Defaults false; when false,
+     * `mocks` is ignored entirely (Live behavior is byte-identical to today).
+     */
+    mockRun?: boolean;
+    /** nodeId -> canned output, consulted only when `mockRun` is true. See `mockRun`. */
+    mocks?: Record<string, unknown>;
+    /** The invocation payload, exposed to nodes as ctx.runInput. */
+    input?: Record<string, unknown>;
+    /**
+     * Host-provided runner for Subflow nodes: given a workflow id + input, runs
+     * that child flow to completion and returns its collected output. The
+     * executor injects the calling node's id (for log prefixing / cycle context);
+     * the host owns workflow lookup and the recursion/cycle guard. Absent when
+     * the host can't resolve other workflows.
+     */
+    subflowRunner?: (workflowId: string, input: Record<string, unknown>, callerNodeId: string) => Promise<SubflowResult>;
+}
+export declare class FlowRun {
+    readonly run: WorkflowRun;
+    private readonly flow;
+    private readonly registry;
+    private readonly trace?;
+    private readonly events;
+    private readonly now;
+    private readonly newId;
+    private readonly secrets;
+    private readonly vars;
+    private readonly environment?;
+    private readonly safeMode;
+    private readonly runInput;
+    private readonly pins;
+    private readonly mockRun;
+    private readonly mocks;
+    private readonly subflowRunner?;
+    private readonly order;
+    private readonly outputs;
+    private readonly skippedNodes;
+    private readonly branchTaken;
+    private readonly regionByForEach;
+    /** Nodes a completed loop region already executed; the main cursor consumes them silently. */
+    private readonly loopExecuted;
+    private activeLoop?;
+    private cursor;
+    /** Run-wide execution counter — numbers every node execution in the log. */
+    private execSeq;
+    constructor(opts: StartRunOptions);
+    step(): Promise<boolean>;
+    /**
+     * Runs one node's implementation (or reuses its pin) end to end: resolve
+     * config/input, execute, record state + trace, handle failure. Shared by
+     * the main cursor and by loop-body execution, which additionally tags the
+     * resulting NodeRunState with the current iteration.
+     */
+    private executeNode;
+    /** First step on a reachable ForEach: resolve items, chunk, and start (or short-circuit) the region. */
+    private startLoop;
+    /**
+     * Sets the ForEach's per-iteration output and resets body branch-skip
+     * state. Also clears each body id's prior-iteration output: without this,
+     * a body node that a branch skips this iteration would still resolve
+     * downstream inputMap reads to whatever it produced last iteration, since
+     * `outputs` is otherwise only ever overwritten (never cleared) by execution.
+     */
+    private beginIteration;
+    /** One step of an in-progress region: a body node, an iteration advance, or the final Collect. */
+    private stepLoop;
+    /** Resolves Collect's `value` input against the current iteration's body outputs. */
+    private resolveCollectValue;
+    /**
+     * Executes Collect once with the accumulated results and hands the region's
+     * nodes to `loopExecuted` so the main cursor consumes them silently — it
+     * must NOT jump past the Collect, because topo order can interleave
+     * parallel non-region nodes between the ForEach and the Collect.
+     */
+    private finishLoop;
+    /** Remember a node's taken branch when its output carries `$branch`. */
+    private captureBranch;
+    /**
+     * A node is reachable if it has no incoming edges, or at least one incoming
+     * edge from a non-skipped, executed source whose branch (if the edge names
+     * one via sourceHandle) was taken.
+     */
+    private isReachable;
+    private epilogue;
+    runToEnd(): Promise<WorkflowRun>;
+    cancel(): void;
+    /**
+     * Resolve {"$secret": NAME} and {"$env": NAME} config values; a missing
+     * secret/var fails the node. `$secret` is only recognized at a config
+     * value's top level (matching today's behavior — secrets are never nested
+     * inside larger config structures). `$env` is resolved deeply, the same
+     * walk used for the run-input payload, so refs nested in objects/arrays
+     * (e.g. an Input node's `config.defaults`) resolve too.
+     */
+    private resolveConfig;
+    private resolveInput;
+    /**
+     * A lenient variant of `resolveInput` for nodes whose implementation never
+     * runs (mocked, or an infra node with no mock, in a mock run): resolves
+     * only `inputMap`-sourced fields (other nodes' already-computed outputs,
+     * which can never carry a `$secret`/`$env` ref). Skips the config-sourced
+     * fields `resolveInput` also merges in — those come from `resolveConfig`,
+     * which this path deliberately never calls, since that is exactly what
+     * could throw (e.g. `Missing secret`) for a node this run will never
+     * actually execute.
+     */
+    private resolveInputLenient;
+    private finish;
+    private setNodeState;
+    private emitLog;
+    private recordSample;
+}
+export declare function startRun(opts: StartRunOptions): FlowRun;