@uipath/maestro-builder-sdk 6.25.1 → 6.27.0

package/dist/check.js

@@ -29,7 +29,7 @@ import { ownEntry } from './core/own-entry.js';
 import { FLOW_NODE_TYPES } from './flow-node-registry.js';
 import { stepExits } from './flow-step-exits.js';
 import { plainHttpOnErrorMessage } from './nodes/http/flow/family.js';
-import { resolveVersion } from './core/nodes/versioned.js';
+import { resolveVersion, resolveVersionCarried } from './core/nodes/versioned.js';
 import { declaredErrorPortRefusal } from './core/error-port.js';
 export function check(built, opts = {}) {
     let diags = [];
@@ -275,7 +275,7 @@ function checkFlow(built, ancestors, opts = {}) {
                 declared.add(s.name); // a step's output is referenceable by name
             }
             if ((s.kind === 'stepToList' || s.kind === 'stepToRef') && s.port === 'error')
-                checkOnError(s, prevPortSource, diags, prevPortSource && checkedSteps.get(prevPortSource.name));
+                checkOnError(s, prevPortSource, diags, prevPortSource && checkedSteps.get(prevPortSource.name), carriedLookup([built, ...ancestors]));
             if ((s.kind === 'stepToList' || s.kind === 'stepToRef') && s.port.startsWith('branch-')) {
                 const want = s.port.slice('branch-'.length);
                 const prevSpec = prevAction?.spec;
@@ -381,7 +381,7 @@ function checkFlow(built, ancestors, opts = {}) {
                 prevPortSource = s;
                 const registered = registeredKind(s.spec);
                 if (registered) {
-                    const { placed, checked } = checkRegisteredStep(registered, s, exprs, errorSource, opts, diags, typeOf, triggerId);
+                    const { placed, checked } = checkRegisteredStep(registered, s, exprs, errorSource, opts, diags, typeOf, triggerId, carriedLookup([built, ...ancestors]));
                     checkedSteps.set(s.name, checked);
                     if (placed)
                         registeredSteps.set(s.name, checked);
@@ -518,13 +518,51 @@ function checkFlow(built, ancestors, opts = {}) {
                 walk(s.otherwise, inLoop);
             }
             else if (s.kind === 'switch') {
-                addExpr(s.on.js, s.name);
+                if (s.on)
+                    addExpr(s.on.js, s.name);
+                for (const c of s.cases)
+                    if (c.when)
+                        addExpr(c.when.js, s.name);
                 switchNames.add(s.name);
+                s.cases.forEach((c, i) => {
+                    const hasValue = c.value !== undefined;
+                    const hasWhen = c.when !== undefined;
+                    if (hasValue === hasWhen || (hasValue && !s.on)) {
+                        diags.push({
+                            level: 'error',
+                            code: 'SWITCH_CASE_FORM',
+                            message: hasValue && hasWhen
+                                ? `Switch "${s.name}" case ${i + 1} has both \`value\` and \`when\`. Give it one: \`value\` is compared with \`on\`, \`when\` is the case's own condition.`
+                                : hasValue
+                                    ? `Switch "${s.name}" case ${i + 1} has a \`value\` but the switch has no \`on\` to compare it with. Pass \`on\`, or give the case a \`when\` condition.`
+                                    : `Switch "${s.name}" case ${i + 1} has neither \`value\` nor \`when\`.`,
+                            step: s.name,
+                        });
+                    }
+                    if (hasWhen && c.when.literal) {
+                        diags.push({
+                            level: 'error',
+                            code: 'SWITCH_CONST_WHEN',
+                            message: `Switch "${s.name}" case ${i + 1}'s \`when\` is the constant ${JSON.stringify(c.when.value)}, so it is always or never taken. Pass an expression.`,
+                            step: s.name,
+                        });
+                    }
+                });
                 // A constant discriminant can never match a case — it is what
                 // `.switch('q', 'quarter', …)` (a name where an expression belongs)
                 // degrades into once types are stripped, and it would emit
                 // `"quarter" === 2`: valid JS, always false, default arm every time.
-                if (s.on.literal)
+                // `on` is compared only with `value` cases; with none, it is unused.
+                const hasValueCase = s.cases.some((c) => c.value !== undefined);
+                if (s.on && !hasValueCase && s.cases.length > 0)
+                    diags.push({
+                        level: 'warning',
+                        code: 'SWITCH_ON_UNUSED',
+                        message: `Switch "${s.name}" has an \`on\`, but every case has its own \`when\` condition, so \`on\` is never compared. `
+                            + 'Pass `undefined` for `on`.',
+                        step: s.name,
+                    });
+                if (s.on?.literal && hasValueCase)
                     diags.push({
                         level: 'error',
                         code: 'SWITCH_CONST_ON',
@@ -563,12 +601,12 @@ function checkFlow(built, ancestors, opts = {}) {
                     seenIds.add(String(caseId));
                 });
                 for (const c of s.cases) {
-                    const key = `${typeof c.value}:${String(c.value)}`;
+                    const key = c.when !== undefined ? `when:${c.when.js}` : `${typeof c.value}:${String(c.value)}`;
                     if (seenValues.has(key))
                         diags.push({
                             level: 'error',
                             code: 'DUP_CASE',
-                            message: `Switch "${s.name}" has two cases for ${JSON.stringify(c.value)}; the second is unreachable `
+                            message: `Switch "${s.name}" has two cases for ${c.when !== undefined ? `when ${c.when.js}` : JSON.stringify(c.value)}; the second is unreachable `
                                 + '(the first matching case wins).',
                             step: s.name,
                         });
@@ -577,7 +615,7 @@ function checkFlow(built, ancestors, opts = {}) {
                         diags.push({
                             level: 'warning',
                             code: 'EMPTY_ARM',
-                            message: `Switch "${s.name}" has an empty arm for case ${JSON.stringify(c.value)}.`,
+                            message: `Switch "${s.name}" has an empty arm for case ${c.when !== undefined ? `when ${c.when.js}` : JSON.stringify(c.value)}.`,
                             step: s.name,
                         });
                     walk(c.body, inLoop);
@@ -3935,6 +3973,8 @@ function reportUnreachableHitlOutcomes(choices, exprs, diags) {
  * and so are object/array/any/file discriminants — nothing useful to compare.
  */
 function checkCaseValueTypes(s, typeOf, diags, triggerId) {
+    if (!s.on)
+        return;
     const refName = declaredRefName(s.on.js, triggerId);
     if (!refName)
         return;
@@ -3946,6 +3986,8 @@ function checkCaseValueTypes(s, typeOf, diags, triggerId) {
     if (!expected)
         return;
     for (const c of s.cases) {
+        if (c.value === undefined)
+            continue;
         const actual = typeof c.value;
         if (actual === expected)
             continue;
@@ -3977,6 +4019,11 @@ const LOOP_FIELDS = new Set(['currentItem', 'currentIteration', 'collection', 'o
  * before the 2.4 default (#868); its own fields are not audited here.
  */
 const LOOP_FIELDS_1_0_0 = new Set(['currentItem', 'currentIndex', 'collection', 'output', 'error']);
+/** The {@link CarriedLookup} over `scopes` — the flow being checked first, then its ancestors. */
+function carriedLookup(scopes) {
+    const all = scopes.flatMap((b) => b.definitions ?? []);
+    return Object.assign((typeName, version) => all.find((d) => d.nodeType === typeName && d.version === version), { versions: (typeName) => [...new Set(all.filter((d) => d.nodeType === typeName).map((d) => String(d.version)))] });
+}
 /** The registered node type for a spec's kind, or undefined (a custom FlowAction has no kind). */
 function registeredKind(spec) {
     const kind = spec?.kind;
@@ -3994,14 +4041,15 @@ function registeredKind(spec) {
  * which serialize enforces (#942) and the type's tests pin; an author cannot
  * cause the gap, so there is no author diagnostic to report.
  */
-function checkRegisteredStep(entry, s, exprs, errorSource, opts, diags, typeOf, triggerId) {
+function checkRegisteredStep(entry, s, exprs, errorSource, opts, diags, typeOf, triggerId, carried) {
     const spec = s.spec;
     /** The step's node-local rules and expressions, as `impl` defines them. */
-    const runRules = (impl) => {
+    const runRules = (impl, version = impl.version, carriedDef) => {
         const ctx = {
             step: s.name,
-            version: impl.version,
-            definition: () => bundledDefinition(impl.typeName, impl.version),
+            // At a carried version, the version and definition serialize emits.
+            version,
+            definition: () => carriedDef ?? bundledDefinition(impl.typeName, impl.version),
             report: (code, message, suggestion) => diags.push(catalogued(entry, s.name, code, message, suggestion)),
             declaredRef: (js) => {
                 const name = declaredRefName(js, triggerId);
@@ -4024,8 +4072,14 @@ function checkRegisteredStep(entry, s, exprs, errorSource, opts, diags, typeOf,
         return ctx;
     };
     let impl;
+    let version;
+    let carriedDef;
     try {
-        impl = resolveVersion(entry.type, spec, s.options?.version, `step "${s.name}"`);
+        // A pin the registry lacks but the flow carries resolves (#1128), as in serialize.
+        const resolved = resolveVersionCarried(entry.type, spec, s.options?.version, `step "${s.name}"`, carried);
+        impl = resolved.impl;
+        version = resolved.version;
+        carriedDef = resolved.carried;
     }
     catch (e) {
         // A select() that picks an unregistered version is the node type's bug, not the author's pin.
@@ -4043,8 +4097,14 @@ function checkRegisteredStep(entry, s, exprs, errorSource, opts, diags, typeOf,
             checked: { entry, impl: fallback, spec, placement: { step: s.name, kind: fallback.kind, spec, version: fallback.version }, ctx: fallbackCtx },
         };
     }
-    const ctx = runRules(impl);
-    return { placed: true, checked: { entry, impl, spec, placement: { step: s.name, kind: impl.kind, spec, version: impl.version }, ctx } };
+    const ctx = runRules(impl, version, carriedDef);
+    return {
+        placed: true,
+        checked: {
+            entry, impl, spec, placement: { step: s.name, kind: impl.kind, spec, version }, ctx,
+            ...(carriedDef !== undefined ? { carried: carriedDef } : {}),
+        },
+    };
 }
 /** Every non-literal Expr reachable in `value`, as expressions to check. */
 function pushDeepExprs(value, step, errorSource, out) {
@@ -4171,7 +4231,7 @@ const ERROR_ENVELOPE_FIELDS = ['code', 'message', 'detail', 'category', 'status'
  */
 function checkOnError(_handler, step, diags, 
 /** The step's registry record, when its kind is registered and its version resolved. */
-placed) {
+placed, carried) {
     // The builder refuses a handler with no eligible step before it, so a missing
     // source here means a hand-built `BuiltFlow`; there is nothing to say about it.
     if (!step)
@@ -4243,7 +4303,7 @@ placed) {
             }
         }
         else {
-            const def = bundledDefinition(impl.typeName, impl.version);
+            const def = placed.carried ?? bundledDefinition(impl.typeName, impl.version);
             if (def !== undefined && !definitionHasErrorPort(def)) {
                 diags.push({ level: 'error', code: 'ONERROR_NO_ERROR_PORT', message: typedNoErrorPortMessage(step.name, impl.kind, def), step: step.name });
                 return;
@@ -4262,7 +4322,12 @@ placed) {
     // A version the SDK does not bundle (an inline agent's registry version) has
     // no definition here to ask; version resolution reports that, not this check.
     const bundledType = bundledActionNodeType(spec);
-    const bundledDef = bundledType ? bundledDefinition(bundledType, actionVersion(spec, step.options?.version)) : undefined;
+    // A version the flow CARRIES (`.definitions()`, #1128) answers the same way
+    // a bundled one does: it is the definition serialize will emit.
+    const pinned = step.options?.version;
+    const bundledDef = bundledType
+        ? bundledDefinition(bundledType, actionVersion(spec, pinned)) ?? (pinned !== undefined ? carried?.(bundledType, pinned) : undefined)
+        : undefined;
     // A per-tenant family: ask the definition serialize synthesizes for it (#1040).
     let perCallDef;
     if (!bundledType) {

package/dist/core/carried-definitions.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Node definitions a flow CARRIES — the third source a pinned `{ version }`
+ * resolves from, after the SDK's bundle (#1128).
+ *
+ * Every `.flow` file holds the exact definition of every node it uses, in
+ * `definitions[]`. The SDK bundles only the versions it was released with, so
+ * a version the registry served later (`node add` writes
+ * `uipath.human-in-the-loop.quick-form@1.6`; the SDK ships 1.0 and 1.1) used
+ * to be refused, and the source decompile wrote for an untouched product flow
+ * did not compile. A carried definition closes that: decompile copies the
+ * file's own entry into `.definitions([...])`, and compile resolves the pin
+ * against it.
+ *
+ * A carried definition is an exact copy of a real one, never a way to invent a
+ * version. So it is validated the way a `rawNode` snapshot manifest is: it
+ * names its own `nodeType` and `version`, and it has the `display.label` every
+ * node manifest has.
+ */
+/** A carried definition, by its `<nodeType>@<version>` key. */
+export type CarriedDefinitions = ReadonlyMap<string, Record<string, unknown>>;
+/**
+ * Why `manifest` cannot be carried, or `undefined` when it can.
+ *
+ * For instance `{ nodeType: 'x', version: '1.0' }` is refused for lacking
+ * `display.label`.
+ */
+export declare function carriedDefinitionRefusal(manifest: unknown, where: string): string | undefined;
+/**
+ * Index `manifests` by `<nodeType>@<version>`. Throws on an invalid manifest,
+ * or on two different manifests for one pair (which one compiles would be a
+ * guess).
+ */
+export declare function indexCarriedDefinitions(manifests: readonly unknown[], where: string, into?: Map<string, Record<string, unknown>>): Map<string, Record<string, unknown>>;

package/dist/core/carried-definitions.js

@@ -0,0 +1,63 @@
+/**
+ * Node definitions a flow CARRIES — the third source a pinned `{ version }`
+ * resolves from, after the SDK's bundle (#1128).
+ *
+ * Every `.flow` file holds the exact definition of every node it uses, in
+ * `definitions[]`. The SDK bundles only the versions it was released with, so
+ * a version the registry served later (`node add` writes
+ * `uipath.human-in-the-loop.quick-form@1.6`; the SDK ships 1.0 and 1.1) used
+ * to be refused, and the source decompile wrote for an untouched product flow
+ * did not compile. A carried definition closes that: decompile copies the
+ * file's own entry into `.definitions([...])`, and compile resolves the pin
+ * against it.
+ *
+ * A carried definition is an exact copy of a real one, never a way to invent a
+ * version. So it is validated the way a `rawNode` snapshot manifest is: it
+ * names its own `nodeType` and `version`, and it has the `display.label` every
+ * node manifest has.
+ */
+/**
+ * Why `manifest` cannot be carried, or `undefined` when it can.
+ *
+ * For instance `{ nodeType: 'x', version: '1.0' }` is refused for lacking
+ * `display.label`.
+ */
+export function carriedDefinitionRefusal(manifest, where) {
+    if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+        return `${where}: a carried definition must be a node manifest object.`;
+    }
+    const m = manifest;
+    if (typeof m.nodeType !== 'string' || !m.nodeType || typeof m.version !== 'string' || !m.version) {
+        return `${where}: a carried definition must name its exact nodeType and version.`;
+    }
+    if (typeof m.display?.label !== 'string' || !m.display.label) {
+        return `${where}: the carried definition ${m.nodeType}@${m.version} lacks display.label — not a valid node manifest.`;
+    }
+    return undefined;
+}
+/**
+ * Index `manifests` by `<nodeType>@<version>`. Throws on an invalid manifest,
+ * or on two different manifests for one pair (which one compiles would be a
+ * guess).
+ */
+export function indexCarriedDefinitions(manifests, where, into = new Map()) {
+    for (const m of manifests) {
+        const refusal = carriedDefinitionRefusal(m, where);
+        if (refusal)
+            throw new Error(refusal);
+        const def = m;
+        const key = `${def.nodeType}@${def.version}`;
+        const prior = into.get(key);
+        if (prior !== undefined && stableJson(prior) !== stableJson(def)) {
+            throw new Error(`${where}: two different carried definitions for ${key}. Keep the one the file holds.`);
+        }
+        into.set(key, def);
+    }
+    return into;
+}
+/** `JSON.stringify` with object keys sorted, so two copies of one manifest compare equal whatever their key order. */
+function stableJson(value) {
+    return JSON.stringify(value, (_key, v) => (v && typeof v === 'object' && !Array.isArray(v)
+        ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, v[k]]))
+        : v));
+}

package/dist/core/nodes/versioned.d.ts

@@ -48,3 +48,38 @@ export declare function asVersioned<Ctx extends ArtifactContexts>(t: AnyNodeType
  * node type's bug, not the author's, and throws as an internal SDK error.
  */
 export declare function resolveVersion<Spec, Ctx extends ArtifactContexts>(t: VersionedNodeType<Spec, unknown, Ctx>, spec: Spec, requested: string | undefined, where: string): NodeType<Spec, unknown, Ctx>;
+/**
+ * Looks up a definition the flow carries (`.definitions()`) for `typeName@version`.
+ * `versions`, when present, lists every version of `typeName` the flow carries,
+ * so a refusal can name them.
+ */
+export type CarriedDefinitionLookup = ((typeName: string, version: string) => Record<string, unknown> | undefined) & {
+    readonly versions?: (typeName: string) => readonly string[];
+};
+/** What {@link resolveVersionCarried} resolved: the implementation, the version to emit, and a carried definition when one answered. */
+export interface ResolvedNodeVersion<Impl> {
+    readonly impl: Impl;
+    /** The version the node is emitted at — `impl.version`, or the carried version. */
+    readonly version: string;
+    /** The definition the FLOW carries for `typeName@version`, when the registry has no implementation at that version. */
+    readonly carried?: Record<string, unknown>;
+}
+/**
+ * {@link resolveVersion} with the third definition source (#1128): a definition
+ * the flow CARRIES (`.definitions()`, decompile's copy of the file's own
+ * `definitions[]` entry).
+ *
+ * Order: a registered version resolves as before. An explicit version the type
+ * does not register, but the flow carries, is emitted AT that version with the
+ * carried definition, through the implementation the type would use unpinned
+ * (`select(spec)`, else the default) — the registry has no implementation of
+ * its own for it, and the node keeps the version the file pins instead of being
+ * refused. Anything else is refused as {@link resolveVersion} refuses it, except
+ * that an unregistered pin also names the versions the flow carries and the
+ * `.definitions()` remedy.
+ *
+ * For instance a file pinning `core.action.script@1.0` (registered: 1.0.0, 1.1)
+ * and carrying that definition emits the node at 1.0 through the default
+ * implementation.
+ */
+export declare function resolveVersionCarried<Spec, Ctx extends ArtifactContexts>(t: VersionedNodeType<Spec, unknown, Ctx>, spec: Spec, requested: string | undefined, where: string, carried: CarriedDefinitionLookup | undefined): ResolvedNodeVersion<NodeType<Spec, unknown, Ctx>>;

package/dist/core/nodes/versioned.js

@@ -44,3 +44,38 @@ export function resolveVersion(t, spec, requested, where) {
     }
     return impl;
 }
+/**
+ * {@link resolveVersion} with the third definition source (#1128): a definition
+ * the flow CARRIES (`.definitions()`, decompile's copy of the file's own
+ * `definitions[]` entry).
+ *
+ * Order: a registered version resolves as before. An explicit version the type
+ * does not register, but the flow carries, is emitted AT that version with the
+ * carried definition, through the implementation the type would use unpinned
+ * (`select(spec)`, else the default) — the registry has no implementation of
+ * its own for it, and the node keeps the version the file pins instead of being
+ * refused. Anything else is refused as {@link resolveVersion} refuses it, except
+ * that an unregistered pin also names the versions the flow carries and the
+ * `.definitions()` remedy.
+ *
+ * For instance a file pinning `core.action.script@1.0` (registered: 1.0.0, 1.1)
+ * and carrying that definition emits the node at 1.0 through the default
+ * implementation.
+ */
+export function resolveVersionCarried(t, spec, requested, where, carried) {
+    if (requested !== undefined && !ownEntry(t.versions, requested)) {
+        const def = carried?.(t.typeName, requested);
+        if (def !== undefined) {
+            return { impl: resolveVersion(t, spec, undefined, where), version: requested, carried: def };
+        }
+        // Refused: name both sources, and the way to add the second one.
+        const registered = Object.keys(t.versions).sort().join(', ');
+        const carriedVersions = [...(carried?.versions?.(t.typeName) ?? [])].sort();
+        throw new Error(`${where} requests ${t.typeName}@${requested}, but this SDK registers only ${registered}`
+            + (carriedVersions.length > 0 ? ` and the flow carries only ${carriedVersions.join(', ')}` : '')
+            + '. Versions are exact — omit { version } to use the default, request one listed here, or carry '
+            + "that version's definition (the .flow file's definitions[] entry) with .definitions([...]).");
+    }
+    const impl = resolveVersion(t, spec, requested, where);
+    return { impl, version: impl.version };
+}