@uipath/maestro-builder-sdk 6.56.0 → 6.58.0

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

@@ -0,0 +1,57 @@
+/** One name a script function reads from outside itself. */
+export interface ScriptFunctionCapture {
+    /** How the call is named in messages: `script(renderSafe)`. */
+    call: string;
+    /** The name read. */
+    name: string;
+    /** Where the binding it resolves to is declared, `file:line`. */
+    declaredAt: string;
+    /** Where the read is, `file:line`. */
+    readAt: string;
+}
+/** What the pass found in a source: the captures, and what it could not check. */
+export interface ScriptFunctionScope {
+    captures: ScriptFunctionCapture[];
+    /** `script(<arg>)` calls whose function-typed argument it could not follow, `file:line` each. */
+    unfollowed: string[];
+    /**
+     * `script(<arg>)` calls whose argument it could not follow and whose type is
+     * `any` or `unknown` (`fns.check` on an `any` object, a function from a `.js`
+     * file): a function or a string script's options, the pass cannot tell which.
+     */
+    untyped: string[];
+    /** How many distinct script functions it followed to a declaration. */
+    followed: number;
+    /**
+     * Each followed function's text as Node's type stripping leaves it, whitespace
+     * removed: what `Function.prototype.toString()` returns for it under that
+     * loader, so a lowered function can be matched to its declaration. Empty when
+     * this Node has no `module.stripTypeScriptTypes`.
+     */
+    followedTexts: Set<string>;
+}
+/**
+ * Every name a `script(fn)` function in `file` (or a file it imports) reads from
+ * outside itself, and every call whose function it could not follow.
+ *
+ * It follows a bare identifier (through `const`, a function declaration and
+ * imports between the author's files) and an inline function. Any other
+ * function-typed argument (`script(h.check)`, `script(fns.check)`, a wrapper's
+ * parameter) is `unfollowed`, and the caller refuses it rather than let a capture
+ * through unchecked. An argument that is not a function (`script({ code })`, or
+ * options passed by name) is the string form and is not a script function.
+ */
+export declare function scriptFunctionScope(file: string): ScriptFunctionScope;
+/** A whitespace-free key for comparing function texts. */
+export declare function functionTextKey(text: string): string;
+/**
+ * Why a loaded flow cannot be trusted with its script functions, or undefined.
+ *
+ * Fails closed: a function the pass could not follow, or fewer functions found in
+ * the source than `script(fn)` lowered (a call made through `const sc = script`,
+ * a re-exporting module, or a function from a file outside the program), is
+ * refused like a capture, because what it reads was not checked.
+ */
+export declare function scriptFunctionScopeProblem(file: string, lowered: readonly string[]): string | undefined;
+/** The message a load refuses with, one line per capture. */
+export declare function scriptFunctionCaptureMessage(captures: readonly ScriptFunctionCapture[]): string;

package/dist/script-function-scope.js

@@ -0,0 +1,203 @@
+import { relative } from 'node:path';
+import { typescript } from './core/typescript-module.js';
+import { isReference } from './core/script-function.js';
+/**
+ * Every name a `script(fn)` function in `file` (or a file it imports) reads from
+ * outside itself, and every call whose function it could not follow.
+ *
+ * It follows a bare identifier (through `const`, a function declaration and
+ * imports between the author's files) and an inline function. Any other
+ * function-typed argument (`script(h.check)`, `script(fns.check)`, a wrapper's
+ * parameter) is `unfollowed`, and the caller refuses it rather than let a capture
+ * through unchecked. An argument that is not a function (`script({ code })`, or
+ * options passed by name) is the string form and is not a script function.
+ */
+export function scriptFunctionScope(file) {
+    const ts = typescript();
+    const options = {
+        noLib: true, types: [], noEmit: true, skipLibCheck: true, allowImportingTsExtensions: true,
+        target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.NodeNext, moduleResolution: ts.ModuleResolutionKind.NodeNext,
+    };
+    const program = ts.createProgram([file], options);
+    const checker = program.getTypeChecker();
+    const cwd = process.cwd();
+    const where = (n) => {
+        const sf = n.getSourceFile();
+        return `${relative(cwd, sf.fileName) || sf.fileName}:${sf.getLineAndCharacterOfPosition(n.getStart()).line + 1}`;
+    };
+    const out = [];
+    const unfollowed = [];
+    const untyped = [];
+    const seen = new Set();
+    const followedTexts = new Set();
+    const strip = stripTypes();
+    for (const sf of program.getSourceFiles()) {
+        if (sf.isDeclarationFile || sf.fileName.includes('/node_modules/'))
+            continue;
+        const visit = (n) => {
+            if (ts.isCallExpression(n) && isScriptCall(ts, checker, n) && n.arguments.length > 0) {
+                const arg = n.arguments[0];
+                const fn = functionOf(ts, checker, arg);
+                if (!fn) {
+                    const type = checker.getTypeAtLocation(arg);
+                    if (type.getCallSignatures().length > 0)
+                        unfollowed.push(where(arg));
+                    else if (type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown))
+                        untyped.push(where(arg));
+                }
+                if (fn && !seen.has(fn)) {
+                    seen.add(fn);
+                    const text = strip?.(fnText(ts, fn));
+                    if (text !== undefined)
+                        followedTexts.add(text);
+                    const call = `script(${ts.isIdentifier(n.arguments[0]) ? n.arguments[0].text : 'function'})`;
+                    for (const c of capturesIn(ts, checker, fn))
+                        out.push({ call, name: c.id.text, declaredAt: where(c.decl), readAt: where(c.id) });
+                }
+            }
+            ts.forEachChild(n, visit);
+        };
+        visit(sf);
+    }
+    return { captures: out, unfollowed, untyped, followed: seen.size, followedTexts };
+}
+/** A whitespace-free key for comparing function texts. */
+export function functionTextKey(text) {
+    return text.replace(/\s+/g, '');
+}
+/**
+ * Node's own type stripping (`module.stripTypeScriptTypes`, Node 22.13+), as a
+ * function from a function's source text to its key; undefined when this Node
+ * does not have it, or the text does not strip on its own.
+ */
+function stripTypes() {
+    const getBuiltinModule = process.getBuiltinModule;
+    const mod = getBuiltinModule?.('node:module');
+    const stripTs = mod?.stripTypeScriptTypes;
+    if (!stripTs)
+        return undefined;
+    return (text) => {
+        try {
+            // Parenthesised, so an anonymous function expression is a valid statement.
+            const stripped = stripTs(`(${text})`, { mode: 'strip' });
+            return functionTextKey(stripped.slice(1, -1));
+        }
+        catch {
+            return undefined;
+        }
+    };
+}
+/** A function's source as `toString()` would start it: without `export` / `default`. */
+function fnText(ts, fn) {
+    const sf = fn.getSourceFile();
+    const mods = ts.canHaveModifiers(fn) ? ts.getModifiers(fn) ?? [] : [];
+    const lead = mods.filter((m) => m.kind === ts.SyntaxKind.ExportKeyword || m.kind === ts.SyntaxKind.DefaultKeyword);
+    const start = lead.length > 0 ? lead[lead.length - 1].end : fn.getStart();
+    return sf.text.slice(start, fn.end).trim();
+}
+/**
+ * Why a loaded flow cannot be trusted with its script functions, or undefined.
+ *
+ * Fails closed: a function the pass could not follow, or fewer functions found in
+ * the source than `script(fn)` lowered (a call made through `const sc = script`,
+ * a re-exporting module, or a function from a file outside the program), is
+ * refused like a capture, because what it reads was not checked.
+ */
+export function scriptFunctionScopeProblem(file, lowered) {
+    const scope = scriptFunctionScope(file);
+    const parts = [];
+    if (scope.captures.length > 0)
+        parts.push(scriptFunctionCaptureMessage(scope.captures));
+    // Which lowered functions the pass accounts for. Matched by text when it can
+    // be: under Node's type stripping a lowered function's text IS its
+    // declaration's, minus types, so each one must match a followed declaration,
+    // and a `script()` call that never ran accounts for nothing. When nothing
+    // matches at all, either the loader reprints (tsx) or nothing lowered was
+    // followed; then an argument it could not type keeps it closed, and the
+    // count is the backstop.
+    const keys = [...new Set(lowered.map(functionTextKey))];
+    const matched = keys.filter((k) => scope.followedTexts.has(k)).length;
+    const unaccounted = matched > 0
+        ? keys.length - matched
+        : (scope.untyped.length > 0 ? Math.max(scope.untyped.length, 1) : Math.max(0, keys.length - scope.followed));
+    const where = [...scope.unfollowed, ...(matched > 0 ? [] : scope.untyped)];
+    if (scope.unfollowed.length > 0 || unaccounted > 0) {
+        const at = where.length > 0 ? ` (${where.join(', ')})` : '';
+        parts.push(`${Math.max(scope.unfollowed.length + unaccounted, 1)} script function(s) could not be checked for names taken from the module${at}: `
+            + 'pass each function to `script()` by name, or inline (`script(fn)`, `script((vars) => …)`), from a `.ts` file, with `script` imported by that name.');
+    }
+    return parts.length > 0 ? parts.join('\n') : undefined;
+}
+/** The message a load refuses with, one line per capture. */
+export function scriptFunctionCaptureMessage(captures) {
+    const lines = captures.map((c) => `  ${c.call} reads ${c.name} (${c.readAt}), which resolves to ${c.declaredAt} in the author's code, `
+        + `but the lowered script runs alone, so ${c.name} would be the runtime's own global of that name, or nothing.`);
+    return `${captures.length} script function read(s) a name from outside the function:\n${lines.join('\n')}\n`
+        + 'Move the helper\'s code inside the function, or give it a name the runtime does not have.';
+}
+/**
+ * Whether a call is `script(…)` from an import: the callee is an identifier
+ * imported under the name `script`, or `<namespace import>.script`.
+ */
+function isScriptCall(ts, checker, call) {
+    const callee = call.expression;
+    if (ts.isIdentifier(callee)) {
+        const decl = checker.getSymbolAtLocation(callee)?.declarations?.[0];
+        return decl !== undefined && ts.isImportSpecifier(decl) && (decl.propertyName ?? decl.name).text === 'script';
+    }
+    if (ts.isPropertyAccessExpression(callee) && callee.name.text === 'script' && ts.isIdentifier(callee.expression)) {
+        const decl = checker.getSymbolAtLocation(callee.expression)?.declarations?.[0];
+        return decl !== undefined && ts.isNamespaceImport(decl);
+    }
+    return false;
+}
+/** The function an argument is, or names: inline, a declaration, or a `const` bound to one, through imports. */
+function functionOf(ts, checker, arg) {
+    const fnLike = (n) => {
+        while (n && (ts.isParenthesizedExpression(n) || ts.isAsExpression(n) || ts.isSatisfiesExpression(n)))
+            n = n.expression;
+        return n && (ts.isArrowFunction(n) || ts.isFunctionExpression(n) || ts.isFunctionDeclaration(n)) ? n : undefined;
+    };
+    const inline = fnLike(arg);
+    if (inline)
+        return inline;
+    if (!ts.isIdentifier(arg))
+        return undefined;
+    let symbol = checker.getSymbolAtLocation(arg);
+    if (symbol && symbol.flags & ts.SymbolFlags.Alias)
+        symbol = checker.getAliasedSymbol(symbol);
+    for (const d of symbol?.declarations ?? []) {
+        const f = ts.isVariableDeclaration(d) ? fnLike(d.initializer) : fnLike(d);
+        if (f)
+            return f;
+    }
+    return undefined;
+}
+/** Each read in `fn` of a binding declared outside it, with that declaration. */
+function capturesIn(ts, checker, fn) {
+    const found = [];
+    const names = new Set();
+    const inside = (d) => d.getSourceFile() === fn.getSourceFile() && d.pos >= fn.pos && d.end <= fn.end;
+    const visit = (n) => {
+        if (ts.isIdentifier(n) && isReference(ts, n) && !names.has(n.text)) {
+            const p = n.parent;
+            const symbol = ts.isShorthandPropertyAssignment(p) && p.name === n
+                ? checker.getShorthandAssignmentValueSymbol(p)
+                : checker.getSymbolAtLocation(n);
+            // An import, or any binding the author's own files declare outside the
+            // function. A name that resolves to nothing, or only to a declaration file
+            // (`console` once `@types/node` is in the program), is a global, and the
+            // lowering has judged it already. An import still lands on its specifier
+            // in the author's file.
+            const decl = symbol?.declarations?.find((d) => !inside(d) && !d.getSourceFile().isDeclarationFile);
+            if (decl && !symbol.declarations.some(inside)) {
+                names.add(n.text);
+                found.push({ id: n, decl });
+            }
+        }
+        ts.forEachChild(n, visit);
+    };
+    if (fn.body)
+        visit(fn.body);
+    return found;
+}

package/dist/sdk-resolve.js

@@ -3,6 +3,7 @@ import { existsSync } from 'node:fs';
 import { register } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import { PACKAGE_NAME } from './package-name.js';
+import { CompileRefusal } from './core/compile-refusal.js';
 let registered = false;
 /**
  * Make `import … from '@uipath/maestro-builder-sdk'` in authored source resolve
@@ -25,7 +26,7 @@ export function useThisSdkForAuthoredSource() {
             registered = true;
             return;
         }
-        throw new Error(`cannot point authored source at this copy of ${PACKAGE_NAME}: ${fileURLToPath(hook)} is missing, as in a bundle, `
+        throw new CompileRefusal('SDK_RESOLVE_HOOK_MISSING', `cannot point authored source at this copy of ${PACKAGE_NAME}: ${fileURLToPath(hook)} is missing, as in a bundle, `
             + 'so its imports would load a second copy and serialize wrong. Run the installed package, or load authored source yourself.');
     }
     register(hook);

package/dist/serialize.d.ts

@@ -188,9 +188,12 @@ export declare function assertFileWideIdsUnique(flow: any): void;
  * It holds for real definitions: of the 5,102 in the local registry index
  * (2026-09-30), 4,999 reference a `<bindings.…>` name and every one of them
  * declares that name in `model.bindings.values`, which is what the emitters
- * close. Agent resource definitions are the one exemption (see below).
+ * close. Agent resource definitions are one exemption (see below); `unbound`,
+ * the nodes a draft compile reported as `BINDING_MISSING`, is the other: such a
+ * node names no connection, so it writes no binding rows, and the draft finding
+ * already says so.
  *
  * @throws BindingRefusal `BINDING_PLACEHOLDER_UNRESOLVED`, naming each dangling
  * placeholder and the step that carries it.
  */
-export declare function assertBindingPlaceholdersResolve(flow: any): void;
+export declare function assertBindingPlaceholdersResolve(flow: any, unbound?: ReadonlySet<string>): void;