@mondaydotcomorg/z2h-cli 0.30.0 → 0.31.0

package/src/backend/parser/__tests__/ast.test.ts

@@ -0,0 +1,252 @@
+import { parse, type ExpressionStatement, type Program } from 'acorn';
+import { describe, expect, it } from 'vitest';
+import { collectApiUsages } from '../api-usage';
+import { collectBindings } from '../bindings';
+import { createPathResolver } from '../member-path';
+
+const program = (source: string): Program => parse(source, { ecmaVersion: 'latest', sourceType: 'script' });
+
+const SIGNATURES = { 'snowflake.query': ['sql', 'params', 'options'] };
+
+const queryCalls = (source: string) => {
+  const p = program(source);
+  const bindings = collectBindings(p);
+  return collectApiUsages(p, bindings, createPathResolver(bindings, 'ctx'), source, SIGNATURES).snowflake.query;
+};
+
+const querySql = (source: string) => queryCalls(source).map(call => call.sql);
+
+const resolveLast = (source: string, contextParam?: string) => {
+  const p = program(source);
+  const last = p.body[p.body.length - 1] as ExpressionStatement;
+  return createPathResolver(collectBindings(p), contextParam).pathOf(last.expression);
+};
+
+describe('createPathResolver', () => {
+  it('returns the literal chain when nothing is aliased', () => {
+    expect(resolveLast('ctx.api.v1.db.get;')).toBe('ctx.api.v1.db.get');
+  });
+
+  it('treats computed string literals as static keys', () => {
+    expect(resolveLast('ctx.api.v1["db"].get;')).toBe('ctx.api.v1.db.get');
+    expect(resolveLast("const { ['db']: store } = ctx.api.v1; store.get;")).toBe('ctx.api.v1.db.get');
+  });
+
+  it('returns undefined for dynamic links and non-identifier roots', () => {
+    expect(resolveLast('ctx.api.v1[db].get;')).toBeUndefined();
+    expect(resolveLast('fn().db;')).toBeUndefined();
+    expect(resolveLast('"x";')).toBeUndefined();
+  });
+
+  it('rewrites the handler context parameter to ctx', () => {
+    expect(resolveLast('context.api.v1.db.get;', 'context')).toBe('ctx.api.v1.db.get');
+    expect(resolveLast('const sf = context.api.v1.snowflake; sf.query;', 'context')).toBe('ctx.api.v1.snowflake.query');
+  });
+
+  it('follows const aliases, including destructuring and chains', () => {
+    expect(resolveLast('const sf = ctx.api.v1.snowflake; sf.query;')).toBe('ctx.api.v1.snowflake.query');
+    expect(resolveLast('const { v1 } = ctx.api; v1.db;')).toBe('ctx.api.v1.db');
+    expect(resolveLast('const { v1: { db: store } } = ctx.api; store.get;')).toBe('ctx.api.v1.db.get');
+    expect(resolveLast('const a = ctx.api; const b = a.v1; const c = b.db; c;')).toBe('ctx.api.v1.db');
+  });
+
+  it('leaves unpinnable names as written', () => {
+    expect(resolveLast('let sf = ctx.api.v1.snowflake; sf.query;')).toBe('sf.query');
+    expect(resolveLast('const sf = ctx.api.v1.snowflake; sf = 1; sf.query;')).toBe('sf.query');
+    expect(resolveLast('const [sf] = ctx.api; sf.query;')).toBe('sf.query');
+  });
+
+  it('resolves a const that a function param of the same name shadows only inside that function', () => {
+    expect(resolveLast('const sf = ctx.api.v1.snowflake; function f(sf) {} sf.query;')).toBe(
+      'ctx.api.v1.snowflake.query'
+    );
+  });
+
+  it('resolves a const that a block-scoped const of the same name shadows only inside that block', () => {
+    expect(resolveLast('const sf = ctx.api.v1.snowflake; { const sf = 1; } sf.query;')).toBe(
+      'ctx.api.v1.snowflake.query'
+    );
+  });
+
+  it('resolves through a const alias even when a catch param reuses the name', () => {
+    expect(resolveLast('const sf = ctx.api.v1.snowflake; try {} catch (sf) {} sf.query;')).toBe(
+      'ctx.api.v1.snowflake.query'
+    );
+  });
+
+  it('does not loop on circular aliases', () => {
+    expect(resolveLast('const a = b.x; const b = a.y; a.z;')).toBe('a.y.x.z');
+  });
+});
+
+describe('collectApiUsages — argument names and values', () => {
+  it('keys arguments by the documented parameter names, falling back to source text for dynamic object property values', () => {
+    expect(queryCalls('ctx.api.v1.snowflake.query("SELECT 1", { x: ctx.input.x });')).toEqual([
+      { sql: 'SELECT 1', params: { x: 'ctx.input.x' } },
+    ]);
+  });
+
+  it('falls back to positional keys past the signature or on an undocumented method', () => {
+    const source = 'ctx.api.v1.snowflake.query("SELECT 1", p, o, "extra"); ctx.api.v1.other.thing("a", "b");';
+    const p = program(source);
+    const bindings = collectBindings(p);
+    const usages = collectApiUsages(p, bindings, createPathResolver(bindings, 'ctx'), source, SIGNATURES);
+    expect(usages.snowflake.query[0]).toEqual({ sql: 'SELECT 1', params: 'p', options: 'o', arg3: 'extra' });
+    expect(usages.other.thing).toEqual([{ arg0: 'a', arg1: 'b' }]);
+  });
+
+  it('resolves string literals, `+` concatenation, and a static numeric argument', () => {
+    expect(queryCalls('ctx.api.v1.snowflake.query("SELECT " + \'1\', { x: ctx.input.x }, 5);')).toEqual([
+      { sql: 'SELECT 1', params: { x: 'ctx.input.x' }, options: 5 },
+    ]);
+  });
+
+  it('follows a const SQL variable and inlines the constants its template references', () => {
+    const source = [
+      'const WHERE = " WHERE x = :x";',
+      'const sql = `SELECT 1${WHERE}`;',
+      'ctx.api.v1.snowflake.query(sql, params);',
+    ].join('\n');
+    expect(queryCalls(source)).toEqual([{ sql: 'SELECT 1 WHERE x = :x', params: 'params' }]);
+  });
+
+  it('picks the declaration in scope at each call when the same name is declared per branch', () => {
+    const source = [
+      'const sql = "SELECT outer";',
+      'if (a) { const sql = "SELECT a"; withCache(() => ctx.api.v1.snowflake.query(sql)); }',
+      'if (b) { const sql = "SELECT b"; ctx.api.v1.snowflake.query(sql); }',
+      'ctx.api.v1.snowflake.query(sql);',
+    ].join('\n');
+    expect(querySql(source)).toEqual(['SELECT a', 'SELECT b', 'SELECT outer']);
+  });
+
+  it('leaves a template hole unresolved when it resolves to a structured value ($or), rather than gluing branches', () => {
+    const source = [
+      'const clause = custom ? " AND a" : " AND b";',
+      'ctx.api.v1.snowflake.query(`SELECT 1${clause}`);',
+    ].join('\n');
+    expect(querySql(source)).toEqual(['SELECT 1${clause}']);
+  });
+
+  it('keeps template holes it cannot resolve as written', () => {
+    const source = ['ctx.api.v1.snowflake.query(`SELECT 1 LIMIT ${ctx.input.n}`);'].join('\n');
+    expect(querySql(source)).toEqual(['SELECT 1 LIMIT ${ctx.input.n}']);
+  });
+
+  it('leaves a conditional unresolved when either branch is dynamic', () => {
+    const source = [
+      'const clause = custom ? " AND a" : ctx.input.clause;',
+      'ctx.api.v1.snowflake.query(`SELECT 1${clause}`);',
+    ].join('\n');
+    expect(querySql(source)).toEqual(['SELECT 1${clause}']);
+  });
+
+  it('resolves a logical expression whose sides both resolve, recording both alternatives', () => {
+    const source = [
+      'const OVERRIDE = "SELECT override";',
+      'const sql = OVERRIDE || "SELECT default";',
+      'ctx.api.v1.snowflake.query(sql);',
+    ].join('\n');
+    expect(querySql(source)).toEqual([{ $or: ['SELECT override', 'SELECT default'] }]);
+    expect(querySql('const sql = "SELECT a" ?? "SELECT b"; ctx.api.v1.snowflake.query(sql);')).toEqual([
+      { $or: ['SELECT a', 'SELECT b'] },
+    ]);
+  });
+
+  it("falls back to the const declaration's init source text when a logical expression has a dynamic side", () => {
+    const source = 'const sql = ctx.input.override || fetchSql(); ctx.api.v1.snowflake.query(sql);';
+    expect(querySql(source)).toEqual(['ctx.input.override || fetchSql()']);
+  });
+
+  it('resolves numbers, booleans, and null literals', () => {
+    const source = 'ctx.api.v1.snowflake.query("SELECT 1", null, 5); ctx.api.v1.other.thing(true, false);';
+    const p = program(source);
+    const bindings = collectBindings(p);
+    const usages = collectApiUsages(p, bindings, createPathResolver(bindings, 'ctx'), source, SIGNATURES);
+    expect(usages.snowflake.query).toEqual([{ sql: 'SELECT 1', params: null, options: 5 }]);
+    expect(usages.other.thing).toEqual([{ arg0: true, arg1: false }]);
+  });
+
+  it('resolves an array whose every element resolves', () => {
+    expect(queryCalls('ctx.api.v1.snowflake.query("SELECT 1", [1, "a", true]);')).toEqual([
+      { sql: 'SELECT 1', params: [1, 'a', true] },
+    ]);
+  });
+
+  it('falls back to source text for an array element that does not resolve, and for a hole', () => {
+    expect(queryCalls('ctx.api.v1.snowflake.query("SELECT 1", [1, ctx.input.x, , ...rest]);')).toEqual([
+      { sql: 'SELECT 1', params: [1, 'ctx.input.x', null, '...rest'] },
+    ]);
+  });
+
+  it('resolves an object literal whose every property resolves', () => {
+    expect(queryCalls('ctx.api.v1.snowflake.query("SELECT 1", { a: 1, b: "x" });')).toEqual([
+      { sql: 'SELECT 1', params: { a: 1, b: 'x' } },
+    ]);
+  });
+
+  it('falls back to source text for a dynamic property value or a computed key, and marks a spread instead of dropping it', () => {
+    expect(queryCalls('ctx.api.v1.snowflake.query("SELECT 1", { a: ctx.input.x });')).toEqual([
+      { sql: 'SELECT 1', params: { a: 'ctx.input.x' } },
+    ]);
+    expect(queryCalls('ctx.api.v1.snowflake.query("SELECT 1", { [k]: 1 });')).toEqual([
+      { sql: 'SELECT 1', params: { k: 1 } },
+    ]);
+    expect(queryCalls('ctx.api.v1.snowflake.query("SELECT 1", { a: 1, ...rest });')).toEqual([
+      { sql: 'SELECT 1', params: { a: 1, '...rest': 'rest' } },
+    ]);
+    expect(
+      queryCalls('ctx.api.v1.snowflake.query("SELECT 1", { tz, ...windowBindParams(timeRange), excludeInternal });')
+    ).toEqual([
+      {
+        sql: 'SELECT 1',
+        params: {
+          tz: 'tz',
+          '...windowBindParams(timeRange)': 'windowBindParams(timeRange)',
+          excludeInternal: 'excludeInternal',
+        },
+      },
+    ]);
+  });
+
+  it('follows a const array/object through an identifier, same as strings', () => {
+    const source = ['const rows = [1, 2, 3];', 'ctx.api.v1.snowflake.query("SELECT 1", rows);'].join('\n');
+    expect(queryCalls(source)).toEqual([{ sql: 'SELECT 1', params: [1, 2, 3] }]);
+  });
+
+  it('leaves a template hole unresolved when it resolves to a non-scalar value (array)', () => {
+    const source = [
+      'const params = custom ? [1, 2] : [3, 4];',
+      'ctx.api.v1.snowflake.query(`SELECT 1 -- ${params}`);',
+    ].join('\n');
+    expect(querySql(source)).toEqual(['SELECT 1 -- ${params}']);
+  });
+
+  it('falls back to source text for non-const, reassigned, destructured and circular bindings', () => {
+    expect(queryCalls('let sql = "SELECT 1"; ctx.api.v1.snowflake.query(sql);')).toEqual([{ sql: 'sql' }]);
+    expect(queryCalls('const sql = "SELECT 1"; sql = "x"; ctx.api.v1.snowflake.query(sql);')).toEqual([{ sql: 'sql' }]);
+    expect(queryCalls('const { sql } = q; ctx.api.v1.snowflake.query(sql);')).toEqual([{ sql: 'sql' }]);
+    expect(queryCalls('const a = b; const b = a; ctx.api.v1.snowflake.query(a);')).toEqual([{ sql: 'b' }]);
+  });
+
+  it('resolves a const despite a same-named function param in a different scope', () => {
+    const source = [
+      'const sql = "SELECT 1";',
+      'function helper(sql) { return sql; }',
+      'ctx.api.v1.snowflake.query(sql);',
+    ].join('\n');
+    expect(querySql(source)).toEqual(['SELECT 1']);
+  });
+
+  it('does not resolve a tagged template (the tag function return is unknown)', () => {
+    expect(queryCalls('ctx.api.v1.snowflake.query(sql`SELECT 1`);')).toEqual([{ sql: 'sql`SELECT 1`' }]);
+  });
+
+  it('records a destructured method call (const { query } = ctx.api.v1.snowflake)', () => {
+    const source = ['const { query } = ctx.api.v1.snowflake;', 'query("SELECT 1", { x: 1 });'].join('\n');
+    const p = program(source);
+    const bindings = collectBindings(p);
+    const usages = collectApiUsages(p, bindings, createPathResolver(bindings, 'ctx'), source, SIGNATURES);
+    expect(usages.snowflake.query).toEqual([{ sql: 'SELECT 1', params: { x: 1 } }]);
+  });
+});

package/src/backend/{__tests__ → parser/__tests__}/parse.test.ts

@@ -1,8 +1,8 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import { trackEvent } from '../../util/tracker';
+import { trackEvent } from '../../../util/tracker';
 import { parseOrThrow } from '../parse';
 
-vi.mock('../../util/tracker', () => ({
+vi.mock('../../../util/tracker', () => ({
   trackEvent: vi.fn().mockResolvedValue(undefined),
   trackDuration: vi.fn(),
 }));

package/src/backend/parser/api-signatures.ts

@@ -0,0 +1,23 @@
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import type { ApiSignatures } from './types';
+
+let cached: ApiSignatures | undefined;
+
+/** Derived from the runner's channel docs by `scripts/generate-handler-api.mjs` at build time. */
+export function loadApiSignatures(): ApiSignatures {
+  if (cached) {
+    return cached;
+  }
+  const root = path.dirname(createRequire(import.meta.url).resolve('@mondaydotcomorg/z2h-cli/package.json'));
+  try {
+    cached = JSON.parse(readFileSync(path.join(root, 'handler-api', 'signatures.json'), 'utf8')) as ApiSignatures;
+  } catch (err) {
+    if ((err as { code?: string }).code !== 'ENOENT') {
+      throw err;
+    }
+    cached = {};
+  }
+  return cached;
+}

package/src/backend/parser/api-usage.ts

@@ -0,0 +1,73 @@
+import { simple as walkSimple } from 'acorn-walk';
+import { resolveOrSourceText } from './utils';
+import { bestSourceText, staticValue } from './static-value';
+import { loadApiSignatures } from './api-signatures';
+import type { Program } from 'acorn';
+import type { ApiCall, ApiSignatures, ApiUsage, Bindings, PathResolver } from './types';
+
+// ctx.api.v1.<domain>.<method>(...) — the only API shape the runner exposes today
+const API_PREFIX = ['ctx', 'api', 'v1'] as const;
+const API_CALL_MIN_PARTS = API_PREFIX.length + 2;
+
+function isApiPath(parts: string[]): boolean {
+  return parts[0] === API_PREFIX[0] && parts[1] === API_PREFIX[1] && parts[2] === API_PREFIX[2];
+}
+
+function isApiCall(parts: string[]): boolean {
+  return isApiPath(parts) && parts.length >= API_CALL_MIN_PARTS;
+}
+
+export function collectApiDomains(program: Program, paths: PathResolver): Set<string> {
+  const apiDomains = new Set<string>();
+  walkSimple(program, {
+    MemberExpression(node) {
+      const parts = paths.pathOf(node)?.split('.') ?? [];
+      if (isApiPath(parts) && parts[3]) {
+        apiDomains.add(parts[3]);
+      }
+    },
+  });
+  return apiDomains;
+}
+
+export function collectApiUsages(
+  program: Program,
+  bindings: Bindings,
+  paths: PathResolver,
+  source: string,
+  signatures: ApiSignatures = loadApiSignatures()
+): ApiUsage {
+  const apiUsages: ApiUsage = {};
+  walkSimple(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: ApiCall = {};
+      node.arguments.forEach((arg, i) => {
+        call[names?.[i] ?? `arg${i}`] = resolveOrSourceText(
+          arg,
+          source,
+          node => staticValue(node, bindings, source, new Set()),
+          node => bestSourceText(node, source, bindings)
+        );
+      });
+      const methods = (apiUsages[domain] ??= {});
+      const calls = (methods[method] ??= []);
+      calls.push(call);
+    },
+  });
+  return apiUsages;
+}

package/src/backend/parser/bindings.ts

@@ -0,0 +1,87 @@
+import { fullAncestor as walkFullAncestor } from 'acorn-walk';
+import { enclosingScope, patternBindings, patternNames } from './utils';
+import type { AnyNode, Node, Pattern, Program } from 'acorn';
+import type { Bindings, Declaration } from './types';
+
+function functionBodyScope(node: AnyNode): Node {
+  if (
+    (node.type === 'FunctionDeclaration' ||
+      node.type === 'FunctionExpression' ||
+      node.type === 'ArrowFunctionExpression') &&
+    node.body.type === 'BlockStatement'
+  ) {
+    return node.body;
+  }
+  return node;
+}
+
+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));
+
+  walkFullAncestor(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 };
+}
+
+export function declarationAt(bindings: Bindings, name: string, position: number): Declaration | undefined {
+  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;
+}

package/src/backend/parser/member-path.ts

@@ -0,0 +1,31 @@
+import { memberChain } from './utils';
+import { declarationAt } from './bindings';
+import type { AnyNode } from 'acorn';
+import type { Bindings, PathResolver } from './types';
+
+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, node.start, resolving), ...chain.parts].join('.');
+  }
+
+  function resolveRoot(name: string, position: number, resolving: ReadonlySet<string>): string {
+    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()) };
+}

package/src/backend/{parse.ts → parser/parse.ts}

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

package/src/backend/parser/static-value.ts

@@ -0,0 +1,145 @@
+import { displayText, propertyKey, resolveOrSourceText, sourceTextOf } from './utils';
+import { declarationAt } from './bindings';
+import type { AnyNode } from 'acorn';
+import type { Bindings, JsonValue, Resolved } from './types';
+
+type Inner = (child: AnyNode) => Resolved<JsonValue> | undefined;
+
+function resolveLiteral(node: AnyNode & { type: 'Literal' }): Resolved<JsonValue> | undefined {
+  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: AnyNode & { type: 'TemplateLiteral' },
+  source: string,
+  inner: Inner
+): Resolved<JsonValue> {
+  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: AnyNode & { type: 'ArrayExpression' | 'ObjectExpression' },
+  source: string,
+  bindings: Bindings,
+  inner: Inner
+): Resolved<JsonValue> {
+  const fallbackText = (n: AnyNode) => bestSourceText(n, source, bindings);
+  if (node.type === 'ArrayExpression') {
+    return {
+      value: node.elements.map(element => (element ? resolveOrSourceText(element, source, inner, fallbackText) : null)),
+    };
+  }
+  const result: { [key: string]: JsonValue } = {};
+  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: Resolved<JsonValue> | undefined,
+  right: Resolved<JsonValue> | undefined
+): Resolved<JsonValue> | undefined {
+  return left !== undefined && right !== undefined ? { value: { $or: [left.value, right.value] } } : undefined;
+}
+
+function resolveIdentifier(
+  node: AnyNode & { type: 'Identifier' },
+  bindings: Bindings,
+  source: string,
+  resolving: ReadonlySet<string>
+): Resolved<JsonValue> | undefined {
+  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. */
+export function bestSourceText(node: AnyNode, source: string, bindings: Bindings): string {
+  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);
+}
+
+export function staticValue(
+  node: AnyNode,
+  bindings: Bindings,
+  source: string,
+  resolving: ReadonlySet<string>
+): Resolved<JsonValue> | undefined {
+  const inner: 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;
+  }
+}