@uipath/maestro-builder-sdk 5.2.0

package/dist/bpmn/xml-ranges.d.ts

@@ -0,0 +1,45 @@
+/**
+ * xml-ranges — locate elements by their SOURCE RANGE in an XML document.
+ *
+ * A tolerant scanner, not a parser: it reports where each element's text begins and
+ * ends and nothing about what it means. That is all a merge needs, and it is the only
+ * shape that can preserve an element **byte for byte** — the merged document is the
+ * original text with a few ranges spliced, so anything untouched is untouched in the
+ * literal sense, down to attribute order, quoting and indentation.
+ *
+ * Why not `bpmn-moddle`, which the SDK already depends on: a moddle round trip
+ * normalises. It drops attributes its descriptor does not declare, and the whole point
+ * of a brownfield merge is to carry through exactly the payloads the builder does NOT
+ * model. Reading with moddle would lose the thing being preserved.
+ *
+ * Correspondingly, this file must not be mistaken for a general XML implementation. It
+ * handles what a `.bpmn` contains — elements, attributes, comments, CDATA, processing
+ * instructions, a doctype — and it assumes well-formed input, because every caller has
+ * either just written the file or is about to hand it to a real parser anyway.
+ */
+/** One element's place in the source text. */
+export interface XmlRange {
+    /** Qualified name as written, e.g. `bpmn:scriptTask`. */
+    readonly name: string;
+    /** Name without its prefix, e.g. `scriptTask`. */
+    readonly local: string;
+    /** `id` attribute, when present — how a merge keys one document's element to another's. */
+    readonly id?: string;
+    /** Offset of `<`. */
+    readonly start: number;
+    /** Offset just past `>` of the close tag (or of the self-closing tag). */
+    readonly end: number;
+    /** Offset just past `>` of the OPEN tag — where this element's content begins. */
+    readonly innerStart: number;
+    /** Offset of `<` of the close tag. Equals `innerStart` when self-closing. */
+    readonly innerEnd: number;
+    readonly attributes: Readonly<Record<string, string>>;
+    readonly children: readonly XmlRange[];
+}
+/**
+ * Every element in the document, as a tree of source ranges. The returned array holds
+ * the top-level elements — a `.bpmn` has exactly one, `bpmn:definitions`.
+ */
+export declare function parseXmlRanges(xml: string): readonly XmlRange[];
+/** Depth-first search for the first element with the given local name. */
+export declare function findByLocal(nodes: readonly XmlRange[], local: string): XmlRange | undefined;

package/dist/bpmn/xml-ranges.js

@@ -0,0 +1,151 @@
+/**
+ * xml-ranges — locate elements by their SOURCE RANGE in an XML document.
+ *
+ * A tolerant scanner, not a parser: it reports where each element's text begins and
+ * ends and nothing about what it means. That is all a merge needs, and it is the only
+ * shape that can preserve an element **byte for byte** — the merged document is the
+ * original text with a few ranges spliced, so anything untouched is untouched in the
+ * literal sense, down to attribute order, quoting and indentation.
+ *
+ * Why not `bpmn-moddle`, which the SDK already depends on: a moddle round trip
+ * normalises. It drops attributes its descriptor does not declare, and the whole point
+ * of a brownfield merge is to carry through exactly the payloads the builder does NOT
+ * model. Reading with moddle would lose the thing being preserved.
+ *
+ * Correspondingly, this file must not be mistaken for a general XML implementation. It
+ * handles what a `.bpmn` contains — elements, attributes, comments, CDATA, processing
+ * instructions, a doctype — and it assumes well-formed input, because every caller has
+ * either just written the file or is about to hand it to a real parser anyway.
+ */
+const ATTRIBUTE = /([^\s=/>]+)\s*=\s*("([^"]*)"|'([^']*)')/g;
+function parseAttributes(source) {
+    const attributes = {};
+    for (const match of source.matchAll(ATTRIBUTE)) {
+        attributes[match[1]] = match[3] ?? match[4] ?? '';
+    }
+    return attributes;
+}
+/**
+ * Find the `>` that closes a tag opening at `from`, ignoring any inside a quoted
+ * attribute value — `targetNamespace="http://…/>"` is not the end of the tag.
+ */
+function endOfTag(xml, from) {
+    let quote = null;
+    for (let i = from; i < xml.length; i += 1) {
+        const c = xml[i];
+        if (quote) {
+            if (c === quote)
+                quote = null;
+        }
+        else if (c === '"' || c === "'") {
+            quote = c;
+        }
+        else if (c === '>') {
+            return i;
+        }
+    }
+    throw new Error(`xml-ranges: unterminated tag at offset ${from}`);
+}
+/** Skip a construct that ends with a known terminator; returns the offset past it. */
+function skipUntil(xml, from, terminator) {
+    const at = xml.indexOf(terminator, from);
+    if (at < 0)
+        throw new Error(`xml-ranges: unterminated ${terminator.trim()} at offset ${from}`);
+    return at + terminator.length;
+}
+function* rawTags(xml) {
+    let i = 0;
+    while (i < xml.length) {
+        const lt = xml.indexOf('<', i);
+        if (lt < 0)
+            return;
+        // Constructs that are not element tags, and whose bodies may contain `<` or `>`.
+        if (xml.startsWith('<!--', lt)) {
+            i = skipUntil(xml, lt, '-->');
+            continue;
+        }
+        if (xml.startsWith('<![CDATA[', lt)) {
+            i = skipUntil(xml, lt, ']]>');
+            continue;
+        }
+        if (xml.startsWith('<?', lt)) {
+            i = skipUntil(xml, lt, '?>');
+            continue;
+        }
+        if (xml.startsWith('<!', lt)) {
+            i = endOfTag(xml, lt) + 1;
+            continue;
+        }
+        const gt = endOfTag(xml, lt);
+        const body = xml.slice(lt + 1, gt);
+        const closing = body.startsWith('/');
+        const selfClosing = body.endsWith('/');
+        const inner = body.replace(/^\//, '').replace(/\/$/, '');
+        const name = inner.split(/[\s/]/, 1)[0] ?? '';
+        yield {
+            name,
+            start: lt,
+            end: gt + 1,
+            selfClosing,
+            closing,
+            attributes: closing ? {} : parseAttributes(inner.slice(name.length)),
+        };
+        i = gt + 1;
+    }
+}
+/**
+ * Every element in the document, as a tree of source ranges. The returned array holds
+ * the top-level elements — a `.bpmn` has exactly one, `bpmn:definitions`.
+ */
+export function parseXmlRanges(xml) {
+    const roots = [];
+    const stack = [];
+    const finish = (tag, node, end) => {
+        const range = {
+            name: node.tag.name,
+            local: node.tag.name.includes(':') ? node.tag.name.split(':').pop() : node.tag.name,
+            ...(node.tag.attributes.id !== undefined ? { id: node.tag.attributes.id } : {}),
+            start: node.tag.start,
+            end,
+            innerStart: node.tag.end,
+            innerEnd: node.tag.selfClosing ? node.tag.end : tag.start,
+            attributes: node.tag.attributes,
+            children: node.children,
+        };
+        const parent = stack[stack.length - 1];
+        if (parent)
+            parent.children.push(range);
+        else
+            roots.push(range);
+    };
+    for (const tag of rawTags(xml)) {
+        if (tag.closing) {
+            const node = stack.pop();
+            if (!node)
+                throw new Error(`xml-ranges: stray </${tag.name}> at offset ${tag.start}`);
+            finish(tag, node, tag.end);
+            continue;
+        }
+        if (tag.selfClosing) {
+            const node = { tag, children: [] };
+            finish(tag, node, tag.end);
+            continue;
+        }
+        stack.push({ tag, children: [] });
+    }
+    if (stack.length > 0) {
+        throw new Error(`xml-ranges: unclosed <${stack[stack.length - 1].tag.name}>`);
+    }
+    return roots;
+}
+/** Depth-first search for the first element with the given local name. */
+export function findByLocal(nodes, local) {
+    for (const node of nodes) {
+        if (node.local === local)
+            return node;
+        const nested = findByLocal(node.children, local);
+        if (nested)
+            return nested;
+    }
+    return undefined;
+}

package/dist/case/case-expr-check.d.ts

@@ -0,0 +1,35 @@
+/**
+ * case-expr-check — the CASE adapter over the shared `core/expr-check`, run by
+ * `CaseBuilder.build()` before it hands back the model to be serialized.
+ *
+ * A case `=js:` gate reads a declared variable as `=js:vars.<name>` — the `vars.`
+ * namespace, NOT `case.` (a `case.` reference resolves to nothing; the platform's
+ * `uip maestro case validate` only IGNORES it, which is why it looks accepted).
+ * `vars.` is a CLOSED namespace: a reference to a name no variable declares is a
+ * definite mistake, and `validate` says so (`vars.<name> does not exist`). So this
+ * flags every undeclared `vars.<root>`, exactly as the flow check flags `$vars`,
+ * and `build()` is the fast pre-`validate` gate.
+ *
+ * The surfaces that carry a `=js:` gate: every rule's `expression`, a task's
+ * `skipWhen`, and each SLA's `when`. Stage/task STRUCTURAL references
+ * (`rule.stage` / `rule.tasks`) are a different thing and are checked by
+ * `case/check.ts`, not here.
+ */
+import { type ExprDiagnostic } from '../core/expr-check.js';
+import type { BuiltCase } from './case-sdk.js';
+/** A diagnostic plus the part of the case it was found in. */
+export interface CaseLocatedDiagnostic extends ExprDiagnostic {
+    where: string;
+}
+/** Every first-level expression problem in a built case, each stamped with its location. */
+export declare function checkCaseExpressions(built: BuiltCase): CaseLocatedDiagnostic[];
+/**
+ * Thrown by `CaseBuilder.build()` when the first-level expression check finds a
+ * likely-typo'd case-variable reference. Same shape/rationale as the flow's
+ * `FlowBuildError`: `message` lists every problem; `diagnostics` carries them
+ * structured.
+ */
+export declare class CaseBuildError extends Error {
+    readonly diagnostics: CaseLocatedDiagnostic[];
+    constructor(built: BuiltCase, diagnostics: CaseLocatedDiagnostic[]);
+}

package/dist/case/case-expr-check.js

@@ -0,0 +1,85 @@
+/**
+ * case-expr-check — the CASE adapter over the shared `core/expr-check`, run by
+ * `CaseBuilder.build()` before it hands back the model to be serialized.
+ *
+ * A case `=js:` gate reads a declared variable as `=js:vars.<name>` — the `vars.`
+ * namespace, NOT `case.` (a `case.` reference resolves to nothing; the platform's
+ * `uip maestro case validate` only IGNORES it, which is why it looks accepted).
+ * `vars.` is a CLOSED namespace: a reference to a name no variable declares is a
+ * definite mistake, and `validate` says so (`vars.<name> does not exist`). So this
+ * flags every undeclared `vars.<root>`, exactly as the flow check flags `$vars`,
+ * and `build()` is the fast pre-`validate` gate.
+ *
+ * The surfaces that carry a `=js:` gate: every rule's `expression`, a task's
+ * `skipWhen`, and each SLA's `when`. Stage/task STRUCTURAL references
+ * (`rule.stage` / `rule.tasks`) are a different thing and are checked by
+ * `case/check.ts`, not here.
+ */
+import { checkExpression } from '../core/expr-check.js';
+const NOUN = 'case variable';
+const NAMESPACE = 'vars';
+function checkExpr(expr, where, roots, out) {
+    if (!expr)
+        return;
+    for (const d of checkExpression(expr, { roots, noun: NOUN, namespace: NAMESPACE })) {
+        out.push({ ...d, where });
+    }
+}
+/** Every rule's `=js:` gate across an AND/OR rule matrix. */
+function checkRules(rules, where, roots, out) {
+    for (const group of rules ?? [])
+        for (const r of group)
+            checkExpr(r.expression, where, roots, out);
+}
+/** Every first-level expression problem in a built case, each stamped with its location. */
+export function checkCaseExpressions(built) {
+    const roots = new Set(built.vars.map((v) => v.name));
+    // Task output bindings declare readable case variables too (`=vars.<var>`),
+    // via a root `inputOutputs` companion — include them so a gate that reads a
+    // task output is not flagged as an undeclared reference.
+    for (const stage of built.stages)
+        for (const lane of stage.lanes)
+            for (const task of lane)
+                for (const o of task.outputs ?? [])
+                    roots.add(o.var);
+    // Event-trigger payload extractions declare readable case variables too.
+    for (const t of built.triggers)
+        for (const o of t.eventOutputs ?? [])
+            roots.add(o.var);
+    const out = [];
+    built.slaRules.forEach((sla, i) => checkExpr(sla.expression, `case SLA #${i + 1}`, roots, out));
+    built.caseExit.forEach((ce, i) => checkRules(ce.rules, `case completion #${i + 1}`, roots, out));
+    for (const stage of built.stages) {
+        const at = `stage "${stage.label}"`;
+        for (const ec of stage.entry)
+            checkRules(ec.rules, `${at} entry`, roots, out);
+        for (const xc of stage.exit)
+            checkRules(xc.rules, `${at} exit`, roots, out);
+        stage.slaRules.forEach((sla, i) => checkExpr(sla.expression, `${at} SLA #${i + 1}`, roots, out));
+        for (const lane of stage.lanes) {
+            for (const task of lane) {
+                const tat = `task "${task.name}" in ${at}`;
+                checkExpr(task.skip, `${tat} skipWhen`, roots, out);
+                for (const ec of task.entry)
+                    checkRules(ec.rules, `${tat} entry`, roots, out);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Thrown by `CaseBuilder.build()` when the first-level expression check finds a
+ * likely-typo'd case-variable reference. Same shape/rationale as the flow's
+ * `FlowBuildError`: `message` lists every problem; `diagnostics` carries them
+ * structured.
+ */
+export class CaseBuildError extends Error {
+    diagnostics;
+    constructor(built, diagnostics) {
+        const label = built.name || built.id || 'case';
+        const lines = diagnostics.map((d) => `  ✗ [${d.code}] in ${d.where}: ${d.message}${d.suggestion ? ` (did you mean "${d.suggestion}"?)` : ''}`);
+        super(`Cannot build case "${label}" — ${diagnostics.length} expression problem(s):\n${lines.join('\n')}`);
+        this.name = 'CaseBuildError';
+        this.diagnostics = diagnostics;
+    }
+}