styled-components-to-stylex-codemod 0.0.1 → 0.0.2

package/README.md

@@ -2,6 +2,12 @@
 
 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
@@ -140,6 +146,42 @@ Adapters are the main extension point. They let you control:
 - how theme paths and CSS variables 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`)
+
+#### External Styles 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:
+
+```ts
+const adapter = defineAdapter({
+  resolveValue(ctx) {
+    // ... value resolution logic
+    return null;
+  },
+
+  shouldSupportExternalStyling(ctx) {
+    // ctx: { filePath, componentName, exportName, isDefaultExport }
+
+    // Example: Enable for all exports in shared components folder
+    if (ctx.filePath.includes("/shared/components/")) {
+      return true;
+    }
+
+    // Example: Enable for specific component names
+    if (ctx.componentName === "Button" || ctx.componentName === "Card") {
+      return true;
+    }
+
+    return false;
+  },
+});
+```
+
+When `shouldSupportExternalStyling` returns `true`, the generated component will:
+
+- Accept `className` and `style` props
+- Merge them with the StyleX-generated styles
+- Forward remaining props via `...rest`
 
 #### Dynamic interpolations
 
@@ -154,23 +196,12 @@ If the pipeline can’t resolve an interpolation:
 - for `withConfig({ shouldForwardProp })` wrappers, the transform preserves the value as an inline style so output keeps visual parity
 - otherwise, the declaration containing that interpolation is **dropped** and a warning is produced (manual follow-up required)
 
-### Notes / Limitations
+### 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).
 
-### Transform Result
-
-```ts
-interface RunTransformResult {
-  errors: number; // Files that had errors
-  unchanged: number; // Files that were unchanged
-  skipped: number; // Files that were skipped
-  transformed: number; // Files that were transformed
-  timeElapsed: number; // Total time in seconds
-}
-```
-
 ## License
 
 MIT

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as defineAdapter, i as Adapter, r as TransformWarning } from "./transform-types-CCX_WVPh.mjs";
+import { a as defineAdapter, i as Adapter, r as TransformWarning } from "./transform-types-Cry4CAGJ.mjs";
 
 //#region src/internal/logger.d.ts
 interface CollectedWarning extends TransformWarning {

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { n as logWarning, t as flushWarnings } from "./logger-D09HOyqF.mjs";
+import { a as describeValue, i as assertValidAdapter, n as logWarning, t as flushWarnings } from "./logger-Ckk2VkqY.mjs";
 import { run } from "jscodeshift/src/Runner.js";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
@@ -8,6 +8,9 @@ import { spawn } from "node:child_process";
 
 //#region src/adapter.ts
 /**
+* Adapter - Single user entry point for customizing the codemod.
+*/
+/**
 * Helper for nicer user authoring + type inference.
 *
 * Usage:
@@ -24,14 +27,15 @@ import { spawn } from "node:child_process";
 *       return null;
 *     },
 *
-*     // Optional: Enable className/style/rest support for exported components
-*     shouldSupportExternalStyles(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/");
 *     },
 *   });
 */
 function defineAdapter(adapter) {
+	assertValidAdapter(adapter, "defineAdapter(adapter)");
 	return adapter;
 }
 
@@ -64,19 +68,45 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 * ```
 */
 async function runTransform(options) {
+	if (!options || typeof options !== "object") throw new Error([
+		"[styled-components-to-stylex] runTransform(options) was called with an invalid argument.",
+		"Expected: runTransform({ files: string | string[], adapter: Adapter, ... })",
+		`Received: ${describeValue(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 });"
+	].join("\n"));
+	const filesValue = options.files;
+	if (typeof filesValue !== "string" && !Array.isArray(filesValue)) throw new Error([
+		"[styled-components-to-stylex] runTransform(options): `files` is required.",
+		"Expected: files: string | string[]",
+		`Received: files=${describeValue(filesValue)}`
+	].join("\n"));
+	if (typeof filesValue === "string" && filesValue.trim() === "") throw new Error(["[styled-components-to-stylex] runTransform(options): `files` must be a non-empty string.", "Example: files: \"src/**/*.tsx\""].join("\n"));
+	if (Array.isArray(filesValue)) {
+		if (filesValue.length === 0) throw new Error(["[styled-components-to-stylex] 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(["[styled-components-to-stylex] 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 adapter = options.adapter;
-	if (!adapter || typeof adapter.resolveValue !== "function") throw new Error("Adapter must provide resolveValue(ctx) => { expr, imports } | null");
-	const adapterWithLogging = { resolveValue(ctx) {
-		try {
-			return adapter.resolveValue(ctx);
-		} catch (e) {
-			const kind = ctx?.kind;
-			const details = kind === "theme" ? `path=${String(ctx.path ?? "")}` : kind === "cssVariable" ? `name=${String(ctx.name ?? "")}` : kind === "call" ? `callee=${String(ctx.calleeImportedName ?? "")} source=${String(ctx.calleeSource?.value ?? "")} file=${String(ctx.callSiteFilePath ?? "")}` : "";
-			logWarning(`[styled-components-to-stylex] adapter.resolveValue threw${kind ? ` (kind=${kind}${details ? ` ${details}` : ""})` : ""}: ${e?.stack ?? String(e)}\n`);
-			throw e;
+	assertValidAdapter(adapter, "runTransform(options)");
+	const adapterWithLogging = {
+		shouldSupportExternalStyling(ctx) {
+			return adapter.shouldSupportExternalStyling(ctx);
+		},
+		resolveValue(ctx) {
+			try {
+				return adapter.resolveValue(ctx);
+			} catch (e) {
+				const kind = ctx?.kind;
+				const details = kind === "theme" ? `path=${String(ctx.path ?? "")}` : kind === "cssVariable" ? `name=${String(ctx.name ?? "")}` : kind === "call" ? `callee=${String(ctx.calleeImportedName ?? "")} source=${String(ctx.calleeSource?.value ?? "")} file=${String(ctx.callSiteFilePath ?? "")}` : "";
+				logWarning(`[styled-components-to-stylex] adapter.resolveValue threw${kind ? ` (kind=${kind}${details ? ` ${details}` : ""})` : ""}: ${e?.stack ?? String(e)}\n`);
+				throw e;
+			}
 		}
-	} };
+	};
 	const patterns = Array.isArray(files) ? files : [files];
 	const filePaths = [];
 	const cwd = process.cwd();

package/dist/logger-Ckk2VkqY.mjs

@@ -0,0 +1,89 @@
+//#region src/internal/public-api-validation.ts
+const ADAPTER_DOCS_URL = `https://github.com/skovhus/styled-components-to-stylex-codemod#adapter`;
+function describeValue(value) {
+	if (value === null) return "null";
+	if (value === void 0) return "undefined";
+	if (Array.isArray(value)) return `Array(${value.length})`;
+	if (typeof value === "string") return `"${value}"`;
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	if (typeof value === "bigint") return value.toString();
+	if (typeof value === "symbol") return value.description ? `Symbol(${value.description})` : "Symbol()";
+	if (typeof value === "function") return "[Function]";
+	if (typeof value === "object") {
+		const ctor = value?.constructor?.name ?? "Object";
+		let keys = [];
+		try {
+			keys = Object.keys(value);
+		} catch {}
+		const preview = keys.slice(0, 5).join(", ");
+		const suffix = keys.length > 5 ? ", ..." : "";
+		return keys.length ? `${ctor} { ${preview}${suffix} }` : ctor;
+	}
+	return "[Unknown]";
+}
+function assertValidAdapter(candidate, where) {
+	const obj = candidate;
+	const resolveValue = obj?.resolveValue;
+	const shouldSupportExternalStyling = obj?.shouldSupportExternalStyling;
+	if (!candidate || typeof candidate !== "object") throw new Error([
+		`[styled-components-to-stylex] ${where}: expected an adapter object.`,
+		`Received: ${describeValue(candidate)}`,
+		"",
+		"Adapter requirements:",
+		"  - adapter.resolveValue(context) is required",
+		"  - adapter.shouldSupportExternalStyling(context) is required",
+		"",
+		"resolveValue(context) is called with one of these shapes:",
+		"  - { kind: \"theme\", path }",
+		"  - { kind: \"cssVariable\", name, fallback?, definedValue? }",
+		"  - { kind: \"call\", callSiteFilePath, calleeImportedName, calleeSource, args }",
+		"",
+		`Docs/examples: ${ADAPTER_DOCS_URL}`
+	].join("\n"));
+	if (typeof resolveValue !== "function") throw new Error([
+		`[styled-components-to-stylex] ${where}: adapter.resolveValue must be a function.`,
+		`Received: resolveValue=${describeValue(resolveValue)}`,
+		"",
+		"Adapter shape:",
+		"  {",
+		"    resolveValue(context) { return { expr: string, imports: ImportSpec[] } | null }",
+		"  }",
+		"",
+		`Docs/examples: ${ADAPTER_DOCS_URL}`
+	].join("\n"));
+	if (typeof shouldSupportExternalStyling !== "function") throw new Error([`[styled-components-to-stylex] ${where}: adapter.shouldSupportExternalStyling must be a function.`, `Received: shouldSupportExternalStyling=${describeValue(shouldSupportExternalStyling)}`].join("\n"));
+}
+
+//#endregion
+//#region src/internal/logger.ts
+let collected = [];
+/**
+* Clear collected warnings and return them.
+*/
+function flushWarnings() {
+	const result = collected;
+	collected = [];
+	return result;
+}
+/**
+* Log a warning message to stderr.
+* All codemod warnings go through this so tests can mock it.
+*/
+function logWarning(message) {
+	process.stderr.write(message);
+}
+/**
+* Log transform warnings to stderr and collect them.
+*/
+function logWarnings(warnings, filePath) {
+	for (const warning of warnings) {
+		collected.push({
+			...warning,
+			filePath
+		});
+		logWarning(`[styled-components-to-stylex] Warning${warning.loc ? ` (${filePath}:${warning.loc.line}:${warning.loc.column})` : ` (${filePath})`}: ${warning.message}\n`);
+	}
+}
+
+//#endregion
+export { describeValue as a, assertValidAdapter as i, logWarning as n, logWarnings as r, flushWarnings as t };

package/dist/{transform-types-CCX_WVPh.d.mts → transform-types-Cry4CAGJ.d.mts}

@@ -93,9 +93,9 @@ interface Adapter {
   /**
    * Called for exported styled components to determine if they should support
    * external className/style extension. Return true to generate wrapper with
-   * className/style/rest merging. Default: false.
+   * className/style/rest merging.
    */
-  shouldSupportExternalStyles?: (context: ExternalStylesContext) => boolean;
+  shouldSupportExternalStyling: (context: ExternalStylesContext) => boolean;
 }
 /**
  * Helper for nicer user authoring + type inference.
@@ -114,8 +114,8 @@ interface Adapter {
  *       return null;
  *     },
  *
- *     // Optional: Enable className/style/rest support for exported components
- *     shouldSupportExternalStyles(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/");
  *     },

package/dist/transform.d.mts

@@ -1,4 +1,4 @@
-import { n as TransformResult, r as TransformWarning, t as TransformOptions } from "./transform-types-CCX_WVPh.mjs";
+import { n as TransformResult, r as TransformWarning, t as TransformOptions } from "./transform-types-Cry4CAGJ.mjs";
 import { API, FileInfo, Options } from "jscodeshift";
 
 //#region src/transform.d.ts