@barefootjs/jsx 0.16.0 → 0.17.0

package/src/__tests__/ir-reduce-op.test.ts

@@ -1,21 +1,21 @@
 import { describe, test, expect } from 'bun:test'
 import { analyzeComponent } from '../analyzer'
 import { jsxToIR } from '../jsx-to-ir'
-import { parseExpression } from '../expression-parser'
+import { parseExpression, asCallbackMethodCall } from '../expression-parser'
 
 /**
- * IR-level verification for `.reduce(fn, init)` (#1448 Tier C). The
- * parser intercepts the arithmetic-fold catalogue into a structured
- * `array-method` + `ReduceOp` node — this test pins the source-string
- * that survives through `jsxToIR` to an `IRExpression`, then re-parses
- * it to confirm the structured fold shape adapters consume.
+ * IR-level verification for `.reduce(fn, init)` (#2018 P5). The parser no
+ * longer folds the reducer into a structured `ReduceOp`; `.reduce` arrives as a
+ * generic `call` whose callee is `<recv>.reduce` and whose args are the
+ * comparator `arrow` + the init literal. The adapter serializes the arrow body
+ * to the runtime evaluator. This test pins that the generic callback shape
+ * survives the analyzer → IR boundary.
  *
- * Hydration and template-emit correctness are pinned at the adapter
- * conformance layer (`reduce-*` fixtures in `packages/adapter-tests/
- * fixtures/methods/`).
+ * Hydration / template-emit / Go==Perl==JS fold correctness are pinned at the
+ * adapter conformance + eval-vectors layers.
  */
 describe('reduce(fn, init) IR shape', () => {
-  test('sum over a struct field re-parses to a numeric ReduceOp', () => {
+  test('sum over a struct field parses to a generic reduce callback', () => {
     const source = `
       'use client'
       import { createSignal } from '@barefootjs/client'
@@ -35,17 +35,14 @@ describe('reduce(fn, init) IR shape', () => {
     expect(exprNode?.type).toBe('expression')
     if (exprNode?.type !== 'expression') return
 
-    // The IR carries the expression as a source string (the same shape
-    // adapters re-parse at emit time). Round-trip it to confirm the
-    // ReduceOp catalogue match survives the analyzer → IR boundary.
     const parsed = parseExpression(exprNode.expr)
-    expect(parsed.kind).toBe('array-method')
-    if (parsed.kind !== 'array-method') return
-    expect(parsed.method).toBe('reduce')
-    if (parsed.method !== 'reduce') return
-    expect(parsed.reduceOp.op).toBe('+')
-    expect(parsed.reduceOp.key).toEqual({ kind: 'field', field: 'duration' })
-    expect(parsed.reduceOp.type).toBe('numeric')
-    expect(parsed.reduceOp.init).toBe('0')
+    const cb = asCallbackMethodCall(parsed)
+    expect(cb).not.toBeNull()
+    expect(cb!.method).toBe('reduce')
+    expect(cb!.arrow.params).toEqual(['sum', 't'])
+    // Reducer body: `sum + t.duration`.
+    expect(cb!.arrow.body.kind).toBe('binary')
+    // The init literal travels as the trailing argument.
+    expect(cb!.args).toEqual([{ kind: 'literal', value: 0, literalType: 'number', raw: '0' }])
   })
 })

package/src/__tests__/ir-sort-comparator.test.ts

@@ -1,6 +1,7 @@
 import { describe, test, expect } from 'bun:test'
 import { analyzeComponent } from '../analyzer'
 import { jsxToIR } from '../jsx-to-ir'
+import { sortComparatorFromArrow } from '../expression-parser'
 
 describe('sort().map() / toSorted().map()', () => {
   test('sort((a, b) => a.price - b.price).map() produces sortComparator (asc)', () => {
@@ -31,11 +32,10 @@ describe('sort().map() / toSorted().map()', () => {
       expect(loop).toBeDefined()
       if (loop?.type === 'loop') {
         expect(loop.sortComparator).toBeDefined()
-        expect(loop.sortComparator!.keys).toHaveLength(1)
-        expect(loop.sortComparator!.keys[0].key).toEqual({ kind: 'field', field: 'price' })
-        expect(loop.sortComparator!.keys[0].type).toBe('numeric')
-        expect(loop.sortComparator!.keys[0].direction).toBe('asc')
-        expect(loop.sortComparator!.method).toBe('sort')
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys).toHaveLength(1)
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys[0].key).toEqual({ kind: 'field', field: 'price' })
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys[0].type).toBe('numeric')
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys[0].direction).toBe('asc')
         expect(loop.sortComparator!.paramA).toBe('a')
         expect(loop.sortComparator!.paramB).toBe('b')
         expect(loop.array).toBe('products()')
@@ -70,11 +70,10 @@ describe('sort().map() / toSorted().map()', () => {
       expect(loop).toBeDefined()
       if (loop?.type === 'loop') {
         expect(loop.sortComparator).toBeDefined()
-        expect(loop.sortComparator!.keys).toHaveLength(1)
-        expect(loop.sortComparator!.keys[0].key).toEqual({ kind: 'field', field: 'price' })
-        expect(loop.sortComparator!.keys[0].type).toBe('numeric')
-        expect(loop.sortComparator!.keys[0].direction).toBe('desc')
-        expect(loop.sortComparator!.method).toBe('toSorted')
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys).toHaveLength(1)
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys[0].key).toEqual({ kind: 'field', field: 'price' })
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys[0].type).toBe('numeric')
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys[0].direction).toBe('desc')
       }
     }
   })
@@ -107,10 +106,10 @@ describe('sort().map() / toSorted().map()', () => {
         expect(loop.filterPredicate).toBeDefined()
         expect(loop.filterPredicate!.param).toBe('t')
         expect(loop.sortComparator).toBeDefined()
-        expect(loop.sortComparator!.keys).toHaveLength(1)
-        expect(loop.sortComparator!.keys[0].key).toEqual({ kind: 'field', field: 'priority' })
-        expect(loop.sortComparator!.keys[0].type).toBe('numeric')
-        expect(loop.sortComparator!.keys[0].direction).toBe('asc')
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys).toHaveLength(1)
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys[0].key).toEqual({ kind: 'field', field: 'priority' })
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys[0].type).toBe('numeric')
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys[0].direction).toBe('asc')
         expect(loop.chainOrder).toBe('filter-sort')
         expect(loop.array).toBe('todos()')
       }
@@ -176,7 +175,7 @@ describe('sort().map() / toSorted().map()', () => {
       expect(loop?.type).toBe('loop')
       if (loop?.type === 'loop') {
         expect(loop.sortComparator).toBeDefined()
-        expect(loop.sortComparator!.keys).toEqual([
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys).toEqual([
           { key: { kind: 'field', field: 'price' }, type: 'numeric', direction: 'desc' },
           { key: { kind: 'field', field: 'name' }, type: 'string', direction: 'asc' },
         ])
@@ -209,7 +208,7 @@ describe('sort().map() / toSorted().map()', () => {
       const loop = ir!.children.find(c => c.type === 'loop')
       if (loop?.type === 'loop') {
         expect(loop.sortComparator).toBeDefined()
-        expect(loop.sortComparator!.keys).toEqual([
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys).toEqual([
           { key: { kind: 'field', field: 'rank' }, type: 'auto', direction: 'asc' },
         ])
       }
@@ -241,7 +240,7 @@ describe('sort().map() / toSorted().map()', () => {
       const loop = ir!.children.find(c => c.type === 'loop')
       if (loop?.type === 'loop') {
         expect(loop.sortComparator).toBeDefined()
-        expect(loop.sortComparator!.keys).toEqual([
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys).toEqual([
           { key: { kind: 'self' }, type: 'auto', direction: 'asc' },
         ])
       }
@@ -273,7 +272,7 @@ describe('sort().map() / toSorted().map()', () => {
       const loop = ir!.children.find(c => c.type === 'loop')
       if (loop?.type === 'loop') {
         expect(loop.sortComparator).toBeDefined()
-        expect(loop.sortComparator!.keys).toEqual([
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys).toEqual([
           { key: { kind: 'field', field: 'price' }, type: 'numeric', direction: 'asc' },
         ])
         // block body unwraps to the returned expression, keeping the
@@ -310,7 +309,7 @@ describe('sort().map() / toSorted().map()', () => {
         expect(loop.sortComparator).toBeDefined()
         // The `=== ? 0` arm is a tie; direction comes from the inner
         // relational ternary (a.rank > b.rank ? 1 : -1 → ascending).
-        expect(loop.sortComparator!.keys).toEqual([
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys).toEqual([
           { key: { kind: 'field', field: 'rank' }, type: 'auto', direction: 'asc' },
         ])
       }
@@ -342,7 +341,7 @@ describe('sort().map() / toSorted().map()', () => {
       const loop = ir!.children.find(c => c.type === 'loop')
       if (loop?.type === 'loop') {
         expect(loop.sortComparator).toBeDefined()
-        expect(loop.sortComparator!.keys).toEqual([
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys).toEqual([
           { key: { kind: 'field', field: 'price' }, type: 'numeric', direction: 'asc' },
           { key: { kind: 'field', field: 'rank' }, type: 'auto', direction: 'asc' },
         ])

package/src/__tests__/lowering-registry.test.ts

@@ -0,0 +1,141 @@
+/**
+ * Lowering-plugin registry (#2057) — the one seam every lowering flows through.
+ * These tests guarantee the mechanism works: a registered plugin's matcher is
+ * bound per-component and produces a backend-neutral node, and the registry gates
+ * on the plugin's own import recognition. They use a standalone SAMPLE plugin so
+ * they exercise the mechanism itself, independent of the built-in plugins (like
+ * `queryHref`) the compiler registers by default — see `builtin-lowering-plugins`.
+ */
+
+import { describe, test, expect, afterEach } from 'bun:test'
+import {
+  registerLoweringPlugin,
+  getLoweringPlugins,
+  prepareLoweringMatchers,
+  matchLoweringCall,
+  __resetLoweringPluginsForTest,
+  type LoweringPlugin,
+  type IRMetadata,
+  type ParsedExpr,
+} from '../index'
+
+// A minimal sample plugin: active only when the component imports anything from
+// `@sample/pkg`, and lowers a `demo(...)` call to a neutral `helper-call` node.
+// This is exactly the shape a first-party / userland package would register.
+const samplePlugin: LoweringPlugin = {
+  name: 'sample-demo',
+  prepare(metadata) {
+    const active = metadata.imports.some(i => i.source === '@sample/pkg' && !i.isTypeOnly)
+    if (!active) return null
+    return (callee, args) =>
+      callee.kind === 'identifier' && callee.name === 'demo'
+        ? { kind: 'helper-call', helper: 'demo', args }
+        : null
+  },
+}
+
+function metadataImporting(source: string): IRMetadata {
+  return {
+    imports: [{ source, isTypeOnly: false, specifiers: [] }],
+  } as unknown as IRMetadata
+}
+
+const demoCall = { kind: 'identifier', name: 'demo' } as ParsedExpr
+const otherCall = { kind: 'identifier', name: 'other' } as ParsedExpr
+const arg = { kind: 'literal', value: 'x', literalType: 'string' } as ParsedExpr
+
+// Keep the global registry clean between tests (the sample must not leak into
+// other suites that assert on the registered set).
+afterEach(() => {
+  const remaining = getLoweringPlugins().filter(p => p.name !== 'sample-demo')
+  __resetLoweringPluginsForTest(remaining)
+})
+
+describe('lowering-plugin registry', () => {
+  test('registerLoweringPlugin adds the plugin; getLoweringPlugins returns a copy', () => {
+    registerLoweringPlugin(samplePlugin)
+    const plugins = getLoweringPlugins()
+    expect(plugins.some(p => p.name === 'sample-demo')).toBe(true)
+    // Mutating the returned array can't corrupt the registry.
+    ;(plugins as LoweringPlugin[]).length = 0
+    expect(getLoweringPlugins().some(p => p.name === 'sample-demo')).toBe(true)
+  })
+
+  test('re-registering the same name replaces, not duplicates (idempotent)', () => {
+    registerLoweringPlugin(samplePlugin)
+    registerLoweringPlugin(samplePlugin)
+    expect(getLoweringPlugins().filter(p => p.name === 'sample-demo')).toHaveLength(1)
+  })
+
+  test('prepare gates on the plugin recognising its own import', () => {
+    registerLoweringPlugin(samplePlugin)
+    // Active: component imports from @sample/pkg.
+    expect(prepareLoweringMatchers(metadataImporting('@sample/pkg'))).toHaveLength(1)
+    // Inactive: unrelated import → no matcher, so the adapter skips it entirely.
+    expect(prepareLoweringMatchers(metadataImporting('react'))).toHaveLength(0)
+  })
+
+  test('a bound matcher lowers a recognised call to its neutral node', () => {
+    registerLoweringPlugin(samplePlugin)
+    const [matcher] = prepareLoweringMatchers(metadataImporting('@sample/pkg'))
+    expect(matcher(demoCall, [arg])).toEqual({ kind: 'helper-call', helper: 'demo', args: [arg] })
+    // A call the plugin doesn't recognise is declined (→ generic lowering).
+    expect(matcher(otherCall, [arg])).toBeNull()
+  })
+
+  test('matchLoweringCall tries all registered plugins for the metadata', () => {
+    registerLoweringPlugin(samplePlugin)
+    expect(matchLoweringCall(demoCall, [arg], metadataImporting('@sample/pkg'))).toEqual({
+      kind: 'helper-call',
+      helper: 'demo',
+      args: [arg],
+    })
+    // No plugin recognises this metadata → null (the built-in queryHref plugin
+    // is inactive here — a `react` import isn't `@barefootjs/client`).
+    expect(matchLoweringCall(demoCall, [arg], metadataImporting('react'))).toBeNull()
+  })
+})
+
+describe('built-in plugins are applied by default', () => {
+  // `queryHref` is a built-in plugin the compiler registers on load — no
+  // `registerLoweringPlugin` call in the test. Importing `@barefootjs/jsx`
+  // (the import above) is what registers it, so it's present here for free.
+  const queryHrefCall = { kind: 'identifier', name: 'queryHref' } as ParsedExpr
+  const base = { kind: 'literal', value: '/x', literalType: 'string' } as ParsedExpr
+  const tagValue = { kind: 'literal', value: 'a', literalType: 'string' } as ParsedExpr
+  const paramsObj = {
+    kind: 'object-literal',
+    raw: '{ tag: "a" }',
+    properties: [{ key: 'tag', shorthand: false, value: tagValue }],
+  } as ParsedExpr
+
+  function importingQueryHref(): IRMetadata {
+    return {
+      imports: [
+        {
+          source: '@barefootjs/client',
+          isTypeOnly: false,
+          specifiers: [{ name: 'queryHref', alias: null, isDefault: false, isNamespace: false }],
+        },
+      ],
+    } as unknown as IRMetadata
+  }
+
+  test('queryHref is registered without any explicit registerLoweringPlugin call', () => {
+    expect(getLoweringPlugins().some(p => p.name === 'queryHref')).toBe(true)
+  })
+
+  test('a queryHref(base, { … }) call lowers to a neutral guard-list on the `query` helper', () => {
+    const node = matchLoweringCall(queryHrefCall, [base, paramsObj], importingQueryHref())
+    expect(node).toEqual({
+      kind: 'guard-list',
+      helper: 'query',
+      base,
+      triples: [{ guard: null, key: 'tag', value: tagValue }],
+    })
+  })
+
+  test('the built-in stays inert when the component does not import queryHref', () => {
+    expect(matchLoweringCall(queryHrefCall, [base, paramsObj], metadataImporting('react'))).toBeNull()
+  })
+})

package/src/__tests__/primitive-resolver-alias.test.ts

@@ -100,6 +100,29 @@ describe('reactive primitive resolver — alias fidelity (checker path)', () =>
     expect(ctx.signals[0].initialValue).toBe('0')
   })
 
+  test('import { createSearchParams as csp }: csp() is recognized as an env signal', () => {
+    // #2057: the env-signal factory resolves through the same alias path as
+    // createSignal. The signal must be tagged `envReader` and carry the
+    // as-written callee (`csp`) so client/SSR emit `csp()`, not the canonical
+    // name — and validateReactiveFactoryCalls must NOT raise BF110 for it.
+    const filePath = path.resolve(CLIENT_DIR, '../.bench-env-alias-test.tsx')
+    const source = `
+      import { createSearchParams as csp } from '@barefootjs/client'
+      export function SortLabel() {
+        const [sp] = csp()
+        return <p>{sp().get('sort') ?? 'none'}</p>
+      }
+    `
+    const program = programFor(filePath, source)
+    const ctx = analyzeComponent(source, filePath, undefined, program)
+    expect(ctx.signals).toHaveLength(1)
+    expect(ctx.signals[0].getter).toBe('sp')
+    expect(ctx.signals[0].envReader).toBe('search')
+    expect(ctx.signals[0].envFactory).toBe('csp')
+    // No spurious BF110 (unrecognized reactive factory) for the aliased call.
+    expect(ctx.errors.some(e => e.code === 'BF110')).toBe(false)
+  })
+
   test('user-defined function named createSignal is NOT misclassified without checker', () => {
     // Without a checker, the fast path still matches by name. This
     // documents the limitation — the fast path is optimistic. A shared

package/src/__tests__/query-href-recognition.test.ts

@@ -0,0 +1,58 @@
+/**
+ * `queryHrefLocalNames` — recognises the `queryHref` import (incl. aliases) so
+ * adapters can gate the `queryHref(base, { … })` → query-helper lowering (#2042).
+ */
+import { describe, test, expect } from 'bun:test'
+import { compileJSX, queryHrefLocalNames, type ComponentIR } from '../index'
+import { TestAdapter } from '../adapters/test-adapter'
+
+function metadata(src: string): ComponentIR['metadata'] {
+  const result = compileJSX(src.trimStart(), 'T.tsx', { adapter: new TestAdapter(), outputIR: true })
+  const ir = JSON.parse(result.files.find(f => f.type === 'ir')!.content) as ComponentIR
+  return ir.metadata
+}
+
+describe('queryHrefLocalNames (#2042)', () => {
+  test('recognises a plain queryHref import', () => {
+    const md = metadata(`
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string }) {
+  return <a href={queryHref(props.base, {})}>x</a>
+}
+`)
+    expect([...queryHrefLocalNames(md)]).toEqual(['queryHref'])
+  })
+
+  test('binds to the local alias', () => {
+    const md = metadata(`
+'use client'
+import { queryHref as qh } from '@barefootjs/client'
+export function P(props: { base: string }) {
+  return <a href={qh(props.base, {})}>x</a>
+}
+`)
+    expect([...queryHrefLocalNames(md)]).toEqual(['qh'])
+  })
+
+  test('recognises the @barefootjs/client/runtime re-export too', () => {
+    // `queryHref` is exported from both entries; importing from the runtime entry
+    // must still enable SSR lowering, else the call hits BF101.
+    const md = metadata(`
+'use client'
+import { queryHref } from '@barefootjs/client/runtime'
+export function P(props: { base: string }) {
+  return <a href={queryHref(props.base, {})}>x</a>
+}
+`)
+    expect([...queryHrefLocalNames(md)]).toEqual(['queryHref'])
+  })
+
+  test('is empty when not imported', () => {
+    const md = metadata(`
+'use client'
+export function P() { return <a href="/x">x</a> }
+`)
+    expect(queryHrefLocalNames(md).size).toBe(0)
+  })
+})

package/src/__tests__/serialize-parsed-expr.test.ts

@@ -0,0 +1,204 @@
+import { describe, expect, test } from 'bun:test'
+import { parseExpression, serializeParsedExpr, freeVarsInBody } from '../expression-parser'
+
+/**
+ * `serializeParsedExpr` emits the minimal JSON the runtime evaluator (Go
+ * `eval.go` `EvalNode` / Perl `Evaluator.pm` `evaluate`) reads. These tests pin
+ * the field contract (only evaluator-read fields per kind) and the purity gate
+ * (folded / non-expression kinds → null). `freeVarsInBody` pins the captured
+ * free-var set used to build the evaluator's `base_env`. (#2018)
+ */
+
+/** Parse a callback-body source and serialize it to the evaluator JSON object. */
+function evalJSON(src: string): unknown {
+  const s = serializeParsedExpr(parseExpression(src))
+  return s === null ? null : JSON.parse(s)
+}
+
+describe('serializeParsedExpr', () => {
+  test('literal carries only `value` (no literalType / raw)', () => {
+    expect(evalJSON('42')).toEqual({ kind: 'literal', value: 42 })
+    expect(evalJSON("'hi'")).toEqual({ kind: 'literal', value: 'hi' })
+    expect(evalJSON('true')).toEqual({ kind: 'literal', value: true })
+    expect(evalJSON('null')).toEqual({ kind: 'literal', value: null })
+  })
+
+  test('identifier carries `name`', () => {
+    expect(evalJSON('acc')).toEqual({ kind: 'identifier', name: 'acc' })
+  })
+
+  test('reducer body: binary over member projection', () => {
+    expect(evalJSON('acc + item.price')).toEqual({
+      kind: 'binary',
+      op: '+',
+      left: { kind: 'identifier', name: 'acc' },
+      // member carries object + property only (no `computed`).
+      right: {
+        kind: 'member',
+        object: { kind: 'identifier', name: 'item' },
+        property: 'price',
+      },
+    })
+  })
+
+  test('comparator body: 3-way ternary', () => {
+    expect(evalJSON('a > b ? 1 : a < b ? -1 : 0')).toEqual({
+      kind: 'conditional',
+      test: { kind: 'binary', op: '>', left: { kind: 'identifier', name: 'a' }, right: { kind: 'identifier', name: 'b' } },
+      consequent: { kind: 'literal', value: 1 },
+      alternate: {
+        kind: 'conditional',
+        test: { kind: 'binary', op: '<', left: { kind: 'identifier', name: 'a' }, right: { kind: 'identifier', name: 'b' } },
+        consequent: { kind: 'unary', op: '-', argument: { kind: 'literal', value: 1 } },
+        alternate: { kind: 'literal', value: 0 },
+      },
+    })
+  })
+
+  test('filter body: logical over member access', () => {
+    expect(evalJSON('item.done && item.priority > 3')).toEqual({
+      kind: 'logical',
+      op: '&&',
+      left: { kind: 'member', object: { kind: 'identifier', name: 'item' }, property: 'done' },
+      right: {
+        kind: 'binary',
+        op: '>',
+        left: { kind: 'member', object: { kind: 'identifier', name: 'item' }, property: 'priority' },
+        right: { kind: 'literal', value: 3 },
+      },
+    })
+  })
+
+  test('index-access carries object + index', () => {
+    expect(evalJSON('item[i]')).toEqual({
+      kind: 'index-access',
+      object: { kind: 'identifier', name: 'item' },
+      index: { kind: 'identifier', name: 'i' },
+    })
+  })
+
+  test('builtin call carries callee + args', () => {
+    expect(evalJSON('Math.max(a, b)')).toEqual({
+      kind: 'call',
+      callee: { kind: 'member', object: { kind: 'identifier', name: 'Math' }, property: 'max' },
+      args: [
+        { kind: 'identifier', name: 'a' },
+        { kind: 'identifier', name: 'b' },
+      ],
+    })
+  })
+
+  test('template literal: string + expression parts', () => {
+    expect(evalJSON('`n=${acc + 1}`')).toEqual({
+      kind: 'template-literal',
+      parts: [
+        { type: 'string', value: 'n=' },
+        { type: 'expression', expr: { kind: 'binary', op: '+', left: { kind: 'identifier', name: 'acc' }, right: { kind: 'literal', value: 1 } } },
+      ],
+    })
+  })
+
+  test('map body: object literal carries key + value (no keyKind / shorthand)', () => {
+    expect(evalJSON('({ id: item.id, n: item.n })')).toEqual({
+      kind: 'object-literal',
+      properties: [
+        { key: 'id', value: { kind: 'member', object: { kind: 'identifier', name: 'item' }, property: 'id' } },
+        { key: 'n', value: { kind: 'member', object: { kind: 'identifier', name: 'item' }, property: 'n' } },
+      ],
+    })
+  })
+
+  test('array literal', () => {
+    expect(evalJSON('[item.a, item.b]')).toEqual({
+      kind: 'array-literal',
+      elements: [
+        { kind: 'member', object: { kind: 'identifier', name: 'item' }, property: 'a' },
+        { kind: 'member', object: { kind: 'identifier', name: 'item' }, property: 'b' },
+      ],
+    })
+  })
+
+  test('purity gate: a folded method call in the body → null', () => {
+    // `.toUpperCase()` folds to `array-method`, outside the evaluator surface.
+    expect(serializeParsedExpr(parseExpression('item.name.toUpperCase()'))).toBeNull()
+    // A higher-order call (`.filter`) likewise.
+    expect(serializeParsedExpr(parseExpression('item.tags.filter(t => t)'))).toBeNull()
+    // An unsupported shape.
+    expect(serializeParsedExpr(parseExpression('a instanceof B'))).toBeNull()
+  })
+
+  test('purity gate: a folded subtree anywhere poisons the whole body', () => {
+    expect(serializeParsedExpr(parseExpression('acc + item.name.toUpperCase()'))).toBeNull()
+  })
+
+  test('purity gate: a non-builtin call is refused (evaluator would read it as nil)', () => {
+    // Bare function call — not on the evaluator allowlist.
+    expect(serializeParsedExpr(parseExpression('foo(item)'))).toBeNull()
+    // Method call on a value — generic `call` with a non-Math member callee.
+    expect(serializeParsedExpr(parseExpression('item.compute(2)'))).toBeNull()
+    // `parseInt` etc. are not the allowlisted `Number`/`String`/`Boolean`.
+    expect(serializeParsedExpr(parseExpression('parseInt(item.s)'))).toBeNull()
+    // A computed builtin reference the evaluator rejects (`Math['max']`).
+    expect(serializeParsedExpr(parseExpression("Math['max'](a, b)"))).toBeNull()
+  })
+
+  test('allowlisted builtins serialize (Math.* / String / Number / Boolean)', () => {
+    expect(serializeParsedExpr(parseExpression('Math.floor(item.x)'))).not.toBeNull()
+    expect(serializeParsedExpr(parseExpression('String(item.n)'))).not.toBeNull()
+    expect(serializeParsedExpr(parseExpression('Number(item.s)'))).not.toBeNull()
+    expect(serializeParsedExpr(parseExpression('Boolean(item.s)'))).not.toBeNull()
+  })
+
+  test('a computed member value carries `computed: true` (plain access omits it)', () => {
+    // `row['price']` folds to a computed `member`; the flag is preserved so a
+    // computed member stays distinguishable. (`row.price` carries no `computed`.)
+    expect(evalJSON("row['price']")).toEqual({
+      kind: 'member',
+      object: { kind: 'identifier', name: 'row' },
+      property: 'price',
+      computed: true,
+    })
+    expect(evalJSON('row.price')).toEqual({
+      kind: 'member',
+      object: { kind: 'identifier', name: 'row' },
+      property: 'price',
+    })
+  })
+})
+
+describe('freeVarsInBody', () => {
+  test('collects refs minus the callback params, sorted & deduped', () => {
+    const body = parseExpression('acc + item.price + acc')
+    expect(freeVarsInBody(body, new Set(['acc', 'item']))).toEqual([])
+    expect(freeVarsInBody(body, new Set(['acc']))).toEqual(['item'])
+    expect(freeVarsInBody(body, new Set())).toEqual(['acc', 'item'])
+  })
+
+  test('captures an outer free var referenced in the body (base_env source)', () => {
+    // `taxRate` is neither param — it must travel as a captured free var.
+    const body = parseExpression('acc + item.price * taxRate')
+    expect(freeVarsInBody(body, new Set(['acc', 'item']))).toEqual(['taxRate'])
+  })
+
+  test('member property names are not references; object-literal values are', () => {
+    // `price` (property) is not a free var; `item` and `factor` are.
+    const body = parseExpression('({ total: item.price * factor })')
+    expect(freeVarsInBody(body, new Set()).sort()).toEqual(['factor', 'item'])
+  })
+
+  test('template + index + call cover their value positions', () => {
+    // `Math` is a builtin callee resolved syntactically by the evaluator — it
+    // is NOT captured (it would emit an undefined `$Math` / `.Math` base_env
+    // entry). The real refs `k`, `n`, `row` are.
+    const body = parseExpression('`${row[k]}-${Math.abs(n)}`')
+    expect(freeVarsInBody(body, new Set())).toEqual(['k', 'n', 'row'])
+  })
+
+  test('builtin call callees (Math.<fn> / String / Number / Boolean) are not captured', () => {
+    // Each builtin is resolved syntactically by the evaluator, so its
+    // identifier must not enter base_env (Copilot review #2031). The
+    // arguments, however, ARE real references.
+    const body = parseExpression('Math.max(a, factor) + Number(label) + String(x) + Boolean(flag)')
+    expect(freeVarsInBody(body, new Set(['a']))).toEqual(['factor', 'flag', 'label', 'x'])
+  })
+})