@barefootjs/xslate 0.16.0 → 0.17.0

package/lib/BarefootJS/Backend/Xslate.pm

@@ -1,5 +1,5 @@
 package BarefootJS::Backend::Xslate;
-our $VERSION = "0.15.2";
+our $VERSION = "0.16.0";
 use strict;
 use warnings;
 use utf8;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/xslate",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Text::Xslate (Kolon) adapter for BarefootJS — compiles IR to .tx templates and ships the Xslate rendering backend; runs under any PSGI/Plack app",
   "type": "module",
   "main": "./dist/index.js",
@@ -55,14 +55,14 @@
     "directory": "packages/adapter-xslate"
   },
   "dependencies": {
-    "@barefootjs/shared": "0.16.0"
+    "@barefootjs/shared": "0.17.0"
   },
   "peerDependencies": {
     "@barefootjs/jsx": ">=0.2.0"
   },
   "devDependencies": {
     "@barefootjs/adapter-tests": "0.1.0",
-    "@barefootjs/jsx": "0.16.0",
+    "@barefootjs/jsx": "0.17.0",
     "typescript": "^5.0.0"
   }
 }

package/src/__tests__/query-href.test.ts

@@ -0,0 +1,96 @@
+/**
+ * `queryHref(base, { … })` → `$bf.query(...)` lowering for the Xslate adapter
+ * (#2042). Parity with the go-template / Mojo lowering: the call + object literal
+ * are structured IR, so it lowers directly. The shared `query` runtime helper
+ * (BarefootJS.pm) includes a pair iff its guard is truthy AND its value is a
+ * non-empty string, so a plain `key: v` passes guard `1` and a conditional
+ * `key: cond ? v : undefined` passes the lowered condition.
+ */
+import { describe, test, expect } from 'bun:test'
+import { compileJSX, type ComponentIR } from '@barefootjs/jsx'
+import { XslateAdapter } from '../adapter/xslate-adapter'
+
+function template(src: string): string {
+  const a = new XslateAdapter()
+  const r = compileJSX(src.trimStart(), 'T.tsx', { adapter: a, outputIR: true })
+  const ir = JSON.parse(r.files.find(f => f.type === 'ir')!.content) as ComponentIR
+  return a.generate(ir).template
+}
+
+describe('queryHref → $bf.query (Xslate, #2042)', () => {
+  test('a plain value passes guard 1', () => {
+    const t = template(`
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string; tag: string }) {
+  return <a href={queryHref(props.base, { tag: props.tag })}>x</a>
+}
+`)
+    expect(t).toContain("$bf.query($base, 1, 'tag', $tag)")
+  })
+
+  test('a conditional include passes the lowered condition as the guard', () => {
+    const t = template(`
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string; sort: string; tag: string }) {
+  return <a href={queryHref(props.base, { sort: props.sort !== 'date' ? props.sort : undefined, tag: props.tag })}>x</a>
+}
+`)
+    // Kolon uses `!=` for string inequality (no `ne` operator).
+    expect(t).toContain("$bf.query($base, ($sort != 'date'), 'sort', $sort, 1, 'tag', $tag)")
+  })
+
+  // A bare-value guard (`flag ? v : undefined`) is JS *string* truthiness — `'0'`
+  // is a truthy string in JS but false under Perl's `unless`. The lowering must
+  // normalise it to a non-empty-string test so SSR matches the client / go (where
+  // `lowerUrlGuard` emits `ne <value> ""`). Kolon renders the `!== ''` test as
+  // `!= ''` (its string inequality), matching the comparison guard above.
+  test('a bare-value guard is normalised to a non-empty-string test', () => {
+    const t = template(`
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string; flag: string; val: string }) {
+  return <a href={queryHref(props.base, { q: props.flag ? props.val : undefined })}>x</a>
+}
+`)
+    expect(t).toContain("$bf.query($base, ($flag != ''), 'q', $val)")
+  })
+
+  // An array value (`{ tag: props.tags }`) lowers to the bare slice expression;
+  // the shared Perl `query` helper detects the arrayref at runtime and appends
+  // one pair per non-empty member (#2048). No adapter-side change beyond passing
+  // the value through.
+  test('an array value passes the slice expression for the helper to append', () => {
+    const t = template(`
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string; tags: string[] }) {
+  return <a href={queryHref(props.base, { tag: props.tags })}>x</a>
+}
+`)
+    expect(t).toContain("$bf.query($base, 1, 'tag', $tags)")
+  })
+
+  test('an aliased import is recognised', () => {
+    const t = template(`
+'use client'
+import { queryHref as qh } from '@barefootjs/client'
+export function P(props: { base: string; tag: string }) {
+  return <a href={qh(props.base, { tag: props.tag })}>x</a>
+}
+`)
+    expect(t).toContain("$bf.query($base, 1, 'tag', $tag)")
+  })
+
+  test('a dynamic (non-literal) params object falls back (no $bf.query)', () => {
+    const t = template(`
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string; q: Record<string, string> }) {
+  return <a href={queryHref(props.base, props.q)}>x</a>
+}
+`)
+    expect(t).not.toContain('.query')
+  })
+})

package/src/__tests__/xslate-adapter.test.ts

@@ -291,3 +291,58 @@ export function C() {
     expect(deferred.template).not.toContain('data-x')
   })
 })
+
+// #2018 P2: higher-order predicates lower through the runtime evaluator
+// (`$bf.*_eval`), isomorphic with the Go / Mojo `*_eval` helpers. A predicate
+// the evaluator can't model (a method-call predicate) falls back to the Kolon
+// lambda runtime call. Template-text pins guard against silent divergence.
+describe('XslateAdapter - higher-order predicate lowering (#2018 P2)', () => {
+  test('a serializable predicate lowers to $bf.filter_eval with the JSON body + env', () => {
+    // A standalone `.filter().length` exercises the higher-order emitter (the
+    // `.filter().map()` form is a loop-hoist with an inline `: if`, handled by
+    // renderLoop, not this emitter).
+    const { template } = compileAndGenerate(`
+function A({ items }: { items: { done: boolean }[] }) {
+  return <div>{items.filter(x => x.done).length}</div>
+}
+export { A }
+`)
+    expect(template).toContain('$bf.filter_eval(')
+    expect(template).toContain('"property":"done"')
+    expect(template).toContain("'x'")
+  })
+
+  test('.find / .findLast share $bf.find_eval, distinguished by the forward flag', () => {
+    const find = compileAndGenerate(`
+function A({ items }: { items: { done: boolean }[] }) {
+  return <div>{items.find(x => x.done) ? 'y' : 'n'}</div>
+}
+export { A }
+`).template
+    expect(find).toContain('$bf.find_eval(')
+    expect(find).toContain(', 1, {})')
+
+    const findLast = compileAndGenerate(`
+function A({ items }: { items: { done: boolean }[] }) {
+  return <div>{items.findLast(x => x.done) ? 'y' : 'n'}</div>
+}
+export { A }
+`).template
+    expect(findLast).toContain('$bf.find_eval(')
+    expect(findLast).toContain(', 0, {})')
+  })
+
+  test('a method-call predicate falls back to the Kolon-lambda runtime call', () => {
+    const { template } = compileAndGenerate(`
+function A({ items }: { items: { name: string }[] }) {
+  return <div>{items.every(x => x.name.includes('a')) ? 'y' : 'n'}</div>
+}
+export { A }
+`)
+    // No evaluator helper — the unsupported predicate keeps the `-> $x { … }`
+    // lambda form passed to the runtime `$bf.every`.
+    expect(template).not.toContain('every_eval')
+    expect(template).toContain('$bf.every(')
+    expect(template).toContain('-> $x {')
+  })
+})

package/src/adapter/analysis/component-tree.ts

@@ -0,0 +1,123 @@
+/**
+ * Component-tree analysis for the Text::Xslate (Kolon) template adapter.
+ *
+ * Extracted from `xslate-adapter.ts` (domain-module refactor, issue #2018
+ * track D). Pure functions over the IR — they read no adapter instance
+ * state. `collectImportedLoopChildComponentErrors` returns its diagnostics
+ * instead of pushing onto the adapter's error list, so the adapter stays the
+ * sole owner of `errors`.
+ *
+ * SHARED CANDIDATE: `hasClientInteractivity` is byte-identical to the Mojo
+ * adapter's copy and adapter-agnostic; the BF103 loop-child check is the same
+ * structural walk in both, differing only in the Perl/Kolon diagnostic text —
+ * both are groundwork for a shared Perl-family codegen module (issue #2018
+ * track D).
+ */
+
+import type {
+  ComponentIR,
+  IRNode,
+  IRComponent,
+  IRElement,
+  IRFragment,
+  IRConditional,
+  IRLoop,
+  IRIfStatement,
+  IRProvider,
+  IRAsync,
+  CompilerError,
+} from '@barefootjs/jsx'
+
+/**
+ * Whether the component needs the client runtime — it owns reactive state
+ * (signals / effects / onMount) or the analyzer flagged it as needing init.
+ */
+export function hasClientInteractivity(ir: ComponentIR): boolean {
+  return (
+    ir.metadata.signals.length > 0 ||
+    ir.metadata.effects.length > 0 ||
+    ir.metadata.onMounts.length > 0 ||
+    (ir.metadata.clientAnalysis?.needsInit ?? false)
+  )
+}
+
+/**
+ * Build a `BF103` diagnostic for every component reference inside a loop body
+ * whose name is imported from a relative-path module. Mirror of the Go
+ * adapter's check — the Xslate adapter has the same cross-template-registration
+ * constraint at request time. Returns the diagnostics so the caller pushes
+ * them onto its own error list.
+ */
+export function collectImportedLoopChildComponentErrors(
+  ir: ComponentIR,
+  componentName: string,
+): CompilerError[] {
+  const errors: CompilerError[] = []
+  const relativeImports = new Set<string>()
+  for (const imp of ir.metadata.templateImports ?? ir.metadata.imports ?? []) {
+    if (!imp.source.startsWith('./') && !imp.source.startsWith('../')) continue
+    if (imp.isTypeOnly) continue
+    for (const spec of imp.specifiers) {
+      relativeImports.add(spec.alias ?? spec.name)
+    }
+  }
+  if (relativeImports.size === 0) return errors
+
+  const loc = { file: componentName + '.tsx', start: { line: 1, column: 0 }, end: { line: 1, column: 0 } }
+  const visit = (node: IRNode, inLoop: boolean): void => {
+    switch (node.type) {
+      case 'component': {
+        const comp = node as IRComponent
+        if (inLoop && relativeImports.has(comp.name)) {
+          errors.push({
+            code: 'BF103',
+            severity: 'error',
+            message: `Component <${comp.name}> is imported from a sibling module and used inside a loop. The Xslate adapter emits a cross-template call; the child template must be registered alongside the parent at render time.`,
+            loc: comp.loc ?? loc,
+            suggestion: {
+              message:
+                `Options:\n` +
+                `  1. Compile '${comp.name}' (its source file) with the same adapter and register the resulting Xslate template alongside the parent at render time.\n` +
+                `  2. Inline <${comp.name}> directly inside the loop body so no cross-file template lookup is needed.\n` +
+                `  3. Mark the loop position as @client-only so the template is materialised on the client instead of at SSR time.`,
+            },
+          })
+        }
+        for (const child of comp.children) visit(child, inLoop)
+        break
+      }
+      case 'element':
+        for (const child of (node as IRElement).children) visit(child, inLoop)
+        break
+      case 'fragment':
+        for (const child of (node as IRFragment).children) visit(child, inLoop)
+        break
+      case 'conditional': {
+        const cond = node as IRConditional
+        visit(cond.whenTrue, inLoop)
+        if (cond.whenFalse) visit(cond.whenFalse, inLoop)
+        break
+      }
+      case 'loop':
+        for (const child of (node as IRLoop).children) visit(child, true)
+        break
+      case 'if-statement': {
+        const stmt = node as IRIfStatement
+        visit(stmt.consequent, inLoop)
+        if (stmt.alternate) visit(stmt.alternate, inLoop)
+        break
+      }
+      case 'provider':
+        for (const child of (node as IRProvider).children) visit(child, inLoop)
+        break
+      case 'async': {
+        const a = node as IRAsync
+        visit(a.fallback, inLoop)
+        for (const child of a.children) visit(child, inLoop)
+        break
+      }
+    }
+  }
+  visit(ir.root, false)
+  return errors
+}

package/src/adapter/emit-context.ts

@@ -0,0 +1,104 @@
+/**
+ * The contract the extracted expression-emitter modules depend on instead of
+ * the concrete `XslateAdapter`.
+ *
+ * The Xslate adapter's top-level expression lowering is mutually recursive
+ * with the adapter's own const/record resolution and its filter-predicate
+ * emitter, so the extracted `XslateTopLevelEmitter` still needs to call back
+ * into shared per-compile state and recursive entry points. `XslateEmitContext`
+ * is that seam: the emitter takes a `XslateEmitContext` built by the adapter's
+ * private `emitCtx` getter (the adapter does NOT `implements` this interface,
+ * so the wrapped members stay private and off its exported public type —
+ * matching the Go adapter's `emitCtx`). The emitter depends on this narrow
+ * interface rather than the full ~2.5k-line class, so the coupling is explicit
+ * and it's unit-testable against a stub.
+ *
+ * Keep this surface minimal: add a member only when an extracted module
+ * genuinely needs it, so the seam documents the real cross-module coupling
+ * rather than re-exposing the whole adapter.
+ */
+
+import type { ParsedExpr, CompilerError, IRMetadata } from '@barefootjs/jsx'
+
+export interface XslateEmitContext {
+  /**
+   * (#1922) Local binding names the request-scoped `searchParams()` env signal
+   * is imported under. Non-empty enables the env-signal method-call lowering.
+   */
+  readonly _searchParamsLocals: Set<string>
+
+  /**
+   * Inline a module-scope pure string-literal const by name as the resolved
+   * literal value, or null when the name is not such a const.
+   */
+  _resolveModuleStringConst(name: string): string | null
+
+  /** Resolve a literal const (`const totalPages = 5`) to its Kolon value, or null. */
+  _resolveLiteralConst(name: string): string | null
+
+  /**
+   * Resolve a static property access on a module object-literal const
+   * (`variantClasses.ghost`) to its Kolon value at compile time, or null.
+   */
+  _resolveStaticRecordLiteral(objectName: string, key: string): string | null
+
+  /** Record a BF101 unsupported-expression diagnostic. */
+  _recordExprBF101(message: string, reason?: string): void
+
+  /** Lower a filter/predicate body to its Kolon form, bound to `param`. */
+  _renderKolonFilterExprPublic(expr: ParsedExpr, param: string): string
+}
+
+/**
+ * The contract the extracted object-literal / conditional-spread lowering
+ * (`spread/spread-codegen.ts`) depends on. The spread lowering recurses into
+ * the core expression lowering and records its own BF101 diagnostics, so it
+ * needs the recursive entry point plus the per-compile bookkeeping the
+ * adapter owns. Declared separately from `XslateEmitContext` so each
+ * extracted module's real coupling is documented precisely.
+ */
+export interface XslateSpreadContext {
+  /** Component name, for diagnostic source locations. */
+  readonly componentName: string
+
+  /** Per-compile diagnostic list the spread lowering appends to. */
+  readonly errors: CompilerError[]
+
+  /** Local-constant metadata, for resolving `Record[key]` spread values. */
+  readonly localConstants: IRMetadata['localConstants']
+
+  /** Prop params, for classifying a bare-identifier index as a prop. */
+  readonly propsParams: { name: string }[]
+
+  /**
+   * Lower a JS expression to its Kolon form (the core recursive entry).
+   *
+   * When the IR already carries a structured `ParsedExpr` tree, pass it as
+   * `preParsed` so the converter threads it straight through instead of
+   * re-parsing `expr` — mirrors go-template's
+   * `convertExpressionToGo(jsExpr, out?, preParsed?)`. With `preParsed` set,
+   * `expr` is unused for parsing (the converter derives any diagnostic text
+   * from the tree), so callers may pass `''`.
+   */
+  convertExpressionToKolon(expr: string, preParsed?: ParsedExpr): string
+}
+
+/**
+ * The contract the extracted in-template memo / context seeding
+ * (`memo/seed.ts`) depends on. The seed lowering recurses into the core
+ * expression lowering to compute a derived signal/memo value or a context
+ * default; that recursive entry is its only adapter coupling.
+ */
+export interface XslateMemoContext {
+  /**
+   * Lower a JS expression to its Kolon form (the core recursive entry).
+   *
+   * When the IR already carries a structured `ParsedExpr` tree, pass it as
+   * `preParsed` so the converter threads it straight through instead of
+   * re-parsing `expr` — mirrors go-template's
+   * `convertExpressionToGo(jsExpr, out?, preParsed?)`. With `preParsed` set,
+   * `expr` is unused for parsing (the converter derives any diagnostic text
+   * from the tree), so callers may pass `''`.
+   */
+  convertExpressionToKolon(expr: string, preParsed?: ParsedExpr): string
+}