@barefootjs/jsx 0.15.2 → 0.17.0

package/src/types.ts

@@ -4,7 +4,25 @@
  * JSX-independent intermediate representation for multi-backend support.
  */
 
-import type { ParsedExpr, ParsedStatement, SortComparator } from './expression-parser.ts'
+import type { ParsedExpr, ParsedStatement } from './expression-parser.ts'
+
+/**
+ * Loop-hoisted sort comparator for the `.sort().map()` / `.toSorted().map()`
+ * pattern (#2018 P5). Carries the generic comparator `arrow` (params + body)
+ * that the SSR adapter serializes to the runtime evaluator (eval-first) or, for
+ * a `localeCompare` comparator the evaluator can't model, recovers a structured
+ * comparator from via `sortComparatorFromArrow`. The `paramA` / `paramB` / `raw`
+ * fields round-trip the comparator to native JS for the client / CSR path
+ * (`(paramA, paramB) => raw`), so the client is untouched.
+ */
+export type IRLoopSort = {
+  // Always the comparator arrow itself — narrowed so consumers read
+  // `.params` / `.body` without a defensive `kind` check or non-null assertion.
+  arrow: Extract<ParsedExpr, { kind: 'arrow' }>
+  paramA: string
+  paramB: string
+  raw: string
+}
 
 // =============================================================================
 // Source Location (for Error Reporting)
@@ -323,6 +341,20 @@ export interface IRExpression {
   expr: string
   /** Pre-transformed expr with destructured prop refs rewritten to _p.xxx (for client JS templates). */
   templateExpr?: string
+  /**
+   * Structured parse of `expr` (`parseExpression(expr.trim())`), attached once
+   * during IR construction so SSR adapters emit from the tree instead of each
+   * re-parsing the string at emit time (and so a multi-adapter build parses it
+   * once, not per adapter). Plain serializable data.
+   *
+   * OPTIONAL by design — consumers MUST fall back to parsing `expr` when it is
+   * missing. It is absent for an empty/whitespace `expr`, and may also be
+   * absent for a node the IR-build walk doesn't reach (the walk is best-effort;
+   * under-coverage is a missed optimization, never a behavioural change). When
+   * present, an unparsable expression is a `{ kind: 'unsupported' }` node (the
+   * adapter's own support gate handles it).
+   */
+  parsed?: ParsedExpr
   typeInfo: TypeInfo | null
   reactive: boolean
   slotId: string | null
@@ -347,6 +379,13 @@ export interface IRConditional {
   condition: string
   /** Pre-transformed condition with destructured prop refs rewritten to _p.xxx. */
   templateCondition?: string
+  /**
+   * Structured parse of `condition` (`parseExpression(condition.trim())`),
+   * attached during IR construction so adapters lower the condition from the
+   * tree instead of re-parsing the string. Optional/best-effort — see
+   * `IRExpression.parsed`; consumers fall back to parsing `condition`.
+   */
+  parsedCondition?: ParsedExpr
   conditionType: TypeInfo | null
   reactive: boolean
   whenTrue: IRNode
@@ -404,6 +443,14 @@ export interface IRLoop {
    */
   method?: 'flatMap'
   array: string
+  /**
+   * Structured parse of `array` (`parseExpression(array.trim())`), attached
+   * during IR construction so adapters lower the loop's array from the tree
+   * instead of re-parsing the string (e.g. the Go adapter's scalar-literal
+   * loop typing). Optional/best-effort — mirrors `IRExpression.parsed`;
+   * consumers fall back to parsing `array`.
+   */
+  arrayParsed?: ParsedExpr
   /** Pre-transformed array expr with destructured prop refs rewritten to _p.xxx. */
   templateArray?: string
   arrayType: TypeInfo | null
@@ -471,14 +518,16 @@ export interface IRLoop {
    * When present, the loop renders with an if-condition wrapping each iteration.
    * Example: todos.filter(t => !t.done).map(...) stores { param: 't', predicate: ParsedExpr, raw: '!t.done' }
    *
-   * For block-body filters like:
+   * Block-body filters like
    *   filter(t => { const f = filter(); if (f === 'active') return !t.done; return true })
-   * The blockBody field contains the parsed statements.
+   * are normalized to a single boolean `predicate` expression at IR-build time
+   * (#2040, `foldBlockToExpr` + `predicateTernaryToLogical` in `jsx-to-ir`), so
+   * adapters only ever see the unified expression form — there is no separate
+   * block-statement shape to lower.
    */
   filterPredicate?: {
     param: string
-    predicate?: ParsedExpr        // Expression body
-    blockBody?: ParsedStatement[] // Block body (mutually exclusive with predicate)
+    predicate?: ParsedExpr        // Boolean predicate expression (folded from any block body)
     raw: string  // Original string for error messages
   }
 
@@ -487,14 +536,14 @@ export interface IRLoop {
    * When present, the loop array is sorted before iteration.
    * Example: todos.sort((a, b) => a.priority - b.priority).map(...)
    *
-   * The structured shape carries enough info for both adapters to
-   * emit the same `bf_sort` / `bf->sort` call (`SortComparator` is
-   * defined in `expression-parser.ts` because the standalone
-   * `array-method` IR variant uses the same type). The loop-hoist
-   * path lifts a comparator off a sibling `array-method` node
-   * during `jsx-to-ir.ts` chain detection — see `extractSortComparator`.
+   * The {@link IRLoopSort} struct carries the generic comparator `arrow`
+   * (params + body) the SSR adapter serializes to the runtime evaluator
+   * (eval-first; `sortComparatorFromArrow` fallback for `localeCompare`), plus
+   * the param names + raw body for the client JS round-trip. Lifted off the
+   * `.sort()` callback during `jsx-to-ir.ts` chain detection — see
+   * `extractSortComparator`. (#2018 P5)
    */
-  sortComparator?: SortComparator
+  sortComparator?: IRLoopSort
 
   /**
    * When both filter and sort are chained, indicates the order of operations.
@@ -746,6 +795,13 @@ export interface IRIfStatement {
   condition: string
   /** Pre-transformed condition with destructured prop refs rewritten to _p.xxx. */
   templateCondition?: string
+  /**
+   * Structured parse of `condition` (`parseExpression(condition.trim())`),
+   * attached during IR construction so adapters lower the condition from the
+   * tree instead of re-parsing the string. Optional/best-effort — see
+   * `IRExpression.parsed`; consumers fall back to parsing `condition`.
+   */
+  parsedCondition?: ParsedExpr
   /** The JSX return in the then branch */
   consequent: IRNode
   /** The else branch: either another IRIfStatement (else if) or IRNode (final else) */
@@ -839,6 +895,14 @@ export interface ExpressionAttr {
   /** `expr` with destructured prop refs rewritten to `_p.xxx`, for SSR
    *  template inlining. Absent when no rewrite was needed. */
   templateExpr?: string
+  /**
+   * Structured parse of `expr` (`parseExpression(expr.trim())`), attached
+   * during IR construction so adapters lower the attribute value from the tree
+   * instead of re-parsing the string (often several times per attribute).
+   * Optional/best-effort — see `IRExpression.parsed`; consumers fall back to
+   * parsing `expr`.
+   */
+  parsed?: ParsedExpr
   /** Set when the producer peeled an `expr || undefined` boolean-presence
    *  pattern; adapters fold this back into `(expr) || undefined` at emit. */
   presenceOrUndefined?: boolean
@@ -873,6 +937,16 @@ export interface SpreadAttr {
   kind: 'spread'
   expr: string
   templateExpr?: string
+  /**
+   * Structured parse of `expr` (`parseExpression(expr.trim())`), attached
+   * during IR construction so adapters lower the spread bag from the tree
+   * instead of re-parsing the string with `ts.createSourceFile`. Optional /
+   * best-effort — mirrors `ExpressionAttr.parsed`: it may be absent (a node the
+   * attach walk misses, or an empty `expr`), and parsing may yield
+   * `{ kind: 'unsupported' }`, which adapters treat as unlowerable and handle
+   * via their existing non-conditional spread paths (or BF101).
+   */
+  parsed?: ParsedExpr
   /**
    * Component-scoped, stable slot ID assigned at IR-build time for
    * adapters that need to plumb the spread bag through a structured
@@ -1039,6 +1113,14 @@ export interface SignalInfo {
   getter: string
   setter: string | null
   initialValue: string
+  /**
+   * `initialValue` parsed into a structured tree (Roadmap A). Attached
+   * best-effort by the analyzer so adapters can lower a literal initial value
+   * (e.g. `useState(['a', 'b'])`) from structure instead of re-parsing the
+   * string with `ts.createSourceFile`. Absent when the shape isn't supported;
+   * consumers fall back to parsing `initialValue`.
+   */
+  parsed?: ParsedExpr
   /** Initial value with TypeScript type annotations preserved, for .tsx output */
   typedInitialValue?: string
   type: TypeInfo
@@ -1075,6 +1157,26 @@ export interface SignalInfo {
   isModule?: boolean
   /** When true, the declaration carries an `export` keyword. */
   isExported?: boolean
+  /**
+   * Request-scoped environment-signal key when this signal was produced by an
+   * env-signal factory (`createSearchParams()` → `'search'`), rather than by
+   * `createSignal`. Set structurally by the analyzer (#2057) — the getter is a
+   * normal reactive getter (so it lands in the fold purity oracle for free, no
+   * name allow-list), but its *value* is a request-scoped reader with methods
+   * (`.get(key)`), which adapters lower to their per-request reader object
+   * instead of a plain template field. This flag is how adapters recognise an
+   * env signal from structure instead of matching the import name.
+   */
+  envReader?: string
+  /**
+   * For an env signal (`envReader` set), the exact callee text of its factory
+   * call as written — `'createSearchParams'`, an alias (`'csp'` for
+   * `import { createSearchParams as csp }`), or a namespace access
+   * (`'bf.createSearchParams'`). Backends that re-emit the declaration (client
+   * JS, JSX/Hono SSR) emit `<envFactory>()` so the call resolves to the binding
+   * actually in scope, not a hardcoded canonical name (#2057).
+   */
+  envFactory?: string
 }
 
 export interface MemoInfo {
@@ -1082,6 +1184,52 @@ export interface MemoInfo {
   computation: string
   /** Computation with TypeScript type annotations preserved, for .tsx output */
   typedComputation?: string
+  /**
+   * Structured parse of the memo's BODY as a single value expression, computed
+   * once at analysis time. Lets adapters pattern-match the memo's shape on the
+   * structured tree instead of re-parsing `computation` with their own AST walks
+   * / regexes.
+   *
+   * Set for an expression-bodied arrow (`() => <body>`) whose body
+   * `parseExpression` supports, AND — since #2040 — for a block-bodied memo
+   * (`() => { … }`) whose statements `foldBlockToExpr` can normalize to one
+   * expression (`let`-inline + value `if` / early `return` → ternary). A block
+   * the fold refuses (imperative residue) or a shape `parseExpression` can't
+   * represent leaves `parsed` undefined, so consumers must still fall back to
+   * `parsedBlock` / `computation` when it's missing. NOTE: a present `parsed`
+   * therefore no longer implies an expression-bodied arrow.
+   */
+  parsed?: ParsedExpr
+  /**
+   * Whether the memo's effective body is a template literal (`() => `…`` or a
+   * block body whose first `return` is one), classified once at analysis time
+   * from the real arrow AST. Lets the Go adapter pick the `string` field type
+   * without re-parsing `computation` with `ts.createSourceFile`. A template
+   * literal — including a no-substitution `` `plain` `` — folds to a plain
+   * string `ParsedExpr` literal, losing the backtick distinction, so this is a
+   * dedicated flag rather than a `parsed.kind` check.
+   */
+  bodyIsTemplateLiteral?: boolean
+  /**
+   * A block-bodied memo's statements, parsed best-effort (tolerant: a statement
+   * the parser can't represent is omitted). Lets the Go adapter pattern-match
+   * block-body memo shapes — e.g. the `const k = getter(); if (!k) return CONST`
+   * guard — on the structured statements instead of re-parsing `computation`
+   * with `ts.createSourceFile`. Absent for expression-bodied memos (those carry
+   * `parsed` instead) and when the arrow has no block body.
+   */
+  parsedBlock?: ParsedStatement[]
+  /**
+   * Whether {@link parsedBlock} represents EVERY statement of the block (true)
+   * or the tolerant parser omitted at least one it couldn't represent (false).
+   * A consumer that must reason about the whole block — e.g. one that bails on
+   * any statement it doesn't recognise (the template-literal memo lowering) —
+   * reads this and falls back when it's `false`, since omitted statements are
+   * otherwise invisible. Consumers that scan for a recognised prefix and ignore
+   * the rest (the guard-and-return-const lowering) can disregard it. Only set
+   * when `parsedBlock` is.
+   */
+  parsedBlockComplete?: boolean
   type: TypeInfo
   deps: string[]
   loc: SourceLocation
@@ -1282,6 +1430,17 @@ export interface FunctionInfo {
 export interface ConstantInfo {
   name: string
   value?: string
+  /**
+   * `value` parsed into a structured tree (Roadmap A). Attached best-effort by
+   * the analyzer (parsed from the parenthesised value so a bare object literal
+   * — which TS reads as a block at statement position — resolves to an
+   * `object-literal` rather than failing). Lets adapters lower a constant value
+   * (e.g. a module-scope record's `{ … }`) from structure instead of
+   * re-parsing the string with `ts.createSourceFile`. Absent when the constant
+   * has no `value` string (e.g. an inlined-JSX const) or when the analyzer
+   * couldn't structure it (best-effort — consumers fall back to the string).
+   */
+  parsed?: ParsedExpr
   /** Value with TypeScript type annotations preserved, for .tsx output */
   typedValue?: string
   valueBranches?: string[]

package/src/__tests__/flatmap-support.test.ts

@@ -1,218 +0,0 @@
-/**
- * BarefootJS Compiler - .flatMap() support (#1554 / #1448 Tier C)
- *
- * flatMap callbacks containing JSX must compile to valid JS for
- * JavaScript runtime adapters (Hono, CSR). Template-language adapters
- * (Go, Mojo) do not support flatMap — the workaround is .map() + Fragment.
- */
-
-import { describe, test, expect } from 'bun:test'
-import { compileJSX } from '../compiler'
-import { TestAdapter } from '../adapters/test-adapter'
-import { HonoAdapter } from '../../../../packages/adapter-hono/src/adapter/hono-adapter'
-
-const adapter = new TestAdapter()
-
-describe('.flatMap() — simple arrow with array literal', () => {
-  test('arrow body returning [<A/>, <B/>] compiles to flatMap with valid JS', () => {
-    const source = `
-      'use client'
-
-      export function DL(props: { items: { term: string; def: string }[] }) {
-        return (
-          <dl>
-            {props.items.flatMap((item, i) => [
-              <dt key={\`dt-\${i}\`}>{item.term}</dt>,
-              <dd key={\`dd-\${i}\`}>{item.def}</dd>
-            ])}
-          </dl>
-        )
-      }
-    `
-    const result = compileJSX(source, 'DL.tsx', { adapter })
-    expect(result.errors).toHaveLength(0)
-
-    const clientJs = result.files.find(f => f.type === 'clientJs')!
-    expect(clientJs.content).toContain('.flatMap(')
-    expect(clientJs.content).toContain('.join(')
-    // Template contains compiled HTML (not raw JSX)
-    expect(clientJs.content).toContain('item.term')
-    expect(clientJs.content).toContain('item.def')
-  })
-})
-
-describe('.flatMap() — complex block body with conditional returns', () => {
-  test('block body with variable JSX and conditional returns produces valid client JS', () => {
-    const source = `
-      'use client'
-
-      export function Timeline(props: { frames: { label: string }[] }) {
-        return (
-          <div>
-            {props.frames.flatMap((frame, i) => {
-              const panel = (
-                <ResizablePanel key={\`p-\${i}\`}>
-                  {i + 1}
-                </ResizablePanel>
-              )
-              if (i === 0) return [panel]
-              return [<ResizableHandle key={\`h-\${i}\`} />, panel]
-            })}
-          </div>
-        )
-      }
-    `
-    const result = compileJSX(source, 'Timeline.tsx', { adapter })
-    expect(result.errors).toHaveLength(0)
-
-    const clientJs = result.files.find(f => f.type === 'clientJs')!
-    expect(clientJs.content).toContain('.flatMap(')
-    expect(clientJs.content).toContain('.join(')
-    // JSX should be compiled to renderChild calls, not raw JSX
-    expect(clientJs.content).toContain("renderChild('ResizablePanel'")
-    expect(clientJs.content).toContain("renderChild('ResizableHandle'")
-    expect(clientJs.content).not.toContain('<ResizablePanel')
-    expect(clientJs.content).not.toContain('<ResizableHandle')
-  })
-})
-
-describe('.flatMap() — Hono adapter', () => {
-  test('Hono preserves JSX in flatMap callback', () => {
-    const source = `
-      'use client'
-
-      export function Timeline(props: { frames: { label: string }[] }) {
-        return (
-          <div>
-            {props.frames.flatMap((frame, i) => {
-              const panel = (
-                <ResizablePanel key={\`p-\${i}\`}>
-                  {i + 1}
-                </ResizablePanel>
-              )
-              if (i === 0) return [panel]
-              return [<ResizableHandle key={\`h-\${i}\`} />, panel]
-            })}
-          </div>
-        )
-      }
-    `
-    const result = compileJSX(source, 'Timeline.tsx', { adapter: new HonoAdapter() })
-    expect(result.errors).toHaveLength(0)
-
-    const markedTemplate = result.files.find(f => f.type === 'markedTemplate')!
-    // Hono should use flatMap (not map)
-    expect(markedTemplate.content).toContain('.flatMap(')
-    // Hono preserves JSX natively
-    expect(markedTemplate.content).toContain('<ResizablePanel')
-    expect(markedTemplate.content).toContain('<ResizableHandle')
-  })
-
-  test('simple flatMap arrow with array literal works in Hono', () => {
-    const source = `
-      'use client'
-
-      export function DL(props: { items: { term: string; def: string }[] }) {
-        return (
-          <dl>
-            {props.items.flatMap((item, i) => [
-              <dt key={\`dt-\${i}\`}>{item.term}</dt>,
-              <dd key={\`dd-\${i}\`}>{item.def}</dd>
-            ])}
-          </dl>
-        )
-      }
-    `
-    const result = compileJSX(source, 'DL.tsx', { adapter: new HonoAdapter() })
-    expect(result.errors).toHaveLength(0)
-
-    const markedTemplate = result.files.find(f => f.type === 'markedTemplate')!
-    expect(markedTemplate.content).toContain('.flatMap(')
-  })
-})
-
-describe('.flatMap() — single JSX return (same as map)', () => {
-  test('flatMap with single JSX return compiles like map', () => {
-    const source = `
-      'use client'
-
-      export function List(props: { items: string[] }) {
-        return (
-          <ul>
-            {props.items.flatMap((item, i) => (
-              <li key={i}>{item}</li>
-            ))}
-          </ul>
-        )
-      }
-    `
-    const result = compileJSX(source, 'List.tsx', { adapter })
-    expect(result.errors).toHaveLength(0)
-
-    const clientJs = result.files.find(f => f.type === 'clientJs')!
-    expect(clientJs.content).toContain('.flatMap(')
-    // Template contains compiled HTML template literal, not raw JSX
-    expect(clientJs.content).toContain('data-key')
-  })
-})
-
-describe('.flatMap() — variable-assigned result (#1554 comment)', () => {
-  test('flatMap stored in const, then used in JSX, compiles without raw JSX', () => {
-    const source = `
-      'use client'
-
-      export function TimelineBar(props: { items: string[] }) {
-        const children = props.items.flatMap((item, i) => {
-          const panel = (
-            <ResizablePanel key={item} defaultSize={50} className="segment">
-              <span>{i + 1}</span>
-            </ResizablePanel>
-          )
-          if (i === 0) return [panel]
-          return [<ResizableHandle key={\`h-\${item}\`} />, panel]
-        })
-
-        return (
-          <ResizablePanelGroup direction="horizontal">
-            {children}
-          </ResizablePanelGroup>
-        )
-      }
-    `
-    const result = compileJSX(source, 'TimelineBar.tsx', { adapter })
-    expect(result.errors).toHaveLength(0)
-
-    const clientJs = result.files.find(f => f.type === 'clientJs')!
-    // flatMap should be used (not map)
-    expect(clientJs.content).toContain('.flatMap(')
-    // JSX should be compiled to renderChild calls, not raw JSX
-    expect(clientJs.content).toContain("renderChild('ResizablePanel'")
-    expect(clientJs.content).toContain("renderChild('ResizableHandle'")
-    expect(clientJs.content).not.toContain('<ResizablePanel')
-    expect(clientJs.content).not.toContain('<ResizableHandle')
-    // The raw const declaration should not appear in the init function
-    expect(clientJs.content).not.toContain('const children = ')
-  })
-
-  test('map() stored in const with JSX also gets inlined', () => {
-    const source = `
-      'use client'
-
-      export function List(props: { items: string[] }) {
-        const rendered = props.items.map((item, i) => (
-          <ListItem key={i} label={item} />
-        ))
-
-        return (
-          <ul>{rendered}</ul>
-        )
-      }
-    `
-    const result = compileJSX(source, 'List.tsx', { adapter })
-    expect(result.errors).toHaveLength(0)
-
-    const clientJs = result.files.find(f => f.type === 'clientJs')!
-    expect(clientJs.content).not.toContain('<ListItem')
-    expect(clientJs.content).not.toContain('const rendered = ')
-  })
-})