@ticket-gate/react 0.0.0-stage → 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,89 @@
-# Temporary Holding Version
+# @ticket-gate/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The React Compiler bailout ratchet for `@ticket-gate/engine`. `compiler.mjs` exports `reactCompiler(options)`, which runs
+`babel-plugin-react-compiler` over the `.ts` and `.tsx` files of the configured scan directories and compares what the compiler
+could not compile with a baseline file. A new bailout, a skipped component or hook, or a stale baseline entry fails the check.
+
+Every project value (scan directories, exclude pattern, where `@babel/core` and the plugin resolve from, baseline path, message
+texts) is an option. The package has no runtime dependency beyond the engine: `@babel/core` and `babel-plugin-react-compiler` are
+resolved from the consuming project at call time.
+
+## Profiling a React app
+
+`ticket-gate profile` counts what React renders during one scripted action. It reads React's own performance tracks from a Chrome
+trace: Scheduler (Render and Commit) and Components (one entry per component that rendered). It measures React DOM apps; LWC is not
+covered.
+
+```
+ticket-gate profile [--build] [--runs=N] [--scenarios=] [--out=] [--compare=] [--max-renders=]
+```
+
+The command is added by `reactPack({ profile })`, where `profile` is a function returning the config below; the config is loaded only
+when the command runs. `viteProfiling({ cmd, preview })` describes the build and the preview server of a Vite app, which must alias
+`react-dom/client` to `react-dom/profiling` and set `esbuild.keepNames` in its own Vite config; a wrong build is caught by the trace
+guards, which fail the run with the fix instead of printing zeros. For Next.js use
+`{ ...nextProfiling({ app: 'web' }) }` from `@ticket-gate/supabase-next/profile-build.mjs`, and the Supabase reset and login hooks
+from `@ticket-gate/supabase-next/profile-hooks.mjs`. `lock: false` skips the stack lock for a caller that already holds it. Playwright
+comes from the project (`playwrightFrom` names the `package.json` that depends on it), never from this package, so it must be installed in the project at `playwrightFrom`.
+
+`profile.config.mjs`:
+
+```js
+import { viteProfiling } from '@ticket-gate/react/profile.mjs';
+
+const root = new URL('.', import.meta.url).pathname;
+
+export default {
+  root,
+  command: 'ticket-gate profile',
+  lock: 'profile:web',
+  scenarios: { home: async () => async () => {} },
+  writing: [],
+  componentsFor: () => ['Card', 'List'],
+  usage: { maxRenders: 'home:<n>' },
+  out: `${root}profile-out`,
+  tracePrefix: 'web-',
+  context: { viewport: { width: 1280, height: 800 } },
+  open: async () => {},
+  reset: async () => {},
+  playwrightFrom: `${root}package.json`,
+  appUrl: 'http://localhost:4173',
+  build: viteProfiling({ cmd: 'npm run build', preview: 'npm run preview' }),
+  messages: { expected: 'Card, List' },
+  preflight: { portInUse: 'port 4173 is in use', noApp: 'nothing on :4173: run with --build', noWebEnv: 'no app env' },
+  services: [],
+  probe: (url) => fetch(url).then(() => true, () => false),
+  hasEnv: () => true,
+};
+```
+
+`gate.config.mjs`:
+
+```js
+import { defineGate } from '@ticket-gate/engine';
+import { reactPack } from '@ticket-gate/react/index.mjs';
+
+export default defineGate({
+  steps: [],
+  packs: [reactPack({ profile: async () => (await import('./profile.config.mjs')).default })],
+});
+```
+
+## Profiling every night
+
+`reactProfile` from `@ticket-gate/react/profile.mjs` is a nightly suite runner. Put it in `nightly.suites` after the end-to-end suite, and give the suite entry `keep: runner.keep`, which is how the engine learns how many nights of traces to keep. `config` is the profile config module above, as a path relative to the worktree. Its `budgets` key is `{ [scenario]: { max, blocking? } }`, the largest median of component renders a scenario may have.
+
+A scenario over its budget makes the night amber until its entry says `blocking: true`; then the night is red and `ticket-gate nightly status` names the merges since the last green night. A run that leaves no numbers (the build failed, the trace guards fired, the child died) is red. A run cut short at `limitS` is printed as `red (cut-short)`. A scenario that stayed within its budget, and within 10% of itself, for seven nights gets a hint to promote it to `blocking: true`. Results are kept every night and traces for the newest `keepTraces` nights. A cut-short night has no results, because `results.json` is written only when the run ends; the traces it had written are dropped once `keepTraces` reported nights exist. The runner takes no stack lock because the nightly already holds it; it profiles in a child process so that `limitS` can stop it.
+
+```js
+import { reactProfile } from '@ticket-gate/react/profile.mjs';
+
+const runner = reactProfile({
+  config: 'profile.config.mjs',
+  runs: 1,
+  scenarios: 'all',
+  keepTraces: 3,
+});
+
+export const suite = { name: 'profile', runner, limitS: 2700, keep: runner.keep };
+```

package/compiler.mjs

@@ -0,0 +1,391 @@
+// React Compiler bailout ratchet, as a pack check. Runs babel-plugin-react-compiler
+// over every .ts/.tsx file of the configured scan dirs, the way the bundlers do, and
+// compares what it could not compile with a baseline file.
+//
+// A bailout (the compiler gave up on a function) that is not in the baseline fails
+// the check. So does a "skip": a top-level function named like a component or hook
+// that the compiler emitted no event for (compilationMode infer drops a use* hook
+// that calls no hook). A baseline entry whose function now compiles also fails, so
+// the baseline can only shrink by itself.
+//
+// Every project value (scan dirs, exclude pattern, where @babel/core and the plugin
+// resolve from, baseline path, message texts) is an option of reactCompiler().
+// run(argv) takes --update, --seed, --root=<dir>, --baseline=<path> and returns
+// { code, out, err }; it never prints and never exits.
+//
+// Exit codes: 0 green, 1 a new, stale, unreasoned or skipped function or a plugin-version
+// mismatch, 2 the plugin did not load or a file did not parse.
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+
+const PLUGIN = 'babel-plugin-react-compiler';
+export const COMPONENT_OR_HOOK = /^(use[A-Z0-9]|[A-Z])/;
+
+class CheckFailure extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+const fail = (code, message) => {
+  throw new CheckFailure(code, message);
+};
+
+/** `@babel/core` and the plugin as the first package of `via` resolves them, step by step. */
+function loadCompiler(repo, { from, via }, install) {
+  try {
+    let req = createRequire(join(repo, from, 'package.json'));
+    for (const spec of via) {
+      let dir = dirname(req.resolve(spec));
+      while (!existsSync(join(dir, 'package.json'))) dir = dirname(dir);
+      req = createRequire(join(dir, 'package.json'));
+    }
+    const pluginEntry = req.resolve(PLUGIN);
+    let pdir = dirname(pluginEntry);
+    const nameOf = (d) =>
+      existsSync(join(d, 'package.json'))
+        ? JSON.parse(readFileSync(join(d, 'package.json'), 'utf8')).name
+        : null;
+    while (nameOf(pdir) !== PLUGIN) pdir = dirname(pdir);
+    return {
+      babel: req('@babel/core'),
+      plugin: req(PLUGIN),
+      version: JSON.parse(readFileSync(join(pdir, 'package.json'), 'utf8'))
+        .version,
+    };
+  } catch (e) {
+    return fail(
+      2,
+      `could not load @babel/core and ${PLUGIN} through ${via.at(-1)} (${e.message}). Run \`${install}\`.`,
+    );
+  }
+}
+
+const isFn = (n) =>
+  n &&
+  (n.type === 'FunctionDeclaration' ||
+    n.type === 'FunctionExpression' ||
+    n.type === 'ArrowFunctionExpression');
+
+const sameStart = (node, loc) =>
+  node.loc?.start.line === loc?.start?.line &&
+  node.loc?.start.column === loc?.start?.column;
+
+/** Visit every node with its parent. */
+function walk(node, parent, visit) {
+  if (!node || typeof node.type !== 'string') return;
+  visit(node, parent);
+  for (const key of Object.keys(node)) {
+    if (
+      key === 'loc' ||
+      key === 'leadingComments' ||
+      key === 'trailingComments' ||
+      key === 'innerComments'
+    )
+      continue;
+    const v = node[key];
+    if (Array.isArray(v)) for (const c of v) walk(c, node, visit);
+    else if (v && typeof v === 'object') walk(v, node, visit);
+  }
+}
+
+/** R2: the logger names only successes, so a bailout takes its name from the AST. */
+function nameAt(ast, fnLoc) {
+  let name = null;
+  const parents = new Map();
+  walk(ast, null, (node, parent) => {
+    parents.set(node, parent);
+    if (name !== null || !isFn(node) || !sameStart(node, fnLoc)) return;
+    if (node.id?.name) {
+      name = node.id.name;
+      return;
+    }
+    let up = parents.get(node);
+    while (up?.type === 'CallExpression') up = parents.get(up);
+    if (up?.type === 'VariableDeclarator' && up.id.type === 'Identifier')
+      name = up.id.name;
+    else if (up?.type === 'ExportDefaultDeclaration') name = 'default';
+    else name = '<anonymous>';
+  });
+  return name ?? '<anonymous>';
+}
+
+const WRAPPERS = /^(forwardRef|memo)$/;
+const calleeName = (call) =>
+  call.callee.name ?? call.callee.property?.name ?? '';
+
+/** Top-level functions: { name, node }. */
+function topLevelFunctions(ast) {
+  const out = [];
+  for (const stmt of ast.program.body) {
+    const decl =
+      stmt.type === 'ExportNamedDeclaration' ||
+      stmt.type === 'ExportDefaultDeclaration'
+        ? stmt.declaration
+        : stmt;
+    if (decl?.type === 'FunctionDeclaration' && decl.id)
+      out.push({ name: decl.id.name, node: decl });
+    else if (decl?.type === 'VariableDeclaration')
+      for (const d of decl.declarations) {
+        if (d.id.type !== 'Identifier') continue;
+        let init = d.init;
+        while (
+          init?.type === 'CallExpression' &&
+          WRAPPERS.test(calleeName(init))
+        )
+          init = init.arguments.find(
+            (a) => isFn(a) || a.type === 'CallExpression',
+          );
+        if (isFn(init)) out.push({ name: d.id.name, node: init });
+      }
+  }
+  return out;
+}
+
+const categoryOf = (e) =>
+  e.kind === 'PipelineError'
+    ? 'Pipeline'
+    : (e.detail?.category ?? e.detail?.options?.category ?? 'Unknown');
+const reasonOf = (e) =>
+  e.detail?.reason ??
+  e.detail?.options?.reason ??
+  (typeof e.data === 'string' ? e.data : 'unknown');
+
+function listFiles(root, scanDirs, exclude) {
+  const r = spawnSync('git', ['ls-files', '--', ...scanDirs], {
+    cwd: root,
+    encoding: 'utf8',
+  });
+  if (r.status !== 0)
+    fail(
+      2,
+      `git ls-files failed in ${root}: ${r.stderr.trim()}. Run it inside a git work tree.`,
+    );
+  return r.stdout
+    .split('\n')
+    .filter(
+      (f) => /\.tsx?$/.test(f) && !exclude.test(f) && existsSync(join(root, f)),
+    )
+    .sort();
+}
+
+export function scan(root, { babel, plugin }, { scanDirs, exclude }) {
+  const files = listFiles(root, scanDirs, exclude);
+  const bailouts = new Map();
+  const skipped = [];
+  let compiled = 0;
+  for (const path of files) {
+    const events = [];
+    const options = {
+      babelrc: false,
+      configFile: false,
+      filename: join(root, path),
+      parserOpts: {
+        plugins: path.endsWith('.tsx') ? ['typescript', 'jsx'] : ['typescript'],
+      },
+    };
+    const code = readFileSync(join(root, path), 'utf8');
+    let ast;
+    try {
+      babel.transformSync(code, {
+        ...options,
+        plugins: [
+          [
+            plugin,
+            {
+              target: '19',
+              panicThreshold: 'none',
+              logger: { logEvent: (_f, event) => events.push(event) },
+            },
+          ],
+        ],
+      });
+      ast = babel.parseSync(code, options);
+    } catch (e) {
+      return fail(
+        2,
+        `${path} did not parse or transform: ${String(e.message).split('\n')[0]}. Fix the syntax error first.`,
+      );
+    }
+    for (const e of events) {
+      if (e.kind === 'CompileSuccess') compiled += 1;
+      if (e.kind !== 'CompileError' && e.kind !== 'PipelineError') continue;
+      const name = nameAt(ast, e.fnLoc);
+      const category = categoryOf(e);
+      const key = `${path}|${name}|${category}`;
+      if (!bailouts.has(key))
+        bailouts.set(key, {
+          key,
+          path,
+          line: e.fnLoc?.start?.line ?? 0,
+          name,
+          category,
+          reason: reasonOf(e),
+        });
+    }
+    for (const { name, node } of topLevelFunctions(ast)) {
+      if (!COMPONENT_OR_HOOK.test(name)) continue;
+      if (events.some((e) => e.fnLoc && sameStart(node, e.fnLoc))) continue;
+      skipped.push({
+        key: `${path}|${name}`,
+        path,
+        line: node.loc.start.line,
+        name,
+      });
+    }
+  }
+  return {
+    files: files.length,
+    compiled,
+    bailouts: [...bailouts.values()],
+    skipped,
+  };
+}
+
+export function compare(report, baseline) {
+  const known = new Set(baseline.bailouts.map((e) => e.key));
+  const current = new Set(report.bailouts.map((b) => b.key));
+  const allowedSkips = new Set(baseline.skipped.map((e) => e.key));
+  const currentSkips = new Set(report.skipped.map((s) => s.key));
+  const entries = [...baseline.bailouts, ...baseline.skipped];
+  const fresh = report.bailouts.filter((b) => !known.has(b.key));
+  const stale = baseline.bailouts.filter((e) => !current.has(e.key));
+  const staleSkips = baseline.skipped.filter((e) => !currentSkips.has(e.key));
+  const unskipped = report.skipped.filter((s) => !allowedSkips.has(s.key));
+  const unreasoned = entries.filter((e) => e.allow === '');
+  return {
+    fresh,
+    stale: [...stale, ...staleSkips],
+    unskipped,
+    unreasoned,
+  };
+}
+
+const byKey = (p, q) => (p.key < q.key ? -1 : p.key > q.key ? 1 : 0);
+
+/** Next baseline for the current scan (rules in the header). */
+export function updateBaseline(
+  report,
+  baseline,
+  version,
+  { seed = false, comment } = {},
+) {
+  const old = new Map(
+    [...baseline.bailouts, ...baseline.skipped].map((e) => [e.key, e]),
+  );
+  const withAllow = (entry) => {
+    const prev = old.get(entry.key);
+    if (prev?.allow !== undefined) entry.allow = prev.allow;
+    else if (!prev && !seed) entry.allow = '';
+    return entry;
+  };
+  return {
+    comment: comment,
+    plugin: version,
+    bailouts: report.bailouts
+      .map((b) => withAllow({ key: b.key, reason: b.reason }))
+      .sort(byKey),
+    skipped: report.skipped.map((s) => withAllow({ key: s.key })).sort(byKey),
+  };
+}
+
+function loadBaseline(path, version) {
+  try {
+    const b = JSON.parse(readFileSync(path, 'utf8'));
+    return { ...b, bailouts: b.bailouts ?? [], skipped: b.skipped ?? [] };
+  } catch {
+    return { plugin: version, bailouts: [], skipped: [] };
+  }
+}
+
+export function reactCompiler({
+  repo,
+  scanDirs,
+  exclude,
+  resolve: resolveVia,
+  baseline: baselineRel,
+  comment,
+  name,
+  update,
+  install,
+}) {
+  const scope = { scanDirs, exclude };
+
+  function run(argv) {
+    const out = [];
+    try {
+      const opt = (flag) =>
+        argv.find((a) => a.startsWith(`--${flag}=`))?.slice(flag.length + 3);
+      const root = resolve(opt('root') ?? repo);
+      const baselinePath = resolve(opt('baseline') ?? join(root, baselineRel));
+      const compiler = loadCompiler(repo, resolveVia, install);
+      const pluginVersion = compiler.version;
+      const report = scan(root, compiler, scope);
+      const baseline = loadBaseline(baselinePath, pluginVersion);
+
+      if (argv.includes('--update')) {
+        const next = updateBaseline(report, baseline, pluginVersion, {
+          seed: argv.includes('--seed'),
+          comment,
+        });
+        writeFileSync(baselinePath, JSON.stringify(next, null, 2) + '\n');
+        out.push(
+          `${name}: baseline rewritten, ${next.bailouts.length} bailouts, ${next.skipped.length} skips.`,
+        );
+        return { code: 0, out, err: [] };
+      }
+
+      const { fresh, stale, unskipped, unreasoned } = compare(report, baseline);
+      let problems = 0;
+      if (baseline.plugin !== pluginVersion) {
+        problems += 1;
+        out.push(
+          `plugin ${pluginVersion} != baseline ${baseline.plugin}: re-seed with --update`,
+        );
+      }
+      for (const b of fresh) {
+        problems += 1;
+        out.push(
+          `new bailout: ${b.path}:${b.line} ${b.name} [${b.category}] ${b.reason}`,
+        );
+      }
+      for (const e of stale) {
+        problems += 1;
+        out.push(`stale: ${e.key} (fixed - run ${update})`);
+      }
+      for (const s of unskipped) {
+        problems += 1;
+        out.push(
+          `skipped: ${s.path}:${s.line} ${s.name} is named like a component or hook but was not compiled ('use memo', or an allow entry)`,
+        );
+      }
+      for (const e of unreasoned) {
+        problems += 1;
+        out.push(`unreasoned: ${e.key}`);
+      }
+      const debt = baseline.bailouts.filter(
+        (e) => e.allow === undefined,
+      ).length;
+      const allowed = baseline.bailouts.length - debt;
+      out.push(
+        `${name}: ${report.files} files, ${report.compiled} compiled functions, ${report.bailouts.length} bailouts (${debt} debt, ${allowed} allowed), ${baseline.skipped.length} allowed skips`,
+      );
+      return { code: problems > 0 ? 1 : 0, out, err: [] };
+    } catch (e) {
+      if (e instanceof CheckFailure)
+        return { code: e.code, out: [], err: [`${name}: ${e.message}`] };
+      throw e;
+    }
+  }
+
+  return {
+    scan: (root, compiler) => scan(root, compiler, scope),
+    compare,
+    updateBaseline: (report, baselineJson, version, { seed = false } = {}) =>
+      updateBaseline(report, baselineJson, version, { seed, comment }),
+    run,
+  };
+}