@mondaydotcomorg/z2h-cli 0.30.0 → 0.32.0

package/dist/backend/handlers.d.ts

@@ -1,8 +1,11 @@
+import { type ApiUsage } from './validate';
 export interface ReadHandlersResult {
     /** handler name (filename without .js) → JS source */
     handlers: Record<string, string>;
     /** Every `ctx.api.v1.<domain>` any handler touches, sorted and unique. */
     apiDomains: string[];
+    /** handler name → per-call `ctx.api.v1` usage, for `usage.json`. */
+    apiUsages: Record<string, ApiUsage>;
 }
 /**
  * Reads every `backend/handlers/*.js` file inside `consumerDir` and returns a

package/dist/backend/handlers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../src/backend/handlers.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,0EAA0E;IAC1E,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA2BnF"}
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../src/backend/handlers.ts"],"names":[],"mappings":"AAGA,OAAO,EAAyB,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAIlE,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,0EAA0E;IAC1E,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;CACrC;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA8BnF"}

package/dist/backend/handlers.js

@@ -18,27 +18,30 @@ const HANDLERS_DIR = path__default.default.join('backend', 'handlers');
 async function readHandlers(consumerDir) {
     const handlersDir = path__default.default.join(consumerDir, HANDLERS_DIR);
     if (!(await fs.pathExists(handlersDir))) {
-        return { handlers: {}, apiDomains: [] };
+        return { handlers: {}, apiDomains: [], apiUsages: {} };
     }
     const entries = await promises.readdir(handlersDir);
     const tsFiles = entries.filter(f => f.endsWith('.ts'));
     if (tsFiles.length > 0) {
         throw new Error(`TypeScript handlers are not yet supported (${tsFiles.join(', ')}). Compile to .js first.`);
     }
-    const jsFiles = entries.filter(f => f.endsWith('.js'));
+    // Sorted so usage.json's key order is deterministic across machines, not readdir()'s.
+    const jsFiles = entries.filter(f => f.endsWith('.js')).sort();
     if (jsFiles.length === 0) {
-        return { handlers: {}, apiDomains: [] };
+        return { handlers: {}, apiDomains: [], apiUsages: {} };
     }
     const handlers = {};
     const apiDomains = new Set();
+    const apiUsages = {};
     for (const file of jsFiles) {
         const handlerName = path__default.default.parse(file).name;
         const source = await promises.readFile(path__default.default.join(handlersDir, file), 'utf8');
         const validation = backend_validate.validateHandlerSource(file, source);
         validation.apiDomains.forEach(d => apiDomains.add(d));
         handlers[handlerName] = source;
+        apiUsages[handlerName] = validation.apiUsages;
     }
-    return { handlers, apiDomains: [...apiDomains].sort() };
+    return { handlers, apiDomains: [...apiDomains].sort(), apiUsages };
 }
 
 exports.readHandlers = readHandlers;

package/dist/backend/parser/__tests__/ast.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast.test.d.ts","sourceRoot":"","sources":["../../../../src/backend/parser/__tests__/ast.test.ts"],"names":[],"mappings":""}

package/dist/backend/parser/__tests__/parse.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.test.d.ts","sourceRoot":"","sources":["../../../../src/backend/parser/__tests__/parse.test.ts"],"names":[],"mappings":""}

package/dist/backend/parser/api-signatures.d.ts

@@ -0,0 +1,4 @@
+import type { ApiSignatures } from './types';
+/** Derived from the runner's channel docs by `scripts/generate-handler-api.mjs` at build time. */
+export declare function loadApiSignatures(): ApiSignatures;
+//# sourceMappingURL=api-signatures.d.ts.map

package/dist/backend/parser/api-signatures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-signatures.d.ts","sourceRoot":"","sources":["../../../src/backend/parser/api-signatures.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAI7C,kGAAkG;AAClG,wBAAgB,iBAAiB,IAAI,aAAa,CAcjD"}

package/dist/backend/parser/api-signatures.js

@@ -0,0 +1,31 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const fs = require('node:fs');
+const node_module = require('node:module');
+const path = require('node:path');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+const _interopDefault = e => e && e.__esModule ? e : { default: e };
+
+const path__default = /*#__PURE__*/_interopDefault(path);
+
+let cached;
+/** Derived from the runner's channel docs by `scripts/generate-handler-api.mjs` at build time. */
+function loadApiSignatures() {
+    if (cached) {
+        return cached;
+    }
+    const root = path__default.default.dirname(node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('backend/parser/api-signatures.js', document.baseURI).href))).resolve('@mondaydotcomorg/z2h-cli/package.json'));
+    try {
+        cached = JSON.parse(fs.readFileSync(path__default.default.join(root, 'handler-api', 'signatures.json'), 'utf8'));
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
+            throw err;
+        }
+        cached = {};
+    }
+    return cached;
+}
+
+exports.loadApiSignatures = loadApiSignatures;

package/dist/backend/parser/api-usage.d.ts

@@ -0,0 +1,5 @@
+import type { Program } from 'acorn';
+import type { ApiSignatures, ApiUsage, Bindings, PathResolver } from './types';
+export declare function collectApiDomains(program: Program, paths: PathResolver): Set<string>;
+export declare function collectApiUsages(program: Program, bindings: Bindings, paths: PathResolver, source: string, signatures?: ApiSignatures): ApiUsage;
+//# sourceMappingURL=api-usage.d.ts.map

package/dist/backend/parser/api-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-usage.d.ts","sourceRoot":"","sources":["../../../src/backend/parser/api-usage.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AACrC,OAAO,KAAK,EAAW,aAAa,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAcxF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,GAAG,GAAG,CAAC,MAAM,CAAC,CAWpF;AAED,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,MAAM,EACd,UAAU,GAAE,aAAmC,GAC9C,QAAQ,CAkCV"}

package/dist/backend/parser/api-usage.js

@@ -0,0 +1,61 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const acornWalk = require('acorn-walk');
+const backend_parser_utils = require('./utils.js');
+const backend_parser_staticValue = require('./static-value.js');
+const backend_parser_apiSignatures = require('./api-signatures.js');
+
+// ctx.api.v1.<domain>.<method>(...) — the only API shape the runner exposes today
+const API_PREFIX = ['ctx', 'api', 'v1'];
+const API_CALL_MIN_PARTS = API_PREFIX.length + 2;
+function isApiPath(parts) {
+    return parts[0] === API_PREFIX[0] && parts[1] === API_PREFIX[1] && parts[2] === API_PREFIX[2];
+}
+function isApiCall(parts) {
+    return isApiPath(parts) && parts.length >= API_CALL_MIN_PARTS;
+}
+function collectApiDomains(program, paths) {
+    const apiDomains = new Set();
+    acornWalk.simple(program, {
+        MemberExpression(node) {
+            const parts = paths.pathOf(node)?.split('.') ?? [];
+            if (isApiPath(parts) && parts[3]) {
+                apiDomains.add(parts[3]);
+            }
+        },
+    });
+    return apiDomains;
+}
+function collectApiUsages(program, bindings, paths, source, signatures = backend_parser_apiSignatures.loadApiSignatures()) {
+    const apiUsages = {};
+    acornWalk.simple(program, {
+        CallExpression(node) {
+            if (node.callee.type !== 'MemberExpression' && node.callee.type !== 'Identifier') {
+                return;
+            }
+            const parts = paths.pathOf(node.callee)?.split('.') ?? [];
+            if (!isApiCall(parts)) {
+                return;
+            }
+            const [, , , domain, ...methodParts] = parts;
+            const method = methodParts.join('.');
+            const sigKey = `${domain}.${method}`;
+            const names = signatures[sigKey];
+            if (!names) {
+                // eslint-disable-next-line no-console
+                console.warn(`[ast] no signature for ${sigKey} — argument names will be positional`);
+            }
+            const call = {};
+            node.arguments.forEach((arg, i) => {
+                call[names?.[i] ?? `arg${i}`] = backend_parser_utils.resolveOrSourceText(arg, source, node => backend_parser_staticValue.staticValue(node, bindings, source, new Set()), node => backend_parser_staticValue.bestSourceText(node, source, bindings));
+            });
+            const methods = (apiUsages[domain] ??= {});
+            const calls = (methods[method] ??= []);
+            calls.push(call);
+        },
+    });
+    return apiUsages;
+}
+
+exports.collectApiDomains = collectApiDomains;
+exports.collectApiUsages = collectApiUsages;

package/dist/backend/parser/bindings.d.ts

@@ -0,0 +1,5 @@
+import type { Program } from 'acorn';
+import type { Bindings, Declaration } from './types';
+export declare function collectBindings(program: Program): Bindings;
+export declare function declarationAt(bindings: Bindings, name: string, position: number): Declaration | undefined;
+//# sourceMappingURL=bindings.d.ts.map

package/dist/backend/parser/bindings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindings.d.ts","sourceRoot":"","sources":["../../../src/backend/parser/bindings.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAA0B,OAAO,EAAE,MAAM,OAAO,CAAC;AAC7D,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAcrD,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,QAAQ,CA2D1D;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAQzG"}

package/dist/backend/parser/bindings.js

@@ -0,0 +1,84 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const acornWalk = require('acorn-walk');
+const backend_parser_utils = require('./utils.js');
+
+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) => backend_parser_utils.patternNames(pattern).forEach(n => unpinnable.add(n));
+    acornWalk.fullAncestor(program, (node, _state, ancestors) => {
+        switch (node.type) {
+            case 'VariableDeclaration': {
+                const scope = backend_parser_utils.enclosingScope(ancestors);
+                for (const declarator of node.declarations) {
+                    for (const { name, path } of backend_parser_utils.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 backend_parser_utils.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 backend_parser_utils.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;
+}
+
+exports.collectBindings = collectBindings;
+exports.declarationAt = declarationAt;

package/dist/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/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/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/backend/parser/member-path.js

@@ -0,0 +1,31 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const backend_parser_utils = require('./utils.js');
+const backend_parser_bindings = require('./bindings.js');
+
+function createPathResolver(bindings, contextParam) {
+    function resolveChain(node, resolving) {
+        const chain = backend_parser_utils.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 = backend_parser_bindings.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()) };
+}
+
+exports.createPathResolver = createPathResolver;

package/dist/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/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/backend/{parse.js → parser/parse.js}

@@ -2,9 +2,9 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
 const acorn = require('acorn');
 const zod = require('zod');
-const util_tracker = require('../util/tracker.js');
-const backend_handlerDeclaration = require('./handler-declaration.js');
-const backend_messages = require('./messages.js');
+const util_tracker = require('../../util/tracker.js');
+const backend_parser_handlerDeclaration = require('./handler-declaration.js');
+const backend_parser_messages = require('./messages.js');
 
 const acornLocSchema = zod.z.object({ line: zod.z.number(), column: zod.z.number() });
 function isAcornSyntaxError(err) {
@@ -48,19 +48,19 @@ function parseOrThrow(file, code) {
     const asModule = tryParse(code, 'module');
     if (asModule.ok) {
         const { body } = asModule.program;
-        if (body.some(backend_handlerDeclaration.exportsHandler)) {
-            throw parseError(backend_messages.messages.mustNotExportHandler(file));
+        if (body.some(backend_parser_handlerDeclaration.exportsHandler)) {
+            throw parseError(backend_parser_messages.messages.mustNotExportHandler(file));
         }
         if (body.some(isImportLike)) {
-            throw parseError(backend_messages.messages.mustNotImport(file));
+            throw parseError(backend_parser_messages.messages.mustNotImport(file));
         }
         if (body.some(isExport)) {
-            throw parseError(backend_messages.messages.mustNotExport(file));
+            throw parseError(backend_parser_messages.messages.mustNotExport(file));
         }
-        throw parseError(backend_messages.messages.moduleOnlySyntax(file, stripPosition(asScript.error.message)));
+        throw parseError(backend_parser_messages.messages.moduleOnlySyntax(file, stripPosition(asScript.error.message)));
     }
     const { line, column } = asScript.error.loc;
-    throw parseError(backend_messages.messages.syntaxError(file, line, column, stripPosition(asScript.error.message)));
+    throw parseError(backend_parser_messages.messages.syntaxError(file, line, column, stripPosition(asScript.error.message)));
 }
 
 exports.parseOrThrow = parseOrThrow;

package/dist/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/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/backend/parser/static-value.js

@@ -0,0 +1,117 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const backend_parser_utils = require('./utils.js');
+const backend_parser_bindings = require('./bindings.js');
+
+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 ? backend_parser_utils.displayText(resolved.value) : `\${${backend_parser_utils.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 ? backend_parser_utils.resolveOrSourceText(element, source, inner, fallbackText) : null)),
+        };
+    }
+    const result = {};
+    for (const prop of node.properties) {
+        if (prop.type === 'SpreadElement') {
+            const spreadText = backend_parser_utils.sourceTextOf(prop.argument, source);
+            result[`...${spreadText}`] = spreadText;
+            continue;
+        }
+        if (prop.type !== 'Property') {
+            continue;
+        }
+        const key = prop.computed
+            ? backend_parser_utils.sourceTextOf(prop.key, source)
+            : backend_parser_utils.propertyKey(prop.key, false) ?? backend_parser_utils.sourceTextOf(prop.key, source);
+        result[key] = backend_parser_utils.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 = backend_parser_bindings.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 = backend_parser_bindings.declarationAt(bindings, node.name, node.start);
+        if (decl && decl.kind === 'const' && decl.init && decl.path?.length === 0) {
+            return backend_parser_utils.sourceTextOf(decl.init, source);
+        }
+    }
+    return backend_parser_utils.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;
+    }
+}
+
+exports.bestSourceText = bestSourceText;
+exports.staticValue = staticValue;

package/dist/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/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/backend/parser/types.js

@@ -0,0 +1 @@
+

package/dist/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/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"}