@wise/wds-codemods 1.0.0-experimental-7597060 → 1.0.0-experimental-1fe0062

package/README.md

@@ -3,19 +3,17 @@
 # WDS Codemods
 
 > WDS Codemods is a collection of codemod scripts designed to automate codebase transformations
-> 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.
+> 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.
 
 ## Table of Contents
 
 - [The Repository](#-the-repository)
-- [Getting Started](#-getting-started)
-- [CLI Options](#cli-options)
-- [Available Transforms](#-available-transforms)
-  - [Button Transform](./button.md)
-  - [ListItem Transform](./list-item.md)
+- [Getting started](#-getting-started)
+- [Commands](#commands)
 - [Key Features](#-key-features)
+- [Available Transforms](#-available-transforms)
 - [Working with the Project Locally](#-working-with-the-project-locally)
 - [Writing Codemod Transforms](#-writing-codemod-transforms)
 - [Developer Documentation](#-developer-documentation)
@@ -28,11 +26,12 @@ 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
 
-### Installation
+You can run codemods against your project in two ways: using interactive prompts or via CLI
+arguments. Here's how to do both:
 
-Install globally for convenience:
+### To get started, install the package
 
 ```bash
 # Using npm
@@ -45,7 +44,7 @@ pnpm add -g @wise/wds-codemods
 yarn global add @wise/wds-codemods
 ```
 
-Or run directly without installing:
+Or, if you prefer, you can run it directly without installing globally:
 
 ```bash
 # Using npx
@@ -58,60 +57,53 @@ pnpm dlx @wise/wds-codemods
 yarn dlx @wise/wds-codemods
 ```
 
-### Running Codemods
+### Using Interactive Prompts
 
-You can run codemods in two ways:
+Simply run the codemod runner without any arguments:
 
-#### Interactive Mode
+```bash
+wds-codemods
+```
 
-Run without arguments to get interactive prompts:
+Or, if you prefer, you can run it directly using `npx` without installing globally:
 
 ```bash
-wds-codemods
+npx wds-codemods
 ```
 
-You'll be prompted to:
+You will be prompted to:
 
-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)
+- 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).
 
-#### Direct CLI Mode
+### Using CLI Arguments
 
-Run with arguments for automation:
+You can also run codemods directly by providing arguments:
 
 ```bash
-wds-codemods <transform> <targetPath> [options]
+wds-codemods <transform> <targetPath> [--dry] [--print] [--monorepo]
 ```
 
-Example:
+Or using package runners:
 
 ```bash
-wds-codemods button ./src --dry --print
+npx @wise/wds-codemods <transform> <targetPath> [--dry] [--print] [--monorepo]
 ```
 
-## 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:
+## Commands
 
-| Option                | Description                              |
-| --------------------- | ---------------------------------------- |
-| `--dry` / `--dry-run` | Preview changes without writing to files |
-| `--gitignore`         | Respect `.gitignore` files               |
-| `--no-gitignore`      | Ignore `.gitignore` files                |
+- `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.
 
-### Common Examples
+Examples:
 
 ```bash
 # Basic transform with dry run
@@ -135,83 +127,73 @@ wds-codemods button ./src --print --dry
 
 ## 💻 Available Transforms
 
-We currently provide two codemods for migrating Wise Design System components:
+### Button Transform (`button`)
 
-### 🔘 [Button Transform (`button`)](./README-BUTTON.md)
+Migrates `Button` and `ActionButton` components from `@transferwise/components` (v46.5.0+) to the new v2 API.
 
-Migrates `Button` and `ActionButton` components from `@transferwise/components` to the new v2 API.
+**Key Features:**
 
-- **Engine**: jscodeshift (AST-based transformations)
-- **Prerequisites**: `@transferwise/components >=46.5.0`
+- **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
 
-**What it does:**
+**Configuration Options:**
 
-- 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
+During transform execution, you'll be prompted to choose:
 
-**[→ Full Button Transform Documentation](./README-BUTTON.md)**
+- `accentSecondaryMapping`: How accent + secondary buttons are mapped (`secondary-neutral` recommended or `secondary`)
+- `positiveSecondaryMapping`: How positive + secondary buttons are mapped (`secondary-neutral` recommended or `secondary`)
 
----
-
-### 📋 [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:**
+**Manual Review:**
 
-- Converts `ActionOption`, `NavigationOption`, `Summary`, `SwitchOption`, `CheckboxOption`, `RadioOption`, `DefinitionList`
-- Maps to `ListItem` + subcomponents (`ListItem.Button`, `ListItem.Checkbox`, etc.)
-- Handles complex state requirements (modals, popovers)
-- Preserves HTML attributes and removes legacy props
+The transform generates a `codemod-report.txt` file for cases requiring manual attention:
 
-**[→ Full ListItem Transform Documentation](./README-LIST-ITEM.md)**
+- Spread props (`{...props}`)
+- Dynamic expressions that cannot be statically analyzed
+- Unsupported prop values
+- Ambiguous icon children (conditional rendering, complex expressions)
 
 ---
 
 ## 🔧 Key Features
 
-### Automatic Package Validation
+### Package Requirements Validation
 
-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
+- **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
 
 ### Monorepo Support
 
-- 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
+- **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
 
-**📋 ListItem transform:**
+### Manual Review Reports
 
-- No report file generated
-- Claude handles complex cases inline
-- Use `--print` to review diffs before applying
+- **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
 
-### Smart Processing
+### Intelligent Processing
 
-- Only runs on projects with compatible dependencies
-- Efficient directory traversal and file filtering
-- Graceful error handling for edge cases
-- Performance-optimized for large codebases
+- **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
 
 ---