styled-components-to-stylex-codemod 0.0.14 → 0.0.15

package/README.md

@@ -38,6 +38,7 @@ const adapter = defineAdapter({
 
 await runTransform({
   files: "src/**/*.tsx",
+  consumerPaths: null, // set to a glob to enable cross-file selector support
   adapter,
   dryRun: false,
   parser: "tsx",
@@ -136,6 +137,7 @@ const adapter = defineAdapter({
 
 await runTransform({
   files: "src/**/*.tsx",
+  consumerPaths: null,
   adapter,
   dryRun: false,
   parser: "tsx",
@@ -155,25 +157,56 @@ Adapters are the main extension point, see full example above. They let you cont
 - which exported components should support external className/style extension and/or polymorphic `as` prop (`externalInterface`)
 - how className/style merging is handled for components accepting external styling (`styleMerger`)
 
+#### Cross-file selectors (`consumerPaths`)
+
+`consumerPaths` is required. Pass `null` to opt out, or a glob pattern to enable cross-file selector scanning.
+
+When transforming a subset of files, other files may reference your styled components as CSS selectors (e.g. `${Icon} { fill: red }`). Pass `consumerPaths` to scan those files and wire up cross-file selectors automatically:
+
+```ts
+await runTransform({
+  files: "src/components/**/*.tsx", // files to transform
+  consumerPaths: "src/**/*.tsx", // additional files to scan for cross-file usage
+  adapter,
+});
+```
+
+- Files in **both** `files` and `consumerPaths` use the **marker sidecar** strategy (both consumer and target are transformed, using `stylex.defineMarker()`).
+- Files in `consumerPaths` but **not** in `files` use the **bridge** strategy (a stable `className` is added to the converted component so unconverted consumers' selectors still work).
+
 #### Auto-detecting external interface usage (experimental)
 
-Instead of manually specifying which components need `styles` or `as` support, you can use `createExternalInterface` to auto-detect usage by scanning your consumer code with [ripgrep](https://github.com/BurntSushi/ripgrep) (`rg`).
+Instead of manually specifying which components need `styles` or `as` support, set `externalInterface: "auto"` to auto-detect usage by scanning consumer code.
 
 > [!NOTE]
-> Experimental. Requires `rg` installed and available in `$PATH`. Not supported on Windows.
+> Experimental. Requires `consumerPaths` and a successful prepass scan.
+> If prepass fails, `runTransform()` throws (fail-fast) when `externalInterface: "auto"` is used.
 
 ```ts
-import { defineAdapter, createExternalInterface } from "styled-components-to-stylex-codemod";
-
-const externalInterface = createExternalInterface({ searchDirs: ["src/"] });
+import { runTransform, defineAdapter } from "styled-components-to-stylex-codemod";
 
-export default defineAdapter({
+const adapter = defineAdapter({
   // ...
-  externalInterface: externalInterface.get,
+  externalInterface: "auto",
+});
+
+await runTransform({
+  files: "src/**/*.tsx",
+  consumerPaths: "src/**/*.tsx", // required for auto-detection
+  adapter,
 });
 ```
 
-This scans the given directories for `styled(Component)` calls and `<Component as={...}>` JSX usage, resolves imports back to the component definition files, and returns the appropriate `{ styles, as }` flags automatically.
+When `externalInterface: "auto"` is set, `runTransform()` scans `files` and `consumerPaths` for `styled(Component)` calls and `<Component as={...}>` JSX usage, resolves imports back to the component definition files, and returns the appropriate `{ styles, as }` flags automatically.
+
+If that prepass scan fails, `runTransform()` stops and throws an actionable error rather than silently falling back to non-auto behavior.
+
+Troubleshooting prepass failures with `"auto"`:
+
+- verify `consumerPaths` globs match the files you expect
+- confirm the selected parser matches your source syntax (`parser: "tsx"`, `parser: "ts"`, etc.)
+- check resolver inputs (import paths, tsconfig path aliases, and related module resolution config)
+- if needed, switch to a manual `externalInterface(ctx)` function to continue migration while you fix prepass inputs
 
 #### Dynamic interpolations
 
@@ -190,7 +223,7 @@ When the codemod encounters an interpolation inside a styled template literal, i
 - helper calls applied to prop values (e.g. `shadow(props.shadow)`) by emitting a StyleX style function that calls the helper at runtime
 - conditional CSS blocks via ternary (e.g. `props.$dim ? "opacity: 0.5;" : ""`)
 
-If the pipeline can’t resolve an interpolation:
+If the pipeline can't resolve an interpolation:
 
 - for some dynamic value cases, the transform preserves the value as a wrapper inline style so output keeps visual parity (at the cost of using `style={...}` for that prop)
 - otherwise, the declaration containing that interpolation is **dropped** and a warning is produced (manual follow-up required)
@@ -201,6 +234,39 @@ If the pipeline can’t resolve an interpolation:
 - **createGlobalStyle**: detected usage is reported as an **unsupported-feature** warning (StyleX does not support global styles in the same way).
 - **Theme prop overrides**: passing a `theme` prop directly to styled components (e.g. `<Button theme={...} />`) is not supported and will bail with a warning.
 
+## Migration game plan
+
+### 1. Define your theme and mixins as StyleX
+
+Before running the codemod, convert your theme object and shared style helpers into StyleX equivalents:
+
+```ts
+// tokens.stylex.ts — theme variables
+import * as stylex from "@stylexjs/stylex";
+
+// Before: { colors: { primary: "#0066cc" }, spacing: { sm: "8px" } }
+export const colors = stylex.defineVars({ primary: "#0066cc" });
+export const spacing = stylex.defineVars({ sm: "8px" });
+```
+
+```ts
+// helpers.stylex.ts — shared mixins
+import * as stylex from "@stylexjs/stylex";
+
+// Before: export const truncate = () => `white-space: nowrap; overflow: hidden; ...`
+export const truncate = stylex.create({
+  base: { whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" },
+});
+```
+
+### 2. Write an adapter and run the codemod
+
+The adapter maps your project's `props.theme.*` access, CSS variables, and helper calls to the StyleX equivalents from step 1. See [Usage](#usage) for the full API.
+
+### 3. Verify, iterate, clean up
+
+Build and test your project. Review warnings — they tell you which files were skipped and why. Fix adapter gaps, re-run on remaining files, and repeat until done. [Report issues](https://github.com/skovhus/styled-components-to-stylex-codemod/issues) with input/output examples if the codemod produces incorrect results.
+
 ## License
 
 MIT

package/dist/bridge-consumer-patcher-D3fRIEkZ.mjs

@@ -0,0 +1,122 @@
+import { t as isSelectorContext } from "./selector-context-heuristic-CGwiJ3HL.mjs";
+import { readFileSync } from "node:fs";
+
+//#region src/internal/bridge-consumer-patcher.ts
+/**
+* Post-transform consumer patching for global selector bridges.
+*
+* After the target component is transformed and gets a bridge className,
+* patch unconverted consumer files to:
+*   1. Import the bridge's GlobalSelector variable from the target module
+*   2. Replace `${Component}` selector references with `${ComponentGlobalSelector}`
+*/
+/**
+* Build a mapping from consumer file paths to their required replacements,
+* cross-referencing prepass selector usages with successful bridge results.
+*/
+function buildConsumerReplacements(selectorUsages, bridgeResults) {
+	const consumerReplacements = /* @__PURE__ */ new Map();
+	const bridgeLookup = /* @__PURE__ */ new Map();
+	for (const [targetPath, results] of bridgeResults) for (const result of results) {
+		bridgeLookup.set(`${targetPath}:${result.componentName}`, result);
+		if (result.exportName && result.exportName !== result.componentName) bridgeLookup.set(`${targetPath}:${result.exportName}`, result);
+	}
+	for (const [consumerPath, usages] of selectorUsages) for (const usage of usages) {
+		if (usage.consumerIsTransformed) continue;
+		const bridge = bridgeLookup.get(`${usage.resolvedPath}:${usage.importedName}`);
+		if (!bridge) continue;
+		let replacements = consumerReplacements.get(consumerPath);
+		if (!replacements) {
+			replacements = [];
+			consumerReplacements.set(consumerPath, replacements);
+		}
+		replacements.push({
+			localName: usage.localName,
+			importSource: usage.importSource,
+			globalSelectorVarName: bridge.globalSelectorVarName,
+			importedName: usage.importedName
+		});
+	}
+	return consumerReplacements;
+}
+/**
+* Patch a single consumer file:
+*   1. Add import for each GlobalSelector variable
+*   2. Replace `${Component}` in styled template selectors with `${ComponentGlobalSelector}`
+*
+* Returns the patched source or null if no changes were made.
+*/
+function patchConsumerFile(filePath, replacements) {
+	let source;
+	try {
+		source = readFileSync(filePath, "utf-8");
+	} catch {
+		return null;
+	}
+	if (replacements.length === 0) return null;
+	const bySource = /* @__PURE__ */ new Map();
+	for (const r of replacements) {
+		let list = bySource.get(r.importSource);
+		if (!list) {
+			list = [];
+			bySource.set(r.importSource, list);
+		}
+		list.push(r);
+	}
+	let modified = source;
+	for (const [importSource, reps] of bySource) {
+		const varNames = reps.map((r) => r.globalSelectorVarName);
+		const importRegex = new RegExp(`(import\\s+(?:(?:\\{[^}]*\\}|[^;{]+)\\s+from\\s+['"]${escapeRegExp(importSource)}['"])\\s*;?)`);
+		if (modified.match(importRegex)) {
+			const namedImportRegex = new RegExp(`(import\\s+(?:[\\w$]+\\s*,\\s*)?\\{)([^}]*)(\\}\\s+from\\s+['"]${escapeRegExp(importSource)}['"]\\s*;?)`);
+			const namedMatch = modified.match(namedImportRegex);
+			if (namedMatch) {
+				const existingNames = namedMatch[2];
+				const newNames = varNames.filter((name) => !hasExactImportName(existingNames, name));
+				if (newNames.length > 0) {
+					const separator = existingNames.trimEnd().endsWith(",") ? " " : ", ";
+					modified = modified.replace(namedImportRegex, `$1${existingNames.trimEnd()}${separator}${newNames.join(", ")} $3`);
+				}
+			} else {
+				const newImport = `import { ${varNames.join(", ")} } from "${importSource}";`;
+				modified = modified.replace(importRegex, `$1\n${newImport}`);
+			}
+		} else {
+			const newImport = `import { ${varNames.join(", ")} } from "${importSource}";`;
+			const lastImportIdx = modified.lastIndexOf("\nimport ");
+			if (lastImportIdx !== -1) {
+				const importEnd = findImportEnd(modified, lastImportIdx + 1);
+				modified = modified.slice(0, importEnd) + "\n" + newImport + modified.slice(importEnd);
+			} else modified = newImport + "\n" + modified;
+		}
+	}
+	for (const r of replacements) {
+		const templateExprRegex = new RegExp(`(\\$\\{\\s*)${escapeRegExp(r.localName)}(\\s*\\})`, "g");
+		modified = modified.replace(templateExprRegex, (match, prefix, suffix, offset) => {
+			if (isInStyledTemplateSelectorContext(modified, offset, match.length)) return `${prefix}${r.globalSelectorVarName}${suffix}`;
+			return match;
+		});
+	}
+	return modified !== source ? modified : null;
+}
+/** Find the end position of an import statement starting at startIdx (handles multi-line imports). */
+function findImportEnd(source, startIdx) {
+	const semiIdx = source.indexOf(";", startIdx);
+	if (semiIdx === -1) return source.indexOf("\n", startIdx);
+	return semiIdx + 1;
+}
+/** Check if a template expression at the given position is in a CSS selector context. */
+function isInStyledTemplateSelectorContext(source, offset, length) {
+	const after = source.slice(offset + length).trimStart();
+	return isSelectorContext(source.slice(Math.max(0, offset - 200), offset).trimEnd(), after);
+}
+/** Check if a name appears as a distinct identifier in an import specifier list string. */
+function hasExactImportName(importSpecifiers, name) {
+	return new RegExp(`(?:^|[^A-Za-z0-9_$])${escapeRegExp(name)}(?:$|[^A-Za-z0-9_$])`).test(importSpecifiers);
+}
+function escapeRegExp(s) {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+//#endregion
+export { buildConsumerReplacements, patchConsumerFile };

package/dist/index.d.mts

@@ -1,6 +1,4 @@
-import { i as defineAdapter, t as Adapter } from "./adapter-DilRjT4L.mjs";
-import { createExternalInterface } from "./consumer-analyzer.mjs";
-import { t as CollectedWarning } from "./logger-I_hbSbxa.mjs";
+import { a as defineAdapter, i as AdapterInput, t as CollectedWarning } from "./logger-B7SOfCti.mjs";
 
 //#region src/run.d.ts
 interface RunTransformOptions {
@@ -9,11 +7,32 @@ interface RunTransformOptions {
    * @example "src/**\/*.tsx" or ["src/**\/*.ts", "src/**\/*.tsx"]
    */
   files: string | string[];
+  /**
+   * File glob(s) to scan for cross-file component selector usage, or `null` to opt out.
+   *
+   * When set to a glob pattern, files matching this glob that are NOT in `files` trigger
+   * the bridge strategy (stable bridge className for incremental migration when consumers
+   * are not transformed). Files in both globs use the marker sidecar strategy (both
+   * consumer and target are transformed).
+   *
+   * Required when `externalInterface` is `"auto"`.
+   *
+   * @example "src/**\/*.tsx"
+   * @example null  // opt out of cross-file scanning
+   */
+  consumerPaths: string | string[] | null;
   /**
    * Adapter for customizing the transform.
    * Controls value resolution and resolver-provided imports.
+   *
+   * Use `externalInterface: "auto"` to auto-detect which exported components
+   * need external className/style and polymorphic `as` support by scanning
+   * consumer code specified via `consumerPaths` (or `files`).
+   *
+   * Note: `"auto"` requires prepass scanning to succeed. If prepass fails,
+   * runTransform throws instead of silently falling back.
    */
-  adapter: Adapter;
+  adapter: AdapterInput;
   /**
    * Dry run - don't write changes to files
    * @default false
@@ -37,7 +56,7 @@ interface RunTransformOptions {
   formatterCommands?: string[];
   /**
    * Maximum number of examples shown per warning category in the summary.
-   * @default 15
+   * @default 3
    */
   maxExamples?: number;
 }
@@ -75,6 +94,7 @@ interface RunTransformResult {
  *
  * await runTransform({
  *   files: 'src/**\/*.tsx',
+ *   consumerPaths: null,
  *   adapter,
  *   dryRun: true,
  * });
@@ -82,4 +102,4 @@ interface RunTransformResult {
  */
 declare function runTransform(options: RunTransformOptions): Promise<RunTransformResult>;
 //#endregion
-export { createExternalInterface, defineAdapter, runTransform };
+export { type AdapterInput, defineAdapter, runTransform };

package/dist/index.mjs

@@ -1,10 +1,9 @@
-import { n as assertValidAdapter, r as describeValue, t as Logger } from "./logger-D3j-qxgZ.mjs";
-import { createExternalInterface } from "./consumer-analyzer.mjs";
+import { i as describeValue, r as assertValidAdapterInput, t as Logger } from "./logger-D-R2KB6I.mjs";
 import { run } from "jscodeshift/src/Runner.js";
 import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
-import { existsSync } from "node:fs";
-import { glob } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { glob, writeFile } from "node:fs/promises";
 import { spawn } from "node:child_process";
 
 //#region src/adapter.ts
@@ -64,7 +63,7 @@ import { spawn } from "node:child_process";
 *   });
 */
 function defineAdapter(adapter) {
-	assertValidAdapter(adapter, "defineAdapter(adapter)");
+	assertValidAdapterInput(adapter, "defineAdapter(adapter)");
 	return adapter;
 }
 
@@ -95,6 +94,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 *
 * await runTransform({
 *   files: 'src/**\/*.tsx',
+*   consumerPaths: null,
 *   adapter,
 *   dryRun: true,
 * });
@@ -109,7 +109,7 @@ async function runTransform(options) {
 		"Example (plain JS):",
 		"  import { runTransform, defineAdapter } from \"styled-components-to-stylex-codemod\";",
 		"  const adapter = defineAdapter({ resolveValue() { return null; } });",
-		"  await runTransform({ files: \"src/**/*.tsx\", adapter });"
+		"  await runTransform({ files: \"src/**/*.tsx\", consumerPaths: null, adapter });"
 	].join("\n"));
 	const filesValue = options.files;
 	if (typeof filesValue !== "string" && !Array.isArray(filesValue)) throw new Error([
@@ -122,47 +122,52 @@ async function runTransform(options) {
 		if (filesValue.length === 0) throw new Error(["runTransform(options): `files` must not be an empty array.", "Example: files: [\"src/**/*.ts\", \"src/**/*.tsx\"]"].join("\n"));
 		if (filesValue.find((p) => typeof p !== "string" || p.trim() === "") !== void 0) throw new Error(["runTransform(options): `files` array must contain non-empty strings.", `Received: files=${describeValue(filesValue)}`].join("\n"));
 	}
-	const { files, dryRun = false, print = false, parser = "tsx", formatterCommands, maxExamples } = options;
+	if (options.consumerPaths === void 0) throw new Error([
+		"runTransform(options): `consumerPaths` is required.",
+		"Pass a glob pattern to enable cross-file selector scanning, or `null` to opt out.",
+		"Example: consumerPaths: \"src/**/*.tsx\"  // scan for cross-file usage",
+		"Example: consumerPaths: null             // opt out"
+	].join("\n"));
+	const { files, consumerPaths: consumerPathsOption, dryRun = false, print = false, parser = "tsx", formatterCommands, maxExamples } = options;
 	if (maxExamples !== void 0) Logger.setMaxExamples(maxExamples);
-	const adapter = options.adapter;
-	assertValidAdapter(adapter, "runTransform(options)");
+	const adapterInput = options.adapter;
+	assertValidAdapterInput(adapterInput, "runTransform(options)");
+	if (adapterInput.externalInterface === "auto" && consumerPathsOption === null) throw new Error([
+		"runTransform(options): externalInterface is \"auto\" but consumerPaths is null.",
+		"Auto-detection needs consumer file globs to scan for styled(Component) and as-prop usage.",
+		"Example: consumerPaths: \"src/**/*.tsx\""
+	].join("\n"));
 	const resolveValueWithLogging = (ctx) => {
 		try {
-			return adapter.resolveValue(ctx);
+			return adapterInput.resolveValue(ctx);
 		} catch (e) {
 			const msg = `adapter.resolveValue threw an error: ${e instanceof Error ? e.message : String(e)}`;
 			const filePath = ctx.filePath ?? "<unknown>";
 			Logger.logError(msg, filePath, ctx.loc, ctx);
+			Logger.markErrorAsLogged(e);
 			throw e;
 		}
 	};
 	const resolveCallWithLogging = (ctx) => {
 		try {
-			return adapter.resolveCall(ctx);
+			return adapterInput.resolveCall(ctx);
 		} catch (e) {
 			const msg = `adapter.resolveCall threw an error: ${e instanceof Error ? e.message : String(e)}`;
 			Logger.logError(msg, ctx.callSiteFilePath, ctx.loc, ctx);
+			Logger.markErrorAsLogged(e);
 			throw e;
 		}
 	};
 	const resolveSelectorWithLogging = (ctx) => {
 		try {
-			return adapter.resolveSelector(ctx);
+			return adapterInput.resolveSelector(ctx);
 		} catch (e) {
 			const msg = `adapter.resolveSelector threw an error: ${e instanceof Error ? e.message : String(e)}`;
 			Logger.logError(msg, ctx.filePath, ctx.loc, ctx);
+			Logger.markErrorAsLogged(e);
 			throw e;
 		}
 	};
-	const adapterWithLogging = {
-		styleMerger: adapter.styleMerger,
-		externalInterface(ctx) {
-			return adapter.externalInterface(ctx);
-		},
-		resolveValue: resolveValueWithLogging,
-		resolveCall: resolveCallWithLogging,
-		resolveSelector: resolveSelectorWithLogging
-	};
 	const patterns = Array.isArray(files) ? files : [files];
 	const filePaths = [];
 	const cwd = process.cwd();
@@ -179,7 +184,73 @@ async function runTransform(options) {
 		};
 	}
 	Logger.setFileCount(filePaths.length);
-	const result = await run((() => {
+	const consumerPatterns = consumerPathsOption ? Array.isArray(consumerPathsOption) ? consumerPathsOption : [consumerPathsOption] : [];
+	const consumerFilePaths = [];
+	for (const pattern of consumerPatterns) for await (const file of glob(pattern, { cwd })) consumerFilePaths.push(file);
+	if (consumerPatterns.length > 0 && consumerFilePaths.length === 0) throw new Error([
+		"runTransform(options): consumerPaths matched no files.",
+		`Pattern(s): ${consumerPatterns.join(", ")}`,
+		"Check that the glob pattern is correct and files exist."
+	].join("\n"));
+	const { createModuleResolver } = await import("./resolve-imports-BDk6Ms09.mjs");
+	const sharedResolver = createModuleResolver();
+	const { runPrepass } = await import("./run-prepass-BcidTT9f.mjs");
+	const absoluteFiles = filePaths.map((f) => resolve(f));
+	const absoluteConsumers = consumerFilePaths.map((f) => resolve(f));
+	let prepassResult;
+	try {
+		prepassResult = await runPrepass({
+			filesToTransform: absoluteFiles,
+			consumerPaths: absoluteConsumers,
+			resolver: sharedResolver,
+			parserName: parser,
+			createExternalInterface: adapterInput.externalInterface === "auto",
+			enableAstCache: true
+		});
+	} catch (err) {
+		if (adapterInput.externalInterface === "auto") throw createAutoPrepassFailureError(err, consumerPatterns, parser);
+		Logger.warn(`Prepass failed, continuing without cross-file analysis: ${err instanceof Error ? err.message : String(err)}`);
+		prepassResult = {
+			crossFileInfo: {
+				selectorUsages: /* @__PURE__ */ new Map(),
+				componentsNeedingMarkerSidecar: /* @__PURE__ */ new Map(),
+				componentsNeedingGlobalSelectorBridge: /* @__PURE__ */ new Map()
+			},
+			consumerAnalysis: void 0
+		};
+	}
+	const crossFilePrepassResult = prepassResult.crossFileInfo;
+	const resolvedAdapter = (() => {
+		if (adapterInput.externalInterface === "auto" && prepassResult.consumerAnalysis) {
+			const analysisMap = prepassResult.consumerAnalysis;
+			return {
+				...adapterInput,
+				externalInterface: (ctx) => {
+					let realPath;
+					try {
+						realPath = realpathSync(resolve(ctx.filePath));
+					} catch {
+						realPath = resolve(ctx.filePath);
+					}
+					return analysisMap.get(`${realPath}:${ctx.componentName}`) ?? {
+						styles: false,
+						as: false
+					};
+				}
+			};
+		}
+		return adapterInput;
+	})();
+	const adapterWithLogging = {
+		styleMerger: resolvedAdapter.styleMerger,
+		externalInterface(ctx) {
+			return resolvedAdapter.externalInterface(ctx);
+		},
+		resolveValue: resolveValueWithLogging,
+		resolveCall: resolveCallWithLogging,
+		resolveSelector: resolveSelectorWithLogging
+	};
+	const transformPath = (() => {
 		const adjacent = join(__dirname, "transform.mjs");
 		if (existsSync(adjacent)) return adjacent;
 		const distSibling = join(__dirname, "..", "dist", "transform.mjs");
@@ -190,31 +261,34 @@ async function runTransform(options) {
 			`       ${distSibling}`,
 			"Run `pnpm build` to generate dist artifacts."
 		].join("\n"));
-	})(), filePaths, {
+	})();
+	const sidecarFiles = /* @__PURE__ */ new Map();
+	const bridgeResults = /* @__PURE__ */ new Map();
+	const result = await run(transformPath, filePaths, {
 		parser,
 		dry: dryRun,
 		print,
 		adapter: adapterWithLogging,
+		crossFilePrepassResult,
+		sidecarFiles,
+		bridgeResults,
 		runInBand: true
 	});
-	if (formatterCommands && formatterCommands.length > 0 && result.ok > 0 && !dryRun) for (const formatterCommand of formatterCommands) {
-		const [cmd, ...cmdArgs] = formatterCommand.split(/\s+/);
-		if (cmd) try {
-			await new Promise((resolve, reject) => {
-				const proc = spawn(cmd, [...cmdArgs, ...filePaths], {
-					stdio: "inherit",
-					shell: true
-				});
-				proc.on("close", (code) => {
-					if (code === 0) resolve();
-					else reject(/* @__PURE__ */ new Error(`Formatter command exited with code ${code}`));
-				});
-				proc.on("error", reject);
-			});
-		} catch (e) {
-			Logger.warn(`Formatter command failed: ${e instanceof Error ? e.message : String(e)}`);
+	if (sidecarFiles.size > 0 && !dryRun) for (const [sidecarPath, content] of sidecarFiles) await writeFile(sidecarPath, mergeSidecarContent(sidecarPath, content), "utf-8");
+	if (bridgeResults.size > 0 && !dryRun) {
+		const { buildConsumerReplacements, patchConsumerFile } = await import("./bridge-consumer-patcher-D3fRIEkZ.mjs");
+		const consumerReplacements = buildConsumerReplacements(crossFilePrepassResult.selectorUsages, bridgeResults);
+		const patchedFiles = [];
+		for (const [consumerPath, replacements] of consumerReplacements) {
+			const patched = patchConsumerFile(consumerPath, replacements);
+			if (patched !== null) {
+				await writeFile(consumerPath, patched, "utf-8");
+				patchedFiles.push(consumerPath);
+			}
 		}
+		if (formatterCommands && patchedFiles.length > 0) await runFormatters(formatterCommands, patchedFiles);
 	}
+	if (formatterCommands && formatterCommands.length > 0 && result.ok > 0 && !dryRun) await runFormatters(formatterCommands, filePaths);
 	const report = Logger.createReport();
 	report.print();
 	return {
@@ -226,6 +300,70 @@ async function runTransform(options) {
 		warnings: report.getWarnings()
 	};
 }
+function createAutoPrepassFailureError(err, consumerPatterns, parser) {
+	const reason = err instanceof Error ? err.message : String(err);
+	return new Error([
+		"runTransform(options): prepass failed while using externalInterface: \"auto\".",
+		"\"auto\" depends on successful prepass scanning and cannot continue without it.",
+		`Underlying error: ${reason}`,
+		"",
+		"Troubleshooting:",
+		"  - Verify `consumerPaths` glob(s) and file syntax.",
+		`  - Confirm parser setting matches your code (current parser: ${JSON.stringify(parser)}).`,
+		"  - Check module resolution inputs (tsconfig paths / imports).",
+		"  - Use a manual `externalInterface(ctx)` function to continue without auto-detection.",
+		"",
+		`consumerPaths: ${consumerPatterns.length > 0 ? consumerPatterns.join(", ") : "(none)"}`
+	].join("\n"));
+}
+/**
+* Merge new sidecar marker content into an existing .stylex.ts file, preserving
+* user-owned exports (e.g. defineVars). If the file doesn't exist, returns content as-is.
+*
+* New marker declarations (`export const XMarker = stylex.defineMarker()`) are
+* appended only if they don't already exist in the file. The stylex import is
+* ensured at the top.
+*/
+function mergeSidecarContent(sidecarPath, newContent) {
+	let existing;
+	try {
+		existing = readFileSync(sidecarPath, "utf-8");
+	} catch {
+		return newContent;
+	}
+	const markerLineRe = /^export const \w+ = stylex\.defineMarker\(\);$/gm;
+	const newMarkers = [];
+	for (const m of newContent.matchAll(markerLineRe)) newMarkers.push(m[0]);
+	if (newMarkers.length === 0) return newContent;
+	const markersToAdd = newMarkers.filter((line) => !existing.includes(line));
+	if (markersToAdd.length === 0) return existing;
+	let merged = existing;
+	if (!merged.includes("@stylexjs/stylex")) merged = `import * as stylex from "@stylexjs/stylex";\n\n${merged}`;
+	const trailingNewline = merged.endsWith("\n") ? "" : "\n";
+	merged = merged + trailingNewline + markersToAdd.join("\n") + "\n";
+	return merged;
+}
+/** Run formatter commands on a list of files, logging warnings on failure. */
+async function runFormatters(commands, files) {
+	for (const formatterCommand of commands) {
+		const [cmd, ...cmdArgs] = formatterCommand.split(/\s+/);
+		if (cmd) try {
+			await new Promise((res, rej) => {
+				const proc = spawn(cmd, [...cmdArgs, ...files], {
+					stdio: "inherit",
+					shell: true
+				});
+				proc.on("close", (code) => {
+					if (code === 0) res();
+					else rej(/* @__PURE__ */ new Error(`Formatter command exited with code ${code}`));
+				});
+				proc.on("error", rej);
+			});
+		} catch (e) {
+			Logger.warn(`Formatter command failed: ${e instanceof Error ? e.message : String(e)}`);
+		}
+	}
+}
 
 //#endregion
-export { createExternalInterface, defineAdapter, runTransform };
+export { defineAdapter, runTransform };