@uipath/maestro-builder-sdk 5.3.1 → 5.4.0

package/dist/check.js

@@ -104,6 +104,13 @@ function checkFlow(built, ancestors, opts = {}) {
     // (and their declared outcome ids), and which ids actually got a route.
     const hitlOutcomeSteps = new Map();
     const hitlOutcomeRouted = new Map();
+    // The other half of that bookkeeping: hitl steps that declare a CHOICE (more
+    // than one outcome) and did NOT opt into per-outcome exits, so the graph gives
+    // every outcome the same single exit. Whether that is a mistake depends on
+    // something no single step can see — whether anything downstream reads the
+    // chosen outcome — so the decision waits until the expressions are collected
+    // (see HITL_OUTCOMES_UNREACHABLE below).
+    const hitlChoiceNoPorts = new Map();
     const dataFabricUpdates = [];
     // Placeholder (`mock()`) step names. The platform's `core.logic.mock` declares
     // one output whose `source` is the literal `"null"` — it publishes nothing —
@@ -322,6 +329,19 @@ function checkFlow(built, ancestors, opts = {}) {
                 if (s.spec.kind === 'hitl') {
                     checkHitl(s.name, s.spec.inputs, diags);
                     hitlForms.set(s.name, s.spec.inputs);
+                    const outcomes = s.spec.inputs?.outcomes ?? [];
+                    // `action: 'End'` ends the PROCESS at the node, so a task whose every
+                    // outcome ends it has nothing downstream to distinguish — one exit is
+                    // the whole truth there, and the rule below would be a false positive.
+                    const allEnd = outcomes.length > 0
+                        && outcomes.every((o) => typeof o !== 'string' && o?.action === 'End');
+                    if (outcomes.length > 1 && !allEnd
+                        && s.spec.inputs?.outcomePorts !== true && s.spec.inputs?.exposeError !== true) {
+                        hitlChoiceNoPorts.set(s.name, {
+                            names: outcomes.map((o) => String((typeof o === 'string' ? o : o?.name) ?? '').trim()),
+                            variant: s.spec.inputs?.variant,
+                        });
+                    }
                 }
                 if (s.spec.kind === 'rpaWorkflow')
                     checkRpaWorkflow(s.name, s.spec.inputs, diags);
@@ -577,6 +597,7 @@ function checkFlow(built, ancestors, opts = {}) {
             });
         }
     }
+    reportUnreachableHitlOutcomes(hitlChoiceNoPorts, exprs, diags);
     for (const { step, inputs } of dataFabricUpdates) {
         const fromRead = inputs.record?.fromRead;
         if (typeof fromRead === 'string' && !dataFabricReads.has(fromRead)) {
@@ -3821,6 +3842,78 @@ function outcomeSlug(name, index) {
         .replace(/^-+|-+$/g, '');
     return slug || `outcome-${index + 1}`;
 }
+/**
+ * HITL_OUTCOMES_UNREACHABLE — a human task offers the reviewer a CHOICE that
+ * nothing downstream can act on.
+ *
+ * `outcomes` and `outcomePorts` are two halves of one decision, and only the
+ * first half reads as load-bearing. Declaring outcomes without the flag emits
+ * the node's 1.0 definition, whose ONE source handle is `completed`: the
+ * outcomes still reach the reviewer and still appear in
+ * `inputs.schema.outcomes`, and then every button the reviewer can press leaves
+ * the node the same way. Two outcomes, one path — an approval whose approve and
+ * reject arms are indistinguishable is a modelling error, not a style choice,
+ * yet it compiles and `flow validate` answers `Valid` (flow-builder-sdk#735).
+ *
+ * The one thing that makes the single-exit shape correct is a read of the
+ * chosen outcome: `out('<step>', 'Action')` feeding a `.switch()` is the
+ * DEFAULT documented shape, and it is the only shape the quick-form,
+ * action-app and document-validation variants have — they carry no per-outcome
+ * definition for `outcomePorts` to select (HITL_OUTCOME_PORTS_VARIANT). So the
+ * rule is not "outcomes without ports", which would refuse that shape; it is
+ * "outcomes that no exit and no expression distinguishes". That is why it runs
+ * here, after `walk`, rather than inside `checkHitl`: the deciding evidence is
+ * the rest of the flow.
+ *
+ * A read counts when it can SEE the outcome — `.output.Action`, the whole
+ * answer object (`out('<step>')` / `$vars.<step>.output`, which carries
+ * `Action` into a script), `.status` (the platform's own projection of it,
+ * redirected by HITL_READ_STATUS but still an author reaching for the outcome),
+ * a bare `$vars.<step>`, or any bracket read, whose path this scan cannot
+ * resolve. One named answer field (`$vars.<step>.output.note`) does not: it
+ * says nothing about which button was pressed.
+ *
+ * A warning, not an error, for the same reason HITL_OUTCOME_UNROUTED is: the
+ * artifact deploys and the task works — what is lost is the branch.
+ */
+function reportUnreachableHitlOutcomes(choices, exprs, diags) {
+    if (choices.size === 0)
+        return;
+    const readsOutcome = new Set();
+    for (const { js } of exprs) {
+        for (const m of js.matchAll(/\$vars\.([A-Za-z0-9_]+)(?:\.([A-Za-z0-9_]+))?(?:\.([A-Za-z0-9_]+))?/g)) {
+            const [, name, field, tail] = m;
+            if (field === undefined || field === 'status')
+                readsOutcome.add(name);
+            else if (field === 'output' && (tail === undefined || tail === 'Action'))
+                readsOutcome.add(name);
+        }
+        // `$vars.<step>['output']` — VARS_BRACKET_READ's shape. The path is not
+        // statically resolvable here, so it counts as a read: this rule fails open.
+        for (const m of js.matchAll(/\$vars\.([A-Za-z0-9_]+)\s*\[/g))
+            readsOutcome.add(m[1]);
+    }
+    for (const [step, { names, variant }] of choices) {
+        if (readsOutcome.has(step))
+            continue;
+        const ids = names.map((n, i) => outcomeSlug(n, i));
+        diags.push({
+            level: 'warning', code: 'HITL_OUTCOMES_UNREACHABLE', step,
+            message: `Human task "${step}" declares ${names.length} outcomes (${names.join(', ')}), but nothing `
+                + `downstream tells them apart: the node emits its single 'completed' exit and every outcome leaves `
+                + `on it, and no expression reads out('${step}', 'Action') either. The outcomes reach the reviewer `
+                + `and the artifact; the decision does not reach the flow. `
+                + (variant === undefined
+                    ? `Set outcomePorts: true to give each outcome its own exit (${ids.map((i) => `'outcome-${i}'`).join(', ')}), `
+                        + `or switch on out('${step}', 'Action') to route it as data.`
+                    : `The "${variant}" variant has no per-outcome definition for outcomePorts to select, so switch on `
+                        + `out('${step}', 'Action') to route it as data.`),
+            suggestion: variant === undefined
+                ? 'outcomePorts: true'
+                : `.switch('route', out('${step}', 'Action'), …)`,
+        });
+    }
+}
 /**
  * A human task's form.
  *

package/dist/core/actions.d.ts

@@ -564,7 +564,11 @@ export interface HitlInputs {
     /**
      * The completion buttons, e.g. `['Approve', 'Reject']`. At least one, or the
      * reviewer has no way to complete the task and the flow waits forever. The
-     * first is the primary (default) one.
+     * first is the primary (default) one. Declaring them creates no EXITS: with
+     * more than one, set `outcomePorts` to fork in the graph, or read
+     * `out('<step>', 'Action')` to route as data. With neither, every outcome
+     * leaves on the same `completed` exit and nothing downstream can tell them
+     * apart — which `check` warns about as `HITL_OUTCOMES_UNREACHABLE`.
      *
      * Which one they pressed is `out('<step>', 'Action')` — that is what the
      * platform's own routing conditions compare against, so branch on it.
@@ -578,7 +582,9 @@ export interface HitlInputs {
      * Route each outcome from its OWN port instead of the single `completed`
      * exit. Selects the node's **1.1** definition, whose exits are
      * `outcome-<id>` handles (one per outcome; ids are the outcome names
-     * slugified, e.g. `'Approve'` → `outcome-approve`).
+     * slugified, e.g. `'Approve'` → `outcome-approve`). It REPLACES `completed`
+     * rather than adding to it, and it is not an optional refinement — see
+     * `outcomes` for the choice it is one half of.
      *
      * The FIRST (primary) outcome continues the main path; route the others with
      * `.stepToList('outcome-<id>', …)`. Base variant only — the sub-typed nodes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "5.3.1",
+  "version": "5.4.0",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -87,5 +87,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "dbd94aff19eeaff9d162b8d4e3ee923554fb5c2a"
+  "gitref": "b5c108408c7198fa36dcaf2c8d84bf46b3c1ee72"
 }