@uipath/maestro-builder-sdk 6.33.1 → 6.34.0

package/dist/merge-variables.js

@@ -0,0 +1,191 @@
+/**
+ * merge-variables — the delta rule for a flow's root `variables` (#1261).
+ *
+ * Nodes merge as a delta: one the author did not touch (edited equals
+ * baseline) is restored from the original. `variables` follow the same rule.
+ *
+ * The same rule, applied at three levels:
+ *
+ *   - the whole section: edited equals baseline → the original's, verbatim;
+ *   - a top-level key (`globals`, `nodes`, `variableUpdates`): edited equals
+ *     baseline → the original's (absent stays absent);
+ *   - an entry of an id-keyed list (`globals`, `nodes`) or a key of a map
+ *     (`variableUpdates`): the same, and inside an entry each field the same,
+ *     so an edited global's new `type` lands without the `name` compile adds.
+ *
+ * Presence follows the same logic. An entry the edited file lacks was removed
+ * by the author when the baseline has it, and lost by the round trip when it
+ * does not (kept). An entry the original lacks is the author's when the
+ * baseline lacks it or differs, and the round trip's when the baseline has it
+ * unchanged (dropped).
+ *
+ * Example, after the author changes `creditAmount`'s type and nothing else:
+ *
+ *     original  { id: 'creditAmount', direction: 'out', type: 'string' }
+ *     baseline  { id: 'creditAmount', name: 'creditAmount', direction: 'out', type: 'string' }
+ *     edited    { id: 'creditAmount', name: 'creditAmount', direction: 'out', type: 'number' }
+ *     merged    { id: 'creditAmount', direction: 'out', type: 'number' }
+ *
+ * An original with no `variables` section, or with no `globals` / `nodes` /
+ * `variableUpdates` key, is treated as empty there: what compile minted for
+ * the untouched part is still the round trip's, and only the author's
+ * additions land.
+ *
+ * Without a baseline there is nothing to tell an edit from the round trip, so
+ * the edited section is taken whole. So is a section whose original uses a key
+ * this file does not know (the older map spelling, `variables.city = {...}`)
+ * once the author changed anything: mixing two spellings in one section is
+ * worse than taking the compile's. The round-trip report still lists what that
+ * carries, but does not refuse it under `--strict`, because the author cannot
+ * avoid it short of making no edit ({@link isDeltaSpelling}).
+ */
+import { jsonClone } from './core/json-clone.js';
+import { CONTAINER_KEYS } from './flow-variables.js';
+/** `jsonClone`, which also passes `undefined` (an absent section or key) through. */
+const copy = (v) => (v === undefined ? v : jsonClone(v));
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** JSON with object keys sorted, so key order is not a difference. */
+export function stableJson(v) {
+    return JSON.stringify(v, (_k, val) => (isObj(val)
+        ? Object.fromEntries(Object.keys(val).sort().map((k) => [k, val[k]]))
+        : val));
+}
+const same = (a, b) => stableJson(a) === stableJson(b);
+/**
+ * Whether `variables` is spelled the way the delta reads it: absent, or an
+ * object whose keys are only the container keys (`globals`, `nodes`,
+ * `variableUpdates`). A map-spelled original is not, and is taken whole.
+ */
+export function isDeltaSpelling(variables) {
+    return variables === undefined || (isObj(variables) && Object.keys(variables).every((k) => CONTAINER_KEYS.has(k)));
+}
+/**
+ * The merged root `variables`. `goneNodeIds` are the original's nodes (root and
+ * subflows) the merged file no longer has: a node variable, or a
+ * `variableUpdates` key, kept from the original for one of them is dropped
+ * with the node.
+ */
+export function mergeVariables(original, edited, baseline, goneNodeIds) {
+    if (!baseline)
+        return copy(edited);
+    const base = baseline.variables;
+    if (same(edited, base))
+        return withoutGoneUpdates(copy(original), goneNodeIds);
+    if (!isDeltaSpelling(original) || !isObj(edited))
+        return copy(edited);
+    const orig = isObj(original) ? original : {};
+    const baseObj = isObj(base) ? base : {};
+    const out = {};
+    for (const key of keysInOrder(orig, edited)) {
+        const updates = key === 'variableUpdates';
+        const inner = updates
+            ? (o, b, e) => (isObj(o) && isObj(e) ? mergeFields(o, isObj(b) ? b : undefined, e) : copy(e))
+            : (o, b, e) => mergeList(o, b, e, goneNodeIds);
+        // A section the original lacks but the round trip writes is merged as an
+        // empty one, so its minted entries stay out and only the author's land.
+        const absent = !(key in orig) && key in baseObj && key in edited && !same(edited[key], baseObj[key]);
+        const value = absent
+            ? nonEmpty(inner(updates ? {} : [], baseObj[key], edited[key]))
+            : mergeKey(orig[key], baseObj[key], edited[key], key in orig, key in baseObj, key in edited, inner);
+        if (value !== undefined)
+            out[key] = value;
+    }
+    if (original === undefined && Object.keys(out).length === 0)
+        return undefined;
+    return withoutGoneUpdates(out, goneNodeIds);
+}
+/** `undefined` for an empty list or map, so an absent section stays absent. */
+function nonEmpty(v) {
+    if (Array.isArray(v))
+        return v.length ? v : undefined;
+    if (isObj(v))
+        return Object.keys(v).length ? v : undefined;
+    return v;
+}
+/**
+ * `variables` without the `variableUpdates` keys (node ids) of nodes the merge
+ * dropped. A key the round trip lost is kept from the original, so without
+ * this it would outlive its node.
+ */
+function withoutGoneUpdates(variables, goneNodeIds) {
+    const updates = isObj(variables) ? variables.variableUpdates : undefined;
+    if (!isObj(updates) || !Object.keys(updates).some((k) => goneNodeIds.has(k)))
+        return variables;
+    return { ...variables, variableUpdates: Object.fromEntries(Object.entries(updates).filter(([k]) => !goneNodeIds.has(k))) };
+}
+/** Original's keys in its order, then the edited file's new ones. */
+function keysInOrder(original, edited) {
+    return [...Object.keys(original), ...Object.keys(edited).filter((k) => !(k in original))];
+}
+/**
+ * One key's value under the delta rule; `undefined` = leave the key out.
+ * `inner` merges a value both sides have and the author changed.
+ */
+function mergeKey(o, b, e, inOriginal, inBaseline, inEdited, inner) {
+    if (!inEdited)
+        return inBaseline || !inOriginal ? undefined : copy(o); // removed by the author / lost by the round trip
+    if (inBaseline && same(e, b))
+        return inOriginal ? copy(o) : undefined; // untouched
+    if (!inOriginal)
+        return copy(e); // the author's addition
+    return inner(o, b, e);
+}
+/** An id-keyed list (`globals`, `nodes`): per entry, then per field. */
+function mergeList(o, b, e, goneNodeIds) {
+    if (!idList(o) || !idList(e))
+        return copy(e);
+    const base = new Map((idList(b) ? b : []).map((x) => [x.id, x]));
+    const edits = new Map(e.map((x) => [x.id, x]));
+    const out = [];
+    for (const entry of o) {
+        const id = entry.id;
+        if (!edits.has(id)) {
+            // The author removed it (baseline has it), or the round trip lost it; a
+            // lost node variable whose node is gone goes with the node.
+            if (!base.has(id) && !boundToGoneNode(entry, goneNodeIds))
+                out.push(copy(entry));
+            continue;
+        }
+        const ed = edits.get(id);
+        out.push(base.has(id) && same(ed, base.get(id)) ? copy(entry) : mergeFields(entry, base.get(id), ed));
+    }
+    const originalIds = new Set(o.map((x) => x.id));
+    for (const [i, ed] of e.entries()) {
+        const id = ed.id;
+        if (originalIds.has(id) || (base.has(id) && same(ed, base.get(id))))
+            continue; // kept above / minted by the round trip
+        out.splice(insertAt(out, e, i), 0, copy(ed));
+    }
+    return out;
+}
+/** After the nearest earlier edited entry already in `out`, else first. */
+function insertAt(out, edited, i) {
+    for (let j = i - 1; j >= 0; j--) {
+        const at = out.findIndex((x) => x.id === edited[j].id);
+        if (at >= 0)
+            return at + 1;
+    }
+    return 0;
+}
+/**
+ * An object the author changed — a list entry, or the `variableUpdates` map
+ * (keyed by node id): each key under the delta rule, each value taken whole,
+ * keys in the original's order.
+ */
+function mergeFields(o, b, e) {
+    const base = b ?? {};
+    const out = {};
+    for (const key of keysInOrder(o, e)) {
+        const v = mergeKey(o[key], base[key], e[key], key in o, key in base, key in e, (_o, _b, ev) => copy(ev));
+        if (v !== undefined)
+            out[key] = v;
+    }
+    return out;
+}
+function idList(v) {
+    return Array.isArray(v) && v.every((x) => isObj(x) && typeof x.id === 'string');
+}
+function boundToGoneNode(entry, goneNodeIds) {
+    const nodeId = isObj(entry.binding) ? entry.binding.nodeId : undefined;
+    return typeof nodeId === 'string' && goneNodeIds.has(nodeId);
+}

package/dist/merge.d.ts

@@ -26,7 +26,8 @@
  *
  * Layout, `metadata`, `solutionId`, `projectId`, `runtime` and `layout` are
  * preserved from the original; `subflows` and edges (with their ids) come from
- * `edited`; `definitions` and `bindings` are unioned
+ * `edited`; root `variables` merge as a delta per entry, like nodes
+ * (merge-variables.ts); `definitions` and `bindings` are unioned
  * (original wins on conflict, since the original's are the tenant-resolved
  * authority). A binding row's identity is what it binds, not its row id, and a
  * row the no-edit recompile minted only for nodes merge kept from the original
@@ -143,8 +144,8 @@ export interface MergeOptions {
      * - with a `baseline`, each wire-identity difference between the baseline
      *   (the no-edit round trip) and the original — a node or edge added, dropped
      *   or rewired, a switch case id or human-task outcome id renamed, a binding
-     *   row added or dropped — that the merged file still carries, i.e. the
-     *   author's edit did not undo it;
+     *   row added or dropped, a root `variables` entry added or rewritten — that
+     *   the merged file still carries, i.e. the author's edit did not undo it;
      * - an edited node whose `typeVersion` differs from the original node with
      *   the same id, because the edit took the SDK's version;
      * - a merged edge whose `sourcePort` is not a handle its source node declares,

package/dist/merge.js

@@ -26,7 +26,8 @@
  *
  * Layout, `metadata`, `solutionId`, `projectId`, `runtime` and `layout` are
  * preserved from the original; `subflows` and edges (with their ids) come from
- * `edited`; `definitions` and `bindings` are unioned
+ * `edited`; root `variables` merge as a delta per entry, like nodes
+ * (merge-variables.ts); `definitions` and `bindings` are unioned
  * (original wins on conflict, since the original's are the tenant-resolved
  * authority). A binding row's identity is what it binds, not its row id, and a
  * row the no-edit recompile minted only for nodes merge kept from the original
@@ -89,6 +90,7 @@ import { MergeRefusedError, mergedFileFindings, roundTripFindings } from './merg
 import { placeAddedNodes } from './node-placement.js';
 import { mergeAgentSidecars } from './merge-sidecars.js';
 import { embeddedAgentFindings, isEmbeddedAgent, mergeEmbeddedAgentNode } from './merge-embedded-agent.js';
+import { mergeVariables } from './merge-variables.js';
 export { MergeRefusedError } from './merge-roundtrip.js';
 function byId(nodes) {
     return new Map((nodes ?? []).map((n) => [n.id, n]));
@@ -256,8 +258,7 @@ function mergeFlowFindings(original, edited, options) {
     result.nodes = finalNodes;
     // Nodes present in the original but absent from `edited` were deleted by the
     // user; they are simply not carried over.
-    // ── Variables & subflows: the edited flow is authoritative (the user's graph). ──
-    result.variables = jsonClone(edited.variables);
+    // ── Subflows: the edited flow is authoritative (the user's graph). ──
     result.subflows = jsonClone(edited.subflows ?? {});
     // A subflow is taken from `edited` whole, so an embedded agent inside one
     // would flip to the edited shell even with no edit. Keep it embedded too.
@@ -267,6 +268,20 @@ function mergeFlowFindings(original, edited, options) {
     if (options.baseline)
         keepOriginalSourcesInSubflows(original, result.subflows, options.baseline);
     const subflowScopes = Object.values(result.subflows);
+    // ── Variables: the same delta as nodes, per entry — what the author did not
+    //    change stays the original's, so compile's own spellings (an added
+    //    `name`, a re-derived End output type) do not reach the file (#1261).
+    //    See merge-variables.ts. ──
+    const mergedNodeIds = new Set([...finalNodes, ...subflowScopes.flatMap((sf) => sf?.nodes ?? [])].map((n) => n.id));
+    const goneNodeIds = new Set([
+        ...(original.nodes ?? []),
+        ...Object.values(original.subflows ?? {}).flatMap((sf) => sf?.nodes ?? []),
+    ].map((n) => n.id).filter((id) => !mergedNodeIds.has(id)));
+    const variables = mergeVariables(original.variables, edited.variables, options.baseline, goneNodeIds);
+    if (variables === undefined)
+        delete result.variables;
+    else
+        result.variables = variables;
     // ── Edges: the edited graph's edges define the wiring, under the edited
     //    file's own ids. compile draws every edge id — root AND subflows — from
     //    one file-wide counter, so they are already unique. Renumbering the root

package/dist/schema-version.js

@@ -106,11 +106,16 @@ export function schemaVersionRefusal(policy, requested) {
     if (isWritableSchemaVersion(policy, requested))
         return undefined;
     const writable = writableSchemaVersions(policy);
+    const newestWritable = writable.at(-1);
     const direction = policy.latestKnown !== undefined && schemaVersionAtLeast(requested, policy.latestKnown)
         ? compareSchemaVersions(requested, policy.latestKnown) > 0
             ? `The platform's newest known ${family} schema version is ${policy.latestKnown}, so ${requested} is newer than anything this SDK has read.`
             : `${requested} is the platform's current ${family} schema version, but this SDK build has not been taught to write it.`
-        : `${requested} is older than the ${writable.length === 1 ? 'one version' : 'versions'} this build writes.`;
+        : newestWritable !== undefined && compareSchemaVersions(requested, newestWritable) > 0
+            ? `${requested} is a platform ${family} schema version newer than this build writes`
+                + (policy.latestKnown !== undefined ? ` (the platform's current is ${policy.latestKnown})` : '')
+                + '; this SDK build has not been taught to write it.'
+            : `${requested} is older than the ${writable.length === 1 ? 'one version' : 'versions'} this build writes.`;
     return (`${method}("${requested}"): this SDK build writes ${family} schema ${writable.join(' / ')}. ${direction} `
         + `A document's version claims that the WHOLE document matches that schema, so declaring one this build cannot emit `
         + `would write a false claim rather than a different document. ${policy.migration}`);

package/package.json

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