@barefootjs/go-template 0.16.0 → 0.17.0

package/src/adapter/analysis/component-tree.ts

@@ -0,0 +1,174 @@
+/**
+ * IR component-tree analysis for the Go html/template adapter.
+ *
+ * Pure structural walks over the IR — no adapter instance state, no rendering.
+ * Only the two entry points (`hasClientInteractivity`,
+ * `findNestedComponents`) are exported; the recursive collectors stay
+ * module-internal.
+ */
+
+import type {
+  ComponentIR,
+  IRNode,
+  IRElement,
+  IRFragment,
+  IRConditional,
+  IRLoop,
+  IRIfStatement,
+  IRComponent,
+} from '@barefootjs/jsx'
+
+import type { NestedComponentInfo } from '../lib/types.ts'
+
+/**
+ * Does the component need client JS? True when it has reactive state
+ * (signals), effects, onMounts, any event handler in the tree, or any
+ * child component (which needs the parent's hydration).
+ */
+export function hasClientInteractivity(ir: ComponentIR): boolean {
+  if (ir.metadata.signals.length > 0) return true
+  if (ir.metadata.effects.length > 0) return true
+  if (ir.metadata.onMounts.length > 0) return true
+  if (hasEventsInTree(ir.root)) return true
+  // Child components need the parent's hydration.
+  if (findChildComponentNames(ir.root).size > 0) return true
+  return false
+}
+
+/** Recursively check if any element in the tree has events. */
+function hasEventsInTree(node: IRNode): boolean {
+  if (node.type === 'element') {
+    const element = node as IRElement
+    if (element.events.length > 0) return true
+    for (const child of element.children) {
+      if (hasEventsInTree(child)) return true
+    }
+  } else if (node.type === 'fragment') {
+    const fragment = node as IRFragment
+    for (const child of fragment.children) {
+      if (hasEventsInTree(child)) return true
+    }
+  } else if (node.type === 'conditional') {
+    const cond = node as IRConditional
+    if (hasEventsInTree(cond.whenTrue)) return true
+    if (cond.whenFalse && hasEventsInTree(cond.whenFalse)) return true
+  } else if (node.type === 'loop') {
+    const loop = node as IRLoop
+    for (const child of loop.children) {
+      if (hasEventsInTree(child)) return true
+    }
+  } else if (node.type === 'if-statement') {
+    const ifStmt = node as IRIfStatement
+    if (hasEventsInTree(ifStmt.consequent)) return true
+    if (ifStmt.alternate && hasEventsInTree(ifStmt.alternate)) return true
+  }
+  return false
+}
+
+/** Find all child component names used in the IR tree. */
+function findChildComponentNames(node: IRNode): Set<string> {
+  const names = new Set<string>()
+  collectChildComponentNames(node, names)
+  return names
+}
+
+function collectChildComponentNames(node: IRNode, names: Set<string>): void {
+  if (node.type === 'component') {
+    const comp = node as IRComponent
+    names.add(comp.name)
+  } else if (node.type === 'element') {
+    const element = node as IRElement
+    for (const child of element.children) {
+      collectChildComponentNames(child, names)
+    }
+  } else if (node.type === 'fragment') {
+    const fragment = node as IRFragment
+    for (const child of fragment.children) {
+      collectChildComponentNames(child, names)
+    }
+  } else if (node.type === 'conditional') {
+    const cond = node as IRConditional
+    collectChildComponentNames(cond.whenTrue, names)
+    if (cond.whenFalse) {
+      collectChildComponentNames(cond.whenFalse, names)
+    }
+  } else if (node.type === 'loop') {
+    const loop = node as IRLoop
+    for (const child of loop.children) {
+      collectChildComponentNames(child, names)
+    }
+  } else if (node.type === 'if-statement') {
+    const ifStmt = node as IRIfStatement
+    collectChildComponentNames(ifStmt.consequent, names)
+    if (ifStmt.alternate) {
+      collectChildComponentNames(ifStmt.alternate, names)
+    }
+  }
+}
+
+/**
+ * Find all nested components (loops with `childComponent`). Returns extended
+ * info that includes whether the component comes from a dynamic (signal) array
+ * loop vs a static one.
+ */
+export function findNestedComponents(node: IRNode): NestedComponentInfo[] {
+  const result: NestedComponentInfo[] = []
+  collectNestedComponents(node, result)
+  return result
+}
+
+function collectNestedComponents(node: IRNode, result: NestedComponentInfo[]): void {
+  if (node.type === 'loop') {
+    const loop = node as IRLoop
+    if (loop.childComponent) {
+      if (!result.some(c => c.name === loop.childComponent!.name)) {
+        const hasBodyChildren = loop.childComponent.children.length > 0
+        result.push({
+          ...loop.childComponent,
+          isDynamic: !loop.isStaticArray,
+          isPropDerived: !!loop.isPropDerivedArray,
+          loopKey: loop.key ?? undefined,
+          loopParam: loop.param ?? undefined,
+          bodyChildren: hasBodyChildren ? loop.childComponent.children : undefined,
+          loopArray: loop.array,
+          loopArrayParsed: loop.arrayParsed,
+          loopMarkerId: loop.markerId,
+          loopItemType: loop.itemType,
+        })
+      }
+    }
+    for (const child of loop.children) {
+      collectNestedComponents(child, result)
+    }
+  } else if (node.type === 'element') {
+    const element = node as IRElement
+    for (const child of element.children) {
+      collectNestedComponents(child, result)
+    }
+  } else if (node.type === 'fragment') {
+    const fragment = node as IRFragment
+    for (const child of fragment.children) {
+      collectNestedComponents(child, result)
+    }
+  } else if (node.type === 'conditional') {
+    const cond = node as IRConditional
+    collectNestedComponents(cond.whenTrue, result)
+    if (cond.whenFalse) {
+      collectNestedComponents(cond.whenFalse, result)
+    }
+  } else if (node.type === 'if-statement') {
+    const stmt = node as IRIfStatement
+    collectNestedComponents(stmt.consequent, result)
+    if (stmt.alternate) {
+      collectNestedComponents(stmt.alternate, result)
+    }
+  } else if (node.type === 'component') {
+    // JSX children passed to an imported component render via a companion
+    // define with the PARENT's data, so a keyed loop nested inside them needs
+    // its `<Name>s` slice on THIS component's props like any other nested loop.
+    const comp = node as IRComponent
+    for (const child of comp.children) {
+      collectNestedComponents(child, result)
+    }
+  }
+}

package/src/adapter/emit-context.ts

@@ -0,0 +1,59 @@
+/**
+ * The contract extracted emit modules depend on instead of the concrete
+ * `GoTemplateAdapter`.
+ *
+ * The Go adapter's lowering is deeply mutually recursive (expression ↔
+ * condition ↔ rendering), so a module pulled out still needs to call back into
+ * the shared per-compile state and the recursive entry points. `GoEmitContext`
+ * is that seam: extracted free functions take it as their first argument, and
+ * the adapter — which owns the state and implements the entry points — passes
+ * `this`. Modules depend on this narrow interface, so they stay unit-testable
+ * against a stub.
+ *
+ * Keep this surface minimal: add a member only when an extracted module
+ * genuinely needs it, so the seam documents the real cross-module coupling.
+ */
+
+import type { ParsedExpr } from '@barefootjs/jsx'
+
+import type { CompileState } from './lib/compile-state.ts'
+
+export interface GoEmitContext {
+  /** Per-compile mutable state (signals, consts, type tables, errors, …). */
+  readonly state: CompileState
+
+  /**
+   * Lower a JS expression to its Go-template form (the core recursive entry).
+   * `preParsed` reuses an already-built tree instead of re-parsing `jsExpr`.
+   */
+  convertExpressionToGo(
+    jsExpr: string,
+    out?: { parsed?: ParsedExpr },
+    preParsed?: ParsedExpr,
+  ): string
+
+  /**
+   * Lower a JS condition to a Go-template bool + any hoisted preamble.
+   * `preParsed` reuses an already-built tree instead of re-parsing `jsCondition`.
+   */
+  convertConditionToGo(
+    jsCondition: string,
+    preParsed?: ParsedExpr,
+  ): { condition: string; preamble: string }
+
+  /** Extract the prop name from a `props.X ?? …` initial value, or null. */
+  extractPropNameFromInitialValue(initialValue: string): string | null
+
+  /**
+   * Parse a signal-time initial value `props.X ?? <literal>` into the source
+   * prop name and the Go-formatted fallback, or null when it isn't that shape.
+   */
+  extractPropFallback(initialValue: string): { propName: string; goFallback: string } | null
+
+  /**
+   * Inline a module string const by name as a Go double-quoted literal
+   * (`"<escaped>"`), or null when the name is not such a const (loop vars and
+   * outer-loop params are excluded).
+   */
+  resolveModuleStringConst(name: string): string | null
+}

package/src/adapter/expr/helper-inline.ts

@@ -0,0 +1,274 @@
+/**
+ * Inlining of component-scope arrow-const helpers at a call site.
+ *
+ * When a JSX expression calls a local `const f = (a) => …` helper, the Go
+ * adapter has no function to emit — it inlines the helper body with the call
+ * args substituted for the params, so the result lowers like any inline
+ * expression. The substitution is scope-blind, so the guards here reject bodies
+ * where a param replacement could be wrong.
+ */
+
+import { type ParsedExpr } from '@barefootjs/jsx'
+
+import type { GoEmitContext } from '../emit-context.ts'
+
+/**
+ * Inline a call to a local arrow-const helper.
+ *
+ * @param callParsed the call's already-built `ParsedExpr`. Must be a `call`
+ *   node; inlining is declined without it.
+ * @returns the substituted body tree, or null when the expression isn't such a
+ *   call or the body isn't substitution-safe (nested functions, helper-calling
+ *   helpers, spread args, …)
+ */
+export function inlineLocalHelperCall(
+  ctx: GoEmitContext,
+  jsExpr: string,
+  callParsed?: ParsedExpr,
+): ParsedExpr | null {
+  if (ctx.state.localHelperNames.size === 0) return null
+  // Fast path: skip unless the expression begins with a known helper name
+  // applied as a call (`<helper>(`); the real shape check is the tree
+  // inspection below.
+  const head = /^\s*([A-Za-z_$][\w$]*)\s*\(/.exec(jsExpr)
+  if (!head || !ctx.state.localHelperNames.has(head[1])) return null
+
+  if (!callParsed || callParsed.kind !== 'call' || callParsed.callee.kind !== 'identifier') {
+    return null
+  }
+  const calleeName = callParsed.callee.name
+  if (!ctx.state.localHelperNames.has(calleeName)) return null
+
+  const fnConst = ctx.state.localConstants.find(
+    c => c.name === calleeName && !c.isModule && c.parsed,
+  )
+  const arrow = fnConst?.parsed
+  if (!arrow || arrow.kind !== 'arrow') return null
+  if (arrow.params.length !== callParsed.args.length) return null
+
+  // The body must be a lowerable `ParsedExpr` — an `unsupported` body (e.g. a
+  // nested function / regex outside the narrow surface) refuses here.
+  const body = arrow.body
+  if (!body || body.kind === 'unsupported') return null
+
+  // Don't half-inline a helper that calls another local helper.
+  if (bodyCallsLocalHelper(ctx, body)) return null
+
+  // Refuse a body containing a method call (`x.foo(…)`). The structural body
+  // tree models it as a generic `call`, but `parseExpression` (which the rest
+  // of the lowering is keyed to) folds the string / array method family
+  // (`.replace`, `.includes`, `.filter`, …) into specialised `array-method` /
+  // `higher-order` nodes — so lowering this tree directly would diverge.
+  // (`x()` with an identifier callee — `params()` — is fine.)
+  if (bodyHasMethodCall(body)) return null
+
+  const subs = new Map<string, ParsedExpr>()
+  for (let i = 0; i < arrow.params.length; i++) {
+    subs.set(arrow.params[i], callParsed.args[i])
+  }
+  // Reject bodies where a param name appears as an object shorthand key
+  // (`{ k }`, which can't be rewritten to `{ (arg) }`).
+  if (!isSubstituteSafeBody(body, new Set(subs.keys()))) return null
+  return substituteHelperParams(body, subs)
+}
+
+/**
+ * Guard for `substituteHelperParams`: an `object-literal` lowers opaquely from
+ * its `raw` source string, so a param referenced ANYWHERE inside it survives
+ * un-substituted — a shorthand key (`{ p }`) or a value position (`{ x: p }`,
+ * `{ x: f(p) }`) — and would emit the param's original name instead of the call
+ * arg. A body is substitute-safe only when no object literal it contains
+ * references any param.
+ */
+function isSubstituteSafeBody(body: ParsedExpr, paramNames: ReadonlySet<string>): boolean {
+  // True when `n`'s subtree references any param (handling object-literal
+  // shorthand keys, which carry the param name on the key rather than a value).
+  const referencesParam = (n: ParsedExpr): boolean => {
+    if (n.kind === 'identifier') return paramNames.has(n.name)
+    if (n.kind === 'object-literal') {
+      return n.properties.some(
+        p => (p.shorthand && paramNames.has(p.key)) || referencesParam(p.value),
+      )
+    }
+    let hit = false
+    forEachValueChild(n, c => {
+      if (referencesParam(c)) hit = true
+    })
+    return hit
+  }
+
+  let safe = true
+  const visit = (n: ParsedExpr): void => {
+    if (!safe) return
+    if (n.kind === 'object-literal') {
+      // The whole object literal lowers from `raw`; a param mentioned anywhere
+      // inside can't be substituted — decline the body.
+      if (referencesParam(n)) safe = false
+      return
+    }
+    forEachValueChild(n, visit)
+  }
+  visit(body)
+  return safe
+}
+
+/**
+ * True when `body` contains a call to a *local* (component-scope) arrow helper
+ * const — the signal that inlining `body` here would only push the problem to
+ * another un-lowered helper (e.g. `sortHref`'s body calls `hrefFor`).
+ */
+function bodyCallsLocalHelper(ctx: GoEmitContext, body: ParsedExpr): boolean {
+  let found = false
+  const visit = (n: ParsedExpr): void => {
+    if (found) return
+    if (n.kind === 'call' && n.callee.kind === 'identifier') {
+      const name = n.callee.name
+      if (ctx.state.localConstants.some(c => c.name === name && !c.isModule && c.containsArrow)) {
+        found = true
+        return
+      }
+    }
+    forEachValueChild(n, visit)
+  }
+  visit(body)
+  return found
+}
+
+/**
+ * True when `body` contains a method call (`x.foo(…)` — a `call` whose callee
+ * is a `member`); such a body must not be lowered from this tree. See the guard
+ * in `inlineLocalHelperCall` for why.
+ */
+function bodyHasMethodCall(body: ParsedExpr): boolean {
+  let found = false
+  const visit = (n: ParsedExpr): void => {
+    if (found) return
+    if (n.kind === 'call' && n.callee.kind === 'member') {
+      found = true
+      return
+    }
+    forEachValueChild(n, visit)
+  }
+  visit(body)
+  return found
+}
+
+/**
+ * Re-build `body` with each identifier named in `subs` replaced by the
+ * substitution's `ParsedExpr` subtree. The substitution is the arg subtree
+ * itself, so operator precedence survives without parenthesisation (the tree
+ * *is* the precedence). Non-value identifier positions — the property NAME in
+ * `a.b`, a plain `{ k: … }` key — are not visited, so a param sharing a name
+ * with a member or key is left untouched.
+ */
+export function substituteHelperParams(
+  body: ParsedExpr,
+  subs: ReadonlyMap<string, ParsedExpr>,
+): ParsedExpr {
+  const go = (n: ParsedExpr): ParsedExpr => {
+    switch (n.kind) {
+      case 'identifier': {
+        const sub = subs.get(n.name)
+        return sub !== undefined ? sub : n
+      }
+      // `object-literal` / `unsupported` lower from their `raw` string, and a
+      // `regex` carries its exact source text — re-lowering structured children
+      // has no effect, so leave as-is (a param inside an object literal is
+      // rejected by the shorthand guard upstream).
+      case 'literal':
+      case 'object-literal':
+      case 'unsupported':
+      case 'regex':
+        return n
+      case 'member':
+        return { ...n, object: go(n.object) }
+      case 'index-access':
+        return { ...n, object: go(n.object), index: go(n.index) }
+      case 'call':
+        return { ...n, callee: go(n.callee), args: n.args.map(go) }
+      case 'binary':
+        return { ...n, left: go(n.left), right: go(n.right) }
+      case 'logical':
+        return { ...n, left: go(n.left), right: go(n.right) }
+      case 'unary':
+        return { ...n, argument: go(n.argument) }
+      case 'conditional':
+        return { ...n, test: go(n.test), consequent: go(n.consequent), alternate: go(n.alternate) }
+      case 'template-literal':
+        return {
+          ...n,
+          parts: n.parts.map(p =>
+            p.type === 'expression' ? { type: 'expression', expr: go(p.expr) } : p,
+          ),
+        }
+      case 'array-literal':
+        return { ...n, elements: n.elements.map(go) }
+      case 'arrow':
+        // A nested arrow's params shadow any same-named outer helper param, but
+        // the inline body-method guard (`bodyHasMethodCall`) already declined
+        // bodies whose substitution could be wrong; re-lower the body verbatim.
+        return { ...n, body: go(n.body) }
+      case 'array-method':
+        // `.flat` carries no `args`; the generic variant does. Re-lower both
+        // `object` and any `args`.
+        return n.method === 'flat'
+          ? { ...n, object: go(n.object) }
+          : { ...n, object: go(n.object), args: n.args.map(go) }
+    }
+  }
+  return go(body)
+}
+
+/**
+ * Visit the value-position `ParsedExpr` children of `n` (the property name in
+ * `a.b` and a plain `{ k: v }` key are skipped — they aren't value positions;
+ * `object-literal` is handled by the caller because its shorthand keys carry a
+ * guard).
+ */
+function forEachValueChild(n: ParsedExpr, visit: (c: ParsedExpr) => void): void {
+  switch (n.kind) {
+    case 'identifier':
+    case 'literal':
+    case 'unsupported':
+    case 'object-literal':
+    case 'regex':
+      return
+    case 'member':
+      visit(n.object)
+      return
+    case 'index-access':
+      visit(n.object)
+      visit(n.index)
+      return
+    case 'call':
+      visit(n.callee)
+      n.args.forEach(visit)
+      return
+    case 'binary':
+    case 'logical':
+      visit(n.left)
+      visit(n.right)
+      return
+    case 'unary':
+      visit(n.argument)
+      return
+    case 'conditional':
+      visit(n.test)
+      visit(n.consequent)
+      visit(n.alternate)
+      return
+    case 'template-literal':
+      for (const p of n.parts) if (p.type === 'expression') visit(p.expr)
+      return
+    case 'array-literal':
+      n.elements.forEach(visit)
+      return
+    case 'arrow':
+      visit(n.body)
+      return
+    case 'array-method':
+      visit(n.object)
+      if (n.method !== 'flat') n.args.forEach(visit)
+      return
+  }
+}

package/src/adapter/expr/url-builder.ts

@@ -0,0 +1,123 @@
+/**
+ * Go lowering of helper calls to template expressions. Renders backend-neutral
+ * `LoweringNode`s produced by registered lowering plugins (#2057) — one uniform
+ * path for both userland plugins and built-ins like `queryHref` (a default plugin
+ * that lowers to `bf_query`, #2042). Every node funnels through
+ * `renderLoweringNode`, which maps a logical helper id to its Go helper; the
+ * adapter carries no per-API recognition branch of its own.
+ */
+
+import {
+  type LoweringNode,
+  type ParsedExpr,
+  parseExpression,
+  stringifyParsedExpr,
+} from '@barefootjs/jsx'
+
+import type { GoEmitContext } from '../emit-context.ts'
+import { wrapIfMultiToken } from '../lib/go-emit.ts'
+
+/** Logical helper id → Go template helper name. */
+const GO_HELPER_NAMES: Record<string, string> = { query: 'bf_query' }
+
+const BOOL_COMPARISON_OPS: ReadonlySet<string> = new Set([
+  '==', '===', '!=', '!==', '<', '>', '<=', '>=',
+])
+
+/**
+ * Lower an expression to a Go *bool* for `bf_query`'s `include` argument. A
+ * comparison / negation / bool-literal already yields a bool
+ * (`convertConditionToGo`); anything else is JS string-truthiness, lowered to
+ * `ne <value> ""`. The arg must be a real bool — `bf_query` type-asserts it, so
+ * Go-template truthiness (`{{if x}}`) is not enough.
+ *
+ * The `ne <value> ""` path models *string* truthiness, which is the query
+ * domain: `queryHref` values are strings (`QueryParamValue`). A guard on a
+ * non-string value is outside the supported surface; the type-assert on
+ * `bf_query`'s include arg surfaces it as a build error rather than silently
+ * mis-including. (#2041 review.)
+ */
+function lowerUrlGuard(ctx: GoEmitContext, g: ParsedExpr): string {
+  // Comparisons, `!x`, and bool literals lower to a Go bool via the condition
+  // lowering. `&&` / `||` do NOT qualify: Go's `and`/`or` return one of their
+  // operands (a string for a truthiness guard like `tag && other`), not a
+  // bool — so they take the truthiness-wrap path below, yielding
+  // `ne (and …) ""`, an actual bool.
+  const isBoolShape =
+    (g.kind === 'binary' && BOOL_COMPARISON_OPS.has(g.op)) ||
+    (g.kind === 'unary' && g.op === '!') ||
+    (g.kind === 'literal' && g.literalType === 'boolean')
+  if (isBoolShape) {
+    return ctx.convertConditionToGo(stringifyParsedExpr(g), g).condition
+  }
+  const valueGo = wrapIfMultiToken(ctx.convertExpressionToGo(stringifyParsedExpr(g), undefined, g))
+  return `ne ${valueGo} ""`
+}
+
+/**
+ * Lower a helper call to a Go template expression, or null when no registered
+ * plugin recognises it (→ the generic lowering). Matchers — including the
+ * built-in `queryHref` plugin (#2042) — are bound to the component metadata at
+ * init (`ctx.state.loweringMatchers`), so this is one uniform loop with no
+ * per-API branch.
+ *
+ * Cheap-out: no active matchers → null; else reuse `preParsed` when it's already
+ * a call, otherwise a regex pre-filter gates the parse so non-call expressions
+ * never pay for `parseExpression`.
+ */
+export function lowerRegisteredCall(
+  ctx: GoEmitContext,
+  jsExpr: string,
+  preParsed?: ParsedExpr,
+): string | null {
+  const matchers = ctx.state.loweringMatchers
+  if (matchers.length === 0) return null
+
+  let call: ParsedExpr | undefined = preParsed?.kind === 'call' ? preParsed : undefined
+  if (!call) {
+    if (!/^\s*[A-Za-z_$][\w$]*\s*\(/.test(jsExpr)) return null
+    const parsed = parseExpression(jsExpr)
+    if (parsed.kind !== 'call') return null
+    call = parsed
+  }
+
+  for (const matcher of matchers) {
+    const node = matcher(call.callee, call.args)
+    if (!node) continue
+    const rendered = renderLoweringNode(ctx, node)
+    if (rendered !== null) return rendered
+  }
+  return null
+}
+
+/**
+ * Render a backend-neutral lowering node to a Go template expression, or null
+ * when the node's `helper` has no Go mapping — the caller then declines
+ * (generic lowering → BF101), rather than emitting the raw helper id, which
+ * would be invalid Go. Adapters must switch on `helper`; an unknown one is not
+ * rendered.
+ */
+function renderLoweringNode(ctx: GoEmitContext, node: LoweringNode): string | null {
+  const helper = GO_HELPER_NAMES[node.helper]
+  if (!helper) return null
+  const lowerExpr = (n: ParsedExpr): string =>
+    ctx.convertExpressionToGo(stringifyParsedExpr(n), undefined, n)
+  if (node.kind === 'helper-call') {
+    const args = node.args.map(a => wrapIfMultiToken(lowerExpr(a)))
+    return [helper, ...args].join(' ')
+  }
+  // guard-list — `queryHref`-shaped. Inclusion mirrors the client exactly, where
+  // every param value is a STRING (`QueryParamValue`): bf_query drops an
+  // included-but-empty value and appends array members.
+  //   - plain `key: v` (guard null)        → `(true) "key" v`
+  //   - conditional `key: cond ? a : <omit>` → `(<cond>) "key" a`, where the
+  //     non-empty check is done by bf_query, not folded into the guard.
+  const parts: string[] = [wrapIfMultiToken(lowerExpr(node.base))]
+  for (const t of node.triples) {
+    const includeGo = t.guard === null ? 'true' : lowerUrlGuard(ctx, t.guard)
+    parts.push(`(${includeGo})`)
+    parts.push(JSON.stringify(t.key))
+    parts.push(wrapIfMultiToken(lowerExpr(t.value)))
+  }
+  return `${helper} ${parts.join(' ')}`
+}