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

package/README.md

@@ -4,10 +4,6 @@ Transform styled-components to StyleX.
 
 **[Try it in the online playground](https://skovhus.github.io/styled-components-to-stylex-codemod/)** — experiment with the transform in your browser.
 
-> [!WARNING]
->
-> **Very much under construction (alpha):** this codemod is still early in development — expect rough edges! 🚧
-
 ## Installation
 
 ```bash
@@ -24,10 +20,46 @@ Use `runTransform` to transform files matching a glob pattern:
 import { runTransform, defineAdapter } from "styled-components-to-stylex-codemod";
 
 const adapter = defineAdapter({
+  // Map theme paths and CSS variables to StyleX expressions
+  resolveValue(ctx) {
+    return null;
+  },
+  // Map helper function calls to StyleX expressions
+  resolveCall(ctx) {
+    return null;
+  },
+  // Control which components accept external className/style and polymorphic `as`
+  externalInterface(ctx) {
+    return { style: false, as: false };
+  },
+  // Optional: use a helper for merging StyleX styles with external className/style
+  styleMerger: null,
+});
+
+await runTransform({
+  files: "src/**/*.tsx",
+  consumerPaths: null, // set to a glob to enable cross-file selector support
+  adapter,
+  dryRun: false,
+  parser: "tsx",
+  formatterCommands: ["pnpm prettier --write"],
+});
+```
+
+<details>
+<summary>Full adapter example</summary>
+
+```ts
+import { runTransform, defineAdapter } from "styled-components-to-stylex-codemod";
+
+const adapter = defineAdapter({
+  /**
+   * Resolve dynamic values in styled template literals to StyleX expressions.
+   * Called for theme access (`props.theme.x`), CSS variables (`var(--x)`),
+   * and imported values. Return `{ expr, imports }` or `null` to skip.
+   */
   resolveValue(ctx) {
     if (ctx.kind === "theme") {
-      // Called for patterns like: ${(props) => props.theme.color.primary}
-      // `ctx.path` is the dotted path after `theme.`
       const varName = ctx.path.replace(/\./g, "_");
       return {
         expr: `tokens.${varName}`,
@@ -41,39 +73,11 @@ const adapter = defineAdapter({
     }
 
     if (ctx.kind === "cssVariable") {
-      // Called for CSS values containing `var(--...)`
-      // Note: `fallback` is the raw fallback string inside `var(--x, <fallback>)` (if present).
-      // Note: `definedValue` is populated when the transformer sees a local `--x: <value>` definition.
-      const { name, fallback, definedValue } = ctx;
-
-      // Example: lift `var(--base-size)` to StyleX vars, and optionally drop a matching local definition.
-      if (name === "--base-size") {
-        return {
-          expr: "calcVars.baseSize",
-          imports: [
-            {
-              from: { kind: "specifier", value: "./css-calc.stylex" },
-              names: [{ imported: "calcVars" }],
-            },
-          ],
-          ...(definedValue === "16px" ? { dropDefinition: true } : {}),
-        };
-      }
-
-      // Generic mapping: `--kebab-case` -> `vars.kebabCase`
-      // e.g. `--color-primary` -> `vars.colorPrimary`
-      const toCamelCase = (cssVarName: string) =>
-        cssVarName
-          .replace(/^--/, "")
-          .split("-")
-          .filter(Boolean)
-          .map((part, i) => (i === 0 ? part : part[0]?.toUpperCase() + part.slice(1)))
-          .join("");
-
-      // If you care about fallbacks, you can use `fallback` here to decide whether to resolve or not.
-      void fallback;
+      const toCamelCase = (s: string) =>
+        s.replace(/^--/, "").replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+
       return {
-        expr: `vars.${toCamelCase(name)}`,
+        expr: `vars.${toCamelCase(ctx.name)}`,
         imports: [
           {
             from: { kind: "specifier", value: "./css-variables.stylex" },
@@ -86,19 +90,12 @@ const adapter = defineAdapter({
     return null;
   },
 
+  /**
+   * Resolve helper function calls in template interpolations.
+   * e.g. `${transitionSpeed("slow")}` → `transitionSpeedVars.slow`
+   * Return `{ expr, imports }` or `null` to bail the file with a warning.
+   */
   resolveCall(ctx) {
-    // Called for template interpolations like: ${transitionSpeed("slowTransition")}
-    // `calleeImportedName` is the imported symbol name (works even with aliasing).
-    // `calleeSource` tells you where it came from:
-    // - { kind: "absolutePath", value: "/abs/path" } for relative imports
-    // - { kind: "specifier", value: "some-package/foo" } for package imports
-    //
-    // The codemod determines how to use the result based on context:
-    // - If `ctx.cssProperty` exists (e.g., `border: ${helper()}`) → result is used as a CSS value
-    // - If `ctx.cssProperty` is undefined (e.g., `${helper()}`) → result is used as a StyleX style object
-    //
-    // Use `ctx.cssProperty` to return the appropriate expression for the context.
-
     const arg0 = ctx.args[0];
     const key = arg0?.kind === "literal" && typeof arg0.value === "string" ? arg0.value : null;
     if (ctx.calleeImportedName !== "transitionSpeed" || !key) {
@@ -116,27 +113,43 @@ const adapter = defineAdapter({
     };
   },
 
-  externalInterface() {
-    return null;
+  /**
+   * Control which exported components accept external className/style
+   * and/or polymorphic `as` prop. Return `{ styles, as }` flags.
+   */
+  externalInterface(ctx) {
+    if (ctx.filePath.includes("/shared/components/")) {
+      return { styles: true, as: true };
+    }
+    return { styles: false, as: false };
   },
 
-  styleMerger: null,
+  /**
+   * When `externalInterface` enables styles, use a helper to merge
+   * StyleX styles with external className/style props.
+   * See test-cases/lib/mergedSx.ts for a reference implementation.
+   */
+  styleMerger: {
+    functionName: "mergedSx",
+    importSource: { kind: "specifier", value: "./lib/mergedSx" },
+  },
 });
 
-const result = await runTransform({
+await runTransform({
   files: "src/**/*.tsx",
+  consumerPaths: null,
   adapter,
   dryRun: false,
-  parser: "tsx", // "babel" | "babylon" | "flow" | "ts" | "tsx"
-  formatterCommands: ["pnpm prettier --write"], // optional: format transformed files
+  parser: "tsx",
+  formatterCommands: ["pnpm prettier --write"],
 });
-
-console.log(result);
 ```
 
+</details>
+
 ### Adapter
 
-Adapters are the main extension point. They let you control:
+Adapters are the main extension point, see full example above. They let you control:
 
 - how theme paths, CSS variables, and imported values are turned into StyleX-compatible JS values (`resolveValue`)
 - what extra imports to inject into transformed files (returned from `resolveValue`)
@@ -144,109 +157,56 @@ Adapters are the main extension point. They let you control:
 - 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`)
 
-#### Style Merger
-
-When a component accepts external `className` and/or `style` props (e.g., via `shouldSupportExternalStyling`, or when wrapping a base component that already accepts these props), the generated code needs to merge StyleX styles with externally passed values.
+#### Cross-file selectors (`consumerPaths`)
 
-> **Note:** Allowing external className/style props is generally discouraged in StyleX as it bypasses the type-safe styling system. However, it can be useful during migration to maintain compatibility with existing code that passes these props.
+`consumerPaths` is required. Pass `null` to opt out, or a glob pattern to enable cross-file selector scanning.
 
-By default, this generates verbose inline merging code. You can provide a `styleMerger` to use a helper function instead for cleaner output:
+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
-const adapter = defineAdapter({
-  resolveValue(ctx) {
-    // ... value resolution logic
-    return null;
-  },
-
-  resolveCall() {
-    return null;
-  },
-
-  externalInterface(ctx) {
-    if (ctx.filePath.includes("/shared/components/")) {
-      return { styles: true, as: true };
-    }
-    return { styles: false, as: false };
-  },
-
-  // Use a custom merger function for cleaner output
-  styleMerger: {
-    functionName: "mergedSx",
-    importSource: { kind: "specifier", value: "./lib/mergedSx" },
-  },
+await runTransform({
+  files: "src/components/**/*.tsx", // files to transform
+  consumerPaths: "src/**/*.tsx", // additional files to scan for cross-file usage
+  adapter,
 });
 ```
 
-The merger function should have this signature:
+- 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).
 
-```ts
-function mergedSx(
-  styles: StyleXStyles,
-  className?: string,
-  style?: React.CSSProperties,
-): ReturnType<typeof stylex.props>;
-```
-
-See [`test-cases/lib/mergedSx.ts`](./test-cases/lib/mergedSx.ts) for a reference implementation.
+#### Auto-detecting external interface usage (experimental)
 
-#### External Interface (Styles and Polymorphic `as` Support)
+Instead of manually specifying which components need `styles` or `as` support, set `externalInterface: "auto"` to auto-detect usage by scanning consumer code.
 
-Transformed components are "closed" by default — they don't accept external `className` or `style` props, and exported components only get `as` support when it is used inside the file. Use `externalInterface` to control which exported components should support these features:
+> [!NOTE]
+> Experimental. Requires `consumerPaths` and a successful prepass scan.
+> If prepass fails, `runTransform()` throws (fail-fast) when `externalInterface: "auto"` is used.
 
 ```ts
-const adapter = defineAdapter({
-  resolveValue(ctx) {
-    // ... value resolution logic
-    return null;
-  },
-
-  resolveCall() {
-    return null;
-  },
-
-  externalInterface(ctx) {
-    // ctx: { filePath, componentName, exportName, isDefaultExport }
-
-    // Example: Enable styles and `as` for all exports in shared components folder
-    if (ctx.filePath.includes("/shared/components/")) {
-      return { styles: true, as: true };
-    }
-
-    // Example: Enable only styles (no `as` prop)
-    if (ctx.filePath.includes("/design-system/")) {
-      return { styles: true, as: false };
-    }
-
-    // Example: Enable only `as` prop (no style merging)
-    if (ctx.componentName === "Typography") {
-      return { styles: false, as: true };
-    }
+import { runTransform, defineAdapter } from "styled-components-to-stylex-codemod";
 
-    // Disable both (default)
-    return { styles: false, as: false };
-  },
+const adapter = defineAdapter({
+  // ...
+  externalInterface: "auto",
+});
 
-  styleMerger: null,
+await runTransform({
+  files: "src/**/*.tsx",
+  consumerPaths: "src/**/*.tsx", // required for auto-detection
+  adapter,
 });
 ```
 
-The `externalInterface` method returns:
-
-- `{ styles: false, as: false }` — no external interface
-- `{ styles: true, as: false }` — accept className/style props only
-- `{ styles: true, as: true }` — accept className/style props AND polymorphic `as` prop
-- `{ styles: false, as: true }` — accept only polymorphic `as` prop (no style merging)
-
-When `styles: true`, the generated component will:
+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.
 
-- Accept `className` and `style` props
-- Merge them with the StyleX-generated styles
-- Forward remaining props via `...rest`
+If that prepass scan fails, `runTransform()` stops and throws an actionable error rather than silently falling back to non-auto behavior.
 
-When `as: true` is also set, the component will additionally accept a polymorphic `as` prop for rendering as a different element type.
+Troubleshooting prepass failures with `"auto"`:
 
-When `{ styles: false, as: true }`, the generated component will accept a polymorphic `as` prop but won't include className/style merging.
+- 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
 
@@ -263,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)
@@ -274,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,4 +1,4 @@
-import { i as defineAdapter, r as Adapter, t as CollectedWarning } from "./logger-kU4pnRpt.mjs";
+import { a as defineAdapter, i as AdapterInput, t as CollectedWarning } from "./logger-B7SOfCti.mjs";
 
 //#region src/run.d.ts
 interface RunTransformOptions {
@@ -7,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
@@ -35,7 +56,7 @@ interface RunTransformOptions {
   formatterCommands?: string[];
   /**
    * Maximum number of examples shown per warning category in the summary.
-   * @default 15
+   * @default 3
    */
   maxExamples?: number;
 }
@@ -73,6 +94,7 @@ interface RunTransformResult {
  *
  * await runTransform({
  *   files: 'src/**\/*.tsx',
+ *   consumerPaths: null,
  *   adapter,
  *   dryRun: true,
  * });
@@ -80,4 +102,4 @@ interface RunTransformResult {
  */
 declare function runTransform(options: RunTransformOptions): Promise<RunTransformResult>;
 //#endregion
-export { defineAdapter, runTransform };
+export { type AdapterInput, defineAdapter, runTransform };