@barefootjs/cli 0.15.1 → 0.16.0

package/dist/index.js

@@ -20959,6 +20959,76 @@ function turnToEventBinding(graph, events) {
   }
   return out;
 }
+function nextCommandsForSubscriber(fallbackComponent, subscriber) {
+  const cmds = [];
+  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;
+}
+function buildAgentFindings(component, hotSubscribers, wastedReReruns, batchAdvisor, unattributed) {
+  const findings = [];
+  for (const s of hotSubscribers.subscribers) {
+    if (!s.hot) continue;
+    findings.push({
+      kind: "hot-subscriber",
+      severity: "warning",
+      actionable: s.loc !== void 0,
+      subscriber: s.subscriber,
+      loc: s.loc,
+      message: `${s.name ?? s.subscriber} ran ${s.runsPerTurn.toFixed(1)}\xD7/turn \u2014 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 !== void 0,
+      subscriber: s.subscriber,
+      loc: s.loc,
+      message: `${s.name ?? s.subscriber} produced identical output in ${Math.round(s.wastedRatio * 100)}% of runs \u2014 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 !== void 0,
+      subscriber: c.turn,
+      loc: c.loc,
+      message: `${c.handler ?? c.turn} re-ran shared effects ${c.savings}\xD7 extra across ${c.writes} writes \u2014 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}" \u2014 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;
+}
 function buildProfileReport(input) {
   const { source, filePath, componentName, scenario, events } = input;
   const primary = buildComponentAnalysis(source, filePath, componentName).graph;
@@ -21037,6 +21107,27 @@ function buildProfileReport(input) {
       handlerIds.add(e.turn);
     }
   }
+  const findings = buildAgentFindings(primary.componentName, hotSubscribers, wastedReReruns, batchAdvisor, unattributed);
+  const status = findings.some((f) => f.severity === "warning" || f.severity === "error") ? "warning" : "ok";
+  const ratio = handlersTotal > 0 ? Math.min(1, handlerIds.size / handlersTotal) : 1;
+  let guidance;
+  if (turnSeqs.size === 0) {
+    guidance = handlersTotal === 0 ? {
+      reason: "no-handlers",
+      message: "No event handlers \u2014 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 \u2014 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 \u2014 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,
@@ -21051,12 +21142,16 @@ function buildProfileReport(input) {
     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 } : {}
   };
 }
 function formatProfileReport(r2) {
@@ -21083,8 +21178,66 @@ function formatProfileReport(r2) {
   if (c.diagnostics.count > 0) {
     lines.push(`  \xB7 ${c.diagnostics.count} anonymous runtime id(s) (non-actionable bookkeeping)`);
   }
+  lines.push("");
+  lines.push(`status: ${r2.status} (${r2.findings.length} finding(s))`);
+  if (r2.guidance) {
+    lines.push(`  guidance: ${r2.guidance.message}`);
+    lines.push(`  next: ${r2.guidance.nextCommands[0]}`);
+  } else if (r2.findings.length > 0) {
+    lines.push(`  next: ${r2.findings[0].nextCommands[0]}`);
+  }
   return lines.join("\n");
 }
+function evaluateProfileGates(report, config) {
+  const failOn = new Set(config.failOn ?? []);
+  const checks = [];
+  if (failOn.has("coverage") || config.minCoverage !== void 0) {
+    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 ? "\u2265" : "<"} required ${(threshold * 100).toFixed(0)}%`
+    });
+  }
+  if (failOn.has("unresolved") || config.maxUnresolved !== void 0) {
+    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 ? "\u2264" : ">"} allowed ${threshold}`
+    });
+  }
+  if (failOn.has("hot") || config.maxRunsPerTurn !== void 0) {
+    const observed = report.hotSubscribers.subscribers.reduce((m, s) => Math.max(m, s.runsPerTurn), 0);
+    if (config.maxRunsPerTurn !== void 0) {
+      const threshold = config.maxRunsPerTurn;
+      checks.push({
+        gate: "hot",
+        passed: observed <= threshold,
+        observed,
+        threshold,
+        message: `max ${observed.toFixed(1)} runs/turn ${observed <= threshold ? "\u2264" : ">"} budget ${threshold}`
+      });
+    } else {
+      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 };
+}
 var PROFILE_SCHEMA_VERSION, DEFAULT_FANOUT_THRESHOLD, DEFAULT_HOT_RUNS_PER_TURN, BAR_EIGHTHS, DEFAULT_WASTED_RATIO;
 var init_profiler = __esm({
   "../jsx/src/profiler.ts"() {
@@ -21786,6 +21939,7 @@ __export(src_exports, {
   emitParsedExpr: () => emitParsedExpr,
   enableCompilerInstrumentation: () => enableCompilerInstrumentation,
   evalStringArrayJoin: () => evalStringArrayJoin,
+  evaluateProfileGates: () => evaluateProfileGates,
   exprToString: () => exprToString,
   extractArrowBodyExpression: () => extractArrowBodyExpression,
   extractFunctionParams: () => extractFunctionParams,
@@ -104393,6 +104547,18 @@ __export(debug_profile_exports, {
 import { execFileSync as execFileSync2 } from "node:child_process";
 import { readFileSync as readFileSync19 } from "node:fs";
 import path24 from "node:path";
+function parseFailOn(raw) {
+  const parts = raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  if (parts.length === 0) fail("--fail-on requires at least one gate name.");
+  const out = [];
+  for (const p of parts) {
+    if (!GATE_NAMES.includes(p)) {
+      fail(`--fail-on: unknown gate "${p}" (expected ${GATE_NAMES.join(", ")}).`);
+    }
+    if (!out.includes(p)) out.push(p);
+  }
+  return out;
+}
 function parseFlags2(args2) {
   const flags = { positional: [] };
   const value2 = (args3, i, name2) => {
@@ -104419,6 +104585,10 @@ function parseFlags2(args2) {
     else if (a === "--top") flags.topN = num(args2, ++i, "--top", { integer: true, min: 1 });
     else if (a === "--hot-ms") flags.minMs = num(args2, ++i, "--hot-ms", { min: 0 });
     else if (a === "--wasted-pct") flags.wastedPct = num(args2, ++i, "--wasted-pct", { min: 0, max: 100 });
+    else if (a === "--fail-on") flags.failOn = parseFailOn(value2(args2, ++i, "--fail-on"));
+    else if (a === "--min-coverage") flags.minCoverage = num(args2, ++i, "--min-coverage", { min: 0, max: 1 });
+    else if (a === "--max-runs-per-turn") flags.maxRunsPerTurn = num(args2, ++i, "--max-runs-per-turn", { min: 0 });
+    else if (a === "--max-unresolved") flags.maxUnresolved = num(args2, ++i, "--max-unresolved", { integer: true, min: 0 });
     else if (a.startsWith("-")) fail(`Unknown flag "${a}".`);
     else flags.positional.push(a);
   }
@@ -104429,6 +104599,11 @@ function fail(message) {
   console.error(USAGE);
   process.exit(1);
 }
+function formatGates(g) {
+  const lines = [`gates: ${g.passed ? "PASS" : "FAIL"}`];
+  for (const c of g.checks) lines.push(`  ${c.passed ? "\u2713" : "\u2717"} ${c.gate}: ${c.message}`);
+  return lines.join("\n");
+}
 async function run22(args2, ctx2) {
   if (args2.includes("--help") || args2.includes("-h")) {
     console.log(HELP2);
@@ -104438,13 +104613,23 @@ async function run22(args2, ctx2) {
   if (flags.scenario && flags.diff) {
     fail("--scenario and --diff cannot be combined: --scenario measures a run, --diff compares two compiles. Pick one.");
   }
+  const wantsRegression = (flags.failOn ?? []).includes("regression");
+  const dynamicFailOn = (flags.failOn ?? []).filter((g) => g !== "regression");
+  const wantsDynamicGate = dynamicFailOn.length > 0 || flags.minCoverage !== void 0 || flags.maxRunsPerTurn !== void 0 || flags.maxUnresolved !== void 0;
+  if (wantsDynamicGate && !flags.scenario) {
+    fail("Coverage / unresolved / hot gates need a measured run \u2014 add --scenario auto|<file>.");
+  }
+  if (wantsRegression && !flags.diff) {
+    fail("--fail-on regression needs a compile comparison \u2014 add --diff <ref>.");
+  }
   const {
     buildStaticBudget: buildStaticBudget2,
     formatStaticBudget: formatStaticBudget2,
     diffStaticBudget: diffStaticBudget2,
     formatBudgetDiff: formatBudgetDiff2,
     buildProfileReport: buildProfileReport2,
-    formatProfileReport: formatProfileReport2
+    formatProfileReport: formatProfileReport2,
+    evaluateProfileGates: evaluateProfileGates2
   } = await Promise.resolve().then(() => (init_src2(), src_exports));
   const componentName = flags.positional[0];
   if (!componentName) {
@@ -104488,12 +104673,22 @@ async function run22(args2, ctx2) {
         // `--wasted-pct` is a percentage on the CLI; the analysis takes a [0,1] fraction.
         wastedRatio: flags.wastedPct !== void 0 ? flags.wastedPct / 100 : void 0
       });
+      const gateConfig = {
+        failOn: dynamicFailOn,
+        minCoverage: flags.minCoverage,
+        maxRunsPerTurn: flags.maxRunsPerTurn,
+        maxUnresolved: flags.maxUnresolved
+      };
+      const gates = wantsDynamicGate ? evaluateProfileGates2(report, gateConfig) : void 0;
+      if (gates && !gates.passed) report.status = "error";
       if (ctx2.jsonFlag) {
-        console.log(JSON.stringify(report, null, 2));
+        console.log(JSON.stringify(gates ? { ...report, gates } : report, null, 2));
       } else {
         console.log(formatProfileReport2(report));
         if (fired === 0) console.log("  note: no interactive elements were found to fire.");
+        if (gates) console.log("\n" + formatGates(gates));
       }
+      if (gates && !gates.passed) process.exit(1);
     } catch (err) {
       console.error(`Error: ${err.message}`);
       process.exit(1);
@@ -104515,10 +104710,24 @@ async function run22(args2, ctx2) {
       fanOutThreshold: flags.fanOutThreshold
     });
     const diff = diffStaticBudget2(base, head);
+    const gates = wantsRegression ? {
+      passed: !diff.regressed,
+      failed: diff.regressed ? ["regression"] : [],
+      checks: [
+        {
+          gate: "regression",
+          passed: !diff.regressed,
+          observed: diff.regressed ? 1 : 0,
+          threshold: 0,
+          message: diff.regressed ? "a reactivity metric regressed" : "no regression"
+        }
+      ]
+    } : void 0;
     if (ctx2.jsonFlag) {
-      console.log(JSON.stringify(diff, null, 2));
+      console.log(JSON.stringify(gates ? { ...diff, gates } : diff, null, 2));
     } else {
       console.log(formatBudgetDiff2(diff));
+      if (gates) console.log("\n" + formatGates(gates));
     }
     if (diff.regressed) process.exit(1);
     return;
@@ -104552,12 +104761,12 @@ function readFileAtRef(filePath, ref) {
     return gitError(err);
   }
 }
-var USAGE, HELP2;
+var USAGE, HELP2, GATE_NAMES;
 var init_debug_profile2 = __esm({
   "src/commands/debug-profile.ts"() {
     "use strict";
     init_resolve_source();
-    USAGE = "Usage: bf debug profile <component> [--diff <ref>] [--scenario auto|<file>] [--fanout <n>] [--top <n>] [--hot-ms <n>] [--wasted-pct <n>] [--json]";
+    USAGE = "Usage: bf debug profile <component> [--diff <ref>] [--scenario auto|<file>] [--fanout <n>] [--top <n>] [--hot-ms <n>] [--wasted-pct <n>] [--fail-on <gates>] [--min-coverage <r>] [--max-runs-per-turn <n>] [--max-unresolved <n>] [--json]";
     HELP2 = `bf debug profile \u2014 reactive performance profiler
 
 Find and fix wasted reactive work: re-runs that produce nothing, fan-out that
@@ -104621,6 +104830,25 @@ FLAGS
                       is additive-only. Stable schema with deterministic
                       tie-breaking; structural findings reproduce run-to-run
                       (wall-clock-timed ranks can shift near rounding boundaries).
+                      A dynamic run also carries \`status\`, normalized \`findings\`
+                      (severity + actionable + nextCommands), and \u2014 when handlers
+                      were under-exercised \u2014 \`guidance\` pointing at a story file.
+
+AGENT GATES (CI pass/fail with intent)
+  By default a run never fails CI. Opt into a gate and the command exits non-zero
+  when it trips, emitting a \`gates\` block ({passed, failed, checks}) in --json and
+  escalating \`status\` to "error". Gates compose with --json so an agent decides
+  fail-vs-continue without parsing prose.
+
+  --fail-on <gates>        Comma-separated: unresolved,hot,coverage (need
+                           --scenario) and regression (needs --diff). Each uses its
+                           default threshold unless a numeric flag below overrides.
+  --min-coverage <r>       Fail when coverage ratio < r (0\u20131). Implies the
+                           coverage gate. Needs --scenario.
+  --max-runs-per-turn <n>  Fail when the hottest subscriber exceeds n runs/turn.
+                           Implies the hot gate. Needs --scenario.
+  --max-unresolved <n>     Fail when more than n unresolved (actionable) coverage
+                           gaps remain. Implies the unresolved gate. Needs --scenario.
 
 EXAMPLES
   bf debug profile calendar                       # static budget, no run
@@ -104628,6 +104856,8 @@ EXAMPLES
   bf debug profile calendar --scenario auto --top 5 --hot-ms 1
   bf debug profile checkout --scenario ./stories/checkout.tsx --json
   bf debug profile checkout --diff origin/main    # regression gate (CI)
+  bf debug profile calendar --scenario auto --min-coverage 0.8 --fail-on hot --json
+  bf debug profile checkout --diff origin/main --fail-on regression --json
 
 NOTES
   \u2022 Instrumentation is dev-only and is stripped from production builds.
@@ -104635,6 +104865,7 @@ NOTES
     static budget and --diff need no build.
   \u2022 Composes with \`bf debug graph/trace/why-update\`: those say *where to look*,
     profile says *what it cost and what to change*, citing the same source lines.`;
+    GATE_NAMES = ["unresolved", "hot", "coverage", "regression"];
   }
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/cli",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "description": "CLI for agent-driven UI component discovery and scaffolding",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,11 +29,11 @@
   "dependencies": {
     "esbuild": "^0.25.0",
     "typescript": "^5.0.0",
-    "@barefootjs/client": "0.15.1",
-    "@barefootjs/shared": "0.15.1"
+    "@barefootjs/client": "0.16.0",
+    "@barefootjs/shared": "0.16.0"
   },
   "devDependencies": {
-    "@barefootjs/jsx": "0.15.1",
+    "@barefootjs/jsx": "0.16.0",
     "@types/node": "^22.0.0",
     "@happy-dom/global-registrator": "^20.0.11",
     "happy-dom": "^20.0.11"