@wise/wds-codemods 1.0.0-experimental-1fe0062 → 1.0.0-experimental-4bcf6a2

package/README.md

@@ -3,17 +3,19 @@
 # WDS Codemods
 
 > WDS Codemods is a collection of codemod scripts designed to automate codebase transformations
-> specifically for the Wise Design System. This package leverages the power of [jscodeshift](https://github.com/facebook/jscodeshift)
-> to perform AST-based code modifications, enabling large-scale refactoring and updates
-> with minimal manual effort.
+> specifically for the Wise Design System. This package provides two types of transforms:
+> **[jscodeshift](https://github.com/facebook/jscodeshift)** and **[Claude AI](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk)**,
+> enabling large-scale refactoring and updates with minimal manual effort.
 
 ## Table of Contents
 
 - [The Repository](#-the-repository)
-- [Getting started](#-getting-started)
-- [Commands](#commands)
-- [Key Features](#-key-features)
+- [Getting Started](#-getting-started)
+- [CLI Options](#cli-options)
 - [Available Transforms](#-available-transforms)
+  - [Button Transform](./button.md)
+  - [ListItem Transform](./list-item.md)
+- [Key Features](#-key-features)
 - [Working with the Project Locally](#-working-with-the-project-locally)
 - [Writing Codemod Transforms](#-writing-codemod-transforms)
 - [Developer Documentation](#-developer-documentation)
@@ -26,12 +28,11 @@ The project provides a flexible CLI interface that allows you to run codemods ei
 via prompts or directly through command-line arguments. It includes intelligent package validation,
 monorepo support, and comprehensive reporting for manual review cases.
 
-## 🚀 Getting started
+## 🚀 Getting Started
 
-You can run codemods against your project in two ways: using interactive prompts or via CLI
-arguments. Here's how to do both:
+### Installation
 
-### To get started, install the package
+Install globally for convenience:
 
 ```bash
 # Using npm
@@ -44,7 +45,7 @@ pnpm add -g @wise/wds-codemods
 yarn global add @wise/wds-codemods
 ```
 
-Or, if you prefer, you can run it directly without installing globally:
+Or run directly without installing:
 
 ```bash
 # Using npx
@@ -57,53 +58,60 @@ pnpm dlx @wise/wds-codemods
 yarn dlx @wise/wds-codemods
 ```
 
-### Using Interactive Prompts
+### Running Codemods
 
-Simply run the codemod runner without any arguments:
+You can run codemods in two ways:
 
-```bash
-wds-codemods
-```
+#### Interactive Mode
 
-Or, if you prefer, you can run it directly using `npx` without installing globally:
+Run without arguments to get interactive prompts:
 
 ```bash
-npx wds-codemods
+wds-codemods
 ```
 
-You will be prompted to:
+You'll be prompted to:
 
-- Select a codemod transform from the available list.
-- Enter the target directory or file path to apply the codemod.
-- Choose whether to run in dry mode (no files are modified).
-- Choose whether to print the transformed source code to the console.
-- Configure monorepo detection (automatically detected in most cases).
+1. Select a transform (`button` or `list-item`)
+2. Enter target directory or file path
+3. Choose dry-run mode (preview without writing) (🔘 `button` only)
+4. Choose whether to print transformed output
+5. Configure monorepo detection (auto-detected in most cases)
+6. Answer transform-specific configuration questions (🔘 `button` only)
 
-### Using CLI Arguments
+#### Direct CLI Mode
 
-You can also run codemods directly by providing arguments:
+Run with arguments for automation:
 
 ```bash
-wds-codemods <transform> <targetPath> [--dry] [--print] [--monorepo]
+wds-codemods <transform> <targetPath> [options]
 ```
 
-Or using package runners:
+Example:
 
 ```bash
-npx @wise/wds-codemods <transform> <targetPath> [--dry] [--print] [--monorepo]
+wds-codemods button ./src --dry --print
 ```
 
-## Commands
+## CLI Options
+
+All codemods support these command-line options:
+
+| Option                  | Description                                                                                                        |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `--print`               | Print transformed source to console                                                                                |
+| `--ignore-pattern=GLOB` | Ignore files matching [glob pattern(s)](https://code.visualstudio.com/docs/editor/glob-patterns) (comma-separated) |
+| `--monorepo`            | Enable monorepo package checking across workspace folders                                                          |
+
+Only button transform supports the following options:
 
-- `npx wds-codemods <transform> <targetPath>`: Run a specific codemod transform on the target path.
-- `--dry` or `--dry-run`: Run in dry mode without writing changes to files. This is useful for previewing what changes would be made before actually applying them, allowing you to review the transformations safely.
-- `--print`: Print transformed source to the console.
-- `--ignore-pattern=GLOB`: Ignore files matching the provided [glob pattern(s)](https://code.visualstudio.com/docs/editor/glob-patterns). Multiple patterns can be comma separated.
-- `--gitignore`: Respect `.gitignore` files to ignore files/folders during codemod runs.
-- `--no-gitignore`: Do not respect `.gitignore` files.
-- `--monorepo`: Enable monorepo package checking across multiple workspace folders.
+| Option                | Description                              |
+| --------------------- | ---------------------------------------- |
+| `--dry` / `--dry-run` | Preview changes without writing to files |
+| `--gitignore`         | Respect `.gitignore` files               |
+| `--no-gitignore`      | Ignore `.gitignore` files                |
 
-Examples:
+### Common Examples
 
 ```bash
 # Basic transform with dry run
@@ -127,73 +135,83 @@ wds-codemods button ./src --print --dry
 
 ## 💻 Available Transforms
 
-### Button Transform (`button`)
+We currently provide two codemods for migrating Wise Design System components:
 
-Migrates `Button` and `ActionButton` components from `@transferwise/components` (v46.5.0+) to the new v2 API.
+### 🔘 [Button Transform (`button`)](./README-BUTTON.md)
 
-**Key Features:**
+Migrates `Button` and `ActionButton` components from `@transferwise/components` to the new v2 API.
 
-- **ActionButton Migration**: Converts deprecated `ActionButton` to `Button` with `v2` prop and default size
-- **Legacy Prop Transformations**:
-  - `priority`: Maps legacy values to new API (`primary`, `secondary`, `tertiary`, `secondary-neutral`)
-  - `size`: Converts to new size tokens (`sm`, `md`, `lg`, `xl`)
-  - `type` & `htmlType`: Handles legacy button types and HTML types appropriately
-  - `sentiment`: Manages sentiment values with special ControlType handling
-  - `text`: Converts ActionButton text prop to children
-- **Smart Enum Handling**:
-  - **Preserves** valid `ControlType` enums (`ControlType.NEGATIVE`, `ControlType.POSITIVE`, `ControlType.ACCENT`)
-  - Converts `Priority` and `Size` enums to string equivalents
-  - Reports deprecated `Type` enum values for manual review
-- **Icon Processing**: Automatically converts icon children to `addonStart`/`addonEnd` props
-- **Link Button Support**: Removes `as="a"` and manages `href` attributes properly
-- **Configurable Mapping**: Interactive prompts for accent/positive secondary button priority mapping
+- **Engine**: jscodeshift (AST-based transformations)
+- **Prerequisites**: `@transferwise/components >=46.5.0`
 
-**Configuration Options:**
+**What it does:**
 
-During transform execution, you'll be prompted to choose:
+- Converts `ActionButton` + `Button` → `Button` with v2 prop
+- Migrates legacy props (`priority`, `size`, `type`, `sentiment`)
+- Processes icon children into addon props
+- Handles link buttons and enum conversions
 
-- `accentSecondaryMapping`: How accent + secondary buttons are mapped (`secondary-neutral` recommended or `secondary`)
-- `positiveSecondaryMapping`: How positive + secondary buttons are mapped (`secondary-neutral` recommended or `secondary`)
+**[→ Full Button Transform Documentation](./README-BUTTON.md)**
 
-**Manual Review:**
+---
+
+### 📋 [ListItem Transform (`list-item`)](./README-LIST-ITEM.md)
+
+Migrates legacy `Option` and `Summary` components to `ListItem` component and subcomponents.
+
+- **Engine**: Claude AI (context-aware transformations)
+- **Prerequisites**: `@transferwise/components >=46.104.0` + LLM Gateway access
+
+**What it does:**
 
-The transform generates a `codemod-report.txt` file for cases requiring manual attention:
+- Converts `ActionOption`, `NavigationOption`, `Summary`, `SwitchOption`, `CheckboxOption`, `RadioOption`, `NavigationOptionList`
+- Maps to `ListItem` + subcomponents (`ListItem.Button`, `ListItem.Checkbox`, etc.)
+- Handles complex state requirements (modals, popovers)
+- Preserves HTML attributes and removes legacy props
 
-- Spread props (`{...props}`)
-- Dynamic expressions that cannot be statically analyzed
-- Unsupported prop values
-- Ambiguous icon children (conditional rendering, complex expressions)
+**[→ Full ListItem Transform Documentation](./README-LIST-ITEM.md)**
 
 ---
 
 ## 🔧 Key Features
 
-### Package Requirements Validation
+### Automatic Package Validation
 
-- **Automatic Dependency Checking**: Validates required packages and versions before running transforms
-- **Multi-Package Manager Support**: Works with npm, pnpm, and yarn
-- **Smart Detection**: Checks package.json, lockfiles, and node_modules directories
-- **Comprehensive Reporting**: Clear feedback when dependencies are missing or incompatible
+Before running any transform, the codemod automatically:
+
+- Validates required package versions (e.g., `@transferwise/components >=46.5.0`)
+- Checks `package.json`, lockfiles, and `node_modules`
+- Supports npm, pnpm, and yarn
+- Skips packages that don't meet prerequisites with clear reporting
 
 ### Monorepo Support
 
-- **Auto-Detection**: Automatically identifies monorepo structures (packages/, apps/, libs/, etc.)
-- **Cross-Package Validation**: Checks dependencies across all workspace packages
-- **Summary Reports**: Provides detailed breakdown of which packages have required dependencies
-- **Flexible Configuration**: Manual monorepo mode for custom structures
+- Auto-detects monorepo structures (`packages/`, `apps/`, `libs/`, etc.)
+- Validates dependencies across all workspace packages
+- Provides summary reports showing which packages are ready
+- Manual monorepo mode for custom structures
+
+### Manual Review Reporting
+
+**🔘 Button transform only:**
+
+- Generates `codemod-report.txt` for cases needing manual attention
+- Includes file paths, line numbers, and specific issue descriptions
+- Reports spread props, dynamic expressions, and unsupported values
+- Auto-removes old reports and provides fresh summaries
 
-### Manual Review Reports
+**📋 ListItem transform:**
 
-- **Automated Report Generation**: Creates `codemod-report.txt` for issues requiring manual attention
-- **Detailed Context**: Includes file paths, line numbers, and specific issue descriptions
-- **Smart Cleanup**: Automatically removes old reports and provides fresh summaries
-- **Issue Categories**: Organised reporting for spread props, dynamic expressions, and unsupported values
+- No report file generated
+- Claude handles complex cases inline
+- Use `--print` to review diffs before applying
 
-### Intelligent Processing
+### Smart Processing
 
-- **Selective Execution**: Only runs transforms on projects with compatible dependencies
-- **Performance Optimisation**: Caching and efficient directory traversal
-- **Robust Error Handling**: Graceful handling of edge cases and invalid configurations
+- Only runs on projects with compatible dependencies
+- Efficient directory traversal and file filtering
+- Graceful error handling for edge cases
+- Performance-optimized for large codebases
 
 ---