@uipath/maestro-builder-sdk 5.2.0

package/dist/core/connectors.d.ts

@@ -0,0 +1,184 @@
+/**
+ * core/connectors — the typed connector-descriptor surface.
+ *
+ * A *descriptor* is a tiny, generated value that identifies one connector
+ * operation (`nodeType` + `version`) and carries its input/output **types** as
+ * phantom brands (zero runtime cost). The generated per-connector modules
+ * (materialized from the connector library — see `lib/`) export one descriptor
+ * per op, so authoring a connector step is statically checked:
+ *
+ * ```ts
+ * import { connector } from './sdk';
+ * import { CreateIssue } from '@uipath/flow-connectors/uipath-atlassian-jira';
+ * connector(CreateIssue, { fields: { project: { key: 'TS' }, summary: '…' } },
+ *           { connection: 'jira', folder: 'shared' });
+ * ```
+ *
+ * The descriptor is a **typed index over the library**, not a replacement: it
+ * only carries the id + types; `serialize()` still resolves the full node
+ * payload from `library-json` via `Library.resolve()`. Both are generated from
+ * the same library snapshot. Generated inputs expose natural nested objects and
+ * arrays; `buildConnectorInputs` validates them and projects them back to the
+ * registry's flat field ids when emitting Flow JSON.
+ */
+import type { Expr } from './expr.js';
+import type { LookupSpec, LookupToken } from './lookups.js';
+/**
+ * What a generated `Inputs` property accepts: the value, or an expression.
+ *
+ * The generator used to type a string field as `string`, full stop. That was
+ * never what the SDK accepts — `input('x')`, `out('step','f')`, `` tmpl`…` ``
+ * and `` js`…` `` all produce an {@link Expr}, and passing one is the ordinary
+ * way to author a connector step. So `connector(CreateIssue, { summary:
+ * input('summary') })` did not typecheck.
+ *
+ * Nothing caught it because no shipped example uses a descriptor (they all use
+ * the string form, which takes `Record<string, unknown>`), and because `compile`
+ * runs under `--experimental-strip-types` — types are erased, never checked.
+ * The typed surface was decorative.
+ *
+ * Arrays distribute, so BOTH shapes an author reaches for are legal: the whole
+ * collection as one expression (`tags: input('tags')`) and a literal array with
+ * an expression in a slot (`tags: ['a', out('s','b')]`). Without the
+ * distribution the second form forced every element to be a bare literal.
+ *
+ * This does NOT loosen which FIELDS are accepted, which is the property the
+ * closed `Inputs` type exists for. Only which value forms, and to exactly the
+ * set the serializer already renders.
+ */
+export type ConnectorValue<T> = Expr | (T extends readonly (infer E)[] ? Array<E | Expr> : T);
+/**
+ * {@link ConnectorValue} for a field that also accepts an unresolved lookup.
+ *
+ * Deliberately separate. If every property accepted a {@link LookupToken}, a
+ * `lookup(...)` could be attached to a field with no `reference` at all, and
+ * the mistake would survive to `prepare`, which has nothing to resolve it
+ * against. Confining the token to fields that declare a lookup makes that a
+ * compile error at the call site instead.
+ */
+export type ConnectorLookupValue<T> = LookupToken | (T extends readonly (infer E)[] ? Array<E | Expr | LookupToken> : T | Expr);
+/** Runtime metadata a generated descriptor carries. `nodeType` is `uipath.connector.<key>.<action>` (no `@version`). */
+export interface ConnectorMeta {
+    nodeType: string;
+    version?: string;
+    requiresConnection?: boolean;
+    requiresFolderKey?: boolean;
+    /**
+     * Which OBJECT this descriptor addresses, for a **generic** operation whose
+     * nodeType covers many (`…netsuite.get-record` covers 182). Baked in by the
+     * generator so `connector(D, …)` needs no `{ object }`; an explicit
+     * `{ object }` still wins.
+     *
+     * @remarks
+     * Precedence is the call option first, the descriptor's baked constant second.
+     */
+    objectName?: string;
+    /**
+     * The operation's resolvable lookup fields, keyed by field name — generated
+     * from each input's `reference` block. Absent when the operation has none.
+     *
+     * Consumed by {@link lookup}, and readable as plain source: the generator
+     * also writes the same facts as a comment above the descriptor, because the
+     * agents this surface is for run with `grep` and no language server, so a
+     * `.byEmail` discoverable only by hovering is invisible.
+     *
+     * Degenerate lookups are deliberately absent — see `_lookups.py`.
+     */
+    lookups?: Readonly<Record<string, LookupSpec>>;
+}
+/**
+ * A generated, typed connector descriptor: {@link ConnectorMeta} branded with
+ * phantom input/output types. `__inputs`/`__outputs` never materialize at
+ * runtime — they exist only so `connector(descriptor, inputs)` can infer types.
+ */
+export type ConnectorDescriptor<I = Record<string, unknown>, O = Record<string, unknown>> = ConnectorMeta & {
+    readonly __inputs?: I;
+    readonly __outputs?: O;
+};
+/**
+ * Brand a descriptor literal with its input/output types (zero runtime cost).
+ * Used by codegen: `descriptor<CreateIssueInputs, CreateIssueOutputs>()({ … } as const)`.
+ * Curried so the generator names `I`/`O` explicitly while TS still narrows the
+ * literal (`nodeType`, flags) from `as const`.
+ *
+ * @returns A branding function: call it with the descriptor literal (`as const`) to get
+ * that literal typed as a {@link ConnectorDescriptor}.
+ */
+export declare function descriptor<I = Record<string, unknown>, O = Record<string, unknown>>(): <const D extends ConnectorMeta>(d: D) => D & {
+    readonly __inputs?: I;
+    readonly __outputs?: O;
+};
+/**
+ * Split a connector `nodeType` into its `{ key, action }`.
+ *
+ * @internal Public for compatibility; not an authoring factory.
+ */
+export declare function splitConnectorNodeType(nodeType: string): {
+    key: string;
+    action: string;
+};
+/** Runtime metadata a generated trigger descriptor carries. */
+export interface TriggerMeta {
+    /** Connector key, e.g. `'uipath-atlassian-jira'`. */
+    connector: string;
+    /** Curated event id, e.g. `'issue-created'` (the last segment of the nodeType). */
+    event: string;
+    version?: string;
+    /** Human label from the registry catalog, e.g. `'Issue Created'` (docs only). */
+    displayName?: string;
+}
+/**
+ * A generated, typed connector-trigger descriptor: {@link TriggerMeta} branded
+ * with phantom `where`/output types. Offline both are loose; a connection-scoped
+ * generator can narrow them. `__where`/`__output` never materialize at runtime.
+ */
+export type TriggerDescriptor<W = Record<string, string>, O = Record<string, unknown>> = TriggerMeta & {
+    readonly __where?: W;
+    readonly __output?: O;
+};
+/**
+ * Brand a trigger descriptor literal with its where/output types. Used by codegen:
+ * `triggerDescriptor<IssueCreatedWhere>()({ … } as const)`. Curried so the
+ * generator names `W`/`O` explicitly while TS narrows the literal.
+ *
+ * @remarks
+ * It also stamps a non-enumerable runtime marker — see `isTriggerDescriptor`
+ * for why a type-level-only brand was not enough.
+ *
+ * @returns A branding function: call it with the descriptor literal (`as const`) to get
+ * that literal typed as a {@link TriggerDescriptor}.
+ */
+export declare function triggerDescriptor<W = Record<string, string>, O = Record<string, unknown>>(): <const D extends TriggerMeta>(d: D) => D & TriggerDescriptor<W, O>;
+/**
+ * Distinguish the typed `onEvent(descriptor, opts)` form from the stringly
+ * `onEvent(subscription)` form.
+ *
+ * ## This used to test for the ABSENCE of `where`, and that was load-bearing on an
+ * assumption that turned out to be false
+ *
+ * The old rule was *"both carry `connector` + `event`; only an `EventSubscription`
+ * carries `where`, so its ABSENCE marks a bare descriptor"*. It held only while
+ * every connector event HAD event parameters. The HTTP Webhook connector has none
+ * — it is scoped by the connection, so `{ connector: 'uipath-http-webhook',
+ * event: 'http-webhook', connection: 'bWebhook', folder: 'bFolder' }` is a
+ * complete, correct subscription with no `where` at all — and the old test read it
+ * as a descriptor. The consequence was not a type error: `subscriptionFrom` then
+ * rebuilt the subscription from the descriptor's three fields and **silently
+ * dropped `connection`, `folder` and `filters`**, emitting a start trigger bound
+ * to no connection. 162 of 164 deployed connector start triggers carry a
+ * `detail.connectionId`; ours carried none, and every rung stayed green because a
+ * local run resolves connectors from the library rather than from the binding.
+ *
+ * So the test is now POSITIVE and belt-and-braces:
+ *
+ *  1. a descriptor is what `triggerDescriptor()` stamped (the only producer — the
+ *     generated `<key>.triggers.ts` modules all go through it);
+ *  2. and nothing carrying a SUBSCRIPTION-ONLY key is ever a descriptor, so an
+ *     unbranded hand-written subscription cannot be misread either.
+ *
+ * Rule of thumb this cost: **never discriminate a union on a field that is allowed
+ * to be absent.**
+ *
+ * @internal Public for compatibility; not an authoring factory.
+ */
+export declare function isTriggerDescriptor(x: unknown): x is TriggerDescriptor;

package/dist/core/connectors.js

@@ -0,0 +1,128 @@
+/**
+ * core/connectors — the typed connector-descriptor surface.
+ *
+ * A *descriptor* is a tiny, generated value that identifies one connector
+ * operation (`nodeType` + `version`) and carries its input/output **types** as
+ * phantom brands (zero runtime cost). The generated per-connector modules
+ * (materialized from the connector library — see `lib/`) export one descriptor
+ * per op, so authoring a connector step is statically checked:
+ *
+ * ```ts
+ * import { connector } from './sdk';
+ * import { CreateIssue } from '@uipath/flow-connectors/uipath-atlassian-jira';
+ * connector(CreateIssue, { fields: { project: { key: 'TS' }, summary: '…' } },
+ *           { connection: 'jira', folder: 'shared' });
+ * ```
+ *
+ * The descriptor is a **typed index over the library**, not a replacement: it
+ * only carries the id + types; `serialize()` still resolves the full node
+ * payload from `library-json` via `Library.resolve()`. Both are generated from
+ * the same library snapshot. Generated inputs expose natural nested objects and
+ * arrays; `buildConnectorInputs` validates them and projects them back to the
+ * registry's flat field ids when emitting Flow JSON.
+ */
+/**
+ * Brand a descriptor literal with its input/output types (zero runtime cost).
+ * Used by codegen: `descriptor<CreateIssueInputs, CreateIssueOutputs>()({ … } as const)`.
+ * Curried so the generator names `I`/`O` explicitly while TS still narrows the
+ * literal (`nodeType`, flags) from `as const`.
+ *
+ * @returns A branding function: call it with the descriptor literal (`as const`) to get
+ * that literal typed as a {@link ConnectorDescriptor}.
+ */
+export function descriptor() {
+    // Returns `D & brand`, NOT `D & ConnectorDescriptor<I, O>`. The two are
+    // equivalent for assignability — `D extends ConnectorMeta` already — but not
+    // for `keyof`: re-intersecting `ConnectorMeta` puts its wide
+    // `lookups?: Record<string, LookupSpec>` beside the literal's narrow one, and
+    // `keyof (A & B)` is the UNION of their keys, so `keyof D['lookups']`
+    // collapsed to `string`. That silently disabled every lookup field-name check
+    // — `lookup(D, 'nonexistent')` type-checked clean and failed at run time.
+    return (d) => d;
+}
+/**
+ * Split a connector `nodeType` into its `{ key, action }`.
+ *
+ * @internal Public for compatibility; not an authoring factory.
+ */
+export function splitConnectorNodeType(nodeType) {
+    const rest = nodeType.replace(/^uipath\.connector\./, '');
+    const dot = rest.lastIndexOf('.');
+    if (dot <= 0)
+        throw new Error(`invalid connector nodeType "${nodeType}" (expected uipath.connector.<key>.<action>).`);
+    return { key: rest.slice(0, dot), action: rest.slice(dot + 1) };
+}
+/**
+ * The runtime marker `triggerDescriptor()` stamps on a descriptor. Non-enumerable,
+ * so it never reaches a `JSON.stringify`, an emitted `.flow`, or a spread — it
+ * exists only so `isTriggerDescriptor` can answer POSITIVELY.
+ */
+const TRIGGER_DESCRIPTOR = Symbol.for('uipath.flow-sdk.triggerDescriptor');
+/** Keys only an `EventSubscription` ever carries. */
+const SUBSCRIPTION_ONLY_KEYS = ['where', 'object', 'filters', 'connection', 'folder'];
+/**
+ * Brand a trigger descriptor literal with its where/output types. Used by codegen:
+ * `triggerDescriptor<IssueCreatedWhere>()({ … } as const)`. Curried so the
+ * generator names `W`/`O` explicitly while TS narrows the literal.
+ *
+ * @remarks
+ * It also stamps a non-enumerable runtime marker — see `isTriggerDescriptor`
+ * for why a type-level-only brand was not enough.
+ *
+ * @returns A branding function: call it with the descriptor literal (`as const`) to get
+ * that literal typed as a {@link TriggerDescriptor}.
+ */
+export function triggerDescriptor() {
+    return (d) => {
+        // A descriptor literal is freshly written at its call site, so defining a
+        // property on it is safe; guard anyway for a frozen or reused object.
+        try {
+            Object.defineProperty(d, TRIGGER_DESCRIPTOR, { value: true, enumerable: false });
+        }
+        catch { /* a frozen literal still works — SUBSCRIPTION_ONLY_KEYS decides */ }
+        return d;
+    };
+}
+/**
+ * Distinguish the typed `onEvent(descriptor, opts)` form from the stringly
+ * `onEvent(subscription)` form.
+ *
+ * ## This used to test for the ABSENCE of `where`, and that was load-bearing on an
+ * assumption that turned out to be false
+ *
+ * The old rule was *"both carry `connector` + `event`; only an `EventSubscription`
+ * carries `where`, so its ABSENCE marks a bare descriptor"*. It held only while
+ * every connector event HAD event parameters. The HTTP Webhook connector has none
+ * — it is scoped by the connection, so `{ connector: 'uipath-http-webhook',
+ * event: 'http-webhook', connection: 'bWebhook', folder: 'bFolder' }` is a
+ * complete, correct subscription with no `where` at all — and the old test read it
+ * as a descriptor. The consequence was not a type error: `subscriptionFrom` then
+ * rebuilt the subscription from the descriptor's three fields and **silently
+ * dropped `connection`, `folder` and `filters`**, emitting a start trigger bound
+ * to no connection. 162 of 164 deployed connector start triggers carry a
+ * `detail.connectionId`; ours carried none, and every rung stayed green because a
+ * local run resolves connectors from the library rather than from the binding.
+ *
+ * So the test is now POSITIVE and belt-and-braces:
+ *
+ *  1. a descriptor is what `triggerDescriptor()` stamped (the only producer — the
+ *     generated `<key>.triggers.ts` modules all go through it);
+ *  2. and nothing carrying a SUBSCRIPTION-ONLY key is ever a descriptor, so an
+ *     unbranded hand-written subscription cannot be misread either.
+ *
+ * Rule of thumb this cost: **never discriminate a union on a field that is allowed
+ * to be absent.**
+ *
+ * @internal Public for compatibility; not an authoring factory.
+ */
+export function isTriggerDescriptor(x) {
+    if (typeof x !== 'object' || x === null)
+        return false;
+    if (typeof x.connector !== 'string')
+        return false;
+    if (typeof x.event !== 'string')
+        return false;
+    if (SUBSCRIPTION_ONLY_KEYS.some((k) => k in x))
+        return false;
+    return x[TRIGGER_DESCRIPTOR] === true;
+}

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

@@ -0,0 +1,93 @@
+/**
+ * core/expr-check — a FORMAT-AGNOSTIC first-level check of the references inside
+ * an expression, shared by Flow, Case, and BPMN.
+ *
+ * This is the piece each SDK's `build()` runs BEFORE it hands back the model to
+ * be serialized: cheap, high-confidence checks that catch a broken expression at
+ * the moment the SDK code runs, rather than three steps later at
+ * `uip maestro flow validate`. Its guiding rule is **conservative**: only flag
+ * what it can be certain of, so it never produces a misleading error. Deeper,
+ * heavier checks (does step X actually output `.foo`, is the comparison
+ * type-sound) belong to the `validate` CLI, which can afford them.
+ *
+ * The first thing it checks: every `$vars.<root>` reference resolves to a name the
+ * runtime will provide — a declared input, variable, or step/task/node. A
+ * reference to nothing is a definite bug (a typo, or a renamed step), and the
+ * runtime's variable bag is pre-declared, so an unknown root reads `null` forever
+ * and every guard built on it silently takes the wrong path.
+ *
+ * The second: the expression PARSES as JavaScript. That sounds like something a
+ * later rung would catch, and nothing did — `validate` checks the artifact's
+ * contract, not the contents of an expression string, so
+ * `$vars.searchIssues.output.issues[*]` reached a live run and faulted there
+ * (`[400008] Failed to evaluate the input collection variable`). `[*]` is
+ * JSONPath; the runtime evaluates JavaScript. Reference resolution alone could
+ * not see it, because the root (`searchIssues`) was perfectly real.
+ *
+ * It is deliberately NOT tied to any one format's model: a caller passes the set
+ * of valid roots (which it alone knows how to compute) and the expression string,
+ * and gets back diagnostics with no location. The caller stamps the location
+ * (which node / task / field) it came from.
+ */
+/** A `$vars.*` reference found in an expression. */
+export interface ExprRef {
+    /** The first segment after `$vars.` — the name the reference is rooted at. */
+    root: string;
+    /** The remaining dotted / indexed segments, e.g. `['output', 'items', '[0]', 'id']`. */
+    path: string[];
+    /** The whole matched reference text, for messages. */
+    raw: string;
+}
+/** A problem found in an expression. Location is stamped by the caller. */
+export interface ExprDiagnostic {
+    level: 'error' | 'warning';
+    code: string;
+    message: string;
+    suggestion?: string;
+}
+/**
+ * What the caller knows and the checker does not: which `$vars` roots are valid.
+ *
+ * `roots` is every name a reference may be rooted at — declared inputs, working
+ * variables, and the names of steps/tasks/nodes whose output is referenceable.
+ * `noun` names them in the message (`'input, variable, or step'` for a flow), so
+ * the same checker reads naturally for a case ('field or task') or a bpmn model.
+ */
+export interface ExprScope {
+    roots: Set<string>;
+    noun?: string;
+    /**
+     * The reference NAMESPACE this check owns — the leading token whose roots are
+     * author-declared and therefore checkable. Flow uses `$vars` (its default); Case
+     * uses `vars` (a case gate reads a declared variable as `=js:vars.<name>`). Every
+     * OTHER namespace the engine provides (`outputs`, `result`, `metadata`,
+     * `orchestrator`, …) is a runtime built-in, so a reference into one is left alone
+     * rather than flagged.
+     */
+    namespace?: string;
+    /**
+     * Parse the expression as JavaScript and report a syntax error.
+     *
+     * OFF by default, because "expression" does not mean the same thing in all
+     * three formats and only the caller knows. A Flow `Expr` carries the bare
+     * JavaScript the runtime evaluates, so it parses. A BPMN condition is
+     * `=vars.total` and a Case gate is `=js:vars.total` — both carry a leading
+     * `=` sigil and are not JavaScript as given, so parsing them would report a
+     * syntax error on every well-formed expression in those formats.
+     */
+    syntax?: 'javascript';
+}
+/**
+ * Every `<namespace>.*` reference in an expression, in source order, with literals
+ * masked so a reference-shaped substring inside a string is not counted.
+ * `namespace` defaults to `$vars` (Flow); Case passes `case`.
+ */
+export declare function extractRefs(expr: string, namespace?: string): ExprRef[];
+/**
+ * First-level check of ONE expression: every reference's root must resolve.
+ *
+ * Returns a diagnostic per unresolved root (deduped, so `$vars.x + $vars.x` is one
+ * message). An empty result means "nothing this check is sure is wrong" — never
+ * "fully valid"; the `validate` CLI is what proves the rest.
+ */
+export declare function checkExpression(expr: string, scope: ExprScope): ExprDiagnostic[];

package/dist/core/expr-check.js

@@ -0,0 +1,186 @@
+/**
+ * core/expr-check — a FORMAT-AGNOSTIC first-level check of the references inside
+ * an expression, shared by Flow, Case, and BPMN.
+ *
+ * This is the piece each SDK's `build()` runs BEFORE it hands back the model to
+ * be serialized: cheap, high-confidence checks that catch a broken expression at
+ * the moment the SDK code runs, rather than three steps later at
+ * `uip maestro flow validate`. Its guiding rule is **conservative**: only flag
+ * what it can be certain of, so it never produces a misleading error. Deeper,
+ * heavier checks (does step X actually output `.foo`, is the comparison
+ * type-sound) belong to the `validate` CLI, which can afford them.
+ *
+ * The first thing it checks: every `$vars.<root>` reference resolves to a name the
+ * runtime will provide — a declared input, variable, or step/task/node. A
+ * reference to nothing is a definite bug (a typo, or a renamed step), and the
+ * runtime's variable bag is pre-declared, so an unknown root reads `null` forever
+ * and every guard built on it silently takes the wrong path.
+ *
+ * The second: the expression PARSES as JavaScript. That sounds like something a
+ * later rung would catch, and nothing did — `validate` checks the artifact's
+ * contract, not the contents of an expression string, so
+ * `$vars.searchIssues.output.issues[*]` reached a live run and faulted there
+ * (`[400008] Failed to evaluate the input collection variable`). `[*]` is
+ * JSONPath; the runtime evaluates JavaScript. Reference resolution alone could
+ * not see it, because the root (`searchIssues`) was perfectly real.
+ *
+ * It is deliberately NOT tied to any one format's model: a caller passes the set
+ * of valid roots (which it alone knows how to compute) and the expression string,
+ * and gets back diagnostics with no location. The caller stamps the location
+ * (which node / task / field) it came from.
+ */
+import * as ts from 'typescript';
+/**
+ * A JSONPath wildcard/filter step — the spelling that reaches for JavaScript and
+ * misses. Used only to add a suggestion; the parse decides.
+ */
+const JSONPATH_WILDCARD = /\[\s*(?:\*|\?|'[^']*'|"[^"]*")\s*\]|\.\.[A-Za-z_$]/;
+/**
+ * The first syntax error in `expr` read as a JavaScript EXPRESSION, or
+ * `undefined` when it parses.
+ *
+ * Wrapped in parentheses so it is parsed in expression position: a bare
+ * `{ a: 1 }` is a block with a label otherwise, and object literals are ordinary
+ * here. The newline before the closing paren keeps a trailing line comment from
+ * swallowing it.
+ *
+ * `ts.createSourceFile` is a parse, not an evaluation — nothing in `expr` runs.
+ * TypeScript is already a runtime dependency of this package (see
+ * `core/script-return.ts`, which infers a script's return type the same way), so
+ * this adds no dependency.
+ */
+function syntaxError(expr) {
+    const source = ts.createSourceFile('expression.ts', `(${expr}\n)`, ts.ScriptTarget.ES2020, 
+    /* setParentNodes */ false);
+    // `parseDiagnostics` is where the scanner records syntax problems. It is not on
+    // the public `SourceFile` type, hence the cast; there is no public API that
+    // parses a fragment and hands back its syntax diagnostics without also running
+    // a full program's type-check.
+    const problems = source.parseDiagnostics;
+    if (!problems || problems.length === 0)
+        return undefined;
+    return ts.flattenDiagnosticMessageText(problems[0].messageText, ' ');
+}
+const DEFAULT_NAMESPACE = '$vars';
+/**
+ * Blank out the CONTENTS of single- and double-quoted string literals, preserving
+ * length and the quotes, so a `$vars.`-looking substring INSIDE a literal is not
+ * mistaken for a reference.
+ *
+ * `js`${input('a')} === ${'$vars.notAName'}`` renders to
+ * `$vars.a === "$vars.notAName"`; only the first is a reference. Template literals
+ * (backticks) are LEFT INTACT on purpose — the SDK's `tmpl` emits real references
+ * inside their `${…}`, and a literal `$vars.` in the surrounding URL/message text
+ * is not a thing the serializer produces. Escapes are honored so a quote inside a
+ * literal does not end it early.
+ */
+function maskStringLiterals(expr) {
+    return expr.replace(/'(?:\\.|[^'\\])*'|"(?:\\.|[^"\\])*"/g, (m) => m[0] + ' '.repeat(m.length - 2) + m[m.length - 1]);
+}
+const SEGMENT = /\??\.([A-Za-z_$][\w$]*)|\[(\d+)\]/g;
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * A `<namespace>.<root><path>` reference matcher. The root is a JS identifier;
+ * the path is any run of `.ident`, `?.ident`, or `[<digits>]` selectors — the
+ * same shape the platform's variable-path grammar admits. The leading
+ * `(?<![\w.$])` keeps `case` from matching inside `mycase` or as the `.case`
+ * member of something else — only a namespace at a token boundary counts (the
+ * engine's own `DetectIdentifiers` uses the same guard).
+ */
+function refRegex(namespace) {
+    return new RegExp(`(?<![\\w.$])${escapeRegExp(namespace)}\\.([A-Za-z_$][\\w$]*)((?:\\??\\.[A-Za-z_$][\\w$]*|\\[\\d+\\])*)`, 'g');
+}
+/**
+ * Every `<namespace>.*` reference in an expression, in source order, with literals
+ * masked so a reference-shaped substring inside a string is not counted.
+ * `namespace` defaults to `$vars` (Flow); Case passes `case`.
+ */
+export function extractRefs(expr, namespace = DEFAULT_NAMESPACE) {
+    const masked = maskStringLiterals(expr);
+    const refs = [];
+    for (const m of masked.matchAll(refRegex(namespace))) {
+        const [raw, root, tail] = m;
+        const path = tail
+            ? Array.from(tail.matchAll(SEGMENT), (s) => (s[2] !== undefined ? `[${s[2]}]` : s[1]))
+            : [];
+        refs.push({ root, path, raw });
+    }
+    return refs;
+}
+/** True when `a` and `b` are equal or one edit (insert/delete/substitute) apart. */
+function editDistanceLE1(a, b) {
+    if (a === b)
+        return true;
+    const la = a.length;
+    const lb = b.length;
+    if (Math.abs(la - lb) > 1)
+        return false;
+    let i = 0;
+    while (i < la && i < lb && a[i] === b[i])
+        i++;
+    if (la === lb)
+        return a.slice(i + 1) === b.slice(i + 1); // substitution
+    return la > lb ? a.slice(i + 1) === b.slice(i) : a.slice(i) === b.slice(i + 1); // insert/delete
+}
+/**
+ * The declared root `name` is most likely a typo of, if any: a case-only mismatch
+ * (strongest signal, any length) or — for names long enough that an edit is
+ * unlikely to be a coincidence (≥ 4 chars) — one edit away.
+ */
+function nearMiss(name, roots) {
+    const lower = name.toLowerCase();
+    let oneEdit;
+    for (const r of roots) {
+        const rl = r.toLowerCase();
+        if (rl === lower)
+            return r; // case-only difference — the strongest typo signal
+        if (oneEdit === undefined && Math.max(rl.length, lower.length) >= 4 && editDistanceLE1(lower, rl)) {
+            oneEdit = r;
+        }
+    }
+    return oneEdit;
+}
+/**
+ * First-level check of ONE expression: every reference's root must resolve.
+ *
+ * Returns a diagnostic per unresolved root (deduped, so `$vars.x + $vars.x` is one
+ * message). An empty result means "nothing this check is sure is wrong" — never
+ * "fully valid"; the `validate` CLI is what proves the rest.
+ */
+export function checkExpression(expr, scope) {
+    const namespace = scope.namespace ?? DEFAULT_NAMESPACE;
+    const noun = scope.noun ?? 'input, variable, or step';
+    const diags = [];
+    const seen = new Set();
+    // Syntax first: an expression that does not parse cannot have meaningful
+    // references, and reporting both would just be noise on one root cause.
+    const syntax = scope.syntax === 'javascript' ? syntaxError(expr) : undefined;
+    if (syntax) {
+        return [{
+                level: 'error',
+                code: 'EXPR_SYNTAX',
+                message: `Expression is not valid JavaScript: ${syntax}`,
+                ...(JSONPATH_WILDCARD.test(expr)
+                    ? {
+                        suggestion: 'This looks like JSONPath. The runtime evaluates JavaScript, so index or map '
+                            + 'explicitly — `…issues` for the whole array, `…issues.map(i => i.key)` for one field.',
+                    }
+                    : {}),
+            }];
+    }
+    for (const ref of extractRefs(expr, namespace)) {
+        if (scope.roots.has(ref.root) || seen.has(ref.root))
+            continue;
+        seen.add(ref.root);
+        const near = nearMiss(ref.root, scope.roots);
+        diags.push({
+            level: 'error',
+            code: 'EXPR_UNDECLARED_REF',
+            message: `Expression references \`${namespace}.${ref.root}\`, but no ${noun} named "${ref.root}" is declared.`,
+            ...(near ? { suggestion: near } : {}),
+        });
+    }
+    return diags;
+}