@uipath/maestro-builder-sdk 6.19.0 → 6.20.1

package/dist/merge-roundtrip.js

@@ -0,0 +1,404 @@
+/**
+ * merge-roundtrip — what the no-edit round trip changed that the merged file
+ * still carries, and what the merged file gets wrong from mixing its sources.
+ *
+ * `merge` is given `baseline = compile(decompile(original))`, the round trip of
+ * the original with NO edit. Wherever baseline and original differ in wire
+ * identity, decompile or compile lost or invented something. The merged file
+ * inherits that change unless the author's edit undid it, so each difference is
+ * reported only when the merged file still differs from the original at that
+ * spot. For example:
+ *
+ *     original:  logFailure1@success -> forEachItem1@continue
+ *     baseline:  logFailure1@success -> callApi1ErrorEnd@input      (validate: Success)
+ *
+ * is reported when the merged file has the `callApi1ErrorEnd` edge, and not
+ * when the author re-wired `logFailure1@success` back to `forEachItem1@continue`
+ * in the edited source.
+ *
+ * BPMN has the same invariant as a gate: `bpmn/lift-verify.ts` builds both
+ * sources and writes the nested one only when the graphs agree. Here the two
+ * graphs are already built, so this compares them directly:
+ *
+ * - node ids (per scope: the root and each subflow), and the type of a node the
+ *   merge takes from the edited side;
+ * - edges as `(source, sourcePort, target, targetPort)`; edge ids are not
+ *   identity;
+ * - switch case ids and human-task outcome ids, which name the handles the
+ *   edges leave from;
+ * - binding rows by what they bind (`core/binding-identity.ts`), never by the
+ *   row `id`.
+ *
+ * Two checks run on the MERGED file whatever the baseline says, because merge
+ * mixes sources (untouched nodes from the original, edges from the edited file):
+ *
+ * - every root edge leaves from a handle its source node declares — the static
+ *   handles of the node's definition, its `repeat` handles expanded over the
+ *   node's inputs (`case-{item.id}` over `inputs.cases`), and for a human task
+ *   the `outcome-<id>` handles the product derives from its outcomes. This is
+ *   the rule `flow validate` applies ("Edge references undeclared source
+ *   handle");
+ * - no two binding rows bind the same resource property.
+ *
+ * Two classes are reported but never refused, because the merged file does the
+ * same thing as the original:
+ *
+ * - an End the compile appends to a tail the original left open. The canvas
+ *   does not require a trailing End, the SDK always writes one, and a path that
+ *   runs out of nodes ends either way;
+ * - a binding row the round trip drops. Merge keeps every original row, so the
+ *   merged file still has it.
+ */
+import { bindingIdentity } from './core/binding-identity.js';
+import { OUTCOME_HANDLE_NODE_TYPES } from './core/hitl-routing.js';
+/** A file's definitions, keyed `nodeType@version`. */
+function defsOf(f) {
+    const out = new Map();
+    for (const d of f.definitions ?? [])
+        out.set(`${String(d.nodeType)}@${String(d.version)}`, d);
+    return out;
+}
+const defOf = (defs, n) => defs.get(`${n.type}@${String(n.typeVersion)}`);
+/** The root and every subflow, keyed `''` for the root and `subflows.<key>` otherwise. */
+function scopesOf(f) {
+    const out = new Map([['', { nodes: f.nodes ?? [], edges: f.edges ?? [] }]]);
+    for (const [key, sf] of Object.entries(f.subflows ?? {})) {
+        const s = (sf ?? {});
+        out.set(`subflows.${key}`, { nodes: s.nodes ?? [], edges: s.edges ?? [] });
+    }
+    return out;
+}
+const where = (scope) => (scope ? ` in ${scope}` : '');
+const edgeText = (e) => `${e.sourceNodeId}@${e.sourcePort} -> ${e.targetNodeId}@${e.targetPort}`;
+const edgeKey = (e) => JSON.stringify([e.sourceNodeId, e.sourcePort, e.targetNodeId, e.targetPort]);
+/** `inputs.schema` may be stored as a JSON string. */
+function schemaOf(n) {
+    let schema = n.inputs?.schema;
+    if (typeof schema === 'string') {
+        try {
+            schema = JSON.parse(schema);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return schema && typeof schema === 'object' ? schema : undefined;
+}
+function idsOf(list) {
+    return Array.isArray(list) ? list.map((x) => x?.id).filter((id) => typeof id === 'string') : [];
+}
+function bindingText(b) {
+    const sub = b.resourceSubType ? `/${String(b.resourceSubType)}` : '';
+    return `${String(b.resource)}${sub} "${String(b.resourceKey ?? '')}" ${String(b.propertyAttribute ?? b.name)}`;
+}
+/**
+ * Every wire-identity difference between the original and its no-edit round
+ * trip that the merged file still carries, phrased as what the merge writes.
+ *
+ * A difference the author's edit undid is not reported: an edge the round trip
+ * dropped that the merged file has again, an edge or node the round trip added
+ * that the merged file lacks, a node whose type or handles the round trip
+ * changed that the merged file no longer has (or has with the original's).
+ *
+ * @param original - The file being merged into.
+ * @param baseline - compile(decompile(original)) before any edit.
+ * @param merged - The merged file, before it is written.
+ * @returns One finding per difference, in a stable order.
+ */
+export function roundTripFindings(original, baseline, merged) {
+    const out = [];
+    const origDefs = defsOf(original);
+    const baseDefs = defsOf(baseline);
+    const mergedDefs = defsOf(merged);
+    const origScopes = scopesOf(original);
+    const baseScopes = scopesOf(baseline);
+    const mergedScopes = scopesOf(merged);
+    const scopeKeys = [...new Set([...origScopes.keys(), ...baseScopes.keys()])];
+    for (const scope of scopeKeys) {
+        const o = origScopes.get(scope) ?? { nodes: [], edges: [] };
+        const b = baseScopes.get(scope) ?? { nodes: [], edges: [] };
+        const m = mergedScopes.get(scope);
+        if (!origScopes.has(scope)) {
+            if (m)
+                out.push({ kind: 'node-added', refuses: true, message: `the round trip adds ${scope}, which the original does not have; merge will write it.` });
+            continue;
+        }
+        if (!baseScopes.has(scope)) {
+            if (!m)
+                out.push({ kind: 'node-removed', refuses: true, message: `the round trip drops ${scope}; merge will not write it.` });
+            continue;
+        }
+        const oNodes = new Map(o.nodes.map((n) => [n.id, n]));
+        const bNodes = new Map(b.nodes.map((n) => [n.id, n]));
+        const mNodes = new Map((m?.nodes ?? []).map((n) => [n.id, n]));
+        const mKeys = new Set((m?.edges ?? []).map(edgeKey));
+        const inMerged = (e) => mKeys.has(edgeKey(e));
+        // ── Edges, first, because whether an added End is neutral depends on them. ──
+        const oKeys = new Set(o.edges.map(edgeKey));
+        const bKeys = new Set(b.edges.map(edgeKey));
+        let removed = o.edges.filter((e) => !bKeys.has(edgeKey(e)));
+        let added = b.edges.filter((e) => !oKeys.has(edgeKey(e)));
+        // Same source, same target, different handle(s): the handle was renamed
+        // (`case-default-1` -> `case-case_1`, `completed` -> one edge per outcome).
+        // Reported while the merged file carries a renamed edge.
+        const byLink = (e) => JSON.stringify([e.sourceNodeId, e.targetNodeId, e.targetPort]);
+        for (const link of [...new Set(removed.map(byLink))]) {
+            const r = removed.filter((e) => byLink(e) === link);
+            const a = added.filter((e) => byLink(e) === link);
+            if (a.length === 0)
+                continue;
+            removed = removed.filter((e) => byLink(e) !== link);
+            added = added.filter((e) => byLink(e) !== link);
+            const live = a.filter(inMerged);
+            if (live.length === 0)
+                continue;
+            const [s, t] = [r[0].sourceNodeId, `${r[0].targetNodeId}@${r[0].targetPort}`];
+            out.push({
+                kind: 'edge-handle-renamed', refuses: true,
+                message: `the round trip moves the edge ${s} -> ${t}${where(scope)} from handle `
+                    + `${r.map((e) => `"${e.sourcePort}"`).join(', ')} to ${live.map((e) => `"${e.sourcePort}"`).join(', ')}; merge will write the new handle(s).`,
+            });
+        }
+        // Same source handle, different target: the edge was rewired. Reported
+        // while the merged file carries a rewired edge.
+        const byPort = (e) => JSON.stringify([e.sourceNodeId, e.sourcePort]);
+        for (const port of [...new Set(removed.map(byPort))]) {
+            const r = removed.filter((e) => byPort(e) === port);
+            const a = added.filter((e) => byPort(e) === port);
+            if (a.length === 0)
+                continue;
+            removed = removed.filter((e) => byPort(e) !== port);
+            added = added.filter((e) => byPort(e) !== port);
+            const live = a.filter(inMerged);
+            if (live.length === 0)
+                continue;
+            out.push({
+                kind: 'edge-rewired', refuses: true,
+                message: `the round trip rewires ${r[0].sourceNodeId}@${r[0].sourcePort}${where(scope)} from `
+                    + `${r.map((e) => `${e.targetNodeId}@${e.targetPort}`).join(', ')} to ${live.map((e) => `${e.targetNodeId}@${e.targetPort}`).join(', ')}; merge will write the new target.`,
+            });
+        }
+        // A dropped edge is reported while both its ends are in the merged file and
+        // the edge is not: an edge into a node the author deleted is gone by the edit.
+        for (const e of removed) {
+            if (inMerged(e) || !mNodes.has(e.sourceNodeId) || !mNodes.has(e.targetNodeId))
+                continue;
+            out.push({ kind: 'edge-removed', refuses: true, message: `the round trip drops the edge ${edgeText(e)}${where(scope)}; merge will not write it.` });
+        }
+        // An added TERMINAL node (its definition declares no source handle — an
+        // End) is neutral when every edge into it leaves a handle the original left
+        // open (no edge from that source handle at all). Read off the manifest, not
+        // a type name, so any terminal type counts.
+        const openInOriginal = (e) => !o.edges.some((x) => x.sourceNodeId === e.sourceNodeId && x.sourcePort === e.sourcePort);
+        const neutralEnd = new Set();
+        for (const n of b.nodes) {
+            if (oNodes.has(n.id) || declaredSourceHandles(n, defOf(baseDefs, n))?.size !== 0)
+                continue;
+            const into = b.edges.filter((e) => e.targetNodeId === n.id);
+            if (into.length > 0 && into.every((e) => added.includes(e) && openInOriginal(e)))
+                neutralEnd.add(n.id);
+        }
+        for (const e of added) {
+            if (neutralEnd.has(e.targetNodeId) || !inMerged(e))
+                continue;
+            out.push({ kind: 'edge-added', refuses: true, message: `the round trip adds the edge ${edgeText(e)}${where(scope)}; merge will write it.` });
+        }
+        // ── Nodes ──
+        for (const n of o.nodes) {
+            if (!bNodes.has(n.id) && !mNodes.has(n.id)) {
+                out.push({ kind: 'node-removed', refuses: true, message: `the round trip drops node "${n.id}" (${n.type})${where(scope)}; merge will not write it.` });
+            }
+        }
+        for (const n of b.nodes) {
+            if (oNodes.has(n.id) || !mNodes.has(n.id))
+                continue;
+            if (neutralEnd.has(n.id)) {
+                const tails = b.edges.filter((e) => e.targetNodeId === n.id).map((e) => `${e.sourceNodeId}@${e.sourcePort}`);
+                out.push({
+                    kind: 'implicit-end', refuses: false,
+                    message: `the round trip appends End "${n.id}" (${n.type})${where(scope)} after ${tails.join(', ')}, which the original leaves open; `
+                        + `merge will write it (same behaviour: a path that runs out of nodes ends; not refused under --strict).`,
+                });
+            }
+            else {
+                out.push({ kind: 'node-added', refuses: true, message: `the round trip adds node "${n.id}" (${n.type})${where(scope)}; merge will write it.` });
+            }
+        }
+        for (const n of o.nodes) {
+            const bn = bNodes.get(n.id);
+            const mn = mNodes.get(n.id);
+            if (!bn || !mn)
+                continue;
+            if (bn.type !== n.type && mn.type === bn.type) {
+                out.push({
+                    kind: 'node-type', refuses: true,
+                    message: `the round trip changes node "${n.id}"${where(scope)} from ${n.type} to ${bn.type}; merge will write ${bn.type}.`,
+                });
+            }
+            // Handle ids live on the node; the edges that leave them come from the
+            // edited side. A merged node with the round-trip ids is reported as is; a
+            // merged node with the original's ids (merge kept the original node) only
+            // when a merged edge leaves it on a round-trip id.
+            if (n.type !== bn.type || mn.type !== n.type)
+                continue;
+            const oh = derivedHandles(n, defOf(origDefs, n));
+            const bh = derivedHandles(bn, defOf(baseDefs, bn) ?? defOf(origDefs, n));
+            if (!oh || !bh || JSON.stringify(oh) === JSON.stringify(bh))
+                continue;
+            const mh = JSON.stringify(derivedHandles(mn, defOf(mergedDefs, mn) ?? defOf(origDefs, n)));
+            const roundTripOnly = new Set(bh.filter((h) => !oh.includes(h)));
+            let consequence;
+            if (mh === JSON.stringify(bh))
+                consequence = 'merge will write the round-trip ids';
+            else if (mh === JSON.stringify(oh) && (m?.edges ?? []).some((e) => e.sourceNodeId === n.id && roundTripOnly.has(e.sourcePort))) {
+                consequence = 'merge keeps the original node, but the edges it writes name the round-trip ids';
+            }
+            if (!consequence)
+                continue;
+            out.push({
+                kind: 'handle-ids', refuses: true,
+                message: `the round trip renames node "${n.id}" (${n.type})${where(scope)} handles ${oh.join(', ') || '(none)'} to ${bh.join(', ') || '(none)'}; ${consequence}.`,
+            });
+        }
+    }
+    // ── Bindings, by what they bind ──
+    const oRows = new Map((original.bindings ?? []).map((r) => [bindingIdentity(r), r]));
+    const bRows = new Map((baseline.bindings ?? []).map((r) => [bindingIdentity(r), r]));
+    const mRows = new Set((merged.bindings ?? []).map((r) => bindingIdentity(r)));
+    for (const [k, r] of oRows) {
+        if (!bRows.has(k)) {
+            out.push({ kind: 'binding-removed', refuses: false, message: `the round trip drops the binding row for ${bindingText(r)}; merge keeps the original's row (not refused under --strict).` });
+        }
+    }
+    for (const [k, r] of bRows) {
+        if (!oRows.has(k) && mRows.has(k)) {
+            out.push({ kind: 'binding-added', refuses: true, message: `the round trip adds a binding row for ${bindingText(r)}; merge will write it.` });
+        }
+    }
+    return out;
+}
+/** The source handles a node's definition declares, or `undefined` when they cannot be known. */
+function declaredSourceHandles(node, def) {
+    const groups = def?.handleConfiguration;
+    if (!Array.isArray(groups))
+        return undefined;
+    const out = new Set();
+    for (const g of groups) {
+        for (const h of (g?.handles ?? [])) {
+            if (h?.type !== 'source' || typeof h.id !== 'string')
+                continue;
+            const template = /\{item\.([A-Za-z0-9_]+)\}/.exec(h.id);
+            if (!template) {
+                out.add(h.id);
+                continue;
+            }
+            if (typeof h.repeat !== 'string' || !h.repeat.startsWith('inputs.'))
+                return undefined; // a template this check cannot expand
+            let items = node.inputs;
+            for (const seg of h.repeat.slice('inputs.'.length).split('.'))
+                items = items?.[seg];
+            for (const item of Array.isArray(items) ? items : []) {
+                const v = item?.[template[1]];
+                if (typeof v === 'string' || typeof v === 'number')
+                    out.add(h.id.replace(template[0], String(v)));
+            }
+        }
+    }
+    return out;
+}
+/**
+ * The handles a node derives from its own inputs, in order: a definition's
+ * `repeat` handles expanded (`case-{item.id}` over `inputs.cases` gives
+ * `case-default-1`), and a human task's `outcome-<id>` per outcome. These are
+ * the handle ids a round trip can rename; static handles cannot change.
+ * `undefined` when the node has no definition and is not a human task.
+ */
+function derivedHandles(node, def) {
+    const out = [];
+    const groups = def?.handleConfiguration;
+    for (const g of Array.isArray(groups) ? groups : []) {
+        for (const h of (g?.handles ?? [])) {
+            if (h?.type !== 'source' || typeof h.id !== 'string' || !h.id.includes('{item.'))
+                continue;
+            const single = { ...def, handleConfiguration: [{ handles: [h] }] };
+            out.push(...(declaredSourceHandles(node, single) ?? []));
+        }
+    }
+    if (OUTCOME_HANDLE_NODE_TYPES.has(node.type)) {
+        for (const id of idsOf(schemaOf(node)?.outcomes))
+            if (!out.includes(`outcome-${id}`))
+                out.push(`outcome-${id}`);
+    }
+    else if (!Array.isArray(groups)) {
+        return undefined;
+    }
+    return out;
+}
+/**
+ * Inconsistencies in the merged file that come from mixing its sources: a root
+ * edge leaving a handle its source node does not declare, and two binding rows
+ * binding the same resource property.
+ *
+ * A node with no definition in `merged.definitions` (a sticky note, a type
+ * neither input carried) is not judged. Neither is anything the original
+ * already had — an edge it carries verbatim, or as many same-identity binding
+ * rows as it already holds — because the merge did not cause it.
+ *
+ * @param merged - The merged file.
+ * @param original - The file merged into.
+ * @returns One finding per inconsistency.
+ */
+export function mergedFileFindings(merged, original = {}) {
+    const out = [];
+    const originalEdges = new Set((original.edges ?? []).map(edgeKey));
+    const originalRows = new Map();
+    for (const r of original.bindings ?? [])
+        originalRows.set(bindingIdentity(r), (originalRows.get(bindingIdentity(r)) ?? 0) + 1);
+    const nodes = new Map((merged.nodes ?? []).map((n) => [n.id, n]));
+    const defs = new Map();
+    for (const d of merged.definitions ?? [])
+        defs.set(`${String(d.nodeType)}@${String(d.version)}`, d);
+    for (const e of merged.edges ?? []) {
+        const n = nodes.get(e.sourceNodeId);
+        if (!n || originalEdges.has(edgeKey(e)))
+            continue;
+        let declared = declaredSourceHandles(n, defs.get(`${n.type}@${String(n.typeVersion)}`));
+        if (OUTCOME_HANDLE_NODE_TYPES.has(n.type)) {
+            // The product derives a human task's `outcome-<id>` handles from its
+            // outcomes; the manifest lists only `completed`. (A `completed` edge on a
+            // task WITH outcomes is a stale placeholder the product remaps, which
+            // `validate` accepts and canvas files carry — not judged here.)
+            declared = new Set([...(declared ?? ['completed']), ...idsOf(schemaOf(n)?.outcomes).map((id) => `outcome-${id}`)]);
+        }
+        if (!declared || declared.has(e.sourcePort))
+            continue;
+        out.push({
+            kind: 'undeclared-handle', refuses: true,
+            message: `the merged edge ${edgeText(e)} leaves handle "${e.sourcePort}", which node "${n.id}" (${n.type}) does not declare `
+                + `(it declares ${[...declared].map((h) => `"${h}"`).join(', ') || 'none'}); \`validate\` will report "undeclared source handle".`,
+        });
+    }
+    const seen = new Map();
+    for (const r of merged.bindings ?? []) {
+        const k = bindingIdentity(r);
+        seen.set(k, [...(seen.get(k) ?? []), String(r.id ?? '(no id)')]);
+    }
+    for (const [k, ids] of seen) {
+        if (ids.length < 2 || ids.length <= (originalRows.get(k) ?? 0))
+            continue;
+        const r = (merged.bindings ?? []).find((x) => bindingIdentity(x) === k);
+        out.push({ kind: 'duplicate-binding', refuses: true, message: `the merged file has ${ids.length} binding rows for ${bindingText(r)} (ids ${ids.join(', ')}).` });
+    }
+    return out;
+}
+/** Thrown by `mergeFlow` under `strict` when a finding refuses the merge. */
+export class MergeRefusedError extends Error {
+    /** Every refusing finding, in report order. */
+    findings;
+    constructor(findings) {
+        super(`refused (--strict): the merged file would differ from the original where the author made no edit:\n`
+            + findings.map((f) => `  - ${f.message}`).join('\n'));
+        this.name = 'MergeRefusedError';
+        this.findings = findings;
+    }
+}

package/dist/merge.d.ts

@@ -28,7 +28,7 @@
  * preserved from the original; `subflows` and edges (with their ids) come from
  * `edited`; `definitions` and `bindings` are unioned
  * (original wins on conflict, since the original's are the tenant-resolved
- * authority). Node ids are stable by construction (decompile names every step by
+ * authority). A binding row's identity is what it binds, not its row id. Node ids are stable by construction (decompile names every step by
  * its node id), which is what lets every re-attach key on id.
  *
  * ## Definitions are keyed by `nodeType@version`, not by `nodeType`
@@ -63,7 +63,18 @@
  * A node whose pair is in NEITHER file cannot be given a definition here, and a
  * merge that stayed silent about it wrote a file it already knew would fail
  * `validate`. Those are reported through {@link MergeOptions.warn}.
+ *
+ * ## The baseline is also compared with the original
+ *
+ * `baseline` is the no-edit round trip, so wherever it differs from the original
+ * in wire identity (a node, an edge, a switch case id, a human-task outcome id,
+ * a binding row), the merged file inherits that change unless the author's edit
+ * undid it. Each difference the merged file still carries is reported through
+ * `warn`, and `strict` refuses the merge over it; the merged file is also
+ * checked for an edge that leaves a handle its kept source node does not
+ * declare. See merge-roundtrip.ts.
  */
+export { MergeRefusedError, type MergeFinding } from './merge-roundtrip.js';
 interface AnyNode {
     id: string;
     type: string;
@@ -115,12 +126,30 @@ export interface MergeOptions {
      */
     baseline?: AnyFlow;
     /**
-     * Called once per finding, mirroring `DecompileOptions.warn`. Today the only
-     * finding is a node whose `(type, typeVersion)` pair has no definition in
-     * either input — the one case where the merge cannot produce a self-consistent
-     * file and `validate` will refuse the result.
+     * Called once per finding, mirroring `DecompileOptions.warn`. The findings are:
+     *
+     * - a node whose `(type, typeVersion)` pair has no definition in either input,
+     *   so `validate` will refuse the result;
+     * - 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;
+     * - 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,
+     *   and two merged binding rows for the same resource property.
      */
     warn?: (message: string) => void;
+    /**
+     * Refuse instead of warn: when the merged file differs from the original
+     * where the author made no edit, throw {@link MergeRefusedError} listing every
+     * such finding, and return nothing. The other findings still go to `warn`.
+     * Two findings never refuse, because the merged file does what the original
+     * does: an End the compile appends to a tail the original leaves open, and a
+     * binding row the round trip drops (merge keeps the original's). Meant to be
+     * used with `baseline`; without one, only the merged-file checks can refuse.
+     */
+    strict?: boolean;
 }
 export declare function mergeFlow(original: AnyFlow, edited: AnyFlow, options?: MergeOptions): AnyFlow;
-export {};