@barefootjs/go-template 0.16.0 → 0.17.1

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(' ')}`
+}