@barefootjs/jsx 0.15.2 → 0.17.0

package/src/__tests__/ir-reduce-op.test.ts

@@ -1,21 +1,21 @@
 import { describe, test, expect } from 'bun:test'
 import { analyzeComponent } from '../analyzer'
 import { jsxToIR } from '../jsx-to-ir'
-import { parseExpression } from '../expression-parser'
+import { parseExpression, asCallbackMethodCall } from '../expression-parser'
 
 /**
- * IR-level verification for `.reduce(fn, init)` (#1448 Tier C). The
- * parser intercepts the arithmetic-fold catalogue into a structured
- * `array-method` + `ReduceOp` node — this test pins the source-string
- * that survives through `jsxToIR` to an `IRExpression`, then re-parses
- * it to confirm the structured fold shape adapters consume.
+ * IR-level verification for `.reduce(fn, init)` (#2018 P5). The parser no
+ * longer folds the reducer into a structured `ReduceOp`; `.reduce` arrives as a
+ * generic `call` whose callee is `<recv>.reduce` and whose args are the
+ * comparator `arrow` + the init literal. The adapter serializes the arrow body
+ * to the runtime evaluator. This test pins that the generic callback shape
+ * survives the analyzer → IR boundary.
  *
- * Hydration and template-emit correctness are pinned at the adapter
- * conformance layer (`reduce-*` fixtures in `packages/adapter-tests/
- * fixtures/methods/`).
+ * Hydration / template-emit / Go==Perl==JS fold correctness are pinned at the
+ * adapter conformance + eval-vectors layers.
  */
 describe('reduce(fn, init) IR shape', () => {
-  test('sum over a struct field re-parses to a numeric ReduceOp', () => {
+  test('sum over a struct field parses to a generic reduce callback', () => {
     const source = `
       'use client'
       import { createSignal } from '@barefootjs/client'
@@ -35,17 +35,14 @@ describe('reduce(fn, init) IR shape', () => {
     expect(exprNode?.type).toBe('expression')
     if (exprNode?.type !== 'expression') return
 
-    // The IR carries the expression as a source string (the same shape
-    // adapters re-parse at emit time). Round-trip it to confirm the
-    // ReduceOp catalogue match survives the analyzer → IR boundary.
     const parsed = parseExpression(exprNode.expr)
-    expect(parsed.kind).toBe('array-method')
-    if (parsed.kind !== 'array-method') return
-    expect(parsed.method).toBe('reduce')
-    if (parsed.method !== 'reduce') return
-    expect(parsed.reduceOp.op).toBe('+')
-    expect(parsed.reduceOp.key).toEqual({ kind: 'field', field: 'duration' })
-    expect(parsed.reduceOp.type).toBe('numeric')
-    expect(parsed.reduceOp.init).toBe('0')
+    const cb = asCallbackMethodCall(parsed)
+    expect(cb).not.toBeNull()
+    expect(cb!.method).toBe('reduce')
+    expect(cb!.arrow.params).toEqual(['sum', 't'])
+    // Reducer body: `sum + t.duration`.
+    expect(cb!.arrow.body.kind).toBe('binary')
+    // The init literal travels as the trailing argument.
+    expect(cb!.args).toEqual([{ kind: 'literal', value: 0, literalType: 'number', raw: '0' }])
   })
 })

package/src/__tests__/ir-sort-comparator.test.ts

@@ -1,6 +1,7 @@
 import { describe, test, expect } from 'bun:test'
 import { analyzeComponent } from '../analyzer'
 import { jsxToIR } from '../jsx-to-ir'
+import { sortComparatorFromArrow } from '../expression-parser'
 
 describe('sort().map() / toSorted().map()', () => {
   test('sort((a, b) => a.price - b.price).map() produces sortComparator (asc)', () => {
@@ -31,11 +32,10 @@ describe('sort().map() / toSorted().map()', () => {
       expect(loop).toBeDefined()
       if (loop?.type === 'loop') {
         expect(loop.sortComparator).toBeDefined()
-        expect(loop.sortComparator!.keys).toHaveLength(1)
-        expect(loop.sortComparator!.keys[0].key).toEqual({ kind: 'field', field: 'price' })
-        expect(loop.sortComparator!.keys[0].type).toBe('numeric')
-        expect(loop.sortComparator!.keys[0].direction).toBe('asc')
-        expect(loop.sortComparator!.method).toBe('sort')
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys).toHaveLength(1)
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys[0].key).toEqual({ kind: 'field', field: 'price' })
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys[0].type).toBe('numeric')
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys[0].direction).toBe('asc')
         expect(loop.sortComparator!.paramA).toBe('a')
         expect(loop.sortComparator!.paramB).toBe('b')
         expect(loop.array).toBe('products()')
@@ -70,11 +70,10 @@ describe('sort().map() / toSorted().map()', () => {
       expect(loop).toBeDefined()
       if (loop?.type === 'loop') {
         expect(loop.sortComparator).toBeDefined()
-        expect(loop.sortComparator!.keys).toHaveLength(1)
-        expect(loop.sortComparator!.keys[0].key).toEqual({ kind: 'field', field: 'price' })
-        expect(loop.sortComparator!.keys[0].type).toBe('numeric')
-        expect(loop.sortComparator!.keys[0].direction).toBe('desc')
-        expect(loop.sortComparator!.method).toBe('toSorted')
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys).toHaveLength(1)
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys[0].key).toEqual({ kind: 'field', field: 'price' })
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys[0].type).toBe('numeric')
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys[0].direction).toBe('desc')
       }
     }
   })
@@ -107,10 +106,10 @@ describe('sort().map() / toSorted().map()', () => {
         expect(loop.filterPredicate).toBeDefined()
         expect(loop.filterPredicate!.param).toBe('t')
         expect(loop.sortComparator).toBeDefined()
-        expect(loop.sortComparator!.keys).toHaveLength(1)
-        expect(loop.sortComparator!.keys[0].key).toEqual({ kind: 'field', field: 'priority' })
-        expect(loop.sortComparator!.keys[0].type).toBe('numeric')
-        expect(loop.sortComparator!.keys[0].direction).toBe('asc')
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys).toHaveLength(1)
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys[0].key).toEqual({ kind: 'field', field: 'priority' })
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys[0].type).toBe('numeric')
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys[0].direction).toBe('asc')
         expect(loop.chainOrder).toBe('filter-sort')
         expect(loop.array).toBe('todos()')
       }
@@ -176,7 +175,7 @@ describe('sort().map() / toSorted().map()', () => {
       expect(loop?.type).toBe('loop')
       if (loop?.type === 'loop') {
         expect(loop.sortComparator).toBeDefined()
-        expect(loop.sortComparator!.keys).toEqual([
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys).toEqual([
           { key: { kind: 'field', field: 'price' }, type: 'numeric', direction: 'desc' },
           { key: { kind: 'field', field: 'name' }, type: 'string', direction: 'asc' },
         ])
@@ -209,7 +208,7 @@ describe('sort().map() / toSorted().map()', () => {
       const loop = ir!.children.find(c => c.type === 'loop')
       if (loop?.type === 'loop') {
         expect(loop.sortComparator).toBeDefined()
-        expect(loop.sortComparator!.keys).toEqual([
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys).toEqual([
           { key: { kind: 'field', field: 'rank' }, type: 'auto', direction: 'asc' },
         ])
       }
@@ -241,7 +240,7 @@ describe('sort().map() / toSorted().map()', () => {
       const loop = ir!.children.find(c => c.type === 'loop')
       if (loop?.type === 'loop') {
         expect(loop.sortComparator).toBeDefined()
-        expect(loop.sortComparator!.keys).toEqual([
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys).toEqual([
           { key: { kind: 'self' }, type: 'auto', direction: 'asc' },
         ])
       }
@@ -273,7 +272,7 @@ describe('sort().map() / toSorted().map()', () => {
       const loop = ir!.children.find(c => c.type === 'loop')
       if (loop?.type === 'loop') {
         expect(loop.sortComparator).toBeDefined()
-        expect(loop.sortComparator!.keys).toEqual([
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys).toEqual([
           { key: { kind: 'field', field: 'price' }, type: 'numeric', direction: 'asc' },
         ])
         // block body unwraps to the returned expression, keeping the
@@ -310,7 +309,7 @@ describe('sort().map() / toSorted().map()', () => {
         expect(loop.sortComparator).toBeDefined()
         // The `=== ? 0` arm is a tie; direction comes from the inner
         // relational ternary (a.rank > b.rank ? 1 : -1 → ascending).
-        expect(loop.sortComparator!.keys).toEqual([
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys).toEqual([
           { key: { kind: 'field', field: 'rank' }, type: 'auto', direction: 'asc' },
         ])
       }
@@ -342,7 +341,7 @@ describe('sort().map() / toSorted().map()', () => {
       const loop = ir!.children.find(c => c.type === 'loop')
       if (loop?.type === 'loop') {
         expect(loop.sortComparator).toBeDefined()
-        expect(loop.sortComparator!.keys).toEqual([
+        expect(sortComparatorFromArrow(loop.sortComparator!.arrow)!.keys).toEqual([
           { key: { kind: 'field', field: 'price' }, type: 'numeric', direction: 'asc' },
           { key: { kind: 'field', field: 'rank' }, type: 'auto', direction: 'asc' },
         ])

package/src/__tests__/lowering-registry.test.ts

@@ -0,0 +1,141 @@
+/**
+ * Lowering-plugin registry (#2057) — the one seam every lowering flows through.
+ * These tests guarantee the mechanism works: a registered plugin's matcher is
+ * bound per-component and produces a backend-neutral node, and the registry gates
+ * on the plugin's own import recognition. They use a standalone SAMPLE plugin so
+ * they exercise the mechanism itself, independent of the built-in plugins (like
+ * `queryHref`) the compiler registers by default — see `builtin-lowering-plugins`.
+ */
+
+import { describe, test, expect, afterEach } from 'bun:test'
+import {
+  registerLoweringPlugin,
+  getLoweringPlugins,
+  prepareLoweringMatchers,
+  matchLoweringCall,
+  __resetLoweringPluginsForTest,
+  type LoweringPlugin,
+  type IRMetadata,
+  type ParsedExpr,
+} from '../index'
+
+// A minimal sample plugin: active only when the component imports anything from
+// `@sample/pkg`, and lowers a `demo(...)` call to a neutral `helper-call` node.
+// This is exactly the shape a first-party / userland package would register.
+const samplePlugin: LoweringPlugin = {
+  name: 'sample-demo',
+  prepare(metadata) {
+    const active = metadata.imports.some(i => i.source === '@sample/pkg' && !i.isTypeOnly)
+    if (!active) return null
+    return (callee, args) =>
+      callee.kind === 'identifier' && callee.name === 'demo'
+        ? { kind: 'helper-call', helper: 'demo', args }
+        : null
+  },
+}
+
+function metadataImporting(source: string): IRMetadata {
+  return {
+    imports: [{ source, isTypeOnly: false, specifiers: [] }],
+  } as unknown as IRMetadata
+}
+
+const demoCall = { kind: 'identifier', name: 'demo' } as ParsedExpr
+const otherCall = { kind: 'identifier', name: 'other' } as ParsedExpr
+const arg = { kind: 'literal', value: 'x', literalType: 'string' } as ParsedExpr
+
+// Keep the global registry clean between tests (the sample must not leak into
+// other suites that assert on the registered set).
+afterEach(() => {
+  const remaining = getLoweringPlugins().filter(p => p.name !== 'sample-demo')
+  __resetLoweringPluginsForTest(remaining)
+})
+
+describe('lowering-plugin registry', () => {
+  test('registerLoweringPlugin adds the plugin; getLoweringPlugins returns a copy', () => {
+    registerLoweringPlugin(samplePlugin)
+    const plugins = getLoweringPlugins()
+    expect(plugins.some(p => p.name === 'sample-demo')).toBe(true)
+    // Mutating the returned array can't corrupt the registry.
+    ;(plugins as LoweringPlugin[]).length = 0
+    expect(getLoweringPlugins().some(p => p.name === 'sample-demo')).toBe(true)
+  })
+
+  test('re-registering the same name replaces, not duplicates (idempotent)', () => {
+    registerLoweringPlugin(samplePlugin)
+    registerLoweringPlugin(samplePlugin)
+    expect(getLoweringPlugins().filter(p => p.name === 'sample-demo')).toHaveLength(1)
+  })
+
+  test('prepare gates on the plugin recognising its own import', () => {
+    registerLoweringPlugin(samplePlugin)
+    // Active: component imports from @sample/pkg.
+    expect(prepareLoweringMatchers(metadataImporting('@sample/pkg'))).toHaveLength(1)
+    // Inactive: unrelated import → no matcher, so the adapter skips it entirely.
+    expect(prepareLoweringMatchers(metadataImporting('react'))).toHaveLength(0)
+  })
+
+  test('a bound matcher lowers a recognised call to its neutral node', () => {
+    registerLoweringPlugin(samplePlugin)
+    const [matcher] = prepareLoweringMatchers(metadataImporting('@sample/pkg'))
+    expect(matcher(demoCall, [arg])).toEqual({ kind: 'helper-call', helper: 'demo', args: [arg] })
+    // A call the plugin doesn't recognise is declined (→ generic lowering).
+    expect(matcher(otherCall, [arg])).toBeNull()
+  })
+
+  test('matchLoweringCall tries all registered plugins for the metadata', () => {
+    registerLoweringPlugin(samplePlugin)
+    expect(matchLoweringCall(demoCall, [arg], metadataImporting('@sample/pkg'))).toEqual({
+      kind: 'helper-call',
+      helper: 'demo',
+      args: [arg],
+    })
+    // No plugin recognises this metadata → null (the built-in queryHref plugin
+    // is inactive here — a `react` import isn't `@barefootjs/client`).
+    expect(matchLoweringCall(demoCall, [arg], metadataImporting('react'))).toBeNull()
+  })
+})
+
+describe('built-in plugins are applied by default', () => {
+  // `queryHref` is a built-in plugin the compiler registers on load — no
+  // `registerLoweringPlugin` call in the test. Importing `@barefootjs/jsx`
+  // (the import above) is what registers it, so it's present here for free.
+  const queryHrefCall = { kind: 'identifier', name: 'queryHref' } as ParsedExpr
+  const base = { kind: 'literal', value: '/x', literalType: 'string' } as ParsedExpr
+  const tagValue = { kind: 'literal', value: 'a', literalType: 'string' } as ParsedExpr
+  const paramsObj = {
+    kind: 'object-literal',
+    raw: '{ tag: "a" }',
+    properties: [{ key: 'tag', shorthand: false, value: tagValue }],
+  } as ParsedExpr
+
+  function importingQueryHref(): IRMetadata {
+    return {
+      imports: [
+        {
+          source: '@barefootjs/client',
+          isTypeOnly: false,
+          specifiers: [{ name: 'queryHref', alias: null, isDefault: false, isNamespace: false }],
+        },
+      ],
+    } as unknown as IRMetadata
+  }
+
+  test('queryHref is registered without any explicit registerLoweringPlugin call', () => {
+    expect(getLoweringPlugins().some(p => p.name === 'queryHref')).toBe(true)
+  })
+
+  test('a queryHref(base, { … }) call lowers to a neutral guard-list on the `query` helper', () => {
+    const node = matchLoweringCall(queryHrefCall, [base, paramsObj], importingQueryHref())
+    expect(node).toEqual({
+      kind: 'guard-list',
+      helper: 'query',
+      base,
+      triples: [{ guard: null, key: 'tag', value: tagValue }],
+    })
+  })
+
+  test('the built-in stays inert when the component does not import queryHref', () => {
+    expect(matchLoweringCall(queryHrefCall, [base, paramsObj], metadataImporting('react'))).toBeNull()
+  })
+})

package/src/__tests__/primitive-resolver-alias.test.ts

@@ -100,6 +100,29 @@ describe('reactive primitive resolver — alias fidelity (checker path)', () =>
     expect(ctx.signals[0].initialValue).toBe('0')
   })
 
+  test('import { createSearchParams as csp }: csp() is recognized as an env signal', () => {
+    // #2057: the env-signal factory resolves through the same alias path as
+    // createSignal. The signal must be tagged `envReader` and carry the
+    // as-written callee (`csp`) so client/SSR emit `csp()`, not the canonical
+    // name — and validateReactiveFactoryCalls must NOT raise BF110 for it.
+    const filePath = path.resolve(CLIENT_DIR, '../.bench-env-alias-test.tsx')
+    const source = `
+      import { createSearchParams as csp } from '@barefootjs/client'
+      export function SortLabel() {
+        const [sp] = csp()
+        return <p>{sp().get('sort') ?? 'none'}</p>
+      }
+    `
+    const program = programFor(filePath, source)
+    const ctx = analyzeComponent(source, filePath, undefined, program)
+    expect(ctx.signals).toHaveLength(1)
+    expect(ctx.signals[0].getter).toBe('sp')
+    expect(ctx.signals[0].envReader).toBe('search')
+    expect(ctx.signals[0].envFactory).toBe('csp')
+    // No spurious BF110 (unrecognized reactive factory) for the aliased call.
+    expect(ctx.errors.some(e => e.code === 'BF110')).toBe(false)
+  })
+
   test('user-defined function named createSignal is NOT misclassified without checker', () => {
     // Without a checker, the fast path still matches by name. This
     // documents the limitation — the fast path is optimistic. A shared

package/src/__tests__/profiler.test.ts

@@ -20,6 +20,7 @@ import {
   buildIdIndex,
   joinProfilerEvents,
   findUninstrumentedEffects,
+  evaluateProfileGates,
 } from '../profiler'
 import { buildComponentAnalysis } from '../debug'
 import type { ProfilerEvent } from '@barefootjs/shared'
@@ -533,3 +534,151 @@ describe('findUninstrumentedEffects (#1849 B6)', () => {
     expect(e1.candidates).toEqual([{ file: 'C.tsx', line: 8 }])
   })
 })
+
+describe('agent contract: status, findings, guidance (#1841)', () => {
+  const src = `
+    'use client'
+    import { createSignal, createMemo } from '@barefootjs/client'
+    export function Calc() {
+      const [count, setCount] = createSignal(0)
+      const a = createMemo(() => count() * 2)
+      return <button onClick={() => setCount(count() + 1)}>{a()}</button>
+    }
+  `
+  let n = 0
+  const ev = (type: ProfilerEvent['type'], f: Partial<ProfilerEvent> = {}): ProfilerEvent =>
+    ({ type, seq: n++, turn: null, ...f })
+
+  // A memo that re-runs 3× in a single turn → runsPerTurn 3 → flagged `hot`.
+  function hotRunEvents(): ProfilerEvent[] {
+    n = 0
+    const turn = 'Calc#handler:s0:click'
+    const events: ProfilerEvent[] = [ev('turnBegin', { handlerId: turn })]
+    for (let i = 0; i < 3; i++) {
+      events.push(ev('effectEnter', { subscriber: 'Calc#memo:a', turn }))
+      events.push(ev('effectExit', { subscriber: 'Calc#memo:a', dur: 1, turn }))
+    }
+    events.push(ev('turnEnd', {}))
+    return events
+  }
+
+  test('a clean run is status ok with no findings', () => {
+    n = 0
+    // One memo run in a turn → runsPerTurn 1 → not hot, nothing flagged.
+    const turn = 'Calc#handler:s0:click'
+    const events: ProfilerEvent[] = [
+      ev('turnBegin', { handlerId: turn }),
+      ev('effectEnter', { subscriber: 'Calc#memo:a', turn }),
+      ev('effectExit', { subscriber: 'Calc#memo:a', dur: 1, turn }),
+      ev('turnEnd', {}),
+    ]
+    const r = buildProfileReport({ source: src, filePath: 'Calc.tsx', scenario: 'auto', events })
+    expect(r.status).toBe('ok')
+    expect(r.findings).toHaveLength(0)
+    expect(r.coverage.ratio).toBe(1)
+    expect(r.guidance).toBeUndefined()
+  })
+
+  test('a hot subscriber becomes a warning finding with valid nextCommands', () => {
+    const r = buildProfileReport({ source: src, filePath: 'Calc.tsx', scenario: 'auto', events: hotRunEvents() })
+    expect(r.status).toBe('warning')
+    const hot = r.findings.find(f => f.kind === 'hot-subscriber')!
+    expect(hot.severity).toBe('warning')
+    expect(hot.actionable).toBe(true)
+    expect(hot.subscriber).toBe('Calc#memo:a')
+    // A memo id maps to a name `bf debug trace` accepts; graph is the fallback.
+    expect(hot.nextCommands).toContain('bf debug trace Calc a --json')
+    expect(hot.nextCommands).toContain('bf debug graph Calc --json')
+  })
+
+  test('an unresolved id is an actionable coverage-gap finding', () => {
+    n = 0
+    // A profiler-shaped id with no matching IR node → SR4 coverage gap.
+    const events: ProfilerEvent[] = [ev('effectEnter', { subscriber: 'Calc#memo:ghost' })]
+    const r = buildProfileReport({ source: src, filePath: 'Calc.tsx', scenario: 'auto', events })
+    const gap = r.findings.find(f => f.kind === 'coverage-gap')!
+    expect(gap.actionable).toBe(true)
+    expect(gap.subscriber).toBe('Calc#memo:ghost')
+  })
+
+  test('nextCommands target the component parsed from the id, not the root', () => {
+    n = 0
+    // A scenario-file run resolves subscribers from composed children: the id's
+    // component (`Child`) differs from the profiled root (`Calc`). Follow-up
+    // commands must target `Child`, or they point an agent at the wrong file.
+    const events: ProfilerEvent[] = [ev('effectEnter', { subscriber: 'Child#memo:ghost' })]
+    const r = buildProfileReport({ source: src, filePath: 'Calc.tsx', scenario: 'auto', events })
+    const gap = r.findings.find(f => f.kind === 'coverage-gap')!
+    expect(gap.nextCommands).toContain('bf debug trace Child ghost --json')
+    expect(gap.nextCommands).toContain('bf debug graph Child --json')
+    expect(gap.nextCommands.every(c => !c.includes('graph Calc'))).toBe(true)
+  })
+
+  test('coverage.ratio is clamped to 1 when the stream over-counts handlers', () => {
+    n = 0
+    // Calc exposes a single handler (handlersTotal 1), but a malformed stream
+    // reports two distinct turn ids — without clamping the ratio would be 2.0
+    // and silently pass a `--min-coverage` gate it shouldn't.
+    const events: ProfilerEvent[] = [
+      ev('effectEnter', { subscriber: 'Calc#memo:a', turn: 'Calc#handler:s0:click' }),
+      ev('effectEnter', { subscriber: 'Calc#memo:a', turn: 'Calc#handler:s9:click' }),
+    ]
+    const r = buildProfileReport({ source: src, filePath: 'Calc.tsx', scenario: 'auto', events })
+    expect(r.coverage.ratio).toBe(1)
+    expect(r.coverage.ratio).toBeLessThanOrEqual(1)
+  })
+
+  test('a zero-turn run emits guidance pointing at a story file', () => {
+    n = 0
+    // Handlers exist (the onClick) but none fired → no-interactions guidance.
+    const events: ProfilerEvent[] = [ev('effectEnter', { subscriber: 'Calc#memo:a' })]
+    const r = buildProfileReport({ source: src, filePath: 'Calc.tsx', scenario: 'auto', events })
+    expect(r.turns).toBe(0)
+    expect(r.guidance?.reason).toBe('no-interactions')
+    expect(r.guidance?.nextCommands[0]).toContain('--scenario <story.tsx>')
+  })
+
+  describe('evaluateProfileGates', () => {
+    test('hot gate fails when a subscriber exceeds the runs/turn budget', () => {
+      const r = buildProfileReport({ source: src, filePath: 'Calc.tsx', scenario: 'auto', events: hotRunEvents() })
+      const fail = evaluateProfileGates(r, { maxRunsPerTurn: 2 })
+      expect(fail.passed).toBe(false)
+      expect(fail.failed).toContain('hot')
+      const pass = evaluateProfileGates(r, { maxRunsPerTurn: 5 })
+      expect(pass.passed).toBe(true)
+    })
+
+    test('bare --fail-on hot trips on any flagged hot subscriber', () => {
+      const r = buildProfileReport({ source: src, filePath: 'Calc.tsx', scenario: 'auto', events: hotRunEvents() })
+      const g = evaluateProfileGates(r, { failOn: ['hot'] })
+      expect(g.passed).toBe(false)
+      expect(g.checks[0].threshold).toBeNull()
+    })
+
+    test('coverage gate compares ratio against --min-coverage', () => {
+      n = 0
+      // Handlers exist but only mount runs, no turn → ratio 0.
+      const events: ProfilerEvent[] = [ev('effectEnter', { subscriber: 'Calc#memo:a' })]
+      const r = buildProfileReport({ source: src, filePath: 'Calc.tsx', scenario: 'auto', events })
+      expect(r.coverage.ratio).toBe(0)
+      const g = evaluateProfileGates(r, { minCoverage: 0.8 })
+      expect(g.passed).toBe(false)
+      expect(g.failed).toContain('coverage')
+    })
+
+    test('unresolved gate counts actionable gaps against --max-unresolved', () => {
+      n = 0
+      const events: ProfilerEvent[] = [ev('effectEnter', { subscriber: 'Calc#memo:ghost' })]
+      const r = buildProfileReport({ source: src, filePath: 'Calc.tsx', scenario: 'auto', events })
+      expect(evaluateProfileGates(r, { maxUnresolved: 0 }).passed).toBe(false)
+      expect(evaluateProfileGates(r, { maxUnresolved: 5 }).passed).toBe(true)
+    })
+
+    test('no configured gate yields an empty, passing result', () => {
+      const r = buildProfileReport({ source: src, filePath: 'Calc.tsx', scenario: 'auto', events: hotRunEvents() })
+      const g = evaluateProfileGates(r, {})
+      expect(g.passed).toBe(true)
+      expect(g.checks).toHaveLength(0)
+    })
+  })
+})

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

@@ -0,0 +1,58 @@
+/**
+ * `queryHrefLocalNames` — recognises the `queryHref` import (incl. aliases) so
+ * adapters can gate the `queryHref(base, { … })` → query-helper lowering (#2042).
+ */
+import { describe, test, expect } from 'bun:test'
+import { compileJSX, queryHrefLocalNames, type ComponentIR } from '../index'
+import { TestAdapter } from '../adapters/test-adapter'
+
+function metadata(src: string): ComponentIR['metadata'] {
+  const result = compileJSX(src.trimStart(), 'T.tsx', { adapter: new TestAdapter(), outputIR: true })
+  const ir = JSON.parse(result.files.find(f => f.type === 'ir')!.content) as ComponentIR
+  return ir.metadata
+}
+
+describe('queryHrefLocalNames (#2042)', () => {
+  test('recognises a plain queryHref import', () => {
+    const md = metadata(`
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string }) {
+  return <a href={queryHref(props.base, {})}>x</a>
+}
+`)
+    expect([...queryHrefLocalNames(md)]).toEqual(['queryHref'])
+  })
+
+  test('binds to the local alias', () => {
+    const md = metadata(`
+'use client'
+import { queryHref as qh } from '@barefootjs/client'
+export function P(props: { base: string }) {
+  return <a href={qh(props.base, {})}>x</a>
+}
+`)
+    expect([...queryHrefLocalNames(md)]).toEqual(['qh'])
+  })
+
+  test('recognises the @barefootjs/client/runtime re-export too', () => {
+    // `queryHref` is exported from both entries; importing from the runtime entry
+    // must still enable SSR lowering, else the call hits BF101.
+    const md = metadata(`
+'use client'
+import { queryHref } from '@barefootjs/client/runtime'
+export function P(props: { base: string }) {
+  return <a href={queryHref(props.base, {})}>x</a>
+}
+`)
+    expect([...queryHrefLocalNames(md)]).toEqual(['queryHref'])
+  })
+
+  test('is empty when not imported', () => {
+    const md = metadata(`
+'use client'
+export function P() { return <a href="/x">x</a> }
+`)
+    expect(queryHrefLocalNames(md).size).toBe(0)
+  })
+})