styled-components-to-stylex-codemod 0.0.7 → 0.0.10

package/README.md

@@ -21,10 +21,7 @@ pnpm add styled-components-to-stylex-codemod
 Use `runTransform` to transform files matching a glob pattern:
 
 ```ts
-import {
-  runTransform,
-  defineAdapter,
-} from "styled-components-to-stylex-codemod";
+import { runTransform, defineAdapter } from "styled-components-to-stylex-codemod";
 
 const adapter = defineAdapter({
   resolveValue(ctx) {
@@ -70,9 +67,7 @@ const adapter = defineAdapter({
           .replace(/^--/, "")
           .split("-")
           .filter(Boolean)
-          .map((part, i) =>
-            i === 0 ? part : part[0]?.toUpperCase() + part.slice(1)
-          )
+          .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.
@@ -88,44 +83,44 @@ const adapter = defineAdapter({
       };
     }
 
-    if (ctx.kind === "call") {
-      // 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
-
-      if (ctx.calleeImportedName !== "transitionSpeed") {
-        return null;
-      }
-
-      // If you need to scope resolution to a particular module, you can use:
-      // - ctx.calleeSource
-
-      const arg0 = ctx.args[0];
-      const key =
-        arg0?.kind === "literal" && typeof arg0.value === "string"
-          ? arg0.value
-          : null;
-      if (!key) {
-        return null;
-      }
+    return null;
+  },
 
-      return {
-        expr: `transitionSpeedVars.${key}`,
-        imports: [
-          {
-            from: { kind: "specifier", value: "./lib/helpers.stylex" },
-            names: [
-              { imported: "transitionSpeed", local: "transitionSpeedVars" },
-            ],
-          },
-        ],
-      };
+  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) {
+      return null;
     }
 
+    return {
+      expr: `transitionSpeedVars.${key}`,
+      imports: [
+        {
+          from: { kind: "specifier", value: "./lib/helpers.stylex" },
+          names: [{ imported: "transitionSpeed", local: "transitionSpeedVars" }],
+        },
+      ],
+    };
+  },
+
+  externalInterface() {
     return null;
   },
+
+  styleMerger: null,
 });
 
 const result = await runTransform({
@@ -143,10 +138,10 @@ console.log(result);
 
 Adapters are the main extension point. They let you control:
 
-- how theme paths and CSS variables are turned into StyleX-compatible JS values (`resolveValue`)
+- 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`)
-- how helper calls are resolved (via `resolveValue({ kind: "call", ... })`)
-- which exported components should support external className/style extension (`shouldSupportExternalStyling`)
+- how helper calls are resolved (via `resolveCall({ ... })` returning `{ expr, imports }`; `null`/`undefined` bails the file)
+- 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
@@ -164,8 +159,15 @@ const adapter = defineAdapter({
     return null;
   },
 
-  shouldSupportExternalStyling(ctx) {
-    return ctx.filePath.includes("/shared/components/");
+  resolveCall() {
+    return null;
+  },
+
+  externalInterface(ctx) {
+    if (ctx.filePath.includes("/shared/components/")) {
+      return { styles: true };
+    }
+    return null;
   },
 
   // Use a custom merger function for cleaner output
@@ -182,15 +184,15 @@ The merger function should have this signature:
 function mergedSx(
   styles: StyleXStyles,
   className?: string,
-  style?: React.CSSProperties
+  style?: React.CSSProperties,
 ): ReturnType<typeof stylex.props>;
 ```
 
 See [`test-cases/lib/mergedSx.ts`](./test-cases/lib/mergedSx.ts) for a reference implementation.
 
-#### External Styles Support
+#### External Interface (Styles and Polymorphic `as` Support)
 
-Transformed components are "closed" by default — they don't accept external `className` or `style` props. Use `shouldSupportExternalStyling` to control which exported components should support external styling:
+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:
 
 ```ts
 const adapter = defineAdapter({
@@ -199,37 +201,59 @@ const adapter = defineAdapter({
     return null;
   },
 
-  shouldSupportExternalStyling(ctx) {
+  resolveCall() {
+    return null;
+  },
+
+  externalInterface(ctx) {
     // ctx: { filePath, componentName, exportName, isDefaultExport }
 
-    // Example: Enable for all exports in shared components folder
+    // Example: Enable styles (and `as`) for all exports in shared components folder
     if (ctx.filePath.includes("/shared/components/")) {
-      return true;
+      return { styles: true };
     }
 
-    // Example: Enable for specific component names
-    if (ctx.componentName === "Button" || ctx.componentName === "Card") {
-      return true;
+    // Example: Enable only `as` prop (no style merging)
+    if (ctx.componentName === "Typography") {
+      return { styles: false, as: true };
     }
 
-    return false;
+    // Disable both (default)
+    return null;
   },
+
+  styleMerger: null,
 });
 ```
 
-When `shouldSupportExternalStyling` returns `true`, the generated component will:
+The `externalInterface` method returns:
+
+- `null` — no external interface (neither className/style nor `as` prop)
+- `{ styles: true }` — accept className/style props AND polymorphic `as` prop
+- `{ styles: false, as: true }` — accept only polymorphic `as` prop (no style merging)
+- `{ styles: false, as: false }` — equivalent to `null`
+
+When `styles: true`, the generated component will:
 
 - Accept `className` and `style` props
 - Merge them with the StyleX-generated styles
 - Forward remaining props via `...rest`
+- Accept polymorphic `as` prop (required for style merging to work correctly)
+
+When `{ styles: false, as: true }`, the generated component will accept a polymorphic `as` prop but won't include className/style merging.
 
 #### Dynamic interpolations
 
 When the codemod encounters an interpolation inside a styled template literal, it runs an internal dynamic resolution pipeline which covers common cases like:
 
 - theme access (`props.theme...`) via `resolveValue({ kind: "theme", path })`
+- imported value access (`import { zIndex } ...; ${zIndex.popover}`) via `resolveValue({ kind: "importedValue", importedName, source, path })`
 - prop access (`props.foo`) and conditionals (`props.foo ? "a" : "b"`, `props.foo && "color: red;"`)
-- simple helper calls (`transitionSpeed("slowTransition")`) via `resolveValue({ kind: "call", calleeImportedName, calleeSource, args, ... })`
+- helper calls (`transitionSpeed("slowTransition")`) via `resolveCall({ ... })` — the codemod infers usage from context:
+  - With `ctx.cssProperty` (e.g., `color: ${helper()}`) → result used as CSS value in `stylex.create()`
+  - Without `ctx.cssProperty` (e.g., `${helper()}`) → result used as StyleX styles in `stylex.props()`
+  - Use the optional `usage: "create" | "props"` field to override the default inference
+- if `resolveCall` returns `null` or `undefined`, the transform **bails the file** and logs a warning
 - 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;" : ""`)
 
@@ -241,8 +265,8 @@ If the pipeline can’t resolve an interpolation:
 ### Limitations
 
 - **Flow** type generation is non-existing, works best with TypeScript or plain JS right now. Contributions more than welcome!
-- **ThemeProvider**: if a file imports and uses `ThemeProvider` from `styled-components`, the transform **skips the entire file** (theming strategy is project-specific).
 - **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.
 
 ## License
 

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { i as defineAdapter, r as Adapter, t as CollectedWarning } from "./logger-BS4Evg0n.mjs";
+import { i as defineAdapter, r as Adapter, t as CollectedWarning } from "./logger-DC-1uogs.mjs";
 
 //#region src/run.d.ts
 interface RunTransformOptions {

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { n as assertValidAdapter, r as describeValue, t as Logger } from "./logger-Dlnt1fYP.mjs";
+import { n as assertValidAdapter, r as describeValue, t as Logger } from "./logger-BLeJjMzG.mjs";
 import { run } from "jscodeshift/src/Runner.js";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
@@ -8,11 +8,15 @@ import { spawn } from "node:child_process";
 
 //#region src/adapter.ts
 /**
-* Adapter - Single user entry point for customizing the codemod.
+* Adapter entry point for customizing the codemod.
+* Core concepts: value resolution hooks and adapter validation.
 */
 /**
 * Helper for nicer user authoring + type inference.
 *
+* `defineAdapter(...)` also performs runtime validation (helpful for JS consumers)
+* and will throw a descriptive error message if the adapter shape is invalid.
+*
 * Usage:
 *   export default defineAdapter({
 *     resolveValue(ctx) {
@@ -24,14 +28,37 @@ import { spawn } from "node:child_process";
 *           ],
 *         };
 *       }
-*       return null;
+*       // Return undefined to bail/skip the file
+*     },
+*
+*     resolveCall(ctx) {
+*       // Resolve helper calls inside template interpolations.
+*       // Use ctx.cssProperty to determine context:
+*       // - If ctx.cssProperty exists → return a CSS value expression
+*       // - If ctx.cssProperty is undefined → return a StyleX style object reference
+*       // Return { expr, imports } or undefined to bail/skip the file
+*       void ctx;
 *     },
 *
-*     // Enable className/style/rest support for exported components
-*     shouldSupportExternalStyling(ctx) {
-*       // Example: Enable for all exported components in a shared components folder
-*       return ctx.filePath.includes("/shared/components/");
+*     resolveSelector(ctx) {
+*       // Resolve imported values used in selector position (e.g., media query helpers).
+*       // Return:
+*       // - { kind: "media", expr, imports } for media queries (e.g., breakpoints.phone)
+*       // - undefined to bail/skip the file
+*       void ctx;
 *     },
+*
+*     // Configure external interface for exported components
+*     externalInterface(ctx) {
+*       // Example: Enable styles (and `as`) for shared components folder
+*       if (ctx.filePath.includes("/shared/components/")) {
+*         return { styles: true };
+*       }
+*       return null;
+*     },
+*
+*     // Optional: provide a custom merger, or use `null` for the default verbose merge output
+*     styleMerger: null,
 *   });
 */
 function defineAdapter(adapter) {
@@ -41,6 +68,10 @@ function defineAdapter(adapter) {
 
 //#endregion
 //#region src/run.ts
+/**
+* Runs the codemod over input files with an adapter.
+* Core concepts: jscodeshift execution, globs, and adapter hooks.
+*/
 const __dirname = dirname(fileURLToPath(import.meta.url));
 /**
 * Run the styled-components to StyleX transform on files matching the glob pattern.
@@ -92,20 +123,42 @@ async function runTransform(options) {
 	const { files, dryRun = false, print = false, parser = "tsx", formatterCommand } = options;
 	const adapter = options.adapter;
 	assertValidAdapter(adapter, "runTransform(options)");
+	const resolveValueWithLogging = (ctx) => {
+		try {
+			return adapter.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);
+			throw e;
+		}
+	};
+	const resolveCallWithLogging = (ctx) => {
+		try {
+			return adapter.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);
+			throw e;
+		}
+	};
+	const resolveSelectorWithLogging = (ctx) => {
+		try {
+			return adapter.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);
+			throw e;
+		}
+	};
 	const adapterWithLogging = {
 		styleMerger: adapter.styleMerger,
-		shouldSupportExternalStyling(ctx) {
-			return adapter.shouldSupportExternalStyling(ctx);
+		externalInterface(ctx) {
+			return adapter.externalInterface(ctx);
 		},
-		resolveValue(ctx) {
-			try {
-				return adapter.resolveValue(ctx);
-			} catch (e) {
-				const msg = `adapter.resolveValue threw an error: ${e instanceof Error ? e.message : String(e)}`;
-				Logger.error(msg, ctx);
-				throw e;
-			}
-		}
+		resolveValue: resolveValueWithLogging,
+		resolveCall: resolveCallWithLogging,
+		resolveSelector: resolveSelectorWithLogging
 	};
 	const patterns = Array.isArray(files) ? files : [files];
 	const filePaths = [];
@@ -143,13 +196,13 @@ async function runTransform(options) {
 	if (formatterCommand && result.ok > 0 && !dryRun) {
 		const [cmd, ...cmdArgs] = formatterCommand.split(/\s+/);
 		if (cmd) try {
-			await new Promise((resolve$1, reject) => {
+			await new Promise((resolve, reject) => {
 				const proc = spawn(cmd, [...cmdArgs, ...filePaths], {
 					stdio: "inherit",
 					shell: true
 				});
 				proc.on("close", (code) => {
-					if (code === 0) resolve$1();
+					if (code === 0) resolve();
 					else reject(/* @__PURE__ */ new Error(`Formatter command exited with code ${code}`));
 				});
 				proc.on("error", reject);
@@ -158,13 +211,15 @@ async function runTransform(options) {
 			Logger.warn(`Formatter command failed: ${e instanceof Error ? e.message : String(e)}`);
 		}
 	}
+	const report = Logger.createReport();
+	report.print();
 	return {
 		errors: result.error,
 		unchanged: result.nochange,
 		skipped: result.skip,
 		transformed: result.ok,
 		timeElapsed: parseFloat(result.timeElapsed) || 0,
-		warnings: Logger.flushWarnings()
+		warnings: report.getWarnings()
 	};
 }