@barefootjs/jinja 0.31.4 → 0.31.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/jinja",
-  "version": "0.31.4",
+  "version": "0.31.5",
   "description": "Jinja2 adapter for BarefootJS — compiles IR to .jinja templates and ships the Python BarefootJS rendering runtime; runs under any Python web framework (Flask, etc.)",
   "type": "module",
   "main": "./dist/index.js",
@@ -53,7 +53,7 @@
     "directory": "packages/adapter-jinja"
   },
   "dependencies": {
-    "@barefootjs/shared": "0.31.4"
+    "@barefootjs/shared": "0.31.5"
   },
   "peerDependencies": {
     "@barefootjs/jsx": ">=0.2.0",
@@ -70,9 +70,9 @@
   },
   "devDependencies": {
     "@barefootjs/adapter-tests": "0.1.0",
-    "@barefootjs/jsx": "0.31.4",
-    "@barefootjs/vite": "0.31.4",
-    "@barefootjs/client": "0.31.4",
+    "@barefootjs/jsx": "0.31.5",
+    "@barefootjs/vite": "0.31.5",
+    "@barefootjs/client": "0.31.5",
     "typescript": "^5.0.0",
     "vite": "^6.0.0"
   }

package/src/__tests__/jinja-adapter-unit.test.ts

@@ -414,11 +414,12 @@ export function Parent() {
 // `ir.metadata.localConstants` with no notion of AST scope — it used to
 // substitute an outer const's literal value even at an occurrence that is
 // actually an enclosing loop callback's own (shadowing) parameter, so every
-// iteration rendered the same hard-coded literal. Guarded with the same
-// coarse `collectLoopBoundNames` exclusion as #2212: any name a loop binds
-// anywhere in the component never inlines, falling back to the bare
-// identifier. SSR-only tests for the same #2222 reason as the #2212
-// describe below.
+// iteration rendered the same hard-coded literal. Guarded via the threaded,
+// position-accurate `BindingScope` (#2482 Stage 2 — previously a coarse
+// whole-component exclusion, same as #2212's, that also suppressed a
+// genuinely non-shadowed occurrence outside the loop; the threaded scope
+// only shadows AT the enclosing loop's own body). SSR-only tests for the
+// same #2222 reason as the #2212 describe below.
 describe('JinjaAdapter - const inlining vs loop-param shadowing (#2221)', () => {
   test('a loop param shadowing an outer literal const emits the identifier, not the const value', () => {
     const { template } = compileAndGenerate(`
@@ -457,11 +458,11 @@ function Widget({ values }: { values: number[] }) {
     expect(template).toContain('1 + 5')
   })
 
-  // The accepted coarse-exclusion trade-off (same as #2212): a name that is
-  // loop-bound ANYWHERE in the component never inlines, even at a genuinely
-  // non-shadowed occurrence outside the loop — the bare identifier is
-  // emitted instead of the value.
-  test('a const referenced outside the loop whose name is loop-bound elsewhere falls back to the identifier (accepted trade-off)', () => {
+  // Position-accurate scope (#2482 Stage 2): a name that is loop-bound
+  // elsewhere in the component but NOT at THIS occurrence still inlines
+  // here — the coarse whole-component exclusion this used to hit (and
+  // accept as a trade-off) is gone; only the loop's own body shadows.
+  test('a const referenced outside the loop whose name is loop-bound elsewhere still inlines outside, stays the identifier inside', () => {
     const { template } = compileAndGenerate(`
 function Widget({ values }: { values: number[] }) {
   const label: string = 'x'
@@ -471,7 +472,7 @@ function Widget({ values }: { values: number[] }) {
   </div>
 }
 `)
-    expect(template).not.toContain("1 + 'x'")
+    expect(template).toContain("1 + 'x'")
     expect(template).toContain('2 + label')
   })
 })
@@ -483,9 +484,8 @@ function Widget({ values }: { values: number[] }) {
 // substitute the outer const's member value even at an occurrence that is
 // actually an enclosing loop callback's own (shadowing) parameter, so every
 // iteration rendered the same hard-coded literal instead of the per-item
-// value. Guarded with the same coarse `staticLoopSourceBoundNames`
-// exclusion as #2221: any name a loop binds anywhere in the component
-// never inlines, falling back to the bare `cfg['x']` member expression.
+// value. Guarded via the threaded, position-accurate `BindingScope` (#2482
+// Stage 2), same as #2221's fix above.
 describe('JinjaAdapter - record-literal member lookup vs loop-param shadowing (#2237)', () => {
   test('a loop param shadowing an outer module object const emits the member access, not the outer literal', () => {
     const { template } = compileAndGenerate(`
@@ -510,12 +510,12 @@ function Widget({ variant }: { variant: 'solid' | 'ghost' }) {
     expect(template).toContain("bf.string('bg-ghost')")
   })
 
-  // The accepted coarse-exclusion trade-off (same as #2221/#2212): an
-  // object name that is loop-bound ANYWHERE in the component never
-  // inlines its member lookups, even at a genuinely non-shadowed
-  // occurrence outside the loop — the bare member expression is emitted
-  // instead of the value.
-  test('a record member referenced outside the loop whose object name is loop-bound elsewhere falls back to the member expression (accepted trade-off)', () => {
+  // Position-accurate scope (#2482 Stage 2): an object name that is
+  // loop-bound elsewhere in the component but NOT at THIS occurrence still
+  // inlines its member lookup here — the coarse whole-component exclusion
+  // this used to hit (and accept as a trade-off) is gone; only the loop's
+  // own body shadows.
+  test('a record member referenced outside the loop whose object name is loop-bound elsewhere still inlines outside, stays the member expression inside', () => {
     const { template } = compileAndGenerate(`
 const cfg = { x: 'outer-lit' }
 function Widget({ rows }: { rows: { x: string }[] }) {
@@ -525,11 +525,49 @@ function Widget({ rows }: { rows: { x: string }[] }) {
   </div>
 }
 `)
-    expect(template).not.toContain("bf.string('outer-lit')")
+    expect(template).toContain("bf.string('outer-lit')")
     expect(template).toContain("bf.string(cfg['x'])")
   })
 })
 
+// Copilot review on #2600 (#2482 Stage 2 follow-up): the position-accurate
+// `this.scope` (replacing the old coarse `staticLoopSourceBoundNames` set)
+// was only threaded around `renderChildren(loop.children)` in `renderLoop`
+// — narrower than the coarse set's always-on coverage. Two row-context
+// conversions sit OUTSIDE that window: a `.map()` preamble local's own
+// initializer, and the whole-item-conditional `loop-i:` key anchor
+// (`loop.key`). Both genuinely evaluate PER ROW and must see the row's own
+// bindings — a loop param shadowing a same-named outer const must resolve
+// to the row value there too, exactly as it already does inside the loop
+// body proper. `renderLoop` now enters the row scope before converting
+// either and pops it after, closing the gap.
+describe('JinjaAdapter - row scope covers preamble/key conversions outside renderChildren (#2482 Stage 2 Copilot follow-up)', () => {
+  test('a loop param shadowing an outer const resolves to the row value inside a whole-item-conditional loop-i: key anchor', () => {
+    const { template } = compileAndGenerate(`
+function Widget({ values }: { values: number[] }) {
+  const label: string = 'x'
+  return <ul>{values.map((label) => (label > 0 ? <li key={label}>{label}</li> : null))}</ul>
+}
+`)
+    expect(template).toContain('bf.comment("loop-i:" ~ bf.string(label))')
+    expect(template).not.toContain("bf.comment(\"loop-i:\" ~ bf.string('x'))")
+  })
+
+  test('a loop param shadowing an outer const resolves to the row value inside a .map() preamble local initializer', () => {
+    const { template } = compileAndGenerate(`
+function Widget({ values }: { values: number[] }) {
+  const label: string = 'x'
+  return <ul>{values.map((label) => {
+    const cls = label
+    return <li key={label} class={cls}>{label}</li>
+  })}</ul>
+}
+`)
+    expect(template).toContain('{% set cls = label %}')
+    expect(template).not.toContain("{% set cls = 'x' %}")
+  })
+})
+
 // A fragment-rooted component (top-level `<>...</>` return) has no single
 // wrapping element to bound the client's scope query, so `renderFragment`
 // brackets its children with a comment-based scope marker pair instead of

package/src/adapter/jinja-adapter.ts

@@ -145,8 +145,8 @@ import {
   dangerousInnerHtmlMetacharViolation,
   dangerousInnerHtmlDiagnostic,
   resolveStaticLoopSource,
-  collectLoopBoundNames,
   derivesScopeFromSlot,
+  BindingScope,
 } from '@barefootjs/jsx'
 import { isAriaBooleanAttr, isBooleanResultExpr, isExplicitStringCall } from './boolean-result.ts'
 import type { ParsedExpr, LoweringMatcher } from '@barefootjs/jsx'
@@ -272,30 +272,24 @@ export class JinjaAdapter extends BaseAdapter implements IRNodeEmitter<JinjaRend
   private localConstants: IRMetadata['localConstants'] = []
 
   /**
-   * Every name a `.map()`/`.filter()` loop callback binds as its item/index
-   * parameter anywhere in the component (#2208 fable review). A static
-   * loop-SOURCE name (e.g. a function-scope `const items = [...]`) must
-   * never resolve through `resolveStaticLoopSource` at a use site where a
-   * DIFFERENT, enclosing loop's own callback param shadows it — same
-   * shadowing hazard, and same coarse-but-safe mitigation, as #2212's
-   * `collectLoopBoundNames` use in `collectStringValueNames`.
+   * The one canonical, position-accurate "names bound by an enclosing loop
+   * callback" service (#2482 Stage 2) — replaces the two ad-hoc devices
+   * this adapter used to carry side by side: a coarse whole-component
+   * shadow-name Set (built once at `generate()` entry, used only to guard
+   * static-const inlining) and a ref-counted, position-accurate live map
+   * (pushed/popped around `renderLoop`'s body, used for the boolean-prop/
+   * nullable-optional classification sites (#2488) and `emitSpread`'s
+   * local-const fallback (#2489)). Both consulted the "is this name
+   * loop-bound" question with DIFFERENT meanings — the coarse/live drift
+   * #2482 Stage 2 ends. Every shadow-guard site now reads this ONE
+   * threaded, immutable scope: `enterLoopRow`/pop-by-reference around
+   * `renderChildren(loop.children)` in `renderLoop`, mirroring the Stage
+   * 1a/1b `ctx.scope` precedent in `jsx-to-ir.ts`. `IRLoop` already
+   * structurally satisfies `LoopBindingSource`
+   * (`param`/`index`/`paramBindings`/`preamble`), so `renderLoop` passes
+   * the loop node straight to `enterLoopRow`.
    */
-  private staticLoopSourceBoundNames: Set<string> = new Set()
-
-  /**
-   * Names currently bound by an enclosing loop body — the block-param
-   * locals `renderLoop` introduces (item, index, per-binding destructure
-   * fields, `.map()` preamble declarations) — ref-counted so nested loops
-   * compose. This is the POSITION-ACCURATE twin of the coarse
-   * `staticLoopSourceBoundNames` above: that set is a whole-component
-   * union used only to guard static-const inlining (safe to over-suppress
-   * there — the fallback is just "don't inline"), whereas the boolean-prop
-   * and nullable-optional classification sites (#2488) and `emitSpread`'s
-   * local-const fallback (#2489) need to know whether a name is loop-bound
-   * AT THIS POSITION, because for those the coarse fallback would silently
-   * mis-render a genuine occurrence of the same name outside the loop too.
-   */
-  private loopBoundNames: Map<string, number> = new Map()
+  private scope: BindingScope = BindingScope.EMPTY
 
   /**
    * Optional, no-default props that are `None` when the caller omits them.
@@ -329,8 +323,7 @@ export class JinjaAdapter extends BaseAdapter implements IRNodeEmitter<JinjaRend
     // ("True"/"False") (#1897, pagination's data-active).
     this.booleanTypedProps = collectBooleanTypedProps(ir)
     this.localConstants = ir.metadata.localConstants ?? []
-    this.staticLoopSourceBoundNames = collectLoopBoundNames(ir)
-    this.loopBoundNames.clear()
+    this.scope = BindingScope.EMPTY
     this.nullableOptionalProps = collectNullableOptionalProps(ir)
     this.stringValueNames = collectStringValueNames(ir)
     this.moduleStringConsts = collectModuleStringConsts(ir.metadata.localConstants)
@@ -829,9 +822,11 @@ export class JinjaAdapter extends BaseAdapter implements IRNodeEmitter<JinjaRend
     // bare identifier expression below, same as before #2208 — which
     // still trips the pre-existing BF101 gate for an unresolvable local
     // const reference (a loud, conservative refusal, not a silent wrong
-    // value).
+    // value). Canonical, position-accurate predicate (#2482 Stage 2) — the
+    // enclosing loop scope's own membership, not a coarse whole-component
+    // union.
     const staticItems = resolveStaticLoopSource(loop.arrayParsed, this.localConstants, {
-      isNameShadowed: name => this.staticLoopSourceBoundNames.has(name),
+      isNameShadowed: this.scope.asShadowPredicate(),
     })
     const staticArray = staticItems !== null ? staticValueToJinja(staticItems) : null
 
@@ -941,6 +936,34 @@ export class JinjaAdapter extends BaseAdapter implements IRNodeEmitter<JinjaRend
     // loop-child naming convention). renderedChildren above was computed with
     // the previous flag; recompute under the loop flag.
 
+    // This loop's row scope, for the position-accurate shadow guard
+    // (#2488/#2489, canonicalized on `BindingScope` in #2482 Stage 2).
+    // `IRLoop` already structurally satisfies `LoopBindingSource`
+    // (`param`/`index`/`paramBindings`/`preamble`) — `enterLoopRow(loop)`
+    // binds exactly the for-header target(s), each destructure binding,
+    // the index (when present), and the `.map()` preamble's declared
+    // locals, mirroring what THIS renderLoop's for-header + `indexLocalLines`
+    // actually introduce. Restored by reference (immutable — no ref-count
+    // bookkeeping) so nested loops compose for free. Entered BEFORE
+    // `preambleLines`/`bodyChildren` are converted and popped AFTER, not
+    // just around `renderChildren` — Copilot review on #2600 caught that
+    // the narrower window silently regressed the module-const shadow guard
+    // (`_resolveLiteralConst`/`_resolveStaticRecordLiteral`, now
+    // scope-driven instead of the old coarse whole-component set) for two
+    // row-context conversions that sit OUTSIDE `renderChildren`: a
+    // `.map()` preamble local's own initializer (`d.raw`, below) and the
+    // whole-item-conditional `loop-i:` key anchor (`loop.key`, in
+    // `bodyChildren` below) — both genuinely evaluate PER ROW and must see
+    // the row's own bindings. `loop.filterPredicate` deliberately stays
+    // OUTSIDE this window (further down, after the pop): per the Stage 0
+    // design a filter/sort callback's own param is a separate `callback`
+    // frame, never folded into the `.map()` row — and empirically
+    // `JinjaFilterEmitter` (the filter predicate's dedicated,
+    // self-contained emitter) never consults `this.scope` at all, so its
+    // position relative to the pop is inert either way.
+    const prevScope = this.scope
+    this.scope = prevScope.enterLoopRow(loop)
+
     // Per-row locals for a `.map()` callback preamble (#2447), in source
     // order so a later initializer sees an earlier local — same as the
     // source block. Phase 1 refuses the loop outright when the preamble
@@ -949,39 +972,7 @@ export class JinjaAdapter extends BaseAdapter implements IRNodeEmitter<JinjaRend
     const preambleLines = (loop.preamble?.declarations ?? []).map(
       d => `{% set ${jinjaIdent(d.name)} = ${this.convertExpressionToJinja(d.raw, d.valueParsed)} %}`,
     )
-    // Names this loop binds in body scope, for the position-accurate
-    // `loopBoundNames` guard (#2488) — mirrors the ERB adapter's `loopBound`
-    // derivation, adapted to what THIS renderLoop actually binds: the
-    // for-header target(s) (`loopVar` / `objectIteration` key+value /
-    // `iterationShape === 'keys'`'s `param`), each `indexLocalLines` name
-    // (explicit index, or a destructure binding), and the `.map()`
-    // preamble's declared locals. Ref-counted so nested loops compose.
-    const loopBound: string[] = []
-    if (loop.objectIteration === 'entries') {
-      loopBound.push(loop.index ?? param, param)
-    } else if (loop.objectIteration === 'keys' || loop.objectIteration === 'values') {
-      loopBound.push(param)
-    } else if (loop.iterationShape === 'keys') {
-      // The header still binds the throwaway loop var; `param` is only the
-      // index alias set beneath it (#2488).
-      loopBound.push('__bf_item', param)
-    } else if (supportableDestructure) {
-      loopBound.push('__bf_item', ...(loop.paramBindings ?? []).map(b => b.name))
-      if (loop.index) loopBound.push(loop.index)
-    } else {
-      loopBound.push(param)
-      if (loop.index) loopBound.push(loop.index)
-    }
-    for (const d of loop.preamble?.declarations ?? []) loopBound.push(d.name)
-    for (const n of loopBound) {
-      this.loopBoundNames.set(n, (this.loopBoundNames.get(n) ?? 0) + 1)
-    }
     const childrenUnderLoop = this.renderChildren(loop.children)
-    for (const n of loopBound) {
-      const c = (this.loopBoundNames.get(n) ?? 1) - 1
-      if (c <= 0) this.loopBoundNames.delete(n)
-      else this.loopBoundNames.set(n, c)
-    }
     this.currentLoopKeyDepth = prevLoopKeyDepth
     this.inLoop = prevInLoop
     void renderedChildren
@@ -989,11 +980,13 @@ export class JinjaAdapter extends BaseAdapter implements IRNodeEmitter<JinjaRend
     // Whole-item conditional: prepend an always-present `<!--bf-loop-i:KEY-->`
     // anchor before each item's (possibly empty) conditional content so the
     // client's `mapArrayAnchored` can hydrate every SSR-rendered item by its
-    // anchor.
+    // anchor. Still under the row scope (see above) — `loop.key` is a
+    // per-row expression.
     const bodyChildren =
       loop.bodyIsItemConditional && loop.key
         ? `{{ bf.comment("loop-i:" ~ bf.string(${this.convertExpressionToJinja(loop.key)})) | safe }}\n${childrenUnderLoop}`
         : childrenUnderLoop
+    this.scope = prevScope
 
     const lines: string[] = []
     // Scoped per-call-site marker so sibling `.map()`s under the same parent
@@ -1472,13 +1465,13 @@ export class JinjaAdapter extends BaseAdapter implements IRNodeEmitter<JinjaRend
       // function-scope (`!isModule`) consts whose value is NOT itself a bare
       // identifier (loop guard) are considered.
       //
-      // `loopBoundNames` guard (#2489): an enclosing `.map()` callback's own
-      // param can shadow this outer const's name (`.map((attrs) => <p
+      // `this.scope` shadow guard (#2489): an enclosing `.map()` callback's
+      // own param can shadow this outer const's name (`.map((attrs) => <p
       // {...attrs} />)`) — without the guard this forwarded the OUTER
       // const's value at every iteration instead of the per-item value.
-      // Must be the LIVE map, not `staticLoopSourceBoundNames` — the same
-      // name spread at ROOT must still resolve the const.
-      if (/^[A-Za-z_$][\w$]*$/.test(trimmed) && !this.loopBoundNames.has(trimmed)) {
+      // Must be the threaded, position-accurate scope — the same name
+      // spread at ROOT (no enclosing loop) must still resolve the const.
+      if (/^[A-Za-z_$][\w$]*$/.test(trimmed) && !this.scope.isBound(trimmed)) {
         const localConst = (this.localConstants ?? []).find(
           c => c.name === trimmed && !c.isModule,
         )
@@ -1894,9 +1887,9 @@ export class JinjaAdapter extends BaseAdapter implements IRNodeEmitter<JinjaRend
     return this.booleanTypedProps.has(bare)
   }
 
-  /** Position-accurate loop-bound-name check — see `loopBoundNames`'s docstring. */
+  /** Position-accurate loop-bound-name check — see `this.scope`'s docstring. */
   private isLoopBoundName(name: string): boolean {
-    return this.loopBoundNames.has(name)
+    return this.scope.isBound(name)
   }
 
   /**
@@ -1923,17 +1916,16 @@ export class JinjaAdapter extends BaseAdapter implements IRNodeEmitter<JinjaRend
    * context, so a bare reference would resolve to Undefined.
    *
    * The lookup is a flat name match with no notion of AST scope, so a
-   * name that any loop callback binds as its item/index param never
-   * inlines (#2221) — the occurrence may be the loop's own (shadowing)
-   * binding, and substituting the outer const's value there renders every
-   * iteration with the same hard-coded literal. Coarse (a genuinely
-   * non-shadowed same-named const elsewhere in the component also stops
-   * inlining, falling back to the bare identifier) but safe — the same
-   * trade-off as #2212's `collectLoopBoundNames` use in
-   * `collectStringValueNames`.
+   * name bound by the CURRENTLY ENCLOSING loop's item/index/destructure/
+   * preamble param never inlines (#2221) — the occurrence may be the
+   * loop's own (shadowing) binding, and substituting the outer const's
+   * value there renders every iteration with the same hard-coded literal.
+   * Position-accurate via the threaded `this.scope` (#2482 Stage 2) — a
+   * same-named const elsewhere in the component, outside any loop that
+   * shadows it, still inlines.
    */
   private _resolveLiteralConst(name: string): string | null {
-    if (this.staticLoopSourceBoundNames.has(name)) return null
+    if (this.scope.isBound(name)) return null
     const c = (this.localConstants ?? []).find(lc => lc.name === name)
     if (c?.value === undefined) return null
     const v = c.value.trim()
@@ -1951,15 +1943,16 @@ export class JinjaAdapter extends BaseAdapter implements IRNodeEmitter<JinjaRend
    * scope, so an enclosing loop callback's own param of the same name
    * (`.map((cfg) => <li>{cfg.x}</li>)` shadowing a module `const cfg = {…}`)
    * still resolved to the OUTER const's member value at every iteration
-   * (#2237) — the sibling hazard to #2221's `_resolveLiteralConst`. Same
-   * coarse-but-safe `staticLoopSourceBoundNames` guard: any name a loop
-   * binds anywhere in the component never inlines, falling back to the bare
+   * (#2237) — the sibling hazard to #2221's `_resolveLiteralConst`.
+   * Position-accurate via the threaded `this.scope` (#2482 Stage 2), passed
+   * as `lookupStaticRecordLiteral`'s required guard: a name the CURRENTLY
+   * ENCLOSING loop binds never inlines, falling back to the bare
    * `cfg['x']` member expression (which a Jinja for-loop binds correctly
-   * at the shadowed occurrences).
+   * at the shadowed occurrence); a same-named const elsewhere, outside any
+   * loop that shadows it, still inlines.
    */
   private _resolveStaticRecordLiteral(objectName: string, key: string): string | null {
-    if (this.staticLoopSourceBoundNames.has(objectName)) return null
-    const hit = lookupStaticRecordLiteral(objectName, key, this.localConstants)
+    const hit = lookupStaticRecordLiteral(objectName, key, this.localConstants, name => this.scope.isBound(name))
     if (!hit) return null
     return hit.kind === 'number'
       ? hit.text