@mondaydotcomorg/z2h-cli 0.27.1 → 0.28.0

package/src/backend/ast.ts

@@ -0,0 +1,204 @@
+import type { AnyNode, Expression, Node, Pattern, Program, VariableDeclaration } from 'acorn';
+import { full as walkFull, simple as walkSimple } from 'acorn-walk';
+
+/** 1-based line a node starts on; requires the program to be parsed with `locations: true`. */
+export const lineOf = (node: Node): number | undefined => node.loc?.start.line;
+
+// ─────────── Bindings ───────────
+
+export interface Declaration {
+  kind: VariableDeclaration['kind'];
+  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;
+}
+
+export interface Bindings {
+  /** Every `var|let|const <name> = …` in the file, by name. */
+  declarations: Map<string, Declaration[]>;
+  /** Names whose value cannot be pinned: reassigned, updated, or bound as parameters. */
+  unpinnable: Set<string>;
+}
+
+interface PatternBinding {
+  name: string;
+  path: string[] | 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.
+ */
+function patternBindings(pattern: Pattern, path: string[] | undefined): PatternBinding[] {
+  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 [];
+  }
+}
+
+function propertyKey(key: AnyNode, computed: boolean): string | undefined {
+  if (key.type === 'Literal' && typeof key.value === 'string') {
+    return key.value;
+  }
+  if (!computed && key.type === 'Identifier') {
+    return key.name;
+  }
+  return undefined;
+}
+
+/** Every identifier a binding pattern introduces (`{ a, b: [c] } = …` → a, c). */
+export const patternNames = (pattern: Pattern): string[] => patternBindings(pattern, []).map(b => b.name);
+
+export function collectBindings(program: Program): Bindings {
+  const declarations = new Map<string, Declaration[]>();
+  const unpinnable = new Set<string>();
+  const markUnpinnable = (pattern: Pattern) => patternNames(pattern).forEach(n => unpinnable.add(n));
+
+  walkFull(program, node => {
+    switch (node.type) {
+      case 'VariableDeclaration':
+        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 });
+            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':
+        node.params.forEach(markUnpinnable);
+        break;
+      case 'CatchClause':
+        if (node.param) {
+          markUnpinnable(node.param);
+        }
+        break;
+    }
+  });
+
+  return { declarations, unpinnable };
+}
+
+// ─────────── Member paths ───────────
+
+interface MemberChain {
+  root: string;
+  parts: string[];
+}
+
+/** `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: AnyNode): MemberChain | undefined {
+  if (node.type === 'ChainExpression') {
+    return memberChain(node.expression);
+  }
+  const parts: string[] = [];
+  let cur: AnyNode = 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;
+}
+
+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, so a `let` alias or a parameter of the same
+   * name is never mistaken for the channel. 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;
+}
+
+export function createPathResolver(bindings: Bindings, contextParam?: string): PathResolver {
+  function resolveChain(node: AnyNode, resolving: ReadonlySet<string>): string | undefined {
+    const chain = memberChain(node);
+    if (!chain) {
+      return undefined;
+    }
+    return [resolveRoot(chain.root, resolving), ...chain.parts].join('.');
+  }
+
+  function resolveRoot(name: string, resolving: ReadonlySet<string>): string {
+    if (contextParam !== undefined && name === contextParam) {
+      return 'ctx';
+    }
+    if (bindings.unpinnable.has(name) || resolving.has(name)) {
+      return name;
+    }
+    const decls = bindings.declarations.get(name);
+    if (!decls || decls.length !== 1) {
+      return name;
+    }
+    const [{ kind, init, path }] = decls;
+    if (kind !== 'const' || !init || !path) {
+      return name;
+    }
+    const base = resolveChain(init, new Set(resolving).add(name));
+    return base ? [base, ...path].join('.') : name;
+  }
+
+  return { pathOf: node => resolveChain(node, new Set()) };
+}
+
+/** Every `ctx.api.v1.<domain>` the program touches (known or not), through `paths`. */
+export function collectApiDomains(program: Program, paths: PathResolver): Set<string> {
+  const apiDomains = new Set<string>();
+  walkSimple(program, {
+    MemberExpression(node) {
+      const [obj, api, version, domain] = paths.pathOf(node)?.split('.') ?? [];
+      if (obj === 'ctx' && api === 'api' && version === 'v1' && domain) {
+        apiDomains.add(domain);
+      }
+    },
+  });
+  return apiDomains;
+}

package/src/backend/detect-integrations.ts

@@ -1,22 +1,20 @@
-import { DECLARED_INTEGRATIONS } from '../constants';
+import { DECLARED_INTEGRATIONS, type DeclaredIntegration } from '@mondaydotcomorg/z2h-shared-utils';
+
+const declared: ReadonlySet<string> = new Set(DECLARED_INTEGRATIONS);
+const isDeclaredIntegration = (domain: string): domain is DeclaredIntegration => declared.has(domain);
 
 /**
- * Integrations inferred from handler source at deploy time — whatever
+ * Integrations inferred from handler sources at deploy time — whatever
  * `ctx.api.v1.<name>` the handlers touch (from `DECLARED_INTEGRATIONS`) is
  * registered with the platform. There is no `integrations.json` and no declare
  * CLI step.
  *
- * Only OAuth-gated integrations belong in that set. `db`, `llm`, and `snowflake`
- * are always-on channels and are never declared.
+ * `apiDomains` comes from the handler parse in `validateHandlerSource`, so a
+ * domain mentioned only in a comment or string does not count as usage.
+ *
+ * Only OAuth-gated integrations belong in the result. `db`, `llm`, and
+ * `snowflake` are always-on channels and are never declared.
  */
-export function detectIntegrationsFromHandlers(handlers: Record<string, string>): string[] {
-  const found = new Set<string>();
-  for (const source of Object.values(handlers)) {
-    for (const name of DECLARED_INTEGRATIONS) {
-      if (new RegExp(`\\bctx\\.api\\.v1\\.${name}\\b`).test(source)) {
-        found.add(name);
-      }
-    }
-  }
-  return [...found].sort();
+export function detectIntegrations(apiDomains: Iterable<string>): DeclaredIntegration[] {
+  return [...new Set(apiDomains)].filter(isDeclaredIntegration).sort();
 }

package/src/backend/handler-declaration.ts

@@ -0,0 +1,104 @@
+import type {
+  AnyNode,
+  ArrowFunctionExpression,
+  Expression,
+  FunctionDeclaration,
+  FunctionExpression,
+  ModuleDeclaration,
+  Pattern,
+  Statement,
+} from 'acorn';
+
+/** True for the `handler` identifier specifically — used everywhere a node might name the binding. */
+const isHandlerIdentifier = (candidate: AnyNode | null | undefined): boolean =>
+  candidate?.type === 'Identifier' && candidate.name === 'handler';
+
+export type HandlerDeclaration =
+  | { kind: 'function'; params: FunctionDeclaration['params'] }
+  | { kind: 'variable'; init: Expression | null | undefined };
+
+/** The top-level declaration that binds `handler`, if any. */
+export function findHandlerDeclaration(
+  body: readonly (Statement | ModuleDeclaration)[]
+): HandlerDeclaration | undefined {
+  for (const node of body) {
+    if (node.type === 'FunctionDeclaration' && isHandlerIdentifier(node.id)) {
+      return { kind: 'function', params: node.params };
+    }
+    if (node.type === 'VariableDeclaration') {
+      const declarator = node.declarations.find(d => isHandlerIdentifier(d.id));
+      if (declarator) {
+        return { kind: 'variable', init: declarator.init };
+      }
+    }
+  }
+  return undefined;
+}
+
+/** `export function handler`, `export const handler`, `export { handler }`, `export default handler`. */
+export function exportsHandler(node: Statement | ModuleDeclaration): boolean {
+  if (node.type === 'ExportNamedDeclaration') {
+    return (
+      (node.declaration != null && findHandlerDeclaration([node.declaration]) !== undefined) ||
+      node.specifiers.some(s => isHandlerIdentifier(s.local) || isHandlerIdentifier(s.exported))
+    );
+  }
+  if (node.type === 'ExportDefaultDeclaration') {
+    const { declaration } = node;
+    return (
+      (declaration.type === 'FunctionDeclaration' && isHandlerIdentifier(declaration.id)) ||
+      isHandlerIdentifier(declaration)
+    );
+  }
+  return false;
+}
+
+/** Peel `wrap(fn)`, `(0, fn)`, and the like until a function expression remains. */
+function asFunction(expr: Expression | null | undefined): FunctionExpression | ArrowFunctionExpression | undefined {
+  if (!expr) {
+    return undefined;
+  }
+  switch (expr.type) {
+    case 'FunctionExpression':
+    case 'ArrowFunctionExpression':
+      return expr;
+    case 'SequenceExpression':
+      return asFunction(expr.expressions.at(-1));
+    case 'CallExpression': {
+      for (const arg of expr.arguments) {
+        if (arg.type === 'SpreadElement') {
+          continue;
+        }
+        const fn = asFunction(arg);
+        if (fn) {
+          return fn;
+        }
+      }
+      return undefined;
+    }
+    default:
+      return undefined;
+  }
+}
+
+function firstParamName(params: readonly Pattern[]): string | undefined {
+  let first: Pattern | undefined = params[0];
+  if (first?.type === 'AssignmentPattern') {
+    first = first.left;
+  }
+  return first?.type === 'Identifier' ? first.name : undefined;
+}
+
+/** First positional parameter of `handler`, when it's a plain identifier (`ctx`, `context`, …). */
+export function handlerContextParamName(declaration: HandlerDeclaration): string | undefined {
+  const params = declaration.kind === 'function' ? declaration.params : asFunction(declaration.init)?.params;
+  return params ? firstParamName(params) : undefined;
+}
+
+/** Values that can never be a function, so `const handler = <this>` is caught at build time. */
+export const NEVER_A_FUNCTION: ReadonlySet<string> = new Set([
+  'Literal',
+  'ObjectExpression',
+  'ArrayExpression',
+  'TemplateLiteral',
+]);

package/src/backend/handlers.ts

@@ -1,38 +1,15 @@
 import path from 'node:path';
 import { readdir, readFile } from 'node:fs/promises';
 import { pathExists } from 'fs-extra';
+import { validateHandlerSource } from './validate';
 
 const HANDLERS_DIR = path.join('backend', 'handlers');
 
 export interface ReadHandlersResult {
   /** handler name (filename without .js) → JS source */
   handlers: Record<string, string>;
-}
-
-/**
- * True if the source defines a `handler` function or variable at the top level.
- * Handlers run in a V8 isolate with no module system — `handler` must be a plain
- * global, not an export.
- */
-function definesHandler(source: string): boolean {
-  return /\bfunction\s+handler\b/.test(source) || /\b(const|let|var)\s+handler\b/.test(source);
-}
-
-/**
- * True if `handler` is declared with an `export` prefix. It reads as valid source but
- * the isolate has no module system, so an exported handler is simply invisible to the
- * runner — caught here rather than failing opaquely at invoke time.
- */
-function exportsHandler(source: string): boolean {
-  return /\bexport\s+(default\s+)?(async\s+)?(function\s+handler\b|(?:const|let|var)\s+handler\b)/.test(source);
-}
-
-/**
- * True if the source contains any `import` or `require` call. Neither works in
- * the V8 isolate — reach the outside world through `ctx` capabilities instead.
- */
-function hasImports(source: string): boolean {
-  return /^\s*import\b/m.test(source) || /\brequire\s*\(/.test(source);
+  /** Every `ctx.api.v1.<domain>` any handler touches, sorted and unique. */
+  apiDomains: string[];
 }
 
 /**
@@ -43,7 +20,7 @@ function hasImports(source: string): boolean {
 export async function readHandlers(consumerDir: string): Promise<ReadHandlersResult> {
   const handlersDir = path.join(consumerDir, HANDLERS_DIR);
   if (!(await pathExists(handlersDir))) {
-    return { handlers: {} };
+    return { handlers: {}, apiDomains: [] };
   }
 
   const entries = await readdir(handlersDir);
@@ -53,30 +30,18 @@ export async function readHandlers(consumerDir: string): Promise<ReadHandlersRes
   }
   const jsFiles = entries.filter(f => f.endsWith('.js'));
   if (jsFiles.length === 0) {
-    return { handlers: {} };
+    return { handlers: {}, apiDomains: [] };
   }
 
   const handlers: Record<string, string> = {};
+  const apiDomains = new Set<string>();
   for (const file of jsFiles) {
     const handlerName = path.parse(file).name;
     const source = await readFile(path.join(handlersDir, file), 'utf8');
 
-    // Before the definesHandler check: `export const handler` satisfies that one too.
-    if (exportsHandler(source)) {
-      throw new Error(
-        `${file} must not export handler — the isolate has no module system; declare it as a plain global, e.g. async function handler(ctx) { ... }`
-      );
-    }
-    if (!definesHandler(source)) {
-      throw new Error(`${file} must define a handler — e.g. async function handler(ctx) { ... }`);
-    }
-    if (hasImports(source)) {
-      throw new Error(
-        `${file} must not import other files or packages — handlers are self-contained; reach the outside world through ctx capabilities`
-      );
-    }
-
+    const validation = validateHandlerSource(file, source);
+    validation.apiDomains.forEach(d => apiDomains.add(d));
     handlers[handlerName] = source;
   }
-  return { handlers };
+  return { handlers, apiDomains: [...apiDomains].sort() };
 }

package/src/backend/messages.ts

@@ -0,0 +1,16 @@
+const EXAMPLE = 'async function handler(ctx) { ... }';
+
+export const messages = {
+  mustDefine: (file: string) => `${file} must define a handler — e.g. ${EXAMPLE}`,
+  notAFunction: (file: string) => `${file} declares handler but it is not a function — e.g. ${EXAMPLE}`,
+  mustNotImport: (file: string) =>
+    `${file} must not import other files or packages — handlers are self-contained; reach the outside world through ctx capabilities`,
+  mustNotExportHandler: (file: string) =>
+    `${file} must not export handler — the isolate has no module system; declare it as a plain global, e.g. ${EXAMPLE}`,
+  mustNotExport: (file: string) =>
+    `${file} must not use export — the isolate has no module system; declare handler as a plain global, e.g. ${EXAMPLE}`,
+  moduleOnlySyntax: (file: string, detail: string) =>
+    `${file} uses module-only syntax (${detail}) — handlers run as plain scripts, so top-level await and import.meta are not available`,
+  syntaxError: (file: string, line: number, column: number, detail: string) =>
+    `${file}:${line}:${column}: not valid JavaScript — ${detail}`,
+};

package/src/backend/parse.ts

@@ -0,0 +1,82 @@
+import { parse, type ExportNamedDeclaration, type ModuleDeclaration, type Program, type Statement } from 'acorn';
+import { z } from 'zod';
+import { trackEvent } from '../util/tracker';
+import { exportsHandler } from './handler-declaration';
+import { messages } from './messages';
+
+const acornLocSchema = z.object({ line: z.number(), column: z.number() });
+
+interface AcornSyntaxError extends SyntaxError {
+  loc: { line: number; column: number };
+}
+
+function isAcornSyntaxError(err: unknown): err is AcornSyntaxError {
+  return err instanceof SyntaxError && acornLocSchema.safeParse((err as { loc?: unknown }).loc).success;
+}
+
+type ParseResult = { ok: true; program: Program } | { ok: false; error: AcornSyntaxError };
+
+function tryParse(code: string, sourceType: 'script' | 'module'): ParseResult {
+  try {
+    return { ok: true, program: parse(code, { ecmaVersion: 'latest', sourceType, locations: true }) };
+  } catch (err) {
+    if (isAcornSyntaxError(err)) {
+      return { ok: false, error: err };
+    }
+    throw err;
+  }
+}
+
+/** Acorn appends ` (line:col)` to its messages; we report the position ourselves. */
+const stripPosition = (message: string): string => message.replace(/ \(\d+:\d+\)$/, '');
+
+type ImportLike = (ModuleDeclaration & { type: 'ImportDeclaration' | 'ExportAllDeclaration' }) | ExportNamedDeclaration;
+
+const isImportLike = (node: Statement | ModuleDeclaration): node is ImportLike =>
+  node.type === 'ImportDeclaration' ||
+  node.type === 'ExportAllDeclaration' ||
+  (node.type === 'ExportNamedDeclaration' && node.source != null);
+
+type ExportLike = ModuleDeclaration & { type: 'ExportNamedDeclaration' | 'ExportDefaultDeclaration' };
+
+const isExport = (node: Statement | ModuleDeclaration): node is ExportLike =>
+  node.type === 'ExportNamedDeclaration' || node.type === 'ExportDefaultDeclaration';
+
+/** Reports the failure, then returns the error for the caller to throw. */
+function parseError(message: string): Error {
+  void trackEvent('z2h_cli_handler_parse_error', { error: message });
+  return new Error(message);
+}
+
+/**
+ * The runner compiles handlers with `isolate.compileScript`, i.e. the classic
+ * *script* grammar — so that is the grammar we validate against. `import`/`export`
+ * declarations and top-level `await`/`import.meta` are only legal under the
+ * *module* grammar, so a handler using any of them fails the script parse; we
+ * re-parse it as a module purely to name which of those four things it was,
+ * instead of surfacing V8's bare "Unexpected token 'export'".
+ */
+export function parseOrThrow(file: string, code: string): Program {
+  const asScript = tryParse(code, 'script');
+  if (asScript.ok) {
+    return asScript.program;
+  }
+
+  const asModule = tryParse(code, 'module');
+  if (asModule.ok) {
+    const { body } = asModule.program;
+    if (body.some(exportsHandler)) {
+      throw parseError(messages.mustNotExportHandler(file));
+    }
+    if (body.some(isImportLike)) {
+      throw parseError(messages.mustNotImport(file));
+    }
+    if (body.some(isExport)) {
+      throw parseError(messages.mustNotExport(file));
+    }
+    throw parseError(messages.moduleOnlySyntax(file, stripPosition(asScript.error.message)));
+  }
+
+  const { line, column } = asScript.error.loc;
+  throw parseError(messages.syntaxError(file, line, column, stripPosition(asScript.error.message)));
+}