@barefootjs/jsx 0.15.2 → 0.17.0

package/src/profiler.ts

@@ -1360,6 +1360,13 @@ export interface ProfileCoverage {
   handlersFired: number
   /** Handlers the IR knows about (`buildEventSummary`). */
   handlersTotal: number
+  /**
+   * `handlersFired / handlersTotal` in `[0,1]` — the fraction of known handlers
+   * this run exercised, so an agent can gate on it (`--min-coverage`) without
+   * dividing the two counts itself (#1841). `1` when the component has no
+   * handlers (nothing to cover ⇒ trivially complete, not a gap).
+   */
+  ratio: number
   /** SR4 ids the IR could not resolve — the honest, actionable gap. */
   unattributed: UnattributedId[]
   /**
@@ -1386,6 +1393,79 @@ export interface ProfileReport {
   wastedReReruns: WastedReRunsResult
   batchAdvisor: BatchAdvisorResult
   coverage: ProfileCoverage
+  /**
+   * Normalized run status an agent can branch on without parsing prose (#1841):
+   * `ok` when nothing is flagged, `warning` when any finding is severity
+   * `warning` or higher — regardless of its `actionable` flag, since an
+   * unresolved-but-real cost (e.g. a hot subscriber with no source loc) is still
+   * worth surfacing. A failed *gate* escalates this to `error` — but gates are
+   * policy applied by the CLI from flags, so the builder only ever sets
+   * `ok`/`warning` here.
+   */
+  status: ProfileStatus
+  /**
+   * Flattened, normalized findings (#1841): the hot/wasted/batch/coverage tables
+   * re-expressed with a single `severity` scale, an explicit `actionable` flag,
+   * and `nextCommands` — the exact follow-up `bf debug …` invocations to run.
+   * The structured tables above stay the source of truth; this is the agent view.
+   */
+  findings: AgentFinding[]
+  /**
+   * Coverage guidance for an under-exercised run (#1841): present only when the
+   * scenario fired no or only some handlers, which usually means a story file is
+   * needed (handlers live in composed children).
+   */
+  guidance?: ScenarioGuidance
+}
+
+// -- Agent contract (#1841): normalized severity, actionable findings, guidance
+
+/** Normalized finding severity an agent can branch on without parsing prose. */
+export type ProfileSeverity = 'info' | 'warning' | 'error'
+
+/** Top-level run status: `ok` (clean), `warning` (findings), `error` (gate failed). */
+export type ProfileStatus = 'ok' | 'warning' | 'error'
+
+/**
+ * One normalized, machine-actionable finding flattened from the per-analysis
+ * tables (hot subscribers / wasted re-runs / batch advisor / coverage gaps).
+ * Carries the agent contract fields the issue asks for: a normalized `severity`,
+ * an explicit `actionable` flag (`false` ⇒ no safe direct fix — e.g. an
+ * unverified advisory), and `nextCommands` — valid, ready-to-run `bf debug …`
+ * follow-ups.
+ */
+export interface AgentFinding {
+  kind: 'hot-subscriber' | 'wasted-re-run' | 'batch-candidate' | 'coverage-gap'
+  severity: ProfileSeverity
+  /**
+   * Whether this finding has a concrete fix worth acting on directly. `false`
+   * marks a finding an agent should *not* apply blindly — an unverified `batch()`
+   * advisory (the wrap could change behavior) or a finding whose source location
+   * the id index couldn't resolve. A coverage gap is `actionable: true`: the next
+   * step (widen the scenario, inspect the graph) is clear even without a `loc`.
+   */
+  actionable: boolean
+  /** The compiler subscriber/turn id this finding is about, when it has one. */
+  subscriber?: string
+  /** Source location, when the id resolved to an IR node. */
+  loc?: { file: string; line: number }
+  /** One-line human summary — the same sentence the text report would print. */
+  message: string
+  /** Follow-up commands to run next — valid, ready-to-run `bf debug …` lines. */
+  nextCommands: string[]
+}
+
+/**
+ * Coverage guidance for an under-exercised run (#1841). `--scenario auto` can
+ * only fire handlers the IR exposes on *this* component; for a compound/context
+ * component whose handlers live in composed children it fires `0/N`, and the
+ * honest next step is a story/scenario file rather than trusting a thin run.
+ */
+export interface ScenarioGuidance {
+  /** Why coverage was incomplete — drives the suggested next step. */
+  reason: 'no-handlers' | 'no-interactions' | 'partial-coverage'
+  message: string
+  nextCommands: string[]
 }
 
 export interface ProfileReportInput {
@@ -1412,6 +1492,104 @@ export interface ProfileReportInput {
   wastedRatio?: number
 }
 
+/**
+ * The follow-up `bf debug …` commands an agent should run to investigate a
+ * subscriber finding (#1841). Every command is valid and ready to run: a
+ * memo/signal id resolves to a name `bf debug trace` accepts; a DOM-binding id
+ * resolves to a slotId `bf debug why-update` accepts; `bf debug graph` is always
+ * applicable, so it is the universal fallback.
+ *
+ * Commands target the component parsed *from the id* (`<Component>#…`), not the
+ * primary component — a scenario-file run resolves subscribers from composed
+ * children (`extraSources`), so a child's finding must point at the child. The
+ * passed `fallbackComponent` is used only for ids that don't parse (e.g. an
+ * anonymous `e1`).
+ */
+function nextCommandsForSubscriber(fallbackComponent: string, subscriber: string): string[] {
+  const cmds: string[] = []
+  const parsed = parseProfilerId(subscriber)
+  const component = parsed?.component ?? fallbackComponent
+  if (parsed) {
+    if (parsed.kind === 'memo' || parsed.kind === 'signal') {
+      cmds.push(`bf debug trace ${component} ${parsed.rest} --json`)
+    } else if (parsed.kind === 'binding') {
+      cmds.push(`bf debug why-update ${component} ${parsed.rest} --json`)
+    }
+  }
+  cmds.push(`bf debug graph ${component} --json`)
+  return cmds
+}
+
+/**
+ * Flatten the per-analysis tables into the normalized agent findings (#1841).
+ * Only *flagged* rows become findings — a hot subscriber that isn't `hot`, or a
+ * subscriber below the wasted threshold, is data in the tables but not something
+ * the agent must act on. Coverage gaps (unresolved ids) are actionable findings;
+ * the non-actionable bookkeeping ids stay in `coverage.diagnostics`.
+ */
+function buildAgentFindings(
+  component: string,
+  hotSubscribers: HotSubscribersResult,
+  wastedReReruns: WastedReRunsResult,
+  batchAdvisor: BatchAdvisorResult,
+  unattributed: readonly UnattributedId[],
+): AgentFinding[] {
+  const findings: AgentFinding[] = []
+  for (const s of hotSubscribers.subscribers) {
+    if (!s.hot) continue
+    findings.push({
+      kind: 'hot-subscriber',
+      severity: 'warning',
+      actionable: s.loc !== undefined,
+      subscriber: s.subscriber,
+      loc: s.loc,
+      message: `${s.name ?? s.subscriber} ran ${s.runsPerTurn.toFixed(1)}×/turn — re-run pressure (split or batch).`,
+      nextCommands: nextCommandsForSubscriber(component, s.subscriber),
+    })
+  }
+  for (const s of wastedReReruns.subscribers) {
+    if (!s.wasted) continue
+    findings.push({
+      kind: 'wasted-re-run',
+      severity: 'warning',
+      actionable: s.loc !== undefined,
+      subscriber: s.subscriber,
+      loc: s.loc,
+      message: `${s.name ?? s.subscriber} produced identical output in ${Math.round(s.wastedRatio * 100)}% of runs — finer split.`,
+      nextCommands: nextCommandsForSubscriber(component, s.subscriber),
+    })
+  }
+  for (const c of batchAdvisor.candidates) {
+    findings.push({
+      kind: 'batch-candidate',
+      // Only a *proven-safe* batch is advised as actionable warning; an
+      // unverified one is surfaced as info so an agent doesn't apply a wrap that
+      // could change behavior (mirrors the batch advisor's own safety gate).
+      severity: c.safety === 'safe' ? 'warning' : 'info',
+      actionable: c.safety === 'safe' && c.loc !== undefined,
+      subscriber: c.turn,
+      loc: c.loc,
+      message: `${c.handler ?? c.turn} re-ran shared effects ${c.savings}× extra across ${c.writes} writes — batch() candidate (${c.safety}).`,
+      // The turn id is `<Component>#handler:…` — for a scenario-file run it can be
+      // a composed child, so route through the helper to target the right one.
+      nextCommands: nextCommandsForSubscriber(component, c.turn),
+    })
+  }
+  for (const u of unattributed) {
+    findings.push({
+      kind: 'coverage-gap',
+      severity: 'warning',
+      actionable: true,
+      subscriber: u.id,
+      message: `Unresolved subscriber id "${u.id}" — could not map to source (scope caveat).`,
+      // `u.id` is shaped `<Component>#…` and may name a composed child — route
+      // through the helper so the command targets that component, not the root.
+      nextCommands: nextCommandsForSubscriber(component, u.id),
+    })
+  }
+  return findings
+}
+
 /**
  * Assemble a dynamic profile (SR1–SR4 + analyses, SR7) from a recorded event
  * stream. Pure: the DOM run that *produces* `events` lives in the driver (the
@@ -1524,6 +1702,41 @@ export function buildProfileReport(input: ProfileReportInput): ProfileReport {
     }
   }
 
+  const findings = buildAgentFindings(primary.componentName, hotSubscribers, wastedReReruns, batchAdvisor, unattributed)
+  // Status is measurement-only here: any warning/error finding ⇒ `warning`. A
+  // failed gate escalates to `error`, but gates are CLI policy (flags), so the
+  // builder never sets `error` itself.
+  const status: ProfileStatus = findings.some(f => f.severity === 'warning' || f.severity === 'error') ? 'warning' : 'ok'
+
+  // Coverage ratio: 1 when there is nothing to cover (no handlers), else the
+  // exercised fraction. Clamped to `[0,1]` — a malformed stream (more distinct
+  // turn ids than `buildEventSummary` knows about, e.g. missing `extraSources`)
+  // must not push the ratio past 1 and break a gate's assumptions. Drives
+  // `--min-coverage` and the guidance below.
+  const ratio = handlersTotal > 0 ? Math.min(1, handlerIds.size / handlersTotal) : 1
+  let guidance: ScenarioGuidance | undefined
+  if (turnSeqs.size === 0) {
+    guidance =
+      handlersTotal === 0
+        ? {
+            reason: 'no-handlers',
+            message: 'No event handlers — use the static budget instead of a dynamic run.',
+            nextCommands: [`bf debug profile ${primary.componentName} --json`],
+          }
+        : {
+            reason: 'no-interactions',
+            message:
+              'Handlers exist but none fired — they likely live in composed children. Drive the component with a story/scenario file.',
+            nextCommands: [`bf debug profile ${primary.componentName} --scenario <story.tsx> --json`],
+          }
+  } else if (ratio < 1) {
+    guidance = {
+      reason: 'partial-coverage',
+      message: `Only ${handlerIds.size}/${handlersTotal} handlers exercised — a story/scenario file can cover the rest.`,
+      nextCommands: [`bf debug profile ${primary.componentName} --scenario <story.tsx> --json`],
+    }
+  }
+
   return {
     kind: 'profile',
     schemaVersion: PROFILE_SCHEMA_VERSION,
@@ -1538,12 +1751,16 @@ export function buildProfileReport(input: ProfileReportInput): ProfileReport {
     coverage: {
       handlersFired: handlerIds.size,
       handlersTotal,
+      ratio,
       unattributed,
       // Roll the (potentially hundreds of) bookkeeping ids up to a count + a
       // small sample so JSON consumers aren't flooded (#1849 B7). `diagnostics`
       // is already sorted hottest-first by `joinProfilerEvents`.
       diagnostics: { count: diagnostics.length, sample: diagnostics.slice(0, 3).map(d => d.id) },
     },
+    status,
+    findings,
+    ...(guidance ? { guidance } : {}),
   }
 }
 
@@ -1579,5 +1796,116 @@ export function formatProfileReport(r: ProfileReport): string {
   if (c.diagnostics.count > 0) {
     lines.push(`  · ${c.diagnostics.count} anonymous runtime id(s) (non-actionable bookkeeping)`)
   }
+  // Agent contract footer (#1841): a normalized status and the single most
+  // useful next command, so a human reading the text output sees the same
+  // signal `--json` consumers branch on.
+  lines.push('')
+  lines.push(`status: ${r.status} (${r.findings.length} finding(s))`)
+  if (r.guidance) {
+    lines.push(`  guidance: ${r.guidance.message}`)
+    lines.push(`  next: ${r.guidance.nextCommands[0]}`)
+  } else if (r.findings.length > 0) {
+    lines.push(`  next: ${r.findings[0].nextCommands[0]}`)
+  }
   return lines.join('\n')
 }
+
+// -- Gates (#1841): turn a measured report into a pass/fail CI decision --------
+
+/** The gate names `--fail-on` accepts. `regression` applies to `--diff` mode. */
+export type GateName = 'unresolved' | 'hot' | 'coverage' | 'regression'
+
+/**
+ * Gate thresholds an agent/CI supplies via flags. A gate is *active* when it is
+ * named in `failOn` or its numeric threshold is set — so `--max-unresolved 0`
+ * enforces the unresolved gate without also passing `--fail-on unresolved`.
+ */
+export interface GateConfig {
+  failOn?: readonly GateName[]
+  /** `--min-coverage`: minimum `coverage.ratio` in `[0,1]`. */
+  minCoverage?: number
+  /** `--max-runs-per-turn`: budget for the hottest subscriber's runs/turn. */
+  maxRunsPerTurn?: number
+  /** `--max-unresolved`: maximum allowed unresolved (actionable) coverage gaps. */
+  maxUnresolved?: number
+}
+
+export interface GateCheck {
+  gate: GateName
+  passed: boolean
+  /** The measured value the gate compared (ratio, count, or runs/turn). */
+  observed: number
+  /** The threshold it was compared against; `null` for a boolean gate. */
+  threshold: number | null
+  message: string
+}
+
+export interface GateResult {
+  passed: boolean
+  /** Names of the gates that failed — the `gates.failed` an agent branches on. */
+  failed: GateName[]
+  checks: GateCheck[]
+}
+
+/**
+ * Evaluate the dynamic-run gates (#1841) against a measured report. Pure: maps a
+ * `ProfileReport` + thresholds to a pass/fail decision the CLI turns into an
+ * exit code. The `regression` gate is *not* evaluated here — it belongs to
+ * `--diff` mode, which the CLI gates directly off the `BudgetDiff`.
+ */
+export function evaluateProfileGates(report: ProfileReport, config: GateConfig): GateResult {
+  const failOn = new Set(config.failOn ?? [])
+  const checks: GateCheck[] = []
+
+  if (failOn.has('coverage') || config.minCoverage !== undefined) {
+    const threshold = config.minCoverage ?? 1
+    const observed = report.coverage.ratio
+    checks.push({
+      gate: 'coverage',
+      passed: observed >= threshold,
+      observed,
+      threshold,
+      message: `coverage ${(observed * 100).toFixed(0)}% ${observed >= threshold ? '≥' : '<'} required ${(threshold * 100).toFixed(0)}%`,
+    })
+  }
+
+  if (failOn.has('unresolved') || config.maxUnresolved !== undefined) {
+    const threshold = config.maxUnresolved ?? 0
+    const observed = report.coverage.unattributed.length
+    checks.push({
+      gate: 'unresolved',
+      passed: observed <= threshold,
+      observed,
+      threshold,
+      message: `${observed} unresolved id(s) ${observed <= threshold ? '≤' : '>'} allowed ${threshold}`,
+    })
+  }
+
+  if (failOn.has('hot') || config.maxRunsPerTurn !== undefined) {
+    const observed = report.hotSubscribers.subscribers.reduce((m, s) => Math.max(m, s.runsPerTurn), 0)
+    if (config.maxRunsPerTurn !== undefined) {
+      // Numeric budget: the hottest subscriber must not exceed it.
+      const threshold = config.maxRunsPerTurn
+      checks.push({
+        gate: 'hot',
+        passed: observed <= threshold,
+        observed,
+        threshold,
+        message: `max ${observed.toFixed(1)} runs/turn ${observed <= threshold ? '≤' : '>'} budget ${threshold}`,
+      })
+    } else {
+      // Bare `--fail-on hot`: any subscriber the analysis flagged `hot` fails it.
+      const anyHot = report.hotSubscribers.subscribers.some(s => s.hot)
+      checks.push({
+        gate: 'hot',
+        passed: !anyHot,
+        observed,
+        threshold: null,
+        message: anyHot ? `hot subscriber(s) present (max ${observed.toFixed(1)} runs/turn)` : 'no hot subscribers',
+      })
+    }
+  }
+
+  const failed = checks.filter(c => !c.passed).map(c => c.gate)
+  return { passed: failed.length === 0, failed, checks }
+}

package/src/query-href-lowering.ts

@@ -0,0 +1,147 @@
+/**
+ * Backend-neutral destructuring of a recognised `queryHref(base, { … })` call
+ * (#2042) into a base expression plus include triples, shared by the SSR
+ * adapters' query lowering.
+ *
+ * `queryHref` is the pure functional URL-query builder (the counterpart to
+ * `searchParams()`); its call + object literal are already structured IR, so an
+ * adapter lowers it to its query helper without any block-body recognition or
+ * re-parse. This module only does the structural match — turning the object
+ * literal's properties into `{ guard, key, value }` triples — leaving each
+ * adapter to format the include condition and the helper call in its own
+ * template language.
+ *
+ * Inclusion is truthy-omit over string values (matching the client `queryHref`'s
+ * `if (value)`): a plain `key: v` is included iff `v` is a non-empty string
+ * (`guard: null`); a conditional `key: cond ? a : <undefined|null|''>` is
+ * included iff `cond` AND `a` is non-empty (`guard: cond`, `value: a`).
+ */
+
+import type { ParsedExpr } from './expression-parser.ts'
+
+export interface QueryHrefTriple {
+  /**
+   * The conditional test of a `key: cond ? a : <omit>` include, or null for a
+   * plain `key: v` (which is included purely on value-truthiness). An adapter
+   * combines this with the value's non-emptiness to form the include condition.
+   */
+  guard: ParsedExpr | null
+  /** The literal search-param key. */
+  key: string
+  /** The value expression (the consequent for a conditional include). */
+  value: ParsedExpr
+}
+
+export interface QueryHrefCall {
+  base: ParsedExpr
+  triples: QueryHrefTriple[]
+}
+
+/**
+ * Match a `queryHref(base, { … })` call from its callee + args, returning the
+ * base and include triples, or null when it isn't a `queryHref` call with a
+ * plain object-literal second argument (→ the adapter falls back to its generic
+ * lowering). `localNames` are the bindings `queryHref` is imported under (from
+ * `queryHrefLocalNames`).
+ */
+export function matchQueryHrefCall(
+  callee: ParsedExpr,
+  args: readonly ParsedExpr[],
+  localNames: ReadonlySet<string>,
+): QueryHrefCall | null {
+  if (callee.kind !== 'identifier' || !localNames.has(callee.name)) return null
+  if (args.length !== 2) return null
+  const [base, obj] = args
+  // A dynamic (non-literal) params object can't be lowered to static include
+  // triples — fall back to the generic lowering.
+  if (obj.kind !== 'object-literal') return null
+
+  const triples: QueryHrefTriple[] = []
+  for (const p of obj.properties) {
+    const v = p.value
+    if (v.kind === 'conditional' && isOmitBranch(v.alternate)) {
+      triples.push({ guard: v.test, key: p.key, value: v.consequent })
+    } else {
+      triples.push({ guard: null, key: p.key, value: v })
+    }
+  }
+  return { base, triples }
+}
+
+/**
+ * Format a {@link QueryHrefCall} as the flat argument list for a guard-list
+ * query helper (`bf->query(base, guard, key, value, …)` in Mojo / `$bf.query(…)`
+ * in Xslate — the two adapters whose helper does the non-empty check itself).
+ * Each triple contributes a guard (`'1'` for a plain include, or the lowered
+ * condition for a conditional one), the key as a string literal, and the value —
+ * all lowered through the adapter's `emit`. The caller wraps the result in its
+ * own `<helper>(…)` call. (The go-template adapter folds the non-empty check
+ * into the include condition itself, so it formats its own form instead.)
+ *
+ * A conditional guard that is NOT already boolean-shaped (a bare value, a member
+ * access, `&&`/`||`) is JS *string* truthiness — `'0'` is a truthy string in JS
+ * but false under Perl's `unless`. To keep SSR byte-identical to the client (and
+ * to the go adapter, whose `lowerUrlGuard` does the same), such a guard is
+ * normalised to a `guard !== ''` test, emitted against a string literal so each
+ * adapter renders string `ne`, not numeric `!=`. Comparisons / `!x` / boolean
+ * literals already yield a real boolean and pass through unchanged.
+ */
+export function queryHrefArgs(q: QueryHrefCall, emit: (e: ParsedExpr) => string): string[] {
+  const out = [emit(q.base)]
+  for (const t of q.triples) {
+    if (t.guard === null) {
+      out.push('1')
+    } else if (isBoolShapeGuard(t.guard)) {
+      out.push(`(${emit(t.guard)})`)
+    } else {
+      const test: ParsedExpr = {
+        kind: 'binary',
+        op: '!==',
+        left: t.guard,
+        right: { kind: 'literal', value: '', literalType: 'string' },
+      }
+      out.push(`(${emit(test)})`)
+    }
+    out.push(emit({ kind: 'literal', value: t.key, literalType: 'string' }))
+    out.push(emit(t.value))
+  }
+  return out
+}
+
+const GUARD_BOOL_OPS: ReadonlySet<string> = new Set([
+  '==',
+  '===',
+  '!=',
+  '!==',
+  '<',
+  '>',
+  '<=',
+  '>=',
+])
+
+/**
+ * Whether a conditional-include guard already evaluates to a real boolean, so it
+ * can be emitted as-is rather than wrapped in a `!== ''` string-truthiness test.
+ * A comparison, a `!negation`, or a boolean literal qualifies; a bare value /
+ * member / `&&` / `||` does not. Mirrors the go adapter's `lowerUrlGuard`
+ * `isBoolShape` so the four backends agree on which guards need normalising.
+ */
+function isBoolShapeGuard(g: ParsedExpr): boolean {
+  return (
+    (g.kind === 'binary' && GUARD_BOOL_OPS.has(g.op)) ||
+    (g.kind === 'unary' && g.op === '!') ||
+    (g.kind === 'literal' && g.literalType === 'boolean')
+  )
+}
+
+/**
+ * The falsy "omit" branch of a conditional include — `undefined` (an identifier),
+ * `null`, or `''` — which makes `cond ? v : <omit>` a conditional include.
+ */
+function isOmitBranch(node: ParsedExpr): boolean {
+  if (node.kind === 'identifier') return node.name === 'undefined'
+  if (node.kind === 'literal') {
+    return node.literalType === 'null' || (node.literalType === 'string' && node.value === '')
+  }
+  return false
+}

package/src/ssr-defaults.ts

@@ -143,6 +143,10 @@ export function extractSsrDefaults(metadata: IRMetadata): Record<string, SsrDefa
   }
   for (const sig of metadata.signals) {
     if (!sig.getter || sig.isModule) continue
+    // Env signals (#2057) have no static SSR default — their value is the
+    // request-scoped reader, seeded by the adapter's env-signal binding, not a
+    // baked initial value.
+    if (sig.envReader) continue
     const value = tryStaticEval(sig.initialValue, { bindings, propsLike })
     out[sig.getter] = { value: resultToJsonable(value) }
     bindings[sig.getter] = value
@@ -169,7 +173,7 @@ export function extractSsrDefaults(metadata: IRMetadata): Record<string, SsrDefa
   if (metadata.propsObjectName !== null) {
     const referenced = new Set<string>()
     for (const sig of metadata.signals) {
-      if (!sig.getter || sig.isModule) continue
+      if (!sig.getter || sig.isModule || sig.envReader) continue
       collectPropRefs(sig.initialValue, metadata.propsObjectName, referenced)
     }
     for (const memo of metadata.memos) {