@uipath/maestro-builder-sdk 6.58.0 → 6.58.1

package/dist/edit-scope.d.ts

@@ -0,0 +1,180 @@
+/**
+ * edit-scope — which parts of a Flow the author edited, and where a finding
+ * sits relative to that edit.
+ *
+ * A node or subflow of the edited flow that differs from its `baseline`
+ * counterpart (compile(decompile(original)), the no-edit round trip) is one
+ * the author changed; one that equals it is untouched. `mergeFlow` takes the
+ * changed ones from the edited flow and restores the untouched ones from the
+ * original; `flow merge --baseline-from` (merge-cli.ts) sorts each draft
+ * refusal and `check()` finding by the same rule, so a finding on an untouched
+ * node is a warning and one on an edited node is an error.
+ *
+ * For instance, a canvas Slack node with no connection yet that the author did
+ * not touch is `kept`; the same node with a new message text is `refused`.
+ *
+ * Pure: no file access, so a portable entry (`check.ts`, `merge.ts`) can use
+ * it. Reading the original and compiling its baseline is merge-compile.ts's.
+ */
+import type { Diagnostic } from './check.js';
+export interface AnyNode {
+    id: string;
+    type: string;
+    typeVersion?: string;
+    parentId?: string;
+    ui?: unknown;
+    display?: unknown;
+    inputs?: Record<string, unknown>;
+    outputs?: Record<string, unknown>;
+    [k: string]: unknown;
+}
+export interface AnyEdge {
+    id?: string;
+    sourceNodeId: string;
+    sourcePort: string;
+    targetNodeId: string;
+    targetPort: string;
+    [k: string]: unknown;
+}
+export interface AnyFlow {
+    id?: string;
+    name?: string;
+    version?: string;
+    nodes?: AnyNode[];
+    edges?: AnyEdge[];
+    definitions?: Array<{
+        nodeType?: string;
+        [k: string]: unknown;
+    }>;
+    variables?: unknown;
+    subflows?: Record<string, unknown>;
+    bindings?: Array<{
+        id?: string;
+        [k: string]: unknown;
+    }>;
+    metadata?: unknown;
+    solutionId?: unknown;
+    projectId?: unknown;
+    layout?: unknown;
+    runtime?: unknown;
+    [k: string]: unknown;
+}
+export declare function byId(nodes: AnyNode[] | undefined): Map<string, AnyNode>;
+/**
+ * Whether two nodes are the SAME as far as the author is concerned — same type,
+ * same inputs and same output mappings. Layout (`ui`), `display`, `typeVersion`,
+ * and the derived parts of `outputs` (type, schema, description) are ignored,
+ * because those are exactly the parts decompile does not carry through. An
+ * output's `source` is authored, not derived: it is what an End returns, so an
+ * edit to `.return({ ... })` changes nothing else on the node. Used only to
+ * decide "did the user edit this node?" against the baseline.
+ */
+export declare function nodeUnchanged(a: AnyNode | undefined, b: AnyNode | undefined): boolean;
+/**
+ * The keys of the subflows `mergeFlow` (merge.ts) takes from `edited` rather than
+ * restoring from `original`: every subflow that is new, that the original does
+ * not have, or that differs from its `baseline` counterpart in any way the
+ * author can edit — a node's inputs, output sources or label, an edge, the
+ * scope's `variables` or `layout` (`subflowUnchanged`, #1322). With no
+ * baseline, that is every subflow. A kept subflow is the original's whole: its
+ * nodes, edges, variables and layout.
+ */
+export declare function subflowsTakenFromEdited(original: AnyFlow, edited: AnyFlow, baseline?: AnyFlow): string[];
+export type SubflowScope = {
+    nodes?: AnyNode[];
+    edges?: AnyEdge[];
+    variables?: unknown;
+    layout?: unknown;
+};
+/**
+ * Whether merge restores `e`'s ORIGINAL node instead of taking `e`: there is a
+ * baseline, the original has the node, and `e` equals its baseline counterpart.
+ * merge.ts's `mergeFlow` node loop and {@link nodesTakenFromEdited} both ask this.
+ */
+export declare function isKept(e: AnyNode, origNodes: Map<string, AnyNode>, baseNodes: Map<string, AnyNode>, baseline: AnyFlow | undefined): boolean;
+/**
+ * Why a finding is an error: `edited`, its node is one the author changed or
+ * added; `subflow`, it sits in a subflow the edit changed, which merge takes
+ * whole; `unplaced`, it names no node and the original's own round trip does
+ * not report it, so the edit introduced it.
+ */
+export type TakenReason = 'edited' | 'subflow' | 'unplaced';
+/**
+ * A finding on a node merge takes from the edited flow, with the reason it
+ * takes it: `edited`, the author changed or added the node; `subflow`, the
+ * node sits in a subflow the edit changed, which merge takes whole (`subflow`
+ * names it).
+ */
+export type Refused<T> = T & {
+    reason: TakenReason;
+    subflow?: string;
+};
+/** A finding on a node merge restores from the original; `subflow` names the untouched subflow it sits in. */
+type Kept<T> = T & {
+    subflow?: string;
+};
+/**
+ * Sort each finding by what merge does with its node: `refused` when the node
+ * comes from the edited flow (reason `edited`: the author changed or added it;
+ * reason `subflow`: it sits in a subflow the edit changed, which merge takes
+ * whole), `kept` when merge restores the original node — a root node the edit
+ * did not touch, or any node of a subflow the edit did not touch (#1322) — and
+ * `unplaced` when the finding names no node merge knows (an unnamed End's
+ * `.return`, a flow-level finding). The caller sorts those again with
+ * {@link splitUnplaced}: one the original's own round trip reports too is
+ * printed, one the edit introduced is refused.
+ *
+ * For instance a Slack node with no connection that the author did not touch
+ * is `kept`; the same node with a new message text is `refused` as `edited`.
+ */
+export declare function classifyDrafts<T extends {
+    nodeId: string;
+    subflow?: string;
+}>(original: any, edited: any, baseline: any, findings: readonly T[]): {
+    kept: Kept<T>[];
+    refused: Refused<T>[];
+    unplaced: T[];
+};
+/**
+ * A `check()` diagnostic, placed on the node its step emitted (`''` when it
+ * names no node); `subflow` is the calling step when the finding is inside a
+ * subflow, which then decides how it is classified.
+ */
+export type PlacedDiagnostic = Diagnostic & {
+    nodeId: string;
+    subflow?: string;
+};
+/**
+ * Place each `check()` diagnostic on the node its step emitted in `editedFlow`, so
+ * {@link classifyDrafts} can sort it: a root step on its node (by label, then
+ * id); a step inside a subflow (`check` reports it as `<caller> › <step>`, one
+ * segment per level) on the deepest step the path resolves to, with `subflow`
+ * set to the deepest subflow on that path, which is what decides; a named End
+ * on its End node (#1322). A diagnostic with no step, or one no node answers
+ * to, gets nodeId `''`.
+ */
+export declare function placeDiagnostics(diagnostics: readonly Diagnostic[], editedFlow: any): PlacedDiagnostic[];
+/** How many times each {@link findingKey} occurs, for {@link splitUnplaced}'s baseline. */
+export declare function findingCounts(findings: ReadonlyArray<{
+    code: string;
+    message: string;
+}>): Map<string, number>;
+/**
+ * Sort findings merge could not place on a node by whether the edit introduced
+ * them: `known` when the ORIGINAL's own round trip (`baseline`, the decompiled
+ * original compiled and checked, as {@link findingCounts}) reports the same
+ * code and message — once per occurrence, so a second copy of a finding the
+ * original has once is `introduced` — so the finding predates the edit and
+ * only prints; `introduced` otherwise, which is refused like any error on an
+ * edited node (#1322). With no baseline findings to compare against (a
+ * precompiled `--baseline` file), every one is `introduced`, as merge treated
+ * them before.
+ */
+export declare function splitUnplaced<T extends {
+    code: string;
+    message: string;
+}>(unplaced: readonly T[], baseline: ReadonlyMap<string, number> | undefined): {
+    known: T[];
+    introduced: T[];
+};
+export {};

package/dist/edit-scope.js

@@ -0,0 +1,251 @@
+export function byId(nodes) {
+    return new Map((nodes ?? []).map((n) => [n.id, n]));
+}
+/**
+ * Whether two nodes are the SAME as far as the author is concerned — same type,
+ * same inputs and same output mappings. Layout (`ui`), `display`, `typeVersion`,
+ * and the derived parts of `outputs` (type, schema, description) are ignored,
+ * because those are exactly the parts decompile does not carry through. An
+ * output's `source` is authored, not derived: it is what an End returns, so an
+ * edit to `.return({ ... })` changes nothing else on the node. Used only to
+ * decide "did the user edit this node?" against the baseline.
+ */
+export function nodeUnchanged(a, b) {
+    if (!a || !b)
+        return false;
+    if (a.type !== b.type)
+        return false;
+    return JSON.stringify(a.inputs ?? {}) === JSON.stringify(b.inputs ?? {})
+        && JSON.stringify(outputSources(a)) === JSON.stringify(outputSources(b));
+}
+/** Each output's `source` by output name; outputs without one are left out. */
+function outputSources(n) {
+    const sources = {};
+    for (const [name, output] of Object.entries(n.outputs ?? {})) {
+        if (output && typeof output === 'object' && 'source' in output)
+            sources[name] = output.source;
+    }
+    return sources;
+}
+/**
+ * The ids of the root nodes `mergeFlow` (merge.ts) takes from `edited` rather than
+ * restoring from `original`: every node that is new, or that differs from its
+ * `baseline` counterpart. With no baseline, that is every node.
+ *
+ * For instance, with a baseline equal to `edited` and every node present in
+ * `original`, the answer is `[]` — a no-edit merge keeps them all.
+ */
+function nodesTakenFromEdited(original, edited, baseline) {
+    const origNodes = byId(original.nodes);
+    const baseNodes = byId(baseline?.nodes);
+    return (edited.nodes ?? []).filter((e) => !isKept(e, origNodes, baseNodes, baseline)).map((e) => e.id);
+}
+/**
+ * The keys of the subflows `mergeFlow` (merge.ts) takes from `edited` rather than
+ * restoring from `original`: every subflow that is new, that the original does
+ * not have, or that differs from its `baseline` counterpart in any way the
+ * author can edit — a node's inputs, output sources or label, an edge, the
+ * scope's `variables` or `layout` (`subflowUnchanged`, #1322). With no
+ * baseline, that is every subflow. A kept subflow is the original's whole: its
+ * nodes, edges, variables and layout.
+ */
+export function subflowsTakenFromEdited(original, edited, baseline) {
+    return Object.keys(edited.subflows ?? {}).filter((key) => {
+        const orig = original.subflows?.[key];
+        const base = baseline?.subflows?.[key];
+        return !baseline || orig === undefined || base === undefined
+            || !subflowUnchanged(edited.subflows[key], base);
+    });
+}
+/** A node's canvas label, when it has one. */
+const labelOf = (n) => n?.display?.label;
+/**
+ * Whether an edited subflow equals its baseline: the same node ids, each node
+ * unchanged (`nodeUnchanged`) and under the same label, the same edges by
+ * their endpoints and handles (ids are compile's own), and the same
+ * `variables` and `layout` byte for byte. The scope's variables carry what the
+ * nodes do not — a step's `{ updates }` row, a child `.input()` type, a `.var()`
+ * default — and a kept subflow is the original's whole, so any of them changing
+ * has to make the subflow a taken one.
+ */
+function subflowUnchanged(e, b) {
+    const eNodes = byId(e.nodes);
+    const bNodes = byId(b.nodes);
+    if (eNodes.size !== bNodes.size)
+        return false;
+    for (const [id, n] of eNodes) {
+        const base = bNodes.get(id);
+        if (!nodeUnchanged(n, base) || labelOf(n) !== labelOf(base))
+            return false;
+    }
+    if (JSON.stringify(e.variables ?? null) !== JSON.stringify(b.variables ?? null))
+        return false;
+    // `layout.edges` is keyed by edge id, and ids come from one file-wide
+    // counter: a step added before the call shifts every id in the subflow
+    // without touching it. So routes are compared by the endpoints the id names
+    // (as the edges themselves are), and `layout.nodes` as it is.
+    if (JSON.stringify(layoutByEndpoints(e)) !== JSON.stringify(layoutByEndpoints(b)))
+        return false;
+    const eEdges = (e.edges ?? []).map(edgeKey).sort();
+    const bEdges = (b.edges ?? []).map(edgeKey).sort();
+    return eEdges.length === bEdges.length && eEdges.every((k, i) => k === bEdges[i]);
+}
+/** `<source>@<port>-><target>@<port>`: an edge's identity apart from its id. */
+const edgeKey = (x) => `${x.sourceNodeId}@${x.sourcePort}->${x.targetNodeId}@${x.targetPort}`;
+/** A scope's layout with its `edges` re-keyed by endpoints, so an id shift does not read as a change. */
+function layoutByEndpoints(sf) {
+    const layout = sf.layout;
+    if (!layout || typeof layout !== 'object')
+        return layout ?? null;
+    const byId = new Map((sf.edges ?? []).map((x) => [x.id, edgeKey(x)]));
+    const { edges, ...rest } = layout;
+    const routes = Object.entries(edges ?? {}).map(([id, route]) => [byId.get(id) ?? id, route]).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return { ...rest, edges: Object.fromEntries(routes) };
+}
+/**
+ * Whether merge restores `e`'s ORIGINAL node instead of taking `e`: there is a
+ * baseline, the original has the node, and `e` equals its baseline counterpart.
+ * merge.ts's `mergeFlow` node loop and {@link nodesTakenFromEdited} both ask this.
+ */
+export function isKept(e, origNodes, baseNodes, baseline) {
+    return !!baseline && origNodes.has(e.id) && nodeUnchanged(e, baseNodes.get(e.id));
+}
+/**
+ * Sort each finding by what merge does with its node: `refused` when the node
+ * comes from the edited flow (reason `edited`: the author changed or added it;
+ * reason `subflow`: it sits in a subflow the edit changed, which merge takes
+ * whole), `kept` when merge restores the original node — a root node the edit
+ * did not touch, or any node of a subflow the edit did not touch (#1322) — and
+ * `unplaced` when the finding names no node merge knows (an unnamed End's
+ * `.return`, a flow-level finding). The caller sorts those again with
+ * {@link splitUnplaced}: one the original's own round trip reports too is
+ * printed, one the edit introduced is refused.
+ *
+ * For instance a Slack node with no connection that the author did not touch
+ * is `kept`; the same node with a new message text is `refused` as `edited`.
+ */
+export function classifyDrafts(original, edited, baseline, findings) {
+    const fromEdited = new Set(nodesTakenFromEdited(original, edited, baseline));
+    const takenSubflows = new Set(subflowsTakenFromEdited(original, edited, baseline));
+    const rootIds = new Set((edited?.nodes ?? []).map((n) => n.id));
+    /** A subflow's own node ids → the key (the calling step) of the subflow holding them. */
+    const subflowOfNode = new Map();
+    for (const [key, sf] of Object.entries(edited?.subflows ?? {})) {
+        for (const n of sf?.nodes ?? [])
+            subflowOfNode.set(n.id, key);
+    }
+    const kept = [];
+    const refused = [];
+    const unplaced = [];
+    for (const f of findings) {
+        // A finding inside a subflow — placed on the calling step by `checkEdited`
+        // (`subflow` set), or a draft on one of the subflow's own nodes — is judged
+        // by the SUBFLOW: taken whole when the edit changed it, else the original's.
+        const subflow = f.subflow ?? subflowOfNode.get(f.nodeId);
+        if (subflow !== undefined) {
+            if (takenSubflows.has(subflow))
+                refused.push({ ...f, reason: 'subflow', subflow });
+            else
+                kept.push({ ...f, subflow });
+        }
+        else if (rootIds.has(f.nodeId)) {
+            if (fromEdited.has(f.nodeId))
+                refused.push({ ...f, reason: 'edited' });
+            else
+                kept.push(f);
+        }
+        else {
+            unplaced.push(f);
+        }
+    }
+    return { kept, refused, unplaced };
+}
+/**
+ * Place each `check()` diagnostic on the node its step emitted in `editedFlow`, so
+ * {@link classifyDrafts} can sort it: a root step on its node (by label, then
+ * id); a step inside a subflow (`check` reports it as `<caller> › <step>`, one
+ * segment per level) on the deepest step the path resolves to, with `subflow`
+ * set to the deepest subflow on that path, which is what decides; a named End
+ * on its End node (#1322). A diagnostic with no step, or one no node answers
+ * to, gets nodeId `''`.
+ */
+export function placeDiagnostics(diagnostics, editedFlow) {
+    const byStep = new Map();
+    for (const n of editedFlow?.nodes ?? []) {
+        const label = n?.display?.label;
+        if (typeof label === 'string' && !byStep.has(label))
+            byStep.set(label, n.id);
+    }
+    const ids = new Set((editedFlow?.nodes ?? []).map((n) => n.id));
+    /** `name` as a node id in `nodes`: by label, then by id; `''` when neither answers. */
+    const resolveIn = (nodes, name) => {
+        const byLabel = nodes.find((n) => n?.display?.label === name);
+        if (byLabel)
+            return byLabel.id;
+        return nodes.some((n) => n?.id === name) ? name : '';
+    };
+    // `subflows` is flat, keyed by each caller's id at every depth, and check
+    // prefixes a finding at every level (`outer › inner › x`): the subflow that
+    // decides is the DEEPEST one on the path, since merge keeps or takes each
+    // subflow on its own (an edit inside `inner` leaves `outer` kept).
+    const place = (step) => {
+        if (step === undefined)
+            return { nodeId: '' };
+        const segments = step.split(SUBFLOW_STEP_SEPARATOR);
+        let scope = editedFlow?.nodes ?? [];
+        let subflow;
+        let nodeId = '';
+        for (const [i, segment] of segments.entries()) {
+            const id = i === 0 ? (byStep.get(segment) ?? (ids.has(segment) ? segment : '')) : resolveIn(scope, segment);
+            if (id === '')
+                break;
+            nodeId = id;
+            const child = i < segments.length - 1 ? editedFlow?.subflows?.[id] : undefined;
+            if (child === undefined)
+                break;
+            subflow = id;
+            scope = child.nodes ?? [];
+        }
+        return subflow !== undefined ? { nodeId: nodeId === '' ? subflow : nodeId, subflow } : { nodeId };
+    };
+    return diagnostics.map((d) => ({ ...d, ...place(d.step) }));
+}
+/** The identity of a finding for the introduced-or-not comparison: its code and message. */
+function findingKey(f) {
+    return `${f.code}\n${f.message}`;
+}
+/** How many times each {@link findingKey} occurs, for {@link splitUnplaced}'s baseline. */
+export function findingCounts(findings) {
+    const counts = new Map();
+    for (const f of findings)
+        counts.set(findingKey(f), (counts.get(findingKey(f)) ?? 0) + 1);
+    return counts;
+}
+/**
+ * Sort findings merge could not place on a node by whether the edit introduced
+ * them: `known` when the ORIGINAL's own round trip (`baseline`, the decompiled
+ * original compiled and checked, as {@link findingCounts}) reports the same
+ * code and message — once per occurrence, so a second copy of a finding the
+ * original has once is `introduced` — so the finding predates the edit and
+ * only prints; `introduced` otherwise, which is refused like any error on an
+ * edited node (#1322). With no baseline findings to compare against (a
+ * precompiled `--baseline` file), every one is `introduced`, as merge treated
+ * them before.
+ */
+export function splitUnplaced(unplaced, baseline) {
+    const known = [];
+    const introduced = [];
+    const left = new Map(baseline ?? []);
+    for (const f of unplaced) {
+        const n = left.get(findingKey(f)) ?? 0;
+        if (n > 0) {
+            left.set(findingKey(f), n - 1);
+            known.push(f);
+        }
+        else
+            introduced.push(f);
+    }
+    return { known, introduced };
+}
+/** How `check` joins a subflow's calling step and the step inside it in a diagnostic's `step`. */
+const SUBFLOW_STEP_SEPARATOR = ' › ';

package/dist/merge-cli.js

@@ -9,7 +9,8 @@
  * `--baseline-from <original.flow>` makes merge build the baseline itself
  * (decompile + compile, nothing written), and an edited `.flow.ts` makes merge
  * compile it: both compiles tolerate DRAFT nodes, and merge refuses a draft
- * only where it would take the node from the edited flow. See merge-compile.ts.
+ * only where it would take the node from the edited flow. See merge-compile.ts
+ * and edit-scope.ts.
  *
  * `edited.flow` is compile(decompile(original) after your edits). `--baseline`
  * is compile(decompile(original)) BEFORE any edit — supplying it enables the
@@ -55,7 +56,8 @@ import { flowCheckOpts, openCliLibrary } from './cli-library.js';
 import { Bindings } from './bindings.js';
 import { defaultBindingsFile } from './workdir.js';
 import { loadNodePackages } from './node-packages.js';
-import { baselineFromOriginal, checkEdited, classifyDrafts, compileSourceDraftTolerant, findingCounts, splitUnplaced } from './merge-compile.js';
+import { baselineFromOriginal, checkEdited, compileSourceDraftTolerant } from './merge-compile.js';
+import { classifyDrafts, findingCounts, splitUnplaced } from './edit-scope.js';
 const USAGE = 'usage: flow-merge <original.flow> <edited.flow | Edited.flow.ts> [-o merged.flow] '
     + '[--baseline <baseline.flow> | --baseline-from <original.flow>] [--library <dir>] [--bindings <file>] [--strict]';
 /**

package/dist/merge-compile.d.ts

@@ -1,5 +1,6 @@
 import { type DraftFinding, type SerializeOpts } from './serialize.js';
-import { type CheckOpts, type Diagnostic } from './check.js';
+import { type CheckOpts } from './check.js';
+import { type PlacedDiagnostic } from './edit-scope.js';
 import type { BuiltFlow } from './flow-sdk.js';
 /**
  * A compile's flow, the draft refusals it reported instead of throwing, and the
@@ -30,94 +31,10 @@ export declare function compileSourceDraftTolerant(file: string, opts?: Omit<Ser
 export declare function baselineFromOriginal(originalPath: string, opts?: Omit<SerializeOpts, 'draft'>, warn?: (message: string) => void): Promise<DraftTolerantCompile & {
     built: BuiltFlow;
 }>;
-/**
- * Why a finding is an error: `edited`, its node is one the author changed or
- * added; `subflow`, it sits in a subflow the edit changed, which merge takes
- * whole; `unplaced`, it names no node and the original's own round trip does
- * not report it, so the edit introduced it.
- */
-export type TakenReason = 'edited' | 'subflow' | 'unplaced';
-/**
- * A finding on a node merge takes from the edited flow, with the reason it
- * takes it: `edited`, the author changed or added the node; `subflow`, the
- * node sits in a subflow the edit changed, which merge takes whole (`subflow`
- * names it).
- */
-export type Refused<T> = T & {
-    reason: TakenReason;
-    subflow?: string;
-};
-/** A finding on a node merge restores from the original; `subflow` names the untouched subflow it sits in. */
-export type Kept<T> = T & {
-    subflow?: string;
-};
-/**
- * Sort each finding by what merge does with its node: `refused` when the node
- * comes from the edited flow (reason `edited`: the author changed or added it;
- * reason `subflow`: it sits in a subflow the edit changed, which merge takes
- * whole), `kept` when merge restores the original node — a root node the edit
- * did not touch, or any node of a subflow the edit did not touch (#1322) — and
- * `unplaced` when the finding names no node merge knows (an unnamed End's
- * `.return`, a flow-level finding). The caller sorts those again with
- * {@link splitUnplaced}: one the original's own round trip reports too is
- * printed, one the edit introduced is refused.
- *
- * For instance a Slack node with no connection that the author did not touch
- * is `kept`; the same node with a new message text is `refused` as `edited`.
- */
-export declare function classifyDrafts<T extends {
-    nodeId: string;
-    subflow?: string;
-}>(original: any, edited: any, baseline: any, findings: readonly T[]): {
-    kept: Kept<T>[];
-    refused: Refused<T>[];
-    unplaced: T[];
-};
-/**
- * A `check()` diagnostic, placed on the node its step emitted (`''` when it
- * names no node); `subflow` is the calling step when the finding is inside a
- * subflow, which then decides how it is classified.
- */
-export type PlacedDiagnostic = Diagnostic & {
-    nodeId: string;
-    subflow?: string;
-};
 /**
  * Run `check()` on the edited source, as `compile` does, and place each
- * diagnostic on the node its step emitted in `editedFlow`, so
- * {@link classifyDrafts} can sort it: a root step on its node (by label, then
- * id); a step inside a subflow (`check` reports it as `<caller> › <step>`, one
- * segment per level) on the deepest step the path resolves to, with `subflow`
- * set to the deepest subflow on that path, which is what decides; a named End
- * on its End node (#1322). A diagnostic with no step, or one no node answers
- * to, gets nodeId `''`.
+ * diagnostic on its node ({@link placeDiagnostics}). The `check()` call stays
+ * here, not in `edit-scope.ts`, so `check.ts` can import that module without a
+ * load-time cycle.
  */
 export declare function checkEdited(built: BuiltFlow, editedFlow: any, opts: CheckOpts): PlacedDiagnostic[];
-/** The identity of a finding for the introduced-or-not comparison: its code and message. */
-export declare function findingKey(f: {
-    code: string;
-    message: string;
-}): string;
-/** How many times each {@link findingKey} occurs, for {@link splitUnplaced}'s baseline. */
-export declare function findingCounts(findings: ReadonlyArray<{
-    code: string;
-    message: string;
-}>): Map<string, number>;
-/**
- * Sort findings merge could not place on a node by whether the edit introduced
- * them: `known` when the ORIGINAL's own round trip (`baseline`, the decompiled
- * original compiled and checked, as {@link findingCounts}) reports the same
- * code and message — once per occurrence, so a second copy of a finding the
- * original has once is `introduced` — so the finding predates the edit and
- * only prints; `introduced` otherwise, which is refused like any error on an
- * edited node (#1322). With no baseline findings to compare against (a
- * precompiled `--baseline` file), every one is `introduced`, as merge treated
- * them before.
- */
-export declare function splitUnplaced<T extends {
-    code: string;
-    message: string;
-}>(unplaced: readonly T[], baseline: ReadonlyMap<string, number> | undefined): {
-    known: T[];
-    introduced: T[];
-};

package/dist/merge-compile.js

@@ -4,7 +4,8 @@
  * Both compiles tolerate draft nodes (`SerializeOpts.draft`). A draft on a node
  * merge keeps from the original is a warning; a draft or `check()` error on a
  * node merge takes from the edited flow is an error. Nothing draft-tolerant is
- * written to disk.
+ * written to disk. Which nodes count as edited, and how each finding is sorted,
+ * is edit-scope.ts's.
  */
 import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
@@ -12,9 +13,9 @@ import { dirname, join, resolve } from 'node:path';
 import { decompile } from './decompile.js';
 import { loadBuiltFlow } from './load.js';
 import { serialize } from './serialize.js';
-import { check } from './check.js';
-import { nodesTakenFromEdited, subflowsTakenFromEdited } from './merge.js';
 import { PACKAGE_NAME } from './package-name.js';
+import { check } from './check.js';
+import { placeDiagnostics } from './edit-scope.js';
 /** Compile `built` with draft tolerance. Every other refusal still throws. */
 export function compileDraftTolerant(built, opts = {}) {
     const drafts = [];
@@ -73,143 +74,12 @@ function baselineDirectory(originalPath) {
         return mkdtempSync(join(tmpdir(), 'flow-merge-baseline-'));
     }
 }
-/**
- * Sort each finding by what merge does with its node: `refused` when the node
- * comes from the edited flow (reason `edited`: the author changed or added it;
- * reason `subflow`: it sits in a subflow the edit changed, which merge takes
- * whole), `kept` when merge restores the original node — a root node the edit
- * did not touch, or any node of a subflow the edit did not touch (#1322) — and
- * `unplaced` when the finding names no node merge knows (an unnamed End's
- * `.return`, a flow-level finding). The caller sorts those again with
- * {@link splitUnplaced}: one the original's own round trip reports too is
- * printed, one the edit introduced is refused.
- *
- * For instance a Slack node with no connection that the author did not touch
- * is `kept`; the same node with a new message text is `refused` as `edited`.
- */
-export function classifyDrafts(original, edited, baseline, findings) {
-    const fromEdited = new Set(nodesTakenFromEdited(original, edited, baseline));
-    const takenSubflows = new Set(subflowsTakenFromEdited(original, edited, baseline));
-    const rootIds = new Set((edited?.nodes ?? []).map((n) => n.id));
-    /** A subflow's own node ids → the key (the calling step) of the subflow holding them. */
-    const subflowOfNode = new Map();
-    for (const [key, sf] of Object.entries(edited?.subflows ?? {})) {
-        for (const n of sf?.nodes ?? [])
-            subflowOfNode.set(n.id, key);
-    }
-    const kept = [];
-    const refused = [];
-    const unplaced = [];
-    for (const f of findings) {
-        // A finding inside a subflow — placed on the calling step by `checkEdited`
-        // (`subflow` set), or a draft on one of the subflow's own nodes — is judged
-        // by the SUBFLOW: taken whole when the edit changed it, else the original's.
-        const subflow = f.subflow ?? subflowOfNode.get(f.nodeId);
-        if (subflow !== undefined) {
-            if (takenSubflows.has(subflow))
-                refused.push({ ...f, reason: 'subflow', subflow });
-            else
-                kept.push({ ...f, subflow });
-        }
-        else if (rootIds.has(f.nodeId)) {
-            if (fromEdited.has(f.nodeId))
-                refused.push({ ...f, reason: 'edited' });
-            else
-                kept.push(f);
-        }
-        else {
-            unplaced.push(f);
-        }
-    }
-    return { kept, refused, unplaced };
-}
 /**
  * Run `check()` on the edited source, as `compile` does, and place each
- * diagnostic on the node its step emitted in `editedFlow`, so
- * {@link classifyDrafts} can sort it: a root step on its node (by label, then
- * id); a step inside a subflow (`check` reports it as `<caller> › <step>`, one
- * segment per level) on the deepest step the path resolves to, with `subflow`
- * set to the deepest subflow on that path, which is what decides; a named End
- * on its End node (#1322). A diagnostic with no step, or one no node answers
- * to, gets nodeId `''`.
+ * diagnostic on its node ({@link placeDiagnostics}). The `check()` call stays
+ * here, not in `edit-scope.ts`, so `check.ts` can import that module without a
+ * load-time cycle.
  */
 export function checkEdited(built, editedFlow, opts) {
-    const byStep = new Map();
-    for (const n of editedFlow?.nodes ?? []) {
-        const label = n?.display?.label;
-        if (typeof label === 'string' && !byStep.has(label))
-            byStep.set(label, n.id);
-    }
-    const ids = new Set((editedFlow?.nodes ?? []).map((n) => n.id));
-    /** `name` as a node id in `nodes`: by label, then by id; `''` when neither answers. */
-    const resolveIn = (nodes, name) => {
-        const byLabel = nodes.find((n) => n?.display?.label === name);
-        if (byLabel)
-            return byLabel.id;
-        return nodes.some((n) => n?.id === name) ? name : '';
-    };
-    // `subflows` is flat, keyed by each caller's id at every depth, and check
-    // prefixes a finding at every level (`outer › inner › x`): the subflow that
-    // decides is the DEEPEST one on the path, since merge keeps or takes each
-    // subflow on its own (an edit inside `inner` leaves `outer` kept).
-    const place = (step) => {
-        if (step === undefined)
-            return { nodeId: '' };
-        const segments = step.split(SUBFLOW_STEP_SEPARATOR);
-        let scope = editedFlow?.nodes ?? [];
-        let subflow;
-        let nodeId = '';
-        for (const [i, segment] of segments.entries()) {
-            const id = i === 0 ? (byStep.get(segment) ?? (ids.has(segment) ? segment : '')) : resolveIn(scope, segment);
-            if (id === '')
-                break;
-            nodeId = id;
-            const child = i < segments.length - 1 ? editedFlow?.subflows?.[id] : undefined;
-            if (child === undefined)
-                break;
-            subflow = id;
-            scope = child.nodes ?? [];
-        }
-        return subflow !== undefined ? { nodeId: nodeId === '' ? subflow : nodeId, subflow } : { nodeId };
-    };
-    return check(built, opts).map((d) => ({ ...d, ...place(d.step) }));
-}
-/** The identity of a finding for the introduced-or-not comparison: its code and message. */
-export function findingKey(f) {
-    return `${f.code}\n${f.message}`;
-}
-/** How many times each {@link findingKey} occurs, for {@link splitUnplaced}'s baseline. */
-export function findingCounts(findings) {
-    const counts = new Map();
-    for (const f of findings)
-        counts.set(findingKey(f), (counts.get(findingKey(f)) ?? 0) + 1);
-    return counts;
-}
-/**
- * Sort findings merge could not place on a node by whether the edit introduced
- * them: `known` when the ORIGINAL's own round trip (`baseline`, the decompiled
- * original compiled and checked, as {@link findingCounts}) reports the same
- * code and message — once per occurrence, so a second copy of a finding the
- * original has once is `introduced` — so the finding predates the edit and
- * only prints; `introduced` otherwise, which is refused like any error on an
- * edited node (#1322). With no baseline findings to compare against (a
- * precompiled `--baseline` file), every one is `introduced`, as merge treated
- * them before.
- */
-export function splitUnplaced(unplaced, baseline) {
-    const known = [];
-    const introduced = [];
-    const left = new Map(baseline ?? []);
-    for (const f of unplaced) {
-        const n = left.get(findingKey(f)) ?? 0;
-        if (n > 0) {
-            left.set(findingKey(f), n - 1);
-            known.push(f);
-        }
-        else
-            introduced.push(f);
-    }
-    return { known, introduced };
+    return placeDiagnostics(check(built, opts), editedFlow);
 }
-/** How `check` joins a subflow's calling step and the step inside it in a diagnostic's `step`. */
-const SUBFLOW_STEP_SEPARATOR = ' › ';

package/dist/merge.d.ts

@@ -87,50 +87,9 @@
  * original plus the author's change to the node. See merge-embedded-agent.ts.
  */
 import { type MergeSidecarSources, type SidecarWrite } from './merge-sidecars.js';
+import { type AnyFlow } from './edit-scope.js';
 export { MergeRefusedError, type MergeFinding } from './merge-roundtrip.js';
 export type { MergeSidecarSources, SidecarSet, SidecarWrite } from './merge-sidecars.js';
-interface AnyNode {
-    id: string;
-    type: string;
-    typeVersion?: string;
-    parentId?: string;
-    ui?: unknown;
-    display?: unknown;
-    inputs?: Record<string, unknown>;
-    outputs?: Record<string, unknown>;
-    [k: string]: unknown;
-}
-interface AnyEdge {
-    id?: string;
-    sourceNodeId: string;
-    sourcePort: string;
-    targetNodeId: string;
-    targetPort: string;
-    [k: string]: unknown;
-}
-interface AnyFlow {
-    id?: string;
-    name?: string;
-    version?: string;
-    nodes?: AnyNode[];
-    edges?: AnyEdge[];
-    definitions?: Array<{
-        nodeType?: string;
-        [k: string]: unknown;
-    }>;
-    variables?: unknown;
-    subflows?: Record<string, unknown>;
-    bindings?: Array<{
-        id?: string;
-        [k: string]: unknown;
-    }>;
-    metadata?: unknown;
-    solutionId?: unknown;
-    projectId?: unknown;
-    layout?: unknown;
-    runtime?: unknown;
-    [k: string]: unknown;
-}
 export interface MergeOptions {
     /**
      * compile(decompile(original)) captured BEFORE the user's edits. Enables the
@@ -172,25 +131,6 @@ export interface MergeOptions {
      */
     strict?: boolean;
 }
-/**
- * The ids of the root nodes {@link mergeFlow} takes from `edited` rather than
- * restoring from `original`: every node that is new, or that differs from its
- * `baseline` counterpart. With no baseline, that is every node.
- *
- * For instance, with a baseline equal to `edited` and every node present in
- * `original`, the answer is `[]` — a no-edit merge keeps them all.
- */
-export declare function nodesTakenFromEdited(original: AnyFlow, edited: AnyFlow, baseline?: AnyFlow): string[];
-/**
- * The keys of the subflows {@link mergeFlow} takes from `edited` rather than
- * restoring from `original`: every subflow that is new, that the original does
- * not have, or that differs from its `baseline` counterpart in any way the
- * author can edit — a node's inputs, output sources or label, an edge, the
- * scope's `variables` or `layout` (`subflowUnchanged`, #1322). With no
- * baseline, that is every subflow. A kept subflow is the original's whole: its
- * nodes, edges, variables and layout.
- */
-export declare function subflowsTakenFromEdited(original: AnyFlow, edited: AnyFlow, baseline?: AnyFlow): string[];
 export declare function mergeFlow(original: AnyFlow, edited: AnyFlow, options?: MergeOptions): AnyFlow;
 /**
  * `mergeFlow`, plus the agent sidecar files the merged flow needs written beside

package/dist/merge.js

@@ -95,119 +95,8 @@ import { placeAddedNodes } from './node-placement.js';
 import { mergeAgentSidecars } from './merge-sidecars.js';
 import { embeddedAgentFindings, isEmbeddedAgent, mergeEmbeddedAgentNode } from './merge-embedded-agent.js';
 import { mergeObject, mergeVariables, stableJson } from './merge-variables.js';
+import { byId, isKept, nodeUnchanged, subflowsTakenFromEdited } from './edit-scope.js';
 export { MergeRefusedError } from './merge-roundtrip.js';
-function byId(nodes) {
-    return new Map((nodes ?? []).map((n) => [n.id, n]));
-}
-/**
- * Whether two nodes are the SAME as far as the author is concerned — same type,
- * same inputs and same output mappings. Layout (`ui`), `display`, `typeVersion`,
- * and the derived parts of `outputs` (type, schema, description) are ignored,
- * because those are exactly the parts decompile does not carry through. An
- * output's `source` is authored, not derived: it is what an End returns, so an
- * edit to `.return({ ... })` changes nothing else on the node. Used only to
- * decide "did the user edit this node?" against the baseline.
- */
-function nodeUnchanged(a, b) {
-    if (!a || !b)
-        return false;
-    if (a.type !== b.type)
-        return false;
-    return JSON.stringify(a.inputs ?? {}) === JSON.stringify(b.inputs ?? {})
-        && JSON.stringify(outputSources(a)) === JSON.stringify(outputSources(b));
-}
-/** Each output's `source` by output name; outputs without one are left out. */
-function outputSources(n) {
-    const sources = {};
-    for (const [name, output] of Object.entries(n.outputs ?? {})) {
-        if (output && typeof output === 'object' && 'source' in output)
-            sources[name] = output.source;
-    }
-    return sources;
-}
-/**
- * The ids of the root nodes {@link mergeFlow} takes from `edited` rather than
- * restoring from `original`: every node that is new, or that differs from its
- * `baseline` counterpart. With no baseline, that is every node.
- *
- * For instance, with a baseline equal to `edited` and every node present in
- * `original`, the answer is `[]` — a no-edit merge keeps them all.
- */
-export function nodesTakenFromEdited(original, edited, baseline) {
-    const origNodes = byId(original.nodes);
-    const baseNodes = byId(baseline?.nodes);
-    return (edited.nodes ?? []).filter((e) => !isKept(e, origNodes, baseNodes, baseline)).map((e) => e.id);
-}
-/**
- * The keys of the subflows {@link mergeFlow} takes from `edited` rather than
- * restoring from `original`: every subflow that is new, that the original does
- * not have, or that differs from its `baseline` counterpart in any way the
- * author can edit — a node's inputs, output sources or label, an edge, the
- * scope's `variables` or `layout` (`subflowUnchanged`, #1322). With no
- * baseline, that is every subflow. A kept subflow is the original's whole: its
- * nodes, edges, variables and layout.
- */
-export function subflowsTakenFromEdited(original, edited, baseline) {
-    return Object.keys(edited.subflows ?? {}).filter((key) => {
-        const orig = original.subflows?.[key];
-        const base = baseline?.subflows?.[key];
-        return !baseline || orig === undefined || base === undefined
-            || !subflowUnchanged(edited.subflows[key], base);
-    });
-}
-/** A node's canvas label, when it has one. */
-const labelOf = (n) => n?.display?.label;
-/**
- * Whether an edited subflow equals its baseline: the same node ids, each node
- * unchanged (`nodeUnchanged`) and under the same label, the same edges by
- * their endpoints and handles (ids are compile's own), and the same
- * `variables` and `layout` byte for byte. The scope's variables carry what the
- * nodes do not — a step's `{ updates }` row, a child `.input()` type, a `.var()`
- * default — and a kept subflow is the original's whole, so any of them changing
- * has to make the subflow a taken one.
- */
-function subflowUnchanged(e, b) {
-    const eNodes = byId(e.nodes);
-    const bNodes = byId(b.nodes);
-    if (eNodes.size !== bNodes.size)
-        return false;
-    for (const [id, n] of eNodes) {
-        const base = bNodes.get(id);
-        if (!nodeUnchanged(n, base) || labelOf(n) !== labelOf(base))
-            return false;
-    }
-    if (JSON.stringify(e.variables ?? null) !== JSON.stringify(b.variables ?? null))
-        return false;
-    // `layout.edges` is keyed by edge id, and ids come from one file-wide
-    // counter: a step added before the call shifts every id in the subflow
-    // without touching it. So routes are compared by the endpoints the id names
-    // (as the edges themselves are), and `layout.nodes` as it is.
-    if (JSON.stringify(layoutByEndpoints(e)) !== JSON.stringify(layoutByEndpoints(b)))
-        return false;
-    const eEdges = (e.edges ?? []).map(edgeKey).sort();
-    const bEdges = (b.edges ?? []).map(edgeKey).sort();
-    return eEdges.length === bEdges.length && eEdges.every((k, i) => k === bEdges[i]);
-}
-/** `<source>@<port>-><target>@<port>`: an edge's identity apart from its id. */
-const edgeKey = (x) => `${x.sourceNodeId}@${x.sourcePort}->${x.targetNodeId}@${x.targetPort}`;
-/** A scope's layout with its `edges` re-keyed by endpoints, so an id shift does not read as a change. */
-function layoutByEndpoints(sf) {
-    const layout = sf.layout;
-    if (!layout || typeof layout !== 'object')
-        return layout ?? null;
-    const byId = new Map((sf.edges ?? []).map((x) => [x.id, edgeKey(x)]));
-    const { edges, ...rest } = layout;
-    const routes = Object.entries(edges ?? {}).map(([id, route]) => [byId.get(id) ?? id, route]).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
-    return { ...rest, edges: Object.fromEntries(routes) };
-}
-/**
- * Whether merge restores `e`'s ORIGINAL node instead of taking `e`: there is a
- * baseline, the original has the node, and `e` equals its baseline counterpart.
- * {@link mergeFlow}'s node loop and {@link nodesTakenFromEdited} both ask this.
- */
-function isKept(e, origNodes, baseNodes, baseline) {
-    return !!baseline && origNodes.has(e.id) && nodeUnchanged(e, baseNodes.get(e.id));
-}
 /**
  * Give an edited node the original's position, by id.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.58.0",
+  "version": "6.58.1",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -96,5 +96,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "d70ce10e11def3cbb2d1d42ba52c76686dcfae2f"
+  "gitref": "5109abb1e51b0990a2318bf03312a805eb194fbf"
 }