@uipath/maestro-builder-sdk 6.59.1 → 6.60.0

package/dist/core/script-function.d.ts

@@ -33,6 +33,18 @@ export interface ScriptRuntime {
     scopeGlobal: string;
     /** Every other global name the runtime provides: the language built-ins it has, `console`. */
     globals: ReadonlySet<string>;
+    /**
+     * Globals the runtime declares with `const` before the body runs. The body
+     * runs as a script, so declaring one at its top level is an early error
+     * ("Identifier '…' has already been declared"), and assigning one is a
+     * runtime error ("Assignment to constant variable.").
+     */
+    constGlobals?: ReadonlySet<string>;
+    /**
+     * Globals that are objects with a fixed set of members: any other member reads
+     * `undefined` in the runtime, so reading one is refused.
+     */
+    globalMembers?: ReadonlyMap<string, ReadonlySet<string>>;
     /** How errors name the runtime: `the Flow script runtime`. */
     name: string;
 }

package/dist/core/script-function.js

@@ -201,6 +201,7 @@ class Lowering {
             this.checkNoCapture();
             this.checkNoRedeclaredParameter();
         }
+        this.checkConstGlobals();
         this.visit(fn.body, 0);
         if (this.aliased.size > 0) {
             const name = [...this.aliased][0];
@@ -306,6 +307,102 @@ class Lowering {
                 + 'Give the local a name of its own.');
         }
     }
+    /**
+     * Refuse what the runtime's `const` globals make fail: a declaration of one at
+     * the body's top level, and an assignment to one where it is still the global.
+     * The body runs as a script, so its top level is the global scope: a `let`,
+     * `const`, `function` or `class` statement directly in it, and a `var` anywhere
+     * outside a nested function (it hoists), collides with the runtime's `const`.
+     */
+    checkConstGlobals() {
+        const { ts } = this;
+        const reserved = this.runtime.constGlobals;
+        if (!reserved || reserved.size === 0)
+            return;
+        const declared = new Set();
+        const assigned = new Set();
+        const body = this.fn.body;
+        const names = (n, into) => {
+            if (ts.isIdentifier(n)) {
+                if (reserved.has(n.text))
+                    into.add(n.text);
+                return;
+            }
+            for (const e of n.elements)
+                if (!ts.isOmittedExpression(e))
+                    names(e.name, into);
+        };
+        // Declarations need a block body; an expression-bodied arrow has none, but
+        // its expression can still assign one (below).
+        if (ts.isBlock(body)) {
+            for (let stmt of body.statements) {
+                // A label does not scope what it labels: `l: function console() {}` collides too (measured).
+                while (ts.isLabeledStatement(stmt))
+                    stmt = stmt.statement;
+                if (ts.isVariableStatement(stmt))
+                    for (const d of stmt.declarationList.declarations)
+                        names(d.name, declared);
+                if ((ts.isFunctionDeclaration(stmt) || ts.isClassDeclaration(stmt)) && stmt.name && reserved.has(stmt.name.text))
+                    declared.add(stmt.name.text);
+            }
+            // A `var` in a nested block hoists to the top level too.
+            const vars = (n) => {
+                if (ts.isFunctionLike(n) || ts.isClassLike(n))
+                    return;
+                if (ts.isVariableDeclarationList(n) && (n.flags & ts.NodeFlags.BlockScoped) === 0)
+                    for (const d of n.declarations)
+                        names(d.name, declared);
+                ts.forEachChild(n, vars);
+            };
+            ts.forEachChild(body, vars);
+        }
+        // An assignment to the global itself: an unresolved target with a reserved name.
+        const targets = (e) => {
+            if (ts.isIdentifier(e)) {
+                if (reserved.has(e.text) && !this.resolves(e))
+                    assigned.add(e.text);
+            }
+            else if (ts.isParenthesizedExpression(e))
+                targets(e.expression);
+            else if (ts.isArrayLiteralExpression(e))
+                e.elements.forEach((x) => targets(ts.isSpreadElement(x) ? x.expression : x));
+            else if (ts.isObjectLiteralExpression(e)) {
+                for (const p of e.properties) {
+                    if (ts.isShorthandPropertyAssignment(p)) {
+                        // The name resolves to the property; the value assigned is the variable's own symbol.
+                        const sym = this.checker.getShorthandAssignmentValueSymbol(p);
+                        if (reserved.has(p.name.text) && (!sym || isUndefinedSymbol(sym)))
+                            assigned.add(p.name.text);
+                    }
+                    else if (ts.isPropertyAssignment(p))
+                        targets(p.initializer);
+                    else if (ts.isSpreadAssignment(p))
+                        targets(p.expression);
+                }
+            }
+            else if (ts.isBinaryExpression(e) && e.operatorToken.kind === ts.SyntaxKind.EqualsToken)
+                targets(e.left);
+        };
+        const walk = (n) => {
+            if (ts.isBinaryExpression(n) && n.operatorToken.kind >= ts.SyntaxKind.FirstAssignment && n.operatorToken.kind <= ts.SyntaxKind.LastAssignment)
+                targets(n.left);
+            if ((ts.isPrefixUnaryExpression(n) || ts.isPostfixUnaryExpression(n))
+                && (n.operator === ts.SyntaxKind.PlusPlusToken || n.operator === ts.SyntaxKind.MinusMinusToken))
+                targets(n.operand);
+            if ((ts.isForOfStatement(n) || ts.isForInStatement(n)) && !ts.isVariableDeclarationList(n.initializer))
+                targets(n.initializer);
+            ts.forEachChild(n, walk);
+        };
+        walk(body);
+        for (const name of declared) {
+            this.problems.push(`it declares \`${name}\` at its top level, which ${this.runtime.name} has already declared with \`const\`: `
+                + `the script would fail with "Identifier '${name}' has already been declared". Rename it, or declare it inside a nested block or function.`);
+        }
+        for (const name of assigned) {
+            this.problems.push(`it assigns to \`${name}\`, which ${this.runtime.name} declares with \`const\`: the script would fail with "Assignment to constant variable.". `
+                + 'Use a local of another name.');
+        }
+    }
     /**
      * Walk the body: queue the renames and `__name` removals, and collect the
      * names the runtime would not have. `fnDepth` counts the non-arrow functions
@@ -374,8 +471,10 @@ class Lowering {
         }
         if (symbol && !isUndefinedSymbol(symbol))
             return;
-        if (id.text === this.runtime.scopeGlobal || this.runtime.globals.has(id.text))
+        if (id.text === this.runtime.scopeGlobal || this.runtime.globals.has(id.text)) {
+            this.checkGlobalMember(id);
             return;
+        }
         // `typeof x` of a bare name does not throw when `x` is absent, so it is a
         // legitimate probe. A compound operand (`typeof x.y`, `typeof f()`) is
         // evaluated first and does throw, so its names are checked as usual.
@@ -383,6 +482,25 @@ class Lowering {
             return;
         this.free.add(id.text);
     }
+    /**
+     * A member the runtime's object does not have (`crypto.getRandomValues`,
+     * `console.table`): read by name (`.x`, `['x']`) from the global itself.
+     */
+    checkGlobalMember(id) {
+        const { ts } = this;
+        const members = this.runtime.globalMembers?.get(id.text);
+        if (!members)
+            return;
+        const p = id.parent;
+        const name = ts.isPropertyAccessExpression(p) && p.expression === id ? p.name.text
+            : ts.isElementAccessExpression(p) && p.expression === id && ts.isStringLiteralLike(p.argumentExpression) ? p.argumentExpression.text
+                : undefined;
+        if (name === undefined || members.has(name))
+            return;
+        const problem = `it reads \`${id.text}.${name}\`, which ${this.runtime.name}'s \`${id.text}\` does not have: it has only ${[...members].map((m) => `\`${m}\``).join(', ')}.`;
+        if (!this.problems.includes(problem))
+            this.problems.push(problem);
+    }
     /** Whether an identifier resolves to a declaration in the function (as opposed to an ambient global). */
     resolves(id) {
         const s = this.checker.getSymbolAtLocation(id);

package/dist/nodes/script/flow/runtime.d.ts

@@ -4,11 +4,23 @@
  */
 import type { ScriptRuntime } from '../../../core/script-function.js';
 /**
- * What a Flow script body can read: the language's ES2020 built-ins, `console`,
- * and the runtime's `$vars`. From the Flow skill's `references/script.md` ("The
- * JavaScript runtime"), which also lists what reads `undefined` in a real run and
- * is therefore absent here: `Intl`, `URL`, `TextEncoder`, `Buffer`, `fetch`,
- * `require`, `structuredClone`. Change this when the runtime changes.
+ * What a Flow script body can read: the language's ES2020 built-ins, the
+ * globals the engine registers, `console`, and the runtime's `$vars`.
+ *
+ * Measured against UiPath/PO.BpmnEngine, which runs a script body with
+ * Jint 4.4.0 (`ScriptTaskService.InvokeScriptAsync`,
+ * `src/BpmnEngine/UiPath.PO.Worker/Services/ElementExecution/Script/ScriptTaskService.cs`):
+ * the body goes to `Engine.Evaluate` as a script, after `btoa`/`atob` (UTF-8),
+ * `randomUUID` and `crypto` (holding only `randomUUID`) are set
+ * (`src/BpmnEngine/UiPath.PO.BpmnEngine/Expressions/JavaScriptEvaluator.cs`) and
+ * two preludes declare {@link FLOW_SCRIPT_CONST_GLOBALS} with `const`. `Intl`,
+ * `URL`, `TextEncoder`, `Buffer`, `fetch`, `require` and `structuredClone` read
+ * `undefined` there, so they are absent here. Change this when the engine does.
+ *
+ * `aggregate`, `_aggregate`, `_pipe` and `uipath` exist but are the engine's
+ * undocumented helpers, so a script function may not read them; it may not
+ * redeclare or assign them either (`constGlobals`). Of `crypto` and `console`
+ * it may read only the members the engine's have (`globalMembers`).
  *
  * Annex B's `escape`/`unescape` are left off on purpose: they URL-encode, and
  * `escape` is the likeliest name for an author's own HTML-escape helper, which

package/dist/nodes/script/flow/runtime.js

@@ -1,9 +1,41 @@
 /**
- * What a Flow script body can read: the language's ES2020 built-ins, `console`,
- * and the runtime's `$vars`. From the Flow skill's `references/script.md` ("The
- * JavaScript runtime"), which also lists what reads `undefined` in a real run and
- * is therefore absent here: `Intl`, `URL`, `TextEncoder`, `Buffer`, `fetch`,
- * `require`, `structuredClone`. Change this when the runtime changes.
+ * The names the engine's preludes declare with `const` before the script runs
+ * (`ScriptTaskService.cs`, `WithBuiltInFunctions` and `WithConsole`). At the
+ * body's top level, a `const`, `let`, `var`, `function` or `class` of one fails
+ * with "Identifier '…' has already been declared", and an assignment to one with
+ * "Assignment to constant variable." (both measured on Jint 4.4.0). Inside a
+ * nested block or function the name is the author's own and is fine.
+ */
+const FLOW_SCRIPT_CONST_GLOBALS = new Set(['console', 'uipath', 'aggregate', '_aggregate', '_pipe']);
+/**
+ * The members the engine's own objects have; any other member reads
+ * `undefined`, so calling it throws "Property '…' of object is not a function"
+ * (measured on Jint 4.4.0). `crypto` holds only `randomUUID`
+ * (`JavaScriptEvaluator.cs`), and `console` only the five no-ops `WithConsole`
+ * declares (`ScriptTaskService.cs`).
+ */
+const FLOW_SCRIPT_GLOBAL_MEMBERS = new Map([
+    ['crypto', new Set(['randomUUID'])],
+    ['console', new Set(['debug', 'error', 'info', 'log', 'warn'])],
+]);
+/**
+ * What a Flow script body can read: the language's ES2020 built-ins, the
+ * globals the engine registers, `console`, and the runtime's `$vars`.
+ *
+ * Measured against UiPath/PO.BpmnEngine, which runs a script body with
+ * Jint 4.4.0 (`ScriptTaskService.InvokeScriptAsync`,
+ * `src/BpmnEngine/UiPath.PO.Worker/Services/ElementExecution/Script/ScriptTaskService.cs`):
+ * the body goes to `Engine.Evaluate` as a script, after `btoa`/`atob` (UTF-8),
+ * `randomUUID` and `crypto` (holding only `randomUUID`) are set
+ * (`src/BpmnEngine/UiPath.PO.BpmnEngine/Expressions/JavaScriptEvaluator.cs`) and
+ * two preludes declare {@link FLOW_SCRIPT_CONST_GLOBALS} with `const`. `Intl`,
+ * `URL`, `TextEncoder`, `Buffer`, `fetch`, `require` and `structuredClone` read
+ * `undefined` there, so they are absent here. Change this when the engine does.
+ *
+ * `aggregate`, `_aggregate`, `_pipe` and `uipath` exist but are the engine's
+ * undocumented helpers, so a script function may not read them; it may not
+ * redeclare or assign them either (`constGlobals`). Of `crypto` and `console`
+ * it may read only the members the engine's have (`globalMembers`).
  *
  * Annex B's `escape`/`unescape` are left off on purpose: they URL-encode, and
  * `escape` is the likeliest name for an author's own HTML-escape helper, which
@@ -15,8 +47,11 @@
 export const FLOW_SCRIPT_RUNTIME = {
     scopeGlobal: '$vars',
     name: 'the Flow script runtime',
+    constGlobals: FLOW_SCRIPT_CONST_GLOBALS,
+    globalMembers: FLOW_SCRIPT_GLOBAL_MEMBERS,
     globals: new Set([
         'undefined', 'NaN', 'Infinity', 'globalThis', 'console',
+        'btoa', 'atob', 'randomUUID', 'crypto',
         'Object', 'Function', 'Array', 'Number', 'Boolean', 'String', 'Symbol', 'BigInt', 'Date', 'RegExp', 'Math', 'JSON',
         'Promise', 'Proxy', 'Reflect', 'Map', 'Set', 'WeakMap', 'WeakSet',
         'Error', 'EvalError', 'RangeError', 'ReferenceError', 'SyntaxError', 'TypeError', 'URIError',

package/dist/script-globals.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The globals the Flow script runtime gives a script body beyond the language,
+ * as types, for a `.flow.ts` that type-checks its script functions.
+ *
+ * Opt in from the file that uses them:
+ *
+ * ```ts
+ * /// <reference types="@uipath/maestro-builder-sdk/script-globals" />
+ * ```
+ *
+ * Types only. A script function is never called in Node; its body runs on the
+ * engine, which provides these names (UiPath/PO.BpmnEngine,
+ * `src/BpmnEngine/UiPath.PO.BpmnEngine/Expressions/JavaScriptEvaluator.cs`).
+ * Importing an implementation instead would not work: `compile` refuses a script
+ * function that reads a name from its module.
+ *
+ * Opt-in rather than part of the package entry, so importing the SDK does not
+ * add globals to every program that does.
+ *
+ * `btoa` and `atob` repeat the signatures `@types/node` and the DOM library
+ * declare, so they merge with either; they are here for a program that has
+ * neither. Note the engine's are UTF-8, where Node's and the browser's are
+ * Latin-1 and throw on a character above U+00FF. `crypto` is not declared:
+ * the engine's holds only `randomUUID`, and both of those libraries already
+ * type `crypto.randomUUID()`.
+ */
+export {};
+declare global {
+    /** A fresh lowercase, hyphenated v4 UUID. The engine also exposes it as `crypto.randomUUID`. */
+    function randomUUID(): string;
+    /** Base64 of a string's UTF-8 bytes, in the engine (Node's and the browser's take Latin-1). */
+    function btoa(data: string): string;
+    /** The string whose UTF-8 bytes a Base64 string encodes, in the engine. */
+    function atob(data: string): string;
+}

package/dist/script-globals.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.59.1",
+  "version": "6.60.0",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -37,6 +37,10 @@
       "types": "./dist/cli/index.d.ts",
       "import": "./dist/cli/index.js"
     },
+    "./script-globals": {
+      "types": "./dist/script-globals.d.ts",
+      "import": "./dist/script-globals.js"
+    },
     "./registry-materializer": {
       "types": "./dist/registry/materializer.d.ts",
       "import": "./dist/registry/materializer.js"
@@ -96,5 +100,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "b7b4631f9c98cab1479e0d5ec9495f43651e93f8"
+  "gitref": "d9059695caec0a3b1f3b215f5b830451dbdbdad9"
 }