@barefootjs/rust 0.1.0

package/src/adapter/lib/ir-scope.ts

@@ -0,0 +1,95 @@
+/**
+ * IR traversal helpers for the minijinja template adapter.
+ *
+ * Ported from `packages/adapter-xslate/src/adapter/lib/ir-scope.ts`.
+ * `resolveJsxChildrenProp` and `collectRootScopeNodes` are byte-identical
+ * (adapter-agnostic IR walks).
+ *
+ * `extractTopLevelIdentifiers` scans the RENDERED template text (rather than
+ * re-deriving free vars from the original JS AST) so it stays exactly in
+ * sync with whatever the emitter actually produced — but Jinja identifiers
+ * have no sigil (unlike Kolon's `$`, which made a trivially safe
+ * `\$([A-Za-z_]\w*)` scan possible): a bare word in the rendered text could
+ * be a genuine context-var reference, a `bf.` runtime-helper method name, a
+ * Jinja grammar keyword emitted by this adapter's own condition/ternary
+ * lowering (`if`/`else`/`is`/`not`/`and`/`or`/`none`/`true`/`false`), or
+ * content inside a single-quoted string literal. This helper makes the scan
+ * sound: it strips quoted string spans first, then matches identifier tokens
+ * NOT immediately preceded by a `.` (excluding dotted property/method names
+ * — the same exclusion the `$` sigil gave Kolon for free, since Kolon's
+ * regex only ever matched right after `$`), then drops the closed set of
+ * tokens this adapter's own codegen can emit that aren't context vars (`bf`
+ * and the Jinja keywords above). `memo/seed.ts` uses it to detect a
+ * constant lowering (no top-level identifier at all) that should keep the
+ * static ssr-defaults seed instead of an in-template `{% set %}`; scope
+ * AVAILABILITY itself is now the shared `computeSsrSeedPlan`'s job
+ * (packages/jsx/src/ssr-seed-plan.ts), not this module's (#2075).
+ */
+
+import type { IRNode, IRProp, IRIfStatement, IRFragment } from '@barefootjs/jsx'
+
+/** Tokens this adapter's own codegen can emit that are never context vars. */
+const NON_VAR_TOKENS = new Set([
+  'bf', 'if', 'else', 'is', 'not', 'and', 'or', 'in', 'none', 'true', 'false',
+  // `is defined` — the nullish-coalescing (`??`) lowering's Undefined guard
+  // (`expr/emitters.ts`'s `logical`, and the nullable-optional-prop
+  // attribute-omission test in `minijinja-adapter.ts`) emits this Jinja test
+  // keyword; it's never a context var.
+  'defined',
+])
+
+/**
+ * Extract the set of "top-level identifier" tokens from a rendered Jinja
+ * expression: bare words, excluding quoted-string content, dotted
+ * property/method names, and this adapter's own non-var keyword vocabulary.
+ * See the file header for why this replaces a direct `\w+` scan.
+ */
+export function extractTopLevelIdentifiers(jinjaExpr: string): string[] {
+  // Strip single-quoted string literals (this adapter only ever emits
+  // single-quoted string literals, backslash-escaped) so their content can't
+  // leak into the identifier scan.
+  const stripped = jinjaExpr.replace(/'(?:\\.|[^'\\])*'/g, ' ')
+  const out: string[] = []
+  for (const m of stripped.matchAll(/(?<!\.)\b([A-Za-z_]\w*)\b/g)) {
+    if (!NON_VAR_TOKENS.has(m[1])) out.push(m[1])
+  }
+  return out
+}
+
+/**
+ * Find the `children` prop's `jsx-children` payload. Narrowed via the
+ * AttrValue `kind` discriminator so adapter code stays type-safe if the IR
+ * shape evolves.
+ */
+export function resolveJsxChildrenProp(props: readonly IRProp[]): IRNode[] {
+  const prop = props.find(p => p.name === 'children')
+  if (!prop) return []
+  if (prop.value.kind !== 'jsx-children') return []
+  return prop.value.children
+}
+
+/**
+ * Collect the component's root scope element node(s) — the elements that
+ * become the rendered root and so carry `data-key` for a keyed loop item. A
+ * plain element root is itself; an `if-statement` (early-return) root
+ * contributes the top element of each branch, since exactly one renders at
+ * runtime. (#1297)
+ */
+export function collectRootScopeNodes(node: IRNode): Set<IRNode> {
+  const out = new Set<IRNode>()
+  const visit = (n: IRNode | null): void => {
+    if (!n) return
+    if (n.type === 'element') { out.add(n); return }
+    if (n.type === 'if-statement') {
+      const s = n as IRIfStatement
+      visit(s.consequent)
+      visit(s.alternate)
+      return
+    }
+    if (n.type === 'fragment') {
+      for (const c of (n as IRFragment).children) visit(c)
+    }
+  }
+  visit(node)
+  return out
+}

package/src/adapter/lib/minijinja-naming.ts

@@ -0,0 +1,85 @@
+/**
+ * Jinja2 identifier and dict-key conventions for the minijinja adapter.
+ *
+ * Near-verbatim port of the adapter-jinja equivalent
+ * (`packages/adapter-jinja/src/adapter/lib/jinja-naming.ts`, itself ported
+ * from the Kolon equivalent,
+ * `packages/adapter-xslate/src/adapter/lib/kolon-naming.ts`), adjusted for
+ * two real syntax divergences between Kolon and Jinja2. The RESERVED_WORDS
+ * set below is the IDENTICAL Python-keyword list adapter-jinja uses — kept
+ * unchanged rather than re-derived for minijinja, since the point is for the
+ * TS emitter and the Rust runtime's `mangle_ident` to agree on one set, not
+ * to find the minimal set minijinja's own grammar requires:
+ *
+ * 1. **Dict-literal keys are always quoted.** Kolon's hashref fat-comma
+ *    (`key => value`) auto-quotes a bareword key, so `kolonHashKey` only
+ *    quotes a non-identifier-safe name (`'data-slot'`). A Jinja/Python dict
+ *    LITERAL has no such bareword-key sugar — `{key: value}` means "look up
+ *    the *variable* `key` and use its value as the key", not the string
+ *    `"key"`. `minijinjaHashKey` therefore ALWAYS emits a quoted string literal,
+ *    identifier-safe or not — the one place this port is NOT a bare 1:1
+ *    syntax substitution, because treating it as one would silently change
+ *    dict keys into undefined-variable lookups.
+ * 2. **Reserved-word identifier mangling.** adapter-jinja verified empirically
+ *    against Python's Jinja 3.1 that most Python keywords (`class`, `import`,
+ *    `for`, …) parse fine as bare Jinja variable / loop-target names — Jinja
+ *    compiles every user template name to an internally-prefixed Python local
+ *    (`l_0_…`), so the template layer itself mostly sidesteps Python's own
+ *    reserved-word rules. minijinja 2.21 was re-verified compatible by the
+ *    orchestrator spike (same dict-literal / `{% set %}` / elif / `~` concat
+ *    / `| safe` behavior). The genuinely Jinja-reserved bare words are `not`
+ *    / `and` / `or` / `in` / `is` / `if` / `else` (grammar keywords) plus the
+ *    three constants `true` / `false` / `none` (rejected specifically as
+ *    assignment targets). Per the adapter plan, `minijinjaIdent` mangles the
+ *    FULL Python reserved-word list (a conservative superset of what Jinja's
+ *    grammar strictly requires) with a trailing-underscore suffix, trivial
+ *    and easy to keep in lock-step with the Rust runtime's identical rule
+ *    (`mangle_ident` in `render_named`, `packages/adapter-rust/runtime/src/backend_minijinja.rs`)
+ *    — the runtime applies the SAME mangling when it builds the per-render
+ *    context, so a prop/signal named e.g. `class` is threaded through as
+ *    context key `'class_'` on both sides.
+ */
+
+/**
+ * Escape a string for a Jinja/Python single-quoted literal: backslash first
+ * (so it doesn't double-escape the quote we add next), then the quote.
+ * Python string-literal escaping treats `\\` / `\'` identically to Perl's,
+ * so this is byte-identical to `escapeKolonSingleQuoted`.
+ */
+export function escapeMinijinjaSingleQuoted(s: string): string {
+  return s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")
+}
+
+/**
+ * Quote a dict-literal KEY for Jinja. UNLIKE Kolon's `kolonHashKey`, this
+ * always quotes — see the file header for why a bareword key would silently
+ * become a variable lookup instead of a string key.
+ */
+export function minijinjaHashKey(name: string): string {
+  return `'${escapeMinijinjaSingleQuoted(name)}'`
+}
+
+/**
+ * Python reserved words (the plan's list) that must not appear as a bare
+ * Jinja identifier — see the file header. Kept as the single source of
+ * truth, IDENTICAL to adapter-jinja's set; the Rust runtime's
+ * `mangle_ident` mirrors this exact set.
+ */
+const RESERVED_WORDS = new Set([
+  'if', 'else', 'for', 'in', 'is', 'not', 'and', 'or', 'none', 'true', 'false',
+  'import', 'from', 'class', 'def', 'pass', 'del', 'return', 'lambda', 'global',
+  'with', 'as', 'raise', 'try', 'except', 'finally', 'while', 'break',
+  'continue', 'elif', 'yield', 'assert', 'nonlocal',
+])
+
+/**
+ * Mangle a JS identifier (prop name, signal getter, loop param, …) into a
+ * Jinja-safe variable name: reserved words get a trailing `_` suffix,
+ * everything else passes through unchanged. Applied at every point the
+ * adapter emits a bare Jinja variable reference or `{% set %}` target —
+ * mirrors Kolon's `$name` sigil giving those references collision immunity
+ * for free; Jinja has no sigil, so the adapter mangles instead.
+ */
+export function minijinjaIdent(name: string): string {
+  return RESERVED_WORDS.has(name) ? `${name}_` : name
+}

package/src/adapter/lib/types.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared type aliases for the minijinja template adapter.
+ *
+ * Near-verbatim port of `packages/adapter-jinja/src/adapter/lib/types.ts`
+ * (itself extracted the way `packages/adapter-xslate/src/adapter/lib/types.ts`
+ * is): pure type declarations — no runtime behaviour — so the extracted emit
+ * modules and the main adapter share one definition rather than
+ * re-declaring the render context / options shape. The emitted template
+ * syntax is identical to adapter-jinja's (both target Jinja2-compatible
+ * syntax); only the render engine (minijinja, Rust) and identity fields
+ * differ, so the type names below keep their `Jinja*` shape rather than
+ * being renamed per-file.
+ */
+
+/** A template-primitive spec: expected call arity + the emit fn. */
+export interface PrimitiveSpec {
+  arity: number
+  emit: (args: string[]) => string
+}
+
+/**
+ * The adapter's IRNode render context. Like the Xslate adapter, Jinja2's
+ * lowering doesn't consume any render-position flags, so the Ctx is empty.
+ * Kept as a named alias so future flags can extend it without changing the
+ * `IRNodeEmitter` interface.
+ */
+export type JinjaRenderCtx = Record<string, never>
+
+export interface MinijinjaAdapterOptions {
+  /** Base path for client JS files (default: '/static/components/') */
+  clientJsBasePath?: string
+
+  /** Path to barefoot.js runtime (default: '/static/components/barefoot.js') */
+  barefootJsPath?: string
+}

package/src/adapter/memo/seed.ts

@@ -0,0 +1,135 @@
+/**
+ * In-template memo / context seeding for the minijinja template adapter.
+ *
+ * Near-verbatim port of `packages/adapter-jinja/src/adapter/memo/seed.ts`
+ * (itself ported from `packages/adapter-xslate/src/adapter/memo/seed.ts`).
+ * Free functions taking a `JinjaMemoContext` (built by the adapter's `memoCtx`
+ * getter) so the cluster depends only on the recursive expression entry, not
+ * the whole adapter class. These emit the `{% set x = ... %}` statements
+ * that let the body's bare `x` resolve to a derived signal/memo value or an
+ * active context value at SSR time.
+ *
+ * One deliberate behavioural IMPROVEMENT over the Kolon port: Kolon's `my`
+ * declares a NEW lexical, so `: my $x = … $x …;` reads the not-yet-assigned
+ * lexical on its own right-hand side — broken. Xslate therefore skips
+ * in-template seeding for a same-name signal/memo (a `refsSelf` guard in its
+ * `generateDerivedMemoSeed`). Jinja's `{% set %}` has no such shadowing
+ * hazard — `{% set x = x + 1 %}` resolves the right-hand `x` against the
+ * value ALREADY bound in the enclosing scope (verified empirically against
+ * Python's Jinja 3.1: `env.from_string("{% set x = x + 1 %}{{ x }}").render(x=5)`
+ * → `"6"`, not an error or a stale `5`; `{% set %}` inside `{% for %}` was
+ * independently re-verified against minijinja 2.21 by the orchestrator
+ * spike). This adapter therefore seeds a
+ * same-name signal/memo too, which is strictly more correct — the seed then
+ * re-derives from the already-bound prop instead of leaving the render var
+ * on its static (possibly per-callsite-wrong) default. No self-ref guard is
+ * ported for this reason.
+ */
+
+import {
+  type ComponentIR,
+  type ContextConsumer,
+  collectContextConsumers,
+  computeSsrSeedPlan,
+  materializeGetterCalls,
+} from '@barefootjs/jsx'
+
+import type { JinjaMemoContext } from '../emit-context.ts'
+import { extractTopLevelIdentifiers } from '../lib/ir-scope.ts'
+import { minijinjaIdent, escapeMinijinjaSingleQuoted } from '../lib/minijinja-naming.ts'
+
+/** Jinja literal for a context-consumer's `createContext` default. */
+export function contextDefaultJinja(c: ContextConsumer): string {
+  const d = c.defaultValue
+  if (d === null || d === undefined) return 'none'
+  if (typeof d === 'string') return `'${escapeMinijinjaSingleQuoted(d)}'`
+  if (typeof d === 'boolean') return d ? 'true' : 'false'
+  return String(d)
+}
+
+/**
+ * Emit one `{% set <local> = bf.use_context(...) %}` statement per context
+ * consumer so the body's bare `<local>` resolves to the active provider
+ * value (or the `createContext` default). (#1297)
+ */
+export function generateContextConsumerSeed(ir: ComponentIR): string {
+  const consumers = collectContextConsumers(ir.metadata)
+  if (consumers.length === 0) return ''
+  return (
+    consumers
+      .map(
+        c =>
+          `{% set ${minijinjaIdent(c.localName)} = bf.use_context('${c.contextName}', ${contextDefaultJinja(c)}) %}`,
+      )
+      .join('\n') + '\n'
+  )
+}
+
+/**
+ * Emit `{% set <name> = <jinja> %}` statements for every `derived` step of
+ * the backend-neutral SSR seed plan — the scope/availability/ordering
+ * analysis lives in `computeSsrSeedPlan` (packages/jsx/src/ssr-seed-plan.ts);
+ * this only lowers each step's expression to Jinja and applies the
+ * backend-specific emit guards: skip an empty lowering, and skip a lowering
+ * that references no top-level identifier at all (a constant init/body —
+ * e.g. a `derived` step with empty `frees` — keeps the existing static
+ * ssr-defaults seed instead). Unlike the Kolon port there is no self-ref
+ * guard — see the file header. `env-reader` and `opaque` steps emit nothing
+ * (the runtime supplies the reader, or the adapter's ssr-defaults path
+ * already covers it). (#1297, #2075)
+ *
+ * `convertExpressionToJinja` can still fail DEEPER than the plan's
+ * structural `isSupported` pre-check — e.g. a `.filter(predicate)` whose
+ * predicate isn't evaluator-serializable has NO lambda fallback on this
+ * adapter (divergence 3, `minijinja-adapter.ts`'s file header: unlike Kolon/Perl,
+ * Jinja has no lambda-expression form), so the lowering records a HARD
+ * BF101 as a side effect rather than degrading. That's correct for every
+ * OTHER `convertExpressionToJinja` call site (which commit to using the
+ * lowered text), but wrong here: this is a SPECULATIVE "recompute the memo
+ * in-template, else keep the static ssrDefault seed" attempt, so a deeper
+ * refusal must degrade silently, not fail the whole component compile.
+ * Snapshot the diagnostic list and roll back any errors appended during each
+ * step's attempt before moving on.
+ *
+ * A second, related Jinja-only gap divergence 3 opens up: a predicate
+ * referencing a SIBLING getter (`props.items.filter((p) => !tag() || …)`,
+ * `tag` a sibling memo) contains a zero-arg CALL node (`tag()`), which the
+ * evaluator's pure-expression surface refuses (`toEvalNode`'s `call` arm
+ * only allows a builtin callee, e.g. `Math.floor`) — with no lambda
+ * fallback to fall back to, the whole predicate would refuse. Kolon/Perl
+ * never hit this: their lambda form closes over the sibling's ALREADY-SEEDED
+ * lexical directly, without going through the evaluator at all. Go hits the
+ * identical gap (it also has no closures at SSR-constructor time) and fixes
+ * it the same way its `memo/memo-compute.ts` (`matchFilterArmMemo`) does:
+ * `materializeGetterCalls` rewrites a getter call into a bare identifier
+ * BEFORE serialization, so the evaluator captures it as a free-var read from
+ * `base_env` instead of an unsupported call node — and that free var then
+ * resolves against the sibling's own `{% set %}` line, which (being an
+ * EARLIER step per the plan's ordering guarantee) is always already bound.
+ * `env-reader` names are excluded from the materializable set — the runtime
+ * supplies those via the per-request reader, not a template-var lexical, so
+ * a call to one (`searchParams()`) must stay a real call, not a bare var.
+ */
+export function generateDerivedMemoSeed(ctx: JinjaMemoContext, ir: ComponentIR): string {
+  // Package G attached this to metadata at compile time; the `??` fallback
+  // only covers hand-built metadata in older tests that predate the attached
+  // plan — same shared function, so there's no divergence from the compiler.
+  const plan = ir.metadata.ssrSeedPlan ?? computeSsrSeedPlan(ir.metadata)
+  const knownGetterNames = new Set<string>(
+    plan.steps.filter(s => s.kind !== 'env-reader').map(s => s.name),
+  )
+  const lines: string[] = []
+  for (const step of plan.steps) {
+    if (step.kind !== 'derived') continue
+    const materialized = materializeGetterCalls(step.parsed, knownGetterNames)
+    const errorsBefore = ctx.errors.length
+    const jinja = ctx.convertExpressionToJinja('', materialized)
+    if (ctx.errors.length > errorsBefore) {
+      ctx.errors.length = errorsBefore
+      continue
+    }
+    if (jinja === '' || extractTopLevelIdentifiers(jinja).length === 0) continue
+    lines.push(`{% set ${minijinjaIdent(step.name)} = ${jinja} %}`)
+  }
+  return lines.length > 0 ? lines.join('\n') + '\n' : ''
+}