@mondaydotcomorg/z2h-cli 0.30.0 → 0.31.0

package/dist/esm/backend/parser/bindings.mjs

@@ -0,0 +1,81 @@
+import { fullAncestor } from 'acorn-walk';
+import { patternNames, enclosingScope, patternBindings } from './utils.mjs';
+
+function functionBodyScope(node) {
+    if ((node.type === 'FunctionDeclaration' ||
+        node.type === 'FunctionExpression' ||
+        node.type === 'ArrowFunctionExpression') &&
+        node.body.type === 'BlockStatement') {
+        return node.body;
+    }
+    return node;
+}
+function collectBindings(program) {
+    const declarations = new Map();
+    const unpinnable = new Set();
+    const markUnpinnable = (pattern) => patternNames(pattern).forEach(n => unpinnable.add(n));
+    fullAncestor(program, (node, _state, ancestors) => {
+        switch (node.type) {
+            case 'VariableDeclaration': {
+                const scope = enclosingScope(ancestors);
+                for (const declarator of node.declarations) {
+                    for (const { name, path } of patternBindings(declarator.id, [])) {
+                        const list = declarations.get(name) ?? [];
+                        list.push({ kind: node.kind, init: declarator.init, path, scope });
+                        declarations.set(name, list);
+                    }
+                }
+                break;
+            }
+            case 'AssignmentExpression':
+                markUnpinnable(node.left);
+                break;
+            case 'UpdateExpression':
+                if (node.argument.type === 'Identifier') {
+                    unpinnable.add(node.argument.name);
+                }
+                break;
+            case 'ForInStatement':
+            case 'ForOfStatement':
+                if (node.left.type !== 'VariableDeclaration') {
+                    markUnpinnable(node.left);
+                }
+                break;
+            case 'FunctionDeclaration':
+            case 'FunctionExpression':
+            case 'ArrowFunctionExpression': {
+                const scope = functionBodyScope(node);
+                for (const param of node.params) {
+                    for (const name of patternNames(param)) {
+                        const list = declarations.get(name) ?? [];
+                        list.push({ kind: 'param', init: undefined, path: undefined, scope });
+                        declarations.set(name, list);
+                    }
+                }
+                break;
+            }
+            case 'CatchClause':
+                if (node.param) {
+                    const scope = node.body;
+                    for (const name of patternNames(node.param)) {
+                        const list = declarations.get(name) ?? [];
+                        list.push({ kind: 'param', init: undefined, path: undefined, scope });
+                        declarations.set(name, list);
+                    }
+                }
+                break;
+        }
+    });
+    return { declarations, unpinnable };
+}
+function declarationAt(bindings, name, position) {
+    const best = (bindings.declarations.get(name) ?? [])
+        .filter(d => d.scope.start <= position && position < d.scope.end)
+        .sort((a, b) => b.scope.start - a.scope.start)[0];
+    if (!best || best.kind === 'param' || bindings.unpinnable.has(name)) {
+        return undefined;
+    }
+    return best;
+}
+
+export { collectBindings, declarationAt };

package/dist/esm/backend/parser/handler-declaration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler-declaration.d.ts","sourceRoot":"","sources":["../../../../src/backend/parser/handler-declaration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,UAAU,EACV,mBAAmB,EAEnB,iBAAiB,EAEjB,SAAS,EACV,MAAM,OAAO,CAAC;AAMf,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAC,QAAQ,CAAC,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,CAAA;CAAE,CAAC;AAE9D,8DAA8D;AAC9D,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,SAAS,CAAC,SAAS,GAAG,iBAAiB,CAAC,EAAE,GAC/C,kBAAkB,GAAG,SAAS,CAahC;AAED,yGAAyG;AACzG,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,GAAG,iBAAiB,GAAG,OAAO,CAe3E;AAsCD,mGAAmG;AACnG,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,kBAAkB,GAAG,MAAM,GAAG,SAAS,CAG3F;AAED,gGAAgG;AAChG,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAK/C,CAAC"}

package/dist/esm/backend/parser/member-path.d.ts

@@ -0,0 +1,3 @@
+import type { Bindings, PathResolver } from './types';
+export declare function createPathResolver(bindings: Bindings, contextParam?: string): PathResolver;
+//# sourceMappingURL=member-path.d.ts.map

package/dist/esm/backend/parser/member-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"member-path.d.ts","sourceRoot":"","sources":["../../../../src/backend/parser/member-path.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEtD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,YAAY,CAyB1F"}

package/dist/esm/backend/parser/member-path.mjs

@@ -0,0 +1,29 @@
+import { memberChain } from './utils.mjs';
+import { declarationAt } from './bindings.mjs';
+
+function createPathResolver(bindings, contextParam) {
+    function resolveChain(node, resolving) {
+        const chain = memberChain(node);
+        if (!chain) {
+            return undefined;
+        }
+        return [resolveRoot(chain.root, node.start, resolving), ...chain.parts].join('.');
+    }
+    function resolveRoot(name, position, resolving) {
+        if (contextParam !== undefined && name === contextParam) {
+            return 'ctx';
+        }
+        if (resolving.has(name)) {
+            return name;
+        }
+        const decl = declarationAt(bindings, name, position);
+        if (!decl || decl.kind !== 'const' || !decl.init || !decl.path) {
+            return name;
+        }
+        const base = resolveChain(decl.init, new Set(resolving).add(name));
+        return base ? [base, ...decl.path].join('.') : name;
+    }
+    return { pathOf: node => resolveChain(node, new Set()) };
+}
+
+export { createPathResolver };

package/dist/esm/backend/parser/messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../../../src/backend/parser/messages.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,QAAQ;uBACA,MAAM;yBACJ,MAAM;0BACL,MAAM;iCAEC,MAAM;0BAEb,MAAM;6BAEH,MAAM,UAAU,MAAM;wBAE3B,MAAM,QAAQ,MAAM,UAAU,MAAM,UAAU,MAAM;CAEzE,CAAC"}

package/dist/esm/backend/parser/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../../../src/backend/parser/parse.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8D,KAAK,OAAO,EAAkB,MAAM,OAAO,CAAC;AAkDjH;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAuBhE"}

package/dist/esm/backend/{parse.mjs → parser/parse.mjs}

@@ -1,6 +1,6 @@
 import { parse } from 'acorn';
 import { z } from 'zod';
-import { trackEvent } from '../util/tracker.mjs';
+import { trackEvent } from '../../util/tracker.mjs';
 import { exportsHandler } from './handler-declaration.mjs';
 import { messages } from './messages.mjs';
 

package/dist/esm/backend/parser/static-value.d.ts

@@ -0,0 +1,6 @@
+import type { AnyNode } from 'acorn';
+import type { Bindings, JsonValue, Resolved } from './types';
+/** Source text for a node that failed to resolve — the const declaration's init when the node names one, else the node itself. */
+export declare function bestSourceText(node: AnyNode, source: string, bindings: Bindings): string;
+export declare function staticValue(node: AnyNode, bindings: Bindings, source: string, resolving: ReadonlySet<string>): Resolved<JsonValue> | undefined;
+//# sourceMappingURL=static-value.d.ts.map

package/dist/esm/backend/parser/static-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"static-value.d.ts","sourceRoot":"","sources":["../../../../src/backend/parser/static-value.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AACrC,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAgG7D,kIAAkI;AAClI,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAQxF;AAED,wBAAgB,WAAW,CACzB,IAAI,EAAE,OAAO,EACb,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,WAAW,CAAC,MAAM,CAAC,GAC7B,QAAQ,CAAC,SAAS,CAAC,GAAG,SAAS,CA6BjC"}

package/dist/esm/backend/parser/static-value.mjs

@@ -0,0 +1,114 @@
+import { sourceTextOf, displayText, resolveOrSourceText, propertyKey } from './utils.mjs';
+import { declarationAt } from './bindings.mjs';
+
+function resolveLiteral(node) {
+    return typeof node.value === 'string' ||
+        typeof node.value === 'number' ||
+        typeof node.value === 'boolean' ||
+        node.value === null
+        ? { value: node.value }
+        : undefined;
+}
+/** Template holes only interpolate scalars; a resolved object/array (e.g. `$or`) is shown unresolved instead of glued inline. */
+function resolveTemplate(node, source, inner) {
+    const text = node.quasis
+        .map((quasi, i) => {
+        const literalText = quasi.value.cooked ?? quasi.value.raw;
+        const hole = node.expressions[i];
+        if (!hole) {
+            return literalText;
+        }
+        const resolved = inner(hole);
+        const scalar = resolved !== undefined &&
+            (typeof resolved.value === 'string' ||
+                typeof resolved.value === 'number' ||
+                typeof resolved.value === 'boolean' ||
+                resolved.value === null);
+        return literalText + (scalar ? displayText(resolved.value) : `\${${sourceTextOf(hole, source)}}`);
+    })
+        .join('');
+    return { value: text };
+}
+/**
+ * Each element/property resolves independently, falling back to source text. A spread is kept
+ * visible under a `...`-prefixed key/value pair rather than silently dropped.
+ */
+function resolveContainer(node, source, bindings, inner) {
+    const fallbackText = (n) => bestSourceText(n, source, bindings);
+    if (node.type === 'ArrayExpression') {
+        return {
+            value: node.elements.map(element => (element ? resolveOrSourceText(element, source, inner, fallbackText) : null)),
+        };
+    }
+    const result = {};
+    for (const prop of node.properties) {
+        if (prop.type === 'SpreadElement') {
+            const spreadText = sourceTextOf(prop.argument, source);
+            result[`...${spreadText}`] = spreadText;
+            continue;
+        }
+        if (prop.type !== 'Property') {
+            continue;
+        }
+        const key = prop.computed
+            ? sourceTextOf(prop.key, source)
+            : propertyKey(prop.key, false) ?? sourceTextOf(prop.key, source);
+        result[key] = resolveOrSourceText(prop.value, source, inner, fallbackText);
+    }
+    return { value: result };
+}
+function joinBranches(left, right) {
+    return left !== undefined && right !== undefined ? { value: { $or: [left.value, right.value] } } : undefined;
+}
+function resolveIdentifier(node, bindings, source, resolving) {
+    if (resolving.has(node.name)) {
+        return undefined;
+    }
+    const decl = declarationAt(bindings, node.name, node.start);
+    if (!decl || decl.kind !== 'const' || !decl.init || decl.path?.length !== 0) {
+        return undefined;
+    }
+    return staticValue(decl.init, bindings, source, new Set(resolving).add(node.name));
+}
+/** Source text for a node that failed to resolve — the const declaration's init when the node names one, else the node itself. */
+function bestSourceText(node, source, bindings) {
+    if (node.type === 'Identifier') {
+        const decl = declarationAt(bindings, node.name, node.start);
+        if (decl && decl.kind === 'const' && decl.init && decl.path?.length === 0) {
+            return sourceTextOf(decl.init, source);
+        }
+    }
+    return sourceTextOf(node, source);
+}
+function staticValue(node, bindings, source, resolving) {
+    const inner = child => staticValue(child, bindings, source, resolving);
+    switch (node.type) {
+        case 'Literal':
+            return resolveLiteral(node);
+        case 'TemplateLiteral':
+            return resolveTemplate(node, source, inner);
+        case 'ArrayExpression':
+        case 'ObjectExpression':
+            return resolveContainer(node, source, bindings, inner);
+        case 'BinaryExpression': {
+            if (node.operator !== '+') {
+                return undefined;
+            }
+            const left = inner(node.left);
+            const right = inner(node.right);
+            return typeof left?.value === 'string' && typeof right?.value === 'string'
+                ? { value: left.value + right.value }
+                : undefined;
+        }
+        case 'ConditionalExpression':
+            return joinBranches(inner(node.consequent), inner(node.alternate));
+        case 'LogicalExpression':
+            return joinBranches(inner(node.left), inner(node.right));
+        case 'Identifier':
+            return resolveIdentifier(node, bindings, source, resolving);
+        default:
+            return undefined;
+    }
+}
+
+export { bestSourceText, staticValue };

package/dist/esm/backend/parser/types.d.ts

@@ -0,0 +1,53 @@
+import type { AnyNode, Expression, Node, VariableDeclaration } from 'acorn';
+/** `"<domain>.<method>"` → parameter names by position, as documented for handler authors. */
+export type ApiSignatures = Record<string, readonly string[]>;
+export interface Declaration {
+    kind: VariableDeclaration['kind'] | 'param';
+    init: Expression | null | undefined;
+    /**
+     * Property path from `init` to this binding: `[]` for `const x = init`,
+     * `['a', 'b']` for `const { a: { b: x } } = init`, `undefined` when the value
+     * is not a plain property read (array/rest/default patterns).
+     */
+    path: string[] | undefined;
+    scope: Node;
+}
+export interface Bindings {
+    declarations: Map<string, Declaration[]>;
+    /** Names reassigned or updated after declaration — never followed as a stable alias. */
+    unpinnable: Set<string>;
+}
+export interface PatternBinding {
+    name: string;
+    path: string[] | undefined;
+}
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** Wraps a resolved value so "resolved to null" is distinguishable from "unresolved" (`undefined`). */
+export type Resolved<T> = {
+    readonly value: T;
+};
+export interface MemberChain {
+    root: string;
+    parts: string[];
+}
+export interface PathResolver {
+    /**
+     * Dotted path of a member chain, following `const` aliases back to their
+     * source: with `const sf = ctx.api.v1.snowflake`, `sf.query` resolves to
+     * `ctx.api.v1.snowflake.query`. Destructuring counts too
+     * (`const { snowflake: sf } = ctx.api.v1`). `undefined` if any link is dynamic.
+     *
+     * Only single, never-reassigned, never-shadowed `const` bindings are followed —
+     * anything else is left as written. The handler's first parameter is treated as
+     * `ctx` even when renamed (`handler(context)` → `context.api.v1.db` resolves as
+     * `ctx.api.v1.db`).
+     */
+    pathOf(node: AnyNode): string | undefined;
+}
+/** Undocumented arguments or methods fall back to `arg<index>` keys. */
+export type ApiCall = Record<string, JsonValue>;
+/** `domain -> method -> calls`, later written into `usage.json` by deploy. */
+export type ApiUsage = Record<string, Record<string, ApiCall[]>>;
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/backend/parser/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/backend/parser/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,OAAO,CAAC;AAE5E,8FAA8F;AAC9F,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;AAI9D,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,mBAAmB,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC;IAC5C,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,CAAC;IACpC;;;;OAIG;IACH,IAAI,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAC3B,KAAK,EAAE,IAAI,CAAC;CACb;AAED,MAAM,WAAW,QAAQ;IACvB,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;IACzC,wFAAwF;IACxF,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CAC5B;AAID,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEtG,uGAAuG;AACvG,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;IAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAAC;AAIhD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B;;;;;;;;;;OAUG;IACH,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;CAC3C;AAID,wEAAwE;AACxE,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAEhD,8EAA8E;AAC9E,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC"}

package/dist/esm/backend/parser/types.mjs

@@ -0,0 +1 @@
+

package/dist/esm/backend/parser/utils.d.ts

@@ -0,0 +1,19 @@
+import type { AnyNode, Node, Pattern } from 'acorn';
+import type { JsonValue, MemberChain, PatternBinding, Resolved } from './types';
+export declare const sourceTextOf: (node: AnyNode, source: string) => string;
+export declare function displayText(value: JsonValue): string;
+export declare function resolveOrSourceText(node: AnyNode, source: string, resolve: (node: AnyNode) => Resolved<JsonValue> | undefined, fallbackText?: (node: AnyNode) => string): JsonValue;
+/** Static property key of `obj.key` / `obj['key']` / `{ key: … }`; `undefined` when computed from a non-literal. */
+export declare function propertyKey(key: AnyNode, computed: boolean): string | undefined;
+/** `a.b.c` / `a['b'].c` → root `a`, parts `[b, c]`; `undefined` if any link is dynamic or the root is not an identifier. */
+export declare function memberChain(node: AnyNode): MemberChain | undefined;
+/**
+ * Every identifier a binding pattern introduces, with its property path from the
+ * pattern's value. `path` is deliberately not defaulted: callers pass `[]` for
+ * the root and `undefined` once the pattern stops being a plain property read.
+ */
+export declare function patternBindings(pattern: Pattern, path: string[] | undefined): PatternBinding[];
+export declare const patternNames: (pattern: Pattern) => string[];
+/** Nearest scope enclosing the last node of `ancestors` (which `fullAncestor` includes in the list). */
+export declare function enclosingScope(ancestors: AnyNode[]): Node;
+//# sourceMappingURL=utils.d.ts.map

package/dist/esm/backend/parser/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../../src/backend/parser/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAIhF,eAAO,MAAM,YAAY,GAAI,MAAM,OAAO,EAAE,QAAQ,MAAM,KAAG,MAA4C,CAAC;AAE1G,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAEpD;AAED,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,QAAQ,CAAC,SAAS,CAAC,GAAG,SAAS,EAC3D,YAAY,GAAE,CAAC,IAAI,EAAE,OAAO,KAAK,MAAqC,GACrE,SAAS,CAGX;AAID,oHAAoH;AACpH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAQ/E;AAED,4HAA4H;AAC5H,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAelE;AAID;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,SAAS,GAAG,cAAc,EAAE,CAsB9F;AAED,eAAO,MAAM,YAAY,GAAI,SAAS,OAAO,KAAG,MAAM,EAAmD,CAAC;AAc1G,wGAAwG;AACxG,wBAAgB,cAAc,CAAC,SAAS,EAAE,OAAO,EAAE,GAAG,IAAI,CAOzD"}

package/dist/esm/backend/parser/utils.mjs

@@ -0,0 +1,88 @@
+// ─────────── Source text ───────────
+const sourceTextOf = (node, source) => source.slice(node.start, node.end);
+function displayText(value) {
+    return typeof value === 'string' ? value : JSON.stringify(value);
+}
+function resolveOrSourceText(node, source, resolve, fallbackText = n => sourceTextOf(n, source)) {
+    const resolved = resolve(node);
+    return resolved !== undefined ? resolved.value : fallbackText(node);
+}
+// ─────────── Keys and member chains ───────────
+/** Static property key of `obj.key` / `obj['key']` / `{ key: … }`; `undefined` when computed from a non-literal. */
+function propertyKey(key, computed) {
+    if (key.type === 'Literal' && typeof key.value === 'string') {
+        return key.value;
+    }
+    if (!computed && key.type === 'Identifier') {
+        return key.name;
+    }
+    return undefined;
+}
+/** `a.b.c` / `a['b'].c` → root `a`, parts `[b, c]`; `undefined` if any link is dynamic or the root is not an identifier. */
+function memberChain(node) {
+    if (node.type === 'ChainExpression') {
+        return memberChain(node.expression);
+    }
+    const parts = [];
+    let cur = node;
+    while (cur.type === 'MemberExpression') {
+        const key = propertyKey(cur.property, cur.computed);
+        if (key === undefined) {
+            return undefined;
+        }
+        parts.unshift(key);
+        cur = cur.object;
+    }
+    return cur.type === 'Identifier' ? { root: cur.name, parts } : undefined;
+}
+// ─────────── Binding patterns ───────────
+/**
+ * Every identifier a binding pattern introduces, with its property path from the
+ * pattern's value. `path` is deliberately not defaulted: callers pass `[]` for
+ * the root and `undefined` once the pattern stops being a plain property read.
+ */
+function patternBindings(pattern, path) {
+    switch (pattern.type) {
+        case 'Identifier':
+            return [{ name: pattern.name, path }];
+        case 'ObjectPattern':
+            return pattern.properties.flatMap(p => {
+                if (p.type === 'RestElement') {
+                    return patternBindings(p.argument, undefined);
+                }
+                const key = propertyKey(p.key, p.computed);
+                return patternBindings(p.value, path && key !== undefined ? [...path, key] : undefined);
+            });
+        case 'ArrayPattern':
+            return pattern.elements.flatMap(e => (e ? patternBindings(e, undefined) : []));
+        case 'AssignmentPattern':
+            return patternBindings(pattern.left, undefined);
+        case 'RestElement':
+            return patternBindings(pattern.argument, undefined);
+        default:
+            // MemberExpression targets (`obj.x = …`) bind no names.
+            return [];
+    }
+}
+const patternNames = (pattern) => patternBindings(pattern, []).map(b => b.name);
+// ─────────── Scopes ───────────
+const SCOPE_TYPES = new Set([
+    'Program',
+    'BlockStatement',
+    'StaticBlock',
+    'SwitchStatement',
+    'ForStatement',
+    'ForInStatement',
+    'ForOfStatement',
+]);
+/** Nearest scope enclosing the last node of `ancestors` (which `fullAncestor` includes in the list). */
+function enclosingScope(ancestors) {
+    for (let i = ancestors.length - 2; i > 0; i--) {
+        if (SCOPE_TYPES.has(ancestors[i].type)) {
+            return ancestors[i];
+        }
+    }
+    return ancestors[0];
+}
+
+export { displayText, enclosingScope, memberChain, patternBindings, patternNames, propertyKey, resolveOrSourceText, sourceTextOf };

package/dist/esm/backend/validate.d.ts

@@ -1,6 +1,9 @@
+import type { ApiUsage } from './parser/types';
+export type { ApiCall, ApiUsage } from './parser/types';
 export interface HandlerValidation {
     /** Every `ctx.api.v1.<domain>` the handler touches (known or not), sorted and unique. */
     apiDomains: string[];
+    apiUsages: ApiUsage;
 }
 /**
  * Validates a handler's source before upload: real parsing (via acorn) catches
@@ -12,9 +15,6 @@ export interface HandlerValidation {
  * Unknown `ctx.api.v1.<domain>` usage is a warning, not a failure: this pass is
  * build-time DX feedback for agent-generated code, never a security boundary —
  * the isolate has no ambient capabilities regardless of what a handler contains.
- *
- * Returns the `ctx.api.v1.*` domains the handler touches so callers (integration
- * detection) can reuse the parse instead of re-scanning the source.
  */
 export declare function validateHandlerSource(file: string, source: string): HandlerValidation;
 //# sourceMappingURL=validate.d.ts.map

package/dist/esm/backend/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/backend/validate.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,iBAAiB;IAChC,yFAAyF;IACzF,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,iBAAiB,CAkCrF"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/backend/validate.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAIxD,MAAM,WAAW,iBAAiB;IAChC,yFAAyF;IACzF,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,QAAQ,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,iBAAiB,CAmCrF"}

package/dist/esm/backend/validate.mjs

@@ -1,10 +1,12 @@
 import { simple } from 'acorn-walk';
 import { ALWAYS_ON_CHANNELS, DECLARED_INTEGRATIONS } from '@mondaydotcomorg/z2h-shared-utils';
 import { warn } from '../util/logger.mjs';
-import { collectBindings, createPathResolver, collectApiDomains } from './ast.mjs';
-import { findHandlerDeclaration, NEVER_A_FUNCTION, handlerContextParamName } from './handler-declaration.mjs';
-import { messages } from './messages.mjs';
-import { parseOrThrow } from './parse.mjs';
+import { collectApiDomains, collectApiUsages } from './parser/api-usage.mjs';
+import { collectBindings } from './parser/bindings.mjs';
+import { findHandlerDeclaration, NEVER_A_FUNCTION, handlerContextParamName } from './parser/handler-declaration.mjs';
+import { createPathResolver } from './parser/member-path.mjs';
+import { messages } from './parser/messages.mjs';
+import { parseOrThrow } from './parser/parse.mjs';
 
 const KNOWN_API_DOMAINS = [...ALWAYS_ON_CHANNELS, ...DECLARED_INTEGRATIONS];
 /**
@@ -17,9 +19,6 @@ const KNOWN_API_DOMAINS = [...ALWAYS_ON_CHANNELS, ...DECLARED_INTEGRATIONS];
  * Unknown `ctx.api.v1.<domain>` usage is a warning, not a failure: this pass is
  * build-time DX feedback for agent-generated code, never a security boundary —
  * the isolate has no ambient capabilities regardless of what a handler contains.
- *
- * Returns the `ctx.api.v1.*` domains the handler touches so callers (integration
- * detection) can reuse the parse instead of re-scanning the source.
  */
 function validateHandlerSource(file, source) {
     const program = parseOrThrow(file, source);
@@ -43,12 +42,13 @@ function validateHandlerSource(file, source) {
     }
     const paths = createPathResolver(bindings, handlerContextParamName(declaration));
     const apiDomains = collectApiDomains(program, paths);
+    const apiUsages = collectApiUsages(program, bindings, paths, source);
     for (const domain of apiDomains) {
         if (!KNOWN_API_DOMAINS.includes(domain)) {
             warn(`${file}: ctx.api.v1.${domain} is not a known capability (available: ${KNOWN_API_DOMAINS.join(', ')})`);
         }
     }
-    return { apiDomains: [...apiDomains].sort() };
+    return { apiDomains: [...apiDomains].sort(), apiUsages };
 }
 
 export { validateHandlerSource };

package/dist/esm/commands/backend.d.ts

@@ -1,19 +1,9 @@
-/**
- * True if the app ships an app-level backend — a `backend/handlers/` directory.
- * Callers gate on this so the deploy path is explicit about whether a backend is in
- * play.
- */
 export declare function hasHandlers(appDir: string): boolean;
 /**
  * Deploy the app's backend handlers to S3 and return the integrations detected
  * from their sources. Each `.js` handler is uploaded as its own flat file — no
  * compilation, no bundling, no npm deps.
  *
- * Live and preview differ only in where the handlers land, so that is the only
- * thing `isPreview` switches:
- * - live:    `<appName>/backend-<version>` — the app's immutable per-version slot.
- * - preview: `<mfKeyPrefix without /MF>/MS` — beside the preview's `/MF` frontend.
- *
  * Integration sync note: the returned set is re-derived from the CURRENT backend
  * sources on every deploy, and the platform set is reconciled to exactly match
  * it (there is no stored declaration to fall back on). A deploy therefore always
@@ -29,9 +19,8 @@ export declare function deployBackend(opts: {
     isPreview: boolean;
 }): Promise<string[]>;
 /**
- * Run the same handler validation deploy runs (syntax, isolate constraints,
- * handler rules, integration detection) against the working tree — without
- * uploading anything. Throws on the first invalid handler.
+ * Runs the same checks deploy does against the working tree, refreshing the
+ * local `usage.json` — no upload to S3. Throws on the first invalid handler.
  */
 export declare function backendValidateCommand(appDir?: string): Promise<void>;
 export declare function backendInvokeCommand(handlerName: string, opts?: {

package/dist/esm/commands/backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../../src/commands/backend.ts"],"names":[],"mappings":"AAoBA;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnD;AAmCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CASpB;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,GAAE,MAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAa1F;AAED,wBAAsB,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAa5G"}
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../../src/commands/backend.ts"],"names":[],"mappings":"AAsBA,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnD;AAqDD;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CASpB;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,GAAE,MAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAe1F;AAED,wBAAsB,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAa5G"}