@barefootjs/go-template 0.18.4 → 0.18.7

package/src/adapter/analysis/static-child-loop-bake.ts

@@ -0,0 +1,119 @@
+/**
+ * Compile-time baking for a static-array `.map()` loop whose body is a
+ * single child component with a plain-value (non-JSX) prop set (#2208).
+ *
+ * `NewXxxProps`'s existing `staticWithoutBody` path (see
+ * `go-template-adapter.ts`'s `generateNewPropsFunction`) populates a static
+ * loop's child slices from `in.<Name>s` — data the CALLER (handler) must
+ * supply. When the loop's array source is itself a fully-static literal
+ * (`const items = [{ label: 'Alpha' }, ...]`, #2208), there is no caller
+ * input to wait for: every per-item prop value is already known at compile
+ * time. `analyzeBakeableStaticChildLoop` resolves that data — the resolved
+ * Go literal for each item's input fields, plus its `data-key` — so the
+ * constructor can emit `New<Name>Props(<Name>Input{ Field: "value", ... })`
+ * directly per item instead of ranging over `in.<Name>s`.
+ *
+ * Deliberately narrow: only scalar (string/number/boolean) prop values are
+ * baked. Anything else (an unresolvable expression, a destructured loop
+ * param, a JSX-valued prop) returns `null` so the caller keeps the existing
+ * `in.<Name>s`-driven path (or BF101 refusal) unchanged.
+ */
+
+import { evaluateStaticLiteral, parseExpression, resolveStaticLoopSource, type ConstantInfo, type IRProp, type ParsedExpr } from '@barefootjs/jsx'
+import { capitalizeFieldName } from '../lib/go-naming.ts'
+import { escapeGoString } from '../lib/go-emit.ts'
+
+export interface BakedStaticChildItem {
+  inputFields: Array<{ goField: string; goValue: string }>
+  dataKey: string | null
+}
+
+export interface BakedStaticChildLoop {
+  items: BakedStaticChildItem[]
+}
+
+/**
+ * Render a compile-time-known JS scalar as a Go template literal (a quoted
+ * string / bare number / `true`/`false`), or `null` for anything else
+ * (object, array, `null`, `undefined`) — those have no bare-literal Go
+ * template form at this layer. Exported for reuse by
+ * `static-element-loop-bake.ts` (#2224), which bakes item field values into
+ * a plain-element loop body's text/attr positions the same way this module
+ * bakes them into a child component's `Input{...}` constructor call.
+ */
+export function scalarToGoLiteral(value: unknown): string | null {
+  if (typeof value === 'string') return `"${escapeGoString(value)}"`
+  if (typeof value === 'number') return String(value)
+  if (typeof value === 'boolean') return value ? 'true' : 'false'
+  return null
+}
+
+/**
+ * Analyze one nested static child-component loop for bakeability. `props`
+ * are the child's JSX attrs (`IRLoopChildComponent.props`); `loopArrayParsed`
+ * / `loopParam` / `loopKey` come from the same `NestedComponentInfo` the
+ * caller already carries. Returns `null` when the shape isn't (yet)
+ * bakeable — the caller falls back to its existing behavior unchanged.
+ */
+export function analyzeBakeableStaticChildLoop(
+  nested: {
+    props: ReadonlyArray<{ name: string; value: IRProp['value']; isEventHandler: boolean }>
+    loopArrayParsed?: ParsedExpr
+    loopParam?: string
+    loopKey?: string
+  },
+  localConstants: ReadonlyArray<ConstantInfo>,
+  opts?: { isNameShadowed?: (name: string) => boolean },
+): BakedStaticChildLoop | null {
+  // A destructured loop param's raw pattern text starts with `{`/`[` (the
+  // synthesized single-identifier rewrite only applies to a SIMPLE param) —
+  // defer rather than mis-bind bindings under a pattern name.
+  if (!nested.loopParam || /^[{[]/.test(nested.loopParam)) return null
+
+  const staticItemsResult = resolveStaticLoopSource(nested.loopArrayParsed, localConstants, opts)
+  if (staticItemsResult === null) return null
+
+  const items: BakedStaticChildItem[] = []
+  for (const item of staticItemsResult) {
+    const bindings = new Map<string, unknown>([[nested.loopParam, item]])
+    const inputFields: Array<{ goField: string; goValue: string }> = []
+    for (const prop of nested.props) {
+      if (prop.isEventHandler) continue
+      if (prop.name.includes('-')) continue // no rest-bag at this compile-time-baked layer
+      const resolved = resolvePropValue(prop.value, bindings)
+      if (resolved === undefined) return null
+      const goValue = scalarToGoLiteral(resolved)
+      if (goValue === null) return null
+      inputFields.push({ goField: capitalizeFieldName(prop.name), goValue })
+    }
+    let dataKey: string | null = null
+    if (nested.loopKey) {
+      const keyExpr = parseExpression(nested.loopKey)
+      const keyResolved = evaluateStaticLiteral(keyExpr, bindings)
+      if (keyResolved === null) return null
+      dataKey = String(keyResolved.value)
+    }
+    items.push({ inputFields, dataKey })
+  }
+  return { items }
+}
+
+/** Resolves a prop's `AttrValue` to a plain JS value, or `undefined` if unresolvable. */
+function resolvePropValue(value: IRProp['value'], bindings: ReadonlyMap<string, unknown>): unknown {
+  switch (value.kind) {
+    case 'literal':
+      return value.value
+    case 'boolean-shorthand':
+    case 'boolean-attr':
+      return true
+    case 'expression': {
+      if (!value.parsed) return undefined
+      const resolved = evaluateStaticLiteral(value.parsed, bindings)
+      return resolved === null ? undefined : resolved.value
+    }
+    default:
+      // `template` / `spread` / `jsx-children`: not evaluated at this
+      // compile-time-baked layer — defer to the existing runtime path.
+      return undefined
+  }
+}

package/src/adapter/analysis/static-element-loop-bake.ts

@@ -0,0 +1,211 @@
+/**
+ * Compile-time UNROLL for a static-array `.map()` loop whose body is a
+ * PLAIN ELEMENT TREE (no child component) — go-only follow-up to #2208
+ * (#2224 shape 1). `html/template` has no slice/map literal syntax, so
+ * unlike the other 7 template adapters (which splice a serialized literal
+ * straight into the loop header — #2208), Go can't bind a compile-time-only
+ * array as a `{{range}}` source at all. Rather than synthesizing a Go struct
+ * type for the item shape (a materially bigger lift — see the #2224 issue
+ * body's "suggested fix direction"), this module verifies the loop body is
+ * fully foldable against every item and lets the caller
+ * (`go-template-adapter.ts`'s `renderLoop`) render the body once PER ITEM
+ * with every item-derived value substituted as a compile-time-known Go
+ * literal — no `{{range}}`, no struct, no field lookup, so no hidden runtime
+ * failure mode either (`html/template` resolves struct fields at EXECUTE
+ * time, not Go compile time).
+ *
+ * ACCEPTANCE CRITERIA — `analyzeBakeableStaticElementLoop` returns `null`
+ * (caller keeps today's BF101 refusal) unless ALL of the following hold:
+ *
+ *   - The loop has no child component (that shape is #2208's own baking
+ *     path — `analyzeBakeableStaticChildLoop`).
+ *   - Not a `.flatMap()` (`method: 'flatMap'` / `flatMapCallback` set) — an
+ *     item can fold to 0+ elements there, and a complex callback carries its
+ *     body out-of-band rather than in `children`; out of scope.
+ *   - The loop array resolves via `resolveStaticLoopSource` (a fully-static
+ *     array literal, inline or a named function-scope const;
+ *     `isNameShadowed`-checked — the SAME resolution #2208 already trusts
+ *     for the child-component shape).
+ *   - The callback param is a simple identifier (no array/object destructure
+ *     pattern).
+ *   - The callback does NOT bind an index parameter (`.map((item, i) =>
+ *     ...)`, or `.entries()`/`.keys()`/`Object.entries()`-style pre-map
+ *     iteration) — deliberately excluded from the evaluator surface even
+ *     though the index value is technically knowable at unroll time, to
+ *     keep the per-item binding set identical to #2208's (item-only).
+ *   - No `.filter()` / `.sort()` chained onto the `.map()` — out of scope.
+ *   - The body is neither multi-root (`bodyIsMultiRoot`) nor a whole-item
+ *     conditional (`bodyIsItemConditional`) — those need anchor-marker
+ *     machinery this pass doesn't attempt to reproduce per item.
+ *   - Every node anywhere in the body's IR tree is an `element`, `text`, or
+ *     `expression` — a nested `loop`, `conditional`, `component`, `slot`,
+ *     `fragment`, `if-statement`, `provider`, or `async` bails the WHOLE
+ *     loop (no partial unroll; a loud refusal beats silently wrong output).
+ *   - Every element attribute is `literal` / `boolean-attr` /
+ *     `boolean-shorthand`, or a plain `expression` whose parsed kind is one
+ *     of `identifier` / `member` / `index-access` / `literal`. An attribute
+ *     `template-literal` or `conditional` bypasses the Go adapter's normal
+ *     `convertExpressionToGo` emission path in its own attribute emitter
+ *     (it calls `renderParsedExpr` directly and splices the result assuming
+ *     adapter-specific self-wrapping conventions) — baking those would need
+ *     separate handling, deferred. `spread` / `jsx-children` attrs bail.
+ *   - Every dynamic text `expression` node (any parsed kind, INCLUDING
+ *     `template-literal` — text always funnels through
+ *     `convertExpressionToGo` uniformly, no bypass) resolves via
+ *     `evaluateStaticLiteral(expr.parsed, itemBindings)` to a scalar
+ *     (string/number/boolean) for EVERY item. A signal/memo call, a
+ *     reference to any non-item-static local (props, outer consts, an
+ *     enclosing loop's own param), an unresolvable nested method chain, or
+ *     a non-scalar (array/object) result bails the whole loop.
+ *
+ * Analysis only (mirrors `static-child-loop-bake.ts`): this module never
+ * emits Go syntax. `go-template-adapter.ts`'s `renderLoop` re-runs the SAME
+ * `evaluateStaticLiteral` call per item through its own
+ * `convertExpressionToGo` override once this analysis has cleared the whole
+ * loop, so the two passes can never disagree — this pass is pure validation,
+ * with no adapter-state side effects to roll back if it can't clear a loop.
+ */
+
+import {
+  evaluateStaticLiteral,
+  resolveStaticLoopSource,
+  type ConstantInfo,
+  type IRElement,
+  type IRLoop,
+  type IRNode,
+  type ParsedExpr,
+} from '@barefootjs/jsx'
+import { scalarToGoLiteral } from './static-child-loop-bake.ts'
+
+export interface BakedStaticElementLoop {
+  items: unknown[]
+}
+
+const ALLOWED_ATTR_EXPRESSION_KINDS: ReadonlySet<ParsedExpr['kind']> = new Set([
+  'identifier',
+  'member',
+  'index-access',
+  'literal',
+])
+
+type LoopShape = Pick<
+  IRLoop,
+  | 'childComponent'
+  | 'param'
+  | 'index'
+  | 'arrayParsed'
+  | 'children'
+  | 'filterPredicate'
+  | 'sortComparator'
+  | 'bodyIsMultiRoot'
+  | 'bodyIsItemConditional'
+  | 'paramBindings'
+  | 'iterationShape'
+  | 'objectIteration'
+  | 'method'
+  | 'flatMapCallback'
+>
+
+/**
+ * Analyze a `.map()` loop with a plain-element (non-component) body for
+ * static unrolling. Returns the resolved item values (ready for the caller
+ * to render the body once per item) or `null` when the shape isn't (yet)
+ * bakeable this way — see the acceptance criteria in the module docstring.
+ */
+export function analyzeBakeableStaticElementLoop(
+  loop: LoopShape,
+  localConstants: ReadonlyArray<ConstantInfo>,
+  opts?: { isNameShadowed?: (name: string) => boolean },
+): BakedStaticElementLoop | null {
+  if (loop.childComponent) return null // #2208's own path handles this shape.
+  // `.flatMap()`: an item can fold to 0+ elements, and a complex callback
+  // carries its body out-of-band (`flatMapCallback`, `children` left empty)
+  // rather than in `children` — either way this pass's per-item, single-
+  // element-tree model doesn't apply. Out of scope.
+  if (loop.method === 'flatMap' || loop.flatMapCallback) return null
+  if (!loop.param || /^[{[]/.test(loop.param)) return null
+  if (loop.index && loop.index !== '_') return null
+  if (loop.paramBindings && loop.paramBindings.length > 0) return null
+  if (loop.filterPredicate || loop.sortComparator) return null
+  if (loop.iterationShape || loop.objectIteration) return null
+  if (loop.bodyIsMultiRoot || loop.bodyIsItemConditional) return null
+  if (!isFoldableTree(loop.children)) return null
+
+  const items = resolveStaticLoopSource(loop.arrayParsed, localConstants, opts)
+  if (items === null) return null
+
+  for (const item of items) {
+    const bindings = new Map<string, unknown>([[loop.param, item]])
+    if (!allExpressionsFoldFor(loop.children, bindings)) return null
+  }
+  return { items }
+}
+
+/**
+ * Structural (item-independent) pass: every node kind in the subtree must be
+ * one this module knows how to fold, and every attribute value must be a
+ * shape `convertExpressionToGo`'s normal (non-bypassing) path handles.
+ */
+function isFoldableTree(nodes: readonly IRNode[]): boolean {
+  for (const node of nodes) {
+    switch (node.type) {
+      case 'text':
+      case 'expression':
+        continue // resolvability is checked per-item in `allExpressionsFoldFor`.
+      case 'element':
+        if (!isFoldableAttrs(node)) return false
+        if (!isFoldableTree(node.children)) return false
+        continue
+      default:
+        // 'conditional' | 'loop' | 'component' | 'slot' | 'fragment' |
+        // 'if-statement' | 'provider' | 'async' — none foldable per-item.
+        return false
+    }
+  }
+  return true
+}
+
+function isFoldableAttrs(element: IRElement): boolean {
+  for (const attr of element.attrs) {
+    if (attr.clientOnly) continue // omitted from SSR emission entirely.
+    switch (attr.value.kind) {
+      case 'literal':
+      case 'boolean-attr':
+      case 'boolean-shorthand':
+        continue
+      case 'expression':
+        if (!attr.value.parsed || !ALLOWED_ATTR_EXPRESSION_KINDS.has(attr.value.parsed.kind)) return false
+        continue
+      default:
+        // 'template' / 'spread' / 'jsx-children'
+        return false
+    }
+  }
+  return true
+}
+
+/** Per-item pass: every expression actually resolves to a bakeable scalar. */
+function allExpressionsFoldFor(nodes: readonly IRNode[], bindings: ReadonlyMap<string, unknown>): boolean {
+  for (const node of nodes) {
+    if (node.type === 'expression') {
+      if (node.clientOnly) continue // renders as an item-independent marker.
+      if (!node.parsed || !resolvesToScalar(node.parsed, bindings)) return false
+      continue
+    }
+    if (node.type === 'element') {
+      for (const attr of node.attrs) {
+        if (attr.clientOnly) continue
+        if (attr.value.kind !== 'expression') continue
+        if (!attr.value.parsed || !resolvesToScalar(attr.value.parsed, bindings)) return false
+      }
+      if (!allExpressionsFoldFor(node.children, bindings)) return false
+    }
+  }
+  return true
+}
+
+function resolvesToScalar(expr: ParsedExpr, bindings: ReadonlyMap<string, unknown>): boolean {
+  const resolved = evaluateStaticLiteral(expr, bindings)
+  if (resolved === null) return false
+  return scalarToGoLiteral(resolved.value) !== null
+}