@uipath/maestro-builder-sdk 6.66.6 → 6.66.8

package/dist/serialize.js

@@ -11,7 +11,7 @@ import { LOOP_DEFAULT_VERSION, bodyUsesBreak, loopDeclaredInputs, loopHasInnerHa
 import { Expr, toExpr, SCHEDULE_PRESETS, flatNameSegmentsOf, parallelFork } from './flow-sdk.js';
 import { FlowAction, FlowTrigger } from './core/node-classes.js';
 import { connectorRawNodeRefusal } from './core/connector-raw-node.js';
-import { CompileRefusal } from './core/compile-refusal.js';
+import { CompileRefusal, LibraryRequiredRefusal } from './core/compile-refusal.js';
 import { nearestName } from './core/edit-distance.js';
 import { rawNodeInputProblem, registeredRawType } from './raw-node-advice.js';
 import { planContributionBindings } from './core/contribution-bindings.js';
@@ -736,17 +736,31 @@ function resolveEvent(library, kind, sub, where) {
 /**
  * LIBRARY_REQUIRED for an event subscription at `site`, after the refusals that
  * need no library: its binding labels, judged as `eventDetail` judges them, so a
- * run without a library (`check`'s inner loop) still hears about them.
+ * run without a library (`check`'s inner loop) still hears about them. The
+ * refusal carries the connection the node is bound to, so its collect-mode
+ * stand-in still takes part in the file-wide connection rule (`connectionConnectors`).
  */
 function libraryRequiredForEvent(opts, sub, nodeId, site, call) {
+    let use;
     if (sub !== null && typeof sub === 'object') {
+        // With no library no parameter is declared, so every `where` key lands in
+        // eventParameters and folds into the match expression, exactly as
+        // `eventDetail` places an undeclared key. A lookup token is a value only
+        // a library resolves; it is not judged here.
+        if (sub.where !== null && typeof sub.where === 'object') {
+            const scope = Object.fromEntries(Object.entries(sub.where).filter(([, v]) => !isLookupToken(v)));
+            eventScopeClauses(flattenWhere(scope, new Set()), nodeId);
+        }
         if (Array.isArray(sub.filters))
             eventFilterReads(sub.filters, nodeId);
         requireBindingPair(site, sub, eventTarget(sub));
-        resolveBinding(opts, sub.connection, 'connection', `event node "${nodeId}"`, eventTarget(sub));
+        const connection = resolveBinding(opts, sub.connection, 'connection', `event node "${nodeId}"`, eventTarget(sub));
         resolveBinding(opts, sub.folder, 'folder', `event node "${nodeId}"`, eventTarget(sub));
+        const connector = eventTarget(sub)?.key;
+        if (connection !== undefined && connector !== undefined)
+            use = { connector, connection };
     }
-    return new CompileRefusal('LIBRARY_REQUIRED', `${call} needs a library (pass --library / set $FLOW_SDK_LIBRARY_JSON).`);
+    return new LibraryRequiredRefusal(`${call} needs a library (pass --library / set $FLOW_SDK_LIBRARY_JSON).`, use);
 }
 /** The trigger kinds a `.trigger()` or `.entryPoint()` spec may carry. */
 const TRIGGER_KINDS = new Set(['manual', 'scheduled', 'event', 'form', 'conversation', 'voice']);
@@ -916,6 +930,36 @@ function eventFilterReads(filters, nodeId) {
         return read;
     });
 }
+/**
+ * The match-expression clauses of a subscription's EVENT parameters, one
+ * `k == '<value>'` per value, or the refusal of the first value compile cannot
+ * write there. The clause compares against a JMESPath string, so the value must
+ * be a string, number or boolean: an object or array would be stringified to
+ * `'[object Object]'` (or a comma list), a subscription that matches nothing
+ * (EVENT_WHERE_NOT_SCALAR). A string with a backslash JMESPath engines read
+ * apart is EVENT_FILTER_BACKSLASH. An absent or empty value (`''` or `[]`, so a
+ * `where` built from a possibly-empty list) writes no clause.
+ *
+ * Only event parameters fold into the expression; a query or path parameter is
+ * sent with the request that registers the subscription and is never read as
+ * JMESPath, so neither rule applies to it.
+ */
+function eventScopeClauses(eventParameters, nodeId) {
+    return Object.entries(eventParameters)
+        .filter(([, v]) => v !== undefined && v !== null && v !== '' && !(Array.isArray(v) && v.length === 0))
+        .map(([k, v]) => {
+        if (typeof v !== 'string' && typeof v !== 'number' && typeof v !== 'boolean') {
+            throw new CompileRefusal('EVENT_WHERE_NOT_SCALAR', `event node "${nodeId}": \`where.${k}\` is ${Array.isArray(v) ? 'an array' : isLookupToken(v) ? 'an unresolved lookup() nested inside an object' : 'an object'}, `
+                + `and an event parameter is matched as one text value (\`${k} == '<value>'\`): written as it is, `
+                + `the subscription would compare against ${JSON.stringify(String(v))} and match nothing. `
+                + `Give \`${k}\` a string, number or boolean.`, `where: { '${k}': '<value>' }`);
+        }
+        const problem = jmesStringProblem(String(v));
+        if (problem)
+            throw new CompileRefusal('EVENT_FILTER_BACKSLASH', `event node "${nodeId}": \`where.${k}\`: ${problem}`);
+        return `${k} == ${jmesString(String(v))}`;
+    });
+}
 function eventDetail(rc, sub, nodeId, opts, site) {
     requireBindingPair(site, sub, eventTarget(sub));
     const conn = resolveBinding(opts, sub.connection, 'connection', `event node "${nodeId}"`, eventTarget(sub));
@@ -976,14 +1020,7 @@ function eventDetail(rc, sub, nodeId, opts, site) {
     // subscription's own scope — the mandatory clause the platform AND-joins —
     // whereas a query or path parameter is part of the request that registers
     // the subscription, not a property of the events it matches.
-    const scopeClauses = Object.entries(eventParameters)
-        .filter(([, v]) => v !== undefined && v !== null && String(v) !== '')
-        .map(([k, v]) => {
-        const problem = jmesStringProblem(String(v));
-        if (problem)
-            throw new CompileRefusal('EVENT_FILTER_BACKSLASH', `event node "${nodeId}": \`where.${k}\`: ${problem}`);
-        return `${k} == ${jmesString(String(v))}`;
-    });
+    const scopeClauses = eventScopeClauses(eventParameters, nodeId);
     // Each authored filter is read structurally (which operator, which value) and
     // lowered with the designer's own grammar — see `event-filters.ts` for the
     // measured table.
@@ -1499,6 +1536,21 @@ function terminateOutputs(scope) {
     }
     return outs;
 }
+/**
+ * A step or entry point named `start` in a scope where `$vars.start` is
+ * rewritten to the scope's start node (#1518): the root while `.triggerId()`
+ * renames the trigger (`renamedTrigger`), or any subflow body (its start node
+ * is `<caller>Start`). The rewrite would point the node's own readers at that
+ * start node, so the name is refused instead. A step-level refusal: `check`
+ * reports it on the step (or entry point), so the message names no scope.
+ */
+function startReadRefusal(what, renamedTrigger, code = 'STEP_ID_COLLISION') {
+    const owner = renamedTrigger !== undefined
+        ? `the trigger, which .triggerId("${renamedTrigger}") renamed: compile rewrites \`$vars.start\` to \`$vars.${renamedTrigger}\``
+        : "this subflow body's own start node: compile rewrites `$vars.start` to it";
+    return new CompileRefusal(code, `[${code}] ${what}: \`$vars.start\` (what \`input()\` reads) names ${owner}, so reads of `
+        + `${what} would go there. Give it another name.`);
+}
 /**
  * Rewrite `$vars.<step>` references through a scope's rename map.
  *
@@ -1716,6 +1768,13 @@ function serializeFlow(built, opts) {
      * placeholder check exempts them.
      */
     const unboundDrafts = new Set();
+    /**
+     * The connection each collect-mode stand-in was bound to, by node id: a node
+     * refused only for want of a library (`LibraryRequiredRefusal`) has no
+     * `detail` to read, so the file-wide connection rule (`connectionConnectors`)
+     * is handed it here. Empty outside collect mode.
+     */
+    const standInConnections = new Map();
     /**
      * RESOURCE bindings collected while emitting, keyed by binding id — `resource:
      * 'process'` for the rpa family, `resource: 'queue'` for the queue family.
@@ -1877,9 +1936,16 @@ function serializeFlow(built, opts) {
     // trigger node's default id. When the flow renames the trigger, register that
     // rename so the SAME pass that rewrites step-name references rewrites these
     // too, rather than teaching every call site about the trigger.
-    if (built.triggerId && built.triggerId !== 'start') {
-        root.rename.nodeIds.set('start', [built.triggerId]);
-    }
+    //
+    // That rewrite cannot tell an `input()` read from a read of a node that is
+    // really named `start` (`entryInput('start', 'x')` and `$vars.start.output.x`
+    // in a step's code are the same text), so while the trigger is renamed the
+    // name `start` is the trigger's: a step or an entry point that takes it is
+    // refused (`startReadRefusal`), never rewritten to point at the trigger. A
+    // subflow body renames `start` the same way, so its steps are held to it too.
+    const renamedTrigger = built.triggerId && built.triggerId !== 'start' ? built.triggerId : undefined;
+    if (renamedTrigger)
+        root.rename.nodeIds.set('start', [renamedTrigger]);
     // Every node id emitted anywhere in the file. `start` is taken before
     // anything else: the root trigger's id is fixed, so a step named like the
     // trigger is refused (claimStepIds).
@@ -1984,7 +2050,9 @@ function serializeFlow(built, opts) {
      *   thrown before any node is emitted). Renaming the second to `x2` left
      *   `.stepToRef('x')` and `$vars.x` pointing at the first, with no word said.
      * - In the flow itself, a step named like the trigger is refused the same
-     *   way (STEP_ID_COLLISION).
+     *   way (STEP_ID_COLLISION). So is a step named `start` wherever
+     *   `$vars.start` is rewritten to a start node: the flow while `.triggerId()`
+     *   renames the trigger, and every subflow body (#1518, `startReadRefusal`).
      * - A subflow body whose ids are already taken (a second copy of the same
      *   child, or a child step sharing a name with a caller's step) is the one
      *   place ids move: the whole copy is prefixed with the calling step's name,
@@ -2019,6 +2087,10 @@ function serializeFlow(built, opts) {
         // A subflow copy's named Ends (`alsoIds`) decide the prefix with its steps (#1253).
         const prefix = copyPrefix !== undefined && [...seen.keys(), ...alsoIds].some((id) => takenIds.has(id)) ? copyPrefix : '';
         for (const [safe, n] of seen) {
+            // `$vars.start` names this scope's start node, not a step (see `renamedTrigger`).
+            if (safe === 'start' && (copyPrefix !== undefined || renamedTrigger)) {
+                refuseOn(scope, n, startReadRefusal(`step "${n}"`, copyPrefix !== undefined ? undefined : renamedTrigger));
+            }
             if (!prefix && takenIds.has(safe)) {
                 throw new CompileRefusal('STEP_ID_COLLISION', `${where}: [STEP_ID_COLLISION] step "${n}" has the trigger's node id "${safe}", and compile will not `
                     + `rename it "${safe}2". Rename the step.`);
@@ -2244,6 +2316,34 @@ function serializeFlow(built, opts) {
             || scope.pendingEdges.some((p) => p.from.node === node && isOutcome(p.from.port));
         return tails.filter((t) => capsOpenTail.has(t.node) && !hasOutcomeEdge(t.node));
     }
+    /**
+     * A subflow body is started by its caller, through the one manual Start node
+     * `emitSubflowBodyIn` writes. So a child's own way of starting has nowhere to
+     * go in the `.flow`, and writing the body without it would silently drop what
+     * the author wrote (#1067): a `.trigger(scheduled(…))` would never fire, and an
+     * `.entryPoint()` root and its steps would vanish. Both are refused.
+     * `.trigger(manual(), { label, version })` is allowed: it names the child's
+     * Start node (#1050), and it is the form decompile writes for a renamed one.
+     */
+    function refuseChildRoots(child, step) {
+        // `subflow(undefined, …)` is `check`'s SUBFLOW_NO_CHILD.
+        if (!child || !Array.isArray(child.steps))
+            return;
+        const kind = child.trigger?.kind;
+        if (child.trigger !== undefined && kind !== 'manual') {
+            const noun = kind === 'scheduled' ? 'schedule' : kind === 'event' ? 'event subscription' : 'trigger';
+            throw new CompileRefusal('SUBFLOW_CHILD_TRIGGER', `Subflow "${step}" runs a flow with its own \`.trigger(…)\`. A subflow is started by its caller, never by a `
+                + `trigger of its own — the ${noun} would be dropped. Remove the .trigger() from "${child.id}" `
+                + `(\`.trigger(manual(), { label })\` is allowed, to name the child's start node).`);
+        }
+        const roots = child.entryPoints ?? [];
+        if (roots.length > 0) {
+            throw new CompileRefusal('SUBFLOW_CHILD_ENTRY_POINT', `Subflow "${step}" runs a flow with ${roots.length === 1 ? 'an entry point' : 'entry points'} `
+                + `(${roots.map((r) => `"${r.id}"`).join(', ')}). A subflow has one root, its caller, so the entry `
+                + `${roots.length === 1 ? 'point and its steps' : 'points and their steps'} would be dropped. Call a flow `
+                + `without .entryPoint(), or move each entry point's steps into a flow of its own.`);
+        }
+    }
     /**
      * Emit a child flow into its own scope and register it under the calling
      * node's id — that key is how the format names a subflow body, and how
@@ -2252,7 +2352,7 @@ function serializeFlow(built, opts) {
      * The child gets its own manual Start node (a subflow always starts manually
      * — nothing schedules a subflow; its caller is the trigger) and its own
      * variables. A child's `.trigger(manual(), { label, version })` sets that
-     * node's canvas label and exact version; `check` refuses any other kind.
+     * node's canvas label and exact version; `refuseChildRoots` refuses any other kind.
      * Every `in` variable carries `triggerNodeId` pointing at that
      * Start: it is what binds the caller's value, and omitting it is the single
      * defect that makes a subflow validate clean and then fault at run time with
@@ -2803,8 +2903,9 @@ function serializeFlow(built, opts) {
         }
         // A type that owns a family of names (`typeNamePrefix`) is placed under the
         // name its definition carries — `uipath.core.function.<key>`, not the prefix.
-        // The bare prefix is allowed: an empty `key` builds it, check refuses that
-        // input (`*_NO_KEY`), and serialize alone emits what it always did.
+        // The bare prefix is a name the type owns, so it is not an internal error
+        // here; a type refuses a blank key itself when that is what builds it (the
+        // process family's `*_NO_KEY`, nodes/process/flow/refusals.ts).
         const prefix = entry.type.typeNamePrefix;
         const nodeType = prefix !== undefined ? def?.nodeType : impl.typeName;
         if (prefix !== undefined && (typeof nodeType !== 'string' || !nodeType.startsWith(prefix)
@@ -2889,6 +2990,43 @@ function serializeFlow(built, opts) {
             throw refusal;
         record(refusal, stepName, scope.stepNodeId.get(stepName) ?? scope.pending.get(stepName));
     }
+    /**
+     * Refuse a `.switch()` case the node cannot hold as written (#1518). Each
+     * case becomes one `{ id, expression }` row and one `case-<id>` port, so:
+     *  - SWITCH_CASE_FORM: a case needs exactly one of `value` (compared with
+     *    `on`) and `when` (its own condition). With both, only `when` would be
+     *    written and the value dropped; a `value` with no `on` would be written as
+     *    `undefined === 1`, and a case with neither as `undefined === undefined`,
+     *    which is always taken.
+     *  - SWITCH_CASE_ID: an id must be a non-empty string, and one per case. Two
+     *    cases on one id (an explicit `case_2` beside the positional one, #1130)
+     *    would share one `case-case_2` port, edges to both arms; a blank or
+     *    non-string id writes a `case-` / `case-5` port.
+     * In collect mode each one is reported on the switch, and the node is still
+     * written as authored, so the arms are judged.
+     */
+    function refuseSwitchCases(scope, step) {
+        const s = step.name;
+        const seenIds = new Set();
+        step.cases.forEach((c, i) => {
+            const hasValue = c.value !== undefined;
+            const hasWhen = c.when !== undefined;
+            if (hasValue === hasWhen || (hasValue && !step.on)) {
+                refuseOn(scope, s, new CompileRefusal('SWITCH_CASE_FORM', hasValue && hasWhen
+                    ? `Switch "${s}" case ${i + 1} has both \`value\` and \`when\`. Give it one: \`value\` is compared with \`on\`, \`when\` is the case's own condition.`
+                    : hasValue
+                        ? `Switch "${s}" case ${i + 1} has a \`value\` but the switch has no \`on\` to compare it with. Pass \`on\`, or give the case a \`when\` condition.`
+                        : `Switch "${s}" case ${i + 1} has neither \`value\` nor \`when\`.`));
+            }
+            const caseId = c.id ?? `case_${i + 1}`;
+            if (typeof caseId !== 'string' || caseId === '' || seenIds.has(caseId)) {
+                refuseOn(scope, s, new CompileRefusal('SWITCH_CASE_ID', typeof caseId !== 'string' || caseId === ''
+                    ? `Switch "${s}" case ${i + 1} has an id that is not a non-empty string. Leave \`id\` out for the positional case_<n>.`
+                    : `Switch "${s}" has two cases with the id "${caseId}", so both would leave from one 'case-${caseId}' port. Give one a different \`id\`.`));
+            }
+            seenIds.add(String(caseId));
+        });
+    }
     /** The step whose node `nodeId` is, in `scope`. */
     function stepOfNode(scope, nodeId) {
         for (const [name, id] of scope.stepNodeId)
@@ -2911,6 +3049,8 @@ function serializeFlow(built, opts) {
         catch (error) {
             const refusal = stepRefusal(error);
             record(refusal, name, id);
+            if (refusal instanceof LibraryRequiredRefusal && refusal.connection)
+                standInConnections.set(id, refusal.connection);
             root.nodes.length = mark.nodes;
             for (const key of [...resourceBindings.keys()])
                 if (!mark.resources.has(key))
@@ -2947,6 +3087,8 @@ function serializeFlow(built, opts) {
             const refusal = stepRefusal(error);
             const id = scope.stepNodeId.get(step.name) ?? stepUid(scope, step.name);
             record(refusal, step.name, id);
+            if (refusal instanceof LibraryRequiredRefusal && refusal.connection)
+                standInConnections.set(id, refusal.connection);
             scope.nodes.length = mark.nodes;
             scope.edges.length = mark.edges;
             scope.pendingEdges.length = mark.pendingEdges;
@@ -3026,6 +3168,7 @@ function serializeFlow(built, opts) {
         if (registered)
             return emitRegistered(registered, step, tails, scope, parentId);
         if (spec.kind === 'subflow') {
+            refuseChildRoots(spec.child, step.name);
             const id = stepUid(scope, step.name);
             // `subflows` is ONE flat map for the whole file, keyed by the calling
             // node's id. `stepUid` draws from the file-wide allocator, including in
@@ -3387,6 +3530,7 @@ function serializeFlow(built, opts) {
                 // the runtime — so no `=js:` prefix, same as a decision's `expression`.
                 const id = stepUid(scope, step.name);
                 const node = makeNode(NODE_TYPE.switch, id, step.options?.label ?? step.label ?? step.name, { parentId, requestedVersion: step.options?.version });
+                refuseSwitchCases(scope, step);
                 // `id` is the author's when given (a decompiled switch keeps the
                 // canvas's `default-1`, …: merge keeps the original node, so the edges
                 // must leave from ITS handles), else positional (#1130).
@@ -3785,6 +3929,14 @@ function serializeFlow(built, opts) {
         const firstShared = built.steps.find((st) => 'name' in st && st.kind !== 'return');
         const sharedTarget = firstShared && 'name' in firstShared ? root.stepNodeId.get(firstShared.name) : undefined;
         for (const ep of entryPoints) {
+            if (ep.id === 'start' && renamedTrigger) {
+                // Reported on the entry point; in collect mode it is still emitted (the
+                // id `start` is free in the file), so its prefix is judged too.
+                const refusal = startReadRefusal(`.entryPoint("${ep.id}")`, renamedTrigger, 'ENTRY_POINT_DUP_ID');
+                if (!opts.collect)
+                    throw refusal;
+                record(refusal, ep.id, ep.id);
+            }
             if (takenIds.has(ep.id)) {
                 throw new CompileRefusal('ENTRY_POINT_DUP_ID', `.entryPoint("${ep.id}"): the id collides with a step, the trigger, or another entry point.`);
             }
@@ -3955,7 +4107,7 @@ function serializeFlow(built, opts) {
     assertBindingPlaceholdersResolve(flow, unboundDrafts);
     assertFileWideIdsUnique(flow);
     assertConnectorConfigurationRestorable(flow);
-    connectionConnectors(flow);
+    connectionConnectors(flow, standInConnections);
     return flow;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.66.6",
+  "version": "6.66.8",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -100,5 +100,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "108478742e5fc426dc26ba07020d85a3fdbcaa66"
+  "gitref": "4800f0ca4d2a58eed272d12640145fc039e43a16"
 }