@barefootjs/xslate 0.17.1 → 0.18.0

package/src/adapter/xslate-adapter.ts

@@ -40,6 +40,7 @@ import type {
   TypeInfo,
   TemplatePrimitiveRegistry,
   IRMetadata,
+  LoopBindingPathSegment,
 } from '@barefootjs/jsx'
 import {
   BaseAdapter,
@@ -64,13 +65,14 @@ import {
   collectModuleStringConsts,
   extractArrowBodyExpression,
   collectContextConsumers,
-  isLowerableObjectRestDestructure,
   type ContextConsumer,
   lookupStaticRecordLiteral,
   searchParamsLocalNames,
   prepareLoweringMatchers,
   queryHrefArgs,
+  isValidHelperId,
   sortComparatorFromArrow,
+  isLowerableLoopDestructure,
 } from '@barefootjs/jsx'
 import { isAriaBooleanAttr, isBooleanResultExpr } from './boolean-result.ts'
 import ts from 'typescript'
@@ -79,7 +81,7 @@ import { BF_SLOT, BF_COND, BF_REGION } from '@barefootjs/shared'
 
 import type { XslateRenderCtx } from './lib/types.ts'
 import { XSLATE_PRIMITIVE_EMIT_MAP } from './lib/constants.ts'
-import { kolonHashKey } from './lib/kolon-naming.ts'
+import { kolonHashKey, escapeKolonSingleQuoted } from './lib/kolon-naming.ts'
 import {
   resolveJsxChildrenProp,
   collectRootScopeNodes,
@@ -108,6 +110,47 @@ import {
 export type { XslateAdapterOptions } from './lib/types.ts'
 import type { XslateAdapterOptions } from './lib/types.ts'
 
+/**
+ * Build a Kolon accessor expression for a `.map()` destructure binding's
+ * structured `segments` path (#2087 Phase B), walking `field` (`.key` for an
+ * identifier-safe name, `["key"]` — quoted with `kolonHashKey`'s convention —
+ * otherwise, since Kolon parses `$x.data-priority` as a subtraction) /
+ * `index` (`[N]`) steps onto `base`. Verified against real Text::Xslate that
+ * dot- and bracket-access chain freely (`$x.cells[0]`, `$x["cells"][0]`).
+ * Never string-parses `LoopParamBinding.path` — see the repo-wide rule
+ * against regex-parsing JS/TS-derived syntax.
+ *
+ * Used both for a fixed binding's FULL accessor (`base` = `$__bf_item`,
+ * `segments` = the whole path) and a rest binding's PARENT-prefix accessor
+ * (`segments` may be empty, at the loop root, in which case this returns
+ * `base` unchanged) — see `LoopParamBinding.segments` jsdoc for which case
+ * a binding is in.
+ */
+function kolonSegmentAccessor(base: string, segments: readonly LoopBindingPathSegment[]): string {
+  let expr = base
+  for (const seg of segments) {
+    expr +=
+      seg.kind === 'field'
+        ? seg.isIdent
+          ? `.${seg.key}`
+          : `[${kolonHashKey(seg.key)}]`
+        : `[${seg.index}]`
+  }
+  return expr
+}
+
+/**
+ * Quote a string as a Kolon single-quoted literal, unconditionally — unlike
+ * `kolonHashKey` (which leaves an identifier-safe name unquoted for `key =>
+ * val` hashref-literal position), a plain array-literal element
+ * (`$bf.omit($x, [id, title])`) is NOT hash-key position: Kolon has no
+ * bareword-as-string convention there, so every object-rest exclude key
+ * needs an explicit string literal.
+ */
+function kolonStringLiteral(s: string): string {
+  return `'${escapeKolonSingleQuoted(s)}'`
+}
+
 export class XslateAdapter extends BaseAdapter implements IRNodeEmitter<XslateRenderCtx> {
   name = 'xslate'
   extension = '.tx'
@@ -578,33 +621,79 @@ export class XslateAdapter extends BaseAdapter implements IRNodeEmitter<XslateRe
       return `<: $bf.comment("loop:${loop.markerId}") | mark_raw :><: $bf.comment("/loop:${loop.markerId}") | mark_raw :>`
     }
 
-    // An array/object-destructure loop param (`([emoji, users]) => ...` or
-    // `({ name, age }) => ...`) lowers to invalid Kolon — Kolon's `for LIST
-    // -> $item` binds a single scalar and can't unpack a tuple. Surface this
-    // at build time instead of shipping a broken template line.
-    // A destructure loop param is lowerable for the object-rest / simple-field
-    // shape (`.map(({ id, title, ...rest }) => …)`, `rest` read via member
-    // access): each binding becomes a Kolon `: my` local off the per-item var,
-    // so the body's `$id` / `$rest.flag` resolve. Array-index / nested /
-    // rest-spread shapes still can't unpack a tuple → BF104. (#1310)
+    // A `.map()` destructure loop param (`([k, v]) => ...` / `({ id, user: {
+    // name } }) => ...` / `({ id, ...rest }) => ...`) lowers to a Kolon `: my`
+    // local per binding, walking each binding's structured `segments` path
+    // (#2087 Phase B) into a native `.key` / `["key"]` / `[N]` accessor off
+    // the per-item var — so the body's `$id` / `$name` / `$rest.flag` /
+    // `{...rest}` all resolve natively, at any nesting depth.
+    //
+    // Check the IR's structured `paramBindings` field rather than
+    // string-matching `loop.param`: Phase 1 populates `paramBindings`
+    // iff the param is a destructure pattern (array or object); a
+    // simple identifier leaves it `undefined`. The structured check is
+    // robust to whitespace / formatting variants in the source.
+    //
+    // `isLowerableLoopDestructure` (#2087) still refuses: an object-rest
+    // binding used any way other than member access (`rest.flag`) or a
+    // `{...rest}` spread onto an intrinsic element (that needs the actual
+    // residual *object*, which isn't always safe to materialize — see the
+    // gate's own jsdoc for the full list); a `.filter().map(destructure)`
+    // chain (the filter-param rewrite is out of scope here); and a
+    // computed property key (`{ [k]: v }`, refused earlier as BF025).
     const destructure = !!(loop.paramBindings && loop.paramBindings.length > 0)
-    const supportableDestructure = destructure && isLowerableObjectRestDestructure(loop)
+    const supportableDestructure = destructure && isLowerableLoopDestructure(loop)
     if (destructure && !supportableDestructure) {
       this.errors.push({
         code: 'BF104',
         severity: 'error',
-        message: `Loop callback uses an array/object destructure pattern (\`${loop.param}\`) that the Xslate adapter cannot lower — Kolon \`for LIST -> $item\` binds a single scalar and can't unpack a tuple.`,
+        message: `Loop callback uses a destructure pattern (\`${loop.param}\`) that the Xslate adapter cannot lower — see the diagnostic detail for the specific shape.`,
         loc: loop.loc ?? { file: this.componentName + '.tsx', start: { line: 1, column: 0 }, end: { line: 1, column: 0 } },
         suggestion: {
           message:
             `Options:\n` +
-            `  1. Rename the parameter to a single name and access tuple elements with index syntax in the body (e.g. \`entry => entry[0]\` instead of \`([k, v]) => ...\`).\n` +
-            `  2. Mark the loop position as @client-only so the destructure runs in JS on the client.\n` +
-            `  3. Move the loop into a primitive that the adapter registers explicitly.`,
+            `  1. If this is an object-rest binding (\`{ ...rest }\`), only reading \`rest.field\` or spreading \`{...rest}\` onto an intrinsic element lowers — other uses (passing \`rest\` to a function, rendering it as text) need the client runtime.\n` +
+            `  2. If this is chained \`.filter().map(({ ... }) => ...)\`, hoist the destructure into a variable inside the callback body instead.\n` +
+            `  3. Mark the loop position as @client-only so the destructure runs in JS on the client.\n` +
+            `  4. Move the loop into a primitive that the adapter registers explicitly.`,
         },
       })
     }
 
+    // A `.map()` loop whose array is a bare identifier bound to a
+    // FUNCTION-scope local const with a non-statically-evaluable initializer
+    // that reads props/signals (e.g. `const entries =
+    // Object.entries(props.x ?? {}).filter(...)`) can't render correctly.
+    // Module-scope consts (`isModule`, e.g. `const payments = [...]` at the
+    // top of the file) are a DIFFERENT, already-working case handled
+    // elsewhere. Function-scope locals get no per-render stash slot — this
+    // adapter's only "elsewhere" for a local const is inlining its value at
+    // the use site (`_resolveLiteralConst`'s numeric/single-quoted-string
+    // fast path, or a static-record-literal lookup), never binding one as a
+    // `: my` template local. Left unchecked, `: for $entries -> $__bf_item {`
+    // over an undeclared `$entries` faults at request time instead of
+    // failing loudly at build time. Pre-existing, general limitation,
+    // orthogonal to #2087's destructure-binding work — newly reachable in
+    // this adapter's test corpus only because the widened destructure gate
+    // (#2087 Phase A/B) no longer refuses this fixture's `([emoji, users])
+    // => ...` param first.
+    const arrayName = loop.array.trim()
+    if (/^[A-Za-z_$][\w$]*$/.test(arrayName)) {
+      const arrayConst = (this.localConstants ?? []).find(c => c.name === arrayName)
+      if (arrayConst && !arrayConst.isModule && this._resolveLiteralConst(arrayName) === null) {
+        this.errors.push({
+          code: 'BF101',
+          severity: 'error',
+          message: `Loop array \`${arrayName}\` is a local computed value (\`${arrayConst.value}\`) that the Xslate adapter cannot bind as a template variable — only numeric/string-literal locals inline at their use site.`,
+          loc: loop.loc ?? { file: this.componentName + '.tsx', start: { line: 1, column: 0 }, end: { line: 1, column: 0 } },
+          suggestion: {
+            message:
+              'Pre-compute the array server-side and pass it as a prop, or mark the loop position as @client-only so it runs in JS on the client.',
+          },
+        })
+      }
+    }
+
     const rawArray = this.convertExpressionToKolon(loop.array)
     // Apply sort if present: wrap the loop array in the shared `$bf.sort`
     // helper, binding the sorted result to a per-iteration local so the
@@ -642,8 +731,20 @@ export class XslateAdapter extends BaseAdapter implements IRNodeEmitter<XslateRe
     // Index alias: when an explicit `index` param is present (`.map((x, i) =>
     // ...)`) or the iteration is `keys`-shaped, expose it via a `: my` Kolon
     // local bound to the loop variable's `.index` accessor. A supported
-    // destructure param adds one `: my` local per binding (`rest` aliases the
-    // item so `$rest.flag` resolves).
+    // destructure param adds one `: my` local per binding, walking each
+    // binding's `segments` path (#2087 Phase B):
+    //   - fixed (`b.rest` unset): the FULL accessor from `$__bf_item`.
+    //   - array-rest: `$bf.slice(parent, from, nil)` — the same runtime
+    //     helper `.slice()` JS-method calls lower to (see `array-method.ts`),
+    //     so the "no end → to length" arithmetic stays in one place. Kolon's
+    //     undefined literal is `nil`, not Perl's `undef`.
+    //   - object-rest: `$bf.omit(parent, [...excluded keys...])` — a TRUE
+    //     residual hashref (not the whole item aliased), so both
+    //     `$rest.flag` (member-access use) and `$bf.spread_attrs($rest)`
+    //     (spread-onto-element use) see only the non-destructured keys.
+    // `parent` is `$__bf_item` walked through the binding's PARENT-prefix
+    // `segments` (empty at the loop root, per the `LoopParamBinding` jsdoc) —
+    // NOT the same as a fixed binding's full-accessor segments.
     const indexLocalLines: string[] = []
     if (loop.iterationShape === 'keys') {
       indexLocalLines.push(`: my $${param} = $~${loopVar}.index;`)
@@ -652,11 +753,17 @@ export class XslateAdapter extends BaseAdapter implements IRNodeEmitter<XslateRe
     }
     if (supportableDestructure) {
       for (const b of loop.paramBindings ?? []) {
-        indexLocalLines.push(
-          b.rest
-            ? `: my $${b.name} = $${loopVar};`
-            : `: my $${b.name} = $${loopVar}${b.path};`,
-        )
+        const parent = kolonSegmentAccessor(`$${loopVar}`, b.segments ?? [])
+        if (b.rest?.kind === 'object') {
+          const exclude = b.rest.exclude.map(k => kolonStringLiteral(k.key)).join(', ')
+          indexLocalLines.push(`: my $${b.name} = $bf.omit(${parent}, [${exclude}]);`)
+        } else if (b.rest?.kind === 'array') {
+          indexLocalLines.push(`: my $${b.name} = $bf.slice(${parent}, ${b.rest.from}, nil);`)
+        } else {
+          indexLocalLines.push(
+            `: my $${b.name} = ${kolonSegmentAccessor(`$${loopVar}`, b.segments ?? [])};`,
+          )
+        }
       }
     }
 
@@ -750,11 +857,11 @@ export class XslateAdapter extends BaseAdapter implements IRNodeEmitter<XslateRe
     },
     emitSpread: (value) => {
       // Kolon hashrefs can't be splatted into the entry list the way Perl
-      // `%{...}` flattens into a list. The propsObject case is handled in
-      // `renderComponent` (it enumerates the analyzer's props params); any
-      // other spread shape is refused there via the unsupported gate. Emit
-      // the lowered expression so a downstream consumer sees something
-      // coherent, but renderComponent only routes the enumerated case here.
+      // `%{...}` flattens into a list. `renderComponent` handles EVERY
+      // spread shape itself (both the enumerated propsObject case and the
+      // general chained `.merge(...)` fold — see its own docstring), so
+      // this callback is never reached for `kind: 'spread'` props; it
+      // only exists to satisfy the `AttrValueEmitter` interface.
       return this.convertExpressionToKolon(value.expr)
     },
     emitTemplate: (value, name) =>
@@ -766,41 +873,106 @@ export class XslateAdapter extends BaseAdapter implements IRNodeEmitter<XslateRe
     emitJsxChildren: () => '',
   }
 
+  /**
+   * A `renderComponent` props hashref, built as an ORDERED sequence of
+   * segments so `{...before, ...spread, after: 1}` JSX spread semantics
+   * (later entries win) survive the trip through Kolon, which has no
+   * hash-splat syntax (no `%$h`-into-hashref-literal form — verified: parse
+   * error). Each `'entries'` segment is a literal Kolon hashref
+   * `{ k => v, ... }`; each `'spread'` segment is an arbitrary expression
+   * lowered from a `{...expr}` prop. `combineComponentPropSegments` folds
+   * the sequence into ONE expression via chained `.merge(...)` calls
+   * (Kolon's builtin hash method, later argument wins on key conflict,
+   * matching `Object.assign`/JSX order).
+   */
+  private componentPropSegmentEntries(
+    segments: Array<{ kind: 'entries'; parts: string[] } | { kind: 'spread'; expr: string }>,
+  ): string[] {
+    const last = segments[segments.length - 1]
+    if (last && last.kind === 'entries') return last.parts
+    const seg = { kind: 'entries' as const, parts: [] as string[] }
+    segments.push(seg)
+    return seg.parts
+  }
+
+  /**
+   * Fold ordered prop segments into a single Kolon expression via chained
+   * `.merge(...)` calls — Kolon's builtin hash method, later argument wins
+   * on key conflict, exactly like `{...a, ...b}`. A spread segment's
+   * expression is wrapped `(EXPR // {})` before merging: `.merge(undef)`
+   * warns "Merging value is not a HASH reference" (verified against real
+   * Text::Xslate 3.5.9), so the defined-or guard normalises a missing bag
+   * (e.g. `$children.props` when `children` was never passed — Kolon
+   * tolerates the chained dot-access on an undefined value itself,
+   * verified empirically) to an empty hashref first. If the fold starts
+   * with a spread segment, the base is just `($SPREAD // {})`; a
+   * following segment chains `.merge({...})` onto it. Empty `'entries'`
+   * segments are dropped so a leading/trailing spread doesn't drag in a
+   * needless `{}.merge(...)`. Returns `'{}'` when every segment is empty
+   * (no props at all).
+   */
+  private combineComponentPropSegments(
+    segments: ReadonlyArray<{ kind: 'entries'; parts: string[] } | { kind: 'spread'; expr: string }>,
+  ): string {
+    let acc: string | null = null
+    for (const seg of segments) {
+      if (seg.kind === 'entries') {
+        if (seg.parts.length === 0) continue
+        const text = `{ ${seg.parts.join(', ')} }`
+        acc = acc === null ? text : `${acc}.merge(${text})`
+      } else {
+        const text = `(${seg.expr} // {})`
+        acc = acc === null ? text : `${acc}.merge(${text})`
+      }
+    }
+    return acc ?? '{}'
+  }
+
   renderComponent(comp: IRComponent): string {
-    const propParts: string[] = []
+    type Segment = { kind: 'entries'; parts: string[] } | { kind: 'spread'; expr: string }
+    const segments: Segment[] = [{ kind: 'entries', parts: [] }]
+    const currentEntries = () => this.componentPropSegmentEntries(segments)
+
     for (const p of comp.props) {
       // Skip callback props (onXxx) and `ref` — both are client-only for
       // SSR (Hono renders neither; the client JS wires them at hydration).
       if ((p.name.match(/^on[A-Z]/) || p.name === 'ref') && p.value.kind === 'expression') continue
-      // Spread props: enumerate the analyzer's props params into hashref
-      // entries (the propsObject case) — Kolon can't flatten a hashref into
-      // the entry list. Other spread shapes are refused with BF101.
       if (p.value.kind === 'spread') {
         const trimmed = p.value.expr.trim()
+        // SolidJS-style props identifier (`function(props: P)`) has no
+        // matching runtime hash in Kolon scope — props arrive as a flat
+        // set of top-level template vars, so enumerate the
+        // analyzer-extracted props params into hashref entries instead of
+        // treating it as a runtime spread expression.
         if (this.propsObjectName && this.propsObjectName === trimmed) {
           for (const pp of this.propsParams) {
-            propParts.push(`${pp.name} => $${pp.name}`)
+            currentEntries().push(`${pp.name} => $${pp.name}`)
           }
           continue
         }
-        this.errors.push({
-          code: 'BF101',
-          severity: 'error',
-          message: `Spread props (\`{...${trimmed}}\`) on a child component cannot be lowered to Kolon — Kolon hashref method args can't splat a runtime hash into named entries.`,
-          loc: comp.loc ?? { file: this.componentName + '.tsx', start: { line: 1, column: 0 }, end: { line: 1, column: 0 } },
-          suggestion: {
-            message: 'Pass the child component its props explicitly rather than spreading a runtime object.',
-          },
-        })
+        // Every other spread shape (a destructure rest-bag `props`, a
+        // member-access bag like `children.props`, an intrinsic-element
+        // spread helper's own operand, …) — Kolon hashref literals can't
+        // splat a runtime hash into named entries at a call site, but the
+        // builtin `.merge` method can fold it into the accumulated
+        // hashref at the right ordinal position, mirroring Twig's
+        // `|merge` / Jinja's `dict(base, **top)`: no compile-time
+        // filtering of onXxx/ref keys out of the runtime bag (the render
+        // contract tolerates them, same as the other spread-lowering
+        // adapters).
+        segments.push({ kind: 'spread', expr: this.convertExpressionToKolon(p.value.expr) })
         continue
       }
       const lowered = emitAttrValue(p.value, this.componentPropEmitter, p.name)
-      if (lowered) propParts.push(lowered)
+      if (lowered) currentEntries().push(lowered)
     }
     // Pass slot ID so the child renderer can set correct scope ID for
     // hydration. Skip for loop children — they use ComponentName_random.
+    // Appended to whatever the trailing entries segment is so a spread's
+    // own `_bf_slot`/`children` keys (if any) never win over these
+    // compiler-controlled entries.
     if (comp.slotId && !this.inLoop) {
-      propParts.push(`_bf_slot => '${comp.slotId}'`)
+      currentEntries().push(`_bf_slot => '${comp.slotId}'`)
     }
     const tplName = this.toTemplateName(comp.name)
 
@@ -822,12 +994,13 @@ export class XslateAdapter extends BaseAdapter implements IRNodeEmitter<XslateRe
       const childrenBody = this.renderChildren(effectiveChildren)
       this.inLoop = prevInLoop
       const macroName = `bf_children_${comp.slotId ?? 'c' + this.childrenCaptureCounter++}`
-      const childrenEntry = `children => ${macroName}()`
-      const allParts = [...propParts, childrenEntry]
-      return `<: macro ${macroName} -> () { :>${childrenBody}<: } :><: $bf.render_child('${tplName}', { ${allParts.join(', ')} }) | mark_raw :>`
+      currentEntries().push(`children => ${macroName}()`)
+      const dict = this.combineComponentPropSegments(segments)
+      return `<: macro ${macroName} -> () { :>${childrenBody}<: } :><: $bf.render_child('${tplName}', ${dict}) | mark_raw :>`
     }
 
-    const hashEntries = propParts.length > 0 ? `, { ${propParts.join(', ')} }` : ''
+    const isEmpty = segments.every(s => s.kind === 'entries' && s.parts.length === 0)
+    const hashEntries = isEmpty ? '' : `, ${this.combineComponentPropSegments(segments)}`
     return `<: $bf.render_child('${tplName}'${hashEntries}) | mark_raw :>`
   }
 
@@ -1327,6 +1500,17 @@ export class XslateAdapter extends BaseAdapter implements IRNodeEmitter<XslateRe
           const qArgs = queryHrefArgs(node, n => this.renderParsedExprToKolon(n))
           return `$bf.query(${qArgs.join(', ')})`
         }
+        // Generic `helper-call` (#2069) — the neutral vocabulary's escape
+        // hatch for a userland `LoweringPlugin` that lowers to a single
+        // runtime-helper invocation. `$bf.<helper>(args…)` mirrors the
+        // `query` helper's own naming convention exactly: the framework
+        // renders the call, the plugin author registers `<helper>` as a
+        // Kolon-callable method on the `$bf` vars entry in their own
+        // runtime — same contract as `$bf.query` itself, just not built in.
+        if (node?.kind === 'helper-call' && isValidHelperId(node.helper)) {
+          const argsX = node.args.map(a => this.renderParsedExprToKolon(a))
+          return `$bf.${node.helper}(${argsX.join(', ')})`
+        }
       }
     }
 

package/src/conformance-pins.ts

@@ -0,0 +1,112 @@
+/**
+ * Per-fixture build-time contracts for shapes the Xslate adapter
+ * intentionally refuses to lower. Mirrors mojo's set — the lowering
+ * gates are shared code paths in the ported adapter. Consumed by this
+ * package's own conformance test (as `expectedDiagnostics`) and by
+ * `bf compat` (issue-URL attribution).
+ */
+
+import type { ConformancePins } from '@barefootjs/jsx'
+
+export const conformancePins: ConformancePins = {
+  // Sibling-imported child component in a loop body: emits a
+  // cross-template call needing separate registration. BF103 makes
+  // the requirement loud (same as mojo).
+  'static-array-children': [{ code: 'BF103', severity: 'error' }],
+  // TodoApp / TodoAppSSR import `TodoItem` from a sibling file and
+  // call it inside a keyed `.map`. With the standalone-filter fix in
+  // place these reach the SAME BF103 (imported child in `.map`) as
+  // mojo — NOT BF101 — confirming the `.filter(...)` chain itself now
+  // lowers and the only remaining gate is the imported-child one.
+  'todo-app': [{ code: 'BF103', severity: 'error' }],
+  'todo-app-ssr': [{ code: 'BF103', severity: 'error' }],
+  // `([emoji, users]) => ...` / `([id, t]) => ...` are plain array-index
+  // (tuple) destructures, no rest — #2087 Phase B's `segments`-walking
+  // accessor lowers both to `$__bf_item[0]` / `$__bf_item[1]` `: my` locals
+  // like any other fixed binding, so BF104 no longer fires for either
+  // fixture. Each now hits a DIFFERENT, pre-existing, orthogonal gap
+  // instead: the loop array (`entries`) is a function-scope local const
+  // with a computed initializer (`Object.entries(props.x ?? {}).filter(...)`)
+  // that the adapter can't bind as a template variable — see the dedicated
+  // `arrayConst` BF101 check in `renderLoop`. This was always true; it was
+  // simply unreachable before because BF104 refused the destructure shape
+  // first.
+  'static-array-from-props': [{ code: 'BF101', severity: 'error' }],
+  // Both BF103 (sibling-imported `<Tag>` child component) and the BF101
+  // above fire; BF104 no longer does (see above).
+  'static-array-from-props-with-component': [
+    { code: 'BF103', severity: 'error' },
+    { code: 'BF101', severity: 'error' },
+  ],
+  // #1310 / #2087: rest destructure in .map() callback. All four shapes now
+  // lower via #2087 Phase B's `segments`-walking accessor:
+  //   - object-rest read via member access (`rest-destructure-object-in-map`):
+  //     `$bf.omit($__bf_item, [...exclude keys...])`, `$rest.flag` reads the
+  //     residual hashref.
+  //   - object-rest spread onto the root element
+  //     (`rest-destructure-object-spread-in-map`): same `$bf.omit(...)`
+  //     residual, forwarded via the existing `$bf.spread_attrs($rest)` path.
+  //   - array-rest (`rest-destructure-array-in-map`): `$bf.slice($__bf_item,
+  //     N, nil)` — the same runtime helper `.slice()` JS-method calls use.
+  //   - nested rest inside an object pattern (`rest-destructure-nested-in-map`):
+  //     the parent-prefix accessor (`$__bf_item.cells`) feeds the same
+  //     `$bf.slice(...)` call.
+  // None of these are pinned here anymore.
+  // (button/kbd graduated: the site/ui Button/Kbd `<Slot>` `{...props}` /
+  // `{...children.props}` component-spread now lowers via Kolon's builtin
+  // `.merge(...)` method chain — see `xslate-adapter.ts`'s
+  // `renderComponent` — instead of refusing with BF101, so these two no
+  // longer need a pin here.)
+  // #1467 demo-corpus context providers (`radio-group`, `select`,
+  // `dropdown-menu`, `combobox`, `command`) are no longer pinned — an
+  // object-literal provider value (`{ value: currentValue,
+  // onValueChange: (v) => {…} }`) lowers to a Kolon hashref via
+  // `parseProviderObjectLiteral` (#1897): getter members snapshot
+  // their body's SSR value, handler / function-shaped members lower
+  // to `nil`. The command demo's `ref={(el) => {…}}` function prop on
+  // an imported component is skipped at SSR like `on*` handlers.
+  //
+  // #1467 Phase 2e: `data-table` is no longer pinned here — it
+  // compiles clean now (`selected()[index]` → `index-access`,
+  // `.toFixed(2)` → `$bf.to_fixed`, `/* @client */` memo SSR-folded)
+  // and renders to Hono parity on real Text::Xslate. The keyed-loop
+  // scope-ID divergence (#1896) was fixed by the body-children
+  // `inLoop` reset (loop-item children get `_bf_slot`); data-table is
+  // off `skipJsx` entirely and only kept in `skipMarkerConformance`
+  // below for the shared `/* @client */` keyed-map slot-id elision
+  // contract (same as `todo-app`), not a render or BF101 gap.
+  // `style-3-signals` / `style-object-dynamic` no longer pinned — a
+  // `style={{ … }}` object literal now lowers to a CSS string with dynamic
+  // values interpolated (`background-color:<: $color :>;padding:8px`) via
+  // `tryLowerStyleObject` (#1322).
+  // (`tagged-template-classname` graduated by #2092 — the tag resolves
+  // through the interleave-tag catalogue and desugars to an untagged
+  // template literal, so it lowers like any other className template.)
+  // #2038: a filter predicate whose body contains a NESTED callback call
+  // (`t => !picked().some(p => …)` / `t => picked().find(p => …)`). Kolon
+  // has no inline `grep` form, so `XslateFilterEmitter.callbackMethod` used
+  // to degrade the inner call to its receiver, silently changing predicate
+  // semantics — the compiler is loud instead of lossy. (Mojo is pinned only
+  // for the `.find` variant: it lowers a nested `.some` to a real inline
+  // Perl `grep`.) The `/* @client */` twin
+  // (`filter-nested-callback-predicate-client`) has no pin here: it must
+  // render clean on every adapter, which asserts the suppression contract.
+  // https://github.com/piconic-ai/barefootjs/issues/2038
+  'filter-nested-callback-predicate': [
+    { code: 'BF101', severity: 'error', issue: 'https://github.com/piconic-ai/barefootjs/issues/2038' },
+  ],
+  'filter-nested-find-predicate': [
+    { code: 'BF101', severity: 'error', issue: 'https://github.com/piconic-ai/barefootjs/issues/2038' },
+  ],
+  // NB: TOP-LEVEL `.find` / `.findIndex` / `.findLast` / `.findLastIndex`
+  // (text position) are NOT pinned here — unlike mojo (which refuses them),
+  // Xslate lowers them to `$bf.find` / `find_index` / `find_last` /
+  // `find_last_index` via the same Kolon-lambda mechanism as `.filter` /
+  // `.every` / `.some`, so they render. Only the NESTED-in-a-predicate form
+  // above is refused (#2038).
+  // #2073 follow-up: a function-reference `.map(format)` callback has no
+  // arrow body to serialize — not a CALLBACK_METHODS shape — so the
+  // UNSUPPORTED_METHODS gate refuses it with BF101 rather than emitting
+  // a broken template.
+  'array-map-function-reference': [{ code: 'BF101', severity: 'error' }],
+}

package/src/index.ts

@@ -6,3 +6,4 @@
 
 export { XslateAdapter, xslateAdapter } from './adapter/index.ts'
 export type { XslateAdapterOptions } from './adapter/index.ts'
+export { conformancePins } from './conformance-pins.ts'