@uipath/maestro-builder-sdk 5.2.0

package/dist/bpmn/bpmn-expr-check.js

@@ -0,0 +1,218 @@
+/**
+ * bpmn-expr-check — the BPMN adapter over the shared `core/expr-check`, run by
+ * `BpmnBuilder.build()` before it hands back the model to be serialized.
+ *
+ * A BPMN `=`-expression reads a declared variable as `=vars.<name>` (a gateway
+ * flow `condition`, a script `input`, a multi-instance `collection`/`completion`,
+ * a variable assignment). `vars.` is a CLOSED namespace, so a reference to a name
+ * nothing declares is a definite mistake — and this is the ONLY thing that
+ * catches it early: a `=vars.<typo>` reaches run time and reads `undefined`,
+ * silently taking the wrong path. So this flags every undeclared `vars.<root>`,
+ * exactly as the flow check flags `$vars`.
+ *
+ * "Declared" means what it means to the platform, which is wider than
+ * `.var()`/`.input()`/`.output()`: a node's output `var` is itself a declaration
+ * (the canvas model keys a variable off each output), so a connector's
+ * `<id>_response`, a script task's output and a variable task's assignment target
+ * are all readable downstream. `nodeDeclaredVars` supplies them; being stricter
+ * than the platform here would reject working processes.
+ *
+ * A loop's item binds `iterator.<itemVar>`, and a script output writes `=result.…`
+ * — different namespaces, left alone (only `vars.` is the author's to get wrong).
+ * Variables are SCOPED: a sub-process sees the enclosing variables plus its own.
+ */
+import { checkExpression } from '../core/expr-check.js';
+import { nodeDeclaredVars } from './bpmn-sdk.js';
+const NOUN = 'variable';
+const NAMESPACE = 'vars';
+const BINDING_NOUN = 'binding';
+const BINDING_NAMESPACE = 'bindings';
+function checkExpr(expr, where, roots, out) {
+    if (!expr)
+        return;
+    for (const d of checkExpression(expr, { roots: roots.vars, noun: NOUN, namespace: NAMESPACE }))
+        out.push({ ...d, where });
+    for (const d of checkExpression(expr, { roots: roots.bindings, noun: BINDING_NOUN, namespace: BINDING_NAMESPACE }))
+        out.push({ ...d, where });
+    // A process variable is always read through the `vars` namespace. The bare
+    // spelling is especially easy to confuse with a script task's local input
+    // identifiers: `inputs: { amount: '=vars.amount' }` makes `amount` local only
+    // inside the script body. On a flow condition or mapping, `=amount` reaches
+    // the runtime as an unresolved identifier while both XML validators accept it.
+    // Keep this intentionally narrow (a single optionally-parenthesized name) so
+    // local declarations inside arbitrary `=js:` programs are not guessed at.
+    const bare = expr.match(/^\s*=(?:js:)?\s*\(?\s*([A-Za-z_$][\w$]*)\s*\)?\s*$/)?.[1];
+    if (bare && roots.varIds.has(bare)) {
+        out.push({
+            level: 'error',
+            code: 'EXPR_BARE_VAR_REF',
+            message: `Expression reads declared variable \`${bare}\` without the \`vars\` namespace; use \`=vars.${bare}\`.`,
+            where,
+        });
+    }
+}
+/** Check every `=`-expression VALUE of a `field → expression` map (keys are targets). */
+function checkExprValues(rec, where, roots, out) {
+    for (const v of Object.values(rec ?? {}))
+        checkExpr(v, where, roots, out);
+}
+/** Reach `=`-expression strings anywhere in a connector's (possibly nested) inputs. */
+function deepExprStrings(val, where, roots, out) {
+    if (typeof val === 'string') {
+        if (val.startsWith('='))
+            checkExpr(val, where, roots, out);
+        return;
+    }
+    if (Array.isArray(val)) {
+        for (const v of val)
+            deepExprStrings(v, where, roots, out);
+        return;
+    }
+    if (val && typeof val === 'object') {
+        for (const v of Object.values(val))
+            deepExprStrings(v, where, roots, out);
+    }
+}
+function walk(nodes, flows, rootsIn, out) {
+    // A node's output `var` IS a variable declaration to the platform (its canvas
+    // model keys a variable off each output's `var`), so a downstream read of one
+    // resolves without any `uipath:variables` entry — a connector's response, a
+    // script task's output, a variable task's assignment target. Collect them for
+    // the WHOLE scope before walking: a flow condition is checked first but may
+    // read a node declared later in authoring order.
+    const roots = { vars: new Set(rootsIn.vars), varIds: rootsIn.varIds, bindings: rootsIn.bindings };
+    for (const n of nodes)
+        for (const name of nodeDeclaredVars(n))
+            roots.vars.add(name);
+    for (const f of flows)
+        checkExpr(f.condition, `flow "${f.id}" condition`, roots, out);
+    for (const n of nodes) {
+        const at = `${n.kind} "${n.id}"`;
+        // An errorMapping row's `condition` is an expression on EVERY activity kind, so
+        // it is checked before the per-kind arms rather than inside them. Worth checking
+        // here specifically because the CANVAS treats an undeclared reference in it as a
+        // blocking error while `uip maestro bpmn validate` says nothing at all — so
+        // without this the author's first sign of trouble is the designer refusing the
+        // artifact, long after every gate this repo runs went green.
+        // Events carry no errorMapping — the field exists on the activity arms only.
+        //
+        // `error` is a BUILT-IN root here, not an author declaration. The skill's
+        // expression reference says so outright — "Error mapping conditions may inspect the
+        // built-in error object through `vars.error`, for example
+        // `=vars.error.code == \"SERVICE_UNAVAILABLE\"`" — and that example is the whole
+        // point of the scenario: a row exists to classify a failure, so the only thing worth
+        // branching on is the failure. Requiring `.var('error', …)` first forced authors to
+        // declare a DECOY variable whose only purpose was to quiet this check, and which then
+        // shipped as a real `uipath:inputOutput` row in the artifact.
+        //
+        // Scoped to this one expression slot rather than added to the shared root set: outside
+        // an errorMapping condition there is no error object in scope, so `vars.error` there
+        // really is an undeclared reference and should still be reported.
+        // `error` joins `vars` (so `vars.error` resolves) but NOT `varIds`: it is a
+        // scoped runtime binding, not a declared variable, so `=error` is not a bare
+        // spelling of one.
+        const errRoots = { vars: new Set(roots.vars).add('error'), varIds: roots.varIds, bindings: roots.bindings };
+        for (const row of ('errorMapping' in n ? n.errorMapping : undefined) ?? []) {
+            checkExpr(row.condition, `${at} errorMapping "${row.code}" condition`, errRoots, out);
+        }
+        // A loop's collection and completion condition, on every activity kind EXCEPT the
+        // sub-process, which checks its own below in the right scopes. Only that arm used to
+        // check them, so a `.scriptTask({ loop })` — the commonest looping shape — had
+        // neither expression checked. It matters more now the engine HONOURS the completion
+        // condition: an unevaluatable one is swallowed there and the loop runs the whole
+        // collection, so this is the gate that reports it.
+        if (n.kind !== 'subProcess' && 'loop' in n && n.loop !== undefined) {
+            checkExpr(n.loop.collection, `${at} loop collection`, roots, out);
+            // The iterator bindings (`iterator.item`, `iterator.<itemVar>`) are the loop's
+            // own, not author declarations, so a completion condition may read them.
+            const loopRoots = {
+                vars: new Set(roots.vars).add('iterator'),
+                varIds: roots.varIds,
+                bindings: roots.bindings,
+            };
+            checkExpr(n.loop.completion, `${at} loop completion`, loopRoots, out);
+        }
+        if (n.kind === 'scriptTask') {
+            checkExprValues(n.inputs, `${at} input`, roots, out);
+            checkExprValues(n.outputs, `${at} output`, roots, out);
+        }
+        else if (n.kind === 'task') {
+            checkExprValues(n.set, `${at} assignment`, roots, out);
+        }
+        else if (n.kind === 'connector') {
+            deepExprStrings(n.inputs, `${at} input`, roots, out);
+        }
+        else if (n.kind === 'subProcess') {
+            // A sub-process is its own variable scope: it sees the enclosing variables
+            // plus the ones it declares. The loop COLLECTION is evaluated in the
+            // enclosing scope (before entry); the body and completion see the sub-scope.
+            checkExpr(n.loop?.collection, `${at} loop collection`, roots, out);
+            const subRoots = { vars: new Set(roots.vars), varIds: new Set(roots.varIds), bindings: roots.bindings };
+            for (const v of n.variables)
+                subRoots.vars.add(v.name);
+            checkExpr(n.loop?.completion, `${at} loop completion`, subRoots, out);
+            walk(n.nodes, n.flows, subRoots, out);
+        }
+    }
+}
+/** Every first-level expression problem in a built BPMN process, stamped with its location. */
+export function checkBpmnExpressions(built) {
+    const roots = {
+        // Keyed by ID, which is what an expression reads — `BpmnVarDecl.id` is documented as
+        // "what expressions read as `vars.<id>`", and every product-shaped artifact agrees:
+        // the fixtures under skills `edit/*/fixture` declare
+        // `<uipath:inputOutput id="Var_OrderId" name="OrderId">` and reference
+        // `=vars.Var_OrderId`, never the display name.
+        //
+        // This read `v.name`, so a variable given a friendly name became unreferenceable: the
+        // id an expression uses was not in the root set and every reference to it failed
+        // EXPR_UNDECLARED_REF. It only looked right because `.var()` defaults `name` to the id,
+        // so the bug was invisible until a display name differed — which is exactly what
+        // `bpmn-decompile` produces from any real artifact, so it blocked the whole
+        // decompile-edit-recompile round trip.
+        //
+        // The display name is accepted too. It is not what the wire uses, but an author who
+        // wrote `vars.<displayName>` in an existing process should get the reference resolved
+        // rather than a spurious error from a stricter check.
+        vars: new Set(built.variables.flatMap((v) => [v.id, v.name])),
+        varIds: new Set(built.variables.map((v) => v.id)),
+        // Author-declared bindings, plus the symbolic connection/folder names a
+        // connector turns into bindings at serialize time — the author's own spelling
+        // is what they would reference, so both are legitimate roots.
+        bindings: new Set([...built.bindings.map((b) => b.id), ...connectorBindingNames(built.nodes)]),
+    };
+    const out = [];
+    walk(built.nodes, built.flows, roots, out);
+    return out;
+}
+/** Every symbolic connection/folder name in a graph, at any nesting depth. */
+function connectorBindingNames(nodes) {
+    const out = [];
+    for (const n of nodes) {
+        if (n.kind === 'connector') {
+            if (n.connection)
+                out.push(n.connection);
+            if (n.folder)
+                out.push(n.folder);
+        }
+        if (n.kind === 'subProcess')
+            out.push(...connectorBindingNames(n.nodes));
+    }
+    return out;
+}
+/**
+ * Thrown by `BpmnBuilder.build()` when the first-level expression check finds an
+ * undeclared `vars.<name>` reference. Same shape/rationale as the flow's
+ * `FlowBuildError`: `message` lists every problem; `diagnostics` carries them
+ * structured.
+ */
+export class BpmnBuildError extends Error {
+    diagnostics;
+    constructor(built, diagnostics) {
+        const label = built.name || built.id || 'process';
+        const lines = diagnostics.map((d) => `  ✗ [${d.code}] in ${d.where}: ${d.message}${d.suggestion ? ` (did you mean "${d.suggestion}"?)` : ''}`);
+        super(`Cannot build BPMN process "${label}" — ${diagnostics.length} expression problem(s):\n${lines.join('\n')}`);
+        this.name = 'BpmnBuildError';
+        this.diagnostics = diagnostics;
+    }
+}