@uipath/maestro-builder-sdk 6.57.0 → 6.58.0

package/dist/ref-resolve.d.ts

@@ -1,39 +1,3 @@
-/**
- * `$ref` resolution for SPLIT `.flow` files (design §5, Phase 5E).
- *
- * The format lets a `.flow` be split across sibling files with JSON Reference
- * (`{ "$ref": "./layout.json" }`) — used to sideline layout or definitions, or
- * to extract a subflow out of an oversized file
- * (`flow-schema/REF_RESOLUTION.md`, MST-8579). Decompile has to READ those, so
- * this resolves them into ONE object model before anything else looks at the
- * document.
- *
- * Compile keeps writing a single file, deliberately: nothing in the designer or
- * the skills splits files today, so write-through splitting would be a merge
- * concern with no producer to round-trip against.
- *
- * The semantics below are the platform resolver's, mirrored rather than
- * reinvented (`flow-schema/src/ref-resolver/`), because a file the platform
- * reads one way and the SDK another is worse than no support at all:
- *
- *  - **`$ref` replaces the whole object.** JSON Reference, not JSON Schema —
- *    sibling properties beside a `$ref` are dropped, not merged.
- *  - **Same-document fragments (`#/…`) are left ALONE.** They are legitimate
- *    internal pointers — a connector tool's `outputSchema` carries them — and
- *    they are not file references. Resolving them as filenames is the exact
- *    regression the platform's own guard exists to prevent.
- *  - **Relative paths only.** Absolute paths, Windows drive letters, protocol
- *    URIs and traversal above the referencing file's root are REFUSED, because
- *    a `.flow` is untrusted input and the alternative is a file-exfiltration
- *    primitive (`$ref: '/etc/passwd'`, `$ref: 'https://…'`).
- *  - **Any depth**, and resolved content is walked again for its own refs.
- *
- * Where this deliberately differs: an unresolvable ref is an ERROR here, not a
- * warning. The platform's resolver collects non-fatal errors because a canvas
- * can render a partial document and let a person fix it; decompile turns the
- * document into SOURCE, and a silently-missing subtree becomes source that
- * compiles to a different flow. Failing names the file that is missing.
- */
 /** How this module reads a sibling file. Injected so it is testable and so the
  * SDK core stays free of `node:fs`. */
 export type RefReader = (resolvedPath: string) => string;

package/dist/ref-resolve.js

@@ -34,6 +34,7 @@
  * document into SOURCE, and a silently-missing subtree becomes source that
  * compiles to a different flow. Failing names the file that is missing.
  */
+import { CompileRefusal } from './core/compile-refusal.js';
 /**
  * Collapse `.` and `..` segments, preserving a leading `/` for POSIX absolute
  * paths — the platform's `normalizePath`, same behavior.
@@ -60,13 +61,13 @@ function normalizePath(path) {
  */
 export function resolveRefPath(baseUri, refPath) {
     if (refPath.startsWith('#')) {
-        throw new Error(`$ref "${refPath}" is a same-document fragment, not a file — it must not be resolved as a path.`);
+        throw new CompileRefusal('JSON_REF_PATH_INVALID', `$ref "${refPath}" is a same-document fragment, not a file — it must not be resolved as a path.`);
     }
     if (refPath.startsWith('/') || /^[a-zA-Z]:/.test(refPath)) {
-        throw new Error(`$ref "${refPath}" is an absolute path; only relative paths are allowed.`);
+        throw new CompileRefusal('JSON_REF_PATH_INVALID', `$ref "${refPath}" is an absolute path; only relative paths are allowed.`);
     }
     if (refPath.includes('://')) {
-        throw new Error(`$ref "${refPath}" is a protocol URI; only relative file paths are allowed.`);
+        throw new CompileRefusal('JSON_REF_PATH_INVALID', `$ref "${refPath}" is a protocol URI; only relative file paths are allowed.`);
     }
     const normalizedBase = baseUri.replace(/\\/g, '/');
     const lastSlash = normalizedBase.lastIndexOf('/');
@@ -74,7 +75,7 @@ export function resolveRefPath(baseUri, refPath) {
     const resolved = normalizePath(`${baseDir}${refPath}`);
     const isAbsoluteBase = normalizedBase.startsWith('/') || /^[a-zA-Z]:\//.test(normalizedBase);
     if (!isAbsoluteBase && resolved.startsWith('..')) {
-        throw new Error(`$ref "${refPath}" escapes the project root.`);
+        throw new CompileRefusal('JSON_REF_PATH_INVALID', `$ref "${refPath}" escapes the project root.`);
     }
     return resolved;
 }
@@ -115,11 +116,11 @@ export function resolveFlowRefs(doc, options) {
             if (node.$ref.startsWith('#'))
                 return node;
             if (depth >= maxDepth) {
-                throw new Error(`$ref resolution exceeded ${maxDepth} levels at ${where} ("${node.$ref}").`);
+                throw new CompileRefusal('JSON_REF_TOO_DEEP', `$ref resolution exceeded ${maxDepth} levels at ${where} ("${node.$ref}").`);
             }
             const path = resolveRefPath(baseUri, node.$ref);
             if (visiting.has(path)) {
-                throw new Error(`Circular $ref at ${where}: "${node.$ref}" is already being resolved.`);
+                throw new CompileRefusal('JSON_REF_CIRCULAR', `Circular $ref at ${where}: "${node.$ref}" is already being resolved.`);
             }
             let text;
             try {
@@ -127,7 +128,7 @@ export function resolveFlowRefs(doc, options) {
             }
             catch (err) {
                 const why = err instanceof Error ? err.message : String(err);
-                throw new Error(`$ref at ${where} points at "${node.$ref}", which could not be read (${why}).`);
+                throw new CompileRefusal('JSON_REF_UNREADABLE', `$ref at ${where} points at "${node.$ref}", which could not be read (${why}).`);
             }
             let parsed;
             try {
@@ -135,7 +136,7 @@ export function resolveFlowRefs(doc, options) {
             }
             catch (err) {
                 const why = err instanceof Error ? err.message : String(err);
-                throw new Error(`$ref at ${where} points at "${node.$ref}", which is not valid JSON (${why}).`);
+                throw new CompileRefusal('JSON_REF_NOT_JSON', `$ref at ${where} points at "${node.$ref}", which is not valid JSON (${why}).`);
             }
             visiting.add(path);
             try {

package/dist/schema-version.d.ts

@@ -1,41 +1,3 @@
-/**
- * schema-version — the artifact's FILE-FORMAT version, as something an author
- * can declare and a decompile can PRESERVE.
- *
- * Every artifact family this SDK writes carries a version that describes the
- * DOCUMENT's grammar rather than the author's release: Flow's top-level
- * `version`, Case's top-level `version`, BPMN's `uipath:migrationVersion`. Until
- * now each family pinned exactly one value in its serializer's format profile
- * and overwrote whatever the input said, which is right for greenfield
- * authoring and wrong for the brownfield loop:
- *
- *   decompile(a 1.10 flow) -> compile -> a 1.9 flow, with nothing said.
- *
- * That silent rewrite is the hole this module closes. `.schemaVersion(v)` on
- * each builder declares the version the emitted document targets, decompile
- * emits the call so a round-trip re-declares what it read, and the serializer
- * writes what was declared instead of the pin.
- *
- * ## A declared version is a CLAIM, not a switch
- *
- * The rule that shapes this whole module is the one CASE_PARITY §3.8 states for
- * `.version()`: a document's version asserts that the whole document matches
- * that schema. An author writing `.version('30.0.0')` against the old
- * V20-emitting serializer produced an INVALID document, because the claim was
- * false. So `.schemaVersion()` accepts only versions this SDK can actually
- * write — {@link SchemaVersionPolicy.writable}, each row carrying the evidence
- * that says so — and refuses anything else rather than stamping a claim it
- * cannot back. Moving a document BETWEEN versions stays the product's job
- * (`uip maestro flow migrate`), because a hop can carry data repairs this SDK
- * has no way to reproduce.
- *
- * ## Comparing versions
- *
- * `'1.10' < '1.9'` as strings, which is exactly the wrong answer, and the same
- * trap sits in Case's `'30.0.0'` vs `'9.0.0'`. Nothing here compares version
- * strings with `<`; {@link compareSchemaVersions} splits on `.` and compares
- * segments numerically, and every gate goes through it.
- */
 /** The artifact families that carry a schema version. */
 export type ArtifactFamily = 'flow' | 'case' | 'bpmn';
 /** A version this SDK build can WRITE, with the evidence that says it can. */

package/dist/schema-version.js

@@ -36,6 +36,7 @@
  * strings with `<`; {@link compareSchemaVersions} splits on `.` and compares
  * segments numerically, and every gate goes through it.
  */
+import { CompileRefusal } from './core/compile-refusal.js';
 /** A version string the schema families use: dotted, numeric, e.g. `1.9`, `1.10`, `30.0.0`. */
 const SYNTAX = /^\d+(\.\d+)*$/;
 /** True when `value` is shaped like a schema version at all. */
@@ -52,7 +53,7 @@ export function isSchemaVersionSyntax(value) {
  */
 export function compareSchemaVersions(a, b) {
     if (!isSchemaVersionSyntax(a) || !isSchemaVersionSyntax(b)) {
-        throw new Error(`compareSchemaVersions: "${a}" / "${b}" is not a dotted-numeric schema version.`);
+        throw new Error(`internal SDK error: compareSchemaVersions: "${a}" / "${b}" is not a dotted-numeric schema version.`);
     }
     const left = a.split('.').map(Number);
     const right = b.split('.').map(Number);
@@ -134,7 +135,7 @@ export function resolveSchemaVersion(policy, requested) {
         return policy.default;
     const refusal = schemaVersionRefusal(policy, requested);
     if (refusal)
-        throw new Error(refusal);
+        throw new CompileRefusal('SCHEMA_VERSION_UNSUPPORTED', refusal);
     return requested;
 }
 export function preserveSchemaVersion(policy, declared) {

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;