@stacksjs/stx 0.2.154 → 0.2.156

package/dist/client/directive.d.ts

@@ -1,3 +1,10 @@
+/**
+ * STX Router Directive
+ *
+ * Usage in templates:
+ *   @stxRouter - Inject the SPA router script
+ *   @stxRouter('main') - Specify custom container selector
+ */
 import type { CustomDirective } from '../types';
 /**
  * Handler for @stxRouter directive

package/dist/client/index.d.ts

@@ -4,5 +4,4 @@
  * Browser-side functionality for STX applications.
  */
 export * from './directive';
-// Re-export getRouterScript from the canonical router (packages/router)
 export { getRouterScript } from 'stx-router';

package/dist/client-script-bundler.d.ts

@@ -1,4 +1,62 @@
-export declare function shouldLogBundlerDiagnostics(environment?: { STX_DEBUG?: string }): boolean;
+/**
+ * Client Script Bundler
+ *
+ * Uses Bun.build to resolve and bundle imports in `<script client>` blocks.
+ * Only activates when real user imports are detected (local files, npm packages).
+ * stx runtime, @stores, and @composables are marked as external — handled
+ * by existing auto-import and store-import transforms.
+ *
+ * @module client-script-bundler
+ */
+import type { BuildFailureDetail } from './build-message';
+export declare function shouldLogBundlerDiagnostics(environment?: {
+    STX_DEBUG?: string;
+}): boolean;
+/**
+ * Client-script bundle failures recorded during the current process.
+ *
+ * When a `<script client>` block fails to bundle, the bundler falls back to
+ * shipping the ORIGINAL, unbundled source so the page still renders. That is a
+ * reasonable dev-server behaviour and a terrible build behaviour: imports never
+ * resolve, bindings silently do nothing, and `stx build` still exited 0, so CI
+ * published a broken page as a success.
+ *
+ * Nothing was counting these. `ssg.failedCount` only ever saw render-time throws,
+ * never a bundle failure, because the fallback swallowed it and returned a
+ * string. The registry gives the build a way to ask, without the bundler having
+ * to know whether it is running under a dev server or a build. See #1884.
+ */
+export interface BundleFailure {
+    filePath: string;
+    message: string;
+    /**
+     * The same failure with its position intact, for a dev-server overlay to
+     * draw a code frame from. Absent only when the thrower gave no position.
+     */
+    details?: BuildFailureDetail[];
+}
+/** Record a bundle failure. Called from the bundler's fallback path. */
+export declare function recordBundleFailure(filePath: string, message: string, details?: BuildFailureDetail[]): void;
+/** Every bundle failure since the last reset. */
+export declare function getBundleFailures(): BundleFailure[];
+/** Drop recorded failures — call at the start of a build, and in tests. */
+export declare function clearBundleFailures(): void;
+/** What to do when a client script will not bundle. */
+export type BundlerFallbackMode = 'warn' | 'error';
+/**
+ * Override the configured fallback mode, for tests and embedders.
+ *
+ * Pass `undefined` to go back to reading `strict.bundlerFallback` from config.
+ */
+export declare function setBundlerFallbackMode(mode: BundlerFallbackMode | undefined): void;
+/**
+ * The effective fallback mode.
+ *
+ * Read lazily rather than captured at import time: config is loaded after this
+ * module is first imported, so a value read at import time is always the
+ * default.
+ */
+export declare function resolveBundlerFallback(): BundlerFallbackMode;
 /**
  * Check if a script has user imports that need Bun.build bundling.
  *
@@ -24,7 +82,7 @@ export declare function hasUserImports(code: string): boolean;
  */
 export declare function queueClientBundleBuild<T>(task: () => Promise<T>): Promise<T>;
 export declare function bundleClientScript(code: string, filePath: string, options?: {
-    projectRoot?: string
-    minify?: boolean
-    cacheDir?: string
-  }): Promise<string>;
+    projectRoot?: string;
+    minify?: boolean;
+    cacheDir?: string;
+}): Promise<string>;

package/dist/client-script-bundler.js

@@ -2,7 +2,8 @@ import path from "node:path";
 import fs from "node:fs";
 import { getPublicEnvDefine } from "./public-env.js";
 import { stateDir } from "./state-dir.js";
-import { formatBuildFailure } from "./build-message.js";
+import { describeBuildFailure, formatBuildFailure } from "./build-message.js";
+import { config } from "./config.js";
 const BUNDLE_CACHE_VERSION = 5, BUNDLE_CACHE_METADATA_VERSION = 1;
 export function shouldLogBundlerDiagnostics(environment = process.env) {
   return environment.STX_DEBUG === "true" || environment.STX_DEBUG === "1";
@@ -11,6 +12,29 @@ function logBundlerDiagnostic(...message) {
   if (shouldLogBundlerDiagnostics())
     console.log("[stx:bundler]", ...message);
 }
+const _bundleFailures = [];
+export function recordBundleFailure(filePath, message, details) {
+  _bundleFailures.push({ filePath: filePath || "<inline>", message, details });
+}
+export function getBundleFailures() {
+  return _bundleFailures.slice();
+}
+export function clearBundleFailures() {
+  _bundleFailures.length = 0;
+}
+let _fallbackOverride;
+export function setBundlerFallbackMode(mode) {
+  _fallbackOverride = mode;
+}
+export function resolveBundlerFallback() {
+  if (_fallbackOverride)
+    return _fallbackOverride;
+  try {
+    return config.strict?.bundlerFallback ?? "warn";
+  } catch {
+    return "warn";
+  }
+}
 const EXTERNAL_PATTERNS = [
   /^stx$/,
   /^@stacksjs\/stx$/,
@@ -268,7 +292,11 @@ ${publicAssignments}`.trim();
     }));
     return bundled;
   } catch (error) {
-    console.warn(`[stx:bundler] error: ${formatBuildFailure(error, filePath || void 0)}`);
+    const details = describeBuildFailure(error, filePath || void 0), failure = formatBuildFailure(error, filePath || void 0);
+    console.warn(`[stx:bundler] error: ${failure}`);
+    recordBundleFailure(filePath || "", failure, details);
+    if (resolveBundlerFallback() === "error")
+      throw error;
     return code;
   } finally {
     try {

package/dist/client-script.d.ts

@@ -1,4 +1,45 @@
+/**
+ * Client Script Processor
+ *
+ * Transforms <script client> blocks in SFC (.stx) components:
+ * 1. Auto-imports from 'stx' and '@stacksjs/browser' (no import statements needed)
+ * 2. Resolves `import { store } from '@stores'` to runtime store access
+ * 3. Transpiles TypeScript to JavaScript (strips type annotations, interfaces, import type)
+ * 4. Injects event binding code (from @click, @input, etc.) into the script scope
+ * 5. Auto-wraps in a scoped IIFE for isolation
+ *
+ * This enables clean component authoring:
+ * ```stx
+ * <template>
+ *   <button @click="handleClick()">Count: {{ count() }}</button>
+ * </template>
+ *
+ * <script>
+ * // No imports needed! state, onMount, Trail, etc. are auto-imported
+ * const count = state(0)
+ *
+ * onMount(async () => {
+ *   const trails = await Trail.all()
+ *   console.log(trails)
+ * })
+ *
+ * function handleClick() {
+ *   count.set(count() + 1)
+ * }
+ * </script>
+ * ```
+ *
+ * @module client-script
+ */
 import type { ParsedEvent } from './events';
+export interface VendorCssImport {
+    /** The original specifier as written in the import — kept verbatim for the data attribute. */
+    source: string;
+    /** The resolved absolute filesystem path — used for dedupe and reads. */
+    resolvedPath: string;
+    /** The CSS file contents at build time. */
+    contents: string;
+}
 /**
  * Strip side-effect `.css` imports from a `<script client>` body and read
  * their contents off disk.
@@ -21,7 +62,13 @@ import type { ParsedEvent } from './events';
  * call. Cross-component dedupe still relies on the caller's HTML response
  * (CSS rules collapse harmlessly at the browser level either way).
  */
-export declare function extractAndStripCssImports(code: string, options: { filePath?: string, projectRoot?: string }): { code: string, styles: VendorCssImport[] };
+export declare function extractAndStripCssImports(code: string, options: {
+    filePath?: string;
+    projectRoot?: string;
+}): {
+    code: string;
+    styles: VendorCssImport[];
+};
 /**
  * Render collected vendor CSS as one `<style>` tag per resolved source,
  * each wrapped in `@layer vendor { … }` so the styles can never out-specificity
@@ -33,6 +80,33 @@ export declare function extractAndStripCssImports(code: string, options: { fileP
  * below un-layered rules, so vendor styles default to lowest precedence.
  */
 export declare function renderVendorStyleTags(styles: VendorCssImport[]): string;
+/**
+ * Exports from 'stx' auto-imported into classic `<script>` / `<script client>`
+ * blocks.
+ *
+ * Derived from {@link STX_RUNTIME_GLOBALS} rather than hand-maintained (#1804).
+ * This was a separate 82-name literal, and it had drifted: 16 of those names
+ * were not on `window.stx` at all. Because the generated prologue destructures
+ * (`var { … } = window.stx`), a missing name is not an error — it binds
+ * `undefined`, and the author sees "undefined is not a function" at the call
+ * site with nothing naming the identifier or saying why. `provide` worked and
+ * `inject` did not; `onMounted` worked and `onUpdated` did not.
+ *
+ * Five of the 16 (`isDerived`, `inject`, `useSlots`, `watchMultiple`,
+ * `onBeforeMount`) are now implemented in the runtime and live in the shared
+ * list. The remaining 11 are server- or compile-time only — `h` and `Fragment`
+ * belong to the JSX runtime, `useMeta`/`getCurrentInstance`/`useAttrs`/
+ * `onErrorCaptured`/`onBeforeUpdate`/`onUpdated`/`createStore`/`createSelector`
+ * are module exports with no client counterpart, and `action` has no
+ * implementation anywhere — so they are no longer offered. A `ReferenceError`
+ * naming the identifier beats a silent `undefined`.
+ */
+export declare const STX_AUTO_IMPORTS: readonly string[];
+export interface BrowserCoreAutoImportResult {
+    code: string;
+    imports: string[];
+    models: string[];
+}
 /**
  * Turn bare core browser helper usage into a real module import before the
  * client bundler runs.
@@ -55,6 +129,33 @@ export declare function injectBrowserCoreAutoImports(code: string): BrowserCoreA
  * undefined name.
  */
 export declare function stripCommentsAndLiterals(code: string): string;
+export interface ClientScriptOptions {
+    /** Event bindings collected from template @event attributes */
+    eventBindings?: ParsedEvent[];
+    /** Whether to enable auto-imports (default: true) */
+    autoImports?: boolean;
+    /** Original script tag attributes (e.g., 'type="module"') */
+    attrs?: string;
+    /** Whether the component template contains : prefix directives */
+    hasColonDirectives?: boolean;
+    /** Template HTML content for auto-binding analysis (Phase 2: auto-detect which scripts need stx.mount()) */
+    templateContent?: string;
+    /** File path of the template (for relative import resolution in bundler) */
+    filePath?: string;
+    /** Project root directory (for @/ path resolution in bundler) */
+    projectRoot?: string;
+    /** Whether this is a production build (enables minification in bundler) */
+    production?: boolean;
+    /**
+     * Server → client data bridge. Top-level `<script server>` variables (and
+     * other template-context values) made available to `<script client>` code:
+     * any JSON-serializable value referenced — but not redeclared — by the client
+     * script is serialized into the client bundle, so reactive state can be seeded
+     * from build-time data (e.g. `const items = state(serverItems)`) without a
+     * round-trip fetch. Functions/non-serializable values are skipped.
+     */
+    serverData?: Record<string, unknown>;
+}
 /**
  * Generate destructuring statements for auto-imported symbols
  * These access globals set up by the STX runtime and @stacksjs/browser
@@ -98,49 +199,3 @@ export declare function generateServerDataBridge(code: string, serverData?: Reco
  * @returns A complete `<script>...</script>` tag ready for browser injection
  */
 export declare function processClientScript(scriptContent: string, options?: ClientScriptOptions): Promise<string>;
-/**
- * Exports from 'stx' auto-imported into classic `<script>` / `<script client>`
- * blocks.
- *
- * Derived from {@link STX_RUNTIME_GLOBALS} rather than hand-maintained (#1804).
- * This was a separate 82-name literal, and it had drifted: 16 of those names
- * were not on `window.stx` at all. Because the generated prologue destructures
- * (`var { … } = window.stx`), a missing name is not an error — it binds
- * `undefined`, and the author sees "undefined is not a function" at the call
- * site with nothing naming the identifier or saying why. `provide` worked and
- * `inject` did not; `onMounted` worked and `onUpdated` did not.
- *
- * Five of the 16 (`isDerived`, `inject`, `useSlots`, `watchMultiple`,
- * `onBeforeMount`) are now implemented in the runtime and live in the shared
- * list. The remaining 11 are server- or compile-time only — `h` and `Fragment`
- * belong to the JSX runtime, `useMeta`/`getCurrentInstance`/`useAttrs`/
- * `onErrorCaptured`/`onBeforeUpdate`/`onUpdated`/`createStore`/`createSelector`
- * are module exports with no client counterpart, and `action` has no
- * implementation anywhere — so they are no longer offered. A `ReferenceError`
- * naming the identifier beats a silent `undefined`.
- */
-export declare const STX_AUTO_IMPORTS: readonly string[];
-export declare interface VendorCssImport {
-  source: string
-  resolvedPath: string
-  contents: string
-}
-export declare interface BrowserCoreAutoImportResult {
-  code: string
-  imports: string[]
-  models: string[]
-}
-// =============================================================================
-// Types
-// =============================================================================
-export declare interface ClientScriptOptions {
-  eventBindings?: ParsedEvent[]
-  autoImports?: boolean
-  attrs?: string
-  hasColonDirectives?: boolean
-  templateContent?: string
-  filePath?: string
-  projectRoot?: string
-  production?: boolean
-  serverData?: Record<string, unknown>
-}

package/dist/client-script.js

@@ -467,7 +467,7 @@ function transformAutoImports(code) {
   for (const symbol of STX_AUTO_IMPORTS) {
     if (existingImports.has(symbol) || locallyDeclared.has(symbol))
       continue;
-    if (new RegExp(`\\b${symbol}\\s*\\(`, "g").test(transformedCode))
+    if (new RegExp(`\\b${symbol}\\s*(?:<[^>]*>)?\\s*\\(`, "g").test(transformedCode))
       usedStxImports.add(symbol);
   }
   for (const symbol of BROWSER_CORE_IMPORTS) {
@@ -522,6 +522,18 @@ function generateAutoImportGuard(stxImports, browserImports) {
 `;
 }
 export function extractBridgeData(context) {
+  const declared = context.__stxClientPayload;
+  if (declared && typeof declared === "object") {
+    const picked = {};
+    for (const key in declared) {
+      const value = declared[key];
+      if (typeof value === "function")
+        continue;
+      picked[key] = value;
+    }
+    picked.__stxDeclaredPayload = !0;
+    return picked;
+  }
   const out = {};
   for (const key in context) {
     if (key.startsWith("__") || key.startsWith("$"))
@@ -580,13 +592,13 @@ function warnAboutBridgedValue(name, json) {
 export function generateServerDataBridge(code, serverData) {
   if (!serverData)
     return "";
-  const searchable = stripCommentsAndLiterals(code), lines = [];
+  const searchable = stripCommentsAndLiterals(code), declaredPayload = serverData.__stxDeclaredPayload === !0, lines = [];
   for (const [name, value] of Object.entries(serverData)) {
     if (!/^[A-Za-z_$][\w$]*$/.test(name))
       continue;
     if (name.startsWith("__") || name.startsWith("$"))
       continue;
-    if (!referencesIdentifier(searchable, name))
+    if (!declaredPayload && !referencesIdentifier(searchable, name))
       continue;
     if (declaresClientIdentifier(code, name))
       continue;

package/dist/codemod.d.ts

@@ -0,0 +1,56 @@
+/** Run the codemods over one file's source. */
+export declare function codemodSource(source: string, options?: CodemodOptions): CodemodFileResult;
+/** Human-readable report. */
+export declare function formatCodemodFindings(findings: CodemodFinding[], wrote: boolean): string;
+export declare interface CodemodFinding {
+  file: string
+  line: number
+  rule: CodemodRule
+  applied: boolean
+  reason?: string
+  snippet: string
+}
+export declare interface CodemodFileResult {
+  code: string
+  findings: CodemodFinding[]
+}
+export declare interface CodemodOptions {
+  rules?: CodemodRule[]
+  file?: string
+}
+/**
+ * Codemods for adopting stx primitives an app hand-rolled around (#1843).
+ *
+ * Two production apps built on stx reached past it into vanilla JS for things
+ * it already ships. The audit found the cause was discovery, not absence: one
+ * app called bare `confirm()` in five places and used `title=` thirteen times
+ * while `stxConfirm` and `x-tooltip` were both delivered and used zero times.
+ * A native fallback that WORKS is the hardest kind of gap to notice — nothing
+ * fails, so nothing prompts you to look.
+ *
+ * #1843 proposes both rewrites as "mechanical and safe". Neither is, and the
+ * difference matters enough that this tool reports by default and only edits
+ * when asked:
+ *
+ *   - `confirm()` returns a boolean synchronously; `stxConfirm()` returns a
+ *     Promise. `if (confirm(m))` rewritten to `if (stxConfirm(m))` is ALWAYS
+ *     TRUE, because a Promise is truthy. A blind rewrite turns every "Delete
+ *     this?" into an unconditional yes.
+ *
+ *   - `title=` is announced by screen readers. `x-tooltip` sets no `role` and
+ *     no `aria-*` — it is a visual tooltip driven by mouseover/focusin.
+ *     Replacing one with the other removes the accessible description. So the
+ *     tooltip rule ADDS `x-tooltip` and keeps `title`.
+ */
+export type CodemodRule = | 'confirm'
+    | 'tooltip'
+    | 'route-params'
+    | 'search-params'
+    | 'navigate'
+    | 'fetch'
+    | 'polling'
+    | 'debounce'
+    | 'click-outside'
+    | 'focus'
+    | 'clipboard'
+    | 'watch';

package/dist/codemod.js

@@ -0,0 +1,192 @@
+function contextAfter(source, index, length = 240) {
+  return source.slice(index, index + length);
+}
+const REPORT_RULES = [
+  {
+    rule: "route-params",
+    pattern: /\blocation\s*\.\s*pathname\s*\.\s*(?:match|split)\s*\(/g,
+    primitive: "useRoute() / useRouteParams() / useRouteParam(name)",
+    why: "parsing the URL by hand re-implements the router and does not update on SPA navigation"
+  },
+  {
+    rule: "search-params",
+    pattern: /new\s+URLSearchParams\s*\(/g,
+    primitive: "useSearchParams()",
+    why: "reactive, and writes back through the router instead of history.replaceState"
+  },
+  {
+    rule: "navigate",
+    pattern: /\blocation\s*\.\s*(?:assign|replace)\s*\(|\blocation\s*\.\s*href\s*=/g,
+    primitive: "navigate(path) / goBack()",
+    why: "a full document load throws away every store and the scroll position; navigate() is an SPA transition",
+    reject: (source, index) => /^[^\n]*?(?:['"`]\s*)?(?:mailto:|tel:|sms:|https?:\/\/|\/\/)/.test(contextAfter(source, index, 160))
+  },
+  {
+    rule: "fetch",
+    pattern: /new\s+AbortController\s*\(/g,
+    primitive: "useFetch(url) / useAsyncData(key, fn)",
+    why: "cancellation, loading and error state are already wired; hand-rolling them is where the races live"
+  },
+  {
+    rule: "polling",
+    pattern: /setInterval\s*\(/g,
+    primitive: "useEventSource() / useSSE() / useWebSocket() / useChannel()",
+    why: "polling burns requests and lags; the push primitives are delivered",
+    reject: (source, index) => !/\bfetch\s*\(|\$fetch\b|useFetch\b|\.get\s*\(|axios\b/.test(contextAfter(source, index))
+  },
+  {
+    rule: "debounce",
+    pattern: /\bclearTimeout\s*\(/g,
+    primitive: "useDebounce(fn, ms) / useThrottle(fn, ms)",
+    why: "a hand-held timer handle per call site is the usual source of stale-result bugs",
+    requires: (source) => /setTimeout\s*\(/.test(source)
+  },
+  {
+    rule: "click-outside",
+    pattern: /document\s*\.\s*addEventListener\s*\(\s*['"](?:click|mousedown|pointerdown)['"]/g,
+    primitive: "useClickOutside(ref, fn)",
+    why: "the document-level listener plus the blur race is exactly what this composable exists to remove"
+  },
+  {
+    rule: "focus",
+    pattern: /\.\s*(?:getElementById|querySelector)\s*\([^)]*\)\s*(?:\?\.)?\s*\.?focus\s*\(/g,
+    primitive: "useFocus(ref) with x-ref",
+    why: "a query by id breaks under nested scopes and SPA navigation; a ref does not"
+  },
+  {
+    rule: "clipboard",
+    pattern: /navigator\s*\.\s*(?:clipboard|share)\b/g,
+    primitive: "useClipboard() / useShare()",
+    why: "permission state, the copied flag and the unsupported-browser fallback are already handled"
+  },
+  {
+    rule: "watch",
+    pattern: /\beffect\s*\(\s*\(\s*\)\s*=>\s*\{[^}]*\bvoid\s+\w+\s*\(\s*\)/g,
+    primitive: "watch(source, cb) / watchMultiple([...], cb)",
+    why: "the `void a(); void b()` dance is a manual dependency list; watch takes one directly"
+  }
+], DEFAULT_RULES = ["confirm", "tooltip", ...REPORT_RULES.map((r) => r.rule)];
+function lineOf(source, index) {
+  let line = 1;
+  for (let i = 0;i < index; i++)
+    if (source[i] === `
+`)
+      line++;
+  return line;
+}
+function snippetAt(source, index) {
+  const start = source.lastIndexOf(`
+`, index) + 1, end = source.indexOf(`
+`, index);
+  return source.slice(start, end === -1 ? source.length : end).trim().slice(0, 120);
+}
+function isInsideAsyncFunction(source, index) {
+  const before = source.slice(0, index), fnKeyword = before.lastIndexOf("function"), arrow = before.lastIndexOf("=>"), boundary = Math.max(fnKeyword, arrow);
+  if (boundary === -1)
+    return !1;
+  const window = source.slice(Math.max(0, boundary - 120), boundary);
+  return /\basync\b[^;{}]*$/.test(window);
+}
+function applyConfirmRule(source, file, findings) {
+  const pattern = /(^|[^\w$.])confirm\s*\(/g;
+  let out = "", last = 0, match;
+  while ((match = pattern.exec(source)) !== null) {
+    const callAt = match.index + match[1].length, line = lineOf(source, callAt), snippet = snippetAt(source, callAt);
+    if (/stxConfirm\s*\($/.test(source.slice(0, callAt + 8)))
+      continue;
+    const safe = isInsideAsyncFunction(source, callAt);
+    findings.push({
+      file,
+      line,
+      rule: "confirm",
+      applied: safe,
+      snippet,
+      reason: safe ? void 0 : "stxConfirm() returns a Promise and native confirm() is synchronous, so this needs `await` inside an async function. Rewriting it here would make the condition always true."
+    });
+    if (safe) {
+      out += source.slice(last, callAt) + "await stxConfirm(";
+      last = callAt + 8;
+    }
+  }
+  return out + source.slice(last);
+}
+function applyTooltipRule(source, file, findings) {
+  const pattern = /(<[a-z][\w-]*\b[^>]*?)\stitle=(["'])(.*?)\2/gis;
+  let out = "", last = 0, match;
+  while ((match = pattern.exec(source)) !== null) {
+    const [whole, openTag, quote, value] = match, line = lineOf(source, match.index), snippet = snippetAt(source, match.index);
+    if (/\bx-tooltip[=\s]/.test(openTag) || value.trim() === "") {
+      findings.push({
+        file,
+        line,
+        rule: "tooltip",
+        applied: !1,
+        snippet,
+        reason: /\bx-tooltip[=\s]/.test(openTag) ? "already has x-tooltip" : "empty title"
+      });
+      continue;
+    }
+    findings.push({ file, line, rule: "tooltip", applied: !0, snippet });
+    out += source.slice(last, match.index) + `${openTag} x-tooltip=${quote}${value}${quote} title=${quote}${value}${quote}`;
+    last = match.index + whole.length;
+  }
+  return out + source.slice(last);
+}
+function applyReportRules(source, file, rules, findings) {
+  for (const entry of REPORT_RULES) {
+    if (!rules.includes(entry.rule))
+      continue;
+    if (entry.requires && !entry.requires(source))
+      continue;
+    entry.pattern.lastIndex = 0;
+    let match;
+    while ((match = entry.pattern.exec(source)) !== null) {
+      if (entry.reject?.(source, match.index))
+        continue;
+      findings.push({
+        file,
+        line: lineOf(source, match.index),
+        rule: entry.rule,
+        applied: !1,
+        snippet: snippetAt(source, match.index),
+        reason: `${entry.primitive} \u2014 ${entry.why}`
+      });
+    }
+  }
+}
+export function codemodSource(source, options = {}) {
+  const rules = options.rules ?? DEFAULT_RULES, file = options.file ?? "<source>", findings = [];
+  applyReportRules(source, file, rules, findings);
+  let code = source;
+  if (rules.includes("confirm"))
+    code = applyConfirmRule(code, file, findings);
+  if (rules.includes("tooltip"))
+    code = applyTooltipRule(code, file, findings);
+  findings.sort((a, b) => a.line - b.line);
+  return { code, findings };
+}
+const REWRITABLE = new Set(["confirm", "tooltip"]);
+export function formatCodemodFindings(findings, wrote) {
+  if (findings.length === 0)
+    return "No hand-rolled equivalents found.";
+  const applied = findings.filter((f) => f.applied), declined = findings.filter((f) => !f.applied && REWRITABLE.has(f.rule)), adopt = findings.filter((f) => !f.applied && !REWRITABLE.has(f.rule)), lines = [];
+  if (applied.length > 0) {
+    lines.push(wrote ? `Rewrote ${applied.length} site(s):` : `Would rewrite ${applied.length} site(s) (pass --fix):`);
+    for (const f of applied)
+      lines.push(`  ${f.file}:${f.line}  [${f.rule}]  ${f.snippet}`);
+  }
+  if (declined.length > 0) {
+    lines.push("", `Needs a human \u2014 ${declined.length} site(s):`);
+    for (const f of declined)
+      lines.push(`  ${f.file}:${f.line}  [${f.rule}]  ${f.snippet}
+      ${f.reason}`);
+  }
+  if (adopt.length > 0) {
+    lines.push("", `An stx primitive already covers this \u2014 ${adopt.length} site(s):`);
+    for (const f of adopt)
+      lines.push(`  ${f.file}:${f.line}  [${f.rule}]  ${f.snippet}
+      use ${f.reason}`);
+  }
+  return lines.join(`
+`);
+}