styled-components-to-stylex-codemod 0.0.9 → 0.0.11

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.
@@ -97,18 +92,20 @@ const adapter = defineAdapter({
     // `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;
+    const key = arg0?.kind === "literal" && typeof arg0.value === "string" ? arg0.value : null;
     if (ctx.calleeImportedName !== "transitionSpeed" || !key) {
       return null;
     }
 
     return {
-      usage: "create",
       expr: `transitionSpeedVars.${key}`,
       imports: [
         {
@@ -119,9 +116,11 @@ const adapter = defineAdapter({
     };
   },
 
-  shouldSupportExternalStyling() {
-    return false;
+  externalInterface() {
+    return null;
   },
+
+  styleMerger: null,
 });
 
 const result = await runTransform({
@@ -139,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 `resolveCall({ ... })` returning `usage: "props" | "create"`; `null`/`undefined` now bails)
-- 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
@@ -160,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
@@ -178,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({
@@ -195,39 +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 `resolveCall({ ... })` returning `usage: "create"`
-- style helper calls (returning StyleX styles) via `resolveCall({ ... })` returning `usage: "props"`; these are emitted as extra `stylex.props(...)` args
-- if `resolveCall` returns `null` or `undefined`, the transform now **bails the file** and logs a warning
+- 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;" : ""`)
 
@@ -239,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-CNmtK-uJ.mjs";
+import { i as defineAdapter, r as Adapter, t as CollectedWarning } from "./logger-BkySFMoy.mjs";
 
 //#region src/run.d.ts
 interface RunTransformOptions {
@@ -33,6 +33,11 @@ interface RunTransformOptions {
    * @example "pnpm prettier --write"
    */
   formatterCommand?: string;
+  /**
+   * Maximum number of examples shown per warning category in the summary.
+   * @default 15
+   */
+  maxExamples?: number;
 }
 interface RunTransformResult {
   /** Number of files that had errors */

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { n as assertValidAdapter, r as describeValue, t as Logger } from "./logger-DKelw2HS.mjs";
+import { n as assertValidAdapter, r as describeValue, t as Logger } from "./logger-D3j-qxgZ.mjs";
 import { run } from "jscodeshift/src/Runner.js";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
@@ -8,7 +8,8 @@ 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.
@@ -27,23 +28,34 @@ import { spawn } from "node:child_process";
 *           ],
 *         };
 *       }
-*       return null;
+*       // Return undefined to bail/skip the file
 *     },
 *
 *     resolveCall(ctx) {
 *       // Resolve helper calls inside template interpolations.
-*       // Return:
-*       // - { usage: "props", expr, imports } for StyleX styles (usable in stylex.props)
-*       // - { usage: "create", expr, imports } for a single value (usable in stylex.create)
-*       // - null to leave the call unresolved
+*       // 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;
-*       return null;
 *     },
 *
-*     // 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.
+*       // Return one of:
+*       // - { kind: "media", expr, imports } for media queries (e.g., breakpoints.phone)
+*       // - { kind: "pseudoAlias", values, styleSelectorExpr?, imports? } for pseudo-class expansion
+*       // - 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
@@ -57,6 +69,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.
@@ -105,7 +121,8 @@ 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", formatterCommand } = options;
+	const { files, dryRun = false, print = false, parser = "tsx", formatterCommand, maxExamples } = options;
+	if (maxExamples !== void 0) Logger.setMaxExamples(maxExamples);
 	const adapter = options.adapter;
 	assertValidAdapter(adapter, "runTransform(options)");
 	const resolveValueWithLogging = (ctx) => {
@@ -114,7 +131,7 @@ async function runTransform(options) {
 		} 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, void 0, ctx);
+			Logger.logError(msg, filePath, ctx.loc, ctx);
 			throw e;
 		}
 	};
@@ -123,17 +140,27 @@ async function runTransform(options) {
 			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, void 0, ctx);
+			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: resolveValueWithLogging,
-		resolveCall: resolveCallWithLogging
+		resolveCall: resolveCallWithLogging,
+		resolveSelector: resolveSelectorWithLogging
 	};
 	const patterns = Array.isArray(files) ? files : [files];
 	const filePaths = [];
@@ -150,6 +177,7 @@ async function runTransform(options) {
 			warnings: []
 		};
 	}
+	Logger.setFileCount(filePaths.length);
 	const result = await run((() => {
 		const adjacent = join(__dirname, "transform.mjs");
 		if (existsSync(adjacent)) return adjacent;
@@ -171,13 +199,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);
@@ -186,13 +214,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()
 	};
 }