@uipath/maestro-builder-sdk 6.70.6 → 6.70.7

package/dist/case/task-output-ref.js

@@ -0,0 +1,212 @@
+/**
+ * Reading another task's output in place: the SDD's `vars.$xref('<stage>',
+ * '<task>', '<output>')` marker, and `taskOutput()`, the typed way to write it
+ * (builder-sdk#1241).
+ *
+ * A task's own output is a variable of its own: the Case Designer saves it as
+ * `{ name: 'AgentExpenseRequest', id: 'agentExpenseRequest', var:
+ * 'agentExpenseRequest' }`, with no root `variables` entry, and a later task
+ * reads it as `=vars.agentExpenseRequest`. The id is the plan's, not the
+ * author's: it is unique across the plan, so a second task's `Action` output
+ * is `action2`. An SDD therefore names an output by where it is produced, and
+ * `uip maestro case sdd convert` lowers each marker to `vars.<output id>`
+ * (`sdd-convert/xrefs.ts`). Without the lowering here, an author had to copy
+ * the value into a case variable the SDD does not declare, and `validate
+ * --strict --sdd` refuses each one (`STRICT_SDD_VARIABLE_EXTRA`).
+ *
+ * The rule lives here so `check` (at `build()`) and `serialize` read a marker
+ * the same way. `build()` cannot see the ids, which `serialize` mints, so it
+ * resolves the stage and the task, and the output where the task's rows are
+ * all authored (a reference-mode task). `serialize` resolves every marker
+ * against the rows it wrote and refuses one that names no output.
+ */
+/**
+ * One argument, read by its own delimiter: `'…'`, `"…"`, `` `…` `` or the curly
+ * pair, the four `sdd convert` accepts. A curly pair is two code points, so it
+ * gets its own branch instead of a backreference.
+ */
+const QUOTED = String.raw `(?:'((?:\\.|[^'\\])*)'|"((?:\\.|[^"\\])*)"|` +
+    '`((?:\\\\.|[^`\\\\])*)`' +
+    String.raw `|\u201c([^\u201d]*)\u201d)`;
+/** A `vars.$xref(stage, task, output)` marker. Global: use with `replace`/`matchAll` only. */
+const XREF_CALL = new RegExp(String.raw `vars\.\$xref\(\s*${QUOTED}\s*,\s*${QUOTED}\s*,\s*${QUOTED}\s*\)`, 'g');
+/**
+ * A property read glued to the marker (`vars.$xref(…).unusualClauses`). The
+ * producer may not have run when the reader does, so inside a `=js:`
+ * expression the lowering writes the optional chain
+ * `vars.<id>?.unusualClauses`, as `sdd convert` does. Only there: `?.` is
+ * JavaScript, and nothing shows that the platform's non-js `=vars.<path>`
+ * binding reads it, so any other value keeps the plain `.`.
+ */
+const DOTTED_READ = /^\.[A-Za-z_$]/;
+const unescape = (value) => value.replace(/\\(.)/g, '$1');
+/** Each marker in `text`, in order, with where it sits. */
+export function taskOutputRefs(text) {
+    if (!text.includes('$xref'))
+        return [];
+    return [...text.matchAll(XREF_CALL)].map((m) => {
+        const arg = (from) => unescape(m.slice(from, from + 4).find((v) => v !== undefined) ?? '');
+        return { stage: arg(1), task: arg(5), output: arg(9), whole: m[0], index: m.index ?? 0 };
+    });
+}
+/**
+ * Replace every marker in `text` with what `lower` returns for it. In a `=js:`
+ * expression, a marker followed by a property read gets the optional chain
+ * (`vars.<id>?.field`); any other value keeps the plain read (`vars.<id>.field`).
+ *
+ * @param text - The expression.
+ * @param lower - The variable a marker reads (`agentExpenseRequest`), or `undefined` to keep the marker.
+ */
+export function lowerTaskOutputRefs(text, lower) {
+    if (!text.includes('$xref'))
+        return text;
+    const js = /^\s*=js:/.test(text);
+    let out = '';
+    let at = 0;
+    for (const ref of taskOutputRefs(text)) {
+        const after = text.slice(ref.index + ref.whole.length);
+        const variable = lower(ref);
+        // `undefined` keeps the marker as written (a reference to a stand-in; see `resolveInPlan`).
+        out += variable === undefined ? text.slice(at, ref.index) + ref.whole : `${text.slice(at, ref.index)}vars.${variable}${js && DOTTED_READ.test(after) ? '?' : ''}`;
+        at = ref.index + ref.whole.length;
+    }
+    return out + text.slice(at);
+}
+/**
+ * The one candidate `name` picks out: an exact match first, then a
+ * case-insensitive one (an SDD addresses a stage or an output in any case).
+ * `undefined` when none does; `'ambiguous'` when more than one does.
+ */
+export function pickByName(items, name, names) {
+    for (const same of [(a) => a === name, (a) => a.toLowerCase() === name.toLowerCase()]) {
+        const hits = [...new Set(items.filter((item) => names(item).some((n) => n !== undefined && same(n))))];
+        if (hits.length === 1)
+            return hits[0];
+        if (hits.length > 1)
+            return 'ambiguous';
+    }
+    return undefined;
+}
+/**
+ * The row an output reference names among one task's rows: by the field it
+ * reads (`name`) or by the variable it writes (`var`).
+ */
+export function pickOutputRow(rows, output) {
+    return pickByName(rows, output, (row) => [row.name, row.var]);
+}
+/** The refusal message for a marker that resolves to nothing. */
+export function unresolvedTaskOutputRef(ref, why) {
+    return `taskOutput(${JSON.stringify(ref.stage)}, ${JSON.stringify(ref.task)}, ${JSON.stringify(ref.output)}) ${why}. ` +
+        'A task-output reference names the stage label, the task name and the output (the result field it reads, or the key it has in `.outputs()`).';
+}
+/**
+ * The marker for a reference: `vars.$xref('<stage>','<task>','<output>')`,
+ * each argument single-quoted with its quotes and backslashes escaped. What
+ * `taskOutput()` returns, and what decompile writes back.
+ */
+export function taskOutputMarker(stage, task, output) {
+    const quote = (value) => `'${value.replace(/[\\']/g, '\\$&')}'`;
+    return `vars.$xref(${quote(stage)},${quote(task)},${quote(output)})`;
+}
+/** Every stage task's output rows in a written caseplan, in document order. */
+export function planTaskOutputs(plan) {
+    const found = [];
+    const nodes = plan?.nodes;
+    for (const node of Array.isArray(nodes) ? nodes : []) {
+        const data = node?.data;
+        if (typeof data?.label !== 'string' || !Array.isArray(data.tasks))
+            continue;
+        for (const lane of data.tasks)
+            for (const task of Array.isArray(lane) ? lane : []) {
+                if (typeof task?.displayName !== 'string')
+                    continue;
+                const rows = Array.isArray(task.data?.outputs) ? task.data.outputs : [];
+                found.push({
+                    stage: data.label,
+                    task: task.displayName,
+                    rows: rows.filter((row) => row && typeof row === 'object'),
+                    ...(task.data?.standIn === true ? { standIn: true } : {}),
+                });
+            }
+    }
+    return found;
+}
+/**
+ * What a reference reads in a written plan: the variable of the row it names
+ * (`vars.<id>`, or a custom row's `var`, which has no id), or why it names none.
+ */
+export function resolveInPlan(tasks, ref) {
+    const stage = pickByName([...new Set(tasks.map((t) => t.stage))], ref.stage, (label) => [label]);
+    if (stage === undefined)
+        return { why: `names no stage labelled ${JSON.stringify(ref.stage)}` };
+    if (stage === 'ambiguous')
+        return { why: `names a stage label that more than one stage answers to` };
+    const task = pickByName(tasks.filter((t) => t.stage === stage), ref.task, (t) => [t.task]);
+    if (task === undefined)
+        return { why: `names no task ${JSON.stringify(ref.task)} in stage ${JSON.stringify(stage)}` };
+    if (task === 'ambiguous')
+        return { why: `names a task that more than one task in stage ${JSON.stringify(stage)} answers to` };
+    // The named task was refused and stood in (collect mode). Its refusal is the
+    // finding; its outputs were never written, so there is nothing to judge the
+    // reference against here (`build()` already judged it against the authored ones).
+    if (task.standIn)
+        return { standIn: true };
+    const row = pickOutputRow(task.rows, ref.output);
+    const offered = [...new Set(task.rows.map((r) => r.name).filter((n) => typeof n === 'string'))];
+    if (row === undefined)
+        return { why: `names no output of task ${JSON.stringify(task.task)}, whose outputs are ${offered.length ? offered.map((n) => JSON.stringify(n)).join(', ') : 'none'}` };
+    if (row === 'ambiguous')
+        return { why: `names more than one output of task ${JSON.stringify(task.task)}; name it by the variable it writes instead` };
+    const variable = typeof row.id === 'string' && row.id ? row.id : row.var;
+    if (typeof variable !== 'string' || !variable)
+        return { why: `names an output of task ${JSON.stringify(task.task)} that writes no variable` };
+    return { variable };
+}
+/**
+ * Turn each `vars.<output id>` read in `text` that only a task-output reference
+ * can say back into `vars.$xref(…)`, for decompile. `byId` maps such an id to
+ * the reference that names it.
+ */
+export function raiseTaskOutputReads(text, byId) {
+    if (!byId.size || !text.includes('vars.'))
+        return text;
+    return text.replace(/(?<![\w$.])vars\.([A-Za-z_$][\w$]*)(?![\w$])/g, (whole, id) => {
+        const ref = byId.get(id);
+        return ref ? taskOutputMarker(ref.stage, ref.task, ref.output) : whole;
+    });
+}
+/**
+ * The output ids a decompiled source can only read back by reference: a row
+ * whose id is not the variable it writes (a reassigned extract, a Designer row
+ * such as `{ id: 'oA1b2C3d4', var: 'AgentExpenseRequest' }`). Recompiling mints
+ * that id afresh, and no declaration makes `vars.<id>` readable, so a
+ * `vars.<id>` read in the plan goes back to the source as the reference that
+ * resolves to the same row. A read of an id that is also a variable (an
+ * own-name row, a root variable) is left as written. A row the reference
+ * could not name uniquely is left as written too.
+ */
+export function referableOutputIds(plan, rootNames) {
+    const tasks = planTaskOutputs(plan);
+    const vars = new Set(rootNames);
+    for (const task of tasks)
+        for (const row of task.rows)
+            if (typeof row.var === 'string')
+                vars.add(row.var);
+    const byId = new Map();
+    for (const task of tasks)
+        for (const row of task.rows) {
+            if (typeof row.id !== 'string' || !row.id || row.id === row.var || vars.has(row.id))
+                continue;
+            for (const output of [row.name, row.var]) {
+                if (typeof output !== 'string' || !output)
+                    continue;
+                const ref = { stage: task.stage, task: task.task, output };
+                const resolved = resolveInPlan(tasks, ref);
+                if ('variable' in resolved && resolved.variable === row.id) {
+                    byId.set(row.id, ref);
+                    break;
+                }
+            }
+        }
+    return byId;
+}

package/dist/core/refusals.d.ts

@@ -640,6 +640,7 @@ export declare const REFUSALS: {
     readonly TASK_OUTPUTS_NO_RESPONSE: "lowering";
     readonly TASK_OUTPUTS_PLACEHOLDER_EVENT: "lowering";
     readonly TASK_OUTPUTS_UNSUPPORTED: "lowering";
+    readonly TASK_OUTPUT_REF_UNRESOLVED: "lowering";
     readonly TASK_OUTPUT_SOURCE_AND_ASSIGN: "lowering";
     readonly TASK_REENTRY_IGNORED: "lint";
     readonly TASK_TIMER_OUT_OF_RANGE: "lint";

package/dist/core/refusals.js

@@ -692,6 +692,7 @@ export const REFUSALS = {
     TASK_OUTPUTS_NO_RESPONSE: 'lowering',
     TASK_OUTPUTS_PLACEHOLDER_EVENT: 'lowering',
     TASK_OUTPUTS_UNSUPPORTED: 'lowering',
+    TASK_OUTPUT_REF_UNRESOLVED: 'lowering',
     TASK_OUTPUT_SOURCE_AND_ASSIGN: 'lowering',
     TASK_REENTRY_IGNORED: 'lint',
     TASK_TIMER_OUT_OF_RANGE: 'lint',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.70.6",
+  "version": "6.70.7",
   "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": "acb0888df4770ee4db5ebb89ef2116cf400ee1b9"
+  "gitref": "31471f814e8ca706a02e96e3dbceb39641584de6"
 }