Implement initial transform

oxlint.json → .oxlintrc.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://raw.githubusercontent.com/oxc-project/oxc/main/npm/oxlint/configuration_schema.json",
   "rules": {
-    "no-unused-vars": "warn",
-    "no-console": "warn",
+    "no-unused-vars": "error",
+    "no-console": "error",
     "eqeqeq": "error"
   },
   "ignorePatterns": [

.vscode/settings.json

@@ -0,0 +1,9 @@
+{
+  "editor.formatOnSave": true,
+  "[javascript]": {
+    "editor.defaultFormatter": "oxc.oxc-vscode"
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "oxc.oxc-vscode"
+  }
+}

CLAUDE.md

@@ -36,9 +36,9 @@ pnpm storybook        # Start Storybook dev server (port 6006)
 src/
 ├── index.ts              # Main exports
 ├── transform.ts          # Transform implementation
-├── transform.test.ts     # Test runner (auto-discovers test cases)
+├── __tests__/transform.test.ts     # Test runner (auto-discovers test cases)
 ├── run.ts                # Programmatic runner (runTransform)
-└── adapter.ts            # Adapter interface and default adapter
+└── adapter.ts            # Adapter API (value resolution + dynamic handlers)
 
 test-cases/
 ├── *.input.tsx           # Input files (styled-components)
@@ -60,13 +60,13 @@ test-cases/
 
 Create matching `.input.tsx` and `.output.tsx` files in `test-cases/`. Tests auto-discover all pairs and fail if any file is missing its counterpart.
 
+Unsupported fixtures can be named `_unsupported.<case>.input.tsx` and should NOT have an output file.
+
 **Test categories:**
 
 - **File pairing**: Verifies all test cases have matching input/output files
 - **Output linting**: Runs oxlint on all output files to ensure valid code
-- **Transform tests** (skipped): Will verify transform produces expected output once implemented
-
-**Note**: The transform is currently a stub that adds TODO comments. The transform tests are skipped until implementation is complete. Output files represent the expected transformation results.
+- **Transform tests**: Verifies transform produces expected output fixtures for supported cases
 
 ## Storybook Visual Testing
 
@@ -88,52 +88,34 @@ Use the Playwright MCP to inspect test case rendering:
 
 The "All" story shows every test case side-by-side, making it easy to compare styled-components input with StyleX output.
 
-## Adapter System
+## Adapter API
 
-The codemod uses an adapter system for value transformations, allowing customization of how styled-components values are converted to StyleX.
+The codemod exposes an adapter-based API for customization (value resolution + dynamic interpolation handling).
 
 ### Programmatic Usage
 
-Create a script to run the transform with a custom adapter:
-
-```typescript
-// run-transform.ts
+```ts
 import { runTransform } from "styled-components-to-stylex-codemod";
-import type { Adapter } from "styled-components-to-stylex-codemod";
-
-const myAdapter: Adapter = {
-  transformValue({ path, defaultValue, valueType }) {
-    // Return StyleX-compatible value
-    // valueType is 'theme' | 'helper' | 'interpolation'
-    return `themeVars.${path.replace(/\./g, "_")}`;
-  },
-  getImports() {
-    return ["import { themeVars } from './theme.stylex';"];
-  },
-  getDeclarations() {
-    return [];
+import { defineAdapter } from "styled-components-to-stylex-codemod";
+
+const adapter = defineAdapter({
+  resolveValue(ctx) {
+    if (ctx.kind !== "theme") return null;
+    return {
+      expr: `themeVars.${ctx.path.replace(/\./g, "_")}`,
+      imports: ["import { themeVars } from './theme.stylex';"],
+    };
   },
-};
+});
 
 await runTransform({
   files: "src/**/*.tsx",
-  adapter: myAdapter,
+  adapter,
   dryRun: true, // Set to false to write changes
   parser: "tsx",
 });
 ```
 
-Run with: `npx tsx run-transform.ts`
-
-### Default Adapter
-
-The default adapter converts theme values to CSS custom properties:
-
-```typescript
-// Input: props.theme.colors.primary
-// Output: 'var(--colors-primary, #defaultValue)'
-```
-
 ## StyleX Requirements
 
 Output files must use valid StyleX syntax:

README.md

@@ -2,13 +2,241 @@
 
 Transform styled-components to StyleX.
 
-## Usage
+## Installation
 
 ```bash
-npx styled-components-to-stylex src/
-npx styled-components-to-stylex --dry src/  # dry run
+npm install styled-components-to-stylex-codemod
+# or
+pnpm add styled-components-to-stylex-codemod
+```
+
+## Usage
+
+Use `runTransform` to transform files matching a glob pattern:
+
+```ts
+import {
+  runTransform,
+  defineAdapter,
+} from "styled-components-to-stylex-codemod";
+
+const adapter = defineAdapter({
+  resolveValue(ctx) {
+    if (ctx.kind !== "theme") return null;
+    return {
+      expr: `tokens.${ctx.path.replace(/\./g, "_")}`,
+      imports: ["import { tokens } from './design-system.stylex';"],
+    };
+  },
+});
+
+const result = await runTransform({
+  files: "src/**/*.tsx",
+  adapter,
+});
+
+console.log(`Transformed ${result.transformed} files`);
+```
+
+### Options
+
+```ts
+interface RunTransformOptions {
+  /** Glob pattern(s) for files to transform */
+  files: string | string[];
+
+  /**
+   * Adapter for customizing the transform.
+   * Controls value resolution (and resolver-provided imports) and custom handlers.
+   */
+  adapter: Adapter;
+
+  /** Dry run - don't write changes to files (default: false) */
+  dryRun?: boolean;
+
+  /** Print transformed output to stdout (default: false) */
+  print?: boolean;
+
+  /** Parser to use (default: "tsx") */
+  parser?: "babel" | "babylon" | "flow" | "ts" | "tsx";
+}
+```
+
+### Dry Run
+
+Preview changes without modifying files:
+
+```ts
+await runTransform({
+  files: "src/**/*.tsx",
+  adapter,
+  dryRun: true,
+  print: true, // prints transformed output to stdout
+});
+```
+
+### Custom Adapter
+
+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 to handle dynamic interpolations inside template literals (`handlers`)
+
+#### `Adapter` interface (what you can customize)
+
+```ts
+export interface Adapter {
+  /**
+   * Resolve theme paths and CSS variables to StyleX-compatible values.
+   *
+   * Called by built-in handlers for patterns like:
+   *   ${(props) => props.theme.colors.primary}
+   *
+   * Also used for CSS `var(--...)` tokens inside static CSS values.
+   *
+   * Return an object containing:
+   * - `expr`: JS expression string to inline into output
+   * - `imports`: import statements required by `expr`
+   * - `dropDefinition?`: (CSS variables only) drop local `--x: ...` definitions when true
+   */
+  resolveValue: (
+    context:
+      | { kind: "theme"; path: string }
+      | {
+          kind: "cssVariable";
+          name: string;
+          fallback?: string;
+          definedValue?: string;
+        }
+  ) => { expr: string; imports: string[]; dropDefinition?: boolean } | null;
+
+  /**
+   * Custom handlers for dynamic expressions (template interpolations).
+   * These run BEFORE built-in handlers.
+   */
+  handlers?: Array<{
+    name: string;
+    handle: (node: unknown, ctx: unknown) => unknown | null;
+  }>;
+}
+```
+
+#### How handler ordering works
+
+When the codemod encounters an interpolation inside a styled template literal, it tries handlers in this order:
+
+- `adapter.handlers` (your custom handlers, in array order)
+- internal built-in handlers (always enabled), which cover common cases like:
+  - theme access (`props.theme...`)
+  - prop access (`props.foo`)
+  - conditionals (`props.foo ? "a" : "b"`, `props.foo && "color: red;"`)
+
+If no handler can 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)
+
+#### Create a custom adapter (theme path → tokens)
+
+```ts
+import {
+  runTransform,
+  defineAdapter,
+} from "styled-components-to-stylex-codemod";
+
+const adapter = defineAdapter({
+  resolveValue(ctx) {
+    if (ctx.kind === "theme") {
+      // Example: theme.colors.primary -> tokens.colors_primary
+      const varName = ctx.path.replace(/\./g, "_");
+      return {
+        expr: `tokens.${varName}`,
+        imports: ["import { tokens } from './design-system.stylex';"],
+      };
+    }
+    if (ctx.kind === "cssVariable") {
+      // Example: var(--spacing-sm) -> vars.spacingSm
+      if (ctx.name === "--spacing-sm") {
+        return {
+          expr: "vars.spacingSm",
+          imports: ['import { vars } from "./tokens.stylex";'],
+        };
+      }
+    }
+    return null;
+  },
+});
+
+await runTransform({
+  files: "src/**/*.tsx",
+  adapter,
+});
+```
+
+#### Create a custom handler (advanced)
+
+Most projects won’t need custom handlers. If you do, handlers let you convert an interpolation into:
+
+- a resolved value (inline into the generated style object)
+- a style function (generated helper + call site wiring)
+- split variants (turn a conditional into base + conditional style keys)
+
+If you want to implement handlers, start by importing the types:
+
+```ts
+import type {
+  DynamicHandler,
+  DynamicNode,
+  HandlerContext,
+} from "styled-components-to-stylex-codemod";
+```
+
+Then add handlers to your adapter:
+
+```ts
+import { defineAdapter } from "styled-components-to-stylex-codemod";
+
+export default defineAdapter({
+  handlers: [
+    {
+      name: "my-handler",
+      handle(node: any, ctx: any) {
+        // Return null to let the next handler try.
+        // Return a handler result object to tell the transform what to emit.
+        return null;
+      },
+    },
+  ],
+});
+```
+
+### Notes / Limitations
+
+- **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
+}
 ```
 
+## Public API
+
+This package intentionally exposes a small public API:
+
+- **`defineAdapter`**: define how theme paths / CSS variables resolve, plus custom handlers
+- **`runTransform`**: run the codemod over a set of files (uses jscodeshift under the hood)
+
+The underlying jscodeshift transform function is considered **internal** and is not a supported public entrypoint.
+
 ## License
 
 MIT